@duyquangnvx/agent-cli 0.0.0-stage → 0.2.0

package/dist/interrupts.js

@@ -0,0 +1,118 @@
+import { CliError } from "./errors.js";
+/** 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");
+export const INTERRUPTED = "INTERRUPTED";
+function interruptedError() {
+    return new CliError({
+        code: INTERRUPTED,
+        message: "interrupted before it finished",
+        hint: "run the command again",
+        retryable: true,
+    });
+}
+function deadlineError(commandLine, ms) {
+    return new CliError({
+        code: "DEADLINE_EXCEEDED",
+        message: `${commandLine} ran past its ${ms} ms deadline`,
+        hint: "run it again later, when the service it waits on may answer faster",
+        retryable: true,
+    });
+}
+/** One Command run's cancellation: its signal, its deadlines and the steps it must finish. */
+export class RunControl {
+    signal;
+    #controller = new AbortController();
+    #commandLine;
+    #outer;
+    #onOuterAbort = () => this.#controller.abort(interruptedError());
+    #steps = new Set();
+    #deadlineTimers = new Set();
+    #deadlineHit;
+    #graceTimer;
+    #endGrace = () => { };
+    #graceOver = new Promise((resolve) => {
+        this.#endGrace = resolve;
+    });
+    constructor(commandLine, outer) {
+        this.#commandLine = commandLine;
+        this.#outer = outer;
+        this.signal = this.#controller.signal;
+        this.signal.addEventListener("abort", () => this.#startGrace(), { once: true });
+        if (outer?.aborted === true) {
+            this.#onOuterAbort();
+        }
+        else {
+            outer?.addEventListener("abort", this.#onOuterAbort, { once: true });
+        }
+    }
+    deadline(ms) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => {
+            this.#deadlineHit ??= deadlineError(this.#commandLine, ms);
+            controller.abort(this.#deadlineHit);
+        }, ms);
+        this.#deadlineTimers.add(timer);
+        return AbortSignal.any([this.signal, controller.signal]);
+    }
+    async runToEnd(work) {
+        clearTimeout(this.#graceTimer);
+        const step = work();
+        // Only tracks when the step settles; the step's own error reaches the caller below.
+        const settled = step.then(() => { }, () => { });
+        this.#steps.add(settled);
+        try {
+            return await step;
+        }
+        finally {
+            this.#steps.delete(settled);
+            this.#startGrace();
+        }
+    }
+    /** Waits for the Command, its must-finish steps, and no longer than the grace once interrupted. */
+    async settle(work) {
+        try {
+            const value = await Promise.race([work, this.#graceOver]);
+            if (this.signal.aborted || value === GRACE_OVER) {
+                throw this.signal.reason;
+            }
+            return value;
+        }
+        finally {
+            await this.#stepsDone();
+            this.#dispose();
+        }
+    }
+    /**
+     * The error a run ends with: an interrupt or a missed deadline outranks what the Command threw,
+     * unless the Command threw its own `INTERRUPTED`, saying what it finished before it stopped.
+     */
+    errorAfter(error) {
+        if (this.signal.aborted) {
+            return error instanceof CliError && error.code === INTERRUPTED ? error : this.signal.reason;
+        }
+        if (this.#deadlineHit !== undefined && !(error instanceof CliError)) {
+            return this.#deadlineHit;
+        }
+        return error;
+    }
+    #startGrace() {
+        if (this.signal.aborted && this.#steps.size === 0) {
+            clearTimeout(this.#graceTimer);
+            this.#graceTimer = setTimeout(() => this.#endGrace(GRACE_OVER), GRACE_MS);
+        }
+    }
+    async #stepsDone() {
+        while (this.#steps.size > 0) {
+            await Promise.all(this.#steps);
+        }
+    }
+    #dispose() {
+        clearTimeout(this.#graceTimer);
+        for (const timer of this.#deadlineTimers) {
+            clearTimeout(timer);
+        }
+        this.#outer?.removeEventListener("abort", this.#onOuterAbort);
+    }
+}
+//# sourceMappingURL=interrupts.js.map

package/dist/interrupts.js.map

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

package/dist/invocation.d.ts

@@ -0,0 +1,9 @@
+export declare const END_OF_OPTIONS = "--";
+export interface Invocation {
+    readonly cliName: string;
+    readonly argv: readonly string[];
+}
+/** The caller's command line, ready to paste, with `flag value` replacing any value they gave. */
+export declare function commandLineWith({ cliName, argv }: Invocation, flag: string, value: string): string;
+/** The caller's command line, ready to paste, with each flag in `renames` typed as its new name. */
+export declare function commandLineRenaming({ cliName, argv }: Invocation, renames: ReadonlyMap<string, string>): string;

package/dist/invocation.js

@@ -0,0 +1,37 @@
+export const END_OF_OPTIONS = "--";
+const SHELL_SAFE = /^[\w@%+=:,./-]+$/;
+// POSIX quoting: Agent harnesses run commands in a POSIX shell, Git Bash included on Windows.
+function quoted(token) {
+    return SHELL_SAFE.test(token) ? token : `'${token.replaceAll("'", `'\\''`)}'`;
+}
+function pasteable(cliName, tokens) {
+    return [cliName, ...tokens].map(quoted).join(" ");
+}
+function split(argv) {
+    const end = argv.indexOf(END_OF_OPTIONS);
+    return end === -1
+        ? { options: [...argv], operands: [] }
+        : { options: argv.slice(0, end), operands: argv.slice(end) };
+}
+function without(flag, tokens) {
+    return tokens.filter((token, index) => token !== flag && !token.startsWith(`${flag}=`) && tokens[index - 1] !== flag);
+}
+/** The caller's command line, ready to paste, with `flag value` replacing any value they gave. */
+export function commandLineWith({ cliName, argv }, flag, value) {
+    const { options, operands } = split(argv);
+    return pasteable(cliName, [...without(flag, options), flag, value, ...operands]);
+}
+function renamed(token, renames) {
+    const [flag = token, ...value] = token.split("=");
+    const name = renames.get(flag);
+    if (name === undefined) {
+        return token;
+    }
+    return value.length === 0 ? name : `${name}=${value.join("=")}`;
+}
+/** The caller's command line, ready to paste, with each flag in `renames` typed as its new name. */
+export function commandLineRenaming({ cliName, argv }, renames) {
+    const { options, operands } = split(argv);
+    return pasteable(cliName, [...options.map((token) => renamed(token, renames)), ...operands]);
+}
+//# sourceMappingURL=invocation.js.map

package/dist/invocation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invocation.js","sourceRoot":"","sources":["../src/invocation.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC;AACnC,MAAM,UAAU,GAAG,kBAAkB,CAAC;AAOtC,8FAA8F;AAC9F,SAAS,MAAM,CAAC,KAAa;IAC3B,OAAO,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC;AAChF,CAAC;AAED,SAAS,SAAS,CAAC,OAAe,EAAE,MAAyB;IAC3D,OAAO,CAAC,OAAO,EAAE,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACpD,CAAC;AAED,SAAS,KAAK,CAAC,IAAuB;IACpC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IACzC,OAAO,GAAG,KAAK,CAAC,CAAC;QACf,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE;QACtC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;AACjE,CAAC;AAED,SAAS,OAAO,CAAC,IAAY,EAAE,MAAyB;IACtD,OAAO,MAAM,CAAC,MAAM,CAClB,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,CAChG,CAAC;AACJ,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,eAAe,CAC7B,EAAE,OAAO,EAAE,IAAI,EAAc,EAC7B,IAAY,EACZ,KAAa;IAEb,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1C,OAAO,SAAS,CAAC,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC;AACnF,CAAC;AAED,SAAS,OAAO,CAAC,KAAa,EAAE,OAAoC;IAClE,MAAM,CAAC,IAAI,GAAG,KAAK,EAAE,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClD,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AAClE,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,mBAAmB,CACjC,EAAE,OAAO,EAAE,IAAI,EAAc,EAC7B,OAAoC;IAEpC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1C,OAAO,SAAS,CAAC,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC;AAC/F,CAAC"}

package/dist/list.d.ts

@@ -0,0 +1,44 @@
+import * as z from "zod";
+import type { NameOf, StandardFlag } from "./flags.js";
+import { type InputField } from "./input.js";
+import { type Invocation } from "./invocation.js";
+declare const FIELDS_FLAG = "--fields";
+export declare const PAGE_INPUT: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PageInput = z.output<typeof PAGE_INPUT>;
+export type ListFlagName = keyof PageInput | NameOf<typeof FIELDS_FLAG>;
+export type RowSchema = z.ZodObject;
+export declare class Page<Item> {
+    readonly items: readonly Item[];
+    readonly nextCursor: number | undefined;
+    constructor(items: readonly Item[], nextCursor: number | undefined);
+}
+export declare function paginate<Item>(items: readonly Item[], { limit, cursor }: PageInput): Page<Item>;
+/** What the Runtime adds to a List Command, derived from its row schema. */
+export interface ListSpec {
+    readonly rowFields: readonly string[];
+    /** `--limit` and `--cursor`, read and validated as the Command's options are. */
+    readonly pageFields: readonly InputField[];
+    readonly standardFlags: readonly StandardFlag[];
+    /** The printed page, for help JSON. */
+    readonly output: z.ZodType;
+}
+/** The Standard flags every List Command gets, as the caller types them. */
+export declare const LIST_FLAGS: readonly string[];
+export declare function listSpec(rows: RowSchema): ListSpec;
+/** The fields the caller asked for, in their order, or undefined when they gave no `--fields`. */
+export declare function selectedFields(values: ReadonlyMap<string, string | true>, rowFields: readonly string[], commandLine: string): readonly string[] | undefined;
+type Row = Readonly<Record<string, unknown>>;
+export declare function projected(rows: readonly unknown[], fields: readonly string[]): Row[];
+/** Selected rows as text: a header line of the field names, then one tab-separated line per row. */
+export declare function renderRows(rows: readonly Row[], fields: readonly string[]): string;
+export interface PrintedPage {
+    readonly items: readonly unknown[];
+    readonly next?: string;
+}
+export declare function printedPage(page: Page<unknown>, invocation: Invocation): PrintedPage;
+/** The line that ends a rendered page, so the caller always knows whether and how to get more. */
+export declare function pageFooter({ items, next }: PrintedPage): string;
+export {};

package/dist/list.js

@@ -0,0 +1,126 @@
+import * as z from "zod";
+import { UsageError } from "./errors.js";
+import { optionField, optionFields } from "./input.js";
+import { commandLineWith } from "./invocation.js";
+const DEFAULT_PAGE_LIMIT = 20;
+const FIELDS_FLAG = "--fields";
+const SEPARATOR = ",";
+const COLUMN_SEPARATOR = "\t";
+const UNSAFE_IN_COLUMN = /[\t\n\r]/;
+export const PAGE_INPUT = z.object({
+    limit: z.number().int().positive().default(DEFAULT_PAGE_LIMIT),
+    cursor: z.number().int().nonnegative().optional(),
+});
+export class Page {
+    items;
+    nextCursor;
+    constructor(items, nextCursor) {
+        this.items = items;
+        this.nextCursor = nextCursor;
+    }
+}
+export function paginate(items, { limit, cursor = 0 }) {
+    const end = cursor + limit;
+    return new Page(items.slice(cursor, end), end < items.length ? end : undefined);
+}
+const PAGE_FLAG_DESCRIPTIONS = {
+    limit: `how many rows to show, a positive whole number (default: ${DEFAULT_PAGE_LIMIT})`,
+    cursor: "where to start, as given by the previous page's next",
+};
+function pageFlag(key) {
+    const field = optionField(key, PAGE_INPUT.shape[key]);
+    return {
+        flag: field.label,
+        usage: field.usage,
+        description: PAGE_FLAG_DESCRIPTIONS[key],
+        takes: "optional value",
+        schema: field.schema,
+    };
+}
+function fieldsFlag(rowFields) {
+    return {
+        flag: FIELDS_FLAG,
+        usage: `${FIELDS_FLAG} <a,b>`,
+        description: `print only these comma-separated fields of each row (any of: ${rowFields.join(", ")})`,
+        takes: "optional value",
+        schema: z.string(),
+    };
+}
+const PAGE_FIELDS = optionFields(PAGE_INPUT);
+const PAGE_FLAGS = {
+    limit: pageFlag("limit"),
+    cursor: pageFlag("cursor"),
+};
+/** The Standard flags every List Command gets, as the caller types them. */
+export const LIST_FLAGS = [
+    ...Object.values(PAGE_FLAGS).map(({ flag }) => flag),
+    FIELDS_FLAG,
+];
+export function listSpec(rows) {
+    const rowFields = Object.keys(rows.shape);
+    return {
+        rowFields,
+        pageFields: PAGE_FIELDS,
+        standardFlags: [...Object.values(PAGE_FLAGS), fieldsFlag(rowFields)],
+        output: z.object({ items: z.array(rows), next: z.string().optional() }),
+    };
+}
+function quoted(names) {
+    return names.map((name) => `'${name}'`).join(", ");
+}
+/** The fields the caller asked for, in their order, or undefined when they gave no `--fields`. */
+export function selectedFields(values, rowFields, commandLine) {
+    const raw = values.get(FIELDS_FLAG);
+    if (raw === undefined) {
+        return undefined;
+    }
+    const hint = `pass ${FIELDS_FLAG} with any of: ${rowFields.join(", ")}`;
+    const names = typeof raw === "string" ? raw.split(SEPARATOR).filter((name) => name !== "") : [];
+    if (names.length === 0) {
+        throw new UsageError({
+            code: "INVALID_INPUT",
+            message: `${FIELDS_FLAG}: missing value for \`${commandLine}\``,
+            hint,
+        });
+    }
+    const unknown = names.filter((name) => !rowFields.includes(name));
+    if (unknown.length > 0) {
+        throw new UsageError({
+            code: "UNKNOWN_FIELD",
+            message: `unknown field ${quoted(unknown)} for \`${commandLine}\``,
+            hint,
+        });
+    }
+    return names;
+}
+function fieldOf(row, field) {
+    return typeof row === "object" && row !== null ? row[field] : undefined;
+}
+export function projected(rows, fields) {
+    return rows.map((row) => Object.fromEntries(fields.map((field) => [field, fieldOf(row, field)])));
+}
+function cell(value) {
+    if (value === undefined || value === null) {
+        return "";
+    }
+    return typeof value === "string" && !UNSAFE_IN_COLUMN.test(value) ? value : JSON.stringify(value);
+}
+/** Selected rows as text: a header line of the field names, then one tab-separated line per row. */
+export function renderRows(rows, fields) {
+    const lines = [fields, ...rows.map((row) => fields.map((field) => cell(row[field])))];
+    return `${lines.map((line) => line.join(COLUMN_SEPARATOR)).join("\n")}\n`;
+}
+export function printedPage(page, invocation) {
+    return page.nextCursor === undefined
+        ? { items: page.items }
+        : {
+            items: page.items,
+            next: commandLineWith(invocation, PAGE_FLAGS.cursor.flag, String(page.nextCursor)),
+        };
+}
+/** The line that ends a rendered page, so the caller always knows whether and how to get more. */
+export function pageFooter({ items, next }) {
+    const more = next === undefined ? "no more pages" : `next page: \`${next}\``;
+    return `${items.length} shown; ${more}\n`;
+}
+//# sourceMappingURL=list.js.map

