r2ui 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fd8c94c82db6c74efb8c77dba2e80155c61336aa2e2f7e0c49ada508f0ea0ddf
+  data.tar.gz: 338646823240fdbecd726268b2ef4f72388a5e7633cbdbd0eb3acd0cc143d96a
+SHA512:
+  metadata.gz: 91cc25cf40c7a4beedc55caf86f4dc13703c92c493bbadaccf326a60dea821611024f6a5f9ed8fdb8c6924e25596748c9d0948c6c35cab6291e526321b494ca5
+  data.tar.gz: 6c5f8747986ac1b5219ecfe3bc415ccac2ed79d23b107af5ec00616daac862e1e842ef030c0fbc214bba8ff7999351aa513bcda0a88528a77884ca0517bb373b

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Gavin
+
+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,79 @@
+# R2UI
+
+ActiveAdmin-style DSL for terminal dashboards. You declare resources, scopes, groupings, columns and actions; R2UI draws the tables, gauges and sparklines, and handles keys, search, sorting and folding.
+
+Pure Ruby, no runtime dependencies.
+
+```ruby
+R2UI.resource :process do
+  source { MyProbe.processes }        # any array of hashes, Data/Struct objects or models
+  refresh every: 2                    # seconds, or an ActiveSupport::Duration
+  key :pid, parent: :ppid             # identity, plus parent for tree grouping
+
+  scope :agents, default: true, &:agent
+  scope :all
+
+  group_by :agent, label: "Session"   # same value → one line, numbers summed
+  group_by :cwd, label: "Directory"
+  group_by :parent, tree: true        # tree; each node's numbers include its subtree
+
+  index do
+    column :pid, format: :id
+    column :name
+    column :cwd, format: :short_path
+    column :cpu, format: :percent, sparkline: true, sort: :desc
+    column :rss, label: "Memory", format: :bytes
+  end
+
+  filter :name, :cwd                  # what "/" free text matches
+
+  action :terminate, key: "K", confirm: true do |process|
+    Process.kill(:TERM, process.pid)
+  end
+end
+
+R2UI.dashboard do
+  row height: 15 do
+    panel :memory, span: 1 do
+      gauge :used, of: :total
+      stat :wired, :compressed, :swap_used
+      sparkline :pressure
+    end
+    panel :sessions, resource: :process, span: 2 do
+      table scope: :agents, group_by: :agent
+    end
+  end
+  row { panel :process }              # no block: the resource's full index
+end
+```
+
+## Run it
+
+```sh
+exe/r2ui examples/agents.rb              # interactive
+exe/r2ui --snapshot examples/agents.rb   # print one frame and exit
+```
+
+`examples/agents.rb` is a macOS monitor for Claude and Codex runs. It groups processes by agent session (the outermost `claude`/`codex` process, or the desktop app), by working directory, by name or as a tree. It also breaks memory down the way Activity Monitor does: app, wired and compressed memory, compression ratio, swap, swap-out and compression rates, and memory pressure.
+
+## Keys
+
+| Key | Does |
+|---|---|
+| `tab` / `shift-tab` | Focus next / previous panel |
+| `[` `]` | Previous / next scope |
+| `g` | Cycle grouping (off → each `group_by` → off) |
+| `s` / `S` | Next sort column / reverse |
+| `/` | Search: free text, or `cpu>5`, `rss>=500M`, `cwd~starseed`; `esc` clears |
+| `enter` / `space` | Fold or unfold a tree node |
+| `z` | Zoom the focused panel |
+| action keys | Run the action on the selected line (all its rows when grouped) |
+| `q` | Quit |
+
+## Formats
+
+`:text`, `:id`, `:integer`, `:number`, `:percent`, `:bytes`, `:bytes_per_sec`, `:ratio`, `:short_path`. The format decides display, alignment, how grouped lines aggregate (`:sum`, `:count` or a single shared value) and how search operands are parsed (`500M`, `5%`).
+
+## Next: active_tui
+
+A Rails engine on top of the same DSL: `ActiveTui.register Order do ... end` reads columns, scopes and associations from the model, `source` defaults to the relation, and actions become model methods. This gem stays Rails-free.

