@metaobjectsdev/cli 1.0.9 → 1.0.11

package/src/commands/verify.ts

@@ -39,6 +39,7 @@ import {
 } from "../lib/requirement-check.js";
 import { lintRequirements } from "../lib/requirement-lint.js";
 import { lintOverlays } from "../lib/overlay-lint.js";
+import { lintNodeNames } from "../lib/name-lint.js";
 import { FileSource } from "@metaobjectsdev/metadata/core";
 import { resolveD1Config, resolveMigrateConfig } from "../lib/config.js";
 import {
@@ -106,6 +107,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 +164,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 +208,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 +276,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);
@@ -349,6 +351,11 @@ export async function verifyCommand(
   // way every other advisory pass does.
   let overlaySection: AdvisorySection<AdvisoryDiagnosticRow> =
     skippedSection("the overlay lint did not run");
+  // The node-name authoring lint — its own section for the same reason: a model
+  // carrying a few hundred legacy names must not push another section's findings
+  // off the end of a capped run.
+  let nameSection: AdvisorySection<AdvisoryDiagnosticRow> =
+    skippedSection("the name lint did not run");
   // The ledger counts `meta verify` prints on every run. Undefined for a project
   // declaring no requirement.* node at all (opt-in by declaration) — the payload
   // then omits the block rather than reporting zeroes that would read as an empty
@@ -385,6 +392,10 @@ export async function verifyCommand(
   // Warnings ONLY — never changes the exit code.
   await runOverlayLintAdvisory();
 
+  // Whitespace in a node's `name` — loads clean on every port, almost never meant.
+  // Runs on every `meta verify`; warnings ONLY, never changes the exit code.
+  runNameLintAdvisory();
+
   // Advisory verify-as-teacher pass: surface hand-rolled work the metadata could
   // model. Warnings ONLY — never changes the exit code (bias to under-flagging).
   // Suppressed with --no-antipatterns or META_NO_ANTIPATTERNS=1 for the rare
@@ -433,6 +444,7 @@ export async function verifyCommand(
         requirementCounts,
         antiPatterns: antiPatternSection,
         overlays: overlaySection,
+        names: nameSection,
       }),
       fmt,
     );
@@ -481,8 +493,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 +524,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 +533,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 +806,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")));
@@ -800,6 +819,29 @@ export async function verifyCommand(
     }
   }
 
+  // -- node-name authoring lint (advisory) -----------------------------------
+  // Reads the LOADED model (see name-lint.ts). Its own section, its own cap, and
+  // a skip that carries its reason rather than looking like a clean scan.
+  function runNameLintAdvisory(): void {
+    if (flags.noNameLint) {
+      nameSection = skippedSection("suppressed by --no-name-lint");
+      return;
+    }
+    if (process.env.META_NO_NAME_LINT === "1") {
+      nameSection = skippedSection("suppressed by META_NO_NAME_LINT=1");
+      return;
+    }
+    const findings = lintNodeNames(root);
+    nameSection = ranSection(findings.map((d) => toDiagnosticRow(d, "lint")));
+    if (findings.length > 0) {
+      log.warn(
+        `meta verify — names: ${findings.length} authoring warning(s) ` +
+          `(advisory — does not fail the build):`,
+      );
+      warnCapped(findings.map(formatDiagnostic), flags.limit, { structured });
+    }
+  }
+
   // -- verify-as-teacher (advisory) ------------------------------------------
   // Records its result EITHER WAY — a skip carries its reason rather than looking
   // like a clean scan. Warnings only; nothing here reaches the exit code (the
@@ -819,7 +861,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 +902,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 +1086,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 +1192,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 +1218,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 +1232,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 +1265,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 +1289,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 +1306,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 +1492,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 +1589,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 +1665,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;
     }
 
