Skip to content

refactor: split the dashboard API client into domain modules - #14563

Merged
bolichen97 merged 2 commits into
mainfrom
refactor/f01-api-client-domain-split
Sep 28, 2026
Merged

bolichen97 merged 2 commits into
mainfrom
refactor/f01-api-client-domain-split

Conversation

@bolichen97

@bolichen97 bolichen97 commented Sep 27, 2026 •

Copy link
Copy Markdown
Contributor

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 api object with the same requests as before.

website/src/api/client.ts held 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

  • The file changed about 345 times in 90 days, and over 60 open PRs touch it, so unrelated endpoint work collides in one file.
  • Reviewers could not see which owner a method belonged to, or which domain a wire type described, without reading the whole file.
  • The frontend refactor scopes that follow (WebSocket router, composer, chat page, app shell) need a stable API facade to build on.

Not a goal

  • Changing any endpoint's URL, method, query, headers, body or response handling.
  • Changing the transport or auth recovery (session key, j/jNullable, silent refresh, re-auth banner, stale-owner prompt); it stays where it is.
  • Changing a consumer: every import from api/client and every vi.mock('../api/client') keeps working as it is.
  • Renaming, reordering or reshaping any api member.
  • Moving deleteLesson, saveDecisionsConsent, browseRemoteArtifacts, wakatimeExportDownload or the Kiro usage types, which other docs, the i18n gate or a late-bound call pin to client.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.

Before After
Endpoint definitions 665 methods in one api literal 40 domain modules under website/src/api/client/ (chat, memory, security, config endpoints, artifacts, …), each a create*Endpoints factory
Wire types ~140 interfaces in client.ts Beside the endpoints that use them, re-exported from client.ts
Transport and auth recovery client.ts client.ts, unchanged
api One object literal The same plain object, assembled from the modules' segments in the original key order

Every 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 (ClientTransport in website/src/api/client/transport.ts), holding the same helper objects it installs as the blessed apiTransport. That keeps one definition of the session key and the recovery pipeline, and it keeps the module graph acyclic at runtime.

client.ts then spreads the segments into api in the order the methods have always had, so the object keeps its identity, key order, nested teams/appearances shape and plain data properties that vi.spyOn(api, …) and { ...mod.api } mock factories rely on. Four methods and the Kiro usage types stay defined in client.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, and wakatimeExportDownload still reads api.wakatimeExportUrl at call time. The four owning docs now name the new owners: dashboard-token-auth.md gains 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, and steering-viewer.md, persistent-agent-channels.md and extension-seams.md point at the modules that define their endpoints.

Backwards compatibility

