audit.py

#!/usr/bin/env python3
"""
AI CLI Preparation - Tool audit and version management.

Modular architecture for CLI tool management with parallel collection,
snapshot-based caching, and intelligent version detection.

Usage:
    audit.py              # Render audit from snapshot
    audit.py --update     # Collect fresh versions
    audit.py --install    # Install missing tools
    audit.py --upgrade    # Upgrade outdated tools
"""

from __future__ import annotations

import argparse
import json
import os
import re
import sys
from collections import Counter
from concurrent.futures import ThreadPoolExecutor, as_completed

# Add current directory to path
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))

from cli_audit import collectors  # noqa: E402
from cli_audit.collectors import (  # noqa: E402
    collect_endoflife,
    get_github_rate_limit,
    get_github_rate_limit_help,
    get_gitlab_rate_limit,
    is_wsl,
)
from cli_audit.detection import VERSION_PROBE_TIMEOUT, audit_tool_installation, detect_multi_versions  # noqa: E402
from cli_audit.local_state import (  # noqa: E402
    LocalInstallation,
    LocalState,
    build_legacy_snapshot,
    get_local_state_path,
    load_local_state,
    write_local_state,
)
from cli_audit.logging_config import setup_logging  # noqa: E402
from cli_audit.pins import lookup_pin  # noqa: E402
from cli_audit.pins import should_skip as _pin_should_skip  # noqa: E402
from cli_audit.render import osc8, print_summary, render_table, status_icon  # noqa: E402
from cli_audit.snapshot import get_snapshot_path, load_snapshot, render_from_snapshot, write_snapshot  # noqa: E402

# Import modules
from cli_audit.tools import Tool, all_tools, filter_tools, latest_target_url, tool_homepage_url  # noqa: E402

# Split file support (Phase 2.1)
from cli_audit.upstream_cache import (  # noqa: E402
    UpstreamVersion,
    get_upstream_cache_path,
    load_upstream_cache,
    write_upstream_cache,
)

# Strip control characters from externally-sourced strings (e.g. GitHub tags)
# to prevent terminal escape sequence injection.
_CONTROL_CHAR_RE = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]")


def _sanitize(s: str) -> str:
    """Remove control characters from a string for safe terminal display."""
    return _CONTROL_CHAR_RE.sub("", s) if s else s


# Configuration from environment
OFFLINE_MODE = os.environ.get("CLI_AUDIT_OFFLINE", "0") == "1"
MAX_WORKERS = int(os.environ.get("CLI_AUDIT_MAX_WORKERS", "16"))
# (CLI_AUDIT_HINTS is gone; canned hints added no information — the row
# state and tool name already tell the user what action is available.)
COLLECT_MODE = os.environ.get("CLI_AUDIT_COLLECT", "0") == "1"
RENDER_MODE = os.environ.get("CLI_AUDIT_RENDER", "0") == "1"
JSON_MODE = os.environ.get("CLI_AUDIT_JSON", "0") == "1"
FILTER_STATUS = os.environ.get("CLI_AUDIT_FILTER_STATUS", "")  # e.g., "NOT INSTALLED,OUTDATED"
# Split file modes (Phase 2.1)
UPDATE_LOCAL_ONLY = os.environ.get("CLI_AUDIT_UPDATE_LOCAL", "0") == "1"
UPDATE_BASELINE_ONLY = os.environ.get("CLI_AUDIT_UPDATE_BASELINE", "0") == "1"
USE_SPLIT_FILES = os.environ.get("CLI_AUDIT_SPLIT_FILES", "0") == "1"

# Audit status value (named to avoid duplicating the literal across call sites)
STATUS_NOT_INSTALLED = "NOT INSTALLED"


def normalize_version(version: str) -> str:
    """Normalize version string for comparison.

    Args:
        version: Version string (e.g., "7.28.00", "v1.2.0")

    Returns:
        Normalized version string (e.g., "7.28.0", "1.2.0")
    """
    if not version:
        return version

    # Remove 'v' prefix
    version = version.lstrip("v")

    # Split into parts and remove trailing zeros from each part
    parts = version.split(".")
    normalized_parts = []

    for i, part in enumerate(parts):
        # For numeric parts, strip trailing zeros but keep at least one digit
        if part.isdigit():
            # Keep at least one zero if the part is all zeros
            normalized = part.lstrip("0") or "0"
            normalized_parts.append(normalized)
        else:
            # Non-numeric parts (e.g., "rc1", "beta") - keep as is
            normalized_parts.append(part)

    return ".".join(normalized_parts)


def compute_status(installed: str, latest: str) -> str:
    """Determine audit status from installed vs latest using DIRECTIONAL version
    comparison.

    ``installed >= latest`` is UP-TO-DATE -- a tool that is *ahead* of the known
    latest (e.g. ahead of a stale committed baseline) needs no upgrade and must
    not be reported as OUTDATED. Only ``installed < latest`` is OUTDATED. Missing
    installed -> NOT INSTALLED; missing latest -> UNKNOWN.
    """
    if not installed:
        return STATUS_NOT_INSTALLED
    if not latest:
        return "UNKNOWN"
    from cli_audit.upgrade import compare_versions

    if compare_versions(normalize_version(installed), normalize_version(latest)) < 0:
        return "OUTDATED"
    return "UP-TO-DATE"


def collect_latest_version(tool: Tool, offline_cache: dict[str, tuple[str, str]] | None = None) -> tuple[str, str]:
    """Collect latest version for a tool.

    Args:
        tool: Tool definition
        offline_cache: Optional offline cache for fallback

    Returns:
        Tuple of (tag, version_number)
    """
    if tool.source_kind == "skip":
        return ("", "")

    try:
        if tool.source_kind == "gh" and len(tool.source_args) >= 2:
            owner, repo = tool.source_args[0], tool.source_args[1]
            return collectors.collect_github(owner, repo, offline_cache)
        elif tool.source_kind == "gitlab" and len(tool.source_args) >= 2:
            group, project = tool.source_args[0], tool.source_args[1]
            return collectors.collect_gitlab(group, project, offline_cache)
        elif tool.source_kind == "pypi" and tool.source_args:
            package = tool.source_args[0]
            return collectors.collect_pypi(package, offline_cache)
        elif tool.source_kind == "npm" and tool.source_args:
            package = tool.source_args[0]
            return collectors.collect_npm(package, offline_cache)
        elif tool.source_kind == "crates" and tool.source_args:
            crate = tool.source_args[0]
            return collectors.collect_crates(crate, offline_cache)
        elif tool.source_kind == "gnu" and len(tool.source_args) >= 2:
            tool_name, ftp_url = tool.source_args[0], tool.source_args[1]
            return collectors.collect_gnu(tool_name, ftp_url, offline_cache)
        else:
            return ("", "")
    except Exception as e:
        if os.environ.get("CLI_AUDIT_DEBUG"):
            print(f"# DEBUG: Collection failed for {tool.name}: {e}", file=sys.stderr)
        return ("", "")


