@crouton-kit/humanloop 0.1.2 → 0.1.4

package/dist/tui/app.js

@@ -1,201 +1,336 @@
 import { readFileSync, existsSync, writeFileSync, renameSync, unlinkSync } from 'fs';
 import { setupTerminal, restoreTerminal, parseKeypress, getTerminalSize } from './terminal.js';
-import { flush, renderOverview, renderItemReview, renderFinal } from './render.js';
-import { handleKeypress } from './input.js';
+import { diffFrame, renderOverview, renderItemReview, renderFinal } from './render.js';
+import { handleKeypress, assignShortcuts } from './input.js';
 import { readConversation } from '../conversation/reader.js';
-import { generateVisuals } from '../visuals/generate.js';
-// Validate the parsed JSON before opening the terminal so bad agent input
-// fails with a clear error instead of crashing inside the TUI.
+import { defaultGenerateVisual } from '../visuals/generate.js';
 export function validateInput(parsed) {
     if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-        throw new Error('Decisions file must be a JSON object with a `questions` array');
+        throw new Error('Deck file must be a JSON object with an `interactions` array');
     }
     const obj = parsed;
-    if (!Array.isArray(obj.questions)) {
-        throw new Error('`questions` must be an array');
+    if (!Array.isArray(obj.interactions)) {
+        throw new Error('`interactions` must be an array');
     }
-    if (obj.questions.length === 0) {
-        throw new Error('No questions in decisions file');
+    if (obj.interactions.length === 0) {
+        throw new Error('No interactions in deck file');
     }
     if (obj.title !== undefined && typeof obj.title !== 'string') {
         throw new Error('`title` must be a string when present');
     }
     const seen = new Set();
     const validated = [];
-    for (let i = 0; i < obj.questions.length; i++) {
-        const q = obj.questions[i];
-        const where = `questions[${i}]`;
-        if (typeof q !== 'object' || q === null || Array.isArray(q)) {
+    for (let i = 0; i < obj.interactions.length; i++) {
+        const raw = obj.interactions[i];
+        const where = `interactions[${i}]`;
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
             throw new Error(`${where} must be an object`);
         }
-        if (typeof q.id !== 'string' || q.id === '') {
+        if (typeof raw.id !== 'string' || raw.id === '') {
             throw new Error(`${where}.id must be a non-empty string`);
         }
-        if (seen.has(q.id)) {
-            throw new Error(`Duplicate question id: ${JSON.stringify(q.id)}`);
-        }
-        seen.add(q.id);
-        if (q.type === 'validation') {
-            if (typeof q.statement !== 'string')
-                throw new Error(`${where}.statement must be a string`);
-            if (typeof q.rationale !== 'string')
-                throw new Error(`${where}.rationale must be a string`);
-            validated.push({ id: q.id, type: 'validation', statement: q.statement, rationale: q.rationale });
-        }
-        else if (q.type === 'choice') {
-            if (typeof q.question !== 'string')
-                throw new Error(`${where}.question must be a string`);
-            if (typeof q.rationale !== 'string')
-                throw new Error(`${where}.rationale must be a string`);
-            if (!Array.isArray(q.options))
-                throw new Error(`${where}.options must be an array`);
-            if (q.options.length < 2)
-                throw new Error(`${where}.options must have at least 2 items (got ${q.options.length})`);
-            const opts = [];
-            for (let j = 0; j < q.options.length; j++) {
-                if (typeof q.options[j] !== 'string')
-                    throw new Error(`${where}.options[${j}] must be a string`);
-                opts.push(q.options[j]);
+        if (seen.has(raw.id)) {
+            throw new Error(`Duplicate interaction id: ${JSON.stringify(raw.id)}`);
+        }
+        seen.add(raw.id);
+        if (typeof raw.title !== 'string' || raw.title === '') {
+            throw new Error(`${where}.title must be a non-empty string`);
+        }
+        if (!Array.isArray(raw.options)) {
+            throw new Error(`${where}.options must be an array`);
+        }
+        const opts = [];
+        for (let j = 0; j < raw.options.length; j++) {
+            const o = raw.options[j];
+            const owhere = `${where}.options[${j}]`;
+            if (typeof o !== 'object' || o === null || Array.isArray(o)) {
+                throw new Error(`${owhere} must be an object`);
+            }
+            if (typeof o.id !== 'string' || o.id === '') {
+                throw new Error(`${owhere}.id must be a non-empty string`);
             }
-            validated.push({ id: q.id, type: 'choice', question: q.question, rationale: q.rationale, options: opts });
+            if (typeof o.label !== 'string') {
+                throw new Error(`${owhere}.label must be a string`);
+            }
+            const opt = { id: o.id, label: o.label };
+            if (o.description !== undefined) {
+                if (typeof o.description !== 'string')
+                    throw new Error(`${owhere}.description must be a string`);
+                opt.description = o.description;
+            }
+            if (o.shortcut !== undefined) {
+                if (typeof o.shortcut !== 'string')
+                    throw new Error(`${owhere}.shortcut must be a string`);
+                opt.shortcut = o.shortcut;
+            }
+            opts.push(opt);
+        }
+        const interaction = { id: raw.id, title: raw.title, options: opts };
+        if (raw.subtitle !== undefined) {
+            if (typeof raw.subtitle !== 'string')
+                throw new Error(`${where}.subtitle must be a string`);
+            interaction.subtitle = raw.subtitle;
         }
-        else if (q.type === 'freetext') {
-            if (typeof q.question !== 'string')
-                throw new Error(`${where}.question must be a string`);
-            if (typeof q.rationale !== 'string')
-                throw new Error(`${where}.rationale must be a string`);
-            validated.push({ id: q.id, type: 'freetext', question: q.question, rationale: q.rationale });
+        if (raw.body !== undefined) {
+            if (typeof raw.body !== 'string')
+                throw new Error(`${where}.body must be a string`);
+            interaction.body = raw.body;
         }
-        else {
-            throw new Error(`${where}.type must be "validation" | "choice" | "freetext" (got ${JSON.stringify(q.type)})`);
+        if (raw.bodyPath !== undefined) {
+            if (typeof raw.bodyPath !== 'string')
+                throw new Error(`${where}.bodyPath must be a string`);
+            interaction.bodyPath = raw.bodyPath;
         }
+        if (raw.freetextLabel !== undefined) {
+            if (typeof raw.freetextLabel !== 'string')
+                throw new Error(`${where}.freetextLabel must be a string`);
+            interaction.freetextLabel = raw.freetextLabel;
+        }
+        if (raw.allowFreetext !== undefined) {
+            if (typeof raw.allowFreetext !== 'boolean')
+                throw new Error(`${where}.allowFreetext must be a boolean`);
+            interaction.allowFreetext = raw.allowFreetext;
+        }
+        if (raw.kind !== undefined) {
+            interaction.kind = raw.kind;
+        }
+        validated.push(interaction);
     }
-    return { title: obj.title, questions: validated };
+    const deck = { interactions: validated };
+    if (obj.title !== undefined)
+        deck.title = obj.title;
+    return deck;
 }
-export async function launchTui(decisionsPath, sessionId) {
-    if (!existsSync(decisionsPath)) {
-        throw new Error(`Decisions file not found: ${decisionsPath}`);
-    }
-    const raw = readFileSync(decisionsPath, 'utf8');
-    const parsed = JSON.parse(raw);
-    const input = validateInput(parsed);
-    const state = {
-        phase: 'overview',
+// ── Internal helpers ──────────────────────────────────────────────────────────
+function buildInitialState(deck) {
+    // Single-question decks skip the overview list — there's nothing to overview,
+    // and overview hides the option hotkeys so users press 'y' and nothing happens.
+    const initialPhase = deck.interactions.length === 1 ? 'item-review' : 'overview';
+    return {
+        phase: initialPhase,
         currentIndex: 0,
-        questions: input.questions,
-        answers: new Map(),
+        interactions: deck.interactions,
+        responses: new Map(),
         visuals: new Map(),
         inputMode: null,
         selectedAction: 0,
         detailExpanded: false,
         scrollOffset: 0,
     };
-    const progressPath = `${decisionsPath}.progress.json`;
-    state.persist = () => {
-        const answers = [];
-        for (const q of input.questions) {
-            const a = state.answers.get(q.id);
-            if (a)
-                answers.push(a);
-        }
-        const payload = {
-            partial: true,
-            answers,
-            savedAt: new Date().toISOString(),
-        };
-        try {
-            const tmp = `${progressPath}.tmp`;
-            writeFileSync(tmp, JSON.stringify(payload, null, 2));
-            renameSync(tmp, progressPath);
-        }
-        catch {
-            // best-effort — do not crash the TUI if the directory isn't writable
+}
+function collectResponses(state) {
+    const out = [];
+    for (const interaction of state.interactions) {
+        const r = state.responses.get(interaction.id);
+        if (r !== undefined)
+            out.push(r);
+    }
+    return out;
+}
+function tryResume(state, progressPath, interactions) {
+    try {
+        const prior = JSON.parse(readFileSync(progressPath, 'utf8'));
+        if (!Array.isArray(prior.responses))
+            return;
+        const validIds = new Set(interactions.map((i) => i.id));
+        for (const r of prior.responses) {
+            if (validIds.has(r.id))
+                state.responses.set(r.id, r);
         }
+        const firstUnanswered = interactions.findIndex((i) => !state.responses.has(i.id));
+        state.currentIndex = firstUnanswered >= 0 ? firstUnanswered : 0;
+    }
+    catch {
+        // corrupt or missing progress file — start fresh
+    }
+}
+function atomicWriteProgress(progressPath, responses) {
+    const payload = JSON.stringify({ partial: true, responses, savedAt: new Date().toISOString() }, null, 2);
+    const tmp = `${progressPath}.tmp`;
+    try {
+        writeFileSync(tmp, payload);
+        renameSync(tmp, progressPath);
+    }
+    catch {
+        // best-effort
+    }
+}
+function rebindPersist(internals) {
+    internals.state.persist = () => {
+        const responses = collectResponses(internals.state);
+        if (internals.progressPath !== undefined)
+            atomicWriteProgress(internals.progressPath, responses);
+        internals.callbacks.onProgress?.(responses);
     };
-    if (existsSync(progressPath)) {
-        try {
-            const prior = JSON.parse(readFileSync(progressPath, 'utf8'));
-            const validIds = new Set(input.questions.map((q) => q.id));
-            for (const a of prior.answers ?? []) {
-                if (validIds.has(a.id))
-                    state.answers.set(a.id, a);
-            }
-            const firstUnanswered = input.questions.findIndex((q) => !state.answers.has(q.id));
-            state.currentIndex = firstUnanswered >= 0 ? firstUnanswered : 0;
-        }
-        catch {
-            // corrupt progress file — ignore and start fresh
-        }
+}
+function fireVisuals(internals, interactions) {
+    if (internals.generateVisual === undefined)
+        return;
+    const gen = internals.generateVisual;
+    for (const interaction of interactions) {
+        internals.state.visuals.set(interaction.id, { questionId: interaction.id, content: '', status: 'loading' });
+        gen(interaction).then((r) => {
+            if (!internals.mounted)
+                return;
+            if (!internals.state.interactions.some((x) => x.id === interaction.id))
+                return;
+            internals.state.visuals.set(interaction.id, r.ok
+                ? { questionId: interaction.id, content: r.ansi, status: 'ready' }
+                : { questionId: interaction.id, content: '', status: 'error' });
+        }).catch(() => {
+            if (!internals.mounted)
+                return;
+            if (!internals.state.interactions.some((x) => x.id === interaction.id))
+                return;
+            internals.state.visuals.set(interaction.id, { questionId: interaction.id, content: '', status: 'error' });
+        });
     }
-    // Initialize visuals — 'loading' if we'll generate them, skip otherwise
-    if (sessionId) {
-        for (const q of input.questions) {
-            state.visuals.set(q.id, { questionId: q.id, content: '', status: 'loading' });
-        }
+}
+export function mountPanel(opts) {
+    const internals = {
+        state: buildInitialState(opts.deck),
+        cols: opts.cols,
+        rows: opts.rows,
+        mounted: true,
+        generateVisual: opts.generateVisual,
+        progressPath: opts.progressPath,
+        callbacks: { onProgress: opts.onProgress, onComplete: opts.onComplete, onExit: opts.onExit },
+    };
+    assignShortcuts(internals.state.interactions);
+    rebindPersist(internals);
+    if (internals.progressPath !== undefined) {
+        tryResume(internals.state, internals.progressPath, opts.deck.interactions);
     }
-    setupTerminal();
-    const render = () => {
-        let lines;
-        switch (state.phase) {
-            case 'overview':
-                lines = renderOverview(state);
-                break;
-            case 'item-review':
-                lines = renderItemReview(state);
-                break;
-            case 'final':
-                lines = renderFinal(state);
-                break;
-        }
-        flush(lines);
+    fireVisuals(internals, opts.deck.interactions);
+    const renderLines = () => {
+        switch (internals.state.phase) {
+            case 'overview': return renderOverview(internals.state, internals.cols, internals.rows);
+            case 'item-review': return renderItemReview(internals.state, internals.cols, internals.rows);
+            case 'final': return renderFinal(internals.state, internals.cols, internals.rows);
+        }
     };
-    // Initial render
-    render();
-    // Fan out haiku visual generation in background
-    if (sessionId) {
-        try {
-            const conversation = readConversation(sessionId);
-            if (conversation.length > 0) {
-                const { cols } = getTerminalSize();
-                const visualWidth = Math.max(40, Math.min(cols - 4, 76));
-                generateVisuals(input.questions, conversation, (qId, block) => {
-                    state.visuals.set(qId, block);
-                    render();
-                }, visualWidth).catch((err) => {
-                    process.stderr.write(`Visual generation failed: ${err}\n`);
-                });
+    return {
+        handleKey(input, key) {
+            if (!internals.mounted)
+                return;
+            const onAutoComplete = () => {
+                const responses = collectResponses(internals.state);
+                if (internals.progressPath !== undefined) {
+                    try {
+                        unlinkSync(internals.progressPath);
+                    }
+                    catch { /* ignore */ }
+                }
+                internals.callbacks.onComplete?.(responses);
+            };
+            handleKeypress(input, key, internals.state, () => { }, () => {
+                const responses = collectResponses(internals.state);
+                if (responses.length >= internals.state.interactions.length) {
+                    onAutoComplete();
+                }
+                else {
+                    internals.callbacks.onExit?.();
+                }
+            });
+        },
+        render() {
+            if (!internals.mounted)
+                return [];
+            return renderLines();
+        },
+        handleResize(cols, rows) {
+            internals.cols = cols;
+            internals.rows = rows;
+            return renderLines();
+        },
+        unmount() {
+            internals.mounted = false;
+            internals.state.visuals.clear();
+            internals.state.persist = undefined;
+        },
+        loadDeck(deck, loadOpts) {
+            if (!internals.mounted)
+                return;
+            internals.state = buildInitialState(deck);
+            if (loadOpts !== undefined && loadOpts.progressPath !== undefined) {
+                internals.progressPath = loadOpts.progressPath;
             }
-        }
-        catch (err) {
-            for (const q of input.questions) {
-                state.visuals.set(q.id, { questionId: q.id, content: '', status: 'error' });
+            assignShortcuts(internals.state.interactions);
+            rebindPersist(internals);
+            if (internals.progressPath !== undefined) {
+                tryResume(internals.state, internals.progressPath, deck.interactions);
             }
+            fireVisuals(internals, deck.interactions);
+        },
+        canAcceptHostKeys() {
+            if (!internals.mounted)
+                return false;
+            return internals.state.inputMode === null;
+        },
+    };
+}
+// ── launchTui shim ────────────────────────────────────────────────────────────
+export async function launchTui(decisionsPath, sessionId) {
+    if (!existsSync(decisionsPath)) {
+        throw new Error(`Decisions file not found: ${decisionsPath}`);
+    }
+    const raw = readFileSync(decisionsPath, 'utf8');
+    const deck = validateInput(JSON.parse(raw));
+    let conversationContext = '';
+    if (sessionId !== undefined) {
+        try {
+            const conv = readConversation(sessionId);
+            conversationContext = conv.map((m) => `${m.role}: ${m.content}`).join('\n\n');
+        }
+        catch {
+            // empty context — proceed without visuals context
         }
     }
+    setupTerminal();
+    const { cols, rows } = getTerminalSize();
     return new Promise((resolve) => {
-        const exit = () => {
+        let panel = null;
+        let prevFrameLocal = [];
+        let lastResponses = [];
+        let onData;
+        const flushHost = (lines) => {
+            const { rows: currentRows } = getTerminalSize();
+            const { writes, nextPrevFrame } = diffFrame(prevFrameLocal, lines, currentRows);
+            process.stdout.write('\x1b[?2026h');
+            for (const w of writes)
+                process.stdout.write(w);
+            process.stdout.write('\x1b[?2026l');
+            prevFrameLocal = nextPrevFrame;
+        };
+        const onComplete = (responses) => {
             restoreTerminal();
             process.stdin.removeListener('data', onData);
-            const answers = [];
-            for (const q of input.questions) {
-                const a = state.answers.get(q.id);
-                if (a)
-                    answers.push(a);
-            }
-            if (answers.length >= input.questions.length) {
-                try {
-                    unlinkSync(progressPath);
-                }
-                catch { /* ignore */ }
-            }
-            resolve({
-                answers,
-                completedAt: new Date().toISOString(),
-            });
+            panel?.unmount();
+            resolve({ responses, completedAt: new Date().toISOString() });
         };
-        const onData = (data) => {
+        panel = mountPanel({
+            deck,
+            progressPath: `${decisionsPath}.progress.json`,
+            cols,
+            rows,
+            generateVisual: sessionId !== undefined
+                ? (interaction) => defaultGenerateVisual(interaction, conversationContext)
+                : undefined,
+            onProgress: (responses) => {
+                lastResponses = responses;
+                if (panel !== null)
+                    flushHost(panel.render());
+            },
+            onComplete,
+            onExit: () => {
+                onComplete(lastResponses);
+            },
+        });
+        flushHost(panel.render());
+        onData = (data) => {
             const { input: inp, key } = parseKeypress(data);
-            handleKeypress(inp, key, state, render, exit);
+            panel.handleKey(inp, key);
+            flushHost(panel.render());
         };
         process.stdin.on('data', onData);
     });

package/dist/tui/input.d.ts

@@ -1,5 +1,6 @@
-import type { TuiState } from '../types.js';
+import type { TuiState, Interaction } from '../types.js';
 import type { Key } from './terminal.js';
 export type RenderFn = () => void;
 export type ExitFn = () => void;
+export declare function assignShortcuts(interactions: Interaction[]): void;
 export declare function handleKeypress(input: string, key: Key, state: TuiState, render: RenderFn, exit: ExitFn): void;