@exodus/stasis 1.0.0-beta.1 → 1.0.0-beta.10

package/src/vfs-bundle/tree.js

@@ -0,0 +1,647 @@
+import { constants } from 'node:fs'
+import { basename, dirname, join, posix, relative, resolve, sep } from 'node:path'
+
+import { isValidRepoField } from '@exodus/stasis-core/bundle'
+import { NO_ENTRY, packageJSONStat, packageJSONText, parseGithubRepository, readJson } from '@exodus/stasis-core/bundle-util'
+import { byName } from '@exodus/stasis-core/host'
+import { hasNodeModulesSegment, isPlainObject } from '@exodus/stasis-core/util'
+import { buildNpmTree, findNpmWorkspaces } from '@preventive/deptree/npm.js'
+import { buildPnpmTree, findPnpmProjects } from '@preventive/deptree/pnpm.js'
+import { LockfileError, TomlError, buildSoldeerTree } from '@preventive/deptree/soldeer.js'
+import { buildYarn1Tree, findYarn1Workspaces } from '@preventive/deptree/yarn1.js'
+import { VfsError } from '@preventive/vfs'
+import { createNodeResolver } from '../resolve-node.js'
+import { settleSoldeer } from './soldeer.js'
+import { isDir, isFile } from '../resolve-typescript.js'
+
+// A project's dependencies laid out in memory from its lockfile by @preventive/deptree, as `pnpm
+// install --frozen-lockfile --ignore-scripts` lays out its node_modules with pnpm 9, 10, 11 or 12,
+// `yarn install --frozen-lockfile --ignore-scripts` with yarn 1.22, `npm ci --ignore-scripts` with
+// npm 10.9 or 11, or `soldeer install` its dependencies folder with Soldeer 0.12, and the host that
+// reads the project through them. The project is read through a host it is given, and nothing else.
+
+// cwd or the nearest of its ancestors that `holds`, or null.
+export function nearest(cwd, holds) {
+  for (let dir = cwd; ; dir = dirname(dir)) {
+    if (holds(dir)) return dir
+    if (dirname(dir) === dir) return null
+  }
+}
+
+// Whether a directory holds a file of one of `names`.
+export const holding = (host, ...names) => (dir) => names.some((name) => isFile(join(dir, name), host))
+
+// The directory of the package cwd is in that is none of `projects` (their directories from
+// `root`), or null: the nearest package.json with a name between cwd and `root`, one without being a
+// `type` marker.
+function outsider(host, root, cwd, projects) {
+  for (let dir = cwd; dir !== root; dir = dirname(dir)) {
+    const file = join(dir, 'package.json')
+    if (!isFile(file, host)) continue
+    if (projects.has(relative(root, dir))) return null
+    const json = readJson(file, host) // unreadable, a package all the same
+    if (json === null || json.name !== undefined) return dir
+  }
+  return null
+}
+
+// `promise`, a refusal of @preventive/lockfile's naming `file` (deptree names the files it reads but
+// for yarn.lock and soldeer.lock).
+const naming = (file, promise) => promise.catch((cause) => {
+  if (!(cause instanceof LockfileError || cause instanceof TomlError)) throw cause
+  throw new Error(`${file}: ${cause.message}`, { cause })
+})
+
+// The directory `root` as `host` holds it, by paths from `/`, as deptree reads a project.
+export function projectView(host, root) {
+  const at = (p) => (p === '/' ? root : join(root, p))
+  const typeOf = (st) => (st.isDirectory() ? 'directory' : st.isFile() ? 'file' : 'other')
+  const stat = (p) => {
+    const st = host.stat(at(p))
+    if (st === null) throw new VfsError('ENOENT', p)
+    return st
+  }
+  return {
+    readdir: (p) => host.readdir(at(p)).map((d) => d.name),
+    lstat(p) {
+      if (host.readlink(at(p)) !== null) return { type: 'symlink', mode: 0o777 }
+      const st = stat(p)
+      return { type: typeOf(st), mode: st.mode & 0o777 }
+    },
+    stat: (p) => ({ type: typeOf(stat(p)) }),
+    readFile: (p) => host.readFile(at(p)),
+  }
+}
+
+// What pnpm matches packages' `libc` against (as deptree's host.libc takes it).
+const LIBCS = new Set(['glibc', 'musl', 'unknown'])
+
+// pnpm's libc, detect-libc's familySync, by its check of Node's report alone (it reads
+// /usr/bin/ldd first): unknown where that can't tell, which pnpm then installs everything for.
+// The report leaves out the network, whose reverse DNS can stall.
+let machineLibc
+function currentLibc() {
+  if (machineLibc !== undefined) return machineLibc
+  machineLibc = 'unknown'
+  if (process.platform !== 'linux' || !process.report) return machineLibc
+  const { excludeNetwork } = process.report
+  try {
+    process.report.excludeNetwork = true
+    const report = process.report.getReport()
+    if (report.header?.glibcVersionRuntime) machineLibc = 'glibc'
+    else if (report.sharedObjects?.some((file) => file.includes('libc.musl-') || file.includes('ld-musl-'))) machineLibc = 'musl'
+  } catch { /* unknown */ } finally {
+    process.report.excludeNetwork = excludeNetwork
+  }
+  return machineLibc
+}
+
+const machine = () => ({ node: process.versions.node, os: process.platform, cpu: process.arch })
+
+// The machine a tree is laid out for: this one, but for the `os`, `cpu` and `libc` given. A libc is
+// detected only for this machine's os; for another, unless given, pnpm matches none ('unknown').
+const target = ({ os, cpu, libc } = {}) => {
+  const here = machine()
+  const forOs = os ?? here.os
+  return { node: here.node, os: forOs, cpu: cpu ?? here.cpu, libc: libc ?? (forOs === here.os ? currentLibc() : 'unknown') }
+}
+
+// `os` and `cpu` as Node names them (process.platform, process.arch); `libc` is pnpm's alone, and
+// Soldeer takes `os` alone: what a package manager matches nothing against changes nothing.
+export function checkTarget(name, { os, cpu, libc }) {
+  for (const [key, value] of Object.entries({ os, cpu })) {
+    if (value !== undefined && (typeof value !== 'string' || value === '')) throw new TypeError(`${name}: ${key} must be a non-empty string`)
+  }
+  if (libc !== undefined && !LIBCS.has(libc)) throw new TypeError(`${name}: libc must be one of 'glibc', 'musl', 'unknown'`)
+}
+
+// `cache`, where npm packages' tarballs and version documents are kept, as @preventive/upstream's
+// CacheOptions take it: left out, in setCacheDir's cache; a store with `read` and `write`, in place
+// of it; or false, nowhere. Checked as deptree checks it, before anything is fetched.
+export function checkCache(name, cache) {
+  if (cache === undefined || cache === false || (typeof cache?.read === 'function' && typeof cache?.write === 'function')) return
+  throw new TypeError(`${name}: cache must be false, or a store with read and write, or left out`)
+}
+
+// yarn installs a workspace from the root that declares it, whatever yarn.lock is nearer, and any
+// other package from the nearest yarn.lock.
+function yarn1Root(host, cwd) {
+  const workspaces = (dir) => {
+    const declared = readJson(join(dir, 'package.json'), host)?.workspaces
+    return Boolean(Array.isArray(declared) ? declared : declared?.packages)
+  }
+  const root = nearest(cwd, workspaces)
+  if (root !== null && outsider(host, root, cwd, new Set(findYarn1Workspaces({ project: projectView(host, root) }))) === null) return root
+  return nearest(cwd, holding(host, 'yarn.lock'))
+}
+
+// Whether `dir` holds a package: a package.json naming one, or unreadable, which is one all the same;
+// one with no name is a `type` marker, its files the package's above.
+function holdsPackage(host, dir) {
+  if (!isFile(join(dir, 'package.json'), host)) return false
+  const json = readJson(join(dir, 'package.json'), host)
+  return json === null || json.name !== undefined
+}
+
+// The first directory above `dir` whose workspaces, as npm's glob finds them on `os`, take it, as npm
+// finds its local prefix; else null. npm takes a falsy declaration for none, and fails on any other
+// but a sequence of globs, or yarn's `{ packages: [...] }` of them.
+function npmWorkspaceRoot(host, dir, os) {
+  for (let above = dir; dirname(above) !== above;) {
+    above = dirname(above)
+    const declared = readJson(join(above, 'package.json'), host)?.workspaces
+    if (!declared) continue
+    const globs = Array.isArray(declared.packages) ? declared.packages : declared
+    if (!Array.isArray(globs) || globs.some((glob) => typeof glob !== 'string')) throw new Error(`${join(above, 'package.json')}: workspaces: expected a sequence of globs, which npm fails without`)
+    if (findNpmWorkspaces({ project: projectView(host, above), os: target({ os }).os }).includes(relative(above, dir))) return above
+  }
+  return null
+}
+
+// npm installs the package cwd is in from npmWorkspaceRoot's, whatever package-lock.json is nearer,
+// and past a workspace declaring workspaces of its own -- and any other package from the nearest
+// package-lock.json beside a package.json, npm's prefix being no directory without one. A
+// package.json with no name is a package where a workspace root takes it, which npm names by its
+// directory, and else a `type` marker, its files the package's above.
+function npmRoot(host, cwd, os) {
+  for (let dir = cwd; ; dir = dirname(dir)) {
+    if (isFile(join(dir, 'package.json'), host)) {
+      const root = npmWorkspaceRoot(host, dir, os)
+      if (root !== null) return root
+      if (holdsPackage(host, dir)) break
+    }
+    if (dirname(dir) === dir) break
+  }
+  return nearest(cwd, (dir) => holding(host, 'package-lock.json')(dir) && holding(host, 'package.json')(dir))
+}
+
+// npm's host: the machine's, but a libc npm finds only as glibc or musl, and none where it finds
+// neither.
+const npmHost = (npm, given) => {
+  const { libc, ...host } = target(given)
+  return { npm, ...host, ...(libc === 'glibc' || libc === 'musl' ? { libc } : {}) }
+}
+
+// What each package manager reproduced installs from: the kind of bundle it installs for; its
+// lockfile; the name a root package.json's packageManager pins it by, where one does; the version
+// reproduced where nothing pins one; the directory it installs cwd from, which holds the lockfile
+// (for the os given, where that changes it); whether a directory holding the lockfile is installed
+// from by itself, by the names in it and in each directory above it (`above()`, as listings); the
+// projects it finds in a view of that directory, for the machine given; the directory it installs
+// in each, and any it hides, as another package manager's; and the tree.
+const PACKAGE_MANAGERS = {
+  pnpm: {
+    kind: 'js',
+    lockfile: 'pnpm-lock.yaml',
+    pin: 'pnpm',
+    version: '10.33.4',
+    // pnpm installs from the workspace's root, whatever pnpm-lock.yaml is nearer.
+    root: (host, cwd) => nearest(cwd, holding(host, 'pnpm-workspace.yaml')) ?? nearest(cwd, holding(host, 'pnpm-lock.yaml')),
+    alone: async (names, above) => !(await above()).some((dir) => dir.includes('pnpm-workspace.yaml')),
+    projects: (view, pnpm) => findPnpmProjects({ project: view, host: { pnpm } }),
+    installs: 'node_modules',
+    build: (view, pnpm, _file, given) => buildPnpmTree({ project: view, host: { pnpm, ...target(given) }, cache: given?.cache }),
+  },
+  yarn1: {
+    kind: 'js',
+    lockfile: 'yarn.lock',
+    pin: 'yarn',
+    version: '1.22.22',
+    root: yarn1Root,
+    // A package.json above may declare it a workspace.
+    alone: async (names, above) => !(await above()).some((dir) => dir.includes('package.json')),
+    projects: (view) => findYarn1Workspaces({ project: view }),
+    installs: 'node_modules',
+    build: (view, yarn, file, given) => {
+      const { libc: _, ...host } = target({ ...given, libc: 'unknown' }) // yarn 1 matches no libc
+      return naming(file, buildYarn1Tree({ project: view, host: { yarn, ...host }, cache: given?.cache }))
+    },
+  },
+  npm: {
+    kind: 'js',
+    lockfile: 'package-lock.json',
+    // npm reads no packageManager, so nothing pins it.
+    version: '11.21.0',
+    root: npmRoot,
+    // A package.json above may declare it a workspace.
+    alone: async (names, above) => !(await above()).some((dir) => dir.includes('package.json')),
+    projects: (view, _npm, given) => findNpmWorkspaces({ project: view, os: target(given).os }),
+    installs: 'node_modules',
+    build: (view, npm, file, given) => naming(file, buildNpmTree({ project: view, host: npmHost(npm, given), cache: given?.cache })),
+  },
+  soldeer: {
+    kind: 'sol',
+    lockfile: 'soldeer.lock',
+    version: '0.12.0',
+    // Soldeer installs from the nearest directory holding foundry.toml or soldeer.toml, never above
+    // the git repository's root; without one, from that root, else from cwd.
+    root: (host, cwd) => nearest(cwd, (dir) => holding(host, 'foundry.toml', 'soldeer.toml')(dir) || isDir(join(dir, '.git'), host)) ?? cwd,
+    alone: async (names, above) => names.includes('foundry.toml') || names.includes('soldeer.toml') || !(await above()).some((dir) => dir.includes('foundry.toml') || dir.includes('soldeer.toml')),
+    projects: () => ['.'],
+    installs: 'dependencies',
+    hides: 'node_modules',
+    async build(view, soldeer, file, given) {
+      const tree = await naming(file, buildSoldeerTree({ project: view, host: { soldeer, os: given?.os ?? process.platform }, github: given?.client }))
+      settleSoldeer(view, tree.vfs, dirname(file))
+      return tree
+    },
+  },
+}
+
+// Their names.
+const PACKAGE_MANAGER_NAMES = Object.keys(PACKAGE_MANAGERS)
+
+// layOutTree's tree, with the host reading `project` through it (treeHost).
+export async function loadTree(options) {
+  const tree = await layOutTree(options)
+  return { ...tree, host: treeHost(tree, options.project) }
+}
+
+// The host reading `project`, a host of the project's Vfs, through `tree` (layOutTree's): the tree
+// serves what the package manager installs, and any file it writes beside it at the root.
+export function treeHost(tree, project) {
+  const pm = PACKAGE_MANAGERS[tree.packageManager]
+  const files = tree.vfs.readdir('/').filter((name) => tree.vfs.lstat(`/${name}`).type === 'file')
+  const installs = [...[...tree.projects].map((dir) => join(dir, pm.installs)), ...files]
+  return vfsHost(tree.vfs, { root: tree.root, outside: project, installs, hides: pm.hides })
+}
+
+// The lockfile `packageManager` installs from, e.g. 'pnpm-lock.yaml'.
+export const lockfileOf = (packageManager) => PACKAGE_MANAGERS[packageManager].lockfile
+
+// Whether `packageManager` installs a directory holding its lockfile from that directory itself, by
+// the names in it and, from `above()`, the names in each directory above it.
+export const installedAlone = (packageManager, names, above) => PACKAGE_MANAGERS[packageManager].alone(names, above)
+
+// The real path of the directory `host` holds `cwd` (a real path) installed from by `pm`, for `os`,
+// where it holds the lockfile; else null. That directory is cwd or above it, so none is without a
+// lockfile there.
+function rootOf(host, pm, cwd, os) {
+  if (nearest(cwd, holding(host, pm.lockfile)) === null) return null
+  const found = pm.root(host, cwd, os)
+  return found !== null && isFile(join(found, pm.lockfile), host) ? host.realpath(found) : null
+}
+
+// The real path of the directory the project `host` reads holds at `cwd` is installed from, for
+// `os`, which holds the lockfile and which a bundle's paths are relative to; null without one.
+export const lockfileRoot = (host, packageManager, cwd, os) => rootOf(host, PACKAGE_MANAGERS[packageManager], host.realpath(cwd), os)
+
+// The package managers that install node_modules.
+export const NODE_MODULES_MANAGERS = PACKAGE_MANAGER_NAMES.filter((name) => PACKAGE_MANAGERS[name].installs === 'node_modules')
+
+// The one of the package managers `names` that installs `cwd` in the project `host` reads from a
+// directory holding its lockfile, as lockfileRoot finds it for `os`: refused where none or more than
+// one does.
+export function detectPackageManager(name, host, cwd, { names = PACKAGE_MANAGER_NAMES, os } = {}) {
+  const real = host.realpath(cwd)
+  const found = names.flatMap((pm) => {
+    const root = rootOf(host, PACKAGE_MANAGERS[pm], real, os)
+    return root === null ? [] : [[pm, join(root, PACKAGE_MANAGERS[pm].lockfile)]]
+  })
+  if (found.length === 1) return found[0][0]
+  if (found.length === 0) throw noLockfile(name, real, names)
+  throw new Error(`${name}: no packageManager given, and more than one lockfile installs ${real}: ${found.map(([pm, file]) => `${file} (${pm})`).join(', ')}`)
+}
+
+// That none of the lockfiles of `names` installs `place`.
+export const noLockfile = (name, place, names = PACKAGE_MANAGER_NAMES) => new Error(`${name}: no packageManager given, and none of ${names.map((pm) => PACKAGE_MANAGERS[pm].lockfile).join(', ')} installs ${place}`)
+
+// Whether a directory's listing (listRepoDir's) holds `packageManager`'s lockfile.
+const listsLockfile = (listing, packageManager) => listing.some((entry) => entry.path === PACKAGE_MANAGERS[packageManager].lockfile && entry.type === 'blob')
+
+// The package managers whose lockfile `listings` (a directory's and those above it) hold, which are
+// the only ones that may install that directory.
+export const lockfilesListed = (listings) => PACKAGE_MANAGER_NAMES.filter((pm) => listings.some((listing) => listsLockfile(listing, pm)))
+
+// A `packageManagerVersion` is one of the package manager given, never of one detected.
+export function checkVersion(name, { packageManager, packageManagerVersion }) {
+  if (packageManagerVersion !== undefined && packageManager === undefined) throw new TypeError(`${name}: packageManagerVersion is only valid with packageManager`)
+}
+
+// The package manager of `names` the project `host` reads is built with at `cwd`: `packageManager`
+// if given, else the one detected for `os`.
+export function packageManagerFor(name, host, cwd, { packageManager, packageManagerVersion, os }, names = PACKAGE_MANAGER_NAMES) {
+  checkVersion(name, { packageManager, packageManagerVersion })
+  if (packageManager === undefined) return detectPackageManager(name, host, cwd, { names, os })
+  packageManagerOf(name, packageManager, names)
+  return packageManager
+}
+
+const KIND_LABELS = { js: 'JS', sol: 'Solidity' }
+
+// Refused where no package manager of `names` builds bundles of `kind`.
+export function checkKind(name, kind, names = PACKAGE_MANAGER_NAMES) {
+  if (names.some((pm) => PACKAGE_MANAGERS[pm].kind === kind)) return
+  const kinds = [...new Set(names.map((pm) => PACKAGE_MANAGERS[pm].kind))]
+  const builders = (of) => names.filter((pm) => PACKAGE_MANAGERS[pm].kind === of).join(', ')
+  throw new Error(names.length === 1
+    ? `${name}: only ${KIND_LABELS[kinds[0]]} bundles are built with ${names[0]}`
+    : `${name}: only ${kinds.map((of) => `${KIND_LABELS[of]} bundles (${builders(of)})`).join(' and ')} are built`)
+}
+
+// The PACKAGE_MANAGERS entry of `packageManager`, which has to be one of `names`.
+export function packageManagerOf(name, packageManager, names = PACKAGE_MANAGER_NAMES) {
+  if (!names.includes(packageManager)) throw new TypeError(`${name}: packageManager must be one of ${names.map((n) => `'${n}'`).join(', ')}`)
+  return PACKAGE_MANAGERS[packageManager]
+}
+
+// Anything read as a @preventive/vfs Vfs: a Vfs of another copy of the package is one too.
+export function checkVfs(name, vfs) {
+  for (const method of ['lstat', 'readdir', 'readFile', 'readlink']) {
+    if (typeof vfs?.[method] !== 'function') throw new TypeError(`${name}: vfs must be a @preventive/vfs Vfs holding the project`)
+  }
+}
+
+// -> { root, vfs, projects, stats, installed, packageManager, packageManagerVersion }, of the project
+// `project` holds that `cwd` is in, as `packageManager` installs it: the directory it installs from,
+// as a real path; a new Vfs holding the tree, rooted there; the directories of the projects it finds,
+// from there; deptree's counts, and what it installs, each by its `path` from there; and the version
+// reproduced, `packageManagerVersion` if given, else the one the root package.json's packageManager
+// pins, else the default. deptree reads the project through a view of `project`, which nothing is
+// written through. `client`, a @preventive/upstream/github.js client, is what a Soldeer git
+// dependency is fetched through (deptree's `github`); without one, a lockfile holding one is refused
+// before anything is fetched. `cache` (checkCache) is where npm packages' tarballs and version
+// documents are kept, which deptree fetches for pnpm, yarn1 and npm.
+async function layOutTree({ project, packageManager, cwd, packageManagerVersion, os, cpu, libc, client, cache }) {
+  const pm = PACKAGE_MANAGERS[packageManager]
+  const found = pm.root(project, cwd, os)
+  if (found === null) throw new Error(`no ${pm.lockfile} found in ${cwd} or any parent directory`)
+  const file = join(found, pm.lockfile)
+  if (!isFile(file, project)) throw new Error(`no ${pm.lockfile} found in ${found}, where ${cwd} is installed from`)
+  const pinned = pm.pin === undefined ? undefined : readJson(join(found, 'package.json'), project)?.packageManager
+  // Left out, deptree takes the one packageManager pins, and refuses another package manager.
+  const version = packageManagerVersion ?? (pinned === undefined ? pm.version : undefined)
+  const view = projectView(project, found)
+  const projects = new Set(pm.projects(view, version, { os, cpu, libc }))
+  const other = pm.kind === 'js' ? outsider(project, found, cwd, projects) : null
+  if (other !== null) throw new Error(`${file} does not install ${other}: it is none of the lockfile's projects`)
+  const { vfs, stats, installed } = await pm.build(view, version, file, { os, cpu, libc, client, cache })
+  return {
+    root: project.realpath(found),
+    vfs,
+    projects,
+    stats,
+    installed,
+    packageManager,
+    packageManagerVersion: version ?? (String(pinned).startsWith(`${pm.pin}@`) ? /^[^@]+@([^+]+)/u.exec(pinned)[1] : undefined),
+  }
+}
+
+// The root of the GitHub repository a git URL names, or undefined for another host's.
+const githubRoot = (url) => {
+  const github = parseGithubRepository(url)
+  return github === null ? undefined : { github, directory: '' }
+}
+
+// Each dependency of `bundle`, its paths from `root`, at the commit the tree (layOutTree's) installs
+// it from, where deptree names a full one: an npm package at its gitHead, which the registry's
+// version document names, a commit of the repository its own package.json names, so taken only
+// where the bundle records that one; a Soldeer git dependency at its lockfile's `rev`, the root of
+// the repository it is fetched from, where that is a GitHub one. Metadata, as `repo` is: the
+// publisher's word, held to no repository.
+export function pinCommits(bundle, root, { root: from, installed }) {
+  const byDir = new Map(installed.map((pkg) => [posix.relative(root, posix.join(from, pkg.path)), pkg]))
+  for (const [dir, info] of bundle.modules) {
+    const pkg = byDir.get(dir)
+    if (!isValidRepoField('commit', pkg?.commit)) continue
+    const repo = info.repo ?? githubRoot(pkg.git)
+    if (repo !== undefined) bundle.modules.set(dir, { ...info, repo: { ...repo, commit: pkg.commit } })
+  }
+}
+
+// fs.Stats#mode carries the file type above the permission bits a Vfs stat holds.
+const TYPE_BITS = { file: constants.S_IFREG, directory: constants.S_IFDIR, symlink: constants.S_IFLNK }
+
+const statsFor = (st) => ({
+  isFile: () => st.type === 'file',
+  isDirectory: () => st.type === 'directory',
+  isSymbolicLink: () => st.type === 'symlink',
+  mode: TYPE_BITS[st.type] | st.mode,
+})
+
+const dirent = (name, type) => ({
+  name,
+  isFile: () => type === 'file',
+  isDirectory: () => type === 'directory',
+  isSymbolicLink: () => type === 'symlink',
+})
+
+// A view over the Vfs's bytes, never a copy.
+const asBuffer = (bytes) => Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+
+// What `vfs` holds at `p` itself (the last link not followed), or null.
+function lstatOrNull(vfs, p) {
+  try {
+    return vfs.lstat(p)
+  } catch (err) {
+    if (NO_ENTRY.has(err?.code)) return null
+    throw err
+  }
+}
+
+const TREE = 'tree'
+const NONE = 'none'
+const OUTSIDE = 'outside'
+
+const invalidPackageConfig = (path, cause) => Object.assign(new Error(`Invalid package config ${path}.`, { cause }), { code: 'ERR_INVALID_PACKAGE_CONFIG' })
+
+// A `host` (@exodus/stasis-core/host) over `vfs`. Alone, every path is the Vfs's. With `root`, a
+// real path, and `outside`, a host of the rest, the Vfs's `/` stands for `root`, holding the tree
+// the package manager lays out there: each of the paths it `installs` (from `root`) is served from
+// the Vfs only, whatever `outside` holds there; a directory named `hides` anywhere, and any
+// node_modules out of `root`, is none; and everything else comes from `outside`. Symlinks cross
+// between the two both ways, so realpaths are walked here one link at a time, and a path is read as
+// the OS reads one: a `..` after a link leads up from where the link leads, never textually (Node's
+// own resolution, `findPackageJSON` and `resolve`, normalizes its paths first, as Node does). A
+// relative path is from `/`. What it reads is cached, as for a tree that holds still, unless `cache`
+// is false.
+export function vfsHost(vfs, { root, outside, installs = [], hides, cache = true } = {}) {
+  if (sep !== '/') throw new Error('The Vfs host is POSIX-only')
+  const disk = outside ?? null
+  const installed = new Set(installs)
+  // Paths here are absolute and normal.
+  const prefix = disk === null || root === '/' ? '/' : `${root}/`
+  // The root and the directories above it, whatever their names.
+  const towardRoot = (p) => p === root || prefix.startsWith(`${p}/`)
+  const zoneOf = (p) => {
+    if (disk === null) return TREE
+    if (!p.startsWith(prefix)) return hasNodeModulesSegment(p) && !towardRoot(p) ? NONE : OUTSIDE
+    const rel = p.slice(prefix.length)
+    for (let at = rel.indexOf('/'); at !== -1; at = rel.indexOf('/', at + 1)) {
+      if (installed.has(rel.slice(0, at))) return TREE
+    }
+    if (installed.has(rel)) return TREE
+    return hides !== undefined && rel.split('/').includes(hides) ? NONE : OUTSIDE
+  }
+  // The names of the installed paths in each directory holding one.
+  const installedIn = new Map()
+  for (const dir of disk === null ? [] : installed) {
+    const at = join(root, dirname(dir))
+    installedIn.set(at, [...(installedIn.get(at) ?? []), basename(dir)])
+  }
+  // A path in the tree, as the Vfs spells it.
+  const inVfs = disk === null ? (p) => p : (p) => `/${p.slice(prefix.length)}`
+  // `p` from `/`, as spelled: realpath resolves its `..` after the link before it.
+  const abs = (p) => (p.startsWith('/') ? p : `/${p}`)
+  const normal = (p) => resolve('/', p)
+  const memo = () => (cache ? new Map() : { get() {}, set() {} })
+
+  // `p` is a real path but for its last name; null when it exists and isn't a link.
+  const readlink = (p) => {
+    const zone = zoneOf(p)
+    if (zone === OUTSIDE) return disk.readlink(p)
+    if (zone === NONE) throw new VfsError('ENOENT', p)
+    const node = lstatOrNull(vfs, inVfs(p))
+    if (node === null) throw new VfsError('ENOENT', p)
+    return node.type === 'symlink' ? vfs.readlink(inVfs(p)) : null
+  }
+
+  const realCache = memo()
+  const realpath = (p, hops = 0) => {
+    if (p === '/') return '/'
+    const hit = realCache.get(p)
+    if (hit !== undefined) {
+      if (hit instanceof Error) throw hit
+      return hit
+    }
+    let result
+    try {
+      const parentReal = realpath(dirname(p), hops)
+      const name = basename(p)
+      // A `.` or `..` is taken in the real dir before it, which must be one.
+      if (name === '.' || name === '..') {
+        if (statOf(parentReal)?.isDirectory() !== true) throw new VfsError('ENOTDIR', p)
+        result = name === '.' ? parentReal : dirname(parentReal)
+        realCache.set(p, result)
+        return result
+      }
+      const candidate = join(parentReal, name)
+      const link = readlink(candidate)
+      if (link === null) {
+        result = candidate
+      } else {
+        if (hops >= 40) throw new VfsError('ELOOP', p)
+        result = realpath(link.startsWith('/') ? link : `${dirname(candidate)}/${link}`, hops + 1)
+      }
+    } catch (err) {
+      if (hops === 0 && (err.code === 'ENOENT' || err.code === 'ELOOP')) realCache.set(p, err)
+      throw err
+    }
+    realCache.set(p, result)
+    return result
+  }
+
+  const nodeOf = (real) => {
+    const node = lstatOrNull(vfs, inVfs(real))
+    if (node === null) throw new VfsError('ENOENT', real)
+    return node
+  }
+
+  // Node's findPackageJSON refuses a manifest that is no JSON object.
+  const manifestErrors = memo()
+  const checkManifest = (path) => {
+    let error = manifestErrors.get(path)
+    if (error === undefined) {
+      error = null
+      try {
+        const data = JSON.parse(packageJSONText(host.readFile(path)))
+        if (!isPlainObject(data)) error = invalidPackageConfig(path)
+      } catch (cause) {
+        error = invalidPackageConfig(path, cause)
+      }
+      manifestErrors.set(path, error)
+    }
+    if (error !== null) throw error
+  }
+
+  const statCache = memo()
+  const statOf = (real) => {
+    if (zoneOf(real) === OUTSIDE) return disk.stat(real)
+    let stats = statCache.get(real)
+    if (stats === undefined) {
+      const node = lstatOrNull(vfs, inVfs(real))
+      stats = node !== null && node.type !== 'symlink' ? statsFor(node) : null
+      statCache.set(real, stats)
+    }
+    return stats
+  }
+  // A path ending in `/` or `/.` names a directory, which path.resolve drops.
+  const namesDir = (p) => p.endsWith('/') || p.endsWith('/.')
+  const checkDir = (p, real) => {
+    if (namesDir(p) && statOf(real)?.isDirectory() === false) throw new VfsError('ENOTDIR', p)
+  }
+
+  const host = {
+    stat(p) {
+      let real
+      try {
+        real = realpath(abs(p))
+      } catch {
+        return null
+      }
+      const stats = statOf(real)
+      return stats !== null && namesDir(p) && !stats.isDirectory() ? null : stats
+    },
+    readFile(p) {
+      const real = realpath(abs(p))
+      checkDir(p, real)
+      if (zoneOf(real) === OUTSIDE) return disk.readFile(real)
+      if (nodeOf(real).type !== 'file') throw new VfsError('EISDIR', p)
+      return asBuffer(vfs.readFile(inVfs(real)))
+    },
+    readdir(p) {
+      const real = realpath(abs(p))
+      if (zoneOf(real) === TREE) {
+        if (nodeOf(real).type !== 'directory') throw new VfsError('ENOTDIR', p)
+        const dir = inVfs(real)
+        return vfs.readdir(dir).map((name) => dirent(name, vfs.lstat(join(dir, name)).type)).toSorted(byName)
+      }
+      // An outside directory shows the tree's installed paths in place of its own, and nothing that
+      // is none.
+      const out = disk.readdir(real).filter((d) => zoneOf(join(real, d.name)) === OUTSIDE)
+      for (const name of installedIn.get(real) ?? []) {
+        const node = lstatOrNull(vfs, inVfs(join(real, name)))
+        if (node !== null) out.push(dirent(name, node.type))
+      }
+      return out.toSorted(byName)
+    },
+    readlink(p) {
+      if (namesDir(p)) {
+        checkDir(p, realpath(abs(p)))
+        return null
+      }
+      p = abs(p)
+      // A `..` names a directory, as lstat takes it.
+      if (basename(p) === '..') {
+        realpath(p)
+        return null
+      }
+      return readlink(join(realpath(dirname(p)), basename(p)))
+    },
+    realpath(p) {
+      const real = realpath(abs(p))
+      checkDir(p, real)
+      return real
+    },
+    // As Node's: the nearest package.json above a file's real path, never out of a node_modules dir;
+    // one there that can't be read is refused (packageJSONStat).
+    findPackageJSON(p) {
+      let from = normal(p)
+      if (host.stat(from)?.isFile()) from = realpath(from)
+      for (let dir = dirname(from); basename(dir) !== 'node_modules'; dir = dirname(dir)) {
+        const candidate = join(dir, 'package.json')
+        if (packageJSONStat(host, candidate)?.isFile()) {
+          checkManifest(candidate)
+          return candidate
+        }
+        if (dirname(dir) === dir) break
+      }
+      return undefined
+    },
+    resolve(parentFile, specifier, conditions) {
+      return (resolver ?? createNodeResolver(host)).resolve(normal(parentFile), specifier, conditions)
+    },
+  }
+  const resolver = cache ? createNodeResolver(host) : undefined
+  return host
+}