fix(local-collector): publish the package so the packaging fix ships

[tnunamak]

Merges after #71. This branch is rebased on that PR's head, and keeps its pinned-expectation test exactly as approved there.

Problem

@pdpp/local-collector is broken on npm and the fix cannot reach anyone.

Every published version from 1.3.0 through 1.5.4 (current latest) is unrunnable. Those tarballs contain a compiled bare import of @pdpp/reference-contract, a package that is not declared as a dependency and does not exist on the registry. It resolved for developers through the workspace link and failed closed on every real install, so any invocation exits immediately:

$ npm i -g @pdpp/local-collector@1.5.4 && pdpp-local-collector --help
Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@pdpp/reference-contract'
  imported from .../@pdpp/local-collector/dist/polyfill-connectors/src/local-device-client.js

The packaging fix has been on main since the package moved to this repository, and the built output now contains no @pdpp/* bare imports at all. It reaches no user, because nothing publishes this package:

• PDP-Connect/pdpp's .releaserc.yaml records that publishing responsibility for @pdpp/local-collector moved here, and it retains no pkgRoot entry for it.
• This repository's npm-release workflow publishes only @pdpp/connector-protocol and @pdpp/collector-runtime.
• packages/local-collector/package.json is private: true at version 0.0.0, which blocks publishing. It does not block npm pack: a control run of npm pack --ignore-scripts against the base's exact private manifest succeeds and produces pdpp-local-collector-0.0.0.tgz.

The commit-analyzer scope gate closed the loop: fix(local-collector) was explicitly listed as a scope that releases nothing.

Approach

The package joins the existing lockstep release set rather than getting a parallel pipeline.

Versioning. The next publish must exceed 1.5.4, and it does so without a manual version field. semantic-release derives the version from this repository's v${version} tags; the highest is v2.1.0, which is the commit published as @pdpp/connector-protocol@2.1.0 (gitHead 187838be1). The next release is therefore at least 2.1.1, above the 1.5.4 line. The version field stays a placeholder that @semantic-release/npm overwrites at publish time, exactly as both sibling packages already do. The package name is unchanged.

Publish set. packages/local-collector is added as an @semantic-release/npm pkgRoot, ordered last, after the two packages its prepack builds against. publishConfig.provenance flips to true and the package is added to the workflow's existing gh attestation verify loop.

Plugin order determines invocation sequence, not atomicity. semantic-release tags before running publish hooks, so a failure partway through can leave a partial release, and a plain re-run is not guaranteed to repair it: the existing tag can make the next dry-run see no unreleased commit. The attestation loop runs after publication and cannot roll anything back.

Scope gate. Admitting local-collector to the allowlist required updating the exclusion rule in the same step. That rule is written as the exact complement of the allowlist, and the config's own header documents why: if a commit matches both a real rule and the exclusion, the exclusion's false wins and cancels the entire release batch, including unrelated real releases.

Release gate. The quality job runs one step calling the package's verify script, now extended to run pack-install-run alongside validate:package. #71 added that step for downstream-breakage coverage while the package was unpublished; this branch keeps a single step and updates its comment for the package now being published here. validate:package rejects any bare import the manifest does not declare. pack-install-run packs the tarball, installs it into a clean project, and drives the real CLI through advertise, enroll, and run against an in-process reference server. Because quality must pass before release, a failure blocks publication.

Verification

Run locally on the rebased head:

• npm run --workspace packages/local-collector verify exits 0: 218 tests, 213 pass, 0 fail, 5 skipped, ending in PASS pack-install-run local smoke. Wall time was 14-16s on this host across cold- and warm-build runs; an independent reviewer measured 113-119s on different hardware, so treat the duration as host-dependent rather than a fixed budget.
• A sabotage control confirms the gate bites: appending an undeclared @pdpp/reference-contract import to a built dist/ file makes validate:package throw and verify exit non-zero.
• npm pack produces a 92-file, 148.3 kB tarball. Installed into a clean temp project, pdpp-local-collector --help prints usage. enroll --base-url http://127.0.0.1:9 --code probe-code resolves its full module graph and fails only at the network call, with no ERR_MODULE_NOT_FOUND. Omitting --code exits 64 on argument validation before any network work, so the --code argument is required for this to be a resolution test.
• The same commands against published 1.5.4 in a clean project reproduce the crash quoted above.
• npm publish --dry-run --provenance --access public succeeds. This exercises packing and manifest handling only; it is not an authenticated publish and proves nothing about registry authorization.
• The scope-gate rules were re-derived against the installed @semantic-release/commit-analyzer, as the config header instructs. All 11 cases pass, including the batch case where a real fix(local-collector) commit sits alongside unrelated scoped and unscoped commits and still yields patch.
• npx vitest run scripts/npm-release-commit-analyzer.test.ts scripts/npm-release-signer-workflow.test.ts: 23 passed.

A semantic-release dry-run confirms the config loads and registers all three npm publish roots in order. An independent reviewer, running the same dry-run against a scratch clone with the candidate tree named main, observed the analyzer select 2.1.1 from tag v2.1.0. Attestation verification still cannot be exercised before a real release, unchanged from the note already in the workflow.

npm trusted publishing: an external prerequisite

Publishing uses OIDC trusted publishing (id-token: write), not a token. gh api /repos/PDP-Connect/data-connect/actions/secrets returns {"total_count":0,"secrets":[]}, so there is no NPM_TOKEN repository secret and none is proposed.

Trusted publishing is configured per package on npm, and this branch cannot configure it. Before merging, confirm or create for @pdpp/local-collector a Trusted Publisher of type GitHub Actions with organization PDP-Connect, repository data-connect, and workflow filename npm-release.yml — the filename alone in that field, not the full .github/workflows/ path — with no environment restriction, since the release job declares none. The authorization must permit direct npm publish.

The package's existing provenance attests to how it was published historically; it does not establish its current trusted-publisher settings, which were not inspected here.

If that authorization is missing or mismatched, the failure is fail-closed and early: @semantic-release/npm verifies auth for each package during verifyConditions, before any prepare, tag, or publish step, and the resolve-version dry-run invokes verification too. An independent reviewer confirmed this against the installed plugin by simulating a 403 OIDC exchange, which threw ENONPMTOKEN.

Follow-up after this lands

Once a corrected version is published, deprecate the broken range, substituting the actual published version for <NEXT>:

npm deprecate "@pdpp/local-collector@>=1.3.0 <NEXT" "Unrunnable: missing @pdpp/reference-contract dependency causes ERR_MODULE_NOT_FOUND on every install. Upgrade with npm i -g @pdpp/local-collector@latest"

This is an unexecuted maintainer step: it needs the real published version and npm write credentials.

Notes

The README documents installing and upgrading and records the affected 1.3.0-1.5.4 range with its error signature. It states that @latest still resolves to an affected version until a corrected release exists, and describes the gates as detecting the import failures they test for rather than as a guarantee against every packaging defect.

The commit-analyzer test is updated here because it asserted that local-collector commits release nothing, which is the premise this change reverses. The connect-scope.test.ts repair belongs to #71 and is unchanged by this branch.

Assisted-by: AI

[tnunamak]

This addresses PDP-Connect/pdpp#266, the ERR_MODULE_NOT_FOUND report against published @pdpp/local-collector.

Assisted-by: AI