@nekostack/cli 1.0.0

package/dist/commands/schema/migrate/plan.js

@@ -0,0 +1,255 @@
+/**
+ * `neko schema migrate plan` command implementation (v0.8 Step 21).
+ *
+ * The diff-aware planner CLI surface. Mirrors `runMigrateList`'s
+ * pure / writer-injected discipline (Master plan Decision #1).
+ *
+ * Flow:
+ *
+ *   1. `walkWorkspace({ root })` — load every `*.schema.{ts,js}`.
+ *      Any per-file load failure → IO_ERROR.
+ *   2. `buildRegistry(walk.entries)` — index the schemas.
+ *      `duplicate_schema_id` → LOGICAL_FAILURE; any `integrity_error`
+ *      → INTEGRITY_ERROR.
+ *   3. `readMigrations({ root })` — load every `*.migration.ts`.
+ *      Any per-file load failure → IO_ERROR.
+ *   4. `buildMigrationRegistry(migrationWalk.entries)` — index the
+ *      migrations and parse each one's provenance.
+ *      `duplicate_migration` → LOGICAL_FAILURE; any `integrity_error`
+ *      → INTEGRITY_ERROR.
+ *   5. `planMigrationHandler({ schemaRegistry, migrationRegistry,
+ *      schemaId, fromVersion, toVersion })`. Failure-issue mapping:
+ *      - `migration_missing_endpoint`  → LOGICAL_FAILURE
+ *      - `migration_not_found`         → LOGICAL_FAILURE
+ *      - `migration_chain_broken`      → LOGICAL_FAILURE
+ *      - `migration_ambiguous_chain`   → LOGICAL_FAILURE
+ *   6. Format and write:
+ *      - `--json`  → one-line `{ plan: {...} }` to stdout
+ *      - default   → pretty paragraph distinguishing the four success
+ *                    shapes (no-change / over_specified /
+ *                    additive_no_migration / chain).
+ *   7. Return SUCCESS.
+ *
+ * **Pure.** No `process.exit`, no `console.*`, no direct
+ * `process.stdout` / `process.stderr` writes. Writers are injected.
+ *
+ * **`migration.transform` is NEVER invoked here.** The planner is
+ * structural — `diffNodes` + DFS chain enumeration. The v0.8
+ * INVARIANTS ("no apply, no transform execution") stay in force.
+ * Static-scan asserted by [`../../../../tests/commands/schema-migrate-plan.test.ts`](../../../../tests/commands/schema-migrate-plan.test.ts).
+ *
+ * **JSON output shape is locked.** The `MigrationEntry.migration`
+ * field — the live `AnyMigration` carrying the `transform` closure —
+ * is NEVER serialized (neither inside `chain` rows nor inside
+ * `notes[].migration` projections):
+ *
+ *     {
+ *       "plan": {
+ *         "schemaId":      "com.x.Tenant",
+ *         "fromVersion":   "1.0.0",
+ *         "toVersion":     "2.0.0",
+ *         "worstSeverity": "breaking" | "additive" | "cosmetic" | null,
+ *         "versionPath":   ["1.0.0", "1.5.0", "2.0.0"],
+ *         "notes": [
+ *           { "kind": "over_specified", "migration": { schemaId, fromVersion, toVersion,
+ *             sourcePath, fromIrHash, toIrHash, fromSourceHash, toSourceHash } },
+ *           { "kind": "additive_no_migration", "worstSeverity": "additive" }
+ *         ],
+ *         "chain": [
+ *           { "schemaId": "...", "fromVersion": "1.0.0", "toVersion": "1.5.0",
+ *             "sourcePath": "...", "fromIrHash": "sha256:...", "toIrHash": "sha256:...",
+ *             "fromSourceHash": "sha256:...", "toSourceHash": "sha256:..." },
+ *           …
+ *         ]
+ *       }
+ *     }
+ */
+import { buildMigrationRegistry, buildRegistry, planMigrationHandler, } from "@nekostack/schema/cli";
+import { EXIT_CODES } from "../../../exit-codes.js";
+import { formatJson } from "../../../formatters/json.js";
+import { formatIssuesPretty, formatLoadFailuresPretty, } from "../../../formatters/pretty.js";
+import { readMigrations } from "../../../loaders/read-migrations.js";
+import { walkWorkspace } from "../../../loaders/walk-workspace.js";
+function projectMigrationEntry(e) {
+    return {
+        schemaId: e.schemaId,
+        fromVersion: e.fromVersion,
+        toVersion: e.toVersion,
+        sourcePath: e.sourcePath,
+        fromIrHash: e.fromIrHash,
+        toIrHash: e.toIrHash,
+        fromSourceHash: e.fromSourceHash,
+        toSourceHash: e.toSourceHash,
+    };
+}
+function projectPlanNote(note) {
+    if (note.kind === "over_specified") {
+        return { kind: "over_specified", migration: projectMigrationEntry(note.migration) };
+    }
+    return { kind: "additive_no_migration", worstSeverity: note.worstSeverity };
+}
+function projectPlan(plan, opts) {
+    return {
+        schemaId: plan.schemaId,
+        fromVersion: opts.fromVersion,
+        toVersion: opts.toVersion,
+        worstSeverity: plan.worstSeverity,
+        versionPath: plan.versionPath,
+        notes: plan.notes.map(projectPlanNote),
+        chain: plan.chain.map(projectMigrationEntry),
+    };
+}
+// =============================================================================
+// Load-failure projection (strip `cause`)
+// =============================================================================
+function toSerializableLoadFailure(f) {
+    return { path: f.path, reason: f.reason, message: f.message };
+}
+// =============================================================================
+// Exit-code mapping for issue lists
+// =============================================================================
+/**
+ * `buildRegistry` / `buildMigrationRegistry` failure → exit code.
+ * Any `integrity_error` → INTEGRITY_ERROR; otherwise LOGICAL_FAILURE
+ * (covers `duplicate_schema_id` / `duplicate_migration`). Same rule
+ * as the v0.7 `runCheck` handler-failure mapping and Step 20's
+ * `runMigrateList`.
+ */
+function pickRegistryFailureExitCode(issues) {
+    for (const i of issues) {
+        if (i.code === "integrity_error")
+            return EXIT_CODES.INTEGRITY_ERROR;
+    }
+    return EXIT_CODES.LOGICAL_FAILURE;
+}
+/**
+ * `planMigrationHandler` failure → exit code. All four locked
+ * failure codes (`migration_missing_endpoint` / `migration_not_found`
+ * / `migration_chain_broken` / `migration_ambiguous_chain`) map to
+ * `LOGICAL_FAILURE`. Defensive fallback also returns LOGICAL_FAILURE
+ * — the v0.8 planner does not emit `integrity_error`.
+ */
+function pickPlannerFailureExitCode(_issues) {
+    return EXIT_CODES.LOGICAL_FAILURE;
+}
+// =============================================================================
+// Pretty formatter
+// =============================================================================
+function formatMigrationPlanPretty(plan, opts) {
+    const header = `Plan: ${plan.schemaId}  ${opts.fromVersion} → ${opts.toVersion}` +
+        `  (worstSeverity: ${plan.worstSeverity ?? "none"})`;
+    const lines = [header];
+    if (plan.chain.length === 0) {
+        if (plan.notes.length === 0) {
+            lines.push("  No migration needed — diff has no breaking or additive changes.");
+        }
+        else {
+            for (const note of plan.notes) {
+                if (note.kind === "over_specified") {
+                    lines.push(`  No migration needed — diff is cosmetic/none, but a migration is registered at \`${note.migration.sourcePath}\`. (over_specified)`);
+                }
+                else {
+                    lines.push(`  No migration registered — diff is additive (\`${note.worstSeverity}\`); a migration is optional. (additive_no_migration)`);
+                }
+            }
+        }
+    }
+    else {
+        lines.push(`  Chain (${plan.chain.length} hop${plan.chain.length === 1 ? "" : "s"}):`);
+        for (let i = 0; i < plan.chain.length; i++) {
+            const hop = plan.chain[i];
+            lines.push(`    ${i + 1}. ${hop.fromVersion} → ${hop.toVersion}  ${hop.sourcePath}`);
+        }
+        lines.push(`  Version path: ${plan.versionPath.join(" → ")}`);
+    }
+    return lines.join("\n") + "\n";
+}
+// =============================================================================
+// Public entry
+// =============================================================================
+export async function runMigratePlan(opts) {
+    // 1. Schema walk + load failures → IO_ERROR.
+    const walk = await walkWorkspace({ root: opts.root });
+    if (walk.failures.length > 0) {
+        if (opts.json) {
+            opts.stdout(formatJson({
+                failures: walk.failures.map(toSerializableLoadFailure),
+            }));
+        }
+        else {
+            opts.stderr(formatLoadFailuresPretty(walk.failures));
+        }
+        return EXIT_CODES.IO_ERROR;
+    }
+    // 2. Build the schema registry.
+    const reg = buildRegistry(walk.entries);
+    if (!reg.success) {
+        if (opts.json) {
+            opts.stdout(formatJson({ issues: reg.issues }));
+        }
+        else {
+            opts.stderr(formatIssuesPretty(reg.issues));
+        }
+        return pickRegistryFailureExitCode(reg.issues);
+    }
+    // 3. Migration walk + load failures → IO_ERROR.
+    const migWalk = await readMigrations({ root: opts.root });
+    if (migWalk.failures.length > 0) {
+        if (opts.json) {
+            opts.stdout(formatJson({
+                failures: migWalk.failures.map(toSerializableLoadFailure),
+            }));
+        }
+        else {
+            opts.stderr(formatLoadFailuresPretty(migWalk.failures, {
+                noun: { singular: "migration file", plural: "migration files" },
+            }));
+        }
+        return EXIT_CODES.IO_ERROR;
+    }
+    // 4. Build the migration registry.
+    const migReg = buildMigrationRegistry(migWalk.entries);
+    if (!migReg.success) {
+        if (opts.json) {
+            opts.stdout(formatJson({ issues: migReg.issues }));
+        }
+        else {
+            opts.stderr(formatIssuesPretty(migReg.issues));
+        }
+        return pickRegistryFailureExitCode(migReg.issues);
+    }
+    // 5. Dispatch to the planner.
+    const result = planMigrationHandler({
+        schemaRegistry: reg.data,
+        migrationRegistry: migReg.data,
+        schemaId: opts.schemaId,
+        fromVersion: opts.fromVersion,
+        toVersion: opts.toVersion,
+    });
+    if (!result.success) {
+        if (opts.json) {
+            opts.stdout(formatJson({ issues: result.issues }));
+        }
+        else {
+            opts.stderr(formatIssuesPretty(result.issues));
+        }
+        return pickPlannerFailureExitCode(result.issues);
+    }
+    // 6. Success.
+    if (opts.json) {
+        opts.stdout(formatJson({
+            plan: projectPlan(result.data, {
+                fromVersion: opts.fromVersion,
+                toVersion: opts.toVersion,
+            }),
+        }));
+    }
+    else {
+        opts.stdout(formatMigrationPlanPretty(result.data, {
+            fromVersion: opts.fromVersion,
+            toVersion: opts.toVersion,
+        }));
+    }
+    return EXIT_CODES.SUCCESS;
+}
+//# sourceMappingURL=plan.js.map

