@nimbus-sh/core 0.6.0 → 0.7.0

package/src/substrate/lifo/commands/io/dd.ts

@@ -91,7 +91,7 @@ async function copyFromStdin(ctx: CommandContext, options: DdOptions): Promise<n
       skipRemaining -= chunk.length;
       continue;
     }
-    const bytes = encode(chunk);
+    const bytes = typeof chunk === 'string' ? encode(chunk) : chunk;
     sink.write(bytes);
     copied += bytes.length;
   }
@@ -99,7 +99,7 @@ async function copyFromStdin(ctx: CommandContext, options: DdOptions): Promise<n
   return copied;
 }
 
-async function readStdinChunk(stdin: CommandInputStream, want: number): Promise<string | null> {
+async function readStdinChunk(stdin: CommandInputStream, want: number): Promise<Uint8Array | string | null> {
   if (stdin.readBytes) return stdin.readBytes(want);
   return stdin.read();
 }

package/src/substrate/lifo/commands/net/curl.ts

@@ -12,6 +12,8 @@ type CurlOptions = {
   dataParts: CurlDataPart[];
   data?: string;
   outputFile?: string;
+  /** -D/--dump-header target: response headers go to this file, or to stdout when it is '-'. */
+  dumpHeaders?: string;
   silent: boolean;
   showError: boolean;
   followRedirects: boolean;
@@ -58,9 +60,101 @@ type VirtualResponse = {
   _donePromise?: Promise<void>;
 };
 
-const SHORT_VALUE_OPTIONS = new Set(['X', 'H', 'd', 'o', 'w']);
+const SHORT_VALUE_OPTIONS = new Set(['X', 'H', 'd', 'o', 'w', 'D']);
+
+/** What a header dump needs from a response — native Response or shaped. */
+type CurlHeaderSource = {
+  status: number;
+  statusText: string;
+  headers: Headers | Record<string, string>;
+};
 const MAX_REDIRECTS = 20;
 
+/** curl's exit code for local write failures (-o/-D targets). */
+const CURL_WRITE_ERROR_EXIT = 23;
+
+/**
+ * A dump-target failure is a local write problem, not a transport error: it
+ * must surface as exit 23 with the precise cause, never as a rejected
+ * virtual call or a generic connection-failure exit 7.
+ */
+class CurlHeaderWriteError extends Error {
+  constructor(action: string, target: string, cause: unknown) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    super(`${action} dump-header file '${target}': ${detail}`);
+  }
+}
+
+/**
+ * Transfer-scoped sink for -D/--dump-header, opened once per command before
+ * the request. '-' streams straight to stdout with no init; a VFS path is
+ * truncated into existence up front — an empty file is the truthful record
+ * of a response that never arrived — and every received header block is
+ * persisted on arrival, before any body drain. With no -D flag at all the
+ * sink is inert; an empty-string target is still a target — it resolves to
+ * the cwd, the write is attempted up front, and failing it exits 23.
+ */
+class CurlHeaderSink {
+  private readonly ctx: Parameters<Command>[0];
+  private readonly target: string | null;
+  private contents: string[] = [];
+
+  constructor(ctx: Parameters<Command>[0], target: string | null) {
+    this.ctx = ctx;
+    this.target = target;
+  }
+
+  /** True when no -D was given: every sink method is a no-op. */
+  get inert(): boolean {
+    return this.target === null;
+  }
+
+  /** Truncate/create the file target up front; '-' needs no init, no -D skips. */
+  async open(): Promise<void> {
+    if (this.target === null || this.target === '-') return;
+    try {
+      this.ctx.vfs.writeFile(resolve(this.ctx.cwd, this.target), '');
+    } catch (error) {
+      throw new CurlHeaderWriteError('create', this.target, error);
+    }
+  }
+
+  /** Persist one received response's header block, in arrival order. */
+  async writeBlock(response: CurlHeaderSource): Promise<void> {
+    if (this.target === null) return;
+    const block = curlHeaderBlock(response);
+    try {
+      if (this.target === '-') {
+        this.ctx.stdout.write(block);
+        return;
+      }
+      this.contents.push(block);
+      this.ctx.vfs.writeFile(resolve(this.ctx.cwd, this.target), this.contents.join(''));
+    } catch (error) {
+      throw new CurlHeaderWriteError('write', this.target, error);
+    }
+  }
+}
+
+function reportCurlWriteError(ctx: Parameters<Command>[0], error: CurlHeaderWriteError): number {
+  ctx.stderr.write(`curl: (${CURL_WRITE_ERROR_EXIT}) Failed ${error.message}\n`);
+  return CURL_WRITE_ERROR_EXIT;
+}
+
+/**
+ * Persist one arrived response block; a failing dump target cancels the
+ * undrained body before the write error surfaces, so the abandoned
+ * transfer leaks no stream on its way to exit 23.
+ */
+async function writeHeaderDump(sink: CurlHeaderSink, response: Response): Promise<void> {
+  try {
+    await sink.writeBlock(response);
+  } catch (error) {
+    cancelStreamBody(response.body);
+    throw error;
+  }
+}
+
 function createCurlImpl(kernel?: Kernel): Command {
   return async (ctx) => {
     const options = parseCurlArgs(ctx.args);
@@ -68,7 +162,7 @@ function createCurlImpl(kernel?: Kernel): Command {
 
     if (!url) {
       ctx.stderr.write('curl: no URL specified\n');
-      ctx.stderr.write('Usage: curl [-fsSLI#] [-X method] [-H header] [-d data] [-o file] [-w format] url\n');
+      ctx.stderr.write('Usage: curl [-fsSLI#] [-X method] [-H header] [-d data] [-o file] [-D file] [-w format] url\n');
       return 1;
     }
 
@@ -84,49 +178,50 @@ function createCurlImpl(kernel?: Kernel): Command {
       return 26;
     }
 
-    if (kernel?.portRegistry) {
-      const virtual = await resolveVirtualCurlResponse(kernel, ctx, options, url);
-      if (virtual?.kind === 'response') {
-        return handleCurlResponse(ctx, options, virtual.response);
-      }
-      if (virtual?.kind === 'external') {
-        url = virtual.url;
-      }
-      if (virtual?.kind === 'error') {
-        return virtual.exitCode;
-      }
-    }
-
+    const headers = new CurlHeaderSink(ctx, options.dumpHeaders ?? null);
     try {
       const requestSignal = createRequestSignal(ctx.signal, options.maxTimeSeconds);
-      const fetchOptions: RequestInit = {
-        method: options.method,
-        headers: Object.keys(options.headers).length > 0 ? options.headers : undefined,
-        body: options.data,
-        redirect: options.followRedirects ? 'follow' : 'manual',
-        signal: requestSignal.signal,
-      };
-
       try {
-        const response = await fetch(url, fetchOptions);
-        const effectiveUrl = response.url || url;
-        // Body streams to stdout as it arrives (SSE/chunked responses flow
-        // live); an -o file needs the whole payload for a single VFS write.
-        const body = options.outputFile
-          ? new Uint8Array(await response.arrayBuffer())
-          : response.body ?? '';
-        return await handleCurlResponse(ctx, options, {
-          status: response.status,
-          statusText: response.statusText,
-          headers: headersToRecord(response.headers),
-          body,
-          url: effectiveUrl,
+        await headers.open();
+
+        if (kernel?.portRegistry) {
+          const virtual = await resolveVirtualCurlResponse(kernel, ctx, options, url, headers);
+          if (virtual?.kind === 'response') {
+            return handleCurlResponse(ctx, options, virtual.response);
+          }
+          if (virtual?.kind === 'external') {
+            url = virtual.url;
+          }
+          if (virtual?.kind === 'error') {
+            return virtual.exitCode;
+          }
+        }
+
+        // -L with a dump target needs every hop's headers, so redirects are
+        // followed manually here; without -D the fetch-native follow keeps
+        // its proven semantics.
+        if (options.followRedirects && !headers.inert) {
+          return await followExternalWithDump(ctx, options, url, headers, requestSignal.signal);
+        }
+
+        const response = await fetch(url, {
+          method: options.method,
+          headers: Object.keys(options.headers).length > 0 ? options.headers : undefined,
+          body: options.data,
+          redirect: options.followRedirects ? 'follow' : 'manual',
+          signal: requestSignal.signal,
         });
+        // Headers are dumped on arrival — before any arrayBuffer()/body drain.
+        await writeHeaderDump(headers, response);
+        return await handleCurlResponse(ctx, options, await drainCurlResponse(options, response, response.url || url));
       } finally {
         requestSignal.cleanup();
       }
-    } catch (e) {
-      const msg = e instanceof Error ? e.message : String(e);
+    } catch (error) {
+      if (error instanceof CurlHeaderWriteError) {
+        return reportCurlWriteError(ctx, error);
+      }
+      const msg = error instanceof Error ? error.message : String(error);
       if (msg === CURL_TIMEOUT_ERROR) {
         ctx.stderr.write(`curl: operation timed out after ${options.maxTimeSeconds} seconds\n`);
       } else if (msg.includes('Failed to fetch') || msg.includes('NetworkError') || msg.includes('CORS')) {
@@ -140,6 +235,120 @@ function createCurlImpl(kernel?: Kernel): Command {
   };
 }
 
+/** Request headers fetch-follow strips when a redirect crosses origins. */
+const CREDENTIAL_HEADERS = ['authorization', 'proxy-authorization', 'cookie', 'cookie2'];
+
+/** Content headers that only make sense on a request that carries a body. */
+const CONTENT_HEADERS = ['content-type', 'content-length', 'transfer-encoding', 'expect'];
+
+/**
+ * Bounded manual redirect walk for external -L with a dump target: every
+ * hop's header block is written on arrival, and the final response goes
+ * through normal handling; exceeding the cap reports curl's redirect error.
+ * Request mutation mirrors fetch-follow: 301/302 collapse only POST to a
+ * bodyless GET, 303 collapses everything but HEAD, 307/308 preserve method
+ * and body; content headers go with the body, and credential headers are
+ * stripped when a hop crosses origins.
+ */
+async function followExternalWithDump(
+  ctx: Parameters<Command>[0],
+  options: CurlOptions,
+  startUrl: string,
+  headers: CurlHeaderSink,
+  signal: AbortSignal,
+): Promise<number> {
+  let current = new URL(startUrl);
+  let method = options.method;
+  let data = options.data;
+  let requestHeaders = new Headers(Object.keys(options.headers).length > 0 ? options.headers : {});
+  for (let redirects = 0; redirects <= MAX_REDIRECTS; redirects++) {
+    const response = await fetch(current, {
+      method,
+      headers: [...requestHeaders.keys()].length > 0 ? requestHeaders : undefined,
+      body: data,
+      redirect: 'manual',
+      signal,
+    });
+    // Dump on arrival — before any drain of this hop's body.
+    await writeHeaderDump(headers, response);
+    const record = headersToRecord(response.headers);
+
+    if (!isRedirectStatus(response.status)) {
+      return await handleCurlResponse(
+        ctx,
+        options,
+        await drainCurlResponse(options, response, response.url || current.toString()),
+      );
+    }
+    const location = getHeader(record, 'location');
+    if (!location) {
+      // Redirect status without a target: nothing to follow, handle as final.
+      return await handleCurlResponse(
+        ctx,
+        options,
+        await drainCurlResponse(options, response, response.url || current.toString()),
+      );
+    }
+    if (redirects === MAX_REDIRECTS) {
+      cancelStreamBody(response.body);
+      break;
+    }
+
+    let next: URL;
+    try {
+      next = new URL(location, current);
+    } catch {
+      // Unusable Location: this hop is as final as it gets — the body must
+      // still be drainable, so it is only released once we decide to follow.
+      return await handleCurlResponse(
+        ctx,
+        options,
+        await drainCurlResponse(options, response, current.toString()),
+      );
+    }
+    // Follow decision made: this hop's body is no longer needed.
+    cancelStreamBody(response.body);
+    if ([301, 302].includes(response.status) && method === 'POST') {
+      method = 'GET';
+      data = undefined;
+    } else if (response.status === 303 && method !== 'HEAD') {
+      method = 'GET';
+      data = undefined;
+    }
+    if (data === undefined) {
+      for (const name of CONTENT_HEADERS) requestHeaders.delete(name);
+    }
+    if (next.origin !== current.origin) {
+      for (const name of CREDENTIAL_HEADERS) requestHeaders.delete(name);
+    }
+    current = next;
+  }
+  ctx.stderr.write(`curl: (47) Maximum (${MAX_REDIRECTS}) redirects followed\n`);
+  return 47;
+}
+
+/**
+ * Shape a native Response for response handling. Body streams to stdout as
+ * they arrive (SSE/chunked responses flow live); an -o file needs the whole
+ * payload for a single VFS write.
+ */
+async function drainCurlResponse(
+  options: CurlOptions,
+  response: Response,
+  url: string,
+): Promise<CurlResponse> {
+  const body = options.outputFile
+    ? new Uint8Array(await response.arrayBuffer())
+    : response.body ?? '';
+  return {
+    status: response.status,
+    statusText: response.statusText,
+    headers: headersToRecord(response.headers),
+    body,
+    url,
+  };
+}
+
 const CURL_TIMEOUT_ERROR = 'curl request timeout';
 
 function parseCurlArgs(args: string[]): CurlOptions {
@@ -216,6 +425,11 @@ function parseLongOption(options: CurlOptions, arg: string, args: string[], inde
       options.outputFile = value;
       return consumed;
     }
+    case '--dump-header': {
+      const { value, consumed } = readValue();
+      options.dumpHeaders = value;
+      return consumed;
+    }
     case '--write-out': {
       const { value, consumed } = readValue();
       options.writeOut = value;
@@ -315,6 +529,9 @@ function applyShortValueOption(options: CurlOptions, flag: string, value: string
     case 'w':
       options.writeOut = value;
       break;
+    case 'D':
+      options.dumpHeaders = value;
+      break;
   }
 }
 
@@ -373,11 +590,12 @@ async function resolveVirtualCurlResponse(
   ctx: Parameters<Command>[0],
   options: CurlOptions,
   startUrl: string,
+  headers: CurlHeaderSink,
 ): Promise<VirtualCurlResult | null> {
   let currentUrl = startUrl;
 
   for (let redirects = 0; redirects <= MAX_REDIRECTS; redirects++) {
-    const response = await fetchVirtualCurlResponse(kernel, ctx, options, currentUrl);
+    const response = await fetchVirtualCurlResponse(kernel, ctx, options, currentUrl, headers);
     if (!response) {
       return redirects === 0 ? null : { kind: 'external', url: currentUrl };
     }
@@ -416,6 +634,7 @@ async function routeCurlOverLoopback(
   requestUrl: URL,
   url: string,
   port: number,
+  headers: CurlHeaderSink,
 ): Promise<CurlResponse | null> {
   if (!kernel.routeLoopback) return null;
   const hasBody = options.method !== 'GET' && options.method !== 'HEAD' && options.data !== undefined;
@@ -426,6 +645,8 @@ async function routeCurlOverLoopback(
     signal: ctx.signal,
   }));
   if (!response) return null;
+  // Dump on arrival — before the optional arrayBuffer() drain below.
+  await writeHeaderDump(headers, response);
   return {
     status: response.status,
     statusText: response.statusText,
@@ -444,6 +665,7 @@ async function fetchVirtualCurlResponse(
   ctx: Parameters<Command>[0],
   options: CurlOptions,
   url: string,
+  headers: CurlHeaderSink,
 ): Promise<CurlResponse | { exitCode: number } | null> {
   let requestUrl: URL;
   try {
@@ -468,7 +690,7 @@ async function fetchVirtualCurlResponse(
     if (!requestCarriesSessionAiToken(new Headers(options.headers), ctx.env[NIMBUS_AI_TOKEN_ENV] || '')) {
       return null;
     }
-    return routeCurlOverLoopback(kernel, ctx, options, requestUrl, url, NIMBUS_AI_GATEWAY_PORT);
+    return routeCurlOverLoopback(kernel, ctx, options, requestUrl, url, NIMBUS_AI_GATEWAY_PORT, headers);
   }
 
   const handler = kernel.portRegistry.get(port);
@@ -498,6 +720,11 @@ async function fetchVirtualCurlResponse(
       }
     }
 
+    await headers.writeBlock({
+      status: vRes.statusCode,
+      statusText: statusText(vRes.statusCode),
+      headers: vRes.headers,
+    });
     return {
       status: vRes.statusCode,
       statusText: statusText(vRes.statusCode),
@@ -507,7 +734,7 @@ async function fetchVirtualCurlResponse(
     };
   }
 
-  const routed = await routeCurlOverLoopback(kernel, ctx, options, requestUrl, url, port);
+  const routed = await routeCurlOverLoopback(kernel, ctx, options, requestUrl, url, port, headers);
   if (routed) return routed;
 
   ctx.stderr.write(`curl: (7) Failed to connect to ${requestUrl.hostname} port ${port}\n`);
@@ -520,7 +747,7 @@ async function handleCurlResponse(ctx: Parameters<Command>[0], options: CurlOpti
   if (options.headOnly) {
     cancelStreamBody(response.body);
     if (!failed) {
-      await writeCurlOutput(ctx, options, curlHeaders(response));
+      await writeCurlOutput(ctx, options, curlHeaderBlock(response));
     }
     writeCurlFailure(ctx, options, response);
     writeCurlWriteOut(ctx, options, response);
@@ -543,18 +770,30 @@ async function handleCurlResponse(ctx: Parameters<Command>[0], options: CurlOpti
   return curlExitCode(options, response.status);
 }
 
-function cancelStreamBody(body: CurlBody): void {
+function cancelStreamBody(body: CurlBody | ReadableStream<unknown> | null): void {
   if (body instanceof ReadableStream) {
     body.cancel().catch(() => {});
   }
 }
 
+/**
+ * --fail diagnostic: curl's own wording pairs its exit code with the
+ * offending HTTP status.
+ */
 function writeCurlFailure(ctx: Parameters<Command>[0], options: CurlOptions, response: CurlResponse): void {
   if (options.fail && options.showError && response.status >= 400) {
-    ctx.stderr.write(`curl: (${response.status}) The requested URL returned error: ${response.status}\n`);
+    ctx.stderr.write(`curl: (22) The requested URL returned error: ${response.status}\n`);
   }
 }
 
+function curlExitCode(options: CurlOptions, status: number): number {
+  return options.fail && status >= 400 ? 22 : 0;
+}
+
+function isRedirectStatus(status: number): boolean {
+  return status >= 300 && status < 400;
+}
+
 async function writeCurlOutput(ctx: Parameters<Command>[0], options: CurlOptions, body: CurlBody): Promise<void> {
   if (!options.outputFile) {
     if (typeof body === 'string') {
@@ -641,23 +880,36 @@ function headersToRecord(headers: Headers): Record<string, string> {
   });
   return record;
 }
-
-function curlHeaders(response: CurlResponse): string {
-  const lines = [`HTTP/${response.status} ${response.statusText}`];
-  for (const [key, value] of Object.entries(response.headers)) {
-    lines.push(`${key}: ${value}`);
+function curlHeaderEntries(headers: Headers | Record<string, string>): [string, string][] {
+  if (!(headers instanceof Headers)) return Object.entries(headers);
+  // TS's Headers lib type predates getSetCookie; the runtime has it.
+  const getSetCookie = (headers as { getSetCookie?: () => string[] }).getSetCookie;
+  const pairs: [string, string][] = [];
+  for (const [name, value] of headers.entries()) {
+    if (typeof getSetCookie === 'function' && name.toLowerCase() === 'set-cookie') continue;
+    pairs.push([name, value]);
   }
-  return lines.join('\n') + '\n';
-}
-
-function curlExitCode(options: CurlOptions, status: number): number {
-  return options.fail && status >= 400 ? 22 : 0;
+  if (typeof getSetCookie === 'function') {
+    for (const value of getSetCookie.call(headers)) pairs.push(['set-cookie', value]);
+  }
+  return pairs;
 }
-
-function isRedirectStatus(status: number): boolean {
-  return status >= 300 && status < 400;
+/**
+ * The received response as an HTTP/1.1 header block: status line plus each
+ * header terminated CRLF, closed by the blank CRLF line that ends every
+ * header section. fetch exposes no negotiated wire version, so HTTP/1.1 is
+ * the explicit compatibility representation — a bare `HTTP/<code>` is not
+ * valid status-line syntax. Both -I's stdout display and -D's dump share
+ * this one serializer so the two surfaces cannot drift.
+ */
+function curlHeaderBlock(response: CurlHeaderSource): string {
+  const reason = response.statusText;
+  const statusLine = reason
+    ? `HTTP/1.1 ${response.status} ${reason}`
+    : `HTTP/1.1 ${response.status}`;
+  const lines = [statusLine, ...curlHeaderEntries(response.headers).map(([n, v]) => `${n}: ${v}`)];
+  return lines.map((line) => `${line}\r\n`).join('') + '\r\n';
 }
-
 function getHeader(headers: Record<string, string>, name: string): string | undefined {
   const wanted = name.toLowerCase();
   for (const [key, value] of Object.entries(headers)) {

package/src/substrate/lifo/commands/system/npm.ts

@@ -3,7 +3,7 @@ import type { CommandRegistry } from '../registry.js';
 import type { VFS } from '../../kernel/vfs/index.js';
 import type { Kernel } from '../../kernel/index.js';
 import { resolve, join } from '../../utils/path.js';
-import { decompressGzip, parseTar } from '../../utils/archive.js';
+import { writeTarballStream, type TarballWriteResult } from '../../../../_shared/tarball.js';
 import {
 	RegistryPackumentSchema,
 	RegistrySearchResponseSchema,
@@ -36,6 +36,24 @@ export type ShellExecuteFn = (
 	ctx: CommandContext,
 ) => Promise<number>;
 
+/** A host may supply a facet-based installer instead of in-process extraction. */
+export interface NpmInstallPort {
+	install(
+		projectDir: string,
+		options: { packages?: string[]; production?: boolean; pid?: number },
+	): Promise<{
+		installed: string[];
+		failed: string[];
+		totalFiles: number;
+		elapsed: number;
+		cachedHits?: number;
+	}>;
+}
+
+export interface NpmCommandDeps {
+	readonly installer?: NpmInstallPort;
+}
+
 // ─── Helpers ───
 
 function getRegistry(env: Record<string, string>): string {
@@ -188,48 +206,19 @@ async function fetchWithRange(
 	return data.versions[matching[0].version];
 }
 
-async function downloadAndExtract(
+async function fetchAndStreamPackage(
 	tarballUrl: string,
 	targetDir: string,
 	vfs: VFS,
 	signal: AbortSignal,
-): Promise<void> {
+): Promise<TarballWriteResult> {
 	const response = await fetch(tarballUrl, { signal });
 	if (!response.ok) {
 		throw new Error(`Failed to download tarball: ${response.status}`);
 	}
 
-	const arrayBuffer = await response.arrayBuffer();
-	const compressed = new Uint8Array(arrayBuffer);
-
-	// Decompress gzip → parse tar
-	const decompressed = await decompressGzip(compressed);
-	const entries = parseTar(decompressed);
-
-	// Ensure target directory
-	try { vfs.mkdir(targetDir, { recursive: true }); } catch { /* exists */ }
-
-	// Extract, stripping the first path component (npm tarballs use "package/")
-	for (const entry of entries) {
-		const slashIdx = entry.path.indexOf('/');
-		if (slashIdx === -1) continue;
-
-		const relativePath = entry.path.slice(slashIdx + 1);
-		if (!relativePath) continue;
-
-		const fullPath = join(targetDir, relativePath);
-
-		if (entry.type === 'directory') {
-			try { vfs.mkdir(fullPath, { recursive: true }); } catch { /* exists */ }
-		} else {
-			// Ensure parent exists
-			const parent = fullPath.slice(0, fullPath.lastIndexOf('/'));
-			if (parent) {
-				try { vfs.mkdir(parent, { recursive: true }); } catch { /* exists */ }
-			}
-			vfs.writeFile(fullPath, entry.data);
-		}
-	}
+	if (!response.body) throw new Error(`Registry served no body for ${tarballUrl}`);
+	return writeTarballStream(response.body, targetDir, vfs);
 }
 
 function readProjectPackageJson(vfs: VFS, cwd: string): PackageJson | null {
@@ -300,7 +289,12 @@ async function installSinglePackage(
 
 	const info = await fetchPackageInfo(npmRegistry, name, version, signal);
 
-	await downloadAndExtract(info.dist.tarball, targetDir, vfs, signal);
+	const written = await fetchAndStreamPackage(info.dist.tarball, targetDir, vfs, signal);
+	if (written.files === 0 || !vfs.exists(join(targetDir, 'package.json'))) {
+		throw new Error(
+			`${name}: extraction wrote ${written.files} files and left no package.json in ${targetDir}`,
+		);
+	}
 
 	let installed = 1;
 
@@ -378,7 +372,12 @@ async function npmInit(ctx: CommandContext): Promise<number> {
 	return 0;
 }
 
-async function npmInstall(ctx: CommandContext, registry: CommandRegistry, kernel?: Kernel): Promise<number> {
+async function npmInstall(
+	ctx: CommandContext,
+	registry: CommandRegistry,
+	kernel?: Kernel,
+	deps?: NpmCommandDeps,
+): Promise<number> {
 	const args = ctx.args.slice(1);
 
 	let isGlobal = false;
@@ -409,6 +408,22 @@ async function npmInstall(ctx: CommandContext, registry: CommandRegistry, kernel
 		try { ctx.vfs.mkdir(GLOBAL_BIN, { recursive: true }); } catch { /* exists */ }
 	}
 
+	if (deps?.installer) {
+		const projectDir = isGlobal ? GLOBAL_MODULES : ctx.cwd;
+		const result = await deps.installer.install(projectDir, {
+			packages: packages.length > 0 ? packages : undefined,
+			production: saveDev ? false : undefined,
+			pid: ctx.pid,
+		});
+		for (const failure of result.failed) ctx.stderr.write(`npm ERR! ${failure}\n`);
+		ctx.stdout.write(
+			`\nadded ${result.installed.length} package${result.installed.length === 1 ? '' : 's'}`
+			+ ` (${result.totalFiles} files) in ${(result.elapsed / 1000).toFixed(1)}s\n`,
+		);
+		registerLocalBins(ctx.vfs, projectDir, registry, kernel);
+		return result.failed.length > 0 ? 1 : 0;
+	}
+
 	if (packages.length === 0) {
 		// Install from package.json
 		if (isGlobal) {
@@ -853,7 +868,12 @@ async function npmSearch(ctx: CommandContext): Promise<number> {
 
 // ─── Factory ───
 
-export function createNpmCommand(registry: CommandRegistry, shellExecute?: ShellExecuteFn, kernel?: Kernel): Command {
+export function createNpmCommand(
+	registry: CommandRegistry,
+	shellExecute?: ShellExecuteFn,
+	kernel?: Kernel,
+	deps?: NpmCommandDeps,
+): Command {
 	return async (ctx) => {
 		const subcommand = ctx.args[0];
 
@@ -868,7 +888,7 @@ export function createNpmCommand(registry: CommandRegistry, shellExecute?: Shell
 			case 'install':
 			case 'i':
 			case 'add':
-				return npmInstall(ctx, registry, kernel);
+				return npmInstall(ctx, registry, kernel, deps);
 			case 'uninstall':
 			case 'remove':
 			case 'rm':