ruby_event_store-cli 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3cc76bc96f8012d2bdfaa641285adc472b2b10d6478b7e357acfafb6437bc4ac
+  data.tar.gz: 72784ab8ca2775dd942881df73f876b6a909aabebf5694ab94e7a3fe89c1628c
+SHA512:
+  metadata.gz: 9863ab71a7a826037c01055ec8e548cfbb1ab94104d592dccda9a15013ca5df7096daa46ef7cb9859a3c4d009d85ec65b141acda505570117afb91e6c4448fb4
+  data.tar.gz: b76082eb5ad9e552a22187d357298f5f7e1fbc83a7b452250333da110f9a1a5c4c2ce5d358dcc37f540b5f9692f37417b15f7349779ac6819664883a91f9e2ee

data/README.md

@@ -0,0 +1,98 @@
+# ruby_event_store-cli
+
+Command-line interface for inspecting a RubyEventStore event store without needing `rails console`.
+
+## Installation
+
+Add to your application's Gemfile:
+
+```ruby
+gem "ruby_event_store-cli"
+```
+
+The `res` executable will be available in your project. Run all commands from your Rails app root directory — the CLI autodetects `config/environment.rb` and loads your environment.
+
+## Commands
+
+### Stream
+
+```bash
+# List events in a stream (default: last 50)
+bundle exec res stream events MyStream
+bundle exec res stream events MyStream --limit 20
+bundle exec res stream events MyStream --format json
+bundle exec res stream events MyStream --type OrderPlaced
+bundle exec res stream events MyStream --after 2024-01-01T00:00:00Z
+bundle exec res stream events MyStream --before 2024-03-01T00:00:00Z
+bundle exec res stream events MyStream --from <event_uuid>
+
+# Follow a stream for new events (Ctrl+C to stop)
+bundle exec res stream events MyStream --follow
+bundle exec res stream events MyStream -f
+
+# Show stream summary
+bundle exec res stream show MyStream
+```
+
+### Event
+
+```bash
+# Show full event details (data, metadata, timestamps)
+bundle exec res event show <uuid>
+
+# List all streams an event belongs to
+bundle exec res event streams <uuid>
+```
+
+### Search
+
+Search events across all streams or within a specific one:
+
+```bash
+bundle exec res search --type OrderPlaced
+bundle exec res search --type OrderPlaced --limit 100
+bundle exec res search --type OrderPlaced --after 2024-01-01T00:00:00Z
+bundle exec res search --stream Orders --type OrderPlaced
+bundle exec res search --format json | jq '.[].data'
+```
+
+### Trace
+
+Display the causal tree for a correlation ID — all events triggered by a single request, in order:
+
+```bash
+bundle exec res trace <correlation_id>
+```
+
+### Stats
+
+```bash
+# Total event count and unique event types
+bundle exec res stats
+
+# Stats for a specific stream
+bundle exec res stats --stream Orders
+```
+
+### Watch
+
+Live view of new events as they arrive, grouped by bounded context (namespace prefix of the class name):
+
+```bash
+# Watch all new events (Ctrl+C to stop)
+bundle exec res watch
+
+# Filter to specific namespace(s)
+bundle exec res watch --namespace Ordering
+bundle exec res watch --namespace Ordering,Payments
+
+# Watch events from a point in time
+bundle exec res watch --since 2024-01-15T10:00:00Z
+
+# Adjust polling interval and max events shown per namespace
+bundle exec res watch --interval 2 --limit 20
+```
+
+## License
+
+MIT

data/bin/res

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "dry/cli"
+require_relative "../lib/ruby_event_store/cli"
+require_relative "../lib/ruby_event_store/cli/commands"
+
+env_file = File.expand_path("config/environment.rb")
+
+abort "Could not find config/environment.rb. Run `res` from the root of your Rails application." unless File.exist?(env_file)
+
+require env_file
+
+abort <<~MSG unless defined?(Rails) && Rails.configuration.respond_to?(:event_store)
+  Could not find event store instance after loading config/environment.rb.
+
+  Expected Rails.configuration.event_store to be set (standard RES setup).
+MSG
+
+Dry::CLI.new(RubyEventStore::CLI::Commands).call

