@impeccable/reviews 0.1.0

package/dist/transcript.js

@@ -0,0 +1,139 @@
+import { appendFileSync, chmodSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { redact, SECRET_FIELD } from './log.js';
+const LIMIT = 2000;
+/** `location` is a .md file (the .jsonl goes beside it) or a folder; the OS temp folder without one. */
+export function transcriptPaths(runId, location) {
+    if (location?.endsWith('.md'))
+        return { markdown: location, events: `${location.slice(0, -3)}.jsonl` };
+    const name = `transcript-${runId.replace(/[^\w.-]/g, '_')}`;
+    const dir = location ?? tmpdir();
+    return { markdown: join(dir, `${name}.md`), events: join(dir, `${name}.jsonl`) };
+}
+const blocks = (content) => (Array.isArray(content) ? content : typeof content === 'string' ? [{ type: 'text', text: content }] : []);
+const textOf = (content) => blocks(content)
+    .filter((b) => b.type === 'text')
+    .map((b) => b.text ?? '')
+    .join('\n')
+    .trim();
+const cut = (text) => (text.length > LIMIT ? `${text.slice(0, LIMIT)}\n[cut: ${LIMIT} of ${text.length} characters shown]` : text);
+const fenced = (text, lang = '') => {
+    const fence = text.includes('```') ? '````' : '```';
+    return `${fence}${lang}\n${text}\n${fence}`;
+};
+const count = (n) => (n ?? 0).toLocaleString('en-US');
+/** A copy of an event with every string cleaned, a credential field's value and everything belonging to a sensitive tool call reading [redacted]. */
+function mask(value, calls, clean) {
+    if (typeof value === 'string')
+        return clean(value);
+    if (Array.isArray(value))
+        return value.map((v) => mask(v, calls, clean));
+    if (!value || typeof value !== 'object')
+        return value;
+    const obj = value;
+    const hidden = typeof obj.toolCallId === 'string' && calls.has(obj.toolCallId);
+    const secret = (k, v) => (hidden && ['content', 'result', 'details'].includes(k)) || (typeof v === 'string' && SECRET_FIELD.test(k));
+    return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, secret(k, v) ? '[redacted]' : mask(v, calls, clean)]));
+}
+export function createTranscript(opts) {
+    const paths = transcriptPaths(opts.runId, opts.location);
+    const secrets = new Set(opts.secrets?.filter(Boolean));
+    const sensitiveCalls = new Set();
+    const questions = new Set();
+    let turn = 0;
+    let failure;
+    /** Writes through, or remembers why it could not: a transcript is not worth stopping the run for. */
+    const attempt = (write) => {
+        if (failure)
+            return;
+        try {
+            write();
+        }
+        catch (err) {
+            failure = err instanceof Error ? err.message : String(err);
+        }
+    };
+    // Not even a token's prefix stays, so a search for pst_ or phr_ finds nothing.
+    // Each secret as typed and as JSON writes it, for a result that is JSON text.
+    const clean = (text) => redact(text, [...secrets].flatMap((s) => [s, JSON.stringify(s).slice(1, -1)])).replace(/\b(pst|phr)_\[redacted\]/g, '[redacted]');
+    const append = (path, text) => attempt(() => appendFileSync(path, clean(text), { mode: 0o600 }));
+    const md = (...parts) => append(paths.markdown, `${parts.join('\n\n')}\n\n`);
+    // Each run starts both files afresh, so a path used before holds this run alone.
+    attempt(() => {
+        mkdirSync(dirname(paths.markdown), { recursive: true });
+        writeFileSync(paths.markdown, clean(`# Impeccable setup transcript\n\n${opts.heading} · started ${new Date().toISOString()}\n\n`), { mode: 0o600 });
+        writeFileSync(paths.events, '', { mode: 0o600 });
+        // mode only applies to a new file; one that was there keeps its own until told.
+        for (const path of [paths.markdown, paths.events])
+            chmodSync(path, 0o600);
+    });
+    function assistant(message) {
+        const parts = [];
+        for (const block of blocks(message.content)) {
+            if (block.type === 'thinking')
+                parts.push(`**Thinking**`, block.redacted ? '_(redacted by the provider)_' : (block.thinking ?? '').trim().replace(/^/gm, '> '));
+            else if (block.type === 'text' && block.text?.trim())
+                parts.push(block.text.trim());
+            else if (block.type === 'toolCall' && block.id) {
+                const args = block.arguments ?? {};
+                if (block.name === 'impeccable_ask') {
+                    questions.add(block.id);
+                    if (args.sensitive === true)
+                        sensitiveCalls.add(block.id);
+                    const options = Array.isArray(args.options) ? args.options.map((o) => `- ${String(o.label)} (\`${String(o.value)}\`)`) : [];
+                    parts.push(`**Question** \`${String(args.id)}\` (${String(args.kind)}${args.sensitive === true ? ', sensitive' : ''}${args.skippable === true ? ', skippable' : ''})`, String(args.prompt ?? ''), ...(options.length ? [options.join('\n')] : []));
+                }
+                else {
+                    parts.push(`**Tool call** \`${block.name}\``, fenced(cut(JSON.stringify(args, null, 2)), 'json'));
+                }
+            }
+        }
+        if (message.stopReason === 'error')
+            parts.push(`**Error** ${message.errorMessage ?? 'the model call failed'}`);
+        const u = message.usage;
+        if (u)
+            parts.push(`_Usage: ${count(u.input)} in · ${count(u.output)} out · ${count(u.cacheRead)} cache read · ${count(u.cacheWrite)} cache write · $${(u.cost?.total ?? 0).toFixed(4)}_`);
+        if (parts.length)
+            md(...parts);
+    }
+    return {
+        paths,
+        get failure() {
+            return failure;
+        },
+        report() {
+            if (!failure)
+                return [`Transcript of the run: ${paths.markdown}`, `Its raw events: ${paths.events}`];
+            return [`The transcript stops early, because a write failed (${failure}). What was saved: ${paths.markdown} and ${paths.events}`];
+        },
+        secret(value) {
+            if (value)
+                secrets.add(value);
+        },
+        record(event) {
+            if (event.type === 'message_update' || event.type === 'tool_execution_update')
+                return;
+            // Cleaned string by string before it is serialized (#82): each line stays JSON, and a secret JSON escapes is still found.
+            const line = JSON.stringify({ at: new Date().toISOString(), ...mask(event, sensitiveCalls, clean) });
+            attempt(() => appendFileSync(paths.events, `${line}\n`, { mode: 0o600 }));
+            if (event.type === 'turn_start') {
+                md(`## Turn ${++turn} · ${new Date().toISOString().slice(11, 19)}Z`);
+            }
+            else if (event.type === 'message_end') {
+                const message = event.message;
+                if (message.role === 'assistant')
+                    assistant(message);
+                else if (message.role === 'user')
+                    md(`**Prompt**`, cut(textOf(message.content)).replace(/^/gm, '> '));
+                else if (message.role === 'custom')
+                    md(`_Context sent to the model (${message.customType ?? 'custom'}, ${textOf(message.content).length} characters)._`);
+            }
+            else if (event.type === 'tool_execution_end') {
+                const answer = questions.has(event.toolCallId);
+                const text = sensitiveCalls.has(event.toolCallId) ? '[redacted]' : cut(textOf(event.result?.content));
+                md(`**${answer ? 'Answer' : 'Result'}** \`${event.toolName}\`${event.isError ? ' (error)' : ''}`, fenced(text || '(nothing)'));
+            }
+        },
+    };
+}

