Adam Jeniski
5171059692
- Add eject button for tmux sessions (keeps tmux running, removes from Spiceflow) - Add refresh button to session settings for all providers - Improve terminal controls: larger buttons, more zoom levels (50-150%), copy selection, paste clipboard, enter key - Fix session navigation: properly reload when switching between sessions - Update tmux screen presets to larger dimensions (fullscreen 260x48, desktop 120x48, landscape 80x24) - Add testing documentation to CLAUDE.md - Refactor E2E tests to use API-based cleanup Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
191 lines
5.1 KiB
Markdown
191 lines
5.1 KiB
Markdown
# CLAUDE.md
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
./script/dev # Start backend + frontend
|
|
./script/test # Run E2E tests
|
|
```
|
|
|
|
### Backend
|
|
|
|
```bash
|
|
cd server
|
|
clj -M:dev # Start REPL with dev tools
|
|
clj -M:run # Start server (production mode)
|
|
clj -M:test # Run unit tests
|
|
```
|
|
|
|
**REPL commands:**
|
|
```clojure
|
|
(go) ; Start server + file watcher
|
|
(reset) ; Reload code
|
|
(stop) ; Stop server
|
|
```
|
|
|
|
### Frontend
|
|
|
|
```bash
|
|
cd client
|
|
npm install
|
|
npm run dev # Dev server
|
|
npm run build # Production build
|
|
npm run check # TypeScript check
|
|
```
|
|
|
|
### E2E Tests
|
|
|
|
```bash
|
|
cd e2e
|
|
npm test
|
|
npm run test:headed # Visible browser
|
|
npm run test:ui # Interactive explorer
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Backend
|
|
|
|
```
|
|
server/src/spiceflow/
|
|
├── core.clj # Entry point
|
|
├── config.clj # Settings from config.edn
|
|
├── db/
|
|
│ ├── protocol.clj # DataStore interface
|
|
│ ├── sqlite.clj # SQLite implementation
|
|
│ └── memory.clj # In-memory (tests)
|
|
├── adapters/
|
|
│ ├── protocol.clj # AgentAdapter interface
|
|
│ ├── claude.clj # Claude Code CLI
|
|
│ ├── opencode.clj # OpenCode CLI
|
|
│ └── tmux.clj # Terminal multiplexer
|
|
├── api/
|
|
│ ├── routes.clj # HTTP endpoints
|
|
│ └── websocket.clj # Real-time streaming
|
|
└── session/
|
|
└── manager.clj # Session lifecycle
|
|
```
|
|
|
|
### Frontend
|
|
|
|
```
|
|
client/src/
|
|
├── routes/ # SvelteKit file-based routing
|
|
│ ├── +layout.svelte
|
|
│ ├── +page.svelte # Home (session list)
|
|
│ └── session/[id]/+page.svelte
|
|
├── lib/
|
|
│ ├── api.ts # HTTP + WebSocket client
|
|
│ ├── stores/sessions.ts
|
|
│ └── components/
|
|
└── app.css # Tailwind
|
|
```
|
|
|
|
### Protocols
|
|
|
|
Database and CLI adapters use protocols for swappability:
|
|
|
|
```clojure
|
|
(defprotocol DataStore
|
|
(get-sessions [this])
|
|
(save-message [this msg]))
|
|
|
|
(defprotocol AgentAdapter
|
|
(spawn-session [this session])
|
|
(send-message [this session msg]))
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
| Endpoint | Method | Description |
|
|
|----------|--------|-------------|
|
|
| `/api/health` | GET | Health check |
|
|
| `/api/sessions` | GET | List sessions |
|
|
| `/api/sessions` | POST | Create session |
|
|
| `/api/sessions/:id` | GET | Get session with messages |
|
|
| `/api/sessions/:id` | PATCH | Update session |
|
|
| `/api/sessions/:id` | DELETE | Delete session |
|
|
| `/api/sessions/:id/send` | POST | Send message |
|
|
| `/api/sessions/:id/permission` | POST | Handle permission |
|
|
| `/api/sessions/:id/terminal` | GET | Get tmux content |
|
|
| `/api/sessions/:id/terminal/input` | POST | Send tmux input |
|
|
| `/api/ws` | WebSocket | Event streaming |
|
|
|
|
## Configuration
|
|
|
|
Environment variables or `server/resources/config.edn`:
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `SPICEFLOW_PORT` | 3000 | Server port |
|
|
| `SPICEFLOW_HOST` | 0.0.0.0 | Server host |
|
|
| `SPICEFLOW_DB` | spiceflow.db | SQLite path |
|
|
| `CLAUDE_SESSIONS_DIR` | ~/.claude/projects | Claude sessions |
|
|
| `OPENCODE_CMD` | opencode | OpenCode binary |
|
|
|
|
## Testing Changes
|
|
|
|
Always test changes before considering them complete. Choose the appropriate testing method:
|
|
|
|
### 1. E2E Tests (Playwright)
|
|
For UI changes, user flows, and integration between frontend/backend:
|
|
```bash
|
|
cd e2e && npm test # Run all E2E tests
|
|
cd e2e && npm run test:headed # Visible browser for debugging
|
|
cd e2e && npm test -- -g "test name" # Run specific test
|
|
```
|
|
|
|
### 2. Unit Tests (Clojure)
|
|
For backend logic, pure functions, and isolated components:
|
|
```bash
|
|
cd server && clj -M:test # Run all unit tests
|
|
```
|
|
|
|
### 3. REPL Testing
|
|
For quick one-off validation of Clojure code during development:
|
|
```clojure
|
|
;; In REPL (clj -M:dev, then (go))
|
|
(require '[spiceflow.some-ns :as ns])
|
|
(ns/some-function arg1 arg2) ; Test function directly
|
|
```
|
|
|
|
### 4. Manual API Testing
|
|
For testing HTTP endpoints directly:
|
|
```bash
|
|
# Health check
|
|
curl http://localhost:3000/api/health
|
|
|
|
# List sessions
|
|
curl http://localhost:3000/api/sessions
|
|
|
|
# Create session
|
|
curl -X POST http://localhost:3000/api/sessions \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"provider": "claude"}'
|
|
|
|
# Get session
|
|
curl http://localhost:3000/api/sessions/:id
|
|
```
|
|
|
|
### When to Use Each
|
|
| Change Type | Recommended Testing |
|
|
|-------------|---------------------|
|
|
| UI component | E2E tests |
|
|
| API endpoint | Manual API + unit tests |
|
|
| Business logic | Unit tests + REPL |
|
|
| User flow | E2E tests |
|
|
| Bug fix | Add regression test + manual verify |
|
|
|
|
## Subdirectory CLAUDE.md Files
|
|
|
|
Each directory has specific details:
|
|
- `server/` - REPL workflow, Mount lifecycle
|
|
- `server/src/spiceflow/db/` - Schema, queries
|
|
- `server/src/spiceflow/adapters/` - Adding adapters
|
|
- `server/src/spiceflow/api/` - HTTP handlers, WebSocket
|
|
- `server/src/spiceflow/session/` - Session state
|
|
- `client/` - SvelteKit, PWA
|
|
- `client/src/lib/` - API client, stores
|
|
- `client/src/routes/` - Pages, routing
|
|
- `e2e/` - E2E tests
|