devguard 0.2.0__py3-none-any.whl

devguard/cli.py

@@ -0,0 +1,1510 @@
+"""CLI interface for Guardian."""
+
+import asyncio
+import json
+import logging
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.prompt import Prompt
+from rich.table import Table
+
+from devguard.config import get_settings
+from devguard.core import Guardian
+from devguard.dashboard import run_dashboard
+from devguard.reporting import Reporter
+
+app = typer.Typer(
+    help="Guardian - Unified monitoring for npm packages, GitHub repos, and deployments"
+)
+console = Console()
+
+_MAX_TABLE_ROWS = 15
+
+
+def _sev_style(severity: str) -> str:
+    """Return a Rich style string for the given severity level."""
+    s = severity.lower()
+    if s in ("critical", "error", "high"):
+        return "red"
+    if s in ("warning", "medium"):
+        return "yellow"
+    return "dim"
+
+
+def _print_local_dev_table(hits: list) -> None:
+    if not hits:
+        return
+    table = Table(title="local_dev findings", title_style="bold")
+    table.add_column("repo_path", style="cyan", max_width=40)
+    table.add_column("finding_type", style="yellow")
+    table.add_column("file_path", max_width=50)
+    for h in hits[:_MAX_TABLE_ROWS]:
+        reason = h.reason if hasattr(h, "reason") else h.get("reason", "")
+        ftype = reason.split(":")[0] if ":" in reason else reason
+        repo = h.repo_path if hasattr(h, "repo_path") else h.get("repo_path", "")
+        fpath = h.file_path if hasattr(h, "file_path") else h.get("file_path", "")
+        repo_short = Path(repo).name if repo else ""
+        table.add_row(repo_short, ftype, fpath)
+    if len(hits) > _MAX_TABLE_ROWS:
+        table.add_row("...", f"+{len(hits) - _MAX_TABLE_ROWS} more", "", style="dim")
+    console.print(table)
+
+
+def _print_public_github_secrets_table(report: dict) -> None:
+    findings = report.get("findings", [])
+    if not findings:
+        return
+    from collections import Counter
+
+    repo_counts: Counter = Counter()
+    repo_engine: dict[str, set] = {}
+    for f in findings:
+        repo = f.get("repo", "?")
+        repo_counts[repo] += 1
+        engine = (f.get("type", "") or "").split(":")[0]
+        repo_engine.setdefault(repo, set()).add(engine)
+    table = Table(title="public_github_secrets findings", title_style="bold")
+    table.add_column("repo_name", style="cyan")
+    table.add_column("finding_count", justify="right", style="red")
+    table.add_column("engine")
+    for repo, count in repo_counts.most_common(_MAX_TABLE_ROWS):
+        engines = ", ".join(sorted(repo_engine.get(repo, set())))
+        table.add_row(repo, str(count), engines)
+    if len(repo_counts) > _MAX_TABLE_ROWS:
+        table.add_row("...", f"+{len(repo_counts) - _MAX_TABLE_ROWS} repos", "", style="dim")
+    console.print(table)
+
+
+def _print_local_dirty_worktree_table(report: dict) -> None:
+    findings = report.get("findings", [])
+    if not findings:
+        return
+    from collections import Counter
+
+    repo_counts: Counter = Counter()
+    for f in findings:
+        repo = f.get("repo_path", "?")
+        repo_counts[Path(repo).name] += 1
+    table = Table(title="local_dirty_worktree_secrets findings", title_style="bold")
+    table.add_column("repo_name", style="cyan")
+    table.add_column("finding_count", justify="right", style="red")
+    for repo, count in repo_counts.most_common(_MAX_TABLE_ROWS):
+        table.add_row(repo, str(count))
+    if len(repo_counts) > _MAX_TABLE_ROWS:
+        table.add_row("...", f"+{len(repo_counts) - _MAX_TABLE_ROWS} repos", style="dim")
+    console.print(table)
+
+
+def _print_project_flaudit_table(results: list) -> None:
+    rows = []
+    for r in results:
+        if not r.findings:
+            continue
+        repo_name = Path(r.repo_path).name
+        count = len(r.findings)
+        sevs = [f.severity for f in r.findings]
+        top_sev = "low"
+        for s in ("critical", "high", "medium"):
+            if s in sevs:
+                top_sev = s
+                break
+        rows.append((repo_name, count, top_sev))
+    if not rows:
+        return
+    rows.sort(key=lambda x: -x[1])
+    table = Table(title="project_flaudit findings", title_style="bold")
+    table.add_column("repo_name", style="cyan")
+    table.add_column("finding_count", justify="right")
+    table.add_column("top_severity")
+    for repo_name, count, top_sev in rows[:_MAX_TABLE_ROWS]:
+        table.add_row(repo_name, str(count), f"[{_sev_style(top_sev)}]{top_sev}[/]")
+    if len(rows) > _MAX_TABLE_ROWS:
+        table.add_row("...", f"+{len(rows) - _MAX_TABLE_ROWS} repos", "", style="dim")
+    console.print(table)
+
+
+def _print_gitignore_audit_table(report: dict) -> None:
+    repos = report.get("repos", [])
+    if not repos:
+        return
+    table = Table(title="gitignore_audit findings", title_style="bold")
+    table.add_column("repo_name", style="cyan")
+    table.add_column("is_public")
+    table.add_column("missing_patterns", max_width=60)
+    for r in repos[:_MAX_TABLE_ROWS]:
+        repo_name = Path(r["repo_path"]).name
+        is_pub = "[red]yes[/]" if r.get("is_public") else "no"
+        missing = ", ".join(r.get("missing_patterns", [])[:6])
+        if len(r.get("missing_patterns", [])) > 6:
+            missing += f" (+{len(r['missing_patterns']) - 6})"
+        table.add_row(repo_name, is_pub, missing)
+    if len(repos) > _MAX_TABLE_ROWS:
+        table.add_row("...", "", f"+{len(repos) - _MAX_TABLE_ROWS} repos", style="dim")
+    console.print(table)
+
+
+def _print_dependency_audit_table(report: dict) -> None:
+    repos = [r for r in report.get("repos", []) if r.get("vulns")]
+    if not repos:
+        return
+    table = Table(title="dependency_audit findings", title_style="bold")
+    table.add_column("repo_name", style="cyan")
+    table.add_column("severity")
+    table.add_column("vuln_count", justify="right")
+    for r in repos[:_MAX_TABLE_ROWS]:
+        repo_name = Path(r["repo_path"]).name
+        sev_counts = r.get("severity_counts", {})
+        top_sev = "low"
+        for s in ("critical", "high", "medium", "low"):
+            if sev_counts.get(s, 0) > 0:
+                top_sev = s
+                break
+        count = r.get("vuln_count", len(r.get("vulns", [])))
+        table.add_row(repo_name, f"[{_sev_style(top_sev)}]{top_sev}[/]", str(count))
+    if len(repos) > _MAX_TABLE_ROWS:
+        table.add_row("...", "", f"+{len(repos) - _MAX_TABLE_ROWS} repos", style="dim")
+    console.print(table)
+
+
+def _print_ssh_key_audit_table(report: dict) -> None:
+    keys_with_issues = [k for k in report.get("keys", []) if k.get("issues")]
+    if not keys_with_issues:
+        return
+    table = Table(title="ssh_key_audit findings", title_style="bold")
+    table.add_column("key_file", style="cyan", max_width=40)
+    table.add_column("issue_type", style="yellow")
+    table.add_column("detail", max_width=50)
+    row_count = 0
+    for k in keys_with_issues:
+        key_name = Path(k["key_path"]).name
+        for issue in k["issues"]:
+            if row_count >= _MAX_TABLE_ROWS:
+                break
+            if "passphrase" in issue:
+                itype = "no_passphrase"
+                style = "red"
+            elif "deprecated" in issue or "bit" in issue or "NIST" in issue:
+                itype = "weak_algorithm"
+                style = "red"
+            elif "permissions" in issue:
+                itype = "bad_permissions"
+                style = "yellow"
+            elif "GitHub" in issue:
+                itype = "not_on_github"
+                style = "yellow"
+            else:
+                itype = "other"
+                style = "dim"
+            table.add_row(f"[{style}]{key_name}[/]", itype, issue)
+            row_count += 1
+        if row_count >= _MAX_TABLE_ROWS:
+            break
+    total_issues = sum(len(k["issues"]) for k in keys_with_issues)
+    if total_issues > _MAX_TABLE_ROWS:
+        table.add_row("...", f"+{total_issues - _MAX_TABLE_ROWS} more", "", style="dim")
+    console.print(table)
+
+
+def _print_cargo_publish_audit_table(report: dict) -> None:
+    repos = [r for r in report.get("repos", []) if r.get("findings")]
+    if not repos:
+        return
+    table = Table(title="cargo_publish_audit findings", title_style="bold")
+    table.add_column("repo_name", style="cyan")
+    table.add_column("check")
+    table.add_column("severity")
+    table.add_column("message", max_width=50)
+    row_count = 0
+    for r in repos:
+        for f in r.get("findings", []):
+            if row_count >= _MAX_TABLE_ROWS:
+                break
+            sev = f.get("severity", "info")
+            table.add_row(
+                r["repo_name"],
+                f.get("check", ""),
+                f"[{_sev_style(sev)}]{sev}[/]",
+                f.get("message", ""),
+            )
+            row_count += 1
+        if row_count >= _MAX_TABLE_ROWS:
+            break
+    total = sum(len(r.get("findings", [])) for r in repos)
+    if total > _MAX_TABLE_ROWS:
+        table.add_row("...", "", "", f"+{total - _MAX_TABLE_ROWS} more", style="dim")
+    console.print(table)
+
+
+def _print_ai_editor_config_table(report: dict) -> None:
+    repos = [r for r in report.get("repos", []) if r.get("findings")]
+    if not repos:
+        return
+    table = Table(title="ai_editor_config_audit findings", title_style="bold")
+    table.add_column("repo_name", style="cyan")
+    table.add_column("check")
+    table.add_column("severity")
+    table.add_column("message", max_width=50)
+    row_count = 0
+    for r in repos:
+        for f in r.get("findings", []):
+            if row_count >= _MAX_TABLE_ROWS:
+                break
+            sev = f.get("severity", "info")
+            table.add_row(
+                r["repo_name"],
+                f.get("check", ""),
+                f"[{_sev_style(sev)}]{sev}[/]",
+                f.get("message", ""),
+            )
+            row_count += 1
+        if row_count >= _MAX_TABLE_ROWS:
+            break
+    total = sum(len(r.get("findings", [])) for r in repos)
+    if total > _MAX_TABLE_ROWS:
+        table.add_row("...", "", "", f"+{total - _MAX_TABLE_ROWS} more", style="dim")
+    console.print(table)
+
+
+def _configure_logging(json_output: bool = False) -> None:
+    """Configure logging based on output mode.
+
+    In JSON mode, suppress INFO logs from httpx/httpcore to keep output clean.
+    """
+    if json_output:
+        # Suppress verbose HTTP logs in JSON mode
+        logging.getLogger("httpx").setLevel(logging.WARNING)
+        logging.getLogger("httpcore").setLevel(logging.WARNING)
+        logging.getLogger("devguard").setLevel(logging.WARNING)
+
+
+@app.command()
+def check(
+    json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
+    watch: bool = typer.Option(False, "--watch", "-w", help="Watch mode (continuous checks)"),
+    interval: int = typer.Option(
+        None, "--interval", "-i", help="Interval in seconds for watch mode"
+    ),
+    skip_validation: bool = typer.Option(
+        False, "--skip-validation", help="Skip configuration validation"
+    ),
+    env_file: str | None = typer.Option(
+        None,
+        "--env-file",
+        help="Optional env file path to load (overrides default env_file search).",
+    ),
+) -> None:
+    """Run monitoring checks."""
+    _configure_logging(json_output)
+    settings = get_settings(env_file=env_file)
+    guardian = Guardian(settings)
+    reporter = Reporter(settings)
+
+    # Validate configuration
+    if not skip_validation:
+        warnings = guardian.validate_configuration()
+        if warnings:
+            console.print("[bold yellow]Configuration Warnings:[/bold yellow]")
+            for warning in warnings:
+                console.print(f"  ⚠ {warning}")
+            console.print()
+
+    async def run_check():
+        report = await guardian.run_checks()
+
+        if json_output:
+            report_dict = reporter._report_to_dict(report)
+            console.print(json.dumps(report_dict, indent=2))
+        else:
+            await reporter.report(report)
+
+    if watch:
+        # Don't run watch mode if no checkers configured
+        if not skip_validation and not guardian.checkers:
+            console.print(
+                "[bold red]Error: No checkers configured. Cannot run in watch mode.[/bold red]"
+            )
+            console.print("Configure at least one checker or use --skip-validation to proceed.")
+            raise typer.Exit(code=1)
+
+        interval_seconds = interval or settings.check_interval_seconds
+        console.print(f"[bold]Watching with interval: {interval_seconds}s[/bold]\n")
+
+        async def watch_loop():
+            while True:
+                await run_check()
+                await asyncio.sleep(interval_seconds)
+
+        asyncio.run(watch_loop())
+    else:
+        asyncio.run(run_check())
+
+
+@app.command()
+def config() -> None:
+    """Show current configuration."""
+    settings = get_settings()
+
+    console.print("[bold blue]Guardian Configuration[/bold blue]\n")
+
+    console.print(f"GitHub: {'✓' if settings.github_token else '✗'}")
+    if settings.github_org:
+        console.print(f"  Organization: {settings.github_org}")
+    if settings.github_repos_to_monitor:
+        console.print(f"  Repos: {', '.join(settings.github_repos_to_monitor)}")
+
+    console.print(f"\nVercel: {'✓' if settings.vercel_token else '✗'}")
+    if settings.vercel_team_id:
+        console.print(f"  Team ID: {settings.vercel_team_id}")
+    if settings.vercel_projects_to_monitor:
+        console.print(f"  Projects: {', '.join(settings.vercel_projects_to_monitor)}")
+
+    console.print(f"\nFly.io: {'✓' if settings.fly_api_token else '✗'}")
+    if settings.fly_apps_to_monitor:
+        console.print(f"  Apps: {', '.join(settings.fly_apps_to_monitor)}")
+
+    console.print(f"\nnpm: {'✓' if settings.npm_packages_to_monitor else '✗'}")
+    if settings.npm_packages_to_monitor:
+        console.print(f"  Packages: {', '.join(settings.npm_packages_to_monitor)}")
+    if settings.snyk_token:
+        console.print("  Snyk: ✓")
+    if settings.npm_security_enabled:
+        console.print("  Deep Security Analysis: ✓")
+
+
+@app.command()
+def auth(
+    service: str = typer.Argument(..., help="Service to authenticate (gh, vercel, fly, snyk)"),
+    token: str = typer.Option(
+        None, "--token", "-t", help="Token value (if not provided, will prompt)"
+    ),
+    test: bool = typer.Option(False, "--test", help="Test the token after setting it"),
+) -> None:
+    """Authenticate with a service by setting API token."""
+    service = service.lower()
+    valid_services = ["gh", "github", "vercel", "fly", "snyk"]
+
+    if service not in valid_services:
+        console.print(f"[bold red]Error: Invalid service '{service}'[/bold red]")
+        console.print(f"Valid services: {', '.join(valid_services)}")
+        raise typer.Exit(code=1)
+
+    # Get token
+    if not token:
+        console.print(f"[bold]Setting up {service.upper()} authentication[/bold]")
+        token = Prompt.ask(f"Enter your {service.upper()} token", password=True)
+        if not token:
+            console.print("[bold red]Error: Token cannot be empty[/bold red]")
+            raise typer.Exit(code=1)
+
+    # Determine env var name
+    env_var_map = {
+        "gh": "GITHUB_TOKEN",
+        "github": "GITHUB_TOKEN",  # Alias for backwards compatibility
+        "vercel": "VERCEL_TOKEN",
+        "fly": "FLY_API_TOKEN",
+        "snyk": "SNYK_TOKEN",
+    }
+    env_var = env_var_map[service]
+
+    # Write to .env file
+    env_file = Path(".env")
+    env_content = ""
+
+    # Read existing .env if it exists
+    if env_file.exists():
+        env_content = env_file.read_text()
+
+    # Update or add the token
+    lines = env_content.split("\n") if env_content else []
+    updated = False
+    new_lines = []
+
+    for line in lines:
+        if line.startswith(f"{env_var}="):
+            new_lines.append(f"{env_var}={token}")
+            updated = True
+        else:
+            new_lines.append(line)
+
+    if not updated:
+        new_lines.append(f"{env_var}={token}")
+
+    # Write back to .env
+    env_file.write_text("\n".join(new_lines) + "\n")
+
+    console.print(f"[bold green]✓[/bold green] {service.upper()} token saved to .env file")
+
+    # Test the token if requested
+    if test:
+        console.print(f"\n[bold]Testing {service.upper()} token...[/bold]")
+        from devguard.cli_helpers import test_service_token
+
+        success, message = asyncio.run(test_service_token(service, token))
+        if success:
+            console.print(f"[bold green]✓[/bold green] {message}")
+        else:
+            console.print(f"[bold red]✗[/bold red] {message}")
+            console.print("[yellow]Token saved but test failed. Please verify manually.[/yellow]")
+
+    console.print(
+        "\n[bold]Note:[/bold] Restart Guardian or reload environment to use the new token."
+    )
+
+
+@app.command()
+def mcp() -> None:
+    """Start the Guardian MCP server."""
+    from devguard.mcp_server import run_mcp_server
+
+    console.print("[bold green]Starting Guardian MCP Server...[/bold green]")
+    run_mcp_server()
+
+
+@app.command()
+def auth_status() -> None:
+    """Show authentication status for all services."""
+    from devguard.cli_helpers import show_auth_status
+
+    settings = get_settings()
+    show_auth_status(settings)
+
+
+@app.command()
+def dashboard(
+    host: str = typer.Option(None, "--host", help="Host to bind to"),
+    port: int = typer.Option(None, "--port", help="Port to bind to"),
+) -> None:
+    """Start the web dashboard server."""
+    settings = get_settings()
+
+    if not settings.dashboard_enabled and not host:
+        console.print("[bold yellow]Warning:[/bold yellow] Dashboard is not enabled in config.")
+        console.print("Set DASHBOARD_ENABLED=true or use --host/--port to override.")
+        console.print()
+
+    if settings.dashboard_api_key:
+        console.print("[bold green]✓[/bold green] Dashboard API key configured")
+    else:
+        console.print(
+            "[bold yellow]⚠[/bold yellow] DASHBOARD_API_KEY not set - "
+            "dashboard will be accessible without authentication (development mode)"
+        )
+        console.print("Generate a key with: [dim]openssl rand -hex 32[/dim]")
+        console.print()
+
+    console.print("[bold]Starting Guardian dashboard...[/bold]")
+    dashboard_url = f"http://{host or settings.dashboard_host}:{port or settings.dashboard_port}"
+    console.print(f"Access at: {dashboard_url}")
+    console.print()
+
+    try:
+        run_dashboard(host=host, port=port)
+    except KeyboardInterrupt:
+        console.print("\n[bold]Dashboard stopped[/bold]")
+        raise typer.Exit(0)
+
+    console.print()
+
+
+@app.command()
+def spec(
+    init: bool = typer.Option(False, "--init", help="Create a new spec file interactively"),
+    from_env: bool = typer.Option(False, "--from-env", help="Generate spec from current .env"),
+    edit: bool = typer.Option(False, "--edit", help="Open spec file in editor"),
+) -> None:
+    """Manage monitoring specifications."""
+    from pathlib import Path
+
+    from devguard.spec import MonitorSpec, get_default_spec, load_spec
+
+    spec_file = Path("devguard.spec.yaml")
+
+    if init:
+        if spec_file.exists():
+            if not typer.confirm(f"{spec_file} already exists. Overwrite?", default=False):
+                console.print("[yellow]Cancelled[/yellow]")
+                return
+
+        console.print("[bold]Creating new monitoring spec...[/bold]")
+        console.print()
+
+        # Ask basic questions
+        name = Prompt.ask("Spec name", default="default")
+        description = Prompt.ask("Description (optional)", default="")
+
+        # Ask what to discover
+        console.print("\n[bold]What should Guardian discover?[/bold]")
+        discover_npm = typer.confirm("  Discover npm packages?", default=True)
+        discover_github = typer.confirm("  Discover GitHub repos?", default=True)
+        discover_vercel = typer.confirm("  Discover Vercel projects?", default=True)
+        discover_fly = typer.confirm("  Discover Fly.io apps?", default=True)
+        discover_domains = typer.confirm("  Discover domains from configs?", default=False)
+        discover_commits = typer.confirm("  Track GitHub commits?", default=False)
+        discover_mentions = typer.confirm("  Track GitHub mentions?", default=False)
+
+        # Build spec
+        spec = MonitorSpec(name=name, description=description or None)
+        default_spec = get_default_spec()
+
+        # Copy relevant rules
+        rule_map = {
+            "npm": ["npm_list", "npm_package_json"],
+            "github": ["github_repos"],
+            "vercel": ["vercel_projects"],
+            "fly": ["fly_apps"],
+            "domains": ["domains"],
+            "commits": ["github_commits"],
+            "mentions": ["github_mentions"],
+        }
+
+        for key, rule_names in rule_map.items():
+            enabled = locals().get(f"discover_{key}", False)
+            if enabled:
+                for rule_name in rule_names:
+                    rule = next(
+                        (r for r in default_spec.discovery_rules if r.name == rule_name), None
+                    )
+                    if rule:
+                        spec.discovery_rules.append(rule)
+
+        # Always include username discovery (needed for mentions/commits)
+        username_rule = next(
+            (r for r in default_spec.discovery_rules if r.name == "github_username"), None
+        )
+        if username_rule:
+            spec.discovery_rules.append(username_rule)
+
+        # Save spec
+        import yaml
+
+        spec_dict = spec.model_dump(exclude_none=True)
+        with open(spec_file, "w") as f:
+            yaml.dump(spec_dict, f, default_flow_style=False, sort_keys=False)
+
+        console.print(f"\n[bold green]✓[/bold green] Created {spec_file}")
+        console.print("[dim]Edit it to customize discovery rules[/dim]")
+
+    elif from_env:
+        # Generate spec from current .env
+        from devguard.config import get_settings
+
+        settings = get_settings()
+        spec = MonitorSpec(name="from_env", description="Generated from current .env")
+
+        # Add rules based on what's configured
+        default_spec = get_default_spec()
+
+        if settings.npm_packages_to_monitor:
+            spec.manual_resources["npm"] = settings.npm_packages_to_monitor
+            # Also enable discovery
+            spec.discovery_rules.extend(
+                [r for r in default_spec.discovery_rules if "npm" in r.name]
+            )
+
+        if settings.github_token:
+            if settings.github_repos_to_monitor:
+                spec.manual_resources["github"] = settings.github_repos_to_monitor
+            spec.discovery_rules.extend(
+                [r for r in default_spec.discovery_rules if "github" in r.name]
+            )
+
+        if settings.vercel_token:
+            if settings.vercel_projects_to_monitor:
+                spec.manual_resources["vercel"] = settings.vercel_projects_to_monitor
+            spec.discovery_rules.extend(
+                [r for r in default_spec.discovery_rules if "vercel" in r.name]
+            )
+
+        if settings.fly_api_token:
+            if settings.fly_apps_to_monitor:
+                spec.manual_resources["fly"] = settings.fly_apps_to_monitor
+            spec.discovery_rules.extend(
+                [r for r in default_spec.discovery_rules if "fly" in r.name]
+            )
+
+        # Save
+        import yaml
+
+        spec_dict = spec.model_dump(exclude_none=True)
+        with open(spec_file, "w") as f:
+            yaml.dump(spec_dict, f, default_flow_style=False, sort_keys=False)
+
+        console.print(f"[bold green]✓[/bold green] Generated {spec_file} from current .env")
+
+    elif edit:
+        import os
+        import subprocess
+
+        editor = os.environ.get("EDITOR", "nano")
+        try:
+            subprocess.run([editor, str(spec_file)])
+        except Exception as e:
+            console.print(f"[bold red]Error opening editor: {e}[/bold red]")
+            console.print(f"Edit {spec_file} manually")
+
+    else:
+        # Show current spec
+        if spec_file.exists():
+            try:
+                spec = load_spec(spec_file)
+                console.print(f"[bold blue]Current Spec: {spec.name}[/bold blue]")
+                if spec.description:
+                    console.print(f"[dim]{spec.description}[/dim]")
+                console.print(f"\nDiscovery Rules: {len(spec.discovery_rules)}")
+                for rule in spec.discovery_rules:
+                    status = "✓" if rule.enabled else "○"
+                    console.print(f"  {status} {rule.name} ({rule.type})")
+                if spec.manual_resources:
+                    console.print("\nManual Resources:")
+                    for rtype, resources in spec.manual_resources.items():
+                        console.print(f"  {rtype}: {len(resources)} items")
+            except Exception as e:
+                console.print(f"[bold red]Error loading spec: {e}[/bold red]")
+        else:
+            console.print(f"[yellow]No spec file found: {spec_file}[/yellow]")
+            console.print("Run [bold]devguard spec --init[/bold] to create one")
+
+
+@app.command()
+def discover(
+    spec_file: str = typer.Option(
+        "devguard.spec.yaml", "--spec", "-s", help="Path to monitoring spec file"
+    ),
+    base_path: str = typer.Option(
+        None, "--base-path", "-b", help="Base path for file scanning (default: ~/Documents/dev)"
+    ),
+    json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
+    update_env: bool = typer.Option(
+        False, "--update-env", help="Update .env file with discovered resources"
+    ),
+    env_file: str = typer.Option(
+        ".env",
+        "--env-file",
+        help="Env file path to write when using --update-env (default: .env).",
+    ),
+) -> None:
+    """Auto-discover resources to monitor based on spec."""
+    from pathlib import Path
+
+    from devguard.discovery import discover_all
+    from devguard.spec import load_spec
+
+    # Load spec
+    spec_path = Path(spec_file)
+    if spec_path.exists():
+        try:
+            spec = load_spec(spec_path)
+        except Exception as e:
+            console.print(f"[bold red]Error loading spec: {e}[/bold red]")
+            raise typer.Exit(1)
+    else:
+        console.print(f"[bold yellow]Spec file not found: {spec_path}[/bold yellow]")
+        console.print("Using default spec...")
+        from devguard.spec import get_default_spec
+
+        spec = get_default_spec()
+
+    # Determine base path
+    if base_path:
+        base = Path(base_path)
+    else:
+        base = Path.home() / "Documents" / "dev"
+
+    console.print(f"[bold]Discovering resources from: {base}[/bold]")
+    console.print(f"[dim]Using spec: {spec.name}[/dim]\n")
+
+    async def run_discovery():
+        result = await discover_all(spec, base)
+        return result
+
+    result = asyncio.run(run_discovery())
+
+    if json_output:
+        console.print(json.dumps(result.to_dict(), indent=2))
+    else:
+        # Display results
+        from rich.table import Table
+
+        console.print("[bold blue]Discovery Results[/bold blue]\n")
+
+        if result.resources:
+            table = Table(title="Discovered Resources")
+            table.add_column("Type", style="cyan")
+            table.add_column("Count", style="magenta")
+            table.add_column("Examples", style="green")
+
+            for resource_type, resources in result.resources.items():
+                count = len(resources)
+                examples = ", ".join(str(r)[:50] for r in resources[:3])
+                if count > 3:
+                    examples += f" ... (+{count - 3} more)"
+                table.add_row(resource_type, str(count), examples)
+
+            console.print(table)
+            console.print()
+
+        if result.errors:
+            console.print("[bold red]Errors:[/bold red]")
+            for error in result.errors:
+                console.print(f"  • {error}")
+            console.print()
+
+        # Update .env if requested
+        if update_env:
+            env_path = Path(env_file)
+            env_content = env_path.read_text() if env_path.exists() else ""
+
+            # Update npm packages
+            if "npm" in result.resources:
+                npm_packages = result.resources["npm"]
+                env_content = _update_env_var(
+                    env_content, "NPM_PACKAGES_TO_MONITOR", ",".join(npm_packages[:20])
+                )
+
+            # Update GitHub repos
+            if "github" in result.resources:
+                github_repos = result.resources["github"]
+                env_content = _update_env_var(
+                    env_content, "GITHUB_REPOS_TO_MONITOR", ",".join(github_repos[:20])
+                )
+
+            # Update Vercel projects
+            if "vercel" in result.resources:
+                vercel_projects = result.resources["vercel"]
+                env_content = _update_env_var(
+                    env_content, "VERCEL_PROJECTS_TO_MONITOR", ",".join(vercel_projects[:20])
+                )
+
+            # Update Fly apps
+            if "fly" in result.resources:
+                fly_apps = result.resources["fly"]
+                env_content = _update_env_var(
+                    env_content, "FLY_APPS_TO_MONITOR", ",".join(fly_apps[:20])
+                )
+
+            env_path.write_text(env_content)
+            console.print("[bold green]✓[/bold green] Updated .env file with discovered resources")
+
+
+@app.command()
+def stats(
+    live_mode: bool = typer.Option(
+        False, "--live", "-l", help="Live updating stats (refresh every 5s)"
+    ),
+) -> None:
+    """Show current monitoring statistics in a TUI."""
+    from rich.console import Console
+    from rich.layout import Layout
+    from rich.live import Live
+    from rich.panel import Panel
+    from rich.table import Table
+
+    console = Console()
+
+    def generate_stats() -> Layout:
+        """Generate the stats layout."""
+        settings = get_settings()
+        guardian = Guardian(settings)
+
+        # Run checks to get current stats
+        import asyncio
+
+        report = asyncio.run(guardian.run_checks())
+
+        # Create layout
+        layout = Layout()
+
+        # Header
+        header = Panel.fit(
+            "[bold blue]🛡️ Guardian Monitoring Stats[/bold blue]",
+            border_style="blue",
+        )
+
+        # Summary table
+        summary_table = Table(show_header=False, box=None, padding=(0, 2))
+        summary_table.add_column("Metric", style="cyan", width=25)
+        summary_table.add_column("Value", style="magenta")
+
+        summary = report.summary
+        summary_table.add_row("Total Checks", str(summary.get("total_checks", 0)))
+        summary_table.add_row("Successful", f"[green]{summary.get('successful_checks', 0)}[/green]")
+        summary_table.add_row("Failed", f"[red]{summary.get('failed_checks', 0)}[/red]")
+        summary_table.add_row("", "")
+        summary_table.add_row("Vulnerabilities", str(summary.get("total_vulnerabilities", 0)))
+        summary_table.add_row(
+            "Critical", f"[red]{summary.get('critical_vulnerabilities', 0)}[/red]"
+        )
+        summary_table.add_row(
+            "Unhealthy Deployments", f"[yellow]{summary.get('unhealthy_deployments', 0)}[/yellow]"
+        )
+        summary_table.add_row("Repository Alerts", str(summary.get("open_repository_alerts", 0)))
+        summary_table.add_row("", "")
+        summary_table.add_row(
+            "Total Cost (USD)",
+            f"[bold yellow]${summary.get('total_cost_usd', 0):.2f}[/bold yellow]",
+        )
+
+        summary_panel = Panel(summary_table, title="Summary", border_style="blue")
+
+        # Checks table
+        checks_table = Table(title="Check Results")
+        checks_table.add_column("Service", style="cyan")
+        checks_table.add_column("Status", style="magenta")
+        checks_table.add_column("Vulns", justify="right")
+        checks_table.add_column("Deployments", justify="right")
+        checks_table.add_column("Cost", justify="right", style="yellow")
+
+        for check in report.checks:
+            status_icon = "[green]✓[/green]" if check.success else "[red]✗[/red]"
+            vuln_count = len(check.vulnerabilities)
+            deploy_count = len(check.deployments)
+            cost = sum(cm.amount or 0 for cm in check.cost_metrics)
+            cost_str = f"${cost:.2f}" if cost > 0 else "-"
+
+            checks_table.add_row(
+                check.check_type.upper(),
+                status_icon,
+                str(vuln_count),
+                str(deploy_count),
+                cost_str,
+            )
+
+        checks_panel = Panel(checks_table, title="Service Checks", border_style="green")
+
+        # Cost breakdown
+        cost_table = Table(title="Cost Breakdown", show_header=False, box=None)
+        cost_table.add_column("Service", style="cyan")
+        cost_table.add_column("Amount", justify="right", style="yellow")
+        cost_table.add_column("Usage", style="green")
+
+        all_cost_metrics = report.get_cost_metrics()
+        if all_cost_metrics:
+            for cm in all_cost_metrics:
+                amount_str = f"${cm.amount:.2f}" if cm.amount else "$0.00"
+                usage_str = f"{cm.usage:.0f}/{cm.limit:.0f}" if cm.limit else f"{cm.usage:.0f}"
+                usage_pct = f"({cm.usage_percent:.1f}%)" if cm.usage_percent else ""
+                cost_table.add_row(cm.service, amount_str, f"{usage_str} {usage_pct}")
+        else:
+            cost_table.add_row("No cost data", "-", "-")
+
+        cost_panel = Panel(cost_table, title="Cost Metrics", border_style="yellow")
+
+        # Layout structure
+        layout.split_column(
+            Layout(header, size=3),
+            Layout(summary_panel, name="summary"),
+            Layout(checks_panel, name="checks"),
+            Layout(cost_panel, name="costs"),
+        )
+
+        layout["summary"].size = 12
+        layout["checks"].size = None
+        layout["costs"].size = None
+
+        return layout
+
+    if live_mode:
+        # Live updating mode
+        with Live(generate_stats(), refresh_per_second=0.2, screen=True) as live_view:
+            import time
+
+            while True:
+                try:
+                    time.sleep(5)
+                    live_view.update(generate_stats())
+                except KeyboardInterrupt:
+                    break
+    else:
+        # Single snapshot
+        console.print(generate_stats())
+
+
+@app.command("sweep-dev")
+def sweep_dev(
+    dev_root: str = typer.Option(
+        None,
+        "--dev-root",
+        help="Dev workspace root (default: $DEV_DIR or ~/Documents/dev).",
+    ),
+    output: str = typer.Option(
+        "devguard_sweep_dev.json",
+        "--output",
+        "-o",
+        help="Where to write the JSON report.",
+    ),
+    max_blob_mb: int = typer.Option(
+        5,
+        "--max-blob-mb",
+        help="Flag tracked files larger than this many MiB (working tree size).",
+    ),
+    max_depth: int = typer.Option(
+        2,
+        "--max-depth",
+        help="How deep under dev_root to look for git repos (bounded).",
+    ),
+) -> None:
+    """Sweep local dev repos for likely accidental committed artifacts."""
+    from devguard.sweeps.local_dev import default_dev_root, sweep_dev_repos, write_report
+
+    root = Path(dev_root).expanduser() if dev_root else default_dev_root()
+    report_path = Path(output).expanduser()
+
+    hits, meta = sweep_dev_repos(
+        root,
+        max_blob_bytes=max_blob_mb * 1024 * 1024,
+        max_depth=max_depth,
+    )
+    write_report(report_path, hits, meta)
+
+    console.print(f"[bold]Wrote report:[/bold] {report_path}")
+    console.print(f"[bold]Repos scanned:[/bold] {meta['repos_scanned']}")
+    console.print(f"[bold]Findings:[/bold] {len(hits)}")
+    _print_local_dev_table(hits)
+
+    if hits:
+        console.print(
+            "[bold yellow]Action:[/bold yellow] Review report and clean up flagged files."
+        )
+        raise typer.Exit(code=2)
+
+
+@app.command()
+def sweep(
+    spec_file: str = typer.Option(
+        "devguard.spec.yaml",
+        "--spec",
+        "-s",
+        help="Path to spec file (drives which sweeps run and their policy).",
+    ),
+    dev_root: str = typer.Option(
+        None,
+        "--dev-root",
+        help="Dev workspace root (default: $DEV_DIR or ~/Documents/dev).",
+    ),
+    only: list[str] = typer.Option(
+        None,
+        "--only",
+        help="Run only these sweeps (repeatable). Known: local_dev, public_github_secrets, local_dirty_worktree_secrets, project_flaudit, gitignore_audit, dependency_audit, ssh_key_audit, cargo_publish_audit, ai_editor_config_audit",
+    ),
+    format: str = typer.Option(
+        "text",
+        "--format",
+        "-f",
+        help="Output format: text, json, sarif",
+    ),
+) -> None:
+    """Run spec-driven sweeps (policy checks).
+
+    Today this runs the local dev repo sweep (and will expand over time).
+    """
+    import sys
+
+    from devguard.spec import MonitorSpec, SweepSpec, load_spec
+    from devguard.sweeps.local_dev import DEFAULT_DENY_GLOBS, default_dev_root, sweep_dev_repos
+    from devguard.sweeps.local_dirty_worktree_secrets import (
+        scan_dirty_worktrees,
+    )
+    from devguard.sweeps.local_dirty_worktree_secrets import (
+        write_report as write_dirty_json,
+    )
+    from devguard.sweeps.public_github_secrets import scan_public_github_repos
+    from devguard.sweeps.public_github_secrets import write_report as write_json
+
+    machine_output = format in ("json", "sarif")
+    sweep_reports: list[tuple[str, dict]] = []
+
+    stderr_console = Console(stderr=True)
+    spec_path = Path(spec_file)
+    if not spec_path.exists():
+        stderr_console.print(
+            "No spec file found; using defaults. Create devguard.spec.yaml to customize."
+        )
+        spec = MonitorSpec(
+            name="default",
+            discovery_rules=[],
+            manual_resources={},
+            filters={},
+            sweeps=SweepSpec(),
+        )
+    else:
+        spec = load_spec(spec_path)
+
+    wanted = {w.strip() for w in (only or []) if w and w.strip()}
+
+    exit_code = 0
+
+    # local-dev sweep
+    local = spec.sweeps.local_dev
+    if local.enabled and (not wanted or "local_dev" in wanted):
+        root = Path(dev_root).expanduser() if dev_root else default_dev_root()
+        deny = list(DEFAULT_DENY_GLOBS) + list(local.deny_globs or [])
+        hits, meta = sweep_dev_repos(
+            root,
+            deny_globs=deny,
+            max_blob_bytes=local.max_blob_mb * 1024 * 1024,
+            max_depth=local.max_depth,
+        )
+        out_path = Path(local.output).expanduser()
+        from devguard.sweeps.local_dev import write_report
+
+        write_report(out_path, hits, meta)
+        if machine_output:
+            from dataclasses import asdict
+
+            sweep_reports.append(
+                (
+                    "local_dev",
+                    {**meta, "hits": [asdict(h) for h in hits]},
+                )
+            )
+        else:
+            console.print(f"[bold]local_dev report:[/bold] {out_path}")
+            console.print(f"[bold]Repos scanned:[/bold] {meta['repos_scanned']}")
+            console.print(f"[bold]Findings:[/bold] {len(hits)}")
+            _print_local_dev_table(hits)
+        if hits:
+            exit_code = max(exit_code, 2)
+
+    # public-github-secrets sweep
+    pub = spec.sweeps.public_github_secrets
+    if pub.enabled and (not wanted or "public_github_secrets" in wanted):
+        report, errors = scan_public_github_repos(
+            owners=pub.owners,
+            include_repos=pub.include_repos,
+            exclude_repos=pub.exclude_repos,
+            include_forks=pub.include_forks,
+            max_repos=pub.max_repos,
+            engines=getattr(pub, "engines", None),
+            timeout_s=pub.timeout_s,
+            max_concurrency=pub.max_concurrency,
+        )
+        out_path = Path(pub.output).expanduser()
+        write_json(out_path, report)
+        if machine_output:
+            sweep_reports.append(("public_github_secrets", report))
+        else:
+            console.print(f"[bold]public_github_secrets report:[/bold] {out_path}")
+            console.print(f"[bold]Repos scanned:[/bold] {report['scope']['repos_scanned_count']}")
+            console.print(f"[bold]Findings:[/bold] {report['summary']['findings_total']}")
+            if errors:
+                console.print(f"[yellow]Errors:[/yellow] {len(errors)} (see report)")
+                if pub.fail_on_errors:
+                    console.print(
+                        "[bold red]Action:[/bold red] Fix scan errors (missed coverage) and rerun."
+                    )
+            _print_public_github_secrets_table(report)
+        if errors and pub.fail_on_errors:
+            exit_code = max(exit_code, 3)
+        if report["summary"]["findings_total"] > 0:
+            exit_code = max(exit_code, 2)
+
+    # local dirty worktree secret sweep
+    dirty = spec.sweeps.local_dirty_worktree_secrets
+    if dirty.enabled and (not wanted or "local_dirty_worktree_secrets" in wanted):
+        root = Path(dirty.dev_root).expanduser() if dirty.dev_root else default_dev_root()
+        report, errors = scan_dirty_worktrees(
+            dev_root=root,
+            max_depth=dirty.max_depth,
+            only_dirty=dirty.only_dirty,
+            exclude_repo_globs=dirty.exclude_repo_globs,
+            check_upstream=dirty.check_upstream,
+            fetch_remotes=dirty.fetch_remotes,
+            max_paths_per_repo=getattr(dirty, "max_paths_per_repo", 50),
+            include_ignored_files=getattr(dirty, "include_ignored_files", False),
+            max_concurrency=dirty.max_concurrency,
+            timeout_s=dirty.timeout_s,
+        )
+        out_path = Path(dirty.output).expanduser()
+        write_dirty_json(out_path, report)
+        if machine_output:
+            sweep_reports.append(("local_dirty_worktree_secrets", report))
+        else:
+            console.print(f"[bold]local_dirty_worktree_secrets report:[/bold] {out_path}")
+            console.print(f"[bold]Repos scanned:[/bold] {report['scope']['repos_scanned_count']}")
+            console.print(f"[bold]Findings:[/bold] {report['summary']['findings_total']}")
+            if errors:
+                console.print(f"[yellow]Errors:[/yellow] {len(errors)} (see report)")
+            _print_local_dirty_worktree_table(report)
+        if report["summary"]["findings_total"] > 0:
+            exit_code = max(exit_code, 2)
+
+    # project_flaudit sweep (files-to-prompt + OpenRouter/Gemini)
+    flaudit = spec.sweeps.project_flaudit
+    if flaudit.enabled and (not wanted or "project_flaudit" in wanted):
+        from devguard.sweeps.local_dev import default_dev_root
+        from devguard.sweeps.project_flaudit import scan_project_flaudit
+        from devguard.sweeps.project_flaudit import write_report as write_flaudit
+
+        root = Path(flaudit.dev_root).expanduser() if flaudit.dev_root else default_dev_root()
+        settings = get_settings()
+        wr_path = None
+        if flaudit.workspace_rules_path:
+            p = Path(flaudit.workspace_rules_path).expanduser()
+            if not p.is_absolute():
+                p = root / p
+            wr_path = str(p.resolve()) if p.resolve().is_dir() else None
+        results, meta = scan_project_flaudit(
+            dev_root=root,
+            k_recent=flaudit.k_recent,
+            max_depth=flaudit.max_depth,
+            model_id=flaudit.model_id,
+            settings=settings,
+            max_prompt_chars=flaudit.max_prompt_chars,
+            include_rules=flaudit.include_rules,
+            exclude_repo_globs=flaudit.exclude_repo_globs,
+            workspace_rules_path=wr_path,
+            workspace_rules_include=flaudit.workspace_rules_include or None,
+            max_workspace_rules_chars=flaudit.max_workspace_rules_chars,
+            severity_guidance=flaudit.severity_guidance,
+            depth_0_skip_prefixes=flaudit.depth_0_skip_prefixes,
+            depth_0_allow_names=flaudit.depth_0_allow_names,
+            scope_recent_commits=flaudit.scope_recent_commits,
+            public_repo_names=flaudit.public_repo_names or None,
+            stricter_public_prompt=flaudit.stricter_public_prompt,
+        )
+        out_path = Path(flaudit.output).expanduser()
+        write_flaudit(out_path, results, meta)
+        total_findings = sum(len(r.findings) for r in results)
+        total_errors = sum(1 for r in results if r.error)
+        if machine_output:
+            sweep_reports.append(
+                (
+                    "project_flaudit",
+                    json.loads(out_path.read_text()),
+                )
+            )
+        else:
+            console.print(f"[bold]project_flaudit report:[/bold] {out_path}")
+            console.print(f"[bold]Projects analyzed:[/bold] {meta['repos_scanned']}")
+            console.print(f"[bold]Findings:[/bold] {total_findings}")
+            if total_errors:
+                console.print(f"[bold]Errors:[/bold] {total_errors}", style="yellow")
+            _print_project_flaudit_table(results)
+        if total_findings > 0:
+            exit_code = max(exit_code, 2)
+
+    # gitignore audit sweep
+    gi = spec.sweeps.gitignore_audit
+    if gi.enabled and (not wanted or "gitignore_audit" in wanted):
+        from devguard.sweeps.gitignore_audit import audit_gitignores
+        from devguard.sweeps.gitignore_audit import write_report as write_gi
+
+        root = Path(gi.dev_root).expanduser() if gi.dev_root else default_dev_root()
+        report, errors = audit_gitignores(
+            dev_root=root,
+            max_depth=gi.max_depth,
+            exclude_repo_globs=gi.exclude_repo_globs,
+        )
+        out_path = Path(gi.output).expanduser()
+        write_gi(out_path, report)
+        if machine_output:
+            sweep_reports.append(("gitignore_audit", report))
+        else:
+            console.print(f"[bold]gitignore_audit report:[/bold] {out_path}")
+            console.print(f"[bold]Repos scanned:[/bold] {report['scope']['repos_scanned']}")
+            console.print(
+                f"[bold]Repos without .gitignore:[/bold]"
+                f" {report['summary']['repos_without_gitignore']}"
+            )
+            console.print(
+                f"[bold]Public repos with gaps:[/bold]"
+                f" {report['summary']['public_repos_with_gaps']}"
+            )
+            console.print(f"[bold]Total gaps:[/bold] {report['summary']['total_gaps']}")
+            if errors:
+                console.print(f"[yellow]Errors:[/yellow] {len(errors)} (see report)")
+            _print_gitignore_audit_table(report)
+        if report["summary"]["public_repos_with_gaps"] > 0:
+            exit_code = max(exit_code, 2)
+
+    # dependency audit sweep
+    depaudit = spec.sweeps.dependency_audit
+    if depaudit.enabled and (not wanted or "dependency_audit" in wanted):
+        from devguard.sweeps.dependency_audit import audit_dependencies
+        from devguard.sweeps.dependency_audit import write_report as write_depaudit
+
+        root = Path(depaudit.dev_root).expanduser() if depaudit.dev_root else default_dev_root()
+        report, errors = audit_dependencies(
+            dev_root=root,
+            max_depth=depaudit.max_depth,
+            exclude_repo_globs=depaudit.exclude_repo_globs,
+            engines=depaudit.engines,
+            max_concurrency=depaudit.max_concurrency,
+            timeout_s=depaudit.timeout_s,
+        )
+        out_path = Path(depaudit.output).expanduser()
+        write_depaudit(out_path, report)
+        if machine_output:
+            sweep_reports.append(("dependency_audit", report))
+        else:
+            console.print(f"[bold]dependency_audit report:[/bold] {out_path}")
+            console.print(f"[bold]Repos scanned:[/bold] {report['scope']['repos_scanned']}")
+            console.print(f"[bold]Repos with vulns:[/bold] {report['summary']['repos_with_vulns']}")
+            console.print(f"[bold]Total vulns:[/bold] {report['summary']['total_vulns']}")
+            sev = report["summary"]["severity_counts"]
+            console.print(
+                f"[bold]Severity:[/bold] critical={sev.get('critical', 0)}"
+                f" high={sev.get('high', 0)}"
+                f" medium={sev.get('medium', 0)}"
+                f" low={sev.get('low', 0)}"
+            )
+            if errors:
+                console.print(f"[yellow]Errors:[/yellow] {len(errors)} (see report)")
+            _print_dependency_audit_table(report)
+        if report["summary"]["total_vulns"] > 0:
+            exit_code = max(exit_code, 2)
+
+    # ssh key audit sweep
+    sshk = spec.sweeps.ssh_key_audit
+    if sshk.enabled and (not wanted or "ssh_key_audit" in wanted):
+        from devguard.sweeps.ssh_key_audit import audit_ssh_keys
+        from devguard.sweeps.ssh_key_audit import write_report as write_sshk
+
+        ssh_path = Path(sshk.ssh_dir).expanduser()
+        report, errors = audit_ssh_keys(
+            ssh_dir=ssh_path,
+            check_github=sshk.check_github,
+            min_rsa_bits=sshk.min_rsa_bits,
+            flag_ecdsa=sshk.flag_ecdsa,
+        )
+        out_path = Path(sshk.output).expanduser()
+        write_sshk(out_path, report)
+        if machine_output:
+            sweep_reports.append(("ssh_key_audit", report))
+        else:
+            console.print(f"[bold]ssh_key_audit report:[/bold] {out_path}")
+            console.print(f"[bold]Keys scanned:[/bold] {report['summary']['keys_scanned']}")
+            console.print(f"[bold]Issues:[/bold] {report['summary']['issues_total']}")
+            if errors:
+                console.print(f"[yellow]Errors:[/yellow] {len(errors)} (see report)")
+            _print_ssh_key_audit_table(report)
+        if report["summary"]["issues_total"] > 0:
+            exit_code = max(exit_code, 2)
+
+    # cargo publish audit sweep
+    cpub = spec.sweeps.cargo_publish_audit
+    if cpub.enabled and (not wanted or "cargo_publish_audit" in wanted):
+        from devguard.sweeps.cargo_publish_audit import audit_cargo_publish
+        from devguard.sweeps.cargo_publish_audit import write_report as write_cpub
+
+        root = Path(cpub.dev_root).expanduser() if cpub.dev_root else default_dev_root()
+        report, errors = audit_cargo_publish(
+            dev_root=root,
+            max_depth=cpub.max_depth,
+            exclude_repo_globs=cpub.exclude_repo_globs,
+            only_public=cpub.only_public,
+            repo_names=cpub.repo_names or None,
+        )
+        out_path = Path(cpub.output).expanduser()
+        write_cpub(out_path, report)
+        if machine_output:
+            sweep_reports.append(("cargo_publish_audit", report))
+        else:
+            console.print(f"[bold]cargo_publish_audit report:[/bold] {out_path}")
+            console.print(f"[bold]Rust repos found:[/bold] {report['scope']['rust_repos_found']}")
+            console.print(
+                f"[bold]Repos with errors:[/bold] {report['summary']['repos_with_errors']}"
+            )
+            console.print(
+                f"[bold]Repos with warnings:[/bold] {report['summary']['repos_with_warnings']}"
+            )
+            console.print(f"[bold]Total findings:[/bold] {report['summary']['total_findings']}")
+            if report["summary"]["repos_with_errors_list"]:
+                console.print(
+                    f"[red]Error repos:[/red]"
+                    f" {', '.join(report['summary']['repos_with_errors_list'])}"
+                )
+            if errors:
+                console.print(f"[yellow]Errors:[/yellow] {len(errors)} (see report)")
+            _print_cargo_publish_audit_table(report)
+        if report["summary"]["total_errors"] > 0:
+            exit_code = max(exit_code, 2)
+
+    # ai editor config audit sweep
+    aicfg = spec.sweeps.ai_editor_config_audit
+    if aicfg.enabled and (not wanted or "ai_editor_config_audit" in wanted):
+        from devguard.sweeps.ai_editor_config_audit import audit_ai_editor_configs
+        from devguard.sweeps.ai_editor_config_audit import write_report as write_aicfg
+
+        root = Path(aicfg.dev_root).expanduser() if aicfg.dev_root else default_dev_root()
+        report, errors = audit_ai_editor_configs(
+            dev_root=root,
+            max_depth=aicfg.max_depth,
+            exclude_repo_globs=aicfg.exclude_repo_globs,
+            only_with_configs=aicfg.only_with_configs,
+        )
+        out_path = Path(aicfg.output).expanduser()
+        write_aicfg(out_path, report)
+        if machine_output:
+            sweep_reports.append(("ai_editor_config_audit", report))
+        else:
+            console.print(f"[bold]ai_editor_config_audit report:[/bold] {out_path}")
+            console.print(
+                f"[bold]Repos with AI configs:[/bold] {report['scope']['repos_with_ai_configs']}"
+            )
+            console.print(
+                f"[bold]Repos with errors:[/bold] {report['summary']['repos_with_errors']}"
+            )
+            console.print(
+                f"[bold]Repos with warnings:[/bold] {report['summary']['repos_with_warnings']}"
+            )
+            console.print(f"[bold]Total findings:[/bold] {report['summary']['total_findings']}")
+            if report["summary"].get("tool_adoption"):
+                tools = ", ".join(f"{t}={c}" for t, c in report["summary"]["tool_adoption"])
+                console.print(f"[bold]Tool adoption:[/bold] {tools}")
+            if errors:
+                console.print(f"[yellow]Errors:[/yellow] {len(errors)} (see report)")
+            _print_ai_editor_config_table(report)
+        if report["summary"]["total_errors"] > 0:
+            exit_code = max(exit_code, 2)
+
+    # publish audit sweep (PyPI + npm)
+    puba = spec.sweeps.publish_audit
+    if puba.enabled and (not wanted or "publish_audit" in wanted):
+        from devguard.sweeps.publish_audit import audit_publish
+        from devguard.sweeps.publish_audit import write_report as write_puba
+
+        root = Path(puba.dev_root).expanduser() if puba.dev_root else default_dev_root()
+        report, errors = audit_publish(
+            dev_root=root,
+            max_depth=puba.max_depth,
+            exclude_repo_globs=puba.exclude_repo_globs,
+            ecosystems=puba.ecosystems or None,
+        )
+        out_path = Path(puba.output).expanduser()
+        write_puba(out_path, report)
+        if machine_output:
+            sweep_reports.append(("publish_audit", report))
+        else:
+            console.print(f"[bold]publish_audit report:[/bold] {out_path}")
+            console.print(f"[bold]Repos scanned:[/bold] {report['scope']['repos_scanned']}")
+            console.print(
+                f"[bold]Repos with errors:[/bold] {report['summary']['repos_with_errors']}"
+            )
+            console.print(f"[bold]Total findings:[/bold] {report['summary']['total_findings']}")
+            if errors:
+                console.print(f"[yellow]Errors:[/yellow] {len(errors)} (see report)")
+        if report["summary"]["total_errors"] > 0:
+            exit_code = max(exit_code, 2)
+
+    any_enabled = (
+        local.enabled
+        or pub.enabled
+        or spec.sweeps.local_dirty_worktree_secrets.enabled
+        or spec.sweeps.project_flaudit.enabled
+        or spec.sweeps.gitignore_audit.enabled
+        or spec.sweeps.dependency_audit.enabled
+        or spec.sweeps.ssh_key_audit.enabled
+        or spec.sweeps.cargo_publish_audit.enabled
+        or spec.sweeps.ai_editor_config_audit.enabled
+        or spec.sweeps.publish_audit.enabled
+    )
+    if not wanted and not any_enabled:
+        if not machine_output:
+            console.print("[yellow]No sweeps enabled in spec.[/yellow]")
+
+    # Emit machine-readable output to stdout
+    if machine_output and sweep_reports:
+        if format == "sarif":
+            from devguard.sarif import reports_to_sarif
+
+            sarif_doc = reports_to_sarif(sweep_reports)
+            sys.stdout.write(json.dumps(sarif_doc, indent=2) + "\n")
+        elif format == "json":
+            combined = {name: report for name, report in sweep_reports}
+            sys.stdout.write(json.dumps(combined, indent=2) + "\n")
+
+    if exit_code > 0:
+        raise typer.Exit(code=exit_code)
+
+
+def _update_env_var(env_content: str, var_name: str, value: str) -> str:
+    """Update or add an environment variable in .env content."""
+    lines = env_content.split("\n")
+    updated = False
+    new_lines = []
+
+    for line in lines:
+        if line.startswith(f"{var_name}="):
+            new_lines.append(f"{var_name}={value}")
+            updated = True
+        else:
+            new_lines.append(line)
+
+    if not updated:
+        new_lines.append(f"{var_name}={value}")
+
+    return "\n".join(new_lines) + "\n"
+
+
+@app.command()
+def doctor() -> None:
+    """Check external tool prerequisites for sweeps."""
+    import shutil
+
+    tools = [
+        (
+            "trufflehog",
+            "public_github_secrets, local_dirty_worktree_secrets",
+            "brew install trufflehog",
+        ),
+        (
+            "cargo-audit",
+            "dependency_audit (Rust repos)",
+            "cargo install cargo-audit",
+        ),
+        (
+            "npm",
+            "dependency_audit (JS repos)",
+            "install Node.js from https://nodejs.org",
+        ),
+        (
+            "pip-audit",
+            "dependency_audit (Python repos)",
+            "pip install pip-audit",
+        ),
+        (
+            "gh",
+            "public_github_secrets, ssh_key_audit (GitHub cross-ref)",
+            "brew install gh",
+        ),
+        (
+            "git",
+            "most sweeps",
+            "brew install git",
+        ),
+    ]
+
+    found = 0
+    total = len(tools)
+
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("Tool")
+    table.add_column("Status")
+    table.add_column("Used by")
+    table.add_column("Install hint")
+
+    for tool_name, used_by, hint in tools:
+        path = shutil.which(tool_name)
+        if path:
+            found += 1
+            table.add_row(tool_name, "[green]found[/green]", used_by, "")
+        else:
+            table.add_row(tool_name, "[red]missing[/red]", used_by, hint)
+
+    console.print(table)
+    console.print()
+    console.print(
+        f"{found}/{total} tools found. Missing tools will cause some sweeps to skip or fail."
+    )
+
+
+def main() -> None:
+    """Entry point for CLI."""
+    app()
+
+
+if __name__ == "__main__":
+    main()