Compatible: every export of api/client keeps its name, kind and type, and every api member 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, 403 X-Auth-Required, 401 stale_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.ts pins what a move could silently change: raw-fetch reads keep sending no session key, the caller-owned bodies of unlinkMirror and cloudLaunch, bundled_cli passing through untouched, owner-only 403s staying ApiErrors, the nested teams/appearances requests, the self-parsing publish and export error branches, wakatimeExportDownload following a replaced api.wakatimeExportUrl, and that apiTransport and the endpoints issue identical requests.
  • ApiClient.refactor.facade.test.ts pins the api shape (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 that installApiTransport runs once at load with the seven helpers.
  • ApiClient.refactor.surface.test.ts pins the key order of all 665 members and the two nested namespaces, and the 171 members that send no X-Session-Key, both generated from the base the split was cut from.
  • All three pass against the base client.ts as well; each was checked to fail on a deliberate violation (a duplicate key, two swapped spreads, a raw read moved onto get, a raw write moved onto patch, 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 and KiroPrerequisiteGate.test.tsx pass unchanged.
  • Local run on a shared host: scripts/local-gate.py --dry-run selects 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

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@bolichen97
bolichen97 requested a review from a team September 27, 2026 23:44
@bolichen97
bolichen97 requested a review from a team as a code owner September 27, 2026 23:44
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 27, 2026
@github-actions

github-actions Bot commented Sep 27, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — ✅ PASS

UX-level review of c8a2472efd83aaf212dd64cd725c03ff39c5e37f — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: PASS

Nothing to check.

[UX-REVIEWED] c8a2472

@github-actions

github-actions Bot commented Sep 27, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of c8a2472efd83aaf212dd64cd725c03ff39c5e37f — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Coordinate the landing window: ~60 open PRs touch client.ts, and this 5,400-line move conflicts them all at once.

Suggestions

  • Follow-up (not this PR): once in-flight PRs drain, verify no consumer iterates api's keys and then collapse the interleaved per-factory segments and the API_KEY_ORDER pin — the ~100-entry spread list exists only to reproduce accidental historical ordering, and every future endpoint pays its tax otherwise.

[DESIGN-REVIEWED] c8a2472

@github-actions

github-actions Bot commented Sep 27, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of c8a2472efd83aaf212dd64cd725c03ff39c5e37f — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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 ships

Inventory (8 items) — 8 justified

Intent: let a maintainer find and change any dashboard API endpoint in a domain-owned module while every caller keeps the identical api object — a structural MOVE (refactor), not a fix or new capability.

  1. 665 endpoint methods moved from one 5,842-line client.ts into 40 domain modules — justified.
  2. Transport and auth recovery stay sole-defined in client.ts, handed to each module via the new ClientTransport (12 members, wider signatures than the frozen 7-method edition ApiTransport — checked, not a second spelling) — justified.
  3. 41 create*Endpoints factories become importable; counted 0 consumers outside the facade, matching the declared core-internal seam — justified.
  4. Wire types re-exported from client.ts so every existing import path keeps working — justified.
  5. Four methods stay pinned in client.ts, each with a comment naming its pin — justified.
  6. Three new test files pin key order, one-owner-per-key, and wire behavior; no existing test deleted or edited — justified.
  7. dashboard-token-auth.md gains a browser-side recovery ownership map and a gateway-403-vs-proxy note (documents pre-existing edgeAuthChallenge behavior; same-commit doc rule) — justified.
  8. Three specs re-pointed at the new module owners — justified.

Checks run: projectHeader existed on base (moved, not added); sampled moved hunks byte-identical; telemetry.ts's facade import is type-only, so the runtime graph is acyclic as claimed; no product-shape item, so lens 9 does not fire.

[FIRST-PRINCIPLES-REVIEWED] c8a2472

@github-actions

github-actions Bot commented Sep 27, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of c8a2472efd83aaf212dd64cd725c03ff39c5e37f and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] c8a2472

False positive or not applicable? A repository writer can comment:
/ai-review override gpt c8a2472efd83aaf212dd64cd725c03ff39c5e37f: <one-sentence reason>

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 28, 2026
@github-actions

github-actions Bot commented Sep 28, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

Reviewed c8a2472efd83aaf212dd64cd725c03ff39c5e37f — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] c8a2472

Verdict parsed from the review's SHA-scoped output markers for commit c8a2472efd83aaf212dd64cd725c03ff39c5e37f.

False positive or not applicable? A repository writer can comment:
/ai-review override fable c8a2472efd83aaf212dd64cd725c03ff39c5e37f: <one-sentence reason>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 28, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) September 28, 2026 00:27
@bolichen97
bolichen97 force-pushed the refactor/f01-api-client-domain-split branch from 287f1bd to 7ed9efb Compare September 28, 2026 00:40
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Sep 28, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=3c591dd46aa7 Error Handling note in dashboard-token-auth.md fixed in 6336a14

The note belongs to this PR's owned-spec update: it states which 403 shape starts the recovery client.ts owns and which is a proxy page, the rule the new frontend owner map in the same spec relies on.
What changed now names it, so the description declares the doc change instead of shipping it undeclared.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Rerunning two jobs on 6336a14c1a7e1fdb6efc7ff593dcbea870b4be4e that the GitHub Actions incident around 03:05–03:30Z killed while they were still setting up. Neither job got far enough to read this diff.

Job Where it stopped Error
Cross-Platform Portability, job 108771704644, then its rerun 108774476419 actions/checkout (03:09:39–03:14:06, then again 03:26:59–03:28:04) The job has exceeded the maximum execution time of 5m0s
Screenshot Evidence, job 108771917007 Set up job (03:10:12–03:15:11) The job has exceeded the maximum execution time of 5m0s

