feat(vfs-bundle): Solidity bundles from soldeer.lock; post-merge fixes to the vfs-bundle export

[exo-nikita]

Follow-up to #189: Soldeer support in @exodus/stasis/vfs-bundle, plus fixes from a post-merge review.

Soldeer

buildVfsBundle({ vfs, packageManager: 'soldeer', entries, mappingFile?, manifests?, env? }) builds a Solidity bundle from the project in the Vfs. buildGitHubBundle takes 'soldeer' too.

• @preventive/deptree lays out the dependencies folder that soldeer install (0.12.0) makes from soldeer.lock. Each zip comes from Soldeer's registry, is checked against the lockfile's sha256, and is cached only where setCacheDir points.
• The bundle is the one stasis bundle builds over that folder.
• What the project holds as installed is never read: its own dependencies folder, and any node_modules (Soldeer installs none, so none can be trusted).
• What soldeer install writes beside the folder is reproduced (vfs-bundle/soldeer.js):
  • the remappings.txt that Soldeer's update would leave is served from the tree in place of the project's;
  • a foundry.toml that Soldeer would edit is refused: "dependencies" missing from [profile.default] libs, or remappings kept in the config that aren't as it leaves them;
  • so is the rare remapping where only Rust's semver could decide whether Soldeer rewrites it.
  • These outputs were checked byte for byte against the real Soldeer 0.12.0 binary: a missing or stale file, CRLF lines, a prefix and version suffix, regeneration, and a lib/ target rewritten.
• env supplies FOUNDRY_PROFILE / FOUNDRY_REMAPPINGS and defaults to {}; nothing is taken from process.env.
• The result has no lockfile (Solidity bundles have none).
• loadNodeModules stays limited to 'pnpm' and 'yarn1'.

To make this work:

• The Solidity loaders (solidity.js, foundry.js) and buildSolidityBundle read the project through a host, the disk's by default.
• The disk host's new optional readdirUnsorted keeps forge's unsorted read_dir order for remapping detection.
• vfsHost serves whichever paths the tree installs (each project's node_modules, or dependencies plus the files written beside it), and hides a directory name a package manager doesn't reproduce.
• Each package manager entry carries its bundle kind (js / sol) and the directory it installs into, which buildVfsBundle uses for its checks and dispatch.
• The Soldeer root is the nearest foundry.toml or soldeer.toml, never above the git root, matching Soldeer's find_project_root.

deptree gap, not fixed here: Soldeer's registry zips for forge-std 1.9.0, 1.9.1 and 1.9.2 use absolute entry names (/LICENSE-APACHE, …).

• Soldeer 0.12 installs them: zip 8.6's enclosed_name drops the root.
• @preventive/deptree 1.0.0-alpha.5 still refuses them with its zip cannot be read: entry name "/LICENSE-APACHE" is absolute.
• So projects on those forge-std versions can't be built here until deptree accepts a leading / the way the zip crate does.

Post-merge fixes

• Install root, picked the way each package manager picks it:
  • pnpm: the workspace root (pnpm-workspace.yaml) wins over a nearer pnpm-lock.yaml.
  • yarn 1: the root whose workspaces include cwd's package; otherwise the nearest yarn.lock.
  • Before, the nearest lockfile always won, so a stray lockfile inside a workspace member got used.
  • lockfileRoot, which buildGitHubBundle uses to set the bundle's repo location, follows the same rule.
  • buildGitHubBundle downloads a directory alone only when its package manager installs it from there: no pnpm-workspace.yaml above it (pnpm), no package.json above it (yarn 1), or its own foundry.toml/soldeer.toml (Soldeer). Otherwise it downloads the whole repo.
• Entry pre-check: buildVfsBundle checks entries relative to cwd. Before, an entry of a project under a node_modules directory skipped the check and only failed after the fetch.
• Shared JS dispatch: buildBundle, bundleCommand and buildVfsBundle now share one JS dispatch. buildBundle and bundleCommand pass their env through it.
• Error naming: pnpm-lock.yaml refusals now come from deptree, which names the file; the stasis-side pre-parse is gone. yarn.lock and soldeer.lock refusals are named in stasis.
• Membership check: "none of the lockfile's projects" applies to the JS package managers only; Soldeer reads no package.json.
• deptree's setCacheDir: the export is now deptree's own.
• Vfs check: any object with a Vfs's methods is accepted, from any copy of @preventive/vfs; its errors are told apart by code.
• Byte order mark: every package.json is read past a BOM, as Node reads it: by the resolver, State, packageType, findPackageMetadata and readJson, through one packageJSONText decoder in the zero-dependency core. Before, the resolver accepted such a manifest and State then crashed on it.
• Node parity in the resolver: an empty main counts as none, and an encoded separator anywhere in an exports target's URL is refused. Node 24 does both; each is covered in the require.resolve parity test.
• State walk: State's walk up to a package.json with a name now finds it by stat (files only) and never goes above its root, instead of calling findPackageJSON on a directory. A package.json that is no JSON object is refused with ERR_INVALID_PACKAGE_CONFIG. Before:
  • in a Vfs, a type-only /package.json looped forever, because findPackageJSON('/') kept returning /package.json;
  • on disk, findPackageJSON can return the directory itself.

Tests

• tests/fixtures/soldeer-bundle holds a project that depends on stasis-sol-lib, a small package with its zip in registry/.
  • The project's soldeer.lock and remappings.txt were written by a real soldeer install (0.12.0), run against a stand-in registry API serving that zip; dependencies/ is the folder that install made.
  • A second install from the lockfile changed nothing.
  • The zip is seeded into the cache, so the tests fetch nothing; checked with fetch replaced by a throw.
• tests/vfs-bundle-soldeer.test.js checks:
  • the tree against the real install (files, modes, bytes);
  • the bundle byte for byte against plain stasis bundle over it, with and without --manifests;
  • that a tampered dependencies folder and an installed node_modules are ignored;
  • the remappings.txt written, against real-install outputs, and the foundry.toml refusals;
  • that a checksum mismatch fails;
  • root discovery, refusals, and repo.
• Each fix has a regression test, checked to fail without its fix. The State-walk test hangs without its fix.
• oxlint is clean. The full suite passes locally on Node 24.14 (2129 pass, 3 pre-existing skips). CI needs no new install step.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KPSLumcb6Rdo4xXL5s5CpE