clap-ts 0.2.0 → 0.3.0

package/dist/plugins.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Subcommands discovered from installed packages, the way git, eslint and kubectl
+ * grow: drop `my-tool-plugin-deploy` next to the CLI and `my-tool deploy` works.
+ *
+ * ```ts
+ * import { pluginSubCommands } from 'clap-ts/plugins';
+ *
+ * const main = defineCommand({
+ *   meta: { name: 'my-tool' },
+ *   lazySubCommands: pluginSubCommands('my-tool'),
+ * });
+ * ```
+ *
+ * Pairs with `lazySubCommands`: discovery is a directory scan and each plugin is
+ * a module import, so neither happens until a token could be a subcommand.
+ */
+import type { CommandDef } from './types.js';
+/** A plugin package found on disk, before it has been loaded. */
+export interface DiscoveredPlugin {
+    /** Subcommand name, the part after the prefix. */
+    readonly name: string;
+    /** Full package name. */
+    readonly packageName: string;
+    /** Directory the package lives in. */
+    readonly dir: string;
+}
+export interface PluginOptions {
+    /**
+     * Package name prefix. Defaults to `<tool>-plugin-`, so `my-tool-plugin-deploy`
+     * becomes the `deploy` subcommand.
+     */
+    readonly prefix?: string;
+    /** Directories to scan. Defaults to every `node_modules` up from `cwd`. */
+    readonly searchPaths?: readonly string[];
+    /** Where to start the walk (default `process.cwd()`). */
+    readonly cwd?: string;
+    /** Load a package and return its command. Defaults to a dynamic import of the package. */
+    readonly load?: (plugin: DiscoveredPlugin) => CommandDef<any> | undefined;
+    /** Called when a plugin fails to load. Defaults to rethrowing. */
+    readonly onError?: (plugin: DiscoveredPlugin, error: unknown) => void;
+}
+/** Every `node_modules` directory from `cwd` up to the filesystem root. */
+export declare function nodeModulesPaths(cwd?: string): string[];
+/**
+ * Find plugin packages without loading any of them.
+ *
+ * Scoped packages are handled: `@acme/my-tool-plugin-deploy` is found under its
+ * scope directory and reported as `deploy`. The nearest copy of a package wins,
+ * matching how resolution works.
+ */
+export declare function discoverPlugins(tool: string, opts?: PluginOptions): DiscoveredPlugin[];
+/**
+ * A thunk for `lazySubCommands` that discovers and loads plugin packages.
+ *
+ * Nothing is scanned or imported until the thunk runs, which the parser only
+ * does when a token could be a subcommand.
+ */
+export declare function pluginSubCommands(tool: string, opts?: PluginOptions): () => Record<string, CommandDef<any>>;

package/dist/plugins.js

