riffer-rig 0.2.0 → 0.3.0

data/lib/riffer/rig/ui/animator.rb

@@ -3,20 +3,36 @@
 # Animated output is gated behind an interactive, colour-enabled TTY, so piped
 # or tested runs stay silent and escape-free.
 class Riffer::Rig::UI::Animator
-  REVEAL_FRAME_SECONDS = 0.05
-  SPINNER_FRAME_SECONDS = 0.12
-  EQ_LEVELS = '▁▂▃▄▅▆▇█'.chars.freeze
-  EQ_BARS = 7
-  NEUTRAL_LABEL = 'riffing…'
+  REVEAL_FRAME_SECONDS = 0.05 #: Float
+
+  SPINNER_FRAME_SECONDS = 0.12 #: Float
+
+  EQ_LEVELS = '▁▂▃▄▅▆▇█'.chars.freeze #: Array[String]
+
+  EQ_BARS = 7 #: Integer
+
+  NEUTRAL_LABEL = 'riffing…' #: String
+
   REASONING_PHRASES = [
     'contemplating…', 'pondering…', 'mulling it over…', 'reasoning…',
     'connecting the dots…', 'herding thoughts…', 'consulting the muse…',
     'doing some deep listening…', 'warming up…', 'tuning up…',
     'in the woodshed…', 'vamping…', 'finding the key…', 'counting it off…',
     'jamming internally…'
-  ].freeze
-  REASONING_TICK_RANGE = (1..5)
+  ].freeze #: Array[String]
 
+  REASONING_TICK_RANGE = (1..5) #: Range[Integer]
+
+  # @rbs @io: untyped
+  # @rbs @theme: Riffer::Rig::UI::Theme
+  # @rbs @thread: Thread?
+  # @rbs @mode: Symbol
+  # @rbs @phrase: String?
+  # @rbs @stop: bool
+
+  # @rbs io: untyped
+  # @rbs ?theme: Riffer::Rig::UI::Theme
+  # @rbs return: void
   def initialize(io: $stdout, theme: Riffer::Rig::UI::Theme.for(io))
     @io = io
     @theme = theme
@@ -26,6 +42,9 @@ class Riffer::Rig::UI::Animator
   end
 
   # When not on a TTY, prints the final frame once instead of animating.
+  #
+  # @rbs frames: Array[Array[String]]
+  # @rbs return: void
   def reveal(frames)
     unless enabled?
       frames.last.each { |line| @io.puts(line) }
@@ -41,6 +60,8 @@ class Riffer::Rig::UI::Animator
     end
   end
 
+  # @rbs ?mode: Symbol
+  # @rbs return: void
   def start(mode = :neutral)
     return unless enabled?
 
@@ -54,16 +75,21 @@ class Riffer::Rig::UI::Animator
     @thread = Thread.new { animate }
   end
 
+  # @rbs return: void
   def stop
-    return unless @thread
+    thread = @thread
+    return unless thread
 
     @stop = true
-    @thread.join
+    thread.join
     @thread = nil
     @io.print("\r\e[K")
     @io.flush
   end
 
+  # @rbs tick: Integer
+  # @rbs ?label: String
+  # @rbs return: String
   def equalizer(tick, label = NEUTRAL_LABEL)
     bars = Array.new(EQ_BARS) do |i|
       height = (Math.sin((tick + i) * 0.6).abs * (EQ_LEVELS.length - 1)).round
@@ -75,6 +101,7 @@ class Riffer::Rig::UI::Animator
 
   private
 
+  # @rbs return: void
   def animate
     tick = 0
     roll_at = 0.0 # force an immediate phrase roll when entering reasoning mode
@@ -88,18 +115,31 @@ class Riffer::Rig::UI::Animator
   end
 
   # Re-rolls both phrase and duration whenever the reasoning tick expires.
+  #
+  # @rbs roll_at: Float
+  # @rbs return: Float
   def roll_phrase(roll_at)
     now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
     return roll_at unless @mode == :reasoning && now >= roll_at
 
     @phrase = REASONING_PHRASES.sample
