scc-cli 1.5.3__py3-none-any.whl

scc_cli/core/errors.py

@@ -0,0 +1,297 @@
+"""
+Typed exceptions for SCC - Sandboxed Claude CLI.
+
+Error handling philosophy: "One message, one action"
+- Each error has a clear user_message (what went wrong)
+- Each error has a suggested_action (what to do next)
+- Debug context is available with --debug flag
+
+Exit codes:
+- 0: Success
+- 2: Invalid usage / bad input
+- 3: Missing prerequisites (Docker, Git)
+- 4: External tool failure (docker/git command failed)
+- 5: Internal error (bug)
+"""
+
+import shlex
+from dataclasses import dataclass, field
+
+
+@dataclass
+class SCCError(Exception):
+    """Base error with user-friendly messaging."""
+
+    user_message: str
+    suggested_action: str = ""
+    debug_context: str | None = None
+    exit_code: int = 1
+
+    def __str__(self) -> str:
+        return self.user_message
+
+
+@dataclass
+class UsageError(SCCError):
+    """Invalid usage or bad input."""
+
+    exit_code: int = field(default=2, init=False)
+
+
+@dataclass
+class PrerequisiteError(SCCError):
+    """Docker/Git missing or wrong version."""
+
+    exit_code: int = field(default=3, init=False)
+
+
+@dataclass
+class DockerNotFoundError(PrerequisiteError):
+    """Docker is not installed or not in PATH."""
+
+    user_message: str = field(default="Docker is not installed or not in PATH")
+    suggested_action: str = field(
+        default="Install Docker Desktop from https://docker.com/products/docker-desktop"
+    )
+
+
+@dataclass
+class DockerVersionError(PrerequisiteError):
+    """Docker version is too old for sandbox feature."""
+
+    current_version: str = ""
+    required_version: str = "4.50.0"
+    user_message: str = field(default="")
+    suggested_action: str = field(
+        default="Update Docker Desktop from https://docker.com/products/docker-desktop"
+    )
+
+    def __post_init__(self) -> None:
+        if not self.user_message:
+            self.user_message = (
+                f"Docker Desktop {self.required_version}+ required for sandbox support\n"
+                f"Current: {self.current_version or 'unknown'} | Required: {self.required_version}+"
+            )
+
+
+@dataclass
+class SandboxNotAvailableError(PrerequisiteError):
+    """Docker sandbox feature is not available."""
+
+    user_message: str = field(default="Docker sandbox feature is not available")
+    suggested_action: str = field(
+        default="Ensure Docker Desktop is version 4.50+ and sandbox feature is enabled"
+    )
+
+
+@dataclass
+class GitNotFoundError(PrerequisiteError):
+    """Git is not installed or not in PATH."""
+
+    user_message: str = field(default="Git is not installed or not in PATH")
+    suggested_action: str = field(default="Install Git from https://git-scm.com/downloads")
+
+
+@dataclass
+class ToolError(SCCError):
+    """External tool (Docker/Git) command failed."""
+
+    exit_code: int = field(default=4, init=False)
+    command: str | None = None
+    stderr: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.command or self.stderr:
+            parts = []
+            if self.command:
+                parts.append(f"Command: {self.command}")
+            if self.stderr:
+                parts.append(f"Error: {self.stderr}")
+            self.debug_context = "\n".join(parts)
+
+
+@dataclass
+class WorkspaceError(ToolError):
+    """Invalid workspace path or clone failed."""
+
+    user_message: str = field(default="Workspace error")
+
+
+@dataclass
+class WorkspaceNotFoundError(WorkspaceError):
+    """Workspace path does not exist."""
+
+    path: str = ""
+    user_message: str = field(default="")
+    suggested_action: str = field(default="Check the path exists or create the directory")
+
+    def __post_init__(self) -> None:
+        super().__post_init__()
+        if not self.user_message and self.path:
+            self.user_message = f"Workspace not found: {self.path}"
+
+
+@dataclass
+class NotAGitRepoError(WorkspaceError):
+    """Path is not a git repository."""
+
+    path: str = ""
+    user_message: str = field(default="")
+    suggested_action: str = field(default="Initialize git with 'git init' or clone a repository")
+
+    def __post_init__(self) -> None:
+        super().__post_init__()
+        if not self.user_message and self.path:
+            self.user_message = f"Not a git repository: {self.path}"
+
+
+@dataclass
+class CloneError(WorkspaceError):
+    """Git clone failed."""
+
+    url: str = ""
+    user_message: str = field(default="")
+    suggested_action: str = field(default="Check the repository URL and your network connection")
+
+    def __post_init__(self) -> None:
+        super().__post_init__()
+        if not self.user_message and self.url:
+            self.user_message = f"Failed to clone repository: {self.url}"
+
+
+@dataclass
+class GitWorktreeError(ToolError):
+    """Worktree creation/cleanup failed."""
+
+    user_message: str = field(default="Git worktree operation failed")
+
+
+@dataclass
+class WorktreeExistsError(GitWorktreeError):
+    """Worktree already exists."""
+
+    path: str = ""
+    user_message: str = field(default="")
+    suggested_action: str = field(
+        default="Use existing worktree, remove it first, or choose a different name"
+    )
+
+    def __post_init__(self) -> None:
+        super().__post_init__()
+        if not self.user_message and self.path:
+            self.user_message = f"Worktree already exists: {self.path}"
+
+
+@dataclass
+class WorktreeCreationError(GitWorktreeError):
+    """Failed to create worktree."""
+
+    name: str = ""
+    user_message: str = field(default="")
+    suggested_action: str = field(
+        default="Check if the branch already exists or if there are uncommitted changes"
+    )
+
+    def __post_init__(self) -> None:
+        super().__post_init__()
+        if not self.user_message and self.name:
+            self.user_message = f"Failed to create worktree: {self.name}"
+
+
+@dataclass
+class SandboxLaunchError(ToolError):
+    """Docker sandbox failed to start."""
+
+    exit_code: int = field(default=5, init=False)
+    user_message: str = field(default="Failed to start Docker sandbox")
+    suggested_action: str = field(
+        default="Check Docker Desktop is running and has available resources"
+    )
+
+
+@dataclass
+class ContainerNotFoundError(ToolError):
+    """Container does not exist (for resume operations)."""
+
+    container_name: str = ""
+    user_message: str = field(default="")
+    suggested_action: str = field(
+        default="Start a new session or check 'scc list' for available containers"
+    )
+
+    def __post_init__(self) -> None:
+        super().__post_init__()
+        if not self.user_message and self.container_name:
+            self.user_message = f"Container not found: {self.container_name}"
+
+
+@dataclass
+class InternalError(SCCError):
+    """Internal error (bug in the CLI)."""
+
+    exit_code: int = field(default=5, init=False)
+    suggested_action: str = field(
+        default="Please report this issue at https://github.com/CCimen/scc/issues"
+    )
+
+
+@dataclass
+class ConfigError(SCCError):
+    """Configuration error."""
+
+    exit_code: int = field(default=2, init=False)
+    user_message: str = field(default="Configuration error")
+    suggested_action: str = field(default="Run 'scc config --show' to view current configuration")
+
+
+@dataclass
+class ProfileNotFoundError(ConfigError):
+    """Team profile not found."""
+
+    profile_name: str = ""
+    user_message: str = field(default="")
+    suggested_action: str = field(default="Run 'scc team list' to see available profiles")
+
+    def __post_init__(self) -> None:
+        if not self.user_message and self.profile_name:
+            self.user_message = f"Team profile not found: {self.profile_name}"
+
+
+@dataclass
+class PolicyViolationError(ConfigError):
+    """Security policy violation during config processing.
+
+    Raised when a plugin, MCP server, or other item is blocked by
+    organization security policies.
+    """
+
+    item: str = ""
+    blocked_by: str = ""
+    item_type: str = "plugin"  # Default to plugin
+    user_message: str = field(default="")
+    suggested_action: str = field(default="")
+
+    def __post_init__(self) -> None:
+        if not self.user_message and self.item:
+            if self.blocked_by:
+                self.user_message = (
+                    f"Security policy violation: '{self.item}' is blocked "
+                    f"by pattern '{self.blocked_by}'"
+                )
+            else:
+                self.user_message = f"Security policy violation: '{self.item}' is blocked"
+
+        # Generate fix-it command for suggested action (inline to keep core/ dependency-free)
+        if not self.suggested_action and self.item:
+            type_to_flag = {
+                "plugin": "--allow-plugin",
+                "mcp_server": "--allow-mcp",
+                "base_image": "--allow-image",
+            }
+            flag = type_to_flag.get(self.item_type, f"--allow-{self.item_type}")
+            quoted_item = shlex.quote(self.item)
+            cmd = (
+                "scc exceptions create --policy --id INC-... "
+                f'{flag} {quoted_item} --ttl 8h --reason "..."'
+            )
+            self.suggested_action = f"To request a policy exception (requires PR approval): {cmd}"

