prdigest 0.1.1 → 0.3.0

data/configs/config.example.yml

@@ -1,12 +1,6 @@
-# prdigest — multi-repo merged-PR daily digest (Hive-independent)
+# prdigest — merged-PR facts for agents and provider-written prose
 
 timezone: Europe/London
-schedule:
-  # Prefer systemd timer + `prdigest run` for v1.
-  # serve mode may honor this later.
-  cron: "5 9 * * *"
-  # Newest retained catch-up window; valid range is 1..30.
-  max_catchup_days: 7
 
 github:
   token_env: GITHUB_TOKEN
@@ -23,10 +17,16 @@ telegram:
 
 digest:
   line_stats: true
-  send_empty: true
-  empty_message: "Merged PR digest — {date}\nTotal: 0 PRs"
+
+prose:
+  # Used only by `prdigest prose`; `facts` never contacts this endpoint.
+  provider: openai_compatible
+  base_url: https://openrouter.ai/api/v1
+  # Replace with a model identifier accepted by the configured endpoint.
+  model: provider/model
+  # The key value belongs in the environment, never this file.
+  api_key_env: OPENROUTER_API_KEY
 
 state:
-  path: /var/lib/prdigest/state.json
-  # Stable rendered chunks and next-unsent position, separate from the date cursor.
+  # Stable prose chunks and the next-unsent position.
   delivery_path: /var/lib/prdigest/deliveries

data/lib/prdigest/cli.rb

@@ -8,34 +8,43 @@ module Prdigest
   class CLI < Thor
     class ParseError < StandardError; end
 
-    desc "run", "Build and send (or dry-run) a merged-PR digest for one local day"
-    def run_cmd; end
-    map "run" => :run_cmd
+    EXIT_CODES = {
+      "config" => 2, "cli" => 2, "refusal" => 2,
+      "github" => 3,
+      "telegram" => 4, "telegram_refused" => 4, "telegram_permanent" => 4,
+      "telegram_ambiguous" => 4, "delivery_checkpoint" => 4,
+      "delivery_checkpoint_permanent" => 4,
+      "state" => 5,
+      "provider" => 7, "provider_ambiguous" => 7
+    }.freeze
+
+    desc "facts", "Print deterministic merged-PR facts as JSON"
+    def facts; end
+
+    desc "prose", "Generate an optional AI-written merged-PR digest"
+    def prose; end
 
     desc "version", "Print version"
     def version; end
 
-    desc "serve", "Compatibility stub; use the systemd timer"
-    def serve; end
-
     class << self
       def invoke(argv = ARGV, out: $stdout, err: $stderr, env: ENV,
-                 system_path: "/etc/prdigest/config.yml", runner_factory: nil)
-        json_intent = Array(argv).any? { |arg| arg == "--json" || arg.start_with?("--json=") }
+                 system_path: "/etc/prdigest/config.yml", facts_runner_factory: nil,
+                 prose_runner_factory: nil)
+        intent = command_intent(argv)
+        facts_intent = intent == "facts"
+        prose_intent = intent == "prose"
         parsed = parse(argv)
+        validate_command_options!(parsed, intent: intent)
         return print_version(out) if parsed[:command] == "version"
+        raise ParseError, "--help is not valid for facts" if facts_intent && parsed[:command] == "help"
         return print_help(out) if %w[help --help -h].include?(parsed[:command])
 
-        unless %w[run serve].include?(parsed[:command])
-          raise ParseError, "unknown command"
-        end
+        raise ParseError, "unknown command" unless %w[facts prose].include?(parsed[:command])
 
         path = Config.resolve_path(explicit: parsed[:config], env: env, system_path: system_path)
-        config = Config.load(path)
-        if parsed[:command] == "serve"
-          err.puts "prdigest serve: deferred in v0.1.x — use systemd timer + `prdigest run`"
-          return 0
-        end
+        capability = config_capability(parsed)
+        config = Config.load(path, capability: capability)
 
         validate_date!(parsed[:date]) if parsed[:date]
         repositories = if parsed[:repos].empty?
@@ -43,37 +52,64 @@ module Prdigest
                        else
                          Config.normalize_repos(parsed[:repos], label: "--repo")
                        end
-        raise ConfigError, "GitHub token is missing" if config.github_token(env).empty?
-        if !parsed[:dry_run] && config.telegram_token(env).empty?
-          raise ConfigError, "Telegram bot token is missing"
+        if parsed[:command] == "facts"
+          raise ConfigError, "GitHub token is missing" if config.github_token(env).empty?
+
+          factory = facts_runner_factory || ->(**options) { FactsRunner.new(**options) }
+          document = factory.call(
+            config: config,
+            date: parsed[:date],
+            repositories: repositories,
+            env: env
+          ).call
+          out.puts JSON.generate(document)
+          return 0
         end
 