package/dist/commands/schema/migrate/plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../../../src/commands/schema/migrate/plan.ts"],"names":[],"mappings":"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"}

package/dist/commands/schema/migrate/stub.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `neko schema migrate stub` command implementation (v0.8 Step 23).
+ *
+ * The only v0.8 migrate verb that writes a file. Mirrors v0.7's
+ * `runGenerate` shape: the schema-side handler is pure and returns
+ * `{ suggestedPath, content }`; this command is responsible for the
+ * actual filesystem persistence. Master plan Decision #1 keeps the
+ * filesystem on the CLI side.
+ *
+ * Flow:
+ *
+ *   1. `walkWorkspace({ root })` — load every `*.schema.{ts,js}`.
+ *      Any per-file load failure → IO_ERROR.
+ *   2. `buildRegistry(walk.entries)` — index the schemas.
+ *      `duplicate_schema_id` → LOGICAL_FAILURE.
+ *   3. `stubMigrationHandler({ schemaRegistry, schemaId, fromVersion,
+ *      toVersion })` — generate the stub payload. Failure modes
+ *      surface as `migration_missing_endpoint` →
+ *      LOGICAL_FAILURE.
+ *   4. **Refuse to overwrite.** Unlike `runGenerate` (which clobbers
+ *      generated artifacts by default), `runMigrateStub` writes a
+ *      file that contains hand-authored code. If the destination
+ *      already exists, the command returns LOGICAL_FAILURE without
+ *      modifying it. Decision #5 of the v0.8 phase plan locks this
+ *      contract.
+ *   5. `mkdir -p` the destination's parent + `writeFile` the
+ *      stub content. Any thrown error (EACCES, ENOSPC, etc.) →
+ *      IO_ERROR.
+ *   6. Format and write:
+ *      - `--json` (success) → `{ stub: { schemaId, fromVersion,
+ *        toVersion, suggestedPath } }`. The `content` field is
+ *        deliberately omitted — machine consumers don't need the
+ *        full source body, and the file is already on disk.
+ *      - pretty → `Wrote stub: <suggestedPath>`.
+ *
+ * **Pure helpers + bounded I/O.** `mkdir` and `writeFile` (and a
+ * `stat` for the overwrite check) are the only `node:fs` calls.
+ * `process.exit`, `console.*`, and direct stdout/stderr writes are
+ * forbidden — static-scan asserted by
+ * [`../../../../tests/commands/schema-migrate-stub.test.ts`](../../../../tests/commands/schema-migrate-stub.test.ts).
+ *
+ * **No `migration.transform`.** The stub command doesn't even own
+ * a registry of authored migrations — only the schema registry. The
+ * `.transform(` pattern still appears as a forbidden token in the
+ * static scan so the v0.8 boundary stays enforced everywhere.
+ */
+import { type ExitCode } from "../../../exit-codes.js";
+export interface RunMigrateStubOptions {
+    readonly root: string;
+    readonly schemaId: string;
+    readonly fromVersion: string;
+    readonly toVersion: string;
+    readonly json: boolean;
+    readonly quiet: boolean;
+    readonly stdout: (s: string) => void;
+    readonly stderr: (s: string) => void;
+}
+export declare function runMigrateStub(opts: RunMigrateStubOptions): Promise<ExitCode>;
+//# sourceMappingURL=stub.d.ts.map

