@scelar/nodepod 1.0.0

package/src/packages/browser-bundler.ts

@@ -0,0 +1,284 @@
+// Browser Bundler — bundles node_modules packages into single ESM files for the browser.
+// Uses esbuild-wasm. React-family packages are kept external (shared via import map).
+
+import {
+  build,
+  setVolume as setVFS,
+  type BundleOutput as BuildResult,
+} from "../polyfills/esbuild";
+import type { MemoryVolume } from "../memory-volume";
+
+// ---------------------------------------------------------------------------
+// Module-level state
+// ---------------------------------------------------------------------------
+
+const bundledModules = new Map<string, string>();
+let activeVolume: MemoryVolume | null = null;
+let externalPackages: string[] = [];
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export function invalidateBundleCache(): void {
+  bundledModules.clear();
+}
+
+// Must be called before bundleForBrowser
+export function attachVolume(vol: MemoryVolume): void {
+  setVFS(vol);
+  activeVolume = vol;
+}
+
+export function setExternalPackages(packages: string[]): void {
+  externalPackages = [...packages];
+}
+
+// Bundle a bare specifier (e.g. "zod", "lodash/merge") into a self-contained ESM string
+export async function bundleForBrowser(specifier: string): Promise<string> {
+  const hit = bundledModules.get(specifier);
+  if (hit) return hit;
+
+  const entryFile = locateEntryPoint(specifier);
+
+  let knownExports: string[] = [];
+  if (entryFile && activeVolume) {
+    try {
+      const src = activeVolume.readFileSync(entryFile, "utf8");
+      knownExports = detectCjsExports(src);
+    } catch {
+      // non-critical
+    }
+  }
+
+  let outcome: BuildResult;
+
+  if (entryFile) {
+    outcome = await build({
+      entryPoints: [entryFile],
+      bundle: true,
+      format: "esm",
+      target: "esnext",
+      external: externalPackages,
+      write: false,
+    });
+  } else {
+    // can't determine entry point — let esbuild resolve it via a re-export stub
+    const stub = `export * from '${specifier}';\n`;
+    outcome = await build({
+      stdin: {
+        contents: stub,
+        resolveDir: "/node_modules",
+        loader: "js",
+      },
+      bundle: true,
+      format: "esm",
+      target: "esnext",
+      external: externalPackages,
+      write: false,
+    });
+  }
+
+  if (!outcome.outputFiles || outcome.outputFiles.length === 0) {
+    throw new Error(`Bundling produced no output for "${specifier}"`);
+  }
+
+  const outputRecord = outcome.outputFiles[0];
+  let esmCode = outputRecord.text;
+  if (!esmCode && outputRecord.contents?.length > 0) {
+    esmCode = new TextDecoder().decode(outputRecord.contents);
+  }
+
+  if (!esmCode) {
+    throw new Error(
+      `Bundling produced empty output for "${specifier}" (entry: ${entryFile || "stdin"})`,
+    );
+  }
+
+  esmCode = rewriteExternalRequireCalls(esmCode);
+  if (knownExports.length > 0) {
+    esmCode = injectNamedExports(esmCode, knownExports);
+  }
+
+  bundledModules.set(specifier, esmCode);
+  return esmCode;
+}
+
+// ---------------------------------------------------------------------------
+// Entry-point resolution
+// ---------------------------------------------------------------------------
+
+// CJS first to avoid .mjs confusion
+const CONDITION_ORDER = ["require", "import", "module", "default"] as const;
+
+// Walk nested export conditions until we hit an actual file path string
+function drillCondition(node: unknown): string | undefined {
+  if (typeof node === "string") return node;
+  if (typeof node === "object" && node !== null) {
+    const obj = node as Record<string, unknown>;
+    for (const key of CONDITION_ORDER) {
+      if (key in obj) {
+        const found = drillCondition(obj[key]);
+        if (found) return found;
+      }
+    }
+  }
+  return undefined;
+}
+
+function fileExists(filePath: string): boolean {
+  if (!activeVolume) return false;
+  if (!activeVolume.existsSync(filePath)) return false;
+  try {
+    return !activeVolume.statSync(filePath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+// Resolve bare specifier to absolute path. Handles scoped packages, exports map, and fallbacks.
+function locateEntryPoint(specifier: string): string | null {
+  if (!activeVolume) return null;
+
+  const segments = specifier.split("/");
+  const isScoped = segments[0].startsWith("@");
+  const pkgName = isScoped ? segments.slice(0, 2).join("/") : segments[0];
+  const subPath = isScoped
+    ? segments.slice(2).join("/")
+    : segments.slice(1).join("/");
+
+  const pkgRoot = `/node_modules/${pkgName}`;
+  const manifestFile = `${pkgRoot}/package.json`;
+  if (!activeVolume.existsSync(manifestFile)) return null;
+
+  try {
+    const manifest = JSON.parse(
+      activeVolume.readFileSync(manifestFile, "utf8"),
+    );
+
+    if (manifest.exports && typeof manifest.exports === "object") {
+      const conditionKey = subPath ? `./${subPath}` : ".";
+      const mapEntry = (manifest.exports as Record<string, unknown>)[
+        conditionKey
+      ];
+      if (mapEntry) {
+        const resolved = drillCondition(mapEntry);
+        if (resolved) {
+          const abs = `${pkgRoot}/${resolved.replace(/^\.\//, "")}`;
+          if (fileExists(abs)) return abs;
+        }
+      }
+    }
+
+    // fallback: main/module fields (root export only)
+    if (!subPath) {
+      const fallbackEntry = manifest.main || manifest.module;
+      if (fallbackEntry) {
+        const abs = `${pkgRoot}/${fallbackEntry.replace(/^\.\//, "")}`;
+        if (fileExists(abs)) return abs;
+      }
+      const defaultIndex = `${pkgRoot}/index.js`;
+      if (fileExists(defaultIndex)) return defaultIndex;
+    } else {
+      const basePath = `${pkgRoot}/${subPath}`;
+      for (const ext of ["", ".js", ".cjs", ".mjs", ".json"]) {
+        if (fileExists(basePath + ext)) return basePath + ext;
+      }
+    }
+  } catch {
+    // non-fatal
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// CJS export detection
+// ---------------------------------------------------------------------------
+
+// Detect named exports from CJS — looks for esbuild's __export() helper or exports.X = patterns
+function detectCjsExports(source: string): string[] {
+  const helperMatch = source.match(/__export\(\w+,\s*\{([^}]+)\}/);
+  if (helperMatch) {
+    return [...helperMatch[1].matchAll(/(\w+)\s*:/g)]
+      .map((m) => m[1])
+      .filter((id) => id !== "default" && id !== "__esModule");
+  }
+
+  const propMatches = [...source.matchAll(/exports\.(\w+)\s*=/g)].map(
+    (m) => m[1],
+  );
+  return [...new Set(propMatches)].filter(
+    (id) => id !== "default" && id !== "__esModule",
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Post-processing transforms
+// ---------------------------------------------------------------------------
+
+// esbuild emits __require("ext") for CJS externals in ESM — rewrite to proper import declarations
+function rewriteExternalRequireCalls(code: string): string {
+  const specifiers = new Set<string>();
+  for (const m of code.matchAll(/__require\(["']([^"']+)["']\)/g)) {
+    specifiers.add(m[1]);
+  }
+  if (specifiers.size === 0) return code;
+
+  const uniqueSpecs = [...specifiers];
+  const importBlock = uniqueSpecs
+    .map((spec, idx) => `import * as __imported${idx} from "${spec}";`)
+    .join("\n");
+
+  let patched = code;
+  for (let idx = 0; idx < uniqueSpecs.length; idx++) {
+    const spec = uniqueSpecs[idx];
+    patched = patched.split(`__require("${spec}")`).join(`__imported${idx}`);
+    patched = patched.split(`__require('${spec}')`).join(`__imported${idx}`);
+  }
+
+  return importBlock + "\n" + patched;
+}
+
+// esbuild wraps CJS as `export default require_xxx()` with no named exports.
+// When we know the names from static analysis, inject explicit re-exports.
+function injectNamedExports(code: string, names: string[]): string {
+  if (names.length === 0) return code;
+
+  const wrapperPattern = /export\s+default\s+(require_\w+)\(\)\s*;?/;
+  const m = code.match(wrapperPattern);
+  if (!m) return code;
+
+  const requireCall = m[1];
+
+  const replacement =
+    `var __mod = ${requireCall}();\nexport default __mod;\n` +
+    names.map((n) => `export var ${n} = __mod.${n};`).join("\n") +
+    "\n";
+
+  return code.replace(m[0], replacement);
+}
+
+// ---------------------------------------------------------------------------
+// Class facade
+// ---------------------------------------------------------------------------
+
+export class BrowserBundler {
+  private vol: MemoryVolume;
+
+  constructor(vol: MemoryVolume, options?: { external?: string[] }) {
+    this.vol = vol;
+    attachVolume(vol);
+    if (options?.external) setExternalPackages(options.external);
+  }
+
+  bundle(specifier: string): Promise<string> {
+    return bundleForBrowser(specifier);
+  }
+
+  clearCache(): void {
+    invalidateBundleCache();
+  }
+}
+
+export default BrowserBundler;

package/src/packages/installer.ts

@@ -0,0 +1,396 @@
+// Dependency Installer
+// Handles the full install lifecycle: resolve, download, extract, transform, bin stubs, lock file.
+
+import { MemoryVolume } from "../memory-volume";
+import { RegistryClient, RegistryConfig } from "./registry-client";
+import {
+  resolveDependencyTree,
+  resolveFromManifest,
+  ResolvedDependency,
+  ResolutionConfig,
+} from "./version-resolver";
+import { downloadAndExtract } from "./archive-extractor";
+import { convertPackage, prepareTransformer } from "../module-transformer";
+import type { PackageManifest } from "../types/manifest";
+import * as path from "../polyfills/path";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface InstallFlags {
+  registry?: string;
+  persist?: boolean;
+  persistDev?: boolean;
+  withDevDeps?: boolean;
+  withOptionalDeps?: boolean;
+  onProgress?: (message: string) => void;
+  // default: true
+  transformModules?: boolean;
+}
+
+export interface InstallOutcome {
+  resolved: Map<string, ResolvedDependency>;
+  newPackages: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+// Normalize bin field — handles both shorthand string and object forms
+function normalizeBinField(
+  packageName: string,
+  bin?: string | Record<string, string>,
+): Record<string, string> {
+  if (!bin) return {};
+  if (typeof bin === "string") {
+    const command = packageName.includes("/")
+      ? packageName.split("/").pop()!
+      : packageName;
+    return { [command]: bin };
+  }
+  return bin;
+}
+
+// Split "express@4.18.2" or "@types/node@20" into name + version
+function splitSpecifier(spec: string): { name: string; version?: string } {
+  if (spec.startsWith("@")) {
+    const slashIdx = spec.indexOf("/");
+    if (slashIdx === -1)
+      throw new Error(`Malformed package specifier: ${spec}`);
+
+    const tail = spec.slice(slashIdx + 1);
+    const atIdx = tail.indexOf("@");
+    if (atIdx === -1) return { name: spec };
+    return {
+      name: spec.slice(0, slashIdx + 1 + atIdx),
+      version: tail.slice(atIdx + 1),
+    };
+  }
+
+  const atIdx = spec.indexOf("@");
+  if (atIdx === -1) return { name: spec };
+  return {
+    name: spec.slice(0, atIdx),
+    version: spec.slice(atIdx + 1),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Main class
+// ---------------------------------------------------------------------------
+
+let transformerReady = false;
+
+export class DependencyInstaller {
+  private vol: MemoryVolume;
+  private registryClient: RegistryClient;
+  private workingDir: string;
+
+  constructor(vol: MemoryVolume, opts: { cwd?: string } & RegistryConfig = {}) {
+    this.vol = vol;
+    this.registryClient = new RegistryClient(opts);
+    this.workingDir = opts.cwd || "/";
+  }
+
+  // -----------------------------------------------------------------------
+  // Public API
+  // -----------------------------------------------------------------------
+
+  async install(
+    packageName: string,
+    version?: string,
+    flags: InstallFlags = {},
+  ): Promise<InstallOutcome> {
+    const { onProgress } = flags;
+
+    const spec = splitSpecifier(packageName);
+    const targetName = spec.name;
+    const targetRange = version || spec.version || "latest";
+
+    onProgress?.(`Resolving ${targetName}@${targetRange}...`);
+
+    const resolutionOpts: ResolutionConfig = {
+      registry: this.registryClient,
+      devDependencies: flags.withDevDeps,
+      optionalDependencies: flags.withOptionalDeps,
+      onProgress,
+    };
+
+    const tree = await resolveDependencyTree(
+      targetName,
+      targetRange,
+      resolutionOpts,
+    );
+
+    const newPkgs = await this.materializePackages(tree, flags);
+
+    if (flags.persist || flags.persistDev) {
+      const entry = tree.get(targetName);
+      if (entry) {
+        await this.patchManifest(
+          targetName,
+          `^${entry.version}`,
+          !!flags.persistDev,
+        );
+      }
+    }
+
+    onProgress?.(`Installed ${tree.size} package(s)`);
+
+    return { resolved: tree, newPackages: newPkgs };
+  }
+
+  async installFromManifest(
+    manifestPath?: string,
+    flags: InstallFlags = {},
+  ): Promise<InstallOutcome> {
+    const { onProgress } = flags;
+
+    const jsonPath = manifestPath || path.join(this.workingDir, "package.json");
+
+    if (!this.vol.existsSync(jsonPath)) {
+      throw new Error(`Manifest not found at ${jsonPath}`);
+    }
+
+    const raw = this.vol.readFileSync(jsonPath, "utf8");
+    const manifest: PackageManifest = JSON.parse(raw);
+
+    onProgress?.("Resolving dependency tree...");
+
+    const resolutionOpts: ResolutionConfig = {
+      registry: this.registryClient,
+      devDependencies: flags.withDevDeps,
+      optionalDependencies: flags.withOptionalDeps,
+      onProgress,
+    };
+
+    const tree = await resolveFromManifest(manifest, resolutionOpts);
+
+    const newPkgs = await this.materializePackages(tree, flags);
+
+    onProgress?.(`Installed ${tree.size} package(s)`);
+
+    return { resolved: tree, newPackages: newPkgs };
+  }
+
+  listInstalled(): Record<string, string> {
+    const nmDir = path.join(this.workingDir, "node_modules");
+    if (!this.vol.existsSync(nmDir)) return {};
+
+    const result: Record<string, string> = {};
+    const topLevel = this.vol.readdirSync(nmDir) as string[];
+
+    for (const entry of topLevel) {
+      if (entry.startsWith(".")) continue;
+
+      if (entry.startsWith("@")) {
+        const scopeDir = path.join(nmDir, entry);
+        const scopedEntries = this.vol.readdirSync(scopeDir) as string[];
+        for (const child of scopedEntries) {
+          const manifest = path.join(scopeDir, child, "package.json");
+          if (this.vol.existsSync(manifest)) {
+            const data = JSON.parse(this.vol.readFileSync(manifest, "utf8"));
+            result[`${entry}/${child}`] = data.version;
+          }
+        }
+      } else {
+        const manifest = path.join(nmDir, entry, "package.json");
+        if (this.vol.existsSync(manifest)) {
+          const data = JSON.parse(this.vol.readFileSync(manifest, "utf8"));
+          result[entry] = data.version;
+        }
+      }
+    }
+
+    return result;
+  }
+
+  // -----------------------------------------------------------------------
+  // Private helpers
+  // -----------------------------------------------------------------------
+
+  // Download, extract, transform, and wire up packages not already in node_modules
+  private async materializePackages(
+    tree: Map<string, ResolvedDependency>,
+    flags: InstallFlags,
+  ): Promise<string[]> {
+    const { onProgress } = flags;
+    const additions: string[] = [];
+
+    const nmRoot = path.join(this.workingDir, "node_modules");
+    this.vol.mkdirSync(nmRoot, { recursive: true });
+
+    const pending: Array<{
+      depName: string;
+      dep: ResolvedDependency;
+      targetDir: string;
+    }> = [];
+
+    for (const [depName, dep] of tree) {
+      const targetDir = path.join(nmRoot, depName);
+      const existingManifest = path.join(targetDir, "package.json");
+
+      if (this.vol.existsSync(existingManifest)) {
+        try {
+          const current = JSON.parse(
+            this.vol.readFileSync(existingManifest, "utf8"),
+          );
+          if (current.version === dep.version) {
+            onProgress?.(`Skipping ${depName}@${dep.version} (up to date)`);
+            continue;
+          }
+        } catch {
+          // corrupt manifest, reinstall
+        }
+      }
+
+      pending.push({ depName, dep, targetDir });
+    }
+
+    // Only need main-thread transformer as fallback when workers aren't available
+    const shouldTransform = flags.transformModules !== false;
+    if (shouldTransform && !transformerReady) {
+      if (typeof Worker === "undefined") {
+        onProgress?.("Preparing module transformer...");
+        await prepareTransformer();
+      }
+      transformerReady = true;
+    }
+
+    // Safe to batch aggressively since extract + transform are offloaded to workers
+    const WORKER_COUNT = 12;
+    onProgress?.(`Downloading ${pending.length} package(s)...`);
+
+    for (let offset = 0; offset < pending.length; offset += WORKER_COUNT) {
+      const batch = pending.slice(offset, offset + WORKER_COUNT);
+
+      await Promise.all(
+        batch.map(async ({ depName, dep, targetDir }) => {
+          onProgress?.(`  Fetching ${depName}@${dep.version}...`);
+
+          await downloadAndExtract(dep.tarballUrl, this.vol, targetDir, {
+            stripComponents: 1,
+          });
+
+          if (shouldTransform) {
+            try {
+              const transformed = await convertPackage(
+                this.vol,
+                targetDir,
+                onProgress,
+              );
+              if (transformed > 0) {
+                onProgress?.(
+                  `  Transformed ${transformed} file(s) in ${depName}`,
+                );
+              }
+            } catch (err) {
+              onProgress?.(
+                `  Warning: transformation failed for ${depName}: ${err}`,
+              );
+            }
+          }
+
+          this.createBinStubs(nmRoot, depName, targetDir);
+
+          additions.push(depName);
+        }),
+      );
+    }
+
+    this.writeLockFile(tree);
+
+    return additions;
+  }
+
+  private createBinStubs(
+    nmRoot: string,
+    depName: string,
+    pkgDir: string,
+  ): void {
+    try {
+      const manifestPath = path.join(pkgDir, "package.json");
+      if (!this.vol.existsSync(manifestPath)) return;
+
+      const data = JSON.parse(this.vol.readFileSync(manifestPath, "utf8"));
+      const bins = normalizeBinField(depName, data.bin);
+      const binDir = path.join(nmRoot, ".bin");
+
+      for (const [cmd, relPath] of Object.entries(bins)) {
+        this.vol.mkdirSync(binDir, { recursive: true });
+        const target = path.join(pkgDir, relPath);
+        this.vol.writeFileSync(
+          path.join(binDir, cmd),
+          `node "${target}" "$@"\n`,
+        );
+      }
+    } catch {
+      // best-effort
+    }
+  }
+
+  private writeLockFile(tree: Map<string, ResolvedDependency>): void {
+    const entries: Record<string, { version: string; resolved: string }> = {};
+
+    for (const [depName, dep] of tree) {
+      entries[depName] = {
+        version: dep.version,
+        resolved: dep.tarballUrl,
+      };
+    }
+
+    const lockPath = path.join(
+      this.workingDir,
+      "node_modules",
+      ".package-lock.json",
+    );
+    this.vol.writeFileSync(lockPath, JSON.stringify(entries, null, 2));
+  }
+
+  private async patchManifest(
+    depName: string,
+    versionSpec: string,
+    asDev: boolean,
+  ): Promise<void> {
+    const jsonPath = path.join(this.workingDir, "package.json");
+
+    let manifest: Record<string, unknown> = {};
+    if (this.vol.existsSync(jsonPath)) {
+      manifest = JSON.parse(this.vol.readFileSync(jsonPath, "utf8"));
+    }
+
+    const section = asDev ? "devDependencies" : "dependencies";
+    if (!manifest[section]) {
+      manifest[section] = {};
+    }
+    (manifest[section] as Record<string, string>)[depName] = versionSpec;
+
+    this.vol.writeFileSync(jsonPath, JSON.stringify(manifest, null, 2));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Convenience function
+// ---------------------------------------------------------------------------
+
+// One-shot install: `install("express@4.18.2", vol)`
+export async function install(
+  specifier: string,
+  vol: MemoryVolume,
+  flags?: InstallFlags,
+): Promise<InstallOutcome> {
+  const installer = new DependencyInstaller(vol);
+  return installer.install(specifier, undefined, flags);
+}
+
+export { RegistryClient } from "./registry-client";
+export type {
+  RegistryConfig,
+  VersionDetail,
+  PackageMetadata,
+} from "./registry-client";
+export type { ResolvedDependency, ResolutionConfig } from "./version-resolver";
+export type { ExtractionOptions } from "./archive-extractor";
+export { splitSpecifier };