@fexd/toolchain 0.1.0

package/README.md

@@ -0,0 +1,144 @@
+# @fexd/toolchain
+
+`@fexd/toolchain` 是一个面向前端项目的工具链运行器，用于让项目脚本固定使用指定版本的 Node.js 和 pnpm。
+
+它适合这种场景：不同项目依赖不同的 Node.js / pnpm 版本，但开发者希望自己的全局 shell 环境保持不变。通过 `tc` 执行的命令只会在当前子进程中使用项目指定的工具链，不会切换或污染全局 `node` / `pnpm`。
+
+## 特性
+
+- 按项目固定 Node.js 版本。
+- 按项目固定 pnpm 版本。
+- 不依赖 `nvm`、`fnm` 或 Corepack。
+- 不修改当前 shell 的全局 `node` / `pnpm`。
+- 支持 Windows、macOS 和 Linux。
+- 支持嵌套脚本中的 `pnpm` 命令继续使用项目指定版本。
+- 自动下载并缓存所需的 Node.js 和 pnpm。
+
+## 安装
+
+```bash
+pnpm add -D @fexd/toolchain
+```
+
+也可以使用 npm：
+
+```bash
+npm install -D @fexd/toolchain
+```
+
+## 配置
+
+在项目根目录的 `.npmrc` 中配置工具链版本：
+
+```ini
+tc-version-node=20.19.5
+tc-version-pnpm=9.15.9
+```
+
+字段说明：
+
+- `tc-version-node`：项目脚本使用的 Node.js 版本。
+- `tc-version-pnpm`：项目脚本使用的 pnpm 版本。
+
+## 使用
+
+在 `package.json` scripts 中通过 `tc` 执行命令：
+
+```json
+{
+  "scripts": {
+    "toolchain:versions": "tc doctor && npm run toolchain:node && npm run toolchain:pnpm",
+    "toolchain:node": "tc node -v",
+    "toolchain:pnpm": "tc pnpm -v",
+    "install:deps": "tc pnpm install",
+    "dev": "tc pnpm dev",
+    "build": "tc pnpm build"
+  }
+}
+```
+
+常用命令：
+
+```bash
+tc doctor
+tc node -v
+tc node scripts/build.js
+tc pnpm -v
+tc pnpm install
+tc pnpm run build
+```
+
+## 嵌套脚本
+
+`tc` 会在子进程的 `PATH` 前面放入项目指定版本的 pnpm shim。因此通过 `tc pnpm` 启动的脚本中，如果继续执行 `pnpm`，仍然会使用 `.npmrc` 中配置的 pnpm 版本。
+
+例如：
+
+```json
+{
+  "scripts": {
+    "dev": "tc pnpm exec concurrently \"pnpm --filter @app/web dev\" \"pnpm --filter @app/server dev\""
+  }
+}
+```
+
+上面两个内层 `pnpm` 命令都会使用项目指定的 pnpm 版本。
+
+## 工作方式
+
+执行 `tc` 时会按以下流程运行：
+
+1. 从当前目录向上查找项目根目录。
+2. 读取项目 `.npmrc` 中的 `tc-version-node` 和 `tc-version-pnpm`。
+3. 检查本地缓存中是否已有对应版本的 Node.js 和 pnpm。
+4. 如果缓存不存在，则自动下载并解压。
+5. 使用指定 Node.js 启动目标命令。
+6. 为目标命令注入临时 `PATH`，确保子进程优先使用指定 Node.js 和 pnpm。
+
+命令结束后，当前 shell 的全局 `node` / `pnpm` 版本不会变化。
+
+## 缓存目录
+
+默认缓存位置：
+
+- Windows：`%LOCALAPPDATA%\fexd-toolchain`
+- macOS：`~/Library/Caches/fexd-toolchain`
+- Linux：`${XDG_CACHE_HOME:-~/.cache}/fexd-toolchain`
+
+可以通过 `TC_HOME` 指定缓存目录：
+
+```bash
+TC_HOME=/path/to/toolchain-cache tc doctor
+```
+
+## 下载源
+
+默认下载源：
+
+- Node.js：`https://nodejs.org/dist`
+- pnpm：`https://registry.npmjs.org`
+
+可以通过环境变量配置镜像：
+
+```bash
+TC_NODE_MIRROR=https://nodejs.org/dist
+TC_NPM_REGISTRY=https://registry.npmjs.org
+```
+
+## Roadmap
+
+当前版本聚焦于 Node.js 和 pnpm 的项目级版本管理。后续可以继续扩展到更多项目运行所需的外部工具链：
+
+- JDK：支持通过 `.npmrc` 指定项目需要的 Java 版本，并在执行脚本时注入 `JAVA_HOME`。
+- Android SDK：支持管理 Android platform、build-tools、platform-tools 等 SDK 组件。
+- Android NDK：支持为 native 构建固定 NDK 版本。
+- Python：支持为 `node-gyp`、native addon 等构建场景固定 Python 版本，并注入 `PYTHON` 环境变量。
+
+这些能力会继续遵循当前定位：只管理项目脚本运行所需的外部工具链，不替代包管理器，也不管理已经适合放在 `devDependencies` 中的普通前端依赖。
+
+## 注意事项
+
+- 启动 `tc` 本身需要本机已有可用的 Node.js。
+- 启动 `tc` 的 Node.js 版本需要满足 `>=14.17`。
+- 第一次使用某个 Node.js / pnpm 版本时需要联网下载。
+- 为了让 scripts 跨平台，建议在脚本中写 `pnpm`，不要写死 `pnpm.cmd`。

