migraguard 0.9.1 → 0.9.2

package/cli-contract.yaml

@@ -77,9 +77,16 @@ commandSets:
               type: boolean
               default: false
 
+          - name: dry-run
+            aliases: [n]
+            description: Show what would be created without writing files.
+            schema:
+              type: boolean
+              default: false
+
         exits:
           '0':
-            description: Migration file (or group directory) created successfully.
+            description: Migration file (or group directory) created successfully (or dry-run preview completed).
             stdout:
               format: text
             files:
@@ -105,6 +112,10 @@ commandSets:
           idempotent: false
           sideEffects:
             - file_write
+          sideEffectNote: Creates migration SQL file(s) in the configured migrations directory.
+          safeDryRunOption: dry-run
+          expectedDurationMs: 1000
+          retryableExitCodes: []
 
       # ── apply ────────────────────────────────────────
       apply:
@@ -168,7 +179,12 @@ commandSets:
             requires writing a compensating migration or restoring from backup.
           sideEffects:
             - database_write
+          sideEffectNote: >-
+            Executes SQL via native CLI and records results in schema_migrations.
+            Uses advisory lock to prevent concurrent execution.
           safeDryRunOption: dry-run
+          expectedDurationMs: 60000
+          retryableExitCodes: []
           recommendedBeforeUse:
             - Run migraguard check to verify metadata integrity.
             - Run migraguard lint to check for unsafe DDL patterns.
@@ -192,6 +208,11 @@ commandSets:
               format: text
 
           '1':
+            description: Unexpected error (file read failure, parse error).
+            stderr:
+              format: text
+
+          '10':
             description: Integrity check failed (tampered, missing, or extra files).
             stderr:
               format: text
@@ -201,6 +222,9 @@ commandSets:
           requiresConfirmation: false
           idempotent: true
           sideEffects: []
+          sideEffectNote: Read-only. Compares metadata.json against files on disk.
+          expectedDurationMs: 2000
+          retryableExitCodes: []
 
       # ── squash ───────────────────────────────────────
       squash:
@@ -211,6 +235,15 @@ commandSets:
           recovery and hotfix workflows. Original migration files are deleted.
         usage:
           - migraguard squash
+          - migraguard squash --dry-run
+
+        options:
+          - name: dry-run
+            aliases: [n]
+            description: Show what would be squashed without writing files.
+            schema:
+              type: boolean
+              default: false
 
         exits:
           '0':
@@ -240,6 +273,12 @@ commandSets:
           sideEffects:
             - file_write
             - file_delete
+          sideEffectNote: >-
+            Merges migration files into one and deletes originals.
+            Updates metadata.json.
+          safeDryRunOption: dry-run
+          expectedDurationMs: 3000
+          retryableExitCodes: []
           recommendedBeforeUse:
             - Ensure all pending files are ready for release.
             - Confirm no uncommitted changes to migration files.
@@ -290,6 +329,9 @@ commandSets:
           requiresConfirmation: false
           idempotent: true
           sideEffects: []
+          sideEffectNote: Read-only. Scans migration files against safety rules.
+          expectedDurationMs: 3000
+          retryableExitCodes: []
 
       # ── dump ─────────────────────────────────────────
       dump:
@@ -325,6 +367,11 @@ commandSets:
           sideEffects:
             - database_read
             - file_write
+          sideEffectNote: >-
+            Reads DB schema via pg_dump/mysqldump and writes normalized
+            output to schema.sql.
+          expectedDurationMs: 10000
+          retryableExitCodes: [1]
 
       # ── diff ─────────────────────────────────────────
       diff:
@@ -369,6 +416,11 @@ commandSets:
           idempotent: true
           sideEffects:
             - database_read
+          sideEffectNote: >-
+            Reads DB schema via pg_dump/mysqldump and compares with
+            saved schema.sql. No writes.
+          expectedDurationMs: 10000
+          retryableExitCodes: [1]
 
       # ── status ───────────────────────────────────────
       status:
@@ -406,6 +458,9 @@ commandSets:
           idempotent: true
           sideEffects:
             - database_read
+          sideEffectNote: Reads schema_migrations table and compares with local files.
+          expectedDurationMs: 5000
+          retryableExitCodes: [1]
 
       # ── resolve ──────────────────────────────────────
       resolve:
@@ -417,6 +472,7 @@ commandSets:
           addressed by other means.
         usage:
           - migraguard resolve 20260301_120000__create_users_table.sql
