scc-cli 1.4.0__py3-none-any.whl

scc_cli/marketplace/compute.py

@@ -0,0 +1,377 @@
+"""
+Effective plugin computation for team profiles.
+
+This module provides the core plugin resolution logic:
+- BlockedPlugin: Dataclass for blocked plugins with reason/pattern
+- EffectivePlugins: Result of computation with enabled/blocked/disabled sets
+- compute_effective_plugins(): Pure function for plugin resolution
+
+Order of Operations:
+    1. Normalize all plugin references to canonical form
+    2. Merge defaults.enabled_plugins + profile.additional_plugins
+    3. Apply profile.disabled_plugins patterns (removes from merged)
+    4. Apply profile.allowed_plugins filter (for additional only)
+    5. Apply security.blocked_plugins (final security gate)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from scc_cli.marketplace.normalize import (
+    matches_pattern,
+    normalize_plugin,
+)
+
+if TYPE_CHECKING:
+    from scc_cli.marketplace.schema import OrganizationConfig, TeamConfig
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Exceptions
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TeamNotFoundError(KeyError):
+    """Raised when requested team profile is not found in config."""
+
+    def __init__(self, team_id: str, available_teams: list[str]) -> None:
+        self.team_id = team_id
+        self.available_teams = available_teams
+        teams_str = ", ".join(sorted(available_teams)) if available_teams else "none"
+        super().__init__(
+            f"Team '{team_id}' not found in organization config. Available teams: {teams_str}"
+        )
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Dataclasses
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class BlockedPlugin:
+    """A plugin blocked by security policy.
+
+    Attributes:
+        plugin_id: The canonical plugin reference (name@marketplace)
+        reason: Human-readable explanation from security config
+        pattern: The glob pattern that matched this plugin
+    """
+
+    plugin_id: str
+    reason: str
+    pattern: str
+
+
+@dataclass
+class EffectivePlugins:
+    """Result of computing effective plugins for a team.
+
+    Attributes:
+        enabled: Set of enabled plugin references (name@marketplace)
+        blocked: List of BlockedPlugin with reasons
+        not_allowed: Plugins rejected by allowed_plugins filter
+        disabled: Plugins removed by disabled_plugins patterns
+        extra_marketplaces: List of marketplace IDs to enable
+    """
+
+    enabled: set[str] = field(default_factory=set)
+    blocked: list[BlockedPlugin] = field(default_factory=list)
+    not_allowed: list[str] = field(default_factory=list)
+    disabled: list[str] = field(default_factory=list)
+    extra_marketplaces: list[str] = field(default_factory=list)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Computation
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def compute_effective_plugins(
+    config: OrganizationConfig,
+    team_id: str,
+) -> EffectivePlugins:
+    """Compute effective plugins for a team based on organization config.
+
+    This is a pure function that determines which plugins a team member
+    can use, applying all governance rules in the correct order.
+
+    Order of operations:
+        1. Normalize all plugin references
+        2. Merge defaults + profile additional plugins
+        3. Apply disabled_plugins patterns
+        4. Apply allowed_plugins filter (additional only)
+        5. Apply security.blocked_plugins
+
+    Args:
+        config: Organization configuration with profiles and security
+        team_id: The profile/team ID to compute plugins for
+
+    Returns:
+        EffectivePlugins with enabled, blocked, disabled, and marketplace info
+
+    Raises:
+        TeamNotFoundError: If team_id is not in config.profiles
+        AmbiguousMarketplaceError: If bare plugin name with 2+ org marketplaces
+    """
+    # Validate team exists
+    if team_id not in config.profiles:
+        raise TeamNotFoundError(
+            team_id=team_id,
+            available_teams=list(config.profiles.keys()),
+        )
+
+    profile = config.profiles[team_id]
+    defaults = config.defaults
+    security = config.security
+    org_marketplaces = config.marketplaces or {}
+
+    result = EffectivePlugins()
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # Step 1: Collect all plugins (normalized)
+    # ─────────────────────────────────────────────────────────────────────────
+
+    # Normalize defaults.enabled_plugins
+    default_plugins: set[str] = set()
+    if defaults and defaults.enabled_plugins:
+        for plugin_ref in defaults.enabled_plugins:
+            normalized = normalize_plugin(plugin_ref, org_marketplaces)
+            default_plugins.add(normalized)
+
+    # Normalize profile.additional_plugins
+    additional_plugins: set[str] = set()
+    if profile.additional_plugins:
+        for plugin_ref in profile.additional_plugins:
+            normalized = normalize_plugin(plugin_ref, org_marketplaces)
+            additional_plugins.add(normalized)
+
+    # Start with defaults as base
+    merged_plugins = default_plugins.copy()
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # Step 2: Apply disabled_plugins patterns (remove from merged)
+    # ─────────────────────────────────────────────────────────────────────────
+
+    disabled_patterns = profile.disabled_plugins or []
+    for plugin in list(merged_plugins):
+        for pattern in disabled_patterns:
+            if matches_pattern(plugin, pattern):
+                merged_plugins.discard(plugin)
+                result.disabled.append(plugin)
+                break
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # Step 3: Apply allowed_plugins filter to additional plugins
+    # ─────────────────────────────────────────────────────────────────────────
+
+    # allowed_plugins semantics:
+    # - None: allow all additional plugins
+    # - []: block all additional plugins
+    # - ["x", "y"]: only allow x and y from additional
+    allowed_plugins = profile.allowed_plugins
+
+    for plugin in additional_plugins:
+        # Check if already disabled
+        if plugin in result.disabled:
+            continue
+
+        if allowed_plugins is None:
+            # Allow all
+            merged_plugins.add(plugin)
+        elif plugin in allowed_plugins:
+            # In allowlist
+            merged_plugins.add(plugin)
+        else:
+            # Not in allowlist (includes empty list case)
+            result.not_allowed.append(plugin)
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # Step 4: Apply security.blocked_plugins (final security gate)
+    # ─────────────────────────────────────────────────────────────────────────
+
+    blocked_patterns = security.blocked_plugins if security else []
+    blocked_reason = security.blocked_reason if security else "Blocked by security policy"
+
+    for plugin in list(merged_plugins):
+        for pattern in blocked_patterns:
+            if matches_pattern(plugin, pattern):
+                merged_plugins.discard(plugin)
+                result.blocked.append(
+                    BlockedPlugin(
+                        plugin_id=plugin,
+                        reason=blocked_reason,
+                        pattern=pattern,
+                    )
+                )
+                break
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # Step 5: Collect extra marketplaces
+    # ─────────────────────────────────────────────────────────────────────────
+
+    marketplace_set: set[str] = set()
+
+    if defaults and defaults.extra_marketplaces:
+        marketplace_set.update(defaults.extra_marketplaces)
+
+    if profile.extra_marketplaces:
+        marketplace_set.update(profile.extra_marketplaces)
+
+    result.extra_marketplaces = list(marketplace_set)
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # Final result
+    # ─────────────────────────────────────────────────────────────────────────
+
+    result.enabled = merged_plugins
+    return result
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Federated Computation
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def compute_effective_plugins_federated(
+    config: OrganizationConfig,
+    team_id: str,
+    team_config: TeamConfig,
+) -> EffectivePlugins:
+    """Compute effective plugins for a federated team (6-step precedence).
+
+    This handles teams with external config_source. The key difference from
+    inline teams is that federated teams:
+    - Use TeamConfig.enabled_plugins instead of profile.additional_plugins
+    - Use TeamConfig.disabled_plugins for team-level filtering
+    - Are NOT subject to allowed_plugins restrictions (that's for inline only)
+    - Are ALWAYS subject to org security.blocked_plugins
+
+    Order of operations (6-step precedence):
+        1. Start with org defaults.enabled_plugins
+        2. Add team config enabled_plugins
+        3. Apply team config disabled_plugins patterns
+        4. Apply org defaults.disabled_plugins patterns
+        5. SKIP allowed_plugins (federated teams not subject to inline restrictions)
+        6. Apply org security.blocked_plugins (ALWAYS enforced)
+
+    Args:
+        config: Organization configuration with profiles and security
+        team_id: The profile/team ID to compute plugins for
+        team_config: External team configuration fetched from config_source
+
+    Returns:
+        EffectivePlugins with enabled, blocked, disabled, and marketplace info
+
+    Raises:
+        TeamNotFoundError: If team_id is not in config.profiles
+    """
+    # Validate team exists in org config
+    if team_id not in config.profiles:
+        raise TeamNotFoundError(
+            team_id=team_id,
+            available_teams=list(config.profiles.keys()),
+        )
+
+    profile = config.profiles[team_id]
+    defaults = config.defaults
+    security = config.security
+    org_marketplaces = config.marketplaces or {}
+
+    result = EffectivePlugins()
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # Step 1: Start with org defaults.enabled_plugins
+    # ─────────────────────────────────────────────────────────────────────────
+
+    merged_plugins: set[str] = set()
+    if defaults and defaults.enabled_plugins:
+        for plugin_ref in defaults.enabled_plugins:
+            normalized = normalize_plugin(plugin_ref, org_marketplaces)
+            merged_plugins.add(normalized)
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # Step 2: Add team config enabled_plugins
+    # ─────────────────────────────────────────────────────────────────────────
+
+    if team_config.enabled_plugins:
+        for plugin_ref in team_config.enabled_plugins:
+            normalized = normalize_plugin(plugin_ref, org_marketplaces)
+            merged_plugins.add(normalized)
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # Step 3: Apply team config disabled_plugins patterns
+    # ─────────────────────────────────────────────────────────────────────────
+
+    team_disabled_patterns = team_config.disabled_plugins or []
+    for plugin in list(merged_plugins):
+        for pattern in team_disabled_patterns:
+            if matches_pattern(plugin, pattern):
+                merged_plugins.discard(plugin)
+                result.disabled.append(plugin)
+                break
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # Step 4: Apply org defaults.disabled_plugins patterns
+    # ─────────────────────────────────────────────────────────────────────────
+
+    org_disabled_patterns = (defaults.disabled_plugins or []) if defaults else []
+    for plugin in list(merged_plugins):
+        for pattern in org_disabled_patterns:
+            if matches_pattern(plugin, pattern):
+                merged_plugins.discard(plugin)
+                result.disabled.append(plugin)
+                break
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # Step 5: SKIP allowed_plugins (federated teams not subject to this)
+    # ─────────────────────────────────────────────────────────────────────────
+
+    # For federated teams, we do NOT apply the allowed_plugins filter.
+    # This restriction is only for inline teams using additional_plugins.
+    # Federated teams have their own governance via trust grants.
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # Step 6: Apply org security.blocked_plugins (ALWAYS enforced)
+    # ─────────────────────────────────────────────────────────────────────────
+
+    blocked_patterns = security.blocked_plugins if security else []
+    blocked_reason = security.blocked_reason if security else "Blocked by security policy"
+
+    for plugin in list(merged_plugins):
+        for pattern in blocked_patterns:
+            if matches_pattern(plugin, pattern):
+                merged_plugins.discard(plugin)
+                result.blocked.append(
+                    BlockedPlugin(
+                        plugin_id=plugin,
+                        reason=blocked_reason,
+                        pattern=pattern,
+                    )
+                )
+                break
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # Collect extra marketplaces (from defaults and profile only)
+    # ─────────────────────────────────────────────────────────────────────────
+
+    # Note: TeamConfig doesn't have extra_marketplaces - it defines
+    # actual marketplace sources via its 'marketplaces' dict instead.
+    marketplace_set: set[str] = set()
+
+    if defaults and defaults.extra_marketplaces:
+        marketplace_set.update(defaults.extra_marketplaces)
+
+    if profile.extra_marketplaces:
+        marketplace_set.update(profile.extra_marketplaces)
+
+    result.extra_marketplaces = list(marketplace_set)
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # Final result
+    # ─────────────────────────────────────────────────────────────────────────
+
+    result.enabled = merged_plugins
+    return result

scc_cli/marketplace/constants.py

@@ -0,0 +1,87 @@
+"""
+Constants for marketplace and plugin management.
+
+This module defines:
+- IMPLICIT_MARKETPLACES: Built-in marketplaces that Claude Code knows about
+- EXIT_CODES: Semantic exit codes for marketplace operations
+- Path constants for cache and state files
+"""
+
+from typing import Final
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Implicit Marketplaces
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Marketplaces that Claude Code supports natively without explicit configuration.
+# These are NEVER written to settings.local.json and don't count toward ambiguity
+# when resolving unqualified plugin names.
+#
+# Per research.md RQ-10:
+# - Implicit marketplaces are always available
+# - Don't need to be written to extraKnownMarketplaces
+# - Unqualified plugins can resolve here when no org marketplaces exist
+IMPLICIT_MARKETPLACES: Final[frozenset[str]] = frozenset(
+    {
+        "claude-plugins-official",
+    }
+)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Exit Codes
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Semantic exit codes for marketplace operations.
+# These align with existing SCC exit code conventions.
+#
+# Usage:
+#     from scc_cli.marketplace.constants import EXIT_CODES
+#     sys.exit(EXIT_CODES["validation_error"])
+EXIT_CODES: Final[dict[str, int]] = {
+    # Success
+    "success": 0,
+    # User errors (2)
+    "validation_error": 2,  # Schema validation failed
+    "invalid_plugin_ref": 2,  # Malformed plugin reference
+    "ambiguous_marketplace": 2,  # Plugin ref needs explicit @marketplace
+    # Prerequisite errors (3)
+    "network_error": 3,  # Cannot fetch remote config
+    "git_unavailable": 3,  # Git not installed for git: sources
+    # Tool errors (4)
+    "git_clone_failed": 4,  # Git clone/fetch failed
+    "http_fetch_failed": 4,  # HTTP download failed
+    "materialization_failed": 4,  # Failed to materialize marketplace
+    # Internal errors (5)
+    "internal_error": 5,  # Bug in SCC
+    # Policy violations (6)
+    "blocked_by_policy": 6,  # Plugin blocked by security policy
+}
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Path Constants
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Directory name for materialized marketplaces (under project's .claude/)
+# Per research.md RQ-2: Must be project-local for Docker sandbox visibility
+MARKETPLACE_CACHE_DIR: Final[str] = ".scc-marketplaces"
+
+# Filename for tracking SCC-managed entries in settings
+# Per research.md RQ-7: Enables non-destructive merge
+MANAGED_STATE_FILE: Final[str] = ".scc-managed.json"
+
+# Filename for marketplace manifest tracking materialization state
+MANIFEST_FILE: Final[str] = ".manifest.json"
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# TTL and Caching
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Default TTL for org config freshness (24 hours in seconds)
+# Per research.md RQ-6: Time-based staleness detection
+DEFAULT_ORG_CONFIG_TTL_SECONDS: Final[int] = 24 * 60 * 60
+
+# Minimum TTL to prevent excessive re-fetching (1 hour)
+MIN_ORG_CONFIG_TTL_SECONDS: Final[int] = 1 * 60 * 60

scc_cli/marketplace/managed.py

@@ -0,0 +1,135 @@
+"""
+Managed state tracking for SCC marketplace integration.
+
+This module tracks what SCC has added to settings.local.json, enabling
+non-destructive merges that preserve user customizations.
+
+Key responsibilities:
+1. ManagedState - Data structure tracking SCC-managed entries
+2. load_managed_state() - Load tracking state from .scc-managed.json
+3. save_managed_state() - Persist tracking state to disk
+4. clear_managed_state() - Remove tracking state (for reset operations)
+
+Per RQ-7: Non-destructive merge preserves user-added plugins/marketplaces.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from scc_cli.marketplace.constants import MANAGED_STATE_FILE
+
+
+@dataclass
+class ManagedState:
+    """Tracks what SCC has added to settings.local.json.
+
+    This state enables non-destructive merging:
+    - On sync: Remove entries in managed_plugins/marketplaces, then add new ones
+    - User customizations: Entries NOT in managed lists are preserved
+
+    Attributes:
+        managed_plugins: Plugin references (name@marketplace) managed by SCC
+        managed_marketplaces: Marketplace paths managed by SCC
+        last_sync: Timestamp of last successful sync
+        org_config_url: URL of the org config that was synced
+        team_id: Team ID that was selected during sync
+    """
+
+    managed_plugins: list[str] = field(default_factory=list)
+    managed_marketplaces: list[str] = field(default_factory=list)
+    last_sync: datetime | None = None
+    org_config_url: str | None = None
+    team_id: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to dictionary for JSON storage."""
+        result: dict[str, Any] = {
+            "managed_plugins": self.managed_plugins,
+            "managed_marketplaces": self.managed_marketplaces,
+        }
+
+        if self.last_sync is not None:
+            result["last_sync"] = self.last_sync.isoformat()
+
+        if self.org_config_url is not None:
+            result["org_config_url"] = self.org_config_url
+
+        if self.team_id is not None:
+            result["team_id"] = self.team_id
+
+        return result
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ManagedState:
+        """Deserialize from dictionary."""
+        last_sync = None
+        if "last_sync" in data and data["last_sync"]:
+            try:
+                last_sync = datetime.fromisoformat(data["last_sync"])
+            except (ValueError, TypeError):
+                pass
+
+        return cls(
+            managed_plugins=data.get("managed_plugins", []),
+            managed_marketplaces=data.get("managed_marketplaces", []),
+            last_sync=last_sync,
+            org_config_url=data.get("org_config_url"),
+            team_id=data.get("team_id"),
+        )
+
+
+def load_managed_state(project_dir: Path) -> ManagedState:
+    """Load managed state from .scc-managed.json.
+
+    Args:
+        project_dir: Project root directory
+
+    Returns:
+        ManagedState with tracking data, or empty state if file doesn't exist
+    """
+    managed_path = project_dir / ".claude" / MANAGED_STATE_FILE
+
+    if not managed_path.exists():
+        return ManagedState()
+
+    try:
+        data: dict[str, Any] = json.loads(managed_path.read_text())
+        return ManagedState.from_dict(data)
+    except json.JSONDecodeError:
+        # Corrupted file - return empty state
+        return ManagedState()
+
+
+def save_managed_state(project_dir: Path, state: ManagedState) -> None:
+    """Save managed state to .scc-managed.json.
+
+    Creates .claude directory if it doesn't exist.
+
+    Args:
+        project_dir: Project root directory
+        state: ManagedState to persist
+    """
+    claude_dir = project_dir / ".claude"
+    claude_dir.mkdir(parents=True, exist_ok=True)
+
+    managed_path = claude_dir / MANAGED_STATE_FILE
+    managed_path.write_text(json.dumps(state.to_dict(), indent=2))
+
+
+def clear_managed_state(project_dir: Path) -> None:
+    """Remove managed state file.
+
+    Used for reset operations. Preserves .claude directory and other files.
+
+    Args:
+        project_dir: Project root directory
+    """
+    managed_path = project_dir / ".claude" / MANAGED_STATE_FILE
+
+    if managed_path.exists():
+        managed_path.unlink()