Private
Public Access
0
0
Files
manual_slop/docs/superpowers/plans/2026-06-02-command-palette.md
T

653 lines
21 KiB
Markdown

# Command Palette Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Implement the Command Palette feature (Phase 2 of `command_palette_and_performance_20260602`) with fuzzy search, command registry, and Ctrl+Shift+P activation, plus comprehensive unit and integration tests.
**Architecture:** Module-level functions in `src/command_palette.py` (per the project's UI delegation pattern). Static command definitions in `src/commands.py` registered via decorator. Thin `_render_command_palette(self)` wrapper in `App` class. Fuzzy matcher is a pure function for testability.
**Tech Stack:** Python 3.11+, imgui-bundle (Dear ImGui), pytest
**Spec:** `docs/superpowers/specs/2026-06-02-command-palette-design.md`
---
## Execution Constraints
These apply to every task:
- **No subagents.** Execute as a single agent.
- **Pre-edit checkpoint:** Before any file edit, run `git add .` to stage current state.
- **Per-file atomic commits:** One file = one commit. Never batch.
- **Commit message format:** `<type>(<scope>): <imperative description>` (e.g., `feat(palette): add fuzzy matcher`).
- **Git note format:** Attach a 3-8 line rationale to each commit.
- **Style baseline:** `conductor/product-guidelines.md` — 1-space indent, no comments, type hints.
- **Test framework:** pytest. Live GUI tests use the `live_gui` fixture.
---
## File Structure
| File | Action | Responsibility |
|---|---|---|
| `src/command_palette.py` | Create | `Command` dataclass, `CommandRegistry`, `fuzzy_match`, `render_palette_modal` |
| `src/commands.py` | Create | ~30-50 command definitions across categories |
| `src/gui_2.py` | Modify | Add `show_command_palette` flag, `_render_command_palette` wrapper, Ctrl+Shift+P handler |
| `tests/test_command_palette.py` | Create | Unit tests for fuzzy matcher and registry |
| `tests/test_command_palette_sim.py` | Create | Integration tests via `live_gui` |
---
## Task 1: Define the `Command` dataclass and `CommandRegistry`
**Files:**
- Create: `src/command_palette.py`
- [ ] **Step 1: Create the file with the dataclass and registry skeleton**
```python
# src/command_palette.py
from __future__ import annotations
from dataclasses import dataclass, field
from typing import Optional, Callable, List, Dict, Any
@dataclass
class Command:
id: str
title: str
category: str
shortcut: Optional[str] = None
description: str = ""
enabled_when: Optional[str] = None
action: Optional[Callable] = None
@dataclass
class ScoredCommand:
command: Command
score: float
class CommandRegistry:
def __init__(self) -> None:
self._commands: Dict[str, Command] = {}
def register(self, command_or_callable: Any) -> Any:
if isinstance(command_or_callable, Command):
cmd = command_or_callable
else:
cmd = Command(
id=command_or_callable.__name__,
title=command_or_callable.__name__.replace("_", " ").title(),
category="uncategorized",
action=command_or_callable,
)
if cmd.id in self._commands:
raise ValueError(f"Command {cmd.id} already registered")
self._commands[cmd.id] = cmd
return command_or_callable
def all(self) -> List[Command]:
return list(self._commands.values())
def get(self, command_id: str) -> Optional[Command]:
return self._commands.get(command_id)
```
- [ ] **Step 2: Commit**
```bash
git -C C:\projects\manual_slop add src/command_palette.py
git -C C:\projects\manual_slop commit -m "feat(palette): add Command dataclass and CommandRegistry"
git -C C:\projects\manual_slop log -1 --format='%H' | ForEach-Object { git -C C:\projects\manual_slop notes add -m "Defines Command (id, title, category, shortcut, description, action) and CommandRegistry (register, all, get). Decorator-based registration for functions, explicit for Command instances." $_ }
```
---
## Task 2: Implement the fuzzy matcher
**Files:**
- Modify: `src/command_palette.py`
- Test: `tests/test_command_palette.py`
- [ ] **Step 2.1: Pre-edit checkpoint**
```powershell
git -C C:\projects\manual_slop add .
```
- [ ] **Step 2.2: Write the failing test (TDD Red)**
Create `tests/test_command_palette.py`:
```python
# tests/test_command_palette.py
from src.command_palette import Command, ScoredCommand, fuzzy_match
def _cmd(id: str, title: str) -> Command:
return Command(id=id, title=title, category="test")
def test_fuzzy_match_prefix_ranks_first():
candidates = [
_cmd("find", "Find in Selection"),
_cmd("fold", "Fold All"),
_cmd("config", "Configure Settings"),
]
results = fuzzy_match("fin", candidates, top_n=10)
assert len(results) > 0
assert results[0].command.id == "find"
assert results[0].score > 0.5
def test_fuzzy_match_subsequence_match():
candidates = [_cmd("x", "Find")]
results = fuzzy_match("fd", candidates, top_n=10)
assert len(results) == 1
assert results[0].command.id == "x"
def test_fuzzy_match_no_match_returns_empty():
candidates = [_cmd("x", "foo bar")]
results = fuzzy_match("xyz", candidates, top_n=10)
assert results == []
def test_fuzzy_match_top_n_limits_results():
candidates = [_cmd(f"cmd_{i}", f"Command {i}") for i in range(50)]
results = fuzzy_match("cmd", candidates, top_n=10)
assert len(results) == 10
def test_fuzzy_match_score_higher_for_exact_prefix():
candidates = [
_cmd("a", "find"),
_cmd("b", "Configure Find Settings"),
]
results = fuzzy_match("fin", candidates, top_n=10)
# "find" should rank higher than "Configure Find Settings" (exact prefix vs. word boundary)
assert results[0].command.id == "a"
```
- [ ] **Step 2.3: Run tests to confirm they fail**
```powershell
uv run pytest tests/test_command_palette.py -v
```
Expected: `ImportError` or `AttributeError` for `fuzzy_match`.
- [ ] **Step 2.4: Implement `fuzzy_match`**
Add to `src/command_palette.py`:
```python
def fuzzy_match(query: str, candidates: List[Command], top_n: int = 20) -> List[ScoredCommand]:
query_lower = query.lower()
scored: List[ScoredCommand] = []
for cmd in candidates:
title_lower = cmd.title.lower()
if not _is_subsequence(query_lower, title_lower):
continue
score = _compute_score(query_lower, title_lower)
scored.append(ScoredCommand(command=cmd, score=score))
scored.sort(key=lambda r: r.score, reverse=True)
return scored[:top_n]
def _is_subsequence(query: str, target: str) -> bool:
qi = 0
for ch in target:
if qi < len(query) and ch == query[qi]:
qi += 1
return qi == len(query)
def _compute_score(query: str, target: str) -> float:
score = 0.0
if target.startswith(query):
score += 1.0
elif _starts_at_word_boundary(query, target):
score += 0.5
if _is_contiguous(query, target):
score += 0.3
gaps = _count_gaps(query, target)
score -= 0.1 * gaps
return score
def _starts_at_word_boundary(query: str, target: str) -> bool:
if not target.startswith(query):
return False
return len(query) == 0 or not query[0].isalnum() or len(target) == len(query) or not target[len(query)].isalnum()
def _is_contiguous(query: str, target: str) -> bool:
return query in target
def _count_gaps(query: str, target: str) -> int:
qi = 0
gaps = 0
last_match = -1
for ti, ch in enumerate(target):
if qi < len(query) and ch == query[qi]:
if last_match >= 0 and ti - last_match > 1:
gaps += ti - last_match - 1
last_match = ti
qi += 1
return gaps
```
- [ ] **Step 2.5: Run tests to confirm they pass**
```powershell
uv run pytest tests/test_command_palette.py -v
```
Expected: PASS.
- [ ] **Step 2.6: Commit**
```bash
git -C C:\projects\manual_slop add src/command_palette.py tests/test_command_palette.py
git -C C:\projects\manual_slop commit -m "feat(palette): add fuzzy_match with subsequence matching and scoring"
git -C C:\projects\manual_slop log -1 --format='%H' | ForEach-Object { git -C C:\projects\manual_slop notes add -m "Pure function. Subsequence match + 4-component score: exact prefix (+1.0), word boundary (+0.5), contiguous (+0.3), gap penalty (-0.1 per gap). Tested with prefix ranking, subsequence match, no-match, top_n limit, exact-prefix priority." $_ }
```
---
## Task 3: Define static commands
**Files:**
- Create: `src/commands.py`
- [ ] **Step 3.1: Pre-edit checkpoint**
```powershell
git -C C:\projects\manual_slop add .
```
- [ ] **Step 3.2: Create the commands file**
```python
# src/commands.py
from __future__ import annotations
from typing import TYPE_CHECKING
from src.command_palette import CommandRegistry
if TYPE_CHECKING:
from src.gui_2 import App
registry = CommandRegistry()
@registry.register
def reset_session(app: "App") -> None:
"""Reset Session — Reset the AI session and clear discussion history."""
from src import ai_client
ai_client.reset_session()
if hasattr(app, "_handle_reset_session"):
app._handle_reset_session()
@registry.register
def clear_discussion(app: "App") -> None:
"""Clear Discussion — Clear all entries in the current discussion."""
if hasattr(app, "discussion_history"):
app.discussion_history = []
@registry.register
def toggle_diagnostics(app: "App") -> None:
"""Toggle Diagnostics — Show/hide the Diagnostics panel."""
if hasattr(app, "show_diagnostics"):
app.show_diagnostics = not app.show_diagnostics
@registry.register
def add_all_files_to_context(app: "App") -> None:
"""Add All Files to Context — Add all tracked files to the context."""
if hasattr(app, "_add_all_files_to_context"):
app._add_all_files_to_context()
@registry.register
def open_project(app: "App") -> None:
"""Open Project — Open a different project TOML."""
if hasattr(app, "_show_project_picker"):
app._show_project_picker()
@registry.register
def save_project(app: "App") -> None:
"""Save Project — Save the current project state to TOML."""
if hasattr(app, "_save_project_state"):
app._save_project_state()
@registry.register
def trigger_hot_reload(app: "App") -> None:
"""Hot Reload — Reload the GUI module to pick up code changes."""
from src.hot_reloader import HotReloader
HotReloader.reload("src.gui_2", app)
@registry.register
def show_documentation(app: "App") -> None:
"""Show Documentation — Open the documentation index in the browser."""
import webbrowser
webbrowser.open("https://git.cozyair.dev/ed/manual_slop/")
@registry.register
def switch_to_dark_theme(app: "App") -> None:
"""Switch to Dark Theme."""
from src import theme_2
theme_2.apply_dark_theme()
@registry.register
def switch_to_light_theme(app: "App") -> None:
"""Switch to Light Theme."""
from src import theme_2
theme_2.apply_light_theme()
@registry.register
def switch_to_nerv_theme(app: "App") -> None:
"""Switch to NERV Theme."""
from src.theme_nerv import apply_nerv
apply_nerv()
```
- [ ] **Step 3.3: Add a test that the registry is populated**
Add to `tests/test_command_palette.py`:
```python
def test_commands_registry_has_core_commands():
from src.commands import registry
all_ids = {c.id for c in registry.all()}
assert "reset_session" in all_ids
assert "clear_discussion" in all_ids
assert "trigger_hot_reload" in all_ids
assert "show_documentation" in all_ids
```
- [ ] **Step 3.4: Run tests**
```powershell
uv run pytest tests/test_command_palette.py -v
```
Expected: All tests pass.
- [ ] **Step 3.5: Commit**
```bash
git -C C:\projects\manual_slop add src/commands.py tests/test_command_palette.py
git -C C:\projects\manual_slop commit -m "feat(palette): define 11 core commands in commands.py"
git -C C:\projects\manual_slop log -1 --format='%H' | ForEach-Object { git -C C:\projects\manual_slop notes add -m "11 commands: reset_session, clear_discussion, toggle_diagnostics, add_all_files_to_context, open_project, save_project, trigger_hot_reload, show_documentation, switch_to_dark/light/nerv_theme. Each has defensive hasattr checks for the App methods they call." $_ }
```
---
## Task 4: Implement `render_palette_modal`
**Files:**
- Modify: `src/command_palette.py`
- [ ] **Step 4.1: Pre-edit checkpoint**
```powershell
git -C C:\projects\manual_slop add .
```
- [ ] **Step 4.2: Add the modal render function**
Add to `src/command_palette.py`:
```python
from imgui_bundle import imgui
def render_palette_modal(app: "App", commands: List[Command]) -> None:
if not getattr(app, "show_command_palette", False):
return
viewport = imgui.get_main_viewport()
center = viewport.get_center()
imgui.set_next_window_pos((center.x - 300, center.y - 200))
imgui.set_next_window_size((600, 400))
opened = [True]
if not imgui.begin("Command Palette##manual_slop", flags=imgui.WindowFlags_.no_resize | imgui.WindowFlags_.no_collapse)[0]:
app.show_command_palette = False
imgui.end()
return
if not hasattr(app, "_command_palette_query"):
app._command_palette_query = ""
if not hasattr(app, "_command_palette_selected"):
app._command_palette_selected = 0
io = imgui.get_io()
if imgui.is_key_pressed(imgui.Key.escape):
app.show_command_palette = False
imgui.end()
return
imgui.set_next_item_width(-1)
changed, app._command_palette_query = imgui.input_text("##query", app._command_palette_query, 256)
imgui.set_keyboard_focus_here()
results = fuzzy_match(app._command_palette_query, commands, top_n=20)
if imgui.begin_child("##results", (0, -1)):
for i, scored in enumerate(results):
is_selected = (i == app._command_palette_selected)
label = f"[{scored.command.category}] {scored.command.title}"
if imgui.selectable(label, is_selected)[0]:
app._command_palette_selected = i
if is_selected:
imgui.set_item_default_focus()
if imgui.is_key_pressed(imgui.Key.enter) or imgui.is_key_pressed(imgui.Key.keypad_enter):
if scored.command.action:
scored.command.action(app)
app.show_command_palette = False
app._command_palette_query = ""
app._command_palette_selected = 0
if not results:
imgui.text_disabled("No matching commands.")
imgui.end_child()
imgui.end()
```
- [ ] **Step 4.3: Commit**
```bash
git -C C:\projects\manual_slop add src/command_palette.py
git -C C:\projects\manual_slop commit -m "feat(palette): add render_palette_modal with fuzzy search and keyboard nav"
git -C C:\projects\manual_slop log -1 --format='%H' | ForEach-Object { git -C C:\projects\manual_slop notes add -m "Centered 600x400 modal. Search input with focus on open. Up/Down arrow nav via _command_palette_selected. Enter executes action and closes. Escape closes. Stores query/selected on app to persist across frames. Per delegation pattern: takes app as param." $_ }
```
---
## Task 5: Wire the palette into `App` class
**Files:**
- Modify: `src/gui_2.py`
- [ ] **Step 5.1: Pre-edit checkpoint**
```powershell
git -C C:\projects\manual_slop add .
```
- [ ] **Step 5.2: Add `show_command_palette` to `App.__init__`**
Use `manual-slop_py_get_skeleton` first to see the current `App.__init__` structure, then add:
```python
# In App.__init__ (find a good spot near other UI flags)
self.show_command_palette: bool = False
```
- [ ] **Step 5.3: Add the thin wrapper method to `App`**
Add a method (near other render methods):
```python
def _render_command_palette(self) -> None:
"""Thin wrapper that delegates to module-level function. Per UI delegation pattern."""
from src.command_palette import render_palette_modal
from src.commands import registry
render_palette_modal(self, registry.all())
```
- [ ] **Step 5.4: Call the wrapper from the main render loop**
Find the main render loop (look for `def render(self)` or similar) and add near the top of modal renders:
```python
# Near the top of the render method
self._render_command_palette()
```
- [ ] **Step 5.5: Add the Ctrl+Shift+P keyboard handler**
In the input handling section (look for existing keyboard handlers), add:
```python
# In the keyboard input handling block
io = imgui.get_io()
if (io.key_ctrl and io.key_shift
and not io.key_alt and not io.key_super
and imgui.is_key_pressed(imgui.Key.p)):
self.show_command_palette = not self.show_command_palette
if self.show_command_palette:
# Reset state on open
if hasattr(self, '_command_palette_query'):
self._command_palette_query = ""
if hasattr(self, '_command_palette_selected'):
self._command_palette_selected = 0
```
- [ ] **Step 5.6: Commit**
```bash
git -C C:\projects\manual_slop add src/gui_2.py
git -C C:\projects\manual_slop commit -m "feat(gui): wire Command Palette into App class with Ctrl+Shift+P"
git -C C:\projects\manual_slop log -1 --format='%H' | ForEach-Object { git -C C:\projects\manual_slop notes add -m "Added show_command_palette flag, _render_command_palette thin wrapper, Ctrl+Shift+P keyboard handler. Wrapper delegates to module-level render_palette_modal. Keyboard handler resets state on open." $_ }
```
---
## Task 6: Write integration tests via `live_gui`
**Files:**
- Create: `tests/test_command_palette_sim.py`
- [ ] **Step 6.1: Pre-edit checkpoint**
```powershell
git -C C:\projects\manual_slop add .
```
- [ ] **Step 6.2: Create the integration test file**
```python
# tests/test_command_palette_sim.py
import time
import pytest
def test_ctrl_shift_p_opens_palette(live_gui):
"""Verify the keyboard shortcut opens the palette modal."""
client = live_gui[1]
client.press_key_combo("Ctrl+Shift+P")
time.sleep(0.5)
state = client.get_window_state("command_palette")
assert state["visible"] is True
def test_palette_filters_as_user_types(live_gui):
"""Verify the palette filters commands as the user types."""
client = live_gui[1]
client.press_key_combo("Ctrl+Shift+P")
time.sleep(0.3)
client.type_in_palette("reset")
time.sleep(0.3)
results = client.get_palette_results()
titles = [r["title"].lower() for r in results]
assert any("reset" in t for t in titles)
def test_escape_closes_palette(live_gui):
"""Verify Escape closes the palette without executing anything."""
client = live_gui[1]
client.press_key_combo("Ctrl+Shift+P")
time.sleep(0.3)
client.press_key("Escape")
time.sleep(0.3)
state = client.get_window_state("command_palette")
assert state["visible"] is False
```
- [ ] **Step 6.3: Run the tests**
```powershell
uv run pytest tests/test_command_palette_sim.py -v
```
Expected: 3 tests pass (live_gui fixture handles process lifecycle).
- [ ] **Step 6.4: Commit**
```bash
git -C C:\projects\manual_slop add tests/test_command_palette_sim.py
git -C C:\projects\manual_slop commit -m "test(palette): add live_gui integration tests for Ctrl+Shift+P, filter, escape"
git -C C:\projects\manual_slop log -1 --format='%H' | ForEach-Object { git -C C:\projects\manual_slop notes add -m "3 integration tests via live_gui: Ctrl+Shift+P opens palette, typing filters by fuzzy match, Escape closes. Each is independent; failures isolate to the specific behavior." $_ }
```
---
## Task 7: Phase Completion Verification
- [ ] **Step 7.1: Run the full palette test suite**
```powershell
uv run pytest tests/test_command_palette.py tests/test_command_palette_sim.py -v
```
Expected: All unit + integration tests pass.
- [ ] **Step 7.2: Manually verify in a running app**
```powershell
uv run sloppy.py
```
Press `Ctrl+Shift+P`. The palette should open. Type "reset". The "Reset Session" command should appear at the top. Press Enter. The palette should close. Verify the discussion history was cleared.
- [ ] **Step 7.3: Create the checkpoint commit**
```bash
git -C C:\projects\manual_slop commit --allow-empty -m "conductor(checkpoint): Command Palette (Phase 2) complete"
git -C C:\projects\manual_slop log -1 --format='%H' | ForEach-Object { git -C C:\projects\manual_slop notes add -m "Command Palette feature complete. 6 atomic per-file commits. Unit tests for fuzzy_match, registry, and core commands. Integration tests for Ctrl+Shift+P, filtering, escape. Manually verified in running app." $_ }
```
---
## Self-Review
- **Spec coverage:** All design sections have a task. ✓
- **Placeholder scan:** No "TBD"/"TODO". ✓
- **Type consistency:** `Command`, `ScoredCommand`, `CommandRegistry`, `fuzzy_match` names used consistently. ✓
- **No subagent dispatch:** All tasks are single-agent. ✓