@north-light/crouter 0.3.173 → 0.3.174

package/dist/clients/web/events.js

@@ -1,163 +0,0 @@
-// events.ts — the browser shell's realtime invalidation lane.
-//
-// One server-sent-events stream, `GET /__crtr/events`, carries change
-// invalidations, never data. On an event the shell re-reads through the REST
-// proxy rather than waiting for its fixed polling interval.
-//
-// 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: 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 for messages).
-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 listeners = new Set();
-    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 */
-            }
-        }
-        for (const listener of listeners) {
-            try {
-                listener(kind);
-            }
-            catch {
-                /* an in-process consumer's failure must never break SSE fan-out */
-            }
-        }
-    };
-    // 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);
-        },
-        subscribe(listener) {
-            listeners.add(listener);
-            return () => {
-                listeners.delete(listener);
-            };
-        },
-        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();
-            listeners.clear();
-        },
-    };
-}

package/dist/clients/web/push-engine.d.ts

@@ -1,44 +0,0 @@
-import type { NodeLifeStatus } from './web-client/shared/protocol.js';
-import type { PushLastSeenStore, PushRegistryStore, PushSubscriptionRecord } from './push-registry.js';
-export interface CanvasNodeRow {
-    node_id: string;
-    parent: string | null;
-    status: NodeLifeStatus;
-    attention_count: number;
-}
-export type PushSendResult = 'sent' | 'gone' | 'error';
-export interface PushPayload {
-    conversationId: string;
-    kind: 'done';
-    title: string;
-    snippet: string;
-}
-export interface PushEngineDeps {
-    registry: PushRegistryStore;
-    lastSeen: PushLastSeenStore;
-    readCanvasNodes: () => Promise<CanvasNodeRow[]> | CanvasNodeRow[];
-    sendPush: (record: PushSubscriptionRecord, payload: PushPayload) => Promise<PushSendResult>;
-    isTargetScope: (authScope: string) => boolean;
-    now?: () => number;
-    rateWindowMs?: number;
-}
-export declare class PushDiffEngine {
-    private readonly registry;
-    private readonly lastSeen;
-    private readonly readCanvasNodes;
-    private readonly sendPush;
-    private readonly isTargetScope;
-    private readonly now;
-    private readonly rateWindowMs;
-    private draining;
-    private pendingNodes;
-    private readonly lastPushAt;
-    private readonly deliveredForKey;
-    constructor(deps: PushEngineDeps);
-    /** Record the current canvas state without sending notifications. */
-    seed(): Promise<void>;
-    onNodesInvalidation(): Promise<void>;
-    private drain;
-    private runNodesPass;
-    private emit;
-}

package/dist/clients/web/push-engine.js

@@ -1,125 +0,0 @@
-// push-engine.ts — the server-side web-push diff engine. SSE (`events.ts`) is
-// a trigger only (`{kind, ts}`, never data); this module re-reads the canvas,
-// diffs persisted last-seen state, and emits done-transition notifications.
-//
-// A `nodes` invalidation detects a conversation root (`parent === null`) crossing
-// from a nonterminal state into done, dead, or canceled. On server start,
-// `seed()` records the current state and sends nothing.
-import { isAllowedPushEndpoint } from './push-registry.js';
-const DONE_STATUSES = new Set(['done', 'dead', 'canceled']);
-const DEFAULT_RATE_WINDOW_MS = 30_000;
-export class PushDiffEngine {
-    registry;
-    lastSeen;
-    readCanvasNodes;
-    sendPush;
-    isTargetScope;
-    now;
-    rateWindowMs;
-    draining = false;
-    pendingNodes = false;
-    lastPushAt = new Map();
-    deliveredForKey = new Map();
-    constructor(deps) {
-        this.registry = deps.registry;
-        this.lastSeen = deps.lastSeen;
-        this.readCanvasNodes = deps.readCanvasNodes;
-        this.sendPush = deps.sendPush;
-        this.isTargetScope = deps.isTargetScope;
-        this.now = deps.now ?? (() => Date.now());
-        this.rateWindowMs = deps.rateWindowMs ?? DEFAULT_RATE_WINDOW_MS;
-    }
-    /** Record the current canvas state without sending notifications. */
-    async seed() {
-        const nodes = await this.readCanvasNodes();
-        const roots = {};
-        for (const node of nodes) {
-            if (node.parent === null)
-                roots[node.node_id] = { status: node.status, attention_count: node.attention_count };
-        }
-        this.lastSeen.replace({ schemaVersion: 1, updatedAt: this.now(), roots });
-    }
-    async onNodesInvalidation() {
-        this.pendingNodes = true;
-        await this.drain();
-    }
-    async drain() {
-        if (this.draining)
-            return;
-        this.draining = true;
-        try {
-            while (this.pendingNodes) {
-                this.pendingNodes = false;
-                await this.runNodesPass();
-            }
-        }
-        finally {
-            this.draining = false;
-        }
-    }
-    async runNodesPass() {
-        const nodes = await this.readCanvasNodes();
-        const previous = this.lastSeen.snapshot();
-        const roots = {};
-        for (const node of nodes) {
-            if (node.parent !== null)
-                continue;
-            const before = previous.roots[node.node_id];
-            const transitioned = before !== undefined && !DONE_STATUSES.has(before.status) && DONE_STATUSES.has(node.status);
-            if (!transitioned) {
-                roots[node.node_id] = { status: node.status, attention_count: node.attention_count };
-                continue;
-            }
-            const sent = await this.emit(node.node_id, {
-                conversationId: node.node_id,
-                kind: 'done',
-                title: 'Conversation finished',
-                snippet: `This conversation is now ${node.status}.`,
-            });
-            roots[node.node_id] = sent ? { status: node.status, attention_count: node.attention_count } : before;
-        }
-        this.lastSeen.replace({ schemaVersion: previous.schemaVersion, updatedAt: this.now(), roots });
-    }
-    async emit(conversationId, payload) {
-        const eligible = this.registry.snapshot().filter((record) => this.isTargetScope(record.authScope) && record.prefs.doneNotifications);
-        const key = `${conversationId}:${payload.kind}`;
-        if (eligible.length === 0) {
-            this.deliveredForKey.delete(key);
-            return true;
-        }
-        const now = this.now();
-        const last = this.lastPushAt.get(conversationId) ?? 0;
-        if (now - last < this.rateWindowMs)
-            return false;
-        this.lastPushAt.set(conversationId, now);
-        const delivered = this.deliveredForKey.get(key) ?? new Set();
-        let transientFailure = false;
-        for (const record of eligible) {
-            if (delivered.has(record.id))
-                continue;
-            if (!isAllowedPushEndpoint(record.endpoint)) {
-                this.registry.deleteById(record.id);
-                continue;
-            }
-            let result;
-            try {
-                result = await this.sendPush(record, payload);
-            }
-            catch {
-                result = 'error';
-            }
-            if (result === 'gone')
-                this.registry.deleteById(record.id);
-            else if (result === 'sent')
-                delivered.add(record.id);
-            else
-                transientFailure = true;
-        }
-        if (transientFailure) {
-            this.deliveredForKey.set(key, delivered);
-            return false;
-        }
-        this.deliveredForKey.delete(key);
-        return true;
-    }
-}