The same jobs passed on this PR's two earlier heads (287f1bd, 7ed9efb). Each run gets one --failed rerun. The same window also hit three more jobs: two artifact uploads failed with Failed to CreateArtifact: Unable to make request: ETIMEDOUT (Build Wheel, Integration), and the i18n step could not fetch its base commit (Frontend Lint & Type Check). Their test and build steps had already passed. Those runs are still in progress; they get one --failed rerun once they finish.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 28, 2026
@bolichen97
bolichen97 force-pushed the refactor/f01-api-client-domain-split branch from 6336a14 to 6d42b1c Compare September 28, 2026 03:53
@bolichen97

Copy link
Copy Markdown
Contributor Author

Update to the rerun note above: the pending CI and Build reruns were not issued. 6d42b1ce632f7055ab41e0dfbfc50d910e317d40 replaces 6336a14c1 (same parent 7ed9efba97) and adds slashCommands, which sends no session key, to the surface test. Every workflow restarts on the new head.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 28, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=b3ae33085696 coalesce each domain into one contiguous spread: rebutted (out of this PR's goal)

This PR's frozen Not-a-goal excludes "Renaming, reordering or reshaping any api member", and its scope contract freezes the api key enumeration order.
The interleaved segments (telemetry at four positions, and others) exist only to reproduce that order byte-for-byte; ApiClient.refactor.surface.test.ts pins it.
Coalescing would change Object.keys(api), which is a behavior change. Whether any consumer depends on the order is exactly what a structural refactor should not decide on its own.
Once the split has landed, a separate PR can drop the order pin and coalesce the spreads, with that change as its stated goal and a maintainer's sign-off.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Sep 28, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rerunning the Opus 5 Review lane once on a356a41e46ee99ca90f4a269aec02621628fe84b. Its job reached a verdict but could not post it, because the Actions installation's API rate limit was exhausted during this morning's runner backlog:

Opus 5 Review produced a verdict for a356a41 but could not publish it, so this run's verdict is not in the slot. Cause of the failed comment read: reading this PR's comments to find this lane's slot exited 1 and reported: gh: API rate limit exceeded for installation.

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 withheld-verdict-…-r36383529237-a1 artifact. gh run rerun 36383529237 --failed runs it once.

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.
@bolichen97
bolichen97 force-pushed the refactor/f01-api-client-domain-split branch from a356a41 to c8a2472 Compare September 28, 2026 07:12
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased onto main at 631f8e6dc0638148e1b73e0ac1ec99188b7f33d8 so CI runs with #14641, the main fix for test_mcp_tool_titles[kirocrew-dashboard]. No content changed: git range-diff 082d00f4a..a356a41e4 631f8e6dc..c8a2472ef reports both commits as =. Still two commits, with authorship unchanged. This push replaces the Opus lane rerun mentioned above.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 28, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rerunning Pod Boot Canary (Windows) once on c8a2472efd83aaf212dd64cd725c03ff39c5e37f. It failed at pod down, after pod up, list, status and token had all succeeded:

test/test_pod_windows_boot.py::test_a_real_pod_boots_under_task_scheduler_and_leaves_nothing_behind - AssertionError: pod down failed: pod: stopping pod KiroCrew failed: pod 'KiroCrew': [WinError 32] The process cannot access the file because it is being used by another process: 'C:\kcpb944769\env\kcboot31b378.KiroCrew.cmd'

That is a Windows file-in-use race while tearing down a real pod. This PR changes no Python or pod code.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 28, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=5f326b774481 collapse the interleaved segments and the API_KEY_ORDER pin in a follow-up: rebutted for this PR (out of goal); agreed as a separate follow-up

This is the same class as span=b3ae33085696 on 6d42b1c. This PR's frozen Not-a-goal excludes "Renaming, reordering or reshaping any api member", and its scope freezes the api key enumeration order.
The segments exist only to reproduce that order, and ApiClient.refactor.surface.test.ts pins it, so a key two owners define, or a moved spread, fails instead of silently reordering.
Checking that no consumer iterates api, and then dropping the pin and coalescing the spreads, changes Object.keys(api). It belongs in its own PR with that goal, once the in-flight PRs that touch client.ts have drained.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Sep 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants