@duyquangnvx/agent-cli 0.0.0-stage → 0.2.0

package/dist/errors.js

@@ -0,0 +1,72 @@
+export class CliError extends Error {
+    code;
+    hint;
+    retryable;
+    constructor({ code, message, hint, retryable }, options) {
+        super(message, options);
+        this.name = "CliError";
+        this.code = code;
+        this.hint = hint;
+        this.retryable = retryable;
+    }
+}
+/** The caller called the Agent CLI wrong; retrying the same call can't succeed. */
+export class UsageError extends CliError {
+    constructor(details) {
+        super({ ...details, retryable: false });
+        this.name = "UsageError";
+    }
+}
+const INTERNAL_CODE = "INTERNAL";
+export function isMissingFile(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+export function debugVariable(cliName) {
+    return `${cliName.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_DEBUG`;
+}
+export function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isDebug({ env, cliName }) {
+    return Boolean(env[debugVariable(cliName)]);
+}
+function detailsOf(error, format) {
+    if (error instanceof CliError) {
+        const { code, message, hint, retryable } = error;
+        return { code, message, hint, retryable };
+    }
+    return {
+        code: INTERNAL_CODE,
+        message: messageOf(error),
+        hint: isDebug(format)
+            ? "the stack trace shows where it failed"
+            : `rerun with ${debugVariable(format.cliName)}=1 to see the stack trace`,
+        retryable: false,
+    };
+}
+function stackOf(error, format) {
+    return isDebug(format) && !(error instanceof CliError) && error instanceof Error
+        ? error.stack
+        : undefined;
+}
+export function formatRuntimeError(error, format) {
+    const details = detailsOf(error, format);
+    const stack = stackOf(error, format);
+    if (format.json) {
+        return `${JSON.stringify({ ...details, stack })}\n`;
+    }
+    const { style } = format;
+    const label = style.red(error instanceof CliError ? "error:" : "internal error:");
+    const trace = stack === undefined ? "" : `${stack}\n`;
+    return `${label} ${details.message}\n${trace}${style.cyan("hint:")} ${details.hint}\n`;
+}
+/** A failure that still prints the Command's data on stdout, as `doctor` does with its rows. */
+export class FailureWithData extends CliError {
+    data;
+    constructor(details, data) {
+        super(details);
+        this.name = "FailureWithData";
+        this.data = data;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/execute.d.ts

@@ -0,0 +1,21 @@
+import type { Command, Context } from "./define.js";
+import type { Invocation } from "./invocation.js";
+import type { PageInput } from "./list.js";
+import type { Style } from "./style.js";
+export interface Outcome {
+    readonly value: unknown;
+    render(style: Style): string;
+}
+export interface ExecuteFlags {
+    readonly dryRun: boolean;
+    /** The target the caller named with `--confirm`, if any. */
+    readonly confirm: string | undefined;
+    /** The page a List Command's `run` receives with its input. */
+    readonly page: PageInput;
+    /** The caller's command line and the Command's, for the hint of a confirmation error. */
+    readonly invocation: Invocation;
+    readonly commandLine: string;
+}
+/** How the Command prints data it fails with, which is the data its `run` or `apply` returns. */
+export declare function renderOf(command: Command): (data: unknown, style: Style) => string;
+export declare function execute(command: Command, input: Record<string, unknown>, ctx: Context, { dryRun, confirm, page, invocation, commandLine }: ExecuteFlags): Promise<Outcome>;

package/dist/execute.js

@@ -0,0 +1,26 @@
+import { checkConfirmation } from "./confirm.js";
+function outcomeOf(value, render) {
+    return { value, render: (style) => render(value, style) };
+}
+/** How the Command prints data it fails with, which is the data its `run` or `apply` returns. */
+export function renderOf(command) {
+    // The union of render signatures only accepts the intersection of their data types.
+    return (data, style) => command.render(data, style);
+}
+export async function execute(command, input, ctx, { dryRun, confirm, page, invocation, commandLine }) {
+    if (command.rows !== undefined) {
+        return outcomeOf(await command.run({ ...input, ...page }, ctx), (data, style) => command.render(data, style));
+    }
+    if (command.effect === "read") {
+        return outcomeOf(await command.run(input, ctx), (data, style) => command.render(data, style));
+    }
+    const plan = await command.plan(input, ctx);
+    if (dryRun) {
+        return outcomeOf(plan, (value, style) => command.renderPlan(value, style));
+    }
+    if (command.effect === "destructive") {
+        checkConfirmation({ invocation, commandLine, given: confirm }, command.confirm(plan));
+    }
+    return outcomeOf(await command.apply(plan, ctx), (data, style) => command.render(data, style));
+}
+//# sourceMappingURL=execute.js.map

package/dist/execute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.js","sourceRoot":"","sources":["../src/execute.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAsBjD,SAAS,SAAS,CAAQ,KAAY,EAAE,MAA8C;IACpF,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC;AAC5D,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,QAAQ,CAAC,OAAgB;IACvC,oFAAoF;IACpF,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAE,OAAO,CAAC,MAAkD,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AACnG,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,OAAgB,EAChB,KAA8B,EAC9B,GAAY,EACZ,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAgB;IAEhE,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,SAAS,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,EAAE,GAAG,KAAK,EAAE,GAAG,IAAI,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAC9E,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAC5B,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAC9B,OAAO,SAAS,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;IAChG,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC5C,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,SAAS,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,aAAa,EAAE,CAAC;QACrC,iBAAiB,CAAC,EAAE,UAAU,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,SAAS,CAAC,MAAM,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;AACjG,CAAC"}

package/dist/flags.d.ts

@@ -0,0 +1,50 @@
+import * as z from "zod";
+import type { Command } from "./define.js";
+import { type ListFlagName, type ListSpec } from "./list.js";
+import type { Takes } from "./tokenize.js";
+type Effect = Command["effect"];
+export declare const HELP_FLAG = "--help";
+export declare const HELP_SHORT = "-h";
+export declare const VERSION_FLAG = "--version";
+declare const ROUTING_FLAGS: readonly ["--help", "-h", "--version"];
+export type NameOf<Flag extends string> = Flag extends `--${infer Name}` ? Name : Flag extends `-${infer Name}` ? Name : Flag;
+export interface StandardFlag {
+    /** The flag as the caller types it, such as `--json`. */
+    readonly flag: string;
+    readonly usage: string;
+    readonly description: string;
+    readonly takes: Takes;
+    readonly schema: z.ZodType;
+}
+export declare const JSON_FLAG: StandardFlag & {
+    readonly flag: "--json";
+};
+export declare const DRY_RUN_FLAG: StandardFlag & {
+    readonly flag: "--dry-run";
+};
+export declare const CONFIRM_FLAG: StandardFlag & {
+    readonly flag: "--confirm";
+};
+declare const EFFECT_FLAGS: {
+    readonly read: readonly [StandardFlag & {
+        readonly flag: "--json";
+    }];
+    readonly write: readonly [StandardFlag & {
+        readonly flag: "--json";
+    }, StandardFlag & {
+        readonly flag: "--dry-run";
+    }];
+    readonly destructive: readonly [StandardFlag & {
+        readonly flag: "--json";
+    }, StandardFlag & {
+        readonly flag: "--dry-run";
+    }, StandardFlag & {
+        readonly flag: "--confirm";
+    }];
+};
+export type StandardFlagName = NameOf<(typeof ROUTING_FLAGS)[number]> | NameOf<(typeof EFFECT_FLAGS)[Effect][number]["flag"]> | ListFlagName;
+/** The Standard flags of a Command with this Effect, and of a List Command. */
+export declare function standardFlagsFor(effect: Effect, list: ListSpec | undefined): readonly StandardFlag[];
+/** Throws when the Command declares an arg or option under a Standard flag's name. */
+export declare function checkNoStandardFlags(command: Command): void;
+export {};

package/dist/flags.js

@@ -0,0 +1,59 @@
+import * as z from "zod";
+import { argFields, kebab, optionFields } from "./input.js";
+import { LIST_FLAGS } from "./list.js";
+export const HELP_FLAG = "--help";
+export const HELP_SHORT = "-h";
+export const VERSION_FLAG = "--version";
+// The Runtime reads these at every level of the command line, so no Command can declare them.
+const ROUTING_FLAGS = [HELP_FLAG, HELP_SHORT, VERSION_FLAG];
+function nameOf(flag) {
+    return flag.replace(/^--?/, "");
+}
+function standardFlag(flag, { placeholder, ...rest }) {
+    return { flag, usage: placeholder === undefined ? flag : `${flag} ${placeholder}`, ...rest };
+}
+export const JSON_FLAG = standardFlag("--json", {
+    description: "print the result as JSON",
+    takes: "nothing",
+    schema: z.boolean(),
+});
+export const DRY_RUN_FLAG = standardFlag("--dry-run", {
+    description: "print the Plan without changing anything",
+    takes: "nothing",
+    schema: z.boolean(),
+});
+export const CONFIRM_FLAG = standardFlag("--confirm", {
+    placeholder: "<target>",
+    description: "name the target to confirm the change; an error hint gives the exact command",
+    takes: "value",
+    schema: z.string(),
+});
+const EFFECT_FLAGS = {
+    read: [JSON_FLAG],
+    write: [JSON_FLAG, DRY_RUN_FLAG],
+    destructive: [JSON_FLAG, DRY_RUN_FLAG, CONFIRM_FLAG],
+};
+// Every name is reserved on every Command, whatever flags it gets, so a name means one thing.
+const RESERVED = new Map([...ROUTING_FLAGS, ...EFFECT_FLAGS.destructive.map(({ flag }) => flag), ...LIST_FLAGS].map((flag) => [nameOf(flag), flag]));
+/** The Standard flags of a Command with this Effect, and of a List Command. */
+export function standardFlagsFor(effect, list) {
+    return [...EFFECT_FLAGS[effect], ...(list?.standardFlags ?? [])];
+}
+/** Throws when the Command declares an arg or option under a Standard flag's name. */
+export function checkNoStandardFlags(command) {
+    const declared = [
+        ...argFields(command.args).map(({ key }) => ({ kind: "arg", key })),
+        ...optionFields(command.options).map(({ key }) => ({ kind: "option", key })),
+    ];
+    const lines = declared.flatMap(({ kind, key }) => {
+        const flag = RESERVED.get(kebab(key));
+        return flag === undefined ? [] : [`  ${kind} '${key}' is the Standard flag ${flag}`];
+    });
+    if (lines.length > 0) {
+        throw new Error([
+            `Command '${command.name}' declares Standard flags the Runtime adds; rename them:`,
+            ...lines,
+        ].join("\n"));
+    }
+}
+//# sourceMappingURL=flags.js.map

package/dist/flags.js.map

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

package/dist/global-install.d.ts

@@ -0,0 +1,13 @@
+import { type NpmContext } from "./npm.js";
+/** Where npm installed this copy of the CLI globally. */
+export interface InstalledCopy {
+    readonly prefix: string;
+    readonly packageDir: string;
+}
+/** Where npm puts global packages under its global prefix. */
+export declare function globalModulesDir(prefix: string): 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,51 @@
+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";
+/** Where npm puts global packages under its global prefix. */
+export function globalModulesDir(prefix) {
+    return process.platform === "win32"
+        ? join(prefix, "node_modules")
+        : join(prefix, "lib", "node_modules");
+}
+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 = join(globalModulesDir(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,8DAA8D;AAC9D,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,OAAO,OAAO,CAAC,QAAQ,KAAK,OAAO;QACjC,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,cAAc,CAAC;QAC9B,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC;AAC1C,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,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACvE,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 { CommandSpec, GroupSpec, SpecNode } from "./command-spec.js";
+export declare function cliHelpJson(version: string, root: SpecNode): string;
+export declare function groupHelpJson(group: GroupSpec): string;
+export declare function commandHelpJson(spec: CommandSpec): string;

package/dist/help-json.js

@@ -0,0 +1,44 @@
+import * as z from "zod";
+// Transforms and other unrepresentable parts become `{}` rather than failing the whole help.
+function inputSchema(schema) {
+    return z.toJSONSchema(schema, { io: "input", unrepresentable: "any" });
+}
+// Keys are the names the caller types, so option `greetingWord` reads `greeting-word`.
+function optionsSchema(options) {
+    return inputSchema(z.object(Object.fromEntries(options.map(({ name, schema }) => [name, schema]))));
+}
+function commandData(spec) {
+    return {
+        name: spec.commandLine,
+        description: spec.description,
+        effect: spec.effect,
+        examples: spec.examples,
+        args: inputSchema(spec.command.args ?? z.object({})),
+        options: optionsSchema(spec.options),
+        standardFlags: spec.standardFlags.map(({ usage, description, schema }) => ({
+            usage,
+            description,
+            schema: inputSchema(schema),
+        })),
+        output: spec.output === undefined ? null : z.toJSONSchema(spec.output, { unrepresentable: "any" }),
+    };
+}
+function nodeData(node) {
+    return node.kind === "command" ? commandData(node) : groupData(node);
+}
+function groupData(group) {
+    return { name: group.commandLine, commands: Object.values(group.commands).map(nodeData) };
+}
+function printed(data) {
+    return `${JSON.stringify(data)}\n`;
+}
+export function cliHelpJson(version, root) {
+    return printed({ name: root.commandLine, version, ...nodeData(root) });
+}
+export function groupHelpJson(group) {
+    return printed(groupData(group));
+}
+export function commandHelpJson(spec) {
+    return printed(commandData(spec));
+}
+//# 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":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAMzB,6FAA6F;AAC7F,SAAS,WAAW,CAAC,MAAiB;IACpC,OAAO,CAAC,CAAC,YAAY,CAAC,MAAM,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,CAAC,CAAC;AACzE,CAAC;AAED,uFAAuF;AACvF,SAAS,aAAa,CAAC,OAA8B;IACnD,OAAO,WAAW,CAChB,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAChF,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,IAAiB;IACpC,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,WAAW;QACtB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,IAAI,EAAE,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACpD,OAAO,EAAE,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC;QACpC,aAAa,EAAE,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;YACzE,KAAK;YACL,WAAW;YACX,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC;SAC5B,CAAC,CAAC;QACH,MAAM,EACJ,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,eAAe,EAAE,KAAK,EAAE,CAAC;KAC7F,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CAAC,IAAc;IAC9B,OAAO,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;AACvE,CAAC;AAED,SAAS,SAAS,CAAC,KAAgB;IACjC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,WAAW,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;AAC5F,CAAC;AAED,SAAS,OAAO,CAAC,IAAgB;IAC/B,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAAe,EAAE,IAAc;IACzD,OAAO,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACzE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAgB;IAC5C,OAAO,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAiB;IAC/C,OAAO,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC;AACpC,CAAC"}

package/dist/help.d.ts

@@ -0,0 +1,5 @@
+import type { CommandSpec, GroupSpec } from "./command-spec.js";
+import type { Style } from "./style.js";
+export declare function cliHelp(version: string, root: GroupSpec, style: Style): string;
+export declare function groupHelp(group: GroupSpec, style: Style): string;
+export declare function commandHelp(spec: CommandSpec, style: Style): string;

package/dist/help.js

@@ -0,0 +1,64 @@
+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 node.kind === "command"
+        ? node.description
+        : `group: ${Object.keys(node.commands).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, group, style) {
+    return lines(style.bold(heading), ...section("Commands", commandRows(group), style), "", `Run \`${group.commandLine} <command> --help\` for its examples and input.`);
+}
+export function cliHelp(version, root, style) {
+    return listing(`${root.commandLine} ${version}`, root, style);
+}
+export function groupHelp(group, style) {
+    return listing(group.commandLine, group, 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));
+}
+function flagRow({ usage, description }) {
+    return [usage, description];
+}
+export function commandHelp(spec, style) {
+    return lines(style.bold(spec.commandLine), spec.description, ...section("Examples", spec.examples.map(({ command, note }) => [command, note]), style), ...section("Arguments", spec.args.map(argRow), style), ...section("Options", spec.options.map(optionRow), style), "", `${style.bold("Effect:")} ${spec.effect} (${EFFECT_NOTES[spec.effect]})`, ...section("Standard flags", spec.standardFlags.map(flagRow), 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,12 @@
+export { defineCli } from "./built-ins.js";
+export type { Cli, Command, Commands, Context, DestructiveCommand, DoctorCheck, DoctorFinding, Env, Example, GlobalInstall, ListCommand, 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 "./list.js";
+export { paginate } from "./list.js";
+export type { RunResult } from "./output.js";
+export type { RunOptions } 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 { paginate } from "./list.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;AAgB3C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAElE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAGrC,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 * as z from "zod";
+import type { InputSchema } from "./define.js";
+export type ValueType = "string" | "number" | "boolean";
+export interface InputField {
+    readonly key: string;
+    /** The name the caller sees: the key for an arg, the flag without `--` for an option. */
+    readonly name: string;
+    readonly schema: z.ZodType;
+    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 declare function kebab(key: string): string;
+export declare function optionField(key: string, schema: z.ZodType): InputField;
+export declare function argFields(schema: InputSchema | undefined): InputField[];
+export declare function optionFields(schema: InputSchema | undefined): InputField[];

package/dist/input.js

@@ -0,0 +1,63 @@
+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, name: key, schema, ...describe(schema), label, usage: label };
+}
+export function optionField(key, schema) {
+    const described = describe(schema);
+    const name = kebab(key);
+    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-${name}` : `--${name}`;
+    const usage = isBoolean ? label : `${label} <${described.choices?.join("|") ?? "value"}>`;
+    return { key, name, schema, ...described, label, usage };
+}
+function fieldsOf(schema, toField) {
+    return schema === undefined
+        ? []
+        : Object.entries(schema.shape).map(([key, value]) => toField(key, value));
+}
+export function argFields(schema) {
+    return fieldsOf(schema, argField);
+}
+export function optionFields(schema) {
+    return fieldsOf(schema, optionField);
+}
+//# 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;
+}