omigamedev
d484f61b29
- docs/plan.md: Master roadmap with phases and priorities - docs/milestones/01-13: Detailed specs for each feature - Updated CLAUDE.md with plan references and build commands Milestones cover: - Phase 1: Temporal versioning, auto-capture, context injection, codebase indexing - Phase 2: Daily journal, content ingestion, graph visualization, import/export - Phase 3: Multi-graph, smart retrieval, TUI dashboard, browser extension, shell completions
268 lines
12 KiB
Markdown
268 lines
12 KiB
Markdown
# Milestone 11: TUI Dashboard
|
|
|
|
## Overview
|
|
|
|
Interactive terminal user interface for browsing, searching, and managing the knowledge graph without leaving the terminal.
|
|
|
|
## Motivation
|
|
|
|
- CLI commands require knowing what to type
|
|
- Visual browsing aids discovery
|
|
- Power users prefer staying in terminal
|
|
- Real-time feedback on graph state
|
|
|
|
## Features
|
|
|
|
### 11.1 Main Dashboard
|
|
|
|
```bash
|
|
# Launch interactive TUI
|
|
cortex tui
|
|
cortex ui # Alias
|
|
```
|
|
|
|
Layout:
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ CORTEX Graph: work│
|
|
├────────────────────┬────────────────────────────────────────────┤
|
|
│ 📚 Recent (5) │ 🔍 Search: ________________________ │
|
|
│ ├─ Auth flow... │ │
|
|
│ ├─ API design... │ ┌─────────────────────────────────────┐ │
|
|
│ └─ DB schema... │ │ Auth flow design │ │
|
|
│ │ │ ───────────────────── │ │
|
|
│ 📋 Tasks (3) │ │ OAuth2 PKCE flow for SPA │ │
|
|
│ ├─ Fix login bug │ │ │ │
|
|
│ └─ Update docs │ │ Tags: auth, security, oauth │ │
|
|
│ │ │ Status: active │ │
|
|
│ 🔗 Components (8) │ │ │ │
|
|
│ ├─ UserService │ │ ── Connections ── │ │
|
|
│ └─ AuthService │ │ → implements: OAuth2 spec │ │
|
|
│ │ │ → contains: Token refresh logic │ │
|
|
│ 🎯 Decisions (4) │ └─────────────────────────────────────┘ │
|
|
│ └─ Use JWT... │ │
|
|
├────────────────────┴────────────────────────────────────────────┤
|
|
│ [/]Search [n]New [e]Edit [d]Delete [l]Link [q]Quit │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 11.2 Navigation
|
|
|
|
- Arrow keys / vim keys (hjkl) to navigate
|
|
- Enter to select/expand
|
|
- Tab to switch panels
|
|
- `/` to search
|
|
- `?` for help
|
|
|
|
### 11.3 Quick Actions
|
|
|
|
| Key | Action |
|
|
|-----|--------|
|
|
| `n` | New node |
|
|
| `e` | Edit selected |
|
|
| `d` | Delete selected |
|
|
| `l` | Link to another node |
|
|
| `t` | Add tags |
|
|
| `s` | Change status |
|
|
| `/` | Search |
|
|
| `g` | Graph view (ASCII) |
|
|
| `q` | Quit |
|
|
|
|
### 11.4 Search Mode
|
|
|
|
Real-time search as you type:
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ 🔍 Search: auth_ │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ 1. [component] AuthService (0.95) │
|
|
│ 2. [decision] Use JWT tokens (0.87) │
|
|
│ 3. [memory] Auth flow design (0.82) │
|
|
│ 4. [task] Fix auth bug (0.75) │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 11.5 Graph View Mode
|
|
|
|
ASCII visualization of connections:
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Graph View: AuthService │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌──────────────┐ │
|
|
│ depends_on │ UserService │ │
|
|
│ ┌───────►│ │ │
|
|
│ │ └──────────────┘ │
|
|
│ ┌────────┴─────┐ │
|
|
│ │ AuthService │ │
|
|
│ │ │──────────┐ │
|
|
│ └──────────────┘ │ implements │
|
|
│ │ ▼ │
|
|
│ │ ┌──────────────┐ │
|
|
│ contains│ │ OAuth2 spec │ │
|
|
│ ▼ └──────────────┘ │
|
|
│ ┌──────────────┐ │
|
|
│ │Token refresh │ │
|
|
│ └──────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 11.6 Edit Mode
|
|
|
|
Inline editing with validation:
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Edit: AuthService │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ Title: [AuthService ] │
|
|
│ Kind: [component ▼] │
|
|
│ Status: [active ▼] │
|
|
│ Tags: [backend, auth, service ] │
|
|
│ │
|
|
│ Content: │
|
|
│ ┌─────────────────────────────────────────────────────────┐ │
|
|
│ │ Handles all authentication operations including: │ │
|
|
│ │ - Login/logout │ │
|
|
│ │ - Token management │ │
|
|
│ │ - Session handling │ │
|
|
│ └─────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ [Tab]Next field [Ctrl+S]Save [Esc]Cancel │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Implementation
|
|
|
|
### Technology Choice
|
|
|
|
Use **Ink** (React for CLI) or **blessed-contrib**:
|
|
|
|
```typescript
|
|
// Using Ink
|
|
import React from 'react';
|
|
import { render, Box, Text, useInput } from 'ink';
|
|
import { useState, useEffect } from 'react';
|
|
|
|
const Dashboard: React.FC = () => {
|
|
const [nodes, setNodes] = useState<Node[]>([]);
|
|
const [selected, setSelected] = useState(0);
|
|
const [mode, setMode] = useState<'browse' | 'search' | 'edit'>('browse');
|
|
|
|
useInput((input, key) => {
|
|
if (key.upArrow || input === 'k') setSelected(s => Math.max(0, s - 1));
|
|
if (key.downArrow || input === 'j') setSelected(s => Math.min(nodes.length - 1, s + 1));
|
|
if (input === '/') setMode('search');
|
|
if (input === 'q') process.exit(0);
|
|
});
|
|
|
|
return (
|
|
<Box flexDirection="column">
|
|
<Header graph={activeGraph} />
|
|
<Box flexDirection="row">
|
|
<Sidebar nodes={nodes} selected={selected} />
|
|
<DetailPanel node={nodes[selected]} />
|
|
</Box>
|
|
<StatusBar mode={mode} />
|
|
</Box>
|
|
);
|
|
};
|
|
```
|
|
|
|
### Component Structure
|
|
|
|
```
|
|
src/tui/
|
|
├── index.tsx # Entry point
|
|
├── components/
|
|
│ ├── Dashboard.tsx # Main layout
|
|
│ ├── Sidebar.tsx # Node list
|
|
│ ├── DetailPanel.tsx # Node details
|
|
│ ├── SearchBox.tsx # Search input
|
|
│ ├── GraphView.tsx # ASCII graph
|
|
│ ├── EditForm.tsx # Edit mode
|
|
│ └── StatusBar.tsx # Bottom bar
|
|
├── hooks/
|
|
│ ├── useNodes.ts # Node data fetching
|
|
│ ├── useSearch.ts # Search state
|
|
│ └── useKeyboard.ts # Key handling
|
|
└── utils/
|
|
└── ascii-graph.ts # ASCII graph renderer
|
|
```
|
|
|
|
### ASCII Graph Renderer
|
|
|
|
```typescript
|
|
// src/tui/utils/ascii-graph.ts
|
|
export function renderAsciiGraph(rootId: string, depth: number = 3): string[] {
|
|
const lines: string[] = [];
|
|
const node = getNode(rootId);
|
|
if (!node) return lines;
|
|
|
|
const connections = getConnections(rootId);
|
|
|
|
lines.push(`┌${'─'.repeat(node.title.length + 4)}┐`);
|
|
lines.push(`│ ${node.title} │`);
|
|
lines.push(`└${'─'.repeat(node.title.length + 4)}┘`);
|
|
|
|
for (const conn of connections.outgoing) {
|
|
lines.push(` │ ${conn.type}`);
|
|
lines.push(` ▼`);
|
|
lines.push(`┌${'─'.repeat(conn.node.title.length + 4)}┐`);
|
|
lines.push(`│ ${conn.node.title} │`);
|
|
lines.push(`└${'─'.repeat(conn.node.title.length + 4)}┘`);
|
|
}
|
|
|
|
return lines;
|
|
}
|
|
```
|
|
|
|
## CLI Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `cortex tui` | Launch interactive TUI |
|
|
| `cortex ui` | Alias |
|
|
|
|
## Testing
|
|
|
|
- [ ] Navigation works smoothly
|
|
- [ ] Search updates in real-time
|
|
- [ ] Edit mode saves correctly
|
|
- [ ] Graph view renders correctly
|
|
- [ ] Handles large node lists
|
|
- [ ] Vim keybindings work
|
|
- [ ] Color scheme readable
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] Can browse all nodes visually
|
|
- [ ] Search is responsive (<100ms)
|
|
- [ ] Edit/create nodes without leaving TUI
|
|
- [ ] Graph view shows connections
|
|
- [ ] Keyboard-only navigation
|
|
- [ ] Works in standard terminals
|
|
|
|
## Estimated Effort
|
|
|
|
- Ink/blessed setup: 3 hours
|
|
- Sidebar component: 3 hours
|
|
- Detail panel: 3 hours
|
|
- Search component: 3 hours
|
|
- Edit form: 4 hours
|
|
- Graph view: 4 hours
|
|
- Polish/testing: 4 hours
|
|
- **Total: ~24 hours**
|
|
|
|
## Dependencies
|
|
|
|
- `ink` or `blessed-contrib`
|
|
- `react` (for Ink)
|
|
|
|
## References
|
|
|
|
- [Ink - React for CLI](https://github.com/vadimdemedes/ink)
|
|
- [blessed-contrib](https://github.com/yaronn/blessed-contrib)
|
|
- [Lazygit TUI](https://github.com/jesseduffield/lazygit) for inspiration
|