@nimbus-sh/worker 0.1.0

package/dist/npm/npx-install.d.ts

@@ -0,0 +1,74 @@
+/**
+ * npx-install.ts — Nimbus-native npx implementation.
+ *
+ * Replaces @lifo-sh/core's createNpxCommand (which uses a too-narrow
+ * semver-range detector that misses major-only ranges like `'1'`, `'2'`,
+ * `'1.0'`). The core's `ic()` regex `/[\^~>=<|*x]/.test(r)` flagged
+ * caret/tilde/comparator/x ranges correctly but treated `'1'` as a
+ * literal version → fetched `/wrappy/1` → 404 → silently skipped.
+ *
+ * Symptom captured by tests/behavioral/install/transitive-dep-resolution.mjs:
+ *   `npx --yes rimraf@3.0.2 --help` →
+ *     warn: could not install wrappy: Package 'wrappy@1' not found in registry
+ *     warn: could not install inherits: Package 'inherits@2' not found in registry
+ *     Cannot find module './' (from /tmp/.npx-cache/node_modules/rimraf)
+ *
+ * Fix: route the npx install step through Nimbus's NpmInstaller, which
+ * uses always-fetch-packument + RESOLVE_VERSION-style version-pick path
+ * (resolve-one-facet.ts:264 + RESOLVE_VERSION). Handles all semver-range
+ * syntax including major-only and major.minor.
+ *
+ * Binary-lookup and execution stay closer to the @lifo-sh/core flow:
+ *   1. Check cwd/node_modules/.bin/<cmd>
+ *   2. Check /tmp/.npx-cache/node_modules/.bin/<cmd>
+ *   3. Check global registry (built-ins like vite, esbuild — handled by
+ *      caller; this module is only invoked when registry resolution failed)
+ *   4. Install package via NpmInstaller into /tmp/.npx-cache
+ *   5. Locate <pkg>/package.json#bin → resolve absolute path
+ *   6. Invoke via Nimbus's `node` registry command (preserves PID
+ *      tracking, log buffer, process table membership)
+ */
+import type { NpmInstaller } from './installer.js';
+import type { SqliteVFS } from '../vfs/sqlite-vfs.js';
+/** Path where npx caches packages it installs. Matches the constant
+ *  in @lifo-sh/core (Vs in dist/index-Djm2onjx.js) so any other code
+ *  reading this dir (e.g. tooling that introspects npx state) sees the
+ *  same layout. */
+export declare const NPX_CACHE_DIR = "/tmp/.npx-cache";
+/**
+ * Result of a Nimbus-native npx invocation.
+ *
+ *   ok=true:  the binary was located AND about to be invoked. The
+ *             caller dispatches via the `node` registry handler with
+ *             { args: [binPath, ...binArgs] }.
+ *   ok=false: bin not found OR install failed OR arg parse error.
+ *             `error` is a human-readable message; caller prints to
+ *             stderr and returns exit code.
+ */
+export interface NpxResolveResult {
+    ok: boolean;
+    binPath?: string;
+    binArgs?: string[];
+    error?: string;
+    /** Diagnostic: which path located the bin (project-nm / npx-cache /
+     *  fresh-install). Useful in logs. */
+    source?: 'project-nm' | 'npx-cache' | 'fresh-install';
+}
+/**
+ * Resolve a binary for `npx <args>` by:
+ *   1. Parsing args.
+ *   2. Checking node_modules/.bin/<binName> in cwd, then NPX cache.
+ *   3. If absent, installing the package via NpmInstaller into
+ *      /tmp/.npx-cache, then re-checking.
+ *
+ * The caller is responsible for actually invoking the resulting binPath
+ * via Nimbus's `node` command — keeping this module pure (no process
+ * spawning) makes it testable.
+ *
+ * Note: deliberately does NOT honor `--version`/`--help` for npx
+ * itself (those are caller's job); they bubble up as `error` markers
+ * so the caller can format the usage banner consistently with the
+ * rest of the shell.
+ */
+export declare function resolveNpxBinary(installer: NpmInstaller, vfs: SqliteVFS, cwd: string, rawArgs: string[], log: (msg: string) => void): Promise<NpxResolveResult>;
+//# sourceMappingURL=npx-install.d.ts.map

