@metaobjectsdev/cli 0.11.6 → 0.12.0-rc.1

package/dist/src/commands/migrate.js

@@ -3,7 +3,9 @@ import { mkdir } from "node:fs/promises";
 import { spawn } from "node:child_process";
 import { parseMigrateArgs } from "../lib/args.js";
 import { resolveMigrateConfig, MIGRATE_DEFAULT_OUT_DIR } from "../lib/config.js";
-import { formatMigrateResult } from "../lib/output.js";
+import { formatMigrateResult, formatMigrateResultToon } from "../lib/output.js";
+import { formatMigrateResultJson } from "../lib/output-json.js";
+import { toonEncode } from "../lib/format.js";
 import { buildKyselyFromUrl } from "../lib/kysely.js";
 import { log } from "../lib/log.js";
 import { loadMemory } from "@metaobjectsdev/sdk";
@@ -12,6 +14,64 @@ import { buildExpectedSchema, introspect, diff, emit, writeMigration, baselineFr
 import { buildWranglerExecuteArgs, defaultWranglerRunner, } from "../lib/wrangler.js";
 import { buildProjectionViews } from "@metaobjectsdev/codegen-ts";
 import { tokensToAllowOptions, describeChange } from "../lib/allow.js";
+const MIGRATE_HELP_TEXT = `meta migrate — diff metadata vs live DB; emit migration SQL files
+
+USAGE:
+  meta migrate [baseline] [flags]
+
+SUBCOMMANDS:
+  baseline             Seed the committed reference snapshot (no migration emitted).
+                       Required before the first offline generate.
+
+MIGRATE FLAGS:
+  --db <url>           DB connection URL (required for live-introspect / --apply / --rollback)
+                       Supports: file:, libsql:, postgres:, postgresql:
+  --dialect sqlite|postgres|d1
+                       Optional dialect override (auto-detected from URL scheme)
+  --out-dir <path>     Migration directory (default: ./.metaobjects/migrations)
+  --slug <name>        Required when changes are present (e.g., --slug add-user-shipping)
+  --allow <csv>        Comma-separated destructive-change permissions:
+                       drop-column,drop-table,type-change,drop-index,drop-fk,nullable-to-not-null
+  --on-ambiguous abort|rename|drop-add
+                       How to handle ambiguous renames (default: abort)
+  --from-db            Introspect live DB instead of using the committed snapshot
+  --apply              Run pending migration files against the DB after writing
+  --rollback <target>  Roll back applied migrations newer than <target>
+  --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
+  --help, -h           Print this help
+
+EXAMPLES:
+  meta migrate baseline --dialect sqlite
+  meta migrate --dialect sqlite --slug add-users
+  meta migrate --db file:local.db --slug add-orders
+  meta migrate --db postgresql://localhost/mydb --slug add-index --apply
+`;
+/** Emit a structured error on stdout (not stderr) in the active format, per axi. */
+function emitStructuredError(error, hint, fmt) {
+    const payload = { error, hint };
+    if (fmt === "json") {
+        log.info(JSON.stringify(payload, null, 2));
+    }
+    else if (fmt === "toon") {
+        log.info(toonEncode(payload));
+    }
+    // text format: errors go to stderr via log.error() — the caller handles that path
+}
+/**
+ * Sentinel thrown by sub-functions that have already emitted a structured error
+ * via emitStructuredError(). The top-level catch in migrateCommand re-throws
+ * this as-is without double-emitting.
+ */
+class AlreadyEmittedError extends Error {
+    exitCode;
+    constructor(exitCode) {
+        super("already-emitted");
+        this.exitCode = exitCode;
+    }
+}
 function mapOnAmbiguous(v) {
     return v === "drop-add" ? "drop+add" : v;
 }
@@ -58,264 +118,300 @@ function ambiguousToEntries(amb) {
 }
 export async function migrateCommand(args, cwd, 
 /** Injectable wrangler runner — tests pass a mock; production uses the default. */
-wranglerRunner) {
+wranglerRunner, fmt = "text") {
+    // Intercept --help / -h before parseMigrateArgs (parseArgs strict mode rejects them).
+    if (args.includes("--help") || args.includes("-h")) {
+        log.info(MIGRATE_HELP_TEXT);
+        return 0;
+    }
     let flags;
     try {
         flags = parseMigrateArgs(args);
     }
     catch (err) {
-        log.error(`migrate: ${err.message}`);
+        const msg = err.message;
+        log.error(`migrate: ${msg}`);
+        emitStructuredError(`migrate: ${msg}`, "run `meta migrate --help` for usage", fmt);
         return 2;
     }
     const metaRoot = cwd;
     const config = await resolveMigrateConfig(flags, metaRoot);
-    if (config.dialect === "d1") {
+    try {
+        if (config.dialect === "d1") {
+            if (config.baseline) {
+                log.error(`migrate baseline is not supported for dialect 'd1' (snapshots are a postgres/sqlite concept)`);
+                emitStructuredError(`migrate baseline is not supported for dialect 'd1'`, "drop 'baseline' for d1 — snapshots are a postgres/sqlite concept", fmt);
+                return 2;
+            }
+            if (config.databaseUrl !== undefined) {
+                log.error(`migrate: --db / DATABASE_URL is not used for dialect 'd1' — wrangler.toml owns connection`);
+                emitStructuredError(`migrate: --db / DATABASE_URL is not used for dialect 'd1'`, "remove --db / DATABASE_URL for d1 — wrangler.toml owns the connection", fmt);
+                return 2;
+            }
+            if (config.rollback !== undefined) {
+                log.error(`migrate: --rollback is not supported for dialect 'd1' (use 'wrangler d1 migrations' tooling)`);
+                emitStructuredError(`migrate: --rollback is not supported for dialect 'd1'`, "use 'wrangler d1 migrations' tooling to roll back d1", fmt);
+                return 2;
+            }
+            return await runD1Migrate(config, metaRoot, wranglerRunner ?? defaultWranglerRunner, fmt);
+        }
+        // `migrate baseline` — seed the committed reference snapshot, emit no migration.
         if (config.baseline) {
-            log.error(`migrate baseline is not supported for dialect 'd1' (snapshots are a postgres/sqlite concept)`);
-            return 2;
+            return await runBaseline(config, metaRoot, fmt);
+        }
+        // Default = offline snapshot generation. The live-introspection path runs only
+        // when explicitly requested via --from-db, when --apply needs a connection, or
+        // for --rollback (which runs hand-authored down.sql against the live DB).
+        if (!config.fromDb && !config.apply && config.rollback === undefined) {
+            return await runOfflineGenerate(config, metaRoot, fmt);
         }
-        if (config.databaseUrl !== undefined) {
-            log.error(`migrate: --db / DATABASE_URL is not used for dialect 'd1' — wrangler.toml owns connection`);
+        if (config.databaseUrl === undefined) {
+            log.error(`migrate: --db <url> required (or set DATABASE_URL, or add migrate.databaseUrl to .metaobjects/config.json)`);
+            emitStructuredError(`migrate: --db <url> required`, "pass --db <url>, set DATABASE_URL, or add migrate.databaseUrl to .metaobjects/config.json", fmt);
             return 2;
         }
+        // --rollback short-circuits the diff/emit pipeline: it runs the down.sql of
+        // every applied migration NEWER than <target> (target retained), in reverse
+        // order, ledger-tracked + advisory-locked. postgres/sqlite only.
         if (config.rollback !== undefined) {
-            log.error(`migrate: --rollback is not supported for dialect 'd1' (use 'wrangler d1 migrations' tooling)`);
-            return 2;
+            return await runRollback(config, metaRoot);
         }
-        return await runD1Migrate(config, metaRoot, wranglerRunner ?? defaultWranglerRunner);
-    }
-    // `migrate baseline` — seed the committed reference snapshot, emit no migration.
-    if (config.baseline) {
-        return await runBaseline(config, metaRoot);
-    }
-    // Default = offline snapshot generation. The live-introspection path runs only
-    // when explicitly requested via --from-db, when --apply needs a connection, or
-    // for --rollback (which runs hand-authored down.sql against the live DB).
-    if (!config.fromDb && !config.apply && config.rollback === undefined) {
-        return await runOfflineGenerate(config, metaRoot);
-    }
-    if (config.databaseUrl === undefined) {
-        log.error(`migrate: --db <url> required (or set DATABASE_URL, or add migrate.databaseUrl to .metaobjects/config.json)`);
-        return 2;
-    }
-    // --rollback short-circuits the diff/emit pipeline: it runs the down.sql of
-    // 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);
-    }
-    // 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.
-    let postgresConfigProviders;
-    try {
-        const forgeConfig = await loadMetaobjectsConfig(metaRoot);
-        postgresConfigProviders = forgeConfig.providers;
-    }
-    catch {
-        postgresConfigProviders = undefined;
-    }
-    let metadata;
-    try {
-        metadata = await loadMemory(metaRoot, {
-            ...(postgresConfigProviders !== undefined ? { providers: postgresConfigProviders } : {}),
-        });
-    }
-    catch (err) {
-        const msg = err.message;
-        if (msg.includes("ENOENT") || msg.includes("no such") || msg.includes("cannot read")) {
-            log.error(`no metaobjects/ found in ${metaRoot}; run 'meta init' to scaffold`);
+        // 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.
+        let postgresConfigProviders;
+        try {
+            const forgeConfig = await loadMetaobjectsConfig(metaRoot);
+            postgresConfigProviders = forgeConfig.providers;
         }
-        else {
-            log.error(`failed to load metadata: ${msg}`);
+        catch {
+            postgresConfigProviders = undefined;
         }
-        return 2;
-    }
-    let kysely;
-    try {
-        kysely = await buildKyselyFromUrl(config.databaseUrl, config.dialect);
-    }
-    catch (err) {
-        log.error(`migrate: ${err.message}`);
-        return 2;
-    }
-    let exitCode = 0;
-    let writtenPaths = [];
-    let appliedNames = [];
-    let blocked = [];
-    let ambiguous = [];
-    let changeCounts = {};
-    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";
+        let metadata;
         try {
-            const cfg = await loadMetaobjectsConfig(metaRoot);
-            if (cfg.columnNamingStrategy)
-                columnNamingStrategy = cfg.columnNamingStrategy;
+            metadata = await loadMemory(metaRoot, {
+                ...(postgresConfigProviders !== undefined ? { providers: postgresConfigProviders } : {}),
+            });
         }
-        catch {
-            // metaobjects.config.ts absent or invalid — use default snake_case
-        }
-        // 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 expected = buildExpectedSchema(metadata, {
-            dialect: kysely.dialect,
-            columnNamingStrategy,
-            views: expectedViews,
-        });
-        let actual;
+        catch (err) {
+            const msg = err.message;
+            if (msg.includes("ENOENT") || msg.includes("no such") || msg.includes("cannot read")) {
+                log.error(`no metaobjects/ found in ${metaRoot}; run 'meta init' to scaffold`);
+            }
+            else {
+                log.error(`failed to load metadata: ${msg}`);
+            }
+            return 2;
+        }
+        let kysely;
         try {
-            actual = await introspect(kysely.db, kysely.dialect);
+            kysely = await buildKyselyFromUrl(config.databaseUrl, config.dialect);
         }
         catch (err) {
-            log.error(`migrate: failed to connect to ${kysely.displayUrl}: ${err.message}`);
-            await kysely.close();
+            log.error(`migrate: ${err.message}`);
             return 2;
         }
-        const collectedAmbiguous = [];
-        const onAmbiguousResolution = mapOnAmbiguous(config.onAmbiguous);
-        let diffResult;
+        let exitCode = 0;
+        let writtenPaths = [];
+        let appliedNames = [];
+        let applyFailed = false;
+        let blocked = [];
+        let ambiguous = [];
+        let changeCounts = {};
         try {
-            diffResult = await diff({
-                expected,
-                actual,
+            // 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";
+            try {
+                const cfg = await loadMetaobjectsConfig(metaRoot);
+                if (cfg.columnNamingStrategy)
+                    columnNamingStrategy = cfg.columnNamingStrategy;
+            }
+            catch {
+                // metaobjects.config.ts absent or invalid — use default snake_case
+            }
+            // 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 expected = buildExpectedSchema(metadata, {
                 dialect: kysely.dialect,
-                allow: tokensToAllowOptions(config.allow),
-                onAmbiguous: async (a) => {
-                    collectedAmbiguous.push(a);
-                    return onAmbiguousResolution;
-                },
+                columnNamingStrategy,
+                views: expectedViews,
             });
-        }
-        catch (err) {
-            // diff() throws when onAmbiguous returns "abort" — surface as exit 1
-            // with the collected ambiguity list.
-            if (err.message.includes("aborted by onAmbiguous")) {
-                ambiguous = ambiguousToEntries(collectedAmbiguous);
-                const output = formatMigrateResult({
-                    dialect: kysely.dialect,
-                    displayUrl: kysely.displayUrl,
-                    changeCounts: {},
-                    blocked: [],
-                    ambiguous,
-                    writtenPaths: [],
-                    dryRun: config.dryRun,
-                }, { isTTY: !!process.stdout.isTTY });
-                log.info(output);
+            let actual;
+            try {
+                actual = await introspect(kysely.db, kysely.dialect);
+            }
+            catch (err) {
+                log.error(`migrate: failed to connect to ${kysely.displayUrl}: ${err.message}`);
                 await kysely.close();
-                return 1;
+                return 2;
             }
-            throw err;
-        }
-        changeCounts = summarizeChanges(diffResult.changes);
-        // All changes — tables AND views — are emitted by the one schema-diff path.
-        // View DDL (create/drop/replace) is produced by diff()'s view passes (2b body
-        // comparison, 2c dependency-recreate) and rendered by every dialect's emitter;
-        // STAGE_ORDER sequences drop-view before and create-view after any column change
-        // a view reads. There is no separate view-migration emitter, and unchanged views
-        // produce no change (introspect reads the actual body, diff compares it).
-        if (diffResult.changes.length === 0) {
-            // no-op — output will say "No schema changes"
-        }
-        else {
-            let emitted;
+            const collectedAmbiguous = [];
+            const onAmbiguousResolution = mapOnAmbiguous(config.onAmbiguous);
+            let diffResult;
             try {
-                emitted = emit(diffResult.changes, {
+                diffResult = await diff({
+                    expected,
+                    actual,
                     dialect: kysely.dialect,
-                    expectedSchema: expected,
-                    ...(actual.meta !== undefined ? { actualMeta: actual.meta } : {}),
+                    allow: tokensToAllowOptions(config.allow),
+                    onAmbiguous: async (a) => {
+                        collectedAmbiguous.push(a);
+                        return onAmbiguousResolution;
+                    },
                 });
             }
             catch (err) {
-                if (err instanceof BlockedChangesError) {
-                    blocked = blockedToEntries(err);
-                    exitCode = 1;
-                }
-                else {
-                    throw err;
+                // diff() throws when onAmbiguous returns "abort" — surface as exit 1
+                // with the collected ambiguity list.
+                if (err.message.includes("aborted by onAmbiguous")) {
+                    ambiguous = ambiguousToEntries(collectedAmbiguous);
+                    const migrateResult = {
+                        dialect: kysely.dialect,
+                        displayUrl: kysely.displayUrl,
+                        changeCounts: {},
+                        blocked: [],
+                        ambiguous,
+                        writtenPaths: [],
+                        dryRun: config.dryRun,
+                        applied: [],
+                        applyFailed: false,
+                    };
+                    const output = fmt === "toon" ? formatMigrateResultToon(migrateResult)
+                        : fmt === "json" ? formatMigrateResultJson(migrateResult)
+                            : formatMigrateResult(migrateResult, { isTTY: !!process.stdout.isTTY });
+                    log.info(output);
+                    await kysely.close();
+                    return 1;
                 }
+                throw err;
             }
-            if (exitCode === 0 && emitted) {
-                if (config.slug === undefined) {
-                    log.error(`migrate: --slug <name> required when there are changes (e.g., --slug add-user-shipping)`);
-                    await kysely.close();
-                    return 2;
+            changeCounts = summarizeChanges(diffResult.changes);
+            // All changes — tables AND views — are emitted by the one schema-diff path.
+            // View DDL (create/drop/replace) is produced by diff()'s view passes (2b body
+            // comparison, 2c dependency-recreate) and rendered by every dialect's emitter;
+            // STAGE_ORDER sequences drop-view before and create-view after any column change
+            // a view reads. There is no separate view-migration emitter, and unchanged views
+            // produce no change (introspect reads the actual body, diff compares it).
+            if (diffResult.changes.length === 0) {
+                // no-op — output will say "No schema changes"
+            }
+            else {
+                let emitted;
+                try {
+                    emitted = emit(diffResult.changes, {
+                        dialect: kysely.dialect,
+                        expectedSchema: expected,
+                        ...(actual.meta !== undefined ? { actualMeta: actual.meta } : {}),
+                    });
                 }
-                if (config.dryRun) {
-                    log.info(`-- UP --\n${emitted.up}\n\n-- DOWN --\n${emitted.down}`);
+                catch (err) {
+                    if (err instanceof BlockedChangesError) {
+                        blocked = blockedToEntries(err);
+                        exitCode = 1;
+                    }
+                    else {
+                        throw err;
+                    }
                 }
-                else {
-                    const outDir = resolvePath(metaRoot, config.outDir);
-                    await mkdir(outDir, { recursive: true });
-                    const res = await writeMigration({ up: emitted.up, down: emitted.down }, { dir: outDir, slug: config.slug });
-                    writtenPaths = [res.upPath, res.downPath];
-                    if (config.fromDb) {
-                        log.info(`migrate: --from-db did not advance the committed snapshot; run 'meta migrate baseline --from-db' to re-sync`);
+                if (exitCode === 0 && emitted) {
+                    if (config.slug === undefined) {
+                        log.error(`migrate: --slug <name> required when there are changes (e.g., --slug add-user-shipping)`);
+                        await kysely.close();
+                        return 2;
+                    }
+                    if (config.dryRun) {
+                        log.info(`-- UP --\n${emitted.up}\n\n-- DOWN --\n${emitted.down}`);
                     }
+                    else {
+                        const outDir = resolvePath(metaRoot, config.outDir);
+                        await mkdir(outDir, { recursive: true });
+                        const res = await writeMigration({ up: emitted.up, down: emitted.down }, { dir: outDir, slug: config.slug });
+                        writtenPaths = [res.upPath, res.downPath];
+                        if (config.fromDb) {
+                            log.info(`migrate: --from-db did not advance the committed snapshot; run 'meta migrate baseline --from-db' to re-sync`);
+                        }
+                    }
+                }
+            }
+            // --apply: run pending committed migration files against the DB, tracked by
+            // the migration-history ledger, transactionally. Idempotency comes from the
+            // ledger (skip already-applied), NOT from re-diffing — so this also applies
+            // any previously-written-but-unapplied files in this run. Skipped on dry-run
+            // and when a prior step set a non-zero exit (e.g. blocked changes).
+            if (config.apply && exitCode === 0 && !config.dryRun) {
+                const outDir = resolvePath(metaRoot, config.outDir);
+                try {
+                    // applyPending calls ensureLedger internally (idempotent), so no need
+                    // to ensure it here. Pass the dialect so postgres gets schema-qualified
+                    // ledger DDL + the session advisory lock (sqlite is a no-op there).
+                    const result = await applyPending(kysely.db, outDir, {
+                        dryRun: false,
+                        dialect: kysely.dialect,
+                    });
+                    appliedNames = [...result.applied];
+                }
+                catch (err) {
+                    log.error(`migrate: apply failed: ${err.message}`);
+                    exitCode = 1;
+                    applyFailed = true;
                 }
             }
         }
-        // --apply: run pending committed migration files against the DB, tracked by
-        // the migration-history ledger, transactionally. Idempotency comes from the
-        // ledger (skip already-applied), NOT from re-diffing — so this also applies
-        // any previously-written-but-unapplied files in this run. Skipped on dry-run
-        // and when a prior step set a non-zero exit (e.g. blocked changes).
-        if (config.apply && exitCode === 0 && !config.dryRun) {
-            const outDir = resolvePath(metaRoot, config.outDir);
+        finally {
             try {
-                // applyPending calls ensureLedger internally (idempotent), so no need
-                // to ensure it here. Pass the dialect so postgres gets schema-qualified
-                // ledger DDL + the session advisory lock (sqlite is a no-op there).
-                const result = await applyPending(kysely.db, outDir, {
-                    dryRun: false,
-                    dialect: kysely.dialect,
-                });
-                appliedNames = [...result.applied];
+                await kysely.close();
             }
             catch (err) {
-                log.error(`migrate: apply failed: ${err.message}`);
-                exitCode = 1;
+                log.warn(`migrate: failed to close DB cleanly: ${err.message}`);
             }
         }
-    }
-    finally {
-        try {
-            await kysely.close();
-        }
-        catch (err) {
-            log.warn(`migrate: failed to close DB cleanly: ${err.message}`);
+        const migrateResult = {
+            dialect: kysely.dialect,
+            displayUrl: kysely.displayUrl,
+            changeCounts,
+            blocked,
+            ambiguous,
+            writtenPaths,
+            dryRun: config.dryRun,
+            applied: appliedNames,
+            applyFailed,
+        };
+        const output = fmt === "toon" ? formatMigrateResultToon(migrateResult)
+            : fmt === "json" ? formatMigrateResultJson(migrateResult)
+                : formatMigrateResult(migrateResult, { isTTY: !!process.stdout.isTTY });
+        log.info(output);
+        if (config.apply && exitCode === 0) {
+            if (appliedNames.length > 0) {
+                log.info(`migrate: applied ${appliedNames.length} migration(s): ${appliedNames.join(", ")}`);
+            }
+            else {
+                log.info(`migrate: no pending migrations to apply`);
+            }
         }
+        return exitCode;
     }
-    const output = formatMigrateResult({
-        dialect: kysely.dialect,
-        displayUrl: kysely.displayUrl,
-        changeCounts,
-        blocked,
-        ambiguous,
-        writtenPaths,
-        dryRun: config.dryRun,
-    }, { isTTY: !!process.stdout.isTTY });
-    log.info(output);
-    if (config.apply && exitCode === 0) {
-        if (appliedNames.length > 0) {
-            log.info(`migrate: applied ${appliedNames.length} migration(s): ${appliedNames.join(", ")}`);
-        }
-        else {
-            log.info(`migrate: no pending migrations to apply`);
-        }
+    catch (err) {
+        // AlreadyEmittedError: sub-function already called emitStructuredError — just
+        // propagate the exit code without double-emitting.
+        if (err instanceof AlreadyEmittedError)
+            return err.exitCode;
+        // Unexpected error: emit structured error on stdout in the active format, then exit 1.
+        const msg = err.message ?? String(err);
+        log.error(`migrate: unexpected error: ${msg}`);
+        emitStructuredError(`migrate: unexpected error: ${msg}`, "run `meta migrate --help` for usage", fmt);
+        return 1;
     }
-    return exitCode;
 }
 /**
  * `meta migrate baseline [--from-db]` — seed the committed reference snapshot.
  * `--from-metadata` (default) derives it from metadata; `--from-db` introspects
  * an existing database once. Emits no migration.
  */
-export async function runBaseline(config, metaRoot) {
+export async function runBaseline(config, metaRoot, _fmt = "text") {
     if (config.dialect === undefined) {
         log.error(`migrate baseline: --dialect required (or set migrate.dialect in .metaobjects/config.json)`);
         return 2;
@@ -380,7 +476,7 @@ export async function runBaseline(config, metaRoot) {
  * Scope: table/column/index/FK changes. Projection-view migrations stay on the
  * introspection path (offline-view parity is a follow-up).
  */
-export async function runOfflineGenerate(config, metaRoot) {
+export async function runOfflineGenerate(config, metaRoot, fmt = "text") {
     if (config.dialect === undefined) {
         log.error(`migrate: --dialect required for offline generation (or use --from-db)`);
         return 2;
@@ -404,7 +500,9 @@ export async function runOfflineGenerate(config, metaRoot) {
         return 2;
     }
     if (snapshot === null) {
-        log.error(`migrate: no schema snapshot at ${path}; run 'meta migrate baseline' first`);
+        log.error(`migrate: no schema snapshot at ${path}; run \`meta migrate baseline --dialect ${config.dialect}\` first`);
+        // Structured next-step on stdout so callers / agents can parse it, in the active format.
+        emitStructuredError("no schema snapshot", `first run \`meta migrate baseline --dialect ${config.dialect}\``, fmt);
         return 2;
     }
     const collectedAmbiguous = [];
@@ -522,7 +620,7 @@ async function runRollback(config, metaRoot) {
         }
     }
 }
-async function runD1Migrate(config, metaRoot, runner) {
+async function runD1Migrate(config, metaRoot, runner, _fmt = "text") {
     // 1. Resolve wrangler.toml + binding.
     const wranglerConfigPath = config.d1.wranglerConfigPath
         ? resolvePath(metaRoot, config.d1.wranglerConfigPath)