@pdpp/local-collector fails with ERR_MODULE_NOT_FOUND: missing @pdpp/reference-contract dependency

[natea]

Description

Running the enroll command from the self-host setup instructions (https://pdpp.dev/self-host) fails immediately with ERR_MODULE_NOT_FOUND.

Repro

npx -y @pdpp/local-collector enroll --base-url http://localhost:3000 --code <redacted> --device-label "My laptop"

Error

node:internal/modules/package_json_reader:314
  throw new ERR_MODULE_NOT_FOUND(packageName, fileURLToPath(base), null);
        ^

Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@pdpp/reference-contract' imported from .../node_modules/@pdpp/local-collector/dist/polyfill-connectors/src/local-device-client.js
    at Object.getPackageJSONURL (node:internal/modules/package_json_reader:314:9)
    at packageResolve (node:internal/modules/esm/resolve:768:81)
    at moduleResolve (node:internal/modules/esm/resolve:855:18)
    at defaultResolve (node:internal/modules/esm/resolve:985:11)
    at #cachedDefaultResolve (node:internal/modules/esm/loader:747:20)
    at ModuleLoader.resolve (node:internal/modules/esm/loader:724:38)
    at ModuleLoader.getModuleJobForImport (node:internal/modules/esm/loader:320:38)
    at ModuleJob._link (node:internal/modules/esm/module_job:182:49) {
  code: 'ERR_MODULE_NOT_FOUND'
}

Node.js v22.22.3

Root cause

dist/polyfill-connectors/src/local-device-client.js in the published package imports:

import { canonicalTerminalRunCommitEnvelope } from "@pdpp/reference-contract/common";

but:

1. @pdpp/reference-contract is not listed in local-collector's package.json dependencies (only zod is listed), so npm/npx never installs it.
2. @pdpp/reference-contract does not exist on the public npm registry at all (npm view @pdpp/reference-contract returns a 404).

This looks like an internal pnpm-workspace package that's referenced in the compiled dist/ output but never got published or added as a real dependency when local-collector was packaged for npm.

I confirmed this import is present and unresolved in every published version I checked going back to 1.4.1 through the current 1.5.4, so this isn't a recent regression — the npm package appears to have never worked correctly for anyone outside the monorepo.

Environment

• Node.js v22.22.3
• @pdpp/local-collector 1.5.4 (also reproduced on 1.5.3, 1.5.2, 1.5.0, 1.4.1)
• macOS
• Invoked via npx -y @pdpp/local-collector ... per the self-host docs

Suggested fix

Either publish @pdpp/reference-contract to npm and add it as a real dependency of local-collector, or bundle/inline the needed exports into local-collector's build so the published package has no unresolved workspace-only imports.

[natea]

Update after digging into the source: @pdpp/local-collector actually lives in a separate repo now, PDP-Connect/data-connect (per packages/local-collector), not in this monorepo. Filing here since the npm package itself is what's broken, but the fix belongs in that repo.

Root cause confirmed: packages/local-collector/scripts/postbuild.ts in data-connect is supposed to rewrite the bare @pdpp/reference-contract/common import into a vendored relative path before publish (there's a whole commented-out mechanism for this — see tsconfig.build.json lines ~39-49 and postbuild.ts lines ~51-91). There's even a dedicated test, test/validate-package-bare-specifiers.test.ts, that specifically asserts this exact bare import must not survive the build.

When I built packages/local-collector from source in that repo (npm run build), the postbuild step ran correctly and produced a clean dist/ with no bare @pdpp/reference-contract imports anywhere — confirmed via grep -rn "reference-contract" dist/ (only .d.ts type references remain, no runtime imports). So the build pipeline itself works.

That means the npm-published 1.5.4 (and every version back through 1.4.1 that I checked) was published from a build where this step either didn't run, ran against stale source, or the published tarball wasn't rebuilt after a source change reintroduced the bare import. Worth checking whether prepack/prepublishOnly actually invokes the same build script used by CI's pack-install-run job — if publishing happens through a different path (e.g. manual npm publish without running npm run build first, or a stale dist/ left in the working tree), that would explain the drift between a passing CI check and a broken published artifact.

Second, separate bug found while testing a from-source build: running enroll + run end-to-end against a local PDPP reference server, all record batches collect and send successfully (confirmed 3164/3164 sent in my test), but the final terminal-run-commit is rejected every time with:

local device request failed: 400 invalid_request message=terminal run commit body or binding is invalid

This reproduces on every recover --apply pass too (dead-letter count grows by one each pass instead of clearing), so it's not a transient failure — something in the terminal-run-commit request body/binding doesn't validate against the reference server. Data itself isn't lost (all records ARE delivered), but the connection gets stuck in lifecycle_state: "dead_letter" and never reports as drained/complete. Happy to file this as a separate issue with a full repro if useful — let me know.

[tnunamak]

The packaging fix for this shipped in PDP-Connect/data-connect#73, which adds packages/local-collector as a semantic-release pkgRoot so the corrected bundle is published.

Assisted-by: AI