@duyquangnvx/agent-cli 0.17.0 → 0.18.0

package/dist/command-line/shell-words.js

@@ -0,0 +1,83 @@
+const BLANK = /\s/;
+// Unquoted, these make the line more than one command with its words, so its words can't be checked.
+const SHELL_SYNTAX = new Set(["|", "&", ";", ">", "(", ")", "$", "`"]);
+const STDIN_REDIRECT = "<";
+// Inside double quotes a backslash escapes only these, as in POSIX sh.
+const DOUBLE_QUOTE_ESCAPES = new Set(["$", "`", '"', "\\"]);
+function quotedFrom(line, start, quote) {
+    let word = "";
+    for (let index = start; index < line.length; index += 1) {
+        const char = line[index] ?? "";
+        if (char === quote)
+            return { word, end: index + 1 };
+        const next = line[index + 1];
+        if (quote === '"' && char === "\\" && next !== undefined && DOUBLE_QUOTE_ESCAPES.has(next)) {
+            word += next;
+            index += 1;
+        }
+        else {
+            word += char;
+        }
+    }
+    return undefined;
+}
+function skipBlanks(line, start) {
+    let index = start;
+    while (BLANK.test(line[index] ?? ""))
+        index += 1;
+    return index;
+}
+function isBoundary(char) {
+    return BLANK.test(char) || char === STDIN_REDIRECT || SHELL_SYNTAX.has(char);
+}
+// One word from `start` up to the next blank or shell operator, its quotes and escapes removed.
+function wordFrom(line, start) {
+    let word = "";
+    let index = start;
+    while (index < line.length && !isBoundary(line[index] ?? "")) {
+        const char = line[index] ?? "";
+        if (char === "'" || char === '"') {
+            const quoted = quotedFrom(line, index + 1, char);
+            if (quoted === undefined)
+                return { reason: `its ${char} is never closed` };
+            word += quoted.word;
+            index = quoted.end;
+        }
+        else if (char === "\\") {
+            word += line[index + 1] ?? "";
+            index += 2;
+        }
+        else {
+            word += char;
+            index += 1;
+        }
+    }
+    return { word, end: index };
+}
+/**
+ * The words a POSIX shell would pass for `line`, without the file of a `< file` redirect; a reason
+ * instead when a quote is left open or the line uses other shell syntax.
+ */
+export function shellWords(line) {
+    const words = [];
+    let index = skipBlanks(line, 0);
+    while (index < line.length) {
+        const redirect = line[index] === STDIN_REDIRECT;
+        if (redirect)
+            index = skipBlanks(line, index + 1);
+        const char = line[index];
+        if (char === undefined || char === STDIN_REDIRECT) {
+            return { ok: false, reason: "its `<` names no file" };
+        }
+        if (SHELL_SYNTAX.has(char))
+            return { ok: false, reason: `it uses the shell's \`${char}\`` };
+        const scanned = wordFrom(line, index);
+        if ("reason" in scanned)
+            return { ok: false, reason: scanned.reason };
+        if (!redirect)
+            words.push(scanned.word);
+        index = skipBlanks(line, scanned.end);
+    }
+    return { ok: true, words };
+}
+//# sourceMappingURL=shell-words.js.map

package/dist/command-line/shell-words.js.map

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

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

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

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

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

package/dist/{usage.d.ts → command-line/usage.d.ts}

@@ -1,4 +1,4 @@
-import { UsageError } from "./errors.js";
+import { UsageError } from "../errors.js";
 import { type Invocation } from "./invocation.js";
 export declare const INVALID_INPUT = "INVALID_INPUT";
 export declare const UNKNOWN_OPTION = "UNKNOWN_OPTION";

package/dist/{usage.js → command-line/usage.js}

@@ -1,6 +1,6 @@
-import { UsageError } from "./errors.js";
+import { STDIN_OPERAND } from "../context/stdin.js";
+import { UsageError } from "../errors.js";
 import { commandLineOf, commandLineRenaming } from "./invocation.js";
