@shaferllc/keel 0.68.0 → 0.77.0

package/dist/core/console-prompt.js

@@ -0,0 +1,239 @@
+/**
+ * Interactive prompts for console commands — ask, confirm, choice, and friends.
+ *
+ *   const name = await prompt.ask("What is your name?");
+ *   const ok = await prompt.confirm("Delete everything?");
+ *   const driver = await prompt.choice("Pick a driver", ["sqlite", "postgres"]);
+ *
+ * `node:readline` is imported dynamically, so the core still loads on the edge.
+ *
+ * ## Prompts are testable, which is the whole point
+ *
+ * A command that asks questions is normally a command you can't test. So a prompt
+ * can be **trapped**: you script the answer up front, and the prompt never
+ * touches the terminal.
+ *
+ *   const prompt = createPrompt({ trap: true });
+ *   prompt.trap("What is your name?").replyWith("Ada");
+ *   prompt.trap("Delete everything?").reject();
+ *
+ * An untrapped prompt in trap mode **throws** rather than hanging forever waiting
+ * on stdin that a test will never provide.
+ */
+const valueOf = (choice) => (typeof choice === "string" ? choice : choice.value);
+const labelOf = (choice) => typeof choice === "string" ? choice : (choice.label ?? choice.value);
+export function createPrompt(options = {}) {
+    const traps = new Map();
+    const trapping = options.trap ?? false;
+    /** Read one line from the terminal. */
+    async function readLine(question, mask = false) {
+        const readline = await import("node:readline");
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+            terminal: true,
+        });
+        // For a secure prompt, swallow the echo so the password isn't left on screen.
+        if (mask) {
+            const output = rl;
+            const original = output.output.write.bind(output.output);
+            output.output.write = (chunk) => {
+                if (chunk.includes(question))
+                    original(chunk);
+            };
+        }
+        return new Promise((resolve) => {
+            rl.question(question, (answer) => {
+                rl.close();
+                if (mask)
+                    process.stdout.write("\n");
+                resolve(answer);
+            });
+        });
+    }
+    /**
+     * Resolve a question from its trap, running whatever assertions were attached.
+     * Returns `undefined` when there's no trap — the caller decides what that means.
+     */
+    function fromTrap(question, validate) {
+        const state = traps.get(question);
+        if (!state)
+            return undefined;
+        for (const { value, message } of state.expectFail) {
+            const result = validate ? validate(value) : true;
+            if (result === true) {
+                throw new Error(`Expected the prompt "${question}" to reject ${JSON.stringify(value)}, but it passed.`);
+            }
+            if (message !== undefined && result !== message) {
+                throw new Error(`Expected the prompt "${question}" to reject ${JSON.stringify(value)} with "${message}", got "${result}".`);
+            }
+        }
+        for (const value of state.expectPass) {
+            const result = validate ? validate(value) : true;
+            if (result !== true) {
+                throw new Error(`Expected the prompt "${question}" to accept ${JSON.stringify(value)}, but it said "${result}".`);
+            }
+        }
+        state.answered = true;
+        return state.answer;
+    }
+    /** Nothing scripted this question, and there's no terminal to ask. */
+    function untrapped(question) {
+        throw new Error(`The prompt "${question}" was not trapped. Script it with prompt.trap(${JSON.stringify(question)}).replyWith(…) — ` +
+            `otherwise the command would block forever waiting for input a test can't give it.`);
+    }
+    function check(question, value, options) {
+        const problem = options?.validate?.(value);
+        if (problem !== undefined && problem !== true)
+            throw new Error(`${question}: ${problem}`);
+        return options?.result ? options.result(value) : value;
+    }
+    const prompt = {
+        async ask(question, options) {
+            if (trapping) {
+                const answer = fromTrap(question, options?.validate);
+                if (answer === undefined)
+                    untrapped(question);
+                return check(question, answer, options);
+            }
+            const hint = options?.default ? ` (${options.default})` : "";
+            const raw = (await readLine(`${question}${hint} `)).trim();
+            const value = raw || options?.default || "";
+            const problem = options?.validate?.(value);
+            // Ask again rather than dying — a typo shouldn't cost them the whole command.
+            if (problem !== undefined && problem !== true) {
+                console.error(problem);
+                return prompt.ask(question, options);
+            }
+            return options?.result ? options.result(value) : value;
+        },
+        async secure(question, options) {
+            if (trapping) {
+                const answer = fromTrap(question, options?.validate);
+                if (answer === undefined)
+                    untrapped(question);
+                return check(question, answer, options);
+            }
+            const value = (await readLine(`${question} `, true)).trim();
+            return check(question, value, options);
+        },
+        async confirm(question, options) {
+            return prompt.toggle(question, ["y", "n"], options);
+        },
+        async toggle(question, labels, options) {
+            if (trapping) {
+                const answer = fromTrap(question, options?.validate);
+                if (answer === undefined)
+                    untrapped(question);
+                return check(question, answer, options);
+            }
+            const fallback = options?.default ?? false;
+            const hint = fallback ? `[${labels[0].toUpperCase()}/${labels[1]}]` : `[${labels[0]}/${labels[1].toUpperCase()}]`;
+            const raw = (await readLine(`${question} ${hint} `)).trim().toLowerCase();
+            const value = raw === "" ? fallback : raw === labels[0].toLowerCase() || raw === "yes" || raw === "true";
+            return check(question, value, options);
+        },
+        async choice(question, choices, options) {
+            if (trapping) {
+                const index = fromTrap(question);
+                if (index === undefined)
+                    untrapped(question);
+                const choice = choices[index];
+                if (!choice)
+                    throw new Error(`The prompt "${question}" has no option at index ${index}.`);
+                return check(question, valueOf(choice), options);
+            }
+            console.log(question);
+            choices.forEach((choice, i) => console.log(`  ${i + 1}) ${labelOf(choice)}`));
+            const raw = (await readLine("> ")).trim();
+            const index = Number(raw) - 1;
+            const choice = choices[index];
+            if (!choice) {
+                console.error(`Pick a number between 1 and ${choices.length}.`);
+                return prompt.choice(question, choices, options);
+            }
+            return check(question, valueOf(choice), options);
+        },
+        async multiple(question, choices, options) {
+            if (trapping) {
+                const indexes = fromTrap(question);
+                if (indexes === undefined)
+                    untrapped(question);
+                const values = indexes.map((i) => {
+                    const choice = choices[i];
+                    if (!choice)
+                        throw new Error(`The prompt "${question}" has no option at index ${i}.`);
+                    return valueOf(choice);
+                });
+                return check(question, values, options);
+            }
+            console.log(`${question} (comma-separated numbers)`);
+            choices.forEach((choice, i) => console.log(`  ${i + 1}) ${labelOf(choice)}`));
+            const raw = (await readLine("> ")).trim();
+            const values = raw
+                .split(",")
+                .map((part) => choices[Number(part.trim()) - 1])
+                .filter((choice) => choice !== undefined)
+                .map(valueOf);
+            return check(question, values, options);
+        },
+        async autocomplete(question, choices, options) {
+            if (trapping) {
+                const answer = fromTrap(question);
+                if (answer === undefined)
+                    untrapped(question);
+                return check(question, answer, options);
+            }
+            // Without a raw-mode TTY there's no live filtering to do, so it degrades to
+            // a plain choice list rather than pretending.
+            return prompt.choice(question, choices, options);
+        },
+        trap(question) {
+            const state = {
+                question,
+                answered: false,
+                expectFail: [],
+                expectPass: [],
+            };
+            traps.set(question, state);
+            const api = {
+                replyWith(value) {
+                    state.answer = value;
+                    return api;
+                },
+                accept() {
+                    state.answer = true;
+                    return api;
+                },
+                reject() {
+                    state.answer = false;
+                    return api;
+                },
+                chooseOption(index) {
+                    state.answer = index;
+                    return api;
+                },
+                chooseOptions(indexes) {
+                    state.answer = indexes;
+                    return api;
+                },
+                assertFails(value, message) {
+                    state.expectFail.push({ value, message });
+                    return api;
+                },
+                assertPasses(value) {
+                    state.expectPass.push(value);
+                    return api;
+                },
+            };
+            return api;
+        },
+        assertAllTrapsUsed() {
+            const unused = [...traps.values()].filter((t) => !t.answered).map((t) => t.question);
+            if (unused.length) {
+                throw new Error(`These prompts were trapped but never asked: ${unused.map((q) => `"${q}"`).join(", ")}.`);
+            }
+        },
+    };
+    return prompt;
+}

