@nimbus-sh/worker 0.1.0

package/dist/session/diag.js

@@ -0,0 +1,118 @@
+/**
+ * session/diag.ts — heap probe + W5 OOM-ring persistence helpers.
+ *
+ * Why a sibling module: heap-sampling state (peak RSS, sample count)
+ * is per-DO-instance but doesn't belong in the DO class itself —
+ * it's pure data + one ctx-side persistence helper, kept here so the
+ * class file stays small and the diag is testable without a workerd
+ * harness.
+ *
+ * Surfaces:
+ *   - readNodeMem() — process.memoryUsage() if available; null otherwise.
+ *   - readPerfMem() — performance.memory if available; null otherwise.
+ *   - sampleMemory(host) — read + update peak trackers (no I/O, microseconds).
+ *   - rehydrateRingFromStorage(host, ctx) — load OOM ring snapshot at boot.
+ *   - persistRing(host, ctx) — async put with redundant-write skip.
+ *
+ * Per DEFECT-D1: ctx is taken as a separate explicit arg.
+ */
+import { rehydrateFromStorage, snapshotForStorage, getFailures, } from '../observability/oom-discriminator.js';
+import { W5_RING_STORAGE_KEY } from './keys.js';
+export function readNodeMem() {
+    try {
+        const g = globalThis;
+        if (g.process && typeof g.process.memoryUsage === 'function') {
+            const mu = g.process.memoryUsage();
+            return {
+                rss: mu.rss | 0,
+                heapTotal: mu.heapTotal | 0,
+                heapUsed: mu.heapUsed | 0,
+                external: mu.external | 0,
+                arrayBuffers: mu.arrayBuffers | 0,
+            };
+        }
+    }
+    catch { /* ignore */ }
+    return null;
+}
+export function readPerfMem() {
+    try {
+        const g = globalThis;
+        if (g.performance && g.performance.memory) {
+            return {
+                jsHeapSizeLimit: g.performance.memory.jsHeapSizeLimit | 0,
+                totalJSHeapSize: g.performance.memory.totalJSHeapSize | 0,
+                usedJSHeapSize: g.performance.memory.usedJSHeapSize | 0,
+            };
+        }
+    }
+    catch { /* ignore */ }
+    return null;
+}
+/**
+ * Sample current heap and update peak trackers. Idempotent on call
+ * count beyond `_diagSampleCount`. Safe to call from any code path
+ * (request handler, install/bundle progress callbacks) — does NO
+ * I/O, NO async work, returns immediately. Cost: one process.memoryUsage()
+ * which is microseconds.
+ */
+export function sampleMemory(host) {
+    host._diagSampleCount++;
+    const mu = readNodeMem();
+    if (!mu)
+        return;
+    const now = Date.now();
+    if (mu.rss > host._diagPeakRss) {
+        host._diagPeakRss = mu.rss;
+        host._diagPeakAt = now;
+    }
+    if (mu.heapUsed > host._diagPeakHeapUsed) {
+        host._diagPeakHeapUsed = mu.heapUsed;
+        // _diagPeakAt is whichever is most recent of the two; prefer
+        // heapUsed peaks since rss is a lagging indicator that may include
+        // freed-but-not-returned pages.
+        host._diagPeakAt = now;
+    }
+}
+/**
+ * W5 Lever 5: rehydrate the OOM ring from storage (best-effort).
+ * Survives DO hibernation; lets cf-tail-style forensics include
+ * pre-hibernate failures. Fail-soft on garbage / missing.
+ */
+export async function rehydrateRingFromStorage(_host, ctx) {
+    try {
+        const blob = await ctx.storage.get(W5_RING_STORAGE_KEY);
+        if (blob)
+            rehydrateFromStorage(blob);
+    }
+    catch (_e) {
+        // Storage read can fail on a fresh isolate or after schema reset.
+        // The ring stays empty — perfectly OK.
+    }
+}
+/**
+ * Snapshot the ring + persist to ctx.storage. Async; callers should
+ * pass the returned promise to ctx.waitUntil so close-handler return
+ * doesn't race the put. Skips redundant writes.
+ */
+export function persistRing(host, ctx) {
+    try {
+        const failures = getFailures();
+        if (failures.length === 0)
+            return null;
+        if (failures.length === host._w5LastPersistRingSize)
+            return null;
+        const snap = snapshotForStorage();
+        host._w5LastPersistRingSize = failures.length;
+        host._w5LastPersistAt = Date.now();
+        // ctx.storage.put returns a promise; await semantics for the
+        // caller's waitUntil. Errors here are non-fatal — log and move on.
+        return ctx.storage.put(W5_RING_STORAGE_KEY, snap).catch((e) => {
+            console.warn('[nimbus/W5] ring persist failed:', e?.message);
+        });
+    }
+    catch (e) {
+        console.warn('[nimbus/W5] ring persist threw:', e?.message);
+        return null;
+    }
+}

