scc-cli 1.5.3__py3-none-any.whl

scc_cli/json_output.py

@@ -0,0 +1,159 @@
+"""
+JSON envelope builder for CLI output.
+
+Provide structured, versioned JSON envelopes for machine-readable output.
+All JSON output MUST use this builder to ensure consistency.
+
+Usage:
+    from scc_cli.json_output import build_envelope
+    from scc_cli.kinds import Kind
+
+    envelope = build_envelope(Kind.TEAM_LIST, data={"teams": [...]})
+"""
+
+from datetime import datetime, timezone
+from typing import Any
+
+from . import __version__
+from .core.errors import SCCError
+from .kinds import Kind
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Constants
+# ═══════════════════════════════════════════════════════════════════════════════
+
+API_VERSION = "scc.cli/v1"
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Envelope Builder
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+def build_envelope(
+    kind: Kind,
+    *,
+    data: dict[str, Any] | None = None,
+    ok: bool = True,
+    errors: list[str] | None = None,
+    warnings: list[str] | None = None,
+) -> dict[str, Any]:
+    """Build a JSON envelope with standard structure.
+
+    All JSON output follows this contract for consistency and parseability.
+
+    Args:
+        kind: The envelope kind (from Kind enum)
+        data: The command-specific payload
+        ok: Whether the operation was successful
+        errors: List of error messages (sets ok=False if non-empty)
+        warnings: List of warning messages
+
+    Returns:
+        A structured envelope dict ready for JSON serialization:
+        {
+            "apiVersion": "scc.cli/v1",
+            "kind": "TeamList",
+            "metadata": {
+                "generatedAt": "2025-12-23T10:00:00Z",
+                "cliVersion": "1.2.3"
+            },
+            "status": {
+                "ok": true,
+                "errors": [],
+                "warnings": []
+            },
+            "data": { ... }
+        }
+    """
+    # Normalize optional parameters
+    if data is None:
+        data = {}
+    if errors is None:
+        errors = []
+    if warnings is None:
+        warnings = []
+
+    # If errors provided, ok should be False
+    if errors and ok:
+        ok = False
+
+    # Generate ISO 8601 timestamp in UTC
+    generated_at = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    return {
+        "apiVersion": API_VERSION,
+        "kind": str(kind.value) if hasattr(kind, "value") else str(kind),
+        "metadata": {
+            "generatedAt": generated_at,
+            "cliVersion": __version__,
+        },
+        "status": {
+            "ok": ok,
+            "errors": errors,
+            "warnings": warnings,
+        },
+        "data": data,
+    }
+
+
+def build_error_envelope(exc: Exception) -> dict[str, Any]:
+    """Build a JSON error envelope from an exception.
+
+    This is the canonical error format for JSON mode output.
+    All errors should go through this function to ensure consistency.
+
+    Args:
+        exc: The exception to convert to JSON envelope
+
+    Returns:
+        A structured error envelope dict ready for JSON serialization:
+        {
+            "apiVersion": "scc.cli/v1",
+            "kind": "Error",
+            "metadata": { ... },
+            "status": {
+                "ok": false,
+                "errors": ["Error message"],
+                "warnings": []
+            },
+            "data": {
+                "error_type": "SCCError",
+                "user_message": "...",
+                "suggested_action": "...",
+                "debug_context": "..."  # Only for SCCError
+            }
+        }
+    """
+    # Generate ISO 8601 timestamp in UTC
+    generated_at = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    # Build error data depending on exception type
+    error_data: dict[str, Any] = {
+        "error_type": type(exc).__name__,
+    }
+
+    if isinstance(exc, SCCError):
+        error_data["user_message"] = exc.user_message
+        if exc.suggested_action:
+            error_data["suggested_action"] = exc.suggested_action
+        if exc.debug_context:
+            error_data["debug_context"] = exc.debug_context
+        error_message = exc.user_message
+    else:
+        error_message = str(exc)
+
+    return {
+        "apiVersion": API_VERSION,
+        "kind": str(Kind.ERROR.value),
+        "metadata": {
+            "generatedAt": generated_at,
+            "cliVersion": __version__,
+        },
+        "status": {
+            "ok": False,
+            "errors": [error_message],
+            "warnings": [],
+        },
+        "data": error_data,
+    }

scc_cli/kinds.py

