@crouton-kit/crouter 0.3.66 → 0.3.67

package/dist/core/__tests__/remote-canvas-target.test.js

@@ -0,0 +1,87 @@
+// remote-canvas-target.test.ts — config normalization for
+// `remoteCanvas.targets.<name>` (`../config.ts`'s normalizeRemoteCanvasTarget,
+// exercised through the public readConfig/updateConfig surface — it isn't
+// exported directly) plus `resolveRemoteCanvasTarget`'s error paths
+// (`../view/remote-canvas-target.ts`). The one load-bearing invariant here:
+// an error message about a missing/unknown target must never leak a token
+// substring, even though it's guiding the agent toward the exact command
+// that would set one.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { readConfig, updateConfig } from '../config.js';
+import { setRelayToken } from '../secrets.js';
+import { getRemoteCanvasTarget, resolveRemoteCanvasTarget } from '../view/remote-canvas-target.js';
+let home;
+let realHome;
+before(() => {
+    realHome = process.env['HOME'];
+    home = mkdtempSync(join(tmpdir(), 'crtr-remote-target-'));
+    process.env['HOME'] = home;
+});
+beforeEach(() => {
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    rmSync(home, { recursive: true, force: true });
+    if (realHome !== undefined)
+        process.env['HOME'] = realHome;
+    else
+        delete process.env['HOME'];
+});
+test('normalizeRemoteCanvasTarget accepts a valid relayTokenRef entry', () => {
+    updateConfig('user', (cfg) => {
+        cfg.remoteCanvas.targets['cloud'] = { previewEndpoint: 'https://x.preview.bl.run', relayTokenRef: 'cloud' };
+    });
+    const target = getRemoteCanvasTarget('cloud', 'user');
+    assert.deepEqual(target, { previewEndpoint: 'https://x.preview.bl.run', relayTokenRef: 'cloud' });
+});
+test('normalizeRemoteCanvasTarget drops an entry missing relayTokenRef instead of throwing', () => {
+    updateConfig('user', (cfg) => {
+        // Bypass the RemoteCanvasTarget type to write a malformed raw entry, the
+        // same way a hand-edited config.json could.
+        cfg.remoteCanvas.targets['broken'] = { previewEndpoint: 'https://x.preview.bl.run' };
+    });
+    const cfg = readConfig('user');
+    assert.equal(cfg.remoteCanvas.targets['broken'], undefined);
+});
+test('normalizeRemoteCanvasTarget drops an entry with an empty previewEndpoint', () => {
+    updateConfig('user', (cfg) => {
+        cfg.remoteCanvas.targets['broken'] = { previewEndpoint: '', relayTokenRef: 'x' };
+    });
+    assert.equal(readConfig('user').remoteCanvas.targets['broken'], undefined);
+});
+test('resolveRemoteCanvasTarget on an unknown name throws a usage error that never contains a token substring', () => {
+    updateConfig('user', (cfg) => {
+        cfg.remoteCanvas.targets['cloud'] = { previewEndpoint: 'https://x.preview.bl.run', relayTokenRef: 'cloud' };
+    });
+    setRelayToken('cloud', 'super-secret-token', 'user');
+    assert.throws(() => resolveRemoteCanvasTarget('no-such-target', 'user'), (err) => {
+        assert.ok(err instanceof Error);
+        assert.match(err.message, /no remote canvas target named 'no-such-target'/);
+        assert.match(err.message, /configured: cloud/);
+        assert.ok(!err.message.includes('super-secret-token'));
+        return true;
+    });
+});
+test('resolveRemoteCanvasTarget on a target with no stored token throws without leaking a token substring', () => {
+    updateConfig('user', (cfg) => {
+        cfg.remoteCanvas.targets['cloud'] = { previewEndpoint: 'https://x.preview.bl.run', relayTokenRef: 'cloud' };
+    });
+    // Deliberately no setRelayToken call — the secret was never stored.
+    assert.throws(() => resolveRemoteCanvasTarget('cloud', 'user'), (err) => {
+        assert.ok(err instanceof Error);
+        assert.match(err.message, /has no stored relay token/);
+        return true;
+    });
+});
+test('resolveRemoteCanvasTarget on a fully configured target returns the RelayTarget with the real token', () => {
+    updateConfig('user', (cfg) => {
+        cfg.remoteCanvas.targets['cloud'] = { previewEndpoint: 'https://x.preview.bl.run', relayTokenRef: 'cloud' };
+    });
+    setRelayToken('cloud', 'super-secret-token', 'user');
+    const relay = resolveRemoteCanvasTarget('cloud', 'user');
+    assert.deepEqual(relay, { previewEndpoint: 'https://x.preview.bl.run', relayToken: 'super-secret-token' });
+});

