tempest-rb 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b397a067ca8e4f637036351fd8d3f29f41dc7ef6a96d809c8f793993f34c940d
-  data.tar.gz: 83435fddf2631e5d16afdc8d185ae3b3ba5666c1a5bb6b838705e5ee4fc526f2
+  metadata.gz: b22f62246911621115721bfa860e0e20227af1e183934c68d8ca1d04a964f809
+  data.tar.gz: 6988da4cf1585e253697b7b45ac1b2459ab8358d795937e242624081ae871f1c
 SHA512:
-  metadata.gz: c770fedb069f714b7a280535efe1c5984001bfcad6cce6a1ab4cc0e6ee8ee579fec9402659578b1573572c98d40fd089fe82f5469c0e040f0cc33b1dfeda39a0
-  data.tar.gz: 3cba24306fa9a90c00f44c77bd768753b1ab26f3420be6fb3706b275bdbaa426e869ce791248e3c0be7a8dfc27e673610f7286b60ffb416806c4b01b26ccf724
+  metadata.gz: abf73e75e9f73690fbdddfc588313a727b232de1b735146702f50a90801dace70241a326bc4245c5c16f142cea87e3ff8bc77146ebb292963898dcefc3359024
+  data.tar.gz: 86f61238ba980c20e770838b67ccfc2f68eef1fe6c3d26d2f17b083c1044ed4d4bd16415faffd5d764c939ae86dbd2e322da1cad839ac5999e9ec56e3c8f8c0e

data/README.md

@@ -37,6 +37,24 @@ bundle install
 bundle exec exe/tempest
 ```
 
+## Upgrading
+
+The gem on RubyGems is `tempest-rb`, while the executable it ships is `tempest`.
+
+If you installed it with `gem install`:
+
+```sh
+gem update tempest-rb
+```
+
+To check the currently installed version:
+
+```sh
+tempest --version
+```
+
+If you use Bundler in your own project, bump the requirement in your `Gemfile` and run `bundle update tempest-rb` instead.
+
 ## Usage
 
 Set your credentials in the environment and run `tempest`:
@@ -73,6 +91,25 @@ Each post in the timeline is prefixed with a short `$XX` id, and URLs found insi
 | `--no-stream`     | Disable the auto-started Jetstream feed                      |
 | `--feed=MODE`     | `home` (default, your follows + your own posts) or `self` (only your own posts) |
 
+### Non-interactive CLI
+
+Once you have signed in once with `tempest tui`, you can call the CLI from scripts and tools:
+
+```sh
+tempest whoami --json
+tempest post "今日もよろしくお願いします"
+tempest feed me --since today --format json | jq '.text'
+tempest feed author asonas.bsky.social --limit 20
+```
+
+`--format=json` emits newline-delimited JSON; one post per line. The schema is documented in `lib/tempest/post_view.rb`.
+
+`--format=raw` emits the underlying `getAuthorFeed`/`getTimeline` response pretty-printed; do not rely on its shape.
+
+`--format=line` (default when stdout is a TTY) prints the same single-line representation as the TUI scroll buffer.
+
+The non-interactive subcommands require a cached session on disk. If your cache is missing or expired, run `tempest tui` once to refresh it.
+
 ### Environment variables
 
 | Variable                    | Purpose                                                                 |
@@ -101,25 +138,6 @@ A built-in watchdog runs alongside the Jetstream consumer regardless of logging:
 
 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.
 
-## Non-interactive CLI
-
-Once you have signed in once with `tempest tui`, you can call the CLI from scripts and tools:
-
-```sh
-tempest whoami --json
-tempest post "今日もよろしくお願いします"
-tempest feed me --since today --format json | jq '.text'
-tempest feed author asonas.bsky.social --limit 20
-```
-
-`--format=json` emits newline-delimited JSON; one post per line. The schema is documented in `lib/tempest/post_view.rb`.
-
-`--format=raw` emits the underlying `getAuthorFeed`/`getTimeline` response pretty-printed; do not rely on its shape.
-
-`--format=line` (default when stdout is a TTY) prints the same single-line representation as the TUI scroll buffer.
-
-The non-interactive subcommands require a cached session on disk. If your cache is missing or expired, run `tempest tui` once to refresh it.
-
 ## Development
 
 ```sh

data/lib/tempest/cli.rb

