@crouton-kit/crouter 0.3.65 → 0.3.67

package/dist/clients/attach/__tests__/attach-remote-readonly.test.js

@@ -0,0 +1,191 @@
+// attach-remote-readonly.test.ts — Phase 3 review Major 1: a REMOTE attach
+// (`crtr surface attach --canvas <name>`) must be a strictly VIEW-ONLY
+// surface. Three defenses are proven independently here:
+//
+//   A. slash-commands.ts's REMOTE_SAFE_BUILTIN_NAMES gate — a remote attach
+//      never even dispatches a mutating builtin slash command.
+//   B. input-controller.ts's central `emitCommand` choke point — even if a
+//      caller somehow got past A, the REAL InputController (constructed
+//      against fakes, not stubbed out) never lets a drive frame reach
+//      `hooks.onCommand`, for every input path (submit, `!bash`, Esc-abort,
+//      and every direct keybinding).
+//   C. attach-cmd.ts's `resolveHelloRole` — the hello handshake always
+//      claims 'observer' for a remote attach, regardless of `--observer`.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { dispatchSlashCommand } from '../slash-commands.js';
+import { InputController } from '../input-controller.js';
+import { resolveHelloRole } from '../attach-cmd.js';
+// ---------------------------------------------------------------------------
+// Half A — slash-command gate
+// ---------------------------------------------------------------------------
+function fakeSlashContext(remote, nodeId) {
+    const notices = [];
+    const sent = [];
+    const ctx = {
+        send: (frame) => sent.push(frame),
+        notify: (m) => notices.push(m),
+        cwd: '/tmp/does-not-matter',
+        nodeId,
+        remote,
+    };
+    return { ctx, notices, sent };
+}
+const MUTATING_BUILTINS = [
+    '/new', '/compact', '/name test', '/model', '/resume', '/fork', '/tree',
+    '/settings', '/share', '/clone', '/import', '/reload', '/scoped-models',
+    '/login', '/logout', '/export',
+];
+test('dispatchSlashCommand blocks every mutating/wrong-host builtin in remote mode, never sending a frame', () => {
+    const { ctx, notices, sent } = fakeSlashContext(true, 'a');
+    for (const cmd of MUTATING_BUILTINS) {
+        notices.length = 0;
+        const handled = dispatchSlashCommand(cmd, ctx);
+        assert.equal(handled, true, `${cmd} must be handled (blocked, never forwarded to the engine as a prompt)`);
+        assert.equal(notices.length, 1, `${cmd} must notify exactly once, got: ${JSON.stringify(notices)}`);
+        assert.match(notices[0], /not available for a remote attach/, `${cmd} must produce the remote-block notice, got: ${notices[0]}`);
+    }
+    assert.equal(sent.length, 0, 'no command frame must ever reach ctx.send for a blocked remote builtin');
+});
+test('the same builtins dispatch normally in local mode (remote unaffected proof)', () => {
+    const { ctx, sent } = fakeSlashContext(false, '');
+    assert.equal(dispatchSlashCommand('/name a-new-name', ctx), true);
+    assert.equal(dispatchSlashCommand('/new', ctx), true);
+    const types = sent.map((f) => f.type);
+    assert.ok(types.includes('set_session_name'), `expected set_session_name in local mode, got ${JSON.stringify(types)}`);
+    assert.ok(types.includes('new_session'), `expected new_session in local mode, got ${JSON.stringify(types)}`);
+});
+test('/copy /session /changelog /hotkeys /quit remain reachable in remote mode (not blocked by the gate)', () => {
+    const { ctx, notices } = fakeSlashContext(true, 'a');
+    notices.length = 0;
+    ctx.state = { model: 'test-model' };
+    dispatchSlashCommand('/session', ctx);
+    assert.equal(notices.length, 1);
+    assert.ok(!/not available for a remote attach/.test(notices[0]), `/session must not hit the remote-block notice, got: ${notices[0]}`);
+    notices.length = 0;
+    dispatchSlashCommand('/changelog', ctx);
+    assert.equal(notices.length, 1);
+    assert.ok(!/not available for a remote attach/.test(notices[0]));
+    notices.length = 0;
+    dispatchSlashCommand('/hotkeys', ctx);
+    assert.equal(notices.length, 1);
+    assert.ok(!/not available for a remote attach/.test(notices[0]));
+    notices.length = 0;
+    let copied = false;
+    ctx.onCopy = () => { copied = true; };
+    dispatchSlashCommand('/copy', ctx);
+    assert.equal(copied, true, '/copy must reach its onCopy hook in remote mode');
+    notices.length = 0;
+    let quit = false;
+    ctx.onQuit = () => { quit = true; };
+    dispatchSlashCommand('/quit', ctx);
+    assert.equal(quit, true, '/quit must reach its onQuit hook in remote mode');
+});
+// ---------------------------------------------------------------------------
+// Half B — InputController's central emitCommand gate, against a REAL
+// InputController built from minimal fakes.
+// ---------------------------------------------------------------------------
+function fakeEditor() {
+    const actions = new Map();
+    let text = '';
+    const history = [];
+    const obj = {
+        onSubmit: undefined,
+        onEscape: undefined,
+        onPasteImage: undefined,
+        onAction: (name, cb) => { actions.set(name, cb); },
+        getText: () => text,
+        setText: (t) => { text = t; },
+        addToHistory: (t) => { history.push(t); },
+        insertTextAtCursor: (t) => { text += t; },
+    };
+    return { obj, actions, setText: (t) => { text = t; } };
+}
+function fakeTui() {
+    return {
+        requestRender: () => { },
+        setFocus: () => { },
+        showOverlay: () => ({ hide: () => { } }),
+        start: () => { },
+        stop: () => { },
+    };
+}
+function buildController(remote) {
+    const sent = [];
+    const notices = [];
+    const editor = fakeEditor();
+    const tui = fakeTui();
+    const ic = new InputController(tui, editor.obj, {}, {
+        onCommand: (f) => sent.push(f),
+        onDialogResponse: () => { },
+        onNotice: (m) => notices.push(m),
+        remote,
+    });
+    return { ic, editor, sent, notices };
+}
+test('InputController never emits a drive frame to onCommand when remote is true — every input path', () => {
+    const { ic, editor, sent, notices } = buildController(true);
+    // 1. Text submission → would have been `prompt`.
+    editor.setText('');
+    editor.obj.onSubmit('hello');
+    assert.equal(sent.length, 0);
+    // 2. `!` bash → would have been `bash`.
+    editor.setText('');
+    editor.obj.onSubmit('!ls');
+    assert.equal(sent.length, 0);
+    // 3. Esc while streaming → would have been `abort`.
+    ic.setState({ isStreaming: true });
+    editor.obj.onEscape();
+    assert.equal(sent.length, 0);
+    // 4. Direct keybindings → new_session, cycle_model×2, cycle_thinking.
+    editor.actions.get('app.session.new')();
+    editor.actions.get('app.model.cycleForward')();
+    editor.actions.get('app.model.cycleBackward')();
+    editor.actions.get('app.thinking.cycle')();
+    assert.equal(sent.length, 0, `remote InputController must never emit a frame, got: ${JSON.stringify(sent)}`);
+    // 5. The gate must have actually fired (proves the hooks weren't simply
+    // never wired — a real block happened).
+    assert.ok(notices.some((n) => /Read-only remote attach/.test(n)), `expected a "Read-only remote attach" notice, got: ${JSON.stringify(notices)}`);
+    // 6. `app.message.dequeue` → handleDequeue's own remote guard (a second
+    // frame type, `dequeue`, not covered by the direct-keybinding block above).
+    notices.length = 0;
+    editor.actions.get('app.message.dequeue')();
+    assert.equal(sent.length, 0, `remote dequeue must never emit a frame, got: ${JSON.stringify(sent)}`);
+    assert.ok(notices.some((n) => /Read-only remote attach/.test(n)), `expected a "Read-only remote attach" notice from dequeue, got: ${JSON.stringify(notices)}`);
+});
+test('InputController emits the SAME drive frames normally when remote is false (local unaffected proof)', () => {
+    const { ic, editor, sent, notices } = buildController(false);
+    editor.setText('');
+    editor.obj.onSubmit('hello');
+    editor.setText('');
+    editor.obj.onSubmit('!ls');
+    ic.setState({ isStreaming: true });
+    editor.obj.onEscape();
+    editor.actions.get('app.session.new')();
+    editor.actions.get('app.model.cycleForward')();
+    editor.actions.get('app.model.cycleBackward')();
+    editor.actions.get('app.thinking.cycle')();
+    // `app.message.dequeue` locally never hits the remote guard (it falls
+    // through to the "not available in this viewer" branch since the fake
+    // hooks supply no `onRequest`) — proves handleDequeue's remote check is
+    // remote-conditional, not an unconditional block.
+    notices.length = 0;
+    editor.actions.get('app.message.dequeue')();
+    assert.ok(!notices.some((n) => /Read-only remote attach/.test(n)), `local dequeue must not hit the read-only remote notice, got: ${JSON.stringify(notices)}`);
+    const types = sent.map((f) => f.type);
+    assert.ok(types.includes('prompt'), `expected prompt, got ${JSON.stringify(types)}`);
+    assert.ok(types.includes('bash'), `expected bash, got ${JSON.stringify(types)}`);
+    assert.ok(types.includes('abort'), `expected abort, got ${JSON.stringify(types)}`);
+    assert.ok(types.includes('new_session'), `expected new_session, got ${JSON.stringify(types)}`);
+    assert.equal(types.filter((t) => t === 'cycle_model').length, 2, `expected two cycle_model frames, got ${JSON.stringify(types)}`);
+    assert.ok(types.includes('cycle_thinking'), `expected cycle_thinking, got ${JSON.stringify(types)}`);
+});
+// ---------------------------------------------------------------------------
+// Half C — hello role
+// ---------------------------------------------------------------------------
+test('resolveHelloRole always claims observer for remote, regardless of --observer', () => {
+    assert.equal(resolveHelloRole(true, false), 'observer');
+    assert.equal(resolveHelloRole(true, true), 'observer');
+    assert.equal(resolveHelloRole(false, false), 'controller');
+    assert.equal(resolveHelloRole(false, true), 'observer');
+});