scc_cli/core/exit_codes.py

@@ -0,0 +1,91 @@
+"""
+Exit codes for SCC CLI.
+
+Standardized exit codes following Unix conventions with semantic meaning.
+All commands MUST use these constants for consistency.
+
+Exit Code Semantics:
+  0: Success - command completed successfully
+  1: Not Found - target not found (worktree name, session id, workspace missing)
+  2: Usage Error - bad flags, invalid inputs, missing required args
+  3: Config Error - config problems, network errors
+  4: Tool Error - external tool failed (git error, docker error, not a git repo)
+  5: Prerequisite Error - missing tools (Docker, Git not installed)
+  6: Governance Error - blocked by policy
+  130: Cancelled - user cancelled operation (SIGINT)
+
+Preferred Usage:
+  - Use specific codes (EXIT_NOT_FOUND, EXIT_TOOL, EXIT_CONFIG, etc.)
+  - Avoid EXIT_ERROR - use a specific code instead
+  - EXIT_VALIDATION maps to EXIT_TOOL (validation is a tool concern)
+  - EXIT_INTERNAL maps to EXIT_PREREQ (internal errors are system issues)
+
+Note: Click/Typer argument parsing errors (EXIT_USAGE) occur before
+commands run, so they emit to stderr without JSON envelope.
+"""
+
+# Success
+EXIT_SUCCESS = 0  # Command completed successfully
+
+# Primary exit codes (1-6) - use these in new code
+EXIT_NOT_FOUND = 1  # Target not found (worktree, session, workspace)
+EXIT_USAGE = 2  # Invalid usage/arguments (Click default)
+EXIT_CONFIG = 3  # Config or network error
+EXIT_TOOL = 4  # External tool failed (git error, docker error, not a git repo)
+EXIT_PREREQ = 5  # Prerequisites not met (Docker, Git not installed)
+EXIT_GOVERNANCE = 6  # Blocked by governance policy
+
+# Cancellation (SIGINT convention)
+EXIT_CANCELLED = 130  # User cancelled operation (SIGINT)
+
+# Deprecated aliases - prefer specific codes above
+# These exist for backward compatibility and will be removed in a future version
+EXIT_ERROR = EXIT_NOT_FOUND  # DEPRECATED: Use EXIT_NOT_FOUND or a specific code
+EXIT_VALIDATION = EXIT_TOOL  # DEPRECATED: Use EXIT_TOOL instead
+EXIT_INTERNAL = EXIT_PREREQ  # DEPRECATED: Use EXIT_PREREQ instead
+
+# Map exception types to exit codes (for json_command decorator)
+# Note: Import from errors module only when needed to avoid circular imports
+EXIT_CODE_MAP = {
+    # Tool errors (external commands failed)
+    "ToolError": EXIT_TOOL,
+    "WorkspaceError": EXIT_TOOL,
+    "WorkspaceNotFoundError": EXIT_TOOL,
+    "NotAGitRepoError": EXIT_TOOL,
+    "GitWorktreeError": EXIT_TOOL,
+    # Config errors
+    "ConfigError": EXIT_CONFIG,
+    "ProfileNotFoundError": EXIT_CONFIG,
+    # Validation errors (treated as tool errors)
+    "ValidationError": EXIT_TOOL,
+    # Governance errors
+    "PolicyViolationError": EXIT_GOVERNANCE,
+    # Prerequisite errors
+    "PrerequisiteError": EXIT_PREREQ,
+    "DockerNotFoundError": EXIT_PREREQ,
+    "GitNotFoundError": EXIT_PREREQ,
+    # Internal errors (treated as prerequisite/system errors)
+    "InternalError": EXIT_PREREQ,
+    # Usage errors
+    "UsageError": EXIT_USAGE,
+}
+
+
+def get_exit_code_for_exception(exc: Exception) -> int:
+    """Return the appropriate exit code for an exception type.
+
+    Walk up the exception's MRO to find a matching type in EXIT_CODE_MAP.
+    Fall back to EXIT_NOT_FOUND if no specific mapping exists.
+
+    Args:
+        exc: The exception instance to map.
+
+    Returns:
+        The standardized exit code for the exception type.
+    """
+    for cls in type(exc).__mro__:
+        if cls.__name__ in EXIT_CODE_MAP:
+            return EXIT_CODE_MAP[cls.__name__]
+
+    # Fallback for unmapped exceptions
+    return EXIT_NOT_FOUND