package/dist/core/__tests__/secrets.test.d.ts

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

package/dist/core/__tests__/secrets.test.js

@@ -0,0 +1,55 @@
+// secrets.test.ts — the 0600 relay-token store (`../secrets.ts`). Covers the
+// round-trip (set/get/delete) and the one load-bearing invariant a JSON
+// config file doesn't get for free: the file is written 0600, not the
+// process's default umask-derived mode.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, statSync, existsSync, chmodSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { readSecrets, writeSecrets, getRelayToken, setRelayToken, deleteRelayToken, fingerprint } from '../secrets.js';
+let home;
+let realHome;
+before(() => {
+    realHome = process.env['HOME'];
+    home = mkdtempSync(join(tmpdir(), 'crtr-secrets-'));
+    process.env['HOME'] = home;
+});
+beforeEach(() => {
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    rmSync(home, { recursive: true, force: true });
+    if (realHome !== undefined)
+        process.env['HOME'] = realHome;
+    else
+        delete process.env['HOME'];
+});
+test('a scope with no secrets.json yet reads as empty', () => {
+    assert.deepEqual(readSecrets('user'), { relayTokens: {} });
+    assert.equal(getRelayToken('cloud', 'user'), undefined);
+});
+test('set/get/delete round-trip a token by ref', () => {
+    setRelayToken('cloud', 'sekret-token-value', 'user');
+    assert.equal(getRelayToken('cloud', 'user'), 'sekret-token-value');
+    deleteRelayToken('cloud', 'user');
+    assert.equal(getRelayToken('cloud', 'user'), undefined);
+});
+test('writeSecrets writes secrets.json 0600, even over a pre-existing looser-mode file', () => {
+    writeSecrets('user', { relayTokens: { a: 'x' } });
+    const p = join(home, '.crouter', 'secrets.json');
+    assert.ok(existsSync(p));
+    assert.equal(statSync(p).mode & 0o777, 0o600);
+    // Re-write over an existing file that had a looser mode — chmodSync must
+    // re-tighten it, not just rely on the initial writeFileSync mode.
+    chmodSync(p, 0o644);
+    assert.equal(statSync(p).mode & 0o777, 0o644);
+    writeSecrets('user', { relayTokens: { a: 'x', b: 'y' } });
+    assert.equal(statSync(p).mode & 0o777, 0o600);
+});
+test('fingerprint is the sha256(token) hex prefix — pinned, so a reversible encoding fails', () => {
+    assert.equal(fingerprint('sekret-token-value'), '662bda51b31e');
+    assert.notEqual(fingerprint('a-different-token'), fingerprint('sekret-token-value'));
+    assert.match(fingerprint('sekret-token-value'), /^[0-9a-f]{12}$/);
+    assert.ok(!fingerprint('sekret-token-value').includes('sekret-token-value'));
+});

package/dist/core/canvas/__tests__/remote-canvas-source.test.d.ts

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

package/dist/core/canvas/__tests__/remote-canvas-source.test.js

