@north-light/crouter 0.3.170 → 0.3.172

package/dist/clients/inbox/review/live-source.js

@@ -0,0 +1,160 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, statSync, watch } from 'node:fs';
+import { basename, dirname } from 'node:path';
+import { documentLines } from '../../../core/document-lines.js';
+import { checkReviewableFile } from '../../../core/human/visible-paths.js';
+/** The trailing delay used to collapse an editor's write/rename burst. */
+export const COALESCE_MS = 120;
+function hashText(text) {
+    return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+function staleReasonFromCheck(reason) {
+    if (reason.includes('UTF-8'))
+        return 'binary';
+    if (reason.includes('too large') || reason.includes('too long'))
+        return 'too-large';
+    return 'unreadable';
+}
+function readSource(absFile) {
+    try {
+        const stat = statSync(absFile);
+        if (!stat.isFile())
+            return { status: 'stale', reason: 'missing' };
+    }
+    catch (error) {
+        return {
+            status: 'stale',
+            reason: error.code === 'ENOENT' ? 'missing' : 'unreadable',
+        };
+    }
+    const check = checkReviewableFile(absFile);
+    if (!check.ok) {
+        if (check.reason === 'not a file')
+            return { status: 'stale', reason: 'unreadable' };
+        return { status: 'stale', reason: staleReasonFromCheck(check.reason) };
+    }
+    try {
+        const text = readFileSync(absFile, 'utf8');
+        return {
+            status: 'live',
+            text,
+            sha256: hashText(text),
+            loadedAt: new Date().toISOString(),
+        };
+    }
+    catch {
+        return { status: 'stale', reason: 'unreadable' };
+    }
+}
+function initialSnapshot(absFile) {
+    const result = readSource(absFile);
+    if (result.status === 'stale') {
+        throw new Error(`Unable to open live source ${absFile}: ${result.reason}`);
+    }
+    return {
+        text: result.text,
+        lines: documentLines(result.text),
+        revision: 0,
+        status: 'live',
+        sha256: result.sha256,
+        loadedAt: result.loadedAt,
+    };
+}
+/** Watch the containing directory so atomic replacement of the file remains live. */
+export function openLiveSource(absFile) {
+    let snapshot = initialSnapshot(absFile);
+    const openedText = snapshot.text;
+    const listeners = new Set();
+    const target = basename(absFile);
+    let watcher;
+    let timer;
+    let closed = false;
+    const refreshNow = () => {
+        if (closed)
+            return;
+        const result = readSource(absFile);
+        const previous = snapshot;
+        if (result.status === 'stale') {
+            const next = {
+                ...previous,
+                status: 'stale',
+                staleReason: result.reason,
+            };
+            snapshot = next;
+            if (previous.status === next.status)
+                return;
+            for (const listener of listeners) {
+                if (!closed)
+                    listener(next, previous);
+            }
+            return;
+        }
+        const textChanged = result.text !== previous.text;
+        const statusChanged = previous.status !== 'live';
+        const next = {
+            text: result.text,
+            lines: textChanged ? documentLines(result.text) : previous.lines,
+            revision: previous.revision + (textChanged ? 1 : 0),
+            status: 'live',
+            sha256: result.sha256,
+            loadedAt: textChanged || statusChanged ? result.loadedAt : previous.loadedAt,
+        };
+        snapshot = next;
+        if (!textChanged && !statusChanged)
+            return;
+        for (const listener of listeners) {
+            if (!closed)
+                listener(next, previous);
+        }
+    };
+    const scheduleRefresh = () => {
+        if (closed)
+            return;
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = undefined;
+            if (!closed)
+                refreshNow();
+        }, COALESCE_MS);
+    };
+    try {
+        watcher = watch(dirname(absFile), (_event, filename) => {
+            if (!closed && filename !== null && String(filename) === target)
+                scheduleRefresh();
+        });
+        watcher.on('error', () => {
+            // The next explicit refresh remains authoritative; a directory watcher
+            // error must not terminate the viewer process.
+        });
+    }
+    catch {
+        // A source that was readable at open remains usable through refreshNow().
+    }
+    return {
+        current: () => snapshot,
+        openText: () => openedText,
+        onChange: (fn) => {
+            if (!closed)
+                listeners.add(fn);
+        },
+        refreshNow,
+        close: () => {
+            if (closed)
+                return;
+            closed = true;
+            if (timer !== undefined) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            listeners.clear();
+            try {
+                watcher?.close();
+            }
+            catch {
+                // Teardown is best effort when the watcher has already failed.
+            }
+            watcher = undefined;
+        },
+    };
+}

