@seanmars/tospec 0.19.0-beta.0 → 0.19.0-beta.13

package/dist/cli/index.js

@@ -1,45 +1,79 @@
-import { emitFailure } from '../commands/shared-output.js';
-import { Command, Option, InvalidArgumentError } from 'commander';
+import { emitFailure, isCliAbort, emitFailureStatus, normalizeCommanderCode, } from '../commands/shared-output.js';
+import { Command, CommanderError, Option, InvalidArgumentError } from 'commander';
 import { createRequire } from 'module';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { promises as fs } from 'fs';
 import { AI_TOOLS } from '../core/config.js';
-import { UpdateCommand } from '../core/update.js';
-import { ListCommand } from '../core/list.js';
-import { ArchiveCommand } from '../core/archive.js';
-import { MigrateCommand } from '../core/migrate.js';
+import { UpdateCommand, UPDATE_FAILURE_PAYLOAD } from '../core/update.js';
+import { INIT_FAILURE_PAYLOAD } from '../core/init.js';
+import { RULES_FAILURE_PAYLOAD } from '../core/rules.js';
+import { MigrateCommand, MIGRATE_FAILURE_PAYLOAD } from '../core/migrate.js';
 import { resolveRootForCommand, resolveTospecRoot, isRootSelectionError, toRootOutput, } from '../core/root-selection.js';
-import { ValidateCommand } from '../commands/validate.js';
-import { ShowCommand } from '../commands/show.js';
+import { ValidateCommand, VALIDATE_FAILURE_PAYLOAD } from '../commands/validate.js';
+import { ShowCommand, SHOW_FAILURE_PAYLOAD } from '../commands/show.js';
 import { isInteractive } from '../utils/interactive.js';
-import { registerConfigCommand } from '../commands/config.js';
-import { registerDecisionCommand } from '../commands/decision.js';
+import { registerConfigCommand, CONFIG_FAILURE_PAYLOADS } from '../commands/config.js';
+import { registerDecisionCommand, DECISION_NEW_FAILURE_PAYLOAD, DECISION_LIST_FAILURE_PAYLOAD, } from '../commands/decision.js';
 import { registerMetricsCommand } from '../commands/metrics.js';
-import { statusCommand, BATCH_STATUS_FAILURE_PAYLOAD, instructionsCommand, applyInstructionsCommand, templatesCommand, schemasCommand, newChangeCommand, DEFAULT_SCHEMA, } from '../commands/workflow/index.js';
+import { statusCommand, BATCH_STATUS_FAILURE_PAYLOAD, STATUS_FAILURE_PAYLOAD, instructionsCommand, applyInstructionsCommand, INSTRUCTIONS_FAILURE_PAYLOAD, APPLY_ARGUMENT, templatesCommand, TEMPLATES_FAILURE_PAYLOAD, schemasCommand, SCHEMAS_FAILURE_PAYLOAD, newChangeCommand, NEW_CHANGE_FAILURE_PAYLOAD, DEFAULT_SCHEMA, } from '../commands/workflow/index.js';
 /**
  * The options the user actually typed.
  *
- * Commander materialises a negatable option's default: `--no-scenarios` puts
- * `scenarios: true` into the object even when nobody typed it. So "the key is
- * present" and "the user asked for this" are different questions, and a command
- * body testing presence answers the wrong one — `show <change>` warned about an
- * ignored `scenarios` flag on every single run.
- *
- * Dropping the defaults here makes the two questions the same, rather than
- * teaching each consumer a table of per-flag defaults to keep in sync. Safe
- * because every consumer already treats a missing flag and its default
- * identically (`options.scenarios !== false`, `options.interactive === false`).
+ * Commander materialises a negatable option's default (`--no-scenarios` puts
+ * `scenarios: true` in even when nobody typed it), so a body testing presence
+ * answers the wrong question. Safe to drop the defaults here because every
+ * consumer treats a missing flag and its default identically.
  */
 function userSuppliedOptions(options, command) {
     if (!options)
         return {};
     return Object.fromEntries(Object.entries(options).filter(([key]) => command.getOptionValueSource(key) !== 'default'));
 }