+          - migraguard resolve --dry-run 20260301_120000__create_users_table.sql
 
         arguments:
           - name: file
@@ -426,6 +482,14 @@ commandSets:
             schema:
               type: string
 
+        options:
+          - name: dry-run
+            aliases: [n]
+            description: Show what would be resolved without writing to DB.
+            schema:
+              type: boolean
+              default: false
+
         exits:
           '0':
             description: Migration marked as skipped.
@@ -447,6 +511,10 @@ commandSets:
             Re-apply the migration manually if needed.
           sideEffects:
             - database_write
+          sideEffectNote: Inserts a 'skipped' record into schema_migrations for the given file.
+          safeDryRunOption: dry-run
+          expectedDurationMs: 3000
+          retryableExitCodes: [1]
           recommendedBeforeUse:
             - Verify that the failure has been addressed by a subsequent migration or manual fix.
             - Run migraguard status to confirm the file is in failed state.
@@ -476,6 +544,9 @@ commandSets:
           requiresConfirmation: false
           idempotent: true
           sideEffects: []
+          sideEffectNote: Read-only. Lists leaf/latest migration files from metadata.
+          expectedDurationMs: 1000
+          retryableExitCodes: []
 
       # ── verify ───────────────────────────────────────
       verify:
@@ -512,7 +583,14 @@ commandSets:
               format: '{options.format}'
 
           '1':
+            description: Unexpected error (connection error, file parse failure).
+            stderr:
+              format: text
+
+          '10':
             description: One or more migrations failed idempotency verification.
+            stdout:
+              format: '{options.format}'
             stderr:
               format: text
 
@@ -523,6 +601,11 @@ commandSets:
           sideEffects:
             - database_read
             - database_write
+          sideEffectNote: >-
+            Creates and destroys a temporary shadow database to verify
+            idempotency. Does not modify the primary database.
+          expectedDurationMs: 60000
+          retryableExitCodes: [1]
           recommendedBeforeUse:
             - Ensure the database server is running and accessible.
 
@@ -562,6 +645,9 @@ commandSets:
           requiresConfirmation: false
           idempotent: true
           sideEffects: []
+          sideEffectNote: Read-only. Derives group state from schema_migrations records.
+          expectedDurationMs: 3000
+          retryableExitCodes: [1]
 
       # ── baseline ─────────────────────────────────────
       baseline:
@@ -573,6 +659,7 @@ commandSets:
         usage:
           - migraguard baseline
           - migraguard baseline --keep-since 20260301_120000__create_users_table.sql
+          - migraguard baseline --dry-run
 
         options:
           - name: keep-since
@@ -582,9 +669,16 @@ commandSets:
             schema:
               type: string
 
+          - name: dry-run
+            aliases: [n]
+            description: Show what would be baselined without writing files.
+            schema:
+              type: boolean
+              default: false
+
         exits:
           '0':
-            description: Baseline created successfully.
+            description: Baseline created successfully (or dry-run preview completed).
             stdout:
               format: text
 
@@ -604,6 +698,12 @@ commandSets:
           sideEffects:
             - file_write
             - file_delete
+          sideEffectNote: >-
+            Dumps current DB schema to schema.sql, deletes squashed migration
+            files, updates metadata.json, and rewrites depends-on references.
+          safeDryRunOption: dry-run
+          expectedDurationMs: 30000
+          retryableExitCodes: []
           recommendedBeforeUse:
             - Ensure all migrations have been applied to all environments.
             - Back up migration files before running.
@@ -650,9 +750,16 @@ commandSets:
             schema:
               type: string
 
+          - name: dry-run
+            aliases: [n]
+            description: Show what would be recorded without writing to DB.
+            schema:
+              type: boolean
+              default: false
+
         exits:
           '0':
-            description: Phase state transition recorded.
+            description: Phase state transition recorded (or dry-run preview completed).
             stdout:
               format: text
 
@@ -673,6 +780,10 @@ commandSets:
             status value to manually correct, or reset group state in the database.
           sideEffects:
             - database_write
+          sideEffectNote: Inserts a phase state transition record into schema_migrations.
+          safeDryRunOption: dry-run
+          expectedDurationMs: 5000
+          retryableExitCodes: [1]
           recommendedBeforeUse:
             - Run migraguard group-status <group> to verify current phase state before advancing.
 
@@ -710,9 +821,16 @@ commandSets:
             schema:
               type: string
 
+          - name: dry-run
+            aliases: [n]
+            description: Show what would be applied without executing SQL.
+            schema:
+              type: boolean
+              default: false
+
         exits:
           '0':
