scc-cli 1.5.3__py3-none-any.whl

scc_cli/templates/statusline.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+# SCC Status Line for Claude Code
+# Shows: Model | Git branch/worktree | Lines changed
+#
+# Install: scc statusline --install
+# This script receives JSON from Claude Code via stdin
+
+# Read JSON input from stdin
+input=$(cat)
+
+# Extract values using jq
+MODEL=$(echo "$input" | jq -r '.model.display_name // "Unknown"')
+CURRENT_DIR=$(echo "$input" | jq -r '.workspace.current_dir // "."')
+PROJECT_DIR=$(echo "$input" | jq -r '.workspace.project_dir // "."')
+LINES_ADDED=$(echo "$input" | jq -r '.cost.total_lines_added // 0')
+LINES_REMOVED=$(echo "$input" | jq -r '.cost.total_lines_removed // 0')
+
+# Colors
+CYAN="\033[36m"
+GREEN="\033[32m"
+RED="\033[31m"
+MAGENTA="\033[35m"
+YELLOW="\033[33m"
+WHITE="\033[1;37m"
+DIM="\033[2m"
+RESET="\033[0m"
+
+# Git information
+GIT_INFO=""
+cd "$CURRENT_DIR" 2>/dev/null || cd "$PROJECT_DIR" 2>/dev/null
+
+if git rev-parse --git-dir > /dev/null 2>&1; then
+    # Get branch name
+    BRANCH=$(git branch --show-current 2>/dev/null)
+    if [ -z "$BRANCH" ]; then
+        # Detached HEAD - show short SHA
+        BRANCH=$(git rev-parse --short HEAD 2>/dev/null || echo "detached")
+    fi
+
+    # Check if we're in a worktree
+    GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
+
+    if [[ "$GIT_DIR" == *".git/worktrees/"* ]]; then
+        # In a worktree - show ⎇ icon
+        WORKTREE_NAME=$(basename "$(dirname "$GIT_DIR")" 2>/dev/null)
+        GIT_INFO="${MAGENTA}⎇ ${WORKTREE_NAME}${RESET}:${CYAN}${BRANCH}${RESET}"
+    else
+        # Regular repo - show 🌿 icon
+        GIT_INFO="${CYAN}🌿 ${BRANCH}${RESET}"
+    fi
+
+    # Check for uncommitted changes
+    if ! git diff --quiet 2>/dev/null || ! git diff --cached --quiet 2>/dev/null; then
+        GIT_INFO="${GIT_INFO}${YELLOW}*${RESET}"
+    fi
+fi
+
+# Lines changed (only show if any changes made)
+LINES_INFO=""
+if [ "$LINES_ADDED" -gt 0 ] || [ "$LINES_REMOVED" -gt 0 ]; then
+    LINES_INFO=" ${DIM}|${RESET} ${GREEN}+${LINES_ADDED}${RESET} ${RED}-${LINES_REMOVED}${RESET}"
+fi
+
+# Build the status line
+# Format: [Model] 🌿 branch* | +156 -23
+OUTPUT="${WHITE}[${MODEL}]${RESET}"
+
+if [ -n "$GIT_INFO" ]; then
+    OUTPUT="${OUTPUT} ${GIT_INFO}"
+fi
+
+OUTPUT="${OUTPUT}${LINES_INFO}"
+
+# Output (printf handles escape codes)
+printf "%b\n" "$OUTPUT"

scc_cli/theme.py

