feat: first attempt at a gui for managing sessions
This commit is contained in:
Joe Fleming
140
PLAN.md
Normal file
140
PLAN.md
Normal file
@@ -0,0 +1,140 @@
|
||||
# Session Mover TUI - Project Plan
|
||||
|
||||
## Overview
|
||||
A Python Textual TUI application to visually manage OpenCode sessions (move/copy between projects and workspaces) without writing SQL.
|
||||
|
||||
## Database Schema (opencode.db)
|
||||
|
||||
### Core Tables
|
||||
- **session**: `id, project_id, workspace_id, parent_id, slug, directory, title, version, time_created, time_updated, time_archived`
|
||||
- **project**: `id, worktree, name, vcs`
|
||||
- **workspace**: `id, project_id, branch, type, name, directory`
|
||||
|
||||
### Related Data (cascade on session delete)
|
||||
- **message** → **part**: Conversation content
|
||||
- **todo**: Session todos
|
||||
- **session_share**: Share links
|
||||
|
||||
## Goals
|
||||
|
||||
1. **Visual browsing** - Tree view of Projects → Workspaces → Sessions
|
||||
2. **Easy session movement** - Drag-and-drop or keyboard-driven moving between projects
|
||||
3. **Batch operations** - Select multiple sessions and move them together
|
||||
4. **Safety** - Confirmation dialogs, preview SQL, automatic backup
|
||||
5. **Discoverability** - Hotkeys always visible, clear status indicators
|
||||
|
||||
## Key Features
|
||||
|
||||
### Display
|
||||
- Split pane: Left = Projects/Workspaces tree, Right = Sessions table
|
||||
- Sessions table columns: Title, Project, Workspace, Messages, Created, Archived status
|
||||
- Filter/search box for sessions
|
||||
- Toggle for archived sessions (hidden by default)
|
||||
- Selected sessions highlighted/checked
|
||||
|
||||
### Navigation
|
||||
- Mouse: Click to select, double-click to open details
|
||||
- Keyboard: Tab/Shift+Tab between panels, arrows to navigate
|
||||
- Hotkeys always visible at bottom
|
||||
|
||||
### Actions
|
||||
- **Backup** (`B`) - Create timestamped DB copy
|
||||
- **Move** (`M`) - Move selected sessions to another project/workspace
|
||||
- **Copy** (`C`) - Duplicate sessions to another project
|
||||
- **Show archived** (`A`) - Toggle archived sessions visibility
|
||||
- **Refresh** (`R`) - Reload data from database
|
||||
- **Quit** (`Q`)
|
||||
|
||||
### Move/Copy Dialog
|
||||
- Dropdown selectors for destination Project (required) and Workspace (optional)
|
||||
- Preview of affected sessions and SQL statements that will execute
|
||||
- Confirmation before executing
|
||||
- Summary after completion
|
||||
|
||||
### Backup Strategy
|
||||
- Before first write operation, create backup: `opencode-YYYYMMDD-HHMMSS.db`
|
||||
- Location: same directory as source DB
|
||||
- Only one backup per session (don't spam)
|
||||
- User can manually backup at any time with `B`
|
||||
|
||||
## Technical Implementation
|
||||
|
||||
### Stack
|
||||
- **Python 3.9+**
|
||||
- **Textual** (TUI framework)
|
||||
- **sqlite3** (stdlib)
|
||||
|
||||
### Project Structure
|
||||
```
|
||||
session-mover/
|
||||
├── main.py # Application entry point
|
||||
├── app.py # Textual App class
|
||||
├── database.py # DB connection, queries, models
|
||||
├── widgets/
|
||||
│ ├── project_tree.py # Projects/Workspaces tree
|
||||
│ ├── sessions_table.py # Sessions data table
|
||||
│ └── dialogs.py # Move/Copy dialogs
|
||||
├── utils.py # Backup, formatting helpers
|
||||
└── requirements.txt
|
||||
```
|
||||
|
||||
### Database Operations
|
||||
|
||||
**Move session:**
|
||||
```sql
|
||||
UPDATE session SET project_id = ? WHERE id = ?;
|
||||
-- Optionally: UPDATE session SET workspace_id = ? WHERE id = ?;
|
||||
```
|
||||
|
||||
**Copy session:**
|
||||
```sql
|
||||
BEGIN TRANSACTION;
|
||||
-- Copy session with new UUID
|
||||
INSERT INTO session (...)
|
||||
SELECT ... FROM session WHERE id = ?;
|
||||
-- Copy related records with new IDs
|
||||
INSERT INTO message ... SELECT ... FROM message WHERE session_id = ?;
|
||||
INSERT INTO part ... SELECT ... FROM part WHERE session_id = ?;
|
||||
INSERT INTO todo ... SELECT ... FROM todo WHERE session_id = ?;
|
||||
INSERT INTO session_share ... SELECT ... FROM session_share WHERE session_id = ?;
|
||||
COMMIT;
|
||||
```
|
||||
|
||||
**Validation checks:**
|
||||
- Target project exists
|
||||
- If workspace specified: exists and belongs to target project
|
||||
- Sessions exist and aren't already in target
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. **Setup** - Create project structure, requirements.txt with `textual`
|
||||
2. **Database layer** - `database.py` with connection, session/project/workspace queries
|
||||
3. **TUI skeleton** - Basic Textual app with split layout
|
||||
4. **Project tree widget** - Load projects/workspaces, show hierarchy
|
||||
5. **Sessions table** - Load sessions with counts, implement filtering
|
||||
6. **Selection** - Multi-select mechanism (checkboxes or highlight+shift)
|
||||
7. **Action dialogs** - Move/Copy dialog with preview
|
||||
8. **Backup system** - Before first write operation
|
||||
9. **SQL execution** - Safe updates with transactions
|
||||
10. **Polish** - Status messages, error handling, hotkeys display
|
||||
|
||||
## Open Questions (Resolved)
|
||||
|
||||
- Use Textual: **Yes**
|
||||
- Show hotkeys: **Always at bottom**
|
||||
- Include archived: **hidden by default, toggle显示**
|
||||
- Single DB path: **Default opencode.db in current dir, --db flag to override**
|
||||
- Copy command: **Yes, duplicate sessions**
|
||||
- Batch move: **All selected move to same destination**
|
||||
- Confirmation needed: **Yes, with SQL preview**
|
||||
- Backup: **Timestamped copy before first write**
|
||||
- Workspace on move: **Optional - can keep current or select new**
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- Can browse all sessions with project/workspace context
|
||||
- Can select session(s) and move them to different project with one keystroke
|
||||
- Can see exactly what SQL will run before confirming
|
||||
- Backup created automatically before any change
|
||||
- All operations display clear success/error feedback
|
||||
- No need to write SQL manually
|
||||
Reference in New Issue
Block a user