feat: enhanced SEA mode with walker integration and VFS

.github/workflows/ci.yml

@@ -11,7 +11,7 @@ jobs:
     strategy:
       fail-fast: false # prevent test to stop if one fails
       matrix:
-        node-version: [20.x, 22.x, 24.x]
+        node-version: [22.x, 24.x]
         os: [ubuntu-latest, windows-latest, macos-latest]
     runs-on: ${{ matrix.os }}
     steps:
@@ -23,7 +23,7 @@ jobs:
 
       - run: yarn install
 
-      - if: matrix['node-version'] == '20.x' && matrix['os'] == 'ubuntu-latest'
+      - if: matrix['node-version'] == '22.x' && matrix['os'] == 'ubuntu-latest'
         run: yarn lint
       - run: yarn build
   test_host:
@@ -36,11 +36,6 @@ jobs:
     with:
       npm_command: test:22
 
-  test_20:
-    uses: ./.github/workflows/test.yml
-    with:
-      npm_command: test:20
-
   test_24:
     uses: ./.github/workflows/test.yml
     with:

.github/workflows/test.yml

@@ -13,7 +13,7 @@ jobs:
     strategy:
       fail-fast: false # prevent test to stop if one fails
       matrix:
-        node-version: [20.x, 22.x, 24.x]
+        node-version: [22.x, 24.x]
         os: [ubuntu-latest, windows-latest, macos-latest]
     runs-on: ${{ matrix.os }}
     steps:

.github/workflows/update-dep.yml

@@ -24,10 +24,10 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Use Node.js 20
+      - name: Use Node.js 22
         uses: actions/setup-node@v4
         with:
-          node-version: 20.x
+          node-version: 22.x
           cache: 'yarn'
 
       - name: Update dependency

.gitignore

@@ -19,4 +19,5 @@ examples/express/node_modules
 
 # Editors
 yarn-error.log
-tsconfig.tsbuildinfo
+tsconfig.tsbuildinfo
+prelude/sea-bootstrap.bundle.js

README.md

@@ -47,7 +47,7 @@ After installing it, run `pkg --help` without arguments to see list of options:
     --no-native-build    skip native addons build
     --no-dict            comma-separated list of packages names to ignore dictionaries. Use --no-dict * to disable all dictionaries
     -C, --compress       [default=None] compression algorithm = Brotli or GZip
-    --sea                (Experimental) compile give file using node's SEA feature. Requires node v20.0.0 or higher and only single file is supported
+    --sea                (Experimental) compile using node's SEA feature. With package.json input and node >= 22, uses enhanced mode with full dependency walking and VFS
 
   Examples:
 
@@ -58,7 +58,7 @@ After installing it, run `pkg --help` without arguments to see list of options:
   – Makes executable for particular target machine
     $ pkg -t node22-win-arm64 index.js
   – Makes executables for target machines of your choice
-    $ pkg -t node20-linux,node22-linux,node22-win index.js
+    $ pkg -t node22-linux,node24-linux,node24-win index.js
   – Bakes '--expose-gc' and '--max-heap-size=34' into executable
     $ pkg --options "expose-gc,max-heap-size=34" index.js
   – Consider packageA and packageB to be public
@@ -87,9 +87,9 @@ The entrypoint of your project is a mandatory CLI argument. It may be:
 `pkg` can generate executables for several target machines at a
 time. You can specify a comma-separated list of targets via `--targets`
 option. A canonical target consists of 3 elements, separated by
-dashes, for example `node20-macos-x64` or `node22-linux-arm64`:
+dashes, for example `node22-macos-x64` or `node24-linux-arm64`:
 
-- **nodeRange** node20, node22, node24 or latest
+- **nodeRange** node22, node24 or latest
 - **platform** alpine, linux, linuxstatic, win, macos, (freebsd)
 - **arch** x64, arm64, (armv6, armv7)
 

eslint.config.js

@@ -15,6 +15,7 @@ module.exports = [
       'test/test-51-esm-import-meta/esm-module/test-import-meta-basic.js',
       'lib/log.js', // ESM re-export file
       'test/test-50-extensions/test-y-esnext.js', // ESM test file
+      'prelude/sea-bootstrap.bundle.js', // Generated by esbuild
     ],
   },
 

