@nimbus-sh/core 0.1.0

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/cpython-preamble.d.ts

@@ -0,0 +1,32 @@
+/**
+ * cpython-preamble.ts — the guest half of the CPython runtime, as source.
+ *
+ * This text is spliced into a loader child's module scope, after the WASI host
+ * from runtime/wasi/preamble.ts and the virtual socket kernel. It owns exactly
+ * one thing: turning a compiled python.wasm into a running interpreter and
+ * feeding it source. Everything about WHAT to run belongs to cpython-runner.ts.
+ *
+ * Three constraints shape it, all of them learned the expensive way:
+ *
+ *   1. Every entry into the VM goes through `enterVm`, which is
+ *      WebAssembly.promising. Not just the calls known to park today — V8 traps
+ *      ANY call into a WebAssembly.Suspending import from a stack that
+ *      promising did not enter, including one that returns a plain integer.
+ *      Which imports the interpreter reaches is the interpreter's business and
+ *      the suspending set grows.
+ *
+ *   2. __wasiInitFS deliberately clears the adopted supervisor, so the
+ *      supervisor is adopted AFTER it, never before. The other order leaves the
+ *      guest reading a filesystem it can never write back to, which looks like
+ *      success right up until the writes are gone.
+ *
+ *   3. The interpreter is compiled once, in the child-init window where
+ *      compilation is allowed, and instantiated per call. Instantiation is not
+ *      gated; only compilation is. A fresh instance per one-shot invocation is
+ *      also what makes each `python -c` a pristine interpreter rather than one
+ *      carrying the last caller's __main__.
+ */
+/** Marker the runner writes around the interpreter's exit status. */
+export declare const CPYTHON_EXIT_MARKER = "__NIMBUS_PY_EXIT__";
+export declare const CPYTHON_PREAMBLE_TAIL: string;
+//# sourceMappingURL=cpython-preamble.d.ts.map

package/dist/runtime/cpython-preamble.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cpython-preamble.d.ts","sourceRoot":"","sources":["../../src/runtime/cpython-preamble.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,qEAAqE;AACrE,eAAO,MAAM,mBAAmB,uBAAuB,CAAC;AAExD,eAAO,MAAM,qBAAqB,QAyQjC,CAAC"}

package/dist/runtime/cpython-preamble.js