@@ -0,0 +1,65 @@
+"""Define centralized JSON envelope kind names to prevent drift.
+
+Define all JSON envelope `kind` values here as enum members.
+This prevents inconsistencies like "TeamList" vs "TeamsList" across the codebase.
+
+Usage:
+    from scc_cli.kinds import Kind
+
+    envelope = build_envelope(Kind.TEAM_LIST, data={...})
+"""
+
+from enum import Enum
+
+
+class Kind(str, Enum):
+    """Define JSON envelope kind identifiers.
+
+    Inherit from str so enum values serialize directly to JSON without .value.
+    Add new kinds here to ensure consistency across all commands.
+    """
+
+    # Team commands
+    TEAM_LIST = "TeamList"
+    TEAM_INFO = "TeamInfo"
+    TEAM_CURRENT = "TeamCurrent"
+    TEAM_SWITCH = "TeamSwitch"
+    TEAM_VALIDATE = "TeamValidate"
+
+    # Status/Doctor
+    STATUS = "Status"
+    DOCTOR_REPORT = "DoctorReport"
+
+    # Worktree commands
+    WORKTREE_LIST = "WorktreeList"
+    WORKTREE_CREATE = "WorktreeCreate"
+    WORKTREE_REMOVE = "WorktreeRemove"
+
+    # Session/Container
+    SESSION_LIST = "SessionList"
+    CONTAINER_LIST = "ContainerList"
+
+    # Org admin
+    ORG_VALIDATION = "OrgValidation"
+    ORG_SCHEMA = "OrgSchema"
+    ORG_STATUS = "OrgStatus"
+    ORG_IMPORT = "OrgImport"
+    ORG_IMPORT_PREVIEW = "OrgImportPreview"
+    ORG_INIT = "OrgInit"
+    ORG_TEMPLATE_LIST = "OrgTemplateList"
+    ORG_UPDATE = "OrgUpdate"
+
+    # Support
+    SUPPORT_BUNDLE = "SupportBundle"
+
+    # Config
+    CONFIG_EXPLAIN = "ConfigExplain"
+
+    # Start
+    START_DRY_RUN = "StartDryRun"
+
+    # Init
+    INIT_RESULT = "InitResult"
+
+    # Error (used by handle_errors in JSON mode)
+    ERROR = "Error"

scc_cli/marketplace/__init__.py

@@ -0,0 +1,123 @@
+"""
+Marketplace and plugin management for SCC.
+
+This package provides organization-level plugin governance with:
+- Multi-source marketplace definitions (GitHub, Git, URL, directory)
+- Team-based plugin sets with org defaults inheritance
+- Security policies (blocked plugins with audit trail)
+- Project-local materialization for Docker sandbox compatibility
+
+Public API:
+    - Schema models: OrgConfig, MarketplaceSource, TeamProfile, SecurityConfig
+    - Constants: IMPLICIT_MARKETPLACES, EXIT_CODES
+    - Normalization: normalize_plugin(), matches_pattern()
+    - Computation: compute_effective_plugins(), EffectivePlugins
+    - Materialization: materialize_marketplace(), MaterializedMarketplace
+    - Settings: render_settings(), merge_settings()
+    - State: ManagedState, load_managed_state(), save_managed_state()
+
+Example:
+    >>> from scc_cli.marketplace import OrgConfig, compute_effective_plugins
+    >>> config = OrgConfig.model_validate(json_data)
+    >>> effective = compute_effective_plugins(config, team_id="backend")
+    >>> print(effective.enabled_plugins)
+"""
+
+from scc_cli.marketplace.compute import (
+    BlockedPlugin,
+    EffectivePlugins,
+    TeamNotFoundError,
+    compute_effective_plugins,
+)
+from scc_cli.marketplace.constants import (
+    EXIT_CODES,
+    IMPLICIT_MARKETPLACES,
+    MANAGED_STATE_FILE,
+    MARKETPLACE_CACHE_DIR,
+)
+
+# Managed State
+from scc_cli.marketplace.managed import (
+    ManagedState,
+    clear_managed_state,
+    load_managed_state,
+    save_managed_state,
+)
+
+# Materialization
+from scc_cli.marketplace.materialize import (
+    GitNotAvailableError,
+    InvalidMarketplaceError,
+    MaterializationError,
+    MaterializedMarketplace,
+    materialize_marketplace,
+)
+from scc_cli.marketplace.normalize import (
+    AmbiguousMarketplaceError,
+    InvalidPluginRefError,
+    matches_any_pattern,
+    matches_pattern,
+    normalize_plugin,
+)
+
+# Rendering
+from scc_cli.marketplace.render import (
+    check_conflicts,
+    merge_settings,
+    render_settings,
+)
+from scc_cli.marketplace.schema import (
+    DefaultsConfig,
+    MarketplaceSource,
+    MarketplaceSourceDirectory,
+    MarketplaceSourceGit,
+    MarketplaceSourceGitHub,
+    MarketplaceSourceURL,
+    OrganizationConfig,
+    SecurityConfig,
+    TeamProfile,
+)
+
+__all__ = [
+    # Constants
+    "EXIT_CODES",
+    "IMPLICIT_MARKETPLACES",
+    "MARKETPLACE_CACHE_DIR",
+    "MANAGED_STATE_FILE",
+    # Schema models
+    "OrganizationConfig",
+    "MarketplaceSource",
+    "MarketplaceSourceGitHub",
+    "MarketplaceSourceGit",
+    "MarketplaceSourceURL",
+    "MarketplaceSourceDirectory",
+    "TeamProfile",
+    "SecurityConfig",
+    "DefaultsConfig",
+    # Normalization
+    "normalize_plugin",
+    "matches_pattern",
+    "matches_any_pattern",
+    "InvalidPluginRefError",
+    "AmbiguousMarketplaceError",
+    # Computation
+    "compute_effective_plugins",
+    "EffectivePlugins",
+    "BlockedPlugin",
+    "TeamNotFoundError",
+    # Materialization
+    "materialize_marketplace",
+    "MaterializedMarketplace",
+    "MaterializationError",
+    "GitNotAvailableError",
+    "InvalidMarketplaceError",
+    # Rendering
+    "render_settings",
+    "merge_settings",
+    "check_conflicts",
+    # Managed state
+    "ManagedState",
+    "load_managed_state",
+    "save_managed_state",
+    "clear_managed_state",
+]

