@seanhogg/builderforce-webcontainers-core 2026.10.2 → 2026.10.4

package/src/installer/semver.ts

@@ -0,0 +1,190 @@
+/**
+ * The slice of node-semver an installer needs: parse, compare, range matching
+ * and "highest version satisfying". Written here rather than depending on the
+ * `semver` package because that one is CommonJS, and the core must load as
+ * native ESM in a browser without a bundler step.
+ *
+ * Semantics follow node-semver (and so npm): `^`/`~`/x-ranges/hyphen ranges,
+ * `||` unions, and the prerelease rule — a prerelease only satisfies a range
+ * that names a prerelease on the same major.minor.patch.
+ */
+
+export interface SemVer {
+  major: number;
+  minor: number;
+  patch: number;
+  prerelease: Array<string | number>;
+  /** Normalised `1.2.3-beta.1` (build metadata dropped). */
+  version: string;
+}
+
+type Op = '<' | '<=' | '>' | '>=' | '=';
+interface Comparator {
+  op: Op;
+  version: SemVer;
+}
+/** OR of AND sets; an empty AND set matches every (non-prerelease) version. */
+type Range = Comparator[][];
+
+const VERSION = /^\s*[v=]*\s*(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-.]+)?\s*$/;
+const PARTIAL = /^[v=]*(\d+|[xX*])?(?:\.(\d+|[xX*]))?(?:\.(\d+|[xX*]))?(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-.]+)?$/;
+
+export function parseVersion(input: string): SemVer | null {
+  const m = VERSION.exec(input);
+  if (!m) return null;
+  const prerelease = m[4] ? m[4].split('.').map((id) => (/^\d+$/.test(id) ? Number(id) : id)) : [];
+  return make(Number(m[1]), Number(m[2]), Number(m[3]), prerelease);
+}
+
+function make(major: number, minor: number, patch: number, prerelease: Array<string | number> = []): SemVer {
+  const pre = prerelease.length ? `-${prerelease.join('.')}` : '';
+  return { major, minor, patch, prerelease, version: `${major}.${minor}.${patch}${pre}` };
+}
+
+export function valid(input: string): string | null {
+  return parseVersion(input)?.version ?? null;
+}
+
+function comparePre(a: SemVer, b: SemVer): number {
+  if (!a.prerelease.length || !b.prerelease.length) return (b.prerelease.length ? 1 : 0) - (a.prerelease.length ? 1 : 0) || 0;
+  for (let i = 0; ; i++) {
+    const x = a.prerelease[i];
+    const y = b.prerelease[i];
+    if (x === undefined && y === undefined) return 0;
+    if (x === undefined) return -1;
+    if (y === undefined) return 1;
+    if (x === y) continue;
+    if (typeof x === 'number' && typeof y === 'number') return x < y ? -1 : 1;
+    if (typeof x === 'number') return -1; // numeric identifiers sort below alphanumeric ones
+    if (typeof y === 'number') return 1;
+    return x < y ? -1 : 1;
+  }
+}
+
+/** -1, 0 or 1. Accepts strings or parsed versions. */
+export function compare(a: string | SemVer, b: string | SemVer): number {
+  const x = typeof a === 'string' ? parseVersion(a) : a;
+  const y = typeof b === 'string' ? parseVersion(b) : b;
+  if (!x || !y) throw new TypeError(`Invalid version: ${!x ? String(a) : String(b)}`);
+  return Math.sign(x.major - y.major || x.minor - y.minor || x.patch - y.patch) || comparePre(x, y);
+}
+
+const isX = (part: string | undefined) => part === undefined || part === 'x' || part === 'X' || part === '*';
+
+/** One `op + partial` token → comparators (an x-range expands to a pair). */
+function expand(token: string): Comparator[] | null {
+  const opMatch = /^(~>?|\^|<=|>=|<|>|=)?(.*)$/.exec(token)!;
+  const op = opMatch[1] ?? '';
+  const m = PARTIAL.exec(opMatch[2]!);
+  if (!m) return null;
+  const [, M, m2, p, pre] = m;
+  const pr = pre ? pre.split('.').map((id) => (/^\d+$/.test(id) ? Number(id) : id)) : [];
+  const xM = isX(M), xm = xM || isX(m2), xp = xm || isX(p);
+  const maj = xM ? 0 : Number(M), min = xm ? 0 : Number(m2), pat = xp ? 0 : Number(p);
+  const ge = (v: SemVer): Comparator => ({ op: '>=', version: v });
+  const lt = (v: SemVer): Comparator => ({ op: '<', version: v });
+  const upper = (a: number, b: number, c: number) => lt(make(a, b, c, [0]));
+
+  if (op === '^') {
+    if (xM) return [];
+    const lower = ge(make(maj, min, pat, pr));
+    if (maj > 0 || xm) return [lower, upper(maj + 1, 0, 0)];
+    if (min > 0 || xp) return [lower, upper(0, min + 1, 0)];
+    return [lower, upper(0, 0, pat + 1)];
+  }
+  if (op === '~' || op === '~>') {
+    if (xM) return [];
+    const lower = ge(make(maj, min, pat, pr));
+    return xm ? [lower, upper(maj + 1, 0, 0)] : [lower, upper(maj, min + 1, 0)];
+  }
+  if (op === '' || op === '=') {
+    if (xM) return [];
+    if (xm) return [ge(make(maj, 0, 0)), upper(maj + 1, 0, 0)];
+    if (xp) return [ge(make(maj, min, 0)), upper(maj, min + 1, 0)];
+    return [{ op: '=', version: make(maj, min, pat, pr) }];
+  }
+  // <, <=, >, >= with a partial version.
+  if (xM) return op === '<' || op === '>' ? [lt(make(0, 0, 0, [0]))] : [];
+  if (!xp) return [{ op: op as Op, version: make(maj, min, pat, pr) }];
+  if (op === '>') return [ge(xm ? make(maj + 1, 0, 0) : make(maj, min + 1, 0))];
+  if (op === '<=') return [xm ? upper(maj + 1, 0, 0) : upper(maj, min + 1, 0)];
+  if (op === '<') return [lt(make(maj, min, 0, [0]))];
+  return [ge(make(maj, min, 0))]; // >=
+}
+
+function parsePartialBound(text: string): { parts: string[]; full: SemVer | null } {
+  return { parts: text.replace(/^[v=]+/, '').split('-')[0]!.split('.'), full: parseVersion(text) };
+}
+
+function hyphen(from: string, to: string): Comparator[] | null {
+  const lower = expand(`>=${from}`);
+  if (!lower) return null;
+  const { parts, full } = parsePartialBound(to);
+  if (full) return [...lower, { op: '<=', version: full }];
+  if (isX(parts[0])) return lower;
+  const upperC = expand(`<=${to}`);
+  return upperC ? [...lower, ...upperC] : null;
+}
+
+const cache = new Map<string, Range | null>();
+
+export function parseRange(input: string): Range | null {
+  const hit = cache.get(input);
+  if (hit !== undefined) return hit;
+  let range: Range | null = [];
+  for (const raw of input.split('||')) {
+    const part = raw.trim().replace(/(<=|>=|<|>|=|~>?|\^)\s+/g, '$1');
+    const h = /^(\S+)\s+-\s+(\S+)$/.exec(part);
+    const set = h ? hyphen(h[1]!, h[2]!) : part.split(/\s+/).filter(Boolean).reduce<Comparator[] | null>((acc, token) => {
+      const c = acc && expand(token);
+      return c ? [...acc!, ...c] : null;
+    }, []);
+    if (!set) {
+      range = null;
+      break;
+    }
+    range.push(set);
+  }
+  cache.set(input, range);
+  return range;
+}
+
+export function validRange(input: string): boolean {
+  return parseRange(input) !== null;
+}
+
+function test(c: Comparator, v: SemVer): boolean {
+  const d = compare(v, c.version);
+  switch (c.op) {
+    case '<': return d < 0;
+    case '<=': return d <= 0;
+    case '>': return d > 0;
+    case '>=': return d >= 0;
+    default: return d === 0;
+  }
+}
+
+function testSet(set: Comparator[], v: SemVer, includePrerelease: boolean): boolean {
+  if (!set.every((c) => test(c, v))) return false;
+  if (!v.prerelease.length || includePrerelease) return true;
+  // A prerelease only matches when the range itself names one on the same tuple.
+  return set.some((c) => c.version.prerelease.length > 0
+    && c.version.major === v.major && c.version.minor === v.minor && c.version.patch === v.patch);
+}
+
+export function satisfies(version: string | SemVer, range: string, options: { includePrerelease?: boolean } = {}): boolean {
+  const v = typeof version === 'string' ? parseVersion(version) : version;
+  const r = parseRange(range);
+  if (!v || !r) return false;
+  return r.some((set) => testSet(set, v, options.includePrerelease ?? false));
+}
+
+/** The highest of `versions` satisfying `range`, or null. */
+export function maxSatisfying(versions: Iterable<string>, range: string): string | null {
+  let best: SemVer | null = null;
+  for (const raw of versions) {
+    const v = parseVersion(raw);
+    if (v && satisfies(v, range) && (!best || compare(v, best) > 0)) best = v;
+  }
+  return best?.version ?? null;
+}

