Wayfind: pretty check + watch TUI + showcase fixture (toward check --watch)

[XertroV]

Destination

Ship path toward a releasable CLI mode (post-screenshots → 0.3.1+):

1. Pretty check — TTY default: source excerpts + caret annotations + light frame; plain gcc-style when piped / NO_COLOR / --format plain.
2. Showcase fixture at tests/fixtures/showcase-diags/ with a deliberate solid array of diagnostics (deps, inference, generics, etc.) for CI + screenshots.
3. Watch TUI v1 — openplanet-lsp check --watch: re-run diagnostics on file change (notify/inotify-class), pretty list, quit key. Not full IDE chrome in this map.
4. Rust-only TUI crate in-repo (e.g. crates/openplanet-lsp-tui) with mock TuiDataSource first, then wire a real backend via a run(...) API the main binary calls.
5. Automated TUI snapshots / e2e as part of the crate quality bar.

Notes

• Repo: clankercode/lsp-openplanet (Rust LSP). Skills: wayfinder, grilling, prototype, codebase-design, ultra-tui-iteration when implementing.
• Prefer deepening modules (pretty render seam separate from typecheck; TUI crate behind a clean data-source trait).
• LSP JSON-RPC stays unstyled / protocol-correct; pretty is CLI-only.
• Screenshot targets until showcase exists: tm-buffer-time (~18 diags), tm-better-totd (~22), fixture tm-dashboard (~66). Avoid E++ (700+) for hero shots.
• Hold 0.3.1 until screenshots + this path are ready; crates.io Trusted Publishing already fixed on master (crates-io-auth-action).
• ChatGPT caret mock is the visual north star for pretty check (not boxes as the product).

Decisions so far

Not yet specified

• Exact caret excerpt algorithm (context lines, tab width, unicode columns, multi-span diags).
• Frame/border style tokens (unicode light box vs minimal rules vs no box).
• Mock TuiDataSource trait surface (events, cancel, incremental vs full recheck).
• Snapshot harness choice for ratatui-class TUIs.
• Whether pretty renderer is shared 100% between one-shot check and watch TUI or thin adapters.
• CI matrix cost for showcase fixture + TUI snapshots.
• How --watch chooses workspace root / plugins-dir / typedb (inherit all check flags?).

Out of scope

• Full multi-pane IDE TUI (file tree, hover preview, multi-tab) — tracked separately as future wayfinding, not this destination.
• Go throwaway TUI prototype (decided: Rust-only crate).
• Changing LSP protocol diagnostics payload for pretty (pretty is a CLI view over existing diagnostics).
• Publishing 0.3.1 before screenshots land.

[XertroV]

Charting note (operator)

Bare invocation: if run with no subcommand in a TTY and the cwd (or ancestors) is a plugin workspace (info.toml), default to the watch TUI on that plugin — not LSP stdio.

Editors still get LSP because they attach non-TTY pipes to stdio. Explicit openplanet-lsp with piped stdio / non-TTY remains the language server.

Fold into launch/entrypoint tickets.

[XertroV]

Frontier tickets (charting)

#	Title	Type	Blocked by
#10	Research: Rust TUI stack + snapshot/e2e	research	—
#11	Research: cross-platform file watch	research	—
#12	Grill: pretty diagnostic excerpt + frame	grilling	—
#13	Grill: CLI entrypoints bare TTY / check --watch / LSP	grilling	—
#16	Prototype: showcase-diags fixture	prototype	—
#14	Prototype: pretty check caret renderer	prototype	#12
#15	Prototype: openplanet-lsp-tui + mock backend	prototype	#10 #11 #13
#17	Task: README screenshots	task	#14

Future (out of this map): #9

Screenshot plugins now: tm-buffer-time (18), tm-better-totd (22), fixture tm-dashboard (66).

[XertroV]

Decisions so far (update)

• Research: Rust TUI stack + snapshot/e2e — ratatui 0.30 + crossterm + TestBackend + insta; workspace crate crates/openplanet-lsp-tui; mock TuiDataSource first.

[XertroV]

Decisions so far (update)

• Research: cross-platform file watch — notify 8 + notify-debouncer-mini (~200ms); watch in binary adapter; filter *.as/info.toml; single-flight + dirty coalesce.

[XertroV]

Decisions so far (update)

• Grill: CLI entrypoints — bare TTY+plugin → watch TUI; bare TTY+no plugin → help exit 2; non-TTY → LSP; --lsp and lsp force server; check --watch walk-up; watch inherits typedb/plugins; --format is one-shot only (TUI always rich).

[XertroV]

Decisions so far (update)

• Grill: pretty diagnostic excerpt + frame — caret + gutter excerpts; no CLI box frame (TUI owns chrome); tab=4; crude cols v1; --format plain|pretty|auto.

[XertroV]

Decisions so far (update)

• Bare TTY default mode is config-controllable (~/.config/openplanet-lsp/config.toml); default = tui. First-run modal to lock preference tracked as a future issue (not map Wayfind: pretty check + watch TUI + showcase fixture (toward check --watch) #8 destination).

[XertroV]

Decisions so far (update)

• Prototype: pretty check caret renderer — landed master; caret/gutter; no frame.
• Prototype: showcase-diags fixture — landed; ~23 curated diags.

Remaining on map

• #15 TUI crate + mock backend (unblocked: Research: Rust TUI stack + snapshot/e2e options for watch mode #10 Research: cross-platform file watch for check --watch #11 Grill: CLI entrypoints — bare TTY TUI, check --watch, LSP stdio #13 closed)
• #17 Screenshots task
• Config first-run modal: #19 (future, not destination)

[XertroV]

Decisions so far (update)

• Research batch Research: Rust TUI stack + snapshot/e2e options for watch mode #10/Research: cross-platform file watch for check --watch #11 confirmed (ratatui+insta; notify 8 + debouncer; prefer debouncer-full @ ~300ms when wiring).
• Prototype: openplanet-lsp-tui — landed crate + snapshots. Next: wire check --watch + bare TTY entrypoints (Grill: CLI entrypoints — bare TTY TUI, check --watch, LSP stdio #13) and screenshots (Task: capture README screenshots after pretty check lands #17).

[XertroV]

Decisions so far (update)

• TUI crate refined on master (34b47ba): green tests; ready for check --watch adapter next.