but_agent_friendliness.py

#!/usr/bin/env python3
"""
but_agent_friendliness.py — Analyze how agent-friendly the 'but' CLI is.

Reads extracted but-usage data (from but_usage_report.py) and produces a deep
analysis across 7 dimensions: status overhead, JSON output gaps, pipe workarounds,
retry/struggle patterns, error categories, error recovery, and workflow sequences.
Outputs a structured text report and 8 analysis charts.

PREREQUISITES:
    pip install matplotlib          # only needed for charts

USAGE:
    # Full analysis: text report + charts
    python3 but_agent_friendliness.py

    # Text report only (no matplotlib needed)
    python3 but_agent_friendliness.py --report-only

    # Charts only
    python3 but_agent_friendliness.py --charts-only

    # Custom output directory (must contain but_usage.json)
    python3 but_agent_friendliness.py --output-dir /tmp/my-analysis

OUTPUT FILES (in --output-dir, default ./but_usage_output/):
    agent_status_overhead.png       Per-session status check overhead histogram
    agent_json_gaps.png             JSON adoption rate by subcommand
    agent_pipe_workarounds.png      Pipe targets + extracted fields (two-panel)
    agent_retry_struggles.png       Struggle patterns by subcommand
    agent_error_categories.png      Error classification with preventability
    agent_error_recovery.png        Recovery behavior donut chart
    agent_workflow_transitions.png  Command transition heatmap
    agent_friendliness_scorecard.png  Dimension scores bar chart

INPUT:
    Reads but_usage.json produced by but_usage_report.py (run that first).
"""

from __future__ import annotations

import argparse
import json
import re
import statistics
import sys
from collections import Counter, defaultdict
from datetime import datetime
from pathlib import Path

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Configuration
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

DEFAULT_OUTPUT_DIR = Path("but_usage_output")

# Color palette (consistent with but_usage_report.py)
BLUE = "#4C9BE8"
RED = "#E85454"
ORANGE = "#F5A623"
GREEN = "#27AE60"
PURPLE = "#9B59B6"
GRAY = "#95A5A6"

# Error categories considered preventable via better CLI design
PREVENTABLE_CATEGORIES = {"argument_confusion", "ambiguous_ref", "invalid_target_type", "non_interactive"}


# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Helpers
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

def parse_timestamp(ts) -> datetime | None:
    """Convert a timestamp (epoch ms, epoch seconds, or ISO string) to datetime."""
    if ts is None:
        return None
    if isinstance(ts, (int, float)):
        return datetime.fromtimestamp(ts / 1000) if ts > 1e12 else datetime.fromtimestamp(ts)
    if isinstance(ts, str):
        try:
            v = float(ts)
            return datetime.fromtimestamp(v / 1000) if v > 1e12 else datetime.fromtimestamp(v)
        except ValueError:
            try:
                return datetime.fromisoformat(ts)
            except ValueError:
                return None
    return None


def load_data(output_dir: Path) -> list[dict]:
    """Load but_usage.json and filter out but-engineering records."""
    json_path = output_dir / "but_usage.json"
    if not json_path.exists():
        print(f"Error: {json_path} not found. Run but_usage_report.py first.", file=sys.stderr)
        sys.exit(1)
    with open(json_path) as f:
        data = json.load(f)
    # Filter out but-engineering (coordination tool, not CLI usage)
    filtered = [r for r in data if not r["but_subcommand"].startswith("but-")]
    print(f"Loaded {len(filtered)} but commands ({len(data) - len(filtered)} but-engineering records excluded)")
    return filtered


def group_by_session(data: list[dict]) -> dict[str, list[dict]]:
    """Group records by session_id, sorted by timestamp within each session."""
    sessions: dict[str, list[dict]] = defaultdict(list)
    for r in data:
        sessions[r["session_id"]].append(r)
    # Sort each session by timestamp
    for sid in sessions:
        sessions[sid].sort(key=lambda r: parse_timestamp(r.get("timestamp")) or datetime.min)
    return dict(sessions)


# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Analysis 1: Status Check Overhead
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

