@pnpm/napi 12.0.0-rc.8 → 12.0.0-rc.9

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @pnpm/napi
 
+## 12.0.0-rc.9
+
+### Minor Changes
+
+- Added `fetchWarnTimeoutMs` and `fetchMinSpeedKiBps` to the Rust pnpm CLI and its N-API bindings. Slow registry metadata requests and tarball downloads now emit pnpm-compatible warnings without exposing URL credentials, query parameters, fragments, or control characters [pnpm/pnpm#12042](https://github.com/pnpm/pnpm/issues/12042).
+
 ## 12.0.0-rc.8
 
 ## 12.0.0-rc.7

package/README.md

@@ -5,10 +5,20 @@ 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.
+This package binds pnpm's **engine**, and alongside it the pieces of pnpm a
+host would otherwise have to reimplement over that engine: pnpm's terminal
+output (`options.reporter`), its reverse dependency tree (`getDependents` /
+`renderDependents`, what `pnpm why` is built on), and the files it owns —
+`pnpm-lock.yaml` and `.modules.yaml` (`readLockfile` / `writeLockfile` /
+`filterLockfileByImporters` / `readModulesManifest`). The lockfile ones
+include pure in-memory transforms: `filterLockfileByImporters` touches no
+disk at all. They are bound anyway, because the alternative is a second
+implementation of a format the engine writes, kept in step by hand.
+
+What stays a regular `@pnpm/*` JS package is what the engine has no part in:
+type-only packages, and small pure helpers whose call sites are hot enough
+that a boundary crossing per call would cost more than it saves (dep-path
+string parsing runs once per graph edge).
 
 ## API
 
@@ -16,14 +26,61 @@ 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). |
+| `install(options, onLog?, readPackageHook?, onOutput?)` | Install in-memory importers (single or workspace); `readPackageHook` transforms each resolved dependency manifest (must be synchronous). Returns `{ stats, depsRequiringBuild?, storeDir }`. |
+| `rebuild(options, onLog?, selectedNames?, onOutput?)` | 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. |
+| `getDependents(options)` | Every package matching `packages`, each with the reverse tree of what depends on it — the engine side of `pnpm why`. |
+| `renderDependents(trees, options?)` | Return those trees rendered as `pnpm why` renders its own: `tree`, `parseable`, or `json`. |
+| `readLockfile(options)` / `writeLockfile(options)` | Read and write `pnpm-lock.yaml` (or the current lockfile under the virtual store) with the engine's own parser and emitter. |
+| `filterLockfileByImporters(lockfile, importerIds, options?)` | Narrow a lockfile to the transitive closure of what the named importers reach. |
+| `readModulesManifest(modulesDir)` | The `.modules.yaml` state of an installed `node_modules`. |
 | `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. |
 
+### Output
+
+Set `options.reporter` and the engine renders pnpm's own terminal output —
+progress line, packages-diff summary, lifecycle output, the `Done in …`
+footer — with the reporter `pnpm install` itself uses. Without it the call
+prints nothing and `onLog` hands the host the raw event stream to render
+however it likes.
+
+By default the rendered chunks go to stdout. Pass `onOutput` to receive them
+instead, for a host that has redirected its own output at the JavaScript
+level (a monkey-patched `process.stdout.write`, a stream forwarding to a
+remote terminal) where a write from Rust would bypass the redirection. Pass
+`reporter.width` alongside it: the engine cannot see where those chunks end
+up.
+
+### Lockfile
+
+`readLockfile` / `writeLockfile` hand the host the engine's own parser and
+emitter, so it does not carry a second implementation of a file both of them
+own. The JSON crossing the boundary is the file's own shape — `LockfileFile`
+in `@pnpm/lockfile.types` terms — and **top-level keys pnpm does not define
+round-trip untouched**, so a host that records its own state beside the
+lockfile can read it, edit its block, and write it back without losing the
+rest. (An install builds a fresh lockfile rather than rewriting the previous
+one, so a host re-asserts its block afterwards.)
+
+`filterLockfileByImporters` is the engine-side `@pnpm/lockfile.filtering`:
+the named importers keep only the dependency groups asked for, and
+`packages` / `snapshots` are pruned to what they still reach.
+
+### Dependents (`pnpm why`)
+
+`getDependents` returns the reverse trees as plain data and
+`renderDependents` returns them rendered as a string — it prints nothing
+itself — mirroring the split between
+`@pnpm/deps.inspection.tree-builder` and `@pnpm/deps.inspection.list`. The
+split is also what replaces that API's `nameFormatter` callback: the tree
+walk is synchronous Rust and cannot call back into JavaScript, so a host
+that renames nodes after a manifest field asks for the field via
+`manifestFields`, writes `displayName` onto the returned trees, and passes
+them back to be rendered.
+
 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.

package/index.d.ts

@@ -65,6 +65,8 @@ export interface NetworkConfig {
   fetchRetryMintimeout?: number
   fetchRetryMaxtimeout?: number
   fetchTimeout?: number
+  fetchWarnTimeoutMs?: number
+  fetchMinSpeedKiBps?: number
   userAgent?: string
 }
 
@@ -117,6 +119,10 @@ export interface InstallOptions extends SharedEngineOptions {
   dir: string
   projects: NodeApiProject[]
   storeDir?: string
+  /** Slow metadata-request warning threshold in milliseconds. Overrides `networkConfig`. */
+  fetchWarnTimeoutMs?: number
+  /** Minimum average tarball download speed in KiB/s. Overrides `networkConfig`. */
+  fetchMinSpeedKiBps?: number
   nodeLinker?: 'hoisted' | 'isolated'
   /**
    * pnpm's `linkWorkspacePackages`. When `true`/`'deep'`, a bare-semver
@@ -230,6 +236,12 @@ export interface InstallOptions extends SharedEngineOptions {
   returnListOfDepsRequiringBuild?: boolean
   /** Customizations for how peer-dependency mismatches are treated. */
   peerDependencyRules?: PeerDependencyRules
+  /**
+   * Render pnpm's own terminal output for this call. Omitted, the call
+   * prints nothing and the host renders the `onLog` stream itself (or not
+   * at all).
+   */
+  reporter?: ReporterOptions
 }
 
 /** pnpm's `peerDependencyRules`. */
@@ -239,6 +251,85 @@ export interface PeerDependencyRules {
   allowedVersions?: Record<string, string>
 }
 
+
+/**
+ * pnpm's own terminal output, rendered by the engine.
+ *
+ * Without this the host gets only the `onLog` event stream and has to
+ * render it itself — in practice by keeping `@pnpm/logger` and
+ * `@pnpm/cli.default-reporter` and feeding the events into them, a
+ * coupling between one pnpm line's reporter and another's event stream
+ * that the host then has to maintain. Set `reporter` and the engine
+ * renders with the reporter `pnpm install` itself uses.
+ *
+ * Every field maps onto the option of the same name in
+ * `@pnpm/cli.default-reporter`'s `reportingOptions`.
+ */
+export interface ReporterOptions {
+  /**
+   * Print each update on its own line instead of redrawing the frame in
+   * place. Defaults to `true` whenever the output is not a terminal.
+   */
+  appendOnly?: boolean
+  /**
+   * Milliseconds between progress redraws. Defaults to 1000 in
+   * append-only mode and 200 otherwise.
+   */
+  throttleProgress?: number
+  /** Leave the materialized-package count out of the progress line. */
+  hideAddedPkgsProgress?: boolean
+  /** Leave the workspace-project prefix out of progress lines. */
+  hideProgressPrefix?: boolean
+  /**
+   * Keep dependency build-script output in its collapsed block instead of
+   * streaming every line.
+   */
+  hideLifecycleOutput?: boolean
+  /**
+   * Replaces the `Run "pnpm approve-builds"…` line under the list of
+   * packages whose build scripts were blocked, for a host whose users
+   * approve builds through its own configuration.
+   */
+  ignoredBuildsInstructionText?: string
+  /**
+   * Package-name patterns whose *linked* entries are left out of the
+   * packages-diff summary — an entry is linked when it was symlinked in
+   * rather than materialized from the store. A host that links its own
+   * runtime into every project silences that noise without silencing the
+   * same packages when they are really installed. The Rust counterpart of
+   * the TypeScript reporter's `filterPkgsDiff` callback, which cannot
+   * cross the addon boundary.
+   */
+  hideLinkedPkgsDiff?: string[]
+  /** Verbosity ceiling. Defaults to `'info'`. */
+  logLevel?: 'error' | 'warn' | 'info' | 'debug'
+  /**
+   * Width to wrap at, at least one column. Defaults to the output stream's
+   * width when it is a terminal, else 80. Pass it explicitly alongside
+   * `onOutput`: the engine cannot see where those chunks end up.
+   */
+  width?: number
+  /**
+   * Whether to emit ANSI color. Defaults to "the output stream is a
+   * terminal and `NO_COLOR` is unset"; with `onOutput`, to `false`.
+   */
+  color?: boolean
+  /** Render on stderr rather than stdout. Ignored when `onOutput` is given. */
+  useStderr?: boolean
+  /** Directory paths are rendered relative to. Defaults to `dir`. */
+  cwd?: string
+}
+
+/**
+ * Receives each rendered output chunk instead of the engine writing it to
+ * a file descriptor. For a host that has redirected its own output at the
+ * JavaScript level — a monkey-patched `process.stdout.write`, a stream
+ * that forwards to a remote terminal — where a write from Rust would
+ * bypass the redirection. Chunks arrive in order and already carry their
+ * newlines and cursor-control sequences; write them verbatim.
+ */
+export type OutputListener = (chunk: string) => void
+
 export interface InstallResult {
   stats: {
     added: number
@@ -262,11 +353,14 @@ export interface InstallResult {
  * @param readPackageHook a **synchronous** `(manifest, resolvedDir?) => manifest`
  *   transform applied to every resolved dependency manifest during resolution
  *   (the `readPackage` hook). Must return the manifest object, not a promise.
+ * @param onOutput receives the rendered output of `options.reporter`
+ *   instead of the engine writing it to stdout/stderr.
  */
 export function install(
   options: InstallOptions,
   onLog?: LogListener,
   readPackageHook?: ReadPackageHook,
+  onOutput?: OutputListener,
 ): Promise<InstallResult>
 
 /**
@@ -279,6 +373,7 @@ export function rebuild(
   options: InstallOptions,
   onLog?: LogListener,
   selectedNames?: string[],
+  onOutput?: OutputListener,
 ): Promise<void>
 
 export interface PeerIssuesOptions extends SharedEngineOptions {
@@ -423,6 +518,8 @@ export interface ResolvedConfig {
   fetchRetryMintimeout: number
   fetchRetryMaxtimeout: number
   fetchTimeout: number
+  fetchWarnTimeoutMs: number
+  fetchMinSpeedKiBps: number
   /**
    * The explicitly configured user agent, when the cascade set one. The
    * engine's own computed default is omitted — an embedder that passes
@@ -461,5 +558,214 @@ export interface ResolvedConfig {
  */
 export function readConfig(options: ReadConfigOptions): ResolvedConfig
 
+/**
+ * Inputs for {@link getDependents} — the engine side of `pnpm why`.
+ *
+ * The reverse tree is pure lockfile analysis, so a host that asks the
+ * engine for it needs neither `@pnpm/deps.inspection.tree-builder` and
+ * `@pnpm/deps.inspection.list` nor the `@pnpm/lockfile.fs` /
+ * `@pnpm/installing.modules-yaml` readers that feed them.
+ */
+export interface DependentsOptions {
+  /** Lockfile / workspace root directory. */
+  dir: string
+  /** Package selectors to search for: a name, or `name@range`. */
+  packages: string[]
+  /**
+   * Importer directories to walk from. Absolute, or relative to `dir`.
+   * Omitted means every importer the lockfile records.
+   */
+  projectDirs?: string[]
+  /**
+   * Importer-id patterns to skip when `projectDirs` is omitted, in pnpm's
+   * `hoistPattern` glob syntax (`*` is the only wildcard). Lets a host keep
+   * its own generated importers out of the answer without reading the
+   * lockfile itself to enumerate the rest.
+   */
+  excludeProjectPatterns?: string[]
+  /** `node_modules` directory. Defaults to `<dir>/node_modules`. */
+  modulesDir?: string
+  /** Follow `dependencies` edges. Defaults to `true`. */
+  includeDependencies?: boolean
+  /** Follow `devDependencies` edges. Defaults to `true`. */
+  includeDevDependencies?: boolean
+  /** Follow `optionalDependencies` edges. Defaults to `true`. */
+  includeOptionalDependencies?: boolean
+  /** Registry routes, used to reconstruct tarball URLs. */
+  registries?: Record<string, string>
+  /** Fallback when `.modules.yaml` records no value. */
+  virtualStoreDirMaxLength?: number
+  /**
+   * `package.json` fields to project onto every package node as
+   * `manifest`. This is what the TypeScript tree-builder's `nameFormatter`
+   * callback is for: the walk is synchronous Rust and cannot call back
+   * into JavaScript, so a host that renames nodes after a manifest field
+   * asks for that field here, writes `displayName` on the returned trees,
+   * and passes them to {@link renderDependents}. Nodes whose manifest is
+   * unreadable — and every workspace-project node — carry none.
+   */
+  manifestFields?: string[]
+}
+
+/** One entry of a {@link DependentsTree}'s reverse tree. */
+export interface DependentNode {
+  name: string
+  /** Rendered in place of `name`, when set. */
+  displayName?: string
+  version: string
+  /** The node was reached again on its own path; the walk stopped there. */
+  circular?: boolean
+  /** Short hash distinguishing peer-dependency variants of a `name@version`. */
+  peersSuffixHash?: string
+  /** The node is expanded elsewhere in the tree and shown here as a leaf. */
+  deduped?: boolean
+  /** For a workspace-project leaf: which manifest field declares the edge. */
+  depField?: 'dependencies' | 'devDependencies' | 'optionalDependencies'
+  dependents?: DependentNode[]
+  /** The `manifestFields` projection of this node's `package.json`. */
+  manifest?: Record<string, unknown>
+}
+
+/** One matched package and everything that depends on it. */
+export interface DependentsTree {
+  name: string
+  /** Rendered in place of `name`, when set. */
+  displayName?: string
+  version: string
+  /** Resolved filesystem path of the package. */
+  path?: string
+  peersSuffixHash?: string
+  dependents: DependentNode[]
+  /** Message returned by a `--find-by` finder, when one matched. */
+  searchMessage?: string
+  /** See {@link DependentNode.manifest}. */
+  manifest?: Record<string, unknown>
+}
+
+/**
+ * Every package matching `packages`, each with the reverse tree of what
+ * depends on it. An empty array when the directory has no lockfile: an
+ * un-installed workspace has no dependents to report, which is an answer
+ * rather than an error.
+ */
+export function getDependents(options: DependentsOptions): Promise<DependentsTree[]>
+
+export interface RenderDependentsOptions {
+  /** Defaults to `'tree'`. */
+  format?: 'tree' | 'parseable' | 'json'
+  /** Max display depth. Omitted renders the whole tree. */
+  depth?: number
+  /** Include description / repository / homepage / path for each root. */
+  long?: boolean
+}
+
+/**
+ * Render trees from {@link getDependents} — after any `displayName` the
+ * caller wrote onto them — the way `pnpm why` renders its own.
+ */
+export function renderDependents(
+  trees: DependentsTree[],
+  options?: RenderDependentsOptions,
+): string
+
+/**
+ * A `pnpm-lock.yaml` as JSON — the file's own shape, which is
+ * `LockfileFile` in `@pnpm/lockfile.types` terms: each importer dependency
+ * is an `{ specifier, version }` pair, and `packages` (metadata) and
+ * `snapshots` (edges) are separate maps. There is no in-memory-only
+ * variant to convert to or from.
+ *
+ * Top-level keys pnpm does not define are preserved, so a host that
+ * records its own state beside the lockfile can read it, edit its own
+ * block, and write the file back without losing anything else.
+ *
+ * The lockfile functions are generic over this so a host that already has
+ * a precise type for the format — `LockfileFile` from
+ * `@pnpm/lockfile.types`, or its own extension of it — can name it rather
+ * than casting: `readLockfile<MyLockfile>({ dir })`.
+ */
+export type LockfileFile = Record<string, unknown>
+
+export interface ReadLockfileOptions {
+  /** Lockfile / workspace root directory. */
+  dir: string
+  /**
+   * `'wanted'` (the default) reads `<dir>/pnpm-lock.yaml`, what the
+   * workspace asks for. `'current'` reads
+   * `<modulesDir>/.pnpm/lock.yaml`, what the last install actually
+   * materialized.
+   */
+  kind?: 'wanted' | 'current'
+  /**
+   * `node_modules` directory, which the current lockfile lives under.
+   * Absolute, or relative to `dir`. Defaults to `<dir>/node_modules`.
+   */
+  modulesDir?: string
+}
+
+export interface WriteLockfileOptions<Lockfile = LockfileFile> {
+  /** Lockfile / workspace root directory. */
+  dir: string
+  /** The lockfile to write, in the shape {@link readLockfile} returns. */
+  lockfile: Lockfile
+  /** See {@link ReadLockfileOptions.kind}. */
+  kind?: 'wanted' | 'current'
+  /** See {@link ReadLockfileOptions.modulesDir}. */
+  modulesDir?: string
+}
+
+/** `null` when the lockfile is absent or empty. */
+export function readLockfile<Lockfile = LockfileFile>(
+  options: ReadLockfileOptions,
+): Promise<Lockfile | null>
+
+/** Write the lockfile, formatted exactly as an install writes it. */
+export function writeLockfile<Lockfile = LockfileFile>(
+  options: WriteLockfileOptions<Lockfile>,
+): Promise<void>
+
+export interface FilterLockfileOptions {
+  /** Whether the listed importers keep their `dependencies`. Default `true`. */
+  includeDependencies?: boolean
+  /** Whether they keep their `devDependencies`. Default `true`. */
+  includeDevDependencies?: boolean
+  /** Whether they keep their `optionalDependencies`. Default `true`. */
+  includeOptionalDependencies?: boolean
+  /**
+   * Dep paths to treat as already visited — the optional dependencies this
+   * platform did not install. Neither they nor anything reachable only
+   * through them is kept.
+   */
+  skipped?: string[]
+  /**
+   * Whether a dependency reference with no `snapshots` entry fails with
+   * `ERR_PNPM_LOCKFILE_MISSING_DEPENDENCY`. Defaults to `false`, which
+   * drops the reference and keeps walking — what a caller inspecting a
+   * possibly-stale lockfile wants.
+   */
+  failOnMissingDependencies?: boolean
+}
+
+/**
+ * The lockfile narrowed to what `importerIds` reaches: those importers keep
+ * only the dependency groups asked for, and `packages` / `snapshots` are
+ * pruned to the transitive closure of what they still depend on. Every
+ * other importer entry is carried through untouched — the filter narrows
+ * the package graph, not the workspace.
+ *
+ * Synchronous: a transform over data the caller already holds.
+ */
+export function filterLockfileByImporters<Lockfile = LockfileFile>(
+  lockfile: Lockfile,
+  importerIds: string[],
+  options?: FilterLockfileOptions,
+): Lockfile
+
+/**
+ * The `.modules.yaml` state of an installed `node_modules`, or `null` when
+ * the directory has none.
+ */
+export function readModulesManifest(modulesDir: string): Promise<Record<string, unknown> | null>
+
 /** Version of the underlying Rust engine (pacquet). */
 export function engineVersion(): string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pnpm/napi",
-  "version": "12.0.0-rc.8",
+  "version": "12.0.0-rc.9",
   "description": "Node.js addon bindings for the pnpm v12 Rust engine (pacquet)",
   "keywords": [
     "pnpm",
@@ -28,14 +28,14 @@
     "THIRD-PARTY-NOTICES.md"
   ],
   "optionalDependencies": {
-    "@pnpm/napi.win32-x64": "12.0.0-rc.8",
-    "@pnpm/napi.win32-arm64": "12.0.0-rc.8",
-    "@pnpm/napi.darwin-x64": "12.0.0-rc.8",
-    "@pnpm/napi.darwin-arm64": "12.0.0-rc.8",
-    "@pnpm/napi.linux-x64": "12.0.0-rc.8",
-    "@pnpm/napi.linux-arm64": "12.0.0-rc.8",
-    "@pnpm/napi.linux-x64-musl": "12.0.0-rc.8",
-    "@pnpm/napi.linux-arm64-musl": "12.0.0-rc.8"
+    "@pnpm/napi.win32-x64": "12.0.0-rc.9",
+    "@pnpm/napi.win32-arm64": "12.0.0-rc.9",
+    "@pnpm/napi.darwin-x64": "12.0.0-rc.9",
+    "@pnpm/napi.darwin-arm64": "12.0.0-rc.9",
+    "@pnpm/napi.linux-x64": "12.0.0-rc.9",
+    "@pnpm/napi.linux-arm64": "12.0.0-rc.9",
+    "@pnpm/napi.linux-x64-musl": "12.0.0-rc.9",
+    "@pnpm/napi.linux-arm64-musl": "12.0.0-rc.9"
   },
   "scripts": {
     "generate-packages": "node scripts/generate-packages.mjs"