prdigest 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 264ab3685453725051fd4801627cc9eaf917bfa44f6ec9eee58d375168576761
+  data.tar.gz: 6fad72d4c5aaf157b7c8f29841efadc9a29ec154c327436904f11fad34332c5c
+SHA512:
+  metadata.gz: cc48ee4723c80380f105d21f4a82541cbcb8ba9ffbe570e4411db6bce718207b4a89674424489578d03fb01f9485d56fa3e57fb618210a74e4893cd8d2dfef24
+  data.tar.gz: bf5501a504c4528ba4391124cc888c7a7ef4034190055aa6df94de8d6a1afa8dc5376720715ae79acd63bac4a33444d948f9cc497d8f06d3f06fb9c648709afa

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0 - 2026-07-16
+
+- Add timezone-correct daily windows, atomic versioned state, and capped catch-up.
+- Fetch complete merged-PR results with deterministic ordering and optional stats.
+- Render safe, bounded Telegram HTML and deliver only to an allowlisted chat.
+- Persist stable rendered chunks and resume at the next definitely-unsent chunk.
+- Park permanent and ambiguous Telegram failures instead of replaying accepted messages.
+- Add repeatable `--repo owner/name` input and a versioned JSON embedding contract.
+- Add scheduled, explicit replay, dry-run, JSON, and stable exit-code contracts.
+- Add non-root container, hardened systemd units, offline tests, and release smokes.
+
+No tag, gem publication, or GitHub release is created by this preparation.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Kuznetsov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,226 @@
+# PRDigest
+
+PRDigest is a deterministic Ruby oneshot that sends a daily digest of merged
+GitHub pull requests to one allowlisted Telegram chat. It is designed for a
+single operator on a small VPS: repositories are explicit, secrets stay in the
+environment, and a hardened systemd timer owns scheduling.
+
+## Requirements and installation
+
+- Ruby 3.2–3.4 and `tzdata`
+- a fine-grained GitHub token with read-only access to the listed repositories
+- a dedicated Telegram bot and one destination chat ID
+
+For development:
+
+```sh
+bundle install
+bundle exec prdigest version
+GITHUB_TOKEN=... bundle exec prdigest run --config configs/config.example.yml --dry-run
+```
+
+To build and install the prepared gem without publishing it:
+
+```sh
+gem build prdigest.gemspec
+gem install prdigest-0.1.0.gem
+prdigest version
+```
+
+## Configuration and secrets
+
+Configuration lookup is strict: an explicit `--config PATH` wins, then
+`PRDIGEST_CONFIG`, then an existing `/etc/prdigest/config.yml`. PRDigest refuses
+to run when none exists. See `configs/config.example.yml` for every setting.
+
+```yaml
+timezone: Europe/London
+schedule:
+  max_catchup_days: 7
+github:
+  token_env: GITHUB_TOKEN
+  repos:
+    - owner/repo-one
+    - owner/repo-two
+telegram:
+  token_env: TELEGRAM_BOT_TOKEN
+  chat_id_allowlist: [-1001234567890]
+  chat_id: -1001234567890
+digest:
+  line_stats: true
+  send_empty: true
+  empty_message: "Merged PR digest — {date}\nTotal: 0 PRs"
+state:
+  path: /var/lib/prdigest/state.json
+  delivery_path: /var/lib/prdigest/deliveries
+```
+
+Repository order controls digest order. `max_catchup_days` must be `1..30`.
+`chat_id` must appear in the non-empty allowlist; extra allowlisted IDs are
+accepted for schema compatibility but v0.1.0 sends only to `chat_id`. Token
+values belong in environment variables, never YAML.
+
+## Commands and results
+
+```sh
+prdigest run [--config PATH] [--date YYYY-MM-DD] [--dry-run] [--json] [--repo OWNER/NAME ...]
+prdigest serve
+prdigest version
+```
+
+An ordinary `run` reads state, processes owed dates oldest-first, and writes
+state after each settled day. `--date` replays exactly that local date and never
+reads or writes state. `--dry-run` previews the explicit date or yesterday,
+requires GitHub access, and constructs neither state nor Telegram delivery.
+`serve` remains a compatibility stub; use the supplied timer.
+Repeatable `--repo` values replace the configured repository list for that run.
+They use the same strict `owner/name` validation and deterministic order as the
+configuration, which lets callers such as Hive supply their registered projects
+without owning a second digest implementation.
+
+`--json` emits a versioned `prdigest-result` document with `status`, `mode`, `requested_days`,
+`settled_days`, `skipped_days`, `failed_date`, `remaining_days`, nullable
+`error`, dry-run `chunks`, and nullable structured `delivery` progress.
+`delivery` reports `accepted_chunks`, `total_chunks`, `status`, and, on failure,
+`failed_chunk`. Modes are `scheduled` and
+`explicit_date_replay`; statuses are `success`, `dry_run`, `failure`, and
+`partial_failure`.
+
+| Exit | Meaning |
+|---:|---|
+| 0 | completed or dry-run |
+| 1 | unexpected or render failure |
+| 2 | CLI/configuration refusal |
+| 3 | GitHub failure |
+| 4 | Telegram failure |
+| 5 | state failure |
+| 6 | failure after earlier durable progress |
+
+## Delivery and state semantics
+
+Each local day is converted to independent UTC midnight boundaries, including
+DST gaps and repeats. GitHub results are completely fetched and rendered before
+the first Telegram message. A day is settled only after every chunk succeeds,
+an enabled empty message succeeds, or an empty message is intentionally
+suppressed.
+
+Before sending, PRDigest stores the complete rendered chunk list in
+`state.delivery_path`. It marks one chunk in flight before each request and
+advances `next_chunk` only after Telegram definitely accepts it. A definite
+429/5xx rejection receives at most three attempts; a later invocation resumes
+the original rendered payload at the next unsent chunk. If the date cursor write
+fails after complete delivery, the retry observes the completed delivery
+checkpoint and sends nothing before repairing the cursor.
+
+Telegram 400/invalid-response failures are permanent. Transport failures are
+ambiguous because Telegram might have accepted the request before the
+connection failed. Both cases remain parked and never replay automatically.
+Inspect the checkpoint and Telegram chat, reconcile the uncertain chunk, then
+move the checkpoint aside only when an intentional operator replay is safe.
+Changing the chat or repository scope for an existing date also fails closed.
+Explicit `--date` uses this same safety ledger, so a completed date is a no-op
+unless its checkpoint is deliberately archived first.
+
+State is secret-free JSON version 1:
+
+```json
+{"version":1,"timezone":"Europe/London","last_digested_date":"2026-07-15"}
+```
+
+It may include a `last_skip` audit with `start_date`, `end_date`, and
+`notice_pending`. Writes use an atomic mode-`0600` replacement and directory
+fsync. Delivery directories are mode `0700`; delivery files and locks are mode
+`0600`, and a per-date lock prevents concurrent sends for the same checkpoint.
+Missing state means first run and requests yesterday only. Malformed,
+future, unsupported, unreadable, or timezone-mismatched state fails closed with
+exit 5.
+
+When backlog exceeds the cap, PRDigest durably skips the oldest prefix and
+processes only the newest window. That loss is intentional and reported. For a
+timezone migration, stop the timer, preserve the old state for audit, move it
+aside, change the configured timezone, use explicit replay for any required
+dates, then restart the timer. Never silently edit a corrupt checkpoint; inspect
+and repair ownership/JSON or restore a known-good copy first.
+
+GitHub does not publish a search-index freshness guarantee. Keep the host
+timezone equal to the configured digest timezone; the supplied 09:05 timer then
+leaves about nine hours after local midnight. If a later audit finds a delayed
+merge, use `--date YYYY-MM-DD` to replay it.
+
+## systemd deployment
+
+On Ubuntu, install Ruby, `tzdata`, the gem, and then:
+
+```sh
+sudo useradd --system --home /nonexistent --shell /usr/sbin/nologin prdigest
+sudo install -d -o root -g prdigest -m 0750 /etc/prdigest
+sudo install -o root -g prdigest -m 0640 configs/config.example.yml /etc/prdigest/config.yml
+sudo install -o root -g root -m 0600 .env.example /etc/prdigest/.env
+sudo install -o root -g root -m 0644 scripts/systemd/prdigest.service /etc/systemd/system/
+sudo install -o root -g root -m 0644 scripts/systemd/prdigest.timer /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl start prdigest.service
+sudo systemctl enable --now prdigest.timer
+```
+
+Edit the installed config and environment file before starting. systemd creates
+`/var/lib/prdigest` as `prdigest:prdigest` mode `0700`; state files are `0600`.
+Inspect with `systemctl status prdigest.service`, `systemctl list-timers
+prdigest.timer`, and `journalctl -u prdigest.service`. Test a missed-day catch-up
+by stopping the timer for a day, then starting the service. Journal output can
+contain repository/date context, so restrict journal group membership and
+retention.
+
+Rollback by stopping the timer, installing the prior gem/image, restoring the
+matching config and a known-good state backup, and restarting. Replay omitted
+dates explicitly; do not move a checkpoint forward by hand.
+
+## Container
+
+The Alpine image includes `tzdata` and runs as the unprivileged `prdigest` user.
+Initialize mounted ownership with the image before normal use:
+
+```sh
+docker build -t prdigest:0.1.0 .
+docker volume create prdigest-state
+docker run --rm --user root --entrypoint sh -v prdigest-state:/var/lib/prdigest prdigest:0.1.0 \
+  -c 'chown -R prdigest:prdigest /var/lib/prdigest && chmod 0700 /var/lib/prdigest'
+docker run --rm --env-file /etc/prdigest/.env \
+  -v /etc/prdigest/config.yml:/etc/prdigest/config.yml:ro \
+  -v prdigest-state:/var/lib/prdigest prdigest:0.1.0
+```
+
+## Verification and troubleshooting
+
+`bundle exec rake test` is fully offline. Release preparation also supplies
+`test/smoke/gem_install.sh`, `test/smoke/docker.sh`, and
+`test/smoke/systemd.sh`. Live GitHub boundary and Telegram allowlist smokes are
+manual gates: retain timestamps and pass/fail only, never credentials, response
+bodies, message text, or private titles.
+
+- Exit 2: check config discovery, YAML, timezone, cap, chat allowlist, and env.
+- Exit 3: check repository access, rate/search limits, and replay later.
+- Exit 4: inspect `error.kind` and `delivery`. Retry ordinary `telegram` failures;
+  reconcile `telegram_ambiguous`, `telegram_permanent`, and
+  `delivery_checkpoint_permanent` before moving any checkpoint.
+- Exit 5: check `/var/lib/prdigest`, mode/owner, JSON version, date, and timezone.
+- Exit 6: earlier dates or a skipped prefix are durable; inspect the result before retry.
+
+Concurrent scheduled runs remain unsupported because date-cursor scheduling is
+single-owner. Delivery itself takes a nonblocking per-date lock, so a competing
+sender fails instead of duplicating the same payload. The systemd oneshot is the
+normal run coordination mechanism.
+
+See [SECURITY.md](SECURITY.md) for token scope, rotation, and private-data flow.
+
+## Non-goals
+
+v0.1.0 has no built-in Hive configuration discovery, LLM content, web UI,
+interactive bot commands,
+multi-chat routing, organization discovery, non-GitHub forge support, or
+long-running scheduler. This repository prepares v0.1.0 without tagging,
+publishing the gem, or creating a release.
+
+## License
+
+MIT

