@duyquangnvx/agent-cli 0.26.0 → 0.28.0

package/dist/run-scope.js

@@ -0,0 +1,138 @@
+import { poll, realClock } from "./clock.js";
+import { changedArgv } from "./command-line/invocation.js";
+import { knownFlags, stdinArgOf } from "./command-line/parse-input.js";
+import { fileErrorOf } from "./context/errno.js";
+import { realFiles } from "./context/files.js";
+import { outputsOf } from "./context/outputs.js";
+import { envFileOf, isNeeded, secretOf } from "./context/secrets.js";
+import { contextSpawn, contextSpawnDetached, realSpawn, realSpawnDetached, } from "./context/spawn.js";
+import { cliErrorOf } from "./error-table.js";
+import { noticeLine, progressLine } from "./output.js";
+import { packageRootOf } from "./package-root.js";
+import { buildStamp } from "./version.js";
+function selfOf(name, bin) {
+    return bin === undefined ? [name] : [process.execPath, ...process.execArgv, bin];
+}
+const unfakedSpawnDetached = async () => {
+    throw new Error("runCli was given a fake spawn but no spawnDetached: pass spawnDetached to runCli, so the test starts no real child");
+};
+// A test that fakes `spawn` expects no real child, detached ones included.
+function spawnDetachedOf({ spawn, spawnDetached }) {
+    if (spawnDetached !== undefined)
+        return spawnDetached;
+    return spawn === undefined ? realSpawnDetached : unfakedSpawnDetached;
+}
+function portsOf(cli, replacement) {
+    if (replacement !== undefined)
+        return () => replacement;
+    return cli.ports ?? (() => ({}));
+}
+export function runScopeOf(cli, routed, settings, write, baseInvocation) {
+    const { cwd, env } = settings;
+    const clock = settings.clock ?? realClock;
+    const platform = settings.platform ?? process.platform;
+    const invocation = {
+        ...baseInvocation,
+        flags: knownFlags(routed.spec),
+        stdinArg: stdinArgOf(routed),
+    };
+    const rerun = (change) => ({
+        kind: "rerun",
+        words: changedArgv(invocation, change),
+        stdinArg: invocation.stdinArg,
+    });
+    const fileError = fileErrorOf({
+        rerun: rerun(),
+        env,
+        platform,
+    });
+    const outputs = outputsOf(settings.files ?? realFiles(), { cwd, fileError });
+    const packageRoot = packageRootOf(settings.bin, cwd);
+    const progress = (message) => write.stderr(progressLine(message, routed.json));
+    const envFile = envFileOf(cli.name, env);
+    const spawning = { fileError, rerun: rerun() };
+    return {
+        invocation,
+        rerun,
+        fileError,
+        clock,
+        platform,
+        outputs,
+        progress,
+        notice: (text) => write.stderr(noticeLine(text, routed.json)),
+        packageRoot,
+        ports: portsOf(cli, settings.ports),
+        portsBase: (signal) => ({
+            cwd,
+            env,
+            platform,
+            packageRoot,
+            progress,
+            secret: (name) => secretOf({ envFile, env, fileError }, name),
+            envFile,
+            fileError,
+            version: cli.version,
+            build: buildStamp(),
+            self: selfOf(cli.name, settings.bin),
+            signal,
+            clock,
+            files: outputs.files,
+            spawn: contextSpawn(settings.spawn ?? realSpawn, { cwd, env, signal }, spawning),
+            spawnDetached: contextSpawnDetached(spawnDetachedOf(settings), { cwd, env, signal }, spawning),
+        }),
+    };
+}
+export function contextOf(scope, control, { command, flags, project, deliver }) {
+    const portsBase = scope.portsBase(control.signal);
+    const ports = once(() => scope.ports(portsBase));
+    // The only Secrets `ctx.secret` reads.
+    const declared = new Map((command.secrets ?? []).map((declaration) => [declaration.name, declaration]));
+    function secret(name) {
+        const declaration = declared.get(name);
+        // Only a cast reaches an undeclared name, and only a `.env` edited mid-run a missing value.
+        if (declaration === undefined) {
+            throw new Error(`ctx.secret("${name}") names a Secret the Command does not declare`);
+        }
+        const found = portsBase.secret(name);
+        if (found === undefined && isNeeded(declaration)) {
+            throw new Error(`ctx.secret("${name}") found no value`);
+        }
+        return found;
+    }
+    return {
+        ...portsBase,
+        secret,
+        fail: cliErrorOf,
+        deadline: (ms, options) => control.deadline(ms, options),
+        runToEnd: (name, work) => control.runToEnd(name, work),
+        // Built on first read, so a factory that throws fails only what needs the ports, never `doctor`.
+        get ports() {
+            return ports();
+        },
+        project,
+        force: flags.force,
+        dryRun: flags.dryRun,
+        rerun: scope.rerun,
+        poll: (check, { intervalMs, signal: stop }) => poll(portsBase.clock, check, intervalMs, stop === undefined ? control.signal : AbortSignal.any([control.signal, stop])),
+        deliver,
+        notice: scope.notice,
+    };
+}
+/** `build` runs on the first call; later calls give its value or throw its error again. */
+export function once(build) {
+    let outcome;
+    return () => {
+        if (outcome === undefined) {
+            try {
+                outcome = { ok: true, value: build() };
+            }
+            catch (error) {
+                outcome = { ok: false, error };
+            }
+        }
+        if (outcome.ok)
+            return outcome.value;
+        throw outcome.error;
+    };
+}
+//# sourceMappingURL=run-scope.js.map

