earl-bot 0.1.0

data/lib/earl/config.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Earl
+  # Holds and validates environment-based configuration for Mattermost
+  # connectivity, bot credentials, and channel targeting.
+  class Config
+    # Groups Mattermost server URL and bot authentication credentials.
+    MattermostCredentials = Struct.new(:url, :bot_token, :bot_id, keyword_init: true)
+
+    attr_reader :credentials, :channel_id, :allowed_users, :skip_permissions
+
+    alias skip_permissions? skip_permissions
+
+    def initialize
+      @credentials = build_credentials
+      @channel_id = required_env("EARL_CHANNEL_ID")
+      @allowed_users = ENV.fetch("EARL_ALLOWED_USERS", "").split(",").map(&:strip)
+      @skip_permissions = ENV.fetch("EARL_SKIP_PERMISSIONS", "false").downcase == "true"
+    end
+
+    def mattermost_url
+      credentials.url
+    end
+
+    def bot_token
+      credentials.bot_token
+    end
+
+    def bot_id
+      credentials.bot_id
+    end
+
+    def websocket_url
+      "#{mattermost_url.sub(%r{^https://}, "wss://").sub(%r{^http://}, "ws://")}/api/v4/websocket"
+    end
+
+    def api_url(path)
+      "#{mattermost_url}/api/v4#{path}"
+    end
+
+    def channels
+      @channels ||= parse_channels
+    end
+
+    # Builds the env hash for the MCP permission server.
+    # Returns nil when permissions are globally skipped.
+    def permission_env(channel_id:, thread_id: "")
+      return nil if skip_permissions?
+
+      url, token, bot_id = credentials.to_h.values_at(:url, :bot_token, :bot_id)
+      {
+        "PLATFORM_URL" => url, "PLATFORM_TOKEN" => token,
+        "PLATFORM_CHANNEL_ID" => channel_id, "PLATFORM_THREAD_ID" => thread_id,
+        "PLATFORM_BOT_ID" => bot_id, "ALLOWED_USERS" => allowed_users.join(",")
+      }
+    end
+
+    private
+
+    def parse_channels
+      default_dir = Dir.pwd
+      return { channel_id => default_dir } unless ENV.key?("EARL_CHANNELS")
+
+      entries = ENV.fetch("EARL_CHANNELS").split(",")
+      return { channel_id => default_dir } if entries.empty?
+
+      entries.each_with_object({}) do |entry, hash|
+        channel, path = entry.strip.split(":", 2)
+        hash[channel] = path || default_dir
+      end
+    end
+
+    def build_credentials
+      url = required_env("MATTERMOST_URL")
+      validate_url(url)
+      MattermostCredentials.new(
+        url: url,
+        bot_token: required_env("MATTERMOST_BOT_TOKEN"),
+        bot_id: required_env("MATTERMOST_BOT_ID")
+      )
+    end
+
+    def required_env(key)
+      ENV.fetch(key) { raise "Missing required env var: #{key}" }
+    end
+
+    def validate_url(url)
+      uri = URI.parse(url)
+      raise "MATTERMOST_URL must be an HTTP(S) URL, got: #{url}" unless uri.is_a?(URI::HTTP)
+    rescue URI::InvalidURIError
+      raise "MATTERMOST_URL is not a valid URL: #{url}"
+    end
+  end
+end