package/dist/ui/bridge.js

@@ -0,0 +1,145 @@
+import { createInterface } from 'node:readline';
+import { Writable } from 'node:stream';
+import { noteSensitiveAnswer } from './sensitive.js';
+let mounted = null;
+/** Asks the person: the question on the screen, or printed with one line read from stdin. */
+export async function askPerson(q) {
+    const answer = await (mounted ? mounted.ask(q) : askOnStdin(q));
+    if (q.sensitive)
+        for (const value of [answer.value, ...(answer.values ?? [])])
+            if (value)
+                noteSensitiveAnswer(value);
+    if (answer.password)
+        noteSensitiveAnswer(answer.password);
+    return answer;
+}
+/** A status line for the status band. */
+export function reportStatus(line) {
+    mounted?.status(line);
+}
+/** Replaces the task list. */
+export function reportTasks(tasks) {
+    mounted?.tasks(tasks);
+}
+/** The run waits on something outside it (a host's build): the screen counts the time up beside the status line until `null` ends it. */
+export function reportWait(wait) {
+    mounted?.wait?.(wait);
+}
+/** The screen registers itself; null = headless. */
+export function mountUi(ui) {
+    mounted = ui;
+}
+/** What a typed line answers, or null when it answers nothing and the question goes again. */
+function answerOf(q, line) {
+    const text = line.trim();
+    if (!text)
+        return q.skippable ? { skipped: true } : q.kind === 'multi' ? { skipped: false, values: [] } : null;
+    if (q.kind === 'text')
+        return { skipped: false, value: text };
+    const options = q.options ?? [];
+    const pick = (word) => options[Number(word) - 1] ?? options.find((o) => o.value === word || o.label.toLowerCase() === word.toLowerCase());
+    if (q.kind === 'single') {
+        const option = pick(text);
+        return option ? { skipped: false, value: option.value } : null;
+    }
+    const picked = text.split(',').map((word) => pick(word.trim()));
+    return picked.every(Boolean) ? { skipped: false, values: [...new Set(picked.map((o) => o.value))] } : null;
+}
+/** Lines typed or piped in, kept across questions so one read never swallows the next answer. */
+const inputs = new WeakMap();
+/** The next line on stdin, or null once it has ended. stdin is paused again in between, so it never holds the process open. */
+function nextLine() {
+    const stdin = process.stdin;
+    const input = inputs.get(stdin) ?? { lines: [], partial: '', ended: false };
+    inputs.set(stdin, input);
+    const markEnded = () => {
+        if (input.ended)
+            return;
+        input.ended = true;
+        if (input.partial)
+            input.lines.push(input.partial);
+        input.partial = '';
+    };
+    return new Promise((resolve) => {
+        const settle = () => {
+            // stdin may have ended while nothing listened, between two questions.
+            if (stdin.readableEnded)
+                markEnded();
+            if (!input.lines.length && !input.ended)
+                return false;
+            stdin.off('data', onData).off('end', onEnd).pause();
+            resolve(input.lines.shift() ?? null);
+            return true;
+        };
+        const onData = (chunk) => {
+            const parts = (input.partial + String(chunk)).split(/\r?\n/);
+            input.partial = parts.pop();
+            input.lines.push(...parts);
+            settle();
+        };
+        const onEnd = () => {
+            markEnded();
+            settle();
+        };
+        if (!settle())
+            stdin.on('data', onData).on('end', onEnd).resume();
+    });
+}
+/** One line typed at a terminal without echoing it. */
+async function hiddenLine() {
+    const rl = createInterface({ input: process.stdin, output: new Writable({ write: (_chunk, _encoding, done) => done() }), terminal: true });
+    try {
+        return await new Promise((resolve) => {
+            rl.once('line', resolve).once('close', () => resolve(null));
+            // In raw mode Ctrl+C reaches readline, not the process: pass it on so it still stops the command.
+            rl.once('SIGINT', () => {
+                rl.close();
+                process.kill(process.pid, 'SIGINT');
+            });
+        });
+    }
+    finally {
+        rl.close();
+        process.stdout.write('\n');
+    }
+}
+async function askOnStdin(q) {
+    const out = process.stdout;
+    if (q.kind === 'confirm') {
+        out.write(`\n${q.title ? `${q.title}\n` : ''}${q.hint ? `${q.hint}\n` : ''}${q.prompt}\n`);
+        const how = `Type y to ${(q.confirmLabel ?? 'continue').toLowerCase()}, or Enter to ${(q.skipLabel ?? 'skip').toLowerCase()}:`;
+        out.write(`${how} `);
+        for (let line = await nextLine(); line !== null; line = await nextLine()) {
+            if (/^y(es)?$/i.test(line.trim()))
+                return { skipped: false };
+            if (!line.trim())
+                return { skipped: true };
+            out.write(`That is not an answer to this one. ${how} `);
+        }
+        return { skipped: true };
+    }
+    if (q.kind === 'account') {
+        // An empty username keeps the one the field would hold; an empty password skips the account.
+        out.write(`\n${q.title ? `${q.title}. ` : ''}${q.prompt}\n${q.hint ? `${q.hint}\n` : ''}Username or email${q.prefill ? ` (Enter for ${q.prefill})` : ''}: `);
+        const username = (await nextLine())?.trim() || q.prefill;
+        if (!username)
+            return { skipped: true };
+        out.write('Password, or Enter to skip: ');
+        const password = await (process.stdin.isTTY ? hiddenLine : nextLine)();
+        return password ? { skipped: false, username, password } : { skipped: true };
+    }
+    const how = q.kind === 'text' ? (q.skippable ? '(Enter to skip)' : '') : q.kind === 'single' ? `Type a number${q.skippable ? ', or Enter to skip' : ''}:` : `Type the numbers, separated by commas${q.skippable ? ', or Enter to skip' : ''}:`;
+    out.write(`\n${q.prompt}\n${q.hint ? `${q.hint}\n` : ''}`);
+    (q.options ?? []).forEach((o, i) => out.write(`  ${i + 1}. ${o.label}\n`));
+    // A sensitive answer typed at a terminal is not echoed.
+    const read = q.sensitive && process.stdin.isTTY ? hiddenLine : nextLine;
+    out.write(how ? `${how} ` : '');
+    for (let line = await read(); line !== null; line = await read()) {
+        const answer = answerOf(q, line);
+        if (answer)
+            return answer;
+        out.write(`That is not an answer to this one. ${how} `);
+    }
+    // Nobody is there to answer.
+    return { skipped: true };
+}

