@duyquangnvx/agent-cli 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+What changed in each release of `@duyquangnvx/agent-cli` (the Runtime) and `@duyquangnvx/create-agent-cli` (the Scaffolder), which are released together at one version, newest first, in the format of [Keep a Changelog 2.0](https://keepachangelog.com/en/2.0.0/). Each change lands under `## Unreleased` as it merges, grouped under `### Added`, `### Changed`, `### Fixed` or `### Removed`. A breaking change starts with `**Breaking:**` and names what breaks: an export, a Cli or Command field, a built-in Command, a flag, a `--json` field, an exit code, the scaffolded template or the skill. A release turns `## Unreleased` into `## vX.Y.Z (YYYY-MM-DD)`.
+
+## 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
+
+- The Runtime, `@duyquangnvx/agent-cli`: `defineCli` and `defineCommand` declare Commands with Zod arguments and options and a read, write or destructive Effect, and the Runtime owns parsing, layered help, `--json` output, errors with codes and hints, and exit codes 0, 1 and 2. Write and destructive Commands get `--dry-run` from their Plan, destructive ones a confirmation, and `pageOptions`, `pageOf` and `paginate` page a list. `runCli` runs a CLI in-process for tests; `runProcess` runs it as a bin, which exits once its output is written.
+- The Scaffolder, `@duyquangnvx/create-agent-cli`: `npm create @duyquangnvx/agent-cli <name>` creates a repo for a new Agent CLI with one example Command, its test, a skeleton skill, the gate scripts and a first commit.
+- Every multi-Command CLI has a built-in `doctor`: one row per check (`node`, `install`, `registry`, `skill`, then the CLI's own `doctor` rows), each under its own 10 s deadline, followed by the commands that fix each problem. It exits 1 with `DOCTOR_PROBLEMS` when a row is a problem; `--json` returns the rows as data.
+- Every multi-Command CLI has a built-in `update`, which installs the latest version from the CLI's registry with `npm install --global`, prints the upgrade notes from the new `CHANGELOG.md` for each version it passed, and says to update the skill. `--dry-run` shows the version it would install. Ctrl-C never stops npm halfway: once the install has started it finishes, and `update` fails with `INTERRUPTED` saying the new version is installed. It fails with `NOT_GLOBAL_INSTALL`, `REGISTRY_UNREACHABLE`, `REGISTRY_AUTH`, `NO_LATEST` or `INSTALL_FAILED`.
+- A Cli declares `install` (a global npm install of its package from its registry), `engines` and `doctor` rows, which `doctor` and `update` read.
+- A Command whose `output` is a `pageOf(row)` schema accepts `--fields`, which keeps only the named columns in both text and `--json` output; an unknown name is a usage error listing the valid ones.
+- `--help --json` at any level returns the Commands, arguments, options, Effects and examples as data, with each Command's output JSON Schema from its `output`.
+- Ctrl-C or SIGTERM aborts the Command's `ctx.signal` and the run fails with `INTERRUPTED`; a second signal exits at once with 130 or 143. `ctx.deadline(ms)` returns a signal that aborts with `DEADLINE_EXCEEDED`, `ctx.runToEnd(work)` marks a step the process finishes before it exits, and `runCli` takes a `signal` to cancel a run in-process.
+- A Cli with `build` prints `--version` as `X.Y.Z (sha)`, or `X.Y.Z (sha+dirty)` for a build from an unclean tree.
+- A scaffolded CLI bundles the Runtime and zod with tsdown, which stamps its version and commit into `--version`; both are devDependencies, so its own version alone decides its behaviour.
+- A scaffolded CLI declares a global install from npmjs and releases with `@duyquangnvx/release`, which stamps its skill and checks its `--version` before publishing.
+- The agent-cli skill, which teaches a Coding agent to build an Agent CLI on the Runtime: `npx skills add` installs it from this repo's `release` branch, and it names the Runtime version it describes.

package/README.md

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# @duyquangnvx/agent-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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/built-ins.d.ts

@@ -0,0 +1,4 @@
+import type { Cli, Commands, CommandTreeCli } from "./define.js";
+/** The Commands the Runtime adds to a multi-Command CLI: `update` only when it declares an install. */
+export declare function builtInCommands(cli: CommandTreeCli, bin: string | undefined): Commands;
+export declare function defineCli(cli: Cli): Cli;

package/dist/built-ins.js

@@ -0,0 +1,20 @@
+import { doctorCommand } from "./doctor.js";
+import { updateCommand } from "./update.js";
+/** The Commands the Runtime adds to a multi-Command CLI: `update` only when it declares an install. */
+export function builtInCommands(cli, bin) {
+    return {
+        doctor: doctorCommand(cli, bin),
+        ...(cli.install === undefined ? {} : { update: updateCommand(cli, cli.install, bin) }),
+    };
+}
+export function defineCli(cli) {
+    if (cli.commands === undefined)
+        return cli;
+    const { commands } = cli;
+    const taken = Object.keys(builtInCommands(cli, undefined)).filter((name) => commands[name] !== undefined);
+    if (taken.length > 0) {
+        throw new Error(`${cli.name} defines ${taken.join(", ")}, a built-in Command it cannot replace`);
+    }
+    return cli;
+}
+//# sourceMappingURL=built-ins.js.map

package/dist/built-ins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"built-ins.js","sourceRoot":"","sources":["../src/built-ins.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,uGAAuG;AACvG,MAAM,UAAU,eAAe,CAAC,GAAmB,EAAE,GAAuB;IAC1E,OAAO;QACL,MAAM,EAAE,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC;QAC/B,GAAG,CAAC,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC;KACvF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,GAAQ;IAChC,IAAI,GAAG,CAAC,QAAQ,KAAK,SAAS;QAAE,OAAO,GAAG,CAAC;IAC3C,MAAM,EAAE,QAAQ,EAAE,GAAG,GAAG,CAAC;IACzB,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC,MAAM,CAC/D,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,SAAS,CACvC,CAAC;IACF,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CACb,GAAG,GAAG,CAAC,IAAI,YAAY,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,wCAAwC,CAChF,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

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

@@ -0,0 +1,7 @@
+import { type Invocation } from "./invocation.js";
+export interface Confirmation {
+    readonly invocation: Invocation;
+    readonly commandLine: string;
+    readonly given: string | undefined;
+}
+export declare function checkConfirmation({ invocation, commandLine, given }: Confirmation, expected: string): void;

package/dist/confirm.js

@@ -0,0 +1,22 @@
+import { UsageError } from "./errors.js";
+import { CONFIRM_FLAG } from "./flags.js";
+import { commandLineWith } from "./invocation.js";
+export function checkConfirmation({ invocation, commandLine, given }, expected) {
+    if (given === expected) {
+        return;
+    }
+    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_FLAG.flag}`,
+            hint,
+        });
+    }
+    throw new UsageError({
+        code: "CONFIRMATION_MISMATCH",
+        message: `${CONFIRM_FLAG.flag} ${JSON.stringify(given)} does not match the target of \`${commandLine}\``,
+        hint,
+    });
+}
+//# sourceMappingURL=confirm.js.map

