@documentation-robotics/cli 0.2.0 → 0.4.0

package/dist/commands/changeset.js

@@ -4,12 +4,14 @@ import { StagingAreaManager } from "../core/staging-area.js";
 import { ChangesetExporter } from "../core/changeset-exporter.js";
 import { StagedChangesetStorage } from "../core/staged-changeset-storage.js";
 import { ValidationFormatter } from "../validators/validation-formatter.js";
+import { Option } from "commander";
 import * as prompts from "@clack/prompts";
 import path from "path";
 import { isTelemetryEnabled, startSpan, endSpan, startActiveSpan } from "../telemetry/index.js";
-import { getErrorMessage, handleSuccess, handleInfo, handleWarning } from "../utils/errors.js";
+import { CLIError, ErrorCategory, getErrorMessage, handleSuccess, handleInfo, handleWarning } from "../utils/errors.js";
 import { isJson } from "../utils/globals.js";
 import { findElementLayer } from "../utils/element-utils.js";
+import { changesetVerifyCommand } from "./changeset-verify.js";
 function generateImportedChangesetId() {
   return `imported-${Date.now()}`;
 }
@@ -19,7 +21,7 @@ async function changesetCreateCommand(name, options) {
     "changeset.hasDescription": !!options.description
   }) : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !1 }), manager = new StagingAreaManager(model.rootPath, model);
+    const model = await Model.load(options.model, { lazyLoad: !1 }), manager = new StagingAreaManager(model.rootPath, model);
     await manager.load(name) && (isJson() ? console.log(JSON.stringify({ status: "error", code: 1, message: `Changeset '${name}' already exists` })) : console.error(ansis.red(`Error: Changeset '${name}' already exists`)), isTelemetryEnabled && span && span.setStatus({ code: 2, message: "Changeset already exists" }), endSpan(span), process.exit(1));
     let description = options.description;
     if (!description) {
@@ -55,7 +57,7 @@ async function changesetCreateCommand(name, options) {
 async function changesetListCommand(options = {}) {
   const span = isTelemetryEnabled ? startSpan("changeset.list") : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !0 }), changesets = await new StagingAreaManager(model.rootPath, model).list();
+    const model = await Model.load(options.model, { lazyLoad: !0 }), changesets = await new StagingAreaManager(model.rootPath, model).list();
     if (isTelemetryEnabled && span && span.setAttribute("changeset.count", changesets.length), changesets.length === 0) {
       console.log(ansis.yellow("No changesets found")), console.log(), isTelemetryEnabled && span && span.setStatus({ code: 0 }), endSpan(span);
       return;
@@ -83,6 +85,14 @@ Changesets (${changesets.length}):
     endSpan(span);
   }
 }