data/lib/ruby_event_store/cli/commands/base.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+
+module RubyEventStore
+  module CLI
+    module Commands
+      class Base < Dry::CLI::Command
+        private
+
+        def event_store
+          Rails.configuration.event_store
+        end
+      end
+    end
+  end
+end

data/lib/ruby_event_store/cli/commands/event_show.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+require "json"
+require_relative "base"
+
+module RubyEventStore
+  module CLI
+    module Commands
+      class EventShow < Base
+        desc "Print full event details including data, metadata, and timestamps"
+
+        argument :event_id, required: true, desc: "Event ID (UUID)"
+
+        def call(event_id:, **)
+          event = event_store.read.event!(event_id)
+          print_event(event)
+        rescue RubyEventStore::EventNotFound
+          warn "Event not found: #{event_id}"
+          exit 1
+        rescue => e
+          warn e.message
+          exit 1
+        end
+
+        private
+
+        def print_event(event)
+          puts "Event ID:   #{event.event_id}"
+          puts "Type:       #{event.event_type}"
+          puts "Timestamp:  #{event.timestamp.iso8601(3)}"
+          puts "Valid at:   #{event.valid_at.iso8601(3)}"
+          puts "Data:       #{JSON.pretty_generate(event.data)}"
+          puts "Metadata:   #{JSON.pretty_generate(event.metadata.to_h)}"
+        end
+      end
+    end
+  end
+end

data/lib/ruby_event_store/cli/commands/event_streams.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+require_relative "base"
+
+module RubyEventStore
+  module CLI
+    module Commands
+      class EventStreams < Base
+        desc "List all streams the event has been published or linked to"
+
+        argument :event_id, required: true, desc: "Event ID (UUID)"
+
+        def call(event_id:, **)
+          streams = streams_of(event_id)
+          streams.empty? ? puts("(no streams — event not found or not linked to any stream)") : streams.each { |stream| puts stream.name }
+        rescue => e
+          warn e.message
+          exit 1
+        end
+
+        private
+
+        def streams_of(event_id)
+          event_store.streams_of(event_id)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_event_store/cli/commands/search.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+require_relative "base"
+require_relative "../event_renderer"
+require_relative "../read_events"
+
+module RubyEventStore
+  module CLI
+    module Commands
+      class Search < Base
+        include EventRenderer
+
+        desc "Search events across all streams by type, time range, or stream name"
+
+        option :type, desc: "Filter by event type (class name)"
+        option :after, desc: "Filter events newer than timestamp (ISO8601)"
+        option :before, desc: "Filter events older than timestamp (ISO8601)"
+        option :stream, desc: "Limit search to a specific stream"
+        option :limit, type: :integer, default: 50, desc: "Max number of events (default: 50)"
+        option :format, default: "table", values: %w[table json], desc: "Output format"
+
+        def call(limit:, format:, type: nil, after: nil, before: nil, stream: nil, **)
+          specification = stream ? event_store.read.stream(stream) : event_store.read
+          events = ReadEvents.of(specification, type: type, after: after, before: before, limit: limit)
+          render(events, format: format)
+        rescue => e
+          warn e.message
+          exit 1
+        end
+      end
+    end
+  end
+end

data/lib/ruby_event_store/cli/commands/stats.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+require_relative "base"
+
+module RubyEventStore
+  module CLI
+    module Commands
+      class Stats < Base
+        desc "Show total event count and unique event types. Use --stream for per-stream stats."
+
+        option :stream, desc: "Show stats for a specific stream"
+
+        def call(stream: nil, **)
+          specification = stream ? event_store.read.stream(stream) : event_store.read
+          print_stats(specification, stream: stream)
+        rescue => e
+          warn e.message
+          exit 1
+        end
+
+        private
+
+        def print_stats(specification, stream:)
+          puts "Stream:  #{stream}" if stream
+          puts "Events:  #{specification.count}"
+          print_event_types(specification)
+        end
+
+        def print_event_types(specification)
+          types = specification.map(&:event_type).uniq.sort
+          return if types.empty?
+          puts "\nEvent types:"
+          types.each { |t| puts "  #{t}" }
+        end
+      end
+    end
+  end
+end

