@nimbus-sh/core 0.2.0 → 0.4.0

package/dist/workspace/nimbus-workspace.js

@@ -3,37 +3,49 @@
  *
  * A workspace is a durable filesystem plus a shell over it. It owns no
  * transport, no session, no socket and no Durable Object: the host supplies
- * SQLite and gets back `.fs` and `.exec`. That is what makes it embeddable in
- * a Durable Object that is already busy powering something else, and what
- * makes it runnable in a plain bun process over `bun:sqlite`.
+ * the filesystem and gets back `.fs`, `.exec`, and a command registry to add
+ * to. That is what makes it embeddable in a Durable Object that is already
+ * busy powering something else, and what makes it runnable in a plain bun
+ * process over `bun:sqlite`.
  *
- * The composition here is not new. It is the one `session/init.ts` performs,
- * lifted out of the session so there is one recipe rather than one per caller
- * — five unit tests were already hand-rolling it, one of them reaching a
- * private field to do so. The boot itself still belongs to `Sandbox.create`;
- * this adds only what a durable, credentialed filesystem needs on top and
- * nothing the sandbox already knows how to do.
+ * The composition here is not new. It is the one `session/init.ts` performed
+ * inline, lifted out of the session so there is one recipe rather than one per
+ * caller — the session now reads its kernel, shell and registry off a
+ * workspace, and five unit tests were already hand-rolling the same steps.
+ *
+ * Deliberately not `Sandbox.create`, which is the lifo demo sandbox's boot
+ * rather than this one: it registers `systemctl`, `tunnel` and the network
+ * command set, boots enabled service units out of `/etc/systemd`, and starts
+ * the shell before the host can register a command of its own. A session
+ * routed through it would silently acquire all of that.
  */
-import { Sandbox } from '../substrate/lifo/sandbox/Sandbox.js';
+import { Kernel } from '../substrate/lifo/kernel/index.js';
+import { Shell } from '../substrate/lifo/shell/Shell.js';
+import { createDefaultRegistry } from '../substrate/lifo/commands/registry.js';
+import { SandboxCommandsImpl } from '../substrate/lifo/sandbox/SandboxCommands.js';
 import { SandboxFsImpl } from '../substrate/lifo/sandbox/SandboxFs.js';
+import { HeadlessTerminal } from '../substrate/lifo/sandbox/HeadlessTerminal.js';
 import { SqliteVFS, SqliteVFSProvider } from '../vfs/sqlite-vfs.js';
-import { DEFAULT_MOUNT_POINTS, DEFAULT_PATH } from '../constants.js';
+import { DEFAULT_HOME, DEFAULT_HOSTNAME, DEFAULT_MOUNT_POINTS, DEFAULT_PATH, DEFAULT_SHELL, DEFAULT_USER, NIMBUS_VERSION, } from '../constants.js';
 import { CRED_KERNEL, CRED_SESSION_USER } from '../runtime/os-contracts.js';
 import { PID_GEN_STRIDE } from '../runtime/process-table.js';
 import { SessionProcessSupervisor } from '../runtime/session-process-supervisor.js';
 import { rehydrateInstalledRuntimesView, } from '../runtime/installed-runtimes.js';
