@nimbus-sh/core 0.1.0

package/src/_shared/exports-resolver.ts

@@ -0,0 +1,308 @@
+/**
+ * exports-resolver.ts — Single source of truth for `package.json#exports` /
+ * `package.json#imports` resolution per the Node.js spec.
+ *
+ * Used in three contexts:
+ *
+ *   1. Install-time supervisor (TS) — `src/npm-resolver.ts` re-exports the
+ *      typed functions for tree resolution.
+ *
+ *   2. NimbusLoaderPool isolates (JS string) — `src/loaders/pre-bundle-preamble.ts`
+ *      embeds `getExportsResolverJS()` as part of the pool preamble so the
+ *      pre-bundle facet uses identical resolution semantics to the supervisor.
+ *
+ *   3. User-shell `node` runtime (JS string) — `src/node-shims.ts` embeds
+ *      the same JS source so `require()` from inside a user's `node` script
+ *      sees the same exports map as the install pipeline.
+ *
+ *
+ * Spec features supported:
+ *   - String shorthand:                "exports": "./dist/index.mjs"
+ *   - Subpath maps:                    { ".": "...", "./client": "..." }
+ *   - Conditional maps (top-level):    { "import": "...", "require": "..." }
+ *   - Nested conditions:               { ".": { "node": { "default": "..." } } }
+ *   - Subpath wildcards:               { "./*": "./dist/*.js" }
+ *   - Array fallbacks:                 [ "./esm.js", "./cjs.js" ]
+ *   - `imports` field (`#name`):       same shape, same impl (re-uses resolveExports)
+ *   - Null-target enforcement:         { "./private/*": null } — returns null, blocks fallback
+ *
+ * Caller-controlled `conditions` lets the same impl serve:
+ *   - install/ESM/browser  →  ['import', 'module', 'browser', 'default']
+ *   - runtime CJS          →  ['require', 'node', 'default']
+ */
+
+/** Default conditions for ESM/install/browser resolution. */
+export const DEFAULT_ESM_CONDITIONS = ['import', 'module', 'browser', 'default'];
+
+/** Default conditions for CJS runtime resolution (user-shell node). */
+export const DEFAULT_CJS_CONDITIONS = ['require', 'node', 'default'];
+
+/**
+ * Resolve `package.json#exports` (or `#imports`) per Node spec.
+ *
+ * @param exportsField  Raw value from package.json#exports or #imports
+ * @param subpath       '.' for root, './foo' for subpath, '#name' for imports
+ * @param conditions    Active conditions, in priority order
+ * @returns             Relative path target string, or null if not found / forbidden
+ */
+export function resolveExports(
+  exportsField: any,
+  subpath: string = '.',
+  conditions: string[] = DEFAULT_ESM_CONDITIONS,
+): string | null {
+  if (exportsField === undefined || exportsField === null) return null;
+
+  // String shorthand — only valid for root entry
+  if (typeof exportsField === 'string') {
+    return subpath === '.' ? exportsField : null;
+  }
+
+  // Array fallback — try each in order
+  if (Array.isArray(exportsField)) {
+    for (const item of exportsField) {
+      const r = resolveExports(item, subpath, conditions);
+      if (r) return r;
+    }
+    return null;
+  }
+
+  if (typeof exportsField !== 'object') return null;
+
+  const keys = Object.keys(exportsField);
+  if (keys.length === 0) return null;
+
+  // Subpath-map detection: keys begin with "." (exports) or "#" (imports)
+  const isSubpathMap = keys[0].startsWith('.') || keys[0].startsWith('#');
+
+  if (isSubpathMap) {
+    // Exact match first
+    if (subpath in exportsField) {
+      const target = exportsField[subpath];
+      // Null target — forbidden subpath, returns null and BLOCKS fallback
+      if (target === null) return null;
+      return resolveConditionValue(target, conditions);
+    }
+
+    // Wildcard pattern match — try most-specific (longest prefix) first
+    const wildcardKeys = keys
+      .filter(k => k.includes('*'))
+      .sort((a, b) => b.length - a.length); // longest pattern wins
+
+    for (const pattern of wildcardKeys) {
+      const target = exportsField[pattern];
+      const starIdx = pattern.indexOf('*');
+      const prefix = pattern.slice(0, starIdx);
+      const suffix = pattern.slice(starIdx + 1);
+      if (
+        subpath.startsWith(prefix) &&
+        (suffix ? subpath.endsWith(suffix) : true) &&
+        subpath.length >= prefix.length + suffix.length
+      ) {
+        // Null target on wildcard — forbidden, BLOCK fallback
+        if (target === null) return null;
+        const matched = subpath.slice(
+          prefix.length,
+          suffix ? subpath.length - suffix.length : undefined,
+        );
+        const resolved = resolveConditionValue(target, conditions);
+        if (resolved) return resolved.split('*').join(matched);
+      }
+    }
+
+    return null;
+  }
+
+  // Condition map (no subpath map keys) — only valid for root entry
+  if (subpath !== '.') return null;
+  return resolveConditionValue(exportsField, conditions);
+}
+
+/**
+ * Resolve a condition target. Recurses through nested condition objects
+ * and array fallbacks. Honours `default` even if not in the conditions
+ * array (Node spec).
+ */
+function resolveConditionValue(
+  target: any,
+  conditions: string[],
+): string | null {
+  if (target === null || target === undefined) return null;
+  if (typeof target === 'string') return target;
+
+  if (Array.isArray(target)) {
+    for (const item of target) {
+      const r = resolveConditionValue(item, conditions);
+      if (r) return r;
+    }
+    return null;
+  }
+
+  if (typeof target !== 'object') return null;
+
+  // Try each requested condition in priority order
+  for (const cond of conditions) {
+    if (cond in target) {
+      const r = resolveConditionValue(target[cond], conditions);
+      if (r) return r;
+    }
+  }
+
+  // Spec: `default` is always a valid fallback
+  if (!conditions.includes('default') && 'default' in target) {
+    return resolveConditionValue(target.default, conditions);
+  }
+
+  return null;
+}
+
+/**
+ * Resolve a package's entry-point file relative to its directory.
+ * Priority: exports → module → main → null.
+ * For non-root subpaths without an `exports` field, returns the subpath
+ * itself (caller probes filesystem with extension-list).
+ */
+export function resolvePackageEntry(
+  pkg: { exports?: any; module?: string; main?: string },
+  subpath: string = '.',
+  conditions: string[] = DEFAULT_ESM_CONDITIONS,
+): string | null {
+  // 1. exports field
+  if (pkg.exports !== undefined && pkg.exports !== null) {
+    const entry = resolveExports(pkg.exports, subpath, conditions);
+    if (entry) return entry;
+    // If exports is defined but yields nothing for this subpath,
+    // Node spec is: this is an error (subpath isn't exposed).
+    // We return null to let caller decide (some callers fall back to
+    // direct filesystem probing for compatibility with packages that
+    // mis-declare exports).
+    return null;
+  }
+
+  // 2. Root entry: module → main
+  if (subpath === '.') {
+    if (pkg.module) return pkg.module;
+    if (pkg.main) return pkg.main;
+    return null;
+  }
+
+  // 3. Non-root subpath without exports — caller probes raw subpath
+  return subpath;
+}
+
+// ─── JS-source emission for embedding into facet preambles ───────────────
+
+/**
+ * Returns the resolver source as plain JavaScript (no TypeScript syntax),
+ * suitable for embedding into a generated worker preamble or shim string.
+ *
+ * The emitted source declares three top-level functions in scope:
+ *   - resolveExports(exports, subpath, conditions)
+ *   - resolveConditionValue(target, conditions)        (helper)
+ *   - resolvePackageEntry(pkg, subpath, conditions)
+ *
+ * It also declares two arrays:
+ *   - DEFAULT_ESM_CONDITIONS
+ *   - DEFAULT_CJS_CONDITIONS
+ *
+ * This source must be byte-equivalent to the TS impl above (modulo type
+ * annotations and `export` keywords). Keep them in sync — there is one
+ */
+export function getExportsResolverJS(): string {
+  return `
+// ── exports-resolver.js (auto-generated; keep in sync with src/_shared/exports-resolver.ts) ──
+const DEFAULT_ESM_CONDITIONS = ['import', 'module', 'browser', 'default'];
+const DEFAULT_CJS_CONDITIONS = ['require', 'node', 'default'];
+
+function resolveExports(exportsField, subpath, conditions) {
+  if (subpath === undefined) subpath = '.';
+  if (!conditions) conditions = DEFAULT_ESM_CONDITIONS;
+  if (exportsField === undefined || exportsField === null) return null;
+  if (typeof exportsField === 'string') {
+    return subpath === '.' ? exportsField : null;
+  }
+  if (Array.isArray(exportsField)) {
+    for (const item of exportsField) {
+      const r = resolveExports(item, subpath, conditions);
+      if (r) return r;
+    }
+    return null;
+  }
+  if (typeof exportsField !== 'object') return null;
+  const keys = Object.keys(exportsField);
+  if (keys.length === 0) return null;
+  const isSubpathMap = keys[0].startsWith('.') || keys[0].startsWith('#');
+  if (isSubpathMap) {
+    if (subpath in exportsField) {
+      const target = exportsField[subpath];
+      if (target === null) return null;
+      return resolveConditionValue(target, conditions);
+    }
+    const wildcardKeys = keys
+      .filter(k => k.includes('*'))
+      .sort((a, b) => b.length - a.length);
+    for (const pattern of wildcardKeys) {
+      const target = exportsField[pattern];
+      const starIdx = pattern.indexOf('*');
+      const prefix = pattern.slice(0, starIdx);
+      const suffix = pattern.slice(starIdx + 1);
+      if (
+        subpath.startsWith(prefix) &&
+        (suffix ? subpath.endsWith(suffix) : true) &&
+        subpath.length >= prefix.length + suffix.length
+      ) {
+        if (target === null) return null;
+        const matched = subpath.slice(
+          prefix.length,
+          suffix ? subpath.length - suffix.length : undefined,
+        );
+        const resolved = resolveConditionValue(target, conditions);
+        if (resolved) return resolved.split('*').join(matched);
+      }
+    }
+    return null;
+  }
+  if (subpath !== '.') return null;
+  return resolveConditionValue(exportsField, conditions);
+}
+
+function resolveConditionValue(target, conditions) {
+  if (target === null || target === undefined) return null;
+  if (typeof target === 'string') return target;
+  if (Array.isArray(target)) {
+    for (const item of target) {
+      const r = resolveConditionValue(item, conditions);
+      if (r) return r;
+    }
+    return null;
+  }
+  if (typeof target !== 'object') return null;
+  for (const cond of conditions) {
+    if (cond in target) {
+      const r = resolveConditionValue(target[cond], conditions);
+      if (r) return r;
+    }
+  }
+  if (!conditions.includes('default') && 'default' in target) {
+    return resolveConditionValue(target.default, conditions);
+  }
+  return null;
+}
+
+function resolvePackageEntry(pkg, subpath, conditions) {
+  if (subpath === undefined) subpath = '.';
+  if (!conditions) conditions = DEFAULT_ESM_CONDITIONS;
+  if (pkg.exports !== undefined && pkg.exports !== null) {
+    const entry = resolveExports(pkg.exports, subpath, conditions);
+    if (entry) return entry;
+    return null;
+  }
+  if (subpath === '.') {
+    if (pkg.module) return pkg.module;
+    if (pkg.main) return pkg.main;
+    return null;
+  }
+  return subpath;
+}
+// ── end exports-resolver.js ────────────────────────────────────────────
+`;
+}

