@bunizao/cli-kit 0.2.0 → 0.5.0

package/README.md

@@ -57,6 +57,57 @@ await program.parseAsync(args, { from: "user" });
 `insertDefaultVerb` accepts user arguments, not the Node executable and script prefix. It is a
 pure transform and does not mutate the provided array.
 
+Prefer `parseWithPrompts` over calling `parseAsync` yourself. It builds the program, parses,
+and when a person at a terminal left out a trailing positional or a required option, asks for
+it and parses again with the answer appended. `moodle activities list` becomes a unit picker
+instead of `missing required argument 'unit'`. Without a terminal the usage error is thrown
+unchanged, with the command's usage line and argument descriptions as its hint.
+
+```ts
+await parseWithPrompts(() => buildProgram(), args, {
+  ui,
+  fillers: {
+    unit: async ({ ui }) => ui.select("Which unit?", await unitChoices()),
+    task: async ({ provided, ui }) => ui.select("Which task?", await taskChoices(provided.unit)),
+  },
+});
+```
+
+A filler is looked up by argument name; without one, an argument with `.choices()` becomes a
+picker and anything else a text prompt labelled with its description. Fillers see the
+positionals typed so far, including earlier answers, so a task picker can load the chosen
+unit. The factory is called once per round because Commander programs do not parse twice.
+
+## Help
+
+`createProgram` installs one help layout for the family: name and version, usage, the
+commands, options, and a short "Try" list, coloured on a terminal and plain in a pipe.
+`--no-color`, `NO_COLOR` and `FORCE_COLOR` are honoured. Group top-level commands with
+`helpSection` the way `gh` does (core commands first, then the rest), add two or three
+invocations with `examples` (text after two spaces and `#` renders as a comment), and
+give the root a wordmark with `banner`; the art shows only to a person at a terminal.
+
+```ts
+helpSection(program.command("submit"), "Core commands");
+examples(program, ["example units", "example submit UNIT report.pdf  # asks before uploading"]);
+banner(program, EXAMPLE_WORDMARK);
+```
+
+## Theme
+
+`createTheme(enabled)` paints the roles every CLI's human output shares, so a person
+learns once what each colour means: `key` (cyan) is something they can type back, such
+as a unit code or task number; `subject` (bold) is what they gave, such as files or a
+message; `target` (bold cyan) is where it goes; `dim` is a secondary fact; `status`
+colours a word by its `toneOf`, the vocabulary learning sites share ("overdue" is
+danger, "graded" success, "not started" muted, "announcement" accent). Pass the theme
+to `render` and a table gets a dim header, a keyed first column and toned status
+columns; pass `tones` for words the shared list would misread. `ui.banner(art, tagline)`
+opens an onboarding flow with the wordmark.
+
+`isInformationalExit(error)` is true for the help and version exits Commander throws under
+`exitOverride`, including a bare noun with no verb, so the run loop can return 0 for them.
+
 List option flags that consume a separate value in `valueFlags`. This lets the arity counter ignore
 option values when flags are interleaved with positionals. Boolean flags and `--flag=value` do not
 need to be listed.
@@ -118,3 +169,39 @@ a major package release.
 The conformance suite is isolated under `conformance/`. Until all three CLIs have published their
 normalized releases, missing binaries are reported as skipped tests. Its CI workflow installs the
 published packages before running the suite.
+
+## Prompts and progress
+
+`createUi` gives every CLI the same interactive surface, drawn with `@clack/prompts` on
+stderr so `--json` output on stdout stays clean. It only prompts when both stdin and the
+output are terminals; in a pipe, log calls print plain completed lines, spinners print
+their outcome, and every prompt throws a `usage` error that says what to pass instead.
+
+```ts
+const ui = createUi();
+ui.intro("moodle submit");
+const unit = await ui.select("Which unit?", candidates.map((c) => ({ value: c.id, label: c.name, hint: c.code })));
+const spin = ui.spinner();
+spin.start("Uploading 2 files");
+spin.stop("Uploaded 2 files");
+ui.outro("Done");
+```
+
+`select` switches to type-to-filter above `AUTOCOMPLETE_FROM` choices. Ctrl+C inside a
+prompt throws a `cancelled` error (exit 130). `confirm(plan, options)` is built on the same
+layer and keeps its contract: `--dry-run` prints the plan, `--yes` skips the question, a pipe
+without `--yes` is a usage error.
+
+## Human or agent
+
+`detectAudience({ stdin, stdout, env, format })` returns `"human"` only for a person at a
+terminal reading a table: both streams are TTYs, the format is not JSON or YAML, and none
+of `AGENT_ENV_VARS` (`CLI_AGENT`, `CLAUDECODE`, `CI`) is set. Everyone else is an agent and
+gets machine output, no prompts, and errors that name the flag to pass. `createUi` applies
+the same environment rule on its own, so an agent that allocates a pty still never sees a
+prompt. Agents that run commands in a terminal should export `CLI_AGENT=1`.
+
+`ui.password` masks a secret; without a terminal it throws so the caller can point at a
+`--token-stdin` style flag instead. `ui.editor` collects several lines in `$VISUAL` or
+`$EDITOR` the way git collects a commit message, and throws without a terminal so the
+caller can point at a `--body-file` style flag.

package/dist/arguments.d.ts

@@ -0,0 +1,22 @@
+import type { Command } from "commander";
+import type { Ui } from "./ui.js";
+export interface FillContext {
+    readonly command: Command;
+    /** Positionals the person already typed, by argument name, including earlier answers. */
+    readonly provided: Readonly<Record<string, string>>;
+    readonly ui: Ui;
+}
+/** Produces the value for one missing positional. A variadic one may return several tokens. */
+export type ArgumentFiller = (context: FillContext) => Promise<string | readonly string[]>;
+export interface PromptParseOptions {
+    readonly ui: Ui;
+    /** Fillers by argument name (`unit`), consulted before the generic choice or text prompt. */
+    readonly fillers?: Readonly<Record<string, ArgumentFiller>>;
+}
+/**
+ * Parse argv with a freshly built program. When a person at a terminal left out trailing
+ * positionals or a required option, ask for them and parse again with the answers appended,
+ * so `moodle activities list` becomes a unit picker instead of a usage error. Anyone else
+ * gets the usage error, with the command's usage line as the hint.
+ */
+export declare function parseWithPrompts(build: () => Command, argv: readonly string[], options: PromptParseOptions): Promise<void>;

