feat: enhanced SEA mode with walker integration and VFS

[robertsLando]

Summary

Implements #204 — evolves the --sea flag from a simple single-file wrapper into a full packaging pipeline with walker integration and VFS support.

Enhanced SEA mode

• Walker SEA mode — reuses the existing dependency walker with a seaMode flag that skips bytecode compilation and ESM→CJS transform while still discovering all dependencies via stepDetect. In seaMode, stepStrip is a true no-op (preserves record.body Buffer identity) and the walker guarantees that the in-memory body equals the shippable bytes — the asset generator trusts this invariant and skips a disk re-read.

• SEA asset generator (lib/sea-assets.ts) — concatenates all discovered files into a single __pkg_archive__ blob and emits a __pkg_manifest__.json with directory listings, stats, symlinks, native-addon list, entryIsESM flag, and byte offsets into the archive for zero-copy extraction. Race-safe against mid-build source edits (uses the walker's in-memory body rather than re-reading from disk).

• Runtime bootstrap — self-contained bootstrap bundled with @roberts_lando/vfs that provides transparent fs/fs/promises/require/import support via a lazy SEAProvider, native addon extraction, and process.pkg compatibility. Split into:

  • prelude/sea-bootstrap-core.js — shared setup (VFS mount, shared patches, worker interception, diagnostics, perf.start('module loading')). Exports { manifest, entrypoint, perf } without running the entry.
  • prelude/sea-bootstrap.js — single CJS wrapper used for every entry format. Dispatches based on manifest.entryIsESM:
    • CJS entry → Module.runMain() (goes through the real CJS loader; require(esm) on Node 22.12+ transparently handles trivial ESM).
    • ESM entry → compiles import("file:///path/to/entry") via vm.Script with importModuleDynamically: vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER. Dynamic import() inside that script is routed to the default ESM loader, so file URLs resolve and top-level await in the main module works on every Node ≥ 22 target. The ExperimentalWarning for USE_MAIN_CONTEXT_DEFAULT_LOADER is filtered out via a process.emitWarning shim so it doesn't leak into packaged-app stderr.
  • prelude/sea-vfs-setup.js — SEAProvider, archive loading, VFS mount, Windows path normalization. Shared by main thread and workers.

• ESM entrypoints with top-level await (uniform path) — native ESM SEA main (mainFormat: "module", Node 25.7+) is not used. On Node 25.5+, the embedder importModuleDynamicallyForEmbedder callback only resolves builtin modules (nodejs/node#62726), so a native ESM main cannot dynamically import the user entrypoint at all. Instead, the CJS wrapper handles ESM entries through the vm.Script + USE_MAIN_CONTEXT_DEFAULT_LOADER path, which supports TLA on every Node ≥ 22 target — no version split, no build-time warning, no fallback tier.

  Entry	Min target Node	Bootstrap	Dispatch
  CJS	any (>= 22)	sea-bootstrap.bundle.js	Module.runMain()
  ESM	any (>= 22)	sea-bootstrap.bundle.js	vm.Script with USE_MAIN_CONTEXT_DEFAULT_LOADER → dynamic import()

  perf.finalize() is moved into each dispatcher's finally block so module-loading timings reflect real entrypoint completion (including async / TLA apps) and still print when the entry throws. Errors on the ESM path set process.exitCode = 1 instead of calling process.exit() so the finally runs.

• Worker thread support — monkey-patches Worker so /snapshot/... workers get the same SEAProvider + @roberts_lando/vfs mount as the main thread (same archive blob, same Buffer.subarray() extraction, same 164+ fs intercepts). Worker VFS setup is reused from sea-vfs-setup.js, no code duplication.

• DEBUG_PKG diagnostics — the existing DEBUG_PKG / SIZE_LIMIT_PKG / FOLDER_LIMIT_PKG diagnostics now work in SEA mode too. Diagnostic code is only invoked when built with --debug, so release SEA builds can't be coerced into dumping the VFS tree via environment variables.

• Enhanced orchestrator (seaEnhanced() in lib/sea.ts) — full pipeline: walker → refiner → asset generator → blob generation → bake → optional macOS signing.

  • Always uses node --experimental-sea-config to generate the prep blob. --build-sea (Node 25.5+) is intentionally not used: it produces a finished executable and bypasses the prep-blob + postject flow that pkg needs for multi-target injection.
  • Blob generator binary selection is done by host-vs-target major: if host major === minTargetMajor, pkg uses process.execPath (always executable regardless of target platform/arch — this is the only path that works for cross-platform same-major SEA builds, e.g. Linux x64 host producing a Windows x64 SEA). Otherwise it falls back to the downloaded target-platform binary (works cross-major when the host can exec it, e.g. same platform/arch or via QEMU/Rosetta).
  • Host vs target version checks are split: assertHostSeaNodeVersion() validates the pkg host, resolveMinTargetMajor() validates targets separately.
  • useSnapshot: true is rejected — incompatible with the VFS bootstrap (SEA snapshot mode runs the main script at build time inside a V8 startup snapshot context and expects a v8.startupSnapshot.setDeserializeMainFunction() entry; the pkg bootstrap doesn't do that and sea.getRawAsset('__pkg_archive__') does not exist at build time). useCodeCache is still forwarded — it only caches V8 bytecode for the bootstrap script and doesn't touch the runtime VFS path.

• CLI routing — --sea automatically uses enhanced mode when the input has package.json and all targets are Node >= 22; falls back to the existing simple mode otherwise. Public / no-dict / publicPackages WalkerParams are now shared between the SEA and traditional pipelines in lib/index.ts.

• Backward compatible — existing simple --sea mode (single pre-bundled file) works unchanged.

Drop Node.js 20 support

• Node.js 20 reaches EOL in April 2026.
• Minimum engine bumped to >=22.0.0 in package.json.
• Removed Node 20 from CI matrix (ci.yml, test.yml) and test:20 script.
• Updated update-dep.yml workflow to use Node 22.
• @roberts_lando/vfs (requires Node 22+) added as a regular dependency.
• Updated README examples and target documentation.
• @types/node bumped to ^22.0.0.

Bug fixes

• Walker — skip stepDetect (Babel parser) for non-JS files in SEA mode. Previously produced thousands of spurious warnings on .json, .d.ts, .md, .node files.
• Walker — file-before-directory resolution, built-in module shadowing, require.resolve() interception, trailing-slash specifiers, and main-pointing-to-directory. See platformatic/vfs#9 for upstream VFS fixes.
• cpRecursive in bootstrap-shared.js — now uses lstatSync and recreates symlinks at the destination instead of dereferencing them. Fixes infinite recursion and unwanted content escape when addon packages contain symlinks (npm dedup, nested node_modules). Also reads each file once as a Buffer, hashes the buffer directly, and reuses it for writeFileSync — halves I/O on the hash-mismatch path and drops the unnecessary 'binary' encoding conversion.
• SEAProvider._resolveSymlink — throws ELOOP instead of returning the last hop on broken symlink cycles, matching real-fs semantics.
• insideSnapshot — refactored to a prefix table (behavior unchanged, faster check).

Documentation

A full technical comparison of traditional mode vs enhanced SEA mode lives in docs/ARCHITECTURE.md — covers build pipelines, binary formats, runtime bootstrap, VFS provider architecture, worker thread support, performance characteristics, code protection tradeoffs, and the Node.js ecosystem dependencies (including the node:vfs migration path). Updated for the single-bootstrap architecture.

Node.js ecosystem

• Uses @roberts_lando/vfs as VFS polyfill (Node 22+), with built-in migration path to node:vfs when nodejs/node#61478 lands.
• Blob generation uses node --experimental-sea-config. --build-sea and sea-config mainFormat: "module" are deliberately not used (see nodejs/node#62726).

Upstream dependencies

• platformatic/vfs#9 — fixes 5 module resolution issues in @platformatic/vfs module hooks (built-in shadowing, resolution order, require.resolve, trailing slash, main-as-directory).

Test plan

• test-00-sea — simple SEA backward compat (no regression)
• test-85-sea-enhanced — multi-file CJS project with walker integration
• test-86-sea-assets — non-JS asset access via fs.readFileSync
• test-89-sea-fs-ops — VFS ops (readdir, stat, existsSync)
• test-90-sea-worker-threads — workers spawned with /snapshot/... paths
• test-91-sea-esm-entry — ESM entrypoint with relative .mjs imports
• test-92-sea-tla — ESM entrypoint using top-level await (uniform vm.Script path)
• Lint and build pass

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR upgrades pkg’s experimental --sea flag from a single-file wrapper into an “enhanced SEA” pipeline that reuses the existing walker/refiner and embeds a VFS-backed runtime bootstrap, while also raising the project’s minimum supported Node.js version to 22.

Changes:

• Add enhanced SEA orchestration (seaEnhanced) that walks dependencies, generates SEA assets + a manifest, builds a SEA blob, and bakes it into target Node executables.
• Introduce SEA VFS runtime bootstrap (prelude/sea-bootstrap.js) bundled via esbuild, and add @platformatic/vfs as a dependency.
• Drop Node 20 from engines/CI/scripts and add new SEA-focused tests.

Reviewed changes

Copilot reviewed 32 out of 34 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
yarn.lock	Adds lock entry for @platformatic/vfs.
package.json	Adds @platformatic/vfs, bumps @types/node to 22, builds SEA bootstrap bundle, removes Node 20 test script, bumps engines to Node >= 22.
lib/types.ts	Centralizes Marker/WalkerParams types and adds SeaEnhancedOptions.
lib/walker.ts	Adds seaMode behavior to skip bytecode/ESM transforms and keep dependency detection.
lib/sea-assets.ts	New: converts walker/refiner output into SEA asset map + manifest JSON.
lib/sea.ts	Adds seaEnhanced(), shared tempdir helper, execFile usage, and shared macOS signing helper.
lib/index.ts	Routes --sea to enhanced mode when appropriate; factors buildMarker(); reuses macOS signing helper.
prelude/sea-bootstrap.js	New: SEA runtime bootstrap that mounts a VFS from SEA assets and supports native addon extraction.
eslint.config.js	Ignores generated prelude/sea-bootstrap.bundle.js.
.gitignore	Ignores generated prelude/sea-bootstrap.bundle.js.
README.md	Updates SEA docs and examples to reflect enhanced mode and Node >= 22 focus.
.github/workflows/ci.yml	Removes Node 20 from matrix; updates lint run condition to Node 22.
.github/workflows/test.yml	Removes Node 20 from test matrix.
.github/workflows/update-dep.yml	Updates workflow to use Node 22.
test/utils.js	Adds assertSeaOutput() helper for SEA tests.
test/test-85-sea-enhanced/*	New enhanced SEA “multi-file project” test fixture.
test/test-86-sea-assets/*	New enhanced SEA “fs.readFileSync assets” test fixture.
test/test-87-sea-esm/*	New enhanced SEA ESM test fixture (currently skipped).
test/test-89-sea-fs-ops/*	New enhanced SEA filesystem ops test fixture.
plans/SEA_VFS_IMPLEMENTATION_PLAN.md	Adds design/analysis and implementation plan document.

[Copilot]

Pull request overview

Copilot reviewed 36 out of 38 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 36 out of 38 changed files in this pull request and generated 3 comments.

[Niek]

So, comparing SEA with bundle vs Standard PKG (with bundle) = 44% slower startup, 30% larger binary, and you lose source code protection. No offence, but that sounds like a very hard sell. Additionally, if people prefer that route they would rather go with something like fossilize I think, which is a repo dedicated to creating Node SEA executables.

[robertsLando]

Thanks for the feedback! There are some important differences between this PR and fossilize that are worth highlighting:

1. Virtual Filesystem (VFS) — transparent fs/require/import support

Fossilize bundles everything into a single file with esbuild and requires you to use sea.getAsset() to access embedded files. There's no filesystem patching — code that does fs.readFileSync(path.join(__dirname, 'config.json')) or dynamically requires modules simply won't work without refactoring your application.

Our enhanced SEA mode uses @platformatic/vfs (and will migrate to node:vfs when nodejs/node#61478 lands) to provide a full VFS layer that transparently patches fs, require, and import. Existing code works without modification — just like traditional pkg mode.

2. Native addon support

Fossilize cannot handle .node native addons at all (esbuild limitation). Our implementation detects native addons via the walker, embeds them as SEA assets, and extracts them at runtime — same as traditional pkg.

3. Worker thread support

We monkey-patch the Worker constructor to intercept /snapshot/... paths and inject a VFS-aware bootstrap, so worker threads work transparently. Fossilize has no worker thread support.

4. Dependency walker integration

Fossilize relies entirely on esbuild's bundling, which means apps must be fully bundleable. Our approach reuses pkg's battle-tested dependency walker (stepDetect) to discover all dependencies — including edge cases handled by our dictionary of package-specific configs. It then generates a SEA asset map with directory listings, stats, and symlinks.

5. Stock Node.js binaries — no more patched builds

This is actually a shared advantage with fossilize, and one of the main motivations for this PR. Traditional pkg requires patched Node.js binaries built and released via the yao-pkg/pkg-fetch project. These patches are hard to create, time-consuming to build for every Node.js release, and can lag behind upstream — users often have to wait for new builds before they can use a new Node.js version. With enhanced SEA mode, users can use official Node.js binaries directly from nodejs.org — no patches, no waiting for pkg-fetch releases, no maintenance burden.

6. On the performance comparison

You're right about the numbers — SEA with bundle vs Standard PKG with bundle is 261ms vs 381ms startup and 111 MB vs 145 MB binary. That's a meaningful but not dramatic difference, and in return you gain stock Node.js binaries (no pkg-fetch dependency), ESM support, and a much simpler maintenance story.

The tradeoff for losing bytecode/source protection is real, but for many use cases (CLI tools, internal services, IoT deployments) it's not a concern — and the elimination of the patched-binary dependency is a significant operational win.

[Copilot]

Pull request overview

Copilot reviewed 54 out of 58 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 65 out of 69 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 64 out of 68 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 64 out of 68 changed files in this pull request and generated 11 comments.