From 0833fb1f30c0c3b920157deb882e0e902c3af02a Mon Sep 17 00:00:00 2001 From: soryu Date: Mon, 19 Jan 2026 13:47:32 +0000 Subject: Add interactive TUI browser for tasks, contracts, and files (makima view) (#7) * feat(tui): Implement fuzzy search with real-time filtering and highlighting Adds comprehensive fuzzy search functionality to the TUI browser: ## Fuzzy Matching (fuzzy.rs) - FuzzyMatcher wrapper using SkimMatcherV2 from fuzzy-matcher crate - fuzzy_match() returns score and matched character indices - fuzzy_match_all() supports multi-term search (space-separated) - Recency-aware scoring to boost recent items in results - Unit tests for all matching scenarios ## App State (app.rs) - FilteredItem struct with index, score, and matched_indices - apply_filter() uses fuzzy matching with score-based sorting - match_count() and has_no_matches() helper methods - Results sorted by match score (highest first) ## List View (list_view.rs) - Highlighted matched characters in search results - Yellow bold styling for matched chars - Status icons with color coding ## Search Input (search_input.rs) - Real-time match count display (X/Y matches) - Visual feedback for no matches (red border) - Placeholder text when search is empty - Active search mode indication (yellow border) ## Event Handling (event.rs) - Arrow key navigation while in search mode - Ctrl+K/J for vim-style navigation during search - Delete key support alongside backspace - Ctrl+U to clear search query - Tab toggles preview while searching - Escape clears search and exits search mode Co-Authored-By: Claude Opus 4.5 * Task completion checkpoint * [WIP] Heartbeat checkpoint - 2026-01-19 11:20:34 UTC * Task completion checkpoint * [WIP] Heartbeat checkpoint - 2026-01-19 11:31:19 UTC * Task completion checkpoint * [WIP] Heartbeat checkpoint - 2026-01-19 11:39:07 UTC * fix(tui): Fix module exports and main binary integration - Update mod.rs to properly export app, event, fuzzy, and ui modules - Add run() function for TUI entry point - Fix run_view() to use ViewCommand enum instead of ViewArgs - Fix event handling to use poll_event and handle_key_event Co-Authored-By: Claude Opus 4.5 --------- Co-authored-by: Claude Opus 4.5 --- makima/docs/view-command.md | 223 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 223 insertions(+) create mode 100644 makima/docs/view-command.md (limited to 'makima/docs') 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 + +# 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 -- cgit v1.2.3