def audit_multi_version_tool(
    tool_name: str,
    catalog_data: dict,
    mv_config: dict,
) -> list[dict[str, str]]:
    """Audit a multi-version runtime tool.

    For tools like PHP, Python, Node.js that support multiple concurrent versions,
    this generates separate audit entries for each supported version cycle.

    Args:
        tool_name: Base tool name (e.g., "php", "python")
        catalog_data: Full catalog entry data
        mv_config: Multi-version configuration from catalog

    Returns:
        List of audit result dictionaries, one per version cycle
    """
    product = mv_config.get("product", tool_name)
    max_versions = mv_config.get("max_versions", 4)

    # Fetch supported versions from endoflife.date
    try:
        supported = collect_endoflife(product, max_versions=max_versions)
    except Exception:
        return []

    if not supported:
        return []

    # Detect installed versions
    detected = detect_multi_versions(tool_name, mv_config, supported)

    results = []
    for version_info in detected:
        cycle = version_info.get("cycle", "")
        latest = version_info.get("latest_upstream", "")
        installed = version_info.get("installed")
        path = version_info.get("path", "")
        method = version_info.get("install_method", "")
        status_lifecycle = version_info.get("status", "unknown")

        # Determine audit status (directional: installed >= latest is current)
        status = compute_status(installed, latest)

        # Build versioned tool name
        versioned_name = f"{tool_name}@{cycle}"

        # Classification reason
        if method:
            classification_reason = f"Detected via path analysis: {method}"
        else:
            classification_reason = "No installation detected"

        # Hint comes from catalog when provided (empty for generic runtimes —
        # the tool name + state already tell the user what to do, and a
        # canned "check your package manager" line adds no value).
        hint = catalog_data.get("hint", "")

        results.append(
            {
                "tool": versioned_name,
                "category": catalog_data.get("category", tool_name),
                "installed": installed or "",
                "installed_method": method,
                "installed_version": installed or "",
                "installed_path_selected": path,
                "classification_reason_selected": classification_reason,
                "latest_upstream": latest,
                "latest_version": latest,
                "upstream_method": "endoflife",
                "status": status,
                "tool_url": catalog_data.get("homepage", ""),
                "latest_url": f"https://endoflife.date/{product}",
                "hint": hint,
                # Extra fields for multi-version
                "is_multi_version": True,
                "base_tool": tool_name,
                "version_cycle": cycle,
                "lifecycle_status": status_lifecycle,  # active, security, eol
            }
        )

    return results


def _apply_probe_timeout_fallback(
    tool_name: str,
    version_num: str,
    version_line: str,
    path: str,
    install_method: str,
) -> tuple[str, str, str, str, bool]:
    """Fall back to the last known local_state version when the probe timed out.

    A timeout means the binary exists but answered too slowly (slow binaries
    like opengrep need ~2.5s and can exceed the probe timeout under parallel
    collection load) — reporting it as not installed would be wrong.

    Returns:
        Tuple of (version_num, version_line, path, install_method, from_cache).
        from_cache is True only when the cached version was substituted; callers
        must surface that in classification_reason so the fallback is not silent.
    """
    if version_line != VERSION_PROBE_TIMEOUT:
        return version_num, version_line, path, install_method, False

    prev = load_local_state().tools.get(tool_name)
    if prev and prev.installed_version:
        version = prev.installed_version
        line = f"{tool_name} {version} (cached; version probe timed out)"
        return version, line, path or prev.installed_path, install_method or prev.installed_method, True

    # No cached version to fall back to: keep prior "no version" behavior.
    return "", "", path, install_method, False


def audit_tool(tool: Tool, offline_cache: dict[str, tuple[str, str]] | None = None) -> dict[str, str]:
    """Audit a single tool.

    Args:
        tool: Tool definition
        offline_cache: Optional offline cache for latest versions

    Returns:
        Dictionary with audit results
    """
    # Load catalog metadata for version detection
    from cli_audit.catalog import ToolCatalog

    catalog = ToolCatalog()
    version_flag = None
    version_command = None
    if catalog.has_tool(tool.name):
        catalog_data = catalog.get_raw_data(tool.name)
        version_flag = catalog_data.get("version_flag")
        version_command = catalog_data.get("version_command")

    # Detect installed version
    deep_scan = tool.name in {"node", "python", "semgrep", "pre-commit", "bandit", "black", "flake8", "isort"}
    version_num, version_line, path, install_method = audit_tool_installation(
        tool.name, tool.candidates, deep=deep_scan, version_flag=version_flag, version_command=version_command
    )
    version_num, version_line, path, install_method, from_cache = _apply_probe_timeout_fallback(
        tool.name, version_num, version_line, path, install_method
    )

    installed = version_num if version_num else (version_line if version_line != "X" else "")

    # Collect latest version
    latest_tag, latest_num = collect_latest_version(tool, offline_cache)
    latest = latest_num if latest_num else latest_tag

    # Determine status
    if version_line and version_line.startswith("CONFLICT:"):
        status = "CONFLICT"
    elif version_line == "X" or not installed:
        status = STATUS_NOT_INSTALLED
    elif version_num and latest_num:
        # Directional: installed >= latest is UP-TO-DATE (also handles being
        # ahead of a stale baseline and "7.28.00" vs "7.28.0").
        status = compute_status(version_num, latest_num)
    elif version_num and not latest_num:
        status = "UNKNOWN"
    else:
        status = "UNKNOWN"

    # URLs
    tool_url = tool_homepage_url(tool)
    latest_url = latest_target_url(tool, latest_tag, latest_num)

    # Generate classification reason
    if from_cache:
        classification_reason = "Cached version (probe timed out); last known method: " + (install_method or "unknown")
    elif install_method:
        classification_reason = f"Detected via path analysis: {install_method}"
    else:
        classification_reason = "No installation detected"

    return {
        "tool": tool.name,
        "category": tool.category,
        "installed": installed,
        "installed_method": install_method,
        "installed_version": version_num,
        "installed_path_selected": path,
        "classification_reason_selected": classification_reason,
        "latest_upstream": latest,
        "latest_version": latest_num,
        "upstream_method": tool.source_kind,
        "status": status,
        "tool_url": tool_url,
        "latest_url": latest_url,
        "hint": tool.hint if status in (STATUS_NOT_INSTALLED, "OUTDATED", "CONFLICT") else "",
    }