data/SECURITY.md

@@ -0,0 +1,28 @@
+# Security
+
+## Credentials
+
+PRDigest reads tokens only from environment variables. Keep `/etc/prdigest/.env`
+owned by `root:root` with mode `0600`; never put tokens in YAML, command-line
+arguments, fixtures, logs, or issue reports.
+
+Use a fine-grained GitHub personal access token limited to the repositories in
+`github.repos`, with read-only metadata and pull-request access. Use a dedicated
+Telegram bot whose `chat_id` is the only delivery target in the allowlist. Rotate
+either token immediately if it may have appeared in output, then inspect and
+restrict journal retention.
+
+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.
+
+## Reporting
+
+Report vulnerabilities privately to the maintainer address in the gem metadata.
+Do not include credentials, token-bearing URLs, private PR content, config files,
+state files, or unredacted journal output.
+
+## Supported release
+
+Security fixes target the latest published release. v0.1.0 is prepared here but
+is not published, tagged, or released by the build process.

data/configs/config.example.yml

@@ -0,0 +1,32 @@
+# prdigest — multi-repo merged-PR daily digest (Hive-independent)
+
+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
+  # explicit owner/name only — empty list is a hard error
+  repos:
+    - owner/repo-one
+    - owner/repo-two
+
+telegram:
+  token_env: TELEGRAM_BOT_TOKEN
+  chat_id_allowlist:
+    - -1001234567890
+  chat_id: -1001234567890
+
+digest:
+  line_stats: true
+  send_empty: true
+  empty_message: "Merged PR digest — {date}\nTotal: 0 PRs"
+
+state:
+  path: /var/lib/prdigest/state.json
+  # Stable rendered chunks and next-unsent position, separate from the date cursor.
+  delivery_path: /var/lib/prdigest/deliveries

