scc-cli 1.5.3__py3-none-any.whl

scc_cli/output_mode.py

@@ -0,0 +1,167 @@
+"""
+JSON output mode infrastructure.
+
+Provide context management for JSON output mode with automatic stderr suppression.
+Use ContextVar for thread-safe, async-compatible state isolation.
+
+Usage:
+    from scc_cli.output_mode import json_output_mode, is_json_mode, print_json, print_human
+
+    # In command handler:
+    with json_output_mode():
+        # All stderr chatter is suppressed here
+        result = do_work()
+        print_json(build_envelope(Kind.X, data=result))
+
+    # Outside JSON mode (normal human output):
+    print_human("Processing...")  # Only prints if not in JSON mode
+"""
+
+import json
+import sys
+from collections.abc import Generator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import Any, TextIO
+
+from rich.console import Console
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Context Variables (Thread-safe, Async-compatible)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+_json_mode: ContextVar[bool] = ContextVar("json_mode", default=False)
+_json_command_mode: ContextVar[bool] = ContextVar("json_command_mode", default=False)
+_pretty_mode: ContextVar[bool] = ContextVar("pretty_mode", default=False)
+
+# Console instances for stdout and stderr
+# Rich Console requires file= in constructor, not in print()
+console = Console()
+err_console = Console(stderr=True)
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Context Managers
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+@contextmanager
+def json_output_mode() -> Generator[None, None, None]:
+    """Context manager for JSON output mode.
+
+    While active:
+    - is_json_mode() returns True
+    - print_human() becomes a no-op
+    - All stderr chatter should be suppressed
+
+    The context is properly reset even if an exception occurs,
+    thanks to ContextVar's token-based reset mechanism.
+    """
+    token = _json_mode.set(True)
+    try:
+        yield
+    finally:
+        _json_mode.reset(token)
+
+
+@contextmanager
+def json_command_mode() -> Generator[None, None, None]:
+    """Context manager for JSON command handling.
+
+    This signals that errors should be handled by json_command instead of
+    the generic error handler, allowing consistent JSON envelopes.
+    """
+    token = _json_command_mode.set(True)
+    try:
+        yield
+    finally:
+        _json_command_mode.reset(token)
+
+
+@contextmanager
+def pretty_output_mode() -> Generator[None, None, None]:
+    """Context manager for pretty-printed JSON output.
+
+    Enables indented JSON output. Usually combined with json_output_mode.
+    """
+    token = _pretty_mode.set(True)
+    try:
+        yield
+    finally:
+        _pretty_mode.reset(token)
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# State Query Functions
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+def is_json_mode() -> bool:
+    """Check if JSON output mode is active."""
+    return _json_mode.get()
+
+
+def is_json_command_mode() -> bool:
+    """Check if JSON command handling mode is active."""
+    return _json_command_mode.get()
+
+
+def is_pretty_mode() -> bool:
+    """Check if pretty-print mode is active for JSON output."""
+    return _pretty_mode.get()
+
+
+def set_pretty_mode(value: bool) -> None:
+    """Set pretty-print mode for JSON output.
+
+    Note: This is a direct setter that doesn't use context management.
+    Use pretty_output_mode() context manager when possible for proper cleanup.
+
+    Args:
+        value: True to enable pretty-printing, False to disable.
+    """
+    _pretty_mode.set(value)
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Output Functions
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+def print_human(message: str, file: TextIO | None = None, **kwargs: Any) -> None:
+    """Print human-readable output.
+
+    This is a no-op when JSON mode is active, ensuring clean JSON output
+    without any interleaved human-readable messages.
+
+    Args:
+        message: The message to print (Rich markup supported)
+        file: Output target. Use sys.stderr for warnings/errors.
+            Note: Rich Console requires file in constructor, not print(),
+            so we use a separate err_console for stderr output.
+        **kwargs: Additional arguments passed to console.print()
+    """
+    if not is_json_mode():
+        # Select appropriate console based on file parameter
+        target = err_console if file is sys.stderr else console
+        target.print(message, **kwargs)
+
+
+def print_json(envelope: dict[str, Any]) -> None:
+    """Print JSON envelope to stdout.
+
+    Output format:
+    - Compact (no indentation) by default for CI/scripting efficiency
+    - Pretty-printed (2-space indent) when pretty mode is active
+
+    Args:
+        envelope: The JSON envelope to output
+    """
+    if is_pretty_mode():
+        # Pretty mode: indented for human readability
+        output = json.dumps(envelope, indent=2)
+    else:
+        # Compact mode: minimal size for CI pipelines
+        output = json.dumps(envelope, separators=(",", ":"))
+
+    print(output)

scc_cli/panels.py