package/src/installer/spec.ts

@@ -0,0 +1,53 @@
+/**
+ * Package specifiers as `npm install` and package.json write them:
+ * `react`, `react@^18`, `@scope/pkg@latest`, and aliases (`foo@npm:bar@^1`).
+ * Git, file and URL specs are recognised so they can be declined with a reason.
+ */
+
+export interface ParsedSpec {
+  /** The name it is installed under (the alias, for `npm:` specs). */
+  name: string;
+  /** The registry package actually fetched. */
+  registryName: string;
+  /** A semver range or a dist-tag. `''` when none was given. */
+  range: string;
+}
+
+const UNSUPPORTED = /^(?:git\+|git:|github:|gitlab:|bitbucket:|file:|link:|https?:|workspace:)/;
+
+/** Split `name@range` (the CLI form). */
+export function parseInstallSpec(spec: string): ParsedSpec {
+  const at = spec.indexOf('@', spec.startsWith('@') ? 1 : 0);
+  const name = at < 0 ? spec : spec.slice(0, at);
+  const range = at < 0 ? '' : spec.slice(at + 1);
+  return parseDependency(name, range);
+}
+
+/** A package.json `dependencies` entry: `"foo": "npm:bar@^1"` or `"foo": "^1"`. */
+export function parseDependency(name: string, range: string): ParsedSpec {
+  if (!name || /\s/.test(name)) throw new Error(`Invalid package name "${name}".`);
+  if (range.startsWith('npm:')) {
+    const inner = parseInstallSpec(range.slice(4));
+    return { name, registryName: inner.registryName, range: inner.range };
+  }
+  if (UNSUPPORTED.test(range) || /^[^@/\s]+\/[^@/\s]+(#.*)?$/.test(range)) {
+    throw new Error(`"${name}@${range}": only registry packages are supported (not git, file or URL dependencies).`);
+  }
+  return { name, registryName: name, range: range.trim() };
+}
+
+export interface PackageJson {
+  name?: string;
+  version?: string;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  scripts?: Record<string, string>;
+  bin?: string | Record<string, string>;
+  [key: string]: unknown;
+}
+
+export function sortObject(record: Record<string, string>): Record<string, string> {
+  return Object.fromEntries(Object.entries(record).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+}

package/src/installer/tar.ts

@@ -0,0 +1,155 @@
+/**
+ * A minimal tar reader: enough for npm tarballs. ustar headers with the `prefix`
+ * field, pax extended headers (`path`, `linkpath`, `size`) and GNU long names.
+ * Everything else (devices, fifos) is skipped. Symlinks are surfaced as entries
+ * so the caller can decide; npm tarballs essentially never contain them.
+ */
+
+export interface TarEntry {
+  path: string;
+  type: 'file' | 'directory' | 'symlink';
+  data: Uint8Array;
+  mode: number;
+  linkpath?: string;
+}
+
+const BLOCK = 512;
+const decoder = new TextDecoder();
+
+function str(bytes: Uint8Array, start: number, length: number): string {
+  const slice = bytes.subarray(start, start + length);
+  const nul = slice.indexOf(0);
+  return decoder.decode(nul < 0 ? slice : slice.subarray(0, nul));
+}
+
+function octal(bytes: Uint8Array, start: number, length: number): number {
+  // GNU base-256 encoding for sizes over 8 GiB: top bit of the first byte set.
+  if (bytes[start]! & 0x80) {
+    let value = 0;
+    for (let i = start + 1; i < start + length; i++) value = value * 256 + bytes[i]!;
+    return value;
+  }
+  const text = str(bytes, start, length).trim();
+  return text ? parseInt(text, 8) : 0;
+}
+
+/** Parse pax `"<len> key=value\n"` records. */
+function parsePax(data: Uint8Array): Record<string, string> {
+  const out: Record<string, string> = {};
+  const text = decoder.decode(data);
+  let i = 0;
+  while (i < text.length) {
+    const space = text.indexOf(' ', i);
+    if (space < 0) break;
+    const length = parseInt(text.slice(i, space), 10);
+    if (!length) break;
+    // The length counts bytes, but these records are ASCII in practice; fall back
+    // to the newline when a multi-byte path makes the count disagree.
+    let record = text.slice(space + 1, i + length);
+    if (!record.endsWith('\n')) record = text.slice(space + 1, text.indexOf('\n', space) + 1);
+    const eq = record.indexOf('=');
+    if (eq > 0) out[record.slice(0, eq)] = record.slice(eq + 1).replace(/\n$/, '');
+    i = space + 1 + record.length;
+  }
+  return out;
+}
+
+function isZeroBlock(bytes: Uint8Array, at: number): boolean {
+  for (let i = at; i < at + BLOCK; i++) if (bytes[i] !== 0) return false;
+  return true;
+}
+
+export function untar(bytes: Uint8Array): TarEntry[] {
+  const entries: TarEntry[] = [];
+  let offset = 0;
+  let pax: Record<string, string> = {};
+  let globalPax: Record<string, string> = {};
+  let longName: string | undefined;
+  let longLink: string | undefined;
+
+  while (offset + BLOCK <= bytes.length) {
+    if (isZeroBlock(bytes, offset)) break;
+    const name = str(bytes, offset, 100);
+    const mode = octal(bytes, offset + 100, 8);
+    const headerSize = octal(bytes, offset + 124, 12);
+    const typeflag = String.fromCharCode(bytes[offset + 156] || 48);
+    const linkname = str(bytes, offset + 157, 100);
+    const magic = str(bytes, offset + 257, 6);
+    const prefix = magic.startsWith('ustar') ? str(bytes, offset + 345, 155) : '';
+    const merged = { ...globalPax, ...pax };
+    const size = merged.size ? Number(merged.size) : headerSize;
+    const dataStart = offset + BLOCK;
+    const data = bytes.subarray(dataStart, dataStart + size);
+    offset = dataStart + Math.ceil(size / BLOCK) * BLOCK;
+
+    if (typeflag === 'x') {
+      pax = parsePax(data);
+      continue;
+    }
+    if (typeflag === 'g') {
+      globalPax = { ...globalPax, ...parsePax(data) };
+      continue;
+    }
+    if (typeflag === 'L') {
+      longName = str(data, 0, data.length);
+      continue;
+    }
+    if (typeflag === 'K') {
+      longLink = str(data, 0, data.length);
+      continue;
+    }
+
+    const path = merged.path ?? longName ?? (prefix ? `${prefix}/${name}` : name);
+    const linkpath = merged.linkpath ?? longLink ?? linkname;
+    pax = {};
+    longName = undefined;
+    longLink = undefined;
+
+    if (typeflag === '0' || typeflag === '\0' || typeflag === '7') entries.push({ path, type: 'file', data, mode });
+    else if (typeflag === '5') entries.push({ path, type: 'directory', data: new Uint8Array(0), mode });
+    else if (typeflag === '2') entries.push({ path, type: 'symlink', data: new Uint8Array(0), mode, linkpath });
+    else if (typeflag === '1') entries.push({ path, type: 'symlink', data: new Uint8Array(0), mode, linkpath }); // hard link: same treatment
+  }
+  return entries;
+}
+
+/** Write a tar archive (ustar). Used by tests to build fixture tarballs. */
+export function tar(files: Record<string, string | Uint8Array>): Uint8Array {
+  const encoder = new TextEncoder();
+  const chunks: Uint8Array[] = [];
+  for (const [path, contents] of Object.entries(files)) {
+    const data = typeof contents === 'string' ? encoder.encode(contents) : contents;
+    const header = new Uint8Array(BLOCK);
+    const put = (text: string, at: number, length: number) => header.set(encoder.encode(text).subarray(0, length), at);
+    let name = path;
+    let prefix = '';
+    if (encoder.encode(path).length > 100) {
+      const cut = path.lastIndexOf('/', 155);
+      prefix = path.slice(0, cut);
+      name = path.slice(cut + 1);
+    }
+    put(name, 0, 100);
+    put('0000644\0', 100, 8);
+    put('0000000\0', 108, 8);
+    put('0000000\0', 116, 8);
+    put(data.length.toString(8).padStart(11, '0') + '\0', 124, 12);
+    put('00000000000\0', 136, 12);
+    put('        ', 148, 8);
+    header[156] = 48; // '0'
+    put('ustar\0', 257, 6);
+    put('00', 263, 2);
+    put(prefix, 345, 155);
+    let sum = 0;
+    for (const byte of header) sum += byte;
+    put(sum.toString(8).padStart(6, '0') + '\0 ', 148, 8);
+    chunks.push(header, data, new Uint8Array((BLOCK - (data.length % BLOCK)) % BLOCK));
+  }
+  chunks.push(new Uint8Array(BLOCK * 2));
+  const out = new Uint8Array(chunks.reduce((n, c) => n + c.length, 0));
+  let at = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, at);
+    at += chunk.length;
+  }
+  return out;
+}