package/dist/clients/inbox/review/nvim.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Open the reviewed file in the user's configured editor, optionally at a specific line.
+ * Resolves $VISUAL, then $EDITOR, then falls back to 'vi'.
+ * For vi-family editors (nvim, vim, vi, view), passes the line with the +line syntax.
+ * For other editors, opens the file without line positioning.
+ *
+ * @param absFile - Absolute path to the file to edit
+ * @param line - 1-based line number (only used for vi-family editors)
+ * @returns An object with an optional `error` property if the editor launch or execution failed
+ */
+export declare function openReviewedFileInEditor(absFile: string, line: number): {
+    error?: string;
+};

package/dist/clients/inbox/review/nvim.js

@@ -0,0 +1,42 @@
+import { spawnSync } from 'node:child_process';
+/**
+ * Open the reviewed file in the user's configured editor, optionally at a specific line.
+ * Resolves $VISUAL, then $EDITOR, then falls back to 'vi'.
+ * For vi-family editors (nvim, vim, vi, view), passes the line with the +line syntax.
+ * For other editors, opens the file without line positioning.
+ *
+ * @param absFile - Absolute path to the file to edit
+ * @param line - 1-based line number (only used for vi-family editors)
+ * @returns An object with an optional `error` property if the editor launch or execution failed
+ */
+export function openReviewedFileInEditor(absFile, line) {
+    const editor = process.env.VISUAL ?? process.env.EDITOR ?? 'vi';
+    // Extract the first shell token (the command itself)
+    const firstToken = editor.trim().split(/\s+/)[0];
+    if (!firstToken) {
+        return { error: 'editor configuration is empty' };
+    }
+    // Determine if this is a vi-family editor
+    const editorBasename = firstToken.split('/').pop() || firstToken;
+    const isViFamily = ['nvim', 'vim', 'vi', 'view'].includes(editorBasename);
+    // Build the command arguments
+    const args = isViFamily ? [`+${line}`, absFile] : [absFile];
+    try {
+        const result = spawnSync(firstToken, args, { stdio: 'inherit' });
+        // Check for errors
+        if (result.error) {
+            return { error: result.error.message };
+        }
+        if (result.signal !== null) {
+            return { error: `editor was killed by signal ${result.signal}` };
+        }
+        if (result.status !== 0) {
+            return { error: `editor exited with code ${result.status}` };
+        }
+        return {};
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { error: message };
+    }
+}

package/dist/clients/inbox/review/remap.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Line-based range remapping with whole-line LCS.
+ *
+ * Normalizes lines, trims common prefix/suffix, applies monotone LCS to the
+ * middle section, and builds a stable mapping from old→new line numbers.
+ * Remapped ranges become detached when no line survives, shifted when partly
+ * deleted, or kept when both endpoints are unmoved.
+ */
+/**
+ * A monotone partial mapping from old line numbers to new ones (both 0-based).
+ * Returns undefined when a line was deleted.
+ */
+export interface LineMap {
+    get(oldLine: number): number | undefined;
+}
+/**
+ * The result of remapping a range: kept (unmoved), shifted (partially survived),
+ * or detached (no lines survived).
+ */
+export type RemapResult = {
+    kind: 'kept';
+    line: number;
+    endLine: number;
+} | {
+    kind: 'shifted';
+    line: number;
+    endLine: number;
+} | {
+    kind: 'detached';
+};
+/**
+ * Build a monotone line-number mapping from old→new using LCS.
+ *
+ * - Normalizes all lines using D14: `line.replace(/\s+/g, ' ').trim()`
+ * - Trims common prefix and suffix before LCS
+ * - Applies whole-line LCS to the middle section
+ * - Returns a map where `get(oldLine)` is the new line number or undefined
+ */
+export declare function buildLineMap(oldLines: readonly string[], newLines: readonly string[]): LineMap;
+/**
+ * Remap a range [line, endLine) using the built LineMap.
+ *
+ * Returns:
+ * - `kept`: both endpoints are unmoved
+ * - `shifted`: the range is partially deleted; maps to the min/max of survivors
+ * - `detached`: no lines from the range survived
+ */
+export declare function remapRange(map: LineMap, range: {
+    line: number;
+    endLine: number;
+}): RemapResult;