package/dist/list.js.map

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

package/dist/npm.d.ts

@@ -0,0 +1,24 @@
+import type { CommandTreeCli, Context, Env, GlobalInstall } from "./define.js";
+/** What every npm call needs: the CLI it serves, its package, and the caller's env and signal. */
+export interface NpmContext {
+    readonly cliName: string;
+    readonly install: GlobalInstall;
+    readonly env: Env;
+    readonly signal: AbortSignal;
+}
+/** Which kind of npm call failed, since the same npm code means different things for each. */
+export type NpmCall = "prefix" | "view" | "install";
+export declare function npmContext(cli: CommandTreeCli, install: GlobalInstall, ctx: Context): NpmContext;
+/** The flag that points npm at the CLI's registry; none for npmjs, npm's default. */
+export declare function registryFlags({ package: name, registry }: GlobalInstall): string[];
+/** The command a person runs to install the CLI globally from its registry. */
+export declare function installCommandLine(install: GlobalInstall, version?: string): string;
+/**
+ * Runs npm with a fresh cache, so a stale cache never answers for the registry; maps its failures to codes.
+ * `signal` kills npm when it aborts; pass null for a step that must finish.
+ */
+export declare function runNpm(call: NpmCall, args: readonly string[], ctx: NpmContext, signal?: AbortSignal | null): Promise<string>;
+export declare function globalPrefix(ctx: NpmContext): Promise<string>;
+/** Installs `version` globally; never killed by the signal, so run it inside `ctx.runToEnd`. */
+export declare function installGlobally(version: string, ctx: NpmContext): Promise<void>;
+export declare function latestVersion(ctx: NpmContext): Promise<string>;