package/dist/arguments.js

@@ -0,0 +1,117 @@
+import { CliError } from "./errors.js";
+// Every round appends at least one token, so this only guards a filler that keeps failing.
+const MAX_ROUNDS = 8;
+/**
+ * Parse argv with a freshly built program. When a person at a terminal left out trailing
+ * positionals or a required option, ask for them and parse again with the answers appended,
+ * so `moodle activities list` becomes a unit picker instead of a usage error. Anyone else
+ * gets the usage error, with the command's usage line as the hint.
+ */
+export async function parseWithPrompts(build, argv, options) {
+    let args = [...argv];
+    for (let round = 0;; round += 1) {
+        const program = build();
+        annotate(program);
+        try {
+            await program.parseAsync(args, { from: "user" });
+            return;
+        }
+        catch (error) {
+            const failing = failingCommand(error);
+            if (!failing)
+                throw error;
+            if (!options.ui.interactive)
+                throw withUsageHint(error, failing.command);
+            if (round >= MAX_ROUNDS)
+                throw error;
+            const answers = await answersFor(failing.command, failing.code, options);
+            if (!answers.length)
+                throw error;
+            args = [...args, ...answers];
+        }
+    }
+}
+const FILLABLE = new Set(["commander.missingArgument", "commander.missingMandatoryOptionValue"]);
+// Commander reports a missing argument without saying which command wanted it, so every
+// command rethrows its own exit with itself attached.
+function annotate(command) {
+    command.exitOverride(error => {
+        throw Object.assign(error, { command });
+    });
+    for (const child of command.commands)
+        annotate(child);
+}
+function failingCommand(error) {
+    if (!error || typeof error !== "object")
+        return undefined;
+    const { code, command } = error;
+    if (typeof code !== "string" || !FILLABLE.has(code) || !command)
+        return undefined;
+    return { command: command, code };
+}
+async function answersFor(command, code, options) {
+    // Commander reports a missing required option before it counts positionals, but a person
+    // expects to name the unit before the title; ask in that order, in one round.
+    const positionals = await fillPositionals(command, options);
+    if (code === "commander.missingArgument")
+        return positionals;
+    return [...positionals, ...(await fillOption(command, options.ui))];
+}
+async function fillPositionals(command, options) {
+    const typed = command.args;
+    const provided = {};
+    command.registeredArguments.forEach((argument, index) => {
+        const value = typed[index];
+        if (value !== undefined)
+            provided[argument.name()] = value;
+    });
+    const answers = [];
+    for (const argument of command.registeredArguments.slice(typed.length)) {
+        // Commander requires the required positionals to come first, so the first optional one ends the asking.
+        if (!argument.required)
+            break;
+        const answer = await answerFor(argument, { command, provided: { ...provided }, ui: options.ui }, options.fillers?.[argument.name()]);
+        const tokens = typeof answer === "string" ? (argument.variadic ? answer.split(/\s+/u) : [answer.trim()]).filter(Boolean) : [...answer];
+        if (!tokens.length)
+            throw new CliError("usage", `${argument.name()} is required.`);
+        provided[argument.name()] = tokens.join(" ");
+        answers.push(...tokens);
+    }
+    return answers;
+}
+function answerFor(argument, context, filler) {
+    if (filler)
+        return filler(context);
+    const message = argument.description || argument.name();
+    if (argument.argChoices)
+        return context.ui.select(message, argument.argChoices.map(value => ({ value, label: value })));
+    return context.ui.text(message, { validate: value => (value.trim() ? undefined : "Required.") });
+}
+async function fillOption(command, ui) {
+    const option = command.options.find(candidate => candidate.mandatory && command.getOptionValue(candidate.attributeName()) === undefined);
+    const flag = option?.long ?? option?.short;
+    if (!option || !flag)
+        return [];
+    const message = option.description || flag;
+    if (!option.required && !option.optional)
+        return (await ui.confirm(message)) ? [flag] : [];
+    const value = option.argChoices
+        ? await ui.select(message, option.argChoices.map(choice => ({ value: choice, label: choice })))
+        : await ui.text(message, { validate: text => (text.trim() ? undefined : "Required.") });
+    return [flag, value.trim()];
+}
+/** The same usage error, plus the usage line an agent needs to correct the call. */
+function withUsageHint(error, command) {
+    if (!(error instanceof Error))
+        return error;
+    const names = [];
+    for (let current = command; current; current = current.parent)
+        names.unshift(current.name());
+    const describe = (item, term) => (item.description ? `  ${term}  ${item.description}` : undefined);
+    const lines = [
+        `Usage: ${names.join(" ")} ${command.usage()}`,
+        ...command.registeredArguments.map(argument => describe(argument, argument.name())),
+        ...command.options.filter(option => option.mandatory).map(option => describe(option, option.flags)),
+    ].filter((line) => Boolean(line));
+    return new CliError("usage", error.message.replace(/^error:\s*/iu, ""), lines.join("\n"));
+}

package/dist/audience.d.ts

@@ -0,0 +1,26 @@
+import type { OutputFormat } from "./output.js";
+/**
+ * Who is on the other end of the command. A human gets tables, prompts and progress;
+ * an agent gets machine output, no prompts, and errors that name the flag to pass.
+ */
+export type Audience = "human" | "agent";
+/**
+ * Environment variables that mark a shell driven by a program even when it has a pty.
+ * `CLAUDECODE` is set by Claude Code's shell, `CI` by every hosted runner, and
+ * `CLI_AGENT` is the documented opt-in for any other agent that allocates a terminal.
+ * The Claude desktop terminal pane sets none of them, so a person there stays human.
+ */
+export declare const AGENT_ENV_VARS: readonly ["CLI_AGENT", "CLAUDECODE", "CI"];
+export interface AudienceInput {
+    readonly stdin?: {
+        readonly isTTY?: boolean | undefined;
+    };
+    readonly stdout?: {
+        readonly isTTY?: boolean | undefined;
+    };
+    readonly env?: NodeJS.ProcessEnv;
+    /** The resolved output format. JSON and YAML are asked for by programs. */
+    readonly format?: OutputFormat;
+}
+export declare function detectAudience(input?: AudienceInput): Audience;
+export declare function isAgentEnvironment(env?: NodeJS.ProcessEnv): boolean;

