groove-dev 0.17.7 → 0.18.0

package/docs/FILE-EDITOR-PLAN.md

@@ -1,253 +0,0 @@
-# File Editor — Implementation Plan
-
-## Context
-
-Power users want to watch and verify what agents are doing in real-time. A VS Code-style file editor embedded in the GROOVE GUI lets users browse project files, see agent changes as they happen, and make quick edits — all without leaving the dashboard.
-
-## Architecture
-
-```
-+------------------------------------------+
-| [EditorTabs: file1.js | file2.css | ...] |
-+----------+-------------------------------+
-| FileTree | CodeEditor (CodeMirror 6)     |
-| (240px)  | (flex: 1)                     |
-|          |                               |
-|          |  [file changed banner]        |
-|          |                               |
-+----------+-------------------------------+
-```
-
-**Editor library: CodeMirror 6** — modular (~200KB vs Monaco's ~3MB), has a native One Dark theme matching GROOVE's palette, supports programmatic content updates for live agent changes. No new daemon dependencies — file watching uses Node.js built-in `fs.watch`.
-
-## Files to Create
-
-| File | Purpose |
-|------|---------|
-| `packages/gui/src/views/FileEditor.jsx` | Main view — composes tree + tabs + editor |
-| `packages/gui/src/components/FileTree.jsx` | Expandable directory tree sidebar |
-| `packages/gui/src/components/EditorTabs.jsx` | Horizontal tab bar for open files |
-| `packages/gui/src/components/CodeEditor.jsx` | CodeMirror 6 wrapper |
-| `packages/daemon/src/filewatcher.js` | Per-file fs.watch + debounced WebSocket broadcast |
-
-## Files to Modify
-
-| File | Changes |
-|------|---------|
-| `packages/daemon/src/api.js` | Add `/api/files/tree`, `/api/files/read`, `/api/files/write` endpoints |
-| `packages/daemon/src/index.js` | Wire `FileWatcher`, handle `editor:watch`/`editor:unwatch` WS messages |
-| `packages/gui/src/stores/groove.js` | Add editor state + actions + `file:changed` WS handler |
-| `packages/gui/src/App.jsx` | Add "Editor" tab, import + render `<FileEditor />` |
-| `packages/gui/package.json` | Add CodeMirror 6 dependencies |
-
-## Build Order
-
-### Step 1: Backend — File API endpoints
-
-**File: `packages/daemon/src/api.js`**
-
-Add after the existing `// --- Directory Browser ---` section. Reuse the same path validation pattern from `/api/browse`.
-
-**`GET /api/files/tree?path=<relPath>`**
-Returns files AND directories for a given path. Response:
-```json
-{
-  "current": "src/components",
-  "parent": "src",
-  "entries": [
-    { "name": "subdir", "type": "dir", "path": "src/components/subdir", "hasChildren": true },
-    { "name": "App.jsx", "type": "file", "path": "src/components/App.jsx", "size": 4521, "language": "javascript" }
-  ]
-}
-```
-- Dirs first (sorted), then files (sorted)
-- Filter: no `.git`, `node_modules`, dotfiles
-- Language detected from extension via a simple map
-
-**`GET /api/files/read?path=<relPath>`**
-Returns file contents. Response:
-```json
-{ "path": "src/App.jsx", "content": "...", "size": 4521, "language": "javascript" }
-```
-- Reject files > 5MB
-- Detect binary (null bytes in first 8KB) → return `{ binary: true }`
-
-**`POST /api/files/write`**
-Saves file contents. Body: `{ path, content }`. Response: `{ ok: true, size: N }`
-- Same path validation
-- Audit log: `daemon.audit.log('file.write', { path })`
-
-**Language detection helper:**
-```javascript
-const LANG_MAP = {
-  js: 'javascript', jsx: 'javascript', mjs: 'javascript',
-  ts: 'typescript', tsx: 'typescript',
-  css: 'css', scss: 'css', html: 'html', json: 'json',
-  md: 'markdown', py: 'python', rs: 'rust', go: 'go',
-  sh: 'shell', yaml: 'yaml', yml: 'yaml', toml: 'toml',
-  sql: 'sql', xml: 'xml', java: 'java',
-};
-function detectLanguage(filename) {
-  const ext = filename.split('.').pop()?.toLowerCase();
-  return LANG_MAP[ext] || 'text';
-}
-```
-
-### Step 2: Backend — File Watcher
-
-**New file: `packages/daemon/src/filewatcher.js`**
-
-Lightweight class that watches individual files (only files the user has open in the editor):
-- `watch(relPath)` — start watching with `fs.watch`, debounce 300ms, broadcast `{ type: 'file:changed', path, timestamp }` via `daemon.broadcast()`
-- `unwatch(relPath)` — stop watching, clean up
-- `unwatchAll()` — cleanup on daemon shutdown
-
-**Wire in `packages/daemon/src/index.js`:**
-- Instantiate `this.fileWatcher = new FileWatcher(this)` in daemon constructor
-- In the WebSocket `connection` handler, add a `message` listener:
-  - `editor:watch` → `this.fileWatcher.watch(msg.path)`
-  - `editor:unwatch` → `this.fileWatcher.unwatch(msg.path)`
-- Call `this.fileWatcher.unwatchAll()` on daemon shutdown
-
-### Step 3: Dependencies — Install CodeMirror 6
-
-Add to `packages/gui/package.json`:
-```
-@codemirror/view, @codemirror/state, @codemirror/language,
-@codemirror/commands, @codemirror/search, @codemirror/autocomplete,
-@codemirror/lang-javascript, @codemirror/lang-css, @codemirror/lang-html,
-@codemirror/lang-json, @codemirror/lang-markdown, @codemirror/lang-python,
-@codemirror/theme-one-dark
-```
-
-Run `npm install` from project root.
-
-### Step 4: Zustand Store — Editor State
-
-**File: `packages/gui/src/stores/groove.js`**
-
-Add to initial state:
-```javascript
-editorFiles: {},         // { [path]: { content, originalContent, language, loadedAt } }
-editorActiveFile: null,  // currently visible file path
-editorOpenTabs: [],      // ordered array of open file paths
-editorTreeCache: {},     // { [dirPath]: entries[] } — cached tree data
-editorChangedFiles: {},  // { [path]: timestamp } — externally modified files
-```
-
-Add actions:
-- `openFile(path)` — fetch from `/api/files/read`, add to `editorFiles` + `editorOpenTabs`, set `editorActiveFile`, send `editor:watch` via WS
-- `closeFile(path)` — remove from tabs/files, send `editor:unwatch`, switch to next tab
-- `setActiveFile(path)` — switch active tab
-- `updateFileContent(path, content)` — on every editor keystroke (dirty = content !== originalContent)
-- `saveFile(path)` — POST to `/api/files/write`, reset originalContent
-- `reloadFile(path)` — re-fetch from server, clear changed notification
-- `dismissFileChange(path)` — clear from `editorChangedFiles`
-- `fetchTreeDir(path)` — fetch `/api/files/tree?path=...`, cache in `editorTreeCache`
-
-Add WS handler case:
-```javascript
-case 'file:changed':
-  set((s) => ({ editorChangedFiles: { ...s.editorChangedFiles, [msg.path]: msg.timestamp } }));
-  break;
-```
-
-### Step 5: FileTree Component
-
-**New file: `packages/gui/src/components/FileTree.jsx`**
-
-- Recursive expandable tree, lazy-loads children on directory expand
-- Click file → `openFile(path)`
-- Click directory → toggle expand, fetch children if not cached
-- Visual: 16px indent per level, `>` / `v` arrows for dirs
-- Active file highlighted with accent left border
-- File colors by extension (`.js` amber, `.css` blue, `.json` green, `.md` purple, etc.)
-- Search input at top for client-side filtering
-- Style: `var(--bg-chrome)` background, `var(--border)` separators, matching DirPicker patterns
-
-### Step 6: EditorTabs Component
-
-**New file: `packages/gui/src/components/EditorTabs.jsx`**
-
-- Horizontal scrollable row of open file tabs
-- Each tab: filename (tooltip = full path), close `x` button
-- Active tab: `border-bottom: 2px solid var(--accent)`, bright text
-- Dirty indicator: small amber dot next to filename when content !== originalContent
-- `overflow-x: auto` for many open files
-- Style: `var(--bg-chrome)` background, 32px height, matching header tab patterns from App.jsx
-
-### Step 7: CodeEditor Component (CodeMirror 6)
-
-**New file: `packages/gui/src/components/CodeEditor.jsx`**
-
-React wrapper around CodeMirror 6. Key details:
-
-- `useRef` for container div + EditorView instance
-- `useEffect` on mount: create EditorView with extensions (line numbers, bracket matching, search, auto-indent, one-dark theme, language support)
-- When `content` prop changes externally (file reload / different file selected): dispatch full content replacement via `view.dispatch()`
-- `onChange` callback on every transaction → `updateFileContent(path, newContent)` in store
-- Language switching: reconfigure compartment when language prop changes
-- Custom theme override: set editor bg to `var(--bg-base)` (#24282f) since One Dark default is `--bg-chrome` (#282c34)
-- Ctrl/Cmd+S handler → `saveFile(path)`
-- Cleanup on unmount: `view.destroy()`
-
-### Step 8: FileEditor View (Composition)
-
-**New file: `packages/gui/src/views/FileEditor.jsx`**
-
-Composes all pieces:
-```
-Container (flex column, height 100%)
-├── EditorTabs (flexShrink: 0)
-└── Content Row (flex row, flex: 1, overflow: hidden)
-    ├── FileTree (width: 240px, flexShrink: 0, border-right)
-    └── Editor Area (flex: 1, position: relative)
-        ├── External Change Banner (absolute top, z-index 10, amber)
-        │   "File modified externally" [Reload] [Dismiss]
-        └── CodeEditor (flex: 1)
-```
-
-Empty state when no file open: centered "Select a file from the tree" text.
-
-### Step 9: App.jsx Integration
-
-**File: `packages/gui/src/App.jsx`**
-
-1. Add to TABS: `{ id: 'editor', label: 'Editor' }` — position it second (after Agents)
-2. Import `FileEditor` from `'./views/FileEditor'`
-3. Add render: `{activeTab === 'editor' && <FileEditor />}`
-
-The detail panel (agent chat, journalist) continues to work alongside the editor.
-
-## Security
-
-All file endpoints reuse the path validation from `/api/browse`:
-- No absolute paths (`startsWith('/')`)
-- No traversal (`includes('..')`)
-- No null bytes (`includes('\0')`)
-- Must resolve within `daemon.projectDir`
-- 5MB size limit on read/write
-- Binary detection (null bytes in first 8KB)
-- Audit logging on writes
-
-## Verification
-
-1. `npm run build:gui` — should build clean with CodeMirror included
-2. `node --test packages/daemon/test/` — all 137 tests pass
-3. Start daemon (`groove start`), open GUI, click Editor tab
-4. File tree should show project structure
-5. Click a file → opens in CodeMirror with syntax highlighting
-6. Edit content → tab shows dirty dot
-7. Cmd+S → saves, dirty dot clears
-8. Spawn an agent that modifies an open file → amber banner appears "File modified externally"
-9. Click Reload → file content updates
-10. Open multiple files → tabs work, switching preserves state
-
-## Future Extensions (not in this build)
-
-- Diff view for external changes (`@codemirror/merge`)
-- Git status colors in file tree (modified/untracked)
-- File create/delete/rename via right-click context menu
-- Cmd+P fuzzy file finder
-- Search across files (grep-like panel)
-- Breadcrumb path bar above editor

package/docs/GUI_DESIGN_SPEC.md

@@ -1,402 +0,0 @@
-# Groove AI — GUI Design Specification
-### Terminal-Native Visual Control Plane
-
-> The GUI should feel like a terminal that happens to have graphics in it — not a website pretending to be a terminal.
-
----
-
-## Philosophy
-
-This is a TUI-meets-browser hybrid. It runs at `localhost:3141` and is designed to sit inside a terminal multiplexer pane (cmux) alongside real terminal sessions. It should look like it belongs there. No rounded corners on containers, no card shadows, no hover animations, no gradient backgrounds. Think: htop with a React Flow node graph in the center.
-
----
-
-## Color Palette
-
-Based on One Dark Pro. Every color has a purpose.
-
-### Backgrounds
-| Token | Hex | Usage |
-|---|---|---|
-| `--bg-base` | `#24282f` | Main content area / node graph background |
-| `--bg-chrome` | `#282c34` | Sidebar, header bar, panels |
-| `--bg-surface` | `#2c313a` | Buttons, input fields, card surfaces |
-| `--bg-hover` | `#333842` | Button/row hover state |
-| `--bg-active` | `#3a3f4b` | Active/selected button or tab |
-
-### Text
-| Token | Hex | Usage |
-|---|---|---|
-| `--text-primary` | `#abb2bf` | Default body text, labels |
-| `--text-bright` | `#e6e6e6` | Headings, active items, emphasis |
-| `--text-dim` | `#5c6370` | Secondary info, timestamps, hints |
-| `--text-muted` | `#3e4451` | Disabled text, decorative borders |
-
-### Accent / Status
-| Token | Hex | Usage |
-|---|---|---|
-| `--accent` | `#33afbc` | Brand accent — active nav item, selected node border, primary action |
-| `--green` | `#98c379` | Agent active, success states, healthy status |
-| `--amber` | `#e5c07b` | Agent idle, warning, pending approval |
-| `--red` | `#e06c75` | Agent blocked/error, kill actions, conflicts |
-| `--purple` | `#c678dd` | Journalist activity, context rotation events |
-| `--blue` | `#61afef` | Info badges, links, secondary accent |
-
----
-
-## Typography
-
-One font. Everywhere. No exceptions.
-
-```
-font-family: 'JetBrains Mono', 'SF Mono', 'Fira Code', 'Cascadia Code', Consolas, monospace;
-```
-
-| Element | Size | Weight | Color |
-|---|---|---|---|
-| Header bar title | 13px | 600 | `--text-bright` |
-| Nav buttons | 12px | 500 | `--text-primary` (inactive), `--text-bright` (active) |
-| Node labels | 12px | 600 | `--text-bright` |
-| Node metadata | 11px | 400 | `--text-dim` |
-| Panel headings | 11px | 600 | `--text-dim`, uppercase, letter-spacing 1.5px |
-| Panel body text | 12px | 400 | `--text-primary` |
-| Timestamps | 10px | 400 | `--text-dim` |
-| Status badges | 10px | 600 | Status color, uppercase |
-
----
-
-## Layout
-
-```
-┌──────────────────────────────────────────────────────┐
-│  HEADER BAR (--bg-chrome, 40px height)              │
-│  [logo]  [Agents] [Tokens] [Teams] [Permissions]    │
-├────────────────────────────────────┬─────────────────┤
-│                                    │                 │
-│         NODE GRAPH                 │   DETAIL PANEL  │
-│         (--bg-base)                │   (--bg-chrome) │
-│                                    │                 │
-│    React Flow canvas with          │   Context for   │
-│    agent nodes and edges           │   selected node │
-│                                    │                 │
-│                                    │                 │
-└────────────────────────────────────┴─────────────────┘
-```
-
-### Header Bar
-- Height: 40px
-- Background: `--bg-chrome`
-- Bottom border: 1px `--text-muted`
-- Logo: Groove infinity icon (16px), left side
-- Nav buttons: right-aligned, evenly spaced
-
-### Node Graph Area
-- Background: `--bg-base`
-- Takes remaining viewport width/height
-- Subtle dot grid pattern: `--text-muted` dots, 20px spacing, 1px size
-- No border, no padding — edge to edge
-
-### Detail Panel (right sidebar)
-- Width: 320px, collapsible
-- Background: `--bg-chrome`
-- Left border: 1px `--text-muted`
-- Shows detail for whatever is selected in the graph
-
----
-
-## Components
-
-### Nav Buttons (Header)
-
-The four main views: **Agents**, **Tokens**, **Teams**, **Permissions**
-
-```
-Inactive:
-  background: transparent
-  color: --text-primary
-  padding: 6px 14px
-  border: none
-
-Hover:
-  background: --bg-hover
-  color: --text-bright
-
-Active:
-  background: --bg-active
-  color: --text-bright
-  border-bottom: 2px --accent (or underline indicator)
-```
-
-No border-radius. These are terminal tabs, not web buttons.
-
-### Agent Nodes (React Flow)
-
-Each node represents one running agent.
-
-```
-┌─────────────────────────┐
-│ ● backend-1             │  ← status dot + agent name
-│ src/api/**              │  ← file scope
-│ claude-code · 45%       │  ← provider + context usage
-└─────────────────────────┘
-```
-
-| Property | Value |
-|---|---|
-| Background | `--bg-surface` |
-| Border | 1px `--text-muted` |
-| Border (selected) | 1px `--accent` |
-| Border-radius | 2px (barely rounded — terminal feel) |
-| Padding | 10px 12px |
-| Width | 200px |
-| Font | 12px for name, 11px for metadata |
-
-**Status dot** (6px circle, left of agent name):
-- `--green` = active
-- `--amber` = idle / waiting
-- `--red` = blocked / error
-- `--purple` = rotating context
-
-**Context usage bar** (optional, bottom of node):
-- Height: 2px
-- Background: `--text-muted`
-- Fill: `--green` (0-60%), `--amber` (60-80%), `--red` (80-100%)
-
-### Edges (connections between nodes)
-
-- Stroke: `--text-muted`
-- Stroke width: 1px
-- Style: straight or step (not bezier — too soft)
-- Animated dash when data is flowing (introduction events, journalist updates)
-
-### QC Supervisor Node (special)
-
-Same structure as agent node but:
-- Border: 1px `--purple`
-- Label prefix: `[QC]`
-- Always positioned at root/top of the tree
-
-### Status Badges
-
-Small inline badges for agent states.
-
-```
-background: rgba(color, 0.12)
-color: status color
-padding: 2px 6px
-font-size: 10px
-font-weight: 600
-text-transform: uppercase
-letter-spacing: 0.5px
-border-radius: 2px
-```
-
-Examples:
-- `ACTIVE` — green bg tint, green text
-- `IDLE` — amber bg tint, amber text
-- `BLOCKED` — red bg tint, red text
-- `ROTATING` — purple bg tint, purple text
-
-### Token Usage View
-
-Replaces the node graph when "Tokens" tab is active.
-
-```
-┌──────────────────────────────────┐
-│ TOKEN USAGE           this session│
-│                                  │
-│ Total          1,247,893         │
-│ Saved (routing)  412,500  (33%) │
-│ Saved (rotation) 289,100  (23%) │
-│                                  │
-│ AGENT BREAKDOWN                  │
-│ ─────────────────────────────── │
-│ backend-1      482,100   38.6%  │
-│ ████████████████░░░░░░          │
-│ frontend-1     391,200   31.3%  │
-│ ██████████████░░░░░░░░          │
-│ database-1     374,593   30.0%  │
-│ █████████████░░░░░░░░░          │
-└──────────────────────────────────┘
-```
-
-Bar charts use block characters or thin divs:
-- Fill: `--accent`
-- Track: `--text-muted`
-- Height: 3px
-
-Numbers right-aligned, monospace tabular. This should look like a terminal stats output, not a web dashboard.
-
-### Teams View
-
-List of saved team configurations.
-
-```
-┌──────────────────────────────────┐
-│ SAVED TEAMS                      │
-│                                  │
-│ > fullstack          4 agents    │
-│   backend, frontend, db, qc     │
-│   saved 2026-04-05               │
-│                                  │
-│ > api-only           2 agents    │
-│   backend, database              │
-│   saved 2026-04-04               │
-└──────────────────────────────────┘
-```
-
-- `>` prefix for each team (terminal-style list marker)
-- Selected team: `--text-bright` text, `--bg-hover` background
-- Load button: inline, right side, `--accent` text
-
-### Permissions / Approvals View
-
-Pending agent actions requiring human approval.
-
-```
-┌──────────────────────────────────┐
-│ PENDING APPROVALS        2       │
-│                                  │
-│ backend-1 wants to:              │
-│ Edit src/middleware/auth.js      │
-│ "Refactoring auth to use JWT"    │
-│ [APPROVE]  [REJECT]    2m ago   │
-│                                  │
-│ frontend-1 wants to:             │
-│ Create src/components/Modal.jsx  │
-│ "Adding confirmation dialog"     │
-│ [APPROVE]  [REJECT]    45s ago  │
-└──────────────────────────────────┘
-```
-
-Action buttons:
-```
-[APPROVE]:
-  background: rgba(--green, 0.12)
-  color: --green
-  border: 1px rgba(--green, 0.2)
-  padding: 4px 10px
-  font-size: 11px
-
-[REJECT]:
-  background: rgba(--red, 0.12)
-  color: --red
-  border: 1px rgba(--red, 0.2)
-  padding: 4px 10px
-  font-size: 11px
-```
-
----
-
-## Detail Panel (Right Sidebar)
-
-Shows context for selected agent node.
-
-```
-┌─────────────────────┐
-│ AGENT DETAIL        │
-│                     │
-│ backend-1           │
-│ Status: ACTIVE      │
-│ Provider: claude    │
-│ Context: 45%        │
-│ ████████░░░░░░░░░░ │
-│ Tokens: 482,100     │
-│ Scope:              │
-│   src/api/**        │
-│   src/middleware/**  │
-│ Spawned: 14:20      │
-│ Peers: frontend-1,  │
-│   database-1        │
-│                     │
-│ RECENT ACTIVITY     │
-│ ─────────────────  │
-│ 14:32 editing       │
-│   auth.js           │
-│ 14:28 introduced to │
-│   frontend-1        │
-│ 14:20 spawned       │
-└─────────────────────┘
-```
-
-- Section headers: `--text-dim`, 11px, uppercase, 1.5px letter-spacing
-- Dividers: single line of `─` chars or 1px `--text-muted` border
-- Key labels: `--text-dim`
-- Values: `--text-primary`
-- Agent name: `--text-bright`, 14px, 600 weight
-
----
-
-## Interaction States
-
-| State | Treatment |
-|---|---|
-| Default | `--bg-surface` background, `--text-primary` text |
-| Hover | `--bg-hover` background, `--text-bright` text |
-| Active/Selected | `--bg-active` background, `--text-bright` text |
-| Focused | 1px `--accent` outline (no glow, no shadow) |
-| Disabled | `--text-muted` text, no hover change |
-
-No transitions longer than 100ms. No easing curves. Instant or near-instant state changes — like a terminal.
-
----
-
-## What NOT To Do
-
-- No border-radius > 2px anywhere
-- No box-shadow anywhere
-- No gradients anywhere
-- No opacity transitions on hover
-- No font-size larger than 14px (exception: token counter numbers)
-- No sans-serif fonts
-- No rounded buttons
-- No icons — use text labels and ASCII where possible (`●`, `>`, `─`, `█`, `░`)
-- No loading spinners — use text like `loading...` or `syncing...`
-- No toast notifications — use inline status text
-- No modals — use the detail panel or inline expansion
-
----
-
-## CSS Variables (copy-paste ready)
-
-```css
-:root {
-  /* Backgrounds */
-  --bg-base: #24282f;
-  --bg-chrome: #282c34;
-  --bg-surface: #2c313a;
-  --bg-hover: #333842;
-  --bg-active: #3a3f4b;
-
-  /* Text */
-  --text-primary: #abb2bf;
-  --text-bright: #e6e6e6;
-  --text-dim: #5c6370;
-  --text-muted: #3e4451;
-
-  /* Status */
-  --accent: #33afbc;
-  --green: #98c379;
-  --amber: #e5c07b;
-  --red: #e06c75;
-  --purple: #c678dd;
-  --blue: #61afef;
-
-  /* Typography */
-  --font: 'JetBrains Mono', 'SF Mono', 'Fira Code', 'Cascadia Code', Consolas, monospace;
-}
-```
-
----
-
-## File Reference
-
-- Logo (full): `/groove-logo.png` (800x254, cyan on transparent)
-- Logo (icon): `/favicon.png` (500x500, infinity symbol)
-- Brand accent: `#33afbc`
-- Site: https://grooveai.dev
-- Docs: https://docs.grooveai.dev
-
----
-
-*This spec is the single source of truth for GUI visual design. If it's not in here, don't add it. If it contradicts a mockup, this document wins.*