superkick 0.1.0

data/lib/superkick/integrations/circleci/README.md

@@ -0,0 +1,75 @@
+# CircleCI Monitor
+
+Type: `:circleci`
+
+Polls CircleCI pipelines and workflows for a project and branch. Injects
+context when workflows fail or all pass.
+
+## Configuration
+
+```yaml
+monitors:
+  circleci:
+    token: <%= env("CIRCLECI_TOKEN") %>
+```
+
+| Key | Required | Default | Description |
+|-----|----------|---------|-------------|
+| `project_slug` | yes | auto-detected | CircleCI project slug (e.g. `gh/org/repo`) |
+| `branch` | yes | auto-detected | Git branch to watch |
+| `token` | no | `CIRCLECI_TOKEN` env var | CircleCI API token |
+
+The probe auto-detects `project_slug` and `branch` from `.circleci/config.yml`
+and git remote, so explicit config is only needed to override or when there's
+no local checkout.
+
+## Probe
+
+`CircleCIMonitor::Probe` checks for the presence of `.circleci/config.yml` and
+then reads the git remote URL and current branch. Supports GitHub (`gh/`) and
+Bitbucket (`bb/`) project slugs via both SSH and HTTPS remote formats.
+
+Returns `{ "circleci" => { "type" => "circleci", "project_slug" => "...", "branch" => "..." } }`
+on match, or `{}` if no CircleCI config is found.
+
+## Events
+
+### `ci_failure`
+
+Dispatched when all workflows in the latest pipeline complete and at least one
+has a non-success status. Only fires on status change or new pipeline.
+
+Template variables:
+- `project_slug` — CircleCI project slug
+- `branch` — branch name
+- `pipeline_id` — pipeline UUID
+- `pipeline_number` — pipeline number
+- `failed_workflows` — array of failed workflow names
+- `failed_jobs` — array of failed job names across all failed workflows
+- `workflow_count` — total number of workflows
+
+### `ci_success`
+
+Dispatched when all workflows in the latest pipeline pass. Same trigger logic
+as `ci_failure`.
+
+Template variables: same as `ci_failure`.
+
+## Watermarks
+
+The monitor persists these fields on the agent to avoid duplicate events
+across ticks:
+
+- `last_pipeline_id` — last reported pipeline UUID
+- `last_ci_status` — last reported aggregate status (`"success"` or `"failure"`)
+
+## API usage
+
+The monitor uses the [CircleCI API v2](https://circleci.com/docs/api/v2/) via
+Faraday with the `Circle-Token` header for authentication.
+
+## Error handling
+
+- HTTP 401 → `FatalError` (bad token — stops the monitor)
+- HTTP 429 → `RateLimited` (backs off by `rate_limit_backoff`)
+- HTTP 404 → logged and skipped

data/lib/superkick/integrations/circleci/monitor.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module Superkick
+  module Integrations
+    module CircleCI
+      # Polls CircleCI pipelines and workflows for a project+branch.
+      #
+      # Required per-agent config keys: project_slug, branch
+      # Optional config key: token (or CIRCLECI_TOKEN env var)
+      #
+      # Events emitted: ci_failure, ci_success
+      # Watermarks persisted: last_pipeline_id, last_ci_status
+      class Monitor < Superkick::Monitor
+        TERMINAL_STATUSES = %w[success failed error canceled unauthorized].freeze
+
+        GITHUB_SSH_RE = %r{github\.com[:/](?<org>[^/]+)/(?<repo>[^\s.]+)}
+        GITHUB_HTTPS_RE = %r{github\.com/(?<org>[^/\s]+)/(?<repo>[^\s.]+)}
+        BITBUCKET_SSH_RE = %r{bitbucket\.org[:/](?<org>[^/]+)/(?<repo>[^\s.]+)}
+        BITBUCKET_HTTPS_RE = %r{bitbucket\.org/(?<org>[^/\s]+)/(?<repo>[^\s.]+)}
+
+        attr_reader :conn
+
+        def self.type = :circleci
+
+        def self.description
+          "Monitors CircleCI pipelines for workflow status changes. " \
+            "Injects context when workflows fail or all pass on a branch. " \
+            "Requires a project_slug (e.g. gh/org/repo) and branch. " \
+            "Optionally accepts a token (or set CIRCLECI_TOKEN env var)."
+        end
+
+        def self.required_config = %i[project_slug branch]
+
+        def self.setup_label = "CircleCI"
+
+        def self.setup_config
+          <<~YAML
+            circleci:
+              token: <%= env("CIRCLECI_TOKEN") %>
+              # project_slug and branch are auto-detected from git remote.
+              # Uncomment to override:
+              # project_slug: gh/org/repo
+              # branch: main
+          YAML
+        end
+
+        def self.templates_dir
+          File.join(__dir__, "templates")
+        end
+
+        # Fill in missing project_slug and branch from the agent's environment snapshot.
+        def self.resolve_config(config, environment: {})
+          config[:project_slug] ||= parse_project_slug(environment[:git_remotes])
+          config[:branch] ||= environment[:git_branch]
+          config
+        end
+
+        # Extract CircleCI project slug from git remote URLs.
+        def self.parse_project_slug(remotes)
+          return nil unless remotes
+
+          remotes.each do |remote|
+            url = remote[:url].to_s
+            slug = slug_from_url(url)
+            return slug if slug
+          end
+
+          nil
+        end
+
+        private_class_method def self.slug_from_url(url)
+          if (m = GITHUB_SSH_RE.match(url) || GITHUB_HTTPS_RE.match(url))
+            "gh/#{m[:org]}/#{m[:repo].delete_suffix(".git")}"
+          elsif (m = BITBUCKET_SSH_RE.match(url) || BITBUCKET_HTTPS_RE.match(url))
+            "bb/#{m[:org]}/#{m[:repo].delete_suffix(".git")}"
+          end
+        end
+
+        def initialize(name:, config:, handler:, agent: nil, server_context: {}, connection: nil)
+          super(name:, config:, handler:, agent:, server_context:)
+          @conn = connection
+        end
+
+        def tick
+          project_slug = self[:project_slug]
+          branch = self[:branch]
+
+          check_ci(project_slug, branch)
+        end
+
+        def on_start
+          @conn ||= build_connection
+        end
+
+        private
+
+        def check_ci(project_slug, branch)
+          pipeline = latest_pipeline(project_slug, branch)
+          return unless pipeline
+
+          pipeline_id = pipeline["id"]
+          pipeline_number = pipeline["number"]
+
+          last_id = self[:last_pipeline_id]
+          last_status = self[:last_ci_status]
+
+          workflows = fetch_workflows(pipeline_id)
+          return if workflows.empty?
+
+          completed = workflows.select { TERMINAL_STATUSES.include?(it["status"]) }
+          return unless completed.size == workflows.size
+
+          current_status = (completed.all? { it["status"] == "success" }) ? "success" : "failure"
+
+          return if pipeline_id == last_id && current_status == last_status
+
+          @agent.set_monitor_field(@name, :last_pipeline_id, pipeline_id)
+          @agent.set_monitor_field(@name, :last_ci_status, current_status)
+          @config[:last_pipeline_id] = pipeline_id
+          @config[:last_ci_status] = current_status
+
+          failed_workflows = completed.reject { it["status"] == "success" }
+          failed_jobs = failed_workflows.flat_map { fetch_failed_jobs(it["id"]) }
+          event_type = (current_status == "success") ? :ci_success : :ci_failure
+
+          dispatch(
+            event_type:,
+            project_slug:,
+            branch:,
+            pipeline_id:,
+            pipeline_number:,
+            failed_workflows: failed_workflows.map { |w| w["name"] },
+            failed_jobs:,
+            workflow_count: workflows.size,
+            injection_supersede_key: "ci_status",
+            **((event_type == :ci_success) ? {injection_ttl: 60} : {})
+          )
+        end
+
+        def latest_pipeline(project_slug, branch)
+          resp = @conn.get("/api/v2/project/#{project_slug}/pipeline", branch: branch)
+          handle_response!(resp)
+          resp.body.dig("items")&.first
+        end
+
+        def fetch_workflows(pipeline_id)
+          resp = @conn.get("/api/v2/pipeline/#{pipeline_id}/workflow")
+          handle_response!(resp)
+          resp.body.fetch("items", [])
+        end
+
+        def fetch_failed_jobs(workflow_id)
+          resp = @conn.get("/api/v2/workflow/#{workflow_id}/job")
+          handle_response!(resp)
+          jobs = resp.body.fetch("items", [])
+          jobs.reject { |j| j["status"] == "success" }.map { |j| j["name"] }
+        end
+
+        def handle_response!(resp)
+          case resp.status
+          when 200..299
+            # ok
+          when 401
+            raise FatalError, "CircleCI auth failed (HTTP 401)"
+          when 429
+            raise RateLimited, "CircleCI rate limited (HTTP 429)"
+          when 404
+            Superkick.logger.warn(log_tag) { "CircleCI resource not found (HTTP 404)" }
+          end
+        end
+
+        def build_connection
+          token = self[:token] || ENV["CIRCLECI_TOKEN"]
+
+          Faraday.new(url: "https://circleci.com") do |f|
+            f.headers["Circle-Token"] = token if token
+            f.response :json
+          end
+        end
+      end
+    end
+  end
+end

data/lib/superkick/integrations/circleci/probe.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Integrations
+    module CircleCI
+      # Detects a CircleCI project from the agent's environment snapshot.
+      # Detection requires a .circleci/config.yml file to be present.
+      class Monitor::Probe < Superkick::Monitor::Probe
+        def self.type = :circleci
+
+        def self.description
+          "Detects CircleCI projects from .circleci/config.yml and infers project slug from git remote."
+        end
+
+        def self.environment_actions
+          [
+            {action: :git_branch},
+            {action: :git_remotes},
+            {action: :file_exists, paths: [".circleci/config.yml"]}
+          ]
+        end
+
+        # @param environment [Hash] environment data from the agent
+        # @return [Hash] { circleci: { type: "circleci", ... } } or {}
+        def self.detect(environment:)
+          return {} unless environment.dig(:file_exists, ".circleci/config.yml")
+
+          config = Monitor.resolve_config({}, environment:)
+          return {} unless config[:project_slug] && config[:branch]
+
+          {circleci: config.merge(type: "circleci")}
+        end
+      end
+    end
+  end
+end

data/lib/superkick/integrations/circleci/templates/ci_failure.liquid

@@ -0,0 +1,8 @@
+SUPERKICK [{{ "now" | time }}]: CircleCI FAILED on {{ branch }} (pipeline #{{ pipeline_number }})
+{% if failed_workflows.size > 0 -%}
+Failed workflows: {{ failed_workflows | join: ", " }}
+{% endif -%}
+{% if failed_jobs.size > 0 -%}
+Failed jobs: {{ failed_jobs | join: ", " }}
+{% endif -%}
+Please review the CircleCI output and fix the failures before continuing.

data/lib/superkick/integrations/circleci/templates/ci_success.liquid

@@ -0,0 +1 @@
+SUPERKICK [{{ "now" | time }}]: All {{ workflow_count }} CircleCI workflows passed on {{ branch }} (pipeline #{{ pipeline_number }}).

data/lib/superkick/integrations/circleci.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "circleci/monitor"
+require_relative "circleci/probe"
+
+module Superkick
+  Monitor.register(Integrations::CircleCI::Monitor)
+end

data/lib/superkick/integrations/datadog/README.md

@@ -0,0 +1,253 @@
+# Datadog Integration
+
+Provides: **notifier**, **spawner** (error tracking + alerts), **monitor**, **goal**
+
+## Notifier (`:datadog`)
+
+Sends events and metrics to Datadog via DogStatsD (UDP). See the
+[Notifications section](../../../../README.md#notifications) in the main README
+for notifier configuration.
+
+## Spawner (`:datadog`)
+
+Watches Datadog Error Tracking for open error groups and spawns AI coding
+agents to fix them. Polls the Datadog Error Tracking API for error groups
+matching configurable filters (service, environment, source, minimum event
+count).
+
+Error groups are tracked by ID to prevent re-dispatching. Groups that fail
+client-side filters (e.g. below `minimum_events`) are retried on subsequent
+ticks so they fire once the threshold is crossed.
+
+### Configuration
+
+```yaml
+spawners:
+  datadog:
+    type: datadog
+    site: datadoghq.com
+    api_key: <%= env("DD_API_KEY") %>
+    application_key: <%= env("DD_APP_KEY") %>
+    driver: claude_code
+    service: api
+    environment: production
+    source: ruby
+    minimum_events: 5
+    query: "version:2.0.0"
+```
+
+| Key | Required | Default | Description |
+|-----|----------|---------|-------------|
+| `site` | no | `"datadoghq.com"` | Datadog site (e.g. `"datadoghq.eu"` for EU) |
+| `api_key` | no | `$DD_API_KEY` | Datadog API key |
+| `application_key` | no | `$DD_APP_KEY` | Datadog Application key |
+| `service` | no | — | Filter to a specific service name |
+| `environment` | no | `"production"` | Filter to an environment |
+| `source` | no | — | Error source filter (e.g. `"ruby"`, `"python"`) |
+| `minimum_events` | no | `1` | Minimum event count before dispatching |
+| `query` | no | — | Raw Datadog search query string (appended to filters) |
+
+### Agent ID format
+
+```
+datadog-error-{group_id}
+```
+
+Where `group_id` is the Datadog error group ID. Dedup is handled by
+`AgentStore` — if an agent with the same ID already exists, the spawn is
+skipped.
+
+### Events
+
+#### `error_opened`
+
+Dispatched when a new open error group is found that passes all filters.
+
+Template variables:
+
+| Variable | Description |
+|----------|-------------|
+| `group_id` | Datadog error group ID |
+| `error_class` | Error class name (e.g. `NoMethodError`) |
+| `message` | Error message string |
+| `status` | Error group status (e.g. `open`) |
+| `service` | Service name |
+| `environment` | Environment name |
+| `first_seen` | Timestamp of first occurrence |
+| `last_seen` | Timestamp of most recent occurrence |
+| `events` | Total event count |
+| `users` | Number of impacted users |
+| `source` | Error source (e.g. `ruby`) |
+| `url` | Datadog dashboard URL for this error group |
+
+### Error handling
+
+- **401/403** — raises `FatalError`, stops the spawner (authentication failure)
+- **429** — raises `RateLimited`, backs off per the standard poller backoff
+- **404** — logged as warning, skipped (resource not found)
+- Other HTTP errors — logged as warning, skipped
+
+## Alert Spawner (`:datadog_alerts`)
+
+Watches Datadog monitors for triggered alerts and spawns AI coding agents to
+triage them. Polls the Datadog Monitors Search API (`GET /api/v1/monitor/search`)
+for monitors in an alerting state.
+
+Monitors that recover (return to OK) are cleared from the seen set, so if they
+re-alert later a new agent is spawned.
+
+Pairs naturally with the `:datadog_alert_resolved` goal and `:datadog_alert`
+monitor for a full triage lifecycle.
+
+### Configuration
+
+```yaml
+spawners:
+  datadog_alerts:
+    type: datadog_alerts
+    site: datadoghq.com
+    api_key: <%= env("DD_API_KEY") %>
+    application_key: <%= env("DD_APP_KEY") %>
+    driver: claude_code
+    goal:
+      type: datadog_alert_resolved
+    max_duration: 3600
+    statuses:
+      - Alert
+      - Warn
+    tags:
+      - "team:backend"
+      - "env:production"
+    monitor_types:
+      - metric
+      - log
+    priority:
+      - 1
+      - 2
+    query: "scope:host:web-01"
+```
+
+| Key | Required | Default | Description |
+|-----|----------|---------|-------------|
+| `site` | no | `"datadoghq.com"` | Datadog site (e.g. `"datadoghq.eu"` for EU) |
+| `api_key` | no | `$DD_API_KEY` | Datadog API key |
+| `application_key` | no | `$DD_APP_KEY` | Datadog Application key |
+| `statuses` | no | `["Alert"]` | Array of monitor statuses to match |
+| `tags` | no | — | Array of tags to filter (AND logic) |
+| `monitor_types` | no | — | Array of monitor types to include (e.g. `metric`, `log`) |
+| `priority` | no | — | Array of priority levels (1-5) |
+| `query` | no | — | Raw Datadog search query string (appended to filters) |
+
+### Agent ID format
+
+```
+datadog-alert-{monitor_id}
+```
+
+### Events
+
+#### `alert_triggered`
+
+Dispatched when a Datadog monitor enters an alerting state matching the
+configured filters.
+
+Template variables:
+
+| Variable | Description |
+|----------|-------------|
+| `monitor_id` | Datadog monitor ID |
+| `name` | Monitor name |
+| `status` | Current status (e.g. `Alert`, `Warn`) |
+| `alert_type` | Monitor type (e.g. `metric alert`, `log alert`) |
+| `query` | Monitor query being evaluated |
+| `message` | Notification message configured on the monitor |
+| `tags` | Array of monitor tags |
+| `priority` | Monitor priority (1-5, or nil) |
+| `creator` | Name or email of the monitor creator |
+| `url` | URL to the monitor in Datadog |
+
+## Alert Monitor (`:datadog_alert`)
+
+Polls a specific Datadog monitor for status changes and injects events when the
+alert state transitions. Records a baseline on the first tick and only dispatches
+on subsequent state changes.
+
+Typically auto-configured when using the alert spawner — the `monitor_id` is
+passed through the spawn event context.
+
+### Configuration
+
+```yaml
+monitors:
+  datadog_alert:
+    type: datadog_alert
+    monitor_id: 12345
+    site: datadoghq.com
+    api_key: <%= env("DD_API_KEY") %>
+    application_key: <%= env("DD_APP_KEY") %>
+```
+
+| Key | Required | Default | Description |
+|-----|----------|---------|-------------|
+| `monitor_id` | yes | — | Datadog monitor ID to watch |
+| `site` | no | `"datadoghq.com"` | Datadog site |
+| `api_key` | no | `$DD_API_KEY` | Datadog API key |
+| `application_key` | no | `$DD_APP_KEY` | Datadog Application key |
+
+### Events
+
+#### `alert_recovered`
+
+Dispatched when the monitor transitions to OK status.
+
+#### `alert_escalated`
+
+Dispatched when the monitor transitions from Warn to Alert.
+
+#### `alert_changed`
+
+Dispatched for any other status transition (e.g. OK → Warn, Alert → No Data).
+
+All monitor events include these template variables:
+
+| Variable | Description |
+|----------|-------------|
+| `monitor_id` | Datadog monitor ID |
+| `name` | Monitor name |
+| `status` | Current status after transition |
+| `previous_status` | Status before transition |
+| `alert_type` | Monitor type |
+| `query` | Monitor query |
+| `tags` | Array of monitor tags |
+| `url` | URL to the monitor in Datadog |
+
+## Alert Goal (`:datadog_alert_resolved`)
+
+Polls a Datadog monitor and completes when it returns to OK status. The
+`monitor_id` is injected from the spawn event context via `AgentSpawner`.
+
+### Configuration
+
+```yaml
+spawners:
+  datadog_alerts:
+    type: datadog_alerts
+    goal:
+      type: datadog_alert_resolved
+```
+
+| Key | Required | Default | Description |
+|-----|----------|---------|-------------|
+| `monitor_id` | no | — | Injected from spawn event context |
+| `site` | no | `"datadoghq.com"` | Datadog site |
+| `api_key` | no | `$DD_API_KEY` | Datadog API key |
+| `application_key` | no | `$DD_APP_KEY` | Datadog Application key |
+
+### Status mapping
+
+| Monitor state | Goal status |
+|---------------|-------------|
+| OK | `:completed` |
+| Alert, Warn | `:in_progress` |
+| No Data | `:pending` |
+| API error | `:errored` |

data/lib/superkick/integrations/datadog/alert_goal.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module Superkick
+  module Integrations
+    module Datadog
+      # Goal that checks whether a Datadog monitor has recovered (returned to OK).
+      #
+      # Polls the Datadog Monitor API for the specified monitor's status.
+      # Completes when the monitor reaches OK status; stays in_progress while
+      # it remains in an alerting state.
+      #
+      # Configuration:
+      #   goal:
+      #     type: datadog_alert_resolved
+      #     monitor_id: 12345              # injected from spawn event context
+      #     site: datadoghq.com            # optional
+      #     api_key: xxx                   # optional, falls back to DD_API_KEY
+      #     application_key: xxx           # optional, falls back to DD_APP_KEY
+      #
+      # The monitor_id is injected from the spawn event context via AgentSpawner.
+      class AlertResolvedGoal < Superkick::Goal
+        DEFAULT_SITE = "datadoghq.com"
+
+        def self.type = :datadog_alert_resolved
+
+        def self.description
+          "Polls a Datadog monitor and completes when it returns to OK status. " \
+            "The monitor_id is injected from the spawn event context."
+        end
+
+        def self.required_config = %i[]
+
+        def check
+          monitor_id = config[:monitor_id]
+          return :pending unless monitor_id
+
+          resp = connection.get("/api/v1/monitor/#{monitor_id}")
+
+          case resp.status
+          when 200..299
+            status = resp.body["overall_state"].to_s
+            case status
+            when "OK" then :completed
+            when "Alert", "Warn" then :in_progress
+            when "No Data" then :pending
+            else :in_progress
+            end
+          when 401, 403
+            Superkick.logger.error("goal:datadog_alert_resolved") { "Auth failed (HTTP #{resp.status}) for #{agent_id}" }
+            :errored
+          when 429
+            Superkick.logger.warn("goal:datadog_alert_resolved") { "Rate limited for #{agent_id}" }
+            :errored
+          when 404
+            Superkick.logger.warn("goal:datadog_alert_resolved") { "Monitor #{monitor_id} not found for #{agent_id}" }
+            :errored
+          else
+            Superkick.logger.warn("goal:datadog_alert_resolved") { "HTTP #{resp.status} for #{agent_id}" }
+            :errored
+          end
+        rescue Faraday::Error => e
+          Superkick.logger.error("goal:datadog_alert_resolved") { "Check failed for #{agent_id}: #{e.message}" }
+          :errored
+        end
+
+        def teardown
+          @connection = nil
+        end
+
+        private
+
+        def connection
+          @connection ||= build_connection
+        end
+
+        def build_connection
+          site = config[:site] || DEFAULT_SITE
+          api_key = config[:api_key] || ENV["DD_API_KEY"]
+          app_key = config[:application_key] || ENV["DD_APP_KEY"]
+
+          Faraday.new(url: "https://api.#{site}") do |f|
+            f.headers["DD-API-KEY"] = api_key if api_key
+            f.headers["DD-APPLICATION-KEY"] = app_key if app_key
+            f.response :json
+          end
+        end
+      end
+    end
+  end
+end
+
+Superkick::Goal.register(Superkick::Integrations::Datadog::AlertResolvedGoal)