superkick 0.1.0

data/lib/superkick/notifier_state_store.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Superkick
+  # NotifierStateStore — injectable key-value state storage for stateful notifiers.
+  #
+  # Stateful notifiers (Slack, Datadog, Honeybadger) track per-agent state across
+  # events (e.g. Slack thread_ts for threading, spawned_at for duration computation).
+  # This class provides an explicit, injectable interface for that state.
+  #
+  # The Memory subclass preserves current behavior (in-memory, mutex-protected,
+  # lost on server restart). The hosted Rails app provides a database-backed
+  # implementation for persistence and multi-process sharing.
+  #
+  # Interface:
+  #   get(notifier_type, key) → Hash or nil
+  #   put(notifier_type, key, data) → void
+  #   delete(notifier_type, key) → void
+  class NotifierStateStore
+    def get(notifier_type, key)
+      raise NotImplementedError, "#{self.class}#get not implemented"
+    end
+
+    def put(notifier_type, key, data)
+      raise NotImplementedError, "#{self.class}#put not implemented"
+    end
+
+    def delete(notifier_type, key)
+      raise NotImplementedError, "#{self.class}#delete not implemented"
+    end
+
+    # In-memory implementation — thread-safe, process-local, lost on restart.
+    # Default for local server mode.
+    class Memory < NotifierStateStore
+      def initialize
+        @data = {}
+        @mutex = Mutex.new
+      end
+
+      def get(notifier_type, key)
+        @mutex.synchronize { @data.dig(notifier_type, key)&.dup }
+      end
+
+      def put(notifier_type, key, data)
+        @mutex.synchronize do
+          @data[notifier_type] ||= {}
+          @data[notifier_type][key] = data
+        end
+      end
+
+      def delete(notifier_type, key)
+        @mutex.synchronize { @data[notifier_type]&.delete(key) }
+      end
+    end
+  end
+end

data/lib/superkick/notifier_template.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "liquid"
+
+module Superkick
+  # NotifierTemplate — renders Liquid templates with structured output via
+  # block tags. Block tags accumulate data onto a mutable accumulator
+  # (stored in Liquid registers), producing both structured and text output.
+  #
+  # Usage:
+  #
+  #   block_class = NotifierTemplate.create_block_class(->(ctx, text, attrs) {
+  #     ctx.blocks << { type: "header", text: text }
+  #   })
+  #
+  #   result = NotifierTemplate.render(
+  #     source: template_source,
+  #     environment: liquid_environment,
+  #     assigns: { "event_type" => "agent_completed" },
+  #     accumulator: SlackContext.new
+  #   )
+  #   result[:structured]  # => SlackContext with populated blocks
+  #   result[:text]        # => rendered text outside block tags
+  class NotifierTemplate
+    # Generate a Liquid::Block subclass that accumulates structured output.
+    # The handler receives (accumulator, rendered_body_text, attributes) and
+    # pushes structured data onto the accumulator. The block renders as ""
+    # in the template output — structured results are read from the
+    # accumulator after rendering.
+    #
+    # Attribute values are resolved as Liquid expressions at render time:
+    #   - Quoted values (`key: "literal"`) stay as literal strings
+    #   - Bare identifiers (`key: issue.url`) are resolved from the
+    #     template context, matching the behavior of Liquid's built-in
+    #     {% render %} and {% include %} tags
+    def self.create_block_class(handler)
+      Class.new(::Liquid::Block) do
+        define_method(:render) do |context|
+          text = super(context).strip
+          attrs = evaluate_attributes(context)
+          handler.call(context.registers[:notifier_accumulator], text, attrs)
+          ""
+        end
+
+        private
+
+        define_method(:parse_raw_attributes) do
+          @_parsed_expressions ||= begin
+            markup = @markup.to_s.strip
+            return {} if markup.empty?
+
+            exprs = {}
+            markup.scan(::Liquid::TagAttributes) do |key, raw_value|
+              exprs[key] = ::Liquid::Expression.parse(raw_value)
+            end
+            exprs
+          end
+        end
+
+        define_method(:evaluate_attributes) do |context|
+          parse_raw_attributes.each_with_object({}) do |(key, expr), attrs|
+            value = context.evaluate(expr)
+            attrs[key] = value.to_s unless value.nil?
+          end
+        end
+      end
+    end
+
+    # Generate a Liquid::Tag subclass (bodyless — no end tag) that
+    # accumulates structured output. The handler receives
+    # (accumulator, attributes) and pushes structured data onto the
+    # accumulator. The tag renders as "" in the template output.
+    #
+    # Attribute values are resolved as Liquid expressions at render time
+    # (see create_block_class for details).
+    def self.create_tag_class(handler)
+      Class.new(::Liquid::Tag) do
+        define_method(:render) do |context|
+          attrs = evaluate_attributes(context)
+          handler.call(context.registers[:notifier_accumulator], attrs)
+          ""
+        end
+
+        private
+
+        define_method(:parse_raw_attributes) do
+          @_parsed_expressions ||= begin
+            markup = @markup.to_s.strip
+            return {} if markup.empty?
+
+            exprs = {}
+            markup.scan(::Liquid::TagAttributes) do |key, raw_value|
+              exprs[key] = ::Liquid::Expression.parse(raw_value)
+            end
+            exprs
+          end
+        end
+
+        define_method(:evaluate_attributes) do |context|
+          parse_raw_attributes.each_with_object({}) do |(key, expr), attrs|
+            value = context.evaluate(expr)
+            attrs[key] = value.to_s unless value.nil?
+          end
+        end
+      end
+    end
+
+    # Render a template, returning { structured:, text: }.
+    #
+    # @param source      [String]            Liquid template source
+    # @param environment [Liquid::Environment] pre-built environment with filters and tags
+    # @param assigns     [Hash]              template variables (string keys)
+    # @param accumulator [Object]            mutable accumulator for block tags
+    # @return [Hash] { structured: accumulator, text: rendered_text }
+    def self.render(source:, environment:, assigns:, accumulator:)
+      template = ::Liquid::Template.parse(source, environment:)
+      text = template.render(assigns, registers: {notifier_accumulator: accumulator}).strip
+      {structured: accumulator, text:}
+    end
+  end
+end