package/dist/npm/npx-install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"npx-install.d.ts","sourceRoot":"","sources":["../../src/npm/npx-install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD;;;mBAGmB;AACnB,eAAO,MAAM,aAAa,oBAAoB,CAAC;AAiN/C;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;0CACsC;IACtC,MAAM,CAAC,EAAE,YAAY,GAAG,WAAW,GAAG,eAAe,CAAC;CACvD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,YAAY,EACvB,GAAG,EAAE,SAAS,EACd,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EAAE,EACjB,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GACzB,OAAO,CAAC,gBAAgB,CAAC,CAgE3B"}

package/dist/npm/npx-install.js

@@ -0,0 +1,302 @@
+/**
+ * npx-install.ts — Nimbus-native npx implementation.
+ *
+ * Replaces @lifo-sh/core's createNpxCommand (which uses a too-narrow
+ * semver-range detector that misses major-only ranges like `'1'`, `'2'`,
+ * `'1.0'`). The core's `ic()` regex `/[\^~>=<|*x]/.test(r)` flagged
+ * caret/tilde/comparator/x ranges correctly but treated `'1'` as a
+ * literal version → fetched `/wrappy/1` → 404 → silently skipped.
+ *
+ * Symptom captured by tests/behavioral/install/transitive-dep-resolution.mjs:
+ *   `npx --yes rimraf@3.0.2 --help` →
+ *     warn: could not install wrappy: Package 'wrappy@1' not found in registry
+ *     warn: could not install inherits: Package 'inherits@2' not found in registry
+ *     Cannot find module './' (from /tmp/.npx-cache/node_modules/rimraf)
+ *
+ * Fix: route the npx install step through Nimbus's NpmInstaller, which
+ * uses always-fetch-packument + RESOLVE_VERSION-style version-pick path
+ * (resolve-one-facet.ts:264 + RESOLVE_VERSION). Handles all semver-range
+ * syntax including major-only and major.minor.
+ *
+ * Binary-lookup and execution stay closer to the @lifo-sh/core flow:
+ *   1. Check cwd/node_modules/.bin/<cmd>
+ *   2. Check /tmp/.npx-cache/node_modules/.bin/<cmd>
+ *   3. Check global registry (built-ins like vite, esbuild — handled by
+ *      caller; this module is only invoked when registry resolution failed)
+ *   4. Install package via NpmInstaller into /tmp/.npx-cache
+ *   5. Locate <pkg>/package.json#bin → resolve absolute path
+ *   6. Invoke via Nimbus's `node` registry command (preserves PID
+ *      tracking, log buffer, process table membership)
+ */
+/** Path where npx caches packages it installs. Matches the constant
+ *  in @lifo-sh/core (Vs in dist/index-Djm2onjx.js) so any other code
+ *  reading this dir (e.g. tooling that introspects npx state) sees the
+ *  same layout. */
+export const NPX_CACHE_DIR = '/tmp/.npx-cache';
+const NPX_CACHE_NM = `${NPX_CACHE_DIR}/node_modules`;
+/**
+ * SqliteVFS uses absolute paths WITHOUT a leading slash (e.g. it stores
+ * `tmp/.npx-cache/node_modules/foo/package.json`, not `/tmp/...`). The
+ * NpmInstaller's `install()` entry strips the leading slash from its
+ * `projectDir` arg, then propagates the slashless form into all
+ * downstream pkgDirs and inode keys. To check existence post-install,
+ * we MUST strip the same way; `vfs.exists('/...')` always returns false.
+ *
+ * Mirror of `_strip` in src/runtime/node-shims.ts:204.
+ */
+function _vfsKey(p) {
+    return p.replace(/^\/+/, '');
+}
+function parseNpxArgs(rawArgs) {
+    let pkgOverride = null;
+    const consumed = [];
+    let yes = false;
+    let i = 0;
+    while (i < rawArgs.length) {
+        const a = rawArgs[i];
+        if (a === '-y' || a === '--yes') {
+            yes = true;
+            i++;
+            continue;
+        }
+        if (a === '--package' && i + 1 < rawArgs.length) {
+            pkgOverride = rawArgs[i + 1];
+            i += 2;
+            continue;
+        }
+        if (a.startsWith('--package=')) {
+            pkgOverride = a.slice('--package='.length);
+            i++;
+            continue;
+        }
+        if (a === '--version' || a === '-v' || a === '--help' || a === '-h') {
+            // Pass-through to surface npx's own version/help. Caller (init.ts
+            // npx handler) is the one that prints these; this module returns
+            // an error so the caller can branch.
+            return { error: a };
+        }
+        break;
+    }
+    const first = rawArgs[i];
+    if (!first)
+        return { error: 'missing-cmd' };
+    consumed.push(...rawArgs.slice(i + 1));
+    // If --package=<pkg>, the positional arg is the BIN name; the package
+    // installs `<pkg>` and we look for the binary `<first>`.
+    // Else, the positional arg is `<name>[@<version>]`; binary is the
+    // last path segment of `<name>`.
+    let pkgSpec;
+    let binName;
+    if (pkgOverride) {
+        pkgSpec = pkgOverride;
+        binName = first;
+    }
+    else {
+        pkgSpec = first;
+        const namePart = splitSpec(first).name;
+        binName = namePart.split('/').pop() || namePart;
+    }
+    const { name: pkgName } = splitSpec(pkgSpec);
+    return { pkgSpec, pkgName, binName, binArgs: consumed, yes };
+}
+/** Split `name@version` (or scoped `@scope/name@version`) into parts. */
+function splitSpec(spec) {
+    if (spec.startsWith('@')) {
+        const at = spec.indexOf('@', 1);
+        if (at === -1)
+            return { name: spec, version: null };
+        return { name: spec.slice(0, at), version: spec.slice(at + 1) };
+    }
+    const at = spec.indexOf('@');
+    if (at === -1)
+        return { name: spec, version: null };
+    return { name: spec.slice(0, at), version: spec.slice(at + 1) };
+}
+/**
+ * Find the absolute path of a binary inside a package's directory.
+ *
+ * package.json#bin can be:
+ *   - `string` → single bin named after the package itself
+ *   - `Record<string, string>` → multiple bins
+ *
+ * Returns the resolved absolute path (rooted at packageDir) if a
+ * matching bin name is found, else null. Matches @lifo-sh/core's
+ * `Ht()` helper at dist/index-Djm2onjx.js:11707.
+ */
+function findBinInPackage(vfs, packageDir, binName) {
+    const pkgJsonPath = `${packageDir}/package.json`;
+    // SqliteVFS stores keys without leading slash. Check via the stripped
+    // key form to match the installer's write convention.
+    if (!vfs.exists(_vfsKey(pkgJsonPath)))
+        return null;
+    let pkgJson;
+    try {
+        pkgJson = JSON.parse(vfs.readFileString(_vfsKey(pkgJsonPath)));
+    }
+    catch {
+        return null;
+    }
+    const binField = pkgJson.bin;
+    if (!binField)
+        return null;
+    let resolved = null;
+    if (typeof binField === 'string') {
+        // Single-bin shorthand: bin name is package name's last segment.
+        const expected = String(pkgJson.name || '').split('/').pop();
+        if (expected === binName)
+            resolved = binField;
+    }
+    else if (typeof binField === 'object') {
+        const candidate = binField[binName];
+        if (typeof candidate === 'string') {
+            resolved = candidate;
+        }
+        else {
+            // Fall back to the FIRST bin entry — matches @lifo-sh/core's
+            // `Object.values(i)[0]` behavior at dist/index-Djm2onjx.js:11710.
+            const first = Object.values(binField)[0];
+            if (typeof first === 'string')
+                resolved = first;
+        }
+    }
+    if (!resolved)
+        return null;
+    // Strip leading "./" if present and join with packageDir. Return
+    // the absolute path (with leading slash) — the `node` registry
+    // command expects an absolute filesystem path as the first arg.
+    // The vfs.exists checks against _vfsKey internally.
+    const rel = resolved.startsWith('./') ? resolved.slice(2) : resolved;
+    return `${packageDir}/${rel}`;
+}
+/**
+ * Locate a binary by name across the standard search paths npx uses:
+ *   1. cwd/node_modules/.bin/<binName>    (project-local install)
+ *   2. NPX_CACHE_NM/<pkgName>/...         (npx-cache install)
+ *
+ * Returns the absolute path on hit, null on miss.
+ */
+function locateBinary(vfs, cwd, pkgName, binName) {
+    // 1. Project-local node_modules. The packageDir is cwd/node_modules/<pkgName>.
+    const projPkgDir = `${cwd}/node_modules/${pkgName}`;
+    const projHit = findBinInPackage(vfs, projPkgDir, binName);
+    if (projHit && vfs.exists(_vfsKey(projHit)))
+        return projHit;
+    // 2. NPX cache.
+    const npxPkgDir = `${NPX_CACHE_NM}/${pkgName}`;
+    const npxHit = findBinInPackage(vfs, npxPkgDir, binName);
+    if (npxHit && vfs.exists(_vfsKey(npxHit)))
+        return npxHit;
+    return null;
+}
+/**
+ * Ensure /tmp/.npx-cache/package.json exists with the requested spec
+ * in its dependencies. NpmInstaller reads package.json from projectDir
+ * to determine what to install; we synthesize one for the npx cache.
+ *
+ * Idempotent: if the file already exists and has the spec in deps,
+ * leaves it alone. Returns the deps object after the write (useful
+ * for the caller's log line).
+ */
+function ensureNpxCachePackageJson(vfs, pkgName, pkgRange) {
+    const pkgJsonPath = `${NPX_CACHE_DIR}/package.json`;
+    const pkgJsonKey = _vfsKey(pkgJsonPath);
+    let existing = { name: 'npx-cache', version: '0.0.0', dependencies: {} };
+    if (vfs.exists(pkgJsonKey)) {
+        try {
+            existing = JSON.parse(vfs.readFileString(pkgJsonKey));
+            if (!existing.dependencies)
+                existing.dependencies = {};
+        }
+        catch {
+            // Corrupted — overwrite with fresh content below.
+            existing = { name: 'npx-cache', version: '0.0.0', dependencies: {} };
+        }
+    }
+    else {
+        // Ensure the parent dir exists. SqliteVFS auto-creates parent
+        // dirs in writeFile, but mkdir defensively for symmetry with
+        // @lifo-sh/core's flow.
+        try {
+            vfs.mkdir(_vfsKey(NPX_CACHE_DIR), { recursive: true });
+        }
+        catch { /* dir exists */ }
+    }
+    existing.dependencies[pkgName] = pkgRange;
+    vfs.writeFile(pkgJsonKey, JSON.stringify(existing, null, 2) + '\n');
+}
+/**
+ * Resolve a binary for `npx <args>` by:
+ *   1. Parsing args.
+ *   2. Checking node_modules/.bin/<binName> in cwd, then NPX cache.
+ *   3. If absent, installing the package via NpmInstaller into
+ *      /tmp/.npx-cache, then re-checking.
+ *
+ * The caller is responsible for actually invoking the resulting binPath
+ * via Nimbus's `node` command — keeping this module pure (no process
+ * spawning) makes it testable.
+ *
+ * Note: deliberately does NOT honor `--version`/`--help` for npx
+ * itself (those are caller's job); they bubble up as `error` markers
+ * so the caller can format the usage banner consistently with the
+ * rest of the shell.
+ */
+export async function resolveNpxBinary(installer, vfs, cwd, rawArgs, log) {
+    const parsed = parseNpxArgs(rawArgs);
+    if ('error' in parsed) {
+        return { ok: false, error: parsed.error };
+    }
+    // 1. Check project + NPX cache for pre-installed bin.
+    const existing = locateBinary(vfs, cwd, parsed.pkgName, parsed.binName);
+    if (existing) {
+        return {
+            ok: true,
+            binPath: existing,
+            binArgs: parsed.binArgs,
+            source: cwd && existing.startsWith(cwd) ? 'project-nm' : 'npx-cache',
+        };
+    }
+    // 2. Not found anywhere — install into NPX cache via NpmInstaller.
+    //    Use the package's `<pkgSpec>` directly; NpmInstaller parses the
+    //    `<name>@<version>` form same as `npm install <pkgSpec>`.
+    log(`  ${parsed.pkgSpec}...`);
+    const { name: instName, version: instVer } = splitSpec(parsed.pkgSpec);
+    const installSpec = instVer ? `${instName}@${instVer}` : instName;
+    // Synthesize npx-cache package.json so NpmInstaller has a project
+    // root. The deps map is the source of truth for the install set.
+    ensureNpxCachePackageJson(vfs, instName, instVer || 'latest');
+    try {
+        const result = await installer.install(NPX_CACHE_DIR, {
+            packages: [installSpec],
+        });
+        if ((result.failed?.length || 0) > 0) {
+            // Partial install — some package failed to resolve. The fix is
+            // designed to handle major-only ranges; a residual failure here
+            // means a genuinely missing package or an unrelated transitive
+            // gap. Surface it as the error.
+            return {
+                ok: false,
+                error: `npx: install partially failed: ${result.failed.join(', ')}`,
+            };
+        }
+    }
+    catch (e) {
+        return {
+            ok: false,
+            error: `npx: install failed: ${e?.message ?? String(e)}`,
+        };
+    }
+    // 3. Re-check NPX cache after install.
+    const installed = locateBinary(vfs, cwd, parsed.pkgName, parsed.binName);
+    if (installed) {
+        return {
+            ok: true,
+            binPath: installed,
+            binArgs: parsed.binArgs,
+            source: 'fresh-install',
+        };
+    }
+    return {
+        ok: false,
+        error: `npx: installed ${parsed.pkgSpec} but could not locate binary '${parsed.binName}' in ${NPX_CACHE_NM}/${parsed.pkgName}`,
+    };
+}

