@crouton-kit/humanloop 0.3.37 → 0.3.39

package/dist/browser/server.d.ts

@@ -9,12 +9,18 @@ export interface WebServerOpts {
      * exactly once per server instance, only for the first accepted submit
      * (later submits get a 409 and never re-fire this). `responsePath`/
      * `completedAt` are already persisted to disk — the caller converges the
-     * host surface, it must NOT write the result again. Fired only after the
-     * submit's own HTTP 200 has finished flushing to its socket, so it is
-     * safe for this callback to `stop()` the server (which force-closes all
-     * open sockets) without racing the ack the browser is waiting on.
+     * host surface, it must NOT write the result again. For a connected caller,
+     * fires only after its HTTP 200 finishes, so this callback can `stop()` the
+     * server without racing that ack. If the client disconnects after accepted
+     * persistence, it fires without waiting for an impossible finish.
      */
-    onSubmit?: (responses: InteractionResponse[], completedAt: string, responsePath: string) => void;
+    onSubmit?: (responses: InteractionResponse[], completedAt: string, responsePath: string) => void | Promise<void>;
+    /** Controller-owned finalization for a claimed inbox ticket. When supplied,
+     * this server never writes response.json itself. */
+    finalize?: (responses: InteractionResponse[]) => Promise<{
+        completedAt: string;
+        responsePath: string;
+    }>;
 }
 export interface ReviewWebServerOpts {
     /** Shared review job dir — carries review.vim and progress.json. */
@@ -47,6 +53,10 @@ export interface WebServerHandle {
      *  acks (closed, network hiccup) can't hang take-back forever. Safe to call
      *  with zero open sockets (e.g. the browser was never opened). */
     requestTakeBack(): Promise<void>;
+    /** The accepted submit currently completing its HTTP ack and owner convergence,
+     * if one has crossed the server boundary. `true` means the normal submit
+     * finish path completed; `false` means finalization was rejected. */
+    pendingSubmitLifecycle?(): Promise<boolean> | undefined;
     /** Stop listening, close all sockets (WS and HTTP), and tear down. */
     stop(): Promise<void>;
 }

package/dist/browser/server.js

@@ -4,7 +4,7 @@ import { existsSync } from 'node:fs';
 import { join, extname, dirname, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { WebSocketServer } from 'ws';
-import { deckPath, readJson, writeResponse, clearProgress } from '../inbox/convention.js';
+import { deckPath, progressPath, readJson, writeResponse, clearProgress } from '../inbox/convention.js';
 import { buildDraftFeedbackResult, buildFinalFeedbackResult, parseFeedbackComments, readReviewDraft, serializeFeedbackResult, writeReviewDraft, writeSubmitFlag, } from '../editor/feedback.js';
 // See $CRTR_CONTEXT_DIR/phase1-server-contract.md for the deck HTTP/WS API this
 // module implements — this file is the reference implementation for the deck
@@ -118,6 +118,12 @@ async function startDeckServer(opts) {
     let deck = opts.deck;
     const dir = opts.dir;
     let submitted = null;
+    let submitting = false;
+    // Created synchronously when an accepted request enters its finalizer, then
+    // kept pending through response flush and async owner convergence. A
+    // take-back can therefore serialize with the complete submit lifecycle,
+    // rather than racing only its persistence portion.
+    let pendingSubmitLifecycle;
     const scaffold = createServerScaffold();
     scaffold.setHandler(async (req, res) => {
         const url = req.url ?? '/';
@@ -132,7 +138,9 @@ async function startDeckServer(opts) {
             const onDisk = readJson(deckPath(dir));
             if (onDisk !== null)
                 deck = onDisk;
-            sendJson(res, 200, { dir, deck });
+            const progress = readJson(progressPath(dir));
+            const responses = Array.isArray(progress?.responses) ? progress.responses : [];
+            sendJson(res, 200, { dir, deck, responses });
             return;
         }
         if (url === '/api/submit' && req.method === 'POST') {
@@ -156,22 +164,107 @@ async function startDeckServer(opts) {
                 sendJson(res, 409, { ok: false, error: 'already_submitted', ...submitted });
                 return;
             }
+            if (submitting) {
+                sendJson(res, 409, { ok: false, error: 'submit_in_progress' });
+                return;
+            }
+            submitting = true;
             const responses = parsed.responses;
-            const completedAt = new Date().toISOString();
-            // Canonical write — the exact helper the terminal path uses, so nothing
-            // downstream of response.json can tell which surface produced it.
-            const responsePath = writeResponse(dir, responses, completedAt, deck);
+            let resolveSubmitLifecycle;
+            let submitLifecycleSettled = false;
+            const settleSubmitLifecycle = (didSubmit) => {
+                if (submitLifecycleSettled)
+                    return;
+                submitLifecycleSettled = true;
+                resolveSubmitLifecycle(didSubmit);
+            };
+            pendingSubmitLifecycle = new Promise((resolve) => { resolveSubmitLifecycle = resolve; });
+            let completedAt;
+            let responsePath;
+            // Convergence (owner onSubmit) must run exactly once for a persisted
+            // success, regardless of whether the client is still connected. The
+            // `finish` gate below only exists to preserve ack-ordering for a live
+            // caller; once the client is gone there is no ordering to protect.
+            let convergenceStarted = false;
+            const runConvergence = () => {
+                if (convergenceStarted)
+                    return;
+                convergenceStarted = true;
+                void Promise.resolve(opts.onSubmit?.(responses, completedAt, responsePath)).then(() => settleSubmitLifecycle(true), () => settleSubmitLifecycle(false));
+            };
+            // Observe client disconnect BEFORE awaiting the finalizer. If the
+            // client leaves while finalization is still pending we must NOT declare
+            // the accepted submit lost — the finalizer may still persist, in which
+            // case convergence must run. Defer judgment until the finalizer settles.
+            let finalizePending = true;
+            let successReady = false;
+            let responseFinished = false;
+            let clientGone = false;
+            const onResponseFinished = () => {
+                responseFinished = true;
+                if (successReady && submitted !== null)
+                    runConvergence();
+            };
+            const onClientGone = () => {
+                // `writableFinished` only means end() was called; a peer can vanish
+                // before the `finish` event. Only finish proves the live caller got
+                // through the response boundary.
+                if (responseFinished)
+                    return;
+                if (finalizePending || !successReady) {
+                    clientGone = true; // decide once finalization and convergence broadcast settle
+                    return;
+                }
+                if (submitted !== null) {
+                    // Accepted submit persisted but the client left before its body
+                    // flushed — converge once; no live caller remains to protect.
+                    runConvergence();
+                }
+                else {
+                    // The finalizer rejected: the submit was genuinely lost.
+                    settleSubmitLifecycle(false);
+                }
+            };
+            req.once('aborted', onClientGone);
+            res.once('finish', onResponseFinished);
+            res.once('close', onClientGone);
+            res.once('error', onClientGone);
+            try {
+                if (opts.finalize !== undefined) {
+                    ({ completedAt, responsePath } = await opts.finalize(responses));
+                }
+                else {
+                    // Standalone browser handoff retains its direct local persistence.
+                    completedAt = new Date().toISOString();
+                    responsePath = writeResponse(dir, responses, completedAt, deck);
+                    clearProgress(dir);
+                }
+            }
+            catch (error) {
+                finalizePending = false;
+                submitting = false;
+                settleSubmitLifecycle(false);
+                sendJson(res, 400, { error: 'invalid_submit', message: error instanceof Error ? error.message : String(error) });
+                return;
+            }
+            finalizePending = false;
             submitted = { responsePath, completedAt };
-            clearProgress(dir);
-            // Await the flush BEFORE registering the finish callback that can
-            // trigger caller-side stop() — that ordering is what closes the race
-            // between a lost WS frame and the teardown it precedes.
+            // Broadcast convergence before permitting owner cleanup, so connected
+            // observers receive this state transition before the server can close.
             await scaffold.broadcast({ type: 'converged' });
+            successReady = true;
+            if (clientGone) {
+                // The client disconnected during finalization; converge now rather
+                // than waiting for a `finish` that will never fire. The 200 is
+                // best-effort — the socket may already be closed.
+                runConvergence();
+                sendJson(res, 200, { ok: true, responsePath, completedAt });
+                return;
+            }
             // Ack-ordering guarantee: the HTTP caller must always receive its 200
-            // body before any lifecycle teardown can close its socket.
-            res.once('finish', () => {
-                opts.onSubmit?.(responses, completedAt, responsePath);
-            });
+            // body before any lifecycle teardown can close its socket. The finish
+            // observer registered above converges then; `onClientGone` converges if
+            // the peer disappears before finish.
             sendJson(res, 200, { ok: true, responsePath, completedAt });
             return;
         }
@@ -192,6 +285,9 @@ async function startDeckServer(opts) {
         async requestTakeBack() {
             await scaffold.broadcast({ type: 'taken-back' });
         },
+        pendingSubmitLifecycle() {
+            return pendingSubmitLifecycle;
+        },
         stop() {
             return scaffold.stop();
         },

package/dist/conversation/reader.d.ts

@@ -2,5 +2,19 @@ export interface ConversationMessage {
     role: 'user' | 'assistant';
     content: string;
 }
-export declare function readConversation(sessionId: string): ConversationMessage[];
+export type ConversationReadErrorCode = 'session_not_found' | 'session_ambiguous' | 'session_unreadable' | 'session_id_mismatch' | 'conversation_empty';
+export declare class ConversationReadError extends Error {
+    readonly code: ConversationReadErrorCode;
+    constructor(code: ConversationReadErrorCode);
+}
+export interface ConversationReaderOptions {
+    /** Claude SQLite path override for a real-store fixture; production uses Claude's standard store. */
+    claudeDbPath?: string;
+}
+/** Read messages from Claude's local conversation store. */
+export declare function readConversation(sessionId: string, options?: ConversationReaderOptions): ConversationMessage[];
+/** Resolve a pi session by exact header id and return its active useful context. */
+export declare function readPiConversationText(sessionId: string): Promise<string>;
+/** Resolve by exact membership across provider stores, never by session-id shape. */
+export declare function readConversationText(sessionId: string, options?: ConversationReaderOptions): Promise<string>;
 export declare function findRecentSessionId(cwd?: string): string | null;

package/dist/conversation/reader.js

@@ -1,56 +1,346 @@
-import { execSync } from 'child_process';
-import { homedir } from 'os';
-import { join } from 'path';
-import { existsSync } from 'fs';
-const CLAUDE_DB_PATH = join(homedir(), '.claude', '__store.db');
-export function readConversation(sessionId) {
-    if (!existsSync(CLAUDE_DB_PATH)) {
-        throw new Error(`Claude database not found at ${CLAUDE_DB_PATH}`);
+import { execFileSync, execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export class ConversationReadError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = 'ConversationReadError';
     }
+}
+const CLAUDE_DB_PATH = join(homedir(), '.claude', '__store.db');
+const MAX_SESSION_ID_LENGTH = 256;
+const piSessionIndex = new Map();
+/** Read messages from Claude's local conversation store. */
+export function readConversation(sessionId, options = {}) {
+    const claudeDbPath = options.claudeDbPath ?? CLAUDE_DB_PATH;
+    if (!existsSync(claudeDbPath))
+        throw new Error('Claude conversation store unavailable');
     const query = `
     SELECT bm.message_type,
            COALESCE(um.message, am.message) AS content
     FROM base_messages bm
     LEFT JOIN user_messages um ON bm.uuid = um.uuid
     LEFT JOIN assistant_messages am ON bm.uuid = am.uuid
-    WHERE bm.session_id = '${sessionId.replace(/'/g, "''")}'
+    WHERE bm.session_id = '${escapeSqlString(sessionId)}'
     ORDER BY bm.timestamp ASC;
   `;
-    const raw = execSync(`sqlite3 -json "${CLAUDE_DB_PATH}" "${query.replace(/"/g, '\\"')}"`, {
-        encoding: 'utf8',
-        maxBuffer: 50 * 1024 * 1024,
-    });
+    const raw = runSqlite(claudeDbPath, query);
     if (!raw.trim())
         return [];
     const rows = JSON.parse(raw);
-    const messages = [];
-    for (const row of rows) {
-        if (!row.content)
+    return rows.flatMap((row) => row.content && (row.message_type === 'user' || row.message_type === 'assistant')
+        ? [{ role: row.message_type, content: row.content }]
+        : []);
+}
+/** Resolve a pi session by exact header id and return its active useful context. */
+export async function readPiConversationText(sessionId) {
+    if (sessionId.length === 0 || sessionId.length > MAX_SESSION_ID_LENGTH)
+        throw new ConversationReadError('session_not_found');
+    const pi = await import('@earendil-works/pi-coding-agent').catch(() => {
+        throw new ConversationReadError('session_unreadable');
+    });
+    const paths = await resolvePiSessionPaths(pi.SessionManager, sessionId);
+    if (paths.length === 0)
+        throw new ConversationReadError('session_not_found');
+    if (paths.length !== 1)
+        throw new ConversationReadError('session_ambiguous');
+    let entries;
+    try {
+        // parseSessionEntries is the package-root parser. Reading only the SDK-discovered
+        // path keeps an untrusted deck id from becoming a filesystem locator.
+        const raw = readFileSync(paths[0], 'utf8');
+        rejectMalformedCompleteJsonlRecords(raw);
+        entries = pi.parseSessionEntries(raw);
+    }
+    catch {
+        throw new ConversationReadError('session_unreadable');
+    }
+    const header = entries[0];
+    if (!isMatchingHeader(header, sessionId))
+        throw new ConversationReadError('session_id_mismatch');
+    if (entries.length < 2)
+        throw new ConversationReadError('conversation_empty');
+    try {
+        pi.migrateSessionEntries(entries);
+        const sessionEntries = entries.slice(1).filter((entry) => entry.type !== 'session');
+        const context = pi.buildSessionContext(sessionEntries);
+        const text = context.messages.map(serializePiMessage).filter((part) => part !== '').join('\n\n').trim();
+        if (text === '')
+            throw new ConversationReadError('conversation_empty');
+        return text;
+    }
+    catch (error) {
+        if (error instanceof ConversationReadError)
+            throw error;
+        throw new ConversationReadError('session_unreadable');
+    }
+}
+async function resolvePiSessionPaths(SessionManager, sessionId) {
+    const root = process.env.PI_CODING_AGENT_DIR ?? join(homedir(), '.pi', 'agent');
+    let index = piSessionIndex.get(root);
+    if (index === undefined) {
+        index = await buildPiSessionIndex(SessionManager);
+        piSessionIndex.set(root, index);
+    }
+    let paths = index.get(sessionId) ?? [];
+    // A popup can outlive session creation. Refresh once on a miss, then keep the
+    // process-local cache for subsequent visuals instead of rescanning every transcript.
+    if (paths.length === 0) {
+        index = await buildPiSessionIndex(SessionManager);
+        piSessionIndex.set(root, index);
+        paths = index.get(sessionId) ?? [];
+    }
+    return paths;
+}
+async function buildPiSessionIndex(SessionManager) {
+    let sessions;
+    try {
+        sessions = await SessionManager.listAll();
+    }
+    catch {
+        throw new ConversationReadError('session_unreadable');
+    }
+    const index = new Map();
+    for (const session of sessions) {
+        const paths = index.get(session.id);
+        if (paths === undefined)
+            index.set(session.id, [session.path]);
+        else
+            paths.push(session.path);
+    }
+    return index;
+}
+/** Resolve by exact membership across provider stores, never by session-id shape. */
+export async function readConversationText(sessionId, options = {}) {
+    if (sessionId.length === 0 || sessionId.length > MAX_SESSION_ID_LENGTH)
+        throw new ConversationReadError('session_not_found');
+    const claudeDbPath = options.claudeDbPath ?? CLAUDE_DB_PATH;
+    const pi = await import('@earendil-works/pi-coding-agent').catch(() => {
+        throw new ConversationReadError('session_unreadable');
+    });
+    const piPaths = await resolvePiSessionPaths(pi.SessionManager, sessionId);
+    const claudeMatches = findClaudeSessionMembership(sessionId, claudeDbPath);
+    const matches = (piPaths.length === 1 ? 1 : 0) + (claudeMatches ? 1 : 0);
+    if (piPaths.length > 1 || matches > 1)
+        throw new ConversationReadError('session_ambiguous');
+    if (matches === 0)
+        throw new ConversationReadError('session_not_found');
+    if (claudeMatches) {
+        try {
+            const text = readConversation(sessionId, { claudeDbPath }).map((message) => `${message.role}: ${message.content}`).join('\n\n').trim();
+            if (text === '')
+                throw new ConversationReadError('conversation_empty');
+            return text;
+        }
+        catch (error) {
+            if (error instanceof ConversationReadError)
+                throw error;
+            throw new ConversationReadError('session_unreadable');
+        }
+    }
+    return readPiConversationText(sessionId);
+}
+function findClaudeSessionMembership(sessionId, claudeDbPath) {
+    if (!existsSync(claudeDbPath))
+        return false;
+    try {
+        return runSqlite(claudeDbPath, `SELECT 1 AS found FROM base_messages WHERE session_id = '${escapeSqlString(sessionId)}' LIMIT 1;`).trim() !== '';
+    }
+    catch {
+        throw new ConversationReadError('session_unreadable');
+    }
+}
+function runSqlite(dbPath, query) {
+    return execFileSync('sqlite3', ['-json', dbPath, query], { encoding: 'utf8', maxBuffer: 50 * 1024 * 1024 });
+}
+function escapeSqlString(value) { return value.replace(/'/g, "''"); }
+/** Reject corrupt records while allowing only an unterminated JSON-object prefix being concurrently written. */
+function rejectMalformedCompleteJsonlRecords(raw) {
+    const lines = raw.split('\n');
+    for (const line of lines.slice(0, -1)) {
+        if (line.trim() === '')
             continue;
-        if (row.message_type === 'user' || row.message_type === 'assistant') {
-            messages.push({
-                role: row.message_type,
-                content: row.content,
-            });
+        JSON.parse(line);
+    }
+    const tail = lines.at(-1);
+    if (!raw.endsWith('\n') && tail !== '' && !isIncompleteJsonObjectPrefix(tail))
+        JSON.parse(tail);
+}
+function isIncompleteJsonObjectPrefix(source) {
+    let offset = 0;
+    const whitespace = () => { while (/\s/.test(source[offset] ?? ''))
+        offset += 1; };
+    const string = () => {
+        if (source[offset++] !== '"')
+            return 'malformed';
+        while (offset < source.length) {
+            const character = source[offset++];
+            if (character === '"')
+                return 'complete';
+            if (character < ' ')
+                return 'malformed';
+            if (character === '\\') {
+                if (offset === source.length)
+                    return 'incomplete';
+                const escape = source[offset++];
+                if (!'"\\/bfnrtu'.includes(escape))
+                    return 'malformed';
+                if (escape === 'u') {
+                    for (let count = 0; count < 4; count += 1) {
+                        if (offset === source.length)
+                            return 'incomplete';
+                        if (!/[0-9a-f]/i.test(source[offset++]))
+                            return 'malformed';
+                    }
+                }
+            }
+        }
+        return 'incomplete';
+    };
+    const value = () => {
+        whitespace();
+        const character = source[offset];
+        if (character === undefined)
+            return 'incomplete';
+        if (character === '"')
+            return string();
+        if (character === '{')
+            return object();
+        if (character === '[')
+            return array();
+        for (const literal of ['true', 'false', 'null']) {
+            if (source.slice(offset, offset + literal.length) === literal) {
+                offset += literal.length;
+                return 'complete';
+            }
+            if (literal.startsWith(source.slice(offset)))
+                return 'incomplete';
+        }
+        if (character === '-' || /[0-9]/.test(character)) {
+            const match = source.slice(offset).match(/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/);
+            if (match === null)
+                return character === '-' ? 'incomplete' : 'malformed';
+            offset += match[0].length;
+            return 'complete';
+        }
+        return 'malformed';
+    };
+    const object = () => {
+        offset += 1;
+        whitespace();
+        if (source[offset] === '}') {
+            offset += 1;
+            return 'complete';
         }
+        while (true) {
+            if (offset === source.length)
+                return 'incomplete';
+            const key = string();
+            if (key !== 'complete')
+                return key;
+            whitespace();
+            if (offset === source.length)
+                return 'incomplete';
+            if (source[offset++] !== ':')
+                return 'malformed';
+            const item = value();
+            if (item !== 'complete')
+                return item;
+            whitespace();
+            if (offset === source.length)
+                return 'incomplete';
+            const separator = source[offset++];
+            if (separator === '}')
+                return 'complete';
+            if (separator !== ',')
+                return 'malformed';
+            whitespace();
+        }
+    };
+    const array = () => {
+        offset += 1;
+        whitespace();
+        if (source[offset] === ']') {
+            offset += 1;
+            return 'complete';
+        }
+        while (true) {
+            const item = value();
+            if (item !== 'complete')
+                return item;
+            whitespace();
+            if (offset === source.length)
+                return 'incomplete';
+            const separator = source[offset++];
+            if (separator === ']')
+                return 'complete';
+            if (separator !== ',')
+                return 'malformed';
+            whitespace();
+        }
+    };
+    const result = value();
+    whitespace();
+    return result === 'incomplete' && offset === source.length && source.trimStart().startsWith('{');
+}
+function isMatchingHeader(entry, sessionId) {
+    return entry?.type === 'session' && entry.id === sessionId;
+}
+function serializePiMessage(message) {
+    switch (message.role) {
+        case 'user': return labeledText('user', message.content);
+        case 'assistant': {
+            const blocks = Array.isArray(message.content) ? message.content : [];
+            const text = blocks.flatMap((block) => {
+                if (!isRecord(block))
+                    return [];
+                if (block.type === 'text' && typeof block.text === 'string')
+                    return [block.text];
+                if (block.type === 'toolCall' && typeof block.name === 'string')
+                    return [`tool call ${block.name}: ${safeJson(block.arguments)}`];
+                return [];
+            }).filter((part) => part.trim() !== '');
+            return text.length === 0 ? '' : `assistant: ${text.join('\n')}`;
+        }
+        case 'toolResult': return labeledText(`tool result${typeof message.toolName === 'string' ? ` ${message.toolName}` : ''}`, message.content);
+        case 'compactionSummary': return typeof message.summary === 'string' && message.summary.trim() !== '' ? `compaction summary: ${message.summary}` : '';
+        case 'branchSummary': return typeof message.summary === 'string' && message.summary.trim() !== '' ? `branch summary: ${message.summary}` : '';
+        default: return '';
+    }
+}
+function labeledText(label, content) {
+    const text = textFromContent(content);
+    return text === '' ? '' : `${label}: ${text}`;
+}
+function textFromContent(content) {
+    if (typeof content === 'string')
+        return content.trim();
+    if (!Array.isArray(content))
+        return '';
+    return content.flatMap((block) => isRecord(block) && block.type === 'text' && typeof block.text === 'string' ? [block.text] : []).join('\n').trim();
+}
+function safeJson(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return '[unserializable arguments]';
     }
-    return messages;
 }
+function isRecord(value) { return typeof value === 'object' && value !== null; }
 export function findRecentSessionId(cwd) {
     if (!existsSync(CLAUDE_DB_PATH))
         return null;
-    const whereClause = cwd
-        ? `WHERE cwd = '${cwd.replace(/'/g, "''")}'`
-        : '';
+    const whereClause = cwd ? `WHERE cwd = '${cwd.replace(/'/g, "''")}'` : '';
     const query = `SELECT DISTINCT session_id FROM base_messages ${whereClause} ORDER BY timestamp DESC LIMIT 1;`;
     try {
-        const raw = execSync(`sqlite3 -json "${CLAUDE_DB_PATH}" "${query.replace(/"/g, '\\"')}"`, {
-            encoding: 'utf8',
-        });
+        const raw = execSync(`sqlite3 -json "${CLAUDE_DB_PATH}" "${query.replace(/"/g, '\\"')}"`, { encoding: 'utf8' });
         if (!raw.trim())
             return null;
-        const rows = JSON.parse(raw);
-        return rows[0]?.session_id ?? null;
+        return JSON.parse(raw)[0]?.session_id ?? null;
     }
     catch {
         return null;

package/dist/editor/roundtrip.d.ts

@@ -0,0 +1,5 @@
+/** Run $EDITOR against a temporary buffer. Terminal ownership stays with the host. */
+export declare function editBufferInEditor(buffer: string): {
+    text: string;
+    error?: string;
+};

package/dist/editor/roundtrip.js

@@ -0,0 +1,36 @@
+import { readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+/** Run $EDITOR against a temporary buffer. Terminal ownership stays with the host. */
+export function editBufferInEditor(buffer) {
+    const tmpFile = join(tmpdir(), `hl-input-${randomUUID()}.txt`);
+    const editor = process.env.EDITOR || 'vi';
+    try {
+        writeFileSync(tmpFile, buffer);
+        // $EDITOR may be a shell fragment such as "code --wait".
+        const result = spawnSync('/bin/sh', ['-c', `${editor} "$1"`, 'sh', tmpFile], { stdio: 'inherit' });
+        if (result.error)
+            return { text: buffer, error: `$EDITOR ("${editor}") failed to launch: ${result.error.message}` };
+        if (result.signal !== null)
+            return { text: buffer, error: `$EDITOR ("${editor}") was killed by signal ${result.signal}` };
+        if (result.status === 127 || result.status === 126)
+            return { text: buffer, error: `$EDITOR ("${editor}") failed to launch (shell exit ${result.status})` };
+        if (result.status !== 0)
+            return { text: buffer, error: `$EDITOR ("${editor}") exited with status ${result.status}` };
+        let text = readFileSync(tmpFile, 'utf8');
+        if (text.endsWith('\n') && !buffer.endsWith('\n'))
+            text = text.slice(0, -1);
+        return { text };
+    }
+    catch (error) {
+        return { text: buffer, error: `$EDITOR round-trip failed: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    finally {
+        try {
+            unlinkSync(tmpFile);
+        }
+        catch { /* best-effort cleanup */ }
+    }
+}