@nimbus-sh/worker 0.1.0

package/dist/runtime/esbuild-wasm-bytes.d.ts

@@ -0,0 +1,87 @@
+/**
+ * esbuild-wasm-bytes.ts — supervisor-side fetcher for the esbuild-wasm
+ * binary. The bytes live in the static-assets layer (env.ASSETS); this
+ * module hands them to the caller as an ArrayBuffer when needed.
+ *
+ * Cache strategy
+ * ──────────────
+ * - NO module-scope cache (would pin 16 MiB in supervisor heap; the
+ *   reason this module exists, see Phase 2 A'.5 below).
+ * - L2 colo cache via `caches.default` (cache-and-scrub W-D): the bytes
+ *   are version-pinned by URL (`/_assets/esbuild-<ESBUILD_VERSION>.wasm`),
+ *   so an `immutable` cache entry is correct. The Cache API holds its
+ *   OWN reference outside the supervisor heap, so this does not
+ *   re-introduce the residency that A'.5 removed.
+ *
+ * Why no module-scope cache (Phase 2 A'.5)
+ * ────────────────────────────────────────
+ * Pre-rebuild this module decoded a 16 MiB base64 string from
+ * src/esbuild-wasm-bundle.generated.ts into an ArrayBuffer and cached
+ * the result in module scope for the lifetime of the supervisor
+ * isolate. The cache contributed 16 MiB resident to the supervisor
+ * heap (`esbuildResidentBytes` in src/observability/heap-estimate.ts)
+ * AND the base64 string contributed ~21 MiB to the worker bundle
+ * baseline.
+ *
+ * The architecturally correct path is to keep the bytes in the static-
+ * assets layer (public/_assets/esbuild-<version>.wasm), fetch on
+ * demand, and let workerd's loader own the only long-lived copy
+ * (inside dynamic-worker isolates that need it). Cache API entries
+ * are stored OUTSIDE the supervisor heap (workerd manages them), so
+ * adding L2 wrap doesn't undo this.
+ *
+ * Each call to `fetchEsbuildWasmBytes(env)` now does:
+ *   - one `caches.default.match()` — sub-millisecond on hit
+ *   - on miss: one env.ASSETS.fetch() + one cache write-back
+ *   - one Response.arrayBuffer() — 12 MiB ArrayBuffer in supervisor
+ *     heap, briefly, then GC'd
+ *
+ * Failure model
+ * ─────────────
+ * Cache lookup failure (any throw) → fall through to ASSETS.
+ * ASSETS fetch returning non-200 → throw (deploy bug, surface loudly).
+ */
+/**
+ * Path inside env.ASSETS where the esbuild-wasm binary lives.
+ * Versioned so a future esbuild-wasm bump produces a different asset
+ * name and forces a fresh fetch (no stale-cache risk). The matching
+ * file is staged at public/_assets/esbuild-<version>.wasm by
+ * scripts/bundle-esbuild-wasm.mjs at predeploy time.
+ */
+export declare const ESBUILD_WASM_ASSET_PATH = "/_assets/esbuild-0.24.2.wasm";
+/**
+ * The minimal env shape this module needs. Defined narrowly so the
+ * caller can pass any env with an ASSETS Fetcher binding without
+ * dragging in the full Workers env type.
+ */
+export interface EsbuildWasmFetchEnv {
+    ASSETS: {
+        fetch(req: Request): Promise<Response>;
+    };
+}
+/**
+ * Synthetic L2 cache key for the esbuild-wasm asset. Versioned via
+ * ESBUILD_WASM_ASSET_PATH so each esbuild upgrade lands a fresh entry
+ * and old entries naturally evict on TTL.
+ *
+ * Exported so the test endpoint at /api/_test/cache/wasm/reset can
+ * purge the entry between probe runs (otherwise wrangler dev's
+ * persistent caches.default.state preserves the L2 hit across sessions
+ * and the cold path is unobservable).
+ */
+export declare const ESBUILD_WASM_L2_KEY = "https://nimbus-cache.invalid/_assets/esbuild-0.24.2.wasm";
+/**
+ * Fetch the esbuild-wasm bytes from the static-assets layer.
+ *
+ * The supervisor briefly holds the 12 MiB ArrayBuffer between this
+ * call and the caller's hand-off to workerd's LOADER. After the
+ * caller's reference goes out of scope, GC reclaims it; supervisor
+ * residency drops back to zero.
+ *
+ * L2 (cache-and-scrub W-D): on hit, returns the bytes from
+ * `caches.default` (per-colo, sub-millisecond). On miss, falls through
+ * to env.ASSETS and write-back. Cache failures are silent — ASSETS is
+ * always the correct source of truth.
+ */
+export declare function fetchEsbuildWasmBytes(env: EsbuildWasmFetchEnv): Promise<ArrayBuffer>;
+//# sourceMappingURL=esbuild-wasm-bytes.d.ts.map