-    now + rand(REASONING_TICK_RANGE)
+    now + roll_rand
+  end
+
+  # Range rand returns nil for an empty range; this one is a non-empty constant.
+  #
+  # @rbs return: Integer
+  def roll_rand
+    x = rand(REASONING_TICK_RANGE)
+    x || 0
   end
 
+  # @rbs return: String
   def label
-    @mode == :reasoning ? @phrase : NEUTRAL_LABEL
+    @mode == :reasoning ? @phrase || NEUTRAL_LABEL : NEUTRAL_LABEL
   end
 
+  # @rbs return: bool
   def enabled?
     @theme.enabled && @io.respond_to?(:tty?) && @io.tty?
   end

data/lib/riffer/rig/ui/banner.rb

@@ -10,7 +10,7 @@ module Riffer::Rig::UI::Banner
     '██╔══██╗██║██╔══╝  ██╔══╝  ██╔══╝  ██╔══██╗',
     '██║  ██║██║██║     ██║     ███████╗██║  ██║',
     '╚═╝  ╚═╝╚═╝╚═╝     ╚═╝     ╚══════╝╚═╝  ╚═╝'
-  ].freeze
+  ].freeze #: Array[String]
 
   ROW_COLOURS = [
     Riffer::Rig::UI::Palette::PINK,
@@ -19,25 +19,49 @@ module Riffer::Rig::UI::Banner
     Riffer::Rig::UI::Palette::BLUE,
     Riffer::Rig::UI::Palette::CYAN,
     Riffer::Rig::UI::Palette::CYAN
-  ].freeze
+  ].freeze #: Array[Array[Integer]]
 
-  INFO_LABEL_WIDTH = 8
-  INDENT = '  '
+  INFO_LABEL_WIDTH = 8 #: Integer
 
+  INDENT = '  ' #: String
+
+  # @rbs theme: Riffer::Rig::UI::Theme
+  # @rbs model: String
+  # @rbs cwd: String
+  # @rbs context: String
+  # @rbs skills: String
+  # @rbs version: String
+  # @rbs return: String
   def call(theme, model:, cwd:, context:, skills:, version:)
     lines(theme, model: model, cwd: cwd, context: context, skills: skills, version: version).join("\n")
   end
 
+  # @rbs theme: Riffer::Rig::UI::Theme
+  # @rbs model: String
+  # @rbs cwd: String
+  # @rbs context: String
+  # @rbs skills: String
+  # @rbs version: String
+  # @rbs return: Array[String]
   def lines(theme, model:, cwd:, context:, skills:, version:)
     [''] + art(theme) + [''] +
       info(theme, model: model, cwd: cwd, context: context, skills: skills, version: version) + ['']
   end
 
