@nimbus-sh/core 0.3.0 → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ashish Kumar Singh and Nimbus contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# @nimbus-sh/core
+
+> Part of [Nimbus](https://github.com/AshishKumar4/Nimbus), my hobby/research
+> cloud OS. This README is edited and maintained with Claude (AI) and
+> presented as-is.
+
+The backend-agnostic half of Nimbus: a durable POSIX-like filesystem, a shell
+with 60+ Unix commands, and the WASI runtime layer — with no Cloudflare
+dependency. You hand it a SQLite and get back `.fs` and `.exec`. On
+Cloudflare that SQLite is `ctx.storage.sql` inside your Durable Object; in bun
+or node it is `bun:sqlite` or `node:sqlite`.
+
+I extracted this package because I kept wanting Nimbus *inside* other
+projects — a Durable Object that already does something else but needs a real
+workspace, or a local script that needs the same filesystem semantics the
+hosted product has. The whole of it runs on two narrow ports (`SqlDatabase`
+and `SqlTransactions`), so the same code serves both hosts.
+
+## Quick start
+
+```ts
+import { Database } from 'bun:sqlite';
+import { NimbusWorkspace } from '@nimbus-sh/core/workspace';
+
+const db = new Database('workspace.sqlite');
+const sql = {
+  exec(q, ...p) {
+    const st = db.query(q);
+    if (st.columnNames.length === 0) { db.run(q, ...p); return []; }
+    return st.all(...p);
+  },
+};
+const transactions = { storage: { transactionSync: (cb) => db.transaction(cb)() } };
+
+const ws = await NimbusWorkspace.create({ sql, transactions, generation: 1 });
+
+await ws.fs.writeFile('/home/user/hello.txt', 'hi\n');
+const out = await ws.exec('cat /home/user/hello.txt | wc -c');   // { stdout: '3\n', exitCode: 0 }
+```
+
+Inside a Cloudflare Durable Object, complete:
+
+```ts
+import { DurableObject } from 'cloudflare:workers';
+import { NimbusWorkspace } from '@nimbus-sh/core/workspace';
+
+export class Workspace extends DurableObject {
+  private ws?: Promise<NimbusWorkspace>;
+
+  private workspace(): Promise<NimbusWorkspace> {
+    this.ws ??= (async () => {
+      // Bump a persisted counter once per instance. Never a constant and
+      // never Date.now(): pids derive from the generation, so a repeated
+      // one hands a dead process live write authority, and the platform
+      // re-instantiates this class far more often than it looks like it
+      // does (cold starts, hibernation wakes, resets). Use the bumped
+      // value only after the put resolves.
+      const generation = ((await this.ctx.storage.get<number>('generation')) ?? 0) + 1;
+      await this.ctx.storage.put('generation', generation);
+      return NimbusWorkspace.create({
+        sql: this.ctx.storage.sql,
+        transactions: this.ctx,
+        generation,
+      });
+    })();
+    return this.ws;
+  }
+
+  async exec(command: string) {
+    return (await this.workspace()).exec(command);
+  }
+}
+```
+
+Files written through `.fs` are owned by the session user (uid 1000), not
+root, and the shell enforces the same permission model either way: a
+root-owned `/etc/passwd` refuses a write from `.fs`, and `id` resolves names
+through it.
+
+## Real runtimes, off Cloudflare
+
+The wasm runtimes are separate npm packages so nobody downloads a Python
+interpreter to get a filesystem. Install the ones you want and pass them in:
+
+```bash
+npm install @nimbus-sh/runtime-bash @nimbus-sh/runtime-cpython
+```
+
+```ts
+import bash from '@nimbus-sh/runtime-bash';
+import cpython from '@nimbus-sh/runtime-cpython';
+import { localFacetHost } from '@nimbus-sh/core';
+
+const ws = await NimbusWorkspace.create({
+  sql, transactions, generation: 1,
+  facets: localFacetHost(),
+  runtimes: [bash, cpython],
+});
+
+await ws.exec('bash -c "echo $((6*7))"');       // 42 — GNU bash 5.2, real BusyBox children
+await ws.exec(`python -c "import sqlite3; print('live')"`);  // CPython 3.13, real stdlib
+```
+
+`@nimbus-sh/runtime-ruby` (Ruby 3.3) and `@nimbus-sh/runtime-clang` (clang →
+`wasm32-wasi`, compile and run C in the workspace) work the same way. Every
+package carries the same manifest and the same sha256-verified blobs the
+hosted product serves from R2 — one publisher, two transports.
+
+Without `facets` and `runtimes` you still get the full shell and coreutils;
+the wasm runtimes are a dependency you add, not a mode you enable. One caveat:
+`localFacetHost()` covers bun and node only — on workerd the CSP forbids
+request-time `WebAssembly.instantiate`, so wasm has to ride the Worker Loader
+module map, which is the machinery in `@nimbus-sh/worker` and
+`@nimbus-sh/fabric`; the shell, coreutils, and filesystem need none of it.
+
+## Sharing a database with your own app
+
+The workspace is designed to be a tenant in a database you own, not the owner
+of it:
+
+- It creates and touches only its own tables (`inodes`, `file_chunks`,
+  `content_lifecycle`, `vfs_*`).
+- `destroy()` drops exactly those tables. It never calls `deleteAll()`.
+- `transactionSync` must be a real transaction. An implementation that only
+  calls the callback turns every atomic write into a torn one.
+- `generation` must never repeat across restarts of your host — pids derive
+  from it, and a repeated generation would hand a dead process live write
+  authority.
+
+## What needs the Worker package instead
+
+Resident processes (long-running servers, attached TUIs), the session
+protocol, port routing to the public internet, and the hosted terminal all
+live in [`@nimbus-sh/worker`](https://www.npmjs.com/package/@nimbus-sh/worker),
+which composes on this package. If you want the full hosted product shape,
+start from `npx create-nimbus-app`.
+
+## License
+
+MIT.

package/dist/_shared/error-text.d.ts

@@ -0,0 +1,15 @@
+/**
+ * error-text.ts — the text a caught value carries.
+ *
+ * A `catch` binding is `unknown`: the throw site may have thrown an Error, a
+ * string, or a plain object with a `message`, and the shell and runtime paths
+ * report all three the same way. This is that report, in one place, so a
+ * command's diagnostics do not depend on which of those a facet threw.
+ */
+/**
+ * The message a thrown value names, or the value itself when it names none.
+ * Empty and other falsy messages fall through to the value, so an
+ * `new Error('')` still reports as `Error` rather than as nothing.
+ */
+export declare function errorText(error: unknown): string;
+//# sourceMappingURL=error-text.d.ts.map

package/dist/_shared/error-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-text.d.ts","sourceRoot":"","sources":["../../src/_shared/error-text.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAMhD"}

package/dist/_shared/error-text.js

@@ -0,0 +1,21 @@
+/**
+ * error-text.ts — the text a caught value carries.
+ *
+ * A `catch` binding is `unknown`: the throw site may have thrown an Error, a
+ * string, or a plain object with a `message`, and the shell and runtime paths
+ * report all three the same way. This is that report, in one place, so a
+ * command's diagnostics do not depend on which of those a facet threw.
+ */
+/**
+ * The message a thrown value names, or the value itself when it names none.
+ * Empty and other falsy messages fall through to the value, so an
+ * `new Error('')` still reports as `Error` rather than as nothing.
+ */
+export function errorText(error) {
+    if (typeof error === 'object' && error !== null && 'message' in error) {
+        const { message } = error;
+        if (message)
+            return String(message);
+    }
+    return String(error);
+}

package/dist/_shared/exports-resolver.d.ts

@@ -7,7 +7,7 @@
  *   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`
+ *   2. LoaderPool 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.
  *
@@ -34,6 +34,22 @@
 export declare const DEFAULT_ESM_CONDITIONS: string[];
 /** Default conditions for CJS runtime resolution (user-shell node). */
 export declare const DEFAULT_CJS_CONDITIONS: string[];
+/**
+ * A `package.json#exports` / `#imports` value: a target path, an ordered list
+ * of fallbacks to try in turn, or a map keyed by subpath (`"./client"`) or by
+ * condition (`"import"`) whose values are the same shape again. `null` is the
+ * spec's "this subpath is not exported" marker, and blocks fallback.
+ */
+export type ExportsField = string | null | ExportsField[] | {
+    [key: string]: ExportsField;
+};
+/** The package.json fields entry-point resolution reads. */
+export interface ResolvablePackageJson {
+    exports?: ExportsField;
+    imports?: ExportsField;
+    main?: string;
+    module?: string;
+}
 /**
  * Resolve `package.json#exports` (or `#imports`) per Node spec.
  *
@@ -42,18 +58,14 @@ export declare const DEFAULT_CJS_CONDITIONS: string[];
  * @param conditions    Active conditions, in priority order
  * @returns             Relative path target string, or null if not found / forbidden
  */
-export declare function resolveExports(exportsField: any, subpath?: string, conditions?: string[]): string | null;
+export declare function resolveExports(exportsField: ExportsField | undefined, subpath?: string, conditions?: string[]): string | 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 declare function resolvePackageEntry(pkg: {
-    exports?: any;
-    module?: string;
-    main?: string;
-}, subpath?: string, conditions?: string[]): string | null;
+export declare function resolvePackageEntry(pkg: ResolvablePackageJson, subpath?: string, conditions?: string[]): string | null;
 /**
  * Returns the resolver source as plain JavaScript (no TypeScript syntax),
  * suitable for embedding into a generated worker preamble or shim string.

package/dist/_shared/exports-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exports-resolver.d.ts","sourceRoot":"","sources":["../../src/_shared/exports-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,6DAA6D;AAC7D,eAAO,MAAM,sBAAsB,UAA6C,CAAC;AAEjF,uEAAuE;AACvE,eAAO,MAAM,sBAAsB,UAAiC,CAAC;AAErE;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,YAAY,EAAE,GAAG,EACjB,OAAO,GAAE,MAAY,EACrB,UAAU,GAAE,MAAM,EAA2B,GAC5C,MAAM,GAAG,IAAI,CAkEf;AAwCD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE;IAAE,OAAO,CAAC,EAAE,GAAG,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EACtD,OAAO,GAAE,MAAY,EACrB,UAAU,GAAE,MAAM,EAA2B,GAC5C,MAAM,GAAG,IAAI,CAsBf;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAkG7C"}
+{"version":3,"file":"exports-resolver.d.ts","sourceRoot":"","sources":["../../src/_shared/exports-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,6DAA6D;AAC7D,eAAO,MAAM,sBAAsB,UAA6C,CAAC;AAEjF,uEAAuE;AACvE,eAAO,MAAM,sBAAsB,UAAiC,CAAC;AAErE;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,IAAI,GACJ,YAAY,EAAE,GACd;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAAA;CAAE,CAAC;AAEpC,4DAA4D;AAC5D,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,YAAY,EAAE,YAAY,GAAG,SAAS,EACtC,OAAO,GAAE,MAAY,EACrB,UAAU,GAAE,MAAM,EAA2B,GAC5C,MAAM,GAAG,IAAI,CAkEf;AAwCD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,qBAAqB,EAC1B,OAAO,GAAE,MAAY,EACrB,UAAU,GAAE,MAAM,EAA2B,GAC5C,MAAM,GAAG,IAAI,CAsBf;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAkG7C"}

package/dist/_shared/exports-resolver.js

@@ -7,7 +7,7 @@
  *   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`
+ *   2. LoaderPool 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.
  *

package/dist/_shared/retry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/_shared/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,gFAAgF;AAChF,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC,oEAAoE;AACpE,eAAO,MAAM,UAAU,EAAE,SAAS,MAAM,EAAsB,CAAC;AAE/D,4DAA4D;AAC5D,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAM/C;AAED,qDAAqD;AACrD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAOzD;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEnF,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;;OAQG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,WAAW,EAClB,IAAI,CAAC,EAAE,qBAAqB,GAC3B,OAAO,CAAC,QAAQ,CAAC,CAqFnB"}
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/_shared/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,gFAAgF;AAChF,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC,oEAAoE;AACpE,eAAO,MAAM,UAAU,EAAE,SAAS,MAAM,EAAsB,CAAC;AAE/D,4DAA4D;AAC5D,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAM/C;AAED,qDAAqD;AACrD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAOzD;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEnF,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;;OAQG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,WAAW,EAClB,IAAI,CAAC,EAAE,qBAAqB,GAC3B,OAAO,CAAC,QAAQ,CAAC,CAsFnB"}

package/dist/_shared/retry.js

@@ -23,6 +23,7 @@
  * equivalent retry loops inside their isolated function bodies.
  */
 import { disposeRpcResource } from './rpc-dispose.js';
+import { errorText } from './error-text.js';
 /** Default retry count AFTER the first attempt (3 = up to 4 total attempts). */
 export const DEFAULT_RETRIES = 3;
 /** Base backoff delays in ms. Index = retry attempt (0-indexed). */
@@ -142,7 +143,8 @@ export async function retryableFetch(url, init, opts) {
                 throw e;
             }
             const delayMs = jittered(BACKOFF_MS[Math.min(attempt, BACKOFF_MS.length - 1)]);
-            const reason = e?.name === 'AbortError' ? 'timeout' : (e?.message || String(e));
+            const isAbort = typeof e === 'object' && e !== null && 'name' in e && e.name === 'AbortError';
+            const reason = isAbort ? 'timeout' : errorText(e);
             opts?.onRetry?.(attempt + 1, totalRetries, delayMs, reason);
             await new Promise((r) => setTimeout(r, delayMs));
         }

package/dist/_shared/tarball-stream.d.ts

@@ -0,0 +1,93 @@
+/**
+ * tarball-stream.ts — pure streaming tar primitives.
+ *
+ * A leaf with no imports at all, deliberately: `bundle-facet-workers.mjs`
+ * esbuilds this file into a string constant the loader pool injects into
+ * dynamic workers, and a facet isolate resolves no specifier. Anything this
+ * file imported would have to travel with it.
+ *
+ * Zero dependencies. Works identically on the supervisor and inside a
+ * facet isolate. Never buffers the full decompressed tarball — peak
+ * transient heap is one file's bytes plus a 512-byte carry.
+ */
+/**
+ * Maximum size of a single file inside a tarball. Larger entries are skipped.
+ *
+ * History: 5 MB was too low — it silently dropped `esbuild-wasm/esbuild.wasm`
+ * (11.35 MB on v0.24.2), which made Nimbus-in-Nimbus `npm run dev` fail with
+ * `No such module "esbuild-wasm/esbuild.wasm"` since the missing file caused
+ * esbuild's VFS plugin to mark the import `external`, and workerd's LOADER
+ * has no entry for that specifier. 20 MB covers esbuild-wasm with headroom
+ * while keeping per-facet peak heap bounded for the streaming extractor.
+ */
+export declare const MAX_FILE_BYTES = 20000000;
+/**
+ * Read one tar header (USTAR) out of `block`. Returns parsed fields or
+ * `null` for an end-of-archive block (all zeros).
+ */
+/**
+ * Collapse "."/".." segments in a tar entry's package-relative path.
+ * Returns the canonical relative path, or '' when the entry escapes its
+ * package root (a leading ".." that pops above the root) — the caller
+ * treats '' as a no-name entry and skips it. Mirrors the segment logic in
+ * w7-frame's canonicalPath so joined write paths are always accepted.
+ */
+export declare function canonicalTarName(name: string): string;
+export declare function parseTarHeader(block: Uint8Array): {
+    name: string;
+    size: number;
+    typeFlag: number;
+} | null;
+/**
+ * Wrap a `ReadableStream<Uint8Array>` as an async iterable. Workerd and
+ * Node both support `Symbol.asyncIterator` on ReadableStream, but we
+ * spell the reader loop out so we don't depend on ambient lib typings.
+ */
+export declare function readableStreamToAsyncIterable(rs: ReadableStream<Uint8Array>): AsyncGenerator<Uint8Array, void, undefined>;
+/**
+ * Reason a tar entry was skipped and never yielded. Surfaced to callers
+ * via the optional `onSkip` callback on `streamTarEntries`.
+ *
+ * - 'too-large': size > MAX_FILE_BYTES. The most common reason Nimbus
+ *   cares about — it's what caused esbuild-wasm/esbuild.wasm to vanish
+ *   silently in Nimbus-in-Nimbus before the cap was raised.
+ * - 'non-regular': typeFlag indicates a symlink / hardlink / directory /
+ *   PaxHeader / GNU LongName etc. These aren't files we stage.
+ * - 'no-name': header parsed but name was empty (malformed or a PaxHeader
+ *   that our parser didn't recognize as non-regular).
+ */
+export type TarSkipReason = 'too-large' | 'non-regular' | 'no-name';
+/**
+ * Optional skip-observer passed to `streamTarEntries`. Called ONCE per
+ * skipped entry, with the declared name (may be empty for 'no-name'
+ * skips) and the declared size in bytes.
+ *
+ * Consumers typically push these into a per-package warnings array so
+ * users see what wasn't installed. The callback is synchronous and
+ * must not throw — thrown errors are swallowed to keep the extractor
+ * best-effort.
+ */
+export type TarSkipCallback = (name: string, size: number, reason: TarSkipReason) => void;
+/**
+ * Streaming tar extractor.
+ *
+ * Consumes an async iterable of Uint8Array chunks (the decompressed tar
+ * byte stream) and yields one `{ name, data }` entry per regular file,
+ * as each file completes.
+ *
+ * Memory invariant: holds at most one pending file's bytes (≤ MAX_FILE_BYTES)
+ * plus a small carry buffer for the tar header being assembled.
+ *
+ * Skips: symlinks, directories, hardlinks, long-name extensions (PaxHeader),
+ * and any file whose declared size exceeds MAX_FILE_BYTES.
+ *
+ * If `onSkip` is provided, it is invoked for each skipped entry with the
+ * name, declared size, and reason code. Callers that need to surface
+ * dropped-file warnings to users should pass one; legacy callers that
+ * omit the arg still behave exactly as before (silent skip).
+ */
+export declare function streamTarEntries(source: AsyncIterable<Uint8Array>, onSkip?: TarSkipCallback): AsyncGenerator<{
+    name: string;
+    data: Uint8Array;
+}, void, undefined>;
+//# sourceMappingURL=tarball-stream.d.ts.map

package/dist/_shared/tarball-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tarball-stream.d.ts","sourceRoot":"","sources":["../../src/_shared/tarball-stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,WAAa,CAAC;AAEzC;;;GAGG;AACH;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWrD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA+BzG;AAED;;;;GAIG;AACH,wBAAuB,6BAA6B,CAClD,EAAE,EAAE,cAAc,CAAC,UAAU,CAAC,GAC7B,cAAc,CAAC,UAAU,EAAE,IAAI,EAAE,SAAS,CAAC,CAW7C;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,aAAa,GAAG,SAAS,CAAC;AAEpE;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,KAClB,IAAI,CAAC;AAEV;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAuB,gBAAgB,CACrC,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,EACjC,MAAM,CAAC,EAAE,eAAe,GACvB,cAAc,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,EAAE,IAAI,EAAE,SAAS,CAAC,CA6GrE"}

package/dist/_shared/tarball-stream.js

@@ -0,0 +1,235 @@
+/**
+ * tarball-stream.ts — pure streaming tar primitives.
+ *
+ * A leaf with no imports at all, deliberately: `bundle-facet-workers.mjs`
+ * esbuilds this file into a string constant the loader pool injects into
+ * dynamic workers, and a facet isolate resolves no specifier. Anything this
+ * file imported would have to travel with it.
+ *
+ * Zero dependencies. Works identically on the supervisor and inside a
+ * facet isolate. Never buffers the full decompressed tarball — peak
+ * transient heap is one file's bytes plus a 512-byte carry.
+ */
+/**
+ * Maximum size of a single file inside a tarball. Larger entries are skipped.
+ *
+ * History: 5 MB was too low — it silently dropped `esbuild-wasm/esbuild.wasm`
+ * (11.35 MB on v0.24.2), which made Nimbus-in-Nimbus `npm run dev` fail with
+ * `No such module "esbuild-wasm/esbuild.wasm"` since the missing file caused
+ * esbuild's VFS plugin to mark the import `external`, and workerd's LOADER
+ * has no entry for that specifier. 20 MB covers esbuild-wasm with headroom
+ * while keeping per-facet peak heap bounded for the streaming extractor.
+ */
+export const MAX_FILE_BYTES = 20_000_000;
+/**
+ * Read one tar header (USTAR) out of `block`. Returns parsed fields or
+ * `null` for an end-of-archive block (all zeros).
+ */
+/**
+ * Collapse "."/".." segments in a tar entry's package-relative path.
+ * Returns the canonical relative path, or '' when the entry escapes its
+ * package root (a leading ".." that pops above the root) — the caller
+ * treats '' as a no-name entry and skips it. Mirrors the segment logic in
+ * w7-frame's canonicalPath so joined write paths are always accepted.
+ */
+export function canonicalTarName(name) {
+    const out = [];
+    for (const seg of name.split('/')) {
+        if (seg === '..') {
+            if (out.length === 0)
+                return '';
+            out.pop();
+        }
+        else if (seg !== '' && seg !== '.') {
+            out.push(seg);
+        }
+    }
+    return out.join('/');
+}
+export function parseTarHeader(block) {
+    if (block[0] === 0)
+        return null;
+    let name = '';
+    for (let i = 0; i < 100 && block[i] !== 0; i++) {
+        name += String.fromCharCode(block[i]);
+    }
+    let prefix = '';
+    for (let i = 345; i < 500 && block[i] !== 0; i++) {
+        prefix += String.fromCharCode(block[i]);
+    }
+    if (prefix)
+        name = prefix + '/' + name;
+    // Strip the npm `package/` convention.
+    name = name.replace(/^package\//, '');
+    // Canonicalize the entry-relative path. npm tarballs legitimately carry
+    // entries like "./dist/index.js" (agent-base, http-proxy-agent,
+    // protobufjs, ...); left as-is the "./" survives into the VFS write path
+    // and the w7-frame writer rejects the noncanonical path, failing the
+    // whole shared install wave and dropping shard-mates' completion markers.
+    // Collapsing here (the one place entry names are assembled) keeps every
+    // downstream join canonical. An entry that escapes its package root via
+    // ".." is dropped to '' → skipped as a no-name entry.
+    name = canonicalTarName(name);
+    let sizeStr = '';
+    for (let i = 124; i < 136 && block[i] !== 0; i++) {
+        sizeStr += String.fromCharCode(block[i]);
+    }
+    const size = parseInt(sizeStr.trim(), 8) || 0;
+    const typeFlag = block[156];
+    return { name, size, typeFlag };
+}
+/**
+ * Wrap a `ReadableStream<Uint8Array>` as an async iterable. Workerd and
+ * Node both support `Symbol.asyncIterator` on ReadableStream, but we
+ * spell the reader loop out so we don't depend on ambient lib typings.
+ */
+export async function* readableStreamToAsyncIterable(rs) {
+    const reader = rs.getReader();
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                return;
+            if (value && value.length > 0)
+                yield value;
+        }
+    }
+    finally {
+        try {
+            reader.releaseLock();
+        }
+        catch { /* ignore */ }
+    }
+}
+/**
+ * Streaming tar extractor.
+ *
+ * Consumes an async iterable of Uint8Array chunks (the decompressed tar
+ * byte stream) and yields one `{ name, data }` entry per regular file,
+ * as each file completes.
+ *
+ * Memory invariant: holds at most one pending file's bytes (≤ MAX_FILE_BYTES)
+ * plus a small carry buffer for the tar header being assembled.
+ *
+ * Skips: symlinks, directories, hardlinks, long-name extensions (PaxHeader),
+ * and any file whose declared size exceeds MAX_FILE_BYTES.
+ *
+ * If `onSkip` is provided, it is invoked for each skipped entry with the
+ * name, declared size, and reason code. Callers that need to surface
+ * dropped-file warnings to users should pass one; legacy callers that
+ * omit the arg still behave exactly as before (silent skip).
+ */
+export async function* streamTarEntries(source, onSkip) {
+    let carry = new Uint8Array(0);
+    let state = { kind: 'header' };
+    function concat(a, b) {
+        if (a.length === 0)
+            return b;
+        if (b.length === 0)
+            return a;
+        const out = new Uint8Array(a.length + b.length);
+        out.set(a, 0);
+        out.set(b, a.length);
+        return out;
+    }
+    for await (const chunkRaw of source) {
+        let buf = concat(carry, chunkRaw);
+        let cursor = 0;
+        while (true) {
+            if (state.kind === 'header') {
+                if (buf.length - cursor < 512)
+                    break;
+                const header = buf.subarray(cursor, cursor + 512);
+                const parsed = parseTarHeader(header);
+                cursor += 512;
+                if (!parsed)
+                    return; // end-of-archive
+                const { name, size, typeFlag } = parsed;
+                const pad = size === 0 ? 0 : (512 - (size % 512)) % 512;
+                const isRegularFile = (typeFlag === 48 /* '0' */ || typeFlag === 0);
+                if (size === 0) {
+                    if (isRegularFile && name) {
+                        yield { name, data: new Uint8Array(0) };
+                    }
+                    state = { kind: 'header' };
+                    continue;
+                }
+                if (!isRegularFile || !name || size > MAX_FILE_BYTES) {
+                    if (onSkip) {
+                        // Classify before entering the skip state so the reason is
+                        // exact. Precedence matches the condition order above:
+                        // non-regular first (directories/symlinks/PaxHeaders are
+                        // skipped regardless of size), then no-name, then too-large.
+                        const reason = !isRegularFile
+                            ? 'non-regular'
+                            : !name
+                                ? 'no-name'
+                                : 'too-large';
+                        try {
+                            onSkip(name, size, reason);
+                        }
+                        catch { /* best-effort */ }
+                    }
+                    state = { kind: 'skip', remaining: size + pad };
+                    continue;
+                }
+                state = {
+                    kind: 'file',
+                    name,
+                    remaining: size,
+                    fileBuf: new Uint8Array(size),
+                    fileOffset: 0,
+                    pad,
+                    skip: false,
+                };
+                continue;
+            }
+            if (state.kind === 'file') {
+                const avail = buf.length - cursor;
+                if (avail === 0)
+                    break;
+                if (state.remaining > 0) {
+                    const take = Math.min(state.remaining, avail);
+                    state.fileBuf.set(buf.subarray(cursor, cursor + take), state.fileOffset);
+                    state.fileOffset += take;
+                    state.remaining -= take;
+                    cursor += take;
+                    if (state.remaining > 0)
+                        break;
+                }
+                if (state.pad > 0) {
+                    const avail2 = buf.length - cursor;
+                    if (avail2 === 0)
+                        break;
+                    const take = Math.min(state.pad, avail2);
+                    state.pad -= take;
+                    cursor += take;
+                    if (state.pad > 0)
+                        break;
+                }
+                yield { name: state.name, data: state.fileBuf };
+                state = { kind: 'header' };
+                continue;
+            }
+            // state.kind === 'skip'
+            const avail = buf.length - cursor;
+            if (avail === 0)
+                break;
+            const take = Math.min(state.remaining, avail);
+            cursor += take;
+            state.remaining -= take;
+            if (state.remaining > 0)
+                break;
+            state = { kind: 'header' };
+        }
+        if (cursor >= buf.length) {
+            carry = new Uint8Array(0);
+        }
+        else if (cursor === 0) {
+            carry = buf;
+        }
+        else {
+            carry = buf.slice(cursor);
+        }
+    }
+}

