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 seaMode flag that skips bytecode compilation and ESM-to-CJS transform while still discovering all dependencies via stepDetect
• SEA asset generator (lib/sea-assets.ts): Transforms walker output into SEA-compatible asset map + manifest JSON with directory listings, stats, symlinks, and native addon detection
• Runtime bootstrap (prelude/sea-bootstrap.js): Self-contained bootstrap bundled with @platformatic/vfs that provides transparent fs/require/import support via lazy SEAProvider, native addon extraction, and process.pkg compatibility
• Worker thread support: Monkey-patches Worker constructor to intercept /snapshot/... paths, injecting a self-contained VFS bootstrap (sea-worker-bootstrap.js) that uses node:sea directly for module resolution and fs operations in worker threads
• Enhanced orchestrator (seaEnhanced() in lib/sea.ts): Full pipeline: walker → refiner → asset generator → SEA blob → bake, with Node 25.5+ --build-sea detection
• CLI routing: --sea automatically uses enhanced mode when input has package.json and all targets are Node >= 22; falls back to simple mode otherwise
• Backward compatible: Existing simple --sea mode (single pre-bundled file, Node 20+) works unchanged

Drop Node.js 20 support

• Node.js 20 reached 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
• @platformatic/vfs (requires Node 22+) added as 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 caused thousands of spurious warnings on .json, .d.ts, .md, .node files
• Walker: Fix file-before-directory resolution, built-in module shadowing, require.resolve() interception, trailing-slash specifiers, and main-pointing-to-directory — see platformatic/vfs#9 for the upstream VFS fixes

Performance & Code Protection

The implementation plan at plans/SEA_VFS_IMPLEMENTATION_PLAN.md includes a detailed analysis comparing traditional pkg vs enhanced SEA mode on code protection (bytecode vs plaintext), startup time, executable size, build speed, and memory footprint.

Node.js Ecosystem

• Uses @platformatic/vfs as VFS polyfill (Node 22+), with built-in migration path to node:vfs when nodejs/node#61478 lands
• ESM SEA entry (mainFormat: "module") ready for Node 25.7+ per nodejs/node#61813

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-85-sea-enhanced — Multi-file CJS project with walker integration
• test-86-sea-assets — Non-JS asset access via fs.readFileSync
• test-87-sea-esm — ESM project (skipped until node:vfs lands in core)
• test-89-sea-fs-ops — VFS operations: readdir, stat, existsSync
• test-90-sea-worker-threads — Worker thread spawning with VFS support
• test-00-sea — Existing simple SEA test (backward compat, no regression)
• Lint and build pass (145/146, 1 pre-existing failure unrelated)

🤖 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.

[robertsLando]

Packaging Performance Benchmarks — zwave-js-ui v11.15.1

Benchmarked the enhanced SEA mode against standard PKG on zwave-js-ui (v11.15.1), a large real-world ESM project with native addons (@serialport), complex dependency trees, and package.json exports with wildcards and #imports.

Environment: Node.js v22.22.1, Linux x86_64, target node22-linux-x64

Summary

Method	Build Time (avg of 3)	Binary Size	Startup (avg of 4)	Status
Standard PKG (no bundle)	78.2s	324 MB	N/A	❌ ESM runtime crash
Standard PKG (with bundle)	42.3s	111 MB	265ms	✅
SEA with bundle	24.9s	145 MB	382ms	✅
SEA without bundle	80.7s	377 MB	2274ms	✅

Raw Data

Build Times

Method	Run 1	Run 2	Run 3	Average
Standard PKG (no bundle)	78.2s	—	—	78.2s
Standard PKG (with bundle)	42.7s	42.4s	41.7s	42.3s
SEA with bundle	24.9s	26.1s	23.9s	24.9s
SEA without bundle	95.8s	90.4s	56.0s	80.7s

Startup Times (5 runs, cold run discarded, average of runs 2-5)

Method	Run 1 (cold)	Run 2	Run 3	Run 4	Run 5	Average (2-5)
Standard PKG (no bundle)	FAIL	—	—	—	—	N/A
Standard PKG (with bundle)	254ms	266ms	277ms	275ms	243ms	265ms
SEA with bundle	380ms	374ms	391ms	391ms	373ms	382ms
SEA without bundle	2266ms	2280ms	2234ms	2278ms	2303ms	2274ms

Key Findings

• SEA + bundle is the fastest to build (24.9s) — 41% faster than PKG + bundle (42.3s), because it skips V8 bytecode compilation entirely
• PKG + bundle produces the smallest binary (111 MB) — bytecode is more compact than plaintext source (SEA + bundle: 145 MB)
• PKG + bundle has the fastest startup (265ms) — pre-compiled bytecode avoids JS parse overhead
• Standard PKG without bundle fails for ESM projects — bytecode compiler can't handle "type": "module" projects, crashes with ReferenceError: module is not defined in ES module scope
• SEA without bundle works natively with ESM — no pre-bundling needed, walker intercepts all files. Trade-off: largest binary (377 MB), slowest startup (~2.3s) due to loading thousands of individual files from VFS
• SEA + bundle is the best overall for ESM projects — fastest build, reasonable size, good startup, and full ESM support