package/dist/runtime/esbuild-wasm-bytes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"esbuild-wasm-bytes.d.ts","sourceRoot":"","sources":["../../src/runtime/esbuild-wasm-bytes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAIH;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,iCAA6C,CAAC;AAElF;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE;QAAE,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;KAAE,CAAC;CACpD;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,6DAAyE,CAAC;AAE1G;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,WAAW,CAAC,CAuD1F"}

package/dist/runtime/esbuild-wasm-bytes.js

@@ -0,0 +1,131 @@
+/**
+ * esbuild-wasm-bytes.ts — supervisor-side fetcher for the esbuild-wasm
+ * binary. The bytes live in the static-assets layer (env.ASSETS); this
+ * module hands them to the caller as an ArrayBuffer when needed.
+ *
+ * Cache strategy
+ * ──────────────
+ * - NO module-scope cache (would pin 16 MiB in supervisor heap; the
+ *   reason this module exists, see Phase 2 A'.5 below).
+ * - L2 colo cache via `caches.default` (cache-and-scrub W-D): the bytes
+ *   are version-pinned by URL (`/_assets/esbuild-<ESBUILD_VERSION>.wasm`),
+ *   so an `immutable` cache entry is correct. The Cache API holds its
+ *   OWN reference outside the supervisor heap, so this does not
+ *   re-introduce the residency that A'.5 removed.
+ *
+ * Why no module-scope cache (Phase 2 A'.5)
+ * ────────────────────────────────────────
+ * Pre-rebuild this module decoded a 16 MiB base64 string from
+ * src/esbuild-wasm-bundle.generated.ts into an ArrayBuffer and cached
+ * the result in module scope for the lifetime of the supervisor
+ * isolate. The cache contributed 16 MiB resident to the supervisor
+ * heap (`esbuildResidentBytes` in src/observability/heap-estimate.ts)
+ * AND the base64 string contributed ~21 MiB to the worker bundle
+ * baseline.
+ *
+ * The architecturally correct path is to keep the bytes in the static-
+ * assets layer (public/_assets/esbuild-<version>.wasm), fetch on
+ * demand, and let workerd's loader own the only long-lived copy
+ * (inside dynamic-worker isolates that need it). Cache API entries
+ * are stored OUTSIDE the supervisor heap (workerd manages them), so
+ * adding L2 wrap doesn't undo this.
+ *
+ * Each call to `fetchEsbuildWasmBytes(env)` now does:
+ *   - one `caches.default.match()` — sub-millisecond on hit
+ *   - on miss: one env.ASSETS.fetch() + one cache write-back
+ *   - one Response.arrayBuffer() — 12 MiB ArrayBuffer in supervisor
+ *     heap, briefly, then GC'd
+ *
+ * Failure model
+ * ─────────────
+ * Cache lookup failure (any throw) → fall through to ASSETS.
+ * ASSETS fetch returning non-200 → throw (deploy bug, surface loudly).
+ */
+import { ESBUILD_VERSION } from '../constants.js';
+/**
+ * Path inside env.ASSETS where the esbuild-wasm binary lives.
+ * Versioned so a future esbuild-wasm bump produces a different asset
+ * name and forces a fresh fetch (no stale-cache risk). The matching
+ * file is staged at public/_assets/esbuild-<version>.wasm by
+ * scripts/bundle-esbuild-wasm.mjs at predeploy time.
+ */
+export const ESBUILD_WASM_ASSET_PATH = `/_assets/esbuild-${ESBUILD_VERSION}.wasm`;
+/**
+ * Synthetic L2 cache key for the esbuild-wasm asset. Versioned via
+ * ESBUILD_WASM_ASSET_PATH so each esbuild upgrade lands a fresh entry
+ * and old entries naturally evict on TTL.
+ *
+ * Exported so the test endpoint at /api/_test/cache/wasm/reset can
+ * purge the entry between probe runs (otherwise wrangler dev's
+ * persistent caches.default.state preserves the L2 hit across sessions
+ * and the cold path is unobservable).
+ */
+export const ESBUILD_WASM_L2_KEY = `https://nimbus-cache.invalid/_assets/esbuild-${ESBUILD_VERSION}.wasm`;
+/**
+ * Fetch the esbuild-wasm bytes from the static-assets layer.
+ *
+ * The supervisor briefly holds the 12 MiB ArrayBuffer between this
+ * call and the caller's hand-off to workerd's LOADER. After the
+ * caller's reference goes out of scope, GC reclaims it; supervisor
+ * residency drops back to zero.
+ *
+ * L2 (cache-and-scrub W-D): on hit, returns the bytes from
+ * `caches.default` (per-colo, sub-millisecond). On miss, falls through
+ * to env.ASSETS and write-back. Cache failures are silent — ASSETS is
+ * always the correct source of truth.
+ */
+export async function fetchEsbuildWasmBytes(env) {
+    // ── L2 fast path ────────────────────────────────────────────────
+    try {
+        const c = globalThis.caches;
+        if (c?.default) {
+            const hit = await c.default.match(new Request(ESBUILD_WASM_L2_KEY));
+            if (hit && hit.ok) {
+                return await hit.arrayBuffer();
+            }
+        }
+    }
+    catch { /* fall through to ASSETS */ }
+    // ── L4 path (env.ASSETS) ────────────────────────────────────────
+    const url = `https://nimbus-internal.invalid${ESBUILD_WASM_ASSET_PATH}`;
+    // Construct a synthetic request — env.ASSETS routes by pathname only;
+    // the host is ignored. Using `.invalid` per RFC-2606 makes it
+    // unambiguous that this URL is internal-binding-only.
+    const res = await env.ASSETS.fetch(new Request(url));
+    if (!res.ok) {
+        throw new Error(`esbuild-wasm asset fetch failed: ${res.status} ${res.statusText} ` +
+            `for ${ESBUILD_WASM_ASSET_PATH} — deploy is missing the wasm asset`);
+    }
+    // Read the bytes once (Response body is a one-shot stream). The
+    // caller needs the ArrayBuffer to hand to workerd's LOADER; we
+    // also use it to write through to L2.
+    const ab = await res.arrayBuffer();
+    // ── L2 write-back ──────────────────────────────────────────────
+    // Eternal immutable TTL: the URL is version-pinned so a new
+    // ESBUILD_VERSION lands a fresh cache entry; the old one naturally
+    // evicts on TTL. The cache layer holds its own copy (workerd
+    // structured-clones the body during put), so the supervisor's
+    // reference to `ab` is unaffected.
+    // Best-effort: a write failure does NOT block the caller.
+    try {
+        const c = globalThis.caches;
+        if (c?.default) {
+            // We pass a fresh Uint8Array view over the same buffer; the
+            // cache stores a copy at put time. Returning `ab` to the
+            // caller stays valid because Response constructor doesn't
+            // detach the buffer (only ReadableStream consumption would).
+            const writeBack = new Response(new Uint8Array(ab), {
+                headers: {
+                    'Content-Type': 'application/wasm',
+                    'Cache-Control': 'public, max-age=31536000, immutable',
+                },
+            });
+            // Awaited so subsequent reads strictly hit L2 (no
+            // double-fetch race). The wasm payload is 12 MiB; workerd
+            // structured-clones it into the cache, ~1-5 ms locally.
+            await c.default.put(new Request(ESBUILD_WASM_L2_KEY), writeBack);
+        }
+    }
+    catch { /* silent */ }
+    return ab;
+}

