scc-cli 1.4.1__py3-none-any.whl

scc_cli/models/plugin_audit.py

@@ -0,0 +1,434 @@
+"""Define data models for plugin audit feature.
+
+Provide models for auditing Claude Code plugins, including manifest
+parsing results and status reporting.
+
+The audit feature gives visibility into plugin components (MCP servers,
+hooks) without enforcing any policies.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+
+class ManifestStatus(str, Enum):
+    """Status of a manifest file parsing attempt."""
+
+    PARSED = "parsed"
+    """Manifest found and successfully parsed."""
+
+    MISSING = "missing"
+    """Manifest file not found at expected location."""
+
+    UNREADABLE = "unreadable"
+    """Manifest exists but cannot be read (permission error)."""
+
+    MALFORMED = "malformed"
+    """Manifest exists but contains invalid JSON."""
+
+
+@dataclass
+class ParseError:
+    """Details of a JSON parse error with location info."""
+
+    message: str
+    """Human-readable error message."""
+
+    line: int | None = None
+    """Line number where error occurred (1-indexed), if available."""
+
+    column: int | None = None
+    """Column number where error occurred (1-indexed), if available."""
+
+    @classmethod
+    def from_json_error(cls, error: json.JSONDecodeError) -> ParseError:
+        """Create ParseError from a JSONDecodeError.
+
+        Args:
+            error: The JSON decode error with position info.
+
+        Returns:
+            ParseError with line/column if available.
+        """
+        return cls(
+            message=error.msg,
+            line=error.lineno,
+            column=error.colno,
+        )
+
+    def format(self) -> str:
+        """Format error for display.
+
+        Returns:
+            Formatted string like "line 15, col 8: Expected ',' but found '}'"
+        """
+        if self.line is not None and self.column is not None:
+            return f"line {self.line}, col {self.column}: {self.message}"
+        elif self.line is not None:
+            return f"line {self.line}: {self.message}"
+        else:
+            return self.message
+
+
+@dataclass
+class ManifestResult:
+    """Result of parsing a single manifest file."""
+
+    status: ManifestStatus
+    """The parsing status."""
+
+    path: Path | None = None
+    """Path to the manifest file (relative to plugin root)."""
+
+    content: dict[str, Any] | None = None
+    """Parsed content if status is PARSED."""
+
+    error: ParseError | None = None
+    """Parse error details if status is MALFORMED."""
+
+    error_message: str | None = None
+    """Raw error message for UNREADABLE status."""
+
+    @property
+    def is_ok(self) -> bool:
+        """Check if manifest was successfully parsed or is cleanly missing.
+
+        Returns:
+            True if status is PARSED or MISSING (clean states).
+        """
+        return self.status in (ManifestStatus.PARSED, ManifestStatus.MISSING)
+
+    @property
+    def has_problems(self) -> bool:
+        """Check if manifest has problems that should fail CI.
+
+        Returns:
+            True if status is MALFORMED or UNREADABLE.
+        """
+        return self.status in (ManifestStatus.MALFORMED, ManifestStatus.UNREADABLE)
+
+
+@dataclass
+class MCPServerInfo:
+    """Extracted information about an MCP server from manifest."""
+
+    name: str
+    """Server name/identifier."""
+
+    transport: str
+    """Transport type: 'stdio', 'http', 'sse', etc."""
+
+    command: str | None = None
+    """Command to run (for stdio transport)."""
+
+    url: str | None = None
+    """URL (for http/sse transport)."""
+
+    description: str | None = None
+    """Server description if provided."""
+
+
+@dataclass
+class HookInfo:
+    """Extracted information about a hook from manifest."""
+
+    event: str
+    """Event type: 'PreToolUse', 'PostToolUse', etc."""
+
+    hook_type: str
+    """Hook type: 'command', 'prompt', 'agent'."""
+
+    matcher: str | None = None
+    """Matcher pattern if specified."""
+
+
+@dataclass
+class PluginManifests:
+    """Aggregated manifest information for a plugin."""
+
+    mcp: ManifestResult
+    """Result of parsing .mcp.json."""
+
+    hooks: ManifestResult
+    """Result of parsing hooks/hooks.json or inline hooks."""
+
+    plugin_json: ManifestResult | None = None
+    """Result of parsing .claude-plugin/plugin.json (optional)."""
+
+    @property
+    def has_declarations(self) -> bool:
+        """Check if plugin has any component declarations.
+
+        Returns:
+            True if MCP or hooks manifests exist and are parsed.
+        """
+        return (
+            self.mcp.status == ManifestStatus.PARSED or self.hooks.status == ManifestStatus.PARSED
+        )
+
+    @property
+    def has_problems(self) -> bool:
+        """Check if any manifest has problems.
+
+        Returns:
+            True if any manifest is MALFORMED or UNREADABLE.
+        """
+        return self.mcp.has_problems or self.hooks.has_problems
+
+    @property
+    def mcp_servers(self) -> list[MCPServerInfo]:
+        """Extract MCP server info from parsed manifest.
+
+        Returns:
+            List of MCPServerInfo from .mcp.json content.
+        """
+        if self.mcp.status != ManifestStatus.PARSED or self.mcp.content is None:
+            return []
+
+        servers = []
+        mcp_servers = self.mcp.content.get("mcpServers", {})
+        if not isinstance(mcp_servers, dict):
+            return []
+        for name, config in mcp_servers.items():
+            if not isinstance(config, dict):
+                continue
+            transport = config.get("transport", "stdio")
+            servers.append(
+                MCPServerInfo(
+                    name=name,
+                    transport=transport,
+                    command=config.get("command"),
+                    url=config.get("url"),
+                    description=config.get("description"),
+                )
+            )
+        return servers
+
+    @property
+    def hooks_info(self) -> list[HookInfo]:
+        """Extract hook info from parsed manifest.
+
+        Returns:
+            List of HookInfo from hooks content.
+        """
+        if self.hooks.status != ManifestStatus.PARSED or self.hooks.content is None:
+            return []
+
+        hooks_list = []
+        hooks_config = self.hooks.content.get("hooks", {})
+        if not isinstance(hooks_config, dict):
+            return []
+        for event, event_hooks in hooks_config.items():
+            if isinstance(event_hooks, list):
+                for hook_group in event_hooks:
+                    matcher = hook_group.get("matcher")
+                    for hook in hook_group.get("hooks", []):
+                        hooks_list.append(
+                            HookInfo(
+                                event=event,
+                                hook_type=hook.get("type", "unknown"),
+                                matcher=matcher,
+                            )
+                        )
+        return hooks_list
+
+
+@dataclass
+class PluginAuditResult:
+    """Full audit result for a single plugin."""
+
+    plugin_id: str
+    """Plugin identifier in format 'name@marketplace'."""
+
+    plugin_name: str
+    """Plugin name (without marketplace)."""
+
+    marketplace: str
+    """Marketplace name."""
+
+    version: str
+    """Installed version."""
+
+    install_path: Path | None = None
+    """Absolute path to installed plugin, if installed."""
+
+    installed: bool = False
+    """Whether the plugin is currently installed."""
+
+    manifests: PluginManifests | None = None
+    """Manifest parsing results, if installed."""
+
+    @property
+    def status_summary(self) -> str:
+        """Get a summary status for the plugin.
+
+        Returns:
+            Summary string: 'clean', 'parsed', 'malformed', 'unreadable', 'not installed'
+        """
+        if not self.installed:
+            return "not installed"
+
+        if self.manifests is None:
+            return "unknown"
+
+        if self.manifests.has_problems:
+            # Report the worst status
+            if self.manifests.mcp.status == ManifestStatus.MALFORMED:
+                return "malformed"
+            if self.manifests.hooks.status == ManifestStatus.MALFORMED:
+                return "malformed"
+            return "unreadable"
+
+        if self.manifests.has_declarations:
+            return "parsed"
+
+        return "clean"
+
+    @property
+    def has_ci_failures(self) -> bool:
+        """Check if this plugin should cause CI failure.
+
+        Returns:
+            True if any manifest is malformed or unreadable.
+        """
+        if self.manifests is None:
+            return False
+        return self.manifests.has_problems
+
+
+@dataclass
+class AuditOutput:
+    """Overall audit output for all plugins."""
+
+    schema_version: int = 1
+    """Schema version for JSON output."""
+
+    plugins: list[PluginAuditResult] = field(default_factory=list)
+    """Results for each audited plugin."""
+
+    warnings: list[str] = field(default_factory=list)
+    """Warning messages (non-fatal issues)."""
+
+    @property
+    def total_plugins(self) -> int:
+        """Total number of plugins audited."""
+        return len(self.plugins)
+
+    @property
+    def clean_count(self) -> int:
+        """Number of clean plugins (no declarations)."""
+        return sum(1 for p in self.plugins if p.status_summary == "clean")
+
+    @property
+    def parsed_count(self) -> int:
+        """Number of plugins with parsed manifests."""
+        return sum(1 for p in self.plugins if p.status_summary == "parsed")
+
+    @property
+    def problem_count(self) -> int:
+        """Number of plugins with problems."""
+        return sum(1 for p in self.plugins if p.has_ci_failures)
+
+    @property
+    def has_ci_failures(self) -> bool:
+        """Check if any plugin should cause CI failure.
+
+        Returns:
+            True if any plugin has malformed or unreadable manifests.
+        """
+        return any(p.has_ci_failures for p in self.plugins)
+
+    @property
+    def exit_code(self) -> int:
+        """Get CI exit code.
+
+        Returns:
+            0 if all plugins OK, 1 if any have problems.
+        """
+        return 1 if self.has_ci_failures else 0
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization.
+
+        Returns:
+            Dict with schemaVersion and structured plugin data.
+        """
+        return {
+            "schemaVersion": self.schema_version,
+            "summary": {
+                "total": self.total_plugins,
+                "clean": self.clean_count,
+                "parsed": self.parsed_count,
+                "problems": self.problem_count,
+            },
+            "plugins": [self._plugin_to_dict(p) for p in self.plugins],
+            "warnings": self.warnings,
+        }
+
+    def _plugin_to_dict(self, plugin: PluginAuditResult) -> dict[str, Any]:
+        """Convert a single plugin result to dictionary."""
+        result: dict[str, Any] = {
+            "pluginId": plugin.plugin_id,
+            "name": plugin.plugin_name,
+            "marketplace": plugin.marketplace,
+            "version": plugin.version,
+            "installed": plugin.installed,
+            "status": plugin.status_summary,
+        }
+
+        if plugin.install_path:
+            # Use relative path for security (don't leak full paths in CI logs)
+            try:
+                result["installPath"] = str(plugin.install_path.relative_to(Path.home()))
+            except ValueError:
+                # Path not under home, use just the name
+                result["installPath"] = plugin.install_path.name
+
+        if plugin.manifests:
+            result["manifests"] = {
+                "mcp": self._manifest_to_dict(plugin.manifests.mcp),
+                "hooks": self._manifest_to_dict(plugin.manifests.hooks),
+            }
+
+            # Add extracted component info
+            if plugin.manifests.mcp_servers:
+                result["mcpServers"] = [
+                    {
+                        "name": s.name,
+                        "transport": s.transport,
+                        "description": s.description,
+                    }
+                    for s in plugin.manifests.mcp_servers
+                ]
+
+            if plugin.manifests.hooks_info:
+                result["hooks"] = [
+                    {
+                        "event": h.event,
+                        "type": h.hook_type,
+                        "matcher": h.matcher,
+                    }
+                    for h in plugin.manifests.hooks_info
+                ]
+
+        return result
+
+    def _manifest_to_dict(self, manifest: ManifestResult) -> dict[str, Any]:
+        """Convert manifest result to dictionary."""
+        result: dict[str, Any] = {"status": manifest.status.value}
+
+        if manifest.path:
+            result["path"] = str(manifest.path)
+
+        if manifest.error:
+            result["error"] = manifest.error.format()
+
+        if manifest.error_message:
+            result["errorMessage"] = manifest.error_message
+
+        return result

