@sdxc/cli 2026.10.24 → 2026.11.10

package/README.md

@@ -141,6 +141,8 @@ Every token after the command's name, unparsed, to hand to another program.
 command({ arguments: { args: argument.rest() } }); // prog run users --help → ["users", "--help"]
 ```
 
+A program with no commands can declare it on `commands({ arguments: { args: argument.rest() } })` and map a handler to the program itself, so it reads its whole command line, `--help` included.
+
 #### `flag.boolean(name, options?)`
 
 `--name`, and `--no-name` to turn it off.
@@ -226,6 +228,7 @@ Runs a command without a terminal and answers `{ code, stdout, stderr, exec }`.
 
 - `spawnExec`: the default `exec`, over `node:child_process`.
 - `createStyle(enabled)`: the colours `ctx.style` uses, for output outside a handler.
+- `closest(input, candidates)`: the candidate a mistyped name most likely meant, or `undefined`, as the "did you mean" hints for commands and flags pick it.
 - Types: `CommandMiddleware<Effect>` (a middleware publishing `Effect`'s `property`), `Task`, `RunIO`, `Exec`, `ExecOptions`, `ExecOutput`, `HandlerContext`, `ChainContext` (the context a helper shared by several commands takes), `ArgumentsOf`, `FlagsOf`.
 
 ## Patterns

package/dist/describe.js

@@ -7,6 +7,7 @@
  * @copyright Sergio Xalambrí 2026
  */
 import { groupSpec, isGroup } from "./command.js";
+import { exampleLine } from "./help.js";
 /**
  * Describes `entry` and every visible member under it. Hidden commands and flags stay out, as
  * they do from the help.
@@ -43,7 +44,9 @@ export function describeEntry(entry, program) {
             ...(spec.hasDefault ? { default: spec.default } : {}),
         })),
         flags,
-        examples: isGroup(node) ? [] : node.examples.map((example) => `${programName} ${example}`),
+        examples: isGroup(node)
+            ? []
+            : node.examples.map((example) => exampleLine(programName, example)),
         commands,
     };
 }

package/dist/help.d.ts

@@ -16,3 +16,12 @@ export interface HelpProgram {
 }
 /** Renders `entry`'s help, ending with a newline. */
 export declare function renderHelp(entry: Entry, program: HelpProgram, style: Style): string;
+/**
+ * An example as a shell user types it. The program goes before the command after the last
+ * pipe, so `cat a.json | hash` reads `cat a.json | prog hash`, and an example that already names
+ * the program there is printed as written.
+ *
+ * @example exampleLine("prog", "hash a.json") // "prog hash a.json"
+ * @example exampleLine("prog", "cat a.json | hash") // "cat a.json | prog hash"
+ */
+export declare function exampleLine(program: string, example: string): string;

package/dist/help.js

@@ -69,11 +69,27 @@ export function renderHelp(entry, program, style) {
         sections.push(section(`${heading}:`, rows, style));
     if (!isGroup(node) && node.examples.length > 0) {
         let program = entry.title.split(" ")[0];
-        let lines = node.examples.map((example) => `  ${program} ${example}`);
+        let lines = node.examples.map((example) => `  ${exampleLine(program, example)}`);
         sections.push(`${style.bold("Examples:")}\n${lines.join("\n")}`);
     }
     return `${sections.join("\n\n")}\n`;
 }
+/**
+ * An example as a shell user types it. The program goes before the command after the last
+ * pipe, so `cat a.json | hash` reads `cat a.json | prog hash`, and an example that already names
+ * the program there is printed as written.
+ *
+ * @example exampleLine("prog", "hash a.json") // "prog hash a.json"
+ * @example exampleLine("prog", "cat a.json | hash") // "cat a.json | prog hash"
+ */
+export function exampleLine(program, example) {
+    let pipe = example.lastIndexOf("| ");
+    let before = pipe === -1 ? "" : example.slice(0, pipe + 2);
+    let command = pipe === -1 ? example : example.slice(pipe + 2);
+    if (command === program || command.startsWith(`${program} `))
+        return example;
+    return `${before}${program} ${command}`;
+}
 /** A titled section of aligned rows, flag and command names styled. */
 function section(title, rows, style) {
     let width = Math.max(0, ...rows.map(([left]) => visibleWidth(left)));

package/dist/index.d.ts

@@ -30,6 +30,7 @@ export { CancelledError, EXIT_CODES, ExitError, UsageError, cancelled, exit, exi
 export { ExecError, spawnExec } from "./exec.js";
 export { flag } from "./flag.js";
 export { createCommand } from "./handler.js";
+export { closest } from "./suggest.js";
 export { lazy } from "./lazy.js";
 export { prompt } from "./prompt.js";
 export { createStyle } from "./style.js";

package/dist/index.js

@@ -14,6 +14,7 @@ export { CancelledError, EXIT_CODES, ExitError, UsageError, cancelled, exit, exi
 export { ExecError, spawnExec } from "./exec.js";
 export { flag } from "./flag.js";
 export { createCommand } from "./handler.js";
+export { closest } from "./suggest.js";
 export { lazy } from "./lazy.js";
 export { prompt } from "./prompt.js";
 export { createStyle } from "./style.js";

package/dist/parse.js

@@ -30,7 +30,7 @@ export function parseArgv(tree, argv, withVersion) {
         issues: [],
     };
     let index = 0;
-    let rest = false;
+    let rest = tree.root.rest;
     /** Flag tokens read at a group, replayed against the member the command line goes on to name. */
     let atGroup = [];
     /** How many issues stood before the current group's flags were read. */

package/dist/tree.js

@@ -67,8 +67,9 @@ export function buildTree(name, root) {
             args.push({ key, spec });
         });
         let rest = args.some((arg) => arg.spec.rest);
-        if (rest && (isGroup(node) || flags.length > 0 || args.length !== 1)) {
-            throw new Error(`${title}: argument.rest() is a command's only argument, with no flags`);
+        let nested = isGroup(node) && (path.length > 0 || Object.keys(groupSpec(node).members).length > 0);
+        if (rest && (nested || flags.length > 0 || args.length !== 1)) {
+            throw new Error(`${title}: argument.rest() is the only argument of a command, or of a program with no commands, with no flags`);
         }
         let entry = {
             node,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sdxc/cli",
-	"version": "2026.10.24",
+	"version": "2026.11.10",
 	"description": "Build command-line tools with generated help, prompts bound to flags, tasks and a test harness",
 	"license": "MIT",
 	"type": "module",
@@ -14,14 +14,14 @@
 		"@standard-schema/spec": "^1.1.0"
 	},
 	"peerDependencies": {
-		"remix": "3.1.0"
+		"remix": "3.2.0"
 	},
 	"peerDependenciesMeta": {
 		"remix": {
 			"optional": true
 		}
 	},
-	"gitHead": "f9db0f8f1f51a256e74b94b0f4b1db4be9880370",
+	"gitHead": "6191b60a13885b1d826884d574c4a393f9b8eeee",
 	"publishConfig": {
 		"access": "public"
 	},