PFM-ISSUE-34453 - github-actions: Normalize package-lock.json resolved URLs onto the JFrog npm proxy (release/25.2)

[Kaltenbach]

Problem

This repo ships a mixed package-lock.json: 171 entries resolve via https://registry.npmjs.org/, the other 371 via the cplace JFrog npm proxy.

The composite actions run npm ci inside the action directory, on the consumer's runner, while that consumer's ~/.npmrc is active. npm rewrites an npmjs resolved URL onto the configured host and drops the registry's path prefix (pacote/lib/remote.js: new URL(resolvedURL.pathname, this.registry)), producing E404 — masked as *** because the prefix is the JFROG_URL secret.

⚠️ Scope grew during review — read this before approving

This PR is no longer tooling-only. It now contains a runtime behaviour change affecting every consumer:

.github/actions/use-npmrc appends replace-registry-host=never to the ~/.npmrc it writes.

Why it is here rather than in a follow-up: normalizing this repo's lockfile fixes the composite surface only. A consumer's own npm ci runs in the workspace against its own lockfile, and a survey of 299 repo/branch combinations across 41 FE repos found cplace-paw-fe release/25.2 and release/25.3 are broken today — 14 npmjs entries each, verified failing with a cold cache. Nothing masks it: those branches have no cache, and the key is content-addressed to the lockfile.

What it costs: entries still on npmjs are fetched directly from npmjs, bypassing the proxy — no Xray, no curation. That is a deliberate, temporary supply-chain trade to stop live breakage.

How it gets removed: use-npmrc also runs an advisory warn-foreign-registry.sh against the consumer's lockfile, emitting a ::warning plus job summary. Those warnings are the inventory; when no pipeline reports one, the line comes out. Owned by PFM-ISSUE-34454, which has a dedicated section for it. The two compose safely — on a normalized lockfile the flag is a no-op.

Verified end-to-end: cplace-paw-fe#185, full pipeline green (15 jobs) on release/25.2, with Install modules succeeding (added 2439 packages … in 8m, cold cache) and the annotation correctly reporting 14.

What is in the PR

