@metaobjectsdev/cli 1.0.9-rc.2 → 1.0.9-rc.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/cli",
-  "version": "1.0.9-rc.2",
+  "version": "1.0.9-rc.4",
   "description": "CLI for MetaObjects: scaffold, codegen, migrate, and drift-detection commands.",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -51,15 +51,15 @@
     "@biomejs/js-api": "^0.7.0",
     "@biomejs/wasm-nodejs": "^1.9.4",
     "@libsql/kysely-libsql": "^0.4.0",
-    "@metaobjectsdev/codegen-ts": "1.0.9-rc.2",
-    "@metaobjectsdev/codegen-ts-react": "1.0.9-rc.2",
-    "@metaobjectsdev/codegen-ts-tanstack": "1.0.9-rc.2",
-    "@metaobjectsdev/docs-site": "1.0.9-rc.2",
-    "@metaobjectsdev/metadata": "1.0.9-rc.2",
-    "@metaobjectsdev/migrate-ts": "1.0.9-rc.2",
-    "@metaobjectsdev/render": "1.0.9-rc.2",
-    "@metaobjectsdev/runtime-ts": "1.0.9-rc.2",
-    "@metaobjectsdev/sdk": "1.0.9-rc.2",
+    "@metaobjectsdev/codegen-ts": "1.0.9-rc.4",
+    "@metaobjectsdev/codegen-ts-react": "1.0.9-rc.4",
+    "@metaobjectsdev/codegen-ts-tanstack": "1.0.9-rc.4",
+    "@metaobjectsdev/docs-site": "1.0.9-rc.4",
+    "@metaobjectsdev/metadata": "1.0.9-rc.4",
+    "@metaobjectsdev/migrate-ts": "1.0.9-rc.4",
+    "@metaobjectsdev/render": "1.0.9-rc.4",
+    "@metaobjectsdev/runtime-ts": "1.0.9-rc.4",
+    "@metaobjectsdev/sdk": "1.0.9-rc.4",
     "@toon-format/toon": "^2.3.0",
     "jiti": "^2.4.0"
   },

package/src/commands/eject.ts