package/dist/clients/inbox/review/remap.js

@@ -0,0 +1,157 @@
+/**
+ * Line-based range remapping with whole-line LCS.
+ *
+ * Normalizes lines, trims common prefix/suffix, applies monotone LCS to the
+ * middle section, and builds a stable mapping from old→new line numbers.
+ * Remapped ranges become detached when no line survives, shifted when partly
+ * deleted, or kept when both endpoints are unmoved.
+ */
+/** Normalize a line for comparison: collapse whitespace and trim. */
+function normalizeLine(line) {
+    return line.replace(/\s+/g, ' ').trim();
+}
+/**
+ * Build a monotone line-number mapping from old→new using LCS.
+ *
+ * - Normalizes all lines using D14: `line.replace(/\s+/g, ' ').trim()`
+ * - Trims common prefix and suffix before LCS
+ * - Applies whole-line LCS to the middle section
+ * - Returns a map where `get(oldLine)` is the new line number or undefined
+ */
+export function buildLineMap(oldLines, newLines) {
+    // Normalize all lines once
+    const oldNorm = oldLines.map(normalizeLine);
+    const newNorm = newLines.map(normalizeLine);
+    // Find common prefix length
+    let prefixLen = 0;
+    const minPrefix = Math.min(oldNorm.length, newNorm.length);
+    while (prefixLen < minPrefix &&
+        oldNorm[prefixLen] === newNorm[prefixLen]) {
+        prefixLen++;
+    }
+    // Find common suffix length
+    let suffixLen = 0;
+    const minSuffix = Math.min(oldNorm.length - prefixLen, newNorm.length - prefixLen);
+    while (suffixLen < minSuffix &&
+        oldNorm[oldNorm.length - 1 - suffixLen] ===
+            newNorm[newNorm.length - 1 - suffixLen]) {
+        suffixLen++;
+    }
+    // Extract middle sections for LCS
+    const oldMiddleEnd = oldNorm.length - suffixLen;
+    const newMiddleEnd = newNorm.length - suffixLen;
+    const oldMiddle = oldNorm.slice(prefixLen, oldMiddleEnd);
+    const newMiddle = newNorm.slice(prefixLen, newMiddleEnd);
+    // Compute LCS on the middle section
+    const lcsMap = computeLCS(oldMiddle, newMiddle);
+    // Build the final map: prefix + lcsMap + suffix
+    const map = new Map();
+    // Common prefix: identity mapping
+    for (let i = 0; i < prefixLen; i++) {
+        map.set(i, i);
+    }
+    // Middle section from LCS
+    lcsMap.forEach((newIdx, oldIdx) => {
+        map.set(prefixLen + oldIdx, prefixLen + newIdx);
+    });
+    // Common suffix: offset identity mapping
+    for (let i = 0; i < suffixLen; i++) {
+        const oldLine = oldMiddleEnd + i;
+        const newLine = newMiddleEnd + i;
+        map.set(oldLine, newLine);
+    }
+    return {
+        get(oldLine) {
+            return map.get(oldLine);
+        },
+    };
+}
+/**
+ * Compute LCS (Longest Common Subsequence) as a monotone mapping of old→new indices.
+ * Uses dynamic programming to find matching lines and returns only the matching pairs.
+ *
+ * For optimal whole-line matching, we want the longest common subsequence
+ * of line indices, preserving the relative order in both sequences.
+ */
+function computeLCS(oldLines, newLines) {
+    const m = oldLines.length;
+    const n = newLines.length;
+    if (m === 0 || n === 0) {
+        return new Map();
+    }
+    // DP table: dp[i][j] = length of LCS for oldLines[0..i-1] and newLines[0..j-1]
+    const dp = Array(m + 1)
+        .fill(null)
+        .map(() => Array(n + 1).fill(0));
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            if (oldLines[i - 1] === newLines[j - 1]) {
+                dp[i][j] = dp[i - 1][j - 1] + 1;
+            }
+            else {
+                dp[i][j] = Math.max(dp[i - 1][j], dp[i][j - 1]);
+            }
+        }
+    }
+    // Backtrack to find the LCS and build the mapping
+    const matches = new Map();
+    let i = m;
+    let j = n;
+    while (i > 0 && j > 0) {
+        if (oldLines[i - 1] === newLines[j - 1]) {
+            // Match found
+            matches.set(i - 1, j - 1);
+            i--;
+            j--;
+        }
+        else if (dp[i - 1][j] > dp[i][j - 1]) {
+            // oldLines[i-1] was deleted
+            i--;
+        }
+        else {
+            // newLines[j-1] was inserted
+            j--;
+        }
+    }
+    return matches;
+}
+/**
+ * Remap a range [line, endLine) using the built LineMap.
+ *
+ * Returns:
+ * - `kept`: both endpoints are unmoved
+ * - `shifted`: the range is partially deleted; maps to the min/max of survivors
+ * - `detached`: no lines from the range survived
+ */
+export function remapRange(map, range) {
+    const oldStart = range.line;
+    const oldEnd = range.endLine;
+    // Collect all surviving line numbers in the old range
+    let minNew;
+    let maxNew;
+    for (let oldLine = oldStart; oldLine < oldEnd; oldLine++) {
+        const newLine = map.get(oldLine);
+        if (newLine !== undefined) {
+            if (minNew === undefined || newLine < minNew) {
+                minNew = newLine;
+            }
+            if (maxNew === undefined || newLine > maxNew) {
+                maxNew = newLine;
+            }
+        }
+    }
+    if (minNew === undefined) {
+        return { kind: 'detached' };
+    }
+    // Check if both endpoints were preserved in their exact positions
+    const startSurvived = map.get(oldStart);
+    const endSurvived = map.get(oldEnd - 1);
+    if (startSurvived === oldStart && endSurvived === oldEnd - 1) {
+        return { kind: 'kept', line: startSurvived, endLine: endSurvived + 1 };
+    }
+    return {
+        kind: 'shifted',
+        line: minNew,
+        endLine: maxNew + 1,
+    };
+}

