@north-light/crouter 0.3.154

package/dist/core/canvas/browse/__tests__/rebuild-coalescer.test.js

@@ -0,0 +1,134 @@
+// rebuild-coalescer.test.ts — proves `createCoalescedRebuilder` (`../rebuild-coalescer.ts`)
+// collapses a burst of triggers into ONE rebuild call, and single-flights a
+// trigger that lands while a rebuild is already in flight into exactly one
+// trailing rebuild rather than a second overlapping one. This is the fix for
+// the N+1-per-event amplification `canvas browse`'s remote SSE path used to
+// have (see app.ts) — WITHOUT the coalescer (i.e. calling `rebuild()` directly
+// on every trigger), these assertions fail: a burst of 5 triggers would count
+// 5 rebuild calls, not 1.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createCoalescedRebuilder } from '../rebuild-coalescer.js';
+import { wireEventStreamRebuild } from '../app.js';
+function deferred() {
+    let resolve;
+    const promise = new Promise((r) => { resolve = r; });
+    return { promise, resolve };
+}
+test('a burst of triggers within the debounce window collapses into ONE rebuild call', async () => {
+    let calls = 0;
+    const rebuilder = createCoalescedRebuilder(async () => { calls += 1; }, 30);
+    // Five triggers fired synchronously, well inside the debounce window.
+    for (let i = 0; i < 5; i++)
+        rebuilder.trigger();
+    await new Promise((r) => setTimeout(r, 100));
+    assert.equal(calls, 1, 'a burst of 5 triggers must produce exactly 1 rebuild, not 5');
+});
+test('a trigger landing while a rebuild is in flight coalesces into exactly one trailing rebuild', async () => {
+    let calls = 0;
+    const gate = deferred();
+    const rebuilder = createCoalescedRebuilder(async () => {
+        calls += 1;
+        if (calls === 1)
+            await gate.promise; // hold the first rebuild "in flight"
+    }, 10);
+    rebuilder.trigger();
+    await new Promise((r) => setTimeout(r, 30)); // let the debounce fire and the first rebuild start
+    assert.equal(calls, 1, 'the first rebuild should now be in flight');
+    // A burst of events lands WHILE the rebuild is running — must coalesce into
+    // exactly one trailing rebuild, never one overlapping rebuild per event.
+    rebuilder.trigger();
+    rebuilder.trigger();
+    rebuilder.trigger();
+    await new Promise((r) => setTimeout(r, 30));
+    assert.equal(calls, 1, 'events during an in-flight rebuild must not start an overlapping rebuild yet');
+    gate.resolve(); // let the first rebuild finish
+    await new Promise((r) => setTimeout(r, 30));
+    assert.equal(calls, 2, 'exactly one trailing rebuild must run after the in-flight one finished — not 3');
+});
+test('stop() cancels a pending debounce timer so no rebuild fires', async () => {
+    let calls = 0;
+    const rebuilder = createCoalescedRebuilder(async () => { calls += 1; }, 20);
+    rebuilder.trigger();
+    rebuilder.stop();
+    await new Promise((r) => setTimeout(r, 60));
+    assert.equal(calls, 0, 'stop() must cancel the debounced rebuild before it fires');
+});
+// Integration-shaped proof: drive the coalescer with a rebuild function that
+// actually hits a remote-canvas-shaped mock server (the same shelling contract
+// RemoteCanvasSource uses), and count SERVER request rounds — not just JS call
+// counts — across a burst of SSE-style triggers.
+test('a burst of SSE-style triggers produces ONE round of remote requests, not N', async () => {
+    const { createServer } = await import('node:http');
+    const { RemoteCanvasSource } = await import('../../remote-canvas-source.js');
+    let hits = 0;
+    const server = createServer((req, res) => {
+        const chunks = [];
+        req.on('data', (c) => chunks.push(c));
+        req.on('end', () => {
+            hits += 1;
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ ok: true, exitCode: 0, stdout: JSON.stringify({ nodes: [] }), stderr: '' }));
+        });
+    });
+    // The server MUST close in a `finally` — a listening TCP server keeps its
+    // process's event loop non-empty forever. Under `node --test`, every test
+    // file is its own child process; if an assertion in this test throws before
+    // the old inline `server.close()` at the end of the function ran, the
+    // server (and the process) never exited, wedging one `--test-concurrency`
+    // slot permanently and hanging the whole suite (see the CI-hang postmortem).
+    try {
+        await new Promise((r) => server.listen(0, '127.0.0.1', r));
+        const addr = server.address();
+        const port = typeof addr === 'object' && addr !== null ? addr.port : 0;
+        const source = new RemoteCanvasSource(`http://127.0.0.1:${port}`, 'tok');
+        const rebuilder = createCoalescedRebuilder(async () => {
+            source.invalidate();
+            await source.listNodes(); // one round of remote requests, mirroring app.ts's rebuildSnapshot
+        }, 20);
+        for (let i = 0; i < 6; i++)
+            rebuilder.trigger();
+        // Poll for the request to land instead of sleeping a fixed duration —
+        // deterministic under CI's variable CPU load, and doesn't slow down the
+        // common case (returns as soon as the debounce + request round trip land).
+        const deadline = Date.now() + 2000;
+        while (hits < 1 && Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, 10));
+        }
+        assert.equal(hits, 1, 'a burst of 6 SSE events must produce ONE round of remote requests, not 6');
+    }
+    finally {
+        server.closeAllConnections();
+        await new Promise((r) => server.close(() => r()));
+    }
+});
+// Integration proof for browse/app.ts's ACTUAL wiring — not the coalescer
+// helper in isolation. Every test above instantiates `createCoalescedRebuilder`
+// directly, which would stay green even if `app.ts` invoked a per-event
+// rebuild without ever calling the coalescer. This test instead drives
+// `wireEventStreamRebuild`, the exported function `runBrowse` calls to set up
+// its SSE handler, with a fake event stream shaped like the real
+// `RemoteEventStream` (subscribe/start only, no network) — if
+// `wireEventStreamRebuild` is ever changed to call `rebuild` directly per
+// event instead of routing through the coalescer, this test goes red.
+test('wireEventStreamRebuild (the exported app.ts SSE handler) routes a burst of events through the coalescer, not one rebuild per event', async () => {
+    let calls = 0;
+    const listeners = new Set();
+    const fakeEventStream = {
+        subscribe: (fn) => {
+            listeners.add(fn);
+            return () => listeners.delete(fn);
+        },
+        start: () => { },
+    };
+    const { unsubscribe } = wireEventStreamRebuild(fakeEventStream, async () => { calls += 1; });
+    // A burst of 6 simulated SSE events, well inside the coalescer's debounce
+    // window (default 200ms) — must collapse into ONE rebuild round.
+    for (let i = 0; i < 6; i++) {
+        for (const fn of listeners)
+            fn('nodes');
+    }
+    await new Promise((r) => setTimeout(r, 260));
+    assert.equal(calls, 1, 'a burst of 6 events through the app.ts wiring must produce exactly 1 rebuild, not 6 — if this fails, app.ts stopped routing SSE events through the coalescer');
+    unsubscribe();
+});