package/dist/audience.js

@@ -0,0 +1,28 @@
+/**
+ * Environment variables that mark a shell driven by a program even when it has a pty.
+ * `CLAUDECODE` is set by Claude Code's shell, `CI` by every hosted runner, and
+ * `CLI_AGENT` is the documented opt-in for any other agent that allocates a terminal.
+ * The Claude desktop terminal pane sets none of them, so a person there stays human.
+ */
+export const AGENT_ENV_VARS = ["CLI_AGENT", "CLAUDECODE", "CI"];
+export function detectAudience(input = {}) {
+    if (input.format && input.format !== "table")
+        return "agent";
+    const stdin = input.stdin ?? process.stdin;
+    const stdout = input.stdout ?? process.stdout;
+    if (!stdin.isTTY || !stdout.isTTY)
+        return "agent";
+    const env = input.env ?? process.env;
+    if (AGENT_ENV_VARS.some((name) => isSet(env[name])))
+        return "agent";
+    return "human";
+}
+export function isAgentEnvironment(env = process.env) {
+    return AGENT_ENV_VARS.some((name) => isSet(env[name]));
+}
+function isSet(value) {
+    if (value === undefined)
+        return false;
+    const normalized = value.trim().toLowerCase();
+    return normalized !== "" && normalized !== "0" && normalized !== "false";
+}

package/dist/color.d.ts

@@ -0,0 +1,14 @@
+import { styleText } from "node:util";
+export type Paint = (format: Parameters<typeof styleText>[0], text: string) => string;
+interface ColorStream {
+    readonly isTTY?: boolean;
+    hasColors?(): boolean;
+}
+/**
+ * Whether a stream should get ANSI colour. NO_COLOR and FORCE_COLOR win, as Commander
+ * and Node both agree; otherwise only a terminal that reports colour support.
+ */
+export declare function colorEnabled(stream: ColorStream | undefined, env?: NodeJS.ProcessEnv): boolean;
+/** A paint function that colours when asked and is the identity otherwise, so callers never branch. */
+export declare function painter(enabled: boolean): Paint;
+export {};

package/dist/color.js

@@ -0,0 +1,19 @@
+import { styleText } from "node:util";
+/**
+ * Whether a stream should get ANSI colour. NO_COLOR and FORCE_COLOR win, as Commander
+ * and Node both agree; otherwise only a terminal that reports colour support.
+ */
+export function colorEnabled(stream, env = process.env) {
+    if (env.NO_COLOR || env.FORCE_COLOR === "0" || env.FORCE_COLOR === "false")
+        return false;
+    if (env.FORCE_COLOR || env.CLICOLOR_FORCE !== undefined)
+        return true;
+    return Boolean(stream?.isTTY) && (stream?.hasColors?.() ?? true);
+}
+/** A paint function that colours when asked and is the identity otherwise, so callers never branch. */
+export function painter(enabled) {
+    if (!enabled)
+        return (_format, text) => text;
+    // The caller has already decided from the right stream; styleText must not second-guess it.
+    return (format, text) => styleText(format, text, { validateStream: false });
+}

package/dist/confirm.d.ts

@@ -1,8 +1,14 @@
+import { type UiOptions } from "./ui.js";
 export interface MutationPlan {
     readonly summary: string;
 }
+/**
+ * The gate every mutating command passes through. `--dry-run` prints the plan and
+ * stops, `--yes` skips the question, and a pipe without `--yes` is an error rather
+ * than a hang. Only a person at a terminal is ever asked.
+ */
 export declare function confirm(plan: MutationPlan, options: {
     yes: boolean;
     dryRun: boolean;
     interactive: boolean;
-}): Promise<boolean>;
+} & Pick<UiOptions, "input" | "output">): Promise<boolean>;

package/dist/confirm.js

@@ -1,8 +1,14 @@
-import { createInterface } from "node:readline/promises";
 import { CliError } from "./errors.js";
+import { createUi } from "./ui.js";
+/**
+ * The gate every mutating command passes through. `--dry-run` prints the plan and
+ * stops, `--yes` skips the question, and a pipe without `--yes` is an error rather
+ * than a hang. Only a person at a terminal is ever asked.
+ */
 export async function confirm(plan, options) {
+    const output = options.output ?? process.stderr;
     if (options.dryRun) {
-        process.stderr.write(`${plan.summary}\n`);
+        output.write(`${plan.summary}\n`);
         return false;
     }
     if (options.yes)
@@ -10,13 +16,7 @@ export async function confirm(plan, options) {
     if (!options.interactive) {
         throw new CliError("usage", "Mutation requires --yes when stdin is not interactive.");
     }
-    process.stderr.write(`${plan.summary}\n`);
-    const prompt = createInterface({ input: process.stdin, output: process.stderr });
-    try {
-        const answer = await prompt.question("Continue? y/N ");
-        return answer.trim().toLowerCase() === "y";
-    }
-    finally {
-        prompt.close();
-    }
+    const ui = createUi({ interactive: true, ...(options.input ? { input: options.input } : {}), output });
+    ui.note(plan.summary, "Plan");
+    return ui.confirm("Continue?");
 }

package/dist/errors.d.ts

@@ -6,5 +6,7 @@ export declare class CliError extends Error {
     readonly hint: string | undefined;
     constructor(code: ErrorCode, message: string, hint?: string);
 }
+/** Commander's help and version exits: the output is already written and nothing failed. */
+export declare function isInformationalExit(error: unknown): boolean;
 export declare function exitCodeFor(code: ErrorCode): number;
 export declare function normalizeError(error: unknown): CliError;

package/dist/errors.js

@@ -28,6 +28,15 @@ export class CliError extends Error {
         this.hint = hint;
     }
 }
+/** Commander's help and version exits: the output is already written and nothing failed. */
+export function isInformationalExit(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    if ("exitCode" in error && error.exitCode === 0)
+        return true;
+    const code = "code" in error ? String(error.code) : "";
+    return code.startsWith("commander.help") || code === "commander.version";
+}
 export function exitCodeFor(code) {
     return EXIT_CODES[code];
 }