data/exe/r2ui

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# r2ui FILE [SCREEN]                 run the dashboards defined in FILE
+# r2ui --snapshot FILE [SCREEN]      print one frame as plain text and exit
+#   --width N --height N --ticks N      snapshot size, and how many refreshes to take first
+
+require "optparse"
+require_relative "../lib/r2ui"
+
+options = { snapshot: false, width: 120, height: 40, ticks: 2 }
+parser = OptionParser.new do |o|
+  o.banner = "Usage: r2ui [--snapshot] FILE [SCREEN]"
+  o.on("--snapshot", "Print one frame and exit") { options[:snapshot] = true }
+  o.on("--width N", Integer) { |n| options[:width] = n }
+  o.on("--height N", Integer) { |n| options[:height] = n }
+  o.on("--ticks N", Integer) { |n| options[:ticks] = n }
+end
+file, screen = parser.parse(ARGV)
+abort(parser.banner) unless file
+
+load File.expand_path(file)
+if options[:snapshot]
+  puts R2UI.snapshot(screen, width: options[:width], height: options[:height], ticks: options[:ticks])
+else
+  R2UI.run(screen)
+end

data/lib/r2ui/app.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module R2UI
+  # The running program: feeds, panel focus, key handling and the draw loop.
+  class App
+    FRAME = 0.25
+    FLASH_SECONDS = 3
+
+    def initialize(registry, name = nil)
+      @registry = registry
+      @dashboard = registry.screen(name)
+      resources = @dashboard.panels.map(&:resource).uniq.map { |r| registry.resource(r) }
+      @feeds = resources.to_h { |r| [r.name, Feed.new(r)] }
+      @states = @dashboard.panels.to_h do |p|
+        [p, p.table && PanelState.new(registry.resource(p.resource), p.table)]
+      end
+      @focus = @dashboard.panels.find(&:table) || @dashboard.panels.first
+      @renderer = Renderer.new(registry, @feeds, @states)
+      @mode = :normal
+      @zoomed = false
+    end
+
+    def run
+      terminal = Terminal.new
+      @resized = false
+      previous_winch = Signal.trap("WINCH") { @resized = true }
+      @feeds.each_value(&:start)
+      terminal.open do
+        loop do
+          width, height = terminal.size
+          terminal.clear if @resized
+          @resized = false
+          terminal.draw(frame(width, height))
+          break if terminal.read_keys(FRAME).any? { |key| handle(key) == :quit }
+        end
+      end
+    ensure
+      @feeds.each_value(&:stop)
+      Signal.trap("WINCH", previous_winch || "DEFAULT")
+    end
+
+    def snapshot(width:, height:, ticks: 1)
+      ticks.times do |i|
+        sleep(@feeds.values.map { |f| f.resource.interval }.min) if i.positive?
+        @feeds.each_value(&:refresh!)
+      end
+      frame(width, height).plain_lines.join("\n")
+    end
+
+    # Exposed for tests: feed keys without a terminal.
+    def press(*keys) = keys.each { |k| handle(k) }
+
+    def frame(width, height)
+      @renderer.render(@dashboard, width:, height:, focus: @focus, zoomed: @zoomed, prompt:)
+    end
+
+    private
+
+    def state = @states[@focus]
+
+    def lines = @renderer.lines.fetch(@focus, [])
+
+    def resource = @registry.resource(@focus.resource)
+
+    def prompt
+      case @mode
+      when :search then "/#{state.search}▏"
+      when Array then "#{@mode[1].label} #{@mode[2].size} #{@mode[2].size == 1 ? "row" : "rows"}? y/n"
+      else @flash if @flash && Time.now - @flash_at < FLASH_SECONDS
+      end
+    end
+
+    def handle(key)
+      return :quit if key == :interrupt
+
+      case @mode
+      when :search then search_key(key)
+      when Array then confirm_key(key)
+      else normal_key(key)
+      end
+    end
+
+    def normal_key(key)
+      case key
+      when "q" then return :quit
+      when :tab then cycle_focus(1)
+      when :back_tab then cycle_focus(-1)
+      when "z" then @zoomed = !@zoomed
+      end
+      table_key(key) if state
+      nil
+    end
+
+    def table_key(key)
+      case key
+      when :up, "k" then state.move(-1, lines.size)
+      when :down, "j" then state.move(1, lines.size)
+      when :page_up then state.move(-10, lines.size)
+      when :page_down then state.move(10, lines.size)
+      when :home then state.move(-lines.size, lines.size)
+      when :end then state.move(lines.size, lines.size)
+      when "[" then state.cycle_scope(-1)
+      when "]" then state.cycle_scope(1)
+      when "g" then state.cycle_grouping
+      when "s" then state.cycle_sort
+      when "S" then state.reverse_sort
+      when "/" then @mode = :search
+      when :enter, " " then state.toggle(lines[state.selected])
+      else
+        action = resource.actions.find { |a| a.key == key }
+        start_action(action) if action
+      end
+    end
+
+    def search_key(key)
+      case key
+      when :enter then @mode = :normal
+      when :escape
+        state.search = ""
+        @mode = :normal
+      when :backspace then state.search = state.search[0...-1]
+      when String then state.search += key if key.match?(/[[:print:]]/)
+      end
+    end
+
+    def start_action(action)
+      rows = lines[state.selected]&.rows
+      return if rows.nil? || rows.empty?
+
+      action.confirm ? @mode = [:confirm, action, rows] : run_action(action, rows)
+    end
+
+    def confirm_key(key)
+      _, action, rows = @mode
+      @mode = :normal
+      run_action(action, rows) if key == "y"
+    end
+
+    def run_action(action, rows)
+      rows.each { |row| action.handler.call(row) }
+      flash("#{action.label}: #{rows.size} done")
+    rescue StandardError => e
+      flash("#{action.label} failed: #{e.message}")
+    end
+
+    def flash(text)
+      @flash = text
+      @flash_at = Time.now
+    end
+
+    def cycle_focus(step)
+      panels = @dashboard.panels
+      @focus = panels[(panels.index(@focus) + step) % panels.size]
+    end
+  end
+end

