superkick 0.1.0

data/lib/superkick/integrations/honeybadger/spawner.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module Superkick
+  module Integrations
+    module Honeybadger
+      # Watches Honeybadger for unresolved faults and spawns AI coding agents to
+      # fix them.
+      #
+      # Polls the Honeybadger Faults API for faults matching configurable filters
+      # (environment, fault class, minimum occurrence count). Tracks dispatched
+      # fault IDs in-memory to avoid re-dispatching. Faults that fail client-side
+      # filters (e.g. below minimum_occurrences) are retried on subsequent ticks
+      # so they fire once the threshold is crossed.
+      #
+      # Config keys:
+      #   project_id          (required) — Honeybadger project ID
+      #   token               (optional) — API auth token, falls back to $HONEYBADGER_TOKEN
+      #   environment         (optional) — environment name, default "production"
+      #   minimum_occurrences (optional) — minimum occurrence count to dispatch, default 1
+      #   fault_classes       (optional) — array or include/exclude hash
+      class Spawner < Superkick::Spawner
+        attr_reader :conn
+
+        API_BASE = "https://app.honeybadger.io"
+        DEFAULT_ENVIRONMENT = "production"
+        DEFAULT_MINIMUM_OCCURRENCES = 1
+        PER_PAGE = 25
+
+        def self.type = :honeybadger
+
+        def self.description
+          "Watches Honeybadger for unresolved faults and spawns AI coding " \
+            "agents to fix them. Supports filtering by environment, fault " \
+            "class, and minimum occurrence count."
+        end
+
+        def self.required_config = %i[project_id]
+
+        def self.spawn_templates_dir
+          File.join(__dir__, "templates")
+        end
+
+        def self.agent_id(event)
+          "honeybadger-fault-#{event[:fault_id]}"
+        end
+
+        def self.setup_label = "Honeybadger"
+
+        def self.setup_config
+          <<~YAML
+            honeybadger:
+              type: honeybadger
+              project_id: 12345
+              token: <%= env("HONEYBADGER_TOKEN") %>
+              # environment: production           # default
+              # minimum_occurrences: 1            # minimum occurrences before spawning
+              # max_duration: 3600
+          YAML
+        end
+
+        def initialize(name:, config:, handler:, connection: nil)
+          super(name:, config:, handler:)
+          @conn = connection
+        end
+
+        def tick
+          faults = fetch_faults
+          faults.each do |fault|
+            next if filtered_by_fault_class?(fault)
+            next if filtered_by_minimum_occurrences?(fault)
+
+            @seen_fault_ids.add(fault["id"])
+
+            dispatch(
+              event_type: :error_opened,
+              fault_id: fault["id"],
+              error_class: fault["klass"].to_s,
+              message: fault["message"].to_s,
+              environment: fault["environment"].to_s,
+              events: fault["notices_count"] || 0,
+              users: fault["impacted_users_count"],
+              first_seen: fault["created_at"].to_s,
+              last_seen: fault["last_notice_at"].to_s,
+              component: fault["component"].to_s,
+              action: fault["action"].to_s,
+              assignee: fault["assignee"],
+              url: fault_url(fault["id"]),
+              project_id: self[:project_id]
+            )
+          end
+        end
+
+        def on_start
+          @conn ||= build_connection
+          @seen_fault_ids = Set.new
+        end
+
+        private
+
+        # -- Honeybadger Faults API -----------------------------------------------
+
+        def fetch_faults
+          project_id = self[:project_id]
+          params = build_params
+
+          path = "/v2/projects/#{project_id}/faults"
+          Superkick.logger.debug(log_tag) { "Fetching faults: #{path} #{params.inspect}" }
+
+          resp = get(path, params)
+          return [] unless resp
+
+          body = resp.body
+          faults = body["results"]
+          return [] unless faults.is_a?(Array)
+
+          new_faults = faults.reject { @seen_fault_ids.include?(it["id"]) }
+
+          Superkick.logger.info(log_tag) { "Found #{faults.size} faults, #{new_faults.size} new" }
+          new_faults
+        end
+
+        def build_params
+          params = {
+            "order" => "recent",
+            "resolved" => "false",
+            "ignored" => "false",
+            "per_page" => PER_PAGE.to_s
+          }
+
+          env = self[:environment]
+          env = DEFAULT_ENVIRONMENT if env.nil?
+          params["environment"] = env if env && !env.to_s.empty?
+
+          # Server-side class filter (include only)
+          fc = normalize_filter(self[:fault_classes])
+          if fc[:include].any?
+            params["q"] = fc[:include].join(" ")
+          end
+
+          params
+        end
+
+        # -- Client-side filters --------------------------------------------------
+
+        def filtered_by_fault_class?(fault)
+          excludes = normalize_filter(self[:fault_classes])[:exclude]
+          return false unless excludes.any?
+
+          excludes.include?(fault["klass"].to_s)
+        end
+
+        def filtered_by_minimum_occurrences?(fault)
+          min = self[:minimum_occurrences] || DEFAULT_MINIMUM_OCCURRENCES
+          count = fault["notices_count"] || 0
+          count < min
+        end
+
+        # -- Filter normalization -------------------------------------------------
+
+        def normalize_filter(value, default_include: [])
+          case value
+          when Array
+            {include: value, exclude: []}
+          when Hash
+            {include: Array(value[:include]), exclude: Array(value[:exclude])}
+          else
+            {include: default_include, exclude: []}
+          end
+        end
+
+        # -- URL helpers ----------------------------------------------------------
+
+        def fault_url(fault_id)
+          "https://app.honeybadger.io/projects/#{self[:project_id]}/faults/#{fault_id}"
+        end
+
+        # -- HTTP -----------------------------------------------------------------
+
+        def get(path, params = {})
+          resp = @conn.get(path) do |req|
+            params.each { |k, v| req.params[k] = v }
+          end
+          return nil unless handle_response!(resp)
+          resp
+        end
+
+        def handle_response!(resp)
+          case resp.status
+          when 200..299 then true
+          when 401, 403 then raise FatalError, "Honeybadger auth failed (HTTP #{resp.status})"
+          when 429 then raise RateLimited, "Honeybadger rate limited"
+          when 404
+            Superkick.logger.warn(log_tag) { "Honeybadger 404: resource not found" }
+            false
+          else
+            Superkick.logger.warn(log_tag) { "Honeybadger HTTP #{resp.status}" }
+            false
+          end
+        end
+
+        def build_connection
+          token = self[:token] || ENV["HONEYBADGER_TOKEN"]
+
+          Faraday.new(url: API_BASE) do |f|
+            f.request :authorization, :basic, token, "" if token
+            f.response :json
+          end
+        end
+      end
+    end
+  end
+end