data/lib/superkick/notifiers/command.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Notifiers
+    # Runs a shell command when an injection or lifecycle event occurs.
+    #
+    # The command string is executed via the system shell. Event details
+    # are passed as environment variables so commands can build rich
+    # notifications:
+    #
+    #   SUPERKICK_EVENT_TYPE   — e.g. "ci_failure", "pr_comment"
+    #   SUPERKICK_MONITOR_TYPE — e.g. "github", "shell"
+    #   SUPERKICK_MONITOR_NAME — e.g. "github", "disk_check"
+    #   SUPERKICK_AGENT_ID     — the agent that received the injection
+    #   SUPERKICK_MESSAGE      — a short human-readable summary
+    #   SUPERKICK_BODY         — rendered template text (empty if no template)
+    #
+    # The command string also supports $VARIABLE interpolation for
+    # inline use:
+    #
+    #   notifications:
+    #     - type: command
+    #       run: "notify-send 'Superkick' '$SUPERKICK_MESSAGE'"
+    #     - type: command
+    #       run: "curl -X POST $SLACK_WEBHOOK -d '{\"text\": \"$SUPERKICK_BODY\"}'"
+    #
+    # Template support:
+    #   Templates can define additional env vars using the {% env %} block tag:
+    #
+    #     {% env key: "pr_title" %}{{ pull_request.title }}{% endenv %}
+    #     {% env key: "repo" %}{{ repo }}{% endenv %}
+    #     PR #{{ pull_request.number }} needs review.
+    #
+    #   The {% env %} blocks populate SUPERKICK_PR_TITLE, SUPERKICK_REPO, etc.
+    #   Text outside blocks becomes SUPERKICK_BODY. All names are uppercased
+    #   and prefixed with SUPERKICK_ automatically.
+    #
+    #   Templates are resolved from:
+    #     1. ~/.superkick/templates/notifications/command/<event_type>.liquid
+    #     2. ~/.superkick/templates/notifications/command/default.liquid
+    #
+    # Commands are killed after timeout_seconds (default 10) to prevent
+    # hung notification processes from accumulating.
+    class Command < Notifier
+      def self.type = :command
+
+      def self.setup_label = "Command"
+
+      def self.setup_config
+        <<~YAML
+          - type: command
+            run: "notify-send 'Superkick' '$SUPERKICK_MESSAGE'"
+            # timeout_seconds: 10               # kill command after this many seconds
+            # events:                            # restrict which events fire this notifier
+            #   - agent_completed
+            #   - agent_failed
+            #   - agent_blocked
+        YAML
+      end
+
+      DEFAULT_TIMEOUT = 10
+
+      liquid do
+        context do
+          attribute :env_vars, default: -> { {} }
+        end
+
+        block :env do |ctx, text, attrs|
+          name = attrs["key"]
+          ctx.env_vars[name] = text if name
+        end
+      end
+
+      def initialize(run: nil, timeout_seconds: DEFAULT_TIMEOUT, **opts)
+        super(**opts)
+        @run = run
+        @timeout_seconds = timeout_seconds.to_i
+      end
+
+      def notify(payload)
+        unless @run
+          Superkick.logger.warn("notifier:command") { "No 'run' command configured — skipping" }
+          return
+        end
+
+        env = build_env(payload)
+        result = ProcessRunner.spawn(@run, timeout: @timeout_seconds, env:)
+
+        if result[:timed_out]
+          Superkick.logger.warn("notifier:command") { "Command timed out after #{@timeout_seconds}s: #{@run}" }
+        elsif result[:status] && !result[:status].success?
+          Superkick.logger.warn("notifier:command") { "Command exited #{result[:status].exitstatus}" }
+        end
+      rescue Errno::ENOENT => e
+        Superkick.logger.warn("notifier:command") { "Command not found: #{e.message}" }
+      end
+
+      private
+
+      def build_env(payload)
+        monitor = payload[:monitor]
+        env = {
+          "SUPERKICK_EVENT_TYPE" => payload[:event_type].to_s,
+          "SUPERKICK_MONITOR_TYPE" => monitor&.type.to_s,
+          "SUPERKICK_MONITOR_NAME" => monitor&.name.to_s,
+          "SUPERKICK_AGENT_ID" => payload[:agent_id].to_s,
+          "SUPERKICK_MESSAGE" => payload[:message].to_s
+        }
+
+        template_result = render_notification(payload)
+        if template_result
+          env["SUPERKICK_BODY"] = template_result[:text]
+          template_result[:structured].env_vars.each do |name, value|
+            env["SUPERKICK_#{name.upcase}"] = value
+          end
+        end
+
+        env
+      end
+    end
+  end
+
+  Notifier.register(Notifiers::Command)
+end

