cctx-cli 0.2.0__tar.gz → 1.1.0__tar.gz

{cctx_cli-0.2.0 → cctx_cli-1.1.0}/.github/workflows/publish.yml

@@ -46,18 +46,6 @@ jobs:
 
       - name: Publish
         uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
 
-  tag-action:
-    name: Tag floating action version
-    needs: [publish]
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Push floating major tag
-        run: |
-          MAJOR=$(echo "${{ github.event.release.tag_name }}" | cut -d. -f1)
-          git tag -f "$MAJOR"
-          git push origin "$MAJOR" --force

cctx_cli-1.1.0/.github/workflows/release.yml

@@ -0,0 +1,37 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  release:
+    name: Semantic release
+    runs-on: ubuntu-latest
+    concurrency: release
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.RELEASE_TOKEN }}
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install python-semantic-release
+        run: pip install python-semantic-release
+
+      - name: Compute version and push
+        run: semantic-release version
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+
+      - name: Publish GitHub release
+        run: semantic-release publish
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_TOKEN }}

cctx_cli-1.1.0/CHANGELOG.md

@@ -0,0 +1,97 @@
+# CHANGELOG
+
+<!-- version list -->
+
+## v1.1.0 (2026-05-17)
+
+### Chores
+
+- Add skip-existing to pypi publish action
+  ([`23d7e16`](https://github.com/jacquardlabs/cctx/commit/23d7e16e18074da3c25899ba98298100ad3c1ad3))
+
+### Features
+
+- M9 polish — verdict headline, --top N, --turn N
+  ([#83](https://github.com/jacquardlabs/cctx/pull/83),
+  [`b0d2f27`](https://github.com/jacquardlabs/cctx/commit/b0d2f273a373c5a2f52c9de3a3fb2721da59c4f5))
+
+- M9 polish — verdict headline, --top N, and --turn N
+  ([#83](https://github.com/jacquardlabs/cctx/pull/83),
+  [`b0d2f27`](https://github.com/jacquardlabs/cctx/commit/b0d2f273a373c5a2f52c9de3a3fb2721da59c4f5))
+
+### Refactoring
+
+- Cache verdict, fix markup=False bug, use reverse=True
+  ([#83](https://github.com/jacquardlabs/cctx/pull/83),
+  [`b0d2f27`](https://github.com/jacquardlabs/cctx/commit/b0d2f273a373c5a2f52c9de3a3fb2721da59c4f5))
+
+
+## v1.0.0 (2026-05-17)
+
+### Continuous Integration
+
+- Add python-semantic-release for fully automated CD
+  ([`9844921`](https://github.com/jacquardlabs/cctx/commit/98449213e5b3bd597c47d54e4d5043e245adafe4))
+
+- Add workflow_dispatch to release.yml for manual trigger
+  ([`08ac9f8`](https://github.com/jacquardlabs/cctx/commit/08ac9f80eb6ceee7b57155852febc4274cbaf3b0))
+
+
+## v0.2.0 (2026-05-16)
+
+### Bug Fixes
+
+- Ruff lint — B904, E402, E501, F841 across cli, tests, and renderers
+  ([`fa7105f`](https://github.com/jacquardlabs/cctx/commit/fa7105fef340d89136f1996b86824e30d080a730))
+
+- Trace TUI token sum within line-length limit
+  ([`5b7416c`](https://github.com/jacquardlabs/cctx/commit/5b7416c5b92790cfe66f1e53f20891ecaf6e03b0))
+
+### Chores
+
+- Bump version to 0.2.0, update PRODUCT.md and CLAUDE.md
+  ([`828ed49`](https://github.com/jacquardlabs/cctx/commit/828ed4997df9f4a264669bc38f4b10588a151f1c))
+
+### Documentation
+
+- Add CI usage section clarifying harvest is local-only
+  ([`c526408`](https://github.com/jacquardlabs/cctx/commit/c526408a35749858e1c0b0b6ba42aea95bb8f621))
+
+### Features
+
+- **#64,#63**: Tool-thrash and dead-end exploration classifiers
+  ([`14f8f45`](https://github.com/jacquardlabs/cctx/commit/14f8f45f9d3f4ef2fefac374d3e4cea36185c60d))
+
+- **#65**: Harvest v2 — route patches to any .md target (.claude/rules/, .claude/skills/)
+  ([`06ef9b7`](https://github.com/jacquardlabs/cctx/commit/06ef9b7a8ae9abacea54c2c826efc3fb6e6e80be))
+
+- **#66**: Cctx harvest --check audits CLAUDE.md for dead refs and empty sections
+  ([`a3be1d0`](https://github.com/jacquardlabs/cctx/commit/a3be1d0923d387b6830b10c7c2c5acf34a3b8917))
+
+- **#67**: Interactive aggregate drill-down; --check docs in README
+  ([`3db5429`](https://github.com/jacquardlabs/cctx/commit/3db5429dede40777b23d83e32a4b15a8c0e82a16))
+
+- **#68**: --since accepts 7d, 2w, YYYY-MM-DD, and date ranges
+  ([`434d7c4`](https://github.com/jacquardlabs/cctx/commit/434d7c448406e0a5465380ed395e1fadaa1c0db1))
+
+- **#69**: Annotate costs as estimates (~85–95%) in terminal and HTML output
+  ([`5a49889`](https://github.com/jacquardlabs/cctx/commit/5a49889bd43555d30a58c2b78eddf6acbb0d8e97))
+
+- **#70**: Cctx watch — live waste signals during an active session
+  ([`f533a13`](https://github.com/jacquardlabs/cctx/commit/f533a13e1f087da00457ce7b8215934f20c403a2))
+
+- **#72**: Cctx autopsy --github-summary writes findings to GitHub Actions job summary
+  ([`df91256`](https://github.com/jacquardlabs/cctx/commit/df91256b58b75a9bbe9594a000b00dee2ac2fbc5))
+
+- **#73**: Cctx GitHub Action (composite) + --fail-on-findings flag
+  ([`9229584`](https://github.com/jacquardlabs/cctx/commit/9229584ea192ce1b1ee6718721d981cba0ca13e0))
+
+### Refactoring
+
+- Consolidate KIND_LABEL, fix private import, clean up watcher tests
+  ([`31ad4d7`](https://github.com/jacquardlabs/cctx/commit/31ad4d75885eed9c8238c4eb1c08bd5d1ba51a15))
+
+
+## v0.1.0 (2026-05-16)
+
+- Initial Release

{cctx_cli-0.2.0 → cctx_cli-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cctx-cli
-Version: 0.2.0
+Version: 1.1.0
 Summary: Diagnose Claude Code sessions — find what went wrong, what it cost, and what to add to CLAUDE.md
 Author: Jacquard Labs
 License-Expression: MIT

{cctx_cli-0.2.0 → cctx_cli-1.1.0}/cctx/__init__.py

@@ -1,3 +1,3 @@
 """cctx: profile, debug, and optimize Claude Code and Agent SDK sessions."""
 
-__version__ = "0.2.0"
+__version__ = "1.1.0"

{cctx_cli-0.2.0 → cctx_cli-1.1.0}/cctx/cli.py

@@ -31,6 +31,7 @@ from cctx.renderers.terminal import (
     render_harvest_results,
     render_projects,
     render_sessions,
+    render_turn,
 )
 from cctx.tokenizer import tokenize_session
 
@@ -245,6 +246,22 @@ def ls(project: Path | None) -> None:
     default=False,
     help="Exit 1 if any findings are detected (single-session only).",
 )
+@click.option(
+    "--top",
+    "top_n",
+    default=None,
+    metavar="N",
+    type=click.IntRange(min=1),
+    help="Show only the top N patterns by session count (--since mode only).",
+)
+@click.option(
+    "--turn",
+    "turn_num",
+    default=None,
+    metavar="N",
+    type=click.IntRange(min=1),
+    help="Show details for turn N (single-session only).",
+)
 def autopsy(
     target: Path | None,
     since: str | None,
@@ -252,6 +269,8 @@ def autopsy(
     html_out: Path | None,
     github_summary: bool,
     fail_on_findings: bool,
+    top_n: int | None,
+    turn_num: int | None,
 ) -> None:
     """Diagnose a session or project directory.
 
@@ -267,6 +286,10 @@ def autopsy(
         raise click.UsageError("--latest and --since are mutually exclusive.")
     if fail_on_findings and since is not None:
         raise click.UsageError("--fail-on-findings is not supported with --since.")
+    if top_n is not None and since is None:
+        raise click.UsageError("--top requires --since.")
+    if turn_num is not None and since is not None:
+        raise click.UsageError("--turn is not supported with --since.")
 
     if target is None:
         if not latest:
@@ -305,6 +328,8 @@ def autopsy(
         start, end, label = parse_since(since)
         diagnoses = aggregate.run(project_dir, start, end)
         ev = evidence_mod.accumulate(diagnoses)
+        if top_n is not None:
+            ev = dict(sorted(ev.items(), key=lambda x: x[1].session_count, reverse=True)[:top_n])
         patches = claude_md.generate_from_evidence(ev)
         report = AggregateReport(
             period_label=label,
@@ -327,14 +352,16 @@ def autopsy(
         trace = tokenize_session(parse_session(target))
         diagnosis = diagnostician.run(trace)
         diagnosis = claude_md.generate(diagnosis)
-        if html_out is not None:
+        if turn_num is not None:
+            render_turn(trace, diagnosis, turn_num)
+        elif html_out is not None:
             from cctx.renderers.report import render_html
             html_out.write_text(render_html(diagnosis, trace), encoding="utf-8")
             click.echo(f"HTML report written to {html_out}")
-        if github_summary:
+        elif github_summary:
             from cctx.renderers.github import write_github_summary
             write_github_summary(diagnosis)
-        if html_out is None and not github_summary:
+        else:
             render_diagnosis(diagnosis, session_path=target)
         if fail_on_findings and diagnosis.findings:
             raise SystemExit(1)

{cctx_cli-0.2.0 → cctx_cli-1.1.0}/cctx/models.py

@@ -225,6 +225,13 @@ class Diagnosis:
     waste_cost_usd:  float
     analysed_at:     datetime
 
+    @property
+    def verdict(self) -> str:
+        if not self.findings:
+            return "clean session"
+        seen = dict.fromkeys(f.kind for f in self.findings)
+        return " + ".join(KIND_LABEL[k] for k in seen)
+
 
 @dataclass
 class KindEvidence:

{cctx_cli-0.2.0 → cctx_cli-1.1.0}/cctx/renderers/terminal.py

@@ -24,7 +24,7 @@ from cctx.models import KIND_LABEL, FindingKind, Severity
 
 if TYPE_CHECKING:
     from cctx.discovery import ProjectInfo
-    from cctx.models import AggregateReport, Diagnosis
+    from cctx.models import AggregateReport, Diagnosis, SessionTrace
 
 _SEVERITY_STYLE = {
     Severity.HIGH:   "bold red",
@@ -49,6 +49,9 @@ def render_diagnosis(
 
     # Header
     con.print(Rule(f"cctx autopsy — session {diagnosis.session_id}"))
+    verdict = diagnosis.verdict
+    verdict_style = "bold green" if not diagnosis.findings else "bold red"
+    con.print(Text(f"Verdict: {verdict}", style=verdict_style))
     cost_line = f"Session cost: ~${diagnosis.total_cost_usd:.2f}"
     if diagnosis.waste_cost_usd > 0:
         pct = (
@@ -169,6 +172,56 @@ def render_aggregate_drilldown(
         con.print("No matching findings.")
 
 
+def render_turn(
+    trace: SessionTrace,
+    diagnosis: Diagnosis,
+    turn_num: int,
+    *,
+    console: Console | None = None,
+) -> None:
+    """Render details for a single turn N from a session."""
+    con = console or _default_console()
+
+    turn = next((t for t in trace.turns if t.turn_number == turn_num), None)
+    if turn is None:
+        con.print(Text(
+            f"Turn {turn_num} not found (session has {len(trace.turns)} turns).",
+            style="red",
+        ))
+        return
+
+    con.print(Rule(f"Turn {turn_num} — {turn.role} — {turn.timestamp.strftime('%H:%M:%S')}"))
+
+    text = turn.text
+    if text:
+        preview = text[:500]
+        if len(text) > 500:
+            preview += f"\n… [{len(text) - 500} more chars]"
+        con.print(preview)
+
+    for tu in turn.tool_uses:
+        con.print(Text(f"  tool_use: {tu.tool_name}", style="cyan"))
+
+    for tr in turn.tool_results:
+        style = "red" if tr.is_error else "dim"
+        content = tr.content
+        preview = content[:200] + ("…" if len(content) > 200 else "")
+        con.print(Text(f"  tool_result ({tr.tool_name}): {preview}", style=style))
+
+    # Findings that span this turn
+    touching = [
+        f for f in diagnosis.findings
+        if f.first_turn <= turn_num <= (f.last_turn or f.first_turn)
+    ]
+    if touching:
+        con.print()
+        con.print(Text("Findings active at this turn:", style="bold"))
+        for finding in touching:
+            style = _SEVERITY_STYLE.get(finding.severity, "")
+            label = _KIND_LABEL.get(finding.kind, finding.kind.value.upper())
+            con.print(Text(f"  [{label}]", style=style), finding.summary)
+
+
 def render_harvest_results(
     results: list,  # list[ApplyResult] — ApplyStatus is harvest-internal; imported lazily
     *,

{cctx_cli-0.2.0 → cctx_cli-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cctx-cli"
-version = "0.2.0"
+version = "1.1.0"
 description = "Diagnose Claude Code sessions — find what went wrong, what it cost, and what to add to CLAUDE.md"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -42,6 +42,18 @@ python_functions = ["test_*"]
 addopts = "-ra --strict-markers"
 asyncio_mode = "auto"
 
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+version_variables = ["cctx/__init__.py:__version__"]
+tag_format = "v{version}"
+commit_message = "chore(release): v{version} [skip ci]"
+major_on_zero = false
+build_command = "pip install build && python -m build"
+upload_to_vcs_release = true
+
+[tool.semantic_release.branches.main]
+match = "main"
+
 [tool.ruff]
 line-length = 100
 target-version = "py310"

{cctx_cli-0.2.0 → cctx_cli-1.1.0}/tests/test_cli.py

@@ -309,3 +309,83 @@ def test_fail_on_findings_incompatible_with_since(runner):
         ["autopsy", str(FIXTURE_PATH.parent), "--since", "7", "--fail-on-findings"],
     )
     assert result.exit_code != 0
+
+
+# ---------------------------------------------------------------------------
+# --top N tests (#75)
+# ---------------------------------------------------------------------------
+
+
+def test_top_requires_since(runner, session_jsonl):
+    """--top without --since → non-zero exit (UsageError)."""
+    from cctx.cli import cli
+
+    result = runner.invoke(cli, ["autopsy", str(session_jsonl), "--top", "3"])
+    assert result.exit_code != 0
+    assert "since" in result.output.lower() or "Error" in result.output
+
+
+def test_top_with_since_accepted(runner, tmp_path):
+    """--top N with --since → exit 0."""
+    from cctx.cli import cli
+
+    project_dir = tmp_path / "-Users-test-Projects-demo"
+    project_dir.mkdir()
+    session_id = "top-test-sess"
+    line = {
+        "type": "user", "uuid": f"{session_id}-u1", "parentUuid": None,
+        "isSidechain": False, "timestamp": "2026-05-14T10:00:00.000Z",
+        "sessionId": session_id, "version": "2.1.138",
+        "cwd": "/Users/test/Projects/demo", "gitBranch": "main",
+        "userType": "external", "entrypoint": "cli",
+        "message": {"role": "user", "content": "hello"},
+    }
+    (project_dir / f"{session_id}.jsonl").write_text(json.dumps(line) + "\n")
+
+    result = runner.invoke(
+        cli, ["autopsy", str(project_dir), "--since", "7", "--top", "2"],
+        catch_exceptions=False,
+    )
+    assert result.exit_code == 0
+
+
+# ---------------------------------------------------------------------------
+# --turn N tests (#76)
+# ---------------------------------------------------------------------------
+
+
+def test_turn_incompatible_with_since(runner, tmp_path):
+    """--turn N + --since → non-zero exit (UsageError)."""
+    from cctx.cli import cli
+
+    project_dir = tmp_path / "-Users-test-Projects-demo"
+    project_dir.mkdir()
+    result = runner.invoke(
+        cli, ["autopsy", str(project_dir), "--since", "7", "--turn", "3"],
+    )
+    assert result.exit_code != 0
+    assert "since" in result.output.lower() or "Error" in result.output
+
+
+def test_turn_shows_turn_details(runner, session_jsonl):
+    """--turn 1 on a session with one turn prints turn details."""
+    from cctx.cli import cli
+
+    result = runner.invoke(
+        cli, ["autopsy", str(session_jsonl), "--turn", "1"],
+        catch_exceptions=False,
+    )
+    assert result.exit_code == 0
+    assert "Turn 1" in result.output
+
+
+def test_turn_out_of_range_shows_not_found(runner, session_jsonl):
+    """--turn 999 on a one-turn session shows 'not found' message."""
+    from cctx.cli import cli
+
+    result = runner.invoke(
+        cli, ["autopsy", str(session_jsonl), "--turn", "999"],
+        catch_exceptions=False,
+    )
+    assert result.exit_code == 0
+    assert "not found" in result.output.lower() or "999" in result.output

{cctx_cli-0.2.0 → cctx_cli-1.1.0}/tests/test_models.py

@@ -643,3 +643,57 @@ def test_aggregate_report_instantiates():
     )
     assert report.sessions_analysed == 12
     assert FindingKind.RETRY_LOOP in report.by_kind
+
+
+# ---------------------------------------------------------------------------
+# Diagnosis.verdict property (#74)
+# ---------------------------------------------------------------------------
+
+
+def _make_finding_of_kind(kind, first_turn=5):
+    from cctx.models import Confidence, Finding, Severity
+    return Finding(
+        kind=kind,
+        severity=Severity.MEDIUM,
+        confidence=Confidence.MEDIUM,
+        first_turn=first_turn,
+        last_turn=None,
+        evidence={},
+        cost_usd=None,
+        summary="test",
+    )
+
+
+def _make_diag(findings):
+    from cctx.models import Diagnosis
+    return Diagnosis(
+        session_id="abc",
+        findings=findings,
+        inflection_turn=None,
+        patches=[],
+        total_cost_usd=1.0,
+        waste_cost_usd=0.0,
+        analysed_at=_utcnow(),
+    )
+
+
+def test_verdict_clean_session():
+    d = _make_diag([])
+    assert d.verdict == "clean session"
+
+
+def test_verdict_single_finding():
+    from cctx.models import FindingKind
+    d = _make_diag([_make_finding_of_kind(FindingKind.RETRY_LOOP)])
+    assert d.verdict == "RETRY LOOP"
+
+
+def test_verdict_multiple_kinds_deduped_in_order():
+    from cctx.models import FindingKind
+    findings = [
+        _make_finding_of_kind(FindingKind.SCOPE_CREEP),
+        _make_finding_of_kind(FindingKind.RETRY_LOOP),
+        _make_finding_of_kind(FindingKind.SCOPE_CREEP),  # duplicate kind
+    ]
+    d = _make_diag(findings)
+    assert d.verdict == "SCOPE CREEP + RETRY LOOP"

{cctx_cli-0.2.0 → cctx_cli-1.1.0}/tests/test_terminal_renderer.py

@@ -109,3 +109,103 @@ def test_patch_diff_shown():
     )
     output = _render_to_string(diag)
     assert "Retry discipline" in output or "CLAUDE.md" in output
+
+
+def test_verdict_shown_in_output():
+    diag = _make_diagnosis([_make_finding("retry_loop")])
+    output = _render_to_string(diag)
+    assert "Verdict" in output
+
+
+def test_verdict_clean_shown():
+    output = _render_to_string(_make_diagnosis())
+    assert "clean" in output.lower()
+
+
+# ---------------------------------------------------------------------------
+# render_turn (#76)
+# ---------------------------------------------------------------------------
+
+
+def _make_trace_with_turn(turn_number=3, role="assistant", text="some content"):
+    from datetime import datetime, timezone
+
+    from cctx.models import SessionTrace, Turn
+
+    t = Turn(
+        turn_number=turn_number,
+        uuid=f"uuid-{turn_number}",
+        parent_uuid=None,
+        role=role,
+        text=text,
+        thinking="",
+        tool_uses=[],
+        tool_results=[],
+        usage=None,
+        model="claude-sonnet-4-6",
+        stop_reason="end_turn",
+        timestamp=datetime(2026, 5, 14, 10, 30, 0, tzinfo=timezone.utc),
+        duration_ms=None,
+    )
+    from pathlib import Path
+    return SessionTrace(
+        session_id="trace-test",
+        parent_session_id=None,
+        project_path="/p",
+        cwd="/p",
+        primary_model="claude-sonnet-4-6",
+        claude_code_version=None,
+        turns=[t],
+        subagents=[],
+        attachments=[],
+        raw_tool_result_files=[],
+        initial_context_tokens=0,
+        tool_names_loaded=[],
+        start_time=t.timestamp,
+        end_time=t.timestamp,
+        source_path=Path("/p/trace-test.jsonl"),
+        subagent_meta={},
+        warnings=[],
+        subagent_parse_errors=[],
+    )
+
+
+def _render_turn_to_string(trace, diagnosis, turn_num):
+    from rich.console import Console
+
+    from cctx.renderers.terminal import render_turn
+
+    buf = StringIO()
+    console = Console(file=buf, width=120, highlight=False, markup=False)
+    render_turn(trace, diagnosis, turn_num, console=console)
+    return buf.getvalue()
+
+
+def test_render_turn_shows_role_and_number():
+    trace = _make_trace_with_turn(turn_number=3, role="assistant", text="hello world")
+    diag = _make_diagnosis()
+    output = _render_turn_to_string(trace, diag, 3)
+    assert "Turn 3" in output
+    assert "assistant" in output
+
+
+def test_render_turn_shows_text():
+    trace = _make_trace_with_turn(text="important content here")
+    diag = _make_diagnosis()
+    output = _render_turn_to_string(trace, diag, 3)
+    assert "important content here" in output
+
+
+def test_render_turn_not_found():
+    trace = _make_trace_with_turn(turn_number=3)
+    diag = _make_diagnosis()
+    output = _render_turn_to_string(trace, diag, 99)
+    assert "not found" in output.lower() or "99" in output
+
+
+def test_render_turn_shows_active_finding():
+    trace = _make_trace_with_turn(turn_number=5)
+    finding = _make_finding("retry_loop")  # first_turn=5, last_turn=10
+    diag = _make_diagnosis([finding])
+    output = _render_turn_to_string(trace, diag, 5)
+    assert "retry" in output.lower() or "RETRY" in output