def analyze_status_overhead(data: list[dict], sessions: dict[str, list[dict]]) -> dict:
    """Measure the 'status check tax' — how much of agent time is spent polling state.

    Computes overall and per-session proportion of 'but status' commands,
    and counts 'status sandwich' patterns (status -> X -> status).
    """
    total = len(data)
    status_count = sum(1 for r in data if r["but_subcommand"] == "status")
    overall_pct = 100 * status_count / total if total else 0

    # Per-session overhead (only sessions with >= 3 commands)
    per_session = []
    sandwich_count = 0
    for sid, cmds in sessions.items():
        if len(cmds) < 3:
            continue
        s_count = sum(1 for r in cmds if r["but_subcommand"] == "status")
        per_session.append(100 * s_count / len(cmds))
        # Count status sandwiches: status -> non-status -> status
        for i in range(len(cmds) - 2):
            if (cmds[i]["but_subcommand"] == "status"
                    and cmds[i + 1]["but_subcommand"] != "status"
                    and cmds[i + 2]["but_subcommand"] == "status"):
                sandwich_count += 1

    mean_pct = statistics.mean(per_session) if per_session else 0
    median_pct = statistics.median(per_session) if per_session else 0

    return {
        "total": total,
        "status_count": status_count,
        "overall_pct": overall_pct,
        "per_session_overheads": per_session,
        "mean_pct": mean_pct,
        "median_pct": median_pct,
        "sandwich_count": sandwich_count,
        "sessions_analyzed": len(per_session),
    }


# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Analysis 2: JSON Output Gaps
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

def analyze_json_gaps(data: list[dict]) -> dict:
    """Measure --json adoption per subcommand and identify gaps.

    Subcommands with 0% JSON usage indicate missing --json support,
    forcing agents to use pipe workarounds.
    """
    skip = {"--help", "--version", "--json"}
    by_subcmd: dict[str, dict] = {}

    for r in data:
        sc = r["but_subcommand"]
        if sc in skip:
            continue
        if sc not in by_subcmd:
            by_subcmd[sc] = {"total": 0, "json": 0}
        by_subcmd[sc]["total"] += 1
        if "--json" in r["command"]:
            by_subcmd[sc]["json"] += 1

    # Only include subcommands with >= 4 uses
    results = []
    for sc, counts in sorted(by_subcmd.items(), key=lambda x: x[1]["total"], reverse=True):
        if counts["total"] < 4:
            continue
        pct = 100 * counts["json"] / counts["total"]
        results.append({"name": sc, "total": counts["total"], "json_count": counts["json"], "json_pct": pct})

    zero_json = [r for r in results if r["json_count"] == 0]
    total_json = sum(1 for r in data if "--json" in r["command"])
    overall_pct = 100 * total_json / len(data) if data else 0

    return {
        "by_subcmd": results,
        "zero_json_cmds": zero_json,
        "overall_json_pct": overall_pct,
        "total_with_json": total_json,
    }


# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Analysis 3: Pipe Workarounds
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

def analyze_pipe_workarounds(data: list[dict]) -> dict:
    """Analyze what agents pipe but output to and what fields they extract.

    When agents pipe to jq/python3/grep/head, it reveals information the CLI
    isn't surfacing directly.
    """
    pipe_targets = Counter()
    jq_fields = Counter()
    python_fields = Counter()
    head_count = 0
    piped_commands = 0

    known_tools = {"jq", "python3", "python", "grep", "head", "tail", "wc", "sort", "cut", "awk", "sed", "tr"}

    for r in data:
        cmd = r["command"]
        if "|" not in cmd:
            continue
        piped_commands += 1

        parts = cmd.split("|")
        for part in parts[1:]:
            tool = part.strip().split()[0] if part.strip() else ""
            if tool in known_tools:
                pipe_targets[tool] += 1

                # Extract jq field accesses
                if tool == "jq":
                    # Find field accesses like .fieldName, .stacks[], .commits[].cliId
                    fields = re.findall(r'\.([a-zA-Z_][a-zA-Z0-9_]*)', part)
                    for f in fields:
                        jq_fields[f] += 1

                # Extract python3 field accesses from inline scripts
                elif tool in ("python3", "python"):
                    # dict key accesses like ["stacks"], ["branches"], .get("name")
                    keys = re.findall(r'\[["\']([a-zA-Z_][a-zA-Z0-9_]*)["\']', part)
                    for k in keys:
                        python_fields[k] += 1
                    # Also look for .get("field") patterns
                    gets = re.findall(r'\.get\(["\']([a-zA-Z_][a-zA-Z0-9_]*)', part)
                    for g in gets:
                        python_fields[g] += 1

                elif tool == "head":
                    head_count += 1

    # Merge jq + python field accesses
    all_fields = Counter()
    all_fields.update(jq_fields)
    all_fields.update(python_fields)

    return {
        "piped_commands": piped_commands,
        "pipe_targets": pipe_targets,
        "jq_fields": jq_fields,
        "python_fields": python_fields,
        "all_fields": all_fields,
        "head_truncation_count": head_count,
    }


# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Analysis 4: Retry/Struggle Patterns
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

def analyze_retry_patterns(sessions: dict[str, list[dict]]) -> dict:
    """Detect when agents struggle — consecutive same-subcommand runs.

    Separates benign status polling from real struggles, and checks whether
    agents adapted their approach (changed args) or retried blindly.
    """
    sequences = []  # (session_id, subcommand, run_length, had_error, adapted)

    for sid, cmds in sessions.items():
        if len(cmds) < 2:
            continue
        i = 0
        while i < len(cmds):
            sc = cmds[i]["but_subcommand"]
            j = i + 1
            while j < len(cmds) and cmds[j]["but_subcommand"] == sc:
                j += 1
            run_len = j - i
            if run_len >= 2:
                had_error = any(cmds[k]["is_error"] for k in range(i, j))
                # Check if command text changed (adapted) vs identical (blind retry)
                unique_cmds = set(cmds[k]["command"].strip() for k in range(i, j))
                adapted = len(unique_cmds) > 1
                sequences.append({
                    "session_id": sid,
                    "subcommand": sc,
                    "run_length": run_len,
                    "had_error": had_error,
                    "adapted": adapted,
                })
            i = j

    status_polls = [s for s in sequences if s["subcommand"] == "status"]
    real_struggles = [s for s in sequences if s["subcommand"] != "status"]
    struggle_by_subcmd = Counter(s["subcommand"] for s in real_struggles)
    error_struggles = [s for s in real_struggles if s["had_error"]]
    adapted_count = sum(1 for s in real_struggles if s["adapted"])
    blind_count = sum(1 for s in real_struggles if not s["adapted"])

    return {
        "total_sequences": len(sequences),
        "status_polls": len(status_polls),
        "real_struggles": len(real_struggles),
        "struggle_by_subcmd": struggle_by_subcmd,
        "error_struggles": len(error_struggles),
        "adapted_count": adapted_count,
        "blind_count": blind_count,
        "sequences": sequences,
    }


# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Analysis 5: Error Categories
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

def classify_error(output: str) -> str:
    """Classify an error output into an actionable category.

    Categories (in priority order):
      argument_confusion — wrong flag name or incompatible flags
      stale_id          — CLI ID no longer valid after an operation
      ambiguous_ref     — short ref matches multiple targets
      non_interactive   — missing flag for non-TTY environment
      invalid_target    — wrong entity type for the operation
      safety_guard      — CLI safety check blocked the action
      locked_resource   — transient infrastructure issue (db lock)
      other             — unclassified
    """
    out = output.lower()
    if any(p in out for p in ["unexpected argument", "a similar argument exists", "cannot be used with",
                               "unrecognized option", "unknown flag"]):
        return "argument_confusion"
    if any(p in out for p in ["ambiguous", "did you mean"]):
        return "ambiguous_ref"
    if "non-interactive" in out or "non interactive" in out:
        return "non_interactive"
    if any(p in out for p in ["not found", "could not find", "no such"]):
        return "stale_id"
    if any(p in out for p in ["cannot stage", "is a stack", "is a committed", "must be"]):
        return "invalid_target"
    if "refusing" in out:
        return "safety_guard"
    if "database is locked" in out or "lock" in out and "failed" in out:
        return "locked_resource"
    return "other"


def categorize_errors(data: list[dict]) -> dict:
    """Classify all errors and compute preventability stats."""
    errors = [r for r in data if r["is_error"]]
    categories = Counter()
    by_subcmd_cat: dict[str, Counter] = defaultdict(Counter)

    for r in errors:
        cat = classify_error(r["output"])
        categories[cat] += 1
        by_subcmd_cat[r["but_subcommand"]][cat] += 1

    preventable = sum(categories[c] for c in PREVENTABLE_CATEGORIES)

    return {
        "total_errors": len(errors),
        "categories": categories,
        "by_subcmd_cat": dict(by_subcmd_cat),
        "preventable_count": preventable,
        "preventable_pct": 100 * preventable / len(errors) if errors else 0,
    }


# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Analysis 6: Error Recovery
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

