scc-cli 1.4.0__py3-none-any.whl

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 .errors import ConfigError, PolicyViolationError, PrerequisiteError, SCCError
+from .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

scc_cli/json_output.py

@@ -0,0 +1,96 @@
+"""
+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 .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,
+    }

scc_cli/kinds.py

@@ -0,0 +1,62 @@
+"""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"

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",
+]