prdigest 0.1.1 → 0.2.0

data/SECURITY.md

@@ -12,10 +12,43 @@ Telegram bot whose `chat_id` is the only delivery target in the allowlist. Rotat
 either token immediately if it may have appeared in output, then inspect and
 restrict journal retention.
 
+Standalone prose uses the environment variable named by
+`prose.api_key_env`. Never place the provider key itself in YAML, shell history,
+arguments, checkpoints, fixtures, or logs. Remote provider URLs must use HTTPS;
+plaintext HTTP is accepted only for exact `localhost`, IPv4 `127.0.0.0/8`, or
+IPv6 `::1` loopback hosts. PRDigest rejects provider URLs with embedded
+credentials, query strings, or fragments and does not include provider response
+bodies in errors. Generated prose containing C0/C1 terminal controls is rejected
+before stdout, checkpoints, or Telegram; tabs and newlines remain allowed.
+
 Private pull-request titles and author names cross from GitHub into the configured
 Telegram chat. Treat that chat and its members as having access to repository
 metadata. PRDigest refuses non-allowlisted chat IDs before opening a connection.
 
+`prdigest facts` writes repository names, titles, authors, URLs, merge times, and
+optional statistics to stdout. The caller owns that output after the single JSON
+document is emitted; avoid terminal capture, shell tracing, and logs that are
+broader than the repository's audience.
+
+OpenClaw mode sends that facts document into the configured OpenClaw execution
+and model boundary so OpenClaw can write prose. Standalone `prdigest prose`
+sends the same complete document plus the configured model name to the
+OpenAI-compatible endpoint. Private repositories therefore require an OpenClaw
+deployment or provider whose data handling, retention, and access controls are
+acceptable to the operator. Neither mode is ambient: `prdigest run` and
+`prdigest facts` never contact the standalone prose provider.
+
+Pull-request fields are untrusted input. The built-in provider prompt and the
+OpenClaw skill explicitly classify the facts JSON as data, never instructions,
+but operators should still restrict tools and authority available to any model
+processing private repository content. The OpenClaw skill must not make a second
+GitHub query, deliver messages, install software silently, or print credentials.
+
+Prose Telegram checkpoints contain generated text derived from repository facts.
+They use the same secret-free mode-`0600` files and mode-`0700` directories as
+deterministic delivery, under a separate `prose` namespace. Protect, retain, and
+delete them as private repository metadata.
+
 ## Reporting
 
 Report vulnerabilities privately to the maintainer address in the gem metadata.
@@ -25,4 +58,6 @@ state files, or unredacted journal output.
 ## Supported release
 
 Security fixes target the latest published release. The build and test process
-does not tag or publish releases automatically.
+does not tag or publish releases automatically. The exact-tag release workflow
+uses a RubyGems trusted publisher and a short-lived GitHub OIDC credential; no
+long-lived RubyGems API key is stored in the repository or Actions secrets.

data/configs/config.example.yml

@@ -26,6 +26,15 @@ digest:
   send_empty: true
   empty_message: "Merged PR digest — {date}\nTotal: 0 PRs"
 
+prose:
+  # Used only by `prdigest prose`; `run` and `facts` never contact 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.

data/lib/prdigest/cli.rb

@@ -12,6 +12,12 @@ module Prdigest
     def run_cmd; end
     map "run" => :run_cmd
 
+    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
 
@@ -20,20 +26,27 @@ module Prdigest
 
     class << self
       def invoke(argv = ARGV, out: $stdout, err: $stderr, env: ENV,
-                 system_path: "/etc/prdigest/config.yml", runner_factory: nil)
+                 system_path: "/etc/prdigest/config.yml", runner_factory: nil,
+                 facts_runner_factory: nil, prose_runner_factory: nil)
         json_intent = Array(argv).any? { |arg| arg == "--json" || arg.start_with?("--json=") }
+        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])
+        unless %w[facts prose run serve].include?(parsed[:command])
           raise ParseError, "unknown command"
         end
 
         path = Config.resolve_path(explicit: parsed[:config], env: env, system_path: system_path)
-        config = Config.load(path)
+        capability = config_capability(parsed)
+        config = Config.load(path, capability: capability)
         if parsed[:command] == "serve"
-          err.puts "prdigest serve: deferred in v0.1.x — use systemd timer + `prdigest run`"
+          err.puts "prdigest serve: not implemented — use systemd timer + `prdigest run`"
           return 0
         end
 
@@ -43,6 +56,42 @@ module Prdigest
                        else
                          Config.normalize_repos(parsed[:repos], label: "--repo")
                        end
+        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
+
+        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
+
         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"
@@ -59,14 +108,31 @@ module Prdigest
         present(result, json: parsed[:json], out: out, err: err)
         result.exit_code
       rescue ParseError => e
+        return present_facts_failure(out, "cli", e.message) if facts_intent
+        return present_prose_failure(err, "cli", e.message) if prose_intent
+
         result = Result.failure(mode: "scheduled", error_kind: "cli", message: e.message)
         present(result, json: json_intent, out: out, err: err)
         result.exit_code
       rescue ConfigError => e
