@duyquangnvx/agent-cli 0.0.0-stage → 0.1.0

package/dist/fields.js

@@ -0,0 +1,71 @@
+import { UsageError } from "./errors.js";
+import { rowSchemaOf } from "./page.js";
+const SEPARATOR = ",";
+const COLUMN_SEPARATOR = "\t";
+const UNSAFE_IN_COLUMN = /[\t\n\r]/;
+export const FIELDS_OPTION = "--fields";
+/** The fields a list Command's rows have, or undefined for a Command that is not a list. */
+export function rowFieldsOf(command) {
+    const row = rowSchemaOf(command.output);
+    return row === undefined ? undefined : Object.keys(row.shape);
+}
+export function fieldsDescription(rowFields) {
+    return `print only these comma-separated fields of each row (any of: ${rowFields.join(", ")})`;
+}
+export function fieldsOption(rowFields) {
+    return {
+        key: "fields",
+        type: "string",
+        required: false,
+        defaultValue: undefined,
+        description: fieldsDescription(rowFields),
+        choices: undefined,
+        label: FIELDS_OPTION,
+        usage: `${FIELDS_OPTION} <a,b>`,
+    };
+}
+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(raw, rowFields, commandLine) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    const hint = `pass ${FIELDS_OPTION} 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_OPTION}: 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`;
+}
+//# sourceMappingURL=fields.js.map

package/dist/fields.js.map

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

package/dist/flags.d.ts

@@ -0,0 +1,12 @@
+import type { Command } from "./define.js";
+type Effect = Command["effect"];
+export interface RuntimeFlag {
+    readonly usage: string;
+    readonly description: string;
+    readonly effects: readonly Effect[];
+}
+export declare const JSON_FLAG: RuntimeFlag;
+export declare const DRY_RUN_FLAG: RuntimeFlag;
+export declare const CONFIRM_FLAG: RuntimeFlag;
+export declare function runtimeFlagsFor(effect: Effect): readonly RuntimeFlag[];
+export {};

package/dist/flags.js

@@ -0,0 +1,22 @@
+import { CONFIRM_OPTION } from "./confirm.js";
+export const JSON_FLAG = {
+    usage: "--json",
+    description: "print the result as JSON",
+    effects: ["read", "write", "destructive"],
+};
+export const DRY_RUN_FLAG = {
+    usage: "--dry-run",
+    description: "print the Plan without changing anything",
+    effects: ["write", "destructive"],
+};
+export const CONFIRM_FLAG = {
+    usage: `${CONFIRM_OPTION} <target>`,
+    description: "name the target to confirm the change; an error hint gives the exact command",
+    effects: ["destructive"],
+};
+// A Command's help lists every flag here whose effects include the Command's Effect.
+const RUNTIME_FLAGS = [JSON_FLAG, DRY_RUN_FLAG, CONFIRM_FLAG];
+export function runtimeFlagsFor(effect) {
+    return RUNTIME_FLAGS.filter((flag) => flag.effects.includes(effect));
+}
+//# sourceMappingURL=flags.js.map

package/dist/flags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags.js","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAW9C,MAAM,CAAC,MAAM,SAAS,GAAgB;IACpC,KAAK,EAAE,QAAQ;IACf,WAAW,EAAE,0BAA0B;IACvC,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,aAAa,CAAC;CAC1C,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GAAgB;IACvC,KAAK,EAAE,WAAW;IAClB,WAAW,EAAE,0CAA0C;IACvD,OAAO,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC;CAClC,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GAAgB;IACvC,KAAK,EAAE,GAAG,cAAc,WAAW;IACnC,WAAW,EAAE,8EAA8E;IAC3F,OAAO,EAAE,CAAC,aAAa,CAAC;CACzB,CAAC;AAEF,qFAAqF;AACrF,MAAM,aAAa,GAA2B,CAAC,SAAS,EAAE,YAAY,EAAE,YAAY,CAAC,CAAC;AAEtF,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,OAAO,aAAa,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;AACvE,CAAC"}

package/dist/global-install.d.ts

