Address PR feedback: split authedFetch, fix token refresh and delete-only checkpoints

FadhlanR · claude · FadhlanR · commit b407dcf606aa · 2026-04-14T15:48:02.000+07:00
- Split authedFetch into authedRealmFetch and authedRealmServerFetch for clarity
- Fix P1: handle expired server token during realm-auth prefetch gracefully
  so the 401 retry path still works
- Fix P2: persist checkpoint after delete-only pulls (not just downloads)

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/packages/boxel-cli/src/commands/realm/create.ts b/packages/boxel-cli/src/commands/realm/create.ts
@@ -68,13 +68,16 @@ export async function createRealm(
 
   let response: Response;
   try {
-    response = await pm.authedFetch(`${realmServerUrl}/_create-realm`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/vnd.api+json' },
-      body: JSON.stringify({
-        data: { type: 'realm', attributes },
-      }),
-    });
+    response = await pm.authedRealmServerFetch(
+      `${realmServerUrl}/_create-realm`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/vnd.api+json' },
+        body: JSON.stringify({
+          data: { type: 'realm', attributes },
+        }),
+      },
+    );
   } catch (e: unknown) {
     console.error(`Error: failed to connect to realm server`);
     console.error(e instanceof Error ? e.message : String(e));
diff --git a/packages/boxel-cli/src/commands/realm/pull.ts b/packages/boxel-cli/src/commands/realm/pull.ts
@@ -71,6 +71,7 @@ class RealmPuller extends RealmSyncBase {
       }
     }
 
+    const deletedFiles: string[] = [];
     if (this.pullOptions.deleteLocal) {
       const filesToDelete = new Set(localFiles.keys());
       for (const relativePath of remoteFiles.keys()) {
@@ -105,6 +106,7 @@ class RealmPuller extends RealmSyncBase {
             const localPath = localFiles.get(relativePath);
             if (localPath) {
               await this.deleteLocalFile(localPath);
+              deletedFiles.push(relativePath);
               console.log(`  Deleted: ${relativePath}`);
             }
           } catch (error) {
@@ -121,6 +123,11 @@ class RealmPuller extends RealmSyncBase {
         file: f,
         status: 'modified' as const,
       }));
+      if (deletedFiles.length > 0) {
+        for (const f of deletedFiles) {
+          pullChanges.push({ file: f, status: 'deleted' as const });
+        }
+      }
       const checkpoint = checkpointManager.createCheckpoint(
         'remote',
         pullChanges,
@@ -131,6 +138,22 @@ class RealmPuller extends RealmSyncBase {
           `\nCheckpoint created: ${checkpoint.shortHash} ${tag} ${checkpoint.message}`,
         );
       }
+    } else if (!this.options.dryRun && deletedFiles.length > 0) {
+      const checkpointManager = new CheckpointManager(this.options.localDir);
+      const deleteChanges: CheckpointChange[] = deletedFiles.map((f) => ({
+        file: f,
+        status: 'deleted' as const,
+      }));
+      const checkpoint = checkpointManager.createCheckpoint(
+        'remote',
+        deleteChanges,
+      );
+      if (checkpoint) {
+        const tag = checkpoint.isMajor ? '[MAJOR]' : '[minor]';
+        console.log(
+          `\nCheckpoint created: ${checkpoint.shortHash} ${tag} ${checkpoint.message}`,
+        );
+      }
     }
 
     console.log('Pull completed');
diff --git a/packages/boxel-cli/src/lib/profile-manager.ts b/packages/boxel-cli/src/lib/profile-manager.ts
@@ -377,35 +377,26 @@ export class ProfileManager {
     }
   }
 