package/dist/help.d.ts

@@ -0,0 +1,20 @@
+import type { Command, Help } from "commander";
+/**
+ * List a subcommand under `title` in its parent's help instead of the one flat list.
+ * Sections appear in the order they were first named and commands in the order they
+ * were placed, so the caller decides what comes first however the tree was registered.
+ */
+export declare function helpSection(command: Command, title: string): Command;
+/** A few invocations shown under "Try" in the command's help; text after `  # ` renders as a comment. */
+export declare function examples(command: Command, lines: readonly string[]): Command;
+/**
+ * ASCII art shown above the root help page, but only to a person: a pipe and an agent
+ * get the plain header, because art in a transcript is noise.
+ */
+export declare function banner(command: Command, art: string): Command;
+/**
+ * The help layout every CLI in the family shares: name and version, a usage line, the
+ * commands grouped by section, then options and examples. Colour follows the output
+ * stream, so a pipe and an agent get the same text without escape codes.
+ */
+export declare function styledHelp(): Partial<Help>;

package/dist/help.js

@@ -0,0 +1,182 @@
+import { painter } from "./color.js";
+const sections = new WeakMap();
+const sectionOrder = new WeakMap();
+const sectionRank = new WeakMap();
+let nextRank = 0;
+const exampleLines = new WeakMap();
+const banners = new WeakMap();
+/**
+ * List a subcommand under `title` in its parent's help instead of the one flat list.
+ * Sections appear in the order they were first named and commands in the order they
+ * were placed, so the caller decides what comes first however the tree was registered.
+ */
+export function helpSection(command, title) {
+    sections.set(command, title);
+    sectionRank.set(command, nextRank++);
+    if (command.parent) {
+        const order = sectionOrder.get(command.parent) ?? [];
+        if (!order.includes(title))
+            sectionOrder.set(command.parent, [...order, title]);
+    }
+    return command;
+}
+/** A few invocations shown under "Try" in the command's help; text after `  # ` renders as a comment. */
+export function examples(command, lines) {
+    exampleLines.set(command, lines);
+    return command;
+}
+/**
+ * ASCII art shown above the root help page, but only to a person: a pipe and an agent
+ * get the plain header, because art in a transcript is noise.
+ */
+export function banner(command, art) {
+    banners.set(command, art.replace(/^\n+|\s+$/gu, ""));
+    return command;
+}
+/**
+ * The help layout every CLI in the family shares: name and version, a usage line, the
+ * commands grouped by section, then options and examples. Colour follows the output
+ * stream, so a pipe and an agent get the same text without escape codes.
+ */
+export function styledHelp() {
+    return {
+        prepareContext(context) {
+            this.helpWidth = this.helpWidth ?? context.helpWidth ?? 80;
+            this.hasColors = context.outputHasColors ?? false;
+            // Commander reports a width only for a terminal; forced colour means a person asked for the styled page.
+            this.terminal = typeof context.helpWidth === "number" || Boolean(context.outputHasColors);
+        },
+        formatHelp(command, helper) {
+            const styled = helper;
+            return formatHelp(command, helper, painter(Boolean(styled.hasColors)), Boolean(styled.terminal));
+        },
+    };
+}
+function formatHelp(command, helper, paint, terminal) {
+    const blocks = [];
+    const width = helper.helpWidth ?? 80;
+    const title = (text) => paint("bold", text);
+    const list = (items) => {
+        const termWidth = Math.max(...items.map(item => helper.displayWidth(item.term)));
+        return items.map(item => helper.formatItem(item.term, termWidth, tidy(item.description), helper));
+    };
+    const version = command.parent ? undefined : command.version();
+    const art = command.parent ? undefined : banners.get(command);
+    if (art && terminal) {
+        // The wordmark is the name; the version rides on the description line instead of a second header.
+        blocks.push(...art.split("\n").map(line => paint("cyan", line)), "");
+        if (command.description())
+            blocks.push(`${helper.boxWrap(tidy(command.description()), width)}${version ? `  ${paint("dim", `v${version}`)}` : ""}`);
+    }
+    else {
+        blocks.push(`${paint("bold", commandPath(command))}${version ? ` ${paint("dim", `v${version}`)}` : ""}`);
+        if (command.description())
+            blocks.push(helper.boxWrap(tidy(command.description()), width));
+    }
+    blocks.push("");
+    // Commander's own usage line repeats the aliases ("units|courses"); the path is enough.
+    blocks.push(title("Usage"), `  ${styleUsage(`${commandPath(command)} ${command.usage()}`, paint)}`, "");
+    const args = helper.visibleArguments(command);
+    if (args.length) {
+        blocks.push(title("Arguments"), ...list(args.map(argument => ({ term: paint("bold", helper.argumentTerm(argument)), description: helper.argumentDescription(argument) }))), "");
+    }
+    // The implicit help command is not one of `command.commands`; the footer already says how to get help.
+    const commands = helper.visibleCommands(command).filter(child => command.commands.includes(child));
+    const groups = new Map();
+    for (const heading of sectionOrder.get(command) ?? [])
+        groups.set(heading, []);
+    const placed = [...commands].sort((a, b) => (sectionRank.get(a) ?? Infinity) - (sectionRank.get(b) ?? Infinity));
+    for (const child of placed) {
+        const heading = sections.get(child) ?? "Commands";
+        groups.set(heading, [...(groups.get(heading) ?? []), child]);
+    }
+    const termWidth = commands.length ? Math.max(...commands.map(child => helper.displayWidth(subcommandTerm(child, paint)))) : 0;
+    for (const [heading, children] of groups) {
+        if (!children.length)
+            continue;
+        blocks.push(title(heading), ...children.map(child => helper.formatItem(subcommandTerm(child, paint), termWidth, tidy(helper.subcommandDescription(child)), helper)), "");
+    }
+    // A section holding nothing but --help says nothing.
+    const options = helper.visibleOptions(command);
+    if (options.some(option => option.long !== "--help")) {
+        blocks.push(title("Options"), ...list(options.map(option => ({ term: paint("cyan", helper.optionTerm(option)), description: helper.optionDescription(option) }))), "");
+    }
+    const lines = exampleLines.get(command);
+    if (lines?.length) {
+        blocks.push(title("Try"), ...lines.map(line => `  ${styleExample(line, paint)}`), "");
+    }
+    // Root options apply after any subcommand too; a subcommand page names them once, without repeating the table.
+    const root = rootOf(command);
+    const globals = command.parent ? helper.visibleOptions(root).filter(option => option.long !== "--help" && option.long !== "--version") : [];
+    if (globals.length) {
+        blocks.push(title("Global options"), ...wrapItems(globals.map(longFlag), width - 2).map(line => `  ${paint("dim", line)}`), "");
+    }
+    if (commands.length)
+        blocks.push(paint("dim", `Run '${commandPath(command)} <command> --help' for details on a command.`), "");
+    return `${blocks.join("\n").trimEnd()}\n`;
+}
+// "-o, --output <file>" reads as "--output <file>": the long flag with its own placeholder.
+function longFlag(option) {
+    return option.flags.split(/,\s*/u).find(part => part.startsWith("--")) ?? option.flags;
+}
+// Wrap flag by flag, so "--limit <number>" never splits across lines the way word wrapping would.
+function wrapItems(items, width) {
+    const lines = [];
+    let line = "";
+    for (const item of items) {
+        const joined = line ? `${line}, ${item}` : item;
+        if (line && joined.length > width) {
+            lines.push(`${line},`);
+            line = item;
+        }
+        else {
+            line = joined;
+        }
+    }
+    if (line)
+        lines.push(line);
+    return lines;
+}
+function rootOf(command) {
+    let current = command;
+    while (current.parent)
+        current = current.parent;
+    return current;
+}
+const EXTRAS = /( \((?:choices|default|env|preset):[^]*\))$/u;
+/** A one-sentence description reads as a man page does, without its full stop; prose keeps it. */
+function tidy(description) {
+    const match = EXTRAS.exec(description);
+    const body = match ? description.slice(0, match.index) : description;
+    const single = !/[.!?]\s+\S/u.test(body);
+    return `${single ? body.replace(/\.$/u, "") : body}${match ? match[1] : ""}`;
+}
+function commandPath(command) {
+    const names = [];
+    for (let current = command; current; current = current.parent)
+        names.unshift(current.name());
+    return names.join(" ");
+}
+function subcommandTerm(command, paint) {
+    const aliases = command.aliases().length ? paint("dim", `, ${command.aliases().join(", ")}`) : "";
+    const args = command.registeredArguments.map(argument => ` ${paint("dim", argumentTerm(argument))}`).join("");
+    return `${paint("bold", command.name())}${aliases}${args}`;
+}
+function argumentTerm(argument) {
+    const name = `${argument.name()}${argument.variadic ? "..." : ""}`;
+    return argument.required ? `<${name}>` : `[${name}]`;
+}
+function styleUsage(usage, paint) {
+    // "moodle activities list [options] <unit>": the command words in bold, the rest dimmed.
+    const words = usage.split(" ");
+    const first = words.findIndex(word => word.startsWith("[") || word.startsWith("<"));
+    const names = first === -1 ? words : words.slice(0, first);
+    const rest = first === -1 ? [] : words.slice(first);
+    return [paint("bold", names.join(" ")), ...rest.map(word => paint("dim", word))].join(" ");
+}
+function styleExample(line, paint) {
+    const comment = line.indexOf("  # ");
+    if (comment === -1)
+        return line;
+    return `${line.slice(0, comment)}  ${paint("dim", line.slice(comment + 2))}`;
+}