data/lib/earl/cron_parser.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Earl
+  # Minimal 5-field cron expression parser (minute hour dom month dow).
+  # Supports: *, specific values, ranges (1-5), steps (*/15), lists (1,3,5).
+  class CronParser
+    MAX_SCAN_DAYS = 366
+
+    def initialize(expression)
+      @fields = parse_expression(expression)
+    end
+
+    def matches?(time)
+      matches_values?(extract_time_values(time))
+    end
+
+    def next_occurrence(from: Time.now)
+      # Start scanning from the next whole minute
+      candidate = beginning_of_next_minute(from)
+      limit = from + (MAX_SCAN_DAYS * 86_400)
+
+      while candidate <= limit
+        return candidate if matches?(candidate)
+
+        candidate += 60
+      end
+
+      nil
+    end
+
+    private
+
+    def extract_time_values(time)
+      [time.min, time.hour, time.day, time.month, time.wday]
+    end
+
+    def matches_values?(values)
+      @fields.zip(values).all? { |allowed, value| allowed.include?(value) }
+    end
+
+    def beginning_of_next_minute(time)
+      Time.new(time.year, time.month, time.day, time.hour, time.min, 0) + 60
+    end
+
+    def parse_expression(expression)
+      fields = expression.strip.split(/\s+/)
+      count = fields.size
+      raise ArgumentError, "Invalid cron expression: expected 5 fields, got #{count}" unless count == 5
+
+      fields.zip(FIELD_RANGES).map { |field, range| parse_field(field, range) }
+    end
+
+    FIELD_RANGES = [0..59, 0..23, 1..31, 1..12, 0..6].freeze
+    private_constant :FIELD_RANGES
+
+    def parse_field(field, range)
+      values = field.split(",").flat_map { |token| PartParser.new(token.strip, range).parse }
+      values.select { |val| range.include?(val) }.uniq.sort
+    end
+
+    # Parses a single cron field part (e.g. "*/15", "1-5", "3").
+    # Encapsulates the part string and valid range as instance state
+    # so parsing methods can reference them without parameter passing.
+    class PartParser
+      def initialize(part, range)
+        @part = part
+        @range = range
+      end
+
+      def parse
+        return @range.to_a if @part == "*"
+        return [@part.to_i] if @part.match?(/\A\d+\z/)
+        return parse_wildcard_step if @part.start_with?("*/")
+        return parse_range_step if @part.include?("/")
+        return parse_range if @part.include?("-")
+
+        raise ArgumentError, "Invalid cron field: #{@part}"
+      end
+
+      private
+
+      def parse_wildcard_step
+        step = @part.delete_prefix("*/").to_i
+        validated_step(@range, step)
+      end
+
+      def parse_range
+        left, right = @part.split("-", 2)
+        (left.to_i..right.to_i).to_a
+      end
+
+      def parse_range_step
+        range_str, step_str = @part.split("/", 2)
+        left, right = range_str.split("-", 2)
+        validated_step(left.to_i..right.to_i, step_str.to_i)
+      end
+
+      def validated_step(range, step)
+        raise ArgumentError, "Invalid step: #{@part}" if step.zero?
+
+        range.step(step).to_a
+      end
+    end
+  end
+end

data/lib/earl/formatting.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Earl
+  # Shared formatting helpers for numbers and display.
+  module Formatting
+    private
+
+    def format_number(num)
+      return "0" unless num
+
+      num.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+    end
+  end
+end

data/lib/earl/heartbeat_config.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Earl
+  # Loads and validates heartbeat definitions from <config_root>/heartbeats.yml.
+  class HeartbeatConfig
+    include Logging
+
+    def self.config_path
+      @config_path ||= File.join(Earl.config_root, "heartbeats.yml")
+    end
+
+    attr_reader :path
+
+    # A single heartbeat definition with schedule, prompt, and execution options.
+    HeartbeatDefinition = Struct.new(
+      :name, :description, :cron, :interval, :run_at, :channel_id, :working_dir,
+      :prompt, :permission_mode, :persistent, :timeout, :enabled, :once,
+      keyword_init: true
+    ) do
+      def self.from_config(name, config, working_dir_resolver)
+        schedule = config["schedule"] || {}
+        new(
+          name: name, description: config["description"] || name,
+          cron: schedule["cron"], interval: schedule["interval"], run_at: schedule["run_at"],
+          **extract_options(config, working_dir_resolver)
+        )
+      end
+
+      def self.extract_options(config, working_dir_resolver)
+        {
+          channel_id: config["channel_id"],
+          working_dir: working_dir_resolver.call(config["working_dir"]),
+          prompt: config["prompt"],
+          permission_mode: (config["permission_mode"] || "interactive").to_sym,
+          persistent: config.fetch("persistent", false),
+          timeout: config.fetch("timeout", 600),
+          enabled: config.fetch("enabled", true),
+          once: config.fetch("once", false)
+        }
+      end
+
+      def active?
+        enabled && channel_id && prompt
+      end
+
+      def auto_permission?
+        permission_mode == :auto
+      end
+
+      def base_session_opts
+        { working_dir: working_dir, auto_permission: auto_permission?, channel_id: channel_id }
+      end
+    end
+
+    def initialize(path: self.class.config_path)
+      @path = path
+    end
+
+    def definitions
+      load_definitions
+    rescue StandardError => error
+      log(:warn, "Failed to load heartbeat config from #{@path}: #{error.message}")
+      []
+    end
+
+    private
+
+    def load_definitions
+      return [] unless File.exist?(@path)
+
+      data = YAML.safe_load_file(@path)
+      heartbeats = data.is_a?(Hash) ? data["heartbeats"] : nil
+      return [] unless heartbeats.is_a?(Hash)
+
+      heartbeats.filter_map { |name, config| build_definition(name, config) }
+    end
+
+    def build_definition(name, config)
+      return nil unless config.is_a?(Hash)
+      return nil unless valid_schedule?(config)
+
+      definition = HeartbeatDefinition.from_config(name, config, method(:resolve_working_dir))
+      definition if definition.active?
+    end
+
+    def valid_schedule?(config)
+      schedule = config["schedule"]
+      return false unless schedule.is_a?(Hash)
+
+      schedule.key?("cron") || schedule.key?("interval") || schedule.key?("run_at")
+    end
+
+    def resolve_working_dir(path)
+      return nil unless path
+
+      File.expand_path(path)
+    end
+  end
+end

