@bunizao/cli-kit 0.5.0 → 0.6.0

package/README.md

@@ -187,8 +187,10 @@ 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
+`select` switches to type-to-filter above `AUTOCOMPLETE_FROM` choices, or always with
+`{ search: true }`; every typed word must appear in the label or hint, in any order.
+`{ initial }` highlights a row. A multi-step picker passes `{ back: true }` and gets `BACK`
+when the person presses Escape. 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.
 

package/dist/program.js

@@ -63,7 +63,8 @@ function describe(command, noun) {
         aliases: command.aliases(),
         description: command.description(),
         positionals: command.registeredArguments.map(describeArgument),
-        options: command.options.map(describeOption),
+        // Match help output: options created with .hideHelp() stay out of the description.
+        options: command.options.filter((option) => !option.hidden).map(describeOption),
         mutating: mutations.has(command),
         commands: command.commands.filter((child) => child.name() !== "help").map((child) => describe(child, currentNoun)),
     };

package/dist/ui.d.ts

@@ -9,6 +9,19 @@ export interface Choice<T> {
     readonly label: string;
     readonly hint?: string;
 }
+/** What `select` resolves when the person presses Escape on a prompt opened with `back: true`. */
+export declare const BACK: unique symbol;
+export interface SelectOptions<T> {
+    /** Type-to-filter at any length; a short list still wants it when the person knows the name. */
+    readonly search?: boolean;
+    /** The row highlighted when the list opens. */
+    readonly initial?: T;
+    /**
+     * Escape resolves `BACK` instead of cancelling, so a multi-step picker can return to the
+     * previous step. Ctrl+C still cancels.
+     */
+    readonly back?: boolean;
+}
 export interface UiOptions {
     /** Keyboard input. Defaults to `process.stdin`. */
     readonly input?: NodeJS.ReadStream;
@@ -30,6 +43,8 @@ export interface Spinner {
     /** End the step and leave `message` (or the last running text) as the permanent line. */
     stop(message?: string): void;
     error(message?: string): void;
+    /** End the step and erase it, for progress whose outcome is printed elsewhere. */
+    clear(): void;
 }
 export interface Ui {
     readonly interactive: boolean;
@@ -47,10 +62,14 @@ export interface Ui {
     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.
+     * type-to-filter, because arrowing through thirty forum threads is not a picker. The
+     * filter matches every typed word anywhere in the label or hint, in any order.
      * Without a terminal this throws a usage error that lists the choices.
      */
-    select<T>(message: string, choices: readonly Choice<T>[]): Promise<T>;
+    select<T>(message: string, choices: readonly Choice<T>[], options: SelectOptions<T> & {
+        readonly back: true;
+    }): Promise<T | typeof BACK>;
+    select<T>(message: string, choices: readonly Choice<T>[], options?: SelectOptions<T>): Promise<T>;
     /** Yes or no. Without a terminal this throws a usage error. */
     confirm(message: string, options?: {
         readonly initial?: boolean;

package/dist/ui.js

@@ -6,6 +6,8 @@ import * as clack from "@clack/prompts";
 import { isAgentEnvironment } from "./audience.js";
 import { colorEnabled, painter } from "./color.js";
 import { CliError } from "./errors.js";
+/** What `select` resolves when the person presses Escape on a prompt opened with `back: true`. */
+export const BACK = Symbol("cli-kit.back");
 export const AUTOCOMPLETE_FROM = 8;
 /**
  * Every CLI in the family draws the same way: prompts, steps and spinners on stderr
@@ -18,8 +20,15 @@ export function createUi(options = {}) {
     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`);
+    // Escape erases the abandoned step and the answer above it, so going back looks like
+    // the earlier question was never answered. That needs to know how many rows each prompt
+    // drew; clack redraws with relative moves, so counting newlines and cursor-up/down
+    // sequences written through the ui gives it.
+    let row = 0;
+    const answered = [];
+    const drawn = interactive ? trackRows(output, delta => { row += delta; }) : output;
+    const common = { input, output: drawn, ...(options.signal ? { signal: options.signal } : {}) };
+    const plain = (text) => drawn.write(`${text}\n`);
     const paint = painter(colorEnabled(output, options.env));
     return {
         interactive,
@@ -30,7 +39,7 @@ export function createUi(options = {}) {
                 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`);
+            drawn.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)),
@@ -41,11 +50,31 @@ export function createUi(options = {}) {
         spinner() {
             if (interactive) {
                 const inner = clack.spinner(common);
+                // Clack's spinner holds stdin in raw mode and answers Ctrl+C with process.exit(0),
+                // which skips the caller's cleanup and leaves half-written files behind. Handing
+                // the key back to the terminal makes it a real SIGINT: the spinner erases itself,
+                // the CLI's own handler runs, and a CLI without one still dies as Ctrl+C always has.
+                const onInterrupt = () => {
+                    process.off("SIGINT", onInterrupt);
+                    inner.clear();
+                    if (!process.listenerCount("SIGINT"))
+                        process.kill(process.pid, "SIGINT");
+                };
+                const end = (finish) => {
+                    process.off("SIGINT", onInterrupt);
+                    finish();
+                };
                 return {
-                    start: message => inner.start(message),
+                    start: message => {
+                        inner.start(message);
+                        if (process.stdin.isTTY)
+                            process.stdin.setRawMode(false);
+                        process.prependListener("SIGINT", onInterrupt);
+                    },
                     message: message => inner.message(message),
-                    stop: message => inner.stop(message),
-                    error: message => inner.error(message),
+                    stop: message => end(() => inner.stop(message)),
+                    error: message => end(() => inner.error(message)),
+                    clear: () => end(() => inner.clear()),
                 };
             }
             // A pipe is read after the fact: only the outcome of a step is worth a line.
@@ -55,9 +84,10 @@ export function createUi(options = {}) {
                 message: message => { running = message; },
                 stop: message => plain(message ?? running),
                 error: message => plain(`error: ${message ?? running}`),
+                clear: () => { running = ""; },
             };
         },
-        async select(message, choices) {
+        async select(message, choices, selectOptions = {}) {
             if (!choices.length)
                 throw new CliError("unexpected", `Nothing to choose for "${message}".`);
             if (!interactive) {
@@ -65,10 +95,33 @@ export function createUi(options = {}) {
             }
             // `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);
+            const initial = selectOptions.initial !== undefined ? { initialValue: selectOptions.initial } : {};
+            // Clack reports Escape and Ctrl+C as the same cancel, so the key itself tells them apart.
+            let escaped = false;
+            const onKey = (_, key) => { escaped = key?.name === "escape"; };
+            if (selectOptions.back)
+                input.on("keypress", onKey);
+            const start = row;
+            let picked;
+            try {
+                picked = selectOptions.search || choices.length >= AUTOCOMPLETE_FROM
+                    ? await clack.autocomplete({ message, options: list, placeholder: "Type to filter", maxItems: AUTOCOMPLETE_FROM, filter: matchesWords, ...initial, ...common })
+                    : await clack.select({ message, options: list, ...initial, ...common });
+            }
+            finally {
+                input.off("keypress", onKey);
+            }
+            if (selectOptions.back && escaped && clack.isCancel(picked)) {
+                // The answer above is erased too only when nothing was drawn between it and this step.
+                const previous = answered.at(-1)?.end === start ? answered.pop() : undefined;
+                const up = row - (previous?.start ?? start);
+                if (up > 0)
+                    drawn.write(`\u001b[${up}A\r\u001b[J`);
+                return BACK;
+            }
+            const value = unwrap(picked);
+            answered.push({ start, end: row });
+            return value;
         },
         async confirm(message, confirmOptions = {}) {
             if (!interactive)
@@ -117,6 +170,32 @@ export function createUi(options = {}) {
         },
     };
 }
+// "2086 week 5" should find "FIT2086 · Week 5": each typed word on its own, anywhere in
+// the label or hint. A number starts a run of digits, so "5" finds "Week 5" and "2086"
+// finds "FIT2086", but "5" does not find "Week 15".
+function matchesWords(search, option) {
+    const text = `${option.label ?? ""} ${option.hint ?? ""}`.toLowerCase();
+    return search.toLowerCase().split(/\s+/u).filter(Boolean).every(word => /^\d+$/u.test(word)
+        ? new RegExp(`(?<!\\d)${word}`, "u").test(text)
+        : text.includes(word));
+}
+// Everything else about the stream (columns, isTTY, resize events) is the real one.
+function trackRows(output, moved) {
+    const write = (chunk, ...rest) => {
+        for (const match of String(chunk).matchAll(/\u001b\[(\d*)([AB])|\n/gu)) {
+            moved(match[0] === "\n" ? 1 : (match[2] === "A" ? -1 : 1) * Number(match[1] || 1));
+        }
+        return output.write(chunk, ...rest);
+    };
+    return new Proxy(output, {
+        get(target, property) {
+            if (property === "write")
+                return write;
+            const value = Reflect.get(target, property, target);
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+    });
+}
 /** 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))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bunizao/cli-kit",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Shared command-line contract for Bunizao CLI tools",
   "type": "module",
   "exports": {