package/dist/runtime/framework-detect.d.ts

@@ -0,0 +1,71 @@
+/**
+ * framework-detect.ts — single source of truth for "what kind of project
+ * is this?" Pure function — no I/O of its own. Takes a parsed
+ * package.json + a set of root-level filenames + (optional) per-file
+ * contents and returns a discriminated union.
+ *
+ * Resolution order (first match wins):
+ *
+ *   0. Wrangler-on-framework override:
+ *      `wrangler.{toml,jsonc,json}` at root AND any framework dep present
+ *      → framework: <fw>, devCommand: 'wrangler-dev'
+ *      W10's wrangler-dev path loads the framework's CF adapter.
+ *      MUST come first — Remix-on-CF and SK-on-CF projects have BOTH a
+ *      framework dep AND a wrangler config; without this rule W10's
+ *      path never sees them.
+ *
+ *   1. `next` in deps                            → 'next'
+ *   2. `astro` in deps                           → 'astro'
+ *   3. `nuxt` in deps                            → 'nuxt'
+ *   4. `@remix-run/dev` in deps AND vite.config* references @remix-run/dev
+ *                                                → 'remix'
+ *   5. `@sveltejs/kit` in deps                   → 'sveltekit'
+ *   6. (rule moved to step 0)
+ *   7. `wrangler.{toml,jsonc,json}` alone        → 'wrangler'
+ *   8. `vite` in deps                            → 'vite' (generic)
+ *   9. else                                      → 'unknown'
+ *
+ * Bare `@remix-run/react` without `@remix-run/dev` falls through to step 7
+ * — it's a runtime dep alone, not a Remix v2 vite-plugin project.
+ *
+ * See audit/sections/W11-plan.md §4 for the full spec + rationale.
+ */
+export type Framework = 'next' | 'astro' | 'nuxt' | 'remix' | 'sveltekit' | 'vite' | 'wrangler' | 'unknown';
+export type DevCommand = 'next-cli' | 'astro-cli' | 'nuxt-cli' | 'remix-cli' | 'sveltekit-vite' | 'vite-real' | 'wrangler-dev' | 'generic';
+export interface DetectInput {
+    pkg: {
+        dependencies?: Record<string, string>;
+        devDependencies?: Record<string, string>;
+        scripts?: Record<string, string>;
+    };
+    /** Basenames at project root, e.g. {'package.json', 'svelte.config.js'} */
+    files: Set<string>;
+    /**
+     * Optional: file contents keyed by basename. Currently used for:
+     *   - vite.config.{ts,js,mjs} — Remix gate (must reference @remix-run/dev)
+     * If undefined, the Remix gate falls back to dep-presence only with a
+     * lower confidence.
+     */
+    fileContents?: Record<string, string>;
+}
+export interface DetectResult {
+    framework: Framework;
+    /** 0..1; ≥0.7 means "act on it without asking". */
+    confidence: number;
+    /** Human-readable reason, suitable for logging to the user terminal. */
+    reason: string;
+    /** What the supervisor should treat `npm run dev` as. */
+    devCommand: DevCommand;
+}
+/**
+ * Detect what framework "owns" this project for purposes of routing
+ * `npm run dev`/`npm run build`. Pure; deterministic; no I/O.
+ */
+export declare function detectFramework(input: DetectInput): DetectResult;
+/**
+ * Companion helper: detection result is reportable as a one-line MOTD.
+ * Used by initSession to print a single boot line:
+ *   [nimbus] detected framework: sveltekit (sveltekit-vite, conf=0.95)
+ */
+export declare function describeDetect(result: DetectResult): string;
+//# sourceMappingURL=framework-detect.d.ts.map