-import { STDIN_OPERAND } from "./stdin.js";
 export const INVALID_INPUT = "INVALID_INPUT";
 export const UNKNOWN_OPTION = "UNKNOWN_OPTION";
 export const UNKNOWN_COMMAND = "UNKNOWN_COMMAND";

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

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../src/command-line/usage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAmB,MAAM,iBAAiB,CAAC;AAEtF,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC;AAC7C,MAAM,CAAC,MAAM,cAAc,GAAG,gBAAgB,CAAC;AAC/C,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAC;AAUjD,SAAS,YAAY,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,EAAW;IAChF,OAAO,IAAI,UAAU,CAAC;QACpB,IAAI;QACJ,OAAO,EAAE,GAAG,OAAO,UAAU,WAAW,IAAI;QAC5C,IAAI,EACF,WAAW,CAAC,MAAM,KAAK,CAAC;YACtB,CAAC,CAAC,SAAS,WAAW,wBAAwB,MAAM,EAAE;YACtD,CAAC,CAAC,gBAAgB,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,KAAK,UAAU,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG;KAC3F,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,WAAmB,EACnB,UAAsB,EACtB,IAAY,EACZ,WAA8B;IAE9B,OAAO,YAAY,CAAC;QAClB,IAAI,EAAE,cAAc;QACpB,OAAO,EAAE,mBAAmB,IAAI,GAAG;QACnC,WAAW;QACX,WAAW,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CACpC,mBAAmB,CAAC,UAAU,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CACzD;QACD,MAAM,EAAE,SAAS;KAClB,CAAC,CAAC;AACL,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,cAAc,CAC5B,WAAmB,EACnB,UAAsB,EACtB,IAAY;IAEZ,MAAM,SAAS,GAAG,aAAa,CAAC,UAAU,EAAE,EAAE,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;IACtF,OAAO,IAAI,UAAU,CAAC;QACpB,IAAI,EAAE,cAAc;QACpB,OAAO,EAAE,mBAAmB,IAAI,WAAW,WAAW,IAAI;QAC1D,IAAI,EACF,wFAAwF;YACxF,KAAK,SAAS,yCAAyC;KAC1D,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,WAAmB,EACnB,IAAY,EACZ,WAA8B;IAE9B,OAAO,YAAY,CAAC;QAClB,IAAI,EAAE,eAAe;QACrB,OAAO,EAAE,oBAAoB,IAAI,GAAG;QACpC,WAAW;QACX,WAAW,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,GAAG,WAAW,IAAI,UAAU,EAAE,CAAC;QAC5E,MAAM,EAAE,UAAU;KACnB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,WAAmB,EAAE,OAAe;IACpE,OAAO,IAAI,UAAU,CAAC;QACpB,IAAI,EAAE,aAAa;QACnB,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,SAAS,WAAW,qCAAqC;KAChE,CAAC,CAAC;AACL,CAAC"}

package/dist/command-spec.d.ts

@@ -1,7 +1,7 @@
 import type * as z from "zod";
+import { type StandardFlag } from "./command-line/flags.js";
+import { type InputField } from "./command-line/input.js";
 import { type Command, type Commands, type Example } from "./define.js";