package/dist/npm/pre-bundle-facet.d.ts

@@ -0,0 +1,168 @@
+/**
+ * pre-bundle-facet.ts — NimbusLoaderPool entry for esbuild pre-bundling.
+ *
+ * Why this exists
+ * ───────────────
+ * Pre-bundling npm packages (the `Pre-bundling N modules…` step in
+ * src/npm-installer.ts:704) used to call `EsbuildService.build(...)`
+ * inside the supervisor DO isolate. Each `esbuild.build` allocates
+ * 30–80 MiB of WASM linear memory plus the input/output graph; against
+ * the 128 MB DO heap cap this OOM-killed the supervisor on installs
+ * touching large React libraries (motion, framer-motion, etc.). The
+ * symptom was a banner re-print after `npm install` succeeded —
+ * NimbusSession's constructor running again because workerd had killed
+ * the previous isolate.
+ *
+ * The fix is to dispatch each per-specifier `esbuild.build` to a
+ * NimbusLoaderPool isolate. Each facet has its own 128 MB budget and
+ * stable-slot reuse keeps the warm-up cost amortized across the 8
+ * concurrent specs of a typical install. Same pattern as
+ * src/npm-install-facet.ts (tarball extraction).
+ *
+ * File-slice strategy (zero per-read RPC)
+ * ──────────────────────────────────────
+ * esbuild's VFS plugin would naturally call back to the supervisor for
+ * every onLoad / onResolve hit. With workerd's ~5–20 ms RPC latency and
+ * 50–200 reads per bundle × 8 specs that's 4–32 seconds of pure RPC
+ * overhead per install — measurably worse than the current OOM-y path.
+ *
+ * Instead the supervisor walks the spec's transitive non-external
+ * dependency tree once (fast — direct VFS access) and ships the
+ * entire `{path → bytes}` slice as part of the spec. The facet's VFS
+ * plugin reads from this in-memory map. Zero RPC during bundling.
+ *
+ * Stability invariants
+ * ───────────────────
+ * cloudflare-parallel serializes the function via `fn.toString()`.
+ *   - No `this` references (arrow / anonymous async).
+ *   - No free variables other than preamble names + explicit args.
+ *   - Module-level constants the function references must come from
+ *     the preamble (src/parallel/pre-bundle-preamble.ts) — see
+ *     `ESBUILD_PRELOAD_PREAMBLE`.
+ *
+ * The supervisor RPC surface (env.SUPERVISOR) is available for emergency
+ * fallbacks but the bundle path MUST NOT use it — slice-up-front is the
+ * contract.
+ */
+import type { SqliteVFS } from '../vfs/sqlite-vfs.js';
+import type { ResolvedPackage } from './resolver.js';
+import { BUNDLER_VERSION } from '../runtime/esbuild-service.js';
+/**
+ * One file inside a facet spec's slice. `bytes` is a Uint8Array — esbuild's
+ * loader inferences (js/ts/css/binary) need raw bytes for binary entries
+ * and TextDecoder produces lossless text for source code.
+ *
+ * RPC serialisation: workerd transmits Uint8Array via structured-clone with
+ * zero-copy semantics across same-process isolates. Memory cost on the
+ * facet side equals the spec's slice size; cost on the supervisor side is
+ * the same (the slice was just built from VFS reads).
+ */
+export interface SlicedFile {
+    path: string;
+    bytes: Uint8Array;
+    isDir: false;
+}
+export interface SlicedDir {
+    path: string;
+    isDir: true;
+}
+export type SliceEntry = SlicedFile | SlicedDir;
+/** What the supervisor sends per pre-bundle dispatch. */
+export interface PrebundleSpec {
+    /** Bare specifier being bundled, e.g. "framer-motion" or "react/jsx-runtime". */
+    specifier: string;
+    /** VFS path of the entry point, e.g. "/home/user/app/node_modules/framer-motion/dist/es/index.mjs". */
+    entryPath: string;
+    /** External specifiers (from getSharedRuntimeExternals). */
+    externals: string[];
+    /**
+     * Slice: every file/dir the bundler may need for this spec. Computed
+     * supervisor-side via a transitive-dependency walk. Includes:
+     *   - Every file under node_modules/<spec-pkg>/
+     *   - Every file under node_modules/<dep>/ for each transitive dep
+     *     NOT marked external by `externals`.
+     */
+    slice: SliceEntry[];
+    /** Stamp written into pkg_esm_bundles.bundle_hash; matches BUNDLER_VERSION. */
+    bundlerVersion: string;
+    /** Optional esbuild `define` map. Used by the on-demand bundler path
+     *  (vite-dev-server) to inject process.env.NODE_ENV, import.meta.env.*,
+     *  global → globalThis, etc. The pre-bundle path leaves this undefined
+     *  (browser-target build needs no define replacement). */
+    define?: Record<string, string>;
+}
+/** What the facet returns. */
+export interface PrebundleResult {
+    specifier: string;
+    ok: boolean;
+    /** ESM bundle output as a UTF-8 string. Empty when ok=false. */
+    esmCode: string;
+    /** First esbuild error message; populated when ok=false. */
+    errorText?: string;
+    /** Wall-clock ms inside the facet (bundling only, excludes RPC roundtrip). */
+    elapsed: number;
+    /** Non-fatal warnings the supervisor should surface. */
+    warnings: string[];
+}
+/**
+ * Walk node_modules to collect every file the pre-bundle of `specifier`
+ * may read. Runs in the supervisor (cheap — direct VFS access).
+ *
+ * Algorithm:
+ *   1. Compute the externals via getSharedRuntimeExternals(specifier).
+ *      These are the bare specifiers esbuild will leave external; their
+ *      files do NOT need to be in the slice.
+ *   2. Resolve the spec's package directory and add every file beneath
+ *      it to the slice.
+ *   3. Read its package.json `dependencies` and recurse into each one
+ *      that is NOT in the externals set. Deps that walked up are
+ *      visited at most once (visited set).
+ *
+ * Lives here (alongside the facet function) so changes to the slice
+ * shape touch one file — the supervisor caller in npm-installer.ts is
+ * a thin orchestrator.
+ */
+export interface BuildSliceOptions {
+    /** Cap on total bytes shipped to the facet. 24 MiB leaves headroom under
+     *  the 32 MiB workerd RPC cap. Returns `null` if the cap is exceeded so
+     *  the caller can decide whether to bail or split (bf41d1c precedent).
+     */
+    maxBytes?: number;
+}
+export declare function buildSliceForSpecifier(vfs: SqliteVFS, specifier: string, nmDir: string): {
+    slice: SliceEntry[];
+    totalBytes: number;
+} | null;
+export declare function buildSliceForSpecifierWithCap(vfs: SqliteVFS, specifier: string, nmDir: string, capBytes: number): {
+    slice: SliceEntry[];
+    totalBytes: number;
+} | null;
+/**
+ * Choose the externals list for a specifier, exported so the supervisor
+ * can compute the same value when building the spec without re-pulling
+ * the helper from esbuild-service.ts on the call site.
+ */
+export declare function externalsForSpecifier(specifier: string): string[];
+/**
+ * Bundle one specifier in a facet isolate. Returns the ESM bundle output
+ * to the supervisor; bundle bytes flow through `pool.map`'s return value
+ * (no RPC writeBatch — pkg_esm_bundles is supervisor-side SQLite, not VFS).
+ *
+ * Memory plan (verified by /api/_diag/memory after the rollout):
+ *   - Slice retained in facet memory: ~3–10 MiB per typical React lib.
+ *   - esbuild WASM linear memory: ~30–80 MiB during build.
+ *   - Output bundle: usually <2 MiB.
+ *   - Peak in the facet: ~100 MiB worst case (well under 128 MB cap).
+ *
+ * The supervisor never holds more than the spec arg + result return at
+ * once, so its peak stays in the low tens of MiB during the entire
+ * pre-bundle phase.
+ */
+export declare const prebundleOne: (spec: PrebundleSpec, _env: {
+    SUPERVISOR: {
+        readFile(p: string): Promise<string | null>;
+    };
+}) => Promise<PrebundleResult>;
+export { BUNDLER_VERSION };
+export type _ResolvedPackage = ResolvedPackage;
+//# sourceMappingURL=pre-bundle-facet.d.ts.map

