@cardstack/boxel-cli 0.2.0-unstable.425 → 0.2.0-unstable.448

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardstack/boxel-cli",
-  "version": "0.2.0-unstable.425",
+  "version": "0.2.0-unstable.448",
   "license": "MIT",
   "description": "CLI tools for Boxel workspace management",
   "main": "./dist/index.js",
@@ -53,8 +53,8 @@
     "typescript": "~5.9.3",
     "vite": "^6.3.2",
     "vitest": "^2.1.9",
-    "@cardstack/postgres": "0.0.0",
     "@cardstack/local-types": "0.0.0",
+    "@cardstack/postgres": "0.0.0",
     "@cardstack/runtime-common": "1.0.0"
   },
   "publishConfig": {

package/src/commands/file/read.ts

@@ -6,14 +6,21 @@ import {
 } from '../../lib/profile-manager';
 import { ensureTrailingSlash } from '@cardstack/runtime-common/paths';
 import { SupportedMimeType } from '@cardstack/runtime-common/supported-mime-type';
+import { isBinaryFilename } from '@cardstack/runtime-common/infer-content-type';
 import { FG_RED, DIM, RESET } from '../../lib/colors';
 import { cliLog } from '../../lib/cli-log';
 
 export interface ReadResult {
   ok: boolean;
   status?: number;
-  /** Raw text content of the file. */
+  /** Raw text content of the file. Populated for non-binary paths. */
   content?: string;
+  /**
+   * Raw bytes. Populated when the requested path is a binary filename
+   * (PNG, PDF, font, etc.) — see `isBinaryFilename`. Mutually exclusive
+   * with `content`.
+   */
+  bytes?: Uint8Array;
   error?: string;
 }
 
@@ -27,8 +34,10 @@ interface ReadCliOptions {
 }
 
 /**
- * Read a file from a realm. Always returns the raw text content.
- * Callers should parse the content themselves if needed (e.g. JSON).
+ * Read a file from a realm. Returns raw text in `content` for text files;
+ * returns raw bytes in `bytes` for binary files (PNG / PDF / font / etc.,
+ * per `isBinaryFilename`). Callers should parse the content themselves
+ * if needed (e.g. JSON).
  *
  * Uses the per-realm JWT via `ProfileManager.authedRealmFetch`.
  */
@@ -70,6 +79,11 @@ export async function read(
     };
   }
 
+  if (isBinaryFilename(path)) {
+    let bytes = new Uint8Array(await response.arrayBuffer());
+    return { ok: true, status: response.status, bytes };
+  }
+
   let text = await response.text();
   return { ok: true, status: response.status, content: text };
 }
