adl-toolkit 0.0.0-stage → 0.1.1

package/adl_drift/cli/main.py

@@ -0,0 +1,744 @@
+"""Main CLI entry point.
+
+Entry point: `adl-drift`
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import click
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+from rich.tree import Tree
+from rich.progress import (
+    Progress, SpinnerColumn, TextColumn, BarColumn,
+    MofNCompleteColumn, TimeElapsedColumn,
+)
+
+from adl_drift.cli.commands import DriftCommands
+
+if sys.platform == "win32":
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8")
+        except (AttributeError, OSError):
+            pass
+
+console = Console()
+
+
+@click.group()
+@click.option("--project", "-p", type=click.Path(exists=True), default=".",
+              help="Project root directory")
+@click.pass_context
+def cli(ctx: click.Context, project: str) -> None:
+    """ADL Drift - Static analysis for Python and Java codebases."""
+    ctx.ensure_object(dict)
+    ctx.obj["project_path"] = Path(project)
+    ctx.obj["commands"] = DriftCommands(ctx.obj["project_path"])
+
+
+# --more-info display helpers
+_OBJECT_KEYS = (
+    "handler", "function", "decorator", "name", "class",
+    "key", "key_name", "route_path", "module", "type", "role",
+)
+_SEVERITY_STYLES = {"CRITICAL": "bold white on red", "HIGH": "bold red",
+                    "MEDIUM": "yellow", "LOW": "dim"}
+_MORE_INFO_ROW_CAP = 50
+
+
+def _confidence_word(conf: float) -> str:
+    """Translate a 0–1 confidence into a plain word."""
+    if conf >= 0.85:
+        return "Certain"
+    if conf >= 0.6:
+        return "Likely"
+    return "Guess"
+
+
+def _result_object(r: dict) -> str:
+    md = r.get("metadata") or {}
+    return next((str(md[k]) for k in _OBJECT_KEYS if md.get(k)), "")
+
+
+def _baseline_dict(ctx: Optional[Any]) -> Optional[Dict[str, Any]]:
+    """Convert a ProjectContext into a JSON-serializable dict."""
+    if ctx is None:
+        return None
+    return {
+        "files_analyzed": ctx.files_analyzed,
+        "lines_of_code": ctx.lines_of_code,
+        "non_blank_lines": ctx.non_blank_lines,
+        "total_symbols": ctx.total_symbols,
+        "total_functions": ctx.total_functions,
+        "total_classes": ctx.total_classes,
+        "total_variables": ctx.total_variables,
+        "total_modules": ctx.total_modules,
+        "entry_points": ctx.entry_points,
+        "calls_edges": ctx.calls_edges,
+        "total_patterns": ctx.total_patterns,
+        "frameworks": ctx.frameworks,
+        "patterns_by_category": ctx.patterns_by_category,
+        "excluded_files": ctx.excluded_files,
+    }
+
+
+def _print_scan_summary(results: list, files_scanned: int, errors: int = 0,
+                        baseline: Optional[Any] = None) -> None:
+    """One-line overview + category counts (the part a non-dev reads)."""
+    sec = [r for r in results if r["category"] in ("SECURITY", "TAINT")]
+    sev_counts: dict = {}
+    for r in sec:
+        sev = str((r.get("metadata") or {}).get("severity", "")).upper()
+        if sev:
+            sev_counts[sev] = sev_counts.get(sev, 0) + 1
+
+    parts = [f"Scanned [bold]{files_scanned}[/bold] files",
+             f"[bold]{len(results)}[/bold] findings"]
+    if baseline:
+        parts.append(f"[bold]{baseline.lines_of_code:,}[/bold] LOC")
+        parts.append(f"[bold]{baseline.total_symbols}[/bold] symbols")
+        if baseline.entry_points:
+            parts.append(f"[bold]{baseline.entry_points}[/bold] entry points")
+    if sec:
+        sev_bits = ", ".join(
+            f"[{_SEVERITY_STYLES.get(s, 'white')}]{n} {s}[/]"
+            for s, n in sorted(sev_counts.items())
+        )
+        parts.append(f"{len(sec)} security ({sev_bits})" if sev_bits else f"{len(sec)} security")
+    if errors:
+        parts.append(f"[red]{errors} errors[/red]")
+    excluded = getattr(baseline, "excluded_files", None) or []
+    if excluded:
+        by_reason: dict = {}
+        for e in excluded:
+            by_reason[e["reason"]] = by_reason.get(e["reason"], 0) + 1
+        reason_bits = ", ".join(f"{n} {r}" for r, n in sorted(by_reason.items()))
+        parts.append(f"[dim]{len(excluded)} excluded ({reason_bits})[/dim]")
+    console.print(" · ".join(parts))
+
+    cat_counts: dict = {}
+    for r in results:
+        cat_counts[r["category"]] = cat_counts.get(r["category"], 0) + 1
+    console.print("[dim]" + " · ".join(
+        f"{c} {n}" for c, n in sorted(cat_counts.items(), key=lambda x: -x[1])
+    ) + "[/dim]\n")
+
+
+def _print_scan_errors(errors: list) -> None:
+    """P2.5: per-file scan failures, shown after the results table."""
+    if not errors:
+        return
+    console.print(f"[red]{len(errors)} file(s) failed to scan:[/red]")
+    for e in errors:
+        console.print(f"  [dim]{e['file']}[/dim] — {e['error']}")
+
+
+def _print_more_info_table(results: list, full: bool) -> None:
+    shown = results if full else results[:_MORE_INFO_ROW_CAP]
+
+    table = Table(title=f"Detected Patterns ({len(results)})")
+    table.add_column("Category", style="cyan")
+    table.add_column("Object", style="white")
+    table.add_column("What was found", style="green", max_width=60)
+    table.add_column("Severity")
+    table.add_column("File", style="blue")
+    table.add_column("Line", style="yellow")
+    table.add_column("Confidence", style="magenta")
+
+    for r in shown:
+        md = r.get("metadata") or {}
+        sev = str(md.get("severity", "")).upper()
+        sev_cell = f"[{_SEVERITY_STYLES[sev]}]{sev}[/]" if sev in _SEVERITY_STYLES else ""
+        table.add_row(
+            r["category"],
+            _result_object(r),
+            r.get("description") or r["name"],
+            sev_cell,
+            r["file"],
+            str(r["line"]),
+            _confidence_word(r.get("confidence", 0.0)),
+        )
+    console.print(table)
+
+    hidden = len(results) - len(shown)
+    if hidden > 0:
+        console.print(
+            f"[dim]… {hidden} more findings not shown — "
+            f"use --full to see everything, or -c <category> to filter.[/dim]"
+        )
+
+
+@cli.command()
+@click.argument("path", type=click.Path(exists=True), default=".")
+@click.option("--category", "-c", help="Filter by pattern category")
+@click.option("--format", "-f", type=click.Choice(["table", "json", "github"]), default="table")
+@click.option("--incremental", "-i", is_flag=True, help="Only re-parse changed files")
+@click.option("--lang", "language", type=click.Choice(["python", "java"]),
+              help="Scan one language only; default auto-detects all backends")
+@click.option("--more-info", "more_info", is_flag=True,
+              help="Beginner-friendly output: summary line, plain-language descriptions, "
+                   "severity colors, worded confidence, capped row count")
+@click.option("--full", is_flag=True,
+              help=f"With --more-info: show all rows instead of the first {_MORE_INFO_ROW_CAP}")
+@click.option("--baseline", "show_baseline", is_flag=True,
+              help="Print project baseline JSON (files, LOC, symbols) and exit.")
+@click.pass_context
+def scan(ctx: click.Context, path: str, category: Optional[str], format: str,
+         incremental: bool, language: Optional[str], more_info: bool, full: bool,
+         show_baseline: bool) -> None:
+    """Scan files or directories for patterns."""
+    commands = ctx.obj["commands"]
+
+    use_progress = sys.stdout.isatty() and format == "table" and not show_baseline
+
+    if use_progress:
+        progress_ctx = Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            BarColumn(),
+            MofNCompleteColumn(),
+            TimeElapsedColumn(),
+            console=console,
+            transient=True,
+        )
+        with progress_ctx as progress:
+            task = progress.add_task("scanning", total=None)
+
+            def _progress_cb(done: int, total: int, detail: str) -> None:
+                if detail.startswith("PHASE:"):
+                    phase = detail[7:].strip()
+                    progress.update(task, description=phase, total=None, completed=0)
+                else:
+                    name = Path(detail).name
+                    progress.update(task, advance=1, total=total,
+                                    description=f"scanning [dim]{name}[/dim]")
+
+            results = commands.scan(Path(path), category, incremental=incremental,
+                                    progress_callback=_progress_cb, language=language)
+    else:
+        results = commands.scan(Path(path), category, incremental=incremental, language=language)
+
+    scan_errors = commands.last_scan_errors
+    baseline_ctx = commands.last_scan_context
+    baseline = _baseline_dict(baseline_ctx)
+    if baseline is None:
+        baseline = commands.memory.get_scan_baseline(Path(path)) or {}
+
+    if show_baseline:
+        import json
+        print(json.dumps(baseline, indent=2))
+        return
+
+    if format == "json":
+        import json
+        print(json.dumps({"results": results, "errors": scan_errors, "baseline": baseline}, indent=2))
+    elif format == "github":
+        # GitHub Actions annotation format
+        for r in results:
+            level = "warning" if r.get("confidence", 0) > 0.7 else "notice"
+            click.echo(
+                f"::{level} file={r['file']},line={r['line']}::{r['name']}: {r['description']}"
+            )
+        for e in scan_errors:
+            click.echo(f"::error file={e['file']}::scan failed: {e['error']}")
+    elif more_info:
+        files_scanned = len(commands._find_files(Path(path)))
+        _print_scan_summary(results, files_scanned, errors=len(scan_errors), baseline=baseline_ctx)
+        _print_more_info_table(results, full)
+        _print_scan_errors(scan_errors)
+    else:
+        table = Table(title=f"Detected Patterns ({len(results)})")
+        table.add_column("Category", style="cyan")
+        table.add_column("Name", style="green")
+        table.add_column("Object", style="white")
+        table.add_column("File", style="blue")
+        table.add_column("Line", style="yellow")
+        table.add_column("Confidence", style="magenta")
+
+        for r in results:
+            table.add_row(
+                r["category"],
+                r["name"],
+                _result_object(r),
+                r["file"],
+                str(r["line"]),
+                f"{r['confidence']:.2f}",
+            )
+        console.print(table)
+        _print_scan_errors(scan_errors)
+
+
+@cli.command()
+@click.argument("pattern_id")
+@click.pass_context
+def approve(ctx: click.Context, pattern_id: str) -> None:
+    """Approve a detected pattern."""
+    commands = ctx.obj["commands"]
+    commands.approve(pattern_id)
+    console.print(f"[green]Approved pattern: {pattern_id}[/green]")
+
+
+@cli.command()
+@click.pass_context
+def patterns(ctx: click.Context) -> None:
+    """List all detected patterns."""
+    commands = ctx.obj["commands"]
+    patterns = commands.list_patterns()
+
+    table = Table(title="Patterns")
+    table.add_column("ID", style="dim")
+    table.add_column("Name", style="green")
+    table.add_column("Category", style="cyan")
+    table.add_column("Approved", style="yellow")
+    table.add_column("Confidence", style="magenta")
+
+    for p in patterns:
+        table.add_row(
+            p["id"][:16],
+            p["name"],
+            p["category"],
+            "✓" if p["is_approved"] else "",
+            f"{p['confidence']:.2f}",
+        )
+    console.print(table)
+
+
+@cli.command()
+@click.argument("topic")
+@click.argument("content", nargs=-1)
+@click.pass_context
+def learn(ctx: click.Context, topic: str, content: tuple[str, ...]) -> None:
+    """Add tribal knowledge."""
+    text = " ".join(content).strip()
+    if not text:
+        if not sys.stdin.isatty():
+            text = sys.stdin.read().strip()
+        else:
+            template = (
+                f"# Tribal knowledge for topic: {topic}\n"
+                "# Write the note below. Lines starting with '#' are ignored.\n"
+                "# Save and close to submit. Close without saving to abort.\n\n"
+            )
+            console.print(f"[dim]Opening editor for topic '{topic}'...[/dim]")
+            edited = click.edit(template)
+            if edited is None:
+                raise click.UsageError(
+                    "Editor aborted or no editor configured. "
+                    "Set $env:EDITOR (e.g. 'notepad'), pass content as args, "
+                    "or pipe via stdin."
+                )
+            text = "\n".join(
+                ln for ln in edited.splitlines() if not ln.lstrip().startswith("#")
+            ).strip()
+    if not text:
+        raise click.UsageError("Content empty after stripping comments. Nothing saved.")
+    commands = ctx.obj["commands"]
+    kid = commands.add_knowledge(topic, text)
+    console.print(f"[green]Added knowledge: {kid}[/green]")
+
+
+@cli.command()
+@click.argument("topic")
+@click.pass_context
+def why(ctx: click.Context, topic: str) -> None:
+    """Query tribal knowledge."""
+    commands = ctx.obj["commands"]
+    knowledge = commands.get_knowledge(topic)
+
+    if not knowledge:
+        console.print(f"[yellow]No knowledge stored for topic '{topic}'.[/yellow]")
+        return
+    for k in knowledge:
+        console.print(Panel(
+            k["content"],
+            title=f"[bold]{k['topic']}[/bold]",
+            subtitle=k["updated_at"],
+            width=min(console.width, 100),
+            expand=False,
+        ))
+
+
+@cli.command()
+@click.option("--god-nodes", is_flag=True, default=False, help="Show top-N highest-degree nodes (architectural linchpins).")
+@click.option("--top-n", default=10, show_default=True, help="Number of god nodes to show (with --god-nodes).")
+@click.option("--surprising", is_flag=True, default=False, help="Show cross-community CALLS/INSTANTIATES edges (accidental coupling).")
+@click.pass_context
+def graph(ctx: click.Context, god_nodes: bool, top_n: int, surprising: bool) -> None:
+    """Show call graph statistics (nodes, edges by type, entry points)."""
+    commands = ctx.obj["commands"]
+    console.print("[dim]Building call graph...[/dim]")
+
+    if god_nodes:
+        nodes = commands.god_nodes(top_n)
+        table = Table(title=f"Top-{top_n} God Nodes (highest degree)")
+        table.add_column("Rank", style="dim")
+        table.add_column("ID", style="cyan")
+        table.add_column("Type", style="yellow")
+        table.add_column("Degree", style="green")
+        table.add_column("In", style="dim green")
+        table.add_column("Out", style="dim green")
+        table.add_column("File", style="dim")
+        for i, node in enumerate(nodes, 1):
+            file_str = f"{node['file']}:{node['line']}" if node.get("file") else ""
+            table.add_row(str(i), node["id"], node["type"], str(node["degree"]),
+                          str(node["in_degree"]), str(node["out_degree"]), file_str)
+        console.print(table)
+        return
+
+    if surprising:
+        edges = commands.surprising_connections()
+        if not edges:
+            console.print("[green]No surprising cross-community connections found.[/green]")
+            return
+        table = Table(title=f"Surprising Cross-Community Connections ({len(edges)} total)")
+        table.add_column("From", style="cyan")
+        table.add_column("To", style="cyan")
+        table.add_column("Type", style="yellow")
+        table.add_column("Conf", style="green")
+        table.add_column("From Comm", style="dim")
+        table.add_column("To Comm", style="dim")
+        for edge in edges[:50]:
+            table.add_row(edge["from"], edge["to"], edge["edge_type"],
+                          f"{edge['confidence']:.2f}",
+                          str(edge["from_community"]), str(edge["to_community"]))
+        if len(edges) > 50:
+            console.print(f"[dim](showing 50 of {len(edges)})[/dim]")
+        console.print(table)
+        return
+
+    stats = commands.graph_stats()
+    table = Table(title="Call Graph Stats")
+    table.add_column("Metric", style="cyan")
+    table.add_column("Value", style="green")
+    table.add_row("Total nodes", str(stats["total_nodes"]))
+    table.add_row("Total edges", str(stats["total_edges"]))
+    table.add_row("Entry points", str(stats["entry_points"]))
+    for k, v in stats["node_types"].items():
+        table.add_row(f"  node:{k}", str(v))
+    for k, v in stats["edge_types"].items():
+        table.add_row(f"  edge:{k}", str(v))
+    console.print(table)
+
+
+@cli.command()
+@click.argument("symbol")
+@click.option("--format", "-f", type=click.Choice(["tree", "table", "json"]), default="tree")
+@click.option(
+    "--include-initializers",
+    is_flag=True,
+    help="Count synthetic Java <init>/<clinit> executable contexts as callers.",
+)
+@click.pass_context
+def impact(
+    ctx: click.Context, symbol: str, format: str, include_initializers: bool,
+) -> None:
+    """Blast-radius analysis: who calls SYMBOL (direct + transitive)."""
+    commands = ctx.obj["commands"]
+    # Keep human chatter on stderr so `-f json` stdout is machine-parseable (P2.24).
+    click.echo(f"Building call graph and resolving '{symbol}'...", err=True)
+    report = commands.impact(symbol, include_initializers=include_initializers)
+
+    if "error" in report:
+        console.print(f"[red]{report['error']}: '{symbol}'[/red]")
+        sys.exit(1)
+
+    if format == "json":
+        import json
+        print(json.dumps(report, indent=2, default=str))
+        return
+
+    if format == "table":
+        t = Table(title=f"Impact: {report['target']}")
+        t.add_column("Field", style="cyan")
+        t.add_column("Value", style="green")
+        for k in ("target_file", "affected_member_count", "initializer_caller_count",
+                  "transitive_initializer_caller_count",
+                  "direct_caller_count", "instantiator_count",
+                  "transitive_caller_count", "transitive_instantiator_count",
+                  "affected_entry_count",
+                  "affected_file_count", "user_facing", "max_depth"):
+            t.add_row(k, str(report[k]))
+        if report["ambiguous_matches"]:
+            t.add_row(
+                "[yellow]ambiguous_matches[/yellow]",
+                f"[yellow]{len(report['ambiguous_matches'])} distinct targets merged into the counts above[/yellow]",
+            )
+        console.print(t)
+        return
+
+    # tree
+    tree = Tree(f"[bold]{report['target']}[/bold] [dim]({report['target_file']})[/dim]")
+    if report["ambiguous_matches"]:
+        # `get_impact_analysis` merges every distinct target's callers into
+        # the counts below — it does not "pick first" (bugfix: the old
+        # wording claimed the opposite of what the code does, so a merged/
+        # inflated count could pass for a single clean target's result).
+        warn = tree.add(
+            f"[yellow]ambiguous: {len(report['ambiguous_matches'])} matches, "
+            f"merged into the counts below[/yellow]"
+        )
+        for m in report["ambiguous_matches"]:
+            warn.add(m)
+    if report.get("affected_member_count"):
+        mem_branch = tree.add(
+            f"[bold]Container members[/bold] ({report['affected_member_count']}) "
+            f"[dim]impact includes their callers[/dim]"
+        )
+        for m in report["affected_members"][:20]:
+            mem_branch.add(m)
+        if report["affected_member_count"] > 20:
+            mem_branch.add(f"[dim]... +{report['affected_member_count'] - 20} more[/dim]")
+    if report.get("initializer_caller_count"):
+        init_branch = tree.add(
+            f"[bold]Initializer callers[/bold] ({report['initializer_caller_count']}) "
+            f"[dim]{'included in caller counts' if report['include_initializers'] else 'reported separately'}[/dim]"
+        )
+        for caller in report["initializer_callers"]:
+            init_branch.add(caller)
+    if report.get("transitive_initializer_caller_count"):
+        trans_init_branch = tree.add(
+            f"[bold]Transitive initializer callers[/bold] "
+            f"({report['transitive_initializer_caller_count']})"
+        )
+        for caller, depth in sorted(
+            report["transitive_initializer_callers"].items(),
+            key=lambda item: (item[1], item[0]),
+        ):
+            trans_init_branch.add(f"[dim]d={depth}[/dim] {caller}")
+    direct_label = f"[bold]Direct callers[/bold] ({report['direct_caller_count']})"
+    instantiator_count = report.get("instantiator_count", 0)
+    if instantiator_count != report["direct_caller_count"]:
+        # Class targets: direct_caller_count includes TYPE_OF/RETURNS
+        # dependents, not just `Target(...)` constructor call sites.
+        direct_label += f" [dim]— {instantiator_count} construct it[/dim]"
+    direct_branch = tree.add(direct_label)
+    for c in report["direct_callers"]:
+        direct_branch.add(c)
+    trans_label = f"[bold]Transitive callers[/bold] ({report['transitive_caller_count']})"
+    trans_inst_count = report.get("transitive_instantiator_count", 0)
+    if trans_inst_count != report["transitive_caller_count"]:
+        # Class targets: transitive_callers includes TYPE_OF/RETURNS fan-out,
+        # not just construction chains — transitive_instantiator_count is the
+        # transitive counterpart of "X construct it" above.
+        trans_label += f" [dim]— {trans_inst_count} reachable via construction[/dim]"
+    trans_branch = tree.add(trans_label)
+    for c, depth in sorted(report["transitive_callers"].items(), key=lambda x: x[1]):
+        trans_branch.add(f"[dim]d={depth}[/dim] {c}")
+    ep_branch = tree.add(
+        f"[bold]Affected entry points[/bold] ({report['affected_entry_count']}) "
+        f"{'[green]user-facing[/green]' if report['user_facing'] else '[dim]internal only[/dim]'}"
+    )
+    for c in report["affected_entry_points"]:
+        ep_branch.add(c)
+    files_branch = tree.add(f"[bold]Affected files[/bold] ({report['affected_file_count']})")
+    for f in report["affected_files"]:
+        files_branch.add(f)
+    console.print(tree)
+
+
+@cli.command()
+@click.option("--port", default=3000, help="Server port")
+@click.pass_context
+def server(ctx: click.Context, port: int) -> None:
+    """Start MCP server."""
+    from adl_drift.server.mcp_server import DriftMCPServer
+
+    project_path = ctx.obj["project_path"]
+    console.print(f"[blue]Starting MCP server on port {port}...[/blue]")
+    console.print(f"[dim]Project: {project_path}[/dim]")
+
+    mcp_server = DriftMCPServer(project_path, port=port)
+    mcp_server.run()
+
+
+@cli.command()
+@click.option("--host", default="127.0.0.1", help="Bind host")
+@click.option("--port", default=8765, help="Bind port")
+@click.pass_context
+def viz(ctx: click.Context, host: str, port: int) -> None:
+    """Start interactive graph visualization web server."""
+    from adl_drift.server.web import serve
+
+    project_path = ctx.obj["project_path"]
+    serve(project_path, host=host, port=port)
+
+
+@cli.group()
+def mcp() -> None:
+    """MCP server + client configuration (serve / setup / doctor)."""
+
+
+@mcp.command("serve")
+@click.pass_context
+def mcp_serve(ctx: click.Context) -> None:
+    """Run MCP server over stdio (for Claude Code / Cursor / Claude Desktop / Antigravity / Codex VS Code)."""
+    from adl_drift.server.mcp_stdio import run_stdio
+
+    project_path = ctx.obj["project_path"]
+    run_stdio(project_path)
+
+
+@mcp.command("setup")
+@click.option("--claude", is_flag=True, help="Configure Claude Code (.mcp.json + skill)")
+@click.option("--cursor", is_flag=True, help="Configure Cursor (.cursor/mcp.json + rule)")
+@click.option("--antigravity", is_flag=True, help="Configure Antigravity IDE (~/.gemini/.../mcp_config.json)")
+@click.option("--codex", is_flag=True, help="Configure Codex (.codex/config.toml + AGENTS.md workflow)")
+@click.option("--print", "dry_run", is_flag=True, help="Dry run: show what would be written")
+@click.pass_context
+def mcp_setup(ctx: click.Context, claude: bool, cursor: bool, antigravity: bool, codex: bool, dry_run: bool) -> None:
+    """Write MCP client configs + install the skill file (merging, never clobbering)."""
+    from adl_drift.harness.setup import setup
+
+    project_path = ctx.obj["project_path"]
+    try:
+        actions = setup(project_path, claude=claude, cursor=cursor, antigravity=antigravity, codex=codex, dry_run=dry_run)
+    except ValueError as e:
+        console.print(f"[red]{e}[/red]")
+        sys.exit(1)
+
+    if dry_run:
+        console.print("[dim]dry run — nothing written[/dim]")
+    styles = {"created": "green", "updated": "yellow", "unchanged": "dim"}
+    for a in actions:
+        console.print(f"  [{styles[a['action']]}]{a['action']:9}[/] {a['path']}")
+    if not dry_run:
+        console.print("\n[green]Done.[/green] Restart your MCP client, then verify with "
+                      "[bold]adl-drift mcp doctor[/bold]")
+
+
+@mcp.command("uninstall")
+@click.option("--claude", is_flag=True, help="Remove Claude Code config + skill")
+@click.option("--cursor", is_flag=True, help="Remove Cursor config + rule")
+@click.option("--antigravity", is_flag=True, help="Remove Antigravity config + AGENTS.md section")
+@click.option("--codex", is_flag=True, help="Remove Codex config and managed AGENTS.md workflow")
+@click.option("--print", "dry_run", is_flag=True, help="Dry run: show what would be removed")
+@click.pass_context
+def mcp_uninstall(ctx: click.Context, claude: bool, cursor: bool, antigravity: bool, codex: bool, dry_run: bool) -> None:
+    """Remove MCP client configs and skill files installed by `mcp setup`."""
+    from adl_drift.harness.setup import uninstall
+
+    project_path = ctx.obj["project_path"]
+    actions = uninstall(project_path, claude=claude, cursor=cursor, antigravity=antigravity, codex=codex, dry_run=dry_run)
+
+    if dry_run:
+        console.print("[dim]dry run — nothing removed[/dim]")
+    styles = {"removed": "green", "unchanged": "dim"}
+    for a in actions:
+        console.print(f"  [{styles.get(a['action'], 'yellow')}]{a['action']:9}[/] {a['path']}")
+
+
+@mcp.command("doctor")
+@click.pass_context
+def mcp_doctor(ctx: click.Context) -> None:
+    """Verify the wiring: config, interpreter, mcp SDK, live stdio handshake."""
+    from adl_drift.harness.setup import doctor
+
+    project_path = ctx.obj["project_path"]
+    report = doctor(project_path)
+    for c in report["checks"]:
+        mark = "[green]ok[/green]" if c["ok"] else (
+            "[red]FAIL[/red]" if c["required"] else "[yellow]warn[/yellow]")
+        console.print(f"  {mark:18} {c['name']:12} {c['detail']}")
+    if report["ok"]:
+        console.print("\n[green]All required checks passed.[/green]")
+    else:
+        console.print("\n[red]Doctor found problems — see FAIL lines above.[/red]")
+        sys.exit(1)
+
+
+@cli.command()
+@click.option("--interval", default=2.0, show_default=True, help="Poll interval in seconds")
+@click.option("--lang", "language", type=click.Choice(["python", "java"]),
+              help="Watch one language only; default auto-detects all backends")
+@click.pass_context
+def watch(ctx: click.Context, interval: float, language: Optional[str]) -> None:
+    """Watch for file changes and keep the index fresh (hash-based, incremental)."""
+    from adl_drift.harness.watch import watch as run_watch
+
+    project_path = ctx.obj["project_path"]
+    try:
+        run_watch(project_path, interval=interval, language=language,
+                  on_event=lambda msg: console.print(f"[dim]{msg}[/dim]"))
+    except KeyboardInterrupt:
+        console.print("[dim]watch stopped[/dim]")
+
+
+@cli.command()
+@click.option("--json", "as_json", is_flag=True,
+              help="Emit {violations, new_patterns, scan_errors, high_security}; "
+                   "exit 1 on HIGH-severity security findings or scan errors")
+@click.pass_context
+def gate(ctx: click.Context, as_json: bool) -> None:
+    """CI gate - check for unapproved patterns."""
+    import json as json_module
+
+    commands = ctx.obj["commands"]
+
+    if as_json:
+        report = commands.gate_report()
+        click.echo(json_module.dumps(report, indent=2))
+        sys.exit(1 if report["failed"] else 0)
+
+    violations = commands.check_gate()
+    if violations:
+        console.print("[red]Gate failed - unapproved patterns found:[/red]")
+        for v in violations:
+            console.print(f"  - {v['pattern']} at {v['file']}:{v['line']}")
+        sys.exit(1)
+    else:
+        console.print("[green]Gate passed - all patterns approved[/green]")
+
+
+@cli.command()
+@click.option("--aggressive", is_flag=True, default=False,
+              help="Also sweep patterns for live files the detector no longer "
+                   "emits (runs a full scan first). Skips approved rows.")
+@click.option("--include-approved", is_flag=True, default=False,
+              help="With --aggressive, also sweep approved stale patterns.")
+@click.option("--dry-run", is_flag=True, default=False,
+              help="Report what would be deleted without writing.")
+@click.pass_context
+def prune(ctx: click.Context, aggressive: bool, include_approved: bool,
+          dry_run: bool) -> None:
+    """Reclaim space from cortex.db: reap dead projects/files, then VACUUM."""
+    commands = ctx.obj["commands"]
+    if aggressive and not dry_run:
+        console.print("[dim]Full scan to refresh detected patterns...[/dim]")
+    report = commands.prune(
+        aggressive=aggressive,
+        include_approved=include_approved,
+        dry_run=dry_run,
+    )
+
+    table = Table(title="Prune" + (" (dry run)" if dry_run else ""))
+    table.add_column("Table", style="cyan")
+    table.add_column("Rows deleted", style="magenta", justify="right")
+    for tbl, n in sorted(report["deleted"].items()):
+        table.add_row(tbl, str(n))
+    if not report["deleted"]:
+        table.add_row("[dim]nothing[/dim]", "0")
+    console.print(table)
+    console.print(
+        f"[dim]dead projects: {report['dead_projects']} · "
+        f"dead files: {report['dead_files']} · "
+        f"stale patterns: {report['stale_patterns']}[/dim]"
+    )
+    if not dry_run:
+        console.print(
+            f"[green]Freed {report['bytes_freed'] / 1e6:.2f} MB[/green]"
+        )
+
+
+def main() -> None:
+    """Entry point for `adl-drift` command."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()