@duyquangnvx/agent-cli 0.5.0 → 0.6.0

package/dist/command-spec.js.map

@@ -1 +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,EAAoC,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAChF,OAAO,EAAE,SAAS,EAAmB,YAAY,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAiB,QAAQ,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AA6BvC,oGAAoG;AACpG,MAAM,UAAU,eAAe,CAAC,EAAE,QAAQ,EAAa;IACrD,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CACrF,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,OAAgB;IAClC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAC3D,CAAC;IACD,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,OAAO,KAAK,SAAS;QACtC,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,IAAI,EAAE,OAAO,CAAC,IAAI,KAAK,SAAS;KACjC,CAAC;AACJ,CAAC;AAED,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,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,MAAM,EAAE,OAAO,CAAC,MAAM,KAAK,IAAI;QAC/B,QAAQ,EAAE,OAAO,CAAC,QAAQ,KAAK,IAAI;QACnC,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,UAAU,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC;QAC1E,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"}
+{"version":3,"file":"command-spec.js","sourceRoot":"","sources":["../src/command-spec.ts"],"names":[],"mappings":"AACA,OAAO,EAA6C,SAAS,EAAE,MAAM,aAAa,CAAC;AACnF,OAAO,EAAoC,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAChF,OAAO,EAAE,SAAS,EAAmB,YAAY,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAiB,QAAQ,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAiCvC,oGAAoG;AACpG,MAAM,UAAU,eAAe,CAAC,EAAE,QAAQ,EAAa;IACrD,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CACrF,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,OAAgB;IAClC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAC3D,CAAC;IACD,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,OAAO,KAAK,SAAS;QACtC,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,IAAI,EAAE,OAAO,CAAC,IAAI,KAAK,SAAS;KACjC,CAAC;AACJ,CAAC;AAOD,MAAM,cAAc,GAAc,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAE/D,MAAM,UAAU,WAAW,CACzB,WAAmB,EACnB,OAAgB,EAChB,EAAE,IAAI,EAAE,OAAO,EAAE,GAAc,cAAc;IAE7C,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,IAAI;QACJ,OAAO;QACP,OAAO;QACP,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,MAAM,EAAE,OAAO,CAAC,MAAM,KAAK,IAAI;QAC/B,QAAQ,EAAE,OAAO,CAAC,QAAQ,KAAK,IAAI;QACnC,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,UAAU,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC;QAC1E,IAAI;QACJ,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,OAAO,CAAC,MAAM;KACvC,CAAC;AACJ,CAAC;AAED,SAAS,KAAK,CAAC,WAAmB,EAAE,QAAkC;IACpE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC;AAClD,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,SAAS,CAAC,WAAmB,EAAE,QAAkB,EAAE,QAAkB;IACnF,OAAO,KAAK,CAAC,WAAW,EAAE;QACxB,GAAG,OAAO,CAAC,WAAW,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC/D,GAAG,OAAO,CAAC,WAAW,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;KAC/D,CAAC,CAAC;AACL,CAAC;AAED,SAAS,OAAO,CACd,WAAmB,EACnB,QAAkB,EAClB,EAAE,IAAI,EAAE,OAAO,EAAa;IAE5B,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC;QAC5C,GAAG;QACH,MAAM,CAAC,GAAG,WAAW,IAAI,GAAG,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC;KACzE,CAAC,CACH,CAAC;AACJ,CAAC;AAED,SAAS,MAAM,CAAC,WAAmB,EAAE,IAAwB,EAAE,KAAgB;IAC7E,OAAO,SAAS,CAAC,IAAI,CAAC;QACpB,CAAC,CAAC,WAAW,CAAC,WAAW,EAAE,IAAI,EAAE,KAAK,CAAC;QACvC,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;AAC5D,CAAC"}

package/dist/context.d.ts

