@metaobjectsdev/cli 1.0.9-rc.6 → 1.0.10

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;
     }
@@ -1438,7 +1447,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 +1465,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 +1505,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 +1547,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 +1588,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 +1621,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 +1717,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;
   }
 

package/src/commands/verify.ts

@@ -106,6 +106,7 @@ import {
 } from "@metaobjectsdev/metadata";
 import { verify, ERR_REQUIRED_SLOT_UNUSED, ERR_PARTIAL_UNRESOLVED } from "@metaobjectsdev/render";
 import { describeLoadError, reportLoadError } from "../lib/load-error.js";
+import { describeError } from "../lib/error-text.js";
 
 const DEFAULT_PROMPTS_DIR = "prompts";
 
@@ -162,7 +163,7 @@ export async function verifyCommand(
   try {
     flags = parseVerifyArgs(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 this command is being fixed for, one level up.
@@ -206,7 +207,7 @@ export async function verifyCommand(
   try {
     collection = await resolveCollection(cwd);
   } catch (err) {
-    const msg = (err as Error).message;
+    const msg = describeError(err);
     log.error(msg);
     emitStructured({ error: msg, hint: "declare metadata `sources` in .metaobjects/config.json, or run `meta init`" }, fmt);
     return 2;
@@ -274,7 +275,7 @@ export async function verifyCommand(
       strict: !flags.lax,
     });
   } catch (err) {
-    const msg = (err as Error).message;
+    const msg = describeError(err);
     // Everything the loader's envelope carried, not just the message: the stable code a
     // CI job keys on, and the FILE + json path the message itself can never name.
     const report = describeLoadError(err);
@@ -481,8 +482,15 @@ export async function verifyCommand(
     // .metaobjects/config.json — the spelling a TypeScript project is least likely
     // to have. migrate's own resolution still WINS where it has an answer, because
     // it is the more specific statement about the chain being replayed.
+    if (flags.dialect === undefined && migrateConfig.dialect === undefined && forgeConfig?.dialect === "mysql") {
+      log.error(
+        "meta verify --replay: MetaObjects does not own a MySQL schema, so there is no migration chain to replay.",
+      );
+      return 2;
+    }
+    const configuredDialect = forgeConfig?.dialect === "mysql" ? undefined : forgeConfig?.dialect;
     const dialect: Dialect | undefined =
-      flags.dialect ?? migrateConfig.dialect ?? forgeConfig?.dialect;
+      flags.dialect ?? migrateConfig.dialect ?? configuredDialect;
     if (dialect === undefined) {
       log.error(
         `meta verify --replay: no dialect — pass --dialect <postgres|sqlite>, ` +
@@ -505,7 +513,7 @@ export async function verifyCommand(
     } catch (err) {
       // A missing optional driver lands here, and its message already carries the
       // install hint. Operational, not drift.
-      log.error(`meta verify --replay: ${(err as Error).message}`);
+      log.error(`meta verify --replay: ${describeError(err)}`);
       return 2;
     }
 
@@ -514,7 +522,7 @@ export async function verifyCommand(
       try {
         applied = await applyPending(engine.db, dir, { dryRun: false, dialect });
       } catch (err) {
-        log.error(`meta verify --replay: ${(err as Error).message}`);
+        log.error(`meta verify --replay: ${describeError(err)}`);
         for (const line of replayRemedy(err)) log.error(`meta verify --replay: ${line}`);
         return 1;
       }
@@ -787,7 +795,7 @@ export async function verifyCommand(
       findings = await lintOverlays(collection, (path) => new FileSource(path));
     } catch (err) {
       // Never let an advisory scan break verify — and never report it as clean.
-      overlaySection = skippedSection(`the overlay lint failed: ${(err as Error).message}`);
+      overlaySection = skippedSection(`the overlay lint failed: ${describeError(err)}`);
       return;
     }
     overlaySection = ranSection(findings.map((d) => toDiagnosticRow(d, "lint")));
@@ -819,7 +827,7 @@ export async function verifyCommand(
       findings = scanSourceForAntiPatterns(projectRoot, ignore !== undefined ? { ignore } : undefined);
     } catch (err) {
       // Never let an advisory scan break verify — and never report it as clean.
-      antiPatternSection = skippedSection(`the scan failed: ${(err as Error).message}`);
+      antiPatternSection = skippedSection(`the scan failed: ${describeError(err)}`);
       return;
     }
     // F52 — the one gate that can see a provider silently missing its base. Folded into
@@ -860,12 +868,17 @@ export async function verifyCommand(
     // each one and says how to declare it (`index.lookup`) instead. Read off the SAME
     // expected schema `meta migrate` builds, so "covered" means covered in its DDL.
     let unindexedFks: UnindexedFkFinding[] = [];
+    // Skipped on MySQL: MetaObjects emits no DDL there, and InnoDB indexes every foreign
+    // key itself.
+    const scanDialect = flags.dialect ?? forgeConfig?.dialect ?? "postgres";
     try {
-      unindexedFks = scanForUnindexedForeignKeys(root, {
-        dialect: flags.dialect ?? forgeConfig?.dialect ?? "postgres",
-        columnNamingStrategy: forgeConfig?.columnNamingStrategy ?? "snake_case",
-        skip: collection.imported,
-      });
+      if (scanDialect !== "mysql") {
+        unindexedFks = scanForUnindexedForeignKeys(root, {
+          dialect: scanDialect,
+          columnNamingStrategy: forgeConfig?.columnNamingStrategy ?? "snake_case",
+          skip: collection.imported,
+        });
+      }
     } catch {
       // Same discipline as its siblings: an advisory scan never breaks verify. A model the
       // schema builder refuses is migrate's to report, with its own message.
@@ -1039,7 +1052,8 @@ export async function verifyCommand(
         const text = provider.resolve(ref);
         if (text === undefined) {
           log.error(
-            `[${tmpl.name}] (${label}) ${ERR_PARTIAL_UNRESOLVED}: ref "${ref}" did not resolve under ${promptsDir}`,
+            `[${tmpl.name}] (${label}) ${ERR_PARTIAL_UNRESOLVED}: ref "${ref}" did not resolve under ${promptsDir}` +
+              ` — create ${join(promptsDir, `${ref}.mustache`)} (or .txt), or point --prompts at the directory that holds it`,
           );
           errorCount++;
           anyErrorHere = true;
@@ -1144,7 +1158,7 @@ export async function verifyCommand(
     try {
       kysely = await buildKyselyFromUrl(flags.db as string, flags.dialect as Dialect | undefined);
     } catch (err) {
-      log.error(`verify: ${(err as Error).message}`);
+      log.error(`verify: ${describeError(err)}`);
       return 1;
     }
 
@@ -1170,7 +1184,7 @@ export async function verifyCommand(
           ...importedOption(collection),
         });
       } catch (err) {
-        log.error(`verify: failed to introspect ${kysely.displayUrl}: ${(err as Error).message}`);
+        log.error(`verify: failed to introspect ${kysely.displayUrl}: ${describeError(err)}`);
         return 1;
       }
 
@@ -1184,7 +1198,7 @@ export async function verifyCommand(
       try {
         await kysely.close();
       } catch (err) {
-        log.warn(`verify: failed to close DB cleanly: ${(err as Error).message}`);
+        log.warn(`verify: failed to close DB cleanly: ${describeError(err)}`);
       }
     }
   }
@@ -1217,7 +1231,7 @@ export async function verifyCommand(
       try {
         binding = resolveD1Binding(parsed.d1Bindings, d1Config.binding);
       } catch (err) {
-        log.error(`verify: ${(err as Error).message}`);
+        log.error(`verify: ${describeError(err)}`);
         return 2;
       }
     } else {
@@ -1241,7 +1255,7 @@ export async function verifyCommand(
     try {
       actual = await introspectD1({ runner: d1Runner, binding: binding.binding, remote, configPath: wranglerConfigPath });
     } catch (err) {
-      log.error(`verify: failed to introspect D1 binding '${binding.binding}': ${(err as Error).message}`);
+      log.error(`verify: failed to introspect D1 binding '${binding.binding}': ${describeError(err)}`);
       return 1;
     }
 
@@ -1258,7 +1272,7 @@ export async function verifyCommand(
         ...importedOption(collection),
       });
     } catch (err) {
-      log.error(`verify: ${(err as Error).message}`);
+      log.error(`verify: ${describeError(err)}`);
       return 1;
     }
 
@@ -1444,7 +1458,7 @@ export async function verifyCommand(
     try {
       result = await computeCodegenDrift(forgeConfig, codegenRoot, genConfigDir, genCollection.inScope);
     } catch (err) {
-      log.error(`verify --codegen: regeneration failed: ${(err as Error).message}`);
+      log.error(`verify --codegen: regeneration failed: ${describeError(err)}`);
       return 1;
     }
 
@@ -1541,7 +1555,7 @@ export async function verifyCommand(
         cwd: genConfigDir,
       });
     } catch (err) {
-      log.error(`verify --docs: regeneration failed: ${(err as Error).message}`);
+      log.error(`verify --docs: regeneration failed: ${describeError(err)}`);
       return 1;
     }
 
@@ -1617,7 +1631,7 @@ export async function verifyCommand(
     try {
       lock = await readLockOrThrow(collection.configDir);
     } catch (err) {
-      log.error(`verify --deps: ${(err as Error).message}`);
+      log.error(`verify --deps: ${describeError(err)}`);
       return 2;
     }
 

package/src/index.ts

@@ -4,6 +4,7 @@ import { cliVersion } from "./lib/version.js";
 import { resolveFormat, isValidFormat, VALID_FORMATS, type OutputFormat } from "./lib/format.js";
 import { resolveCollection } from "@metaobjectsdev/sdk";
 import { GENERATOR_HELP } from "./commands/generator-help.js";
+import { describeError } from "./lib/error-text.js";
 export { defineConfig } from "@metaobjectsdev/codegen-ts";
 export type { MetaobjectsGenConfig } from "@metaobjectsdev/codegen-ts";
 
@@ -591,7 +592,7 @@ export async function run(argv: string[]): Promise<number> {
       try {
         flags = parseAgentDocsArgs(rest);
       } catch (err) {
-        log.error((err as Error).message);
+        log.error(describeError(err));
         return 2;
       }
       const targetCwd = flags.out !== undefined ? resolve(cwd, flags.out) : cwd;
@@ -609,7 +610,7 @@ export async function run(argv: string[]): Promise<number> {
         log.info("Re-run agent-docs to update; --no-wire-root to skip the root CLAUDE.md @import.");
         return 0;
       } catch (err) {
-        log.error((err as Error).message);
+        log.error(describeError(err));
         return 1;
       }
     }

package/src/lib/args.ts

@@ -197,6 +197,23 @@ export function parseExportArgs(argv: string[]): ExportFlags {
 const DIALECTS = ["sqlite", "postgres", "d1"] as const;
 type Dialect = (typeof DIALECTS)[number];
 
+/**
+ * `--dialect` names a database whose schema `meta migrate` / `meta verify --db` OWN. MySQL is
+ * a codegen + runtime dialect (`dialect: "mysql"` in metaobjects.config.ts) and is refused
+ * here by name, so the message says what to do instead of only listing the others.
+ */
+function assertSchemaDialect(dialect: string | undefined): void {
+  if (dialect === undefined || DIALECTS.includes(dialect as Dialect)) return;
+  if (dialect === "mysql") {
+    throw new Error(
+      "invalid --dialect 'mysql': MetaObjects does not own a MySQL schema. " +
+        `Write the DDL yourself; \`dialect: "mysql"\` in metaobjects.config.ts is for generated code. ` +
+        `Schema dialects: ${DIALECTS.join(", ")}`,
+    );
+  }
+  throw new Error(`invalid --dialect '${dialect}'; expected: ${DIALECTS.join(", ")}`);
+}
+
 /**
  * #192 — migration output-format adapters. Orthogonal to dialect: a Flyway shop
  * is still on postgres or sqlite. "default" is the homegrown
@@ -428,9 +445,7 @@ export function parseVerifyArgs(argv: string[]): VerifyFlags {
   });
 
   const dialect = values.dialect as string | undefined;
-  if (dialect !== undefined && !DIALECTS.includes(dialect as Dialect)) {
-    throw new Error(`invalid --dialect '${dialect}'; expected: ${DIALECTS.join(", ")}`);
-  }
+  assertSchemaDialect(dialect);
 
   const allowTokens = parseAllowTokens(values.allow as string | string[] | undefined);
 
@@ -588,9 +603,7 @@ export function parseMigrateArgs(argv: string[]): MigrateFlags {
   }
 
   const dialect = values.dialect as string | undefined;
-  if (dialect !== undefined && !DIALECTS.includes(dialect as Dialect)) {
-    throw new Error(`invalid --dialect '${dialect}'; expected: ${DIALECTS.join(", ")}`);
-  }
+  assertSchemaDialect(dialect);
 
   // NOTE: the flag is --migration-format, not --format: `--format` is already a
   // GLOBAL cli flag selecting output rendering (toon|json|text), consumed in index.ts.

package/src/lib/catalog-listing.ts

@@ -41,6 +41,7 @@ import {
 } from "./runtime-eject.js";
 import { OWNED_RUNTIME_DIR } from "@metaobjectsdev/codegen-ts";
 import { readPackageManifest, declaredDependencyNames } from "./package-manifest.js";
+import { describeError } from "./error-text.js";
 
 /**
  * One `--list` row. The cross-port subset is name / layer / tier / description.
@@ -239,7 +240,7 @@ async function probeOne(
         // Fall through: the original error is the one worth reporting.
       }
     }
-    return { error: (err as Error).message };
+    return { error: describeError(err) };
   }
 }
 
@@ -432,6 +433,9 @@ export const REFERENCE_HELPER_NOTE: readonly string[] = [
   "Each generator is a reference helper, not a guarantee: `meta eject <name>` copies it into",
   "your repo and the copy is yours to change. What MetaObjects guarantees (migrate, verify,",
   "render) is not a generator and is not listed here.",
+  "Your database, store or framework is not listed (MongoDB, DynamoDB, Express, NestJS, Vue, …)?",
+  "Model it anyway and write or retarget a generator: the metaobjects-codegen skill's",
+  "references/any-stack.md has the procedure. MySQL is `dialect: \"mysql\"`.",
 ];
 
 /** The footer line explaining the `package-only` row mark. */

package/src/lib/dependency-sync.ts

@@ -37,6 +37,7 @@ import {
   type Lock,
   type LockEntry,
 } from "@metaobjectsdev/sdk";
+import { describeError } from "./error-text.js";
 
 /** `dependency-sync.ts`'s own `ParseError` factory for every
  *  `ERR_DEPENDENCY_MANIFEST_INVALID` case (DESIGN §4.1 step 2 and step 4):
@@ -128,7 +129,7 @@ export async function readManifestDir(dir: string, name: string): Promise<Manife
   try {
     parsed = JSON.parse(raw);
   } catch (err) {
-    manifestInvalid(name, "readManifestDir", `${manifestPath} is not valid JSON: ${(err as Error).message}`);
+    manifestInvalid(name, "readManifestDir", `${manifestPath} is not valid JSON: ${describeError(err)}`);
   }
 
   const result = DependencyManifestSchema.safeParse(parsed);
@@ -491,7 +492,7 @@ export async function readLockOrThrow(configDir: string): Promise<Lock | undefin
     return await readLock(configDir);
   } catch (err) {
     throw new Error(
-      `${DEFAULT_METAOBJECTS_DIR}/${LOCK_FILE} is corrupted and could not be read: ${(err as Error).message}. ` +
+      `${DEFAULT_METAOBJECTS_DIR}/${LOCK_FILE} is corrupted and could not be read: ${describeError(err)}. ` +
         "Fix it by hand, or delete it and re-run `meta deps sync` to regenerate it.",
     );
   }
@@ -613,7 +614,7 @@ export async function checkDependencies(
         lockIntegrity: lockEntry?.integrity,
         installedVersion: undefined,
         installedIntegrity: undefined,
-        detail: stripDependencyPrefix(name, (err as Error).message),
+        detail: stripDependencyPrefix(name, describeError(err)),
       });
     }
   }

package/src/lib/error-text.ts

@@ -0,0 +1,13 @@
+// The text to print for a caught error. `(err as Error).message` is empty for an
+// AggregateError such as a refused Postgres connection on a dual-stack host, where the
+// detail lives on the inner errors, so a bare `.message` printed nothing after the colon.
+
+export function describeError(err: unknown): string {
+  if (!(err instanceof Error)) return String(err);
+  if (err.message) return err.message;
+  if (err instanceof AggregateError && err.errors.length > 0) {
+    return err.errors.map(describeError).join("; ");
+  }
+  const code = (err as { code?: unknown }).code;
+  return typeof code === "string" && code ? code : err.name;
+}