package/src/_shared/facet-vfs-cursor.ts

@@ -0,0 +1,58 @@
+/**
+ * Seed the coherence cursor the facet's staged VFS snapshot was read at.
+ *
+ * A facet's resident set is a cache of the supervisor's VFS, and the cursor is
+ * the only thing that says WHICH state it caches. Without one the first ACQUIRE
+ * carries a null epoch, and a null epoch is not a stale cursor the authority can
+ * compute a delta from — it can only answer poison, "drop everything". So the
+ * first async fs call in the process throws away every staged cell, and the next
+ * synchronous read of any of them raises EAGAIN for content that was staged
+ * correctly and never changed. Measured: pi, launched as a bin, lost all 3210
+ * cells of its bundle to one `fs.promises` call and then failed reading its own
+ * `dist/modes/interactive/theme/dark.json`.
+ *
+ * Shared source rather than a line per body: the long-running node body and the
+ * staged-artifact body each hold a hand-written copy of the snapshot preamble,
+ * and neither gained this seed when the one-shot body did. That drift is the
+ * defect, and one definition every generator splices is what makes it
+ * unrepeatable.
+ *
+ * Splice it AFTER `__MODULE_VFS_CURSOR` is defined and BEFORE the shims: the
+ * shims read the cursor into a closure const as they evaluate, so an assignment
+ * that lands later replaces an object nothing still points at.
+ *
+ * Where `__MODULE_VFS_CURSOR` comes from is the generator's business, and for
+ * the two node bodies there is only one right answer: the invocation. Their
+ * generated text is content-addressed — the one-shot body is cached on
+ * hash(code + bundle + manifest), the resident body is stored as a facet image
+ * named by its own digest — and a cursor carries a revision that advances on
+ * every spawn and an epoch that belongs to one supervisor incarnation. Baked
+ * in, it gives the same program a new image each time and hands a shared body
+ * another session's epoch. So it rides the request body and the start payload
+ * respectively, the same channel argv and env want. The staged-artifact body
+ * is generated from a per-invocation spec that is not addressed by its bytes,
+ * so there it is simply one more field of that spec.
+ */
+export const VFS_CURSOR_SEED_SOURCE = `
+if (__MODULE_VFS_CURSOR) {
+  globalThis.__nimbusVfsCursor = {
+    epoch: __MODULE_VFS_CURSOR.epoch,
+    rev: __MODULE_VFS_CURSOR.rev,
+  };
+}
+`;
+
+/** The cursor a facet snapshot travels with, or `null` when it has none. */
+export interface FacetVfsCursor {
+  epoch: string;
+  rev: number;
+}
+
+/**
+ * The `__MODULE_VFS_CURSOR` literal for a generated facet body. `null` is a
+ * real answer — a facet built without a VFS has no state to be coherent with —
+ * and the seed above is a no-op for it.
+ */
+export function serializeFacetVfsCursor(cursor: FacetVfsCursor | undefined): string {
+  return JSON.stringify(cursor ?? null);
+}

