@north-light/api 0.3.580 → 0.3.588

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

@@ -0,0 +1,43 @@
+import { openReviewWindow } from './review/launch.js';
+import { createReviewClient, ReviewTerminalError, terminalRefusalNotice } from './review/review-client.js';
+/** Resolve a durable review ticket and open it in its own tmux window. */
+export class ReviewAdapter {
+    opts;
+    running = null;
+    stopped = false;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** Resolves true once the review window has opened and been selected. */
+    start() {
+        if (this.running !== null)
+            return this.running;
+        this.running = this.run();
+        return this.running;
+    }
+    async stop() {
+        this.stopped = true;
+        if (this.running !== null)
+            await this.running;
+    }
+    async run() {
+        if (this.opts.host.capabilities.remote) {
+            this.opts.host.notice('The review is unavailable in a remote attach — the file and companion live on the host.');
+            return false;
+        }
+        let review;
+        try {
+            review = await createReviewClient().byId(this.opts.reviewId);
+        }
+        catch (error) {
+            this.opts.host.notice(noticeForLookupFailure(error));
+            return false;
+        }
+        return !this.stopped && openReviewWindow(this.opts.host, review);
+    }
+}
+function noticeForLookupFailure(error) {
+    if (error instanceof ReviewTerminalError)
+        return terminalRefusalNotice(error);
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/clients/inbox/surface.d.ts

@@ -0,0 +1,25 @@
+import type { SurfaceHost } from '../surfaces/host.js';
+import type { InboxRow } from './dto-adapt.js';
+/** The attached node's profile identity, when it has one. The surface never
+ *  selects a profile itself — it is handed the one the viewer is attached to. */
+export interface InboxSurfaceProfile {
+    id: string;
+    /** Display name, or the id when the manifest name could not be resolved. */
+    label: string;
+}
+export interface InboxSurfaceOptions {
+    host: SurfaceHost;
+    profile?: InboxSurfaceProfile;
+    /** Injection seams for tests; production passes none. */
+    scan?: () => Promise<InboxRow[]>;
+}
+export interface InboxSurfaceOwner {
+    /** Mount when closed and close when open. */
+    toggle(): void;
+    /** Mount if closed; seat the selection on `preselectDir` when given. */
+    open(preselectDir?: string): void;
+    /** Idempotent surface and controller teardown. */
+    close(): void;
+    isOpen(): boolean;
+}
+export declare function createInboxSurface(opts: InboxSurfaceOptions): InboxSurfaceOwner;

package/dist/clients/inbox/surface.js

@@ -0,0 +1,190 @@
+import { InboxController } from './controller.js';
+import { byNewestFirst, inboxRowFromDTO } from './dto-adapt.js';
+import { cliClient } from '../../commands/api-client.js';
+import { decodeInboxKey } from './tui/keys.js';
+import { clipLine, visibleWidth } from './tui/ansi.js';
+class InboxComponent {
+    controller;
+    focused = false;
+    rows = 0;
+    width = -1;
+    height = -1;
+    handle;
+    constructor(controller) {
+        this.controller = controller;
+    }
+    setRows(rows) {
+        this.rows = rows;
+    }
+    render(width) {
+        const rows = this.rows;
+        if (width !== this.width || rows !== this.height) {
+            this.width = width;
+            this.height = rows;
+            this.controller.resize(width, rows);
+        }
+        return padFrame(this.controller.render(), width, rows);
+    }
+    handleInput(data) {
+        const { input, key } = decodeInboxKey(data);
+        this.controller.handleKey(input, key);
+    }
+    invalidate() {
+        this.handle?.invalidate();
+    }
+    setHandle(handle) {
+        this.handle = handle;
+    }
+}
+function padFrame(lines, cols, rows) {
+    const frame = lines.slice(0, rows);
+    while (frame.length < rows)
+        frame.push('');
+    return frame.map((line) => {
+        const clipped = clipLine(line, cols);
+        return clipped + ' '.repeat(Math.max(0, cols - visibleWidth(clipped)));
+    });
+}
+/** Reach the row source once before mounting, so a daemon that cannot answer
+ *  surfaces as a notice instead of an inbox that silently has nothing in it. */
+async function probeRows(opts) {
+    if (opts.scan !== undefined)
+        return opts.scan();
+    const { tickets } = await cliClient().listHumanInbox();
+    return tickets.map(inboxRowFromDTO).sort(byNewestFirst);
+}
+/** Name the operation in its failure, so a load error says which half failed. */
+async function named(operation, load) {
+    try {
+        return await load();
+    }
+    catch (error) {
+        throw new Error(`Could not load ${operation}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export function createInboxSurface(opts) {
+    let session;
+    const close = () => {
+        const current = session;
+        if (current === undefined || current.closed)
+            return;
+        current.closed = true;
+        session = undefined;
+        current.controller?.close();
+        current.handle?.close();
+        current.controller = undefined;
+        current.handle = undefined;
+    };
+    const mount = (current) => {
+        if (current.closed || session !== current)
+            return;
+        const nextController = new InboxController({
+            host: opts.host,
+            onDirty: () => current.handle?.invalidate(),
+            onClosed: close,
+            ...(opts.scan === undefined ? {} : { scan: opts.scan }),
+            onInboxActivity: () => refresh(current),
+            ...(current.preselectDir === undefined ? {} : { initialSelection: current.preselectDir }),
+            ...(opts.profile === undefined ? {} : { profile: {
+                    id: opts.profile.id,
+                    label: opts.profile.label,
+                    members: () => current.profileMembers,
+                } }),
+        });
+        const component = new InboxComponent(nextController);
+        current.controller = nextController;
+        try {
+            const handle = opts.host.mount(component);
+            current.handle = handle;
+            component.setHandle(handle);
+            handle.onClose(() => {
+                if (current.handle === handle)
+                    current.handle = undefined;
+                nextController.close();
+            });
+            nextController.start();
+        }
+        catch (error) {
+            close();
+            throw error;
+        }
+    };
+    // The first load decides whether the inbox opens at all — an unreachable
+    // daemon is a notice, not an empty surface. Afterwards the controller owns
+    // its own rows, so activity only has to tell it to re-read.
+    // Visibility and profile membership are loaded together, so the controller
+    // never sees one of them refreshed against the other's stale half.
+    const load = async (probe) => {
+        const profile = opts.profile;
+        // The mounted controller re-reads its own rows; only a first load probes them.
+        const rows = probe ? named('inbox visibility', () => probeRows(opts)) : undefined;
+        // No status or lifecycle restriction: a node that finished can still be the
+        // requester of a ticket that is waiting on a person.
+        const members = profile === undefined
+            ? undefined
+            : named('profile membership', () => cliClient().listNodes({ profile_id: profile.id }));
+        const [, nodes] = await Promise.all([rows, members]);
+        return nodes === undefined ? undefined : new Set(nodes.map((node) => node.node_id));
+    };
+    const refresh = (current, initial = false) => {
+        if (!initial && current.controller !== undefined && opts.profile === undefined) {
+            void current.controller.invalidate();
+            return;
+        }
+        const generation = ++current.refreshGeneration;
+        void load(current.controller === undefined).then((members) => {
+            if (current.closed || session !== current || generation !== current.refreshGeneration)
+                return;
+            if (members !== undefined)
+                current.profileMembers = members;
+            if (current.controller === undefined)
+                mount(current);
+            else
+                current.controller.refreshOutcome();
+        }, (error) => {
+            if (current.closed || session !== current || generation !== current.refreshGeneration)
+                return;
+            const message = error instanceof Error ? error.message : String(error);
+            if (initial) {
+                close();
+                opts.host.notice(message);
+                return;
+            }
+            // The mounted inbox keeps the last complete list and says the refresh
+            // failed, rather than showing a profile emptied by a failed fetch.
+            current.controller?.refreshOutcome(message);
+        });
+    };
+    const open = (preselectDir) => {
+        if (session !== undefined) {
+            if (preselectDir !== undefined)
+                session.controller?.selectDir(preselectDir);
+            return;
+        }
+        if (opts.host.capabilities.remote) {
+            opts.host.notice('The inbox is unavailable in a remote attach.');
+            return;
+        }
+        const current = {
+            closed: false,
+            refreshGeneration: 0,
+            profileMembers: new Set(),
+            ...(preselectDir === undefined ? {} : { preselectDir }),
+        };
+        session = current;
+        refresh(current, true);
+    };
+    const toggle = () => {
+        if (session !== undefined) {
+            close();
+            return;
+        }
+        open();
+    };
+    return {
+        toggle,
+        open,
+        close,
+        isOpen: () => session !== undefined,
+    };
+}

package/dist/clients/inbox/tui/ansi.d.ts

@@ -0,0 +1,68 @@
+export declare const ESC = "\u001B[";
+export declare const RESET = "\u001B[0m";
+export declare const BOLD = "\u001B[1m";
+export declare const DIM = "\u001B[2m";
+export declare const ITALIC = "\u001B[3m";
+export declare const RED = "\u001B[31m";
+export declare const GREEN = "\u001B[32m";
+export declare const YELLOW = "\u001B[33m";
+export declare const CYAN = "\u001B[36m";
+export declare const GRAY = "\u001B[90m";
+export declare const REVERSE = "\u001B[7m";
+export declare function sanitize(text: string): string;
+export declare function singleLine(text: string): string;
+export declare function hline(width: number, char?: string): string;
+export declare function padRight(text: string, width: number): string;
+/** Char-based width truncation with a trailing ellipsis. The canonical page
+ *  renderer variant. */
+export declare function truncate(text: string, maxWidth: number): string;
+/** Word-aware truncation that also flattens newlines and strips decorative
+ *  emoji — tuned for dense inbox rows (ported from sisyphus format.ts). Kept
+ *  distinct from `truncate` because those two surfaces want different behavior. */
+export declare function truncateRow(text: string, max: number): string;
+/** Word-wrap on whitespace; splits on `\n` into separate paragraphs. */
+export declare function wrap(text: string, maxWidth: number): string[];
+/** Hard character wrap that ignores word boundaries; splits on `\n`. Used for
+ *  free-form input buffers where every character (including runs without
+ *  spaces) must stay on screen. */
+export declare function hardWrap(text: string, maxWidth: number): string[];
+/**
+ * Pad each non-empty line with leading spaces to horizontally center the
+ * `contentWidth`-wide block within `cols`. Wide terminals get breathing room;
+ * narrow panes skip centering. Empty lines stay empty so frame diffing keeps
+ * them as cheap no-ops.
+ */
+export declare function centerHorizontal(lines: string[], cols: number, contentWidth: number): string[];
+/** Visible width of a line in display cells. pi-tui's helper is the one
+ *  terminal-cell contract: it accounts for graphemes and wide cells while
+ *  ignoring SGR, OSC, and APC sequences. */
+export declare function visibleWidth(line: string): number;
+/**
+ * The one display-cell containment primitive: the visible cells
+ * `[start, start + width)` of `line`, with escape sequences preserved.
+ *
+ * Every line rendered into a rectangle must fit within its assigned width, so
+ * each logical line occupies one physical row. Overflow wraps into the next
+ * row and violates the frame contract. Styling seen before
+ * the window is replayed at its head so a slice keeps the colors it had in
+ * place, and a double-width glyph straddling either edge becomes spaces so
+ * the slice occupies exactly the cells it claims.
+ */
+export declare function sliceCells(line: string, start: number, width: number): string;
+/**
+ * ANSI-aware clip: truncate a line's visible width to `maxWidth`. Thin
+ * wrapper over `sliceCells` so containment has a single implementation.
+ */
+export declare function clipLine(line: string, maxWidth: number): string;
+/**
+ * Horizontal window onto a row that may be wider than its rectangle (a
+ * Mermaid diagram rendered at the pane's full width). A row that fits is
+ * returned untouched — panning only ever moves content that overflows, so
+ * prose stays put while a diagram slides. Hidden content on either side is
+ * marked with a dim ‹/› in the edge cell, so the row always states whether
+ * more of the diagram exists left or right, and the marker disappears once
+ * that edge is reached (nothing is unreachable).
+ */
+export declare function panLine(line: string, offset: number, width: number): string;
+/** Cells of `line` that fall outside a `width`-wide rectangle. */
+export declare function rowOverflow(line: string, width: number): number;

package/dist/clients/inbox/tui/ansi.js

@@ -0,0 +1,321 @@
+import stringWidth from 'string-width';
+import { visibleWidth as piVisibleWidth } from '@earendil-works/pi-tui';
+// ── ANSI escape constants ─────────────────────────────────────────────────────
+// The single home for these — both the page renderer (render.ts) and the inbox
+// picker (inbox/tui.ts) import from here rather than keeping their own copies.
+export const ESC = '\x1b[';
+export const RESET = `${ESC}0m`;
+export const BOLD = `${ESC}1m`;
+export const DIM = `${ESC}2m`;
+export const ITALIC = `${ESC}3m`;
+export const RED = `${ESC}31m`;
+export const GREEN = `${ESC}32m`;
+export const YELLOW = `${ESC}33m`;
+export const CYAN = `${ESC}36m`;
+export const GRAY = `${ESC}90m`;
+export const REVERSE = `${ESC}7m`;
+// ── Text helpers ──────────────────────────────────────────────────────────────
+const CONTROL_CHARS_RE = /\x1b\[[0-9;?]*[a-zA-Z]|\x1b[@-_]|[\x00-\x08\x0B\x0E-\x1F\x7F-\x9F]/g;
+export function sanitize(text) {
+    if (typeof text !== 'string')
+        return '';
+    return text.replace(CONTROL_CHARS_RE, '');
+}
+export function singleLine(text) {
+    return sanitize(text).replace(/\s+/g, ' ').trim();
+}
+export function hline(width, char = '─') {
+    if (width < 1)
+        return '';
+    return char.repeat(width);
+}
+export function padRight(text, width) {
+    const w = stringWidth(text);
+    if (w >= width)
+        return text;
+    return text + ' '.repeat(width - w);
+}
+/** Char-based width truncation with a trailing ellipsis. The canonical page
+ *  renderer variant. */
+export function truncate(text, maxWidth) {
+    if (maxWidth < 1)
+        return '';
+    if (stringWidth(text) <= maxWidth)
+        return text;
+    const chars = [...text];
+    let w = 0;
+    let out = '';
+    for (const ch of chars) {
+        const cw = stringWidth(ch);
+        if (w + cw + 1 > maxWidth)
+            break;
+        out += ch;
+        w += cw;
+    }
+    return out + '…';
+}
+/** Word-aware truncation that also flattens newlines and strips decorative
+ *  emoji — tuned for dense inbox rows (ported from sisyphus format.ts). Kept
+ *  distinct from `truncate` because those two surfaces want different behavior. */
+export function truncateRow(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 + '…';
+}
+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;
+}
+/** Word-wrap on whitespace; splits on `\n` into separate paragraphs. */
+export 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 : [''];
+}
+/** Hard character wrap that ignores word boundaries; splits on `\n`. Used for
+ *  free-form input buffers where every character (including runs without
+ *  spaces) must stay on screen. */
+export function hardWrap(text, maxWidth) {
+    if (maxWidth < 1)
+        return [text];
+    const segments = text.split('\n');
+    const out = [];
+    for (const seg of segments) {
+        if (seg.length === 0) {
+            out.push('');
+            continue;
+        }
+        let current = '';
+        let currentW = 0;
+        for (const ch of [...seg]) {
+            const cw = stringWidth(ch);
+            if (currentW + cw > maxWidth) {
+                out.push(current);
+                current = ch;
+                currentW = cw;
+            }
+            else {
+                current += ch;
+                currentW += cw;
+            }
+        }
+        out.push(current);
+    }
+    return out;
+}
+/**
+ * Pad each non-empty line with leading spaces to horizontally center the
+ * `contentWidth`-wide block within `cols`. Wide terminals get breathing room;
+ * narrow panes skip centering. Empty lines stay empty so frame diffing keeps
+ * them as cheap no-ops.
+ */
+export function centerHorizontal(lines, cols, contentWidth) {
+    const extraPad = Math.max(0, Math.floor((cols - contentWidth) / 2));
+    if (extraPad === 0)
+        return lines;
+    const pad = ' '.repeat(extraPad);
+    return lines.map((line) => (line === '' ? '' : pad + line));
+}
+/** Visible width of a line in display cells. pi-tui's helper is the one
+ *  terminal-cell contract: it accounts for graphemes and wide cells while
+ *  ignoring SGR, OSC, and APC sequences. */
+export function visibleWidth(line) {
+    return piVisibleWidth(line);
+}
+const ANSI_TOKEN = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b_[^\x07\x1b]*(?:\x07|\x1b\\)|\x1b\[[0-9;?]*[a-zA-Z]|\x1b[@-^]/g;
+const OSC8_TOKEN = /\x1b\]8;[^;\x07\x1b]*;([^\x07\x1b]*)(\x07|\x1b\\)/g;
+const GRAPHEMES = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+/** ANSI escapes are tokens of their own; all printable text is segmented into
+ * extended grapheme clusters before widths or slice boundaries are calculated.
+ * `visibleWidth` assigns display width to the complete cluster (not its
+ * constituent code points), which keeps ZWJ emoji, flags, skin tones and
+ * combining sequences indivisible while panning, and counts a tab as the same
+ * cells the rest of the rectangle measures it at. */
+function displayTokens(line) {
+    const tokens = [];
+    let at = 0;
+    ANSI_TOKEN.lastIndex = 0;
+    for (let match = ANSI_TOKEN.exec(line); match !== null; match = ANSI_TOKEN.exec(line)) {
+        for (const segment of GRAPHEMES.segment(line.slice(at, match.index))) {
+            tokens.push({ ansi: false, text: segment.segment, width: visibleWidth(segment.segment) });
+        }
+        tokens.push({ ansi: true, text: match[0] });
+        at = match.index + match[0].length;
+    }
+    for (const segment of GRAPHEMES.segment(line.slice(at))) {
+        tokens.push({ ansi: false, text: segment.segment, width: visibleWidth(segment.segment) });
+    }
+    return tokens;
+}
+/**
+ * The one display-cell containment primitive: the visible cells
+ * `[start, start + width)` of `line`, with escape sequences preserved.
+ *
+ * Every line rendered into a rectangle must fit within its assigned width, so
+ * each logical line occupies one physical row. Overflow wraps into the next
+ * row and violates the frame contract. Styling seen before
+ * the window is replayed at its head so a slice keeps the colors it had in
+ * place, and a double-width glyph straddling either edge becomes spaces so
+ * the slice occupies exactly the cells it claims.
+ */
+export function sliceCells(line, start, width) {
+    if (width < 1)
+        return '';
+    const from = Math.max(0, start);
+    const end = from + width;
+    let carried = ''; // styling established before the window
+    let out = '';
+    let emitted = false; // any escape inside the window
+    let cell = 0;
+    for (const token of displayTokens(line)) {
+        if (token.ansi) {
+            if (cell < from)
+                carried += token.text;
+            else {
+                out += token.text;
+                emitted = true;
+            }
+            continue;
+        }
+        if (cell >= end)
+            break;
+        const cw = token.width;
+        // A standalone combining mark has no cells but is still a complete
+        // grapheme cluster; retain it whenever its zero-width position is inside
+        // the window rather than dropping it through the usual boundary check.
+        if (cw === 0) {
+            if (cell >= from)
+                out += token.text;
+            continue;
+        }
+        if (cell + cw <= from) {
+            cell += cw;
+            continue;
+        }
+        if (cell < from) { // whole grapheme straddles the left edge
+            out += ' '.repeat(cell + cw - from);
+            cell += cw;
+            continue;
+        }
+        if (cell + cw > end) { // whole grapheme straddles the right edge
+            out += ' '.repeat(end - cell);
+            cell = end;
+            break;
+        }
+        out += token.text;
+        cell += cw;
+    }
+    if (out === '')
+        return '';
+    if (carried !== '') {
+        out = carried + out;
+        emitted = true;
+    }
+    const hyperlinkClose = closeActiveOsc8(out);
+    return emitted ? out + hyperlinkClose + RESET : out;
+}
+/** Close an OSC-8 hyperlink that starts inside a clipped row so it cannot
+ * remain active through padding or the next terminal row. */
+function closeActiveOsc8(line) {
+    let close = '';
+    OSC8_TOKEN.lastIndex = 0;
+    for (let match = OSC8_TOKEN.exec(line); match !== null; match = OSC8_TOKEN.exec(line)) {
+        close = match[1] === '' ? '' : `\x1b]8;;${match[2]}`;
+    }
+    return close;
+}
+/**
+ * ANSI-aware clip: truncate a line's visible width to `maxWidth`. Thin
+ * wrapper over `sliceCells` so containment has a single implementation.
+ */
+export function clipLine(line, maxWidth) {
+    if (maxWidth < 1)
+        return '';
+    if (visibleWidth(line) <= maxWidth)
+        return line; // visibleWidth ignores ANSI
+    return sliceCells(line, 0, maxWidth);
+}
+/**
+ * Horizontal window onto a row that may be wider than its rectangle (a
+ * Mermaid diagram rendered at the pane's full width). A row that fits is
+ * returned untouched — panning only ever moves content that overflows, so
+ * prose stays put while a diagram slides. Hidden content on either side is
+ * marked with a dim ‹/› in the edge cell, so the row always states whether
+ * more of the diagram exists left or right, and the marker disappears once
+ * that edge is reached (nothing is unreachable).
+ */
+export function panLine(line, offset, width) {
+    if (width < 1)
+        return '';
+    const w = visibleWidth(line);
+    if (w <= width)
+        return line;
+    const max = w - width;
+    const off = Math.max(0, Math.min(offset, max));
+    const left = off > 0;
+    const right = off < max;
+    const innerWidth = width - (left ? 1 : 0) - (right ? 1 : 0);
+    const body = innerWidth > 0 ? sliceCells(line, off + (left ? 1 : 0), innerWidth) : '';
+    return `${left ? `${DIM}‹${RESET}` : ''}${body}${right ? `${DIM}›${RESET}` : ''}`;
+}
+/** Cells of `line` that fall outside a `width`-wide rectangle. */
+export function rowOverflow(line, width) {
+    return Math.max(0, visibleWidth(line) - width);
+}

package/dist/clients/inbox/tui/input.d.ts

@@ -0,0 +1,5 @@
+import type { TuiState } from './types.js';
+import type { Key } from './keys.js';
+export type RenderFn = () => void;
+export type ExitFn = (submit?: boolean) => void;
+export declare function handleKeypress(input: string, key: Key, state: TuiState, render: RenderFn, exit: ExitFn): void;