data/lib/r2ui/canvas.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module R2UI
+  Rect = Data.define(:x, :y, :width, :height) do
+    def inner = Rect.new(x: x + 1, y: y + 1, width: [width - 2, 0].max, height: [height - 2, 0].max)
+    def bottom = y + height
+    def empty? = width <= 0 || height <= 0
+
+    # Split off the top `lines` rows: [top, rest].
+    def take(lines)
+      lines = lines.clamp(0, height)
+      [with(height: lines), with(y: y + lines, height: height - lines)]
+    end
+  end
+
+  # A grid of styled characters. Widgets draw into it; the terminal (or a snapshot) prints it.
+  class Canvas
+    STYLES = {
+      plain: "0", bold: "1", dim: "2", reverse: "7",
+      title: "1;36", header: "1;37", border: "90", focus: "36", selected: "7;36",
+      ok: "32", warn: "33", alert: "31", accent: "35", muted: "90"
+    }.freeze
+
+    attr_reader :width, :height
+
+    def initialize(width, height)
+      @width = width
+      @height = height
+      @chars = Array.new(height) { Array.new(width, " ") }
+      @styles = Array.new(height) { Array.new(width, :plain) }
+    end
+
+    def write(x, y, text, style = :plain, max: nil)
+      return if y.negative? || y >= height
+
+      limit = [max || width, width - x].min
+      text.to_s.each_char.first([limit, 0].max).each_with_index do |ch, i|
+        next if (x + i).negative?
+
+        @chars[y][x + i] = ch
+        @styles[y][x + i] = style
+      end
+    end
+
+    def fill(rect, char = " ", style = :plain)
+      rect.height.times { |dy| write(rect.x, rect.y + dy, char * rect.width, style) }
+    end
+
+    def plain_lines = @chars.map { |row| row.join.rstrip }
+
+    # ANSI for each line, so the terminal can redraw only lines that changed.
+    def ansi_lines
+      @chars.each_index.map do |y|
+        out = +""
+        current = nil
+        @chars[y].each_with_index do |ch, x|
+          style = @styles[y][x]
+          out << "\e[0;#{STYLES.fetch(style)}m" if style != current
+          current = style
+          out << ch
+        end
+        out << "\e[0m"
+      end
+    end
+  end
+end