@@ -26,20 +26,39 @@ export interface Context<Ports = unknown, Settings = unknown> {
     readonly build: BuildStamp | undefined;
     /**
      * The command line that reruns this CLI, to spawn one of its hidden Commands: Node, its flags and
-     * the bin, or the CLI's name, found on PATH, when run without a bin.
+     * the bin, or the CLI's name, found on PATH, when run without a bin. Spawn it as
+     * `ctx.spawn(self[0], [...self.slice(1), "daemon"])`.
      */
     readonly self: readonly string[];
-    /** The folder holding this CLI's `package.json`, for reading files shipped in the package. */
+    /**
+     * The folder holding this CLI's `package.json`, found from the running bin, for reading files the
+     * package ships; run through `runCli` without `bin`, it is found from `cwd`.
+     */
     readonly packageRoot: string;
-    /** Writes a plain line to stderr, for long work; it never reaches stdout. */
+    /**
+     * Writes a line to stderr, for long work; it never reaches stdout. Under `--json` the line is
+     * `{"progress":"..."}`.
+     */
     progress(message: string): void;
     /**
-     * Aborts when the run is interrupted (Ctrl-C) or hits the Command's run deadline; pass it to
-     * `fetch` and child processes.
+     * Aborts when the run is interrupted (Ctrl-C, SIGTERM, or `runCli`'s `signal`) or hits the
+     * Command's run deadline; pass it to `fetch` and the ports. An interrupt fails the run with
+     * `INTERRUPTED`, exit 130 for SIGINT or 143 for SIGTERM; a second Ctrl-C ends the process at once.
      */
     readonly signal: AbortSignal;
-    /** Returns a signal that also aborts, with `DEADLINE_EXCEEDED`, once `ms` have passed. */
+    /**
+     * Returns a signal that aborts with `ctx.signal`, and with `DEADLINE_EXCEEDED` (exit 75) once
+     * `ms` have passed. The run reports that deadline for each error, or leaf of an `AggregateError`,
+     * that is not a `CliError` and whose `cause` chain holds its abort; any other error is reported
+     * as it is, so a `CliError` keeping the abort as `cause` keeps its own code.
+     */
     deadline(ms: number): AbortSignal;
+    /**
+     * Returns a signal that aborts with `DEADLINE_EXCEEDED` (exit 75) once `ms` have passed, and
+     * follows neither `ctx.signal` nor the run deadline: it bounds a call inside `runToEnd` that
+     * Ctrl-C must not cut short. Its abort is reported as `ctx.deadline`'s is.
+     */
+    timeout(ms: number): AbortSignal;
     /**
      * Runs a step that must not stop halfway: the run waits for it even when stopped, and then
      * prints `finishing <name>` on stderr.
@@ -47,33 +66,47 @@ export interface Context<Ports = unknown, Settings = unknown> {
     runToEnd<T>(name: string, work: () => Promise<T>): Promise<T>;
     /**
      * Records the data done so far, in the shape `render` takes; the last call wins. A run that then
-     * fails, hits a deadline or is interrupted prints it; a returned value replaces it.
+     * fails, hits a deadline or is interrupted prints it on stdout beside its errors on stderr; a
+     * returned value replaces it. Delivered data spills like returned data.
      */
     deliver(data: unknown): void;
     /** The outside systems the CLI declared with `agentCli<Ports>()`. */
     readonly ports: Ports;
     /**
-     * Reads, lists, removes and atomically writes files and folders, paths resolved against `cwd`; a
-     * failure fails the run with `PERMISSION_DENIED`, `DISK_FULL`, `NOT_FOUND`, `NOT_A_FILE` or
-     * `ALREADY_EXISTS`.
+     * Reads, lists, removes and atomically writes files and folders, paths resolved against `cwd`. A
+     * failure fails the run naming the path: `PERMISSION_DENIED` (exit 2, with a hint on allowing the
+     * path in a Coding agent's sandbox), `DISK_FULL` (exit 2), `NOT_FOUND`, `NOT_A_FILE` or
+     * `ALREADY_EXISTS` (exit 1); the codes are exported.
      */
     readonly files: Files;
     /**
-     * Runs a child process, killed when the run is interrupted; `check: true` fails the run with
-     * `TOOL_FAILED` and the tail of its stderr when it exits non-zero.
+     * Runs a child process in `cwd` with `env`, killed when the run is interrupted; on Windows every
+     * process it started is killed too. A program not found fails the run with `TOOL_MISSING` (exit 2).
      */
     readonly spawn: ContextSpawn;
     /** Deadlines, `poll` and the grace period after an interrupt run on it. */
     readonly clock: Clock;
     /**
      * Calls `check` until it returns a value other than `undefined`, sleeping `intervalMs` between
-     * calls; it stops when `ctx.signal` or the given `signal` aborts.
+     * calls; it ends with the abort reason of `ctx.signal` or of the given `signal`.
      */
     poll<T>(check: () => T | undefined | Promise<T | undefined>, options: PollOptions): Promise<T>;
-    /** The Project file found by walking up from `cwd`, parsed by the CLI's schema. */
+    /**
+     * The Project file found by walking up from `cwd`, parsed by the CLI's schema, or `undefined`
+     * when there is none. A file the schema rejects fails the run with `PROJECT_INVALID` (exit 2)
+     * before the Command runs; the built-in Commands never read it.
+     */
     readonly project: Project<Settings> | undefined;
-    /** Reads `name` from the env, then from `$XDG_CONFIG_HOME/<cli>/.env`, with where it came from. */
+    /**
+     * Reads `name` from the env, then from `$XDG_CONFIG_HOME/<cli>/.env` (default `~/.config`), with
+     * where it came from; a `.env` it cannot read fails the run with `PERMISSION_DENIED`.
+     */
     secret(name: string): Secret | undefined;
+    /**
+     * The `.env` that `secret` reads: `$XDG_CONFIG_HOME/<cli>/.env`, or `~/.config/<cli>/.env`
+     * without it. Name it in a hint that asks for a missing key.
+     */
+    readonly envFile: string;
     /**
      * Classifies an errno failure of the CLI's own file access, such as a store it opens itself, as
      * `ctx.files` does; any other error comes back unchanged.
@@ -83,13 +116,17 @@ export interface Context<Ports = unknown, Settings = unknown> {
     readonly force: boolean;
     /**
      * The command line as the caller typed it, starting with the CLI's name and shell-quoted, with
-     * each flag in `remove` dropped along with its value and the words in `add` placed before any
-     * `--`; for the hint that names the command to run next.
+     * each flag in `remove` dropped along with its value (`--from 3` and `--from=3`, every time it was
+     * given) and the words in `add` placed before any `--`. Build every hint that names a command to
+     * run with it.
      */
     commandLine(change?: CommandLineChange): string;
 }