+/** `--concurrency` / `--port`: digits only, so `''`, `1.5` and `0x10` are all refused. */
+function positiveIntegerArg(value) {
+    if (!/^\d+$/.test(value.trim()) || Number(value) <= 0) {
+        throw new InvalidArgumentError('Expected a positive integer.');
+    }
+    return value;
+}
+function portArg(value) {
+    if (!/^\d+$/.test(value.trim()) || Number(value) > 65535) {
+        throw new InvalidArgumentError('Expected an integer between 0 and 65535.');
+    }
+    return value;
+}
+const jsonFailureShapes = new WeakMap();
+function withJsonFailureShape(command, shape) {
+    jsonFailureShapes.set(command, shape);
+    return command;
+}
+/**
+ * Makes commander throw instead of exiting, for the whole command tree. Applied
+ * after every subcommand is registered: commander copies `_exitCallback` into a
+ * subcommand at `.command()` time, so setting it on the root alone leaves every
+ * subcommand still calling `process.exit`.
+ */
+function throwOnCommanderExit(command) {
+    command.exitOverride((error) => {
+        // Attach the command so runCli can recover its null-shape; commander's
+        // error carries only a code and a message.
+        error.tospecCommand = command;
+        throw error;
+    });
+    for (const child of command.commands)
+        throwOnCommanderExit(child);
+}
+/**
+ * The root output for a command that takes its root as a path argument rather
+ * than searching: `init`, `update`, `rules`, `migrate`. Their success payloads
+ * report `source: 'explicit'`, so their failures say the same.
+ */
+function explicitRootOutput(targetPath) {
+    return { path: path.resolve(targetPath), source: 'explicit' };
+}
+/** The agent contract: one JSON document on stdout per `--json` failure. */
 function failWithError(error, json) {
-    // The agent contract: every --json failure leaves exactly one JSON
-    // document on stdout (the command's null-shape plus a status array).
-    // Delegates to the one shared failure sink (shared-output.emitFailure).
     emitFailure(json?.enabled, json?.payload ?? {}, error, json?.fallbackCode ?? 'command_error');
 }
 const program = new Command();
@@ -49,20 +83,24 @@ program
     .name('tospec')
     .description('Spec-driven development CLI for requirements and issue workflows')
     .version(version);
-// Kept for backward compatibility with existing invocations; output has no
-// color to disable now, so this is otherwise a no-op.
+// Kept for backward compatibility; output has no color to disable, so this is a
+// no-op.
 program.option('--no-color', 'Disable color output (no-op: output is plain text)');
-// -----------------------------------------------------------------------------
-// Install layer
-// -----------------------------------------------------------------------------
 const availableToolIds = AI_TOOLS.filter((tool) => tool.skillsDir).map((tool) => tool.value);
-const toolsOptionDescription = `Configure AI tools non-interactively. Use "all", "none", or a comma-separated list of: ${availableToolIds.join(', ')}`;
+// Derived from the same table so a future dependency documents itself: a value
+// that drags another target in otherwise reads as "pick this or don't".
+const toolDependencyNotes = AI_TOOLS
+    .filter((tool) => tool.requires?.length)
+    .map((tool) => `${tool.value} implies ${tool.requires.join(', ')}`)
+    .join('; ');
+const toolsOptionDescription = `Configure AI tools non-interactively. Use "all", "none", or a comma-separated list of: ${availableToolIds.join(', ')}${toolDependencyNotes ? ` (${toolDependencyNotes})` : ''}`;
 program
     .command('init [path]')
     .description('Initialize tospec in your project')
     .option('--tools <tools>', toolsOptionDescription)
-    .option('--force', 'Refresh existing generated files without prompting')
+    .option('--force', 'Refresh existing generated files without prompting; does not bypass rule conflicts')
     .option('--profile <profile>', 'Override global config profile (core or custom)')
