clap-ts 0.2.1 → 0.3.0

package/dist/prompt.js

@@ -0,0 +1,299 @@
+/**
+ * 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 { createInterface } from 'node:readline/promises';
+import { styleText } from 'node:util';
+import { possibleValues } from './parser.js';
+let sharedIO;
+/**
+ * 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 function terminalIO() {
+    sharedIO ??= createTerminalIO();
+    return sharedIO;
+}
+function createTerminalIO() {
+    const interactive = process.stdin.isTTY === true && process.stdout.isTTY === true;
+    let rl;
+    let lines;
+    const iface = () => {
+        // terminal: true against a pipe makes readline echo the whole buffer and
+        // reorder it, so this follows whatever stdin actually is.
+        rl ??= createInterface({
+            input: process.stdin,
+            output: process.stdout,
+            terminal: interactive,
+        });
+        return rl;
+    };
+    /**
+     * Pull one line.
+     *
+     * readline consumes a pipe greedily, so a second `question()` would find the
+     * stream already drained and never resolve. Reading through the async
+     * iterator keeps the lines queued and hands them out one at a time.
+     */
+    const nextLine = async () => {
+        lines ??= iface()[Symbol.asyncIterator]();
+        const { value, done } = await lines.next();
+        if (done === true) {
+            throw new Error('input ended while waiting for an answer');
+        }
+        return value;
+    };
+    const ask = async (text, mask) => {
+        const active = iface();
+        process.stdout.write(text);
+        if (!mask) {
+            return nextLine();
+        }
+        const hooked = active;
+        const original = hooked._writeToOutput;
+        // Echo a bullet per printable character, and nothing for control keys.
+        hooked._writeToOutput = (chunk) => {
+            if (chunk.length === 1 && chunk >= ' ') {
+                hooked.output?.write('*');
+            }
+        };
+        try {
+            return await nextLine();
+        }
+        finally {
+            if (original === undefined) {
+                delete hooked._writeToOutput;
+            }
+            else {
+                hooked._writeToOutput = original;
+            }
+            process.stdout.write('\n');
+        }
+    };
+    return {
+        interactive,
+        question: (text) => ask(text, false),
+        secret: (text) => ask(text, true),
+        write: (text) => {
+            process.stdout.write(text);
+        },
+        close: () => {
+            rl?.close();
+            rl = undefined;
+            lines = undefined;
+            sharedIO = undefined;
+        },
+    };
+}
+/** A PromptIO that answers from a list, for tests. */
+export function scriptedIO(answers) {
+    let index = 0;
+    const io = {
+        interactive: true,
+        output: '',
+        question: (text) => {
+            io.output += text;
+            const answer = answers[index++] ?? '';
+            io.output += `${answer}\n`;
+            return Promise.resolve(answer);
+        },
+        secret: (text) => io.question(text),
+        write: (text) => {
+            io.output += text;
+        },
+        close: () => { },
+    };
+    return io;
+}
+function paint(text, codes) {
+    return styleText('red', 'x') === 'x' ? text : styleText(codes, text);
+}
+/** Ask for a line of text, returning the default when the reply is empty. */
+export async function input(message, opts) {
+    const io = opts?.io ?? terminalIO();
+    const hint = opts?.defaultValue === undefined ? '' : ` (${opts.defaultValue})`;
+    const answer = (await io.question(`${paint('?', 'green')} ${message}${hint}: `)).trim();
+    return answer.length > 0 ? answer : (opts?.defaultValue ?? '');
+}
+/** Ask for a secret, without echoing it. */
+export async function password(message, opts) {
+    const io = opts?.io ?? terminalIO();
+    return (await io.secret(`${paint('?', 'green')} ${message}: `)).trim();
+}
+/** Ask a yes or no question. */
+export async function confirm(message, opts) {
+    const io = opts?.io ?? terminalIO();
+    const fallback = opts?.defaultValue ?? false;
+    const hint = fallback ? 'Y/n' : 'y/N';
+    const answer = (await io.question(`${paint('?', 'green')} ${message} (${hint}): `))
+        .trim()
+        .toLowerCase();
+    if (answer.length === 0) {
+        return fallback;
+    }
+    return answer === 'y' || answer === 'yes' || answer === 'true' || answer === '1';
+}
+/**
+ * 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 async function select(message, choices, opts) {
+    const io = opts?.io ?? terminalIO();
+    const values = choices.map((c) => (typeof c === 'string' ? { name: c } : c));
+    if (values.length === 0) {
+        throw new Error('select needs at least one choice');
+    }
+    for (;;) {
+        io.write(`${paint('?', 'green')} ${message}\n`);
+        values.forEach((choice, i) => {
+            const help = choice.help === undefined ? '' : `  ${choice.help}`;
+            io.write(`  ${String(i + 1)}) ${choice.name}${help}\n`);
+        });
+        const hint = opts?.defaultValue === undefined ? '' : ` (${opts.defaultValue})`;
+        const answer = (await io.question(`  choice${hint}: `)).trim();
+        if (answer.length === 0 && opts?.defaultValue !== undefined) {
+            return opts.defaultValue;
+        }
+        const index = Number.parseInt(answer, 10);
+        if (!Number.isNaN(index) && index >= 1 && index <= values.length) {
+            return values[index - 1].name;
+        }
+        const named = values.find((c) => c.name === answer);
+        if (named !== undefined) {
+            return named.name;
+        }
+        io.write(`  ${paint('not one of the choices', 'yellow')}\n`);
+    }
+}
+/** Offer a numbered list and take several answers, separated by commas. */
+export async function multiselect(message, choices, opts) {
+    const io = opts?.io ?? terminalIO();
+    const values = choices.map((c) => (typeof c === 'string' ? { name: c } : c));
+    for (;;) {
+        io.write(`${paint('?', 'green')} ${message}\n`);
+        values.forEach((choice, i) => {
+            io.write(`  ${String(i + 1)}) ${choice.name}\n`);
+        });
+        const answer = (await io.question('  choices (comma separated): ')).trim();
+        if (answer.length === 0) {
+            return [];
+        }
+        const picked = [];
+        let bad = false;
+        for (const part of answer.split(',').map((p) => p.trim())) {
+            const index = Number.parseInt(part, 10);
+            if (!Number.isNaN(index) && index >= 1 && index <= values.length) {
+                picked.push(values[index - 1].name);
+                continue;
+            }
+            const named = values.find((c) => c.name === part);
+            if (named === undefined) {
+                bad = true;
+                break;
+            }
+            picked.push(named.name);
+        }
+        if (!bad) {
+            return picked;
+        }
+        io.write(`  ${paint('not one of the choices', 'yellow')}\n`);
+    }
+}
+/** The message shown when asking for an argument. */
+function messageFor(key, def) {
+    return def.description ?? def.longDescription ?? `Value for ${def.long ?? key}`;
+}
+/**
+ * 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 async function promptForArg(key, def, opts) {
+    const io = opts?.io ?? terminalIO();
+    const message = messageFor(key, def);
+    const values = possibleValues(def).filter((v) => !v.hidden);
+    if (def.type === 'boolean') {
+        return confirm(message, { io });
+    }
+    if (values.length > 0) {
+        return def.action === 'append'
+            ? multiselect(message, values, { io })
+            : select(message, values, { io });
+    }
+    if (def.secret === true) {
+        return password(message, { io });
+    }
+    for (;;) {
+        const answer = await input(message, {
+            io,
+            ...(def.default === undefined ? {} : { defaultValue: String(def.default) }),
+        });
+        if (answer.length === 0) {
+            io.write(`  ${paint('a value is required', 'yellow')}\n`);
+            continue;
+        }
+        if (typeof def.valueParser === 'function') {
+            try {
+                def.valueParser(answer);
+            }
+            catch (error) {
+                io.write(`  ${paint(error instanceof Error ? error.message : String(error), 'yellow')}\n`);
+                continue;
+            }
+        }
+        if (def.type === 'number' && Number.isNaN(Number(answer))) {
+            io.write(`  ${paint('expected a number', 'yellow')}\n`);
+            continue;
+        }
+        return answer;
+    }
+}
+/**
+ * A `fillMissing` hook that asks for each required argument still empty.
+ *
+ * ```ts
+ * await runMain(main, { fillMissing: promptMissing() });
+ * ```
+ */
+export function promptMissing(opts) {
+    return async (missing) => {
+        const io = opts?.io ?? terminalIO();
+        if (!io.interactive && opts?.force !== true) {
+            io.close();
+            return undefined;
+        }
+        const filled = {};
+        try {
+            for (const { key, def } of missing) {
+                filled[key] = await promptForArg(key, def, { io });
+            }
+        }
+        finally {
+            io.close();
+        }
+        return filled;
+    };
+}