package/dist/session/fs-watch.d.ts

@@ -0,0 +1,132 @@
+/**
+ * session/fs-watch.ts — server-side `fs-watch-*` WS protocol.
+ *
+ * The VFS event bus (`src/vfs/events.ts`) already fires
+ * `add`/`addDir`/`change`/`unlink`/`unlinkDir`/`rename` on every
+ * SqliteVFS mutation (sqlite-vfs.ts:934, 1020, 1147, 1168, 1253,
+ * 1654-1659). Three consumers already subscribe: cirrus-real HMR
+ * (facets/cirrus-real.ts:894), in-supervisor vite-dev-server
+ * (facets/vite-dev-server.ts:1524), and wrangler-dev
+ * (wrangler/nimbus-wrangler.ts:245, 977).
+ *
+ * This module exposes that bus to browser clients (the FileTree
+ * sidebar in public/s/index.html) over the existing shell WebSocket,
+ * closing the user-reported gap: "file editor doesnt auto load any
+ * new files/folders".
+ *
+ * Protocol (additive; coexists with fs-read/fs-write/fs-list at
+ * session/init.ts:260):
+ *
+ *   IN  { type:'fs-watch-subscribe', reqId, paths:string[] }
+ *   OUT { type:'fs-watch-subscribe-result', reqId, ok:true, subId:string }
+ *       or { type:'fs-watch-subscribe-result', reqId, ok:false, error }
+ *
+ *   OUT { type:'fs-watch-event', subId, events:VfsEvent[], dropped?:number }
+ *       — SERVER-PUSHED; no reqId echo.
+ *
+ *   IN  { type:'fs-watch-unsubscribe', reqId, subId?:string }
+ *   OUT { type:'fs-watch-unsubscribe-result', reqId, ok:true, removed:number }
+ *
+ *   subId is optional on unsubscribe: omitting it drops ALL of the
+ *   WS's subscriptions. The client side prefers omitting since it
+ *   maintains one subscription per WS in practice.
+ *
+ * Coalescing strategy
+ * -------------------
+ * The bus delivers global-batched events once per microtask. We add an
+ * additional ~50 ms debounce so a 1000-file npm install doesn't
+ * produce 1000 WS frames (or ~1000 microtask-batches). 50 ms absorbs
+ * the typical burst pattern and stays well under the user-perceptible
+ * 100 ms threshold.
+ *
+ * Memory cap: per subscriber, pending events are hard-capped at 200.
+ * When the cap is hit, oldest events are dropped and a `dropped:N`
+ * field rides on the next emitted frame so the client can choose to
+ * re-fetch the whole tree (it does in practice — bounded patches vs
+ * full reload). No producer back-pressure.
+ *
+ * Lifecycle
+ * ---------
+ *   - One Map<WebSocket, Sub[]> per session DO on the WsHost.
+ *   - On `fs-watch-subscribe`: append a Sub + register the bus listener.
+ *   - On `fs-watch-unsubscribe`: invoke unsub closures + remove entries.
+ *   - On WS close / error (ws.ts:wsClose / wsError): unconditionally
+ *     drop all subs for the dying WS.
+ *   - On WS warm-rejoin: the OLD ws's close already cleaned up; the
+ *     NEW ws is unrelated until the client re-subscribes from
+ *     its onopen handler.
+ *
+ * No recurring timers introduced. The debounce uses a one-shot
+ * setTimeout that nulls itself on fire and is cleared on unsub —
+ * preserving the W1 hibernation invariant (CF DO docs verbatim:
+ * "scheduled callbacks prevent hibernation. This includes setTimeout
+ * and setInterval usage." — a transient one-shot during active work is
+ * acceptable and matches the W9 flush debounce pattern at
+ * hibernation.ts:236-256).
+ */
+import type { VfsEvent } from '../vfs/events.js';
+import type { SqliteVFS } from '../vfs/sqlite-vfs.js';
+/** Per-subscription state. Closed over a single WebSocket. */
+export interface FsWatchSub {
+    /** Stable id for client-side correlation. */
+    subId: string;
+    /** Path-prefixes the client cares about. Empty = match-all. */
+    paths: string[];
+    /** Bus unsubscribe closure. */
+    unsub: () => void;
+    /** Pending events to flush in the next debounce window. */
+    pending: VfsEvent[];
+    /** Count of events dropped due to the SUB_MAX_QUEUE cap. */
+    dropped: number;
+    /** Active debounce timer; null when no flush scheduled. */
+    flushTimer: any;
+}
+/** Minimal host shape needed by this module. */
+export interface FsWatchHost {
+    sqliteFs: SqliteVFS | null;
+    _fsWatchSubs?: Map<WebSocket, FsWatchSub[]>;
+}
+/**
+ * Handle `fs-watch-subscribe`. Registers a bus listener; the listener
+ * captures `ws` and pushes events (debounced + coalesced) over it.
+ *
+ * Returns the structured result for the caller to forward as the
+ * `fs-watch-subscribe-result` frame.
+ */
+export declare function handleFsWatchSubscribe(host: FsWatchHost, ws: WebSocket, msg: {
+    paths?: unknown;
+}): {
+    ok: true;
+    subId: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Handle `fs-watch-unsubscribe`. If `subId` is given, drops only that
+ * subscription; otherwise drops ALL of this WS's subscriptions.
+ * Returns the count removed.
+ */
+export declare function handleFsWatchUnsubscribe(host: FsWatchHost, ws: WebSocket, msg: {
+    subId?: unknown;
+}): {
+    ok: true;
+    removed: number;
+};
+/**
+ * Drop EVERY subscription on the closing WS. Called from wsClose /
+ * wsError. Idempotent + no-op when nothing pending.
+ */
+export declare function cleanupFsWatchOnClose(host: FsWatchHost, ws: WebSocket): void;
+/**
+ * Diagnostic: total subscriber + pending-event counts across the host.
+ * Useful for /api/_diag/* surfaces and leak-detection probes (the
+ * cleanup-on-disconnect probe asserts counts return to 0 after WS close).
+ */
+export declare function getFsWatchStats(host: FsWatchHost): {
+    wsCount: number;
+    subCount: number;
+    pendingTotal: number;
+    droppedTotal: number;
+};
+//# sourceMappingURL=fs-watch.d.ts.map

package/dist/session/fs-watch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-watch.d.ts","sourceRoot":"","sources":["../../src/session/fs-watch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,8DAA8D;AAC9D,MAAM,WAAW,UAAU;IACzB,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,+BAA+B;IAC/B,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,2DAA2D;IAC3D,OAAO,EAAE,QAAQ,EAAE,CAAC;IACpB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,UAAU,EAAE,GAAG,CAAC;CACjB;AAiBD,gDAAgD;AAChD,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,SAAS,GAAG,IAAI,CAAC;IAC3B,YAAY,CAAC,EAAE,GAAG,CAAC,SAAS,EAAE,UAAU,EAAE,CAAC,CAAC;CAC7C;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,WAAW,EACjB,EAAE,EAAE,SAAS,EACb,GAAG,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CA6F5D;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,WAAW,EACjB,EAAE,EAAE,SAAS,EACb,GAAG,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAgB/B;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,SAAS,GAAG,IAAI,CAS5E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,GAAG;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACtB,CAcA"}

package/dist/session/fs-watch.js

@@ -0,0 +1,255 @@
+/**
+ * session/fs-watch.ts — server-side `fs-watch-*` WS protocol.
+ *
+ * The VFS event bus (`src/vfs/events.ts`) already fires
+ * `add`/`addDir`/`change`/`unlink`/`unlinkDir`/`rename` on every
+ * SqliteVFS mutation (sqlite-vfs.ts:934, 1020, 1147, 1168, 1253,
+ * 1654-1659). Three consumers already subscribe: cirrus-real HMR
+ * (facets/cirrus-real.ts:894), in-supervisor vite-dev-server
+ * (facets/vite-dev-server.ts:1524), and wrangler-dev
+ * (wrangler/nimbus-wrangler.ts:245, 977).
+ *
+ * This module exposes that bus to browser clients (the FileTree
+ * sidebar in public/s/index.html) over the existing shell WebSocket,
+ * closing the user-reported gap: "file editor doesnt auto load any
+ * new files/folders".
+ *
+ * Protocol (additive; coexists with fs-read/fs-write/fs-list at
+ * session/init.ts:260):
+ *
+ *   IN  { type:'fs-watch-subscribe', reqId, paths:string[] }
+ *   OUT { type:'fs-watch-subscribe-result', reqId, ok:true, subId:string }
+ *       or { type:'fs-watch-subscribe-result', reqId, ok:false, error }
+ *
+ *   OUT { type:'fs-watch-event', subId, events:VfsEvent[], dropped?:number }
+ *       — SERVER-PUSHED; no reqId echo.
+ *
+ *   IN  { type:'fs-watch-unsubscribe', reqId, subId?:string }
+ *   OUT { type:'fs-watch-unsubscribe-result', reqId, ok:true, removed:number }
+ *
+ *   subId is optional on unsubscribe: omitting it drops ALL of the
+ *   WS's subscriptions. The client side prefers omitting since it
+ *   maintains one subscription per WS in practice.
+ *
+ * Coalescing strategy
+ * -------------------
+ * The bus delivers global-batched events once per microtask. We add an
+ * additional ~50 ms debounce so a 1000-file npm install doesn't
+ * produce 1000 WS frames (or ~1000 microtask-batches). 50 ms absorbs
+ * the typical burst pattern and stays well under the user-perceptible
+ * 100 ms threshold.
+ *
+ * Memory cap: per subscriber, pending events are hard-capped at 200.
+ * When the cap is hit, oldest events are dropped and a `dropped:N`
+ * field rides on the next emitted frame so the client can choose to
+ * re-fetch the whole tree (it does in practice — bounded patches vs
+ * full reload). No producer back-pressure.
+ *
+ * Lifecycle
+ * ---------
+ *   - One Map<WebSocket, Sub[]> per session DO on the WsHost.
+ *   - On `fs-watch-subscribe`: append a Sub + register the bus listener.
+ *   - On `fs-watch-unsubscribe`: invoke unsub closures + remove entries.
+ *   - On WS close / error (ws.ts:wsClose / wsError): unconditionally
+ *     drop all subs for the dying WS.
+ *   - On WS warm-rejoin: the OLD ws's close already cleaned up; the
+ *     NEW ws is unrelated until the client re-subscribes from
+ *     its onopen handler.
+ *
+ * No recurring timers introduced. The debounce uses a one-shot
+ * setTimeout that nulls itself on fire and is cleared on unsub —
+ * preserving the W1 hibernation invariant (CF DO docs verbatim:
+ * "scheduled callbacks prevent hibernation. This includes setTimeout
+ * and setInterval usage." — a transient one-shot during active work is
+ * acceptable and matches the W9 flush debounce pattern at
+ * hibernation.ts:236-256).
+ */
+/** Hard cap on pending events per subscriber before drop-oldest. */
+const SUB_MAX_QUEUE = 200;
+/**
+ * Debounce window in ms. 50 ms absorbs npm-install / git-checkout
+ * burst patterns; well under the 100 ms user-perceptible threshold;
+ * not a recurring timer (one-shot per burst, self-clears on fire).
+ */
+const COALESCE_MS = 50;
+/** Generate a short opaque id for a new subscription. */
+function genSubId() {
+    return 'sub-' + Math.random().toString(36).slice(2, 10) + '-' + Date.now().toString(36);
+}
+/**
+ * Handle `fs-watch-subscribe`. Registers a bus listener; the listener
+ * captures `ws` and pushes events (debounced + coalesced) over it.
+ *
+ * Returns the structured result for the caller to forward as the
+ * `fs-watch-subscribe-result` frame.
+ */
+export function handleFsWatchSubscribe(host, ws, msg) {
+    const vfs = host.sqliteFs;
+    if (!vfs)
+        return { ok: false, error: 'VFS not initialised' };
+    // Normalise paths to a string[]. Empty array means match-all
+    // (the global bus listener delivers every event).
+    const paths = [];
+    if (Array.isArray(msg.paths)) {
+        for (const p of msg.paths) {
+            if (typeof p === 'string' && p.length > 0)
+                paths.push(p);
+        }
+    }
+    if (!host._fsWatchSubs)
+        host._fsWatchSubs = new Map();
+    let list = host._fsWatchSubs.get(ws);
+    if (!list) {
+        list = [];
+        host._fsWatchSubs.set(ws, list);
+    }
+    const sub = {
+        subId: genSubId(),
+        paths,
+        unsub: () => { }, // patched below once busUnsub is in hand
+        pending: [],
+        dropped: 0,
+        flushTimer: null,
+    };
+    /** Flush pending events over the WS. Best-effort. */
+    const flush = () => {
+        sub.flushTimer = null;
+        if (sub.pending.length === 0 && sub.dropped === 0)
+            return;
+        const events = sub.pending;
+        const dropped = sub.dropped;
+        sub.pending = [];
+        sub.dropped = 0;
+        try {
+            const frame = { type: 'fs-watch-event', subId: sub.subId, events };
+            if (dropped > 0)
+                frame.dropped = dropped;
+            ws.send(JSON.stringify(frame));
+        }
+        catch {
+            // WS closed mid-flush; wsClose cleanup handles unsub. Silent drop.
+        }
+    };
+    /**
+     * Filter event against this subscription's path prefixes. SqliteVFS
+     * paths in events are bare (no leading slash, e.g. 'home/user/x.txt');
+     * client may send absolute paths (e.g. '/home/user'). Strip leading
+     * slashes on both sides before prefix-match.
+     */
+    const matches = (eventPath) => {
+        if (paths.length === 0)
+            return true;
+        const ep = eventPath.replace(/^\/+/, '');
+        for (const p of paths) {
+            const norm = p.replace(/^\/+/, '');
+            if (ep === norm || ep.startsWith(norm + '/'))
+                return true;
+        }
+        return false;
+    };
+    /** Bus listener — global-batched per microtask. */
+    const onBatch = (batch) => {
+        for (const ev of batch) {
+            if (!matches(ev.path))
+                continue;
+            if (sub.pending.length >= SUB_MAX_QUEUE) {
+                // Drop-oldest: shift instead of unbounded growth.
+                sub.pending.shift();
+                sub.dropped++;
+            }
+            sub.pending.push(ev);
+        }
+        if (sub.pending.length === 0 && sub.dropped === 0)
+            return;
+        // One-shot debounce: re-arm if no flush scheduled.
+        if (!sub.flushTimer) {
+            sub.flushTimer = setTimeout(flush, COALESCE_MS);
+        }
+    };
+    const busUnsub = vfs.events.on(onBatch);
+    sub.unsub = () => {
+        try {
+            busUnsub();
+        }
+        catch { }
+        if (sub.flushTimer) {
+            try {
+                clearTimeout(sub.flushTimer);
+            }
+            catch { }
+            sub.flushTimer = null;
+        }
+        sub.pending = [];
+        sub.dropped = 0;
+    };
+    list.push(sub);
+    return { ok: true, subId: sub.subId };
+}
+/**
+ * Handle `fs-watch-unsubscribe`. If `subId` is given, drops only that
+ * subscription; otherwise drops ALL of this WS's subscriptions.
+ * Returns the count removed.
+ */
+export function handleFsWatchUnsubscribe(host, ws, msg) {
+    const map = host._fsWatchSubs;
+    if (!map)
+        return { ok: true, removed: 0 };
+    const list = map.get(ws);
+    if (!list)
+        return { ok: true, removed: 0 };
+    let removed = 0;
+    const targetId = typeof msg.subId === 'string' ? msg.subId : null;
+    for (let i = list.length - 1; i >= 0; i--) {
+        if (targetId === null || list[i].subId === targetId) {
+            try {
+                list[i].unsub();
+            }
+            catch { }
+            list.splice(i, 1);
+            removed++;
+        }
+    }
+    if (list.length === 0)
+        map.delete(ws);
+    return { ok: true, removed };
+}
+/**
+ * Drop EVERY subscription on the closing WS. Called from wsClose /
+ * wsError. Idempotent + no-op when nothing pending.
+ */
+export function cleanupFsWatchOnClose(host, ws) {
+    const map = host._fsWatchSubs;
+    if (!map)
+        return;
+    const list = map.get(ws);
+    if (!list)
+        return;
+    for (const sub of list) {
+        try {
+            sub.unsub();
+        }
+        catch { }
+    }
+    map.delete(ws);
+}
+/**
+ * Diagnostic: total subscriber + pending-event counts across the host.
+ * Useful for /api/_diag/* surfaces and leak-detection probes (the
+ * cleanup-on-disconnect probe asserts counts return to 0 after WS close).
+ */
+export function getFsWatchStats(host) {
+    const map = host._fsWatchSubs;
+    if (!map)
+        return { wsCount: 0, subCount: 0, pendingTotal: 0, droppedTotal: 0 };
+    let subCount = 0;
+    let pendingTotal = 0;
+    let droppedTotal = 0;
+    for (const list of map.values()) {
+        subCount += list.length;
+        for (const sub of list) {
+            pendingTotal += sub.pending.length;
+            droppedTotal += sub.dropped;
+        }
+    }
+    return { wsCount: map.size, subCount, pendingTotal, droppedTotal };
+}

package/dist/session/helpers.d.ts

@@ -0,0 +1,150 @@
+/**
+ * session/helpers.ts — pure helpers used by the supervisor.
+ *
+ * All functions here are pure (no class state, no
+ * `cloudflare:workers` import), so they can be unit-tested with bun
+ * test without a workerd harness. The cleanup-and-readme reorg moved
+ * them here from src/nimbus-session.ts (originally lines 96-523).
+ *
+ * audit/sections/SESSION-REFACTOR-PLAN.md §B.3.2 + S1.
+ *
+ * Re-exported by nimbus-session.ts so existing imports keep working.
+ */
+import type { SqliteVFS } from '../vfs/sqlite-vfs.js';
+/**
+ * Render a polished "no dev server" placeholder HTML page for the /preview/
+ * route. Matches the Nimbus shell MOTD aesthetic (near-black background,
+ * green monospace accents). Auto-reloads when /api/stats reports the named
+ * service has flipped to `running: true`.
+ *
+ * All CSS inlined — no external deps so it works offline.
+ */
+export declare function renderNoDevServerHtml(opts: {
+    /** Shell hint to display in the code block (already HTML-escaped). */
+    hint: string;
+    /** Fully-qualified URL path to poll (e.g. `/s/<id>/api/stats`). */
+    polled: string;
+    /** Stats field to watch for `.running === true`. */
+    liveKey: 'vite' | 'wrangler';
+}): string;
+/**
+ * Known bundler / framework CLIs that need node_modules to be usable.
+ * If an npm script starts with one of these binaries, missing node_modules
+ * is a hard error (exit 1) rather than a warning. Scripts that don't match
+ * get a soft warning; the script runs anyway in case it's something like
+ * `echo hi` that doesn't need deps at all.
+ */
+export declare const BUNDLER_BIN_PREFIXES: string[];
+/**
+ * Bins that can't execute inside a Durable Object isolate, with tailored
+ * guidance for the user. These are commands that CAN install into
+ * node_modules/.bin but that crash or hang at runtime because they depend
+ * on primitives (child_process.spawn, native binaries, real sockets) that
+ * Nimbus doesn't provide.
+ *
+ * Used by the `npm run` handler's Fix-1 pre-flight: if a script starts
+ * with one of these bins, we short-circuit with a deterministic error
+ * instead of letting it enter the shell.execute black hole.
+ *
+ * Keep the keys as the RAW bin name the user's script would invoke;
+ * point to the Nimbus-native alternative if one exists.
+ *
+ * NOTE: `wrangler` is NOT here anymore — it's registered as a transparent
+ * alias for `nimbus-wrangler` in initSession, so `npm run dev` with a
+ * wrangler-based dev script Just Works via the DO-in-DO implementation.
+ * If a user's Worker uses bindings that nimbus-wrangler can't provide
+ * (durable_objects, assets, worker_loaders, etc.), the wrapper prints a
+ * loud warning BEFORE building so there are no mysterious runtime errors.
+ */
+export declare const NIMBUS_UNSUPPORTED_BINS: Record<string, {
+    reason: string;
+    alternative?: string;
+}>;
+/**
+ * wrangler CLI flags that have no meaning inside Nimbus (the DO provides
+ * its own host/port/log routing). If present in a wrangler/npm-run-dev
+ * invocation, we strip them silently rather than failing — user scripts
+ * authored for real wrangler shouldn't need modification.
+ *
+ * Flags are matched by exact name; the following token (value) is also
+ * consumed when the flag is a known "takes a value" variant.
+ */
+export declare const WRANGLER_IGNORED_FLAGS: Set<string>;
+export declare const WRANGLER_IGNORED_FLAGS_WITH_VALUE: Set<string>;
+/**
+ * Strip wrangler-specific flags (and their values when applicable) from
+ * an argv slice. Returns both the cleaned args AND the list of ignored
+ * tokens so the caller can log them (once) for transparency.
+ */
+export declare function filterWranglerFlags(argv: string[]): {
+    args: string[];
+    ignored: string[];
+};
+/**
+ * wrangler.jsonc binding fields that require real wrangler / the real
+ * Cloudflare runtime with proper binding provisioning. nimbus-wrangler
+ * can bundle the Worker and load it via env.LOADER, but these bindings
+ * are not wired up — the Worker will get `undefined` when it tries to
+ * access them, which is usually a runtime crash.
+ *
+ * We don't refuse to start — some Workers use these bindings only on
+ * certain paths or in a way that a runtime-undefined value just causes
+ * a specific endpoint to fail. We warn LOUDLY so users know why their
+ * Worker might crash.
+ */
+export declare const WRANGLER_UNSUPPORTED_CONFIG_FIELDS: string[];
+/**
+ * Read the user's wrangler config from the VFS and return any field names
+ * from WRANGLER_UNSUPPORTED_CONFIG_FIELDS that are present and non-empty.
+ *
+ * Best-effort: tolerates JSONC comments and syntax errors (returns [] on
+ * parse failure). The caller decides whether to warn or block — we only
+ * report; nimbus-wrangler itself still runs.
+ */
+export declare function detectUnsupportedWranglerConfig(vfs: SqliteVFS, root: string): string[];
+/**
+ * W8: classify a child_process spawn target by execution kind. Used by
+ * the FacetProcessManager to decide between inline pure-builtin vs
+ * facet-direct dispatch. See audit/sections/W8-plan.md §8.5 BLOCKER-2.
+ *
+ *   pure-builtin  — sync, no facet recursion. echo, cat, true, false,
+ *                   ls, cd, env, sleep, mkdir, rm, … (all the unix
+ *                   command shims in src/unix-commands.ts).
+ *   facet-direct  — needs a fresh isolate. node, npm, npx, git, sh,
+ *                   bash, husky, lefthook, the wranglers, vite, …
+ *   unknown       — exit 127.
+ */
+export declare const _CP_FACET_DIRECT: Set<string>;
+export declare const _CP_PURE_BUILTIN: Set<string>;
+/**
+ * Classify a command name by kind. Returns null for unknown commands.
+ *
+ * Prefix-form rule: anything starting with `./`, `/`, or `node_modules/`
+ * is treated as facet-direct so a registered bin script (or a node
+ * fallthrough) can attempt to run it.
+ */
+export declare function _classifyCommand(name: string): {
+    kind: 'pure-builtin' | 'facet-direct' | 'unknown';
+} | null;
+/**
+ * Parse the first token of an npm script's command string and decide whether
+ * it's a bundler/framework CLI that requires node_modules. Handles common
+ * prefixes like `cross-env FOO=bar vite`, `node ./server.js`, and npx.
+ *
+ * Returns the detected bundler bin name (e.g. "vite") or null.
+ */
+export declare function detectBundlerBin(script: string): string | null;
+/**
+ * Check whether a project directory has installed dependencies.
+ *
+ * Returns { missing: true, depCount } if package.json declares deps AND
+ * node_modules/ doesn't exist. `missing: false` when:
+ *   - There's no package.json (we're not in a project, no guard needed)
+ *   - package.json declares zero deps (no install needed)
+ *   - node_modules/ exists (even if stale — caught by runtime error overlay)
+ */
+export declare function checkNodeModulesGuard(vfs: SqliteVFS, projectRoot: string): {
+    missing: boolean;
+    depCount: number;
+};
+//# sourceMappingURL=helpers.d.ts.map

package/dist/session/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/session/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;CAC9B,GAAG,MAAM,CAiHT;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,UAehC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAI5F,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,aAQjC,CAAC;AACH,eAAO,MAAM,iCAAiC,aAG5C,CAAC;AAEH;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAoBzF;AAED;;;;;;;;;;;GAWG;AAiBH,eAAO,MAAM,kCAAkC,UAQ9C,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAwCtF;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,aAU3B,CAAC;AACH,eAAO,MAAM,gBAAgB,aAS3B,CAAC;AAEH;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,cAAc,GAAG,cAAc,GAAG,SAAS,CAAA;CAAE,GAAG,IAAI,CAU3G;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiB9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,SAAS,EACd,WAAW,EAAE,MAAM,GAClB;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAiBxC"}