@@ -98,8 +98,8 @@ module Tempest
       Tempest::Commands::Tui.cursor_store(env)
     end
 
-    def build_debug_logger(env)
-      Tempest::Commands::Tui.build_debug_logger(env)
+    def build_debug_logger(env, argv: [])
+      Tempest::Commands::Tui.build_debug_logger(env, argv: argv)
     end
 
     def watchdog_options(env)

data/lib/tempest/commands/tui.rb

@@ -29,7 +29,8 @@ module Tempest
                store: nil)
         Tempest::REPL::Formatter.color = stdout.respond_to?(:tty?) && stdout.tty? && env["NO_COLOR"].to_s.empty?
 
-        debug_logger = build_debug_logger(env)
+        debug_logger = build_debug_logger(env, argv: argv)
+        announce_debug_logger(debug_logger, stderr)
 
         store ||= Tempest::SessionStore.new(path: Tempest::SessionStore.default_path(env))
         session = sign_in(env, stdout, stdin, session_factory, store: store)
@@ -184,12 +185,29 @@ module Tempest
         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)
+      # Returns a Tempest::DebugLog::Channel. info.log is always enabled
+      # (suppress with TEMPEST_NO_LOG=1). debug.log is enabled when --debug is
+      # passed on the command line or TEMPEST_DEBUG=1 is set in the
+      # environment. The legacy TEMPEST_DEBUG_LOG=<path> env var still routes
+      # everything to a single file regardless of the other settings.
+      def build_debug_logger(env, argv: [])
+        Tempest::DebugLog.build(env: env, debug: debug_flag?(argv: argv, env: env))
+      end
+
+      def debug_flag?(argv:, env:)
+        return true if argv.include?("--debug")
+        env["TEMPEST_DEBUG"] == "1"
+      end
+
+      # Print a one-line note on stderr so the user knows where to look for
+      # the log files. Silent when logging is disabled.
+      def announce_debug_logger(channel, stderr)
+        paths = channel.loggers.map { |l|
+          dev = l.instance_variable_get(:@logdev)
+          dev && dev.filename
+        }.compact
+        return if paths.empty?
+        stderr.puts "[tempest] debug log: #{paths.join(', ')}"
       end
 
       # Parses TEMPEST_WATCHDOG_THRESHOLD / TEMPEST_WATCHDOG_INTERVAL into the
@@ -286,6 +304,11 @@ module Tempest
             --feed=MODE         Choose what the live feed subscribes to:
                                   home  (default) Your follows + your own posts
                                   self  Only your own posts (legacy echo mode)
+            --debug             Also write a verbose debug.log alongside the
+                                always-on info.log. Both files live under
+                                $XDG_STATE_HOME/tempest (default
+                                ~/.local/state/tempest) and use size-based
+                                rotation (5 MiB x 5 files).
 
           Environment (required only when no cached session is available):
             TEMPEST_IDENTIFIER     Your handle (e.g. asonas.bsky.social)
@@ -306,13 +329,17 @@ module Tempest
                                    $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          Set to 1 to behave as if --debug was passed.
+            TEMPEST_LOG_DIR        Override the directory holding info.log and debug.log.
+                                   Default: $XDG_STATE_HOME/tempest or
+                                   ~/.local/state/tempest.
+            TEMPEST_NO_LOG         Set to 1 to disable info.log/debug.log entirely.
+            TEMPEST_DEBUG_LOG      Legacy: path to a single combined log file. When set,
+                                   every log line (DEBUG and above) is written to this
+                                   path in addition to the regular info.log/debug.log.
             TEMPEST_DEBUG_LOG_LEVEL
-                                   DEBUG | INFO (default) | WARN. Overrides the log
-                                   verbosity when TEMPEST_DEBUG_LOG is enabled.
+                                   DEBUG (default) | INFO | WARN. Overrides the log
+                                   verbosity for the legacy TEMPEST_DEBUG_LOG file.
             TEMPEST_WATCHDOG_THRESHOLD
                                    Seconds without a Jetstream event before the watchdog
                                    forces a reconnect (default: 90).

data/lib/tempest/debug_log.rb

@@ -3,15 +3,35 @@ require "fileutils"
 require "time"
 
 module Tempest
-  # Thin wrapper around stdlib Logger for opt-in debug logging.
+  # Structured diagnostic logging for tempest.
   #
