@pnpm/releasing.commands 1100.1.0 → 1100.2.1

package/lib/pack-app/packApp.d.ts

@@ -7,7 +7,7 @@ export declare function help(): string;
 export type PackAppOptions = Pick<Config, 'dir' | 'pnpmHomeDir'> & Partial<Pick<Config, 'ca' | 'cert' | 'configByUri' | 'httpProxy' | 'httpsProxy' | 'key' | 'localAddress' | 'nodeDownloadMirrors' | 'noProxy' | 'strictSsl' | 'userAgent'>> & {
     entry?: string;
     target?: string | string[];
-    nodeVersion?: string;
+    runtime?: string;
     outputDir?: string;
     outputName?: string;
 };
@@ -16,7 +16,7 @@ export declare function handler(opts: PackAppOptions, params: string[]): Promise
 export interface ProjectAppConfig {
     entry?: string;
     targets?: string[];
-    nodeVersion?: string;
+    runtime?: string;
     outputDir?: string;
     outputName?: string;
 }

package/lib/pack-app/packApp.js

@@ -12,11 +12,6 @@ import { safeExeca as execa } from 'execa';
 import { renderHelp } from 'render-help';
 /** Minimum Node.js version that supports `node --build-sea`. */
 const MIN_BUILDER_VERSION = { major: 25, minor: 5 };
-// Range to download when the running Node is too old. Constrained to the
-// current major so we don't silently jump majors across releases, and pinned
-// above MIN_BUILDER_VERSION.minor so older point releases (e.g. 25.0.x) that
-// don't support `--build-sea` aren't picked.
-const DEFAULT_BUILDER_SPEC = `>=${MIN_BUILDER_VERSION.major}.${MIN_BUILDER_VERSION.minor}.0 <${MIN_BUILDER_VERSION.major + 1}.0.0`;
 // Target OS names match `process.platform`. That keeps the CLI surface
 // consistent with pnpm's own `--os` flag (which also takes platform constants)
 // and with `supportedArchitectures.os` in pnpm-workspace.yaml.
