feat: cross-repo compatibility matrix + CI check (#395)

[bright5455]

Closes #395

Problem

bridgelet-core, bridgelet-sdk, and this repo each release independently, and nothing recorded which frontend release actually works against which SDK version, or gave an automated signal when a combination breaks.

What this adds

• docs/compatibility.md — the human-readable matrix: which bridgelet releases are verified against which bridgelet-sdk / bridgelet-core versions, a status legend, and the update process.
• compatibility.json — the machine-readable pin (verified.bridgeletSdk/bridgeletCore: repo/ref/commit/version) that both CI and the release process read. Currently pinned to bridgelet-sdk/bridgelet-core main by commit SHA, since neither repo has cut a tagged release yet.
• .github/workflows/compatibility.yml — checks out the pinned bridgelet-sdk commit, boots it against a real Postgres + Stellar testnet, and runs scripts/check-sdk-contract.mjs against its live OpenAPI spec (GET /api/docs-json). It fails the build if an endpoint or field frontend/lib/create-bridgelet-client.ts depends on is missing — this is the authoritative pass/fail signal, and it runs on every PR (path-filtered) and on a daily schedule without needing funded-testnet secrets. When BRIDGELET_SDK_* secrets are configured (documented in docs/compatibility.md#required-ci-secrets) it additionally runs the e2e/ Playwright suite in "SDK integration" mode as a best-effort secondary check; without them, it still verifies install/build/migrate/boot and says explicitly in the job summary what was skipped rather than reporting a false pass.
• scripts/check-compatibility-doc.mjs, wired into .release-it.json's before:git:release hook — blocks tagging a release until compatibility.json and docs/compatibility.md have been updated for that version and CI has actually verified the pin (status: "verified"). I ran it locally against the current repo state and confirmed it correctly refuses to release right now, since the pin hasn't had a passing CI run yet.
• README.md, CHANGELOG.md, and package.json (bridgeletCompatibility pointer + check:compatibility/check:sdk-contract scripts) updated to reference the above.

Why not a full-file diff or a pure browser e2e check?

Two things I found while building this that shaped the design, flagged here for visibility:

1. frontend/lib/bridgelet.ts is hand-written, not the output of frontend/scripts/generate-types.mjs (which emits openapi-typescript's paths/components shape). Regenerating and diffing that file against a live SDK would show a 100% rewrite on every run regardless of real compatibility — a false-positive failure, not a signal. check-sdk-contract.mjs instead asserts field-name presence for the specific endpoints/fields the frontend's client actually reads/sends, resolving $refs against the live spec. It's field-presence, not full type/enum equivalence — documented as a known limit in the script's header and in docs/compatibility.md.
2. frontend/components/mock-provider.tsx currently enables MSW mocking whenever NODE_ENV=development, regardless of any E2E_USE_MOCKS setting, and claim-flow.tsx's redeem handler has a hardcoded dev-mode stub. So the e2e/README.md-documented "SDK integration" mode doesn't yet exercise every route against a real backend end-to-end. I've kept the Playwright run as a secondary, best-effort check (continue-on-error, doesn't fail the job) and documented the gap rather than either silently claiming full e2e coverage or expanding this PR's scope into fixing the mock-toggle wiring, which is a separate, pre-existing issue.

I also found, while comparing the frontend's types against bridgelet-sdk's actual DTOs, that the frontend's AccountStatus type (pending | claimed | expired) doesn't match the SDK's real enum (pending_payment | pending_claim | claimed | expired | failed) — a genuine, pre-existing drift. check-sdk-contract.mjs deliberately doesn't check enum values (see above), so this doesn't fail CI; it's called out in docs/compatibility.md#known-gap-this-check-does-not-close as a known issue for whoever picks it up next, not something this PR fixes.

Acceptance criteria

• A compatibility matrix exists and is kept current as part of each release — docs/compatibility.md + compatibility.json, enforced by the release-it hook.
• CI verifies at least one known-good cross-repo combination on each PR or on a scheduled basis — .github/workflows/compatibility.yml, PR (path-filtered) + daily schedule + manual dispatch.
• .release-it.json release process updated to require the compatibility doc be updated before tagging — before:git:release hook, verified locally to correctly block.

Test plan

• node scripts/check-compatibility-doc.mjs run locally — correctly exits non-zero against current repo state (pin not yet CI-verified), with a clear error message.
• node scripts/check-sdk-contract.mjs unit-tested locally against a mock OpenAPI server built from bridgelet-sdk's actual DTOs (pulled from the real repo) — passes on a matching spec, fails with a precise message when a depended-on field is removed.
• .github/workflows/compatibility.yml validated for YAML syntax; steps cross-checked against bridgelet-sdk's actual .env.example, main.ts bootstrap (network-guard, Swagger path, port), and health controller — I don't have a way to execute a full Postgres+Stellar-testnet run of bridgelet-sdk from here, so the first real CI run may surface small environment fixes.
• First live run of .github/workflows/compatibility.yml on this PR (will run automatically since this PR touches compatibility.json).

🤖 Generated with Claude Code

[vercel]

@bright5455 is attempting to deploy a commit to the aminubabafatima8-gmailcom's projects Team on Vercel.

A member of the Team first needs to authorize it.