superkick 0.1.0

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Integrations
+    module Shortcut
+      # Liquid Drop for Shortcut member data. Wraps the symbol-keyed
+      # hash returned by ShortcutMonitor#resolve_member /
+      # ShortcutSpawner#resolve_member so Liquid templates can access
+      # properties via dot notation (e.g. {{ author.display_name }}).
+      class MemberDrop < Superkick::Drop
+        def self.drop_type = "shortcut_member"
+
+        def display_name = @data[:display_name]
+
+        def mention_name = @data[:mention_name]
+
+        # "Display Name (@mention)" — used in member_list filter and
+        # directly in templates via {{ member.tag }}.
+        def tag = "#{display_name} (@#{mention_name})"
+      end
+
+      # Liquid Drop for a Shortcut story. Wraps the common story fields
+      # (id, name, url) that appear in every Shortcut event, plus optional
+      # extended fields from spawner events (description, type, etc.).
+      #
+      # The `ref` method replaces the `story_ref` filter — it formats
+      # the story reference as `sc-{id} "truncated name"`.
+      class StoryDrop < Superkick::Drop
+        def self.drop_type = "shortcut_story"
+
+        def id = @data[:id]
+
+        def name = @data[:name]
+
+        def url = @data[:url]
+
+        def description = @data[:description]
+
+        def type = @data[:type]
+
+        def workflow_state = @data[:workflow_state]
+
+        def labels = @data[:labels]
+
+        def owners = @data[:owners]
+
+        def epic_name = @data[:epic_name]
+
+        def tasks = @data[:tasks]
+
+        def comments = @data[:comments]
+
+        # Formatted reference: sc-123 "Story title" — replaces story_ref filter.
+        def ref
+          truncated = name.to_s
+          truncated = "#{truncated[0, 47]}..." if truncated.length > 50
+          name_part = truncated.empty? ? "" : " \"#{truncated}\""
+          "sc-#{id}#{name_part}"
+        end
+      end
+
+      # Liquid Drop for Shortcut story tasks.
+      class TaskDrop < Superkick::Drop
+        def self.drop_type = "shortcut_task"
+
+        def description = @data[:description]
+
+        def complete = @data[:complete]
+      end
+
+      # Liquid Drop for Shortcut story comments.
+      class CommentDrop < Superkick::Drop
+        def self.drop_type = "shortcut_comment"
+
+        def author
+          raw = @data[:author]
+          raw.is_a?(MemberDrop) ? raw : MemberDrop.new(raw)
+        end
+
+        def body = @data[:body]
+
+        def created_at = @data[:created_at]
+      end
+    end
+  end
+end
+
+Superkick::Drop.register(Superkick::Integrations::Shortcut::MemberDrop)
+Superkick::Drop.register(Superkick::Integrations::Shortcut::StoryDrop)
+Superkick::Drop.register(Superkick::Integrations::Shortcut::TaskDrop)
+Superkick::Drop.register(Superkick::Integrations::Shortcut::CommentDrop)

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