data/exe/prdigest

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "prdigest"
+
+exit Prdigest::CLI.invoke(ARGV)

data/lib/prdigest/cli.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "date"
+require "json"
+require "thor"
+
+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
+
+    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=") }
+        parsed = parse(argv)
+        return print_version(out) if parsed[:command] == "version"
+        return print_help(out) if %w[help --help -h].include?(parsed[:command])
+
+        unless %w[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)
+        if parsed[:command] == "serve"
+          err.puts "prdigest serve: deferred in v0.1.0 — use systemd timer + `prdigest run`"
+          return 0
+        end
+
+        validate_date!(parsed[:date]) if parsed[:date]
+        repositories = if parsed[:repos].empty?
+                         nil
+                       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"
+        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
+      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
+      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
+      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
+      end
+
+      alias start invoke
+
+      def exit_on_failure?
+        true
+      end
+
+      private
+
+      def parse(argv)
+        parsed = { command: nil, config: nil, date: nil, dry_run: false, json: false, repos: [] }
+        args = Array(argv).dup
+        until args.empty?
+          argument = args.shift
+          case argument
+          when "--help", "-h"
+            parsed[:command] = "help"
+          when "--dry-run"
+            parsed[:dry_run] = true
+          when "--json"
+            parsed[:json] = true
+          when "--config", "--date", "--repo"
+            value = args.shift
+            raise ParseError, "missing value for #{argument}" if value.nil? || value.start_with?("--")
+            if argument == "--repo"
+              parsed[:repos] << value
+            else
+              parsed[argument.delete_prefix("--").tr("-", "_").to_sym] = value
+            end
+          when /\A--config=(.*)\z/
+            raise ParseError, "missing value for --config" if Regexp.last_match(1).empty?
+            parsed[:config] = Regexp.last_match(1)
+          when /\A--date=(.*)\z/
+            raise ParseError, "missing value for --date" if Regexp.last_match(1).empty?
+            parsed[:date] = Regexp.last_match(1)
+          when /\A--repo=(.*)\z/
+            raise ParseError, "missing value for --repo" if Regexp.last_match(1).empty?
+            parsed[:repos] << Regexp.last_match(1)
+          when /\A-/
+            raise ParseError, "unknown option"
+          else
+            raise ParseError, "unexpected argument" if parsed[:command]
+            parsed[:command] = argument
+          end
+        end
+        parsed
+      end
+
+      def validate_date!(value)
+        unless value.match?(/\A\d{4}-\d{2}-\d{2}\z/) && Date.iso8601(value).iso8601 == value
+          raise ConfigError, "date must use YYYY-MM-DD"
+        end
+      rescue Date::Error
+        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
+        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]}"
+        end
+      end
+
+      def human_dates(dates)
+        values = Array(dates)
+        values.empty? ? "none" : values.join(",")
+      end
+
+      def print_version(out)
+        out.puts "prdigest #{VERSION}"
+        0
+      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"
+        0
+      end
+    end
+  end
+end