+    .option('--json', 'Output as JSON (for programmatic use)')
     .action(async (targetPath = '.', options) => {
     try {
         const resolvedPath = path.resolve(targetPath);
@@ -88,37 +126,70 @@ program
             tools: options?.tools,
             force: options?.force,
             profile: options?.profile,
+            json: options?.json,
         });
         await initCommand.execute(targetPath);
     }
     catch (error) {
-        failWithError(error);
+        failWithError(error, {
+            enabled: options?.json,
+            payload: { ...INIT_FAILURE_PAYLOAD, root: explicitRootOutput(targetPath) },
+            fallbackCode: 'init_error',
+        });
     }
 });
 program
     .command('update [path]')
     .description('Update tospec instruction files')
-    .option('--force', 'Force update even when tools are up to date')
+    .option('--force', 'Force update even when tools are up to date; does not bypass rule conflicts')
+    .option('--json', 'Output as JSON (for programmatic use)')
     .action(async (targetPath = '.', options) => {
     try {
-        const updateCommand = new UpdateCommand({ force: options?.force });
+        const updateCommand = new UpdateCommand({ force: options?.force, json: options?.json });
         await updateCommand.execute(targetPath);
     }
     catch (error) {
-        failWithError(error);
+        failWithError(error, {
+            enabled: options?.json,
+            payload: { ...UPDATE_FAILURE_PAYLOAD, root: explicitRootOutput(targetPath) },
+            fallbackCode: 'update_error',
+        });
+    }
+});
+program
+    .command('rules [path]')
+    .description('Refresh workflow rules for tools with installed tospec skills')
+    .option('--json', 'Output as JSON (for programmatic use)')
+    .action(async (targetPath = '.', options) => {
+    try {
+        const { RulesCommand } = await import('../core/rules.js');
+        await new RulesCommand().execute(targetPath, { json: options?.json });
+    }
+    catch (error) {
+        failWithError(error, {
+            enabled: options?.json,
+            payload: { ...RULES_FAILURE_PAYLOAD, root: explicitRootOutput(targetPath) },
+            fallbackCode: 'rules_error',
+        });
     }
 });
 program
     .command('migrate [openspec-dir]')
     .description('Migrate an OpenSpec project into tospec format (default source: ./openspec)')
     .option('-f, --force', 'Skip confirmation prompt')
+    .option('--json', 'Output as JSON (non-interactive; requires --force)')
     .action(async (openspecDir, options) => {
     try {
         const migrateCommand = new MigrateCommand();
         await migrateCommand.execute(openspecDir, options);
     }
     catch (error) {
-        failWithError(error);
+        failWithError(error, {
+            enabled: options?.json,
+            // migrate always writes `tospec/` into the cwd, so the root is known here.
+            payload: { ...MIGRATE_FAILURE_PAYLOAD, root: explicitRootOutput(process.cwd()) },
+            fallbackCode: 'migrate_error',
+        });
     }
 });
 program