scc_cli/org_templates.py

@@ -0,0 +1,269 @@
+"""
+Organization config template loading and generation.
+
+Provides template-based skeleton generation for `scc org init`.
+Templates are bundled JSON files with placeholder substitutions.
+
+Key functions:
+- list_templates(): List available template names with descriptions
+- load_template(): Load a template with variable substitutions
+- render_template(): Generate JSON output for a template
+
+Template naming convention:
+- minimal: Minimal quickstart config
+- teams: Multi-team with profiles
+- strict: Strict security for regulated industries
+- reference: Complete reference with all fields
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from importlib.resources import files
+from typing import Any, cast
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Template Registry
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+@dataclass(frozen=True)
+class TemplateInfo:
+    """Metadata about an available template.
+
+    Attributes:
+        name: Template identifier (e.g., "minimal", "teams").
+        description: Human-readable description.
+        level: Complexity level ("beginner", "intermediate", "advanced").
+        use_case: Primary use case description.
+    """
+
+    name: str
+    description: str
+    level: str
+    use_case: str
+
+
+# Available templates with metadata
+TEMPLATES: dict[str, TemplateInfo] = {
+    "minimal": TemplateInfo(
+        name="minimal",
+        description="Minimal quickstart config",
+        level="beginner",
+        use_case="First-time setup, single team, sensible defaults",
+    ),
+    "teams": TemplateInfo(
+        name="teams",
+        description="Multi-team with profiles and delegation",
+        level="intermediate",
+        use_case="Organizations with multiple teams needing different configs",
+    ),
+    "strict": TemplateInfo(
+        name="strict",
+        description="Strict security for regulated industries",
+        level="advanced",
+        use_case="Financial, healthcare, or compliance-heavy environments",
+    ),
+    "reference": TemplateInfo(
+        name="reference",
+        description="Complete reference with all fields",
+        level="reference",
+        use_case="Documentation and learning all available options",
+    ),
+}
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Template Loading
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+class TemplateNotFoundError(Exception):
+    """Raised when a template name is not recognized."""
+
+    def __init__(self, name: str, available: list[str]) -> None:
+        self.name = name
+        self.available = available
+        super().__init__(
+            f"Unknown template '{name}'. Available templates: {', '.join(sorted(available))}"
+        )
+
+
+def list_templates() -> list[TemplateInfo]:
+    """List all available templates with metadata.
+
+    Returns:
+        List of TemplateInfo objects describing each template.
+
+    Example:
+        >>> templates = list_templates()
+        >>> templates[0].name
+        'minimal'
+    """
+    return list(TEMPLATES.values())
+
+
+def get_template_info(name: str) -> TemplateInfo:
+    """Get metadata for a specific template.
+
+    Args:
+        name: Template identifier.
+
+    Returns:
+        TemplateInfo for the requested template.
+
+    Raises:
+        TemplateNotFoundError: If template name is not recognized.
+    """
+    if name not in TEMPLATES:
+        raise TemplateNotFoundError(name, list(TEMPLATES.keys()))
+    return TEMPLATES[name]
+
+
+def load_template_raw(name: str) -> str:
+    """Load raw template content from package resources.
+
+    Args:
+        name: Template identifier (e.g., "minimal", "teams").
+
+    Returns:
+        Raw template content as string (with placeholders).
+
+    Raises:
+        TemplateNotFoundError: If template name is not recognized.
+        FileNotFoundError: If template file doesn't exist.
+    """
+    # Validate template name exists
+    if name not in TEMPLATES:
+        raise TemplateNotFoundError(name, list(TEMPLATES.keys()))
+
+    # Load from package resources
+    template_file = files("scc_cli.templates.org").joinpath(f"{name}.json")
+    try:
+        return template_file.read_text()
+    except FileNotFoundError:
+        raise FileNotFoundError(f"Template file '{name}.json' not found in package")
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Template Rendering
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+@dataclass
+class TemplateVars:
+    """Variables for template substitution.
+
+    Attributes:
+        org_name: Organization name (e.g., "acme-corp").
+        org_domain: Organization domain (e.g., "acme.com").
+        schema_version: Schema version (default: "1.0.0").
+        min_cli_version: Minimum CLI version (default: "1.2.0").
+    """
+
+    org_name: str = "my-org"
+    org_domain: str = "example.com"
+    schema_version: str = "1.0.0"
+    min_cli_version: str = "1.2.0"
+
+
+def render_template(
+    name: str,
+    vars: TemplateVars | None = None,
+) -> dict[str, Any]:
+    """Render a template with variable substitutions.
+
+    Template placeholders use the format {{VAR_NAME}}.
+    Supported placeholders:
+    - {{ORG_NAME}}: Organization name
+    - {{ORG_DOMAIN}}: Organization domain
+    - {{SCHEMA_VERSION}}: Schema version
+    - {{MIN_CLI_VERSION}}: Minimum CLI version
+
+    Args:
+        name: Template identifier.
+        vars: Template variables for substitution.
+
+    Returns:
+        Rendered template as a dict.
+
+    Raises:
+        TemplateNotFoundError: If template name is not recognized.
+        json.JSONDecodeError: If rendered template is not valid JSON.
+
+    Example:
+        >>> result = render_template("minimal", TemplateVars(org_name="acme"))
+        >>> result["name"]
+        'acme'
+    """
+    if vars is None:
+        vars = TemplateVars()
+
+    # Load raw template
+    raw = load_template_raw(name)
+
+    # Apply substitutions
+    substitutions = {
+        "{{ORG_NAME}}": vars.org_name,
+        "{{ORG_DOMAIN}}": vars.org_domain,
+        "{{SCHEMA_VERSION}}": vars.schema_version,
+        "{{MIN_CLI_VERSION}}": vars.min_cli_version,
+    }
+
+    rendered = raw
+    for placeholder, value in substitutions.items():
+        rendered = rendered.replace(placeholder, value)
+
+    # Parse as JSON
+    return cast(dict[str, Any], json.loads(rendered))
+
+
+def render_template_string(
+    name: str,
+    vars: TemplateVars | None = None,
+    indent: int = 2,
+) -> str:
+    """Render a template as a formatted JSON string.
+
+    This is useful for --stdout output or file writing.
+
+    Args:
+        name: Template identifier.
+        vars: Template variables for substitution.
+        indent: JSON indentation level (default: 2).
+
+    Returns:
+        Formatted JSON string.
+
+    Example:
+        >>> output = render_template_string("minimal")
+        >>> print(output)
+        {
+          "name": "my-org",
+          ...
+        }
+    """
+    data = render_template(name, vars)
+    return json.dumps(data, indent=indent, ensure_ascii=False)
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Validation
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+def validate_template_name(name: str) -> None:
+    """Validate that a template name is recognized.
+
+    This is a strict validation that raises an error for unknown names.
+    Use this before any operation that requires a valid template.
+
+    Args:
+        name: Template name to validate.
+
+    Raises:
+        TemplateNotFoundError: If template name is not recognized.
+    """
+    if name not in TEMPLATES:
+        raise TemplateNotFoundError(name, list(TEMPLATES.keys()))