package/dist/confirm.js.map

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,132 @@
+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 {
+    readonly command: string;
+    readonly note: string;
+}
+export interface Context {
+    readonly cwd: string;
+    readonly env: Env;
+    /** Writes a plain line to stderr, for long work; it never reaches stdout. */
+    progress(message: string): void;
+    /** Aborts when the run is interrupted (Ctrl-C); pass it to `fetch` and child processes. */
+    readonly signal: AbortSignal;
+    /** Returns a signal that also aborts, with `DEADLINE_EXCEEDED`, once `ms` have passed. */
+    deadline(ms: number): AbortSignal;
+    /** Runs a step that must not stop halfway: the run waits for it even when interrupted. */
+    runToEnd<T>(work: () => Promise<T>): Promise<T>;
+}
+export type InputSchema = z.ZodObject;
+export type NoInput = z.ZodObject<Record<never, never>>;
+type OutputOf<Schema extends InputSchema> = keyof Schema["shape"] extends never ? unknown : z.output<Schema>;
+type Flatten<T> = {
+    [K in keyof T]: T[K];
+};
+export type Input<Args extends InputSchema, Options extends InputSchema> = Flatten<OutputOf<Args> & OutputOf<Options>>;
+interface CommandBase<Args extends InputSchema, Options extends InputSchema> {
+    readonly name: string;
+    readonly description: string;
+    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 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 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;
+    renderPlan(plan: Plan, style: Style): string;
+}
+export interface WriteCommand<Args extends InputSchema, Options extends InputSchema, Plan, Data> extends PlannedCommand<Args, Options, Plan, Data> {
+    readonly effect: "write";
+}
+export interface DestructiveCommand<Args extends InputSchema, Options extends InputSchema, Plan, Data> extends PlannedCommand<Args, Options, Plan, Data> {
+    readonly effect: "destructive";
+    /** 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> | ListCommand<InputSchema, InputSchema, RowSchema> | WriteCommand<InputSchema, InputSchema, unknown, unknown> | DestructiveCommand<InputSchema, InputSchema, unknown, unknown>;
+export interface Commands {
+    readonly [key: string]: Command | Commands;
+}
+interface CliBase {
+    readonly name: string;
+    readonly version: string;
+    /** The commit the build was made from, stamped by the bundler; `--version` prints it. */
+    readonly build?: {
+        readonly sha: string;
+        readonly dirty: boolean;
+    };
+}
+/** Where an Agent CLI is published and how it is installed; `doctor` and `update` read it. */
+export interface GlobalInstall {
+    readonly mode: "global";
+    readonly package: string;
+    readonly registry: string;
+}
+export interface DoctorFinding {
+    readonly state: "ok" | "problem";
+    readonly message: string;
+    /** The command that fixes the problem. */
+    readonly fix?: string;
+}
+/** A row the CLI adds to `doctor`, for a system it depends on. */
+export interface DoctorCheck {
+    readonly name: string;
+    /** `ctx.signal` aborts at the 10 s deadline. A thrown error is reported as this row's problem. */
+    run(ctx: Context): DoctorFinding | Promise<DoctorFinding>;
+}
+/** An Agent CLI whose Commands are reached by name, as in `tool voices list`. */
+export interface CommandTreeCli extends CliBase {
+    readonly commands: Commands;
+    readonly command?: never;
+    /** Absent for a CLI that is not published: `doctor` then checks no install or registry. */
+    readonly install?: GlobalInstall;
+    /** The package.json `engines`; `doctor` checks `node` when it is `>=X[.Y[.Z]]`. */
+    readonly engines?: {
+        readonly node?: string;
+    };
+    readonly doctor?: readonly DoctorCheck[];
+}
+/** An Agent CLI that is one Command, run with no Command name, as in `tool <args>`. */
+export interface SingleCommandCli extends CliBase {
+    readonly command: Command;
+    readonly commands?: never;
+}
+export type Cli = CommandTreeCli | SingleCommandCli;
+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