def cmd_audit(args: argparse.Namespace) -> int:
    """Render audit from snapshot (fast, no network)."""
    # If COLLECT_MODE is enabled with specific tools, do fresh collection
    if COLLECT_MODE and args.tools:
        # Fresh collection for specific tools
        tools_list = filter_tools(args.tools)

        if not tools_list:
            if not JSON_MODE:
                print(f"# No matching tools found for: {', '.join(args.tools)}", file=sys.stderr)
            return 0

        if not JSON_MODE:
            print(f"# Collecting fresh data for {len(tools_list)} tool(s)...", file=sys.stderr)

        # Separate multi-version tools from regular tools
        from cli_audit.catalog import ToolCatalog

        catalog = ToolCatalog()
        regular_tools = []
        mv_tools = {}  # tool_name -> (catalog_data, mv_config)
        for tool in tools_list:
            if catalog.has_tool(tool.name):
                catalog_data = catalog.get_raw_data(tool.name)
                mv_config = catalog_data.get("multi_version", {})
                if mv_config.get("enabled"):
                    mv_tools[tool.name] = (catalog_data, mv_config)
                    continue
            regular_tools.append(tool)

        # Collect regular tools in parallel
        results = []
        if regular_tools:
            with ThreadPoolExecutor(max_workers=min(MAX_WORKERS, len(regular_tools))) as executor:
                future_to_tool = {executor.submit(audit_tool, tool, None): tool for tool in regular_tools}
                for future in as_completed(future_to_tool):
                    try:
                        result = future.result()
                        results.append(result)
                    except Exception:
                        pass

        # Collect multi-version tools
        for tool_name, (catalog_data, mv_config) in mv_tools.items():
            mv_results = audit_multi_version_tool(tool_name, catalog_data, mv_config)
            results.extend(mv_results)

        tools = results

        # If there's an existing snapshot and we're in merge mode, update it
        if os.environ.get("CLI_AUDIT_MERGE", "0") == "1":
            snapshot = load_snapshot()
            if snapshot.get("tools"):
                # Merge results into existing snapshot
                tool_names = {t.get("tool") for t in results}
                existing_tools = [t for t in snapshot.get("tools", []) if t.get("tool") not in tool_names]
                merged_tools = existing_tools + results

                # Write merged snapshot
                write_snapshot(merged_tools, offline=OFFLINE_MODE)

                if not JSON_MODE:
                    print(f"# Updated snapshot with {len(results)} tool(s)", file=sys.stderr)
    else:
        # Load snapshot
        snapshot = load_snapshot()
        if not snapshot.get("tools"):
            if not JSON_MODE:
                print("# No snapshot found - run 'make update' first", file=sys.stderr)
            return 1

        # Filter tools if specified
        selected = set(args.tools) if args.tools else None
        tools = render_from_snapshot(snapshot, selected)

    # Apply status filter if specified
    if FILTER_STATUS:
        allowed_statuses = {s.strip().upper() for s in FILTER_STATUS.split(",")}
        tools = [t for t in tools if t.get("status", "").upper() in allowed_statuses]

    # JSON output mode
    if JSON_MODE:
        # Enrich tools with additional fields for guide.sh compatibility
        enriched_tools = []
        for tool in tools:
            enriched = tool.copy()
            status = tool.get("status", "UNKNOWN")
            installed = tool.get("installed", "")
            install_method = tool.get("installed_method", "")

            # Add state_icon field
            enriched["state_icon"] = status_icon(status, installed)

            # Add is_up_to_date boolean field
            enriched["is_up_to_date"] = status == "UP-TO-DATE"  # type: ignore[assignment]

            # Add path and classification fields (for backward compatibility with old snapshots)
            if "installed_path_selected" not in enriched:
                enriched["installed_path_selected"] = ""
            if "classification_reason_selected" not in enriched:
                if install_method:
                    enriched["classification_reason_selected"] = f"Detected via path analysis: {install_method}"
                else:
                    enriched["classification_reason_selected"] = "No installation detected"

            enriched_tools.append(enriched)

        # Output JSON array to stdout
        print(json.dumps(enriched_tools, indent=2))
        return 0

    # Table output mode
    print("=" * 80, file=sys.stderr)
    print("Audit Mode", file=sys.stderr)
    print("=" * 80, file=sys.stderr)

    # Get metadata for friendly message
    meta = snapshot.get("__meta__", {})
    count = meta.get("count", len(tools))
    created_at = meta.get("created_at", "cached")

    # Calculate age
    if created_at and created_at != "cached":
        try:
            from datetime import datetime

            created_dt = datetime.fromisoformat(created_at)
            now = datetime.now(created_dt.tzinfo)
            age_seconds = (now - created_dt).total_seconds()
            if age_seconds < 60:
                age_str = "just now"
            elif age_seconds < 3600:
                age_str = f"{int(age_seconds / 60)}m ago"
            elif age_seconds < 86400:
                age_str = f"{int(age_seconds / 3600)}h ago"
            else:
                age_str = f"{int(age_seconds / 86400)}d ago"
        except Exception:
            age_str = "cached"
    else:
        age_str = "cached"

    print(f"# Auditing {count} development tools from snapshot ({age_str})...", file=sys.stderr)
    print("", file=sys.stderr)

    # Render table
    render_table(tools)

    # Print summary
    print_summary(snapshot, tools)

    # Suggest package manager upgrades
    from cli_audit.catalog import suggest_package_manager_upgrades

    suggest_package_manager_upgrades()

    return 0


