@duyquangnvx/agent-cli 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,18 @@ What changed in each release of `@duyquangnvx/agent-cli` (the Runtime) and `@duy
 
 ## Unreleased
 
+## v0.2.0 (2026-10-19)
+
+### Changed
+
+- **Breaking:** a List Command is declared by its row schema alone: a read Command sets `rows: rowSchema` in place of `output`, and the Runtime adds `--limit`, `--cursor` and `--fields`, passes `limit` and `cursor` to `run` and gives help JSON the page of rows as its output schema. A described or otherwise wrapped row schema keeps `--fields`, and a write or destructive Command with `rows` fails type checking. The exports `pageOf` and `pageOptions` are removed; the agent-cli skill and the scaffolded template use `rows`.
+- **Breaking:** help and `--help --json` list `--limit`, `--cursor` and `--fields` under Standard flags instead of among the Command's options, so help JSON's `options` no longer has `fields`, `limit` or `cursor`. Each entry of help JSON's `standardFlags` carries the JSON Schema of the flag's value as `schema`, such as `--limit`'s positive integer with default 20.
+- **Breaking:** `defineCommand` throws, and type checking fails, when a Command declares an arg or option named like any Standard flag, whether or not that Command gets the flag: `json`, `help`, `h`, `version`, `dry-run` (key `dryRun`), `confirm`, `limit`, `cursor` or `fields`.
+
+### Fixed
+
+- `--help` or `-h` after `--` is an argument, as every other word after `--` is, instead of showing help.
+
 ## v0.1.0 (2026-10-18)
 
 ### Added

package/README.md

@@ -0,0 +1,11 @@
+# @duyquangnvx/agent-cli
+
+The Runtime for Agent CLIs: command-line tools whose main caller is an LLM coding agent. You declare Commands with Zod schemas. The Runtime does the parsing, help (as text and as `--help --json`), output, errors with hints, exit codes, `--dry-run` and `--confirm`, pagination, Ctrl-C and deadlines, and the built-in `doctor` and `update`.
+
+An Agent CLI bundles the Runtime, so install it as a devDependency next to `zod`. The fastest start is the Scaffolder:
+
+```sh
+pnpm create @duyquangnvx/agent-cli <name> --description "One line saying what it does"
+```
+
+See the [repository](https://github.com/duyquangnvx/cli-for-agent) for an overview and the [agent-cli skill](https://github.com/duyquangnvx/cli-for-agent/blob/release/skills/agent-cli/SKILL.md) for the full guide.

package/dist/command-spec.d.ts

@@ -0,0 +1,28 @@
+import type * as z from "zod";
+import { type Command, type Commands, type Example } from "./define.js";
+import { type StandardFlag } from "./flags.js";
+import { type InputField } from "./input.js";
+import { type ListSpec } from "./list.js";
+/** Everything help, help JSON and input parsing know about one Command. */
+export interface CommandSpec {
+    readonly kind: "command";
+    readonly commandLine: string;
+    readonly command: Command;
+    readonly description: string;
+    readonly effect: Command["effect"];
+    readonly examples: readonly Example[];
+    readonly args: readonly InputField[];
+    /** The options the author declared; Standard flags are kept apart in `standardFlags`. */
+    readonly options: readonly InputField[];
+    readonly standardFlags: readonly StandardFlag[];
+    readonly list: ListSpec | undefined;
+    readonly output: z.ZodType | undefined;
+}
+export interface GroupSpec {
+    readonly kind: "group";
+    readonly commandLine: string;
+    readonly commands: Readonly<Record<string, SpecNode>>;
+}
+export type SpecNode = CommandSpec | GroupSpec;
+export declare function commandSpec(commandLine: string, command: Command): CommandSpec;
+export declare function groupSpec(commandLine: string, commands: Commands): GroupSpec;

package/dist/command-spec.js

@@ -0,0 +1,31 @@
+import { isCommand } from "./define.js";
+import { standardFlagsFor } from "./flags.js";
+import { argFields, optionFields } from "./input.js";
+import { listSpec } from "./list.js";
+export function commandSpec(commandLine, command) {
+    const list = command.rows === undefined ? undefined : listSpec(command.rows);
+    return {
+        kind: "command",
+        commandLine,
+        command,
+        description: command.description,
+        effect: command.effect,
+        examples: command.examples,
+        args: argFields(command.args),
+        options: optionFields(command.options),
+        standardFlags: standardFlagsFor(command.effect, list),
+        list,
+        output: list?.output ?? command.output,
+    };
+}
+export function groupSpec(commandLine, commands) {
+    return {
+        kind: "group",
+        commandLine,
+        commands: Object.fromEntries(Object.entries(commands).map(([key, node]) => [key, specOf(`${commandLine} ${key}`, node)])),
+    };
+}
+function specOf(commandLine, node) {
+    return isCommand(node) ? commandSpec(commandLine, node) : groupSpec(commandLine, node);
+}
+//# sourceMappingURL=command-spec.js.map

package/dist/command-spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-spec.js","sourceRoot":"","sources":["../src/command-spec.ts"],"names":[],"mappings":"AACA,OAAO,EAA6C,SAAS,EAAE,MAAM,aAAa,CAAC;AACnF,OAAO,EAAqB,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACjE,OAAO,EAAE,SAAS,EAAmB,YAAY,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAiB,QAAQ,EAAE,MAAM,WAAW,CAAC;AA0BpD,MAAM,UAAU,WAAW,CAAC,WAAmB,EAAE,OAAgB;IAC/D,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E,OAAO;QACL,IAAI,EAAE,SAAS;QACf,WAAW;QACX,OAAO;QACP,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,IAAI,EAAE,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC;QAC7B,OAAO,EAAE,YAAY,CAAC,OAAO,CAAC,OAAO,CAAC;QACtC,aAAa,EAAE,gBAAgB,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC;QACrD,IAAI;QACJ,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,OAAO,CAAC,MAAM;KACvC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,WAAmB,EAAE,QAAkB;IAC/D,OAAO;QACL,IAAI,EAAE,OAAO;QACb,WAAW;QACX,QAAQ,EAAE,MAAM,CAAC,WAAW,CAC1B,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,WAAW,IAAI,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,CAC5F;KACF,CAAC;AACJ,CAAC;AAED,SAAS,MAAM,CAAC,WAAmB,EAAE,IAAwB;IAC3D,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;AACzF,CAAC"}

package/dist/confirm.d.ts

@@ -1,5 +1,4 @@
 import { type Invocation } from "./invocation.js";
-export declare const CONFIRM_OPTION = "--confirm";
 export interface Confirmation {
     readonly invocation: Invocation;
     readonly commandLine: string;

package/dist/confirm.js

@@ -1,21 +1,21 @@
 import { UsageError } from "./errors.js";
+import { CONFIRM_FLAG } from "./flags.js";
 import { commandLineWith } from "./invocation.js";
-export const CONFIRM_OPTION = "--confirm";
 export function checkConfirmation({ invocation, commandLine, given }, expected) {
     if (given === expected) {
         return;
     }
-    const hint = `to confirm, run \`${commandLineWith(invocation, CONFIRM_OPTION, expected)}\``;
+    const hint = `to confirm, run \`${commandLineWith(invocation, CONFIRM_FLAG.flag, expected)}\``;
     if (given === undefined) {
         throw new UsageError({
             code: "CONFIRMATION_REQUIRED",
-            message: `\`${commandLine}\` is destructive and needs ${CONFIRM_OPTION}`,
+            message: `\`${commandLine}\` is destructive and needs ${CONFIRM_FLAG.flag}`,
             hint,
         });
     }
     throw new UsageError({
         code: "CONFIRMATION_MISMATCH",
-        message: `${CONFIRM_OPTION} ${JSON.stringify(given)} does not match the target of \`${commandLine}\``,
+        message: `${CONFIRM_FLAG.flag} ${JSON.stringify(given)} does not match the target of \`${commandLine}\``,
         hint,
     });
 }

