@statewalker/webrun-modules 0.1.0

package/src/server/new-module-server.ts

@@ -0,0 +1,416 @@
+import type { FilesApi } from "@statewalker/webrun-files";
+import { readText, writeText } from "@statewalker/webrun-files";
+import semver from "semver";
+import { resolveNodeBuiltin } from "../resolution/node-builtins.js";
+import { resolveEntry } from "../resolution/resolve-entry.js";
+import { npmRegistrySource } from "../sources/npm-registry-source.js";
+import { detectFormat, newDefaultTransform } from "../transform/index.js";
+import { scanSpecifiers } from "../transform/scan.js";
+import type {
+  Lockfile,
+  ModuleRef,
+  ModuleServer,
+  ModuleServerOptions,
+  PackageManifest,
+  ResolvedModule,
+} from "../types.js";
+import { ModuleResolveError } from "../types.js";
+import { parseSpecifier, relativeUrl } from "./specifiers.js";
+
+const RAW_EXT = ["", ".js", ".mjs", ".cjs", ".json", "/index.js", "/index.mjs"];
+
+/** JS/TS module files — the only ones the transform touches. */
+const MODULE_EXT = /\.(?:m|c)?[jt]sx?$/;
+const isModuleFile = (path: string) => MODULE_EXT.test(path);
+
+const CONTENT_TYPES: Record<string, string> = {
+  json: "application/json",
+  css: "text/css",
+  md: "text/markdown",
+  html: "text/html",
+  svg: "image/svg+xml",
+  wasm: "application/wasm",
+  map: "application/json",
+  txt: "text/plain",
+};
+
+/** Guess a content-type from a file path (non-module resources). */
+function contentType(path: string): string {
+  const ext = path.split(".").pop()?.toLowerCase() ?? "";
+  return CONTENT_TYPES[ext] ?? "application/octet-stream";
+}
+
+/** Create a module/dependency server over an injected `FilesApi` cache. */
+export function newModuleServer(options: ModuleServerOptions): ModuleServer {
+  const cache = options.cache;
+  const project = options.project;
+  const sources = options.sources ?? [npmRegistrySource()];
+  const transformer = options.transform ?? newDefaultTransform();
+  const target = options.target ?? "browser";
+  const basePath = normalizeBase(options.basePath ?? "/");
+  // Optional prefix (relative to `basePath`) for external package URLs, so npm
+  // deps can be isolated under e.g. `/deps/` while authored project files stay at
+  // `~/`. Default "" ⇒ packages served alongside project files (unchanged).
+  const depsPrefix = normalizeDeps(options.depsPath ?? "");
+  const lock: Lockfile = { ...(options.lock ?? {}) };
+  const tRoot = `/t/${target}`;
+
+  let ready: Promise<void> | undefined;
+  const init = () => {
+    ready ??= (async () => {
+      if (await cache.exists("/lock.json")) {
+        Object.assign(lock, JSON.parse(await readText(cache, "/lock.json")), options.lock ?? {});
+      }
+    })();
+    return ready;
+  };
+
+  // Project ids (`~/…`) are served verbatim; package ids get the `depsPrefix`.
+  // `urlPath` is the site-relative form (after `basePath`) and the space that
+  // import URLs are made relative in, so cross-prefix imports resolve correctly.
+  const urlPath = (id: string) => (id.startsWith("~/") ? id : depsPrefix + id);
+  const urlFor = (id: string) => basePath + urlPath(id);
+  const idFromPath = (pathname: string): string => {
+    let p = pathname.startsWith(basePath)
+      ? pathname.slice(basePath.length)
+      : pathname.replace(/^\//, "");
+    if (depsPrefix && p.startsWith(depsPrefix)) p = p.slice(depsPrefix.length);
+    return p;
+  };
+
+  function matchSource(ref: ModuleRef) {
+    const s = sources.find((x) => x.matches(ref));
+    if (!s) throw new ModuleResolveError(ref, "no source matches");
+    return s;
+  }
+
+  function reusable(locked: string, spec: string | undefined): boolean {
+    if (!spec) return true;
+    if (semver.valid(spec)) return locked === spec;
+    if (semver.validRange(spec)) return semver.satisfies(locked, spec);
+    return true; // dist-tag → reuse the locked version
+  }
+
+  async function cachedManifest(pkgKey: string): Promise<PackageManifest> {
+    return JSON.parse(await readText(cache, `/raw/${pkgKey}/package.json`));
+  }
+
+  /** Persist a loaded package's files under `/raw/{name}@{version}/…` (idempotent).
+   *  The manifest is written as `package.json` (the authority — a Source's files
+   *  are not required to include one). */
+  async function cacheRaw(
+    name: string,
+    version: string,
+    files: FilesApi,
+    manifest: PackageManifest,
+  ): Promise<void> {
+    const key = `${name}@${version}`;
+    if (await cache.exists(`/raw/${key}/package.json`)) return;
+    for await (const info of files.list("/", { recursive: true })) {
+      if (info.kind === "file") {
+        await cache.write(`/raw/${key}${info.path}`, [await collect(files.read(info.path))]);
+      }
+    }
+    if (!(await cache.exists(`/raw/${key}/package.json`))) {
+      await writeText(cache, `/raw/${key}/package.json`, JSON.stringify(manifest));
+    }
+  }
+
+  /** Lazily load a package's raw files by its `name@version` cache key (idempotent). */
+  async function ensureRawByKey(pkgKey: string): Promise<void> {
+    if (await cache.exists(`/raw/${pkgKey}/package.json`)) return;
+    const at = pkgKey.lastIndexOf("@");
+    const ref = { pkg: pkgKey.slice(0, at), version: pkgKey.slice(at + 1) };
+    const loaded = await matchSource(ref).load(ref);
+    await cacheRaw(loaded.name, loaded.version, loaded.files, loaded.manifest);
+  }
+
+  /** Ensure a package's raw files + manifest are cached; return its pinned id. */
+  async function ensurePackage(ref: { pkg: string; version?: string; subpath?: string }) {
+    const name = ref.pkg;
+    const locked = lock[name];
+    let version: string;
+    let manifest: PackageManifest;
+    if (locked && reusable(locked, ref.version)) {
+      // Honor the lock even on a cold cache — load the *locked* version, not latest.
+      version = locked;
+      await ensureRawByKey(`${name}@${version}`);
+      manifest = await cachedManifest(`${name}@${version}`);
+    } else {
+      const loaded = await matchSource(ref).load({ pkg: name, version: ref.version });
+      version = loaded.version;
+      await cacheRaw(name, version, loaded.files, loaded.manifest);
+      manifest = loaded.manifest;
+      if (!locked) lock[name] = version;
+    }
+    const entry = resolveEntry(manifest, ref.subpath, target);
+    const file = await resolveRawFile(`${name}@${version}`, entry); // resolve real extension/index
+    return { name, version, file, id: `${name}@${version}/${file}`, manifest };
+  }
+
+  /** Resolve an import specifier (from `fromId`) to what to emit + its cache id. */
+  async function resolveSpec(spec: string, fromId: string): Promise<{ url: string; id?: string }> {
+    if (/^(https?:|data:)/.test(spec)) return { url: spec }; // absolute — pass through
+    const builtin = resolveNodeBuiltin(spec, target); // node: builtins → polyfill/external
+    if (builtin) {
+      if ("external" in builtin) return { url: builtin.external };
+      const t = await ensurePackage(builtin.ref);
+      return { url: relativeUrl(urlPath(fromId), urlPath(t.id)), id: t.id };
+    }
+    if (spec.startsWith(".")) {
+      const id = await resolveRelativeId(fromId, spec);
+      // Emit the *extension-resolved* relative URL (`./x` → `./x.js`), not the raw
+      // specifier: the browser fetches this URL verbatim, and only a recognized
+      // module extension makes the server transform it + serve `text/javascript`.
+      return { url: jsonModuleUrl(relativeUrl(urlPath(fromId), urlPath(id)), id), id };
+    }
+    const { pkg, subpath } = parseSpecifier(spec);
+    // Resolve the version from the *importing package's* context (Node semantics):
+    // a package requiring its own name → itself; a dependency → the importer's
+    // declared range. Falls back to the global lock/latest for project files or
+    // undeclared (transitive) deps.
+    const version = await importerVersion(pkg, fromId);
+    const t = await ensurePackage({ pkg, version, subpath });
+    return { url: jsonModuleUrl(relativeUrl(urlPath(fromId), urlPath(t.id)), t.id), id: t.id };
+  }
+
+  /** The version constraint a bare specifier should resolve to, from the importer's
+   *  package: self-reference → the importer's own version; a dependency → the
+   *  importer's `package.json` range; otherwise undefined (global lock/latest). */
+  async function importerVersion(pkg: string, fromId: string): Promise<string | undefined> {
+    const m = fromId.match(/^((?:@[^/]+\/)?[^/]+)@([^/]+)\//);
+    if (!m) return undefined; // project file — no package context
+    const [, impName, impVersion] = m;
+    if (pkg === impName) return impVersion; // self-reference → same version
+    const manifest = await cachedManifest(`${impName}@${impVersion}`).catch(() => undefined);
+    return (
+      manifest?.dependencies?.[pkg] ??
+      manifest?.peerDependencies?.[pkg] ??
+      (manifest?.optionalDependencies as Record<string, string> | undefined)?.[pkg]
+    );
+  }
+
+  /** A `.json` imported by a JS module is served as an ESM (`export default …`);
+   *  mark its URL with `?module` so `fetch` wraps it instead of serving raw JSON. */
+  function jsonModuleUrl(url: string, id: string): string {
+    return id.endsWith(".json") ? `${url}?module` : url;
+  }
+
+  /** Resolve a relative specifier against an importer id to a concrete cache id. */
+  async function resolveRelativeId(fromId: string, spec: string): Promise<string> {
+    const dir = fromId.split("/").slice(0, -1);
+    for (const part of spec.split("/")) {
+      if (part === "." || part === "") continue;
+      if (part === "..") dir.pop();
+      else dir.push(part);
+    }
+    const base = dir.join("/");
+    const pkgKey = base.match(/^(?:@[^/]+\/)?[^/]+@[^/]+/)?.[0];
+    if (pkgKey) {
+      const rel = base.slice(pkgKey.length + 1);
+      const file = await resolveRawFile(pkgKey, rel);
+      return `${pkgKey}/${file}`;
+    }
+    return base; // project-relative
+  }
+
+  /** Try extension/index variants for a package-relative file; return what exists. */
+  async function resolveRawFile(pkgKey: string, file: string): Promise<string> {
+    for (const ext of RAW_EXT) {
+      if (await cache.exists(`/raw/${pkgKey}/${file}${ext}`)) return file + ext;
+    }
+    return file;
+  }
+
+  /** Load a canonical id's raw source + format context. */
+  async function loadRaw(
+    id: string,
+  ): Promise<{ path: string; source: string; format: ReturnType<typeof detectFormat> }> {
+    if (id.startsWith("~/")) {
+      if (!project) throw new ModuleResolveError({ url: id }, "no project FilesApi");
+      const path = `/${id.slice(2)}`;
+      const source = await readText(project, path);
+      return { path, source, format: detectFormat(path, source) };
+    }
+    const m = id.match(/^((?:@[^/]+\/)?[^/]+@[^/]+)\/(.+)$/);
+    if (!m) throw new ModuleResolveError({ url: id }, "not a module id");
+    const [, pkgKey, rawFile] = m;
+    await ensureRawByKey(pkgKey);
+    const file = await resolveRawFile(pkgKey, rawFile);
+    const source = await readText(cache, `/raw/${pkgKey}/${file}`);
+    const manifest = await cachedManifest(pkgKey).catch(() => undefined);
+    return { path: `/${pkgKey}/${file}`, source, format: detectFormat(file, source, manifest) };
+  }
+
+  /** Transform a module (pre-resolving its specifiers) and cache the ESM output. */
+  async function transformAndCache(id: string): Promise<string> {
+    const { path, source, format } = await loadRaw(id);
+    const specs = await scanSpecifiers(source, format);
+    const map = new Map<string, string>();
+    for (const spec of specs) map.set(spec, (await resolveSpec(spec, id)).url);
+    const out = await transformer.transform({ path, source, format }, (s) => map.get(s) ?? s);
+    await writeText(cache, `${tRoot}/${id}`, out);
+    return out;
+  }
+
+  /** Resolve a file id (project `~/…` or `{pkg}@{ver}/{file}`) to its raw bytes. */
+  async function rawBytes(id: string): Promise<Uint8Array | undefined> {
+    if (id.startsWith("~/")) {
+      const path = `/${id.slice(2)}`;
+      if (!project || !(await project.exists(path))) return undefined;
+      return collect(project.read(path));
+    }
+    const m = id.match(/^((?:@[^/]+\/)?[^/]+@[^/]+)\/(.+)$/);
+    if (!m) return undefined;
+    await ensureRawByKey(m[1]);
+    const file = await resolveRawFile(m[1], m[2]);
+    if (!(await cache.exists(`/raw/${m[1]}/${file}`))) return undefined;
+    return collect(cache.read(`/raw/${m[1]}/${file}`));
+  }
+
+  /** Serve a file's raw bytes (non-module resources, or `?raw`). */
+  async function serveRaw(id: string, asOctet: boolean): Promise<Response> {
+    const bytes = await rawBytes(id);
+    if (!bytes) return new Response(null, { status: 404 });
+    return new Response(bytes as BodyInit, {
+      status: 200,
+      headers: { "content-type": asOctet ? "application/octet-stream" : contentType(id) },
+    });
+  }
+
+  /** Serve a JSON file as an ESM module (`export default …`) — how a JS `import`
+   *  of a `.json` is satisfied without relying on browser JSON-import attributes. */
+  async function serveJsonModule(id: string): Promise<Response> {
+    const bytes = await rawBytes(id);
+    if (!bytes) return new Response(null, { status: 404 });
+    const json = new TextDecoder().decode(bytes);
+    return new Response(`export default ${json};`, {
+      status: 200,
+      headers: { "content-type": "text/javascript" },
+    });
+  }
+
+  async function resolveEntryId(ref: ModuleRef): Promise<string> {
+    if ("url" in ref) {
+      if (/^https?:/.test(ref.url)) throw new ModuleResolveError(ref, "absolute URL is not local");
+      const p = idFromPath(ref.url);
+      return p.startsWith("~/") ? p : `~/${p.replace(/^\//, "")}`;
+    }
+    return (await ensurePackage(ref)).id;
+  }
+
+  /** Walk + transform + cache the whole graph from an entry; persist the lockfile.
+   *  Returns the entry id and every reachable module id. */
+  async function walkGraph(entry: ModuleRef): Promise<{ rootId: string; ids: string[] }> {
+    const rootId = await resolveEntryId(entry);
+    const seen = new Set<string>();
+    const queue = [rootId];
+    while (queue.length) {
+      const id = queue.shift();
+      if (id === undefined || seen.has(id)) continue;
+      seen.add(id);
+      if (!isModuleFile(id)) {
+        // non-JS resource (json/css/…): ensure it's cached, don't scan/transform.
+        const m = id.match(/^((?:@[^/]+\/)?[^/]+@[^/]+)\//);
+        if (m) await ensureRawByKey(m[1]);
+        continue;
+      }
+      const { source, format } = await loadRaw(id);
+      for (const spec of await scanSpecifiers(source, format)) {
+        const { id: childId } = await resolveSpec(spec, id);
+        if (childId && !seen.has(childId)) queue.push(childId);
+      }
+      await transformAndCache(id);
+    }
+    await writeText(cache, "/lock.json", JSON.stringify(lock));
+    return { rootId, ids: [...seen] };
+  }
+
+  return {
+    get lock() {
+      return lock;
+    },
+
+    async resolve(ref: ModuleRef): Promise<ResolvedModule> {
+      await init();
+      const id = await resolveEntryId(ref);
+      return { url: urlFor(id), target };
+    },
+
+    async prime(entry: ModuleRef): Promise<ResolvedModule> {
+      await init();
+      const { rootId } = await walkGraph(entry);
+      return { url: urlFor(rootId), target };
+    },
+
+    async listResources(entry: ModuleRef): Promise<string[]> {
+      await init();
+      const { ids } = await walkGraph(entry);
+      return ids.map(urlFor).sort();
+    },
+
+    async listPackageFiles(ref: ModuleRef): Promise<string[]> {
+      await init();
+      if ("url" in ref) throw new ModuleResolveError(ref, "not a package reference");
+      const { name, version } = await ensurePackage({ pkg: ref.pkg, version: ref.version });
+      const key = `${name}@${version}`;
+      const files: string[] = [];
+      for await (const info of cache.list(`/raw/${key}`, { recursive: true })) {
+        if (info.kind === "file") files.push(info.path.replace(`/raw/${key}/`, ""));
+      }
+      return files.sort();
+    },
+
+    async fetch(request: Request): Promise<Response> {
+      await init();
+      const url = new URL(request.url);
+      const id = idFromPath(url.pathname);
+      try {
+        // `?raw` → octet-stream; `?module` on a `.json` → ESM wrapper; non-module
+        // files (json/md/css/…) → raw + guessed type.
+        if (url.searchParams.has("raw")) return await serveRaw(id, true);
+        if (url.searchParams.has("module") && id.endsWith(".json")) {
+          return await serveJsonModule(id);
+        }
+        if (!isModuleFile(id)) return await serveRaw(id, false);
+        // module files → transform to ESM.
+        const body = (await cache.exists(`${tRoot}/${id}`))
+          ? await readText(cache, `${tRoot}/${id}`)
+          : await transformAndCache(id);
+        return new Response(body, { status: 200, headers: { "content-type": "text/javascript" } });
+      } catch {
+        return new Response(null, { status: 404 });
+      }
+    },
+  };
+}
+
+function normalizeBase(base: string): string {
+  let b = base.startsWith("/") ? base : `/${base}`;
+  if (!b.endsWith("/")) b += "/";
+  return b;
+}
+
+// The deps prefix is relative to `basePath` — no leading slash, trailing slash
+// when non-empty; "" means "no prefix" (packages served alongside project files).
+function normalizeDeps(prefix: string): string {
+  if (!prefix) return "";
+  const s = prefix.replace(/^\/+/, "").replace(/\/+$/, "");
+  return s ? `${s}/` : "";
+}
+
+async function collect(chunks: AsyncIterable<Uint8Array>): Promise<Uint8Array> {
+  const parts: Uint8Array[] = [];
+  let n = 0;
+  for await (const c of chunks) {
+    parts.push(c);
+    n += c.length;
+  }
+  const out = new Uint8Array(n);
+  let off = 0;
+  for (const p of parts) {
+    out.set(p, off);
+    off += p.length;
+  }
+  return out;
+}

package/src/server/specifiers.ts

@@ -0,0 +1,26 @@
+/** Split a bare specifier into package name + optional subpath (scope-aware). */
+export function parseSpecifier(spec: string): { pkg: string; subpath?: string } {
+  const parts = spec.split("/");
+  if (spec.startsWith("@")) {
+    const pkg = parts.slice(0, 2).join("/");
+    const subpath = parts.slice(2).join("/");
+    return subpath ? { pkg, subpath } : { pkg };
+  }
+  const [pkg, ...rest] = parts;
+  const subpath = rest.join("/");
+  return subpath ? { pkg, subpath } : { pkg };
+}
+
+/**
+ * Relative URL from one canonical module id to another (both are slash paths with
+ * no leading slash, filename last). Keeps served imports mount-prefix-portable.
+ */
+export function relativeUrl(fromId: string, toId: string): string {
+  const from = fromId.split("/").slice(0, -1); // importer directory parts
+  const to = toId.split("/");
+  let i = 0;
+  while (i < from.length && i < to.length && from[i] === to[i]) i++;
+  const ups = from.length - i;
+  const rel = [...Array(ups).fill(".."), ...to.slice(i)].join("/");
+  return rel.startsWith(".") ? rel : `./${rel}`;
+}

package/src/sources/npm-registry-source.ts

@@ -0,0 +1,86 @@
+import type { FilesApi } from "@statewalker/webrun-files";
+import { MemFilesApi } from "@statewalker/webrun-files-mem";
+import semver from "semver";
+import type { LoadedPackage, ModuleRef, PackageManifest, Source } from "../types.js";
+import { ModuleResolveError } from "../types.js";
+import { untarTgz } from "./untar.js";
+
+export interface NpmRegistrySourceOptions {
+  /** Registry base URL. Defaults to the public npm registry. */
+  registryUrl?: string;
+  /** Injectable fetch (tests supply a fake; defaults to global `fetch`). */
+  fetch?: typeof fetch;
+  /** Factory for the in-memory package tree. Defaults to `new MemFilesApi()`. */
+  createFiles?: () => FilesApi;
+}
+
+/** Registry metadata shape (only the fields we read). */
+interface RegistryMeta {
+  "dist-tags"?: Record<string, string>;
+  versions?: Record<string, PackageManifest & { dist?: { tarball?: string } }>;
+}
+
+/**
+ * The default acquisition `Source`: resolves a version from npm registry
+ * metadata, downloads the tarball, untars it into a fresh `FilesApi`, and returns
+ * the package files + manifest. Fully isomorphic (`fetch` + pure-JS untar).
+ */
+export function npmRegistrySource(opts: NpmRegistrySourceOptions = {}): Source {
+  const registry = (opts.registryUrl ?? "https://registry.npmjs.org").replace(/\/+$/, "");
+  const doFetch = opts.fetch ?? globalThis.fetch;
+  const createFiles = opts.createFiles ?? (() => new MemFilesApi());
+
+  return {
+    matches(ref: ModuleRef): boolean {
+      return "pkg" in ref;
+    },
+
+    async load(ref: ModuleRef): Promise<LoadedPackage> {
+      if (!("pkg" in ref)) throw new ModuleResolveError(ref, "not an npm reference");
+      const name = ref.pkg;
+
+      const metaRes = await doFetch(`${registry}/${encodeName(name)}`);
+      if (!metaRes.ok) throw new ModuleResolveError(ref, `registry ${metaRes.status} for ${name}`);
+      const meta = (await metaRes.json()) as RegistryMeta;
+
+      const version = resolveVersion(meta, ref.version, ref);
+      const vmeta = meta.versions?.[version];
+      const tarball = vmeta?.dist?.tarball;
+      if (!tarball) throw new ModuleResolveError(ref, `no tarball for ${name}@${version}`);
+
+      const tgzRes = await doFetch(tarball);
+      if (!tgzRes.ok)
+        throw new ModuleResolveError(ref, `tarball ${tgzRes.status} for ${name}@${version}`);
+      const entries = untarTgz(new Uint8Array(await tgzRes.arrayBuffer()));
+
+      const files = createFiles();
+      for (const [path, bytes] of entries) await files.write(`/${path}`, [bytes]);
+
+      return { name, version, files, manifest: { ...vmeta, name, version } };
+    },
+  };
+}
+
+/** Resolve a dist-tag, exact version, or semver range to a concrete version. */
+export function resolveVersion(
+  meta: RegistryMeta,
+  spec: string | undefined,
+  ref: ModuleRef,
+): string {
+  const versions = Object.keys(meta.versions ?? {});
+  const tags = meta["dist-tags"] ?? {};
+  const s = spec ?? "latest";
+  if (tags[s]) return tags[s]; // dist-tag (latest, next, …)
+  if (versions.includes(s)) return s; // exact
+  const range = semver.validRange(s);
+  if (range) {
+    const best = semver.maxSatisfying(versions, range);
+    if (best) return best;
+  }
+  throw new ModuleResolveError(ref, `no version satisfies "${s}"`);
+}
+
+/** Encode a package name for a registry URL (scoped names need the `/` escaped). */
+function encodeName(name: string): string {
+  return name.startsWith("@") ? name.replace("/", "%2F") : name;
+}

package/src/sources/untar.ts

@@ -0,0 +1,37 @@
+import { gunzipSync } from "fflate";
+
+/**
+ * Untar an npm `.tgz` (gzipped ustar) into a map of path → bytes, isomorphically
+ * (no `node:zlib`, no `Buffer`). npm tarballs prefix every entry with `package/`;
+ * that prefix is stripped so keys are relative to the package root.
+ */
+export function untarTgz(tgz: Uint8Array): Map<string, Uint8Array> {
+  return untar(gunzipSync(tgz));
+}
+
+const td = new TextDecoder();
+
+function str(buf: Uint8Array, start: number, end: number): string {
+  return td.decode(buf.subarray(start, end)).replace(/\0.*/s, "");
+}
+
+/** Parse a raw ustar archive (512-byte blocks). */
+export function untar(buf: Uint8Array): Map<string, Uint8Array> {
+  const out = new Map<string, Uint8Array>();
+  let off = 0;
+  while (off + 512 <= buf.length) {
+    const name = str(buf, off, off + 100);
+    if (!name) break; // two zero blocks terminate the archive
+    const size = Number.parseInt(str(buf, off + 124, off + 136).trim() || "0", 8);
+    const type = str(buf, off + 156, off + 157);
+    const prefix = str(buf, off + 345, off + 500);
+    const full = prefix ? `${prefix}/${name}` : name;
+    const start = off + 512;
+    // type "0" or "" = regular file; skip directories/links/pax headers.
+    if (type === "0" || type === "") {
+      out.set(full.replace(/^package\//, ""), buf.subarray(start, start + size));
+    }
+    off = start + Math.ceil(size / 512) * 512;
+  }
+  return out;
+}

package/src/transform/index.ts

@@ -0,0 +1,52 @@
+import type { PackageManifest, SourceFile, SourceFormat, Transform } from "../types.js";
+import { newCjsTransform } from "./transform-cjs.js";
+import { newEsmTransform } from "./transform-esm.js";
+
+/** The default per-file transform: dispatch ESM/TS/JSX vs CJS by `file.format`. */
+export function newDefaultTransform(): Transform {
+  const esm = newEsmTransform();
+  const cjs = newCjsTransform();
+  return {
+    transform(file: SourceFile, rewrite: (specifier: string) => string): Promise<string> {
+      return file.format === "cjs" ? cjs.transform(file, rewrite) : esm.transform(file, rewrite);
+    },
+  };
+}
+
+// `module.exports` / `exports.x` / `exports[…]` are impossible in real ESM — a
+// *definitive* CJS signal (unlike the word "export", which appears in CJS files'
+// strings/comments, e.g. React's dev warnings).
+const CJS_EXPORTS = /\bmodule\.exports\b|\bexports\s*[.[]/;
+// A real ESM statement: `import`/`export` as syntax, not a word in prose.
+const ESM_STMT = /(^|[\s;])(import|export)[\s{*'"]/;
+const REQUIRE_CALL = /(^|[^.\w])require\s*\(/;
+
+/**
+ * Decide a file's `SourceFormat` from its extension, the package `type`, and
+ * (for ambiguous `.js`) a content sniff. Mirrors Node: `.mjs`=ESM, `.cjs`=CJS,
+ * `.js` follows `package.json#type`; with no `type`, a package `.js` is CJS
+ * (Node's default) unless real ESM syntax is present. Definitive CJS markers
+ * (`module.exports`/`exports.x`) win over a loose `import`/`export` word-match,
+ * so a CJS file with "export" in a string is not mis-read as ESM.
+ */
+export function detectFormat(
+  path: string,
+  source: string,
+  manifest?: PackageManifest,
+): SourceFormat {
+  if (path.endsWith(".ts")) return "ts";
+  if (path.endsWith(".tsx") || path.endsWith(".jsx")) return "tsx";
+  if (path.endsWith(".mjs")) return "esm";
+  if (path.endsWith(".cjs")) return "cjs";
+  if (manifest?.type === "module") return "esm";
+  if (manifest?.type === "commonjs") return "cjs";
+  if (CJS_EXPORTS.test(source)) return "cjs"; // definitive CJS
+  if (ESM_STMT.test(source)) return "esm"; // real import/export syntax
+  if (REQUIRE_CALL.test(source)) return "cjs"; // weaker CJS hint
+  // Node default: a package `.js` with no `type:module` is CJS; authored source
+  // (no manifest) defaults to ESM.
+  return manifest ? "cjs" : "esm";
+}
+
+export { newCjsTransform } from "./transform-cjs.js";
+export { newEsmTransform } from "./transform-esm.js";

package/src/transform/scan.ts

@@ -0,0 +1,32 @@
+import { init as initCjs, parse as parseCjs } from "cjs-module-lexer";
+import { init as initEsm, parse as parseEsm } from "es-module-lexer";
+import type { SourceFormat } from "../types.js";
+import { toJs } from "./to-js.js";
+
+const REQUIRE_RE = /require\(\s*(['"])((?:(?!\1)[^\\]|\\.)*)\1\s*\)/g;
+
+let esmReady: Promise<unknown> | undefined;
+let cjsReady: Promise<unknown> | undefined;
+
+/**
+ * List the import specifiers a file's transform will rewrite — the exact same set
+ * the ESM/CJS transforms discover — so the server can pre-resolve them (async)
+ * before running the synchronous rewrite. For TS/JSX the raw source is scanned;
+ * `es-module-lexer` tolerates types well enough to find every specifier.
+ */
+export async function scanSpecifiers(source: string, format: SourceFormat): Promise<string[]> {
+  if (format === "cjs") {
+    cjsReady ??= initCjs();
+    await cjsReady;
+    return [...new Set([...source.matchAll(REQUIRE_RE)].map((m) => m[2]))];
+  }
+  esmReady ??= initEsm;
+  await esmReady;
+  const [imports] = parseEsm(toJs(source, format));
+  const out = new Set<string>();
+  for (const imp of imports) if (imp.n != null) out.add(imp.n);
+  return [...out];
+}
+
+// re-export so callers can warm the CJS lexer for export detection if needed
+export { parseCjs };

package/src/transform/to-js.ts

@@ -0,0 +1,18 @@
+import { transform as sucraseTransform } from "sucrase";
+import type { SourceFormat } from "../types.js";
+
+/**
+ * Strip TS/JSX to plain JS (leave already-ESM/CJS JS untouched). Shared by the
+ * ESM transform and the specifier scanner so both see the *same* JS — raw TS/JSX
+ * cannot be lexed directly (`es-module-lexer` throws on JSX). JSX uses the
+ * automatic runtime, so scanning the output also surfaces the `react/jsx-runtime`
+ * import the runtime injects.
+ */
+export function toJs(source: string, format: SourceFormat, path?: string): string {
+  if (format === "ts" || format === "tsx") {
+    const transforms: ("typescript" | "jsx")[] =
+      format === "tsx" ? ["typescript", "jsx"] : ["typescript"];
+    return sucraseTransform(source, { transforms, jsxRuntime: "automatic", filePath: path }).code;
+  }
+  return source;
+}