package/src/installer/tree.ts

@@ -0,0 +1,236 @@
+/**
+ * Dependency tree resolution with npm-style hoisting.
+ *
+ * Breadth-first from the root, each dependency edge is first satisfied by
+ * whatever Node's own lookup would find (walking up `node_modules`); only when
+ * that fails is a version picked and PLACED — as high as possible without
+ * (a) landing on a different version already there, or (b) shadowing a version
+ * that some deeper package already resolves to and would stop satisfying. That
+ * is what dedupes compatible versions to the top and nests conflicts.
+ *
+ * Locations are npm lockfile keys: `node_modules/a/node_modules/b`; the root is `''`.
+ */
+import type { PackageManifest } from './registry.js';
+import { parseDependency, type PackageJson, type ParsedSpec } from './spec.js';
+import { satisfies, validRange } from './semver.js';
+
+export type EdgeType = 'prod' | 'dev' | 'optional' | 'peer';
+
+export interface ResolvedPackage {
+  location: string;
+  /** The name it is installed under (an alias may differ from `manifest.name`). */
+  name: string;
+  manifest: PackageManifest;
+  /** Only reachable through devDependencies. */
+  dev: boolean;
+  /** Only reachable through optionalDependencies. */
+  optional: boolean;
+}
+
+interface Dependency {
+  name: string;
+  range: string;
+  type: EdgeType;
+}
+
+interface Edge extends Dependency {
+  /** The package that declared it (`''` for the root). */
+  owner: string;
+  /** Where lookup starts: the owner, or the owner's parent for a peer. */
+  from: string;
+  /** The location it resolved to. */
+  to: string;
+}
+
+export interface ResolveTreeOptions {
+  root: PackageJson;
+  /** Choose a manifest for a spec (lockfile first, then the registry). */
+  pick(spec: ParsedSpec): Promise<PackageManifest>;
+  /** Warm caches for a spec about to be picked; lets fetches overlap. */
+  prefetch?(spec: ParsedSpec): void;
+  /** Leave devDependencies out (`--omit=dev`). */
+  production?: boolean;
+  warn(message: string): void;
+  onResolved?(pkg: { name: string; version: string }): void;
+}
+
+export const childLocation = (loc: string, name: string): string => (loc ? `${loc}/node_modules/${name}` : `node_modules/${name}`);
+
+export function parentLocation(location: string): string {
+  const cut = location.lastIndexOf('/node_modules/');
+  return cut < 0 ? '' : location.slice(0, cut);
+}
+
+/** `loc`, then each enclosing package location, ending with the root `''`. */
+function* chain(loc: string): Generator<string> {
+  let current = loc;
+  for (;;) {
+    yield current;
+    if (!current) return;
+    current = parentLocation(current);
+  }
+}
+
+const inSubtree = (location: string, loc: string) => loc === '' || location === loc || location.startsWith(loc + '/node_modules/');
+
+/** The platform this runtime reports: a browser, so no native binaries ever fit. */
+export const PLATFORM = { os: 'linux', cpu: 'wasm32' } as const;
+
+function fitsPlatform(m: PackageManifest): boolean {
+  const ok = (list: string[] | undefined, value: string) =>
+    !list?.length || (list.some((x) => x === value) && !list.includes('!' + value)) || (list.every((x) => x.startsWith('!')) && !list.includes('!' + value));
+  return ok(m.os, PLATFORM.os) && ok(m.cpu, PLATFORM.cpu);
+}
+
+function bundledNames(m: { bundleDependencies?: string[] | boolean; bundledDependencies?: string[] | boolean; dependencies?: Record<string, string> }): Set<string> {
+  const field = m.bundleDependencies ?? m.bundledDependencies;
+  if (field === true) return new Set(Object.keys(m.dependencies ?? {}));
+  return new Set(Array.isArray(field) ? field : []);
+}
+
+function dependenciesOf(m: PackageJson | PackageManifest, isRoot: boolean, production: boolean): Dependency[] {
+  const out = new Map<string, Dependency>();
+  const add = (record: Record<string, string> | undefined, type: EdgeType) => {
+    for (const [name, range] of Object.entries(record ?? {})) if (!out.has(name) || type === 'optional') out.set(name, { name, range, type });
+  };
+  if (isRoot && !production) add((m as PackageJson).devDependencies, 'dev');
+  add(m.dependencies, 'prod');
+  add(m.optionalDependencies, 'optional');
+  if (!isRoot) {
+    const meta = (m as PackageManifest).peerDependenciesMeta ?? {};
+    for (const [name, range] of Object.entries(m.peerDependencies ?? {})) {
+      if (!out.has(name) && !meta[name]?.optional) out.set(name, { name, range, type: 'peer' });
+    }
+  }
+  const bundled = bundledNames(m as PackageManifest);
+  return [...out.values()].filter((d) => !bundled.has(d.name)).sort((a, b) => (a.name < b.name ? -1 : 1));
+}
+
+/** Does `version` satisfy the edge's range? A dist-tag never "matches" without a pick. */
+function matches(version: string, range: string): boolean {
+  const r = range || '*';
+  return validRange(r) && satisfies(version, r);
+}
+
+export async function resolveTree(options: ResolveTreeOptions): Promise<Map<string, ResolvedPackage>> {
+  const nodes = new Map<string, ResolvedPackage>();
+  const edges: Edge[] = [];
+  const edgesByName = new Map<string, Edge[]>();
+  const production = options.production ?? false;
+
+  const lookup = (from: string, name: string): string | undefined => {
+    for (const loc of chain(from)) {
+      const at = childLocation(loc, name);
+      if (nodes.has(at)) return at;
+    }
+    return undefined;
+  };
+
+  const record = (edge: Edge) => {
+    edges.push(edge);
+    const list = edgesByName.get(edge.name) ?? [];
+    list.push(edge);
+    edgesByName.set(edge.name, list);
+  };
+
+  /** Edges below `loc` that a new `name` at `loc` would capture. */
+  const captured = (loc: string, name: string) =>
+    (edgesByName.get(name) ?? []).filter((e) => inSubtree(e.from, loc) && !(inSubtree(parentLocation(e.to), loc) && parentLocation(e.to) !== loc));
+
+  const place = (from: string, name: string, version: string): string | undefined => {
+    let target: string | undefined;
+    for (const loc of chain(from)) {
+      if (nodes.has(childLocation(loc, name))) break;
+      if (captured(loc, name).some((e) => !matches(version, e.range))) break;
+      target = loc;
+    }
+    return target === undefined ? undefined : childLocation(target, name);
+  };
+
+  const queue: Array<{ location: string; deps: Dependency[] }> = [{ location: '', deps: dependenciesOf(options.root, true, production) }];
+  while (queue.length) {
+    const { location, deps } = queue.shift()!;
+    const specs = new Map<string, ParsedSpec>();
+    for (const dep of deps) {
+      try {
+        const spec = parseDependency(dep.name, dep.range);
+        specs.set(dep.name, spec);
+        options.prefetch?.(spec);
+      } catch (error) {
+        if (dep.type !== 'optional') throw error;
+        options.warn(`skipped optional ${dep.name}: ${(error as Error).message}`);
+      }
+    }
+
+    for (const dep of deps) {
+      const spec = specs.get(dep.name);
+      if (!spec) continue;
+      const from = dep.type === 'peer' ? parentLocation(location) : location;
+      const existing = lookup(from, dep.name);
+      const edge = { ...dep, range: spec.range, owner: location, from };
+      if (existing && matches(nodes.get(existing)!.manifest.version, spec.range)) {
+        record({ ...edge, to: existing });
+        continue;
+      }
+      if (existing && dep.type === 'peer') {
+        options.warn(`peer dependency conflict: ${location || 'root'} wants ${dep.name}@${spec.range}, found ${nodes.get(existing)!.manifest.version}`);
+        record({ ...edge, to: existing });
+        continue;
+      }
+
+      let manifest: PackageManifest;
+      try {
+        manifest = await options.pick(spec);
+      } catch (error) {
+        if (dep.type !== 'optional') throw error;
+        options.warn(`skipped optional ${dep.name}: ${(error as Error).message}`);
+        continue;
+      }
+      if (!fitsPlatform(manifest)) {
+        if (dep.type === 'optional') continue; // a native binary for another platform: expected, not an error
+        options.warn(`${manifest.name}@${manifest.version} targets ${[manifest.os, manifest.cpu].flat().filter(Boolean).join('/')} and may not work here`);
+      }
+      if (existing && nodes.get(existing)!.manifest.version === manifest.version) {
+        record({ ...edge, to: existing });
+        continue;
+      }
+
+      const target = place(from, dep.name, manifest.version);
+      if (!target) {
+        options.warn(`could not place ${dep.name}@${manifest.version} for ${location || 'root'}`);
+        continue;
+      }
+      for (const e of captured(parentLocation(target), dep.name)) e.to = target; // now resolved by the nearer copy
+      nodes.set(target, { location: target, name: dep.name, manifest, dev: false, optional: false });
+      record({ ...edge, to: target });
+      options.onResolved?.({ name: dep.name, version: manifest.version });
+      queue.push({ location: target, deps: dependenciesOf(manifest, false, production) });
+    }
+  }
+
+  markFlags(nodes, edges);
+  return nodes;
+}
+
+/** npm's `dev`/`optional` flags: reachability from the root without those edge kinds. */
+function markFlags(nodes: Map<string, ResolvedPackage>, edges: Edge[]): void {
+  const reach = (skip: (e: Edge) => boolean): Set<string> => {
+    const seen = new Set<string>();
+    const stack = [''];
+    while (stack.length) {
+      const owner = stack.pop()!;
+      for (const e of edges) {
+        if (e.owner !== owner || skip(e) || seen.has(e.to)) continue;
+        seen.add(e.to);
+        stack.push(e.to);
+      }
+    }
+    return seen;
+  };
+  const nonDev = reach((e) => e.owner === '' && e.type === 'dev');
+  const nonOptional = reach((e) => e.type === 'optional');
+  for (const node of nodes.values()) {
+    node.dev = !nonDev.has(node.location);
+    node.optional = !nonOptional.has(node.location);
+  }
+}