data/lib/ruby_event_store/cli/commands/stream_events.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+require_relative "base"
+require_relative "../event_renderer"
+require_relative "../read_events"
+
+module RubyEventStore
+  module CLI
+    module Commands
+      class StreamEvents < Base
+        include EventRenderer
+        desc "Print events from a stream. Supports filtering by type, time, and position. Use --follow/-f to tail live."
+
+        argument :stream_name, required: true, desc: "Stream name"
+        option :limit, type: :integer, default: 50, desc: "Max number of events (default: 50)"
+        option :format, default: "table", values: %w[table json], desc: "Output format"
+        option :type, desc: "Filter by event type (class name)"
+        option :after, desc: "Filter events newer than timestamp (ISO8601)"
+        option :before, desc: "Filter events older than timestamp (ISO8601)"
+        option :from, desc: "Start reading from event ID (exclusive)"
+        option :follow, type: :boolean, default: false, aliases: ["-f"], desc: "Watch for new events (Ctrl+C to stop)"
+
+        def call(stream_name:, limit:, format:, type: nil, after: nil, before: nil, from: nil, follow: false, **)
+          specification = event_store.read.stream(stream_name)
+          events = ReadEvents.of(specification, type: type, after: after, before: before, from: from, limit: limit)
+          render(events, format: format)
+          tail(stream_name, last_id: events.last&.event_id, type: type, format: format) if follow
+        rescue Interrupt
+          exit 0
+        rescue => e
+          warn e.message
+          exit 1
+        end
+
+        private
+
+        def tail(stream_name, last_id:, type:, format:)
+          loop do
+            sleep 1
+            events = ReadEvents.of(event_store.read.stream(stream_name), type: type, from: last_id)
+            next if events.empty?
+            render(events, format: format)
+            last_id = events.last.event_id
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_event_store/cli/commands/stream_show.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+require_relative "base"
+
+module RubyEventStore
+  module CLI
+    module Commands
+      class StreamShow < Base
+        desc "Show event count, version, and first/last event for a stream"
+
+        argument :stream_name, required: true, desc: "Stream name"
+
+        def call(stream_name:, **)
+          specification = event_store.read.stream(stream_name)
+          print_stream(stream_name, specification)
+        rescue => e
+          warn e.message
+          exit 1
+        end
+
+        private
+
+        def print_stream(stream_name, specification)
+          count = specification.count
+          puts "Stream:  #{stream_name}"
+          puts "Events:  #{count}"
+          return if count.zero?
+          first = specification.first
+          last = specification.last
+          puts "Version: #{count - 1}"
+          puts "First:   #{first.timestamp.iso8601(3)} (#{first.event_type})"
+          puts "Last:    #{last.timestamp.iso8601(3)} (#{last.event_type})"
+        end
+      end
+    end
+  end
+end

