@dbsp/cli 2.1.4 → 2.2.0

package/dist/index.js

@@ -14,7 +14,7 @@ import {
 } from "./chunk-AKVQI5ZD.js";
 
 // src/index.ts
-import { Command as Command7, CommanderError } from "commander";
+import { Command as Command8, CommanderError } from "commander";
 
 // src/commands/generate.ts
 import { mkdirSync, writeFileSync } from "fs";
@@ -218,6 +218,7 @@ import {
   comparePgsqlDatabaseSchema,
   createPgsqlAdapter,
   ensureMigrationsTable,
+  escapeDiagnosticText,
   generateMigrationFile,
   generateMigrationSQL,
   getAppliedMigrations,
@@ -574,7 +575,9 @@ var devCommand = new Command3("dev").description("Generate a migration from sche
       const diff = await comparePgsqlDatabaseSchema(adapter, schemaModel, {
         ...options.schemaName ? { schema: options.schemaName } : {},
         ...loaded.dbCasing ? { dbCasing: loaded.dbCasing } : {},
-        onWarning: (message) => console.warn(`\u26A0\uFE0F  ${message}`)
+        onExpressionCanonicalizationWarning: (warning) => console.warn(
+          `\u26A0\uFE0F  [${warning.kind} ${escapeDiagnosticText(warning.table)}.${escapeDiagnosticText(warning.name)}] ${warning.message}`
+        )
       });
       if (diff.changes.length === 0) {
         console.log("\u2705 No changes detected \u2014 database matches schema.");
@@ -691,15 +694,530 @@ var statusCommand = new Command3("status").description("Show migration status").
 );
 var migrateCommand = new Command3("migrate").description("Database migration management").addCommand(devCommand).addCommand(applyCommand).addCommand(rollbackCommand).addCommand(statusCommand);
 
+// src/commands/plan.ts
+import {
+  acquirePgTransitionClient,
+  createPgExecutionContract,
+  createPgsqlAdapter as createPgsqlAdapter2,
+  createPgTransitionLessor,
+  createPgTransitionPack,
+  createPgTransitionRunPersister,
+  ensureTransitionJournal,
+  escapeDiagnosticText as escapeDiagnosticText2,
+  PgExecutionContractDerivationError,
+  pgTargetIdentityMismatch,
+  readPgExecutionTargetFromClient,
+  readPgObservationContextFromLessor
+} from "@dbsp/adapter-pgsql";
+import {
+  acquireTransitionLease,
+  bindExecutionContract,
+  createComparator,
+  createPackRegistry,
+  createProver,
+  createTransitionRunMetadata
+} from "@dbsp/core";
+import { Command as Command4 } from "commander";
+var PlanPersistenceIndeterminateError = class extends Error {
+  runId;
+  result;
+  persistenceError;
+  cleanup;
+  constructor(result, persistenceError, cleanup = noCleanupFailure) {
+    const cause = cleanup.kind === "failed" ? new AggregateError(
+      [persistenceError, cleanup.error],
+      "persistence and connection release both failed"
+    ) : persistenceError;
+    super(
+      `persistence indeterminate; inspect run ${result.runId}: ${escapeDiagnosticText2(describeThrown(persistenceError))}`,
+      { cause }
+    );
+    this.name = "PlanPersistenceIndeterminateError";
+    this.runId = result.runId ?? "";
+    this.result = result;
+    this.persistenceError = persistenceError;
+    this.cleanup = cleanup;
+  }
+};
+var PlanCleanupError = class extends Error {
+  constructor(result, cleanupError) {
+    super(
+      `connection release failed after the plan outcome was determined: ${escapeDiagnosticText2(describeThrown(cleanupError))}`,
+      { cause: cleanupError }
+    );
+    this.result = result;
+    this.cleanupError = cleanupError;
+    this.name = "PlanCleanupError";
+  }
+  result;
+  cleanupError;
+};
+var PlanOperationAndCleanupError = class extends AggregateError {
+  constructor(operationError, cleanupError) {
+    super(
+      [operationError, cleanupError],
+      "planning and connection release both failed",
+      { cause: operationError }
+    );
+    this.operationError = operationError;
+    this.cleanupError = cleanupError;
+    this.name = "PlanOperationAndCleanupError";
+  }
+  operationError;
+  cleanupError;
+};
+var noCleanupFailure = { kind: "not-failed" };
+function equivalenceContext(context) {
+  return {
+    engine: context.engine,
+    ...context.databaseId ? { databaseId: context.databaseId } : {},
+    ...context.targetSchema ? { targetSchema: context.targetSchema } : {},
+    ...context.searchPath ? { searchPath: context.searchPath } : {},
+    proofObservationContext: context
+  };
+}
+function executionTargetNamespaces(plan, fallbackSchema) {
+  const namespaces = [
+    ...new Set(
+      plan.steps.map((step) => {
+        const payload = step.operation.payload;
+        if (payload === null || typeof payload !== "object" || Array.isArray(payload) || typeof payload.schema !== "string")
+          throw new PgExecutionContractDerivationError(
+            step.operation.ref,
+            step.operation.operationKind.name,
+            "has no derivable target namespace"
+          );
+        return payload.schema;
+      })
+    )
+  ];
+  if (namespaces.length === 0 && fallbackSchema !== void 0)
+    namespaces.push(fallbackSchema);
+  return namespaces;
+}
+async function buildPgExecutionContract(pool, schema, plan, expectedTargetIdentity) {
+  const lease = await acquireTransitionLease(createPgTransitionLessor(pool));
+  try {
+    const target = await readPgExecutionTargetFromClient(
+      lease.session,
+      executionTargetNamespaces(plan, schema)
+    );
+    const mismatch = pgTargetIdentityMismatch(
+      expectedTargetIdentity,
+      target.identity
+    );
+    if (mismatch) {
+      throw new Error(
+        `PostgreSQL target identity changed before plan persistence: ${mismatch}`
+      );
+    }
+    return createPgExecutionContract(
+      plan,
+      target.identity,
+      target.sessionProvenance
+    );
+  } finally {
+    await lease.release();
+  }
+}
+var defaultPlanDeps = {
+  async createDbConnection(db) {
+    const { pool } = await createDbConnection(db);
+    return { pool, release: () => pool.end() };
+  },
+  loadSchema,
+  async ensureTransitionJournal(pool) {
+    const lease = await acquireTransitionLease(createPgTransitionLessor(pool));
+    try {
+      await ensureTransitionJournal(lease.session);
+    } finally {
+      await lease.release();
+    }
+  },
+  async captureTargetIdentity(pool, schema) {
+    const lease = await acquireTransitionLease(createPgTransitionLessor(pool));
+    try {
+      return (await readPgExecutionTargetFromClient(lease.session, [
+        schema ?? "public"
+      ])).identity;
+    } finally {
+      await lease.release();
+    }
+  },
+  async loadCurrent(pool, schema, expectedTargetIdentity) {
+    const lease = await acquirePgTransitionClient(pool);
+    try {
+      const observed = await readPgExecutionTargetFromClient(
+        lease.client,
+        [schema ?? "public"]
+      );
+      const mismatch = pgTargetIdentityMismatch(
+        expectedTargetIdentity,
+        observed.identity
+      );
+      if (mismatch) {
+        throw new Error(
+          `PostgreSQL introspection target identity does not match the captured target: ${mismatch}`
+        );
+      }
+      return await createPgsqlAdapter2(lease.client, {
+        borrowedClient: true
+      }).introspect(schema === void 0 ? {} : { schema });
+    } finally {
+      lease.release();
+    }
+  },
+  async readContext(pool, schema, expectedTargetIdentity) {
+    return readPgObservationContextFromLessor(
+      createPgTransitionLessor(pool),
+      schema,
+      void 0,
+      expectedTargetIdentity
+    );
+  },
+  createPlanner(loaded) {
+    const registry = createPackRegistry([
+      createPgTransitionPack({
+        ...loaded.dbCasing ? { dbCasing: loaded.dbCasing } : {}
+      })
+    ]);
+    const comparator = createComparator(registry);
+    const prover = createProver(registry);
+    return {
+      compare: (desired, current, context) => comparator.compare(desired, current, equivalenceContext(context)),
+      prove: (compare, pool, context) => prover.prove(compare, createPgTransitionLessor(pool), context),
+      render: (plan, context) => renderProvenPlanSql(registry, plan, context)
+    };
+  },
+  async persist(pool, run, plan) {
+    const lease = await acquireTransitionLease(createPgTransitionLessor(pool));
+    try {
+      await createPgTransitionRunPersister(lease.session).persist(run, plan);
+    } finally {
+      await lease.release();
+    }
+  },
+  buildExecutionContract: buildPgExecutionContract
+};
+function resolvedDeps(overrides) {
+  return { ...defaultPlanDeps, ...overrides };
+}
+function describeThrown(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function executionContractBlockedAssessment(error) {
+  return {
+    decision: "blocked",
+    assurance: "unproven",
+    lifecycle: "planned",
+    continuation: "replan-required",
+    reasons: [
+      {
+        code: "unsupported-transition",
+        changes: [],
+        scope: [],
+        detail: error.message
+      }
+    ]
+  };
+}
+function renderProvenPlanSql(registry, plan, context) {
+  const statements = plan.steps.map((step) => {
+    const resolution = registry.resolveOperation(step.operation);
+    if (!resolution.ok || !resolution.semantics.renderPlanSql) {
+      throw new Error(
+        `no SQL renderer is registered for proven operation ${step.operation.operationKind.name}`
+      );
+    }
+    return resolution.semantics.renderPlanSql(step.operation, context);
+  });
+  return [
+    "-- dbsp transition plan view; apply accepts a persisted run id, never this SQL.",
+    ...statements.map((statement) => `${statement};`)
+  ].join("\n");
+}
+async function runPlan(options, overrides) {
+  const deps = resolvedDeps(overrides);
+  const format = options.format ?? "sql";
+  if (format !== "sql" && format !== "json") {
+    throw new Error(`unsupported plan format ${format}; expected sql or json`);
+  }
+  const loaded = await deps.loadSchema(options.schemaFile);
+  const connection = await deps.createDbConnection(options.db);
+  const { pool } = connection;
+  let result;
+  let operationError;
+  let failed = false;
+  try {
+    const targetIdentity = await deps.captureTargetIdentity(
+      pool,
+      options.schema
+    );
+    await deps.ensureTransitionJournal(pool);
+    const current = await deps.loadCurrent(
+      pool,
+      options.schema,
+      targetIdentity
+    );
+    const context = await deps.readContext(
+      pool,
+      options.schema,
+      targetIdentity
+    );
+    const planner = deps.createPlanner(loaded);
+    const compare = planner.compare(loaded.model, current, context);
+    const prove = await planner.prove(compare, pool, context);
+    if (prove.kind === "proven") {
+      let executionContract;
+      try {
+        executionContract = await deps.buildExecutionContract(
+          pool,
+          options.schema,
+          prove.plan,
+          targetIdentity
+        );
+      } catch (error) {
+        if (!(error instanceof PgExecutionContractDerivationError)) throw error;
+        result = {
+          compareKind: compare.kind,
+          proveKind: "blocked",
+          assessment: executionContractBlockedAssessment(error),
+          persisted: false,
+          runId: null,
+          planDigest: null
+        };
+      }
+      if (executionContract !== void 0) {
+        const durablePlan = bindExecutionContract(
+          prove.plan,
+          executionContract
+        );
+        const run = createTransitionRunMetadata(durablePlan);
+        const proofContext = prove.plan.observations.find(
+          (observation) => observation.role === "evidence"
+        )?.context;
+        if (!proofContext) {
+          throw new Error(
+            "internal error: minted proven plan has no evidence observation context"
+          );
+        }
+        const sql = planner.render(durablePlan, proofContext);
+        if (!options.dryRun) {
+          try {
+            await deps.persist(pool, run, durablePlan);
+          } catch (error) {
+            throw new PlanPersistenceIndeterminateError(
+              {
+                compareKind: compare.kind,
+                proveKind: prove.kind,
+                assessment: prove.assessment,
+                persisted: "indeterminate",
+                runId: run.runId,
+                planDigest: run.planDigest
+              },
+              error
+            );
+          }
+        }
+        result = {
+          compareKind: compare.kind,
+          proveKind: prove.kind,
+          assessment: prove.assessment,
+          persisted: !options.dryRun,
+          runId: options.dryRun ? null : run.runId,
+          planDigest: run.planDigest,
+          plan: durablePlan,
+          sql
+        };
+      }
+    }
+    if (prove.kind === "no-drift") {
+      result = {
+        compareKind: compare.kind,
+        proveKind: prove.kind,
+        assessment: prove.assessment,
+        persisted: false,
+        runId: null,
+        planDigest: null
+      };
+    } else if (prove.kind !== "proven") {
+      result = {
+        compareKind: compare.kind,
+        proveKind: prove.kind,
+        assessment: prove.assessment,
+        persisted: false,
+        runId: null,
+        planDigest: null
+      };
+    }
+  } catch (error) {
+    failed = true;
+    operationError = error;
+  }
+  let cleanup = noCleanupFailure;
+  try {
+    await connection.release();
+  } catch (error) {
+    cleanup = { kind: "failed", error };
+  }
+  if (failed) {
+    if (operationError instanceof PlanPersistenceIndeterminateError) {
+      throw new PlanPersistenceIndeterminateError(
+        operationError.result,
+        operationError.persistenceError,
+        cleanup
+      );
+    }
+    if (cleanup.kind === "failed") {
+      throw new PlanOperationAndCleanupError(operationError, cleanup.error);
+    }
+    throw operationError;
+  }
+  if (cleanup.kind === "failed") {
+    throw new PlanCleanupError(result, cleanup.error);
+  }
+  return result;
+}
+function formatPlanJson(result, dryRun) {
+  return {
+    compareKind: result.compareKind,
+    proveKind: result.proveKind,
+    assessment: result.assessment,
+    persisted: result.persisted,
+    runId: result.runId,
+    planDigest: result.planDigest,
+    ...result.plan ? { plan: result.plan } : {},
+    ...result.sql ? { sql: result.sql } : {},
+    ...dryRun && result.proveKind === "proven" ? { preview: "non-executable; no durable dbsp record" } : {}
+  };
+}
+function formatPlanHuman(result, dryRun) {
+  if (result.proveKind === "proven") {
+    return [
+      dryRun ? "Proven transition preview (non-executable; no durable dbsp record):" : "Proven transition plan:",
+      // Every operation renderer converges on result.sql before this human-only
+      // view, so database-sourced SQL cannot bypass terminal escaping here.
+      ...result.sql === void 0 ? [] : [escapeDiagnosticText2(result.sql)],
+      ...result.plan?.executionContract ? [
+        "Execution contract:",
+        ...result.plan.executionContract.requirements.map(
+          (requirement) => `  ${escapeDiagnosticText2(JSON.stringify(requirement))}`
+        )
+      ] : [],
+      dryRun ? `Preview digest: ${result.planDigest}` : `Run id: ${result.runId}
+Plan digest: ${result.planDigest}`
+    ].filter((line) => line !== void 0).join("\n");
+  }
+  if (result.proveKind === "no-drift") {
+    return "Database already matches the target; nothing was persisted.";
+  }
+  return `No durable plan was created.
+${escapeDiagnosticText2(JSON.stringify(result.assessment, null, 2))}`;
+}
+function preservedPlanResult(error, fallback) {
+  if (error instanceof PlanPersistenceIndeterminateError) return error.result;
+  if (error instanceof PlanCleanupError) return error.result;
+  return fallback;
+}
+function primaryPlanError(error) {
+  if (error instanceof PlanPersistenceIndeterminateError) {
+    return error.persistenceError;
+  }
+  if (error instanceof PlanCleanupError) return error.cleanupError;
+  if (error instanceof PlanOperationAndCleanupError) {
+    return error.operationError;
+  }
+  return error;
+}
+function cleanupFailure(error) {
+  if (error instanceof PlanPersistenceIndeterminateError) {
+    return error.cleanup;
+  }
+  if (error instanceof PlanCleanupError) {
+    return { kind: "failed", error: error.cleanupError };
+  }
+  if (error instanceof PlanOperationAndCleanupError) {
+    return { kind: "failed", error: error.cleanupError };
+  }
+  return noCleanupFailure;
+}
+function formatPlanFailureJson(error, fallback) {
+  const result = preservedPlanResult(error, fallback);
+  const cleanupError = cleanupFailure(error);
+  return {
+    compareKind: result?.compareKind ?? null,
+    proveKind: result?.proveKind ?? null,
+    assessment: result?.assessment ?? null,
+    persisted: result?.persisted ?? false,
+    runId: result?.runId ?? null,
+    planDigest: result?.planDigest ?? null,
+    error: describeThrown(primaryPlanError(error)),
+    ...cleanupError.kind === "not-failed" ? {} : { cleanupError: describeThrown(cleanupError.error) }
+  };
+}
+function formatPlanFailureHuman(error, fallback) {
+  const result = preservedPlanResult(error, fallback);
+  const fields = result ? [
+    result.persisted === true ? "A durable plan was created before this failure." : result.persisted === "indeterminate" ? "Persistence is indeterminate; inspect the minted run before retrying." : "No durable plan was created.",
+    ...result.runId ? [`Run id: ${result.runId}`] : [],
+    ...result.planDigest ? [`Plan digest: ${result.planDigest}`] : []
+  ] : [];
+  const cleanupError = cleanupFailure(error);
+  return [
+    `\u274C ${escapeDiagnosticText2(describeThrown(primaryPlanError(error)))}`,
+    ...fields,
+    ...cleanupError.kind === "not-failed" ? [] : [
+      `Connection release also failed: ${escapeDiagnosticText2(describeThrown(cleanupError.error))}`
+    ]
+  ].join("\n");
+}
+function printHumanResult(result, dryRun) {
+  console.log(formatPlanHuman(result, dryRun));
+}
+function exitCodeForPlanResult(result) {
+  return result.proveKind === "blocked" || result.proveKind === "inapplicable" ? 1 : 0;
+}
+var planCommand = new Command4("plan").description("Prove and persist a transition plan without applying it").argument("<schema-file>", "Schema DSL file").requiredOption("-d, --db <url>", "Database connection URL (required)").option("--schema <name>", "Database schema name", "public").option("--dry-run", "Prove and render without persisting a transition run").option("--format <format>", "Output format: sql or json", "sql").exitOverride().configureOutput({ writeErr: () => {
+} }).action(
+  async (schemaFile, options) => {
+    let result;
+    try {
+      result = await runPlan({ ...options, schemaFile });
+      if (options.format === "json") {
+        console.log(
+          JSON.stringify(
+            formatPlanJson(result, options.dryRun === true),
+            null,
+            2
+          )
+        );
+      } else {
+        printHumanResult(result, options.dryRun === true);
+      }
+      process.exitCode = exitCodeForPlanResult(result);
+    } catch (error) {
+      if (options.format === "json") {
+        console.log(
+          JSON.stringify(formatPlanFailureJson(error, result), null, 2)
+        );
+      } else {
+        console.error(formatPlanFailureHuman(error, result));
+      }
+      process.exitCode = 1;
+    }
+  }
+);
+
 // src/commands/push.ts
 import {
   comparePgsqlDatabaseSchema as comparePgsqlDatabaseSchema2,
-  createPgsqlAdapter as createPgsqlAdapter2,
+  createPgsqlAdapter as createPgsqlAdapter3,
+  escapeDiagnosticText as escapeDiagnosticText3,
   generateDDL,
   generateMigrationSQL as generateMigrationSQL2,
   getNamingPluginForDbCasing
 } from "@dbsp/adapter-pgsql";
-import { Command as Command4 } from "commander";
+import { Command as Command5 } from "commander";
 
 // src/ddl-executor.ts
 async function executeDdl(pool, statements, options) {
@@ -732,7 +1250,7 @@ async function executeDdl(pool, statements, options) {
 
 // src/commands/push.ts
 var MIGRATIONS_TABLE = "_dbsp_migrations";
-var pushCommand = new Command4("push").description("Push schema to database (additive by default)").option(
+var pushCommand = new Command5("push").description("Push schema to database (additive by default)").option(
   "-s, --schema <path>",
   "Path to schema file (default: dbsp.schema.ts)"
 ).requiredOption("-d, --db <url>", "Database connection URL (required)").option("--schema-name <name>", "Database schema name (default: public)").option("--drop", "Drop and recreate all objects (preserves migrations)").option("--dry-run", "Print SQL without executing").option("--json", "Output as JSON").action(
@@ -792,11 +1310,13 @@ var pushCommand = new Command4("push").description("Push schema to database (add
             );
           }
         } else {
-          const adapter = createPgsqlAdapter2(pool);
+          const adapter = createPgsqlAdapter3(pool);
           const compareOptions = {
             ...options.schemaName ? { schema: options.schemaName } : {},
             ...loaded.dbCasing ? { dbCasing: loaded.dbCasing } : {},
-            onWarning: (message) => console.warn(`\u26A0\uFE0F  ${message}`)
+            onExpressionCanonicalizationWarning: (warning) => console.warn(
+              `\u26A0\uFE0F  [${warning.kind} ${escapeDiagnosticText3(warning.table)}.${escapeDiagnosticText3(warning.name)}] ${warning.message}`
+            )
           };
           const diff = await comparePgsqlDatabaseSchema2(
             adapter,
@@ -933,8 +1453,8 @@ function formatOutstandingChange(change) {
 
 // src/commands/repl.ts
 import { readFileSync as readFileSync2 } from "fs";
-import { Command as Command5 } from "commander";
-var replCommand = new Command5("repl").description("Launch interactive REPL for exploring schema and queries").option("-s, --schema <path>", "Path to schema file (default: auto-detect)").option(
+import { Command as Command6 } from "commander";
+var replCommand = new Command6("repl").description("Launch interactive REPL for exploring schema and queries").option("-s, --schema <path>", "Path to schema file (default: auto-detect)").option(
   "-d, --db <url>",
   "PostgreSQL connection URL for execution mode (e.g., postgres://localhost/mydb)"
 ).option("-e, --eval <query>", "Execute a single query and exit (batch mode)").option(
@@ -1056,9 +1576,10 @@ function mapReplCasingOption(casing) {
 // src/commands/verify.ts
 import {
   comparePgsqlDatabaseSchema as comparePgsqlDatabaseSchema3,
-  createPgsqlAdapter as createPgsqlAdapter3
+  createPgsqlAdapter as createPgsqlAdapter4,
+  escapeDiagnosticText as escapeDiagnosticText4
 } from "@dbsp/adapter-pgsql";
-import { Command as Command6 } from "commander";
+import { Command as Command7 } from "commander";
 
 // src/verifier.ts
 var CHANGE_TO_DRIFT = {
@@ -1182,7 +1703,7 @@ function formatVerifyResult(result) {
 }
 
 // src/commands/verify.ts
-var verifyCommand = new Command6("verify").description("Compare schema vs real database (drift detection)").option(
+var verifyCommand = new Command7("verify").description("Compare schema vs real database (drift detection)").option(
   "-s, --schema <path>",
   "Path to schema file (default: dbsp.schema.ts)"
 ).requiredOption("-d, --db <url>", "Database connection URL (required)").option("--schema-name <name>", "Database schema name (default: public)").option("--json", "Output as JSON").action(
@@ -1202,11 +1723,13 @@ var verifyCommand = new Command6("verify").description("Compare schema vs real d
       const schemaModel = loaded.model;
       const { pool } = await createDbConnection(options.db);
       try {
-        const adapter = createPgsqlAdapter3(pool);
+        const adapter = createPgsqlAdapter4(pool);
         const diff = await comparePgsqlDatabaseSchema3(adapter, schemaModel, {
           ...options.schemaName ? { schema: options.schemaName } : {},
           ...loaded.dbCasing !== void 0 ? { dbCasing: loaded.dbCasing } : {},
-          onWarning: (message) => console.warn(`\u26A0\uFE0F  ${message}`)
+          onExpressionCanonicalizationWarning: (warning) => console.warn(
+            `\u26A0\uFE0F  [${warning.kind} ${escapeDiagnosticText4(warning.table)}.${escapeDiagnosticText4(warning.name)}] ${warning.message}`
+          )
         });
         const dbModel = await adapter.introspect({
           ...options.schemaName ? { schema: options.schemaName } : {}
@@ -1250,14 +1773,45 @@ var verifyCommand = new Command6("verify").description("Compare schema vs real d
 );
 
 // src/index.ts
-var program = new Command7();
+var program = new Command8();
+function selectedCommand(argv, commands) {
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--") return void 0;
+    if (argument?.startsWith("-")) continue;
+    const command = commands.find((candidate) => candidate.name() === argument);
+    return command === void 0 ? void 0 : { command, index };
+  }
+  return void 0;
+}
+function requestsPlanJson(argv, commands) {
+  const selected = selectedCommand(argv, commands);
+  if (selected?.command !== planCommand) return false;
+  for (let index = selected.index + 1; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--") break;
+    if (argument === "--format" && argv[index + 1] === "json" || argument === "--format=json") {
+      return true;
+    }
+  }
+  return false;
+}
 program.name("dbsp").description("Schema-first code generation for db-semantic-planner").version("0.0.1");
 program.addCommand(generateCommand);
 program.addCommand(introspectCommand);
 program.addCommand(migrateCommand);
+program.addCommand(planCommand);
 program.addCommand(pushCommand);
 program.addCommand(replCommand);
 program.addCommand(verifyCommand);
+var planJsonRequested = requestsPlanJson(
+  process.argv.slice(2),
+  program.commands
+);
+if (planJsonRequested) {
+  program.configureOutput({ writeErr: () => {
+  } });
+}
 program.exitOverride();
 try {
   program.parse();
@@ -1266,7 +1820,7 @@ try {
     process.exit(0);
   }
   const message = err instanceof Error ? err.message : "Command parse error";
-  if (process.argv.includes("--json")) {
+  if (process.argv.includes("--json") || planJsonRequested) {
     console.log(JSON.stringify({ status: "error", error: message }, null, 2));
   } else {
     console.error(`\u274C ${message}`);