package/src/_shared/install-phase.ts

@@ -0,0 +1,56 @@
+/**
+ * _shared/install-phase.ts — single source of truth for the npm-install
+ * state-machine phase enum.
+ *
+ * History: CLN-1 (2026-05-11) — consolidated from two diverged copies.
+ *   - `npm/installer.ts:93-95` was the progress-event variant. Included
+ *     'lock-check' (a real progress event emitted while parsing
+ *     package-lock.json) but lacked 'idle'.
+ *   - `observability/diag-counters.ts:33-35` was the counter-state variant.
+ *     Included 'idle' (the resting state when no install is in flight)
+ *     but lacked 'lock-check'. The diag-counter's `setInstallPhase()`
+ *     was actually called with 'idle' (installer.ts:184,201) — passing
+ *     a value not declared in installer.ts's local type. The type check
+ *     fell through to diag-counters' type because installer.ts imports
+ *     setInstallPhase from there; the local `InstallPhase` definition
+ *     in installer.ts was only used by `InstallProgress.phase`.
+ *
+ * Going forward both consumers import from this module; any new phase
+ * value added here is automatically available everywhere.
+ *
+ * Phase semantics (chronological order for a single install run):
+ *
+ *   idle         resting state, no install in flight
+ *     ↓
+ *   lock-check   parsing existing package-lock.json (if present)
+ *     ↓
+ *   resolve      walking the dep tree, fetching packuments
+ *     ↓
+ *   hoist        hoisting peer-deps + flattening node_modules
+ *     ↓
+ *   diff         comparing target tree against current install state
+ *     ↓
+ *   fetch        downloading missing tarballs
+ *     ↓
+ *   write        extracting tarballs into the VFS
+ *     ↓
+ *   link-bins    creating bin/ symlinks
+ *     ↓
+ *   bundle       (post-install) pre-bundling for esbuild fast path
+ *     ↓
+ *   done         install complete; about to return to 'idle'
+ *
+ * The phase strings are surfaced via /api/_diag/install-pipeline and
+ * displayed in the install-progress UI; treat them as a public API.
+ */
+export type InstallPhase =
+  | 'idle'
+  | 'lock-check'
+  | 'resolve'
+  | 'hoist'
+  | 'diff'
+  | 'fetch'
+  | 'write'
+  | 'link-bins'
+  | 'bundle'
+  | 'done';

