icdev 0.0.3__py3-none-any.whl

tools/ci/__init__.py

@@ -0,0 +1,2 @@
+# [TEMPLATE: CUI // SP-CTI]
+# SPARKPILOT CI/CD Integration — GitHub + GitLab dual support

tools/ci/connectors/__init__.py

@@ -0,0 +1,2 @@
+# [TEMPLATE: CUI // SP-CTI]
+# SPARKPILOT CI/CD Connectors — Slack, Mattermost, and marketplace chat plugins

tools/ci/connectors/base_connector.py

@@ -0,0 +1,80 @@
+# [TEMPLATE: CUI // SP-CTI]
+# SPARKPILOT Chat Connector ABC — base class for all chat platform connectors (D66, D136)
+
+"""
+Abstract base class for chat platform connectors.
+
+All built-in and marketplace chat connectors must implement this ABC.
+Provides a consistent interface for inbound event parsing, outbound messaging,
+and webhook signature verification.
+
+Architecture Decisions:
+    D66: Provider abstraction pattern (ABC + implementations)
+    D136: Slack and Mattermost are built-in connectors with enable/disable toggles;
+          additional platforms via marketplace plugins
+
+Usage:
+    class MyConnector(ChatConnectorAdapter):
+        connector_name = "my_platform"
+        ...
+"""
+
+from abc import ABC, abstractmethod
+from typing import Optional
+
+from tools.ci.core.event_envelope import EventEnvelope
+
+
+class ChatConnectorAdapter(ABC):
+    """Abstract base class for all chat platform connectors."""
+
+    @property
+    @abstractmethod
+    def connector_name(self) -> str:
+        """Unique connector name (e.g., 'slack', 'mattermost')."""
+        ...
+
+    @abstractmethod
+    def parse_inbound(self, raw_payload: dict) -> Optional[EventEnvelope]:
+        """Parse an inbound webhook payload into an EventEnvelope.
+
+        Returns None if the event should be ignored (e.g., bot message, challenge).
+        """
+        ...
+
+    @abstractmethod
+    def send_message(
+        self, channel_id: str, text: str, thread_id: str = None,
+    ) -> bool:
+        """Send a message to a channel/thread.
+
+        Args:
+            channel_id: Platform-specific channel ID.
+            text: Message text.
+            thread_id: Thread ID for threaded replies (D137: always use threads).
+
+        Returns:
+            True if message sent successfully, False otherwise.
+        """
+        ...
+
+    @abstractmethod
+    def verify_signature(self, raw_body: bytes, signature: str) -> bool:
+        """Verify webhook request signature.
+
+        Args:
+            raw_body: Raw request body bytes.
+            signature: Signature header value from the request.
+
+        Returns:
+            True if signature is valid.
+        """
+        ...
+
+    def get_webhook_route(self) -> str:
+        """Return the webhook route path for this connector."""
+        return f"/chat/{self.connector_name}"
+
+    def is_enabled(self) -> bool:
+        """Check if this connector is enabled in config."""
+        return True

tools/ci/connectors/connector_registry.py

