feat(sea): let users override the base Node binary

lib/config.ts

@@ -138,6 +138,25 @@ const FLAG_SPECS: readonly FlagSpec[] = [
     default: false,
   },
   { cli: 'sea', cfg: 'sea', resolved: 'sea', kind: 'bool', default: false },
+  {
+    // SEA mode: use a specific Node binary as the base for the executable
+    // instead of downloading one from nodejs.org. Lets you embed a custom
+    // build (e.g. one that runs on older glibc, or a differently-configured
+    // runtime). The binary's major version must match the target's.
+    cli: 'sea-node-path',
+    cfg: 'seaNodePath',
+    resolved: 'seaNodePath',
+    kind: 'string',
+  },
+  {
+    // SEA mode: use the Node binary currently running pkg (process.execPath)
+    // as the base. Shorthand for `--sea-node-path "$(command -v node)"`.
+    cli: 'sea-use-local-node',
+    cfg: 'seaUseLocalNode',
+    resolved: 'seaUseLocalNode',
+    kind: 'bool',
+    default: false,
+  },
   {
     cli: 'compress',
     cfg: 'compress',
@@ -485,6 +504,10 @@ export interface ResolvedFlags {
   fallbackToSource: boolean;
   public: boolean;
   sea: boolean;
+  /** SEA mode: path to a base Node binary to embed (overrides the download). */
+  seaNodePath: string | undefined;
+  /** SEA mode: embed the Node binary running pkg (process.execPath) as the base. */
+  seaUseLocalNode: boolean;
   publicPackages: string[] | undefined;
   noDictionary: string[] | undefined;
   bakeOptions: string[] | undefined;

lib/help.ts

@@ -26,10 +26,13 @@ export default function help() {
     --signature          enable macOS binary signing (default; use to override signature:false in config)
     --no-signature       skip macOS binary signing [default: sign]
     --sea                (Experimental) compile given file using node's SEA feature. Requires node v20.0.0 or higher and only single file is supported
+    --sea-node-path      SEA mode: path to a base Node binary to embed instead of downloading one (must match the target's major version)
+    --sea-use-local-node SEA mode: embed the Node binary running pkg (process.execPath) as the base
 
   All build-shaping flags above (compress, fallback-to-source, public, public-packages,
-  options, bytecode, native-build, no-dict, debug, signature, sea) can also be set in
-  the pkg config file (camelCase keys). CLI flags override config values.
+  options, bytecode, native-build, no-dict, debug, signature, sea, sea-node-path,
+  sea-use-local-node) can also be set in the pkg config file (camelCase keys). CLI flags
+  override config values.
 
   ${pc.dim('Examples:')}
 

lib/index.ts

@@ -192,6 +192,18 @@ export async function exec(
   }
 
   if (flags.sea) {
+    // Base-node override (both forms are mutually exclusive). nodePath embeds a
+    // specific binary; useLocalNode embeds the Node running pkg. Either lets you
+    // ship a SEA built on a custom runtime (e.g. one linked against older glibc).
+    if (flags.seaNodePath && flags.seaUseLocalNode) {
+      throw wasReported(
+        "Specify either '--sea-node-path' or '--sea-use-local-node', not both",
+      );
+    }
+    const seaBase = {
+      nodePath: flags.seaNodePath,
+      useLocalNode: flags.seaUseLocalNode,
+    };
     if (inputJson || configJson) {
       // Enhanced SEA mode — use walker pipeline.
       // seaEnhanced validates the host Node version and minTargetMajor itself.
@@ -202,6 +214,7 @@ export async function exec(
         params: { ...params, seaMode: true },
         addition: isConfiguration(input) ? input : undefined,
         doCompress: flags.compress,
+        ...seaBase,
       });
     } else {
       // Simple SEA mode — plain .js file without package.json.
@@ -216,6 +229,7 @@ export async function exec(
       await sea(inputFin, {
         targets,
         signature: flags.signature,
+        ...seaBase,
       });
     }
     return;

lib/types.ts

@@ -66,6 +66,10 @@ export interface PkgOptions {
   debug?: boolean;
   signature?: boolean;
   sea?: boolean;
+  /** SEA mode: path to a base Node binary to embed (overrides the download). */
+  seaNodePath?: string;
+  /** SEA mode: embed the Node binary running pkg (process.execPath) as the base. */
+  seaUseLocalNode?: boolean;
 }
 
 export interface PackageJson {
@@ -200,4 +204,12 @@ export interface PkgExecOptions {
   noDictionary?: string[];
   /** Sign macOS binaries when applicable. Default `true`. */
   signature?: boolean;
+  /**
+   * SEA mode: path to a base Node binary to embed instead of downloading one
+   * from nodejs.org. Use to embed a custom build (e.g. one linked against an
+   * older glibc). Its major version must match the target's.
+   */
+  seaNodePath?: string;
+  /** SEA mode: embed the Node binary running pkg (`process.execPath`) as the base. */
+  seaUseLocalNode?: boolean;
 }

test/test-95-sea-local-node/index.js

@@ -0,0 +1,6 @@
+'use strict';
+
+// Packaged into a SEA with `--sea-use-local-node`, so the embedded runtime is
+// the same Node that ran pkg (rather than a downloaded one). Output is asserted
+// by main.js. process.pkg confirms the enhanced SEA bootstrap is active.
+console.log('local-node SEA OK:' + (process.pkg != null));

test/test-95-sea-local-node/main.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const assert = require('assert');
+const utils = require('../utils.js');
+
+// Enhanced SEA requires Node.js >= 22
+if (utils.getNodeMajorVersion() < 22) {
+  return;
+}
+
+assert(__dirname === process.cwd());
+
+const input = './package.json';
+const testName = 'test-95-sea-local-node';
+
+const newcomers = utils.seaHostOutputs(testName);
+
+const before = utils.filesBefore(newcomers);
+
+// `--sea-use-local-node` embeds the Node binary running pkg as the SEA base
+// instead of downloading one. Exercises the base-node override end to end (and,
+// on Node >= 25.5 hosts, the in-core `--build-sea` injection path).
+utils.runSeaHostOnly(input, testName, ['--sea-use-local-node']);
+
+utils.assertSeaOutput(testName, 'local-node SEA OK:true\n');
+
+utils.filesAfter(before, newcomers, { tolerateWindowsEbusy: true });

test/test-95-sea-local-node/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "test-95-sea-local-node",
+  "version": "1.0.0",
+  "main": "index.js",
+  "bin": "index.js"
+}

test/test.js

@@ -84,6 +84,7 @@ const npmTests = [
   'test-91-sea-esm-entry',
   'test-92-sea-tla',
   'test-94-sea-esm-import-meta',
+  'test-95-sea-local-node',
 ];
 
 if (testFilter) {

test/unit/config-parse.test.ts

@@ -165,6 +165,24 @@ describe('parseInput — CLI argv', () => {
     it('--options "" preserves the explicit empty signal', () => {
       assert.equal(parseInput(['--options', '', 'a.js']).flags.options, '');
     });
+
+    it('string flag --sea-node-path (kebab key preserved)', () => {
+      assert.equal(
+        parseInput(['--sea-node-path', '/opt/node/bin/node', 'a.js']).flags[
+          'sea-node-path'
+        ],
+        '/opt/node/bin/node',
+      );
+    });
+
+    it('bool flag --sea-use-local-node (kebab key preserved)', () => {
+      assert.equal(
+        parseInput(['--sea-use-local-node', 'a.js']).flags[
+          'sea-use-local-node'
+        ],
+        true,
+      );
+    });
   });
 
   describe('negation', () => {
@@ -410,6 +428,25 @@ describe('resolveFlags — CLI > config > default', () => {
     assert.equal(f.bytecode, false);
   });
 
+  it('SEA base-node override — defaults, config, CLI precedence', () => {
+    const def = resolveFlags({}, {});
+    assert.equal(def.seaNodePath, undefined);
+    assert.equal(def.seaUseLocalNode, false);
+
+    // config keys (cfg name) resolve when CLI is absent
+    const cfg = resolveFlags({}, { seaNodePath: '/n', seaUseLocalNode: true });
+    assert.equal(cfg.seaNodePath, '/n');
+    assert.equal(cfg.seaUseLocalNode, true);
+
+    // CLI (kebab cli name) overrides config
+    const cli = resolveFlags(
+      { 'sea-node-path': '/cli', 'sea-use-local-node': true },
+      { seaNodePath: '/cfg' },
+    );
+    assert.equal(cli.seaNodePath, '/cli');
+    assert.equal(cli.seaUseLocalNode, true);
+  });
+
   describe('list handling', () => {
     it('CLI "" clears the configured list (empty wins)', () => {
       const f = resolveFlags({ options: '' }, { options: ['expose-gc'] });