-        factory = runner_factory || ->(**options) { Runner.new(**options) }
-        result = factory.call(
-          config: config,
-          date: parsed[:date],
-          dry_run: parsed[:dry_run],
-          repositories: repositories,
-          env: env
-        ).call
-        present(result, json: parsed[:json], out: out, err: err)
-        result.exit_code
+        if parsed[:command] == "prose"
+          if parsed[:deliver]
+            raise ConfigError, "Telegram bot token is missing" if config.telegram_token(env).empty?
+          else
+            raise ConfigError, "GitHub token is missing" if config.github_token(env).empty?
+            if config.prose_api_key(env).empty?
+              raise ConfigError, "prose API key environment variable is unset"
+            end
+          end
+
+          factory = prose_runner_factory || ->(**options) { ProseRunner.new(**options) }
+          outcome = factory.call(
+            config: config,
+            date: parsed[:date],
+            deliver: parsed[:deliver],
+            repositories: repositories,
+            env: env
+          ).call
+          present_prose(outcome, out: out)
+          return 0
+        end
       rescue ParseError => e
-        result = Result.failure(mode: "scheduled", error_kind: "cli", message: e.message)
-        present(result, json: json_intent, out: out, err: err)
-        result.exit_code
+        return present_facts_failure(out, "cli", e.message) if facts_intent
+        return present_prose_failure(err, "cli", e.message) if prose_intent
+
+        present_cli_failure(err, "cli", e.message)
       rescue ConfigError => e
-        result = Result.failure(mode: parsed && parsed[:date] ? "explicit_date_replay" : "scheduled", error_kind: "config", message: e.message)
-        present(result, json: parsed ? parsed[:json] : json_intent, out: out, err: err)
-        result.exit_code
+        return present_facts_failure(out, "config", e.message) if facts_intent
+        return present_prose_failure(err, "config", safe_prose_message(e, config: config, env: env)) if prose_intent
+
+        present_cli_failure(err, "config", e.message)
       rescue StandardError => e
-        result = Result.failure(
-          mode: parsed && parsed[:date] ? "explicit_date_replay" : "scheduled",
-          error_kind: "internal",
-          message: "unexpected CLI failure (#{e.class})"
-        )
-        present(result, json: parsed ? parsed[:json] : json_intent, out: out, err: err)
-        result.exit_code
+        if facts_intent
+          kind = e.is_a?(FetchError) ? e.kind : "internal"
+          message = e.is_a?(FetchError) ? e.message : "unexpected facts failure (#{e.class})"
+          return present_facts_failure(out, kind, message)
+        end
+        if prose_intent
+          kind = prose_error_kind(e)
+          message = safe_prose_message(e, config: config, env: env)
+          return present_prose_failure(err, kind, message)
+        end
+
+        present_cli_failure(err, "internal", "unexpected CLI failure (#{e.class})")
       end
 
       alias start invoke
@@ -84,8 +120,32 @@ module Prdigest
 
       private
 
+      def command_intent(argv)
+        args = Array(argv).dup
+        until args.empty?
+          argument = args.shift
+          case argument
+          when "--config", "--date", "--repo"
+            args.shift
+          when /\A--/
+            next
+          else
+            return argument
+          end
+        end
+        nil
+      end
+
       def parse(argv)
-        parsed = { command: nil, config: nil, date: nil, dry_run: false, json: false, repos: [] }
+        parsed = {
+          command: nil,
+          config: nil,
+          date: nil,
+          dry_run: false,
+          json: false,
+          deliver: false,
+          repos: []
+        }
         args = Array(argv).dup
         until args.empty?
           argument = args.shift
@@ -96,6 +156,8 @@ module Prdigest
             parsed[:dry_run] = true
           when "--json"
             parsed[:json] = true
+          when "--deliver"
+            parsed[:deliver] = true
           when "--config", "--date", "--repo"
             value = args.shift
             raise ParseError, "missing value for #{argument}" if value.nil? || value.start_with?("--")
@@ -131,27 +193,78 @@ module Prdigest
         raise ConfigError, "date must use YYYY-MM-DD"
       end
 
