loki-mode 7.5.27 → 7.5.29

package/docs/MERGE-ROUTE-MAP.md

@@ -0,0 +1,139 @@
+# Purple Lab Into Dashboard: Route Map (Phase Merge-1)
+
+**Status:** Audit complete. Doc-only output for Phase Merge-1 of the v7.5.29+ true-integration arc.
+**Date:** 2026-05-23
+**Source:** `dashboard/server.py` (133 routes) and `web-app/server.py` (112 routes), audited from HEAD.
+
+This document is the source-of-truth route-collision analysis for the Purple Lab merge into Dashboard. It enumerates every route in both servers, identifies collisions, and defines the namespace strategy for Phases Merge-2 through Merge-7.
+
+## Top-Level Summary
+
+| Metric | Value |
+|---|---|
+| Dashboard routes -- main `app` decorators | 133 |
+| Dashboard routes -- `api_v2_router` (mounted at `/api/v2/*` via `include_router`) | 24 |
+| Dashboard routes -- total | **157** |
+| Dashboard `/api/*` routes | 135 |
+| Purple Lab routes (total) | 112 |
+| Purple Lab `/api/*` routes | 100 |
+| Purple Lab routers (`APIRouter` / `include_router`) | 0 |
+| Exact collisions (method + path) | **3** |
+| Path-only collisions | **3** |
+| `/api/*` collisions (any method) | **0** |
+| `/api/v2/*` collisions vs Purple Lab | **0** (Purple Lab has no `/api/v2/*` routes) |
+| Surviving uncollided Purple Lab routes | **109** |
+
+**Result:** The merge is structurally clean. Only 3 infrastructure paths collide; all 100 of Purple Lab's `/api/*` routes have distinct paths from Dashboard's 135 `/api/*` routes. The `api_v2_router` (24 routes at `/api/v2/tenants`, `/api/v2/runs`, `/api/v2/api-keys`, `/api/v2/policies`, `/api/v2/audit`) is enterprise multi-tenant surface that Purple Lab does not currently expose.
+
+## The 3 Collisions
+
+| Method | Path | Dashboard purpose | Purple Lab purpose | Resolution |
+|---|---|---|---|---|
+| `GET` | `/health` | Dashboard health check | Purple Lab health check | Single `/health` on Dashboard wins. Lab's becomes `/lab/health`. |
+| `GET` | `/{full_path:path}` | Dashboard SPA catch-all (serves `dashboard/static/index.html`) | Purple Lab SPA catch-all (serves `web-app/dist/index.html`) | Dashboard catch-all wins at root. Lab's becomes `/lab/{full_path:path}` -- triggered only inside the mount. |
+| `WS` | `/ws` | Dashboard WebSocket bus | Purple Lab WebSocket bus | Dashboard `/ws` wins. Lab's becomes `/lab/ws`. Long term: unify into a single bus (Phase Merge-5). |
+
+All three collisions resolve automatically when Lab's FastAPI app is mounted at `/lab` via Starlette `app.mount("/lab", purple_lab_app)`. No code dedup needed in Merge-1 -- the mount provides path isolation.
+
+## Namespace Strategy
+
+Single rule: **Purple Lab's entire FastAPI app mounts under `/lab/`**. No route renames inside the Lab app itself -- the mount handles prefixing.
+
+- Lab route `/api/sessions/{id}/chat` becomes externally visible as `/lab/api/sessions/{id}/chat`.
+- Lab static asset `/assets/index-BN52-GQT.js` becomes `/lab/assets/index-BN52-GQT.js`.
+- Lab WebSocket `/ws` becomes `/lab/ws`.
+
+The Vite build (Phase Merge-3) is rebuilt with `base: '/lab/'` so the bundled JS naturally calls `/lab/api/*` and the HTML loads `/lab/assets/*`. No runtime base-href shimming needed.
+
+## Web-App Route Inventory (by category)
+
+| Category | Count | Sample paths |
+|---|---|---|
+| `/api/sessions/*` | 61 | `/api/sessions/{session_id}/chat/{task_id}/stream`, `/api/sessions/{session_id}/checkpoints` |
+| `/api/session/*` | 18 | `/api/session/start`, `/api/session/quick-start`, `/api/session/status` |
+| `/api/deploy/*` | 6 | `/api/deploy/{provider}` |
+| `/api/magic/*` | 5 | `/api/magic/components`, `/api/magic/generate` |
+| `/api/auth/*` | 5 | (auth endpoints) |
+| `/api/teams/*` | 4 | (team management) |
+| `/api/secrets/*` | 3 | (secrets management) |
+| `/api/templates/*` | 2 | `/api/templates`, `/api/templates/{filename}` |
+| `/api/provider/*` | 2 | `/api/provider/current`, `/api/provider/set` |
+| `/api/audit-log` | 1 | (audit log endpoint) |
+| `/proxy/{session_id}` | 1 | (legacy proxy) |
+| `/ws/*` | 2 | `/ws`, `/ws/terminal` |
+| `/health` | 1 | (health check) |
+| `/{full_path:path}` | 1 | (SPA catch-all) |
+| **Total** | **112** | |
+
+## Dashboard Route Inventory (by category, top 20)
+
+| Category | Count |
+|---|---|
+| `/api/memory/*` | 14 |
+| `/api/registry/*` | 10 |
+| `/api/learning/*` | 9 |
+| `/api/migration/*` | 8 |
+| `/api/council/*` | 8 |
+| `/api/tasks/*` | 6 |
+| `/api/enterprise/*` | 6 |
+| `/api/projects/*` | 5 |
+| `/api/control/*` | 5 |
+| `/api/checklist/*` | 5 |
+| `/api/notifications/*` | 4 |
+| `/api/agents/*` | 4 |
+| `/api/managed/*` | 3 |
+| `/api/github/*` | 3 |
+| `/api/focus/*` | 3 |
+| `/api/checkpoints/*` | 3 |
+| (etc., 89 more under /api/) | -- |
+| **Total** | **133** |
+
+## Semantic Overlap (Candidates for Dedup in Phase Merge-5)
+
+After path-suffix analysis, only one path-suffix is genuinely shared between the two servers:
+
+- `github/status` -- appears as `/api/github/status` (Dashboard) and inside Lab's session endpoints. Not a collision (different paths), but functional overlap worth investigation in Phase Merge-5.
+
+The bigger semantic overlap is at the conceptual level:
+
+| Concept | Dashboard endpoint | Purple Lab endpoint | Merge-5 decision needed |
+|---|---|---|---|
+| Session lifecycle (start/stop/status) | `/api/control/*` (5 routes) | `/api/session/*` (18 routes) + `/api/sessions/{id}/*` (61 routes) | Likely: Lab keeps richer session CRUD; Dashboard's `/api/control/*` becomes thin wrappers calling Lab's. Or: unify on Lab's surface and retire Dashboard's. Decide in Merge-5. |
+| Memory access | `/api/memory/*` (14 routes) | `/api/session/{id}/memory` (1 route) | Dashboard owns the rich surface; Lab's becomes a thin wrapper. |
+| Checkpoints | `/api/checkpoints/*` (3 routes) | `/api/sessions/{id}/checkpoints` (2 routes) | Dashboard owns the global view; Lab's per-session view consumes Dashboard's. |
+| Council / quality | `/api/council/*` (8) + `/api/quality-score/*` (2) | -- | Dashboard-only. Lab needs to surface this via UI, not duplicate endpoints. |
+| Provider routing | `/api/provider/*` (?) | `/api/provider/current`, `/api/provider/set` | Likely same routes already; verify in Merge-2. |
+
+None of these block the mount in Merge-4. They become refactor targets in Merge-5.
+
+## Phase Dependencies (Confirmed by This Audit)
+
+- **Merge-2** (state/business-logic dedup audit): Doable in parallel with Merge-3. Operates on `.loki/state/` and Python modules, not routes.
+- **Merge-3** (Vite rebuild with `base: '/lab/'`): Single-file config change in `web-app/vite.config.ts` + `npm run build`. No route changes needed because the mount handles prefixing.
+- **Merge-4** (FastAPI mount): The 3 infrastructure collisions resolve naturally via mount path isolation. No route renames inside `web-app/server.py`.
+- **Merge-5** (deep dedup): Only required for the 4 conceptual overlaps above. Each becomes a separate sub-task.
+- **Merge-6** (sidebar entry): Pure dashboard-UI work, no backend route changes.
+- **Merge-7** (deprecate `loki web` standalone): Keep `loki web` working for 2 minor versions per user-safety Rule 0. Standalone uvicorn entrypoint is preserved; only `loki dashboard` gains the mount.
+
+## NOT Decided In This Phase
+
+1. **Cookie / session-token namespace.** If Lab and Dashboard both set cookies at root path, mount may cause conflicts. Audit needed in Merge-2.
+2. **CORS middleware.** Lab has CORS middleware at line 119 of `web-app/server.py`. After mount, this becomes redundant (same origin). Remove in Merge-4.
+3. **Lifespan / startup events.** Lab's startup hooks (if any) must compose with Dashboard's. Audit in Merge-4.
+4. **Auth headers.** If Lab requires its own auth token and Dashboard requires another, the mount may double-auth or break. Audit in Merge-2.
+
+These are not blockers for Merge-1 sign-off; they are explicit followups.
+
+## Cleanup
+
+Audit artifacts in `/tmp/loki-merge-audit/` may be removed:
+```bash
+rm -rf /tmp/loki-merge-audit
+```
+
+## Honest Acknowledgements
+
+- The "0 /api/* collisions" finding holds for the route-table inspection only. Two routes with distinct paths can still share a backing function or `.loki/` file, and that semantic overlap is what Phase Merge-2 must catalog.
+- Initial audit used `grep -nE '^@app\.(get|post|put|delete|patch|websocket)\(' ...` which missed `include_router` mounts. Followup audit found Dashboard's `api_v2_router` at `dashboard/api_v2.py` (24 routes, prefix `/api/v2`) and confirmed Purple Lab has zero `APIRouter` / `include_router` registrations. The summary table reflects the corrected total of 157 Dashboard routes.
+- `app.add_api_route(...)` is also a dynamic registration pattern. `grep -n "add_api_route" web-app/server.py dashboard/server.py` returns nothing -- both servers use decorator-style registration exclusively.
+- No fixture-based runtime collision test was performed. Phase Merge-4 must add a route-table dump test that runs the mounted app and asserts the surviving route set against this doc's expected output.