@@ -0,0 +1,113 @@
+"""
+Provide Rich panel components for consistent UI across the CLI.
+
+Define reusable panel factories for info, warning, success, and error messages
+with standardized styling and structure.
+
+All colors are sourced from ui/theme.py design tokens for consistency.
+"""
+
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from scc_cli.theme import Borders, Colors
+
+
+def create_info_panel(title: str, content: str, subtitle: str = "") -> Panel:
+    """Create an info panel with brand styling.
+
+    Args:
+        title: Panel title text.
+        content: Main content text.
+        subtitle: Optional dimmed subtitle text.
+
+    Returns:
+        Rich Panel with brand color border and styling.
+    """
+    body = Text()
+    body.append(content)
+    if subtitle:
+        body.append("\n")
+        body.append(subtitle, style=Colors.SECONDARY)
+    return Panel(
+        body,
+        title=f"[{Colors.BRAND_BOLD}]{title}[/{Colors.BRAND_BOLD}]",
+        border_style=Borders.PANEL_INFO,
+        padding=(0, 1),
+    )
+
+
+def create_warning_panel(title: str, message: str, hint: str = "") -> Panel:
+    """Create a warning panel with warning styling.
+
+    Args:
+        title: Panel title text (will have warning icon prepended).
+        message: Main warning message.
+        hint: Optional action hint text.
+
+    Returns:
+        Rich Panel with warning color border and styling.
+    """
+    body = Text()
+    body.append(message, style="bold")
+    if hint:
+        body.append("\n\n")
+        body.append("-> ", style=Colors.SECONDARY)
+        body.append(hint, style=Colors.WARNING)
+    return Panel(
+        body,
+        title=f"[{Colors.WARNING_BOLD}]{title}[/{Colors.WARNING_BOLD}]",
+        border_style=Borders.PANEL_WARNING,
+        padding=(0, 1),
+    )
+
+
+def create_success_panel(title: str, items: dict[str, str]) -> Panel:
+    """Create a success panel with key-value summary.
+
+    Args:
+        title: Panel title text (will have checkmark icon prepended).
+        items: Dictionary of key-value pairs to display.
+
+    Returns:
+        Rich Panel with success color border and key-value grid.
+    """
+    grid = Table.grid(padding=(0, 2))
+    grid.add_column(style=Colors.SECONDARY, no_wrap=True)
+    grid.add_column(style=Colors.PRIMARY)
+
+    for key, value in items.items():
+        grid.add_row(f"{key}:", str(value))
+
+    return Panel(
+        grid,
+        title=f"[{Colors.SUCCESS_BOLD}]{title}[/{Colors.SUCCESS_BOLD}]",
+        border_style=Borders.PANEL_SUCCESS,
+        padding=(0, 1),
+    )
+
+
+def create_error_panel(title: str, message: str, hint: str = "") -> Panel:
+    """Create an error panel with error styling.
+
+    Args:
+        title: Panel title text (will have error icon prepended).
+        message: Main error message.
+        hint: Optional fix/action hint text.
+
+    Returns:
+        Rich Panel with error color border and styling.
+    """
+    body = Text()
+    body.append(message, style="bold")
+    if hint:
+        body.append("\n\n")
+        body.append("-> ", style=Colors.SECONDARY)
+        body.append(hint, style=Colors.ERROR)
+    return Panel(
+        body,
+        title=f"[{Colors.ERROR_BOLD}]{title}[/{Colors.ERROR_BOLD}]",
+        border_style=Borders.PANEL_ERROR,
+        padding=(0, 1),
+    )

scc_cli/platform.py