@@ -0,0 +1,11 @@
+import { type NpmContext } from "./npm.js";
+/** Where npm installed this copy of the CLI globally. */
+export interface InstalledCopy {
+    readonly prefix: string;
+    readonly packageDir: string;
+}
+/**
+ * The global npm install this copy runs from, found by asking npm for its global prefix.
+ * `bin` is the script that started the CLI; throws `NOT_GLOBAL_INSTALL` when it is not inside that install.
+ */
+export declare function globalInstallOf(bin: string | undefined, ctx: NpmContext): Promise<InstalledCopy>;

package/dist/global-install.js

@@ -0,0 +1,50 @@
+import { lstat, realpath } from "node:fs/promises";
+import { isAbsolute, join, relative } from "node:path";
+import { CliError, isMissingFile } from "./errors.js";
+import { globalPrefix, installCommandLine } from "./npm.js";
+function packageDirUnder(prefix, name) {
+    return process.platform === "win32"
+        ? join(prefix, "node_modules", name)
+        : join(prefix, "lib", "node_modules", name);
+}
+function notGlobal(ctx, message) {
+    return new CliError({
+        code: "NOT_GLOBAL_INSTALL",
+        message,
+        hint: `install it with npm, so \`${ctx.cliName} update\` can replace it: ${installCommandLine(ctx.install)}`,
+        retryable: false,
+    });
+}
+async function realpathOrUndefined(path) {
+    return realpath(path).catch((error) => {
+        if (isMissingFile(error))
+            return undefined;
+        throw error;
+    });
+}
+function isInside(dir, path) {
+    const inner = relative(dir, path);
+    return inner !== "" && !inner.startsWith("..") && !isAbsolute(inner);
+}
+/**
+ * The global npm install this copy runs from, found by asking npm for its global prefix.
+ * `bin` is the script that started the CLI; throws `NOT_GLOBAL_INSTALL` when it is not inside that install.
+ */
+export async function globalInstallOf(bin, ctx) {
+    if (bin === undefined) {
+        throw notGlobal(ctx, `${ctx.cliName} runs from source, not from an npm install`);
+    }
+    const prefix = await globalPrefix(ctx);
+    const packageDir = packageDirUnder(prefix, ctx.install.package);
+    const installed = await realpathOrUndefined(packageDir);
+    const here = (await realpathOrUndefined(bin)) ?? bin;
+    if (installed === undefined || !isInside(installed, here)) {
+        throw notGlobal(ctx, `${ctx.cliName} runs from ${here}, not from npm's global install at ${packageDir}`);
+    }
+    // `npm link` puts a symlink to a source checkout where the install would be.
+    if ((await lstat(packageDir)).isSymbolicLink()) {
+        throw notGlobal(ctx, `${ctx.cliName} runs from a link to ${installed} (npm link), not from an npm install`);
+    }
+    return { prefix, packageDir };
+}
+//# sourceMappingURL=global-install.js.map

package/dist/global-install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-install.js","sourceRoot":"","sources":["../src/global-install.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAmB,MAAM,UAAU,CAAC;AAQ7E,SAAS,eAAe,CAAC,MAAc,EAAE,IAAY;IACnD,OAAO,OAAO,CAAC,QAAQ,KAAK,OAAO;QACjC,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,CAAC;QACpC,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,CAAC,CAAC;AAChD,CAAC;AAED,SAAS,SAAS,CAAC,GAAe,EAAE,OAAe;IACjD,OAAO,IAAI,QAAQ,CAAC;QAClB,IAAI,EAAE,oBAAoB;QAC1B,OAAO;QACP,IAAI,EAAE,6BAA6B,GAAG,CAAC,OAAO,6BAA6B,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE;QAC5G,SAAS,EAAE,KAAK;KACjB,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,mBAAmB,CAAC,IAAY;IAC7C,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QAC7C,IAAI,aAAa,CAAC,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QAC3C,MAAM,KAAK,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,QAAQ,CAAC,GAAW,EAAE,IAAY;IACzC,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAClC,OAAO,KAAK,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;AACvE,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,GAAuB,EACvB,GAAe;IAEf,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,MAAM,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC,OAAO,4CAA4C,CAAC,CAAC;IACnF,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,CAAC;IACvC,MAAM,UAAU,GAAG,eAAe,CAAC,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAChE,MAAM,SAAS,GAAG,MAAM,mBAAmB,CAAC,UAAU,CAAC,CAAC;IACxD,MAAM,IAAI,GAAG,CAAC,MAAM,mBAAmB,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC;IACrD,IAAI,SAAS,KAAK,SAAS,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,CAAC;QAC1D,MAAM,SAAS,CACb,GAAG,EACH,GAAG,GAAG,CAAC,OAAO,cAAc,IAAI,sCAAsC,UAAU,EAAE,CACnF,CAAC;IACJ,CAAC;IACD,6EAA6E;IAC7E,IAAI,CAAC,MAAM,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC;QAC/C,MAAM,SAAS,CACb,GAAG,EACH,GAAG,GAAG,CAAC,OAAO,wBAAwB,SAAS,sCAAsC,CACtF,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;AAChC,CAAC"}