+import { seedRuntimePackage } from '../runtime/runtime-package.js';
 import { registerUnixCommands } from '../shell/unix-commands.js';
 import { installPathExecResolver } from '../shell/exec-dispatch.js';
 /**
  * A durable filesystem and a shell over it.
  *
- * Created with {@link NimbusWorkspace.create} rather than `new` because the
- * boot it delegates to sources `/etc/profile`, which is genuinely async. A
- * Durable Object constructor cannot await, so a host constructs the workspace
- * in its first request rather than in its constructor.
+ * The composition itself is synchronous. {@link create} awaits only the
+ * optional work — installing runtime packages, loading the wasm runner modules
+ * — so a host that asks for neither is never suspended between mounting the
+ * filesystem and registering the commands. A Durable Object needs that: it
+ * must not take delivery of an event with a half-built shell. The remaining
+ * async step, running the user's login files, is {@link start}, which the host
+ * calls once its own commands are in place.
  */
 export class NimbusWorkspace {
-    sandbox;
     sql;
     /**
      * Credentialed and mount-aware. Acts as the session user, never as the
@@ -45,48 +57,84 @@ export class NimbusWorkspace {
     vfs;
     kernel;
     shell;
-    constructor(sandbox, vfs, sql) {
-        this.sandbox = sandbox;
+    /** What the shell resolves a command name against. A host adds its own. */
+    registry;
+    /**
+     * The environment the shell was composed with. The shell's own copy drifts
+     * from this one the moment the user exports anything; this is what a host
+     * hands to a subordinate shell it starts itself.
+     */
+    env;
+    commands;
+    constructor(vfs, kernel, shell, registry, env, sql) {
         this.sql = sql;
         this.vfs = vfs;
-        this.kernel = sandbox.kernel;
-        this.shell = sandbox.shell;
-        // NOT `sandbox.fs`, which wraps the raw kernel VFS. The mount is
-        // kernel-credentialed because the shell re-credentials per command; a host
-        // calling `.fs` has no process behind it and must not inherit that.
-        this.fs = new SandboxFsImpl(sandbox.kernel.vfs.as(CRED_SESSION_USER), () => sandbox.shell.getCwd());
+        this.kernel = kernel;
+        this.shell = shell;
+        this.registry = registry;
+        this.env = env;
+        this.commands = new SandboxCommandsImpl(shell, registry);
+        // NOT the kernel VFS as it stands, which is kernel-credentialed because
+        // the shell re-credentials per command; a host calling `.fs` has no
+        // process behind it and must not inherit that.
+        this.fs = new SandboxFsImpl(kernel.vfs.as(CRED_SESSION_USER), () => shell.getCwd());
     }
     static async create(options) {
-        const vfs = new SqliteVFS(options.sql, options.transactions);
-        vfs.revokeAppendWritersThrough((options.generation ?? 1) * PID_GEN_STRIDE);
+        const vfs = options.vfs ?? openFilesystem(options);
         const mounts = options.mounts ?? DEFAULT_MOUNT_POINTS;
         seedBaseFilesystem(vfs, mounts);
-        const sandbox = await Sandbox.create({
-            env: options.env,
-            cwd: options.cwd,
-            terminal: options.terminal,
-            providerMounts: mounts.map((mount) => ({
-                virtualPath: '/' + mount,
-                provider: new SqliteVFSProvider(vfs, mount),
-            })),
-        });
+        const kernel = new Kernel();
+        // Seeds the in-memory tree. Mounting AFTER it is what keeps a durable
+        // /etc from being overwritten by the defaults on every boot.
+        kernel.initFilesystem();
+        for (const mount of mounts) {
+            kernel.vfs.mount(`/${mount}`, new SqliteVFSProvider(vfs, mount));
+        }
+        const registry = createDefaultRegistry();
         // The durable coreutils replace ~25 lifo builtins. They are the ones that
         // carry credentials and read this filesystem's uid/gid, so they must win.
-        registerUnixCommands(sandbox.commands.registry, vfs);
-        installPathExecResolver(sandbox.commands.registry, vfs.as(CRED_SESSION_USER), () => sandbox.shell.getCwd());
+        registerUnixCommands(registry, vfs);
+        const env = { ...defaultEnv(), ...options.env };
+        const shell = new Shell(options.terminal ?? new HeadlessTerminal(), kernel.vfs, registry, env, kernel.processRegistry, options.identity);
+        if (options.cwd)
+            shell.setCwd(options.cwd);
+        // Kernel-credentialed on purpose: this only INSPECTS a file to decide how
+        // to run it, and re-checks the caller's own execute permission at
+        // invocation time — the `authorize` wrapper in exec-dispatch.ts.
+        installPathExecResolver(registry, vfs.as(CRED_KERNEL), () => shell.getCwd());
+        const home = env.HOME ?? DEFAULT_HOME;
+        // Before the runners are wired, because registration reads what the
+        // filesystem holds — the same order `nimbus install` observes, and the
+        // same order a Durable Object observes when it rehydrates after eviction.
+        for (const runtimePackage of options.runtimes ?? []) {
+            await seedRuntimePackage(vfs.as(CRED_KERNEL), home, runtimePackage);
+        }
         if (options.facets) {
             await registerWasmRuntimes({
                 facets: options.facets,
                 vfs,
-                registry: sandbox.commands.registry,
+                registry,
                 generation: options.generation ?? 1,
-                home: options.env?.HOME ?? '/home/user',
+                home,
             });
         }
-        return new NimbusWorkspace(sandbox, vfs, options.sql);
+        return new NimbusWorkspace(vfs, kernel, shell, registry, env, options.sql);
     }
     exec(command, options) {
-        return this.sandbox.commands.run(command, options);
+        return this.commands.run(command, options);
+    }
+    /**
+     * Apply the login files, and begin reading the terminal when there is one.
+     *
+     * Separate from {@link create} because a host with commands of its own must
+     * register them first: `/etc/profile` and `~/.nimbusrc` are the user's
+     * files, and either may name a command the host has yet to supply.
+     */
+    async start() {
+        // Sources /etc/profile and the first user rc file it finds, then prompts.
+        this.shell.start();
+        // Nimbus's own rc file, which the shell's list predates.
+        await this.shell.sourceFile(`${this.shell.getEnv().HOME ?? DEFAULT_HOME}/.nimbusrc`);
     }
     /**
      * Files, directories and bytes this workspace occupies.
@@ -113,6 +161,51 @@ export class NimbusWorkspace {
         }
     }
 }
+/**
+ * Open the durable filesystem for a host that has not opened one itself.
+ *
+ * The revocation is here rather than in `create` because it is the act of
+ * OPENING that carries it: pids at or below this generation's floor belong to
+ * an instance that is gone, and their append capabilities must stop being
+ * honoured before the first read. A host that opened the filesystem itself has
+ * already done this, at the same seam, for the same reason.
+ */
+function openFilesystem(options) {
+    const vfs = new SqliteVFS(options.sql, options.transactions);
+    vfs.revokeAppendWritersThrough((options.generation ?? 1) * PID_GEN_STRIDE);
+    return vfs;
+}
+/**
+ * The environment a Nimbus shell starts in.
+ *
+ * `PATH` and `EDITOR` restate what the seeded `/etc/profile` exports, so a
+ * workspace whose host never runs the login files is still on the real PATH.
+ * `PORT` and `HOST` are here because every scaffolded server reads them and
+ * gets `undefined` otherwise — Express's default app, every create-vite
+ * template, `${PORT:-3000}` in a package.json script.
+ */
+function defaultEnv() {
+    return {
+        HOME: DEFAULT_HOME,
+        USER: DEFAULT_USER,
+        SHELL: DEFAULT_SHELL,
+        HOSTNAME: DEFAULT_HOSTNAME,
+        TERM: 'xterm-256color',
+        PWD: DEFAULT_HOME,
+        PATH: DEFAULT_PATH,
+        PS1: `\x1b[1;32muser@${DEFAULT_HOSTNAME}\x1b[0m:\x1b[1;34m\\w\x1b[0m$ `,
+        NODE_ENV: 'development',
+        LANG: 'en_US.UTF-8',
+        EDITOR: 'nano',
+        NIMBUS_VERSION: NIMBUS_VERSION,
+        TMPDIR: '/tmp',
+        XDG_CONFIG_HOME: `${DEFAULT_HOME}/.config`,
+        XDG_DATA_HOME: `${DEFAULT_HOME}/.local/share`,
+        npm_config_prefix: '/usr/local',
+        PORT: '3000',
+        HOST: '0.0.0.0',
+    };
+}
 /**
  * Turn a facet host into commands: the runtimes this filesystem already holds,
  * plus `wasm-runner` for everything else with a `\0asm` header.
@@ -127,24 +220,31 @@ export class NimbusWorkspace {
  * them.
  */
 async function registerWasmRuntimes(deps) {
-    const [{ makeBashRunnerFactory }, { makeCPythonRunnerFactory }, { wasmRunnerSpec }, { buildRuntimeHandler }, esbuildModule,] = await Promise.all([
+    const [{ makeBashRunnerFactory }, { makeCPythonRunnerFactory }, { makeRubyRunnerFactory }, { makeClangRunnerFactory }, { wasmRunnerSpec }, { buildRuntimeHandler },] = await Promise.all([
         import('../runtime/bash-runner.js'),
         import('../runtime/cpython-runner.js'),
+        import('../runtime/ruby-runner.js'),
+        import('../runtime/clang-runner.js'),
         import('../runtime/wasm-runner.js'),
         import('../runtime/runtime-registry.js'),
-        import('../runtime/esbuild-service.js'),
     ]);
     // wasm-runner allocates pids for what it runs, so it needs a process table
-    // whose pid space is this generation's — the same rule the append writers
-    // above are revoked by.
+    // whose pid space is this generation's.
     const processes = new SessionProcessSupervisor();
     processes.setPidBase(deps.generation * PID_GEN_STRIDE);
+    // Loaded on the first TypeScript or ESM script and not before. The module
+    // statically imports `esbuild-wasm/esbuild.wasm`, which only wrangler
+    // resolves — node instantiates it as a wasm module and fails on its Go
+    // imports — so a host outside Cloudflare must be able to run a shell, bash
+    // and python without that module ever entering its graph.
     let esbuild = null;
     deps.registry.register('wasm-runner', buildRuntimeHandler(wasmRunnerSpec({ vfs: deps.vfs, facets: deps.facets, processes }), {
         vfs: deps.vfs,
         getEsbuild: () => {
-            if (!esbuild)
-                esbuild = new esbuildModule.EsbuildService(deps.vfs);
+            if (!esbuild) {
+                esbuild = import('../runtime/esbuild-service.js')
+                    .then((module) => new module.EsbuildService(deps.vfs));
+            }
             return esbuild;
         },
         registry: deps.registry,
@@ -153,8 +253,13 @@ async function registerWasmRuntimes(deps) {
         'bash-runner': makeBashRunnerFactory({ facets: deps.facets, vfs: deps.vfs }),
         // No `startResident`: a workspace owns no actor that could outlive the
         // call, so a program that keeps serving is refused by name rather than
-        // run as a one-shot that dies with it.
+        // run as a one-shot that dies with it. Same for ruby, where a script is
+        // the shape that may bind a port.
         'cpython-runner': makeCPythonRunnerFactory({ facets: deps.facets, vfs: deps.vfs }),
+        'ruby-runner': makeRubyRunnerFactory({
+            facets: deps.facets, vfs: deps.vfs, registry: deps.registry,
+        }),
+        'clang-runner': makeClangRunnerFactory({ facets: deps.facets, vfs: deps.vfs }),
     };
     rehydrateInstalledRuntimesView(deps.vfs.as(CRED_KERNEL), deps.registry, deps.home, (key) => runners[key]);
 }
@@ -185,8 +290,14 @@ const WORKSPACE_TABLES = [
  * a workspace reopened over a populated database keeps whatever the user did
  * to these files. `/etc/passwd` and `/etc/group` are load-bearing rather than
  * decorative — `id`, `chown` and `su` resolve names through them.
+ *
+ * What a PRODUCT puts in a fresh filesystem — a banner, a welcome file, a
+ * starter app — is not here. This is the base an OS needs in order to boot,
+ * and it is exported because a host may need the filesystem before it needs a
+ * shell: the Nimbus session seeds its starter project for a browser that hits
+ * `/preview` without ever opening a terminal.
  */
-function seedBaseFilesystem(vfs, mounts) {
+export function seedBaseFilesystem(vfs, mounts) {
     const fs = vfs.as(CRED_SESSION_USER);
     const rootFs = vfs.as(CRED_KERNEL);
     // Created AS the session user, so the user owns their own tree. Seeding
@@ -195,12 +306,37 @@ function seedBaseFilesystem(vfs, mounts) {
         if (mount !== 'etc' && !fs.exists(mount))
             fs.mkdir(mount, { recursive: true });
     }
-    for (const dir of ['home/user', 'usr/bin', 'usr/local/bin', 'var/log', 'tmp']) {
+    for (const dir of [
+        'home/user', 'home/user/.config', 'home/user/projects',
+        'tmp', 'var/log',
+        'usr/bin', 'usr/lib', 'usr/lib/node_modules',
+        'usr/share', 'usr/share/pkg', 'usr/share/pkg/node_modules',
+        'usr/local', 'usr/local/lib', 'usr/local/lib/node_modules', 'usr/local/bin',
+    ]) {
         if (!fs.exists(dir))
             fs.mkdir(dir, { recursive: true });
     }
-    if (!rootFs.exists('etc'))
+    // /etc belongs to root, and is re-asserted rather than only created: a
+    // user-writable /etc is an authority bug, not an untidy directory.
+    if (!rootFs.exists('etc')) {
         rootFs.mkdir('etc', { mode: 0o755 });
+    }
+    else {
+        const etc = rootFs.stat('etc');
+        if (etc.uid !== 0 || etc.gid !== 0)
+            rootFs.chown('etc', 0, 0);
+        if ((etc.mode & 0o7777) !== 0o755)
+            rootFs.chmod('etc', 0o755);
+    }
+    if (!rootFs.exists('etc/hostname')) {
+        rootFs.writeFile('etc/hostname', `${DEFAULT_HOSTNAME}\n`);
+        rootFs.chown('etc/hostname', CRED_SESSION_USER.uid, CRED_SESSION_USER.gid);
+    }
+    if (!rootFs.exists('etc/os-release')) {
+        rootFs.writeFile('etc/os-release', `NAME="Nimbus"\nVERSION="${NIMBUS_VERSION}"\nID=nimbus\n`
+            + 'PRETTY_NAME="Nimbus — Cloud Dev Environment"\n');
+        rootFs.chown('etc/os-release', CRED_SESSION_USER.uid, CRED_SESSION_USER.gid);
+    }
     // Root-owned 0644, and re-asserted rather than only created: these decide
     // what `id`, `chown` and `su` believe, so a user-writable /etc/passwd would
     // be an authority bug rather than an untidy file.
@@ -215,8 +351,17 @@ function seedBaseFilesystem(vfs, mounts) {
     };
     accountFile('etc/passwd', 'root:x:0:0:root:/root:/bin/sh\nuser:x:1000:1000:Nimbus User:/home/user:/bin/sh\n');
     accountFile('etc/group', 'root:x:0:\nuser:x:1000:user\n');
+    const defaultProfile = `export PATH=${DEFAULT_PATH}\nexport EDITOR=nano\n`;
     if (!rootFs.exists('etc/profile')) {
-        rootFs.writeFile('etc/profile', `export PATH=${DEFAULT_PATH}\nexport EDITOR=nano\n`);
+        rootFs.writeFile('etc/profile', defaultProfile);
         rootFs.chown('etc/profile', CRED_SESSION_USER.uid, CRED_SESSION_USER.gid);
     }
+    else if (rootFs.readFileString('etc/profile') === 'export PATH=/usr/bin:/bin\nexport EDITOR=nano\n') {
+        // The lifo default, from before Nimbus had a PATH of its own. Nobody ever
+        // chose it, so replacing it is not overwriting a user's file.
+        rootFs.writeFile('etc/profile', defaultProfile);
+    }
+    if (!fs.exists('home/user/.nimbusrc')) {
+        fs.writeFile('home/user/.nimbusrc', '# Nimbus shell config\nalias ll="ls -la"\nalias la="ls -a"\nalias l="ls -1"\n');
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimbus-sh/core",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Backend-agnostic half of Nimbus \u2014 the durable filesystem, the shell, and the OS/process contracts, over a host-supplied SQL port.",
   "keywords": [
     "filesystem",
@@ -45,7 +45,9 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json --noCheck --noEmit false --declaration true --declarationMap true --outDir dist --rootDir src",

package/src/_shared/tarball-stream.ts

@@ -0,0 +1,263 @@
+/**
+ * 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: string): string {
+  const out: string[] = [];
+  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: Uint8Array): { name: string; size: number; typeFlag: number } | null {
+  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: ReadableStream<Uint8Array>,
+): AsyncGenerator<Uint8Array, void, undefined> {
+  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 */ }
+  }
+}
+
+/**
+ * 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 async function* streamTarEntries(
+  source: AsyncIterable<Uint8Array>,
+  onSkip?: TarSkipCallback,
+): AsyncGenerator<{ name: string; data: Uint8Array }, void, undefined> {
+  let carry: Uint8Array<ArrayBufferLike> = new Uint8Array(0);
+
+  type State =
+    | { kind: 'header' }
+    | { kind: 'file'; name: string; remaining: number; fileBuf: Uint8Array; fileOffset: number; pad: number; skip: boolean }
+    | { kind: 'skip'; remaining: number };
+  let state: State = { kind: 'header' };
+
+  function concat(a: Uint8Array, b: Uint8Array): Uint8Array {
+    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: TarSkipReason = !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);
+    }
+  }
+}