data/lib/r2ui/dsl/column.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module R2UI
+  module DSL
+    # One attribute of a resource: how to read it, show it and roll it up.
+    Column = Data.define(:key, :label, :format, :sparkline, :aggregate, :width, :align, :sort, :reader) do
+      def self.build(key, label: nil, format: :text, sparkline: false, aggregate: nil, width: nil, align: nil,
+                     sort: nil, &reader)
+        new(
+          key:, format:, sparkline:, width:, sort:, reader:,
+          label: label || key.to_s.tr("_", " ").capitalize,
+          aggregate: aggregate || Format.default_aggregate(format),
+          align: align || Format.default_align(format)
+        )
+      end
+
+      def read(row) = reader ? reader.call(row) : Value.fetch(row, key)
+
+      def numeric? = Format.numeric?(format)
+
+      def render(value) = Format.call(format, value)
+    end
+  end
+end

data/lib/r2ui/dsl/dashboard.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module R2UI
+  module DSL
+    Gauge = Data.define(:attr, :of, :label)
+    Stat = Data.define(:attrs)
+    Sparkline = Data.define(:attr, :label, :height)
+    Table = Data.define(:scope, :group_by, :sort, :limit)
+
+    Panel = Data.define(:name, :resource, :span, :title, :items) do
+      def table = items.find { |i| i.is_a?(Table) }
+    end
+
+    Row = Data.define(:height, :panels)
+
+    # A screen made of rows of panels. Each panel shows one resource.
+    class Dashboard
+      attr_reader :name, :title, :rows
+
+      def self.build(name, &block)
+        dashboard = new(name)
+        Builder.new(dashboard).instance_eval(&block) if block
+        dashboard
+      end
+
+      # A one-panel dashboard showing a resource's full index.
+      def self.for_resource(resource)
+        build(resource.name) { row { panel resource.name } }
+      end
+
+      def initialize(name)
+        @name = name.to_sym
+        @title = name.to_s.tr("_", " ").capitalize
+        @rows = []
+      end
+
+      def panels = rows.flat_map(&:panels)
+
+      class Builder
+        def initialize(dashboard) = @d = dashboard
+
+        def title(text) = @d.instance_variable_set(:@title, text)
+
+        # `height:` in terminal lines; rows without one share the remaining space.
+        def row(height: nil, &block)
+          builder = RowBuilder.new
+          builder.instance_eval(&block)
+          @d.rows << Row.new(height:, panels: builder.panels)
+        end
+      end
+
+      class RowBuilder
+        attr_reader :panels
+
+        def initialize = @panels = []
+
+        # `span:` is a relative width; panels in a row split it by their spans.
+        def panel(name, resource: name, span: 1, title: nil, &block)
+          items = PanelBuilder.new.tap { |b| b.instance_eval(&block) if block }.items
+          items = [Table.new(scope: nil, group_by: nil, sort: nil, limit: nil)] if items.empty?
+          @panels << Panel.new(name:, resource:, span:, title:, items:)
+        end
+      end
+
+      class PanelBuilder
+        attr_reader :items
+
+        def initialize = @items = []
+
+        def gauge(attr, of:, label: nil) = @items << Gauge.new(attr:, of:, label:)
+
+        def stat(*attrs) = @items << Stat.new(attrs:)
+
+        def sparkline(attr, label: nil, height: 3) = @items << Sparkline.new(attr:, label:, height:)
+
+        def table(scope: nil, group_by: nil, sort: nil, limit: nil)
+          @items << Table.new(scope:, group_by:, sort:, limit:)
+        end
+      end
+    end
+  end
+end