def cmd_update(args: argparse.Namespace) -> int:
    """Collect fresh version data from upstream."""
    # Reset terminal state at start (in case previous run left corruption)
    print("\033[0m", end="", file=sys.stderr, flush=True)

    print("=" * 80, file=sys.stderr)
    print("Update Mode", file=sys.stderr)
    print("=" * 80, file=sys.stderr)

    # Show platform info
    if is_wsl():
        print("ℹ️  Platform: WSL (Windows Subsystem for Linux)", file=sys.stderr)

    # Get tools to audit
    tools_list = filter_tools(args.tools) if args.tools else all_tools()
    total = len(tools_list)

    # Show GitHub rate limit before starting
    rate_limit = get_github_rate_limit()
    if rate_limit:
        remaining = rate_limit.get("remaining", 0)
        limit = rate_limit.get("limit", 0)
        authenticated = rate_limit.get("authenticated", False)
        token_source = rate_limit.get("token_source", "")

        # Build status message
        auth_info = ""
        if authenticated:
            if token_source == "gh_cli":
                auth_info = " (via gh CLI)"
            elif token_source == "GITHUB_TOKEN":
                auth_info = " (via GITHUB_TOKEN)"

        if remaining < limit * 0.2:  # Warn if less than 20% remaining
            print(f"⚠️  GitHub rate limit: {remaining}/{limit} remaining{auth_info}", file=sys.stderr, flush=True)
            if not authenticated:
                print(get_github_rate_limit_help(), file=sys.stderr, flush=True)
        elif not authenticated and limit == 60:
            # Unauthenticated with default limit - suggest authentication
            print(f"ℹ️  GitHub rate limit: {remaining}/{limit} remaining (unauthenticated)", file=sys.stderr, flush=True)
            print(get_github_rate_limit_help(), file=sys.stderr, flush=True)
        else:
            print(f"✓ GitHub rate limit: {remaining}/{limit} remaining{auth_info}", file=sys.stderr, flush=True)

    # Show GitLab rate limit if we have GitLab tools
    gitlab_rate = get_gitlab_rate_limit()
    if gitlab_rate and "remaining" in gitlab_rate and "limit" in gitlab_rate:
        gl_remaining = gitlab_rate["remaining"]
        gl_limit = gitlab_rate["limit"]
        gl_authenticated = gitlab_rate.get("authenticated", False)
        gl_token_source = gitlab_rate.get("token_source", "")
        gl_host = gitlab_rate.get("host", "gitlab.com")

        gl_auth_info = ""
        if gl_authenticated:
            if gl_token_source == "glab_cli":
                gl_auth_info = " (via glab CLI)"
            else:
                gl_auth_info = " (via GITLAB_TOKEN)"

        if gl_remaining < gl_limit * 0.2:
            print(
                f"⚠️  GitLab rate limit ({gl_host}): {gl_remaining}/{gl_limit} remaining{gl_auth_info}",
                file=sys.stderr,
                flush=True,
            )
        else:
            print(
                f"✓ GitLab rate limit ({gl_host}): {gl_remaining}/{gl_limit} remaining{gl_auth_info}",
                file=sys.stderr,
                flush=True,
            )

    print(f"# Collecting fresh data for {total} tools...", file=sys.stderr)
    est_time = int((total / MAX_WORKERS) * 3 * 1.5)
    print(f"# Estimated time: ~{est_time}s (timeout=3s per tool, {MAX_WORKERS} workers)", file=sys.stderr)
    print("", file=sys.stderr)

    # Identify multi-version tools
    from cli_audit.catalog import ToolCatalog

    catalog = ToolCatalog()
    multi_version_tools = {}  # tool_name -> (catalog_data, mv_config)
    regular_tools = []

    for tool in tools_list:
        if catalog.has_tool(tool.name):
            catalog_data = catalog.get_raw_data(tool.name)
            mv_config = catalog_data.get("multi_version", {})
            if mv_config.get("enabled"):
                multi_version_tools[tool.name] = (catalog_data, mv_config)
                continue
        regular_tools.append(tool)

    # Group regular tools by category for organized output
    from cli_audit.render import CATEGORY_DESC, CATEGORY_ICON, CATEGORY_ORDER

    categorized: dict[str, list] = {}
    for tool in regular_tools:
        cat = tool.category or "general"
        if cat not in categorized:
            categorized[cat] = []
        categorized[cat].append(tool)
    sorted_cats = sorted(categorized.keys(), key=lambda c: CATEGORY_ORDER.get(c, 99))

    # Total includes both regular tools and multi-version entries
    total = len(regular_tools) + len(multi_version_tools)

    # Parallel audit with progress tracking
    # All tools submitted to a single executor for maximum parallelism
    # (no per-category sequential bottleneck)
    results = []
    completed = 0

    # ANSI colors for all platforms
    GREEN = "\033[32m"
    BOLD_GREEN = "\033[1;32m"
    YELLOW = "\033[33m"
    BLUE = "\033[34m"
    RESET = "\033[0m"

    try:
        if regular_tools:
            with ThreadPoolExecutor(max_workers=min(MAX_WORKERS, len(regular_tools))) as executor:
                future_to_tool = {executor.submit(audit_tool, tool, None): tool for tool in regular_tools}

                try:
                    for future in as_completed(future_to_tool):
                        tool = future_to_tool[future]
                        try:
                            result = future.result()
                            results.append(result)
                            completed += 1

                            # Progress
                            inst = result.get("installed", "")
                            latest = result.get("latest_upstream", "")
                            status = result.get("status", "")
                            cat = tool.category or "general"

                            # Color the installed version based on status
                            if status == "UP-TO-DATE":
                                inst_color = GREEN
                                latest_color = GREEN
                                op = "==="
                            elif status == "OUTDATED":
                                inst_color = YELLOW
                                latest_color = BOLD_GREEN
                                op = "!=="
                            elif status == "CONFLICT":
                                inst_color = YELLOW
                                latest_color = BOLD_GREEN
                                op = "⚠️"
                            else:  # NOT INSTALLED, UNKNOWN
                                inst_color = BLUE
                                latest_color = BLUE
                                op = "?"

                            inst_display = _sanitize(inst) if inst else "n/a"
                            latest_display = _sanitize(latest) if latest else "n/a"

                            # Add pinned/skip markers from user pins file
                            pin_val = lookup_pin(tool.name)
                            markers = []
                            if pin_val:
                                markers.append("NEVER" if pin_val == "never" else f"PIN:{pin_val}")
                            if _pin_should_skip(tool.name, latest):
                                markers.append("SKIP")

                            marker_str = f" [{' '.join(markers)}]" if markers else ""
                            inst_fmt = f"{inst_color}{inst_display}{RESET}"
                            latest_fmt = f"{latest_color}{latest_display}{RESET}"
                            # Hyperlink the latest version to its release/page URL
                            # (osc8 self-disables when CLI_AUDIT_LINKS=0 or no URL)
                            latest_link = result.get("latest_url", "")
                            if latest_link and latest_display != "n/a":
                                latest_fmt = osc8(latest_link, latest_fmt)
                            msg = (
                                f"# [{completed}/{total}] [{cat}] {tool.name} "
                                f"(installed: {inst_fmt} {op} latest: {latest_fmt}){marker_str}"
                            )

                            print(msg, file=sys.stderr, flush=True)

                        except Exception as e:
                            completed += 1
                            print(f"# [{completed}/{total}] {tool.name} (failed: {e})", file=sys.stderr, flush=True)

                            # Add failure entry
                            results.append(
                                {
                                    "tool": tool.name,
                                    "category": tool.category,
                                    "installed": "",
                                    "installed_method": "",
                                    "installed_version": "",
                                    "installed_path_selected": "",
                                    "classification_reason_selected": "Detection failed",
                                    "latest_upstream": "",
                                    "latest_version": "",
                                    "upstream_method": tool.source_kind,
                                    "status": "UNKNOWN",
                                    "tool_url": tool_homepage_url(tool),
                                    "latest_url": "",
                                    "hint": "",
                                }
                            )
                except KeyboardInterrupt:
                    executor.shutdown(wait=False, cancel_futures=True)
                    raise

        # Print grouped summary (single-pass counting)
        status_counts: dict[str, Counter] = {cat: Counter() for cat in sorted_cats}
        for r in results:
            cat = r.get("category", "general")
            if cat in status_counts:
                status_counts[cat][r.get("status")] += 1

        print("\n# Summary by category:", file=sys.stderr)
        for category in sorted_cats:
            icon = CATEGORY_ICON.get(category, "📦")
            desc = CATEGORY_DESC.get(category, category)
            counts = status_counts[category]
            parts = []
            if counts["UP-TO-DATE"]:
                parts.append(f"{GREEN}{counts['UP-TO-DATE']} current{RESET}")
            if counts["OUTDATED"]:
                parts.append(f"{YELLOW}{counts['OUTDATED']} outdated{RESET}")
            if counts[STATUS_NOT_INSTALLED]:
                parts.append(f"{BLUE}{counts['NOT INSTALLED']} missing{RESET}")
            if counts["CONFLICT"]:
                parts.append(f"{YELLOW}{counts['CONFLICT']} conflict{RESET}")
            if counts["UNKNOWN"]:
                parts.append(f"{BLUE}{counts['UNKNOWN']} unknown{RESET}")
            summary = ", ".join(parts) if parts else "–"
            print(f"#   {icon} {desc}: {summary}", file=sys.stderr)

        # Audit multi-version runtimes
        if multi_version_tools:
            print(f"\n# 🔄 Multi-version runtimes ({len(multi_version_tools)} runtimes)", file=sys.stderr)

            for tool_name, (catalog_data, mv_config) in multi_version_tools.items():
                completed += 1
                print(f"# [{completed}/{total}] {tool_name} (multi-version)...", file=sys.stderr, flush=True)

                mv_results = audit_multi_version_tool(tool_name, catalog_data, mv_config)

                for mv_result in mv_results:
                    results.append(mv_result)

                    # Progress output for each version
                    versioned_name = mv_result.get("tool", "")
                    inst = mv_result.get("installed", "")
                    latest = mv_result.get("latest_upstream", "")
                    status = mv_result.get("status", "")

                    if status == "UP-TO-DATE":
                        inst_color = GREEN
                        op = "==="
                    elif status == "OUTDATED":
                        inst_color = YELLOW
                        op = "!=="
                    else:
                        inst_color = BLUE
                        op = "?"

                    inst_display = _sanitize(inst) if inst else "n/a"
                    latest_display = _sanitize(latest) if latest else "n/a"
                    inst_fmt = f"{inst_color}{inst_display}{RESET}"
                    latest_fmt = f"{BOLD_GREEN}{latest_display}{RESET}"
                    print(f"#     → {versioned_name}: {inst_fmt} {op} {latest_fmt}", file=sys.stderr, flush=True)

    except KeyboardInterrupt:
        print("\n\n✗ Interrupted", file=sys.stderr)
        # Reset terminal state before exiting
        print("\033[0m", end="", file=sys.stderr, flush=True)
        sys.stderr.flush()
        # Exit immediately to avoid shutdown deadlocks
        import os

        os._exit(130)

    # Write snapshot
    try:
        meta = write_snapshot(results, offline=OFFLINE_MODE)
        print("", file=sys.stderr)
        print(f"✓ Snapshot updated: {get_snapshot_path()}", file=sys.stderr)
        print(f"✓ Collected {meta['count']} tools", file=sys.stderr)

        # Print the same Readiness summary the render (make upgrade) shows, so
        # make update and make upgrade report identical totals. The per-category
        # summary above omits multi-version cycles; this grand total includes them.
        print_summary({"__meta__": {"count": len(results), "offline": OFFLINE_MODE}}, results)

        # Report GitHub rate limit status
        rate_limit = get_github_rate_limit()
        if rate_limit:
            remaining = rate_limit.get("remaining", 0)
            limit = rate_limit.get("limit", 0)
            authenticated = rate_limit.get("authenticated", False)
            token_source = rate_limit.get("token_source", "")

            auth_info = ""
            if authenticated:
                if token_source == "gh_cli":
                    auth_info = " (via gh CLI)"
                elif token_source == "GITHUB_TOKEN":
                    auth_info = " (via GITHUB_TOKEN)"

            if remaining < limit * 0.2:
                print(f"⚠️  GitHub rate limit: {remaining}/{limit} remaining{auth_info}", file=sys.stderr, flush=True)
            else:
                print(f"✓ GitHub rate limit: {remaining}/{limit} remaining{auth_info}", file=sys.stderr, flush=True)

        # Suggest package manager upgrades
        from cli_audit.catalog import suggest_package_manager_upgrades

        suggest_package_manager_upgrades()

        # Reset terminal state (reset colors + ensure echo mode)
        # \033[0m = reset colors/attributes
        # Flush to ensure it's sent before returning
        print("\033[0m", end="", file=sys.stderr, flush=True)
        sys.stderr.flush()
        return 0
    except Exception as e:
        print(f"✗ Failed to write snapshot: {e}", file=sys.stderr)
        # Reset terminal state even on error
        print("\033[0m", end="", file=sys.stderr, flush=True)
        sys.stderr.flush()
        return 1