data/lib/superkick/notifiers/terminal_bell.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Notifiers
+    # Writes a BEL character (\a) to the server's original TTY.
+    #
+    # This is the zero-config default notifier. Most terminal emulators
+    # respond to BEL with a visual or audible alert:
+    #   - iTerm2 bounces the dock icon
+    #   - tmux marks the window with activity
+    #   - GNOME Terminal flashes the tab title
+    #   - Windows Terminal flashes the taskbar
+    #
+    # Config (config.yml):
+    #   notifications:
+    #     - type: terminal_bell
+    class TerminalBell < Notifier
+      def self.type = :terminal_bell
+
+      def self.setup_label = "Terminal Bell"
+
+      def self.setup_config
+        <<~YAML
+          - type: terminal_bell
+        YAML
+      end
+
+      def notify(payload)
+        # Write BEL to stderr — the server's stderr is typically
+        # connected to the controlling terminal (unless daemonized,
+        # in which case it's redirected to the log file and the bell
+        # is a harmless no-op).
+        $stderr.write("\a")
+      rescue IOError
+        # stderr closed or redirected — nothing to do.
+      end
+    end
+  end
+
+  Notifier.register(Notifiers::TerminalBell)
+end

data/lib/superkick/output_logger.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Superkick
+  # Manages writing PTY output to a per-agent log file.
+  # Raw bytes (including ANSI escape codes) are written in append mode
+  # with sync flushing so `tail -f` works in real time.
+  #
+  # Simple size-based rotation: one rotated file (*.1). When the log
+  # exceeds max_size, the current file becomes .1 and a new file starts.
+  class OutputLogger
+    MAX_SIZE = 10 * 1024 * 1024 # 10 MB default
+
+    def initialize(agent_id:, max_size: MAX_SIZE, log_dir: Superkick.config.output_logs_dir)
+      @path = File.join(log_dir, "#{agent_id}.log")
+      @max_size = max_size
+      @file = nil
+      @bytes_written = 0
+    end
+
+    def start
+      FileUtils.mkdir_p(File.dirname(@path))
+      @file = File.open(@path, "ab")
+      @file.sync = true
+      @bytes_written = @file.size
+      self
+    end
+
+    def write(data)
+      return unless @file
+      rotate! if @bytes_written + data.bytesize > @max_size
+      @file.write(data)
+      @bytes_written += data.bytesize
+    end
+
+    def close
+      @file&.close
+      @file = nil
+    end
+
+    attr_reader :path
+
+    private
+
+    def rotate!
+      @file.close
+      rotated = "#{@path}.1"
+      FileUtils.rm_f(rotated)
+      File.rename(@path, rotated)
+      @file = File.open(@path, "ab")
+      @file.sync = true
+      @bytes_written = 0
+    end
+  end
+end

