Walkthrough

This PR implements scoped package registry support across the pnpm/pacquet codebase. It extends the config schema to store per-scope registry routes, parses them from .npmrc files, pnpm-workspace.yaml, and CLI arguments, then updates package-manager operations to select and use the appropriate registry for each package throughout dependency resolution, installation, and updates.

Changes

Scoped registries implementation

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• pnpm/pnpm#11806: Both PRs extend the CLI ConfigOverrides flow in pacquet/crates/cli/src/config_overrides.rs to apply registry configuration; the referenced PR adds the foundational override layer for registry, while this PR extends it to handle scoped :registry keys and overlay them onto Config.registries.

Suggested reviewers

• KSXGitHub

Poem

🐇 Hops excitedly through registry routes

Scoped packages hop along their registry trails,
while @private friends find their proper homes—
no more lost in the default alone!
The config now remembers which scope goes where,
from .npmrc to workspace yaml to CLI whispers.
🎯✨

• X
• Mastodon
• Reddit
• LinkedIn

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Description

Both tarball_url_and_integrity and collect_outdated rebuild a registries HashMap from
config.resolved_registries() on hot per-item paths (per-package install resolution and
per-dependency outdated checks). This causes repeated cloning/allocation overhead that scales with
package/dependency count and is avoidable because the registry routing configuration is immutable
for the command run.

Code

pacquet/crates/package-manager/src/install_package_by_snapshot.rs[R607-614]

+            let registries: HashMap<String, String> =
+                config.resolved_registries().into_iter().collect();
+            let name = package_key.name.to_string();
+            let registry = pick_registry_for_package(&registries, &name, None);
+            let registry = registry.strip_suffix('/').unwrap_or(&registry);
            let version = package_key.suffix.version();
-            let bare_name = name.bare.as_str();
+            let bare_name = package_key.name.bare.as_str();
            let tarball_url = format!("{registry}/{name}/-/{bare_name}-{version}.tgz");

Evidence

The cited helper for registry/tarball resolution constructs a new registries map each time it runs,
and because it is invoked from the per-package install loop, that cloning/allocation repeats once
per package during snapshot materialization. Similarly, in collect_outdated the registries
HashMap is built inside the dependency-mapped async closure used for the fan-out
(join_all(fetches)), meaning the same map construction runs once per dependency fetch rather than
once per command invocation, multiplying overhead with the number of dependencies.

pacquet/crates/package-manager/src/install_package_by_snapshot.rs[293-297]
pacquet/crates/package-manager/src/install_package_by_snapshot.rs[606-615]
pacquet/crates/cli/src/cli_args/outdated.rs[126-138]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`tarball_url_and_integrity` and `collect_outdated` currently build a fresh `HashMap<String, String>` from `config.resolved_registries()` on per-item execution paths (per-package install resolution and per-dependency outdated checks). This repeatedly clones the same registry routing configuration and allocates a new map many times within a single command, even though the registries mapping is effectively immutable for the duration of the run.

## Issue Context
- In the install/materialization path, `tarball_url_and_integrity` is called as part of handling each package’s registry/tarball resolution, so rebuilding the registries map repeats per package.
- In `outdated`, the registries map is constructed inside the dependency fan-out async closure, so it runs once per dependency fetch; because this command commonly fans out to many concurrent registry requests, the overhead scales with dependency count.
- The registries map may be small, but it is stable across the command, so rebuilding it per package/dependency is unnecessary work.

## Fix Focus Areas
- pacquet/crates/package-manager/src/install_package_by_snapshot.rs[293-316]
- pacquet/crates/package-manager/src/install_package_by_snapshot.rs[592-616]
- pacquet/crates/cli/src/cli_args/outdated.rs[114-158]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

scoped_registry_key and normalize_registry_url are duplicated across CLI overrides, .npmrc
parsing, and workspace YAML parsing, increasing the risk of inconsistent behavior if one copy
changes. This duplication makes future fixes (e.g., stricter validation or URL normalization
changes) easy to apply incompletely.

Code

pacquet/crates/cli/src/config_overrides.rs[R97-104]

+fn scoped_registry_key(key: &str) -> Option<&str> {
+    key.strip_suffix(":registry")
+        .filter(|scope| scope.starts_with('@') && scope.len() > 1 && !scope.contains('/'))
+}
+
+fn normalize_registry_url(registry: &str) -> String {
+    if registry.ends_with('/') { registry.to_string() } else { format!("{registry}/") }
+}

Evidence

The same helper logic is present in multiple places, so a change to one implementation would not
automatically update the others.

