fix(cli): print the real reason when an error has an empty message

The adopter-estate release gate failed with
`meta migrate apply-pending: apply failed: ` and nothing after the
colon. The cause was a refused Postgres connection: on a dual-stack host
node-postgres rejects with an AggregateError whose own message is empty,
and the CLI printed `(err as Error).message`.

A new `describeError` returns the message, or for an AggregateError the
inner errors' messages, or the error's code or name. It replaces the
raw `.message` read at all 89 sites in the CLI, so no command can print
an empty reason.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M1mRRB1K2WdYy82kntMQdx

Author: dmealing

CHANGELOG.md

@@ -55,6 +55,12 @@ here.**
 
 ### Fixed
 
+- **CLI errors no longer print an empty reason.** A refused Postgres connection on a dual-stack
+  host rejects with an `AggregateError` whose own message is empty, so `meta migrate
+  apply-pending` printed `apply failed: ` and nothing else. Every CLI command now prints the
+  inner errors instead (`connect ECONNREFUSED 127.0.0.1:55440; …`), or the error's code or name
+  when it carries no message.
+
 - **`meta verify` counts only requirement gaps a `@disposition` could settle.** The "recorded
   gap(s) with no @disposition" line counted every `partial` / `planned` requirement without a
   disposition, including roll-up parents that are `partial` only because a descendant is. On one

server/typescript/packages/cli/src/commands/deps.ts

@@ -26,6 +26,7 @@ import {
   planSync,
   readLockOrThrow,
 } from "../lib/dependency-sync.js";
