@crouton-kit/crouter 0.3.70 → 0.3.79

package/dist/core/__tests__/scope-crouter-home-fence.test.js

@@ -0,0 +1,55 @@
+// The scope ancestor walk (`collectAncestorScopeRoots` → `findProjectScopeRoots`)
+// must never climb at or above `homedir()`. When HOME is relocated and nested
+// under a directory tree that itself contains a `.crouter/` (a mock-VM home
+// under the real host home, or any relocated-HOME sandbox), the unfenced walk
+// climbs ABOVE homedir() and sweeps in the above-HOME `.crouter` as a bogus
+// "project ancestor" — leaking that host's entire user-global memory store into
+// every nested-HOME node's assembled knowledge/preference catalog. This test
+// pins the fence: an ancestor `.crouter/` sitting ABOVE the relocated HOME must
+// NOT be collected as a project scope root, while a legitimate project
+// `.crouter/` BETWEEN the cwd and HOME still is.
+//
+// Mirrors src/core/__tests__/on-read-crouter-home-fence.test.ts.
+//
+// Run: node --import tsx/esm --test src/core/__tests__/scope-crouter-home-fence.test.ts
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { findProjectScopeRoots, resetScopeCache } from '../scope.js';
+let sandbox;
+let prevHomeEnv;
+before(() => {
+    prevHomeEnv = process.env['HOME'];
+});
+beforeEach(() => {
+    resetScopeCache();
+    // A sandbox that CONTAINS the relocated HOME, so the ancestor walk from a cwd
+    // under HOME can (without the fence) climb above HOME into the sandbox.
+    sandbox = mkdtempSync(join(tmpdir(), 'crtr-scope-fence-'));
+});
+after(() => {
+    resetScopeCache();
+    rmSync(sandbox, { recursive: true, force: true });
+    if (prevHomeEnv === undefined)
+        delete process.env['HOME'];
+    else
+        process.env['HOME'] = prevHomeEnv;
+});
+test('an ancestor .crouter ABOVE a relocated HOME is not collected as a project scope root', () => {
+    // Simulated host user-global store, sitting ABOVE the relocated home.
+    const hostUserRoot = join(sandbox, '.crouter');
+    mkdirSync(join(hostUserRoot, 'memory'), { recursive: true });
+    // The relocated HOME, nested one level under the sandbox.
+    const home = join(sandbox, 'vm-home');
+    process.env['HOME'] = home;
+    // A legitimate project `.crouter/` between the node cwd and HOME.
+    const projectDir = join(home, 'work', 'proj');
+    const projectRoot = join(projectDir, '.crouter');
+    mkdirSync(join(projectRoot, 'memory'), { recursive: true });
+    resetScopeCache();
+    const roots = findProjectScopeRoots(projectDir, null);
+    assert.ok(!roots.includes(hostUserRoot), `above-HOME .crouter must NOT be collected as a project ancestor; got: ${JSON.stringify(roots)}`);
+    assert.ok(roots.includes(projectRoot), `legitimate project .crouter between cwd and HOME must still be collected; got: ${JSON.stringify(roots)}`);
+});

package/dist/core/__tests__/stream-watchdog.test.d.ts

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

package/dist/core/__tests__/stream-watchdog.test.js

@@ -0,0 +1,70 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/stream-watchdog.test.ts
+//
+// Unit-level contract test for StreamWatchdog (see stream-watchdog.ts): a
+// single-timer dead-man's switch the broker pokes while a turn awaits the
+// provider (disarmed during tool execution) and clears at agent_end. This
+// locks the class's arm/clear/single-fire/token contract directly — no broker
+// or fake-engine harness needed (that integration surface is deliberately out
+// of scope; see
+// the roadmap's Fix 3 test-scope note).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { StreamWatchdog } from '../runtime/stream-watchdog.js';
+const MS = 30;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+test('poke() arms the watchdog, firing once after ms with no further poke', async () => {
+    let calls = 0;
+    const wd = new StreamWatchdog(() => calls++, MS);
+    wd.poke(0);
+    assert.equal(calls, 0, 'must not fire before ms elapses');
+    await sleep(MS * 2);
+    assert.equal(calls, 1, 'must fire exactly once after ms with no further poke');
+});
+test('repeated pokes rearm the deadline from the LAST poke, not the first', async () => {
+    // A cancel-without-reschedule bug (clear the old timer but never arm a new
+    // one) would also "never fire while poked", so proving no-fire mid-stream is
+    // not enough. Prove the deadline actually REARMS: no fire around the original
+    // deadline, then exactly one fire measured from the FINAL poke.
+    let calls = 0;
+    const wd = new StreamWatchdog(() => calls++, MS);
+    wd.poke(0);
+    // Re-poke well inside the window, several times, always resetting the clock.
+    // The last poke lands at ~t=2.5*MS, so the original t=MS deadline must pass
+    // with no fire.
+    for (let i = 0; i < 5; i++) {
+        await sleep(MS / 2);
+        wd.poke(0);
+    }
+    assert.equal(calls, 0, 'no fire around the original deadline — each poke rearmed it');
+    // From the final poke the timer must still be armed and fire exactly once.
+    await sleep(MS * 2);
+    assert.equal(calls, 1, 'exactly one fire, measured from the final poke — proves rearming');
+});
+test('clear() after poke prevents firing', async () => {
+    let calls = 0;
+    const wd = new StreamWatchdog(() => calls++, MS);
+    wd.poke(0);
+    wd.clear();
+    await sleep(MS * 2);
+    assert.equal(calls, 0, 'a cleared watchdog must never fire');
+});
+test('fires exactly once even if left armed well past ms', async () => {
+    let calls = 0;
+    const wd = new StreamWatchdog(() => calls++, MS);
+    wd.poke(0);
+    await sleep(MS * 5);
+    assert.equal(calls, 1, 'must fire only once, not repeatedly, past the deadline');
+});
+test('onStall receives the token of the arm that fired (generation binding)', async () => {
+    // The broker stamps each poke with the current session generation and no-ops
+    // a stall whose token is stale. This pins that the token travels with the
+    // arm: a re-poke supersedes the prior token, so a fire after a rebind carries
+    // the NEW generation — and an old timer that somehow survived would deliver
+    // the OLD one, which the broker guard rejects.
+    const tokens = [];
+    const wd = new StreamWatchdog((token) => tokens.push(token), MS);
+    wd.poke(1);
+    wd.poke(2); // supersedes generation 1 before it can fire
+    await sleep(MS * 2);
+    assert.deepEqual(tokens, [2], 'exactly one fire, carrying the most-recent arm\'s token');
+});

