scc-cli 1.4.0__py3-none-any.whl

scc_cli/marketplace/render.py

@@ -0,0 +1,238 @@
+"""
+Settings rendering for Claude Code integration.
+
+This module provides the bridge between SCC's marketplace/plugin management
+and Claude Code's settings.local.json format. Key responsibilities:
+
+1. render_settings() - Convert effective plugins to Claude settings format
+2. merge_settings() - Non-destructive merge preserving user customizations
+3. check_conflicts() - Detect conflicts between user and team settings
+
+Per RQ-11: All paths must be relative for Docker sandbox compatibility.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from scc_cli.marketplace.constants import MANAGED_STATE_FILE
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Render Settings
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def render_settings(
+    effective_plugins: dict[str, Any],
+    materialized_marketplaces: dict[str, Any],
+) -> dict[str, Any]:
+    """Render effective plugins and marketplaces to Claude settings format.
+
+    Creates a settings.local.json compatible structure with:
+    - extraKnownMarketplaces: Array of marketplace configs with type and path
+    - enabledPlugins: Array of plugin references (name@marketplace)
+
+    Args:
+        effective_plugins: Result from compute_effective_plugins()
+            - enabled: Set of enabled plugin references
+            - extra_marketplaces: List of marketplace IDs to enable
+        materialized_marketplaces: Dict mapping name to MaterializedMarketplace-like dicts
+            - relative_path: Path relative to project root
+            - source_type: Type of source (github, git, directory, url)
+
+    Returns:
+        Dict with Claude Code settings structure:
+            {
+                "extraKnownMarketplaces": [...],
+                "enabledPlugins": [...]
+            }
+    """
+    settings: dict[str, Any] = {}
+
+    # Build extraKnownMarketplaces array
+    extra_marketplaces: list[dict[str, str]] = []
+    for name, marketplace_data in materialized_marketplaces.items():
+        # Get the relative path from the materialized data
+        relative_path = marketplace_data.get("relative_path", "")
+
+        # All local marketplaces use type: directory
+        # This is because they've been cloned/downloaded to a local path
+        extra_marketplaces.append(
+            {
+                "type": "directory",
+                "path": relative_path,
+            }
+        )
+
+    settings["extraKnownMarketplaces"] = extra_marketplaces
+
+    # Build enabledPlugins array
+    enabled = effective_plugins.get("enabled", set())
+    # Convert set to sorted list for consistent output
+    if isinstance(enabled, set):
+        settings["enabledPlugins"] = sorted(list(enabled))
+    else:
+        settings["enabledPlugins"] = list(enabled)
+
+    return settings
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Merge Settings (Non-Destructive)
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def _load_settings(project_dir: Path) -> dict[str, Any]:
+    """Load existing settings.local.json if it exists."""
+    settings_path = project_dir / ".claude" / "settings.local.json"
+    if settings_path.exists():
+        try:
+            result: dict[str, Any] = json.loads(settings_path.read_text())
+            return result
+        except json.JSONDecodeError:
+            return {}
+    return {}
+
+
+def _load_managed_state(project_dir: Path) -> dict[str, Any]:
+    """Load the SCC managed state tracking file."""
+    managed_path = project_dir / ".claude" / MANAGED_STATE_FILE
+    if managed_path.exists():
+        try:
+            result: dict[str, Any] = json.loads(managed_path.read_text())
+            return result
+        except json.JSONDecodeError:
+            return {}
+    return {}
+
+
+def merge_settings(
+    project_dir: Path,
+    new_settings: dict[str, Any],
+) -> dict[str, Any]:
+    """Non-destructively merge new settings with existing user settings.
+
+    This function implements RQ-7 from the research document:
+    - Preserves user-added plugins and marketplaces
+    - Removes old SCC-managed entries before adding new ones
+    - Uses .scc-managed.json to track what SCC has added
+
+    Algorithm:
+        1. Load existing settings.local.json
+        2. Load .scc-managed.json to know what was previously SCC-managed
+        3. Remove previously managed plugins and marketplaces
+        4. Add all new plugins and marketplaces from new_settings
+        5. Return merged result (caller responsible for writing)
+
+    Args:
+        project_dir: Project root directory
+        new_settings: New settings from render_settings()
+
+    Returns:
+        Merged settings dict ready to write to settings.local.json
+    """
+    existing = _load_settings(project_dir)
+    managed = _load_managed_state(project_dir)
+
+    # Get what was previously managed by SCC
+    managed_plugins = set(managed.get("managed_plugins", []))
+    managed_marketplaces = set(managed.get("managed_marketplaces", []))
+
+    # Start with existing settings
+    merged = dict(existing)
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # Process enabledPlugins
+    # ─────────────────────────────────────────────────────────────────────────
+
+    # Get existing plugins, removing old SCC-managed ones
+    existing_plugins = set(existing.get("enabledPlugins", []))
+    # Remove old managed plugins
+    remaining_user_plugins = existing_plugins - managed_plugins
+
+    # Add new plugins from this render
+    new_plugins = set(new_settings.get("enabledPlugins", []))
+    merged_plugins = remaining_user_plugins | new_plugins
+
+    # Deduplicate and sort
+    merged["enabledPlugins"] = sorted(list(merged_plugins))
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # Process extraKnownMarketplaces
+    # ─────────────────────────────────────────────────────────────────────────
+
+    existing_marketplaces = existing.get("extraKnownMarketplaces", [])
+
+    # Filter out old SCC-managed marketplaces
+    remaining_user_marketplaces = [
+        m for m in existing_marketplaces if m.get("path", "") not in managed_marketplaces
+    ]
+
+    # Add new marketplaces from this render
+    new_marketplaces = new_settings.get("extraKnownMarketplaces", [])
+
+    # Merge: user marketplaces first, then new ones
+    # Deduplicate by path
+    seen_paths: set[str] = set()
+    merged_marketplaces: list[dict[str, str]] = []
+
+    for m in remaining_user_marketplaces:
+        path = m.get("path", "")
+        if path not in seen_paths:
+            merged_marketplaces.append(m)
+            seen_paths.add(path)
+
+    for m in new_marketplaces:
+        path = m.get("path", "")
+        if path not in seen_paths:
+            merged_marketplaces.append(m)
+            seen_paths.add(path)
+
+    merged["extraKnownMarketplaces"] = merged_marketplaces
+
+    return merged
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Conflict Detection
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def check_conflicts(
+    existing_plugins: list[str],
+    blocked_plugins: list[dict[str, Any]],
+) -> list[str]:
+    """Check for conflicts between user plugins and team security policy.
+
+    Generates human-readable warnings when a user has installed plugins
+    that would be blocked by the team's security policy.
+
+    Args:
+        existing_plugins: List of plugin references from user's current settings
+        blocked_plugins: List of blocked plugin dicts from EffectivePlugins.blocked
+            Each dict has: plugin_id, reason, pattern
+
+    Returns:
+        List of warning strings for display to user
+    """
+    warnings: list[str] = []
+
+    # Build a set of blocked plugin IDs for fast lookup
+    blocked_ids = {b.get("plugin_id", "") for b in blocked_plugins}
+
+    for plugin in existing_plugins:
+        if plugin in blocked_ids:
+            # Find the block details
+            for blocked in blocked_plugins:
+                if blocked.get("plugin_id") == plugin:
+                    reason = blocked.get("reason", "Blocked by policy")
+                    pattern = blocked.get("pattern", "")
+                    warnings.append(
+                        f"⚠️ Plugin '{plugin}' is blocked by team policy: {reason} "
+                        f"(matched pattern: {pattern})"
+                    )
+                    break
+
+    return warnings

scc_cli/marketplace/resolve.py

@@ -0,0 +1,459 @@
+"""Effective config resolution for team profiles (Phase 2: Federation).
+
+This module provides:
+- EffectiveConfig: Complete resolved configuration for a team
+- ConfigFetchError: Error when fetching federated team config fails
+- resolve_effective_config(): Main orchestrator (T2a-18, to be implemented)
+
+EffectiveConfig serves as the unified result type for both inline and federated
+team configurations, providing backwards compatibility via to_phase1_format().
+
+Design Decision:
+    EffectiveConfig wraps the plugin computation results (from compute.py) with
+    additional metadata about the configuration source. This allows the CLI to
+    display federated vs inline status, version info, and trust state.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from scc_cli.marketplace.compute import (
+    BlockedPlugin,
+    EffectivePlugins,
+    compute_effective_plugins,
+    compute_effective_plugins_federated,
+)
+from scc_cli.marketplace.team_fetch import fetch_team_config_with_fallback
+from scc_cli.marketplace.trust import TrustViolationError, validate_team_config_trust
+
+if TYPE_CHECKING:
+    from scc_cli.marketplace.schema import (
+        ConfigSource,
+        MarketplaceSource,
+        OrganizationConfig,
+    )
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Exceptions
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class ConfigFetchError(Exception):
+    """Error when fetching federated team configuration fails.
+
+    Provides structured error information with remediation hints.
+    """
+
+    def __init__(
+        self,
+        team_id: str,
+        source_type: str,
+        source_url: str,
+        error: str,
+    ) -> None:
+        self.team_id = team_id
+        self.source_type = source_type
+        self.source_url = source_url
+        self.error = error
+
+        # Build message with remediation hints
+        remediation = _get_fetch_remediation(source_type, error)
+        message = (
+            f"Failed to fetch config for team '{team_id}' from {source_type} "
+            f"source ({source_url}): {error}"
+        )
+        if remediation:
+            message += f" {remediation}"
+
+        super().__init__(message)
+
+
+def _get_fetch_remediation(source_type: str, error: str) -> str:
+    """Get remediation hint based on source type and error pattern."""
+    error_lower = error.lower()
+
+    # Network issues
+    if "network" in error_lower or "connection" in error_lower:
+        return "Try 'scc org update --team <name>' to refresh when connected."
+
+    # Cache expired
+    if "max_stale_age" in error_lower or "expired" in error_lower:
+        return "The cached config has expired. Connect to network to refresh."
+
+    # Git/GitHub specific
+    if source_type in ("github", "git"):
+        if "clone" in error_lower or "repository" in error_lower:
+            return "Check repository access permissions and URL."
+        if "branch" in error_lower:
+            return "Verify the branch name exists in the repository."
+        if "path" in error_lower or "not found" in error_lower:
+            return "Check that team-config.json exists at the specified path."
+
+    # URL specific
+    if source_type == "url":
+        if "401" in error or "unauthorized" in error_lower:
+            return "Add authentication headers to config_source."
+        if "403" in error or "forbidden" in error_lower:
+            return "Check access permissions for the config URL."
+        if "404" in error or "not found" in error_lower:
+            return "Verify the config URL is correct."
+
+    # Generic fallback
+    return "Run 'scc org update --team <name>' to retry fetching."
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# EffectiveConfig Dataclass
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+@dataclass
+class EffectiveConfig:
+    """Complete resolved configuration for a team.
+
+    This is the unified result type for both inline and federated team
+    configurations. It contains all the information needed to:
+    - Launch Claude Code with the correct plugins
+    - Display status information to the user
+    - Validate security compliance
+
+    For backwards compatibility, use to_phase1_format() to get the
+    (EffectivePlugins, marketplaces) tuple expected by Phase 1 code.
+
+    Attributes:
+        team_id: Team/profile identifier
+        is_federated: True if config came from external source
+        enabled_plugins: Set of enabled plugin references (name@marketplace)
+        config_source: External config source (if federated)
+        config_commit_sha: Git commit SHA (for git/github sources)
+        config_etag: HTTP ETag (for URL sources)
+        blocked_plugins: Plugins blocked by security policy
+        disabled_plugins: Plugins removed by disabled_plugins patterns
+        not_allowed_plugins: Plugins rejected by allowed_plugins filter
+        marketplaces: Effective marketplace sources
+        extra_marketplaces: Additional marketplace IDs to enable
+    """
+
+    # Required fields
+    team_id: str
+    is_federated: bool
+    enabled_plugins: set[str]
+
+    # Optional federation metadata
+    config_source: ConfigSource | None = None
+    config_commit_sha: str | None = None
+    config_etag: str | None = None
+
+    # Cache status (T2b-03: cached configs validated against current org security)
+    used_cached_config: bool = False
+    cache_is_stale: bool = False
+    staleness_warning: str | None = None
+
+    # Plugin filtering results
+    blocked_plugins: list[BlockedPlugin] = field(default_factory=list)
+    disabled_plugins: list[str] = field(default_factory=list)
+    not_allowed_plugins: list[str] = field(default_factory=list)
+
+    # Marketplace configuration
+    marketplaces: dict[str, MarketplaceSource] = field(default_factory=dict)
+    extra_marketplaces: list[str] = field(default_factory=list)
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # Computed Properties
+    # ─────────────────────────────────────────────────────────────────────────
+
+    @property
+    def has_security_violations(self) -> bool:
+        """Check if any plugins were blocked by security policy.
+
+        Returns:
+            True if blocked_plugins is non-empty
+        """
+        return len(self.blocked_plugins) > 0
+
+    @property
+    def plugin_count(self) -> int:
+        """Get total number of enabled plugins.
+
+        Returns:
+            Count of enabled plugins
+        """
+        return len(self.enabled_plugins)
+
+    @property
+    def source_description(self) -> str:
+        """Get human-readable description of config source.
+
+        Returns:
+            'inline' for non-federated, or source URL for federated
+        """
+        if not self.is_federated or self.config_source is None:
+            return "inline"
+
+        # Import here to avoid circular imports
+        from scc_cli.marketplace.schema import (
+            ConfigSourceGit,
+            ConfigSourceGitHub,
+            ConfigSourceURL,
+        )
+
+        if isinstance(self.config_source, ConfigSourceGitHub):
+            return f"github.com/{self.config_source.owner}/{self.config_source.repo}"
+        elif isinstance(self.config_source, ConfigSourceGit):
+            # Normalize git URL for display
+            url = self.config_source.url
+            if url.startswith("https://"):
+                url = url[8:]
+            elif url.startswith("git@"):
+                url = url[4:].replace(":", "/", 1)
+            if url.endswith(".git"):
+                url = url[:-4]
+            return url
+        elif isinstance(self.config_source, ConfigSourceURL):
+            # Strip protocol for display
+            url = self.config_source.url
+            if url.startswith("https://"):
+                url = url[8:]
+            return url
+        else:
+            return "unknown"
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # Phase 1 Compatibility
+    # ─────────────────────────────────────────────────────────────────────────
+
+    def to_phase1_format(self) -> tuple[EffectivePlugins, dict[str, MarketplaceSource]]:
+        """Convert to Phase 1 format for backwards compatibility.
+
+        This adapter method allows EffectiveConfig to work with existing
+        Phase 1 code that expects:
+        - EffectivePlugins for plugin computation results
+        - dict[str, MarketplaceSource] for marketplace configuration
+
+        Returns:
+            Tuple of (EffectivePlugins, marketplaces dict)
+        """
+        plugins = EffectivePlugins(
+            enabled=self.enabled_plugins,
+            blocked=self.blocked_plugins,
+            not_allowed=self.not_allowed_plugins,
+            disabled=self.disabled_plugins,
+            extra_marketplaces=self.extra_marketplaces,
+        )
+
+        return (plugins, self.marketplaces)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Resolution Orchestrator
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def resolve_effective_config(
+    config: OrganizationConfig,
+    team_id: str,
+) -> EffectiveConfig:
+    """Resolve effective configuration for a team (inline or federated).
+
+    This is the main orchestrator for Phase 2 configuration resolution.
+    It determines whether a team uses inline or federated configuration
+    and applies the appropriate resolution strategy.
+
+    For inline teams (no config_source):
+        - Uses compute_effective_plugins() from compute.py
+        - Returns EffectiveConfig with is_federated=False
+
+    For federated teams (has config_source):
+        - Fetches external team config via fetch_team_config()
+        - Uses compute_effective_plugins_federated() from compute.py
+        - Returns EffectiveConfig with is_federated=True and metadata
+
+    Args:
+        config: Organization configuration with profiles and security
+        team_id: The profile/team ID to resolve plugins for
+
+    Returns:
+        EffectiveConfig with complete resolved configuration
+
+    Raises:
+        TeamNotFoundError: If team_id is not in config.profiles
+        RuntimeError: If federated fetch fails
+    """
+    # Import here to avoid circular imports
+    # Validate team exists (this also raises TeamNotFoundError if missing)
+    from scc_cli.marketplace.compute import TeamNotFoundError
+    from scc_cli.marketplace.schema import TeamConfig
+
+    if team_id not in config.profiles:
+        raise TeamNotFoundError(
+            team_id=team_id,
+            available_teams=list(config.profiles.keys()),
+        )
+
+    profile = config.profiles[team_id]
+    org_marketplaces = config.marketplaces or {}
+
+    # Check if team has config_source (federated) or not (inline)
+    if profile.config_source is None:
+        # ─────────────────────────────────────────────────────────────────
+        # INLINE TEAM: No external config source
+        # ─────────────────────────────────────────────────────────────────
+        plugins = compute_effective_plugins(config, team_id)
+
+        return EffectiveConfig(
+            team_id=team_id,
+            is_federated=False,
+            enabled_plugins=plugins.enabled,
+            blocked_plugins=plugins.blocked,
+            disabled_plugins=plugins.disabled,
+            not_allowed_plugins=plugins.not_allowed,
+            marketplaces=org_marketplaces,
+            extra_marketplaces=plugins.extra_marketplaces,
+        )
+
+    else:
+        # ─────────────────────────────────────────────────────────────────
+        # FEDERATED TEAM: Has external config source
+        # ─────────────────────────────────────────────────────────────────
+        source = profile.config_source
+
+        # Fetch the external team config with cache fallback (T2b-01+02)
+        fallback_result = fetch_team_config_with_fallback(source, team_id)
+
+        if not fallback_result.success or fallback_result.result.team_config is None:
+            fetch_result = fallback_result.result
+            raise ConfigFetchError(
+                team_id=team_id,
+                source_type=fetch_result.source_type,
+                source_url=fetch_result.source_url,
+                error=fetch_result.error or "Unknown fetch error",
+            )
+
+        # Extract cache status for caller visibility
+        fetch_result = fallback_result.result
+        used_cached_config = fallback_result.used_cache
+        cache_is_stale = fallback_result.is_stale
+        staleness_warning = fallback_result.staleness_warning
+
+        # Parse the fetched config as TeamConfig
+        team_config = TeamConfig.model_validate(fetch_result.team_config)
+
+        # Validate team config against trust grants (T2a-27: marketplace collisions)
+        trust = profile.trust
+        if trust:
+            validate_team_config_trust(
+                team_config=team_config,
+                trust=trust,
+                team_name=team_id,
+                org_marketplaces=org_marketplaces,
+            )
+
+        # Use federated plugin computation
+        plugins = compute_effective_plugins_federated(config, team_id, team_config)
+
+        # Build effective marketplaces based on trust grants (T2a-28)
+        # If inherit_org_marketplaces=false, org marketplaces are NOT inherited
+        effective_marketplaces: dict[str, MarketplaceSource] = {}
+
+        if trust and not trust.inherit_org_marketplaces:
+            # T2a-28: Validate that defaults.enabled_plugins don't require org marketplaces
+            # when inherit_org_marketplaces=false
+            _validate_defaults_dont_need_org_marketplaces(
+                config=config,
+                org_marketplaces=org_marketplaces,
+                team_id=team_id,
+            )
+        else:
+            # inherit_org_marketplaces=true (default) - include org marketplaces
+            effective_marketplaces = dict(org_marketplaces)
+
+        # Add team marketplaces if trust allows
+        if team_config.marketplaces and trust and trust.allow_additional_marketplaces:
+            effective_marketplaces.update(team_config.marketplaces)
+
+        return EffectiveConfig(
+            team_id=team_id,
+            is_federated=True,
+            enabled_plugins=plugins.enabled,
+            config_source=source,
+            config_commit_sha=fetch_result.commit_sha,
+            config_etag=fetch_result.etag,
+            # Cache status - T2b-03: note that validate_team_config_trust() above
+            # uses CURRENT org security, so cached configs are always validated
+            # against the latest org policy
+            used_cached_config=used_cached_config,
+            cache_is_stale=cache_is_stale,
+            staleness_warning=staleness_warning,
+            blocked_plugins=plugins.blocked,
+            disabled_plugins=plugins.disabled,
+            not_allowed_plugins=plugins.not_allowed,
+            marketplaces=effective_marketplaces,
+            extra_marketplaces=plugins.extra_marketplaces,
+        )
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Helper Functions
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def _validate_defaults_dont_need_org_marketplaces(
+    config: OrganizationConfig,
+    org_marketplaces: dict[str, MarketplaceSource],
+    team_id: str,
+) -> None:
+    """Validate that defaults.enabled_plugins don't require org marketplaces.
+
+    When a federated team sets inherit_org_marketplaces=false, they won't have
+    access to org-defined marketplaces. However, defaults.enabled_plugins may
+    reference plugins from those marketplaces, creating a conflict.
+
+    This function validates that no such conflict exists.
+
+    Args:
+        config: Organization configuration with defaults
+        org_marketplaces: Dict of org-defined marketplaces
+        team_id: Team name for error messages
+
+    Raises:
+        TrustViolationError: If defaults.enabled_plugins reference org marketplaces
+    """
+    # Import here to avoid circular imports
+    from scc_cli.marketplace.constants import IMPLICIT_MARKETPLACES
+
+    if not config.defaults or not config.defaults.enabled_plugins:
+        return
+
+    # Check each default plugin for org marketplace references
+    conflicting_plugins: list[str] = []
+    conflicting_marketplaces: set[str] = set()
+
+    for plugin_ref in config.defaults.enabled_plugins:
+        if "@" in plugin_ref:
+            # Extract marketplace from plugin@marketplace format
+            marketplace_name = plugin_ref.split("@")[1]
+
+            # Skip implicit marketplaces - they're always available
+            if marketplace_name in IMPLICIT_MARKETPLACES:
+                continue
+
+            # Check if this marketplace is org-defined
+            if marketplace_name in org_marketplaces:
+                conflicting_plugins.append(plugin_ref)
+                conflicting_marketplaces.add(marketplace_name)
+
+    if conflicting_plugins:
+        plugins_str = ", ".join(conflicting_plugins)
+        marketplaces_str = ", ".join(sorted(conflicting_marketplaces))
+        raise TrustViolationError(
+            team_name=team_id,
+            violation=(
+                f"Team has inherit_org_marketplaces=false but defaults.enabled_plugins "
+                f"reference org marketplaces. Conflicting plugins: [{plugins_str}]. "
+                f"These require org marketplaces: [{marketplaces_str}]. "
+                "Either set inherit_org_marketplaces=true or remove these plugins from defaults."
+            ),
+        )