+  # @rbs theme: Riffer::Rig::UI::Theme
+  # @rbs return: Array[String]
   def art(theme)
     art = WORDMARK.each_index.map { |i| "#{INDENT}#{theme.paint(WORDMARK[i], ROW_COLOURS[i])}" }
     art + ["#{INDENT}#{theme.cyan("♪ let's riff ♪")}"]
   end
 
+  # @rbs theme: Riffer::Rig::UI::Theme
+  # @rbs model: String
+  # @rbs cwd: String
+  # @rbs context: String
+  # @rbs skills: String
+  # @rbs version: String
+  # @rbs return: Array[String]
   def info(theme, model:, cwd:, context:, skills:, version:)
     rows = { model: model, cwd: cwd, context: context, skills: skills, version: version }.map do |label, value|
       "  #{theme.magenta('▸')} #{theme.grey(label.to_s.ljust(INFO_LABEL_WIDTH))}#{value}"

data/lib/riffer/rig/ui/cursor.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Hides the terminal cursor while a turn is in flight: a hidden cursor can't
+# flicker against the animator's erase-and-redraw churn.
+class Riffer::Rig::UI::Cursor
+  HIDE = "\e[?25l" #: String
+
+  SHOW = "\e[?25h" #: String
+
+  # @rbs @io: untyped
+  # @rbs @theme: Riffer::Rig::UI::Theme
+
+  # @rbs io: untyped
+  # @rbs ?theme: Riffer::Rig::UI::Theme
+  # @rbs return: void
+  def initialize(io: $stdout, theme: Riffer::Rig::UI::Theme.for(io))
+    @io = io
+    @theme = theme
+  end
+
+  # @rbs return: void
+  def hide
+    write(HIDE)
+  end
+
+  # @rbs return: void
+  def show
+    write(SHOW)
+  end
+
+  private
+
+  # @rbs sequence: String
+  # @rbs return: void
+  def write(sequence)
+    return unless enabled?
+
+    @io.print(sequence)
+    @io.flush
+  end
+
+  # @rbs return: bool
+  def enabled?
+    @theme.enabled && @io.respond_to?(:tty?) && @io.tty?
+  end
+end

data/lib/riffer/rig/ui/palette.rb

@@ -1,11 +1,17 @@
 # frozen_string_literal: true
 
 module Riffer::Rig::UI::Palette
-  PINK = [255, 106, 193].freeze
-  MAGENTA = [192, 76, 253].freeze
-  PURPLE = [122, 92, 255].freeze
-  BLUE = [77, 124, 255].freeze
-  CYAN = [45, 226, 230].freeze
-  GREY = [138, 139, 154].freeze
-  RED = [255, 92, 122].freeze
+  PINK = [255, 106, 193].freeze #: Array[Integer]
+
+  MAGENTA = [192, 76, 253].freeze #: Array[Integer]
+
+  PURPLE = [122, 92, 255].freeze #: Array[Integer]
+
+  BLUE = [77, 124, 255].freeze #: Array[Integer]
+
+  CYAN = [45, 226, 230].freeze #: Array[Integer]
+
+  GREY = [138, 139, 154].freeze #: Array[Integer]
+
+  RED = [255, 92, 122].freeze #: Array[Integer]
 end

data/lib/riffer/rig/ui/renderer.rb

@@ -3,8 +3,18 @@
 require 'json'
 
 class Riffer::Rig::UI::Renderer
-  RESULT_PREVIEW_LIMIT = 200
-
+  RESULT_PREVIEW_LIMIT = 200 #: Integer
+
+  # @rbs @io: untyped
+  # @rbs @theme: Riffer::Rig::UI::Theme
+  # @rbs @tally: Riffer::Rig::TokenTally?
+  # @rbs @smoother: Riffer::Rig::UI::Smoother | PassThroughSmoother?
+
+  # @rbs io: untyped
+  # @rbs ?theme: Riffer::Rig::UI::Theme
+  # @rbs ?tally: Riffer::Rig::TokenTally?
+  # @rbs ?smoother: Riffer::Rig::UI::Smoother | PassThroughSmoother?
+  # @rbs return: void
   def initialize(io: $stdout, theme: Riffer::Rig::UI::Theme.for(io), tally: nil, smoother: nil)
     @io = io
     @theme = theme
@@ -12,6 +22,8 @@ class Riffer::Rig::UI::Renderer
     @smoother = smoother
   end
 
+  # @rbs event: Riffer::StreamEvents::Base
+  # @rbs return: void
   def render(event)
     case event
     when Riffer::StreamEvents::TextDelta
@@ -31,6 +43,8 @@ class Riffer::Rig::UI::Renderer
     end
   end
 
+  # @rbs message: Riffer::Messages::Base
+  # @rbs return: void
   def render_tool_result(message)
     return unless message.is_a?(Riffer::Messages::Tool)
 
@@ -40,46 +54,61 @@ class Riffer::Rig::UI::Renderer
 
   private
 
+  # @rbs return: Riffer::Rig::UI::Smoother | PassThroughSmoother
   def smoother
     @smoother || PassThroughSmoother.new(@io)
   end
 
-  # Stand-in when no smoother is injected, so a bare Renderer still prints
+  # Stand-in when no smoother is injected, so a bare Riffer::Rig::UI::Renderer still prints
   # synchronously.
   class PassThroughSmoother
+    # @rbs @io: untyped
+
+    # @rbs io: untyped
+    # @rbs return: void
     def initialize(io) = @io = io
 
+    # @rbs content: String
+    # @rbs return: self
     def <<(content)
       @io.print(content)
       @io.flush
       self
     end
 
+    # @rbs return: nil
     def drain = nil
 
+    # @rbs return: nil
     def finish = nil
   end
 
+  # @rbs return: void
   def drain_smoother
     smoother.drain
   end
 
+  # @rbs usage: Riffer::Providers::TokenUsage
+  # @rbs return: void
   def render_token_usage(usage)
-    return unless @tally
+    tally = @tally
+    return unless tally
 
-    @tally.add(usage)
+    tally.add(usage)
 
     parts = ["↑#{usage.input_tokens}", "↓#{usage.output_tokens}"]
     parts << "cache_write:#{usage.cache_write_tokens}" if usage.cache_write_tokens&.positive?
     parts << "cache_read:#{usage.cache_read_tokens}" if usage.cache_read_tokens&.positive?
 
-    session_parts = ["session #{@tally.total_tokens} tok"]
-    cost = @tally.estimated_cost
+    session_parts = ["session #{tally.total_tokens} tok"]
+    cost = tally.estimated_cost
     session_parts << format('~$%.4f', cost) if cost
 
     @io.puts("\n#{@theme.dim("#{parts.join(' · ')}   #{session_parts.join(' · ')}")}")
   end
 
+  # @rbs arguments: String
+  # @rbs return: String
   def format_arguments(arguments)
     parsed = JSON.parse(arguments)
     parsed.map { |key, value| "#{key}: #{value.inspect}" }.join(', ')
@@ -87,6 +116,8 @@ class Riffer::Rig::UI::Renderer
     arguments
   end
 
+  # @rbs content: String
+  # @rbs return: String
   def preview(content)
     first_line = content.to_s.lines.first.to_s.chomp
     return first_line if first_line.length <= RESULT_PREVIEW_LIMIT

data/lib/riffer/rig/ui/smoother.rb

@@ -4,7 +4,7 @@
 # typing. On a non-TTY output it is transparent: writes pass through
 # synchronously and no thread ever runs.
 class Riffer::Rig::UI::Smoother
-  TICK_SECONDS = 1.0 / 60.0
+  TICK_SECONDS = 1.0 / 60.0 #: Float
 
   # A frame removes only a sixtieth of the remaining backlog — an exponential
   # decay whose tail keeps text flowing for a second or more, so the reveal
@@ -12,9 +12,24 @@ class Riffer::Rig::UI::Smoother
   # releases so the effective rate can settle at the provider's throughput;
   # the floor is fractional (10 chars/s) so it can't over-drain a backlog
   # that's trickling in slower than 60 chars/s.
-  BACKLOG_FRACTION_PER_TICK = Rational(1, 60)
-  MIN_CHARS_PER_TICK = Rational(1, 6)
+  #
+  BACKLOG_FRACTION_PER_TICK = Rational(1, 60) #: Rational
 
+  MIN_CHARS_PER_TICK = Rational(1, 6) #: Rational
+
+  # @rbs @io: untyped
+  # @rbs @theme: Riffer::Rig::UI::Theme
+  # @rbs @clock: singleton(Kernel)
+  # @rbs @backlog: String
+  # @rbs @carry: Rational
+  # @rbs @mutex: Mutex
+  # @rbs @thread: Thread?
+  # @rbs @stop: bool
+
+  # @rbs io: untyped
+  # @rbs ?theme: Riffer::Rig::UI::Theme
+  # @rbs clock: singleton(Kernel)
+  # @rbs return: void
   def initialize(io: $stdout, theme: Riffer::Rig::UI::Theme.for(io), clock: Kernel)
     @io = io
     @theme = theme
@@ -26,6 +41,7 @@ class Riffer::Rig::UI::Smoother
     @stop = false
   end
 
+  # @rbs return: void
   def start
     return unless enabled?
     return if @thread
@@ -39,6 +55,8 @@ class Riffer::Rig::UI::Smoother
     end
   end
 
+  # @rbs content: String
+  # @rbs return: self
   def <<(content)
     if enabled?
       @mutex.synchronize { @backlog << content }
@@ -50,6 +68,8 @@ class Riffer::Rig::UI::Smoother
   end
 
   # The write sits inside the mutex so a concurrent tick can't reorder a drain.
+  #
+  # @rbs return: void
   def tick
     @mutex.synchronize do
       return if @backlog.empty?
@@ -65,6 +85,8 @@ class Riffer::Rig::UI::Smoother
   end
 
   # Called before non-delta output so printed order matches stream order.
+  #
+  # @rbs return: void
   def drain
     @mutex.synchronize do
       return if @backlog.empty?
@@ -75,10 +97,13 @@ class Riffer::Rig::UI::Smoother
   end
 
   # Idempotent: the REPL's ensure path runs it even after a happy-path finish.
+  #
+  # @rbs return: void
   def finish
-    if @thread
+    thread = @thread
+    if thread
       @stop = true
-      @thread.join
+      thread.join
       @thread = nil
     end
     drain
@@ -86,6 +111,7 @@ class Riffer::Rig::UI::Smoother
 
   private
 
+  # @rbs return: bool
   def enabled?
     @theme.enabled && @io.respond_to?(:tty?) && @io.tty?
   end

data/lib/riffer/rig/ui/theme.rb

@@ -2,43 +2,74 @@
 
 # +enabled+ gates every escape so the same code path emits plain, escape-free
 # text when piped or tested.
-Riffer::Rig::UI::Theme = Data.define(:enabled)
-
-# Behaviour lives in a reopened class (rather than the `Data.define` block) so
-# the type checker can analyse the methods.
 class Riffer::Rig::UI::Theme
+  # @rbs @enabled: bool
+
+  # @rbs return: bool
+  # @dynamic enabled
+  attr_reader :enabled #: bool
+
+  # @rbs enabled: bool
+  # @rbs return: void
+  def initialize(enabled:)
+    @enabled = enabled
+  end
+
+  # @rbs io: untyped
+  # @rbs return: Riffer::Rig::UI::Theme
   def self.for(io)
     new(enabled: io.respond_to?(:tty?) && io.tty? && !ENV.key?('NO_COLOR'))
   end
 
+  # @rbs text: String
+  # @rbs rgb: Array[Integer]
+  # @rbs return: String
   def paint(text, rgb)
-    return text.to_s unless enabled
+    return text unless enabled
 
     "\e[38;2;#{rgb[0]};#{rgb[1]};#{rgb[2]}m#{text}\e[0m"
   end
 
+  # @rbs text: String
+  # @rbs return: String
   def pink(text) = paint(text, Riffer::Rig::UI::Palette::PINK)
 
+  # @rbs text: String
+  # @rbs return: String
   def magenta(text) = paint(text, Riffer::Rig::UI::Palette::MAGENTA)
 
+  # @rbs text: String
+  # @rbs return: String
   def purple(text) = paint(text, Riffer::Rig::UI::Palette::PURPLE)
 
+  # @rbs text: String
+  # @rbs return: String
   def blue(text) = paint(text, Riffer::Rig::UI::Palette::BLUE)
 
+  # @rbs text: String
+  # @rbs return: String
   def cyan(text) = paint(text, Riffer::Rig::UI::Palette::CYAN)
 
+  # @rbs text: String
+  # @rbs return: String
   def grey(text) = paint(text, Riffer::Rig::UI::Palette::GREY)
 
+  # @rbs text: String
+  # @rbs return: String
   def red(text) = paint(text, Riffer::Rig::UI::Palette::RED)
 
+  # @rbs text: String
+  # @rbs return: String
   def dim(text)
-    return text.to_s unless enabled
+    return text unless enabled
 
     "\e[2m#{text}\e[0m"
   end
 
+  # @rbs text: String
+  # @rbs return: String
   def bold(text)
-    return text.to_s unless enabled
+    return text unless enabled
 
     "\e[1m#{text}\e[0m"
   end

data/lib/riffer/rig/version.rb

@@ -2,6 +2,6 @@
 
 module Riffer
   module Rig
-    VERSION = '0.2.0'
+    VERSION = '0.3.0'
   end
 end

data/sig/generated/riffer/rig/cli.rbs

@@ -0,0 +1,41 @@
+# Generated from lib/riffer/rig/cli.rb with RBS::Inline
+
+module Riffer::Rig::CLI
+  PROVIDER_URLS: Hash[String, String]
+
+  # @rbs output: untyped
+  # @rbs input: untyped
+  # @rbs return: Integer
+  def start: (?output: untyped, ?input: untyped) -> Integer
+
+  private
+
+  # @rbs provider: String?
+  # @rbs api_key: String
+  # @rbs return: void
+  def configure_provider: (String? provider, String api_key) -> void
+
+  # @rbs provider: String?
+  # @rbs theme: Riffer::Rig::UI::Theme
+  # @rbs output: untyped
+  # @rbs input: untyped
+  # @rbs return: String?
+  def onboard: (String? provider, Riffer::Rig::UI::Theme theme, output: untyped, input: untyped) -> String?
+
+  # @rbs provider: String?
+  # @rbs return: String
+  def env_var_for: (String? provider) -> String
+
+  # @rbs input: untyped
+  # @rbs return: String?
+  def read_secret: (untyped input) -> String?
+
+  # @rbs theme: Riffer::Rig::UI::Theme
+  # @rbs animator: Riffer::Rig::UI::Animator
+  # @rbs model: String
+  # @rbs return: void
+  def reveal_banner: (Riffer::Rig::UI::Theme theme, Riffer::Rig::UI::Animator animator, String model) -> void
+
+  # @rbs return: String
+  def count_skills: () -> String
+end

data/sig/generated/riffer/rig/coding_agent.rbs

@@ -0,0 +1,9 @@
+# Generated from lib/riffer/rig/coding_agent.rb with RBS::Inline
+
+class Riffer::Rig::CodingAgent < Riffer::Agent
+  GLOBAL_AGENTS_FILE: String
+
+  GLOBAL_SKILLS_DIR: String
+
+  PROJECT_SKILLS_DIR: ^() -> String
+end

data/sig/generated/riffer/rig/credentials.rbs

@@ -0,0 +1,55 @@
+# Generated from lib/riffer/rig/credentials.rb with RBS::Inline
+
+# Reads and writes API keys for each supported provider in
+# <tt>~/.riffer/auth.json</tt>.
+#
+# Keys are stored under the provider name, e.g.:
+#
+#   {
+#     "anthropic": "sk-ant-...",
+#     "openai": "sk-...",
+#     "gemini": "...",
+#     "openrouter": "sk-or-..."
+#   }
+#
+# The environment variable checked per provider:
+#
+#   anthropic  → ANTHROPIC_API_KEY
+#   openai     → OPENAI_API_KEY
+#   gemini     → GEMINI_API_KEY
+#   openrouter → OPENROUTER_API_KEY
+module Riffer::Rig::Credentials
+  PATH: String
+
+  PROVIDER_ENV_VARS: Hash[String, String]
+
+  # Returns the API key for +provider+, checking the environment variable first,
+  # then the stored file. Returns +nil+ if no key is available.
+  #
+  # @rbs provider: String?
+  # @rbs path: String
+  # @rbs return: String?
+  def api_key_for: (String? provider, ?path: String) -> String?
+
+  # Saves an API key for +provider+ to the auth file with 0600 permissions.
+  #
+  # @rbs provider: String
+  # @rbs key: String
+  # @rbs path: String
+  # @rbs return: String
+  def save_api_key: (String provider, String key, ?path: String) -> String
+
+  private
+
+  # @rbs provider: String?
+  # @rbs path: String
+  # @rbs return: String?
+  def key_from_file: (String? provider, String path) -> String?
+
+  # The parsed auth file, or an empty hash when the file is absent or
+  # malformed.
+  #
+  # @rbs path: String
+  # @rbs return: Hash[String, untyped]
+  def read: (String path) -> Hash[String, untyped]
+end