package/dist/clients/web/push-registry.d.ts

@@ -1,85 +0,0 @@
-import type { NodeLifeStatus } from './web-client/shared/protocol.js';
-export interface PushPreferences {
-    doneNotifications: boolean;
-}
-export interface PushSubscriptionRecord {
-    id: string;
-    endpoint: string;
-    keys: {
-        p256dh: string;
-        auth: string;
-    };
-    authScope: string;
-    createdAt: number;
-    lastSeenAt: number;
-    prefs: PushPreferences;
-}
-export interface PushRegistryFile {
-    schemaVersion: number;
-    records: PushSubscriptionRecord[];
-}
-export interface PushLastSeenRootState {
-    status: NodeLifeStatus;
-    attention_count: number;
-}
-export interface PushLastSeenFile {
-    schemaVersion: number;
-    updatedAt: number;
-    roots: Record<string, PushLastSeenRootState>;
-}
-/** A locally generated VAPID keypair, persisted so the same identity signs
- *  every outbound push across restarts. The private key never leaves this
- *  file/process — only `publicKey` is ever served to a client. */
-export interface VapidKeypairFile {
-    schemaVersion: number;
-    publicKey: string;
-    privateKey: string;
-    subject: string;
-}
-export declare class PushRequestError extends Error {
-    readonly statusCode: number;
-    constructor(statusCode: number, message: string);
-}
-export declare function registryPath(): string;
-export declare function lastSeenPath(): string;
-export declare function vapidPath(): string;
-export declare function pushBodyMaxBytes(): number;
-/** Re-checkable at any later point (e.g. immediately before an outbound send,
- *  not just at subscribe time) with no dependency on DNS resolution — the
- *  allowlist match is a pure string check, so there is nothing to TOCTOU. */
-export declare function isAllowedPushEndpoint(endpoint: string): boolean;
-export declare function normalizeEndpoint(endpoint: unknown): string;
-export declare function subscriptionIdForEndpoint(endpoint: string): string;
-export declare function parsePushSubscriptionBody(rawBody: string, authScope: string, now?: number): PushSubscriptionRecord;
-export declare function parsePushDeleteBody(rawBody: string): {
-    endpoint: string;
-};
-/** Load the persisted VAPID keypair, generating and persisting a fresh one on
- *  first run. One keypair per server identity (design D8/push contract) —
- *  every subscription is signed with the same public key for the life of this
- *  `crtrHome()`. The private key never leaves this file/process. */
-export declare function loadOrCreateVapidKeypair(path?: string, subject?: string): VapidKeypairFile;
-export declare class PushRegistryStore {
-    private readonly path;
-    private state;
-    private readonly byId;
-    constructor(path?: string);
-    snapshot(): PushSubscriptionRecord[];
-    listByScope(authScope: string): PushSubscriptionRecord[];
-    upsert(record: PushSubscriptionRecord): PushSubscriptionRecord;
-    touchById(id: string, lastSeenAt: number): PushSubscriptionRecord | null;
-    /** Scoped delete for the HTTP DELETE verb: a caller may only remove a
-     *  subscription it owns (its authScope matches the stored record's). Pruning a
-     *  service-reported-gone endpoint is a separate, unscoped path (`deleteById`). */
-    deleteByEndpoint(endpoint: string, authScope: string): boolean;
-    deleteById(id: string): boolean;
-    private persist;
-}
-export declare class PushLastSeenStore {
-    private readonly path;
-    private state;
-    constructor(path?: string);
-    snapshot(): PushLastSeenFile;
-    replace(next: PushLastSeenFile): void;
-    private persist;
-}