package/dist/run-scope.js.map

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

package/dist/runtime-codes.d.ts

@@ -1,3 +1,138 @@
+import type { ErrorTable } from "./error-table.js";
+import type { ExitClass } from "./exit-classes.js";
+export declare const DOCTOR_PROBLEMS = "DOCTOR_PROBLEMS";
+export declare const NOT_GLOBAL_INSTALL = "NOT_GLOBAL_INSTALL";
+export declare const NOT_ON_PATH = "NOT_ON_PATH";
+export declare const REGISTRY_UNREACHABLE = "REGISTRY_UNREACHABLE";
+export declare const REGISTRY_AUTH = "REGISTRY_AUTH";
+export declare const INSTALL_FAILED = "INSTALL_FAILED";
+export declare const NPM_FAILED = "NPM_FAILED";
+export declare const NO_LATEST = "NO_LATEST";
+/**
+ * The Runtime codes only some Commands reach: each Command that throws one, Built-in or the CLI's
+ * own, declares it in `errors`, as it does a code of the CLI's Error table.
+ */
+export declare const declaredRuntimeErrors: {
+    readonly DOCTOR_PROBLEMS: {
+        readonly class: "operator";
+    };
+    readonly NOT_GLOBAL_INSTALL: {
+        readonly class: "operator";
+    };
+    readonly NOT_ON_PATH: {
+        readonly class: "operator";
+    };
+    readonly REGISTRY_UNREACHABLE: {
+        readonly class: "operator";
+    };
+    readonly REGISTRY_AUTH: {
+        readonly class: "operator";
+    };
+    readonly INSTALL_FAILED: {
+        readonly class: "operator";
+    };
+    readonly NPM_FAILED: {
+        readonly class: "operator";
+    };
+    readonly NO_LATEST: {
+        readonly class: "source";
+    };
+};
+/** The Runtime's own Error table: every code it fails a run with, and the class that must act. */
+export declare const runtimeErrors: {
+    readonly INVALID_INPUT: {
+        readonly class: "caller";
+    };
+    readonly UNKNOWN_OPTION: {
+        readonly class: "caller";
+    };
+    readonly UNKNOWN_COMMAND: {
+        readonly class: "caller";
+    };
+    readonly UNKNOWN_FIELD: {
+        readonly class: "caller";
+    };
+    readonly CONFIRMATION_REQUIRED: {
+        readonly class: "caller";
+    };
+    readonly CONFIRMATION_MISMATCH: {
+        readonly class: "caller";
+    };
+    readonly NOT_CONFIRMED: {
+        readonly class: "operator";
+    };
+    readonly NEEDS_OPERATOR: {
+        readonly class: "operator";
+    };
+    readonly OUTPUT_EXISTS: {
+        readonly class: "caller";
+    };
+    readonly STDIN_STALLED: {
+        readonly class: "caller";
+    };
+    readonly INTERRUPTED: {
+        readonly class: "interrupted";
+    };
+    readonly DEADLINE_EXCEEDED: {
+        readonly class: "wait";
+    };
+    readonly INTERNAL: {
+        readonly class: "bug";
+    };
+    readonly PERMISSION_DENIED: {
+        readonly class: "operator";
+    };
+    readonly DISK_FULL: {
+        readonly class: "operator";
+    };
+    readonly NOT_FOUND: {
+        readonly class: "caller";
+    };
+    readonly ALREADY_EXISTS: {
+        readonly class: "caller";
+    };
+    readonly NOT_A_FILE: {
+        readonly class: "caller";
+    };
+    readonly TOOL_FAILED: {
+        readonly class: "operator";
+    };
+    readonly TOOL_MISSING: {
+        readonly class: "operator";
+    };
+    readonly SECRET_MISSING: {
+        readonly class: "operator";
+    };
+    readonly PROJECT_INVALID: {
+        readonly class: "operator";
+    };
+    readonly DOCTOR_PROBLEMS: {
+        readonly class: "operator";
+    };
+    readonly NOT_GLOBAL_INSTALL: {
+        readonly class: "operator";
+    };
+    readonly NOT_ON_PATH: {
+        readonly class: "operator";
+    };
+    readonly REGISTRY_UNREACHABLE: {
+        readonly class: "operator";
+    };
+    readonly REGISTRY_AUTH: {
+        readonly class: "operator";
+    };
+    readonly INSTALL_FAILED: {
+        readonly class: "operator";
+    };
+    readonly NPM_FAILED: {
+        readonly class: "operator";
+    };
+    readonly NO_LATEST: {
+        readonly class: "source";
+    };
+};
+export type RuntimeCode = keyof typeof runtimeErrors;
+export type DeclaredRuntimeErrors = typeof declaredRuntimeErrors;
 /** Every code the Runtime fails a run with, keyed by itself, to catch or assert one. */
 export declare const runtimeCodes: {
     readonly INVALID_INPUT: "INVALID_INPUT";
@@ -31,4 +166,8 @@ export declare const runtimeCodes: {
     readonly NPM_FAILED: "NPM_FAILED";
     readonly NO_LATEST: "NO_LATEST";
 };
-export type RuntimeCode = (typeof runtimeCodes)[keyof typeof runtimeCodes];
+export declare const anyCommandClasses: readonly ExitClass[];
+export declare function isRuntimeCode(code: string): code is RuntimeCode;
+export declare function isDeclaredRuntimeCode(code: string): code is keyof DeclaredRuntimeErrors;
+/** Whether a Command or `doctor` row throwing `code` must declare it: a code of `table`, or a Runtime one only some reach. */
+export declare function mustDeclare(code: string, table: ErrorTable): boolean;

package/dist/runtime-codes.js

@@ -1,7 +1,3 @@
-import { DOCTOR_PROBLEMS } from "./built-ins/doctor.js";
-import { NOT_GLOBAL_INSTALL } from "./built-ins/install/global-npm.js";
-import { INSTALL_FAILED, NO_LATEST, NPM_FAILED, REGISTRY_AUTH, REGISTRY_UNREACHABLE, } from "./built-ins/npm.js";
-import { NOT_ON_PATH } from "./built-ins/setup.js";
 import { INVALID_INPUT, UNKNOWN_COMMAND, UNKNOWN_OPTION } from "./command-line/usage.js";
 import { CONFIRMATION_MISMATCH, CONFIRMATION_REQUIRED } from "./context/confirm.js";
 import { NOT_CONFIRMED } from "./context/cost.js";
@@ -16,6 +12,55 @@ import { STDIN_STALLED } from "./context/stdin.js";
 import { TOOL_MISSING } from "./context/tools.js";
 import { INTERNAL } from "./errors.js";
 import { UNKNOWN_FIELD } from "./list.js";
+export const DOCTOR_PROBLEMS = "DOCTOR_PROBLEMS";
+export const NOT_GLOBAL_INSTALL = "NOT_GLOBAL_INSTALL";
+export const NOT_ON_PATH = "NOT_ON_PATH";
+export const REGISTRY_UNREACHABLE = "REGISTRY_UNREACHABLE";
+export const REGISTRY_AUTH = "REGISTRY_AUTH";
+export const INSTALL_FAILED = "INSTALL_FAILED";
+export const NPM_FAILED = "NPM_FAILED";
+export const NO_LATEST = "NO_LATEST";
+/** The Runtime codes any Command can meet, which no Command declares. */
+const anyCommandErrors = {
+    [INVALID_INPUT]: { class: "caller" },
+    [UNKNOWN_OPTION]: { class: "caller" },
+    [UNKNOWN_COMMAND]: { class: "caller" },
+    [UNKNOWN_FIELD]: { class: "caller" },
+    [CONFIRMATION_REQUIRED]: { class: "caller" },
+    [CONFIRMATION_MISMATCH]: { class: "caller" },
+    [NOT_CONFIRMED]: { class: "operator" },
+    [NEEDS_OPERATOR]: { class: "operator" },
+    [OUTPUT_EXISTS]: { class: "caller" },
+    [STDIN_STALLED]: { class: "caller" },
+    [INTERRUPTED]: { class: "interrupted" },
+    [DEADLINE_EXCEEDED]: { class: "wait" },
+    [INTERNAL]: { class: "bug" },
+    [PERMISSION_DENIED]: { class: "operator" },
+    [DISK_FULL]: { class: "operator" },
+    [NOT_FOUND]: { class: "caller" },
+    [ALREADY_EXISTS]: { class: "caller" },
+    [NOT_A_FILE]: { class: "caller" },
+    [TOOL_FAILED]: { class: "operator" },
+    [TOOL_MISSING]: { class: "operator" },
+    [SECRET_MISSING]: { class: "operator" },
+    [PROJECT_INVALID]: { class: "operator" },
+};
+/**
+ * The Runtime codes only some Commands reach: each Command that throws one, Built-in or the CLI's
+ * own, declares it in `errors`, as it does a code of the CLI's Error table.
+ */
+export const declaredRuntimeErrors = {
+    [DOCTOR_PROBLEMS]: { class: "operator" },
+    [NOT_GLOBAL_INSTALL]: { class: "operator" },
+    [NOT_ON_PATH]: { class: "operator" },
+    [REGISTRY_UNREACHABLE]: { class: "operator" },
+    [REGISTRY_AUTH]: { class: "operator" },
+    [INSTALL_FAILED]: { class: "operator" },
+    [NPM_FAILED]: { class: "operator" },
+    [NO_LATEST]: { class: "source" },
+};
+/** The Runtime's own Error table: every code it fails a run with, and the class that must act. */
+export const runtimeErrors = { ...anyCommandErrors, ...declaredRuntimeErrors };
 /** Every code the Runtime fails a run with, keyed by itself, to catch or assert one. */
 export const runtimeCodes = {
     INVALID_INPUT,
@@ -49,4 +94,15 @@ export const runtimeCodes = {
     NPM_FAILED,
     NO_LATEST,
 };
+export const anyCommandClasses = Object.values(anyCommandErrors).map((declaration) => declaration.class);
+export function isRuntimeCode(code) {
+    return Object.hasOwn(runtimeErrors, code);
+}
+export function isDeclaredRuntimeCode(code) {
+    return Object.hasOwn(declaredRuntimeErrors, code);
+}
+/** Whether a Command or `doctor` row throwing `code` must declare it: a code of `table`, or a Runtime one only some reach. */
+export function mustDeclare(code, table) {
+    return Object.hasOwn(table, code) || isDeclaredRuntimeCode(code);
+}
 //# sourceMappingURL=runtime-codes.js.map

package/dist/runtime-codes.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-codes.js","sourceRoot":"","sources":["../src/runtime-codes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AACvE,OAAO,EACL,cAAc,EACd,SAAS,EACT,UAAU,EACV,aAAa,EACb,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzF,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACpF,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EACL,cAAc,EACd,SAAS,EACT,UAAU,EACV,SAAS,EACT,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE1C,wFAAwF;AACxF,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,aAAa;IACb,cAAc;IACd,eAAe;IACf,aAAa;IACb,qBAAqB;IACrB,qBAAqB;IACrB,aAAa;IACb,cAAc;IACd,aAAa;IACb,aAAa;IACb,WAAW;IACX,iBAAiB;IACjB,QAAQ;IACR,iBAAiB;IACjB,SAAS;IACT,SAAS;IACT,cAAc;IACd,UAAU;IACV,WAAW;IACX,YAAY;IACZ,cAAc;IACd,eAAe;IACf,eAAe;IACf,kBAAkB;IAClB,WAAW;IACX,oBAAoB;IACpB,aAAa;IACb,cAAc;IACd,UAAU;IACV,SAAS;CACD,CAAC"}
+{"version":3,"file":"runtime-codes.js","sourceRoot":"","sources":["../src/runtime-codes.ts"],"names":[],"mappings":"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"}

package/docs/README.md

@@ -30,7 +30,7 @@ Read [Principles](principles.md) once, then the guide for the task at hand. Ever
 ## A Command is done when
 
 - Every Error table code it throws, its helpers' and ports' included, is in its `errors`, and it throws its own through `ctx.fail`.
-- Every key it reads is in its `secrets`, whose `get` says where to obtain it.
+- Every key it reads is in its `secrets`, whose `get` says where to obtain it; one it can run without, such as a token that overrides a saved login, is `optional: true`.
 - Each line to run next is a Next step in `next`, never in the hint's prose; a rerun of the caller's own line comes from `ctx.rerun()`; the hint says whether running them is safe, and a step only the operator can take says so.
 - It declares `output` or `rows`.
 - It has `examples` with realistic full command lines starting with the CLI's name, which `checkExamples(cli)` passes.
@@ -40,7 +40,7 @@ Read [Principles](principles.md) once, then the guide for the task at hand. Ever
 - Its tests, through `runCli`, cover:
   - the success output, in text and under `--json`;
   - each `CliError` code;
-  - for a Command with `secrets`, `SECRET_MISSING` before any work;
+  - for a Command with `secrets` it needs, `SECRET_MISSING` before any work; for an optional one, a run with it unset;
   - for a write or destructive Command, that `--dry-run` and each refused guard change nothing;
   - for a write Command, that it is idempotent: a second run after a success changes nothing;
   - cancellation by passing `signal` to `runCli`, aborted once with the reason `"SIGTERM"` for 143;

package/docs/example/cli.test.ts

@@ -241,8 +241,8 @@ describe("links check", () => {
 });
 
 describe("links doctor", () => {
-  async function doctor(env: Record<string, string>, config?: unknown) {
-    const cwd = await folderWith(LINKS);
+  async function doctor(env: Record<string, string>, config?: unknown, links: unknown = LINKS) {
+    const cwd = await folderWith(links);
     if (config !== undefined) {
       await writeFile(join(cwd, "links.config.json"), JSON.stringify(config));
     }
@@ -268,6 +268,13 @@ describe("links doctor", () => {
     });
   });
 
+  test("a corrupt links.json fails doctor in the store row as CORRUPT_DATA, exit 1", async () => {
+    const { result, row } = await doctor({ PATH: await pathWith("git") }, undefined, "not links");
+
+    expect(row("store")).toMatchObject({ state: "problem", code: "CORRUPT_DATA" });
+    expect(result.exitCode).toBe(1);
+  });
+
   test("the tag row reads the Project file's tag", async () => {
     const { row } = await doctor({ PATH: await pathWith("git") }, { tag: "work" });
 

package/docs/example/cli.ts

@@ -148,6 +148,7 @@ const check = defineCommand({
 
 const store: DoctorCheck<Ports, Settings> = {
   name: "store",
+  errors: ["CORRUPT_DATA"],
   run: async (ctx) => {
     const links = await readLinks(ctx);
     return { state: "ok", message: `${linksPath(ctx.cwd)} holds ${links.length} links` };

package/docs/example/folder.ts

@@ -39,6 +39,7 @@ export function fakeFiles(overrides: Partial<Files>): Files {
     remove: async () => {},
     mkdir: async () => {},
     stat: async () => undefined,
+    realPath: async () => undefined,
     ...overrides,
   };
 }

package/docs/guides/commands.md

@@ -26,9 +26,9 @@ Data over 30,000 characters spills to a file, so make a list that may grow a Lis
 
 Reach the outside through `ctx`, so tests control it:
 
-- the working directory and environment as `ctx.cwd` and `ctx.env`;
+- the working directory, environment and platform as `ctx.cwd`, `ctx.env` and `ctx.platform`, which `runCli`'s `platform` replaces in a test;
 - the file system through `ctx.files`, whose failures name the path; a `node:fs` failure is a bug (exit 70). Pass `mode` to its `write` or `mkdir` for a file or folder holding tokens. Catch a file code from `runtimeCodes` to say what to do instead, as [`example/bundle.ts`](../example/bundle.ts) turns `ALREADY_EXISTS` into its own `BUNDLE_EXISTS`;
-- a key or token through `ctx.secret(name)`, for a name in the Command's `secrets`. The Runtime reads each declared Secret from the environment, then the CLI's `.env` at `ctx.envFile` (`~/.config/<name>/.env`, or under `$XDG_CONFIG_HOME`), an empty value counting as unset, and fails the run with `SECRET_MISSING` before any work, `--dry-run` included, when one is unset; so `ctx.secret` returns a `Secret`, never `undefined`. Messages name its `origin` and keep its `value` out of the agent's context. `doctor` reports every declared Secret; a key it should check that no Command requires goes in `defineCli({ secrets })`;
+- a key or token through `ctx.secret(name)`, for a name in the Command's `secrets`. The Runtime reads each declared Secret from the environment, then the CLI's `.env` at `ctx.envFile` (`~/.config/<name>/.env`, or under `$XDG_CONFIG_HOME`), an empty value counting as unset, and fails the run with `SECRET_MISSING` before any work, `--dry-run` included, when one is unset; so `ctx.secret` returns a `Secret`, never `undefined`. The exception is a key that only replaces something the CLI already has, such as a token that overrides a saved login: declared `optional: true`, its absence fails nothing and `ctx.secret` may give `undefined`, while help still names it, so an agent learns the key exists. Messages name its `origin` and keep its `value` out of the agent's context. `doctor` reports every declared Secret it needs, and each optional one that is set; a key it should check that no Command requires goes in `defineCli({ secrets })`;
 - a program through `ctx.spawn`, listed in the Command's `tools`, so a missing one fails before any work and `doctor` checks it. Its `stdin` option feeds the program, from an async iterable for input too large to hold, and its `onLine` option receives each line the program writes as it comes;
 - `ctx.progress` while a long step runs, since a Coding agent may kill a CLI that stays silent;
 - `ctx.notice` for something the caller should know beside the data, such as that a copy it relies on is behind. A fact the next step acts on belongs in the data instead.

package/docs/guides/doctor.md

@@ -5,6 +5,7 @@ Every multi-Command CLI has a built-in `doctor` that reports one row per check:
 ```ts
 const store: DoctorCheck<Ports, Settings> = {
   name: "store",
+  errors: ["CORRUPT_DATA"],
   run: async (ctx) => {
     const links = await readLinks(ctx);
     return { state: "ok", message: `${linksPath(ctx.cwd)} holds ${links.length} links` };
@@ -36,9 +37,9 @@ A row returns one of:
 - `{ state: "problem", message, fix?, code? }`, where `fix` is the command that fixes the problem, which `doctor` gives as a Next step before its own rerun, and `code` is one of the Error table's or the Runtime's;
 - `{ state: "skipped", message }` for a row not checked, such as "not checked: the bridge is down", so one cause shows up as one problem. It never fails `doctor`.
 
-When any row is a problem, `doctor` fails with one error per problem row, its `code` or `DOCTOR_PROBLEMS` (exit 2) without one, so it exits by the class that must act first as any Command does: an expired session 3, a network failure 75. Give a problem the code of its real cause. A row that throws becomes its own problem, with a `CliError`'s message and hint as the message, its first Next step other than `ctx.rerun()` as `fix`, and its code as `code`; the failure ends with `doctor` as typed, which a rerun in the row's hint means. A row whose `ctx.spawn` finds no declared tool on `PATH` is `skipped`, since that tool's row reports it. Each row runs under its own deadline, 10 s unless it sets `deadlineMs`, and `ctx.signal` aborts at that deadline, so pass it on. A row with `advisory: true` shows its problem and `fix` but never fails `doctor`; when it has no `fix`, `next` ends with `doctor` as typed.
+When any row is a problem, `doctor` fails with one error per problem row, its `code` or `DOCTOR_PROBLEMS` (exit 2) without one, so it exits by the class that must act first as any Command does: an expired session 3, a network failure 75. Give a problem the code of its real cause, and list in the row's `errors` each code of the Error table, and each Runtime code only some Commands reach, that it fails with, thrown or returned, as a Command does: the `store` row above declares `CORRUPT_DATA`, which `readLinks` throws. A row failing with a code it does not declare fails `doctor` as a bug (exit 70), even when another row declares it. `doctor`'s own `errors`, which `--help --json` lists, are `DOCTOR_PROBLEMS` and the codes of every row that is not advisory. A row that throws becomes its own problem, with a `CliError`'s message and hint as the message, its first Next step other than `ctx.rerun()` as `fix`, and its code as `code`; the failure ends with `doctor` as typed, which a rerun in the row's hint means. A row whose `ctx.spawn` finds no declared tool on `PATH` is `skipped`, since that tool's row reports it. Each row runs under its own deadline, 10 s unless it sets `deadlineMs`, and `ctx.signal` aborts at that deadline, so pass it on. A row with `advisory: true` shows its problem and `fix` but never fails `doctor`; when it has no `fix`, `next` ends with `doctor` as typed.
 
-The Runtime's `secrets` row checks every Secret the CLI and its Commands declare, naming where each came from and never its value, so no row of yours reads a key.
+The Runtime's `secrets` row checks every Secret the CLI and its Commands declare, naming where each came from and never its value, so no row of yours reads a key. An optional Secret appears only when set, unless some Command or the CLI needs the same name.
 
 The `install` and `registry` rows follow `defineCli({ install })`, and are `skipped` without it. Both are advisory: a project may stay on an older release on purpose.
 

package/docs/guides/errors.md

@@ -21,7 +21,7 @@ export const errors = defineErrors({
 
 When a `details` field is worth reading in text mode too, such as a stack, name it in the code's `print` rather than repeating it in the message, which `--json` would then carry twice.
 
-Each Command lists in `errors` the table codes it throws, its helpers' and ports' included, so a shared store's `CORRUPT_DATA` goes on every Command that reads the store. A run ending in a table code its Command does not declare, directly or as an `AggregateError` leaf, fails as a bug (exit 70) naming the code and the Command, so the Command's tests catch a missing one; `defineCli` throws on a code the table lacks. Runtime codes are never listed.
+Each Command lists in `errors` the table codes it throws, its helpers' and ports' included, so a shared store's `CORRUPT_DATA` goes on every Command that reads the store. A run ending in a table code its Command does not declare, directly or as an `AggregateError` leaf, fails as a bug (exit 70) naming the code and the Command, so the Command's tests catch a missing one; `defineCli` throws on a code the table lacks. A Runtime code any Command can meet, such as `NOT_FOUND` or `TOOL_MISSING`, is never listed; one only some Commands reach (`NOT_GLOBAL_INSTALL`, `NOT_ON_PATH`, `REGISTRY_UNREACHABLE`, `REGISTRY_AUTH`, `INSTALL_FAILED`, `NPM_FAILED`, `NO_LATEST`, `DOCTOR_PROBLEMS`) is declared like a table code by each Command that throws it, the Built-in Commands included. A `doctor` row declares its codes in its own `errors` ([`doctor` rows](doctor.md)). `--help` lists only the exit codes some Command can end in, so exit 3 shows only when a code of class `source` is declared.
 
 Inside a Command, throw `ctx.fail(code, init, options?)`, typed to the Command's `errors` and each code's `details`, so an undeclared code is a type error. A helper outside a Command, such as [`example/store.ts`](../example/store.ts), throws through the `cliError` that `agentCli` returns, typed by the whole table.
 

package/docs/guides/testing.md

@@ -17,7 +17,7 @@ test("--dry-run prints the Plan and saves nothing", async () => {
 
 The scaffolded `test/global-setup.ts` points `TMPDIR` at one root that it removes after the run, so these folders leave nothing behind; a CLI without it should add one.
 
-One test checks every example, the Built-in Commands' included: `checkExamples(cli)` from `@duyquangnvx/agent-cli/testing` throws one error listing each example that does not tokenize, route to a Command or pass its schemas. The scaffolded test calls it already.
+One test checks every example, the Built-in Commands' included: `checkExamples(cli)` from `@duyquangnvx/agent-cli/testing` throws one error listing each example that does not tokenize, route to a Command or pass its schemas. The scaffolded test calls it already. Under `runCli`, a failure's Next steps face the same check: a Next step that would not run as given, such as one missing a required option or holding a placeholder like `<id>` for a number, fails the run as a bug (exit 70) naming it and why.
 
 Under `--json`, stderr is JSON Lines: one `{"progress":"..."}` per progress line, then `{ errors: [{ code, message, hint, next?, details?, retryAt? }] }` as the last line, even for one error. Assert a failure's code through `runtimeCodes`, so a misspelt code fails type checking:
 
@@ -63,6 +63,7 @@ A Command that awaits native threads, such as sharp's, runs work the clock canno
 - `spawnDetached`: replace it to answer for a detached child, such as a Daemon: return `{ pid }`. A test that fakes `spawn` but not `spawnDetached` fails as a bug when the Command starts one, rather than start a real child.
 - `tools`: put a folder holding an empty executable of that name on the test's `PATH`.
 - `stdin`: pass the text an `orStdin` arg reads as `runCli`'s `stdin` option.
+- `platform`: pass `"win32"` to run the Runtime's Windows branches on any OS, where it would read `process.platform`: hint wording, a declared tool found on `PATH` by its `PATHEXT` extension, such as an executable `ffmpeg.CMD`, and the npm file (`npm.cmd`), bin folder and global `node_modules` folder the Built-in Commands use. Starting a real child and retrying a real file rename still follow the host.
 
 ## What the Runtime already tests
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duyquangnvx/agent-cli",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Runtime for agent-first command-line tools: owns parsing, output, errors and exit codes.",
   "type": "module",
   "engines": {

package/dist/command-errors.d.ts

@@ -1,8 +0,0 @@
-import { type CommandSpec } from "./command-spec.js";
-import type { Cli } from "./define.js";
-/**
- * `error`, or a bug naming each Error table code in it that the Command does not declare in its
- * `errors`. Runtime codes are never in the table, and a built-in's failures, `doctor` rows'
- * included, belong to no declaration, so both pass.
- */
-export declare function checkedCodes(error: unknown, { command, path, builtIn }: CommandSpec, cli: Pick<Cli, "name" | "errors">): unknown;

package/dist/command-errors.js

@@ -1,25 +0,0 @@
-import { commandLabel } from "./command-spec.js";
-import { errorTableOf } from "./error-table.js";
-import { CliError, errorsOf } from "./errors.js";
-/**
- * `error`, or a bug naming each Error table code in it that the Command does not declare in its
- * `errors`. Runtime codes are never in the table, and a built-in's failures, `doctor` rows'
- * included, belong to no declaration, so both pass.
- */
-export function checkedCodes(error, { command, path, builtIn }, cli) {
-    if (builtIn)
-        return error;
-    const table = errorTableOf(cli);
-    const declared = new Set(command.errors ?? []);
-    const undeclared = errorsOf(error).flatMap((leaf) => leaf instanceof CliError && Object.hasOwn(table, leaf.code) && !declared.has(leaf.code)
-        ? [leaf.code]
-        : []);
-    if (undeclared.length === 0)
-        return error;
-    const label = commandLabel(path, cli.name).join(" ");
-    const codes = [...new Set(undeclared)].join(", ");
-    return new Error(`\`${label}\` threw ${codes}, which its errors do not declare`, {
-        cause: error,
-    });
-}
-//# sourceMappingURL=command-errors.js.map

package/dist/command-errors.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"command-errors.js","sourceRoot":"","sources":["../src/command-errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEnE,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAc,EACd,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAe,EACvC,GAAiC;IAEjC,IAAI,OAAO;QAAE,OAAO,KAAK,CAAC;IAC1B,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IAChC,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAS,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;IACvD,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAClD,IAAI,YAAY,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;QACrF,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QACb,CAAC,CAAC,EAAE,CACP,CAAC;IACF,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1C,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACrD,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClD,OAAO,IAAI,KAAK,CAAC,KAAK,KAAK,YAAY,KAAK,mCAAmC,EAAE;QAC/E,KAAK,EAAE,KAAK;KACb,CAAC,CAAC;AACL,CAAC"}

package/dist/command-line/route-line.d.ts

@@ -1,15 +0,0 @@
-import type { SpecNode } from "../command-spec.js";
-import type { Invocation } from "./invocation.js";
-import { type CommandRoute } from "./route.js";
-import type { ShellWords } from "./shell-words.js";
-/** A line a test checks: the Command it routes to, or why it routes to none. */
-export type RoutedLine = {
-    readonly ok: true;
-    readonly routed: CommandRoute;
-    readonly invocation: Invocation;
-} | {
-    readonly ok: false;
-    readonly reason: string;
-};
-/** Routes `argv`, the line's words after the Run-as, to a Command of `root`. */
-export declare function routeLine(root: SpecNode, runAs: string, argv: ShellWords): RoutedLine;

package/dist/command-line/route-line.js

@@ -1,18 +0,0 @@
-import { route } from "./route.js";
-/** Routes `argv`, the line's words after the Run-as, to a Command of `root`. */
-export function routeLine(root, runAs, argv) {
-    if (!argv.ok)
-        return { ok: false, reason: `it does not tokenize: ${argv.reason}` };
-    const invocation = { runAs, argv: argv.words, flags: [] };
-    const routed = route(root, invocation);
-    switch (routed.kind) {
-        case "usage error":
-            return { ok: false, reason: routed.error.message };
-        case "help":
-        case "version":
-            return { ok: false, reason: "it names no Command" };
-        case "command":
-            return { ok: true, routed, invocation };
-    }
-}
-//# sourceMappingURL=route-line.js.map

package/dist/command-line/route-line.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"route-line.js","sourceRoot":"","sources":["../../src/command-line/route-line.ts"],"names":[],"mappings":"AAEA,OAAO,EAAqB,KAAK,EAAE,MAAM,YAAY,CAAC;AAQtD,gFAAgF;AAChF,MAAM,UAAU,SAAS,CAAC,IAAc,EAAE,KAAa,EAAE,IAAgB;IACvE,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,yBAAyB,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;IACnF,MAAM,UAAU,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;IAC1D,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IACvC,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,aAAa;YAChB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACrD,KAAK,MAAM,CAAC;QACZ,KAAK,SAAS;YACZ,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC;QACtD,KAAK,SAAS;YACZ,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAC5C,CAAC;AACH,CAAC"}