package/dist/_shared/tarball.d.ts

@@ -0,0 +1,17 @@
+/**
+ * tarball.ts — a whole tarball, in memory, as a path→bytes map.
+ *
+ * The streaming primitives it walks with (`parseTarHeader`, `streamTarEntries`,
+ * `readableStreamToAsyncIterable`) live in `./tarball-stream.ts` — a
+ * dependency-free leaf, because `bundle-facet-workers.mjs` esbuilds that file
+ * into a string the loader pool injects into dynamic workers, where an import
+ * would not resolve.
+ *
+ * This half is for a caller that already holds the bytes: `gem install`, which
+ * fetches a `.gem` (a tar holding a gzipped tar) and needs both layers open at
+ * once. An installer streaming a tarball it is still downloading should drive
+ * `streamTarEntries` itself and never hold the whole thing.
+ */
+/** Extract every regular file. Gzipped input is decompressed first. */
+export declare function extractTarball(tarball: ArrayBuffer): Promise<Map<string, Uint8Array>>;
+//# sourceMappingURL=tarball.d.ts.map

package/dist/_shared/tarball.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tarball.d.ts","sourceRoot":"","sources":["../../src/_shared/tarball.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH,uEAAuE;AACvE,wBAAsB,cAAc,CAClC,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAsBlC"}