@@ -0,0 +1,582 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require "digest"
+
+module Superkick
+  module Integrations
+    module Shortcut
+      # Polls Shortcut (formerly Clubhouse) for story-level changes.
+      #
+      # Config keys provided by probe: story_id (auto-detected from sc-XXXXX branch)
+      # Optional config keys: token (or SHORTCUT_API_TOKEN env var),
+      #                        workspace_slug (for building web URLs),
+      #                        member (UUID, email, or mention name to identify current user),
+      #                        ignore_self (default true — skip self-authored changes)
+      #
+      # Events emitted: story_state_changed, story_comment, story_blocker,
+      #                 story_unblocked, story_owner_changed,
+      #                 story_description_changed, related_story_changed
+      #
+      # Watermarks persisted: last_state_id, last_comment_id, last_blocker,
+      #                       last_owner_ids, last_description_hash
+      class Monitor < Superkick::Monitor
+        API_BASE = "https://api.app.shortcut.com"
+        BRANCH_STORY_RE = /sc-(\d+)/
+
+        attr_reader :conn
+
+        def self.type = :shortcut
+
+        def self.description
+          "Monitors a Shortcut story for state changes, new comments, blockers, " \
+            "owner changes, and description updates. Also watches linked and sibling stories " \
+            "under the same epic. story_id is auto-detected from sc-XXXXX branch pattern. " \
+            "Optionally accepts a token (or set SHORTCUT_API_TOKEN env var) and workspace_slug. " \
+            "Self-authored changes are ignored by default (set ignore_self: false to disable)."
+        end
+
+        def self.required_config = %i[story_id]
+
+        def self.setup_label = "Shortcut"
+
+        def self.setup_config
+          <<~YAML
+            shortcut:
+              token: <%= env("SHORTCUT_API_TOKEN") %>
+              # story_id is auto-detected from sc-XXXXX branch pattern.
+              # Uncomment to set explicitly:
+              # story_id: 12345
+              # workspace_slug: my-workspace    # enables story URL generation
+              # ignore_self: true               # skip self-authored changes (default)
+          YAML
+        end
+
+        # Fill in missing story_id from the git branch name (sc-XXXXX pattern).
+        def self.resolve_config(config, environment: {})
+          unless config[:story_id]
+            branch = environment[:git_branch].to_s
+            match = BRANCH_STORY_RE.match(branch)
+            config[:story_id] = match[1] if match
+          end
+          config
+        end
+
+        def self.templates_dir
+          File.join(__dir__, "templates")
+        end
+
+        def initialize(name:, config:, handler:, agent: nil, server_context: {}, connection: nil)
+          super(name:, config:, handler:, agent:, server_context:)
+          @conn = connection
+        end
+
+        def tick
+          story_id = self[:story_id].to_i
+          story = fetch_story(story_id)
+          return unless story
+
+          check_state_change(story)
+          check_comments(story)
+          check_blocker(story)
+          check_owners(story)
+          check_description(story)
+          check_related_stories(story)
+        end
+
+        def on_start
+          @conn ||= build_connection
+          @workflow_states = fetch_workflow_states
+          @members = fetch_members
+          @current_member_id = detect_current_member
+        end
+
+        private
+
+        # ── Self-action filtering ────────────────────────────────────────────────
+
+        def ignore_self?
+          self[:ignore_self].nil? || self[:ignore_self]
+        end
+
+        UUID_PATTERN = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
+        private_constant :UUID_PATTERN
+
+        def detect_current_member
+          member = self[:member]
+          if member
+            resolved = resolve_member_config(member)
+            if resolved
+              Superkick.logger.info(log_tag) { "Resolved member #{member.inspect} to #{resolved}" }
+              return resolved
+            end
+            Superkick.logger.warn(log_tag) { "Could not resolve member #{member.inspect}" }
+            return nil
+          end
+
+          # Auto-detect from API token
+          resp = get("/api/v3/member")
+          return nil unless resp
+
+          data = resp.body
+          member_id = data["id"]
+          mention = data["mention_name"] || data.dig("profile", "mention_name") || member_id
+          Superkick.logger.info(log_tag) { "Detected current member: #{mention} (#{member_id})" }
+          member_id
+        rescue => e
+          Superkick.logger.warn(log_tag) { "Could not detect current member: #{e.message}" }
+          nil
+        end
+
+        def resolve_member_config(value)
+          # UUID — use directly
+          return value if value.match?(UUID_PATTERN)
+
+          # Email — lookup by email_address
+          # Mention name — lookup by mention_name
+          resp = get("/api/v3/members")
+          return nil unless resp
+
+          members = resp.body
+          match = if value.include?("@")
+            members.find { |m| (m.dig("profile", "email_address") || "").casecmp?(value) }
+          else
+            members.find { |m| (m.dig("profile", "mention_name") || "") == value }
+          end
+          match&.dig("id")
+        end
+
+        def self_action?(actor_id)
+          ignore_self? && @current_member_id && actor_id == @current_member_id
+        end
+
+        def latest_history_actor(story_id)
+          resp = get("/api/v3/stories/#{story_id}/history")
+          return nil unless resp
+
+          entries = resp.body
+          return nil if entries.empty?
+
+          # History entries are chronological; last entry is most recent
+          latest = entries.last
+          latest["member_id"]
+        rescue => e
+          Superkick.logger.debug(log_tag) { "Could not fetch story history: #{e.message}" }
+          nil
+        end
+
+        # ── Story fetch ─────────────────────────────────────────────────────────
+
+        def fetch_story(story_id)
+          resp = get("/api/v3/stories/#{story_id}")
+          return nil unless resp
+
+          resp.body
+        end
+
+        # ── State changes ───────────────────────────────────────────────────────
+
+        def check_state_change(story)
+          current_state_id = story["workflow_state_id"]
+          last_state_id = self[:last_state_id]
+
+          # Seed watermark on first tick
+          if last_state_id.nil?
+            @agent.set_monitor_field(@name, :last_state_id, current_state_id)
+            @config[:last_state_id] = current_state_id
+            return
+          end
+
+          return if current_state_id == last_state_id
+
+          old_state = resolve_state(last_state_id)
+          new_state = resolve_state(current_state_id)
+          new_state_type = resolve_state_type(current_state_id)
+
+          @agent.set_monitor_field(@name, :last_state_id, current_state_id)
+          @config[:last_state_id] = current_state_id
+
+          actor_id = latest_history_actor(story["id"])
+          return if self_action?(actor_id)
+
+          dispatch(
+            event_type: :story_state_changed,
+            story: story_drop(story),
+            old_state:,
+            new_state:,
+            new_state_type:,
+            actor: actor_id ? member_drop(actor_id) : nil
+          )
+        end
+
+        # ── Comments ────────────────────────────────────────────────────────────
+
+        def check_comments(story)
+          comments = story["comments"] || []
+          last_id = self[:last_comment_id]&.to_i || 0
+
+          # Seed watermark on first tick
+          if self[:last_comment_id].nil? && comments.any?
+            max_id = comments.map { |c| c["id"] }.max
+            @agent.set_monitor_field(@name, :last_comment_id, max_id)
+            @config[:last_comment_id] = max_id
+            return
+          end
+
+          new_comments = comments.select { |c| c["id"] > last_id }
+          return if new_comments.empty?
+
+          # Always advance the watermark (even for self-authored comments)
+          max_id = new_comments.map { |c| c["id"] }.max
+          @agent.set_monitor_field(@name, :last_comment_id, max_id)
+          @config[:last_comment_id] = max_id
+
+          # Filter out self-authored comments
+          if ignore_self? && @current_member_id
+            new_comments = new_comments.reject { |c| c["author_id"] == @current_member_id }
+          end
+
+          new_comments.each do |comment|
+            dispatch(
+              event_type: :story_comment,
+              story: story_drop(story),
+              author: member_drop(comment["author_id"]),
+              body: comment["text"].to_s.strip
+            )
+          end
+        end
+
+        # ── Blocker status ──────────────────────────────────────────────────────
+
+        def check_blocker(story)
+          current_blocker = story["blocker"] || false
+          last_blocker = self[:last_blocker]
+
+          # Seed watermark on first tick
+          if last_blocker.nil?
+            @agent.set_monitor_field(@name, :last_blocker, current_blocker)
+            @config[:last_blocker] = current_blocker
+            return
+          end
+
+          return if current_blocker == last_blocker
+
+          @agent.set_monitor_field(@name, :last_blocker, current_blocker)
+          @config[:last_blocker] = current_blocker
+
+          actor_id = latest_history_actor(story["id"])
+          return if self_action?(actor_id)
+
+          if current_blocker
+            # Look for blocker comments
+            comments = story["comments"] || []
+            blocker_comments = comments.select { |c| c["blocker"] }
+            blocker_reason = blocker_comments.last&.dig("text")
+
+            dispatch(
+              event_type: :story_blocker,
+              story: story_drop(story),
+              blocker_reason: blocker_reason,
+              actor: actor_id ? member_drop(actor_id) : nil,
+              injection_priority: :high,
+              injection_supersede_key: "story_blocker_status"
+            )
+          else
+            dispatch(
+              event_type: :story_unblocked,
+              story: story_drop(story),
+              actor: actor_id ? member_drop(actor_id) : nil,
+              injection_ttl: 120,
+              injection_supersede_key: "story_blocker_status"
+            )
+          end
+        end
+
+        # ── Owner changes ───────────────────────────────────────────────────────
+
+        def check_owners(story)
+          owner_ids = story["owner_ids"] || []
+          current_ids = owner_ids.sort
+          last_ids_json = self[:last_owner_ids]
+
+          # Seed watermark on first tick
+          if last_ids_json.nil?
+            @agent.set_monitor_field(@name, :last_owner_ids, JSON.generate(current_ids))
+            @config[:last_owner_ids] = JSON.generate(current_ids)
+            return
+          end
+
+          last_ids = JSON.parse(last_ids_json).sort
+          return if current_ids == last_ids
+
+          @agent.set_monitor_field(@name, :last_owner_ids, JSON.generate(current_ids))
+          @config[:last_owner_ids] = JSON.generate(current_ids)
+
+          actor_id = latest_history_actor(story["id"])
+          return if self_action?(actor_id)
+
+          added = current_ids - last_ids
+          removed = last_ids - current_ids
+
+          dispatch(
+            event_type: :story_owner_changed,
+            story: story_drop(story),
+            added_owners: added.map { member_drop(it) },
+            removed_owners: removed.map { member_drop(it) },
+            actor: actor_id ? member_drop(actor_id) : nil
+          )
+        end
+
+        # ── Description changes ─────────────────────────────────────────────────
+
+        def check_description(story)
+          current_name = story["name"].to_s
+          current_description = story["description"].to_s
+          content = "#{current_name}\n#{current_description}"
+          current_hash = Digest::SHA256.hexdigest(content)
+          last_hash = self[:last_description_hash]
+
+          # Seed watermark on first tick
+          if last_hash.nil?
+            @last_name = current_name
+            @last_description = current_description
+            @agent.set_monitor_field(@name, :last_description_hash, current_hash)
+            @config[:last_description_hash] = current_hash
+            return
+          end
+
+          return if current_hash == last_hash
+
+          old_name = @last_name || current_name
+          old_description = @last_description || current_description
+
+          @last_name = current_name
+          @last_description = current_description
+          @agent.set_monitor_field(@name, :last_description_hash, current_hash)
+          @config[:last_description_hash] = current_hash
+
+          actor_id = latest_history_actor(story["id"])
+          return if self_action?(actor_id)
+
+          dispatch(
+            event_type: :story_description_changed,
+            story: story_drop(story),
+            old_name:,
+            new_name: current_name,
+            old_description:,
+            new_description: current_description,
+            actor: actor_id ? member_drop(actor_id) : nil
+          )
+        end
+
+        # ── Related stories (linked + epic siblings) ────────────────────────────
+
+        def check_related_stories(story)
+          @related_states ||= {}
+
+          related_ids = collect_related_ids(story)
+          return if related_ids.empty?
+
+          related_ids.each do |rid|
+            related = fetch_story(rid)
+            next unless related
+
+            current_state_id = related["workflow_state_id"]
+            last_state_id = @related_states[rid]
+
+            if last_state_id.nil?
+              @related_states[rid] = current_state_id
+              next
+            end
+
+            next if current_state_id == last_state_id
+
+            @related_states[rid] = current_state_id
+
+            dispatch(
+              event_type: :related_story_changed,
+              story: story_drop(related),
+              old_state: resolve_state(last_state_id),
+              new_state: resolve_state(current_state_id),
+              primary_story: story_drop(story),
+              relationship: directed_verbs(story, related),
+              epic_sibling: epic_sibling?(story, related)
+            )
+          end
+        end
+
+        def collect_related_ids(story)
+          ids = Set.new
+
+          # Linked stories
+          story_links = story["story_links"] || []
+          story_links.each do |link|
+            other_id = (link["subject_id"] == story["id"]) ? link["object_id"] : link["subject_id"]
+            ids.add(other_id)
+          end
+
+          # Epic siblings
+          epic_id = story["epic_id"]
+          if epic_id && !@epic_stories_fetched
+            @epic_stories_fetched = true
+            @epic_story_ids = fetch_epic_story_ids(epic_id) - [story["id"]]
+          end
+
+          ids.merge(@epic_story_ids || [])
+          ids.to_a.first(10) # Cap to avoid too many API calls
+        end
+
+        def fetch_epic_story_ids(epic_id)
+          resp = get("/api/v3/epics/#{epic_id}/stories")
+          return [] unless resp
+
+          stories = resp.body
+          stories.map { |s| s["id"] }
+        end
+
+        INVERSE_VERBS = {
+          "blocks" => "is blocked by",
+          "duplicates" => "is duplicated by",
+          "relates to" => "relates to"
+        }.freeze
+
+        def directed_verbs(primary, related)
+          primary_links = primary["story_links"] || []
+          links = primary_links.select do |l|
+            l["subject_id"] == related["id"] || l["object_id"] == related["id"]
+          end
+
+          links.map do |l|
+            verb = l["verb"]
+            if l["subject_id"] == primary["id"]
+              verb
+            else
+              INVERSE_VERBS[verb] || verb
+            end
+          end
+        end
+
+        def epic_sibling?(primary, related)
+          primary["epic_id"] && primary["epic_id"] == related["epic_id"]
+        end
+
+        # ── Workflow state resolution ───────────────────────────────────────────
+
+        def fetch_workflow_states
+          resp = get("/api/v3/workflows")
+          return {} unless resp
+
+          states = {}
+          workflows = resp.body
+          workflows.each do |wf|
+            wf_states = wf["states"] || []
+            wf_states.each do |s|
+              states[s["id"]] = {name: s["name"], type: s["type"]}
+            end
+          end
+          states
+        end
+
+        def resolve_state(state_id)
+          entry = @workflow_states[state_id]
+          return entry[:name] if entry
+
+          # Cache miss — refetch
+          @workflow_states = fetch_workflow_states
+          @workflow_states.dig(state_id, :name) || "Unknown (#{state_id})"
+        end
+
+        def resolve_state_type(state_id)
+          entry = @workflow_states[state_id]
+          return entry[:type] if entry
+
+          @workflow_states = fetch_workflow_states
+          @workflow_states.dig(state_id, :type) || "unknown"
+        end
+
+        # ── Member resolution ───────────────────────────────────────────────────
+
+        def fetch_members
+          resp = get("/api/v3/members")
+          return {} unless resp
+
+          members = resp.body
+          members.each_with_object({}) do |m, h|
+            profile = m["profile"] || {}
+            h[m["id"]] = {
+              mention_name: profile["mention_name"] || m["id"],
+              display_name: profile["name"] || profile["mention_name"] || m["id"]
+            }
+          end
+        end
+
+        def resolve_member(member_id)
+          return {mention_name: "unknown", display_name: "unknown"} unless member_id
+
+          info = @members[member_id]
+          return info if info
+
+          # Cache miss — refetch
+          @members = fetch_members
+          @members[member_id] || {mention_name: member_id.to_s, display_name: member_id.to_s}
+        end
+
+        # ── Drop helpers ──────────────────────────────────────────────────────
+
+        def member_drop(member_id)
+          MemberDrop.new(resolve_member(member_id))
+        end
+
+        def story_drop(story, **extra)
+          StoryDrop.new({
+            id: story["id"],
+            name: story["name"],
+            url: story_url(story["id"]),
+            **extra
+          })
+        end
+
+        # ── URL helpers ─────────────────────────────────────────────────────────
+
+        def story_url(story_id)
+          slug = self[:workspace_slug]
+          return nil unless slug
+
+          "https://app.shortcut.com/#{slug}/story/#{story_id}"
+        end
+
+        # ── HTTP helpers ────────────────────────────────────────────────────────
+
+        def get(path)
+          resp = @conn.get(path)
+          return nil unless handle_response!(resp)
+          resp
+        end
+
+        # Returns true on success, raises on auth/rate-limit, returns false on 404.
+        def handle_response!(resp)
+          case resp.status
+          when 200..299 then true
+          when 401, 403 then raise FatalError, "Shortcut auth failed (HTTP #{resp.status})"
+          when 429 then raise RateLimited, "Shortcut rate limited (HTTP 429)"
+          when 404
+            Superkick.logger.warn(log_tag) { "Shortcut resource not found (HTTP 404)" }
+            false
+          else
+            false
+          end
+        end
+
+        def build_connection
+          token = self[:token] || ENV["SHORTCUT_API_TOKEN"]
+
+          Faraday.new(url: API_BASE) do |f|
+            f.headers["Shortcut-Token"] = token if token
+            f.response :json
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Integrations
+    module Shortcut
+      # Detects a Shortcut story ID from the agent's git branch name.
+      #
+      # Shortcut's Git integration creates branches with patterns like:
+      #   user/sc-12345/my-feature
+      #   sc-12345/my-feature
+      #   sc-12345
+      class Monitor::Probe < Superkick::Monitor::Probe
+        def self.type = :shortcut
+
+        def self.description
+          "Detects Shortcut story ID from git branch name (sc-XXXXX pattern)."
+        end
+
+        def self.environment_actions
+          [{action: :git_branch}]
+        end
+
+        # @param environment [Hash] environment data from the agent
+        # @return [Hash] { shortcut: { type: "shortcut", story_id: "12345" } } or {}
+        def self.detect(environment:)
+          config = Monitor.resolve_config({}, environment:)
+          return {} unless config[:story_id]
+
+          {shortcut: config.merge(type: "shortcut")}
+        end
+      end
+    end
+  end
+end