@pnpm/engine.runtime.node-resolver 1001.0.5

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-2016 Rico Sta. Cruz and other contributors
+Copyright (c) 2016-2026 Zoltan Kochan and other contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# @pnpm/engine.runtime.node-resolver
+
+> Resolves a Node.js version specifier to an exact Node.js version
+
+[![npm version](https://img.shields.io/npm/v/@pnpm/engine.runtime.node-resolver.svg)](https://www.npmjs.com/package/@pnpm/engine.runtime.node-resolver)
+
+## Installation
+
+```sh
+pnpm add @pnpm/engine.runtime.node-resolver
+```
+
+## License
+
+MIT

package/lib/getNodeArtifactAddress.d.ts

@@ -0,0 +1,13 @@
+export interface NodeArtifactAddress {
+    basename: string;
+    extname: string;
+    dirname: string;
+}
+export interface GetNodeArtifactAddressOptions {
+    version: string;
+    baseUrl: string;
+    platform: string;
+    arch: string;
+    libc?: string;
+}
+export declare function getNodeArtifactAddress({ version, baseUrl, platform, arch, libc }: GetNodeArtifactAddressOptions): NodeArtifactAddress;

package/lib/getNodeArtifactAddress.js

@@ -0,0 +1,13 @@
+import { getNormalizedArch } from './normalizeArch.js';
+export function getNodeArtifactAddress({ version, baseUrl, platform, arch, libc, }) {
+    const isWindowsPlatform = platform === 'win32';
+    const normalizedPlatform = isWindowsPlatform ? 'win' : platform;
+    const normalizedArch = getNormalizedArch(platform, arch, version);
+    const archSuffix = libc === 'musl' ? '-musl' : '';
+    return {
+        dirname: `${baseUrl}v${version}`,
+        basename: `node-v${version}-${normalizedPlatform}-${normalizedArch}${archSuffix}`,
+        extname: isWindowsPlatform ? '.zip' : '.tar.gz',
+    };
+}
+//# sourceMappingURL=getNodeArtifactAddress.js.map

package/lib/getNodeMirror.d.ts

@@ -0,0 +1,2 @@
+import type { Config } from '@pnpm/config.reader';
+export declare function getNodeMirror(rawConfig: Config['rawConfig'], releaseChannel: string): string;

package/lib/getNodeMirror.js

@@ -0,0 +1,10 @@
+export function getNodeMirror(rawConfig, releaseChannel) {
+    // This is a dynamic lookup since the 'use-node-version' option is allowed to be '<releaseChannel>/<version>'
+    const configKey = `node-mirror:${releaseChannel}`;
+    const nodeMirror = rawConfig[configKey] ?? `https://nodejs.org/download/${releaseChannel}/`;
+    return normalizeNodeMirror(nodeMirror);
+}
+function normalizeNodeMirror(nodeMirror) {
+    return nodeMirror.endsWith('/') ? nodeMirror : `${nodeMirror}/`;
+}
+//# sourceMappingURL=getNodeMirror.js.map

package/lib/index.d.ts

@@ -0,0 +1,19 @@
+import type { FetchFromRegistry } from '@pnpm/fetching.types';
+import type { ResolveOptions, ResolveResult, VariationsResolution, WantedDependency } from '@pnpm/resolving.resolver-base';
+import { getNodeArtifactAddress } from './getNodeArtifactAddress.js';
+import { getNodeMirror } from './getNodeMirror.js';
+import { parseNodeSpecifier } from './parseNodeSpecifier.js';
+export { getNodeArtifactAddress, getNodeMirror, parseNodeSpecifier };
+export declare const DEFAULT_NODE_MIRROR_BASE_URL = "https://nodejs.org/download/release/";
+export declare const UNOFFICIAL_NODE_MIRROR_BASE_URL = "https://unofficial-builds.nodejs.org/download/release/";
+export interface NodeRuntimeResolveResult extends ResolveResult {
+    resolution: VariationsResolution;
+    resolvedVia: 'nodejs.org';
+}
+export declare function resolveNodeRuntime(ctx: {
+    fetchFromRegistry: FetchFromRegistry;
+    rawConfig: Record<string, string>;
+    offline?: boolean;
+}, wantedDependency: WantedDependency, opts?: Partial<ResolveOptions>): Promise<NodeRuntimeResolveResult | null>;
+export declare function resolveNodeVersion(fetch: FetchFromRegistry, versionSpec: string, nodeMirrorBaseUrl?: string): Promise<string | null>;
+export declare function resolveNodeVersions(fetch: FetchFromRegistry, versionSpec?: string, nodeMirrorBaseUrl?: string): Promise<string[]>;

package/lib/index.js

@@ -0,0 +1,168 @@
+import { getNodeBinsForCurrentOS } from '@pnpm/constants';
+import { fetchShasumsFile } from '@pnpm/crypto.shasums-file';
+import { PnpmError } from '@pnpm/error';
+import semver from 'semver';
+import versionSelectorType from 'version-selector-type';
+import { getNodeArtifactAddress } from './getNodeArtifactAddress.js';
+import { getNodeMirror } from './getNodeMirror.js';
+import { parseNodeSpecifier } from './parseNodeSpecifier.js';
+export { getNodeArtifactAddress, getNodeMirror, parseNodeSpecifier };
+export const DEFAULT_NODE_MIRROR_BASE_URL = 'https://nodejs.org/download/release/';
+export const UNOFFICIAL_NODE_MIRROR_BASE_URL = 'https://unofficial-builds.nodejs.org/download/release/';
+export async function resolveNodeRuntime(ctx, wantedDependency, opts) {
+    if (wantedDependency.alias !== 'node' || !wantedDependency.bareSpecifier?.startsWith('runtime:'))
+        return null;
+    if (opts?.currentPkg && !opts.update) {
+        return {
+            id: opts.currentPkg.id,
+            resolution: opts.currentPkg.resolution,
+            resolvedVia: 'nodejs.org',
+        };
+    }
+    if (ctx.offline)
+        throw new PnpmError('NO_OFFLINE_NODEJS_RESOLUTION', 'Offline Node.js resolution is not supported');
+    const versionSpec = wantedDependency.bareSpecifier.substring('runtime:'.length);
+    const { releaseChannel, versionSpecifier } = parseNodeSpecifier(versionSpec);
+    const nodeMirrorBaseUrl = getNodeMirror(ctx.rawConfig, releaseChannel);
+    const version = await resolveNodeVersion(ctx.fetchFromRegistry, versionSpecifier, nodeMirrorBaseUrl);
+    if (!version) {
+        throw new PnpmError('NODEJS_VERSION_NOT_FOUND', `Could not find a Node.js version that satisfies ${versionSpec}`);
+    }
+    const variants = await readNodeAssets(ctx.fetchFromRegistry, nodeMirrorBaseUrl, version);
+    const range = version === versionSpec ? version : `^${version}`;
+    return {
+        id: `node@runtime:${version}`,
+        normalizedBareSpecifier: `runtime:${range}`,
+        resolvedVia: 'nodejs.org',
+        manifest: {
+            name: 'node',
+            version,
+            bin: getNodeBinsForCurrentOS(),
+        },
+        resolution: {
+            type: 'variations',
+            variants,
+        },
+    };
+}
+async function readNodeAssets(fetch, nodeMirrorBaseUrl, version) {
+    const assets = await readNodeAssetsFromMirror(fetch, { nodeMirrorBaseUrl, version, muslOnly: false });
+    // When using the default mirror, also fetch musl variants from unofficial-builds.nodejs.org,
+    // since musl builds are not available on the official mirror.
+    if (nodeMirrorBaseUrl === DEFAULT_NODE_MIRROR_BASE_URL) {
+        try {
+            const muslAssets = await readNodeAssetsFromMirror(fetch, { nodeMirrorBaseUrl: UNOFFICIAL_NODE_MIRROR_BASE_URL, version, muslOnly: true });
+            assets.push(...muslAssets);
+        }
+        catch {
+            // Musl variants may not be available for all Node.js versions (e.g. very old ones)
+        }
+    }
+    return assets;
+}
+async function readNodeAssetsFromMirror(fetch, opts) {
+    const { nodeMirrorBaseUrl, version, muslOnly } = opts;
+    const integritiesFileUrl = `${nodeMirrorBaseUrl}v${version}/SHASUMS256.txt`;
+    const shasumsFileItems = await fetchShasumsFile(fetch, integritiesFileUrl);
+    const escaped = version.replace(/\\/g, '\\\\').replace(/\./g, '\\.');
+    // The second capture group uses [^.-]+ to stop at a dash, so that the optional
+    // third group can capture the '-musl' suffix separately (e.g. 'x64' + '-musl').
+    const pattern = new RegExp(`^node-v${escaped}-([^-.]+)-([^.-]+)(-musl)?\\.(?:tar\\.gz|zip)$`);
+    const assets = [];
+    for (const { integrity, fileName } of shasumsFileItems) {
+        const match = pattern.exec(fileName);
+        if (!match)
+            continue;
+        let [, platform, arch, muslSuffix] = match;
+        if (platform === 'win') {
+            platform = 'win32';
+        }
+        const isMusl = muslSuffix != null;
+        if (muslOnly && !isMusl)
+            continue;
+        const libc = isMusl ? 'musl' : undefined;
+        const address = getNodeArtifactAddress({
+            version,
+            baseUrl: nodeMirrorBaseUrl,
+            platform,
+            arch,
+            libc,
+        });
+        const url = `${address.dirname}/${address.basename}${address.extname}`;
+        const resolution = {
+            type: 'binary',
+            archive: address.extname === '.zip' ? 'zip' : 'tarball',
+            bin: getNodeBinsForCurrentOS(platform),
+            integrity,
+            url,
+        };
+        if (resolution.archive === 'zip') {
+            resolution.prefix = address.basename;
+        }
+        const target = {
+            os: platform,
+            cpu: arch,
+            ...(libc != null && { libc }),
+        };
+        assets.push({
+            targets: [target],
+            resolution,
+        });
+    }
+    return assets;
+}
+const SEMVER_OPTS = {
+    includePrerelease: true,
+    loose: true,
+};
+export async function resolveNodeVersion(fetch, versionSpec, nodeMirrorBaseUrl) {
+    const allVersions = await fetchAllVersions(fetch, nodeMirrorBaseUrl);
+    if (versionSpec === 'latest') {
+        return allVersions[0].version;
+    }
+    const { versions, versionRange } = filterVersions(allVersions, versionSpec);
+    return semver.maxSatisfying(versions, versionRange, SEMVER_OPTS) ?? null;
+}
+export async function resolveNodeVersions(fetch, versionSpec, nodeMirrorBaseUrl) {
+    const allVersions = await fetchAllVersions(fetch, nodeMirrorBaseUrl);
+    if (!versionSpec) {
+        return allVersions.map(({ version }) => version);
+    }
+    if (versionSpec === 'latest') {
+        return [allVersions[0].version];
+    }
+    const { versions, versionRange } = filterVersions(allVersions, versionSpec);
+    return versions.filter(version => semver.satisfies(version, versionRange, SEMVER_OPTS));
+}
+async function fetchAllVersions(fetch, nodeMirrorBaseUrl) {
+    const response = await fetch(`${nodeMirrorBaseUrl ?? 'https://nodejs.org/download/release/'}index.json`);
+    return (await response.json()).map(({ version, lts }) => ({
+        version: version.substring(1),
+        lts,
+    }));
+}
+function filterVersions(versions, versionSelector) {
+    if (versionSelector === 'lts') {
+        return {
+            versions: versions
+                .filter(({ lts }) => lts !== false)
+                .map(({ version }) => version),
+            versionRange: '*',
+        };
+    }
+    const vst = versionSelectorType(versionSelector);
+    if (vst?.type === 'tag') {
+        const wantedLtsVersion = vst.normalized.toLowerCase();
+        return {
+            versions: versions
+                .filter(({ lts }) => typeof lts === 'string' && lts.toLowerCase() === wantedLtsVersion)
+                .map(({ version }) => version),
+            versionRange: '*',
+        };
+    }
+    return {
+        versions: versions.map(({ version }) => version),
+        versionRange: versionSelector,
+    };
+}
+//# sourceMappingURL=index.js.map

package/lib/normalizeArch.d.ts

@@ -0,0 +1 @@
+export declare function getNormalizedArch(platform: string, arch: string, nodeVersion?: string): string;

package/lib/normalizeArch.js

@@ -0,0 +1,16 @@
+export function getNormalizedArch(platform, arch, nodeVersion) {
+    if (nodeVersion) {
+        const nodeMajorVersion = +nodeVersion.split('.')[0];
+        if ((platform === 'darwin' && arch === 'arm64' && (nodeMajorVersion < 16))) {
+            return 'x64';
+        }
+    }
+    if (platform === 'win32' && arch === 'ia32') {
+        return 'x86';
+    }
+    if (arch === 'arm') {
+        return 'armv7l';
+    }
+    return arch;
+}
+//# sourceMappingURL=normalizeArch.js.map

package/lib/parseNodeSpecifier.d.ts

@@ -0,0 +1,5 @@
+export interface NodeSpecifier {
+    releaseChannel: string;
+    versionSpecifier: string;
+}
+export declare function parseNodeSpecifier(specifier: string): NodeSpecifier;

package/lib/parseNodeSpecifier.js

@@ -0,0 +1,39 @@
+import { PnpmError } from '@pnpm/error';
+const RELEASE_CHANNELS = ['nightly', 'rc', 'test', 'v8-canary', 'release'];
+const isStableVersion = (version) => /^\d+\.\d+\.\d+$/.test(version);
+export function parseNodeSpecifier(specifier) {
+    // Handle "channel/version" format: "rc/18", "rc/18.0.0-rc.4", "release/22.0.0", "nightly/latest"
+    if (specifier.includes('/')) {
+        const [releaseChannel, versionSpecifier] = specifier.split('/', 2);
+        if (!RELEASE_CHANNELS.includes(releaseChannel)) {
+            throw new PnpmError('INVALID_NODE_RELEASE_CHANNEL', `"${releaseChannel}" is not a valid Node.js release channel`, {
+                hint: `Valid release channels are: ${RELEASE_CHANNELS.join(', ')}`,
+            });
+        }
+        return { releaseChannel, versionSpecifier };
+    }
+    // Exact prerelease version with a recognized release channel suffix.
+    // e.g. "22.0.0-rc.4", "22.0.0-nightly20250315d765e70802", "22.0.0-v8-canary2025..."
+    const prereleaseChannelMatch = specifier.match(/^\d+\.\d+\.\d+-(nightly|rc|test|v8-canary)/);
+    if (prereleaseChannelMatch != null) {
+        return { releaseChannel: prereleaseChannelMatch[1], versionSpecifier: specifier };
+    }
+    // Exact stable version: "22.0.0"
+    if (isStableVersion(specifier)) {
+        return { releaseChannel: 'release', versionSpecifier: specifier };
+    }
+    // Standalone release channel name means "latest from that channel".
+    // e.g. "nightly" → latest nightly, "rc" → latest rc, "release" → latest release
+    if (RELEASE_CHANNELS.includes(specifier)) {
+        return { releaseChannel: specifier, versionSpecifier: 'latest' };
+    }
+    // Well-known version aliases on the stable release channel
+    if (specifier === 'lts' || specifier === 'latest') {
+        return { releaseChannel: 'release', versionSpecifier: specifier };
+    }
+    // Semver ranges ("18", "^18", ">=18", "18.x") and LTS codenames ("argon", "iron", "hydrogen")
+    // are all passed through as versionSpecifier on the release channel.
+    // Any truly invalid input will fail at resolution time with NODEJS_VERSION_NOT_FOUND.
+    return { releaseChannel: 'release', versionSpecifier: specifier };
+}
+//# sourceMappingURL=parseNodeSpecifier.js.map

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@pnpm/engine.runtime.node-resolver",
+  "version": "1001.0.5",
+  "description": "Resolves a Node.js version specifier to an exact Node.js version",
+  "keywords": [
+    "pnpm",
+    "pnpm11",
+    "env",
+    "node.js"
+  ],
+  "license": "MIT",
+  "funding": "https://opencollective.com/pnpm",
+  "repository": "https://github.com/pnpm/pnpm/tree/main/engine/runtime/node-resolver",
+  "homepage": "https://github.com/pnpm/pnpm/tree/main/engine/runtime/node-resolver#readme",
+  "bugs": {
+    "url": "https://github.com/pnpm/pnpm/issues"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "files": [
+    "lib",
+    "!*.map"
+  ],
+  "dependencies": {
+    "semver": "^7.7.2",
+    "version-selector-type": "^3.0.0",
+    "@pnpm/config.reader": "1004.4.2",
+    "@pnpm/crypto.shasums-file": "1001.0.2",
+    "@pnpm/constants": "1001.3.1",
+    "@pnpm/error": "1000.0.5",
+    "@pnpm/fetching.types": "1000.2.0",
+    "@pnpm/types": "1000.9.0",
+    "@pnpm/resolving.resolver-base": "1005.1.0"
+  },
+  "devDependencies": {
+    "@types/semver": "7.7.1",
+    "@pnpm/engine.runtime.node-resolver": "1001.0.5",
+    "@pnpm/network.fetch": "1000.2.6"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "jest": {
+    "preset": "@pnpm/jest-config"
+  },
+  "scripts": {
+    "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\"",
+    "_test": "cross-env NODE_OPTIONS=\"$NODE_OPTIONS --experimental-vm-modules --disable-warning=ExperimentalWarning --disable-warning=DEP0169\" jest",
+    "test": "pnpm run compile && pnpm run _test",
+    "compile": "tsgo --build && pnpm run lint --fix"
+  }
+}