@sdxc/cli 2026.10.16 → 2026.10.23

package/README.md

@@ -157,7 +157,7 @@ What to ask when a flag or argument is missing on a terminal: `prompt.select({ m
 
 #### `createCLI({ name, version?, commands, middleware? })`
 
-The program. `--help` and `--version` come for free.
+The program. `--help` and `--version` come for free, and `--help --json` prints the same facts as data.
 
 #### `cli.map(command, handler)`
 
@@ -167,6 +167,19 @@ Binds a handler, a `createCommand(...)` or a `lazy(...)` import to a command.
 
 Runs the command and answers its exit code; `io` replaces the process's `cwd`, `env`, streams or `exec`.
 
+#### `cli.describe(path?)`
+
+The contract as data: every visible command under `path` with its arguments, flags and examples, as `--help --json` prints it.
+
+#### `cli.check(argv)`
+
+Checks a command line without running it: the command, every flag and every value against its schema. A value a prompt would ask for passes. Answers the command's path, or a `UsageError` listing every problem.
+
+```typescript
+let checked = await cli.check(["greet", "Ada", "--shuot"]);
+if (isFailure(checked)) console.error(checked.error.message); // Unknown flag --shuot …
+```
+
 #### `createCommand(command, handler)`
 
 A handler typed from its command, for a module of its own; pass `{ middleware, handler }` for middleware this command alone runs.

package/dist/cli.d.ts

@@ -6,12 +6,15 @@
  * @author [Sergio Xalambrí](https://sergiodxa.com)
  * @copyright Sergio Xalambrí 2026
  */
+import type { Result } from "@sdxc/result";
 import type { ArgumentsOf, FlagsOf, Group, Node } from "./command.js";
+import type { CommandDescription } from "./describe.js";
 import type { CommandAction, CommandHandler } from "./handler.js";
 import type { Lazy } from "./lazy.js";
 import type { AnyCommandMiddleware, ChainProperties } from "./middleware.js";
 import type { RunIO, Script } from "./session.js";
 import { CommandContext } from "./context.js";
+import { UsageError } from "./errors.js";
 /** What a CLI is built from. */
 export interface CLIOptions<Commands extends Group, Chain extends readonly AnyCommandMiddleware[]> {
     /** The program name, as the usage line prints it. */
@@ -48,6 +51,28 @@ export interface CLI<Commands extends Group = Group, Chain extends readonly AnyC
      * @example process.exitCode = await cli.run(process.argv.slice(2));
      */
     run(argv: readonly string[], io?: RunIO): Promise<number>;
+    /**
+     * The contract as data, the facts `--help --json` prints: the whole program, or the command
+     * `path` names, with every visible member below it.
+     *
+     * @returns The description, or `undefined` when `path` names no command
+     * @example let make = cli.describe(["make"]);
+     */
+    describe(path?: readonly string[]): CommandDescription | undefined;
+    /**
+     * Checks `argv` the way a run does before it asks or runs anything: the command it names, every
+     * flag, and every value against its schema. A missing value that a prompt would ask for passes,
+     * since a terminal run asks for it. Nothing is loaded and no handler runs.
+     *
+     * @returns The path of the command `argv` reaches, or a usage failure listing every problem
+     * @example let checked = await cli.check(["make", "controller", "posts", "--method", "form"]);
+     */
+    check(argv: readonly string[]): Promise<Result<CheckedCommand, UsageError>>;
+}
+/** A command line `check()` accepted. */
+export interface CheckedCommand {
+    /** The words that reached the command; empty for the root. */
+    path: string[];
 }
 /**
  * Builds a CLI over a command contract.

package/dist/cli.js

@@ -8,7 +8,9 @@
  */
 import { failure, isFailure, success } from "@sdxc/result";
 import { CommandContext } from "./context.js";
+import { describeEntry } from "./describe.js";
 import { CancelledError, EXIT_CODES, exitCodeOf, UsageError } from "./errors.js";
+import { ExecError } from "./exec.js";
 import { isAction } from "./handler.js";
 import { renderHelp } from "./help.js";
 import { isLazy } from "./lazy.js";
@@ -45,6 +47,15 @@ export function createCLI(options) {
             bindings.set(target, resolver(binding));
         },
         run: (argv, io = {}) => execute(cli, argv, io, undefined),
+        describe(path = []) {
+            let entry = tree.root;
+            for (let word of path)
+                entry = entry?.children.get(word);
+            if (entry === undefined)
+                return undefined;
+            return describeEntry(entry, { version: options.version, description: options.description });
+        },
+        check: (argv) => check(tree, options.version !== undefined, argv),
     };
     INTERNALS.set(cli, {
         tree,
@@ -82,6 +93,35 @@ function normalize(binding) {
 export function runScripted(cli, argv, io, script) {
     return execute(cli, argv, io, script);
 }
+/**
+ * Whether `--json` rides along with `--help`, before any `--`, so the help prints as data. A
+ * command with a `--json` flag of its own reads the pair the same way.
+ */
+function asksForJSON(argv) {
+    let end = argv.indexOf("--");
+    return (end === -1 ? argv : argv.slice(0, end)).includes("--json");
+}
+/**
+ * The prompts of a check: every one answers its initial value, so a value a terminal run would
+ * ask for counts as given.
+ */
+const CHECK_SESSION = {
+    interactive: true,
+    ask: (request) => Promise.resolve(success(request.initial)),
+};
+/** Parses and checks `argv` against `tree`, asking nothing and running nothing. */
+async function check(tree, withVersion, argv) {
+    let parsed = parseArgv(tree, argv, withVersion);
+    let path = [...parsed.entry.path];
+    if (parsed.help || parsed.version)
+        return success({ path });
+    let inputs = await resolveInputs(parsed, CHECK_SESSION);
+    if (isFailure(inputs)) {
+        let error = inputs.error;
+        return failure(error instanceof UsageError ? error : new UsageError(error.message));
+    }
+    return success({ path });
+}
 /** One run, from argument vector to exit code. */
 async function execute(cli, argv, io, script) {
     let internals = INTERNALS.get(cli);
@@ -91,6 +131,10 @@ async function execute(cli, argv, io, script) {
     let session = openSession(io, parsed.noProgress, script);
     try {
         let entry = parsed.entry;
+        if (parsed.help && asksForJSON(argv)) {
+            session.stdout.write(`${JSON.stringify(describeEntry(entry, program), null, 2)}\n`);
+            return EXIT_CODES.success;
+        }
         if (parsed.help) {
             session.stdout.write(renderHelp(entry, program, session.style));
             return EXIT_CODES.success;
@@ -173,7 +217,10 @@ async function dispatch(chain, context, handler) {
 function asError(error) {
     return error instanceof Error ? error : new Error(String(error));
 }
-/** Prints a failed run's message and answers its exit code. */
+/**
+ * Prints a failed run's message and answers its exit code. An `ExecError` also prints the
+ * child's stderr so CI sees wrangler/cf authentication lines instead of only "exited with 1".
+ */
 function report(error, entry, session, program) {
     if (error instanceof UsageError) {
         let help = renderHelp(entry, program, session.style.stderr);
@@ -181,6 +228,9 @@ function report(error, entry, session, program) {
     }
     else if (!(error instanceof CancelledError) && error.message !== "") {
         session.screen.write(session.stderr, `${error.message}\n`);
+        if (error instanceof ExecError && error.stderr !== "") {
+            session.screen.write(session.stderr, error.stderr.endsWith("\n") ? error.stderr : `${error.stderr}\n`);
+        }
     }
     return exitCodeOf(error);
 }

package/dist/describe.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The contract as plain data: every command with its arguments, flags and examples, the same
+ * facts the help prints. `--help --json` prints it, and a tool reads it to check what a script,
+ * a guide or an agent passes against what the program accepts.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { FlagKind } from "./flag.js";
+import type { Entry } from "./tree.js";
+/** One argument of a command, in the order the command line takes them. */
+export interface ArgumentDescription {
+    name: string;
+    description: string | null;
+    /** A value is needed; a missing one is asked for on a terminal when the argument prompts. */
+    required: boolean;
+    /** Takes every remaining positional. */
+    variadic: boolean;
+    /** Takes every token after the command's name unparsed, flags included. */
+    rest: boolean;
+    /** The default, when one is declared. */
+    default?: unknown;
+}
+/** One flag of a command, or one every command answers to (`builtin`). */
+export interface FlagDescription {
+    /** The long name, written `--<name>`. */
+    name: string;
+    aliases: string[];
+    /** The one-character alias, written `-<short>`. */
+    short: string | null;
+    kind: FlagKind;
+    /** A boolean's `--no-<name>` spelling is accepted. */
+    negatable: boolean;
+    /** What the help shows in `<…>` after the flag; `null` for a boolean. */
+    value: string | null;
+    /** The flag may appear bare or with `=value`. */
+    optionalValue: boolean;
+    /** One value holds several, separated by commas. */
+    list: boolean;
+    /** Repeating the flag collects every value. */
+    repeatable: boolean;
+    required: boolean;
+    description: string | null;
+    /** Answered by every command the program runs: `--help`, `--version`, `--no-progress`. */
+    builtin: boolean;
+    /** The default, when one is declared. */
+    default?: unknown;
+}
+/** One command or group, with every visible member below it. */
+export interface CommandDescription {
+    /** The words typed after the program to reach it; empty for the root. */
+    path: string[];
+    /** The program name and the path, as the help prints it. */
+    title: string;
+    description: string | null;
+    arguments: ArgumentDescription[];
+    flags: FlagDescription[];
+    /** Example command lines, each starting with the program name. */
+    examples: string[];
+    /** Members of a group by name; empty for a command. */
+    commands: CommandDescription[];
+}
+/** The program's own facts the description includes beside the contract. */
+export interface DescribeProgram {
+    version: string | undefined;
+    description: string | undefined;
+}
+/**
+ * Describes `entry` and every visible member under it. Hidden commands and flags stay out, as
+ * they do from the help.
+ */
+export declare function describeEntry(entry: Entry, program: DescribeProgram): CommandDescription;

package/dist/describe.js

@@ -0,0 +1,88 @@
+/**
+ * The contract as plain data: every command with its arguments, flags and examples, the same
+ * facts the help prints. `--help --json` prints it, and a tool reads it to check what a script,
+ * a guide or an agent passes against what the program accepts.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { groupSpec, isGroup } from "./command.js";
+/**
+ * Describes `entry` and every visible member under it. Hidden commands and flags stay out, as
+ * they do from the help.
+ */
+export function describeEntry(entry, program) {
+    let node = entry.node;
+    let spec = isGroup(node) ? groupSpec(node) : node;
+    let description = spec.description ?? (entry.parent === undefined ? program.description : undefined);
+    let flags = entry.flags.filter(({ spec }) => !spec.hidden).map(({ spec }) => describeFlag(spec));
+    if (entry.tasks)
+        flags.push(builtin("progress", "Print tasks without animation", true));
+    if (program.version !== undefined && entry.parent === undefined) {
+        flags.push(builtin("version", "Print the version", false));
+    }
+    flags.push({ ...builtin("help", "Show this help", false), short: "h" });
+    let programName = entry.title.split(" ")[0];
+    let commands = [];
+    for (let child of entry.children.values()) {
+        let childSpec = isGroup(child.node) ? groupSpec(child.node) : child.node;
+        if (childSpec.hidden)
+            continue;
+        commands.push(describeEntry(child, program));
+    }
+    return {
+        path: [...entry.path],
+        title: entry.title,
+        description: description ?? null,
+        arguments: entry.arguments.map(({ key, spec }) => ({
+            name: spec.valueName ?? key,
+            description: spec.description ?? null,
+            required: !spec.optional && !spec.hasDefault && (spec.variadic ? spec.min > 0 : true),
+            variadic: spec.variadic,
+            rest: spec.rest,
+            ...(spec.hasDefault ? { default: spec.default } : {}),
+        })),
+        flags,
+        examples: isGroup(node) ? [] : node.examples.map((example) => `${programName} ${example}`),
+        commands,
+    };
+}
+/** A declared flag as data. */
+function describeFlag(spec) {
+    let boolean = spec.kind === "boolean";
+    return {
+        name: spec.name,
+        aliases: [...spec.aliases],
+        short: spec.short ?? null,
+        kind: spec.kind,
+        negatable: boolean,
+        value: boolean ? null : (spec.valueName ?? (spec.kind === "number" ? "number" : "value")),
+        optionalValue: spec.optionalValue,
+        list: spec.list,
+        repeatable: spec.multiple,
+        required: spec.required && spec.prompt === undefined,
+        description: spec.description ?? null,
+        builtin: false,
+        ...(spec.hasDefault && spec.default !== undefined ? { default: spec.default } : {}),
+    };
+}
+/**
+ * A flag the runtime answers for every command. `--no-progress` is the one spelled negated, so
+ * its name is `progress` and it is negatable.
+ */
+function builtin(name, description, negatable) {
+    return {
+        name,
+        aliases: [],
+        short: null,
+        kind: "boolean",
+        negatable,
+        value: null,
+        optionalValue: false,
+        list: false,
+        repeatable: false,
+        required: false,
+        description,
+        builtin: true,
+    };
+}

package/dist/exec.js

@@ -7,6 +7,7 @@
  * @copyright Sergio Xalambrí 2026
  */
 import { spawn } from "node:child_process";
+import { iife } from "@sdxc/iife";
 import { failure, success } from "@sdxc/result";
 import { CancelledError } from "./errors.js";
 /** A child that could not start or exited with a code other than 0. */
@@ -61,27 +62,33 @@ export const spawnExec = (command, request) => new Promise((resolve) => {
     }
     let shown = displayCommand(command);
     let direct = (target, stream) => target === stream;
-    let outTarget = request.stdio === "inherit"
-        ? request.stdout
-        : request.stdio === "stderr"
-            ? request.stderr
-            : null;
+    let outTarget = null;
+    if (request.stdio === "inherit")
+        outTarget = request.stdout;
+    else if (request.stdio === "stderr")
+        outTarget = request.stderr;
     let errTarget = request.stdio === "inherit" || request.stdio === "stderr" ? request.stderr : null;
-    let stdout = request.stdio === "ignore"
-        ? "ignore"
-        : outTarget === null
-            ? "pipe"
-            : direct(outTarget, process.stdout)
-                ? "inherit"
-                : direct(outTarget, process.stderr)
-                    ? 2
-                    : "pipe";
-    let stderr = request.stdio === "ignore"
-        ? "ignore"
-        : errTarget !== null && direct(errTarget, process.stderr)
-            ? "inherit"
-            : "pipe";
-    let stdin = request.input !== undefined ? "pipe" : request.stdio === "inherit" ? "inherit" : "ignore";
+    let stdout = iife(() => {
+        if (request.stdio === "ignore")
+            return "ignore";
+        if (outTarget === null)
+            return "pipe";
+        if (direct(outTarget, process.stdout))
+            return "inherit";
+        if (direct(outTarget, process.stderr))
+            return 2;
+        return "pipe";
+    });
+    let stderr = "pipe";
+    if (request.stdio === "ignore")
+        stderr = "ignore";
+    else if (errTarget !== null && direct(errTarget, process.stderr))
+        stderr = "inherit";
+    let stdin = "ignore";
+    if (request.input !== undefined)
+        stdin = "pipe";
+    else if (request.stdio === "inherit")
+        stdin = "inherit";
     let child = spawn(program, args, {
         cwd: request.cwd,
         env: { ...request.env },

package/dist/help.js

@@ -6,6 +6,7 @@
  * @author [Sergio Xalambrí](https://sergiodxa.com)
  * @copyright Sergio Xalambrí 2026
  */
+import { iife } from "@sdxc/iife";
 import { groupSpec, isGroup } from "./command.js";
 import { visibleWidth } from "./style.js";
 /** Renders `entry`'s help, ending with a newline. */
@@ -99,11 +100,13 @@ function flagLabel(spec) {
     if (spec.short !== undefined)
         names.push(`-${spec.short}`);
     if (spec.kind === "boolean") {
-        let prefix = spec.prompt !== undefined || spec.default === undefined
-            ? "[no-]"
-            : spec.default === true
-                ? "no-"
-                : "";
+        let prefix = iife(() => {
+            if (spec.prompt !== undefined || spec.default === undefined)
+                return "[no-]";
+            if (spec.default === true)
+                return "no-";
+            return "";
+        });
         names.push(`--${prefix}${spec.name}`);
         for (let alias of spec.aliases)
             names.push(`--${prefix}${alias}`);

package/dist/index.d.ts

@@ -7,9 +7,10 @@
  * @copyright Sergio Xalambrí 2026
  */
 export type { Argument, ArgumentOptions, ArgumentValue, RestArgumentOptions, SingleArgumentOptions, VariadicArgumentOptions, } from "./argument.js";
-export type { Binding, CLI, CLIOptions } from "./cli.js";
+export type { Binding, CheckedCommand, CLI, CLIOptions } from "./cli.js";
 export type { ArgumentsOf, ArgumentsShape, Command, CommandDefinition, FlagsOf, FlagsShape, Group, GroupDefinition, GroupInputs, Node, } from "./command.js";
 export type { AnyCommandContext, CommandContextInit, Stdin } from "./context.js";
+export type { ArgumentDescription, CommandDescription, FlagDescription } from "./describe.js";
 export type { Exec, ExecOptions, ExecOutput, ExecRequest, Stdio } from "./exec.js";
 export type { BooleanFlagOptions, Flag, FlagKind, FlagOptions, FlagValue, ValueFlag, ValueFlagOptions, } from "./flag.js";
 export type { ChainContext, CLITypes, CommandAction, CommandHandler, HandlerContext, } from "./handler.js";

package/dist/interactions.js

@@ -6,6 +6,7 @@
  * @author [Sergio Xalambrí](https://sergiodxa.com)
  * @copyright Sergio Xalambrí 2026
  */
+import { iife } from "@sdxc/iife";
 import { typed } from "./keys.js";
 import { normalizeChoices } from "./prompt.js";
 import { graphemes } from "./style.js";
@@ -150,9 +151,11 @@ function numberLine(options, initial) {
                 let current = editor.text === "" ? (fallback ?? options.min ?? 0) : Number(editor.text);
                 if (Number.isNaN(current))
                     current = fallback ?? 0;
-                let next = editor.text === "" && fallback === undefined
-                    ? current
-                    : current + (key.name === "up" ? step : -step);
+                let next = iife(() => {
+                    if (editor.text === "" && fallback === undefined)
+                        return current;
+                    return current + (key.name === "up" ? step : -step);
+                });
                 editor = new Editor(String(clamp(next)));
                 return undefined;
             }
@@ -261,11 +264,13 @@ function list(choices, initial, mode) {
         render(style, header) {
             let lines = [];
             if (mode.search === true) {
-                let shownQuery = query.chars.length === 0
-                    ? mode.placeholder === undefined
-                        ? style.inverse(" ")
-                        : style.dim(mode.placeholder)
-                    : query.render(style);
+                let shownQuery = iife(() => {
+                    if (query.chars.length === 0)
+                        return mode.placeholder === undefined
+                            ? style.inverse(" ")
+                            : style.dim(mode.placeholder);
+                    return query.render(style);
+                });
                 lines.push(`${header} › ${shownQuery}`);
             }
             else
@@ -283,12 +288,18 @@ function list(choices, initial, mode) {
             for (let index of window) {
                 let option = options[index];
                 let pointer = index === cursor ? style.cyan("❯") : " ";
-                let box = mode.mode === "many" ? `${selected.has(index) ? style.green("◉") : "◯"} ` : "";
-                let label = option.disabled
-                    ? style.dim(`${option.label} (disabled)`)
-                    : index === cursor
-                        ? style.cyan(option.label)
-                        : option.label;
+                let box;
+                if (mode.mode === "many")
+                    box = `${selected.has(index) ? style.green("◉") : "◯"} `;
+                else
+                    box = "";
+                let label;
+                if (option.disabled)
+                    label = style.dim(`${option.label} (disabled)`);
+                else if (index === cursor)
+                    label = style.cyan(option.label);
+                else
+                    label = option.label;
                 let hint = option.hint === "" ? "" : ` ${style.dim(option.hint)}`;
                 lines.push(`${pointer} ${box}${label}${hint}`);
             }

package/dist/keys.js

@@ -7,6 +7,7 @@
  * @copyright Sergio Xalambrí 2026
  */
 import { emitKeypressEvents } from "node:readline";
+import { iife } from "@sdxc/iife";
 import { graphemes } from "./style.js";
 /**
  * Starts reading keys from `input` in raw mode.
@@ -101,7 +102,13 @@ export function keyFromName(name) {
     let bare = ctrl ? name.slice(5) : name;
     let named = NAMED_KEYS[bare];
     if (named !== undefined) {
-        let sequence = named === "space" ? " " : named === "return" ? "\r" : "";
+        let sequence = iife(() => {
+            if (named === "space")
+                return " ";
+            if (named === "return")
+                return "\r";
+            return "";
+        });
         return { name: named, sequence, ctrl, meta: false, shift: false };
     }
     let shift = bare !== bare.toLowerCase();

package/dist/parse.js

@@ -6,6 +6,7 @@
  * @author [Sergio Xalambrí](https://sergiodxa.com)
  * @copyright Sergio Xalambrí 2026
  */
+import { iife } from "@sdxc/iife";
 import { isGroup } from "./command.js";
 import { closest } from "./suggest.js";
 /** A token that starts a flag: a dash and something after it, other than a negative number. */
@@ -185,6 +186,11 @@ function skipValue(argv, index) {
     let next = argv[index];
     return next === undefined || isFlagToken(next) || next === "--" ? index : index + 1;
 }
+/**
+ * How many commands declaring a misplaced flag its usage error names; past it the rest are
+ * counted, so a flag every member of a large group shares still fits on one line.
+ */
+const NAMED_OWNERS = 3;
 /**
  * The message for a flag `entry` does not declare: the commands that do declare it, or the
  * closest name it does declare.
@@ -198,9 +204,14 @@ function unknownFlag(tree, entry, token) {
     let owners = long ? (tree.owners.get(name) ?? tree.owners.get(positive) ?? []) : [];
     if (owners.length > 0) {
         let titles = owners.map((owner) => owner.title);
-        let listed = titles.length === 1
-            ? titles[0]
-            : `${titles.slice(0, -1).join(", ")} and ${titles.at(-1)}`;
+        let listed = iife(() => {
+            if (titles.length === 1)
+                return titles[0];
+            if (titles.length > NAMED_OWNERS) {
+                return `${titles.slice(0, NAMED_OWNERS).join(", ")} and ${titles.length - NAMED_OWNERS} more`;
+            }
+            return `${titles.slice(0, -1).join(", ")} and ${titles.at(-1)}`;
+        });
         return `${spelled} is not a flag of ${entry.title}; ${listed} ${titles.length === 1 ? "takes" : "take"} it`;
     }
     let candidates = [];

package/dist/resolve.d.ts

@@ -22,6 +22,6 @@ export interface Inputs {
  * @returns The inputs, a usage failure listing every problem, a cancelled failure, or the
  * failure of a scripted answer that was missing or rejected
  */
-export declare function resolveInputs(parsed: Parsed, session: Session): Promise<Result<Inputs, Error>>;
+export declare function resolveInputs(parsed: Parsed, session: Pick<Session, "interactive" | "ask">): Promise<Result<Inputs, Error>>;
 /** The `ctx.prompt` of one run: asks on a terminal or from a script, else answers the default. */
 export declare function createPrompter(session: Session): Prompter;

package/dist/resolve.js

@@ -6,6 +6,7 @@
  * @author [Sergio Xalambrí](https://sergiodxa.com)
  * @copyright Sergio Xalambrí 2026
  */
+import { iife } from "@sdxc/iife";
 import { failure, isFailure, success } from "@sdxc/result";
 import { isGroup } from "./command.js";
 import { CancelledError, UsageError } from "./errors.js";
@@ -109,13 +110,14 @@ export async function resolveInputs(parsed, session) {
             return success(spec.variadic ? checked.data : checked.data[0]);
         };
         if (given.length === 0) {
-            let fallback = spec.hasDefault
-                ? { value: spec.default }
-                : spec.optional
-                    ? { value: undefined }
-                    : spec.variadic && spec.min === 0
-                        ? { value: [] }
-                        : undefined;
+            let fallback = iife(() => {
+                if (spec.hasDefault)
+                    return { value: spec.default };
+                if (spec.optional)
+                    return { value: undefined };
+                if (spec.variadic && spec.min === 0)
+                    return { value: [] };
+            });
             missing.push({
                 label,
                 names: [key],
@@ -154,13 +156,14 @@ export async function resolveInputs(parsed, session) {
             return success(many ? checked.data : checked.data[0]);
         };
         if (occurrences.length === 0) {
-            let fallback = spec.hasDefault
-                ? { value: spec.default }
-                : spec.kind === "boolean"
-                    ? { value: false }
-                    : spec.required
-                        ? undefined
-                        : { value: many ? [] : undefined };
+            let fallback = iife(() => {
+                if (spec.hasDefault)
+                    return { value: spec.default };
+                if (spec.kind === "boolean")
+                    return { value: false };
+                if (!spec.required)
+                    return { value: many ? [] : undefined };
+            });
             missing.push({
                 label,
                 names: [key, spec.name],

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sdxc/cli",
-	"version": "2026.10.16",
+	"version": "2026.10.23",
 	"description": "Build command-line tools with generated help, prompts bound to flags, tasks and a test harness",
 	"license": "MIT",
 	"type": "module",
@@ -9,6 +9,7 @@
 		"./test": "./dist/test.js"
 	},
 	"dependencies": {
+		"@sdxc/iife": "2026.10.23",
 		"@sdxc/result": "2026.10.13",
 		"@standard-schema/spec": "^1.1.0"
 	},
@@ -20,7 +21,7 @@
 			"optional": true
 		}
 	},
-	"gitHead": "1e547d8431568f5ed9bdb079ca3046c936240fde",
+	"gitHead": "8e428ddf15290d44500a9618ec4d04bd7629fa99",
 	"publishConfig": {
 		"access": "public"
 	},