first usable version (disclaimer: 100% vibe-coded)

exe/rat

···
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# rat – Ruby ATProto Tool
+#
+# Simple CLI for Bluesky AT Protocol using:
+# - Minisky  (XRPC client)
+# - Skyfall  (firehose / Jetstream streaming)
+# - DIDKit   (DID / handle resolution)
+#
+# Usage:
+#   rat fetch at://<did-or-handle>/<collection-nsid>/<rkey>
+#   rat stream <relay.host> [-j|--jetstream] [-r|--cursor CURSOR] \
+#                [-d|--did DID,...] [-c|--collection NSID,...]
+#   rat resolve <did-or-handle>
+#   rat help | --help
+#   rat version | --version
+
+require 'optparse'
+require 'json'
+require 'time'
+require 'uri'
+
+require 'minisky'
+require 'skyfall'
+require 'didkit'   # defines DIDKit::DID and top-level DID alias
+
+VERSION = '0.0.1'
+
+DID_REGEX       = /\Adid:[a-z0-9]+:[a-zA-Z0-9.\-_:]+\z/
+DOMAIN_REGEX    = /\A[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+\z/i
+HOST_PORT_REGEX = /\A#{DOMAIN_REGEX.source}(?::\d+)?\z/i
+
+def global_help
+  <<~HELP
+    rat #{VERSION}
+
+    Usage:
+      rat fetch at://<did-or-handle>/<collection-nsid>/<rkey>
+      rat stream <relay.host> [options]
+      rat resolve <did-or-handle>
+      rat help | --help
+      rat version | --version
+
+    Commands:
+      fetch     Fetch a single record given its at:// URI
+      stream    Stream commit events from a relay / PDS firehose
+      resolve   Resolve a DID or @handle using DIDKit
+      help      Show this help
+      version   Show version
+
+    Stream options:
+      -j, --jetstream                  Use Skyfall::Jetstream (JSON)
+                                       (uses Jetstream wanted_dids / wanted_collections
+                                       when -d/-c are provided)
+      -r, --cursor CURSOR              Start from cursor (seq or time_us)
+      -d, --did DID[,DID...]           Filter only events from given DID(s)
+                                       (can be passed multiple times)
+      -c, --collection NSID[,NSID...]  Filter only events of given collection(s)
+                                       (can be passed multiple times)
+  HELP
+end
+
+def abort_with_help(message = nil)
+  warn "Error: #{message}" if message
+  warn
+  warn global_help
+  exit 1
+end
+
+def valid_did?(s)
+  DID_REGEX.match?(s)
+end
+
+def valid_handle?(s)
+  DOMAIN_REGEX.match?(s)
+end
+
+def valid_nsid?(s)
+  # NSIDs look like domain names (reverse DNS), so reuse DOMAIN_REGEX
+  DOMAIN_REGEX.match?(s)
+end
+
+def validate_handle!(s, context: 'handle')
+  unless valid_handle?(s)
+    abort_with_help("#{s.inspect} doesn't look like a valid #{context}")
+  end
+  s
+end
+
+def validate_did!(s)
+  unless valid_did?(s)
+    abort_with_help("#{s.inspect} doesn't look like a valid DID")
+  end
+  s
+end
+
+def validate_nsid!(nsid)
+  unless valid_nsid?(nsid)
+    abort_with_help("#{nsid.inspect} doesn't look like a valid collection NSID")
+  end
+  nsid
+end
+
+def parse_at_uri(str)
+  unless str.start_with?('at://')
+    abort_with_help("not an at:// URI: #{str.inspect}")
+  end
+
+  m = /\Aat:\/\/([^\/]+)\/([^\/]+)\/([^\/]+)\z/.match(str)
+  unless m
+    abort_with_help("invalid at:// URI: expected at://<repo>/<collection>/<rkey>")
+  end
+
+  repo, collection, rkey = m.captures
+  [repo, collection, rkey]
+end
+
+def resolve_repo_to_did_and_pds(repo_str)
+  if repo_str.start_with?('did:')
+    validate_did!(repo_str)
+    did_obj = DID.new(repo_str)
+  else
+    handle = repo_str.sub(/\A@/, '')
+    validate_handle!(handle, context: 'handle in at:// URI')
+    did_obj = DID.resolve_handle(handle)
+  end
+
+  doc = did_obj.document
+  pds_host = doc.pds_host
+  unless pds_host && !pds_host.empty?
+    abort_with_help("DID document for #{did_obj} does not contain a pds_host")
+  end
+
+  [did_obj.to_s, pds_host]
+rescue StandardError => e
+  warn "Error resolving repo #{repo_str.inspect}: #{e.class}: #{e.message}"
+  exit 1
+end
+
+def do_fetch(argv)
+  uri = argv.shift or abort_with_help("fetch requires an at:// URI")
+  unless argv.empty?
+    abort_with_help("unexpected extra arguments for fetch: #{argv.join(' ')}")
+  end
+
+  repo_str, collection, rkey = parse_at_uri(uri)
+
+  # basic validation of collection (NSID-ish)
+  validate_nsid!(collection)
+
+  did, pds_host = resolve_repo_to_did_and_pds(repo_str)
+
+  client = Minisky.new(pds_host, nil)
+  params = { repo: did, collection: collection, rkey: rkey }
+
+  begin
+    res = client.get_request('com.atproto.repo.getRecord', params)
+  rescue StandardError => e
+    warn "Error calling com.atproto.repo.getRecord: #{e.class}: #{e.message}"
+    exit 1
+  end
+
+  value = res['value']
+  if value.nil?
+    warn "Warning: response did not contain a 'value' field"
+    puts JSON.pretty_generate(res)
+  else
+    puts JSON.pretty_generate(value)
+  end
+end
+
+def do_resolve(argv)
+  target = argv.shift or abort_with_help("resolve requires a DID or handle")
+  unless argv.empty?
+    abort_with_help("unexpected extra arguments for resolve: #{argv.join(' ')}")
+  end
+
+  if target.start_with?('did:')
+    validate_did!(target)
+    begin
+      did_obj = DID.new(target)
+      doc = did_obj.document
+      json = doc.respond_to?(:json) ? doc.json : doc
+      puts did_obj.to_s
+      puts JSON.pretty_generate(json)
+    rescue StandardError => e
+      warn "Error resolving DID #{target.inspect}: #{e.class}: #{e.message}"
+      exit 1
+    end
+  else
+    handle = target.sub(/\A@/, '')
+    validate_handle!(handle)
+    begin
+      did_obj = DID.resolve_handle(handle)
+      doc = did_obj.document
+      json = doc.respond_to?(:json) ? doc.json : doc
+      puts did_obj.to_s
+      puts JSON.pretty_generate(json)
+    rescue StandardError => e
+      warn "Error resolving handle #{target.inspect}: #{e.class}: #{e.message}"
+      exit 1
+    end
+  end
+end
+
+def validate_relay_host!(host)
+  # Accept:
+  #   - bare hostname or hostname:port
+  #   - ws://host[:port]
+  #   - wss://host[:port]
+  if host =~ /\Aws:\/\//i || host =~ /\Awss:\/\//i
+    uri = URI(host)
+    if uri.path && uri.path != '' && uri.path != '/'
+      abort_with_help("relay URL must not contain a path: #{host.inspect}")
+    end
+    unless uri.host && DOMAIN_REGEX.match?(uri.host)
+      abort_with_help("invalid relay hostname in URL: #{host.inspect}")
+    end
+  else
+    unless HOST_PORT_REGEX.match?(host)
+      abort_with_help("invalid relay hostname: #{host.inspect}")
+    end
+  end
+
+  host
+rescue URI::InvalidURIError
+  abort_with_help("invalid relay URL: #{host.inspect}")
+end
+
+def parse_stream_options(argv)
+  options = {
+    use_jetstream: false,
+    cursor:        nil,
+    dids:          [],
+    collections:   []
+  }
+
+  parser = OptionParser.new do |opts|
+    opts.banner = "Usage: rat stream <relay.host> [options]"
+
+    opts.on('-j', '--jetstream', 'Use Skyfall::Jetstream (JSON)') do
+      options[:use_jetstream] = true
+    end
+
+    opts.on('-rCURSOR', '--cursor=CURSOR', 'Start from cursor (seq or time_us)') do |cursor|
+      options[:cursor] = cursor
+    end
+
+    opts.on('-dLIST', '--did=LIST',
+            'Filter only events from DID(s) (comma-separated or repeated)') do |list|
+      items = list.split(',').map(&:strip).reject(&:empty?)
+      if items.empty?
+        abort_with_help("empty argument to -d/--did")
+      end
+      options[:dids].concat(items)
+    end
+
+    opts.on('-cLIST', '--collection=LIST',
+            'Filter only events of given collection NSID(s)') do |list|
+      items = list.split(',').map(&:strip).reject(&:empty?)
+      if items.empty?
+        abort_with_help("empty argument to -c/--collection")
+      end
+      options[:collections].concat(items)
+    end
+
+    opts.on('-h', '--help', 'Show stream-specific help') do
+      puts opts
+      exit 0
+    end
+  end
+
+  remaining = []
+  begin
+    parser.order!(argv) { |nonopt| remaining << nonopt }
+  rescue OptionParser::InvalidOption, OptionParser::MissingArgument => e
+    warn "Error: #{e.message}"
+    warn parser
+    exit 1
+  end
+
+  [options, remaining]
+end
+
+def do_stream(argv)
+  options, remaining = parse_stream_options(argv)
+
+  host = remaining.shift or abort_with_help("stream requires a relay hostname")
+  validate_relay_host!(host)
+
+  unless remaining.empty?
+    abort_with_help("unexpected extra arguments for stream: #{remaining.join(' ')}")
+  end
+
+  # validate cursor (if given)
+  if options[:cursor] && options[:cursor] !~ /\A\d+\z/
+    abort_with_help("cursor must be a decimal integer, got #{options[:cursor].inspect}")
+  end
+
+  # validate DIDs
+  options[:dids].each do |did|
+    validate_did!(did)
+  end
+
+  # validate collections
+  options[:collections].each do |nsid|
+    validate_nsid!(nsid)
+  end
+
+  # Build Skyfall client
+  if options[:use_jetstream]
+    jet_opts = {}
+    jet_opts[:cursor] = options[:cursor].to_i if options[:cursor]
+
+    # Pass filters through to Jetstream server-side
+    jet_opts[:wanted_dids] = options[:dids] unless options[:dids].empty?
+    jet_opts[:wanted_collections] = options[:collections] unless options[:collections].empty?
+
+    sky = Skyfall::Jetstream.new(host, jet_opts)
+  else
+    cursor = options[:cursor]&.to_i
+    sky = Skyfall::Firehose.new(host, :subscribe_repos, cursor)
+  end
+
+  # Lifecycle logging
+  sky.on_connecting { |url| puts "Connecting to #{url}..." }
+  sky.on_connect    { puts "Connected" }
+  sky.on_disconnect { puts "Disconnected" }
+  sky.on_reconnect  { puts "Connection lost, trying to reconnect..." }
+  sky.on_timeout    { puts "Connection stalled, triggering a reconnect..." } if sky.respond_to?(:on_timeout)
+  sky.on_error      { |e| warn "ERROR: #{e}" }
+
+  # Message handler
+  sky.on_message do |msg|
+    next unless msg.type == :commit
+
+    did = if msg.respond_to?(:repo) && msg.repo
+            msg.repo
+          elsif msg.respond_to?(:did)
+            msg.did
+          else
+            nil
+          end
+
+    if !options[:dids].empty? && (!did || !options[:dids].include?(did))
+      next
+    end
+
+    ts = msg.time ? msg.time.getlocal.iso8601 : 'unknown-time'
+
+    msg.operations.each do |op|
+      # collection filter (still applied client-side, in case server doesn't)
+      if !options[:collections].empty? &&
+         !options[:collections].include?(op.collection)
+        next
+      end
+
+      line = "[#{ts}] #{did || '-'} :#{op.action} #{op.collection} #{op.rkey}"
+
+      if op.respond_to?(:raw_record) && op.raw_record && !op.raw_record.empty?
+        # compact JSON on one line
+        line << " " << JSON.generate(op.raw_record)
+      end
+
+      puts line
+    end
+  end
+
+  # Clean disconnect on Ctrl+C
+  trap('SIGINT') do
+    puts 'Disconnecting...'
+    sky.disconnect
+  end
+
+  sky.connect
+end
+
+# ---- main dispatcher ----
+
+if ARGV.empty?
+  puts global_help
+  exit 0
+end
+
+cmd = ARGV.shift
+
+case cmd
+when 'help', '--help', '-h'
+  puts global_help
+  exit 0
+when 'version', '--version'
+  puts VERSION
+  exit 0
+when 'fetch'
+  do_fetch(ARGV)
+when 'resolve'
+  do_resolve(ARGV)
+when 'stream'
+  do_stream(ARGV)
+else
+  abort_with_help("unknown command: #{cmd}")
+end

ratproto.gemspec

···
   spec.authors = ["Kuba Suder"]
   spec.email = ["[e-mail]"]
 
-  spec.summary = "TODO: Write a short summary, because RubyGems requires one."
-  spec.description = "TODO: Write a longer description or delete this line."
-  spec.homepage = "TODO: Put your gem's website or public repo URL here."
+  spec.summary = "Ruby CLI tool for accessing Bluesky API / ATProto"
+  spec.homepage = "https://ruby.sdk.blue"
 
   spec.license = "Zlib"
   spec.required_ruby_version = ">= 2.6.0"
 
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "TODO: Put your gem's public repo URL here."
-  spec.metadata["changelog_uri"] = "TODO: Put your gem's CHANGELOG.md URL here."
+  spec.metadata = {
+    "bug_tracker_uri"   => "https://tangled.org/mackuba.eu/ratproto/issues",
+    "changelog_uri"     => "https://tangled.org/mackuba.eu/ratproto/blob/master/CHANGELOG.md",
+    "source_code_uri"   => "https://tangled.org/mackuba.eu/ratproto",
+  }
 
   spec.files = Dir.chdir(__dir__) do
     Dir['*.md'] + Dir['*.txt'] + Dir['exe/*'] + Dir['lib/**/*'] + Dir['sig/**/*']
   end
 
   spec.bindir = 'exe'
+  spec.executables = ['rat']
   spec.require_paths = ['lib']
+
+  spec.add_dependency 'minisky', '>= 0.5', '< 2.0'
+  spec.add_dependency 'skyfall', '>= 0.6', '< 2.0'
+  spec.add_dependency 'didkit', '>= 0.3.1', '< 2.0'
 end