+function reportCommitValidation(result, details) {
+  if (result.validation.ran === !1) {
+    delete details.validationPassed, details.validationSkipped = !0, isJson() || console.log(ansis.yellow("\u26A0 Validation skipped (--no-validate); run 'dr validate' to check the result"));
+    return;
+  }
+  const preExisting = result.validation.preExistingErrors ?? 0;
+  details.preExistingErrors = preExisting, preExisting > 0 && (details.preExistingSample = result.validation.preExistingSample ?? [], isJson() || console.log(ansis.yellow(`\u26A0 ${preExisting} validation error(s) already in the base model were ignored; the changeset introduced none. Run 'dr validate' to see them.`)));
+}
 async function changesetApplyCommand(name, options) {
   const span = isTelemetryEnabled ? startSpan("changeset.apply", {
     "changeset.name": name,
@@ -90,7 +100,7 @@ async function changesetApplyCommand(name, options) {
     "apply.force": options?.force === !0
   }) : null;
   try {
-    const model = await Model.load(options?.model || process.cwd(), { lazyLoad: !1 }), manager = new StagingAreaManager(model.rootPath, model), changeset = await manager.load(name);
+    const model = await Model.load(options?.model, { lazyLoad: !1 }), manager = new StagingAreaManager(model.rootPath, model), changeset = await manager.load(name);
     if (changeset || (isJson() ? console.log(JSON.stringify({ status: "error", code: 2, message: `Changeset '${name}' not found` })) : console.error(ansis.red(`Error: Changeset '${name}' not found`)), isTelemetryEnabled && span && span.setStatus({ code: 2, message: "Changeset not found" }), endSpan(span), process.exit(1)), isTelemetryEnabled && span && (span.setAttribute("changeset.id", changeset.id), span.setAttribute("changeset.changeCount", changeset.changes.length)), !isJson()) {
       console.log(ansis.bold(`
 Applying changeset: ${ansis.cyan(name)}
@@ -120,7 +130,7 @@ Applying changeset: ${ansis.cyan(name)}
       failed: result.failed,
       validationPassed: result.validation.passed
     };
-    if (result.failed > 0 && (applyDetails.errors = result.validation.errors, !isJson())) {
+    if (reportCommitValidation(result, applyDetails), result.failed > 0 && (applyDetails.errors = result.validation.errors, !isJson())) {
       handleInfo(ansis.red(`\u2717 Failed to apply ${result.failed} change(s):`));
       for (const error of result.validation.errors)
         handleInfo(ansis.dim(`  - ${error}`));
@@ -144,7 +154,7 @@ async function changesetRevertCommand(name, options = {}) {
     "changeset.name": name
   }) : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !1 }), manager = new StagingAreaManager(model.rootPath, model), changeset = await manager.load(name);
+    const model = await Model.load(options.model, { lazyLoad: !1 }), manager = new StagingAreaManager(model.rootPath, model), changeset = await manager.load(name);
     changeset || (isJson() ? console.log(JSON.stringify({ status: "error", code: 2, message: `Changeset '${name}' not found` })) : console.error(ansis.red(`Error: Changeset '${name}' not found`)), isTelemetryEnabled && span && span.setStatus({ code: 2, message: "Changeset not found" }), endSpan(span), process.exit(1)), isTelemetryEnabled && span && (span.setAttribute("changeset.id", changeset.id), span.setAttribute("changeset.changeCount", changeset.changes.length)), isJson() || (console.log(ansis.bold(`
 Reverting changeset: ${ansis.cyan(name)}
 `)), console.log(ansis.dim(`Changes to discard: ${changeset.changes.length}`)));
@@ -173,7 +183,7 @@ async function changesetActivateCommand(name, options = {}) {
     "changeset.name": name
   }) : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), changeset = await manager.load(name);
+    const model = await Model.load(options.model, { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), changeset = await manager.load(name);
     changeset || (isJson() ? console.log(JSON.stringify({ status: "error", code: 2, message: `Changeset '${name}' not found` })) : console.error(ansis.red(`Error: Changeset '${name}' not found`)), isTelemetryEnabled && span && span.setStatus({ code: 2, message: "Changeset not found" }), endSpan(span), process.exit(1)), await manager.setActive(name), handleSuccess(`Activated changeset: ${ansis.bold(name)}`, {
       changesetName: name,
       changesetId: changeset.id
@@ -190,7 +200,7 @@ async function changesetActivateCommand(name, options = {}) {
 async function changesetDeactivateCommand(options = {}) {
   const span = isTelemetryEnabled ? startSpan("changeset.deactivate") : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), active = await manager.getActiveId();
+    const model = await Model.load(options.model, { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), active = await manager.getActiveId();
     if (!active) {
       handleInfo(ansis.yellow("No active changeset")), isTelemetryEnabled && span && (span.setAttribute("changeset.wasActive", !1), span.setStatus({ code: 0 })), endSpan(span);
       return;
@@ -216,7 +226,7 @@ async function changesetDeleteCommand(name, options) {
     "delete.force": options.force === !0
   }) : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), changeset = await manager.load(name);
+    const model = await Model.load(options.model, { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), changeset = await manager.load(name);
     if (changeset || (isJson() ? console.log(JSON.stringify({ status: "error", code: 2, message: `Changeset '${name}' not found` })) : console.error(ansis.red(`Error: Changeset '${name}' not found`)), isTelemetryEnabled && span && span.setStatus({ code: 2, message: "Changeset not found" }), endSpan(span), process.exit(1)), await manager.getActiveId() === changeset.id && (isJson() ? console.log(JSON.stringify({ status: "error", code: 1, message: `Cannot delete active changeset '${name}'` })) : (console.error(ansis.red(`Error: Cannot delete active changeset '${name}'`)), console.log(ansis.dim("  Run `dr changeset deactivate` first"))), isTelemetryEnabled && span && span.setStatus({ code: 2, message: "Cannot delete active changeset" }), endSpan(span), process.exit(1)), !options.force) {
       const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
       if (isTelemetryEnabled && span && span.setAttribute("cli.interactive", isInteractive), isInteractive) {
@@ -248,7 +258,7 @@ async function changesetDeleteCommand(name, options) {
 async function changesetStatusCommand(options = {}) {
   const span = isTelemetryEnabled ? startSpan("changeset.status") : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), active = await manager.getActiveId();
+    const model = await Model.load(options.model, { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), active = await manager.getActiveId();
     if (!active) {
       console.log(ansis.dim("No active changeset")), isTelemetryEnabled && span && (span.setAttribute("changeset.hasActive", !1), span.setStatus({ code: 0 })), endSpan(span);
       return;
@@ -277,7 +287,7 @@ async function changesetStagedCommand(options) {
     "staged.layer": options.layer
   }) : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), activeChangeset = await manager.getActiveId();
+    const model = await Model.load(options.model, { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), activeChangeset = await manager.getActiveId();
     if (!activeChangeset) {
       isJson() ? console.log(JSON.stringify({ status: "error", code: 1, message: "No active changeset" })) : console.error(ansis.red("Error: No active changeset")), isTelemetryEnabled && span && span.setStatus({ code: 2, message: "No active changeset" }), endSpan(span);
       return;
@@ -327,7 +337,7 @@ Staged Changes (${changes.length}):
 async function changesetExplicitStageCommand(elementId, options = {}) {
   const span = isTelemetryEnabled ? startSpan("changeset.stage-explicit", { "stage.elementId": elementId }) : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), activeChangesetId = await manager.getActiveId();
+    const model = await Model.load(options.model, { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), activeChangesetId = await manager.getActiveId();
     if (!activeChangesetId) {
       isJson() ? console.log(JSON.stringify({ status: "error", code: 1, message: "No active changeset" })) : console.error(ansis.red("Error: No active changeset")), isTelemetryEnabled && span && span.setStatus({ code: 2, message: "No active changeset" }), endSpan(span);
       return;
@@ -361,7 +371,7 @@ async function changesetUnstageCommand(elementId, options = {}) {
     "unstage.elementId": elementId
   }) : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), activeChangesetId = await manager.getActiveId();
+    const model = await Model.load(options.model, { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), activeChangesetId = await manager.getActiveId();
     if (!activeChangesetId) {
       isJson() ? console.log(JSON.stringify({ status: "error", code: 1, message: "No active changeset" })) : console.error(ansis.red("Error: No active changeset")), isTelemetryEnabled && span && span.setStatus({ code: 2, message: "No active changeset" }), endSpan(span);
       return;
@@ -395,7 +405,7 @@ async function changesetDiscardCommand(elementId, options = {}) {
     "discard.all": !elementId
   }) : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), activeChangesetId = await manager.getActiveId();
+    const model = await Model.load(options.model, { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), activeChangesetId = await manager.getActiveId();
     if (!activeChangesetId) {
       isJson() ? console.log(JSON.stringify({ status: "error", code: 1, message: "No active changeset" })) : console.error(ansis.red("Error: No active changeset")), isTelemetryEnabled && span && span.setStatus({ code: 2, message: "No active changeset" }), endSpan(span);
       return;
@@ -445,7 +455,7 @@ async function changesetPreviewCommand(options) {
     "preview.layer": options.layer
   }) : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !1 }), manager = new StagingAreaManager(model.rootPath, model), activeChangesetId = await manager.getActiveId();
+    const model = await Model.load(options.model, { lazyLoad: !1 }), manager = new StagingAreaManager(model.rootPath, model), activeChangesetId = await manager.getActiveId();
     if (!activeChangesetId) {
       console.error(ansis.red("Error: No active changeset")), isTelemetryEnabled && span && span.setStatus({ code: 2, message: "No active changeset" }), endSpan(span);
       return;
@@ -498,7 +508,7 @@ async function changesetDiffCommand(options) {
     "diff.layer": options.layer
   }) : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !1 }), manager = new StagingAreaManager(model.rootPath, model), activeChangesetId = await manager.getActiveId();
+    const model = await Model.load(options.model, { lazyLoad: !1 }), manager = new StagingAreaManager(model.rootPath, model), activeChangesetId = await manager.getActiveId();
     if (!activeChangesetId) {
       console.error(ansis.red("Error: No active changeset")), isTelemetryEnabled && span && span.setStatus({ code: 2, message: "No active changeset" }), endSpan(span);
       return;
@@ -533,10 +543,30 @@ Diff: Base Model vs Staged Changes
     endSpan(span);
   }
 }
-async function changesetCommitCommand(options) {
+async function changesetCommitCommand(nameOrId, options) {
+  let restoreActive = null;
+  const restore = async () => {
+    if (!restoreActive)
+      return;
+    const { rootPath, previous } = restoreActive;
+    restoreActive = null;
+    const probe = await Model.load(rootPath, { lazyLoad: !0 }), manager = new StagingAreaManager(probe.rootPath, probe), prior = previous ? await manager.load(previous) : null;
+    prior?.status === "staged" ? (await manager.setActive(previous), isJson() || console.log(ansis.dim(`Changeset '${prior.name}' is active again.`))) : await manager.clearActive();
+  };
   await startActiveSpan("changeset.commit", async (span) => {
     try {
-      const model = await Model.load(options?.model || process.cwd(), { lazyLoad: !1 }), stagingManager = new StagingAreaManager(model.rootPath, model), activeChangesetId = await stagingManager.getActiveId();
+      if (nameOrId) {
+        const probe = await Model.load(options?.model, { lazyLoad: !0 }), probeManager = new StagingAreaManager(probe.rootPath, probe), target = await probeManager.load(nameOrId);
+        if (!target || !target.id)
+          throw new CLIError(`Changeset '${nameOrId}' not found`, ErrorCategory.USER, [
+            'Run "dr changeset list" to see changesets by name and id'
+          ]);
+        if (target.status !== "staged")
+          throw new CLIError(`Changeset '${target.name}' is ${target.status}; only a staged changeset can be committed`, ErrorCategory.USER, ['Run "dr changeset list" to find a staged changeset']);
+        const activeId = await probeManager.getActiveId();
+        activeId !== target.id && (restoreActive = { rootPath: probe.rootPath, previous: activeId }, await probeManager.setActive(target.id));
+      }
+      const model = await Model.load(options?.model, { lazyLoad: !1 }), stagingManager = new StagingAreaManager(model.rootPath, model), activeChangesetId = await stagingManager.getActiveId();
       if (!activeChangesetId) {
         isJson() ? console.log(JSON.stringify({ status: "error", code: 1, message: "No active changeset" })) : console.error(ansis.red("Error: No active changeset")), isTelemetryEnabled && span.setStatus({ code: 2, message: "No active changeset" });
         return;
@@ -549,7 +579,7 @@ async function changesetCommitCommand(options) {
           name: changeset.name,
           changesetId: activeChangesetId,
           stagedChanges: 0
-        }, { verbose: !0 }), isTelemetryEnabled && span.setStatus({ code: 0 });
+        }, { verbose: !0 }), await restore(), isTelemetryEnabled && span.setStatus({ code: 0 });
         return;
       }
       isJson() || (console.log(ansis.bold(`
@@ -567,21 +597,26 @@ Committing changeset: ${ansis.cyan(changeset.name)}`)), console.log(ansis.dim(`S
           stagedChanges: changeCount,
           validationPassed: result.validation.passed
         };
-        (result.skipped ?? 0) > 0 && (commitDetails.skipped = result.skipped, commitDetails.skippedDetails = (result.skippedDetails ?? []).slice(0, 10)), result.failed > 0 && (commitDetails.failed = result.failed);
+        reportCommitValidation(result, commitDetails), (result.skipped ?? 0) > 0 && (commitDetails.skipped = result.skipped, commitDetails.skippedDetails = (result.skippedDetails ?? []).slice(0, 10)), result.failed > 0 && (commitDetails.failed = result.failed);
         const accountedFor = result.committed + (result.skipped ?? 0) + result.failed;
         if (accountedFor < changeCount) {
           const unaccounted = changeCount - accountedFor;
           commitDetails.unaccountedChanges = unaccounted, isJson() || console.log(ansis.yellow(`\u26A0 Warning: ${unaccounted} staged change(s) were not applied, skipped, or reported as failed. This is unexpected \u2014 check the changeset log for details.`));
         }
-        result.driftWarning && (commitDetails.driftDetected = !0, isJson() || console.log(ansis.yellow("\u26A0 Warning: Model had drifted since changeset creation (--force was used)")), isTelemetryEnabled && span.setAttribute("commit.driftDetected", !0)), isTelemetryEnabled && span.setStatus({ code: 0 }), handleSuccess(`Committed ${result.committed} change(s)`, commitDetails, { verbose: !0 }), isJson() || console.log();
+        result.driftWarning && (commitDetails.driftDetected = !0, isJson() || console.log(ansis.yellow("\u26A0 Warning: Model had drifted since changeset creation (--force was used)")), isTelemetryEnabled && span.setAttribute("commit.driftDetected", !0)), isTelemetryEnabled && span.setStatus({ code: 0 }), handleSuccess(`Committed ${result.committed} change(s)`, commitDetails, { verbose: !0 }), await restore(), isJson() || console.log();
       } catch (error) {
         throw isJson() ? console.log(JSON.stringify({ status: "error", code: 1, message: `Commit failed and rolled back: ${getErrorMessage(error)}` })) : console.log(ansis.red(`\u2717 Commit failed and rolled back: ${getErrorMessage(error)}`)), isTelemetryEnabled && span.setAttribute("commit.rolledBack", !0), error;
       }
     } catch (error) {
-      isTelemetryEnabled && (span.recordException(error), span.setStatus({
+      if (isTelemetryEnabled && (span.recordException(error), span.setStatus({
         code: 2,
         message: getErrorMessage(error)
-      })), isJson() ? console.log(JSON.stringify({ status: "error", code: 1, message: getErrorMessage(error) })) : console.error(ansis.red(`Error: ${getErrorMessage(error)}`)), span.end(), process.exit(1);
+      })), isJson())
+        console.log(JSON.stringify({ status: "error", code: 1, message: getErrorMessage(error) }));
+      else if (console.error(ansis.red(`Error: ${getErrorMessage(error)}`)), error instanceof CLIError && error.suggestions?.length)
+        for (const suggestion of error.suggestions)
+          console.error(ansis.dim(`  ${suggestion}`));
+      await restore().catch((restoreError) => console.error(ansis.red(`Error: could not reactivate the previous changeset: ${getErrorMessage(restoreError)}`))), span.end(), process.exit(1);
     }
   }, {
     "commit.validate": options?.validate !== !1,
@@ -594,7 +629,7 @@ async function changesetExportCommand(changesetId, options) {
     "export.format": format
   }) : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !0 }), exporter = new ChangesetExporter(model.rootPath), ext = format === "patch" ? "patch" : format, outputPath = options.output || `${changesetId}.${ext}`, absolutePath = path.isAbsolute(outputPath) ? outputPath : path.join(process.cwd(), outputPath);