package/bin/tc.cjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+const { runCli } = require('../src/cli.cjs');
+
+runCli(process.argv.slice(2)).then((exitCode) => {
+  process.exitCode = exitCode;
+}, (error) => {
+  console.error(error && error.stack ? error.stack : error);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@fexd/toolchain",
+  "version": "0.1.0",
+  "description": "Run project scripts with a project-pinned Node.js and pnpm toolchain.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fexd-team/toolchain.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fexd-team/toolchain/issues"
+  },
+  "homepage": "https://github.com/fexd-team/toolchain#readme",
+  "bin": {
+    "tc": "bin/tc.cjs",
+    "fexd-toolchain": "bin/tc.cjs"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node test/run-tests.cjs"
+  },
+  "engines": {
+    "node": ">=14.17"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/skills/migrate-to-fexd-toolchain/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: migrate-to-fexd-toolchain
+description: Use when converting an existing JavaScript or TypeScript project to @fexd/toolchain, tc, or package.json scripts that pin Node.js and pnpm versions, especially when replacing nvm, fnm, corepack, pnpm.cmd, direct node, or direct pnpm commands while preserving cross-platform behavior.
+---
+
+# Migrate To FEXD Toolchain
+
+## Goal
+
+Convert an existing project so its package scripts run through `@fexd/toolchain`:
+
+- project scripts use the configured Node.js and pnpm versions;
+- the user's interactive shell keeps its global `node` and `pnpm`;
+- Windows and macOS scripts stay portable;
+- unrelated project changes are preserved.
+
+## Inspect First
+
+Before editing, read:
+
+- `package.json`
+- `.npmrc`, if present
+- `.node-version` and `.nvmrc`, if present
+- lockfiles and package-manager metadata
+- `git status --short`
+
+Do not revert unrelated dirty files. If a dirty file must be edited, inspect it first and preserve the user's changes.
+
+## Version Sources
+
+Prefer version sources in this order:
+
+1. existing `.npmrc` values: `tc-version-node`, `tc-version-pnpm`
+2. user-provided versions
+3. `packageManager` for the pnpm version
+4. `.node-version` or `.nvmrc` for the Node.js version
+5. `engines.node` only when it pins a concrete version
+
+If the pnpm version exists in both `.npmrc` and `packageManager`, keep them consistent or ask before choosing one.
+
+Update `.npmrc` without removing unrelated npm settings:
+
+```ini
+tc-version-node=20.19.5
+tc-version-pnpm=9.15.9
+```
+
+Keep `packageManager` when it is useful for standard package-manager metadata:
+
+```json
+{
+  "packageManager": "pnpm@9.15.9"
+}
+```
+
+## Script Rewrite Rules
+
+Rewrite only commands that need the project-pinned Node.js or pnpm.
+
+| Before | After |
+| --- | --- |
+| `node script.js` | `tc node script.js` |
+| `pnpm install` | `tc pnpm install` |
+| `pnpm run build` | `tc pnpm run build` |
+| `pnpm --filter @pkg dev` | `tc pnpm --filter @pkg dev` |
+| `pnpm exec prettier ...` | `tc pnpm exec prettier ...` |
+| `pnpm.cmd ...` | `tc pnpm ...` |
+| `fnm exec node ...` | `tc node ...` |
+| `fnm exec pnpm ...` | `tc pnpm ...` |
+| `fnm exec pnpm.cmd ...` | `tc pnpm ...` |
+| `corepack pnpm@x ...` | `tc pnpm ...` |
+
+For nested scripts, keep the outer command under `tc` and use plain `pnpm` inside quoted child commands:
+
+```json
+{
+  "dev": "tc pnpm exec concurrently \"pnpm --filter @app/web dev\" \"pnpm --filter @app/server dev\""
+}
+```
+
+Use plain `pnpm`, not `pnpm.cmd`, inside scripts so the same `package.json` works on Windows and macOS. `tc pnpm` injects a pinned pnpm shim into the child process `PATH`.
+
+## What Not To Wrap
+
+Do not wrap commands that are intentionally system tools:
+
+- `open`
+- `xcrun`
+- `xcodebuild`
+- `ios-deploy`
+- `idevicedebug`
+- `idevicesyslog`
+- `adb`
+- `gradlew` or `./gradlew`, unless the command itself is launched through a pnpm script that needs `tc pnpm`
+
+Do not make `tc` manage ordinary npm dependencies such as `vite`, `webpack`, `rollup`, `eslint`, `prettier`, `typescript`, `husky`, or project-specific CLIs. Run them through `tc pnpm exec` or existing package scripts.
+
+## Dependency Handling
+
+If `@fexd/toolchain` is not already available in the project, add it as a dev dependency using the project's package manager:
+
+```bash
+pnpm add -D @fexd/toolchain
+```
+
+If the user explicitly asks for a local package link, use the local path they provide instead of adding a registry dependency.
+
+## Validation
+
+After migration, run the smallest checks that prove the scripts use `tc` correctly:
+
+```bash
+npm run toolchain:versions
+```
+
+Run one lightweight real project script, such as a small build or package build:
+
+```bash
+npm run build:bridge
+```
+
+Verify nested `pnpm` through a shell command on Windows, because `child_process.execFileSync('pnpm')` does not necessarily resolve `.cmd` files:
+
+```bash
+tc pnpm exec node -e "require('child_process').execSync('pnpm -v', {stdio:'inherit'})"
+```
+
+Optionally confirm the interactive shell is unchanged:
+
+```bash
+node -v
+pnpm -v
+```
+
+Report validation output, remaining warnings, and any unrelated dirty files left untouched.
+
+## Common Mistakes
+
+- Replacing inner quoted `pnpm.cmd` with another `pnpm.cmd`; use plain `pnpm`.
+- Wrapping macOS/iOS system commands in `tc`.
+- Removing existing `.npmrc` settings while adding toolchain versions.
+- Treating `engines.node` ranges such as `>=16` as exact install versions.
+- Deleting `.node-version` or `.nvmrc` without confirming they are obsolete for the project.
+- Using global `pnpm` to test a project whose global pnpm version is known to be incompatible.

package/src/cache.cjs

@@ -0,0 +1,57 @@
+const os = require('os');
+const path = require('path');
+const { getNodeExecutableRelativePath, getPnpmDistribution } = require('./distributions.cjs');
+
+const CACHE_DIR_NAME = 'fexd-toolchain';
+
+function getDefaultCacheRoot(options) {
+  const opts = options || {};
+  const platform = opts.platform || process.platform;
+  const env = opts.env || process.env;
+  const home = opts.home || os.homedir();
+
+  if (env.TC_HOME) {
+    return path.resolve(env.TC_HOME);
+  }
+
+  if (platform === 'win32') {
+    return path.join(env.LOCALAPPDATA || path.join(home, 'AppData', 'Local'), CACHE_DIR_NAME);
+  }
+
+  if (platform === 'darwin') {
+    return path.join(home, 'Library', 'Caches', CACHE_DIR_NAME);
+  }
+
+  return path.join(env.XDG_CACHE_HOME || path.join(home, '.cache'), CACHE_DIR_NAME);
+}
+
+function getNodePaths(cacheRoot, distribution) {
+  const installDir = path.join(
+    cacheRoot,
+    'node',
+    distribution.version,
+    distribution.platform + '-' + distribution.arch,
+    distribution.folderName
+  );
+
+  return {
+    installDir,
+    executablePath: path.join(installDir, getNodeExecutableRelativePath(distribution))
+  };
+}
+
+function getPnpmPaths(cacheRoot, version) {
+  const distribution = getPnpmDistribution(version);
+  const installDir = path.join(cacheRoot, 'pnpm', distribution.version);
+
+  return {
+    installDir,
+    executablePath: path.join(installDir, distribution.executableRelativePath)
+  };
+}
+
+module.exports = {
+  getDefaultCacheRoot,
+  getNodePaths,
+  getPnpmPaths
+};

package/src/cli.cjs

@@ -0,0 +1,170 @@
+const path = require('path');
+const childProcess = require('child_process');
+const { readToolchainConfig } = require('./config.cjs');
+const { getDefaultCacheRoot } = require('./cache.cjs');
+const { ensureNode, ensurePnpm } = require('./install.cjs');
+const { ensurePnpmShim, buildToolchainPath } = require('./shims.cjs');
+
+async function runCli(argv, dependencies) {
+  const deps = dependencies || {};
+  const args = Array.isArray(argv) ? argv.slice() : [];
+  const command = args.shift();
+  const stdout = deps.stdout || process.stdout;
+  const stderr = deps.stderr || process.stderr;
+  const platform = deps.platform || process.platform;
+  const arch = deps.arch || process.arch;
+  const env = Object.assign({}, deps.env || process.env);
+  const cwd = deps.cwd || process.cwd();
+
+  if (!command || command === '--help' || command === '-h') {
+    stdout.write(usage());
+    return 0;
+  }
+
+  if (command !== 'doctor' && command !== 'node' && command !== 'pnpm') {
+    stderr.write('Unknown command: ' + command + '\n\n' + usage());
+    return 1;
+  }
+
+  let config;
+  try {
+    config = (deps.readToolchainConfig || readToolchainConfig)(cwd);
+  } catch (error) {
+    stderr.write(formatError(error) + '\n');
+    return 1;
+  }
+
+  if (command === 'doctor') {
+    stdout.write([
+      'Project: ' + config.root,
+      'Config: ' + (config.npmrcPath || '(missing .npmrc)'),
+      'Node.js: ' + (config.nodeVersion || '(missing tc-version-node)'),
+      'pnpm: ' + (config.pnpmVersion || '(missing tc-version-pnpm)'),
+      ''
+    ].join('\n'));
+    return config.nodeVersion && config.pnpmVersion ? 0 : 1;
+  }
+
+  if (!config.nodeVersion) {
+    stderr.write('Missing tc-version-node in ' + (config.npmrcPath || 'project .npmrc') + '\n');
+    return 1;
+  }
+
+  if (command === 'pnpm' && !config.pnpmVersion) {
+    stderr.write('Missing tc-version-pnpm in ' + (config.npmrcPath || 'project .npmrc') + '\n');
+    return 1;
+  }
+
+  const cacheRoot = (deps.getDefaultCacheRoot || getDefaultCacheRoot)({
+    platform,
+    env
+  });
+
+  try {
+    const node = await (deps.ensureNode || ensureNode)({
+      version: config.nodeVersion,
+      cacheRoot,
+      platform,
+      arch
+    });
+
+    if (command === 'node') {
+      return spawnAndReturn({
+        spawnSync: deps.spawnSync || childProcess.spawnSync,
+        command: node.executablePath,
+        args,
+        cwd,
+        env: withPath(env, path.dirname(node.executablePath), null, platform),
+        stdio: deps.stdio || 'inherit'
+      });
+    }
+
+    const pnpm = await (deps.ensurePnpm || ensurePnpm)({
+      version: config.pnpmVersion,
+      cacheRoot
+    });
+    const shim = (deps.ensurePnpmShim || ensurePnpmShim)({
+      cacheRoot,
+      nodeVersion: config.nodeVersion,
+      pnpmVersion: config.pnpmVersion,
+      platform,
+      arch,
+      nodePath: node.executablePath,
+      pnpmCliPath: pnpm.executablePath
+    });
+
+    return spawnAndReturn({
+      spawnSync: deps.spawnSync || childProcess.spawnSync,
+      command: node.executablePath,
+      args: [pnpm.executablePath].concat(args),
+      cwd,
+      env: withPath(env, path.dirname(node.executablePath), shim.dir, platform),
+      stdio: deps.stdio || 'inherit'
+    });
+  } catch (error) {
+    stderr.write(formatError(error) + '\n');
+    return 1;
+  }
+}
+
+function spawnAndReturn(options) {
+  const result = options.spawnSync(options.command, options.args, {
+    cwd: options.cwd,
+    env: options.env,
+    stdio: options.stdio
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  return typeof result.status === 'number' ? result.status : 0;
+}
+
+function withPath(env, nodeBinDir, shimDir, platform) {
+  const nextEnv = Object.assign({}, env);
+  const pathKey = findPathKey(nextEnv, platform);
+  nextEnv[pathKey] = buildToolchainPath({
+    currentPath: nextEnv[pathKey],
+    shimDir,
+    nodeBinDir,
+    delimiter: getPathDelimiter(platform)
+  });
+  return nextEnv;
+}
+
+function findPathKey(env, platform) {
+  if (platform === 'win32') {
+    const existing = Object.keys(env).find((key) => key.toLowerCase() === 'path');
+    return existing || 'Path';
+  }
+
+  return 'PATH';
+}
+
+function getPathDelimiter(platform) {
+  return platform === 'win32' ? ';' : ':';
+}
+
+function formatError(error) {
+  return error && error.message ? error.message : String(error);
+}
+
+function usage() {
+  return [
+    'Usage:',
+    '  tc doctor',
+    '  tc node <args...>',
+    '  tc pnpm <args...>',
+    '',
+    'Project .npmrc:',
+    '  tc-version-node=20.19.5',
+    '  tc-version-pnpm=9.15.9',
+    ''
+  ].join('\n');
+}
+
+module.exports = {
+  runCli,
+  usage
+};

package/src/config.cjs

@@ -0,0 +1,61 @@
+const fs = require('fs');
+const path = require('path');
+const { parseNpmrcText } = require('./npmrc.cjs');
+
+function parentOf(directory) {
+  const parent = path.dirname(directory);
+  return parent === directory ? null : parent;
+}
+
+function hasToolchainConfig(npmrcConfig) {
+  return Boolean(npmrcConfig['tc-version-node'] || npmrcConfig['tc-version-pnpm']);
+}
+
+function findProjectRoot(startDirectory) {
+  let current = path.resolve(startDirectory || process.cwd());
+  let nearestPackageRoot = null;
+
+  while (current) {
+    const packageJsonPath = path.join(current, 'package.json');
+    if (!nearestPackageRoot && fs.existsSync(packageJsonPath)) {
+      nearestPackageRoot = current;
+    }
+
+    const npmrcPath = path.join(current, '.npmrc');
+    if (fs.existsSync(npmrcPath)) {
+      const npmrcConfig = parseNpmrcText(fs.readFileSync(npmrcPath, 'utf8'));
+      if (hasToolchainConfig(npmrcConfig)) {
+        return current;
+      }
+    }
+
+    current = parentOf(current);
+  }
+
+  return nearestPackageRoot;
+}
+
+function readToolchainConfig(startDirectory) {
+  const root = findProjectRoot(startDirectory);
+
+  if (!root) {
+    throw new Error('Could not find a package.json or .npmrc from ' + path.resolve(startDirectory || process.cwd()));
+  }
+
+  const npmrcPath = path.join(root, '.npmrc');
+  const npmrcConfig = fs.existsSync(npmrcPath)
+    ? parseNpmrcText(fs.readFileSync(npmrcPath, 'utf8'))
+    : {};
+
+  return {
+    root,
+    nodeVersion: npmrcConfig['tc-version-node'] || '',
+    pnpmVersion: npmrcConfig['tc-version-pnpm'] || '',
+    npmrcPath: fs.existsSync(npmrcPath) ? npmrcPath : null
+  };
+}
+
+module.exports = {
+  findProjectRoot,
+  readToolchainConfig
+};

package/src/distributions.cjs

@@ -0,0 +1,81 @@
+const DEFAULT_NODE_MIRROR = 'https://nodejs.org/dist';
+const DEFAULT_NPM_REGISTRY = 'https://registry.npmjs.org';
+
+function normalizeNodeVersion(version) {
+  const clean = String(version || '').trim();
+  return clean.startsWith('v') ? clean.slice(1) : clean;
+}
+
+function mapNodeArch(arch) {
+  if (arch === 'x64' || arch === 'arm64') {
+    return arch;
+  }
+
+  throw new Error('Unsupported CPU architecture for Node.js downloads: ' + arch);
+}
+
+function getNodeDistribution(options) {
+  const version = normalizeNodeVersion(options.version);
+  const platform = options.platform || process.platform;
+  const arch = mapNodeArch(options.arch || process.arch);
+  const mirror = (options.mirror || process.env.TC_NODE_MIRROR || DEFAULT_NODE_MIRROR).replace(/\/+$/, '');
+
+  if (!version) {
+    throw new Error('Node.js version is required');
+  }
+
+  let platformPart;
+  let extension;
+
+  if (platform === 'win32') {
+    platformPart = 'win';
+    extension = 'zip';
+  } else if (platform === 'darwin') {
+    platformPart = 'darwin';
+    extension = 'tar.gz';
+  } else if (platform === 'linux') {
+    platformPart = 'linux';
+    extension = 'tar.xz';
+  } else {
+    throw new Error('Unsupported platform for Node.js downloads: ' + platform);
+  }
+
+  const folderName = 'node-v' + version + '-' + platformPart + '-' + arch;
+  const fileName = folderName + '.' + extension;
+
+  return {
+    version,
+    platform,
+    arch,
+    fileName,
+    folderName,
+    url: mirror + '/v' + version + '/' + fileName
+  };
+}
+
+function getNodeExecutableRelativePath(distribution) {
+  return distribution.platform === 'win32' ? 'node.exe' : 'bin/node';
+}
+
+function getPnpmDistribution(version, registry) {
+  const cleanVersion = String(version || '').trim();
+  const cleanRegistry = (registry || process.env.TC_NPM_REGISTRY || DEFAULT_NPM_REGISTRY).replace(/\/+$/, '');
+
+  if (!cleanVersion) {
+    throw new Error('pnpm version is required');
+  }
+
+  return {
+    version: cleanVersion,
+    fileName: 'pnpm-' + cleanVersion + '.tgz',
+    folderName: 'package',
+    url: cleanRegistry + '/pnpm/-/pnpm-' + cleanVersion + '.tgz',
+    executableRelativePath: 'package/bin/pnpm.cjs'
+  };
+}
+
+module.exports = {
+  getNodeDistribution,
+  getNodeExecutableRelativePath,
+  getPnpmDistribution
+};

package/src/install.cjs

@@ -0,0 +1,134 @@
+const fs = require('fs');
+const http = require('http');
+const https = require('https');
+const path = require('path');
+const childProcess = require('child_process');
+const { getNodeDistribution, getPnpmDistribution } = require('./distributions.cjs');
+const { getNodePaths, getPnpmPaths } = require('./cache.cjs');
+
+async function ensureNode(options) {
+  const opts = options || {};
+  const distribution = getNodeDistribution({
+    version: opts.version,
+    platform: opts.platform,
+    arch: opts.arch
+  });
+  const paths = getNodePaths(opts.cacheRoot, distribution);
+
+  if (fs.existsSync(paths.executablePath)) {
+    return {
+      distribution,
+      executablePath: paths.executablePath,
+      installDir: paths.installDir,
+      reused: true
+    };
+  }
+
+  const download = opts.downloadFile || downloadFile;
+  const extract = opts.extractArchive || extractArchive;
+  const archivePath = path.join(opts.cacheRoot, 'downloads', distribution.fileName);
+
+  fs.mkdirSync(path.dirname(archivePath), { recursive: true });
+  fs.mkdirSync(path.dirname(paths.installDir), { recursive: true });
+
+  await download(distribution.url, archivePath);
+  await extract(archivePath, path.dirname(paths.installDir));
+
+  if (!fs.existsSync(paths.executablePath)) {
+    throw new Error('Node.js install did not produce expected executable: ' + paths.executablePath);
+  }
+
+  return {
+    distribution,
+    executablePath: paths.executablePath,
+    installDir: paths.installDir,
+    reused: false
+  };
+}
+
+async function ensurePnpm(options) {
+  const opts = options || {};
+  const distribution = getPnpmDistribution(opts.version);
+  const paths = getPnpmPaths(opts.cacheRoot, distribution.version);
+
+  if (fs.existsSync(paths.executablePath)) {
+    return {
+      distribution,
+      executablePath: paths.executablePath,
+      installDir: paths.installDir,
+      reused: true
+    };
+  }
+
+  const download = opts.downloadFile || downloadFile;
+  const extract = opts.extractArchive || extractArchive;
+  const archivePath = path.join(opts.cacheRoot, 'downloads', distribution.fileName);
+
+  fs.mkdirSync(path.dirname(archivePath), { recursive: true });
+  fs.mkdirSync(paths.installDir, { recursive: true });
+
+  await download(distribution.url, archivePath);
+  await extract(archivePath, paths.installDir);
+
+  if (!fs.existsSync(paths.executablePath)) {
+    throw new Error('pnpm install did not produce expected CLI: ' + paths.executablePath);
+  }
+
+  return {
+    distribution,
+    executablePath: paths.executablePath,
+    installDir: paths.installDir,
+    reused: false
+  };
+}
+
+function downloadFile(url, destination) {
+  const client = url.startsWith('https:') ? https : http;
+
+  return new Promise((resolve, reject) => {
+    const request = client.get(url, (response) => {
+      if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+        response.resume();
+        downloadFile(response.headers.location, destination).then(resolve, reject);
+        return;
+      }
+
+      if (response.statusCode !== 200) {
+        response.resume();
+        reject(new Error('Download failed with HTTP ' + response.statusCode + ': ' + url));
+        return;
+      }
+
+      fs.mkdirSync(path.dirname(destination), { recursive: true });
+      const stream = fs.createWriteStream(destination);
+      response.pipe(stream);
+      stream.on('finish', () => stream.close(resolve));
+      stream.on('error', reject);
+    });
+
+    request.on('error', reject);
+  });
+}
+
+function extractArchive(archivePath, destination) {
+  fs.mkdirSync(destination, { recursive: true });
+
+  const result = childProcess.spawnSync('tar', ['-xf', archivePath, '-C', destination], {
+    stdio: 'inherit'
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  if (result.status !== 0) {
+    throw new Error('Failed to extract archive: ' + archivePath);
+  }
+}
+
+module.exports = {
+  ensureNode,
+  ensurePnpm,
+  downloadFile,
+  extractArchive
+};

package/src/npmrc.cjs

@@ -0,0 +1,30 @@
+function parseNpmrcText(text) {
+  const result = {};
+  const lines = String(text || '').split(/\r?\n/);
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+
+    if (!line || line.startsWith('#') || line.startsWith(';')) {
+      continue;
+    }
+
+    const separatorIndex = line.indexOf('=');
+    if (separatorIndex < 0) {
+      continue;
+    }
+
+    const key = line.slice(0, separatorIndex).trim();
+    const value = line.slice(separatorIndex + 1).trim();
+
+    if (key) {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+module.exports = {
+  parseNpmrcText
+};

package/src/shims.cjs

@@ -0,0 +1,61 @@
+const fs = require('fs');
+const path = require('path');
+
+function ensurePnpmShim(options) {
+  const opts = options || {};
+  const platform = opts.platform || process.platform;
+  const arch = opts.arch || process.arch;
+  const dir = path.join(
+    opts.cacheRoot,
+    'shims',
+    'node-' + opts.nodeVersion,
+    'pnpm-' + opts.pnpmVersion,
+    platform + '-' + arch
+  );
+
+  fs.mkdirSync(dir, { recursive: true });
+
+  if (platform === 'win32') {
+    const command = path.join(dir, 'pnpm.cmd');
+    const content = [
+      '@echo off',
+      '"' + opts.nodePath + '" "' + opts.pnpmCliPath + '" %*',
+      ''
+    ].join('\r\n');
+
+    fs.writeFileSync(command, content, 'utf8');
+    return { dir, command };
+  }
+
+  const command = path.join(dir, 'pnpm');
+  const content = [
+    '#!/bin/sh',
+    "exec " + shellQuote(opts.nodePath) + " " + shellQuote(opts.pnpmCliPath) + ' "$@"',
+    ''
+  ].join('\n');
+
+  fs.writeFileSync(command, content, { encoding: 'utf8', mode: 0o755 });
+  try {
+    fs.chmodSync(command, 0o755);
+  } catch (error) {
+    // Best effort on filesystems that do not support POSIX modes.
+  }
+
+  return { dir, command };
+}
+
+function shellQuote(value) {
+  return "'" + String(value).replace(/'/g, "'\\''") + "'";
+}
+
+function buildToolchainPath(options) {
+  const opts = options || {};
+  const delimiter = opts.delimiter || path.delimiter;
+  const segments = [opts.shimDir, opts.nodeBinDir, opts.currentPath].filter(Boolean);
+  return segments.join(delimiter);
+}
+
+module.exports = {
+  ensurePnpmShim,
+  buildToolchainPath
+};