superkick 0.1.0

data/lib/superkick/integrations/git.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "git/version_control"
+require_relative "git/repository_source"
+
+module Superkick
+  VersionControl.register(Integrations::Git::VersionControl)
+end

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

@@ -0,0 +1,300 @@
+# GitHub Integration
+
+The GitHub integration provides a **monitor**, **spawners**, and **goals** for GitHub repositories.
+
+## Monitor
+
+Type: `:github`
+
+Polls GitHub CI check runs and PR activity for a registered agent. Injects
+context when CI fails, new PR comments arrive, or reviews are submitted.
+
+## Configuration
+
+```yaml
+monitors:
+  github:
+    token: <%= env("GITHUB_TOKEN") %>
+```
+
+| Key | Required | Default | Description |
+|-----|----------|---------|-------------|
+| `repo` | yes | auto-detected | GitHub repo in `org/name` format |
+| `branch` | yes | auto-detected | Git branch to watch |
+| `token` | no | `GITHUB_TOKEN` env var | Personal access token for private repos |
+
+The probe auto-detects `repo` and `branch` from the local git remote, so
+explicit config is only needed to override or when there's no local checkout.
+
+## Probe
+
+`GitHubMonitor::Probe` inspects the current directory's git remote for a
+GitHub URL and reads the current branch via `git symbolic-ref`. Returns a
+config hash keyed as `"github"` with `repo` and `branch` populated.
+
+Returns `{}` if the directory isn't a git repo or has no GitHub remote.
+
+## Events
+
+### `ci_failure`
+
+Dispatched when all check runs for the HEAD commit complete and at least one
+has a non-success conclusion. Only fires on status change or new SHA.
+
+Template variables:
+- `repo` — `org/name`
+- `branch` — branch name
+- `sha` — full commit SHA (`short_sha(sha)` for 7-char form)
+- `failed_checks` — array of failed check names
+- `check_count` — total number of checks
+
+### `ci_success`
+
+Dispatched when all check runs pass. Same trigger logic as `ci_failure`.
+
+Template variables: same as `ci_failure`.
+
+### `pr_comment`
+
+Dispatched for each new issue comment on the open PR for the watched branch.
+Uses a `last_comment_id` watermark to avoid re-reporting.
+
+Template variables:
+- `repo`, `branch`
+- `pull_request` — `PullRequestDrop` with `.number`, `.title`
+- `comment` — `CommentDrop` with `.author`, `.body`, `.url`
+
+### `pr_review`
+
+Dispatched for each new non-pending review on the open PR. Uses a
+`last_review_id` watermark.
+
+Template variables:
+- `repo`, `branch`
+- `pull_request` — `PullRequestDrop` with `.number`, `.title`
+- `review` — `ReviewDrop` with `.author`, `.state`, `.body`, `.url`
+
+## Watermarks
+
+The monitor persists these fields on the agent to avoid duplicate events
+across ticks:
+
+- `last_ci_sha` / `last_ci_status` — last reported commit + its CI result
+- `last_comment_id` — highest seen PR comment ID
+- `last_review_id` — highest seen PR review ID
+
+## Monitor error handling
+
+- `Octokit::TooManyRequests` → `RateLimited` (backs off by `rate_limit_backoff`)
+- `Octokit::Unauthorized` → `FatalError` (stops the monitor thread)
+- `Octokit::NotFound` → logged and skipped (e.g. branch deleted mid-tick)
+
+## Goal
+
+Type: `:github_pr_merged`
+
+Polls GitHub to check whether a PR has been merged. Intended for spawned agents
+— when the PR is merged, the goal returns `:completed` and the Supervisor
+terminates the agent.
+
+### Configuration
+
+```yaml
+spawners:
+  my_spawner:
+    goal:
+      type: github_pr_merged
+```
+
+All config keys are optional:
+
+| Key | Required | Default | Description |
+|-----|----------|---------|-------------|
+| `repo` | no | auto-detected from git remote | GitHub repo in `org/name` format |
+| `branch` | no | auto-detected from git HEAD | Branch to search for PRs on |
+| `pr_number` | no | discovered via branch search | Direct PR number for efficient lookups |
+| `token` | no | `GITHUB_TOKEN` env var | Personal access token for private repos |
+| `working_dir` | no | injected by AgentSpawner | Directory for git auto-detection |
+| `check_interval` | no | `poll_interval` | Seconds between goal checks |
+
+The `AgentSpawner` automatically injects `working_dir` into the goal config at
+spawn time, so the server-side goal checker can run git commands against the
+agent's workspace.
+
+### Auto-detection
+
+The goal auto-detects `repo` and `branch` from the git working directory using
+the same approach as the monitor probe:
+
+- **`repo`** — parsed from `git remote -v` (SSH or HTTPS GitHub URLs). Cached
+  after first detection.
+- **`branch`** — read from `git symbolic-ref --short HEAD`. Re-detected on each
+  check to handle the spawner flow where the agent starts on `main` and later
+  creates a feature branch.
+
+Once a PR is found via branch search, its number is cached for efficient direct
+lookups on subsequent checks.
+
+### Status mapping
+
+| PR State | Goal Status |
+|----------|-------------|
+| Merged (`merged_at` present) | `:completed` (terminal) |
+| Closed without merge | `:failed` (terminal) |
+| Open | `:in_progress` (non-terminal) |
+| No PR found | `:pending` (non-terminal) |
+| API error / rate limit | `:errored` (non-terminal) |
+
+### Goal error handling
+
+- `Octokit::TooManyRequests` → `:errored` (logged, retried next check)
+- `Octokit::Unauthorized` → `:errored` (logged, retried next check)
+- Generic exceptions → `:errored` (logged, retried next check)
+
+## Goal: GitHub Issue Resolved
+
+Type: `:github_issue_resolved`
+
+Polls GitHub to check whether an issue has been closed. Any close reason
+(completed or not_planned) counts as success. Pairs naturally with the
+`:github_issues` spawner.
+
+### Configuration
+
+```yaml
+spawners:
+  github_issues:
+    goal:
+      type: github_issue_resolved
+      # issue context (IssueDrop) is injected from the spawn event by AgentSpawner
+```
+
+| Key | Required | Default | Description |
+|-----|----------|---------|-------------|
+| `repo` | no | auto-detected from git remote | GitHub repo in `org/name` format |
+| `issue` | yes | injected by AgentSpawner | `IssueDrop` from spawn event context (provides `.number`, `.title`, etc.) |
+| `token` | no | `GITHUB_TOKEN` env var | Personal access token for private repos |
+| `working_dir` | no | injected by AgentSpawner | Directory for git auto-detection |
+| `check_interval` | no | `poll_interval` | Seconds between goal checks |
+
+### Status mapping
+
+| Issue State | Goal Status |
+|-------------|-------------|
+| Closed (any reason) | `:completed` (terminal) |
+| Open | `:in_progress` (non-terminal) |
+| Missing config | `:pending` (non-terminal) |
+| API error / rate limit | `:errored` (non-terminal) |
+
+## Spawner: GitHub Issues
+
+Type: `:github_issues`
+
+Watches for newly created or reopened GitHub issues and spawns agents to work
+on them. Uses an `updated_at` watermark so reopened issues are caught
+automatically.
+
+### Configuration
+
+```yaml
+spawners:
+  github_issues:
+    type: github_issues
+    repo: myorg/myrepo
+    token: <%= env("GITHUB_TOKEN") %>
+    labels:
+      - ai-ready
+    assignee: "*"
+    driver: claude_code
+    repository: my-app
+    branch_template: "fix-{agent_id}"
+    goal:
+      type: github_issue_resolved
+    max_duration: 7200
+```
+
+| Key | Required | Default | Description |
+|-----|----------|---------|-------------|
+| `repo` | yes | — | GitHub repo in `org/name` format |
+| `token` | no | `GITHUB_TOKEN` env var | Personal access token |
+| `labels` | no | — | Array of label names (AND filter) |
+| `assignee` | no | — | Username, `"*"` (any), or `"none"` |
+| `milestone` | no | — | Milestone number, `"*"`, or `"none"` |
+| `creator` | no | — | Filter by issue creator username |
+| `exclude_pull_requests` | no | `true` | Filter out PRs from the issues endpoint |
+
+### Agent ID format
+
+`github-issue-{org}-{repo}-{number}` (e.g. `github-issue-myorg-myrepo-42`)
+
+### Events
+
+#### `issue_opened`
+
+Template variables:
+- `repo` — `org/name`
+- `issue` — `IssueDrop` with `.number`, `.title`, `.body`, `.url`, `.author`, `.labels`, `.assignees`, `.milestone`, `.created_at`, `.updated_at`
+
+## Spawner: GitHub Check Failed
+
+Type: `:github_check_failed`
+
+Watches GitHub check suites for failures on configured branches and spawns
+agents to fix them. Works across CI providers since it polls GitHub's check
+runs API.
+
+### Configuration
+
+```yaml
+spawners:
+  ci_fixer:
+    type: github_check_failed
+    repo: myorg/myrepo
+    branches:
+      - main
+      - staging
+    token: <%= env("GITHUB_TOKEN") %>
+    app_filter:
+      - github-actions
+    exclude_apps:
+      - dependabot
+    driver: claude_code
+    max_concurrent: 2
+    cooldown: 600
+```
+
+| Key | Required | Default | Description |
+|-----|----------|---------|-------------|
+| `repo` | yes | — | GitHub repo in `org/name` format |
+| `branches` | yes | — | Array of branch names to watch |
+| `token` | no | `GITHUB_TOKEN` env var | Personal access token |
+| `app_filter` | no | — | Array of app names/slugs to include |
+| `check_name_filter` | no | — | Array of check run names to include |
+| `exclude_apps` | no | — | Array of app names to ignore |
+
+### Agent ID format
+
+`github-check-{org}-{repo}-{branch}-{short_sha}` (e.g. `github-check-myorg-myrepo-main-abc1234`)
+
+A new agent is spawned per branch+commit, so a new failure after a push gets
+its own agent.
+
+### Events
+
+#### `check_failed`
+
+Template variables:
+- `repo` — `org/name`
+- `branch` — branch name
+- `sha` — full commit SHA (`short_sha(sha)` for 7-char form)
+- `failed_checks` — array of `CheckRunDrop` with `.name`, `.conclusion`, `.app`, `.details_url`, `.html_url`
+- `total_checks` — total number of (filtered) checks
+- `commit` — `CommitDrop` with `.message`, `.author`, `.url`
+
+### Behavior
+
+- Polls each configured branch's HEAD SHA on every tick
+- Skips branches where the SHA hasn't changed since last check
+- Waits for all (filtered) check runs to reach `completed` status before evaluating
+- Only dispatches when at least one check has a non-success conclusion
+- Does not re-dispatch the same SHA on subsequent ticks

data/lib/superkick/integrations/github/check_failed_spawner.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "octokit"
+
+module Superkick
+  module Integrations
+    module GitHub
+      # Watches GitHub check suites for failures on configured branches and
+      # spawns agents to fix them.
+      #
+      # Primary use case: CI broken on main or environment branches.  Works
+      # across CI providers since it polls GitHub's check runs API.
+      #
+      # Config keys:
+      #   repo              (required) — owner/name
+      #   branches          (required) — array of branch names to watch
+      #   token             (optional) — falls back to GITHUB_TOKEN
+      #   app_filter        (optional) — array of app names/slugs to include
+      #   check_name_filter (optional) — array of check run names to include
+      #   exclude_apps      (optional) — array of app names to ignore
+      #   only_latest_commit (optional, default true) — only check HEAD of each branch
+      class CheckFailedSpawner < Superkick::Spawner
+        attr_reader :client
+
+        def initialize(name:, config:, handler:, client: nil)
+          super(name:, config:, handler:)
+          @client = client
+        end
+
+        def self.type = :github_check_failed
+
+        def self.description
+          "Watches GitHub check suites for failures on configured branches " \
+            "and spawns AI coding agents to fix them. Supports filtering by " \
+            "app name, check name, and branch."
+        end
+
+        def self.required_config = %i[repo branches]
+
+        def self.spawn_templates_dir
+          File.join(__dir__, "templates")
+        end
+
+        def self.agent_id(event)
+          "github-check-#{event[:repo].tr("/", "-")}-#{event[:branch]}-#{event[:sha][0..6]}"
+        end
+
+        def self.setup_label = "GitHub Check Failures"
+
+        def self.setup_config
+          <<~YAML
+            github_check_failed:
+              type: github_check_failed
+              repo: org/repo
+              branches:
+                - main
+              token: <%= env("GITHUB_TOKEN") %>
+              # app_filter:                      # only checks from these CI apps
+              #   - "GitHub Actions"
+              # check_name_filter:               # only these check run names
+              #   - "test"
+              # max_duration: 3600
+          YAML
+        end
+
+        def tick
+          branches = self[:branches]
+          return unless branches.is_a?(Array)
+
+          branches.each { check_branch(it) }
+        rescue Octokit::TooManyRequests => e
+          raise RateLimited, e.message
+        rescue Octokit::Unauthorized => e
+          raise FatalError, "GitHub auth failed: #{e.message}"
+        end
+
+        def on_start
+          @client ||= build_client
+          @last_seen_sha = {}
+          @dispatched_shas = {}
+        end
+
+        private
+
+        def check_branch(branch)
+          repo = self[:repo]
+
+          sha = head_sha(repo, branch)
+          return unless sha
+
+          # Skip if we've already processed this SHA
+          return if sha == @last_seen_sha[branch]
+
+          runs_data = @client.check_runs_for_ref(repo, sha, accept: "application/vnd.github+json")
+          checks = runs_data.check_runs
+          return if checks.empty?
+
+          checks = apply_filters(checks)
+          return if checks.empty?
+
+          # Wait for all (filtered) checks to complete
+          completed = checks.select { it.status == "completed" }
+          return unless completed.size == checks.size
+
+          @last_seen_sha[branch] = sha
+
+          failed = completed.reject { it.conclusion == "success" }
+          return if failed.empty?
+
+          # Don't re-dispatch the same SHA
+          return if @dispatched_shas[branch] == sha
+
+          @dispatched_shas[branch] = sha
+
+          commit_info = fetch_commit_info(repo, sha)
+
+          dispatch(
+            event_type: :check_failed,
+            repo:,
+            branch:,
+            sha:,
+            failed_checks: failed.map { CheckRunDrop.new(format_check(it)) },
+            total_checks: checks.size,
+            commit: CommitDrop.new(commit_info)
+          )
+        rescue Octokit::NotFound => e
+          Superkick.logger.warn(log_tag) { "Branch #{branch} not found: #{e.message}" }
+        end
+
+        def head_sha(repo, branch)
+          @client.branch(repo, branch).commit.sha
+        rescue Octokit::NotFound
+          nil
+        end
+
+        def apply_filters(checks)
+          if self[:app_filter]&.any?
+            app_names = self[:app_filter].map(&:downcase)
+            checks = checks.select { app_names.include?(it.app.slug.downcase) || app_names.include?(it.app.name.downcase) }
+          end
+
+          if self[:exclude_apps]&.any?
+            excluded = self[:exclude_apps].map(&:downcase)
+            checks = checks.reject { excluded.include?(it.app.slug.downcase) || excluded.include?(it.app.name.downcase) }
+          end
+
+          if self[:check_name_filter]&.any?
+            names = self[:check_name_filter].map(&:downcase)
+            checks = checks.select { names.include?(it.name.downcase) }
+          end
+
+          checks
+        end
+
+        def format_check(check)
+          {
+            name: check.name,
+            conclusion: check.conclusion,
+            app: check.app.name,
+            details_url: check.details_url,
+            html_url: check.html_url
+          }
+        end
+
+        def fetch_commit_info(repo, sha)
+          commit = @client.commit(repo, sha)
+          {
+            message: commit.commit.message.lines.first&.strip.to_s,
+            author: commit.commit.author.name,
+            url: commit.html_url
+          }
+        rescue => e
+          Superkick.logger.debug(log_tag) { "Could not fetch commit #{sha}: #{e.message}" }
+          {message: "", author: "", url: ""}
+        end
+
+        def build_client
+          token = self[:token] || ENV["GITHUB_TOKEN"]
+
+          Octokit::Client.new(
+            access_token: token,
+            middleware: faraday_stack
+          )
+        end
+
+        def faraday_stack
+          Faraday::RackBuilder.new do |builder|
+            builder.request :retry,
+              max: 3,
+              interval: 0.5,
+              backoff_factor: 2,
+              exceptions: Faraday::Retry::Middleware::DEFAULT_EXCEPTIONS + [Faraday::ConnectionFailed]
+            builder.adapter Faraday.default_adapter
+          end
+        end
+      end
+    end
+  end
+end