data/lib/ruby_event_store/cli/commands/trace.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+require_relative "base"
+
+module RubyEventStore
+  module CLI
+    module Commands
+      class Trace < Base
+        desc "Print the causation tree for all events sharing a correlation ID"
+
+        argument :correlation_id, required: true, desc: "Correlation ID (UUID)"
+
+        def call(correlation_id:, **)
+          events = events_for(correlation_id)
+          if events.empty?
+            puts "(no events found for correlation ID #{correlation_id})"
+            return
+          end
+          print_causation_tree(events)
+        rescue => e
+          warn e.message
+          exit 1
+        end
+
+        private
+
+        def events_for(correlation_id)
+          event_store.read.stream("$by_correlation_id_#{correlation_id}").to_a
+        end
+
+        def print_causation_tree(events)
+          causation = events.group_by { |e| e.metadata[:causation_id] }
+          roots = root_events(events)
+          roots.each { |e| print_tree(e, causation, "", true, roots.last == e) }
+        end
+
+        def root_events(events)
+          event_ids = events.map(&:event_id).to_set
+          events.reject { |e| event_ids.include?(e.metadata[:causation_id]) }
+        end
+
+        def print_tree(event, by_causation, prefix, root, last)
+          connector = root ? "" : (last ? "└── " : "├── ")
+          puts "#{prefix}#{connector}#{event.event_type} [#{event.event_id}]"
+          children = by_causation[event.event_id] || []
+          child_prefix = root ? prefix : prefix + (last ? "    " : "│   ")
+          children.each_with_index do |child, i|
+            print_tree(child, by_causation, child_prefix, false, i == children.size - 1)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_event_store/cli/commands/watch.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+require_relative "base"
+
+module RubyEventStore
+  module CLI
+    module Commands
+      class Watch < Base
+        desc "Watch new events live, grouped by bounded context"
+
+        option :namespace, desc: "Filter by namespace(s), comma-separated (e.g. Ordering,Payments)"
+        option :since, desc: "Watch events since timestamp (ISO8601, default: now)"
+        option :limit, type: :integer, default: 50, desc: "Max events shown per namespace (default: 50)"
+        option :interval, type: :integer, default: 1, desc: "Refresh interval in seconds (default: 1)"
+
+        def call(namespace: nil, since: nil, limit:, interval:, **)
+          started_at = since ? Time.parse(since) : Time.now
+          namespaces = namespace&.split(",")&.map(&:strip)
+          watch(since: started_at, namespaces: namespaces, limit: limit.to_i, interval: interval.to_i)
+        rescue Interrupt
+          show_cursor
+          exit 0
+        rescue => e
+          show_cursor
+          warn e.message
+          exit 1
+        end
+
+        private
+
+        def watch(since:, namespaces:, limit:, interval:)
+          hide_cursor
+          loop do
+            events = grouped_events(since: since, namespaces: namespaces)
+            render(events, limit: limit, since: since)
+            sleep interval
+          end
+        end
+
+        def grouped_events(since:, namespaces:)
+          events = events_since(since)
+          events = filter_by_namespaces(events, namespaces)
+          group_by_namespace(events)
+        end
+
+        def events_since(since)
+          event_store.read.newer_than(since).map do |e|
+            { event_id: e.event_id, type: e.event_type, timestamp: e.timestamp }
+          end
+        end
+
+        def filter_by_namespaces(events, namespaces)
+          return events unless namespaces
+          events.select { |e| namespaces.include?(namespace(e[:type])) }
+        end
+
+        def group_by_namespace(events)
+          events.group_by { |e| namespace(e[:type]) }.sort
+        end
+
+        def render(grouped, limit:, since:)
+          lines = grouped.empty? ? [empty_message(since)] : event_lines(grouped, limit)
+          lines << footer(since)
+          clear_screen
+          puts lines.join("\n")
+        end
+
+        def event_lines(grouped, limit)
+          grouped.flat_map do |ns, ns_events|
+            [
+              bold("#{ns} (#{ns_events.size} events)"),
+              *ns_events.last(limit).map { |e| format_event(e) },
+              ""
+            ]
+          end
+        end
+
+        def format_event(e)
+          "  #{pad(short_type(e[:type]), 30)} #{e[:timestamp].strftime("%H:%M:%S")}  #{e[:event_id]}"
+        end
+
+        def empty_message(since)
+          dim("No events yet — waiting since #{since.strftime("%H:%M:%S")}")
+        end
+
+        def footer(since)
+          dim("Watching since #{since.strftime("%H:%M:%S")} — Press Ctrl+C to exit")
+        end
+
+        def namespace(type)
+          type.include?("::") ? type.split("::").first : "Other"
+        end
+
+        def short_type(type)
+          type.split("::").last
+        end
+
+        def pad(str, width)
+          str.ljust(width)[0, width]
+        end
+
+        def clear_screen
+          system("clear")
+        end
+
+        def hide_cursor
+          print "\e[?25l"
+        end
+
+        def show_cursor
+          print "\e[?25h"
+        end
+
+        def bold(str)
+          "\e[1m#{str}\e[0m"
+        end
+
+        def dim(str)
+          "\e[2m#{str}\e[0m"
+        end
+      end
+    end
+  end
+end

