scc-cli 1.5.3__py3-none-any.whl

scc_cli/evaluation/__init__.py

@@ -0,0 +1,27 @@
+"""Evaluation layer for SCC exception system.
+
+Provide pure functions for evaluating configs and applying exceptions.
+All IO is isolated to the stores layer.
+"""
+
+from scc_cli.evaluation.apply_exceptions import (
+    apply_local_overrides,
+    apply_policy_exceptions,
+)
+from scc_cli.evaluation.evaluate import evaluate
+from scc_cli.evaluation.models import (
+    BlockedItem,
+    Decision,
+    DeniedAddition,
+    EvaluationResult,
+)
+
+__all__ = [
+    "BlockedItem",
+    "Decision",
+    "DeniedAddition",
+    "EvaluationResult",
+    "apply_local_overrides",
+    "apply_policy_exceptions",
+    "evaluate",
+]

scc_cli/evaluation/apply_exceptions.py

@@ -0,0 +1,207 @@
+"""Apply exceptions to evaluation results.
+
+Contain the core exception application logic. All functions are pure (no IO)
+and operate on immutable data structures.
+
+Key rules:
+- apply_policy_exceptions() can override ANY block (security or delegation)
+- apply_local_overrides() can ONLY override DELEGATION blocks
+- Expired exceptions have no effect
+- Wildcard patterns (e.g., "jira-*") are supported
+"""
+
+from __future__ import annotations
+
+import fnmatch
+from datetime import datetime, timezone
+from typing import Literal
+
+from scc_cli.evaluation.models import (
+    Decision,
+    EvaluationResult,
+)
+from scc_cli.models.exceptions import AllowTargets, BlockReason
+from scc_cli.models.exceptions import Exception as SccException
+from scc_cli.utils.ttl import format_relative
+
+
+def _is_expired(exception: SccException) -> bool:
+    """Check if an exception has expired."""
+    try:
+        expires = datetime.fromisoformat(exception.expires_at.replace("Z", "+00:00"))
+        return expires <= datetime.now(timezone.utc)
+    except (ValueError, AttributeError):
+        return True  # Invalid expiration = expired
+
+
+def _matches_target(pattern: str, target: str) -> bool:
+    """Check if a pattern matches a target, supporting wildcards."""
+    # Exact match first
+    if pattern == target:
+        return True
+    # Wildcard match (fnmatch supports * and ?)
+    return fnmatch.fnmatch(target, pattern)
+
+
+def _get_allowed_targets(
+    allow: AllowTargets, target_type: Literal["plugin", "mcp_server", "base_image"]
+) -> list[str]:
+    """Get the list of allowed targets for a specific type."""
+    if target_type == "plugin":
+        return allow.plugins or []
+    elif target_type == "mcp_server":
+        return allow.mcp_servers or []
+    elif target_type == "base_image":
+        return allow.base_images or []
+    return []
+
+
+def _find_matching_exception(
+    target: str,
+    target_type: Literal["plugin", "mcp_server", "base_image"],
+    exceptions: list[SccException],
+) -> SccException | None:
+    """Find the first non-expired exception that matches the target.
+
+    Prefers exact matches over wildcard matches.
+    """
+    exact_match = None
+    wildcard_match = None
+
+    for exc in exceptions:
+        if _is_expired(exc):
+            continue
+
+        allowed = _get_allowed_targets(exc.allow, target_type)
+        for pattern in allowed:
+            if pattern == target:
+                exact_match = exc
+                break  # Exact match found, use it
+            elif _matches_target(pattern, target) and wildcard_match is None:
+                wildcard_match = exc
+
+        if exact_match:
+            break
+
+    return exact_match or wildcard_match
+
+
+def _calculate_expires_in(exception: SccException) -> str | None:
+    """Calculate the relative time until expiration."""
+    try:
+        expires = datetime.fromisoformat(exception.expires_at.replace("Z", "+00:00"))
+        return format_relative(expires)
+    except (ValueError, AttributeError):
+        return None
+
+
+def apply_policy_exceptions(
+    result: EvaluationResult,
+    exceptions: list[SccException],
+) -> EvaluationResult:
+    """Apply policy exceptions to an evaluation result.
+
+    Policy exceptions can override ANY block - both security blocks and
+    delegation denials. This is the first layer of exception application.
+
+    Args:
+        result: The current evaluation result
+        exceptions: List of policy exceptions to apply
+
+    Returns:
+        New EvaluationResult with matching items removed and decisions added
+    """
+    new_result = result.copy()
+
+    # Process blocked items (security blocks)
+    remaining_blocked = []
+    for blocked in result.blocked_items:
+        matching_exc = _find_matching_exception(blocked.target, blocked.target_type, exceptions)
+        if matching_exc:
+            # Create decision record
+            decision = Decision(
+                item=blocked.target,
+                item_type=blocked.target_type,
+                result="allowed",
+                reason="Policy exception applied",
+                source="policy",
+                exception_id=matching_exc.id,
+                expires_in=_calculate_expires_in(matching_exc),
+            )
+            new_result.decisions.append(decision)
+        else:
+            remaining_blocked.append(blocked)
+
+    new_result.blocked_items = remaining_blocked
+
+    # Process denied additions (delegation blocks)
+    remaining_denied = []
+    for denied in result.denied_additions:
+        matching_exc = _find_matching_exception(denied.target, denied.target_type, exceptions)
+        if matching_exc:
+            decision = Decision(
+                item=denied.target,
+                item_type=denied.target_type,
+                result="allowed",
+                reason="Policy exception applied",
+                source="policy",
+                exception_id=matching_exc.id,
+                expires_in=_calculate_expires_in(matching_exc),
+            )
+            new_result.decisions.append(decision)
+        else:
+            remaining_denied.append(denied)
+
+    new_result.denied_additions = remaining_denied
+
+    return new_result
+
+
+def apply_local_overrides(
+    result: EvaluationResult,
+    overrides: list[SccException],
+    source: Literal["repo", "user"],
+) -> EvaluationResult:
+    """Apply local overrides to an evaluation result.
+
+    Local overrides can ONLY override DELEGATION blocks (denied additions).
+    Security blocks are immutable to local overrides - this is a critical
+    security boundary.
+
+    Args:
+        result: The current evaluation result
+        overrides: List of local overrides to apply
+        source: Where the overrides came from ("repo" or "user")
+
+    Returns:
+        New EvaluationResult with matching denied additions removed and decisions added
+    """
+    new_result = result.copy()
+
+    # ONLY process denied additions (delegation blocks)
+    # Security blocks (blocked_items) are NEVER affected by local overrides
+    remaining_denied = []
+    for denied in result.denied_additions:
+        # Only delegation blocks can be overridden locally
+        if denied.reason != BlockReason.DELEGATION:
+            remaining_denied.append(denied)
+            continue
+
+        matching_exc = _find_matching_exception(denied.target, denied.target_type, overrides)
+        if matching_exc:
+            decision = Decision(
+                item=denied.target,
+                item_type=denied.target_type,
+                result="allowed",
+                reason="Local override applied",
+                source=source,
+                exception_id=matching_exc.id,
+                expires_in=_calculate_expires_in(matching_exc),
+            )
+            new_result.decisions.append(decision)
+        else:
+            remaining_denied.append(denied)
+
+    new_result.denied_additions = remaining_denied
+
+    return new_result