-  # 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.
+  # `Tempest::DebugLog.build` returns a `Channel` that fans messages out to one
+  # or more underlying `::Logger` instances. The format is logfmt-flavored
+  # single-line:
   #
-  # 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
+  #   2026-05-18T01:23:45+09:00 level=warn module=watchdog event=stalled_detected elapsed_seconds=612.3 threshold_seconds=600
+  #
+  # The fixed leading keys (`level=`, `module=`, `event=`) are produced by the
+  # formatter from the level + progname + first-positional arguments, so call
+  # sites just write the variable fields as keyword arguments:
+  #
+  #   @logger.warn("watchdog", event: "stalled_detected", elapsed_seconds: 612.3, threshold_seconds: 600)
+  #
+  # Output destinations:
+  #
+  #   * `info.log` — INFO and above, always written when logging is enabled.
+  #   * `debug.log` — DEBUG and above, written only when `--debug` (or the
+  #     equivalent flag passed to `build(debug: true)`) is on.
+  #
+  # Default base directory is `$XDG_STATE_HOME/tempest` (falling back to
+  # `~/.local/state/tempest`). Override via `TEMPEST_LOG_DIR=/path` for the
+  # whole tree, or set `TEMPEST_NO_LOG=1` to disable both files entirely (used
+  # by tests). The legacy `TEMPEST_DEBUG_LOG=/path/to/file` env var still
+  # works and routes everything (DEBUG and above) to a single file regardless
+  # of the other settings.
+  #
+  # All file destinations use size-based rotation (5 MiB x 5 files) so a
+  # long-running session can't fill the disk.
   module DebugLog
     LEVELS = {
       "DEBUG" => Logger::DEBUG,
@@ -21,33 +41,39 @@ module Tempest
       "FATAL" => Logger::FATAL,
     }.freeze
 
+    DEFAULT_ROTATION_COUNT = 5
+    DEFAULT_ROTATION_SIZE = 5 * 1024 * 1024
+
     module_function
 
-    def from_env(env)
-      raw = env["TEMPEST_DEBUG_LOG"]
-      if raw.nil? || raw.empty?
-        return build_null_logger
+    def build(env:, debug: false)
+      loggers = []
+
+      legacy = env["TEMPEST_DEBUG_LOG"]
+      if legacy && !legacy.empty?
+        loggers << build_file_logger(legacy, level: resolve_level(env["TEMPEST_DEBUG_LOG_LEVEL"]) || Logger::DEBUG)
       end
 
-      path = File.expand_path(raw)
-      FileUtils.mkdir_p(File.dirname(path))
+      unless env["TEMPEST_NO_LOG"] == "1"
+        dir = log_dir(env)
+        loggers << build_file_logger(File.join(dir, "info.log"), level: Logger::INFO)
+        loggers << build_file_logger(File.join(dir, "debug.log"), level: Logger::DEBUG) if debug
+      end
 
-      logger = Logger.new(path, "daily")
-      logger.level = resolve_level(env["TEMPEST_DEBUG_LOG_LEVEL"]) || Logger::INFO
-      logger.formatter = formatter
-      logger
+      Channel.new(loggers: loggers)
     end
 
-    def build_null_logger
-      logger = Logger.new(IO::NULL)
-      logger.level = Logger::FATAL
-      logger
+    def null_channel
+      Channel.new(loggers: [])
     end
 
     def formatter
       proc do |severity, time, progname, msg|
-        tag = progname && !progname.to_s.empty? ? "[#{progname}] " : ""
-        "#{time.iso8601} #{severity.ljust(5)} #{tag}#{msg}\n"
+        parts = []
+        parts << "level=#{severity.downcase}"
+        parts << "module=#{progname}" if progname && !progname.to_s.empty?
+        parts << msg if msg && !msg.to_s.empty?
+        "#{time.iso8601} #{parts.join(' ')}\n"
       end
     end
 
@@ -55,5 +81,99 @@ module Tempest
       return nil if value.nil? || value.empty?
       LEVELS[value.to_s.upcase]
     end