area	files
Normalizer + invariant check	tools/scripts/lockfile/{lib.sh,fingerprint.jq,normalize-lockfile.sh,check-lockfile.sh}
Interim mitigation	.github/actions/use-npmrc/action.yml, tools/scripts/lockfile/warn-foreign-registry.sh
PR guard	.github/workflows/pr-checks.yml (this repo's first on: pull_request workflow)
Tests	tools/scripts/lockfile/*.bats — 51 tests
The lockfile	package-lock.json — 171 prefixes, its own commit
Docs	tools/scripts/lockfile/README.md, specs/2026-08-10_normalize-package-lock-resolved-urls/

Why bash + jq in a TypeScript repo

Bootstrap independence. npx ts-node needs node_modules, which needs the npm ci that is broken.

Two modes, and why CI uses the weaker one

• --prefix-only — every entry resolves via the proxy. This is the PR guard.
• --baseline <ref> — the above plus the dependency graph is unchanged. Verifies a normalization commit.

Graph invariance forbids any dependency change, so gating PRs on it would fail every legitimate npm install. Consequence, stated plainly: a green CI run is not evidence that a lockfile diff changed only prefixes. Where that matters, run the baseline form locally.

Evidence

• 171 entries rewritten, +4788 bytes, 342 changed lines, 0 outside a "resolved" line; idempotent
• Output byte-identical to a raw sed prefix rewrite
• grep -c registry.npmjs.org package-lock.json → 0
• Local before/after with the real ~/.npmrc: E404 → added 542 packages
• Proxy re-probed for all 171 tarballs: 166 × 200, 5 × 302, zero 403/404
• 51/51 bats, shellcheck and actionlint clean

Every failure message names a package path, never a URL, so it survives *** masking.

Review history

Two rounds found 12 defects, all reproduced before fixing. Several failed open — reporting success on a lockfile that was never actually verified. See the inline threads; each fix has a regression test.

Known limitation

The guard reports but cannot block until PFM-ISSUE-34465 (Rule Sets) lands. release/25.2 has no branch protection at all today.

Rollout

Branch 1 of 7. master and release/26.3 are not downstream of 26.2, so this cannot ride the upmerge. The other six carry byte-identical tooling plus the same machine-checked lockfile transformation — this is the review that counts.

Spec: specs/2026-08-10_normalize-package-lock-resolved-urls/

Refs PFM-ISSUE-34453. Blocks PFM-ISSUE-34454.

🤖 Generated with Claude Code

[Kaltenbach]

Validation complete — ready for review

1. Local reproduction — controlled experiment

Same machine, same ~/.npmrc, lockfile as the only variable:

lockfile	npm ci
pre-fix (171 npmjs URLs)	npm error code E404 — GET https://cplace.jfrog.io/unicode-property-aliases-ecmascript/-/…tgz (the /artifactory/api/npm/cplace-npm prefix dropped)
normalized (0 npmjs URLs)	added 542 packages, and audited 543 packages in 5s, exit 0

2. Consumer canary — cplace-paw-fe#184 (throwaway, now closed)

cplace-remote-filesystem-fe couldn't be used — its release branches don't go back to 25.2. Ran fe-pr-snapshot in cplace-paw-fe instead; run 31487742492 green, zero E404:

Run cd "$GITHUB_ACTION_PATH/../../.." && pwd && npm ci
added 542 packages, and audited 543 packages in 14s
Run npx ts-node "$GITHUB_ACTION_PATH/../../../tools/scripts/artifacts/main.ts"

542/543 is this repo's lockfile entry count, matching the local run — so the tree under test is what actually got installed. main.ts then ran on top, proving node_modules was functional, not merely populated.

⚠️ Worth knowing for the remaining canaries: re-pinning the consumer's uses: alone tests the wrong lockfile. The composite runs cd "$GITHUB_ACTION_PATH/../../.." && npm ci, so the ref on the composite decides which lockfile is installed — and fe-pr-snapshot.yml pins use-npmrc/artifacts internally at @release/25.2. A naive canary would have installed the un-normalized lockfile and passed for the wrong reason. A throwaway branch with the internal refs re-pinned was used, then deleted.

No artifact was published (a workflow-file-only change leaves no nx project affected), confirmed via jf rt search. Not claimed as a publish test — npm publish never depended on lockfile resolution.

3. Blocker found and fixed: repository Actions policy

The first run of the new guard ended in startup_failure at 0s with no jobs and no annotations anywhere in the API — which reads like a broken workflow file. It wasn't: the repo's Actions policy was allowed_actions=local_only ("Allow collaborationFactory actions and reusable workflows"), which permits only owner-owned actions, so actions/checkout — owned by the actions org — was rejected before any job started.

Now selected with github_owned_allowed=true, verified_allowed=false (actions/* only, narrower than an unrestricted "all"). Measured blast radius: zero — all 91 workflow files across the seven branches are workflow_call-only and never self-execute, and reusable-workflow runs are governed by the caller's policy, so consumers were never affected.

What to focus review on

This is the only PR of the seven with novel content. The other six will carry byte-identical tooling plus the same machine-checked lockfile transformation, so this review is the one that counts.

• tools/scripts/lockfile/lib.sh — the hard-coded proxy constant and the single tarball-path regex are load-bearing; the constant is deliberately not configurable, because a caller-supplied prefix would make the exactness assertion validate its own typo.
• check-lockfile.sh — two assertions, both required. Neither subsumes the other, and check-lockfile.bats asserts each drift class fails via the correct one.
• pr-checks.yml — deliberately not fe--prefixed, since that prefix here means "reusable workflow consumed by other repos".

Known limitation, stated up front: this guard reports but cannot block until the Rule Sets follow-up lands. release/25.2 has no branch protection at all today.

[Copilot]

Pull request overview

This PR introduces a bash+jq toolchain to normalize package-lock.json resolved URLs onto the cplace JFrog npm proxy, adds a PR workflow guard to detect drift/reintroduction, and updates the lockfile accordingly to prevent consumer-runner npm ci failures caused by ~/.npmrc registry rewriting.

Changes:

• Add lockfile normalization + invariant-check scripts (jq fingerprint + two-assertion checker) with bats test coverage.
• Add a new on: pull_request workflow (pr-checks.yml) to run the lockfile invariant check plus shellcheck/bats.
• Normalize package-lock.json resolved entries and document the approach in tools/scripts/lockfile/README.md and specs/….

Reviewed changes

Copilot reviewed 13 out of 14 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tools/scripts/lockfile/lib.sh	Shared constants/helpers for normalization/checking (proxy constant, regexes, jq helpers).
tools/scripts/lockfile/fingerprint.jq	Registry-independent fingerprint transform for graph invariance comparisons.
tools/scripts/lockfile/normalize-lockfile.sh	Rewrites resolved URLs onto the proxy while self-asserting graph invariance.
tools/scripts/lockfile/check-lockfile.sh	Baseline-vs-candidate invariant checker (graph invariance + prefix exactness).
tools/scripts/lockfile/test-helper.bash	Shared bats fixture builders and mutation helper for drift injection.
tools/scripts/lockfile/normalize-lockfile.bats	Behavioural tests for the normalizer script.
tools/scripts/lockfile/check-lockfile.bats	Behavioural tests for the invariant checker, including drift-class coverage.
tools/scripts/lockfile/README.md	Operational documentation: rollout, conflict resolution, interpreting guard failures.
.github/workflows/pr-checks.yml	New PR workflow to run lockfile invariant + shell script lint/tests.
.prettierignore	Excludes package-lock.json from prettier checks.
specs/2026-08-10_normalize-package-lock-resolved-urls/design.md	Design doc capturing constraints/decisions for the solution.
specs/2026-08-10_normalize-package-lock-resolved-urls/plan.md	Implementation plan and rollout steps across branches.
specs/2026-08-10_normalize-package-lock-resolved-urls/research.md	Research evidence backing the approach and constraints.
package-lock.json	Normalized resolved URL prefixes to the JFrog npm proxy.

Suppressed comments (2)

tools/scripts/lockfile/check-lockfile.sh:151

• mktemp without a template is not portable (it fails on macOS/BSD). Use a portable template path for the baseline temp file.

  baseline_file="$(mktemp)"

tools/scripts/lockfile/lib.sh:36

• RESOLVED_URL_RE is intended to validate standard npm tarball URLs (as described in the error message), but it currently allows any trailing filename. Consider requiring \.tgz to align validation with the documented contract.

readonly RESOLVED_URL_RE='^https?://[^/]+/.*(?:@[^/]+/)?[^/]+/-/[^/]+$'

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Benno42]

🚀 Looks good. Just two questions.

[Kaltenbach]

Why replace-registry-host=never was added to use-npmrc

New commits since the review started. This one changes use-npmrc, so it deserves an explanation rather than being discovered in the diff.

The problem this PR originally solved was only half of it

Normalizing this repo's package-lock.json fixes the composite surface: npm ci running inside the action's own checkout, outside the workspace. It does nothing for the consumer surface — a consumer's own npm ci, running in the workspace against its own lockfile.

surface	where npm ci runs	whose lockfile	fixed by
composite	the action's checkout	this repo's	normalization (this PR)
consumer	the workspace	the consumer's	nothing, until now

That mattered more than expected. A survey of 299 repo/branch combinations across 41 FE repos found 8 affected branches — and cplace-paw-fe release/25.2 and release/25.3 are broken right now, each with 14 registry.npmjs.org entries. Reproduced with a cold cache and the real ~/.npmrc:

npm error code E404
npm error 404 Not Found - GET https://cplace.jfrog.io/readdirp/-/readdirp-3.6.0.tgz

Nothing masks it: that repo has zero caches on those branches, and the cache key is hashFiles('**/package-lock.json') — content-addressed, so a cross-branch cache hit is impossible by construction. It is unobserved only because no recent PR has targeted those branches.

What the one line does

echo 'replace-registry-host=never' >> ~/.npmrc

npm's default (replace-registry-host=npmjs) rewrites a lockfile's npmjs URLs onto the configured registry and drops that registry's path prefix — the bug. never makes npm fetch each resolved URL verbatim. Measured against real lockfiles with the real secret:

github-actions, un-normalized	added 542 packages
cplace-paw-fe release/25.2	added 2576 packages

JFrog URLs stay authenticated by the secret, so this adds no dependency on anonymous JFrog access.

Why not just revert use-npmrc to a workspace-level .npmrc

That was the first instinct, and it was measured rather than argued:

• It does not fix the consumer surface. A consumer's npm ci runs in the workspace, where that file lives — so cplace-paw-fe stays broken.
• It costs 730 anonymous JFrog requests per run, creating exactly the dependency PFM-ISSUE-34454 exists to remove. If the anonymous shutdown landed while that revert was in place, every composite would break — worse than today.

This is a mitigation, and it inventories its own removal

Under it, entries still on npmjs are fetched directly from npmjs, bypassing Xray and curation. So use-npmrc also runs warn-foreign-registry.sh against the consumer's lockfile:

⚠️ 14 resolved entries in package-lock.json point somewhere other than the cplace npm proxy… First 10 affected packages ▸

Those warnings are the removal criteria. When no pipeline reports one, the line comes out — by then it is already a no-op, since a normalized lockfile has no foreign URLs left to rewrite. The two compose safely in either order, so removal is lazy and per-branch, not a coordinated switchover. Tracked on PFM-ISSUE-34454, which now has a dedicated section for it.

The check is advisory by construction — it runs in every consumer's pipeline, so missing lockfile, missing jq and invalid JSON all exit 0 silently, and local-path resolved values (found in 4 of 41 FE repos) are ignored rather than reported as false positives. Four of the 34 bats tests exist solely to pin that property.

One consequence worth flagging for PFM-ISSUE-34454: a clean JFrog access log no longer proves everything resolves through the proxy while this is in place, because npmjs-direct requests never reach JFrog at all.

design.md gains Dimension 9 and plan.md gains Phase 4b/6b covering all of this.

[Kaltenbach]

Mitigation canary: green on the branch that is broken today

cplace-paw-fe#185, run 31509557594 — a draft PR against cplace-paw-fe release/25.2, chosen deliberately because that branch carries 14 registry.npmjs.org entries in its own lockfile and fails npm ci today.

Result

echo 'replace-registry-host=never' >> ~/.npmrc
##[warning]14 entries in package-lock.json do not resolve via the cplace npm proxy.
          They install today only because use-npmrc sets replace-registry-host=never.
          Normalize this lockfile - see PFM-ISSUE-34453.
added 2439 packages, and audited 2440 packages in 8m

step	outcome
Use .npmrc	success
Install modules	success — this is the step that returns E404 without the mitigation

Two details that make this a real test rather than a lucky one:

• The install took 8 minutes, i.e. it ran genuinely cold. Nothing was restored from cache — which is exactly the condition under which this branch fails. Had a cache been restored, Install modules would have been skipped and the run would have proved nothing.
• The warning independently counted 14, matching the survey's count for that branch, and surfaced in the run UI without failing the job — the advisory contract holding under real conditions.

Why the internal re-pin was necessary

The canary branch re-pins use-npmrc/artifacts/snapshots internally to itself. The mitigation lives in use-npmrc, and fe-install-deps.yml pins use-npmrc@release/25.2. Re-pinning only the consumer's uses: would have loaded the old use-npmrc and tested nothing — the same trap as the Phase 6 canary, one level deeper.

What this does and does not prove

Proven: the mitigation fixes the consumer surface on a real runner, on a branch that genuinely fails without it.

Not claimed: the rest of paw-fe's pipeline (build, e2e, code-quality) is still running and is not the subject — those exercise paw-fe's own code, not this change. install-deps was the whole test, and it is green.

Canary PR and both throwaway branches will be deleted.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 18 changed files in this pull request and generated 1 comment.

Suppressed comments (4)

specs/2026-08-10_normalize-package-lock-resolved-urls/design.md:537

• This integration statement is false in the current diff: use-npmrc/action.yml is modified to append replace-registry-host=never and run the advisory scanner. Update the architecture summary so the material consumer-runtime mitigation is not documented as out of scope.

- `.github/actions/use-npmrc/action.yml` is **not modified** — that is PFM-ISSUE-34454's territory.

tools/scripts/lockfile/check-lockfile.sh:75

• The union comparison treats a missing top-level key and an explicitly present null key as equal because both $A[$key] and $B[$key] evaluate to null. As a result, adding or removing null-valued top-level metadata passes the claimed whole-document graph invariant. Compare key presence with has as well as values.

    | [ ((($A | keys) + ($B | keys)) | unique)[]
        | select(. != "packages")
        | select(($A[.] | tojson) != ($B[.] | tojson))
        | "top-level key: " + . ]

tools/scripts/lockfile/README.md:125

• This guard description contradicts the mode table immediately above and the workflow: pr-checks.yml now invokes --prefix-only, so graph invariance is not run on pull requests. Rewrite this section to distinguish the PR guard's single prefix assertion from the two assertions used by baseline verification; otherwise readers may incorrectly assume ordinary PRs are checked for graph drift.

`.github/workflows/pr-checks.yml` runs `check-lockfile.sh` on every pull request. It makes **two independent
assertions, both of which must pass**:

specs/2026-08-10_normalize-package-lock-resolved-urls/design.md:529

• The implemented PR guard no longer compares against the base commit; it runs check-lockfile.sh --prefix-only so legitimate dependency changes are allowed. This architecture summary still documents the superseded behavior.

This issue also appears on line 537 of the same file.

**Guard (every PR):** `pr-checks.yml` → `lockfile` job runs `check-lockfile.sh` against the base commit → on failure,
prints offending package paths plus the remediation command; `scripts` job runs shellcheck + bats.

[Benno42]

🚀 LGTM