package/dist/core/console-ui.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Terminal UI for console commands — colors, a logger, tables, boxes, and a task
+ * runner. No dependency: ANSI codes are a dozen escape sequences, not a package.
+ *
+ *   ui.success("Migrated 3 tables");
+ *   ui.table(["Name", "Rows"]).row(["users", "42"]).render();
+ *
+ * Everything goes through the same `write`, which is what makes the whole thing
+ * testable: `createUi({ raw: true })` strips the colors and buffers the output
+ * instead of printing it, so a test can assert on exactly what a command said.
+ */
+declare const CODES: {
+    readonly reset: 0;
+    readonly bold: 1;
+    readonly dim: 2;
+    readonly italic: 3;
+    readonly underline: 4;
+    readonly red: 31;
+    readonly green: 32;
+    readonly yellow: 33;
+    readonly blue: 34;
+    readonly magenta: 35;
+    readonly cyan: 36;
+    readonly white: 37;
+    readonly gray: 90;
+    readonly bgRed: 41;
+    readonly bgGreen: 42;
+    readonly bgYellow: 43;
+};
+export type ColorName = keyof typeof CODES;
+/** Paint text, or don't — the same call site works either way. */
+export interface Colors {
+    (name: ColorName, text: string): string;
+    readonly enabled: boolean;
+}
+/** Strip ANSI escapes — used by the raw mode, and handy in assertions. */
+export declare function stripAnsi(text: string): string;
+export interface Table {
+    head(...columns: string[]): Table;
+    row(cells: string[]): Table;
+    rows(rows: string[][]): Table;
+    /** Render it and write it out. */
+    render(): void;
+    /** Render it to a string instead of writing it. */
+    toString(): string;
+}
+/** What a single task can report while it runs. */
+export interface TaskHandle {
+    update(message: string): void;
+}
+export interface Tasks {
+    add(title: string, run: (task: TaskHandle) => Promise<string | void> | string | void): Tasks;
+    /** Run them in order. Resolves to false if any task failed. */
+    run(): Promise<boolean>;
+}
+export interface UiOptions {
+    /**
+     * Buffer output instead of printing it, and drop the colors. What tests use —
+     * `ui.logs` then holds every line.
+     */
+    raw?: boolean;
+    /** Force colors on or off. Defaults to on unless raw, or NO_COLOR is set. */
+    colors?: boolean;
+}
+export interface Ui {
+    readonly colors: Colors;
+    /** In raw mode, every line written. Empty otherwise. */
+    readonly logs: string[];
+    /** In raw mode, every line written to stderr. */
+    readonly errors: string[];
+    /** Write a line verbatim. */
+    write(line: string): void;
+    debug(message: string): void;
+    info(message: string): void;
+    success(message: string): void;
+    warning(message: string): void;
+    /** Goes to stderr. */
+    error(message: string): void;
+    /** Goes to stderr. */
+    fatal(message: string): void;
+    /**
+     * A one-line status for something you did: `CREATE  app/Models/User.ts`.
+     * The verb is padded so a run of them lines up.
+     */
+    action(verb: string, target: string, status?: "done" | "skipped" | "failed"): void;
+    table(head?: string[]): Table;
+    /** A boxed message — for the thing you want them to actually read. */
+    sticker(lines: string[], title?: string): void;
+    /** Numbered next-steps. */
+    instructions(lines: string[], title?: string): void;
+    tasks(): Tasks;
+    /** Clear the captured buffers (raw mode). */
+    clear(): void;
+}
+export declare function createUi(options?: UiOptions): Ui;
+export {};

