# Phase 16.2: BUGSWEEPER Live Debugging Framework - Context

**Gathered:** 2026-03-24
**Status:** Ready for planning

<domain>
## Phase Boundary

Build BUGSWEEPER — a modular live debugging framework that gives Claude Code agents full programmatic control over the running Slint frontend. Agents can inspect UI state, read/write Slint properties, invoke callbacks, query application data, and capture screenshots — enabling fully autonomous testing, debugging, and UAT rounds without human interaction. The framework must be feature-gated so it adds zero overhead to production builds.

</domain>

<decisions>
## Implementation Decisions

### Communication Protocol
- HTTP/REST debug server on localhost (e.g., `127.0.0.1:9876`) with JSON request/response
- Agents interact via standard bash `curl` commands — no special client binary needed
- Server runs on a background thread; UI operations dispatched to Slint main loop via `slint::invoke_from_event_loop()`
- Responses are synchronous JSON — agent sends command, blocks until result returns
- Server only binds to loopback (127.0.0.1) — never exposed to network
- Use `tiny_http` or equivalent minimal HTTP crate — no heavy framework

### Scope of Frontend Control
- **Property reads**: Read any DashboardWindow property value (cards, search-text, active-mode-index, toast-message, etc.)
- **Property writes**: Set any writable property (search-text, active-mode-index, show-archived, etc.)
- **Callback invocation**: Trigger any DashboardWindow callback (on-refresh-all, on-card-clicked, on-tab-clicked, on-search-changed, etc.)
- **Model inspection**: Read the full `cards` model as JSON array — every CardData field serialized
- **Model mutation**: Update individual card properties or replace the entire cards model
- **State queries**: Query DashboardRuntime state (discovery mode, archive store, edit queue, card UI states)
- **Toast/notification control**: Trigger and read toast messages for verification
- **Window info**: Read window dimensions, title, visibility state

### Module Architecture
- New workspace crate: `crates/bugsweeper/` — contains HTTP server, command router, serialization
- Feature-gated in `crates/app/Cargo.toml`: `bugsweeper = ["dep:bugsweeper"]`
- Core app impact is minimal: `main.rs` gets ~10 lines behind `#[cfg(feature = "bugsweeper")]` to start the server
- BUGSWEEPER receives a handle to DashboardWindow + Arc references to shared state (SqliteStore, AppConfig, DashboardRuntime)
- The `bugsweeper` crate depends on `slint` (for Window handle types) and `serde_json` (for serialization)
- Build command: `cargo build --features bugsweeper` — normal builds are unaffected
- Environment variable `BUGSWEEPER_PORT` overrides the default port

### Data Access Strategy
- **Dual-path approach**: SQLite direct reads for data layer + Slint API for UI state
- SQLite: BUGSWEEPER opens its own read-only connection to `witwhat.db` (WAL mode allows concurrent readers)
- Slint API: Properties and model data read via the DashboardWindow handle through `invoke_from_event_loop`
- Endpoint groups:
  - `/api/ui/*` — Slint property reads/writes, callback invocation, model inspection
  - `/api/data/*` — Direct SQLite queries (recipients, cards, products, notes, archive records)
  - `/api/state/*` — DashboardRuntime inspection (discovery state, edit queue, card UI states)
  - `/api/app/*` — App-level info (config, connection status, sync state, window info)
  - `/api/debug/*` — Diagnostic endpoints (health check, version, endpoint listing)

### Agent Workflow Support
- `GET /api/debug/health` — Quick liveness check (agents verify app is running before test suite)
- `GET /api/ui/cards` — Full card model dump as JSON (primary data for UAT assertions)
- `POST /api/ui/callback` — Invoke named callback with args (simulate user actions)
- `GET /api/ui/property/{name}` — Read a specific Slint property
- `PUT /api/ui/property/{name}` — Write a Slint property
- `GET /api/data/query` — Run a read-only SQL query against the database
- `GET /api/state/discovery` — Current discovery mode, filters, search text
- `GET /api/state/archive` — Archive store state for all cards
- Screenshot capture is handled externally by Claude Code's screenshot tool — BUGSWEEPER does not need to implement screenshotting