def analyze_error_recovery(sessions: dict[str, list[dict]]) -> dict:
    """Track how agents respond after errors.

    Categories:
      blind_retry      — exact same command repeated
      status_then_retry — refreshed state via 'but status' before retrying
      adapted          — same subcommand with different arguments
      pivoted          — switched to a different subcommand
      no_followup      — error was the last but command in the session
    """
    recovery = Counter()

    for sid, cmds in sessions.items():
        for i, r in enumerate(cmds):
            if not r["is_error"]:
                continue

            if i + 1 >= len(cmds):
                recovery["no_followup"] += 1
                continue

            next_cmd = cmds[i + 1]
            if next_cmd["command"].strip() == r["command"].strip():
                recovery["blind_retry"] += 1
            elif next_cmd["but_subcommand"] == "status":
                recovery["status_then_retry"] += 1
            elif next_cmd["but_subcommand"] == r["but_subcommand"]:
                recovery["adapted"] += 1
            else:
                recovery["pivoted"] += 1

    total = sum(recovery.values())
    recovered = total - recovery.get("no_followup", 0) - recovery.get("blind_retry", 0)
    recovery_rate = 100 * recovered / total if total else 0

    return {
        "total_errors_with_context": total,
        "recovery": dict(recovery),
        "recovery_rate": recovery_rate,
    }


# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Analysis 7: Workflow Sequences
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

def analyze_workflow_sequences(data: list[dict], sessions: dict[str, list[dict]]) -> dict:
    """Build a transition matrix showing what subcommand follows what.

    Focuses on top 10 subcommands for a readable heatmap.
    """
    # Top 10 subcommands by frequency
    subcmd_counts = Counter(r["but_subcommand"] for r in data)
    top_subcmds = [sc for sc, _ in subcmd_counts.most_common(10)]

    # Build transition counts
    transitions: Counter = Counter()
    for sid, cmds in sessions.items():
        for i in range(len(cmds) - 1):
            src = cmds[i]["but_subcommand"]
            dst = cmds[i + 1]["but_subcommand"]
            if src in top_subcmds and dst in top_subcmds:
                transitions[(src, dst)] += 1

    # Build top trigrams
    trigrams: Counter = Counter()
    for sid, cmds in sessions.items():
        for i in range(len(cmds) - 2):
            tri = (cmds[i]["but_subcommand"], cmds[i + 1]["but_subcommand"], cmds[i + 2]["but_subcommand"])
            trigrams[tri] += 1

    return {
        "top_subcmds": top_subcmds,
        "transitions": transitions,
        "top_trigrams": trigrams.most_common(15),
    }


# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Scorecard
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

def generate_scorecard(results: dict) -> dict:
    """Compute an overall Agent Friendliness Score across 5 dimensions (0-100 each)."""
    status = results["status_overhead"]
    json_gaps = results["json_gaps"]
    errors = results["error_categories"]
    recovery = results["error_recovery"]
    retries = results["retry_patterns"]

    # Status overhead: lower overhead = higher score
    status_score = max(0, min(100, 100 - status["overall_pct"] * 1.5))

    # JSON coverage: higher adoption = higher score
    json_score = max(0, min(100, json_gaps["overall_json_pct"] * 2.5))

    # Error rate: lower = higher score (5.8% error rate → ~71)
    error_pct = 100 * errors["total_errors"] / status["total"] if status["total"] else 0
    error_score = max(0, min(100, 100 - error_pct * 5))

    # Error recovery: direct mapping
    recovery_score = min(100, recovery["recovery_rate"])

    # Retry burden: fewer real struggles = higher score
    struggle_pct = 100 * retries["real_struggles"] / status["total"] if status["total"] else 0
    retry_score = max(0, min(100, 100 - struggle_pct * 10))

    scores = {
        "Status Overhead": round(status_score),
        "JSON Coverage": round(json_score),
        "Error Rate": round(error_score),
        "Error Recovery": round(recovery_score),
        "Retry Burden": round(retry_score),
    }
    composite = round(statistics.mean(scores.values()))
    scores["OVERALL"] = composite

    return scores


# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Text Report
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

