bc1b3147cd
Address 8 issues found in spec audit (post PR #2): 1. §refs label: distinguish design vs report sections in p3-1 / p3-2 / p4-2 / p9-1 / p9-5 contract_sections (e.g., "report §11.2 Ollama" not "§11.2"). 2. mock feature gate: gate MockEmbedder (p3-1) and MockLanguageModel (p4-1) behind `mock` cargo feature, default OFF; add CI symbol-scan as DoD item. 3. Warning type unification: p1-2 frontmatter now emits `kb_parse_types::Warning` (matches p1-3 / p1-4); drops crate-internal type. 4. p4-3 streaming thread: explicitly single-threaded inside RagPipeline::ask; collection + sink.send share the calling thread, no race. UI concurrency is callers responsibility (TUI worker thread pattern in p9-3). 5. p6-2 tesseract version: noted that `tesseract` 0.13 has no stable Rust `version()` accessor; use TessVersion FFI or shell-out + cache approach. 6. p9-* App struct extensions: introduce `kb_tui::{Library,Search,Ask,Inspect}State` slots in p9-1 forward-decl form; p9-2/3/4 fill bodies in their own crate without editing `App`. Parallel-safety contract added. 7. p3-3 cosine score: shift `(sim+1)/2` instead of clamp; preserve ranking signal between unrelated and opposite vectors. Clamp reserved for NaN. 8. fixtures/ root: p0-1 DoD now creates all fixture subdirs with .gitkeep so downstream tasks have a stable target path.
145 lines
6.3 KiB
Markdown
145 lines
6.3 KiB
Markdown
---
|
|
phase: P9
|
|
component: kb-tui (library view)
|
|
task_id: p9-1
|
|
title: "Ratatui library list view + tag filter"
|
|
status: planned
|
|
depends_on: [p1-6]
|
|
unblocks: [p9-2, p9-3, p9-4]
|
|
contract_source: ../../docs/superpowers/specs/2026-04-27-kb-final-form-design.md
|
|
contract_sections: [report §16.2 TUI (also tasks/phase-9-ui.md epic), design §3.7 SearchHit, design §1 UX scenes for shared key bindings]
|
|
---
|
|
|
|
# p9-1 — TUI library view
|
|
|
|
## Goal
|
|
|
|
Stand up a Ratatui app skeleton with a "Library" pane: list documents, filter by tag/lang, navigate. Establishes the global app loop, key dispatch, and `kb-app` integration point that the search/ask/inspect panes (p9-2..p9-4) extend.
|
|
|
|
## Why now / why this size
|
|
|
|
Library is the cheapest screen and the natural anchor for the TUI shell. Subsequent panes plug into the same dispatch / shared state.
|
|
|
|
## Allowed dependencies
|
|
|
|
- `kb-core`
|
|
- `kb-config`
|
|
- `kb-app` (facade — the only crate this binary touches besides `kb-core`/`kb-config`)
|
|
- `ratatui = "0.28"`
|
|
- `crossterm`
|
|
- `tracing`
|
|
- `thiserror`
|
|
|
|
## Forbidden dependencies
|
|
|
|
- `kb-source-fs`, `kb-parse-*`, `kb-normalize`, `kb-chunk`, `kb-store-*`, `kb-embed*`, `kb-search`, `kb-llm*`, `kb-rag` (UI must go through `kb-app` only — this is the design §8 boundary)
|
|
|
|
## Inputs
|
|
|
|
| input | type | source |
|
|
|-------|------|--------|
|
|
| `kb-app::list_docs(filter)` | facade call | runtime |
|
|
| keyboard events | `crossterm` | terminal |
|
|
| `kb-config::Config` | runtime | env / file |
|
|
|
|
## Outputs
|
|
|
|
| output | type | downstream |
|
|
|--------|------|------------|
|
|
| Ratatui frame | terminal render | user |
|
|
| App state (selected doc, filter, focus) | in-memory | next-pane handoff |
|
|
|
|
## Public surface (signatures only — no new types)
|
|
|
|
```rust
|
|
// `App` is the SHELL — its full set of fields is owned by p9-1, but the layout
|
|
// reserves one optional sub-state slot per pane so p9-2/3/4 can plug their own
|
|
// state in WITHOUT modifying the App struct definition. This avoids merge
|
|
// conflicts when p9-2/3/4 land in parallel; only p9-1 ever changes `App`.
|
|
pub struct App {
|
|
pub config: kb_config::Config,
|
|
pub focus: Pane,
|
|
pub library: LibraryState, // owned by p9-1
|
|
pub search: Option<SearchState>, // populated by p9-2 (None until that crate links in)
|
|
pub ask: Option<AskState>, // populated by p9-3
|
|
pub inspect: Option<InspectState>, // populated by p9-4
|
|
}
|
|
|
|
// p9-1 defines LibraryState fully. The other 3 sub-states are forward-declared
|
|
// as opaque (zero-field) here; their authoring tasks fill them.
|
|
pub struct LibraryState { /* docs, filter, selection */ }
|
|
pub struct SearchState; // body filled by p9-2
|
|
pub struct AskState; // body filled by p9-3
|
|
pub struct InspectState; // body filled by p9-4
|
|
|
|
impl App {
|
|
pub fn new(config: kb_config::Config) -> anyhow::Result<Self>;
|
|
pub fn run(&mut self) -> anyhow::Result<()>; // blocking loop until quit
|
|
}
|
|
|
|
pub enum Pane { Library, Search, Ask, Inspect, Jobs }
|
|
|
|
pub fn render_library<B: ratatui::backend::Backend>(f: &mut ratatui::Frame, area: ratatui::layout::Rect, state: &App);
|
|
|
|
pub fn handle_key_library(state: &mut App, key: crossterm::event::KeyEvent) -> KeyOutcome;
|
|
|
|
pub enum KeyOutcome { Continue, Quit, SwitchPane(Pane), Refresh }
|
|
```
|
|
|
|
**Parallel-safety contract:** p9-2 / p9-3 / p9-4 fill the bodies of `SearchState` / `AskState` / `InspectState` in their own crate's source — no edits to `App`, no edits to the other sub-state structs. Their `render_*` and `handle_key_*` functions take `&mut App` but read/write only their own `Option<...>` field. With this slot pattern, the four p9-* tasks can be authored in parallel and merged in any order without conflict on `App`.
|
|
|
|
## Behavior contract
|
|
|
|
- Layout: header (1 line, breadcrumb / pane label) + body (full) + footer (key hints).
|
|
- Library body: scrollable list of `DocSummary` with columns `[title] [tag list] [updated_at] [chunk_count]`.
|
|
- Filter bar (toggled by `f`): edit `tags_any` and `lang` fields; pressing `Enter` re-runs `list_docs`.
|
|
- Key bindings (Library pane only):
|
|
- `j` / `k` or arrow keys → move selection down/up
|
|
- `g g` → top, `G` → bottom
|
|
- `f` → toggle filter
|
|
- `/` → switch to Search pane (p9-2)
|
|
- `?` → switch to Ask pane (p9-3)
|
|
- `Enter` → switch to Inspect pane (p9-4) on selected doc
|
|
- `q` or `Esc` → quit
|
|
- All facade calls run on the main thread (no async). For long calls, render a "loading…" state and call from a worker thread; bridge via `mpsc::channel` (this task may keep things synchronous and accept brief UI hangs for v1).
|
|
- Logging: `tracing` initialized to a file under `~/.local/state/kb/logs/`; never to stdout/stderr (so the TUI is not corrupted).
|
|
- Error rendering: a popup overlay shows `error: {msg}\nhint: {hint}` from `anyhow::Error` chain; press any key to dismiss.
|
|
|
|
## Storage / wire effects
|
|
|
|
- Reads: `kb-app::list_docs` only.
|
|
- Writes: none.
|
|
|
|
## Test plan
|
|
|
|
| kind | description | fixture / data |
|
|
|------|-------------|----------------|
|
|
| unit | `handle_key_library` arrow-down increments selection within bounds | inline state |
|
|
| unit | filter `f` opens edit overlay; `Enter` triggers refresh | inline |
|
|
| snapshot | rendered library with 3 docs + filter open produces stable frame buffer (use `ratatui::backend::TestBackend`) | inline |
|
|
| unit | error popup renders without panic on injected `anyhow::Error` | inline |
|
|
| integration | mocked `kb-app::list_docs` returning N docs renders all rows | inline |
|
|
|
|
All tests under `cargo test -p kb-tui library`.
|
|
|
|
## Definition of Done
|
|
|
|
- [ ] `cargo check -p kb-tui` passes
|
|
- [ ] `cargo test -p kb-tui library` passes
|
|
- [ ] No imports outside `kb-core`, `kb-config`, `kb-app`
|
|
- [ ] `kb tui` (or `kb` if TUI is the default) launches and shows Library on a real terminal (manual smoke)
|
|
- [ ] PR links design §8 module boundary, report §16.2 (TUI epic)
|
|
|
|
## Out of scope
|
|
|
|
- Search pane (p9-2), Ask pane (p9-3), Inspect pane (p9-4), Jobs pane.
|
|
- Mouse support (P+).
|
|
- Theme / color customization (P+).
|
|
- Cross-platform installation packaging (separate concern).
|
|
|
|
## Risks / notes
|
|
|
|
- Ratatui re-renders on every event; large doc lists can be slow. Use `ListState` and only render visible rows.
|
|
- crossterm raw-mode cleanup must run on panic (`color_eyre` or manual `disable_raw_mode` in `Drop`); a corrupted terminal after a crash is a UX disaster.
|
|
- Korean text rendering width: use `unicode-width` and account for wide characters when computing column widths.
|