data/lib/earl/heartbeat_scheduler/config_reloading.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Earl
+  class HeartbeatScheduler
+    # Auto-reload: detects config file changes and updates heartbeat definitions.
+    module ConfigReloading
+      private
+
+      def check_for_reload
+        mtime = config_file_mtime
+        return if mtime == @control.config_mtime
+
+        @control.config_mtime = mtime
+        reload_definitions
+      end
+
+      def reload_definitions
+        new_defs = @deps.heartbeat_config.definitions
+        now = Time.now
+        new_names = new_defs.map(&:name)
+
+        @mutex.synchronize do
+          add_new_definitions(new_defs, now)
+          remove_stale_definitions(new_names)
+          update_existing_definitions(new_defs)
+        end
+
+        log(:info, "Heartbeat config reloaded: #{new_defs.size} definition(s)")
+      end
+
+      def add_new_definitions(new_defs, now)
+        new_defs.each do |definition|
+          def_name = definition.name
+          next if @states.key?(def_name)
+
+          @states[def_name] = build_initial_state(definition, now)
+          log(:info, "Heartbeat reload: added '#{def_name}'")
+        end
+      end
+
+      def remove_stale_definitions(new_names)
+        @states.each_key do |name|
+          next if new_names.include?(name)
+          next if @states[name].running
+
+          @states.delete(name)
+          log(:info, "Heartbeat reload: removed '#{name}'")
+        end
+      end
+
+      def update_existing_definitions(new_defs)
+        new_defs.each do |definition|
+          @states[definition.name]&.update_definition_if_idle(definition)
+        end
+      end
+
+      def config_file_mtime
+        File.mtime(@control.heartbeat_config_path)
+      rescue Errno::ENOENT
+        nil
+      end
+    end
+  end
+end

data/lib/earl/heartbeat_scheduler/execution.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Earl
+  class HeartbeatScheduler
+    # Heartbeat execution: creates sessions, streams responses, handles completion.
+    module Execution
+      private
+
+      def execute_heartbeat(state)
+        definition = state.definition
+        def_name = definition.name
+        log(:info, "Heartbeat '#{def_name}' starting")
+        thread_id = post_heartbeat_header(definition.channel_id, definition.description)
+        return unless thread_id
+
+        run_heartbeat_session(definition, state, thread_id)
+      rescue StandardError => error
+        handle_heartbeat_error(state, def_name, error)
+      ensure
+        finalize_heartbeat(state)
+      end
+
+      def handle_heartbeat_error(state, name, error)
+        error_msg = error.message
+        log(:error, "Heartbeat '#{name}' error: #{error_msg}")
+        log(:error, error.backtrace&.first(5)&.join("\n"))
+        @mutex.synchronize { state.last_error = error_msg }
+      end
+
+      def post_heartbeat_header(channel_id, description)
+        post = @deps.mattermost.create_post(channel_id: channel_id, message: "\u{1FAC0} **#{description}**")
+        post&.dig("id")
+      end
+
+      def run_heartbeat_session(definition, state, thread_id)
+        session = build_heartbeat_session(definition, state)
+        completed = false
+        response = build_heartbeat_response(thread_id, definition.channel_id)
+        setup_heartbeat_callbacks(session, response) { completed = true }
+        session.start
+        session.send_message(definition.prompt)
+        await_heartbeat_completion(session, definition.timeout) { completed }
+        log(:info, "Heartbeat '#{definition.name}' completed (run ##{state.run_count + 1})")
+      end
+
+      def build_heartbeat_response(thread_id, channel_id)
+        response = StreamingResponse.new(thread_id: thread_id, mattermost: @deps.mattermost, channel_id: channel_id)
+        response.start_typing
+        response
+      end
+
+      def build_heartbeat_session(definition, state)
+        session_opts = heartbeat_session_opts(definition)
+        persistent = definition.persistent
+        apply_resume_opts(session_opts, state) if persistent
+        session = ClaudeSession.new(**session_opts)
+        @mutex.synchronize { state.session_id = session.session_id } if persistent
+        session
+      end
+
+      def heartbeat_session_opts(definition)
+        auto, channel_id, working_dir = definition.base_session_opts.values_at(:auto_permission, :channel_id,
+                                                                               :working_dir)
+        { working_dir: working_dir, permission_config: auto ? nil : heartbeat_permission_env(channel_id) }
+      end
+
+      def apply_resume_opts(opts, state)
+        saved_session_id = state.session_id
+        return unless saved_session_id
+
+        opts[:session_id] = saved_session_id
+        opts[:mode] = :resume
+      end
+
+      def heartbeat_permission_env(channel_id)
+        @deps.config.permission_env(channel_id: channel_id)
+      end
+
+      def setup_heartbeat_callbacks(session, response)
+        session.on_text { |text| response.on_text(text) }
+        session.on_complete do |_|
+          response.on_complete
+          yield
+        end
+        session.on_tool_use { |tool_use| response.on_tool_use(tool_use) }
+      end
+
+      def await_heartbeat_completion(session, timeout)
+        start_time = monotonic_now
+        until yield
+          if monotonic_now - start_time >= timeout
+            log(:warn, "Heartbeat timed out after #{timeout}s")
+            session.kill
+            return
+          end
+          sleep 1
+        end
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/earl/heartbeat_scheduler/heartbeat_state.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Earl
+  class HeartbeatScheduler
+    # Per-heartbeat runtime state.
+    HeartbeatState = Struct.new(
+      :definition, :next_run_at, :running, :run_thread, :last_run_at,
+      :last_completed_at, :last_error, :run_count, :session_id,
+      keyword_init: true
+    ) do
+      def to_status
+        {
+          name: definition.name, description: definition.description,
+          next_run_at: next_run_at, last_run_at: last_run_at,
+          last_completed_at: last_completed_at, last_error: last_error,
+          run_count: run_count, running: running
+        }
+      end
+
+      def update_definition_if_idle(new_definition)
+        return if running
+
+        self.definition = new_definition
+      end
+
+      def dispatch(now, &block)
+        self.running = true
+        self.last_run_at = now
+        self.run_thread = Thread.new(&block)
+      end
+
+      def mark_completed(next_run)
+        self.running = false
+        self.last_completed_at = Time.now
+        self.run_count += 1
+        self.run_thread = nil
+        self.next_run_at = next_run
+      end
+    end
+  end
+end