package/dist/core/__tests__/tmux-surface.test.js

@@ -18,8 +18,11 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, basename } from 'node:path';
+import { installTmuxBindings } from '../runtime/tmux-chrome.js';
+import { resolveKeybindings } from '../keybindings/index.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const SRC_ROOT = join(__dirname, '..', '..'); // .../src
 const TMUX_TS = join(SRC_ROOT, 'core', 'runtime', 'tmux.ts');
@@ -113,3 +116,72 @@ test('§5.1 lint: only placement.ts / tmux-chrome.ts import the tmux driver', ()
         .map((f) => f.slice(SRC_ROOT.length + 1));
     assert.deepEqual(offenders, [], `modules importing tmux.ts directly: ${offenders.join(', ')}`);
 });
+function isolatedTmux(socket, args) {
+    const result = spawnSync('tmux', ['-S', socket, ...args], { encoding: 'utf8' });
+    return { status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+}
+function tmuxBinding(socket, table, key) {
+    const result = isolatedTmux(socket, ['list-keys', '-T', table]);
+    if (result.status !== 0)
+        return null;
+    return result.stdout.split('\n').find((line) => {
+        const match = line.match(/^bind-key\s+(?:-r\s+)?-T\s+\S+\s+(\S+)\s+/);
+        return match?.[1] === key;
+    }) ?? null;
+}
+test('tmux installer remaps owned pairs and preserves occupied user bindings', (t) => {
+    if (spawnSync('tmux', ['-V']).status !== 0) {
+        t.skip('tmux is unavailable');
+        return;
+    }
+    const name = `crtr-keybindings-${process.pid}-${Date.now()}`;
+    const boot = spawnSync('tmux', ['-L', name, 'new-session', '-d', '-s', 'test'], { encoding: 'utf8' });
+    assert.equal(boot.status, 0, boot.stderr);
+    const socketResult = spawnSync('tmux', ['-L', name, 'display-message', '-p', '#{socket_path}'], { encoding: 'utf8' });
+    const socket = socketResult.stdout.trim();
+    assert.notEqual(socket, '');
+    const priorTmux = process.env['TMUX'];
+    process.env['TMUX'] = `${socket},1,0`;
+    try {
+        isolatedTmux(socket, ['bind-key', '-T', 'root', 'M-]', 'run-shell', `crtr node cycle --dir next --pane '#{pane_id}' >/dev/null 2>&1`]);
+        const first = installTmuxBindings(resolveKeybindings());
+        assert.equal(first.ok, true, JSON.stringify(first.diagnostics));
+        assert.ok(first.installed.some((pair) => pair.table === 'root' && pair.key === 'M-]'));
+        assert.match(tmuxBinding(socket, 'root', 'M-c') ?? '', /display-menu/);
+        assert.match(tmuxBinding(socket, 'root', 'M-v') ?? '', /switch-client/);
+        const remapped = installTmuxBindings(resolveKeybindings({
+            'crtr.tmux.menu.open': ['alt+shift+z'],
+            'crtr.tmux.menu.graph': ['shift+z'],
+            'crtr.tmux.node.next': [],
+            'crtr.tmux.view.next': ['alt+z > n'],
+            'crtr.tmux.view.previous': ['alt+z > p'],
+        }));
+        assert.equal(remapped.ok, true, JSON.stringify(remapped.diagnostics));
+        assert.equal(tmuxBinding(socket, 'root', 'M-c'), null);
+        assert.equal(tmuxBinding(socket, 'root', 'M-]'), null);
+        const menu = tmuxBinding(socket, 'root', 'M-Z') ?? '';
+        assert.match(menu, /graph view/);
+        assert.match(menu, /Z/);
+        const prefix = tmuxBinding(socket, 'root', 'M-z') ?? '';
+        assert.match(prefix, /switch-client/);
+        const again = installTmuxBindings(resolveKeybindings({
+            'crtr.tmux.menu.open': ['alt+shift+y'],
+            'crtr.tmux.node.next': [],
+            'crtr.tmux.view.next': ['alt+z > n'],
+            'crtr.tmux.view.previous': ['alt+z > p'],
+        }));
+        assert.equal(again.ok, true, JSON.stringify(again.diagnostics));
+        isolatedTmux(socket, ['bind-key', '-T', 'root', 'M-Z', 'display-message', 'user-owned']);
+        const occupied = installTmuxBindings(resolveKeybindings({ 'crtr.tmux.menu.open': ['alt+shift+z'] }));
+        assert.equal(occupied.ok, true);
+        assert.ok(occupied.diagnostics.some((diagnostic) => diagnostic.code === 'occupied' && diagnostic.bindingId === 'crtr.tmux.menu.open'));
+        assert.match(tmuxBinding(socket, 'root', 'M-Z') ?? '', /user-owned/);
+    }
+    finally {
+        if (priorTmux === undefined)
+            delete process.env['TMUX'];
+        else
+            process.env['TMUX'] = priorTmux;
+        isolatedTmux(socket, ['kill-server']);
+    }
+});

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

@@ -108,20 +108,38 @@ test('pruneNode: absent id is a no-op', () => {
     assert.equal(t.nodes.size, before);
 });
 // ── tab predicates ───────────────────────────────────────────────────────────
-test('tabPredicate: All / Live / Dormant / Flagged', () => {
-    assert.deepEqual([...TABS], ['All', 'Live', 'Dormant', 'Flagged']);
+test('tabPredicate: All / Live / Dormant / Attention / Pinned', () => {
+    assert.deepEqual([...TABS], ['All', 'Live', 'Dormant', 'Attention', 'Pinned']);
     const active = ROWS[0]; // root1 active
     const idle = ROWS[1]; // child-a idle
     const done = ROWS[2]; // grand-x done
-    const flagged = ROWS[3]; // child-b active asks 2
+    const attention = ROWS[3]; // child-b active asks 2
     assert.equal(tabPredicate('All', done), true);
     assert.equal(tabPredicate('Live', active), true);
     assert.equal(tabPredicate('Live', idle), true);
     assert.equal(tabPredicate('Live', done), false);
     assert.equal(tabPredicate('Dormant', done), true);
     assert.equal(tabPredicate('Dormant', active), false);
-    assert.equal(tabPredicate('Flagged', flagged), true);
-    assert.equal(tabPredicate('Flagged', active), false);
+    // Attention = pending asks OR a fault.
+    assert.equal(tabPredicate('Attention', attention), true);
+    assert.equal(tabPredicate('Attention', active), false);
+    assert.equal(tabPredicate('Attention', { ...active, asks: 0, hanging: { kind: 'provider' } }), true);
+    // Pinned reads the isPinned arg, not the row.
+    assert.equal(tabPredicate('Pinned', active), false);
+    assert.equal(tabPredicate('Pinned', active, true), true);
+});
+// ── flatten: pins ────────────────────────────────────────────────────────────
+test('flatten: Pinned tab shows only pinned rows', () => {
+    const pinned = new Set(['child-c']);
+    const v = flatten(tree(), { collapsed: new Set(), tab: 'Pinned', query: '', pinned });
+    // child-c is directly matched; root2 rides along as its ancestor (context).
+    const matched = v.filter((r) => r.matched).map((r) => r.id);
+    assert.deepEqual(matched, ['child-c']);
+});
+test('flatten: pinned rows float to the top in a flat sort', () => {
+    const pinned = new Set(['lonely']); // an idle straggler that would otherwise sort late
+    const v = flatten(tree(), { collapsed: new Set(), tab: 'All', query: '', sort: 'recency', pinned });
+    assert.equal(v[0].id, 'lonely');
 });
 // ── flatten: collapse / expand ───────────────────────────────────────────────
 const allCollapsed = () => new Set(['root1', 'child-a', 'root2']); // every node with children

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

@@ -37,6 +37,7 @@ function state(over = {}) {
         sort: 'tree',
         preview: false,
         residentsOnly: false,
+        pinned: new Set(),
         ...over,
     };
 }

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

@@ -1,6 +1,11 @@
 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.residents", "crtr.browse.preview", "crtr.browse.search", "crtr.browse.revive-now", "crtr.browse.focus"];
+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
@@ -18,3 +23,4 @@ export declare function runBrowse(opts?: {
     source?: CanvasSource;
     eventStream?: RemoteEventStream;
 }): Promise<void>;
+export {};