Cursor rule

1---
2description: CLI, MCP, and share must pass the same format opts (tz, locale, flags)
3globs: packages/{cli,mcp,core}/**/*
4alwaysApply: false
5---
6 
7# Surface parity (CLI / MCP / share)
8 
9Any user-visible formatter change must land on **all three surfaces** before merge:
10 
11| Surface | Verify |
12|---------|--------|
13| CLI | `packages/cli` command + `packages/cli/test/` |
14| MCP | `toolGet*` in `packages/mcp/src/tools.ts` + `packages/mcp/test/tools.test.ts` |
15| Share | `formatShare*` + `packages/mcp/test/share.test.ts` |
16 
17`scripts/release-qa.sh` exercises CLI + share rendering across locales and timezones; MCP arg threading is **not** rendered there — guard it with unit tests.
18 
19## Knockout surfaces live-resolve — never read the skeleton (the #1 recurring bug)
20 
21The bundled schedule's knockout slots are **resultless placeholders** (codes like `2A`/`2B`, flag `🏳️`). So a team-facing surface that reads the static bundle is **silently** blind to a confirmed knockout tie — no crash, no wrong data, just a stale placeholder. **Knockout live-resolve regressions** shipped repeatedly in different surfaces (root cause: skeleton reads, cache gaps, or both):
22 
23- v0.8.2 — R32 pre-draw seeds rendered static, didn't live-resolve.
24- v0.8.6 — bracket third-place slots never read the merged live `match.home/away`.
25- v0.8.7 — `next` / `share next` / MCP next-fixture resolvers read only the static bundle.
26- v0.8.8 — statusline next-match countdown read the static bundle (`🏳️ vs 🏳️` / `⚽ —` in knockouts).
27- v0.8.9 — empty fixtures cache stamped the full 15min TTL at phase boundaries; stale-cache `live · syncing…` still read the skeleton.
28 
29**Rule:** every team-facing surface must reach the live overlay (`getBracket` / `getNextFixtureForTeam` — the same `fetchWindow` the bracket uses), fail closed on outage, and attribute the provider only when the overlay served the chosen fixture. **Exception — statusline:** hot path cannot fetch; the cold-path refresher calls `getKnockoutFixtures` and caches to `CacheState.fixtures`; `renderPrompt` merges that slice over the bundle (countdown **and** `live · syncing…`), never leaking 🏳️. **Exception — MCP `fixtures://{date}` resource:** deliberately static ("Static fixture list"; a resource URI carries no tz and gets no live overlay) — do not "fix" it to live-resolve without a maintainer decision; agents use `get_today`/`get_bracket` for resolved pairings.
30 
31| Surface | Entry point | Must |
32|---------|-------------|------|
33| CLI `bracket` / `next` | `cmdBracket` / `cmdNext` | call `getBracket` / `getNextFixtureForTeam` |
34| CLI `share bracket` / `share next` | `cmdShare` | same |
35| MCP `get_bracket` / `get_next_fixture` | `toolGetBracket` / `toolGetNextFixture` | same |
36| MCP `get_share_snippet{bracket,next}` | `toolGetShareSnippet` | same |
37| **statusline** | `renderPrompt` + `runRefresh` | hot path, NO network — indirect: refresher caches `getKnockoutFixtures` → `CacheState.fixtures`; `renderPrompt` merges them, **failing closed to `⚽ —`** when the cache lacks the pairing; unresolved placeholders dropped in syncing (never 🏳️). Empty successful fetch uses a **short TTL** (~60s); provider errors keep prior cache. **`cmdPrompt` and `cmdHook`** both spawn fixtures refresh in knockout phase. |
38 
39**Executable guard:** `packages/{cli,mcp}/test/knockout-surface-coverage.test.ts` pins one fake resolved tie (Mexico vs Ecuador) and asserts every surface renders the real nations, not `🏳️` (statusline from a seeded cache). **`statusline.test.ts` / `refresh.test.ts`** cover syncing + empty-cache TTL. **Adding a team-facing surface? Add it to that test and this table.**
40 
41## Format opts invariant
42 
43If a core formatter accepts `tz`, `locale`, `flags`, or `date`, **every wrapper** passes them from `CliConfig` / `CommonOpts`.
44 
45```typescript
46// ❌ BAD — locale only; tz silently drops to server local
47formatBracketList(view, { footer: false, locale: args.lang });
48 
49// ✅ GOOD
50formatBracketList(view, { footer: false, locale: args.lang, tz: args.tz });
51// or reuse fmtOpts(args) where shapes align
52```
53 
54## Regression tests
55 
56When adding a format option (e.g. `date: true` on `formatKickoff`):
57 
58- Add a **core** unit test for the option.
59- Add an **MCP tool test** proving `tz` changes output (e.g. UTC vs `America/Mexico_City` on a cross-midnight kickoff).
60- Update share tests if `formatShareBracket` / compact lines are affected.
61