+
+    def log_dir(env)
+      override = env["TEMPEST_LOG_DIR"]
+      return override if override && !override.empty?
+
+      xdg = env["XDG_STATE_HOME"]
+      base = if xdg && !xdg.empty?
+        xdg
+      else
+        File.join(env["HOME"] || Dir.home, ".local", "state")
+      end
+      File.join(base, "tempest")
+    end
+
+    def build_file_logger(path, level:)
+      path = File.expand_path(path)
+      FileUtils.mkdir_p(File.dirname(path))
+      logger = Logger.new(path, DEFAULT_ROTATION_COUNT, DEFAULT_ROTATION_SIZE)
+      logger.level = level
+      logger.formatter = formatter
+      logger
+    end
+
+    def encode_value(value)
+      case value
+      when nil
+        "nil"
+      when true, false, Integer, Float, Symbol
+        value.to_s
+      when Time
+        value.iso8601
+      else
+        s = value.to_s
+        if s.empty?
+          '""'
+        elsif s.match?(/[\s"=]/)
+          '"' + s.gsub('\\', '\\\\\\\\').gsub('"', '\\"') + '"'
+        else
+          s
+        end
+      end
+    end
+
+    class Channel
+      attr_reader :loggers
+
+      def initialize(loggers:)
+        @loggers = Array(loggers)
+      end
+
+      def info(mod, event:, **fields)
+        emit(Logger::INFO, mod, event, fields)
+      end
+
+      def debug(mod, event:, **fields)
+        emit(Logger::DEBUG, mod, event, fields)
+      end
+
+      def warn(mod, event:, **fields)
+        emit(Logger::WARN, mod, event, fields)
+      end
+
+      def error(mod, event:, **fields)
+        emit(Logger::ERROR, mod, event, fields)
+      end
+
+      def close
+        @loggers.each do |logger|
+          begin
+            logger.close
+          rescue StandardError
+            # Best-effort: a half-built or already-closed logger should not
+            # take down shutdown.
+          end
+        end
+      end
+
+      private
+
+      def emit(level, mod, event, fields)
+        return if @loggers.empty?
+        msg = format_body(event, fields)
+        @loggers.each { |logger| logger.add(level, msg, mod) }
+      end
+
+      def format_body(event, fields)
+        parts = []
+        parts << "event=#{Tempest::DebugLog.encode_value(event)}" if event
+        fields.each do |k, v|
+          parts << "#{k}=#{Tempest::DebugLog.encode_value(v)}"
+        end
+        parts.join(" ")
+      end
+    end
   end
 end

data/lib/tempest/jetstream/decoder.rb

@@ -2,6 +2,7 @@ require "json"
 
 require_relative "../../tempest"
 require_relative "../facet"
+require_relative "../post"
 
 module Tempest
   module Jetstream
@@ -18,10 +19,11 @@ module Tempest
       :subject_uri,
       :facets,
       :reply_parent_uri,
+      :embed_kind,
     ) do
       def initialize(kind:, did:, time_us:, collection:, operation:, rkey:, cid:,
                      text:, created_at:, subject_uri: nil, facets: [],
-                     reply_parent_uri: nil)
+                     reply_parent_uri: nil, embed_kind: nil)
         super
       end
 
@@ -72,6 +74,7 @@ module Tempest
           subject_uri: subject.is_a?(Hash) ? subject["uri"] : nil,
           facets: Tempest::Facet.parse(record["facets"]),
           reply_parent_uri: reply_parent.is_a?(Hash) ? reply_parent["uri"] : nil,
+          embed_kind: Tempest::Post.embed_kind_from(record["embed"]),
         )
       rescue JSON::ParserError
         nil

data/lib/tempest/jetstream/stream_manager.rb

@@ -33,7 +33,7 @@ module Tempest
         @cursor_store = cursor_store
         @cursor_save_interval = cursor_save_interval
         @filter = filter
-        @logger = logger || Tempest::DebugLog.build_null_logger
+        @logger = logger || Tempest::DebugLog.null_channel
         @thread = nil
         @mutex = Mutex.new
         @stopping = false
@@ -50,10 +50,8 @@ module Tempest
       end
 
       def stop
-        @logger.info("stream") do
-          live = @mutex.synchronize { @cursor_state[:live] }
-          "stopping final_cursor=#{live.inspect}"
-        end
+        live = @mutex.synchronize { @cursor_state[:live] }
+        @logger.info("stream", event: "stopping", final_cursor: live)
         @mutex.synchronize { @stopping = true }
         thread = @mutex.synchronize do
           t = @thread
@@ -84,7 +82,15 @@ module Tempest
       def force_reconnect
         thread = @mutex.synchronize { @thread }
         return unless thread&.alive?
-        @logger.warn("stream") { "force_reconnect requested" }
+        @logger.warn("stream", event: "force_reconnect_requested")
+        # Pre-advance last_event_at so the watchdog's next tick sees a fresh
+        # connection and doesn't re-fire while the worker is still recovering.
+        # Without this, a second Stalled can land in the backoff sleep — which
+        # is outside the inner `rescue Stalled` block — and would historically
+        # take down the worker. The outer rescue in `run` now catches that
+        # case too, but suppressing the duplicate force_reconnect is still the
+        # right thing to do.
+        @mutex.synchronize { @last_event_at = @clock.call }
         begin
           thread.raise(Stalled.new("forced reconnect"))
         rescue ThreadError
@@ -98,19 +104,28 @@ module Tempest
         Thread.current.report_on_exception = false
         cursor, startup_gap_since = load_initial_cursor
         if startup_gap_since
-          @logger.warn("stream") { "startup_stale stale_since=#{startup_gap_since.iso8601}" }
+          @logger.warn("stream", event: "startup_stale", stale_since: startup_gap_since)
           on_event.call(StreamStatus.new(state: :gapped, since: startup_gap_since))
         end
         last_saved_cursor = cursor
         last_save_at = nil
         attempt = 0
 
-        @logger.info("stream") do
-          age = cursor ? cursor_age_seconds(cursor) : nil
-          "worker start cursor=#{cursor.inspect} cursor_age_seconds=#{age.inspect}"
-        end
+        @logger.info(
+          "stream",
+          event: "worker_start",
+          cursor: cursor,
+          cursor_age_seconds: cursor ? cursor_age_seconds(cursor) : nil,
+        )
 
         until stopping?
+          # The outer `rescue Stalled` below catches Stalled raised by
+          # force_reconnect that lands OUTSIDE the inner each_event block —
+          # e.g. during @sleeper.call(delay), the cursor age check, or the
+          # disconnected/reconnecting status emission. Without this guard, a
+          # second force_reconnect arriving during recovery used to escape
+          # the inner rescue and silently kill the worker thread.
+          begin
           # Detect a long offline gap from the cursor's age rather than from
           # wall-clock disconnect timestamps. When the host machine sleeps,
           # the background thread is suspended and we only learn about the
@@ -123,7 +138,12 @@ module Tempest
             cursor_age = @clock.call.to_f - (cursor / 1_000_000.0)
             if cursor_age > CURSOR_WINDOW_SECONDS
               since = Time.at(cursor / 1_000_000.0)
-              @logger.warn("stream") { "gapped cursor_age_seconds=#{cursor_age.round(1)} since=#{since.iso8601}" }
+              @logger.warn(
+                "stream",
+                event: "gapped",
+                cursor_age_seconds: cursor_age.round(1),
+                since: since,
+              )
               on_event.call(StreamStatus.new(state: :gapped, since: since))
               cursor = nil
             end
@@ -131,13 +151,19 @@ module Tempest
 
           if attempt > 0
             delay = @backoff[[attempt - 1, @backoff.length - 1].min]
-            @logger.info("stream") { "reconnecting attempt=#{attempt} cursor=#{cursor.inspect} backoff_just_slept=#{delay}" }
+            @logger.info(
+              "stream",
+              event: "reconnect_attempt",
+              attempt: attempt,
+              cursor: cursor,
+              backoff_just_slept_seconds: delay,
+            )
             on_event.call(StreamStatus.new(state: :reconnecting))
           end
 
           error = nil
           saw_event = false
-          @logger.info("stream") { "subscribe cursor=#{cursor.inspect}" }
+          @logger.info("stream", event: "subscribe", cursor: cursor, attempt: attempt)
           begin
             @client.each_event(cursor: cursor) do |event|
               now = @clock.call
@@ -154,7 +180,7 @@ module Tempest
                 if @cursor_store && cursor != last_saved_cursor
                   if last_save_at.nil? || (now - last_save_at) >= @cursor_save_interval
                     @cursor_store.save(time_us: cursor, at: now)
-                    @logger.debug("stream") { "cursor save time_us=#{cursor}" }
+                    @logger.debug("stream", event: "cursor_save", cursor: cursor)
                     last_saved_cursor = cursor
                     last_save_at = now
                     @mutex.synchronize { @cursor_state[:saved] = cursor }