data/lib/ruby_event_store/cli/commands.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+require_relative "commands/base"
+require_relative "commands/stream_events"
+require_relative "commands/stream_show"
+require_relative "commands/event_show"
+require_relative "commands/event_streams"
+require_relative "commands/trace"
+require_relative "commands/search"
+require_relative "commands/stats"
+require_relative "commands/watch"
+
+module RubyEventStore
+  module CLI
+    module Commands
+      extend Dry::CLI::Registry
+
+      register "stream", Class.new(Dry::CLI::Command) {
+        desc "Inspect a stream"
+        def call(**) = warn "Usage: res stream SUBCOMMAND\n\nSubcommands: events, show\n\nRun `res stream --help` for details."
+      }
+      register "stream events", StreamEvents
+      register "stream show", StreamShow
+
+      register "event", Class.new(Dry::CLI::Command) {
+        desc "Inspect an event"
+        def call(**) = warn "Usage: res event SUBCOMMAND\n\nSubcommands: show, streams\n\nRun `res event --help` for details."
+      }
+      register "event show", EventShow
+      register "event streams", EventStreams
+      register "trace", Trace
+      register "search", Search
+      register "stats", Stats
+      register "watch", Watch
+    end
+  end
+end

data/lib/ruby_event_store/cli/event_renderer.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RubyEventStore
+  module CLI
+    module EventRenderer
+      def render(events, format:)
+        case format
+        when "json" then render_json(events)
+        when "table" then render_table(events)
+        end
+      end
+
+      def render_json(events)
+        puts JSON.pretty_generate(events.map { |e|
+          { event_id: e.event_id, event_type: e.event_type, data: e.data,
+            metadata: e.metadata.to_h, timestamp: e.timestamp.iso8601(3) }
+        })
+      end
+
+      def render_table(events)
+        return puts "(no events)" if events.empty?
+
+        puts "%-36s  %-40s  %s" % ["EVENT ID", "TYPE", "TIMESTAMP"]
+        puts "-" * 90
+        events.each do |e|
+          puts "%-36s  %-40s  %s" % [e.event_id, e.event_type, e.timestamp.iso8601(3)]
+        end
+        puts "\n#{events.size} event(s)"
+      end
+    end
+  end
+end

data/lib/ruby_event_store/cli/read_events.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module RubyEventStore
+  module CLI
+    class ReadEvents
+      def self.of(specification, type: nil, after: nil, before: nil, from: nil, limit: nil)
+        specification = specification.of_type(resolve_type(type))    if type
+        specification = specification.newer_than(Time.parse(after))  if after
+        specification = specification.older_than(Time.parse(before)) if before
+        specification = specification.from(from)                     if from
+        limit ? specification.limit(limit.to_i).to_a : specification.to_a
+      end
+
+      def self.resolve_type(name)
+        Object.const_get(name)
+      rescue NameError
+        raise "Unknown event type: #{name}"
+      end
+    end
+  end
+end

data/lib/ruby_event_store/cli/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RubyEventStore
+  module CLI
+    VERSION = "0.1.0"
+  end
+end

data/lib/ruby_event_store/cli.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "cli/version"
+
+module RubyEventStore
+  module CLI
+  end
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: ruby_event_store-cli
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Arkency
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: ruby_event_store
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+email: dev@arkency.com
+executables:
+- res
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- README.md
+- bin/res
+- lib/ruby_event_store/cli.rb
+- lib/ruby_event_store/cli/commands.rb
+- lib/ruby_event_store/cli/commands/base.rb
+- lib/ruby_event_store/cli/commands/event_show.rb
+- lib/ruby_event_store/cli/commands/event_streams.rb
+- lib/ruby_event_store/cli/commands/search.rb
+- lib/ruby_event_store/cli/commands/stats.rb
+- lib/ruby_event_store/cli/commands/stream_events.rb
+- lib/ruby_event_store/cli/commands/stream_show.rb
+- lib/ruby_event_store/cli/commands/trace.rb
+- lib/ruby_event_store/cli/commands/watch.rb
+- lib/ruby_event_store/cli/event_renderer.rb
+- lib/ruby_event_store/cli/read_events.rb
+- lib/ruby_event_store/cli/version.rb
+homepage: https://railseventstore.org
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://railseventstore.org
+  source_code_uri: https://github.com/RailsEventStore/rails_event_store
+  bug_tracker_uri: https://github.com/RailsEventStore/rails_event_store/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.1
+specification_version: 4
+summary: Command-line interface for Ruby Event Store
+test_files: []