core-runtime 0.1.1__py3-none-any.whl

cli/commands/inspect/_helpers.py

@@ -0,0 +1,226 @@
+# src/cli/commands/inspect/_helpers.py
+"""
+Shared helper functions for inspect commands.
+
+Functions used across multiple inspect modules:
+- _as_bool: Normalize repository return types to boolean
+- _show_session_trace: Display detailed session information
+- _show_recent_traces: Tabular display of recent traces
+- _show_pattern_traces: Pattern-specific trace analysis
+- _show_statistics: Aggregate statistics display
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from rich.console import Console
+from rich.table import Table
+
+
+if TYPE_CHECKING:
+    from body.infrastructure.repositories.decision_trace_repository import (
+        DecisionTraceRepository,
+    )
+console = Console()
+
+
+def _as_bool(value: Any) -> bool:
+    """
+    Normalize repository return types (bool/str/int/None) into a boolean.
+
+    Supports common representations like True/"true"/"1"/1.
+
+    Args:
+        value: Value to convert to boolean
+
+    Returns:
+        Boolean interpretation of value
+    """
+    if isinstance(value, bool):
+        return value
+    if value is None:
+        return False
+    if isinstance(value, (int, float)):
+        return value != 0
+    if isinstance(value, str):
+        return value.strip().lower() in {"true", "1", "yes", "y", "t"}
+    return bool(value)
+
+
+async def _show_session_trace(
+    repo: DecisionTraceRepository, session_id: str, details: bool
+) -> None:
+    """
+    Show a specific session trace with optional details.
+
+    Args:
+        repo: Decision trace repository
+        session_id: Session ID to display
+        details: Show full decision details
+    """
+    trace = await repo.get_by_session_id(session_id)
+    if not trace:
+        console.print(f"[yellow]No trace found for session: {session_id}[/yellow]")
+        return
+    console.print(f"\n[bold cyan]Session: {trace.session_id}[/bold cyan]")
+    console.print(f"Agent: {trace.agent_name}")
+    console.print(f"Goal: {trace.goal or 'none'}")
+    console.print(f"Decisions: {trace.decision_count}")
+    console.print(f"Created: {trace.created_at}")
+    if _as_bool(getattr(trace, "has_violations", False)):
+        console.print(f"[red]Violations: {trace.violation_count}[/red]")
+    if details:
+        console.print("\n[bold]Decisions:[/bold]")
+        for i, decision in enumerate(trace.decisions or [], 1):
+            agent = decision.get("agent", "none")
+            d_type = decision.get("decision_type", "none")
+            console.print(f"\n[cyan]{i}. {agent} - {d_type}[/cyan]")
+            console.print(f"  Rationale: {decision.get('rationale', 'none')}")
+            console.print(f"  Chosen: {decision.get('chosen_action', 'none')}")
+            confidence = decision.get("confidence")
+            if isinstance(confidence, (int, float)):
+                console.print(f"  Confidence: {confidence}")
+            else:
+                console.print("  Confidence: none")
+
+
+async def _show_recent_traces(
+    repo: DecisionTraceRepository,
+    limit: int,
+    agent: str | None,
+    failures_only: bool,
+    details: bool,
+) -> None:
+    """
+    Show recent traces with optional filtering in tabular format.
+
+    Args:
+        repo: Decision trace repository
+        limit: Maximum number of traces to show
+        agent: Filter by agent name
+        failures_only: Show only failed traces
+        details: Show detailed info for most recent
+    """
+    traces = await repo.get_recent(
+        limit=limit, agent_name=agent, failures_only=failures_only
+    )
+    if not traces:
+        console.print("[yellow]No traces found matching criteria[/yellow]")
+        return
+    table = Table(title=f"Recent Decision Traces ({len(traces)})")
+    table.add_column("Session", style="cyan")
+    table.add_column("Agent", style="green")
+    table.add_column("Decisions", justify="right")
+    table.add_column("Duration", justify="right")
+    table.add_column("Status")
+    table.add_column("Created", style="dim")
+    for trace in traces:
+        duration_ms = getattr(trace, "duration_ms", None)
+        duration = (
+            f"{duration_ms / 1000:.1f}s"
+            if isinstance(duration_ms, (int, float))
+            else "none"
+        )
+        has_violations = _as_bool(getattr(trace, "has_violations", False))
+        status = "❌ Violations" if has_violations else "✅ Clean"
+        created_at = getattr(trace, "created_at", None)
+        created_str = created_at.strftime("%Y-%m-%d %H:%M") if created_at else "none"
+        table.add_row(
+            (trace.session_id or "")[:12],
+            trace.agent_name or "none",
+            str(getattr(trace, "decision_count", 0)),
+            duration,
+            status,
+            created_str,
+        )
+    console.print(table)
+    if details and traces:
+        console.print("\n[dim]Showing details for most recent trace...[/dim]")
+        await _show_session_trace(repo, traces[0].session_id, True)
+
+
+async def _show_pattern_traces(
+    repo: DecisionTraceRepository, pattern: str, limit: int, details: bool
+) -> None:
+    """
+    Show traces that used a specific pattern.
+
+    Args:
+        repo: Decision trace repository
+        pattern: Pattern ID to filter by
+        limit: Maximum number of traces
+        details: Show detailed view
+    """
+    traces = await repo.get_pattern_stats(pattern, limit)
+    if not traces:
+        console.print(f"[yellow]No traces found using pattern: {pattern}[/yellow]")
+        return
+    console.print(f"\n[bold cyan]Traces using pattern: {pattern}[/bold cyan]")
+    console.print(f"Found: {len(traces)} traces\n")
+    violations = sum(1 for t in traces if _as_bool(getattr(t, "has_violations", False)))
+    success_rate = (len(traces) - violations) / len(traces) * 100 if traces else 0
+    console.print(f"Success rate: [green]{success_rate}%[/green]")
+    console.print(f"Violations: [red]{violations}[/red] / {len(traces)}\n")
+    if not details:
+        table = Table()
+        table.add_column("Session", style="cyan")
+        table.add_column("Agent")
+        table.add_column("Status")
+        table.add_column("Created", style="dim")
+        for trace in traces[:20]:
+            status = "❌" if _as_bool(getattr(trace, "has_violations", False)) else "✅"
+            created_at = getattr(trace, "created_at", None)
+            created_str = (
+                created_at.strftime("%Y-%m-%d %H:%M") if created_at else "none"
+            )
+            table.add_row(
+                (trace.session_id or "")[:12],
+                trace.agent_name or "none",
+                status,
+                created_str,
+            )
+        console.print(table)
+
+
+async def _show_statistics(
+    repo: DecisionTraceRepository, pattern: str | None, days: int = 7
+) -> None:
+    """
+    Show decision trace statistics.
+
+    Args:
+        repo: Decision trace repository
+        pattern: Optional pattern to analyze
+        days: Number of days to include
+    """
+    console.print(
+        f"\n[bold cyan]Decision Trace Statistics (Last {days} days)[/bold cyan]\n"
+    )
+    agent_counts = await repo.count_by_agent(days)
+    if not agent_counts:
+        console.print("[yellow]No traces found in the specified time range[/yellow]")
+        return
+    table = Table(title="Traces by Agent")
+    table.add_column("Agent", style="cyan")
+    table.add_column("Count", justify="right")
+    for agent_name, count in sorted(
+        agent_counts.items(), key=lambda x: x[1], reverse=True
+    ):
+        table.add_row(agent_name, str(count))
+    console.print(table)
+    if pattern:
+        traces = await repo.get_pattern_stats(pattern, 1000)
+        if traces:
+            console.print(f"\n[bold]Pattern: {pattern}[/bold]")
+            violations = sum(
+                1 for t in traces if _as_bool(getattr(t, "has_violations", False))
+            )
+            success_rate = (
+                (len(traces) - violations) / len(traces) * 100 if traces else 0
+            )
+            console.print(f"Total uses: {len(traces)}")
+            console.print(f"Success rate: [green]{success_rate}%[/green]")
+            console.print(f"Violations: [red]{violations}[/red]")
+        else:
+            console.print(f"\n[yellow]No traces found for pattern: {pattern}[/yellow]")

cli/commands/inspect/analysis.py

@@ -0,0 +1,158 @@
+# src/cli/commands/inspect/analysis.py
+"""Code analysis commands.
+
+Thin clients over /v1/analysis/{clusters,duplicates,common-knowledge}
+(ADR-057 D3). Rendering stays inline.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from api.cli import CoreApiClient
+from cli.utils import core_command, deprecated_command
+from shared.cli.command_meta import CommandBehavior, CommandLayer, command_meta
+
+
+logger = logging.getLogger(__name__)
+console = Console()
+
+
+@command_meta(
+    canonical_name="inspect.clusters",
+    behavior=CommandBehavior.READ,
+    layer=CommandLayer.BODY,
+    summary="Finds and displays semantic capability clusters",
+)
+@core_command(dangerous=False, requires_context=False)
+# ID: 9c6d2c21-ed6b-4bf0-bbf2-d02b5a8a9d72
+async def clusters_cmd(
+    ctx: typer.Context,
+    n_clusters: int = typer.Option(
+        25, "--n-clusters", "-n", help="The number of clusters to find."
+    ),
+) -> None:
+    """Finds and displays semantic capability clusters."""
+    _ = ctx
+    client = CoreApiClient()
+    payload = await client.analysis_clusters(limit=n_clusters)
+    if not payload.get("available", True):
+        console.print("[yellow]Cluster inspector not available on the server.[/yellow]")
+        return
+    clusters = payload.get("clusters") or []
+    if not clusters:
+        console.print("[yellow]No clusters found.[/yellow]")
+        return
+    console.print(f"[green]Found {len(clusters)} clusters:[/green]")
+    for cluster in clusters:
+        topic = (
+            cluster.get("topic", "Unknown")
+            if isinstance(cluster, dict)
+            else str(cluster)
+        )
+        size = cluster.get("size", 0) if isinstance(cluster, dict) else ""
+        console.print(f"- {topic}: {size} items")
+
+
+@command_meta(
+    canonical_name="inspect.find-clusters",
+    behavior=CommandBehavior.READ,
+    layer=CommandLayer.BODY,
+    summary="DEPRECATED alias for 'inspect clusters'",
+    aliases=["clusters"],
+)
+@core_command(dangerous=False, requires_context=False)
+# ID: 27c63367-a75d-4fbe-bc3e-aebfa1542549
+async def find_clusters_cmd(
+    ctx: typer.Context,
+    n_clusters: int = typer.Option(
+        25, "--n-clusters", "-n", help="The number of clusters to find."
+    ),
+) -> None:
+    """DEPRECATED alias for `inspect clusters`."""
+    deprecated_command("inspect find-clusters", "inspect clusters")
+    await clusters_cmd(ctx, n_clusters=n_clusters)
+
+
+@command_meta(
+    canonical_name="inspect.duplicates",
+    behavior=CommandBehavior.VALIDATE,
+    layer=CommandLayer.BODY,
+    summary="Runs semantic code duplication check",
+)
+@core_command(dangerous=False, requires_context=False)
+# ID: cb72e5c2-4233-4de3-b784-4a3bf02ff34d
+async def duplicates_command(
+    ctx: typer.Context,
+    threshold: float = typer.Option(
+        0.8,
+        "--threshold",
+        "-t",
+        help="The minimum similarity score to consider a duplicate.",
+        min=0.5,
+        max=1.0,
+    ),
+) -> None:
+    """Runs the semantic code duplication check via the API."""
+    _ = ctx
+    client = CoreApiClient()
+    payload = await client.analysis_duplicates(threshold=threshold)
+    if not payload.get("ok", False):
+        console.print(
+            f"[red]Duplicates analysis failed: {payload.get('error', 'unknown')}[/red]"
+        )
+        raise typer.Exit(code=1)
+    note = payload.get("note")
+    if note:
+        console.print(f"[dim]{note}[/dim]")
+    console.print(
+        f"[green]✅ Duplicates check completed at threshold {threshold}.[/green]"
+    )
+
+
+@command_meta(
+    canonical_name="inspect.common-knowledge",
+    behavior=CommandBehavior.READ,
+    layer=CommandLayer.BODY,
+    summary="Finds structurally identical helper functions that can be consolidated",
+)
+@core_command(dangerous=False, requires_context=False)
+# ID: 508b7556-2747-4822-8772-7a354bd82760
+async def common_knowledge_cmd(ctx: typer.Context) -> None:
+    """Finds DRY-violation candidates via /v1/analysis/common-knowledge."""
+    _ = ctx
+    client = CoreApiClient()
+    payload = await client.analysis_common_knowledge()
+    if not payload.get("available", True):
+        console.print(
+            "[yellow]Common-knowledge inspector not available on the server.[/yellow]"
+        )
+        return
+    candidates = payload.get("candidates") or []
+    if not candidates:
+        console.print("[green]No DRY-violation candidates found.[/green]")
+        return
+    table = Table(title=f"DRY Candidates ({len(candidates)})")
+    table.add_column("Candidate", style="cyan")
+    table.add_column("Occurrences", justify="right")
+    for candidate in candidates:
+        if isinstance(candidate, dict):
+            table.add_row(
+                str(candidate.get("symbol", candidate.get("id", ""))),
+                str(candidate.get("occurrences", "")),
+            )
+        else:
+            table.add_row(str(candidate), "")
+    console.print(table)
+
+
+analysis_commands = [
+    {"name": "clusters", "func": clusters_cmd},
+    {"name": "find-clusters", "func": find_clusters_cmd},
+    {"name": "duplicates", "func": duplicates_command},
+    {"name": "common-knowledge", "func": common_knowledge_cmd},
+]

