@nimbus-sh/worker 0.1.0

package/dist/runtime/comment-strip.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Minimal byte-aligned comment stripper for prefetch's import detection.
+ *
+ * Scope: strip `//` line comments and `/* … *\/` block comments by
+ * replacing each comment with a single space. Newlines INSIDE the
+ * comment are preserved so that line numbers stay aligned with the
+ * input (matches the strip-and-classify pattern used by
+ * `esbuild-service.ts:stripCommentsAndStrings` for the transform
+ * pipeline).
+ *
+ * Why a separate, smaller scanner: prefetch's IMPORT_RE / REQUIRE_RE
+ * in `require-resolver.ts:41,87` are detection-only — they extract
+ * specifier strings, not shapes. The full string-and-template-literal
+ * stripper in `esbuild-service.ts` is overkill for that, and crossing
+ * the anti-touch boundary on `esbuild-service.ts` to extend a single
+ * shared helper isn't worth it right now.
+ *
+ * Empirical justification (esbuild-ast-rewrite wave, P2 measurement):
+ *   - Per-file AST-based extraction: ~5 ms warm avg
+ *   - 100-file session bootstrap with AST: ~553 ms (over the 500 ms gate)
+ *   - Regex with this stripper: ~0.1 ms per file
+ *   - Correctness gap closed: chalk `import { // eslint-disable\n   a,\n   b\n} from './utilities.js'` now matches
+ *
+ * String-literal handling is intentionally OUT of scope. A literal
+ * `import x from 'y'` inside a JavaScript string would still produce
+ * a false-positive prefetch attempt. The resolver no-ops on misses,
+ * so it's a minor wasted-work cost — see IMPORT_RE header comment in
+ * `require-resolver.ts:84-86`.
+ *
+ * TODO(CLN-X): when the `src/runtime/esbuild-service.ts` anti-touch
+ * window opens, unify with the canonical
+ * `stripCommentsAndStrings(src)` helper there. Both implement the
+ * same logical pass over comments; only the string/regex-literal
+ * handling differs.
+ */
+export declare function stripCommentsForImports(src: string): string;
+//# sourceMappingURL=comment-strip.d.ts.map

package/dist/runtime/comment-strip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comment-strip.d.ts","sourceRoot":"","sources":["../../src/runtime/comment-strip.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAqC3D"}

package/dist/runtime/comment-strip.js

@@ -0,0 +1,74 @@
+/**
+ * Minimal byte-aligned comment stripper for prefetch's import detection.
+ *
+ * Scope: strip `//` line comments and `/* … *\/` block comments by
+ * replacing each comment with a single space. Newlines INSIDE the
+ * comment are preserved so that line numbers stay aligned with the
+ * input (matches the strip-and-classify pattern used by
+ * `esbuild-service.ts:stripCommentsAndStrings` for the transform
+ * pipeline).
+ *
+ * Why a separate, smaller scanner: prefetch's IMPORT_RE / REQUIRE_RE
+ * in `require-resolver.ts:41,87` are detection-only — they extract
+ * specifier strings, not shapes. The full string-and-template-literal
+ * stripper in `esbuild-service.ts` is overkill for that, and crossing
+ * the anti-touch boundary on `esbuild-service.ts` to extend a single
+ * shared helper isn't worth it right now.
+ *
+ * Empirical justification (esbuild-ast-rewrite wave, P2 measurement):
+ *   - Per-file AST-based extraction: ~5 ms warm avg
+ *   - 100-file session bootstrap with AST: ~553 ms (over the 500 ms gate)
+ *   - Regex with this stripper: ~0.1 ms per file
+ *   - Correctness gap closed: chalk `import { // eslint-disable\n   a,\n   b\n} from './utilities.js'` now matches
+ *
+ * String-literal handling is intentionally OUT of scope. A literal
+ * `import x from 'y'` inside a JavaScript string would still produce
+ * a false-positive prefetch attempt. The resolver no-ops on misses,
+ * so it's a minor wasted-work cost — see IMPORT_RE header comment in
+ * `require-resolver.ts:84-86`.
+ *
+ * TODO(CLN-X): when the `src/runtime/esbuild-service.ts` anti-touch
+ * window opens, unify with the canonical
+ * `stripCommentsAndStrings(src)` helper there. Both implement the
+ * same logical pass over comments; only the string/regex-literal
+ * handling differs.
+ */
+export function stripCommentsForImports(src) {
+    let out = '';
+    let i = 0;
+    const N = src.length;
+    while (i < N) {
+        const c = src[i];
+        // Line comment: `//` to end-of-line.
+        if (c === '/' && src[i + 1] === '/') {
+            out += ' ';
+            i += 2;
+            while (i < N && src[i] !== '\n')
+                i++;
+            // Newline preserved by falling through; do NOT consume it.
+            continue;
+        }
+        // Block comment: `/*` to `*/`.
+        if (c === '/' && src[i + 1] === '*') {
+            i += 2;
+            while (i < N) {
+                if (src[i] === '\n') {
+                    // Preserve newlines so line numbers stay aligned.
+                    out += '\n';
+                    i++;
+                    continue;
+                }
+                if (src[i] === '*' && src[i + 1] === '/') {
+                    i += 2;
+                    out += ' ';
+                    break;
+                }
+                i++;
+            }
+            continue;
+        }
+        out += c;
+        i++;
+    }
+    return out;
+}

