toga-ai 1.0.404 → 1.0.405

package/knowledge/sessions/2026-07-21-deployment-logout-guard-apeterson.md

@@ -0,0 +1,58 @@
+---
+type: session
+slug: deployment-logout-guard
+title: Force-logout-on-deployment guard for toga25-supply
+author: apeterson
+repos: [toga25-supply]
+framework: "2.0"
+client: shared
+status: active
+created: 2026-07-21
+updated: 2026-07-21
+---
+
+# Session: deployment-logout-guard
+**Date:** 2026-07-21
+**Project/Repo:** toga25-supply (2.0)
+**Task:** Port toga2-commerce's force-logout-on-core-parameter-change mechanism into toga25-supply so a large deployment forces all users to sign out and fully reset session/localStorage/React Query cache — with a smooth UX.
+
+---
+
+## What WORKED
+<!-- Include specific file paths and evidence -->
+- Reviewed the reference mechanism in `toga2-commerce/src/contexts/AuthContext.tsx`: polls Core parameter `META_LAST_REFRESH_DATETIME` via `/core-parameters`, stores the login-time value as a baseline, and on any later differing fetch calls `logout()` + hard-redirects to `/`.
+- Created `toga25-supply/src/hooks/useDeploymentGuard.tsx` — a `useQuery` (enabled while authenticated, `staleTime:0`, `refetchOnWindowFocus:true`, `refetchInterval` 5min) reading `apiGet("/core-parameters", { fields:["value"], key:"META_LAST_REFRESH_DATETIME" })` → `response.data.coreParameters` (array-or-object tolerant). Baseline stored in localStorage key `deployment-version`; first observation sets it (no logout), a later mismatch triggers reset. Exports render-nothing `<DeploymentGuard />`.
+- Smooth UX: on mismatch shows a non-dismissing info toast ("A new version is available — signing you out briefly…") and waits 2.5s before calling `logout()`.
+- Wired `<DeploymentGuard />` into `toga25-supply/src/App.tsx` inside the `AuthProvider`/`ToasterProvider`/`ThemeProvider` tree (both `useAuth` and `useToaster` resolve).
+- Confirmed the existing `AuthContext.logout()` (lines 80–90) already does `performLogout()` + `clearUser()` + `localStorage.clear()` + `queryClient.clear()` — so the entire localStorage (tokens, `zu-user`, `zu-hostname`, persisted `supply-chain-query-cache`, and the `deployment-version` baseline) is wiped. User confirmed this full-clear behavior is what they want.
+- `npx tsc --noEmit` — no errors in the changed files (`useDeploymentGuard.tsx`, `App.tsx`).
+- Captured to team KB: new doc `knowledge/2.0/apps/toga25-supply/features/force-logout-on-deployment.md`, PUSHED to `_main`.
+
+## What did NOT work — DO NOT RETRY THESE
+<!-- Exact failure reasons — do not vague-ify -->
+- (none — no failed approaches this session.)
+
+## Not tried yet (candidates for next session)
+- Live verification against a real API response that `response.data.coreParameters[0].value` is populated for this client, and that the `key` shorthand option (vs a `where` clause) is honored by this environment's `/core-parameters` endpoint. If `key` is not supported, switch the fetch to `where: { and: [{ "CoreParameters.key": { "=": "META_LAST_REFRESH_DATETIME" } }] }`.
+- End-to-end manual test: log in, bump `META_LAST_REFRESH_DATETIME` server-side, confirm the toast appears and the user is signed out + everything reset, and that re-login re-establishes the baseline without a logout loop.
+
+## Current file state
+| File | Status | Notes |
+|------|--------|-------|
+| `toga25-supply/src/hooks/useDeploymentGuard.tsx` | Created | Deployment watch hook + `DeploymentGuard` component. Complete, type-checks clean. |
+| `toga25-supply/src/App.tsx` | Modified | Added import of `DeploymentGuard` and rendered `<DeploymentGuard />` above `<AppRouter />` inside the provider tree. |
+| `toga-tech/knowledge/2.0/apps/toga25-supply/features/force-logout-on-deployment.md` | Created (pushed) | Feature doc, owner `apeterson`, pushed to `_main`. |
+
+## Decisions made
+- **Reuse the centralized `logout()` rather than a bespoke reset path.** It already clears all localStorage + React Query cache + redirects, matching the "reset everything" intent. Rejected: writing a separate partial cache-clear (wouldn't reset session as required).
+- **Do NOT preserve the baseline across logout (simpler than commerce).** Because `logout()` clears the baseline and hard-reloads, the next login's first fetch re-establishes it and the mismatch check is skipped when no baseline exists → no logout loop. Rejected commerce's write-new-value-before-logout dance as unnecessary here.
+- **2.5s toast delay before logout** for a smooth, explained sign-out instead of an abrupt kick. Rejected instant logout (jarring) and history-patching navigation refetch from commerce (fragile) in favor of `refetchOnWindowFocus` + 5min interval.
+
+## Blockers
+none
+
+## Exact next step
+> Manually verify against a live/beta API: log in to toga25-supply, confirm the first `/core-parameters` fetch populates `response.data.coreParameters[].value`; if the `key` shorthand returns nothing, change the `fetchDeploymentVersion` options in `src/hooks/useDeploymentGuard.tsx` to a `where` clause on `CoreParameters.key`.
+
+---
+_Saved by /session-save on 2026-07-21_

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.404",
+  "version": "1.0.405",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",