package/dist/runtime/framework-detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"framework-detect.d.ts","sourceRoot":"","sources":["../../src/runtime/framework-detect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,OAAO,GACP,MAAM,GACN,OAAO,GACP,WAAW,GACX,MAAM,GACN,UAAU,GACV,SAAS,CAAC;AAEd,MAAM,MAAM,UAAU,GAClB,UAAU,GACV,WAAW,GACX,UAAU,GACV,WAAW,GACX,gBAAgB,GAChB,WAAW,GACX,cAAc,GACd,SAAS,CAAC;AAEd,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE;QACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACtC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACzC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAClC,CAAC;IACF,2EAA2E;IAC3E,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACnB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,SAAS,CAAC;IACrB,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,UAAU,EAAE,UAAU,CAAC;CACxB;AA2BD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,YAAY,CAsBhE;AAwGD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAK3D"}

package/dist/runtime/framework-detect.js

@@ -0,0 +1,178 @@
+/**
+ * framework-detect.ts — single source of truth for "what kind of project
+ * is this?" Pure function — no I/O of its own. Takes a parsed
+ * package.json + a set of root-level filenames + (optional) per-file
+ * contents and returns a discriminated union.
+ *
+ * Resolution order (first match wins):
+ *
+ *   0. Wrangler-on-framework override:
+ *      `wrangler.{toml,jsonc,json}` at root AND any framework dep present
+ *      → framework: <fw>, devCommand: 'wrangler-dev'
+ *      W10's wrangler-dev path loads the framework's CF adapter.
+ *      MUST come first — Remix-on-CF and SK-on-CF projects have BOTH a
+ *      framework dep AND a wrangler config; without this rule W10's
+ *      path never sees them.
+ *
+ *   1. `next` in deps                            → 'next'
+ *   2. `astro` in deps                           → 'astro'
+ *   3. `nuxt` in deps                            → 'nuxt'
+ *   4. `@remix-run/dev` in deps AND vite.config* references @remix-run/dev
+ *                                                → 'remix'
+ *   5. `@sveltejs/kit` in deps                   → 'sveltekit'
+ *   6. (rule moved to step 0)
+ *   7. `wrangler.{toml,jsonc,json}` alone        → 'wrangler'
+ *   8. `vite` in deps                            → 'vite' (generic)
+ *   9. else                                      → 'unknown'
+ *
+ * Bare `@remix-run/react` without `@remix-run/dev` falls through to step 7
+ * — it's a runtime dep alone, not a Remix v2 vite-plugin project.
+ *
+ * See audit/sections/W11-plan.md §4 for the full spec + rationale.
+ */
+const WRANGLER_CONFIG_FILES = ['wrangler.toml', 'wrangler.jsonc', 'wrangler.json'];
+const VITE_CONFIG_FILES = ['vite.config.ts', 'vite.config.js', 'vite.config.mjs', 'vite.config.cjs'];
+function hasDep(pkg, name) {
+    return (!!(pkg.dependencies && pkg.dependencies[name]) ||
+        !!(pkg.devDependencies && pkg.devDependencies[name]));
+}
+function hasAnyFile(files, candidates) {
+    for (const c of candidates) {
+        if (files.has(c))
+            return c;
+    }
+    return null;
+}
+function readViteConfig(input) {
+    if (!input.fileContents)
+        return null;
+    for (const c of VITE_CONFIG_FILES) {
+        if (input.fileContents[c])
+            return { name: c, contents: input.fileContents[c] };
+    }
+    return null;
+}
+/**
+ * Detect what framework "owns" this project for purposes of routing
+ * `npm run dev`/`npm run build`. Pure; deterministic; no I/O.
+ */
+export function detectFramework(input) {
+    const { pkg, files } = input;
+    // ── Step 0: Wrangler-on-framework override ──────────────────────────
+    const wranglerCfg = hasAnyFile(files, WRANGLER_CONFIG_FILES);
+    if (wranglerCfg) {
+        // Determine the underlying framework first (informational).
+        const underlying = detectUnderlyingFramework(input);
+        if (underlying.framework !== 'unknown' && underlying.framework !== 'wrangler') {
+            return {
+                framework: underlying.framework,
+                confidence: 0.85,
+                reason: `wrangler config (${wranglerCfg}) AND ${underlying.reason} — routing through ` +
+                    `wrangler-dev so the framework's Cloudflare adapter loads.`,
+                devCommand: 'wrangler-dev',
+            };
+        }
+    }
+    // ── Steps 1-5 + 7-9: underlying framework (or generic) ───────────────
+    return detectUnderlyingFramework(input);
+}
+function detectUnderlyingFramework(input) {
+    const { pkg, files } = input;
+    // Step 1: Next.js
+    if (hasDep(pkg, 'next')) {
+        return {
+            framework: 'next',
+            confidence: 0.95,
+            reason: "found 'next' in dependencies",
+            devCommand: 'next-cli',
+        };
+    }
+    // Step 2: Astro
+    if (hasDep(pkg, 'astro')) {
+        return {
+            framework: 'astro',
+            confidence: 0.95,
+            reason: "found 'astro' in dependencies",
+            devCommand: 'astro-cli',
+        };
+    }
+    // Step 3: Nuxt
+    if (hasDep(pkg, 'nuxt')) {
+        return {
+            framework: 'nuxt',
+            confidence: 0.95,
+            reason: "found 'nuxt' in dependencies",
+            devCommand: 'nuxt-cli',
+        };
+    }
+    // Step 4: Remix v2 (vite-plugin path).
+    // Gate: @remix-run/dev in deps AND vite.config* references @remix-run/dev.
+    if (hasDep(pkg, '@remix-run/dev')) {
+        const cfg = readViteConfig(input);
+        if (cfg && cfg.contents.includes('@remix-run/dev')) {
+            return {
+                framework: 'remix',
+                confidence: 0.95,
+                reason: `found '@remix-run/dev' in deps and ${cfg.name} imports it`,
+                devCommand: 'remix-cli',
+            };
+        }
+        // Lower-confidence fallback: dep present but no contents to verify.
+        if (!input.fileContents) {
+            return {
+                framework: 'remix',
+                confidence: 0.7,
+                reason: "found '@remix-run/dev' in deps (vite.config contents not inspected)",
+                devCommand: 'remix-cli',
+            };
+        }
+        // Contents inspected and the import is missing — fall through.
+    }
+    // Step 5: SvelteKit
+    if (hasDep(pkg, '@sveltejs/kit')) {
+        return {
+            framework: 'sveltekit',
+            confidence: 0.95,
+            reason: "found '@sveltejs/kit' in dependencies",
+            devCommand: 'sveltekit-vite',
+        };
+    }
+    // Step 7: standalone wrangler (no framework deps)
+    if (hasAnyFile(files, WRANGLER_CONFIG_FILES) || hasDep(input.pkg, 'wrangler')) {
+        return {
+            framework: 'wrangler',
+            confidence: 0.85,
+            reason: "wrangler config or dep present, no framework dep — routing to wrangler-dev",
+            devCommand: 'wrangler-dev',
+        };
+    }
+    // Step 8: generic Vite
+    if (hasDep(pkg, 'vite')) {
+        return {
+            framework: 'vite',
+            confidence: 0.7,
+            reason: "found 'vite' in dependencies (no specific framework)",
+            devCommand: 'vite-real',
+        };
+    }
+    // Step 9: unknown
+    const depCount = Object.keys(pkg.dependencies || {}).length +
+        Object.keys(pkg.devDependencies || {}).length;
+    return {
+        framework: 'unknown',
+        confidence: depCount === 0 ? 0.1 : 0.3,
+        reason: depCount === 0
+            ? 'no dependencies declared'
+            : 'no recognized framework dep (next/astro/nuxt/remix/sveltekit/vite)',
+        devCommand: 'generic',
+    };
+}
+/**
+ * Companion helper: detection result is reportable as a one-line MOTD.
+ * Used by initSession to print a single boot line:
+ *   [nimbus] detected framework: sveltekit (sveltekit-vite, conf=0.95)
+ */
+export function describeDetect(result) {
+    return (`framework=${result.framework} dev=${result.devCommand} ` +
+        `confidence=${result.confidence.toFixed(2)} (${result.reason})`);
+}

