@planning-board/contract

The tile contract of the Heppe Planning Board: what a product repository publishes and the board reads.

• The tile — BoardSummary, the shape of meta.json a publisher writes per environment, and isSummary, the guard the board validates it with. isSummary checks every field the board dereferences and tolerates fields it does not know.
• The registry — Registry, the shape of a view's case registry (e2e/cases/<view>.json in the Heppe monorepo).
• The reason line — reasonLine / REASON_MAX, the first line of a failure or skip message with anything shaped like an email address or a phone number redacted and the length capped: the only part of a message a public tile may carry.
• The Linear project slug — linearProjectSlug, read out of a registry's links.linearProject, the one name a tile and a Linear plan share.

Who uses it

The Heppe monorepo's publish step (apps/admin/planning-board/*) imports the types, reasonLine and linearProjectSlug to write tiles; the board's own workspace imports it through @planning-board/planning. Nothing else of the board is shared.

Semver

Read from the board's side. Adding an optional field that readers tolerate is a minor release. Adding a required field, removing a field or narrowing one is a major release: a required addition breaks every producer that constructs BoardSummary and makes isSummary refuse every older tile. A field that is to become required goes in optional first.

test/fixtures/test-meta.json is a real tile from a nightly run; refresh it when the summariser's output changes shape, and let fixture-tile.test.ts say whether the change is minor or major.

Releasing

1. Bump version in package.json on a pull request and merge it.
2. On main, create the tag contract/vX.Y.Z and push the tag.
3. .github/workflows/release-contract.yml builds, tests, packs with pnpm and stages the version by npm trusted publishing (no token anywhere). It refuses when the tag and the manifest disagree, or when the tag is not on main.
4. A maintainer approves the staged version with 2FA, on npmjs.com under the package's Staged packages or from a terminal: npm stage list @planning-board/contract, then npm stage approve <stage-id>. Until then no consumer can install it; npm stage reject <stage-id> drops it.

The package ships compiled dist/ (built on prepack), because Node refuses to strip types from files under node_modules; inside this workspace it resolves to its source.

The publish entry

@planning-board/contract/publish is the publisher's side: proofCase names a test from its registry; allureReporter is the reporter entry that writes the labels; stripAttachments keeps screenshots and traces out of a public tile; summarize turns Allure results and registries into the tile (and runs as a CLI: node dist/publish/summarize.js --results <dir> --cases <registry dir> --environment <env> --out <meta.json>); listedTests and registryFindings hold a suite's registries and specs together, one finding per sentence.