scc-cli 1.4.1__py3-none-any.whl

scc_cli/cli_audit.py

@@ -0,0 +1,245 @@
+"""Provide CLI commands for plugin audit functionality.
+
+Audit installed Claude Code plugins via the `scc audit plugins` command,
+including manifest validation and MCP server/hooks discovery.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from scc_cli.audit.reader import audit_all_plugins
+from scc_cli.constants import AGENT_CONFIG_DIR
+from scc_cli.models.plugin_audit import (
+    AuditOutput,
+    ManifestStatus,
+    PluginAuditResult,
+)
+
+console = Console()
+
+# Create the audit sub-app
+audit_app = typer.Typer(
+    name="audit",
+    help="Audit installed plugins and configurations.",
+    no_args_is_help=True,
+)
+
+
+def get_claude_dir() -> Path:
+    """Get the Claude Code directory path."""
+    return Path.home() / AGENT_CONFIG_DIR
+
+
+def format_status(status: str) -> str:
+    """Format status with color for Rich output."""
+    if status == "clean":
+        return "[dim]clean[/dim]"
+    elif status == "parsed":
+        return "[green]parsed[/green]"
+    elif status == "malformed":
+        return "[red]malformed[/red]"
+    elif status == "unreadable":
+        return "[yellow]unreadable[/yellow]"
+    elif status == "not installed":
+        return "[dim]not installed[/dim]"
+    return status
+
+
+def render_human_output(output: AuditOutput) -> None:
+    """Render audit output in human-readable format."""
+    # Header
+    console.print()
+    header_body = Text()
+    header_body.append("Plugin Audit Report", style="bold")
+    header_body.append("\n")
+    header_body.append(f"Discovered {output.total_plugins} plugin(s)", style="dim")
+    console.print(
+        Panel(
+            header_body,
+            border_style="cyan",
+            padding=(0, 1),
+        )
+    )
+    console.print()
+
+    if output.total_plugins == 0:
+        console.print("[dim]No plugins installed.[/dim]")
+        console.print()
+        _print_disclaimer()
+        return
+
+    # Create table for plugins with rounded borders
+    table = Table(
+        show_header=True,
+        header_style="bold",
+        box=box.ROUNDED,
+        border_style="dim",
+        padding=(0, 1),
+    )
+    table.add_column("Plugin", style="cyan", no_wrap=True)
+    table.add_column("Version", style="dim")
+    table.add_column("Status", justify="center")
+    table.add_column("MCP", justify="right", style="green")
+    table.add_column("Hooks", justify="right", style="yellow")
+
+    for plugin in output.plugins:
+        # Format MCP server count
+        mcp_count = 0
+        if plugin.manifests and plugin.manifests.mcp.status == ManifestStatus.PARSED:
+            mcp_count = len(plugin.manifests.mcp_servers)
+        mcp_display = str(mcp_count) if mcp_count > 0 else "[dim]-[/dim]"
+
+        # Format hooks count
+        hooks_count = 0
+        if plugin.manifests and plugin.manifests.hooks.status == ManifestStatus.PARSED:
+            hooks_count = len(plugin.manifests.hooks_info)
+        hooks_display = str(hooks_count) if hooks_count > 0 else "[dim]-[/dim]"
+
+        table.add_row(
+            plugin.plugin_name,
+            plugin.version,
+            format_status(plugin.status_summary),
+            mcp_display,
+            hooks_display,
+        )
+
+    console.print(table)
+    console.print()
+
+    # Show details for plugins with declarations
+    for plugin in output.plugins:
+        if plugin.manifests and plugin.manifests.has_declarations:
+            _render_plugin_details(plugin)
+
+    # Show problems in a warning panel
+    problem_plugins = [p for p in output.plugins if p.has_ci_failures]
+    if problem_plugins:
+        _render_problems_panel(problem_plugins)
+
+    # Disclaimer
+    _print_disclaimer()
+
+
+def _render_plugin_details(plugin: PluginAuditResult) -> None:
+    """Render details for a plugin with declarations."""
+    if not plugin.manifests:
+        return
+
+    # Create a details grid
+    details = Text()
+    details.append(f"  {plugin.plugin_name}", style="bold cyan")
+    details.append("\n")
+
+    # Show MCP servers
+    if plugin.manifests.mcp_servers:
+        details.append("  MCP Servers: ", style="dim")
+        server_names = [s.name for s in plugin.manifests.mcp_servers]
+        details.append(", ".join(server_names), style="green")
+        details.append("\n")
+
+    # Show hooks
+    if plugin.manifests.hooks_info:
+        details.append("  Hooks: ", style="dim")
+        hook_events = [h.event for h in plugin.manifests.hooks_info]
+        details.append(", ".join(hook_events), style="yellow")
+        details.append("\n")
+
+    console.print(details)
+
+
+def _render_problems_panel(plugins: list[PluginAuditResult]) -> None:
+    """Render a warning panel for all plugins with CI failures."""
+    problems_text = Text()
+
+    for i, plugin in enumerate(plugins):
+        if not plugin.manifests:
+            continue
+
+        if i > 0:
+            problems_text.append("\n")
+
+        problems_text.append(f"⚠ {plugin.plugin_name}", style="bold red")
+        problems_text.append("\n")
+
+        # Check MCP manifest
+        if plugin.manifests.mcp.has_problems:
+            mcp = plugin.manifests.mcp
+            if mcp.status == ManifestStatus.MALFORMED and mcp.error:
+                problems_text.append("  .mcp.json: ", style="dim")
+                problems_text.append(f"malformed ({mcp.error.format()})", style="red")
+                problems_text.append("\n")
+            elif mcp.status == ManifestStatus.UNREADABLE:
+                problems_text.append("  .mcp.json: ", style="dim")
+                problems_text.append(f"unreadable ({mcp.error_message})", style="yellow")
+                problems_text.append("\n")
+
+        # Check hooks manifest
+        if plugin.manifests.hooks.has_problems:
+            hooks = plugin.manifests.hooks
+            if hooks.status == ManifestStatus.MALFORMED and hooks.error:
+                problems_text.append("  hooks/hooks.json: ", style="dim")
+                problems_text.append(f"malformed ({hooks.error.format()})", style="red")
+                problems_text.append("\n")
+            elif hooks.status == ManifestStatus.UNREADABLE:
+                problems_text.append("  hooks/hooks.json: ", style="dim")
+                problems_text.append(f"unreadable ({hooks.error_message})", style="yellow")
+                problems_text.append("\n")
+
+    console.print(
+        Panel(
+            problems_text,
+            title="[bold yellow]Manifest Problems[/bold yellow]",
+            border_style="yellow",
+            padding=(0, 1),
+        )
+    )
+    console.print()
+
+
+def _print_disclaimer() -> None:
+    """Print the informational disclaimer."""
+    console.print("[dim]ℹ Informational only; SCC does not enforce plugin internals.[/dim]")
+    console.print()
+
+
+def render_json_output(output: AuditOutput) -> None:
+    """Render audit output as JSON."""
+    data = output.to_dict()
+    console.print(json.dumps(data, indent=2))
+
+
+@audit_app.command(name="plugins")
+def audit_plugins_cmd(
+    as_json: bool = typer.Option(
+        False,
+        "--json",
+        help="Output as JSON with schemaVersion for CI integration.",
+    ),
+) -> None:
+    """Audit installed Claude Code plugins.
+
+    Shows manifest status, MCP servers, and hooks for all installed plugins.
+
+    Exit codes:
+    - 0: All plugins parsed successfully (or no plugins installed)
+    - 1: One or more plugins have malformed or unreadable manifests
+    """
+    claude_dir = get_claude_dir()
+    output = audit_all_plugins(claude_dir)
+
+    if as_json:
+        render_json_output(output)
+    else:
+        render_human_output(output)
+
+    # Exit with appropriate code for CI
+    raise typer.Exit(code=output.exit_code)

scc_cli/cli_common.py

@@ -0,0 +1,166 @@
+"""
+CLI Common Utilities.
+
+Shared utilities, constants, and decorators used across all CLI modules.
+This module is extracted to prevent circular imports and enable clean composition.
+"""
+
+from collections.abc import Callable
+from functools import wraps
+from typing import Any, TypeVar, cast
+
+import typer
+from rich import box
+from rich.console import Console
+from rich.table import Table
+
+from .errors import SCCError
+from .exit_codes import EXIT_CANCELLED
+from .output_mode import is_json_command_mode, is_json_mode
+from .panels import create_warning_panel
+from .ui.prompts import render_error
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Display Constants
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Maximum length for displaying file paths before truncation
+MAX_DISPLAY_PATH_LENGTH = 50
+# Characters to keep when truncating (MAX - 3 for "...")
+PATH_TRUNCATE_LENGTH = 47
+# Terminal width threshold for wide mode tables
+WIDE_MODE_THRESHOLD = 110
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Shared Console and State
+# ─────────────────────────────────────────────────────────────────────────────
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+class AppState:
+    """Global application state for CLI flags."""
+
+    debug: bool = False
+
+
+state = AppState()
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Error Boundary Decorator
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def handle_errors(func: F) -> F:
+    """Catch SCCError exceptions and render user-friendly error output.
+
+    Wrap CLI command functions to provide consistent error handling:
+    - SCCError: Render with render_error and exit with error's exit_code
+    - KeyboardInterrupt: Print cancellation message and exit 130
+    - Other exceptions: Show warning panel (or full traceback with --debug)
+
+    Args:
+        func: The CLI command function to wrap.
+
+    Returns:
+        Wrapped function with error handling.
+    """
+
+    @wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return func(*args, **kwargs)
+        except SCCError as e:
+            if is_json_command_mode():
+                raise
+            target_console = err_console if is_json_mode() else console
+            render_error(target_console, e, debug=state.debug)
+            raise typer.Exit(e.exit_code)
+        except KeyboardInterrupt:
+            if is_json_command_mode():
+                raise
+            target_console = err_console if is_json_mode() else console
+            target_console.print("\n[dim]Operation cancelled.[/dim]")
+            raise typer.Exit(EXIT_CANCELLED)
+        except (typer.Exit, SystemExit):
+            # Let typer exits pass through
+            raise
+        except Exception as e:
+            if is_json_command_mode():
+                raise
+            # Unexpected errors
+            target_console = err_console if is_json_mode() else console
+            if state.debug:
+                target_console.print_exception()
+            else:
+                target_console.print(
+                    create_warning_panel(
+                        "Unexpected Error",
+                        str(e),
+                        "Run with --debug for full traceback",
+                    )
+                )
+            raise typer.Exit(5)
+
+    return cast(F, wrapper)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# UI Helpers (Consistent Aesthetic)
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def render_responsive_table(
+    title: str,
+    columns: list[tuple[str, str]],  # (header, style)
+    rows: list[list[str]],
+    wide_columns: list[tuple[str, str]] | None = None,  # Extra columns for wide mode
+) -> None:
+    """Render a table that adapts to terminal width.
+
+    Display base columns on narrow terminals, adding extra columns when
+    terminal width exceeds WIDE_MODE_THRESHOLD.
+
+    Args:
+        title: Table title displayed above the table.
+        columns: Base columns as list of (header, style) tuples.
+        rows: Data rows where each row contains values for all columns
+            (base + wide). Extra values are ignored on narrow terminals.
+        wide_columns: Additional columns shown only on wide terminals.
+    """
+    width = console.width
+    wide_mode = width >= WIDE_MODE_THRESHOLD
+
+    table = Table(
+        title=f"[bold cyan]{title}[/bold cyan]",
+        box=box.ROUNDED,
+        header_style="bold cyan",
+        expand=True,
+        show_lines=False,
+    )
+
+    # Add base columns
+    for header, style in columns:
+        table.add_column(header, style=style)
+
+    # Add extra columns in wide mode
+    if wide_mode and wide_columns:
+        for header, style in wide_columns:
+            table.add_column(header, style=style)
+
+    # Add rows
+    for row in rows:
+        if wide_mode and wide_columns:
+            table.add_row(*row)
+        else:
+            # Truncate to base columns only
+            table.add_row(*row[: len(columns)])
+
+    console.print()
+    console.print(table)
+    console.print()