-/** The slice of `Context` the ports factory receives, which exists before the ports do. */
-export type PortsBase = Pick<Context, "env" | "cwd" | "packageRoot" | "secret" | "spawn" | "files" | "clock" | "signal" | "progress" | "version" | "build" | "self" | "fileError">;
+/**
+ * The slice of `Context` the ports factory receives, which exists before the ports do; a test that
+ * keeps the real factory gives it the test's env and fakes.
+ */
+export type PortsBase = Pick<Context, "env" | "cwd" | "packageRoot" | "secret" | "envFile" | "spawn" | "files" | "clock" | "signal" | "progress" | "version" | "build" | "self" | "fileError">;
 export interface Project<Settings = unknown> {
     /** The folder holding the Project file. */
     readonly root: string;

package/dist/define.d.ts

@@ -3,8 +3,11 @@ import type { BuildStamp, Context, PortsBase, ProjectFile } from "./context.js";
 import type { ErrorTable } from "./error-table.js";
 import { type StandardFlagName } from "./flags.js";
 import type { Page, PageInput, RowSchema } from "./list.js";
+import type { SideTaskRun } from "./side-task.js";
 import type { Style } from "./style.js";
+/** Shown in help and help JSON. */
 export interface Example {
+    /** A realistic full command line, starting with the CLI's name. */
     readonly command: string;
     readonly note: string;
 }
@@ -27,12 +30,15 @@ export interface RunDeadline<In> {
     readonly ms: number;
     /**
      * The command line that continues the work, given as the hint of the run's `DEADLINE_EXCEEDED`;
-     * `commandLine` is `ctx.commandLine`.
+     * `commandLine` is `ctx.commandLine`. Once the deadline passes, every error of the run becomes
+     * `DEADLINE_EXCEEDED`.
      */
     resume(input: In, commandLine: Context["commandLine"]): string;
 }
 interface CommandBase<Args extends InputSchema, Options extends InputSchema> {
+    /** The word the Command is listed under in `commands`; it labels the Command in errors and spill files. */
     readonly name: string;
+    /** One line, shown in help and help JSON. */
     readonly description: string;
     /** A paragraph printed after the options in text help, and carried as `help` in help JSON. */
     readonly help?: string;
@@ -41,48 +47,84 @@ interface CommandBase<Args extends InputSchema, Options extends InputSchema> {
     readonly hidden?: boolean;
     /**
      * Only a person at a terminal runs it: under a Coding agent the run fails with `NEEDS_OPERATOR`
-     * before `plan`, `run` or `start`, naming the line the operator types.
+     * (exit 2) before its input is read, stdin included, and the hint asks the operator to type the
+     * command line after `!`. `--json` alone does not make it refuse.
      */
     readonly operator?: true;
-    /** Missing ones fail the run with `TOOL_MISSING` before `plan`, `run` or `start`. */
+    /**
+     * Looked up before `plan`, `run` or `start`, `--dry-run` included: missing ones fail the run with
+     * `TOOL_MISSING` (exit 2), naming each with its `install`, and `doctor` checks each.
+     */
     readonly tools?: readonly Tool[];
+    /**
+     * Positional operands, in the schema's order; each field's `.describe()` is its help. The last
+     * field may be a `z.array(...)`, which takes every remaining operand, and one string field may be
+     * wrapped in `orStdin`. Input the schema rejects is a usage error (exit 1) before the Command runs.
+     */
     readonly args?: Args;
+    /**
+     * Flags, a camelCase key typed in kebab-case; each field's `.describe()` is its help. A
+     * `z.array(...)` option collects every occurrence of its flag in order, and a repeated scalar flag
+     * keeps its last value. Input the schema rejects is a usage error (exit 1) before the Command runs.
+     */
     readonly options?: Options;
     /** At `ms`, `ctx.signal` aborts and the run ends with `DEADLINE_EXCEEDED` (exit 75). */
     readonly deadline?: RunDeadline<Input<Args, Options>>;
 }
 interface UnpagedCommand<Args extends InputSchema, Options extends InputSchema> extends CommandBase<Args, Options> {
+    /** The schema of the data the Command prints, published as JSON Schema in help JSON. */
     readonly output?: z.ZodType;
     readonly rows?: never;
 }
 export interface ReadCommand<Args extends InputSchema, Options extends InputSchema, Data, Ports = unknown, Settings = unknown> extends UnpagedCommand<Args, Options> {
     readonly effect: "read";
     run(input: Input<Args, Options>, ctx: Context<Ports, Settings>): Data | Promise<Data>;
+    /**
+     * Turns the data into short text; `--json` prints the data itself. `style` colours only when a
+     * person watches a terminal or `FORCE_COLOR` is set.
+     */
     render(data: Data, style: Style): string;
 }
-/** A read Command whose data is a page of rows; the Runtime adds `--limit`, `--cursor` and `--fields`. */
+/**
+ * A read Command whose data is a page of rows, from `paginate` or `page`; the Runtime adds `--limit`
+ * (default 20), `--cursor` and `--fields`, and prints the page as `{ items, next? }`, `next` being
+ * the command line for the following page, and as text ends it with a line saying how many rows were
+ * shown and either that command line or that no pages remain. A page never spills, and `--fields` keeps only the named fields.
+ */
 export interface ListCommand<Args extends InputSchema, Options extends InputSchema, Row extends RowSchema, Ports = unknown, Settings = unknown> 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<Ports, Settings>): Page<z.output<Row>> | Promise<Page<z.output<Row>>>;
+    /** Receives the page; render `page.items`. */
     render(page: Page<z.output<Row>>, style: Style): string;
 }
