@duyquangnvx/agent-cli 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# 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.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/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/confirm.d.ts

@@ -0,0 +1,8 @@
+import { type Invocation } from "./invocation.js";
+export declare const CONFIRM_OPTION = "--confirm";
+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 { 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)}\``;
+    if (given === undefined) {
+        throw new UsageError({
+            code: "CONFIRMATION_REQUIRED",
+            message: `\`${commandLine}\` is destructive and needs ${CONFIRM_OPTION}`,
+            hint,
+        });
+    }
+    throw new UsageError({
+        code: "CONFIRMATION_MISMATCH",
+        message: `${CONFIRM_OPTION} ${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,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"}

package/dist/define.d.ts

@@ -0,0 +1,108 @@
+import type * as z from "zod";
+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;
+    readonly output?: z.ZodType;
+}
+export interface ReadCommand<Args extends InputSchema, Options extends InputSchema, Data> extends CommandBase<Args, Options> {
+    readonly effect: "read";
+    run(input: Input<Args, Options>, ctx: Context): Data | Promise<Data>;
+    render(data: Data, 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> {
+    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> | 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;
+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>;
+export declare function isCommand(node: Command | Commands): node is Command;
+export {};

package/dist/define.js

@@ -0,0 +1,8 @@
+export function defineCommand(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":"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"}

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);
+}

package/dist/errors.js

@@ -0,0 +1,72 @@
+export class CliError extends Error {
+    code;
+    hint;
+    retryable;
+    constructor({ code, message, hint, retryable }, options) {
+        super(message, options);
+        this.name = "CliError";
+        this.code = code;
+        this.hint = hint;
+        this.retryable = retryable;
+    }
+}
+/** The caller called the Agent CLI wrong; retrying the same call can't succeed. */
+export class UsageError extends CliError {
+    constructor(details) {
+        super({ ...details, retryable: false });
+        this.name = "UsageError";
+    }
+}
+const INTERNAL_CODE = "INTERNAL";
+export function isMissingFile(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+export function debugVariable(cliName) {
+    return `${cliName.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_DEBUG`;
+}
+export function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isDebug({ env, cliName }) {
+    return Boolean(env[debugVariable(cliName)]);
+}
+function detailsOf(error, format) {
+    if (error instanceof CliError) {
+        const { code, message, hint, retryable } = error;
+        return { code, message, hint, retryable };
+    }
+    return {
+        code: INTERNAL_CODE,
+        message: messageOf(error),
+        hint: isDebug(format)
+            ? "the stack trace shows where it failed"
+            : `rerun with ${debugVariable(format.cliName)}=1 to see the stack trace`,
+        retryable: false,
+    };
+}
+function stackOf(error, format) {
+    return isDebug(format) && !(error instanceof CliError) && error instanceof Error
+        ? error.stack
+        : undefined;
+}
+export function formatRuntimeError(error, format) {
+    const details = detailsOf(error, format);
+    const stack = stackOf(error, format);
+    if (format.json) {
+        return `${JSON.stringify({ ...details, stack })}\n`;
+    }
+    const { style } = format;
+    const label = style.red(error instanceof CliError ? "error:" : "internal error:");
+    const trace = stack === undefined ? "" : `${stack}\n`;
+    return `${label} ${details.message}\n${trace}${style.cyan("hint:")} ${details.hint}\n`;
+}
+/** A failure that still prints the Command's data on stdout, as `doctor` does with its rows. */
+export class FailureWithData extends CliError {
+    data;
+    constructor(details, data) {
+        super(details);
+        this.name = "FailureWithData";
+        this.data = data;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/execute.d.ts

@@ -0,0 +1,12 @@
+import { type Confirmation } from "./confirm.js";
+import type { Command, Context } from "./define.js";
+import type { Style } from "./style.js";
+export interface Outcome {
+    readonly value: unknown;
+    render(style: Style): string;
+}
+export interface ExecuteFlags {
+    readonly dryRun: boolean;
+    readonly confirmation: Confirmation;
+}
+export declare function execute(command: Command, input: Record<string, unknown>, ctx: Context, { dryRun, confirmation }: ExecuteFlags): Promise<Outcome>;

package/dist/execute.js

@@ -0,0 +1,18 @@
+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 }) {
+    if (command.effect === "read") {
+        return outcomeOf(await command.run(input, ctx), (data, style) => command.render(data, style));
+    }
+    const plan = await command.plan(input, ctx);
+    if (dryRun) {
+        return outcomeOf(plan, (value, style) => command.renderPlan(value, style));
+    }
+    if (command.effect === "destructive") {
+        checkConfirmation(confirmation, command.confirm(plan));
+    }
+    return outcomeOf(await command.apply(plan, ctx), (data, style) => command.render(data, style));
+}
+//# sourceMappingURL=execute.js.map

package/dist/execute.js.map

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

package/dist/fields.d.ts

@@ -0,0 +1,14 @@
+import type { Command } from "./define.js";
+import type { InputField } from "./input.js";
+export declare const FIELDS_OPTION = "--fields";
+type Row = Readonly<Record<string, unknown>>;
+/** The fields a list Command's rows have, or undefined for a Command that is not a list. */
+export declare function rowFieldsOf(command: Command): readonly string[] | undefined;
+export declare function fieldsDescription(rowFields: readonly string[]): string;
+export declare function fieldsOption(rowFields: readonly string[]): InputField;
+/** The fields the caller asked for, in their order, or undefined when they gave no `--fields`. */
+export declare function selectedFields(raw: string | boolean | undefined, rowFields: readonly string[], commandLine: string): readonly string[] | undefined;
+export declare function projected(rows: readonly unknown[], fields: readonly string[]): Row[];
+/** Selected rows as text: a header line of the field names, then one tab-separated line per row. */
+export declare function renderRows(rows: readonly Row[], fields: readonly string[]): string;
+export {};