def cmd_update_local(args: argparse.Namespace) -> int:
    """Update only local installation state (fast, no network)."""
    # Check if we're in merge mode (updating specific tools only)
    merge_mode = os.environ.get("CLI_AUDIT_MERGE", "0") == "1"
    specific_tools = bool(args.tools)

    # Only show header if not in quiet merge mode
    if not (merge_mode and specific_tools):
        print("=" * 80, file=sys.stderr)
        print("Update Local State", file=sys.stderr)
        print("=" * 80, file=sys.stderr)

    # Get tools to audit
    tools_list = filter_tools(args.tools) if args.tools else all_tools()
    total = len(tools_list)

    if not (merge_mode and specific_tools):
        print(f"# Detecting local installations for {total} tools...", file=sys.stderr)

    # Load existing upstream cache for status determination
    upstream_cache = load_upstream_cache()

    # In merge mode with specific tools, load existing local state first
    if merge_mode and specific_tools:
        local_state = load_local_state()
    else:
        local_state = LocalState()
    completed = 0

    with ThreadPoolExecutor(max_workers=min(MAX_WORKERS, total)) as executor:
        future_to_tool = {}
        for tool in tools_list:
            # Submit only local detection (no upstream collection)
            future = executor.submit(_detect_local_only, tool)
            future_to_tool[future] = tool

        for future in as_completed(future_to_tool):
            tool = future_to_tool[future]
            try:
                installation = future.result()
                # Determine status using cached upstream
                cached = upstream_cache.versions.get(tool.name)
                if cached and installation.installed_version:
                    installation.status = compute_status(installation.installed_version, cached.latest_version)
                elif not installation.installed_version:
                    installation.status = STATUS_NOT_INSTALLED
                else:
                    installation.status = "UNKNOWN"

                local_state.tools[tool.name] = installation
                completed += 1
                print(
                    f"# [{completed}/{total}] {tool.name}: {installation.installed_version or 'not installed'}",
                    file=sys.stderr,
                )
            except Exception as e:
                completed += 1
                print(f"# [{completed}/{total}] {tool.name}: failed ({e})", file=sys.stderr)

    # Write local state
    write_local_state(local_state, offline=OFFLINE_MODE)

    if not (merge_mode and specific_tools):
        print("", file=sys.stderr)
        print(f"✓ Local state updated: {get_local_state_path()}", file=sys.stderr)
        print(f"✓ Detected {len(local_state.tools)} tools", file=sys.stderr)

    # Update legacy snapshot for backward compatibility
    if merge_mode and specific_tools:
        # In merge mode, load existing snapshot and merge in updated tools
        existing_snapshot = load_snapshot()
        existing_tools = existing_snapshot.get("tools", [])

        # Build dict of existing tools keyed by name
        tools_by_name = {t.get("tool"): t for t in existing_tools}

        # Get updated tool data for the specific tools we just detected
        updated_tools = build_legacy_snapshot(upstream_cache, local_state).get("tools", [])
        tools_to_update = {tool.name for tool in tools_list}
        updated_tool_names = {t.get("tool") for t in updated_tools if t.get("tool") in tools_to_update}

        # Merge: update only the tools we re-detected
        for updated_tool in updated_tools:
            tool_name = updated_tool.get("tool")
            if tool_name in updated_tool_names:
                tools_by_name[tool_name] = updated_tool

        # Multi-version tools (python@3.14, node@22, php@8.3, …) have one
        # snapshot entry per cycle. build_legacy_snapshot/merge_for_display
        # only emits the base-tool key, so without this block the cycle
        # entries would stay stale after an upgrade — masking successful
        # installs as "version unchanged" in the guide.
        try:
            from cli_audit.catalog import ToolCatalog

            _catalog = ToolCatalog()
        except Exception:
            _catalog = None
        if _catalog is not None:
            for tool in tools_list:
                if not _catalog.has_tool(tool.name):
                    continue
                catalog_data = _catalog.get_raw_data(tool.name)
                mv_config = catalog_data.get("multi_version", {})
                if not mv_config.get("enabled"):
                    continue
                # Reuse supported-cycle metadata from existing snapshot so this
                # fast-path stays network-free. First full audit populates it;
                # subsequent refreshes just re-detect local installs.
                supported: list[dict] = []
                for t in existing_tools:
                    if t.get("base_tool") == tool.name and t.get("version_cycle"):
                        supported.append(
                            {
                                "cycle": t["version_cycle"],
                                "latest": t.get("latest_upstream", ""),
                                "status": t.get("lifecycle_status", "unknown"),
                                "eol": None,
                                "support": None,
                                "release_date": None,
                                "lts": False,
                            }
                        )
                if not supported:
                    continue
                detected = detect_multi_versions(tool.name, mv_config, supported)
                for info in detected:
                    cycle = str(info.get("cycle", ""))
                    if not cycle:
                        continue
                    installed_v = info.get("installed")
                    latest_v = info.get("latest_upstream", "")
                    if installed_v and installed_v == latest_v:
                        status_v = "UP-TO-DATE"
                    elif installed_v:
                        status_v = "OUTDATED"
                    else:
                        status_v = STATUS_NOT_INSTALLED
                    method = info.get("install_method")
                    versioned = f"{tool.name}@{cycle}"
                    entry = dict(tools_by_name.get(versioned, {}))
                    entry.update(
                        {
                            "tool": versioned,
                            "category": catalog_data.get("category", tool.name),
                            "installed": installed_v or "",
                            "installed_method": method,
                            "installed_version": installed_v or "",
                            "installed_path_selected": info.get("path"),
                            "classification_reason_selected": (
                                f"Detected via path analysis: {method}" if method else "No installation detected"
                            ),
                            "latest_upstream": latest_v,
                            "latest_version": latest_v,
                            "status": status_v,
                            "is_multi_version": True,
                            "base_tool": tool.name,
                            "version_cycle": cycle,
                            "lifecycle_status": info.get("status", "unknown"),
                        }
                    )
                    # Hint stays empty for generic multi-version runtimes;
                    # the tool name + state already tell the user what to do.
                    entry["hint"] = ""
                    tools_by_name[versioned] = entry

        # Write merged snapshot
        merged_tools = list(tools_by_name.values())
        write_snapshot(merged_tools, offline=OFFLINE_MODE)
    else:
        # Full update: refresh the snapshot's installed_version + status from the
        # fresh local detection, but PRESERVE each tool's existing latest_version.
        # A network-free refresh must NOT clobber the upstream "latest" that
        # `make update` collected (the committed baseline is older) -- otherwise
        # make-update and make-upgrade disagree and the guide shows a target that
        # is lower than the installed version.
        existing = load_snapshot().get("tools", [])
        if existing:
            for entry in existing:
                name = entry.get("tool", "")
                if "@" in name:
                    continue  # multi-version cycle: no per-cycle local-only data
                inst = local_state.tools.get(name)
                if inst is None:
                    continue
                latest = entry.get("latest_version") or ""
                entry["installed"] = inst.installed_version or ""
                entry["installed_version"] = inst.installed_version or ""
                entry["installed_method"] = inst.installed_method or ""
                entry["installed_path_selected"] = inst.installed_path or ""
                entry["status"] = compute_status(inst.installed_version or "", latest)
            write_snapshot(existing, offline=OFFLINE_MODE)
            print(f"✓ Legacy snapshot refreshed (installed state): {get_snapshot_path()}", file=sys.stderr)
        else:
            # No snapshot yet -- build one from the upstream baseline.
            legacy_snapshot = build_legacy_snapshot(upstream_cache, local_state)
            write_snapshot(legacy_snapshot.get("tools", []), offline=OFFLINE_MODE)
            print(f"✓ Legacy snapshot updated: {get_snapshot_path()}", file=sys.stderr)

    return 0


