Walkthrough

Adds end-to-end support for pnpm-style configDependencies: an env lockfile document, resolver + env-installer crate to materialize config deps into node_modules/.pnpm-config, updateConfig hook execution, workspace manifest edits for configDependencies, CLI wiring for install/add, reporter events, hashing helpers, and tests.

Changes

Config Dependencies and UpdateConfig Hooks

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related issues

• pacquet: complete pnpmfile hooks (filterLog, pnpm:hook log channel, pnpmfile flags, multiple pnpmfiles, updateConfig, finders) #12118: Hook discovery and updateConfig semantics implemented here address items raised in that issue.
• Add global virtual store support to pacquet install --frozen-lockfile pacquet#432: Adds global virtual store and related hashing/installer concerns overlapping this work.
• pacquet: lockfile-parity gaps vs pnpm CLI (npm: aliases, minimumReleaseAge, peer suffixes) #12266: Related to env-lockfile and configDependencies support.

Possibly related PRs

• pnpm/pnpm#11892: Related pruning behavior for env lockfile entries.
• pnpm/pnpm#11787: Related catalogs/cat-types infrastructure used by this change.
• pnpm/pnpm#11734: Integration boundary work overlapping CLI/reporting plumbing.

Poem

🐰 I hop through lockfiles, links, and hooks,
Sewing catalogs into hidden books,
Symlinks set, and envs take root,
Tests snug as carrots in a boot,
Hooray — a comfy install nook!

• ❄️ 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

Config-dependency names are used directly in Path::join(...) for creating/pruning .pnpm-config
entries and locating plugin pnpmfiles, without validating they are safe npm package names. A crafted
configDependencies key (e.g. containing extra /, .., or an absolute path) can escape
.pnpm-config and lead to unintended directory deletion/symlink placement or loading an unintended
pnpmfile.

Code

pacquet/crates/env-installer/src/install_config_deps.rs[R44-55]

