cctx-cli 0.1.0__py3-none-any.whl

cctx/renderers/terminal.py

@@ -0,0 +1,251 @@
+"""Terminal renderer for autopsy Diagnosis output.
+
+render_diagnosis(diagnosis, console=None) -> None
+render_aggregate(report, console=None) -> None
+render_harvest_results(results, dry_run=False, console=None) -> None
+render_projects(projects, console=None) -> None
+render_sessions(project, console=None) -> None
+
+Uses rich for formatting. Accepts an optional Console for testing.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.rule import Rule
+from rich.syntax import Syntax
+from rich.table import Table
+from rich.text import Text
+
+from cctx.models import FindingKind, Severity
+
+if TYPE_CHECKING:
+    from cctx.discovery import ProjectInfo
+    from cctx.models import AggregateReport, Diagnosis
+
+_SEVERITY_STYLE = {
+    Severity.HIGH:   "bold red",
+    Severity.MEDIUM: "bold yellow",
+    Severity.LOW:    "bold green",
+}
+
+_KIND_LABEL = {
+    FindingKind.RETRY_LOOP:    "RETRY LOOP",
+    FindingKind.SCOPE_CREEP:   "SCOPE CREEP",
+    FindingKind.STALE_CONTEXT: "STALE CONTEXT",
+}
+
+
+def _default_console() -> Console:
+    return Console()
+
+
+def render_diagnosis(
+    diagnosis: Diagnosis,
+    *,
+    session_path: Path | None = None,
+    console: Console | None = None,
+) -> None:
+    con = console or _default_console()
+
+    # Header
+    con.print(Rule(f"cctx autopsy — session {diagnosis.session_id}"))
+    cost_line = f"Session cost: ${diagnosis.total_cost_usd:.2f}"
+    if diagnosis.waste_cost_usd > 0:
+        pct = (
+            diagnosis.waste_cost_usd / diagnosis.total_cost_usd * 100
+            if diagnosis.total_cost_usd
+            else 0
+        )
+        cost_line += f" | Attributed waste: ${diagnosis.waste_cost_usd:.2f} ({pct:.0f}%)"
+    con.print(cost_line)
+
+    if not diagnosis.findings:
+        con.print("\nNo findings — session looks clean.")
+        return
+
+    con.print(f"Inflection turn: {diagnosis.inflection_turn}")
+    con.print()
+
+    # Findings
+    for finding in diagnosis.findings:
+        style = _SEVERITY_STYLE.get(finding.severity, "")
+        label = _KIND_LABEL.get(finding.kind, finding.kind.value.upper())
+        badge = Text(f" {label} ", style=style)
+        conf_note = f"({finding.confidence.value} confidence)"
+        con.print(badge, conf_note, "—", finding.summary)
+
+    # Patches
+    if diagnosis.patches:
+        con.print()
+        con.print(Rule("CLAUDE.md patches"))
+        for patch in diagnosis.patches:
+            con.print(f"\n{patch.description}  [{patch.target_file}]")
+            con.print(f"Evidence: {patch.evidence_summary}")
+            syntax = Syntax(patch.unified_diff, "diff", theme="monokai", word_wrap=True)
+            con.print(syntax)
+
+    if session_path is not None:
+        con.print()
+        con.print(
+            Text("cctx trace ", style="bold")
+            + Text(str(session_path), style="dim")
+            + Text("  to step through this session interactively", style="dim")
+        )
+
+
+def render_aggregate(report: AggregateReport, *, console: Console | None = None) -> None:
+    con = console or _default_console()
+
+    days = int(report.window.total_seconds() / 86400)
+    con.print(Rule(f"cctx autopsy — last {days} days"))
+    con.print(
+        f"Sessions: {report.sessions_analysed} analysed, "
+        f"{report.sessions_with_findings} with findings"
+    )
+    con.print(
+        f"Total cost: ${report.total_cost_usd:.2f} | "
+        f"Waste: ${report.waste_cost_usd:.2f}"
+    )
+
+    if not report.by_kind:
+        con.print("\nNo findings across sessions.")
+        return
+
+    # Summary table
+    table = Table(title="Finding frequency")
+    table.add_column("Pattern")
+    table.add_column("Sessions", justify="right")
+    table.add_column("Waste ($)", justify="right")
+    for kind, ev in report.by_kind.items():
+        table.add_row(
+            _KIND_LABEL.get(kind, kind.value),
+            str(ev.session_count),
+            f"${ev.total_waste_usd:.2f}",
+        )
+    con.print(table)
+
+    # Patches
+    if report.patches:
+        con.print(Rule("Recommended CLAUDE.md patches"))
+        for patch in report.patches:
+            con.print(f"\n{patch.description}")
+            syntax = Syntax(patch.unified_diff, "diff", theme="monokai", word_wrap=True)
+            con.print(syntax)
+
+
+def render_harvest_results(
+    results: list,  # list[ApplyResult] — ApplyStatus is harvest-internal; imported lazily
+    *,
+    dry_run: bool = False,
+    console: Console | None = None,
+) -> None:
+    """Render harvest ApplyResult list to terminal."""
+    from cctx.harvest import ApplyStatus
+
+    con = console or _default_console()
+
+    if not results:
+        con.print("No patches to apply. Session looks clean.")
+        return
+
+    total = len(results)
+    for i, result in enumerate(results, start=1):
+        if result.status == ApplyStatus.SKIPPED:
+            con.print(
+                Text(
+                    f"already present ({result.message.removeprefix('already present: ')}) "
+                    f"— skipping",
+                    style="dim",
+                )
+            )
+            continue
+
+        if result.status == ApplyStatus.APPLIED:
+            title_style = "green"
+        elif result.status == ApplyStatus.ERROR:
+            title_style = "red"
+        else:
+            title_style = "dim"
+        title = f"Patch {i} of {total} — {result.patch.finding_kind.value}"
+        syntax = Syntax(result.patch.unified_diff, "diff", theme="monokai", word_wrap=True)
+        panel = Panel(
+            syntax,
+            title=title,
+            title_align="left",
+            border_style=title_style,
+            subtitle=Text(result.patch.evidence_summary, style="dim"),
+            subtitle_align="left",
+        )
+        con.print(panel)
+
+    applied_count = sum(1 for r in results if r.status == ApplyStatus.APPLIED)
+    if dry_run:
+        con.print("Dry run complete. No changes made.")
+    else:
+        con.print(f"Applied {applied_count} patch(es).")
+
+
+def render_projects(projects: list[ProjectInfo], *, console: Console | None = None) -> None:
+    con = console or _default_console()
+
+    if not projects:
+        con.print("No projects found in ~/.claude/projects/.")
+        return
+
+    con.print(Rule("cctx — projects"))
+    table = Table(show_header=True, box=None, pad_edge=False, show_edge=False)
+    table.add_column("Project", style="bold")
+    table.add_column("Sessions", justify="right", style="dim")
+    table.add_column("Last session", style="dim")
+
+    for proj in projects:
+        last = proj.latest_time.strftime("%Y-%m-%d") if proj.latest_time else "—"
+        table.add_row(
+            proj.display_name,
+            str(proj.session_count),
+            last,
+        )
+    con.print(table)
+    con.print()
+    con.print(
+        Text("cctx ls <project-path>", style="bold") +
+        Text("  to list sessions in a project", style="dim")
+    )
+    con.print(
+        Text("cctx autopsy --latest <project-path>", style="bold") +
+        Text("  to diagnose the most recent session", style="dim")
+    )
+
+
+def render_sessions(project: ProjectInfo, *, console: Console | None = None) -> None:
+    con = console or _default_console()
+
+    con.print(Rule(f"cctx — {project.display_name}"))
+    if not project.sessions:
+        con.print("No sessions found.")
+        return
+
+    table = Table(show_header=True, box=None, pad_edge=False, show_edge=False)
+    table.add_column("Session", style="bold")
+    table.add_column("Date", style="dim")
+    table.add_column("Branch", style="dim")
+    table.add_column("Path", style="dim")
+
+    for s in project.sessions:
+        date_str = s.start_time.strftime("%Y-%m-%d %H:%M") if s.start_time else "—"
+        table.add_row(
+            s.session_id[:8],
+            date_str,
+            s.git_branch or "—",
+            str(s.path),
+        )
+    con.print(table)
+    con.print()
+    con.print(
+        Text("cctx autopsy <path>", style="bold") +
+        Text("  to diagnose a session", style="dim")
+    )

cctx/renderers/trace_tui.py

@@ -0,0 +1,291 @@
+"""Textual TUI for trace visualization with autopsy overlay.
+
+Public API:
+    affected_turns(finding, trace) -> frozenset[int]
+    verdict(diagnosis) -> str
+    launch(trace, diagnosis) -> None
+
+Internal:
+    _build_flagged_index(findings, trace) -> dict[int, list[Finding]]
+
+Textual is only imported inside launch() so that the pure helpers remain
+importable without the textual package (e.g. during testing).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from cctx.models import FindingKind
+
+if TYPE_CHECKING:
+    from cctx.models import Diagnosis, Finding, SessionTrace, Turn
+
+
+# ---------------------------------------------------------------------------
+# Pure helpers — no Textual dependency
+# ---------------------------------------------------------------------------
+
+
+def affected_turns(finding: Finding, trace: SessionTrace) -> frozenset[int]:
+    """Return turn numbers covered by a finding using per-kind evidence extraction."""
+    ev = finding.evidence or {}
+    kind = finding.kind
+
+    if kind is FindingKind.RETRY_LOOP:
+        turns: set[int] = {occ["turn"] for occ in ev.get("occurrences", []) if "turn" in occ}
+    elif kind is FindingKind.SCOPE_CREEP:
+        turns = {ph["turn"] for ph in ev.get("phrases", []) if "turn" in ph}
+    elif kind is FindingKind.STALE_CONTEXT:
+        last = finding.last_turn if finding.last_turn is not None else finding.first_turn
+        turns = set()
+        for item in ev.get("stale_items", []):
+            if "last_referenced_turn" in item:
+                turns.update(range(item["last_referenced_turn"] + 1, last + 1))
+    else:
+        last = finding.last_turn if finding.last_turn is not None else finding.first_turn
+        turns = set(range(finding.first_turn, last + 1))
+
+    return frozenset(turns) if turns else frozenset({finding.first_turn})
+
+
+def verdict(diagnosis: Diagnosis) -> str:
+    """One-line human summary: 'Clean session' or '{n} finding(s) · ${waste:.2f} waste'."""
+    if not diagnosis.findings:
+        return "Clean session"
+    n = len(diagnosis.findings)
+    label = "finding" if n == 1 else "findings"
+    return f"{n} {label} · ${diagnosis.waste_cost_usd:.2f} waste"
+
+
+def _build_flagged_index(findings: list[Finding], trace: SessionTrace) -> dict[int, list[Finding]]:
+    """Map turn_number -> list of findings that affect that turn."""
+    index: dict[int, list[Finding]] = {}
+    for finding in findings:
+        for tn in affected_turns(finding, trace):
+            index.setdefault(tn, []).append(finding)
+    return index
+
+
+# ---------------------------------------------------------------------------
+# Entry point — Textual imports deferred here
+# ---------------------------------------------------------------------------
+
+
+def launch(trace: SessionTrace, diagnosis: Diagnosis) -> None:  # noqa: C901
+    """Build and run the Textual app (blocking). Imports textual on first call."""
+    from textual.app import App, ComposeResult
+    from textual.binding import Binding
+    from textual.containers import ScrollableContainer
+    from textual.screen import ModalScreen
+    from textual.widgets import DataTable, Footer, Header, Label, Static
+
+    flagged = _build_flagged_index(diagnosis.findings, trace)
+    session_verdict = verdict(diagnosis)
+
+    class FindingModal(ModalScreen):  # type: ignore[type-arg]
+        """Finding details for the selected turn."""
+
+        DEFAULT_CSS = """
+        FindingModal {
+            align: center middle;
+            width: 80%;
+            height: 80%;
+        }
+        FindingModal > ScrollableContainer {
+            background: $surface;
+            border: solid $accent;
+            padding: 1 2;
+        }
+        """
+
+        BINDINGS = [
+            Binding("escape", "dismiss", "Close"),
+            Binding("q", "dismiss", "Close"),
+        ]
+
+        def __init__(self, findings: list[Finding]) -> None:
+            super().__init__()
+            self._findings = findings
+
+        def compose(self) -> ComposeResult:
+            lines: list[str] = []
+            for f in self._findings:
+                lines.append(
+                    f"[bold]{f.kind.value}[/]  severity={f.severity.value}"
+                    f"  confidence={f.confidence.value}"
+                )
+                lines.append(f"  {f.summary}")
+                if f.cost_usd is not None:
+                    lines.append(f"  cost: ${f.cost_usd:.4f}")
+                lines.append("")
+            text = "\n".join(lines).rstrip() or "No findings."
+            with ScrollableContainer():
+                yield Label(text, markup=True)
+
+    class ToolResultModal(ModalScreen):  # type: ignore[type-arg]
+        """Turn content and tool results for the selected turn."""
+
+        DEFAULT_CSS = """
+        ToolResultModal {
+            align: center middle;
+            width: 80%;
+            height: 80%;
+        }
+        ToolResultModal > ScrollableContainer {
+            background: $surface;
+            border: solid $accent;
+            padding: 1 2;
+        }
+        """
+
+        BINDINGS = [
+            Binding("escape", "dismiss", "Close"),
+            Binding("q", "dismiss", "Close"),
+        ]
+
+        def __init__(self, selected_turn: Turn) -> None:
+            super().__init__()
+            self._turn = selected_turn
+
+        def compose(self) -> ComposeResult:
+            t = self._turn
+            lines: list[str] = [f"[bold]Turn {t.turn_number}[/] — {t.role}", ""]
+            if t.text:
+                preview = t.text[:2000]
+                if len(t.text) > 2000:
+                    preview += "\n[dim]…truncated[/]"
+                lines.append(preview)
+                lines.append("")
+            for tr in t.tool_results:
+                lines.append(f"[bold]{tr.tool_name}[/] ({tr.tool_use_id})")
+                content_preview = tr.content[:1000]
+                if len(tr.content) > 1000:
+                    content_preview += "\n[dim]…truncated[/]"
+                lines.append(content_preview)
+                lines.append("")
+            if not t.text and not t.tool_results:
+                lines.append("[dim](no content)[/]")
+            with ScrollableContainer():
+                yield Label("\n".join(lines), markup=True)
+
+    class HelpScreen(ModalScreen):  # type: ignore[type-arg]
+        """Keyboard shortcut reference."""
+
+        DEFAULT_CSS = """
+        HelpScreen {
+            align: center middle;
+            width: 60%;
+            height: 60%;
+        }
+        HelpScreen > ScrollableContainer {
+            background: $surface;
+            border: solid $accent;
+            padding: 1 2;
+        }
+        """
+
+        BINDINGS = [
+            Binding("escape", "dismiss", "Close"),
+            Binding("q", "dismiss", "Close"),
+            Binding("question_mark", "dismiss", "Close"),
+        ]
+
+        def compose(self) -> ComposeResult:
+            help_text = (
+                "[bold]cctx trace — keyboard shortcuts[/]\n\n"
+                "  [bold]↑ / ↓[/]    Navigate turns\n"
+                "  [bold]Enter[/]    Show turn content / tool results\n"
+                "  [bold]f[/]        Show finding details (flagged turns only)\n"
+                "  [bold]?[/]        Toggle this help screen\n"
+                "  [bold]q[/]        Quit\n"
+            )
+            with ScrollableContainer():
+                yield Label(help_text, markup=True)
+
+    class TraceTUI(App):  # type: ignore[type-arg]
+        """Interactive turn-by-turn trace viewer with autopsy overlay."""
+
+        DEFAULT_CSS = """
+        DataTable { height: 1fr; }
+        #verdict { height: 1; background: $accent; color: $text; padding: 0 1; }
+        """
+
+        BINDINGS = [
+            Binding("q", "quit", "Quit"),
+            Binding("f", "show_finding", "Finding"),
+            Binding("question_mark", "show_help", "Help"),
+        ]
+
+        def __init__(self) -> None:
+            super().__init__()
+            self._turn_numbers: list[int] = []
+
+        def compose(self) -> ComposeResult:
+            yield Header()
+            yield DataTable(id="turns", cursor_type="row")
+            yield Static(session_verdict, id="verdict")
+            yield Footer()
+
+        def on_mount(self) -> None:
+            table = self.query_one("#turns", DataTable)
+            table.add_column("#", width=6)
+            table.add_column("Role", width=14)
+            table.add_column("Model", width=22)
+            table.add_column("Tokens", width=10)
+            table.add_column("Flags", width=22)
+
+            for t in trace.turns:
+                is_flagged = t.turn_number in flagged
+                findings = flagged.get(t.turn_number, [])
+                tokens = (
+                    f"{t.usage.input_tokens + t.usage.cache_creation_5m + t.usage.cache_creation_1h + t.usage.cache_read:,}"
+                    if t.usage
+                    else ""
+                )
+                model = t.model or ""
+                flags = ", ".join(f.kind.value for f in findings)
+
+                if is_flagged:
+                    cells = [
+                        f"[bold red]{t.turn_number}[/]",
+                        f"[bold red]{t.role}[/]",
+                        f"[red]{model}[/]",
+                        f"[red]{tokens}[/]",
+                        f"[bold red]{flags}[/]",
+                    ]
+                else:
+                    cells = [str(t.turn_number), t.role, model, tokens, flags]
+
+                table.add_row(*cells)
+                self._turn_numbers.append(t.turn_number)
+
+        def _current_turn_number(self) -> int | None:
+            table = self.query_one("#turns", DataTable)
+            idx = table.cursor_row
+            if idx < 0 or idx >= len(self._turn_numbers):
+                return None
+            return self._turn_numbers[idx]
+
+        def on_data_table_row_selected(self, event: DataTable.RowSelected) -> None:
+            idx = event.cursor_row
+            if idx < 0 or idx >= len(self._turn_numbers):
+                return
+            turn_number = self._turn_numbers[idx]
+            selected = next((t for t in trace.turns if t.turn_number == turn_number), None)
+            if selected is not None:
+                self.push_screen(ToolResultModal(selected))
+
+        def action_show_finding(self) -> None:
+            tn = self._current_turn_number()
+            if tn is None:
+                return
+            findings = flagged.get(tn)
+            if not findings:
+                return
+            self.push_screen(FindingModal(findings))
+
+        def action_show_help(self) -> None:
+            self.push_screen(HelpScreen())
+
+    TraceTUI().run()

