tempest-rb 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c5f6d650f85e45e0d4f39f9ace3184141099dfacc7e499144157ccc3e1b9e1fa
+  data.tar.gz: 0d86da89ce1f2c8335d5a9d62911a8d86bc68e9f5e317e6b884aa898bd69227c
+SHA512:
+  metadata.gz: cf7a05f136b292d36a01893f7ee83d8362b53ae2391e3dece56ef80b5d24f7dc0070dfadc12f6e49d1615649f69fa6511993cce0e7be272db36f5295cbc71cee
+  data.tar.gz: 0ee8b681779c0d7d54b51e85f5127c13d32923f90fb7c340e3c48ba49824bfab5a0600e5493523aba93723ad6b849826eaee933df7edd6746a06da6271d99e7a

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuya Fujiwara
+
+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,120 @@
+# tempest
+
+`tempest` is a REPL-style terminal client for [Bluesky](https://bsky.app/), inspired by the classic Twitter client [earthquake](https://github.com/jugyo/earthquake). It speaks the AT Protocol directly: XRPC for reads and writes, and Jetstream for the live timeline feed.
+
+This is an unofficial, third-party client. It is not affiliated with or endorsed by Bluesky Social, PBC.
+
+## Features
+
+- Earthquake-style split layout: a scrolling timeline on top, a prompt at the bottom.
+- Auto-started [Jetstream](https://github.com/bluesky-social/jetstream) feed so new posts appear as they happen.
+- Home timeline fetch on demand.
+- Post by simply typing — anything that is not a `:command` is sent as a new post.
+- Session cache with automatic token refresh; the email sign-in code is requested only once.
+- DID-to-handle resolution with in-memory caching.
+
+## Requirements
+
+- Ruby 4.0 or later
+- A Bluesky account and an [app password](https://bsky.app/settings/app-passwords)
+
+## Installation
+
+Once published to RubyGems:
+
+```sh
+gem install tempest-rb
+```
+
+The installed executable is `tempest` (the gem name on RubyGems is `tempest-rb` because `tempest` was already taken).
+
+Or from a local checkout:
+
+```sh
+git clone https://github.com/asonas/tempest.git
+cd tempest
+bundle install
+bundle exec exe/tempest
+```
+
+## Usage
+
+Set your credentials in the environment and run `tempest`:
+
+```sh
+export TEMPEST_IDENTIFIER="your-handle.bsky.social"
+export TEMPEST_APP_PASSWORD="xxxx-xxxx-xxxx-xxxx"
+tempest
+```
+
+The first sign-in may prompt for the email code Bluesky sends as a second factor. After a successful sign-in the session is cached at `$XDG_CONFIG_HOME/tempest/session.json` (defaults to `~/.config/tempest/session.json`), and subsequent launches refresh tokens silently.
+
+### REPL commands
+
+| Command          | Description                                      |
+|------------------|--------------------------------------------------|
+| `:timeline`      | Fetch and print the home timeline                |
+| `:stream on/off` | Toggle the Jetstream live feed                   |
+| `:open $LX`      | Open the URL with id `$LX` in the browser        |
+| `:help`          | Show in-app help                                 |
+| `:quit`          | Exit (`Ctrl-D` works too)                        |
+| `$XX <text>`     | Reply to the post with id `$XX`                  |
+
+Anything else you type is sent as a new post.
+
+Each post in the timeline is prefixed with a short `$XX` id, and URLs found inside posts get their own `$LX` ids. Use those ids with `$XX <text>` to reply or `:open $LX` to open a link.
+
+### CLI options
+
+| Option            | Description                                                  |
+|-------------------|--------------------------------------------------------------|
+| `-h`, `--help`    | Show CLI help                                                |
+| `-v`, `--version` | Show version                                                 |
+| `--no-stream`     | Disable the auto-started Jetstream feed                      |
+| `--feed=MODE`     | `home` (default, your follows + your own posts) or `self` (only your own posts) |
+
+### Environment variables
+
+| Variable                    | Purpose                                                                 |
+|-----------------------------|-------------------------------------------------------------------------|
+| `TEMPEST_IDENTIFIER`        | Your handle, e.g. `asonas.bsky.social`                                  |
+| `TEMPEST_APP_PASSWORD`      | An app password generated in Bluesky settings                           |
+| `TEMPEST_PDS_HOST`          | Override PDS host (default `https://bsky.social`)                       |
+| `TEMPEST_AUTH_FACTOR_TOKEN` | Pre-supply an email sign-in code; usually unnecessary                   |
+| `TEMPEST_NO_STREAM`         | Set to `1` to disable the auto-started Jetstream feed                   |
+| `TEMPEST_FEED`              | `home` (default) or `self`; equivalent to `--feed`                      |
+| `TEMPEST_OPEN_CMD`          | Command used by `:open $LX` to open URLs (default `open`); URL is passed as the single argument |
+| `TEMPEST_SESSION_PATH`      | Override the session cache path                                         |
+| `TEMPEST_CURSOR_PATH`       | Override the Jetstream cursor cache path                                |
+| `TEMPEST_TIMELINE_PATH`     | Override the timeline snapshot cache path                               |
+| `TEMPEST_DEBUG_LOG`         | Path to a debug log file (unset by default; see Diagnostics)            |
+| `TEMPEST_DEBUG_LOG_LEVEL`   | `DEBUG`, `INFO` (default), or `WARN`                                    |
+| `TEMPEST_WATCHDOG_THRESHOLD`| Seconds without a Jetstream event before a forced reconnect (default 90) |
+| `TEMPEST_WATCHDOG_INTERVAL` | Seconds between watchdog checks (default 30)                            |
+| `NO_COLOR`                  | Disable ANSI colors when set to any non-empty value                     |
+
+## Diagnostics
+
+Set `TEMPEST_DEBUG_LOG` to a writable path and `tempest` will append timestamped notes about every Jetstream state transition to that file (rotated daily). When the variable is unset no file is created and the runtime behaves exactly as before. Example: `TEMPEST_DEBUG_LOG=~/tempest-debug.log tempest`.
+
+A built-in watchdog runs alongside the Jetstream consumer regardless of logging: if no event arrives within `TEMPEST_WATCHDOG_THRESHOLD` seconds (default 90), it forces the consumer to reconnect. This protects the live feed against stalled sockets that the kernel still believes are alive, the typical failure mode after macOS sleep and wake.
+
+To inspect the log, grep by component tag: `grep '\[stream\]' ~/tempest-debug.log` shows connect, reconnect, gap, and disconnect events, while `grep '\[watchdog\]' ~/tempest-debug.log` shows forced reconnects.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+```
+
+The test suite uses Ruby's bundled `minitest`-style harness under `test/`.
+
+## License
+
+Released under the [MIT License](LICENSE). See `LICENSE` for the full text.
+
+## Acknowledgements
+
+- The [AT Protocol](https://atproto.com/) and [Bluesky](https://bsky.app/) teams for the open protocol and the Jetstream firehose.
+- [earthquake](https://github.com/jugyo/earthquake) for the original REPL-style terminal client design.

data/exe/tempest

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require_relative "../lib/tempest/cli"
+
+exit Tempest::CLI.run

data/lib/tempest/cli.rb

@@ -0,0 +1,305 @@
+require_relative "../tempest"
+require_relative "config"
+require_relative "debug_log"
+require_relative "session"
+require_relative "session_store"
+require_relative "cursor_store"
+require_relative "timeline_store"
+require_relative "xrpc_client"
+require_relative "handle_resolver"
+require_relative "follows"
+require_relative "jetstream/client"
+require_relative "jetstream/stream_manager"
+require_relative "jetstream/subscription"
+require_relative "jetstream/watchdog"
+require_relative "repl/runner"
+require_relative "repl/formatter"
+require_relative "repl/async_output"
+require_relative "repl/screen"
+
+module Tempest
+  module CLI
+    module_function
+
+    def run(argv: ARGV, env: ENV, stdout: $stdout, stderr: $stderr, stdin: $stdin,
+            session_factory: Tempest::Session.method(:create),
+            store: nil)
+      if argv.include?("--version") || argv.include?("-v")
+        stdout.puts "tempest #{Tempest::VERSION}"
+        return 0
+      end
+
+      if argv.include?("--help") || argv.include?("-h")
+        stdout.puts help_text
+        return 0
+      end
+
+      Tempest::REPL::Formatter.color = stdout.respond_to?(:tty?) && stdout.tty? && env["NO_COLOR"].to_s.empty?
+
+      debug_logger = build_debug_logger(env)
+
+      store ||= Tempest::SessionStore.new(path: Tempest::SessionStore.default_path(env))
+      session = sign_in(env, stdout, stdin, session_factory, store: store)
+      client = Tempest::XRPCClient.new(session)
+      input = RelineReader.new
+
+      handle_resolver = Tempest::HandleResolver.new(client: client)
+      handle_resolver.seed(session.did, session.handle)
+
+      mode = feed_mode(argv: argv, env: env)
+      plan = build_subscription(
+        mode: mode, session: session, client: client,
+        handle_resolver: handle_resolver, stdout: stdout,
+      )
+
+      jetstream_client = Tempest::Jetstream::Client.new(
+        wanted_collections: [
+          "app.bsky.feed.post",
+          "app.bsky.feed.like",
+          "app.bsky.feed.repost",
+        ],
+        wanted_dids: plan.wanted_dids,
+      )
+      stream_manager = Tempest::Jetstream::StreamManager.new(
+        client: jetstream_client,
+        cursor_store: cursor_store(env),
+        filter: plan.filter,
+        logger: debug_logger,
+      )
+      watchdog = Tempest::Jetstream::Watchdog.new(
+        stream_manager: stream_manager,
+        logger: debug_logger,
+        **watchdog_options(env),
+      )
+
+      stdout.puts "tempest #{Tempest::VERSION} — signed in as @#{session.handle}"
+      stdout.puts "Type :help for commands, :quit to exit."
+
+      screen = Tempest::REPL::Screen.new(io: stdout)
+      screen.enable
+
+      runner = Tempest::REPL::Runner.new(
+        session: session,
+        client: client,
+        input: input,
+        output: screen.enabled? ? screen : stdout,
+        stream_output: screen.enabled? ? screen : Tempest::REPL::AsyncOutput.new(stdout),
+        stream_manager: stream_manager,
+        handle_resolver: handle_resolver,
+        timeline_store: timeline_store(env),
+        opener: opener_for(env: env),
+      )
+
+      begin
+        runner.bootstrap_timeline
+
+        if stream_default_on?(argv, env)
+          runner.auto_start_stream
+        end
+
+        watchdog.start
+        runner.run
+        0
+      ensure
+        watchdog.stop
+        screen.disable
+      end
+    rescue Tempest::Config::MissingValue => e
+      stderr.puts "configuration error: #{e.message}"
+      stderr.puts "Set TEMPEST_IDENTIFIER and TEMPEST_APP_PASSWORD before launching."
+      2
+    rescue Tempest::AuthenticationError => e
+      stderr.puts "authentication failed: #{e.message}"
+      3
+    rescue Tempest::Error => e
+      stderr.puts "error: #{e.message}"
+      1
+    end
+
+    def sign_in(env, stdout, stdin, session_factory, store:)
+      identifier_hint = nil_if_empty(env["TEMPEST_IDENTIFIER"])
+      pds_host_hint = nil_if_empty(env["TEMPEST_PDS_HOST"])
+
+      if (existing = store.load(identifier: identifier_hint, pds_host: pds_host_hint))
+        attach_store(existing, store, existing.identifier || identifier_hint)
+        begin
+          existing.refresh!
+          return existing
+        rescue Tempest::Error => e
+          existing.on_change = nil
+          stdout.puts "[tempest] cached session refresh failed: #{e.message}"
+          stdout.puts "[tempest] cache kept at #{store.path}; falling back to TEMPEST_IDENTIFIER/TEMPEST_APP_PASSWORD"
+        end
+      end
+
+      config = Tempest::Config.from_env(env)
+      session = create_with_2fa(config, env, stdout, stdin, session_factory)
+      attach_store(session, store, config.identifier)
+      store.save(session, identifier: config.identifier)
+      session
+    end
+
+    def nil_if_empty(value)
+      value.nil? || value.empty? ? nil : value
+    end
+
+    def create_with_2fa(config, env, stdout, stdin, session_factory)
+      token = env["TEMPEST_AUTH_FACTOR_TOKEN"]
+      session_factory.call(config, auth_factor_token: token)
+    rescue Tempest::AuthenticationError => e
+      raise unless e.code == "AuthFactorTokenRequired" && token.nil?
+
+      stdout.puts "Bluesky sent a sign-in code to your email. Enter it below."
+      stdout.print "code: "
+      stdout.flush
+      code = stdin.gets&.strip
+      raise Tempest::AuthenticationError.new("sign-in cancelled (no code entered)", code: e.code) if code.nil? || code.empty?
+
+      session_factory.call(config, auth_factor_token: code)
+    end
+
+    def stream_default_on?(argv, env)
+      return false if argv.include?("--no-stream")
+      return false if env["TEMPEST_NO_STREAM"] == "1"
+      true
+    end
+
+    def cursor_store(env)
+      Tempest::CursorStore.new(path: Tempest::CursorStore.default_path(env))
+    end
+
+    # Returns a Logger configured from TEMPEST_DEBUG_LOG (path) and
+    # TEMPEST_DEBUG_LOG_LEVEL. When TEMPEST_DEBUG_LOG is unset, the returned
+    # logger writes to IO::NULL at FATAL level so call sites can log
+    # unconditionally without producing files or output.
+    def build_debug_logger(env)
+      Tempest::DebugLog.from_env(env)
+    end
+
+    # Parses TEMPEST_WATCHDOG_THRESHOLD / TEMPEST_WATCHDOG_INTERVAL into the
+    # keyword-hash shape Watchdog expects. Raises ArgumentError on garbage so
+    # a typo in env config fails loudly rather than silently degrading.
+    def watchdog_options(env)
+      threshold = env["TEMPEST_WATCHDOG_THRESHOLD"]
+      interval = env["TEMPEST_WATCHDOG_INTERVAL"]
+      {
+        threshold_seconds: threshold ? Integer(threshold) :
+          Tempest::Jetstream::Watchdog::DEFAULT_THRESHOLD_SECONDS,
+        interval_seconds: interval ? Integer(interval) :
+          Tempest::Jetstream::Watchdog::DEFAULT_INTERVAL_SECONDS,
+      }
+    end
+
+    def timeline_store(env)
+      Tempest::TimelineStore.new(path: Tempest::TimelineStore.default_path(env))
+    end
+
+    def opener_for(env:, system_proc: Kernel.method(:system))
+      cmd = env["TEMPEST_OPEN_CMD"]
+      return Tempest::REPL::Runner::DEFAULT_OPENER if cmd.nil? || cmd.empty?
+      ->(url) { system_proc.call(cmd, url) }
+    end
+
+    VALID_FEED_MODES = %i[home self].freeze
+
+    def feed_mode(argv:, env: {})
+      flag = argv.find { |a| a.start_with?("--feed=") }&.split("=", 2)&.last
+      raw = flag || env["TEMPEST_FEED"] || "home"
+
+      mode = raw.to_sym
+      raise ArgumentError, "invalid --feed value: #{raw.inspect} (must be home|self)" \
+        unless VALID_FEED_MODES.include?(mode)
+      mode
+    end
+
+    # Decides what the Jetstream subscription should look like for a freshly
+    # signed-in session. In :self mode we only watch the user's own DID (the
+    # historical earthquake-style "echo my posts" UX). In :home mode we fetch
+    # the user's follows from AppView and let Subscription decide between
+    # server-side wantedDids filtering and a firehose+client-filter fallback.
+    # When a handle_resolver is provided, follow handles are seeded so the
+    # live feed can render @handle without an extra getProfile roundtrip.
+    def build_subscription(mode:, session:, client:, handle_resolver: nil, stdout: nil)
+      case mode
+      when :self
+        Tempest::Jetstream::Plan.new(wanted_dids: [session.did], filter: nil)
+      when :home
+        stdout&.puts "[tempest] fetching follows..."
+        follows = Tempest::Follows.fetch(client, actor: session.did)
+        follows.each { |f| handle_resolver&.seed(f[:did], f[:handle]) }
+        plan = Tempest::Jetstream::Subscription.build(self_did: session.did, follows: follows)
+        if plan.filter
+          stdout&.puts "[tempest] following #{follows.length} accounts (exceeds 10000 cap; using firehose+client-filter)"
+        else
+          stdout&.puts "[tempest] following #{follows.length} accounts"
+        end
+        plan
+      else
+        raise ArgumentError, "unknown feed mode: #{mode.inspect}"
+      end
+    end
+
+    def attach_store(session, store, identifier)
+      session.identifier ||= identifier
+      session.on_change = ->(s) { store.save(s, identifier: s.identifier || identifier) }
+    end
+
+    def help_text
+      <<~HELP
+        Usage: tempest [options]
+
+        Options:
+          -h, --help       Show this help
+          -v, --version    Show version
+          --no-stream      Disable the auto-started Jetstream feed
+          --feed=MODE      Choose what the live feed subscribes to:
+                             home  (default) Your follows + your own posts
+                             self  Only your own posts (legacy echo mode)
+
+        Environment (required only when no cached session is available):
+          TEMPEST_IDENTIFIER     Your handle (e.g. asonas.bsky.social)
+          TEMPEST_APP_PASSWORD   An app password generated in Bluesky settings
+          TEMPEST_PDS_HOST       Override PDS host (default: https://bsky.social)
+          TEMPEST_AUTH_FACTOR_TOKEN
+                                 Pre-supply an email sign-in code (rarely needed; the CLI will
+                                 prompt interactively when Bluesky asks for one)
+          TEMPEST_NO_STREAM      Set to 1 to disable the auto-started Jetstream feed
+          TEMPEST_OPEN_CMD       Command used to open URLs when :open $LX is invoked
+                                 (default: "open"). The URL is passed as the single
+                                 argument after the command.
+          TEMPEST_SESSION_PATH   Override the session cache path (default:
+                                 $XDG_CONFIG_HOME/tempest/session.json or
+                                 ~/.config/tempest/session.json). The cache holds refreshed
+                                 tokens so the email sign-in code is only requested once.
+          TEMPEST_CURSOR_PATH    Override the Jetstream cursor cache path (default:
+                                 $XDG_CONFIG_HOME/tempest/cursor.json). Holds the last-seen
+                                 time_us so a restart can replay missed events.
+          TEMPEST_FEED           "home" (default) or "self"; equivalent to --feed.
+          TEMPEST_DEBUG_LOG      Path to a debug log file. When set, the live-stream
+                                 component writes timestamped state transitions to this
+                                 file (rotated daily). Unset by default — no file is
+                                 created and no output is produced.
+          TEMPEST_DEBUG_LOG_LEVEL
+                                 DEBUG | INFO (default) | WARN. Overrides the log
+                                 verbosity when TEMPEST_DEBUG_LOG is enabled.
+          TEMPEST_WATCHDOG_THRESHOLD
+                                 Seconds without a Jetstream event before the watchdog
+                                 forces a reconnect (default: 90).
+          TEMPEST_WATCHDOG_INTERVAL
+                                 Seconds between watchdog checks (default: 30).
+      HELP
+    end
+
+    # Wraps Reline to fit the input interface expected by REPL::Runner.
+    class RelineReader
+      def initialize
+        require "reline"
+        @reline = Reline
+      end
+
+      def readline(prompt)
+        @reline.readline(prompt, true)
+      end
+    end
+  end
+end

data/lib/tempest/config.rb

@@ -0,0 +1,30 @@
+require_relative "../tempest"
+
+module Tempest
+  class Config
+    class MissingValue < Tempest::Error; end
+
+    DEFAULT_PDS_HOST = "https://bsky.social".freeze
+
+    attr_reader :identifier, :app_password, :pds_host
+
+    def self.from_env(env = ENV)
+      identifier = env["TEMPEST_IDENTIFIER"]
+      raise MissingValue, "TEMPEST_IDENTIFIER is not set" if identifier.nil? || identifier.empty?
+
+      app_password = env["TEMPEST_APP_PASSWORD"]
+      raise MissingValue, "TEMPEST_APP_PASSWORD is not set" if app_password.nil? || app_password.empty?
+
+      pds_host = env["TEMPEST_PDS_HOST"]
+      pds_host = DEFAULT_PDS_HOST if pds_host.nil? || pds_host.empty?
+
+      new(identifier: identifier, app_password: app_password, pds_host: pds_host)
+    end
+
+    def initialize(identifier:, app_password:, pds_host: DEFAULT_PDS_HOST)
+      @identifier = identifier
+      @app_password = app_password
+      @pds_host = pds_host
+    end
+  end
+end

data/lib/tempest/cursor_store.rb

@@ -0,0 +1,52 @@
+require "fileutils"
+require "json"
+require "time"
+
+require_relative "../tempest"
+
+module Tempest
+  # Persists the last-seen Jetstream `time_us` so a restarted tempest can hand
+  # the server a cursor and replay events from the previous session. Stored
+  # alongside session.json under XDG_CONFIG_HOME. Staleness is decided by the
+  # caller (StreamManager checks saved_at against its replay window).
+  class CursorStore
+    def self.default_path(env = ENV)
+      explicit = env["TEMPEST_CURSOR_PATH"]
+      return explicit if explicit && !explicit.empty?
+
+      base = env["XDG_CONFIG_HOME"]
+      base = File.join(env["HOME"].to_s, ".config") if base.nil? || base.empty?
+      File.join(base, "tempest", "cursor.json")
+    end
+
+    def initialize(path:)
+      @path = path
+    end
+
+    attr_reader :path
+
+    def save(time_us:, at: Time.now)
+      payload = { "time_us" => time_us, "saved_at" => at.utc.iso8601(6) }
+
+      FileUtils.mkdir_p(File.dirname(@path))
+      File.open(@path, File::WRONLY | File::CREAT | File::TRUNC, 0o600) do |io|
+        io.write(JSON.generate(payload))
+      end
+    end
+
+    def load
+      return nil unless File.exist?(@path)
+
+      data = JSON.parse(File.read(@path))
+      return nil unless data.is_a?(Hash) && data["time_us"] && data["saved_at"]
+
+      { time_us: data["time_us"], saved_at: Time.iso8601(data["saved_at"]) }
+    rescue JSON::ParserError, ArgumentError
+      nil
+    end
+
+    def clear
+      File.delete(@path) if File.exist?(@path)
+    end
+  end
+end

data/lib/tempest/debug_log.rb

@@ -0,0 +1,59 @@
+require "logger"
+require "fileutils"
+require "time"
+
+module Tempest
+  # Thin wrapper around stdlib Logger for opt-in debug logging.
+  #
+  # Activated only when the TEMPEST_DEBUG_LOG environment variable points at a
+  # writable path. Otherwise from_env returns a Logger pointed at IO::NULL at
+  # FATAL level, so call sites can unconditionally call `info`/`debug`/`warn`
+  # without an `if logger` guard and without producing any output or file I/O.
+  #
+  # Output format is ISO-8601 local time + level + progname tag + message, e.g.:
+  #   2026-05-17T10:30:42+09:00 INFO  [stream] reconnect attempt=2 cursor=nil
+  module DebugLog
+    LEVELS = {
+      "DEBUG" => Logger::DEBUG,
+      "INFO"  => Logger::INFO,
+      "WARN"  => Logger::WARN,
+      "ERROR" => Logger::ERROR,
+      "FATAL" => Logger::FATAL,
+    }.freeze
+
+    module_function
+
+    def from_env(env)
+      raw = env["TEMPEST_DEBUG_LOG"]
+      if raw.nil? || raw.empty?
+        return build_null_logger
+      end
+
+      path = File.expand_path(raw)
+      FileUtils.mkdir_p(File.dirname(path))
+
+      logger = Logger.new(path, "daily")
+      logger.level = resolve_level(env["TEMPEST_DEBUG_LOG_LEVEL"]) || Logger::INFO
+      logger.formatter = formatter
+      logger
+    end
+
+    def build_null_logger
+      logger = Logger.new(IO::NULL)
+      logger.level = Logger::FATAL
+      logger
+    end
+
+    def formatter
+      proc do |severity, time, progname, msg|
+        tag = progname && !progname.to_s.empty? ? "[#{progname}] " : ""
+        "#{time.iso8601} #{severity.ljust(5)} #{tag}#{msg}\n"
+      end
+    end
+
+    def resolve_level(value)
+      return nil if value.nil? || value.empty?
+      LEVELS[value.to_s.upcase]
+    end
+  end
+end

data/lib/tempest/facet.rb

@@ -0,0 +1,40 @@
+require_relative "../tempest"
+
+module Tempest
+  # Typed representations of app.bsky.richtext.facet entries attached to a
+  # post record. `byte_start` / `byte_end` are UTF-8 byte offsets into the
+  # post text (NOT character offsets). We only model the `#link` feature for
+  # now; `#mention` and `#tag` features are dropped at parse time.
+  module Facet
+    Link = Data.define(:byte_start, :byte_end, :uri)
+
+    module_function
+
+    # Parse a raw facets array from a Bluesky record into typed entries.
+    # Unknown / unsupported feature types are silently dropped.
+    def parse(raw)
+      return [] unless raw.is_a?(Array)
+
+      raw.flat_map do |facet|
+        next [] unless facet.is_a?(Hash)
+        index = facet["index"] || {}
+        byte_start = index["byteStart"]
+        byte_end = index["byteEnd"]
+        next [] unless byte_start.is_a?(Integer) && byte_end.is_a?(Integer)
+
+        features = facet["features"]
+        next [] unless features.is_a?(Array)
+
+        features.filter_map do |feature|
+          next nil unless feature.is_a?(Hash)
+          case feature["$type"]
+          when "app.bsky.richtext.facet#link"
+            uri = feature["uri"]
+            next nil unless uri.is_a?(String) && !uri.empty?
+            Link.new(byte_start: byte_start, byte_end: byte_end, uri: uri)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tempest/follows.rb

@@ -0,0 +1,36 @@
+require_relative "../tempest"
+
+module Tempest
+  # Fetches the authenticated user's follow list via app.bsky.graph.getFollows.
+  # Returns a flat array of `{did:, handle:}` so callers can both warm the
+  # HandleResolver and build a Jetstream `wantedDids` filter from a single
+  # pass.
+  module Follows
+    PAGE_LIMIT = 100
+
+    module_function
+
+    def fetch(client, actor:)
+      results = []
+      cursor = nil
+
+      loop do
+        response = client.get(
+          "app.bsky.graph.getFollows",
+          query: { actor: actor, limit: PAGE_LIMIT, cursor: cursor },
+        )
+
+        Array(response["follows"]).each do |row|
+          did = row["did"]
+          handle = row["handle"]
+          results << { did: did, handle: handle } if did
+        end
+
+        cursor = response["cursor"]
+        break if cursor.nil? || cursor.empty?
+      end
+
+      results
+    end
+  end
+end