package/dist/npm.js

@@ -0,0 +1,181 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { CliError, messageOf } from "./errors.js";
+import { isVersion } from "./semver.js";
+export function npmContext(cli, install, ctx) {
+    return { cliName: cli.name, install, env: ctx.env, signal: ctx.signal };
+}
+const NPMJS = "https://registry.npmjs.org/";
+const STDERR_TAIL_LINES = 10;
+const RM_RETRIES = 3;
+const NETWORK_CODES = new Set([
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "ETIMEDOUT",
+    "ENETUNREACH",
+    "EHOSTUNREACH",
+    "ERR_SOCKET_TIMEOUT",
+]);
+const AUTH_CODES = new Set(["E401", "E403"]);
+const NPM_CODE = /^npm (?:error|ERR!) code (\S+)$/m;
+/** The flag that points npm at the CLI's registry; none for npmjs, npm's default. */
+export function registryFlags({ package: name, registry }) {
+    if (registry === NPMJS)
+        return [];
+    const scope = /^(@[^/]+)\//.exec(name)?.[1];
+    return [scope === undefined ? `--registry=${registry}` : `--${scope}:registry=${registry}`];
+}
+/** The command a person runs to install the CLI globally from its registry. */
+export function installCommandLine(install, version = "latest") {
+    return [
+        "npm",
+        "install",
+        "--global",
+        `${install.package}@${version}`,
+        ...registryFlags(install),
+    ].join(" ");
+}
+// npm.cmd needs cmd.exe on Windows, so there the arguments go through a shell, quoted. A step
+// without a signal must finish, so on POSIX it leaves the terminal's process group and its Ctrl-C.
+function spawnNpm(args, ctx, signal) {
+    const windows = process.platform === "win32";
+    const command = windows
+        ? ["npm", ...args].map((arg) => `"${arg.replaceAll('"', '""')}"`).join(" ")
+        : "npm";
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, windows ? [] : args, {
+            env: ctx.env,
+            shell: windows,
+            windowsHide: true,
+            stdio: ["ignore", "pipe", "pipe"],
+            detached: signal === null && !windows,
+            signal: signal ?? undefined,
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.setEncoding("utf8").on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.setEncoding("utf8").on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("error", reject);
+        child.on("close", (exitCode) => resolve({ exitCode, stdout, stderr }));
+    });
+}
+function tail(stderr) {
+    const lines = stderr.trim().split("\n").slice(-STDERR_TAIL_LINES);
+    return lines.length === 0 || lines[0] === "" ? "" : `\n${lines.join("\n")}`;
+}
+function failureOf(call, answer, ctx) {
+    const { registry, package: name } = ctx.install;
+    const code = NPM_CODE.exec(answer.stderr)?.[1];
+    const output = tail(answer.stderr);
+    if (code !== undefined && NETWORK_CODES.has(code)) {
+        return new CliError({
+            code: "REGISTRY_UNREACHABLE",
+            message: `npm could not reach ${registry} (${code})${output}`,
+            hint: "check the network or VPN, then run it again",
+            retryable: true,
+        });
+    }
+    if (code !== undefined && AUTH_CODES.has(code)) {
+        return new CliError({
+            code: "REGISTRY_AUTH",
+            message: `${registry} refused npm's credentials (${code})${output}`,
+            hint: `log in to ${registry} (npm login --registry=${registry}) or set its token in ~/.npmrc, then run it again`,
+            retryable: false,
+        });
+    }
+    if (call === "view" && code === "E404") {
+        return noLatest(ctx, `npm found no ${name}@latest on ${registry}: no version of it is published there`);
+    }
+    if (call === "install") {
+        return new CliError({
+            code: "INSTALL_FAILED",
+            message: `npm could not install ${name}${code === undefined ? "" : ` (${code})`}${output}`,
+            hint: `fix what npm reports, then run it again, or install it yourself: ${installCommandLine(ctx.install)}`,
+            retryable: false,
+        });
+    }
+    return new CliError({
+        code: "NPM_FAILED",
+        message: `npm ${call} failed with exit code ${answer.exitCode}${output}`,
+        hint: "fix what npm reports, then run it again",
+        retryable: false,
+    });
+}
+function noLatest(ctx, message) {
+    return new CliError({
+        code: "NO_LATEST",
+        message,
+        hint: `check that ${ctx.install.package} is published on ${ctx.install.registry}`,
+        retryable: false,
+    });
+}
+/**
+ * Runs npm with a fresh cache, so a stale cache never answers for the registry; maps its failures to codes.
+ * `signal` kills npm when it aborts; pass null for a step that must finish.
+ */
+export async function runNpm(call, args, ctx, signal = ctx.signal) {
+    const cache = await mkdtemp(join(tmpdir(), `${ctx.cliName}-npm-`));
+    try {
+        const answer = await spawnNpm([...args, `--cache=${join(cache, "cache")}`, "--logs-max=0"], ctx, signal).catch((error) => {
+            if (signal?.aborted === true)
+                throw signal.reason;
+            throw new CliError({
+                code: "NPM_FAILED",
+                message: `npm could not be started: ${messageOf(error)}`,
+                hint: "install Node with npm, or put npm on PATH",
+                retryable: false,
+            }, { cause: error });
+        });
+        if (answer.exitCode !== 0) {
+            throw failureOf(call, answer, ctx);
+        }
+        return answer.stdout;
+    }
+    finally {
+        // A cache left behind in the temp dir costs disk space only, never the call's result.
+        await rm(cache, { recursive: true, force: true, maxRetries: RM_RETRIES }).catch(() => { });
+    }
+}
+export async function globalPrefix(ctx) {
+    return (await runNpm("prefix", ["prefix", "--global"], ctx)).trim();
+}
+// npm 12 answers `["X.Y.Z"]` and npm 11 a bare `"X.Y.Z"`.
+function versionInViewAnswer(answer) {
+    try {
+        const parsed = JSON.parse(answer);
+        const version = Array.isArray(parsed) ? parsed.at(-1) : parsed;
+        return typeof version === "string" && isVersion(version) ? version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Installs `version` globally; never killed by the signal, so run it inside `ctx.runToEnd`. */
+export async function installGlobally(version, ctx) {
+    await runNpm("install", [
+        "install",
+        "--global",
+        "--no-audit",
+        "--no-fund",
+        `${ctx.install.package}@${version}`,
+        ...registryFlags(ctx.install),
+    ], ctx, null);
+}
+export async function latestVersion(ctx) {
+    const { package: name, registry } = ctx.install;
+    const answer = await runNpm("view", ["view", `${name}@latest`, "version", "--json", ...registryFlags(ctx.install)], ctx);
+    const version = versionInViewAnswer(answer);
+    if (version === undefined) {
+        throw noLatest(ctx, `npm answered no version for ${name}@latest on ${registry}: ${answer.trim()}`);
+    }
+    return version;
+}
+//# sourceMappingURL=npm.js.map

package/dist/npm.js.map

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

package/dist/output.d.ts

@@ -0,0 +1,33 @@
+import type { SpecNode } from "./command-spec.js";
+import type { Cli, Env } from "./define.js";
+import type { Outcome } from "./execute.js";
+import type { Invocation } from "./invocation.js";
+import type { Style } from "./style.js";
+export interface RunResult {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number;
+}
+export interface OutputFormat {
+    readonly cliName: string;
+    readonly env: Env;
+    readonly style: Style;
+    readonly invocation: Invocation;
+    readonly json: boolean;
+}
+export interface DataFormat extends OutputFormat {
+    readonly fields: readonly string[] | undefined;
+}
+/** How a Command's run ended; a thrown error carries the Command's render for any data it holds. */
+export type Settled = {
+    readonly ok: true;
+    readonly outcome: Outcome;
+} | {
+    readonly ok: false;
+    readonly error: unknown;
+    readonly render: (data: unknown, style: Style) => string;
+};
+export declare function errorResult(error: unknown, format: OutputFormat): RunResult;
+export declare function commandResult(settled: Settled, format: DataFormat): RunResult;
+export declare function helpResult(node: SpecNode, root: SpecNode, cli: Cli, { style, json }: OutputFormat): RunResult;
+export declare function versionResult({ version, build }: Cli): RunResult;