def cmd_update_baseline(args: argparse.Namespace) -> int:
    """Update only upstream baseline cache (network required)."""
    print("=" * 80, file=sys.stderr)
    print("Update Upstream Baseline", file=sys.stderr)
    print("=" * 80, file=sys.stderr)

    # Get tools to audit
    tools_list = filter_tools(args.tools) if args.tools else all_tools()
    total = len(tools_list)

    # Show GitHub rate limit
    rate_limit = get_github_rate_limit()
    if rate_limit:
        remaining = rate_limit.get("remaining", 0)
        limit = rate_limit.get("limit", 0)
        authenticated = rate_limit.get("authenticated", False)
        token_source = rate_limit.get("token_source", "")

        auth_info = ""
        if authenticated:
            if token_source == "gh_cli":
                auth_info = " (via gh CLI)"
            elif token_source == "GITHUB_TOKEN":
                auth_info = " (via GITHUB_TOKEN)"

        if not authenticated and limit == 60:
            print(f"ℹ️  GitHub rate limit: {remaining}/{limit} remaining (unauthenticated)", file=sys.stderr, flush=True)
            print(get_github_rate_limit_help(), file=sys.stderr, flush=True)
        else:
            print(f"✓ GitHub rate limit: {remaining}/{limit} remaining{auth_info}", file=sys.stderr, flush=True)

    print(f"# Collecting upstream versions for {total} tools...", file=sys.stderr)

    # Collect upstream versions only. Merge into the existing baseline so a
    # tool-scoped run (or a transient collection failure) never drops the
    # entries that were not collected this run (issue #125).
    upstream_cache = load_upstream_cache()
    completed = 0
    collected = 0

    with ThreadPoolExecutor(max_workers=min(MAX_WORKERS, total)) as executor:
        future_to_tool = {}
        for tool in tools_list:
            future = executor.submit(collect_latest_version, tool, None)
            future_to_tool[future] = tool

        for future in as_completed(future_to_tool):
            tool = future_to_tool[future]
            try:
                latest_tag, latest_num = future.result()
                version = UpstreamVersion(
                    latest_tag=latest_tag,
                    latest_version=latest_num,
                    latest_url=latest_target_url(tool, latest_tag, latest_num),
                    tool_url=tool_homepage_url(tool),
                    upstream_method=tool.source_kind,
                )
                upstream_cache.versions[tool.name] = version
                completed += 1
                collected += 1

                display = latest_num or latest_tag or "n/a"
                print(f"# [{completed}/{total}] {tool.name}: {display}", file=sys.stderr)
            except Exception as e:
                completed += 1
                print(f"# [{completed}/{total}] {tool.name}: failed ({e})", file=sys.stderr)

    # Write upstream cache
    write_upstream_cache(upstream_cache)
    print("", file=sys.stderr)
    print(f"✓ Upstream baseline updated: {get_upstream_cache_path()}", file=sys.stderr)
    print(f"✓ Collected {collected}/{total} versions", file=sys.stderr)

    # Report rate limit
    rate_limit = get_github_rate_limit()
    if rate_limit:
        remaining = rate_limit.get("remaining", 0)
        limit = rate_limit.get("limit", 0)
        authenticated = rate_limit.get("authenticated", False)
        token_source = rate_limit.get("token_source", "")

        auth_info = ""
        if authenticated:
            if token_source == "gh_cli":
                auth_info = " (via gh CLI)"
            elif token_source == "GITHUB_TOKEN":
                auth_info = " (via GITHUB_TOKEN)"

        print(f"✓ GitHub rate limit: {remaining}/{limit} remaining{auth_info}", file=sys.stderr, flush=True)

    return 0


def _detect_local_only(tool: Tool) -> LocalInstallation:
    """Detect local installation without collecting upstream version."""
    from cli_audit.catalog import ToolCatalog

    catalog = ToolCatalog()
    version_flag = None
    version_command = None
    if catalog.has_tool(tool.name):
        catalog_data = catalog.get_raw_data(tool.name)
        version_flag = catalog_data.get("version_flag")
        version_command = catalog_data.get("version_command")

    deep_scan = tool.name in {"node", "python", "semgrep", "pre-commit", "bandit", "black", "flake8", "isort"}
    version_num, version_line, path, install_method = audit_tool_installation(
        tool.name, tool.candidates, deep=deep_scan, version_flag=version_flag, version_command=version_command
    )
    version_num, version_line, path, install_method, from_cache = _apply_probe_timeout_fallback(
        tool.name, version_num, version_line, path, install_method
    )

    installed = version_num if version_num else (version_line if version_line != "X" else "")

    if from_cache:
        classification_reason = "Cached version (probe timed out); last known method: " + (install_method or "unknown")
    elif install_method:
        classification_reason = f"Detected via path analysis: {install_method}"
    else:
        classification_reason = "No installation detected"

    return LocalInstallation(
        installed_version=installed,
        installed_path=path,
        installed_method=install_method,
        status="UNKNOWN",  # Will be determined by caller using cached upstream
        classification_reason=classification_reason,
        category=tool.category,
        hint=tool.hint,
    )


def cmd_install(args: argparse.Namespace) -> int:
    """Install missing tools using bulk installation system."""
    print("=" * 80, file=sys.stderr)
    print("Install Mode", file=sys.stderr)
    print("=" * 80, file=sys.stderr)

    print("Please specify tools to install: audit.py --install TOOL1 TOOL2", file=sys.stderr)
    return 1


def cmd_upgrade(args: argparse.Namespace) -> int:
    """Upgrade outdated tools using upgrade orchestration system."""
    print("=" * 80, file=sys.stderr)
    print("Upgrade Mode", file=sys.stderr)
    print("=" * 80, file=sys.stderr)

    print("Upgrade functionality available via upgrade module", file=sys.stderr)
    return 1