@@ -0,0 +1,10 @@
+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.
+export function isCommand(node) {
+    return typeof node.effect === "string";
+}
+//# sourceMappingURL=define.js.map

package/dist/define.js.map

@@ -0,0 +1 @@
+{"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/doctor-rows.d.ts

@@ -0,0 +1,3 @@
+import type { CommandTreeCli, DoctorCheck } from "./define.js";
+/** The rows every `doctor` reports first, in this order. */
+export declare function fixedRows(cli: CommandTreeCli, bin: string | undefined): DoctorCheck[];

package/dist/doctor-rows.js

@@ -0,0 +1,115 @@
+import { CliError } from "./errors.js";
+import { globalInstallOf } from "./global-install.js";
+import { installCommandLine, latestVersion, npmContext } from "./npm.js";
+import { engineMinimum, meetsMinimum, standingOf } from "./semver.js";
+import { skillCopies, skillUpdateCommand } from "./skills.js";
+function ok(message) {
+    return { state: "ok", message };
+}
+function nodeRow(cli) {
+    return {
+        name: "node",
+        run: () => {
+            const found = process.versions.node;
+            const range = cli.engines?.node;
+            if (range === undefined) {
+                return ok(`Node ${found}; ${cli.name} declares no engines.node to check it against`);
+            }
+            const minimum = engineMinimum(range);
+            if (minimum === undefined) {
+                return {
+                    state: "problem",
+                    message: `${cli.name} declares engines.node "${range}", which doctor cannot read: only >=X.Y.Z is supported`,
+                };
+            }
+            if (meetsMinimum(found, minimum)) {
+                return ok(`Node ${found} meets ${range}`);
+            }
+            const major = minimum[0];
+            return {
+                state: "problem",
+                message: `${cli.name} runs on Node ${found}, older than the ${range} it needs; install Node ${minimum.join(".")} or newer and make it the default`,
+                fix: `nvm install ${major} && nvm alias default ${major}`,
+            };
+        },
+    };
+}
+function installRow(cli, bin) {
+    return {
+        name: "install",
+        run: async (ctx) => {
+            const { install } = cli;
+            if (install === undefined) {
+                return ok(`${cli.name} declares no install, so it has no \`update\``);
+            }
+            try {
+                const copy = await globalInstallOf(bin, npmContext(cli, install, ctx));
+                return ok(`a global npm install under ${copy.prefix}`);
+            }
+            catch (error) {
+                if (error instanceof CliError && error.code === "NOT_GLOBAL_INSTALL") {
+                    return { state: "problem", message: error.message, fix: installCommandLine(install) };
+                }
+                throw error;
+            }
+        },
+    };
+}
+function registryRow(cli) {
+    return {
+        name: "registry",
+        run: async (ctx) => {
+            const { install } = cli;
+            if (install === undefined) {
+                return ok(`${cli.name} declares no registry to compare this build with`);
+            }
+            const latest = await latestVersion(npmContext(cli, install, ctx));
+            const standing = standingOf(cli.version, latest);
+            const head = `${install.registry} has ${latest} as latest: this build`;
+            if (standing === "behind") {
+                return {
+                    state: "problem",
+                    message: `${head} (${cli.version}) is older`,
+                    fix: `${cli.name} update`,
+                };
+            }
+            return ok(`${head} is ${standing === "current" ? "current" : `newer (${cli.version})`}`);
+        },
+    };
+}
+const SKILL_STATE_NOTES = {
+    current: "the same as this build",
+    behind: "older than this build",
+    ahead: "newer than this build",
+    unversioned: "states no metadata.version",
+    unreadable: "could not be read",
+};
+function describeCopy({ path, version, state }) {
+    return `${path}${version === undefined ? "" : ` ${version}`} (${SKILL_STATE_NOTES[state]})`;
+}
+function skillFix(cli, copies) {
+    if (copies.some(({ state }) => state === "behind" || state === "unversioned")) {
+        return skillUpdateCommand(cli.name);
+    }
+    return copies.some(({ state }) => state === "ahead") ? `${cli.name} update` : undefined;
+}
+// A skill describes the CLI but never stops it working, so this row is always ok.
+function skillRow(cli) {
+    return {
+        name: "skill",
+        run: async (ctx) => {
+            const copies = await skillCopies(cli.name, cli.version, ctx.cwd, ctx.env);
+            if (copies.length === 0) {
+                return ok(`no copy of the ${cli.name} skill is installed`);
+            }
+            const fix = skillFix(cli, copies);
+            const message = copies.map(describeCopy).join("; ");
+            return fix === undefined ? ok(message) : { state: "ok", message, fix };
+        },
+    };
+}
+/** The rows every `doctor` reports first, in this order. */
+export function fixedRows(cli, bin) {
+    return [nodeRow(cli), installRow(cli, bin), registryRow(cli), skillRow(cli)];
+}
+//# sourceMappingURL=doctor-rows.js.map

package/dist/doctor-rows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-rows.js","sourceRoot":"","sources":["../src/doctor-rows.ts"],"names":[],"mappings":"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"}

package/dist/doctor.d.ts

@@ -0,0 +1,3 @@
+import { type Command, type CommandTreeCli } from "./define.js";
+/** The built-in `doctor`: the fixed rows, then the CLI's own, each under its own deadline. */
+export declare function doctorCommand(cli: CommandTreeCli, bin: string | undefined): Command;

package/dist/doctor.js

@@ -0,0 +1,100 @@
+import * as z from "zod";
+import { defineCommand, } from "./define.js";
+import { fixedRows } from "./doctor-rows.js";
+import { CliError, FailureWithData, messageOf } from "./errors.js";
+const PROBE_DEADLINE_MS = 10_000;
+const MS_PER_SECOND = 1000;
+const MIN_LABEL_WIDTH = 8;
+const rowSchema = z.object({
+    check: z.string(),
+    state: z.enum(["ok", "problem"]),
+    message: z.string(),
+    fix: z.string().optional(),
+});
+const reportSchema = z.object({
+    rows: z.array(rowSchema),
+    next: z.array(z.string()),
+});
+function untilAborted(signal) {
+    return new Promise((_resolve, reject) => {
+        if (signal.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+    });
+}
+function problemOf(check, error, { signal, deadline }) {
+    if (!signal.aborted && deadline.aborted && error === deadline.reason) {
+        return {
+            state: "problem",
+            message: `${check.name} did not answer within ${PROBE_DEADLINE_MS / MS_PER_SECOND} s`,
+        };
+    }
+    if (error instanceof CliError) {
+        return { state: "problem", message: `${error.message}; ${error.hint}` };
+    }
+    return { state: "problem", message: `the ${check.name} row hit a bug: ${messageOf(error)}` };
+}
+// Racing the deadline ends a row whose check ignores its signal.
+async function rowOf(check, ctx) {
+    const signal = ctx.deadline(PROBE_DEADLINE_MS);
+    let finding;
+    try {
+        finding = await Promise.race([
+            Promise.resolve().then(() => check.run({ ...ctx, signal })),
+            untilAborted(signal),
+        ]);
+    }
+    catch (error) {
+        finding = problemOf(check, error, { signal: ctx.signal, deadline: signal });
+    }
+    return { check: check.name, ...finding };
+}
+function nextOf(rows) {
+    return [...new Set(rows.flatMap(({ fix }) => (fix === undefined ? [] : [fix])))];
+}
+function render({ rows, next }, style) {
+    const width = Math.max(MIN_LABEL_WIDTH, ...rows.map(({ check }) => check.length)) + 2;
+    const stateWidth = Math.max(...rows.map(({ state }) => state.length)) + 2;
+    const lines = rows.map(({ check, state, message }) => {
+        const label = state === "problem" ? style.red(state) : state;
+        return `${check.padEnd(width)}${label}${" ".repeat(stateWidth - state.length)}${message}`;
+    });
+    return [...lines, ...next.map((fix) => `${"next".padEnd(width)}${fix}`)].join("\n");
+}
+function failure(cliName, report) {
+    const problems = report.rows.filter(({ state }) => state === "problem").map(({ check }) => check);
+    return new FailureWithData({
+        code: "DOCTOR_PROBLEMS",
+        message: `${cliName} doctor found ${problems.length === 1 ? "a problem" : `${problems.length} problems`}: ${problems.join(", ")}`,
+        hint: report.next.length === 0
+            ? "each problem row says what is wrong"
+            : "run the commands under next, then run doctor again",
+        retryable: false,
+    }, report);
+}
+/** The built-in `doctor`: the fixed rows, then the CLI's own, each under its own deadline. */
+export function doctorCommand(cli, bin) {
+    return defineCommand({
+        name: "doctor",
+        description: "check the setup and say what fixes each problem",
+        examples: [
+            { command: `${cli.name} doctor`, note: "check the setup and list the commands that fix it" },
+            { command: `${cli.name} doctor --json`, note: "get the rows and fixes as data" },
+        ],
+        effect: "read",
+        output: reportSchema,
+        run: async (_input, ctx) => {
+            const checks = [...fixedRows(cli, bin), ...(cli.doctor ?? [])];
+            const rows = await Promise.all(checks.map((check) => rowOf(check, ctx)));
+            const report = { rows, next: nextOf(rows) };
+            if (rows.some(({ state }) => state === "problem")) {
+                throw failure(cli.name, report);
+            }
+            return report;
+        },
+        render,
+    });
+}
+//# sourceMappingURL=doctor.js.map

package/dist/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,34 @@
+import type { Env } from "./define.js";
+import type { Style } from "./style.js";
+export interface CliErrorDetails {
+    readonly code: string;
+    readonly message: string;
+    readonly hint: string;
+    readonly retryable: boolean;
+}
+export declare class CliError extends Error {
+    readonly code: string;
+    readonly hint: string;
+    readonly retryable: boolean;
+    constructor({ code, message, hint, retryable }: CliErrorDetails, options?: ErrorOptions);
+}
+export type UsageErrorDetails = Omit<CliErrorDetails, "retryable">;
+/** The caller called the Agent CLI wrong; retrying the same call can't succeed. */
+export declare class UsageError extends CliError {
+    constructor(details: UsageErrorDetails);
+}
+export interface ErrorFormat {
+    readonly cliName: string;
+    readonly json: boolean;
+    readonly env: Env;
+    readonly style: Style;
+}
+export declare function isMissingFile(error: unknown): boolean;
+export declare function debugVariable(cliName: string): string;
+export declare function messageOf(error: unknown): string;
+export declare function formatRuntimeError(error: unknown, format: ErrorFormat): string;
+/** A failure that still prints the Command's data on stdout, as `doctor` does with its rows. */
+export declare class FailureWithData extends CliError {
+    readonly data: unknown;
+    constructor(details: CliErrorDetails, data: unknown);
+}