-      def present(result, json:, out:, err:)
-        if json
-          out.puts JSON.generate(result.to_h)
-        elsif result.exit_code.zero?
-          if result.status == "dry_run"
-            out.puts result.chunks.join("\n\n")
-          else
-            out.puts "prdigest: success; settled=#{result.settled_days.length} skipped=#{result.skipped_days.length}"
-          end
+      def validate_command_options!(parsed, intent:)
+        command = intent || parsed.fetch(:command)
+        if parsed[:deliver] && command != "prose"
+          raise ParseError, "--deliver is only valid for prose"
+        end
+
+        if command == "facts"
+          raise ParseError, "--dry-run is not valid for facts" if parsed[:dry_run]
+          raise ParseError, "--json is not valid for facts; output is always JSON" if parsed[:json]
+        elsif command == "prose"
+          raise ParseError, "--dry-run is not valid for prose" if parsed[:dry_run]
+          raise ParseError, "--json is not valid for prose" if parsed[:json]
+        end
+      end
+
+      def config_capability(parsed)
+        case parsed.fetch(:command)
+        when "facts" then :facts
+        when "prose" then parsed[:deliver] ? :prose_delivery : :prose
+        end
+      end
+
+      def present_facts_failure(out, error_kind, message)
+        out.puts JSON.generate(Facts.failure(error_kind: error_kind, message: message))
+        EXIT_CODES.fetch(error_kind.to_s, 1)
+      end
+
+      def present_prose(outcome, out:)
+        if outcome.delivered?
+          delivery = outcome.delivery
+          out.puts(
+            "prdigest: prose delivered; date=#{outcome.date} " \
+            "chunks=#{delivery.fetch(:total_chunks)}"
+          )
         else
-          if result.status == "partial_failure"
-            err.puts "prdigest: progress; settled=#{human_dates(result.settled_days)} " \
-                     "skipped=#{human_dates(result.skipped_days)} remaining=#{human_dates(result.remaining_days)}"
-          end
-          err.puts "prdigest: #{result.error[:kind]}: #{result.error[:message]}"
+          out.write("#{outcome.prose.to_s.sub(/(?:\r?\n)*\z/, "")}\n")
+        end
+      end
+
+      def present_prose_failure(err, error_kind, message)
+        err.puts "prdigest: #{error_kind}: #{message}"
+        EXIT_CODES.fetch(error_kind.to_s, 1)
+      end
+
+      def present_cli_failure(err, error_kind, message)
+        err.puts "prdigest: #{error_kind}: #{message}"
+        EXIT_CODES.fetch(error_kind.to_s, 1)
+      end
+
+      def prose_error_kind(error)
+        case error
+        when FetchError then error.kind
+        when SendError then error.kind
+        when StateError then "state"
+        when GenerationError then error.kind
+        when RenderError then error.kind
+        else "internal"
         end
       end
 
-      def human_dates(dates)
-        values = Array(dates)
-        values.empty? ? "none" : values.join(",")
+      def safe_prose_message(error, config:, env:)
+        message = error.is_a?(Error) ? error.message : "unexpected prose failure (#{error.class})"
+        return message unless config
+
+        secrets = [
+          config.github_token(env),
+          config.telegram_token(env),
+          config.prose_api_key(env)
+        ]
+        secrets.reject(&:empty?).reduce(message.dup) do |safe, secret|
+          safe.gsub(secret, "[REDACTED]")
+        end
       end
 
       def print_version(out)
@@ -160,8 +273,9 @@ module Prdigest
       end
 
       def print_help(out)
-        out.puts "Usage: prdigest run [--config PATH] [--date YYYY-MM-DD] [--repo owner/name] [--dry-run] [--json]"
-        out.puts "       prdigest serve | version"
+        out.puts "Usage: prdigest facts [--config PATH] [--date YYYY-MM-DD] [--repo owner/name]"
+        out.puts "       prdigest prose [--config PATH] [--date YYYY-MM-DD] [--repo owner/name] [--deliver]"
+        out.puts "       prdigest version"
         0
       end
     end

data/lib/prdigest/collector.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Prdigest
+  class Collector
+    def initialize(clock:, github:, repositories:, line_stats: false)
+      @clock = clock
+      @github = github
+      @repositories = Array(repositories).map { |repository| repository.to_s.freeze }.freeze
+      @line_stats = line_stats == true
+    end
+
+    def call(date:)
+      date = Date.iso8601(date.to_s)
+      window = @clock.window(date)
+      return empty_digest(date) if window.zero_length?
+
+      @github.fetch(
+        date: date,
+        window: window,
+        repositories: @repositories,
+        line_stats: @line_stats
+      )
+    end
+
+    private
+
+    def empty_digest(date)
+      DayDigest.build(
+        date: date,
+        repository_order: @repositories,
+        pulls: [],
+        line_stats: @line_stats
+      )
+    end
+  end
+end

