@metaobjectsdev/cli 1.0.13 → 1.1.0

package/src/commands/migrate.ts

@@ -5,14 +5,14 @@ import { spawn } from "node:child_process";
 import { parseMigrateArgs } from "../lib/args.js";
 import { resolveMigrateConfig, MIGRATE_DEFAULT_OUT_DIR } from "../lib/config.js";
 import type { ResolvedMigrateConfig } from "../lib/config.js";
-import { formatMigrateResult, formatMigrateResultToon, type BlockedEntry, type AmbiguousEntry } from "../lib/output.js";
+import { formatMigrateResult, formatMigrateResultToon, type BlockedEntry, type AmbiguousEntry, type MigrateResultShape, migrateResultToData } from "../lib/output.js";
 import { formatMigrateResultJson } from "../lib/output-json.js";
 import type { OutputFormat } from "../lib/format.js";
-import { toonEncode } from "../lib/format.js";
-import { buildKyselyFromUrl, redactUrl } from "../lib/kysely.js";
+import { emitStructured, narrate, toonEncode } from "../lib/format.js";
+import { buildKyselyFromUrl, inferDialect, redactUrl } from "../lib/kysely.js";
 import { log } from "../lib/log.js";
 import { loadMemory, resolveCollection, resolveConfigDir, type Collection } from "@metaobjectsdev/sdk";