def cmd_versions(args: argparse.Namespace) -> int:
    """Show multi-version runtime status.

    Displays all runtimes that support multiple concurrent versions (PHP, Python,
    Node.js, Ruby, Go) and shows which versions are installed vs available.

    Supports JSON output via CLI_AUDIT_JSON=1 environment variable.
    """
    from cli_audit.catalog import ToolCatalog

    catalog = ToolCatalog()

    # Find all tools with multi_version enabled
    multi_version_tools = []
    for tool_name in catalog.all_tools():
        data = catalog.get_raw_data(tool_name)
        mv_config = data.get("multi_version", {})
        if mv_config.get("enabled"):
            multi_version_tools.append((tool_name, data, mv_config))

    if not multi_version_tools:
        if JSON_MODE:
            print(json.dumps({"runtimes": [], "total": 0}))
        else:
            print("No multi-version runtimes configured.", file=sys.stderr)
        return 0

    # Filter to specific tools if requested
    if args.tools:
        requested = set(args.tools)
        multi_version_tools = [(name, data, config) for name, data, config in multi_version_tools if name in requested]

    # Collect all runtime data
    runtimes_data = []
    for tool_name, data, mv_config in multi_version_tools:
        product = mv_config.get("product", tool_name)
        max_versions = mv_config.get("max_versions", 4)
        display_name = data.get("description", tool_name.upper())

        runtime_info = {
            "name": tool_name,
            "display_name": display_name,
            "product": product,
            "versions": [],
            "error": None,
        }

        # Fetch supported versions from endoflife.date
        try:
            supported = collect_endoflife(product, max_versions=max_versions)
        except Exception as e:
            runtime_info["error"] = str(e)
            runtimes_data.append(runtime_info)
            continue

        if not supported:
            runtime_info["error"] = "No supported versions found"
            runtimes_data.append(runtime_info)
            continue

        # Detect installed versions
        detected = detect_multi_versions(tool_name, mv_config, supported)

        for version_info in detected:
            installed = version_info.get("installed")
            latest = version_info.get("latest_upstream", "")
            runtime_info["versions"].append(
                {
                    "cycle": version_info.get("cycle", ""),
                    "latest_upstream": latest,
                    "installed": installed,
                    "is_installed": bool(installed),
                    "is_up_to_date": installed == latest if installed else False,
                    "needs_upgrade": bool(installed and installed != latest),
                    "path": version_info.get("path", ""),
                    "install_method": version_info.get("install_method", ""),
                    "status": version_info.get("status", "unknown"),
                }
            )

        runtimes_data.append(runtime_info)

    # JSON output mode
    if JSON_MODE:
        output = {
            "runtimes": runtimes_data,
            "total": len(runtimes_data),
        }
        print(json.dumps(output, indent=2))
        return 0

    # Table output mode
    GREEN = "\033[32m"
    YELLOW = "\033[33m"
    RED = "\033[31m"
    BLUE = "\033[34m"
    BOLD = "\033[1m"
    RESET = "\033[0m"

    print("=" * 80, file=sys.stderr)
    print("Runtime Versions", file=sys.stderr)
    print("=" * 80, file=sys.stderr)
    print("", file=sys.stderr)

    for runtime in runtimes_data:
        print(f"{BOLD}🔧 {runtime['display_name']}{RESET}", file=sys.stderr)
        print("-" * 40, file=sys.stderr)

        if runtime["error"]:
            print(f"  {RED}✗ {runtime['error']}{RESET}", file=sys.stderr)
            print("", file=sys.stderr)
            continue

        for v in runtime["versions"]:
            cycle = v["cycle"]
            latest = v["latest_upstream"]
            installed = v["installed"]
            status = v["status"]
            method = v["install_method"]

            # Status indicator
            if status == "active":
                status_str = f"{GREEN}active{RESET}"
            elif status == "security":
                status_str = f"{YELLOW}security{RESET}"
            else:
                status_str = f"{RED}eol{RESET}"

            # Installed indicator
            if installed:
                if installed == latest:
                    inst_str = f"{GREEN}✓ {installed}{RESET}"
                else:
                    inst_str = f"{YELLOW}⚠ {installed}{RESET} → {GREEN}{latest}{RESET}"
                method_str = f" ({method})" if method else ""
            else:
                inst_str = f"{BLUE}○ not installed{RESET}"
                method_str = ""

            print(f"  {cycle:6} [{status_str:16}] {inst_str}{method_str}", file=sys.stderr)

        print("", file=sys.stderr)

    # Summary
    print("=" * 80, file=sys.stderr)
    print(f"Total: {len(runtimes_data)} runtimes configured", file=sys.stderr)

    return 0


def _shape_reconcile_plan(tool, installs, preferred, active, protected):
    """Build a uniform plan dict for a tool's installations.

    Each installation gets a ``preferred`` boolean (matched by path) so shell
    consumers don't have to cross-reference the separate ``preferred`` entry.
    """
    pref_path = preferred.path if preferred else None
    return {
        "tool": tool,
        "count": len(installs),
        "protected": protected,
        "preferred": preferred.to_dict() if preferred else None,
        "active": active.to_dict() if active else None,
        "installations": [{**i.to_dict(), "preferred": bool(pref_path and i.path == pref_path)} for i in installs],
    }


def _print_reconcile_plans(plans) -> None:
    """Human-readable rendering of reconcile plans (non-JSON mode)."""
    multi = [p for p in plans if p["count"] > 1]
    if not multi:
        print("No duplicate installations detected.", file=sys.stderr)
        return
    for p in multi:
        note = " [protected]" if p["protected"] else ""
        print(f"\n{p['tool']} — {p['count']} installations{note}:", file=sys.stderr)
        for i in p["installations"]:
            marks = []
            if i.get("active"):
                marks.append("→ active")
            if i.get("preferred"):
                marks.append("✓ keep")
            suffix = ("  " + "  ".join(marks)) if marks else ""
            ver = i.get("version") or "?"
            print(f"   • {ver}  {i['method']}  {i['path']}{suffix}", file=sys.stderr)