@@ -0,0 +1,371 @@
+// remote-canvas-source.test.ts — `RemoteCanvasSource` (`../remote-canvas-source.ts`)
+// over its real wire contract: a POST to `/__crtr/source` carrying
+// `{kind:'exec', bin, args}` (see `../../view/transport-remote.ts`), bearer-
+// authed. Mirrors `src/clients/attach/__tests__/transport-relay.test.ts`'s
+// `startMockRelay` shape — a plain `node:http` server standing in for the
+// remote canvas's `/__crtr/source` endpoint, recording every request so
+// assertions land on the wire (argv shape, token placement), not just
+// behavior.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { RemoteCanvasSource } from '../remote-canvas-source.js';
+import { dashboardRowsAllFromSource, renderForestFromSource } from '../render.js';
+/** Stand up a bare `node:http` server on an ephemeral loopback port — the
+ *  `/__crtr/source` endpoint a `RemoteCanvasSource` POSTs to. `route` decides
+ *  the response per captured argv; every request is recorded first so a test
+ *  can assert on the raw wire (headers, body) independent of what `route`
+ *  returns. */
+function startMockCrtrServer(route) {
+    return new Promise((resolve) => {
+        const requests = [];
+        const server = createServer((req, res) => {
+            const chunks = [];
+            req.on('data', (c) => chunks.push(c));
+            req.on('end', () => {
+                const bodyText = Buffer.concat(chunks).toString('utf8');
+                const parsed = JSON.parse(bodyText);
+                // Reject any request that does not match the exec-only shelling contract
+                // (`{kind:'exec', bin:'crtr'}`) instead of silently routing it —
+                // RemoteCanvasSource must never send anything else over this wire.
+                if (parsed.kind !== 'exec' || parsed.bin !== 'crtr') {
+                    res.writeHead(500, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, exitCode: 1, stdout: '', stderr: `unexpected request shape: kind=${parsed.kind} bin=${parsed.bin}` }));
+                    return;
+                }
+                requests.push({
+                    authHeader: req.headers.authorization,
+                    url: req.url ?? '',
+                    method: req.method,
+                    headers: req.headers,
+                    rawBody: bodyText,
+                    kind: parsed.kind,
+                    bin: parsed.bin,
+                    args: parsed.args,
+                });
+                const result = route(parsed.args);
+                if (result.kind === 'json') {
+                    res.writeHead(result.status ?? 200, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ ok: true, exitCode: 0, stdout: JSON.stringify(result.body), stderr: '' }));
+                }
+                else {
+                    res.writeHead(result.status, { 'content-type': result.contentType ?? 'text/plain' });
+                    res.end(result.body);
+                }
+            });
+        });
+        server.listen(0, '127.0.0.1', () => {
+            const addr = server.address();
+            const port = typeof addr === 'object' && addr !== null ? addr.port : 0;
+            resolve({
+                url: `http://127.0.0.1:${port}`,
+                requests,
+                close: () => new Promise((res) => server.close(() => res())),
+            });
+        });
+    });
+}
+function meta(id, over = {}) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...over,
+    };
+}
+function showResponse(id, reports = []) {
+    return {
+        node: meta(id),
+        reports: reports.map((r) => ({ node_id: r.node_id, name: r.node_id, kind: 'general', status: 'active', active: r.active })),
+        managers: [],
+        artifacts: { report: 0, doc: 0, roadmap: 0 },
+        pending_triggers: 0,
+        paths: { context_dir: '/tmp/context', reports_dir: '/tmp/reports', session_file: null },
+        follow_up: '',
+    };
+}
+test('every request POSTs argv leading with --json, and the token appears ONLY in the Authorization header', async (t) => {
+    const server = await startMockCrtrServer((args) => {
+        if (args[0] === '--json' && args[1] === 'node' && args[2] === 'inspect' && args[3] === 'show') {
+            return { kind: 'json', body: showResponse(args[4]) };
+        }
+        return { kind: 'json', status: 500, body: {} };
+    });
+    t.after(() => server.close());
+    const source = new RemoteCanvasSource(server.url, 'secret-relay-token');
+    await source.getNode('a');
+    assert.equal(server.requests.length, 1);
+    const req = server.requests[0];
+    assert.equal(req.method, 'POST');
+    assert.equal(req.url, '/__crtr/source');
+    assert.equal(req.authHeader, 'Bearer secret-relay-token');
+    assert.equal(req.kind, 'exec', 'RemoteCanvasSource must only ever send the exec contract');
+    assert.equal(req.bin, 'crtr', 'RemoteCanvasSource must only ever shell the existing crtr binary, never an ad-hoc command');
+    assert.deepEqual(req.args.slice(0, 4), ['--json', 'node', 'inspect', 'show']);
+    assert.ok(!req.url.includes('secret-relay-token'));
+    assert.ok(!JSON.stringify(req.args).includes('secret-relay-token'));
+    assert.ok(!req.rawBody.includes('secret-relay-token'), 'the raw POST body must not carry the token');
+    for (const [k, v] of Object.entries(req.headers)) {
+        if (k.toLowerCase() === 'authorization')
+            continue;
+        assert.ok(!String(v).includes('secret-relay-token'), `header ${k} must not carry the token`);
+    }
+});
+test('getNode/getRow project the show response correctly', async (t) => {
+    const server = await startMockCrtrServer((args) => {
+        if (args[3] === 'show')
+            return { kind: 'json', body: showResponse('a') };
+        return { kind: 'json', status: 500, body: {} };
+    });
+    t.after(() => server.close());
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    const node = await source.getNode('a');
+    assert.equal(node?.node_id, 'a');
+    assert.equal(node?.status, 'active');
+    const row = await source.getRow('a');
+    assert.equal(row?.node_id, 'a');
+    assert.equal(row?.kind, 'general');
+    assert.equal(row?.host_kind, null);
+    assert.equal(row?.profile_id, null);
+});
+test('listNodes passes --status only when a filter is given', async (t) => {
+    const seenArgs = [];
+    const server = await startMockCrtrServer((args) => {
+        seenArgs.push(args);
+        const nodes = [];
+        return { kind: 'json', body: { nodes } };
+    });
+    t.after(() => server.close());
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    await source.listNodes();
+    assert.deepEqual(seenArgs[0], ['--json', 'node', 'inspect', 'list']);
+    await source.listNodes({ status: 'active' });
+    assert.deepEqual(seenArgs[1], ['--json', 'node', 'inspect', 'list', '--status', 'active']);
+    await source.listNodes({ status: ['active', 'idle'] });
+    assert.deepEqual(seenArgs[2], ['--json', 'node', 'inspect', 'list', '--status', 'active,idle']);
+});
+test('subscriptionsOf/subscribersOf map reports/managers with created: \'\'', async (t) => {
+    const server = await startMockCrtrServer((args) => {
+        if (args[3] === 'show') {
+            return {
+                kind: 'json',
+                body: {
+                    ...showResponse(args[4], [{ node_id: 'child', active: true }]),
+                    managers: [{ node_id: 'boss', name: 'boss', kind: 'general', status: 'active', active: false }],
+                },
+            };
+        }
+        return { kind: 'json', status: 500, body: {} };
+    });
+    t.after(() => server.close());
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    const subs = await source.subscriptionsOf('a');
+    assert.deepEqual(subs, [{ node_id: 'child', active: true, created: '' }]);
+    const managers = await source.subscribersOf('a');
+    assert.deepEqual(managers, [{ node_id: 'boss', active: false, created: '' }]);
+});
+test('view BFS traverses subscriptionsOf and is cycle-safe', async (t) => {
+    // root -> a -> b -> a (cycle back to a).
+    const graph = {
+        root: [{ node_id: 'a', active: true }],
+        a: [{ node_id: 'b', active: true }],
+        b: [{ node_id: 'a', active: true }],
+    };
+    const server = await startMockCrtrServer((args) => {
+        if (args[3] === 'show') {
+            const id = args[4];
+            return { kind: 'json', body: showResponse(id, graph[id] ?? []) };
+        }
+        return { kind: 'json', status: 500, body: {} };
+    });
+    t.after(() => server.close());
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    const result = await source.view('root');
+    assert.deepEqual([...result].sort(), ['a', 'b']);
+});
+test('a 500 response, a non-JSON body, and a non-zero exitCode all degrade gracefully instead of throwing', async (t) => {
+    const server = await startMockCrtrServer((args) => {
+        if (args.includes('http500'))
+            return { kind: 'json', status: 500, body: {} };
+        if (args.includes('badjson'))
+            return { kind: 'raw', status: 200, body: 'not json', contentType: 'application/json' };
+        if (args.includes('nonzero-exit')) {
+            // stdout is syntactically valid JSON that WOULD be accepted if execJson
+            // ignored exitCode — the assertion below only passes because the
+            // nonzero exitCode is honored and this payload is discarded.
+            const poisoned = JSON.stringify({ counts: { 'nonzero-exit': 7 } });
+            return { kind: 'raw', status: 200, body: JSON.stringify({ ok: true, exitCode: 1, stdout: poisoned, stderr: 'boom' }), contentType: 'application/json' };
+        }
+        return { kind: 'json', status: 500, body: {} };
+    });
+    t.after(() => server.close());
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    assert.equal(await source.getNode('http500'), null);
+    assert.deepEqual(await source.listNodes(), []);
+    assert.deepEqual(await source.askCountsForView('badjson'), {});
+    assert.deepEqual(await source.askCountsForView('nonzero-exit'), {});
+});
+test('malformed success JSON (exit 0, wrong shape) degrades cleanly instead of returning a shape a consumer would crash on', async (t) => {
+    const server = await startMockCrtrServer((args) => {
+        if (args[3] === 'show') {
+            const id = args[4];
+            if (id === 'empty-object')
+                return { kind: 'json', body: {} };
+            if (id === 'null-node')
+                return { kind: 'json', body: { node: null, reports: [], managers: [] } };
+            if (id === 'reports-not-array')
+                return { kind: 'json', body: { node: meta('a'), reports: 'nope', managers: [] } };
+            if (id === 'node-missing-id')
+                return { kind: 'json', body: { node: { name: 'a' }, reports: [], managers: [] } };
+            return { kind: 'json', body: showResponse(id) };
+        }
+        if (args[3] === 'list') {
+            return { kind: 'json', body: { nodes: 'not-an-array' } };
+        }
+        if (args[2] === 'attention') {
+            return { kind: 'json', body: { counts: 'not-an-object' } };
+        }
+        return { kind: 'json', status: 500, body: {} };
+    });
+    t.after(() => server.close());
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    // `{}` — no `node` key at all. Without shape validation this would cast
+    // through as a truthy "valid" RemoteShowResponse (an object with `.node ===
+    // undefined`), and a consumer like `node inspect show`'s remote passthrough
+    // branch (src/commands/node.ts) treats any non-null return as found, then
+    // its renderer dereferences fields on `undefined` and throws.
+    assert.equal(await source.getNode('empty-object'), null, 'a shape with no node key must degrade to null, not a malformed object');
+    assert.equal(await source.rawShow('empty-object'), null);
+    assert.equal(await source.getNode('null-node'), null, '`node: null` must degrade to null');
+    assert.deepEqual(await source.subscriptionsOf('reports-not-array'), [], 'a non-array reports field must degrade to []');
+    assert.equal(await source.getNode('node-missing-id'), null, 'a node object missing node_id must degrade to null');
+    // `listNodes()` with a non-array `nodes` field must degrade to [], never
+    // throw or return the malformed value.
+    assert.deepEqual(await source.listNodes(), []);
+    // `askCountsForView()` with a non-object `counts` field must degrade to {}.
+    assert.deepEqual(await source.askCountsForView('root'), {});
+});
+function fullNodeRow(id, over = {}) {
+    return {
+        node_id: id,
+        name: id,
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        cwd: '/tmp/work',
+        host_kind: null,
+        profile_id: null,
+        parent: null,
+        created: new Date().toISOString(),
+        intent: null,
+        pi_pid: null,
+        pi_pid_identity: null,
+        window: null,
+        tmux_session: null,
+        pane: null,
+        ...over,
+    };
+}
+test('listNodes drops malformed row elements (null, missing required fields) instead of casting them through', async (t) => {
+    const server = await startMockCrtrServer((args) => {
+        if (args[3] === 'list') {
+            return {
+                kind: 'json',
+                body: { nodes: [null, { node_id: 'partial-only' }, fullNodeRow('good')] },
+            };
+        }
+        return { kind: 'json', status: 500, body: {} };
+    });
+    t.after(() => server.close());
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    const nodes = await source.listNodes();
+    assert.deepEqual(nodes.map((n) => n.node_id), ['good'], 'a null element and a row missing required string fields must both be dropped, leaving only the well-formed row');
+});
+test('isValidShowResponse rejects a payload missing/malformed on artifacts/pending_triggers/paths/follow_up (Phase 3 review Minor 2)', async (t) => {
+    const server = await startMockCrtrServer((args) => {
+        if (args[3] !== 'show')
+            return { kind: 'json', status: 500, body: {} };
+        const id = args[4];
+        const valid = showResponse(id);
+        switch (id) {
+            case 'missing-artifacts': {
+                const { artifacts: _artifacts, ...rest } = valid;
+                return { kind: 'json', body: rest };
+            }
+            case 'artifacts-wrong-type':
+                return { kind: 'json', body: { ...valid, artifacts: { report: '0', doc: 0, roadmap: 0 } } };
+            case 'missing-pending-triggers': {
+                const { pending_triggers: _pt, ...rest } = valid;
+                return { kind: 'json', body: rest };
+            }
+            case 'paths-session-file-undefined': {
+                const { session_file: _sf, ...restPaths } = valid.paths;
+                return { kind: 'json', body: { ...valid, paths: restPaths } };
+            }
+            case 'paths-session-file-null':
+                return { kind: 'json', body: { ...valid, paths: { ...valid.paths, session_file: null } } };
+            case 'missing-follow-up': {
+                const { follow_up: _fu, ...rest } = valid;
+                return { kind: 'json', body: rest };
+            }
+            case 'fully-valid':
+                return { kind: 'json', body: valid };
+            default:
+                return { kind: 'json', status: 500, body: {} };
+        }
+    });
+    t.after(() => server.close());
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    assert.equal(await source.rawShow('missing-artifacts'), null, 'a payload with no artifacts key must degrade to null');
+    assert.equal(await source.rawShow('artifacts-wrong-type'), null, 'artifacts.report as a string must degrade to null');
+    assert.equal(await source.rawShow('missing-pending-triggers'), null, 'a payload with no pending_triggers key must degrade to null');
+    assert.equal(await source.rawShow('paths-session-file-undefined'), null, 'paths.session_file entirely absent (not null) must degrade to null');
+    assert.notEqual(await source.rawShow('paths-session-file-null'), null, 'paths.session_file explicitly null (no session yet) must be ACCEPTED');
+    assert.equal(await source.rawShow('missing-follow-up'), null, 'a payload with no follow_up key must degrade to null');
+    assert.notEqual(await source.rawShow('fully-valid'), null, 'the tightened validator must not false-reject the real, fully-valid shape');
+});
+test('a malformed row element does not crash the browse snapshot path (dashboardRowsAllFromSource / renderForestFromSource)', async (t) => {
+    const server = await startMockCrtrServer((args) => {
+        if (args[3] === 'list') {
+            return { kind: 'json', body: { nodes: [null, { node_id: 'partial-only' }, fullNodeRow('good')] } };
+        }
+        if (args[3] === 'show') {
+            return { kind: 'json', body: showResponse('good') };
+        }
+        return { kind: 'json', status: 500, body: {} };
+    });
+    t.after(() => server.close());
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    // `browse/app.ts`'s `rebuildSnapshot` calls `listNodes()` and dereferences
+    // `n.parent`/`n.kind`/`n.node_id` on every row, and `dashboardRowsAllFromSource`
+    // reaches the same shape via `dashboardRowFromNodeRow` — both rely on
+    // `listNodes()` having already dropped the malformed `null` element.
+    const rows = await dashboardRowsAllFromSource(source);
+    assert.deepEqual(rows.map((r) => r.node_id), ['good']);
+    const forest = await renderForestFromSource(source);
+    assert.ok(forest.includes('good'));
+});
+test('cache coalescing: two getNode calls inside the TTL hit the server once; invalidate() busts it', async (t) => {
+    let hitCount = 0;
+    const server = await startMockCrtrServer((args) => {
+        if (args[3] === 'show') {
+            hitCount += 1;
+            return { kind: 'json', body: showResponse(args[4]) };
+        }
+        return { kind: 'json', status: 500, body: {} };
+    });
+    t.after(() => server.close());
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    await source.getNode('a');
+    await source.getNode('a');
+    assert.equal(hitCount, 1);
+    source.invalidate();
+    await source.getNode('a');
+    assert.equal(hitCount, 2);
+});