VFS Fixes Required

Testing against zwave-js-ui uncovered several issues in @platformatic/vfs module hooks that were fixed during this work:

1. Wildcard pattern support in exports maps (e.g., "./bindings/*")
2. Package #imports (subpath imports) resolution for VFS-hosted files
3. CJS exports field support in Module._resolveFilename patch
4. CJS subpath directory resolution (e.g., require('pkg/subdir') → subdir/index.js)
5. fs.copyFileSync not routed through VFS in SEA overlay mode (dlopen patch)
6. fs.realpathSync crash in diagnostic dumpLevel function

Fixes 5-6 are committed on this branch. Fixes 1-4 require an upstream PR to @platformatic/vfs (plan written at ../vfs/VFS_MODULE_HOOKS_FIXES_PLAN.md).

[robertsLando]

SEA Provider Performance Optimizations — Results

Follow-up to the initial benchmarks. After profiling the SEA no-bundle startup with DEBUG_PKG_PERF=1, we identified and optimized the VFS provider hot paths.

What was optimized

Optimization	Impact
internalModuleStat() — O(1) manifest hash lookup instead of MemoryProvider tree walk	Eliminated ~30K tree walks
statSync() — lightweight stat objects from manifest	Avoids full VirtualStats allocation
readFileSync() — flat Map cache bypassing MemoryProvider write+read roundtrip	Saves ~82ms of MemoryProvider overhead
existsSync() — pure manifest lookup, no fallback	Removes redundant MemoryProvider stat calls

Updated startup times (SEA no-bundle, zwave-js-ui)

Variant	Run 1	Run 2	Run 3	Run 4	Run 5	Average
Before (original)	2332ms	2300ms	2320ms	2282ms	2324ms	2312ms
After (optimized)	1835ms	1840ms	1863ms	1849ms	1820ms	1841ms
Improvement						-20% (-471ms)

Where the remaining time goes

Profiled with DEBUG_PKG_PERF=1:

[pkg:perf] phase                 time
[pkg:perf] ──────────────────────────────
[pkg:perf] manifest parse        14.1ms
[pkg:perf] directory tree init   19.1ms
[pkg:perf] vfs mount + hooks     20.3ms
[pkg:perf] vfs setup total       53.4ms
[pkg:perf] module loading      1685.6ms
[pkg:perf]
[pkg:perf] counter                  value
[pkg:perf] ──────────────────────────────
[pkg:perf] files loaded              1776
[pkg:perf] file cache entries        1776
[pkg:perf] sea.getRawAsset()   1046.8ms
[pkg:perf] statSync calls               0
[pkg:perf] existsSync calls          1540
[pkg:perf] readdirSync calls            0

The dominant remaining bottleneck is sea.getRawAsset() — 1,047ms for 1,776 file reads (56% of total). This is the Node.js native SEA API reading assets from the executable binary at ~0.6ms per call.

Future improvement: single-archive asset

The most impactful next step would be packing all VFS files into a single SEA asset (a blob with an offset index) instead of 16K+ individual assets. This would turn 1,776 getRawAsset() calls into 1 call + buffer slicing, potentially cutting startup from ~1.8s to ~0.8s.

Updated summary table

Method	Build Time	Binary Size	Startup	Status
Standard PKG (no bundle)	78.2s	324 MB	N/A	❌ ESM crash
Standard PKG (with bundle)	42.3s	111 MB	265ms	✅
SEA with bundle	24.9s	145 MB	382ms	✅
SEA without bundle (before)	80.7s	377 MB	2312ms	✅
SEA without bundle (after)	80.7s	377 MB	1841ms	✅

[robertsLando]

Single-Archive SEA — Benchmark Results

The archive optimization packs all VFS files into a single SEA asset (__pkg_archive__) with an offset index. At runtime, one sea.getRawAsset() call loads the entire blob, and individual files are extracted via zero-copy Buffer.subarray().

Impact on sea.getRawAsset() bottleneck

Metric	Before (per-file assets)	After (single archive)
getRawAsset() calls	1,776	1
getRawAsset() total time	1,047ms	0.2ms
Module loading phase	1,686ms	622ms

Full benchmark comparison

Method	Build Time (avg of 3)	Binary Size	Startup (avg of runs 2-5)	Status
Standard PKG (no bundle)	78.2s	324 MB	N/A	❌ ESM crash
Standard PKG (with bundle)	16.5s	111 MB	261ms	✅
SEA with bundle	10.1s	145 MB	381ms	✅
SEA without bundle (archive)	39.9s	377 MB	711ms	✅

Startup time progression (SEA no-bundle)

Version	Startup	Improvement
Original (per-file assets, no provider opts)	2,312ms	baseline
+ Provider optimizations (fast stat/exists/read)	1,841ms	-20%
+ Single archive	711ms	-69%

Raw data