@@ -130,31 +201,53 @@ program
     .option('--type <type>', 'Filter changes by type: "requirement" or "issue"')
     .option('--json', 'Output as JSON (for programmatic use)')
     .action(async (options) => {
+    // Resolve first so a failure can still report where the CLI was pointed.
+    // The data key is `null`, never `[]`: an empty array is indistinguishable
+    // from the successful "no active changes" answer.
+    let resolvedRoot = null;
+    const failurePayload = () => ({
+        ...(options?.specs ? { specs: null } : { changes: null }),
+        root: resolvedRoot ? toRootOutput(resolvedRoot) : null,
+    });
     try {
-        if (options?.type && options.type !== 'requirement' && options.type !== 'issue') {
-            throw new Error(`Invalid --type '${options.type}'. Expected "requirement" or "issue".`);
-        }
-        const root = await resolveRootForCommand({}, {
+        resolvedRoot = await resolveRootForCommand({}, {
             json: options?.json,
-            failurePayload: options?.specs ? { specs: [], root: null } : { changes: [], root: null },
+            // An implicit root means no ancestor is a tospec project, and listing
+            // "no changes" there answers about a place that was never checked.
+            allowImplicitRoot: false,
+            failurePayload: failurePayload(),
         });
-        if (!root) {
+        if (!resolvedRoot) {
             return;
         }
+        if (options?.type && options.type !== 'requirement' && options.type !== 'issue') {
+            throw new Error(`Invalid --type '${options.type}'. Expected "requirement" or "issue".`);
+        }
+        // Two listings with no ordering between them; picking one silently
+        // answers a question the user did not ask.
+        if (options?.specs && options?.changes) {
+            throw new Error('Pass either --specs or --changes, not both: they select different listings and there is no ordering between them.');
+        }
+        // Specs have no type. A warning, not an error: the requested listing is
+        // still well-defined. On stderr, so `--json` stdout stays one document.
+        if (options?.specs && options?.type) {
+            console.error('Warning: Ignoring flags not applicable to --specs: type');
+        }
+        const { ListCommand } = await import('../core/list.js');
         const listCommand = new ListCommand();
         const mode = options?.specs ? 'specs' : 'changes';
         const sort = options?.sort === 'name' ? 'name' : 'recent';
-        await listCommand.execute(root.path, mode, {
+        await listCommand.execute(resolvedRoot.path, mode, {
             sort,
             json: options?.json,
             type: options?.type,
-            ...(options?.json ? { root: toRootOutput(root) } : {}),
+            ...(options?.json ? { root: toRootOutput(resolvedRoot) } : {}),
         });
     }
     catch (error) {
         failWithError(error, {
             enabled: options?.json,
-            payload: options?.specs ? { specs: [], root: null } : { changes: [], root: null },
+            payload: failurePayload(),
             fallbackCode: 'list_error',
         });
     }
@@ -163,12 +256,13 @@ program
     .command('archive [change-name]')
     .description('Archive a completed change and update main specs')
     .option('-y, --yes', 'Skip confirmation prompts')
-    .option('--skip-specs', 'Skip spec update operations (useful for infrastructure, tooling, or doc-only changes)')
+    .option('--skip-specs', 'Skip merging delta specs into the main specs for this run only; validation still applies, so an sdd change with no deltas also needs skip_specs: true in its .tospec.yaml (schemas whose specs are optional, such as issue, do not)')
     .option('--no-validate', 'Skip validation (not recommended, requires confirmation)')
     .option('--require-sync', 'Require a passing sync-report.md in the change directory before archiving')
     .option('--json', 'Output as JSON (non-interactive)')
     .action(async (changeName, options) => {
     try {
+        const { ArchiveCommand } = await import('../core/archive.js');
         const archiveCommand = new ArchiveCommand();
         await archiveCommand.execute(changeName, options);
     }
@@ -182,17 +276,13 @@ program
     .option('--all', 'Validate all changes and specs')
     .option('--changes', 'Validate all changes')
     .option('--specs', 'Validate all specs')
-    .option('--type <type>', 'Specify item type when ambiguous: change|spec')
+    // `.choices`, as `show --type` does: an unknown value used to fall through
+    // normalizeType as undefined and silently validate by auto-detection.
+    .addOption(new Option('--type <type>', 'Specify item type when ambiguous').choices(['change', 'spec']))
     .option('--strict', 'Enable strict validation mode')
     .option('--json', 'Output validation results as JSON')
     .addOption(new Option('--concurrency <n>', 'Max concurrent validations (defaults to env TOSPEC_CONCURRENCY or 6)')
-    .argParser((value) => {
-    const n = parseInt(value, 10);
-    if (Number.isNaN(n) || n <= 0 || String(n) !== value.trim()) {
-        throw new InvalidArgumentError('Expected a positive integer.');
-    }
-    return value;
-}))
+    .argParser(positiveIntegerArg))
     .option('--no-interactive', 'Disable interactive prompts')
     .action(async (itemName, options) => {
     try {
@@ -200,17 +290,26 @@ program
         await validateCommand.execute(itemName, options);
     }
     catch (error) {
-        failWithError(error, { enabled: options?.json, fallbackCode: 'validate_error' });
+        failWithError(error, {
+            enabled: options?.json,
+            payload: VALIDATE_FAILURE_PAYLOAD,
+            fallbackCode: 'validate_error',
+        });
     }
 });
 program
     .command('show [item-name]')
     .description('Show a change or spec')
     .option('--json', 'Output as JSON')
-    .option('--type <type>', 'Specify item type when ambiguous: change|spec')
+    .addOption(new Option('--type <type>', 'Specify item type when ambiguous: change|spec').choices([
+    'change',
+    'spec',
+]))
     .option('--no-interactive', 'Disable interactive prompts')
-    .option('--deltas-only', 'Show only deltas (JSON only, change)')
-    .option('--requirements-only', 'Alias for --deltas-only (deprecated, change)')
+    // No-ops kept for compatibility: a change's --json payload is always
+    // id/title/deltaCount/deltas, with no wider shape to narrow.
+    .option('--deltas-only', 'No-op: a change\'s JSON is always deltas (kept for compatibility)')
+    .option('--requirements-only', 'No-op: deprecated alias for --deltas-only')
     .option('--diff', 'Show per-requirement diffs against the main specs (change)')
     .option('--requirements', 'JSON only: Show only requirements (exclude scenarios)')
     .option('--no-scenarios', 'JSON only: Exclude scenario content')
@@ -218,17 +317,16 @@ program
     .action(async (itemName, options, command) => {
     try {
         const showCommand = new ShowCommand();
-        // Defaults stripped so warnIrrelevantFlags reports the flags the user
-        // typed, not the ones commander filled in.
         await showCommand.execute(itemName, userSuppliedOptions(options, command));
     }
     catch (error) {
-        failWithError(error, { enabled: options?.json, fallbackCode: 'show_error' });
+        failWithError(error, {
+            enabled: options?.json,
+            payload: SHOW_FAILURE_PAYLOAD,
+            fallbackCode: 'show_error',
+        });
     }
 });
-// ═══════════════════════════════════════════════════════════
-// Workflow / engine commands (agent contract)
-// ═══════════════════════════════════════════════════════════
 program
     .command('status')
     .description('Display artifact completion status for a change')
@@ -243,9 +341,7 @@ program
     catch (error) {
         failWithError(error, {
             enabled: options.json,
-            // The batch null-shape; the single-change failure shape is
-            // pre-existing contract and stays payload-free.
-            payload: options.all ? BATCH_STATUS_FAILURE_PAYLOAD : undefined,
+            payload: options.all ? BATCH_STATUS_FAILURE_PAYLOAD : STATUS_FAILURE_PAYLOAD,
             fallbackCode: 'change_error',
         });
     }
@@ -258,7 +354,7 @@ program
     .option('--json', 'Output as JSON')
     .action(async (artifactId, options) => {
     try {
-        if (artifactId === 'apply') {
+        if (artifactId === APPLY_ARGUMENT) {
             await applyInstructionsCommand(options);
         }
         else {
@@ -266,7 +362,11 @@ program
         }
     }
     catch (error) {
-        failWithError(error, { enabled: options.json, fallbackCode: 'change_error' });
+        failWithError(error, {
+            enabled: options.json,
+            payload: INSTRUCTIONS_FAILURE_PAYLOAD,
+            fallbackCode: 'change_error',
+        });
     }
 });
 program
@@ -279,7 +379,7 @@ program
         await templatesCommand(options);
     }
     catch (error) {
-        failWithError(error, { enabled: options.json, payload: { templates: null }, fallbackCode: 'templates_error' });
+        failWithError(error, { enabled: options.json, payload: TEMPLATES_FAILURE_PAYLOAD, fallbackCode: 'templates_error' });
     }
 });
 program
@@ -291,7 +391,7 @@ program
         await schemasCommand(options);
     }
     catch (error) {
-        failWithError(error, { enabled: options.json, payload: { schemas: null }, fallbackCode: 'schemas_error' });
+        failWithError(error, { enabled: options.json, payload: SCHEMAS_FAILURE_PAYLOAD, fallbackCode: 'schemas_error' });
     }
 });
 const newCmd = program.command('new').description('Create new items');
@@ -315,8 +415,10 @@ newCmd
 });
 program
     .command('dashboard [path]')
-    .description('Start a local read-only web dashboard for this tospec project')
-    .option('-p, --port <n>', 'Port to listen on', '5620')
+    .description('Start a local dashboard; task checkbox updates are the only writes, confined to this tospec root and blocked for archived or sync-certified changes')
+    // Parsed like --concurrency: `Number('')` is 0, so a bare `--port ''` used to
+    // pass the range check and bind an OS-chosen port.
+    .addOption(new Option('-p, --port <n>', 'Port to listen on (0-65535)').default('5620').argParser(portArg))
     .option('--host <addr>', 'Host to bind', '127.0.0.1')
     .option('-o, --open', 'Open the dashboard in a browser after starting')
     .option('-d, --detach', 'Run the dashboard in the background and return immediately')
@@ -326,10 +428,10 @@ program
     .action(async (targetPath = '.', options) => {
     try {
         const dashboard = await import('../commands/dashboard.js');
-        // --list is global: don't require being inside a tospec project.
+        // --list is global: no tospec project required.
         if (options?.list) {
-            // Same candidate set as --stop, so the two never disagree about what
-            // is running — `--stop` points at this command when it cannot prompt.
+            // Same candidate set as --stop, which points here when it cannot
+            // prompt, so the two never disagree about what is running.
             const running = await dashboard.collectStoppableDashboards(null);
             if (running.length === 0) {
                 console.log('No dashboards are running.');
@@ -345,7 +447,7 @@ program
         const startPath = path.resolve(targetPath);
         // --stop is project-independent, like --list: a path with no tospec root
         // has no dashboard of its own, which is the cue to offer the full list
-        // rather than fail. Only a root *selection* failure degrades to null.
+        // rather than fail.
         if (options?.stop) {
             const stopRoot = await resolveTospecRoot({ startPath, allowImplicitRoot: false }).catch((err) => {
                 if (isRootSelectionError(err))
@@ -360,9 +462,8 @@ program
             }
             let targets = dashboard.selectStopTargets(candidates, stopRootPath);
             if (targets.length === 0) {
-                // Nothing here matches this path — let the user pick which to stop.
-                // `--stop` runs outside a project too, so this branch is reachable
-                // non-interactively, where there is nobody to answer the prompt.
+                // Nothing matches this path, so let the user pick. Reachable
+                // non-interactively too, where there is nobody to answer.
                 const listed = candidates.map((d) => `  ${dashboard.formatRunningDashboard(d, '  ')}`);
                 if (!isInteractive()) {
                     throw new dashboard.DashboardStopError(['No dashboard for this path, and no terminal to choose one from.', ...listed].join('\n'), 'Re-run from an interactive terminal, or see tospec dashboard --list.');
@@ -392,10 +493,12 @@ program
             }
             return;
         }
+        // Already validated by portArg; the default is the only unparsed value.
+        const portValue = Number(options?.port ?? 5620);
         // Starting a dashboard still requires a root — only --stop is lenient.
         const root = await resolveTospecRoot({ startPath, allowImplicitRoot: false });
         const runOpts = {
-            port: Number(options?.port ?? 5620),
+            port: portValue,
             host: options?.host ?? '127.0.0.1',
             open: options?.open,
             allowRemote: options?.allowRemote,
@@ -413,9 +516,90 @@ program
 registerConfigCommand(program);
 registerDecisionCommand(program);
 registerMetricsCommand(program);
+function commandAt(...names) {
+    let current = program;
+    for (const name of names) {
+        const next = current.commands.find((c) => c.name() === name);
+        if (!next)
+            throw new Error(`No such command to register a JSON failure shape for: ${names.join(' ')}`);
+        current = next;
+    }
+    return current;
+}
+// The `--json` null-shapes in one table, so the contract rule (a failure payload
+// mirrors its success payload with the data keys nulled) is checkable in one
+// place. Each entry reuses the object the command's own catch block passes to
+// `failWithError`, never a literal: commander gives every command two failure
+// layers, and copies drift.
+withJsonFailureShape(commandAt('init'), () => INIT_FAILURE_PAYLOAD);
+withJsonFailureShape(commandAt('update'), () => UPDATE_FAILURE_PAYLOAD);
+withJsonFailureShape(commandAt('rules'), () => RULES_FAILURE_PAYLOAD);
+withJsonFailureShape(commandAt('migrate'), () => MIGRATE_FAILURE_PAYLOAD);
+withJsonFailureShape(commandAt('list'), (argv) => argv.includes('--specs') ? { specs: null, root: null } : { changes: null, root: null });
+withJsonFailureShape(commandAt('archive'), () => ({ archive: null, root: null }));
+withJsonFailureShape(commandAt('validate'), () => VALIDATE_FAILURE_PAYLOAD);
+withJsonFailureShape(commandAt('show'), () => SHOW_FAILURE_PAYLOAD);
+withJsonFailureShape(commandAt('status'), (argv) => argv.includes('--all') ? BATCH_STATUS_FAILURE_PAYLOAD : STATUS_FAILURE_PAYLOAD);
+withJsonFailureShape(commandAt('instructions'), () => INSTRUCTIONS_FAILURE_PAYLOAD);
+withJsonFailureShape(commandAt('templates'), () => TEMPLATES_FAILURE_PAYLOAD);
+withJsonFailureShape(commandAt('schemas'), () => SCHEMAS_FAILURE_PAYLOAD);
+withJsonFailureShape(commandAt('new', 'change'), () => NEW_CHANGE_FAILURE_PAYLOAD);
+withJsonFailureShape(commandAt('decision', 'new'), () => DECISION_NEW_FAILURE_PAYLOAD);
+withJsonFailureShape(commandAt('decision', 'list'), () => DECISION_LIST_FAILURE_PAYLOAD);
+// `edit` speaks no --json and is deliberately absent.
+for (const [subcommand, payload] of Object.entries(CONFIG_FAILURE_PAYLOADS)) {
+    withJsonFailureShape(commandAt('config', subcommand), () => payload);
+}
 export { program };
+/**
+ * The command's full invocation path, not just its leaf name. `command.name()`
+ * is wrong for a nested command: `--help` advice naming the leaf of `new change`
+ * points at no command at all, and the leaf of `decision new` is a real command
+ * answering a different question.
+ */
+function commandPath(command) {
+    const names = [];
+    // Stops at the program itself, whose name the caller's template already has.
+    for (let node = command; node?.parent; node = node.parent) {
+        names.unshift(node.name());
+    }
+    return names.join(' ');
+}
 export function runCli(argv = process.argv) {
-    program.parse(argv);
+    throwOnCommanderExit(program);
+    try {
+        program.parse(argv);
+    }
+    catch (error) {
+        if (error instanceof CommanderError) {
+            // `--help` and `--version` come through here having already printed what
+            // they were asked for, so only a non-zero exit is a failure.
+            if (error.exitCode === 0)
+                return;
+            const wantsJson = argv.includes('--json');
+            if (wantsJson) {
+                const command = error.tospecCommand;
+                const shape = command ? jsonFailureShapes.get(command) : undefined;
+                emitFailureStatus(shape ? shape(argv) : {}, {
+                    severity: 'error',
+                    code: normalizeCommanderCode(error.code),
+                    message: error.message,
+                    fix: `See tospec ${commandPath(command)} --help`.replace(/\s+/g, ' ').trim(),
+                });
+                return;
+            }
+            process.exitCode = error.exitCode || 1;
+            return;
+        }
+        // The one abort mechanism for places that cannot stop the run by returning
+        // (commander's preAction hooks). Setting the exit code and returning lets
+        // stdout flush, which `process.exit` does not guarantee.
+        if (isCliAbort(error)) {
+            process.exitCode = 1;
+            return;
+        }
+        throw error;
+    }
 }
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
     runCli();