package/dist/ui/frames.js

@@ -0,0 +1,62 @@
+import { chmodSync, mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { stripTerminalSequences } from '@earendil-works/pi-tui';
+import { workStarted } from '../stages.js';
+/** The state a screen shows; the blank moment between two screens keeps the state before it. */
+export function frameState(scene, question, before = 'start') {
+    switch (scene.kind) {
+        case 'wait':
+            return before;
+        case 'intro':
+            return 'start';
+        case 'signin':
+            return 'sign-in';
+        case 'pull':
+            return 'test-drive';
+        case 'outro':
+            return scene.outro.outcome === 'stopped' ? 'stop' : 'done';
+        case 'run':
+            if (question)
+                return 'question';
+            return workStarted(scene.tasks) ? 'working' : 'understanding';
+    }
+}
+/** Readable only by the person, like the debug log; a file left by an earlier run into the same folder is made so too. */
+const write = (path, text) => {
+    writeFileSync(path, text, { mode: 0o600 });
+    chmodSync(path, 0o600);
+};
+const plain = (lines) => lines.map((line) => stripTerminalSequences(line).trimEnd()).join('\n');
+/** Writes frames into `dir`; one it cannot write is skipped, since frames are not worth stopping the run for. */
+export function createFrameWriter(dir, now = () => new Date()) {
+    const index = [];
+    let seen;
+    return {
+        get last() {
+            return index.at(-1)?.state;
+        },
+        record(state, lines, { question, still } = {}) {
+            const asked = state === 'question' && question ? { question: { id: question.id, title: question.title, prompt: question.prompt, kind: question.kind, options: question.options, sensitive: question.sensitive, skippable: question.skippable } } : {};
+            // A new question is a change even when it reads like the one before.
+            const key = `${state}\n${asked.question?.id ?? ''}\n${plain(still ?? lines)}`;
+            if (key === seen)
+                return;
+            seen = key;
+            const text = plain(lines);
+            const n = index.length + 1;
+            const name = `${String(n).padStart(3, '0')}-${state}`;
+            index.push({ n, state, at: now().toISOString(), ...asked });
+            try {
+                mkdirSync(dir, { recursive: true });
+                write(join(dir, `${name}.ansi`), `${lines.join('\n')}\n`);
+                write(join(dir, `${name}.txt`), `${text}\n`);
+                // Replaced whole, so a reader never sees half of it.
+                write(join(dir, 'index.json.tmp'), JSON.stringify(index, null, 2));
+                renameSync(join(dir, 'index.json.tmp'), join(dir, 'index.json'));
+            }
+            catch {
+                // Skipped.
+            }
+        },
+    };
+}