package/dist/core/canvas/__tests__/remote-event-stream.test.d.ts

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

package/dist/core/canvas/__tests__/remote-event-stream.test.js

@@ -0,0 +1,144 @@
+// remote-event-stream.test.ts — `RemoteEventStream` (`../remote-event-stream.ts`),
+// a manual SSE client over `/__crtr/events`. Covers the wire parse (only
+// known `kind`s fire listeners; comments/pings/unknown kinds are silently
+// ignored) and that `stop()` actually halts the reconnect loop rather than
+// leaving it retrying forever in the background.
+//
+// Reconnect/backoff timing uses an INJECTABLE backoff (`RemoteEventStreamOptions`)
+// so these tests run against a small, fast backoff window instead of the
+// production 1s→30s one, and every wait is a condition-poll on an observed
+// request/event count (`waitFor`) rather than a fixed wall-clock sleep —
+// less flaky under scheduler variance, and fast.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { RemoteEventStream } from '../remote-event-stream.js';
+function startSseServer(onRequest) {
+    return new Promise((resolve) => {
+        let hits = 0;
+        const requests = [];
+        const server = createServer((req, res) => {
+            hits += 1;
+            requests.push({ method: req.method, url: req.url ?? '', headers: req.headers });
+            onRequest(res, req);
+        });
+        server.listen(0, '127.0.0.1', () => {
+            const addr = server.address();
+            const port = typeof addr === 'object' && addr !== null ? addr.port : 0;
+            resolve({
+                url: `http://127.0.0.1:${port}`,
+                hitCount: () => hits,
+                requests,
+                close: () => new Promise((res) => server.close(() => res())),
+            });
+        });
+    });
+}
+/** Poll `predicate` until it's true, or throw after `timeoutMs` — used in
+ *  place of a fixed sleep so tests assert on the OBSERVED condition (a
+ *  request landed, an event fired) rather than a guessed timing window. */
+async function waitFor(predicate, timeoutMs = 2000, intervalMs = 5) {
+    const deadline = Date.now() + timeoutMs;
+    while (!predicate()) {
+        if (Date.now() > deadline)
+            throw new Error(`waitFor: condition not met within ${timeoutMs}ms`);
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+}
+test('a listener fires once per known-kind SSE event, and never for a ping or an unknown kind', async () => {
+    const server = await startSseServer((res) => {
+        res.writeHead(200, { 'content-type': 'text/event-stream' });
+        res.write(': connected\n\n');
+        res.write('data: {"kind":"nodes"}\n\n');
+        res.write(': ping\n\n');
+        res.write('data: {"kind":"bogus"}\n\n');
+        res.end();
+    });
+    const stream = new RemoteEventStream(server.url, 'tok');
+    const seen = [];
+    stream.subscribe((kind) => seen.push(kind));
+    stream.start();
+    await waitFor(() => seen.length > 0);
+    stream.stop();
+    assert.deepEqual(seen, ['nodes']);
+    await server.close();
+});
+test('the SSE connection carries the token ONLY in the Authorization header — not in the URL or any other header', async () => {
+    const server = await startSseServer((res) => {
+        res.writeHead(200, { 'content-type': 'text/event-stream' });
+        res.end();
+    });
+    // A token that cannot collide with a hostname/port (unlike 'tok', which is a
+    // substring of numeric-looking noise) so a pass here can't be a coincidence —
+    // no header, including Host, is permitted to carry it.
+    const token = 'secret-sse-token-value';
+    const stream = new RemoteEventStream(server.url, token);
+    stream.start();
+    await waitFor(() => server.requests.length > 0);
+    stream.stop();
+    assert.equal(server.requests.length, 1);
+    const req = server.requests[0];
+    assert.equal(req.method, 'GET');
+    assert.equal(req.url, '/__crtr/events');
+    assert.equal(req.headers['authorization'], `Bearer ${token}`);
+    for (const [k, v] of Object.entries(req.headers)) {
+        if (k.toLowerCase() === 'authorization')
+            continue;
+        assert.ok(!String(v).includes(token), `header ${k} must not carry the token`);
+    }
+    assert.ok(!req.url.includes(token));
+    await server.close();
+});
+test('stop() cancels a pending reconnect timer — no zombie loop survives a stop()+start() cycle', async () => {
+    const server = await startSseServer((res) => {
+        res.writeHead(500);
+        res.end();
+    });
+    // A small injected backoff (200ms, not production's 1s) — the test asserts
+    // the SAME relative-timing invariant (a stopped loop's dangling reconnect
+    // timer must not fire) but the deliberate gap below (half the backoff)
+    // between the stale deadline and the new deadline is kept proportionally
+    // wide enough that ordinary event-loop/scheduler jitter can't flip it.
+    const BACKOFF = 200;
+    const stream = new RemoteEventStream(server.url, 'tok', { initialBackoffMs: BACKOFF });
+    stream.start();
+    // t≈0: first request fires+fails, backoff(BACKOFF) scheduled → stale deadline ≈ BACKOFF.
+    await waitFor(() => server.hitCount() >= 1);
+    assert.equal(server.hitCount(), 1);
+    // Deliberate mid-backoff gap (half the window) before stop()+start(), so the
+    // stale deadline (hit1 + BACKOFF) and the new loop's own deadline
+    // (hit2 + BACKOFF) land ~BACKOFF/2 apart — the window this test inspects.
+    await new Promise((r) => setTimeout(r, BACKOFF / 2));
+    stream.stop();
+    stream.start();
+    await waitFor(() => server.hitCount() >= 2);
+    assert.equal(server.hitCount(), 2, 'restart fires its own immediate request');
+    // Wait past the STALE timer's deadline (~BACKOFF from the first request) but
+    // well before the NEW loop's own deadline (~BACKOFF from the second,
+    // later, request). A dangling old-loop timer (bug) would add a 3rd hit in
+    // this window; a cleared one (fixed) leaves it at 2.
+    await new Promise((r) => setTimeout(r, BACKOFF * 0.7));
+    assert.equal(server.hitCount(), 2, "no zombie request from the stopped loop's dangling timer");
+    stream.stop();
+    await server.close();
+});
+test('stop() halts the reconnect loop — no further requests after it is called', async () => {
+    const server = await startSseServer((res) => {
+        // Every connection is refused immediately (no SSE headers, just a close)
+        // so the client's loop falls into its backoff-and-retry path.
+        res.writeHead(500);
+        res.end();
+    });
+    const BACKOFF = 20;
+    const stream = new RemoteEventStream(server.url, 'tok', { initialBackoffMs: BACKOFF });
+    stream.start();
+    await waitFor(() => server.hitCount() >= 1);
+    const hitsAtStop = server.hitCount();
+    stream.stop();
+    // The reconnect backoff is BACKOFF ms; wait well past it and confirm no new
+    // connection was attempted — proves the loop actually stopped rather than
+    // continuing to retry in the background after stop() returned.
+    await new Promise((r) => setTimeout(r, BACKOFF * 5));
+    assert.equal(server.hitCount(), hitsAtStop);
+    await server.close();
+});