@duyquangnvx/agent-cli 0.4.0 → 0.6.0

package/dist/built-ins/semver.js.map

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

package/dist/built-ins/skills.d.ts

@@ -0,0 +1,18 @@
+import type { Context } from "../context.js";
+import type { CommandTreeCli } from "../define.js";
+import { type Standing } from "./semver.js";
+export type SkillState = Standing | "unversioned" | "unreadable";
+export interface SkillCopy {
+    readonly path: string;
+    readonly version: string | undefined;
+    readonly state: SkillState;
+}
+type SkillCli = Pick<CommandTreeCli, "name" | "skill">;
+type SkillPlace = Pick<Context, "cwd" | "env" | "packageRoot">;
+export interface SkillReport {
+    readonly copies: readonly SkillCopy[];
+    /** The command line that brings every copy to the version, when one can. */
+    readonly fix: string | undefined;
+}
+export declare function skillReport(cli: SkillCli, version: string, ctx: SkillPlace): Promise<SkillReport>;
+export {};

package/dist/built-ins/skills.js

@@ -0,0 +1,97 @@
+import { readFile, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { isMissingFile } from "../errors.js";
+import { manifestAt } from "../manifest.js";
+import { isVersion, standingOf } from "./semver.js";
+// Everything here mirrors how the skills@1.7.2 installer (`npx skills`) behaves.
+const SKILL_DIRS = [
+    [".claude", "skills"],
+    [".agents", "skills"],
+];
+/** The branch a release moves to the released commit, which holds the skill of that version. */
+const RELEASE_BRANCH = "release";
+// npm's `owner/repo`, `github:owner/repo` and `gitlab:group/repo`, the shorthands the installer also reads.
+const SHORTHAND = /^(?:(?:github:)?[\w.-]+\/[\w.-]+|gitlab:[\w.-]+(?:\/[\w.-]+)+)$/;
+const GIT_URL_PROTOCOLS = new Set(["https:", "http:", "ssh:", "git:"]);
+const SCP_STYLE = /^[\w.-]+@[\w.-]+:[\w./-]+$/;
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---/;
+const METADATA_VERSION = /^metadata:[ \t]*\r?\n(?:[ \t]+.*\r?\n)*?[ \t]+version:[ \t]*["']?([^"'\s]+)["']?[ \t]*$/m;
+/** The version a SKILL.md's frontmatter `metadata.version` states. */
+function skillVersionIn(skill) {
+    const frontmatter = FRONTMATTER.exec(skill)?.[1];
+    return frontmatter === undefined ? undefined : METADATA_VERSION.exec(`${frontmatter}\n`)?.[1];
+}
+function homeOf(env) {
+    return env.HOME ?? env.USERPROFILE ?? homedir();
+}
+async function copyAt(path, version) {
+    let skill;
+    try {
+        skill = await readFile(join(path, "SKILL.md"), "utf8");
+    }
+    catch (error) {
+        if (isMissingFile(error)) {
+            return undefined;
+        }
+        return { path, version: undefined, state: "unreadable" };
+    }
+    const stated = skillVersionIn(skill);
+    if (stated === undefined || !isVersion(stated) || !isVersion(version)) {
+        return { path, version: stated, state: "unversioned" };
+    }
+    return { path, version: stated, state: standingOf(stated, version) };
+}
+async function skillCopies(cliName, version, { cwd, env }) {
+    const roots = [cwd, homeOf(env)];
+    const paths = roots.flatMap((root) => SKILL_DIRS.map((dir) => join(root, ...dir, cliName)));
+    const seen = new Set();
+    const copies = [];
+    for (const path of paths) {
+        const copy = await copyAt(path, version);
+        // The project may be home itself, or one skill dir a link to the other.
+        const real = copy === undefined ? undefined : await realpath(path);
+        if (copy !== undefined && real !== undefined && !seen.has(real)) {
+            seen.add(real);
+            copies.push(copy);
+        }
+    }
+    return copies;
+}
+// The installer clones a non-GitHub source only when it ends in `.git`, and takes the branch from `#ref`.
+function sourceFromRepository(repository) {
+    if (SHORTHAND.test(repository))
+        return `${repository}#${RELEASE_BRANCH}`;
+    const url = repository.replace(/^git\+/, "");
+    const isGitUrl = URL.canParse(url) && GIT_URL_PROTOCOLS.has(new URL(url).protocol);
+    if (!isGitUrl && !SCP_STYLE.test(url))
+        return undefined;
+    return `${url.endsWith(".git") ? url : `${url}.git`}#${RELEASE_BRANCH}`;
+}
+/** What the installer installs the CLI's skill from: the declared source, else the package's repository. */
+function skillSource({ skill }, packageRoot) {
+    if (skill !== undefined)
+        return skill.source;
+    const { repository } = manifestAt(packageRoot);
+    return repository === undefined ? undefined : sourceFromRepository(repository);
+}
+// `skills update` skips a copy it did not install, which is how most unversioned copies got there.
+// A copy ahead gets no fix: doctor's registry row already says when the CLI itself is behind.
+function fixFor(cliName, copies, source) {
+    const has = (wanted) => copies.some(({ state }) => state === wanted);
+    const update = `npx -y skills update ${cliName}`;
+    // `--skill` installs only this CLI's skill from a repo that holds several.
+    const add = source === undefined ? undefined : `npx -y skills add ${source} --skill ${cliName} -g`;
+    if (copies.length === 0) {
+        return add;
+    }
+    if (has("unversioned") && add !== undefined) {
+        return has("behind") ? `${update} && ${add}` : add;
+    }
+    return has("behind") || has("unversioned") ? update : undefined;
+}
+export async function skillReport(cli, version, ctx) {
+    const copies = await skillCopies(cli.name, version, ctx);
+    return { copies, fix: fixFor(cli.name, copies, skillSource(cli, ctx.packageRoot)) };
+}
+//# sourceMappingURL=skills.js.map

package/dist/built-ins/skills.js.map

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

package/dist/{update.d.ts → built-ins/update.d.ts}

@@ -1,3 +1,4 @@
-import { type Command, type CommandTreeCli, type GlobalInstall } from "./define.js";
+import { type Command, type CommandTreeCli, type GlobalInstall } from "../define.js";
+import type { Launch } from "./commands.js";
 /** The built-in `update`, for a CLI installed globally with npm. */
-export declare function updateCommand(cli: CommandTreeCli, install: GlobalInstall, bin: string | undefined): Command;
+export declare function updateCommand(cli: CommandTreeCli, install: GlobalInstall, { bin, node }: Launch): Command;

package/dist/{update.js → built-ins/update.js}

@@ -1,11 +1,11 @@
 import * as z from "zod";
-import { defineCommand } from "./define.js";
-import { CliError } from "./errors.js";
+import { defineCommand } from "../define.js";
+import { CliError } from "../errors.js";
+import { INTERRUPTED } from "../interrupts.js";
 import { globalInstallOf } from "./global-install.js";
-import { INTERRUPTED } from "./interrupts.js";
 import { installGlobally, latestVersion, npmContext } from "./npm.js";
 import { standingOf } from "./semver.js";
-import { skillUpdateCommand } from "./skills.js";
+import { skillReport } from "./skills.js";
 import { upgradeNotes } from "./upgrade-notes.js";
 const updateSchema = z.object({
     from: z.string(),
@@ -21,15 +21,19 @@ function nothingToInstall({ from, latest }) {
 }
 function renderUpdate(cli, install, update) {
     const { installed } = update;
-    if (installed === null) {
-        return nothingToInstall(update);
-    }
-    return [
-        `installed ${install.package}@${installed.version} with the npm under ${installed.prefix}, replacing ${update.from}`,
-        ...update.upgrades.map(({ version, notes }) => `\nchanges in ${version}:\n${notes}`),
-        "",
-        ...update.next.map((command) => `next: ${command}, so the ${cli.name} skill describes ${installed.version}`),
-    ].join("\n");
+    const head = installed === null
+        ? [nothingToInstall(update)]
+        : [
+            `installed ${install.package}@${installed.version} with the npm under ${installed.prefix}, replacing ${update.from}`,
+            ...update.upgrades.map(({ version, notes }) => `\nchanges in ${version}:\n${notes}`),
+        ];
+    const next = update.next.map((command) => `next: ${command}, so the ${cli.name} skill describes ${update.latest}`);
+    return (next.length === 0 ? head : [...head, "", ...next]).join("\n");
+}
+// Compared with the latest release even when nothing was installed: its skill is what the installer gives.
+async function skillNext(cli, latest, ctx) {
+    const { fix } = await skillReport(cli, latest, ctx);
+    return fix === undefined ? [] : [fix];
 }
 // The install ran to its end, so the run reports it rather than asking for a rerun.
 function interruptedAfterInstall(plan) {
@@ -40,7 +44,7 @@ function interruptedAfterInstall(plan) {
     });
 }
 /** The built-in `update`, for a CLI installed globally with npm. */
-export function updateCommand(cli, install, bin) {
+export function updateCommand(cli, install, { bin, node }) {
     return defineCommand({
         name: "update",
         description: "install the latest version of this CLI from its registry",
@@ -51,7 +55,7 @@ export function updateCommand(cli, install, bin) {
         effect: "write",
         output: updateSchema,
         plan: async (_input, ctx) => {
-            const npm = npmContext(cli, install, ctx);
+            const npm = npmContext(cli, install, ctx, node);
             const copy = await globalInstallOf(bin, npm);
             return {
                 package: install.package,
@@ -64,17 +68,23 @@ export function updateCommand(cli, install, bin) {
         apply: async (plan, ctx) => {
             const { from, latest, prefix } = plan;
             if (standingOf(from, latest) !== "behind") {
-                return { from, latest, installed: null, upgrades: [], next: [] };
+                return {
+                    from,
+                    latest,
+                    installed: null,
+                    upgrades: [],
+                    next: await skillNext(cli, latest, ctx),
+                };
             }
             ctx.signal.throwIfAborted();
             ctx.progress(`installing ${plan.package}@${latest} with the npm under ${prefix}…`);
-            await ctx.runToEnd(`installing ${plan.package}@${latest}`, () => installGlobally(latest, npmContext(cli, install, ctx)));
+            await ctx.runToEnd(`installing ${plan.package}@${latest}`, () => installGlobally(latest, npmContext(cli, install, ctx, node)));
             const update = {
                 from,
                 latest,
                 installed: { version: latest, prefix },
                 upgrades: await upgradeNotes(plan.packageDir, from, latest),
-                next: [skillUpdateCommand(cli.name)],
+                next: await skillNext(cli, latest, ctx),
             };
             if (ctx.signal.aborted) {
                 ctx.deliver(update);

package/dist/built-ins/update.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update.js","sourceRoot":"","sources":["../../src/built-ins/update.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,OAAO,EAAqC,aAAa,EAAsB,MAAM,cAAc,CAAC;AACpG,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,QAAQ,EAAE;IAC3E,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACvE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;CAC1B,CAAC,CAAC;AAYH,SAAS,gBAAgB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAoC;IAC1E,OAAO,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,SAAS;QAC3C,CAAC,CAAC,cAAc,IAAI,0CAA0C;QAC9D,CAAC,CAAC,GAAG,IAAI,qCAAqC,MAAM,sBAAsB,CAAC;AAC/E,CAAC;AAED,SAAS,YAAY,CAAC,GAAmB,EAAE,OAAsB,EAAE,MAAc;IAC/E,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC;IAC7B,MAAM,IAAI,GACR,SAAS,KAAK,IAAI;QAChB,CAAC,CAAC,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAC5B,CAAC,CAAC;YACE,aAAa,OAAO,CAAC,OAAO,IAAI,SAAS,CAAC,OAAO,uBAAuB,SAAS,CAAC,MAAM,eAAe,MAAM,CAAC,IAAI,EAAE;YACpH,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,gBAAgB,OAAO,MAAM,KAAK,EAAE,CAAC;SACrF,CAAC;IACR,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAC1B,CAAC,OAAO,EAAE,EAAE,CAAC,SAAS,OAAO,YAAY,GAAG,CAAC,IAAI,oBAAoB,MAAM,CAAC,MAAM,EAAE,CACrF,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACxE,CAAC;AAED,2GAA2G;AAC3G,KAAK,UAAU,SAAS,CAAC,GAAmB,EAAE,MAAc,EAAE,GAAY;IACxE,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IACpD,OAAO,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AACxC,CAAC;AAED,oFAAoF;AACpF,SAAS,uBAAuB,CAAC,IAAgB;IAC/C,OAAO,IAAI,QAAQ,CAAC;QAClB,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,oBAAoB,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,MAAM,kDAAkD,IAAI,CAAC,MAAM,eAAe,IAAI,CAAC,IAAI,EAAE;QAC/I,IAAI,EAAE,mDAAmD;KAC1D,CAAC,CAAC;AACL,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,aAAa,CAC3B,GAAmB,EACnB,OAAsB,EACtB,EAAE,GAAG,EAAE,IAAI,EAAU;IAErB,OAAO,aAAa,CAAC;QACnB,IAAI,EAAE,QAAQ;QACd,WAAW,EAAE,0DAA0D;QACvE,QAAQ,EAAE;YACR,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC,IAAI,SAAS,EAAE,IAAI,EAAE,kDAAkD,EAAE;YAC3F,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC,IAAI,mBAAmB,EAAE,IAAI,EAAE,mCAAmC,EAAE;SACvF;QACD,MAAM,EAAE,OAAO;QACf,MAAM,EAAE,YAAY;QACpB,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAuB,EAAE;YAC/C,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;YAChD,MAAM,IAAI,GAAG,MAAM,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YAC7C,OAAO;gBACL,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,IAAI,EAAE,GAAG,CAAC,OAAO;gBACjB,MAAM,EAAE,MAAM,aAAa,CAAC,GAAG,CAAC;gBAChC,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,UAAU,EAAE,IAAI,CAAC,UAAU;aAC5B,CAAC;QACJ,CAAC;QACD,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAmB,EAAE;YAC1C,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;YACtC,IAAI,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,QAAQ,EAAE,CAAC;gBAC1C,OAAO;oBACL,IAAI;oBACJ,MAAM;oBACN,SAAS,EAAE,IAAI;oBACf,QAAQ,EAAE,EAAE;oBACZ,IAAI,EAAE,MAAM,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC;iBACxC,CAAC;YACJ,CAAC;YACD,GAAG,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;YAC5B,GAAG,CAAC,QAAQ,CAAC,cAAc,IAAI,CAAC,OAAO,IAAI,MAAM,uBAAuB,MAAM,GAAG,CAAC,CAAC;YACnF,MAAM,GAAG,CAAC,QAAQ,CAAC,cAAc,IAAI,CAAC,OAAO,IAAI,MAAM,EAAE,EAAE,GAAG,EAAE,CAC9D,eAAe,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAC7D,CAAC;YACF,MAAM,MAAM,GAAW;gBACrB,IAAI;gBACJ,MAAM;gBACN,SAAS,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE;gBACtC,QAAQ,EAAE,MAAM,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,EAAE,MAAM,CAAC;gBAC3D,IAAI,EAAE,MAAM,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC;aACxC,CAAC;YACF,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBACvB,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;gBACpB,MAAM,uBAAuB,CAAC,IAAI,CAAC,CAAC;YACtC,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC;QACtD,UAAU,EAAE,CAAC,IAAI,EAAE,EAAE,CACnB,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,QAAQ;YAC7C,CAAC,CAAC,iBAAiB,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,MAAM,uBAAuB,IAAI,CAAC,MAAM,eAAe,IAAI,CAAC,IAAI,EAAE;YAC1G,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC;KAC7B,CAAC,CAAC;AACL,CAAC"}

package/dist/{upgrade-notes.js → built-ins/upgrade-notes.js}

@@ -1,6 +1,6 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { isMissingFile } from "./errors.js";
+import { isMissingFile } from "../errors.js";
 import { compareVersions, isVersion } from "./semver.js";
 const RELEASE_HEADING = /^## v?(\S+)/;
 function releasesIn(changelog) {

package/dist/built-ins/upgrade-notes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade-notes.js","sourceRoot":"","sources":["../../src/built-ins/upgrade-notes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAOzD,MAAM,eAAe,GAAG,aAAa,CAAC;AAEtC,SAAS,UAAU,CAAC,SAAiB;IACnC,MAAM,QAAQ,GAA2C,EAAE,CAAC;IAC5D,IAAI,OAAyD,CAAC;IAC9D,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5C,MAAM,OAAO,GAAG,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3C,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YACjC,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;YAClE,IAAI,OAAO,KAAK,SAAS;gBAAE,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpD,CAAC;aAAM,CAAC;YACN,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;AAC7F,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,UAAkB,EAClB,IAAY,EACZ,EAAU;IAEV,IAAI,SAAiB,CAAC;IACtB,IAAI,CAAC;QACH,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,UAAU,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAC;IACvE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,aAAa,CAAC,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QACpC,MAAM,KAAK,CAAC;IACd,CAAC;IACD,OAAO,UAAU,CAAC,SAAS,CAAC;SACzB,MAAM,CACL,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,eAAe,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,eAAe,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,CACzF;SACA,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/dist/clock.d.ts

@@ -1,5 +1,6 @@
 /** Time as the Runtime sees it; a test replaces it through `runCli` to run every wait instantly. */
 export interface Clock {
+    /** Milliseconds since the Unix epoch, as `Date.now()`. */
     now(): number;
     /** Resolves after `ms`, or rejects with the signal's reason once it aborts. */
     sleep(ms: number, signal?: AbortSignal): Promise<void>;

package/dist/clock.js.map

@@ -1 +1 @@
-{"version":3,"file":"clock.js","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":"AAOA,MAAM,CAAC,MAAM,SAAS,GAAU;IAC9B,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;IACrB,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,CACpB,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC9B,IAAI,MAAM,EAAE,OAAO,KAAK,IAAI,EAAE,CAAC;YAC7B,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACtB,OAAO;QACT,CAAC;QACD,MAAM,OAAO,GAAG,GAAS,EAAE;YACzB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACzB,CAAC,CAAC;QACF,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC9C,OAAO,EAAE,CAAC;QACZ,CAAC,EAAE,EAAE,CAAC,CAAC;QACP,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC,CAAC;CACL,CAAC;AAEF,gFAAgF;AAChF,MAAM,UAAU,KAAK,CAAC,KAAY,EAAE,EAAU,EAAE,MAAmB,EAAE,IAAgB;IACnF,KAAK,CAAC,KAAK,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,KAAc,EAAE,EAAE;QACpD,IAAI,CAAC,MAAM,CAAC,OAAO;YAAE,MAAM,KAAK,CAAC;IACnC,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,KAAY,EACZ,KAAmD,EACnD,UAAkB,EAClB,MAAmB;IAEnB,SAAS,CAAC;QACR,MAAM,CAAC,cAAc,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,MAAM,KAAK,EAAE,CAAC;QAC5B,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QACtC,MAAM,KAAK,CAAC,KAAK,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;AACH,CAAC"}
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":"AAQA,MAAM,CAAC,MAAM,SAAS,GAAU;IAC9B,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;IACrB,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,CACpB,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC9B,IAAI,MAAM,EAAE,OAAO,KAAK,IAAI,EAAE,CAAC;YAC7B,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACtB,OAAO;QACT,CAAC;QACD,MAAM,OAAO,GAAG,GAAS,EAAE;YACzB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACzB,CAAC,CAAC;QACF,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC9C,OAAO,EAAE,CAAC;QACZ,CAAC,EAAE,EAAE,CAAC,CAAC;QACP,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC,CAAC;CACL,CAAC;AAEF,gFAAgF;AAChF,MAAM,UAAU,KAAK,CAAC,KAAY,EAAE,EAAU,EAAE,MAAmB,EAAE,IAAgB;IACnF,KAAK,CAAC,KAAK,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,KAAc,EAAE,EAAE;QACpD,IAAI,CAAC,MAAM,CAAC,OAAO;YAAE,MAAM,KAAK,CAAC;IACnC,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,KAAY,EACZ,KAAmD,EACnD,UAAkB,EAClB,MAAmB;IAEnB,SAAS,CAAC;QACR,MAAM,CAAC,cAAc,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,MAAM,KAAK,EAAE,CAAC;QAC5B,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QACtC,MAAM,KAAK,CAAC,KAAK,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;AACH,CAAC"}

package/dist/command-spec.d.ts

@@ -7,8 +7,15 @@ import { type ListSpec } from "./list.js";
 export interface CommandSpec {
     readonly kind: "command";
     readonly commandLine: string;
+    /** The keys that lead from the root to the Command; empty for a single-Command CLI. */
+    readonly path: readonly string[];
     readonly command: Command;
+    /** Whether the Runtime added it, as `doctor`. */
+    readonly builtIn: boolean;
     readonly description: string;
+    readonly help: string | undefined;
+    readonly hidden: boolean;
+    readonly operator: boolean;
     readonly effect: Command["effect"];
     readonly examples: readonly Example[];
     readonly args: readonly InputField[];
@@ -24,5 +31,13 @@ export interface GroupSpec {
     readonly commands: Readonly<Record<string, SpecNode>>;
 }
 export type SpecNode = CommandSpec | GroupSpec;
-export declare function commandSpec(commandLine: string, command: Command): CommandSpec;
-export declare function groupSpec(commandLine: string, commands: Commands): 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>>;
+interface SpecPlace {
+    readonly path: readonly string[];
+    readonly builtIn: boolean;
+}
+export declare function commandSpec(commandLine: string, command: Command, { path, builtIn }?: 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 {};

package/dist/command-spec.js

@@ -3,6 +3,10 @@ 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));
+}
 function declaredOf(command) {
     if (!hasPlan(command)) {
         return { outputs: false, force: undefined, cost: false };
@@ -13,13 +17,19 @@ function declaredOf(command) {
         cost: command.cost !== undefined,
     };
 }
-export function commandSpec(commandLine, command) {
+const SINGLE_COMMAND = { path: [], builtIn: false };
+export function commandSpec(commandLine, command, { path, builtIn } = SINGLE_COMMAND) {
     const list = command.rows === undefined ? undefined : listSpec(command.rows);
     return {
         kind: "command",
         commandLine,
+        path,
         command,
+        builtIn,
         description: command.description,
+        help: command.help,
+        hidden: command.hidden === true,
+        operator: command.operator === true,
         effect: command.effect,
         examples: command.examples,
         args: argFields(command.args),
@@ -29,14 +39,25 @@ export function commandSpec(commandLine, command) {
         output: list?.output ?? command.output,
     };
 }
-export function groupSpec(commandLine, commands) {
-    return {
-        kind: "group",
-        commandLine,
-        commands: Object.fromEntries(Object.entries(commands).map(([key, node]) => [key, specOf(`${commandLine} ${key}`, node)])),
-    };
+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 }),
+    });
+}
+function specsOf(commandLine, commands, { path, builtIn }) {
+    return Object.fromEntries(Object.entries(commands).map(([key, node]) => [
+        key,
+        specOf(`${commandLine} ${key}`, node, { path: [...path, key], builtIn }),
+    ]));
 }
-function specOf(commandLine, node) {
-    return isCommand(node) ? commandSpec(commandLine, node) : groupSpec(commandLine, node);
+function specOf(commandLine, node, place) {
+    return isCommand(node)
+        ? commandSpec(commandLine, node, place)
+        : group(commandLine, specsOf(commandLine, node, place));
 }
 //# sourceMappingURL=command-spec.js.map

package/dist/command-spec.js.map

@@ -1 +1 @@
-{"version":3,"file":"command-spec.js","sourceRoot":"","sources":["../src/command-spec.ts"],"names":[],"mappings":"AACA,OAAO,EAA6C,SAAS,EAAE,MAAM,aAAa,CAAC;AACnF,OAAO,EAAoC,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAChF,OAAO,EAAE,SAAS,EAAmB,YAAY,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAiB,QAAQ,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AA0BvC,SAAS,UAAU,CAAC,OAAgB;IAClC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAC3D,CAAC;IACD,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,OAAO,KAAK,SAAS;QACtC,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,IAAI,EAAE,OAAO,CAAC,IAAI,KAAK,SAAS;KACjC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,WAAmB,EAAE,OAAgB;IAC/D,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E,OAAO;QACL,IAAI,EAAE,SAAS;QACf,WAAW;QACX,OAAO;QACP,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,IAAI,EAAE,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC;QAC7B,OAAO,EAAE,YAAY,CAAC,OAAO,CAAC,OAAO,CAAC;QACtC,aAAa,EAAE,gBAAgB,CAAC,OAAO,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC;QAC1E,IAAI;QACJ,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,OAAO,CAAC,MAAM;KACvC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,WAAmB,EAAE,QAAkB;IAC/D,OAAO;QACL,IAAI,EAAE,OAAO;QACb,WAAW;QACX,QAAQ,EAAE,MAAM,CAAC,WAAW,CAC1B,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,WAAW,IAAI,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,CAC5F;KACF,CAAC;AACJ,CAAC;AAED,SAAS,MAAM,CAAC,WAAmB,EAAE,IAAwB;IAC3D,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;AACzF,CAAC"}
+{"version":3,"file":"command-spec.js","sourceRoot":"","sources":["../src/command-spec.ts"],"names":[],"mappings":"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"}

package/dist/confirm.js

@@ -1,13 +1,17 @@
 import { UsageError } from "./errors.js";
 import { CONFIRM_FLAG } from "./flags.js";
-import { commandLineWith } from "./invocation.js";
+import { commandLineOf } from "./invocation.js";
 export const CONFIRMATION_REQUIRED = "CONFIRMATION_REQUIRED";
 export const CONFIRMATION_MISMATCH = "CONFIRMATION_MISMATCH";
 export function checkConfirmation({ invocation, commandLine, given }, expected) {
     if (given === expected) {
         return;
     }
-    const hint = `to confirm, run \`${commandLineWith(invocation, CONFIRM_FLAG.flag, expected)}\``;
+    const confirmed = commandLineOf(invocation, {
+        remove: [CONFIRM_FLAG.flag],
+        add: [CONFIRM_FLAG.flag, expected],
+    });
+    const hint = `to confirm, run \`${confirmed}\``;
     if (given === undefined) {
         throw new UsageError({
             code: CONFIRMATION_REQUIRED,

package/dist/confirm.js.map

@@ -1 +1 @@
-{"version":3,"file":"confirm.js","sourceRoot":"","sources":["../src/confirm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAmB,MAAM,iBAAiB,CAAC;AAEnE,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAuB,CAAC;AAC7D,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAuB,CAAC;AAQ7D,MAAM,UAAU,iBAAiB,CAC/B,EAAE,UAAU,EAAE,WAAW,EAAE,KAAK,EAAgB,EAChD,QAAgB;IAEhB,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvB,OAAO;IACT,CAAC;IACD,MAAM,IAAI,GAAG,qBAAqB,eAAe,CAAC,UAAU,EAAE,YAAY,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC;IAC/F,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,IAAI;SACL,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,IAAI;KACL,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"confirm.js","sourceRoot":"","sources":["../src/confirm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAmB,MAAM,iBAAiB,CAAC;AAEjE,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAuB,CAAC;AAC7D,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAuB,CAAC;AAQ7D,MAAM,UAAU,iBAAiB,CAC/B,EAAE,UAAU,EAAE,WAAW,EAAE,KAAK,EAAgB,EAChD,QAAgB;IAEhB,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvB,OAAO;IACT,CAAC;IACD,MAAM,SAAS,GAAG,aAAa,CAAC,UAAU,EAAE;QAC1C,MAAM,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC;QAC3B,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,QAAQ,CAAC;KACnC,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,qBAAqB,SAAS,IAAI,CAAC;IAChD,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,IAAI;SACL,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,IAAI;KACL,CAAC,CAAC;AACL,CAAC"}

package/dist/context.d.ts

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

package/dist/context.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":""}

package/dist/cost.js

@@ -1,6 +1,6 @@
 import { CliError } from "./errors.js";
 import { YES_FLAG } from "./flags.js";
-import { commandLineWith } from "./invocation.js";
+import { commandLineOf } from "./invocation.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({ invocation, commandLine, yes }, cost) {
@@ -10,7 +10,7 @@ export function checkCost({ invocation, commandLine, yes }, cost) {
     throw new CliError({
         code: NOT_CONFIRMED,
         message: `\`${commandLine}\` needs ${YES_FLAG.flag}: ${cost}`,
-        hint: `to approve the cost, run \`${commandLineWith(invocation, YES_FLAG.flag)}\``,
+        hint: `to approve the cost, run \`${commandLineOf(invocation, { add: [YES_FLAG.flag] })}\``,
     });
 }
 //# sourceMappingURL=cost.js.map

package/dist/cost.js.map

@@ -1 +1 @@
-{"version":3,"file":"cost.js","sourceRoot":"","sources":["../src/cost.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,eAAe,EAAmB,MAAM,iBAAiB,CAAC;AAEnE,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC;AAQ7C,uFAAuF;AACvF,MAAM,UAAU,SAAS,CACvB,EAAE,UAAU,EAAE,WAAW,EAAE,GAAG,EAAY,EAC1C,IAAwB;IAExB,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,8BAA8B,eAAe,CAAC,UAAU,EAAE,QAAQ,CAAC,IAAI,CAAC,IAAI;KACnF,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"cost.js","sourceRoot":"","sources":["../src/cost.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,aAAa,EAAmB,MAAM,iBAAiB,CAAC;AAEjE,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC;AAQ7C,uFAAuF;AACvF,MAAM,UAAU,SAAS,CACvB,EAAE,UAAU,EAAE,WAAW,EAAE,GAAG,EAAY,EAC1C,IAAwB;IAExB,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,8BAA8B,aAAa,CAAC,UAAU,EAAE,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI;KAC5F,CAAC,CAAC;AACL,CAAC"}