@@ -0,0 +1,188 @@
+# [TEMPLATE: CUI // SP-CTI]
+# SPARKPILOT Connector Registry — plugin registry + route registration (D66, D136)
+
+"""
+Central registry for all chat platform connectors.
+
+Loads enabled connectors from cicd_config.yaml, instantiates them,
+and registers Flask routes for their webhook endpoints.
+
+Architecture Decisions:
+    D66: Provider abstraction pattern (ABC + implementations)
+    D136: Built-in connectors (Slack, Mattermost) with enable/disable toggles;
+          marketplace plugins can register additional connectors
+
+Usage:
+    from tools.ci.connectors.connector_registry import ConnectorRegistry
+
+    # At application startup
+    ConnectorRegistry.load_from_config()
+    ConnectorRegistry.register_routes(app)
+
+    # Get a connector for sending messages
+    slack = ConnectorRegistry.get_connector("slack")
+    if slack:
+        slack.send_message(channel_id, "Hello", thread_id=ts)
+"""
+
+from pathlib import Path
+from typing import Dict, Optional
+
+from tools.ci.connectors.base_connector import ChatConnectorAdapter
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent.parent
+
+
+class ConnectorRegistry:
+    """Central registry for chat platform connectors."""
+
+    _connectors: Dict[str, ChatConnectorAdapter] = {}
+
+    @classmethod
+    def load_from_config(cls, config: dict = None):
+        """Load and register enabled connectors from cicd_config.yaml.
+
+        Args:
+            config: Optional pre-loaded config dict. If None, loads from file.
+        """
+        if config is None:
+            config = cls._load_config()
+
+        channels = config.get("cicd", {}).get("channels", {})
+
+        # Slack
+        slack_config = channels.get("slack", {})
+        if slack_config.get("enabled", False):
+            try:
+                from tools.ci.connectors.slack_connector import SlackConnector
+                connector = SlackConnector(slack_config)
+                cls.register(connector)
+                print("[ConnectorRegistry] Slack connector registered")
+            except ImportError as e:
+                print(f"[ConnectorRegistry] Slack connector unavailable: {e}")
+
+        # Mattermost
+        mm_config = channels.get("mattermost", {})
+        if mm_config.get("enabled", False):
+            try:
+                from tools.ci.connectors.mattermost_connector import MattermostConnector
+                connector = MattermostConnector(mm_config)
+                cls.register(connector)
+                print("[ConnectorRegistry] Mattermost connector registered")
+            except ImportError as e:
+                print(f"[ConnectorRegistry] Mattermost connector unavailable: {e}")
+
+    @classmethod
+    def register(cls, connector: ChatConnectorAdapter):
+        """Register a connector."""
+        cls._connectors[connector.connector_name] = connector
+
+    @classmethod
+    def unregister(cls, name: str):
+        """Unregister a connector."""
+        cls._connectors.pop(name, None)
+
+    @classmethod
+    def get_connector(cls, name: str) -> Optional[ChatConnectorAdapter]:
+        """Get a registered connector by name."""
+        return cls._connectors.get(name)
+
+    @classmethod
+    def list_connectors(cls) -> Dict[str, bool]:
+        """List all registered connectors with their enabled status."""
+        return {
+            name: connector.is_enabled()
+            for name, connector in cls._connectors.items()
+        }
+
+    @classmethod
+    def register_routes(cls, app):
+        """Register Flask routes for all enabled connectors.
+
+        Args:
+            app: Flask application instance.
+        """
+        from tools.ci.core.event_router import EventRouter
+
+        router = EventRouter()
+
+        for name, connector in cls._connectors.items():
+            if not connector.is_enabled():
+                continue
+
+            route_path = connector.get_webhook_route()
+            cls._create_route(app, connector, router, route_path)
+
+    @classmethod
+    def _create_route(cls, app, connector, router, route_path):
+        """Create a Flask route for a connector."""
+
+        def make_handler(conn, rtr):
+            def handler():
+                from flask import request, jsonify
+
+                # Verify signature
+                raw_body = request.get_data()
+                signature = (
+                    request.headers.get("X-Slack-Signature", "")
+                    or request.headers.get("X-Mattermost-Signature", "")
+                    or request.headers.get("X-Signature", "")
+                )
+
+                # For Slack, prepend timestamp for signature verification
+                if conn.connector_name == "slack":
+                    timestamp = request.headers.get(
+                        "X-Slack-Request-Timestamp", ""
+                    )
+                    signature = f"{timestamp}:{signature}" if timestamp else signature
+
+                if signature and not conn.verify_signature(raw_body, signature):
+                    return jsonify({"error": "invalid_signature"}), 401
+
+                # Parse payload
+                payload = request.get_json(silent=True) or {}
+
+                # Handle Slack URL verification challenge
+                if (
+                    conn.connector_name == "slack"
+                    and payload.get("type") == "url_verification"
+                ):
+                    return jsonify({"challenge": payload.get("challenge", "")})
+
+                # Parse inbound event
+                envelope = conn.parse_inbound(payload)
+                if not envelope:
+                    return jsonify({"status": "ignored"}), 200
+
+                # Route through EventRouter
+                result = rtr.route(envelope)
+                return jsonify(result), 200
+
+            handler.__name__ = f"{conn.connector_name}_webhook_handler"
+            return handler
+
+        app.add_url_rule(
+            route_path,
+            endpoint=f"{connector.connector_name}_webhook",
+            view_func=make_handler(connector, router),
+            methods=["POST"],
+        )
+        print(f"[ConnectorRegistry] Registered route: POST {route_path}")
+
+    @classmethod
+    def reset(cls):
+        """Clear all registered connectors (for testing)."""
+        cls._connectors.clear()
+
+    @staticmethod
+    def _load_config() -> dict:
+        """Load cicd_config.yaml."""
+        try:
+            import yaml
+            config_path = PROJECT_ROOT / "args" / "cicd_config.yaml"
+            if config_path.exists():
+                with open(config_path) as f:
+                    return yaml.safe_load(f) or {}
+        except Exception:
+            pass
+        return {}

