@crouton-kit/humanloop 0.1.4 → 0.3.1

package/dist/render/termrender.js

@@ -0,0 +1,271 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+import stringWidth from 'string-width';
+import { TERMRENDER_VERSION } from './version.js';
+// ── The sole org-wide termrender binding ─────────────────────────────────────
+//
+// termrender is a humanloop-managed dependency: a pure-Python tool pinned to
+// TERMRENDER_VERSION, installed into a venv humanloop owns. The binary is
+// resolved by ABSOLUTE PATH inside that venv — never `$PATH` — so a user's
+// own `pip install termrender` can never shadow or break the pin.
+function findPkgRoot() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 12; i++) {
+        if (existsSync(join(dir, 'package.json')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // dist/render/termrender.js or src/render/termrender.ts → two up is pkgRoot.
+    return resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+}
+const PKG_ROOT = findPkgRoot();
+const VENV_DIR = resolve(PKG_ROOT, '.venv');
+const VENV_BIN = resolve(PKG_ROOT, '.venv/bin/termrender');
+const VENV_PYTHON = resolve(PKG_ROOT, '.venv/bin/python');
+let rendererState = 'unchecked';
+function binaryOk() {
+    if (!existsSync(VENV_BIN))
+        return false;
+    try {
+        // v2 contract: no --version flag; use -h (exit 0) as a liveness check.
+        execFileSync(VENV_BIN, ['-h'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: 5000,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function uvAvailable() {
+    try {
+        execFileSync('uv', ['--version'], { stdio: 'pipe', timeout: 5000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Memoized, self-healing. Ensures the pinned termrender binary exists inside
+ * the humanloop-managed venv; (re)provisions it via `uv` when missing or the
+ * version drifts from the pin. Runs at most once per process. Single
+ * degradation path: `uv` absent → one stderr remediation line + plaintext
+ * fallback. win32 → plaintext (no renderer).
+ *
+ * Invoked at postinstall AND lazily on the first render/check/display call,
+ * so `npm ci --ignore-scripts` consumers still self-heal on first use.
+ */
+export function ensureRenderer() {
+    if (rendererState !== 'unchecked')
+        return;
+    if (process.platform === 'win32') {
+        rendererState = 'unavailable';
+        return;
+    }
+    if (binaryOk()) {
+        rendererState = 'ready';
+        return;
+    }
+    if (!uvAvailable()) {
+        process.stderr.write('[hl] termrender unavailable — install uv to enable rich rendering:\n' +
+            '  curl -LsSf https://astral.sh/uv/install.sh | sh\n');
+        rendererState = 'unavailable';
+        return;
+    }
+    try {
+        execFileSync('uv', ['venv', VENV_DIR], { stdio: 'pipe', timeout: 60000 });
+        execFileSync('uv', ['pip', 'install', '--python', VENV_PYTHON, `termrender==${TERMRENDER_VERSION}`], { stdio: 'pipe', timeout: 120000 });
+    }
+    catch (err) {
+        process.stderr.write(`[hl] termrender install failed (${err instanceof Error ? err.message : String(err)}); using plaintext fallback\n`);
+        rendererState = 'unavailable';
+        return;
+    }
+    rendererState = binaryOk() ? 'ready' : 'unavailable';
+    if (rendererState === 'unavailable') {
+        process.stderr.write('[hl] termrender install completed but health check failed; using plaintext fallback\n');
+    }
+}
+/** Cheap predicate — true when the pinned managed binary is present and correct. Does not install. */
+export function isRendererReady() {
+    if (rendererState === 'ready')
+        return true;
+    if (rendererState === 'unavailable')
+        return false;
+    return process.platform !== 'win32' && binaryOk();
+}
+// ── Plaintext fallback helpers (kept here so this is the only termrender site) ─
+const CONTROL_CHARS_RE = /\x1b\[[0-9;?]*[a-zA-Z]|\x1b[@-_]|[\x00-\x08\x0B\x0E-\x1F\x7F-\x9F]/g;
+function sanitize(text) {
+    if (typeof text !== 'string')
+        return '';
+    return text.replace(CONTROL_CHARS_RE, '');
+}
+function sliceByWidth(s, maxWidth) {
+    let w = 0;
+    let out = '';
+    for (const ch of s) {
+        const cw = stringWidth(ch);
+        if (w + cw > maxWidth)
+            break;
+        out += ch;
+        w += cw;
+    }
+    if (out === '' && s.length > 0)
+        out = [...s][0];
+    return out;
+}
+function wrap(text, maxWidth) {
+    if (maxWidth < 1)
+        return [text];
+    const out = [];
+    const paragraphs = text.split('\n');
+    for (let p = 0; p < paragraphs.length; p++) {
+        const para = paragraphs[p];
+        if (para === '') {
+            out.push('');
+            continue;
+        }
+        const words = para.split(/[ \t]+/).filter(Boolean);
+        let current = '';
+        for (let word of words) {
+            while (stringWidth(word) > maxWidth) {
+                if (current) {
+                    out.push(current);
+                    current = '';
+                }
+                const piece = sliceByWidth(word, maxWidth);
+                out.push(piece);
+                word = word.slice(piece.length);
+            }
+            const candidate = current ? `${current} ${word}` : word;
+            if (stringWidth(candidate) <= maxWidth) {
+                current = candidate;
+            }
+            else {
+                if (current)
+                    out.push(current);
+                current = word;
+            }
+        }
+        if (current)
+            out.push(current);
+    }
+    return out.length > 0 ? out : [''];
+}
+// ── Render surface ───────────────────────────────────────────────────────────
+const _bodyCache = new Map();
+/** Render markdown to terminal lines via the pinned binary; plaintext fallback. */
+export function renderMarkdown(md, width) {
+    const key = `${md}\0${width}`;
+    const cached = _bodyCache.get(key);
+    if (cached)
+        return cached;
+    ensureRenderer();
+    if (rendererState === 'ready') {
+        try {
+            const input = JSON.stringify({ source: md, width, color: true });
+            const out = execFileSync(VENV_BIN, ['doc', 'render'], {
+                input,
+                encoding: 'utf-8',
+                timeout: 5000,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            const lines = out.split('\n');
+            if (lines.length > 0 && lines[lines.length - 1] === '')
+                lines.pop();
+            _bodyCache.set(key, lines);
+            return lines;
+        }
+        catch {
+            /* fall through to plaintext */
+        }
+    }
+    const fallback = wrap(sanitize(md), width);
+    _bodyCache.set(key, fallback);
+    return fallback;
+}
+/** Validate markdown via `termrender doc check`. */
+export function checkMarkdown(md) {
+    ensureRenderer();
+    // Renderer unavailable → don't block validation; the body just renders as
+    // plaintext later. Bricking deck validation here would be the wrong default.
+    if (rendererState !== 'ready')
+        return { ok: true };
+    const input = JSON.stringify({ source: md });
+    const result = spawnSync(VENV_BIN, ['doc', 'check'], {
+        input,
+        encoding: 'utf-8',
+        timeout: 5000,
+    });
+    if (result.error) {
+        return { ok: false, error: `termrender: invocation failed: ${result.error.message}` };
+    }
+    let parsed = null;
+    const rawStdout = typeof result.stdout === 'string' ? result.stdout : '';
+    if (rawStdout) {
+        try {
+            parsed = JSON.parse(rawStdout.trim());
+        }
+        catch {
+            // stdout not parseable — fall through to exit-code handling
+        }
+    }
+    if (parsed !== null) {
+        if (parsed.ok)
+            return { ok: true };
+        const first = Array.isArray(parsed.errors) ? parsed.errors[0] : undefined;
+        const msg = (first && typeof first.message === 'string' && first.message) ? first.message : 'invalid markdown';
+        return { ok: false, error: `termrender: ${msg}` };
+    }
+    // exit code 2 = invalid per contract; any non-zero is an error
+    if (result.status !== 0) {
+        return { ok: false, error: `termrender: doc check exited ${result.status}` };
+    }
+    return { ok: true };
+}
+/**
+ * Spawn termrender into a live tmux pane. The pane-budget policy (whether to
+ * split vs open a new window) is decided by the caller (`src/surfaces/
+ * display.ts`); this is the thin managed-binary spawn it delegates to.
+ */
+export function displayInPane(path, opts = {}) {
+    ensureRenderer();
+    if (rendererState !== 'ready')
+        return {};
+    const input = JSON.stringify({
+        path,
+        watch: opts.watch !== false,
+        window: opts.newWindow ? 'new' : 'split',
+    });
+    const result = spawnSync(VENV_BIN, ['pane', 'open'], {
+        input,
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    if (result.error || result.status !== 0)
+        return {};
+    // `encoding: 'utf-8'` makes spawnSync return stdout as a string.
+    const rawStdout = result.stdout;
+    if (!rawStdout)
+        return {};
+    let parsed = null;
+    try {
+        parsed = JSON.parse(rawStdout.trim());
+    }
+    catch {
+        return {};
+    }
+    if (parsed && typeof parsed.pane_id === 'string' && parsed.pane_id) {
+        return { paneId: parsed.pane_id };
+    }
+    return {};
+}

package/dist/render/version.d.ts

@@ -0,0 +1 @@
+export declare const TERMRENDER_VERSION = "2.1.0";

package/dist/render/version.js

@@ -0,0 +1 @@
+export const TERMRENDER_VERSION = '2.1.0';

package/dist/scripts/install-renderer.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/scripts/install-renderer.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { ensureRenderer, isRendererReady } from '../render/termrender.js';
+// postinstall hook. Best-effort: provision the pinned termrender venv now so
+// the first render is fast. NEVER fail — a renderer hiccup must not brick a
+// consumer's `npm install`. The lazy ensureRenderer() on first render covers
+// the `npm ci --ignore-scripts` case.
+try {
+    ensureRenderer();
+    if (!isRendererReady()) {
+        process.stderr.write('[hl] termrender not provisioned at install time; will retry lazily on first render.\n');
+    }
+}
+catch (err) {
+    process.stderr.write(`[hl] termrender postinstall skipped: ${err instanceof Error ? err.message : String(err)}\n`);
+}
+process.exit(0);

package/dist/surfaces/display.d.ts

@@ -0,0 +1,5 @@
+import type { DisplayOpts } from '../types.js';
+export declare function countPanesInCurrentWindow(): number;
+export declare function display(path: string, opts?: DisplayOpts): {
+    paneId?: string;
+};

package/dist/surfaces/display.js

@@ -0,0 +1,19 @@
+import { spawnSync } from 'node:child_process';
+import { displayInPane } from '../render/termrender.js';
+export function countPanesInCurrentWindow() {
+    // -t '' targets the current window of the current session.
+    const result = spawnSync('tmux', ['list-panes', '-F', '#{pane_id}'], {
+        encoding: 'utf8',
+    });
+    if (result.status !== 0)
+        return 0;
+    return result.stdout.split('\n').filter((line) => line.trim() !== '').length;
+}
+export function display(path, opts) {
+    const watch = opts?.watch !== false;
+    const window = (opts?.window === 'split' || opts?.window === 'new') ? opts.window : 'auto';
+    const maxPanes = (opts?.maxPanes !== undefined && opts.maxPanes > 0) ? opts.maxPanes : 3;
+    const newWindow = window === 'new' ||
+        (window === 'auto' && countPanesInCurrentWindow() >= maxPanes);
+    return displayInPane(path, { watch, newWindow });
+}

package/dist/tui/app.d.ts

@@ -1,6 +1,29 @@
-import type { Deck, InteractionResponse, MountedPanel, MountedPanelOpts } from '../types.js';
+import type { Deck, InteractionResponse, MountedPanel, MountedPanelOpts, GenerateVisual } from '../types.js';
+/** Validate an arbitrary parsed value as a Deck. Delegates to the canonical
+ * Zod validator in `inbox/deck-schema.ts` (the single source of truth shared
+ * with sisyphus). Kept exported for back-compat. */
 export declare function validateInput(parsed: unknown): Deck;
 export declare function mountPanel(opts: MountedPanelOpts): MountedPanel;
+export interface ResolveDirOpts {
+    /** Claude session id → per-interaction visual context from history. */
+    sessionId?: string;
+    /** Explicit visual generator; overrides the sessionId default. */
+    generateVisual?: GenerateVisual;
+    cols?: number;
+    rows?: number;
+}
+/**
+ * Resolve an interaction directory in place: mount the panel TUI keyed off
+ * `<dir>/progress.json`, and on finish (full completion OR human-finished
+ * with skips) write `<dir>/response.json` atomically and drop the progress
+ * file. A hard process kill leaves `progress.json` for a later resume —
+ * `tryResume` (unchanged logic) reads the new dir-derived path.
+ */
+export declare function resolveInteractionDir(dir: string, deck: Deck, opts?: ResolveDirOpts): Promise<{
+    responses: InteractionResponse[];
+    completedAt: string;
+    responsePath: string;
+}>;
 export declare function launchTui(decisionsPath: string, sessionId?: string): Promise<{
     responses: InteractionResponse[];
     completedAt: string;

package/dist/tui/app.js

@@ -1,105 +1,17 @@
 import { readFileSync, existsSync, writeFileSync, renameSync, unlinkSync } from 'fs';
+import { dirname, resolve as resolvePath } from 'node:path';
 import { setupTerminal, restoreTerminal, parseKeypress, getTerminalSize } from './terminal.js';
 import { diffFrame, renderOverview, renderItemReview, renderFinal } from './render.js';
 import { handleKeypress, assignShortcuts } from './input.js';
 import { readConversation } from '../conversation/reader.js';
 import { defaultGenerateVisual } from '../visuals/generate.js';
+import { validateDeck } from '../inbox/deck-schema.js';
+import { progressPath as progressPathFor, writeResponse, clearProgress } from '../inbox/convention.js';
+/** Validate an arbitrary parsed value as a Deck. Delegates to the canonical
+ * Zod validator in `inbox/deck-schema.ts` (the single source of truth shared
+ * with sisyphus). Kept exported for back-compat. */
 export function validateInput(parsed) {
-    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-        throw new Error('Deck file must be a JSON object with an `interactions` array');
-    }
-    const obj = parsed;
-    if (!Array.isArray(obj.interactions)) {
-        throw new Error('`interactions` must be an array');
-    }
-    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.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 raw.id !== 'string' || raw.id === '') {
-            throw new Error(`${where}.id must be a non-empty string`);
-        }
-        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`);
-            }
-            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;
-        }
-        if (raw.body !== undefined) {
-            if (typeof raw.body !== 'string')
-                throw new Error(`${where}.body must be a string`);
-            interaction.body = raw.body;
-        }
-        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);
-    }
-    const deck = { interactions: validated };
-    if (obj.title !== undefined)
-        deck.title = obj.title;
-    return deck;
+    return validateDeck(parsed);
 }
 // ── Internal helpers ──────────────────────────────────────────────────────────
 function buildInitialState(deck) {
@@ -269,17 +181,18 @@ export function mountPanel(opts) {
         },
     };
 }
-// ── 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));
+/**
+ * Resolve an interaction directory in place: mount the panel TUI keyed off
+ * `<dir>/progress.json`, and on finish (full completion OR human-finished
+ * with skips) write `<dir>/response.json` atomically and drop the progress
+ * file. A hard process kill leaves `progress.json` for a later resume —
+ * `tryResume` (unchanged logic) reads the new dir-derived path.
+ */
+export async function resolveInteractionDir(dir, deck, opts = {}) {
     let conversationContext = '';
-    if (sessionId !== undefined) {
+    if (opts.sessionId !== undefined) {
         try {
-            const conv = readConversation(sessionId);
+            const conv = readConversation(opts.sessionId);
             conversationContext = conv.map((m) => `${m.role}: ${m.content}`).join('\n\n');
         }
         catch {
@@ -287,7 +200,13 @@ export async function launchTui(decisionsPath, sessionId) {
         }
     }
     setupTerminal();
-    const { cols, rows } = getTerminalSize();
+    const term = getTerminalSize();
+    const cols = opts.cols ?? term.cols;
+    const rows = opts.rows ?? term.rows;
+    const generateVisual = opts.generateVisual ??
+        (opts.sessionId !== undefined
+            ? (interaction) => defaultGenerateVisual(interaction, conversationContext)
+            : undefined);
     return new Promise((resolve) => {
         let panel = null;
         let prevFrameLocal = [];
@@ -302,28 +221,30 @@ export async function launchTui(decisionsPath, sessionId) {
             process.stdout.write('\x1b[?2026l');
             prevFrameLocal = nextPrevFrame;
         };
-        const onComplete = (responses) => {
+        const finalize = (responses) => {
             restoreTerminal();
             process.stdin.removeListener('data', onData);
             panel?.unmount();
-            resolve({ responses, completedAt: new Date().toISOString() });
+            const completedAt = new Date().toISOString();
+            // Resolved supersedes in-progress: write response.json, drop progress.json.
+            const rp = writeResponse(dir, responses, completedAt);
+            clearProgress(dir);
+            resolve({ responses, completedAt, responsePath: rp });
         };
         panel = mountPanel({
             deck,
-            progressPath: `${decisionsPath}.progress.json`,
+            progressPath: progressPathFor(dir),
             cols,
             rows,
-            generateVisual: sessionId !== undefined
-                ? (interaction) => defaultGenerateVisual(interaction, conversationContext)
-                : undefined,
+            generateVisual,
             onProgress: (responses) => {
                 lastResponses = responses;
                 if (panel !== null)
                     flushHost(panel.render());
             },
-            onComplete,
+            onComplete: finalize,
             onExit: () => {
-                onComplete(lastResponses);
+                finalize(lastResponses);
             },
         });
         flushHost(panel.render());
@@ -335,3 +256,17 @@ export async function launchTui(decisionsPath, sessionId) {
         process.stdin.on('data', onData);
     });
 }
+// ── launchTui — file-path entry over the dir resolver (a kept public export
+//    per the interaction-layer plan; consumed until consumers move to ask()) ──
+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));
+    // The interaction dir is the deck file's directory; progress/response live
+    // there per the convention.
+    const dir = dirname(resolvePath(decisionsPath));
+    const { responses, completedAt } = await resolveInteractionDir(dir, deck, { sessionId });
+    return { responses, completedAt };
+}