scc_cli/evaluation/evaluate.py

@@ -0,0 +1,97 @@
+"""Bridge function to convert EffectiveConfig to EvaluationResult.
+
+Provide the evaluate() function that converts the governance layer models
+(profiles.py) to the exception system models (evaluation/models.py) with
+proper BlockReason annotations.
+
+This is a pure function with no IO - all input comes from the EffectiveConfig
+parameter and output is a new EvaluationResult.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from scc_cli.evaluation.models import (
+    BlockedItem,
+    DeniedAddition,
+    EvaluationResult,
+)
+from scc_cli.models.exceptions import BlockReason
+
+if TYPE_CHECKING:
+    from scc_cli.profiles import EffectiveConfig
+
+
+def evaluate(config: EffectiveConfig) -> EvaluationResult:
+    """Convert EffectiveConfig to EvaluationResult with BlockReason annotations.
+
+    This function bridges the governance layer (profiles.py models) to the
+    exception system (evaluation/models.py) by converting:
+
+    - profiles.BlockedItem -> evaluation.BlockedItem with BlockReason.SECURITY
+    - profiles.DelegationDenied -> evaluation.DeniedAddition with BlockReason.DELEGATION
+
+    Args:
+        config: The EffectiveConfig from the profile merge process
+
+    Returns:
+        EvaluationResult with properly annotated blocked items and denied additions
+    """
+    blocked_items: list[BlockedItem] = []
+    denied_additions: list[DeniedAddition] = []
+
+    # Convert blocked items (security blocks)
+    for blocked in config.blocked_items:
+        target_type = _normalize_target_type(blocked.target_type)
+        message = f"Blocked by security pattern '{blocked.blocked_by}'"
+
+        blocked_items.append(
+            BlockedItem(
+                target=blocked.item,
+                target_type=target_type,
+                reason=BlockReason.SECURITY,
+                message=message,
+            )
+        )
+
+    # Convert denied additions (delegation denials)
+    for denied in config.denied_additions:
+        target_type = _normalize_target_type(denied.target_type)
+        # Use the original reason which contains useful context
+        message = denied.reason
+
+        denied_additions.append(
+            DeniedAddition(
+                target=denied.item,
+                target_type=target_type,
+                reason=BlockReason.DELEGATION,
+                message=message,
+            )
+        )
+
+    return EvaluationResult(
+        blocked_items=blocked_items,
+        denied_additions=denied_additions,
+        decisions=[],  # Decisions are populated by apply_*_exceptions functions
+        warnings=[],
+    )
+
+
+def _normalize_target_type(
+    target_type: str,
+) -> Literal["plugin", "mcp_server", "base_image"]:
+    """Normalize target_type to valid literal values.
+
+    Args:
+        target_type: The target type from profiles.py models
+
+    Returns:
+        Normalized target type literal
+    """
+    if target_type == "mcp_server":
+        return "mcp_server"
+    elif target_type == "base_image":
+        return "base_image"
+    else:
+        return "plugin"  # Default to plugin for unknown types

scc_cli/evaluation/models.py

@@ -0,0 +1,80 @@
+"""Define data models for the evaluation layer.
+
+Represent the results of evaluating configs and applying exceptions.
+All models are immutable and support the pure functional evaluation approach.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+from scc_cli.models.exceptions import BlockReason
+
+
+@dataclass(frozen=True)
+class BlockedItem:
+    """Represents an item blocked by security policy.
+
+    Security blocks can only be overridden by policy exceptions.
+    Local overrides have no effect on these.
+    """
+
+    target: str  # The blocked item (plugin name, MCP server, image ref)
+    target_type: Literal["plugin", "mcp_server", "base_image"]
+    reason: BlockReason  # Always SECURITY for blocked items
+    message: str  # Human-readable explanation
+
+
+@dataclass(frozen=True)
+class DeniedAddition:
+    """Represents an addition denied by delegation policy.
+
+    Delegation denials can be overridden by either policy exceptions
+    or local overrides (from repo or user stores).
+    """
+
+    target: str  # The denied item
+    target_type: Literal["plugin", "mcp_server", "base_image"]
+    reason: BlockReason  # Always DELEGATION for denied additions
+    message: str  # Human-readable explanation
+
+
+@dataclass(frozen=True)
+class Decision:
+    """Records a decision made when applying an exception.
+
+    Captures the full context of why an item was allowed or blocked,
+    including the exception that allowed it and when it expires.
+    """
+
+    item: str  # The item being decided on
+    item_type: Literal["plugin", "mcp_server", "base_image"]
+    result: Literal["allowed", "blocked", "denied"]
+    reason: str  # Human-readable explanation
+    source: Literal["policy", "org", "team", "project", "repo", "user"] | None
+    exception_id: str | None  # ID of the exception that allowed it
+    expires_in: str | None  # Relative time like "7h45m"
+
+
+@dataclass
+class EvaluationResult:
+    """The complete result of evaluating a config with exceptions applied.
+
+    Maintains lists of blocked items, denied additions, and decisions.
+    This is the primary data structure passed through the evaluation pipeline.
+    """
+
+    blocked_items: list[BlockedItem] = field(default_factory=list)
+    denied_additions: list[DeniedAddition] = field(default_factory=list)
+    decisions: list[Decision] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+    def copy(self) -> EvaluationResult:
+        """Create a shallow copy for immutable-style updates."""
+        return EvaluationResult(
+            blocked_items=list(self.blocked_items),
+            denied_additions=list(self.denied_additions),
+            decisions=list(self.decisions),
+            warnings=list(self.warnings),
+        )