lib/index.ts

@@ -1,5 +1,5 @@
 import assert from 'assert';
-import { existsSync, readFileSync, writeFileSync, copyFileSync } from 'fs';
+import { existsSync, readFileSync, copyFileSync } from 'fs';
 import { mkdir, readFile, rm, stat } from 'fs/promises';
 import minimist from 'minimist';
 import { need, system } from '@yao-pkg/pkg-fetch';
@@ -16,9 +16,9 @@ import { shutdown } from './fabricator';
 import walk, { Marker, WalkerParams } from './walker';
 import { Target, NodeTarget, SymLinks } from './types';
 import { CompressType } from './compress_type';
-import { patchMachOExecutable, signMachOExecutable } from './mach-o';
+import { signMachOExecutable } from './mach-o';
 import pkgOptions from './options';
-import sea from './sea';
+import sea, { seaEnhanced, signMacOSIfNeeded } from './sea';
 
 const { version } = JSON.parse(
   readFileSync(path.join(__dirname, '../package.json'), 'utf-8'),
@@ -28,6 +28,23 @@ function isConfiguration(file: string) {
   return isPackageJson(file) || file.endsWith('.config.json');
 }
 
+function buildMarker(
+  configJson: Record<string, unknown> | undefined,
+  config: string,
+  inputJson: Record<string, unknown> | undefined,
+  input: string,
+): Marker {
+  const marker: Marker = configJson
+    ? { config: configJson, base: path.dirname(config), configPath: config }
+    : {
+        config: inputJson || {},
+        base: path.dirname(input),
+        configPath: input,
+      };
+  marker.toplevel = true;
+  return marker;
+}
+
 // http://www.openwall.com/lists/musl/2012/12/08/4
 
 const {
@@ -529,10 +546,30 @@ export async function exec(argv2: string[]) {
   }
 
   if (argv.sea) {
-    await sea(inputFin, {
-      targets,
-      signature: argv.signature,
-    });
+    const minTargetMajor = Math.min(
+      ...targets.map((t) => parseInt(t.nodeRange.replace('node', ''), 10)),
+    );
+
+    if ((inputJson || configJson) && minTargetMajor >= 22) {
+      // Enhanced SEA mode — use walker pipeline
+      const marker = buildMarker(configJson, config, inputJson, input);
+
+      pkgOptions.set(configJson?.pkg ?? inputJson?.pkg);
+
+      await seaEnhanced(inputFin, {
+        targets,
+        signature: argv.signature,
+        marker,
+        params: { seaMode: true },
+        addition: isConfiguration(input) ? input : undefined,
+      });
+    } else {
+      // Simple SEA mode (backward compat: plain .js file or Node < 22)
+      await sea(inputFin, {
+        targets,
+        signature: argv.signature,
+      });
+    }
     return;
   }
 
@@ -596,23 +633,8 @@ export async function exec(argv2: string[]) {
 
   let marker: Marker;
 
-  if (configJson) {
-    pkgOptions.set(configJson?.pkg);
-    marker = {
-      config: configJson,
-      base: path.dirname(config),
-      configPath: config,
-    };
-  } else {
-    pkgOptions.set(inputJson?.pkg);
-    marker = {
-      config: inputJson || {}, // not `inputBin` because only `input`
-      base: path.dirname(input), // is the place for `inputJson`
-      configPath: input,
-    };
-  }
-
-  marker.toplevel = true;
+  pkgOptions.set(configJson?.pkg ?? inputJson?.pkg);
+  marker = buildMarker(configJson, config, inputJson, input);
 
   // public
 
@@ -684,30 +706,7 @@ export async function exec(argv2: string[]) {
     });
 
     if (target.platform !== 'win' && target.output) {
-      if (argv.signature && target.platform === 'macos') {
-        // patch executable to allow code signing
-        const buf = patchMachOExecutable(readFileSync(target.output));
-        writeFileSync(target.output, buf);
-
-        try {
-          // sign executable ad-hoc to workaround the new mandatory signing requirement
-          // users can always replace the signature if necessary
-          signMachOExecutable(target.output);
-        } catch {
-          if (target.arch === 'arm64') {
-            log.warn('Unable to sign the macOS executable', [
-              'Due to the mandatory code signing requirement, before the',
-              'executable is distributed to end users, it must be signed.',
-              'Otherwise, it will be immediately killed by kernel on launch.',
-              'An ad-hoc signature is sufficient.',
-              'To do that, run pkg on a Mac, or transfer the executable to a Mac',
-              'and run "codesign --sign - <executable>", or (if you use Linux)',
-              'install "ldid" utility to PATH and then run pkg again',
-            ]);
-          }
-        }
-      }
-
+      await signMacOSIfNeeded(target.output, target, argv.signature);
       await plusx(target.output);
     }
   }

lib/sea-assets.ts

@@ -0,0 +1,96 @@
+import { mkdir, writeFile } from 'fs/promises';
+import { dirname, join } from 'path';
+
+import { STORE_CONTENT, STORE_LINKS, STORE_STAT, snapshotify } from './common';
+import { FileRecords, SymLinks } from './types';
+
+export interface SeaManifest {
+  entrypoint: string;
+  directories: Record<string, string[]>;
+  stats: Record<
+    string,
+    { size: number; isFile: boolean; isDirectory: boolean }
+  >;
+}
+
+export interface SeaAssetsResult {
+  assets: Record<string, string>;
+  manifestPath: string;
+}
+
+/**
+ * Transform walker/refiner output into SEA-compatible asset map and manifest.
+ *
+ * Asset keys use refiner paths (no /snapshot prefix) because @platformatic/vfs
+ * strips the mount prefix before passing paths to the provider. The entrypoint
+ * in the manifest uses the snapshotified path for process.argv[1] compatibility.
+ *
+ * Always uses POSIX '/' separator for manifest paths so the same blob works
+ * regardless of build platform. The bootstrap normalizes at runtime.
+ */
+export async function generateSeaAssets(
+  records: FileRecords,
+  entrypoint: string,
+  _symLinks: SymLinks,
+  tmpDir: string,
+): Promise<SeaAssetsResult> {
+  const assets: Record<string, string> = {};
+  const manifest: SeaManifest = {
+    // Always use '/' — the bootstrap normalizes for the runtime platform
+    entrypoint: snapshotify(entrypoint, '/'),
+    directories: {},
+    stats: {},
+  };
+
+  let modifiedFileCount = 0;
+
+  for (const snap in records) {
+    if (!records[snap]) continue;
+    const record = records[snap];
+
+    // Map file content to SEA asset
+    if (record[STORE_CONTENT]) {
+      if (record.body != null) {
+        // File was modified (patches, rewrites) — write to temp file
+        const tempPath = join(
+          tmpDir,
+          'assets',
+          `modified_${modifiedFileCount}`,
+        );
+        modifiedFileCount += 1;
+        await mkdir(dirname(tempPath), { recursive: true });
+        const content =
+          typeof record.body === 'string'
+            ? Buffer.from(record.body)
+            : record.body;
+        await writeFile(tempPath, content);
+        assets[snap] = tempPath;
+      } else {
+        // Unmodified file — point to source on disk
+        assets[snap] = record.file;
+      }
+    }
+
+    // Collect directory entries
+    if (record[STORE_LINKS]) {
+      manifest.directories[snap] = [
+        ...new Set(record[STORE_LINKS] as string[]),
+      ];
+    }
+
+    // Collect stat metadata
+    if (record[STORE_STAT]) {
+      const stat = record[STORE_STAT];
+      manifest.stats[snap] = {
+        size: stat.size ?? 0,
+        isFile: Boolean(stat.isFileValue),
+        isDirectory: Boolean(stat.isDirectoryValue),
+      };
+    }
+  }
+
+  const manifestPath = join(tmpDir, '__pkg_manifest__.json');
+  await writeFile(manifestPath, JSON.stringify(manifest));
+
+  return { assets, manifestPath };
+}