@crouton-kit/humanloop 0.1.4 → 0.3.1

package/dist/inbox/deck-schema.js

@@ -0,0 +1,110 @@
+import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, resolve, sep } from 'node:path';
+import { z } from 'zod';
+import { checkMarkdown } from '../render/termrender.js';
+// ── zod v4 building blocks ────────────────────────────────────────────────────
+// v4 notes: .nonempty() → .min(1); error messages use {error: 'string'} per check.
+export const interactionOptionSchema = z.object({
+    id: z.string().min(1),
+    label: z.string().min(1),
+    description: z.string().optional(),
+    shortcut: z.string().optional(),
+});
+const interactionSchema = z.object({
+    id: z.string().regex(/^[A-Za-z0-9_-]+$/, { error: 'interaction id must match /^[A-Za-z0-9_-]+$/' }).min(1).max(64),
+    title: z.string().min(1, { error: 'title must be non-empty' }),
+    subtitle: z.string().min(1, { error: 'subtitle must be non-empty when present' }).optional(),
+    body: z.string().optional(),
+    bodyPath: z.string().optional(),
+    options: z.array(interactionOptionSchema),
+    multiSelect: z.boolean().optional(),
+    allowFreetext: z.boolean().optional(),
+    freetextLabel: z.string().optional(),
+    kind: z.enum(['notify', 'validation', 'decision', 'context', 'error']).optional(),
+});
+const deckSourceSchema = z.object({
+    sessionName: z.string().optional(),
+    askedBy: z.string().optional(),
+    blockedSince: z.string().optional(),
+});
+export const deckSchema = z.object({
+    title: z.string().optional(),
+    source: deckSourceSchema.optional(),
+    interactions: z.array(interactionSchema).min(1, { error: 'interactions[] must be non-empty' }),
+}).superRefine((input, ctx) => {
+    const seen = new Map();
+    for (let i = 0; i < input.interactions.length; i++) {
+        const interaction = input.interactions[i];
+        if (interaction.body !== undefined && interaction.bodyPath !== undefined) {
+            ctx.addIssue({
+                code: 'custom',
+                message: 'body and bodyPath are mutually exclusive',
+                path: ['interactions', i],
+            });
+        }
+        const prev = seen.get(interaction.id);
+        if (prev !== undefined) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `duplicate interaction id "${interaction.id}" at indices ${prev} and ${i}`,
+                path: ['interactions', i, 'id'],
+            });
+        }
+        seen.set(interaction.id, i);
+    }
+});
+// ── C2 bodyPath defense + inlining ────────────────────────────────────────────
+export function inlineBodyPath(deckPath, bodyPath) {
+    const deckDir = dirname(deckPath);
+    const joined = resolve(deckDir, bodyPath);
+    // STEP 1: existence + lstat BEFORE realpath to catch symlinks and directories.
+    if (!existsSync(joined)) {
+        throw new Error(`bodyPath does not exist: '${bodyPath}' (resolved against deck dir '${deckDir}'). bodyPath is interpreted relative to the deck JSON's directory; place the body file there and use a relative path (e.g. "completion-summary.md").`);
+    }
+    const stat = lstatSync(joined);
+    if (!stat.isFile()) {
+        // Catches symlinks, directories, FIFOs — lstat does not follow symlinks.
+        throw new Error(`bodyPath must be a regular file (not a symlink, directory, or special file): ${bodyPath}`);
+    }
+    // STEP 2: realpath both sides, prefix-check (defense-in-depth for .. traversal).
+    // realpathSync is safe here: lstat already confirmed the path exists.
+    const realResolved = realpathSync(joined);
+    const realDeckDir = realpathSync(deckDir);
+    const prefix = realDeckDir + sep;
+    if (realResolved !== realDeckDir && !realResolved.startsWith(prefix)) {
+        throw new Error(`bodyPath '${bodyPath}' escapes the deck's directory ('${realDeckDir}'). bodyPath is resolved relative to the deck JSON file and must stay inside its directory (no '..', absolute paths pointing elsewhere, or symlinks out). Fix: write the deck JSON next to the body file (e.g. both inside $SISYPHUS_SESSION_DIR/context/) and use a relative path like "completion-summary.md".`);
+    }
+    // STEP 3: read. lstat confirmed regular file; realpath confirmed in-tree.
+    return readFileSync(joined, 'utf-8');
+}
+// ── public entry points ───────────────────────────────────────────────────────
+export function parseDeck(deckPath) {
+    const raw = readFileSync(deckPath, 'utf-8');
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('deck is not valid JSON');
+    }
+    const parsed = deckSchema.parse(json);
+    const inlinedInteractions = parsed.interactions.map(interaction => {
+        let body = interaction.body;
+        if (interaction.bodyPath !== undefined) {
+            body = inlineBodyPath(deckPath, interaction.bodyPath);
+        }
+        if (body !== undefined) {
+            const check = checkMarkdown(body);
+            if (!check.ok) {
+                throw new Error(check.error);
+            }
+        }
+        // Drop bodyPath from persisted decisions.json (recipe §1.8).
+        const { bodyPath: _drop, ...rest } = interaction;
+        return body !== undefined ? { ...rest, body } : { ...rest };
+    });
+    return { ...parsed, interactions: inlinedInteractions };
+}
+export function validateDeck(parsed) {
+    return deckSchema.parse(parsed);
+}