scc_cli/git.py

@@ -0,0 +1,84 @@
+"""
+Git operations - backward-compatible facade.
+
+This module is a pure re-export facade after Phase 4 refactoring:
+- Data functions: services/git/ (core.py, branch.py, worktree.py, hooks.py)
+- Rendering functions: ui/git_render.py
+- Interactive UI functions: ui/git_interactive.py
+
+All symbols are re-exported for backward compatibility - existing imports
+like `from scc_cli.git import WorktreeInfo` continue to work.
+
+NO Rich imports in this module - that's a key acceptance criterion.
+"""
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Re-exports from services/git/ for backward compatibility
+# These imports ARE used - they're intentional re-exports for the public API
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Branch operations
+from .services.git.branch import (  # noqa: F401
+    PROTECTED_BRANCHES,
+    get_current_branch,
+    get_default_branch,
+    get_display_branch,
+    get_uncommitted_files,
+    is_protected_branch,
+    list_branches_without_worktrees,
+    sanitize_branch_name,
+)
+
+# Core operations
+from .services.git.core import (  # noqa: F401
+    check_git_available,
+    check_git_installed,
+    create_empty_initial_commit,
+    detect_workspace_root,
+    get_git_version,
+    has_commits,
+    has_remote,
+    init_repo,
+    is_git_repo,
+)
+
+# Hooks
+from .services.git.hooks import (  # noqa: F401
+    SCC_HOOK_MARKER,
+    _write_scc_hook,
+    install_pre_push_hook,
+    is_scc_hook,
+)
+
+# Worktree operations
+from .services.git.worktree import (  # noqa: F401
+    WorktreeInfo,
+    find_main_worktree,
+    find_worktree_by_query,
+    get_workspace_mount_path,
+    get_worktree_main_repo,
+    get_worktree_status,
+    is_worktree,
+)
+
+# Keep _get_worktrees_data as alias for backward compatibility
+from .services.git.worktree import get_worktrees_data as _get_worktrees_data  # noqa: F401
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Re-exports from ui/ for backward compatibility
+# ═══════════════════════════════════════════════════════════════════════════════
+# Interactive UI functions (extracted in Phase 4B)
+from .ui.git_interactive import (  # noqa: F401
+    check_branch_safety,
+    cleanup_worktree,
+    clone_repo,
+    create_worktree,
+    install_dependencies,
+    install_hooks,
+    list_worktrees,
+)
+
+# Pure rendering functions
+from .ui.git_render import format_git_status as _format_git_status  # noqa: F401
+from .ui.git_render import render_worktrees  # noqa: F401
+from .ui.git_render import render_worktrees_table as _render_worktrees_table  # noqa: F401

