Repository navigation
refactor: split the dashboard API client into domain modules - #14563
Conversation
UX Review (Fable 5) — ✅ PASSUX-level review of UX-Verdict: PASS Nothing to check. [UX-REVIEWED] c8a2472 |
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Coordinate the landing window: ~60 open PRs touch Suggestions
[DESIGN-REVIEWED] c8a2472 |
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Confirm the surface test's 665-key-order and 171 no-session-key lists were generated from base, not this head — they are the compatibility pin. What this change shipsInventory (8 items) — 8 justifiedIntent: let a maintainer find and change any dashboard API endpoint in a domain-owned module while every caller keeps the identical
Checks run: [FIRST-PRINCIPLES-REVIEWED] c8a2472 |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Opus 5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
287f1bd to
7ed9efb
Compare
|
|
Rerunning two jobs on
The same jobs passed on this PR's two earlier heads (287f1bd, 7ed9efb). Each run gets one |
6336a14 to
6d42b1c
Compare
|
Update to the rerun note above: the pending CI and Build reruns were not issued. |
|
|
Rerunning the Opus 5 Review lane once on
The run is 36383529237 and the failed job is 108804028312, at step 13, "Post Opus 5 review summary". The withheld verdict is kept in that run's |
Move the 664 endpoint methods and their wire types out of website/src/api/client.ts into 40 domain modules under website/src/api/client/. Each module exports a create*Endpoints factory that the facade hands the transport it owns, so no module imports a runtime value from client.ts and the session key, j/jNullable and auth recovery keep one definition. client.ts keeps the transport and auth-recovery pipeline, re-exports every moved type and constant, and assembles the same plain api object by spreading the modules' segments in the original key order. Four methods and the Kiro usage types stay defined in client.ts because other docs, the i18n gate or a late-bound sibling call pin them there. A capture of all 670 methods under seven response shapes is byte-identical at the base and this head. New ApiClient.refactor tests pin the api shape, one owner per key, the transport install, the raw-fetch reads, caller-owned bodies and the late-bound wakatime export URL. The four owning docs name the new owners.
ApiClient.refactor.surface.test.ts holds Object.keys(api) and the teams/appearances namespaces to the order the split was cut from, and asserts that the 171 members whose request carried no X-Session-Key there still send none, so two swapped spreads or a raw read or write moved onto the shared helpers fail instead of passing silently. Also tidies three comments the move left misleading (a stray "Chat" heading, and the usage/capability stub note split between its two modules) and states in dashboard-token-auth.md that authorization stays on the gateway: the token middleware and the handler-level owner gate whose owner_only and stale_session_reauth refusals the client only surfaces.
a356a41 to
c8a2472
Compare
|
Rebased onto |
|
Rerunning Pod Boot Canary (Windows) once on
That is a Windows file-in-use race while tearing down a real pod. This PR changes no Python or pod code.
|
|
Problem / Motivation
Goal: A maintainer can find and change any dashboard API endpoint in the module that owns its domain, while every page, test and edition keeps calling the same
apiobject with the same requests as before.website/src/api/client.tsheld all 664 dashboard endpoint methods, about 140 wire types and the whole transport and auth-recovery pipeline in one 5,842-line file. Finding one endpoint's wire contract meant scanning thousands of unrelated lines, and every change to any endpoint landed in the same file.Why it matters
Not a goal
j/jNullable, silent refresh, re-auth banner, stale-owner prompt); it stays where it is.api/clientand everyvi.mock('../api/client')keeps working as it is.apimember.deleteLesson,saveDecisionsConsent,browseRemoteArtifacts,wakatimeExportDownloador the Kiro usage types, which other docs, the i18n gate or a late-bound call pin toclient.ts.What changed (motivation → approach → change)
Every endpoint change used to collide in one 5,842-line file, and finding an endpoint's wire contract meant reading it. This splits the endpoints by domain so each lives with its own types, while callers see exactly the same
api.apiliteralwebsite/src/api/client/(chat, memory, security, config endpoints, artifacts, …), each acreate*Endpointsfactoryclient.tsclient.tsclient.tsclient.ts, unchangedapiEvery endpoint moved into the module for its domain with its code unchanged; only comments whose "above"/"here" the move made wrong were reworded. A domain module never imports a runtime value from
client.ts: the facade hands each factory the one transport it owns (ClientTransportinwebsite/src/api/client/transport.ts), holding the same helper objects it installs as the blessedapiTransport. That keeps one definition of the session key and the recovery pipeline, and it keeps the module graph acyclic at runtime.client.tsthen spreads the segments intoapiin the order the methods have always had, so the object keeps its identity, key order, nestedteams/appearancesshape and plain data properties thatvi.spyOn(api, …)and{ ...mod.api }mock factories rely on. Four methods and the Kiro usage types stay defined inclient.ts, each with a comment naming what pins it there: two are cited there by other specs, one carries a literal the i18n gate would count as newly written, andwakatimeExportDownloadstill readsapi.wakatimeExportUrlat call time. The four owning docs now name the new owners:dashboard-token-auth.mdgains a map of the browser-side recovery owners and a note on how the client tells the gateway's own 403 from a proxy's sign-in page, andsteering-viewer.md,persistent-agent-channels.mdandextension-seams.mdpoint at the modules that define their endpoints.Backwards compatibility
Compatible: every export of
api/clientkeeps its name, kind and type, and everyapimember keeps its key, position, signature and wire behavior. A throwaway harness called all 671 methods (including the nested ones) under seven response shapes (success, no arguments, object arguments, 500, 204, 403X-Auth-Required, 401stale_session_reauth) at the base and at this head: the recorded requests, results, errors, events, DOM effects and error journal are byte-identical. The only difference it saw is the order of four constant exports on vitest's module object, which a native ESM namespace sorts anyway.Tests
ApiClient.refactor.wire.test.tspins what a move could silently change: raw-fetchreads keep sending no session key, the caller-owned bodies ofunlinkMirrorandcloudLaunch,bundled_clipassing through untouched, owner-only 403s stayingApiErrors, the nestedteams/appearancesrequests, the self-parsing publish and export error branches,wakatimeExportDownloadfollowing a replacedapi.wakatimeExportUrl, and thatapiTransportand the endpoints issue identical requests.ApiClient.refactor.facade.test.tspins theapishape (one plain object, writable data members, spy and spread support) and that every member has exactly one owner, so a key two segments both define fails instead of silently taking the later one, and thatinstallApiTransportruns once at load with the seven helpers.ApiClient.refactor.surface.test.tspins the key order of all 665 members and the two nested namespaces, and the 171 members that send noX-Session-Key, both generated from the base the split was cut from.client.tsas well; each was checked to fail on a deliberate violation (a duplicate key, two swapped spreads, a raw read moved ontoget, a raw write moved ontopatch, an accessor member, a download bound to its own URL builder).ApiClient.coverage.test.tsx, the three other owned tests, the 21 direct-client tests andKiroPrerequisiteGate.test.tsxpass unchanged.scripts/local-gate.py --dry-runselects 1,112 backend and 312 frontend related files. The frontend set ran in full (314 files, 9,218 tests); the backend set was narrowed to the guard tests this change can reach (4 files, 296 tests) beside the whole static gate floor. CI owns the broad set.Manual verification
N/A — no UI or behavior changes; the byte-level parity harness and the unit suites cover the contract.
Screenshots / video
Why no screenshot: the change moves API client code between modules and renders nothing differently.
Related Issues
no linked issue: a behavior-preserving structural refactor of the dashboard API client.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)