-/** A Command that changes something: `plan` has no side effects, `apply` performs the Plan. */
+/**
+ * A Command that changes something: `plan` has no side effects, `apply` performs the Plan. The
+ * Runtime adds `--dry-run`, which prints the Plan and stops; between `plan` and `apply` it checks
+ * `outputs`, then `cost`, then `confirm`, each refusal's hint holding the command line plus its flag.
+ */
 interface PlannedCommand<Args extends InputSchema, Options extends InputSchema, Plan, Data, Ports, Settings> extends UnpagedCommand<Args, Options> {
     plan(input: Input<Args, Options>, ctx: Context<Ports, Settings>): Plan | Promise<Plan>;
     apply(plan: Plan, ctx: Context<Ports, Settings>): Data | Promise<Data>;
     render(data: Data, style: Style): string;
+    /**
+     * `--dry-run --json` prints the Plan itself, or `{ plan, outputs?, cost }` when the Command
+     * declares `outputs` or `cost`; a byte array in it prints as an index-keyed object.
+     */
     renderPlan(plan: Plan, style: Style): string;
     /**
      * A sentence stating what the Plan costs, or undefined when it is cheap. Declaring it adds
-     * `--yes`, which a run must pass whenever it returns a sentence.
+     * `--yes`; a run whose cost is a sentence and lacks it refuses with `NOT_CONFIRMED` (exit 2), and
+     * `--dry-run` prints `cost: <sentence>`.
      */
     cost?(plan: Plan): string | undefined;
     /**
      * The files the Plan writes, relative to `ctx.cwd`. Declaring it adds `--force`, without which
-     * a run refuses with `OUTPUT_EXISTS` when any of them exists.
+     * a run refuses with `OUTPUT_EXISTS` (exit 1) when any of them exists, and `--dry-run` lists them.
+     * Before `apply` the Runtime creates each one's folder and a temp file in it, so a sandbox denial
+     * fails with `PERMISSION_DENIED` first; without `--force` the first write to each is exclusive.
      */
     outputs?(plan: Plan): readonly string[];
     /**
@@ -96,10 +138,16 @@ export interface WriteCommand<Args extends InputSchema, Options extends InputSch
 }
 export interface DestructiveCommand<Args extends InputSchema, Options extends InputSchema, Plan, Data, Ports = unknown, Settings = unknown> extends PlannedCommand<Args, Options, Plan, Data, Ports, Settings> {
     readonly effect: "destructive";
-    /** The value the caller must repeat as `--confirm`, naming the target the Plan changes. */
+    /**
+     * The value the caller must repeat as `--confirm`, naming the target the Plan changes; without it
+     * the run refuses with exit 1.
+     */
     confirm(plan: Plan): string;
 }
