r2ui 0.1.0 → 0.2.0

data/lib/r2ui/cli/ext/table.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+# c10-table: tables, like `npm outdated` or `pnpm ls --long`.
+#
+#   table([["rails", "7.1.0", "12 kB"], ["pg", "1.5", "1.2 MB"]],
+#         headers: %w[Name Version Size], align: { 2 => :right })
+#
+#   table([{ app: "api", state: "up" }, { app: "web", state: "down" }])   # headers from the keys
+#
+# On a terminal (Shell#live?) it draws a Lipgloss::Table with a rounded border (muted) and a bold
+# header, sized to its content and shrunk (wrapping cells) when wider than the shell:
+#
+#   ╭───────┬─────────┬────────╮
+#   │ Name  │ Version │   Size │
+#   ├───────┼─────────┼────────┤
+#   │ rails │ 7.1.0   │  12 kB │
+#   │ pg    │ 1.5     │ 1.2 MB │
+#   ╰───────┴─────────┴────────╯
+#
+# Off a terminal (a pipe, CI, TERM=dumb) it prints plain columns separated by two spaces, no
+# border, no colour, no trailing spaces, one line per row (newlines in a cell become spaces), so
+# `tool ls | awk '{print $1}'` works:
+#
+#   Name   Version    Size
+#   rails  7.1.0     12 kB
+#   pg     1.5      1.2 MB
+#
+# Rows are Arrays (short ones are padded) or Hashes. With Hash rows and no `headers:`, the headers
+# are the keys in the order they first appear; with `headers:`, they pick and order the columns.
+# Cells are shown with #to_s (nil is blank) and measured by display width, so wide characters and
+# already-painted text line up. `align:` maps a column (0-based index, or its header) to :left,
+# :right or :center. With no rows only the header prints; with neither, nothing. Writes to stdout
+# through the Shell (above a running Live region) and returns nil.
+module R2UI
+  module CLI
+    module Ext
+      module Tabulate
+        ALIGNMENTS = { left: Lipgloss::LEFT, right: Lipgloss::RIGHT, center: Lipgloss::CENTER }.freeze
+        GAP = "  "
+
+        module_function
+
+        # [headers or nil, rows as Arrays of Strings, all the same length].
+        def normalize(rows, headers)
+          rows = rows.to_a
+          if rows.any? { |row| row.is_a?(Hash) }
+            keys = headers || rows.flat_map { |row| row.to_h.keys }.uniq
+            rows = rows.map { |row| row.is_a?(Hash) ? keys.map { |key| lookup(row, key) } : Array(row) }
+            headers = keys
+          else
+            rows = rows.map { |row| Array(row) }
+          end
+          headers = headers&.map { |cell| text(cell) }
+          count = [headers&.size || 0, *rows.map(&:size)].max
+          rows = rows.map { |row| Array.new(count) { |i| text(row[i]) } }
+          headers = Array.new(count) { |i| headers[i] || "" } if headers
+          [headers, rows]
+        end
+
+        def lookup(row, key)
+          [key, key.to_s, key.respond_to?(:to_sym) ? key.to_sym : key].each do |k|
+            return row[k] if row.key?(k)
+          end
+          nil
+        end
+
+        def text(cell) = cell.nil? ? "" : cell.to_s
+
+        # { column index => :left/:right/:center } from indexes or header names.
+        def alignments(align, headers)
+          (align || {}).to_h do |column, side|
+            raise ArgumentError, "align: #{side.inspect} isn't :left, :right or :center" unless ALIGNMENTS.key?(side)
+
+            index = column.is_a?(Integer) ? column : headers&.index(column.to_s)
+            raise ArgumentError, "align: no column #{column.inspect}" unless index
+
+            [index, side]
+          end
+        end
+
+        def width(text) = Lipgloss.width(text)
+
+        def plain(headers, rows, align)
+          lines = headers ? [headers, *rows] : rows
+          return [] if lines.empty?
+
+          lines = lines.map { |cells| cells.map { |cell| cell.gsub(/\s*\R\s*/, " ") } }
+          widths = lines.transpose.map { |column| column.map { |cell| width(cell) }.max }
+          lines.map do |cells|
+            cells.each_with_index.map { |cell, i| pad(cell, widths[i], align[i]) }.join(GAP).rstrip
+          end
+        end
+
+        def pad(cell, size, side)
+          space = size - width(cell)
+          case side
+          when :right then (" " * space) + cell
+          when :center then (" " * (space / 2)) + cell + (" " * (space - (space / 2)))
+          else cell + (" " * space)
+          end
+        end
+
+        def boxed(shell, headers, rows, align)
+          return [] if headers.nil? && rows.empty?
+
+          columns = (headers || rows.first).size
+          color = shell.color?
+          cell = Lipgloss::Style.new.padding(0, 1)
+          head = color ? cell.bold(true) : cell
+          table = Lipgloss::Table.new.border(:rounded).rows(rows)
+          table = table.headers(headers) if headers
+          table = table.border_header(false) if rows.empty? # no rule above an empty body
+          table = table.border_style(shell.theme.style(:muted)) if color
+          table = table.style_func(rows: rows.size, columns:) do |row, column|
+            style = row == Lipgloss::Table::HEADER_ROW ? head : cell
+            (side = align[column]) ? style.align(ALIGNMENTS.fetch(side)) : style
+          end
+          out = table.render
+          out = table.width(shell.width).render if out.lines.any? { |line| width(line.chomp) > shell.width }
+          out.split("\n")
+        end
+      end
+    end
+
+    extension :table do
+      helpers do
+        def table(rows, headers: nil, align: nil)
+          headers, rows = Ext::Tabulate.normalize(rows, headers)
+          align = Ext::Tabulate.alignments(align, headers)
+          lines = if shell.live?
+                    Ext::Tabulate.boxed(shell, headers, rows, align)
+                  else
+                    Ext::Tabulate.plain(headers, rows, align)
+                  end
+          lines.each { |line| shell.puts(line) }
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/r2ui/cli/ext/tasks.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+# c02-tasks: an npm-style task list. Steps show as pending, spin while they run and resolve to
+# ✔ / ✖ / – lines with their timings.
+#
+#   tasks do
+#     step("Resolving packages") { resolve }                       # the block's value is kept
+#     step("Fetching") { |s| files.each_with_index { |f, i| s.detail = "#{i + 1}/#{files.size}"; get(f) } }
+#     step("Linking") { |s| s.skip!("nothing to link") if links.empty?; link }
+#   end                                                            # => [resolved, fetched, linked]
+#
+# On a terminal (Shell#live?) the list redraws in place:
+#
+#   ✔ Resolving packages 120ms
+#   ⠹ Fetching · 12/40
+#   ○ Linking
+#
+# and its final state stays in the scrollback. Off a terminal each step prints one line when it
+# ends ("✔ Resolving packages 120ms"), nothing else: no spinner frames, no escape codes.
+#
+# The `tasks` block declares the steps; they run after it, in order, on the caller's thread (so
+# they see `args`, `options` and every helper). When a step raises, it shows ✖, the steps after it
+# show "– skipped" without running, and the exception propagates (a command then exits 1 with
+# "✖ message"; ctrl+c exits 130). `s.skip!(reason)` ends a step as skipped and carries on.
+# `say`/`shell.puts` inside a step prints above the list.
+#
+# `step("Building") { ... }` outside a `tasks` block is a one-step list: it runs at once and
+# returns the block's value.
+#
+# This is the reference extension for output helpers (docs/cli.md): a `helpers` block, a Live
+# region for the terminal, one plain line per event off it. Copy its shape and its test.
+module R2UI
+  module CLI
+    module Ext
+      module Tasks
+        # A step that ended early by choice (Handle#skip!).
+        class Skip < StandardError; end
+
+        Step = Struct.new(:title, :block, :status, :detail, :note, :started, :finished, :value) do
+          def elapsed = finished && started ? finished - started : nil
+        end
+
+        # What a step's block gets: change its title or detail line while it runs, or skip it.
+        class Handle
+          def initialize(step, live)
+            @step = step
+            @live = live
+          end
+
+          def title = @step.title
+
+          def title=(text)
+            @step.title = text.to_s
+            @live.refresh
+          end
+
+          def detail=(text)
+            @step.detail = text&.to_s
+            @live.refresh
+          end
+
+          def skip!(reason = nil) = raise(Skip, reason)
+        end
+
+        # The steps a `tasks` block declared, and how they run and draw.
+        class List
+          def initialize(shell)
+            @shell = shell
+            @steps = []
+            @lock = Monitor.new
+          end
+
+          def add(title, block)
+            raise ArgumentError, "step needs a block" unless block
+
+            @steps << Step.new(title: title.to_s, block:, status: :pending)
+          end
+
+          # Runs every step; returns their values. Re-raises the first step's exception.
+          def run
+            error = nil
+            live = Live.new(@shell) { |frame| view(frame) }
+            live.run do
+              @steps.each do |step|
+                if error
+                  finish(step, :skipped, live)
+                  next
+                end
+                error = run_step(step, live)
+              end
+            end
+            raise error if error
+
+            @steps.map(&:value)
+          end
+
+          def view(frame)
+            @lock.synchronize { @steps.map { |step| line(step, frame) }.join("\n") }
+          end
+
+          private
+
+          def run_step(step, live)
+            update(step, live) do
+              step.status = :running
+              step.started = now
+            end
+            step.value = step.block.call(Handle.new(step, live))
+            finish(step, :done, live)
+            nil
+          rescue Skip => e
+            step.note = e.message unless e.message == e.class.name
+            finish(step, :skipped, live)
+            nil
+          rescue Exception => e # rubocop:disable Lint/RescueException -- ctrl+c and halt end the list too
+            finish(step, e.is_a?(Halt) ? :done : :failed, live)
+            e
+          end
+
+          def finish(step, status, live)
+            update(step, live) do
+              step.status = status
+              step.finished = now if step.started
+            end
+            @shell.puts(line(step, 0)) unless live.running?
+          end
+
+          def update(step, live)
+            @lock.synchronize { yield step }
+            live.refresh
+          end
+
+          def line(step, frame)
+            title = step.title
+            detail = step.detail ? @shell.paint(" · #{step.detail}", :muted) : ""
+            time = step.elapsed ? " #{@shell.paint(Tasks.duration(step.elapsed), :muted)}" : ""
+            case step.status
+            when :pending then "#{@shell.symbol(:pending)} #{@shell.paint(title, :pending)}"
+            when :running then "#{@shell.paint(Live.spinner(frame), :running)} #{title}#{detail}"
+            when :done then "#{@shell.symbol(:success)} #{title}#{detail}#{time}"
+            when :failed then "#{@shell.symbol(:error)} #{title}#{detail}#{time}"
+            when :skipped
+              "#{@shell.symbol(:skipped)} #{@shell.paint("#{title} (#{step.note || "skipped"})", :skipped)}"
+            end
+          end
+
+          def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+
+        module_function
+
+        # 0.12 → "120ms", 3.456 → "3.5s", 75 → "1m 15s".
+        # Rounds before picking the unit, so 59.97 is "1m 0s", not "60.0s".
+        def duration(seconds)
+          return "#{(seconds * 1000).round}ms" if (seconds * 1000).round < 1000
+
+          tenths = (seconds * 10).round
+          return "#{format("%.1f", tenths / 10.0)}s" if tenths < 600
+
+          total = seconds.round
+          "#{total / 60}m #{total % 60}s"
+        end
+
+        # The list a `tasks` block is declaring on this thread (nil outside one).
+        def collecting = Thread.current[:r2ui_cli_tasks]
+
+        def collecting=(list)
+          Thread.current[:r2ui_cli_tasks] = list
+        end
+
+        def running? = Thread.current[:r2ui_cli_tasks_running]
+
+        # Runs the block as the thread's one running list (lists draw one region; they don't nest).
+        def running
+          raise Error, "steps can't run inside a running step" if running?
+
+          Thread.current[:r2ui_cli_tasks_running] = true
+          begin
+            yield
+          ensure
+            Thread.current[:r2ui_cli_tasks_running] = nil
+          end
+        end
+      end
+    end
+
+    extension :tasks do
+      helpers do
+        def tasks(&block)
+          raise ArgumentError, "tasks needs a block" unless block
+          raise Error, "tasks can't be nested" if Ext::Tasks.collecting
+
+          list = Ext::Tasks::List.new(shell)
+          begin
+            Ext::Tasks.collecting = list
+            block.call
+          ensure
+            Ext::Tasks.collecting = nil
+          end
+          Ext::Tasks.running { list.run }
+        end
+
+        def step(title, &block)
+          if (list = Ext::Tasks.collecting)
+            list.add(title, block)
+            return nil
+          end
+
+          list = Ext::Tasks::List.new(shell)
+          list.add(title, block)
+          Ext::Tasks.running { list.run }.first
+        end
+      end
+    end
+  end
+end

