@nekostack/cli 1.0.0

package/dist/commands/schema/list.js

@@ -0,0 +1,115 @@
+/**
+ * `neko schema list` command implementation (v0.7 Step 29).
+ *
+ * First fully-wired schema verb. Replaces the Step 25 placeholder.
+ * Flow:
+ *
+ *   1. `walkWorkspace({ root })` discovers and loads every
+ *      `*.schema.{ts,js}` file under `root`.
+ *   2. If any file failed to load → render failures, exit IO_ERROR.
+ *   3. `buildRegistry(entries)` indexes the loaded schemas.
+ *   4. If the build returned `duplicate_schema_id` Issues → render
+ *      issues, exit LOGICAL_FAILURE.
+ *   5. `listHandler({ registry })` enumerates entries in
+ *      schemaId-ascending order (unversioned last).
+ *   6. Format and write:
+ *      - `--json`  → one-line JSON `{ schemas: [...] }` to stdout
+ *      - default   → padded table to stdout via `formatListPretty`
+ *   7. Return SUCCESS.
+ *
+ * Pure: no `process.exit`, no `console.*`, no direct `process.stdout`
+ * / `process.stderr` writes. The caller (the commander action wired
+ * up in `cli.ts`) injects writers; tests pass collector functions.
+ *
+ * JSON output shape is locked here so machine consumers have a
+ * stable contract. The `schema` field of `RegistryEntry` (the live
+ * `Schema` instance) is deliberately NOT included — it's not
+ * JSON-serializable and not a useful identifier downstream.
+ *
+ *     {
+ *       "schemas": [
+ *         { "schemaId": "com.x.User", "schemaVersion": "1.0.0",
+ *           "sourcePath": "schemas/user.schema.ts",
+ *           "irHash": "sha256:...", "sourceHash": "sha256:..." },
+ *         …
+ *       ]
+ *     }
+ *
+ * Unversioned entries surface as `"schemaVersion": null` so the
+ * JSON shape stays uniform.
+ */
+import { buildRegistry, listHandler } from "@nekostack/schema/cli";
+import { EXIT_CODES } from "../../exit-codes.js";
+import { formatJson } from "../../formatters/json.js";
+import { formatIssuesPretty, formatListPretty, formatLoadFailuresPretty, } from "../../formatters/pretty.js";
+import { walkWorkspace } from "../../loaders/walk-workspace.js";
+/**
+ * Project a `LoadFailure` to a stable, JSON-safe shape. The
+ * underlying `LoadFailure.cause` is an `unknown` thrown by tsx /
+ * esbuild and may not serialize cleanly (or at all — circular
+ * references, function values, etc.). The CLI's `--json` contract
+ * for load failures is `{ path, reason, message }` only.
+ */
+function toSerializableLoadFailure(f) {
+    return { path: f.path, reason: f.reason, message: f.message };
+}
+export async function runList(opts) {
+    // 1. Walk the workspace and load every matching schema file.
+    const walk = await walkWorkspace({ root: opts.root });
+    // 2. Per-file load failures → IO_ERROR. Render before returning.
+    //    Failures are essential diagnostics; `--quiet` does not
+    //    suppress them per the audit guidance for Step 29.
+    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;
+    }
+    // 3. Build the in-memory registry. `buildRegistry` returns a
+    //    `Result` so duplicate-id collisions surface as `Issue[]`
+    //    rather than throws.
+    const reg = buildRegistry(walk.entries);
+    if (!reg.success) {
+        if (opts.json) {
+            opts.stdout(formatJson({ issues: reg.issues }));
+        }
+        else {
+            opts.stderr(formatIssuesPretty(reg.issues));
+        }
+        return EXIT_CODES.LOGICAL_FAILURE;
+    }
+    // 4. Enumerate. `listHandler` has no failure mode, but treat any
+    //    future failure defensively as LOGICAL_FAILURE.
+    const result = listHandler({ registry: reg.data });
+    if (!result.success) {
+        if (opts.json) {
+            opts.stdout(formatJson({ issues: result.issues }));
+        }
+        else {
+            opts.stderr(formatIssuesPretty(result.issues));
+        }
+        return EXIT_CODES.LOGICAL_FAILURE;
+    }
+    // 5. Success — write the entries in the chosen format.
+    if (opts.json) {
+        opts.stdout(formatJson({
+            schemas: result.data.entries.map((e) => ({
+                schemaId: e.schemaId,
+                schemaVersion: e.schemaVersion ?? null,
+                sourcePath: e.sourcePath,
+                irHash: e.irHash,
+                sourceHash: e.sourceHash,
+            })),
+        }));
+    }
+    else {
+        opts.stdout(formatListPretty(result.data.entries));
+    }
+    return EXIT_CODES.SUCCESS;
+}
+//# sourceMappingURL=list.js.map

