diff options
Diffstat (limited to 'makima/docs')
| -rw-r--r-- | makima/docs/view-command.md | 223 |
1 files changed, 223 insertions, 0 deletions
diff --git a/makima/docs/view-command.md b/makima/docs/view-command.md new file mode 100644 index 0000000..6ef790c --- /dev/null +++ b/makima/docs/view-command.md @@ -0,0 +1,223 @@ +# Makima View Command + +The `makima view` command provides an interactive Terminal User Interface (TUI) for browsing and managing tasks, contracts, and files in the makima system. + +## Overview + +The view command offers a fuzzy-searchable interface inspired by tools like [fzf](https://github.com/junegunn/fzf) and [try](https://github.com/tobi/try). It allows you to quickly navigate through your makima entities using keyboard shortcuts and real-time filtering. + +## Usage + +```bash +# Browse tasks interactively +makima view tasks + +# Browse contracts with an initial search query +makima view contracts "my project" + +# Browse files without preview pane +makima view files --no-preview + +# Browse tasks for a specific contract +makima view tasks --contract-id <uuid> + +# Change directory to selected task's worktree (shell integration) +cd $(makima view tasks) +``` + +## Subcommands + +| Subcommand | Description | +|------------|-------------| +| `tasks` | Browse tasks with status indicators and progress summaries | +| `contracts` | Browse contracts with phase and status information | +| `files` | Browse contract files with content preview | + +## Options + +| Option | Environment Variable | Description | +|--------|---------------------|-------------| +| `--api-url` | `MAKIMA_API_URL` | API URL for the makima server (default: `https://api.makima.jp`) | +| `--api-key` | `MAKIMA_API_KEY` | API key for authentication | +| `--contract-id` | `MAKIMA_CONTRACT_ID` | Filter results to a specific contract | +| `--no-preview` | - | Disable the preview pane | +| `--sort` | - | Sort order: `recent` (default), `name`, or `status` | + +## Keyboard Shortcuts + +### Navigation + +| Key | Action | +|-----|--------| +| `↑` / `k` | Move selection up | +| `↓` / `j` | Move selection down | +| `Page Up` | Move up one page | +| `Page Down` | Move down one page | +| `Home` | Go to first item | +| `End` | Go to last item | + +### Actions + +| Key | Action | +|-----|--------| +| `Enter` | View/select the highlighted item | +| `e` | Open in editor (uses `$EDITOR` environment variable) | +| `d` | Delete item (with confirmation prompt) | +| `c` | Navigate to task's worktree (outputs path for `cd`) | +| `Tab` | Toggle preview pane visibility | +| `Ctrl+r` | Refresh data from server | + +### Search + +| Key | Action | +|-----|--------| +| `/` | Focus search input | +| `Esc` | Clear search / cancel | +| (typing) | Filter items in real-time | + +### General + +| Key | Action | +|-----|--------| +| `q` | Quit the TUI | +| `?` | Show help overlay | +| `1` / `2` / `3` | Switch view mode (Tasks/Contracts/Files) | + +## Features + +### Fuzzy Search + +The search uses the SkimMatcherV2 algorithm, providing: + +- **Smart case matching**: Case-insensitive by default, case-sensitive if pattern contains uppercase +- **Word boundary bonuses**: Matches at word boundaries score higher +- **Consecutive character bonuses**: Consecutive matches score higher +- **Multi-term search**: Space-separated terms all must match (e.g., "fix bug" matches items containing both "fix" and "bug") + +### Recency Sorting + +When using the default `recent` sort order, items are sorted by last update time. The fuzzy search also applies a recency bonus, so recently modified items rank higher even with slightly lower match scores. + +### Preview Pane + +The preview pane (toggled with `Tab`) shows detailed information about the selected item: + +- **Tasks**: Name, status, plan, progress summary, worktree path +- **Contracts**: Name, phase, status, task counts, repository info +- **Files**: Name, type, content preview (markdown rendered) + +### Status Indicators + +Tasks display visual status indicators: + +| Icon | Status | +|------|--------| +| `▸` | Running | +| `✓` | Done | +| `✗` | Failed | +| `○` | Pending | +| `⏸` | Paused | +| `⊘` | Blocked | + +## Shell Integration + +### Change to Task Worktree + +The view command can output the selected item's path for shell integration: + +```bash +# Change to selected task's worktree +cd $(makima view tasks) + +# Or create a shell function +function mcd() { + local path=$(makima view tasks "$@") + if [ -n "$path" ]; then + cd "$path" + fi +} +``` + +### Open in Editor + +The `e` key opens the selected item in your configured editor: + +```bash +# Set your preferred editor +export EDITOR=code # VS Code +export EDITOR=vim # Vim +export EDITOR=nano # Nano +``` + +## Examples + +### Browse Running Tasks + +```bash +makima view tasks "running" +``` + +### Find a Specific Contract + +```bash +makima view contracts "authentication" +``` + +### Quick Task Navigation + +```bash +# Jump to a task directory with fuzzy search +cd $(makima view tasks "api endpoint") +``` + +## Architecture + +The view command is built using: + +- **[ratatui](https://github.com/ratatui/ratatui)**: TUI rendering framework +- **[crossterm](https://github.com/crossterm-rs/crossterm)**: Cross-platform terminal manipulation +- **[fuzzy-matcher](https://github.com/lotabout/fuzzy-matcher)**: SkimMatcherV2 fuzzy matching algorithm + +### Module Structure + +``` +makima/src/daemon/ +├── cli/ +│ └── view.rs # CLI argument definitions +└── tui/ + ├── mod.rs # Module exports + ├── fuzzy.rs # Fuzzy matching wrapper + ├── app.rs # Application state (TODO) + ├── event.rs # Event handling (TODO) + ├── ui.rs # UI rendering (TODO) + ├── widgets/ # Reusable components (TODO) + └── views/ # View-specific logic (TODO) +``` + +## Troubleshooting + +### Terminal Compatibility + +The TUI requires a terminal that supports: +- ANSI escape codes +- Alternate screen buffer +- Mouse events (optional) + +Most modern terminals (iTerm2, Terminal.app, Windows Terminal, Alacritty, kitty) are supported. + +### Small Terminal Windows + +If your terminal is too small, use `--no-preview` to disable the preview pane and maximize the list area. + +### API Connection Issues + +If you see connection errors, verify: +1. `MAKIMA_API_URL` is set correctly +2. `MAKIMA_API_KEY` is valid +3. Network connectivity to the server + +## See Also + +- [makima supervisor](./supervisor-commands.md) - Task orchestration commands +- [makima contract](./contract-commands.md) - Contract interaction commands +- [makima daemon](./daemon.md) - Daemon configuration |