scc_cli/json_command.py

@@ -0,0 +1,166 @@
+"""
+JSON command decorator for first-class JSON output support.
+
+Provide a decorator that wraps command output in JSON envelopes.
+
+IMPORTANT: Commands using this decorator MUST explicitly declare these parameters:
+    json_output: bool = typer.Option(False, "--json", help="Output as JSON")
+    pretty: bool = typer.Option(False, "--pretty", help="Pretty-print JSON")
+
+Usage:
+    from scc_cli.json_command import json_command
+    from scc_cli.kinds import Kind
+
+    @team_app.command("list")
+    @json_command(Kind.TEAM_LIST)
+    def team_list(
+        json_output: bool = typer.Option(False, "--json"),
+        pretty: bool = typer.Option(False, "--pretty"),
+    ) -> dict:
+        # Return data dict, decorator handles envelope
+        return {"teams": [...]}
+"""
+
+from collections.abc import Callable
+from functools import wraps
+from typing import Any, TypeVar
+
+import typer
+
+from .core.errors import ConfigError, PolicyViolationError, PrerequisiteError, SCCError
+from .core.exit_codes import (
+    EXIT_CANCELLED,
+    EXIT_CONFIG,
+    EXIT_ERROR,
+    EXIT_GOVERNANCE,
+    EXIT_PREREQ,
+    EXIT_SUCCESS,
+    EXIT_VALIDATION,
+)
+from .json_output import build_envelope
+from .kinds import Kind
+from .output_mode import _pretty_mode, json_command_mode, json_output_mode, print_json
+
+# Type variable for decorated functions
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Exception to Exit Code Mapping
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+def _get_exit_code_for_exception(exc: Exception) -> int:
+    """Map exception types to exit codes."""
+    if isinstance(exc, PolicyViolationError):
+        return EXIT_GOVERNANCE
+    if isinstance(exc, PrerequisiteError):
+        return EXIT_PREREQ
+    if isinstance(exc, ConfigError):
+        return EXIT_CONFIG
+    if isinstance(exc, SCCError):
+        # Check exit_code attribute if available
+        return getattr(exc, "exit_code", EXIT_ERROR)
+    # Check for validation-like errors by name
+    if "Validation" in type(exc).__name__:
+        return EXIT_VALIDATION
+    return EXIT_ERROR
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# JSON Command Decorator
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+def json_command(kind: Kind) -> Callable[[F], F]:
+    """Decorator for commands with --json support.
+
+    This decorator:
+    1. Checks for json_output and pretty parameters in kwargs
+    2. Enters json_output_mode() when json_output=True
+    3. Builds the envelope with the correct kind
+    4. Catches exceptions and maps to exit codes
+    5. Prints JSON output and exits with appropriate code
+
+    IMPORTANT: The decorated function MUST explicitly declare these parameters:
+        json_output: bool = typer.Option(False, "--json", help="Output as JSON")
+        pretty: bool = typer.Option(False, "--pretty", help="Pretty-print JSON")
+
+    Args:
+        kind: The JSON envelope kind for this command
+
+    Returns:
+        A decorator function
+
+    Usage:
+        @team_app.command("list")
+        @json_command(Kind.TEAM_LIST)
+        def team_list(
+            json_output: bool = typer.Option(False, "--json"),
+            pretty: bool = typer.Option(False, "--pretty"),
+        ) -> dict:
+            return {"teams": [...]}
+
+    Note:
+        The decorated function should return a dict that becomes
+        the "data" field in the JSON envelope. When not in JSON mode,
+        the function runs normally (for human-readable output).
+    """
+
+    def decorator(func: F) -> F:
+        @wraps(func)
+        def wrapper(**kwargs: Any) -> Any:
+            # Extract json_output and pretty from kwargs
+            json_output = kwargs.pop("json_output", False)
+            pretty = kwargs.pop("pretty", False)
+
+            # --pretty implies --json
+            if pretty:
+                json_output = True
+                _pretty_mode.set(True)
+
+            if json_output:
+                with json_output_mode(), json_command_mode():
+                    try:
+                        # Call the wrapped function
+                        result = func(**kwargs)
+
+                        # Build and print success envelope
+                        envelope = build_envelope(kind, data=result or {})
+                        print_json(envelope)
+                        raise typer.Exit(EXIT_SUCCESS)
+
+                    except typer.Exit:
+                        # Re-raise typer exits (including our own)
+                        raise
+
+                    except KeyboardInterrupt:
+                        envelope = build_envelope(
+                            kind,
+                            data={},
+                            ok=False,
+                            errors=["Cancelled"],
+                        )
+                        print_json(envelope)
+                        raise typer.Exit(EXIT_CANCELLED)
+
+                    except Exception as e:
+                        # Map exception to exit code
+                        exit_code = _get_exit_code_for_exception(e)
+
+                        # Build and print error envelope
+                        envelope = build_envelope(
+                            kind,
+                            data={},
+                            ok=False,
+                            errors=[str(e)],
+                        )
+                        print_json(envelope)
+                        raise typer.Exit(exit_code)
+            else:
+                # Normal human-readable mode
+                return func(**kwargs)
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator