r2ui 0.1.0 → 0.2.0

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# c06-log: styled log levels, one line per message.
+#
+#   info    "Using node 20"                # ℹ Using node 20             stdout
+#   success "Installed 42 packages"        # ✔ Installed 42 packages    stdout
+#   warn    "3 deprecated packages"        # ⚠ 3 deprecated packages    stderr
+#   error   "Build failed"                 # ✖ Build failed             stderr
+#   debug   "cache hit for react@18"       # • cache hit for react@18   stderr, only when asked
+#
+# On a terminal the symbol takes its level's colour (blue, green, yellow, red) and the message
+# stays plain; a debug line is muted. Off a terminal (a pipe, CI, NO_COLOR) the same lines print
+# with no escape codes. A multi-line message indents its other lines under the first:
+#
+#   ⚠ Peer dependency missing
+#     react@18 is required by app
+#
+# `info` and `success` write to stdout; `warn`, `error` and `debug` to stderr, so `tool | jq`
+# stays clean. `debug` prints only when the command's `options[:verbose]` is true (a `flag
+# :verbose` on the root gives every command `-v`) or the `R2UI_DEBUG` variable is set (and not
+# "0"); otherwise it does nothing.
+#
+# `warn` replaces Kernel#warn inside commands and in scripts that `include R2UI::CLI::Helpers`
+# (several messages become one entry, a line each; Kernel's `uplevel:` and `category:` are
+# accepted and ignored). Inside a Live region (tasks, spinners, progress) the lines print above
+# it. Every helper returns nil.
+module R2UI
+  module CLI
+    module Ext
+      module Log
+        # Level => [theme symbol, theme style for the symbol, stream].
+        LEVELS = {
+          info: [:info, :info, :out],
+          success: [:success, :success, :out],
+          warn: [:warn, :warn, :err],
+          error: [:error, :error, :err],
+          debug: [:bullet, :muted, :err]
+        }.freeze
+
+        module_function
+
+        def write(shell, level, message)
+          symbol_name, style, stream = LEVELS.fetch(level)
+          lines = message.to_s.chomp.split("\n", -1)
+          lines = [""] if lines.empty?
+          symbol = shell.paint(shell.theme.symbol(symbol_name), style)
+          first, *rest = lines
+          rest = rest.map { |line| line.empty? ? line : "  #{line}" }
+          rest = rest.map { |line| shell.paint(line, :muted) } if level == :debug
+          first = shell.paint(first, :muted) if level == :debug
+          text = ["#{symbol} #{first}", *rest].join("\n")
+          stream == :out ? shell.puts(text) : shell.err_puts(text)
+          nil
+        end
+
+        def debug?(context)
+          value = context.shell.env["R2UI_DEBUG"]
+          return true if value && !value.empty? && value != "0"
+
+          context.is_a?(Context) && context.options[:verbose] == true
+        end
+      end
+    end
+
+    extension :log do
+      helpers do
+        def info(message) = Ext::Log.write(shell, :info, message)
+
+        def success(message) = Ext::Log.write(shell, :success, message)
+
+        # Kernel#warn's signature, so it can stand in for it.
+        def warn(*messages, uplevel: nil, category: nil) # rubocop:disable Lint/UnusedMethodArgument
+          messages = messages.flatten
+          return nil if messages.empty?
+
+          Ext::Log.write(shell, :warn, messages.map { |m| m.to_s.chomp }.join("\n"))
+        end
+
+        def error(message) = Ext::Log.write(shell, :error, message)
+
+        def debug(message)
+          return nil unless Ext::Log.debug?(self)
+
+          Ext::Log.write(shell, :debug, message)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+# c12-pager: show long output in a pager, the way git log and gh do.
+#
+#   pager(changelog)                       # => nil
+#   pager(rows.map { |r| format(r) }.join("\n"))
+#
+# On a terminal (Shell#interactive?), when the text is taller than the screen (wrapped lines count
+# by their rows at the shell width), it is piped through `$PAGER`, or `less -R -F -X` when that is
+# unset: -R keeps colours, -F quits at once if it fits after all, -X leaves the text in the
+# scrollback. `pager` waits for the pager to exit. ctrl+c belongs to the pager while it runs (the
+# tool ignores SIGINT until it exits, like git), and the previous SIGINT handler is put back on
+# every path; nothing else about the terminal is touched, so there is nothing else to restore.
+# Quitting the pager before the end of the text is fine.
+#
+# Otherwise it prints the text through the shell, unchanged, with a final newline: in a pipe or CI
+# (`tool log | grep fix`), with `TERM=dumb`, when the text fits on the screen, when `$PAGER` is
+# empty or `cat`, inside a live region (it prints above it), and when the pager program can't be
+# started (not installed: it falls back to printing, no error).
+#
+# `$PAGER` is split like a shell would split it (`PAGER="less -S"`, quotes allowed) and run
+# without a shell.
+module R2UI
+  module CLI
+    module Ext
+      module Pager
+        DEFAULT = "less -R -F -X"
+
+        module_function
+
+        def show(shell, text)
+          text = text.to_s
+          return if text.empty?
+
+          text = "#{text}\n" unless text.end_with?("\n")
+          return if page?(shell, text) && run(shell, command(shell), text)
+
+          shell.puts(text.chomp) # above a live region while one draws
+        end
+
+        def page?(shell, text) = !shell.live && shell.interactive? && rows(text, shell.width) > shell.height
+
+        # $PAGER split into words; nil when it means "don't page" (empty, `cat`, unbalanced quotes).
+        def command(shell)
+          words = Shellwords.split(shell.env["PAGER"] || DEFAULT)
+          words unless words.empty? || words == ["cat"]
+        rescue ArgumentError
+          nil
+        end
+
+        # Screen rows the text takes at `width` columns.
+        def rows(text, width)
+          text.split("\n").sum { |line| [(Lipgloss.width(line) + width - 1) / width, 1].max }
+        end
+
+        # Runs the pager with the text on its stdin and waits for it. False when it couldn't start.
+        def run(shell, command, text)
+          return false unless command
+
+          reader, writer = IO.pipe
+          begin
+            pid = Process.spawn(shell.env.to_h, [command.first, command.first], *command.drop(1),
+                                in: reader, out: shell.output, err: shell.error)
+          rescue SystemCallError, TypeError, ArgumentError # not installed, or IOs without a descriptor
+            return false
+          ensure
+            reader.close
+          end
+          previous = trap("INT", "IGNORE")
+          begin
+            writer.write(text)
+          rescue Errno::EPIPE
+            nil # quit before the end
+          ensure
+            writer.close
+            Process.wait(pid)
+            trap("INT", previous)
+          end
+          true
+        ensure
+          writer.close unless writer.nil? || writer.closed?
+        end
+      end
+    end
+
+    extension :pager do
+      helpers do
+        def pager(text)
+          Ext::Pager.show(shell, text)
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# c09-pairs: an aligned key/value summary, like the block `npm publish` or `gh repo view` prints.
+#
+#   pairs({ "Version" => "1.4.0", "Env" => "production", "Region" => nil }, title: "Deploy")
+#
+# prints
+#
+#   Deploy
+#     Version  1.4.0
+#     Env      production
+#     Region   —
+#
+# Keys are right-padded to the longest key (by display width, so wide characters line up) and
+# followed by two spaces. With a `title:` the title is its own line and the pairs are indented
+# under it by two spaces; without one they start at the left edge. A nil value shows "—"; other
+# keys and values are shown with `to_s`. A multi-line value continues under the value column. An
+# empty hash prints only the title (or nothing). Pairs may also be given as an Array of
+# [key, value] (order and repeated keys kept). Returns nil.
+#
+# On a terminal (Shell#color?) the title is bold, keys and the "—" are muted, values are plain.
+# Off a terminal, or with NO_COLOR, it prints the same text and alignment with no escape codes.
+# Inside a Live region (a `tasks` step) the lines print above it, as `say` does.
+module R2UI
+  module CLI
+    module Ext
+      module Pairs
+        GAP = "  "
+        INDENT = "  "
+        NONE = "—"
+
+        module_function
+
+        def lines(shell, entries, title)
+          entries = entries.to_a.map { |key, value| [key.to_s, value] }
+          out = []
+          out << shell.paint(title.to_s, :heading) unless title.nil?
+          indent = title.nil? ? "" : INDENT
+          width = entries.map { |key, _| Lipgloss.width(key) }.max || 0
+          entries.each do |key, value|
+            pad = " " * (width - Lipgloss.width(key))
+            first, *rest = value.nil? ? [shell.paint(NONE, :muted)] : value.to_s.split("\n", -1)
+            label = "#{indent}#{shell.paint(key, :muted)}"
+            out << (first.to_s.empty? ? label : "#{label}#{pad}#{GAP}#{first}")
+            continuation = indent + (" " * (width + GAP.length))
+            rest.each { |line| out << (line.empty? ? "" : "#{continuation}#{line}") }
+          end
+          out
+        end
+      end
+    end
+
+    extension :pairs do
+      helpers do
+        def pairs(entries, title: nil)
+          Ext::Pairs.lines(shell, entries, title).each { |line| shell.puts(line) }
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+# c13-parallel: concurrent jobs with live status, like `pnpm -r` or turbo. Each job has one status
+# line: queued, spinning while it runs, then ✔ / ✖ with its timing.
+#
+#   results = parallel(max: 4) do
+#     job("api") { build_api }                                  # the block's value is kept
+#     job("web") { |j| bundle { |n| j.detail = "#{n} modules" } }
+#     job("docs") { build_docs }
+#   end                                                         # => { "api" => ..., "web" => ..., "docs" => ... }
+#
+# On a terminal (Shell#live?) every job's line is redrawn together:
+#
+#   ✔ api 1.2s
+#   ⠹ web · 412 modules
+#   ○ docs
+#
+# and the final lines stay in the scrollback. When there are more jobs than the terminal has rows,
+# finished jobs print above the region as they end and the region shows only the running jobs and
+# how many are queued. Off a terminal each job prints one line when it ends, in the order they end
+# ("✔ api 1.2s", "✖ web · Module not found 0.4s"): no spinner frames, no escape codes.
+#
+# The `parallel` block declares the jobs; they run after it on up to `max` threads (default 4,
+# pnpm's), started in declaration order. A job's block runs on its own thread but sees the same
+# `args`, `options` and helpers; `say` inside a job prints above the lines. `j.detail = "..."` and
+# `j.title = "..."` change its line while it runs.
+#
+# A job that raises shows ✖ with the error's message; the other jobs carry on. When every job has
+# ended, `parallel` raises a `CLI::Error` naming the failed jobs, with the first error to happen as
+# its `cause` (a command exits 1 with "✖ 2 jobs failed: web, docs"). Ctrl+c, `halt` or `exit`
+# inside a job stops the rest at once: running and queued jobs show "– name (cancelled)" and the
+# interrupt propagates (exit 130 for ctrl+c). Otherwise it returns the jobs' values as a Hash by
+# job name, in declaration order.
+#
+# Jobs don't nest: `parallel` inside a job raises. Don't start `tasks`, `spin` or another live
+# helper inside a job either; there is one live region at a time.
+require "monitor"
+
+module R2UI
+  module CLI
+    module Ext
+      module Parallel
+        DEFAULT_MAX = 4
+
+        # Raised when jobs failed; `failures` maps each failed job's name to its error.
+        class Failed < Error
+          attr_reader :failures
+
+          def initialize(failures)
+            @failures = failures
+            names = failures.keys.map(&:to_s)
+            super(names.one? ? "job #{names.first} failed: #{failures.values.first.message}" : "#{names.size} jobs failed: #{names.join(", ")}")
+          end
+        end
+
+        Job = Struct.new(:name, :title, :block, :status, :detail, :started, :finished, :value, :error) do
+          def elapsed = finished && started ? finished - started : nil
+        end
+
+        # What a job's block gets: change its title or detail while it runs.
+        class Handle
+          def initialize(job, pool)
+            @job = job
+            @pool = pool
+          end
+
+          def name = @job.name
+
+          def title = @job.title
+
+          def title=(text)
+            @pool.change { @job.title = text.to_s }
+          end
+
+          def detail=(text)
+            @pool.change { @job.detail = text&.to_s }
+          end
+        end
+
+        # The jobs a `parallel` block declared, and how they run and draw.
+        class Pool
+          def initialize(shell, max)
+            @shell = shell
+            @max = max
+            @jobs = []
+            @lock = Monitor.new
+            @live = nil
+          end
+
+          def add(name, block)
+            raise ArgumentError, "job needs a block" unless block
+            raise ArgumentError, "job #{name} is declared twice" if @jobs.any? { |j| j.name.to_s == name.to_s }
+
+            @jobs << Job.new(name:, title: name.to_s, block:, status: :queued)
+          end
+
+          # Runs every job; returns { name => value }. Raises Failed after all end if any failed.
+          def run
+            return {} if @jobs.empty?
+
+            @live = Live.new(@shell) { |frame| view(frame) }
+            @compact = @live.live? && @jobs.size > @shell.height - 1
+            @live.clear = @compact # every result is already printed above the region
+            @live.run { run_jobs }
+            failed = @jobs.select { |j| j.status == :failed }
+            unless failed.empty?
+              first = failed.min_by(&:finished).error
+              raise Failed.new(failed.to_h { |j| [j.name, j.error] }), cause: first
+            end
+            @jobs.to_h { |j| [j.name, j.value] }
+          end
+
+          # Updates a job's state, then redraws (never while holding the lock: the Live ticker
+          # takes its own lock and then calls `view`).
+          def change(&)
+            @lock.synchronize(&)
+            @live&.refresh
+            nil
+          end
+
+          def view(frame)
+            @lock.synchronize do
+              return compact_view(frame) if @compact
+
+              @jobs.map { |job| line(job, frame) }.join("\n")
+            end
+          end
+
+          private
+
+          def run_jobs
+            queue = Queue.new
+            @jobs.each { |job| queue << job }
+            queue.close
+            events = Queue.new
+            workers = Array.new([@max, @jobs.size].min) do
+              Thread.new do
+                Thread.current.report_on_exception = false
+                Thread.current[:r2ui_cli_parallel_job] = true
+                while (job = queue.pop)
+                  fatal = run_job(job)
+                  events << (fatal ? [:fatal, fatal] : [:done, job])
+                  break if fatal
+                end
+              end
+            end
+            ended = 0
+            while ended < @jobs.size
+              kind, value = events.pop
+              raise value if kind == :fatal
+
+              ended += 1
+            end
+          ensure
+            stop(workers) if workers
+          end
+
+          # Runs one job; returns an exception that must stop every job (ctrl+c, halt, exit).
+          def run_job(job)
+            change do
+              job.status = :running
+              job.started = now
+            end
+            value = job.block.call(Handle.new(job, self))
+            finish(job, :done) { job.value = value }
+            nil
+          rescue StandardError => e
+            finish(job, :failed) { job.error = e }
+            nil
+          rescue Exception => e # rubocop:disable Lint/RescueException -- ctrl+c, halt and exit stop the pool
+            finish(job, e.is_a?(Halt) ? :done : :failed) { job.error = e }
+            e
+          end
+
+          # Kills jobs still running (after ctrl+c or a fatal job) and marks the unfinished ones
+          # cancelled.
+          def stop(workers)
+            workers.each(&:kill)
+            workers.each { |w| w.join(5) }
+            @jobs.each { |job| finish(job, :cancelled) if %i[queued running].include?(job.status) }
+          end
+
+          def finish(job, status)
+            text = nil
+            change do
+              yield if block_given?
+              job.status = status
+              job.finished = now if job.started
+              text = line(job, 0) if !@live.running? || @compact
+            end
+            @shell.puts(text) if text
+          end
+
+          def compact_view(frame)
+            running = @jobs.select { |j| j.status == :running }
+            queued = @jobs.count { |j| j.status == :queued }
+            lines = running.first([@shell.height - 2, 1].max).map { |job| line(job, frame) }
+            more = running.size - lines.size
+            notes = []
+            notes << "#{more} more running" if more.positive?
+            notes << "#{queued} queued" if queued.positive?
+            lines << "#{@shell.symbol(:pending)} #{@shell.paint(notes.join(" · "), :pending)}" unless notes.empty?
+            lines.join("\n")
+          end
+
+          def line(job, frame)
+            title = job.title
+            detail = job.error.is_a?(StandardError) ? job.error.message.lines.first.to_s.chomp : job.detail
+            detail = detail && !detail.empty? ? @shell.paint(" · #{detail}", :muted) : ""
+            time = job.elapsed ? " #{@shell.paint(Parallel.duration(job.elapsed), :muted)}" : ""
+            case job.status
+            when :queued 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 :cancelled then "#{@shell.symbol(:skipped)} #{@shell.paint("#{title} (cancelled)", :skipped)}"
+            end
+          end
+
+          def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+
+        module_function
+
+        # 0.12 → "120ms", 3.456 → "3.5s", 75 → "1m 15s" (the task list's format).
+        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 pool a `parallel` block is declaring on this thread (nil outside one).
+        def collecting = Thread.current[:r2ui_cli_parallel]
+
+        def collecting=(pool)
+          Thread.current[:r2ui_cli_parallel] = pool
+        end
+
+        def in_job? = Thread.current[:r2ui_cli_parallel_job]
+      end
+    end
+
+    extension :parallel do
+      helpers do
+        def parallel(max: Ext::Parallel::DEFAULT_MAX, &block)
+          raise ArgumentError, "parallel needs a block" unless block
+          raise ArgumentError, "max must be a positive Integer, not #{max.inspect}" unless max.is_a?(Integer) && max.positive?
+          raise Error, "parallel can't be nested" if Ext::Parallel.collecting || Ext::Parallel.in_job?
+
+          pool = Ext::Parallel::Pool.new(shell, max)
+          begin
+            Ext::Parallel.collecting = pool
+            block.call
+          ensure
+            Ext::Parallel.collecting = nil
+          end
+          pool.run
+        end
+
+        def job(name, &block)
+          pool = Ext::Parallel.collecting
+          raise Error, "job #{name} must be declared inside a parallel block" unless pool
+
+          pool.add(name, block)
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "io/console"
+
+# c18-password: hidden input for tokens and passwords.
+#
+#   token = password("Token?")                           # => "s3cret"
+#   pass  = password("New password?", confirm: true)     # asks twice, again on a mismatch
+#
+# On a terminal (Shell#interactive?) it asks inline with a bubbles TextInput in password echo
+# mode, one • per typed character (backspace, ctrl+u, home/end edit as in bubbles):
+#
+#   ? Token? ••••••█
+#
+# enter submits and leaves "✔ Token? · ••••••" in the scrollback: always six bullets, so the
+# line gives away neither the value nor its length. With `confirm: true` it then asks
+# "? Token? (again)"; when the two differ it starts over with "They didn't match. Try again."
+# under the input. ctrl+c or esc raises Interrupt (a command exits 130) after the terminal is
+# restored.
+#
+# Off a terminal it reads one line (spaces kept, only the line ending removed):
+# - stdin is a terminal, stdout piped (`tool | tee log`): asks "Token? " on stderr and reads with
+#   echo off (IO#noecho), so the value never appears on the screen; `confirm: true` asks again
+#   ("Token? (again) ") and starts over on a mismatch.
+# - from a pipe (`echo "$TOKEN" | tool`, CI): reads silently and records "✔ Token? · ••••••" on
+#   stderr; with `confirm: true` it reads a second line and a mismatch is an error.
+# End of input is an error naming the question. The value itself is never printed or logged.
+module R2UI
+  module CLI
+    module Ext
+      module Password
+        MASK = "••••••"
+        BULLET = "•"
+        AGAIN = "(again)"
+        MISMATCH = "They didn't match. Try again."
+
+        # The inline prompt: a TextInput in password echo mode on R2UI::CLI::Prompt::Model.
+        class Model < Prompt::Model
+          attr_reader :question
+
+          def initialize(shell, question, confirm)
+            super(shell)
+            @question = question
+            @confirm = confirm
+            @first = nil
+            @mismatch = false
+            self.component = Password.input
+          end
+
+          def init = [self, component.focus]
+
+          def view
+            return "#{shell.symbol(:error)} #{question}" if interrupted?
+            return Password.answered(shell, question) if done?
+
+            label = @first.nil? ? question : "#{question} #{shell.paint(AGAIN, :muted)}"
+            line = "#{shell.paint("?", :accent)} #{label} #{component.view}"
+            @mismatch ? "#{line}\n#{shell.paint("  #{MISMATCH}", :error)}" : line
+          end
+
+          private
+
+          def key(name, _message)
+            return unless name == "enter"
+
+            entered = component.value
+            return submit(entered) unless @confirm
+            return ask_again(entered) if @first.nil?
+            return submit(entered) if entered == @first
+
+            start_over
+          end
+
+          def ask_again(entered)
+            @first = entered
+            @mismatch = false
+            fresh_input
+          end
+
+          def start_over
+            @first = nil
+            @mismatch = true
+            fresh_input
+          end
+
+          def fresh_input
+            self.component = Password.input
+            [self, component.focus]
+          end
+        end
+
+        module_function
+
+        def input
+          field = Bubbles::TextInput.new
+          field.prompt = ""
+          field.echo_mode = Bubbles::TextInput::ECHO_PASSWORD
+          field.echo_character = BULLET
+          field
+        end
+
+        def answered(shell, question)
+          "#{shell.symbol(:success)} #{question} #{shell.paint("·", :muted)} #{shell.paint(MASK, :accent)}"
+        end
+
+        def ask_line(shell, question, confirm)
+          loop do
+            value = read_secret(shell, "#{question} ", question)
+            break value unless confirm
+
+            again = read_secret(shell, "#{question} #{AGAIN} ", question)
+            break value if again == value
+            raise Error, "the two answers to #{question.inspect} didn't match" unless shell.input_tty?
+
+            shell.err_puts(MISMATCH)
+          end.tap do
+            shell.err_puts("#{shell.symbol(:success)} #{question} · #{MASK}") unless shell.input_tty?
+          end
+        end
+
+        # One line with echo off when a person types it; silently from a pipe.
+        def read_secret(shell, prompt, question)
+          line =
+            if shell.input_tty?
+              shell.error.write(prompt)
+              shell.error.flush if shell.error.respond_to?(:flush)
+              hidden_gets(shell)
+            else
+              shell.input.gets
+            end
+          raise Error, "no answer for #{question.inspect}: input ended" if line.nil?
+
+          line.chomp
+        end
+
+        # The typed newline isn't echoed with echo off, so end the prompt's line ourselves.
+        def hidden_gets(shell)
+          return shell.input.gets unless shell.input.respond_to?(:noecho)
+
+          line = shell.input.noecho(&:gets)
+          shell.error.write("\n")
+          line
+        end
+      end
+    end
+
+    extension :password do
+      helpers do
+        def password(question, confirm: false)
+          return Ext::Password.ask_line(shell, question, confirm) unless shell.interactive?
+
+          CLI.require_bubbles!
+          Prompt.run(shell, Ext::Password::Model.new(shell, question, confirm)).value
+        end
+      end
+    end
+  end
+end