package/src/_shared/lru-map.ts

@@ -0,0 +1,59 @@
+/**
+ * LruMap — a bounded, insertion-order LRU keyed map.
+ *
+ * Uses the standard JS `Map` insertion-order idiom the VFS content cache
+ * relies on (sqlite-vfs.ts): a read or write moves the key to the most-
+ * recently-used position (delete + re-set), and inserting past capacity
+ * evicts the least-recently-used key (`keys().next().value`).
+ *
+ * Exposes only the `Map` surface its callers use so it can drop in for a
+ * raw `Map` without churn: `get`, `set`, `delete`, `has`, `keys`,
+ * `clear`, and `size`.
+ */
+export class LruMap<K, V> {
+  private readonly map = new Map<K, V>();
+
+  constructor(private readonly maxEntries: number) {
+    if (maxEntries <= 0) throw new Error('LruMap maxEntries must be > 0');
+  }
+
+  get size(): number {
+    return this.map.size;
+  }
+
+  get(key: K): V | undefined {
+    const value = this.map.get(key);
+    if (value === undefined) return undefined;
+    // Move to MRU position.
+    this.map.delete(key);
+    this.map.set(key, value);
+    return value;
+  }
+
+  has(key: K): boolean {
+    return this.map.has(key);
+  }
+
+  set(key: K, value: V): this {
+    if (this.map.has(key)) {
+      this.map.delete(key);
+    } else if (this.map.size >= this.maxEntries) {
+      const lru = this.map.keys().next().value;
+      if (lru !== undefined) this.map.delete(lru);
+    }
+    this.map.set(key, value);
+    return this;
+  }
+
+  delete(key: K): boolean {
+    return this.map.delete(key);
+  }
+
+  clear(): void {
+    this.map.clear();
+  }
+
+  keys(): IterableIterator<K> {
+    return this.map.keys();
+  }
+}

