@north-light/api 0.3.580 → 0.3.587

package/dist/clients/dashboard/app.js

@@ -0,0 +1,438 @@
+// app.ts — the dashboard screen. Runs only as a tmux pane's start command (see
+// commands/surface-dashboard.ts). Polls crtrd's live-roots read every 2 s, paints sections of
+// live root conversations, and opens one by dispatching `crtr surface node focus` from outside
+// this pane's process tree. The screen never opens canvas.db and never launches an engine.
+import { mkdtempSync, readFileSync, rmSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { cliClient } from '../../commands/api-client.js';
+import { loadPins, savePins } from '../../core/canvas/browse/pins.js';
+import { detectColorCaps } from '../../core/tui/draw.js';
+import { getTerminalSize, parseKeypress, restoreTerminal, setupTerminal } from '../../core/tui/terminal.js';
+import { getPaneOption, runShellInBackground, setPaneOption, shellQuote } from '../../core/runtime/placement-tmux.js';
+import { matchesTerminalInput, resolveUserKeybindings } from '../../core/keybindings/index.js';
+import { VIEWER_OWNER_OPTION } from '../attach/session/pane-tag.js';
+import { buildLines, nearestSelectable, placements, rootOf, stepSelectable } from './model.js';
+import { listHeight, renderDashboard } from './render.js';
+const POLL_MS = 2000;
+const TICK_MS = 250;
+const NOTICE_MS = 6000;
+function lineKey(line) {
+    if (line.kind === 'heading')
+        return null;
+    return line.kind === 'root' ? `root:${line.id}` : `child:${line.rootId}:${line.id}`;
+}
+export async function runDashboard(opts) {
+    const pane = process.env['TMUX_PANE'];
+    if (pane === undefined || pane === '')
+        throw new Error('the dashboard runs in a tmux pane (TMUX_PANE is unset)');
+    const client = cliClient();
+    const bindings = resolveUserKeybindings();
+    const caps = detectColorCaps();
+    const matches = (id, raw) => matchesTerminalInput(bindings, id, raw);
+    // Pane identity: claim the pane first, so a late teardown of the viewer this replaced removes
+    // nothing, then drop the viewer tags so tmux stops forwarding attach keys here.
+    const ownPid = String(process.pid);
+    setPaneOption(pane, VIEWER_OWNER_OPTION, ownPid);
+    for (const tag of ['@crtr_node', '@crtr_attach', '@crtr_viewer_at'])
+        setPaneOption(pane, tag, '');
+    // Created exclusively with mode 0700: a pre-planted directory or symlink in the shared temp dir cannot capture the open results.
+    const resultDir = mkdtempSync(join(tmpdir(), 'crtr-dashboard-'));
+    let restored = false;
+    const cleanup = () => {
+        if (restored)
+            return;
+        restored = true;
+        try {
+            restoreTerminal();
+        }
+        catch { /* best-effort */ }
+        if (getPaneOption(pane, VIEWER_OWNER_OPTION) === ownPid)
+            setPaneOption(pane, VIEWER_OWNER_OPTION, '');
+        try {
+            rmSync(resultDir, { recursive: true, force: true });
+        }
+        catch { /* best-effort */ }
+    };
+    process.once('exit', cleanup);
+    for (const sig of ['SIGTERM', 'SIGHUP'])
+        process.once(sig, () => { cleanup(); process.exit(0); });
+    const state = {
+        rows: [],
+        placed: new Map(),
+        pinned: loadPins(),
+        expanded: new Set(),
+        lines: [],
+        cursorKey: null,
+        cursor: 0,
+        scroll: 0,
+        scope: (opts.profileId === undefined ? 'all' : 'profile'),
+        profileLabel: opts.profileId ?? '',
+        loaded: false,
+        help: false,
+        inputFocused: false,
+        inputText: '',
+        dirs: [opts.cwd],
+        dirIndex: 0,
+        dirsLoaded: false,
+        rename: null,
+        renameTarget: null,
+        confirmClose: null,
+        notice: null,
+        opening: null,
+    };
+    const closing = new Set();
+    let noticeTimer;
+    const notify = (text) => {
+        state.notice = text;
+        if (noticeTimer !== undefined)
+            clearTimeout(noticeTimer);
+        noticeTimer = setTimeout(() => { state.notice = null; paint(); }, NOTICE_MS);
+    };
+    const rebuild = () => {
+        const visibleRows = state.rows.filter((r) => !closing.has(r.node_id));
+        state.lines = buildLines(visibleRows, state.placed, state.pinned, state.expanded);
+        const at = state.cursorKey === null ? -1 : state.lines.findIndex((l) => lineKey(l) === state.cursorKey);
+        state.cursor = at >= 0 ? at : nearestSelectable(state.lines, state.cursor);
+        if (state.cursor < 0)
+            state.cursor = 0;
+        const picked = state.lines[state.cursor];
+        state.cursorKey = picked === undefined ? null : lineKey(picked);
+    };
+    const paint = () => {
+        if (restored)
+            return;
+        const size = getTerminalSize();
+        const height = listHeight(size.rows) - 1;
+        if (state.cursor < state.scroll)
+            state.scroll = state.cursor;
+        // keep the section heading above the first row visible when the cursor is at the window top
+        if (state.cursor >= state.scroll + height)
+            state.scroll = state.cursor - height + 1;
+        if (state.scroll < 0)
+            state.scroll = 0;
+        process.stdout.write(renderDashboard({
+            lines: state.lines, cursor: state.cursor, scroll: state.scroll, pinned: state.pinned,
+            scope: state.scope, profileLabel: state.profileLabel,
+            rename: state.rename, inputText: state.inputText, inputFocused: state.inputFocused,
+            chipDir: state.dirs[state.dirIndex] ?? opts.cwd,
+            confirmName: state.confirmClose === null ? null : state.rows.find((r) => r.node_id === state.confirmClose)?.name ?? state.confirmClose,
+            notice: state.notice, opening: state.opening !== null, help: state.help, loaded: state.loaded,
+        }, size, caps));
+    };
+    // One request in flight; a poll requested meanwhile runs once after it lands.
+    let polling = false;
+    let pollAgain = false;
+    const poll = async () => {
+        if (polling) {
+            pollAgain = true;
+            return;
+        }
+        polling = true;
+        try {
+            const res = await client.liveRoots(state.scope === 'profile' && opts.profileId !== undefined ? { profile: opts.profileId } : {});
+            state.rows = res.rows;
+            state.placed = placements(res.rows, state.placed);
+            state.loaded = true;
+            rebuild();
+        }
+        catch (err) {
+            notify(`refresh failed: ${err.message}`);
+        }
+        finally {
+            polling = false;
+        }
+        paint();
+        if (pollAgain) {
+            pollAgain = false;
+            void poll();
+        }
+    };
+    if (opts.profileId !== undefined) {
+        void client.getProfile(opts.profileId).then((p) => { state.profileLabel = p.name; paint(); }).catch(() => undefined);
+    }
+    // ── actions ────────────────────────────────────────────────────────────────
+    const current = () => state.lines[state.cursor];
+    const open = (line) => {
+        if (state.opening !== null || line.kind === 'heading')
+            return;
+        const row = line.kind === 'root' ? line.row : state.rows.find((r) => r.node_id === line.rootId)?.children.find((c) => c.node_id === line.id);
+        const name = row?.name ?? line.id;
+        const ticket = line.kind === 'root' && line.row.asks > 0 ? line.row.first_ask_ticket_id : null;
+        const file = join(resultDir, `open-${Date.now()}`);
+        const cmd = [
+            'crtr', 'surface', 'node', 'focus', line.id, '--pane', pane, '--in-place', '--keep-other-viewers',
+            ...(ticket === null ? [] : ['--open-ticket', ticket]), '--json',
+        ].map(shellQuote).join(' ');
+        // stdout, stderr and the exit status land in files; the status file is renamed into place last.
+        // A successful open replaces this dashboard, whose exit deletes resultDir, so these writes then
+        // fail. The script stays silent and exits 0: tmux shows a failed `run-shell -b` in the active
+        // pane in view mode, which would cover the conversation just opened.
+        const script = `{ ${cmd} >${shellQuote(`${file}.out`)} 2>${shellQuote(`${file}.err`)}; echo $? >${shellQuote(`${file}.code`)} && mv ${shellQuote(`${file}.code`)} ${shellQuote(file)}; } 2>/dev/null; exit 0`;
+        if (!runShellInBackground(script)) {
+            notify(`could not open ${name}`);
+            paint();
+            return;
+        }
+        state.opening = { file, name };
+        paint();
+    };
+    const finishOpen = () => {
+        const pending = state.opening;
+        if (pending === null || !existsSync(pending.file))
+            return;
+        const read = (path) => { try {
+            return readFileSync(path, 'utf8').trim();
+        }
+        catch {
+            return '';
+        } };
+        const code = read(pending.file);
+        const stdout = read(`${pending.file}.out`);
+        const stderr = read(`${pending.file}.err`);
+        for (const f of [pending.file, `${pending.file}.out`, `${pending.file}.err`])
+            rmSync(f, { force: true });
+        state.opening = null;
+        if (code !== '0') {
+            notify(stderr === '' ? `could not open ${pending.name}` : stderr.split('\n')[0]);
+        }
+        else {
+            let focused = false;
+            try {
+                focused = JSON.parse(stdout).focused === true;
+            }
+            catch {
+                focused = false;
+            }
+            if (!focused)
+                notify(`could not open ${pending.name}`);
+        }
+        paint();
+        void poll();
+    };
+    const startConversation = async () => {
+        const prompt = state.inputText.trim();
+        if (prompt === '')
+            return;
+        try {
+            await client.createNode({
+                root: true,
+                prompt,
+                cwd: state.dirs[state.dirIndex] ?? opts.cwd,
+                ...(opts.profileId === undefined ? {} : { profile: opts.profileId }),
+            });
+            state.inputText = '';
+            state.inputFocused = false;
+            void poll();
+        }
+        catch (err) {
+            notify(`could not start: ${err.message}`);
+        }
+        paint();
+    };
+    const loadDirs = () => {
+        if (state.dirsLoaded || opts.profileId === undefined)
+            return;
+        state.dirsLoaded = true;
+        void client.getProfile(opts.profileId).then((p) => {
+            state.dirs = [opts.cwd, ...p.projects.map((x) => x.path).filter((d) => d !== opts.cwd)];
+            paint();
+        }).catch((err) => { notify(`could not list directories: ${err.message}`); paint(); });
+    };
+    const doClose = async (id) => {
+        state.confirmClose = null;
+        closing.add(id);
+        rebuild();
+        paint();
+        try {
+            await client.closeNode(id, { finish: true });
+        }
+        catch (err) {
+            notify(`could not close: ${err.message}`);
+        }
+        finally {
+            closing.delete(id);
+        }
+        void poll();
+        paint();
+    };
+    const commitRename = async () => {
+        const id = state.renameTarget;
+        const name = (state.rename ?? '').trim();
+        state.rename = null;
+        state.renameTarget = null;
+        if (id !== null && name !== '') {
+            try {
+                await client.patchConfig(id, { name });
+            }
+            catch (err) {
+                notify(`could not rename: ${err.message}`);
+            }
+            void poll();
+        }
+        paint();
+    };
+    const togglePin = (id) => {
+        if (state.pinned.has(id))
+            state.pinned.delete(id);
+        else
+            state.pinned.add(id);
+        savePins(state.pinned);
+        rebuild();
+    };
+    const moveTo = (index) => {
+        const idx = nearestSelectable(state.lines, index);
+        if (idx < 0)
+            return;
+        state.cursor = idx;
+        state.cursorKey = lineKey(state.lines[idx]);
+    };
+    // ── keys ───────────────────────────────────────────────────────────────────
+    const printable = (input) => [...input].filter((c) => c >= ' ' && c !== '\x7f').join('');
+    const onText = (input, key, get, set) => {
+        if (key.backspace) {
+            set(get().slice(0, -1));
+            return true;
+        }
+        if (key.ctrl || key.meta)
+            return true;
+        const text = printable(input);
+        if (text !== '')
+            set(get() + text);
+        return true;
+    };
+    const onKey = (input, key) => {
+        const raw = { input, ...key };
+        if (state.help) {
+            state.help = false;
+            paint();
+            return;
+        }
+        if (state.rename !== null) {
+            if (key.escape) {
+                state.rename = null;
+                state.renameTarget = null;
+            }
+            else if (key.return) {
+                void commitRename();
+                return;
+            }
+            else
+                onText(input, key, () => state.rename ?? '', (s) => { state.rename = s; });
+            paint();
+            return;
+        }
+        if (state.inputFocused) {
+            if (matches('crtr.dashboard.input-cancel', raw))
+                state.inputFocused = false;
+            else if (matches('crtr.dashboard.input-submit', raw)) {
+                void startConversation();
+                return;
+            }
+            else if (matches('crtr.dashboard.directory-next', raw))
+                state.dirIndex = (state.dirIndex + 1) % state.dirs.length;
+            else if (matches('crtr.dashboard.directory-previous', raw))
+                state.dirIndex = (state.dirIndex - 1 + state.dirs.length) % state.dirs.length;
+            else
+                onText(input, key, () => state.inputText, (s) => { state.inputText = s; });
+            paint();
+            return;
+        }
+        if (state.confirmClose !== null) {
+            const id = state.confirmClose;
+            if (matches('crtr.dashboard.confirm-close', raw)) {
+                void doClose(id);
+                return;
+            }
+            if (matches('crtr.dashboard.cancel-close', raw)) {
+                state.confirmClose = null;
+                paint();
+            }
+            return; // any other key leaves the y/n prompt up
+        }
+        // No quit key: Ctrl+C and Esc do nothing here; opening a conversation is the way out.
+        const line = current();
+        if (matches('crtr.dashboard.down', raw))
+            moveTo(stepSelectable(state.lines, state.cursor, 1));
+        else if (matches('crtr.dashboard.up', raw))
+            moveTo(stepSelectable(state.lines, state.cursor, -1));
+        else if (matches('crtr.dashboard.first', raw))
+            moveTo(0);
+        else if (matches('crtr.dashboard.last', raw))
+            moveTo(state.lines.length - 1);
+        else if (matches('crtr.dashboard.expand', raw)) {
+            if (line?.kind === 'root' && line.row.children.length > 0) {
+                state.expanded.add(line.id);
+                rebuild();
+            }
+        }
+        else if (matches('crtr.dashboard.collapse', raw)) {
+            if (line !== undefined && line.kind !== 'heading') {
+                const root = rootOf(line);
+                state.expanded.delete(root);
+                state.cursorKey = `root:${root}`;
+                rebuild();
+            }
+        }
+        else if (matches('crtr.dashboard.open', raw)) {
+            if (line !== undefined)
+                open(line);
+            return;
+        }
+        else if (matches('crtr.dashboard.pin', raw)) {
+            const id = line === undefined ? null : rootOf(line);
+            if (id !== null)
+                togglePin(id);
+        }
+        else if (matches('crtr.dashboard.rename', raw)) {
+            const id = line === undefined ? null : rootOf(line);
+            if (id !== null) {
+                state.renameTarget = id;
+                state.rename = state.rows.find((r) => r.node_id === id)?.name ?? '';
+            }
+        }
+        else if (matches('crtr.dashboard.close', raw)) {
+            const id = line === undefined ? null : rootOf(line);
+            const row = id === null ? undefined : state.rows.find((r) => r.node_id === id);
+            if (row !== undefined) {
+                if (row.running_count > 0)
+                    state.confirmClose = row.node_id;
+                else {
+                    void doClose(row.node_id);
+                    return;
+                }
+            }
+        }
+        else if (matches('crtr.dashboard.profile', raw)) {
+            if (opts.profileId !== undefined) {
+                state.scope = state.scope === 'profile' ? 'all' : 'profile';
+                void poll();
+            }
+        }
+        else if (matches('crtr.dashboard.input', raw)) {
+            state.inputFocused = true;
+            loadDirs();
+        }
+        else if (matches('crtr.dashboard.help', raw))
+            state.help = true;
+        paint();
+    };
+    setupTerminal();
+    paint();
+    void poll();
+    setInterval(() => { void poll(); }, POLL_MS);
+    setInterval(finishOpen, TICK_MS);
+    process.stdout.on('resize', paint);
+    await new Promise(() => {
+        process.stdin.on('data', (data) => {
+            try {
+                const { input, key } = parseKeypress(data);
+                onKey(input, key);
+            }
+            catch (err) {
+                notify(`internal error: ${err.message}`);
+                paint();
+            }
+        });
+    });
+}

package/dist/clients/dashboard/model.d.ts

@@ -0,0 +1,39 @@
+import type { LiveRootChildDTO, LiveRootDTO } from '../../api/dto/canvas.js';
+export type Section = 'waiting' | 'running' | 'idle';
+export declare const SECTION_ORDER: readonly Section[];
+export declare const SECTION_TITLE: Record<Section, string>;
+/** Waiting beats Running beats Idle: a running root with an ask still needs the person. */
+export declare function sectionOf(row: LiveRootDTO): Section;
+/** A root's place in its section: the section it is in and the sort key it took on entering it. */
+export interface Placement {
+    section: Section;
+    key: string;
+}
+export type Line = {
+    kind: 'heading';
+    section: Section;
+    count: number;
+} | {
+    kind: 'root';
+    id: string;
+    row: LiveRootDTO;
+    section: Section;
+    expanded: boolean;
+} | {
+    kind: 'child';
+    id: string;
+    rootId: string;
+    child: LiveRootChildDTO;
+};
+/** Carry each root's sort key across refreshes: a row keeps its key while it stays in its
+ *  section, and takes its `last_activity` when it first appears or changes section. */
+export declare function placements(rows: readonly LiveRootDTO[], previous: ReadonlyMap<string, Placement>): Map<string, Placement>;
+/** The flat line list: a heading per non-empty section, pinned rows first inside their section,
+ *  then newest key first; an expanded root is followed by its children. */
+export declare function buildLines(rows: readonly LiveRootDTO[], placed: ReadonlyMap<string, Placement>, pinned: ReadonlySet<string>, expanded: ReadonlySet<string>): Line[];
+/** Index of the nearest selectable line at or after `from` (then before it); -1 when none. */
+export declare function nearestSelectable(lines: readonly Line[], from: number): number;
+/** Step the cursor over headings: +1 / -1 to the next selectable line, or stay put at an end. */
+export declare function stepSelectable(lines: readonly Line[], from: number, dir: 1 | -1): number;
+/** The root a line acts on for pin, rename and close: a child line acts on its root row. */
+export declare function rootOf(line: Line): string | null;

package/dist/clients/dashboard/model.js

@@ -0,0 +1,77 @@
+// model.ts — the dashboard's pure row model: which section a live root belongs to,
+// how rows are ordered inside a section, and the flat list of lines the screen draws.
+export const SECTION_ORDER = ['waiting', 'running', 'idle'];
+export const SECTION_TITLE = {
+    waiting: 'Waiting for you',
+    running: 'Running',
+    idle: 'Idle',
+};
+/** Waiting beats Running beats Idle: a running root with an ask still needs the person. */
+export function sectionOf(row) {
+    if (row.asks > 0 || row.unread || row.fault !== null)
+        return 'waiting';
+    if (row.running_count > 0)
+        return 'running';
+    return 'idle';
+}
+/** Carry each root's sort key across refreshes: a row keeps its key while it stays in its
+ *  section, and takes its `last_activity` when it first appears or changes section. */
+export function placements(rows, previous) {
+    const next = new Map();
+    for (const row of rows) {
+        const section = sectionOf(row);
+        const prior = previous.get(row.node_id);
+        next.set(row.node_id, prior !== undefined && prior.section === section ? prior : { section, key: row.last_activity });
+    }
+    return next;
+}
+/** The flat line list: a heading per non-empty section, pinned rows first inside their section,
+ *  then newest key first; an expanded root is followed by its children. */
+export function buildLines(rows, placed, pinned, expanded) {
+    const lines = [];
+    for (const section of SECTION_ORDER) {
+        const inSection = rows.filter((r) => placed.get(r.node_id)?.section === section);
+        if (inSection.length === 0)
+            continue;
+        inSection.sort((a, b) => {
+            const pa = pinned.has(a.node_id) ? 0 : 1;
+            const pb = pinned.has(b.node_id) ? 0 : 1;
+            if (pa !== pb)
+                return pa - pb;
+            const ka = placed.get(a.node_id).key;
+            const kb = placed.get(b.node_id).key;
+            return ka < kb ? 1 : ka > kb ? -1 : a.node_id < b.node_id ? -1 : 1;
+        });
+        lines.push({ kind: 'heading', section, count: inSection.length });
+        for (const row of inSection) {
+            const isOpen = expanded.has(row.node_id);
+            lines.push({ kind: 'root', id: row.node_id, row, section, expanded: isOpen });
+            if (isOpen)
+                for (const child of row.children)
+                    lines.push({ kind: 'child', id: child.node_id, rootId: row.node_id, child });
+        }
+    }
+    return lines;
+}
+/** Index of the nearest selectable line at or after `from` (then before it); -1 when none. */
+export function nearestSelectable(lines, from) {
+    const start = Math.min(Math.max(0, from), Math.max(0, lines.length - 1));
+    for (let i = start; i < lines.length; i++)
+        if (lines[i].kind !== 'heading')
+            return i;
+    for (let i = start - 1; i >= 0; i--)
+        if (lines[i].kind !== 'heading')
+            return i;
+    return -1;
+}
+/** Step the cursor over headings: +1 / -1 to the next selectable line, or stay put at an end. */
+export function stepSelectable(lines, from, dir) {
+    for (let i = from + dir; i >= 0 && i < lines.length; i += dir)
+        if (lines[i].kind !== 'heading')
+            return i;
+    return from;
+}
+/** The root a line acts on for pin, rename and close: a child line acts on its root row. */
+export function rootOf(line) {
+    return line.kind === 'root' ? line.id : line.kind === 'child' ? line.rootId : null;
+}

package/dist/clients/dashboard/render.d.ts

@@ -0,0 +1,29 @@
+import { type ColorCaps } from '../../core/tui/draw.js';
+import type { Line } from './model.js';
+export interface DashboardFrameState {
+    lines: readonly Line[];
+    cursor: number;
+    scroll: number;
+    pinned: ReadonlySet<string>;
+    /** `all` when the profile filter is off. */
+    scope: 'profile' | 'all';
+    profileLabel: string;
+    /** Rename in progress: the typed name. */
+    rename: string | null;
+    inputText: string;
+    inputFocused: boolean;
+    /** The directory the new conversation will start in. */
+    chipDir: string;
+    /** Row being closed while running, awaiting y/n. */
+    confirmName: string | null;
+    notice: string | null;
+    opening: boolean;
+    help: boolean;
+    loaded: boolean;
+}
+/** Height of the list area: rows minus title, input line and footer. */
+export declare function listHeight(rows: number): number;
+export declare function renderDashboard(state: DashboardFrameState, size: {
+    cols: number;
+    rows: number;
+}, caps: ColorCaps): string;