relayburn-cli: burn summary + hotspots presenters (#248 D1)

[willwashburn]

Summary

• Implement burn summary and burn hotspots as thin presenters over relayburn_sdk::summary / ::hotspots, matching the TS CLI flag set + output byte-for-byte.
• Un-ignore the summary / summary-json / hotspots / hotspots-json golden invocations.

Test plan

• cargo test --workspace
• BURN_GOLDEN=1 cargo test --test golden -p relayburn-cli (4 entries pass)
• burn summary --help / burn hotspots --help match TS flag set

🤖 Generated with Claude Code

[coderabbitai]

Caution

Review failed

Failed to post review comments

📝 Walkthrough

Walkthrough

The PR implements two CLI commands (summary and hotspots) as thin presenters over relayburn-sdk. It introduces payload-bearing Command enum variants with per-command argument structs, adds full implementations with JSON and human-readable output formatting, includes formatting helpers aligned with the TypeScript CLI, updates test infrastructure to bootstrap SQLite from JSONL ledger events, and enables corresponding golden test invocations.

Changes

Summary and Hotspots CLI Commands

Layer / File(s)	Summary
CLI Argument Shape crates/relayburn-cli/src/cli.rs, crates/relayburn-cli/src/commands/summary.rs, crates/relayburn-cli/src/commands/hotspots.rs	Summary and Hotspots enum variants converted from unit-like to payload-bearing, carrying SummaryArgs and HotspotsArgs structs respectively. Each Args struct declares per-command flags (since, project, session, provider, by-tool, by-subagent-type, etc.).
Core Command Logic crates/relayburn-cli/src/commands/summary.rs	Implements full summary workflow: opens ledger, ingests sessions, builds queries, aggregates by model or provider, computes cost/fidelity/replacement-savings via SDK, and routes to JSON or human output. Validates flag mutual exclusivity and deprecated features.
Core Command Logic crates/relayburn-cli/src/commands/hotspots.rs	Implements full hotspots workflow: opens ledger, ingests data, computes per-source coverage breakdown, fetches hotspots via SDK, and renders output in JSON or human-readable format with per-file, per-bash, per-subagent detail.
Output Formatting Infrastructure crates/relayburn-cli/src/render/format.rs, crates/relayburn-cli/src/render/mod.rs	Adds formatting helpers (format_usd, format_int, format_uint, render_table, coerce_whole_f64_to_int) matching TS CLI style; modularized into new format.rs and exported via mod.rs.
JSON & Human Rendering crates/relayburn-cli/src/commands/summary.rs, crates/relayburn-cli/src/commands/hotspots.rs	Both commands include separate emit_json and emit_human entrypoints with JSON serialization helpers (cost_breakdown_to_json, fidelity_summary_to_json, replacement_savings_to_json, etc.) and rich human-readable table rendering with coverage markers, notices, and per-row metrics.
Dispatch & Integration crates/relayburn-cli/src/main.rs, crates/relayburn-sdk/src/lib.rs, crates/relayburn-cli/Cargo.toml	Main.rs dispatch logic destructures payload from Command variants and passes to updated run() signatures. SDK exports new AggregateByProviderOptions type. Cargo.toml adds indexmap dependency with serde feature.
Test Bootstrap & Enablement crates/relayburn-cli/tests/golden.rs, crates/relayburn-cli/tests/smoke.rs, tests/fixtures/cli-golden/invocations.json, tests/fixtures/cli-golden/ledger/.gitignore	Adds bootstrap_sqlite_from_jsonl() to replay ledger.jsonl into SQLite; normalizes tool_result events and constructs Stamps for SDK ingestion. Smoke tests updated to track UNIMPLEMENTED_SUBCOMMANDS separately. Four golden invocations (summary, summary-json, hotspots, hotspots-json) moved from disabled to enabled. .gitignore expanded to cover content.sqlite and archive.sqlite variants.
Documentation CHANGELOG.md	Unreleased entry documents relayburn-cli wiring to relayburn-sdk with thin presenter pattern, parity with TS CLI flags and stdout behavior, and golden test enablement.

Sequence Diagram

sequenceDiagram
    actor User
    participant CLI as CLI Dispatcher
    participant Presenter as Summary/Hotspots Presenter
    participant SDK as relayburn-sdk
    participant Ledger as SQLite Ledger
    participant Render as Formatter/Renderer

    User->>CLI: run burn summary/hotspots [flags]
    CLI->>Presenter: dispatch with parsed Args
    Presenter->>Ledger: open ledger (burn.sqlite)
    Presenter->>SDK: ingest sessions via RawLedger
    Presenter->>SDK: build query (session/project/since filter)
    Presenter->>Ledger: fetch turns matching query
    Presenter->>SDK: aggregate by model/provider OR compute hotspots
    SDK-->>Presenter: aggregated rows / hotspots result
    
    alt JSON output mode
        Presenter->>Render: serialize to JSON (cost, fidelity, attribution)
    else Human output mode
        Presenter->>Render: format tables with coverage cells
        Presenter->>Render: format USD costs with locale separators
        Render-->>Presenter: formatted strings
    end
    
    Presenter-->>Render: rendered output
    Render-->>CLI: emit to stdout
    CLI-->>User: display summary/hotspots

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related issues

• AgentWorkforce/burn#248: Implements the Rust CLI porting work (clap-based Command enum variants, payload-bearing Summary/Hotspots args, run() signatures, presenters, tests, and wiring).

Possibly related PRs

• AgentWorkforce/burn#291: The hotspots CLI command implementation directly consumes the hotspots aggregation surface (attributions/aggregations) exported by this PR.
• AgentWorkforce/burn#310: Main PR extends the cli-golden test harness and fixtures by implementing Summary/Hotspots CLI commands, enabling golden invocations, and adding ledger bootstrap logic.
• AgentWorkforce/burn#301: The CLI Summary and Hotspots commands directly use the SDK-level summary and hotspots query verbs implemented in this PR.

Poem

🐰 A hop and a squeal—the presenters arise!
From thin wires to tables, with cost-column eyes,
JSON flows softly, humanity shines,
Bootstrap the ledger in SQLite's lines!
Four golden tests now skip no more—
Relayburn-cli stats adorn the store! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: implementing burn summary and hotspots as presenters in the relayburn-cli.
Description check	✅ Passed	The description is directly related to the changeset, detailing the implementation of burn summary and hotspots presenters, flag matching, and golden test enablement with test plan confirmation.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch rust-port/cli-summary-hotspots

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[chatgpt-codex-connector]

💡 Codex Review

burn/crates/relayburn-cli/src/commands/hotspots.rs

Lines 752 to 756 in ec40249

	let source_label = if missing_fields.contains(&"tool-result events") {
	"codex"
	} else {
	"claude-code"
	};

Preserve source attribution in hotspots coverage notice

The coverage notice hard-codes a single source label (codex vs claude-code) from aggregate missing-field stats, so any slice with excluded turns from multiple source kinds will produce a misleading explanation (for example, excluded Claude and OpenCode turns can still be reported as only codex). This affects user diagnosis of why attribution was excluded because the message no longer matches the actual source mix that hotspots processed.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[willwashburn]

Addressed in e50f490 — the hotspots presenter now re-walks the matched-window turns itself to build a per-SourceKind describeExcluded-style breakdown, then renders one inline clause per source joined with " and " (same shape as the TS CLI). This drops the brittle "any tool-result-events missing → codex; otherwise claude-code" heuristic the previous version used. JSON output is unchanged (the TS --json shape doesn't carry the per-source breakdown).