package/dist/commands/schema/migrate/stub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub.d.ts","sourceRoot":"","sources":["../../../../src/commands/schema/migrate/stub.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AASH,OAAO,EAAc,KAAK,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAanE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AA6BD,wBAAsB,cAAc,CAClC,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,QAAQ,CAAC,CA6EnB"}

package/dist/commands/schema/migrate/stub.js

@@ -0,0 +1,195 @@
+/**
+ * `neko schema migrate stub` command implementation (v0.8 Step 23).
+ *
+ * The only v0.8 migrate verb that writes a file. Mirrors v0.7's
+ * `runGenerate` shape: the schema-side handler is pure and returns
+ * `{ suggestedPath, content }`; this command is responsible for the
+ * actual filesystem persistence. Master plan Decision #1 keeps the
+ * filesystem on the CLI side.
+ *
+ * Flow:
+ *
+ *   1. `walkWorkspace({ root })` — load every `*.schema.{ts,js}`.
+ *      Any per-file load failure → IO_ERROR.
+ *   2. `buildRegistry(walk.entries)` — index the schemas.
+ *      `duplicate_schema_id` → LOGICAL_FAILURE.
+ *   3. `stubMigrationHandler({ schemaRegistry, schemaId, fromVersion,
+ *      toVersion })` — generate the stub payload. Failure modes
+ *      surface as `migration_missing_endpoint` →
+ *      LOGICAL_FAILURE.
+ *   4. **Refuse to overwrite.** Unlike `runGenerate` (which clobbers
+ *      generated artifacts by default), `runMigrateStub` writes a
+ *      file that contains hand-authored code. If the destination
+ *      already exists, the command returns LOGICAL_FAILURE without
+ *      modifying it. Decision #5 of the v0.8 phase plan locks this
+ *      contract.
+ *   5. `mkdir -p` the destination's parent + `writeFile` the
+ *      stub content. Any thrown error (EACCES, ENOSPC, etc.) →
+ *      IO_ERROR.
+ *   6. Format and write:
+ *      - `--json` (success) → `{ stub: { schemaId, fromVersion,
+ *        toVersion, suggestedPath } }`. The `content` field is
+ *        deliberately omitted — machine consumers don't need the
+ *        full source body, and the file is already on disk.
+ *      - pretty → `Wrote stub: <suggestedPath>`.
+ *
+ * **Pure helpers + bounded I/O.** `mkdir` and `writeFile` (and a
+ * `stat` for the overwrite check) are the only `node:fs` calls.
+ * `process.exit`, `console.*`, and direct stdout/stderr writes are
+ * forbidden — static-scan asserted by
+ * [`../../../../tests/commands/schema-migrate-stub.test.ts`](../../../../tests/commands/schema-migrate-stub.test.ts).
+ *
+ * **No `migration.transform`.** The stub command doesn't even own
+ * a registry of authored migrations — only the schema registry. The
+ * `.transform(` pattern still appears as a forbidden token in the
+ * static scan so the v0.8 boundary stays enforced everywhere.
+ */
+import { dirname, isAbsolute, resolve, sep } from "node:path";
+import { mkdir, stat, writeFile } from "node:fs/promises";
+import { buildRegistry, stubMigrationHandler, } from "@nekostack/schema/cli";
+import { EXIT_CODES } from "../../../exit-codes.js";
+import { formatJson } from "../../../formatters/json.js";
+import { formatIssuesPretty, formatLoadFailuresPretty, } from "../../../formatters/pretty.js";
+import { walkWorkspace } from "../../../loaders/walk-workspace.js";
+// =============================================================================
+// Public entry
+// =============================================================================
+export async function runMigrateStub(opts) {
+    // 1. Schema walk + load failures → IO_ERROR.
+    const walk = await walkWorkspace({ root: opts.root });
+    if (walk.failures.length > 0) {
+        writeLoadFailures(opts, walk.failures);
+        return EXIT_CODES.IO_ERROR;
+    }
+    // 2. Build the schema registry.
+    const reg = buildRegistry(walk.entries);
+    if (!reg.success) {
+        writeIssues(opts, reg.issues);
+        return pickRegistryFailureExitCode(reg.issues);
+    }
+    // 3. Plan the stub. Failures (e.g., `migration_missing_endpoint`)
+    //    surface as `LOGICAL_FAILURE`.
+    const result = stubMigrationHandler({
+        schemaRegistry: reg.data,
+        schemaId: opts.schemaId,
+        fromVersion: opts.fromVersion,
+        toVersion: opts.toVersion,
+    });
+    if (!result.success) {
+        writeIssues(opts, result.issues);
+        return EXIT_CODES.LOGICAL_FAILURE;
+    }
+    const stub = result.data;
+    const rootAbs = isAbsolute(opts.root) ? opts.root : resolve(opts.root);
+    const destAbs = resolve(rootAbs, stub.suggestedPath.split("/").join(sep));
+    // 4. Refuse to overwrite. The destination is hand-authored migration
+    //    code; clobbering it would silently destroy the author's work.
+    if (await pathExists(destAbs)) {
+        const failure = {
+            path: stub.suggestedPath,
+            reason: "stub_path_exists",
+            message: `Refusing to overwrite existing file at \`${stub.suggestedPath}\`. ` +
+                `Move or delete it first, or pick a different (from, to) pair.`,
+        };
+        writeLocalFailures(opts, [failure]);
+        return EXIT_CODES.LOGICAL_FAILURE;
+    }
+    // 5. Persist. `mkdir -p` + `writeFile` may throw on I/O errors
+    //    (EACCES, ENOSPC, etc.); surface those as IO_ERROR.
+    try {
+        await mkdir(dirname(destAbs), { recursive: true });
+        await writeFile(destAbs, stub.content, "utf8");
+    }
+    catch (cause) {
+        const failure = {
+            path: stub.suggestedPath,
+            reason: "stub_write_failed",
+            message: errorMessageOf(cause),
+        };
+        writeLocalFailures(opts, [failure]);
+        return EXIT_CODES.IO_ERROR;
+    }
+    // 6. Success — emit the locked machine-readable shape (no `content`).
+    if (opts.json) {
+        opts.stdout(formatJson({
+            stub: {
+                schemaId: stub.schemaId,
+                fromVersion: stub.fromVersion,
+                toVersion: stub.toVersion,
+                suggestedPath: stub.suggestedPath,
+            },
+        }));
+    }
+    else {
+        opts.stdout(`Wrote stub: ${stub.suggestedPath}\n`);
+    }
+    return EXIT_CODES.SUCCESS;
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+async function pathExists(abs) {
+    try {
+        await stat(abs);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function errorMessageOf(err) {
+    if (err instanceof Error)
+        return err.message;
+    if (typeof err === "string")
+        return err;
+    try {
+        return JSON.stringify(err);
+    }
+    catch {
+        return String(err);
+    }
+}
+/**
+ * Pick exit code for `buildRegistry` failure. Same mapping as
+ * `runMigratePlan` / `runMigrateVerify`.
+ */
+function pickRegistryFailureExitCode(issues) {
+    for (const i of issues) {
+        if (i.code === "integrity_error")
+            return EXIT_CODES.INTEGRITY_ERROR;
+    }
+    return EXIT_CODES.LOGICAL_FAILURE;
+}
+function writeLoadFailures(opts, failures) {
+    if (opts.json) {
+        opts.stdout(formatJson({
+            failures: failures.map((f) => ({
+                path: f.path,
+                reason: f.reason,
+                message: f.message,
+            })),
+        }));
+    }
+    else {
+        opts.stderr(formatLoadFailuresPretty(failures));
+    }
+}
+function writeIssues(opts, issues) {
+    if (opts.json) {
+        opts.stdout(formatJson({ issues }));
+    }
+    else {
+        opts.stderr(formatIssuesPretty(issues));
+    }
+}
+function writeLocalFailures(opts, failures) {
+    if (opts.json) {
+        opts.stdout(formatJson({ failures }));
+    }
+    else {
+        const header = failures.length === 1 ? "Stub failed:" : "Stub failed:";
+        const lines = failures.map((f) => `  [${f.reason}] ${f.path} — ${f.message}`);
+        opts.stderr([header, ...lines].join("\n") + "\n");
+    }
+}
+//# sourceMappingURL=stub.js.map

package/dist/commands/schema/migrate/stub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub.js","sourceRoot":"","sources":["../../../../src/commands/schema/migrate/stub.ts"],"names":[],"mappings":"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"}

package/dist/commands/schema/migrate/verify.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `neko schema migrate verify` command implementation (v0.8 Step 22).
+ *
+ * Mirrors `runMigratePlan`'s pure / writer-injected discipline
+ * (Master plan Decision #1).
+ *
+ * Flow:
+ *
+ *   1. `walkWorkspace({ root })` — load every `*.schema.{ts,js}`.
+ *      Any per-file load failure → IO_ERROR.
+ *   2. `buildRegistry(walk.entries)` — index the schemas.
+ *      `duplicate_schema_id` → LOGICAL_FAILURE; `integrity_error` →
+ *      INTEGRITY_ERROR.
+ *   3. `readMigrations({ root })` — load every `*.migration.ts`.
+ *      Any per-file load failure → IO_ERROR.
+ *   4. `buildMigrationRegistry(migWalk.entries)` — index migrations
+ *      and parse each one's provenance. `duplicate_migration` →
+ *      LOGICAL_FAILURE; `integrity_error` → INTEGRITY_ERROR.
+ *   5. **CLI-side verdict derivation** — walk the migration registry
+ *      with the same classification rule as
+ *      `verifyMigrationProvenance` so the CLI can surface verdicts +
+ *      summary on BOTH the success and failure JSON branches. (The
+ *      schema-side handler discards verdicts on failure; the v0.8
+ *      verify-CLI contract requires them on both branches.)
+ *   6. `verifyMigrationsHandler({ schemaRegistry, migrationRegistry })`
+ *      — gets the official success/failure determination and any
+ *      `migration_drift` / `migration_missing_endpoint` issues.
+ *   7. Format and write:
+ *      - `--json` (success) → `{ verdicts, summary }`
+ *      - `--json` (failure) → `{ verdicts, summary, issues }`
+ *      - pretty → summary header + per-verdict rows
+ *   8. Exit-code mapping:
+ *      - any drift / missing_endpoint → LOGICAL_FAILURE
+ *      - only bound / cosmetic_drift (or empty registry) → SUCCESS
+ *
+ * **Pure.** No `process.exit`, no `console.*`, no direct
+ * `process.stdout` / `process.stderr` writes. Writers are injected.
+ *
+ * **`migration.transform` is NEVER invoked here.** Verification is
+ * provenance-only (the v0.8 INVARIANTS contract). Static-scan
+ * asserted by [`../../../../tests/commands/schema-migrate-verify.test.ts`](../../../../tests/commands/schema-migrate-verify.test.ts).
+ *
+ * **JSON output never serializes `MigrationEntry.migration` or its
+ * `transform` closure.** Verdicts are already shaped as
+ * `{ status, schemaId, fromVersion, toVersion, sourcePath }` per the
+ * `MigrationVerdict` type — no migration reference — so the projection
+ * is the identity. Issue records likewise carry only structured
+ * metadata.
+ */
+import { type ExitCode } from "../../../exit-codes.js";
+export interface RunMigrateVerifyOptions {
+    readonly root: string;
+    readonly json: boolean;
+    readonly quiet: boolean;
+    readonly stdout: (s: string) => void;
+    readonly stderr: (s: string) => void;
+}
+export declare function runMigrateVerify(opts: RunMigrateVerifyOptions): Promise<ExitCode>;
+//# sourceMappingURL=verify.d.ts.map

package/dist/commands/schema/migrate/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../../src/commands/schema/migrate/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAeH,OAAO,EAAc,KAAK,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAcnE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AA+KD,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,uBAAuB,GAC5B,OAAO,CAAC,QAAQ,CAAC,CA+FnB"}