+import { describeError } from "../lib/error-text.js";
 
 /** The declared `dependencies` for the config governing `cwd` — read
  *  DIRECTLY via `loadConfig`, never through `resolveCollection`/`Collection`:
@@ -50,23 +51,23 @@ async function runSync(configDir: string, specs: readonly DependencySpec[], flag
     // Same convention as `depsCommand`'s `declaredDependencies` catch below: a
     // committed project file that fails to parse is a config-class problem,
     // exit 2 — distinct from the exit-1 a `sync` verdict failure gets.
-    log.error((err as Error).message);
+    log.error(describeError(err));
     return 2;
   }
 
   let plan;
   try {
     plan = await planSync(configDir, specs, lock, flags.names);
   } catch (err) {
-    log.error((err as Error).message);
+    log.error(describeError(err));
     return 1;
   }
 
   let applied;
   try {
     applied = await applySync(configDir, plan, { dryRun: flags.dryRun });
   } catch (err) {
-    log.error((err as Error).message);
+    log.error(describeError(err));
     return 1;
   }
 
@@ -100,7 +101,7 @@ async function runSync(configDir: string, specs: readonly DependencySpec[], flag
   try {
     collection = await resolveCollection(configDir);
   } catch (err) {
-    log.error(`meta deps sync: the updated dependency set does not resolve: ${(err as Error).message}`);
+    log.error(`meta deps sync: the updated dependency set does not resolve: ${describeError(err)}`);
     return 1;
   }
   try {
@@ -118,7 +119,7 @@ async function runList(configDir: string, fmt: OutputFormat): Promise<number> {
   try {
     lock = await readLockOrThrow(configDir);
   } catch (err) {
-    log.error((err as Error).message);
+    log.error(describeError(err));
     return 2;
   }
   const entries = Object.entries(lock?.dependencies ?? {});
@@ -159,7 +160,7 @@ async function runCheck(
   try {
     lock = await readLockOrThrow(configDir);
   } catch (err) {
-    log.error((err as Error).message);
+    log.error(describeError(err));
     return 2;
   }
 
@@ -201,7 +202,7 @@ export async function depsCommand(args: string[], cwd: string, fmt: OutputFormat
   try {
     flags = parseDepsArgs(args);
   } catch (err) {
-    log.error((err as Error).message);
+    log.error(describeError(err));
     return 2;
   }
 
@@ -216,7 +217,7 @@ export async function depsCommand(args: string[], cwd: string, fmt: OutputFormat
     // failure (gen.ts, migrate.ts, docs.ts) — distinct from the exit 1 a
     // dependency-resolution failure gets below, because this is a config
     // problem, not a `sync` verdict.
-    log.error((err as Error).message);
+    log.error(describeError(err));
     return 2;
   }
 

server/typescript/packages/cli/src/commands/docs.ts

@@ -56,6 +56,7 @@ import {
 } from "@metaobjectsdev/migrate-ts";
 import type { AgentSchemaInput, SchemaColumnLike } from "@metaobjectsdev/codegen-ts";
 import { reportLoadError } from "../lib/load-error.js";
+import { describeError } from "../lib/error-text.js";
 
 /**
  * Print a load failure with everything the loader's ADR-0009 envelope carried — the stable
@@ -319,7 +320,7 @@ function buildAgentSchemaInput(
     // agent pages still emit.
     log.warn(
       `docs: agent/schema.md skipped — the expected schema could not be built ` +
-        `(${(err as Error).message}). Run 'meta migrate' for the full diagnosis.`,
+        `(${describeError(err)}). Run 'meta migrate' for the full diagnosis.`,
     );
     return undefined;
   }
@@ -337,7 +338,7 @@ export async function docsCommand(
   try {
     flags = parseDocsArgs(args, cwd);
   } catch (err) {
-    log.error(`docs: ${(err as Error).message}`);
+    log.error(`docs: ${describeError(err)}`);
     return 2;
   }
 
@@ -424,7 +425,7 @@ export async function docsCommand(
       flags.projectRootProvided ? { explicitDir: metaRoot } : undefined,
     );
   } catch (err) {
-    log.error(`docs: ${(err as Error).message}`);
+    log.error(`docs: ${describeError(err)}`);
     return 2;
   }
 
@@ -474,7 +475,7 @@ export async function docsCommand(
       configLoadOptions = loadMemoryOptionsFrom(loadedConfig);
     } catch (err) {
       log.warn(
-        `docs: metaobjects.config.ts failed to load (${(err as Error).message}); ` +
+        `docs: metaobjects.config.ts failed to load (${describeError(err)}); ` +
           `generating docs without its providers`,
       );
       loadedConfig = undefined;
@@ -564,7 +565,7 @@ export async function docsCommand(
     suite = resolveGenerators(loadedConfig?.generators ?? []);
   } catch (err) {
     log.warn(
-      `docs: could not resolve the generator suite (${(err as Error).message}) — the agent ` +
+      `docs: could not resolve the generator suite (${describeError(err)}) — the agent ` +
         `pages fall back to the generators declared as values, so a tier wired by name may ` +
         `be missing from them.`,
     );
@@ -624,7 +625,7 @@ export async function docsCommand(
     try {
       modelFiles = await docsFile(modelOpts).generate(ctx);
     } catch (err) {
-      const msg = (err as Error).message;
+      const msg = describeError(err);
       // Duplicate output path (silent-overwrite backstop): the generator already
       // names both colliding FQNs + the path and starts with "docs:". Surface it
       // verbatim as a clean non-zero exit (no double prefix, no stack trace).
@@ -680,7 +681,7 @@ export async function docsCommand(
           );
         }
       } catch (err) {
-        const msg = (err as Error).message;
+        const msg = describeError(err);
         if (msg.startsWith("docs: duplicate output path")) {
           log.error(msg);
           return 1;
@@ -743,7 +744,7 @@ export async function docsCommand(
       await writeFile(path, f.content, "utf8");
     }
   } catch (err) {
-    log.error(`docs: failed to write pages: ${(err as Error).message}`);
+    log.error(`docs: failed to write pages: ${describeError(err)}`);
     return 1;
   }
 
@@ -812,7 +813,7 @@ async function scaffoldSiteCommand(projectRoot: string): Promise<number> {
       created.push(rel);
     }
   } catch (err) {
-    log.error(`docs: failed to scaffold site templates: ${(err as Error).message}`);
+    log.error(`docs: failed to scaffold site templates: ${describeError(err)}`);
     return 1;
   }
   log.info(
@@ -919,7 +920,7 @@ async function emitSite(
     log.info(`meta docs --site — wrote ${r.pages.length} page(s) → ${siteOutDir}`);
     return 0;
   } catch (err) {
-    log.error(`docs: failed to generate site: ${(err as Error).message}`);
+    log.error(`docs: failed to generate site: ${describeError(err)}`);
     return 1;
   }
 }
@@ -937,7 +938,7 @@ async function metamodelDocsCommand(cwd: string, out: string): Promise<number> {
   try {
     docs = renderCoreMetamodelDocs(composeRegistry(coreProviders));
   } catch (err) {
-    log.error(`docs: failed to render metamodel docs: ${(err as Error).message}`);
+    log.error(`docs: failed to render metamodel docs: ${describeError(err)}`);
     return 1;
   }
   try {
@@ -948,7 +949,7 @@ async function metamodelDocsCommand(cwd: string, out: string): Promise<number> {
       await writeFile(path, content, "utf8");
     }
   } catch (err) {
-    log.error(`docs: failed to write metamodel pages: ${(err as Error).message}`);
+    log.error(`docs: failed to write metamodel pages: ${describeError(err)}`);
     return 1;
   }
   log.info(`meta docs --metamodel — wrote ${docs.size} page(s) → ${outDir}`);

server/typescript/packages/cli/src/commands/eject.ts

@@ -36,6 +36,7 @@ import {
   ejectLibrary, ejectableLibraryNames, isLibraryName, libraryStaleness,
   type LibraryEjectResult,
 } from "../lib/library-eject.js";
+import { describeError } from "../lib/error-text.js";
 
 // Mirrors `OWNED_GENERATORS_DIR` in init.ts's `writeOwnedGenerators` — same directory,
 // same never-clobber-without-consent contract. Kept as its own local constant rather
@@ -613,7 +614,7 @@ export async function ejectCommand(
   try {
     flags = parseEjectArgs(args);
   } catch (err) {
-    log.error((err as Error).message);
+    log.error(describeError(err));
     return 2;
   }
 
@@ -687,7 +688,7 @@ export async function ejectCommand(
       if (fmt === "text") reportOne(result, name);
     }
   } catch (err) {
-    log.error((err as Error).message);
+    log.error(describeError(err));
     return 1;
   }
 

server/typescript/packages/cli/src/commands/export.ts

@@ -6,13 +6,14 @@ import { FileSource } from "@metaobjectsdev/metadata/core";
 import { TypeRegistry, registerCoreTypes, MetaDataLoader, canonicalSerialize } from "@metaobjectsdev/metadata";
 import { registerForgeTypes, resolveCollection } from "@metaobjectsdev/sdk";
 import { collectionLoadOptions } from "../lib/collection-load-options.js";
+import { describeError } from "../lib/error-text.js";
 
 export async function exportCommand(args: string[], cwd: string): Promise<number> {
   let flags;
   try {
     flags = parseExportArgs(args);
   } catch (err) {
-    log.error((err as Error).message);
+    log.error(describeError(err));
     return 2;
   }
 
@@ -34,7 +35,7 @@ export async function exportCommand(args: string[], cwd: string): Promise<number
   try {
     collection = await resolveCollection(projectRoot);
   } catch (err) {
-    log.error((err as Error).message);
+    log.error(describeError(err));
     return 1;
   }
 

server/typescript/packages/cli/src/commands/gen.ts

@@ -29,6 +29,7 @@ import {
 } from "../lib/catalog-listing.js";
 import { emitStructured } from "../lib/format.js";
 import { composeCatalog } from "../lib/catalog.js";
+import { describeError } from "../lib/error-text.js";
 
 /**
  * Print a load failure with everything the loader's ADR-0009 envelope carried — the stable
@@ -65,7 +66,7 @@ export function mapStatus(s: WriteStatus): GenFileStatus {
 export async function genCommand(args: string[], cwd: string, fmt: OutputFormat = "text"): Promise<number> {
   let flags;
   try { flags = parseGenArgs(args); }
-  catch (err) { log.error((err as Error).message); return 2; }
+  catch (err) { log.error(describeError(err)); return 2; }
 
   // ADR-0021 D3 — `meta gen --list`: print the generator CATALOG and exit 0 WITHOUT
   // running codegen. No project is required (like `meta types`): "what can this engine
@@ -97,7 +98,7 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
   try {
     collection = await resolveCollection(cwd);
   } catch (err) {
-    log.error((err as Error).message);
+    log.error(describeError(err));
     return 2;
   }
   // ...but `metaobjects.config.ts` is not named by the metadata: it is this
@@ -136,7 +137,7 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
   try {
     forgeConfig = await loadMetaobjectsConfig(projectRoot);
   } catch (err) {
-    log.error((err as Error).message);
+    log.error(describeError(err));
     return 2;
   }
 
@@ -204,7 +205,7 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
       ...(cliConfig.entities.length > 0 ? { entityFilter: cliConfig.entities } : {}),
     });
   } catch (err) {
-    log.error(`gen failed: ${(err as Error).message}`);
+    log.error(`gen failed: ${describeError(err)}`);
     return 1;
   }
 
@@ -369,7 +370,7 @@ function runAntiPatternScan(
       projectRoot, ignore !== undefined ? { ignore } : undefined)));
   } catch (err) {
     // Never let an advisory scan break gen — but never claim it found nothing either.
-    return skippedSection(`the scan failed: ${(err as Error).message}`);
+    return skippedSection(`the scan failed: ${describeError(err)}`);
   }
 }
 
@@ -402,7 +403,7 @@ async function listCatalogCommand(
       collection = await resolveCollection(cwd);
     } catch (err) {
       log.error(
-        `meta gen --list --probe needs a project to probe: ${(err as Error).message}\n` +
+        `meta gen --list --probe needs a project to probe: ${describeError(err)}\n` +
           "Run `meta gen --list` (no --probe) for the catalog on its own.",
       );
       return 2;
@@ -414,7 +415,7 @@ async function listCatalogCommand(
     try {
       forgeConfig = await loadMetaobjectsConfig(projectRoot);
     } catch (err) {
-      log.error((err as Error).message);
+      log.error(describeError(err));
       return 2;
     }
 

server/typescript/packages/cli/src/commands/generator.ts

@@ -24,6 +24,7 @@ import {
   OWNED_GENERATORS_DIR,
   type GeneratorScope,
 } from "./generator-help.js";
+import { describeError } from "../lib/error-text.js";
 
 export { GENERATOR_HELP, GENERATOR_OPTIONS, GENERATOR_SCOPES, OWNED_GENERATORS_DIR } from "./generator-help.js";
 export type { GeneratorScope } from "./generator-help.js";
@@ -334,7 +335,7 @@ export async function generatorCommand(args: string[], cwd: string): Promise<num
   try {
     ({ values, positionals } = parseArgs({ args, options: GENERATOR_OPTIONS, strict: true, allowPositionals: true }));
   } catch (err) {
-    log.error((err as Error).message);
+    log.error(describeError(err));
     return 2;
   }
   const [sub, name, ...extra] = positionals;
@@ -358,7 +359,7 @@ export async function generatorCommand(args: string[], cwd: string): Promise<num
       wire: values["no-wire"] !== true,
     });
   } catch (err) {
-    log.error((err as Error).message);
+    log.error(describeError(err));
     return 2;
   }
 

server/typescript/packages/cli/src/commands/init.ts

@@ -14,6 +14,7 @@ import { log } from "../lib/log.js";
 import { cliVersion } from "../lib/version.js";
 import { findWranglerConfig, parseWranglerConfig } from "@metaobjectsdev/migrate-ts";
 import { DEFAULT_DOCS_DIR } from "@metaobjectsdev/codegen-ts";
+import { describeError } from "../lib/error-text.js";
 
 // ADR-0034 scaffold-and-own — `meta init` copies the codegen reference templates into
 // the consumer's repo so they OWN them; metaobjects.config.ts imports them locally.
@@ -863,7 +864,7 @@ export async function initCommand(args: string[], cwd: string): Promise<number>
     // init failure gets. `init()` refuses it too, which is what covers every other door.
     assertKnownStackValues({ servers: flags.servers ?? [], clients: flags.clients ?? [] });
   } catch (err) {
-    log.error((err as Error).message);
+    log.error(describeError(err));
     return 2;
   }
 
@@ -925,7 +926,7 @@ export async function initCommand(args: string[], cwd: string): Promise<number>
     }
     return 0;
   } catch (err) {
-    log.error((err as Error).message);
+    log.error(describeError(err));
     return 1;
   }
 }