data/lib/superkick/integrations/honeybadger/templates/error_opened.liquid

@@ -0,0 +1,17 @@
+SUPERKICK [{{ "now" | time }}]: Honeybadger fault — {{ error_class }}
+{% if url -%}
+URL: {{ url }}
+{% endif -%}
+{% unless environment == "" %}Env: {{ environment }} | {% endunless %}Occurrences: {{ events }}{% if users %} | Users: {{ users }}{% endif %}
+{% unless component == "" and action == "" -%}
+Component: {{ component }}{% unless action == "" %}#{{ action }}{% endunless %}
+{% endunless -%}
+First seen: {{ first_seen }} | Last seen: {{ last_seen }}
+
+## Error
+
+**{{ error_class }}**: {% if message == "" %}(no message){% else %}{{ message }}{% endif %}
+
+Please investigate this fault, identify the root cause, implement a fix, and
+write tests to prevent regression. Check the Honeybadger dashboard for full
+stack traces and contextual data.

data/lib/superkick/integrations/honeybadger.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "honeybadger/notifier"
+require_relative "honeybadger/spawner"
+
+module Superkick
+  Notifier.register(Integrations::Honeybadger::Notifier)
+  Spawner.register(Integrations::Honeybadger::Spawner)
+end

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

@@ -0,0 +1,83 @@
+# Shell Monitor
+
+Type: `:shell`
+
+Runs a shell command on each poll interval and dispatches events based on exit
+status. Designed for custom health checks, linters, or any script the user
+wants Superkick to watch.
+
+Supports multiple named instances — each with its own command, working
+directory, and timeout.
+
+## Configuration
+
+```yaml
+monitors:
+  disk-check:
+    type: shell
+    command: ./scripts/check-disk.sh
+    timeout: 10
+  lint:
+    type: shell
+    command: bundle exec standardrb --no-fix
+    working_dir: /home/user/myproject
+    report_success: true
+```
+
+| Key | Required | Default | Description |
+|-----|----------|---------|-------------|
+| `command` | yes | — | Shell command string to execute |
+| `working_dir` | no | inherited | Working directory for the command |
+| `timeout` | no | `30` | Seconds before the command is killed with SIGTERM |
+| `report_success` | no | `false` | Dispatch `shell_success` on zero exit (by default only failures are reported) |
+
+The `type: shell` key is required when the monitor name doesn't match the
+type (i.e. for all instances except one literally named `"shell"`).
+
+## Probe
+
+`ShellMonitor::Probe` scans `.superkick/shell/` in the working directory for
+executable files. Each script gets a monitor named `shell-<basename>` (without
+extension).
+
+Example layout:
+```
+.superkick/shell/
+  check-disk.sh    (executable)
+  lint.sh          (executable)
+```
+
+Produces:
+```ruby
+{
+  "shell-check-disk" => { "type" => "shell", "command" => "/abs/path/.superkick/shell/check-disk.sh" },
+  "shell-lint"       => { "type" => "shell", "command" => "/abs/path/.superkick/shell/lint.sh" }
+}
+```
+
+Returns `{}` if the directory doesn't exist or contains no executable files.
+
+## Events
+
+### `shell_alert`
+
+Dispatched when the command exits with a non-zero status.
+
+Template variables:
+- `command` — the command string that was run
+- `output` — combined stdout + stderr (captured, may be empty)
+- `exit_code` — integer exit code
+
+### `shell_success`
+
+Dispatched when the command exits with status 0 **and** `report_success` is
+enabled. Disabled by default to avoid noise.
+
+Template variables: same as `shell_alert`.
+
+## Error handling
+
+- Command timeout → SIGTERM sent, output captured up to that point, logged as
+  warning. The tick continues (no event dispatched for the timeout itself).
+- `SystemCallError` / `IOError` → logged, error message returned as output
+  with `nil` status.

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Integrations
+    module Shell
+      # Runs a shell command each tick and dispatches events based on exit status.
+      #
+      # Required config keys: command
+      # Optional config keys: working_dir, timeout, report_success
+      #
+      # Events emitted: shell_alert (non-zero exit), shell_success (zero exit)
+      class Monitor < Superkick::Monitor
+        def self.type = :shell
+
+        def self.description
+          "Runs a shell command on each poll interval and dispatches events based on exit status. " \
+            "Alerts on non-zero exit codes; optionally reports successes. " \
+            "Requires a command string. Optional: working_dir, timeout (default 30s), report_success (bool)."
+        end
+
+        def self.required_config = %i[command]
+
+        def self.setup_label = "Shell"
+
+        def self.setup_config
+          <<~YAML
+            my_check:
+              type: shell
+              command: .superkick/shell/my-check
+              # timeout: 30                     # seconds before command is killed
+              # report_success: false            # also dispatch on exit code 0
+              # working_dir: /path/to/dir        # working directory for command
+          YAML
+        end
+
+        SHELL_DIR = ".superkick/shell"
+
+        # Resolve bare command names relative to .superkick/shell/.
+        # Absolute paths and explicit relative paths (starting with ./ or ../)
+        # are left unchanged.
+        def self.resolve_config(config, environment: {})
+          command = config[:command]
+          if command && !command.include?("/")
+            config[:command] = File.join(SHELL_DIR, command)
+          end
+          config
+        end
+
+        def self.templates_dir
+          File.join(__dir__, "templates")
+        end
+
+        def tick
+          output, status = run_command
+          return if output.nil? && status.nil?
+
+          success = status&.success?
+          return if success && !self[:report_success]
+
+          dispatch(
+            event_type: success ? :shell_success : :shell_alert,
+            command: self[:command],
+            output: output.to_s.strip,
+            exit_code: status&.exitstatus,
+            **(success ? {injection_ttl: 60} : {})
+          )
+        end
+
+        private
+
+        def run_command
+          cmd = self[:command]
+          dir = self[:working_dir]
+          timeout = self[:timeout]&.to_i || 30
+
+          result = ProcessRunner.run(cmd, timeout: timeout, chdir: dir)
+
+          if result[:timed_out]
+            Superkick.logger.warn(log_tag) { "Command timed out after #{timeout}s: #{cmd}" }
+          end
+
+          [result[:output], result[:status]]
+        end
+      end
+    end
+  end
+end

