opencode-manager 0.3.1 → 0.4.0

package/PROJECT-SUMMARY.md

@@ -5,15 +5,47 @@ Overview
 --------
 - Purpose: Inspect, filter, and clean OpenCode metadata stored on disk.
 - Scope: Lists projects and sessions from local storage; supports filtering, search, interactive selection and deletion, and quick navigation between views.
-- UI: Terminal UI built with @opentui/react.
+- Dual interface: Terminal UI (TUI) built with @opentui/react for interactive use, plus a Commander-based CLI for scripting and automation.
 
 Architecture
 ------------
-- Entry: `opencode/src/opencode-tui.tsx` — main TUI app and panels.
-- Data layer: `opencode/src/lib/opencode-data.ts` — reads/writes metadata JSON, computes derived fields, formatting helpers.
-- Scripts: `opencode/package.json` → `bun run tui` runs the app.
-- CLI wrapper: `opencode/manage_opencode_projects.py` preserves the legacy entry point, resolves Bun (`--bun` overrides PATH), sets `--root` (defaults to `~/.local/share/opencode`), and forwards any extra args after `--` directly to the TUI.
-- Spec diff script: `opencode/opencode-gen.sh` shells out to `opencode generate`, saves the JSON spec under `~/repos/research/opencode/opencode-<version>-spec.json`, and diffs it against the previous snapshot (prefers `delta`, falls back to `diff`).
+The codebase follows a dual-mode architecture with shared libraries:
+
+### Entry Points
+- `src/bin/opencode-manager.ts` — Main entrypoint; routes to CLI or TUI based on subcommand.
+  - CLI subcommands: `projects`, `sessions`, `chat`, `tokens` → dynamic import of CLI module
+  - TUI mode: no subcommand, or explicit `tui` subcommand → dynamic import of TUI module
+
+### CLI Module (`src/cli/`)
+- `index.ts` — Commander program with global options (`--root`, `--format`, `--limit`, `--sort`, `--yes`, `--dry-run`, `--quiet`, `--clipboard`, `--backup-dir`); exports `runCLI(args)`.
+- `commands/` — Subcommand implementations:
+  - `projects.ts` — `list`, `delete` with dry-run/backup support
+  - `sessions.ts` — `list`, `delete`, `rename`, `move`, `copy` 
+  - `chat.ts` — `list`, `show`, `search` with clipboard support
+  - `tokens.ts` — `session`, `project`, `global` token summaries
+  - `tui.ts` — Launches TUI from CLI context
+- `formatters/` — Output formatters:
+  - `json.ts` — JSON with envelope (`{ok, data, meta}`)
+  - `ndjson.ts` — Newline-delimited JSON for streaming
+  - `table.ts` — Column-aligned tables with truncation
+- `output.ts` — Format selector routing by `--format` flag
+- `errors.ts` — Exit codes (0-4), error classes, validation helpers
+- `resolvers.ts` — ID resolution with exact/prefix matching
+- `backup.ts` — Pre-deletion backup to timestamped directories
+
+### TUI Module (`src/tui/`)
+- `app.tsx` — Main TUI app with Projects, Sessions, Chat panels
+- `index.tsx` — Exports `launchTUI(options)`, `bootstrap(args)`
+- `args.ts` — TUI-specific arg parsing (`--root`, `--help`)
+
+### Shared Libraries (`src/lib/`)
+- `opencode-data.ts` — Data layer: load/save metadata, compute tokens, filtering, formatting
+- `search.ts` — Fuzzy search via fast-fuzzy (sessions) and tokenized search (projects)
+- `clipboard.ts` — Cross-platform clipboard (`pbcopy`/`xclip`)
+
+### Other Files
+- `manage_opencode_projects.py` — Legacy wrapper; routes CLI/TUI via `src/bin/opencode-manager.ts`
+- `opencode-gen.sh` — Spec diff script for OpenCode JSON specs
 
 Metadata Layout & Helpers
 -------------------------
@@ -37,6 +69,8 @@ Key Features
   - Rename sessions inline (Shift+R) with validation.
   - Move sessions to another project (M) with project selector.
   - Copy sessions to another project (P) with new session ID generation.
+  - View chat history (V) with message navigation and clipboard support.
+  - Search chat content (F) across sessions with fuzzy matching.
 - Projects ↔ Sessions workflow
   - Pressing Enter on a project jumps to the Sessions tab with the project filter set; status text confirms the active filter.
   - `C` clears the filter (and notifies the user) so global searches go back to all sessions.
@@ -53,6 +87,7 @@ Key Features
 
 Work Completed
 --------------
+### TUI Features
 - Switched Projects list labels to show path instead of project ID; kept ID in the details panel.
 - Sessions list uses session title prominently; added title to details; updated onSelect/Enter status lines to show title and ID.
 - Redesigned Help screen into two columns with color-coded sections and key chips; removed wall-of-text effect.
