@takodotid/circuit 0.43.1 → 1.0.0-rc.2

package/src/cli/text-editor.ts

@@ -0,0 +1,268 @@
+// A small text editor in the terminal, for `circuit secrets`: the whole text on one screen, typed into as in any editor. Ctrl+S saves; Esc leaves, or Ctrl+X, or Ctrl+Q where the terminal passes it on (VS Code's keeps Ctrl+Q for itself). It draws on the terminal's alternate screen, so what it showed is gone from the scrollback when it closes, and it never writes the text anywhere but through `save`.
+
+/** One key, as the terminal sends it. */
+export type Key =
+    | { kind: "text"; text: string }
+    | { kind: "up" | "down" | "left" | "right" | "home" | "end" | "page-up" | "page-down" | "enter" | "backspace" | "delete" }
+    | { kind: "save" | "quit" };
+
+/** The text being edited, its cursor, and whether it changed since the last save. */
+export class EditorBuffer {
+    lines: string[];
+    row = 0;
+    col = 0;
+    modified = false;
+
+    constructor(text: string) {
+        this.lines = text.replace(/\r\n?/g, "\n").replace(/\n$/, "").split("\n");
+    }
+
+    text(): string {
+        return `${this.lines.join("\n")}\n`;
+    }
+
+    private get line(): string {
+        return this.lines[this.row]!;
+    }
+
+    /** Type text at the cursor. A paste may hold several lines. */
+    insert(text: string): void {
+        const parts = text.replace(/\r\n?/g, "\n").replace(/\t/g, "    ").split("\n");
+        const before = this.line.slice(0, this.col);
+        const after = this.line.slice(this.col);
+
+        if (parts.length === 1) {
+            this.lines[this.row] = before + parts[0] + after;
+            this.col += parts[0]!.length;
+        } else {
+            const last = parts[parts.length - 1]!;
+            this.lines.splice(this.row, 1, before + parts[0], ...parts.slice(1, -1), last + after);
+            this.row += parts.length - 1;
+            this.col = last.length;
+        }
+        this.modified = true;
+    }
+
+    newline(): void {
+        this.insert("\n");
+    }
+
+    backspace(): void {
+        if (this.col > 0) {
+            this.lines[this.row] = this.line.slice(0, this.col - 1) + this.line.slice(this.col);
+            this.col--;
+        } else if (this.row > 0) {
+            const previous = this.lines[this.row - 1]!;
+            this.lines.splice(this.row - 1, 2, previous + this.line);
+            this.row--;
+            this.col = previous.length;
+        } else return;
+        this.modified = true;
+    }
+
+    delete(): void {
+        if (this.col < this.line.length) this.lines[this.row] = this.line.slice(0, this.col) + this.line.slice(this.col + 1);
+        else if (this.row < this.lines.length - 1) this.lines.splice(this.row, 2, this.line + this.lines[this.row + 1]);
+        else return;
+        this.modified = true;
+    }
+
+    move(kind: "up" | "down" | "left" | "right" | "home" | "end", by = 1): void {
+        if (kind === "left") {
+            if (this.col > 0) this.col--;
+            else if (this.row > 0) this.col = this.lines[--this.row]!.length;
+        } else if (kind === "right") {
+            if (this.col < this.line.length) this.col++;
+            else if (this.row < this.lines.length - 1) {
+                this.row++;
+                this.col = 0;
+            }
+        } else if (kind === "up") this.row = Math.max(0, this.row - by);
+        else if (kind === "down") this.row = Math.min(this.lines.length - 1, this.row + by);
+        else if (kind === "home") this.col = 0;
+        else this.col = this.line.length;
+
+        this.col = Math.min(this.col, this.line.length);
+    }
+}
+
+/** What the editor reads keys from: a terminal in raw mode. */
+export type TerminalInput = Pick<NodeJS.ReadStream, "on" | "off" | "resume" | "pause" | "setEncoding"> & {
+    setRawMode(mode: boolean): unknown;
+};
+/** What the editor draws on. */
+export type TerminalOutput = Pick<NodeJS.WriteStream, "write" | "on" | "off"> & { rows?: number; columns?: number };
+
+export class TextEditor {
+    private static readonly SEQUENCES: Record<string, Key["kind"]> = {
+        "\x1b[A": "up",
+        "\x1b[B": "down",
+        "\x1b[C": "right",
+        "\x1b[D": "left",
+        "\x1bOA": "up",
+        "\x1bOB": "down",
+        "\x1bOC": "right",
+        "\x1bOD": "left",
+        "\x1b[H": "home",
+        "\x1b[F": "end",
+        "\x1bOH": "home",
+        "\x1bOF": "end",
+        "\x1b[1~": "home",
+        "\x1b[4~": "end",
+        "\x1b[5~": "page-up",
+        "\x1b[6~": "page-down",
+        "\x1b[3~": "delete",
+    };
+
+    private static readonly PASTE_START = "\x1b[200~";
+    private static readonly PASTE_END = "\x1b[201~";
+
+    /** The keys in what the terminal sent. An escape sequence it doesn't know is dropped. */
+    static keys(data: string): Key[] {
+        const keys: Key[] = [];
+        let text = "";
+        const flush = () => {
+            if (text) keys.push({ kind: "text", text });
+            text = "";
+        };
+
+        for (let i = 0; i < data.length;) {
+            if (data.startsWith(TextEditor.PASTE_START, i)) {
+                flush();
+                const end = data.indexOf(TextEditor.PASTE_END, i);
+                const pasted = data.slice(i + TextEditor.PASTE_START.length, end < 0 ? data.length : end);
+                if (pasted) keys.push({ kind: "text", text: pasted });
+                i = end < 0 ? data.length : end + TextEditor.PASTE_END.length;
+                continue;
+            }
+
+            const char = data[i]!;
+            if (char === "\x1b") {
+                flush();
+                const sequence = /^\x1b(\[[0-9;]*[A-Za-z~]|O[A-Za-z])?/.exec(data.slice(i))![0];
+                const kind = TextEditor.SEQUENCES[sequence.replace(/^\x1b\[1;\d+([A-H])$/, "\x1b[$1")];
+                if (kind) keys.push({ kind } as Key);
+                // Esc alone, nothing after it, is the key itself, not the start of a sequence.
+                else if (sequence === "\x1b" && i + 1 === data.length) keys.push({ kind: "quit" });
+                i += sequence.length;
+                continue;
+            }
+
+            const control: Record<string, Key["kind"]> = {
+                "\r": "enter",
+                "\n": "enter",
+                "\x7f": "backspace",
+                "\b": "backspace",
+                "\x13": "save",
+                "\x0f": "save",
+                "\x11": "quit",
+                "\x18": "quit",
+                "\x03": "quit",
+            };
+            if (control[char]) {
+                flush();
+                // A terminal may send Enter as \r\n: one Enter.
+                if (char === "\r" && data[i + 1] === "\n") i++;
+                keys.push({ kind: control[char] } as Key);
+            } else if (char === "\t" || char >= " ") text += char;
+            i++;
+        }
+
+        flush();
+        return keys;
+    }
+
+    /**
+     * Edit `text` on the whole screen until the person leaves. `save` gets the text on Ctrl+S and gives back why it can't be saved, or
+     * undefined once saved. `note` shows at the bottom until the first key. Leaving with changes not saved asks to leave a second time.
+     */
+    static async open(options: {
+        title: string;
+        text: string;
+        note?: string;
+        save: (text: string) => string | undefined;
+        /** The terminal: the process's own unless a test gives another. */
+        terminal?: { input: TerminalInput; output: TerminalOutput };
+    }): Promise<void> {
+        const stdin = options.terminal?.input ?? (process.stdin as TerminalInput);
+        const out = options.terminal?.output ?? (process.stdout as TerminalOutput);
+        const buffer = new EditorBuffer(options.text);
+        const help = "Ctrl+S save   Esc leave";
+        let message = options.note ? `${options.note}   ${help}` : help;
+        let top = 0;
+        let left = 0;
+        let leaving = false;
+
+        const draw = () => {
+            const rows = Math.max(3, out.rows ?? 24);
+            const cols = Math.max(20, out.columns ?? 80);
+            const height = rows - 2;
+
+            if (buffer.row < top) top = buffer.row;
+            if (buffer.row >= top + height) top = buffer.row - height + 1;
+            if (buffer.col < left) left = buffer.col;
+            if (buffer.col >= left + cols) left = buffer.col - cols + 1;
+
+            const title = ` ${options.title}${buffer.modified ? "  (not saved)" : ""}`;
+            let screen = `\x1b[?25l\x1b[H\x1b[7m${title.slice(0, cols).padEnd(cols)}\x1b[0m`;
+            for (let i = 0; i < height; i++) {
+                const line = buffer.lines[top + i];
+                screen += `\x1b[${i + 2};1H\x1b[K${line === undefined ? "" : line.slice(left, left + cols)}`;
+            }
+            screen += `\x1b[${rows};1H\x1b[K\x1b[7m${` ${message}`.slice(0, cols).padEnd(cols)}\x1b[0m`;
+            screen += `\x1b[${buffer.row - top + 2};${buffer.col - left + 1}H\x1b[?25h`;
+            out.write(screen);
+            return height;
+        };
+
+        out.write("\x1b[?1049h\x1b[?2004h");
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding("utf8");
+
+        try {
+            await new Promise<void>((done) => {
+                let height = draw();
+                const redraw = () => (height = draw());
+                out.on("resize", redraw);
+
+                const onData = (data: string) => {
+                    for (const key of TextEditor.keys(data)) {
+                        if (key.kind !== "quit") leaving = false;
+                        message = help;
+
+                        if (key.kind === "text") buffer.insert(key.text);
+                        else if (key.kind === "enter") buffer.newline();
+                        else if (key.kind === "backspace") buffer.backspace();
+                        else if (key.kind === "delete") buffer.delete();
+                        else if (key.kind === "page-up") buffer.move("up", height);
+                        else if (key.kind === "page-down") buffer.move("down", height);
+                        else if (key.kind === "save") {
+                            const problem = options.save(buffer.text());
+                            if (problem) message = `Not saved: ${problem}`;
+                            else {
+                                buffer.modified = false;
+                                message = `Saved. ${help}`;
+                            }
+                        } else if (key.kind === "quit") {
+                            if (!buffer.modified || leaving) {
+                                stdin.off("data", onData);
+                                out.off("resize", redraw);
+                                done();
+                                return;
+                            }
+                            leaving = true;
+                            message = "Not saved. Esc again leaves without saving; Ctrl+S saves.";
+                        } else buffer.move(key.kind);
+                    }
+                    redraw();
+                };
+                stdin.on("data", onData);
+            });
+        } finally {
+            stdin.setRawMode(false);
+            stdin.pause();
+            out.write("\x1b[?2004l\x1b[?1049l");
+        }
+    }
+}

package/src/cli/ui.ts

@@ -0,0 +1,298 @@
+// How the command line talks to a person: a spinner while it waits, questions with a safe default, and messages in colour. Without a terminal, such as in a script, nothing spins and nothing is asked.
+
+import * as prompts from "@clack/prompts";
+import { styleText } from "node:util";
+
+/** One choice in a list: what it gives back, what it says, a hint beside it, and whether it can be picked. */
+export type Choice<T> = { value: T; label: string; hint?: string; disabled?: boolean };
+
+export class Ui {
+    /** A person is at a terminal: Circuit may spin and ask. */
+    static readonly interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+
+    /** Colour only for a terminal, and never when NO_COLOR is set. */
+    private static paint(format: Parameters<typeof styleText>[0], text: string, stream: NodeJS.WriteStream = process.stdout): string {
+        return stream.isTTY && !process.env.NO_COLOR ? styleText(format, text) : text;
+    }
+
+    static bold(text: string): string {
+        return Ui.paint("bold", text);
+    }
+
+    static dim(text: string): string {
+        return Ui.paint("dim", text);
+    }
+
+    static red(text: string, stream?: NodeJS.WriteStream): string {
+        return Ui.paint("red", text, stream);
+    }
+
+    static green(text: string): string {
+        return Ui.paint("green", text);
+    }
+
+    static yellow(text: string, stream?: NodeJS.WriteStream): string {
+        return Ui.paint("yellow", text, stream);
+    }
+
+    private static magenta(text: string): string {
+        return Ui.paint("magenta", text);
+    }
+
+    /** Print why Circuit stops, and stop. */
+    static fail(message: string): never {
+        Ui.active?.halt();
+        console.error(Ui.red(message, process.stderr));
+        process.exit(1);
+    }
+
+    static warn(message: string): void {
+        console.error(`${Ui.yellow("  warn ", process.stderr)}  ${message}`);
+    }
+
+    static error(message: string): void {
+        console.error(`${Ui.red("  error", process.stderr)}  ${message}`);
+    }
+
+    static done(message: string): void {
+        console.log(`${Ui.green("✔")} ${message}`);
+    }
+
+    /** The spinner on screen now: drawn again after a line printed above it, and halted when Circuit stops. */
+    private static active: { draw: () => void; halt: () => void } | undefined;
+
+    /**
+     * Run `work` behind a spinner that says what Circuit waits for, with the seconds it has taken. Lines printed meanwhile, such as a
+     * platform's progress, go above it. When done it leaves a line, ◇ when it worked or ■ when it failed.
+     */
+    static step<T>(message: string, work: () => Promise<T>): Promise<T> {
+        return Ui.spin(message, work, { leave: true, delay: 0 });
+    }
+
+    /**
+     * Wait for `work` with a spinner that leaves nothing behind, for a short wait such as the check before each command. It shows only
+     * after a moment, so a quick answer, such as one from the cache, shows nothing.
+     */
+    static wait<T>(message: string, work: () => Promise<T>): Promise<T> {
+        return Ui.spin(message, work, { leave: false, delay: 150 });
+    }
+
+    private static async spin<T>(message: string, work: () => Promise<T>, options: { leave: boolean; delay: number }): Promise<T> {
+        // In a script nothing spins; inside another spinner, that one keeps going.
+        if (!Ui.interactive || Ui.active) return work();
+
+        // One line only: a longer one would wrap, and could not be drawn over.
+        const width = Math.max(20, (process.stdout.columns ?? 80) - 12);
+        const text = message.length > width ? `${message.slice(0, width - 1)}…` : message;
+        const frames = ["◒", "◐", "◓", "◑"];
+        const started = Date.now();
+        let frame = 0;
+        let shown = false;
+
+        const seconds = () => {
+            const taken = Math.floor((Date.now() - started) / 1000);
+            return taken >= 1 ? Ui.dim(` [${taken}s]`) : "";
+        };
+        const draw = () => {
+            shown = true;
+            process.stdout.write(`\r${Ui.magenta(frames[frame++ % frames.length]!)}  ${text}${seconds()}\x1b[K`);
+        };
+        const clear = () => {
+            if (shown) process.stdout.write("\r\x1b[K");
+        };
+
+        // A line printed while the spinner is on goes above it, and the spinner is drawn again under it.
+        const printers = { log: console.log, info: console.info, warn: console.warn, error: console.error };
+        for (const name of Object.keys(printers) as (keyof typeof printers)[])
+            console[name] = (...args: unknown[]) => {
+                clear();
+                printers[name](...args);
+                if (shown) draw();
+            };
+
+        let ticker: ReturnType<typeof setInterval> | undefined;
+        const start = setTimeout(() => {
+            draw();
+            ticker = setInterval(draw, 100);
+        }, options.delay);
+
+        const halt = () => {
+            clearTimeout(start);
+            clearInterval(ticker);
+            Object.assign(console, printers);
+            clear();
+            Ui.active = undefined;
+        };
+        Ui.active = { draw: () => shown && draw(), halt };
+
+        try {
+            const result = await work();
+            const taken = seconds();
+            halt();
+            if (options.leave) console.log(`${Ui.green("◇")}  ${text}${taken}`);
+            return result;
+        } catch (error) {
+            const taken = seconds();
+            halt();
+            if (options.leave) console.log(`${Ui.red("■")}  ${text}${taken}`);
+            throw error;
+        }
+    }
+
+    /**
+     * Say what Circuit waits for while it can't spin, such as while 1Password asks the person to unlock it. Gives back what takes the
+     * line away again, and brings back the spinner it covered.
+     */
+    static blocked(message: string): () => void {
+        if (!Ui.interactive) return () => {};
+
+        process.stdout.write(`\r${Ui.magenta("◒")}  ${message}\x1b[K`);
+        return () => {
+            process.stdout.write("\r\x1b[K");
+            Ui.active?.draw();
+        };
+    }
+
+    /** Stop when the person pressed Ctrl-C or Esc on a question. */
+    private static answered<T>(value: T): Exclude<T, symbol> {
+        if (prompts.isCancel(value)) {
+            prompts.cancel("Stopped, nothing changed.");
+            process.exit(130);
+        }
+
+        return value as Exclude<T, symbol>;
+    }
+
+    /** A yes or no question. The default is no, so a stray Enter changes nothing. */
+    static async confirm(message: string, initial = false): Promise<boolean> {
+        return Ui.answered(await prompts.confirm({ message, initialValue: initial }));
+    }
+
+    static async select<T>(message: string, choices: readonly Choice<T>[], initial?: T): Promise<T> {
+        const options = choices.map((choice) => ({ ...choice })) as prompts.Option<T>[];
+        return Ui.answered(await prompts.select<T>({ message, options, ...(initial !== undefined ? { initialValue: initial } : {}) }));
+    }
+
+    static async text(
+        message: string,
+        options: { initial?: string; placeholder?: string; check?: (value: string) => string | undefined } = {}
+    ): Promise<string> {
+        return Ui.answered(
+            await prompts.text({
+                message,
+                ...(options.initial !== undefined ? { initialValue: options.initial } : {}),
+                ...(options.placeholder !== undefined ? { placeholder: options.placeholder } : {}),
+                ...(options.check ? { validate: (value) => options.check!(value ?? "") } : {}),
+            })
+        );
+    }
+
+    /** A value typed without showing it, such as a password. With `empty`, Enter alone gives "". */
+    static async secret(message: string, options: { empty?: boolean } = {}): Promise<string> {
+        const answer = await prompts.password({ message, validate: (value) => (value || options.empty ? undefined : "Type a value.") });
+        return Ui.answered(answer) ?? "";
+    }
+
+    /** How wide text is on screen: colours take no room. */
+    private static width(text: string): number {
+        return text.replace(/\x1b\[[0-9;]*m/g, "").length;
+    }
+
+    /** Words of `text` in lines of at most `width` characters; a longer word is cut. Colours are dropped, as a cut could break one. */
+    private static wrap(text: string, width: number): string[] {
+        const plain = text.replace(/\x1b\[[0-9;]*m/g, "");
+        if (plain.length <= width) return [text];
+
+        const lines: string[] = [];
+        let line = "";
+        for (const word of plain.split(" ")) {
+            const next = line ? `${line} ${word}` : word;
+            if (next.length <= width) {
+                line = next;
+                continue;
+            }
+            if (line) lines.push(line);
+            let rest = word;
+            while (rest.length > width) {
+                lines.push(rest.slice(0, width));
+                rest = rest.slice(width);
+            }
+            line = rest;
+        }
+        if (line) lines.push(line);
+        return lines;
+    }
+
+    /**
+     * Rows in a table with lines around each cell and a heading row. A column with `right` lines up its numbers on the right. In a terminal
+     * too narrow for it, the last column's text goes on more lines.
+     */
+    static table(columns: readonly { title: string; right?: boolean }[], rows: readonly (readonly string[])[]): string {
+        const widths = columns.map((column, at) => Math.max(column.title.length, ...rows.map((row) => Ui.width(row[at] ?? ""))));
+
+        // The borders and padding take 3 characters a column, and 1 more.
+        const room = (process.stdout.isTTY ? (process.stdout.columns ?? 0) : 0) - 1 - 3 * columns.length;
+        const others = widths.slice(0, -1).reduce((sum, width) => sum + width, 0);
+        if (room > 0 && others + widths.at(-1)! > room)
+            widths[widths.length - 1] = Math.max(columns.at(-1)!.title.length, room - others, 12);
+
+        const line = (left: string, middle: string, right: string) =>
+            Ui.dim(`${left}${widths.map((width) => "─".repeat(width + 2)).join(middle)}${right}`);
+        const bar = Ui.dim("│");
+        const cell = (text: string, at: number) => {
+            const pad = " ".repeat(Math.max(0, widths[at]! - Ui.width(text)));
+            return columns[at]!.right ? `${pad}${text}` : `${text}${pad}`;
+        };
+        const row = (cells: readonly string[]) => {
+            const wrapped = cells.map((text, at) => (at === columns.length - 1 ? Ui.wrap(text, widths[at]!) : [text]));
+            const height = Math.max(...wrapped.map((lines) => lines.length));
+            return Array.from(
+                { length: height },
+                (_, index) => `${bar} ${wrapped.map((lines, at) => cell(lines[index] ?? "", at)).join(` ${bar} `)} ${bar}`
+            );
+        };
+
+        return [
+            line("┌", "┬", "┐"),
+            ...row(columns.map((column) => Ui.bold(column.title))),
+            line("├", "┼", "┤"),
+            ...rows.flatMap((cells) => row(columns.map((_, at) => cells[at] ?? ""))),
+            line("└", "┴", "┘"),
+        ].join("\n");
+    }
+
+    /** The CIRCUIT logotype, in the font of the one on the site, drawn with blocks. */
+    static readonly LOGO = [
+        " ▄██████▄   ██  ███████▄    ▄██████▄   ██     ██  ██  ████████",
+        "███    ███  ██  ██    ███  ███    ███  ██     ██  ██     ██",
+        "██          ██  ███████▀   ██          ██     ██  ██     ██",
+        "███    ███  ██  ██   ██▄   ███    ███  ███   ███  ██     ██",
+        " ▀██████▀   ██  ██    ██▄   ▀██████▀    ▀█████▀   ██     ██",
+    ];
+
+    /** The logotype and a line under it, in a terminal wide enough; elsewhere, the line alone. */
+    static logo(line: string): void {
+        if (!Ui.interactive) return;
+        if ((process.stdout.columns ?? 0) < 64) {
+            console.log(Ui.bold(line));
+            return;
+        }
+        console.log(`\n${Ui.LOGO.map((row) => `  ${Ui.bold(row)}`).join("\n")}\n\n  ${Ui.dim(line)}\n`);
+    }
+
+    /** A heading for a run of questions, and the line that closes it. */
+    static intro(title: string): void {
+        if (Ui.interactive) prompts.intro(Ui.bold(title));
+    }
+
+    static outro(message: string): void {
+        if (Ui.interactive) prompts.outro(message);
+        else console.log(message);
+    }
+
+    /** A boxed note, such as the next steps. */
+    static note(message: string, title?: string): void {
+        if (Ui.interactive) prompts.note(message, title);
+        else console.log(title ? `${title}\n${message}` : message);
+    }
+}

package/src/cli/version.ts

@@ -0,0 +1,2 @@
+/** This Circuit's version, the same as package.json's. */
+export const VERSION = "1.0.0-rc.2";