data/lib/superkick/poller.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require_relative "liquid"
+
+module Superkick
+  # Poller — abstract base class for all polling event sources.
+  #
+  # Provides the shared run loop, error handling, backoff, and config
+  # validation used by both Monitor (agent-bound) and Spawner (server-level).
+  #
+  # Subclass contract:
+  #   self.type              → unique Symbol
+  #   self.description       → human-readable summary (optional)
+  #   self.required_config   → Array of Symbol keys validated before start
+  #   self.templates_dir     → path to Liquid templates (optional)
+  #   liquid do ... end      → declare Liquid filters, blocks, context (optional)
+  #   tick                   → called each interval; use dispatch(event) to emit
+  #   on_start               → optional hook called once before the run loop
+  class Poller
+    include Superkick::Liquid
+
+    # Raised inside tick to signal API rate-limit; triggers backoff.
+    class RateLimited < StandardError; end
+
+    # Raised inside tick to signal a permanent configuration error; exits thread.
+    class FatalError < StandardError; end
+
+    attr_reader :name
+
+    def initialize(name:, config:, handler:)
+      @name = name.to_s
+      @config = config
+      @handler = handler
+      @running = false
+    end
+
+    # Config accessor — always use symbol keys.
+    def [](key)
+      @config[key.to_sym]
+    end
+
+    # Start the blocking run loop (call from a dedicated thread).
+    def run
+      begin
+        validate_config!
+        on_start
+      rescue FatalError => e
+        Superkick.logger.error(log_tag) { "Fatal startup error: #{e.message}" }
+        return
+      end
+      @running = true
+
+      loop do
+        flush_pending_events
+        begin
+          tick
+        rescue RateLimited => e
+          Superkick.logger.warn(log_tag) { "Rate limited: #{e.message}; backing off #{Superkick.config.rate_limit_backoff}s" }
+          sleep(Superkick.config.rate_limit_backoff)
+        rescue FatalError => e
+          Superkick.logger.error(log_tag) { "Fatal error: #{e.message}; stopping" }
+          break
+        rescue => e
+          Superkick.logger.error(log_tag) { "Unexpected error: #{e.message}\n#{e.backtrace.first(3).join("\n")}" }
+          sleep(Superkick.config.error_backoff)
+        end
+
+        sleep(Superkick.config.poll_interval)
+      end
+    ensure
+      @running = false
+    end
+
+    def stop
+      @running = false
+    end
+
+    # Called once before the run loop starts.
+    def on_start
+    end
+
+    # Subclasses must implement.
+    def tick
+      raise NotImplementedError, "#{self.class}#tick not implemented"
+    end
+
+    def log_tag
+      "#{self.class.type}(#{@name})"
+    end
+
+    # Class-level interface that subclasses must implement:
+    #   self.type           → Symbol
+    #   self.required_config → Array of Symbol keys
+    #   self.templates_dir  → path or nil
+    #   self.description    → String or nil
+
+    class << self
+      def type
+        raise NotImplementedError, "#{self}.type not defined"
+      end
+
+      def description = nil
+      def required_config = []
+      def templates_dir = nil
+      def setup_label = nil
+      def setup_config = nil
+
+      def event_types
+        dir = templates_dir
+        return [] unless dir && File.directory?(dir)
+        Dir.glob(File.join(dir, "*.liquid")).map { |f| File.basename(f, ".liquid") }.sort
+      end
+    end
+
+    private
+
+    def flush_pending_events
+      @handler.flush_pending
+    end
+
+    def validate_config!
+      missing = self.class.required_config.reject { |k| @config.key?(k.to_sym) }
+      raise FatalError, "Missing required config keys: #{missing.join(", ")}" unless missing.empty?
+    end
+  end
+end

