@sdxc/cli 2026.10.16 → 2026.10.20

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,6 +8,7 @@
  */
 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 { isAction } from "./handler.js";
 import { renderHelp } from "./help.js";
@@ -45,6 +46,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 +92,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 +130,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;

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/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/parse.js

@@ -185,6 +185,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.
@@ -200,7 +205,9 @@ function unknownFlag(tree, entry, token) {
         let titles = owners.map((owner) => owner.title);
         let listed = titles.length === 1
             ? titles[0]
-            : `${titles.slice(0, -1).join(", ")} and ${titles.at(-1)}`;
+            : titles.length > NAMED_OWNERS
+                ? `${titles.slice(0, NAMED_OWNERS).join(", ")} and ${titles.length - NAMED_OWNERS} more`
+                : `${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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sdxc/cli",
-	"version": "2026.10.16",
+	"version": "2026.10.20",
 	"description": "Build command-line tools with generated help, prompts bound to flags, tasks and a test harness",
 	"license": "MIT",
 	"type": "module",
@@ -20,7 +20,7 @@
 			"optional": true
 		}
 	},
-	"gitHead": "1e547d8431568f5ed9bdb079ca3046c936240fde",
+	"gitHead": "bd4473246f405c43055d2fc5e08c62ba35197258",
 	"publishConfig": {
 		"access": "public"
 	},