data/lib/prdigest/config.rb

@@ -1,14 +1,22 @@
 # frozen_string_literal: true
 
-require "yaml"
+require "ipaddr"
 require "pathname"
 require "tzinfo"
+require "uri"
+require "yaml"
 
 module Prdigest
   class Config
     attr_reader :raw, :path
 
     REPOSITORY_SEGMENT = /\A[A-Za-z0-9_.-]+\z/
+    ENVIRONMENT_VARIABLE = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+    IPV4_LOOPBACK = IPAddr.new("127.0.0.0/8").freeze
+    IPV6_LOOPBACK = IPAddr.new("::1").freeze
+    PROSE_BASE_URL_ERROR =
+      "prose.base_url must be an absolute HTTPS URL (or HTTP loopback URL) " \
+      "without credentials, query, or fragment"
 
     def self.resolve_path(explicit: nil, env: ENV, system_path: "/etc/prdigest/config.yml")
       return File.expand_path(explicit) if explicit && !explicit.to_s.empty?
@@ -20,14 +28,14 @@ module Prdigest
       raise ConfigError, "config path is required (--config, PRDIGEST_CONFIG, or /etc/prdigest/config.yml)"
     end
 
-    def self.load(path)
+    def self.load(path, capability: :facts)
       path = File.expand_path(path)
       raise ConfigError, "config not found: #{path}" unless File.file?(path)
 
       raw = YAML.safe_load_file(path, aliases: true)
       raise ConfigError, "config root must be a mapping" unless raw.is_a?(Hash)
 
-      new(raw, path: path).tap(&:validate!)
+      new(raw, path: path).tap { |config| config.validate!(capability: capability) }
     rescue ConfigError
       raise
     rescue StandardError => e
@@ -50,6 +58,32 @@ module Prdigest
       end.values.freeze
     end
 
+    def self.parse_prose_base_uri(value)
+      uri = URI.parse(value.to_s.strip)
+      valid = %w[http https].include?(uri.scheme) &&
+        !uri.host.to_s.empty? &&
+        uri.userinfo.nil? &&
+        uri.query.nil? &&
+        uri.fragment.nil? &&
+        (uri.scheme == "https" || loopback_host?(uri.host))
+      raise ConfigError, PROSE_BASE_URL_ERROR unless valid
+
+      uri
+    rescue URI::InvalidURIError
+      raise ConfigError, PROSE_BASE_URL_ERROR
+    end
+
+    def self.loopback_host?(host)
+      return true if host.casecmp("localhost").zero?
+
+      address = IPAddr.new(host)
+      (address.ipv4? && IPV4_LOOPBACK.include?(address)) ||
+        (address.ipv6? && address == IPV6_LOOPBACK)
+    rescue IPAddr::InvalidAddressError
+      false
+    end
+    private_class_method :loopback_host?
+
     def initialize(raw, path: nil)
       @raw = raw
       @path = path
@@ -73,6 +107,26 @@ module Prdigest
       env[env_name.to_s].to_s
     end
 
+    def prose_provider
+      prose_config["provider"].to_s
+    end
+
+    def prose_base_url
+      prose_config["base_url"].to_s.strip
+    end
+
+    def prose_model
+      prose_config["model"].to_s.strip
+    end
+
+    def prose_api_key_env
+      prose_config["api_key_env"].to_s.strip
+    end
+
+    def prose_api_key(env = ENV)
+      env[prose_api_key_env].to_s
+    end
+
     def chat_id
       Integer(raw.dig("telegram", "chat_id"))
     rescue TypeError, ArgumentError
@@ -89,48 +143,61 @@ module Prdigest
       raw.dig("digest", "line_stats") != false
     end
 
-    def send_empty?
-      raw.dig("digest", "send_empty") != false
+    def delivery_state_path
+      raw.dig("state", "delivery_path") || File.expand_path("~/.local/share/prdigest/deliveries")
     end
 
-    def empty_message
-      raw.dig("digest", "empty_message") || "Merged PR digest — {date}\nTotal: 0 PRs"
-    end
+    def validate!(capability: :facts)
+      capability = capability.to_sym
+      unless %i[facts prose prose_delivery].include?(capability)
+        raise ArgumentError, "unknown configuration capability: #{capability}"
+      end
 
-    def state_path
-      raw.dig("state", "path") || File.expand_path("~/.local/share/prdigest/state.json")
-    end
+      begin
+        TZInfo::Timezone.get(timezone)
+      rescue TZInfo::InvalidTimezoneIdentifier
+        raise ConfigError, "timezone must be a resolvable IANA identifier"
+      end
+      repos
+      return self if capability == :facts
 
