@run0/jiki 0.1.0

package/src/network-interceptor.ts

@@ -0,0 +1,143 @@
+/**
+ * Network request interception and mocking for jiki containers.
+ *
+ * Allows intercepting and mocking outgoing `fetch()` calls from executed
+ * code. Useful for testing, offline scenarios, and CORS avoidance.
+ *
+ * @example
+ * ```ts
+ * const container = boot();
+ * container.mockFetch('/api/users', { json: [{ name: 'Alice' }] });
+ * container.execute('fetch("/api/users").then(r => r.json()).then(console.log)');
+ * ```
+ */
+
+export interface MockResponse {
+  /** HTTP status code. Default: 200. */
+  status?: number;
+  /** Response headers. */
+  headers?: Record<string, string>;
+  /** Response body as string. */
+  body?: string;
+  /** Response body as JSON (auto-serialized). Overrides `body`. */
+  json?: unknown;
+}
+
+export type FetchHandler = (
+  url: string,
+  init?: RequestInit,
+) => MockResponse | null | undefined | Promise<MockResponse | null | undefined>;
+
+interface MockRule {
+  pattern: string | RegExp;
+  response?: MockResponse;
+  handler?: FetchHandler;
+}
+
+/**
+ * Intercepts fetch calls and returns mock responses when a URL matches
+ * a registered pattern.
+ */
+export class NetworkInterceptor {
+  private rules: MockRule[] = [];
+  private handlers: FetchHandler[] = [];
+
+  /**
+   * Register a static mock response for a URL pattern.
+   *
+   * @param pattern - String (exact match or prefix) or RegExp
+   * @param response - Mock response to return
+   */
+  mock(pattern: string | RegExp, response: MockResponse): void {
+    this.rules.push({ pattern, response });
+  }
+
+  /**
+   * Register a dynamic handler that can inspect the request and return
+   * a response. Return `null` to pass through to the next handler or
+   * the real network.
+   */
+  onFetch(handler: FetchHandler): void {
+    this.handlers.push(handler);
+  }
+
+  /**
+   * Remove all mock rules and handlers.
+   */
+  clear(): void {
+    this.rules.length = 0;
+    this.handlers.length = 0;
+  }
+
+  /** Number of registered rules. */
+  get ruleCount(): number {
+    return this.rules.length;
+  }
+
+  /** Number of registered handlers. */
+  get handlerCount(): number {
+    return this.handlers.length;
+  }
+
+  /**
+   * Try to match a URL against registered rules and handlers.
+   * Returns a Response-like object if matched, or `null` to pass through.
+   */
+  async intercept(
+    url: string,
+    init?: RequestInit,
+  ): Promise<MockResponse | null> {
+    // Check static rules first
+    for (const rule of this.rules) {
+      if (this.matches(url, rule.pattern)) {
+        return rule.response || { status: 200 };
+      }
+    }
+
+    // Check dynamic handlers
+    for (const handler of this.handlers) {
+      const result = await handler(url, init);
+      if (result) return result;
+    }
+
+    return null;
+  }
+
+  private matches(url: string, pattern: string | RegExp): boolean {
+    if (pattern instanceof RegExp) return pattern.test(url);
+    // String: exact match or prefix match
+    return url === pattern || url.startsWith(pattern);
+  }
+}
+
+/**
+ * Convert a MockResponse to a format suitable for the `fetch` polyfill.
+ */
+export function mockResponseToFetchResponse(mock: MockResponse): {
+  ok: boolean;
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+  text: () => Promise<string>;
+  json: () => Promise<unknown>;
+  arrayBuffer: () => Promise<ArrayBuffer>;
+} {
+  const status = mock.status ?? 200;
+  const body =
+    mock.json !== undefined ? JSON.stringify(mock.json) : (mock.body ?? "");
+  const headers = {
+    "Content-Type": mock.json !== undefined ? "application/json" : "text/plain",
+    ...mock.headers,
+  };
+
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    statusText: status === 200 ? "OK" : String(status),
+    headers,
+    text: async () => body,
+    json: async () => (mock.json !== undefined ? mock.json : JSON.parse(body)),
+    arrayBuffer: async () =>
+      new TextEncoder().encode(body).buffer as ArrayBuffer,
+  };
+}

package/src/npm/cache.ts

