@duyquangnvx/agent-cli 0.16.0 → 0.18.0

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

@@ -1,29 +1,32 @@
-import { after } from "./clock.js";
-import { CliError, causesOf, errorsOf } from "./errors.js";
+import { after } from "../clock.js";
+import { CliError, causesOf, errorsOf } from "../errors.js";
 export const INTERRUPTED = "INTERRUPTED";
 export const DEADLINE_EXCEEDED = "DEADLINE_EXCEEDED";
 /** How long an interrupted Command may take to settle before the run ends without it. */
 export const GRACE_MS = 3000;
 const GRACE_OVER = Symbol("grace over");
 // Ctrl-C is often the operator stopping it on purpose, and a tool timeout stops a plain rerun again.
-function interruptedError(callerLine) {
+function interruptedError(rerun) {
     return new CliError({
         code: INTERRUPTED,
         message: "interrupted before it finished",
-        hint: `to finish it, run \`${callerLine}\` again, unless it was stopped on purpose; if a tool timeout stopped it, give it longer`,
+        hint: "to finish it, run the Next step, unless it was stopped on purpose; if a tool timeout stopped it, give it longer",
+        next: [rerun],
     });
 }
-// A timeout bounds a billed call, which may have been billed before it ran out.
-function waitHint(callerLine, bound) {
-    return bound === "timeout"
-        ? `the call may have been billed: ask your user before running \`${callerLine}\` again`
-        : `run \`${callerLine}\` again later, when the service it waits on may answer faster`;
+// The word an error names a bound by: one that ignores stops bounds a single call, a timeout.
+const BOUND_WORDS = { deadline: "deadline", ignoreStop: "timeout" };
+// A deadline that ignores stops bounds a billed call, which may have been billed before it ran out.
+function waitHint(bound) {
+    return bound === "ignoreStop"
+        ? "the call may have been billed: ask your user before running the Next step"
+        : "run the Next step later, when the service it waits on may answer faster";
 }
-function deadlineError(commandLine, ms, hint, bound = "deadline") {
+function deadlineError(commandLine, ms, advice, bound = "deadline") {
     return new CliError({
         code: DEADLINE_EXCEEDED,
-        message: `${commandLine} ran past its ${ms} ms ${bound}`,
-        hint,
+        message: `${commandLine} ran past its ${ms} ms ${BOUND_WORDS[bound]}`,
+        ...advice,
     });
 }
 /** One Command run's cancellation: its signal, its deadlines and the steps it must finish. */
@@ -31,24 +34,24 @@ export class RunControl {
     signal;
     #controller = new AbortController();
     #commandLine;
-    #callerLine;
+    #rerun;
     #outer;
-    #onOuterAbort = () => this.#controller.abort(interruptedError(this.#callerLine));
+    #onOuterAbort = () => this.#controller.abort(interruptedError(this.#rerun));
     /** Each running must-finish step, tracked until it settles, with its name. */
     #steps = new Map();
     #progress;
     #clock;
     #disposed = new AbortController();
-    /** The reasons this run's deadlines and timeouts aborted with, to tell them in a Command's error. */
+    /** The reasons this run's deadlines aborted with, to tell them in a Command's error. */
     #abortReasons = new WeakSet();
     #graceCancel = new AbortController();
     #endGrace = () => { };
     #graceOver = new Promise((resolve) => {
         this.#endGrace = resolve;
     });
-    constructor({ commandLine, callerLine, outer, clock, progress, runDeadline }) {
+    constructor({ commandLine, rerun, outer, clock, progress, runDeadline }) {
         this.#commandLine = commandLine;
-        this.#callerLine = callerLine;
+        this.#rerun = rerun;
         this.#outer = outer;
         this.#clock = clock;
         this.#progress = progress;
@@ -61,20 +64,20 @@ export class RunControl {
             outer?.addEventListener("abort", this.#onOuterAbort, { once: true });
         }
         if (runDeadline !== undefined) {
-            const { ms, hint } = runDeadline;
-            after(clock, ms, this.#disposed.signal, () => this.#controller.abort(deadlineError(commandLine, ms, hint())));
+            const { ms, advice } = runDeadline;
+            after(clock, ms, this.#disposed.signal, () => this.#controller.abort(deadlineError(commandLine, ms, advice())));
         }
     }
-    deadline(ms) {
-        return AbortSignal.any([this.signal, this.#abortsAfter(ms, "deadline")]);
-    }
-    timeout(ms) {
-        return this.#abortsAfter(ms, "timeout");
+    deadline(ms, options = {}) {
+        return options.ignoreStop === true
+            ? this.#abortsAfter(ms, "ignoreStop")
+            : AbortSignal.any([this.signal, this.#abortsAfter(ms, "deadline")]);
     }
     #abortsAfter(ms, bound) {
         const controller = new AbortController();
         after(this.#clock, ms, this.#disposed.signal, () => {
-            const reason = deadlineError(this.#commandLine, ms, waitHint(this.#callerLine, bound), bound);
+            const advice = { hint: waitHint(bound), next: [this.#rerun] };
+            const reason = deadlineError(this.#commandLine, ms, advice, bound);
             this.#abortReasons.add(reason);
             controller.abort(reason);
         });
@@ -113,8 +116,8 @@ export class RunControl {
     /**
      * 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) {
         if (this.signal.aborted) {

package/dist/context/interrupts.js.map

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

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

@@ -1,5 +1,6 @@
-import type { CommandSpec } from "./command-spec.js";
-import type { Env } from "./context.js";
+import type { CommandSpec } from "../command-spec.js";
+import type { Env } from "../context.js";
+import type { Rerun } from "../next-step.js";
 export declare const NEEDS_OPERATOR = "NEEDS_OPERATOR";
 /** Fails with `NEEDS_OPERATOR` when a Coding agent runs an Operator Command. */
-export declare function checkOperator({ operator, commandLine }: CommandSpec, env: Env, callerLine: string): void;
+export declare function checkOperator({ operator, commandLine }: CommandSpec, env: Env, rerun: Rerun): void;

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

@@ -1,15 +1,16 @@
+import { CliError } from "../errors.js";
 import { isAgent } from "./agent.js";
-import { CliError } from "./errors.js";
 export const NEEDS_OPERATOR = "NEEDS_OPERATOR";
 /** Fails with `NEEDS_OPERATOR` when a Coding agent runs an Operator Command. */
-export function checkOperator({ operator, commandLine }, env, callerLine) {
+export function checkOperator({ operator, commandLine }, env, rerun) {
     if (!operator || !isAgent(env))
         return;
     throw new CliError({
         code: NEEDS_OPERATOR,
         message: `\`${commandLine}\` must be run by a person at a terminal, not a Coding agent`,
         // Typed at Claude Code's prompt, `!` runs the rest of the line in the operator's own shell.
-        hint: `ask the operator to type: ! ${callerLine}`,
+        hint: "ask the operator to type ! then the Next step",
+        next: [rerun],
     });
 }
 //# sourceMappingURL=operator.js.map

package/dist/context/operator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator.js","sourceRoot":"","sources":["../../src/context/operator.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAExC,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC,MAAM,CAAC,MAAM,cAAc,GAAG,gBAAgB,CAAC;AAE/C,gFAAgF;AAChF,MAAM,UAAU,aAAa,CAC3B,EAAE,QAAQ,EAAE,WAAW,EAAe,EACtC,GAAQ,EACR,KAAY;IAEZ,IAAI,CAAC,QAAQ,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO;IACvC,MAAM,IAAI,QAAQ,CAAC;QACjB,IAAI,EAAE,cAAc;QACpB,OAAO,EAAE,KAAK,WAAW,8DAA8D;QACvF,4FAA4F;QAC5F,IAAI,EAAE,+CAA+C;QACrD,IAAI,EAAE,CAAC,KAAK,CAAC;KACd,CAAC,CAAC;AACL,CAAC"}

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

@@ -1,23 +1,24 @@
+import type { Context } from "../context.js";
+import type { NextStep } from "../next-step.js";
 import { type FileError } from "./errno.js";
 import { type Files } from "./files.js";
-import { type Invocation } from "./invocation.js";
 export declare const OUTPUT_EXISTS = "OUTPUT_EXISTS";
 export interface Overwrite {
-    readonly invocation: Invocation;
+    readonly rerun: Context["rerun"];
     readonly commandLine: string;
     readonly force: boolean;
     readonly files: Files;
 }
 /** Refuses a run that would overwrite existing outputs unless the caller passed `--force`. */
-export declare function checkOutputs({ invocation, commandLine, force, files }: Overwrite, outputs: readonly string[] | undefined): Promise<void>;
+export declare function checkOutputs({ rerun, commandLine, force, files }: Overwrite, outputs: readonly string[] | undefined): Promise<void>;
 export interface OutputsGuard {
     /**
      * The run's files: the first write to each guarded output is exclusive, so a file that appeared
      * meanwhile is kept; a later write to it replaces what this run wrote.
      */
     readonly files: Files;
-    /** Guards `outputs` from now on; a refused write's hint names `forceLine`. */
-    guard(outputs: readonly string[], forceLine: string): void;
+    /** Guards `outputs` from now on; a refused write gives `forceStep` as its Next step. */
+    guard(outputs: readonly string[], forceStep: NextStep): void;
 }
 /** Guards the writes to declared outputs of `files`, whose paths resolve against `cwd`. */
 export declare function outputsGuard(files: Files, cwd: string): OutputsGuard;

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

@@ -1,12 +1,11 @@
 import { dirname, join, resolve } from "node:path";
+import { FORCE_FLAG } from "../command-line/flags.js";
+import { CliError } from "../errors.js";
 import { ALREADY_EXISTS } from "./errno.js";
-import { CliError } from "./errors.js";
 import { tempPathOf } from "./files.js";
-import { FORCE_FLAG } from "./flags.js";
-import { commandLineOf } from "./invocation.js";
 export const OUTPUT_EXISTS = "OUTPUT_EXISTS";
 /** Refuses a run that would overwrite existing outputs unless the caller passed `--force`. */
-export async function checkOutputs({ invocation, commandLine, force, files }, outputs) {
+export async function checkOutputs({ rerun, commandLine, force, files }, outputs) {
     if (outputs === undefined || force) {
         return;
     }
@@ -19,13 +18,14 @@ export async function checkOutputs({ invocation, commandLine, force, files }, ou
     throw new CliError({
         code: OUTPUT_EXISTS,
         message: `\`${commandLine}\` would overwrite ${existing.join(", ")}`,
-        hint: `to replace ${them}, run \`${commandLineOf(invocation, { add: [FORCE_FLAG.flag] })}\``,
+        hint: `to replace ${them}, run the Next step`,
+        next: [rerun({ add: [FORCE_FLAG.flag] })],
     });
 }
 /** Guards the writes to declared outputs of `files`, whose paths resolve against `cwd`. */
 export function outputsGuard(files, cwd) {
     const unwritten = new Set();
-    let forceLine = "";
+    let forceStep = [];
     const exclusiveWrite = async (path, data, options) => {
         const target = resolve(cwd, path);
         unwritten.delete(target);
@@ -39,7 +39,8 @@ export function outputsGuard(files, cwd) {
             throw new CliError({
                 code: ALREADY_EXISTS,
                 message: error.message,
-                hint: `to replace it, run \`${forceLine}\``,
+                hint: "to replace it, run the Next step",
+                next: [forceStep],
             }, { cause: error });
         }
     };
@@ -50,8 +51,8 @@ export function outputsGuard(files, cwd) {
                 ? exclusiveWrite(path, data, options)
                 : files.write(path, data, options),
         },
-        guard: (outputs, line) => {
-            forceLine = line;
+        guard: (outputs, step) => {
+            forceStep = step;
             for (const path of outputs)
                 unwritten.add(resolve(cwd, path));
         },

package/dist/context/outputs.js.map

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

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

@@ -1,10 +1,11 @@
-import type { Project, ProjectFile } from "./context.js";
+import type { Project, ProjectFile } from "../context.js";
+import type { Rerun } from "../next-step.js";
 import type { FileError } from "./errno.js";
 export declare const PROJECT_INVALID = "PROJECT_INVALID";
 export interface ProjectScope {
     readonly fileError: FileError;
-    /** The caller's command line, ready to paste, that the hint asks to run again. */
-    readonly callerLine: string;
+    /** The caller's own line, the Next step once the file is fixed. */
+    readonly rerun: Rerun;
 }
 /** The nearest Project file at or above `cwd`, parsed by its schema; undefined when there is none. */
 export declare function projectOf<Settings>(projectFile: ProjectFile<Settings>, cwd: string, scope: ProjectScope): Project<Settings> | undefined;

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

@@ -1,13 +1,14 @@
 import { readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import * as z from "zod";
-import { CliError, isMissingFile, messageOf } from "./errors.js";
+import { CliError, isMissingFile, messageOf } from "../errors.js";
 export const PROJECT_INVALID = "PROJECT_INVALID";
-function invalid(path, problem, callerLine, options) {
+function invalid(path, problem, rerun, options) {
     return new CliError({
         code: PROJECT_INVALID,
         message: `the Project file ${path} is invalid: ${problem}`,
-        hint: `fix ${path}, then run \`${callerLine}\` again`,
+        hint: `fix ${path}, then run the Next step`,
+        next: [rerun],
     }, options);
 }
 function readText(path, fileError) {
@@ -20,24 +21,24 @@ function readText(path, fileError) {
         throw fileError(error, { path, access: "read" });
     }
 }
-function parsed(path, text, schema, callerLine) {
+function parsed(path, text, schema, rerun) {
     let json;
     try {
         json = JSON.parse(text);
     }
     catch (error) {
-        throw invalid(path, messageOf(error), callerLine, { cause: error });
+        throw invalid(path, messageOf(error), rerun, { cause: error });
     }
     const result = schema.safeParse(json);
     if (!result.success)
-        throw invalid(path, z.prettifyError(result.error), callerLine);
+        throw invalid(path, z.prettifyError(result.error), rerun);
     return result.data;
 }
 function projectFrom(projectFile, folder, scope) {
     const path = join(folder, projectFile.file);
     const text = readText(path, scope.fileError);
     if (text !== undefined) {
-        return { root: folder, settings: parsed(path, text, projectFile.schema, scope.callerLine) };
+        return { root: folder, settings: parsed(path, text, projectFile.schema, scope.rerun) };
     }
     const parent = dirname(folder);
     return parent === folder ? undefined : projectFrom(projectFile, parent, scope);

package/dist/context/project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../../src/context/project.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAIlE,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAC;AAQjD,SAAS,OAAO,CAAC,IAAY,EAAE,OAAe,EAAE,KAAY,EAAE,OAAsB;IAClF,OAAO,IAAI,QAAQ,CACjB;QACE,IAAI,EAAE,eAAe;QACrB,OAAO,EAAE,oBAAoB,IAAI,gBAAgB,OAAO,EAAE;QAC1D,IAAI,EAAE,OAAO,IAAI,0BAA0B;QAC3C,IAAI,EAAE,CAAC,KAAK,CAAC;KACd,EACD,OAAO,CACR,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CAAC,IAAY,EAAE,SAAoB;IAClD,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,aAAa,CAAC,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QAC3C,MAAM,SAAS,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACnD,CAAC;AACH,CAAC;AAED,SAAS,MAAM,CACb,IAAY,EACZ,IAAY,EACZ,MAA2B,EAC3B,KAAY;IAEZ,IAAI,IAAa,CAAC;IAClB,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACjE,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;IAC/E,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC;AAED,SAAS,WAAW,CAClB,WAAkC,EAClC,MAAc,EACd,KAAmB;IAEnB,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAC7C,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;IACzF,CAAC;IACD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/B,OAAO,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;AACjF,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,SAAS,CACvB,WAAkC,EAClC,GAAW,EACX,KAAmB;IAEnB,OAAO,WAAW,CAAC,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;AACvD,CAAC"}

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

@@ -1,5 +1,8 @@
-import type { Env } from "./context.js";
+import type { Env } from "../context.js";
+import type { Commands, DoctorCheck, SecretDeclaration } from "../define.js";
+import type { Rerun } from "../next-step.js";
 import type { FileError } from "./errno.js";
+export declare const SECRET_MISSING = "SECRET_MISSING";
 export type SecretOrigin = {
     readonly kind: "env";
 } | {
@@ -21,3 +24,7 @@ export interface SecretScope {
 }
 /** Looks `name` up in the env, then in `envFile`; an empty value counts as unset. */
 export declare function secretOf({ envFile, env, fileError }: SecretScope, name: string): Secret | undefined;
+/** Fails with `SECRET_MISSING`, naming every missing Secret at once, unless all are set. */
+export declare function checkSecrets(secrets: readonly SecretDeclaration[], scope: SecretScope, rerun: Rerun): void;
+/** The `doctor` row over every distinct Secret the CLI and its Commands declare; none without any. */
+export declare function secretRows(secrets: readonly SecretDeclaration[], commands: Commands): DoctorCheck[];

package/dist/context/secrets.js

@@ -0,0 +1,85 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parseEnv } from "node:util";
+import { CliError, isMissingFile } from "../errors.js";
+import { declaredIn } from "./declared.js";
+export const SECRET_MISSING = "SECRET_MISSING";
+/** `$XDG_CONFIG_HOME/<cli>/.env`, with `~/.config` when the variable is unset or empty. */
+export function envFileOf(cliName, env) {
+    const config = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), ".config");
+    return join(config, cliName, ".env");
+}
+function readDotenv(path, fileError) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (isMissingFile(error))
+            return {};
+        throw fileError(error, { path, access: "read" });
+    }
+    return parseEnv(text);
+}
+/** Looks `name` up in the env, then in `envFile`; an empty value counts as unset. */
+export function secretOf({ envFile, env, fileError }, name) {
+    const fromEnv = env[name];
+    if (fromEnv)
+        return { value: fromEnv, origin: { kind: "env" } };
+    const fromFile = readDotenv(envFile, fileError)[name];
+    return fromFile ? { value: fromFile, origin: { kind: "file", path: envFile } } : undefined;
+}
+function missingIn(scope, secrets) {
+    return secrets.filter(({ name }) => secretOf(scope, name) === undefined);
+}
+function getItFrom({ get }) {
+    return `(get it from ${get})`;
+}
+function whereToGet(secrets) {
+    return secrets.map((secret) => `${secret.name} ${getItFrom(secret)}`).join(", ");
+}
+/** Fails with `SECRET_MISSING`, naming every missing Secret at once, unless all are set. */
+export function checkSecrets(secrets, scope, rerun) {
+    const missing = missingIn(scope, secrets);
+    if (missing.length === 0)
+        return;
+    const names = missing.map(({ name }) => name).join(", ");
+    throw new CliError({
+        code: SECRET_MISSING,
+        message: `${missing.length === 1 ? "a Secret it needs is" : "Secrets it needs are"} not set: ${names}`,
+        hint: `set ${whereToGet(missing)} in the environment or in ${scope.envFile}, then run the Next step`,
+        next: [rerun],
+    });
+}
+function originOf({ origin }) {
+    return origin.kind === "env" ? "the environment" : origin.path;
+}
+/** The `doctor` row over every distinct Secret the CLI and its Commands declare; none without any. */
+export function secretRows(secrets, commands) {
+    const declared = declaredIn(secrets, commands, (command) => command.secrets);
+    if (declared.length === 0)
+        return [];
+    return [
+        {
+            name: "secrets",
+            run: ({ env, envFile, fileError }) => {
+                const read = declared.map((declaration) => ({
+                    declaration,
+                    secret: secretOf({ env, envFile, fileError }, declaration.name),
+                }));
+                const missing = read.filter(({ secret }) => secret === undefined);
+                if (missing.length > 0) {
+                    const each = missing.map(({ declaration }) => `${declaration.name} is not set ${getItFrom(declaration)}`);
+                    return {
+                        state: "problem",
+                        message: `${each.join(", ")}; add ${missing.length === 1 ? "it" : "them"} to ${envFile} or the environment`,
+                    };
+                }
+                const found = read.flatMap(({ declaration, secret }) => secret === undefined ? [] : [`${declaration.name} from ${originOf(secret)}`]);
+                return { state: "ok", message: found.join(", ") };
+            },
+        },
+    ];
+}
+//# sourceMappingURL=secrets.js.map

package/dist/context/secrets.js.map

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

package/dist/{side-task.d.ts → context/side-task.d.ts}

@@ -1,5 +1,5 @@
-import { type Clock } from "./clock.js";
-import type { PortsBase } from "./context.js";
+import { type Clock } from "../clock.js";
+import type { PortsBase } from "../context.js";
 /** How long a run waits for its Side task once its output is written. */
 export declare const SIDE_TASK_WAIT_MS = 1000;
 /** What a CLI's Side task receives for one Command run. */

package/dist/{side-task.js → context/side-task.js}

@@ -1,4 +1,4 @@
-import { after } from "./clock.js";
+import { after } from "../clock.js";
 /** How long a run waits for its Side task once its output is written. */
 export const SIDE_TASK_WAIT_MS = 1000;
 export const noSideTask = async () => { };

package/dist/context/side-task.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"side-task.js","sourceRoot":"","sources":["../../src/context/side-task.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAc,MAAM,aAAa,CAAC;AAGhD,yEAAyE;AACzE,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAqBtC,MAAM,CAAC,MAAM,UAAU,GAAmB,KAAK,IAAI,EAAE,GAAE,CAAC,CAAC;AAEzD,SAAS,QAAQ;IACf,OAAO,IAAI,YAAY,CACrB,8BAA8B,iBAAiB,UAAU,EACzD,cAAc,CACf,CAAC;AACJ,CAAC;AAQD,MAAM,UAAU,aAAa,CAC3B,QAA8B,EAC9B,OAA6C,EAC7C,EAAE,KAAK,EAAE,MAAM,EAAmB;IAElC,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC;IAC9C,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC;IAC9B,iGAAiG;IACjG,kFAAkF;IAClF,MAAM,OAAO,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QACjF,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,IAAI,KAAK,KAAK,MAAM,CAAC,MAAM,CAAC;YAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IAClE,CAAC,CAAC,CAAC;IACH,OAAO,KAAK,IAAI,EAAE;QAChB,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAC3C,KAAK,CAAC,KAAK,EAAE,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,EAAE;YAClD,MAAM,IAAI,GAAG,QAAQ,EAAE,CAAC;YACxB,MAAM,CAAC,IAAI,CAAC,CAAC;YACb,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACvB,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC,CACH,CAAC;QACF,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;QACtC,MAAM,CAAC,KAAK,EAAE,CAAC;IACjB,CAAC,CAAC;AACJ,CAAC"}

package/dist/{spawn.d.ts → context/spawn.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";
 import type { FileError } from "./errno.js";
 export declare const TOOL_FAILED = "TOOL_FAILED";
 export interface SpawnResult {
@@ -73,8 +74,8 @@ export declare const realSpawn: Spawn;
 /** `ctx.spawn`: `spawn` bound to the run, its start failures classified by errno. */
 interface SpawnScope {
     readonly fileError: FileError;
-    /** The caller's command line, ready to paste, that a missing program's hint asks to run again. */
-    readonly callerLine: string;
+    /** The caller's own line, the Next step once a missing program is installed. */
+    readonly rerun: Rerun;
 }
 export declare function contextSpawn(run: Spawn, defaults: {
     readonly cwd: string;

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

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import { constants } from "node:os";
-import { CliError, isMissingFile } from "./errors.js";
-import { lastLines } from "./tail.js";
+import { CliError, isMissingFile } from "../errors.js";
+import { lastLines } from "../tail.js";
 import { findTool, TOOL_MISSING } from "./tools.js";
 export const TOOL_FAILED = "TOOL_FAILED";
 const STDERR_TAIL_LINES = 20;
@@ -239,16 +239,17 @@ function failedError(command, { exitCode, stderr }) {
         hint: `the output of ${command} above says why it failed`,
     });
 }
-function missingError(command, callerLine, cause) {
+function missingError(command, rerun, cause) {
     return new CliError({
         code: TOOL_MISSING,
         message: `${command} could not be started: it is not on PATH`,
-        hint: `install ${command}, then run \`${callerLine}\` again`,
+        hint: `install ${command}, then run the Next step`,
+        next: [rerun],
     }, { cause });
 }
-function startError(command, error, { fileError, callerLine }) {
+function startError(command, error, { fileError, rerun }) {
     if (isMissingFile(error))
-        return missingError(command, callerLine, error);
+        return missingError(command, rerun, error);
     return fileError(error, { path: command, access: "read" });
 }
 async function* reported(stream, onError) {

package/dist/context/spawn.js.map

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

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

@@ -1,10 +1,11 @@
-import type { Clock } from "./clock.js";
-import type { Env } from "./context.js";
+import type { Clock } from "../clock.js";
+import type { Env } from "../context.js";
 import type { FileError } from "./errno.js";
 import type { Files } from "./files.js";
 export interface SpillTarget {
     readonly cliName: string;
-    readonly commandName: string;
+    /** The Command's label, joined with `-` in the file name. */
+    readonly label: readonly string[];
     readonly env: Env;
     readonly clock: Clock;
     /** Writes the spill file; its failures are already classified. */

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

@@ -1,15 +1,15 @@
 import { mkdir, readdir, rm, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { isMissingFile } from "./errors.js";
+import { isMissingFile } from "../errors.js";
 const STDOUT_BUDGET_CHARS = 30_000;
 const SPILL_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
 const PREVIEW_CHARS = 2_000;
 // The time's colons become dashes: Windows forbids a colon in a file name.
 const SPILL_FILE = /^\d{4}-\d\d-\d\dT\d\d-\d\d-\d\d\.\d{3}Z-.+\.(json|txt)$/;
-function spillName(now, commandName, json) {
+function spillName(now, label, json) {
     const time = new Date(now).toISOString().replaceAll(":", "-");
-    return `${time}-${commandName}.${json ? "json" : "txt"}`;
+    return `${time}-${label.join("-")}.${json ? "json" : "txt"}`;
 }
 // Another run pruning the same folder may remove a file between readdir and stat.
 async function pruneOne(path, cutoff) {
@@ -47,7 +47,7 @@ export function spillTo(target) {
         const now = target.clock.now();
         const folder = join(tempRoot(target.env), target.cliName);
         await prepare(folder, now - SPILL_RETENTION_MS, target);
-        const file = join(folder, spillName(now, target.commandName, json));
+        const file = join(folder, spillName(now, target.label, json));
         await target.files.write(file, printed);
         const bytes = Buffer.byteLength(printed);
         const preview = printed.slice(0, PREVIEW_CHARS);

package/dist/context/spill.js.map

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

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

@@ -1,7 +1,7 @@
 import type { Readable } from "node:stream";
 import * as z from "zod";
-import { type Clock } from "./clock.js";
-import { CliError } from "./errors.js";
+import { type Clock } from "../clock.js";
+import { CliError } from "../errors.js";
 export declare const STDIN_OPERAND = "-";
 /**
  * Marks a string arg as also taking its text from stdin when the caller passes `-`: all of stdin as

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

@@ -1,6 +1,6 @@
 import * as z from "zod";
-import { after } from "./clock.js";
-import { CliError } from "./errors.js";
+import { after } from "../clock.js";
+import { CliError } from "../errors.js";
 export const STDIN_OPERAND = "-";
 const STDIN_META = "stdin";
 /**