@metaobjectsdev/cli 1.0.9 → 1.0.11

package/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
@@ -286,6 +287,12 @@ function buildAgentSchemaInput(
     );
     return undefined;
   }
+  // MySQL: MetaObjects does not own the schema, so there is no migrate-built schema to
+  // describe. The generated Drizzle tables are the description.
+  if (configured === "mysql") {
+    log.warn("docs: agent/schema.md skipped — MetaObjects does not own a MySQL schema (the generated Drizzle tables describe it).");
+    return undefined;
+  }
   const dialect = configured ?? DEFAULT_DIALECT;
   try {
     const built = buildExpectedSchemaWithProvenance(root, {
@@ -313,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;
   }
@@ -331,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;
   }
 
@@ -418,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;
   }
 
@@ -468,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;
@@ -558,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.`,
     );
@@ -618,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).
@@ -674,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;
@@ -737,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;
   }
 
@@ -806,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(
@@ -913,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;
   }
 }
@@ -931,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 {
@@ -942,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}`);

package/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
@@ -255,7 +256,12 @@ export async function ejectGenerator(opts: EjectOptions): Promise<EjectResult> {
   // The adapter source the OUTPUT imports is part of what is handed over — copied whether
   // or not the generator file itself was already here, and under the same never-clobber
   // rule, so re-running eject fills in a missing copy without touching a kept one.
-  const runtime = ejectsRuntime(opts.name)
+  // Except when the KEPT copy predates that hand-over (1.0.9): with no `runtimeImport`
+  // option its output imports the published package, so the copy would be dead code —
+  // a Drizzle adapter, and its dependencies, in a project that may have no database.
+  const keptCopyImportsPackage =
+    existing !== undefined && !opts.force && !existing.includes("runtimeImport");
+  const runtime = ejectsRuntime(opts.name) && !keptCopyImportsPackage
     ? await ejectRuntime(opts.cwd, [opts.name], opts.force === true)
     : undefined;
 
@@ -613,7 +619,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 +693,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;
   }
 

package/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;
   }
 

package/src/commands/gen.ts