tools/ci/connectors/mattermost_connector.py

@@ -0,0 +1,159 @@
+# [TEMPLATE: CUI // SP-CTI]
+# SPARKPILOT Mattermost Connector — built-in Mattermost integration (D136, D137)
+
+"""
+Built-in Mattermost connector for SPARKPILOT CI/CD.
+
+Mattermost is common in DoD environments (self-hosted, IL4/IL5 compatible).
+
+Handles:
+- Inbound: Mattermost outgoing webhook payloads
+- Outbound: POST /api/v4/posts with threading (D137)
+- Signature: HMAC-SHA256 webhook token verification
+
+Uses only `requests` (existing SPARKPILOT dependency) + stdlib `hmac`/`hashlib`.
+
+Architecture Decisions:
+    D136: Mattermost is a built-in connector with enable/disable toggle
+    D137: All Mattermost responses always use threads (root_id)
+
+Usage:
+    from tools.ci.connectors.mattermost_connector import MattermostConnector
+    connector = MattermostConnector(config)
+    envelope = connector.parse_inbound(payload)
+    connector.send_message(channel_id, "Hello", thread_id=root_id)
+"""
+
+import hashlib
+import hmac
+import os
+from typing import Optional
+
+from tools.ci.connectors.base_connector import ChatConnectorAdapter
+from tools.ci.core.event_envelope import EventEnvelope, BOT_IDENTIFIER
+
+
+class MattermostConnector(ChatConnectorAdapter):
+    """Built-in Mattermost connector."""
+
+    connector_name = "mattermost"
+
+    def __init__(self, config: dict = None):
+        config = config or {}
+        self._server_url = config.get("server_url", "").rstrip("/")
+        self._bot_token = self._resolve_secret(
+            config.get("bot_token_ref", ""),
+            env_var="MATTERMOST_BOT_TOKEN",
+        )
+        self._webhook_secret = self._resolve_secret(
+            config.get("webhook_secret_ref", ""),
+            env_var="MATTERMOST_WEBHOOK_SECRET",
+        )
+        self._default_channel = config.get("default_channel", "")
+        self._thread_mode = config.get("thread_mode", "always")
+        self._enabled = config.get("enabled", False)
+
+    def is_enabled(self) -> bool:
+        return self._enabled
+
+    def verify_signature(self, raw_body: bytes, signature: str) -> bool:
+        """Verify Mattermost outgoing webhook token (HMAC-SHA256)."""
+        if not self._webhook_secret:
+            return False
+
+        computed = hmac.new(
+            self._webhook_secret.encode("utf-8"),
+            raw_body,
+            hashlib.sha256,
+        ).hexdigest()
+
+        return hmac.compare_digest(computed, signature)
+
+    def parse_inbound(self, raw_payload: dict) -> Optional[EventEnvelope]:
+        """Parse Mattermost outgoing webhook payload into EventEnvelope.
+
+        Mattermost outgoing webhooks send:
+            channel_id, channel_name, team_id, team_domain,
+            post_id, text, timestamp, token, trigger_word,
+            user_id, user_name, root_id (thread parent)
+        """
+        text = raw_payload.get("text", "")
+
+        # Ignore bot messages
+        if BOT_IDENTIFIER in text:
+            return None
+
+        user_name = raw_payload.get("user_name", "")
+        if not text or not user_name:
+            return None
+
+        return EventEnvelope.from_mattermost_event(raw_payload)
+
+    def send_message(
+        self, channel_id: str, text: str, thread_id: str = None,
+    ) -> bool:
+        """Send message to Mattermost channel/thread.
+
+        D137: Always threaded — root_id is required for responses.
+        """
+        if not self._bot_token or not self._server_url:
+            print("Warning: Mattermost bot token or server URL not configured")
+            return False
+
+        # Ensure bot identifier
+        if BOT_IDENTIFIER not in text:
+            text = f"{BOT_IDENTIFIER} {text}"
+
+        try:
+            import requests
+
+            payload = {
+                "channel_id": channel_id or self._default_channel,
+                "message": text,
+            }
+
+            # D137: Always use threads for responses
+            if thread_id:
+                payload["root_id"] = thread_id
+
+            response = requests.post(
+                f"{self._server_url}/api/v4/posts",
+                headers={
+                    "Authorization": f"Bearer {self._bot_token}",
+                    "Content-Type": "application/json",
+                },
+                json=payload,
+                timeout=10,
+            )
+
+            if response.status_code in (200, 201):
+                return True
+            else:
+                print(
+                    f"Warning: Mattermost API error: "
+                    f"{response.status_code} {response.text[:200]}"
+                )
+                return False
+
+        except Exception as e:
+            print(f"Warning: Failed to send Mattermost message: {e}")
+            return False
+
+    def _resolve_secret(self, ref: str, env_var: str = "") -> str:
+        """Resolve a secret reference (AWS Secrets Manager or env var)."""
+        if env_var:
+            val = os.environ.get(env_var, "")
+            if val:
+                return val
+
+        if ref and ref.startswith("aws:secretsmanager:"):
+            secret_name = ref.split(":", 2)[-1]
+            try:
+                import boto3
+                client = boto3.client("secretsmanager", region_name="us-gov-west-1")
+                response = client.get_secret_value(SecretId=secret_name)
+                return response.get("SecretString", "")
+            except Exception:
+                pass
+
+        return ""