package/dist/help-json.d.ts

@@ -0,0 +1,4 @@
+import { type Command, type Commands } from "./define.js";
+export declare function cliHelpJson(name: string, version: string, root: Command | Commands): string;
+export declare function groupHelpJson(commandLine: string, commands: Commands): string;
+export declare function commandHelpJson(commandLine: string, command: Command): string;

package/dist/help-json.js

@@ -0,0 +1,60 @@
+import * as z from "zod";
+import { isCommand } from "./define.js";
+import { fieldsDescription, rowFieldsOf } from "./fields.js";
+import { runtimeFlagsFor } from "./flags.js";
+import { kebab } from "./input.js";
+// Transforms and other unrepresentable parts become `{}` rather than failing the whole help.
+function inputSchema(schema) {
+    return z.toJSONSchema(schema ?? z.object({}), { io: "input", unrepresentable: "any" });
+}
+// Options are keyed as the caller types them, so `greetingWord` reads `greeting-word`.
+function optionsSchema(command) {
+    const shape = Object.entries(command.options?.shape ?? {}).map(([key, value]) => [
+        kebab(key),
+        value,
+    ]);
+    const rowFields = rowFieldsOf(command);
+    const fields = rowFields === undefined
+        ? []
+        : [["fields", z.string().optional().describe(fieldsDescription(rowFields))]];
+    return inputSchema(z.object(Object.fromEntries([...shape, ...fields])));
+}
+function commandData(commandLine, command) {
+    return {
+        name: commandLine,
+        description: command.description,
+        effect: command.effect,
+        examples: command.examples,
+        args: inputSchema(command.args),
+        options: optionsSchema(command),
+        standardFlags: runtimeFlagsFor(command.effect).map(({ usage, description }) => ({
+            usage,
+            description,
+        })),
+        output: command.output === undefined
+            ? null
+            : z.toJSONSchema(command.output, { unrepresentable: "any" }),
+    };
+}
+function nodeData(commandLine, node) {
+    return isCommand(node) ? commandData(commandLine, node) : groupData(commandLine, node);
+}
+function groupData(commandLine, commands) {
+    return {
+        name: commandLine,
+        commands: Object.entries(commands).map(([key, node]) => nodeData(`${commandLine} ${key}`, node)),
+    };
+}
+function printed(data) {
+    return `${JSON.stringify(data)}\n`;
+}
+export function cliHelpJson(name, version, root) {
+    return printed({ name, version, ...nodeData(name, root) });
+}
+export function groupHelpJson(commandLine, commands) {
+    return printed(groupData(commandLine, commands));
+}
+export function commandHelpJson(commandLine, command) {
+    return printed(commandData(commandLine, command));
+}
+//# sourceMappingURL=help-json.js.map

package/dist/help-json.js.map

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

package/dist/help.d.ts

@@ -0,0 +1,6 @@
+import { type Command, type Commands } from "./define.js";
+import type { InputFields } from "./input.js";
+import type { Style } from "./style.js";
+export declare function cliHelp(name: string, version: string, commands: Commands, style: Style): string;
+export declare function groupHelp(commandLine: string, commands: Commands, style: Style): string;
+export declare function commandHelp(commandLine: string, command: Command, fields: InputFields, style: Style): string;

package/dist/help.js

