@exodus/stasis 1.0.0-beta.3 → 1.0.0-beta.6

package/src/cmd/bundle.js

@@ -1,35 +1,43 @@
 import { isUtf8 } from 'node:buffer'
-import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync } from 'node:fs'
-import { dirname, extname, isAbsolute, join, posix, relative, resolve } from 'node:path'
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs'
+import { dirname, extname, join, posix, relative, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { brotliCompressSync, brotliDecompressSync } from 'node:zlib'
+import { brotliDecompressSync } from 'node:zlib'
 
 import { Bundle } from '@exodus/stasis-core/bundle'
 import { Lockfile } from '@exodus/stasis-core/lockfile'
-import { scan } from '../scan.js'
+import { importsTypescriptByOutputName, scan } from '../scan.js'
 import { createFieldResolver, resolveConditions } from '../resolve-fields.js'
+import { discoverTsconfig, isDir, loadTsconfigPaths, packageTsconfigPaths } from '../resolve-typescript.js'
 import { createMetroResolver } from '../metro-resolver.js'
 import { State } from '@exodus/stasis-core/state'
-import { brotliOptions } from '@exodus/stasis-core/brotli'
 import { sha512integrity } from '@exodus/stasis-core/state-util'
-import { findPackageMetadata, normalizeEntries, packageType, readJson, readModuleManifest } from '@exodus/stasis-core/bundle-util'
-import { RN_CORE_INCLUDE_FILES, assertRealPathWithinBase, classifyNativeCapture, isExcludedNativeDir, isExecutableFile, isNativeArtifact, isNativeManifest, isPodspec, isSkippedNativeWalkDir, moduleFileKey, parseResourcesOption, refineNativeCapture, splitNodeModulesPath } from '@exodus/stasis-core/util'
+import { detectRepo, findPackageMetadata, normalizeEntries, packageType, readJson, readModuleManifest, readPackageJson, readRegularFileOrNull } from '@exodus/stasis-core/bundle-util'
+import { RN_CORE_INCLUDE_FILES, assertRealPathWithinBase, classifyNativeCapture, hasNodeModulesSegment, isDotEnvFile, isExcludedNativeDir, isExecutableFile, isNativeArtifact, isNativeManifest, isPathWithin, isPodspec, isSkippedNativeWalkDir, moduleFileKey, moduleInfo, parseResourcesOption, posixPathEscapes, refineNativeCapture, relativeEscapes, splitNodeModulesPath, toPosix } from '@exodus/stasis-core/util'
+import { diskHost } from '@exodus/stasis-core/host'
 import {
+  SOLIDITY_PACKAGE_MANIFESTS,
+  SOLIDITY_ROOT_MANIFESTS,
   buildSolidityTree,
   collectSolidityFilesFromDisk,
-  readRemappingsFile,
+  discoverSolidityConfig,
+  expandSolidityEntries,
 } from '../loaders/solidity.js'
+import { decodeUtf8 } from '../loaders/solidity-ownership.js'
 import { buildBashTree, collectBashFilesFromDisk } from '../loaders/bash.js'
-import { buildRustTree, collectRustFilesFromDisk } from '../loaders/rust.js'
+import { boundaryOf, collectRustBundle, withinRealDir } from '../loaders/rust.js'
+import { createCargoContext } from '../loaders/cargo.js'
 import {
   bucketizePhpSources,
   buildPhpTree,
   collectPhpFilesFromDisk,
   loadComposerAutoload,
+  loadComposerPackages,
   loadLaravelProviderFiles,
 } from '../loaders/php.js'
+import { DEFAULT_BUNDLE_FILE, bundledSummary, packagesLabel, writeBundle, writeFile } from './output.js'
 
-const JS_EXTS = new Set(['.js', '.cjs', '.mjs', '.ts', '.cts', '.mts'])
+const JS_EXTS = new Set(['.js', '.cjs', '.mjs', '.ts', '.cts', '.mts', '.jsx', '.tsx'])
 const BASH_EXTS = new Set(['.sh', '.bash'])
 const RUST_EXTS = new Set(['.rs'])
 
@@ -53,7 +61,7 @@ const PHP_FORMAT = 'php'
 // escape cwd (e.g. via remapping), or "." when it is cwd itself.
 export function outermostDir(paths, cwd) {
   if (paths.length === 0) return '.'
-  const cwdAbs = posix.resolve(cwd.replaceAll(/\\/gu, '/'))
+  const cwdAbs = posix.resolve(toPosix(cwd))
   const absDirs = paths.map((p) => posix.dirname(posix.resolve(cwdAbs, p)))
   const partsList = absDirs.map((d) => d.split('/'))
   const common = []
@@ -80,50 +88,24 @@ function githubSlug(url) {
   return m ? `${m[1]}/${m[2]}` : null
 }
 
-// Parse `.gitmodules` (git-config INI) into Map<submodulePath, { name, branch }>,
-// github.com submodules only.
-function parseGithubSubmodules(baseDir) {
+// The github.com ones of `submodules` (readGitmodules), as Map<submodulePath, { name, branch }>.
+function githubSubmodules(submodules) {
   const byPath = new Map()
-  const text = readFileSyncOrNull(join(baseDir, '.gitmodules'))
-  if (!text) return byPath
-  let cur = null
-  const flush = () => {
-    if (cur?.path && cur?.url) {
-      const name = githubSlug(cur.url)
-      if (name) byPath.set(cur.path.replace(/\/+$/u, ''), { name, branch: cur.branch })
-    }
-    cur = null
+  for (const { path, url, branch } of submodules) {
+    const name = url && githubSlug(url)
+    if (name) byPath.set(path, { name, branch })
   }
-  for (const raw of text.split('\n')) {
-    const line = raw.trim()
-    if (line.startsWith('[')) {
-      flush()
-      cur = line.startsWith('[submodule') ? {} : null
-      continue
-    }
-    if (!cur) continue
-    const eq = line.indexOf('=')
-    if (eq === -1) continue
-    const key = line.slice(0, eq).trim()
-    if (key === 'path' || key === 'url' || key === 'branch') cur[key] = line.slice(eq + 1).trim()
-  }
-  flush()
   return byPath
 }
 
-function readFileSyncOrNull(file) {
-  try {
-    return readFileSync(file, 'utf8')
-  } catch {
-    return null
-  }
-}
-
 // Classify a Solidity file's dep bucket: Soldeer (`dependencies/<name>-<version>/`) or a
-// github submodule (`lib/`, via `.gitmodules`), else null to defer to the node_modules/
-// workspace logic.
-function makeSolidityClassifier(baseDir) {
-  const submodules = parseGithubSubmodules(baseDir)
+// github submodule (`lib/`, via the `.gitmodules` `ownership` read), else null to defer to the
+// node_modules/workspace logic. `ownership.assert` vets a package.json path before it is read
+// through `host`.
+function makeSolidityClassifier(baseDir, ownership, host) {
+  const submodules = githubSubmodules(ownership.submodules)
+  const check = ownership.assert
+  const versions = new Map() // a submodule's package.json version, read once
   return (path) => {
     if (path.startsWith('dependencies/')) {
       const seg = path.slice('dependencies/'.length).split('/')[0]
@@ -134,96 +116,126 @@ function makeSolidityClassifier(baseDir) {
     }
     for (const [sub, { name, branch }] of submodules) {
       if (path === sub || path.startsWith(`${sub}/`)) {
-        const pkg = readJson(join(baseDir, sub, 'package.json'))
-        return { bucketDir: sub, name, version: pkg?.version ?? branch ?? '0.0.0', ecosystem: 'github' }
+        if (!versions.has(sub)) versions.set(sub, readPackageJson(baseDir, moduleFileKey(sub, 'package.json'), { strict: true, check, host })?.version)
+        return { bucketDir: sub, name, version: versions.get(sub) ?? branch ?? '0.0.0', ecosystem: 'github' }
       }
     }
     return null
   }
 }
 
-// Minimal Cargo.toml reader: name/version from the `[package]` table; null when no name.
-function parseCargoToml(file) {
-  const text = readFileSyncOrNull(file)
-  if (!text) return null
-  const at = text.search(/^\[package\]\s*$/mu)
-  let body = text
-  if (at !== -1) {
-    const rest = text.slice(at)
-    const next = rest.slice(1).search(/^\[/mu)
-    body = next === -1 ? rest : rest.slice(0, next + 1)
-  }
-  const name = /^\s*name\s*=\s*"([^"]+)"/mu.exec(body)?.[1]
-  const version = /^\s*version\s*=\s*"([^"]+)"/mu.exec(body)?.[1]
-  return name ? { name, version: version ?? '0.0.0' } : null
+// A vendored crate's ecosystem, by where `cargo vendor` copied it from (vendoredFrom): a registry's
+// copy is `cargo`, which `stasis audit` asks OSV about as a crates.io crate's; a git checkout's is
+// `cargo-git`, and a copy with no `.cargo-checksum.json`, which could be either, `cargo-unknown`.
+// Neither is ever sent to a public advisory database: a private git dependency's name has no place
+// there, and a crates.io crate of the same name isn't it.
+const vendoredEcosystem = (from) => {
+  if (from === 'registry') return 'cargo'
+  return from === 'git' ? 'cargo-git' : 'cargo-unknown'
 }
 
-// Classify a Rust file: `cargo vendor` crates under `vendor/<dir>/` (tagged `cargo`), else
-// null to defer to the workspace logic.
-function makeRustClassifier(baseDir) {
+// Classify a Rust file by the nearest Cargo.toml `[package]`: a `cargo vendor`ed crate under the
+// vendor dir (`vendor/<dir>/`, or where .cargo/config.toml points) is a dependency (tagged
+// `cargo`, `cargo-git` or `cargo-unknown`: see vendoredEcosystem); any other package (the crate
+// itself, a workspace member reached through a `path` dependency) is first-party, so no
+// ecosystem. Null (no manifest above the file) defers to the package.json/placeholder logic.
+function makeRustClassifier(cargo) {
   return (path) => {
-    if (!path.startsWith('vendor/')) return null
-    const dir = path.slice('vendor/'.length).split('/')[0]
-    if (!dir) return null
-    const bucketDir = `vendor/${dir}`
-    const pkg = parseCargoToml(join(baseDir, bucketDir, 'Cargo.toml'))
-    return pkg ? { bucketDir, name: pkg.name, version: pkg.version, ecosystem: 'cargo' } : null
+    const pkg = cargo.packageInfo(path)
+    if (!pkg) return null
+    return { bucketDir: pkg.dir, name: pkg.name, version: pkg.version, ecosystem: cargo.isVendored(path) ? vendoredEcosystem(cargo.vendoredFrom(path)) : undefined }
+  }
+}
+
+// A file's key inside its bucket: the inverse of moduleFileKey.
+const fileInBucket = (bucketDir, path) => (bucketDir === '.' ? path : path.slice(bucketDir.length + 1))
+
+// A file of the bundle root (`realBase` its real path), its bytes, by project-relative path, or
+// null when it isn't a regular file there (a manifest the context saw may have gone since; a FIFO
+// would hang a read) or, with `within` a directory, doesn't really lie in it (a vendored crate's
+// manifest linked to a project file).
+function readFileWithinBase(baseDir, realBase, rel, within) {
+  try {
+    assertRealPathWithinBase(realBase, baseDir, rel)
+    if (!withinRealDir(baseDir, rel, within, { who: 'loader.cargo' })) return null
+    if (!statSync(join(baseDir, rel)).isFile()) return null
+    return readFileSync(join(baseDir, rel))
+  } catch (err) {
+    if (err.code === 'ENOENT' || err.code === 'EISDIR') return null
+    throw err
   }
 }
 
 // Project-relative paths in `sources` whose on-disk file carries a POSIX execute bit -- the
 // `executable` list both artifacts record. The State-driven path derives this in addFile; the
 // static builders never touch a State, so they stat here.
-function executableSources(baseDir, sources) {
+function executableSources(baseDir, sources, host) {
   const executable = new Set()
   for (const path of sources.keys()) {
-    if (isExecutableFile(join(baseDir, path))) executable.add(path)
+    if (isExecutableFile(join(baseDir, path), host)) executable.add(path)
   }
   return executable
 }
 
+// Bundles must be self-contained: throw on a missing entry or an unresolved `noun` (import, script,
+// module) of a `lang` bundle -- `missing`'s { spec, from }, with the `reason` it was refused if given.
+function assertSelfContained(lang, noun, entries, sources, missing) {
+  const issues = []
+  for (const entry of entries) {
+    if (!sources.has(entry)) issues.push(`Missing entry: ${entry}`)
+  }
+  for (const { spec, from, reason } of missing) {
+    issues.push(`Unresolved ${noun}: ${spec} from ${from}${reason ? ` (refused: ${reason})` : ''}`)
+  }
+  if (issues.length > 0) {
+    throw new Error(`${lang} bundle has unresolved ${noun}s:\n${issues.map((s) => `  ${s}`).join('\n')}`)
+  }
+}
+
 // Assemble a full-scope code Bundle shared by the non-JS bundlers. Files are bucketed by
 // nearest package.json (node_modules -> `npm`-tagged bucket, workspace -> its dir, none ->
 // "." with the placeholder identity); a node_modules file whose nearest package.json is the
-// workspace root is rejected, not mislabeled. `classifyDep(path)` optionally places a file
-// directly (non-node_modules ecosystems like Soldeer/github); null defers. `format` tags
-// every file, or pass `formats` (Map<path,format>) to tag per file. `resolutions` values are
+// workspace root is rejected, not mislabeled; `packageOf(path)` finds that package.json
+// (packageLookup by default, which walks past a malformed one). `classifyDep(path)` optionally
+// places a file directly (non-node_modules ecosystems like Soldeer/github); null defers. `format` tags
+// every file; `formats` (Map<path,format>) overrides it per file. `resolutions` values are
 // a flat target string or a Map<platform,target>; both round-trip untouched.
 function assembleCodeBundle({
-  baseDir, entries, sources, resolutions, workspaceName, workspaceVersion, format, formats, conditionKey, classifyDep,
+  baseDir, entries, sources, resolutions, workspaceName, workspaceVersion, format, formats, conditionKey, classifyDep, host,
+  packageOf = packageLookup(baseDir, { host }),
 }) {
   const modules = new Map()
-  const ensureBucket = (dir, name, version, bucketEcosystem) => {
-    if (!modules.has(dir)) {
-      modules.set(dir, bucketEcosystem === undefined
-        ? { name, version, files: Object.create(null) }
-        : { name, version, ecosystem: bucketEcosystem, files: Object.create(null) })
-    }
+  // `identity`'s name, version, ecosystem and repo (moduleInfo takes those alone).
+  const ensureBucket = (dir, identity) => {
+    if (!modules.has(dir)) modules.set(dir, moduleInfo({ ...identity, files: Object.create(null) }))
     return modules.get(dir)
   }
 
   for (const [path, content] of sources) {
     const dep = classifyDep?.(path)
     if (dep) {
-      ensureBucket(dep.bucketDir, dep.name, dep.version, dep.ecosystem)
-        .files[path.slice(dep.bucketDir.length + 1)] = content
+      ensureBucket(dep.bucketDir, dep).files[fileInBucket(dep.bucketDir, path)] = content
       continue
     }
-    const meta = findPackageMetadata(baseDir, path)
+    const meta = packageOf(path)
     const inNodeModules = splitNodeModulesPath(path) !== null
     if (meta) {
-      if (inNodeModules && !meta.pkgDir.includes('node_modules')) {
+      if (inNodeModules && !hasNodeModulesSegment(meta.pkgDir)) {
         throw new Error(`No package.json with name+version found for ${path}`)
       }
-      const rel = meta.pkgDir === '.' ? path : path.slice(meta.pkgDir.length + 1)
-      const bucketEcosystem = meta.pkgDir.includes('node_modules') ? 'npm' : undefined
-      ensureBucket(meta.pkgDir, meta.name, meta.version, bucketEcosystem).files[rel] = content
+      ensureBucket(meta.pkgDir, meta).files[fileInBucket(meta.pkgDir, path)] = content
     } else {
       if (inNodeModules) throw new Error(`No package.json with name+version found for ${path}`)
-      ensureBucket('.', workspaceName, workspaceVersion).files[path] = content
+      ensureBucket('.', { name: workspaceName, version: workspaceVersion }).files[path] = content
     }
   }
 
+  return codeBundle({ baseDir, entries, sources, modules, resolutions, format, formats, conditionKey, host })
+}
+
+// A full-scope code Bundle of `sources`, bucketed as `modules`: `format` tags every file, `formats`
+// (Map<path,format>) overrides it per file, and the `resolutions` edges are keyed under `conditionKey`.
+function codeBundle({ baseDir, entries, sources, modules, resolutions, format, formats, conditionKey, host }) {
   const formatsMap = new Map()
   for (const path of sources.keys()) formatsMap.set(path, formats?.get(path) ?? format)
 
@@ -233,7 +245,7 @@ function assembleCodeBundle({
 
   // Executable bits, straight off disk (a synthetic source with no file there is simply not
   // executable). Shell bundles lean on this most: `stasis extract` puts the +x back on the scripts.
-  const executable = executableSources(baseDir, sources)
+  const executable = executableSources(baseDir, sources, host)
 
   // Attribute files to the `bundle` consumer (static builders skip State's per-file tagging).
   return new Bundle({
@@ -246,45 +258,142 @@ function assembleCodeBundle({
   }).withReason('bundle')
 }
 
-// Build an in-memory Bundle from entry .sol files; `mappingFile` (foundry.toml/remappings.txt)
-// is parsed for remappings but not bundled.
-export async function buildSolidityBundle({ cwd = process.cwd(), entries, mappingFile } = {}) {
-  if (!Array.isArray(entries) || entries.length === 0) {
-    throw new Error('buildSolidityBundle: at least one entry .sol file is required')
+// Files never carried, whatever reads them: `.env` files, and Hardhat's config, which is code
+// (both however they're cased).
+const neverCarried = (rel) => isDotEnvFile(rel) || posix.basename(rel).toLowerCase().startsWith('hardhat.config.')
+
+// findPackageMetadata (with `options`) once per directory, the only thing its answer depends on.
+function packageLookup(baseDir, options) {
+  const byDir = new Map()
+  return (path) => {
+    const dir = posix.dirname(path)
+    if (!byDir.has(dir)) byDir.set(dir, findPackageMetadata(baseDir, path, options))
+    return byDir.get(dir)
   }
-  for (const e of entries) {
-    if (!e.endsWith('.sol')) throw new Error(`buildSolidityBundle: not a .sol file: ${e}`)
+}
+
+// The build-description files of a Solidity bundle (--manifests), as Map<path, text>, sorted:
+// `configFiles` (what discoverSolidityConfig read, whatever they're called), each of which must be
+// carried -- one outside the root, neverCarried, refused or gone is an error, as the bundle
+// couldn't reproduce the resolution without it -- plus the SOLIDITY_*_MANIFESTS that exist, for the
+// root and for each package dir `classifyDep`/`packageOf` places a bundled source in, but none
+// whose path `ownership` refuses (see solidityOwnership). Carried as written: whatever they hold
+// (an RPC URL with its API key, an Etherscan key, a URL's credentials) is in the bundle too, as
+// with --package-json. Read through `host`.
+function solidityManifests(baseDir, sources, configFiles, { classifyDep, packageOf, ownership, host }) {
+  const realBase = host.realpath(baseDir)
+  // `{ text }`, or `{ why }` it can't be carried (null: nothing is there). Read by the real path
+  // `ownership` resolved `rel` to, so what's carried is the file it vouched for.
+  const carry = (rel) => {
+    const { reason, real, outside } = ownership.of(rel)
+    if (reason) return { why: reason }
+    if (real === null) return { why: null }
+    if (outside) throw new Error(`Refusing to follow symlink escaping bundle root: ${rel} -> ${resolve(realBase, real)}`)
+    const buf = readRegularFileOrNull(join(realBase, real), rel, host)
+    if (buf === null) return { why: null } // a directory
+    return { text: decodeUtf8(buf, rel) }
+  }
+  const unreproducible = (rel, why) => new Error(`--manifests can't carry ${rel}, which the Solidity resolution read: ${why}`)
+  const out = new Map()
+  for (const rel of configFiles) {
+    // Absolute: the OS couldn't give its real path (see projectRelative).
+    if (posix.isAbsolute(rel)) throw unreproducible(rel, "its real path can't be resolved")
+    if (posixPathEscapes(rel)) throw unreproducible(rel, 'it lies outside the bundle root')
+    if (neverCarried(rel)) throw unreproducible(rel, '.env files and hardhat.config.* are never carried')
+    if (sources.has(rel)) continue
+    const { text, why } = carry(rel)
+    if (text === undefined) throw unreproducible(rel, why ?? 'it is gone')
+    out.set(rel, text)
+  }
+  const optional = new Set(SOLIDITY_ROOT_MANIFESTS)
+  for (const path of sources.keys()) {
+    const dirs = [classifyDep(path)?.bucketDir, packageOf(path)?.pkgDir].filter((d) => d !== undefined)
+    for (const dir of dirs) for (const name of SOLIDITY_PACKAGE_MANIFESTS) optional.add(moduleFileKey(dir, name))
+  }
+  for (const rel of optional) {
+    if (sources.has(rel) || out.has(rel)) continue
+    const { text, why } = carry(rel)
+    if (why) console.warn(`[stasis] Not carrying ${rel}: ${why}`)
+    if (text !== undefined) out.set(rel, text)
+  }
+  return new Map([...out.keys()].toSorted().map((rel) => [rel, out.get(rel)]))
+}
+
+// An entry `stasis bundle` takes for a directory: one that is, or an extensionless path that
+// doesn't exist (a project without `script/` still bundles with `src test script`).
+export const isDirEntry = (abs, host = diskHost) => isDir(abs, host) || (extname(abs) === '' && host.stat(abs) === null)
+
+// Whether `entry` (resolved against `cwd`) is a Solidity bundle's: a .sol file or a directory entry.
+export const isSolidityEntry = (entry, cwd = process.cwd(), host = diskHost) => entry.endsWith('.sol') || isDirEntry(resolve(cwd, entry), host)
+
+// What's wrong with `entries`' directory entries (resolved against `cwd`), or null: a directory
+// entry stands for the .sol files under it, so it goes with Solidity entries only; and entries
+// that are all missing extensionless paths are a mistyped file, not a project without those dirs.
+// `fetched` false: `host` is an empty tree standing in for one not fetched yet, which can't say
+// what is missing.
+export function directoryEntryError(entries, cwd = process.cwd(), host = diskHost, { fetched = true } = {}) {
+  const dirs = entries.filter((e) => isDirEntry(resolve(cwd, e), host))
+  const absent = fetched ? dirs.filter((e) => host.stat(resolve(cwd, e)) === null) : []
+  if (absent.length > 0 && absent.length === entries.length) return `no such file or directory: ${absent[0]}`
+  if (dirs.length === 0 || entries.every((e) => e.endsWith('.sol') || dirs.includes(e))) return null
+  return absent.length > 0
+    ? `no such file or directory: ${absent[0]}`
+    : `a directory entry is only supported for Solidity bundles (it stands for the .sol files under it): ${dirs[0]}`
+}
+
+// Build an in-memory Bundle from entry .sol files and directories (a directory stands for the .sol
+// files under it, as forge's src/test/script dirs and Hardhat's contracts dir do; a missing or
+// empty one is skipped). Imports resolve through the remappings the project's build uses
+// (discoverSolidityConfig: forge's discovery for a Foundry project); `mappingFile`
+// (foundry.toml/remappings.txt) pins them to exactly what it lists. An import is refused when it
+// reaches a non-.sol file or leaves the root, or when a dependency's reaches the project's own
+// files. Config files are read, and bundled only with `manifests` (see solidityManifests). `env`
+// supplies FOUNDRY_PROFILE / FOUNDRY_REMAPPINGS, reported when they apply. The project is read
+// through `host`.
+export async function buildSolidityBundle({ cwd = process.cwd(), entries, mappingFile, manifests = false, env = process.env, host = diskHost } = {}) {
+  if (!Array.isArray(entries) || entries.length === 0) {
+    throw new Error('buildSolidityBundle: at least one entry .sol file or directory is required')
   }
 
   const baseDir = resolve(cwd)
-  const remappings = mappingFile ? await readRemappingsFile(resolve(cwd, mappingFile)) : []
   const normalized = normalizeEntries(entries, cwd)
+  for (const e of normalized) {
+    if (!isSolidityEntry(e, baseDir, host)) throw new Error(`buildSolidityBundle: not a .sol file or directory: ${e}`)
+  }
+  const expanded = expandSolidityEntries(baseDir, normalized, host)
 
-  const sources = await collectSolidityFilesFromDisk(baseDir, normalized, remappings)
-  const { resolutions, missing } = buildSolidityTree(sources, { remappings, baseDir })
+  const { remappings, libs, ownership, files: configFiles, envUsed } = discoverSolidityConfig(baseDir, { mappingFile, env, host })
+  // The bundle doesn't record the environment, so say when it shaped the resolution.
+  if (envUsed.length > 0) console.warn(`[stasis] Solidity imports resolved with ${envUsed.join(', ')} from the environment`)
+  const sources = collectSolidityFilesFromDisk(baseDir, expanded, remappings, { libs, ownership, host })
+  const { resolutions, missing } = buildSolidityTree(sources, { remappings, baseDir, libs, ownership, host })
 
-  // Bundles must be self-contained: fail on a missing entry or unresolved import.
-  const issues = []
-  for (const entry of normalized) {
-    if (!sources.has(entry)) issues.push(`Missing entry: ${entry}`)
-  }
-  for (const { spec, from } of missing) {
-    issues.push(`Unresolved import: ${spec} from ${from}`)
-  }
-  if (issues.length > 0) {
-    throw new Error(`Solidity bundle has unresolved imports:\n${issues.map((s) => `  ${s}`).join('\n')}`)
+  assertSelfContained('Solidity', 'import', expanded, sources, missing)
+
+  const classifyDep = makeSolidityClassifier(baseDir, ownership, host)
+  const packageOf = packageLookup(baseDir, { strict: true, check: ownership.assert, host })
+  const bundled = new Map(sources)
+  const formats = new Map()
+  if (manifests) {
+    for (const [path, text] of solidityManifests(baseDir, sources, configFiles, { classifyDep, packageOf, ownership, host })) {
+      bundled.set(path, text)
+      formats.set(path, posix.basename(path) === 'package.json' ? 'json' : 'resource')
+    }
   }
 
   return assembleCodeBundle({
     baseDir,
-    entries: normalized,
-    sources,
+    entries: expanded,
+    sources: bundled,
     resolutions,
     workspaceName: SOLIDITY_WORKSPACE_NAME,
     workspaceVersion: SOLIDITY_WORKSPACE_VERSION,
     format: SOLIDITY_FORMAT,
+    formats,
     conditionKey: 'solidity',
-    classifyDep: makeSolidityClassifier(baseDir),
+    classifyDep,
+    packageOf,
+    host,
   })
 }
 
@@ -305,17 +414,8 @@ export async function buildBashBundle({ cwd = process.cwd(), entries } = {}) {
   const sources = await collectBashFilesFromDisk(baseDir, normalized)
   const { resolutions, missing } = buildBashTree(sources)
 
-  // Self-contained: fail on a missing entry or unresolved in-root script (external refs never reach `missing`).
-  const issues = []
-  for (const entry of normalized) {
-    if (!sources.has(entry)) issues.push(`Missing entry: ${entry}`)
-  }
-  for (const { spec, from } of missing) {
-    issues.push(`Unresolved script: ${spec} from ${from}`)
-  }
-  if (issues.length > 0) {
-    throw new Error(`Bash bundle has unresolved scripts:\n${issues.map((s) => `  ${s}`).join('\n')}`)
-  }
+  // Self-contained (external refs never reach `missing`).
+  assertSelfContained('Bash', 'script', normalized, sources, missing)
 
   return assembleCodeBundle({
     baseDir,
@@ -329,10 +429,22 @@ export async function buildBashBundle({ cwd = process.cwd(), entries } = {}) {
   })
 }
 
-// Build an in-memory Bundle from entry .rs files by walking `mod` declarations. An
-// unresolvable `mod` is fatal; `use crate::` edges are recorded best-effort (never widen
-// the file set, not gated).
-export async function buildRustBundle({ cwd = process.cwd(), entries } = {}) {
+// Build an in-memory Bundle from entry .rs files (crate roots) by walking `mod` declarations and
+// references to in-tree crates (the package's own lib, Cargo `path` deps, `cargo vendor`ed
+// crates). An unresolvable unconditional `mod` is fatal; path edges (`crate::`/`self::`/`super::`/
+// relative `use`s) are recorded best-effort and never widen the file set. Registry deps that
+// aren't vendored can't be bundled: they're reported, with a `cargo vendor` hint when there is no
+// `vendor/` dir at all. Each crate's features are resolved from the manifests (Cargo.toml +
+// Cargo.lock) the way `cargo build` of the entries' packages would, so `#[cfg(feature = …)]` code
+// that is off stays out; `cargo` takes them from `cargo metadata` instead (opt-in: it runs cargo).
+// `cargoFeatures` / `cargoNoDefaultFeatures` / `cargoAllFeatures` are cargo's `--features` /
+// `--no-default-features` / `--all-features` for the entries' packages, in either mode.
+// `cargoTarget` (a triple, or `host`) names the build's target: its cfgs, asked of rustc, decide
+// `#[cfg(unix)]`-style code and target-specific dependency tables, which are otherwise all kept.
+// `cargoManifests` also carries what describes each bundled package's build: its Cargo.toml (and
+// the workspace's), its build script -- walked like a crate root, so its modules and the in-tree
+// build-dependencies it reaches come along -- plus the root's Cargo.lock and .cargo/config.toml.
+export async function buildRustBundle({ cwd = process.cwd(), entries, cargo = false, cargoFeatures = [], cargoNoDefaultFeatures = false, cargoAllFeatures = false, cargoTarget = null, cargoManifests = false } = {}) {
   if (!Array.isArray(entries) || entries.length === 0) {
     throw new Error('buildRustBundle: at least one entry .rs file is required')
   }
@@ -343,18 +455,76 @@ export async function buildRustBundle({ cwd = process.cwd(), entries } = {}) {
   const baseDir = resolve(cwd)
   const normalized = normalizeEntries(entries, cwd)
 
-  const sources = await collectRustFilesFromDisk(baseDir, normalized)
-  const { resolutions, missing } = buildRustTree(sources)
-
-  const issues = []
-  for (const entry of normalized) {
-    if (!sources.has(entry)) issues.push(`Missing entry: ${entry}`)
+  // One Cargo context for the walk, the edge pass and the bucketing: manifests are read once, and
+  // the walk's crate resolution and the tree's feature decisions agree.
+  const cargoCtx = createCargoContext(baseDir, {
+    entries: normalized,
+    cargo,
+    features: cargoFeatures,
+    noDefaultFeatures: cargoNoDefaultFeatures,
+    allFeatures: cargoAllFeatures,
+    target: cargoTarget,
+  })
+  // `include_str!` / `include_bytes!` assets ride along as resources: the walk records their
+  // format. With `cargoManifests`, each package's build script is walked too (collectRustBundle).
+  const { sources, formats, tree } = await collectRustBundle(baseDir, normalized, { cargo: cargoCtx, buildScripts: cargoManifests })
+  if (cargoManifests) {
+    // Each bundled package's manifests, and its workspace's lockfile and cargo config, carried as
+    // written: whatever they hold (a registry token, a `git` URL's credentials) is in the bundle
+    // too, as with --package-json. A file that isn't UTF-8 text is refused, not altered.
+    const files = new Set()
+    for (const path of sources.keys()) for (const f of cargoCtx.buildFilesFor(path)) files.add(f.path)
+    const realBase = realpathSync(baseDir)
+    for (const rel of files) {
+      if (sources.has(rel)) continue
+      const buf = readFileWithinBase(baseDir, realBase, rel, boundaryOf(rel, cargoCtx))
+      if (buf === null) continue
+      cargoCtx.checkVendoredFile(rel, buf)
+      if (!isUtf8(buf)) throw new Error(`Rust manifest is not valid UTF-8: ${rel}`)
+      sources.set(rel, buf.toString('utf8'))
+      formats.set(rel, 'resource')
+    }
   }
-  for (const { spec, from } of missing) {
-    issues.push(`Unresolved module: ${spec} from ${from}`)
+  const { resolutions, missing, unresolvedCrates } = tree
+
+  assertSelfContained('Rust', 'module', normalized, sources, missing)
+
+  // Where the features the cfg decisions rest on come from: cargo's resolver, or -- something it
+  // takes missing -- a replay of the manifests, said so (a project without Cargo has neither).
+  const resolution = cargoCtx.resolution()
+  if (resolution.mode === 'replay' && normalized.some((e) => cargoCtx.packageInfo(e) !== null)) {
+    console.warn(`[stasis] Rust features from a replay of the manifests, not cargo's resolver: ${resolution.why}`)
+  }
+  // EXODUS_STASIS_DEBUG=1: show the feature resolution the cfg decisions came from, per package and
+  // context, so the replay, cargo's resolver and `cargo metadata` (which unifies dev/build deps
+  // like resolver 1) can be compared.
+  if (process.env.EXODUS_STASIS_DEBUG === '1' || process.env.EXODUS_STASIS_DEBUG === 'true') {
+    const mode = { cargo: "cargo's resolver", metadata: 'cargo metadata', replay: 'manifest replay' }[resolution.mode]
+    for (const context of ['target', 'host']) {
+      const resolved = [...cargoCtx.resolvedFeatures(context)].toSorted(([a], [b]) => (a < b ? -1 : 1))
+      console.warn(`[stasis] Rust features (${mode}, ${context}), ${resolved.length} package${resolved.length === 1 ? '' : 's'}:`)
+      for (const [dir, set] of resolved) {
+        const pkg = cargoCtx.packageInfo(moduleFileKey(dir, 'Cargo.toml'))
+        console.warn(`[stasis]   ${pkg?.name ?? '?'}@${pkg?.version ?? '?'} (${dir}): ${[...set].toSorted().join(', ') || '(none)'}`)
+      }
+    }
   }
-  if (issues.length > 0) {
-    throw new Error(`Rust bundle has unresolved modules:\n${issues.map((s) => `  ${s}`).join('\n')}`)
+
+  // A crate the code names that the bundle doesn't hold: a registry dependency that isn't vendored
+  // (or not in a version its requirement allows), a path or patch outside the bundle root (the
+  // loader warned of those), or a crate root the walk refused -- and any other dependency a bundled
+  // package's build links that nothing in-tree answers, however the code names it, if at all.
+  // Reported whatever the vendor dir holds; with none, the fix is one command.
+  const notLoaded = tree.wantedRoots.filter((r) => !sources.has(r)).map((r) => `${cargoCtx.packageInfo(r)?.name ?? r} (${r})`)
+  const bundledPackages = new Set([...sources.keys()].map((p) => cargoCtx.packageInfo(p)?.dir).filter((d) => d !== undefined))
+  const lacking = cargoCtx.lackingDependencies(bundledPackages, { buildScripts: cargoManifests })
+    .filter((d) => !unresolvedCrates.has(d.key))
+    .map((d) => `${d.name} (a dependency of ${d.from})`)
+  if (unresolvedCrates.size > 0 || notLoaded.length > 0 || lacking.length > 0) {
+    const names = [...new Set([...unresolvedCrates, ...notLoaded, ...lacking])].toSorted()
+    const shown = names.slice(0, 10).join(', ') + (names.length > 10 ? `, ... and ${names.length - 10} more` : '')
+    console.warn(`[stasis] ${names.length} crate${names.length === 1 ? '' : 's'} referenced but not in the bundle: ${shown}`)
+    if (!existsSync(join(baseDir, cargoCtx.vendorDir))) console.warn('[stasis] Registry dependencies are bundled only when vendored in-tree: run `cargo vendor` first.')
   }
 
   return assembleCodeBundle({
@@ -365,8 +535,9 @@ export async function buildRustBundle({ cwd = process.cwd(), entries } = {}) {
     workspaceName: RUST_WORKSPACE_NAME,
     workspaceVersion: RUST_WORKSPACE_VERSION,
     format: RUST_FORMAT,
+    formats,
     conditionKey: 'rust',
-    classifyDep: makeRustClassifier(baseDir),
+    classifyDep: makeRustClassifier(cargoCtx),
   })
 }
 
@@ -385,45 +556,30 @@ export async function buildPhpBundle({ cwd = process.cwd(), entries } = {}) {
   const baseDir = resolve(cwd)
   const normalized = normalizeEntries(entries, cwd)
   const autoload = loadComposerAutoload(baseDir)
+  // The Composer packages, of composer.lock (vendor/composer/installed.json held identical to it
+  // where both are), or of installed.json alone: read once, before anything is scanned.
+  const packages = loadComposerPackages(baseDir)
 
   // Laravel auto-discovers service providers rather than referencing them statically; seed
   // them as extra roots so their config/route/view files get bundled.
-  const providerRoots = loadLaravelProviderFiles(baseDir, autoload)
+  const providerRoots = loadLaravelProviderFiles(baseDir, autoload, packages)
 
   const sources = await collectPhpFilesFromDisk(baseDir, [...normalized, ...providerRoots], { autoload })
   const { resolutions, missing } = buildPhpTree(sources, { baseDir, autoload })
 
-  const issues = []
-  for (const entry of normalized) {
-    if (!sources.has(entry)) issues.push(`Missing entry: ${entry}`)
-  }
-  for (const { spec, from } of missing) {
-    issues.push(`Unresolved import: ${spec} from ${from}`)
-  }
-  if (issues.length > 0) {
-    throw new Error(`PHP bundle has unresolved imports:\n${issues.map((s) => `  ${s}`).join('\n')}`)
-  }
-
-  // Group per Composer package (vendor/<pkg>), not the node_modules bucketizer.
-  const modules = bucketizePhpSources(baseDir, sources, PHP_WORKSPACE_NAME, PHP_WORKSPACE_VERSION)
-
-  const formats = new Map()
-  for (const path of sources.keys()) formats.set(path, PHP_FORMAT)
-
-  // PHP includes don't vary by Node condition; key edges under "php", not the JS wildcard "*".
-  const importsForKey = new Map()
-  for (const [parent, specMap] of resolutions) importsForKey.set(parent, specMap)
-  const imports = new Map([['php', importsForKey]])
+  assertSelfContained('PHP', 'import', normalized, sources, missing)
 
-  // Attribute to the `bundle` consumer, like the other static builders.
-  return new Bundle({
-    config: { scope: 'full' },
-    entries: new Set(normalized),
-    modules,
-    formats,
-    imports,
-    executable: executableSources(baseDir, sources),
-  }).withReason('bundle')
+  return codeBundle({
+    baseDir,
+    entries: normalized,
+    sources,
+    // Group per Composer package (vendor/<pkg>), not the node_modules bucketizer.
+    modules: bucketizePhpSources(baseDir, sources, PHP_WORKSPACE_NAME, PHP_WORKSPACE_VERSION, packages),
+    resolutions,
+    format: PHP_FORMAT,
+    // PHP includes don't vary by Node condition; key edges under "php", not the JS wildcard "*".
+    conditionKey: 'php',
+  })
 }
 
 // Render a scanned file URL for diagnostics: project-relative when inside `baseDir`, else absolute.
@@ -432,15 +588,21 @@ export async function buildPhpBundle({ cwd = process.cwd(), entries } = {}) {
 // bundle itself stores (toRel), rather than leaking the machine's absolute paths into the message.
 function displayPath(url, baseDir) {
   const abs = fileURLToPath(url)
-  if (!baseDir) return abs
   const rel = relative(baseDir, abs)
-  return rel && !rel.startsWith('..') && !isAbsolute(rel) ? rel : abs
+  return rel && !relativeEscapes(rel) ? rel : abs
+}
+
+// One unresolved scan edge for diagnostics, naming the file --typescript would resolve it to when
+// the scan found one (Scan#typescriptCandidate).
+function describeUnresolved(u, show) {
+  const typescript = u.typescriptURL ? `; resolves to ${show(u.typescriptURL)} under --typescript` : ''
+  return `${u.kind} ${u.spec ?? '<dynamic>'} from ${show(u.parentURL)} (${u.reason}${typescript})`
 }
 
 // Classify scanner unresolved edges + parse errors into fatal (broken/divergent at load)
 // vs tolerated (a catchable runtime miss). Shared so the plain and --mainFields JS paths
 // gate identically. `baseDir` relativizes the paths in the emitted messages (see displayPath).
-function analyzeScanner(scanner, { baseDir } = {}) {
+function analyzeScanner(scanner, { baseDir }) {
   const show = (url) => displayPath(url, baseDir)
   // Static ESM import/export-from edges load eagerly before user code, so a failure there is
   // uncatchable (fatal); misses below a require()/dynamic-import() boundary are catchable (warn).
@@ -458,7 +620,7 @@ function analyzeScanner(scanner, { baseDir } = {}) {
   const fatalUnresolved = (u) => staticKinds.has(u.kind) && staticReachable.has(u.parentURL)
   const fatal = scanner.unresolved
     .filter((u) => fatalUnresolved(u))
-    .map((u) => `unresolved ${u.kind} ${u.spec} from ${show(u.parentURL)} (${u.reason})`)
+    .map((u) => `unresolved ${describeUnresolved(u, show)}`)
   // Fatal parse: an eagerly-linked module-family file, or any file the parser couldn't process.
   const fatalParse = (p) => staticReachable.has(p.url) && (p.format?.startsWith('module') === true || !p.recovered)
   for (const p of scanner.parseErrors) {
@@ -482,40 +644,56 @@ function analyzeScanner(scanner, { baseDir } = {}) {
 
 // Throw on fatal scan issues; warn on tolerated ones. `label` tags the scan pass; `baseDir`
 // relativizes the paths in the warnings (see displayPath), matching analyzeScanner's messages.
-function reportScanIssues({ fatal, tolerated, toleratedParse }, { label = '', baseDir } = {}) {
+function reportScanIssues({ fatal, tolerated, toleratedParse }, { label = '', baseDir }) {
   const where = label ? ` (${label})` : ''
   const show = (url) => displayPath(url, baseDir)
+  // The first 10 of `items` as indented lines (`line` renders one), then how many more there are.
+  const listed = (items, line = (s) => s) => {
+    const more = items.length > 10 ? `\n  ... and ${items.length - 10} more` : ''
+    return items.slice(0, 10).map((x) => `  ${line(x)}`).join('\n') + more
+  }
   if (fatal.length > 0) {
-    const shown = fatal.slice(0, 10).map((s) => `  ${s}`).join('\n')
-    const more = fatal.length > 10 ? `\n  ... and ${fatal.length - 10} more` : ''
-    throw new Error(`JS bundle would be broken at load time${where}:\n${shown}${more}`)
+    throw new Error(`JS bundle would be broken at load time${where}:\n${listed(fatal)}`)
   }
   if (tolerated.length > 0) {
-    const summary = tolerated
-      .slice(0, 10)
-      .map((u) => `  ${u.kind} ${u.spec ?? '<dynamic>'} from ${show(u.parentURL)} (${u.reason})`)
-      .join('\n')
-    const more = tolerated.length > 10 ? `\n  ... and ${tolerated.length - 10} more` : ''
-    console.warn(`[stasis] Bundle has ${tolerated.length} unresolved import(s)${where}; they will fall through at load time:\n${summary}${more}`)
+    const summary = listed(tolerated, (u) => describeUnresolved(u, show))
+    console.warn(`[stasis] Bundle has ${tolerated.length} unresolved import(s)${where}; they will fall through at load time:\n${summary}`)
   }
   if (toleratedParse.length > 0) {
-    const summary = toleratedParse
-      .slice(0, 10)
-      .map((p) => `  ${show(p.url)}: ${p.message}`)
-      .join('\n')
-    const more = toleratedParse.length > 10 ? `\n  ... and ${toleratedParse.length - 10} more` : ''
-    console.warn(`[stasis] Bundle has ${toleratedParse.length} file(s) with parse errors${where}; their recorded imports may be incomplete:\n${summary}${more}`)
+    const summary = listed(toleratedParse, (p) => `${show(p.url)}: ${p.message}`)
+    console.warn(`[stasis] Bundle has ${toleratedParse.length} file(s) with parse errors${where}; their recorded imports may be incomplete:\n${summary}`)
   }
 }
 
+// Normalize conditions (trim, drop empties) so a sloppy programmatic caller can't push a bogus
+// token into the resolver.
+const cleanConditions = (conditions) => conditions.map((c) => (typeof c === 'string' ? c.trim() : c)).filter(Boolean)
+
+// --typescript honours tsconfig `paths` aliases: an explicit --tsconfig's for every file (it must
+// exist), else those of the tsconfig.json beside each importing file's package.json
+// (packageTsconfigPaths, the project read as the State reads it, to `env`'s PROJECT_CWD; null
+// matcher = no aliases). Without --typescript they only hint a miss (Scan#typescriptCandidate), so a
+// config that doesn't load is none.
+function typescriptPathsFor(typescript, baseDir, tsconfig, host, env) {
+  if (typescript && tsconfig !== undefined) return loadTsconfigPaths(discoverTsconfig(baseDir, tsconfig, host), host)
+  return packageTsconfigPaths(baseDir, { host, lenient: !typescript, projectCwd: env.PROJECT_CWD })
+}
+
 // Build a JS/TS Bundle (in-memory) by statically scanning the require/import graph; no
 // user code is executed, and TS is stored verbatim (Node strips types at load). Scope comes
 // from stasis.config.json / `EXODUS_STASIS_SCOPE` unless `scope` overrides. `conditions` are
 // extra `exports`/`imports` conditions; on their own they don't honour legacy mainFields or
-// platform suffixes (see `--mainFields` / buildResolvedJsBundle).
-export async function buildJsBundle({ cwd = process.cwd(), entries, scope, conditions = [], jsx = false, flow = false, resources = [], packageJSON = false } = {}) {
+// platform suffixes (see `--mainFields` / buildResolvedJsBundle). `typescript` maps a failed
+// resolution to its on-disk TS source (tsc's rules; see resolve-typescript.js), honouring the
+// `paths` aliases of `tsconfig` (an explicit config path, default each package's tsconfig.json); it
+// is taken as given where the entries import TS sources by output name (importsTypescriptByOutputName).
+// Files are read through `host` (@exodus/stasis-core/host), the disk by default; EXODUS_STASIS_*
+// settings from `env`. With `innermostRoot`, the State is rooted at the innermost package at or
+// above cwd that holds every file the scan reaches (innermostRootOf), rather than at the project's
+// root above it, where that holds no stasis file of its own.
+export async function buildJsBundle({ cwd = process.cwd(), env = process.env, entries, scope, conditions = [], jsx = false, flow = false, typescript = false, tsconfig, resources = [], packageJSON = false, host = diskHost, innermostRoot = false } = {}) {
   if (!Array.isArray(entries) || entries.length === 0) {
-    throw new Error('buildJsBundle: at least one entry .js/.cjs/.mjs/.ts/.cts/.mts file is required')
+    throw new Error('buildJsBundle: at least one entry .js/.cjs/.mjs/.ts/.cts/.mts/.jsx/.tsx file is required')
   }
   for (const e of entries) {
     if (!JS_EXTS.has(extname(e))) throw new Error(`buildJsBundle: not a JS/TS file: ${e}`)
@@ -524,13 +702,14 @@ export async function buildJsBundle({ cwd = process.cwd(), entries, scope, condi
   const baseDir = resolve(cwd)
   const absEntries = entries.map((e) => resolve(baseDir, e))
 
-  // Normalize conditions (trim, drop empties) so a sloppy programmatic caller can't push a
-  // bogus token into the resolver.
-  const scanConditions = conditions.map((c) => (typeof c === 'string' ? c.trim() : c)).filter(Boolean)
+  const scanConditions = cleanConditions(conditions)
   // --resources: extensions/filenames carried as opaque assets instead of failing "can't carry".
   const resourceSet = parseResourcesOption('buildJsBundle', resources)
 
-  const scanner = scan(absEntries, { conditions: scanConditions, jsx, flow, resources: resourceSet })
+  typescript ||= importsTypescriptByOutputName(absEntries, host)
+  const typescriptPaths = typescriptPathsFor(typescript, baseDir, tsconfig, host, env)
+
+  const scanner = scan(absEntries, { conditions: scanConditions, jsx, flow, typescript, typescriptPaths, resources: resourceSet, host })
 
   // Fail closed where the bundle is guaranteed broken at load; warn on catchable misses (see analyzeScanner).
   reportScanIssues(analyzeScanner(scanner, { baseDir }), { baseDir })
@@ -538,8 +717,25 @@ export async function buildJsBundle({ cwd = process.cwd(), entries, scope, condi
   // Materialise via a non-preload State: addFile bucketizes + records sources/formats,
   // addImport replays the edge map; serialize emits the runtime loader's v1 layout.
   // bundle:'replace' skips reading any on-disk stasis.code.br (bundle:'add' would leak stale
-  // entries); lock:'ignore' tolerates a pre-existing lockfile without consuming it.
-  const state = new State(baseDir, { bundle: 'replace', lock: 'ignore', ...(scope ? { scope } : {}) })
+  // entries); lock:'ignore' tolerates a pre-existing lockfile without consuming it; and it is never
+  // written, so it claims no write target.
+  const stateOptions = { bundle: 'replace', lock: 'ignore', ...(scope ? { scope } : {}), host, claim: false }
+  let state = new State(baseDir, { ...stateOptions, env })
+  // A root holding a stasis file is the project's own choice, whose config the build takes.
+  if (innermostRoot && !STASIS_ROOT_FILES.some((file) => host.stat(join(state.root, file)) !== null)) {
+    const root = innermostRootOf(baseDir, [...scanner.files.keys()].map((url) => host.realpath(fileURLToPath(url))), state.root, host)
+    // The State's walk up from cwd stops at PROJECT_CWD, as it does where yarn sets it.
+    if (root !== state.root) state = new State(baseDir, { ...stateOptions, env: { ...env, PROJECT_CWD: root } })
+  }
+  // Named here rather than as the State's bare assertion: a stasis file in a directory below the
+  // project's root (a stray stasis.code.br there, say) roots the State at it, out of the files above.
+  for (const url of scanner.files.keys()) {
+    const file = fileURLToPath(url)
+    if (!relativeEscapes(relative(state.root, file))) continue
+    const markers = STASIS_ROOT_FILES.filter((name) => host.stat(join(state.root, name)) !== null)
+    const rootedBy = markers.length === 0 ? '' : ` (rooted there by its ${markers.join(' and ')}, which can be removed if stale)`
+    throw new Error(`buildJsBundle: ${relative(baseDir, file)} is outside the project root at ${relative(baseDir, state.root) || '.'}${rootedBy}`)
+  }
   for (const [url, info] of scanner.files) {
     // A resource carries bytes only: addFile derives resource vs resource:base64 from the content
     // and stores it under `resources` (a resource can't be an entry, so no isEntry).
@@ -583,26 +779,39 @@ export async function buildJsBundle({ cwd = process.cwd(), entries, scope, condi
   return state
 }
 
-// Extensions probed when a resolved target names none. Limited to what a source bundle can
-// carry (scan's RESOLVABLE_EXTS) so the resolver never resolves a file the bundle would reject.
-// --jsx widens this to the JSX/TSX extensions (mirroring scan's jsx-gated RESOLVABLE_EXTS) so an
-// extensionless `import './Foo'` can land on Foo.jsx/Foo.tsx, as Metro's sourceExts do. `.js`/`.ts`
-// keep their existing precedence (base order preserved as a subsequence); collisions across the
-// added extensions are rare and, like the base list, don't track the project's real Metro order.
-const SOURCE_EXTS = ['js', 'json', 'ts']
-const SOURCE_EXTS_JSX = ['js', 'jsx', 'json', 'ts', 'tsx']
+// The files that root a State in the directory holding one (state.js's discovery).
+const STASIS_ROOT_FILES = ['stasis.config.json', 'stasis.lock.json', DEFAULT_BUNDLE_FILE]
+
+// The innermost directory at or above `baseDir`, up to `root`, holding every one of `files` (real
+// paths) and a package.json with a name, which a State can be rooted at; `root` where none below it
+// does. One without a name, such as a `{"type":"module"}` marker, is no root: the State takes such a
+// file's package to be the named one above it, which it then must hold.
+function innermostRootOf(baseDir, files, root, host) {
+  for (let dir = baseDir; dir !== root && dirname(dir) !== dir; dir = dirname(dir)) {
+    if (files.every((file) => isPathWithin(dir, file)) && readPackageJson(dir, 'package.json', { host })?.name !== undefined) return dir
+  }
+  return root
+}
+
+// Extensions probed when a resolved target names none, in Metro's default sourceExts order.
+// Limited to what a source bundle can carry (scan's RESOLVABLE_EXTS) so the resolver never
+// resolves a file the bundle would reject; an extensionless `import './Foo'` can land on
+// Foo.jsx/Foo.tsx, as it does under Metro. Like Metro's default, this doesn't track a project's
+// own sourceExts.
+const SOURCE_EXTS = ['js', 'jsx', 'json', 'ts', 'tsx']
 // React Native preset mainFields for `--metro` (which also sets the RN conditions + platform suffixes).
 const METRO_MAIN_FIELDS = ['react-native', 'browser', 'main']
 // Synthetic path for the empty module a browser/react-native `false` redirect resolves to,
 // carried as a real empty CJS file so the edge points at attestable bytes.
 const EMPTY_MODULE_PATH = '.stasis/empty-module.js'
 
-// Recursively collect files under a native ios/android dir, skipping build output and symlinks
-// (cycle/escape hazard). Absolute paths into `out`.
-function walkNativeDir(dirAbs, out) {
+// Recursively collect the files under `dirAbs` whose name `keep` takes, skipping build output,
+// symlinks (cycle/escape hazard) and, directly in `dirAbs`, the dirs `skipAtRoot` names. Absolute
+// paths into `out`.
+function walkNative(dirAbs, out, host, keep, skipAtRoot) {
   let entries
   try {
-    entries = readdirSync(dirAbs, { withFileTypes: true })
+    entries = host.readdir(dirAbs)
   } catch {
     return // absent -- nothing for this platform
   }
@@ -610,69 +819,81 @@ function walkNativeDir(dirAbs, out) {
     if (ent.isSymbolicLink()) continue
     const full = join(dirAbs, ent.name)
     if (ent.isDirectory()) {
-      if (!isSkippedNativeWalkDir(ent.name)) walkNativeDir(full, out)
-    } else if (ent.isFile() && !isNativeArtifact(ent.name)) {
+      if (!isSkippedNativeWalkDir(ent.name) && !skipAtRoot?.(ent.name)) walkNative(full, out, host, keep)
+    } else if (ent.isFile() && keep(ent.name)) {
       out.push(full)
     }
   }
 }
 
-// Recursively collect podspec-load manifests (isNativeManifest) under `dirAbs`. RN's own
-// podspecs live in scattered subdirs a root-only scan would miss, so recurse fully.
-function collectNativeManifests(dirAbs, out, atRoot = false) {
-  let entries
-  try {
-    entries = readdirSync(dirAbs, { withFileTypes: true })
-  } catch {
-    return
-  }
-  for (const ent of entries) {
-    if (ent.isSymbolicLink()) continue
-    const full = join(dirAbs, ent.name)
-    if (ent.isDirectory()) {
-      if (!isSkippedNativeWalkDir(ent.name) && !(atRoot && isExcludedNativeDir(ent.name))) collectNativeManifests(full, out)
-    } else if (ent.isFile() && isNativeManifest(ent.name)) {
-      out.push(full)
-    }
-  }
-}
+// The files of a native ios/android dir: all but build artifacts.
+const isNativeSource = (name) => !isNativeArtifact(name)
 
 // Native source files a bundled RN dep contributes to the app's native build (podspecs +
 // ios/android sources). Manifests are kept only when the package is actually native (podspec
 // or ios/android dir), else a JS-only dep's package.json would be pulled in. Deduped absolute paths.
-function nativeModuleFiles(pkgAbs) {
+function nativeModuleFiles(pkgAbs, host) {
+  // Podspec-load manifests: RN's own podspecs live in scattered subdirs a root-only scan would miss,
+  // so recurse fully.
   const manifests = []
-  collectNativeManifests(pkgAbs, manifests, true)
-  const hasIos = existsSync(join(pkgAbs, 'ios'))
-  const hasAndroid = existsSync(join(pkgAbs, 'android'))
+  walkNative(pkgAbs, manifests, host, isNativeManifest, isExcludedNativeDir)
+  const hasIos = host.stat(join(pkgAbs, 'ios')) !== null
+  const hasAndroid = host.stat(join(pkgAbs, 'android')) !== null
   if (!hasIos && !hasAndroid && !manifests.some((f) => isPodspec(f))) return []
   const out = [...manifests]
-  if (hasIos) walkNativeDir(join(pkgAbs, 'ios'), out)
-  if (hasAndroid) walkNativeDir(join(pkgAbs, 'android'), out)
+  if (hasIos) walkNative(join(pkgAbs, 'ios'), out, host, isNativeSource)
+  if (hasAndroid) walkNative(join(pkgAbs, 'android'), out, host, isNativeSource)
   return [...new Set(out)]
 }
 
+// The built-in field/suffix resolver (resolve-fields.js) the legacy-field build resolves with on
+// `platform` (null for --mainFields), its `mainFields` (Metro's under --metro), and the conditions
+// it adds to Node's: --metro asserts the RN conditions (+ browser on web); --mainFields carries the
+// user's --conditions.
+export function fieldResolverFor(platform, { mainFields, metro = false, conditions = [], typescript = false, typescriptPaths = null, host = diskHost }) {
+  const extras = metro ? ['react-native', ...(platform === 'web' ? ['browser'] : [])] : conditions
+  const fields = metro ? METRO_MAIN_FIELDS : mainFields
+  const resolver = createFieldResolver({
+    mainFields: fields,
+    platform,
+    preferNative: platform !== null && platform !== 'web',
+    sourceExts: SOURCE_EXTS,
+    conditions: resolveConditions('commonjs', extras),
+    // Opt into Metro's package-entry browser-field quirks only on the --metro path.
+    metro,
+    // --typescript: tsc's mapping, inside the field resolver (the scanner's own fallback
+    // only backs the built-in resolver). Unreachable under --metro-resolver
+    // (classifyEntries rejects the combination -- metro-resolver can't substitute).
+    typescript,
+    typescriptPaths,
+    host,
+  })
+  return { extras, mainFields: fields, resolver }
+}
+
 // Build a JS/TS Bundle + companion Lockfile via the legacy-field resolver (`--mainFields`/
 // `--metro`). Scanned once per platform; each edge is recorded flat when the platforms that
 // have it agree, or as a `{ platform: target }` map where they diverge. Returns { bundle, lockfile }.
-async function buildResolvedJsBundle({ cwd = process.cwd(), entries, mainFields, platforms, conditions = [], metro = false, metroResolver = false, jsx = false, flow = false, resources = [], packageJSON = false }) {
+async function buildResolvedJsBundle({ cwd = process.cwd(), env = process.env, entries, mainFields, platforms, conditions = [], metro = false, metroResolver = false, jsx = false, flow = false, typescript = false, tsconfig, resources = [], packageJSON = false, host = diskHost }) {
   const baseDir = resolve(cwd)
   const absEntries = entries.map((e) => resolve(baseDir, e))
   const normalized = normalizeEntries(entries, cwd)
 
   const toRel = (abs) => {
-    const rel = relative(baseDir, abs).split(/[\\/]/u).join('/')
-    if (rel.startsWith('..') || isAbsolute(rel)) {
+    const rel = toPosix(relative(baseDir, abs))
+    if (relativeEscapes(rel)) {
       throw new Error(`Bundle would reach a file outside the project root: ${abs}`)
     }
     return rel
   }
 
-  // Normalize conditions (drop stray ''/whitespace) so a sloppy caller can't push a bogus token into the resolver.
-  const scanConditions = conditions.map((c) => (typeof c === 'string' ? c.trim() : c)).filter(Boolean)
+  const scanConditions = cleanConditions(conditions)
 
-  // Under --jsx the resolver probes .jsx/.tsx too, matching scan's jsx-widened carryable set.
-  const sourceExts = jsx ? SOURCE_EXTS_JSX : SOURCE_EXTS
+  // Taken as given where the entries import TS sources by output name, but under --metro-resolver,
+  // which has no tsc mapping (classifyEntries rejects --typescript there).
+  if (!metroResolver) typescript ||= importsTypescriptByOutputName(absEntries, host)
+  // --typescript's tsconfig `paths` matcher, shared by every per-platform resolver below.
+  const typescriptPaths = typescriptPathsFor(typescript, baseDir, tsconfig, host, env)
   // --resources: extensions/filenames carried as opaque assets instead of failing "can't carry".
   const resourceSet = parseResourcesOption('buildResolvedJsBundle', resources)
 
@@ -685,30 +906,26 @@ async function buildResolvedJsBundle({ cwd = process.cwd(), entries, mainFields,
   let usesEmpty = false
 
   for (const platform of platforms) {
-    // --metro asserts the RN conditions (+ browser on web); --mainFields (platform null) carries the user's --conditions.
-    const extras = metro ? ['react-native', ...(platform === 'web' ? ['browser'] : [])] : scanConditions
+    const field = fieldResolverFor(platform, { mainFields, metro, conditions: scanConditions, typescript, typescriptPaths, host })
+    const { extras } = field
     // --metro --metro-resolver delegates to the project's own metro-resolver for byte-for-byte Metro
-    // fidelity; otherwise the built-in field/suffix resolver (resolve-fields.js) reproduces it.
-    // metro-resolver derives default/require|import/platform conditions itself, so it takes only the
-    // extra `react-native` condition (browser comes from its per-platform map, keyed on `web`).
+    // fidelity; otherwise the built-in field/suffix resolver reproduces it. metro-resolver derives
+    // default/require|import/platform conditions itself, so it takes only the extra `react-native`
+    // condition (browser comes from its per-platform map, keyed on `web`).
     const resolver = metroResolver
-      ? createMetroResolver({ projectDir: baseDir, platform, sourceExts, mainFields, conditionNames: ['react-native'] })
-      : createFieldResolver({
-          mainFields,
-          platform,
-          preferNative: platform !== null && platform !== 'web',
-          sourceExts,
-          conditions: resolveConditions('commonjs', extras),
-          // Opt into Metro's package-entry browser-field quirks only on the --metro path.
-          metro,
-        })
-    const scanner = scan(absEntries, { conditions: extras, resolve: resolver, jsx, flow, resources: resourceSet })
+      ? createMetroResolver({ projectDir: baseDir, platform, sourceExts: SOURCE_EXTS, mainFields, conditionNames: ['react-native'], host })
+      : field.resolver
+    // Without --typescript, the field resolver --typescript would build names the file a miss would
+    // land on: a hint in the unresolved report, never an edge (see Scan#typescriptCandidate).
+    const typescriptResolve = typescript || metroResolver ? null : fieldResolverFor(platform, { mainFields, metro, conditions: scanConditions, typescript: true, typescriptPaths, host }).resolver
+    const scanner = scan(absEntries, { conditions: extras, resolve: resolver, typescriptResolve, jsx, flow, resources: resourceSet, host })
     reportScanIssues(analyzeScanner(scanner, { baseDir }), { baseDir, label: platform ?? 'mainFields' })
 
     const platformKey = platform ?? '*' // '*' is a private placeholder for the single mainFields pass; it never unflattens
     for (const [url, info] of scanner.files) {
-      const rel = toRel(fileURLToPath(url))
-      reached.add(fileURLToPath(url))
+      const abs = fileURLToPath(url)
+      const rel = toRel(abs)
+      reached.add(abs)
       if (info.resource) resourceRels.add(rel)
       formatsByRel.set(rel, info.format)
       for (const e of info.edges) {
@@ -729,33 +946,36 @@ async function buildResolvedJsBundle({ cwd = process.cwd(), entries, mainFields,
   // stored as UTF-8 text, so non-UTF-8 bytes would diverge from the hashed bytes -- reject them.
   const sources = new Map()
   const integrities = new Map()
-  const realBase = realpathSync(baseDir)
+  // Carry `rel`: `content` in the bundle as `format`, the integrity of its bytes `buf` in the lockfile.
+  const put = (rel, content, format, buf) => {
+    sources.set(rel, content)
+    formatsByRel.set(rel, format)
+    integrities.set(rel, sha512integrity(buf))
+  }
+  // A resource carries bytes, not source: UTF-8 verbatim or base64 when binary, tagged with the
+  // byte-derived format (here and in the --metro native capture below).
+  const putResource = (rel, buf) => (isUtf8(buf) ? put(rel, buf.toString('utf8'), 'resource', buf) : put(rel, buf.toString('base64'), 'resource:base64', buf))
+  const realBase = host.realpath(baseDir)
   for (const abs of reached) {
     const rel = toRel(abs)
     // Security: the field resolver returns the lexical path, so an in-tree-named symlink
     // escaping the root would slip past toRel's textual check -- realpath and fail closed.
-    assertRealPathWithinBase(realBase, baseDir, rel)
-    const buf = readFileSync(abs)
+    assertRealPathWithinBase(realBase, baseDir, rel, host)
+    const buf = host.readFile(abs)
     if (resourceRels.has(rel)) {
-      // A resource carries bytes, not JS source: store UTF-8 verbatim or base64 when binary, and
-      // tag the byte-derived format (same shape as the --metro native capture below).
-      const utf8 = isUtf8(buf)
-      sources.set(rel, utf8 ? buf.toString('utf8') : buf.toString('base64'))
-      formatsByRel.set(rel, utf8 ? 'resource' : 'resource:base64')
+      putResource(rel, buf)
     } else {
       if (!isUtf8(buf)) throw new Error(`JS bundle source is not valid UTF-8: ${rel}`)
-      sources.set(rel, buf.toString('utf8'))
+      // Its format is the scan's.
+      put(rel, buf.toString('utf8'), formatsByRel.get(rel), buf)
     }
-    integrities.set(rel, sha512integrity(buf))
   }
   if (usesEmpty) {
     // Refuse to shadow a real reached file sitting at the reserved empty-module path.
     if (formatsByRel.has(EMPTY_MODULE_PATH)) {
       throw new Error(`Bundle needs the reserved empty-module path ${EMPTY_MODULE_PATH}, but the project has a real file there`)
     }
-    sources.set(EMPTY_MODULE_PATH, '')
-    formatsByRel.set(EMPTY_MODULE_PATH, 'commonjs')
-    integrities.set(EMPTY_MODULE_PATH, sha512integrity(Buffer.alloc(0)))
+    put(EMPTY_MODULE_PATH, '', 'commonjs', Buffer.alloc(0))
   }
 
   // --metro also carries each bundled dependency's native build-input surface (ios/android
@@ -766,8 +986,9 @@ async function buildResolvedJsBundle({ cwd = process.cwd(), entries, mainFields,
     for (const abs of reached) {
       // Follow the CODE/module graph only: a package reached solely for an asset (--resources) is
       // not a linked native dependency, so it must not drag in its ios/android surface.
-      if (resourceRels.has(toRel(abs))) continue
-      const nm = splitNodeModulesPath(toRel(abs))
+      const rel = toRel(abs)
+      if (resourceRels.has(rel)) continue
+      const nm = splitNodeModulesPath(rel)
       if (nm) pkgDirs.add(nm.dir)
     }
     for (const pkgDir of [...pkgDirs].toSorted()) {
@@ -776,74 +997,65 @@ async function buildResolvedJsBundle({ cwd = process.cwd(), entries, mainFields,
       // so walk its whole tree for native source (React/, ReactCommon/, ReactAndroid/, ...) the same
       // way a native dep's ios/android surface is walked; every other dep gets its ios/android + podspecs.
       const isRnCore = pkgDir.slice(pkgDir.lastIndexOf('node_modules/') + 'node_modules/'.length) === 'react-native'
-      const files = isRnCore ? [] : nativeModuleFiles(pkgAbs)
-      if (isRnCore) walkNativeDir(pkgAbs, files)
+      const files = isRnCore ? [] : nativeModuleFiles(pkgAbs, host)
+      if (isRnCore) walkNative(pkgAbs, files, host, isNativeSource)
       for (const abs of files) {
         const rel = toRel(abs)
         if (sources.has(rel)) continue
-        assertRealPathWithinBase(realBase, baseDir, rel)
+        assertRealPathWithinBase(realBase, baseDir, rel, host)
         // classifyNativeCapture (shared with the StasisMetro plugin) returns action skip/code/resource with a format tag.
         const byName = classifyNativeCapture(rel)
         if (byName.action === 'skip') continue
-        const buf = readFileSync(abs)
+        const buf = host.readFile(abs)
         // Byte-level rules (prebuilt binaries, binary plists) -- see refineNativeCapture.
         const { action, format } = refineNativeCapture(byName, rel, buf, resourceSet)
         if (action === 'skip') continue
-        const utf8 = isUtf8(buf)
         if (action === 'code') {
-          if (!utf8) throw new Error(`native source is not valid UTF-8: ${rel}`)
-          sources.set(rel, buf.toString('utf8'))
-          formatsByRel.set(rel, format)
+          if (!isUtf8(buf)) throw new Error(`native source is not valid UTF-8: ${rel}`)
+          put(rel, buf.toString('utf8'), format, buf)
         } else {
-          sources.set(rel, utf8 ? buf.toString('utf8') : buf.toString('base64'))
-          formatsByRel.set(rel, utf8 ? 'resource' : 'resource:base64')
+          putResource(rel, buf)
         }
-        integrities.set(rel, sha512integrity(buf))
       }
       // RN core's `.js` build scripts the classify loop skips (Metro-owned by extension, but never in
       // the graph): force-include as code so the podspec/Ruby that invokes them at pod-install resolves.
       if (isRnCore) {
         for (const file of RN_CORE_INCLUDE_FILES) {
           const abs = join(pkgAbs, file)
-          if (!existsSync(abs)) continue
+          if (host.stat(abs) === null) continue
           const rel = toRel(abs)
           if (sources.has(rel)) continue
-          assertRealPathWithinBase(realBase, baseDir, rel)
-          const buf = readFileSync(abs)
+          assertRealPathWithinBase(realBase, baseDir, rel, host)
+          const buf = host.readFile(abs)
           if (!isUtf8(buf)) throw new Error(`native source is not valid UTF-8: ${rel}`)
-          sources.set(rel, buf.toString('utf8'))
-          formatsByRel.set(rel, packageType(abs) === 'module' ? 'module' : 'commonjs')
-          integrities.set(rel, sha512integrity(buf))
+          put(rel, buf.toString('utf8'), packageType(abs, host) === 'module' ? 'module' : 'commonjs', buf)
         }
       }
     }
   }
 
   // --package-json: fold each bundled module's package.json into `sources` (and its integrity into
-  // the companion lockfile) even when the scan never reached it. Buckets are the same ones
-  // assembleCodeBundle derives (findPackageMetadata -> pkgDir, else the '.' workspace bucket);
-  // findPackageMetadata is memoized per directory so a package's many files don't each re-walk to the
-  // same manifest. readModuleManifest applies the read/validate rules shared with the State path
-  // (containment, UTF-8-aborts); no identity check here -- these buckets are all fresh from disk.
+  // the companion lockfile) even when the scan never reached it. Buckets are the ones
+  // assembleCodeBundle derives, from the same `packageOf` (findPackageMetadata -> pkgDir, else the
+  // '.' workspace bucket; packageLookup memoizes it per directory so a package's many files don't
+  // each re-walk to the same manifest). readModuleManifest applies the read/validate rules shared
+  // with the State path (containment, UTF-8-aborts); no identity check here -- these buckets are
+  // all fresh from disk.
+  const packageOf = packageLookup(baseDir, { host })
   if (packageJSON) {
-    const metaByDir = new Map()
     const pkgDirs = new Set()
     for (const abs of reached) {
       const rel = toRel(abs)
-      const dir = dirname(rel)
-      if (!metaByDir.has(dir)) metaByDir.set(dir, findPackageMetadata(baseDir, rel))
-      const meta = metaByDir.get(dir)
+      const meta = packageOf(rel)
       if (meta) pkgDirs.add(meta.pkgDir)
       else if (!splitNodeModulesPath(rel)) pkgDirs.add('.')
     }
     for (const pkgDir of pkgDirs) {
       const rel = moduleFileKey(pkgDir, 'package.json')
       if (sources.has(rel)) continue
-      const buf = readModuleManifest({ baseDir, realBase, rel })
+      const buf = readModuleManifest({ baseDir, realBase, rel, host })
       if (!buf) continue
-      sources.set(rel, buf.toString('utf8'))
-      formatsByRel.set(rel, 'json')
-      integrities.set(rel, sha512integrity(buf))
+      put(rel, buf.toString('utf8'), 'json', buf)
     }
   }
 
@@ -862,7 +1074,7 @@ async function buildResolvedJsBundle({ cwd = process.cwd(), entries, mainFields,
     resolutions.set(parent, specMap)
   }
 
-  const rootPkg = readJson(join(baseDir, 'package.json')) ?? {}
+  const rootPkg = readJson(join(baseDir, 'package.json'), host) ?? {}
   const bundle = assembleCodeBundle({
     baseDir,
     entries: normalized,
@@ -872,6 +1084,8 @@ async function buildResolvedJsBundle({ cwd = process.cwd(), entries, mainFields,
     workspaceName: rootPkg.name ?? 'workspace',
     workspaceVersion: rootPkg.version ?? '0.0.0',
     conditionKey: '*',
+    host,
+    packageOf,
   })
 
   // The companion lockfile mirrors the bundle, swapping file content for its integrity.
@@ -879,7 +1093,7 @@ async function buildResolvedJsBundle({ cwd = process.cwd(), entries, mainFields,
   for (const [dir, m] of bundle.modules) {
     const files = Object.create(null)
     for (const rel of Object.keys(m.files)) files[rel] = integrities.get(moduleFileKey(dir, rel))
-    lockModules.set(dir, { name: m.name, version: m.version, ...(m.ecosystem === undefined ? {} : { ecosystem: m.ecosystem }), files })
+    lockModules.set(dir, moduleInfo({ ...m, files }))
   }
   const lockfile = new Lockfile({
     config: bundle.config,
@@ -894,23 +1108,36 @@ async function buildResolvedJsBundle({ cwd = process.cwd(), entries, mainFields,
   return { bundle, lockfile }
 }
 
-// Classify entries into their single shared language and check option applicability; `name` prefixes errors.
-function classifyEntries(name, { entries, mappingFile, scope, lockfile, conditions, mainFields, platforms, metro, metroResolver, jsx, flow, resources, packageJSON }) {
+// Classify entries into their single shared language and check option applicability; `name` prefixes
+// errors. A directory entry (resolved against `cwd`, on `host`) stands for the .sol files under it: Solidity only.
+function classifyEntries(name, { cwd = process.cwd(), entries, mappingFile, manifests, scope, lockfile, conditions, mainFields, platforms, metro, metroResolver, jsx, flow, typescript, tsconfig, resources, packageJSON, cargo, cargoFeatures, cargoNoDefaultFeatures, cargoAllFeatures, cargoTarget, cargoManifests, host = diskHost, fetched }) {
   if (!Array.isArray(entries) || entries.length === 0) {
     throw new Error(`${name}: at least one entry file is required`)
   }
+  const dirError = directoryEntryError(entries, cwd, host, { fetched })
+  if (dirError !== null) throw new Error(`${name}: ${dirError}`)
   let kind
-  if (entries.every((e) => e.endsWith('.sol'))) kind = 'sol'
+  if (entries.every((e) => isSolidityEntry(e, cwd, host))) kind = 'sol'
   else if (entries.every((e) => e.endsWith('.php'))) kind = 'php'
   else if (entries.every((e) => JS_EXTS.has(extname(e)))) kind = 'js'
   else if (entries.every((e) => BASH_EXTS.has(extname(e)))) kind = 'bash'
   else if (entries.every((e) => RUST_EXTS.has(extname(e)))) kind = 'rust'
   else {
-    throw new Error(`${name}: entries must all be .sol, all be .php, all be .js/.cjs/.mjs/.ts/.cts/.mts, all be .sh/.bash, or all be .rs (no mixing)`)
+    throw new Error(`${name}: entries must all be .sol, all be .php, all be .js/.cjs/.mjs/.ts/.cts/.mts/.jsx/.tsx, all be .sh/.bash, or all be .rs (no mixing)`)
   }
   if (mappingFile && kind !== 'sol') {
     throw new Error(`${name}: --mapping is only valid for .sol bundles`)
   }
+  // --manifests carries the Solidity build's description files (foundry.toml, remappings.txt, ...).
+  if (manifests && kind !== 'sol') {
+    throw new Error(`${name}: --manifests is only valid for .sol bundles`)
+  }
+  // --cargo runs `cargo metadata` for the Rust feature/dependency resolution and the --cargo-*
+  // flags steer that resolution; nothing else reads Cargo.
+  if (kind !== 'rust') {
+    const given = { cargo, 'cargo-features': Array.isArray(cargoFeatures) && cargoFeatures.length > 0, 'cargo-no-default-features': cargoNoDefaultFeatures, 'cargo-all-features': cargoAllFeatures, 'cargo-target': cargoTarget, 'cargo-manifests': cargoManifests }
+    for (const [flag, on] of Object.entries(given)) if (on) throw new Error(`${name}: --${flag} is only valid for Rust bundles`)
+  }
   if (scope !== undefined && kind !== 'js') {
     throw new Error(`${name}: --scope is only valid for JS bundles`)
   }
@@ -925,6 +1152,14 @@ function classifyEntries(name, { entries, mappingFile, scope, lockfile, conditio
   if (flow && kind !== 'js') {
     throw new Error(`${name}: --flow is only valid for JS bundles`)
   }
+  // --typescript maps JS-output specifiers to their on-disk TS sources; only the JS resolvers do it.
+  if (typescript && kind !== 'js') {
+    throw new Error(`${name}: --typescript is only valid for JS bundles`)
+  }
+  // --tsconfig names the config whose `paths` aliases --typescript honours; meaningless without it.
+  if (tsconfig !== undefined && !typescript) {
+    throw new Error(`${name}: --tsconfig is only valid with --typescript`)
+  }
   // --resources carries allowlisted assets reached through the JS import graph; JS-only. The list
   // is validated (parseResourcesOption) in the builders, but reject a code extension here too so a
   // typo surfaces with the command name rather than deep in the scan.
@@ -936,7 +1171,8 @@ function classifyEntries(name, { entries, mappingFile, scope, lockfile, conditio
   if (mainFields !== undefined && kind !== 'js') {
     throw new Error(`${name}: --mainFields is only valid for JS bundles`)
   }
-  // --jsx toggles the scanner's JSX parsing for the .js family; only JS entries are scanned.
+  // --jsx toggles the scanner's JSX parsing for the .js family (.jsx/.tsx need no flag); only JS
+  // entries are scanned.
   if (jsx && kind !== 'js') {
     throw new Error(`${name}: --jsx is only valid for JS bundles`)
   }
@@ -974,6 +1210,10 @@ function classifyEntries(name, { entries, mappingFile, scope, lockfile, conditio
   if (metroResolver && !metro) {
     throw new Error(`${name}: --metro-resolver is only valid with --metro`)
   }
+  // metro-resolver has no TS extension substitution, so --typescript would silently not apply -- reject it.
+  if (typescript && metroResolver) {
+    throw new Error(`${name}: --typescript is not supported with --metro-resolver (the project's metro-resolver doesn't substitute .js -> .ts)`)
+  }
   // The field resolver always emits full-scope, so --scope with --mainFields/--metro would be silently ignored -- reject it.
   if (scope !== undefined && (mainFields !== undefined || metro)) {
     throw new Error(`${name}: --scope is not supported with --mainFields or --metro`)
@@ -981,38 +1221,101 @@ function classifyEntries(name, { entries, mappingFile, scope, lockfile, conditio
   return kind
 }
 
-// Programmatic equivalent of `stasis bundle`: build and return an in-memory Bundle without
-// writing to disk. Files are attributed to the `bundle` consumer. Option applicability
-// (--mapping/.sol, --scope|--conditions|--mainFields|--metro|--jsx|--flow/JS) is enforced by classifyEntries.
-export async function buildBundle({ cwd = process.cwd(), entries, mappingFile, scope, conditions, mainFields, platforms, metro, metroResolver, jsx = false, flow = false, resources = [], packageJSON = false } = {}) {
-  const kind = classifyEntries('buildBundle', { entries, mappingFile, scope, conditions, mainFields, platforms, metro, metroResolver, jsx, flow, resources, packageJSON })
-  if (kind === 'sol') return buildSolidityBundle({ cwd, entries, mappingFile })
-  if (kind === 'php') return buildPhpBundle({ cwd, entries })
-  if (kind === 'bash') return buildBashBundle({ cwd, entries })
-  if (kind === 'rust') return buildRustBundle({ cwd, entries })
+// A JS bundle as `stasis bundle` builds it: by the legacy-field resolver with `mainFields` or
+// `metro`, whose per-platform edges and synthetic empty module a State can't hold, else through a
+// State, which detects the bundle's repo itself. `root` is the directory the bundle's paths are
+// relative to: cwd for the resolver's, the State's root for the State's.
+// -> { bundle, lockfile: () => Lockfile, stateBuilt, root }
+async function buildJs({ mainFields, platforms, metro, metroResolver, innermostRoot, ...options }) {
   if (metro || mainFields !== undefined) {
-    const { bundle } = await buildResolvedJsBundle({
-      cwd,
-      entries,
-      mainFields: metro ? METRO_MAIN_FIELDS : mainFields,
-      platforms: metro ? platforms : [null],
-      conditions,
-      metro: Boolean(metro),
-      metroResolver: Boolean(metroResolver),
-      jsx,
-      flow,
-      resources,
-      packageJSON,
-    })
-    return bundle
-  }
-  const state = await buildJsBundle({ cwd, entries, scope, conditions, jsx, flow, resources, packageJSON })
+    const built = await buildResolvedJsBundle({ ...options, mainFields: metro ? METRO_MAIN_FIELDS : mainFields, platforms: metro ? platforms : [null], metro: Boolean(metro), metroResolver: Boolean(metroResolver) })
+    return { bundle: built.bundle, lockfile: () => built.lockfile, stateBuilt: false, root: resolve(options.cwd) }
+  }
+  const state = await buildJsBundle({ ...options, innermostRoot })
   // Stamp the `bundle` consumer (the static build carries none).
-  return state.sourceBundle.withReason('bundle')
+  return { bundle: state.sourceBundle.withReason('bundle'), lockfile: () => state.lockfile, stateBuilt: true, root: state.root }
 }
 
-// Default output: stasis.code.br, the same name `stasis run --bundle=load` discovers, so the two round-trip with no flags.
-const DEFAULT_BUNDLE_FILE = 'stasis.code.br'
+// The bundle of `kind` (classifyEntries') built from buildBundle's options.
+// -> { bundle, lockfile: () => Lockfile, stateBuilt } (the last two of a JS bundle alone)
+async function buildOfKind(kind, { cwd, env, entries, mappingFile, manifests, scope, conditions, mainFields, platforms, metro, metroResolver, jsx, flow, typescript, tsconfig, resources, packageJSON, cargo, cargoFeatures, cargoNoDefaultFeatures, cargoAllFeatures, cargoTarget, cargoManifests }) {
+  if (kind === 'sol') return { bundle: await buildSolidityBundle({ cwd, env, entries, mappingFile, manifests }) }
+  if (kind === 'php') return { bundle: await buildPhpBundle({ cwd, entries }) }
+  if (kind === 'bash') return { bundle: await buildBashBundle({ cwd, entries }) }
+  if (kind === 'rust') return { bundle: await buildRustBundle({ cwd, entries, cargo, cargoFeatures, cargoNoDefaultFeatures, cargoAllFeatures, cargoTarget, cargoManifests }) }
+  return buildJs({ cwd, env, entries, scope, conditions, mainFields, platforms, metro, metroResolver, jsx, flow, typescript, tsconfig, resources, packageJSON })
+}
+
+// buildVfsBundle's checks of `options`, which hold before anything is fetched (`host` the
+// project's, or an empty tree's with `fetched: false`): no metro-resolver, which reads the disk;
+// `generate` only for JS.
+// -> the kind of bundle its entries make
+export function checkVfsOptions(name, options) {
+  const kind = classifyEntries(name, options)
+  if (options.metroResolver) throw new Error(`${name}: metroResolver is not supported`)
+  const { generate = [] } = options
+  if (!Array.isArray(generate) || generate.some((step) => step !== 'prisma')) throw new TypeError(`${name}: generate must be an array of 'prisma'`)
+  if (generate.length > 0 && kind !== 'js') throw new Error(`${name}: --generate is only valid for JS bundles`)
+  return kind
+}
+
+// A bundle from the lockfile of the project held in `vfs` alone (@exodus/stasis/vfs-bundle), `cwd` a
+// path there: buildBundle's JS options, resolved through the node_modules 'pnpm', 'yarn1' or 'npm'
+// would install, or its Solidity options, through the dependencies folder 'soldeer' would install; with
+// nothing read from disk but tarballs and zips, nor from the environment: a Solidity bundle is
+// built with foundry.toml's default profile, whatever FOUNDRY_PROFILE or remappings one sets, and no
+// EXODUS_STASIS_* setting is read. `repo`, the informational `{ github, directory, commit }`,
+// is the Bundle's, over what is detected in the Vfs as `stasis bundle` detects it on disk. `os`,
+// `cpu` and `libc` are loadNodeModules'. Without a `packageManager`, it is the one whose lockfile
+// installs cwd, where only one's does. `innermostRoot` is buildJsBundle's, for a JS bundle built
+// through a State. `generate: ['prisma']` writes each project's Prisma Client into the laid-out
+// tree before the scan, leaving `vfs` as it is (vfs-bundle/prisma.js). `client`, a
+// @preventive/upstream/github.js client, is what a Soldeer git dependency is fetched through; without
+// one, a soldeer.lock holding one is refused, naming deptree's `github`, before anything is fetched.
+// `root` is the directory in the Vfs the bundle's paths are relative to: cwd, or for a JS bundle
+// built through a State, the State's root, which is at or above it.
+// -> { bundle: Bundle, lockfile: Lockfile (of a JS bundle), stats, packageManager, root }
+export async function buildVfsBundle({ vfs, packageManager, cwd = '/', packageManagerVersion, os, cpu, libc, repo, innermostRoot = false, generate = [], client, ...options } = {}) {
+  const { checkKind, checkTarget, checkVfs, loadTree, packageManagerFor, packageManagerOf, treeHost, vfsHost } = await import('../vfs-bundle/tree.js')
+  checkVfs('buildVfsBundle', vfs)
+  checkTarget('buildVfsBundle', { os, cpu, libc })
+  // Checked as the Bundle checks it, before anything is fetched.
+  if (repo !== undefined) repo = new Bundle({ repo }).repo
+  const project = vfsHost(vfs)
+  // A real path, as every file the scan reaches is.
+  cwd = project.realpath(posix.resolve('/', cwd))
+  packageManager = packageManagerFor('buildVfsBundle', project, cwd, { packageManager, packageManagerVersion, os })
+  const pm = packageManagerOf('buildVfsBundle', packageManager)
+  checkKind('buildVfsBundle', checkVfsOptions('buildVfsBundle', { ...options, generate, cwd, host: project }), [packageManager])
+  // Checked before anything is fetched: an entry out of what the tree installs is in the project
+  // already. (A Solidity entry that is no .sol file is a directory, skipped where it is missing.)
+  for (const entry of options.entries) {
+    const abs = posix.resolve(cwd, entry)
+    if (pm.kind === 'sol' && !abs.endsWith('.sol')) continue
+    if (!posix.relative(cwd, abs).split('/').includes(pm.installs) && project.stat(abs) === null) throw new Error(`entry not found: ${abs}`)
+  }
+  const tree = await loadTree({ project, packageManager, cwd, packageManagerVersion, os, cpu, libc, client })
+  let { host } = tree
+  if (generate.includes('prisma')) {
+    const { generatePrismaClients, withPrismaClients } = await import('../vfs-bundle/prisma.js')
+    const outputs = await generatePrismaClients({ host, root: tree.root, projects: tree.projects })
+    if (outputs.length > 0) host = treeHost(tree, vfsHost(withPrismaClients(vfs, outputs)))
+  }
+  const args = { ...options, cwd, host, env: {} }
+  const { bundle, lockfile, stateBuilt, root } = pm.kind === 'sol' ? { bundle: await buildSolidityBundle(args), root: cwd } : await buildJs({ ...args, innermostRoot })
+  if (repo !== undefined) bundle.repo = repo
+  // Rooted at cwd, where `stasis bundle` detects its repo.
+  else if (!stateBuilt) bundle.repo ??= detectRepo(cwd, host)
+  return { bundle, lockfile: lockfile?.(), stats: tree.stats, packageManager, root }
+}
+
+// Programmatic equivalent of `stasis bundle`: build and return an in-memory Bundle without
+// writing to disk. Files are attributed to the `bundle` consumer. Option applicability
+// (--mapping|--manifests/.sol, --scope|--conditions|--mainFields|--metro|--jsx|--flow|--typescript/JS) is enforced by classifyEntries.
+export async function buildBundle({ cwd = process.cwd(), env = process.env, entries, mappingFile, manifests = false, scope, conditions, mainFields, platforms, metro, metroResolver, jsx = false, flow = false, typescript = false, tsconfig, resources = [], packageJSON = false, cargo = false, cargoFeatures = [], cargoNoDefaultFeatures = false, cargoAllFeatures = false, cargoTarget = null, cargoManifests = false } = {}) {
+  const options = { cwd, env, entries, mappingFile, manifests, scope, conditions, mainFields, platforms, metro, metroResolver, jsx, flow, typescript, tsconfig, resources, packageJSON, cargo, cargoFeatures, cargoNoDefaultFeatures, cargoAllFeatures, cargoTarget, cargoManifests }
+  return (await buildOfKind(classifyEntries('buildBundle', options), options)).bundle
+}
 
 // Run `stasis bundle`: build a brotli-compressed bundle and write it to `output`
 // (stasis.code.br by default, `-` for stdout; the summary goes to stderr so it never
@@ -1021,47 +1324,33 @@ const DEFAULT_BUNDLE_FILE = 'stasis.code.br'
 // `stasis run --lock=frozen` (which doesn't replay them) fails closed -- pair it with
 // `--bundle=load` or replay the conditions. `add` unions the fresh build into the bundle
 // already on disk (strict; a conflicting file throws) and can't target stdout.
-export async function bundleCommand({ cwd = process.cwd(), entries, mappingFile, output, scope, lockfile, conditions, mainFields, platforms, metro, metroResolver, jsx = false, flow = false, resources = [], packageJSON = false, brotliQuality, add = false } = {}) {
-  const kind = classifyEntries('bundleCommand', { entries, mappingFile, scope, lockfile, conditions, mainFields, platforms, metro, metroResolver, jsx, flow, resources, packageJSON })
+export async function bundleCommand({ cwd = process.cwd(), env = process.env, entries, mappingFile, manifests = false, output, scope, lockfile, conditions, mainFields, platforms, metro, metroResolver, jsx = false, flow = false, typescript = false, tsconfig, resources = [], packageJSON = false, cargo = false, cargoFeatures = [], cargoNoDefaultFeatures = false, cargoAllFeatures = false, cargoTarget = null, cargoManifests = false, brotliQuality, add = false } = {}) {
+  const options = { cwd, env, entries, mappingFile, manifests, scope, conditions, mainFields, platforms, metro, metroResolver, jsx, flow, typescript, tsconfig, resources, packageJSON, cargo, cargoFeatures, cargoNoDefaultFeatures, cargoAllFeatures, cargoTarget, cargoManifests }
+  const kind = classifyEntries('bundleCommand', { ...options, lockfile })
 
-  const target = output ?? DEFAULT_BUNDLE_FILE
   // --add has nothing to merge into on stdout (write-only).
-  if (add && target === '-') {
+  if (add && output === '-') {
     throw new Error('bundleCommand: --add cannot be combined with --output=- (nothing to merge into on stdout)')
   }
 
-  let bundle
-  let lockData
-  if (kind === 'js' && (metro || mainFields !== undefined)) {
-    // The legacy-field resolver builds Bundle + Lockfile directly (per-platform edges + a
-    // synthetic empty module State's addFile can't represent).
-    const built = await buildResolvedJsBundle({
-      cwd,
-      entries,
-      mainFields: metro ? METRO_MAIN_FIELDS : mainFields,
-      platforms: metro ? platforms : [null],
-      conditions,
-      metro: Boolean(metro),
-      metroResolver: Boolean(metroResolver),
-      jsx,
-      flow,
-      resources,
-      packageJSON,
-    })
-    bundle = built.bundle
-    if (lockfile) lockData = built.lockfile.serialize()
-  } else if (kind === 'js' && lockfile) {
-    // Keep the State: only it carries the file hashes the companion lockfile needs (a Bundle holds sources, not digests).
-    const state = await buildJsBundle({ cwd, entries, scope, conditions, jsx, flow, resources, packageJSON })
-    // Stamp the `bundle` consumer (this branch bypasses buildBundle to keep the State).
-    bundle = state.sourceBundle.withReason('bundle')
-    lockData = state.lockData
-  } else {
-    bundle = await buildBundle({ cwd, entries, mappingFile, scope, conditions, jsx, flow, resources, packageJSON })
-  }
+  const built = await buildOfKind(kind, options)
+  let { bundle } = built
+  // The directory the bundle's paths are relative to: a State-built JS bundle's root, which is the
+  // project's at or above cwd (a workspace package's is the workspace root's), else cwd.
+  const root = built.root ?? resolve(cwd)
+  // By default the bundle goes there, where `stasis run --bundle=load` discovers it. In cwd below
+  // the root it would load as rooted at cwd, and root the next `stasis bundle` there too, out of the
+  // files above it.
+  const target = output ?? relative(resolve(cwd), join(root, DEFAULT_BUNDLE_FILE))
+  // Only a JS bundle has a lockfile (classifyEntries refuses one for the others).
+  let lockData = lockfile ? built.lockfile().serialize() : undefined
+
+  // State-built bundles keep the State root's repo (no cwd fallback: their paths are relative to that root).
+  if (!built.stateBuilt) bundle.repo ??= detectRepo(cwd)
 
   // --add: union the fresh build into the existing on-disk bundle; a conflicting file throws. Skipped when nothing is on disk.
   const outAbs = target === '-' ? undefined : resolve(cwd, target)
+  const lockAbs = lockData ? resolve(cwd, lockfile) : undefined
   // Files the pre-existing bundle carried; undefined when no merge happened (the summary's merged sentinel).
   let mergedFrom
   if (add && existsSync(outAbs)) {
@@ -1076,8 +1365,7 @@ export async function bundleCommand({ cwd = process.cwd(), entries, mappingFile,
     // Keep the companion lockfile consistent with the merged bundle: union an existing one.
     // With none on disk we can't attest the pre-existing bundle's files (their hashes live
     // only in that missing lockfile), so refuse rather than write an under-attesting lockfile.
-    if (lockData && lockfile) {
-      const lockAbs = resolve(cwd, lockfile)
+    if (lockData) {
       if (!existsSync(lockAbs)) {
         throw new Error(`bundleCommand: --add can't write a complete lockfile at ${lockfile}: the bundle at ${target} already carries files a fresh lockfile wouldn't attest, and there's no existing lockfile to merge into. Write --lockfile alongside the bundle from the first build, or drop --lockfile.`)
       }
@@ -1095,28 +1383,15 @@ export async function bundleCommand({ cwd = process.cwd(), entries, mappingFile,
   const files = [...bundle.sources.keys()]
   const modules = bundle.modules
 
-  const data = brotliCompressSync(serialized, brotliOptions(brotliQuality))
-  if (target === '-') {
-    process.stdout.write(data)
-  } else {
-    mkdirSync(dirname(outAbs), { recursive: true })
-    writeFileSync(outAbs, data)
-  }
-  if (lockData) {
-    const lockAbs = resolve(cwd, lockfile)
-    mkdirSync(dirname(lockAbs), { recursive: true })
-    writeFileSync(lockAbs, lockData)
-  }
-  const fromDir = outermostDir(files, resolve(cwd))
-  const dest = target === '-' ? '<stdout>' : target
-  // Count packages: every non-empty bucket (the "." workspace bucket counts as one).
-  const packages = [...modules.values()].filter((m) => Object.keys(m.files).length > 0).length
-  const pkgLabel = `${packages} package${packages === 1 ? '' : 's'}`
+  const dest = writeBundle(cwd, target, serialized, brotliQuality)
+  if (lockData) writeFile(lockAbs, lockData)
+  // The bundle's paths are relative to its root; shown relative to cwd, as `dest` is.
+  const fromDir = posix.join(toPosix(relative(resolve(cwd), root)), outermostDir(files, root))
   // On a merge, report newly-added files alongside the totals; a fresh write keeps the plain line.
   if (mergedFrom !== undefined) {
     const added = files.length - mergedFrom
-    console.warn(`[stasis] Added ${added} file${added === 1 ? '' : 's'} (${files.length} total in ${pkgLabel}) from ${fromDir} to ${dest}`)
+    console.warn(`[stasis] Added ${added} file${added === 1 ? '' : 's'} (${files.length} total in ${packagesLabel(modules)}) from ${fromDir} to ${dest}`)
   } else {
-    console.warn(`[stasis] Bundled ${files.length} files in ${pkgLabel} from ${fromDir} to ${dest}`)
+    console.warn(bundledSummary(files.length, modules, fromDir, dest))
   }
 }