data/lib/r2ui/cli/ext/trace.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# c28-trace: a --trace flag that shows where an unexpected error came from.
+#
+#   R2UI.cli "deployer" do
+#     trace_option
+#     command(:deploy) { run { Deploy.call } }
+#   end
+#
+#   $ deployer deploy --trace
+#   ✖ undefined method 'call' for nil
+#   NoMethodError
+#     lib/deploy.rb:12:in 'Deploy.call'
+#     ...
+#
+# `trace_option` on the root adds `--trace` to every command. With it, an unexpected error (any
+# exception that isn't a CLI::Error, so not `abort!` or a usage error) prints "✖ message" on
+# stderr, then the exception class and its full backtrace, and each "Caused by Class: message"
+# with its own backtrace, and exits 1. On a terminal the class and backtrace are muted; off it
+# they are the same plain lines, nothing else. Without `--trace` errors are reported as before
+# (R2UI_TRACE=1 still works).
+module R2UI
+  module CLI
+    module Ext
+      module Trace
+        module_function
+
+        def report(shell, error)
+          shell.err_puts("#{shell.symbol(:error)} #{error.message}")
+          lines = [error.class.name, *frames(error)]
+          seen = [error]
+          cause = error.cause
+          while cause && !seen.include?(cause)
+            seen << cause
+            lines << "Caused by #{cause.class}: #{cause.message}"
+            lines.concat(frames(cause))
+            cause = cause.cause
+          end
+          lines.each { |line| shell.err_puts(shell.paint(line, :muted)) }
+          1
+        end
+
+        def frames(error) = Array(error.backtrace).map { |frame| "  #{frame}" }
+      end
+    end
+
+    extension :trace do
+      dsl(:command) do
+        def trace_option = declare(:trace_option, true)
+      end
+
+      setup do
+        flag :trace, desc: "Show the backtrace of unexpected errors" if declared(:trace_option).any?
+      end
+
+      on_error do |error|
+        next if error.is_a?(Error) || !options&.fetch(:trace, false)
+        next unless program.declared(:trace_option).any?
+
+        Ext::Trace.report(shell, error)
+      end
+    end
+  end
+end