+        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
+
         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
       rescue StandardError => e
+        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
+
         result = Result.failure(
           mode: parsed && parsed[:date] ? "explicit_date_replay" : "scheduled",
           error_kind: "internal",
@@ -84,8 +150,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 +186,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,6 +223,76 @@ module Prdigest
         raise ConfigError, "date must use YYYY-MM-DD"
       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
+        else :run
+        end
+      end
+
+      def present_facts_failure(out, error_kind, message)
+        out.puts JSON.generate(Facts.failure(error_kind: error_kind, message: message))
+        Result::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
+          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}"
+        Result::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 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 present(result, json:, out:, err:)
         if json
           out.puts JSON.generate(result.to_h)
@@ -161,6 +323,8 @@ module Prdigest
 
       def print_help(out)
         out.puts "Usage: prdigest run [--config PATH] [--date YYYY-MM-DD] [--repo owner/name] [--dry-run] [--json]"
+        out.puts "       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 serve | version"
         0
       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: :run)
       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
@@ -115,7 +169,12 @@ module Prdigest
       raise ConfigError, "schedule.max_catchup_days must be an integer from 1 to 30"
     end
 
-    def validate!
+    def validate!(capability: :run)
+      capability = capability.to_sym
+      unless %i[facts run prose prose_delivery].include?(capability)
+        raise ArgumentError, "unknown configuration capability: #{capability}"
+      end
+
       begin
         TZInfo::Timezone.get(timezone)
       rescue TZInfo::InvalidTimezoneIdentifier
@@ -125,12 +184,45 @@ module Prdigest
         raise ConfigError, "schedule.max_catchup_days must be from 1 to 30"
       end
       repos
+      return self if capability == :facts
+
+      validate_prose! if %i[prose prose_delivery].include?(capability)
+      return self if capability == :prose
+
+      validate_telegram!
+      self
+    end
+
+    private
+
+    def prose_config
+      section = raw["prose"]
+      section.is_a?(Hash) ? section : {}
+    end
+
+    def validate_prose!
+      unless raw["prose"].is_a?(Hash)
+        raise ConfigError, "prose must be a mapping"
+      end
+      if prose_config.key?("api_key")
+        raise ConfigError, "prose API key must be supplied through an environment variable"
+      end
+      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,

data/lib/prdigest/facts.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Prdigest
+  class Facts
+    SCHEMA = "prdigest-facts"
+    SCHEMA_VERSION = 1
+
+    def initialize(digest:, timezone:)
+      @digest = digest
+      @timezone = timezone.to_s.freeze
+    end
+
+    def self.failure(error_kind:, message:)
+      {
+        schema: SCHEMA,
+        schema_version: SCHEMA_VERSION,
+        status: "failure",
+        error: {
+          kind: error_kind.to_s,
+          message: message.to_s
+        },
+        digest: nil
+      }
+    end
+
+    def to_h
+      {
+        schema: SCHEMA,
+        schema_version: SCHEMA_VERSION,
+        status: "success",
+        error: nil,
+        digest: serialize_digest
+      }
+    end
+
+    private
+
+    def serialize_digest
+      {
+        date: @digest.date.iso8601,
+        timezone: @timezone,
+        line_stats: @digest.line_stats,
+        repository_order: @digest.repositories.map(&:name),
+        repositories: @digest.repositories.map { |repository| serialize_repository(repository) },
+        totals: {
+          pull_requests: @digest.total_prs,
+          additions: @digest.total_additions,
+          deletions: @digest.total_deletions,
+          commits: @digest.total_commits
+        }
+      }
+    end
+
+    def serialize_repository(repository)
+      {
+        name: repository.name,
+        pull_requests: repository.pull_requests.map { |pull| serialize_pull(pull) }
+      }
+    end
+
+    def serialize_pull(pull)
+      {
+        number: pull.number,
+        title: pull.title,
+        url: pull.url,
+        author: pull.author,
+        merged_at: pull.merged_at.utc.iso8601,
+        additions: pull.additions,
+        deletions: pull.deletions,
+        commits: pull.commits
+      }
+    end
+  end
+end

data/lib/prdigest/facts_runner.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Prdigest
+  class FactsRunner
+    def initialize(config:, date: nil, repositories: nil, env: ENV, clock: nil, github: nil)
+      @config = config
+      @date = date && Date.iso8601(date.to_s)
+      @repositories = repositories || config.repos
+      @clock = clock || Clock.new(timezone: config.timezone)
+      @github = github || GitHub.new(token: config.github_token(env))
+    end
+
+    def call
+      date = @date || @clock.yesterday
+      digest = Collector.new(
+        clock: @clock,
+        github: @github,
+        repositories: @repositories,
+        line_stats: @config.line_stats?
+      ).call(date: date)
+      Facts.new(digest: digest, timezone: @config.timezone).to_h
+    end
+
+    def inspect
+      "#<#{self.class} date=#{@date || "yesterday"} credentials=[REDACTED]>"
+    end
+
+    alias to_s inspect
+  end
+end