@cardstack/boxel-cli 0.3.0-unstable.13 → 0.3.0-unstable.87

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardstack/boxel-cli",
-  "version": "0.3.0-unstable.13",
+  "version": "0.3.0-unstable.87",
   "license": "MIT",
   "description": "CLI tools for Boxel workspace management",
   "main": "./dist/index.js",
@@ -58,8 +58,8 @@
     "ts-node": "^10.9.1",
     "vite": "^6.3.2",
     "vitest": "^2.1.9",
-    "@cardstack/local-types": "0.0.0",
     "@cardstack/postgres": "0.0.0",
+    "@cardstack/local-types": "0.0.0",
     "@cardstack/runtime-common": "1.0.0"
   },
   "publishConfig": {

package/src/commands/realm/publish.ts

@@ -7,6 +7,7 @@ import {
 } from '../../lib/profile-manager';
 import { unpublishRealm } from './unpublish';
 import { FG_CYAN, FG_GREEN, FG_RED, RESET } from '../../lib/colors';
+import { describeFetchError } from '../../lib/describe-fetch-error';
 
 const DEFAULT_TIMEOUT_MS = 300_000;
 const READINESS_POLL_INTERVAL_MS = 1000;
@@ -193,7 +194,7 @@ async function waitForPublishedRealmReady(
       }
       lastError = `HTTP ${response.status}`;
     } catch (error) {
-      lastError = error instanceof Error ? error.message : String(error);
+      lastError = describeFetchError(error);
     }
     let remaining = timeoutMs - (Date.now() - startedAt);
     if (remaining <= 0) break;
@@ -276,6 +277,14 @@ export function registerPublishCommand(realm: Command): void {
           console.error(
             `${FG_RED}Error:${RESET} ${err instanceof Error ? err.message : String(err)}`,
           );
+          // Node's fetch surfaces the actual transport error (ECONNRESET,
+          // TLS failure, undici socket error, etc.) on `error.cause`. Print
+          // it so opaque "fetch failed" messages don't strand the caller.
+          // `!= null` rather than a truthy check so we don't drop
+          // falsy-but-defined causes (`''`, `0`, `false`, `NaN`).
+          if (err instanceof Error && err.cause != null) {
+            console.error(`${FG_RED}Caused by:${RESET}`, err.cause);
+          }
           process.exit(1);
         }
       },

package/src/commands/realm/sync.ts

@@ -51,6 +51,11 @@ class RealmSyncer extends RealmSyncBase {
   remoteDeletedFiles: string[] = [];
   localDeletedFiles: string[] = [];
   skippedConflicts: string[] = [];
+  // Top-level message from a failed /_atomic batch (e.g. "Atomic upload
+  // failed: 500 Internal Server Error"). Surfaced in `SyncResult.error`
+  // so callers don't have to scrape stderr to learn why the batch
+  // failed.
+  uploadFatalMessage?: string;
 
   constructor(
     private syncOptions: BiSyncOptions,
@@ -320,7 +325,24 @@ class RealmSyncer extends RealmSyncBase {
       this.pushedFiles.push(...result.succeeded);
       if (result.error) {
         this.hasError = true;
-        console.error(result.error.message);
+        // Fold the per-file titles into the surfaced message so
+        // SyncResult.error carries the server's JSON:API error
+        // payload (e.g. "Write Error"), not just the HTTP status
+        // line. Distinct titles only — repeated identical titles
+        // (the common case for a top-level write failure) would
+        // otherwise produce noisy duplicates. The summary line is
+        // re-echoed by registerSyncCommand at the end of the run
+        // via `Error: ${result.error}`, so we no longer also emit
+        // the standalone status line inline — that would duplicate
+        // it in CLI output. The per-file loop stays because it
+        // carries path-level detail the summary aggregates away.
+        let titles = Array.from(
+          new Set(result.error.perFile.map((e) => e.title)),
+        );
+        this.uploadFatalMessage =
+          titles.length > 0
+            ? `${result.error.message} (${titles.join('; ')})`
+            : result.error.message;
         for (const entry of result.error.perFile) {
           console.error(`  ${entry.path}: ${entry.title}`);
         }
@@ -679,7 +701,11 @@ function buildSyncErrorMessage(syncer: RealmSyncer): string {
     `${syncer.skippedConflicts.length} conflicts skipped`,
   ].join(', ');
 
-  return `Sync completed with errors. ${summary}.`;
+  let base = `Sync completed with errors. ${summary}.`;
+  if (syncer.uploadFatalMessage) {
+    return `${base} ${syncer.uploadFatalMessage}`;
+  }
+  return base;
 }
 function emptyResult(partial: Pick<SyncResult, 'error'>): SyncResult {
   return {

package/src/commands/realm/unpublish.ts

@@ -6,6 +6,7 @@ import {
   type ProfileManager,
 } from '../../lib/profile-manager';
 import { FG_CYAN, FG_GREEN, FG_RED, RESET } from '../../lib/colors';
+import { describeFetchError } from '../../lib/describe-fetch-error';
 
 export interface UnpublishOptions {
   /**
@@ -67,9 +68,7 @@ export async function unpublishRealm(
     return {
       publishedRealmURL: normalized,
       unpublished: false,
-      error: `Failed to reach realm server: ${
-        err instanceof Error ? err.message : String(err)
-      }`,
+      error: `Failed to reach realm server: ${describeFetchError(err)}`,
     };
   }
 

package/src/lib/describe-fetch-error.ts

@@ -0,0 +1,25 @@
+// Node's `fetch` error surface is shallow: the outer error is always
+// `TypeError: fetch failed`, and the *real* reason (ECONNRESET, TLS
+// failure, undici socket error, etc.) lives on `error.cause`. Inline
+// both when summarizing a failed fetch for log output or for embedding
+// in a result string returned from a higher-level operation, so that
+// opaque "fetch failed" lines don't reach the operator without context.
+//
+// `error.cause != null` rather than a truthy check so we don't drop
+// falsy-but-defined causes (`''`, `0`, `false`, `NaN`). `!= null`
+// matches both `null` and `undefined` — i.e., the absence markers —
+// and lets every explicit value through.
+//
+// For user-facing CLI output where the full nested Error (including
+// stack frames) is useful, prefer logging `err` and `err.cause` as
+// separate console.error arguments so Node pretty-prints them. This
+// helper is for the case where the output needs to be a single string.
+export function describeFetchError(error: unknown): string {
+  let msg = error instanceof Error ? error.message : String(error);
+  if (error instanceof Error && error.cause != null) {
+    let cause = error.cause;
+    let causeMsg = cause instanceof Error ? cause.message : String(cause);
+    return `${msg} (caused by: ${causeMsg})`;
+  }
+  return msg;
+}