@@ -0,0 +1,172 @@
+/**
+ * Package cache for npm manifests and tarballs.
+ *
+ * Provides an in-memory cache with an optional persistent backing store
+ * (IndexedDB or any `PersistenceAdapter`-like backend). Manifests have a
+ * configurable TTL; tarballs are immutable by URL and cached indefinitely.
+ *
+ * @example
+ * ```ts
+ * const cache = new PackageCache();
+ * const registry = new Registry();
+ * // Wrap getManifest with cache
+ * const manifest = await cache.getManifest('react', () => registry.getManifest('react'));
+ * ```
+ */
+
+import type { PackageManifest } from "./registry";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PackageCacheOptions {
+  /** Manifest TTL in milliseconds. Default: 1 hour. */
+  manifestTtlMs?: number;
+  /** Maximum number of manifests to keep in memory. Default: 500. */
+  maxManifests?: number;
+  /** Maximum number of tarballs to keep in memory. Default: 200. */
+  maxTarballs?: number;
+}
+
+interface CachedManifest {
+  manifest: PackageManifest;
+  timestamp: number;
+}
+
+// ---------------------------------------------------------------------------
+// PackageCache
+// ---------------------------------------------------------------------------
+
+/**
+ * In-memory cache for npm package manifests and tarball data.
+ *
+ * - **Manifests** are keyed by package name with a configurable TTL (default
+ *   1 hour). After TTL expiry the manifest is re-fetched on next access.
+ * - **Tarballs** are keyed by URL. Since npm tarball URLs are immutable
+ *   (content-addressed), they are cached indefinitely.
+ */
+export class PackageCache {
+  private manifests = new Map<string, CachedManifest>();
+  private tarballs = new Map<string, Uint8Array>();
+  private manifestTtlMs: number;
+  private maxManifests: number;
+  private maxTarballs: number;
+
+  constructor(options: PackageCacheOptions = {}) {
+    this.manifestTtlMs = options.manifestTtlMs ?? 60 * 60 * 1000; // 1 hour
+    this.maxManifests = options.maxManifests ?? 500;
+    this.maxTarballs = options.maxTarballs ?? 200;
+  }
+
+  // -- Manifests ------------------------------------------------------------
+
+  /**
+   * Get a cached manifest, or fetch and cache it.
+   *
+   * @param name - Package name
+   * @param fetcher - Async function that fetches the manifest from the registry
+   * @returns The manifest (from cache or freshly fetched)
+   */
+  async getManifest(
+    name: string,
+    fetcher: () => Promise<PackageManifest>,
+  ): Promise<PackageManifest> {
+    const cached = this.manifests.get(name);
+    if (cached && Date.now() - cached.timestamp < this.manifestTtlMs) {
+      return cached.manifest;
+    }
+
+    const manifest = await fetcher();
+    this.setManifest(name, manifest);
+    return manifest;
+  }
+
+  /** Check if a manifest is cached and not expired. */
+  hasManifest(name: string): boolean {
+    const cached = this.manifests.get(name);
+    return !!cached && Date.now() - cached.timestamp < this.manifestTtlMs;
+  }
+
+  /** Store a manifest in the cache. */
+  setManifest(name: string, manifest: PackageManifest): void {
+    if (this.manifests.size >= this.maxManifests) {
+      // Evict oldest entry
+      const oldest = this.manifests.keys().next().value;
+      if (oldest !== undefined) this.manifests.delete(oldest);
+    }
+    this.manifests.set(name, { manifest, timestamp: Date.now() });
+  }
+
+  // -- Tarballs -------------------------------------------------------------
+
+  /**
+   * Get a cached tarball, or fetch and cache it.
+   *
+   * @param url - Tarball URL (immutable by npm convention)
+   * @param fetcher - Async function that downloads the tarball
+   * @returns The tarball data
+   */
+  async getTarball(
+    url: string,
+    fetcher: () => Promise<Uint8Array>,
+  ): Promise<Uint8Array> {
+    const cached = this.tarballs.get(url);
+    if (cached) return cached;
+
+    const data = await fetcher();
+    this.setTarball(url, data);
+    return data;
+  }
+
+  /** Check if a tarball is cached. */
+  hasTarball(url: string): boolean {
+    return this.tarballs.has(url);
+  }
+
+  /** Store a tarball in the cache. */
+  setTarball(url: string, data: Uint8Array): void {
+    if (this.tarballs.size >= this.maxTarballs) {
+      const oldest = this.tarballs.keys().next().value;
+      if (oldest !== undefined) this.tarballs.delete(oldest);
+    }
+    this.tarballs.set(url, data);
+  }
+
+  // -- Diagnostics ----------------------------------------------------------
+
+  /** Number of cached manifests. */
+  get manifestCount(): number {
+    return this.manifests.size;
+  }
+
+  /** Number of cached tarballs. */
+  get tarballCount(): number {
+    return this.tarballs.size;
+  }
+
+  /** Total bytes of cached tarballs. */
+  get tarballBytes(): number {
+    let total = 0;
+    for (const data of this.tarballs.values()) total += data.length;
+    return total;
+  }
+
+  // -- Cache control --------------------------------------------------------
+
+  /** Clear all cached manifests. */
+  clearManifests(): void {
+    this.manifests.clear();
+  }
+
+  /** Clear all cached tarballs. */
+  clearTarballs(): void {
+    this.tarballs.clear();
+  }
+
+  /** Clear all cached data. */
+  clear(): void {
+    this.manifests.clear();
+    this.tarballs.clear();
+  }
+}