-            description: Phase applied successfully.
+            description: Phase applied successfully (or dry-run preview completed).
             stdout:
               format: text
 
@@ -733,6 +851,12 @@ commandSets:
             migration or restore from backup if rollback is needed.
           sideEffects:
             - database_write
+          sideEffectNote: >-
+            Executes a phase SQL file via native CLI and records the
+            result in schema_migrations. Uses advisory lock.
+          safeDryRunOption: dry-run
+          expectedDurationMs: 30000
+          retryableExitCodes: []
           recommendedBeforeUse:
             - Run migraguard group-status to verify current phase state.
 
@@ -790,6 +914,11 @@ commandSets:
               format: text
 
           '1':
+            description: Unexpected error (connection error, invalid condition syntax).
+            stderr:
+              format: text
+
+          '10':
             description: One or more gate conditions not satisfied.
             stderr:
               format: text
@@ -799,6 +928,9 @@ commandSets:
           requiresConfirmation: false
           idempotent: true
           sideEffects: []
+          sideEffectNote: Read-only. Evaluates gate conditions against schema_migrations state.
+          expectedDurationMs: 5000
+          retryableExitCodes: [1]
 
       # ── deps ─────────────────────────────────────────
       deps:
@@ -845,6 +977,11 @@ commandSets:
           idempotent: true
           sideEffects:
             - file_write
+          sideEffectNote: >-
+            Reads migration files and outputs dependency graph.
+            Writes HTML file only when --html is specified.
+          expectedDurationMs: 3000
+          retryableExitCodes: []
 
       # ── audit ─────────────────────────────────────────
       audit:
@@ -917,7 +1054,7 @@ commandSets:
             schema:
               type: string
               enum: [json, text, yaml]
-              default: text
+              default: json
 
         exits:
           '0':
@@ -964,7 +1101,7 @@ commandSets:
             Filesystem write only when --output is specified.
           safeDryRunOption: dry-run
           expectedDurationMs: 120000
-          retryableExitCodes: [1, 12]
+          retryableExitCodes: [12]
 
       # ── propose-expand-contract ───────────────────────
       propose-expand-contract:
@@ -1092,7 +1229,7 @@ commandSets:
             Filesystem write when --output or --output-dir is specified.
           safeDryRunOption: dry-run
           expectedDurationMs: 120000
-          retryableExitCodes: [1, 12]
+          retryableExitCodes: [12]
 
       # ── explain ───────────────────────────────────────
       explain:
@@ -1208,12 +1345,14 @@ commandSets:
             Filesystem write only when --output is specified.
           safeDryRunOption: dry-run
           expectedDurationMs: 120000
-          retryableExitCodes: [1, 12]
+          retryableExitCodes: [12]
 
 components:
   schemas:
     # ── AI Agent Interoperability Schemas (SSoT) ─────────
 
+    # Conforms to agent-contracts dsl_base/components.yaml#/schemas/agent-evidence.
+    # Canonical property names are kind/target/location/excerpt (NOT type/content/source).
     AgentEvidence:
       type: object
       description: Evidence supporting an agent finding.
@@ -1390,7 +1529,7 @@ components:
       description: >-
         Result from explain command. Contains a human-readable explanation
         of another command's output, suitable for PR comments or release decisions.
-      required: [summary, riskLevel, explanation]
+      required: [summary, riskLevel, findings, explanation]
       properties:
         summary:
           type: string

package/dist/cli.js

@@ -2224,6 +2224,25 @@ async function commandApply(config, options) {
       orderedFileNames = files.map((f) => f.fileName);
     }
     const fileMap = new Map(files.map((f) => [f.fileName, f]));
+    if (options?.dryRun) {
+      const pending = [];
+      for (const fileName of orderedFileNames) {
+        const fileRecords = recordsByFile.get(fileName) ?? [];
+        const latestRecord = getLatestRecord(fileRecords);
+        if (!latestRecord || latestRecord.status === "failed") {
+          pending.push(fileName);
+        }
+      }
+      if (pending.length === 0) {
+        console.log(chalk.green("All migrations are up to date."));
+      } else {
+        console.log(chalk.cyan(`[dry-run] ${pending.length} migration(s) would be applied:`));
+        for (const f of pending) {
+          console.log(chalk.cyan(`  ${f}`));
+        }
+      }
+      return result;
+    }
     const latestFileName = files[files.length - 1].fileName;
     const blockedSet = /* @__PURE__ */ new Set();
     const groupStates = deriveAllGroupStates(allRecords);
