12 KiB
12 KiB
id, title, status, wave, depends_on, plan, spec
| id | title | status | wave | depends_on | plan | spec |
|---|---|---|---|---|---|---|
| 04-workspace-cookie-port-scope-frontend | Port-scope workspace cookies (frontend) | done | 1 | plan.md | ../../specs/auth/requirements/fix-multi-instance-cookie-isolation.md |
Task 04: Port-scope workspace cookies (frontend)
Acceptance
apps/web/lib/routing/route-bootstrap.tsgains:scopedCookieName(name: string, port?: string): string— appends_<port>when non-empty; the port defaults to the API origin port fromgetBackendConfig().apiBaseUrl(NOTwindow.location.port, which mismatches in split-origin dev where the SPA runs on the web port and the API on the backend port with no Vite proxy).readScopedCookie(name: string, port?: string)— reads the scoped name first, falls back to the legacy name. The explicitportparameter keeps both helpers pure and unit-testable without jsdom Location stubbing (a same-module function cannot bevi.spyOn-stubbed for its own callers — the ES-module lexical binding trap).readActiveWorkspaceCookieand the office legacy read (readCookie(LEGACY_OFFICE_ACTIVE_WORKSPACE_COOKIE)) use them with the API-origin default.
apps/web/components/app-sidebar/app-sidebar-workspace-navigation.tswriteWorkspaceCookiewrites the scoped name (same API-origin port) for bothkandev-active-workspaceandoffice-active-workspace.- Server-component and async client readers that hold a CookieStore read the
scoped name first, legacy fallback via
readScopedCookieStoreValue(cookieStore, name, port?):apps/web/app/page.tsx,apps/web/app/office/layout.tsx,apps/web/app/settings/layout.tsx, andapps/web/app/office/lib/get-active-workspace.ts(the actual helper location; notapps/web/lib/get-active-workspace.ts). apps/web/src/office-routes.tsxis a synchronous client effect (lines ~224-229) and keeps the document-cookie-basedreadScopedCookie(name, port?)helpers instead of an asyncreadCookies()refactor; both helper families sharescopedCookieNameso the derivation is identical. This split is explicit: CookieStore readers use the store helper, the sync office effect usesreadScopedCookie.- Office precedence unification (task-03 contract, frontend half):
app/office/layout.tsxandapp/office/lib/get-active-workspace.tscurrently resolve the office cookie only, whileoffice-routes.tsxcarries a 5-argument resolver with route precedence. Extract ONE canonical frontend resolver with an explicit input contract:resolveOfficeWorkspaceId(items, { routeWorkspaceId, generalWorkspaceId, officeWorkspaceId, settingsWorkspaceId })and a single documented precedence — route → general (when it names an office workspace) → office cookie → settings → first — every candidate validated against the office set. Wrappers pass their route override where one exists:getActiveWorkspaceId(urlWorkspaceId?)passes it asrouteWorkspaceId(its URL-first behavior is already pinned byget-active-workspace.test.ts:58-78; a valid/office?workspaceId=O2must beat the cookies); only the no-argument caller (app/office/layout.tsx) passesnull. The server layout cannot read query params and hydrates from cookies at first paint, so convergence with a route override is client-eventual: theoffice-routes.tsxbootstrap effect re-resolves route-first and hydrates the store. The convergence regression asserts the OfficeRoutes bootstrap (route O2 + cookies naming O1 → hydratedactiveId= O2), not the server layout — the layout's first-paint value is cookie-driven by design and converges client-side. - Structural guard test (vitest,
fs-based): (a) negative — no workspace-cookiecookieStore.get(...)/readCookie(...)call exists in the five files outside the helpers, with arguments rejected both as literals ("kandev-active-workspace","office-active-workspace") and as the exported constants (ACTIVE_WORKSPACE_COOKIE,LEGACY_OFFICE_ACTIVE_WORKSPACE_COOKIE—app/page.tsxandapp/settings/layout.tsxread via the constant today); (b) positive — each of the four CookieStore readers referencesreadScopedCookieStoreValueandoffice-routes.tsxreferencesreadScopedCookie, so a reader that simply drops its lookup fails the guard. The helper unit tests cover scoped-first + legacy fallback. - Unit tests, failing pre-change:
- Reader tests (beyond the guard, which only proves symbol reference):
app/office/lib/get-active-workspace.test.tsis extended with scoped-first (office-active-workspace_8443), legacy fallback, route-override, and general-vs-office precedence cases;src/office-routes.test.tsis updated in place (it currently tests the 5-argument resolver including route precedence). Classification: the resolver precedence cases (route > general-if-office > office > settings > first, distinct-valid-O1/O2) are invariant — the currentoffice-routes.tsxresolver already implements this precedence and the existingoffice-routes.test.tsalready covers it; extraction must keep them green pre-change. The failing-before coverage targets the scoped/legacy cookie reads (scopedCookieName,readScopedCookie,readScopedCookieStoreValue), the server-reader wrapper wiring (get-active-workspace+ the office layout reading both scoped cookie families), and the client convergence path (route override hydratingactiveId— the old office-cookie-only reads are what is actually wrong). route-bootstrap.test.ts:scopedCookieName("kandev-active-workspace", "8443")=kandev-active-workspace_8443;readScopedCookiereturns the_8443value when present and falls back to the legacy name otherwise.readScopedCookieStoreValuereturns the scopedcookieStoreentry first, legacy fallback. A split-origin regression asserts the default port comes from the API base URL (:38429) and not fromwindow.location.port(:37429) — stubgetBackendConfig(separate module, mockable) or pass the port explicitly.- Structural guard test (vitest,
fs-based): fails on any workspace-cookie lookup in the five files outside the helpers — literal names or the exported constants (ACTIVE_WORKSPACE_COOKIE,LEGACY_OFFICE_ACTIVE_WORKSPACE_COOKIE) — (negative), and on a file that does not reference its mandated helper — the four CookieStore readers must importreadScopedCookieStoreValue,office-routes.tsxmust importreadScopedCookie(positive). - No-port frontend regression: an API origin with no explicit port (or
port="") yields no suffix —scopedCookieName("kandev-active-workspace", "")stays unprefixed and the write path emits the plain name (the spec's single-instance/default-port promise, frontend half; backend session no-port is task 02). - Client convergence: two classes. (invariant) OfficeRoutes
bootstrap with a route override naming O2 and cookies naming O1 hydrates
activeId= O2 — the current route-first resolver already wins, so this guards the precedence, not the change. (failing-before) a no-route / invalid-route case with distinct non-first scoped fixtures: route override absent, scoped general cookie naming O1 (and no valid unprefixed cookie) → the bootstrap hydrates O1 (pre-change the reader never sees the scoped name → settings/first, so the assertion fails pre-change). - OfficeRoutes scoped-office bootstrap regression (failing-before,
the scoped office-family read — the convergence case above covers
the general family only): OfficeRoutes bootstrap with scoped general
kandev-active-workspace_8443naming a kanban workspace, scoped officeoffice-active-workspace_8443naming non-first O2, no legacy office cookie, no route/settings candidate → hydratedactiveId= O2. Pre-change the effect's directreadCookie(LEGACY_OFFICE_ACTIVE_ WORKSPACE_COOKIE)reads only the unprefixed name (absent) → settings/ first; fails pre-change. Implement via a focused bootstrap test or a narrow exported cookie-candidate reader used by the effect. - Per-file guard argument assertions: the structural guard also checks
each CookieStore reader passes the correct cookie name —
app/page.tsxandapp/settings/layout.tsxmust referenceACTIVE_WORKSPACE_COOKIE(not the legacy office constant) through the helper, andapp/office/layout.tsx+get-active-workspace.tsmust pass BOTHACTIVE_WORKSPACE_COOKIEandLEGACY_OFFICE_ACTIVE_WORKSPACE_COOKIEin the documented order (general first);office-routes.tsxmust referencereadScopedCookiewith the legacy office constant for its office candidate (defense-in-depth against the wrong family/name). Text/AST assertions in the guard test, or focused reader tests; a wrong constant or a dropped candidate fails the suite. app-sidebar-workspace-navigation.test.tsandapp-sidebar-workspace-picker.test.tsx(the picker drives the samerememberWorkspaceSelectionpath and today asserts unprefixed writes):rememberWorkspaceSelectionwriteskandev-active-workspace_8443=...(andoffice-active-workspace_8443=...for office workspaces) and does not write the unprefixed names (negative assertion — the legacy read fallback stays, but no new legacy writes); the picker fixtures and captured cookie-name assertions are updated to the API-port suffix.
- Reader tests (beyond the guard, which only proves symbol reference):
Verification
cd apps && pnpm --filter @kandev/web test -- lib/routing/route-bootstrap.test.ts components/app-sidebar/app-sidebar-workspace-navigation.test.ts components/app-sidebar/app-sidebar-workspace-picker.test.tsx app/office/lib/get-active-workspace.test.ts src/office-routes.test.ts
cd apps/web && pnpm run typecheck
Files likely touched
apps/web/lib/routing/route-bootstrap.tsapps/web/lib/routing/route-bootstrap.test.tsapps/web/components/app-sidebar/app-sidebar-workspace-navigation.tsapps/web/components/app-sidebar/app-sidebar-workspace-navigation.test.tsapps/web/components/app-sidebar/app-sidebar-workspace-picker.test.tsxapps/web/app/page.tsxapps/web/app/office/layout.tsxapps/web/app/settings/layout.tsxapps/web/app/office/lib/get-active-workspace.tsapps/web/app/office/lib/get-active-workspace.test.tsapps/web/src/office-routes.tsx(office bootstrap cookie reads)apps/web/src/office-routes.test.ts(resolver tests updated/moved in place)apps/web/lib/config.ts(only if the API-origin port needs a small accessor)
Dependencies
None (independent of the Go helper).
Parallelism
Parallel-safe with task-01 (disjoint tree/contract).
Inputs
- Spec:
What(workspace cookie scoping — API-origin port on both sides, legacy fallback),Scenarios(second, third, split-origin). - Plan:
Frontend. - Existing pattern:
writeWorkspaceCookieis the single client write choke point;readCookieis the single client read choke point;getBackendConfig()inapps/web/lib/config.tsalready resolves the API base URL (split-origin dev vs same-origin prod).
Risks
- Split-origin dev is the trap: any default not derived from the API base URL silently degrades to the legacy fallback. The split-origin regression test is the guard.
- Do not stub a same-module helper with
vi.spyOn— the ES-module lexical binding is not replaced for its own callers; tests pass theportparameter explicitly instead. - Do not scope
kandev_localeorlayout:*reads (out of scope); keep the change limited to the workspace cookies. office-routes.tsxreads both cookies throughreadActiveWorkspaceCookie/readCookie; verify the office bootstrap uses the scoped variants.
Output contract
Report the scoped read/write behavior, changed files, exact commands and
results, blockers/risks, then mark this task done and update plan.md.