@@ -0,0 +1,296 @@
+/**
+ * cpython-preamble.ts — the guest half of the CPython runtime, as source.
+ *
+ * This text is spliced into a loader child's module scope, after the WASI host
+ * from runtime/wasi/preamble.ts and the virtual socket kernel. It owns exactly
+ * one thing: turning a compiled python.wasm into a running interpreter and
+ * feeding it source. Everything about WHAT to run belongs to cpython-runner.ts.
+ *
+ * Three constraints shape it, all of them learned the expensive way:
+ *
+ *   1. Every entry into the VM goes through `enterVm`, which is
+ *      WebAssembly.promising. Not just the calls known to park today — V8 traps
+ *      ANY call into a WebAssembly.Suspending import from a stack that
+ *      promising did not enter, including one that returns a plain integer.
+ *      Which imports the interpreter reaches is the interpreter's business and
+ *      the suspending set grows.
+ *
+ *   2. __wasiInitFS deliberately clears the adopted supervisor, so the
+ *      supervisor is adopted AFTER it, never before. The other order leaves the
+ *      guest reading a filesystem it can never write back to, which looks like
+ *      success right up until the writes are gone.
+ *
+ *   3. The interpreter is compiled once, in the child-init window where
+ *      compilation is allowed, and instantiated per call. Instantiation is not
+ *      gated; only compilation is. A fresh instance per one-shot invocation is
+ *      also what makes each `python -c` a pristine interpreter rather than one
+ *      carrying the last caller's __main__.
+ */
+/** Marker the runner writes around the interpreter's exit status. */
+export const CPYTHON_EXIT_MARKER = '__NIMBUS_PY_EXIT__';
+export const CPYTHON_PREAMBLE_TAIL = String.raw `
+// ── CPython guest runtime ──────────────────────────────────────────────────
+globalThis.__nimbusPyStdout = globalThis.__nimbusPyStdout || [];
+globalThis.__nimbusPyStderr = globalThis.__nimbusPyStderr || [];
+
+// The only way into the VM. See constraint (1) above.
+const __nimbusEnterVm = (fn) =>
+  (typeof WebAssembly.promising === 'function' ? WebAssembly.promising(fn) : fn);
+
+function __nimbusPyModule() {
+  const table = globalThis.__NIMBUS_WASM || {};
+  const mod = table['python.wasm'];
+  if (!mod) throw new Error('python.wasm was not supplied to this facet');
+  return mod;
+}
+
+// Bring up one interpreter over the seeded filesystem and return the handles
+// the rest of this file drives it with.
+async function __nimbusPyBoot(args) {
+  const snapshot = args.fsSnapshot || { files: {}, dirs: [], modes: {}, root: '' };
+  __wasiInitFS({
+    root: snapshot.root || '',
+    preopens: [{ wasiPath: '/', vfsPath: '' }],
+    files: snapshot.files || {},
+    dirs: snapshot.dirs || [],
+    // The root, /tmp and /home are seeded rather than taken from the manifest:
+    // manifestVfs's walk skips the empty root, so without this the preopen at
+    // '/' has effective mode 0 and EVERY traversal through it is EACCES —
+    // which surfaces as "Failed to import encodings module" with nothing
+    // pointing at a permission. Same baseline ruby-runner seeds, same reason.
+    modes: { '': 7, tmp: 7, home: 7, ...(snapshot.modes || {}) },
+    times: snapshot.times,
+    symlinks: snapshot.symlinks,
+    sizes: snapshot.sizes,
+  });
+  // AFTER initFS, never before. See constraint (2). The stub is read back off
+  // globalThis rather than passed in, because the facet entry point published
+  // it there before initFS wiped the adoption.
+  if (typeof __wasiAdoptSupervisor === 'function') {
+    __wasiAdoptSupervisor(globalThis.__nimbusPySupervisor);
+  }
+
+  let instance = null;
+  const made = __wasiMakeImports({
+    argv: args.pyArgv || ['python'],
+    env: args.userEnv || {},
+    getMemory: () => instance.exports.memory,
+    stdoutWrite: (s) => { globalThis.__nimbusPyStdout.push(s); },
+    stderrWrite: (s) => { globalThis.__nimbusPyStderr.push(s); },
+  });
+  instance = new WebAssembly.Instance(__nimbusPyModule(), { wasi_snapshot_preview1: made.wasiImport });
+
+  const exports = instance.exports;
+  if (typeof exports.nimbus_py_init !== 'function' || typeof exports.nimbus_py_run !== 'function') {
+    throw new Error('python.wasm is not a Nimbus reactor build (nimbus_py_init/nimbus_py_run missing)');
+  }
+
+  const withCString = async (text, fn) => {
+    const bytes = new TextEncoder().encode(text);
+    const ptr = exports.malloc(bytes.length + 1);
+    if (!ptr) throw new Error('the interpreter is out of memory');
+    // Taken after malloc and used before the next guest call: growing the
+    // wasm memory detaches every view over the old buffer.
+    const view = new Uint8Array(exports.memory.buffer, ptr, bytes.length + 1);
+    view.set(bytes);
+    view[bytes.length] = 0;
+    try { return await fn(ptr); } finally { exports.free(ptr); }
+  };
+
+  // _initialize is static setup only, so it is safe anywhere. Py_Initialize
+  // reads entropy through random_get, which workerd refuses in module scope —
+  // both run here, at request time.
+  await __nimbusEnterVm(exports._initialize)();
+  const initRc = await withCString(args.pythonHome || '/usr/local',
+    (ptr) => __nimbusEnterVm(exports.nimbus_py_init)(ptr));
+  if (initRc !== 0) {
+    // Do the bytes arrive intact? The interpreter, the stdlib and this preamble
+    // are all proven by tests/unit/cpython-wasi-reactor.mjs, which seeds the
+    // stdlib BY VALUE. The only thing a live session changes is the transport:
+    // manifest entry + supervisor RPC. So hash what the transport actually
+    // delivers rather than guessing at a size limit.
+    let transport = 'not-attempted';
+    try {
+      const zipPath = (args.pythonHome || '').replace(/^\/+/, '') + '/lib/python313.zip';
+      const want = __wasiFS.sizes.get(zipPath);
+      const sup = globalThis.__nimbusPySupervisor;
+      if (!sup || typeof sup.fsReadRange !== 'function') {
+        transport = 'no-supervisor';
+      } else {
+        const got = await sup.fsReadRange(zipPath, 0, want);
+        const bytes = got instanceof Uint8Array ? got : new Uint8Array(got);
+        const digest = await crypto.subtle.digest('SHA-256', bytes);
+        const hex = Array.from(new Uint8Array(digest))
+          .map((b) => b.toString(16).padStart(2, '0')).join('');
+        transport = 'want=' + want + ' got=' + bytes.byteLength + ' sha=' + hex.slice(0, 16);
+      }
+    } catch (e) { transport = 'threw ' + ((e && e.message) || e); }
+
+    // CPython's own message for an unreadable stdlib is "Failed to import
+    // encodings module", which says nothing about where it looked or why the
+    // read failed. These three facts are what separated a mode-0 root from a
+    // missing supervisor from an absent JSPI, each of which presents
+    // identically.
+    throw new Error('the interpreter failed to start: home=' + (args.pythonHome || '/usr/local')
+      + ' supervisor=' + (globalThis.__nimbusPySupervisor ? 'yes' : 'NO')
+      + ' promising=' + (typeof WebAssembly.promising === 'function' ? 'yes' : 'NO')
+      + ' transport[' + transport + ']');
+  }
+
+  return {
+    instance,
+    run: (src) => withCString(src, (ptr) => __nimbusEnterVm(exports.nimbus_py_run)(ptr)),
+    flush: () => __nimbusEnterVm(exports.nimbus_py_flush)(),
+  };
+}
+
+// Ports are the host's to allocate, so the guest cannot bind one by itself:
+// nimbus-net.c's listen(2) opens /dev/nimbus/listen/<port>, which is only a
+// listening descriptor once the kernel has the port. This is the same callback
+// ruby-runner installs, for the same reason and under the same name — one
+// binding convention, not one per language.
+globalThis.__nimbusVirtualSocketDidListen = globalThis.__nimbusVirtualSocketDidListen
+  || function __nimbusVirtualSocketDidListen(port) {
+    const supervisor = globalThis.__nimbusPySupervisor;
+    if (!supervisor || typeof supervisor.registerPort !== 'function') return;
+    try {
+      const p = supervisor.registerPort(Number(port)).catch((e) => {
+        globalThis.__nimbusPyStderr.push(
+          '[cpython-runner] port registration failed: ' + ((e && e.message) || e) + '\n');
+      });
+      (globalThis.__nimbusVirtualPortRegistrationPromises
+        = globalThis.__nimbusVirtualPortRegistrationPromises || []).push(p);
+    } catch (e) {
+      globalThis.__nimbusPyStderr.push(
+        '[cpython-runner] port registration failed: ' + ((e && e.message) || e) + '\n');
+    }
+  };
+
+globalThis.__nimbusVirtualSocketRouteLoopback = globalThis.__nimbusVirtualSocketRouteLoopback
+  || function __nimbusVirtualSocketRouteLoopback(port, request) {
+    const supervisor = globalThis.__nimbusPySupervisor;
+    if (!supervisor || typeof supervisor.routeLoopback !== 'function') {
+      return Promise.reject(new Error('this Python process has no supervisor binding for loopback routing'));
+    }
+    return Promise.resolve(supervisor.routeLoopback(Number(port), request));
+  };
+
+// ── One-shot entry point ───────────────────────────────────────────────────
+// A fresh interpreter per call. See constraint (3).
+globalThis.__cpythonRun = async function __cpythonRun(args) {
+  const stdoutStart = globalThis.__nimbusPyStdout.length;
+  const stderrStart = globalThis.__nimbusPyStderr.length;
+  const drain = () => ({
+    stdout: globalThis.__nimbusPyStdout.slice(stdoutStart).join(''),
+    stderr: globalThis.__nimbusPyStderr.slice(stderrStart).join(''),
+  });
+  let boot;
+  try {
+    boot = await __nimbusPyBoot(args);
+  } catch (e) {
+    return { exitCode: 1, ...drain(), error: (e && e.message) || String(e) };
+  }
+  try {
+    const exitCode = await boot.run(args.userCode || '');
+    await boot.flush();
+    return { exitCode, ...drain() };
+  } catch (e) {
+    try { await boot.flush(); } catch (ignored) { /* the VM is already gone */ }
+    return { exitCode: 1, ...drain(), error: (e && e.message) || String(e) };
+  }
+};
+
+// ── REPL ───────────────────────────────────────────────────────────────────
+// One interpreter for the whole session, unlike __cpythonRun's fresh instance
+// per call: a REPL where the previous line's definitions are gone is not a
+// REPL. The facet pool that owns this runs at concurrency 1, so there is one
+// of these per session and no interleaving to guard against.
+globalThis.__cpythonReplBoot = globalThis.__cpythonReplBoot || null;
+globalThis.__cpythonReplRun = async function __cpythonReplRun(args) {
+  const stdoutStart = globalThis.__nimbusPyStdout.length;
+  const stderrStart = globalThis.__nimbusPyStderr.length;
+  const drain = () => ({
+    stdout: globalThis.__nimbusPyStdout.slice(stdoutStart).join(''),
+    stderr: globalThis.__nimbusPyStderr.slice(stderrStart).join(''),
+  });
+  try {
+    if (!globalThis.__cpythonReplBoot) {
+      globalThis.__cpythonReplBoot = await __nimbusPyBoot(args);
+    }
+  } catch (e) {
+    return { exitCode: 1, ...drain(), error: (e && e.message) || String(e) };
+  }
+  try {
+    const exitCode = await globalThis.__cpythonReplBoot.run(args.userCode || '');
+    await globalThis.__cpythonReplBoot.flush();
+    return { exitCode, ...drain() };
+  } catch (e) {
+    return { exitCode: 1, ...drain(), error: (e && e.message) || String(e) };
+  }
+};
+
+// ── Resident process ───────────────────────────────────────────────────────
+// The program is not suspended between requests — it has already finished.
+// python-server-adapter.ts makes serve_forever() register the server and
+// return, so the body runs to completion and the server object survives on the
+// Python heap. Each inbound request re-enters the interpreter and dispatches
+// one connection into it. Nothing is parked across a request boundary, which is
+// what makes this work at all: workerd cannot resume a wasm stack that a
+// different request suspended.
+globalThis.__cpythonProcess = globalThis.__cpythonProcess || null;
+
+globalThis.__cpythonStartProcess = async function __cpythonStartProcess(args) {
+  if (globalThis.__cpythonProcess) return globalThis.__cpythonProcess.result;
+  const stdoutStart = globalThis.__nimbusPyStdout.length;
+  const stderrStart = globalThis.__nimbusPyStderr.length;
+  const boot = await __nimbusPyBoot(args);
+  const exitCode = await boot.run(args.userCode || '');
+  await boot.flush();
+  const result = {
+    exitCode,
+    stdout: globalThis.__nimbusPyStdout.slice(stdoutStart).join(''),
+    stderr: globalThis.__nimbusPyStderr.slice(stderrStart).join(''),
+  };
+  globalThis.__cpythonProcess = { boot, result };
+  return result;
+};
+
+// Which ports the program left listening. Read back from Python rather than
+// tracked here, because the adapter's registry is the only thing that knows
+// whether serve_forever actually ran.
+globalThis.__cpythonListeningPorts = async function __cpythonListeningPorts() {
+  const proc = globalThis.__cpythonProcess;
+  if (!proc) return [];
+  const before = globalThis.__nimbusPyStdout.length;
+  await proc.boot.run('print("__NIMBUS_PORTS__" + repr(_nimbus_listening_ports()))');
+  const written = globalThis.__nimbusPyStdout.splice(before).join('');
+  const match = /__NIMBUS_PORTS__\[([^\]]*)\]/.exec(written);
+  // Anything the program itself printed in the same turn is kept.
+  const leftover = written.replace(/__NIMBUS_PORTS__\[[^\]]*\]\n?/, '');
+  if (leftover) globalThis.__nimbusPyStdout.push(leftover);
+  if (!match || !match[1].trim()) return [];
+  return match[1].split(',').map((n) => Number(n.trim())).filter((n) => n > 0);
+};
+
+// One dispatch at a time for the whole process: two entries into the same
+// interpreter would interleave inside a single-threaded VM. The queue lives on
+// globalThis because no request may own it — a request context is torn down
+// without warning when its response is sent.
+globalThis.__cpythonServeQueue = globalThis.__cpythonServeQueue || Promise.resolve();
+globalThis.__nimbusVirtualSocketRequestQueued = globalThis.__nimbusVirtualSocketRequestQueued
+  || function __nimbusVirtualSocketRequestQueued(port) {
+    const run = async () => {
+      const proc = globalThis.__cpythonProcess;
+      if (!proc) return false;
+      const rc = await proc.boot.run(
+        'import sys\n'
+        + '_nimbus_ok = _nimbus_serve_one(' + Number(port) + ')\n'
+        + 'if not _nimbus_ok: sys.stderr.write("nimbus: no server registered on port ' + Number(port) + '\\n")');
+      await proc.boot.flush();
+      return rc === 0;
+    };
+    const task = globalThis.__cpythonServeQueue.then(run, run);
+    globalThis.__cpythonServeQueue = task.then(() => {}, () => {});
+    return task;
+  };
+`;

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

@@ -0,0 +1,242 @@
+/**
+ * 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.
+ *   v7 — barrel-package bundles include a named-import signature in
+ *        pkg_esm_bundles.input_hash. Prevents reusing a lucide-react
+ *        bundle synthesized for one icon set after user source imports
+ *        additional icons.
+ *   v8 — pkg_esm_bundles now stores RAW esbuild output (base-independent);
+ *        the module-URL rewrite that used to be baked in is applied per
+ *        request at serve time so one bundle serves every mount base. v7
+ *        rows hold post-rewrite text and must be re-bundled. user_module_
+ *        transforms is likewise re-keyed by mount base.
+ */
+export declare const BUNDLER_VERSION = "v8";
+/**
+ * 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[];
+/**
+ * Detect top-level await in source. Used by `EsbuildService.transform`
+ * to decide whether to async-IIFE-wrap CJS-target sources (see
+ * transform()'s header comment).
+ *
+ * Token scan over a comment-and-string-stripped source. Tracks paren
+ * depth AND function-body depth so a `{` inside a parameter list (a
+ * default-value object literal — `async function f(opts = {})`) is NOT
+ * mistaken for the function body. The earlier heuristic lacked the paren
+ * guard: the `= {}` braces consumed the body-tracking slot, leaving the
+ * real body untracked so an internal `await` read as top-level. That
+ * wrongly routed such files (e.g. @bluwy/giget-core's
+ * download-template.js, reached by create-astro) into the two-pass
+ * ESM→require rewrite, whose assembled output still carried export/import
+ * statements → "Cannot use import statement outside a module" at startup.
+ *
+ * Arrow bodies are distinguished from arrow expression bodies (the
+ * `arrowPending` flag): only a `{` immediately following `=>` opens a
+ * function scope. The idiomatic object-returning arrow `x => ({ ... })`
+ * has its `{` at parenDepth 1, so it opens no body slot — otherwise the
+ * leaked slot would be consumed by a later top-level `{ ... }` block,
+ * making a real top-level `await` inside it read as non-TLA (false
+ * negative) and routing genuine ESM-with-TLA into the wrong transform.
+ *
+ * A regex/token scan (not acorn) is kept here deliberately: pulling
+ * acorn into the esbuild-service bundle chunk duplicates its ~15 KiB
+ * Unicode identifier tables.
+ */
+export declare function hasTopLevelAwait(src: string): boolean;
+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 and return its
+     * Promise to the facet runner:
+     *
+     *     return (async () => {
+     *       <original-source>
+     *     })();
+     *
+     * Inside the IIFE, await is legal. Returning the Promise is required:
+     * the facet runner awaits promise-returning entry functions so
+     * sequential TLA execution cannot race process teardown or VFS flushes.
+     *
+     * 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 a returned 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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"}