@@ -164,6 +190,7 @@ module Tempest
               next if @filter && !@filter.call(event)
 
               if attempt > 0 && !saw_event
+                @logger.info("stream", event: "live_resumed", attempt: attempt, cursor: cursor)
                 on_event.call(StreamStatus.new(state: :live))
               end
               saw_event = true
@@ -171,11 +198,25 @@ module Tempest
             end
           rescue Stalled => e
             error = e
-            @logger.warn("stream") { "stalled — forced reconnect cursor=#{cursor.inspect}" }
+            @logger.warn(
+              "stream",
+              event: "disconnected",
+              reason: "stalled",
+              cursor: cursor,
+              error_class: e.class.name,
+              error_message: e.message,
+            )
             on_event.call(StreamError.new(e))
           rescue => e
             error = e
-            @logger.warn("stream") { "disconnect error=#{e.class}: #{e.message}" }
+            @logger.warn(
+              "stream",
+              event: "disconnected",
+              reason: "error",
+              cursor: cursor,
+              error_class: e.class.name,
+              error_message: e.message,
+            )
             on_event.call(StreamError.new(e))
           end
 
@@ -186,7 +227,7 @@ module Tempest
           if @cursor_store && cursor && cursor != last_saved_cursor
             now = @clock.call
             @cursor_store.save(time_us: cursor, at: now)
-            @logger.debug("stream") { "cursor save (disconnect) time_us=#{cursor}" }
+            @logger.debug("stream", event: "cursor_save_on_disconnect", cursor: cursor)
             last_saved_cursor = cursor
             last_save_at = now
             @mutex.synchronize { @cursor_state[:saved] = cursor }
@@ -203,9 +244,22 @@ module Tempest
           delay = @backoff[[attempt, @backoff.length - 1].min]
           @sleeper.call(delay)
           attempt += 1
+          rescue Stalled => e
+            # Stalled landed outside the inner each_event rescue (typically
+            # in @sleeper.call). Treat it as a transient blip and let the loop
+            # try again instead of letting the worker thread die.
+            @logger.warn(
+              "stream",
+              event: "stalled_outside_each_event",
+              attempt: attempt,
+              cursor: cursor,
+              error_message: e.message,
+            )
+            attempt += 1
+          end
         end
 
-        @logger.info("stream") { "worker exit final_cursor=#{cursor.inspect}" }
+        @logger.info("stream", event: "worker_exit", final_cursor: cursor)
       end
 
       def cursor_age_seconds(cursor)

data/lib/tempest/jetstream/watchdog.rb

@@ -31,7 +31,7 @@ module Tempest
         @interval_seconds = interval_seconds
         @clock = clock
         @sleeper = sleeper
-        @logger = logger || Tempest::DebugLog.build_null_logger
+        @logger = logger || Tempest::DebugLog.null_channel
         @thread = nil
         @mutex = Mutex.new
         @stopping = false
@@ -70,21 +70,44 @@ module Tempest
 
       def tick
         last = @stream_manager.last_event_at
-        return unless @stream_manager.running?
+        running = @stream_manager.running?
+        @logger.debug(
+          "watchdog",
+          event: "tick",
+          running: running,
+          last_event_at: last,
+          elapsed_seconds: last ? (@clock.call - last).round(1) : nil,
+          threshold_seconds: @threshold_seconds,
+        )
+        return unless running
         return if last.nil?
 
         elapsed = @clock.call - last
         return unless elapsed > @threshold_seconds
 
-        @logger.warn("watchdog") do
-          "stalled stream elapsed_seconds=#{elapsed.round(1)} threshold=#{@threshold_seconds} — forcing reconnect"
-        end
+        @logger.warn(
+          "watchdog",
+          event: "stalled_detected",
+          elapsed_seconds: elapsed.round(1),
+          threshold_seconds: @threshold_seconds,
+          last_event_at: last,
+        )
+        @logger.warn(
+          "watchdog",
+          event: "force_reconnect_requested",
+          elapsed_seconds: elapsed.round(1),
+        )
         @stream_manager.force_reconnect
       rescue StandardError => e
         # Never let a bad clock, logger, or stream_manager bug kill the thread.
         # Best-effort log; if logger also raises, swallow.
         begin
-          @logger.error("watchdog") { "tick error=#{e.class}: #{e.message}" }
+          @logger.error(
+            "watchdog",
+            event: "tick_error",
+            error_class: e.class.name,
+            error_message: e.message,
+          )
         rescue StandardError
         end
       end