package/src/_shared/real-node-imports.ts

@@ -0,0 +1,53 @@
+/**
+ * real-node-imports.ts — single source of truth for the static
+ * `import * as __real_X from 'node:X'` block that generated runtime
+ * workers prepend so the SHIMS string can forward to workerd's real
+ * `node:*` builtins.
+ *
+ * Used by:
+ *   - src/facet-manager.ts one-shot runtime worker template
+ *   - src/facet-manager.ts long-running process worker template
+ *
+ * Symmetry constraint (W3 plan §3): both templates MUST consume this
+ * helper to prevent drift. If you add a new `import * as __real_X`,
+ * also wire it into the matching shim block in node-shims.ts.
+ *
+ * Why this lives in _shared/ alongside exports-resolver.ts: same
+ * pattern — JS-string emitter consumed by the facet-code generators
+ * that can't `import` at runtime because the surrounding code is a
+ * raw string template.
+ *
+ * Workerd availability matrix (probe-verified 2026-05-04 at compat
+ * date 2026-04-01, flag `nodejs_compat`):
+ *   - node:crypto       — full Node 20 surface
+ *   - node:tls          — connect/TLSSocket/createSecureContext/...
+ *   - node:async_hooks  — AsyncLocalStorage + AsyncResource + createHook
+ *   - node:fs/promises  — full surface (BUT operates on real-host FS,
+ *                         not our VFS, so we shim VFS-backed instead
+ *                         of forwarding fs/promises)
+ *   - node:diagnostics_channel — full surface incl. tracingChannel +
+ *                                Channel.runStores (fastify-critical)
+ *   - node:repl         — surface stub (start/REPLServer)
+ *   - node:vm           — surface stub: classes/constants present BUT
+ *                         every code-running method throws
+ *                         ERR_METHOD_NOT_IMPLEMENTED. Hybrid shim:
+ *                         forward surface, wrap eval methods with
+ *                         honest error.
+ *   - node:inspector    — Session/console/url surface present; the V8
+ *                         debugger isn't attachable in workerd, so a
+ *                         constructed Session's connect/post are inert.
+ *                         Tools (e.g. nuxi) that open a Session purely
+ *                         for optional profiling degrade cleanly.
+ */
+
+export function getRealNodeImportsCode(): string {
+  return `
+import * as __real_crypto from 'node:crypto';
+import * as __real_tls from 'node:tls';
+import * as __real_async_hooks from 'node:async_hooks';
+import * as __real_diagnostics_channel from 'node:diagnostics_channel';
+import * as __real_repl from 'node:repl';
+import * as __real_vm from 'node:vm';
+import * as __real_inspector from 'node:inspector';
+`.trim();
+}