-import { type StandardFlag } from "./flags.js";
-import { type InputField } from "./input.js";
 import { type ListSpec } from "./list.js";
 /** Everything help, help JSON and input parsing know about one Command. */
 export interface CommandSpec {
@@ -17,6 +17,7 @@ export interface CommandSpec {
     readonly hidden: boolean;
     readonly operator: boolean;
     readonly effect: Command["effect"];
+    /** The examples as help prints them, each starting with the Run-as. */
     readonly examples: readonly Example[];
     readonly args: readonly InputField[];
     /** The options the author declared; Standard flags are kept apart in `standardFlags`. */
@@ -33,11 +34,19 @@ export interface GroupSpec {
 export type SpecNode = CommandSpec | GroupSpec;
 /** The group's Commands and groups that help and suggestions may name: hidden Commands left out. */
 export declare function visibleCommands({ commands }: GroupSpec): Readonly<Record<string, SpecNode>>;
+/** The words that label a Command in errors and spill files: its path, or the CLI's name for a single-Command CLI. */
+export declare function commandLabel(path: readonly string[], cliName: string): readonly string[];
+/** How the CLI is named: in an example's line, and in the lines it gives its caller. */
+export interface CliNames {
+    readonly name: string;
+    readonly runAs: string;
+}
 interface SpecPlace {
     readonly path: readonly string[];
     readonly builtIn: boolean;
+    readonly names: CliNames;
 }
-export declare function commandSpec(commandLine: string, command: Command, { path, builtIn }?: SpecPlace): CommandSpec;
+export declare function commandSpec(commandLine: string, command: Command, { path, builtIn, names }: SpecPlace): CommandSpec;
 /** The root group of a multi-Command CLI: the author's Commands, then the Built-in Commands. */
-export declare function groupSpec(commandLine: string, commands: Commands, builtIns: Commands): GroupSpec;
+export declare function groupSpec(names: CliNames, commands: Commands, builtIns: Commands): GroupSpec;
 export {};

package/dist/command-spec.js

@@ -1,12 +1,16 @@
+import { standardFlagsFor } from "./command-line/flags.js";
+import { argFields, optionFields } from "./command-line/input.js";
 import { isCommand } from "./define.js";
-import { standardFlagsFor } from "./flags.js";
-import { argFields, optionFields } from "./input.js";
 import { listSpec } from "./list.js";
 import { hasPlan } from "./planned.js";
 /** The group's Commands and groups that help and suggestions may name: hidden Commands left out. */
 export function visibleCommands({ commands }) {
     return Object.fromEntries(Object.entries(commands).filter(([, node]) => node.kind === "group" || !node.hidden));
 }
+/** The words that label a Command in errors and spill files: its path, or the CLI's name for a single-Command CLI. */
+export function commandLabel(path, cliName) {
+    return path.length === 0 ? [cliName] : path;
+}
 function declaredOf(command) {
     if (!hasPlan(command)) {
         return { outputs: false, force: undefined, cost: false };
@@ -17,8 +21,14 @@ function declaredOf(command) {
         cost: command.cost !== undefined,
     };
 }
-const SINGLE_COMMAND = { path: [], builtIn: false };
-export function commandSpec(commandLine, command, { path, builtIn } = SINGLE_COMMAND) {
+// An example that does not start with the CLI's name prints as written, for `checkExamples` to report.
+function withRunAs(example, { name, runAs }) {
+    const { command } = example;
+    return command === name || command.startsWith(`${name} `)
+        ? { ...example, command: `${runAs}${command.slice(name.length)}` }
+        : example;
+}
+export function commandSpec(commandLine, command, { path, builtIn, names }) {
     const list = command.rows === undefined ? undefined : listSpec(command.rows);
     return {
         kind: "command",
@@ -31,7 +41,7 @@ export function commandSpec(commandLine, command, { path, builtIn } = SINGLE_COM
         hidden: command.hidden === true,
         operator: command.operator === true,
         effect: command.effect,
-        examples: command.examples,
+        examples: command.examples.map((example) => withRunAs(example, names)),
         args: argFields(command.args),
         options: optionFields(command.options),
         standardFlags: standardFlagsFor(command.effect, declaredOf(command), list),
@@ -43,16 +53,17 @@ function group(commandLine, commands) {
     return { kind: "group", commandLine, commands };
 }
 /** The root group of a multi-Command CLI: the author's Commands, then the Built-in Commands. */
-export function groupSpec(commandLine, commands, builtIns) {
-    return group(commandLine, {
-        ...specsOf(commandLine, commands, { path: [], builtIn: false }),
-        ...specsOf(commandLine, builtIns, { path: [], builtIn: true }),
+export function groupSpec(names, commands, builtIns) {
+    const { runAs } = names;
+    return group(runAs, {
+        ...specsOf(runAs, commands, { path: [], builtIn: false, names }),
+        ...specsOf(runAs, builtIns, { path: [], builtIn: true, names }),
     });
 }
-function specsOf(commandLine, commands, { path, builtIn }) {
+function specsOf(commandLine, commands, { path, builtIn, names }) {
     return Object.fromEntries(Object.entries(commands).map(([key, node]) => [
         key,
-        specOf(`${commandLine} ${key}`, node, { path: [...path, key], builtIn }),
+        specOf(`${commandLine} ${key}`, node, { path: [...path, key], builtIn, names }),
     ]));
 }
 function specOf(commandLine, node, place) {

package/dist/command-spec.js.map

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

package/dist/{agent.d.ts → context/agent.d.ts}

@@ -1,4 +1,4 @@
-import type { Env } from "./context.js";
+import type { Env } from "../context.js";
 /**
  * Whether a Coding agent, not a person, is running the Agent CLI. Some Coding agents run commands
  * in a PTY, so a TTY alone doesn't mean a person is watching.

package/dist/context/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/context/agent.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAG,mBAAmB,CAAC;AAEvC,MAAM,KAAK,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,GAAQ,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC;AACvE,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,KAAa,EAAE,EAAE,CAAC,CAAC,GAAQ,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC;AAElF,oEAAoE;AACpE,qGAAqG;AACrG,MAAM,OAAO,GAAuC;IAClD,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC;IAC5C,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC;IACtB,KAAK,CAAC,eAAe,CAAC;IACtB,KAAK,CAAC,UAAU,CAAC;IACjB,KAAK,CAAC,iBAAiB,CAAC;IACxB,KAAK,CAAC,YAAY,CAAC;IACnB,KAAK,CAAC,aAAa,CAAC;IACpB,KAAK,CAAC,UAAU,CAAC;IACjB,KAAK,CAAC,mBAAmB,CAAC;IAC1B,KAAK,CAAC,eAAe,CAAC;IACtB,KAAK,CAAC,SAAS,CAAC;IAChB,KAAK,CAAC,uBAAuB,CAAC;IAC9B,KAAK,CAAC,YAAY,CAAC;IACnB,KAAK,CAAC,aAAa,CAAC;IACpB,KAAK,CAAC,iBAAiB,CAAC;IACxB,KAAK,CAAC,cAAc,CAAC;IACrB,MAAM,CAAC,4BAA4B,EAAE,YAAY,CAAC;IAClD,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC;IAC9B,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,YAAY,EAAE,cAAc,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IACrF,KAAK,CAAC,gBAAgB,CAAC;CACxB,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,GAAQ;IAC9B,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;AAC/C,CAAC"}

package/dist/{confirm.d.ts → context/confirm.d.ts}

@@ -1,9 +1,9 @@
-import { type Invocation } from "./invocation.js";
+import type { Context } from "../context.js";
 export declare const CONFIRMATION_REQUIRED = "CONFIRMATION_REQUIRED";
 export declare const CONFIRMATION_MISMATCH = "CONFIRMATION_MISMATCH";
 export interface Confirmation {
-    readonly invocation: Invocation;
+    readonly rerun: Context["rerun"];
     readonly commandLine: string;
     readonly given: string | undefined;
 }
-export declare function checkConfirmation({ invocation, commandLine, given }: Confirmation, expected: string): void;
+export declare function checkConfirmation({ rerun, commandLine, given }: Confirmation, expected: string): void;

package/dist/{confirm.js → context/confirm.js}

@@ -1,28 +1,26 @@
-import { UsageError } from "./errors.js";
-import { CONFIRM_FLAG } from "./flags.js";
-import { commandLineOf } from "./invocation.js";
+import { CONFIRM_FLAG } from "../command-line/flags.js";
+import { UsageError } from "../errors.js";
 export const CONFIRMATION_REQUIRED = "CONFIRMATION_REQUIRED";
 export const CONFIRMATION_MISMATCH = "CONFIRMATION_MISMATCH";
-export function checkConfirmation({ invocation, commandLine, given }, expected) {
+export function checkConfirmation({ rerun, commandLine, given }, expected) {
     if (given === expected) {
         return;
     }
-    const confirmed = commandLineOf(invocation, {
-        remove: [CONFIRM_FLAG.flag],
-        add: [CONFIRM_FLAG.flag, expected],
-    });
-    const hint = `to confirm, run \`${confirmed}\``;
+    const advice = {
+        hint: "to confirm, run the Next step",
+        next: [rerun({ remove: [CONFIRM_FLAG.flag], add: [CONFIRM_FLAG.flag, expected] })],
+    };
     if (given === undefined) {
         throw new UsageError({
             code: CONFIRMATION_REQUIRED,
             message: `\`${commandLine}\` is destructive and needs ${CONFIRM_FLAG.flag}`,
-            hint,
+            ...advice,
         });
     }
     throw new UsageError({
         code: CONFIRMATION_MISMATCH,
         message: `${CONFIRM_FLAG.flag} ${JSON.stringify(given)} does not match the target of \`${commandLine}\``,
-        hint,
+        ...advice,
     });
 }
 //# sourceMappingURL=confirm.js.map

package/dist/context/confirm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirm.js","sourceRoot":"","sources":["../../src/context/confirm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAExD,OAAO,EAAe,UAAU,EAAE,MAAM,cAAc,CAAC;AAEvD,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAuB,CAAC;AAC7D,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAuB,CAAC;AAQ7D,MAAM,UAAU,iBAAiB,CAC/B,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAgB,EAC3C,QAAgB;IAEhB,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvB,OAAO;IACT,CAAC;IACD,MAAM,MAAM,GAAW;QACrB,IAAI,EAAE,+BAA+B;QACrC,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;KACnF,CAAC;IACF,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,UAAU,CAAC;YACnB,IAAI,EAAE,qBAAqB;YAC3B,OAAO,EAAE,KAAK,WAAW,+BAA+B,YAAY,CAAC,IAAI,EAAE;YAC3E,GAAG,MAAM;SACV,CAAC,CAAC;IACL,CAAC;IACD,MAAM,IAAI,UAAU,CAAC;QACnB,IAAI,EAAE,qBAAqB;QAC3B,OAAO,EAAE,GAAG,YAAY,CAAC,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,mCAAmC,WAAW,IAAI;QACxG,GAAG,MAAM;KACV,CAAC,CAAC;AACL,CAAC"}

package/dist/{cost.d.ts → context/cost.d.ts}

@@ -1,9 +1,9 @@
-import { type Invocation } from "./invocation.js";
+import type { Context } from "../context.js";
 export declare const NOT_CONFIRMED = "NOT_CONFIRMED";
 export interface Approval {
-    readonly invocation: Invocation;
+    readonly rerun: Context["rerun"];
     readonly commandLine: string;
     readonly yes: boolean;
 }
 /** Refuses a run whose Plan states a cost the caller has not approved with `--yes`. */
-export declare function checkCost({ invocation, commandLine, yes }: Approval, cost: string | undefined): void;
+export declare function checkCost({ rerun, commandLine, yes }: Approval, cost: string | undefined): void;

package/dist/context/cost.js

@@ -0,0 +1,16 @@
+import { YES_FLAG } from "../command-line/flags.js";
+import { CliError } from "../errors.js";
+export const NOT_CONFIRMED = "NOT_CONFIRMED";
+/** Refuses a run whose Plan states a cost the caller has not approved with `--yes`. */
+export function checkCost({ rerun, commandLine, yes }, cost) {
+    if (cost === undefined || yes) {
+        return;
+    }
+    throw new CliError({
+        code: NOT_CONFIRMED,
+        message: `\`${commandLine}\` needs ${YES_FLAG.flag}: ${cost}`,
+        hint: "to approve the cost, run the Next step",
+        next: [rerun({ add: [YES_FLAG.flag] })],
+    });
+}
+//# sourceMappingURL=cost.js.map

package/dist/context/cost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost.js","sourceRoot":"","sources":["../../src/context/cost.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEpD,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAExC,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC;AAQ7C,uFAAuF;AACvF,MAAM,UAAU,SAAS,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,EAAY,EAAE,IAAwB;IACvF,IAAI,IAAI,KAAK,SAAS,IAAI,GAAG,EAAE,CAAC;QAC9B,OAAO;IACT,CAAC;IACD,MAAM,IAAI,QAAQ,CAAC;QACjB,IAAI,EAAE,aAAa;QACnB,OAAO,EAAE,KAAK,WAAW,YAAY,QAAQ,CAAC,IAAI,KAAK,IAAI,EAAE;QAC7D,IAAI,EAAE,wCAAwC;QAC9C,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;KACxC,CAAC,CAAC;AACL,CAAC"}

package/dist/context/declared.d.ts

@@ -0,0 +1,8 @@
+import { type Command, type Commands } from "../define.js";
+/**
+ * What the CLI declares itself (`own`) and every Command under `commands` declares, each name once,
+ * for a `doctor` row: a Command requires only its own, but `doctor` checks them all.
+ */
+export declare function declaredIn<Need extends {
+    readonly name: string;
+}>(own: readonly Need[], commands: Commands, needsOf: (command: Command) => readonly Need[] | undefined): Need[];

package/dist/context/declared.js

@@ -0,0 +1,10 @@
+import { isCommand } from "../define.js";
+/**
+ * What the CLI declares itself (`own`) and every Command under `commands` declares, each name once,
+ * for a `doctor` row: a Command requires only its own, but `doctor` checks them all.
+ */
+export function declaredIn(own, commands, needsOf) {
+    const walk = (node) => isCommand(node) ? [...(needsOf(node) ?? [])] : Object.values(node).flatMap(walk);
+    return [...new Map([...own, ...walk(commands)].map((need) => [need.name, need])).values()];
+}
+//# sourceMappingURL=declared.js.map

package/dist/context/declared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"declared.js","sourceRoot":"","sources":["../../src/context/declared.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,SAAS,EAAE,MAAM,cAAc,CAAC;AAEtE;;;GAGG;AACH,MAAM,UAAU,UAAU,CACxB,GAAoB,EACpB,QAAkB,EAClB,OAA0D;IAE1D,MAAM,IAAI,GAAG,CAAC,IAAwB,EAAU,EAAE,CAChD,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACnF,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;AAC7F,CAAC"}

package/dist/{errno.d.ts → context/errno.d.ts}

@@ -1,4 +1,5 @@
-import type { Env } from "./context.js";
+import type { Env } from "../context.js";
+import type { Rerun } from "../next-step.js";
 export declare const PERMISSION_DENIED = "PERMISSION_DENIED";
 export declare const DISK_FULL = "DISK_FULL";
 export declare const NOT_FOUND = "NOT_FOUND";
@@ -11,8 +12,8 @@ export interface FileAccess {
 }
 export type FileError = (error: unknown, at: FileAccess) => unknown;
 export interface ErrnoScope {
-    /** The caller's command line, ready to paste. */
-    readonly callerLine: string;
+    /** The caller's own line, the Next step once the cause is fixed. */
+    readonly rerun: Rerun;
     readonly env: Env;
     readonly platform: NodeJS.Platform;
 }

package/dist/{errno.js → context/errno.js}

@@ -1,5 +1,5 @@
+import { CliError, errnoOf } from "../errors.js";
 import { isAgent } from "./agent.js";
-import { CliError, errnoOf } from "./errors.js";
 export const PERMISSION_DENIED = "PERMISSION_DENIED";
 export const DISK_FULL = "DISK_FULL";
 export const NOT_FOUND = "NOT_FOUND";
@@ -7,16 +7,22 @@ export const ALREADY_EXISTS = "ALREADY_EXISTS";
 export const NOT_A_FILE = "NOT_A_FILE";
 // The same errnos happen with no sandbox at all (a root-owned folder), so only a detected agent is
 // pointed at its sandbox. Native Windows has no such sandbox: there a program holding the file denies it.
-function permissionHint({ path, access, callerLine, env, platform }) {
+function permissionAdvice({ path, access, rerun, env, platform }) {
     if (platform === "win32") {
-        return `a program may hold ${path} open: close it, then run \`${callerLine}\` again`;
+        return {
+            hint: `a program may hold ${path} open: close it, then run the Next step`,
+            next: [rerun],
+        };
     }
     if (!isAgent(env))
-        return `check the permissions of ${path} and its folder`;
+        return { hint: `check the permissions of ${path} and its folder` };
     const allow = access === "read"
         ? `to allow reading ${path} in the sandbox`
         : `to allow ${path} in the sandbox's write list`;
-    return `your sandbox may block it: ask your user to run \`! ${callerLine}\`, or ${allow}`;
+    return {
+        hint: `your sandbox may block it: ask your user to type ! then the Next step, or ${allow}`,
+        next: [rerun],
+    };
 }
 export function fileErrorOf(scope) {
     return (error, at) => classifyErrno(error, { ...at, ...scope });
@@ -31,14 +37,15 @@ function classifyErrno(error, context) {
             return new CliError({
                 code: PERMISSION_DENIED,
                 message: `permission denied: ${path}`,
-                hint: permissionHint(context),
+                ...permissionAdvice(context),
             }, { cause: error });
         case "ENOSPC":
         case "EDQUOT":
             return new CliError({
                 code: DISK_FULL,
                 message: `no space left on the disk holding ${path}`,
-                hint: `free space on that disk, then run \`${context.callerLine}\` again`,
+                hint: "free space on that disk, then run the Next step",
+                next: [context.rerun],
             }, { cause: error });
         case "ENOENT":
         case "ENOTDIR":

package/dist/context/errno.js.map

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

package/dist/{files.js → context/files.js}

@@ -1,7 +1,7 @@
 import { access, chmod, link, mkdir, open, readdir, readFile, realpath, rename, rm, stat, writeFile, } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
-import { errnoOf, isMissingFile, isNothingThere } from "./errors.js";
+import { errnoOf, isMissingFile, isNothingThere } from "../errors.js";
 const TEMP_FILE = /^\..+\.agent-cli-(\d+)\.tmp$/;
 /** Where the Runtime writes `path` before moving it into place; a dead writer's is swept. */
 export function tempPathOf(path) {

package/dist/context/files.js.map

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

package/dist/{interrupts.d.ts → context/interrupts.d.ts}

@@ -1,37 +1,41 @@
-import { type Clock } from "./clock.js";
+import { type Clock } from "../clock.js";
+import { type Advice } from "../errors.js";
+import type { Rerun } from "../next-step.js";
 export declare const INTERRUPTED = "INTERRUPTED";
 export declare const DEADLINE_EXCEEDED = "DEADLINE_EXCEEDED";
 /** How long an interrupted Command may take to settle before the run ends without it. */
 export declare const GRACE_MS = 3000;
+export interface DeadlineOptions {
+    readonly ignoreStop?: boolean;
+}
 export interface RunControlOptions {
     readonly commandLine: string;
-    /** The caller's command line, ready to paste, that the hints ask to run again. */
-    readonly callerLine: string;
+    /** The caller's own line, the Next step of an interrupt or a missed deadline. */
+    readonly rerun: Rerun;
     /** The caller's signal, whose abort interrupts the run. */
     readonly outer: AbortSignal | undefined;
     readonly clock: Clock;
     readonly progress: (message: string) => void;
-    /** The whole run's deadline and the hint, naming the resume command line, it ends with. */
+    /** The whole run's deadline and the advice, naming the resume Next step, it ends with. */
     readonly runDeadline: {
         readonly ms: number;
-        readonly hint: () => string;
+        readonly advice: () => Advice;
     } | undefined;
 }
 /** One Command run's cancellation: its signal, its deadlines and the steps it must finish. */
 export declare class RunControl {
     #private;
     readonly signal: AbortSignal;
-    constructor({ commandLine, callerLine, outer, clock, progress, runDeadline }: RunControlOptions);
-    deadline(ms: number): AbortSignal;
-    timeout(ms: number): AbortSignal;
+    constructor({ commandLine, rerun, outer, clock, progress, runDeadline }: RunControlOptions);
+    deadline(ms: number, options?: DeadlineOptions): AbortSignal;
     runToEnd<T>(name: string, work: () => Promise<T>): Promise<T>;
     /** Waits for the Command, its must-finish steps, and no longer than the grace once interrupted. */
     settle<T>(work: Promise<T>): Promise<T>;
     /**
      * The error a run ends with: an interrupt or the run deadline outranks what the Command threw,
      * unless the Command threw its own `INTERRUPTED`, saying what it finished before it stopped.
-     * Otherwise each leaf that is not a `CliError` and whose cause chain holds a deadline's or timeout's
-     * abort is reported as that abort, so a declared error keeps its own code.
+     * Otherwise each leaf that is not a `CliError` and whose cause chain holds a deadline's abort is
+     * reported as that abort, so a declared error keeps its own code.
      */
     errorAfter(error: unknown): unknown;
     /** Stops the run's timers and its hold on the caller's signal, for a run that never settles. */