ccid-cli 0.1.1__py3-none-any.whl

ccid_cli/main.py

@@ -0,0 +1,709 @@
+# Copyright (c) 2024-2026 Dr. Fred Mpala. All rights reserved.
+# Proprietary and confidential. Unauthorized copying, distribution,
+# or use of this file, via any medium, is strictly prohibited.
+
+"""
+CCID CLI — Pipeline-native compliance checking from the terminal.
+
+Commands
+--------
+    ccid configure                          Set API URL and auth token
+    ccid analyze <path>                     Run code analysis swarm
+    ccid posture                            Compliance posture snapshot
+    ccid assignments                        List open findings
+    ccid export <assessment-id>             Export assessment report
+    ccid status                             API health check
+    ccid replay <assessment-id>             Replay swarm reasoning chain
+    ccid patterns                           Manage golden patterns
+    ccid review-queue                       Review queue workspace
+    ccid validate-pattern <id>              Validate a pattern against requirements
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.live import Live
+from rich.panel import Panel
+from rich.status import Status
+from rich.table import Table
+from rich.text import Text
+
+from ccid_cli.api import CCIDClient, load_config, save_config
+from ccid_cli.formatters import (
+    console,
+    format_analysis_result,
+    format_assignments,
+    format_pattern_recommendations,
+    format_posture,
+    format_swarm_replay,
+)
+
+app = typer.Typer(
+    name="ccid",
+    help="CCID Compliance CLI - Pipeline-native compliance checking.",
+    no_args_is_help=True,
+)
+
+
+# ---------------------------------------------------------------------------
+# ccid configure
+# ---------------------------------------------------------------------------
+
+@app.command()
+def configure() -> None:
+    """Set API URL and authentication token. Saves to ~/.ccid/config.json."""
+    cfg = load_config()
+
+    api_url = typer.prompt(
+        "CCID API URL",
+        default=cfg.get("api_url", "https://ccid-backend-922408154037.europe-west2.run.app"),
+    )
+    api_key = typer.prompt(
+        "API key / Bearer token",
+        default=cfg.get("api_key", ""),
+        hide_input=True,
+    )
+
+    cfg["api_url"] = api_url.rstrip("/")
+    cfg["api_key"] = api_key
+    save_config(cfg)
+    console.print("[green]Configuration saved to ~/.ccid/config.json[/green]")
+
+
+# ---------------------------------------------------------------------------
+# ccid analyze
+# ---------------------------------------------------------------------------
+
+@app.command()
+def analyze(
+    path: str = typer.Argument(..., help="Path to file or directory to analyse"),
+    framework: Optional[str] = typer.Option(
+        None,
+        "--framework",
+        "-f",
+        help="Comma-separated frameworks, e.g. SOC2,ISO27001",
+    ),
+    format: str = typer.Option(
+        "json", "--format", help="Output format: sarif, json, text"
+    ),
+    live: bool = typer.Option(
+        False, "--live", help="Stream progress via WebSocket"
+    ),
+    fail_on: Optional[str] = typer.Option(
+        None,
+        "--fail-on",
+        help="Exit non-zero on gate decision: 'warn' (exit on warn+block) or 'block' (exit on block only)",
+    ),
+) -> None:
+    """Run compliance code analysis on a file or directory.
+
+    Reads the target path and sends the content to the CCID code-analysis
+    swarm.  Use --live to stream real-time agent progress via WebSocket.
+
+    Exit codes:
+      0 = pass
+      1 = block
+      2 = warn
+    """
+    target = Path(path).expanduser().resolve()
+    if not target.exists():
+        console.print(f"[red]Path not found: {target}[/red]")
+        raise typer.Exit(code=1)
+
+    # Collect code content
+    if target.is_file():
+        code = target.read_text()
+    else:
+        # Concatenate all relevant IaC / code files
+        extensions = {".tf", ".hcl", ".yaml", ".yml", ".json", ".py", ".ts", ".js"}
+        parts: list[str] = []
+        for f in sorted(target.rglob("*")):
+            if f.is_file() and f.suffix in extensions:
+                try:
+                    parts.append(f"# --- {f.relative_to(target)} ---\n{f.read_text()}")
+                except Exception:
+                    pass
+        if not parts:
+            console.print("[red]No analysable files found in directory.[/red]")
+            raise typer.Exit(code=1)
+        code = "\n\n".join(parts)
+
+    frameworks = [s.strip() for s in framework.split(",")] if framework else None
+
+    client = CCIDClient()
+
+    # --live: stream via WebSocket
+    if live:
+        asyncio.run(_live_analyze(client, code, frameworks))
+        return
+
+    # Standard synchronous call
+    with console.status("[bold cyan]Running code analysis...[/bold cyan]"):
+        try:
+            result = client.analyze(code=code, frameworks=frameworks, format=format)
+        except Exception as exc:
+            console.print(f"[red]Analysis failed: {exc}[/red]")
+            raise typer.Exit(code=1)
+
+    if format == "sarif":
+        console.print_json(data=result)
+    elif format == "text":
+        format_analysis_result(result)
+    else:
+        format_analysis_result(result)
+
+    _exit_for_gate(result.get("gate_decision", "pass"), fail_on)
+
+
+async def _live_analyze(
+    client: CCIDClient,
+    code: str,
+    frameworks: list[str] | None,
+) -> None:
+    """Connect WebSocket, submit analysis, stream node progress with Rich Live."""
+    import websockets
+
+    ws_url = client.ws_url
+    headers = {}
+    if client.api_key:
+        # X-API-Key is the header the backend /ws handler reads for key auth
+        # (TRU-583). NB: the WS handler currently validates only the system
+        # API_KEY here, not tenant-scoped ccid_ keys — tenant-key --live is a
+        # separate backend follow-up; this swap is the correct header regardless.
+        headers["X-API-Key"] = client.api_key
+
+    node_states: dict[str, dict] = {}
+
+    def _build_table() -> Table:
+        tbl = Table(title="CCID Live Analysis", show_lines=True, expand=True)
+        tbl.add_column("Node", style="bold", width=28)
+        tbl.add_column("Status", justify="center", width=12)
+        tbl.add_column("Tokens", justify="right", width=10)
+        tbl.add_column("Duration", justify="right", width=10)
+        for name, st in node_states.items():
+            status_str = st.get("status", "pending")
+            if status_str == "completed":
+                indicator = "[green]OK[/green]"
+            elif status_str == "running":
+                indicator = "[yellow]...[/yellow]"
+            elif status_str == "failed":
+                indicator = "[red]FAIL[/red]"
+            else:
+                indicator = "[dim]--[/dim]"
+            tokens = st.get("tokens", "")
+            duration = st.get("duration", "")
+            tbl.add_row(name, indicator, str(tokens), str(duration))
+        return tbl
+
+    try:
+        async with websockets.connect(
+            ws_url, additional_headers=headers
+        ) as ws:
+            # Submit analysis in the background via httpx
+            import httpx
+
+            async def _submit():
+                payload = {"terraform_code": code, "trigger_source": "cli"}
+                if frameworks:
+                    payload["frameworks"] = frameworks
+                async with httpx.AsyncClient(
+                    base_url=client.base_url,
+                    headers=client._headers(),
+                    timeout=120.0,
+                ) as http:
+                    resp = await http.post(
+                        "/api/agents/run-code-analysis", json=payload
+                    )
+                    resp.raise_for_status()
+                    return resp.json()
+
+            submit_task = asyncio.create_task(_submit())
+
+            with Live(_build_table(), console=console, refresh_per_second=4) as live_display:
+                while not submit_task.done():
+                    try:
+                        raw = await asyncio.wait_for(ws.recv(), timeout=0.5)
+                        msg = json.loads(raw) if isinstance(raw, str) else raw
+                        event = msg.get("event", "")
+
+                        if event == "agent_progress":
+                            node_name = msg.get("node", msg.get("agent", "unknown"))
+                            node_states[node_name] = {
+                                "status": msg.get("status", "running"),
+                                "tokens": msg.get("tokens", ""),
+                                "duration": msg.get("duration", ""),
+                            }
+                            live_display.update(_build_table())
+
+                        elif event in (
+                            "code_analysis_completed",
+                            "code_analysis_started",
+                        ):
+                            pass  # handled by submit_task result
+
+                    except asyncio.TimeoutError:
+                        continue
+                    except websockets.exceptions.ConnectionClosed:
+                        break
+
+            result = await submit_task
+            format_analysis_result(result)
+
+    except Exception as exc:
+        console.print(f"[yellow]WebSocket unavailable ({exc}), falling back to sync...[/yellow]")
+        with console.status("[bold cyan]Running code analysis...[/bold cyan]"):
+            result = client.analyze(code=code, frameworks=frameworks)
+        format_analysis_result(result)
+
+
+# ---------------------------------------------------------------------------
+# ccid posture
+# ---------------------------------------------------------------------------
+
+@app.command()
+def posture(
+    scope: str = typer.Option(
+        "system", "--scope", "-s", help="Scope: system, framework, repo"
+    ),
+    scope_id: Optional[str] = typer.Option(
+        None, "--scope-id", help="Scope identifier (e.g. framework code)"
+    ),
+    format: str = typer.Option(
+        "text", "--format", help="Output format: json, sarif, text"
+    ),
+    fail_on: Optional[str] = typer.Option(
+        None,
+        "--fail-on",
+        help="Exit non-zero on posture gate: 'block' (exit 1) or 'warn' "
+        "(exit 2 on warn, 1 on block). 'none'/'off' = informational only. "
+        "Default: never fail.",
+    ),
+) -> None:
+    """Show compliance posture snapshot."""
+    client = CCIDClient()
+    with console.status("[bold cyan]Fetching posture...[/bold cyan]"):
+        data = client.posture(scope=scope, scope_id=scope_id)
+
+    if format == "json":
+        console.print_json(data=data)
+    elif format == "sarif":
+        console.print_json(data=data)
+    else:
+        format_posture(data)
+
+    # The composite action (.github/actions/ccid-compliance) invokes
+    # `ccid posture --fail-on <level>`; before TRU-583 posture had no such
+    # option so that step always exit-2'd. Map the posture verdict → gate.
+    _exit_for_gate(str(data.get("posture", "pass")).lower(), fail_on)
+
+
+# ---------------------------------------------------------------------------
+# ccid assignments
+# ---------------------------------------------------------------------------
+
+@app.command()
+def assignments(
+    severity: Optional[str] = typer.Option(
+        None,
+        "--severity",
+        help="Comma-separated severities, e.g. critical,high",
+    ),
+    status: str = typer.Option(
+        "open", "--status", help="Filter by status: open, resolved, all"
+    ),
+    format: str = typer.Option(
+        "text", "--format", help="Output format: json, text"
+    ),
+) -> None:
+    """List compliance findings / assignments."""
+    client = CCIDClient()
+    with console.status("[bold cyan]Fetching assignments...[/bold cyan]"):
+        data = client.assignments(severity=severity, status=status)
+
+    if format == "json":
+        console.print_json(data=data)
+    else:
+        format_assignments(data)
+
+
+# ---------------------------------------------------------------------------
+# ccid export
+# ---------------------------------------------------------------------------
+
+@app.command()
+def export(
+    assessment_id: str = typer.Argument(..., help="Assessment UUID"),
+    format: str = typer.Option(
+        "json", "--format", help="Export format: sarif, json, html, text"
+    ),
+    output: Optional[str] = typer.Option(
+        None, "--output", "-o", help="Write to file instead of stdout"
+    ),
+) -> None:
+    """Export an assessment report in the given format."""
+    client = CCIDClient()
+    with console.status(f"[bold cyan]Exporting {format}...[/bold cyan]"):
+        content = client.export(assessment_id=assessment_id, format=format)
+
+    if output:
+        Path(output).write_text(content)
+        console.print(f"[green]Written to {output}[/green]")
+    else:
+        if format in ("json", "sarif"):
+            try:
+                console.print_json(content)
+            except Exception:
+                console.print(content)
+        else:
+            console.print(content)
+
+
+# ---------------------------------------------------------------------------
+# ccid status
+# ---------------------------------------------------------------------------
+
+@app.command()
+def status() -> None:
+    """Check API health."""
+    client = CCIDClient()
+    try:
+        data = client.health()
+    except Exception as exc:
+        console.print(f"[red]API unreachable: {exc}[/red]")
+        raise typer.Exit(code=1)
+
+    health = data.get("status", "unknown")
+    style = "green" if health == "healthy" else "red"
+    db_status = data.get("database", "unknown")
+    redis_status = "connected" if data.get("redis") else "unavailable"
+    env = data.get("environment", "unknown")
+
+    tbl = Table(title="CCID API Status", show_lines=True)
+    tbl.add_column("Component", style="bold")
+    tbl.add_column("Status")
+    tbl.add_row("API", Text(health.upper(), style=style))
+    tbl.add_row("Database", db_status)
+    tbl.add_row("Redis", redis_status)
+    tbl.add_row("Environment", env)
+    console.print(tbl)
+
+
+# ---------------------------------------------------------------------------
+# ccid replay
+# ---------------------------------------------------------------------------
+
+@app.command()
+def replay(
+    assessment_id: str = typer.Argument(..., help="Assessment UUID to replay"),
+) -> None:
+    """Replay the swarm reasoning chain for an assessment.
+
+    Fetches swarm-results from the API and renders each node's
+    reasoning as sequential panels in the terminal.
+    """
+    client = CCIDClient()
+    with console.status("[bold cyan]Fetching swarm results...[/bold cyan]"):
+        try:
+            data = client.swarm_results(assessment_id)
+        except Exception as exc:
+            console.print(f"[red]Failed to fetch swarm results: {exc}[/red]")
+            raise typer.Exit(code=1)
+
+    format_swarm_replay(data)
+
+
+# ---------------------------------------------------------------------------
+# ccid patterns
+# ---------------------------------------------------------------------------
+
+@app.command()
+def patterns(
+    control: Optional[str] = typer.Option(
+        None, "--control", "-c", help="Find patterns for a specific control ID (e.g. AC-2, SC-28)"
+    ),
+    framework: Optional[str] = typer.Option(
+        None, "--framework", "-f", help="Framework code (e.g. NIST_800_53_R5)"
+    ),
+    list_all: bool = typer.Option(
+        False, "--list", "-l", help="List all golden patterns"
+    ),
+    registries: bool = typer.Option(
+        False, "--registries", "-r", help="List configured artifact registries"
+    ),
+    sync: Optional[str] = typer.Option(
+        None, "--sync", help="Trigger sync for a registry ID"
+    ),
+    format: str = typer.Option(
+        "text", "--format", help="Output format: json, text"
+    ),
+) -> None:
+    """Manage golden patterns, artifact registries, and pattern recommendations.
+
+    Examples:
+        ccid patterns --control SC-28 --framework NIST_800_53_R5
+        ccid patterns --list
+        ccid patterns --registries
+        ccid patterns --sync <registry_id>
+    """
+    client = CCIDClient()
+
+    if sync:
+        with console.status(f"[bold cyan]Syncing registry {sync}...[/bold cyan]"):
+            try:
+                data = client.post(f"/api/artifact-registries/{sync}/sync")
+            except Exception as exc:
+                console.print(f"[red]Sync failed: {exc}[/red]")
+                raise typer.Exit(code=1)
+        if format == "json":
+            console.print_json(data=data)
+        else:
+            console.print(Panel(
+                f"Patterns found: {data.get('patterns_found', 0)}\n"
+                f"New: {data.get('new', 0)}\n"
+                f"Updated: {data.get('updated', 0)}\n"
+                f"Errors: {data.get('errors', 0)}",
+                title="Registry Sync Results",
+            ))
+        return
+
+    if registries:
+        with console.status("[bold cyan]Fetching registries...[/bold cyan]"):
+            try:
+                data = client.get("/api/artifact-registries")
+            except Exception as exc:
+                console.print(f"[red]Failed: {exc}[/red]")
+                raise typer.Exit(code=1)
+        if format == "json":
+            console.print_json(data=data)
+        else:
+            tbl = Table(title="Artifact Registries", show_lines=True)
+            tbl.add_column("Name", style="bold")
+            tbl.add_column("Type")
+            tbl.add_column("Status")
+            tbl.add_column("Last Sync")
+            for r in data.get("registries", []):
+                status_style = "green" if r.get("status") == "active" else "red"
+                tbl.add_row(
+                    r.get("name", ""),
+                    r.get("registry_type", ""),
+                    Text(r.get("status", ""), style=status_style),
+                    r.get("last_sync_at", "never"),
+                )
+            console.print(tbl)
+        return
+
+    if list_all:
+        with console.status("[bold cyan]Fetching patterns...[/bold cyan]"):
+            try:
+                data = client.get("/api/patterns")
+            except Exception as exc:
+                console.print(f"[red]Failed: {exc}[/red]")
+                raise typer.Exit(code=1)
+        if format == "json":
+            console.print_json(data=data)
+        else:
+            tbl = Table(title="Golden Patterns", show_lines=True)
+            tbl.add_column("Name", style="bold")
+            tbl.add_column("Type")
+            tbl.add_column("Status")
+            tbl.add_column("Controls")
+            for p in data.get("patterns", []):
+                tbl.add_row(
+                    p.get("name", ""),
+                    p.get("pattern_type", ""),
+                    p.get("analysis_status", ""),
+                    str(p.get("control_count", 0)),
+                )
+            console.print(tbl)
+        return
+
+    if control and framework:
+        with console.status(f"[bold cyan]Searching patterns for {framework}/{control}...[/bold cyan]"):
+            try:
+                data = client.get(f"/api/patterns/search?framework={framework}&control_id={control}")
+            except Exception as exc:
+                console.print(f"[red]Failed: {exc}[/red]")
+                raise typer.Exit(code=1)
+        if format == "json":
+            console.print_json(data=data)
+        else:
+            format_pattern_recommendations(data.get("patterns", []), framework, control)
+        return
+
+    console.print("[yellow]Use --control + --framework, --list, --registries, or --sync[/yellow]")
+
+
+# ---------------------------------------------------------------------------
+# ccid review-queue
+# ---------------------------------------------------------------------------
+
+@app.command(name="review-queue")
+def review_queue(
+    target_type: Optional[str] = typer.Option(
+        None, "--type", "-t", help="Filter by type: framework_control, synergy, pattern_mapping, pattern_validation"
+    ),
+    priority: Optional[str] = typer.Option(
+        None, "--priority", "-p", help="Filter by priority: critical, high, medium, low"
+    ),
+    populate: bool = typer.Option(
+        False, "--populate", help="Auto-populate queue from low-confidence items"
+    ),
+    threshold: float = typer.Option(
+        0.70, "--threshold", help="Confidence threshold for auto-populate"
+    ),
+    stats: bool = typer.Option(
+        False, "--stats", help="Show queue statistics"
+    ),
+    format: str = typer.Option(
+        "text", "--format", help="Output format: json, text"
+    ),
+) -> None:
+    """Manage the review queue — view pending items, populate, and stats.
+
+    Examples:
+        ccid review-queue                           Show pending items
+        ccid review-queue --type framework_control  Filter by type
+        ccid review-queue --populate                Auto-populate from low-confidence
+        ccid review-queue --stats                   Queue statistics
+    """
+    client = CCIDClient()
+
+    if populate:
+        with console.status("[bold cyan]Populating review queue...[/bold cyan]"):
+            try:
+                data = client.post(f"/api/review-queue/populate?threshold={threshold}")
+            except Exception as exc:
+                console.print(f"[red]Populate failed: {exc}[/red]")
+                raise typer.Exit(code=1)
+        if format == "json":
+            console.print_json(data=data)
+        else:
+            console.print(Panel(
+                f"Items added: {data.get('items_added', 0)}\nThreshold: {data.get('threshold', threshold)}",
+                title="Review Queue Populated",
+            ))
+        return
+
+    if stats:
+        with console.status("[bold cyan]Fetching queue stats...[/bold cyan]"):
+            try:
+                data = client.get("/api/review-queue/stats")
+            except Exception as exc:
+                console.print(f"[red]Failed: {exc}[/red]")
+                raise typer.Exit(code=1)
+        if format == "json":
+            console.print_json(data=data)
+        else:
+            from ccid_cli.formatters import format_review_queue_stats
+            format_review_queue_stats(data)
+        return
+
+    # Default: show pending items
+    url = "/api/reviews/queue?"
+    if target_type:
+        url += f"target_type={target_type}&"
+    if priority:
+        url += f"priority={priority}&"
+    url += "limit=50"
+
+    with console.status("[bold cyan]Fetching review queue...[/bold cyan]"):
+        try:
+            data = client.get(url)
+        except Exception as exc:
+            console.print(f"[red]Failed: {exc}[/red]")
+            raise typer.Exit(code=1)
+
+    if format == "json":
+        console.print_json(data=data)
+    else:
+        from ccid_cli.formatters import format_review_queue
+        format_review_queue(data.get("items", []))
+
+
+# ---------------------------------------------------------------------------
+# ccid validate-pattern
+# ---------------------------------------------------------------------------
+
+@app.command(name="validate-pattern")
+def validate_pattern(
+    pattern_id: str = typer.Argument(..., help="UUID of the golden pattern to validate"),
+    claim_type: str = typer.Option(
+        "framework_control", "--type", "-t",
+        help="Claim type: framework_control, policy_requirement, obligation"
+    ),
+    reference_id: str = typer.Option(
+        ..., "--reference", "-r", help="UUID of the reference entity"
+    ),
+    description: str = typer.Option(
+        "", "--description", "-d", help="Description of the claim"
+    ),
+    format: str = typer.Option(
+        "text", "--format", help="Output format: json, text"
+    ),
+) -> None:
+    """Validate a golden pattern against a claimed requirement.
+
+    Examples:
+        ccid validate-pattern <id> --type framework_control --reference <control-uuid>
+    """
+    client = CCIDClient()
+    claims = [{
+        "type": claim_type,
+        "reference_id": reference_id,
+        "claim_description": description,
+    }]
+
+    with console.status("[bold cyan]Validating pattern...[/bold cyan]"):
+        try:
+            data = client.post(f"/api/patterns/{pattern_id}/validate", json={"claims": claims})
+        except Exception as exc:
+            console.print(f"[red]Validation failed: {exc}[/red]")
+            raise typer.Exit(code=1)
+
+    if format == "json":
+        console.print_json(data=data)
+    else:
+        from ccid_cli.formatters import format_pattern_validation
+        format_pattern_validation(data)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _exit_for_gate(gate: str, fail_on: str | None) -> None:
+    """Raise typer.Exit with the appropriate code based on gate decision.
+
+    Exit codes:
+      0 = pass
+      1 = block
+      2 = warn
+
+    --fail-on controls which gates cause non-zero exit:
+      "block"          → only exit 1 on block
+      "warn"           → exit 2 on warn, exit 1 on block
+      None/""/none/off → always exit 0 (informational only)
+    """
+    if fail_on is None or fail_on.lower() in ("", "none", "off"):
+        return
+
+    if gate == "block":
+        raise typer.Exit(code=1)
+
+    if gate == "warn" and fail_on == "warn":
+        raise typer.Exit(code=2)
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    app()