package/dist/commands/schema/list.js.map

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

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

@@ -0,0 +1,65 @@
+/**
+ * `neko schema migrate list` command implementation (v0.8 Step 20).
+ *
+ * First fully-wired v0.8 verb. Mirrors the v0.7 `runList` shape exactly
+ * — same pure / writer-injected discipline (Master plan Decision #1).
+ *
+ * Flow:
+ *
+ *   1. `readMigrations({ root })` discovers and loads every
+ *      `*.migration.ts` file under `root`.
+ *   2. If any file failed to load → render failures, exit IO_ERROR.
+ *   3. `buildMigrationRegistry(entries)` indexes the loaded migrations
+ *      and parses each one's JSDoc provenance header.
+ *   4. If the build returned issues:
+ *      - any `integrity_error` → INTEGRITY_ERROR (4)
+ *      - otherwise (e.g., `duplicate_migration`) → LOGICAL_FAILURE (1)
+ *   5. `listMigrationsHandler({ migrationRegistry })` enumerates
+ *      entries in `(schemaId, fromVersion, toVersion)` ascending order.
+ *   6. Format and write:
+ *      - `--json`  → one-line JSON `{ migrations: [...] }` to stdout
+ *      - default   → padded table to stdout via `formatMigrationListPretty`
+ *   7. Return SUCCESS.
+ *
+ * **Pure.** No `process.exit`, no `console.*`, no direct
+ * `process.stdout` / `process.stderr` writes. The caller (the commander
+ * action wired up in `cli.ts` — landing in a later step) injects
+ * writers; tests pass collector functions.
+ *
+ * **`migration.transform` is NEVER invoked here.** The v0.8 boundary
+ * (INVARIANTS — "no apply, no transform execution") stays in force.
+ * Static-scan asserted by [`../../../../tests/commands/schema-migrate-list.test.ts`](../../../../tests/commands/schema-migrate-list.test.ts).
+ *
+ * JSON output shape is locked here so machine consumers have a stable
+ * contract. The `migration` field on `MigrationEntry` — the live
+ * `AnyMigration` carrying the `transform` closure — is deliberately
+ * NOT included; it's not JSON-serializable, not a useful downstream
+ * identifier, and touching it would tempt callers across the v0.8
+ * boundary.
+ *
+ *     {
+ *       "migrations": [
+ *         {
+ *           "schemaId":       "com.x.Tenant",
+ *           "fromVersion":    "1.0.0",
+ *           "toVersion":      "2.0.0",
+ *           "sourcePath":     "schemas/tenant.1-0-0-to-2-0-0.migration.ts",
+ *           "fromIrHash":     "sha256:...",
+ *           "toIrHash":       "sha256:...",
+ *           "fromSourceHash": "sha256:...",
+ *           "toSourceHash":   "sha256:..."
+ *         },
+ *         …
+ *       ]
+ *     }
+ */
+import { type ExitCode } from "../../../exit-codes.js";
+export interface RunMigrateListOptions {
+    readonly root: string;
+    readonly json: boolean;
+    readonly quiet: boolean;
+    readonly stdout: (s: string) => void;
+    readonly stderr: (s: string) => void;
+}
+export declare function runMigrateList(opts: RunMigrateListOptions): Promise<ExitCode>;
+//# sourceMappingURL=list.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../../src/commands/schema/migrate/list.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAIH,OAAO,EAAc,KAAK,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAoCnE,MAAM,WAAW,qBAAqB;IACpC,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;AAED,wBAAsB,cAAc,CAClC,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,QAAQ,CAAC,CAqEnB"}

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