package/dist/runtime/esbuild-service.d.ts

@@ -0,0 +1,201 @@
+/**
+ * EsbuildService — TypeScript/JSX transform + bundling via esbuild-wasm.
+ *
+ * Architecture:
+ *   - esbuild-wasm is imported directly in the supervisor bundle
+ *   - WASM is compiled during module evaluation (startup phase) — allowed
+ *   - transform() runs in the supervisor's isolate (fast, no facet needed)
+ *   - build() also runs in supervisor with a VFS resolver plugin
+ *
+ * Why not a facet? The esbuild-wasm WASM binary needs to be compiled
+ * during module startup (not request time). Dynamic workers created via
+ * LOADER.load() have the same restriction. Since esbuild-wasm is bundled
+ * into the supervisor, it initializes once at startup and stays warm.
+ *
+ * Memory: esbuild-wasm uses ~15-20MB heap. Within the DO's 128MB budget
+ * this is acceptable for Phase 3. Phase 4+ can move it to a dedicated
+ * facet once wasm module passing to dynamic workers is stable.
+ */
+import type { SqliteVFS } from '../vfs/sqlite-vfs.js';
+/**
+ * Bundler version tag. BUMP THIS whenever bundling semantics change —
+ * the esbuild plugin's resolver logic, the shared-externals rules, the
+ * post-processing pipeline, or anything that would invalidate cached
+ * pre-bundles. The version is stored in pkg_esm_bundles.bundle_hash and
+ * checked on read; cache entries with a different version are treated
+ * as missing and rebuilt from scratch.
+ *
+ * History:
+ *   v1 — initial pre-bundling
+ *   v2 — shared React externals, CJS named exports
+ *   v3 — Node subpath imports (#foo) support for vfile/unified ecosystem
+ *   v4 — legacy flat-subpath resolution (pkg/sub without exports field);
+ *        CDN fallback wrapper no longer crashes on modules without default
+ *   v5 — normalize `../` segments in joined entry paths (react-remove-scroll-bar
+ *        style: nested package.json with "module": "../dist/es2015/foo.js")
+ *   v6 — externals enforced via plugin onResolve only (top-level `external:`
+ *        dropped). Fixes dual-React-instance bug where jsx-runtime and
+ *        react-dom/client were inlining their own copy of react because
+ *        esbuild's entry-point external check rejected the externals when
+ *        passed at the top level. v5 cache entries are wrong (contain
+ *        embedded react copies) and must be invalidated.
+ */
+export declare const BUNDLER_VERSION = "v6";
+/**
+ * Returns the list of specifiers that must be marked `external` when bundling
+ * `specifier` so that React / React-DOM / Scheduler share a single instance
+ * across all /@modules/ bundles.
+ *
+ * Why: React uses an internal module-scoped singleton
+ * (`__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED`) for current dispatcher,
+ * owner, etc. If two bundles each contain their own embedded React, they each
+ * have their own singleton, and `createRoot` from one bundle sees JSX elements
+ * created by the other as "alien" — silent render failure (root stays empty).
+ *
+ * The fix: when bundling react-dom/*, mark react/* and scheduler as external.
+ * The bundler leaves `import {...} from "react"` in the output; the browser
+ * then fetches /preview/@modules/react, which is the SAME URL the jsx-runtime
+ * bundle imports — so both react-dom and jsx-runtime share ONE React instance.
+ *
+ * Similarly for react/jsx-runtime and react/jsx-dev-runtime (they must share
+ * react's internals), we externalize `react` (but not `scheduler` — jsx-runtime
+ * doesn't need it).
+ */
+export declare function getSharedRuntimeExternals(specifier: string): string[];
+export interface TransformResult {
+    code: string;
+    map: string;
+    warnings: {
+        text: string;
+        location?: any;
+    }[];
+}
+export interface BuildOutputFile {
+    path: string;
+    contents: string;
+}
+export interface BuildResult {
+    outputFiles: BuildOutputFile[];
+    errors: {
+        text: string;
+        location?: any;
+    }[];
+    warnings: {
+        text: string;
+        location?: any;
+    }[];
+}
+export declare class EsbuildService {
+    private vfs;
+    private initialized;
+    private initPromise;
+    /** Resolved esbuild namespace — populated by ensureInit() after loadEsbuild(). */
+    private _esbuild;
+    constructor(vfs: SqliteVFS);
+    /**
+     * Initialize esbuild-wasm (lazy, on first use). Loads the namespace
+     * via `loadEsbuild()` (which itself is deferred) and caches it on
+     * `this._esbuild` so subsequent calls don't pay the dynamic-import
+     * overhead. All call sites that previously used the top-level
+     * `esbuild` namespace now use `this._esbuild!` after `await this.ensureInit()`.
+     */
+    private ensureInit;
+    /**
+     * Transform a single code string (TS→JS, JSX→JS, minify, etc.)
+     *
+     * Top-level await note (gap #2 in framework-gaps-fix):
+     * ─────────────────────────────────────────────────────
+     * esbuild rejects top-level await when output format is 'cjs' or
+     * 'iife' — neither has a runtime primitive for it. Real Node
+     * supports TLA only in ESM. Nimbus's facet wrapper executes the
+     * transformed code via `new Function(...)` which is CJS-shaped.
+     *
+     * Several modern CLIs (nuxi, vite-cli, oclif's lazy-load bootstrap,
+     * many ESM-only-by-default tools) use TLA at the entry point. With
+     * format:'cjs' those would crash with "Top-level await is currently
+     * not supported with the 'cjs' output format" — an esbuild
+     * SyntaxError surfaced as a Nimbus diagnostic. The user can't
+     * fix this without rewriting upstream.
+     *
+     * Fix: when caller asks for format 'cjs' AND the source has a
+     * top-level await, wrap the source in an async IIFE:
+     *
+     *     ;(async () => {
+     *       <original-source>
+     *     })();
+     *
+     * Inside the IIFE, await is legal.
+     *
+     * ESM-imports-in-CJS note (nuxt-esm-in-cjs wave):
+     * ─────────────────────────────────────────────────
+     * The IIFE wrap above moves the user source INTO a function body.
+     * Top-level ESM `import` statements are LEGAL only at module top
+     * level — inside a function body they're a SyntaxError. Real-world
+     * trigger: nuxi's `bin/nuxi.mjs` opens with `import { performance }
+     * from "node:perf_hooks"` and ends with `const { runMain } = await
+     * import("./dist/index.mjs"); runMain()` — both ESM imports AND TLA.
+     * Pre-fix the IIFE wrap caused esbuild to fail with
+     * `Unexpected "<binding>"` at line 3 of stdin.
+     *
+     * Fix: when TLA AND ESM imports coexist, run a two-stage transform:
+     *   1. Pass 1: `esbuild.transform(code, { format: 'esm', ... })` —
+     *      esbuild accepts TLA + imports cleanly when emitting ESM.
+     *      Output is JS-canonicalised: multi-line imports collapsed,
+     *      bindings normalised, etc.
+     *   2. Extract top-level imports from the pass-1 output and rewrite
+     *      them as `const X = require(...)` shims (see
+     *      `convertEsmImportsToRequire` for the contract / shape).
+     *   3. Wrap the remaining body in the async IIFE.
+     *   4. Return the assembled string as the transform result.
+     *
+     * The require-shim emits the standard `__esModule` interop check
+     * (matches what esbuild itself emits for ESM→CJS conversions), so
+     * default-export binding semantics are preserved.
+     *
+     * If TLA but no ESM imports → existing single-pass IIFE wrap.
+     * If ESM imports but no TLA → existing single-pass esbuild
+     * format:cjs (it auto-converts ESM→CJS gracefully).
+     *
+     * This is bytes-stable for sources outside the TLA+ESM-imports
+     * intersection.
+     */
+    transform(code: string, options?: {
+        loader?: 'ts' | 'tsx' | 'jsx' | 'js' | 'css' | 'json';
+        format?: 'esm' | 'cjs' | 'iife';
+        target?: string;
+        sourcemap?: boolean | 'inline' | 'external';
+        minify?: boolean;
+        jsx?: 'transform' | 'preserve' | 'automatic';
+        jsxFactory?: string;
+        jsxFragment?: string;
+        tsconfigRaw?: string;
+        define?: Record<string, string>;
+    }): Promise<TransformResult>;
+    /**
+     * Bundle entry points from the VFS.
+     */
+    build(entryPoints: string[], options?: {
+        bundle?: boolean;
+        format?: 'esm' | 'cjs' | 'iife';
+        target?: string;
+        platform?: 'browser' | 'node' | 'neutral';
+        outdir?: string;
+        outfile?: string;
+        sourcemap?: boolean | 'inline' | 'external';
+        minify?: boolean;
+        external?: string[];
+        define?: Record<string, string>;
+        globalName?: string;
+        tsconfigRaw?: string;
+        alias?: Record<string, string>;
+        keepNames?: boolean;
+    }): Promise<BuildResult>;
+    /**
+     * VFS resolver plugin for esbuild.
+     * Reads directly from the SqliteVFS (synchronous, co-located — no snapshot needed).
+     * Handles: absolute paths, relative paths, bare specifiers (node_modules).
+     */
+    private makeVfsPlugin;
+    get isInitialized(): boolean;
+}
+//# sourceMappingURL=esbuild-service.d.ts.map

package/dist/runtime/esbuild-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"esbuild-service.d.ts","sourceRoot":"","sources":["../../src/runtime/esbuild-service.ts"],"names":[],"mappings":"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"}