@@ -2502,6 +2521,11 @@ async function commandAdvance(config, options) {
     }
     const dbStatus = STATUS_MAP[status];
     const fileName = findPhaseFileName(group, phase, allRecords);
+    if (options.dryRun) {
+      console.log(chalk.cyan(`[dry-run] Would advance "${group}" ${phase} \u2192 ${status}`));
+      console.log(chalk.cyan(`  File: ${fileName}, current state: ${previousState}`));
+      return { success: true, previousState, newState: `${phase}:${status}` };
+    }
     await db.insertRecord(fileName, "", dbStatus, {
       migrationClass: "expand_contract",
       phase,
@@ -2627,6 +2651,12 @@ async function commandApplyPhase(config, options) {
       return { success: false, group, phase, error: msg };
     }
     const checksum = await checksumFile(file.filePath);
+    if (options.dryRun) {
+      console.log(chalk.cyan(`[dry-run] Would apply phase "${phase}" for "${group}"`));
+      console.log(chalk.cyan(`  File: ${expectedFileName}`));
+      console.log(chalk.cyan(`  Checksum: ${checksum}`));
+      return { success: true, group, phase };
+    }
     const psqlResult = await executeSqlFile(config, file.filePath);
     if (psqlResult.success) {
       await db.insertRecord(file.fileName, checksum, "applied", {
@@ -2710,6 +2740,14 @@ async function commandBaseline(config, options) {
       console.log(chalk.yellow("No files to baseline."));
       return { success: true, squashedFiles: [], remainingLeaves: [...keepSet], schemaFile: "" };
     }
+    if (options?.dryRun) {
+      console.log(chalk.cyan(`[dry-run] Would baseline ${squashTargets.length} file(s) into ${config.schemaFile}:`));
+      for (const f of squashTargets) {
+        console.log(chalk.cyan(`  squash: ${f}`));
+      }
+      console.log(chalk.cyan(`  Remaining: ${[...keepSet].join(", ") || "(none)"}`));
+      return { success: true, squashedFiles: squashTargets, remainingLeaves: [...keepSet], schemaFile: config.schemaFile };
+    }
     const schemaContent = await dumpSchema(config);
     const schemaPath = resolveFromConfig(config, config.schemaFile);
     const baselineIncludes = [];
@@ -2933,39 +2971,50 @@ async function commandNew(config, name, options) {
   const now = /* @__PURE__ */ new Date();
   const primaryDir = config.migrationsDirs[0];
   const migrationsDir = resolveFromConfig(config, primaryDir);
-  if (!existsSync(migrationsDir)) {
+  if (!options?.dryRun && !existsSync(migrationsDir)) {
     await mkdir(migrationsDir, { recursive: true });
   }
   if (options?.expandContract) {
-    await createExpandContractGroup(config, name, now, existingParsed, primaryDir, migrationsDir);
+    await createExpandContractGroup(config, name, now, existingParsed, primaryDir, migrationsDir, options?.dryRun);
   } else {
-    await createSingleFile(config, name, now, existingParsed, primaryDir, migrationsDir);
+    await createSingleFile(config, name, now, existingParsed, primaryDir, migrationsDir, options?.dryRun);
   }
 }
-async function createSingleFile(config, name, now, existingParsed, primaryDir, migrationsDir) {
+async function createSingleFile(config, name, now, existingParsed, primaryDir, migrationsDir, dryRun) {
   const fileName = generateFileName(name, config.naming, { now, existingParsed });
   const filePath = `${migrationsDir}/${fileName}`;
   if (existsSync(filePath)) {
     throw new Error(`File already exists: ${filePath}`);
   }
+  if (dryRun) {
+    console.log(chalk.cyan(`[dry-run] Would create: ${primaryDir}/${fileName}`));
+    return;
+  }
   const content = TEMPLATE.replace("{description}", name).replace("{timestamp}", now.toISOString());
   await writeFile(filePath, content, "utf-8");
   console.log(chalk.green(`Created: ${primaryDir}/${fileName}`));
 }
-async function createExpandContractGroup(config, name, now, existingParsed, primaryDir, migrationsDir) {
+async function createExpandContractGroup(config, name, now, existingParsed, primaryDir, migrationsDir, dryRun) {
   const groupDir = generateGroupDirName(name, config.naming, { now, existingParsed });
   const groupPath = `${migrationsDir}/${groupDir}`;
   if (existsSync(groupPath)) {
     throw new Error(`Directory already exists: ${groupPath}`);
   }
-  await mkdir(groupPath, { recursive: true });
-  const ts = now.toISOString();
   const phaseFiles = [
     { name: "1_expand.sql", template: EXPAND_TEMPLATE },
     { name: "2_backfill.sql", template: BACKFILL_TEMPLATE },
     { name: "3_switch.sql", template: SWITCH_TEMPLATE },
     { name: "4_contract.sql", template: CONTRACT_TEMPLATE }
   ];
+  if (dryRun) {
+    console.log(chalk.cyan(`[dry-run] Would create migration group: ${primaryDir}/${groupDir}/`));
+    for (const pf of phaseFiles) {
+      console.log(chalk.cyan(`  ${pf.name}`));
+    }
+    return;
+  }
+  await mkdir(groupPath, { recursive: true });
+  const ts = now.toISOString();
   for (const pf of phaseFiles) {
     const content = pf.template.replace("{group}", groupDir).replace("{timestamp}", ts);
     await writeFile(`${groupPath}/${pf.name}`, content, "utf-8");
@@ -3106,7 +3155,7 @@ ${content}`);
   }
   return updated;
 }
-async function commandSquash(config) {
+async function commandSquash(config, options) {
   const metadata = await loadMetadata(config);
   const files = await scanMigrations(config);
   const metadataFileSet = new Set(metadata.migrations.map((m) => m.file));
@@ -3115,6 +3164,13 @@ async function commandSquash(config) {
     console.log(chalk.yellow("No new migration files to squash."));
     return;
   }
+  if (options?.dryRun) {
+    console.log(chalk.cyan(`[dry-run] Would squash ${newFiles.length} file(s):`));
+    for (const f of newFiles) {
+      console.log(chalk.cyan(`  ${f.fileName}`));
+    }
+    return;
+  }
   if (isDagMode(metadata, config)) {
     await dagSquash(config, newFiles, metadata);
   } else {
@@ -5177,7 +5233,7 @@ function formatGroupState(state) {
       return chalk.cyan(state);
   }
 }
-async function commandResolve(config, fileName) {
+async function commandResolve(config, fileName, options) {
   const db = createDb(config);
   try {
     await db.connect();
@@ -5194,6 +5250,11 @@ async function commandResolve(config, fileName) {
         `Cannot resolve "${fileName}": latest status is "${latestRecord.status}", expected "failed".`
       );
     }
+    if (options?.dryRun) {
+      console.log(chalk.cyan(`[dry-run] Would resolve: "${fileName}" \u2192 mark as skipped`));
+      console.log(chalk.cyan(`  Current status: ${latestRecord.status}, checksum: ${latestRecord.checksum}`));
+      return;
+    }
     await db.insertRecord(fileName, latestRecord.checksum, "skipped");
     console.log(chalk.green(`\u2713 Resolved: "${fileName}" marked as skipped.`));
     console.log(chalk.gray(`  Ensure a subsequent forward migration covers the intended changes.`));
@@ -6375,16 +6436,17 @@ async function run(fn) {
 }
 var program = new Command();
 program.name(pkg.name).description(pkg.description).version(pkg.version);
-program.command("new <name>").description("Create a new migration SQL file with UTC timestamp").option("--expand-contract", "Create an expand/contract migration group (Class B)").action((name, opts) => run(async () => {
+program.command("new <name>").description("Create a new migration SQL file with UTC timestamp").option("--expand-contract", "Create an expand/contract migration group (Class B)").option("-n, --dry-run", "Show what would be created without writing files").action((name, opts) => run(async () => {
   const config = await loadConfig();
-  await commandNew(config, name, { expandContract: opts.expandContract });
+  await commandNew(config, name, { expandContract: opts.expandContract, dryRun: opts.dryRun });
 }));
-program.command("apply").description("Apply pending migrations via psql").option("--with-drift-check", "Check schema drift before apply and update dump after").option("--from-baseline", "Apply schema.sql first, then remaining migrations").option("--tag <text>", "Tag to record with applied migrations (e.g. commit hash, release tag)").action((opts) => run(async () => {
+program.command("apply").description("Apply pending migrations via psql").option("--with-drift-check", "Check schema drift before apply and update dump after").option("--from-baseline", "Apply schema.sql first, then remaining migrations").option("--tag <text>", "Tag to record with applied migrations (e.g. commit hash, release tag)").option("-n, --dry-run", "List pending migrations without applying").action((opts) => run(async () => {
   const config = await loadConfig();
   const result = await commandApply(config, {
     withDriftCheck: opts.withDriftCheck,
     fromBaseline: opts.fromBaseline,
-    tag: opts.tag
+    tag: opts.tag,
+    dryRun: opts.dryRun
   });
   if (result.errors.length > 0) process.exit(1);
 }));
@@ -6393,9 +6455,9 @@ program.command("check").description("Verify metadata integrity (no DB connectio
   const result = await commandCheck(config);
   if (!result.ok) process.exit(1);
 }));
-program.command("squash").description("Squash multiple new migration files into one").action(() => run(async () => {
+program.command("squash").description("Squash multiple new migration files into one").option("-n, --dry-run", "Show what would be squashed without writing files").action((opts) => run(async () => {
   const config = await loadConfig();
-  await commandSquash(config);
+  await commandSquash(config, { dryRun: opts.dryRun });
 }));
 program.command("lint").description("Run built-in safety rules on migration files").action(() => run(async () => {
   const config = await loadConfig();
@@ -6415,9 +6477,9 @@ program.command("status").description("Show migration status (applied / pending
   const config = await loadConfig();
   await commandStatus(config);
 }));
-program.command("resolve <file>").description("Mark a failed migration as skipped (requires human judgment)").action((file) => run(async () => {
+program.command("resolve <file>").description("Mark a failed migration as skipped (requires human judgment)").option("-n, --dry-run", "Show what would be resolved without writing to DB").action((file, opts) => run(async () => {
   const config = await loadConfig();
-  await commandResolve(config, file);
+  await commandResolve(config, file, { dryRun: opts.dryRun });
 }));
 program.command("editable").description("List migration files that are currently editable (leaf nodes or latest file)").action(() => run(async () => {
   const config = await loadConfig();
@@ -6432,12 +6494,12 @@ program.command("group-status [group]").description("Show migration group state
   const config = await loadConfig();
   await commandGroupStatus(config, group);
 }));
-program.command("baseline").description("Squash applied migrations into schema.sql baseline").option("--keep-since <file...>", "Keep files from this point forward").action((opts) => run(async () => {
+program.command("baseline").description("Squash applied migrations into schema.sql baseline").option("--keep-since <file...>", "Keep files from this point forward").option("-n, --dry-run", "Show what would be baselined without writing files").action((opts) => run(async () => {
   const config = await loadConfig();
-  const result = await commandBaseline(config, { keepSince: opts.keepSince });
+  const result = await commandBaseline(config, { keepSince: opts.keepSince, dryRun: opts.dryRun });
   if (!result.success) process.exit(1);
 }));
-program.command("advance <group> <phase> <status>").description("Record a phase state transition (for external executor)").option("--tag <text>", "Tag to record (e.g. commit hash, release tag)").action((group, phase, status, opts) => run(async () => {
+program.command("advance <group> <phase> <status>").description("Record a phase state transition (for external executor)").option("--tag <text>", "Tag to record (e.g. commit hash, release tag)").option("-n, --dry-run", "Show what would be recorded without writing to DB").action((group, phase, status, opts) => run(async () => {
   const config = await loadConfig();
   const validPhases = ["expand", "backfill", "switch", "contract"];
   const validStatuses = ["running", "completed", "failed"];
@@ -6447,18 +6509,20 @@ program.command("advance <group> <phase> <status>").description("Record a phase
     group,
     phase,
     status,
-    tag: opts.tag
+    tag: opts.tag,
+    dryRun: opts.dryRun
   });
   if (!result.success) process.exit(1);
 }));
-program.command("apply-phase <group> <phase>").description("Apply a specific phase of a migration group via psql").option("--tag <text>", "Tag to record (e.g. commit hash, release tag)").action((group, phase, opts) => run(async () => {
+program.command("apply-phase <group> <phase>").description("Apply a specific phase of a migration group via psql").option("--tag <text>", "Tag to record (e.g. commit hash, release tag)").option("-n, --dry-run", "Show what would be applied without executing SQL").action((group, phase, opts) => run(async () => {
   const config = await loadConfig();
   const validPhases = ["expand", "backfill", "switch", "contract"];
   if (!validPhases.includes(phase)) throw new Error(`Invalid phase: ${phase}`);
   const result = await commandApplyPhase(config, {
     group,
     phase,
-    tag: opts.tag
+    tag: opts.tag,
+    dryRun: opts.dryRun
   });
   if (!result.success) process.exit(1);
 }));