r2ui 0.1.0 → 0.2.0

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+# c26-env: options from environment variables.
+#
+#   R2UI.cli "deployer" do
+#     option :token, env: "DEPLOY_TOKEN", required: true, desc: "API token"
+#     option :port, :integer, env: "DEPLOY_PORT", default: 80
+#     option :env, env: %w[DEPLOY_ENV RACK_ENV]       # the first one set wins
+#     option :tags, many: true, env: "DEPLOY_TAGS"    # "web,api" => ["web", "api"]
+#     flag :force, env: "DEPLOY_FORCE"                # 1/0, true/false, yes/no, on/off
+#   end
+#
+#   $ DEPLOY_TOKEN=s3cret deployer            # options[:token] == "s3cret"
+#   $ DEPLOY_TOKEN=s3cret deployer --token x  # the command line wins: "x"
+#
+# When an option isn't on the command line, its variable fills it (in `after_parse`, so before
+# defaults and the required check: a set variable satisfies `required: true`, and a default
+# lambda isn't called). The value is converted and checked like typed input (type, `in:`), and a
+# bad one is a usage error that names the variable:
+#
+#   ✖ DEPLOY_PORT: --port expects an integer, got "eighty"
+#   Run 'deployer --help' for usage.
+#
+# An empty variable counts as unset. `given?(:token)` stays false: it means typed. Options from
+# a group apply to its subcommands, variables included. Variables are read from the shell's env
+# (`Shell#env`, ENV by default), so tests pass `env:` to `run_cli`.
+#
+# `--help` gains an "Environment" section (hidden options left out), names in the accent colour
+# and headings bold on a terminal, plain text in a pipe:
+#
+#   Environment
+#     DEPLOY_TOKEN  --token
+#     DEPLOY_PORT   --port
+#     DEPLOY_TAGS   --tags (comma-separated)
+module R2UI
+  module CLI
+    module Ext
+      module EnvOptions
+        module_function
+
+        # The variable names for an option (none when it has no `env:`).
+        def names(option) = Array(option.meta[:env])
+
+        def check!(command)
+          command.options.each do |option|
+            env = option.meta[:env]
+            next if env.nil?
+
+            valid = Array(env).then { |list| list.any? && list.all? { |n| n.is_a?(String) && !n.empty? } }
+            raise ArgumentError, "#{command.full_name}: #{option.long} env: expects a variable name or a list of them, got #{env.inspect}" unless valid
+          end
+          command.commands.each { |sub| check!(sub) }
+        end
+
+        # The first set (non-empty) variable as [name, raw value], or nil.
+        def lookup(option, env)
+          names(option).each do |name|
+            value = env[name]
+            return [name, value] unless value.nil? || value.empty?
+          end
+          nil
+        end
+
+        def convert(option, name, raw)
+          if option.many
+            raw.split(",").map(&:strip).reject(&:empty?).map { |part| option.convert(part) }
+          else
+            option.convert(raw)
+          end
+        rescue UsageError => e
+          raise UsageError, "#{name}: #{e.message}"
+        end
+
+        def help(command, shell)
+          rows = command.all_options.reject(&:hidden).flat_map do |option|
+            names(option).map { |name| [name, option] }
+          end
+          return nil if rows.empty?
+
+          width = rows.map { |name, _| name.size }.max
+          lines = rows.map do |name, option|
+            note = option.many ? " #{shell.paint("(comma-separated)", :muted)}" : ""
+            "#{shell.paint(name, :accent)}#{" " * (width - name.size)}  #{option.long}#{note}"
+          end
+          ["Environment", lines]
+        end
+      end
+    end
+
+    extension :env do
+      setup { Ext::EnvOptions.check!(definition) }
+
+      after_parse do
+        command.all_options.each do |option|
+          next if given?(option.name)
+
+          name, raw = Ext::EnvOptions.lookup(option, shell.env)
+          next unless name
+
+          value = Ext::EnvOptions.convert(option, name, raw)
+          options[option.name] = value unless option.many && value.empty?
+        end
+      end
+
+      help_section { |command, shell| Ext::EnvOptions.help(command, shell) }
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# c29-examples: example invocations in a command's --help.
+#
+#   R2UI.cli "deployer" do
+#     command :deploy do
+#       example "deployer deploy api -e production", "Deploy api to production"
+#       example "deployer deploy web"                   # the description is optional
+#     end
+#   end
+#
+# `example(command_line, description = nil)` is repeatable and works on the root and on any
+# command; each command's help shows only its own examples, in the order given, as a last
+# section after Options:
+#
+#   Examples
+#     # Deploy api to production
+#     deployer deploy api -e production
+#     deployer deploy web
+#
+# On a terminal the "# ..." comment is muted and the command is in the accent colour (the same
+# colour as the Usage line), so the runnable part stands out. Off a terminal (a pipe, CI,
+# NO_COLOR) it is the same text without escape codes. A multi-line description makes several
+# comment lines. The command line is printed as given (no "$ " prompt), so it copies cleanly.
+module R2UI
+  module CLI
+    module Ext
+      module Examples
+        Example = Data.define(:command_line, :description)
+
+        module_function
+
+        def section(command, shell)
+          examples = command.declared(:example)
+          return nil if examples.empty?
+
+          ["Examples", examples.flat_map { |e| lines(e, shell) }]
+        end
+
+        def lines(example, shell)
+          comments = example.description.to_s.split("\n").map { |line| shell.paint("# #{line}".rstrip, :muted) }
+          commands = example.command_line.split("\n").map { |line| shell.paint(line, :accent) }
+          comments + commands
+        end
+      end
+    end
+
+    extension :examples do
+      dsl(:command) do
+        def example(command_line, description = nil)
+          command_line = command_line.to_s.strip
+          raise ArgumentError, "example needs a command line" if command_line.empty?
+
+          description = description&.to_s&.strip
+          declare(:example, Ext::Examples::Example.new(command_line:, description:))
+        end
+      end
+
+      help_section { |command, shell| Ext::Examples.section(command, shell) }
+    end
+  end
+end

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

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+# c21-filter: type to filter a list, like gum filter or fzf.
+#
+#   branch = filter("Branch?", `git branch --format=%(refname:short)`.lines(chomp: true))
+#   region = filter("Region?", { "Europe (eu-west-1)" => :eu, "US East (us-east-1)" => :us })
+#   filter("Package?", packages, placeholder: "name or scope", limit: 8)
+#
+# On a terminal (Shell#interactive?) it asks inline: a bubbles TextInput on the question line,
+# and under it the choices narrowed by a fuzzy match as you type (the characters may be spread
+# out: "fbil" finds "feature/billing"; contiguous runs and word starts rank first, ties keep the
+# list's order), the matched characters highlighted:
+#
+#   ? Branch? feat▌  2/6
+#   › feature/billing
+#     feature/login
+#
+# ↑/↓ (ctrl+p/ctrl+n, ctrl+k/ctrl+j) move, enter picks, the usual line-editing keys edit the
+# query. At most `limit:` (10) rows show at once, with "↑ 3 more" / "↓ 5 more" hints. It leaves
+# "✔ Branch? · feature/billing" in the scrollback; ctrl+c or esc raises Interrupt (a command exits
+# 130) after the terminal is restored.
+#
+# Off a terminal it reads one line and returns the best match for it ("bill" → feature/billing).
+# It asks "Branch? " on stderr when a person can type (stdin is a terminal, stdout piped); from a
+# pipe (`echo bill | tool`, CI) it doesn't ask and records "✔ Branch? · feature/billing" on
+# stderr. A line nothing matches, an empty line or end of input raise a CLI::Error naming the
+# question (a command exits 1).
+#
+# Choices are an Array (the item is returned) or a Hash of label ⇒ value (the value is returned).
+module R2UI
+  module CLI
+    module Ext
+      module Filter
+        # Fuzzy scoring, in the spirit of fzf: every query character must appear in order; a match
+        # earns MATCH per character, more at a word start or right after the previous match, less
+        # for each character skipped in between.
+        MATCH = 16
+        BOUNDARY = 8
+        CAMEL = 7
+        CONSECUTIVE = 6
+        GAP_START = 3
+        GAP = 1
+        EXACT = 1000
+
+        # A choice as the list shows it: its label, what picking it returns, its place in the list.
+        Choice = Data.define(:label, :value, :index)
+
+        # A choice that matched: its score and the label positions that matched.
+        Match = Data.define(:choice, :score, :positions)
+
+        # The inline prompt: a Bubbletea model on R2UI::CLI::Prompt hosting a bubbles TextInput.
+        class Model < Prompt::Model
+          attr_reader :question, :matches, :cursor
+
+          def initialize(shell, question, choices, limit: 10, placeholder: "Type to filter")
+            super(shell)
+            @question = question
+            @choices = Filter.choices(choices)
+            @limit = [[limit, shell.height - 3].min, 1].max
+            input = Bubbles::TextInput.new
+            input.prompt = ""
+            input.placeholder = placeholder
+            input.placeholder_style = shell.theme.style(:muted) if shell.color?
+            @focus_command = input.focus
+            self.component = input
+            @query = nil
+            refilter
+          end
+
+          def init = [self, @focus_command]
+
+          def update(message)
+            result = super
+            refilter unless done? || component.value == @query
+            result
+          end
+
+          def view
+            return "#{shell.symbol(:error)} #{question}" if interrupted?
+            return Filter.answered(shell, question, @picked.label) if done?
+
+            [header, *rows].join("\n")
+          end
+
+          private
+
+          def key(name, _message)
+            case name
+            when "enter"
+              return [self, nil] if matches.empty?
+
+              @picked = matches[cursor].choice
+              submit(@picked.value)
+            when "up", "ctrl+p", "ctrl+k" then move(-1)
+            when "down", "ctrl+n", "ctrl+j" then move(1)
+            end
+          end
+
+          def move(step)
+            @cursor = (cursor + step).clamp(0, [matches.size - 1, 0].max)
+            @offset = cursor if cursor < @offset
+            @offset = cursor - @limit + 1 if cursor >= @offset + @limit
+            [self, nil]
+          end
+
+          def refilter
+            @query = component.value
+            @matches = Filter.rank(@query, @choices)
+            @cursor = 0
+            @offset = 0
+          end
+
+          def header
+            count = shell.paint("#{matches.size}/#{@choices.size}", :muted)
+            "#{shell.paint("?", :accent)} #{question} #{component.view}  #{count}"
+          end
+
+          def rows
+            return ["  #{shell.paint("No matches", :muted)}"] if matches.empty?
+
+            above = @offset
+            below = matches.size - @offset - @limit
+            lines = []
+            lines << "  #{shell.paint("↑ #{above} more", :muted)}" if above.positive?
+            matches[@offset, @limit].each_with_index { |match, i| lines << row(match, @offset + i == cursor) }
+            lines << "  #{shell.paint("↓ #{below} more", :muted)}" if below.positive?
+            lines
+          end
+
+          # The pointer marks the row without colour too (NO_COLOR on a terminal).
+          def row(match, selected)
+            room = [shell.width - 2, 1].max
+            label = match.choice.label
+            label = "#{label[0, room - 1]}…" if label.size > room
+            base = selected ? [:accent] : []
+            text = Filter.highlight(shell, label, match.positions, base)
+            selected ? "#{shell.paint(shell.theme.symbol(:pointer), :accent)} #{text}" : "  #{text}"
+          end
+        end
+
+        module_function
+
+        def choices(list)
+          return list if list.is_a?(Array) && list.all?(Choice)
+
+          pairs = list.is_a?(Hash) ? list.to_a : Array(list).map { |item| [item, item] }
+          pairs.each_with_index.map { |(label, value), index| Choice.new(label: label.to_s, value:, index:) }
+        end
+
+        # The choices that match `query`, best first; an empty query keeps them all, in order.
+        def rank(query, choices)
+          matches = choices.filter_map do |choice|
+            score, positions = score(query, choice.label)
+            Match.new(choice:, score:, positions:) if score
+          end
+          matches.sort_by { |m| [-m.score, m.choice.index] }
+        end
+
+        # [score, matched positions] for `query` in `label`, or nil when it doesn't match. The
+        # best alignment by dynamic programming: score[i][j] is the best score with query
+        # character i at label position j.
+        def score(query, label)
+          q = query.downcase.chars
+          return [0, []] if q.empty?
+
+          chars = label.chars
+          lower = chars.map(&:downcase)
+          return nil if q.size > chars.size
+
+          scores = Array.new(q.size) { Array.new(chars.size) }
+          from = Array.new(q.size) { Array.new(chars.size) }
+          q.each_with_index do |qc, i|
+            gapped = nil # best score[i - 1][k] for k <= j - 2, less the gap penalty up to j
+            gapped_from = nil
+            chars.each_index do |j|
+              if i.positive? && j >= 2 && (prev = scores[i - 1][j - 2])
+                gapped -= GAP if gapped
+                if gapped.nil? || prev - GAP_START >= gapped
+                  gapped = prev - GAP_START
+                  gapped_from = j - 2
+                end
+              elsif gapped
+                gapped -= GAP
+              end
+              next unless lower[j] == qc
+
+              bonus = MATCH + bonus(chars, j)
+              if i.zero?
+                scores[i][j] = bonus
+                next
+              end
+
+              best = nil
+              if j >= 1 && (prev = scores[i - 1][j - 1])
+                best = prev + bonus + CONSECUTIVE
+                from[i][j] = j - 1
+              end
+              if gapped && (best.nil? || gapped + bonus > best)
+                best = gapped + bonus
+                from[i][j] = gapped_from
+              end
+              scores[i][j] = best
+            end
+          end
+
+          last = scores.last
+          j = last.each_index.select { |k| last[k] }.max_by { |k| [last[k], -k] }
+          return nil unless j
+
+          total = last[j]
+          positions = [j]
+          (q.size - 1).downto(1) { |i| positions.unshift(j = from[i][j]) }
+          total += EXACT if query.downcase == label.downcase
+          [total, positions]
+        end
+
+        def bonus(chars, j)
+          return BOUNDARY if j.zero?
+
+          before = chars[j - 1]
+          return BOUNDARY unless before.match?(/[[:alnum:]]/)
+          return CAMEL if before.match?(/[[:lower:]]/) && chars[j].match?(/[[:upper:]]/)
+
+          0
+        end
+
+        # The label with matched characters in the highlight style (runs painted together).
+        def highlight(shell, label, positions, base)
+          matched = positions.to_h { |p| [p, true] }
+          label.chars.each_with_index.chunk_while { |(_, a), (_, b)| matched[a] == matched[b] }.map do |run|
+            text = run.map(&:first).join
+            matched[run.first.last] ? shell.paint(text, :highlight) : shell.paint(text, *base)
+          end.join
+        end
+
+        def answered(shell, question, label)
+          "#{shell.symbol(:success)} #{question} #{shell.paint("·", :muted)} #{shell.paint(label, :accent)}"
+        end
+
+        def ask_line(shell, question, choices)
+          line = Prompt.read_line(shell, "#{question} ")
+          query = line.to_s.strip
+          raise Error, "no answer for #{question.inspect} (end of input)" if line.nil?
+          raise Error, "no answer for #{question.inspect}" if query.empty?
+
+          best = rank(query, choices).first
+          raise Error, "nothing matches #{query.inspect} for #{question.inspect}" unless best
+
+          shell.err_puts("#{shell.symbol(:success)} #{question} · #{best.choice.label}") unless shell.input_tty?
+          best.choice.value
+        end
+      end
+    end
+
+    extension :filter do
+      helpers do
+        def filter(question, choices, limit: 10, placeholder: "Type to filter")
+          list = Ext::Filter.choices(choices)
+          raise Error, "nothing to choose from for #{question.inspect}" if list.empty?
+          return Ext::Filter.ask_line(shell, question, list) unless shell.interactive?
+
+          CLI.require_bubbles!
+          model = Ext::Filter::Model.new(shell, question, choices, limit:, placeholder:)
+          Prompt.run(shell, model).value
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+# c14-format: numbers and links the way people read them.
+#
+#   say "added #{plural(1234, "package")} in #{duration(75.2)}"   # added 1,234 packages in 1m 15s
+#   say "#{bytes(1_500_000)} written"                             # 1.5 MB written
+#   say "#{plural(1, "child", "children")}"                       # 1 child
+#   say "opened #{link(pr.url, "PR ##{pr.number}")}"
+#
+# duration(seconds)       "120ms" under a second, "3.5s" under a minute, then "1m 15s", "2h 30m",
+#                         "1d 2h". It rounds before picking the unit, so 59.97 is "1m 0s".
+# bytes(count)            decimal units like npm and the OS file managers: "999 B", "12 kB",
+#                         "1.5 MB", "4.2 GB" (one decimal under 10, none above).
+# plural(count, word,     "3 packages", "1 package", "2 dependencies", "2 boxes"; counts get
+#        plural = nil)    thousands separators. Pass the plural for irregular words.
+# link(url, text = url)   on a terminal with colour, an OSC 8 hyperlink: "text", clickable to url
+#                         (terminals without OSC 8 support show just "text"). Off a terminal, or
+#                         with NO_COLOR, plain "text (url)", or just "url" when there's no text.
+#
+# duration, bytes and plural are the same on and off a terminal; only link looks at the shell.
+module R2UI
+  module CLI
+    module Ext
+      module HumanFormat
+        BYTE_UNITS = %w[B kB MB GB TB PB EB].freeze
+
+        module_function
+
+        def duration(seconds)
+          seconds = Float(seconds)
+          return "-#{duration(-seconds)}" if seconds.negative?
+
+          ms = (seconds * 1000).round
+          return "#{ms}ms" if ms < 1000
+
+          tenths = (seconds * 10).round
+          return "#{format("%.1f", tenths / 10.0)}s" if tenths < 600
+
+          total = seconds.round
+          return "#{total / 60}m #{total % 60}s" if total < 3600
+
+          minutes = (total / 60.0).round
+          return "#{minutes / 60}h #{minutes % 60}m" if minutes < 24 * 60
+
+          hours = (total / 3600.0).round
+          "#{hours / 24}d #{hours % 24}h"
+        end
+
+        def bytes(count)
+          count = Float(count)
+          return "-#{bytes(-count)}" if count.negative?
+
+          # Rounds before picking the unit, so 999_999 is "1 MB", not "1000 kB".
+          unit = 0
+          unit += 1 while unit < BYTE_UNITS.size - 1 && scaled(count, unit) >= 1000
+          value = scaled(count, unit)
+          "#{value == value.to_i ? value.to_i : value} #{BYTE_UNITS[unit]}"
+        end
+
+        def scaled(count, unit)
+          value = count / (1000**unit)
+          value < 10 && unit.positive? ? value.round(1) : value.round
+        end
+
+        def plural(count, word, plural = nil)
+          form = count == 1 ? word : plural || pluralize(word)
+          "#{delimit(count)} #{form}"
+        end
+
+        def link(shell, url, text)
+          return text.nil? || text == url ? url.to_s : "#{text} (#{url})" unless shell.color?
+
+          "\e]8;;#{url}\e\\#{text || url}\e]8;;\e\\"
+        end
+
+        def pluralize(word)
+          case word
+          when /[^aeiou]y\z/i then "#{word[0..-2]}ies"
+          when /(?:s|x|z|ch|sh)\z/i then "#{word}es"
+          else "#{word}s"
+          end
+        end
+
+        def delimit(count)
+          whole, fraction = count.to_s.split(".", 2)
+          whole = whole.reverse.scan(/\d{1,3}/).join(",").reverse.then { |w| whole.start_with?("-") ? "-#{w}" : w }
+          fraction ? "#{whole}.#{fraction}" : whole
+        end
+      end
+    end
+
+    extension :format do
+      helpers do
+        def duration(seconds) = Ext::HumanFormat.duration(seconds)
+
+        def bytes(count) = Ext::HumanFormat.bytes(count)
+
+        def plural(count, word, plural = nil) = Ext::HumanFormat.plural(count, word, plural)
+
+        def link(url, text = nil) = Ext::HumanFormat.link(shell, url, text)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+# c16-list: bullet and numbered lists.
+#
+#   list(%w[rails pg puma])
+#   list(["Build", %w[compile link], "Ship"], numbered: true)
+#
+# prints
+#
+#   • rails                       1. Build
+#   • pg                             1. compile
+#   • puma                           2. link
+#                                 2. Ship
+#
+# A nested Array is a list one level in, under the text of the item before it; numbered lists
+# number each level from 1 and right-align the numbers (" 9." over "10."). An item too long for
+# the shell's width wraps on spaces (a word longer than the line is broken), and every wrapped
+# line, like every line after a "\n" in an item, starts under the item's text, not its marker.
+# Widths are display widths, so wide characters (漢字, emoji) wrap correctly.
+#
+# On a terminal the markers are in the accent colour. Off a terminal (pipe, CI, NO_COLOR) the
+# same lines and layout, without escape codes. Lines go to stdout through the Shell, so inside a
+# live region (tasks, spinners) they print above it. Returns nil.
+module R2UI
+  module CLI
+    module Ext
+      module BulletList
+        # The narrowest text column a wrapped item gets, however deep or narrow the shell.
+        MIN_TEXT_WIDTH = 4
+
+        module_function
+
+        # The lines for `items`, each a String; `indent` is the column the level starts at.
+        def lines(shell, items, numbered:, indent: 0)
+          items = entries(items)
+          count = items.count { |item| !item.is_a?(Array) }
+          number_width = count.to_s.size
+          out = []
+          bullet = shell.theme.symbol(:bullet)
+          text_column = indent + (numbered ? number_width + 1 : Lipgloss.width(bullet)) + 1
+          text_width = [shell.width - text_column, MIN_TEXT_WIDTH].max
+          number = 0
+          items.each do |item|
+            if item.is_a?(Array)
+              out.concat(lines(shell, item, numbered:, indent: text_column))
+              next
+            end
+
+            number += 1
+            marker = numbered ? "#{number.to_s.rjust(number_width)}." : bullet
+            wrap(item.to_s, text_width).each_with_index do |line, i|
+              lead = i.zero? ? "#{" " * indent}#{shell.paint(marker, :accent)} " : " " * text_column
+              out << (line.empty? ? lead.rstrip : "#{lead}#{line}")
+            end
+          end
+          out
+        end
+
+        def entries(items)
+          return items if items.is_a?(Array)
+          raise ArgumentError, "list needs an Array of items, got #{items.class}" if items.is_a?(Hash) || !items.is_a?(Enumerable)
+
+          items.to_a
+        end
+
+        # Word-wraps text to `width` display cells; keeps the text's own line breaks.
+        def wrap(text, width)
+          text.split("\n", -1).flat_map { |paragraph| wrap_line(paragraph, width) }.then { |l| l.empty? ? [""] : l }
+        end
+
+        def wrap_line(text, width)
+          lines = []
+          current = +""
+          text.split(/ +/).each do |word|
+            next if word.empty?
+
+            if current.empty?
+              current = word
+            elsif Lipgloss.width(current) + 1 + Lipgloss.width(word) <= width
+              current << " " << word
+            else
+              lines << current
+              current = word
+            end
+            while Lipgloss.width(current) > width
+              head, current = split_at(current, width)
+              lines << head
+            end
+          end
+          lines << current
+          lines
+        end
+
+        # Splits a word into the longest head that fits in `width` cells and the rest.
+        def split_at(word, width)
+          head = +""
+          clusters = word.grapheme_clusters
+          while (cluster = clusters.first) && Lipgloss.width(head + cluster) <= width
+            head << clusters.shift
+          end
+          head << clusters.shift if head.empty? # a cluster wider than the line still has to go
+          [head, clusters.join]
+        end
+      end
+    end
+
+    extension :list do
+      helpers do
+        def list(items, numbered: false)
+          lines = Ext::BulletList.lines(shell, items, numbered:)
+          shell.puts(lines.join("\n")) unless lines.empty?
+          nil
+        end
+      end
+    end
+  end
+end