+    const model = await Model.load(options.model, { lazyLoad: !0 }), exporter = new ChangesetExporter(model.rootPath), ext = format === "patch" ? "patch" : format, outputPath = options.output || `${changesetId}.${ext}`, absolutePath = path.isAbsolute(outputPath) ? outputPath : path.join(process.cwd(), outputPath);
     isTelemetryEnabled && span && span.setAttribute("export.outputPath", outputPath), await exporter.exportToFile(changesetId, absolutePath, format), handleSuccess(`Exported changeset to ${outputPath}`, {
       changesetId,
       outputPath,
@@ -615,7 +650,7 @@ async function changesetImportCommand(file, options = {}) {
     "import.force": options.force === !0
   }) : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !1 }), exporter = new ChangesetExporter(model.rootPath), absolutePath = path.isAbsolute(file) ? file : path.join(process.cwd(), file), imported = await exporter.importFromFile(absolutePath);
+    const model = await Model.load(options.model, { lazyLoad: !1 }), exporter = new ChangesetExporter(model.rootPath), absolutePath = path.isAbsolute(file) ? file : path.join(process.cwd(), file), imported = await exporter.importFromFile(absolutePath);
     isTelemetryEnabled && span && (span.setAttribute("changeset.name", imported.name), span.setAttribute("changeset.changeCount", imported.changes.length));
     const compatibility = await exporter.validateCompatibility(imported, model);
     if (isTelemetryEnabled && span && (span.setAttribute("import.compatible", compatibility.compatible), span.setAttribute("import.baseSnapshotMatch", compatibility.baseSnapshotMatch)), !compatibility.compatible) {
@@ -734,12 +769,20 @@ Examples:
   $ dr changeset diff
   $ dr changeset diff --layer api`).action(async (options) => {
     await changesetDiffCommand(options);
-  }), changesetGroup.command("commit").description("Apply staged changes to the base model").option("--model <path>", "Path to model root (contains model/manifest.yaml)").option("--validate", "Run validation before commit (default: true)", !0).option("--force", "Commit despite drift warnings", !1).addHelpText("after", `
+  }), changesetGroup.command("commit [changeset]").description("Apply a changeset's staged changes to the base model (the active one, or the one named)").allowExcessArguments(!1).option("--model <path>", "Path to model root (contains model/manifest.yaml)").addOption(new Option("--validate", "Run validation before commit (default)").hideHelp()).option("--no-validate", "Skip validation before commit (validation runs by default; only errors the changeset introduces block, errors already in the base model are reported as a count)").option("--force", "Commit despite drift warnings (does not skip validation)", !1).addHelpText("after", `
+Validation compares the model with and without the changeset. Errors the
+changeset introduces block the commit; errors the base model already had are
+not counted against it, and the output says how many there were.
+
+A named changeset (id or name) need not be active: it is activated for the
+commit, and the changeset that was active before is active again afterwards.
+
 Examples:
   $ dr changeset commit
-  $ dr changeset commit --validate
-  $ dr changeset commit --force`).action(async (options) => {
-    await changesetCommitCommand(options);
+  $ dr changeset commit add-order-api    # commit the changeset named add-order-api
+  $ dr changeset commit --force          # commit despite drift
+  $ dr changeset commit --no-validate    # skip validation entirely`).action(async (name, options) => {
+    await changesetCommitCommand(name, options);
   }), changesetGroup.command("export <changeset-id>").description("Export changeset to portable file").option("--model <path>", "Path to model root (contains model/manifest.yaml)").option("-o, --output <file>", "Output file path").option("-f, --format <format>", "Export format (yaml|json|patch)", "yaml").addHelpText("after", `
 Examples:
   $ dr changeset export api-updates
@@ -753,6 +796,14 @@ Examples:
   $ dr changeset import ../team-changes.json
   $ dr changeset import changes.yaml --force`).action(async (file, options) => {
     await changesetImportCommand(file, options);
+  }), changesetGroup.command("verify [planned]").description("Compare a planned changeset with what was built (an as-built changeset, or the base model)").option("--model <path>", "Path to model root (contains model/manifest.yaml)").option("--against <changeset>", "As-built changeset (ID or name) to compare with").option("--base", "Compare with the base model").option("--extracted", "With --base: the as-built side landed from codebase_extract, so planned parts extraction can't observe are unverifiable, not missing").option("--no-match-by-source", "Do not match elements by shared source file").option("--json", "Output as JSON").addHelpText("after", `
+The planned changeset defaults to the active one.
+
+Examples:
+  $ dr changeset verify export-orders --against export-orders-as-built
+  $ dr changeset verify export-orders --base --json
+  $ dr changeset verify export-orders --base --extracted`).action(async (planned, options) => {
+    await changesetVerifyCommand(planned, options);
   }), changesetGroup.showSuggestionAfterError();
 }
 export {