data/lib/superkick/process_runner.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Superkick
+  # Unified subprocess execution with reliable timeouts.
+  #
+  # Ruby's Timeout.timeout uses Thread.raise to deliver async exceptions,
+  # which cannot reliably interrupt C-level blocking calls like waitpid
+  # or IO#read.  This module avoids Timeout entirely:
+  #
+  #   .run   — captures stdout+stderr, returns {output:, status:, timed_out:}
+  #   .spawn — fire-and-forget, no output capture, kills on timeout
+  #
+  # Both methods SIGTERM the child on timeout and reap it to prevent
+  # zombies.  All timeouts use CLOCK_MONOTONIC to avoid wall-clock skew.
+  module ProcessRunner
+    # Run a command, capture combined stdout+stderr, and return the result.
+    #
+    # @param cmd     [String]  shell command to execute
+    # @param timeout [Integer] seconds before SIGTERM (default 30)
+    # @param env     [Hash]    environment variables (default {})
+    # @param chdir   [String, nil] working directory (default nil)
+    # @return [Hash] { output: String, status: Process::Status|nil, timed_out: Boolean }
+    def self.run(cmd, timeout: 30, env: {}, chdir: nil)
+      options = {err: [:child, :out]}
+      options[:chdir] = chdir if chdir
+
+      output = +""
+      timed_out = false
+
+      IO.popen(env, cmd, **options) do |io|
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+
+        loop do
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          if remaining <= 0
+            Process.kill("TERM", io.pid)
+            timed_out = true
+            break
+          end
+
+          ready = IO.select([io], nil, nil, [remaining, 0.5].min)
+          if ready
+            chunk = io.read_nonblock(8192, exception: false)
+            break if chunk == :wait_readable
+            break if chunk.nil? # EOF
+            output << chunk
+          end
+        end
+
+        io.close
+      end
+
+      {output:, status: $?, timed_out:}
+    rescue SystemCallError, IOError => e
+      {output: e.message, status: nil, timed_out: false}
+    end
+
+    # Spawn a command without capturing output.  Blocks until the
+    # process exits or the timeout is reached, then returns.
+    #
+    # @param cmd     [String]  shell command to execute
+    # @param timeout [Integer] seconds before SIGTERM (default 10)
+    # @param env     [Hash]    environment variables (default {})
+    # @return [Hash] { status: Process::Status|nil, timed_out: Boolean }
+    def self.spawn(cmd, timeout: 10, env: {})
+      pid = Process.spawn(env, cmd, %i[out err] => File::NULL)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+
+      loop do
+        _pid, status = Process.waitpid2(pid, Process::WNOHANG)
+        return {status:, timed_out: false} if status
+
+        if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+          Process.kill("TERM", pid)
+          _, status = Process.waitpid2(pid)
+          return {status:, timed_out: true}
+        end
+
+        sleep 0.1
+      end
+    rescue Errno::ENOENT => e
+      raise e # let caller handle command-not-found
+    rescue Errno::ESRCH, Errno::ECHILD
+      {status: nil, timed_out: false}
+    end
+  end
+end