r2ui 0.1.0 → 0.2.0

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

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+# c07-box: a boxed notice, like npm's "Update available" or a "Next steps" box after scaffolding.
+#
+#   box "Created app\n\n  cd app\n  bin/dev", title: "Next steps"
+#   box "Update available 1.3.0 → 1.4.0\nRun gem update deployer", title: "deployer", style: :warn
+#
+# prints a rounded lipgloss border with the title in its top border:
+#
+#   ╭─ Next steps ─────╮
+#   │                  │
+#   │  Created app     │
+#   │                  │
+#   │    cd app        │
+#   │    bin/dev       │
+#   │                  │
+#   ╰──────────────────╯
+#
+# On a terminal the border and the title are drawn in the style's colour (a Theme name: :info,
+# the default, :success, :warn, :error, :accent, :muted, ...; the title also bold); the text keeps
+# its own styling. Off a terminal (a pipe, CI, NO_COLOR) it prints the same box, character for
+# character, without escape codes, so logs and `| cat` read the same.
+#
+# The box fits its text, never wider than the shell: longer lines wrap inside it (words first,
+# then hard breaks). `width:` fixes the outer width (border included), still capped at the shell.
+# `padding:` is the space inside the border: an Integer n is n blank lines above and below and 2n
+# columns either side (cells are about twice as tall as wide); `[vertical, horizontal]` sets both.
+# Multi-line text, tabs and wide characters (CJK, emoji) keep the right edge aligned. A title too
+# wide for the top border becomes the box's first line instead. Returns nil.
+module R2UI
+  module CLI
+    module Ext
+      module Box
+        BORDER = Lipgloss::Style.new.border(:rounded)
+        TOP_LEFT = "╭"
+        TOP_RIGHT = "╮"
+        TOP = "─"
+
+        module_function
+
+        def render(shell, text, title:, style:, padding:, width:)
+          shell.theme.options(style) # unknown names raise, coloured or not
+          vertical, horizontal = spacing(padding)
+          text = text.to_s
+          title = title&.to_s&.tr("\n", " ")
+          title = nil if title&.empty?
+          max = [width ? width.to_i : shell.width, shell.width].min
+          horizontal = [horizontal, [(max - 3) / 2, 0].max].min
+          inner = width ? max - 2 : natural(text, title, horizontal, max)
+          inner = [inner, 1].max
+
+          in_border = title && fits?(title, inner)
+          body = in_border || title.nil? ? text : "#{shell.paint(title, :heading, style)}\n#{text}"
+          plain = BORDER.padding(vertical, horizontal).width(inner).render(body)
+          lines = plain.split("\n")
+          lines[0] = in_border ? top(shell, title, inner, style) : shell.paint(lines[0], style)
+          lines[-1] = shell.paint(lines[-1], style)
+          lines[1..-2].each_with_index do |line, i|
+            lines[i + 1] = side(shell, line, style)
+          end
+          lines.join("\n")
+        end
+
+        def spacing(padding)
+          case padding
+          when Integer then [padding, padding * 2]
+          when Array
+            raise ArgumentError, "padding: needs [vertical, horizontal]" unless padding.size == 2
+
+            padding.map(&:to_i)
+          else raise ArgumentError, "padding: must be an Integer or [vertical, horizontal]"
+          end.map { |n| [n, 0].max }
+        end
+
+        # The inner width (padding included) that fits the text and the title, capped by `max`.
+        def natural(text, title, horizontal, max)
+          widest = text.split("\n").map { |line| Lipgloss.width(line.gsub("\t", "    ")) }.max || 0
+          inner = widest + (2 * horizontal)
+          inner = [inner, title_width(title)].max if title
+          [inner, max - 2].min
+        end
+
+        def title_width(title) = Lipgloss.width(title) + 4
+
+        def fits?(title, inner) = title_width(title) <= inner
+
+        # "╭─ Title ───╮": the title in the top border, the rest of it in the style's colour.
+        def top(shell, title, inner, style)
+          rest = inner - Lipgloss.width(title) - 3
+          "#{shell.paint("#{TOP_LEFT}#{TOP} ", style)}#{shell.paint(title, :heading, style)}" \
+            "#{shell.paint(" #{TOP * rest}#{TOP_RIGHT}", style)}"
+        end
+
+        # A middle line: its first and last characters are the border; the text between is left as is.
+        def side(shell, line, style)
+          left = line[0]
+          right = line[-1]
+          "#{shell.paint(left, style)}#{line[1..-2]}#{shell.paint(right, style)}"
+        end
+      end
+    end
+
+    extension :box do
+      helpers do
+        def box(text, title: nil, style: :info, padding: 1, width: nil)
+          shell.puts(Ext::Box.render(shell, text, title:, style:, padding:, width:))
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+# c19-choose: pick one of a list.
+#
+#   region = choose("Region?", %w[eu us ap], default: "eu")              # => "eu"
+#   plan = choose("Plan?", { "Free" => :free, "Pro ($9/mo)" => :pro })     # labels ⇒ values
+#
+# Choices are an Array (each item is its own label, shown with to_s) or a Hash of label ⇒ value.
+# `choose` returns the picked value. `default:` (a value or a label) is where the pointer starts
+# and the answer for an empty line or end of input off a terminal.
+#
+# On a terminal (Shell#interactive?) it asks inline, like gum choose:
+#
+#   ? Region? ↑/↓ move · enter pick
+#     › eu
+#       us
+#       ap
+#
+# ↑/↓ (or k/j) move and wrap around, home/end (g/G) jump to the ends, enter picks. More than 10
+# choices scroll, with "↑ 3 more" / "↓ 4 more" lines above and below. It leaves
+# "✔ Region? · eu" 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: a label (any case) or its 1-based number. An empty line or
+# end of input takes `default:`; without one, end of input is an error naming the question and
+# its choices. When a person can still type (stdin is a terminal, stdout piped) it lists the
+# choices as "  1) eu" lines on stderr, asks "Region? [eu] " and asks again after an answer it
+# can't read; from a pipe (`echo us | tool`, CI) it doesn't ask, records "✔ Region? · us" on
+# stderr, and an unknown answer is an error.
+module R2UI
+  module CLI
+    module Ext
+      module Choose
+        VISIBLE = 10
+
+        Option = Data.define(:label, :value)
+
+        # The inline prompt: a pointer list on R2UI::CLI::Prompt.
+        class Model < Prompt::Model
+          attr_reader :question, :options, :cursor
+
+          def initialize(shell, question, options, cursor)
+            super(shell)
+            @question = question
+            @options = options
+            @cursor = cursor || 0
+            @offset = 0
+            scroll
+          end
+
+          def view
+            return "#{shell.symbol(:error)} #{question}" if interrupted?
+            return Choose.answered(shell, question, options[@cursor].label) if done?
+
+            lines = ["#{shell.paint("?", :accent)} #{question} #{shell.paint("↑/↓ move · enter pick", :muted)}"]
+            lines << more("↑", @offset) if @offset.positive?
+            window.each_with_index { |option, i| lines << row(option, @offset + i == @cursor) }
+            below = options.size - @offset - window.size
+            lines << more("↓", below) if below.positive?
+            lines.join("\n")
+          end
+
+          private
+
+          def key(name, _message)
+            case name
+            when "enter" then return submit(options[@cursor].value)
+            when "up", "k", "shift+tab" then @cursor = (@cursor - 1) % options.size
+            when "down", "j", "tab" then @cursor = (@cursor + 1) % options.size
+            when "home", "g", "pgup" then @cursor = name == "pgup" ? [@cursor - VISIBLE, 0].max : 0
+            when "end", "G", "pgdown" then @cursor = name == "pgdown" ? [@cursor + VISIBLE, options.size - 1].min : options.size - 1
+            else return nil
+            end
+            scroll
+            [self, nil]
+          end
+
+          def window = options[@offset, VISIBLE]
+
+          # Keeps the cursor inside the visible window, moving it as little as possible.
+          def scroll
+            @offset = @cursor if @cursor < @offset
+            @offset = @cursor - VISIBLE + 1 if @cursor >= @offset + VISIBLE
+          end
+
+          # The pointer marks the choice without colour too (NO_COLOR on a terminal).
+          def row(option, selected)
+            label = option.label
+            selected ? "  #{shell.paint("#{shell.theme.symbol(:pointer)} #{label}", :highlight)}" : "    #{label}"
+          end
+
+          def more(arrow, count) = "    #{shell.paint("#{arrow} #{count} more", :muted)}"
+        end
+
+        module_function
+
+        # Choices as Options: an Array's items are their own labels, a Hash maps label ⇒ value.
+        def options(choices)
+          list = choices.is_a?(Hash) ? choices.map { |label, value| Option.new(label.to_s, value) } : choices.map { |c| Option.new(c.to_s, c) }
+          raise ArgumentError, "choose needs at least one choice" if list.empty?
+
+          list
+        end
+
+        # The index of `default` (a value or a label) in options; nil for no default.
+        def default_index(options, default)
+          return nil if default.nil?
+
+          options.index { |o| o.value == default } || options.index { |o| o.label == default.to_s } ||
+            raise(ArgumentError, "default #{default.inspect} is not one of the choices")
+        end
+
+        def answered(shell, question, label)
+          "#{shell.symbol(:success)} #{question} #{shell.paint("·", :muted)} #{shell.paint(label, :accent)}"
+        end
+
+        # The Option a typed line names (a label, any case, or a 1-based number); nil if none.
+        def parse(line, options)
+          answer = line.to_s.strip
+          return options[answer.to_i - 1] if answer.match?(/\A\d+\z/) && answer.to_i.between?(1, options.size)
+
+          options.find { |o| o.label == answer } || options.find { |o| o.label.casecmp?(answer) }
+        end
+
+        def ask_line(shell, question, options, default)
+          labels = options.map(&:label).join(", ")
+          options.each_with_index { |o, i| shell.err_puts("  #{i + 1}) #{o.label}") } if shell.input_tty?
+          hint = default ? "[#{options[default].label}] " : ""
+          loop do
+            line = Prompt.read_line(shell, "#{question} #{hint}")
+            if line.nil? || line.strip.empty?
+              option = default && options[default]
+              raise Error, "no answer for #{question.inspect} (choose one of: #{labels}); pass it as an option or give a default" if line.nil? && !option
+            else
+              option = parse(line, options)
+              raise Error, "#{line.strip.inspect} is not a choice for #{question.inspect} (choose one of: #{labels})" if !option && !shell.input_tty?
+            end
+            if option
+              shell.err_puts(answered(shell, question, option.label)) unless shell.input_tty?
+              return option.value
+            end
+            raise Error, "no answer for #{question.inspect} (choose one of: #{labels})" unless shell.input_tty?
+
+            shell.err_puts("Please pick one of the choices or its number (1-#{options.size}).")
+          end
+        end
+      end
+    end
+
+    extension :choose do
+      helpers do
+        def choose(question, choices, default: nil)
+          options = Ext::Choose.options(choices)
+          index = Ext::Choose.default_index(options, default)
+          return Ext::Choose.ask_line(shell, question, options, index) unless shell.interactive?
+
+          Prompt.run(shell, Ext::Choose::Model.new(shell, question, options, index)).value
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+# c20-choose-many: pick several from a list.
+#
+#   choose_many("Features?", %w[api web worker])                       # => ["api", "worker"]
+#   choose_many("Features?", %w[api web worker], selected: %w[web], min: 1, max: 2)
+#   choose_many("Install?", { "API server" => :api, "Web app" => :web }) # => [:api]
+#
+# Choices are an Array (each item is its own label, shown with to_s) or a Hash of label => value.
+# `selected:` lists the values checked at the start (labels work too). The chosen values come back
+# in list order, whatever order they were picked in.
+#
+# On a terminal (Shell#interactive?) it shows a checkbox list inline, like gum choose --no-limit:
+#
+#   ? Features?
+#   › ◯ api
+#     ◉ web
+#     ◯ worker
+#   space toggle · a all · enter submit
+#
+# ↑/↓ (k/j) move (wrapping), space toggles, a checks all (or clears all when all are checked), enter
+# submits once the count is within `min:`..`max:` (otherwise it says "Pick at least 1" and waits).
+# Past 10 items the list scrolls, with "↑ 3 more" / "↓ 4 more" hints. It leaves
+# "✔ Features? · api, web" ("· none" for an empty answer) in the scrollback. ctrl+c or esc raises
+# Interrupt (a command exits 130) after the terminal is restored.
+#
+# Off a terminal it reads one comma-separated line of labels (any case) or 1-based numbers:
+# "web, 1". An empty line or end of input means `selected:`. When a person can still type (stdin
+# is a terminal, stdout piped) it lists the numbered choices and asks
+# "Features? (comma-separated) [web] " on stderr, asking again after an answer it can't use; from
+# a pipe (`echo api,web | tool`, CI) it doesn't ask, records "✔ Features? · api, web" on stderr,
+# and an unknown choice or a count outside min..max is an error naming the question.
+module R2UI
+  module CLI
+    module Ext
+      module ChooseMany
+        PAGE = 10
+        HINT = "space toggle · a all · enter submit"
+
+        # Labels and values, in list order.
+        Choices = Struct.new(:labels, :values) do
+          def size = labels.size
+
+          # Indexes for `selected:` values (or labels); raises on one that isn't a choice.
+          def indexes_of(items)
+            Array(items).map do |item|
+              values.index(item) || labels.index(item.to_s) or
+                raise ArgumentError, "selected: #{item.inspect} is not one of the choices"
+            end
+          end
+
+          # The index for a typed label or 1-based number; nil when it matches nothing.
+          def lookup(token)
+            if token.match?(/\A\d+\z/)
+              n = token.to_i
+              return n - 1 if n.between?(1, size)
+
+              return nil
+            end
+            labels.index(token) || labels.index { |label| label.casecmp?(token) }
+          end
+        end
+
+        # The inline prompt: a Bubbletea model on R2UI::CLI::Prompt.
+        class Model < Prompt::Model
+          attr_reader :question
+
+          def initialize(shell, question, choices, checked, min, max)
+            super(shell)
+            @question = question
+            @choices = choices
+            @checked = checked
+            @min = min
+            @max = max
+            @cursor = 0
+            @offset = 0
+            @problem = nil
+          end
+
+          def view
+            return "#{shell.symbol(:error)} #{question}" if interrupted?
+            return ChooseMany.answered(shell, question, @choices, value_indexes) if done?
+
+            lines = ["#{shell.paint("?", :accent)} #{question}"]
+            lines << shell.paint("  ↑ #{@offset} more", :muted) if @offset.positive?
+            visible.each { |i| lines << row(i) }
+            below = @choices.size - (@offset + visible.size)
+            lines << shell.paint("  ↓ #{below} more", :muted) if below.positive?
+            lines << (@problem ? shell.paint(@problem, :warn) : shell.paint(HINT, :muted))
+            lines.join("\n")
+          end
+
+          private
+
+          def key(name, _message)
+            case name
+            when "up", "k" then move(-1)
+            when "down", "j" then move(1)
+            when "space", " " then toggle(@cursor)
+            when "a" then toggle_all
+            when "enter" then return finish
+            else return nil
+            end
+            [self, nil]
+          end
+
+          def move(step)
+            @cursor = (@cursor + step) % @choices.size
+            @offset = @cursor if @cursor < @offset
+            @offset = @cursor - PAGE + 1 if @cursor >= @offset + PAGE
+          end
+
+          def toggle(index)
+            @problem = nil
+            @checked.include?(index) ? @checked.delete(index) : @checked << index
+          end
+
+          def toggle_all
+            @problem = nil
+            @checked = @checked.size == @choices.size ? [] : (0...@choices.size).to_a
+          end
+
+          def finish
+            @problem = ChooseMany.count_problem(@checked.size, @min, @max)
+            return [self, nil] if @problem
+
+            @indexes = @checked.sort
+            submit(@indexes.map { |i| @choices.values[i] })
+          end
+
+          def value_indexes = @indexes || []
+
+          def visible = (@offset...[@offset + PAGE, @choices.size].min).to_a
+
+          def row(index)
+            pointer = index == @cursor ? shell.paint(shell.theme.symbol(:pointer), :accent) : " "
+            box = @checked.include?(index) ? shell.paint("◉", :success) : shell.paint("◯", :muted)
+            label = @choices.labels[index]
+            label = shell.paint(label, :highlight) if index == @cursor
+            "#{pointer} #{box} #{label}"
+          end
+        end
+
+        module_function
+
+        def choices(list)
+          raise ArgumentError, "choose_many needs at least one choice" if list.nil? || list.empty?
+
+          if list.is_a?(Hash)
+            Choices.new(list.keys.map(&:to_s), list.values)
+          else
+            Choices.new(list.map(&:to_s), list.to_a)
+          end
+        end
+
+        def check_bounds(min, max)
+          raise ArgumentError, "min: must be 0 or more" if min.negative?
+          raise ArgumentError, "max: (#{max}) is less than min: (#{min})" if max && max < min
+        end
+
+        def build_model(shell, question, list, selected, min, max)
+          check_bounds(min, max)
+          choices = choices(list)
+          Model.new(shell, question, choices, choices.indexes_of(selected).uniq, min, max)
+        end
+
+        # "Pick at least 1" / "Pick at most 2" when `count` is out of bounds, else nil.
+        def count_problem(count, min, max)
+          return "Pick at least #{min}" if count < min
+
+          "Pick at most #{max}" if max && count > max
+        end
+
+        def answered(shell, question, choices, indexes)
+          answer = indexes.empty? ? shell.paint("none", :muted) : shell.paint(indexes.map { |i| choices.labels[i] }.join(", "), :accent)
+          "#{shell.symbol(:success)} #{question} #{shell.paint("·", :muted)} #{answer}"
+        end
+
+        # Sorted indexes for a typed line, `default` for an empty one; raises ArgumentError naming
+        # the first token it can't read.
+        def parse(line, choices, default)
+          tokens = line.to_s.split(",").map(&:strip).reject(&:empty?)
+          return default if tokens.empty?
+
+          tokens.map { |token| choices.lookup(token) || raise(ArgumentError, token) }.uniq.sort
+        end
+
+        def ask_line(shell, question, list, selected, min, max)
+          check_bounds(min, max)
+          choices = choices(list)
+          default = choices.indexes_of(selected).uniq.sort
+          person = shell.input_tty?
+          prompt = "#{question} (comma-separated) "
+          prompt += "[#{default.map { |i| choices.labels[i] }.join(", ")}] " unless default.empty?
+          list_choices(shell, choices) if person
+          loop do
+            line = Prompt.read_line(shell, prompt)
+            problem =
+              begin
+                indexes = parse(line, choices, default)
+                count_problem(indexes.size, min, max)
+              rescue ArgumentError => e
+                bad = e.message
+                person ? "Unknown choice #{bad.inspect}" : "unknown choice #{bad.inspect} for #{question.inspect} (choices: #{choices.labels.join(", ")})"
+              end
+            unless problem
+              shell.err_puts(plain_answer(shell, question, choices, indexes)) unless person
+              return indexes.map { |i| choices.values[i] }
+            end
+            raise Error, (bad ? problem : "#{problem.sub("Pick", "pick")} for #{question.inspect}") unless person
+            raise Error, "no answer for #{question.inspect}: #{problem.downcase}" if line.nil?
+
+            shell.err_puts("#{problem}.")
+          end
+        end
+
+        def list_choices(shell, choices)
+          digits = choices.size.to_s.size
+          choices.labels.each_with_index { |label, i| shell.err_puts("  #{(i + 1).to_s.rjust(digits)}. #{label}") }
+        end
+
+        def plain_answer(shell, question, choices, indexes)
+          answer = indexes.empty? ? "none" : indexes.map { |i| choices.labels[i] }.join(", ")
+          "#{shell.symbol(:success)} #{question} · #{answer}"
+        end
+      end
+    end
+
+    extension :choose_many do
+      helpers do
+        def choose_many(question, choices, selected: [], min: 0, max: nil)
+          unless shell.interactive?
+            return Ext::ChooseMany.ask_line(shell, question, choices, selected, min, max)
+          end
+
+          Prompt.run(shell, Ext::ChooseMany.build_model(shell, question, choices, selected, min, max)).value
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# c31-color-option: let the person running a tool turn colour on or off.
+#
+#   R2UI.cli "deployer" do
+#     color_option                      # on the root: every command takes --color / --no-color
+#     command(:deploy) { run { say "Deployed", :success } }
+#   end
+#
+#   deployer deploy --no-color          # on a terminal: no colour codes, live redraw still happens
+#   deployer deploy --color | less -R   # in a pipe: styled as on a terminal, one line per event
+#
+# Without either flag the shell decides as usual (NO_COLOR, FORCE_COLOR, a terminal or not). Given,
+# the flag wins over those variables, and the last one given wins (`--color --no-color` is off).
+# It only changes colour: a pipe still gets plain stable lines (no spinners or cursor movement),
+# and a terminal still redraws live output in place.
+#
+# The flag is applied right after argv is parsed, so usage errors about arguments, the command's
+# output and its error report all follow it. `tool --no-color --help` is the exception: the core
+# prints help before any extension hook runs.
+#
+# Lipgloss picks its colour profile once from the process's stdout, which is "no colour" when stdout
+# is piped; `--color` raises that to the 16-colour ANSI profile (the theme uses palette numbers), so
+# the styles really come out in a pipe.
+module R2UI
+  module CLI
+    module Ext
+      module ColorOption
+        module_function
+
+        def apply(shell, on)
+          shell.color = on
+          force_lipgloss_colour if on
+        end
+
+        def force_lipgloss_colour
+          renderer = R2UI::Compat::Gloss::Renderer
+          renderer.color_profile = :ansi if renderer.color_profile.to_sym == :ascii
+        end
+      end
+    end
+
+    extension :color_option do
+      dsl(:command) do
+        # Adds --color / --no-color to every command (on the root only).
+        def color_option
+          raise ArgumentError, "color_option belongs on the root command" unless definition.root?
+
+          declare(:color_option, true)
+        end
+      end
+
+      setup do
+        if declared(:color_option).any?
+          flag :color, default: nil, desc: "Colour the output (--no-color turns it off; default: on a terminal)"
+        end
+      end
+
+      after_parse do
+        Ext::ColorOption.apply(shell, options[:color]) if program.declared(:color_option).any? && given?(:color)
+      end
+    end
+  end
+end