moving

docs/ux-refactor/gap-cards/S03-command-center.md

@@ -0,0 +1,182 @@
+# Gap Card — S03 · Command Center (Ctrl+K)
+
+> Execution model is the LOCKED **in-place incremental refactor** of `apps/web` + targeted
+> backend extensions. Mockup (`Waggle_OS_Handoff_Assets/screen_03_win_k_command_center.png`) is
+> DIRECTIONAL only; PRD §12.3 acceptance criteria win. Every claim below is grounded in a real file.
+
+---
+
+## 1. Screen & purpose
+
+The universal command layer — opens from anywhere with Ctrl+K / Cmd+K — for **search, launch,
+create, run, navigate, and extend** across every major object type. PRD §12.3 (lines 449-482),
+blueprint screen 3 (`_blueprint_extracted.txt:284-290, 633, 679`). It is the product's "primary
+interaction" per blueprint line 19 ("Primary interaction: Ctrl+K") and the IA spine item #3
+(PRD line 19). Goal: "No user needs to know where a feature lives to use it" (PRD line 482).
+
+The mockup shows a centered modal titled "What do you want to do?" with: a search input
+("Search anything…"), pill tabs (Show my tasks / Open … STM Strategy / Find market analysis /
+Summarize…), five category columns — **Launch · Create · Run · Navigate** plus a Search bucket —
+each listing object/action rows, a "Suggested for you" card strip (review reports, draft proposals),
+and a footer "Type a natural-language command…". A second "Open in new window" affordance is top-right.
+
+---
+
+## 2. Required states (PRD/Blueprint)
+
+PRD §12.3 functional requirements (lines 461-467):
+- Opens from anywhere via Ctrl+K / Cmd+K.
+- Searches across **workspaces, memory, artifacts, sessions, people, agents, skills, commands, connectors, MCPs**.
+- Category sections: **Search, Launch, Create, Run, Navigate, Extend**.
+- Supports **natural-language command input**.
+- Displays **recent and suggested** actions.
+- **Permission-gated actions show an approval prompt before execution.**
+- Reachable by both mouse and keyboard.
+
+PRD §12.3 states (lines 469-477) + blueprint (`:289-290`):
+Idle · Query active · Grouped results · No results · Permission prompt · Command success · Command failure.
+
+Acceptance (lines 479-482): every major object and action is reachable; no user needs to know where a feature lives.
+
+---
+
+## 3. Current state in repo
+
+**Disposition: `rework`** (keep the proven overlay shell + keyboard nav + adapter calls; restructure
+categories to Search/Launch/Create/Run/Navigate/Extend; add execute + permission-prompt + recent/suggested;
+back it with the net-new `/api/command/*` provider).
+
+- **`apps/web/src/components/os/overlays/GlobalSearch.tsx`** (362 lines) — the existing Ctrl+K/Cmd+K
+  overlay. Today it does **client-side federated search only** across 5 categories
+  (`SearchCategory = 'command' | 'workspace' | 'memory' | 'session' | 'skill'`, line 15):
+  - `command` = a **hardcoded static `COMMANDS` array** of 23 app ids (lines 40-64) that must be
+    hand-kept in sync with `appConfig` in `Desktop.tsx` (the file's own comment flags this drift as
+    "the cause of FR #13", lines 33-39).
+  - `workspace`/`session`/`skill` pre-fetched on open via `adapter.getWorkspaces()`,
+    `adapter.getSessions(ws.id)` (first 5 ws × 3 sessions, lines 98-127), `adapter.getSkills()` (lines 129-138).
+  - `memory` = debounced (300 ms, min 2 chars) server call `adapter.searchMemory(query, globalScope?'global')`
+    (lines 142-168) — the **only** server-backed category.
+  - Matching is client-side `fuzzyMatch` (`lib/fuzzy-match`, line 11/177-187); keyboard nav (↑/↓/Enter/Esc),
+    selection clamp, scroll-into-view all already work (lines 224-239).
+  - There is **no execute path** — every Enter calls `onNavigate(category, id)` (lines 231-235, 320),
+    i.e. it only *opens a window*. No Create/Run/Extend, no recent, no suggested, no permission prompt.
+- **`Desktop.tsx` wiring** — `<GlobalSearch open onClose onNavigate={handleSearchNavigate} />` (`:464`),
+  toggled by `ov.toggleGlobalSearch` (Ctrl/Cmd+K via `useKeyboardShortcuts`, `:207`) and the StatusBar
+  search button (`:424`). `handleSearchNavigate` (`Desktop.tsx:217-225`) handles only `command`→`wm.openApp`,
+  `workspace`→`selectWorkspace`+`openChatForWorkspace`, `memory`→`openApp('memory')`. **No `session`/`skill`
+  navigation, no execute.**
+- **`apps/web/src/components/os/overlays/KeyboardShortcutsHelp.tsx`** (92 lines) — static cheat-sheet
+  modal (`shortcuts` array, lines 9-32). Lists "⌘K → Global Search" (line 21). **Disposition `keep`** —
+  it is the separate `Cmd+?` help overlay, not the command center; only update its label if Ctrl+K is
+  rebranded "Command Center".
+- **`adapter.executeCommand(command, workspaceId)`** (`lib/adapter.ts:1345-1350`) → `POST /api/commands/execute`
+  (note **plural** `commands`). Runs **slash commands only** (`/catchup`, `/status`, `/memory`, `/skills`);
+  workflow/spawn commands return "not available" (`packages/server/src/local/routes/commands.ts:1-87`).
+  Exists but is **not** the generic palette execute.
+- **`adapter.searchSessions`** (`adapter.ts:424-427`), `adapter.searchMemory` (`:476-487`) exist and are
+  reusable as federation inputs. `lib/suggested-actions.ts` is **chat-message-scoped** (extracts follow-up
+  chips from the last assistant message) — NOT command-palette suggestions; do not reuse for §12.3 "suggested".
+
+---
+
+## 4. Frontend work
+
+**Rework `GlobalSearch.tsx` → `CommandCenter.tsx`** (rename or keep filename; founder-directional).
+Reuse 100% of the modal chrome, framer-motion animation, debounce, keyboard-nav, selection/scroll logic.
+
+Concrete changes:
+- **Expand `SearchCategory`** to the PRD §12.3 verbs: add `'create'`, `'run'`, `'navigate'`, `'extend'`
+  alongside `'search'` (today's `command/workspace/memory/session/skill` become **Search/Navigate** result
+  feeds). Category headers + ordering (`CATEGORY_LABELS`/`CATEGORY_ORDER`, lines 67-75) extend accordingly —
+  this matches the mockup's Launch/Create/Run/Navigate columns.
+- **Replace client federation with a server provider.** Swap the multi-call client logic (lines 91-168)
+  for a single debounced `adapter.commandSearch(q, { scope })` → `GET /api/command/search?q=` (net-new
+  adapter method on `lib/adapter.ts`, the one contract surface). Keep the existing per-category calls only
+  as offline/fallback. Eliminates the hardcoded `COMMANDS`-vs-`appConfig` drift (FR #13).
+- **Add an execute path.** New `onExecute(commandId|nlInput)` → `adapter.commandExecute()` →
+  `POST /api/command/execute`. On Enter for a Run/Create/Extend item (vs Navigate items which keep calling
+  `onNavigate`). Render the §12.3 **permission prompt** state inline before executing gated actions
+  (reuse the approvals pattern — `useChat().pendingApproval`/`approveAction` and `ApprovalRequest` type,
+  `lib/types.ts`), plus **command success / command failure** toasts (`hooks/use-toast`).
+- **Recent + Suggested.** On idle (empty query), render two strips matching the mockup: "Recent" from
+  `adapter.commandRecent()` → `GET /api/command/recent`, and "Suggested for you" from
+  `adapter.commandSuggestions()` → `GET /api/command/suggestions`.
+- **Natural-language input** (PRD line 464): when the query doesn't match a structured result, surface a
+  "Run as command: '<query>'" row that posts the raw string to execute.
+- **New adapter methods** (4): `commandSearch`, `commandExecute`, `commandRecent`, `commandSuggestions`.
+- **State**: keep local `query/selected/sections`; add `recent`, `suggested`, `pendingPermission`,
+  `executing` states. Props: extend `GlobalSearchProps` (line 27) with `onExecute` and a workspace-id
+  for execute scoping. New optional hook `useCommandCenter()` (wraps the 4 adapter calls + debounce) is the
+  clean home for the provider, mirroring the existing domain-hook pattern.
+
+---
+
+## 5. Backend work (PRD §16.3)
+
+All four are MISSING from the sidecar (grep-confirmed in `backend-routes.md:448-451`; `/api/command/*` =
+0 matches in `packages/server/src/local/routes/*.ts`). None needs a new data store — all federate over
+existing substrate, consistent with the in-place model.
+
+| PRD §16.3 endpoint | Status | Plan |
+|---|---|---|
+| `GET /api/command/search?q=` | **MISSING** | **NET-NEW** route file `packages/server/src/local/routes/command.ts`. Federates over existing reads: workspaces (`WorkspaceManager.list()`), memory (`MindDB` full-text, reuse `memory.ts` search), sessions (reuse `sessions.ts` `/sessions/search`), skills (`skills.ts`), connectors (`connectors.ts`), MCPs (from `capabilities/status` `mcpServers[]` + `@waggle/shared` `mcp-catalog.ts`), agents/personas (`personas.ts`+`agent-groups.ts`), and the app/command catalog (extract from a shared catalog to kill the `COMMANDS` drift). Substrate touched: read-only across `memory_frames`, sessions JSONL, install-audit/marketplace, workspace configs. **No `.mind` migration.** |
+| `POST /api/command/execute` | **PARTIAL** | EXTEND, do **not** duplicate. `POST /api/commands/execute` (plural, `commands.ts`) already runs slash commands with a real `CommandContext`. Either (a) add a singular `/api/command/execute` alias that broadens the context to also dispatch Navigate/Create/Run/Extend intents (open app, create object, fleet-spawn, install), or (b) widen the existing plural route. Reuses `commandRegistry.execute`, `fleet/spawn`, `marketplace/install`. Substrate: same as the underlying action; add an **install-audit** write for gated executes (`InstallAuditStore.record`, `core/install-audit.ts`). **No migration.** |
+| `GET /api/command/recent` | **MISSING** | **NET-NEW** (or derive client-side). Cheapest server path: record executed commands to `ai_interactions` / a small recents list and read back; or derive from session/event history (`events.ts`). Substrate: `ai_interactions` table (read) — no schema change required. |
+| `GET /api/command/suggestions` | **MISSING** | **NET-NEW**. Reuse the **workspace-state next-actions** seed: `deriveNextActions` in `packages/server/src/local/workspace-state.ts:182-218` + `buildWorkspaceNowBlock` (`workspace-context.ts`) give cross-workspace suggestion candidates; `skills.ts` `/skills/suggestions` is the skill-domain analog to fold in. Substrate: read-only over memory/awareness/cron. **No migration.** |
+
+Permission gating: the execute route should run gated actions through the existing approval/SecurityGate
+path so the FE permission-prompt state has a real backend (reuse `approval.ts` + marketplace SecurityGate).
+
+---
+
+## 6. Shared types needed (PRD §15 vs lib/types.ts)
+
+PRD §15 defines no dedicated Command type, but the palette needs a result/command union. Add to
+`apps/web/src/lib/types.ts` (and mirror server-side in the route):
+- `CommandResult { id; kind: 'search'|'launch'|'create'|'run'|'navigate'|'extend'; objectType: 'workspace'|'memory'|'artifact'|'session'|'person'|'agent'|'skill'|'connector'|'mcp'|'command'|'app'; title; subtitle?; icon?; score; requiresApproval?: boolean; payload? }` — supersedes the local `SearchResult` interface (`GlobalSearch.tsx:17-25`).
+- `CommandExecuteRequest`/`CommandExecuteResult` (success/failure + optional permission descriptor).
+- Reuse existing `ApprovalRequest` (`lib/types.ts`) for the permission-prompt state rather than inventing a new one.
+- The `objectType` union overlaps PRD §15.2's missing unions (`ArtifactKind`, `AgentType`) and the absent
+  Artifact entity (substrate-types §e) — Artifact/Agent results are blocked until those screens land (see §7).
+
+---
+
+## 7. Dependencies (screens/phases first)
+
+- **PRD Sprint 3 = Command Center** (PRD lines 1321-1326: indexed search provider, result groups,
+  command execution, recent/suggested) — this card IS Sprint 3. Depends on **Sprint 1 (Shell + Ctrl+K**,
+  blueprint `:582`) being the home of the command provider.
+- **Search breadth is gated by other screens' substrate.** "artifacts" and "agents/people" facets need:
+  Artifacts (S05, PRD §16.6 — entirely net-new, substrate-types §e: no Artifact entity exists) and
+  Agents (S09, PRD §16.7 — sidecar agent CRUD MISSING). Ship Command Center with the **available** facets
+  (workspaces/memory/sessions/skills/commands/connectors/MCPs) and add artifact/agent facets when those
+  screens land. Do not block the whole screen on them.
+- Execute's Create/Run/Extend intents lean on existing fleet-spawn / marketplace-install / cron — already present.
+
+---
+
+## 8. Effort
+
+**L.** The FE overlay is largely reusable (shell, keyboard nav, debounce all done — that caps it below XL),
+but the work spans: 4 net-new/extended backend routes federating across ~8 substrates, an execute +
+permission-prompt path with audit writes, recent/suggested providers, a shared `CommandResult` type, and
+killing the `COMMANDS`/`appConfig` drift — full-stack across multiple existing route files.
+
+---
+
+## 9. Open questions
+
+1. **Route naming:** add singular `/api/command/*` (PRD-literal) as the new surface, or rename the existing
+   plural `/api/commands/execute`? Plural is already referenced by `adapter.executeCommand` + `commands.ts`.
+   Recommend: new singular `command.ts` + alias execute to the existing registry to avoid a breaking rename.
+2. **"Open in new window"** affordance in the mockup (top-right) — is the Command Center expected to also
+   open as a persistent windowed app (an `AppId`), or is it modal-only? Affects whether it needs an
+   `appConfig`/dock entry vs staying an overlay.
+3. **Suggested/recent scope:** cross-workspace blended, or scoped to the active workspace? PRD says
+   "recent and suggested" without scope; `deriveNextActions` is per-workspace today.
+4. **Natural-language commands** (PRD line 464): heuristic intent-parse (cheap, deterministic) vs an LLM
+   round-trip? The existing `commands.ts` is registry-keyed; NL needs an intent resolver — confirm budget.
+5. **Permission prompt reuse:** is the chat approvals pipeline (`approval.ts` + `useChat.pendingApproval`)
+   the intended mechanism for palette-initiated gated actions, or a lighter inline confirm?
+6. The `COMMANDS`-vs-`appConfig` drift (FR #13) — confirm the shared app-catalog refactor is in-scope here
+   vs a separate cleanup (it is the right place to consolidate `AppId` and retire stale `AppView`).