scc_cli/core/workspace.py

@@ -0,0 +1,57 @@
+"""Workspace resolution domain types.
+
+This module contains pure data types for workspace resolution results.
+These types are used by the services layer to communicate resolution outcomes.
+
+Key concepts:
+- WR (workspace_root): The stable identity for sessions (git root or .scc.yaml parent)
+- ED (entry_dir): Where the user invoked from (preserved for container cwd)
+- MR (mount_root): Host path to mount into the container (may expand for worktrees)
+- CW (container_workdir): The working directory inside the container (mirrored host path)
+
+All paths in ResolverResult are absolute and resolved (symlinks expanded).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class ResolverResult:
+    """Complete workspace resolution output.
+
+    All paths are absolute and resolved (symlinks expanded via resolve()).
+
+    Attributes:
+        workspace_root: WR - stable identity for sessions (git root or .scc.yaml parent)
+        entry_dir: ED - where user invoked from
+        mount_root: MR - host path mounted into container
+        container_workdir: CW - mirrored host absolute path inside container
+        is_auto_detected: True if found via git/.scc.yaml (not explicit --workspace)
+        is_suspicious: Whether WR is in a suspicious location (home, /tmp, etc.)
+        is_mount_expanded: Whether MR was expanded for worktree gitdir access
+        reason: Debug explanation of how resolution was performed
+    """
+
+    workspace_root: Path  # WR - stable identity for sessions
+    entry_dir: Path  # ED - where user invoked from
+    mount_root: Path  # MR - host path mounted into container
+    container_workdir: str  # CW - mirrored host absolute path
+    is_auto_detected: bool  # True if found via git/.scc.yaml
+    is_suspicious: bool  # Whether WR is in a suspicious location
+    is_mount_expanded: bool = False  # Whether MR was expanded for worktree
+    reason: str = ""  # Debug explanation
+
+    def is_auto_eligible(self) -> bool:
+        """Whether this result is eligible for auto-launch.
+
+        Auto-launch requires:
+        1. Workspace was auto-detected (not from explicit --workspace arg)
+        2. Workspace is not in a suspicious location (home, /tmp, system dirs)
+
+        Returns:
+            True if workspace can be auto-launched without user confirmation.
+        """
+        return self.is_auto_detected and not self.is_suspicious

scc_cli/deprecation.py

@@ -0,0 +1,54 @@
+"""Provide deprecation warning infrastructure.
+
+Provide consistent deprecation warnings that respect output modes.
+Suppress warnings in JSON mode to maintain clean machine output.
+
+Usage:
+    from scc_cli.deprecation import warn_deprecated
+
+    # In command handler:
+    warn_deprecated("old-cmd", "new-cmd", remove_version="2.0")
+"""
+
+import os
+
+from rich.console import Console
+
+from .output_mode import is_json_mode
+
+# Stderr console for deprecation warnings
+_stderr_console = Console(stderr=True)
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Deprecation Warnings
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+def warn_deprecated(
+    old_cmd: str,
+    new_cmd: str,
+    remove_version: str = "2.0",
+) -> None:
+    """Print deprecation warning to stderr.
+
+    Warnings are suppressed when:
+    - JSON output mode is active (clean machine output)
+    - SCC_NO_DEPRECATION_WARN=1 environment variable is set
+
+    Args:
+        old_cmd: The deprecated command/option name
+        new_cmd: The replacement command/option name
+        remove_version: The version when old_cmd will be removed
+    """
+    # Suppress in JSON mode for clean machine output
+    if is_json_mode():
+        return
+
+    # Allow users to suppress deprecation warnings
+    if os.environ.get("SCC_NO_DEPRECATION_WARN") == "1":
+        return
+
+    _stderr_console.print(
+        f"[yellow]DEPRECATION:[/yellow] '{old_cmd}' is deprecated. "
+        f"Use '{new_cmd}' instead. Will be removed in v{remove_version}."
+    )

scc_cli/deps.py

@@ -0,0 +1,189 @@
+"""
+Provide dependency detection and installation for project workspaces.
+
+Offer opt-in dependency installation that:
+- Is opt-in (--install-deps flag)
+- Never blocks scc start by default
+- Supports strict mode for CI/automation that needs hard failures
+
+Supported package managers:
+- JavaScript: npm, pnpm, yarn, bun
+- Python: poetry, uv, pip
+- Java: maven, gradle
+"""
+
+import subprocess
+from pathlib import Path
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Exception Classes
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+class DependencyInstallError(Exception):
+    """Raised when dependency installation fails in strict mode."""
+
+    def __init__(self, package_manager: str, message: str):
+        self.package_manager = package_manager
+        self.message = message
+        super().__init__(f"{package_manager}: {message}")
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Package Manager Detection
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Detection order matters - lock files take priority over manifest files
+DETECTION_ORDER = [
+    # JavaScript lock files (priority)
+    ("pnpm-lock.yaml", "pnpm"),
+    ("yarn.lock", "yarn"),
+    ("bun.lockb", "bun"),
+    ("package-lock.json", "npm"),
+    # Python lock files (priority)
+    ("uv.lock", "uv"),
+    ("poetry.lock", "poetry"),
+    # Java build files
+    ("pom.xml", "maven"),
+    ("build.gradle.kts", "gradle"),
+    ("build.gradle", "gradle"),
+    # Fallback manifest files
+    ("package.json", "npm"),  # JS fallback
+    ("pyproject.toml", "pip"),  # Python fallback
+    ("requirements.txt", "pip"),
+]
+
+
+def detect_package_manager(workspace: Path) -> str | None:
+    """Detect the package manager from project files.
+
+    Base detection on the presence of lock files and manifest files.
+    Give lock files priority over manifest files.
+
+    Args:
+        workspace: Path to the project workspace
+
+    Returns:
+        Package manager name or None if not detected.
+        Possible values: 'npm', 'pnpm', 'yarn', 'bun', 'poetry', 'uv', 'pip', 'maven', 'gradle'
+    """
+    for filename, package_manager in DETECTION_ORDER:
+        if (workspace / filename).exists():
+            return package_manager
+
+    return None
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Install Commands
+# ═══════════════════════════════════════════════════════════════════════════════
+
+INSTALL_COMMANDS = {
+    # JavaScript
+    "npm": ["npm", "install"],
+    "pnpm": ["pnpm", "install"],
+    "yarn": ["yarn", "install"],
+    "bun": ["bun", "install"],
+    # Python
+    "poetry": ["poetry", "install"],
+    "uv": ["uv", "sync"],
+    "pip": ["pip", "install", "-r", "requirements.txt"],
+    # Java
+    "maven": ["mvn", "install", "-DskipTests"],
+    "gradle": ["gradle", "dependencies"],
+}
+
+
+def get_install_command(package_manager: str) -> list[str] | None:
+    """Return the install command for a package manager.
+
+    Args:
+        package_manager: Name of the package manager
+
+    Returns:
+        List of command arguments or None if unknown
+    """
+    return INSTALL_COMMANDS.get(package_manager)
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Dependency Installation
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+def install_dependencies(
+    workspace: Path,
+    package_manager: str,
+    strict: bool = False,
+) -> bool:
+    """Run the dependency installation command.
+
+    Args:
+        workspace: Path to project workspace
+        package_manager: Detected package manager name
+        strict: If True, raise on failure. If False (default), warn and continue.
+
+    Returns:
+        True if install succeeded, False if failed (only when strict=False)
+
+    Raises:
+        DependencyInstallError: If strict=True and installation fails
+    """
+    cmd = get_install_command(package_manager)
+
+    if cmd is None:
+        if strict:
+            raise DependencyInstallError(package_manager, "Unknown package manager")
+        return False
+
+    try:
+        result = subprocess.run(
+            cmd,
+            cwd=workspace,
+            capture_output=True,
+            text=True,
+        )
+
+        if result.returncode == 0:
+            return True
+
+        # Installation failed
+        error_msg = result.stderr or result.stdout or "Unknown error"
+        if strict:
+            raise DependencyInstallError(package_manager, f"Command failed: {error_msg}")
+
+        return False
+
+    except FileNotFoundError:
+        # Package manager not installed
+        if strict:
+            raise DependencyInstallError(
+                package_manager,
+                f"'{cmd[0]}' not found. Is {package_manager} installed?",
+            )
+        return False
+
+
+def auto_install_dependencies(workspace: Path, strict: bool = False) -> bool:
+    """Detect the package manager and install dependencies.
+
+    Combine detection and installation as a convenience function.
+
+    Args:
+        workspace: Path to project workspace
+        strict: If True, raise on failure. If False (default), warn and continue.
+
+    Returns:
+        True if install succeeded, False if failed or no package manager detected
+
+    Raises:
+        DependencyInstallError: If strict=True and installation fails
+    """
+    package_manager = detect_package_manager(workspace)
+
+    if package_manager is None:
+        if strict:
+            raise DependencyInstallError("unknown", "No package manager detected")
+        return False
+
+    return install_dependencies(workspace, package_manager, strict=strict)