-  private async resolveTokenForUrl(url: string): Promise<string> {
-    // Check if URL matches a cached realm token
+  private async getRealmTokenForUrl(url: string): Promise<string | undefined> {
     let realmToken = this.findRealmTokenForUrl(url);
     if (realmToken) {
       return realmToken;
     }
 
-    // Fetch all realm tokens and try again
-    await this.fetchAndStoreAllRealmTokens();
-    realmToken = this.findRealmTokenForUrl(url);
-    if (realmToken) {
-      return realmToken;
+    try {
+      await this.fetchAndStoreAllRealmTokens();
+    } catch {
+      // Token prefetch failed (e.g. expired server token) — caller will handle 401 retry
+      return undefined;
     }
-
-    // Fall back to server token for server-level endpoints
-    return this.getOrRefreshServerToken();
+    return this.findRealmTokenForUrl(url);
   }
 
-  async authedFetch(
+  private buildHeaders(
     input: string | URL | Request,
-    init?: RequestInit,
-  ): Promise<Response> {
-    let url =
-      input instanceof Request
-        ? input.url
-        : input instanceof URL
-          ? input.href
-          : input;
-    let token = await this.resolveTokenForUrl(url);
+    init: RequestInit | undefined,
+    token: string,
+  ): Headers {
     let baseHeaders =
       input instanceof Request ? new Headers(input.headers) : new Headers();
     let initHeaders = new Headers(init?.headers);
@@ -415,20 +406,68 @@ export class ProfileManager {
     if (!baseHeaders.has('Authorization')) {
       baseHeaders.set('Authorization', token);
     }
+    return baseHeaders;
+  }
 
-    let response = await fetch(input, { ...init, headers: baseHeaders });
+  async authedRealmFetch(
+    input: string | URL | Request,
+    init?: RequestInit,
+  ): Promise<Response> {
+    let url =
+      input instanceof Request
+        ? input.url
+        : input instanceof URL
+          ? input.href
+          : input;
+
+    let token = await this.getRealmTokenForUrl(url);
+    if (!token) {
+      throw new Error(
+        `No realm token available for ${url}. The server token may have expired or the realm is not accessible.`,
+      );
+    }
+    let headers = this.buildHeaders(input, init, token);
+    let response = await fetch(input, { ...init, headers });
 
     if (response.status === 401) {
-      // Clear cached tokens and retry
       let active = this.getActiveProfile();
       if (active) {
         active.profile.realmTokens = {};
         active.profile.realmServerToken = undefined;
         this.saveConfig();
       }
-      token = await this.resolveTokenForUrl(url);
-      baseHeaders.set('Authorization', token);
-      response = await fetch(input, { ...init, headers: baseHeaders });
+      try {
+        await this.fetchAndStoreAllRealmTokens();
+      } catch {
+        throw new Error(
+          `Failed to refresh realm token for ${url}. The server token may have expired.`,
+        );
+      }
+      token = this.findRealmTokenForUrl(url);
+      if (!token) {
+        throw new Error(
+          `No realm token available for ${url} after refresh. The realm may not be accessible.`,
+        );
+      }
+      headers = this.buildHeaders(input, init, token);
+      response = await fetch(input, { ...init, headers });
+    }
+
+    return response;
+  }
+
+  async authedRealmServerFetch(
+    input: string | URL | Request,
+    init?: RequestInit,
+  ): Promise<Response> {
+    let token = await this.getOrRefreshServerToken();
+    let headers = this.buildHeaders(input, init, token);
+    let response = await fetch(input, { ...init, headers });
+
+    if (response.status === 401) {
+      token = await this.refreshServerToken();
+      headers = this.buildHeaders(input, init, token);
+      response = await fetch(input, { ...init, headers });
     }
 
     return response;
diff --git a/packages/boxel-cli/src/lib/realm-sync-base.ts b/packages/boxel-cli/src/lib/realm-sync-base.ts
@@ -81,7 +81,7 @@ export abstract class RealmSyncBase {
     try {
       const url = this.buildDirectoryUrl(dir);
 
-      const response = await this.profileManager.authedFetch(url, {
+      const response = await this.profileManager.authedRealmFetch(url, {
         headers: {
           Accept: 'application/vnd.api+json',
         },
@@ -149,7 +149,7 @@ export abstract class RealmSyncBase {
     try {
       const url = `${this.normalizedRealmUrl}_mtimes`;
 
-      const response = await this.profileManager.authedFetch(url, {
+      const response = await this.profileManager.authedRealmFetch(url, {
         headers: {
           Accept: SupportedMimeType.Mtimes,
         },
@@ -297,7 +297,7 @@ export abstract class RealmSyncBase {
     const content = fs.readFileSync(localPath, 'utf8');
     const url = this.buildFileUrl(relativePath);
 
-    const response = await this.profileManager.authedFetch(url, {
+    const response = await this.profileManager.authedRealmFetch(url, {
       method: 'POST',
       headers: {
         'Content-Type': 'text/plain;charset=UTF-8',
@@ -328,7 +328,7 @@ export abstract class RealmSyncBase {
 
     const url = this.buildFileUrl(relativePath);
 
-    const response = await this.profileManager.authedFetch(url, {
+    const response = await this.profileManager.authedRealmFetch(url, {
       headers: {
         Accept: SupportedMimeType.CardSource,
       },
@@ -366,7 +366,7 @@ export abstract class RealmSyncBase {
 
     const url = this.buildFileUrl(relativePath);
 
-    const response = await this.profileManager.authedFetch(url, {
+    const response = await this.profileManager.authedRealmFetch(url, {
       method: 'DELETE',
       headers: {
         Accept: SupportedMimeType.CardSource,