package/dist/core/canvas/browse/__tests__/render.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/canvas/browse/__tests__/render.test.js

@@ -0,0 +1,111 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { buildTree, flatten } from '../model.js';
+import { renderFrame, detectColorCaps } from '../render.js';
+// ── Fixture ───────────────────────────────────────────────────────────────────
+function row(node_id, name, status, opts = {}) {
+    return { node_id, name, status, kind: 'general', mode: 'base', ctx_tokens: 0, asks: 0, cwd: '/tmp/proj', created: '2026-01-01T00:00:00.000Z', ...opts };
+}
+const ROWS = [
+    row('root1', 'alpha', 'active'),
+    row('idle1', 'bravo', 'idle'),
+    row('done1', 'charlie', 'done', { ctx_tokens: 120_000 }), // ≥100k → red ctx
+    row('dead1', 'delta', 'dead'),
+    row('canc1', 'echo', 'canceled', { asks: 3 }),
+];
+const ROOT_IDS = ['root1', 'idle1', 'done1', 'dead1', 'canc1'];
+const childIdsOf = () => [];
+function tree() {
+    return buildTree(ROWS, ROOT_IDS, childIdsOf);
+}
+const SIZE = { cols: 100, rows: 24 };
+const ON = { color: true, color256: true };
+const OFF = { color: false, color256: false };
+function state(over = {}) {
+    const t = tree();
+    const visible = flatten(t, { collapsed: new Set(), tab: 'All', query: over.query ?? '' });
+    return {
+        tree: t,
+        visible,
+        tab: 'All',
+        cursor: 0,
+        scrollOffset: 0,
+        query: '',
+        search: false,
+        totalNodes: t.nodes.size,
+        cwdScope: null,
+        profileScope: undefined,
+        sort: 'tree',
+        preview: false,
+        residentsOnly: false,
+        pinned: new Set(),
+        ...over,
+    };
+}
+const ESC = '\x1b[';
+/** Any hue (color) SGR: fg 30–37/90–97, bg 40–47/100–107, or 256/truecolor sel. */
+const HUE_RE = /\x1b\[(3\d|4\d|9\d|10\d|38;|48;)/;
+// ── (a) color enabled → status hue present, glyph still there ──────────────────
+test('all-dirs view retains the project column while profile scope is active', () => {
+    const out = renderFrame(state({ profileScope: 'crouter-12345678', cwdScope: null, cursor: -1 }), SIZE, OFF);
+    assert.ok(out.includes('PROJECT'), 'all-dirs column header remains visible');
+    assert.ok(out.includes('~proj'), 'each row retains its cwd basename');
+});
+test('color on: each status glyph carries its hue, glyph kept', () => {
+    // cursor off the rows we assert so lineBase doesn't wrap the glyph code.
+    const out = renderFrame(state({ cursor: -1 }), SIZE, ON);
+    assert.ok(out.includes(`${ESC}32m●`), 'active → green ●');
+    assert.ok(out.includes(`${ESC}33m○`), 'idle → yellow ○');
+    assert.ok(out.includes(`${ESC}36m✓`), 'done → cyan ✓');
+    assert.ok(out.includes(`${ESC}31m✗`), 'dead → red ✗');
+    assert.ok(out.includes(`${ESC}90m⊘`), 'canceled → gray ⊘');
+});
+test('color on: ctx ≥100k row is red; asks are bright-yellow', () => {
+    const out = renderFrame(state({ cursor: -1 }), SIZE, ON);
+    // ctx is a right-aligned fixed-width column now, so the red span carries padding.
+    assert.ok(out.includes(`${ESC}31m`) && out.includes('120k'), 'ctx ≥100k → red');
+    assert.ok(out.includes(`${ESC}93m`), 'asks → bright-yellow');
+    assert.ok(out.includes('⚑3'), 'flag glyph kept');
+});
+test('color on: cursor row uses a 256-color background (not full reverse)', () => {
+    const out = renderFrame(state({ cursor: 0 }), SIZE, ON);
+    assert.ok(out.includes(`${ESC}48;5;236m`), 'subtle dark-gray cursor bg');
+    // and the status glyph hue still reads on the selected row
+    assert.ok(out.includes(`${ESC}32m●`), 'glyph hue survives on cursor row');
+});
+// ── (b) NO_COLOR → no hue SGR, but the glyphs (the real encoding) remain ───────
+test('color off: no hue SGR emitted, but every status glyph remains', () => {
+    const out = renderFrame(state({ cursor: -1 }), SIZE, OFF);
+    assert.ok(!HUE_RE.test(out), `expected no color SGR, got: ${JSON.stringify(out.match(HUE_RE))}`);
+    for (const g of ['●', '○', '✓', '✗', '⊘']) {
+        assert.ok(out.includes(g), `glyph ${g} kept without color`);
+    }
+    assert.ok(out.includes('⚑3'), 'flag glyph kept without color');
+    // structural SGR is still allowed (dim separators/footer, reverse cursor).
+    assert.ok(out.includes(`${ESC}2m`), 'dim (structural) still used');
+});
+test('color off: cursor row falls back to reverse (structural, no hue)', () => {
+    const out = renderFrame(state({ cursor: 0 }), SIZE, OFF);
+    assert.ok(out.includes(`${ESC}7m`), 'reverse cursor fallback');
+    assert.ok(!HUE_RE.test(out), 'still no hue under no-color');
+});
+// ── (c) query → the matched substring is highlighted ───────────────────────────
+test('color on: matched chars in a row name get the bright-cyan highlight', () => {
+    // query 'lph' matches 'alpha' (a-LPH-a). The matched run is highlighted.
+    const out = renderFrame(state({ query: 'lph', cursor: -1 }), SIZE, ON);
+    assert.ok(out.includes(`${ESC}96mlph`), 'matched substring → bright-cyan');
+});
+test('color off: match highlight degrades to bold (no hue), name intact', () => {
+    const out = renderFrame(state({ query: 'lph', cursor: -1 }), SIZE, OFF);
+    assert.ok(!HUE_RE.test(out), 'no hue under no-color even with a query');
+    assert.ok(out.includes(`${ESC}1mlph`), 'matched chars bold as the no-color affordance');
+});
+// ── detectColorCaps gate ───────────────────────────────────────────────────────
+test('detectColorCaps: honors NO_COLOR, TERM=dumb, and non-TTY', () => {
+    assert.deepEqual(detectColorCaps({ isTTY: true }, { TERM: 'xterm-256color', COLORTERM: 'truecolor' }), { color: true, color256: true });
+    assert.equal(detectColorCaps({ isTTY: true }, { TERM: 'xterm-256color', NO_COLOR: '1' }).color, false);
+    assert.equal(detectColorCaps({ isTTY: true }, { TERM: 'dumb' }).color, false);
+    assert.equal(detectColorCaps({ isTTY: false }, { TERM: 'xterm-256color' }).color, false);
+    // basic color but no 256 → color on, color256 off (reverse cursor fallback).
+    assert.deepEqual(detectColorCaps({ isTTY: true }, { TERM: 'xterm' }), { color: true, color256: false });
+});

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

@@ -0,0 +1,41 @@
+import type { CanvasSource } from '../source.js';
+import type { RemoteEventStream } from '../remote-event-stream.js';
+import { type CoalescedRebuilder } from './rebuild-coalescer.js';
+import { type BindingId, type BindingResolution, type RawTerminalInput } from '../../keybindings/index.js';
+declare const BROWSE_NAV_ACTIONS: readonly ["crtr.browse.quit", "crtr.browse.down", "crtr.browse.up", "crtr.browse.first", "crtr.browse.last", "crtr.browse.expand-or-child", "crtr.browse.collapse-or-parent", "crtr.browse.toggle-fold", "crtr.browse.tab-next", "crtr.browse.tab-previous", "crtr.browse.tab.1", "crtr.browse.tab.2", "crtr.browse.tab.3", "crtr.browse.tab.4", "crtr.browse.tab.5", "crtr.browse.close-subtree", "crtr.browse.sort", "crtr.browse.scope", "crtr.browse.profile", "crtr.browse.residents", "crtr.browse.preview", "crtr.browse.search", "crtr.browse.revive-now", "crtr.browse.focus", "crtr.browse.focus-background"];
+declare const BROWSE_SEARCH_ACTIONS: readonly ["crtr.browse.search.cancel", "crtr.browse.search.commit", "crtr.browse.search.delete", "crtr.browse.search.quit"];
+export declare function resolveBrowseNavAction(bindings: BindingResolution<BindingId>, raw: RawTerminalInput): (typeof BROWSE_NAV_ACTIONS)[number] | null;
+export declare function resolveBrowseSearchAction(bindings: BindingResolution<BindingId>, raw: RawTerminalInput): (typeof BROWSE_SEARCH_ACTIONS)[number] | null;
+/** Wires a RemoteEventStream's `nodes`/`inbox` events through the coalescer
+ *  (`rebuild-coalescer.ts`) so a burst of SSE events collapses to ONE rebuild
+ *  round, never one N+1 remote-subprocess rebuild per event. Exported (rather
+ *  than left inline in `runBrowse`) so the coalescer integration test can
+ *  drive this ACTUAL wiring, not just `createCoalescedRebuilder` in isolation
+ *  — the test asserts this function routes through the coalescer rather than
+ *  calling `rebuild()` directly per event. */
+export declare function wireEventStreamRebuild(eventStream: Pick<RemoteEventStream, 'subscribe' | 'start'>, rebuild: () => Promise<void>): {
+    rebuilder: CoalescedRebuilder;
+    unsubscribe: () => void;
+};
+export declare function runBrowse(opts: {
+    returnPane?: string;
+    cwd?: string;
+    /** Profile to show initially. Undefined means no profile is selected, so the
+     *  initial view includes all profiles and the profile toggle is unavailable. */
+    profileId?: string;
+    /** The read source (required) — canvas-browse always injects one
+     *  (`cliCanvasSource`/remote); no in-process openDb fallback exists here. */
+    source: CanvasSource;
+    eventStream?: RemoteEventStream;
+    /** Local viewer registry projection. Kept separate from CanvasSource because
+     *  focus rows describe this machine's screens, not remote canvas state. */
+    viewedNodeIds?: () => Promise<ReadonlySet<string>>;
+    /** Route the `x` close-out through the daemon API (the CLI injects
+     *  `cliClient().closeNode(id, { finish: true })`). Kept as a callback so this
+     *  core module never imports the openDb-reaching `runtime/close.js`. Returns the
+     *  torn-down ids (root + cascaded). */
+    closeNode: (id: string) => Promise<{
+        closed: string[];
+    }>;
+}): Promise<void>;
+export {};