@@ -0,0 +1,61 @@
+import { isCommand } from "./define.js";
+import { runtimeFlagsFor } from "./flags.js";
+function table(rows) {
+    const width = Math.max(...rows.map(([left]) => left.length));
+    return rows.map(([left, right]) => right === "" ? `  ${left}` : `  ${left.padEnd(width)}  ${right}`);
+}
+function section(title, rows, style) {
+    return rows.length === 0 ? [] : ["", style.bold(`${title}:`), ...table(rows)];
+}
+function summaryOf(node) {
+    return isCommand(node) ? node.description : `group: ${Object.keys(node).join(", ")}`;
+}
+function commandRows(commands) {
+    return Object.entries(commands).map(([key, node]) => [key, summaryOf(node)]);
+}
+function lines(...parts) {
+    return `${parts.join("\n")}\n`;
+}
+function listing(heading, commandLine, commands, style) {
+    return lines(style.bold(heading), ...section("Commands", commandRows(commands), style), "", `Run \`${commandLine} <command> --help\` for its examples and input.`);
+}
+export function cliHelp(name, version, commands, style) {
+    return listing(`${name} ${version}`, name, commands, style);
+}
+export function groupHelp(commandLine, commands, style) {
+    return listing(commandLine, commandLine, commands, style);
+}
+const EFFECT_NOTES = {
+    read: "changes nothing",
+    write: "changes something; show the Plan with --dry-run",
+    destructive: "changes something hard to undo; show the Plan with --dry-run, run with --confirm",
+};
+function choicesOf(field) {
+    return field.choices === undefined ? [] : [`one of: ${field.choices.join(", ")}`];
+}
+function defaultsOf(field) {
+    if (field.defaultValue === undefined) {
+        return [];
+    }
+    if (field.type !== "boolean") {
+        return [`default: ${JSON.stringify(field.defaultValue)}`];
+    }
+    // A `--no-` flag sits next to the description of what it turns off, so the row must say so.
+    return field.defaultValue === true ? ["on by default; this flag turns it off"] : [];
+}
+function fieldRow(field, notes) {
+    const all = [...(field.required ? ["required"] : []), ...notes];
+    const suffix = all.length === 0 ? "" : `(${all.join("; ")})`;
+    return [field.usage, [field.description ?? "", suffix].filter((part) => part !== "").join(" ")];
+}
+function argRow(field) {
+    return fieldRow(field, [...choicesOf(field), ...defaultsOf(field)]);
+}
+// An option's usage already shows its choices, as in `--sort <name|date>`.
+function optionRow(field) {
+    return fieldRow(field, defaultsOf(field));
+}
+export function commandHelp(commandLine, command, fields, style) {
+    return lines(style.bold(commandLine), command.description, ...section("Examples", command.examples.map(({ command, note }) => [command, note]), style), ...section("Arguments", fields.args.map(argRow), style), ...section("Options", fields.options.map(optionRow), style), "", `${style.bold("Effect:")} ${command.effect} (${EFFECT_NOTES[command.effect]})`, ...section("Standard flags", runtimeFlagsFor(command.effect).map(({ usage, description }) => [usage, description]), style));
+}
+//# sourceMappingURL=help.js.map

package/dist/help.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { defineCli } from "./built-ins.js";
+export type { Cli, Command, Commands, Context, DestructiveCommand, DoctorCheck, DoctorFinding, Env, Example, GlobalInstall, ReadCommand, WriteCommand, } from "./define.js";
+export { defineCommand } from "./define.js";
+export type { CliErrorDetails, UsageErrorDetails } from "./errors.js";
+export { CliError, debugVariable, UsageError } from "./errors.js";
+export type { Page, PageInput } from "./page.js";
+export { pageOf, pageOptions, paginate } from "./page.js";
+export type { RunOptions, RunResult } from "./run-cli.js";
+export { runCli } from "./run-cli.js";
+export { runProcess } from "./run-process.js";
+export type { Style } from "./style.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { defineCli } from "./built-ins.js";
+export { defineCommand } from "./define.js";
+export { CliError, debugVariable, UsageError } from "./errors.js";
+export { pageOf, pageOptions, paginate } from "./page.js";
+export { runCli } from "./run-cli.js";
+export { runProcess } from "./run-process.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAe3C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAElE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1D,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/input.d.ts