@@ -0,0 +1,145 @@
+/**
+ * Subcommands discovered from installed packages, the way git, eslint and kubectl
+ * grow: drop `my-tool-plugin-deploy` next to the CLI and `my-tool deploy` works.
+ *
+ * ```ts
+ * import { pluginSubCommands } from 'clap-ts/plugins';
+ *
+ * const main = defineCommand({
+ *   meta: { name: 'my-tool' },
+ *   lazySubCommands: pluginSubCommands('my-tool'),
+ * });
+ * ```
+ *
+ * Pairs with `lazySubCommands`: discovery is a directory scan and each plugin is
+ * a module import, so neither happens until a token could be a subcommand.
+ */
+import { readdirSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createRequire } from 'node:module';
+/** Every `node_modules` directory from `cwd` up to the filesystem root. */
+export function nodeModulesPaths(cwd = process.cwd()) {
+    const paths = [];
+    let dir = cwd;
+    for (;;) {
+        if (!dir.endsWith(`${'/'}node_modules`)) {
+            paths.push(join(dir, 'node_modules'));
+        }
+        const parent = join(dir, '..');
+        if (parent === dir) {
+            return paths;
+        }
+        dir = parent;
+    }
+}
+/**
+ * Find plugin packages without loading any of them.
+ *
+ * Scoped packages are handled: `@acme/my-tool-plugin-deploy` is found under its
+ * scope directory and reported as `deploy`. The nearest copy of a package wins,
+ * matching how resolution works.
+ */
+export function discoverPlugins(tool, opts) {
+    const prefix = opts?.prefix ?? `${tool}-plugin-`;
+    const roots = opts?.searchPaths ?? nodeModulesPaths(opts?.cwd);
+    const found = new Map();
+    const consider = (packageName, dir) => {
+        const base = packageName.includes('/') ? packageName.slice(packageName.indexOf('/') + 1) : packageName;
+        if (!base.startsWith(prefix) || base.length === prefix.length) {
+            return;
+        }
+        const name = base.slice(prefix.length);
+        // The first root wins, so a local copy shadows one further up.
+        if (!found.has(name)) {
+            found.set(name, { name, packageName, dir });
+        }
+    };
+    for (const root of roots) {
+        let entries;
+        try {
+            entries = readdirSync(root);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.startsWith('.')) {
+                continue;
+            }
+            if (entry.startsWith('@')) {
+                let scoped;
+                try {
+                    scoped = readdirSync(join(root, entry));
+                }
+                catch {
+                    continue;
+                }
+                for (const inner of scoped) {
+                    consider(`${entry}/${inner}`, join(root, entry, inner));
+                }
+                continue;
+            }
+            consider(entry, join(root, entry));
+        }
+    }
+    return [...found.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Read a discovered package's own name and description, for help before it loads. */
+function packageMeta(plugin) {
+    const pkgPath = join(plugin.dir, 'package.json');
+    if (!existsSync(pkgPath)) {
+        return {};
+    }
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        return pkg.description === undefined ? {} : { description: pkg.description };
+    }
+    catch {
+        return {};
+    }
+}
+function defaultLoad(plugin) {
+    const require = createRequire(join(plugin.dir, 'package.json'));
+    const loaded = require(plugin.packageName);
+    if ('meta' in loaded && loaded.meta !== undefined) {
+        return loaded;
+    }
+    const mod = loaded;
+    return mod.default ?? mod.command;
+}
+/**
+ * A thunk for `lazySubCommands` that discovers and loads plugin packages.
+ *
+ * Nothing is scanned or imported until the thunk runs, which the parser only
+ * does when a token could be a subcommand.
+ */
+export function pluginSubCommands(tool, opts) {
+    return () => {
+        const load = opts?.load ?? defaultLoad;
+        const commands = {};
+        for (const plugin of discoverPlugins(tool, opts)) {
+            let command;
+            try {
+                command = load(plugin);
+            }
+            catch (error) {
+                if (opts?.onError === undefined) {
+                    throw new Error(`plugin '${plugin.packageName}' failed to load: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                opts.onError(plugin, error);
+                continue;
+            }
+            if (command === undefined) {
+                continue;
+            }
+            // Fall back to the package description so help says something useful
+            // even when the plugin did not set one.
+            const meta = command.meta.description === undefined ? packageMeta(plugin) : {};
+            commands[plugin.name] = {
+                ...command,
+                meta: { ...command.meta, name: plugin.name, ...meta },
+            };
+        }
+        return commands;
+    };
+}

package/dist/progress.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Spinners and progress bars that know when nobody is watching.
+ *
+ * ```ts
+ * import { spinner, progressBar } from 'clap-ts/progress';
+ *
+ * const spin = spinner('Fetching');
+ * spin.start();
+ * await work();
+ * spin.succeed('Fetched 12 items');
+ * ```
+ *
+ * Both write to stderr and both go quiet when it is not a terminal, so piping a
+ * command's output never fills a log file with redraw escapes. `NO_COLOR` and
+ * `CI` are honoured the same way.
+ */
+import type { OutputSink } from './types.js';
+export interface ProgressOptions {
+    /** Where to draw (default process.stderr). */
+    readonly sink?: OutputSink;
+    /**
+     * Draw at all. Defaults to true only when the sink is a terminal and CI is
+     * unset, so redirected output stays clean.
+     */
+    readonly enabled?: boolean;
+    /** Use ASCII frames instead of braille. */
+    readonly ascii?: boolean;
+    /** Milliseconds between spinner frames (default 80). */
+    readonly interval?: number;
+    /** Force colour on or off. */
+    readonly color?: boolean;
+    /**
+     * Shortest gap between redraws, in milliseconds (default 16, about 60 a
+     * second). A loop that updates thousands of times a second would otherwise
+     * spend its time writing escape sequences nobody can read.
+     */
+    readonly throttle?: number;
+}
+export interface Spinner {
+    /** Begin animating. Safe to call twice. */
+    start(text?: string): Spinner;
+    /** Change the message without interrupting the animation. */
+    update(text: string): Spinner;
+    /** Stop and leave a green tick. */
+    succeed(text?: string): Spinner;
+    /** Stop and leave a red cross. */
+    fail(text?: string): Spinner;
+    /** Stop and leave a yellow warning mark. */
+    warn(text?: string): Spinner;
+    /** Stop and erase, leaving nothing behind. */
+    stop(): Spinner;
+    /** Whether this spinner draws anything at all. */
+    readonly enabled: boolean;
+}
+/**
+ * A spinner for work of unknown length.
+ *
+ * When drawing is off the terminating calls still print their message once, so
+ * a piped run reports what happened without any animation.
+ */
+export declare function spinner(initialText?: string, opts?: ProgressOptions): Spinner;
+export interface ProgressBar {
+    /** Move to an absolute position. */
+    update(current: number, text?: string): ProgressBar;
+    /** Move forward by an amount (default 1). */
+    tick(by?: number, text?: string): ProgressBar;
+    /** Fill the bar and finish the line. */
+    finish(text?: string): ProgressBar;
+    /** Abandon the bar, erasing it. */
+    stop(): ProgressBar;
+    /** Render the current line without drawing it, for tests. */
+    render(): string;
+    readonly enabled: boolean;
+}
+export interface ProgressBarOptions extends ProgressOptions {
+    /** Total the bar counts up to. */
+    readonly total: number;
+    /** Bar width in characters (default: a third of the terminal, 20 to 40). */
+    readonly width?: number;
+    /** Label shown before the bar. */
+    readonly text?: string;
+}
+/**
+ * A determinate progress bar.
+ *
+ * `render` returns the line it would draw, which is what makes this testable
+ * without a terminal.
+ */
+export declare function progressBar(opts: ProgressBarOptions): ProgressBar;

package/dist/progress.js

@@ -0,0 +1,205 @@
+/**
+ * Spinners and progress bars that know when nobody is watching.
+ *
+ * ```ts
+ * import { spinner, progressBar } from 'clap-ts/progress';
+ *
+ * const spin = spinner('Fetching');
+ * spin.start();
+ * await work();
+ * spin.succeed('Fetched 12 items');
+ * ```
+ *
+ * Both write to stderr and both go quiet when it is not a terminal, so piping a
+ * command's output never fills a log file with redraw escapes. `NO_COLOR` and
+ * `CI` are honoured the same way.
+ */
+import { styleText } from 'node:util';
+import { displayWidth, truncate } from './output.js';
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const ASCII_FRAMES = ['-', '\\', '|', '/'];
+const HIDE_CURSOR = '\x1b[?25l';
+const SHOW_CURSOR = '\x1b[?25h';
+const CLEAR_LINE = '\r\x1b[2K';
+/** Columns available to draw into. */
+function widthOf(sink) {
+    return typeof sink.columns === 'number' && sink.columns > 0 ? sink.columns : 80;
+}
+function resolveSink(opts) {
+    return (opts?.sink ?? process.stderr);
+}
+function shouldDraw(sink, opts) {
+    if (opts?.enabled !== undefined) {
+        return opts.enabled;
+    }
+    // A pipe, a file or a CI log gets no redraws.
+    return sink.isTTY === true && process.env['CI'] === undefined;
+}
+function paint(color, codes, text) {
+    return color ? styleText(codes, text, { validateStream: false }) : text;
+}
+/**
+ * A spinner for work of unknown length.
+ *
+ * When drawing is off the terminating calls still print their message once, so
+ * a piped run reports what happened without any animation.
+ */
+export function spinner(initialText = '', opts) {
+    const sink = resolveSink(opts);
+    const enabled = shouldDraw(sink, opts);
+    const frames = opts?.ascii === true ? ASCII_FRAMES : FRAMES;
+    const interval = opts?.interval ?? 80;
+    const color = opts?.color ?? styleText('red', 'x') !== 'x';
+    let text = initialText;
+    let frame = 0;
+    let timer;
+    let cursorHidden = false;
+    const restoreCursor = () => {
+        if (cursorHidden) {
+            sink.write(SHOW_CURSOR);
+            cursorHidden = false;
+        }
+    };
+    const clear = () => {
+        sink.write(CLEAR_LINE);
+    };
+    const draw = () => {
+        clear();
+        // Two columns for the frame and its space; anything longer wraps, and a
+        // wrapped line cannot be erased by a single carriage return.
+        const room = widthOf(sink) - 2;
+        sink.write(`${paint(color, 'cyan', frames[frame])} ${truncate(text, room)}`);
+        frame = (frame + 1) % frames.length;
+    };
+    const finish = (mark, codes, done) => {
+        if (timer !== undefined) {
+            clearInterval(timer);
+            timer = undefined;
+        }
+        const message = done ?? text;
+        if (enabled) {
+            clear();
+            restoreCursor();
+        }
+        if (message.length > 0) {
+            sink.write(`${paint(color, codes, mark)} ${message}\n`);
+        }
+        return api;
+    };
+    const api = {
+        enabled,
+        start(next) {
+            if (next !== undefined) {
+                text = next;
+            }
+            if (!enabled || timer !== undefined) {
+                return api;
+            }
+            // A visible cursor flickers over the animating frame.
+            sink.write(HIDE_CURSOR);
+            cursorHidden = true;
+            draw();
+            timer = setInterval(draw, interval);
+            // Never hold the event loop open for a spinner.
+            timer.unref?.();
+            return api;
+        },
+        update(next) {
+            text = next;
+            if (enabled && timer !== undefined) {
+                draw();
+            }
+            return api;
+        },
+        succeed: (done) => finish('✔', 'green', done),
+        fail: (done) => finish('✖', 'red', done),
+        warn: (done) => finish('⚠', 'yellow', done),
+        stop() {
+            if (timer !== undefined) {
+                clearInterval(timer);
+                timer = undefined;
+            }
+            if (enabled) {
+                clear();
+                restoreCursor();
+            }
+            return api;
+        },
+    };
+    return api;
+}
+/**
+ * A determinate progress bar.
+ *
+ * `render` returns the line it would draw, which is what makes this testable
+ * without a terminal.
+ */
+export function progressBar(opts) {
+    const sink = resolveSink(opts);
+    const enabled = shouldDraw(sink, opts);
+    const color = opts.color ?? styleText('red', 'x') !== 'x';
+    const total = Math.max(1, opts.total);
+    const columns = widthOf(sink);
+    const width = opts.width ?? Math.min(40, Math.max(20, Math.floor(columns / 3)));
+    const throttle = opts.throttle ?? 16;
+    let current = 0;
+    let text = opts.text ?? '';
+    let lastDraw = 0;
+    const render = () => {
+        const ratio = Math.min(1, current / total);
+        const filled = Math.round(ratio * width);
+        const bar = '█'.repeat(filled) + '░'.repeat(width - filled);
+        const percent = `${String(Math.round(ratio * 100)).padStart(3)}%`;
+        const counts = `${String(current)}/${String(total)}`;
+        const line = `${bar} ${percent} ${counts}${text.length > 0 ? ` ${text}` : ''}`;
+        // Fit the terminal: a line that wraps cannot be erased by a carriage
+        // return, so the next redraw would stack instead of replacing.
+        const fitted = displayWidth(line) > columns ? truncate(line, columns) : line;
+        return color ? fitted.replace(bar, paint(color, 'cyan', bar)) : fitted;
+    };
+    const draw = (force) => {
+        const now = Date.now();
+        // The final frame always lands; the ones in between can be skipped.
+        if (!force && throttle > 0 && now - lastDraw < throttle) {
+            return;
+        }
+        lastDraw = now;
+        sink.write(`${CLEAR_LINE}${render()}`);
+    };
+    const api = {
+        enabled,
+        render,
+        update(next, nextText) {
+            current = Math.max(0, Math.min(total, next));
+            if (nextText !== undefined) {
+                text = nextText;
+            }
+            if (enabled) {
+                draw(false);
+            }
+            return api;
+        },
+        tick: (by = 1, nextText) => api.update(current + by, nextText),
+        finish(done) {
+            current = total;
+            if (done !== undefined) {
+                text = done;
+            }
+            if (enabled) {
+                draw(true);
+                sink.write('\n');
+            }
+            else if (text.length > 0) {
+                sink.write(`${text}\n`);
+            }
+            return api;
+        },
+        stop() {
+            if (enabled) {
+                sink.write(CLEAR_LINE);
+            }
+            return api;
+        },
+    };
+    return api;
+}

package/dist/prompt.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Interactive prompts, derived from the argument definitions a command already
+ * has.
+ *
+ * ```ts
+ * import { promptMissing } from 'clap-ts/prompt';
+ *
+ * await runMain(main, { fillMissing: promptMissing() });
+ * ```
+ *
+ * A required argument nobody supplied is asked for rather than rejected: a
+ * boolean becomes a confirm, an argument with possible values becomes a
+ * numbered list, and one marked `secret` is read without echoing. `ctx
+ * .valueSources` reports those as `'prompt'`.
+ *
+ * Nothing prompts when stdin is not a terminal, so a script or a CI job still
+ * fails fast with the usual error instead of hanging on input that will never
+ * arrive.
+ */
+import type { ArgDef, CommandDef, MissingArg, PossibleValue } from './types.js';
+/** Somewhere to ask questions. The default talks to the terminal. */
+export interface PromptIO {
+    /** Show `text` and resolve with the reply. */
+    question(text: string): Promise<string>;
+    /** As `question`, but the reply is not echoed. */
+    secret(text: string): Promise<string>;
+    /** Write to the prompt's output, for lists and errors. */
+    write(text: string): void;
+    /** Release the terminal. */
+    close(): void;
+    /** Whether anyone is there to answer. */
+    readonly interactive: boolean;
+}
+/**
+ * The PromptIO backed by the real terminal.
+ *
+ * Shared, because a readline interface takes ownership of stdin: a second one
+ * finds the stream already consumed, so two prompts in a row would fail with
+ * the input reported as ended. `close()` releases it, and the next call builds
+ * a fresh one.
+ */
+export declare function terminalIO(): PromptIO;
+/** A PromptIO that answers from a list, for tests. */
+export declare function scriptedIO(answers: readonly string[]): PromptIO & {
+    output: string;
+};
+/** Common to every prompt. */
+export interface AskOptions {
+    /** Where to ask (default: the terminal). */
+    readonly io?: PromptIO;
+}
+/** A prompt that can offer a text default when the reply is empty. */
+export interface TextAskOptions extends AskOptions {
+    readonly defaultValue?: string;
+}
+/** A confirm, whose default is a boolean rather than text. */
+export interface ConfirmOptions extends AskOptions {
+    readonly defaultValue?: boolean;
+}
+/** Ask for a line of text, returning the default when the reply is empty. */
+export declare function input(message: string, opts?: TextAskOptions): Promise<string>;
+/** Ask for a secret, without echoing it. */
+export declare function password(message: string, opts?: AskOptions): Promise<string>;
+/** Ask a yes or no question. */
+export declare function confirm(message: string, opts?: ConfirmOptions): Promise<boolean>;
+/**
+ * Offer a numbered list and take an index or the value itself.
+ *
+ * A numbered list rather than an arrow-key menu, so it behaves the same over
+ * ssh, in a dumb terminal and under a test.
+ */
+export declare function select(message: string, choices: readonly (string | PossibleValue)[], opts?: TextAskOptions): Promise<string>;
+/** Offer a numbered list and take several answers, separated by commas. */
+export declare function multiselect(message: string, choices: readonly (string | PossibleValue)[], opts?: AskOptions): Promise<string[]>;
+/**
+ * Ask for one argument, choosing the prompt from its definition.
+ *
+ * A boolean is a confirm, an argument with possible values is a list, one
+ * marked `secret` is not echoed, and everything else is a line of text. The
+ * result is validated against the argument's own parser before being accepted.
+ */
+export declare function promptForArg(key: string, def: ArgDef, opts?: AskOptions): Promise<string | boolean | string[]>;
+export interface PromptMissingOptions {
+    /** Where to ask (default: the terminal). */
+    readonly io?: PromptIO;
+    /**
+     * Ask even when stdin is not a terminal. Off by default, so a script fails
+     * with the usual error rather than waiting for input that never comes.
+     */
+    readonly force?: boolean;
+}
+/**
+ * A `fillMissing` hook that asks for each required argument still empty.
+ *
+ * ```ts
+ * await runMain(main, { fillMissing: promptMissing() });
+ * ```
+ */
+export declare function promptMissing(opts?: PromptMissingOptions): (missing: readonly MissingArg[], command: CommandDef<any>) => Promise<Record<string, unknown> | undefined>;