Build times

Method	Run 1	Run 2	Run 3	Average
Standard PKG (with bundle)	16.9s	16.0s	16.7s	16.5s
SEA with bundle	10.0s	10.4s	9.9s	10.1s
SEA without bundle (archive)	39.9s	39.6s	40.2s	39.9s

Startup times

Method	Run 1 (cold)	Run 2	Run 3	Run 4	Run 5	Average (2-5)
Standard PKG (with bundle)	269ms	252ms	260ms	270ms	260ms	261ms
SEA with bundle	381ms	371ms	383ms	379ms	392ms	381ms
SEA without bundle (archive)	722ms	707ms	711ms	712ms	712ms	711ms

Perf profile (DEBUG_PKG_PERF=1)

[pkg:perf] phase                 time
[pkg:perf] ──────────────────────────────
[pkg:perf] manifest parse        21.3ms
[pkg:perf] archive load           0.2ms
[pkg:perf] directory tree init   20.7ms
[pkg:perf] vfs mount + hooks     22.3ms
[pkg:perf] vfs setup total       64.5ms
[pkg:perf] module loading       622.0ms
[pkg:perf]
[pkg:perf] counter                  value
[pkg:perf] ──────────────────────────────
[pkg:perf] files loaded              1776
[pkg:perf] file cache entries        1776
[pkg:perf] statSync calls               0
[pkg:perf] existsSync calls          1540
[pkg:perf] readdirSync calls            0

Key takeaways

• SEA without bundle is now viable for production — 711ms startup without requiring any bundler, handling ESM natively
• The archive eliminated the dominant bottleneck — getRawAsset() went from 1,047ms (56% of startup) to 0.2ms
• Remaining startup time is V8 parse/compile (~622ms for 1,776 source files) — inherent to source-mode execution
• SEA + bundle remains fastest for startup-critical use cases (381ms), but the no-bundle option is now within 2x
• Build time halved for SEA no-bundle (80.7s → 39.9s) — writing one archive is faster than registering 16K+ individual SEA assets

[Copilot]

Pull request overview

Copilot reviewed 53 out of 57 changed files in this pull request and generated 7 comments.

[Copilot]

Pull request overview

Copilot reviewed 53 out of 57 changed files in this pull request and generated 5 comments.

[Copilot]

In SEA mode you call stepStrip(record) for JS/ESM files, but stepStrip may remove a BOM/shebang and always overwrites record.body without setting record.bodyModified. generateSeaAssets() only embeds record.body when bodyModified is true; otherwise it streams the original file from disk, which can silently discard the stripped content and make SEA output differ from what the walker analyzed. Set record.bodyModified when stepStrip actually changes content (e.g., compare before/after), or avoid calling stepStrip unless you intend to persist the modified body.

[Copilot]

generateSeaBlob() falls back from --build-sea to --experimental-sea-config on any error. This can mask real failures (e.g., invalid sea-config.json) and misleadingly log that --build-sea is unavailable. Narrow the fallback to the specific “unknown option/unsupported” failure (inspect error message/exit code), and rethrow other errors so users don’t get a different code path unexpectedly.

[Copilot]

This testing guidance still references Node 20 (npm run test:20 and node test/test.js node20 ...), but this PR removes the test:20 script and bumps the minimum supported Node version to 22. Update these commands/examples to Node 22+ so contributors follow working instructions.

[Copilot]

This document says TypeScript targets ES2017 and the project requires Node.js >= 20.0.0, but tsconfig.json targets ES2022 and package.json engines is now >= 22.0.0. Please update these lines so contributor guidance matches the actual build/runtime requirements.

[Copilot]

Project overview still claims support for Node.js 20 (node20, node22+), but this PR bumps engines.node to >=22 and removes Node 20 from CI/tests. Update this sentence to avoid conflicting guidance about supported Node versions.

[Copilot]

Pull request overview

Copilot reviewed 53 out of 57 changed files in this pull request and generated 3 comments.

[Copilot]

assertSeaOutput compares stdout exactly, but SEA executables on Windows often emit different line endings (CRLF) and/or extra leading/trailing newlines (see existing test-00-sea Windows output mismatch). Normalizing the spawned output (e.g., convert CRLF→LF and optionally trim a single trailing newline) before assertion would make these SEA tests stable across platforms while still validating content.

[Copilot]

patchDlopen skips copying the native addon package folder when destFolder already exists. With concurrent process starts, one instance can create destFolder before finishing the recursive copy; a second instance will see destFolder and skip copying, then attempt dlopen from a partially populated directory (ENOENT / load failures). Consider using a completion marker/atomic rename strategy, or at least check for the specific expected target file (newPath) before skipping the copy.

[Copilot]

generateSeaBlob falls back from --build-sea to --experimental-sea-config on any error. That can mask real build failures (invalid config, permission issues, etc.) and lead to confusing secondary errors. Prefer falling back only when the failure indicates the flag is unsupported/unknown; otherwise rethrow the original error (or include stderr) so users see the real cause.

[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.