@@ -69,36 +104,79 @@ Work Completed
 - Added session move feature (M): select target project, relocate session JSON, update projectID field.
 - Added session copy feature (P): select target project, create new session with generated ID, preserve original.
 
+### CLI Implementation (Phase 1-4)
+- Created Commander-based CLI with global options and subcommand routing.
+- Refactored entrypoint to route CLI vs TUI via dynamic imports.
+- Extracted shared libraries (`clipboard.ts`, `search.ts`) from TUI for CLI reuse.
+- Implemented output formatters: JSON with envelope, NDJSON for streaming, table with truncation.
+- Projects commands: `list` (with `--missing-only`, `--search`), `delete` (with `--dry-run`, `--backup-dir`).
+- Sessions commands: `list` (with `--project`, `--search`, fuzzy matching), `delete`, `rename`, `move`, `copy`.
+- Chat commands: `list` (with `--include-parts`), `show` (by `--message` or `--index`, with `--clipboard`), `search`.
+- Tokens commands: `session`, `project`, `global` summaries with breakdown tables.
+- Error handling with typed exit codes (0-4) and consistent error formatting.
+- ID resolution helpers with exact and prefix matching.
+- Pre-deletion backup to timestamped directories.
+- Comprehensive test suite: 350+ tests covering formatters, commands, resolvers, errors, exit codes.
+
 How To Run
 ----------
-- Zero-install via npm: `bunx opencode-manager [--root /path/to/storage]` (preferred).
-- Local dev: `bun run tui [-- --root /path/to/storage]`.
-- Legacy launcher: `./manage_opencode_projects.py [--root PATH] [--bun /path/to/bun] [-- ...extra TUI args]` keeps older automation working while delegating to Bun.
-- Keys:
-  - Global: `Tab`/`1`/`2` switch tabs, `/` search, `X` clear search, `R` reload, `Q` quit, `?` help
-  - Projects: `Space` select, `A` select all, `M` toggle missing, `D` delete, `Enter` view sessions
-  - Sessions: `Space` select, `S` sort, `D` delete, `Y` copy ID, `Shift+R` rename, `M` move, `P` copy, `C` clear filter
-- Optional tmux usage (when permitted): `tmux new -s opencode-tui 'bun run tui'`
-- CLI help: `bun run tui -- --help` (or `bunx opencode-manager -- --help`, or `manage_opencode_projects.py -- --help`) prints the built-in usage block with key bindings.
+### TUI Mode (Interactive)
+- Zero-install: `bunx opencode-manager [--root /path/to/storage]` (preferred)
+- Local dev: `bun run tui [-- --root /path/to/storage]`
+- Legacy launcher: `./manage_opencode_projects.py [--bun /path/to/bun]`
+- TUI help: `bunx opencode-manager --help` shows key bindings
+
+### CLI Mode (Scripting)
+- Projects: `bunx opencode-manager projects list --format json`
+- Sessions: `bunx opencode-manager sessions list --project <id> --limit 10`
+- Chat: `bunx opencode-manager chat search --query "fix bug" --format ndjson`
+- Tokens: `bunx opencode-manager tokens global --format table`
+- Delete with backup: `bunx opencode-manager sessions delete --session <id> --yes --backup-dir ./backups`
+- Dry run: `bunx opencode-manager projects delete --id <id> --dry-run`
+
+### Global CLI Options
+- `--root <path>` — Metadata store root (default: `~/.local/share/opencode`)
+- `--format <json|ndjson|table>` — Output format (default: `table`)
+- `--limit <n>` — Max records (default: 200)
+- `--sort <updated|created>` — Sort order (default: `updated`)
+- `--yes` — Skip confirmation for destructive ops
+- `--dry-run` — Preview changes without executing
+- `--quiet` — Suppress non-essential output
+- `--clipboard` — Copy output to clipboard
+- `--backup-dir <path>` — Backup before deletion
+
+### Exit Codes
+- 0: Success
+- 1: Internal error
+- 2: Usage/validation error (missing `--yes`, bad args)
+- 3: Resource not found (invalid project/session/message ID)
+- 4: File operation error (backup/delete failure)
+
+### TUI Keys
+- Global: `Tab`/`1`/`2` switch tabs, `/` search, `X` clear search, `R` reload, `Q` quit, `?/H` help
+- Projects: `Space` select, `A` select all, `M` toggle missing, `D` delete, `Enter` view sessions, `Esc` clear selection
+- Sessions: `Space` select, `A` select all, `S` sort, `V` view chat, `F` search chats, `Shift+R` rename, `M` move, `P` copy, `Y` copy ID, `C` clear filter, `D` delete, `Enter` details, `Esc` clear selection
+
+### Optional
+- tmux: `tmux new -s opencode-manager 'bun run tui'`
 
 Packaging & Publish Checklist
 -----------------------------
