@impeccable/reviews 0.1.0

package/dist/ui/screens.js

@@ -0,0 +1,544 @@
+import { readFileSync } from 'node:fs';
+import { format } from 'node:util';
+import { CURSOR_MARKER, getCapabilities, Input, KeybindingsManager, matchesKey, ProcessTerminal, setKeybindings, TUI_KEYBINDINGS, TuiAltScreen } from '@earendil-works/pi-tui';
+import { readCheckout } from '../preflight.js';
+import { copyText } from '../login.js';
+import { workStarted } from '../stages.js';
+import { mountUi } from './bridge.js';
+import { createFrameWriter, frameState } from './frames.js';
+import { drawFrame, OUTCOME, PRODUCT, palette } from './look.js';
+import { RunState } from './run-state.js';
+/** How often what moves on screen moves: the loader, the spinner. */
+const TICK_MS = 80;
+/** The run screen's first line, before the agent has said anything. */
+const FIRST_STATUS = 'Reading the repository';
+/** A first Esc on the run screen only asks for a second one within this long. */
+const STOP_WINDOW_MS = 3000;
+/** This package's version, for the corner of the frame. */
+const VERSION = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
+const interactive = () => Boolean(process.stdin.isTTY && process.stdout.isTTY);
+let wizard = null;
+/** --frames: where each screen goes as it changes. */
+let frames;
+class Wizard {
+    state = new RunState();
+    views = [];
+    questions = [];
+    /** Output from anywhere else while the screen is up, printed once it has gone. */
+    held = [];
+    frame = 0;
+    lastClock = '';
+    /** When Esc was first pressed on the run screen; a second press within the window stops the run. */
+    stopAsked = 0;
+    stopped = false;
+    /** How the mark is drawn here: plain text on a dumb terminal. */
+    drawing = process.env.TERM === 'dumb' ? 'plain' : 'blocks';
+    /** Bold, normal and dim until the terminal says what its background is; greys from then on. */
+    style = palette(undefined, this.drawing);
+    /** The window over a screen too tall for the terminal, and the screen it is for: each screen opens its own. */
+    scroll = { by: 0, page: 1, hidden: false };
+    scrollOf;
+    tui = new TuiAltScreen(new ProcessTerminal(), false, undefined, { mouse: false });
+    ticker;
+    restoreConsole;
+    onExit = () => this.stop();
+    onSignal = (signal) => {
+        this.stop();
+        process.kill(process.pid, signal);
+    };
+    constructor() {
+        // The alternate screen's own scrolling and search keys stay off: the wizard draws every row, and a typed answer keeps Home and End.
+        const off = Object.keys(TUI_KEYBINDINGS).filter((id) => id.startsWith('tui.altScreen.'));
+        setKeybindings(new KeybindingsManager(TUI_KEYBINDINGS, Object.fromEntries(off.map((id) => [id, []]))));
+        this.tui.setLayoutRoot(this);
+        this.tui.setFocus(this);
+        this.tui.start();
+        if (!process.env.NO_COLOR && getCapabilities().trueColor) {
+            void this.tui.queryTerminalBackgroundColor({ timeoutMs: 300 }).then((background) => {
+                if (!background)
+                    return;
+                this.style = palette(background, this.drawing);
+                this.redraw();
+            });
+        }
+        this.ticker = setInterval(() => this.tick(), TICK_MS).unref();
+        this.restoreConsole = captureConsole((line) => void (this.held = [...this.held, line].slice(-50)));
+        process.on('exit', this.onExit);
+        process.once('SIGTERM', this.onSignal);
+        process.once('SIGHUP', this.onSignal);
+        mountUi({
+            ask: (q) => this.ask(q),
+            status: (line) => (this.state.status(line), this.redraw()),
+            tasks: (tasks) => (this.state.setTasks(tasks), this.redraw()),
+            wait: (wait) => (this.state.wait(wait), this.redraw()),
+        });
+    }
+    push(view) {
+        this.views.push(view);
+        this.redraw();
+    }
+    remove(view) {
+        this.views = this.views.filter((v) => v !== view);
+        this.redraw();
+    }
+    /** Puts the sign-in link on the clipboard, and says so once it is there. */
+    copy(view) {
+        void view.opts
+            .onCopy()
+            .catch(() => false)
+            .then((copied) => {
+            view.copied ||= copied;
+            this.redraw();
+        });
+    }
+    /** Gives the terminal back as it was before the first screen, once the keys already pressed are read. */
+    async close() {
+        if (this.stopped)
+            return;
+        await this.tui.terminal.drainInput(250);
+        this.stop();
+    }
+    stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        if (wizard === this)
+            wizard = null;
+        clearInterval(this.ticker);
+        process.off('exit', this.onExit);
+        process.off('SIGTERM', this.onSignal);
+        process.off('SIGHUP', this.onSignal);
+        mountUi(null);
+        for (const question of this.questions.splice(0))
+            question.resolve({ skipped: true });
+        // Leaves the alternate screen without copying the last frame out of it: the scrollback gets the outro's summary only.
+        this.tui.stop({ preserveScreen: true });
+        this.restoreConsole();
+        for (const line of this.held.splice(0))
+            console.log(line);
+    }
+    redraw() {
+        if (!this.stopped)
+            this.tui.requestRender();
+    }
+    /** What moves on the run screen, if anything: the loader until the work after reading starts, then the running task's spinner or the status line's. Nothing moves while the person is being asked. */
+    motion() {
+        if (this.questions.length || this.views.at(-1)?.kind !== 'run')
+            return undefined;
+        const { tasks } = this.state;
+        const at = !workStarted(tasks) ? 'loader' : tasks.some((t) => t.status === 'in_progress') ? 'task' : 'status';
+        return { at, frame: this.frame };
+    }
+    stopArmed() {
+        return Date.now() - this.stopAsked < STOP_WINDOW_MS;
+    }
+    /** Redraws when something on screen moves with time: the loader or the spinner, the silence note, the way to stop. */
+    tick() {
+        const clock = JSON.stringify([this.state.band(!this.questions.length), this.stopArmed()]);
+        const moving = this.motion() !== undefined;
+        if (!moving && clock === this.lastClock)
+            return;
+        this.lastClock = clock;
+        if (moving)
+            this.frame++;
+        this.redraw();
+    }
+    ask(q) {
+        return new Promise((resolve) => {
+            const field = new Input({ prompt: '› ' });
+            field.focused = true;
+            // Pasted in, so the cursor waits at its end.
+            if (q.prefill)
+                field.handleInput(`\x1b[200~${q.prefill}\x1b[201~`);
+            const answered = (answer) => {
+                // The time the person took is not the run going quiet.
+                this.state.touch();
+                resolve(answer);
+            };
+            this.questions.push({ q, resolve: answered, field, password: q.kind === 'account' ? new Input() : undefined, focus: 0, cursor: 0, picked: new Set() });
+            this.redraw();
+        });
+    }
+    handleInput(data) {
+        if (matchesKey(data, 'ctrl+c'))
+            return this.interrupt();
+        const question = this.questions[0];
+        if (question)
+            return this.answer(question, data);
+        if (this.scrolls(data))
+            return this.redraw();
+        const view = this.views.at(-1);
+        const escape = matchesKey(data, 'escape');
+        if (view?.kind === 'intro') {
+            if (matchesKey(data, 'enter'))
+                view.done(true);
+            else if (escape)
+                view.done(false);
+        }
+        else if (view?.kind === 'signin') {
+            if (isLetter(data, 'c')) {
+                view.note = undefined;
+                this.copy(view);
+            }
+            else if (isLetter(data, 'p') && !view.pasting) {
+                this.paste(view);
+            }
+            else if (escape) {
+                view.opts.onCancel?.();
+            }
+        }
+        else if (view?.kind === 'run' && escape) {
+            if (this.stopArmed())
+                return this.interrupt();
+            this.stopAsked = Date.now();
+        }
+        else if ((view?.kind === 'pull' || (view?.kind === 'outro' && !view.leaving)) && view.copy && isLetter(data, 'c')) {
+            // C puts the screen's link on the clipboard, and says so once it is there; any other key goes on.
+            void view
+                .copy()
+                .catch(() => false)
+                .then((copied) => {
+                view.copied ||= copied;
+                this.redraw();
+            });
+        }
+        else if (view?.kind === 'pull' || (view?.kind === 'outro' && !view.leaving)) {
+            view.done();
+        }
+        this.redraw();
+    }
+    invalidate() { }
+    /** ↑↓ move the window over a screen too tall for the terminal a row, PgUp PgDn a page; true when `data` is one of them. */
+    scrolls(data) {
+        const by = matchesKey(data, 'up') ? -1 : matchesKey(data, 'down') ? 1 : matchesKey(data, 'pageUp') ? -this.scroll.page : matchesKey(data, 'pageDown') ? this.scroll.page : 0;
+        this.scroll.by += by;
+        return by !== 0;
+    }
+    /** Ctrl+C, or Esc twice on the run screen: the intro cancels, the test drive goes on to the outro, the outro closes, a run winds down through its cancel, and anything else stops here. */
+    interrupt() {
+        const view = this.views.at(-1);
+        if (view?.kind === 'intro')
+            return view.done(false);
+        if (view?.kind === 'pull')
+            return view.done();
+        if (view?.kind === 'outro')
+            return view.leaving ? undefined : view.done();
+        const run = this.views.find((v) => v.kind === 'run');
+        if (!run) {
+            this.stop();
+            process.exit(130);
+        }
+        this.stopAsked = 0;
+        for (const question of this.questions.splice(0))
+            question.resolve({ skipped: true });
+        this.state.status('Stopping the setup');
+        this.redraw();
+        run.cancel();
+    }
+    paste(view) {
+        view.pasting = true;
+        view.note = undefined;
+        void view.opts
+            .onPaste()
+            .catch(() => null)
+            .then((code) => {
+            view.pasting = false;
+            view.note = code ? 'Signing you in…' : 'That is not a code from this sign-in. Press P to try again.';
+            this.redraw();
+        });
+    }
+    answer(question, data) {
+        const { q } = question;
+        const choices = q.kind !== 'text' && q.options?.length ? q.options : null;
+        // PgUp PgDn scroll a question too tall for the terminal, as ↑↓ do unless they move among choices or an account's fields. Any other key brings its field or cursor back into view; while that is out of view, Enter, and Space on choices, only bring it back, so nothing is picked or sent unseen.
+        if (!((choices || question.password) && (matchesKey(data, 'up') || matchesKey(data, 'down'))) && this.scrolls(data))
+            return this.redraw();
+        const hidden = this.scroll.hidden;
+        this.scroll.by = 0;
+        if (hidden && (matchesKey(data, 'enter') || (choices && matchesKey(data, 'space'))))
+            return this.redraw();
+        const done = (answer) => {
+            this.questions.shift();
+            question.resolve(answer);
+            this.redraw();
+        };
+        question.note = undefined;
+        if (matchesKey(data, 'escape')) {
+            if (q.skippable)
+                return done({ skipped: true });
+            question.note = 'This one needs an answer.';
+        }
+        else if (q.kind === 'confirm') {
+            if (matchesKey(data, 'enter'))
+                return done({ skipped: false });
+        }
+        else if (question.password) {
+            // Tab or ↑↓ move between the two fields; Enter sends both once both are filled, else goes to the empty one.
+            const [username, password] = [question.field.getValue().trim(), question.password.getValue()];
+            if (matchesKey(data, 'enter') && username && password)
+                return done({ skipped: false, username, password });
+            if (matchesKey(data, 'enter'))
+                question.focus = username ? 1 : 0;
+            else if (matchesKey(data, 'tab') || matchesKey(data, 'shift+tab'))
+                question.focus = question.focus ? 0 : 1;
+            else if (matchesKey(data, 'up') || matchesKey(data, 'down'))
+                question.focus = matchesKey(data, 'up') ? 0 : 1;
+            else
+                (question.focus ? question.password : question.field).handleInput(data);
+        }
+        else if (matchesKey(data, 'enter')) {
+            if (choices && q.kind === 'single')
+                return done({ skipped: false, value: choices[question.cursor].value });
+            if (choices)
+                return done({ skipped: false, values: choices.filter((_, i) => question.picked.has(i)).map((o) => o.value) });
+            const value = question.field.getValue().trim();
+            if (value)
+                return done({ skipped: false, value });
+            if (q.skippable)
+                return done({ skipped: true });
+            question.note = 'Type an answer first.';
+        }
+        else if (!choices) {
+            question.field.handleInput(data);
+        }
+        else if (matchesKey(data, 'up')) {
+            question.cursor = (question.cursor + choices.length - 1) % choices.length;
+        }
+        else if (matchesKey(data, 'down') || matchesKey(data, 'tab')) {
+            question.cursor = (question.cursor + 1) % choices.length;
+        }
+        else if (/^[1-9]$/.test(data) && Number(data) <= choices.length) {
+            question.cursor = Number(data) - 1;
+            if (q.kind === 'multi')
+                toggle(question.picked, question.cursor);
+        }
+        else if (q.kind === 'multi' && matchesKey(data, 'space')) {
+            toggle(question.picked, question.cursor);
+        }
+        this.redraw();
+    }
+    /** The screen up now; `live` false holds what only time moves (a wait's timer) at its start, for the drawing that tells a change. */
+    scene(live = true) {
+        const view = this.views.at(-1);
+        if (!view)
+            return { kind: 'wait' };
+        if (view.kind === 'intro')
+            return { kind: 'intro' };
+        if (view.kind === 'signin')
+            return { kind: 'signin', link: view.link, copied: view.copied, again: view.again, note: view.pasting ? undefined : view.note };
+        if (view.kind === 'pull')
+            return { kind: 'pull', url: view.url, copied: view.copied };
+        if (view.kind === 'outro')
+            return { kind: 'outro', outro: view.outro, leaving: view.leaving, copied: view.copied };
+        return { kind: 'run', tasks: this.state.tasks, band: this.state.band(!this.questions.length, live), wait: this.state.timer(live) };
+    }
+    render(width) {
+        const question = this.questions[0];
+        const view = this.views.at(-1);
+        // The run's loader and tasks are two screens.
+        const screen = question ?? (view?.kind === 'run' ? (workStarted(this.state.tasks) ? 'tasks' : 'loader') : view);
+        if (screen !== this.scrollOf)
+            [this.scrollOf, this.scroll] = [screen, { by: 0, page: 1, hidden: false }];
+        const scene = this.scene();
+        const frame = {
+            width,
+            height: this.tui.terminal.rows,
+            scene,
+            question: question && {
+                q: question.q,
+                // A sensitive answer shows as dots; the field still does the editing. Only the field with the cursor shows it.
+                field: (w) => (question.q.sensitive ? dots(question.field, true) : question.focus ? `› ${question.field.getValue()}` : (question.field.render(w)[0] ?? '')),
+                password: question.password && (() => dots(question.password, question.focus === 1)),
+                focus: question.focus,
+                cursor: question.cursor,
+                picked: question.picked,
+                note: question.note,
+            },
+            motion: this.motion(),
+            stopping: this.views.at(-1)?.kind === 'run' && !question && this.stopArmed(),
+            scroll: this.scroll,
+            version: VERSION,
+            style: this.style,
+        };
+        const lines = drawFrame(frame);
+        if (frames) {
+            // Drawn again with what moves stopped: a screen that only moved its loader, its spinner or a wait's timer has not changed; a wait beginning or ending has.
+            const still = drawFrame({ ...frame, scene: this.scene(false), motion: frame.motion && { ...frame.motion, frame: 0 } });
+            frames.record(frameState(scene, question?.q, frames.last), lines, { question: question?.q, still });
+        }
+        return lines;
+    }
+}
+/** A hidden answer's field: a dot for each character typed, and the cursor after them when it has it. */
+const dots = (field, focused) => `› ${'•'.repeat(field.getValue().length)}${focused ? `${CURSOR_MARKER}\x1b[7m \x1b[27m` : ''}`;
+const isLetter = (data, letter) => matchesKey(data, letter) || matchesKey(data, `shift+${letter}`);
+function toggle(picked, i) {
+    if (!picked.delete(i))
+        picked.add(i);
+}
+/** Routes console output into `show` until the returned function puts it back. */
+function captureConsole(show) {
+    const saved = { log: console.log, info: console.info, warn: console.warn, error: console.error };
+    const capture = (...args) => format(...args).split('\n').forEach(show);
+    Object.assign(console, { log: capture, info: capture, warn: capture, error: capture });
+    return () => void Object.assign(console, saved);
+}
+/** The mark over --help, as the terminal prints it: plain text on a dumb terminal. */
+export function helpMark() {
+    return palette(undefined, process.env.TERM === 'dumb' ? 'plain' : 'blocks').mark(80).map((row) => row.trimStart());
+}
+/** The wizard when there is a terminal to draw it on. */
+function host() {
+    if (!interactive())
+        return null;
+    wizard ??= new Wizard();
+    return wizard;
+}
+function repository() {
+    try {
+        const checkout = readCheckout(process.cwd());
+        return `${checkout.owner}/${checkout.repo}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Writes every screen into `dir` as it changes (--frames), for the eval. */
+export function recordFrames(dir) {
+    frames = createFrameWriter(dir);
+}
+/** The first screen: what the command does, and the way on. Resolves true to go on, false to cancel. */
+export function showIntro() {
+    const screen = host();
+    if (!screen) {
+        console.log(`${PRODUCT}: setting up ${repository() ?? 'this repository'}.`);
+        console.log();
+        return Promise.resolve(true);
+    }
+    return new Promise((resolve) => {
+        const view = {
+            kind: 'intro',
+            done: (ok) => {
+                screen.remove(view);
+                if (ok)
+                    resolve(true);
+                else
+                    void screen.close().then(() => resolve(false));
+            },
+        };
+        screen.push(view);
+    });
+}
+/**
+ * The sign-in screen, in place of whatever is showing, until `close`: the
+ * link, put on the clipboard as it opens (`onCopy`, and again on C), and a way
+ * to paste the code from a remote shell (P calls `onPaste`, and a null from it
+ * says the code was wrong); Esc calls `onCancel`. Over a run it asks to sign
+ * in again.
+ */
+export function showSignIn(link, opts) {
+    const screen = host();
+    if (!screen) {
+        console.log(`Sign in to ${PRODUCT} in your browser. If it did not open, open this link:`);
+        console.log(link);
+        return { close() { } };
+    }
+    const view = { kind: 'signin', link, opts, pasting: false, again: screen.views.some((v) => v.kind === 'run') };
+    screen.push(view);
+    screen.copy(view);
+    return { close: () => screen.remove(view) };
+}
+/**
+ * The run screen: understanding the app with the loader until the work after
+ * reading starts, then the tasks, each with the status line, and questions in
+ * their place. It opens at once, so the wait for the agent's first words has
+ * something to show; calling it again while it is up only hands it a new
+ * `onCancel`. `close` gives the terminal back.
+ */
+export function showRun(opts) {
+    const screen = host();
+    if (!screen)
+        return { close: async () => { } };
+    const up = screen.views.find((v) => v.kind === 'run');
+    if (up)
+        up.cancel = opts.onCancel;
+    else {
+        screen.state = new RunState(Date.now, FIRST_STATUS);
+        screen.push({ kind: 'run', cancel: opts.onCancel });
+    }
+    return { close: () => screen.close() };
+}
+/** The outro in plain lines, for the scrollback: what stays once the screen has gone. */
+function summary(o) {
+    return ['', `${OUTCOME[o.outcome]} ${o.title}. ${o.result}`, ...o.links.map((l) => `${l.label}: ${l.url}`), ...o.todo.map((line) => `→ ${line}`), ...o.warnings.map((warning) => `! ${warning}`)];
+}
+/** Opens `url` in the browser and puts it on the clipboard, true once it is there. Neither can fail the screen, which shows the link either way. */
+async function handOver(url, hand) {
+    hand.open(url);
+    const copied = hand.copy(url).catch(() => false);
+    return (await Promise.race([copied, new Promise((r) => setTimeout(() => r(false), 1000).unref())])) === true;
+}
+/** The test drive on a screen of its own once the run has ended, before the last screen shows the setup pull request, handed over as it appears, until a key other than ↑↓ PgUp PgDn is pressed. Without a terminal there is no such screen: the summary has it. */
+export async function showPullRequest(url, hand) {
+    const screen = host();
+    if (!screen)
+        return;
+    const copied = await handOver(url, hand);
+    await new Promise((resolve) => {
+        const view = {
+            kind: 'pull',
+            url,
+            copied,
+            copy: () => hand.copy(url),
+            done: () => {
+                screen.remove(view);
+                resolve();
+            },
+        };
+        screen.views = [];
+        screen.push(view);
+    });
+}
+/** The last screen: what happened, what is left, any warnings and its pull request (handed over as it appears) or the links, until a key other than ↑↓ PgUp PgDn is pressed. Its summary then stays in the scrollback. */
+export async function showOutro(o, hand) {
+    const screen = host();
+    if (screen) {
+        const copied = o.link && hand ? await handOver(o.link, hand) : false;
+        // The link C copies: the pull request, or the one link a screen without it lists.
+        const link = o.link ?? (o.links.length === 1 ? o.links[0].url : undefined);
+        await new Promise((resolve) => {
+            const view = {
+                kind: 'outro',
+                outro: o,
+                leaving: false,
+                copied,
+                copy: link ? () => (hand?.copy ?? copyText)(link) : undefined,
+                done: () => {
+                    view.leaving = true;
+                    void screen.close().then(resolve);
+                },
+            };
+            screen.views = [];
+            screen.push(view);
+        });
+    }
+    for (const line of summary(o))
+        console.log(line);
+}
+/** Takes the screen down, if one is up, so what is printed next lands in the terminal as it was. */
+export async function closeScreens() {
+    await wizard?.close();
+}
+const exitNotes = [];
+/** Lines for the scrollback when the command exits, after the screen has gone and the outro's summary: where the logs are. */
+export function atExit(lines) {
+    if (!exitNotes.length) {
+        process.once('exit', () => {
+            wizard?.stop();
+            for (const note of exitNotes)
+                for (const line of note())
+                    console.log(line);
+        });
+    }
+    exitNotes.push(lines);
+}

package/dist/ui/sensitive.js

@@ -0,0 +1,14 @@
+/**
+ * Sensitive answers (a password, a key) as the person gives them, for the
+ * debug log and the transcript to redact wherever the value turns up later.
+ * The bridge reports every one, with a screen or without.
+ */
+const listeners = new Set();
+export function onSensitiveAnswer(listener) {
+    listeners.add(listener);
+    return () => void listeners.delete(listener);
+}
+export function noteSensitiveAnswer(value) {
+    for (const listener of listeners)
+        listener(value);
+}