cli/commands/inspect/decisions.py

@@ -0,0 +1,140 @@
+# src/cli/commands/inspect/decisions.py
+"""Decision trace inspection commands.
+
+Thin client over /v1/decisions and /v1/decisions/patterns (ADR-057 D3).
+Rendering is inline (the legacy `_helpers` module operated on an
+ORM-shaped DecisionTraceRepository; the API payloads have a different
+shape and are simpler to render in place).
+"""
+
+from __future__ import annotations
+
+import logging
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from api.cli import CoreApiClient
+from cli.utils import core_command
+from shared.cli.command_meta import CommandBehavior, CommandLayer, command_meta
+
+
+logger = logging.getLogger(__name__)
+console = Console()
+
+
+@command_meta(
+    canonical_name="inspect.decisions",
+    behavior=CommandBehavior.READ,
+    layer=CommandLayer.BODY,
+    summary="Inspect decision traces from autonomous operations",
+)
+@core_command(dangerous=False, requires_context=False)
+# ID: d50838a6-b4f7-4ad5-ac29-3a121f65e91d
+async def decisions_cmd(
+    ctx: typer.Context,
+    recent: int = typer.Option(
+        10, "--recent", "-n", help="Number of recent traces to show"
+    ),
+    session_id: str | None = typer.Option(
+        None, "--session", "-s", help="Show specific session by ID"
+    ),
+    agent: str | None = typer.Option(
+        None, "--agent", "-a", help="Filter by agent name"
+    ),
+    pattern: str | None = typer.Option(
+        None, "--pattern", "-p", help="Filter by pattern used"
+    ),
+    failures_only: bool = typer.Option(
+        False, "--failures-only", "-f", help="Show only traces with violations"
+    ),
+    stats: bool = typer.Option(
+        False, "--stats", help="Show statistics instead of traces"
+    ),
+    details: bool = typer.Option(
+        False, "--details", "-d", help="Show full decision details"
+    ),
+) -> None:
+    """Inspect decision traces via /v1/decisions."""
+    _ = ctx
+    _ = failures_only  # Server-side filter pending — exposed via future query arg.
+    client = CoreApiClient()
+
+    if stats:
+        payload = await client.decisions_patterns(days=max(recent, 1))
+        _render_patterns(payload)
+        return
+
+    list_payload = await client.decisions_list(
+        session_id=session_id,
+        agent=agent,
+        pattern=pattern,
+        limit=recent,
+    )
+    _render_traces(list_payload, details=details)
+
+
+def _render_traces(payload: dict, *, details: bool) -> None:
+    """Render the decisions list JSON returned by /v1/decisions."""
+    traces = payload.get("traces", [])
+    if not traces:
+        console.print("[yellow]No decision traces found.[/yellow]")
+        return
+
+    console.print(f"[cyan]Found {payload.get('count', len(traces))} trace(s)[/cyan]\n")
+    table = Table(title="Decision Traces")
+    table.add_column("Session", style="cyan")
+    table.add_column("Agent", style="magenta")
+    table.add_column("Pattern", style="yellow")
+    table.add_column("Outcome", style="green")
+    table.add_column("Created", style="dim")
+    for trace in traces:
+        table.add_row(
+            str(trace.get("session_id") or "")[:12],
+            str(trace.get("agent_id") or ""),
+            str(trace.get("pattern") or ""),
+            str(trace.get("outcome") or ""),
+            str(trace.get("created_at") or "")[:19],
+        )
+    console.print(table)
+
+    if details:
+        for trace in traces:
+            console.print(f"\n[bold cyan]Session {trace.get('session_id')}[/bold cyan]")
+            summary = trace.get("summary")
+            if summary:
+                console.print(summary)
+
+
+def _render_patterns(payload: dict) -> None:
+    """Render the patterns aggregate returned by /v1/decisions/patterns."""
+    patterns = payload.get("patterns") or []
+    if not patterns:
+        console.print("[yellow]No pattern statistics found.[/yellow]")
+        return
+
+    console.print(f"[cyan]Lookback: {payload.get('days', 7)} day(s)[/cyan]\n")
+    table = Table(title="Pattern Classification Stats")
+    table.add_column("Pattern", style="cyan")
+    table.add_column("Count", justify="right")
+    table.add_column("Success Rate", justify="right")
+    iterable = (
+        patterns.items()
+        if isinstance(patterns, dict)
+        else ((p.get("pattern", ""), p) for p in patterns)
+    )
+    for name, stats_obj in iterable:
+        if isinstance(stats_obj, dict):
+            count = stats_obj.get("count", 0)
+            success_rate = stats_obj.get("success_rate", 0)
+        else:
+            count = stats_obj
+            success_rate = 0
+        table.add_row(str(name), str(count), f"{float(success_rate):.1f}%")
+    console.print(table)
+
+
+decisions_commands = [
+    {"name": "decisions", "func": decisions_cmd},
+]