package/dist/confirm.js.map

@@ -1 +1 @@
-{"version":3,"file":"confirm.js","sourceRoot":"","sources":["../src/confirm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,eAAe,EAAmB,MAAM,iBAAiB,CAAC;AAEnE,MAAM,CAAC,MAAM,cAAc,GAAG,WAAW,CAAC;AAQ1C,MAAM,UAAU,iBAAiB,CAC/B,EAAE,UAAU,EAAE,WAAW,EAAE,KAAK,EAAgB,EAChD,QAAgB;IAEhB,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvB,OAAO;IACT,CAAC;IACD,MAAM,IAAI,GAAG,qBAAqB,eAAe,CAAC,UAAU,EAAE,cAAc,EAAE,QAAQ,CAAC,IAAI,CAAC;IAC5F,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,UAAU,CAAC;YACnB,IAAI,EAAE,uBAAuB;YAC7B,OAAO,EAAE,KAAK,WAAW,+BAA+B,cAAc,EAAE;YACxE,IAAI;SACL,CAAC,CAAC;IACL,CAAC;IACD,MAAM,IAAI,UAAU,CAAC;QACnB,IAAI,EAAE,uBAAuB;QAC7B,OAAO,EAAE,GAAG,cAAc,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,mCAAmC,WAAW,IAAI;QACrG,IAAI;KACL,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"confirm.js","sourceRoot":"","sources":["../src/confirm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAmB,MAAM,iBAAiB,CAAC;AAQnE,MAAM,UAAU,iBAAiB,CAC/B,EAAE,UAAU,EAAE,WAAW,EAAE,KAAK,EAAgB,EAChD,QAAgB;IAEhB,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvB,OAAO;IACT,CAAC;IACD,MAAM,IAAI,GAAG,qBAAqB,eAAe,CAAC,UAAU,EAAE,YAAY,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC;IAC/F,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,UAAU,CAAC;YACnB,IAAI,EAAE,uBAAuB;YAC7B,OAAO,EAAE,KAAK,WAAW,+BAA+B,YAAY,CAAC,IAAI,EAAE;YAC3E,IAAI;SACL,CAAC,CAAC;IACL,CAAC;IACD,MAAM,IAAI,UAAU,CAAC;QACnB,IAAI,EAAE,uBAAuB;QAC7B,OAAO,EAAE,GAAG,YAAY,CAAC,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,mCAAmC,WAAW,IAAI;QACxG,IAAI;KACL,CAAC,CAAC;AACL,CAAC"}

package/dist/define.d.ts

@@ -1,4 +1,6 @@
 import type * as z from "zod";
+import { type StandardFlagName } from "./flags.js";
+import type { Page, PageInput, RowSchema } from "./list.js";
 import type { Style } from "./style.js";
 export type Env = Readonly<Record<string, string | undefined>>;
 export interface Example {
@@ -30,15 +32,27 @@ interface CommandBase<Args extends InputSchema, Options extends InputSchema> {
     readonly examples: readonly Example[];
     readonly args?: Args;
     readonly options?: Options;
+}
+interface UnpagedCommand<Args extends InputSchema, Options extends InputSchema> extends CommandBase<Args, Options> {
     readonly output?: z.ZodType;
+    readonly rows?: never;
 }
-export interface ReadCommand<Args extends InputSchema, Options extends InputSchema, Data> extends CommandBase<Args, Options> {
+export interface ReadCommand<Args extends InputSchema, Options extends InputSchema, Data> extends UnpagedCommand<Args, Options> {
     readonly effect: "read";
     run(input: Input<Args, Options>, ctx: Context): Data | Promise<Data>;
     render(data: Data, style: Style): string;
 }
+/** A read Command whose data is a page of rows; the Runtime adds `--limit`, `--cursor` and `--fields`. */
+export interface ListCommand<Args extends InputSchema, Options extends InputSchema, Row extends RowSchema> extends CommandBase<Args, Options> {
+    readonly effect: "read";
+    /** The schema of one row; the page's output schema is derived from it. */
+    readonly rows: Row;
+    readonly output?: never;
+    run(input: Flatten<OutputOf<Args> & OutputOf<Options> & PageInput>, ctx: Context): Page<z.output<Row>> | Promise<Page<z.output<Row>>>;
+    render(page: Page<z.output<Row>>, style: Style): string;
+}
 /** A Command that changes something: `plan` has no side effects, `apply` performs the Plan. */
-interface PlannedCommand<Args extends InputSchema, Options extends InputSchema, Plan, Data> extends CommandBase<Args, Options> {
+interface PlannedCommand<Args extends InputSchema, Options extends InputSchema, Plan, Data> extends UnpagedCommand<Args, Options> {
     plan(input: Input<Args, Options>, ctx: Context): Plan | Promise<Plan>;
     apply(plan: Plan, ctx: Context): Data | Promise<Data>;
     render(data: Data, style: Style): string;
@@ -52,7 +66,7 @@ export interface DestructiveCommand<Args extends InputSchema, Options extends In
     /** The value the caller must repeat as `--confirm`, naming the target the Plan changes. */
     confirm(plan: Plan): string;
 }
-export type Command = ReadCommand<InputSchema, InputSchema, unknown> | WriteCommand<InputSchema, InputSchema, unknown, unknown> | DestructiveCommand<InputSchema, InputSchema, unknown, unknown>;
+export type Command = ReadCommand<InputSchema, InputSchema, unknown> | ListCommand<InputSchema, InputSchema, RowSchema> | WriteCommand<InputSchema, InputSchema, unknown, unknown> | DestructiveCommand<InputSchema, InputSchema, unknown, unknown>;
 export interface Commands {
     readonly [key: string]: Command | Commands;
 }
@@ -101,8 +115,18 @@ export interface SingleCommandCli extends CliBase {
     readonly commands?: never;
 }
 export type Cli = CommandTreeCli | SingleCommandCli;
-export declare function defineCommand<Data, Args extends InputSchema = NoInput, Options extends InputSchema = NoInput>(command: ReadCommand<Args, Options, Data>): ReadCommand<Args, Options, Data>;
-export declare function defineCommand<Plan, Data, Args extends InputSchema = NoInput, Options extends InputSchema = NoInput>(command: WriteCommand<Args, Options, Plan, Data>): WriteCommand<Args, Options, Plan, Data>;
-export declare function defineCommand<Plan, Data, Args extends InputSchema = NoInput, Options extends InputSchema = NoInput>(command: DestructiveCommand<Args, Options, Plan, Data>): DestructiveCommand<Args, Options, Plan, Data>;
+type Kebab<Key extends string> = Key extends `${infer Head}${infer Tail}` ? `${Head extends Lowercase<Head> ? Head : `-${Lowercase<Head>}`}${Kebab<Tail>}` : Key;
+type Taken<Schema extends InputSchema> = Extract<Kebab<Extract<keyof Schema["shape"], string>>, StandardFlagName>;
+type Unreserved<Schema extends InputSchema> = [Taken<Schema>] extends [never] ? unknown : {
+    readonly standardFlagDeclared: Taken<Schema>;
+};
+interface WithoutStandardFlags<Args extends InputSchema, Options extends InputSchema> {
+    readonly args?: Unreserved<Args>;
+    readonly options?: Unreserved<Options>;
+}
+export declare function defineCommand<Row extends RowSchema, Args extends InputSchema = NoInput, Options extends InputSchema = NoInput>(command: ListCommand<Args, Options, Row> & WithoutStandardFlags<Args, Options>): ListCommand<Args, Options, Row>;
+export declare function defineCommand<Data, Args extends InputSchema = NoInput, Options extends InputSchema = NoInput>(command: ReadCommand<Args, Options, Data> & WithoutStandardFlags<Args, Options>): ReadCommand<Args, Options, Data>;
+export declare function defineCommand<Plan, Data, Args extends InputSchema = NoInput, Options extends InputSchema = NoInput>(command: WriteCommand<Args, Options, Plan, Data> & WithoutStandardFlags<Args, Options>): WriteCommand<Args, Options, Plan, Data>;
+export declare function defineCommand<Plan, Data, Args extends InputSchema = NoInput, Options extends InputSchema = NoInput>(command: DestructiveCommand<Args, Options, Plan, Data> & WithoutStandardFlags<Args, Options>): DestructiveCommand<Args, Options, Plan, Data>;
 export declare function isCommand(node: Command | Commands): node is Command;
 export {};

package/dist/define.js

@@ -1,4 +1,6 @@
+import { checkNoStandardFlags } from "./flags.js";
 export function defineCommand(command) {
+    checkNoStandardFlags(command);
     return command;
 }
 // A group's values are always objects, so a string `effect` can only belong to a Command.

package/dist/define.js.map

@@ -1 +1 @@
-{"version":3,"file":"define.js","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AA0JA,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,SAAS,CAAC,IAAwB;IAChD,OAAO,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC;AACzC,CAAC"}
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAyB,MAAM,YAAY,CAAC;AAgNzE,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,SAAS,CAAC,IAAwB;IAChD,OAAO,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC;AACzC,CAAC"}

package/dist/execute.d.ts

@@ -1,5 +1,6 @@
-import { type Confirmation } from "./confirm.js";
 import type { Command, Context } from "./define.js";
+import type { Invocation } from "./invocation.js";
+import type { PageInput } from "./list.js";
 import type { Style } from "./style.js";
 export interface Outcome {
     readonly value: unknown;
@@ -7,6 +8,14 @@ export interface Outcome {
 }
 export interface ExecuteFlags {
     readonly dryRun: boolean;
-    readonly confirmation: Confirmation;
+    /** The target the caller named with `--confirm`, if any. */
+    readonly confirm: string | undefined;
+    /** The page a List Command's `run` receives with its input. */
+    readonly page: PageInput;
+    /** The caller's command line and the Command's, for the hint of a confirmation error. */
+    readonly invocation: Invocation;
+    readonly commandLine: string;
 }
-export declare function execute(command: Command, input: Record<string, unknown>, ctx: Context, { dryRun, confirmation }: ExecuteFlags): Promise<Outcome>;
+/** How the Command prints data it fails with, which is the data its `run` or `apply` returns. */
+export declare function renderOf(command: Command): (data: unknown, style: Style) => string;
+export declare function execute(command: Command, input: Record<string, unknown>, ctx: Context, { dryRun, confirm, page, invocation, commandLine }: ExecuteFlags): Promise<Outcome>;

package/dist/execute.js

@@ -2,7 +2,15 @@ import { checkConfirmation } from "./confirm.js";
 function outcomeOf(value, render) {
     return { value, render: (style) => render(value, style) };
 }
-export async function execute(command, input, ctx, { dryRun, confirmation }) {
+/** How the Command prints data it fails with, which is the data its `run` or `apply` returns. */
+export function renderOf(command) {
+    // The union of render signatures only accepts the intersection of their data types.
+    return (data, style) => command.render(data, style);
+}
+export async function execute(command, input, ctx, { dryRun, confirm, page, invocation, commandLine }) {
+    if (command.rows !== undefined) {
+        return outcomeOf(await command.run({ ...input, ...page }, ctx), (data, style) => command.render(data, style));
+    }
     if (command.effect === "read") {
         return outcomeOf(await command.run(input, ctx), (data, style) => command.render(data, style));
     }
@@ -11,7 +19,7 @@ export async function execute(command, input, ctx, { dryRun, confirmation }) {
         return outcomeOf(plan, (value, style) => command.renderPlan(value, style));
     }
     if (command.effect === "destructive") {
-        checkConfirmation(confirmation, command.confirm(plan));
+        checkConfirmation({ invocation, commandLine, given: confirm }, command.confirm(plan));
     }
     return outcomeOf(await command.apply(plan, ctx), (data, style) => command.render(data, style));
 }

package/dist/execute.js.map

@@ -1 +1 @@
-{"version":3,"file":"execute.js","sourceRoot":"","sources":["../src/execute.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAcpE,SAAS,SAAS,CAAQ,KAAY,EAAE,MAA8C;IACpF,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC;AAC5D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,OAAgB,EAChB,KAA8B,EAC9B,GAAY,EACZ,EAAE,MAAM,EAAE,YAAY,EAAgB;IAEtC,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAC9B,OAAO,SAAS,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;IAChG,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC5C,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,SAAS,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,aAAa,EAAE,CAAC;QACrC,iBAAiB,CAAC,YAAY,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,SAAS,CAAC,MAAM,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;AACjG,CAAC"}
+{"version":3,"file":"execute.js","sourceRoot":"","sources":["../src/execute.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAsBjD,SAAS,SAAS,CAAQ,KAAY,EAAE,MAA8C;IACpF,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC;AAC5D,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,QAAQ,CAAC,OAAgB;IACvC,oFAAoF;IACpF,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAE,OAAO,CAAC,MAAkD,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AACnG,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,OAAgB,EAChB,KAA8B,EAC9B,GAAY,EACZ,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAgB;IAEhE,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,SAAS,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,EAAE,GAAG,KAAK,EAAE,GAAG,IAAI,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAC9E,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAC5B,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAC9B,OAAO,SAAS,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;IAChG,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC5C,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,SAAS,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,aAAa,EAAE,CAAC;QACrC,iBAAiB,CAAC,EAAE,UAAU,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,SAAS,CAAC,MAAM,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;AACjG,CAAC"}

package/dist/flags.d.ts

@@ -1,12 +1,50 @@
+import * as z from "zod";
 import type { Command } from "./define.js";
+import { type ListFlagName, type ListSpec } from "./list.js";
+import type { Takes } from "./tokenize.js";
 type Effect = Command["effect"];
-export interface RuntimeFlag {
+export declare const HELP_FLAG = "--help";
+export declare const HELP_SHORT = "-h";
+export declare const VERSION_FLAG = "--version";
+declare const ROUTING_FLAGS: readonly ["--help", "-h", "--version"];
+export type NameOf<Flag extends string> = Flag extends `--${infer Name}` ? Name : Flag extends `-${infer Name}` ? Name : Flag;
+export interface StandardFlag {
+    /** The flag as the caller types it, such as `--json`. */
+    readonly flag: string;
     readonly usage: string;
     readonly description: string;
-    readonly effects: readonly Effect[];
+    readonly takes: Takes;
+    readonly schema: z.ZodType;
 }
-export declare const JSON_FLAG: RuntimeFlag;
-export declare const DRY_RUN_FLAG: RuntimeFlag;
-export declare const CONFIRM_FLAG: RuntimeFlag;
-export declare function runtimeFlagsFor(effect: Effect): readonly RuntimeFlag[];
+export declare const JSON_FLAG: StandardFlag & {
+    readonly flag: "--json";
+};
+export declare const DRY_RUN_FLAG: StandardFlag & {
+    readonly flag: "--dry-run";
+};
+export declare const CONFIRM_FLAG: StandardFlag & {
+    readonly flag: "--confirm";
+};
+declare const EFFECT_FLAGS: {
+    readonly read: readonly [StandardFlag & {
+        readonly flag: "--json";
+    }];
+    readonly write: readonly [StandardFlag & {
+        readonly flag: "--json";
+    }, StandardFlag & {
+        readonly flag: "--dry-run";
+    }];
+    readonly destructive: readonly [StandardFlag & {
+        readonly flag: "--json";
+    }, StandardFlag & {
+        readonly flag: "--dry-run";
+    }, StandardFlag & {
+        readonly flag: "--confirm";
+    }];
+};
+export type StandardFlagName = NameOf<(typeof ROUTING_FLAGS)[number]> | NameOf<(typeof EFFECT_FLAGS)[Effect][number]["flag"]> | ListFlagName;
+/** The Standard flags of a Command with this Effect, and of a List Command. */
+export declare function standardFlagsFor(effect: Effect, list: ListSpec | undefined): readonly StandardFlag[];
+/** Throws when the Command declares an arg or option under a Standard flag's name. */
+export declare function checkNoStandardFlags(command: Command): void;
 export {};

package/dist/flags.js

@@ -1,22 +1,59 @@
-import { CONFIRM_OPTION } from "./confirm.js";
-export const JSON_FLAG = {
-    usage: "--json",
+import * as z from "zod";
+import { argFields, kebab, optionFields } from "./input.js";
+import { LIST_FLAGS } from "./list.js";
+export const HELP_FLAG = "--help";
+export const HELP_SHORT = "-h";
+export const VERSION_FLAG = "--version";
+// The Runtime reads these at every level of the command line, so no Command can declare them.
+const ROUTING_FLAGS = [HELP_FLAG, HELP_SHORT, VERSION_FLAG];
+function nameOf(flag) {
+    return flag.replace(/^--?/, "");
+}
+function standardFlag(flag, { placeholder, ...rest }) {
+    return { flag, usage: placeholder === undefined ? flag : `${flag} ${placeholder}`, ...rest };
+}
+export const JSON_FLAG = standardFlag("--json", {
     description: "print the result as JSON",
-    effects: ["read", "write", "destructive"],
-};
-export const DRY_RUN_FLAG = {
-    usage: "--dry-run",
+    takes: "nothing",
+    schema: z.boolean(),
+});
+export const DRY_RUN_FLAG = standardFlag("--dry-run", {
     description: "print the Plan without changing anything",
-    effects: ["write", "destructive"],
-};
-export const CONFIRM_FLAG = {
-    usage: `${CONFIRM_OPTION} <target>`,
+    takes: "nothing",
+    schema: z.boolean(),
+});
+export const CONFIRM_FLAG = standardFlag("--confirm", {
+    placeholder: "<target>",
     description: "name the target to confirm the change; an error hint gives the exact command",
-    effects: ["destructive"],
+    takes: "value",
+    schema: z.string(),
+});
+const EFFECT_FLAGS = {
+    read: [JSON_FLAG],
+    write: [JSON_FLAG, DRY_RUN_FLAG],
+    destructive: [JSON_FLAG, DRY_RUN_FLAG, CONFIRM_FLAG],
 };
-// A Command's help lists every flag here whose effects include the Command's Effect.
-const RUNTIME_FLAGS = [JSON_FLAG, DRY_RUN_FLAG, CONFIRM_FLAG];
-export function runtimeFlagsFor(effect) {
-    return RUNTIME_FLAGS.filter((flag) => flag.effects.includes(effect));
+// Every name is reserved on every Command, whatever flags it gets, so a name means one thing.
+const RESERVED = new Map([...ROUTING_FLAGS, ...EFFECT_FLAGS.destructive.map(({ flag }) => flag), ...LIST_FLAGS].map((flag) => [nameOf(flag), flag]));
+/** The Standard flags of a Command with this Effect, and of a List Command. */
+export function standardFlagsFor(effect, list) {
+    return [...EFFECT_FLAGS[effect], ...(list?.standardFlags ?? [])];
+}
+/** Throws when the Command declares an arg or option under a Standard flag's name. */
+export function checkNoStandardFlags(command) {
+    const declared = [
+        ...argFields(command.args).map(({ key }) => ({ kind: "arg", key })),
+        ...optionFields(command.options).map(({ key }) => ({ kind: "option", key })),
+    ];
+    const lines = declared.flatMap(({ kind, key }) => {
+        const flag = RESERVED.get(kebab(key));
+        return flag === undefined ? [] : [`  ${kind} '${key}' is the Standard flag ${flag}`];
+    });
+    if (lines.length > 0) {
+        throw new Error([
+            `Command '${command.name}' declares Standard flags the Runtime adds; rename them:`,
+            ...lines,
+        ].join("\n"));
+    }
 }
 //# sourceMappingURL=flags.js.map

package/dist/flags.js.map

@@ -1 +1 @@
-{"version":3,"file":"flags.js","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAW9C,MAAM,CAAC,MAAM,SAAS,GAAgB;IACpC,KAAK,EAAE,QAAQ;IACf,WAAW,EAAE,0BAA0B;IACvC,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,aAAa,CAAC;CAC1C,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GAAgB;IACvC,KAAK,EAAE,WAAW;IAClB,WAAW,EAAE,0CAA0C;IACvD,OAAO,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC;CAClC,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GAAgB;IACvC,KAAK,EAAE,GAAG,cAAc,WAAW;IACnC,WAAW,EAAE,8EAA8E;IAC3F,OAAO,EAAE,CAAC,aAAa,CAAC;CACzB,CAAC;AAEF,qFAAqF;AACrF,MAAM,aAAa,GAA2B,CAAC,SAAS,EAAE,YAAY,EAAE,YAAY,CAAC,CAAC;AAEtF,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,OAAO,aAAa,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;AACvE,CAAC"}
+{"version":3,"file":"flags.js","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":"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"}

package/dist/global-install.d.ts

@@ -4,6 +4,8 @@ export interface InstalledCopy {
     readonly prefix: string;
     readonly packageDir: string;
 }
+/** Where npm puts global packages under its global prefix. */
+export declare function globalModulesDir(prefix: string): string;
 /**
  * The global npm install this copy runs from, found by asking npm for its global prefix.
  * `bin` is the script that started the CLI; throws `NOT_GLOBAL_INSTALL` when it is not inside that install.

package/dist/global-install.js

@@ -2,10 +2,11 @@ import { lstat, realpath } from "node:fs/promises";
 import { isAbsolute, join, relative } from "node:path";
 import { CliError, isMissingFile } from "./errors.js";
 import { globalPrefix, installCommandLine } from "./npm.js";
-function packageDirUnder(prefix, name) {
+/** Where npm puts global packages under its global prefix. */
+export function globalModulesDir(prefix) {
     return process.platform === "win32"
-        ? join(prefix, "node_modules", name)
-        : join(prefix, "lib", "node_modules", name);
+        ? join(prefix, "node_modules")
+        : join(prefix, "lib", "node_modules");
 }
 function notGlobal(ctx, message) {
     return new CliError({
@@ -35,7 +36,7 @@ export async function globalInstallOf(bin, ctx) {
         throw notGlobal(ctx, `${ctx.cliName} runs from source, not from an npm install`);
     }
     const prefix = await globalPrefix(ctx);
-    const packageDir = packageDirUnder(prefix, ctx.install.package);
+    const packageDir = join(globalModulesDir(prefix), ctx.install.package);
     const installed = await realpathOrUndefined(packageDir);
     const here = (await realpathOrUndefined(bin)) ?? bin;
     if (installed === undefined || !isInside(installed, here)) {

package/dist/global-install.js.map

@@ -1 +1 @@
-{"version":3,"file":"global-install.js","sourceRoot":"","sources":["../src/global-install.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAmB,MAAM,UAAU,CAAC;AAQ7E,SAAS,eAAe,CAAC,MAAc,EAAE,IAAY;IACnD,OAAO,OAAO,CAAC,QAAQ,KAAK,OAAO;QACjC,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,CAAC;QACpC,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,CAAC,CAAC;AAChD,CAAC;AAED,SAAS,SAAS,CAAC,GAAe,EAAE,OAAe;IACjD,OAAO,IAAI,QAAQ,CAAC;QAClB,IAAI,EAAE,oBAAoB;QAC1B,OAAO;QACP,IAAI,EAAE,6BAA6B,GAAG,CAAC,OAAO,6BAA6B,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE;QAC5G,SAAS,EAAE,KAAK;KACjB,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,mBAAmB,CAAC,IAAY;IAC7C,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QAC7C,IAAI,aAAa,CAAC,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QAC3C,MAAM,KAAK,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,QAAQ,CAAC,GAAW,EAAE,IAAY;IACzC,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAClC,OAAO,KAAK,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;AACvE,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,GAAuB,EACvB,GAAe;IAEf,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,MAAM,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC,OAAO,4CAA4C,CAAC,CAAC;IACnF,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,CAAC;IACvC,MAAM,UAAU,GAAG,eAAe,CAAC,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAChE,MAAM,SAAS,GAAG,MAAM,mBAAmB,CAAC,UAAU,CAAC,CAAC;IACxD,MAAM,IAAI,GAAG,CAAC,MAAM,mBAAmB,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC;IACrD,IAAI,SAAS,KAAK,SAAS,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,CAAC;QAC1D,MAAM,SAAS,CACb,GAAG,EACH,GAAG,GAAG,CAAC,OAAO,cAAc,IAAI,sCAAsC,UAAU,EAAE,CACnF,CAAC;IACJ,CAAC;IACD,6EAA6E;IAC7E,IAAI,CAAC,MAAM,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC;QAC/C,MAAM,SAAS,CACb,GAAG,EACH,GAAG,GAAG,CAAC,OAAO,wBAAwB,SAAS,sCAAsC,CACtF,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;AAChC,CAAC"}
+{"version":3,"file":"global-install.js","sourceRoot":"","sources":["../src/global-install.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAmB,MAAM,UAAU,CAAC;AAQ7E,8DAA8D;AAC9D,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,OAAO,OAAO,CAAC,QAAQ,KAAK,OAAO;QACjC,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,cAAc,CAAC;QAC9B,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC;AAC1C,CAAC;AAED,SAAS,SAAS,CAAC,GAAe,EAAE,OAAe;IACjD,OAAO,IAAI,QAAQ,CAAC;QAClB,IAAI,EAAE,oBAAoB;QAC1B,OAAO;QACP,IAAI,EAAE,6BAA6B,GAAG,CAAC,OAAO,6BAA6B,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE;QAC5G,SAAS,EAAE,KAAK;KACjB,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,mBAAmB,CAAC,IAAY;IAC7C,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QAC7C,IAAI,aAAa,CAAC,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QAC3C,MAAM,KAAK,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,QAAQ,CAAC,GAAW,EAAE,IAAY;IACzC,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAClC,OAAO,KAAK,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;AACvE,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,GAAuB,EACvB,GAAe;IAEf,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,MAAM,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC,OAAO,4CAA4C,CAAC,CAAC;IACnF,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,CAAC;IACvC,MAAM,UAAU,GAAG,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACvE,MAAM,SAAS,GAAG,MAAM,mBAAmB,CAAC,UAAU,CAAC,CAAC;IACxD,MAAM,IAAI,GAAG,CAAC,MAAM,mBAAmB,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC;IACrD,IAAI,SAAS,KAAK,SAAS,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,CAAC;QAC1D,MAAM,SAAS,CACb,GAAG,EACH,GAAG,GAAG,CAAC,OAAO,cAAc,IAAI,sCAAsC,UAAU,EAAE,CACnF,CAAC;IACJ,CAAC;IACD,6EAA6E;IAC7E,IAAI,CAAC,MAAM,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC;QAC/C,MAAM,SAAS,CACb,GAAG,EACH,GAAG,GAAG,CAAC,OAAO,wBAAwB,SAAS,sCAAsC,CACtF,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;AAChC,CAAC"}

package/dist/help-json.d.ts

@@ -1,4 +1,4 @@
-import { type Command, type Commands } from "./define.js";
-export declare function cliHelpJson(name: string, version: string, root: Command | Commands): string;
-export declare function groupHelpJson(commandLine: string, commands: Commands): string;
-export declare function commandHelpJson(commandLine: string, command: Command): string;
+import type { CommandSpec, GroupSpec, SpecNode } from "./command-spec.js";
+export declare function cliHelpJson(version: string, root: SpecNode): string;
+export declare function groupHelpJson(group: GroupSpec): string;
+export declare function commandHelpJson(spec: CommandSpec): string;

package/dist/help-json.js

@@ -1,60 +1,44 @@
 import * as z from "zod";
-import { isCommand } from "./define.js";
-import { fieldsDescription, rowFieldsOf } from "./fields.js";
-import { runtimeFlagsFor } from "./flags.js";
-import { kebab } from "./input.js";
 // Transforms and other unrepresentable parts become `{}` rather than failing the whole help.
 function inputSchema(schema) {
-    return z.toJSONSchema(schema ?? z.object({}), { io: "input", unrepresentable: "any" });
-}
-// Options are keyed as the caller types them, so `greetingWord` reads `greeting-word`.
-function optionsSchema(command) {
-    const shape = Object.entries(command.options?.shape ?? {}).map(([key, value]) => [
-        kebab(key),
-        value,
-    ]);
-    const rowFields = rowFieldsOf(command);
-    const fields = rowFields === undefined
-        ? []
-        : [["fields", z.string().optional().describe(fieldsDescription(rowFields))]];
-    return inputSchema(z.object(Object.fromEntries([...shape, ...fields])));
-}
-function commandData(commandLine, command) {
+    return z.toJSONSchema(schema, { io: "input", unrepresentable: "any" });
+}
+// Keys are the names the caller types, so option `greetingWord` reads `greeting-word`.
+function optionsSchema(options) {
+    return inputSchema(z.object(Object.fromEntries(options.map(({ name, schema }) => [name, schema]))));
+}
+function commandData(spec) {
     return {
-        name: commandLine,
-        description: command.description,
-        effect: command.effect,
-        examples: command.examples,
-        args: inputSchema(command.args),
-        options: optionsSchema(command),
-        standardFlags: runtimeFlagsFor(command.effect).map(({ usage, description }) => ({
+        name: spec.commandLine,
+        description: spec.description,
+        effect: spec.effect,
+        examples: spec.examples,
+        args: inputSchema(spec.command.args ?? z.object({})),
+        options: optionsSchema(spec.options),
+        standardFlags: spec.standardFlags.map(({ usage, description, schema }) => ({
             usage,
             description,
+            schema: inputSchema(schema),
         })),
-        output: command.output === undefined
-            ? null
-            : z.toJSONSchema(command.output, { unrepresentable: "any" }),
+        output: spec.output === undefined ? null : z.toJSONSchema(spec.output, { unrepresentable: "any" }),
     };
 }
-function nodeData(commandLine, node) {
-    return isCommand(node) ? commandData(commandLine, node) : groupData(commandLine, node);
+function nodeData(node) {
+    return node.kind === "command" ? commandData(node) : groupData(node);
 }
-function groupData(commandLine, commands) {
-    return {
-        name: commandLine,
-        commands: Object.entries(commands).map(([key, node]) => nodeData(`${commandLine} ${key}`, node)),
-    };
+function groupData(group) {
+    return { name: group.commandLine, commands: Object.values(group.commands).map(nodeData) };
 }
 function printed(data) {
     return `${JSON.stringify(data)}\n`;
 }
-export function cliHelpJson(name, version, root) {
-    return printed({ name, version, ...nodeData(name, root) });
+export function cliHelpJson(version, root) {
+    return printed({ name: root.commandLine, version, ...nodeData(root) });
 }
-export function groupHelpJson(commandLine, commands) {
-    return printed(groupData(commandLine, commands));
+export function groupHelpJson(group) {
+    return printed(groupData(group));
 }
-export function commandHelpJson(commandLine, command) {
-    return printed(commandData(commandLine, command));
+export function commandHelpJson(spec) {
+    return printed(commandData(spec));
 }
 //# sourceMappingURL=help-json.js.map

package/dist/help-json.js.map

@@ -1 +1 @@
-{"version":3,"file":"help-json.js","sourceRoot":"","sources":["../src/help-json.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"help-json.js","sourceRoot":"","sources":["../src/help-json.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAMzB,6FAA6F;AAC7F,SAAS,WAAW,CAAC,MAAiB;IACpC,OAAO,CAAC,CAAC,YAAY,CAAC,MAAM,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,CAAC,CAAC;AACzE,CAAC;AAED,uFAAuF;AACvF,SAAS,aAAa,CAAC,OAA8B;IACnD,OAAO,WAAW,CAChB,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAChF,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,IAAiB;IACpC,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,WAAW;QACtB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,IAAI,EAAE,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACpD,OAAO,EAAE,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC;QACpC,aAAa,EAAE,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;YACzE,KAAK;YACL,WAAW;YACX,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC;SAC5B,CAAC,CAAC;QACH,MAAM,EACJ,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,eAAe,EAAE,KAAK,EAAE,CAAC;KAC7F,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CAAC,IAAc;IAC9B,OAAO,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;AACvE,CAAC;AAED,SAAS,SAAS,CAAC,KAAgB;IACjC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,WAAW,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;AAC5F,CAAC;AAED,SAAS,OAAO,CAAC,IAAgB;IAC/B,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAAe,EAAE,IAAc;IACzD,OAAO,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACzE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAgB;IAC5C,OAAO,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAiB;IAC/C,OAAO,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC;AACpC,CAAC"}

package/dist/help.d.ts

@@ -1,6 +1,5 @@
-import { type Command, type Commands } from "./define.js";
-import type { InputFields } from "./input.js";
+import type { CommandSpec, GroupSpec } from "./command-spec.js";
 import type { Style } from "./style.js";
-export declare function cliHelp(name: string, version: string, commands: Commands, style: Style): string;
-export declare function groupHelp(commandLine: string, commands: Commands, style: Style): string;
-export declare function commandHelp(commandLine: string, command: Command, fields: InputFields, style: Style): string;
+export declare function cliHelp(version: string, root: GroupSpec, style: Style): string;
+export declare function groupHelp(group: GroupSpec, style: Style): string;
+export declare function commandHelp(spec: CommandSpec, style: Style): string;