package/dist/npm/pre-bundle-facet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pre-bundle-facet.d.ts","sourceRoot":"","sources":["../../src/npm/pre-bundle-facet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAA6B,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAgB3F;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,UAAU,CAAC;IAClB,KAAK,EAAE,KAAK,CAAC;CACd;AACD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,IAAI,CAAC;CACb;AACD,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;AAEhD,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B,iFAAiF;IACjF,SAAS,EAAE,MAAM,CAAC;IAClB,uGAAuG;IACvG,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB;;;;;;OAMG;IACH,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,+EAA+E;IAC/E,cAAc,EAAE,MAAM,CAAC;IACvB;;;8DAG0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,8BAA8B;AAC9B,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,OAAO,CAAC;IACZ,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AACD,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,SAAS,EACd,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ;IAAE,KAAK,EAAE,UAAU,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAEpD;AAED,wBAAgB,6BAA6B,CAC3C,GAAG,EAAE,SAAS,EACd,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,GACf;IAAE,KAAK,EAAE,UAAU,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA4GpD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAEjE;AAmBD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,GACvB,MAAM,aAAa,EACnB,MAAM;IACJ,UAAU,EAAE;QAAE,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;KAAE,CAAC;CAC7D,KACA,OAAO,CAAC,eAAe,CAgazB,CAAC;AAGF,OAAO,EAAE,eAAe,EAAE,CAAC;AAE3B,MAAM,MAAM,gBAAgB,GAAG,eAAe,CAAC"}