-import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
+import { loadMemoryOptionsFrom, loadMetaobjectsConfig, RemovedNamingConfigError, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
 import { collectionLoadOptions } from "../lib/collection-load-options.js";
 import { exclusionNotes, importedOption, migrateScopeMismatch } from "../lib/migrate-scope.js";
 import {
@@ -39,6 +39,7 @@ import {
   writeMigrationD1,
   writeMigrationFlyway,
   introspectD1,
+  withoutFlywayHistory,
   applyPending,
   rollbackTo,
   findWranglerConfig,
@@ -54,6 +55,7 @@ import {
   type SchemaProvenance,
   type SchemaSnapshot,
   type TableDescriptor,
+  postgresViewReplaceProbe,
 } from "@metaobjectsdev/migrate-ts";
 import {
   buildWranglerExecuteArgs,
@@ -61,8 +63,9 @@ import {
   type WranglerRunner,
 } from "../lib/wrangler.js";
 import { buildProjectionViews } from "@metaobjectsdev/codegen-ts";
-import { tokensToAllowOptions, blockedEntriesFor, blockedHintLines } from "../lib/allow.js";
+import { tokensToAllowOptions, blockedEntriesFor, blockedHintLines, viewRecreateNote } from "../lib/allow.js";
 import { reportLoadError } from "../lib/load-error.js";
+import { decimalPrecisionWarnings } from "../lib/decimal-precision-advisory.js";
 import { scanForReferentialActionConflicts } from "../lib/referential-action-advisory.js";
 import type { MetaData } from "@metaobjectsdev/metadata";
 import { describeError } from "../lib/error-text.js";
@@ -104,7 +107,7 @@ MIGRATE FLAGS:
                        .metaobjects/config.json.
   --out-dir <path>     Migration directory (default: ./.metaobjects/migrations;
                        flyway: src/main/resources/db/migration)
-  --slug <name>        Required when changes are present (e.g., --slug add-user-shipping)
+  --slug <name>        Required to WRITE a migration (not for --dry-run) (e.g., --slug add-user-shipping)
   --allow <csv>        Comma-separated destructive-change permissions:
                        drop-column,drop-table,type-change,drop-index,drop-fk,
                        drop-check,drop-view,drop-view-cascade,
@@ -135,7 +138,7 @@ MIGRATE FLAGS:
   --d1 <binding>       D1 binding name from wrangler.toml (only with --dialect d1)
   --remote             Target remote D1 instead of local (only with --dialect d1)
   --yes                Skip the --remote --apply confirmation pause
-  --dry-run            Print SQL to stdout, don't write
+  --dry-run            Print the SQL, don't write (json/toon: in the document's sql field)
   --help, -h           Print this help
 
 EXAMPLES:
@@ -234,10 +237,39 @@ function logOutOfScope(
   fromDependencies: readonly string[],
   fmt: OutputFormat,
 ): void {
-  for (const msg of exclusionNotes("migrate", names, fromDependencies)) {
-    if (fmt === "text") log.info(msg);
-    else log.warn(msg);
-  }
+  for (const msg of exclusionNotes("migrate", names, fromDependencies)) narrate(fmt, msg);
+}
+
+/**
+ * End a migrate path that reports in prose. Text format prints the lines on stdout as it
+ * always has. A structured format sends the same lines to STDERR and puts exactly ONE
+ * document on stdout — `doc` — so `--format json | jq` always has something to parse
+ * and never a sentence in front of it (the rule `logOutOfScope` states above).
+ */
+function finishMigrate(fmt: OutputFormat, lines: readonly string[], doc: Record<string, unknown>): void {
+  for (const line of lines) narrate(fmt, line);
+  if (fmt !== "text") emitStructured(doc, fmt);
+}
+
+/** The result fields both the offline and the d1 pipeline report when they have none of their own. */
+function migrateResultDefaults(dryRun: boolean): Pick<MigrateResultShape, "blocked" | "ambiguous" | "writtenPaths" | "dryRun"> {
+  return { blocked: [], ambiguous: [], writtenPaths: [], dryRun };
+}
+
+/** `viewRecreateNote` as the `notes` list a result carries: empty when there is nothing to say. */
+function viewRecreateNotes(changes: Change[]): string[] {
+  const note = viewRecreateNote(changes);
+  return note === undefined ? [] : [note];
+}
+
+/** A result's notes as prose lines, for the paths that report through `finishMigrate`. */
+function narratedNotes(notes: readonly string[]): string[] {
+  return notes.map((n) => `migrate: ${n}`);
+}
+
+/** The `-- UP -- / -- DOWN --` preview a dry run prints in text format. */
+function sqlPreview(sql: { up: string; down: string }): string {
+  return `-- UP --\n${sql.up}\n\n-- DOWN --\n${sql.down}`;
 }
 
 /**
@@ -256,6 +288,13 @@ function warnReferentialActionConflicts(metadata: MetaData, collection: Collecti
   for (const f of findings) log.warn(`migrate: ${f.message}`);
 }
 
+/** W4 (ADR-0019 Amendment 1): warn once per wide decimal on a dialect that keeps 15 digits. */
+function warnDecimalPrecision(metadata: MetaData, collection: Collection, dialect: string): void {
+  for (const w of decimalPrecisionWarnings(metadata, dialect, { skip: collection.imported })) {
+    log.warn(`migrate: ${w}`);
+  }
+}
+
 function emitStructuredError(error: string, hint: string, fmt: OutputFormat): void {
   const payload = { error, hint };
   if (fmt === "json") {
@@ -369,15 +408,19 @@ function nextStepsDetail(dialect: string | undefined): string {
 }
 
 /** Table count of the target DB, or undefined when it can't be reached/introspected
- *  (any failure ⇒ unknown ⇒ never block; the caller warns instead of refusing). */
+ *  (any failure ⇒ unknown ⇒ never block; the caller warns instead of refusing). Under the
+ *  flyway format Flyway's own history table is not counted: a database that holds only that
+ *  table has none of the project's tables. */
 async function countLiveTables(
   url: string,
   dialect: ResolvedMigrateConfig["dialect"],
+  format: ResolvedMigrateConfig["format"],
 ): Promise<number | undefined> {
   try {
     const kysely = await buildKyselyFromUrl(url, dialect);
     try {
-      return (await introspect(kysely.db, kysely.dialect)).tables.length;
+      const live = await introspect(kysely.db, kysely.dialect);
+      return (format === "flyway" ? withoutFlywayHistory(live) : live).tables.length;
     } finally {
       await kysely.close();
     }
@@ -509,14 +552,14 @@ export async function migrateCommand(
   // this run — the same directory `resolveCollection` resolves the metadata
   // from, found the same way (design §4.6.1: "Per-port generator config is then
   // read from that same directory"). Everything below is relative to it: the
-  // `.metaobjects/config.json` operational block, `metaobjects.config.ts`'s
-  // `columnNamingStrategy`, the migrations `outDir`, `wrangler.toml` discovery.
+  // `.metaobjects/config.json` operational block and its `naming` (ADR-0058), the
+  // migrations `outDir`, `wrangler.toml` discovery.
   //
   // Read from ambient cwd instead, as this did, they DIVERGE the moment the two
   // differ: run `meta migrate` from a subdirectory of a project whose root
-  // declares `columnNamingStrategy: "literal"` and the metadata resolves from
-  // the ancestor while the strategy silently defaults to snake_case — emitting a
-  // migration that renames every column. Newly reachable, too: before metadata
+  // declares literal column naming and the metadata resolves from the ancestor
+  // while the rule silently defaults to snake_case — emitting a migration that
+  // renames every column. Newly reachable, too: before metadata
   // sources were resolvable that invocation just failed with "no metaobjects/
   // found".
   //
@@ -532,10 +575,8 @@ export async function migrateCommand(
   // answers a different question from `.metaobjects/config.json` (design §4.6 —
   // per-port "how is code generated here?" versus port-neutral "where does metadata
   // come from?"), and in a Maven- or pip-rooted monorepo the two legitimately sit in
-  // different directories. Reading it from `metaRoot` there silently defaults
-  // `columnNamingStrategy` for a package that declares one — the exact
-  // rename-every-column failure the co-location was introduced to prevent, arrived
-  // at from the other side (#326). Nearest wins, so a subdirectory declaring nothing
+  // different directories. Reading it from `metaRoot` there silently drops the
+  // providers and libraries a package declares (#326). Nearest wins, so a subdirectory declaring nothing
   // still walks up to the project root's config; identical to `metaRoot` in every
   // `meta init` project, where the two files sit together.
   const genRoot = resolveGenConfigDir(cwd, metaRoot);
@@ -671,16 +712,20 @@ export async function migrateCommand(
   // every applied migration NEWER than <target> (target retained), in reverse
   // order, ledger-tracked + advisory-locked. postgres/sqlite only.
   if (config.rollback !== undefined) {
-    return await runRollback(config, metaRoot);
+    return await runRollback(config, metaRoot, fmt);
   }
 
   // Best-effort load of metaobjects.config.ts to pick up consumer-supplied
-  // providers. migrate's postgres/sqlite path also reads the config later
-  // for columnNamingStrategy; we load it once here and reuse below.
+  // providers. Column naming is not read here: it is `naming` in
+  // `.metaobjects/config.json`, set on the loaded root (ADR-0058).
   let postgresLoadOptions: ReturnType<typeof loadMemoryOptionsFrom> = {};
   try {
     postgresLoadOptions = loadMemoryOptionsFrom(await loadMetaobjectsConfig(genRoot));
-  } catch {
+  } catch (e) {
+    if (e instanceof RemovedNamingConfigError) {
+      log.error(e.message);
+      return 2;
+    }
     postgresLoadOptions = {};
   }
 
@@ -705,7 +750,7 @@ export async function migrateCommand(
     });
   } catch (err) {
     reportLoadError(log, "failed to load metadata", err);
-    return 2;
+    return 1;
   }
   warnReferentialActionConflicts(metadata, collection);
 
@@ -716,9 +761,13 @@ export async function migrateCommand(
     log.error(`migrate: ${describeError(err)}`);
     return 2;
   }
+  warnDecimalPrecision(metadata, collection, kysely.dialect);
 
   let exitCode = 0;
   let writtenPaths: string[] = [];
+  /** A dry run's SQL: printed in text format, carried in the document otherwise. */
+  let dryRunSql: { up: string; down: string } | undefined;
+  const notes: string[] = [];
   let appliedNames: string[] = [];
   let applyFailed = false;
   let blocked: BlockedEntry[] = [];
@@ -727,23 +776,16 @@ export async function migrateCommand(
   let changeCounts: Record<string, number> = {};
 
   try {
-    // Column-naming strategy (from metaobjects.config) drives BOTH the table schema
-    // and projection view DDL — derive it once, up front, so every view path agrees.
-    let columnNamingStrategy: "snake_case" | "literal" | "kebab-case" = "snake_case";
-    try {
-      const cfg = await loadMetaobjectsConfig(genRoot);
-      if (cfg.columnNamingStrategy) columnNamingStrategy = cfg.columnNamingStrategy;
-    } catch {
-      // metaobjects.config.ts absent or invalid — use default snake_case
-    }
+    // Column naming (ADR-0058: `naming` in .metaobjects/config.json, carried by the loaded
+    // root) drives BOTH the table schema and projection view DDL — read it once, up front,
+    // so every view path agrees. A config.ts still setting the 1.0 key is refused, loudly.
     // Expected views from the SINGLE view-SQL source (codegen-ts emitViewDdl, via
     // buildProjectionViews). Threaded into the schema-diff so the diff produces all
     // view DDL (create/drop/replace + dependency-recreate) and emit() renders it —
     // there is no separate view-migration emitter.
-    const expectedViews = buildProjectionViews(metadata, { dialect: kysely.dialect, columnNamingStrategy });
+    const expectedViews = buildProjectionViews(metadata, { dialect: kysely.dialect });
     const built = buildExpectedSchemaWithProvenance(metadata, {
       dialect: kysely.dialect,
-      columnNamingStrategy,
       views: expectedViews,
     });
     const scopeRc = refuseScopeMismatch(collection, () => built.provenance, fmt);
@@ -758,6 +800,8 @@ export async function migrateCommand(
     let actual;
     try {
       actual = await introspect(kysely.db, kysely.dialect);
+      // Flyway owns its history table; diffing it proposes DROP TABLE flyway_schema_history.
+      if (config.format === "flyway") actual = withoutFlywayHistory(actual);
     } catch (err) {
       log.error(`migrate: failed to connect to ${kysely.displayUrl}: ${describeError(err)}`);
       await kysely.close();
@@ -778,6 +822,9 @@ export async function migrateCommand(
         ...scopedDiffInputs(scoped, collectUnmanagedNames(metadata)),
         actual,
         dialect: kysely.dialect,
+        // Postgres decides whether a changed view can be replaced in place: the probe
+        // creates the new definition as a temporary view in a transaction it rolls back.
+        ...(kysely.dialect === "postgres" ? { viewReplaceProbe: postgresViewReplaceProbe(kysely.db) } : {}),
         allow: tokensToAllowOptions(config.allow),
         renames: config.renames,
         // #258 — adopting a live DB whose PRIMARY KEY differs from the metadata identity
@@ -876,6 +923,7 @@ export async function migrateCommand(
     if (diffResult.changes.length === 0) {
       // no-op — output will say "No schema changes"
     } else {
+      notes.push(...viewRecreateNotes(diffResult.changes));
       let emitted: EmitResult | undefined;
       try {
         emitted = emit(diffResult.changes, {
@@ -894,23 +942,30 @@ 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;
-        }
-
+        notes.push(...(emitted.notices ?? []));
         if (config.dryRun) {
-          log.info(`-- UP --\n${emitted.up}\n\n-- DOWN --\n${emitted.down}`);
+          dryRunSql = { up: emitted.up, down: emitted.down };
+          if (fmt === "text") log.info(sqlPreview(dryRunSql));
         } else {
+          // A preview names no migration; only a write needs the slug.
+          if (config.slug === undefined) {
+            log.error(`migrate: --slug <name> required when there are changes (e.g., --slug add-user-shipping)`);
+            emitStructuredError(
+              "migrate: --slug <name> required when there are changes",
+              "re-run with --slug <name>; for a new database whose migrations are already committed, run `meta migrate apply-pending --db <url>`",
+              fmt,
+            );
+            // 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;
+          }
           const outDir = resolveFormatOutDir(config, metaRoot);
           await mkdir(outDir, { recursive: true });
           // #192 — only the envelope differs; the emitted SQL is identical.
@@ -1025,6 +1080,8 @@ export async function migrateCommand(
     applied: appliedNames,
     applyFailed,
     warnings: hazardWarnings,
+    notes,
+    ...(dryRunSql !== undefined ? { sql: dryRunSql } : {}),
   };
   const output =
     fmt === "toon" ? formatMigrateResultToon(migrateResult)
@@ -1033,10 +1090,12 @@ export async function migrateCommand(
 
   log.info(output);
   if (config.apply && exitCode === 0) {
+    // The document's summary already says what was applied; this line is narration,
+    // so a structured run sends it to stderr rather than after the document.
     if (appliedNames.length > 0) {
-      log.info(`migrate: applied ${appliedNames.length} migration(s): ${appliedNames.join(", ")}`);
+      narrate(fmt, `migrate: applied ${appliedNames.length} migration(s): ${appliedNames.join(", ")}`);
     } else {
-      log.info(`migrate: no pending migrations to apply`);
+      narrate(fmt, `migrate: no pending migrations to apply`);
     }
   }
   return exitCode;
@@ -1090,6 +1149,7 @@ export async function runBaseline(
     }
     try {
       snapshot = await introspect(kysely.db, kysely.dialect);
+      if (config.format === "flyway") snapshot = withoutFlywayHistory(snapshot);
     } finally {
       await kysely.close();
     }
@@ -1102,7 +1162,7 @@ export async function runBaseline(
     // couldn't reach — we still write the snapshot but WARN: an offline baseline is
     // only correct when the database already matches the metadata, and emits no DDL.
     const liveTableCount = config.databaseUrl !== undefined
-      ? await countLiveTables(config.databaseUrl, config.dialect)
+      ? await countLiveTables(config.databaseUrl, config.dialect, config.format)
       : undefined;
     if (liveTableCount === 0) {
       // `liveTableCount === 0` ⇒ databaseUrl was defined (countLiveTables only
@@ -1122,16 +1182,18 @@ export async function runBaseline(
       `your metadata; for a new/empty database run \`${greenfieldCreateCmd(config.dialect)}\` instead.`,
     );
     let metadata;
-    // Load metaobjects.config.ts ONCE, up front, for BOTH the consumer providers/libraries
-    // and the columnNamingStrategy — mirroring the DB path (and `meta gen`) so
-    // offline baseline resolves config-registered custom subtypes too (#157).
+    // Load metaobjects.config.ts ONCE, up front, for the consumer providers/libraries —
+    // mirroring the DB path (and `meta gen`) so offline baseline resolves
+    // config-registered custom subtypes too (#157).
     let baselineLoadOptions: ReturnType<typeof loadMemoryOptionsFrom> = {};
-    let baselineStrategy: "snake_case" | "literal" | "kebab-case" = "snake_case";
     try {
       const cfg = await loadMetaobjectsConfig(genRoot);
       baselineLoadOptions = loadMemoryOptionsFrom(cfg);
-      if (cfg.columnNamingStrategy) baselineStrategy = cfg.columnNamingStrategy;
-    } catch {
+    } catch (e) {
+      if (e instanceof RemovedNamingConfigError) {
+        log.error(e.message);
+        return 2;
+      }
       // config absent — no custom providers, no libraries, default snake_case
     }
     // `baseline` records a STARTING POINT, so it is deliberately NOT scoped: the
@@ -1151,19 +1213,23 @@ export async function runBaseline(
       });
     } catch (err) {
       reportLoadError(log, "migrate baseline: failed to load metadata", err);
-      return 2;
+      return 1;
     }
-    const baselineViews = buildProjectionViews(metadata, { dialect: config.dialect, columnNamingStrategy: baselineStrategy });
-    snapshot = baselineFromMetadata(metadata, config.dialect, baselineStrategy, baselineViews);
+    const baselineViews = buildProjectionViews(metadata, { dialect: config.dialect });
+    snapshot = baselineFromMetadata(metadata, config.dialect, baselineViews);
   }
 
   if (config.dryRun) {
-    log.info(`migrate baseline (dry-run): would write schema snapshot ${path}`);
+    finishMigrate(fmt, [`migrate baseline (dry-run): would write schema snapshot ${path}`], {
+      snapshot: path, written: [], summary: "baseline preview only (nothing written)", help: ["re-run without --dry-run to write the snapshot"],
+    });
     return 0;
   }
 
   await writeSnapshot(path, snapshot);
-  log.info(`migrate: wrote schema snapshot ${path}`);
+  finishMigrate(fmt, [`migrate: wrote schema snapshot ${path}`], {
+    snapshot: path, written: [path], summary: "wrote schema snapshot", help: ["commit the snapshot; later runs diff against it"],
+  });
   return 0;
 }
 
@@ -1263,20 +1329,40 @@ export async function runOfflineGenerate(
    *  `genRoot`. Defaults to `metaRoot`, the co-located case. */
   genRoot: string = metaRoot,
 ): Promise<number> {
+  // `--dialect` is optional wherever a URL is known: the offline path reads the
+  // committed snapshot rather than the database, but `--db` (or DATABASE_URL /
+  // migrate.databaseUrl) still names which dialect that snapshot is for. The help has
+  // always said "auto-detected from URL scheme"; this path used to refuse instead.
+  if (config.dialect === undefined && config.databaseUrl !== undefined) {
+    try {
+      config = { ...config, dialect: inferDialect(config.databaseUrl) };
+    } catch (err) {
+      log.error(`migrate: ${describeError(err)}`);
+      emitStructuredError(`migrate: ${describeError(err)}`, "pass --dialect sqlite|postgres|d1", fmt);
+      return 2;
+    }
+  }
   if (config.dialect === undefined) {
-    log.error(`migrate: --dialect required for offline generation (or use --from-db)`);
+    log.error(`migrate: --dialect required for offline generation — pass --dialect sqlite|postgres, or --db <url> to infer it (or use --from-db)`);
+    emitStructuredError(
+      "migrate: --dialect required for offline generation",
+      "pass --dialect sqlite|postgres, or --db <url> to infer it from the URL scheme",
+      fmt,
+    );
     return 2;
   }
-  // Load metaobjects.config.ts ONCE, up front, for BOTH the consumer providers/libraries
-  // and the columnNamingStrategy — mirroring the DB path (and `meta gen`) so
-  // offline generate resolves config-registered custom subtypes too (#157).
+  // Load metaobjects.config.ts ONCE, up front, for the consumer providers/libraries —
+  // mirroring the DB path (and `meta gen`) so offline generate resolves
+  // config-registered custom subtypes too (#157).
   let offlineLoadOptions: ReturnType<typeof loadMemoryOptionsFrom> = {};
-  let offlineStrategy: "snake_case" | "literal" | "kebab-case" = "snake_case";
   try {
     const cfg = await loadMetaobjectsConfig(genRoot);
     offlineLoadOptions = loadMemoryOptionsFrom(cfg);
-    if (cfg.columnNamingStrategy) offlineStrategy = cfg.columnNamingStrategy;
-  } catch {
+  } catch (e) {
+    if (e instanceof RemovedNamingConfigError) {
+      log.error(e.message);
+      return 2;
+    }
     // config absent — no custom providers, no libraries, default snake_case
   }
 
@@ -1290,17 +1376,17 @@ export async function runOfflineGenerate(
     });
   } catch (err) {
     reportLoadError(log, "migrate: failed to load metadata", err);
-    return 2;
+    return 1;
   }
   warnReferentialActionConflicts(metadata, collection);
+  warnDecimalPrecision(metadata, collection, config.dialect);
 
   const offlineDialect = config.dialect;
-  const offlineViews = buildProjectionViews(metadata, { dialect: offlineDialect, columnNamingStrategy: offlineStrategy });
+  const offlineViews = buildProjectionViews(metadata, { dialect: offlineDialect });
   const scopeRc = refuseScopeMismatch(
     collection,
     () => buildExpectedSchemaWithProvenance(metadata, {
       dialect: offlineDialect,
-      columnNamingStrategy: offlineStrategy,
       views: offlineViews,
     }).provenance,
     fmt,
@@ -1330,6 +1416,7 @@ export async function runOfflineGenerate(
     emitStructuredError("no schema snapshot", nextStepsDetail(config.dialect), fmt);
     return 2;
   }
+  if (config.format === "flyway") snapshot = withoutFlywayHistory(snapshot);
 
   const collectedAmbiguous: AmbiguousChange[] = [];
   const onAmbiguousResolution = mapOnAmbiguous(config.onAmbiguous);
@@ -1342,7 +1429,6 @@ export async function runOfflineGenerate(
       metadata,
       dialect: config.dialect,
       snapshot,
-      columnNamingStrategy: offlineStrategy,
       views: offlineViews,
       // Per-command scope — narrows BOTH sides of the offline diff (see planOffline).
       ...(offlineScope !== undefined ? { inScope: offlineScope } : {}),
@@ -1374,19 +1460,27 @@ export async function runOfflineGenerate(
   const { diff: diffResult, nextSnapshot, expected: governedExpected } = plan;
   logOutOfScope(plan.outOfScope, plan.importedOutOfScope ?? [], fmt);
 
+  const offlineNotes = viewRecreateNotes(diffResult.changes);
+  const offlineResult = (extra: Partial<MigrateResultShape>): MigrateResultShape => ({
+    dialect: offlineDialect,
+    displayUrl: "",
+    changeCounts: summarizeChanges(diffResult.changes),
+    ...migrateResultDefaults(config.dryRun),
+    format: config.format,
+    notes: offlineNotes,
+    ...extra,
+  });
   if (diffResult.blocked.length > 0) {
-    logBlocked(blockedEntriesFor(diffResult.blocked, diffResult.changes));
+    const blocked = blockedEntriesFor(diffResult.blocked, diffResult.changes);
+    logBlocked(blocked);
+    if (fmt !== "text") emitStructured(migrateResultToData(offlineResult({ blocked })), fmt);
     return 1;
   }
   if (diffResult.changes.length === 0) {
-    log.info(`migrate: no changes`);
+    finishMigrate(fmt, [`migrate: no changes`], migrateResultToData(offlineResult({})));
     return 0;
   }
-  if (config.slug === undefined) {
-    log.error(`migrate: --slug <name> required when there are changes (e.g., --slug add-user-shipping)`);
-    return 2;
-  }
-  warnDataHazards(diffResult.hazards);
+  const offlineWarnings = warnDataHazards(diffResult.hazards);
 
   const emitResult = emit(diffResult.changes, {
     dialect: config.dialect,
@@ -1395,11 +1489,26 @@ export async function runOfflineGenerate(
     ...(snapshot.meta ? { actualMeta: snapshot.meta } : {}),
   });
 
+  // The emitter's own notices (e.g. a view dropped and recreated, its grants carried over).
+  offlineNotes.push(...(emitResult.notices ?? []));
+
   if (config.dryRun) {
-    log.info(`-- UP --\n${emitResult.up}\n\n-- DOWN --\n${emitResult.down}`);
+    const sql = { up: emitResult.up, down: emitResult.down };
+    finishMigrate(
+      fmt,
+      [...narratedNotes(offlineNotes), sqlPreview(sql)],
+      migrateResultToData(offlineResult({ sql, warnings: offlineWarnings })),
+    );
     return 0;
   }
 
+  // A preview (above) names no migration; only a write needs the slug.
+  if (config.slug === undefined) {
+    log.error(`migrate: --slug <name> required when there are changes (e.g., --slug add-user-shipping)`);
+    emitStructuredError("migrate: --slug <name> required when there are changes", "re-run with --slug <name>", fmt);
+    return 2;
+  }
+
   // #192 — the MIGRATION FILES follow the active format's layout, while the
   // snapshot stays in `outDir` (it is metaobjects' own state). With the default
   // out-dir that separates them: snapshot in .metaobjects/migrations/, migrations
@@ -1417,8 +1526,11 @@ export async function runOfflineGenerate(
         { dir: writeDir, slug: config.slug },
       );
   await writeSnapshot(path, nextSnapshot);
-  log.info(`migrate: wrote ${res.upPath}`);
-  log.info(`migrate: wrote ${res.downPath}`);
+  finishMigrate(
+    fmt,
+    [`migrate: wrote ${res.upPath}`, `migrate: wrote ${res.downPath}`, ...narratedNotes(offlineNotes)],
+    migrateResultToData(offlineResult({ writtenPaths: [res.upPath, res.downPath], warnings: offlineWarnings })),
+  );
   return 0;
 }
 
@@ -1432,6 +1544,7 @@ export async function runOfflineGenerate(
 async function runRollback(
   config: ResolvedMigrateConfig,
   metaRoot: string,
+  fmt: OutputFormat,
 ): Promise<number> {
   // databaseUrl is guaranteed defined by the caller's guard above.
   const databaseUrl = config.databaseUrl as string;
@@ -1459,11 +1572,10 @@ async function runRollback(
 
   try {
     const result = await rollbackTo(kysely.db, outDir, target, { dialect });
-    if (result.rolledBack.length > 0) {
-      log.info(`migrate: rolled back ${result.rolledBack.length} migration(s): ${result.rolledBack.join(", ")}`);
-    } else {
-      log.info(`migrate: nothing to roll back${target ? ` newer than '${target}'` : ""}`);
-    }
+    const summary = result.rolledBack.length > 0
+      ? `rolled back ${result.rolledBack.length} migration(s): ${result.rolledBack.join(", ")}`
+      : `nothing to roll back${target ? ` newer than '${target}'` : ""}`;
+    finishMigrate(fmt, [`migrate: ${summary}`], { rolledBack: result.rolledBack, summary });
     return 0;
   } catch (err) {
     log.error(`migrate: rollback failed: ${describeError(err)}`);
@@ -1537,7 +1649,11 @@ async function runD1Migrate(
   let d1LoadOptions: ReturnType<typeof loadMemoryOptionsFrom> = {};
   try {
     d1LoadOptions = loadMemoryOptionsFrom(await loadMetaobjectsConfig(genRoot));
-  } catch {
+  } catch (e) {
+    if (e instanceof RemovedNamingConfigError) {
+      log.error(e.message);
+      return 2;
+    }
     d1LoadOptions = {};
   }
 
@@ -1560,20 +1676,14 @@ async function runD1Migrate(
     });
   } catch (err) {
     reportLoadError(log, "migrate: failed to load metadata", err);
-    return 2;
+    return 1;
   }
   warnReferentialActionConflicts(metadata, collection);
+  warnDecimalPrecision(metadata, collection, "d1");
 
   // 4. Build expected schema + introspect actual.
-  let columnNamingStrategy: "snake_case" | "literal" | "kebab-case" = "snake_case";
-  try {
-    const cfg = await loadMetaobjectsConfig(genRoot);
-    if (cfg.columnNamingStrategy) columnNamingStrategy = cfg.columnNamingStrategy;
-  } catch {
-    // metaobjects.config.ts absent or invalid — use default snake_case
-  }
-  const expectedViews = buildProjectionViews(metadata, { dialect: "d1", columnNamingStrategy });
-  const built = buildExpectedSchemaWithProvenance(metadata, { dialect: "d1", columnNamingStrategy, views: expectedViews });
+  const expectedViews = buildProjectionViews(metadata, { dialect: "d1" });
+  const built = buildExpectedSchemaWithProvenance(metadata, { dialect: "d1", views: expectedViews });
   const scopeRc = refuseScopeMismatch(collection, () => built.provenance, fmt);
   if (scopeRc !== undefined) return scopeRc;
   // Per-command scope — both-sided, exactly as on the Kysely path above.
@@ -1634,6 +1744,7 @@ async function runD1Migrate(
   }
 
   const changeCounts = summarizeChanges(diffResult.changes);
+  const d1Notes = viewRecreateNotes(diffResult.changes);
   warnDataHazards(diffResult.hazards);
 
   // Views are emitted by the one schema-diff path: renderD1 = renderSqlite (which
@@ -1641,16 +1752,20 @@ async function runD1Migrate(
   // BEGIN/COMMIT + PRAGMA that recreate-and-copy emits). There is no separate
   // view-migration emitter; introspectD1 now reads view bodies so unchanged views
   // produce no change and body changes emit a DROP+CREATE.
+  const d1Result = (extra: Partial<MigrateResultShape>): MigrateResultShape => ({
+    dialect: "d1",
+    displayUrl: binding.binding,
+    changeCounts,
+    // No `format` key here on purpose: every d1 output this build ships was produced
+    // without it; adding it would change bytes the tests pin.
+    ...migrateResultDefaults(config.dryRun),
+    ...extra,
+  });
   if (diffResult.changes.length === 0) {
-    log.info(`migrate: no schema changes for d1 binding '${binding.binding}'`);
+    finishMigrate(fmt, [`migrate: no schema changes for d1 binding '${binding.binding}'`], migrateResultToData(d1Result({})));
     return 0;
   }
 
-  if (config.slug === undefined) {
-    log.error(`migrate: --slug <name> required when there are changes`);
-    return 2;
-  }
-
   // 6. Emit (with D1 safety pass) + write Wrangler migration files.
   let emitResult;
   try {
@@ -1663,6 +1778,7 @@ async function runD1Migrate(
     throw err;
   }
 
+  d1Notes.push(...(emitResult.notices ?? []));
   const combinedUp = emitResult.up;
   const combinedDown = emitResult.down;
 
@@ -1671,19 +1787,32 @@ async function runD1Migrate(
   const migrationsDir = resolveD1OutDir(config, metaRoot, binding.migrations_dir);
 
   if (config.dryRun) {
-    log.info(`-- UP --\n${combinedUp}\n\n-- DOWN --\n${combinedDown}`);
+    const sql = { up: combinedUp, down: combinedDown };
+    finishMigrate(fmt, [...narratedNotes(d1Notes), sqlPreview(sql)], migrateResultToData(d1Result({ sql, notes: d1Notes })));
     return 0;
   }
 
+  // A preview (above) names no migration; only a write needs the slug.
+  if (config.slug === undefined) {
+    log.error(`migrate: --slug <name> required when there are changes`);
+    emitStructuredError("migrate: --slug <name> required when there are changes", "re-run with --slug <name>", fmt);
+    return 2;
+  }
+
   const writeResult = await writeMigrationD1(
     { up: combinedUp, down: combinedDown },
     { dir: migrationsDir, slug: config.slug },
   );
-  log.info(`migrate: wrote ${writeResult.upPath}`);
-  log.info(`migrate: wrote ${writeResult.downPath}`);
-  for (const [kind, count] of Object.entries(changeCounts)) {
-    log.info(`  ${kind}: ${count}`);
-  }
+  finishMigrate(
+    fmt,
+    [
+      `migrate: wrote ${writeResult.upPath}`,
+      `migrate: wrote ${writeResult.downPath}`,
+      ...Object.entries(changeCounts).map(([kind, count]) => `  ${kind}: ${count}`),
+      ...narratedNotes(d1Notes),
+    ],
+    migrateResultToData(d1Result({ writtenPaths: [writeResult.upPath, writeResult.downPath], notes: d1Notes })),
+  );
 
   // 7. Optional --apply: run `wrangler d1 migrations apply`.
   if (config.d1.autoApply) {
@@ -1707,7 +1836,8 @@ async function runWranglerApply(
   yes: boolean,
 ): Promise<number> {
   if (remote && !yes) {
-    log.info(
+    // Progress, not output: stderr, so it never lands in front of a document on stdout.
+    log.warn(
       `Applying to remote D1 '${databaseName}' (binding=${bindingName}) in 2s — Ctrl+C to abort or pass --yes to skip this pause.`,
     );
     await new Promise<void>((r) => setTimeout(r, 2000));
@@ -1724,3 +1854,4 @@ async function runWranglerApply(
     child.on("close", (code) => resolve(code ?? 1));
   });
 }
+