data/lib/r2ui/cli/ext/tree.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+# c08-tree: a dependency-style tree (npm ls, cargo tree, tree(1)), drawn by Lipgloss::Tree.
+#
+#   tree("app@1.0", { "rails@7.1" => { "rack@3.0" => nil }, "pg@1.5" => nil })
+#
+#   app@1.0
+#   ├── rails@7.1
+#   │   └── rack@3.0
+#   └── pg@1.5
+#
+# Children nest as Hashes (label => children; nil for a leaf, a single value for one child) and
+# Arrays (leaves as Strings, Hashes for branches). An Array right after an item in an Array nests
+# under that item, the way Lipgloss::Tree treats a rootless subtree:
+#
+#   tree("src", ["main.rb", { "lib" => %w[a.rb b.rb] }, "README.md"])
+#   tree("root", ["a", %w[a1 a2], "b"])                  # a1 and a2 hang under "a"
+#   tree({ "a" => nil, "b" => nil })                     # no root line: just the branches
+#
+# Labels are anything with #to_s; multi-line labels keep the rail on their later lines.
+# `depth: n` shows n levels below the root and puts one "…" under each branch it cuts
+# (`depth: 0` is the root and "└── …").
+#
+# On a terminal the root is bold, names are in the accent colour with "@version" muted, and the
+# connectors are muted. Off a terminal (pipe, CI, NO_COLOR) it prints the same lines with the same
+# glyphs and no escape codes, so `tool deps | grep rack` works. Printed through the Shell, so
+# inside a Live region (tasks, spinners) it lands above the region. Returns nil.
+module R2UI
+  module CLI
+    module Ext
+      module DepTree
+        ELLIPSIS = "…"
+        # "name@version": the last "@" that isn't the first character ("@types/node@20.1").
+        VERSIONED = /\A(?<name>.+?)(?<version>@[^@\/\s]+)\z/
+
+        Node = Struct.new(:label, :children)
+
+        module_function
+
+        # Children in any accepted shape → [Node].
+        def nodes(value)
+          case value
+          when nil then []
+          when Hash then value.map { |label, kids| Node.new(label.to_s, nodes(kids)) }
+          when Array then array_nodes(value)
+          else [Node.new(value.to_s, [])]
+          end
+        end
+
+        def array_nodes(items)
+          items.each_with_object([]) do |item, list|
+            if item.is_a?(Array) && !list.empty?
+              list.last.children.concat(nodes(item))
+            else
+              list.concat(nodes(item))
+            end
+          end
+        end
+
+        # Cuts the branches below `depth` levels, leaving one "…" in their place.
+        def truncate(list, depth)
+          return list if depth.nil?
+          return list.empty? ? [] : [Node.new(ELLIPSIS, [])] if depth.zero?
+
+          list.map { |node| Node.new(node.label, truncate(node.children, depth - 1)) }
+        end
+
+        def render(shell, root, list)
+          tree = Lipgloss::Tree.root(root.nil? ? "" : label(shell, root.to_s, root: true))
+          tree = tree.enumerator_style(shell.theme.style(:muted).padding_right(1)) if shell.color?
+          list.each { |node| tree = tree.child(build(shell, node)) }
+          # Lipgloss pads a multi-line item to a block; drop that padding so piped lines stay clean.
+          tree.render.split("\n").map(&:rstrip).join("\n")
+        end
+
+        def build(shell, node)
+          text = label(shell, node.label)
+          return text if node.children.empty?
+
+          node.children.reduce(Lipgloss::Tree.root(text)) { |tree, child| tree.child(build(shell, child)) }
+        end
+
+        def label(shell, text, root: false)
+          return shell.paint(text, :muted) if text == ELLIPSIS
+
+          name_style = root ? :heading : :accent
+          match = text.include?("\n") ? nil : VERSIONED.match(text)
+          return shell.paint(text, name_style) unless match
+
+          shell.paint(match[:name], name_style) + shell.paint(match[:version], :muted)
+        end
+      end
+    end
+
+    extension :tree do
+      helpers do
+        def tree(root, children = nil, depth: nil)
+          unless depth.nil? || (depth.is_a?(Integer) && !depth.negative?)
+            raise ArgumentError, "depth must be a non-negative Integer, got #{depth.inspect}"
+          end
+
+          if children.nil? && (root.is_a?(Hash) || root.is_a?(Array))
+            children = root
+            root = nil
+          end
+          list = Ext::DepTree.truncate(Ext::DepTree.nodes(children), depth)
+          text = Ext::DepTree.render(shell, root, list)
+          shell.puts(text) unless text.empty?
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/r2ui/cli/ext/version.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# c23-version: `tool --version`.
+#
+#   R2UI.cli "deployer" do
+#     version "1.4.0"            # or Deployer::VERSION
+#     ...
+#   end
+#
+#   $ deployer --version         # or -V, or `deployer deploy --version`
+#   deployer 1.4.0
+#
+# `version` on the root adds `-V, --version` ("Print the version") to every command. The flag
+# prints "<name> <version>" on stdout and exits 0 before anything else is checked: missing
+# required options or arguments don't matter and no command runs. The root's `--help` starts with
+# the same line.
+#
+# On a colour terminal the name is bold and the version in the accent colour; in a pipe it is the
+# plain line, so `deployer --version | cut -d' ' -f2` is stable.
+#
+# A tool that already has a `-V` keeps it (the flag is then `--version` only); one that defines
+# its own `version` option keeps that too, and only the help line is added.
+module R2UI
+  module CLI
+    module Ext
+      module VersionFlag
+        module_function
+
+        def line(shell, program)
+          version = program.declared(:version).last
+          "#{shell.paint(program.name, :heading)} #{shell.paint(version.to_s, :accent)}"
+        end
+
+        # True when --version is the flag this extension added (not the tool's own option).
+        def ours?(option) = option&.meta&.fetch(:r2ui_version_flag, false)
+      end
+    end
+
+    extension :version do
+      dsl(:command) do
+        def version(value)
+          raise ArgumentError, "#{definition.full_name}: version belongs on the root command" unless definition.root?
+
+          declare(:version, value)
+        end
+      end
+
+      setup do
+        next if declared(:version).empty? || definition.option(:version)
+
+        short = definition.options.any? { |o| o.short == "V" } ? nil : "V"
+        flag :version, short:, desc: "Print the version", r2ui_version_flag: true
+      end
+
+      after_parse do
+        next unless options[:version] && Ext::VersionFlag.ours?(command.option(:version))
+
+        shell.puts(Ext::VersionFlag.line(shell, program))
+        halt(0)
+      end
+
+      help_header do |command, shell|
+        Ext::VersionFlag.line(shell, command) if command.root? && command.declared(:version).any?
+      end
+    end
+  end
+end