data/lib/tempest/post.rb

@@ -2,9 +2,18 @@ require_relative "../tempest"
 require_relative "facet"
 
 module Tempest
-  Post = Data.define(:uri, :cid, :handle, :display_name, :text, :created_at, :facets, :reply_parent_uri) do
+  Post = Data.define(:uri, :cid, :handle, :display_name, :text, :created_at, :facets, :reply_parent_uri, :embed_kind) do
+    # AT Protocol embed `$type` values mapped to short symbols used by the
+    # REPL. `record` (quote) and `external` (link card) are intentionally
+    # absent: they're surfaced through other UI (URL annotation), so they
+    # don't get a media-marker emoji.
+    EMBED_KINDS = {
+      "app.bsky.embed.images" => :images,
+      "app.bsky.embed.video"  => :video,
+    }.freeze
+
     def initialize(uri:, cid:, handle:, display_name:, text:, created_at:,
-                   facets: [], reply_parent_uri: nil)
+                   facets: [], reply_parent_uri: nil, embed_kind: nil)
       super
     end
 
@@ -23,9 +32,20 @@ module Tempest
         created_at: record["createdAt"],
         facets: Facet.parse(record["facets"]),
         reply_parent_uri: reply_parent.is_a?(Hash) ? reply_parent["uri"] : nil,
+        embed_kind: embed_kind_from(post["embed"] || record["embed"]),
       )
     end
 
+    # The view-side `$type` carries a `#view` suffix (e.g.
+    # `app.bsky.embed.images#view`); the raw record uses the bare form.
+    # Strip the suffix before looking up so both feed and Jetstream payloads
+    # classify identically.
+    def self.embed_kind_from(embed)
+      return nil unless embed.is_a?(Hash)
+      type = embed["$type"].to_s.sub(/#view\z/, "")
+      EMBED_KINDS[type]
+    end
+
     # Compose a record for com.atproto.repo.createRecord (app.bsky.feed.post).
     # When `reply` is provided, both root and parent are set to the same
     # target. This is correct for top-level replies and a known v1 trade-off
@@ -58,6 +78,26 @@ module Tempest
       )
     end
 