pacquet/crates/cli/src/config_overrides.rs[97-104]
pacquet/crates/config/src/npmrc_auth.rs[725-728]
pacquet/crates/config/src/workspace_yaml.rs[951-953]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Multiple modules define their own versions of `scoped_registry_key` and/or `normalize_registry_url`. This creates a drift risk where one path normalizes differently than another.

## Issue Context
These helpers implement routing-critical normalization (trailing slash) and parsing (`@scope:registry` key extraction). Keeping them consistent matters as the feature set grows.

## Fix Focus Areas
- pacquet/crates/cli/src/config_overrides.rs[97-104]
- pacquet/crates/config/src/npmrc_auth.rs[721-728]
- pacquet/crates/config/src/workspace_yaml.rs[951-953]

### Implementation sketch
- Move `normalize_registry_url` (and optionally `scoped_registry_key`) into a shared crate/module (e.g., `pacquet_config` or `pacquet_resolving_npm_resolver::registry_url`).
- Re-export as needed and replace local implementations with calls to the shared helpers.
- Keep existing behavior identical (especially the scope validation predicate and trailing-slash policy).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

• Parse scoped registry routes from .npmrc, pnpm-workspace.yaml, and --config.@scope:registry.
• Thread resolved registry maps through resolution, install/add/update/outdated, snapshots, and
  .modules.yaml.
• Add regression tests ensuring scoped packages use scoped registries and never hit default.

The following are alternative approaches to this PR:

Recommendation: The PR’s approach (store scoped routes on Config, expose a pnpm-shaped resolved_registries(), and reuse the existing pick_registry_for_package logic everywhere) is the right baseline: it keeps routing rules centralized and makes behavior consistent across commands and persistence. Consider a follow-up to deduplicate helper functions (scope key parsing and URL normalization) to avoid drift, but it’s reasonable to keep this PR focused on correctness plus regressions.

config_overrides.rs Support --config.@scope:registry overrides and URL normalization +22/-2

Support --config.@scope:registry overrides and URL normalization

• Extends CLI dotted-key override parsing to recognize @scope:registry keys, normalize registry URLs with a trailing slash, and apply scoped overrides into Config.registries.

pacquet/crates/cli/src/config_overrides.rs

---

lib.rs Add scoped registries to Config and expose resolved_registries() +20/-8

Add scoped registries to Config and expose resolved_registries()

• Introduces Config.registries (scoped routes) and a resolved_registries() helper that returns pnpm’s expected map shape: default plus @scope entries. Updates documentation to reflect scoped registry support in .npmrc parsing.

pacquet/crates/config/src/lib.rs

---

npmrc_auth.rs Parse @scope:registry from .npmrc and apply to Config +18/-4

Parse @scope:registry from .npmrc and apply to Config

• Extends .npmrc parsing to capture scoped registry routes into a BTreeMap, normalizes URLs, merges scoped routes across layered .npmrc sources, and applies them into Config during registry application.

pacquet/crates/config/src/npmrc_auth.rs

---

workspace_yaml.rs Support workspace registries map including default and scoped routes +20/-1

Support workspace registries map including default and scoped routes

• Adds WorkspaceSettings.registries, substitutes/filters env placeholders for this map, and applies it into Config (treating "default" as the base registry and others as scoped routes) with URL normalization.

pacquet/crates/config/src/workspace_yaml.rs

---

dlx.rs Use resolved registries map for dlx cache key inputs +1/-2

Use resolved registries map for dlx cache key inputs

• Replaces the hard-coded default registry map with Config::resolved_registries(), ensuring scoped routes participate in dlx’s registries map used for cache keying.

pacquet/crates/cli/src/cli_args/dlx.rs

---

outdated.rs Pick per-package registry when fetching versions for outdated +6/-1

Pick per-package registry when fetching versions for outdated

• Selects the appropriate registry via pick_registry_for_package using the resolved registries map, and fetches package metadata from that registry instead of always using the default registry.

pacquet/crates/cli/src/cli_args/outdated.rs

---

config_deps.rs Pass resolved registries into config dependency resolution +1/-2

Pass resolved registries into config dependency resolution

• Builds the registry map from Config::resolved_registries() rather than a single default entry, enabling scoped registry routing for configurational dependencies.

pacquet/crates/cli/src/config_deps.rs

---

add.rs Route Add latest/version lookup through scoped registry selection +8/-1

Route Add latest/version lookup through scoped registry selection

• Uses Config::resolved_registries() plus pick_registry_for_package to fetch latest versions from the correct registry instead of always hitting the default registry.

pacquet/crates/package-manager/src/add.rs

---

build_resolution_verifiers.rs Provide verifier full resolved registries map +1/-6

