@nimbus-sh/core 0.1.0

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

@@ -0,0 +1,70 @@
+/**
+ * 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.
+ *
+ */
+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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;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,177 @@
+/**
+ * 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.
+ *
+ */
+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/import-meta-transform.d.ts

@@ -0,0 +1,3 @@
+export declare function importMetaDefines(absUrl: string): Record<string, string>;
+export declare function bindImportMetaResolve(source: string, absUrl: string): string;
+//# sourceMappingURL=import-meta-transform.d.ts.map

package/dist/runtime/import-meta-transform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-meta-transform.d.ts","sourceRoot":"","sources":["../../src/runtime/import-meta-transform.ts"],"names":[],"mappings":"AAEA,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAKxE;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAM5E"}

package/dist/runtime/import-meta-transform.js

@@ -0,0 +1,15 @@
+const IMPORT_META_RESOLVE_HELPER = '__nimbusImportMetaResolveForModule';
+export function importMetaDefines(absUrl) {
+    return {
+        'import.meta.url': JSON.stringify(absUrl),
+        'import.meta.resolve': IMPORT_META_RESOLVE_HELPER,
+    };
+}
+export function bindImportMetaResolve(source, absUrl) {
+    if (!source.includes(IMPORT_META_RESOLVE_HELPER))
+        return source;
+    return [
+        `const ${IMPORT_META_RESOLVE_HELPER} = (specifier) => globalThis.__nimbusImportMetaResolve(specifier, ${JSON.stringify(absUrl)});`,
+        source,
+    ].join('\n');
+}

package/dist/runtime/javascript-ast.d.ts

@@ -0,0 +1,13 @@
+import { type AnyNode } from 'acorn';
+export type AstNode = AnyNode & Record<string, unknown>;
+export declare function parseJavaScriptModule(source: string): AstNode;
+export declare function hasTopLevelModuleSyntax(source: string): boolean;
+export declare function nodeList(node: AstNode, key: string): AstNode[];
+export declare function nodeProp(node: AstNode | undefined, key: string): AstNode | undefined;
+export declare function nodeName(node: AstNode | undefined): string | undefined;
+export declare function stringField(node: AstNode, key: string): string | undefined;
+export declare function booleanField(node: AstNode, key: string): boolean;
+export declare function literalStringValue(node: AstNode | undefined): string | undefined;
+export declare function literalBooleanValue(node: AstNode | undefined): boolean | undefined;
+export declare function isAstNode(value: unknown): value is AstNode;
+//# sourceMappingURL=javascript-ast.d.ts.map

package/dist/runtime/javascript-ast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"javascript-ast.d.ts","sourceRoot":"","sources":["../../src/runtime/javascript-ast.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,OAAO,EAAE,MAAM,OAAO,CAAC;AAE5C,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAExD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAM7D;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAa/D;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,EAAE,CAI9D;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAIpF;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAItE;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG1E;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAGhE;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAEhF;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAElF;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAE1D"}

package/dist/runtime/javascript-ast.js

@@ -0,0 +1,57 @@
+import { parse } from 'acorn';
+export function parseJavaScriptModule(source) {
+    return parse(source, {
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+        allowHashBang: true,
+    });
+}
+export function hasTopLevelModuleSyntax(source) {
+    let ast;
+    try {
+        ast = parseJavaScriptModule(source);
+    }
+    catch {
+        return false;
+    }
+    return nodeList(ast, 'body').some((node) => node.type === 'ImportDeclaration' ||
+        node.type === 'ExportNamedDeclaration' ||
+        node.type === 'ExportDefaultDeclaration' ||
+        node.type === 'ExportAllDeclaration');
+}
+export function nodeList(node, key) {
+    const value = node[key];
+    if (!Array.isArray(value))
+        return [];
+    return value.filter(isAstNode);
+}
+export function nodeProp(node, key) {
+    if (!node)
+        return undefined;
+    const value = node[key];
+    return isAstNode(value) ? value : undefined;
+}
+export function nodeName(node) {
+    if (node?.type !== 'Identifier' && node?.type !== 'Literal')
+        return undefined;
+    if (node.type === 'Identifier')
+        return stringField(node, 'name');
+    return literalStringValue(node);
+}
+export function stringField(node, key) {
+    const value = node[key];
+    return typeof value === 'string' ? value : undefined;
+}
+export function booleanField(node, key) {
+    const value = node[key];
+    return typeof value === 'boolean' ? value : false;
+}
+export function literalStringValue(node) {
+    return node?.type === 'Literal' && typeof node.value === 'string' ? node.value : undefined;
+}
+export function literalBooleanValue(node) {
+    return node?.type === 'Literal' && typeof node.value === 'boolean' ? node.value : undefined;
+}
+export function isAstNode(value) {
+    return !!value && typeof value === 'object' && typeof value.type === 'string';
+}

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