package/dist/clients/attach/__tests__/transport-relay.test.js

@@ -7,10 +7,14 @@
 // NOT-gone counterparts), and a non-101 handshake response (bad token) not
 // hanging connect().
 import assert from 'node:assert/strict';
-import test from 'node:test';
+import test, { after, before } from 'node:test';
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { WebSocketServer } from 'ws';
 import { RelayTransport } from '../transport-relay.js';
 import { BrokerUnavailableError } from '../transport.js';
+import { jobDir } from '../../../core/canvas/paths.js';
 /** Stand up a bare `ws` server on an ephemeral loopback port — the "relay" a
  *  RelayTransport dials. Records the Authorization header + accepted sockets
  *  of every connection so a test can assert on the wire, not just behavior. */
@@ -153,6 +157,39 @@ test('an immediate post-upgrade 1011 "no node <id>" close is still caught by a l
     transport.destroy();
     await new Promise((res) => wss.close(() => res()));
 });
+// --- Phase 3 review Major 3: RelayTransport must never write LOCAL fault
+// state keyed by a REMOTE node id (it is only ever constructed for --canvas
+// attach; there is no legitimate local use case). ---
+let faultTestHome;
+before(() => {
+    faultTestHome = mkdtempSync(join(tmpdir(), 'crtr-transport-relay-fault-'));
+    process.env['CRTR_HOME'] = faultTestHome;
+});
+after(() => {
+    rmSync(faultTestHome, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+test('RelayTransport never writes local fault state for the remote node id, even on a connect failure', async () => {
+    const nodeId = 'remote-fault-test-node';
+    const wss = new WebSocketServer({
+        port: 0,
+        verifyClient: (_info, cb) => cb(false, 401, 'unauthorized'),
+    });
+    await new Promise((resolve) => wss.once('listening', resolve));
+    const addr = wss.address();
+    const port = typeof addr === 'object' && addr !== null ? addr.port : 0;
+    const transport = new RelayTransport(nodeId, {
+        previewEndpoint: `http://127.0.0.1:${port}`,
+        relayToken: 'bad-token',
+    });
+    await new Promise((resolve) => {
+        transport.once('error', () => resolve());
+        transport.connect();
+    });
+    assert.equal(existsSync(join(jobDir(nodeId), 'fault')), false, 'a remote relay connect failure must never write a LOCAL fault file keyed by the remote node id');
+    transport.destroy();
+    await new Promise((res) => wss.close(() => res()));
+});
 test('a non-101 handshake response (401, bad token) rejects connect() with a clear error, not a hang', async () => {
     const wss = new WebSocketServer({
         port: 0,

package/dist/clients/attach/attach-cmd.d.ts

@@ -1,7 +1,35 @@
 import { CombinedAutocompleteProvider } from '@earendil-works/pi-tui';
 import type { BranchDef } from '../../core/command.js';
-import type { BrokerSnapshot } from '../../core/runtime/broker-protocol.js';
+import type { BrokerSnapshot, ClientRole } from '../../core/runtime/broker-protocol.js';
 import { type AttachPalette } from './config-load.js';
+export type Mode = 'normal' | 'spec' | 'plan';
+/** Resolve the mode badge's initial state. Remote never reads the local
+ *  mode-switch `current` file for `nodeId` — always starts 'normal'. */
+export declare function resolveInitialMode(cwd: string, nodeId: string, remote: boolean, readMode?: (cwd: string, nodeId: string) => Mode | undefined): Mode;
+/** Handle Alt+M's mode-cycle request. Remote no-ops entirely (returns `false`,
+ *  so the caller leaves `modeState`/the badge untouched) — there is no
+ *  remote-safe mode-switch protocol, and writing the local `request.json` for a
+ *  remote node id would target the wrong (or a colliding local) node. */
+export declare function requestModeSwitch(cwd: string, nodeId: string, remote: boolean, mode: Mode, writeRequest?: (cwd: string, nodeId: string, mode: Mode) => void): boolean;
+/** Tag/untag the attach pane with `nodeId` so the host-agnostic `nodeInPane()`
+ *  (Alt+C cycle/recycle/close/demote) resolves this broker-hosted node from its
+ *  viewer pane — LOCAL ONLY. Remote never sets `@crtr_node`, so local Alt+C
+ *  lifecycle can never resolve a remote id (or a local id it collides with)
+ *  from this pane. */
+export declare function tagAttachPane(remote: boolean, pane: string | undefined, nodeId: string, setOpt?: (pane: string, name: string, value: string) => void): void;
+export declare function untagAttachPane(remote: boolean, pane: string | undefined, setOpt?: (pane: string, name: string, value: string) => void): void;
+/** A clean detach reaps an empty LOCAL node (an AI-output-free shell the user
+ *  walked away from) — LOCAL ONLY. `reapIfEmpty` deletes a local canvas.db row;
+ *  remote never calls it, so a remote attach can never delete a local node on
+ *  detach even when the remote id collides with one. */
+export declare function reapOnDetach(remote: boolean, nodeId: string, reap?: (nodeId: string) => void): void;
+/** The hello handshake's initial role. A REMOTE attach (`--canvas`) is a
+ *  strictly VIEW-ONLY surface (Phase 3 review Major 1) — it must claim
+ *  observer regardless of `--observer`, never controller. Local attach keeps
+ *  today's exact behavior: controller unless `--observer`. Exported pure so
+ *  the "remote is always observer" contract is unit-testable without
+ *  constructing a real hello/socket. */
+export declare function resolveHelloRole(remote: boolean, observer: boolean): ClientRole;
 /** Derive the shell-mode cue from the editor contents. Leading whitespace is
  *  ignored so pasted commands and indented text still toggle correctly. */
 export declare function deriveBashMode(text: string): 0 | 1 | 2;
@@ -13,7 +41,7 @@ export declare function resolveEditorFrameStyles(bashMode: 0 | 1 | 2, thinkingLe
 export declare function buildAttachAutocompleteProvider(cwd: string, fdPath: string | null, commands?: ReadonlyArray<{
     name: string;
     description?: string;
-}>, createProvider?: (items: ReadonlyArray<{
+}>, remote?: boolean, createProvider?: (items: ReadonlyArray<{
     name: string;
     description?: string;
 }>, cwd: string, fdPath: string | null) => CombinedAutocompleteProvider): CombinedAutocompleteProvider;