+    # Compose an app.bsky.feed.like record referencing the subject post and
+    # send it via com.atproto.repo.createRecord. The AppView surfaces this in
+    # like counts and notifications for the target post.
+    def self.like(client, did:, subject_uri:, subject_cid:,
+                  created_at: Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%LZ"))
+      record = {
+        "$type" => "app.bsky.feed.like",
+        "subject" => { "uri" => subject_uri, "cid" => subject_cid },
+        "createdAt" => created_at,
+      }
+      client.post(
+        "com.atproto.repo.createRecord",
+        body: {
+          repo: did,
+          collection: "app.bsky.feed.like",
+          record: record,
+        },
+      )
+    end
+
     # Scans `text` for bare URLs and builds AT Protocol link facets pointing
     # at each match. Without this, the AppView treats URLs as plain text and
     # does not render them as clickable links.

data/lib/tempest/repl/dispatcher.rb

@@ -5,7 +5,7 @@ module Tempest
     Command = Data.define(:name, :args)
 
     class Dispatcher
-      KNOWN_COMMANDS = %i[timeline quit help stream open relogin].freeze
+      KNOWN_COMMANDS = %i[timeline quit help stream open relogin fav].freeze
       DOLLAR_ID = /\A\$[A-Z]{2}\z/.freeze
 
       def dispatch(input)

data/lib/tempest/repl/formatter.rb

@@ -25,6 +25,14 @@ module Tempest
       URL_PATTERN = %r{https?://[^\s]+}.freeze
       DECORATE_PATTERN = Regexp.union(URL_PATTERN, HASHTAG_PATTERN).freeze
 
+      # Visible hint that a post carries an image / video embed. Only kinds
+      # that aren't already surfaced by other UI (link cards become URLs,
+      # quote posts inline their record) get a marker.
+      MEDIA_EMOJI = {
+        images: "📷",
+        video:  "🎥",
+      }.freeze
+
       class << self
         attr_accessor :color
       end
@@ -37,6 +45,7 @@ module Tempest
         facets = post.respond_to?(:facets) ? post.facets : nil
         body = annotate_urls(squeeze(post.text), registry, facets: facets)
         body = decorate_body(body)
+        body = prepend_media_marker(body, embed_kind_of(post))
         body = prepend_reply_marker(body, reply_parent_uri_of(post), registry)
         icon = avatar_icon(post_did(post), avatar_store)
         compose(var, format_time(post.created_at), post.handle, nil, body, icon: icon)
@@ -87,6 +96,7 @@ module Tempest
           facets = event.respond_to?(:facets) ? event.facets : nil
           body = annotate_urls(squeeze(event.text), registry, facets: facets)
           body = decorate_body(body)
+          body = prepend_media_marker(body, embed_kind_of(event))
           body = prepend_reply_marker(body, reply_parent_uri_of(event), registry)
           var = registry&.assign_post(event)
         end
@@ -127,6 +137,17 @@ module Tempest
         "#{marker}#{body}"
       end
 
+      def embed_kind_of(record)
+        record.respond_to?(:embed_kind) ? record.embed_kind : nil
+      end
+
+      def prepend_media_marker(body, embed_kind)
+        emoji = MEDIA_EMOJI[embed_kind]
+        return body unless emoji
+        body = body.to_s
+        body.empty? ? emoji : "#{emoji} #{body}"
+      end
+
       def annotate_urls(text, registry, facets: nil)
         return text unless registry
         text = text.to_s

data/lib/tempest/repl/runner.rb

@@ -17,7 +17,8 @@ module Tempest
         Available commands:
           :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
+          :open $XX|$LX   Open the post or URL with the given id in the browser
+          :fav $XX        Like the post with id $XX
           :relogin        Re-authenticate when the cached session is dead
           :help           Show this help
           :quit           Exit tempest (or Ctrl-D)
@@ -108,6 +109,8 @@ module Tempest
             handle_reply(command.args[0], command.args[1])
           when :open
             handle_open(command.args.first)
+          when :fav
+            handle_fav(command.args.first)
           when :relogin
             handle_relogin
           when :unknown
@@ -182,12 +185,41 @@ module Tempest
         @output.puts "error: #{e.message}"
       end
 
+      def handle_fav(var)
+        if var.nil? || var.empty?
+          @output.puts "usage: :fav $XX"
+          return
+        end
+        target = @registry.find_post(var)
+        if target.nil?
+          @output.puts "unknown id: #{var}"
+          return
+        end
+        response = Post.like(
+          @client,
+          did: @session.did,
+          subject_uri: reply_uri_for(target),
+          subject_cid: target.cid,
+        )
+        @output.puts "liked: #{response["uri"]}"
+      rescue Tempest::AuthenticationError => e
+        @output.puts "error: #{e.message} (#{RELOGIN_HINT})"
+      rescue Tempest::Error => e
+        @output.puts "error: #{e.message}"
+      end
+
       def handle_open(var)
         if var.nil? || var.empty?
-          @output.puts "usage: :open $LX"
+          @output.puts "usage: :open $XX or $LX"
           return
         end
-        url = @registry.find_url(var)
+
+        if (post = @registry.find_post(var))
+          url = bsky_post_url(post)
+        else
+          url = @registry.find_url(var)
+        end
+
         if url.nil?
           @output.puts "unknown id: #{var}"
           return
@@ -200,6 +232,22 @@ module Tempest
         target.respond_to?(:uri) && target.uri ? target.uri : target.at_uri
       end
 
+      # bsky.app accepts both handles and DIDs in the profile path. Prefer the
+      # handle when we have it (human-readable URLs are nicer for sharing or
+      # for the user to glance at), but fall back to the DID for posts that
+      # arrived through Jetstream where only the DID is known.
+      def bsky_post_url(target)
+        at_uri = reply_uri_for(target)
+        match = at_uri.match(%r{\Aat://([^/]+)/app\.bsky\.feed\.post/(.+)\z})
+        return nil unless match
+
+        did = match[1]
+        rkey = match[2]
+        handle = target.respond_to?(:handle) ? target.handle : nil
+        profile = handle && !handle.empty? ? handle : did
+        "https://bsky.app/profile/#{profile}/post/#{rkey}"
+      end
+
       def handle_stream(arg)
         if @stream_manager.nil?
           @output.puts "stream is not available in this session"

data/lib/tempest/version.rb

@@ -1,3 +1,3 @@
 module Tempest
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tempest-rb
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Yuya Fujiwara