core-runtime 0.1.1__py3-none-any.whl

cli/commands/inspect/drift.py

@@ -0,0 +1,100 @@
+# src/cli/commands/inspect/drift.py
+"""Drift detection commands.
+
+Thin clients over GET /v1/status/drift (ADR-057 D3). The legacy
+inspect-side commands stay as deprecated aliases that forward to
+`core-admin status drift {scope}`; the `register_guard` helper still
+lives in `cli.commands.guard` (the local CLI module, not
+`mind.enforcement.guard_cli` — that import was a layer inversion).
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Coroutine
+
+import typer
+
+from cli.commands.guard import register_guard
+from cli.utils import core_command, deprecated_command
+from shared.cli.command_meta import CommandBehavior, CommandLayer, command_meta
+
+
+logger = logging.getLogger(__name__)
+
+
+def _try_forward_to_status_drift(scope: str, ctx: typer.Context) -> bool:
+    """Best-effort forwarder to `core-admin status drift {scope}`.
+
+    Returns False if forwarding unavailable (so the caller can fall back).
+    """
+    _ = ctx
+    try:
+        from cli.commands.status import drift_cmd as status_drift_cmd
+    except Exception as exc:
+        logger.debug("inspect: status drift forward unavailable: %s", exc)
+        return False
+
+    try:
+        maybe = status_drift_cmd(scope=scope)  # type: ignore[call-arg]
+        if isinstance(maybe, Coroutine):
+            return False
+        return True
+    except Exception as exc:
+        logger.debug("inspect: status drift forward failed: %s", exc)
+        return False
+
+
+@command_meta(
+    canonical_name="inspect.drift.symbol",
+    behavior=CommandBehavior.READ,
+    layer=CommandLayer.BODY,
+    summary="Detects drift between filesystem symbols and database symbols",
+    aliases=["symbol-drift"],
+)
+@core_command(dangerous=False, requires_context=False)
+# ID: 98134193-955b-4b10-a08c-8d8580e3f3bd
+async def symbol_drift_cmd(ctx: typer.Context) -> None:
+    """DEPRECATED alias. Use: core-admin status drift symbol."""
+    deprecated_command("inspect symbol-drift", "status drift symbol")
+    if _try_forward_to_status_drift("symbol", ctx):
+        return
+    # Fallback to the consolidated drift surface via cli.commands.status.
+    from cli.commands.status import drift_cmd as status_drift_cmd
+
+    await status_drift_cmd(ctx, scope="symbol")
+
+
+@command_meta(
+    canonical_name="inspect.drift.vector",
+    behavior=CommandBehavior.READ,
+    layer=CommandLayer.BODY,
+    summary="Verifies synchronization between PostgreSQL and Qdrant",
+    aliases=["vector-drift"],
+)
+@core_command(dangerous=False, requires_context=False)
+# ID: f08e0006-1485-4118-8e75-f396878faaf5
+async def vector_drift_command(ctx: typer.Context) -> None:
+    """DEPRECATED alias. Use: core-admin status drift vector."""
+    deprecated_command("inspect vector-drift", "status drift vector")
+    if _try_forward_to_status_drift("vector", ctx):
+        return
+    from cli.commands.status import drift_cmd as status_drift_cmd
+
+    await status_drift_cmd(ctx, scope="vector")
+
+
+drift_commands = [
+    {"name": "symbol-drift", "func": symbol_drift_cmd},
+    {"name": "vector-drift", "func": vector_drift_command},
+]
+
+
+# ID: 7bc2df06-2d2d-47f4-9c61-3e7045009c5a
+def register_drift_commands(app: typer.Typer) -> None:
+    """Register drift commands including guard commands.
+
+    Guard commands are registered separately via cli.commands.guard.register_guard
+    (a local CLI module, not the mind-side guard_cli helper).
+    """
+    register_guard(app)

cli/commands/inspect/patterns.py

@@ -0,0 +1,102 @@
+# src/cli/commands/inspect/patterns.py
+"""Pattern classification analysis commands.
+
+Thin client over /v1/decisions/patterns (ADR-057 D3). Previously this
+command walked `reports/decisions/trace_*.json` server-side; the API now
+aggregates the same data so the CLI is pure presentation.
+"""
+
+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.patterns",
+    behavior=CommandBehavior.READ,
+    layer=CommandLayer.BODY,
+    summary="Analyze pattern classification and violations across decision traces",
+)
+@core_command(dangerous=False, requires_context=False)
+# ID: 7c9e7493-0e47-430b-ae30-753ae0cea7c3
+async def patterns_cmd(
+    ctx: typer.Context,
+    last: int = typer.Option(
+        10, "--last", "-l", help="Lookback window in days (default: 10)"
+    ),
+    pattern: str | None = typer.Option(
+        None,
+        "--pattern",
+        "-p",
+        help="Filter by specific pattern (e.g., 'action_pattern')",
+    ),
+):
+    """Analyze pattern classification via /v1/decisions/patterns."""
+    _ = ctx
+    console.print("\n[bold blue]🔍 Pattern Classification Analysis[/bold blue]\n")
+
+    client = CoreApiClient()
+    payload = await client.decisions_patterns(days=max(last, 1))
+    patterns = payload.get("patterns") or {}
+
+    if not patterns:
+        console.print("[yellow]No pattern data found.[/yellow]")
+        return
+
+    console.print(f"[cyan]Lookback: {payload.get('days', last)} day(s)[/cyan]\n")
+
+    table = Table(title="Pattern Classification Summary")
+    table.add_column("Pattern", style="cyan")
+    table.add_column("Uses", justify="right")
+    table.add_column("Violations", justify="right")
+    table.add_column("Success Rate", justify="right")
+    table.add_column("Files", justify="right")
+
+    iterable = (
+        patterns.items()
+        if isinstance(patterns, dict)
+        else ((p.get("pattern", ""), p) for p in patterns)
+    )
+    rendered = 0
+    for pattern_id, stats in iterable:
+        if pattern and pattern_id != pattern:
+            continue
+        if isinstance(stats, dict):
+            uses = int(stats.get("count", 0))
+            violations = int(stats.get("violations", 0))
+            files_count = int(stats.get("files", 0))
+        else:
+            uses, violations, files_count = int(stats or 0), 0, 0
+        success_rate = (uses - violations) / uses * 100 if uses > 0 else 0
+        status_color = (
+            "green" if success_rate > 80 else "yellow" if success_rate > 50 else "red"
+        )
+        table.add_row(
+            str(pattern_id),
+            str(uses),
+            str(violations),
+            f"[{status_color}]{success_rate:.1f}%[/{status_color}]",
+            str(files_count),
+        )
+        rendered += 1
+
+    if rendered == 0:
+        console.print("[yellow]No patterns matched filter.[/yellow]")
+        return
+
+    console.print(table)
+
+
+patterns_commands = [{"name": "patterns", "func": patterns_cmd}]

cli/commands/inspect/refusals.py

@@ -0,0 +1,211 @@
+# src/cli/commands/inspect/refusals.py
+"""Constitutional refusal inspection commands.
+
+Thin clients over /v1/refusals and /v1/refusals/stats (ADR-057 D3).
+Default limits are hardcoded CLI options now — they were previously read
+from `shared.infrastructure.intent.operational_config.load_operational_config`,
+which is a `shared.*` reach across the CLI boundary.
+"""
+
+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()
+
+
+_DEFAULT_REFUSAL_LIMIT = 20
+_DEFAULT_BY_TYPE_LIMIT = 50
+
+
+@command_meta(
+    canonical_name="inspect.refusals",
+    behavior=CommandBehavior.READ,
+    layer=CommandLayer.BODY,
+    summary="List recent constitutional refusals",
+)
+@core_command(dangerous=False, requires_context=False)
+# ID: e15b2f7c-2784-4056-b3f8-5dc79aba9537
+async def refusals_list_cmd(
+    ctx: typer.Context,
+    limit: int = typer.Option(
+        _DEFAULT_REFUSAL_LIMIT,
+        "--limit",
+        "-n",
+        help="Maximum records to show",
+    ),
+    refusal_type: str | None = typer.Option(
+        None,
+        "--type",
+        "-t",
+        help="Filter by type (boundary, confidence, extraction, etc.)",
+    ),
+    component: str | None = typer.Option(
+        None, "--component", "-c", help="Filter by component ID"
+    ),
+    details: bool = typer.Option(
+        False, "--details", "-d", help="Show detailed information"
+    ),
+):
+    """List recent constitutional refusals via the API."""
+    _ = ctx
+    _ = component  # /v1/refusals doesn't currently expose a component filter.
+    client = CoreApiClient()
+    payload = await client.refusals_list(
+        refusal_type=refusal_type, session_id=None, limit=limit
+    )
+    _render_refusals(payload, details=details)
+
+
+@command_meta(
+    canonical_name="inspect.refusal-stats",
+    behavior=CommandBehavior.READ,
+    layer=CommandLayer.BODY,
+    summary="Show refusal statistics and trends",
+)
+@core_command(dangerous=False, requires_context=False)
+# ID: 212e0adc-7f66-4e42-9d03-2841309ef823
+async def refusals_stats_cmd(
+    ctx: typer.Context,
+    days: int = typer.Option(
+        7, "--days", "-d", help="Number of days to analyze (default: 7)"
+    ),
+):
+    """Show refusal statistics and trends via /v1/refusals/stats."""
+    _ = ctx
+    client = CoreApiClient()
+    payload = await client.refusals_stats(days=days)
+    _render_stats(payload)
+
+
+@command_meta(
+    canonical_name="inspect.refusals-by-type",
+    behavior=CommandBehavior.READ,
+    layer=CommandLayer.BODY,
+    summary="Show refusals of a specific type",
+)
+@core_command(dangerous=False, requires_context=False)
+# ID: c223a4db-5da5-4089-803c-7b24f0e9e72a
+async def refusals_by_type_cmd(
+    ctx: typer.Context,
+    refusal_type: str = typer.Argument(
+        ...,
+        help="Refusal type (boundary, confidence, extraction, quality, assumption, capability)",
+    ),
+    limit: int = typer.Option(
+        _DEFAULT_BY_TYPE_LIMIT,
+        "--limit",
+        "-n",
+        help="Maximum records to show",
+    ),
+):
+    """Show refusals of a specific type."""
+    _ = ctx
+    client = CoreApiClient()
+    payload = await client.refusals_list(
+        refusal_type=refusal_type, session_id=None, limit=limit
+    )
+    _render_refusals(payload, details=False)
+
+
+@command_meta(
+    canonical_name="inspect.refusals-by-session",
+    behavior=CommandBehavior.READ,
+    layer=CommandLayer.BODY,
+    summary="Show all refusals for a specific decision trace session",
+)
+@core_command(dangerous=False, requires_context=False)
+# ID: 6e93b8a7-64e6-4c76-bded-429f6f65f2ee
+async def refusals_by_session_cmd(
+    ctx: typer.Context,
+    session_id: str = typer.Argument(..., help="Decision trace session ID"),
+):
+    """Show all refusals for a specific decision trace session."""
+    _ = ctx
+    client = CoreApiClient()
+    payload = await client.refusals_list(
+        refusal_type=None,
+        session_id=session_id,
+        limit=_DEFAULT_BY_TYPE_LIMIT,
+    )
+    _render_refusals(payload, details=True)
+
+
+def _render_refusals(payload: dict, *, details: bool) -> None:
+    """Render the refusals list returned by /v1/refusals."""
+    refusals = payload.get("refusals", [])
+    if not refusals:
+        console.print("[yellow]No refusals found.[/yellow]")
+        return
+
+    console.print(
+        f"[cyan]Found {payload.get('count', len(refusals))} refusal(s)[/cyan]\n"
+    )
+    table = Table(title="Constitutional Refusals")
+    table.add_column("ID", style="dim")
+    table.add_column("Component", style="cyan")
+    table.add_column("Phase", style="magenta")
+    table.add_column("Type", style="yellow")
+    table.add_column("Created", style="dim")
+    for refusal in refusals:
+        table.add_row(
+            str(refusal.get("id") or "")[:8],
+            str(refusal.get("component_id") or ""),
+            str(refusal.get("phase") or ""),
+            str(refusal.get("refusal_type") or ""),
+            str(refusal.get("created_at") or "")[:19],
+        )
+    console.print(table)
+
+    if details:
+        for refusal in refusals:
+            console.print(
+                f"\n[bold cyan]{refusal.get('component_id')} — "
+                f"{refusal.get('refusal_type')}[/bold cyan]"
+            )
+            reason = refusal.get("reason")
+            if reason:
+                console.print(f"Reason: {reason}")
+            suggested = refusal.get("suggested_action")
+            if suggested:
+                console.print(f"Suggested: {suggested}")
+
+
+def _render_stats(payload: dict) -> None:
+    """Render /v1/refusals/stats payload."""
+    counts = payload.get("counts_by_type") or {}
+    stats = payload.get("stats") or {}
+    console.print(f"[cyan]Lookback: {payload.get('days', 7)} day(s)[/cyan]\n")
+
+    if counts:
+        table = Table(title="Refusals by Type")
+        table.add_column("Type", style="cyan")
+        table.add_column("Count", justify="right")
+        for refusal_type, count in sorted(
+            counts.items(), key=lambda x: x[1], reverse=True
+        ):
+            table.add_row(str(refusal_type), str(count))
+        console.print(table)
+
+    if stats:
+        console.print("\n[bold]Aggregate stats:[/bold]")
+        for key, value in stats.items():
+            console.print(f"  {key}: {value}")
+
+
+refusals_commands = [
+    {"name": "refusals", "func": refusals_list_cmd},
+    {"name": "refusal-stats", "func": refusals_stats_cmd},
+    {"name": "refusals-by-type", "func": refusals_by_type_cmd},
+    {"name": "refusals-by-session", "func": refusals_by_session_cmd},
+]

cli/commands/inspect/repo_census.py

@@ -0,0 +1,175 @@
+# src/cli/commands/inspect/repo_census.py
+"""
+CIM-0: Repository Structural Census command.
+
+Thin client over /v1/census/* (ADR-058 D1). The API runs `CensusService`,
+`BaselineManager`, and `DiffEngine` server-side; the CLI dispatches,
+polls the async run, and renders the result payload.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from api.cli import CoreApiClient
+from cli.utils import core_command
+
+
+logger = logging.getLogger(__name__)
+console = Console()
+
+
+@core_command(dangerous=False, requires_context=False)
+# ID: 57d975ad-ad77-453a-a7c4-9779eaa9e542
+async def repo_census_cmd(
+    ctx: typer.Context,
+    path: Path = typer.Option(
+        None,
+        "--path",
+        "-p",
+        help="Repository root to inspect (server-side: API resolves repo root).",
+    ),
+    out: Path = typer.Option(
+        None, "--out", "-o", help="Ignored — output paths are server-managed."
+    ),
+    snapshot: bool = typer.Option(
+        False, "--snapshot", help="Save census as immutable snapshot"
+    ),
+    set_baseline: str = typer.Option(
+        None, "--set-baseline", help="Create named baseline from this census"
+    ),
+    list_baselines_flag: bool = typer.Option(
+        False, "--list-baselines", help="List all baselines"
+    ),
+    diff_baseline: str = typer.Option(
+        None, "--diff", help="Compare against named baseline"
+    ),
+    diff_prev: bool = typer.Option(
+        False, "--diff-prev", help="Compare against previous snapshot"
+    ),
+) -> None:
+    """CIM-0: Perform a mechanical census of the repository.
+
+    Modes:
+    - Default: Run census via POST /v1/census/runs
+    - --snapshot: Persist as immutable snapshot server-side
+    - --set-baseline NAME: Create named baseline (requires --snapshot)
+    - --list-baselines: GET /v1/census/baselines
+    - --diff NAME: GET /v1/census/diff?baseline=NAME
+    - --diff-prev: GET /v1/census/diff (no baseline)
+    """
+    _ = ctx
+    _ = path  # API resolves repo_root server-side; --path retained for compatibility.
+    _ = out  # Output paths are now server-managed; --out kept for backward compat.
+    client = CoreApiClient()
+
+    if list_baselines_flag:
+        payload = await client.census_list_baselines()
+        _render_baseline_list(payload)
+        return
+
+    console.print("[blue]Running CIM-0 census via /v1/census/runs[/blue]")
+    initial = await client.census_run(snapshot=snapshot)
+    run_id = initial.get("run_id")
+    if not run_id:
+        console.print(f"[red]Error: census dispatch failed: {initial}[/red]")
+        raise typer.Exit(1)
+
+    console.print(f"[dim]Dispatched run {run_id} — polling…[/dim]")
+    final = await client.poll_census_run(run_id)
+    if final.get("status") != "completed":
+        console.print(f"[red]Census failed: {final.get('error') or final}[/red]")
+        raise typer.Exit(1)
+
+    result = final.get("result") or {}
+    tree = result.get("tree") or {}
+    console.print("[green]✓ Census complete[/green]")
+    console.print(f"  Files scanned: {tree.get('total_files', '?')}")
+    console.print(
+        f"  Execution surfaces: {len(result.get('execution_surfaces') or [])}"
+    )
+    console.print(f"  Mutation surfaces: {len(result.get('mutation_surfaces') or [])}")
+    snapshot_file = result.get("snapshot_file")
+    if snapshot and snapshot_file:
+        console.print(f"[green]✓ Snapshot saved: {snapshot_file}[/green]")
+
+    if set_baseline:
+        if not snapshot:
+            console.print(
+                "[yellow]Warning: --set-baseline requires --snapshot[/yellow]"
+            )
+        else:
+            baseline_payload = await client.census_create_baseline(
+                name=set_baseline, snapshot_file=snapshot_file
+            )
+            console.print(f"[green]✓ Baseline '{set_baseline}' created[/green]")
+            _ = baseline_payload
+
+    if diff_baseline or diff_prev:
+        baseline_name = diff_baseline if diff_baseline else None
+        diff_payload = await client.census_diff(baseline=baseline_name)
+        if not diff_payload.get("available", True):
+            err = diff_payload.get("error", "diff unavailable")
+            console.print(f"[yellow]{err}[/yellow]")
+            raise typer.Exit(0)
+        _display_diff(diff_payload)
+        # ADR-058 does not currently expose a policy-evaluation exit code
+        # via /v1/census/diff. Exit 0 on successful diff render; policy
+        # evaluation moves server-side in a future iteration.
+        raise typer.Exit(0)
+
+
+def _render_baseline_list(payload: dict) -> None:
+    """Render the baseline list returned by /v1/census/baselines."""
+    baselines = payload.get("baselines") or []
+    if not baselines:
+        console.print("[yellow]No baselines found[/yellow]")
+        return
+    table = Table(title="CIM Baselines")
+    table.add_column("Name", style="cyan")
+    table.add_column("Snapshot", style="white")
+    table.add_column("Commit", style="dim")
+    table.add_column("Created", style="green")
+    for baseline in baselines:
+        commit = (baseline.get("git_commit") or "")[:8] or "—"
+        created_raw = baseline.get("created_at", "")
+        created = str(created_raw)[:16] if created_raw else "—"
+        table.add_row(
+            str(baseline.get("name", "")),
+            str(baseline.get("snapshot_file", "")),
+            commit,
+            created,
+        )
+    console.print(table)
+
+
+def _display_diff(diff_payload: dict) -> None:
+    """Render a /v1/census/diff payload in human-readable form."""
+    diff = diff_payload.get("diff") or {}
+    baseline_name = (
+        diff_payload.get("baseline") or diff.get("baseline_name") or "previous"
+    )
+    console.print()
+    console.print("[bold]Census Diff Summary[/bold]")
+    console.print(f"Baseline: {baseline_name}")
+    console.print()
+
+    exec_delta = (diff.get("execution_surfaces") or {}).get("delta", "—")
+    mut_total_delta = (diff.get("mutation_surfaces_total") or {}).get("delta", "—")
+    write_ephemeral_delta = (diff.get("write_ephemeral") or {}).get("delta", "—")
+    write_production_delta = (diff.get("write_production") or {}).get("delta", "—")
+    console.print(f"Execution surfaces: {exec_delta}")
+    console.print(f"Mutation surfaces: {mut_total_delta}")
+    console.print(f"  Ephemeral writes: {write_ephemeral_delta}")
+    console.print(f"  Production writes: {write_production_delta}")
+
+    new_prohibited = diff.get("new_prohibited_writes", 0) or 0
+    if new_prohibited > 0:
+        console.print(f"  [red bold]Prohibited writes: +{new_prohibited}[/red bold]")
+
+    console.print()

cli/commands/inspect/status.py

@@ -0,0 +1,48 @@
+# src/cli/commands/inspect/status.py
+"""System and database status inspection commands."""
+
+from __future__ import annotations
+
+import logging
+
+import typer
+from rich.console import Console
+
+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.status",
+    behavior=CommandBehavior.READ,
+    layer=CommandLayer.BODY,
+    summary="Display database connection and migration status",
+)
+@core_command(dangerous=False, requires_context=False)
+# ID: 4d56d191-4d50-41f6-8d64-cc5732a92186
+async def status_command(ctx: typer.Context) -> None:
+    """Display database connection and schema state via /v1/status/db."""
+    _ = ctx
+    client = CoreApiClient()
+    payload = await client.status_db()
+    if payload.get("connected"):
+        console.print("Database connection: OK")
+    else:
+        console.print("Database connection: FAILED")
+        error = payload.get("error")
+        if error:
+            console.print(f"  {error}")
+    tables = payload.get("core_schema_tables")
+    if tables is not None:
+        console.print(f"core schema tables: {tables}")
+    warning = payload.get("warning")
+    if warning:
+        console.print(f"[yellow]{warning}[/yellow]")
+
+
+status_commands = [{"name": "status", "func": status_command}]