@@ -0,0 +1,350 @@
+"""
+Platform detection and cross-platform utilities.
+
+Handle detection of:
+- Operating system (macOS, Linux, Windows, WSL2)
+- Path normalization across platforms
+- Performance warnings for suboptimal configurations
+
+WSL2 Considerations:
+- Files on /mnt/c (Windows filesystem) are significantly slower
+- Recommend using ~/projects inside WSL for optimal performance
+"""
+
+import os
+import sys
+from enum import Enum
+from pathlib import Path
+
+
+class Platform(Enum):
+    """Supported platforms."""
+
+    MACOS = "macos"
+    LINUX = "linux"
+    WINDOWS = "windows"
+    WSL2 = "wsl2"
+    UNKNOWN = "unknown"
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Platform Detection
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+def detect_platform() -> Platform:
+    """Detect the current platform.
+
+    Return the most specific platform identifier:
+    - WSL2 takes precedence over Linux
+    - macOS, Windows, Linux detected by sys.platform
+    """
+    if is_wsl2():
+        return Platform.WSL2
+
+    if sys.platform == "darwin":
+        return Platform.MACOS
+    elif sys.platform == "win32":
+        return Platform.WINDOWS
+    elif sys.platform.startswith("linux"):
+        return Platform.LINUX
+
+    return Platform.UNKNOWN
+
+
+def is_wsl2() -> bool:
+    """Detect if running in WSL2 environment.
+
+    WSL2 has 'wsl2' in /proc/version (e.g., 'microsoft-standard-WSL2').
+    WSL1 only has 'Microsoft' without 'wsl2' marker.
+    """
+    if sys.platform != "linux":
+        return False
+
+    try:
+        with open("/proc/version") as f:
+            version_info = f.read().lower()
+            # WSL2 specifically contains 'wsl2' in the kernel version
+            return "wsl2" in version_info
+    except (FileNotFoundError, PermissionError, OSError):
+        return False
+
+
+def is_wsl1() -> bool:
+    """Detect if running in WSL1 (legacy) environment.
+
+    WSL1 has 'Microsoft' in /proc/version but NOT 'wsl2'.
+    """
+    if sys.platform != "linux":
+        return False
+
+    try:
+        with open("/proc/version") as f:
+            version_info = f.read().lower()
+            # WSL1 has 'microsoft' but NOT 'wsl2'
+            return "microsoft" in version_info and "wsl2" not in version_info
+    except (FileNotFoundError, PermissionError, OSError):
+        return False
+
+
+def is_macos() -> bool:
+    """Check if running on macOS."""
+    return sys.platform == "darwin"
+
+
+def is_linux() -> bool:
+    """Check if running on native Linux (not WSL)."""
+    return sys.platform.startswith("linux") and not is_wsl2()
+
+
+def is_windows() -> bool:
+    """Check if running on native Windows."""
+    return sys.platform == "win32"
+
+
+def get_platform_name() -> str:
+    """Get human-readable platform name."""
+    platform = detect_platform()
+    names = {
+        Platform.MACOS: "macOS",
+        Platform.LINUX: "Linux",
+        Platform.WINDOWS: "Windows",
+        Platform.WSL2: "WSL2 (Windows Subsystem for Linux)",
+        Platform.UNKNOWN: "Unknown",
+    }
+    return names.get(platform, "Unknown")
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Path Operations
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+def is_windows_mount_path(path: Path) -> bool:
+    """Check if a path is on the Windows filesystem (via /mnt/c, /mnt/d, etc.).
+
+    In WSL2, paths like /mnt/c/Users/... are on the Windows filesystem
+    and have significantly slower I/O performance.
+    """
+    resolved = path.resolve()
+    path_str = str(resolved)
+
+    # Check for /mnt/<drive_letter> pattern
+    if path_str.startswith("/mnt/") and len(path_str) > 5:
+        # /mnt/c, /mnt/d, etc.
+        drive_letter = path_str[5]
+        if drive_letter.isalpha() and (len(path_str) == 6 or path_str[6] == "/"):
+            return True
+
+    return False
+
+
+def normalize_path(path: str | Path) -> Path:
+    """Normalize a path for the current platform.
+
+    - Expand ~ to home directory
+    - Resolve to absolute path
+    - Handle Windows/Unix path differences
+    """
+    if isinstance(path, str):
+        path = Path(path)
+
+    # Expand user home directory
+    path = path.expanduser()
+
+    # Resolve to absolute path
+    path = path.resolve()
+
+    return path
+
+
+def get_recommended_workspace_base() -> Path:
+    """Get the recommended workspace base directory for the platform.
+
+    - macOS/Linux: ~/projects
+    - WSL2: ~/projects (inside WSL, not /mnt/c)
+    - Windows: C:\\Users\\<user>\\projects
+    """
+    if is_wsl2():
+        # In WSL2, always use Linux filesystem for performance
+        return Path.home() / "projects"
+    elif is_windows():
+        return Path.home() / "projects"
+    else:
+        return Path.home() / "projects"
+
+
+def check_path_performance(path: Path) -> tuple[bool, str | None]:
+    """
+    Check if a path has optimal performance characteristics.
+
+    Returns:
+        Tuple of (is_optimal, warning_message)
+    """
+    if not is_wsl2():
+        return True, None
+
+    if is_windows_mount_path(path):
+        return False, (
+            f"Path {path} is on the Windows filesystem.\n"
+            "File operations will be significantly slower.\n"
+            "Recommendation: Move to ~/projects inside WSL."
+        )
+
+    return True, None
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Environment Information
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+def get_shell() -> str:
+    """Get the current shell name."""
+    shell = os.environ.get("SHELL", "")
+    if shell:
+        return Path(shell).name
+    return "unknown"
+
+
+def get_terminal() -> str:
+    """Get the current terminal emulator name."""
+    term = os.environ.get("TERM_PROGRAM", os.environ.get("TERMINAL", ""))
+    if term:
+        return term
+    return os.environ.get("TERM", "unknown")
+
+
+def get_home_directory() -> Path:
+    """Get the user's home directory."""
+    return Path.home()
+
+
+def supports_unicode() -> bool:
+    """Check if the terminal supports Unicode characters.
+
+    Return True if UTF-8 encoding is available.
+    """
+    encoding = sys.stdout.encoding
+    if encoding:
+        return encoding.lower() in ("utf-8", "utf8")
+
+    # Check LANG environment variable
+    lang = os.environ.get("LANG", "")
+    return "utf-8" in lang.lower() or "utf8" in lang.lower()
+
+
+def supports_colors() -> bool:
+    """Check if the terminal supports ANSI colors.
+
+    Check various environment indicators.
+    """
+    # Rich handles this well, but we can do basic detection
+    if os.environ.get("NO_COLOR"):
+        return False
+
+    if os.environ.get("FORCE_COLOR"):
+        return True
+
+    # Check if stdout is a TTY
+    if hasattr(sys.stdout, "isatty") and sys.stdout.isatty():
+        return True
+
+    return False
+
+
+def get_terminal_size() -> tuple[int, int]:
+    """Get terminal size (columns, rows).
+
+    Return (80, 24) as default if detection fails.
+    """
+    try:
+        size = os.get_terminal_size()
+        return size.columns, size.lines
+    except OSError:
+        return 80, 24
+
+
+def is_wide_terminal(threshold: int = 110) -> bool:
+    """
+    Check if terminal is wide enough for full layout.
+
+    Args:
+        threshold: Minimum columns for "wide" mode (default 110)
+
+    Returns:
+        True if terminal width >= threshold
+    """
+    columns, _ = get_terminal_size()
+    return columns >= threshold
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Platform-Specific Paths
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+def get_config_dir() -> Path:
+    """Get the platform-appropriate configuration directory.
+
+    - macOS: ~/Library/Application Support/scc-cli
+    - Linux/WSL2: ~/.config/scc-cli
+    - Windows: %APPDATA%\\scc-cli
+    """
+    if is_macos():
+        return Path.home() / "Library" / "Application Support" / "scc-cli"
+    elif is_windows():
+        appdata = os.environ.get("APPDATA")
+        if appdata:
+            return Path(appdata) / "scc-cli"
+        return Path.home() / "AppData" / "Roaming" / "scc-cli"
+    else:
+        # Linux, WSL2
+        xdg_config = os.environ.get("XDG_CONFIG_HOME")
+        if xdg_config:
+            return Path(xdg_config) / "scc-cli"
+        return Path.home() / ".config" / "scc-cli"
+
+
+def get_cache_dir() -> Path:
+    """Get the platform-appropriate cache directory.
+
+    - macOS: ~/Library/Caches/scc-cli
+    - Linux/WSL2: ~/.cache/scc-cli
+    - Windows: %LOCALAPPDATA%\\scc-cli\\cache
+    """
+    if is_macos():
+        return Path.home() / "Library" / "Caches" / "scc-cli"
+    elif is_windows():
+        localappdata = os.environ.get("LOCALAPPDATA")
+        if localappdata:
+            return Path(localappdata) / "scc-cli" / "cache"
+        return Path.home() / "AppData" / "Local" / "scc-cli" / "cache"
+    else:
+        # Linux, WSL2
+        xdg_cache = os.environ.get("XDG_CACHE_HOME")
+        if xdg_cache:
+            return Path(xdg_cache) / "scc-cli"
+        return Path.home() / ".cache" / "scc-cli"
+
+
+def get_data_dir() -> Path:
+    """Get the platform-appropriate data directory.
+
+    - macOS: ~/Library/Application Support/scc-cli
+    - Linux/WSL2: ~/.local/share/scc-cli
+    - Windows: %LOCALAPPDATA%\\scc-cli\\data
+    """
+    if is_macos():
+        return Path.home() / "Library" / "Application Support" / "scc-cli"
+    elif is_windows():
+        localappdata = os.environ.get("LOCALAPPDATA")
+        if localappdata:
+            return Path(localappdata) / "scc-cli" / "data"
+        return Path.home() / "AppData" / "Local" / "scc-cli" / "data"
+    else:
+        # Linux, WSL2
+        xdg_data = os.environ.get("XDG_DATA_HOME")
+        if xdg_data:
+            return Path(xdg_data) / "scc-cli"
+        return Path.home() / ".local" / "share" / "scc-cli"