@@ -29,6 +29,8 @@ 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";
+import { findRuntimeBoundaryCrossings, runtimeBoundaryWarnings } from "../lib/runtime-boundary-advisory.js";
 
 /**
  * Print a load failure with everything the loader's ADR-0009 envelope carried — the stable
@@ -65,7 +67,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 +99,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 +138,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 +206,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;
   }
 
@@ -234,6 +236,14 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
     info: "",
   }));
 
+  // Advisory: generated code importing the owned adapter copy from outside its own
+  // workspace package (a monorepo) will not build. Warning only.
+  if (!cliConfig.dryRun) {
+    for (const w of runtimeBoundaryWarnings(
+      findRuntimeBoundaryCrossings(projectRoot, result.files.map((f) => f.path)),
+    )) log.warn(`warning: ${w}`);
+  }
+
   const targetDirs = Array.from(new Set(
     (forgeConfig.targets ? Object.values(forgeConfig.targets).map((t) => t.outDir) : [])
       .concat([forgeConfig.outDir]),
@@ -369,7 +379,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 +412,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 +424,7 @@ async function listCatalogCommand(
     try {
       forgeConfig = await loadMetaobjectsConfig(projectRoot);
     } catch (err) {
-      log.error((err as Error).message);
+      log.error(describeError(err));
       return 2;
     }
 

package/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;
   }
 

package/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.
@@ -157,6 +158,8 @@ Next steps:
   4. meta gen                  # generate from exactly what you wired
   5. meta docs                  # neutral model + API docs (on by default)
   6. Create your tables: meta migrate --from-db --db file:dev.sqlite --dialect sqlite --slug init --apply
+     A new database later (a fresh clone, CI, tests) replays the committed migrations:
+       meta migrate apply-pending --db file:other.sqlite
 `;
 
 export interface InitOptions {
@@ -861,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;
   }
 
@@ -923,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;
   }
 }

package/src/commands/migrate.ts

@@ -65,6 +65,7 @@ import { tokensToAllowOptions, blockedEntriesFor, blockedHintLines } from "../li
 import { reportLoadError } from "../lib/load-error.js";
 import { scanForReferentialActionConflicts } from "../lib/referential-action-advisory.js";
 import type { MetaData } from "@metaobjectsdev/metadata";
+import { describeError } from "../lib/error-text.js";
 
 /**
  * Print a load failure with everything the loader's ADR-0009 envelope carried — the stable
@@ -498,7 +499,7 @@ export async function migrateCommand(
   try {
     flags = parseMigrateArgs(args);
   } catch (err) {
-    const msg = (err as Error).message;
+    const msg = describeError(err);
     log.error(`migrate: ${msg}`);
     emitStructuredError(`migrate: ${msg}`, "run `meta migrate --help` for usage", fmt);
     return 2;
@@ -692,7 +693,7 @@ export async function migrateCommand(
   try {
     collection = await resolveCollection(metaRoot);
   } catch (err) {
-    log.error((err as Error).message);
+    log.error(describeError(err));
     return 2;
   }
 
@@ -712,7 +713,7 @@ export async function migrateCommand(
   try {
     kysely = await buildKyselyFromUrl(config.databaseUrl, config.dialect);
   } catch (err) {
-    log.error(`migrate: ${(err as Error).message}`);
+    log.error(`migrate: ${describeError(err)}`);
     return 2;
   }
 
@@ -758,7 +759,7 @@ export async function migrateCommand(
     try {
       actual = await introspect(kysely.db, kysely.dialect);
     } catch (err) {
-      log.error(`migrate: failed to connect to ${kysely.displayUrl}: ${(err as Error).message}`);
+      log.error(`migrate: failed to connect to ${kysely.displayUrl}: ${describeError(err)}`);
       await kysely.close();
       return 2;
     }
@@ -801,7 +802,7 @@ export async function migrateCommand(
       }
       // diff() throws when onAmbiguous returns "abort" — surface as exit 1
       // with the collected ambiguity list.
-      if ((err as Error).message.includes("aborted by onAmbiguous")) {
+      if (describeError(err).includes("aborted by onAmbiguous")) {
         ambiguous = ambiguousToEntries(collectedAmbiguous);
         const migrateResult = {
           dialect: kysely.dialect,
@@ -895,6 +896,14 @@ export async function migrateCommand(
       if (exitCode === 0 && emitted) {
         if (config.slug === undefined) {
           log.error(`migrate: --slug <name> required when there are changes (e.g., --slug add-user-shipping)`);
+          // The common way to land here is a NEW database (a fresh clone, CI, another
+          // environment) whose migrations are already committed: the diff against an empty
+          // database is every table, so it asks to author a new migration. That database
+          // needs the committed chain replayed, not a new migration.
+          log.error(
+            `  New database, migrations already committed? Apply them instead: ` +
+            `meta migrate apply-pending --db <url>`,
+          );
           await kysely.close();
           return 2;
         }
@@ -936,7 +945,7 @@ export async function migrateCommand(
         });
         appliedNames = [...result.applied];
       } catch (err) {
-        log.error(`migrate: apply failed: ${(err as Error).message}`);
+        log.error(`migrate: apply failed: ${describeError(err)}`);
         exitCode = 1;
         applyFailed = true;
       }
@@ -992,7 +1001,7 @@ export async function migrateCommand(
       } catch (err) {
         // The migration itself is written (and possibly applied) — report the
         // bookkeeping failure for what it is rather than as an unexpected error.
-        log.error(`migrate: failed to write the schema snapshot: ${(err as Error).message}`);
+        log.error(`migrate: failed to write the schema snapshot: ${describeError(err)}`);
         exitCode = 1;
       }
     }
@@ -1000,7 +1009,7 @@ export async function migrateCommand(
     try {
       await kysely.close();
     } catch (err) {
-      log.warn(`migrate: failed to close DB cleanly: ${(err as Error).message}`);
+      log.warn(`migrate: failed to close DB cleanly: ${describeError(err)}`);
     }
   }
 
@@ -1038,7 +1047,7 @@ export async function migrateCommand(
     // A metadata defect, not a tool failure: two declarations generate one database name.
     if (isDuplicateSqlNameError(err)) return refuseEngineError(err, DUPLICATE_SQL_NAME_HINT, fmt);
     // Unexpected error: emit structured error on stdout in the active format, then exit 1.
-    const msg = (err as Error).message ?? String(err);
+    const msg = describeError(err) ?? String(err);
     log.error(`migrate: unexpected error: ${msg}`);
     emitStructuredError(`migrate: unexpected error: ${msg}`, "run `meta migrate --help` for usage", fmt);
     return 1;
@@ -1076,7 +1085,7 @@ export async function runBaseline(
     try {
       kysely = await buildKyselyFromUrl(config.databaseUrl, config.dialect);
     } catch (err) {
-      log.error(`migrate baseline: ${(err as Error).message}`);
+      log.error(`migrate baseline: ${describeError(err)}`);
       return 2;
     }
     try {
@@ -1183,7 +1192,7 @@ export async function runApplyPending(
   try {
     kysely = await buildKyselyFromUrl(config.databaseUrl, config.dialect);
   } catch (err) {
-    log.error(`migrate apply-pending: ${(err as Error).message}`);
+    log.error(`migrate apply-pending: ${describeError(err)}`);
     return 2;
   }
 
@@ -1199,13 +1208,13 @@ export async function runApplyPending(
     pendingNames = [...result.pending];
     appliedNames = [...result.applied];
   } catch (err) {
-    log.error(`migrate apply-pending: apply failed: ${(err as Error).message}`);
+    log.error(`migrate apply-pending: apply failed: ${describeError(err)}`);
     exitCode = 1;
   } finally {
     try {
       await kysely.close();
     } catch (err) {
-      log.warn(`migrate apply-pending: failed to close DB cleanly: ${(err as Error).message}`);
+      log.warn(`migrate apply-pending: failed to close DB cleanly: ${describeError(err)}`);
     }
   }
   if (exitCode !== 0) return exitCode;
@@ -1304,7 +1313,7 @@ export async function runOfflineGenerate(
   try {
     snapshot = await readSnapshot(path);
   } catch (err) {
-    log.error(`migrate: cannot read schema snapshot at ${path}: ${(err as Error).message}`);
+    log.error(`migrate: cannot read schema snapshot at ${path}: ${describeError(err)}`);
     return 2;
   }
   if (snapshot === null) {
@@ -1352,7 +1361,7 @@ export async function runOfflineGenerate(
     // #258 — a primary-key move has no expressible migration; refuse loudly.
     if (isPrimaryKeyChangeError(err)) return refuseEngineError(err, PK_CHANGE_HINT, fmt);
     if (isDeclaredRenameError(err)) return refuseEngineError(err, DECLARED_RENAME_HINT, fmt);
-    if ((err as Error).message.includes("aborted by onAmbiguous")) {
+    if (describeError(err).includes("aborted by onAmbiguous")) {
       log.error(`migrate: ambiguous rename/drop detected; re-run with --on-ambiguous rename|drop-add`);
       return 1;
     }
@@ -1409,6 +1418,7 @@ export async function runOfflineGenerate(
       );
   await writeSnapshot(path, nextSnapshot);
   log.info(`migrate: wrote ${res.upPath}`);
+  log.info(`migrate: wrote ${res.downPath}`);
   return 0;
 }
 
@@ -1438,7 +1448,7 @@ async function runRollback(
   try {
     kysely = await buildKyselyFromUrl(databaseUrl, config.dialect);
   } catch (err) {
-    log.error(`migrate: ${(err as Error).message}`);
+    log.error(`migrate: ${describeError(err)}`);
     return 2;
   }
   // kysely.dialect is "sqlite" | "postgres" here — d1 is rejected upstream.
@@ -1456,13 +1466,13 @@ async function runRollback(
     }
     return 0;
   } catch (err) {
-    log.error(`migrate: rollback failed: ${(err as Error).message}`);
+    log.error(`migrate: rollback failed: ${describeError(err)}`);
     return 1;
   } finally {
     try {
       await kysely.close();
     } catch (err) {
-      log.warn(`migrate: failed to close DB cleanly: ${(err as Error).message}`);
+      log.warn(`migrate: failed to close DB cleanly: ${describeError(err)}`);
     }
   }
 }
@@ -1496,7 +1506,7 @@ async function runD1Migrate(
     try {
       binding = resolveD1Binding(parsed.d1Bindings, config.d1.binding);
     } catch (err) {
-      log.error(`migrate: ${(err as Error).message}`);
+      log.error(`migrate: ${describeError(err)}`);
       return 2;
     }
   } else {
@@ -1538,7 +1548,7 @@ async function runD1Migrate(
   try {
     collection = await resolveCollection(metaRoot);
   } catch (err) {
-    log.error((err as Error).message);
+    log.error(describeError(err));
     return 2;
   }
 
@@ -1579,7 +1589,7 @@ async function runD1Migrate(
       configPath: wranglerConfigPath,
     });
   } catch (err) {
-    log.error(`migrate: failed to introspect D1: ${(err as Error).message}`);
+    log.error(`migrate: failed to introspect D1: ${describeError(err)}`);
     return 2;
   }
 
@@ -1612,7 +1622,7 @@ async function runD1Migrate(
     // #258 — a primary-key move has no expressible migration; refuse loudly.
     if (isPrimaryKeyChangeError(err)) return refuseEngineError(err, PK_CHANGE_HINT, fmt);
     if (isDeclaredRenameError(err)) return refuseEngineError(err, DECLARED_RENAME_HINT, fmt);
-    if ((err as Error).message.includes("aborted by onAmbiguous")) {
+    if (describeError(err).includes("aborted by onAmbiguous")) {
       const entries = ambiguousToEntries(collectedAmbiguous);
       for (const e of entries) {
         log.error(`  ambiguous ${e.kind}: ${e.description}${e.hint ? ` [${e.hint}]` : ""}`);
@@ -1708,7 +1718,7 @@ async function runWranglerApply(
   return await new Promise<number>((resolve) => {
     const child = spawn("wrangler", applyArgs, { stdio: "inherit" });
     child.on("error", (err) => {
-      log.error(`migrate: failed to run wrangler: ${(err as Error).message}`);
+      log.error(`migrate: failed to run wrangler: ${describeError(err)}`);
       resolve(2);
     });
     child.on("close", (code) => resolve(code ?? 1));

package/src/commands/prompt-snapshot.ts

@@ -20,6 +20,7 @@ import { collectionLoadOptions } from "../lib/collection-load-options.js";
 import { loadMemory, resolveCollection } from "@metaobjectsdev/sdk";
 import { TYPE_TEMPLATE, TEMPLATE_ATTR_TEXT_REF, TEMPLATE_ATTR_FORMAT } from "@metaobjectsdev/metadata";
 import { render, ESCAPERS, type RenderFormat } from "@metaobjectsdev/render";
+import { describeError } from "../lib/error-text.js";
 
 const DEFAULT_PROMPTS_DIR = "prompts";
 
@@ -28,7 +29,7 @@ export async function promptSnapshotCommand(args: string[], cwd: string): Promis
   try {
     flags = parsePromptSnapshotArgs(args);
   } catch (err) {
-    log.error((err as Error).message);
+    log.error(describeError(err));
     return 2;
   }
 
@@ -44,7 +45,7 @@ export async function promptSnapshotCommand(args: string[], cwd: string): Promis
   try {
     collection = await resolveCollection(cwd);
   } catch (err) {
-    log.error((err as Error).message);
+    log.error(describeError(err));
     return 2;
   }
 
@@ -117,7 +118,7 @@ export async function promptSnapshotCommand(args: string[], cwd: string): Promis
     try {
       payload = JSON.parse(readFileSync(payloadPath, "utf8"));
     } catch (err) {
-      log.error(`[${tmpl.name}] invalid payload.json: ${(err as Error).message}`);
+      log.error(`[${tmpl.name}] invalid payload.json: ${describeError(err)}`);
       errorCount++;
       continue;
     }
@@ -135,7 +136,7 @@ export async function promptSnapshotCommand(args: string[], cwd: string): Promis
     try {
       rendered = render({ ref: textRef, payload, provider, ...(format ? { format } : {}) });
     } catch (err) {
-      log.error(`[${tmpl.name}] render failed: ${(err as Error).message}`);
+      log.error(`[${tmpl.name}] render failed: ${describeError(err)}`);
       errorCount++;
       continue;
     }

package/src/commands/types.ts

@@ -24,6 +24,7 @@ import { composeRegistry, buildVocabularyCatalog } from "@metaobjectsdev/metadat
 import { defaultLoadMemoryProviders } from "@metaobjectsdev/sdk";
 import { log } from "../lib/log.js";
 import { emitStructured, type OutputFormat } from "../lib/format.js";
+import { describeError } from "../lib/error-text.js";
 
 interface TypesFlags {
   query: string | null;
@@ -210,7 +211,7 @@ export async function typesCommand(args: string[], fmt: OutputFormat = "text"):
   try {
     f = parse(args);
   } catch (err) {
-    const msg = (err as Error).message;
+    const msg = describeError(err);
     log.error(msg);
     // A structured caller gets a structured refusal — exiting 2 with an EMPTY stdout is
     // the same silence a `| jq` cannot tell from "no results". Mirrors verify.ts.
@@ -317,7 +318,11 @@ export async function typesCommand(args: string[], fmt: OutputFormat = "text"):
   const shown = capped ? matches.slice(0, f.limit) : matches;
 
   if (f.detail) {
+    // A subtype's block lists its @attrs with their full descriptions, so an attr row
+    // whose owner subtype is also shown would print the same text a second time.
+    const shownSubtypes = new Set(shown.filter((e) => e.kind === "subtype").map((e) => e.owner));
     for (const e of shown) {
+      if (e.kind === "attr" && shownSubtypes.has(e.owner)) continue;
       log.info(`\n${e.name}  (${e.kind})`);
       if (e.description) log.info(`  ${e.description}`);
       if (e.sharedRoot)

package/src/commands/upgrade.ts

@@ -29,6 +29,7 @@ import {
   retirementSuggestions,
 } from "@metaobjectsdev/metadata";
 import { log } from "../lib/log.js";
+import { describeError } from "../lib/error-text.js";
 
 /** YAML authoring (ADR-0006). Rewritten by the `yaml`-backed arm, loaded on demand below. */
 const YAML_EXTENSIONS = new Set([".yaml", ".yml"]);
@@ -61,7 +62,7 @@ export async function upgradeCommand(args: string[], cwd: string): Promise<numbe
   try {
     flags = parseArgs(args);
   } catch (err) {
-    if ((err as Error).message === "__help__") {
+    if (describeError(err) === "__help__") {
       log.info(
         "meta upgrade [<project>] [--to <version>] [--apply]\n\n" +
           "  Rewrites metadata the current loader no longer accepts, in JSON and YAML alike:\n" +
@@ -72,7 +73,7 @@ export async function upgradeCommand(args: string[], cwd: string): Promise<numbe
       );
       return 0;
     }
-    log.error((err as Error).message);
+    log.error(describeError(err));
     return 2;
   }
 
@@ -82,7 +83,7 @@ export async function upgradeCommand(args: string[], cwd: string): Promise<numbe
   try {
     files = (await resolveCollection(projectRoot)).files;
   } catch (err) {
-    log.error((err as Error).message);
+    log.error(describeError(err));
     return 1;
   }