Provide verifier full resolved registries map

• Replaces the previous minimal {default} map with Config::resolved_registries(), enabling verifier behavior consistent with scoped routing configuration.

pacquet/crates/package-manager/src/build_resolution_verifiers.rs

---

install.rs Persist full resolved registries into .modules.yaml +1/-1

Persist full resolved registries into .modules.yaml

• Writes Modules.registries as the full resolved registries map (default + scopes) rather than only the default registry entry.

pacquet/crates/package-manager/src/install.rs

---

install_package_by_snapshot.rs Use scoped registry base when reconstructing tarball URLs from snapshots +7/-3

Use scoped registry base when reconstructing tarball URLs from snapshots

• Updates tarball_url_and_integrity to select the correct registry for a registry resolution via pick_registry_for_package, ensuring reconstructed tarball URLs use scoped registry bases for scoped packages.

pacquet/crates/package-manager/src/install_package_by_snapshot.rs

---

install_with_fresh_lockfile.rs Thread resolved registries through fresh-lockfile resolution and hooks +3/-3

Thread resolved registries through fresh-lockfile resolution and hooks

• Builds the registries map using resolved_registries() for the resolver prefetch phase and passes the full map into the pre-resolution hook context JSON instead of only default.

pacquet/crates/package-manager/src/install_with_fresh_lockfile.rs

---

update.rs Route update latest fetch through scoped registry selection +5/-1

Route update latest fetch through scoped registry selection

• Updates the update flow’s latest-version fetch to pick the correct registry based on package scope using the resolved registries map.

pacquet/crates/package-manager/src/update.rs

---

tests.rs Add tests for scoped registry CLI overrides +29/-0

Add tests for scoped registry CLI overrides

• Adds unit tests verifying that --config.@scope:registry is parsed, normalized (trailing slash), and overrides existing scoped registry config.

pacquet/crates/cli/src/config_overrides/tests.rs

---

tests.rs Test .npmrc scoped registry parsing and env-placeholder filtering +21/-1

Test .npmrc scoped registry parsing and env-placeholder filtering

• Adds coverage ensuring scoped registry routes are parsed and applied with URL normalization, and updates env-placeholder filtering expectations to target scoped registries.

pacquet/crates/config/src/npmrc_auth/tests.rs

---

tests.rs Test parsing and application of registries from workspace YAML +35/-0

Test parsing and application of registries from workspace YAML

• Adds tests verifying registries.default and scoped entries are read from YAML, applied to Config with trailing slashes, and that env-placeholder entries are removed while literal scoped entries remain.

pacquet/crates/config/src/workspace_yaml/tests.rs

---

tests.rs Regression: add uses scoped registry for scoped packages +122/-0

Regression: add uses scoped registry for scoped packages

• Adds an async test with separate default/scoped mock registries asserting @private/foo requests never hit the default registry and are served by the configured scoped registry.

pacquet/crates/package-manager/src/add/tests.rs

---

tests.rs Regression: install routes scoped packages and persists registries +105/-0

Regression: install routes scoped packages and persists registries

• Adds a lockfile-only install test ensuring scoped packuments are fetched from the scoped registry, updates fixtures to include scoped registries, and asserts .modules.yaml contains the scoped entry.

pacquet/crates/package-manager/src/install/tests.rs

---

tests.rs Test snapshot tarball URL reconstruction uses scoped registry +19/-2

Test snapshot tarball URL reconstruction uses scoped registry

• Adds a unit test asserting a scoped package’s reconstructed tarball URL uses the configured scoped registry instead of the default registry base.

pacquet/crates/package-manager/src/install_package_by_snapshot/tests.rs

---

tests.rs Update test config construction for new Config.registries field +1/-0

Update test config construction for new Config.registries field

• Extends the helper config initializer in registry-install tests to populate the new registries field with a default value to match the updated Config struct.

pacquet/crates/package-manager/src/install_package_from_registry/tests.rs

---

tests.rs Stabilize slow-start timing benchmark under CI jitter +5/-5

Stabilize slow-start timing benchmark under CI jitter

• Makes the baseline measurement take the faster of two flat samples and relaxes the asserted margin, reducing flakiness due to scheduler noise while preserving the slow-start signal.

pacquet/tasks/integrated-benchmark/src/latency_proxy/tests.rs

---

Cargo.toml Add mockito for package-manager scoped registry tests +1/-0

Add mockito for package-manager scoped registry tests

• Introduces mockito as a dev/test dependency to support new registry-routing regression tests in the package-manager crate.

pacquet/crates/package-manager/Cargo.toml

---