package/dist/core/console-ui.js

@@ -0,0 +1,187 @@
+/**
+ * Terminal UI for console commands — colors, a logger, tables, boxes, and a task
+ * runner. No dependency: ANSI codes are a dozen escape sequences, not a package.
+ *
+ *   ui.success("Migrated 3 tables");
+ *   ui.table(["Name", "Rows"]).row(["users", "42"]).render();
+ *
+ * Everything goes through the same `write`, which is what makes the whole thing
+ * testable: `createUi({ raw: true })` strips the colors and buffers the output
+ * instead of printing it, so a test can assert on exactly what a command said.
+ */
+/* -------------------------------- colors ---------------------------------- */
+const CODES = {
+    reset: 0,
+    bold: 1,
+    dim: 2,
+    italic: 3,
+    underline: 4,
+    red: 31,
+    green: 32,
+    yellow: 33,
+    blue: 34,
+    magenta: 35,
+    cyan: 36,
+    white: 37,
+    gray: 90,
+    bgRed: 41,
+    bgGreen: 42,
+    bgYellow: 43,
+};
+function makeColors(enabled) {
+    const fn = ((name, text) => enabled ? `\u001b[${CODES[name]}m${text}\u001b[0m` : text);
+    fn.enabled = enabled;
+    return fn;
+}
+/** Strip ANSI escapes — used by the raw mode, and handy in assertions. */
+export function stripAnsi(text) {
+    // eslint-disable-next-line no-control-regex
+    return text.replace(/\u001b\[\d+m/g, "");
+}
+const SYMBOLS = {
+    info: "›",
+    success: "✔",
+    warning: "⚠",
+    error: "✖",
+    debug: "·",
+};
+export function createUi(options = {}) {
+    const raw = options.raw ?? false;
+    const useColors = options.colors ?? (!raw && !process.env.NO_COLOR);
+    const colors = makeColors(useColors);
+    const logs = [];
+    const errors = [];
+    const write = (line) => {
+        if (raw)
+            logs.push(stripAnsi(line));
+        else
+            console.log(line);
+    };
+    const writeError = (line) => {
+        if (raw)
+            errors.push(stripAnsi(line));
+        else
+            console.error(line);
+    };
+    const label = (symbol, color, message) => `${colors(color, symbol)} ${message}`;
+    const ui = {
+        colors,
+        logs,
+        errors,
+        write,
+        debug: (message) => write(label(SYMBOLS.debug, "gray", colors("gray", message))),
+        info: (message) => write(label(SYMBOLS.info, "blue", message)),
+        success: (message) => write(label(SYMBOLS.success, "green", message)),
+        warning: (message) => write(label(SYMBOLS.warning, "yellow", message)),
+        error: (message) => writeError(label(SYMBOLS.error, "red", message)),
+        fatal: (message) => writeError(label(SYMBOLS.error, "red", colors("bold", message))),
+        action(verb, target, status = "done") {
+            const color = status === "failed" ? "red" : status === "skipped" ? "yellow" : "green";
+            const line = `${colors(color, verb.toUpperCase().padEnd(8))}${target}`;
+            if (status === "failed")
+                writeError(line);
+            else
+                write(line);
+        },
+        table(head) {
+            const headers = head ? [...head] : [];
+            const body = [];
+            const table = {
+                head(...columns) {
+                    headers.length = 0;
+                    headers.push(...columns);
+                    return table;
+                },
+                row(cells) {
+                    body.push(cells);
+                    return table;
+                },
+                rows(list) {
+                    body.push(...list);
+                    return table;
+                },
+                toString() {
+                    const all = headers.length ? [headers, ...body] : body;
+                    if (!all.length)
+                        return "";
+                    const columns = Math.max(...all.map((r) => r.length));
+                    const widths = Array.from({ length: columns }, (_, i) => Math.max(...all.map((row) => stripAnsi(row[i] ?? "").length)));
+                    const line = (cells) => cells
+                        .map((cell, i) => cell + " ".repeat(Math.max(0, widths[i] - stripAnsi(cell).length)))
+                        .join("  ")
+                        .trimEnd();
+                    const out = [];
+                    if (headers.length) {
+                        out.push(line(headers.map((h) => colors("bold", h))));
+                        out.push(widths.map((w) => "─".repeat(w)).join("  "));
+                    }
+                    for (const row of body)
+                        out.push(line(row));
+                    return out.join("\n");
+                },
+                render() {
+                    const text = table.toString();
+                    if (text)
+                        write(text);
+                },
+            };
+            return table;
+        },
+        sticker(lines, title) {
+            const content = title ? [colors("bold", title), "", ...lines] : [...lines];
+            const width = Math.max(...content.map((l) => stripAnsi(l).length));
+            write(`┌─${"─".repeat(width)}─┐`);
+            for (const line of content) {
+                const pad = " ".repeat(width - stripAnsi(line).length);
+                write(`│ ${line}${pad} │`);
+            }
+            write(`└─${"─".repeat(width)}─┘`);
+        },
+        instructions(lines, title) {
+            if (title)
+                write(colors("bold", title));
+            lines.forEach((line, i) => write(`  ${colors("gray", `${i + 1}.`)} ${line}`));
+        },
+        tasks() {
+            const queue = [];
+            const runner = {
+                add(title, run) {
+                    queue.push({ title, run });
+                    return runner;
+                },
+                async run() {
+                    let ok = true;
+                    for (const { title, run } of queue) {
+                        let note = "";
+                        const handle = {
+                            update: (message) => {
+                                note = message;
+                            },
+                        };
+                        const started = Date.now();
+                        try {
+                            const result = await run(handle);
+                            const detail = result || note;
+                            const ms = Date.now() - started;
+                            ui.write(`${colors("green", SYMBOLS.success)} ${title}${detail ? ` ${colors("gray", `— ${detail}`)}` : ""} ${colors("gray", `(${ms}ms)`)}`);
+                        }
+                        catch (error) {
+                            ok = false;
+                            // Stop at the first failure: the tasks after it almost certainly
+                            // depend on it, and a cascade of red tells you nothing new.
+                            ui.error(`${title} — ${error instanceof Error ? error.message : String(error)}`);
+                            break;
+                        }
+                    }
+                    return ok;
+                },
+            };
+            return runner;
+        },
+        clear() {
+            logs.length = 0;
+            errors.length = 0;
+        },
+    };
+    return ui;
+}