package/src/npm/index.ts

@@ -0,0 +1,377 @@
+import { MemFS } from "../memfs";
+import { Registry, RegistryOptions } from "./registry";
+import {
+  resolveDependencies,
+  resolveFromPackageJson,
+  satisfies as semverSatisfies,
+  compareVersions,
+  ResolvedPackage,
+} from "./resolver";
+import { downloadAndExtract } from "./tarball";
+import * as path from "../polyfills/path";
+import { PackageCache, type PackageCacheOptions } from "./cache";
+import { readLockfile, lockfileToResolved } from "./lockfile-reader";
+
+export interface LayoutStrategy {
+  getPackageDir(cwd: string, pkgName: string, pkgVersion: string): string;
+  createTopLevelLink(
+    vfs: MemFS,
+    cwd: string,
+    pkgName: string,
+    pkgVersion: string,
+  ): void;
+  createDependencyLinks(
+    vfs: MemFS,
+    cwd: string,
+    pkg: ResolvedPackage,
+    allResolved: Map<string, ResolvedPackage>,
+  ): void;
+  createBinStub(
+    vfs: MemFS,
+    cwd: string,
+    cmdName: string,
+    targetPath: string,
+  ): void;
+}
+
+export class NpmLayout implements LayoutStrategy {
+  getPackageDir(cwd: string, pkgName: string, _pkgVersion: string): string {
+    return path.join(cwd, "node_modules", pkgName);
+  }
+
+  createTopLevelLink(): void {}
+  createDependencyLinks(): void {}
+
+  createBinStub(
+    vfs: MemFS,
+    cwd: string,
+    cmdName: string,
+    targetPath: string,
+  ): void {
+    const binDir = path.join(cwd, "node_modules", ".bin");
+    vfs.mkdirSync(binDir, { recursive: true });
+    const stubPath = path.join(binDir, cmdName);
+    vfs.writeFileSync(
+      stubPath,
+      `#!/usr/bin/env node\nrequire("${targetPath}");\n`,
+    );
+  }
+}
+
+function normalizeBin(
+  pkgName: string,
+  bin?: Record<string, string> | string,
+): Record<string, string> {
+  if (!bin) return {};
+  if (typeof bin === "string") {
+    const cmdName = pkgName.includes("/") ? pkgName.split("/").pop()! : pkgName;
+    return { [cmdName]: bin };
+  }
+  return bin;
+}
+
+export function parsePackageSpec(spec: string): {
+  name: string;
+  version: string;
+} {
+  if (spec.startsWith("@")) {
+    const atIdx = spec.indexOf("@", 1);
+    if (atIdx > 0)
+      return { name: spec.slice(0, atIdx), version: spec.slice(atIdx + 1) };
+    return { name: spec, version: "latest" };
+  }
+  const atIdx = spec.lastIndexOf("@");
+  if (atIdx > 0)
+    return { name: spec.slice(0, atIdx), version: spec.slice(atIdx + 1) };
+  return { name: spec, version: "latest" };
+}
+
+export interface InstallOptions {
+  registry?: string;
+  save?: boolean;
+  saveDev?: boolean;
+  includeDev?: boolean;
+  includeOptional?: boolean;
+  onProgress?: (message: string) => void;
+  transform?: boolean;
+  concurrency?: number;
+}
+
+export interface InstallResult {
+  installed: Map<string, ResolvedPackage>;
+  added: string[];
+}
+
+const DEFAULT_CONCURRENCY =
+  typeof navigator !== "undefined" && navigator.hardwareConcurrency
+    ? navigator.hardwareConcurrency
+    : 6;
+
+export class PackageManager {
+  private vfs: MemFS;
+  private registry: Registry;
+  private cwd: string;
+  readonly layout: LayoutStrategy;
+  /** Package cache for manifests and tarballs. */
+  readonly cache: PackageCache;
+
+  constructor(
+    vfs: MemFS,
+    options: {
+      cwd?: string;
+      layout?: LayoutStrategy;
+      cache?: PackageCache;
+    } & RegistryOptions = {},
+  ) {
+    this.vfs = vfs;
+    this.cache = options.cache || new PackageCache();
+    this.registry = new Registry({ ...options, cache: this.cache });
+    this.cwd = options.cwd || "/";
+    this.layout = options.layout || new NpmLayout();
+  }
+
+  /** Clear the package cache (manifests and tarballs). */
+  clearCache(): void {
+    this.cache.clear();
+  }
+
+  async install(
+    packageSpec: string | string[],
+    options: InstallOptions = {},
+  ): Promise<InstallResult> {
+    const specs = Array.isArray(packageSpec) ? packageSpec : [packageSpec];
+    const { onProgress } = options;
+    const allResolved = new Map<string, ResolvedPackage>();
+    const added: string[] = [];
+
+    const results = await Promise.all(
+      specs.map(async spec => {
+        const { name, version } = parsePackageSpec(spec);
+        onProgress?.(`Resolving ${name}@${version || "latest"}...`);
+        return resolveDependencies(name, version || "latest", {
+          registry: this.registry,
+          includeDev: options.includeDev,
+          includeOptional: options.includeOptional,
+        });
+      }),
+    );
+
+    for (const result of results) {
+      for (const [name, pkg] of result) {
+        if (!allResolved.has(name)) {
+          allResolved.set(name, pkg);
+        } else {
+          // Deduplicate: keep the higher version when two specs resolve the same package
+          const existing = allResolved.get(name)!;
+          if (
+            pkg.version !== existing.version &&
+            compareVersions(pkg.version, existing.version) > 0
+          ) {
+            allResolved.set(name, pkg);
+          }
+        }
+      }
+    }
+
+    const packages = Array.from(allResolved.values());
+    const concurrency = options.concurrency ?? DEFAULT_CONCURRENCY;
+    onProgress?.(`Downloading ${packages.length} packages...`);
+
+    for (let i = 0; i < packages.length; i += concurrency) {
+      const batch = packages.slice(i, i + concurrency);
+      await Promise.all(
+        batch.map(async pkg => {
+          const destDir = this.layout.getPackageDir(
+            this.cwd,
+            pkg.name,
+            pkg.version,
+          );
+          if (this.vfs.existsSync(destDir)) return;
+          onProgress?.(`Installing ${pkg.name}@${pkg.version}`);
+          await downloadAndExtract(
+            pkg.dist.tarball,
+            this.vfs,
+            destDir,
+            1,
+            this.cache,
+          );
+          added.push(`${pkg.name}@${pkg.version}`);
+
+          this.layout.createTopLevelLink(
+            this.vfs,
+            this.cwd,
+            pkg.name,
+            pkg.version,
+          );
+
+          const binEntries = normalizeBin(pkg.name, pkg.bin);
+          for (const [cmdName, binPath] of Object.entries(binEntries)) {
+            const targetPath = path.join(destDir, binPath);
+            this.layout.createBinStub(this.vfs, this.cwd, cmdName, targetPath);
+          }
+        }),
+      );
+    }
+
+    for (const pkg of packages) {
+      this.layout.createDependencyLinks(this.vfs, this.cwd, pkg, allResolved);
+    }
+
+    if (options.save || options.saveDev) {
+      this.updatePackageJson(specs, allResolved, options.saveDev);
+    }
+
+    buildLockfile(this.vfs, allResolved, this.cwd);
+
+    onProgress?.(`Installed ${added.length} packages.`);
+    return { installed: allResolved, added };
+  }
+
+  async installFromPackageJson(
+    options: InstallOptions = {},
+  ): Promise<InstallResult> {
+    const pkgJsonPath = path.join(this.cwd, "package.json");
+    if (!this.vfs.existsSync(pkgJsonPath))
+      throw new Error("No package.json found");
+
+    // Try lockfile-first installation (deterministic, no network for resolution)
+    const lockfile = readLockfile(this.vfs, this.cwd);
+    let resolved: Map<string, ResolvedPackage>;
+    if (lockfile && lockfile.packages.size > 0) {
+      options.onProgress?.("Using lockfile for deterministic install...");
+      resolved = lockfileToResolved(lockfile);
+    } else {
+      const pkgJson = JSON.parse(this.vfs.readFileSync(pkgJsonPath, "utf8"));
+      resolved = await resolveFromPackageJson(pkgJson, {
+        registry: this.registry,
+        includeDev: options.includeDev,
+        includeOptional: options.includeOptional,
+      });
+    }
+
+    const added: string[] = [];
+    const packages = Array.from(resolved.values());
+    const concurrency = options.concurrency ?? DEFAULT_CONCURRENCY;
+    options.onProgress?.(`Downloading ${packages.length} packages...`);
+
+    for (let i = 0; i < packages.length; i += concurrency) {
+      const batch = packages.slice(i, i + concurrency);
+      await Promise.all(
+        batch.map(async pkg => {
+          const destDir = this.layout.getPackageDir(
+            this.cwd,
+            pkg.name,
+            pkg.version,
+          );
+          if (this.vfs.existsSync(destDir)) return;
+          options.onProgress?.(`Installing ${pkg.name}@${pkg.version}`);
+          await downloadAndExtract(
+            pkg.dist.tarball,
+            this.vfs,
+            destDir,
+            1,
+            this.cache,
+          );
+          added.push(`${pkg.name}@${pkg.version}`);
+
+          this.layout.createTopLevelLink(
+            this.vfs,
+            this.cwd,
+            pkg.name,
+            pkg.version,
+          );
+
+          const binEntries = normalizeBin(pkg.name, pkg.bin);
+          for (const [cmdName, binPath] of Object.entries(binEntries)) {
+            const targetPath = path.join(destDir, binPath);
+            this.layout.createBinStub(this.vfs, this.cwd, cmdName, targetPath);
+          }
+        }),
+      );
+    }
+
+    for (const pkg of packages) {
+      this.layout.createDependencyLinks(this.vfs, this.cwd, pkg, resolved);
+    }
+
+    buildLockfile(this.vfs, resolved, this.cwd);
+
+    return { installed: resolved, added };
+  }
+
+  list(): string[] {
+    const nmDir = path.join(this.cwd, "node_modules");
+    if (!this.vfs.existsSync(nmDir)) return [];
+    const entries = this.vfs.readdirSync(nmDir);
+    const packages: string[] = [];
+    for (const entry of entries) {
+      if (entry.startsWith(".")) continue;
+      if (entry.startsWith("@")) {
+        const scopeDir = path.join(nmDir, entry);
+        const scoped = this.vfs.readdirSync(scopeDir);
+        for (const s of scoped) packages.push(`${entry}/${s}`);
+      } else {
+        packages.push(entry);
+      }
+    }
+    return packages;
+  }
+
+  private updatePackageJson(
+    specs: string[],
+    resolved: Map<string, ResolvedPackage>,
+    isDev?: boolean,
+  ): void {
+    const pkgJsonPath = path.join(this.cwd, "package.json");
+    let pkgJson: Record<string, unknown> = {};
+    if (this.vfs.existsSync(pkgJsonPath)) {
+      pkgJson = JSON.parse(this.vfs.readFileSync(pkgJsonPath, "utf8"));
+    }
+    const field = isDev ? "devDependencies" : "dependencies";
+    if (!pkgJson[field]) pkgJson[field] = {};
+    const deps = pkgJson[field] as Record<string, string>;
+    for (const spec of specs) {
+      const { name } = parsePackageSpec(spec);
+      const pkg = resolved.get(name);
+      if (pkg) deps[name] = `^${pkg.version}`;
+    }
+    this.vfs.writeFileSync(pkgJsonPath, JSON.stringify(pkgJson, null, 2));
+  }
+}
+
+export function buildLockfile(
+  vfs: MemFS,
+  resolved: Map<string, ResolvedPackage>,
+  cwd: string = "/",
+): void {
+  const lockfile: Record<string, unknown> = {
+    name: "jiki-project",
+    lockfileVersion: 3,
+    packages: {} as Record<
+      string,
+      {
+        version: string;
+        resolved: string;
+        dependencies?: Record<string, string>;
+      }
+    >,
+  };
+  const packages = lockfile.packages as Record<string, any>;
+  for (const [name, pkg] of resolved) {
+    packages[`node_modules/${name}`] = {
+      version: pkg.version,
+      resolved: pkg.dist.tarball,
+      dependencies:
+        Object.keys(pkg.dependencies).length > 0 ? pkg.dependencies : undefined,
+    };
+  }
+  const lockfilePath = path.join(cwd, "package-lock.json");
+  vfs.writeFileSync(lockfilePath, JSON.stringify(lockfile, null, 2));
+}
+
+export { Registry } from "./registry";
+export type { RegistryOptions } from "./registry";
+export type { ResolvedPackage } from "./resolver";
+export { satisfies, compareVersions } from "./resolver";
+export { readLockfile, lockfileToResolved } from "./lockfile-reader";
+export type { LockfileData, LockfileEntry } from "./lockfile-reader";