chore: migrate to pnpm and Biome, and harden the MCPB bundle build - #37

Description

Ports tomtom-internal/tomtom-traffic-analytics-mcp#34
to this repository: npm → pnpm and ESLint + Prettier → Biome, plus the guards that PR
added around the .mcpb bundle build.

Biome replaces the whole ESLint + Prettier plugin/config stack and runs in milliseconds instead
of seconds; pnpm installs faster from a content-addressed store; both match what the team
already uses. Full reasoning is in the commit messages; this is the summary.

1. pnpm + Biome (1e17407)

packageManager: pnpm@11.21.0, pnpm-lock.yaml, and biome.json replacing eslint.config.js,
.prettierrc, .prettierignore and .eslintignore. The rule set is selected with
linter.rules.preset: "recommended" — the older recommended: true field is deprecated in
Biome 2.5 and goes away in the next major. overrides and allowBuilds move to
pnpm-workspace.yaml, which pnpm 11 requires. All workflows, the Dockerfile, VS Code tasks and
docs follow; CI gains pnpm type-check and pins pnpm/action-setup. Dropped the
@rollup/rollup-linux-x64-gnu optionalDependency, pinned to 4.9.5 against rollup ^4.62.

Three settings are load-bearing, each documented in place:

Contributor note: pnpm run <script> no longer auto-syncs node_modules after a branch
switch. Run pnpm install yourself, the same contract npm always had.

Biome now covers src/, scripts/, tests/ and the root config scripts, where eslint src
covered only src/ — 5 files outside src/ reformat mechanically as a result. JSON stays out of
scope on purpose: prepare-release.yml rewrites package.json and manifest-binary.json with
yq, whose formatting would then fail pnpm format on the first PR after every release. A
.gitattributes with * text=auto eol=lf keeps pnpm format from failing on every file on a
Windows checkout. Also drops the dead version:sync and scripts/generate-version.cjs,
superseded by prepare-release.yml since LSI-305.

2. The .mcpb build was hardened, not replaced (ce71e59)

Upstream #34 also rewrote scripts/build-mcpb.cjs, because on internal main the bundle was
packed by mcpb pack . on a Linux runner and only ever worked on Linux. That does not apply
here: this repository has produced one self-contained bundle per platform since #15, each
shipping its own Node runtime so the launcher is spawned as type: binary — which is what avoids
the macOS Hardened Runtime library-validation restriction on dlopen of non-Anthropic-signed
native modules inside Claude Desktop's Electron UtilityProcess sandbox. Upstream's type: node
rewrite would reintroduce that failure, and its CI smoke test would not catch it, since it runs
the server under a plain node.

So the builder stays and everything around it comes across:

• build-mcpb.yml could only ever fail. It ran a single ubuntu-22.04 job and uploaded
  dist/mcpb/tomtom-traffic-analytics-mcp.mcpb, a path the per-platform script has not produced
  since Tool description audit, pipeline fixes, and per-OS .mcpb packaging #15. It is now a matrix over five native runners — darwin-arm64, darwin-x64,
  linux-x64, win32-x64, win32-arm64 — and runs on pull requests too, bundles being the one
  artifact a Linux-only CI run cannot vouch for.
• The bundle no longer carries the devDependency tree. It copied all of node_modules; it now
  stages a dedicated pnpm install --prod --frozen-lockfile and drops pnpm's .pnpm, .bin and
  bookkeeping. Measured here: 9595 files / 321 MB of node_modules, against 2842 total bundle
  entries with no vitest, typescript, rollup, biome or esbuild left in.

Four guards, since a bundle that cannot run still packs perfectly:

• the staged tree is rejected if @duckdb/node-bindings-<platform>-<arch> is absent, which is the
  whole reason to build on a native runner
• it is also rejected if it holds any symlink. The old copy step called symlinkSync for each one
  it met, and a link only survives an extractor that restores it — otherwise the target is written
  out as a short text file and the server dies on its first require. pnpm's hoisted layout still
  leaves 30 in node_modules
• MCPB_EXPECT_TARGET fails a matrix job whose runner is not the platform its row claims; bundles
  are named from the matrix but built from the host
• scripts/verify-mcpb.cjs unpacks the bundle, asserts the launcher and the embedded Node binary
  kept their executable bit, runs SQL through the bundle's own runtime and duckdb binding, then
  completes an initialize/tools-list handshake against the extracted server

Packing moves from archiver to mcpb pack, which validates the manifest against the published
schema before writing and stores Unix modes — one dependency fewer, and mcpb unpack does the
extraction in the verifier. .mcpbignore goes away; nothing packs the repository directory now.

release.yml globs ./dist/mcpb/**/*.mcpb and asserts one bundle per matrix entry, the count read
from the matrix with yq; otherwise fail-fast: false plus one red platform would quietly ship a
release missing a bundle. Because compatibility.platforms has no arch field, both macOS bundles
advertise ["darwin"] and only the filename separates arm64 from x64, so every release now carries
a machine-to-file table in its notes.

Other divergences from upstream #34

Upstream was cut against a main that does not carry this repository's later fixes, so:

Upstream commits a66b3dd and 8ddce10 are combined into 1e17407 here, since both are Biome
and pnpm configuration and splitting them would have meant two lockfile states for no reviewer
benefit.

Type of change

• Bug fix (non-breaking change which fixes an issue): build-mcpb.yml uploading a path the
  build script does not produce
• New feature (non-breaking change which adds functionality): pnpm, Biome, the bundle matrix
  and verify:mcpb
• This change requires a documentation update (README, CONTRIBUTING, CLAUDE.md updated here)

How Has This Been Tested?

• pnpm install --frozen-lockfile from a clean tree; type-check, lint (0 errors, 178
  pre-existing warnings), format, build, and 285/285 unit tests across 35 files
• docker build + docker run: /health returns {"status":"ok","version":"0.2.1"}, and
  id inside the container reports uid=1000(node)
• build:mcpb on darwin-arm64: 75.8 MB bundle in 19s, 2842 entries, 0 symlinks, no
  devDependencies and no pnpm bookkeeping in the archive
• verify:mcpb on that bundle: unpacked, launcher and embedded Node still executable, duckdb
  executing SQL, 8 tools over a real MCP handshake
• The MCPB_EXPECT_TARGET guard confirmed to fail a deliberate darwin-arm64 / win32-x64
  mismatch

The other four platform bundles are built and verified by this PR's own build-mcpb.yml run — that
is the point of the matrix. Integration tests (test:comprehensive, test:http) run in CI where
the API keys are available.

Reviewer notes

• CI cost: the bundle matrix is 5 jobs including two macOS (10× minutes) and two Windows (2×)
  on every PR. Deliberate, but the pull_request trigger can be narrowed to bundle-affecting
  paths.
• Follow-ups: tsconfig.json still type-checks only src/, so scripts/ and tests/ get
  lint and formatting but no types. The 178 Biome warnings are untouched.
• Next sync from internal: this repository now differs from upstream chore(deps): bump hono from 4.12.27 to 4.13.1 #34 in the MCPB build by
  design. Whoever reconciles internal feat: MCP apps for traffic tools (incidents, area analytics, flow, junctions, routes) #26 (which carries the type: binary builder there) should
  land this shape, not upstream chore(deps): bump hono from 4.12.27 to 4.13.1 #34's.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works: verify-mcpb.cjs
  runs per platform in CI
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules
• I have signed-off my commits as per the DCO

🤖 Generated with Claude Code