data/lib/superkick/integrations/shell/templates/shell_alert.liquid

@@ -0,0 +1,6 @@
+SUPERKICK [{{ "now" | time }}]: SHELL ALERT — "{{ monitor_name }}" exited with code {{ exit_code }}
+Command: {{ command }}
+{% if output and output != "" -%}
+Output:
+{{ output | truncate: 500 }}
+{% endif -%}

data/lib/superkick/integrations/shell/templates/shell_success.liquid

@@ -0,0 +1,6 @@
+SUPERKICK [{{ "now" | time }}]: SHELL OK — "{{ monitor_name }}" completed successfully
+Command: {{ command }}
+{% if output and output != "" -%}
+Output:
+{{ output | truncate: 500 }}
+{% endif -%}

data/lib/superkick/integrations/shell.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "shell/monitor"
+
+module Superkick
+  Monitor.register(Integrations::Shell::Monitor)
+end

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

@@ -0,0 +1,193 @@
+# Shortcut Monitor
+
+Type: `:shortcut`
+
+Polls [Shortcut](https://shortcut.com) (formerly Clubhouse) for story-level
+changes. Watches a primary story plus its linked stories and epic siblings for
+state changes, new comments, blockers, owner changes, and description updates.
+
+## Configuration
+
+```yaml
+monitors:
+  shortcut:
+    token: <%= env("SHORTCUT_API_TOKEN") %>
+    workspace_slug: my-company
+```
+
+| Key | Required | Default | Description |
+|-----|----------|---------|-------------|
+| `token` | no | `SHORTCUT_API_TOKEN` env var | API token for authentication |
+| `workspace_slug` | no | — | Workspace slug, used to build web URLs in templates |
+| `member` | no | auto-detected | UUID, email, or mention name to identify the current user for self-action filtering |
+| `ignore_self` | no | `true` | Skip events caused by the current user (the API token owner) |
+
+The `story_id` is auto-detected by the probe from the current git branch's
+`sc-XXXXX` pattern — it is not a YAML config key.
+
+## Probe
+
+`ShortcutMonitor::Probe` reads the current branch via `git symbolic-ref` and
+matches against the regex `/sc-(\d+)/`. This covers common Shortcut branch
+patterns:
+
+- `user/sc-12345/my-feature`
+- `sc-12345/fix-bug`
+- `sc-12345`
+
+Returns `{ "shortcut" => { "type" => "shortcut", "story_id" => "12345" } }` on
+match, or `{}` if the branch doesn't contain an `sc-XXXXX` pattern.
+
+The probe cannot detect the API token — that must come from YAML config or the
+`SHORTCUT_API_TOKEN` environment variable.
+
+## Events
+
+### `story_state_changed`
+
+Dispatched when the story's `workflow_state_id` changes between ticks. Resolves
+state IDs to human-readable names via the cached workflow map.
+
+Template variables:
+- `story` — `StoryDrop` with `.id`, `.name`, `.url`, `.ref` (formatted as `sc-123 "title"`)
+- `old_state` — previous workflow state name
+- `new_state` — current workflow state name
+- `new_state_type` — state category (`"backlog"`, `"unstarted"`, `"started"`, `"done"`)
+- `actor` — `MemberDrop` or nil with `.display_name`, `.mention_name`, `.tag`
+
+### `story_comment`
+
+Dispatched for each new comment on the tracked story. Uses a `last_comment_id`
+watermark to avoid re-reporting.
+
+Template variables:
+- `story` — `StoryDrop`
+- `author` — `MemberDrop` for the comment author
+- `body` — comment text
+
+### `story_blocker`
+
+Dispatched when the story's `blocker` field changes from `false` to `true`.
+
+Template variables:
+- `story` — `StoryDrop`
+- `blocker_reason` — text of the latest blocker comment (if any)
+- `actor` — `MemberDrop` or nil
+
+### `story_unblocked`
+
+Dispatched when the story's `blocker` field changes from `true` to `false`.
+
+Template variables:
+- `story` — `StoryDrop`
+- `actor` — `MemberDrop` or nil
+
+### `story_owner_changed`
+
+Dispatched when the story's `owner_ids` array changes. Resolves member UUIDs
+to display names via the cached member map.
+
+Template variables:
+- `story` — `StoryDrop`
+- `added_owners` — array of `MemberDrop` for newly added owners
+- `removed_owners` — array of `MemberDrop` for removed owners
+- `actor` — `MemberDrop` or nil
+
+### `story_description_changed`
+
+Dispatched when the SHA-256 hash of `name + description` changes, indicating
+the story title or description was edited. Includes the full before and after
+text so the AI agent can identify exactly what changed.
+
+Template variables:
+- `story` — `StoryDrop`
+- `old_name` — previous story title
+- `new_name` — current story title
+- `old_description` — previous story description body
+- `new_description` — current story description body
+- `actor` — `MemberDrop` or nil
+
+### `related_story_changed`
+
+Dispatched when a linked story or an epic sibling story changes workflow state.
+Related stories are discovered from the primary story's `story_links` and
+`epic_id` fields, capped at 10 to manage API budget.
+
+Template variables:
+- `story` — `StoryDrop` for the related story
+- `old_state`, `new_state` — workflow state transition
+- `primary_story` — `StoryDrop` for the primary tracked story
+- `relationship` — array of directed verbs (e.g., `["blocks"]`, `["is_blocked_by"]`)
+- `epic_sibling` — boolean
+
+## Self-action filtering
+
+By default (`ignore_self: true`), the monitor skips events caused by the
+current user — the person driving the AI agent. This prevents
+redundant injections when you move your own story through workflow states,
+post comments, or toggle blockers.
+
+**How it works:**
+
+1. On startup, the monitor calls `GET /api/v3/member` to discover the
+   authenticated user's member ID. This can be overridden with the `member`
+   config key — accepts a UUID, email address, or mention name (useful when
+   using a shared/service API token).
+
+2. For **comments**, the monitor compares `comment.author_id` against the
+   current member ID. Self-authored comments are silently dropped.
+
+3. For **state changes, blockers, owner changes, and description changes**,
+   the monitor fetches `GET /api/v3/stories/{id}/history` when a change is
+   detected and checks the `member_id` on the most recent history entry. If
+   the actor is the current user, the event is skipped.
+
+4. **Watermarks are always advanced** regardless of filtering — a skipped
+   self-action won't be re-detected on the next tick.
+
+5. If the history endpoint is unavailable or returns an error, the monitor
+   falls back to dispatching the event (fail-open).
+
+Set `ignore_self: false` to disable this filtering entirely.
+
+## Watermarks
+
+The monitor persists these fields on the agent to avoid duplicate events
+across ticks:
+
+- `last_state_id` — last seen `workflow_state_id`
+- `last_comment_id` — highest seen comment ID
+- `last_blocker` — last seen `blocker` boolean
+- `last_owner_ids` — JSON-encoded array of last seen `owner_ids`
+- `last_description_hash` — SHA-256 of `name + description`
+
+Related story states are tracked in memory (not persisted) — they reset when
+the monitor restarts.
+
+## Caching
+
+The monitor caches two reference datasets in `on_start`:
+
+- **Workflow states** — fetched from `GET /api/v3/workflows`, maps state IDs to
+  names and types. Refreshed on cache miss.
+- **Members** — fetched from `GET /api/v3/members`, maps member UUIDs to mention
+  names. Refreshed on cache miss.
+
+## API usage
+
+The monitor uses the [Shortcut REST API v3](https://developer.shortcut.com/api/rest/v3)
+via Faraday with the `Shortcut-Token` header for authentication. Rate limit is
+200 requests/minute.
+
+Per-tick API budget:
+- 1 request for the primary story
+- 1 request per related story being tracked (up to 10)
+- 1 request for `GET /api/v3/member` on startup (once)
+- 1 request for story history per detected change (only when `ignore_self` is
+  enabled and a change is found — typically 0 per tick)
+
+## Error handling
+
+- HTTP 401/403 → `FatalError` (bad token or no access — stops the monitor)
+- HTTP 429 → `RateLimited` (backs off by `rate_limit_backoff`)
+- HTTP 404 → logged and skipped (story may have been deleted or archived)