@@ -0,0 +1,348 @@
+"""Design tokens and theme configuration for SCC CLI.
+
+This module is the SINGLE SOURCE OF TRUTH for all visual constants.
+It must remain a LEAF MODULE with no imports from dashboard, list_screen,
+or other UI modules to prevent circular dependencies.
+
+Contains:
+- Colors: Semantic color names for panels, text, and borders
+- Borders: Panel border style mappings (derived from Colors)
+- Indicators: Status symbols with ASCII fallbacks
+- Spinners: Contextual spinner names for different operations
+- get_scc_theme(): Lazy-loaded Rich Theme for semantic style names
+
+Usage:
+    from scc_cli.theme import Colors, Borders, Indicators, get_scc_theme
+
+    # Use semantic names instead of hardcoded colors:
+    border_style=Borders.PANEL_SUCCESS  # instead of "green"
+
+    # Use indicators with fallbacks:
+    symbol = Indicators.get("PASS")  # returns "✓" or "OK"
+
+    # Apply theme to console:
+    console = Console(theme=get_scc_theme())
+    console.print("[scc.success]✓ Passed[/scc.success]")
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import TextIO
+
+    from rich.theme import Theme
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Unicode Detection (internal, no external dependencies)
+# ═══════════════════════════════════════════════════════════════════════════════
+# NOTE: This logic is kept in sync with console.py's _supports_unicode_for_stream.
+# Duplicated here to keep theme.py a leaf module with no UI imports.
+
+
+def _supports_unicode_for_stream(stream: "TextIO") -> bool:
+    """Check if a stream supports Unicode characters.
+
+    This is stream-aware (matching _supports_colors_for_stream pattern in console.py)
+    to handle cases where different streams have different encodings.
+
+    Args:
+        stream: A file-like object with an 'encoding' attribute.
+
+    Returns:
+        True if UTF-8 encoding is available on the stream.
+    """
+    encoding = getattr(stream, "encoding", None) or ""
+    if encoding.lower() in ("utf-8", "utf8"):
+        return True
+
+    # Check locale environment variables as fallback (LC_ALL > LC_CTYPE > LANG)
+    locale_var = (
+        os.environ.get("LC_ALL") or os.environ.get("LC_CTYPE") or os.environ.get("LANG", "")
+    )
+    return "utf-8" in locale_var.lower() or "utf8" in locale_var.lower()
+
+
+def _supports_unicode() -> bool:
+    """Check if stderr supports Unicode characters.
+
+    IMPORTANT: Defaults to stderr since that's where Rich UI renders.
+    This avoids false negatives when stdout is piped (e.g., `scc ... | jq`).
+
+    For explicit stream checking, use _supports_unicode_for_stream().
+
+    Returns:
+        True if UTF-8 encoding is available on stderr.
+    """
+    return _supports_unicode_for_stream(sys.stderr)
+
+
+# Cached at module load time for consistent behavior.
+# IMPORTANT: In UI code, prefer passing `unicode=caps.unicode` explicitly
+# to Indicators.get() and get_brand_header() rather than relying on this default.
+_UNICODE_SUPPORTED: bool = _supports_unicode()
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Color Definitions
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+class Colors:
+    """Semantic color names for the SCC CLI.
+
+    All color values are Rich-compatible color strings.
+    Use these instead of hardcoded color names for consistency.
+
+    Example:
+        panel = Panel(content, border_style=Colors.SUCCESS)
+    """
+
+    # Brand colors
+    BRAND = "cyan"
+    BRAND_BOLD = "bold cyan"
+
+    # Semantic colors
+    SUCCESS = "green"
+    SUCCESS_BOLD = "bold green"
+    WARNING = "yellow"
+    WARNING_BOLD = "bold yellow"
+    ERROR = "red"
+    ERROR_BOLD = "bold red"
+    INFO = "blue"
+    INFO_BOLD = "bold blue"
+
+    # Text colors
+    PRIMARY = "white"
+    SECONDARY = "dim"
+    MUTED = "dim white"
+
+    # State colors
+    RUNNING = "green"
+    STOPPED = "dim"
+    PAUSED = "yellow"
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Panel Border Styles
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+class Borders:
+    """Panel border styles for consistent UI.
+
+    Maps semantic panel types to their border colors.
+    All values derive from Colors to maintain single source of truth.
+    Use with Panel(..., border_style=Borders.PANEL_SUCCESS).
+
+    Example:
+        panel = Panel(content, border_style=Borders.PANEL_INFO)
+    """
+
+    # Panel borders (derived from Colors - single source of truth)
+    PANEL_INFO = Colors.BRAND  # cyan
+    PANEL_SUCCESS = Colors.SUCCESS  # green
+    PANEL_WARNING = Colors.WARNING  # yellow
+    PANEL_ERROR = Colors.ERROR  # red
+    PANEL_NEUTRAL = Colors.INFO  # blue
+    PANEL_MUTED = Colors.SECONDARY  # dim
+
+    # Footer separator character (width computed at render time via console.width)
+    FOOTER_SEPARATOR = "─" if _UNICODE_SUPPORTED else "-"
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Status Indicators
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+class Indicators:
+    """Status indicator symbols with ASCII fallbacks.
+
+    Use get() method to automatically select Unicode or ASCII based on
+    terminal capabilities detected at module load.
+
+    Example:
+        symbol = Indicators.get("PASS")  # "✓" or "OK"
+        print(f"{Indicators.get('RUNNING')} Container active")
+    """
+
+    # Mapping of indicator name -> (unicode, ascii)
+    _SYMBOLS: dict[str, tuple[str, str]] = {
+        # Success/failure
+        "PASS": ("✓", "OK"),
+        "FAIL": ("✗", "FAIL"),
+        "CHECK": ("✓", "[x]"),
+        "CROSS": ("✗", "[!]"),
+        # Warning/info
+        "WARNING": ("!", "!"),
+        "INFO": ("i", "i"),
+        # Status
+        "RUNNING": ("●", "[*]"),
+        "STOPPED": ("○", "[ ]"),
+        "PAUSED": ("◐", "[~]"),
+        # Navigation
+        "CURSOR": ("❯", ">"),
+        "TEXT_CURSOR": ("▏", "|"),
+        "ARROW": ("→", "->"),
+        "BULLET": ("•", "*"),
+        "SCROLL_UP": ("↑", "^"),
+        "SCROLL_DOWN": ("↓", "v"),
+        # Progress
+        "PENDING": ("⏳", "..."),
+        "SPINNER": ("◌", "o"),
+        # Layout elements
+        "INFO_ICON": ("ℹ", "i"),  # Circled info icon for hints
+        "SEARCH_ICON": ("🔍", "[?]"),  # Search/filter indicator
+        "VERTICAL_LINE": ("│", "|"),  # Table column separator
+        "HORIZONTAL_LINE": ("─", "-"),  # Section separator
+    }
+
+    @classmethod
+    def get(cls, name: str, *, unicode: bool | None = None) -> str:
+        """Get indicator symbol with automatic fallback.
+
+        Args:
+            name: Indicator name (e.g., "PASS", "RUNNING").
+            unicode: Override unicode detection. If None, uses module default.
+
+        Returns:
+            Unicode or ASCII symbol based on terminal capabilities.
+
+        Raises:
+            KeyError: If indicator name is not found.
+        """
+        if name not in cls._SYMBOLS:
+            raise KeyError(f"Unknown indicator: {name}")
+
+        use_unicode = unicode if unicode is not None else _UNICODE_SUPPORTED
+        unicode_char, ascii_char = cls._SYMBOLS[name]
+        return unicode_char if use_unicode else ascii_char
+
+    @classmethod
+    def has(cls, name: str) -> bool:
+        """Check if an indicator name exists.
+
+        Use this to safely check before calling get() if you want to
+        avoid KeyError exceptions.
+
+        Args:
+            name: Indicator name to check.
+
+        Returns:
+            True if the indicator exists, False otherwise.
+        """
+        return name in cls._SYMBOLS
+
+    @classmethod
+    def all_names(cls) -> list[str]:
+        """Get all available indicator names."""
+        return list(cls._SYMBOLS.keys())
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Spinner Names
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+class Spinners:
+    """Contextual spinner names for different operation types.
+
+    All values are valid Rich spinner names.
+    See: https://rich.readthedocs.io/en/stable/reference/spinner.html
+
+    Example:
+        with console.status("Building...", spinner=Spinners.BUILD):
+            build_project()
+    """
+
+    # Default spinner
+    DEFAULT = "dots"
+
+    # Context-specific spinners
+    DOCKER = "dots12"  # Docker/container operations
+    NETWORK = "dots8Bit"  # Network/fetch operations
+    BUILD = "bouncingBar"  # Build/compile operations
+    SEARCH = "point"  # Search/scan operations
+    SETUP = "arc"  # Setup/initialization
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Rich Theme Definition
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Delayed import to keep module load fast when Theme isn't needed
+_theme_instance: Theme | None = None
+
+
+def get_scc_theme() -> Theme:
+    """Get the SCC Rich Theme instance (lazy-loaded).
+
+    Returns:
+        Rich Theme with semantic style names.
+
+    Example:
+        console = Console(theme=get_scc_theme())
+        console.print("[scc.success]✓ Passed[/scc.success]")
+    """
+    global _theme_instance
+    if _theme_instance is None:
+        from rich.theme import Theme
+
+        _theme_instance = Theme(
+            {
+                # Brand
+                "scc.brand": Colors.BRAND,
+                "scc.brand.bold": Colors.BRAND_BOLD,
+                # Semantic
+                "scc.success": Colors.SUCCESS,
+                "scc.success.bold": Colors.SUCCESS_BOLD,
+                "scc.warning": Colors.WARNING,
+                "scc.warning.bold": Colors.WARNING_BOLD,
+                "scc.error": Colors.ERROR,
+                "scc.error.bold": Colors.ERROR_BOLD,
+                "scc.info": Colors.INFO,
+                "scc.info.bold": Colors.INFO_BOLD,
+                # Text
+                "scc.primary": Colors.PRIMARY,
+                "scc.secondary": Colors.SECONDARY,
+                "scc.muted": Colors.MUTED,
+                # Status
+                "scc.running": Colors.RUNNING,
+                "scc.stopped": Colors.STOPPED,
+                "scc.paused": Colors.PAUSED,
+            }
+        )
+    return _theme_instance
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# ASCII Art Branding (Optional)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+def get_brand_header(*, unicode: bool | None = None) -> str:
+    """Get minimal brand header for --version and doctor output.
+
+    Args:
+        unicode: Override unicode detection. If None, uses module default.
+
+    Returns:
+        Brand header string with proper box-drawing characters.
+    """
+    use_unicode = unicode if unicode is not None else _UNICODE_SUPPORTED
+
+    if use_unicode:
+        return """\
+╭───────────────────────────────────────╮
+│  SCC  Sandboxed Claude CLI            │
+╰───────────────────────────────────────╯"""
+    else:
+        return """\
++---------------------------------------+
+|  SCC  Sandboxed Claude CLI            |
++---------------------------------------+"""

scc_cli/ui/__init__.py

@@ -0,0 +1,154 @@
+"""SCC Interactive UI Package.
+
+Public API for building interactive terminal experiences that share
+consistent chrome, keybindings, and behavior patterns.
+
+This package provides:
+- Gate: Interactivity policy enforcement (JSON mode, CI detection, TTY checks)
+- Pickers: High-level selection wrappers for domain objects
+- ListScreen: Core navigation engine for building custom screens
+- Dashboard: Tabbed navigation for the main SCC view
+
+Usage Tiers:
+
+Tier 1 - High-level (recommended for CLI commands):
+    >>> from scc_cli.ui import InteractivityContext, pick_team, TeamSwitchRequested
+    >>> ctx = InteractivityContext.create(json_mode=False)
+    >>> if ctx.allows_prompt():
+    ...     try:
+    ...         team = pick_team(teams)
+    ...     except TeamSwitchRequested:
+    ...         # Handle team switch request
+    ...         pass
+
+Tier 2 - Advanced building blocks (supported, but may evolve):
+    >>> from scc_cli.ui import ListScreen, ListItem, ListMode
+    >>> items = [ListItem(value=x, label=x.name) for x in data]
+    >>> screen = ListScreen(items, title="Custom Picker")
+    >>> selected = screen.run()
+
+Internal modules (not part of public API, may change without notice):
+    - chrome: Layout rendering primitives (Chrome, ChromeConfig, FooterHint)
+    - keys: Key mapping internals (Action, ActionType, KeyReader)
+    Import directly from submodules if needed:
+    >>> from scc_cli.ui.keys import ActionType  # Internal use only
+    >>> from scc_cli.ui.chrome import Chrome    # Internal use only
+"""
+
+from __future__ import annotations
+
+# Dashboard: Main tabbed navigation view
+from .dashboard import run_dashboard
+
+# =============================================================================
+# Tier 1: High-level API (recommended for most uses)
+# =============================================================================
+# Gate: Interactivity policy enforcement
+from .gate import (
+    InteractivityContext,
+    InteractivityMode,
+    is_interactive_allowed,
+    require_selection_or_prompt,
+)
+
+# Git Interactive: User-facing workflows with console output
+from .git_interactive import (
+    check_branch_safety,
+    cleanup_worktree,
+    clone_repo,
+    create_worktree,
+    install_dependencies,
+    install_hooks,
+    list_worktrees,
+)
+
+# Git Rendering: Pure display functions for git data
+from .git_render import (
+    format_git_status,
+    render_worktrees,
+    render_worktrees_table,
+)
+
+# Help: Mode-aware help overlay (user-facing)
+from .help import (
+    HelpMode,
+    show_help_overlay,
+)
+
+# =============================================================================
+# Tier 2: Advanced building blocks (supported, but may evolve)
+# =============================================================================
+# ListScreen: Core navigation engine
+from .list_screen import (
+    ListItem,
+    ListMode,
+    ListScreen,
+    ListState,
+)
+
+# Pickers: Domain-specific selection workflows
+from .picker import (
+    TeamSwitchRequested,
+    pick_container,
+    pick_containers,
+    pick_context,
+    pick_session,
+    pick_team,
+    pick_worktree,
+)
+
+# Prompts: Simple Rich-based user input utilities
+from .prompts import (
+    prompt_custom_workspace,
+    prompt_repo_url,
+    render_error,
+    select_session,
+    select_team,
+)
+
+# =============================================================================
+# Package metadata
+# =============================================================================
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Tier 1: High-level API
+    "InteractivityContext",
+    "InteractivityMode",
+    "is_interactive_allowed",
+    "require_selection_or_prompt",
+    "TeamSwitchRequested",
+    "pick_container",
+    "pick_containers",
+    "pick_context",
+    "pick_session",
+    "pick_team",
+    "pick_worktree",
+    "run_dashboard",
+    "HelpMode",
+    "show_help_overlay",
+    # Tier 2: Advanced building blocks
+    "ListItem",
+    "ListMode",
+    "ListScreen",
+    "ListState",
+    # Prompts: Simple Rich-based user input utilities
+    "prompt_custom_workspace",
+    "prompt_repo_url",
+    "render_error",
+    "select_session",
+    "select_team",
+    # Git Rendering: Pure display functions for git data
+    "format_git_status",
+    "render_worktrees",
+    "render_worktrees_table",
+    # Git Interactive: User-facing workflows with console output
+    "check_branch_safety",
+    "cleanup_worktree",
+    "clone_repo",
+    "create_worktree",
+    "install_dependencies",
+    "install_hooks",
+    "list_worktrees",
+]

scc_cli/ui/branding.py

@@ -0,0 +1,68 @@
+"""Branding utilities for SCC CLI.
+
+This module provides minimal, professional branding elements for CLI output:
+- Version display headers
+- Doctor command headers
+- Unicode-safe fallbacks for all terminals
+
+The aesthetic is professional/minimal to suit enterprise team adoption.
+"""
+
+from __future__ import annotations
+
+from ..platform import supports_unicode
+
+
+def get_version_header(version: str) -> str:
+    """Generate version display header with unicode/ASCII fallback.
+
+    Args:
+        version: The version string to display (e.g., "1.4.0").
+
+    Returns:
+        Formatted header string with box-drawing or ASCII characters.
+    """
+    # Pad version to ensure consistent width (assumes version <= 10 chars)
+    v_padded = f"v{version}".ljust(10)
+
+    if supports_unicode():
+        return (
+            "╭───────────────────────────────────────╮\n"
+            f"│  [cyan bold]SCC[/cyan bold]  Sandboxed Claude CLI  [dim]{v_padded}[/dim] │\n"
+            "╰───────────────────────────────────────╯"
+        )
+    else:
+        return (
+            "+---------------------------------------+\n"
+            f"|  [cyan bold]SCC[/cyan bold]  Sandboxed Claude CLI  [dim]{v_padded}[/dim] |\n"
+            "+---------------------------------------+"
+        )
+
+
+def get_doctor_header() -> str:
+    """Generate doctor command header with unicode/ASCII fallback.
+
+    Returns:
+        Formatted header string for doctor output.
+    """
+    if supports_unicode():
+        return (
+            "╭───────────────────────────────────────╮\n"
+            "│  [cyan bold]SCC Doctor[/cyan bold]  System Health Check     │\n"
+            "╰───────────────────────────────────────╯"
+        )
+    else:
+        return (
+            "+---------------------------------------+\n"
+            "|  [cyan bold]SCC Doctor[/cyan bold]  System Health Check      |\n"
+            "+---------------------------------------+"
+        )
+
+
+def get_brand_tagline() -> str:
+    """Get the brand tagline for SCC.
+
+    Returns:
+        The official tagline string.
+    """
+    return "Safe development environment manager for Claude Code"