-    def delivery_state_path
-      raw.dig("state", "delivery_path") || File.join(File.dirname(state_path), "deliveries")
-    end
+      validate_prose! if %i[prose prose_delivery].include?(capability)
+      return self if capability == :prose
 
-    def schedule_cron
-      raw.dig("schedule", "cron") || "5 9 * * *"
+      validate_telegram!
+      self
     end
 
-    def max_catchup_days
-      Integer(raw.dig("schedule", "max_catchup_days") || 7)
-    rescue TypeError, ArgumentError
-      raise ConfigError, "schedule.max_catchup_days must be an integer from 1 to 30"
+    private
+
+    def prose_config
+      section = raw["prose"]
+      section.is_a?(Hash) ? section : {}
     end
 
-    def validate!
-      begin
-        TZInfo::Timezone.get(timezone)
-      rescue TZInfo::InvalidTimezoneIdentifier
-        raise ConfigError, "timezone must be a resolvable IANA identifier"
+    def validate_prose!
+      unless raw["prose"].is_a?(Hash)
+        raise ConfigError, "prose must be a mapping"
       end
-      unless (1..30).cover?(max_catchup_days)
-        raise ConfigError, "schedule.max_catchup_days must be from 1 to 30"
+      if prose_config.key?("api_key")
+        raise ConfigError, "prose API key must be supplied through an environment variable"
       end
-      repos
+      unless prose_provider == "openai_compatible"
+        raise ConfigError, "prose.provider must be openai_compatible"
+      end
+      self.class.parse_prose_base_uri(prose_base_url)
+      raise ConfigError, "prose.model must not be blank" if prose_model.empty?
+      unless prose_api_key_env.match?(ENVIRONMENT_VARIABLE)
+        raise ConfigError, "prose.api_key_env must name an environment variable"
+      end
+    end
+
+    def validate_telegram!
       raise ConfigError, "telegram.chat_id is required" if chat_id.nil?
       raise ConfigError, "telegram.chat_id_allowlist must not be empty" if chat_id_allowlist.empty?
       unless chat_id_allowlist.include?(chat_id)
         raise ConfigError, "telegram.chat_id must be present in chat_id_allowlist"
       end
-      self
     end
   end
 end

data/lib/prdigest/delivery_checkpoint_store.rb

@@ -102,7 +102,7 @@ module Prdigest
       @root = File.expand_path(root)
     end
 
-    def with_checkpoint(date:, chat_id:, scope:, chunks:)
+    def with_checkpoint(date:, chat_id:, scope:, chunks: nil, chunk_factory: nil)
       normalized_date = Date.iso8601(date.to_s)
       ensure_root!
       path = File.join(@root, "#{normalized_date}.json")
@@ -123,14 +123,15 @@ module Prdigest
           date: normalized_date,
           chat_id: Integer(chat_id),
           scope: Array(scope).map(&:to_s),
-          chunks: Array(chunks).map(&:to_s)
+          chunks: chunks,
+          chunk_factory: chunk_factory
         )
         fail_if_unavailable!(data)
         yield Session.new(path: path, data: data)
       ensure
         lock.flock(File::LOCK_UN)
       end
-    rescue SendError, StateError
+    rescue Error
       raise
     rescue StandardError => e
       raise StateError, "cannot access delivery checkpoint (#{e.class})"
@@ -158,12 +159,13 @@ module Prdigest
       File.chmod(0o700, @root)
     end
 
-    def load_or_create(path, date:, chat_id:, scope:, chunks:)
+    def load_or_create(path, date:, chat_id:, scope:, chunks:, chunk_factory:)
       if File.file?(path)
         data = JSON.parse(File.read(path))
         validate!(data, date: date, chat_id: chat_id, scope: scope)
         data
       else
+        chunks = build_chunks(chunks, chunk_factory)
         data = {
           "schema" => SCHEMA,
           "schema_version" => SCHEMA_VERSION,
@@ -191,6 +193,17 @@ module Prdigest
       )
     end
 
+    def build_chunks(chunks, chunk_factory)
+      both_missing = chunks.nil? && chunk_factory.nil?
+      both_present = !chunks.nil? && !chunk_factory.nil?
+      if both_missing || both_present
+        raise StateError, "delivery checkpoint requires exactly one payload source"
+      end
+
+      source = chunk_factory ? chunk_factory.call : chunks
+      Array(source).map(&:to_s)
+    end
+
     def validate!(data, date:, chat_id:, scope:)
       expected = {
         "schema" => SCHEMA,