@pnpm/napi 0.0.0-0 → 12.0.0-alpha.3

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,63 @@
+# @pnpm/napi
+
+Node.js bindings for pnpm v12's Rust engine (pacquet), exposing pnpm's
+programmatic API — install, rebuild, dependency resolution, and pack — to a
+JavaScript host. The reference consumer is [Bit](https://bit.dev), which drives
+pnpm entirely through its programmatic API.
+
+This package binds only pnpm's **engine**. Pure data utilities that operate on
+in-memory objects or the (byte-stable) on-disk lockfile/store formats stay as
+regular `@pnpm/*` JS packages — both stacks share the same lockfile v9 shape,
+`.modules.yaml` format, and store layout.
+
+## API
+
+See [`index.d.ts`](./index.d.ts) for the full typed contract.
+
+| Export | Purpose |
+| --- | --- |
+| `install(options, onLog?, readPackageHook?)` | Install in-memory importers (single or workspace); `readPackageHook` transforms each resolved dependency manifest (must be synchronous). Returns `{ stats, depsRequiringBuild?, storeDir }`. |
+| `rebuild(options, onLog?, selectedNames?)` | Re-run dependency build scripts against a materialized install (frozen path). |
+| `resolveDependency(wanted, options)` | Resolve an npm-registry specifier to `{ id, manifest, resolvedVia, … }`. |
+| `pack(options, onLog?)` | Build a publishable `.tgz` from a project directory. |
+| `parseBareSpecifier(spec, alias?)` | Split/validate a dependency specifier; `null` when unparsable. |
+| `engineVersion()` | Version string of the underlying Rust engine (pacquet). |
+| `getPeerDependencyIssues(options)` | **Not yet implemented** — throws `ERR_PNPM_NAPI_UNIMPLEMENTED`. Peer-issue reporting is not ported in pacquet's CLI either; consumers should degrade gracefully. |
+
+Errors are plain `Error` objects carrying pnpm's `code` (`ERR_PNPM_*`) and,
+where applicable, `hint` — lifted onto the error by the loader from the engine's
+structured envelope.
+
+Auth: pass `authHeaderByUri` — a map of nerf-darted registry URI → `Authorization`
+header value (with `""` for the default registry). The host resolves these from
+its `.npmrc` credentials; the engine applies them as-is.
+
+## Distribution
+
+The addon ships as prebuilt per-platform packages, the same model as the
+`@pnpm/exe.*` CLI packages:
+
+- `index.js` resolves the addon at load time in this order: a
+  `PNPM_NAPI_BINARY` env override, the matching
+  `@pnpm/napi.<platform>` optional dependency, then a local build.
+- CI cross-compiles the addon per target (`napi build --release --target
+  <rust-triple>`), uploads each as `pnpm-napi.<codeTarget>.node` at the repo
+  root, then runs `scripts/generate-packages.mjs` to produce the eight
+  `@pnpm/napi.<platform>` packages and wire them as this wrapper's
+  `optionalDependencies`.
+
+Supported targets: `win32-x64`, `win32-arm64`, `darwin-x64`, `darwin-arm64`,
+`linux-x64`, `linux-arm64`, `linux-x64-musl`, `linux-arm64-musl`.
+
+## Local development
+
+Build the Rust crate and point the loader at the artifact:
+
+```sh
+cargo build -p pacquet-napi --profile napi-release
+cp ../../../target/napi-release/libpacquet_napi.dylib \
+   ./pnpm-napi.darwin-arm64.node   # .so on Linux, .dll on Windows
+node -e "console.log(require('.').engineVersion())"
+```
+
+Or set `PNPM_NAPI_BINARY=/path/to/addon.node`.

package/index.d.ts

@@ -0,0 +1,289 @@
+/**
+ * Node API bindings for the pnpm v12 Rust engine (pacquet).
+ *
+ * Shapes intentionally mirror the pnpm v11 TypeScript programmatic API
+ * (`@pnpm/installing.deps-installer`, `@pnpm/installing.client`) so that
+ * consumers migrating from the TS engine keep their call sites stable.
+ */
+
+export interface PackageManifest {
+  name?: string
+  version?: string
+  dependencies?: Record<string, string>
+  devDependencies?: Record<string, string>
+  optionalDependencies?: Record<string, string>
+  peerDependencies?: Record<string, string>
+  peerDependenciesMeta?: Record<string, { optional?: boolean }>
+  dependenciesMeta?: Record<string, { injected?: boolean }>
+  bundledDependencies?: string[] | boolean
+  scripts?: Record<string, string>
+  bin?: string | Record<string, string>
+  engines?: Record<string, string>
+  os?: string[]
+  cpu?: string[]
+  libc?: string[]
+  [key: string]: unknown
+}
+
+export interface NodeApiProject {
+  /** Absolute path of the importer directory. */
+  rootDir: string
+  /** In-memory manifest; the engine never reads package.json from disk for listed projects. */
+  manifest: PackageManifest
+}
+
+export interface ProxyConfig {
+  httpProxy?: string
+  httpsProxy?: string
+  noProxy?: string | boolean
+}
+
+export interface NetworkConfig {
+  ca?: string | string[]
+  cert?: string | string[]
+  key?: string
+  localAddress?: string
+  strictSsl?: boolean
+  /**
+   * Maximum number of concurrent connections (sockets) to a single registry
+   * origin — pnpm's `maxSockets`. Bounds each `scheme://host[:port]` origin
+   * independently; the global `networkConcurrency` remains the outer cap.
+   */
+  maxSockets?: number
+  networkConcurrency?: number
+  fetchRetries?: number
+  fetchRetryFactor?: number
+  fetchRetryMintimeout?: number
+  fetchRetryMaxtimeout?: number
+  fetchTimeout?: number
+  userAgent?: string
+}
+
+/** A synchronous `readPackage` hook applied to resolved dependency manifests. */
+export type ReadPackageHook = (manifest: PackageManifest) => PackageManifest
+
+/**
+ * Receives engine log events. The event stream is wire-compatible with
+ * `@pnpm/core-loggers` / the bunyan-shaped objects consumed by
+ * `@pnpm/logger`'s streamParser and `@pnpm/cli.default-reporter`.
+ */
+export type LogListener = (event: Record<string, unknown>) => void
+
+export interface SharedEngineOptions {
+  /** Registry routes: `{ default: url, '@scope': url, ... }` */
+  registries?: Record<string, string>
+  /**
+   * Pre-computed `Authorization` header values keyed by nerf-darted registry
+   * URI (`//host/path/`), plus `''` for the default registry — e.g.
+   * `{ '': 'Bearer abc', '//npm.example.com/': 'Basic <base64(user:pass)>' }`. The
+   * host resolves these from its `authConfig`; the engine applies them as-is.
+   */
+  authHeaderByUri?: Record<string, string>
+  proxyConfig?: ProxyConfig
+  networkConfig?: NetworkConfig
+  cacheDir?: string
+}
+
+export interface InstallOptions extends SharedEngineOptions {
+  /** Lockfile / workspace root directory. */
+  dir: string
+  projects: NodeApiProject[]
+  storeDir?: string
+  nodeLinker?: 'hoisted' | 'isolated'
+  hoistPattern?: string[]
+  publicHoistPattern?: string[]
+  /** Packages linked from outside the workspace; excluded from hoisting/pruning. */
+  externalDependencies?: string[]
+  overrides?: Record<string, string>
+  allowBuilds?: Record<string, boolean>
+  dangerouslyAllowAllBuilds?: boolean
+  autoInstallPeers?: boolean
+  excludeLinksFromLockfile?: boolean
+  lockfileOnly?: boolean
+  frozenLockfile?: boolean
+  preferFrozenLockfile?: boolean
+  packageImportMethod?: 'auto' | 'hardlink' | 'copy' | 'clone'
+  preferOffline?: boolean
+  offline?: boolean
+  virtualStoreDirMaxLength?: number
+  peersSuffixMaxLength?: number
+  dedupePeerDependents?: boolean
+  dedupeDirectDeps?: boolean
+  dedupeInjectedDeps?: boolean
+  resolvePeersFromWorkspaceRoot?: boolean
+  injectWorkspacePackages?: boolean
+  hoistWorkspacePackages?: boolean
+  minimumReleaseAge?: number
+  minimumReleaseAgeExclude?: string[]
+  includeOptionalDeps?: boolean
+  ignoreScripts?: boolean
+  /**
+   * Re-resolve the whole dependency graph to the highest in-range version
+   * (pnpm's `update: true` / `depth: Infinity`). The binding takes no package
+   * selectors, so an update always targets every dependency.
+   */
+  update?: boolean
+  /**
+   * pnpm's `depth`. Accepted for API compatibility; it only toggles pnpm's
+   * direct-vs-any-depth selector matching, which has no effect without package
+   * selectors, so it does not change the whole-graph `update` behavior.
+   */
+  depth?: number
+  /**
+   * Fail the install with `ERR_PNPM_UNSUPPORTED_ENGINE` when a dependency's
+   * `engines` / platform constraint the host does not satisfy is required
+   * (rather than warning). Defaults to `false`.
+   */
+  engineStrict?: boolean
+  /**
+   * Node.js version used as the `engines.node` target for the engine check.
+   * Defaults to the version auto-detected from the `node` binary.
+   */
+  nodeVersion?: string
+  /**
+   * `false` installs without creating a `node_modules` directory: the graph
+   * resolves and the lockfile is written, but nothing is materialized.
+   */
+  enableModulesDir?: boolean
+  /**
+   * Install from the lockfile without gating on the `package.json` ↔
+   * `pnpm-lock.yaml` freshness check, so an in-memory manifest that disagrees
+   * with the lockfile does not block the install.
+   */
+  ignorePackageManifest?: boolean
+  /** pnpm home directory. Accepted for compatibility; unused for project installs. */
+  pnpmHomeDir?: string
+  /**
+   * Fail with `ERR_PNPM_IGNORED_BUILDS` when a dependency build script is
+   * blocked. Defaults to `false`: the blocked packages are reported in
+   * `InstallResult.depsRequiringBuild` instead.
+   */
+  strictDepBuilds?: boolean
+  /** Customizations for how peer-dependency mismatches are treated. */
+  peerDependencyRules?: PeerDependencyRules
+}
+
+/** pnpm's `peerDependencyRules`. */
+export interface PeerDependencyRules {
+  ignoreMissing?: string[]
+  allowAny?: string[]
+  allowedVersions?: Record<string, string>
+}
+
+export interface InstallResult {
+  stats: {
+    added: number
+    removed: number
+    linkedToRoot: number
+  }
+  /** Dep paths whose build scripts were skipped and require approval to run. */
+  depsRequiringBuild?: string[]
+  /** The resolved content-addressable store directory used by this install. */
+  storeDir: string
+}
+
+/**
+ * @param onLog receives wire-compatible pnpm log events.
+ * @param readPackageHook a **synchronous** `(manifest) => manifest` transform
+ *   applied to every resolved dependency manifest during resolution (the
+ *   `readPackage` hook). Must return the manifest object, not a promise.
+ */
+export function install(
+  options: InstallOptions,
+  onLog?: LogListener,
+  readPackageHook?: ReadPackageHook,
+): Promise<InstallResult>
+
+/**
+ * Rebuild dependency build scripts against the already-materialized
+ * `node_modules` (frozen path). Takes the same options shape as `install`.
+ * @param selectedNames restrict the rebuild to these package names / build
+ *   keys; omit (or pass an empty array) to rebuild every build-needing package.
+ */
+export function rebuild(
+  options: InstallOptions,
+  onLog?: LogListener,
+  selectedNames?: string[],
+): Promise<void>
+
+export interface PeerIssuesOptions extends SharedEngineOptions {
+  dir: string
+  projects: NodeApiProject[]
+  storeDir?: string
+  overrides?: Record<string, string>
+  peersSuffixMaxLength?: number
+  virtualStoreDirMaxLength?: number
+}
+
+export interface PeerDependencyIssues {
+  missing: Record<string, Array<{ parents: Array<{ name: string; version: string }>; optional: boolean; wantedRange: string }>>
+  bad: Record<string, Array<{ parents: Array<{ name: string; version: string }>; foundVersion: string; resolvedFrom: Array<{ name: string; version: string }>; optional: boolean; wantedRange: string }>>
+  conflicts: string[]
+  intersections: Record<string, string>
+}
+
+export type PeerDependencyIssuesByProjects = Record<string, PeerDependencyIssues>
+
+export function getPeerDependencyIssues(options: PeerIssuesOptions): Promise<PeerDependencyIssuesByProjects>
+
+export interface WantedDependency {
+  alias?: string
+  bareSpecifier?: string
+}
+
+export interface ResolveOptions extends SharedEngineOptions {
+  /** Project/lockfile dir used to resolve `link:`/`file:` and workspace specs. */
+  dir: string
+  /** Return the full packument-derived manifest instead of the abbreviated one. */
+  fullMetadata?: boolean
+}
+
+export interface ResolveResult {
+  id: string
+  manifest?: PackageManifest
+  resolvedVia: string
+  normalizedBareSpecifier?: string
+  latest?: string
+  resolution?: Record<string, unknown>
+}
+
+export function resolveDependency(wanted: WantedDependency, options: ResolveOptions): Promise<ResolveResult>
+
+export interface PackOptions {
+  dir: string
+  workspaceDir?: string
+  /** Destination directory for the tarball (defaults to `dir`). */
+  packDestination?: string
+  /** Exact output path/filename for the tarball. */
+  out?: string
+  ignoreScripts?: boolean
+  packGzipLevel?: number
+  embedReadme?: boolean
+  dryRun?: boolean
+  extraBinPaths?: string[]
+  extraEnv?: Record<string, string>
+}
+
+export interface PackResult {
+  publishedManifest: PackageManifest
+  contents: string[]
+  tarballPath: string
+  unpackedSize: number
+}
+
+export function pack(options: PackOptions, onLog?: LogListener): Promise<PackResult>
+
+export interface ParsedBareSpecifier {
+  alias?: string
+  bareSpecifier?: string
+  name?: string
+  fetchSpec?: string
+  normalizedBareSpecifier?: string
+  type?: string
+}
+
+/** Parses/validates a dependency specifier. Returns null for unparsable input. */
+export function parseBareSpecifier(spec: string, alias?: string): ParsedBareSpecifier | null
+
+/** Version of the underlying Rust engine (pacquet). */
+export function engineVersion(): string

package/index.js

@@ -0,0 +1,169 @@
+'use strict'
+
+// Loader for the pacquet-napi native addon.
+//
+// Resolution order:
+// 1. PNPM_NAPI_BINARY env var — explicit path to a .node file (local dev,
+//    custom builds).
+// 2. A platform package (`@pnpm/napi.<platform>`) installed as an
+//    optionalDependency (release-time; injected by the package generator like
+//    the `@pnpm/exe.*` packages).
+// 3. A locally built artifact next to this file or under the Cargo target dir
+//    (development checkouts).
+
+const path = require('node:path')
+const fs = require('node:fs')
+
+// `'glibc' | 'musl' | null` — `null` when the host isn't Linux or the libc
+// can't be probed (`process.report` may be unavailable/disabled). glibc builds
+// set `glibcVersionRuntime`; musl leaves it unset.
+function detectLinuxLibc() {
+  if (process.platform !== 'linux') return null
+  try {
+    return process.report?.getReport()?.header?.glibcVersionRuntime ? 'glibc' : 'musl'
+  } catch {
+    return null
+  }
+}
+
+// Ordered platform triples to try. On Linux both libc variants are attempted
+// (ordered by detection) so a musl host whose libc can't be probed still
+// resolves the `-musl` addon instead of failing on the glibc one; elsewhere
+// there is a single triple.
+function platformTriples() {
+  const { platform, arch } = process
+  if (platform === 'linux') {
+    const order = detectLinuxLibc() === 'musl' ? ['-musl', ''] : ['', '-musl']
+    return order.map((suffix) => `linux-${arch}${suffix}`)
+  }
+  return [`${platform}-${arch}`]
+}
+
+function tryLoad(candidate, loadErrors) {
+  if (!candidate) return null
+  try {
+    if (candidate.endsWith('.node') && !fs.existsSync(candidate)) return null
+    return require(candidate)
+  } catch (err) {
+    if (isRetryableLoadError(err, candidate)) {
+      loadErrors.push(err)
+      return null
+    }
+    throw err
+  }
+}
+
+function isRetryableLoadError(err, candidate) {
+  if (!err) return false
+  // The candidate isn't installed (platform package absent) — try the next one.
+  if (isMissingCandidate(err, candidate)) return true
+  // The candidate exists but is the wrong libc / ABI: `require()` throws
+  // `ERR_DLOPEN_FAILED`. Fall through to the other Linux libc variant rather
+  // than aborting the whole load on a wrong first guess.
+  return err.code === 'ERR_DLOPEN_FAILED'
+}
+
+function isMissingCandidate(err, candidate) {
+  return (
+    err &&
+    err.code === 'MODULE_NOT_FOUND' &&
+    typeof err.message === 'string' &&
+    err.message.includes(`'${candidate}'`)
+  )
+}
+
+function loadFailure(triple, loadErrors) {
+  const error = new Error(
+    `Failed to load the pnpm Rust engine for ${triple}. ` +
+      'Install the matching @pnpm/napi platform package, or point ' +
+      'PNPM_NAPI_BINARY at a locally built .node file.'
+  )
+  if (loadErrors.length > 0) {
+    error.cause = loadErrors[0]
+  }
+  return error
+}
+
+function loadBinding() {
+  const triples = platformTriples()
+  const loadErrors = []
+  // An explicit PNPM_NAPI_BINARY is strict: it must be a `.node` file (so a
+  // non-.node value can't be require()'d as an arbitrary module), and if it
+  // exists but fails to load we surface that error directly rather than
+  // silently falling back to a platform package.
+  const explicit = process.env.PNPM_NAPI_BINARY
+  if (explicit) {
+    if (!explicit.endsWith('.node')) {
+      throw new Error(`PNPM_NAPI_BINARY must point to a .node addon file, got: ${explicit}`)
+    }
+    if (fs.existsSync(explicit)) {
+      return require(explicit)
+    }
+    loadErrors.push(new Error(`PNPM_NAPI_BINARY was set but not found: ${explicit}`))
+  }
+  // Platform packages / local artifacts. On Linux both libc variants are tried,
+  // so a wrong-ABI first candidate (an `ERR_DLOPEN_FAILED`) falls through to the
+  // other rather than aborting.
+  const candidates = [
+    ...triples.flatMap((triple) => [
+      `@pnpm/napi.${triple}`,
+      path.join(__dirname, `pnpm-napi.${triple}.node`),
+    ]),
+    path.join(__dirname, 'pnpm-napi.node'),
+  ]
+  for (const candidate of candidates) {
+    const binding = tryLoad(candidate, loadErrors)
+    if (binding) return binding
+  }
+  throw loadFailure(triples[0], loadErrors)
+}
+
+// The Rust side encodes structured error fields (code/hint) as a JSON envelope
+// in the thrown error's message, prefixed with PNPM_ERR_JSON:. Lift them back
+// onto the Error object so consumers keep reading `err.code` / `err.hint`.
+const ENVELOPE_PREFIX = 'PNPM_ERR_JSON:'
+function decorateError(err) {
+  if (err && typeof err.message === 'string' && err.message.startsWith(ENVELOPE_PREFIX)) {
+    try {
+      const parsed = JSON.parse(err.message.slice(ENVELOPE_PREFIX.length))
+      if (parsed.code != null) err.code = parsed.code
+      if (parsed.hint != null) err.hint = parsed.hint
+      if (typeof parsed.message === 'string') err.message = parsed.message
+    } catch {
+      // Leave the error untouched if the envelope doesn't parse.
+    }
+  }
+  return err
+}
+
+// Wrap every exported function so both sync throws and rejected promises get
+// the envelope lifted. Non-function exports (if any) pass through unchanged.
+function wrapExports(binding) {
+  const wrapped = {}
+  for (const key of Object.keys(binding)) {
+    const value = binding[key]
+    if (typeof value !== 'function') {
+      wrapped[key] = value
+      continue
+    }
+    wrapped[key] = function (...args) {
+      try {
+        const result = value.apply(this, args)
+        if (result && typeof result.then === 'function') {
+          return result.then(
+            (resolved) => resolved,
+            (err) => {
+              throw decorateError(err)
+            }
+          )
+        }
+        return result
+      } catch (err) {
+        throw decorateError(err)
+      }
+    }
+  }
+  return wrapped
+}
+
+module.exports = wrapExports(loadBinding())

package/package.json

@@ -1,5 +1,42 @@
 {
   "name": "@pnpm/napi",
-  "version": "0.0.0-0",
-  "license": "MIT"
+  "version": "12.0.0-alpha.3",
+  "description": "Node.js addon bindings for the pnpm v12 Rust engine (pacquet)",
+  "keywords": [
+    "pnpm",
+    "package manager",
+    "rust",
+    "napi"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/pnpm/pnpm/tree/main/pacquet",
+  "bugs": "https://github.com/pnpm/pnpm/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pnpm/pnpm",
+    "directory": "pacquet/npm/napi"
+  },
+  "main": "index.js",
+  "types": "index.d.ts",
+  "engines": {
+    "node": ">=18.*"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
+  "optionalDependencies": {
+    "@pnpm/napi.win32-x64": "12.0.0-alpha.3",
+    "@pnpm/napi.win32-arm64": "12.0.0-alpha.3",
+    "@pnpm/napi.darwin-x64": "12.0.0-alpha.3",
+    "@pnpm/napi.darwin-arm64": "12.0.0-alpha.3",
+    "@pnpm/napi.linux-x64": "12.0.0-alpha.3",
+    "@pnpm/napi.linux-arm64": "12.0.0-alpha.3",
+    "@pnpm/napi.linux-x64-musl": "12.0.0-alpha.3",
+    "@pnpm/napi.linux-arm64-musl": "12.0.0-alpha.3"
+  },
+  "scripts": {
+    "generate-packages": "node scripts/generate-packages.mjs"
+  }
 }