data/lib/earl/heartbeat_scheduler/lifecycle.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Earl
+  class HeartbeatScheduler
+    # Heartbeat lifecycle: finalization, next-run computation, and one-shot disabling.
+    module Lifecycle
+      private
+
+      def finalize_heartbeat(state)
+        definition = state.definition
+        is_once = definition.once
+        next_run = is_once ? nil : compute_next_run(definition, Time.now)
+        @mutex.synchronize { state.mark_completed(next_run) }
+        disable_heartbeat(definition.name) if is_once
+      end
+
+      def compute_next_run(definition, from)
+        schedule = definition.to_h.values_at(:run_at, :cron, :interval)
+        compute_from_schedule(schedule, from)
+      end
+
+      def compute_from_schedule(schedule, from)
+        run_at, cron, interval = schedule
+        if run_at
+          compute_run_at(run_at, from)
+        elsif cron
+          CronParser.new(cron).next_occurrence(from: from)
+        elsif interval
+          from + interval
+        end
+      end
+
+      def compute_run_at(run_at, from)
+        target = Time.at(run_at)
+        [target, from].max
+      end
+
+      def disable_heartbeat(name)
+        path = @control.heartbeat_config_path
+        return unless File.exist?(path)
+
+        update_yaml_entry(path, name)
+      rescue StandardError => error
+        log(:warn, "Failed to disable heartbeat '#{name}': #{error.message}")
+      end
+
+      def update_yaml_entry(path, name)
+        File.open(path, "r+") do |lockfile|
+          lockfile.flock(File::LOCK_EX)
+          yaml_data = YAML.safe_load_file(path)
+          next unless disable_entry(yaml_data, name)
+
+          write_yaml_atomically(path, yaml_data)
+          log(:info, "One-off heartbeat '#{name}' disabled in YAML")
+        end
+      end
+
+      def disable_entry(yaml_data, name)
+        return false unless yaml_data.is_a?(Hash)
+
+        entry = yaml_data.dig("heartbeats", name)
+        return false unless entry.is_a?(Hash)
+
+        entry["enabled"] = false
+        true
+      end
+
+      def write_yaml_atomically(path, data)
+        tmp_path = "#{path}.tmp.#{Process.pid}"
+        File.write(tmp_path, YAML.dump(data))
+        File.rename(tmp_path, path)
+      end
+    end
+  end
+end