cli/commands/inspect/diagnostics.py

@@ -0,0 +1,126 @@
+# src/cli/commands/inspect/diagnostics.py
+"""System diagnostics commands.
+
+Thin clients over /v1/analysis/{command-tree,test-targets} (ADR-057 D3).
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+import typer
+from rich.console import Console
+from rich.table import Table
+from rich.tree import Tree
+
+from api.cli import CoreApiClient
+from cli.utils import core_command
+from shared.cli.command_meta import CommandBehavior, CommandLayer, command_meta
+
+
+logger = logging.getLogger(__name__)
+console = Console()
+
+
+@command_meta(
+    canonical_name="inspect.command-tree",
+    behavior=CommandBehavior.READ,
+    layer=CommandLayer.BODY,
+    summary="Displays a hierarchical tree view of all available CLI commands",
+)
+@core_command(dangerous=False, requires_context=False)
+# ID: d7718166-cf0c-4ec3-b6e5-9f4804d56d1b
+async def command_tree_cmd(ctx: typer.Context) -> None:
+    """Display the CLI command hierarchy served by the API."""
+    _ = ctx
+    console.print("Building CLI Command Tree...")
+    client = CoreApiClient()
+    payload = await client.analysis_command_tree()
+    if not payload.get("available", True):
+        console.print(
+            f"[yellow]Command-tree backend unavailable: "
+            f"{payload.get('error', 'unknown')}[/yellow]"
+        )
+        return
+
+    tree_data = payload.get("commands") or []
+    root = Tree("[bold blue]CORE CLI[/bold blue]")
+
+    # ID: 642514fc-30cb-4d57-b3fd-8f0b2461e77c
+    def add_nodes(nodes: list[dict[str, Any]], parent: Tree) -> None:
+        """Recursively add nodes to the Rich tree."""
+        for node in nodes:
+            label = f"[bold]{node['name']}[/bold]"
+            if node.get("help"):
+                label += f": [dim]{node['help']}[/dim]"
+            branch = parent.add(label)
+            children = node.get("children")
+            if children:
+                add_nodes(children, branch)
+
+    add_nodes(tree_data, root)
+    console.print(root)
+
+
+@command_meta(
+    canonical_name="inspect.test-targets",
+    behavior=CommandBehavior.VALIDATE,
+    layer=CommandLayer.BODY,
+    summary="Identifies and classifies functions as SIMPLE or COMPLEX test targets",
+)
+@core_command(dangerous=False, requires_context=False)
+# ID: ab41749f-0338-49c3-8a1e-9812a4f1b3a2
+async def inspect_test_targets(
+    ctx: typer.Context,
+    file_path: Path = typer.Argument(
+        ...,
+        help="The path to the Python file to analyze.",
+        exists=True,
+        dir_okay=False,
+        resolve_path=True,
+    ),
+) -> None:
+    """Classify functions as SIMPLE or COMPLEX test targets via the API."""
+    _ = ctx
+    _ = file_path  # /v1/analysis/test-targets scans the canonical src/ tree.
+    client = CoreApiClient()
+    payload = await client.analysis_test_targets()
+    if not payload.get("available", True):
+        console.print(
+            f"[yellow]Test-target classifier unavailable: "
+            f"{payload.get('error', 'unknown')}[/yellow]"
+        )
+        return
+
+    targets = payload.get("targets") or []
+    if not targets:
+        console.print("[yellow]No suitable public functions found to analyze.[/yellow]")
+        return
+
+    table = Table(
+        title="Test Target Analysis", header_style="bold magenta", show_header=True
+    )
+    table.add_column("Function", style="cyan")
+    table.add_column("Complexity", style="magenta", justify="right")
+    table.add_column("Classification", style="yellow")
+    table.add_column("Reason")
+    for target in targets:
+        if not isinstance(target, dict):
+            continue
+        classification = str(target.get("classification", ""))
+        style = "green" if classification == "SIMPLE" else "red"
+        table.add_row(
+            str(target.get("name", "")),
+            str(target.get("complexity", "")),
+            f"[{style}]{classification}[/{style}]",
+            str(target.get("reason", "")),
+        )
+    console.print(table)
+
+
+diagnostics_commands = [
+    {"name": "command-tree", "func": command_tree_cmd},
+    {"name": "test-targets", "func": inspect_test_targets},
+]