tools/ci/connectors/slack_connector.py

@@ -0,0 +1,197 @@
+# [TEMPLATE: CUI // SP-CTI]
+# SPARKPILOT Slack Connector — built-in Slack integration (D136, D137)
+
+"""
+Built-in Slack connector for SPARKPILOT CI/CD.
+
+Handles:
+- Inbound: Slack Events API (event_callback, url_verification)
+- Outbound: chat.postMessage with threading (D137)
+- Signature: HMAC-SHA256 request signing verification
+
+Uses only `requests` (existing SPARKPILOT dependency) + stdlib `hmac`/`hashlib`.
+No `slack_sdk` dependency required.
+
+Architecture Decisions:
+    D136: Slack is a built-in connector with enable/disable toggle
+    D137: All Slack responses always use threads
+
+Usage:
+    from tools.ci.connectors.slack_connector import SlackConnector
+    connector = SlackConnector(config)
+    envelope = connector.parse_inbound(payload)
+    connector.send_message(channel_id, "Hello", thread_id=thread_ts)
+"""
+
+import hashlib
+import hmac
+import os
+import time
+from typing import Optional
+
+from tools.ci.connectors.base_connector import ChatConnectorAdapter
+from tools.ci.core.event_envelope import EventEnvelope, BOT_IDENTIFIER
+
+
+SLACK_API_BASE = "https://slack.com/api"
+
+
+class SlackConnector(ChatConnectorAdapter):
+    """Built-in Slack connector."""
+
+    connector_name = "slack"
+
+    def __init__(self, config: dict = None):
+        config = config or {}
+        self._bot_token = self._resolve_secret(
+            config.get("bot_token_ref", ""),
+            env_var="SLACK_BOT_TOKEN",
+        )
+        self._signing_secret = self._resolve_secret(
+            config.get("signing_secret_ref", ""),
+            env_var="SLACK_SIGNING_SECRET",
+        )
+        self._default_channel = config.get("default_channel", "")
+        self._thread_mode = config.get("thread_mode", "always")
+        self._enabled = config.get("enabled", False)
+
+    def is_enabled(self) -> bool:
+        return self._enabled
+
+    def verify_signature(self, raw_body: bytes, signature: str) -> bool:
+        """Verify Slack request signing (HMAC-SHA256).
+
+        Slack signs requests with: v0=HMAC_SHA256(signing_secret, "v0:{timestamp}:{body}")
+        """
+        if not self._signing_secret:
+            return False
+
+        # Extract timestamp from signature header
+        # Signature format: v0=<hex>
+        # Also need X-Slack-Request-Timestamp (passed via signature as "ts:sig")
+        parts = signature.split(":", 1) if ":" in signature else ["", signature]
+        timestamp = parts[0] if len(parts) > 1 else str(int(time.time()))
+        sig_value = parts[-1]
+
+        # Check timestamp freshness (5 minute window)
+        try:
+            ts = int(timestamp)
+            if abs(time.time() - ts) > 300:
+                return False
+        except (ValueError, TypeError):
+            return False
+
+        sig_basestring = f"v0:{timestamp}:{raw_body.decode('utf-8', errors='replace')}"
+        computed = "v0=" + hmac.new(
+            self._signing_secret.encode("utf-8"),
+            sig_basestring.encode("utf-8"),
+            hashlib.sha256,
+        ).hexdigest()
+
+        return hmac.compare_digest(computed, sig_value)
+
+    def parse_inbound(self, raw_payload: dict) -> Optional[EventEnvelope]:
+        """Parse Slack Events API payload into EventEnvelope.
+
+        Handles:
+        - url_verification (challenge response) → returns None
+        - event_callback → message, app_mention
+        """
+        payload_type = raw_payload.get("type", "")
+
+        # URL verification challenge — handled by webhook route directly
+        if payload_type == "url_verification":
+            return None
+
+        if payload_type != "event_callback":
+            return None
+
+        event = raw_payload.get("event", {})
+        event_type = event.get("type", "")
+
+        # Only handle message events and app_mentions
+        if event_type not in ("message", "app_mention"):
+            return None
+
+        # Ignore bot messages
+        if event.get("bot_id") or event.get("subtype") == "bot_message":
+            return None
+
+        text = event.get("text", "")
+        if BOT_IDENTIFIER in text:
+            return None
+
+        event.get("channel", "")
+        event.get("thread_ts", event.get("ts", ""))
+        event.get("user", "")
+
+        return EventEnvelope.from_slack_event(raw_payload)
+
+    def send_message(
+        self, channel_id: str, text: str, thread_id: str = None,
+    ) -> bool:
+        """Send message to Slack channel/thread.
+
+        D137: Always threaded — thread_id is required for responses.
+        """
+        if not self._bot_token:
+            print("Warning: Slack bot token not configured")
+            return False
+
+        # Ensure bot identifier
+        if BOT_IDENTIFIER not in text:
+            text = f"{BOT_IDENTIFIER} {text}"
+
+        try:
+            import requests
+
+            payload = {
+                "channel": channel_id or self._default_channel,
+                "text": text,
+            }
+
+            # D137: Always use threads for responses
+            if thread_id:
+                payload["thread_ts"] = thread_id
+
+            response = requests.post(
+                f"{SLACK_API_BASE}/chat.postMessage",
+                headers={
+                    "Authorization": f"Bearer {self._bot_token}",
+                    "Content-Type": "application/json",
+                },
+                json=payload,
+                timeout=10,
+            )
+
+            result = response.json()
+            if result.get("ok"):
+                return True
+            else:
+                print(f"Warning: Slack API error: {result.get('error', 'unknown')}")
+                return False
+
+        except Exception as e:
+            print(f"Warning: Failed to send Slack message: {e}")
+            return False
+
+    def _resolve_secret(self, ref: str, env_var: str = "") -> str:
+        """Resolve a secret reference (AWS Secrets Manager or env var)."""
+        # Try env var first (development / air-gapped)
+        if env_var:
+            val = os.environ.get(env_var, "")
+            if val:
+                return val
+
+        # Try AWS Secrets Manager
+        if ref and ref.startswith("aws:secretsmanager:"):
+            secret_name = ref.split(":", 2)[-1]
+            try:
+                import boto3
+                client = boto3.client("secretsmanager", region_name="us-gov-west-1")
+                response = client.get_secret_value(SecretId=secret_name)
+                return response.get("SecretString", "")
+            except Exception:
+                pass
+
+        return ""

tools/ci/core/__init__.py

@@ -0,0 +1,2 @@
+# [TEMPLATE: CUI // SP-CTI]
+# SPARKPILOT CI/CD Core — event envelope, routing, conversation, recovery