@crouton-kit/crouter 0.3.28 → 0.3.29

package/dist/clients/attach/view-socket.js

@@ -18,10 +18,15 @@
 // `CLIENT_READ_CAPS`; a broker that somehow sends an oversized frame surfaces as
 // a clean error+exit, not a crash.
 import { EventEmitter } from 'node:events';
+import { randomUUID } from 'node:crypto';
 import { createConnection } from 'node:net';
 import { join } from 'node:path';
 import { nodeDir } from '../../core/canvas/paths.js';
 import { CLIENT_READ_CAPS, encodeFrame, FrameDecoder, FrameOverflowError, } from '../../core/runtime/broker-protocol.js';
+/** How long {@link ViewSocketClient.request} waits for the correlated reply before
+ *  rejecting — bounds a pending picker fetch if the broker drops the request
+ *  (it should always reply with `data` or a correlated `error`). */
+const REQUEST_TIMEOUT_MS = 10_000;
 /** Surfaced when the node has no reachable broker at connect time (no socket
  *  file, or a stale socket with nothing listening). The command catches this to
  *  exit non-zero with a focus/revive hint. */
@@ -51,10 +56,48 @@ export class ViewSocketClient extends EventEmitter {
     socket;
     decoder = new FrameDecoder(CLIENT_READ_CAPS);
     closeEmitted = false;
+    /** In-flight correlated read-ops, keyed by the `id` minted in {@link request}.
+     *  Resolved by the matching `data` frame / rejected by the matching `error`
+     *  frame in {@link onData}, the request's timeout, or socket teardown. */
+    pending = new Map();
     constructor(nodeId) {
         super();
         this.nodeId = nodeId;
     }
+    /** Issue a correlated read-op and resolve with the broker's `data` reply (or
+     *  reject on the correlated `error`, a timeout, or socket teardown). Mints the
+     *  `id`, sends `{...frame, id}`, and parks a resolver consumed by {@link onData}.
+     *  The reply is narrowed by the caller on its `kind`. */
+    request(frame) {
+        const id = randomUUID();
+        return new Promise((resolve, reject) => {
+            // Fail fast on a dead/absent socket rather than parking a promise that the
+            // reply will never reach (it would otherwise hang the full timeout). A
+            // post-`close` request lands here too — `rejectAllPending` already ran.
+            const sock = this.socket;
+            if (sock === undefined || sock.destroyed) {
+                reject(new Error(`cannot issue '${frame.type}': no live broker connection`));
+                return;
+            }
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`request '${frame.type}' timed out after ${REQUEST_TIMEOUT_MS}ms`));
+            }, REQUEST_TIMEOUT_MS);
+            if (typeof timer.unref === 'function')
+                timer.unref();
+            this.pending.set(id, { resolve, reject, timer });
+            this.send({ ...frame, id });
+        });
+    }
+    /** Reject + clear every in-flight request (socket gone / decode error) so a
+     *  picker fetch never hangs past the connection it rode on. */
+    rejectAllPending(reason) {
+        for (const { reject, timer } of this.pending.values()) {
+            clearTimeout(timer);
+            reject(new Error(reason));
+        }
+        this.pending.clear();
+    }
     /** The broker binds `join(nodeDir(id), 'view.sock')` — resolve it the same way. */
     get socketPath() {
         return join(nodeDir(this.nodeId), 'view.sock');
@@ -138,12 +181,37 @@ export class ViewSocketClient extends EventEmitter {
             const msg = err instanceof FrameOverflowError
                 ? `broker sent an oversized frame (${err.message}) — disconnecting`
                 : `failed to decode a broker frame: ${String(err)}`;
+            this.rejectAllPending(msg);
             this.emitError(new Error(msg));
             this.destroy();
             return;
         }
         for (const raw of frames) {
-            this.emit('frame', raw);
+            const frame = raw;
+            // Correlated replies (read-ops + dequeue) are consumed by the pending-by-id
+            // resolver, NOT re-emitted as a generic 'frame' (the attach frame router
+            // would otherwise treat a `data` frame as an AgentSessionEvent). A `data`
+            // frame is ALWAYS a reply, so it is swallowed unconditionally — even a late
+            // post-timeout one (no pending entry) is dropped, never leaked to the
+            // router. An `error` is correlated only when its `id` matches an in-flight
+            // request; an uncorrelated error still flows through.
+            if (frame.type === 'data') {
+                const entry = typeof frame.id === 'string' ? this.pending.get(frame.id) : undefined;
+                if (entry) {
+                    this.pending.delete(frame.id);
+                    clearTimeout(entry.timer);
+                    entry.resolve(frame);
+                }
+                continue;
+            }
+            if (frame.type === 'error' && typeof frame.id === 'string' && this.pending.has(frame.id)) {
+                const entry = this.pending.get(frame.id);
+                this.pending.delete(frame.id);
+                clearTimeout(entry.timer);
+                entry.reject(new Error(frame.message || `request failed: ${frame.code}`));
+                continue;
+            }
+            this.emit('frame', frame);
         }
     }
     onError(err) {
@@ -159,6 +227,7 @@ export class ViewSocketClient extends EventEmitter {
         if (this.closeEmitted)
             return;
         this.closeEmitted = true;
+        this.rejectAllPending('broker connection closed');
         this.emit('close');
     }
     destroy() {

package/dist/clients/web/dev-server.d.ts

@@ -0,0 +1,7 @@
+import type { Server as HttpServer } from 'node:http';
+import type { ViteDevServer } from 'vite';
+/** Create a Vite dev server in middleware mode, HMR bound to `httpServer`.
+ *  Mirrors the old `view serve` resolve setup so the shell's bare imports
+ *  (react, the `@crouton-kit/crouter/web` self-subpath) resolve from the
+ *  generated/shell root. Lazily imports vite so the shipped path never loads it. */
+export declare function createDevServer(httpServer: HttpServer): Promise<ViteDevServer>;

package/dist/clients/web/dev-server.js

@@ -0,0 +1,59 @@
+// dev-server.ts — `crtr web serve --dev` Vite middleware mode.
+//
+// The shipped server serves a prebuilt static shell bundle from dist/web-client/
+// (§11). In --dev a contributor iterating on the shell or a builtin view gets
+// HMR instead: a Vite dev server in MIDDLEWARE mode mounted on the SAME HTTP
+// server as the bridge + WS relay. This is the one place Vite runs at runtime —
+// the mainstream "Vite middleware in dev, static dist in prod" split.
+//
+// The bridge (POST /__crtr/source), the SSE lane (GET /__crtr/events) and the
+// WS relay are owned by server.ts and checked BEFORE Vite's middlewares; this
+// module only supplies the asset/HMR middleware. Vite's HMR WebSocket shares
+// the HTTP server (server.hmr.server) — server.ts's upgrade handler routes
+// `/node/<id>` to the broker relay and leaves every other upgrade for Vite.
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const HERE = dirname(fileURLToPath(import.meta.url));
+/** The shell SPA Vite root — the in-tree shell project (`src/clients/web/web-client/`).
+ *  --dev is a from-source contributor loop, so this resolves against the source
+ *  tree (HERE is `dist/clients/web` when built, `src/clients/web` under tsx);
+ *  walk to the package root and into src. */
+function resolveShellRoot(packageRoot) {
+    return join(packageRoot, 'src', 'clients', 'web', 'web-client');
+}
+/** Create a Vite dev server in middleware mode, HMR bound to `httpServer`.
+ *  Mirrors the old `view serve` resolve setup so the shell's bare imports
+ *  (react, the `@crouton-kit/crouter/web` self-subpath) resolve from the
+ *  generated/shell root. Lazily imports vite so the shipped path never loads it. */
+export async function createDevServer(httpServer) {
+    const packageRoot = resolve(HERE, '../../..');
+    const nodeModules = join(packageRoot, 'node_modules');
+    const shellRoot = resolveShellRoot(packageRoot);
+    const { createServer } = await import('vite');
+    const react = (await import('@vitejs/plugin-react')).default;
+    const tailwindcss = (await import('@tailwindcss/vite')).default;
+    return createServer({
+        configFile: false,
+        root: shellRoot,
+        plugins: [react(), tailwindcss()],
+        appType: 'spa',
+        resolve: {
+            alias: {
+                react: join(nodeModules, 'react'),
+                'react-dom': join(nodeModules, 'react-dom'),
+                // The crtr web runtime is a self-subpath of crouter's own package;
+                // pin it to the built barrel so the shell can import it from any root.
+                '@crouton-kit/crouter/web': join(packageRoot, 'dist', 'web', 'index.js'),
+            },
+            dedupe: ['react', 'react-dom'],
+        },
+        server: {
+            middlewareMode: true,
+            // Share our HTTP server for HMR; server.ts's upgrade handler hands every
+            // non-`/node/<id>` upgrade to Vite (the vite-hmr WebSocket).
+            hmr: { server: httpServer },
+            fs: { allow: [shellRoot, packageRoot] },
+        },
+        logLevel: 'warn',
+    });
+}

package/dist/clients/web/events.d.ts

@@ -0,0 +1,14 @@
+import type { ServerResponse } from 'node:http';
+export type ChangeKind = 'nodes' | 'inbox';
+export interface EventHub {
+    /** Register an SSE client: writes the event-stream headers, streams events
+     *  until the connection closes, and self-removes on close. */
+    addClient: (res: ServerResponse) => void;
+    /** Tear down watchers + heartbeat and end all open streams. */
+    close: () => void;
+}
+/** Start the change-event hub: open the two fs watchers once, fan their
+ *  debounced invalidations out to every connected SSE client. Watchers run for
+ *  the server's lifetime (cheap — two inotify/FSEvents registrations), not
+ *  per-client, so N browsers share one watch. */
+export declare function startEventHub(): EventHub;

package/dist/clients/web/events.js

@@ -0,0 +1,151 @@
+// events.ts — the `crtr web` realtime push lane (the §7 SSE seam, built for v1).
+//
+// ONE server-sent-events stream, `GET /__crtr/events`, that carries CHANGE
+// INVALIDATIONS — never data. The shell / its ViewPanes subscribe and, on an
+// event, re-pull through their existing Sources (the bridge) instead of waiting
+// on a fixed poll tick. SSE carries "something in this class changed"; the
+// consumer decides what to re-read. This keeps the event vocabulary tiny and
+// generic and the contract unchanged (a ViewPane still just runs `refresh`).
+//
+// Event vocabulary (deliberately minimal): { kind: 'nodes' | 'inbox', ts }.
+//   - 'nodes' — the node graph changed (topology, status/intent transitions,
+//     naming). Source: canvas.db (+ its WAL sidecar) mtime. Every transition()
+//     and canvas mutation writes the WAL, so a watch on the home dir's
+//     `canvas.db*` files detects all of them with one cheap watcher.
+//   - 'inbox' — a node's inbox.jsonl gained a message. Source: a recursive watch
+//     on the nodes/ tree, filtered to `inbox.jsonl` writes.
+//
+// WHY these sources (the §7 seam left the event source open): they are the
+// cheapest things that detect node-graph + inbox changes without a daemon hook
+// or a db trigger — pure fs.watch on the two on-disk authorities (canvas.db for
+// the graph, inbox.jsonl appends for messages). No polling, no canvas.db reads.
+import { watch } from 'node:fs';
+import { crtrHome, nodesRoot, ensureHome } from '../../core/canvas/paths.js';
+/** Coalesce a burst of fs events into one emission per kind. WAL writes and
+ *  inbox appends arrive in clusters (a single transition can touch -wal/-shm);
+ *  a short trailing debounce collapses each cluster into a single invalidation,
+ *  which is all a re-pull consumer needs. */
+const DEBOUNCE_MS = 150;
+/** SSE keepalive comment cadence — keeps proxies/clients from idling the stream
+ *  shut. A bare `:` comment line is ignored by EventSource. */
+const HEARTBEAT_MS = 25_000;
+/** Start the change-event hub: open the two fs watchers once, fan their
+ *  debounced invalidations out to every connected SSE client. Watchers run for
+ *  the server's lifetime (cheap — two inotify/FSEvents registrations), not
+ *  per-client, so N browsers share one watch. */
+export function startEventHub() {
+    ensureHome();
+    const clients = new Set();
+    const watchers = [];
+    const timers = new Map();
+    const broadcast = (kind) => {
+        const line = `data: ${JSON.stringify({ kind, ts: Date.now() })}\n\n`;
+        for (const res of clients) {
+            try {
+                res.write(line);
+            }
+            catch {
+                /* a dead stream is reaped by its own 'close' handler */
+            }
+        }
+    };
+    // Debounce per kind: an fs event arms a trailing timer; a fresh event within
+    // the window resets it, so a write cluster emits exactly once.
+    const emit = (kind) => {
+        const existing = timers.get(kind);
+        if (existing !== undefined)
+            clearTimeout(existing);
+        timers.set(kind, setTimeout(() => {
+            timers.delete(kind);
+            broadcast(kind);
+        }, DEBOUNCE_MS));
+    };
+    // Watcher 1 — the canvas home dir (non-recursive). canvas.db lives in WAL
+    // mode, so graph writes land in canvas.db-wal and checkpoints in canvas.db;
+    // watching the dir catches every `canvas.db*` sidecar touch → 'nodes'.
+    try {
+        const homeWatcher = watch(crtrHome(), (_event, filename) => {
+            if (filename !== null && filename.startsWith('canvas.db'))
+                emit('nodes');
+        });
+        homeWatcher.on('error', () => {
+            /* watch dropped (dir replaced) — non-fatal; the poll cadence still backs us */
+        });
+        watchers.push(homeWatcher);
+    }
+    catch {
+        /* fs.watch unavailable on this platform — degrade to poll-only (no SSE) */
+    }
+    // Watcher 2 — the nodes/ tree (recursive). An inbox.jsonl append is a message
+    // landing; a meta.json write is a graph/identity change (naming, polymorph).
+    // Recursive fs.watch is supported on macOS/Windows always and Linux ≥ v20.
+    try {
+        const nodesWatcher = watch(nodesRoot(), { recursive: true }, (_event, filename) => {
+            if (filename === null)
+                return;
+            if (filename.endsWith('inbox.jsonl'))
+                emit('inbox');
+            else if (filename.endsWith('meta.json'))
+                emit('nodes');
+        });
+        nodesWatcher.on('error', () => {
+            /* recursive watch refused/dropped — non-fatal */
+        });
+        watchers.push(nodesWatcher);
+    }
+    catch {
+        /* recursive watch unsupported — inbox push degrades to poll-only */
+    }
+    const heartbeat = setInterval(() => {
+        for (const res of clients) {
+            try {
+                res.write(': ping\n\n');
+            }
+            catch {
+                /* reaped by its 'close' handler */
+            }
+        }
+    }, HEARTBEAT_MS);
+    heartbeat.unref();
+    return {
+        addClient(res) {
+            res.writeHead(200, {
+                'content-type': 'text/event-stream; charset=utf-8',
+                'cache-control': 'no-cache, no-transform',
+                connection: 'keep-alive',
+                // The browser EventSource is same-origin here; no CORS header needed.
+            });
+            // An initial comment flushes headers and confirms the stream is open.
+            res.write(': connected\n\n');
+            clients.add(res);
+            const drop = () => {
+                clients.delete(res);
+            };
+            res.on('close', drop);
+            res.on('error', drop);
+        },
+        close() {
+            clearInterval(heartbeat);
+            for (const t of timers.values())
+                clearTimeout(t);
+            timers.clear();
+            for (const w of watchers) {
+                try {
+                    w.close();
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            for (const res of clients) {
+                try {
+                    res.end();
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            clients.clear();
+        },
+    };
+}

package/dist/clients/web/server.d.ts

@@ -0,0 +1,18 @@
+export interface WebServerOptions {
+    port: number;
+    host?: string;
+    /** --dev: mount a Vite dev server (middleware mode, HMR) for asset serving
+     *  instead of the static dist/web-client/ bundle. The bridge + SSE + WS relay
+     *  are identical in both modes. */
+    dev?: boolean;
+}
+export interface RunningWebServer {
+    url: string;
+    port: number;
+    clientDir: string;
+    close: () => Promise<void>;
+}
+/** Build + start the unified web server. Binds 127.0.0.1 only (remote access is
+ *  out of scope — §9). Resolves once the server is listening. Async because
+ *  --dev awaits a Vite middleware server before listening. */
+export declare function startWebServer(opts: WebServerOptions): Promise<RunningWebServer>;