data/lib/r2ui/dsl/resource.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module R2UI
+  module DSL
+    Scope = Data.define(:name, :label, :default, :filter) do
+      def call(rows) = filter ? rows.select(&filter) : rows
+    end
+
+    # group_by :name (rows with the same value) or group_by :parent, tree: true (subtree totals).
+    Grouping = Data.define(:name, :label, :tree, :by) do
+      def tree? = tree
+    end
+
+    Action = Data.define(:name, :label, :key, :confirm, :handler)
+
+    # A resource definition. Built by Resource::Builder from the block given to R2UI.resource.
+    class Resource
+      attr_reader :name, :title, :source, :interval, :key, :parent_key, :scopes, :groupings, :columns,
+                  :searchable, :actions
+
+      def self.build(name, &block)
+        resource = new(name)
+        Builder.new(resource).instance_eval(&block) if block
+        resource.validate!
+      end
+
+      def initialize(name)
+        @name = name.to_sym
+        @title = name.to_s.tr("_", " ").capitalize
+        @interval = 1.0
+        @scopes = []
+        @groupings = []
+        @columns = []
+        @searchable = []
+        @actions = []
+      end
+
+      def column(key) = columns.find { |c| c.key == key }
+
+      def default_scope = scopes.find(&:default) || scopes.first
+
+      def default_sort
+        col = columns.find(&:sort)
+        col ? [col.key, col.sort] : nil
+      end
+
+      def fetch
+        rows = source.call
+        rows.respond_to?(:to_ary) ? rows.to_ary : [rows]
+      end
+
+      def identify(row) = key ? Value.fetch(row, key) : row.object_id
+
+      def validate!
+        raise Error, "resource #{name} needs a `source { ... }` block" unless source
+        if groupings.any?(&:tree?) && !(key && parent_key)
+          raise Error, "resource #{name}: tree grouping needs `key :id_attr, parent: :parent_attr`"
+        end
+
+        self
+      end
+
+      # The DSL. Each method records a declaration on the resource.
+      class Builder
+        def initialize(resource) = @r = resource
+
+        def title(text) = set(:title, text)
+
+        def source(&block) = set(:source, block)
+
+        # `every:` takes seconds, or anything with #to_f (an ActiveSupport::Duration).
+        def refresh(every:) = set(:interval, every.to_f)
+
+        # Which attribute identifies a row, and optionally which points at its parent row.
+        def key(attr, parent: nil)
+          set(:key, attr)
+          set(:parent_key, parent)
+        end
+
+        def scope(name, label: nil, default: false, &filter)
+          @r.scopes << Scope.new(name:, label: label || humanize(name), default:, filter:)
+        end
+
+        def group_by(name, label: nil, tree: false, by: name)
+          @r.groupings << Grouping.new(name:, label: label || humanize(name), tree:, by:)
+        end
+
+        def index(&) = instance_eval(&)
+
+        def column(key, **, &) = @r.columns << Column.build(key, **, &)
+        alias attribute column
+
+        # Attributes that free-text search ("/") matches against.
+        def filter(*keys) = @r.searchable.concat(keys)
+
+        def action(name, key:, label: nil, confirm: false, &handler)
+          @r.actions << Action.new(name:, label: label || humanize(name), key:, confirm:, handler:)
+        end
+
+        private
+
+        def set(ivar, value) = @r.instance_variable_set(:"@#{ivar}", value)
+
+        def humanize(sym) = sym.to_s.tr("_", " ").capitalize
+      end
+    end
+  end
+end

data/lib/r2ui/feed.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module R2UI
+  # Fetches one resource on its refresh interval in a background thread and records history.
+  class Feed
+    SINGLE = :record
+
+    attr_reader :resource, :history
+
+    def initialize(resource)
+      @resource = resource
+      @history = History.new
+      @lock = Mutex.new
+      @rows = []
+      @error = nil
+      @version = 0
+    end
+
+    def rows = @lock.synchronize { @rows }
+    def error = @lock.synchronize { @error }
+    def version = @lock.synchronize { @version }
+
+    # History id for a row: its key, or :record when the resource returns a single record.
+    def series_id(row) = @resource.key ? @resource.identify(row) : SINGLE
+
+    def start(&on_update)
+      @thread = Thread.new do
+        loop do
+          refresh!
+          on_update&.call
+          sleep @resource.interval
+        end
+      end
+      self
+    end
+
+    def stop
+      @thread&.kill
+      @thread&.join(1)
+    end
+
+    def refresh!
+      rows = @resource.fetch
+      @lock.synchronize do
+        record(rows)
+        @rows = rows
+        @error = nil
+        @version += 1
+      end
+    rescue StandardError => e
+      @lock.synchronize do
+        @error = "#{e.class}: #{e.message}"
+        @version += 1
+      end
+    end
+
+    private
+
+    def record(rows)
+      return unless @resource.key || rows.size == 1
+
+      numeric = @resource.columns.select(&:numeric?)
+      ids = rows.map do |row|
+        id = series_id(row)
+        numeric.each { |c| @history.record(id, c.key, c.read(row) || 0) }
+        id
+      end
+      @history.prune(ids)
+    end
+  end
+end