scc_cli/marketplace/adapter.py

@@ -0,0 +1,74 @@
+"""
+Adapter for translating external org config format to internal Pydantic format.
+
+This module implements the Anti-Corruption Layer pattern between:
+- External format (JSON Schema): Human-readable, semver strings, nested organization
+- Internal format (Pydantic): Python-native types, integer versioning, flat structure
+
+The translation happens AFTER JSON Schema validation (Validation Gate) but
+BEFORE Pydantic model_validate() to ensure proper type conversion.
+"""
+
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+
+def translate_org_config(external: dict[str, Any]) -> dict[str, Any]:
+    """Translate external JSON format to internal Pydantic format.
+
+    External format (from org config JSON):
+      - organization.name, organization.id (nested)
+      - schema_version: "1.0.0" (semver string)
+
+    Internal format (for Pydantic):
+      - name (flat at root level)
+      - schema_version: 1 (integer, major version only)
+
+    Uses deepcopy to prevent side-effects on cached external configuration.
+
+    Args:
+        external: External org config dict (from cache or remote fetch)
+
+    Returns:
+        Internal format dict ready for Pydantic model_validate()
+
+    Examples:
+        >>> external = {
+        ...     "schema_version": "1.0.0",
+        ...     "organization": {"name": "Acme Corp", "id": "acme"},
+        ...     "profiles": {}
+        ... }
+        >>> internal = translate_org_config(external)
+        >>> internal["name"]
+        'Acme Corp'
+        >>> internal["schema_version"]
+        1
+    """
+    # Use deepcopy to prevent cache poisoning via shallow copy mutations
+    internal = copy.deepcopy(external)
+
+    # ── Flatten organization object ───────────────────────────────────────────
+    # Pop the nested organization structure, default to empty dict if missing
+    org_data = internal.pop("organization", {})
+
+    # Only map 'name' if it wasn't already at the top level (precedence rule)
+    # This handles the case where config is already in internal format
+    if "name" not in internal and "name" in org_data:
+        internal["name"] = org_data["name"]
+
+    # ── Convert semver string to integer ──────────────────────────────────────
+    raw_version = internal.get("schema_version")
+    if isinstance(raw_version, str):
+        # Remove common 'v' prefix if present (e.g., "v1.0.0" -> "1.0.0")
+        clean_version = raw_version.lstrip("vV")
+        try:
+            # Handle both "1.0.0" -> 1 and "1" -> 1
+            internal["schema_version"] = int(clean_version.split(".")[0])
+        except ValueError:
+            # If parsing fails, leave as-is; Pydantic will catch the type error
+            # and provide better error context than a generic ValueError
+            pass
+
+    return internal