package/dist/runtime/long-running-handle.d.ts

@@ -0,0 +1,133 @@
+/**
+ * long-running-handle.ts — generic adapter (primitive #3 + #4).
+ *
+ * Goal: any long-running thing in a Nimbus session that *behaves* like
+ * an HTTP server should plug into the supervisor's port registry the
+ * same way, so:
+ *
+ *   - `ps` shows it (via `processTable.spawn` + `setLongRunning`)
+ *   - `/preview/?port=N` routes to it
+ *   - `/preview/` routes to the default-target one
+ *   - `vite stop` / `kill <pid>` tears it down
+ *
+ * Today, two "long-running things" exist in-process:
+ *
+ *   1. ViteDevServer (the built-in Cirrus shim)
+ *   2. CirrusReal (the experimental real-vite facet)
+ *
+ * Both already expose a `handleRequest(request, pathname)` method.
+ * `PortRegistry` expects facets exposing `handleHttpRequest(request)`
+ * (single-arg, full request, with the inner path baked into the URL).
+ *
+ * `makeLongRunningPortStub` adapts the (request, pathname) shape into
+ * the (request) shape, by stripping a configurable `basePath` prefix
+ * from `request.url.pathname` and forwarding the rest. It is the ONE
+ * hook every future long-running thing will use; we do not write a new
+ * adapter per framework.
+ *
+ * NOTE: this is a SUPERVISOR-LOCAL stub, NOT a `WorkerEntrypoint`
+ * RPC stub. The port-registry handler at `routeRequest` happily
+ * accepts any object exposing `handleHttpRequest`, including in-DO
+ * wrappers. That is by design — a long-running facet is NOT required
+ * to live in a separate isolate; the routing primitive is the same
+ * either way.
+ */
+/**
+ * The minimal shape any long-running HTTP-like thing in a Nimbus
+ * session must expose to be registered as a port handler. The first
+ * arg is the original Request (in case the handler wants headers /
+ * body / method); the second is the inner path with any base-prefix
+ * already stripped, plus the original querystring.
+ */
+export interface LongRunningHttpHandler {
+    handleRequest(request: Request, innerPath: string): Promise<Response>;
+}
+/**
+ * Build a port-registry-compatible stub that forwards into the given
+ * handler.
+ *
+ * The supervisor calls `stub.handleHttpRequest(request)` with a request
+ * whose URL pathname is the path relative to the port (`PortRegistry`
+ * already strips the `/port/<n>` prefix). We pass that pathname to the
+ * underlying handler unchanged.
+ *
+ * Concretely: `GET /port/3000/api/users?id=42`
+ *   → port-registry rewrites url to `/api/users?id=42`
+ *   → stub.handleHttpRequest(req)  // req.url has /api/users?id=42
+ *   → handler.handleRequest(req, "/api/users?id=42")
+ */
+export declare function makeLongRunningPortStub(handler: LongRunningHttpHandler): {
+    handleHttpRequest(request: Request): Promise<Response>;
+};
+/**
+ * Parse `--port N`, `--port=N`, `-p N`, `-p=N` from argv. Returns the
+ * parsed integer, or null. Last-wins (so `--port 3000 --port 4000` →
+ * 4000), matching POSIX convention.
+ *
+ * Out-of-range or non-numeric values are returned as null without
+ * throwing — callers fall back to the next source (env, config, default).
+ */
+export declare function parsePortFromArgv(argv: string[]): number | null;
+/**
+ * Resolve a final port to bind to, given the various sources in
+ * priority order. Returns the first finite source.
+ *
+ *   1. argv flags (--port / -p)
+ *   2. env.PORT (post-shell-expansion; Markflow's `${PORT:-3000}` → 3000)
+ *   3. viteConfig.port (explicit `port: NNNN` in vite.config.ts)
+ *   4. fallback (caller-provided default, e.g. 5173 for vite, 3000 for express)
+ */
+export declare function resolveLongRunningPort(opts: {
+    argv?: string[];
+    env?: Record<string, any> | undefined;
+    configPort?: number | undefined;
+    fallback: number;
+}): number;
+/**
+ * Expand shell-style `${VAR}` and `${VAR:-default}` references in a
+ * single argv token, against the supplied env map.
+ *
+ * Nimbus's shell does not expand parameter substitution, so a
+ * package.json script line like
+ *
+ *     "dev": "vite --host 0.0.0.0 --port ${PORT:-3000}"
+ *
+ * arrives at the vite handler as the literal token `${PORT:-3000}`.
+ * Without expansion, `--port ${PORT:-3000}` is parsed as a non-numeric
+ * port and discarded. With expansion (against `env.PORT` falling back
+ * to `3000`), the user gets the port they asked for.
+ *
+ * Supports the two forms commonly seen in `package.json` scripts:
+ *
+ *   - ${VAR}             → env[VAR] || ''
+ *   - ${VAR:-default}    → env[VAR] || default
+ *   - ${VAR:-other_var}  → recursive (one level), so the default may
+ *                          itself reference an env var
+ *
+ * Does NOT support: command substitution, arithmetic substitution,
+ * pattern operators (`${VAR##pat}` etc.), positional params, glob.
+ * That is intentional — full shell semantics belong in the shell, not
+ * the argv expander; this helper covers ~95% of dev-script usage.
+ */
+export declare function expandShellDefaults(token: string, env: Record<string, any> | undefined): string;
+/**
+ * Apply `expandShellDefaults` to every argv token. Used at the top of
+ * a long-running handler before argv parsing so flag values are
+ * fully resolved.
+ */
+export declare function expandArgvShellDefaults(argv: ReadonlyArray<string>, env: Record<string, any> | undefined): string[];
+/**
+ * Pick the default `/preview/` target when no `?port=N` is supplied
+ * AND no in-process `viteDevServer` is currently running. The strategy
+ * is "first PortRegistry entry, ordered by registration time" — so if
+ * a session has only one long-running thing (Markflow's vite on :3000),
+ * `/preview/` lands on it without the user supplying a port.
+ *
+ * Returns null if the registry is empty, in which case the caller
+ * surfaces the existing "no dev server running" placeholder.
+ */
+export declare function pickDefaultPreviewPort(ports: ReadonlyArray<{
+    port: number;
+    registeredAt: number;
+}>): number | null;
+//# sourceMappingURL=long-running-handle.d.ts.map

package/dist/runtime/long-running-handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"long-running-handle.d.ts","sourceRoot":"","sources":["../../src/runtime/long-running-handle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACvE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,sBAAsB;+BAElC,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;EAM/D;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAkB/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;IACtC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,MAAM,CAYT;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GACnC,MAAM,CAiBR;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,EAC3B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GACnC,MAAM,EAAE,CAEV;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC,GAC3D,MAAM,GAAG,IAAI,CASf"}