+    let config_modules_dir = opts.root_dir.join("node_modules").join(".pnpm-config");
+
+    let existing: Vec<String> = read_dir_names(&config_modules_dir)?;
+
+    let mut started = StartedGate::new();
+
+    // Drop config deps that are no longer declared.
+    for name in &existing {
+        if !normalized.contains_key(name) {
+            started.report::<Reporter>();
+            prune_link(&config_modules_dir.join(name));
+        }

Evidence

install_config_deps joins config-dependency names into filesystem paths for pruning/symlinking,
and hooks::finder joins the same names to locate plugin pnpmfiles; meanwhile pnpm-workspace.yaml
configDependencies keys are parsed as raw strings without validation. The repo already contains a
strict npm package-name validator that would prevent unsafe path components (extra /, leading .,
etc.), but it is not applied to configDependencies.

pacquet/crates/env-installer/src/install_config_deps.rs[36-79]
pacquet/crates/hooks/src/finder.rs[32-76]
pacquet/crates/config/src/workspace_yaml.rs[210-219]
pacquet/crates/resolving-parse-wanted-dependency/src/validate_npm_package_name.rs[31-57]

Agent prompt

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

## Issue description
Config dependency names (from `pnpm-workspace.yaml` / env lockfile) are used as path components via `Path::join(name)` when pruning/creating `.pnpm-config` entries and when discovering plugin pnpmfiles. Because these names are not validated as npm package names, a malicious name can introduce `..`/extra path separators/absolute paths and cause filesystem traversal outside `.pnpm-config`.
## Issue Context
There is already a canonical npm-name validator (`is_valid_old_npm_package_name`) used in dependency parsing, but configDependencies keys are deserialized as `BTreeMap<String, ...>` without validation and then consumed by env-installer + hook finder.
## Fix Focus Areas
- pacquet/crates/env-installer/src/resolve_and_install_config_deps.rs[27-100]
- pacquet/crates/env-installer/src/install_config_deps.rs[36-80]
- pacquet/crates/hooks/src/finder.rs[32-78]
- pacquet/crates/config/src/workspace_yaml.rs[210-220]
### Implementation notes
- Reject invalid config-dependency names up-front (before any lockfile mutation or filesystem operations) using `pacquet_resolving_parse_wanted_dependency::is_valid_old_npm_package_name` (or an equivalent shared validator).
- On invalid names, return `ConfigDepError::BadConfigDep { ... }` (ERR_PNPM_BAD_CONFIG_DEP).
- In addition to validation, defensively guard path usage by rejecting names whose `Path::new(name).components()` contains `RootDir`/`Prefix`/`ParentDir` or more than one `/` for scoped packages.
- Apply the same validation filter in `calc_pnpmfile_paths_of_plugin_deps` so plugin discovery never joins unsafe names.

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

Description

EnvLockfile parsing requires a numeric lockfileVersion (ComVer/LockfileVersion<9>), so it will fail
to read an env document whose lockfileVersion is a non-numeric string like "env-1.0". This can
hard-fail config-deps installation when such an env prefix exists in pnpm-lock.yaml.

Code

pacquet/crates/lockfile/src/env_lockfile.rs[R67-92]

+pub struct EnvLockfile {
+    pub lockfile_version: LockfileVersion<9>,
+
+    #[serde(default, serialize_with = "crate::serialize_yaml::sorted_map")]
+    pub importers: HashMap<String, EnvImporterSnapshot>,
+
+    #[serde(default, serialize_with = "crate::serialize_yaml::sorted_map")]
+    pub packages: HashMap<PackageKey, PackageMetadata>,
+
+    #[serde(default, serialize_with = "crate::serialize_yaml::sorted_map")]
+    pub snapshots: HashMap<PackageKey, SnapshotEntry>,
+}
+
+impl EnvLockfile {
+    /// The key used to refer to the root project inside `importers`.
+    pub const ROOT_IMPORTER_KEY: &str = ".";
+
+    /// A fresh, empty env lockfile with the root importer seeded.
+    /// Mirrors upstream's
+    /// [`createEnvLockfile`](https://github.com/pnpm/pnpm/blob/31858c544b/lockfile/fs/src/envLockfile.ts#L14-L24).
+    pub fn create() -> Self {
+        let mut importers = HashMap::new();
+        importers.insert(Self::ROOT_IMPORTER_KEY.to_string(), EnvImporterSnapshot::default());
+        EnvLockfile {
+            lockfile_version: LockfileVersion::<9>::try_from(ComVer::new(9, 0))
+                .expect("9.0 is compatible with lockfile major 9"),

Evidence

EnvLockfile hard-codes lockfile_version to LockfileVersion, which deserializes via ComVer that
only parses numeric major.minor strings; pnpm test fixtures in this repo demonstrate env-document
prefixes using lockfileVersion: env-1.0.

pacquet/crates/lockfile/src/env_lockfile.rs[65-93]
pacquet/crates/lockfile/src/comver.rs[34-40]
lockfile/fs/test/write.test.ts[311-314]

Agent prompt

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

## Issue description
`EnvLockfile` currently deserializes `lockfileVersion` via `LockfileVersion<9>` (which in turn deserializes via `ComVer`), meaning it only accepts numeric `"<major>.<minor>"` strings. Repos/fixtures may contain an env document whose `lockfileVersion` is a non-numeric string (e.g. `env-1.0`), causing `EnvLockfile::read()` to fail and breaking config-deps installs.
## Issue Context
The repo itself contains pnpm fixtures/tests that model an env-document prefix with `lockfileVersion: env-1.0`. Pacquet's env-installer reads and parses the env document via `EnvLockfile::read`, so this incompatibility becomes an install-blocking failure.
## Fix Focus Areas
- pacquet/crates/lockfile/src/env_lockfile.rs[65-127]
- pacquet/crates/lockfile/src/comver.rs[34-49]
## Suggested fix approach
- Change `EnvLockfile.lockfile_version` to deserialize from either:
- a numeric comver string (current behavior), or
- the legacy/non-numeric env-doc marker string(s) (e.g. `env-1.0`), mapping them to a compatible internal representation.
- Consider preserving the original env-doc `lockfileVersion` string when writing back (if round-trip fidelity matters), or consistently normalizing to the numeric lockfile version if pnpm accepts it.
- Add a unit test covering `EnvLockfile::read()` successfully parsing an env document whose `lockfileVersion` is `env-1.0`.

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

Description

resolve_and_install_config_deps treats ConfigDependency::Detailed.integrity as a
"<version>+<integrity>" string and calls parse_integrity, but the Detailed form’s integrity is
checksum-only, so valid object-form configDependencies will always fail migration with
ERR_PNPM_CONFIG_DEP_NO_INTEGRITY. This breaks backward compatibility for workspaces using the `{
tarball?, integrity }` form.

Code

pacquet/crates/env-installer/src/resolve_and_install_config_deps.rs[R43-59]

+            ConfigDependency::Detailed(detail) => {
+                if !has_config_dep(&env_lockfile, name) {
+                    let (version, integrity) = parse_integrity(name, &detail.integrity)?;
+                    let registry = opts.pick_registry(name);
+                    let tarball = detail
+                        .tarball
+                        .clone()
+                        .unwrap_or_else(|| npm_tarball_url(name, &version, registry));
+                    migrate_into_lockfile(
+                        &mut env_lockfile,
+                        name,
+                        &version,
+                        integrity,
+                        tarball,
+                        registry,
+                    );
+                    lockfile_changed = true;

Evidence

The PR’s migration path calls parse_integrity on detail.integrity, but the object-form stores
checksum-only integrity, and parse_integrity requires version+integrity, so the migration will
always error for valid object-form inputs.

pacquet/crates/env-installer/src/resolve_and_install_config_deps.rs[41-60]
pacquet/crates/workspace-state/src/lib.rs[50-69]
pacquet/crates/env-installer/src/parse_integrity.rs[30-51]

Agent prompt

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

## Issue description
`ConfigDependency::Detailed` migration incorrectly calls `parse_integrity(name, &detail.integrity)`, which expects `"<version>+<integrity>"`. In the object form, `detail.integrity` is checksum-only (e.g. `sha512-...`), so migration errors even for valid inputs.
## Issue Context
- `ConfigDependencyDetail` stores `{ tarball?: String, integrity: String }` where `integrity` is a checksum, not a combined version+checksum string.
- `parse_integrity` hard-requires a `+` separator and returns `NoIntegrity` if missing.
## Fix Focus Areas
- pacquet/crates/env-installer/src/resolve_and_install_config_deps.rs[41-61]
- pacquet/crates/env-installer/src/parse_integrity.rs[30-51]
### Implementation notes
- For `ConfigDependency::Detailed(detail)`:
- Parse integrity as `ssri::Integrity` directly from `detail.integrity` (no `split_once('+')`).
- Determine the version to use for the lockfile `PackageKey` / GVS path:
- If `detail.tarball` is present, extract the version (either by parsing canonical npm tarball URLs, or by downloading/extracting `package.json` to read `version`).
- If the version cannot be determined, surface `ERR_PNPM_BAD_CONFIG_DEP` with a clear message (don’t call `parse_integrity`).
- Migrate into the env lockfile with that `(version, integrity, tarball)`.
- Add/extend a unit/integration test that covers object-form migration end-to-end.

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

Description

install_config_deps emits pnpm:installing-config-deps Started when pruning stale links or
materializing missing packages, but it only emits Done when installed is non-empty. This can leave
an unmatched Started event despite real work occurring, contradicting the reporter's bracketing
contract.

Code

pacquet/crates/env-installer/src/install_config_deps.rs[R126-132]

+    if !installed.is_empty() {
+        Reporter::emit(&LogEvent::InstallingConfigDeps(InstallingConfigDepsLog {
+            level: LogLevel::Debug,
+            status: InstallingConfigDepsStatus::Done,
+            deps: installed,
+        }));
+    }

Evidence

StartedGate::report() is invoked for pruning and materialization, but Done is only emitted when
installed is non-empty; reporter documentation expects Started to be followed by a single Done
whenever the operation is not a no-op.

pacquet/crates/env-installer/src/install_config_deps.rs[46-56]
pacquet/crates/env-installer/src/install_config_deps.rs[83-85]
pacquet/crates/env-installer/src/install_config_deps.rs[126-132]
pacquet/crates/reporter/src/lib.rs[167-172]

Agent prompt

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

## Issue description
`install_config_deps` can call `StartedGate::report()` (emitting the Started event) in several work-producing paths (pruning stale `.pnpm-config` entries; materializing missing packages), but the Done event is gated on `installed` being non-empty. This violates the documented contract that the channel is bracketed by Started then Done whenever work happens.
## Issue Context
The reporter docs state this channel should emit `started` then a single `done`, and only emit nothing for a true no-op. Current logic can do work without pushing to `installed`, which suppresses Done.
## Fix Focus Areas
- pacquet/crates/env-installer/src/install_config_deps.rs[46-56]
- pacquet/crates/env-installer/src/install_config_deps.rs[83-95]
- pacquet/crates/env-installer/src/install_config_deps.rs[126-133]
## Suggested fix approach
- Track whether `StartedGate` has emitted (`started.emitted`) and, if so, always emit a Done event at function end.
- Emit Done even when `deps` is empty (the payload supports omitting `deps` when empty).
- Optionally, consider adding entries to `deps` for cases where work occurred but no new symlink was created (e.g., materialization-only), if consumers rely on the list.
- Add a test that triggers Started via pruning or materialization but results in an empty `installed` list, and assert Done is still emitted.

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

Description

extract_env_document only recognizes the exact LF-delimited markers "---\n" and "\n---\n", and
save_value_to_path relies on it to preserve the env document when rewriting pnpm-lock.yaml. If
pnpm-lock.yaml uses CRLF line endings or starts with a UTF-8 BOM, the env document will not be
detected and will be silently dropped on rewrite.

Code

pacquet/crates/lockfile/src/yaml_documents.rs[R42-59]

+/// Extract the env lockfile document (first YAML document) from a
+/// combined file. The synchronous counterpart to upstream's streaming
+/// [`streamReadFirstYamlDocument`](https://github.com/pnpm/pnpm/blob/31858c544b/lockfile/fs/src/yamlDocuments.ts#L15-L60):
+///
+/// - The file must begin with `---\n`; otherwise it carries no env
+///   document and this returns `None`.
+/// - Returns the slice between the leading `---\n` and the next
+///   `\n---\n` separator. A leading `---\n` with no following separator
+///   (an env-only file with no main document) also yields `None`,
+///   matching upstream's fall-through to `return null`.
+///
+/// pacquet reads the whole lockfile into memory rather than streaming,
+/// so this skips upstream's chunked BOM/CRLF handling — the only
+/// callers pass content pacquet itself wrote with LF line endings.
+pub fn extract_env_document(content: &str) -> Option<&str> {
+    let rest = content.strip_prefix(YAML_DOCUMENT_START)?;
+    rest.find(YAML_DOCUMENT_SEPARATOR).map(|idx| &rest[..idx])
+}

Evidence

The lockfile multi-document helpers hard-code LF-only document markers and explicitly skip BOM/CRLF
handling; both save_value_to_path (wanted lockfile writer) and EnvLockfile::read depend on
extract_env_document, so failed detection results in not preserving/reading the env document.

pacquet/crates/lockfile/src/yaml_documents.rs[13-59]
pacquet/crates/lockfile/src/save_lockfile.rs[75-90]
pacquet/crates/lockfile/src/env_lockfile.rs[113-126]

Agent prompt

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

## Issue description
`extract_env_document` requires a literal `---\n` prefix and a `\n---\n` separator. This makes env-doc detection brittle: CRLF line endings and/or a UTF-8 BOM will cause `extract_env_document` to return `None`, and callers will treat the lockfile as having no env document.
## Issue Context
The env document is preserved when rewriting the wanted lockfile (`save_value_to_path`) and is also used by `EnvLockfile::read`. If detection fails, the env document can be lost during a rewrite.
## Fix Focus Areas
- pacquet/crates/lockfile/src/yaml_documents.rs[13-59]
- pacquet/crates/lockfile/src/save_lockfile.rs[75-90]
- pacquet/crates/lockfile/src/env_lockfile.rs[113-126]
### Suggested fix approach
- Make YAML document marker detection tolerant of:
- UTF-8 BOM (strip leading `\u{FEFF}` / 0xEFBBBF)
- CRLF: accept `---\r\n` and `\r\n---\r\n` in addition to the LF forms.
- Keep returned slices correct (avoid naive global string replacement that would invalidate indices). One pragmatic approach is:
- detect which newline style is present in the initial marker and search for the matching separator style.
- Apply the same tolerance to `extract_main_document` so preservation and reading stay consistent across line endings.

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

Description

The CLI config-deps path returns early when config.config_dependencies is None or empty, so
removing the configDependencies block entirely will never trigger env-lockfile/.pnpm-config
cleanup. This leaves stale env-doc state and .pnpm-config links on disk after users delete all
config dependencies.

Code

pacquet/crates/cli/src/config_deps.rs[R38-49]

+pub async fn install_config_deps<Reporter: self::Reporter>(
+    config: &Config,
+    root_dir: &Path,
+    frozen_lockfile: bool,
+) -> Result<()> {
+    let Some(config_dependencies) = config.config_dependencies.as_ref() else {
+        return Ok(());
+    };
+    if config_dependencies.is_empty() {
+        return Ok(());
+    }
+    resolve_and_install::<Reporter>(config, config_dependencies, root_dir, frozen_lockfile).await

Evidence

The CLI explicitly treats missing/empty configDependencies as a no-op, which prevents any
env-installer reconciliation/pruning from running when users remove the block.

pacquet/crates/cli/src/config_deps.rs[34-50]

Agent prompt

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

## Issue description
`install_config_deps` exits early when `config.config_dependencies` is `None` or empty, so the env-installer never runs and cannot prune stale env-lockfile entries or `.pnpm-config` links when the last config dependency is removed.
## Issue Context
- After this PR, config deps are installed/pruned by the env-installer.
- If the configDeps pipeline is skipped entirely, stale `.pnpm-config/*` and the env document can remain indefinitely.
## Fix Focus Areas
- pacquet/crates/cli/src/config_deps.rs[38-50]
### Implementation notes
- When `config.config_dependencies` is `None`/empty, consider running a lightweight cleanup path:
- If an env document exists (`EnvLockfile::read(root_dir)` returns `Some`) OR `node_modules/.pnpm-config` exists, invoke the env-installer with an empty `BTreeMap` so it can clear importer keys, prune packages/snapshots, write the env doc, and remove `.pnpm-config` entries.
- Otherwise keep the fast no-op.
- Add an integration test: install with one config dep, remove the `configDependencies` block, re-run install, assert `.pnpm-config/<dep>` is removed and env doc no longer lists it.

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

• Resolve and install workspace configDependencies into node_modules/.pnpm-config before main
  install.
• Persist config deps in the env lockfile (first pnpm-lock.yaml document) and preserve it on
  rewrites.
• Add updateConfig pnpmfile hook chaining (plugin + root pnpmfile) and support pacquet add --config.

The following are alternative approaches to this PR:

Recommendation: The PR’s approach (a dedicated env-installer + explicit config-finalization phase + JSON round-trip through WorkspaceSettings) is the best fit for pnpm parity and for ensuring the env document is written before the main lockfile path runs. The main follow-up to consider is removing the StoreDir leak by evolving downstream APIs to accept non-'static borrows once the surrounding installer plumbing is ready for that refactor.

Cargo.toml Add pacquet-env-installer crate to workspace +1/-0

Add pacquet-env-installer crate to workspace

• Registers the new env-installer crate in the workspace members/dependencies so it can be consumed by CLI and other crates.

Cargo.toml

---

cli_args.rs Run config-dep install + updateConfig hooks before State::init +35/-5

Run config-dep install + updateConfig hooks before State::init

• Moves config-dependency resolution/installation and updateConfig hook execution into the install command path before the main install state is initialized, ensuring the env lockfile is written first and Config mutations are applied in time.

pacquet/crates/cli/src/cli_args.rs

---

add.rs Add --config flag to route pacquet add to configDependencies +39/-2

Add --config flag to route pacquet add to configDependencies

• Introduces 'pacquet add --config' to resolve/install a config dependency into '.pnpm-config', then persist the clean specifier to 'pnpm-workspace.yaml'. Validates package naming and defaults to 'latest' when no version is provided.

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

---

config_deps.rs Implement config-deps install and updateConfig hook runner +283/-0

Implement config-deps install and updateConfig hook runner

• Adds the orchestration layer to (1) resolve/install declared configDependencies via pacquet-env-installer and (2) load and chain updateConfig hooks from plugin pnpmfiles under '.pnpm-config' plus the workspace pnpmfile. Applies only hook-changed WorkspaceSettings keys back onto Config and captures hook-modified catalogs.

pacquet/crates/cli/src/config_deps.rs

---

lib.rs Expose config_deps module +1/-0

Expose config_deps module

• Registers the new CLI module that handles configDependencies installation and updateConfig hook execution.

pacquet/crates/cli/src/lib.rs

---

lib.rs Enable Config round-trip for updateConfig + store hook-injected catalogs +35/-5

Enable Config round-trip for updateConfig + store hook-injected catalogs

• Adds Serialize support to config enums/fields needed for WorkspaceSettings JSON round-trips, implements custom Serialize for mixed-type settings, and adds 'Config::catalogs' to carry catalogs produced by updateConfig hooks.

pacquet/crates/config/src/lib.rs

---

workspace_yaml.rs Make WorkspaceSettings serializable +1/-1

Make WorkspaceSettings serializable

• Derives Serialize for WorkspaceSettings so it can be converted to/from JSON for updateConfig hook input/output and then applied back to Config.

pacquet/crates/config/src/workspace_yaml.rs

---

Cargo.toml Introduce pacquet-env-installer crate +46/-0

Introduce pacquet-env-installer crate

• Adds a new crate with dependencies on config, lockfile, graph-hasher, network, package-manager import, and workspace-state to implement pnpm-style env-installer behavior for configDependencies.

pacquet/crates/env-installer/Cargo.toml

---

errors.rs Add pnpm-compatible error types/codes for config-deps +80/-0

Add pnpm-compatible error types/codes for config-deps

• Defines ConfigDepError with user-facing diagnostic codes matching pnpm’s ERR_PNPM_* contract, covering integrity migration failures, optional-subdep exact-version enforcement, lockfile corruption, and frozen-lockfile rejection paths.

pacquet/crates/env-installer/src/errors.rs

---

install_config_deps.rs Install config deps into .pnpm-config via global virtual store +531/-0

Install config deps into .pnpm-config via global virtual store

• Implements materialization of config deps into the global virtual store and symlinking under 'node_modules/.pnpm-config', including pruning stale links and installing one level of optional subdeps with host platform filtering and debug logging.

pacquet/crates/env-installer/src/install_config_deps.rs

---

lib.rs Export env-installer public API surface +34/-0

Export env-installer public API surface

• Provides crate-level documentation and re-exports for resolve/install, lockfile pruning, integrity parsing, and install primitives used by the CLI.

pacquet/crates/env-installer/src/lib.rs

---

options.rs Define ConfigDepsInstallOptions and registry selection logic +72/-0

Define ConfigDepsInstallOptions and registry selection logic

• Adds a borrowed options struct carrying install handles/settings (root dir, store, client, registries, retry/frozen flags, platform info) plus scoped-registry selection mirroring pnpm.

pacquet/crates/env-installer/src/options.rs

---

parse_integrity.rs Parse old inline version+integrity config-dep format +51/-0

Parse old inline version+integrity config-dep format

• Implements migration parsing for legacy '<version>+<integrity>' entries and defines normalized in-memory shapes consumed by the install pass.

pacquet/crates/env-installer/src/parse_integrity.rs

---

prune.rs Prune unreachable env-lockfile packages/snapshots +48/-0

Prune unreachable env-lockfile packages/snapshots

• Keeps the env document minimal by retaining only packages/snapshots reachable from configDependencies and one level of optional subdeps, removing stale entries after re-resolve.

pacquet/crates/env-installer/src/prune.rs

---

resolve_and_install_config_deps.rs Resolve clean specifiers, migrate old formats, then install +230/-0

Resolve clean specifiers, migrate old formats, then install

• Implements the end-to-end flow: reads/creates env lockfile, migrates old formats into lockfile, resolves clean specifiers when missing/outdated, enforces frozen-lockfile semantics, prunes stale entries, writes the env document, and triggers installation/linking.

pacquet/crates/env-installer/src/resolve_and_install_config_deps.rs

---

resolve_optional_subdeps.rs Resolve optionalDependencies one level deep with exact-version enforcement +154/-0

Resolve optionalDependencies one level deep with exact-version enforcement

• Resolves and records optional subdeps for config deps into the env lockfile, capturing platform fields (os/cpu/libc) and rejecting non-exact optional versions to preserve reproducibility.

pacquet/crates/env-installer/src/resolve_optional_subdeps.rs

---

global_virtual_store_path.rs Add GVS path hashing for leaf nodes and config-dep subdeps +47/-2

Add GVS path hashing for leaf nodes and config-dep subdeps

• Introduces 'calc_leaf_global_virtual_store_path' and 'calc_global_virtual_store_path_with_subdeps' to hash config deps (and their optional subdeps) into stable global-virtual-store paths matching pnpm’s semantics.

pacquet/crates/graph-hasher/src/global_virtual_store_path.rs

---

lib.rs Re-export new GVS hashing functions +4/-1

Re-export new GVS hashing functions

• Exports the leaf and subdeps-aware GVS path helpers for use by env-installer and other crates.

pacquet/crates/graph-hasher/src/lib.rs

---

finder.rs Add plugin pnpmfile discovery for configDependencies +59/-1

Add plugin pnpmfile discovery for configDependencies

• Implements pnpm plugin name detection and resolves pnpmfile paths for installed plugin config deps under '.pnpm-config', preferring pnpmfile.mjs over pnpmfile.cjs and skipping missing plugin directories.

pacquet/crates/hooks/src/finder.rs

---

lib.rs Add updateConfig hook to PnpmfileHooks trait +16/-0

Add updateConfig hook to PnpmfileHooks trait

• Extends the hook trait with an async updateConfig method (default no-op), enabling hooks to transform configuration before install.

pacquet/crates/hooks/src/lib.rs

---

node_runtime.rs Dispatch updateConfig to Node worker and normalize null result +12/-0

Dispatch updateConfig to Node worker and normalize null result

• Implements updateConfig execution in NodeJsHooks via the worker bridge and treats a null worker response as “no hook”, returning the original config unchanged.

pacquet/crates/hooks/src/node_runtime.rs

---

env_lockfile.rs Introduce EnvLockfile multi-document read/write support +149/-0

Introduce EnvLockfile multi-document read/write support

• Adds a typed representation of the env lockfile (first YAML document) with read/write that preserves the main lockfile document and guarantees the root importer exists, matching pnpm’s envLockfile behavior.

pacquet/crates/lockfile/src/env_lockfile.rs

---

lib.rs Export env_lockfile module from lockfile crate +2/-0

Export env_lockfile module from lockfile crate

• Registers and re-exports EnvLockfile and related types so other crates (env-installer, CLI) can consume them.

pacquet/crates/lockfile/src/lib.rs

---

resolution.rs Expose npm_tarball_url for env-installer migration/resolution +1/-1

Expose npm_tarball_url for env-installer migration/resolution

• Makes 'npm_tarball_url' public so env-installer can derive canonical tarball URLs when lockfile resolutions omit tarball fields.

pacquet/crates/lockfile/src/resolution.rs

---

yaml_documents.rs Add extract_env_document helper for multi-doc pnpm-lock.yaml +21/-2

Add extract_env_document helper for multi-doc pnpm-lock.yaml

• Exposes YAML document framing constants internally and adds 'extract_env_document' to retrieve the first YAML document when present, enabling env preservation during main lockfile rewrites.

pacquet/crates/lockfile/src/yaml_documents.rs

---

install.rs Prefer hook-injected catalogs over workspace manifest catalogs +10/-2

Prefer hook-injected catalogs over workspace manifest catalogs

• Switches catalog selection to use 'config.catalogs' when set by updateConfig hooks, falling back to reading from pnpm-workspace.yaml only when hooks did not modify catalogs.

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

---

lib.rs Add pnpm:installing-config-deps reporter event +42/-0

Add pnpm:installing-config-deps reporter event

• Introduces a new structured log event to bracket config-deps installation ('started'/'done'), including the installed '{name, version}' list and suppressing output on no-op runs.

pacquet/crates/reporter/src/lib.rs

---

edit.rs Add format-preserving edits for configDependencies block +58/-5

Add format-preserving edits for configDependencies block

• Implements insertion/upsert of 'configDependencies' entries while preserving YAML formatting/comments, reusing existing splice helpers generalized to accept explicit mapping paths.

pacquet/crates/workspace-manifest-writer/src/edit.rs

---

lib.rs Expose set_config_dependency API for pnpm-workspace.yaml +28/-0

Expose set_config_dependency API for pnpm-workspace.yaml

• Adds a public helper to write/update 'configDependencies' in pnpm-workspace.yaml (creating file/block if needed) while preserving formatting, used by 'pacquet add --config'.

pacquet/crates/workspace-manifest-writer/src/lib.rs

---

save_lockfile.rs Preserve env lockfile document when writing wanted lockfile +27/-3

Preserve env lockfile document when writing wanted lockfile

• Updates lockfile save logic to detect and re-prepend an existing env document before writing the main lockfile YAML, matching pnpm’s multi-document wanted lockfile write semantics.

pacquet/crates/lockfile/src/save_lockfile.rs

---

config_dependencies.rs Add CLI e2e tests for configDependencies and updateConfig behavior +171/-0

Add CLI e2e tests for configDependencies and updateConfig behavior

• Covers 'pacquet install' installing/linking config deps and writing env lockfile, repeat installs being no-ops, updateConfig mutating nodeLinker before install, updateConfig injecting catalogs used to resolve 'catalog:' deps, and 'pacquet add --config' editing pnpm-workspace.yaml while preserving existing keys.

pacquet/crates/cli/tests/config_dependencies.rs

---

tests.rs Add integration/unit coverage for env-installer behaviors +463/-0

Add integration/unit coverage for env-installer behaviors

• Tests resolving/installing with and without existing env lockfile, optional subdeps and platform metadata, frozen-lockfile failure/success cases, legacy format migration, pruning behavior, and reporter event emission only when work is performed.

pacquet/crates/env-installer/src/tests.rs

---

tests.rs Test new GVS hashing helpers for parity and collision prevention +63/-2

Test new GVS hashing helpers for parity and collision prevention

• Adds tests ensuring leaf hashing matches single-node graph hashing, empty-subdeps hashing equals leaf hashing, and subdep identity changes partition the parent path.

pacquet/crates/graph-hasher/src/global_virtual_store_path/tests.rs

---

node_hooks.rs Test plugin detection/path resolution and updateConfig behavior +82/-0

Test plugin detection/path resolution and updateConfig behavior

• Adds unit tests for plugin name patterns, plugin pnpmfile path calculation ordering and mjs preference, and updateConfig hook application/no-op semantics.

pacquet/crates/hooks/tests/node_hooks.rs

---

tests.rs Test env document round-trip and main-document preservation +103/-0

Test env document round-trip and main-document preservation

• Verifies env doc write/read equality, preservation of pre-existing main lockfile content, and preservation of env doc when the main lockfile is re-saved by the normal install flow.

pacquet/crates/lockfile/src/env_lockfile/tests.rs

---

tests.rs Update test config initialization for new Config::catalogs field +1/-0

Update test config initialization for new Config::catalogs field

• Adjusts test helper config construction to include the new 'catalogs: None' field.

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

---

tests.rs Test configDependencies writer behavior and preservation +41/-0

Test configDependencies writer behavior and preservation

• Adds tests ensuring the block is created when absent, entries are added/upserted correctly, and unrelated keys/comments remain intact.

pacquet/crates/workspace-manifest-writer/src/tests.rs

---

Cargo.toml Wire CLI dependencies for config deps + hooks + manifest writing +8/-1

Wire CLI dependencies for config deps + hooks + manifest writing

• Adds new crate dependencies needed to resolve/install config deps, run updateConfig hooks, compute GVS paths, and edit pnpm-workspace.yaml. Adjusts dev-dependencies accordingly.

pacquet/crates/cli/Cargo.toml

---

Cargo.toml Add catalogs types dependency to Config +1/-0

Add catalogs types dependency to Config

• Introduces 'pacquet-catalogs-types' so Config can store catalogs injected by updateConfig hooks.

pacquet/crates/config/Cargo.toml

---