@@ -96,9 +110,30 @@ export function registerReadCommand(parent: Command): void {
       }
 
       if (opts.json) {
-        cliLog.output(JSON.stringify(result, null, 2));
+        let serializable: Record<string, unknown> = {
+          ok: result.ok,
+          status: result.status,
+          error: result.error,
+        };
+        if (result.content !== undefined) {
+          serializable.content = result.content;
+        }
+        if (result.bytes !== undefined) {
+          // Buffer.from(typedArray) shares memory, then toString('base64')
+          // copies into a base64 string — fine for the JSON output path.
+          serializable.bytesBase64 = Buffer.from(
+            result.bytes.buffer,
+            result.bytes.byteOffset,
+            result.bytes.byteLength,
+          ).toString('base64');
+        }
+        cliLog.output(JSON.stringify(serializable, null, 2));
       } else if (result.ok) {
-        cliLog.output(result.content ?? '');
+        if (result.bytes !== undefined) {
+          process.stdout.write(result.bytes);
+        } else {
+          cliLog.output(result.content ?? '');
+        }
       } else {
         console.error(
           `${DIM}Status:${RESET} ${result.status ?? '(no status)'}`,

package/src/commands/file/write.ts

@@ -7,6 +7,7 @@ import {
 } from '../../lib/profile-manager';
 import { ensureTrailingSlash } from '@cardstack/runtime-common/paths';
 import { SupportedMimeType } from '@cardstack/runtime-common/supported-mime-type';
+import { isBinaryFilename } from '@cardstack/runtime-common/infer-content-type';
 import { FG_GREEN, FG_RED, DIM, RESET } from '../../lib/colors';
 import { cliLog } from '../../lib/cli-log';
 
@@ -26,15 +27,19 @@ interface WriteCliOptions {
 }
 
 /**
- * Write a file to a realm. Content is sent as-is with card+source MIME type.
- * Path should include the file extension.
+ * Write a file to a realm. Path should include the file extension.
+ *
+ * String content is sent with the card+source MIME type (the text path
+ * .gts / .json / .md / etc. always took). Binary content (a `Uint8Array`,
+ * including the `Buffer` subclass) is sent with `application/octet-stream`,
+ * which the realm-server routes to `upsertBinaryFile` and writes verbatim.
  *
  * Uses the per-realm JWT via `ProfileManager.authedRealmFetch`.
  */
 export async function write(
   realmUrl: string,
   path: string,
-  content: string,
+  content: string | Uint8Array,
   options?: WriteCommandOptions,
 ): Promise<WriteResult> {
   let pm = options?.profileManager ?? getProfileManager();
@@ -47,15 +52,38 @@ export async function write(
   }
 
   let url = new URL(path, ensureTrailingSlash(realmUrl)).href;
+  let isBinary = typeof content !== 'string';
+
+  // Defense-in-depth for programmatic callers (BoxelClient.write, tests).
+  // The CLI wrapper has an earlier guard against `--file image.png` →
+  // `notes.md` style misuse, but the library function is also reachable
+  // without going through that branch. Reject the mismatch here so raw
+  // bytes never land at a text extension (corrupt-on-read) and a UTF-8
+  // string never lands at a binary extension (corrupt-on-write).
+  let pathIsBinary = isBinaryFilename(path);
+  if (pathIsBinary !== isBinary) {
+    return {
+      ok: false,
+      error:
+        `Path ${path} is ${pathIsBinary ? 'binary' : 'text'} by extension ` +
+        `but content is ${isBinary ? 'bytes' : 'a string'}. ` +
+        `Refusing to write to avoid silent corruption.`,
+    };
+  }
 
   try {
     let response = await pm.authedRealmFetch(url, {
       method: 'POST',
-      headers: {
-        Accept: SupportedMimeType.CardSource,
-        'Content-Type': SupportedMimeType.CardSource,
-      },
-      body: content,
+      headers: isBinary
+        ? { 'Content-Type': SupportedMimeType.OctetStream }
+        : {
+            Accept: SupportedMimeType.CardSource,
+            'Content-Type': SupportedMimeType.CardSource,
+          },
+      // Both branches of `content: string | Uint8Array` are valid
+      // BodyInit values, but TS narrows them as a union that doesn't
+      // unify against the fetch signature without a hint.
+      body: content as BodyInit,
     });
 
     if (!response.ok) {
@@ -103,10 +131,30 @@ export function registerWriteCommand(parent: Command): void {
     )
     .option('--json', 'Output raw JSON response')
     .action(async (filePath: string, opts: WriteCliOptions) => {
-      let content: string;
+      let content: string | Uint8Array;
       if (opts.file) {
+        // Refuse a source/destination binary-classification mismatch
+        // (e.g., `write notes.md --file image.png`) — otherwise raw
+        // bytes would land at a text extension and corrupt-on-read.
+        const srcIsBinary = isBinaryFilename(opts.file);
+        const dstIsBinary = isBinaryFilename(filePath);
+        if (srcIsBinary !== dstIsBinary) {
+          stderr(
+            `${FG_RED}Error:${RESET} source file ${opts.file} is ${
+              srcIsBinary ? 'binary' : 'text'
+            } but destination path ${filePath} is ${
+              dstIsBinary ? 'binary' : 'text'
+            }. Refusing to write to avoid silent corruption — rename the destination to match.`,
+          );
+          process.exit(1);
+        }
         try {
-          content = readFileSync(opts.file, 'utf-8');
+          // Binary source files are read as raw bytes so write() can
+          // hand them to the realm unchanged; forcing utf-8 would
+          // corrupt PNG / PDF / font / etc. payloads silently.
+          content = srcIsBinary
+            ? readFileSync(opts.file)
+            : readFileSync(opts.file, 'utf-8');
         } catch (err) {
           stderr(
             `${FG_RED}Error:${RESET} Could not read file: ${err instanceof Error ? err.message : String(err)}`,

package/src/commands/profile.ts

@@ -80,7 +80,7 @@ function validateUrl(input: string, label: string): string {
 
 // Matches scripts/env-slug.sh: lowercase, "/" -> "-", strip chars outside
 // [a-z0-9-], collapse runs of "-", trim leading/trailing "-".
-function computeEnvSlug(name: string): string {
+export function computeEnvSlug(name: string): string {
   return name
     .toLowerCase()
     .replace(/\//g, '-')
@@ -91,7 +91,7 @@ function computeEnvSlug(name: string): string {
 
 // Derive URLs from BOXEL_ENVIRONMENT using the same ".${slug}.localhost"
 // pattern that mise-tasks/lib/env-vars.sh produces for env-mode local dev.
-function resolveBoxelEnvironment(): EnvironmentDefaults | null {
+export function resolveBoxelEnvironment(): EnvironmentDefaults | null {
   const raw = process.env.BOXEL_ENVIRONMENT;
   if (!raw || !raw.trim()) return null;
   const slug = computeEnvSlug(raw);
@@ -458,14 +458,28 @@ async function addProfileNonInteractive(
     process.exit(1);
   }
 
-  if (manager.getProfile(matrixId)) {
-    console.log(
-      `${FG_YELLOW}Profile ${matrixId} already exists. Updating password.${RESET}`,
+  const isUpdate = Boolean(manager.getProfile(matrixId));
+
+  // addProfile performs a real matrixLogin and persists the resulting
+  // access token (the password never lands on disk). It also handles the
+  // create-vs-reauth split uniformly: re-running it on an existing profile
+  // refreshes the stored token while preserving cached realm tokens.
+  try {
+    await manager.addProfile(
+      matrixId,
+      password,
+      displayName,
+      matrixUrl,
+      realmServerUrl,
     );
-    await manager.updatePassword(matrixId, password);
-    if (displayName) {
-      manager.updateDisplayName(matrixId, displayName);
-    }
+  } catch (err) {
+    console.error(
+      `${FG_RED}Error:${RESET} ${err instanceof Error ? err.message : String(err)}`,
+    );
+    process.exit(1);
+  }
+
+  if (isUpdate) {
     if (matrixUrl || realmServerUrl) {
       const urlsChanged = manager.updateUrls(matrixId, {
         matrixUrl,
@@ -483,20 +497,6 @@ async function addProfileNonInteractive(
     return;
   }
 
-  try {
-    await manager.addProfile(
-      matrixId,
-      password,
-      displayName,
-      matrixUrl,
-      realmServerUrl,
-    );
-  } catch (err) {
-    console.error(
-      `${FG_RED}Error:${RESET} ${err instanceof Error ? err.message : String(err)}`,
-    );
-    process.exit(1);
-  }
   console.log(
     `${FG_GREEN}\u2713${RESET} Profile created: ${formatProfileBadge(matrixId)}`,
   );
@@ -538,7 +538,7 @@ async function migrateFromEnv(manager: ProfileManager): Promise<void> {
       );
     } else {
       console.log(
-        `${FG_YELLOW}Profile ${formatProfileBadge(result.profileId)} already exists.${RESET} Password has been updated if it changed.`,
+        `${FG_GREEN}\u2713${RESET} Refreshed profile: ${formatProfileBadge(result.profileId)}`,
       );
       console.log(
         `\n${DIM}Use 'boxel profile add -u ${result.profileId} -p <password>' to update other fields.${RESET}`,

package/src/commands/realm/push.ts

@@ -200,6 +200,23 @@ class RealmPusher extends RealmSyncBase {
 
       const result = await this.uploadFilesAtomic(filesToUpload, addPaths);
 
+      // Record every file the server actually wrote before surfacing
+      // errors. uploadFilesAtomic can return both `succeeded` and
+      // `error` when the atomic text batch lands but a per-file
+      // binary POST fails — dropping the manifest update in that
+      // case would force a re-add on the next push (409 cascade).
+      if (result.succeeded.length > 0) {
+        const uploaded = await Promise.all(
+          result.succeeded.map(async (rel) => ({
+            rel,
+            hash: await computeFileHash(filesToUpload.get(rel)!),
+          })),
+        );
+        for (const { rel, hash } of uploaded) {
+          newManifest.files[rel] = hash;
+        }
+      }
+
       if (result.error) {
         uploadFailed = true;
         this.hasError = true;
@@ -215,16 +232,6 @@ class RealmPusher extends RealmSyncBase {
           }
           console.error(`  ${hint}`);
         }
-      } else if (result.succeeded.length > 0) {
-        const uploaded = await Promise.all(
-          result.succeeded.map(async (rel) => ({
-            rel,
-            hash: await computeFileHash(filesToUpload.get(rel)!),
-          })),
-        );
-        for (const { rel, hash } of uploaded) {
-          newManifest.files[rel] = hash;
-        }
       }
     }
 
@@ -270,7 +277,11 @@ class RealmPusher extends RealmSyncBase {
       }
     }
 
-    if (!this.options.dryRun && !uploadFailed && filesToUpload.size > 0) {
+    // Refresh mtimes and save the manifest even on partial failure —
+    // newManifest.files only contains files the server actually wrote
+    // (unchanged carry-overs + succeeded uploads), so persisting it
+    // is always safe and avoids re-uploading text files that landed.
+    if (!this.options.dryRun && filesToUpload.size > 0) {
       try {
         const freshMtimes = await this.getRemoteMtimes();
         for (const rel of Object.keys(newManifest.files)) {
@@ -291,7 +302,7 @@ class RealmPusher extends RealmSyncBase {
       delete newManifest.remoteMtimes;
     }
 
-    if (!this.options.dryRun && !uploadFailed) {
+    if (!this.options.dryRun) {
       await saveManifest(this.options.localDir, newManifest);
     }
 

package/src/commands/realm/sync.ts

@@ -314,14 +314,16 @@ class RealmSyncer extends RealmSyncBase {
       }
 
       const result = await this.uploadFilesAtomic(filesToUpload, addPaths);
+      // Record every file the server actually wrote, even when other
+      // files in the same batch failed — see push.ts for the symmetric
+      // reasoning.
+      this.pushedFiles.push(...result.succeeded);
       if (result.error) {
         this.hasError = true;
         console.error(result.error.message);
         for (const entry of result.error.perFile) {
           console.error(`  ${entry.path}: ${entry.title}`);
         }
-      } else {
-        this.pushedFiles.push(...result.succeeded);
       }
     }
 
@@ -371,8 +373,12 @@ class RealmSyncer extends RealmSyncBase {
       );
     }
 
-    // Phase 6: Update manifest
-    if (!this.options.dryRun && !this.hasError) {
+    // Phase 6: Update manifest. Persist even on partial failure — we
+    // only record hashes for files the server actually wrote
+    // (pushedFiles + pulledFiles), so the manifest stays consistent
+    // with the realm and the next sync won't re-attempt successful
+    // files.
+    if (!this.options.dryRun) {
       // Build updated hashes from prior manifest + current local files + executed ops.
       // Start with the previous manifest so that files deleted locally but not
       // propagated (no --delete) retain their entries and aren't re-pulled next sync.

package/src/lib/auth.ts

@@ -7,6 +7,17 @@ export interface MatrixAuth {
 
 export type RealmTokens = Record<string, string>;
 
+// Thrown when Matrix rejects an access token (401/403). Callers can catch
+// this specifically to drive interactive re-auth without parsing messages.
+export class MatrixAuthError extends Error {
+  status: number;
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = 'MatrixAuthError';
+    this.status = status;
+  }
+}
+
 interface MatrixLoginResponse {
   access_token: string;
   device_id: string;
@@ -69,6 +80,12 @@ async function getOpenIdToken(
 
   if (!response.ok) {
     let text = await response.text();
+    if (response.status === 401 || response.status === 403) {
+      throw new MatrixAuthError(
+        response.status,
+        `OpenID token request failed: ${response.status} ${text}`,
+      );
+    }
     throw new Error(`OpenID token request failed: ${response.status} ${text}`);
   }
 
@@ -138,17 +155,30 @@ function userRealmsAccountDataUrl(matrixAuth: MatrixAuth): string {
 export async function getUserRealmsFromMatrixAccountData(
   matrixAuth: MatrixAuth,
 ): Promise<string[]> {
+  let response: Response;
   try {
-    let response = await fetch(userRealmsAccountDataUrl(matrixAuth), {
+    response = await fetch(userRealmsAccountDataUrl(matrixAuth), {
       headers: { Authorization: `Bearer ${matrixAuth.accessToken}` },
     });
-    if (!response.ok) {
-      return [];
-    }
+  } catch {
+    // Network unreachable / DNS / similar — treat as empty (best-effort).
+    return [];
+  }
+  if (response.status === 401 || response.status === 403) {
+    let text = await response.text();
+    throw new MatrixAuthError(
+      response.status,
+      `Matrix account_data fetch failed: ${response.status} ${text}`,
+    );
+  }
+  if (!response.ok) {
+    // 404 just means the event has never been set — return empty list.
+    return [];
+  }
+  try {
     let data = (await response.json()) as { realms?: string[] };
     return Array.isArray(data.realms) ? [...data.realms] : [];
   } catch {
-    // Best-effort — treat unreachable account data as an empty list
     return [];
   }
 }
@@ -171,6 +201,12 @@ export async function addRealmToMatrixAccountData(
     });
     if (!putResponse.ok) {
       let text = await putResponse.text();
+      if (putResponse.status === 401 || putResponse.status === 403) {
+        throw new MatrixAuthError(
+          putResponse.status,
+          `Failed to update Matrix account data: ${putResponse.status} ${text}`,
+        );
+      }
       throw new Error(
         `Failed to update Matrix account data: ${putResponse.status} ${text}`,
       );
@@ -205,6 +241,12 @@ export async function removeRealmFromMatrixAccountData(
   });
   if (!putResponse.ok) {
     let text = await putResponse.text();
+    if (putResponse.status === 401 || putResponse.status === 403) {
+      throw new MatrixAuthError(
+        putResponse.status,
+        `Failed to update Matrix account data: ${putResponse.status} ${text}`,
+      );
+    }
     throw new Error(
       `Failed to update Matrix account data: ${putResponse.status} ${text}`,
     );