@@ -1807,6 +1855,7 @@ function buildVerifyPayload(input: {
   requirementCounts: RequirementCounts | undefined;
   antiPatterns: AdvisorySection<AdvisoryFindingRow>;
   overlays: AdvisorySection<AdvisoryDiagnosticRow>;
+  names: AdvisorySection<AdvisoryDiagnosticRow>;
 }): Record<string, unknown> {
   const ran = input.gates.filter((g) => g.ran);
   const failed = ran.filter((g) => !g.ok);
@@ -1826,6 +1875,9 @@ function buildVerifyPayload(input: {
   if (input.overlays.status === "ran" && input.overlays.total > 0) {
     parts.push(`${input.overlays.total} overlay authoring finding(s)`);
   }
+  if (input.names.status === "ran" && input.names.total > 0) {
+    parts.push(`${input.names.total} name authoring finding(s)`);
+  }
 
   const help: string[] = [];
   if (failed.length > 0) {
@@ -1841,11 +1893,17 @@ function buildVerifyPayload(input: {
       `${input.overlays.total} unflagged cross-file redeclaration(s) — see overlays.rows[]; add overlay: true so a renamed or removed target fails loudly instead of silently becoming a new object`,
     );
   }
+  if (input.names.total > 0) {
+    help.push(
+      `${input.names.total} node name(s) containing whitespace — see names.rows[]; rename each node, and pin @column on a field whose physical column must keep its name`,
+    );
+  }
   if (
     failed.length === 0 &&
     input.antiPatterns.total === 0 &&
     input.requirements.total === 0 &&
-    input.overlays.total === 0
+    input.overlays.total === 0 &&
+    input.names.total === 0
   ) {
     help.push("no drift and nothing advisory to answer — nothing to do");
   }
@@ -1858,6 +1916,7 @@ function buildVerifyPayload(input: {
     antiPatterns: input.antiPatterns,
     requirements: input.requirements,
     overlays: input.overlays,
+    names: input.names,
     ...(input.requirementCounts !== undefined ? { requirementCounts: input.requirementCounts } : {}),
     // The honest boundary. Everything named here is REACHABLE — it is printed as
     // text on stderr — but it is not in this document, and a reader must not have

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";
 
@@ -126,6 +127,8 @@ VERIFY FLAGS (ADR-0021 D2 — explicit subverbs; combine any; exit 1 on ANY drif
   --no-requirement-lint Suppress the advisory requirement AUTHORING lint (not the gate)
   --no-overlay-lint     Suppress the advisory overlay-redeclaration AUTHORING lint
                         (never a gate — this lint can't fail the build)
+  --no-name-lint        Suppress the advisory node-name AUTHORING lint (whitespace
+                        in a name; never a gate — this lint can't fail the build)
   --limit <n|all>       How many advisory lines TEXT output prints per section before
                         it truncates (default 20). Never applies to --format
                         toon/json, which carry every finding and every diagnostic.
@@ -319,6 +322,8 @@ FLAGS:
   --no-requirement-lint Suppress the advisory requirement AUTHORING lint (not the gate)
   --no-overlay-lint     Suppress the advisory overlay-redeclaration AUTHORING lint —
                         never a gate; this lint can't fail the build
+  --no-name-lint        Suppress the advisory node-name AUTHORING lint (whitespace in
+                        a name) — never a gate; this lint can't fail the build
   --limit <n|all>       Advisory lines TEXT output prints PER SECTION before truncating
                         (default 20; per-section so the authoring lint can never push
                         the gate's own warnings off the end)
@@ -349,6 +354,13 @@ redeclaration lacks 'overlay: true' — today's default merge rule reuses it
 silently, but the same unflagged redeclaration silently becomes a NEW object
 the day the target is renamed or removed upstream. Warnings only — it can
 never fail the build. Opt out with --no-overlay-lint or META_NO_OVERLAY_LINT=1.
+
+verify also prints an ADVISORY node-name authoring lint, in its own section: any
+node (object, field, identity, relationship, ...) whose name contains whitespace.
+Leading or trailing whitespace is almost certainly a copy-paste accident — rename
+the node, and pin @column on a field whose physical column must keep its name.
+Requirement names are left to the requirement lint above. Warnings only — it can
+never fail the build. Opt out with --no-name-lint or META_NO_NAME_LINT=1.
 `,
   export: `meta export — flatten loaded metadata to one canonical JSON artifact
 
@@ -591,7 +603,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 +621,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
@@ -345,6 +362,13 @@ export interface VerifyFlags {
    * lint has no gate half at all — it can never fail the build).
    */
   noOverlayLint: boolean;
+  /**
+   * Suppress the advisory node-NAME authoring lint — whitespace in a node's
+   * `name` (a trailing space copied from legacy XML loads clean on every port).
+   * Advisory only, like its siblings: it has no gate half and can never fail
+   * the build.
+   */
+  noNameLint: boolean;
   /**
    * ADR-0023 strict-attr load opt-OUT (#96). `verify` is strict-by-default — an
    * undeclared/typo'd own `@attr` fails verify (ERR_UNKNOWN_ATTR). `--lax`
@@ -386,6 +410,7 @@ export const VERIFY_OPTIONS = {
   "no-antipatterns": { type: "boolean", default: false },
   "no-requirement-lint": { type: "boolean", default: false },
   "no-overlay-lint": { type: "boolean", default: false },
+  "no-name-lint": { type: "boolean", default: false },
   lax: { type: "boolean", default: false },
   "d1": { type: "string" },
   "remote": { type: "boolean", default: false },
@@ -428,9 +453,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);
 
@@ -472,6 +495,7 @@ export function parseVerifyArgs(argv: string[]): VerifyFlags {
     noAntipatterns: !!values["no-antipatterns"],
     noRequirementLint: !!values["no-requirement-lint"],
     noOverlayLint: !!values["no-overlay-lint"],
+    noNameLint: !!values["no-name-lint"],
     lax: !!values.lax,
     d1: values.d1 as string | undefined,
     remote: !!values.remote,
@@ -588,9 +612,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;
+}

package/src/lib/fk-index-advisory.ts

@@ -96,7 +96,10 @@ export function scanForUnindexedForeignKeys(root: MetaData, opts: UnindexedFkOpt
       });
       const fields = ref !== undefined ? ref.fields : fk.columns;
       const label = ref !== undefined ? `${entity.name}.${ref.name}` : `${entity.name} (${fk.name})`;
-      const indexName = `by${fields.map(pascal).join("")}`;
+      // Entity-prefixed: an index name is schema-wide in Postgres, so a bare `by<Field>`
+      // suggested the SAME name to every entity sharing the FK field, and applying the advice
+      // verbatim failed `meta migrate` with ERR_DUPLICATE_SQL_NAME.
+      const indexName = `${entity.name.charAt(0).toLowerCase()}${entity.name.slice(1)}By${fields.map(pascal).join("")}`;
       const fieldList = fields.length === 1 ? fields[0]! : `[${fields.join(", ")}]`;
       out.push({
         file: files[0] ?? "",

package/src/lib/gen-migrate-advice.ts

@@ -40,7 +40,7 @@ const VIEW_CHANGE_KINDS: ReadonlySet<Change["kind"]> = new Set(["create-view", "
 export interface GenMigrateAdviceInput {
   metadata: MetaRoot;
   /** `metaobjects.config.ts` `dialect` — undefined when no DB code is generated. */
-  dialect: "sqlite" | "postgres" | undefined;
+  dialect: "sqlite" | "postgres" | "mysql" | undefined;
   /** `.metaobjects/config.json` `migrate.dialect`, when set (may say `d1`). */
   migrateDialect: "sqlite" | "postgres" | "d1" | undefined;
   columnNamingStrategy: "snake_case" | "literal" | "kebab-case" | undefined;
@@ -55,6 +55,8 @@ export interface GenMigrateAdviceInput {
 export async function genMigrateAdvice(input: GenMigrateAdviceInput): Promise<string | undefined> {
   if (input.dialect === undefined || input.changedFiles.length === 0) return undefined;
 
+  if (input.dialect === "mysql") return mysqlAdvice(input);
+
   const d1 = d1BindingFor(input);
   const schemaDialect = d1 !== undefined ? "d1" : input.dialect;
   let built;
@@ -94,6 +96,27 @@ export async function genMigrateAdvice(input: GenMigrateAdviceInput): Promise<st
     : `migrate the schema change with \`meta migrate --db <url> --dialect ${input.dialect} --slug <name> --apply\``;
 }
 
+/**
+ * MySQL: `meta migrate` does not own the schema, so there is no migration to write. When the
+ * run touched a table-backed object, say that the adopter's DDL has to follow. The provenance
+ * (which generated file belongs to which table-backed object) does not depend on the dialect,
+ * so it is read through the Postgres expected-schema builder.
+ */
+function mysqlAdvice(input: GenMigrateAdviceInput): string | undefined {
+  let provenance: ReadonlyMap<string, string>;
+  try {
+    provenance = buildExpectedSchemaWithProvenance(input.metadata, {
+      dialect: "postgres",
+      ...(input.columnNamingStrategy !== undefined ? { columnNamingStrategy: input.columnNamingStrategy } : {}),
+    }).provenance;
+  } catch {
+    return undefined;
+  }
+  if (!touchesTableBackedObject(input.changedFiles, provenance)) return undefined;
+  return "MetaObjects does not manage a MySQL schema: apply the matching change to your MySQL DDL " +
+    "(the generated Drizzle tables describe the columns it must have)";
+}
+
 /** The project's D1 binding when it migrates through D1, else undefined. */
 function d1BindingFor(input: GenMigrateAdviceInput): D1Binding | undefined {
   if (input.dialect !== "sqlite" && input.migrateDialect !== "d1") return undefined;

package/src/lib/git-ignore.ts

@@ -17,6 +17,7 @@
 
 import { spawnSync } from "node:child_process";
 import { toPosix } from "./rel-posix.js";
+import { describeError } from "./error-text.js";
 
 /** Ignored paths, or the reason the question could not be asked. */
 export type GitIgnoreResult =
@@ -75,7 +76,7 @@ export function gitIgnored(
   try {
     res = spawnSync(gitBin, args, { encoding: "utf-8", input });
   } catch (err) {
-    return { unavailable: `git could not be run (${(err as Error).message})` };
+    return { unavailable: `git could not be run (${describeError(err)})` };
   }
   if (res.error !== undefined) {
     return { unavailable: "git is not on PATH" };