@crouton-kit/crouter 0.3.16 → 0.3.18

package/dist/core/canvas/browse/app.js

@@ -0,0 +1,349 @@
+// app.ts — the interactive `crtr canvas browse` runtime.
+//
+// Owns the browser state + the stdin keystroke loop. Pure logic lives in
+// model.ts (buildTree/flatten/fuzzyMatch) and render.ts (renderFrame); this file
+// wires the canvas data access in, holds mutable state, and translates keys.
+//
+// Resume is one action: Enter routes the chosen node through `crtr node focus`,
+// which goes via reviveNode() — the ONLY sanctioned open. NEVER spawn
+// `pi --session` directly (see canvas-resume.ts header for the desync hazard).
+import { execFileSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { dashboardRowsAll, renderForest } from '../render.js';
+import { listNodes, subscriptionsOf } from '../canvas.js';
+import { setupTerminal, restoreTerminal, getTerminalSize, parseKeypress, } from './terminal.js';
+import { buildTree, flatten, TABS, SORTS } from './model.js';
+import { renderFrame, detectColorCaps, headerHeight, PREVIEW_HEIGHT } from './render.js';
+/** Viewport (body) height = total rows minus the header renderFrame draws (see
+ *  render.ts headerHeight), the footer, and the preview panel when shown. Kept
+ *  in lockstep with render.ts via the shared headerHeight/PREVIEW_HEIGHT. */
+function viewportHeight(rowsTotal, search, previewOn) {
+    const rows = Math.max(8, rowsTotal);
+    const previewH = previewOn ? PREVIEW_HEIGHT : 0;
+    return Math.max(1, rows - headerHeight(search) - 1 /* footer */ - previewH);
+}
+export async function runBrowse(opts = {}) {
+    // No TTY → print the static forest and exit 0 (no raw mode).
+    if (!process.stdin.isTTY) {
+        process.stdout.write(renderForest() + '\n');
+        return;
+    }
+    // Snapshot the canvas. Drop kind:'human' control-plane decks — they have no pi
+    // session, so `node focus` refuses them; they are never a navigation/resume
+    // target (mirrors canvas-resume.ts / the node focus guard).
+    const rows = dashboardRowsAll().filter((r) => r.kind !== 'human');
+    const rootIds = listNodes()
+        .filter((n) => n.parent === null && n.kind !== 'human')
+        .map((n) => n.node_id);
+    const tree = buildTree(rows, rootIds, (id) => subscriptionsOf(id).map((s) => s.node_id));
+    const totalNodes = tree.nodes.size;
+    // Default cwd scope = the dir browse was launched from (the request). The popup
+    // / command passes --cwd; resolve it so it compares cleanly against stored cwds.
+    // null when unknown → All dirs (the toggle's other state).
+    const launchCwd = opts.cwd !== undefined && opts.cwd.trim() !== '' ? resolve(opts.cwd) : null;
+    const state = {
+        tab: 'All',
+        cursor: 0,
+        // Initial collapse = every node with children → only roots/top-level show.
+        collapsed: new Set([...tree.nodes.entries()].filter(([, n]) => n.childIds.length > 0).map(([id]) => id)),
+        query: '',
+        search: false,
+        scrollOffset: 0,
+        cwdScope: launchCwd, // default: this dir
+        sort: 'tree',
+        preview: true, // default ON (decision)
+    };
+    let visible = [];
+    // Color capability is fixed for the session (it's a property of the tty/env).
+    const caps = detectColorCaps();
+    // Restore the terminal exactly once, however we leave (quit, resume, crash).
+    let restored = false;
+    const cleanup = () => {
+        if (restored)
+            return;
+        restored = true;
+        try {
+            restoreTerminal();
+        }
+        catch { /* best-effort */ }
+    };
+    // Safety net: an uncaught throw in the (un-unit-tested) keystroke path must
+    // never strand the tty in raw + alt-screen + hidden-cursor.
+    process.once('exit', cleanup);
+    /** Open the chosen node — the ONLY sanctioned path (reviveNode via node focus). */
+    const selectAndFocus = (id) => {
+        cleanup();
+        const args = ['node', 'focus', id, ...(opts.returnPane !== undefined && opts.returnPane !== '' ? ['--pane', opts.returnPane] : [])];
+        try {
+            execFileSync('crtr', args, { stdio: 'inherit' });
+        }
+        catch {
+            // `node focus` swaps panes out from under us; a sync call can be
+            // interrupted. Best-effort — the swap is what matters.
+        }
+        process.exit(0);
+    };
+    const recompute = (keepId) => {
+        visible = flatten(tree, {
+            collapsed: state.collapsed,
+            tab: state.tab,
+            query: state.query,
+            cwdScope: state.cwdScope,
+            sort: state.sort,
+        });
+        if (keepId !== undefined) {
+            const idx = visible.findIndex((v) => v.id === keepId);
+            if (idx >= 0)
+                state.cursor = idx;
+        }
+        if (state.cursor > visible.length - 1)
+            state.cursor = Math.max(0, visible.length - 1);
+        if (state.cursor < 0)
+            state.cursor = 0;
+    };
+    const flush = () => {
+        const size = getTerminalSize();
+        const previewOn = state.preview && visible.length > 0;
+        const viewport = viewportHeight(size.rows, state.search, previewOn);
+        // Keep the cursor inside the viewport window.
+        if (state.cursor < state.scrollOffset)
+            state.scrollOffset = state.cursor;
+        if (state.cursor >= state.scrollOffset + viewport)
+            state.scrollOffset = state.cursor - viewport + 1;
+        if (state.scrollOffset < 0)
+            state.scrollOffset = 0;
+        const frame = renderFrame({
+            tree, visible, tab: state.tab, cursor: state.cursor, scrollOffset: state.scrollOffset,
+            query: state.query, search: state.search, totalNodes,
+            cwdScope: state.cwdScope, sort: state.sort, preview: state.preview,
+        }, size, caps);
+        process.stdout.write(frame);
+    };
+    const quit = () => {
+        cleanup();
+        process.exit(0);
+    };
+    const curRow = () => visible[state.cursor];
+    const isExpanded = (id) => !state.collapsed.has(id);
+    const cycleTab = (dir) => {
+        const i = TABS.indexOf(state.tab);
+        state.tab = TABS[(i + dir + TABS.length) % TABS.length];
+        state.cursor = 0;
+        state.scrollOffset = 0;
+        recompute();
+    };
+    // Cycle sort (tree → relevance → recency), keeping the selected node put.
+    const cycleSort = () => {
+        const keep = curRow()?.id;
+        const i = SORTS.indexOf(state.sort);
+        state.sort = SORTS[(i + 1) % SORTS.length];
+        recompute(keep);
+    };
+    // Toggle cwd scope between the launch dir and All dirs (no-op if launch dir
+    // is unknown — stays All dirs). Keeps the selected node put when still in view.
+    const toggleScope = () => {
+        const keep = curRow()?.id;
+        state.cwdScope = state.cwdScope === null ? launchCwd : null;
+        recompute(keep);
+    };
+    const onKeySearch = (input, key) => {
+        if (key.escape) {
+            // Cancel the search: drop the query AND the relevance ranking it switched
+            // on, returning to the tree.
+            state.search = false;
+            state.query = '';
+            state.sort = 'tree';
+            recompute();
+            flush();
+            return;
+        }
+        if (key.return) {
+            // Commit: keep the filter, drop search mode, land on the first match.
+            state.search = false;
+            const firstMatch = visible.findIndex((v) => v.matched);
+            if (firstMatch >= 0)
+                state.cursor = firstMatch;
+            recompute();
+            flush();
+            return;
+        }
+        if (key.backspace) {
+            state.query = state.query.slice(0, -1);
+            recompute();
+            flush();
+            return;
+        }
+        // Any ctrl-combo: Ctrl+C quits; everything else is swallowed (never typed).
+        if (key.ctrl) {
+            if (input === 'c')
+                quit();
+            return;
+        }
+        // Printable single char → append. Ignore multi-byte / control chunks.
+        if (input.length === 1 && input >= ' ') {
+            state.query += input;
+            recompute();
+            flush();
+        }
+    };
+    const onKeyNav = (input, key) => {
+        // Ctrl-combos first: only Ctrl+C is meaningful (quit); swallow the rest so
+        // Ctrl+L / Ctrl+J / Ctrl+Q etc. don't masquerade as l/j/q commands.
+        if (key.ctrl) {
+            if (input === 'c')
+                quit();
+            return;
+        }
+        const row = curRow();
+        // Quit.
+        if (input === 'q' || key.escape)
+            quit();
+        // Move.
+        if (key.upArrow || input === 'k') {
+            state.cursor = Math.max(0, state.cursor - 1);
+            flush();
+            return;
+        }
+        if (key.downArrow || input === 'j') {
+            state.cursor = Math.max(0, Math.min(visible.length - 1, state.cursor + 1));
+            flush();
+            return;
+        }
+        if (input === 'g') {
+            state.cursor = 0;
+            flush();
+            return;
+        }
+        if (input === 'G') {
+            state.cursor = Math.max(0, visible.length - 1);
+            flush();
+            return;
+        }
+        // Expand / descend.
+        if (key.rightArrow || input === 'l') {
+            if (row !== undefined && row.hasChildren) {
+                if (!isExpanded(row.id)) {
+                    state.collapsed.delete(row.id);
+                    recompute(row.id);
+                }
+                else if (state.cursor + 1 < visible.length && visible[state.cursor + 1].depth > row.depth) {
+                    state.cursor += 1; // already expanded → step onto first child
+                }
+            }
+            flush();
+            return;
+        }
+        // Collapse / ascend.
+        if (key.leftArrow || input === 'h') {
+            if (row !== undefined && row.hasChildren && isExpanded(row.id)) {
+                state.collapsed.add(row.id);
+                recompute(row.id);
+            }
+            else if (row !== undefined) {
+                const parentId = tree.nodes.get(row.id)?.parentId ?? null;
+                if (parentId !== null) {
+                    const idx = visible.findIndex((v) => v.id === parentId);
+                    if (idx >= 0)
+                        state.cursor = idx;
+                }
+            }
+            flush();
+            return;
+        }
+        // Toggle collapse.
+        if (input === ' ') {
+            if (row !== undefined && row.hasChildren) {
+                if (isExpanded(row.id))
+                    state.collapsed.add(row.id);
+                else
+                    state.collapsed.delete(row.id);
+                recompute(row.id);
+            }
+            flush();
+            return;
+        }
+        // Tabs.
+        if (key.tab || input === ']') {
+            cycleTab(1);
+            flush();
+            return;
+        }
+        if (key.shiftTab || input === '[') {
+            cycleTab(-1);
+            flush();
+            return;
+        }
+        if (input >= '1' && input <= '4') {
+            const idx = Number(input) - 1;
+            if (idx < TABS.length) {
+                state.tab = TABS[idx];
+                state.cursor = 0;
+                state.scrollOffset = 0;
+                recompute();
+            }
+            flush();
+            return;
+        }
+        // Sort / scope / preview.
+        if (input === 's') {
+            cycleSort();
+            flush();
+            return;
+        }
+        if (input === 'c') {
+            toggleScope();
+            flush();
+            return;
+        }
+        if (input === 'p') {
+            state.preview = !state.preview;
+            flush();
+            return;
+        }
+        // Search. Starting a search ranks by relevance (decision) so the best prompt/
+        // name match floats to the top as you type.
+        if (input === '/') {
+            state.search = true;
+            state.query = '';
+            state.sort = 'relevance';
+            state.cursor = 0;
+            state.scrollOffset = 0;
+            recompute();
+            flush();
+            return;
+        }
+        // Resume.
+        if (key.return) {
+            if (row !== undefined)
+                selectAndFocus(row.id);
+            return;
+        }
+    };
+    // Boot. If the launch dir holds NO nodes, the default this-dir scope would show
+    // a blank canvas — fall back to All dirs so browse is never empty on open.
+    recompute();
+    if (visible.length === 0 && state.cwdScope !== null) {
+        state.cwdScope = null;
+        recompute();
+    }
+    setupTerminal();
+    flush();
+    await new Promise(() => {
+        const onData = (data) => {
+            try {
+                const { input, key } = parseKeypress(data);
+                if (state.search)
+                    onKeySearch(input, key);
+                else
+                    onKeyNav(input, key);
+            }
+            catch {
+                // Never let a keystroke crash leave the tty wedged.
+                cleanup();
+                process.exit(1);
+            }
+        };
+        process.stdin.on('data', onData);
+        process.stdout.on('resize', flush);
+    });
+}

package/dist/core/canvas/browse/model.d.ts

@@ -0,0 +1,97 @@
+import type { DashboardRow } from '../render.js';
+import type { NodeStatus } from '../types.js';
+export type Tab = 'All' | 'Live' | 'Dormant' | 'Flagged';
+export declare const TABS: readonly Tab[];
+/** How the visible rows are ordered.
+ *    tree      — spanning-tree order, ancestors shown for context (the default).
+ *    relevance — FLAT list, best query match first (super-search).
+ *    recency   — FLAT list, newest `created` first. */
+export type SortMode = 'tree' | 'relevance' | 'recency';
+export declare const SORTS: readonly SortMode[];
+/** Does a node belong to this tab's slice?
+ *    All      — every node.
+ *    Live     — active | idle.
+ *    Dormant  — done | dead | canceled.
+ *    Flagged  — has > 0 pending human asks. */
+export declare function tabPredicate(tab: Tab, row: DashboardRow): boolean;
+export interface TreeNode {
+    row: DashboardRow;
+    depth: number;
+    parentId: string | null;
+    childIds: string[];
+}
+export interface Tree {
+    /** Ordered root ids (live-first, then stragglers). */
+    roots: string[];
+    nodes: Map<string, TreeNode>;
+}
+/** Sort rank for roots/stragglers — live first (active, then idle), dormant
+ *  after. Mirrors render.ts / canvas-resume.ts statusRank. */
+export declare function statusRank(status: NodeStatus): number;
+/**
+ * Build a spanning tree of the whole canvas.
+ *   - `rows`       — one DashboardRow per node (display text + status/asks).
+ *   - `rootIds`    — node ids whose `parent === null` (raw, unsorted).
+ *   - `childIdsOf` — a node's children = the nodes it subscribes to (its
+ *                    reports), in edge order. (= subscriptionsOf(id) node ids.)
+ *
+ * Roots are sorted live-first. The graph is walked DFS-preorder; the FIRST
+ * parent to reach a node owns it (cycle-/multi-parent-safe via `visited`). Any
+ * node never reached from a root (orphaned by a missing subscription edge) is
+ * appended as a depth-0 straggler so "All" is genuinely the whole canvas.
+ */
+export declare function buildTree(rows: DashboardRow[], rootIds: string[], childIdsOf: (id: string) => string[]): Tree;
+/** Case-insensitive subsequence match: every char of `query` appears in `text`
+ *  in order (gaps allowed). Empty query matches everything. Substrings are a
+ *  subsequence, so this subsumes substring matching too. */
+export declare function fuzzyMatch(query: string, text: string): boolean;
+/** Indices in `text` consumed by a greedy left-to-right subsequence match of
+ *  `query` — the same walk as `fuzzyMatch`, but returning WHICH chars matched so
+ *  the renderer can highlight them. Empty set when `query` is empty OR does not
+ *  fully match (no partial highlights). */
+export declare function matchIndices(query: string, text: string): Set<number>;
+/** Does this row match the live query? Super-search spans name (which already
+ *  folds in the pi-generated description), kind, short-id, AND the spawn prompt
+ *  (`row.goal`). Empty query matches everything. */
+export declare function queryMatch(query: string, row: DashboardRow): boolean;
+/** Score how well `query` matches one field, 0 (no match) → 1 (exact). Tiers:
+ *  exact > prefix > word-boundary substring > interior substring > subsequence.
+ *  An interior match decays slightly the later it starts so leading matches win. */
+export declare function fieldScore(query: string, text: string): number;
+/** Weighted relevance of a row to the query across all searched fields. 0 means
+ *  no field matched (excluded from relevance results, same as `queryMatch`). */
+export declare function scoreRow(query: string, row: DashboardRow): number;
+export interface VisibleRow {
+    id: string;
+    depth: number;
+    hasChildren: boolean;
+    collapsed: boolean;
+    matched: boolean;
+}
+export interface FlattenOpts {
+    collapsed: Set<string>;
+    tab: Tab;
+    query: string;
+    /** cwd-scope filter: only rows pinned to this dir are directly-matched. null /
+     *  undefined = All dirs (no cwd filter). Like the tab predicate, it gates the
+     *  matched set — ancestors from other dirs still render dimmed for tree context. */
+    cwdScope?: string | null;
+    /** Ordering. `tree` keeps the spanning tree + ancestor context; `relevance` /
+     *  `recency` produce a FLAT ranked list of directly-matched rows. */
+    sort?: SortMode;
+}
+/** Is this row inside the active cwd scope? No scope (null/undefined) = All dirs. */
+export declare function cwdMatch(scope: string | null | undefined, row: DashboardRow): boolean;
+/**
+ * Flatten the tree to the ordered list of currently-visible rows.
+ *
+ * Inclusion: a node is shown when it directly matches (tab predicate AND query)
+ * — flagged `matched:true` — OR it is an ANCESTOR of a directly-matched node
+ * (shown for tree context, `matched:false`, dimmed by the renderer).
+ *
+ * Collapse: children are emitted only under an EXPANDED node. A node is expanded
+ * when it is not in `collapsed` — except under a non-empty query, where every
+ * ancestor-of-a-match is force-expanded regardless of `collapsed` so matches are
+ * always reachable.
+ */
+export declare function flatten(tree: Tree, opts: FlattenOpts): VisibleRow[];