package/docs/MERGE3-PLAN.md

@@ -0,0 +1,119 @@
+# Phase Merge-3 Implementation Plan: Vite Rebuild with `/lab/` Base
+
+**Status:** Architect-approved 2026-05-23. Dev fleet implements per this plan.
+**Owner:** Phase Merge-3 of the v7.5.29+ Purple-Lab-into-Dashboard true-integration arc.
+**Predecessors:** `docs/MERGE-ROUTE-MAP.md` (Merge-1), `docs/MERGE-DEDUP-MAP.md` (Merge-2).
+
+## Binding Decisions
+
+1. **Vite `base: '/lab/'`.** Single config change applies in dev + build.
+2. **API base via `import.meta.env.BASE_URL`.** No `/lab/` hardcoded in TypeScript -- the env var resolves to `/lab/` at build time and `/` in tests.
+3. **`loki web` standalone server ALSO mounts its app under `/lab/`.** Same bundle, same routing model as the merged Dashboard. Root `/` redirects to `/lab/`. Rule 0 preserved by URL shift only.
+4. **No duplicated dist artifacts.** Single `web-app/dist/` shipped to npm + Docker. No `base: '/'` second build.
+
+## File Diffs (concrete)
+
+### 1. `web-app/vite.config.ts`
+```diff
+ export default defineConfig({
+   plugins: [react()],
++  base: '/lab/',
+   resolve: { alias: { '@': path.resolve(__dirname, './src') } },
+   server: {
+     port: 5173,
+     proxy: {
+-      '/api':   { target: 'http://localhost:57375', changeOrigin: true },
+-      '/proxy': { target: 'http://localhost:57375', changeOrigin: true, ws: true },
+-      '/ws':    { target: 'ws://localhost:57375',   ws: true },
++      '/lab/api':   { target: 'http://localhost:57375', changeOrigin: true },
++      '/lab/proxy': { target: 'http://localhost:57375', changeOrigin: true, ws: true },
++      '/lab/ws':    { target: 'ws://localhost:57375',   ws: true },
+     },
+   },
+ })
+```
+
+### 2. `web-app/src/api/client.ts` (line 3 + line 7 area)
+```diff
+-const API_BASE = (import.meta as any).env?.VITE_API_BASE
+-  || `${window.location.origin}/api`;
++const BASE = (import.meta as any).env?.BASE_URL || '/';
++const API_BASE = (import.meta as any).env?.VITE_API_BASE
++  || `${window.location.origin}${BASE}api`;
++const WS_BASE = `${window.location.protocol === 'https:' ? 'wss:' : 'ws:'}//${window.location.host}${BASE}ws`;
+```
+Then export `WS_BASE` and route any other websocket constructor through it.
+
+### 3. `web-app/src/pages/MagicPage.tsx` (4 hardcoded fetches at lines 43, 65, 86, 106)
+Convert each `fetch('/api/magic/...')` to use a shared base. Cleanest fix: import the client API base:
+```diff
+-      const res = await fetch('/api/magic/components');
++      const res = await fetch(`${import.meta.env.BASE_URL}api/magic/components`);
+```
+Apply to all 4 sites. Or extract a `magicApi` helper in `web-app/src/api/client.ts`.
+
+### 4. `web-app/src/components/TerminalEmulator.tsx` (line 49)
+```diff
+-    const wsUrl = `${protocol}//${window.location.host}/ws/terminal/${sessionId}`;
++    const wsUrl = `${protocol}//${window.location.host}${import.meta.env.BASE_URL}ws/terminal/${sessionId}`;
+```
+
+### 5. `web-app/server.py` -- standalone mount (added in Merge-4; staged here)
+
+The architect's option 2: standalone server self-mounts at `/lab/`. The actual wiring lives in Merge-4, but Merge-3 needs to verify the URL flip works for `loki web`. For Merge-3 alone, we accept the standalone `loki web` URL changes to `http://127.0.0.1:57375/lab/`. Browser-open auto-redirect is added in Merge-4.
+
+### 6. `autonomy/loki` `cmd_web_start` browser-open URL (line ~3694)
+Change the `open` URL from `http://127.0.0.1:${PURPLE_LAB_DEFAULT_PORT}/` to `http://127.0.0.1:${PURPLE_LAB_DEFAULT_PORT}/lab/`.
+
+## Release Pipeline Wiring
+
+### 7. Root `package.json` `prepublishOnly` (line ~106)
+Append `&& cd ../web-app && npm ci && npm run build && test -f dist/index.html` after the existing dashboard-ui build.
+
+### 8. `Dockerfile`
+Add `COPY` for web-app build artifacts + server files. Mirror the `dashboard/` COPY pattern. (Merge-4 owns the actual import; Merge-3 ensures files are in the image.)
+
+### 9. `scripts/local-ci.sh`
+Add a check between existing steps:
+```bash
+run_check "web-app build produces /lab/-prefixed assets" \
+  '(cd web-app && npm ci --silent && npm run build) && grep -q "/lab/assets/" web-app/dist/index.html'
+```
+
+## Tests (Merge-3 acceptance)
+
+| ID | Test | Type |
+|---|---|---|
+| T1 | `grep -q '/lab/assets/' web-app/dist/index.html` after `npm run build` | bash, local-ci |
+| T2 | `grep -q '/lab/api' web-app/dist/assets/index-*.js` (runtime base baked in) | bash, local-ci |
+| T3 | `loki web --no-open; curl -sL http://127.0.0.1:57375/lab/ \| grep -q '<div id="root">'` | bash |
+| T4 | `curl -s http://127.0.0.1:57375/lab/assets/index-*.js` returns JS not 404 | bash |
+| T5 | Playwright: visit `http://127.0.0.1:57375/lab/`, no console 404s, screenshot HomePage baseline | Playwright |
+| T6 | (Post-Merge-4) visit `http://127.0.0.1:57374/lab/`, screenshot diff vs T5 pixel-identical | Playwright |
+| T7 | `curl -s http://127.0.0.1:57374/` returns Dashboard root unchanged | bash |
+| T8 | `npm pack --dry-run \| grep web-app/dist/index.html` succeeds | local-ci |
+
+## Risks (with mitigations)
+
+1. **Hardcoded `/api/` strings drift back over time.** Mitigation: add local-ci grep guard:
+   `! grep -rn "['\"]/api\|['\"]/ws" web-app/src/ | grep -v "BASE_URL\|external"`
+
+2. **`/vite.svg` favicon 404 under `/lab/`.** Mitigation: verify `web-app/public/vite.svg` exists; if not, remove the `<link rel="icon" href="/vite.svg">` line from `web-app/index.html`.
+
+3. **Dev workflow break (`http://localhost:5173/` returns 404).** Mitigation: document `http://localhost:5173/lab/` in `web-app/README.md`; optionally add Vite middleware to redirect `/` -> `/lab/` in dev.
+
+4. **Cookies set at root path.** Mitigation: Merge-2 audit confirmed no cookies (Bearer tokens only). Re-verify with curl post-build.
+
+5. **Stale dist in git.** Mitigation: local-ci T1/T2 catch it. Stronger: pre-push hook that runs `npm run build` if src is newer than dist (deferred to follow-up).
+
+## NOT Done In This Phase
+
+- Auto-spawn web-app subprocess from `loki dashboard` (Merge-4).
+- Sidebar entry in `dashboard/static/index.html` (Merge-6).
+- Deep state dedup (Merge-5).
+- Deprecation of `loki web` (Merge-7).
+- `vite-plugin-html` dev `/` -> `/lab/` redirect (nice-to-have, not blocking).
+
+## Acceptance Gate
+
+Merge-3 ships when: T1-T4 + T7 + T8 green, no `git status` noise outside the planned files, `loki web --no-open` serves the Lab UI at `/lab/` end-to-end with browser-side console clean (verified by Playwright T5).