def print_report(results: dict) -> None:
    """Print a structured text report of all findings to stdout."""
    so = results["status_overhead"]
    jg = results["json_gaps"]
    pw = results["pipe_workarounds"]
    rp = results["retry_patterns"]
    ec = results["error_categories"]
    er = results["error_recovery"]
    ws = results["workflow_sequences"]
    sc = results["scorecard"]

    print("\n" + "=" * 70)
    print("  but CLI Agent-Friendliness Report")
    print("=" * 70)

    # 1. Status overhead
    print("\n--- 1. Status Check Overhead ---")
    print(f"Overall: {so['status_count']}/{so['total']} commands ({so['overall_pct']:.1f}%) are 'but status'")
    print(f"Per-session: mean={so['mean_pct']:.1f}%, median={so['median_pct']:.1f}% (across {so['sessions_analyzed']} sessions)")
    print(f"Status-sandwich patterns (status->X->status): {so['sandwich_count']}")
    print(f"Recommendation: --status-after flag on mutation commands could eliminate ~{so['status_count'] // 2}+ status calls")

    # 2. JSON gaps
    print("\n--- 2. JSON Output Gaps ---")
    print(f"Overall --json adoption: {jg['overall_json_pct']:.1f}% ({jg['total_with_json']}/{so['total']})")
    if jg["zero_json_cmds"]:
        zero_list = ", ".join(f"{c['name']} ({c['total']} uses)" for c in jg["zero_json_cmds"])
        print(f"Subcommands with 0% JSON: {zero_list}")
    print(f"Recommendation: Add --json support to all subcommands")
    print()
    print(f"  {'Subcommand':15s} {'Total':>6s} {'--json':>7s} {'Rate':>6s}")
    for entry in jg["by_subcmd"]:
        print(f"  {entry['name']:15s} {entry['total']:6d} {entry['json_count']:7d} {entry['json_pct']:5.0f}%")

    # 3. Pipe workarounds
    print("\n--- 3. Output Piping Analysis ---")
    print(f"Commands piped to external tools: {pw['piped_commands']}")
    print(f"Pipe targets: {', '.join(f'{t} ({c}x)' for t, c in pw['pipe_targets'].most_common(6))}")
    print(f"Output truncated (piped to head): {pw['head_truncation_count']} times")
    print(f"\nTop fields extracted via jq/python3 (reveals missing CLI surface area):")
    for field, count in pw["all_fields"].most_common(12):
        print(f"  .{field:30s} {count:4d} accesses")

    # 4. Retry patterns
    print("\n--- 4. Retry/Struggle Patterns ---")
    print(f"Total consecutive-command sequences: {rp['total_sequences']}")
    print(f"  Status polling (benign): {rp['status_polls']}")
    print(f"  Real struggles: {rp['real_struggles']} ({rp['adapted_count']} adapted, {rp['blind_count']} blind retries)")
    if rp["struggle_by_subcmd"]:
        print(f"  By subcommand: {', '.join(f'{sc} ({c})' for sc, c in rp['struggle_by_subcmd'].most_common(8))}")

    # 5. Error categories
    print("\n--- 5. Error Categories ---")
    print(f"Total errors: {ec['total_errors']}")
    for cat, count in ec["categories"].most_common():
        pct = 100 * count / ec["total_errors"]
        tag = " [PREVENTABLE]" if cat in PREVENTABLE_CATEGORIES else ""
        print(f"  {cat:25s} {count:4d} ({pct:4.1f}%){tag}")
    print(f"Preventable: {ec['preventable_count']}/{ec['total_errors']} ({ec['preventable_pct']:.0f}%)")

    # 6. Error recovery
    print("\n--- 6. Error Recovery ---")
    print(f"Recovery rate: {er['recovery_rate']:.1f}%")
    for behavior, count in sorted(er["recovery"].items(), key=lambda x: -x[1]):
        print(f"  {behavior:25s} {count:4d}")
    print("Positive finding: agents almost always recover from errors")

    # 7. Workflow sequences
    print("\n--- 7. Workflow Sequences ---")
    print("Top trigram patterns (most common 3-step workflows):")
    for tri, count in ws["top_trigrams"][:10]:
        print(f"  {' -> '.join(tri):50s} {count:4d}")

    # Scorecard
    print("\n" + "=" * 70)
    print("  Agent Friendliness Scorecard")
    print("=" * 70)
    for dim, score in sc.items():
        if dim == "OVERALL":
            continue
        bar = "#" * (score // 5)
        grade = "A" if score >= 80 else "B" if score >= 60 else "C" if score >= 40 else "D"
        print(f"  {dim:20s}  {score:3d}/100  [{bar:20s}]  {grade}")
    print(f"\n  {'OVERALL':20s}  {sc['OVERALL']:3d}/100")
    print()


# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Charts
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

def generate_all_charts(results: dict, output_dir: Path) -> None:
    """Generate all 8 analysis charts. Requires matplotlib."""
    import matplotlib
    matplotlib.use("Agg")
    import matplotlib.pyplot as plt
    import numpy as np

    output_dir.mkdir(parents=True, exist_ok=True)

    # ── Chart 1: Status overhead histogram ─────────────────────────────────
    so = results["status_overhead"]
    if so["per_session_overheads"]:
        fig, ax = plt.subplots(figsize=(10, 5))
        bins = list(range(0, 101, 10))
        ax.hist(so["per_session_overheads"], bins=bins, color=ORANGE, edgecolor="white", linewidth=0.5)
        ax.axvline(so["mean_pct"], color=RED, linestyle="--", linewidth=2, label=f"Mean: {so['mean_pct']:.0f}%")
        ax.axvline(so["median_pct"], color=PURPLE, linestyle=":", linewidth=2, label=f"Median: {so['median_pct']:.0f}%")
        ax.set_xlabel("Status commands as % of session")
        ax.set_ylabel("Number of sessions")
        ax.set_title("Agent Status Check Overhead per Session\n"
                      f"{so['overall_pct']:.0f}% of all commands are 'but status'")
        ax.legend()
        plt.tight_layout()
        p = output_dir / "agent_status_overhead.png"
        plt.savefig(p, dpi=150)
        print(f"  Saved {p}")
        plt.close()

    # ── Chart 2: JSON adoption gaps ────────────────────────────────────────
    jg = results["json_gaps"]
    if jg["by_subcmd"]:
        entries = list(reversed(jg["by_subcmd"]))  # smallest at top for horizontal bar
        names = [e["name"] for e in entries]
        json_counts = [e["json_count"] for e in entries]
        no_json = [e["total"] - e["json_count"] for e in entries]

        fig, ax = plt.subplots(figsize=(10, 7))
        ax.barh(names, json_counts, color=BLUE, label="With --json")
        ax.barh(names, no_json, left=json_counts, color=RED, alpha=0.6, label="Without --json")
        for i, e in enumerate(entries):
            ax.text(e["total"] + 1, i, f"{e['json_pct']:.0f}%", va="center", fontsize=9)
        ax.set_xlabel("Invocation count")
        ax.set_title(f"JSON Output Adoption by Subcommand\n"
                      f"Overall: {jg['overall_json_pct']:.0f}% of commands use --json")
        ax.legend(loc="lower right")
        plt.tight_layout()
        p = output_dir / "agent_json_gaps.png"
        plt.savefig(p, dpi=150)
        print(f"  Saved {p}")
        plt.close()

    # ── Chart 3: Pipe workarounds (two-panel) ─────────────────────────────
    pw = results["pipe_workarounds"]
    fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(14, 5))

    # Left: pipe targets
    targets = pw["pipe_targets"].most_common(8)
    if targets:
        t_names = [t for t, _ in reversed(targets)]
        t_counts = [c for _, c in reversed(targets)]
        ax1.barh(t_names, t_counts, color=PURPLE)
        for i, c in enumerate(t_counts):
            ax1.text(c + 0.5, i, str(c), va="center", fontsize=9)
        ax1.set_xlabel("Times used")
        ax1.set_title("Pipe Targets\n(Workaround tools agents use)")

    # Right: top extracted fields
    fields = pw["all_fields"].most_common(12)
    if fields:
        f_names = ["." + f for f, _ in reversed(fields)]
        f_counts = [c for _, c in reversed(fields)]
        ax2.barh(f_names, f_counts, color=ORANGE)
        for i, c in enumerate(f_counts):
            ax2.text(c + 0.3, i, str(c), va="center", fontsize=9)
        ax2.set_xlabel("Access count")
        ax2.set_title("Fields Extracted via Pipes\n(Missing CLI surface area)")

    plt.tight_layout()
    p = output_dir / "agent_pipe_workarounds.png"
    plt.savefig(p, dpi=150)
    print(f"  Saved {p}")
    plt.close()

    # ── Chart 4: Retry struggles ──────────────────────────────────────────
    rp = results["retry_patterns"]
    if rp["struggle_by_subcmd"]:
        items = rp["struggle_by_subcmd"].most_common()
        s_names = [n for n, _ in reversed(items)]
        s_counts = [c for _, c in reversed(items)]
        # Count error vs non-error struggles per subcommand
        err_by_sc = Counter()
        for s in rp["sequences"]:
            if s["subcommand"] != "status" and s["had_error"]:
                err_by_sc[s["subcommand"]] += 1

        s_err = [err_by_sc.get(n, 0) for n in s_names]
        s_ok = [c - e for c, e in zip(s_counts, s_err)]

        fig, ax = plt.subplots(figsize=(10, 5))
        ax.barh(s_names, s_ok, color=ORANGE, label="Retry (no error)")
        ax.barh(s_names, s_err, left=s_ok, color=RED, label="Retry (with error)")
        for i, c in enumerate(s_counts):
            ax.text(c + 0.3, i, str(c), va="center", fontsize=9)
        ax.set_xlabel("Number of retry sequences")
        ax.set_title("Agent Struggle Patterns by Subcommand\n"
                      "(Consecutive same-command sequences, excluding status)")
        ax.legend(loc="lower right")
        plt.tight_layout()
        p = output_dir / "agent_retry_struggles.png"
        plt.savefig(p, dpi=150)
        print(f"  Saved {p}")
        plt.close()

    # ── Chart 5: Error categories ─────────────────────────────────────────
    ec = results["error_categories"]
    if ec["categories"]:
        cats = ec["categories"].most_common()
        c_names = [n for n, _ in reversed(cats)]
        c_counts = [c for _, c in reversed(cats)]
        c_colors = [RED if n in PREVENTABLE_CATEGORIES else ORANGE if n in ("stale_id", "safety_guard") else BLUE for n in c_names]

        fig, ax = plt.subplots(figsize=(10, 5))
        bars = ax.barh(c_names, c_counts, color=c_colors)
        for i, (n, c) in enumerate(zip(c_names, c_counts)):
            pct = 100 * c / ec["total_errors"]
            tag = " [preventable]" if n in PREVENTABLE_CATEGORIES else ""
            ax.text(c + 0.3, i, f"{c} ({pct:.0f}%){tag}", va="center", fontsize=9)
        ax.set_xlabel("Error count")
        ax.set_title(f"Error Categories (Agent-Facing)\n"
                      f"{ec['preventable_pct']:.0f}% are preventable via CLI design improvements")
        # Legend
        from matplotlib.patches import Patch
        legend_elements = [Patch(facecolor=RED, label="Preventable"),
                           Patch(facecolor=ORANGE, label="Situational"),
                           Patch(facecolor=BLUE, label="Other/transient")]
        ax.legend(handles=legend_elements, loc="lower right")
        plt.tight_layout()
        p = output_dir / "agent_error_categories.png"
        plt.savefig(p, dpi=150)
        print(f"  Saved {p}")
        plt.close()

    # ── Chart 6: Error recovery donut ─────────────────────────────────────
    er = results["error_recovery"]
    if er["recovery"]:
        labels_map = {
            "adapted": ("Adapted approach", GREEN),
            "pivoted": ("Pivoted to other cmd", GREEN),
            "status_then_retry": ("Refreshed state first", BLUE),
            "blind_retry": ("Blind retry", RED),
            "no_followup": ("No followup", GRAY),
        }
        labels = []
        sizes = []
        colors = []
        for key in ["adapted", "pivoted", "status_then_retry", "blind_retry", "no_followup"]:
            count = er["recovery"].get(key, 0)
            if count > 0:
                lbl, col = labels_map[key]
                labels.append(f"{lbl} ({count})")
                sizes.append(count)
                colors.append(col)

        fig, ax = plt.subplots(figsize=(8, 8))
        wedges, texts, autotexts = ax.pie(
            sizes, labels=labels, colors=colors, autopct="%1.0f%%",
            pctdistance=0.8, startangle=90, wedgeprops=dict(width=0.4))
        for t in autotexts:
            t.set_fontsize(10)
        # Center text
        ax.text(0, 0, f"{er['recovery_rate']:.0f}%\nRecovery", ha="center", va="center",
                fontsize=18, fontweight="bold")
        ax.set_title("Agent Error Recovery Behavior")
        plt.tight_layout()
        p = output_dir / "agent_error_recovery.png"
        plt.savefig(p, dpi=150)
        print(f"  Saved {p}")
        plt.close()

    # ── Chart 7: Workflow transition heatmap ──────────────────────────────
    ws = results["workflow_sequences"]
    top = ws["top_subcmds"]
    if top:
        n = len(top)
        matrix = [[0] * n for _ in range(n)]
        for (src, dst), count in ws["transitions"].items():
            if src in top and dst in top:
                matrix[top.index(src)][top.index(dst)] = count

        fig, ax = plt.subplots(figsize=(10, 8))
        arr = np.array(matrix, dtype=float)
        im = ax.imshow(arr, cmap="Blues", aspect="auto")
        ax.set_xticks(range(n))
        ax.set_xticklabels(top, rotation=45, ha="right", fontsize=9)
        ax.set_yticks(range(n))
        ax.set_yticklabels(top, fontsize=9)
        ax.set_xlabel("Next command")
        ax.set_ylabel("Current command")
        ax.set_title("Command Transition Matrix\n(What follows what? Darker = more frequent)")
        # Annotate cells
        for i in range(n):
            for j in range(n):
                val = matrix[i][j]
                if val > 0:
                    color = "white" if val > arr.max() * 0.6 else "black"
                    ax.text(j, i, str(val), ha="center", va="center", fontsize=8, color=color)
        fig.colorbar(im, ax=ax, shrink=0.8)
        plt.tight_layout()
        p = output_dir / "agent_workflow_transitions.png"
        plt.savefig(p, dpi=150)
        print(f"  Saved {p}")
        plt.close()

    # ── Chart 8: Scorecard ────────────────────────────────────────────────
    sc = results["scorecard"]
    dims = [k for k in sc if k != "OVERALL"]
    scores = [sc[k] for k in dims]
    bar_colors = [GREEN if s >= 70 else ORANGE if s >= 40 else RED for s in scores]

    fig, ax = plt.subplots(figsize=(10, 5))
    y_pos = range(len(dims))
    ax.barh(list(reversed(dims)), list(reversed(scores)), color=list(reversed(bar_colors)))
    for i, (d, s) in enumerate(zip(reversed(dims), reversed(scores))):
        ax.text(s + 1, i, f"{s}/100", va="center", fontsize=11, fontweight="bold")
    ax.set_xlim(0, 110)
    ax.axvline(sc["OVERALL"], color="black", linestyle="--", linewidth=1.5,
               label=f"Overall: {sc['OVERALL']}/100")
    ax.set_xlabel("Score (0-100)")
    ax.set_title("Agent Friendliness Scorecard")
    ax.legend(loc="lower right", fontsize=11)
    plt.tight_layout()
    p = output_dir / "agent_friendliness_scorecard.png"
    plt.savefig(p, dpi=150)
    print(f"  Saved {p}")
    plt.close()

    print("All charts generated.")


# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# CLI
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

def main():
    parser = argparse.ArgumentParser(
        description="Analyze how agent-friendly the 'but' CLI is.",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  python3 but_agent_friendliness.py                  # full: report + charts
  python3 but_agent_friendliness.py --report-only    # text report only
  python3 but_agent_friendliness.py --charts-only    # charts only
  python3 but_agent_friendliness.py --output-dir /tmp/out
        """,
    )
    parser.add_argument("--report-only", action="store_true",
                        help="Print text report only, skip charts (no matplotlib needed)")
    parser.add_argument("--charts-only", action="store_true",
                        help="Generate charts only, skip text report")
    parser.add_argument("--output-dir", type=Path, default=DEFAULT_OUTPUT_DIR,
                        help=f"Directory containing but_usage.json and for chart output (default: {DEFAULT_OUTPUT_DIR})")
    args = parser.parse_args()

    if args.report_only and args.charts_only:
        parser.error("Cannot use both --report-only and --charts-only")

    # Load and prepare data
    data = load_data(args.output_dir)
    sessions = group_by_session(data)

    # Run all analyses
    results = {
        "status_overhead": analyze_status_overhead(data, sessions),
        "json_gaps": analyze_json_gaps(data),
        "pipe_workarounds": analyze_pipe_workarounds(data),
        "retry_patterns": analyze_retry_patterns(sessions),
        "error_categories": categorize_errors(data),
        "error_recovery": analyze_error_recovery(sessions),
        "workflow_sequences": analyze_workflow_sequences(data, sessions),
    }
    results["scorecard"] = generate_scorecard(results)

    if not args.charts_only:
        print_report(results)

    if not args.report_only:
        print()
        generate_all_charts(results, args.output_dir)


if __name__ == "__main__":
    main()