data/lib/superkick/integrations/github/drops.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Integrations
+    module GitHub
+      # Liquid Drop for a GitHub issue. Wraps the symbol-keyed hash built
+      # by GitHubIssueSpawner so templates can use {{ issue.title }}, etc.
+      class IssueDrop < Superkick::Drop
+        def self.drop_type = "github_issue"
+
+        def number = @data[:number]
+
+        def title = @data[:title]
+
+        def body = @data[:body]
+
+        def url = @data[:url]
+
+        def author = @data[:author]
+
+        def labels = @data[:labels]
+
+        def assignees = @data[:assignees]
+
+        def milestone = @data[:milestone]
+
+        def created_at = @data[:created_at]
+
+        def updated_at = @data[:updated_at]
+      end
+
+      # Liquid Drop for a GitHub pull request. Shared across pr_comment
+      # and pr_review events so templates can use {{ pull_request.number }}.
+      class PullRequestDrop < Superkick::Drop
+        def self.drop_type = "github_pull_request"
+
+        def number = @data[:number]
+
+        def title = @data[:title]
+
+        # Formatted reference: #42 "Title…" (title truncated to 50 chars).
+        def ref
+          title_str = title
+          if title_str && !title_str.empty?
+            truncated = (title_str.length > 50) ? "#{title_str[0, 49]}…" : title_str
+            "##{number} \"#{truncated}\""
+          else
+            "##{number}"
+          end
+        end
+      end
+
+      # Liquid Drop for a GitHub PR comment.
+      class CommentDrop < Superkick::Drop
+        def self.drop_type = "github_comment"
+
+        def author = @data[:author]
+
+        def body = @data[:body]
+
+        def url = @data[:url]
+      end
+
+      # Liquid Drop for a GitHub PR review.
+      class ReviewDrop < Superkick::Drop
+        def self.drop_type = "github_review"
+
+        def author = @data[:author]
+
+        def state = @data[:state]
+
+        def body = @data[:body]
+
+        def url = @data[:url]
+      end
+
+      # Liquid Drop for a GitHub commit. Used in check_failed events.
+      class CommitDrop < Superkick::Drop
+        def self.drop_type = "github_commit"
+
+        def message = @data[:message]
+
+        def author = @data[:author]
+
+        def url = @data[:url]
+      end
+
+      # Liquid Drop for GitHub check run data. Wraps the symbol-keyed
+      # hash returned by GitHubCheckFailedSpawner#format_check so
+      # Liquid templates can access properties via dot notation
+      # (e.g. {{ check.name }}, {{ check.details_url }}).
+      class CheckRunDrop < Superkick::Drop
+        def self.drop_type = "github_check_run"
+
+        def name = @data[:name]
+
+        def conclusion = @data[:conclusion]
+
+        def app = @data[:app]
+
+        def details_url = @data[:details_url]
+
+        def html_url = @data[:html_url]
+      end
+    end
+  end
+end
+
+Superkick::Drop.register(Superkick::Integrations::GitHub::IssueDrop)
+Superkick::Drop.register(Superkick::Integrations::GitHub::PullRequestDrop)
+Superkick::Drop.register(Superkick::Integrations::GitHub::CommentDrop)
+Superkick::Drop.register(Superkick::Integrations::GitHub::ReviewDrop)
+Superkick::Drop.register(Superkick::Integrations::GitHub::CommitDrop)
+Superkick::Drop.register(Superkick::Integrations::GitHub::CheckRunDrop)