@duyquangnvx/agent-cli 0.0.0-stage → 0.1.0

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/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/page.d.ts

@@ -0,0 +1,26 @@
+import * as z from "zod";
+import { type Invocation } from "./invocation.js";
+export declare const pageOptions: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PageInput = z.output<typeof pageOptions>;
+/** The output schema of a list Command: the printed page of `row`s. It earns the Command `--fields`. */
+export declare function pageOf<Row extends z.ZodObject>(row: Row): z.ZodObject<{
+    items: z.ZodArray<Row>;
+    next: z.ZodOptional<z.ZodString>;
+}>;
+export declare function rowSchemaOf(output: z.ZodType | undefined): z.ZodObject | undefined;
+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>;
+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;

package/dist/page.js

@@ -0,0 +1,49 @@
+import * as z from "zod";
+import { commandLineWith } from "./invocation.js";
+const DEFAULT_PAGE_LIMIT = 20;
+const CURSOR_FLAG = "--cursor";
+export const pageOptions = z.object({
+    limit: z.number().int().positive().default(DEFAULT_PAGE_LIMIT).describe("how many to show"),
+    cursor: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe("where to start, as given by the previous page"),
+});
+const rowSchemas = new WeakMap();
+/** The output schema of a list Command: the printed page of `row`s. It earns the Command `--fields`. */
+export function pageOf(row) {
+    const page = z.object({ items: z.array(row), next: z.string().optional() });
+    rowSchemas.set(page, row);
+    return page;
+}
+export function rowSchemaOf(output) {
+    return output === undefined ? undefined : rowSchemas.get(output);
+}
+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);
+}
+export function printedPage(page, invocation) {
+    return page.nextCursor === undefined
+        ? { items: page.items }
+        : {
+            items: page.items,
+            next: commandLineWith(invocation, 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=page.js.map

package/dist/page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page.js","sourceRoot":"","sources":["../src/page.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAAE,eAAe,EAAmB,MAAM,iBAAiB,CAAC;AAEnE,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAC9B,MAAM,WAAW,GAAG,UAAU,CAAC;AAE/B,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IAC3F,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,GAAG,EAAE;SACL,WAAW,EAAE;SACb,QAAQ,EAAE;SACV,QAAQ,CAAC,+CAA+C,CAAC;CAC7D,CAAC,CAAC;AAIH,MAAM,UAAU,GAAG,IAAI,OAAO,EAA0B,CAAC;AAEzD,wGAAwG;AACxG,MAAM,UAAU,MAAM,CACpB,GAAQ;IAER,MAAM,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC5E,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC1B,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,MAA6B;IACvD,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,OAAO,IAAI;IACN,KAAK,CAAkB;IACvB,UAAU,CAAqB;IAExC,YAAY,KAAsB,EAAE,UAA8B;QAChE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED,MAAM,UAAU,QAAQ,CACtB,KAAsB,EACtB,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,EAAa;IAEhC,MAAM,GAAG,GAAG,MAAM,GAAG,KAAK,CAAC;IAC3B,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;AAClF,CAAC;AAOD,MAAM,UAAU,WAAW,CAAC,IAAmB,EAAE,UAAsB;IACrE,OAAO,IAAI,CAAC,UAAU,KAAK,SAAS;QAClC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE;QACvB,CAAC,CAAC;YACE,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,IAAI,EAAE,eAAe,CAAC,UAAU,EAAE,WAAW,EAAE,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;SACxE,CAAC;AACR,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,UAAU,CAAC,EAAE,KAAK,EAAE,IAAI,EAAe;IACrD,MAAM,IAAI,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,gBAAgB,IAAI,IAAI,CAAC;IAC7E,OAAO,GAAG,KAAK,CAAC,MAAM,WAAW,IAAI,IAAI,CAAC;AAC5C,CAAC"}

package/dist/parse-input.d.ts

@@ -0,0 +1,5 @@
+import type { Command as Commander } from "commander";
+import type { Command } from "./define.js";
+import type { InputFields } from "./input.js";
+import { type Invocation } from "./invocation.js";
+export declare function parseInput(command: Command, sub: Commander, fields: InputFields, invocation: Invocation): Record<string, unknown>;

package/dist/parse-input.js

@@ -0,0 +1,114 @@
+import * as z from "zod";
+import { UsageError } from "./errors.js";
+import { commandLineRenaming, END_OF_OPTIONS } from "./invocation.js";
+import { closestFlag } from "./suggest.js";
+import { commandLine, unknownOptionError } from "./usage.js";
+const HELP_FLAG = "--help";
+const NEGATIVE_NUMBER = /^-(\d+|\d*\.\d+)(e[+-]?\d+)?$/;
+function isOptionLike(token) {
+    return (token !== undefined && token.length > 1 && token[0] === "-" && !NEGATIVE_NUMBER.test(token));
+}
+// Commander keeps `--` only after an unknown option, so the words after it are counted from the
+// caller's own command line.
+function leftoversOf(tokens, argv) {
+    const end = argv.indexOf(END_OF_OPTIONS);
+    const split = end === -1 ? tokens.length : Math.max(0, tokens.length - (argv.length - end - 1));
+    const head = tokens.slice(0, split);
+    const parsed = end !== -1 && head.at(-1) === END_OF_OPTIONS ? head.slice(0, -1) : head;
+    const literal = tokens.slice(split).map((value) => ({ value, afterUnknownOption: false }));
+    return {
+        operands: [
+            ...parsed.flatMap((value, index) => isOptionLike(value) ? [] : [{ value, afterUnknownOption: isOptionLike(parsed[index - 1]) }]),
+            ...literal,
+        ],
+        unknownOptions: parsed.filter(isOptionLike),
+    };
+}
+function flagsOf(cmd) {
+    const own = cmd.options.flatMap((option) => (option.long === undefined ? [] : [option.long]));
+    return cmd.parent === null ? [...own, HELP_FLAG] : [...own, ...flagsOf(cmd.parent)];
+}
+function unknownOptionsOf(tokens, sub) {
+    return tokens.map((token) => {
+        const flag = token.split("=")[0] ?? token;
+        return { flag, suggestion: closestFlag(flag, flagsOf(sub)) };
+    });
+}
+// Strings that read as numbers are converted so authors can write `z.number()`; anything else
+// stays a string for Zod to reject with the caller's own value.
+function converted(field, raw) {
+    if (field.type !== "number" || typeof raw !== "string" || raw.trim() === "") {
+        return raw;
+    }
+    const number = Number(raw);
+    return Number.isNaN(number) ? raw : number;
+}
+function parse(schema, values) {
+    const input = Object.fromEntries([...values]
+        .filter(([, raw]) => raw !== undefined)
+        .map(([field, raw]) => [field.key, converted(field, raw)]));
+    return (schema ?? z.object({})).safeParse(input);
+}
+function issueLines(result, values, howToPass, reported) {
+    if (result.success) {
+        return [];
+    }
+    return result.error.issues.flatMap((issue) => {
+        const field = [...values.keys()].find((candidate) => candidate.key === issue.path[0]);
+        if (field === undefined) {
+            return [`  ${issue.message}`];
+        }
+        if (reported.includes(field)) {
+            return [];
+        }
+        const raw = values.get(field);
+        return raw === undefined
+            ? [`  ${field.label}: required, ${howToPass(field)}`]
+            : [`  ${field.label} ${JSON.stringify(raw)}: ${issue.message}`];
+    });
+}
+function unknownLine({ flag, suggestion }) {
+    return `  unknown option '${flag}'${suggestion === undefined ? "" : ` (did you mean ${suggestion}?)`}`;
+}
+function invalidInput(line, invocation, unknown, otherLines) {
+    const renames = new Map(unknown.flatMap(({ flag, suggestion }) => suggestion === undefined ? [] : [[flag, suggestion]]));
+    const correctable = otherLines.length === 0 && renames.size === unknown.length;
+    return new UsageError({
+        code: "INVALID_INPUT",
+        message: [`invalid input for \`${line}\``, ...unknown.map(unknownLine), ...otherLines].join("\n"),
+        hint: correctable
+            ? `did you mean \`${commandLineRenaming(invocation, renames)}\`?`
+            : `run \`${line} --help\` to see the expected input`,
+    });
+}
+export function parseInput(command, sub, fields, invocation) {
+    const { operands, unknownOptions } = leftoversOf(sub.args, invocation.argv);
+    const opts = sub.opts();
+    // A value option given without a value is collected as `true`.
+    const missing = fields.options.filter((field) => field.type !== "boolean" && opts[field.key] === true);
+    const argValues = new Map(fields.args.map((field, index) => [field, operands[index]?.value]));
+    const optionValues = new Map(fields.options.map((field) => [field, missing.includes(field) ? undefined : opts[field.key]]));
+    const args = parse(command.args, argValues);
+    const options = parse(command.options, optionValues);
+    const unknown = unknownOptionsOf(unknownOptions, sub);
+    const otherLines = [
+        ...missing.map((field) => `  ${field.label}: missing value, pass ${field.usage}`),
+        ...operands
+            .slice(fields.args.length)
+            // A word right after an unknown flag may be its value, so it isn't an extra arg.
+            .filter((operand) => !operand.afterUnknownOption)
+            .map((operand) => `  unexpected argument ${JSON.stringify(operand.value)}`),
+        ...issueLines(args, argValues, (field) => `pass it as argument ${fields.args.indexOf(field) + 1}`, []),
+        ...issueLines(options, optionValues, (field) => `pass ${field.usage}`, missing),
+    ];
+    if (unknown.length === 0 && otherLines.length === 0 && args.success && options.success) {
+        return { ...args.data, ...options.data };
+    }
+    const line = commandLine(sub);
+    const [only] = unknown;
+    if (only !== undefined && unknown.length === 1 && otherLines.length === 0) {
+        throw unknownOptionError(line, invocation, only.flag, only.suggestion === undefined ? [] : [only.suggestion]);
+    }
+    throw invalidInput(line, invocation, unknown, otherLines);
+}
+//# sourceMappingURL=parse-input.js.map

package/dist/parse-input.js.map

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

package/dist/run-cli.d.ts

@@ -0,0 +1,20 @@
+import { type Cli, type Env } from "./define.js";
+export interface RunOptions {
+    readonly env: Env;
+    readonly cwd: string;
+    readonly stdoutIsTTY?: boolean;
+    /** Aborting it interrupts the running Command, which then ends with `INTERRUPTED`. */
+    readonly signal?: AbortSignal;
+    /**
+     * The script that started the CLI, as `process.argv[1]`; `doctor` checks it is inside npm's
+     * global install. Absent, the CLI counts as run from source.
+     */
+    readonly bin?: string;
+}
+export interface RunResult {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number;
+}
+export declare function runCli(cli: Cli, argv: readonly string[], options: RunOptions): Promise<RunResult>;
+export declare function runWithProgress(cli: Cli, argv: readonly string[], options: RunOptions, writeProgress: (line: string) => void): Promise<RunResult>;