-1. Install dependencies with `bun install` (Bun v1.1+ only).
+1. Install dependencies with `bun install` (Bun v1.3+ only).
 2. Type-check via `bun run typecheck` (runs `tsc --noEmit`).
 3. Update the version in `package.json` as needed.
 4. Run `npm publish` (package exposes the Bun-native `opencode-manager` bin with public access).
 
 Outstanding Recommendations (Not Yet Implemented)
 -------------------------------------------------
-- UI polish
+- TUI polish
   - Colorize project state in list labels (e.g., green for present, red for missing, gray for unknown).
   - Show a small timestamp snippet for Projects rows (created).
   - Add tiny icons or color accents to distinguish created vs updated descriptions in Sessions.
   - Add per-view mini legends with colored key chips under the panels (Projects/Sessions), consistent with the Help styling.
-  - Show filtered counts (e.g., “Showing X of Y”).
+  - Show filtered counts (e.g., "Showing X of Y").
 - Search enhancements
-  - Optional fuzzy matching; toggle to include/exclude `directory` in Sessions/Projects search for more control.
-  - Persist search and sort preferences per tab (and optionally per project filter) during the app run.
+  - Optional fuzzy matching toggle in TUI; persist search and sort preferences per tab.
   - Save last-used search/sort to a small state file and restore on next launch.
 - Accessibility & layout
   - Ensure all active/inactive/focused states have adequate contrast and consistent highlight styles.
@@ -106,10 +184,12 @@ Outstanding Recommendations (Not Yet Implemented)
 - Performance
   - Debounce UI reactions to large search queries; short-circuit expensive filters when query is empty.
 - Testing
-  - Add unit coverage for opencode-data helpers (formatting, parsing, sorting).
-  - Add basic snapshot/E2E tests for rendering key panels and Help using a headless renderer (if available for @opentui).
-- Packaging/Docs
-  - Add a README section specific to the TUI tool, with a short demo, common actions, and troubleshooting.
+  - Add integration tests for CLI commands with real fixture data.
+  - Add basic snapshot/E2E tests for TUI rendering (if headless renderer available for @opentui).
+- CLI enhancements
+  - Shell completion scripts (bash/zsh/fish).
+  - `--json-lines` alias for `--format ndjson` compatibility.
+  - Template/profile support for common option combinations.
 
 Notes
 -----

package/README.md

@@ -3,7 +3,7 @@
 
 # OpenCode Metadata Manager
 