package/dist/inbox/scan.d.ts

@@ -0,0 +1,2 @@
+import type { InboxItem } from '../types.js';
+export declare function scanInbox(roots: string[]): InboxItem[];

package/dist/inbox/scan.js

@@ -0,0 +1,62 @@
+import { readdirSync, statSync } from 'fs';
+import { resolve, basename } from 'path';
+import { deckPath, isResolved, isClaimed, readJson } from './convention.js';
+// ── scanInbox ─────────────────────────────────────────────────────────────────
+export function scanInbox(roots) {
+    const items = [];
+    for (const root of roots) {
+        let entries;
+        try {
+            entries = readdirSync(root);
+        }
+        catch {
+            // root doesn't exist or isn't readable — skip silently
+            continue;
+        }
+        for (const entry of entries) {
+            const dir = resolve(root, entry);
+            try {
+                const stat = statSync(dir);
+                if (!stat.isDirectory())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            // Skip resolved or actively claimed dirs
+            if (isResolved(dir) || isClaimed(dir))
+                continue;
+            const dp = deckPath(dir);
+            const deck = readJson(dp);
+            if (deck === null)
+                continue;
+            // Derive blockedSince: prefer deck.source.blockedSince, fall back to mtime
+            let blockedSince;
+            if (deck.source?.blockedSince !== undefined) {
+                blockedSince = deck.source.blockedSince;
+            }
+            else {
+                try {
+                    blockedSince = new Date(statSync(dp).mtime).toISOString();
+                }
+                catch {
+                    blockedSince = new Date().toISOString();
+                }
+            }
+            const firstInteraction = deck.interactions[0];
+            const item = {
+                dir,
+                id: firstInteraction?.id ?? basename(dir),
+                title: deck.title ?? firstInteraction?.title,
+                subtitle: firstInteraction?.subtitle,
+                kind: firstInteraction?.kind,
+                source: deck.source,
+                blockedSince,
+            };
+            items.push(item);
+        }
+    }
+    // Sort ascending by blockedSince (ISO string compare is monotonic)
+    items.sort((a, b) => (a.blockedSince < b.blockedSince ? -1 : a.blockedSince > b.blockedSince ? 1 : 0));
+    return items;
+}

package/dist/inbox/tui.d.ts

@@ -0,0 +1,9 @@
+import type { InboxItem } from '../types.js';
+export declare const KIND_ICON: Record<string, string>;
+export declare const KIND_COLOR: Record<string, string>;
+export declare function formatTimeAgo(iso: string): string;
+export declare function buildInboxLines(items: InboxItem[], width: number, selectedIndex: number): string[];
+export declare function pickFromInbox(items: InboxItem[], opts: {
+    cols: number;
+    rows: number;
+}): Promise<InboxItem | null>;

package/dist/inbox/tui.js

@@ -0,0 +1,158 @@
+import stringWidth from 'string-width';
+import { setupTerminal, restoreTerminal, parseKeypress, getTerminalSize, } from '../tui/terminal.js';
+import { diffFrame } from '../tui/render.js';
+// ── ANSI helpers (local to this module) ──────────────────────────────────────
+const ESC = '\x1b[';
+const RESET = `${ESC}0m`;
+const BOLD = `${ESC}1m`;
+const DIM = `${ESC}2m`;
+const ITALIC = `${ESC}3m`;
+const CYAN = `${ESC}36m`;
+const RED = `${ESC}31m`;
+const GRAY = `${ESC}90m`;
+const YELLOW = `${ESC}33m`;
+function ansiColor(text, color) {
+    switch (color) {
+        case 'gray': return `${GRAY}${text}${RESET}`;
+        case 'cyan': return `${CYAN}${text}${RESET}`;
+        case 'red': return `${RED}${text}${RESET}`;
+        case 'yellow': return `${YELLOW}${text}${RESET}`;
+        default: return text;
+    }
+}
+// ── Row model (ported verbatim from sisyphus cross-session-inbox.ts:8-21) ────
+export const KIND_ICON = {
+    notify: '✉',
+    validation: '✓',
+    decision: '◆',
+    context: '✎',
+    error: '⚠',
+};
+export const KIND_COLOR = {
+    notify: 'gray',
+    validation: 'cyan',
+    decision: 'cyan',
+    context: 'cyan',
+    error: 'red',
+};
+// ── formatTimeAgo (ported from sisyphus src/tui/lib/format.ts:5-12) ──────────
+export function formatTimeAgo(iso) {
+    const diff = Date.now() - new Date(iso).getTime();
+    const minutes = Math.floor(diff / 60000);
+    const hours = Math.floor(minutes / 60);
+    if (hours > 0)
+        return `${hours}h ago`;
+    if (minutes > 0)
+        return `${minutes}m ago`;
+    return 'just now';
+}
+// ── truncate (ported from sisyphus src/tui/lib/format.ts:19-37) ──────────────
+function truncate(text, max) {
+    const clean = text.replace(/\n/g, ' ').replace(/✅/g, '✓').replace(/❌/g, '✗').replace(/\p{Emoji_Presentation}/gu, '');
+    if (max < 4)
+        return clean.slice(0, max);
+    const w = stringWidth(clean);
+    if (w <= max)
+        return clean;
+    let result = clean;
+    while (stringWidth(result) > max - 1 && result.length > 0) {
+        const cut = result.lastIndexOf(' ', result.length - 2);
+        if (cut > max * 0.4) {
+            result = result.slice(0, cut);
+        }
+        else {
+            result = result.slice(0, result.length - 1);
+        }
+    }
+    return result + '…';
+}
+// ── buildInboxLines ───────────────────────────────────────────────────────────
+export function buildInboxLines(items, width, selectedIndex) {
+    const lines = [];
+    if (items.length === 0) {
+        lines.push(`  ${DIM}${ITALIC}No pending interactions${RESET}`);
+        return lines;
+    }
+    lines.push(`  ${BOLD}${items.length} pending${RESET}`);
+    lines.push('');
+    const contentWidth = width - 4;
+    for (let i = 0; i < items.length; i++) {
+        const item = items[i];
+        const kindKey = item.kind ?? '';
+        const icon = kindKey in KIND_ICON ? KIND_ICON[kindKey] : '·';
+        const iconColor = kindKey in KIND_COLOR ? KIND_COLOR[kindKey] : 'cyan';
+        const sourceLabel = item.source?.sessionName ?? item.source?.askedBy ?? '';
+        const titleText = item.title ?? `(${item.id.slice(0, 8)})`;
+        const blocked = formatTimeAgo(item.blockedSince);
+        const cursor = i === selectedIndex ? `${CYAN}▸${RESET} ` : '  ';
+        const maxTitle = Math.max(10, contentWidth - sourceLabel.length - blocked.length - 8);
+        let row = cursor;
+        row += ansiColor(icon, iconColor);
+        if (sourceLabel) {
+            row += ` ${ansiColor(sourceLabel, 'yellow')}`;
+            row += ` ${DIM}·${RESET} `;
+        }
+        else {
+            row += ' ';
+        }
+        row += `${BOLD}${truncate(titleText, maxTitle)}${RESET}`;
+        row += `  ${DIM}${blocked}${RESET}`;
+        lines.push(row);
+        if (item.subtitle) {
+            lines.push(`      ${DIM}${truncate(item.subtitle, contentWidth - 6)}${RESET}`);
+        }
+    }
+    return lines;
+}
+// ── pickFromInbox ─────────────────────────────────────────────────────────────
+export function pickFromInbox(items, opts) {
+    if (items.length === 0)
+        return Promise.resolve(null);
+    return new Promise((resolve) => {
+        let selectedIndex = 0;
+        let prevFrame = [];
+        let onData;
+        const flush = () => {
+            const { cols: currentCols, rows: currentRows } = getTerminalSize();
+            const lines = buildInboxLines(items, currentCols, selectedIndex);
+            const { writes, nextPrevFrame } = diffFrame(prevFrame, lines, currentRows);
+            process.stdout.write('\x1b[?2026h');
+            for (const w of writes)
+                process.stdout.write(w);
+            process.stdout.write('\x1b[?2026l');
+            prevFrame = nextPrevFrame;
+        };
+        const done = (result) => {
+            restoreTerminal();
+            process.stdin.removeListener('data', onData);
+            process.stdout.removeListener('resize', flush);
+            resolve(result);
+        };
+        setupTerminal();
+        flush();
+        onData = (data) => {
+            const { input, key } = parseKeypress(data);
+            if (key.downArrow || input === 'j') {
+                selectedIndex = Math.min(selectedIndex + 1, items.length - 1);
+                flush();
+                return;
+            }
+            if (key.upArrow || input === 'k') {
+                selectedIndex = Math.max(selectedIndex - 1, 0);
+                flush();
+                return;
+            }
+            if (key.return) {
+                const selected = items[selectedIndex];
+                done(selected ?? null);
+                return;
+            }
+            if (key.escape || (key.ctrl && input === 'c') || input === 'q') {
+                done(null);
+                return;
+            }
+        };
+        process.stdin.on('data', onData);
+        process.stdout.on('resize', flush);
+    });
+}

package/dist/index.d.ts

@@ -1,5 +1,15 @@
 export { mountPanel, validateInput, launchTui } from './tui/app.js';
 export { defaultGenerateVisual } from './visuals/generate.js';
-export type { Interaction, InteractionOption, InteractionResponse, InteractionKind, Deck, DeckSource, MountedPanel, MountedPanelOpts, GenerateVisual, VisualBlock, } from './types.js';
+export { launchReview } from './editor/review.js';
+export { launchReview as review } from './editor/review.js';
+export type { ReviewOptions } from './editor/review.js';
+export { ask, approve, notify, inbox } from './api.js';
+export { display } from './surfaces/display.js';
+export { scanInbox } from './inbox/scan.js';
+export { renderMarkdown, checkMarkdown, ensureRenderer, isRendererReady, } from './render/termrender.js';
+export { parseDeck, validateDeck, deckSchema } from './inbox/deck-schema.js';
+export { deckPath, responsePath, progressPath, visualsDir, interactionState, isResolved, isClaimed, atomicWriteJson, readJson, writeResponse, writeProgress, clearProgress, } from './inbox/convention.js';
+export type { InteractionState } from './inbox/convention.js';
+export type { Interaction, InteractionOption, InteractionResponse, InteractionKind, Deck, DeckSource, MountedPanel, MountedPanelOpts, GenerateVisual, VisualBlock, FeedbackComment, FeedbackResult, ResolutionEnvelope, InboxItem, DisplayOpts, } from './types.js';
 export type { Key } from './tui/terminal.js';
 export type { ConversationMessage } from './conversation/reader.js';

package/dist/index.js

@@ -1,2 +1,15 @@
 export { mountPanel, validateInput, launchTui } from './tui/app.js';
 export { defaultGenerateVisual } from './visuals/generate.js';
+export { launchReview } from './editor/review.js';
+export { launchReview as review } from './editor/review.js';
+// Interaction-layer surface (SDK).
+export { ask, approve, notify, inbox } from './api.js';
+export { display } from './surfaces/display.js';
+export { scanInbox } from './inbox/scan.js';
+// Renderer binding — the sole org-wide termrender caller. Consumers
+// (sisyphus md-render / ask-schema) route markdown through these.
+export { renderMarkdown, checkMarkdown, ensureRenderer, isRendererReady, } from './render/termrender.js';
+// Canonical deck schema + parsing/validation (consumers stop forking it).
+export { parseDeck, validateDeck, deckSchema } from './inbox/deck-schema.js';
+// Interaction-directory convention helpers (§B) — names humanloop owns.
+export { deckPath, responsePath, progressPath, visualsDir, interactionState, isResolved, isClaimed, atomicWriteJson, readJson, writeResponse, writeProgress, clearProgress, } from './inbox/convention.js';

package/dist/render/termrender.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 declare function ensureRenderer(): void;
+/** Cheap predicate — true when the pinned managed binary is present and correct. Does not install. */
+export declare function isRendererReady(): boolean;
+/** Render markdown to terminal lines via the pinned binary; plaintext fallback. */
+export declare function renderMarkdown(md: string, width: number): string[];
+/** Validate markdown via `termrender doc check`. */
+export declare function checkMarkdown(md: string): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+export interface DisplayInPaneOpts {
+    /** Pass watch so the pane live-updates on file edits. Default true. */
+    watch?: boolean;
+    /** Open in a new tmux window instead of splitting the current one. */
+    newWindow?: boolean;
+}
+/**
+ * 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 declare function displayInPane(path: string, opts?: DisplayInPaneOpts): {
+    paneId?: string;
+};