@@ -0,0 +1,148 @@
+/**
+ * `neko schema migrate list` command implementation (v0.8 Step 20).
+ *
+ * First fully-wired v0.8 verb. Mirrors the v0.7 `runList` shape exactly
+ * — same pure / writer-injected discipline (Master plan Decision #1).
+ *
+ * Flow:
+ *
+ *   1. `readMigrations({ root })` discovers and loads every
+ *      `*.migration.ts` file under `root`.
+ *   2. If any file failed to load → render failures, exit IO_ERROR.
+ *   3. `buildMigrationRegistry(entries)` indexes the loaded migrations
+ *      and parses each one's JSDoc provenance header.
+ *   4. If the build returned issues:
+ *      - any `integrity_error` → INTEGRITY_ERROR (4)
+ *      - otherwise (e.g., `duplicate_migration`) → LOGICAL_FAILURE (1)
+ *   5. `listMigrationsHandler({ migrationRegistry })` enumerates
+ *      entries in `(schemaId, fromVersion, toVersion)` ascending order.
+ *   6. Format and write:
+ *      - `--json`  → one-line JSON `{ migrations: [...] }` to stdout
+ *      - default   → padded table to stdout via `formatMigrationListPretty`
+ *   7. Return SUCCESS.
+ *
+ * **Pure.** No `process.exit`, no `console.*`, no direct
+ * `process.stdout` / `process.stderr` writes. The caller (the commander
+ * action wired up in `cli.ts` — landing in a later step) injects
+ * writers; tests pass collector functions.
+ *
+ * **`migration.transform` is NEVER invoked here.** The v0.8 boundary
+ * (INVARIANTS — "no apply, no transform execution") stays in force.
+ * Static-scan asserted by [`../../../../tests/commands/schema-migrate-list.test.ts`](../../../../tests/commands/schema-migrate-list.test.ts).
+ *
+ * JSON output shape is locked here so machine consumers have a stable
+ * contract. The `migration` field on `MigrationEntry` — the live
+ * `AnyMigration` carrying the `transform` closure — is deliberately
+ * NOT included; it's not JSON-serializable, not a useful downstream
+ * identifier, and touching it would tempt callers across the v0.8
+ * boundary.
+ *
+ *     {
+ *       "migrations": [
+ *         {
+ *           "schemaId":       "com.x.Tenant",
+ *           "fromVersion":    "1.0.0",
+ *           "toVersion":      "2.0.0",
+ *           "sourcePath":     "schemas/tenant.1-0-0-to-2-0-0.migration.ts",
+ *           "fromIrHash":     "sha256:...",
+ *           "toIrHash":       "sha256:...",
+ *           "fromSourceHash": "sha256:...",
+ *           "toSourceHash":   "sha256:..."
+ *         },
+ *         …
+ *       ]
+ *     }
+ */
+import { buildMigrationRegistry, listMigrationsHandler } from "@nekostack/schema/cli";
+import { EXIT_CODES } from "../../../exit-codes.js";
+import { formatJson } from "../../../formatters/json.js";
+import { formatIssuesPretty, formatLoadFailuresPretty, formatMigrationListPretty, } from "../../../formatters/pretty.js";
+import { readMigrations } from "../../../loaders/read-migrations.js";
+/**
+ * Project a `LoadFailure` to a JSON-safe shape. `LoadFailure.cause` is
+ * an `unknown` thrown by tsx/esbuild and may not serialize cleanly
+ * (circular references, function values, etc.). The CLI's `--json`
+ * contract for load failures is `{ path, reason, message }` only —
+ * same projection rule as the v0.7 `runList`.
+ */
+function toSerializableLoadFailure(f) {
+    return { path: f.path, reason: f.reason, message: f.message };
+}
+/**
+ * Pick the exit code for a `buildMigrationRegistry` failure:
+ *   - any `integrity_error` → INTEGRITY_ERROR
+ *   - otherwise (e.g., `duplicate_migration`) → LOGICAL_FAILURE
+ * Same dispatch rule as v0.7 `runCheck`'s handler-failure mapping.
+ */
+function pickRegistryFailureExitCode(issues) {
+    for (const i of issues) {
+        if (i.code === "integrity_error")
+            return EXIT_CODES.INTEGRITY_ERROR;
+    }
+    return EXIT_CODES.LOGICAL_FAILURE;
+}
+export async function runMigrateList(opts) {
+    // 1. Walk the workspace and load every `*.migration.ts` file.
+    const walk = await readMigrations({ root: opts.root });
+    // 2. Per-file load failures → IO_ERROR. Render before returning.
+    //    Failures are essential diagnostics; `--quiet` does not suppress
+    //    them, matching v0.7 `runList`.
+    if (walk.failures.length > 0) {
+        if (opts.json) {
+            opts.stdout(formatJson({
+                failures: walk.failures.map(toSerializableLoadFailure),
+            }));
+        }
+        else {
+            opts.stderr(formatLoadFailuresPretty(walk.failures, {
+                noun: { singular: "migration file", plural: "migration files" },
+            }));
+        }
+        return EXIT_CODES.IO_ERROR;
+    }
+    // 3. Build the in-memory migration registry. `buildMigrationRegistry`
+    //    returns a `Result` so `duplicate_migration` and provenance
+    //    parse failures surface as `Issue[]` rather than throws.
+    const reg = buildMigrationRegistry(walk.entries);
+    if (!reg.success) {
+        if (opts.json) {
+            opts.stdout(formatJson({ issues: reg.issues }));
+        }
+        else {
+            opts.stderr(formatIssuesPretty(reg.issues));
+        }
+        return pickRegistryFailureExitCode(reg.issues);
+    }
+    // 4. Enumerate. `listMigrationsHandler` has no failure mode today
+    //    but treat any future failure defensively as LOGICAL_FAILURE.
+    const result = listMigrationsHandler({ migrationRegistry: reg.data });
+    if (!result.success) {
+        if (opts.json) {
+            opts.stdout(formatJson({ issues: result.issues }));
+        }
+        else {
+            opts.stderr(formatIssuesPretty(result.issues));
+        }
+        return EXIT_CODES.LOGICAL_FAILURE;
+    }
+    // 5. Success — write the entries in the chosen format.
+    if (opts.json) {
+        opts.stdout(formatJson({
+            migrations: result.data.entries.map((e) => ({
+                schemaId: e.schemaId,
+                fromVersion: e.fromVersion,
+                toVersion: e.toVersion,
+                sourcePath: e.sourcePath,
+                fromIrHash: e.fromIrHash,
+                toIrHash: e.toIrHash,
+                fromSourceHash: e.fromSourceHash,
+                toSourceHash: e.toSourceHash,
+            })),
+        }));
+    }
+    else {
+        opts.stdout(formatMigrationListPretty(result.data.entries));
+    }
+    return EXIT_CODES.SUCCESS;
+}
+//# sourceMappingURL=list.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../../../../src/commands/schema/migrate/list.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAEtF,OAAO,EAAE,UAAU,EAAiB,MAAM,wBAAwB,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,EACL,kBAAkB,EAClB,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAGrE;;;;;;GAMG;AACH,SAAS,yBAAyB,CAChC,CAAc;IAEd,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;AAChE,CAAC;AAED;;;;;GAKG;AACH,SAAS,2BAA2B,CAAC,MAAwB;IAC3D,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,CAAC,IAAI,KAAK,iBAAiB;YAAE,OAAO,UAAU,CAAC,eAAe,CAAC;IACtE,CAAC;IACD,OAAO,UAAU,CAAC,eAAe,CAAC;AACpC,CAAC;AAUD,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAA2B;IAE3B,8DAA8D;IAC9D,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAEvD,iEAAiE;IACjE,qEAAqE;IACrE,oCAAoC;IACpC,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,IAAI,CAAC,MAAM,CACT,UAAU,CAAC;gBACT,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,yBAAyB,CAAC;aACvD,CAAC,CACH,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,MAAM,CACT,wBAAwB,CAAC,IAAI,CAAC,QAAQ,EAAE;gBACtC,IAAI,EAAE,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,EAAE,iBAAiB,EAAE;aAChE,CAAC,CACH,CAAC;QACJ,CAAC;QACD,OAAO,UAAU,CAAC,QAAQ,CAAC;IAC7B,CAAC;IAED,sEAAsE;IACtE,gEAAgE;IAChE,6DAA6D;IAC7D,MAAM,GAAG,GAAG,sBAAsB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACjD,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QACjB,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QAClD,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,MAAM,CAAC,kBAAkB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;QAC9C,CAAC;QACD,OAAO,2BAA2B,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACjD,CAAC;IAED,kEAAkE;IAClE,kEAAkE;IAClE,MAAM,MAAM,GAAG,qBAAqB,CAAC,EAAE,iBAAiB,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IACtE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QACrD,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,MAAM,CAAC,kBAAkB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;QACjD,CAAC;QACD,OAAO,UAAU,CAAC,eAAe,CAAC;IACpC,CAAC;IAED,uDAAuD;IACvD,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,IAAI,CAAC,MAAM,CACT,UAAU,CAAC;YACT,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC1C,QAAQ,EAAE,CAAC,CAAC,QAAQ;gBACpB,WAAW,EAAE,CAAC,CAAC,WAAW;gBAC1B,SAAS,EAAE,CAAC,CAAC,SAAS;gBACtB,UAAU,EAAE,CAAC,CAAC,UAAU;gBACxB,UAAU,EAAE,CAAC,CAAC,UAAU;gBACxB,QAAQ,EAAE,CAAC,CAAC,QAAQ;gBACpB,cAAc,EAAE,CAAC,CAAC,cAAc;gBAChC,YAAY,EAAE,CAAC,CAAC,YAAY;aAC7B,CAAC,CAAC;SACJ,CAAC,CACH,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,IAAI,CAAC,MAAM,CAAC,yBAAyB,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,UAAU,CAAC,OAAO,CAAC;AAC5B,CAAC"}

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

@@ -0,0 +1,79 @@
+/**
+ * `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 { type ExitCode } from "../../../exit-codes.js";
+export interface RunMigratePlanOptions {
+    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 runMigratePlan(opts: RunMigratePlanOptions): Promise<ExitCode>;
+//# sourceMappingURL=plan.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../../../src/commands/schema/migrate/plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AAaH,OAAO,EAAc,KAAK,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAcnE,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;AAwJD,wBAAsB,cAAc,CAClC,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,QAAQ,CAAC,CA6FnB"}