cctx/tokenizer.py

@@ -0,0 +1,77 @@
+"""cctx tokenizer.
+
+The ONLY module in cctx allowed to import `anthropic`. Wraps
+anthropic.messages.count_tokens() and walks a parsed SessionTrace,
+populating token_count fields on Turns, ToolUses, and ToolResults.
+
+Honors CCTX_OFFLINE=1 to skip live API calls and use a len(text)//4
+heuristic instead — useful for CI, air-gapped environments, or quick
+relative-proportion estimates.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+from cctx.models import SessionTrace, Turn
+
+
+def tokenize_session(trace: SessionTrace) -> SessionTrace:
+    """Walk a SessionTrace and populate token_count fields in place. Returns the same trace."""
+    counter = _build_counter()
+    _tokenize_trace_recursively(trace, counter)
+    return trace
+
+
+def _build_counter():
+    """Return a callable str -> int. Heuristic in offline mode; live API otherwise."""
+    if os.environ.get("CCTX_OFFLINE") == "1":
+        return _heuristic_token_count
+    return _make_live_counter()
+
+
+def _heuristic_token_count(text: str) -> int:
+    return len(text) // 4
+
+
+def _make_live_counter():
+    api_key = os.environ.get("ANTHROPIC_API_KEY")
+    if not api_key:
+        return _heuristic_token_count
+    import anthropic  # lazy: offline mode never loads the SDK
+
+    client = anthropic.Anthropic(api_key=api_key)
+    cache: dict[str, int] = {}
+
+    def count(text: str) -> int:
+        if text in cache:
+            return cache[text]
+        result = client.messages.count_tokens(
+            model="claude-sonnet-4-5",
+            messages=[{"role": "user", "content": text or " "}],
+        )
+        n = result.input_tokens
+        cache[text] = n
+        return n
+
+    return count
+
+
+def _tokenize_trace_recursively(trace: SessionTrace, counter) -> None:
+    for turn in trace.turns:
+        _tokenize_turn(turn, counter)
+    for child in trace.subagents:
+        _tokenize_trace_recursively(child, counter)
+
+
+def _tokenize_turn(turn: Turn, counter) -> None:
+    narrative = ((turn.text or "") + ("\n" + turn.thinking if turn.thinking else "")).strip()
+    if narrative:
+        turn.token_count = counter(narrative)
+
+    for use in turn.tool_uses:
+        use.token_count = counter(json.dumps(use.tool_input, sort_keys=True))
+
+    for result in turn.tool_results:
+        result.token_count = counter(result.content or "")