package/dist/index.d.ts

@@ -1,6 +1,12 @@
+export * from "./arguments.js";
+export * from "./audience.js";
+export * from "./color.js";
 export * from "./confirm.js";
 export * from "./errors.js";
+export * from "./help.js";
 export * from "./nouns.js";
 export * from "./output.js";
 export * from "./program.js";
 export * from "./report.js";
+export * from "./ui.js";
+export * from "./theme.js";

package/dist/index.js

@@ -1,6 +1,12 @@
+export * from "./arguments.js";
+export * from "./audience.js";
+export * from "./color.js";
 export * from "./confirm.js";
 export * from "./errors.js";
+export * from "./help.js";
 export * from "./nouns.js";
 export * from "./output.js";
 export * from "./program.js";
 export * from "./report.js";
+export * from "./ui.js";
+export * from "./theme.js";

package/dist/output.d.ts

@@ -1,3 +1,4 @@
+import type { Theme, Tone } from "./theme.js";
 export type OutputFormat = "table" | "json" | "yaml";
 export interface FormatOptions {
     readonly json?: boolean;
@@ -6,6 +7,8 @@ export interface FormatOptions {
     readonly fields?: string;
 }
 export declare function resolveFormat(options: FormatOptions, isTty: boolean): OutputFormat;
+/** The format a command will use, read from raw argv before Commander has parsed anything. */
+export declare function formatFromArgv(argv: readonly string[], isTty: boolean): OutputFormat;
 export declare function render(value: unknown, options: {
     format: OutputFormat;
     fields?: readonly string[];
@@ -14,6 +17,10 @@ export declare function render(value: unknown, options: {
     width?: number;
     /** Indent JSON. Readable on a terminal, wasted bytes in a pipe. */
     pretty?: boolean;
+    /** Colour the table: dim headers, the first column as a key, status-like columns by tone. */
+    theme?: Theme;
+    /** The caller's own status words, when the shared vocabulary would misread them. */
+    tones?: Readonly<Record<string, Tone>>;
 }): string;
 export declare function writeOutput(text: string, options: {
     output?: string;

package/dist/output.js

@@ -8,6 +8,17 @@ export function resolveFormat(options, isTty) {
     }
     return selected[0] ?? (isTty ? "table" : "json");
 }
+/** The format a command will use, read from raw argv before Commander has parsed anything. */
+export function formatFromArgv(argv, isTty) {
+    const end = argv.indexOf("--");
+    const tokens = new Set(end === -1 ? argv : argv.slice(0, end));
+    try {
+        return resolveFormat({ json: tokens.has("--json"), yaml: tokens.has("--yaml"), table: tokens.has("--table") }, isTty);
+    }
+    catch {
+        return isTty ? "table" : "json";
+    }
+}
 export function render(value, options) {
     const filtered = options.fields?.length ? selectFields(value, options.fields) : value;
     if (options.format === "json") {
@@ -15,7 +26,7 @@ export function render(value, options) {
     }
     if (options.format === "yaml")
         return stringifyYaml(filtered);
-    return renderTable(filtered, options.columns, options.width);
+    return renderTable(filtered, options.columns, options.width, options.theme, options.tones);
 }
 export async function writeOutput(text, options) {
     if (options.output) {
@@ -45,7 +56,9 @@ function selectFields(value, fields) {
 /** Narrower than this and a column carries no information, so overflow is the lesser evil. */
 const MIN_COLUMN = 8;
 const GAP = "  ";
-function renderTable(value, columns, width) {
+/** Columns whose cells are status words rather than names, so their colour carries meaning. */
+const STATUS_COLUMN = /status|state|type|kind|category|grade|role|due/iu;
+function renderTable(value, columns, width, theme, tones) {
     const rows = Array.isArray(value) ? value : [value];
     if (rows.length === 0)
         return "";
@@ -55,8 +68,17 @@ function renderTable(value, columns, width) {
     const values = rows.map((row) => selected.map(([key]) => formatCell(valueAt(row, key))));
     const natural = selected.map(([, label], index) => Math.max(label.length, ...values.map((row) => row[index]?.length ?? 0)));
     const widths = fitWidths(natural, width);
-    const line = (cells) => cells.map((cell, index) => truncate(cell, widths[index] ?? 0).padEnd(widths[index] ?? 0)).join(GAP).trimEnd();
-    return `${line(selected.map(([, label]) => label))}\n${values.map(line).join("\n")}\n`;
+    // Padding is measured on the plain text; colour is wrapped around the padded cell afterwards.
+    const line = (cells, paint) => cells.map((cell, index) => {
+        const fitted = truncate(cell, widths[index] ?? 0);
+        return paint(index === cells.length - 1 ? fitted : fitted.padEnd(widths[index] ?? 0), index);
+    }).join(GAP).trimEnd();
+    const plain = (cell) => cell;
+    const cellPaint = theme
+        ? (cell, index) => index === 0 ? theme.key(cell) : STATUS_COLUMN.test(selected[index]?.[0] ?? "") ? theme.status(cell, tones) : cell
+        : plain;
+    const header = line(selected.map(([, label]) => label), theme ? cell => theme.dim(cell) : plain);
+    return `${header}\n${values.map(row => line(row, cellPaint)).join("\n")}\n`;
 }
 /** A column key may reach into a nested object, as "unit.code". */
 function valueAt(row, key) {

package/dist/program.js

@@ -1,4 +1,6 @@
 import { Command } from "commander";
+import { colorEnabled } from "./color.js";
+import { styledHelp } from "./help.js";
 export const VERBS = ["list", "show", "read", "get", "search", "send", "submit", "set", "mark-read"];
 const VERB_SET = new Set(VERBS);
 const mutations = new WeakSet();
@@ -8,15 +10,15 @@ const ACTIONS = {
     skills: new Set(["generate", "add"]),
 };
 export function createProgram(meta) {
-    return new Command()
+    const program = new Command()
         .name(meta.name)
-        .version(meta.version, "-V, --version")
+        .version(meta.version, "-V, --version", "Show the version")
         .description(meta.description)
-        .helpOption("-h, --help")
-        .addHelpCommand(true)
+        .helpOption("-h, --help", "Show help")
+        .helpCommand("help [command]", "Show help for a command")
         .showSuggestionAfterError()
         .exitOverride()
-        .configureOutput({ outputError: () => undefined })
+        .configureHelp(styledHelp())
         .option("--json", "Emit JSON")
         .option("--yaml", "Emit YAML")
         .option("--table", "Emit a human-readable table")
@@ -26,6 +28,12 @@ export function createProgram(meta) {
         .option("--no-color", "Disable color output")
         .option("-y, --yes", "Confirm mutations non-interactively")
         .option("--dry-run", "Print the mutation plan without applying it");
+    program.configureOutput({
+        outputError: () => undefined,
+        getOutHasColors: () => program.opts().color !== false && colorEnabled(process.stdout),
+        getErrHasColors: () => program.opts().color !== false && colorEnabled(process.stderr),
+    });
+    return program;
 }
 export function mutating(command) {
     mutations.add(command);

package/dist/theme.d.ts

@@ -0,0 +1,28 @@
+/** What a status word means to the person reading it, independent of the site that produced it. */
+export type Tone = "success" | "warning" | "danger" | "info" | "accent" | "muted";
+/**
+ * The roles a line of human output is made of. Every CLI in the family paints the
+ * same role the same way, so a person learns once that cyan is something they can
+ * type back (a unit code, a task number, an option) and bold is what they gave.
+ */
+export interface Theme {
+    readonly enabled: boolean;
+    /** An identifier the person will type again: a unit code, a task number, an id. */
+    key(text: string): string;
+    /** The thing being acted on: the files, the message, the title. */
+    subject(text: string): string;
+    /** Where it goes: the assignment, the thread, the unit. */
+    target(text: string): string;
+    /** Secondary facts: dates, counts, urls, labels. */
+    dim(text: string): string;
+    tone(tone: Tone, text: string): string;
+    /** A status word coloured by what it means; unknown words stay plain. */
+    status(text: string, overrides?: Readonly<Record<string, Tone>>): string;
+}
+/**
+ * The tone a status word carries. The vocabulary is the one learning sites share
+ * ("overdue", "graded", "not started", "announcement"); a caller with its own words
+ * passes them in `overrides`, matched whole and case-insensitively, before the shared list.
+ */
+export declare function toneOf(text: string, overrides?: Readonly<Record<string, Tone>>): Tone | undefined;
+export declare function createTheme(enabled: boolean): Theme;

package/dist/theme.js

@@ -0,0 +1,49 @@
+import { painter } from "./color.js";
+const TONE_STYLE = {
+    success: "green",
+    warning: "yellow",
+    danger: "red",
+    info: "blue",
+    accent: "magenta",
+    muted: "dim",
+};
+// Checked in order: a negated word ("not graded") must win over the word it contains.
+const TONE_WORDS = [
+    ["muted", /^(?:-|—|none|n\/a|unknown)$|\b(?:not[ _](?:started|submitted|graded|attempted|available|yet)|no submission|un(?:attempted|graded|submitted)|archived|hidden|unlisted|inactive|closed|disabled)\b/iu],
+    ["danger", /\b(?:overdue|late|fail(?:ed|ure)?|error|missing|rejected|need(?:s)?[ _]help|blocked|expired|redo|resubmit|demonstrate|exceeded)\b/iu],
+    ["warning", /\b(?:pending|draft|working|in[ _]progress|due soon|today|tomorrow|awaiting|unanswered|scheduled|discuss|attempted|partial)\b/iu],
+    ["success", /\b(?:complete[d]?|done|submitted|graded|accepted|passed|resolved|answered|ready[ _]for[ _]feedback|active|signed in|ok|success(?:ful)?|enrolled)\b/iu],
+    ["accent", /\b(?:announcement|pinned|staff|endorsed|official|urgent)\b/iu],
+    ["info", /\b(?:question|post|note|general|info)\b/iu],
+];
+/**
+ * The tone a status word carries. The vocabulary is the one learning sites share
+ * ("overdue", "graded", "not started", "announcement"); a caller with its own words
+ * passes them in `overrides`, matched whole and case-insensitively, before the shared list.
+ */
+export function toneOf(text, overrides) {
+    const normalized = text.trim().toLowerCase();
+    if (!normalized)
+        return undefined;
+    if (overrides) {
+        for (const [word, tone] of Object.entries(overrides))
+            if (word.toLowerCase() === normalized)
+                return tone;
+    }
+    return TONE_WORDS.find(([, pattern]) => pattern.test(normalized))?.[0];
+}
+export function createTheme(enabled) {
+    const paint = painter(enabled);
+    return {
+        enabled,
+        key: text => paint("cyan", text),
+        subject: text => paint("bold", text),
+        target: text => paint(["bold", "cyan"], text),
+        dim: text => paint("dim", text),
+        tone: (tone, text) => paint(TONE_STYLE[tone], text),
+        status(text, overrides) {
+            const tone = toneOf(text, overrides);
+            return tone ? paint(TONE_STYLE[tone], text) : text;
+        },
+    };
+}

package/dist/ui.d.ts

@@ -0,0 +1,83 @@
+import type { Writable } from "node:stream";
+/**
+ * One choice offered to `select`. `hint` renders dimmed next to the label, so it is
+ * the place for the secondary fact a person needs to tell two similar rows apart
+ * (a unit code, a due date), never for an id.
+ */
+export interface Choice<T> {
+    readonly value: T;
+    readonly label: string;
+    readonly hint?: string;
+}
+export interface UiOptions {
+    /** Keyboard input. Defaults to `process.stdin`. */
+    readonly input?: NodeJS.ReadStream;
+    /** Where prompts and progress draw. Defaults to `process.stderr` so `--json` stdout stays clean. */
+    readonly output?: Writable;
+    /** Force the interactive or plain path instead of detecting it from the streams and environment. */
+    readonly interactive?: boolean;
+    /** Environment consulted for agent markers. Defaults to `process.env`. */
+    readonly env?: NodeJS.ProcessEnv;
+    /** Aborting it cancels whichever prompt is open. */
+    readonly signal?: AbortSignal;
+    /** The command `editor` runs instead of $VISUAL or $EDITOR; the file path is appended. */
+    readonly editor?: string;
+}
+export interface Spinner {
+    start(message: string): void;
+    /** Replace the running text without ending the step. */
+    message(message: string): void;
+    /** End the step and leave `message` (or the last running text) as the permanent line. */
+    stop(message?: string): void;
+    error(message?: string): void;
+}
+export interface Ui {
+    readonly interactive: boolean;
+    /**
+     * The CLI's wordmark, for the first screen a person sees (onboarding, a guided setup).
+     * A pipe gets the tagline alone, so a transcript never carries the art.
+     */
+    banner(art: string, tagline?: string): void;
+    intro(title: string): void;
+    outro(message: string): void;
+    step(message: string): void;
+    info(message: string): void;
+    warn(message: string): void;
+    note(message: string, title?: string): void;
+    spinner(): Spinner;
+    /**
+     * Let the person pick one row. Above `AUTOCOMPLETE_FROM` choices the list becomes
+     * type-to-filter, because arrowing through thirty forum threads is not a picker.
+     * Without a terminal this throws a usage error that lists the choices.
+     */
+    select<T>(message: string, choices: readonly Choice<T>[]): Promise<T>;
+    /** Yes or no. Without a terminal this throws a usage error. */
+    confirm(message: string, options?: {
+        readonly initial?: boolean;
+    }): Promise<boolean>;
+    /** One line of text. Without a terminal this returns `options.initial` or throws. */
+    text(message: string, options?: {
+        readonly placeholder?: string;
+        readonly initial?: string;
+        readonly validate?: (value: string) => string | undefined;
+    }): Promise<string>;
+    /** One secret, echoed as dots. Without a terminal this throws; callers offer a stdin flag instead. */
+    password(message: string): Promise<string>;
+    /**
+     * Several lines, written in the person's $VISUAL or $EDITOR the way git asks for a
+     * commit message. Returns the file as saved. Without a terminal this throws; callers
+     * offer a file or stdin flag instead.
+     */
+    editor(message: string, options?: {
+        readonly initial?: string;
+        readonly extension?: string;
+    }): Promise<string>;
+}
+export declare const AUTOCOMPLETE_FROM = 8;
+/**
+ * Every CLI in the family draws the same way: prompts, steps and spinners on stderr
+ * in the clack style when a person is at the keyboard; plain completed lines when the
+ * output is a pipe; and never a prompt without a terminal, because a hung agent is
+ * worse than an error that says what to pass.
+ */
+export declare function createUi(options?: UiOptions): Ui;

package/dist/ui.js

@@ -0,0 +1,125 @@
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import * as clack from "@clack/prompts";
+import { isAgentEnvironment } from "./audience.js";
+import { colorEnabled, painter } from "./color.js";
+import { CliError } from "./errors.js";
+export const AUTOCOMPLETE_FROM = 8;
+/**
+ * Every CLI in the family draws the same way: prompts, steps and spinners on stderr
+ * in the clack style when a person is at the keyboard; plain completed lines when the
+ * output is a pipe; and never a prompt without a terminal, because a hung agent is
+ * worse than an error that says what to pass.
+ */
+export function createUi(options = {}) {
+    const input = options.input ?? process.stdin;
+    const output = options.output ?? process.stderr;
+    const interactive = options.interactive
+        ?? (Boolean(input.isTTY) && Boolean(output.isTTY) && !isAgentEnvironment(options.env));
+    const common = { input, output, ...(options.signal ? { signal: options.signal } : {}) };
+    const plain = (text) => output.write(`${text}\n`);
+    const paint = painter(colorEnabled(output, options.env));
+    return {
+        interactive,
+        banner(art, tagline) {
+            if (!interactive) {
+                if (tagline)
+                    plain(tagline);
+                return;
+            }
+            const lines = art.replace(/^\n+|\s+$/gu, "").split("\n").map(line => paint("cyan", line));
+            output.write(`${lines.join("\n")}\n${tagline ? `${paint("dim", tagline)}\n` : ""}\n`);
+        },
+        intro: title => (interactive ? clack.intro(title, common) : plain(title)),
+        outro: message => (interactive ? clack.outro(message, common) : plain(message)),
+        step: message => (interactive ? clack.log.step(message, common) : plain(message)),
+        info: message => (interactive ? clack.log.info(message, common) : plain(message)),
+        warn: message => (interactive ? clack.log.warn(message, common) : plain(`warning: ${message}`)),
+        note: (message, title) => (interactive ? clack.note(message, title, common) : plain(title ? `${title}\n${message}` : message)),
+        spinner() {
+            if (interactive) {
+                const inner = clack.spinner(common);
+                return {
+                    start: message => inner.start(message),
+                    message: message => inner.message(message),
+                    stop: message => inner.stop(message),
+                    error: message => inner.error(message),
+                };
+            }
+            // A pipe is read after the fact: only the outcome of a step is worth a line.
+            let running = "";
+            return {
+                start: message => { running = message; },
+                message: message => { running = message; },
+                stop: message => plain(message ?? running),
+                error: message => plain(`error: ${message ?? running}`),
+            };
+        },
+        async select(message, choices) {
+            if (!choices.length)
+                throw new CliError("unexpected", `Nothing to choose for "${message}".`);
+            if (!interactive) {
+                throw new CliError("usage", `${message} needs a terminal to choose from ${choices.length} options.`, choices.map(c => c.label).join(", "));
+            }
+            // `Option<T>` is conditional on T being primitive, which an open generic cannot resolve.
+            const list = choices.map(c => ({ value: c.value, label: c.label, ...(c.hint ? { hint: c.hint } : {}) }));
+            const picked = choices.length >= AUTOCOMPLETE_FROM
+                ? await clack.autocomplete({ message, options: list, placeholder: "Type to filter", maxItems: AUTOCOMPLETE_FROM, ...common })
+                : await clack.select({ message, options: list, ...common });
+            return unwrap(picked);
+        },
+        async confirm(message, confirmOptions = {}) {
+            if (!interactive)
+                throw new CliError("usage", `${message} needs a terminal to answer; pass --yes to confirm non-interactively.`);
+            return unwrap(await clack.confirm({ message, initialValue: confirmOptions.initial ?? false, ...common }));
+        },
+        async text(message, textOptions = {}) {
+            if (!interactive) {
+                if (textOptions.initial !== undefined)
+                    return textOptions.initial;
+                throw new CliError("usage", `${message} needs a terminal to answer.`);
+            }
+            const answer = await clack.text({
+                message,
+                ...(textOptions.placeholder !== undefined ? { placeholder: textOptions.placeholder } : {}),
+                ...(textOptions.initial !== undefined ? { defaultValue: textOptions.initial, initialValue: textOptions.initial } : {}),
+                ...(textOptions.validate ? { validate: (value) => textOptions.validate?.(value ?? "") } : {}),
+                ...common,
+            });
+            return unwrap(answer);
+        },
+        async password(message) {
+            if (!interactive)
+                throw new CliError("usage", `${message} needs a terminal to enter a secret.`);
+            return unwrap(await clack.password({ message, ...common }));
+        },
+        async editor(message, editorOptions = {}) {
+            if (!interactive)
+                throw new CliError("usage", `${message} needs a terminal to open an editor.`);
+            const env = options.env ?? process.env;
+            const command = options.editor ?? env.VISUAL ?? env.EDITOR ?? (process.platform === "win32" ? "notepad" : "vi");
+            const dir = mkdtempSync(join(tmpdir(), "cli-kit-"));
+            const file = join(dir, `message${editorOptions.extension ?? ".md"}`);
+            try {
+                writeFileSync(file, editorOptions.initial ?? "", "utf8");
+                clack.log.step(`${message}: opening ${command}, save and close to continue.`, common);
+                // The editor owns the terminal until it exits; a shell lets "code --wait" style values work.
+                const result = spawnSync(`${command} "${file}"`, { stdio: "inherit", shell: true });
+                if (result.status !== 0)
+                    throw new CliError("cancelled", `${command} exited with status ${result.status ?? "unknown"}.`);
+                return readFileSync(file, "utf8");
+            }
+            finally {
+                rmSync(dir, { recursive: true, force: true });
+            }
+        },
+    };
+}
+/** Ctrl+C or Escape inside a prompt is the person's decision, reported with exit 130 like a signal. */
+function unwrap(value) {
+    if (clack.isCancel(value))
+        throw new CliError("cancelled", "Cancelled.");
+    return value;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bunizao/cli-kit",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "description": "Shared command-line contract for Bunizao CLI tools",
   "type": "module",
   "exports": {
@@ -22,9 +22,10 @@
     "prepack": "npm test"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20.12"
   },
   "dependencies": {
+    "@clack/prompts": "^1.8.1",
     "commander": "^13.1.0",
     "yaml": "^2.8.0"
   },