@@ -0,0 +1,119 @@
+/**
+ * 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 the process supervisor's long-running spawn)
+ *   - `/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[];
+//# 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"}

package/dist/runtime/long-running-handle.js

@@ -0,0 +1,169 @@
+/**
+ * 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 the process supervisor's long-running spawn)
+ *   - `/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.
+ */
+/**
+ * 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 function makeLongRunningPortStub(handler) {
+    return {
+        async handleHttpRequest(request) {
+            const url = new URL(request.url);
+            const innerPath = (url.pathname || '/') + url.search;
+            return handler.handleRequest(request, innerPath);
+        },
+    };
+}
+/**
+ * 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 function parsePortFromArgv(argv) {
+    let result = null;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        let candidate;
+        if (a === '--port' || a === '-p') {
+            candidate = argv[i + 1];
+            i++;
+        }
+        else if (a.startsWith('--port=')) {
+            candidate = a.slice('--port='.length);
+        }
+        else if (a.startsWith('-p=')) {
+            candidate = a.slice('-p='.length);
+        }
+        if (!candidate)
+            continue;
+        const n = parseInt(candidate, 10);
+        if (Number.isFinite(n) && n > 0 && n < 65536)
+            result = n;
+    }
+    return result;
+}
+/**
+ * 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 function resolveLongRunningPort(opts) {
+    const argvPort = opts.argv ? parsePortFromArgv(opts.argv) : null;
+    if (argvPort)
+        return argvPort;
+    const envPortStr = opts.env?.PORT;
+    if (envPortStr !== undefined && envPortStr !== null && envPortStr !== '') {
+        const n = parseInt(String(envPortStr), 10);
+        if (Number.isFinite(n) && n > 0 && n < 65536)
+            return n;
+    }
+    if (opts.configPort && opts.configPort > 0 && opts.configPort < 65536) {
+        return opts.configPort;
+    }
+    return opts.fallback;
+}
+/**
+ * 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 function expandShellDefaults(token, env) {
+    if (!token || token.indexOf('${') < 0)
+        return token;
+    const lookup = (name) => {
+        const v = env?.[name];
+        if (v === undefined || v === null || v === '')
+            return undefined;
+        return String(v);
+    };
+    // ${VAR:-default}, ${VAR}. One pass; default value is itself
+    // recursively expanded once.
+    return token.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g, (_m, name, def) => {
+        const v = lookup(name);
+        if (v !== undefined)
+            return v;
+        if (def === undefined)
+            return '';
+        // One recursion level so `${PORT:-${PORT_FALLBACK:-3000}}` works.
+        if (def.indexOf('${') >= 0)
+            return expandShellDefaults(def, env);
+        return def;
+    });
+}
+/**
+ * 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 function expandArgvShellDefaults(argv, env) {
+    return argv.map((t) => expandShellDefaults(t, env));
+}

package/dist/runtime/module-source-rewriter.d.ts

@@ -0,0 +1,11 @@
+export interface StaticModuleSpecifierContext {
+    nodeType: string;
+    isSideEffectImport: boolean;
+}
+export interface ModuleSourceRewriteOptions {
+    staticSpecifier(specifier: string, context: StaticModuleSpecifierContext): string | undefined;
+    dynamicImport?(specifier: string): string | undefined;
+    createRequireCallee?: string;
+}
+export declare function rewriteJavaScriptModuleSource(source: string, options: ModuleSourceRewriteOptions): string;
+//# sourceMappingURL=module-source-rewriter.d.ts.map

package/dist/runtime/module-source-rewriter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-source-rewriter.d.ts","sourceRoot":"","sources":["../../src/runtime/module-source-rewriter.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,0BAA0B;IACzC,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,4BAA4B,GAAG,MAAM,GAAG,SAAS,CAAC;IAC9F,aAAa,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACtD,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,0BAA0B,GAClC,MAAM,CAuBR"}