### Claude's Discretion
- Exact HTTP crate selection (tiny_http, warp, or axum — whichever is lightest)
- JSON serialization approach for Slint types (custom or via intermediate structs)
- Error response format and HTTP status code conventions
- Endpoint naming details beyond the groups defined above
- Whether to add a simple HTML debug dashboard (nice-to-have, not required)
- Thread synchronization details for invoke_from_event_loop result passing

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### App architecture
- `crates/app/src/main.rs` — App entry point, DashboardWindow setup, callback wiring (BUGSWEEPER hooks in here)
- `crates/app/src/dashboard/mod.rs` — DashboardView, DashboardRuntime, all re-exports (primary state target)
- `crates/app/src/dashboard/view_model.rs` — DashboardCardViewModel struct (must be serializable for /api/ui/cards)
- `crates/app/src/service_client.rs` — RecipientCardSnapshot, DashboardDataClient trait (data layer types)
- `crates/app/src/live_client.rs` — LiveClient with SqliteStore (sync and data access)

### Slint UI
- `crates/app/ui/dashboard.slint` — DashboardWindow component, CardData struct, all properties and callbacks
- `crates/app/ui/card.slint` — RecipientCard component, ItemSquareData
- `crates/app/ui/tokens.slint` — Colors and Typography globals

### Data layer
- `.planning/DATA-FLOW.md` — Authoritative data architecture reference (mandatory read per CLAUDE.md)
- `crates/service/src/db/sqlite.rs` — SqliteStore implementation (BUGSWEEPER opens its own read connection)

### Workspace
- `Cargo.toml` — Workspace members list (add bugsweeper crate here)
- `crates/app/Cargo.toml` — App dependencies and features (add bugsweeper feature gate here)

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- `DashboardCardViewModel` in `dashboard/view_model.rs`: Already has all card fields — needs `Serialize` derive for JSON output
- `DashboardRuntime` in `dashboard/mod.rs`: Comprehensive state access methods (discovery, archive, edit)
- `SqliteStore` in `service/src/db/sqlite.rs`: Uses `Arc<Mutex<Connection>>` with WAL — safe to open a second read-only connection
- `slint::invoke_from_event_loop()`: Thread-safe way to dispatch UI operations from the HTTP server thread
- `RecipientCardSnapshot` in `service_client.rs`: Data transfer type from SQLite to UI pipeline
- Existing `ureq` dependency in app crate: Confirms HTTP library familiarity in the codebase

### Established Patterns
- Feature gates: `crates/app/Cargo.toml` already has a `dashboard-ui` feature — BUGSWEEPER follows the same pattern
- Arc-shared state: Main.rs already wraps SqliteStore and AppConfig in Arc for cross-thread sharing — same handles pass to BUGSWEEPER
- Background threads: Sync thread pattern in main.rs (spawn thread, clone Arc handles) — BUGSWEEPER server thread follows identical pattern
- `#[derive(serde::Serialize)]` already used across the codebase — adding to view model types is consistent

### Integration Points
- `main.rs` after DashboardWindow creation: Start BUGSWEEPER server with window handle + Arc state refs
- `Cargo.toml` workspace members: Add `crates/bugsweeper`
- `crates/app/Cargo.toml` features: Add `bugsweeper` feature with optional dependency
- Build scripts / CI: Add `--features bugsweeper` for debug/development builds

</code_context>

<specifics>
## Specific Ideas

- Framework is named BUGSWEEPER — use this name in crate, module, and log prefixes
- Primary consumer is Claude Code agents running bash commands — every endpoint must be testable with a single `curl` command
- Screenshot-based visual verification is handled by Claude Code's screenshot-capture skill — BUGSWEEPER focuses on data/state access, not image capture
- The framework enables agents to perform complete UAT rounds: launch app with `--features bugsweeper`, hit health endpoint, run through test scenarios via curl, verify state via JSON responses, capture screenshots for visual checks

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope

</deferred>

---

*Phase: 16.2-bugsweeper-live-debugging-framework-for-agent-executed-slint-frontend-testing-and-uat*
*Context gathered: 2026-03-24*