package/dist/runner.d.ts

@@ -4,7 +4,7 @@
  * Supports inferSubcommands, subcommandRequired, allowExternalSubcommands,
  * argsConflictsWithSubcommands, argRequiredElseHelp, and custom styles.
  */
-import type { ArgDef, ArgsDef, CommandDef, ParsedArgs, RunOptions } from './types.js';
+import type { ArgDef, ArgsDef, CommandDef, ParsedArgs, OutputSink, RunOptions, ValueSource } from './types.js';
 /**
  * Define a command with full type inference on arguments.
  * This is the primary API for creating commands.
@@ -47,7 +47,10 @@ export declare function defineArg<const T extends ArgDef>(arg: T): T;
  * Run a specific command with pre-parsed arguments.
  * Executes the setup -> run -> cleanup lifecycle.
  */
-export declare function runCommand<T extends ArgsDef>(command: CommandDef<T>, args: ParsedArgs<T>, rawArgs?: readonly string[], subCommand?: string): Promise<void>;
+export declare function runCommand<T extends ArgsDef>(command: CommandDef<T>, args: ParsedArgs<T>, rawArgs?: readonly string[], subCommand?: string, valueSources?: ReadonlyMap<string, ValueSource>, io?: {
+    stdout: OutputSink;
+    stderr: OutputSink;
+}): Promise<void>;
 /**
  * Main entry point for CLI applications.
  * Parses args, resolves subcommands, validates, and runs.