commander-wizard 0.0.1 → 0.0.3

package/README.md

@@ -17,7 +17,7 @@ Save as `cli.mjs`:
 
 ```js
 import { Command } from 'commander';
-import { addWizard, WizardCancelledError } from 'commander-wizard';
+import { addWizard } from 'commander-wizard';
 
 const program = new Command('deploy-cli');
 const deploy = program.command('deploy')
@@ -30,11 +30,7 @@ const deploy = program.command('deploy')
 // Add your commands and options before calling addWizard.
 addWizard(program, { invocation: ['node', 'cli.mjs'] });
 
-try {
-  await program.parseAsync();
-} catch (error) {
-  if (!(error instanceof WizardCancelledError)) throw error;
-}
+await program.parseAsync();
 ```
 
 ```sh
@@ -68,9 +64,10 @@ After confirmation, Commander applies parsers, requirements, conflicts, and
 implications before running your action. Restart the wizard to correct invalid
 inputs; custom parsers do not run during prompting.
 
-Declining or pressing Ctrl-C throws `WizardCancelledError` without running your
-hooks or action. Catch it as in the example. For Commander errors, configure
-`exitOverride()` if you need to catch them instead of exiting.
+Declining or pressing Ctrl-C exits cleanly with code 0 without running your
+hooks or action. Wizard failures print like Commander errors and exit 1. For
+tests and embedding, configure `exitOverride()` to catch everything instead
+of exiting — the cancellation code is `commander-wizard.cancelled`.
 
 You keep Commander's parsing and validation for ordinary invocations. Your
 action receives no wizard-trigger option after a wizard run.
@@ -129,8 +126,9 @@ a numeric default alone does not perform that conversion.
 
 ## Compatibility limits
 
-Use root-only or nested leaf actions with global scalar options, short flags,
-positive/negative boolean pairs, positional arguments, choices, and leaf variadics.
+Use global scalar options, short flags, positive/negative boolean pairs,
+positional arguments, choices, and leaf variadics. Actions are optional:
+commands that read `.opts()` after parsing work unchanged in wizard mode.
 
 In wizard mode, put the full command path before flags:
 `cli group command --wizard --flag=value`. Keep short flags separate; avoid `-abc` and
@@ -138,8 +136,8 @@ In wizard mode, put the full command path before flags:
 
 You cannot use these Commander features in wizard mode:
 
-- Executable subcommands, legacy command listeners, actions on commands with
-  children, or implicit/default subcommands.
+- Executable subcommands, implicit/default subcommands, or targeting commands
+  with children.
 - Ancestor positional arguments or variadic options, positional/pass-through
   option modes, or shadowed global option names/flags.
 - Environment-bound options, optional option values (`--color [value]`), presets,

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { addWizard, WizardCancelledError } from './wizard.js';
+export { addWizard } from './wizard.js';
 export type { WizardOptions } from './wizard.js';

package/dist/index.js

@@ -1 +1 @@
-export { addWizard, WizardCancelledError } from './wizard.js';
+export { addWizard } from './wizard.js';

package/dist/wizard.d.ts

@@ -1,7 +1,4 @@
 import type { Argument, Command, Option } from 'commander';
-export declare class WizardCancelledError extends Error {
-    constructor();
-}
 export interface WizardOptions {
     /** Commander boolean flag declaration. Defaults to --wizard. */
     flags?: string;

package/dist/wizard.js

@@ -1,10 +1,13 @@
 import * as p from '@clack/prompts';
 import { inspect } from 'node:util';
-export class WizardCancelledError extends Error {
+class WizardError extends Error {
+}
+/** Aborts collection on cancel; surfaced to callers through Commander's exit channel. */
+class WizardCancelledError extends Error {
     constructor() { super('Wizard cancelled.'); this.name = 'WizardCancelledError'; }
 }
 const installed = new WeakSet();
-const fail = (message) => { throw new Error(`Wizard: ${message}`); };
+const fail = (message) => { throw new WizardError(`Wizard: ${message}`); };
 /** Decorate an already-configured program. No global/prototype patching; use parseAsync for wizard mode. */
 export function addWizard(program, config = {}) {
     if (installed.has(program))
@@ -37,29 +40,40 @@ export function addWizard(program, config = {}) {
         cmd.on(`option:${flagOption.name()}`, () => fail('use parseAsync() with an explicit command path and unbundled flags for wizard mode.'));
     }
     program.parseAsync = async function (argv, options) {
-        const args = userArgs(argv, options?.from);
-        if (!requested(args, markers))
-            return await parseAsync.call(this, argv, options);
-        if (options?.from === 'electron' || (!argv && process.versions.electron))
-            fail('Electron wizard invocations are unsupported; pass explicit user arguments.');
-        let input;
         try {
-            input = scan(program, args, markers);
+            const args = userArgs(argv, options?.from);
+            if (!requested(args, markers))
+                return await parseAsync.call(this, argv, options);
+            if (options?.from === 'electron' || (!argv && process.versions.electron))
+                fail('Electron wizard invocations are unsupported; pass explicit user arguments.');
+            let input;
+            try {
+                input = scan(program, args, markers);
+            }
+            catch {
+                // Commander can distinguish reserved text used as data in grammars we do not support.
+                // An actual wizard option is stopped by the option listener above.
+                return await parseAsync.call(this, argv, options);
+            }
+            // A marker consumed as an option value is data, not a wizard request.
+            if (!input.wizard)
+                return await parseAsync.call(this, argv, options);
+            checkLayout(input.chain, wizardKey);
+            if (!process.stdin.isTTY || !process.stdout.isTTY)
+                fail('interactive input requires a TTY.');
+            const completed = await collect(input, config, wizardKey);
+            // Commander alone owns coercion, validation, hooks, and action dispatch.
+            return await parseAsync.call(this, completed, { from: 'user' });
         }
-        catch {
-            // Commander can distinguish reserved text used as data in grammars we do not support.
-            // An actual wizard option is stopped by the option listener above.
-            return await parseAsync.call(this, argv, options);
+        catch (error) {
+            // Route our failures through Commander's own channel: stock CLI behavior by default,
+            // catchable via .exitOverride() for tests and embedding — no library-specific catches.
+            if (error instanceof WizardCancelledError)
+                exitVia(this, 0, 'commander-wizard.cancelled', 'Wizard cancelled.');
+            if (error instanceof WizardError)
+                this.error(error.message);
+            throw error;
         }
-        // A marker consumed as an option value is data, not a wizard request.
-        if (!input.wizard)
-            return await parseAsync.call(this, argv, options);
-        checkLayout(input.chain, wizardKey);
-        if (!process.stdin.isTTY || !process.stdout.isTTY)
-            fail('interactive input requires a TTY.');
-        const completed = await collect(input, config, wizardKey);
-        // Commander alone owns coercion, validation, hooks, and action dispatch.
-        return await parseAsync.call(this, completed, { from: 'user' });
     };
     installed.add(program);
     return program;
@@ -155,8 +169,9 @@ function checkLayout(chain, wizardKey) {
         }
     }
     const leaf = chain.at(-1);
-    if (leaf.commands.length || !Reflect.get(leaf, '_actionHandler'))
-        fail('select an explicit in-process action command. Legacy listeners are unsupported.');
+    // No action requirement: parse-then-.opts() CLIs work unchanged — the re-parse validates and populates.
+    if (leaf.commands.length)
+        fail('select an explicit leaf command; commands with children are ambiguous in wizard mode.');
 }
 function defaults(owner, config) {
     if (owner.defaultValue === undefined)
@@ -309,7 +324,8 @@ async function collect(input, config, wizardKey) {
             summary.push(`${arg.name()}: ${inspect(arg.variadic ? values : values[0])}`);
         }
         positional.push(...input.positionals.slice(cursor)); // let Commander report excess arguments
-        argv.push('--', ...positional);
+        if (positional.length)
+            argv.push('--', ...positional);
         const invocation = config.invocation ?? [process.execPath, ...process.execArgv, process.argv[1] ?? fail('provide invocation.')];
         const tokens = [...invocation, ...argv];
         if (tokens.some(token => token.includes('\0')))
@@ -345,6 +361,12 @@ function unwrap(value) {
     }
     return value;
 }
+/** Exits through Commander's own channel so .exitOverride() stays authoritative. */
+function exitVia(program, exitCode, code, message) {
+    const exit = Reflect.get(program, '_exit');
+    exit.call(program, exitCode, code, message);
+    throw new Error('unreachable: _exit exits, or an exitOverride callback throws');
+}
 /** POSIX shell quoting. Windows shells are not supported. */
 function shellQuote(value) {
     return /^[\w.,:/@%+=-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commander-wizard",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Interactive wizard mode for commander CLIs — collect, review, and rerun command inputs",
   "keywords": [
     "commander",