-/** A Command that keeps running, such as a preview server, until Ctrl-C or SIGTERM stops it. */
+/**
+ * A Command that keeps running, such as a preview server, until Ctrl-C or SIGTERM stops it with
+ * exit 0. Of the Standard flags it gets only `--json`.
+ */
 export interface ServeCommand<Args extends InputSchema, Options extends InputSchema, Data, Ports = unknown, Settings = unknown> extends UnpagedCommand<Args, Options> {
     readonly effect: "serve";
     /** Starts the work and returns its data, which prints at once; stop the work on `ctx.signal`. */
@@ -113,6 +161,8 @@ export interface Commands<Ports = unknown, Settings = unknown> {
 interface CliBase<Ports, Settings> {
     readonly name: string;
     readonly version: string;
+    /** One line saying what the CLI does, shown under the first line of its help and in help JSON. */
+    readonly description: string;
     /** The commit the build was made from and when, stamped by the bundler; `--version` prints it. */
     readonly build?: BuildStamp;
     /** Every code the CLI throws; a code missing here exits 70, as a bug. */
@@ -124,6 +174,14 @@ interface CliBase<Ports, Settings> {
     readonly skill?: {
         readonly source: string;
     };
+    /**
+     * Work that runs beside every Command run, such as a usage count; return `undefined` to decline.
+     * It starts once the input is parsed, before `plan`, `run` or `start`, so it also runs for a run a
+     * guard refuses, and once the output is written the run waits for it at most `SIDE_TASK_WAIT_MS`.
+     * Nothing it throws changes stdout, stderr or the exit code; `<NAME>_DEBUG=1` prints it on stderr.
+     * It never runs for help, `--version`, a usage error or a built-in Command.
+     */
+    sideTask?(run: SideTaskRun<Ports>): Promise<void> | undefined;
 }
 /** Where an Agent CLI is published and how it is installed; `doctor` and `update` read it. */
 export interface GlobalInstall {

package/dist/define.js.map

@@ -1 +1 @@
-{"version":3,"file":"define.js","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAyB,MAAM,YAAY,CAAC;AACrF,OAAO,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAwS5F,SAAS,cAAc,CAA2B,OAAiB;IACjE,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,UAAU,CAAC,OAAO,CAAC,CAAC;IACpB,iBAAiB,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,gBAAgB,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9D,yBAAyB,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACzD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAA2B,gBAAgB,EAAE,CAAC;AAExE,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":"AAGA,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAyB,MAAM,YAAY,CAAC;AACrF,OAAO,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAkW5F,SAAS,cAAc,CAA2B,OAAiB;IACjE,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,UAAU,CAAC,OAAO,CAAC,CAAC;IACpB,iBAAiB,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,gBAAgB,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9D,yBAAyB,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACzD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAA2B,gBAAgB,EAAE,CAAC;AAExE,0FAA0F;AAC1F,MAAM,UAAU,SAAS,CAAC,IAAwB;IAChD,OAAO,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC;AACzC,CAAC"}

package/dist/error-table.d.ts

@@ -4,6 +4,7 @@ import type { ExitClass } from "./exit-classes.js";
 /** The Exit classes a CLI's own code can have; a bug or an interrupt is the Runtime's to tell. */
 export type DeclaredExitClass = Exclude<ExitClass, "bug" | "interrupted">;
 export interface ErrorDeclaration {
+    /** Who must act, which sets the exit code: `caller` 1, `operator` 2, `source` 3, `wait` 75. */
     readonly class: DeclaredExitClass;
     readonly details?: z.ZodType;
 }
@@ -29,6 +30,10 @@ export type CliErrorInit<Declaration extends ErrorDeclaration> = {
     readonly message: string;
     readonly hint: string;
 } & DetailsInit<Declaration> & RetryInit<Declaration>;
-/** A `CliError` for a code of `table`, whose `details` must match the code's schema. */
+/**
+ * A `CliError` for a code of `table`, whose `details` must match the code's schema. The `hint`
+ * names the next command to run and says whether running it again can help; `retryAt` (ISO 8601)
+ * is allowed only on a wait-class code.
+ */
 export declare function cliError<Table extends ErrorTable, Code extends keyof Table & string>(_table: Table, code: Code, init: CliErrorInit<Table[Code]>, options?: ErrorOptions): CliError;
 export {};

package/dist/error-table.js

@@ -3,7 +3,11 @@ import { CliError } from "./errors.js";
 export function defineErrors(table) {
     return table;
 }
-/** A `CliError` for a code of `table`, whose `details` must match the code's schema. */
+/**
+ * A `CliError` for a code of `table`, whose `details` must match the code's schema. The `hint`
+ * names the next command to run and says whether running it again can help; `retryAt` (ISO 8601)
+ * is allowed only on a wait-class code.
+ */
 export function cliError(_table, code, init, options) {
     return new CliError({ ...init, code }, options);
 }

package/dist/error-table.js.map

@@ -1 +1 @@
-{"version":3,"file":"error-table.js","sourceRoot":"","sources":["../src/error-table.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAcvC,oGAAoG;AACpG,MAAM,UAAU,YAAY,CAAiC,KAAY;IACvE,OAAO,KAAK,CAAC;AACf,CAAC;AAmBD,wFAAwF;AACxF,MAAM,UAAU,QAAQ,CACtB,MAAa,EACb,IAAU,EACV,IAA+B,EAC/B,OAAsB;IAEtB,OAAO,IAAI,QAAQ,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;AAClD,CAAC"}
+{"version":3,"file":"error-table.js","sourceRoot":"","sources":["../src/error-table.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAevC,oGAAoG;AACpG,MAAM,UAAU,YAAY,CAAiC,KAAY;IACvE,OAAO,KAAK,CAAC;AACf,CAAC;AAmBD;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CACtB,MAAa,EACb,IAAU,EACV,IAA+B,EAC/B,OAAsB;IAEtB,OAAO,IAAI,QAAQ,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;AAClD,CAAC"}

package/dist/errors.d.ts

@@ -27,6 +27,8 @@ export interface ErrorFormat {
     readonly json: boolean;
     readonly env: Env;
     readonly style: Style;
+    /** Where the CLI takes bug reports, read from package.json `bugs` only when a hint names it. */
+    readonly bugs?: () => string | undefined;
     /** Whether `error` is a bug: not a `CliError`, or one whose code nobody declared. */
     readonly isBug: (error: unknown) => boolean;
 }
@@ -35,6 +37,12 @@ export declare function isMissingFile(error: unknown): boolean;
 export declare function isNothingThere(error: unknown): boolean;
 export declare function debugVariable(cliName: string): string;
 export declare function messageOf(error: unknown): string;
-/** The errors a run failed with: each one an `AggregateError` holds, or the one it threw. */
+export declare function isDebug({ env, cliName }: Pick<ErrorFormat, "env" | "cliName">): boolean;
+export declare function causesOf(error: unknown): unknown[];
+export declare function traceOf(error: unknown): string;
+/**
+ * The errors a run failed with: the leaves of nested `AggregateError`s, or the one it threw. An
+ * empty `AggregateError` is a leaf.
+ */
 export declare function errorsOf(error: unknown): readonly unknown[];
 export declare function formatRuntimeError(error: unknown, format: ErrorFormat): string;

package/dist/errors.js

@@ -38,13 +38,17 @@ export function debugVariable(cliName) {
 export function messageOf(error) {
     return error instanceof Error ? error.message : String(error);
 }
-function isDebug({ env, cliName }) {
+export function isDebug({ env, cliName }) {
     return Boolean(env[debugVariable(cliName)]);
 }
 function bugHint(format) {
-    return isDebug(format)
-        ? "the stack trace shows where it failed"
-        : `rerun with ${debugVariable(format.cliName)}=1 to see the stack trace`;
+    const bugs = format.bugs?.();
+    if (isDebug(format)) {
+        const where = "the stack trace shows where it failed";
+        return bugs === undefined ? where : `${where}; report it at ${bugs}`;
+    }
+    const rerun = `rerun with ${debugVariable(format.cliName)}=1 to see the stack trace`;
+    return bugs === undefined ? rerun : `${rerun}, then report it at ${bugs}`;
 }
 function fieldsOf(error, format) {
     if (error instanceof CliError) {
@@ -53,12 +57,12 @@ function fieldsOf(error, format) {
     }
     return { code: INTERNAL_CODE, message: messageOf(error), hint: bugHint(format) };
 }
-function causesOf(error) {
+export function causesOf(error) {
     return error instanceof Error && error.cause !== undefined
         ? [error.cause, ...causesOf(error.cause)]
         : [];
 }
-function traceOf(error) {
+export function traceOf(error) {
     return error instanceof Error ? (error.stack ?? error.message) : String(error);
 }
 /** Under debug: a bug's stack trace, then every error's cause chain. */
@@ -71,9 +75,14 @@ function debugTrace(error, format) {
     ];
     return lines.length === 0 ? undefined : lines.join("\n");
 }
-/** The errors a run failed with: each one an `AggregateError` holds, or the one it threw. */
+/**
+ * The errors a run failed with: the leaves of nested `AggregateError`s, or the one it threw. An
+ * empty `AggregateError` is a leaf.
+ */
 export function errorsOf(error) {
-    return error instanceof AggregateError && error.errors.length > 0 ? error.errors : [error];
+    return error instanceof AggregateError && error.errors.length > 0
+        ? error.errors.flatMap(errorsOf)
+        : [error];
 }
 function errorLines(error, format) {
     const fields = fieldsOf(error, format);

package/dist/errors.js.map

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

package/dist/exit-classes.js

@@ -1,16 +1,17 @@
+import { DOCTOR_PROBLEMS } from "./built-ins/doctor.js";
+import { NOT_GLOBAL_INSTALL } from "./built-ins/global-install.js";
+import { INSTALL_FAILED, NO_LATEST, NPM_FAILED, REGISTRY_AUTH, REGISTRY_UNREACHABLE, } from "./built-ins/npm.js";
 import { CONFIRMATION_MISMATCH, CONFIRMATION_REQUIRED } from "./confirm.js";
 import { NOT_CONFIRMED } from "./cost.js";
-import { DOCTOR_PROBLEMS } from "./doctor.js";
 import { ALREADY_EXISTS, DISK_FULL, NOT_A_FILE, NOT_FOUND, PERMISSION_DENIED } from "./errno.js";
 import { CliError, errorsOf, INTERNAL_CODE, UsageError } from "./errors.js";
-import { NOT_GLOBAL_INSTALL } from "./global-install.js";
 import { DEADLINE_EXCEEDED, INTERRUPTED } from "./interrupts.js";
 import { UNKNOWN_FIELD } from "./list.js";
-import { INSTALL_FAILED, NO_LATEST, NPM_FAILED, REGISTRY_AUTH, REGISTRY_UNREACHABLE, } from "./npm.js";
 import { NEEDS_OPERATOR } from "./operator.js";
 import { OUTPUT_EXISTS } from "./outputs.js";
 import { PROJECT_INVALID } from "./project.js";
 import { TOOL_FAILED } from "./spawn.js";
+import { STDIN_STALLED } from "./stdin.js";
 import { TOOL_MISSING } from "./tools.js";
 import { INVALID_INPUT, UNKNOWN_COMMAND, UNKNOWN_OPTION } from "./usage.js";
 export const SIGNAL_EXIT_CODES = { SIGINT: 130, SIGTERM: 143 };
@@ -21,43 +22,39 @@ export const EXIT_CODES = {
     wait: 75,
     bug: 70,
 };
-// Built on call: the modules that throw these codes import this one back (through output.ts), so
-// their constants are not initialised yet while this module loads.
-/** The codes the Runtime and its built-in Commands raise, each with the class that must act on it. */
-function runtimeCodes() {
-    return {
-        [INVALID_INPUT]: "caller",
-        [UNKNOWN_OPTION]: "caller",
-        [UNKNOWN_COMMAND]: "caller",
-        [UNKNOWN_FIELD]: "caller",
-        [CONFIRMATION_REQUIRED]: "caller",
-        [CONFIRMATION_MISMATCH]: "caller",
-        [NOT_CONFIRMED]: "operator",
-        [NEEDS_OPERATOR]: "operator",
-        [OUTPUT_EXISTS]: "caller",
-        [INTERRUPTED]: "interrupted",
-        [DEADLINE_EXCEEDED]: "wait",
-        [INTERNAL_CODE]: "bug",
-        [PERMISSION_DENIED]: "operator",
-        [DISK_FULL]: "operator",
-        [NOT_FOUND]: "caller",
-        [ALREADY_EXISTS]: "caller",
-        [NOT_A_FILE]: "caller",
-        [TOOL_FAILED]: "operator",
-        [TOOL_MISSING]: "operator",
-        [PROJECT_INVALID]: "operator",
-        [DOCTOR_PROBLEMS]: "operator",
-        [NOT_GLOBAL_INSTALL]: "operator",
-        [REGISTRY_UNREACHABLE]: "operator",
-        [REGISTRY_AUTH]: "operator",
-        [INSTALL_FAILED]: "operator",
-        [NPM_FAILED]: "operator",
-        [NO_LATEST]: "source",
-    };
-}
+const RUNTIME_EXIT_CLASSES = {
+    [INVALID_INPUT]: "caller",
+    [UNKNOWN_OPTION]: "caller",
+    [UNKNOWN_COMMAND]: "caller",
+    [UNKNOWN_FIELD]: "caller",
+    [CONFIRMATION_REQUIRED]: "caller",
+    [CONFIRMATION_MISMATCH]: "caller",
+    [NOT_CONFIRMED]: "operator",
+    [NEEDS_OPERATOR]: "operator",
+    [OUTPUT_EXISTS]: "caller",
+    [STDIN_STALLED]: "caller",
+    [INTERRUPTED]: "interrupted",
+    [DEADLINE_EXCEEDED]: "wait",
+    [INTERNAL_CODE]: "bug",
+    [PERMISSION_DENIED]: "operator",
+    [DISK_FULL]: "operator",
+    [NOT_FOUND]: "caller",
+    [ALREADY_EXISTS]: "caller",
+    [NOT_A_FILE]: "caller",
+    [TOOL_FAILED]: "operator",
+    [TOOL_MISSING]: "operator",
+    [PROJECT_INVALID]: "operator",
+    [DOCTOR_PROBLEMS]: "operator",
+    [NOT_GLOBAL_INSTALL]: "operator",
+    [REGISTRY_UNREACHABLE]: "operator",
+    [REGISTRY_AUTH]: "operator",
+    [INSTALL_FAILED]: "operator",
+    [NPM_FAILED]: "operator",
+    [NO_LATEST]: "source",
+};
 /** The codes of `errors` that the Runtime already declares, which a CLI cannot redeclare. */
 export function runtimeCodesIn(errors) {
-    return Object.keys(errors).filter((code) => Object.hasOwn(runtimeCodes(), code));
+    return Object.keys(errors).filter((code) => Object.hasOwn(RUNTIME_EXIT_CLASSES, code));
 }
 // A code that neither the Runtime nor the CLI declares was thrown by mistake: a bug.
 function exitClassOfOne(error, errors) {
@@ -65,7 +62,7 @@ function exitClassOfOne(error, errors) {
         return "bug";
     if (error instanceof UsageError)
         return "caller";
-    return runtimeCodes()[error.code] ?? errors[error.code]?.class ?? "bug";
+    return RUNTIME_EXIT_CLASSES[error.code] ?? errors[error.code]?.class ?? "bug";
 }
 export function isBug(error, errors) {
     return exitClassOfOne(error, errors) === "bug";

package/dist/exit-classes.js.map

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

package/dist/files.d.ts

@@ -2,6 +2,8 @@ import type { FileError } from "./errno.js";
 export interface MkdirOptions {
     /** Fail with `ALREADY_EXISTS` when the folder itself exists. */
     readonly exclusive?: boolean;
+    /** The permission bits of each folder it creates, less the umask; an existing folder keeps its mode. */
+    readonly mode?: number;
 }
 export interface WriteOptions {
     /** Fail with `ALREADY_EXISTS` when anything exists at the path. */
@@ -21,16 +23,19 @@ export interface Files {
      * replacing write through a symlink replaces its target.
      */
     write(path: string, data: string | Uint8Array, options?: WriteOptions): Promise<void>;
-    /** Whether anything exists at the absolute `path`. */
+    /** Whether anything exists at the absolute `path`; false also for a path under a file. */
     exists(path: string): Promise<boolean>;
     read(path: string): Promise<Uint8Array>;
-    /** The names in the absolute `folder`. */
+    /** The names in the absolute `folder`, sorted. */
     list(folder: string): Promise<string[]>;
     /** Removes a file, or a folder and everything in it; a missing `path` is a success. */
     remove(path: string): Promise<void>;
     /** Creates the folder and its missing parents; an existing folder is a success unless `exclusive`. */
     mkdir(path: string, options?: MkdirOptions): Promise<void>;
-    /** The file at the absolute `path`, or `undefined` when nothing is there or a part of it is a file. */
+    /**
+     * The file at the absolute `path`, or `undefined` when nothing is there or a part of it is a file.
+     * Two paths are one file when their `id`s match, which a link or a case-insensitive disk hides.
+     */
     stat(path: string): Promise<FileStat | undefined>;
 }
 /** Where the Runtime writes `path` before moving it into place; a dead writer's is swept. */