@@ -142,6 +142,9 @@ export interface EjectResult {
   packageName: string;
   /** Advisory lines about packages the ejected file imports but the project lacks. */
   dependencyNotes: string[];
+  /** Every `@metaobjectsdev/*` package the ejected file imports (declared or not) — what
+   *  the consolidated install summary folds in, so it covers each per-file line. */
+  templatePackages: string[];
   status: "created" | "preserved" | "replaced";
   /**
    * How the file ALREADY on disk compares to the reference template this CLI ships.
@@ -231,6 +234,7 @@ export async function ejectGenerator(opts: EjectOptions): Promise<EjectResult> {
     exportName,
     packageName: source.packageName,
     dependencyNotes: notes,
+    templatePackages: requiredPackages(templateSource),
   };
 
   const existing = (await fileExists(abs)) ? await readFile(abs, "utf8") : undefined;
@@ -570,6 +574,7 @@ export async function ejectCommand(
   const catalog = composeCatalog();
   const rows: EjectedRow[] = [];
   const libraries: LibraryEjectResult[] = [];
+  const templatePackages = new Set<string>();
   try {
     for (const name of flags.names) {
       if (isLibraryName(name)) {
@@ -579,6 +584,7 @@ export async function ejectCommand(
         continue;
       }
       const result = await ejectGenerator({ cwd, name, force: flags.force });
+      for (const p of result.templatePackages) templatePackages.add(p);
       rows.push({
         name,
         path: result.path,
@@ -595,12 +601,16 @@ export async function ejectCommand(
 
   // ONE install set for the whole call, not one per name: ejecting `hooks` and `grid`
   // needs @metaobjectsdev/codegen-ts-tanstack once, and an adopter handed the same
-  // package twice reasonably wonders which line to run.
+  // package twice reasonably wonders which line to run. It folds in what the ejected
+  // FILES import as well as what the catalog says the generators need: the reference
+  // templates import `@metaobjectsdev/metadata` at gen time, which no catalog entry
+  // names, so a summary built from the catalog alone printed a line that omitted a
+  // package each per-file note had just asked for.
   const entries = flags.names
     .filter((n) => !isLibraryName(n))
     .map((n) => catalog[n])
     .filter((e) => e !== undefined);
-  const install = installSetFor(entries);
+  const install = installSetFor(entries, [...templatePackages]);
   const configKeys = [...new Set(entries.flatMap((e) => e.configKeys ?? []))].sort();
 
   if (fmt === "text") {

package/src/commands/gen.ts

@@ -1,6 +1,7 @@
 import { relative } from "node:path";
 import { parseGenArgs } from "../lib/args.js";
-import { resolveGenConfig } from "../lib/config.js";
+import { resolveGenConfig, resolveMigrateDefaults } from "../lib/config.js";
+import { genMigrateAdvice } from "../lib/gen-migrate-advice.js";
 import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenCollection, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
 import { collectionLoadOptions } from "../lib/collection-load-options.js";
 import { formatGenResult, formatGenResultToon, type GenFileEntry, type GenFileStatus } from "../lib/output.js";
@@ -35,6 +36,9 @@ import { composeCatalog } from "../lib/catalog.js";
  */
 
 
+/** Write outcomes that change a file on disk — the ones that can carry a schema change. */
+const CHANGED_STATUSES: ReadonlySet<WriteStatus> = new Set<WriteStatus>(["new", "overwrite", "merged", "conflict", "removed"]);
+
 export function mapStatus(s: WriteStatus): GenFileStatus {
   switch (s) {
     case "new":       return "new";
@@ -232,6 +236,17 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
   const antiPatterns = runAntiPatternScan(
     projectRoot, cliConfig.dryRun, flags.noAntipatterns, forgeConfig.verify?.antiPatternIgnore);
 
+  const migrateDefaults = await resolveMigrateDefaults(projectRoot);
+  const migrateAdvice = await genMigrateAdvice({
+    metadata,
+    dialect: forgeConfig.dialect,
+    migrateDialect: migrateDefaults.dialect,
+    columnNamingStrategy: forgeConfig.columnNamingStrategy,
+    projectRoot,
+    migrateOutDir: migrateDefaults.outDir,
+    changedFiles: result.files.filter((f) => CHANGED_STATUSES.has(f.status)).map((f) => f.path),
+  });
+
   const genResult = {
     files,
     outDir: targetDirs.length > 1 ? targetDirs.join(", ") : forgeConfig.outDir,
@@ -240,6 +255,7 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
     warnings: [],
     antiPatterns,
     generatorCount: forgeConfig.generators?.length ?? 0,
+    ...(migrateAdvice !== undefined ? { migrateAdvice } : {}),
   };
   const output =
     fmt === "toon" ? formatGenResultToon(genResult)
@@ -412,7 +428,9 @@ async function listCatalogCommand(
         // codegen config it was moved out of.
         libraries: genCollection.libraries,
       },
-      probe: { metadata, scope: genCollection.inScope },
+      // The collection's own files, exactly as `meta gen` supplies them below —
+      // `shared-model` cannot be counted without them.
+      probe: { metadata, scope: genCollection.inScope, sourceFiles: genCollection.ownFiles },
     };
   } else {
     // No probe: still report `wired` / `owned` when a project happens to be here, since

package/src/commands/migrate.ts

@@ -19,6 +19,7 @@ import {
   isBlockedChangesError,
   isPrimaryKeyChangeError,
   isDeclaredRenameError,
+  isDuplicateSqlNameError,
   buildExpectedSchemaWithProvenance,
   scopeExpectedSchema,
   scopedDiffInputs,
@@ -314,6 +315,8 @@ function refuseEngineError(err: Error, hint: string, fmt: OutputFormat): number
 
 const PK_CHANGE_HINT =
   "align the primary key manually, or reconcile the metadata identity to match the live table";
+const DUPLICATE_SQL_NAME_HINT =
+  "rename one of the colliding declarations; an index's database name is its identity.secondary / index.lookup name, not prefixed with its table";
 const DECLARED_RENAME_HINT =
   "fix or remove the --rename-table / --rename-column flag; a table's name is its name in the metadata (the new name when it is renamed too)";
 
@@ -1032,6 +1035,8 @@ export async function migrateCommand(
     // AlreadyEmittedError: sub-function already called emitStructuredError — just
     // propagate the exit code without double-emitting.
     if (err instanceof AlreadyEmittedError) return err.exitCode;
+    // 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);
     log.error(`migrate: unexpected error: ${msg}`);

package/src/commands/verify.ts

@@ -416,12 +416,12 @@ export async function verifyCommand(
 
   // Naming a gate runs ONLY the gates named (ADR-0021 D2), so `verify --codegen --db <url>`
   // exits 0 without ever looking at the prompt templates. A green partial run must not read
-  // as a full one: say which gates did not run and how to select each. A bare `verify` has
-  // already said so in its default note above.
-  if (flags.anyExplicit) {
-    const note = notRunNote(gates);
-    if (note !== undefined) say(note);
-  }
+  // as a full one: say which gates did not run and how to select each. The BARE run says so
+  // too, at the END where the verdict is read: its opening note scrolls past, and on a model
+  // with no templates the only other line was "nothing to check" over a green exit — easy to
+  // wire into CI believing it guards everything. Never changes the exit code.
+  const note = notRunNote(gates, { bare: !flags.anyExplicit });
+  if (note !== undefined) say(note);
 
   if (structured) {
     emitStructured(
@@ -937,7 +937,9 @@ export async function verifyCommand(
     // ADR-0039: effective children — resolve rather than rely on root being unextended.
     const templates = root.children().filter((c) => c.type === TYPE_TEMPLATE);
     if (templates.length === 0) {
-      say("meta verify — no template.* nodes found; nothing to check.");
+      // Names the GATE that had nothing to check — "nothing to check" alone read as a
+      // verdict on the whole project.
+      say("meta verify — no template.* nodes found; the template gate had nothing to check.");
       return 0;
     }
 
@@ -1450,13 +1452,19 @@ export async function verifyCommand(
       return 2;
     }
 
+    // Hand edits are not drift, but they must never be INVISIBLE: a validator weakened
+    // inside a generated file used to pass this gate with "every file's generated
+    // contribution is current" and nothing else. Reported on every run; fails the build
+    // only under --forbid-hand-edits.
+    const handEditExit = reportHandEdits(result.handEdited);
+
     if (result.clean) {
       // Says what it CHECKED, not more. Since 0.24.3 this gate asks whether each file's
       // GENERATED contribution is current — a hand edit `meta gen` preserves is exempt —
       // so "output is in sync with the metadata" claimed a stronger property than it had
       // verified, and did so over a file whose committed content contradicted the model.
       say("meta verify — every file's generated contribution is current (no codegen drift).");
-      return 0;
+      return handEditExit;
     }
 
     log.error(
@@ -1481,6 +1489,23 @@ export async function verifyCommand(
     return 1;
   }
 
+  /** Print the hand-edit notice (or failure, under --forbid-hand-edits); return its exit code. */
+  function reportHandEdits(handEdited: readonly string[]): number {
+    if (handEdited.length === 0) return 0;
+    const [header, ...rest] = handEditNotice(handEdited, flags.forbidHandEdits);
+    const paths = rest.slice(0, handEdited.length);
+    const footer = rest.slice(handEdited.length);
+    if (flags.forbidHandEdits) {
+      // A failure lists every path: truncating the list a build failed on hides the cause.
+      for (const line of [header!, ...paths, ...footer]) log.error(line);
+      return 1;
+    }
+    log.warn(header!);
+    warnCapped(paths, flags.limit, { structured });
+    for (const line of footer) log.warn(line);
+    return 0;
+  }
+
   // -- docs drift -------------------------------------------------------------
   // Gated on --docs. Runs `meta docs` into a temp dir and diffs the committed docs
   // tree. See lib/docs-drift.ts for the deliberate differences from --codegen: a byte
@@ -1683,6 +1708,30 @@ interface VerifyGateRow {
   ok: boolean;
 }
 
+/**
+ * The hand-edit report for `verify --codegen`: a header with the count, one indented line
+ * per path, then how to see an edit. Exported for its test.
+ *
+ * The recipe regenerates rather than diffing against `.gen-state`, because the snapshot
+ * BODIES are gitignored — on a fresh clone or a CI runner only the hashes exist, which
+ * prove a file was edited but cannot show the edit. Deleting a generated file and
+ * re-running `meta gen` re-emits its pristine generation; git then shows the difference.
+ */
+export function handEditNotice(paths: readonly string[], forbidden: boolean): string[] {
+  const header = forbidden
+    ? `meta verify — ${paths.length} generated file(s) carry hand edits, and --forbid-hand-edits is set:`
+    : `meta verify — ${paths.length} generated file(s) carry hand edits ` +
+      `(notice — 'meta gen' preserves them by design; does not fail the build — ` +
+      `pass --forbid-hand-edits to make it):`;
+  return [
+    header,
+    ...paths.map((p) => `  ${p}`),
+    "To see an edit: delete the file and run 'meta gen' (it re-emits the pristine generation), " +
+      "then 'git diff -R -- <file>' shows the edit and 'git checkout -- <file>' restores it" +
+      (forbidden ? "; to drop the edit, commit the regenerated file instead." : "."),
+  ];
+}
+
 /** The flag that selects each gate, for the "not run" note. `requirements` always runs. */
 const GATE_SELECTOR: Record<string, string> = {
   templates: "--templates",
@@ -1697,14 +1746,21 @@ const GATE_SELECTOR: Record<string, string> = {
  * One line naming every gate this run did NOT run, each with the flag that selects it —
  * undefined when every gate ran. Exported for its test.
  */
-export function notRunNote(gates: readonly VerifyGateRow[]): string | undefined {
+export function notRunNote(
+  gates: readonly VerifyGateRow[],
+  opts: { bare?: boolean } = {},
+): string | undefined {
   const skipped = gates.filter((g) => !g.ran);
   if (skipped.length === 0) return undefined;
   const named = skipped.map((g) => {
     const flag = GATE_SELECTOR[g.gate];
     return flag !== undefined ? `${g.gate} (${flag})` : g.gate;
   });
-  return `meta verify — not run: ${named.join(", ")}`;
+  const tail = opts.bare === true
+    ? " — a bare 'meta verify' runs only the template gate (plus the requirement ledger); " +
+      "name each gate to run it"
+    : "";
+  return `meta verify — not run: ${named.join(", ")}${tail}`;
 }
 
 /**

package/src/index.ts

@@ -270,6 +270,10 @@ FLAGS:
                         An <Entity>.names.ts artifact is the exception: it must match a
                         fresh regen exactly — a hand edit in it is itself the defect.
                         Needs metaobjects.config.ts; exit 2 if absent.
+                        Every generated file that carries a hand edit is still LISTED
+                        (a notice, exit code unchanged), so an edit is never invisible.
+  --forbid-hand-edits   With --codegen: fail (exit 1) on ANY hand edit inside generated
+                        code, for teams that want generated files untouchable.
   --docs                Docs drift — run 'meta docs' to a temp dir and diff docs.outDir
                         Needs metaobjects.config.ts; exit 2 if absent. A page the
                         project GIT-IGNORES is exempt (docs.outDir is a directory, not

package/src/lib/args.ts

@@ -279,6 +279,14 @@ export interface VerifyFlags {
   templates: boolean;
   /** Run the codegen-drift gate: is the GENERATED contribution of each file current? */
   codegen: boolean;
+  /**
+   * With `--codegen`: fail the build on any hand edit inside a generated file, for teams
+   * that want generated code untouchable. Off by default, because hand edits are the
+   * documented workflow (`meta gen` three-way-merges them) — without it they are
+   * reported as a notice and never change the exit code. Refused without `--codegen`:
+   * it modifies that gate and would otherwise parse cleanly and do nothing.
+   */
+  forbidHandEdits: boolean;
   /**
    * Run the docs-drift gate: regenerate the `meta docs` surfaces into a temp dir and diff
    * them against the committed docs tree.
@@ -370,6 +378,7 @@ export const VERIFY_OPTIONS = {
   "skip-schema": { type: "boolean", default: false },
   templates: { type: "boolean", default: false },
   codegen: { type: "boolean", default: false },
+  "forbid-hand-edits": { type: "boolean", default: false },
   docs: { type: "boolean", default: false },
   deps: { type: "boolean", default: false },
   replay: { type: "boolean", default: false },
@@ -427,6 +436,12 @@ export function parseVerifyArgs(argv: string[]): VerifyFlags {
 
   const templates = !!values.templates;
   const codegen = !!values.codegen;
+  const forbidHandEdits = !!values["forbid-hand-edits"];
+  if (forbidHandEdits && !codegen) {
+    throw new Error(
+      "--forbid-hand-edits only applies to the codegen gate. Run: meta verify --codegen --forbid-hand-edits",
+    );
+  }
   const docs = !!values.docs;
   const deps = !!values.deps;
   const replay = !!values.replay;
@@ -448,6 +463,7 @@ export function parseVerifyArgs(argv: string[]): VerifyFlags {
     skipSchema: !!values["skip-schema"],
     templates,
     codegen,
+    forbidHandEdits,
     docs,
     deps,
     replay,

package/src/lib/catalog-listing.ts

@@ -77,6 +77,9 @@ export interface GeneratorCatalogRow {
     wouldEmit: number | null;
     /** Why `wouldEmit` is null despite --probe. Absent when it is a number. */
     probeError?: string;
+    /** Config keys this project leaves unset that the generator needs before `meta gen`
+     *  can run it. `wouldEmit` was counted with a placeholder for each. Absent when none. */
+    needsConfig?: string[];
   };
 }
 
@@ -164,7 +167,17 @@ export interface CatalogProject {
 export interface CatalogListingOpts {
   project?: CatalogProject;
   /** Run every generator in memory and report a real file count. Needs `project` + `metadata`. */
-  probe?: { metadata: MetaData; scope?: (fqn: string) => boolean };
+  probe?: {
+    metadata: MetaData;
+    scope?: (fqn: string) => boolean;
+    /**
+     * The collection's OWN source files — the same list `meta gen` threads onto
+     * `ctx.sourceFiles`. `shared-model` loads them standalone to build its artifact, so
+     * without them the probe asked it to publish nothing and reported the refusal as
+     * "probe failed" on every fresh project, for a generator that would in fact run.
+     */
+    sourceFiles?: readonly string[];
+  };
 }
 
 /**
@@ -180,21 +193,46 @@ async function probeOne(
   project: CatalogProject,
   metadata: MetaData,
   scope: ((fqn: string) => boolean) | undefined,
-): Promise<{ count: number } | { error: string }> {
-  try {
+  sourceFiles: readonly string[] | undefined,
+): Promise<{ count: number; needsConfig?: string[] } | { error: string }> {
+  const count = async (config: MetaobjectsGenConfig): Promise<number> => {
     const result = await runGen({
-      config: { ...project.config, generators: [entry.factory()] },
+      config: { ...config, generators: [entry.factory()] },
       metadata,
       projectRoot: project.projectRoot,
       dryRun: true,
       ...(scope !== undefined ? { scope } : {}),
+      ...(sourceFiles !== undefined ? { sourceFiles } : {}),
     });
-    return { count: result.files.length };
+    return result.files.length;
+  };
+  try {
+    return { count: await count(project.config) };
   } catch (err) {
+    // A generator that emits `import { db } from …` (the Fastify `routes`, `queries`)
+    // refuses to run while `dbImport` is unset — which it is in a freshly initialised
+    // project, exactly when `--probe` is being asked "what would this emit?". The path
+    // changes one import line, never the file count, so count with a placeholder and
+    // report the key as needed rather than dropping the count: the listing used to show
+    // `routes … [fastify]` beside `routes-hono … [hono, would emit 3]` with no reason.
+    // Only a retry that SUCCEEDS with the key supplied attributes the failure to it.
+    if (project.config.dbImport === undefined) {
+      try {
+        return {
+          count: await count({ ...project.config, dbImport: PROBE_DB_IMPORT_PLACEHOLDER }),
+          needsConfig: ["dbImport"],
+        };
+      } catch {
+        // Fall through: the original error is the one worth reporting.
+      }
+    }
     return { error: (err as Error).message };
   }
 }
 
+/** Stand-in `dbImport` for a probe. Never written anywhere — `dryRun` touches no file. */
+const PROBE_DB_IMPORT_PLACEHOLDER = "./db";
+
 // ---------------------------------------------------------------------------
 // the listing
 // ---------------------------------------------------------------------------
@@ -241,10 +279,19 @@ export async function buildCatalogListing(opts: CatalogListingOpts = {}): Promis
 
       let wouldEmit: number | null = null;
       let probeError: string | undefined;
+      let needsConfig: string[] | undefined;
       if (opts.probe !== undefined) {
-        const outcome = await probeOne(entry, project, opts.probe.metadata, opts.probe.scope);
-        if ("count" in outcome) wouldEmit = outcome.count;
-        else probeError = outcome.error;
+        const outcome = await probeOne(
+          entry,
+          project,
+          opts.probe.metadata,
+          opts.probe.scope,
+          opts.probe.sourceFiles,
+        );
+        if ("count" in outcome) {
+          wouldEmit = outcome.count;
+          needsConfig = outcome.needsConfig;
+        } else probeError = outcome.error;
       }
 
       row.project = {
@@ -252,6 +299,7 @@ export async function buildCatalogListing(opts: CatalogListingOpts = {}): Promis
         frameworkDetected,
         wouldEmit,
         ...(probeError !== undefined ? { probeError } : {}),
+        ...(needsConfig !== undefined ? { needsConfig } : {}),
       };
     }
 
@@ -361,7 +409,16 @@ export function renderCatalogText(rows: CatalogRow[], probed: boolean): string {
     if (r.project?.wired) marks.push("WIRED");
     if (r.source.owned) marks.push("owned");
     if (probed && r.project?.wouldEmit !== null && r.project?.wouldEmit !== undefined) {
-      marks.push(`would emit ${r.project.wouldEmit}`);
+      const needs = r.project.needsConfig;
+      marks.push(
+        needs !== undefined && needs.length > 0
+          ? `would emit ${r.project.wouldEmit} once ${needs.join(", ")} is set`
+          : `would emit ${r.project.wouldEmit}`,
+      );
+    } else if (probed && r.project?.probeError !== undefined) {
+      // Say that the probe could not count it, not nothing: a missing count read as
+      // "emits nothing" beside a sibling that showed one.
+      marks.push("probe failed — see --format json");
     }
     const suffix = marks.length > 0 ? `  [${marks.join(", ")}]` : "";
     lines.push(`  ${r.name.padEnd(width)}  —  ${r.description}${suffix}`);

package/src/lib/codegen-drift.ts

@@ -68,6 +68,16 @@ export interface CodegenDriftResult {
    * to end. Two doors asking one question must not answer it twice.
    */
   handEditedNames: string[];
+  /**
+   * Project-relative paths of generated files that carry a PRESERVED hand edit, sorted:
+   * the generated contribution is current (a fresh regen hashes to what we recorded
+   * writing) but the committed file differs from it. Not drift — `meta gen` keeps these
+   * edits by design — so they never set `clean` to false. Reported so the edits are
+   * VISIBLE: a validator weakened inside a generated file used to pass this gate in
+   * silence. The command decides whether they fail the build (`--forbid-hand-edits`).
+   * Never overlaps `driftedFiles`.
+   */
+  handEdited: string[];
   /** Set when the gate could not run (e.g. no outDir to compare against). */
   error?: string;
 }
@@ -138,6 +148,7 @@ export async function computeCodegenDrift(
       driftedFiles: [],
       lines: [],
       handEditedNames: [],
+      handEdited: [],
       error:
         "verify --codegen: no outDir configured — cannot locate the committed " +
         "generated output to diff against. Set 'outDir' (and/or per-target " +
@@ -207,6 +218,7 @@ export async function computeCodegenDrift(
     const driftedFiles = new Set<string>();
     const lines: string[] = [];
     const handEditedNames = new Set<string>();
+    const handEdited = new Set<string>();
 
     // Whether we have any record of what we wrote here. With records, the orphan
     // branch below can scope itself to our own output; with none, it cannot tell
@@ -286,6 +298,10 @@ export async function computeCodegenDrift(
               // nothing is proven, so the old byte verdict stands.
               driftedFiles.add(relKey);
               lines.push(`~ ${relKey} (committed content differs from a fresh regen)`);
+            } else {
+              // The generated contribution is current and the bytes still differ: a
+              // hand edit `meta gen` preserved. Not drift, but never silent either.
+              handEdited.add(relKey);
             }
           }
         }
@@ -298,6 +314,7 @@ export async function computeCodegenDrift(
       driftedFiles: sorted,
       lines,
       handEditedNames: [...handEditedNames].sort(),
+      handEdited: [...handEdited].sort(),
     };
   } finally {
     rmSync(tempRoot, { recursive: true, force: true });

package/src/lib/config.ts

@@ -82,6 +82,20 @@ async function tryLoadConfig(metaRoot: string): Promise<Config | undefined> {
 // Public resolvers
 // ---------------------------------------------------------------------------
 
+/**
+ * The migrations directory and dialect `meta migrate` would use with no flags — what
+ * `meta gen` needs to word its "now migrate" next step and find the committed snapshot.
+ */
+export async function resolveMigrateDefaults(
+  metaRoot: string,
+): Promise<{ outDir: string; dialect: Dialect | undefined }> {
+  const config = await tryLoadConfig(metaRoot);
+  return {
+    outDir: config?.migrate?.outDir ?? MIGRATE_DEFAULTS.outDir,
+    dialect: config?.migrate?.dialect ?? MIGRATE_DEFAULTS.dialect,
+  };
+}
+
 export function resolveGenConfig(flags: GenFlags): ResolvedGenConfig {
   return { dryRun: flags.dryRun, entities: flags.entities };
 }