def cmd_reconcile(args: argparse.Namespace) -> int:
    """Reconcile duplicate installations of a tool.

    Without --apply this only reports the plan (which install is kept vs
    removed, which is active on PATH). With --apply it removes the non-preferred
    installations (aggressive mode), honoring the system-tool safelist.

    Supports JSON output via CLI_AUDIT_JSON=1 for consumption by guide.sh.
    """
    from cli_audit.catalog import ToolCatalog
    from cli_audit.reconcile import (
        SYSTEM_TOOL_SAFELIST,
        bulk_reconcile,
        detect_installations,
        reconcile_tool,
    )

    catalog = ToolCatalog()

    def _candidates(tool):
        try:
            return list(catalog.get(tool).to_tool().candidates)
        except Exception:
            return None

    def _plan(tool):
        installs = detect_installations(tool, candidates=_candidates(tool), verbose=args.verbose)
        preferred = installs[0] if installs else None
        active = next((i for i in installs if i.active), None)
        return _shape_reconcile_plan(tool, installs, preferred, active, tool in SYSTEM_TOOL_SAFELIST)

    apply = getattr(args, "apply", False)
    force = getattr(args, "yes", False)
    do_all = getattr(args, "all", False)

    # --- ALL mode ---
    # bulk_reconcile's own "all"/"conflicts" modes only look at config.tools
    # (a tiny user-config subset), so sweep the full catalog explicitly.
    if do_all:
        all_tools = list(catalog.all_tools())
        if apply:
            result = bulk_reconcile(
                mode="explicit",
                tool_names=all_tools,
                reconcile_mode="aggressive",
                force=force,
                verbose=args.verbose,
            )
            # Report only tools that actually had duplicates — the explicit
            # sweep visits every catalog entry, but --all is about conflicts.
            conflicts = [r for r in result.results if len(r.installations) > 1]
            if JSON_MODE:
                print(
                    json.dumps(
                        {
                            "tools_checked": result.tools_checked,
                            "conflicts_found": result.conflicts_found,
                            "conflicts_resolved": result.conflicts_resolved,
                            "results": [r.to_dict() for r in conflicts],
                            "duration_seconds": result.duration_seconds,
                        }
                    )
                )
            else:
                # Per-tool outcomes must be visible without --verbose: a user
                # who confirmed a removal needs to see why it failed.
                for r in conflicts:
                    if r.action_taken == "aborted":
                        print(f"  {r.tool}: skipped (declined)", file=sys.stderr)
                    elif r.action_taken == "blocked":
                        print(f"  {r.tool}: skipped (protected system tool)", file=sys.stderr)
                    elif r.action_taken == "manual_required":
                        print(f"  ⚠ {r.tool}: {r.error_message}", file=sys.stderr)
                    elif not r.success and r.error_message:
                        print(f"  ✗ {r.tool}: {r.error_message}", file=sys.stderr)
                # Aggregate confirmed-but-failed removals into one copy-paste
                # command per remedy instead of dozens of per-tool sudo hints.
                pm_tools: dict[str, set[str]] = {}
                rm_paths: set[str] = set()
                for r in conflicts:
                    if r.action_taken not in ("removed", "manual_required") or r.success:
                        continue
                    for inst in r.installations:
                        if inst == r.preferred or inst in r.removed_installations:
                            continue
                        if inst.method in ("apt", "dnf", "pacman"):
                            pm_tools.setdefault(inst.method, set()).add(inst.tool)
                        elif inst.method in ("manual", "unknown", "go"):
                            rm_paths.add(inst.path)
                if pm_tools or rm_paths:
                    print("\nTo finish the confirmed removals manually, run:", file=sys.stderr)
                    for pm in sorted(pm_tools):
                        print(f"  sudo {pm} remove {' '.join(sorted(pm_tools[pm]))}", file=sys.stderr)
                    if rm_paths:
                        print(f"  sudo rm -f {' '.join(sorted(rm_paths))}", file=sys.stderr)
                print(result.summary(), file=sys.stderr)
            # Fail only on real removal errors — not on protected tools (blocked),
            # tools the user declined (aborted), or removals that just need a
            # manual sudo command (manual_required), which are expected outcomes.
            failures = [
                r
                for r in conflicts
                if not r.success and r.action_taken not in ("blocked", "aborted", "none", "manual_required")
            ]
            return 1 if failures else 0
        # Plan-only sweep (parallel detection, no removal)
        result = bulk_reconcile(
            mode="explicit",
            tool_names=all_tools,
            reconcile_mode="parallel",
            verbose=args.verbose,
        )
        plans = [
            _shape_reconcile_plan(
                r.tool,
                list(r.installations),
                r.preferred,
                r.active,
                r.tool in SYSTEM_TOOL_SAFELIST,
            )
            for r in result.results
            if len(r.installations) > 1
        ]
        if JSON_MODE:
            print(json.dumps({"results": plans, "total": len(plans)}))
        else:
            _print_reconcile_plans(plans)
        return 0

    # --- Explicit tools ---
    tools = args.tools
    if not tools:
        print("reconcile: specify one or more tools, or use --all", file=sys.stderr)
        return 2

    if apply:
        results = []
        for tool in tools:
            results.append(
                reconcile_tool(
                    tool,
                    mode="aggressive",
                    candidates=_candidates(tool),
                    force=force,
                    verbose=args.verbose,
                )
            )
        if JSON_MODE:
            print(json.dumps({"results": [r.to_dict() for r in results]}))
        else:
            for r in results:
                extra = f" ({r.error_message})" if r.error_message else ""
                print(f"{r.tool}: {r.action_taken}{extra}", file=sys.stderr)
        return 0 if all(r.success or r.action_taken == "manual_required" for r in results) else 1

    plans = [_plan(t) for t in tools]
    if JSON_MODE:
        print(json.dumps({"results": plans}))
    else:
        _print_reconcile_plans(plans)
    return 0


def main() -> int:
    """Main entry point for audit system."""
    parser = argparse.ArgumentParser(
        description="AI CLI Preparation - Tool Audit and Version Management",
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )

    parser.add_argument(
        "--update",
        action="store_true",
        help="Collect latest versions from upstream (network required)",
    )
    parser.add_argument(
        "--update-local",
        action="store_true",
        help="Update only local state (no network, fast)",
    )
    parser.add_argument(
        "--update-baseline",
        action="store_true",
        help="Update only upstream baseline cache (network required)",
    )
    parser.add_argument(
        "--install",
        action="store_true",
        help="Install missing tools",
    )
    parser.add_argument(
        "--upgrade",
        action="store_true",
        help="Upgrade outdated tools",
    )
    parser.add_argument(
        "--versions",
        action="store_true",
        help="Show multi-version runtime status (PHP, Python, Node.js, Ruby, Go)",
    )
    parser.add_argument(
        "--reconcile",
        action="store_true",
        help="Report (or with --apply, remove) duplicate installations of a tool",
    )
    parser.add_argument(
        "--all",
        action="store_true",
        help="With --reconcile: operate on all tools that have duplicate installs",
    )
    parser.add_argument(
        "--apply",
        action="store_true",
        help="With --reconcile: actually remove non-preferred installs (default: plan only)",
    )
    parser.add_argument(
        "--yes",
        action="store_true",
        help="With --reconcile --apply: skip confirmation prompts (honors safelist)",
    )
    parser.add_argument(
        "--verbose",
        "-v",
        action="store_true",
        help="Verbose output",
    )
    parser.add_argument(
        "tools",
        nargs="*",
        help="Specific tools to operate on",
    )

    args = parser.parse_args()

    # Setup logging
    setup_logging(verbose=args.verbose)

    # Reconcile-only flags are meaningless (and silently ignored) without
    # --reconcile — fail loudly so scripting mistakes surface.
    if not args.reconcile and (args.all or args.apply or args.yes):
        print("--all/--apply/--yes are only valid with --reconcile", file=sys.stderr)
        return 2

    # Route to appropriate command
    if args.reconcile:
        return cmd_reconcile(args)
    elif args.versions:
        return cmd_versions(args)
    elif args.update:
        # Explicit --update flag: full update of all tools
        return cmd_update(args)
    elif getattr(args, "update_local", False) or UPDATE_LOCAL_ONLY:
        # Update only local state (fast, no network)
        return cmd_update_local(args)
    elif getattr(args, "update_baseline", False) or UPDATE_BASELINE_ONLY:
        # Update only upstream baseline cache
        return cmd_update_baseline(args)
    elif args.install:
        return cmd_install(args)
    elif args.upgrade:
        return cmd_upgrade(args)
    elif COLLECT_MODE and not args.tools:
        # COLLECT_MODE without specific tools: full update
        return cmd_update(args)
    else:
        # Default: audit mode (supports both snapshot rendering and per-tool fresh collection)
        return cmd_audit(args)


if __name__ == "__main__":
    try:
        sys.exit(main())
    except KeyboardInterrupt:
        print("\nInterrupted", file=sys.stderr)
        sys.exit(130)