xlsx is pinned to a CDN tarball, which breaks installs in restricted environments

[jstet]

The problem

package.json pins the runtime dependency as

"xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz"

A non-registry URL in dependencies makes installing this package impossible in
any environment that restricts remote tarball fetches. Two independent reports so
far:

• CorrelAid/formulaid (its issue [survey2ddi 2/6] Port normalize_responses: the LimeSurvey response-data path #11, wiring up XLSValidator) could not
  npm install the package at all; it needed --allow-remote=all, and worked
  around it by building locally and installing a tarball.
• The same restriction blocked me from verifying the fresh-install path while
  fixing tsc build does not emit dist/generated/conventions.json — prepare script leaves dist incomplete #1 — npm error code EALLOWREMOTE ... Refusing to fetch "xlsx@https://cdn.sheetjs.com/...".

Why the obvious workarounds do not help

Both consumer-side theories floated so far are wrong, and worth writing down so
nobody implements them:

• "Commit dist/ (like @correlaid/cdl-design)." That removes the need to
  run our prepare script, but xlsx is a runtime dependency — the consumer's
  installer still has to fetch that tarball. A committed dist/ does not change
  the failure.
• "Ship a release artifact." Same reasoning. Unless the artifact bundles
  xlsx, the dependency still resolves from the CDN at install time.

So this is not a packaging problem; it is a dependency-source problem.

Options

1. Move to the npm-registry xlsx. SheetJS stopped publishing to npm after
   0.18.5, so this means pinning xlsx@^0.18.5 — an older SheetJS. Cheapest fix,
   restores plain npm install, and CorrelAid/formtransform-app and
   CorrelAid/formulaid already depend on xlsx@^0.18.5 themselves, so they would
   also stop carrying two copies. Risk: a behavioural difference between 0.18.5
   and 0.20.3 in workbook parsing. The contract suite (npm run test:contract)
   plus the blessed snapshots should catch that — if all 707 vitest tests and the
   pyxform oracle pass on 0.18.5, the risk is close to zero for our read paths
   (XLSX.read, XLSX.write).
2. Vendor the SheetJS tarball into the repo and depend on a file: path.
   Keeps 0.20.3, works offline, but adds ~1 MB of binary to git and a manual
   update path.
3. Make it a peer dependency and let each consumer bring its own xlsx. Honest
   about the fact that consumers already have one, but it pushes the CDN problem
   onto them and breaks the CLI's standalone install.
4. Do nothing, document it. Consumers pass --allow-remote=all (npm) or the
   bun equivalent. Cheapest today, but every new consumer rediscovers it, and it
   will keep breaking locked-down CI.

Recommendation

Option 1, gated on the test suite. Concretely: switch the pin to xlsx@^0.18.5,
run npm test (707 tests), npm run test:py and npm run bless with no diff
expected in the blessed snapshots. If any snapshot moves, stop and reconsider —
that difference is exactly what we would be shipping to consumers.

Whoever picks this up: report the test results before changing the pin
permanently, and update the install instructions in README.md either way.

[jstet]

Done in a314f76, on main. Option 1 as filed: "xlsx": "^0.18.5" from the npm registry.

The gate came out clean. Under 0.18.5:

• npm test — 707 tests, 47 files

• npm run test:py — 33 passed

• npm run validate (7 gates) + scripts/check-drift.sh

• npm run bless — no snapshot content moved. The only diff across the 13 touched files was prodDate advancing to today's date, which every bless produces regardless of the parser:

  -        <prodDate date="2026-07-22">2026-07-22</prodDate>
  +        <prodDate date="2026-08-19">2026-08-19</prodDate>

  I reverted that churn rather than committing a date bump. So the 0.20.3 → 0.18.5 change is not observable in anything we emit — unsurprising, since the only SheetJS surface the library touches is XLSX.read in src/xlsform/loader.ts.

• bun build dist/index.js --target=browser — bundles, 1.0 MB (was 1.1 MB)

The install that has failed for every consumer now works. Same clean directory, same environment that produced EALLOWREMOTE an hour ago, no --allow-remote flag:

$ npm install "git+file:///…/formtransform#main" --no-audit --no-fund
added 13 packages in 18s

$ ls node_modules/@correlaid/formtransform/dist/generated
Appearances.d.ts  Appearances.js  conventions.d.ts  conventions.js  conventions.json
DdiMappings.d.ts  DdiMappings.js  TypeMappings.d.ts  TypeMappings.js  …
$ ls node_modules/@correlaid/formtransform/dist/index.d.ts
node_modules/@correlaid/formtransform/dist/index.d.ts

That also closes the loop on #1 from the consumer side, and confirms the prepare-runs-tsc path works for git installs: dist/ is gitignored, so the clone cannot contain it — it was built during install. The .d.ts files are there because of e7842ed, which fixed a separate bug: package.json advertised "types": "dist/index.d.ts" while tsconfig never set declaration, so consumers were getting an untyped module and hand-writing declaration stubs.

Reverting is a one-line pin change if a 0.18.5 parsing difference ever surfaces downstream.

Filed separately as #4: the release-asset idea, which is still worth having for a different reason — letting github:-URL installs skip the build step entirely.