-Terminal UI for inspecting, filtering, and pruning OpenCode metadata stored on disk. The app is written in TypeScript, runs on Bun, and renders with [`@opentui/react`](https://github.com/open-tui/opentui).
+Terminal UI for inspecting, filtering, and pruning OpenCode metadata stored on disk. The app is written in TypeScript, runs on Bun, and renders with [`@opentui/react`](https://github.com/sst/opentui).
 
 ## Screenshots
 
@@ -23,7 +23,9 @@ Terminal UI for inspecting, filtering, and pruning OpenCode metadata stored on d
 - List both OpenCode projects and sessions from a local metadata root.
 - Filter by "missing only", bulk-select, and delete metadata safely.
 - Jump from a project directly to its sessions and keep contextual filters.
-- Global search bar (`/` to focus, `Enter` to apply, `Esc` or `X` to clear).
+- **Fuzzy search** across session titles and metadata (`/` to focus, results ranked by relevance).
+- **View session chat history** with full conversation context (`V` to open viewer).
+- **Search across all chat content** in sessions within a project (`F` to search).
 - Rename sessions inline (`Shift+R`) with title validation.
 - Move sessions between projects (`M`) preserving session ID.
 - Copy sessions to other projects (`P`) with new session ID generation.
@@ -56,7 +58,7 @@ The TUI displays token telemetry from OpenCode's stored message data at three le
 - Large datasets are handled with lazy computation to avoid UI freezes.
 
 ## Requirements
-- [Bun](https://bun.sh) **1.1.0+** (developed/tested on 1.2.x).
+- [Bun](https://bun.sh) **1.3.0+** (developed/tested on 1.3.x).
 - A node-compatible terminal (truecolor improves readability but is optional).
 
 ## Installation
@@ -73,6 +75,13 @@ bunx opencode-manager --help
 The repository ships with a focused `.gitignore`, keeping `node_modules/`, caches, and logs out of Git history.
 
 ## Usage
+
+The manager provides both a Terminal UI (TUI) and a scriptable CLI interface.
+
+### Terminal UI (TUI)
+
+The TUI is the default interface when no subcommand is provided:
+
 ```bash
 # Preferred: zero-install command
 bunx opencode-manager --root ~/.local/share/opencode
@@ -85,9 +94,326 @@ bun run tui -- --root ~/.local/share/opencode
 ```
 
 Keyboard reference:
-- **Global**: `Tab`/`1`/`2` switch tabs, `/` search, `X` clear search, `R` reload, `Q` quit, `?` help.
-- **Projects**: `Space` toggle selection, `A` select all, `M` missing-only filter, `D` delete, `Enter` jump to Sessions.
-- **Sessions**: `Space` select, `S` toggle sort, `D` delete, `Y` copy ID, `Shift+R` rename, `M` move to project, `P` copy to project, `C` clear filter.
+- **Global**: `Tab`/`1`/`2` switch tabs, `/` search (fuzzy), `X` clear search, `R` reload, `Q` quit, `?/H` help.
+- **Projects**: `Space` toggle selection, `A` select all, `M` missing-only filter, `D` delete, `Enter` jump to Sessions, `Esc` clear selection.
+- **Sessions**: `Space` select, `A` select all, `S` toggle sort, `V` view chat, `F` search chats, `D` delete, `Y` copy ID, `Shift+R` rename, `M` move, `P` copy, `C` clear filter, `Enter` details, `Esc` clear selection.
+- **Chat Search**: Type query + `Enter` to search, `Up/Down` navigate, `Enter` opens result, `Esc` close.
+- **Chat Viewer**: `Esc` close, `Up/Down` navigate, `PgUp/PgDn` jump 10, `Home/End` first/last, `Y` copy message.
+
+### Command Line Interface (CLI)
+
+The CLI provides scriptable access to all management operations. Use subcommands to list, search, and modify metadata.
+
+#### Global Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-r, --root <path>` | `~/.local/share/opencode` | Root path to OpenCode metadata store |
+| `-f, --format <fmt>` | `table` | Output format: `json`, `ndjson`, or `table` |
+| `-l, --limit <n>` | `200` | Maximum number of records to return |
+| `--sort <order>` | `updated` | Sort order: `updated` or `created` |
+| `-y, --yes` | `false` | Skip confirmation prompts for destructive operations |
+| `-n, --dry-run` | `false` | Preview changes without executing |
+| `-q, --quiet` | `false` | Suppress non-essential output |
+| `-c, --clipboard` | `false` | Copy output to clipboard |
+| `--backup-dir <path>` | — | Directory for backup copies before deletion |
+
+#### Commands Overview
+
+```
+opencode-manager
+├── projects
+│   ├── list      List projects (--missing-only, --search)
+│   └── delete    Delete project metadata (--id, --yes, --dry-run, --backup-dir)
+├── sessions
+│   ├── list      List sessions (--project, --search)
+│   ├── delete    Delete session metadata (--session, --yes, --dry-run, --backup-dir)
+│   ├── rename    Rename a session (--session, --title)
+│   ├── move      Move session to another project (--session, --to)
+│   └── copy      Copy session to another project (--session, --to)
+├── chat
+│   ├── list      List messages in a session (--session, --include-parts)
+│   ├── show      Show a specific message (--session, --message or --index, --clipboard)
+│   └── search    Search chat content across sessions (--query, --project)
+├── tokens
+│   ├── session   Show token usage for a session (--session)
+│   ├── project   Show token usage for a project (--project)
+│   └── global    Show global token usage
+└── tui           Launch the Terminal UI
+```
+
+#### TUI Subcommand
+
+The `tui` subcommand explicitly launches the Terminal UI. This is equivalent to running `opencode-manager` with no subcommand:
+
+```bash
+# These are equivalent:
+opencode-manager
+opencode-manager tui
+opencode-manager tui --root ~/.local/share/opencode
+```
+
+Use the explicit `tui` subcommand when you want to be clear about intent in scripts or when combining with other options. Note that `tui --help` shows the TUI help screen (key bindings), not Commander CLI help.
+
+#### Help System
+
+The manager uses a dual help system depending on context:
+
+| Command | Help Type | Content |
+|---------|-----------|---------|
+| `opencode-manager --help` | TUI help | Key bindings and TUI usage |
+| `opencode-manager -h` | TUI help | Same as `--help` |
+| `opencode-manager tui --help` | TUI help | Key bindings (routes to TUI help) |
+| `opencode-manager projects --help` | CLI help | Commander subcommand help |
+| `opencode-manager sessions --help` | CLI help | Commander subcommand help |
+| `opencode-manager chat --help` | CLI help | Commander subcommand help |
+| `opencode-manager tokens --help` | CLI help | Commander subcommand help |
+
+**Why?** The root command defaults to launching the TUI, so `--help` shows TUI-relevant information (key bindings). CLI subcommands use standard Commander.js help showing options and usage.
+
+To see all CLI subcommands, use any subcommand with `--help`:
+
+```bash
+# Shows TUI key bindings
+opencode-manager --help
+
+# Shows CLI subcommand help with options
+opencode-manager projects --help
+opencode-manager projects list --help
+```
+
+#### Output Format Examples
+
+The CLI supports three output formats via `--format`:
+
+**Table (default)** — Human-readable columnar output:
+
+```bash
+$ bunx opencode-manager projects list --limit 3
+
+   #  State  Path                                                Project ID                Created
+----  -----  --------------------------------------------------  ------------------------  ----------------
+   1    ✓    /home/user/repos/my-app                             a1b2c3d4e5f6g7h8i9j0k1l2  2026-01-04 09:20
+   2    ✓    /home/user/repos/api-server                         b2c3d4e5f6g7h8i9j0k1l2m3  2026-01-03 14:15
+   3    ✗    /home/user/repos/deleted-project                    c3d4e5f6g7h8i9j0k1l2m3n4  2025-12-28 10:30
+```
+
+**JSON** — Structured output with metadata envelope:
+
+```bash
+$ bunx opencode-manager sessions list --project prj_abc123 --format json --limit 2
+
+{
+  "ok": true,
+  "data": [
+    {
+      "index": 1,
+      "sessionId": "sess_xyz789",
+      "projectId": "prj_abc123",
+      "directory": "/home/user/repos/my-app",
+      "title": "Refactor auth module",
+      "version": "1.1.4",
+      "updatedAt": "2026-01-05T14:32:00.000Z",
+      "createdAt": "2026-01-03T09:15:00.000Z"
+    },
+    {
+      "index": 2,
+      "sessionId": "sess_uvw456",
+      "projectId": "prj_abc123",
+      "directory": "/home/user/repos/my-app",
+      "title": "Add unit tests",
+      "version": "1.1.4",
+      "updatedAt": "2026-01-04T16:45:00.000Z",
+      "createdAt": "2026-01-02T11:20:00.000Z"
+    }
+  ],
+  "meta": {
+    "count": 2,
+    "limit": 2
+  }
+}
+```
+
+JSON output auto-detects your terminal: pretty-printed with indentation when output goes to a TTY, compact single-line when piped to another command.
+
+The `meta` object contains:
+- `count` — Number of items in the `data` array
+- `limit` — The limit that was applied (if `--limit` was specified)
+
+**NDJSON** — Newline-delimited JSON for streaming/piping:
+
+```bash
+$ bunx opencode-manager sessions list --format ndjson --limit 2
+
+{"index":1,"sessionId":"ses_abc123","projectId":"prj_xyz789","title":"Feature implementation","createdAt":"2026-01-06T10:30:00.000Z"}
+{"index":2,"sessionId":"ses_def456","projectId":"prj_xyz789","title":"Bug fix session","createdAt":"2026-01-06T11:15:00.000Z"}
+```
+
+Each line is a complete JSON object, ideal for piping to `jq` or line-by-line processing. For single-record commands like `tokens global`, NDJSON outputs one line with the same structure as the JSON `data` field.
+
+**Piping examples:**
+
+```bash
+# Count sessions per project
+bunx opencode-manager sessions list --format ndjson | jq -s 'group_by(.projectId) | map({project: .[0].projectId, count: length})'
+
+# Get all session IDs as plain text
+bunx opencode-manager sessions list --format json | jq -r '.data[].sessionId'
+
+# Export chat history to file
+bunx opencode-manager chat list --session sess_xyz789 --include-parts --format json > chat-export.json
+
+# Dry-run delete to preview affected files
+bunx opencode-manager projects delete --id prj_old --dry-run --format json
+```
+
+#### Token Output Format
+
+Token commands (`tokens session`, `tokens project`, `tokens global`) return structured summaries of token usage.
+
+**Session tokens** — Single session summary with `kind` discriminator:
+
+```bash
+$ bunx opencode-manager tokens session --session sess_xyz789 --format json
+
+# When token data is available (kind: "known"):
+{
+  "ok": true,
+  "data": {
+    "kind": "known",
+    "tokens": {
+      "input": 12500,
+      "output": 8750,
+      "reasoning": 2100,
+      "cacheRead": 4200,
+      "cacheWrite": 950,
+      "total": 28500
+    }
+  }
+}
+
+# When token data is unavailable (kind: "unknown"):
+{
+  "ok": true,
+  "data": {
+    "kind": "unknown",
+    "reason": "no_messages"
+  }
+}
+```
+
+The `reason` field indicates why tokens are unavailable:
+- `"missing"` — Session metadata file not found
+- `"parse_error"` — Token data couldn't be parsed
+- `"no_messages"` — Session has no messages with token data
+
+**Project/Global tokens** — Aggregate summary across multiple sessions:
+
+```bash
+$ bunx opencode-manager tokens project --project prj_abc123 --format json
+
+{
+  "ok": true,
+  "data": {
+    "total": {
+      "kind": "known",
+      "tokens": { "input": 125000, "output": 98000, "reasoning": 32000, "cacheRead": 15000, "cacheWrite": 6500, "total": 276500 }
+    },
+    "knownOnly": { "input": 125000, "output": 98000, "reasoning": 32000, "cacheRead": 15000, "cacheWrite": 6500, "total": 276500 },
+    "unknownSessions": 2
+  }
+}
+```
+
+Aggregate summary fields:
+- `total` — Combined `TokenSummary` (same structure as session tokens)
+- `knownOnly` — Token breakdown from sessions with available data only (omitted if all unknown)
+- `unknownSessions` — Count of sessions where token data was unavailable
+
+**Note:** The `tokens` commands require exact IDs (no prefix matching). Use full session/project IDs as shown in `sessions list` or `projects list` output.
+
+#### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Usage error (missing required options, invalid arguments) |
+| 3 | Resource not found (invalid project/session/message ID) |
+| 4 | File operation error (backup or delete failure) |
+
+#### ID Resolution
+
+Most commands accept ID prefixes for convenience. The CLI will match the prefix to a unique ID:
+
+```bash
+# Full ID
+opencode-manager sessions delete --session sess_01JGNPE16DT1JX1YA8KTPMDRW3
+
+# Prefix match (if unique)
+opencode-manager sessions delete --session sess_01JGN
+
+# Ambiguous prefix (fails with error listing matches)
+opencode-manager sessions delete --session sess_01
+# Error: Multiple sessions match prefix 'sess_01': sess_01JGN..., sess_01ABC...
+```
+
+**Commands supporting prefix matching:**
+- `projects delete --id`
+- `sessions delete --session`, `sessions rename --session`, `sessions move --session`, `sessions copy --session`
+- `sessions move --to`, `sessions copy --to` (project ID)
+- `chat list --session`, `chat show --session`
+- `chat show --message` (also supports 1-based `--index`)
+
+**Commands requiring exact IDs:**
+- `tokens session --session` — requires full session ID
+- `tokens project --project` — requires full project ID
+
+#### Clipboard Support
+
+The `--clipboard` flag (or `Y` key in the TUI) copies content to the system clipboard. Platform support:
+
+| Platform | Tool Required | Notes |
+|----------|---------------|-------|
+| **macOS** | None | Uses built-in `pbcopy` |
+| **Linux** | `xclip` | Install via `apt install xclip` or equivalent |
+| **Windows** | — | Not currently supported |
+
+On Linux, if `xclip` is not installed, clipboard operations will fail silently in the TUI or show an error message in the CLI.
+
+#### Delete Semantics
+
+Delete commands (`projects delete`, `sessions delete`) remove **metadata files only**:
+
+| Command | Deletes | Preserves |
+|---------|---------|-----------|
+| `projects delete` | Project metadata (`storage/project/<id>.json`) | Sessions, messages, parts |
+| `sessions delete` | Session metadata (`storage/sessions/<projectId>.json` entry) | Message and part files |
+
+**Safety features:**
+
+- **Confirmation required** — Destructive operations require `--yes` flag or interactive confirmation:
+  ```bash
+  # Will prompt for confirmation (interactive)
+  opencode-manager projects delete --id prj_abc123
+  
+  # Skip confirmation (scripts)
+  opencode-manager projects delete --id prj_abc123 --yes
+  ```
+
+- **Dry-run preview** — Use `--dry-run` to see what would be deleted without making changes:
+  ```bash
+  opencode-manager sessions delete --session sess_xyz789 --dry-run
+  # Output shows files that would be affected
+  ```
+
+- **Backup before delete** — Use `--backup-dir` to copy files before deletion:
+  ```bash
+  opencode-manager projects delete --id prj_abc123 --backup-dir ./backups --yes
+  # Creates backup, then deletes original
+  ```
+
+**Note:** Session deletion leaves associated chat message files intact. To fully remove a session's data, you would need to manually delete the message files from `storage/message/<sessionId>/`.
 
 ## Development Workflow
 1. Install dependencies with `bun install`.
@@ -99,7 +425,9 @@ Keyboard reference:
 ```
 src/
   bin/opencode-manager.ts   # Bun-native CLI shim exposed as the bin entry
-  opencode-tui.tsx          # Main TUI implementation (panels, search, help)
+  tui/
+    app.tsx                 # Main TUI implementation (panels, search, help)
+    index.tsx               # TUI entrypoint with launchTUI(), parseArgs(), bootstrap()
 manage_opencode_projects.py # Legacy Python launcher for backwards compatibility
 opencode-gen.sh             # Spec snapshot helper script
 PROJECT-SUMMARY.md          # Extended design notes & roadmap

package/bun.lock

@@ -7,6 +7,8 @@
       "dependencies": {
         "@opentui/core": "^0.1.44",
         "@opentui/react": "^0.1.44",
+        "commander": "^12.0.0",
+        "fast-fuzzy": "^1.12.0",
         "react": "^19.0.0",
       },
       "devDependencies": {
@@ -123,6 +125,8 @@
 
     "bun-webgpu-win32-x64": ["bun-webgpu-win32-x64@0.1.4", "", { "os": "win32", "cpu": "x64" }, "sha512-Z5yAK28xrcm8Wb5k7TZ8FJKpOI/r+aVCRdlHYAqI2SDJFN3nD4mJs900X6kNVmG/xFzb5yOuKVYWGg+6ZXWbyA=="],
 
+    "commander": ["commander@12.1.0", "", {}, "sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA=="],
+
     "csstype": ["csstype@3.1.3", "", {}, "sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw=="],
 
     "event-target-shim": ["event-target-shim@5.0.1", "", {}, "sha512-i/2XbnSz/uxRCU6+NdVJgKWDTM427+MqYbkQzD321DuCQJUqOuJKIA0IM2+W2xtYHdKOmZ4dR6fExsd4SXL+WQ=="],
@@ -131,10 +135,14 @@
 
     "exif-parser": ["exif-parser@0.1.12", "", {}, "sha512-c2bQfLNbMzLPmzQuOr8fy0csy84WmwnER81W88DzTp9CYNPJ6yzOj2EZAh9pywYpqHnshVLHQJ8WzldAyfY+Iw=="],
 
+    "fast-fuzzy": ["fast-fuzzy@1.12.0", "", { "dependencies": { "graphemesplit": "^2.4.1" } }, "sha512-sXxGgHS+ubYpsdLnvOvJ9w5GYYZrtL9mkosG3nfuD446ahvoWEsSKBP7ieGmWIKVLnaxRDgUJkZMdxRgA2Ni+Q=="],
+
     "file-type": ["file-type@16.5.4", "", { "dependencies": { "readable-web-to-node-stream": "^3.0.0", "strtok3": "^6.2.4", "token-types": "^4.1.1" } }, "sha512-/yFHK0aGjFEgDJjEKP0pWCplsPFPhwyfwevf/pVxiN0tmE4L9LmwWxWukdJSHdoCli4VgQLehjJtwQBnqmsKcw=="],
 
     "gifwrap": ["gifwrap@0.10.1", "", { "dependencies": { "image-q": "^4.0.0", "omggif": "^1.0.10" } }, "sha512-2760b1vpJHNmLzZ/ubTtNnEx5WApN/PYWJvXvgS+tL1egTTthayFYIQQNi136FLEDcN/IyEY2EcGpIITD6eYUw=="],
 
+    "graphemesplit": ["graphemesplit@2.6.0", "", { "dependencies": { "js-base64": "^3.6.0", "unicode-trie": "^2.0.0" } }, "sha512-rG9w2wAfkpg0DILa1pjnjNfucng3usON360shisqIMUBw/87pojcBSrHmeE4UwryAuBih7g8m1oilf5/u8EWdQ=="],
+
     "ieee754": ["ieee754@1.2.1", "", {}, "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA=="],
 
     "image-q": ["image-q@4.0.0", "", { "dependencies": { "@types/node": "16.9.1" } }, "sha512-PfJGVgIfKQJuq3s0tTDOKtztksibuUEbJQIYT3by6wctQo+Rdlh7ef4evJ5NCdxY4CfMbvFkocEwbl4BF8RlJw=="],
@@ -143,11 +151,13 @@
 
     "jpeg-js": ["jpeg-js@0.4.4", "", {}, "sha512-WZzeDOEtTOBK4Mdsar0IqEU5sMr3vSV2RqkAIzUEV2BHnUfKGyswWFPFwK5EeDo93K3FohSHbLAjj0s1Wzd+dg=="],
 
+    "js-base64": ["js-base64@3.7.8", "", {}, "sha512-hNngCeKxIUQiEUN3GPJOkz4wF/YvdUdbNL9hsBcMQTkKzboD7T/q3OYOuuPZLUE6dBxSGpwhk5mwuDud7JVAow=="],
+
     "mime": ["mime@3.0.0", "", { "bin": "cli.js" }, "sha512-jSCU7/VB1loIWBZe14aEYHU/+1UMEHoaO7qxCOVJOw9GgH72VAWppxNcjU+x9a2k3GSIBXNKxXQFqRvvZ7vr3A=="],
 
     "omggif": ["omggif@1.0.10", "", {}, "sha512-LMJTtvgc/nugXj0Vcrrs68Mn2D1r0zf630VNtqtpI1FEO7e+O9FP4gqs9AcnBaSEeoHIPm28u6qgPR0oyEpGSw=="],
 
-    "pako": ["pako@1.0.11", "", {}, "sha512-4hLB8Py4zZce5s4yd9XzopqwVv/yGNhV1Bl8NTmCq1763HeK2+EwVTv+leGeL13Dnh2wfbqowVPXCIO0z4taYw=="],
+    "pako": ["pako@0.2.9", "", {}, "sha512-NUcwaKxUxWrZLpDG+z/xZaCgQITkA/Dv4V/T6bw7VON6l1Xz/VnrBqrYjZQ12TamKHzITTfOEIYUj48y2KXImA=="],
 
     "parse-bmfont-ascii": ["parse-bmfont-ascii@1.0.6", "", {}, "sha512-U4RrVsUFCleIOBsIGYOMKjn9PavsGOXxbvYGtMOEfnId0SVNsgehXh1DxUdVPLoxd5mvcEtvmKs2Mmf0Mpa1ZA=="],
 
@@ -189,6 +199,8 @@
 
     "three": ["three@0.177.0", "", {}, "sha512-EiXv5/qWAaGI+Vz2A+JfavwYCMdGjxVsrn3oBwllUoqYeaBO75J63ZfyaQKoiLrqNHoTlUc6PFgMXnS0kI45zg=="],
 
+    "tiny-inflate": ["tiny-inflate@1.0.3", "", {}, "sha512-pkY1fj1cKHb2seWDy0B16HeWyczlJA9/WW3u3c4z/NiWDsO3DOU5D7nhTLE9CF0yXv/QZFY7sEJmj24dK+Rrqw=="],
+
     "tinycolor2": ["tinycolor2@1.6.0", "", {}, "sha512-XPaBkWQJdsf3pLKJV9p4qN/S+fm2Oj8AIPo1BTUhg5oxkvm9+SVEGFdhyOz7tTdUTfvxMiAs4sp6/eZO2Ew+pw=="],
 
     "token-types": ["token-types@4.2.1", "", { "dependencies": { "@tokenizer/token": "^0.3.0", "ieee754": "^1.2.1" } }, "sha512-6udB24Q737UD/SDsKAHI9FCRP7Bqc9D/MQUV02ORQg5iskjtLJlZJNdN4kKtcdtwCeWIwIHDGaUsTsCCAa8sFQ=="],
@@ -197,6 +209,8 @@
 
     "undici-types": ["undici-types@6.21.0", "", {}, "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ=="],
 
+    "unicode-trie": ["unicode-trie@2.0.0", "", { "dependencies": { "pako": "^0.2.5", "tiny-inflate": "^1.0.0" } }, "sha512-x7bc76x0bm4prf1VLg79uhAzKw8DVboClSN5VxJuQ+LKDOVEW9CdH+VY7SP+vX7xCYQqzzgQpFqz15zeLvAtZQ=="],
+
     "utif2": ["utif2@4.1.0", "", { "dependencies": { "pako": "^1.0.11" } }, "sha512-+oknB9FHrJ7oW7A2WZYajOcv4FcDR4CfoGB0dPNfxbi4GO05RRnFmt5oa23+9w32EanrYcSJWspUiJkLMs+37w=="],
 
     "web-tree-sitter": ["web-tree-sitter@0.25.10", "", { "peerDependencies": { "@types/emscripten": "^1.40.0" }, "optionalPeers": ["@types/emscripten"] }, "sha512-Y09sF44/13XvgVKgO2cNDw5rGk6s26MgoZPXLESvMXeefBf7i6/73eFurre0IsTW6E14Y0ArIzhUMmjoc7xyzA=="],
@@ -214,5 +228,7 @@
     "image-q/@types/node": ["@types/node@16.9.1", "", {}, "sha512-QpLcX9ZSsq3YYUUnD3nFDY8H7wctAhQj/TFKL8Ya8v5fMm3CFXxo8zStsLAl780ltoYoo1WvKUVGBQK+1ifr7g=="],
 
     "pixelmatch/pngjs": ["pngjs@6.0.0", "", {}, "sha512-TRzzuFRRmEoSW/p1KVAmiOgPco2Irlah+bGFCeNfJXxxYGwSw7YwAOAcd7X28K/m5bjBWKsC29KyoMfHbypayg=="],
+
+    "utif2/pako": ["pako@1.0.11", "", {}, "sha512-4hLB8Py4zZce5s4yd9XzopqwVv/yGNhV1Bl8NTmCq1763HeK2+EwVTv+leGeL13Dnh2wfbqowVPXCIO0z4taYw=="],
   }
 }