@@ -30,7 +25,7 @@ export function cliOptionsTypes() {
     return {
         entry: String,
         target: [String, Array],
-        'node-version': String,
+        runtime: String,
         'output-dir': String,
         'output-name': String,
     };
@@ -44,16 +39,17 @@ export function help() {
         description: 'Pack a CommonJS entry file into a standalone executable for one or more target platforms.\n\n' +
             'The executable embeds a Node.js binary via the Node.js Single Executable Applications API.\n' +
             `Requires Node.js v${MIN_BUILDER_VERSION.major}.${MIN_BUILDER_VERSION.minor}+ to perform ` +
-            'the injection. The running Node.js is used when it is new enough; otherwise, the ' +
-            `latest Node.js v${MIN_BUILDER_VERSION.major}.${MIN_BUILDER_VERSION.minor}+ in the ` +
-            `v${MIN_BUILDER_VERSION.major}.x line is downloaded automatically.\n\n` +
-            'Defaults for --entry, --target, --node-version, --output-dir, and --output-name can be ' +
+            'the injection. SEA blobs are not compatible across Node.js minor releases, so the ' +
+            'builder Node.js must match the embedded runtime version exactly. The running Node.js ' +
+            'is used when it already matches; otherwise a host-arch Node.js of the embedded runtime ' +
+            'version is downloaded automatically.\n\n' +
+            'Defaults for --entry, --target, --runtime, --output-dir, and --output-name can be ' +
             'set in the package.json under "pnpm.app". CLI flags override the config; --target entirely ' +
             'replaces the configured list so you can narrow it at invocation time.',
         url: docsUrl('pack-app'),
         usages: [
             'pnpm pack-app --entry dist/index.cjs --target linux-x64 --target win32-x64',
-            'pnpm pack-app --entry dist/index.cjs --target linux-x64-musl --node-version 22',
+            `pnpm pack-app --entry dist/index.cjs --target linux-x64-musl --runtime node@${MIN_BUILDER_VERSION.major}`,
         ],
         descriptionLists: [
             {
@@ -69,9 +65,11 @@ export function help() {
                         shortAlias: '-t',
                     },
                     {
-                        description: 'Node.js version to embed in the output executables (e.g. "22", "22.0.0", "lts"). ' +
+                        description: 'Runtime to embed in the output executables, as a "<name>@<version>" spec ' +
+                            `(e.g. "node@${MIN_BUILDER_VERSION.major}", "node@${MIN_BUILDER_VERSION.major}.${MIN_BUILDER_VERSION.minor}.0"). ` +
+                            `Only "node" is supported today, and the version must be >= v${MIN_BUILDER_VERSION.major}.${MIN_BUILDER_VERSION.minor} (the minimum that supports --build-sea). ` +
                             'Defaults to the running Node.js version.',
-                        name: '--node-version',
+                        name: '--runtime',
                     },
                     {
                         description: 'Output directory for the built executables. Defaults to "dist-app".',
@@ -115,14 +113,27 @@ export async function handler(opts, params) {
         throw new PnpmError('PACK_APP_MISSING_TARGET', `"pnpm pack-app" requires at least one target — pass --target <triplet> or set "pnpm.app.targets" in package.json. Supported: ${SUPPORTED_TARGETS}`);
     }
     const targets = rawTargets.map(parseTarget);
+    // Parse the runtime before output-name derivation and any network work so
+    // that a malformed --runtime fails fast with a clear error instead of being
+    // masked by later problems (missing package.json name, registry lookup, etc.).
+    const runtimeSpec = opts.runtime ?? project.app?.runtime ?? `node@${process.version.slice(1)}`;
+    const { version: requestedNodeSpec } = parseRuntime(runtimeSpec);
     const outputDir = path.resolve(opts.dir, opts.outputDir ?? project.app?.outputDir ?? 'dist-app');
     await mkdir(outputDir, { recursive: true });
     const outputName = validateOutputName(opts.outputName ?? project.app?.outputName ?? deriveOutputNameFromPackage(project, opts.dir));
-    const requestedNodeSpec = opts.nodeVersion ?? project.app?.nodeVersion ?? process.version.slice(1);
     const fetch = createFetchFromRegistry(opts);
     const buildRoot = path.join(opts.pnpmHomeDir, 'pack-app');
-    const builderBin = await resolveBuilderBinary({ fetch, nodeDownloadMirrors: opts.nodeDownloadMirrors, buildRoot });
+    // Resolve the embedded target version first so the builder can be pinned to
+    // the same version. SEA blobs carry no version header and the serialized
+    // format has changed across Node.js minor releases (e.g. v25.7 added a
+    // ModuleFormat byte for ESM entry points), so a blob produced by a builder
+    // of a different version than the embedded runtime will fail deserialization
+    // at startup with an opaque native assertion.
     const resolvedTargetVersion = await resolveVersion(fetch, requestedNodeSpec, opts.nodeDownloadMirrors);
+    const builderBin = await resolveBuilderBinary({
+        buildRoot,
+        targetVersion: resolvedTargetVersion,
+    });
     const results = [];
     for (const target of targets) {
         // eslint-disable-next-line no-await-in-loop
@@ -170,17 +181,26 @@ export async function handler(opts, params) {
     return `Built ${targets.length} executable${targets.length === 1 ? '' : 's'}:\n${results.join('\n')}`;
 }
 /**
- * Returns a Node.js binary that supports `--build-sea`. Prefers the running
- * interpreter to avoid a download; falls back to downloading Node.js v25.
+ * Returns a Node.js binary that supports `--build-sea` AND produces a SEA
+ * blob the embedded runtime can deserialize. The second constraint forces the
+ * builder to match the target runtime version exactly: blobs are versioned by
+ * the writer's internal struct layout with no header, and Node bumps that
+ * layout in minor releases (e.g. v25.7 added a ModuleFormat byte for ESM
+ * entries), so a cross-version blob crashes at startup.
+ *
+ * Prefers the running interpreter when it already matches the target version;
+ * otherwise downloads the target version for the host platform.
  */
 async function resolveBuilderBinary(ctx) {
-    if (runningNodeCanBuildSea()) {
+    if (runningNodeCanBuildSea() && process.version === `v${ctx.targetVersion}`) {
         return process.execPath;
     }
-    const version = await resolveVersion(ctx.fetch, DEFAULT_BUILDER_SPEC, ctx.nodeDownloadMirrors);
+    if (!builderVersionCanBuildSea(ctx.targetVersion)) {
+        throw new PnpmError('PACK_APP_RUNTIME_TOO_OLD', `The embedded runtime "node@${ctx.targetVersion}" is older than Node.js v${MIN_BUILDER_VERSION.major}.${MIN_BUILDER_VERSION.minor}, which is the minimum version that supports --build-sea.`, { hint: `Pass --runtime node@${MIN_BUILDER_VERSION.major}.${MIN_BUILDER_VERSION.minor}.0 (or newer) or set "pnpm.app.runtime" in package.json.` });
+    }
     return ensureNodeRuntime({
         buildRoot: ctx.buildRoot,
-        version,
+        version: ctx.targetVersion,
         platform: process.platform,
         arch: process.arch,
         // Pin libc to the host's. Otherwise a caller that had set
@@ -196,7 +216,10 @@ function hostLinuxLibc() {
     return family === 'musl' ? 'musl' : 'glibc';
 }
 function runningNodeCanBuildSea() {
-    const [majorStr, minorStr] = process.version.slice(1).split('.');
+    return builderVersionCanBuildSea(process.version.slice(1));
+}
+function builderVersionCanBuildSea(version) {
+    const [majorStr, minorStr] = version.split('.');
     const major = Number(majorStr);
     const minor = Number(minorStr);
     return (major > MIN_BUILDER_VERSION.major ||
@@ -270,6 +293,21 @@ function parseTarget(raw) {
     }
     return { raw, platform, arch, libc: libc || undefined };
 }
+// Runtime spec is "<name>@<version>". Only "node" is supported today; the
+// prefix is kept so future runtimes (bun, deno) can share the same flag
+// without a breaking change. Reading the runtime name rather than a bare
+// version also avoids shadowing pnpm's global `node-version` rc setting,
+// whose value would otherwise leak into Config['nodeVersion'] and override
+// `pnpm.app.runtime`.
+const SUPPORTED_RUNTIMES = ['node'];
+const RUNTIME_PATTERN = /^(node)@(.+)$/;
+function parseRuntime(spec) {
+    const match = RUNTIME_PATTERN.exec(spec);
+    if (!match) {
+        throw new PnpmError('PACK_APP_INVALID_RUNTIME', `Invalid runtime "${spec}". Expected format: <name>@<version> (supported runtimes: ${SUPPORTED_RUNTIMES.join(', ')}; e.g. "node@${MIN_BUILDER_VERSION.major}.${MIN_BUILDER_VERSION.minor}.0").`);
+    }
+    return { name: match[1], version: match[2] };
+}
 // Characters that Win32 rejects in filenames, plus NUL. Path separators are
 // checked separately via `path.basename` so the message is crisp.
 const INVALID_FILENAME_CHARS = /[<>:"|?*\0]/;
@@ -319,7 +357,7 @@ async function readProjectAppConfig(dir) {
     return { name, app: validateAppConfig(appField) };
 }
 function validateAppConfig(raw) {
-    const known = new Set(['entry', 'targets', 'nodeVersion', 'outputDir', 'outputName']);
+    const known = new Set(['entry', 'targets', 'runtime', 'outputDir', 'outputName']);
     for (const key of Object.keys(raw)) {
         if (!known.has(key)) {
             throw new PnpmError('PACK_APP_INVALID_CONFIG', `Unknown "pnpm.app.${key}" setting in package.json. Allowed keys: ${Array.from(known).join(', ')}.`);
@@ -338,11 +376,11 @@ function validateAppConfig(raw) {
         }
         config.targets = raw.targets;
     }
-    if (raw.nodeVersion != null) {
-        if (typeof raw.nodeVersion !== 'string') {
-            throw new PnpmError('PACK_APP_INVALID_CONFIG', '"pnpm.app.nodeVersion" must be a string.');
+    if (raw.runtime != null) {
+        if (typeof raw.runtime !== 'string') {
+            throw new PnpmError('PACK_APP_INVALID_CONFIG', '"pnpm.app.runtime" must be a string.');
         }
-        config.nodeVersion = raw.nodeVersion;
+        config.runtime = raw.runtime;
     }
     if (raw.outputDir != null) {
         if (typeof raw.outputDir !== 'string') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pnpm/releasing.commands",
-  "version": "1100.1.0",
+  "version": "1100.2.1",
   "description": "Commands for deploy, pack, and publish",
   "keywords": [
     "pnpm",
@@ -47,35 +47,35 @@
     "validate-npm-package-name": "7.0.2",
     "write-json-file": "^7.0.0",
     "write-yaml-file": "^6.0.0",
+    "@pnpm/catalogs.types": "1100.0.0",
+    "@pnpm/cli.common-cli-options-help": "1100.0.0",
     "@pnpm/bins.resolver": "1100.0.1",
     "@pnpm/cli.utils": "1101.0.0",
-    "@pnpm/cli.common-cli-options-help": "1100.0.0",
     "@pnpm/config.pick-registry-for-package": "1100.0.1",
     "@pnpm/constants": "1100.0.0",
-    "@pnpm/engine.runtime.node-resolver": "1100.0.3",
+    "@pnpm/deps.path": "1100.0.1",
+    "@pnpm/engine.runtime.node-resolver": "1101.0.0",
+    "@pnpm/engine.runtime.commands": "1100.0.4",
     "@pnpm/error": "1100.0.0",
-    "@pnpm/fetching.directory-fetcher": "1100.0.3",
+    "@pnpm/config.reader": "1101.1.1",
+    "@pnpm/exec.lifecycle": "1100.0.4",
     "@pnpm/exec.pnpm-cli-runner": "1100.0.0",
-    "@pnpm/exec.lifecycle": "1100.0.3",
-    "@pnpm/deps.path": "1100.0.1",
-    "@pnpm/installing.client": "1100.0.3",
+    "@pnpm/fetching.directory-fetcher": "1100.0.4",
     "@pnpm/fs.is-empty-dir-or-nothing": "1100.0.0",
+    "@pnpm/fs.indexed-pkg-importer": "1100.0.3",
     "@pnpm/fs.packlist": "1100.0.0",
-    "@pnpm/catalogs.types": "1100.0.0",
-    "@pnpm/fs.indexed-pkg-importer": "1100.0.2",
-    "@pnpm/engine.runtime.commands": "1100.0.3",
+    "@pnpm/installing.client": "1100.0.4",
+    "@pnpm/installing.commands": "1100.1.2",
+    "@pnpm/lockfile.fs": "1100.0.3",
     "@pnpm/lockfile.types": "1100.0.2",
-    "@pnpm/network.web-auth": "1101.0.0",
     "@pnpm/network.git-utils": "1100.0.0",
+    "@pnpm/network.web-auth": "1101.0.0",
     "@pnpm/releasing.exportable-manifest": "1100.0.2",
-    "@pnpm/types": "1101.0.0",
     "@pnpm/resolving.resolver-base": "1100.1.0",
-    "@pnpm/lockfile.fs": "1100.0.2",
-    "@pnpm/workspace.projects-filter": "1100.0.3",
-    "@pnpm/workspace.projects-sorter": "1100.0.1",
+    "@pnpm/types": "1101.0.0",
     "@pnpm/network.fetch": "1100.0.1",
-    "@pnpm/config.reader": "1101.1.0",
-    "@pnpm/installing.commands": "1100.1.1"
+    "@pnpm/workspace.projects-filter": "1100.0.4",
+    "@pnpm/workspace.projects-sorter": "1100.0.1"
   },
   "peerDependencies": {
     "@pnpm/logger": ">=1001.0.0 <1002.0.0"
@@ -98,14 +98,14 @@
     "load-json-file": "^7.0.1",
     "tar": "^7.5.10",
     "write-yaml-file": "^6.0.0",
-    "@pnpm/hooks.pnpmfile": "1100.0.2",
-    "@pnpm/prepare": "1100.0.2",
-    "@pnpm/assert-project": "1100.0.2",
-    "@pnpm/releasing.commands": "1100.1.0",
+    "@pnpm/catalogs.config": "1100.0.0",
+    "@pnpm/hooks.pnpmfile": "1100.0.3",
+    "@pnpm/prepare": "1100.0.3",
+    "@pnpm/assert-project": "1100.0.3",
     "@pnpm/logger": "1100.0.0",
+    "@pnpm/releasing.commands": "1100.2.1",
     "@pnpm/test-fixtures": "1100.0.0",
     "@pnpm/testing.command-defaults": "1100.0.1",
-    "@pnpm/catalogs.config": "1100.0.0",
     "@pnpm/test-ipc-server": "1100.0.0"
   },
   "engines": {