package/dist/clients/inbox/review/review-client.d.ts

@@ -0,0 +1,30 @@
+export declare class ReviewTerminalError extends Error {
+    readonly state: 'approved' | 'canceled';
+    readonly resultPath?: string;
+    readonly reason?: string;
+    constructor(state: 'approved', resultPath: string);
+    constructor(state: 'canceled', reason?: string);
+}
+export interface OpenedReview {
+    reviewId: string;
+    companionNodeId: string;
+    file: string;
+    cwd: string;
+}
+export interface ReviewClient {
+    open(reviewId: string): Promise<OpenedReview>;
+    byBridge(bridgeNodeId: string): Promise<{
+        reviewId: string;
+    }>;
+    createInline(p: {
+        originNodeId: string;
+        file: string;
+    }): Promise<OpenedReview>;
+    submit(reviewId: string): Promise<{
+        changed: boolean;
+        resultPath: string;
+    }>;
+    cancel(reviewId: string, reason: string): Promise<void>;
+}
+/** The terminal's complete daemon seam for review lifecycle operations. */
+export declare function createReviewClient(): ReviewClient;

package/dist/clients/inbox/review/review-client.js

@@ -0,0 +1,107 @@
+import { randomUUID } from 'node:crypto';
+import { ApiError } from '../../../api/errors.js';
+import { cliClient } from '../../../commands/api-client.js';
+export class ReviewTerminalError extends Error {
+    state;
+    resultPath;
+    reason;
+    constructor(state, detail) {
+        if (state === 'approved') {
+            if (detail === undefined || detail === '')
+                throw new Error('approved review omitted its canonical result path');
+            super(`review is already approved; see ${detail}`);
+            this.resultPath = detail;
+        }
+        else {
+            super(detail === undefined || detail === '' ? 'review is already canceled' : `review is already canceled: ${detail}`);
+            if (detail !== undefined && detail !== '')
+                this.reason = detail;
+        }
+        this.name = 'ReviewTerminalError';
+        this.state = state;
+    }
+}
+/** The terminal's complete daemon seam for review lifecycle operations. */
+export function createReviewClient() {
+    return {
+        async open(reviewId) {
+            try {
+                const opened = await cliClient().openReview(reviewId);
+                if (opened.disposition === 'terminal')
+                    throw terminalError(opened.review);
+                return await openedReview(opened.review, opened.companion_node_id);
+            }
+            catch (error) {
+                throw terminalErrorFromApi(error);
+            }
+        },
+        async byBridge(bridgeNodeId) {
+            const review = await cliClient().getReviewByBridge(bridgeNodeId);
+            return { reviewId: review.review_id };
+        },
+        async createInline(p) {
+            const review = await cliClient().createReview({
+                origin_kind: 'inline',
+                origin_node_id: p.originNodeId,
+                file: p.file,
+                idempotency_key: randomUUID(),
+            });
+            return await openedReview(review, review.companion_node_id);
+        },
+        async submit(reviewId) {
+            const submitted = await cliClient().submitReview(reviewId);
+            return {
+                changed: requireChanged(submitted.review),
+                resultPath: requireResultPath(submitted.review),
+            };
+        },
+        async cancel(reviewId, reason) {
+            await cliClient().cancelReview(reviewId, { reason, actor: 'human' });
+        },
+    };
+}
+async function openedReview(review, companionNodeId) {
+    if (review.state !== 'open')
+        throw terminalError(review);
+    const companion = await cliClient().getNode(companionNodeId);
+    return {
+        reviewId: review.review_id,
+        companionNodeId,
+        file: review.file,
+        cwd: companion.cwd,
+    };
+}
+function terminalErrorFromApi(error) {
+    if (!(error instanceof ApiError) || error.status !== 409 || error.code !== 'review_terminal_conflict')
+        return error;
+    const review = error.details?.review;
+    if (!isTerminalReview(review))
+        return error;
+    return terminalError(review);
+}
+function terminalError(review) {
+    if (review.state !== 'approved' && review.state !== 'canceled') {
+        throw new Error(`terminal review ${review.review_id} has invalid state ${review.state}`);
+    }
+    return review.state === 'approved'
+        ? new ReviewTerminalError('approved', requireResultPath(review))
+        : new ReviewTerminalError('canceled', review.cancel_reason);
+}
+function requireChanged(review) {
+    if (typeof review.changed !== 'boolean') {
+        throw new Error(`approved review ${review.review_id} omitted its changed disposition`);
+    }
+    return review.changed;
+}
+function requireResultPath(review) {
+    if (typeof review.result_path !== 'string' || review.result_path === '') {
+        throw new Error(`terminal review ${review.review_id} omitted its canonical result path`);
+    }
+    return review.result_path;
+}
+function isTerminalReview(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const state = value.state;
+    return state === 'approved' || state === 'canceled';
+}

package/dist/clients/inbox/review/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/clients/inbox/review/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(), `crtr-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 */ }
+    }
+}