@@ -0,0 +1,22 @@
+import type { Command as Commander } from "commander";
+import type { Command } from "./define.js";
+export type ValueType = "string" | "number" | "boolean";
+export interface InputField {
+    readonly key: string;
+    readonly type: ValueType;
+    readonly required: boolean;
+    readonly defaultValue: unknown;
+    readonly description: string | undefined;
+    readonly choices: readonly string[] | undefined;
+    /** How the caller names it: `<name>` for an arg, `--name` or `--no-name` for an option. */
+    readonly label: string;
+    /** How the caller passes it: the label plus a value placeholder such as `<value>` or `<a|b>`. */
+    readonly usage: string;
+}
+export interface InputFields {
+    readonly args: readonly InputField[];
+    readonly options: readonly InputField[];
+}
+export declare function kebab(key: string): string;
+export declare function inputFields(command: Command): InputFields;
+export declare function registerInput(sub: Commander, options: readonly InputField[]): void;

package/dist/input.js

@@ -0,0 +1,70 @@
+import * as z from "zod";
+function isWrapper(schema) {
+    return (schema instanceof z.ZodOptional ||
+        schema instanceof z.ZodNullable ||
+        schema instanceof z.ZodDefault ||
+        schema instanceof z.ZodPrefault);
+}
+export function kebab(key) {
+    return key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+}
+// Any other schema gets the caller's string, for Zod to accept or reject.
+function typeOf(schema) {
+    if (schema instanceof z.ZodNumber) {
+        return "number";
+    }
+    return schema instanceof z.ZodBoolean ? "boolean" : "string";
+}
+function describe(schema) {
+    let current = schema;
+    let description = current.description;
+    let required = true;
+    let defaultValue;
+    while (isWrapper(current)) {
+        if (current instanceof z.ZodDefault || current instanceof z.ZodPrefault) {
+            defaultValue = current.def.defaultValue;
+        }
+        required = false;
+        current = current.unwrap();
+        description ??= current.description;
+    }
+    return {
+        type: typeOf(current),
+        required,
+        defaultValue,
+        description,
+        choices: current instanceof z.ZodEnum ? current.options.map(String) : undefined,
+    };
+}
+function argField(key, schema) {
+    const label = `<${key}>`;
+    return { key, ...describe(schema), label, usage: label };
+}
+function optionField(key, schema) {
+    const described = describe(schema);
+    const isBoolean = described.type === "boolean";
+    // A boolean that defaults to true can only be changed by turning it off.
+    const label = isBoolean && described.defaultValue === true ? `--no-${kebab(key)}` : `--${kebab(key)}`;
+    const usage = isBoolean ? label : `${label} <${described.choices?.join("|") ?? "value"}>`;
+    return { key, ...described, label, usage };
+}
+function fieldsOf(schema, toField) {
+    return schema === undefined
+        ? []
+        : Object.entries(schema.shape).map(([key, value]) => toField(key, value));
+}
+export function inputFields(command) {
+    return {
+        args: fieldsOf(command.args, argField),
+        options: fieldsOf(command.options, optionField),
+    };
+}
+// Commander only collects what the caller typed, so that the Runtime can report every problem
+// with it in one pass: unknown flags, extra args and missing values never stop commander.
+export function registerInput(sub, options) {
+    sub.allowUnknownOption().allowExcessArguments();
+    for (const field of options) {
+        sub.option(field.type === "boolean" ? field.label : `${field.label} [value]`);
+    }
+}
+//# sourceMappingURL=input.js.map

package/dist/input.js.map

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

package/dist/interrupts.d.ts

@@ -0,0 +1,18 @@
+/** How long an interrupted Command may take to settle before the run ends without it. */
+export declare const GRACE_MS = 3000;
+export declare const INTERRUPTED = "INTERRUPTED";
+/** One Command run's cancellation: its signal, its deadlines and the steps it must finish. */
+export declare class RunControl {
+    #private;
+    readonly signal: AbortSignal;
+    constructor(commandLine: string, outer: AbortSignal | undefined);
+    deadline(ms: number): AbortSignal;
+    runToEnd<T>(work: () => Promise<T>): Promise<T>;
+    /** Waits for the Command, its must-finish steps, and no longer than the grace once interrupted. */
+    settle<T>(work: Promise<T>): Promise<T>;
+    /**
+     * The error a run ends with: an interrupt or a missed deadline outranks what the Command threw,
+     * unless the Command threw its own `INTERRUPTED`, saying what it finished before it stopped.
+     */
+    errorAfter(error: unknown): unknown;
+}

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;