data/lib/prdigest/clock.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+require "tzinfo"
+
+module Prdigest
+  class Clock
+    Window = Data.define(:local_date, :start_time, :end_time) do
+      def cover?(time)
+        time >= start_time && time < end_time
+      end
+
+      def zero_length?
+        start_time == end_time
+      end
+    end
+
+    def initialize(timezone:, now: -> { Time.now })
+      @timezone = TZInfo::Timezone.get(timezone)
+      @now = now
+    end
+
+    def yesterday
+      (@timezone.to_local(@now.call.utc).to_date - 1)
+    end
+
+    def window(local_date)
+      date = Date.iso8601(local_date.to_s)
+      Window.new(date, resolve_midnight(date), resolve_midnight(date + 1))
+    end
+
+    private
+
+    def resolve_midnight(date)
+      local = Time.utc(date.year, date.month, date.day)
+      periods = @timezone.periods_for_local(local)
+      return periods.map { |period| (local - period.utc_total_offset).utc }.min unless periods.empty?
+
+      transition = @timezone.transitions_up_to(local + 172_800, local - 172_800).find do |candidate|
+        before = Time.at(candidate.timestamp_value + candidate.previous_offset.utc_total_offset).utc
+        after = Time.at(candidate.timestamp_value + candidate.offset.utc_total_offset).utc
+        after > before && local >= before && local < after
+      end
+      raise ConfigError, "cannot resolve local midnight for #{date}" unless transition
+
+      Time.at(transition.timestamp_value).utc
+    end
+  end
+end