r2ui 0.1.0 → 0.2.0

data/lib/r2ui/cli/prompt.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module R2UI
+  module CLI
+    # How prompts run. On an interactive shell a prompt is a small Bubbletea model run inline (no
+    # alt screen) on r2ui's engine: raw mode while it asks, its last view (the answered line) left
+    # in the scrollback, the terminal restored on every exit path. Prompt stories build their model
+    # on Prompt::Model, hosting a bubbles component when one fits (TextInput for ask/password, List
+    # for choose; `CLI.require_bubbles!` first).
+    #
+    # Off a terminal a prompt reads one line instead (`Prompt.read_line`): asking on stderr when a
+    # person can still type (stdin is a terminal, stdout piped), silently from a pipe otherwise
+    # (`yes | tool`, `echo name | tool`), nil at end of input so the prompt falls back to its default.
+    module Prompt
+      module_function
+
+      # Runs `model` until it quits; returns the final model. ctrl+c raises Interrupt after the
+      # terminal is restored (the model sets `interrupted`).
+      def run(shell, model)
+        runner = InlineRunner.new(model, shell)
+        runner.run
+        model = runner.model
+        raise Interrupt if model.respond_to?(:interrupted?) && model.interrupted?
+
+        model
+      end
+
+      def read_line(shell, prompt)
+        if shell.input_tty?
+          shell.error.write(prompt)
+          shell.error.flush if shell.error.respond_to?(:flush)
+        end
+        line = shell.input.gets
+        line&.chomp
+      end
+
+      # Bubbletea's runner on the shell's input and output (the upstream runner always uses the
+      # process's stdin/stdout), inline.
+      class InlineRunner < Bubbletea::Runner
+        attr_reader :model
+
+        def initialize(model, shell)
+          super(model, alt_screen: false, fps: 30)
+          @shell = shell
+          @program = Bubbletea::Program.new(input: shell.input, output: shell.output)
+        end
+
+        private
+
+        # The runner ends with `print "\r\n"`: send it to the shell's output, not $stdout.
+        def print(*args) = @shell.output.print(*args)
+      end
+
+      # A base for prompt models: Bubbletea::Model plus the shared answer/interrupt bookkeeping.
+      #
+      # - ctrl+c and esc cancel (Prompt.run then raises Interrupt), before anything else sees them.
+      # - Other keys go to `key(name, msg)`; return `submit(value)` to answer, or nil to pass the
+      #   key on to the hosted component.
+      # - `self.component = Bubbles::TextInput.new` hosts a bubbles model: its `init` runs with the
+      #   prompt's, and it gets every message the prompt doesn't handle (keys `key` passes on, blink
+      #   and other ticks, window size), its commands going out with the prompt's.
+      # Subclasses implement `view` (and usually `key`).
+      class Model
+        include Bubbletea::Model
+
+        attr_reader :value, :shell
+        attr_accessor :component
+
+        def initialize(shell)
+          @shell = shell
+          @done = false
+          @interrupted = false
+          @component = nil
+        end
+
+        def init
+          return [self, nil] unless component.respond_to?(:init)
+
+          [self, adopt(component.init)]
+        end
+
+        def update(message)
+          if message.is_a?(Bubbletea::KeyMessage)
+            name = message.to_s
+            return cancel if %w[ctrl+c esc].include?(name)
+
+            result = key(name, message)
+            return result if result
+          end
+          forward(message)
+        end
+
+        def done? = @done
+
+        def interrupted? = @interrupted
+
+        private
+
+        # Prompts that only use a component may leave this out.
+        def key(_name, _message) = nil
+
+        # Sends a message to the hosted component; keeps the model it returns.
+        def forward(message)
+          return [self, nil] unless component
+
+          [self, adopt(component.update(message))]
+        end
+
+        # [model, cmd] or a bare cmd from a component's init/update → the cmd, keeping the model.
+        def adopt(result)
+          if result.is_a?(Array) && result.size == 2 && !result.first.is_a?(Bubbletea::Command)
+            @component = result.first unless result.first.nil?
+            result.last
+          else
+            result
+          end
+        end
+
+        def submit(value)
+          @value = value
+          @done = true
+          [self, Bubbletea.quit]
+        end
+
+        def cancel
+          @interrupted = true
+          @done = true
+          [self, Bubbletea.quit]
+        end
+      end
+    end
+  end
+end

data/lib/r2ui/cli/runner.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module R2UI
+  module CLI
+    # Runs one argv against a Program and turns every outcome into an exit code:
+    #
+    #   0    the command returned (or --help, or a group run without a subcommand: its help)
+    #   1    an error: CLI::Error, abort!, or anything else that escaped ("✖ message" on stderr;
+    #        R2UI_TRACE=1 adds the backtrace)
+    #   2    a usage error: unknown/missing/bad option, argument or command, plus a --help hint
+    #   130  ctrl+c (Interrupt)
+    #   n    abort!(code: n), halt(n), or an on_error hook returning n
+    #
+    # A closed stdout (`tool | head`) ends quietly with 0.
+    class Runner
+      def initialize(program, shell:)
+        @program = program
+        @shell = shell
+      end
+
+      def call(argv)
+        parser = Parser.new(@program)
+        invocation = parser.parse(argv)
+        @context = Context.new(shell: @shell, command: invocation.command, options: invocation.options,
+                               args: invocation.args, argv: invocation.argv, given: invocation.given)
+        return help(invocation.command) if invocation.help
+
+        run_hooks(:after_parse)
+        parser.finish(invocation)
+        return help(invocation.command) unless invocation.command.action
+
+        run_hooks(:before_run)
+        @context.call(invocation.command.action)
+        run_hooks(:after_run)
+        0
+      rescue Halt => e
+        e.code
+      rescue Interrupt
+        @shell.err_puts
+        130
+      rescue Errno::EPIPE
+        0
+      rescue StandardError => e
+        report(e)
+      end
+
+      private
+
+      def help(command)
+        @shell.print(Help.new(command, @shell).to_s)
+        0
+      end
+
+      def run_hooks(kind) = Extensions.hooks(kind).each { |hook| @context.call(hook.block) }
+
+      def report(error)
+        context = @context || Context.new(shell: @shell, command: error.respond_to?(:command) && error.command || @program)
+        Extensions.hooks(:on_error).each do |hook|
+          next unless hook.match?(error)
+
+          code = context.call(hook.block, error)
+          return code if code.is_a?(Integer)
+        end
+
+        case error
+        when UsageError
+          @shell.err_puts("#{@shell.symbol(:error)} #{error.message}")
+          command = error.command || context.command
+          @shell.err_puts(@shell.paint("Run '#{command.full_name} --help' for usage.", :muted))
+        when Abort
+          @shell.err_puts("#{@shell.symbol(:error)} #{error.message}") unless error.silent?
+        else
+          @shell.err_puts("#{@shell.symbol(:error)} #{error.message}")
+          trace(error)
+        end
+        error.is_a?(Error) ? error.code : 1
+      end
+
+      def trace(error)
+        return if error.is_a?(Error) || @shell.env["R2UI_TRACE"].to_s.empty?
+
+        @shell.err_puts(@shell.paint(["#{error.class}: #{error.message}", *error.backtrace].join("\n  "), :muted))
+      end
+    end
+  end
+end

data/lib/r2ui/cli/shell.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require "io/console"
+
+module R2UI
+  module CLI
+    # Where a tool talks to the user, and what that place can do. Every helper writes through a
+    # Shell, never to $stdout directly, so the same code is gorgeous on a terminal and plain in a
+    # pipe, and tests run it on StringIOs.
+    #
+    #   tty?          stdout is a terminal (or `tty:` says so)
+    #   live?         redraw in place: tty? and TERM isn't "dumb"
+    #   interactive?  prompts may take keys: stdin and stdout are terminals and TERM isn't
+    #                 "dumb" (or `interactive:`)
+    #   color?        style output: NO_COLOR unset, and FORCE_COLOR set or tty? (or `color:`)
+    #
+    # Off a terminal, helpers print one stable line per event (no spinners, no cursor movement,
+    # no colour) and prompts fall back to reading a line (docs/cli.md, "On and off a terminal").
+    class Shell
+      attr_reader :input, :output, :error, :env, :theme
+      attr_writer :color
+
+      def initialize(input: $stdin, output: $stdout, error: $stderr, env: ENV, tty: nil,
+                     interactive: nil, color: nil, width: nil, theme: Theme.new)
+        @input = input
+        @output = output
+        @error = error
+        @env = env
+        @tty = tty
+        @interactive = interactive
+        @color = color
+        @width = width
+        @theme = theme
+        @live = nil
+      end
+
+      def tty? = @tty.nil? ? io_tty?(output) : @tty
+
+      def live? = tty? && env["TERM"] != "dumb"
+
+      def interactive?
+        return @interactive unless @interactive.nil?
+
+        tty? && input_tty? && env["TERM"] != "dumb"
+      end
+
+      # Stdin is a terminal. With stdout piped (`tool | tee log`) prompts ask a line on stderr.
+      def input_tty?
+        return @interactive unless @interactive.nil?
+        return @tty unless @tty.nil?
+
+        io_tty?(input)
+      end
+
+      def color?
+        return @color unless @color.nil?
+        return false if present?(env["NO_COLOR"])
+        return true if present?(env["FORCE_COLOR"]) && env["FORCE_COLOR"] != "0"
+
+        live?
+      end
+
+      def width
+        @width || winsize&.last || positive(env["COLUMNS"]) || 80
+      end
+
+      def height = winsize&.first || positive(env["LINES"]) || 24
+
+      # Styles `text` with theme styles (:success, :error, :warn, :info, :accent, :muted, :heading,
+      # ...) when color? is on; plain text otherwise. Line by line, so lines keep their widths.
+      def paint(text, *styles)
+        text = text.to_s
+        return text if styles.empty? || !color?
+
+        text.split("\n", -1).map { |line| line.empty? ? line : theme.render(line, styles) }.join("\n")
+      end
+
+      # A theme symbol (✔ ✖ ⚠ ℹ ○ –), painted in its own style.
+      def symbol(name) = paint(theme.symbol(name), name)
+
+      # Writes a line to stdout. While a Live region is drawing, the line goes above it.
+      def puts(text = "")
+        text = text.to_s
+        if @live
+          @live.println(text)
+        else
+          write(output, text.end_with?("\n") ? text : "#{text}\n")
+        end
+        nil
+      end
+
+      def print(text) = write(output, text.to_s)
+
+      # Writes a line to stderr (warnings, errors, prompts off a terminal).
+      def err_puts(text = "")
+        text = text.to_s
+        if @live && error_shares_terminal?
+          @live.println(text)
+        else
+          write(error, text.end_with?("\n") ? text : "#{text}\n")
+        end
+        nil
+      end
+
+      # The Live region drawing now (set by Live; nil otherwise).
+      attr_accessor :live
+
+      private
+
+      def write(io, text)
+        io.write(text)
+        io.flush if io.respond_to?(:flush)
+      end
+
+      def error_shares_terminal? = io_tty?(error) && tty?
+
+      def io_tty?(io) = io.respond_to?(:tty?) && io.tty?
+
+      def winsize
+        return nil unless @tty.nil? && output.respond_to?(:winsize) && io_tty?(output)
+
+        rows, cols = output.winsize
+        cols.positive? ? [rows, cols] : nil
+      rescue SystemCallError, IOError
+        nil
+      end
+
+      def positive(value)
+        n = value.to_i
+        n.positive? ? n : nil
+      end
+
+      def present?(value) = !value.nil? && !value.empty?
+    end
+
+    # Named styles as lipgloss options (the same vocabulary as the dashboard DSL's `theme`), and
+    # the status symbols. Colours are ANSI palette numbers, so they follow the user's terminal
+    # theme, the way npm's and pnpm's do.
+    class Theme
+      STYLES = {
+        success: { foreground: "2" },
+        error: { foreground: "1" },
+        warn: { foreground: "3" },
+        info: { foreground: "4" },
+        accent: { foreground: "6" },
+        highlight: { foreground: "5", bold: true },
+        muted: { faint: true },
+        heading: { bold: true },
+        pending: { faint: true },
+        skipped: { faint: true },
+        running: { foreground: "6" }
+      }.freeze
+
+      SYMBOLS = {
+        success: "✔",
+        error: "✖",
+        warn: "⚠",
+        info: "ℹ",
+        pending: "○",
+        skipped: "–",
+        pointer: "›",
+        bullet: "•"
+      }.freeze
+
+      def initialize(styles: {}, symbols: {})
+        @styles = STYLES.merge(styles)
+        @symbols = SYMBOLS.merge(symbols)
+        @cache = {}
+      end
+
+      def symbol(name) = @symbols.fetch(name) { raise ArgumentError, "unknown symbol #{name.inspect}" }
+
+      def options(name) = @styles.fetch(name) { raise ArgumentError, "unknown style #{name.inspect}" }
+
+      # A Lipgloss::Style for the named styles merged left to right.
+      def style(*names)
+        @cache[names] ||= names.map { |n| options(n) }.reduce({}, :merge).reduce(Lipgloss::Style.new) do |style, (key, value)|
+          style.public_send(key, value)
+        end
+      end
+
+      def render(text, names) = style(*names).render(text)
+    end
+  end
+end

data/lib/r2ui/cli/testing.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "stringio"
+require_relative "../cli"
+
+module R2UI
+  module CLI
+    # Test a tool without a terminal (any test framework):
+    #
+    #   require "r2ui/cli/testing"
+    #   include R2UI::CLI::Testing
+    #
+    #   result = run_cli(MyTool, "deploy", "api", "--env", "production", input: "y\n")
+    #   assert_equal 0, result.code
+    #   assert_includes result.out, "Deployed"
+    #
+    # By default the shell is a pipe: no colour, no live redraw, prompts read `input` line by
+    # line, exactly what CI sees. `tty: true` makes it look like a terminal (live regions draw
+    # their escape codes into `out`; prompts still read `input`, as lines, unless `interactive:`).
+    module Testing
+      Result = Data.define(:code, :out, :err) do
+        def success? = code.zero?
+      end
+
+      module_function
+
+      def test_shell(input: "", tty: false, interactive: false, color: false, env: {}, width: 80)
+        Shell.new(input: StringIO.new(input), output: StringIO.new, error: StringIO.new, env:, tty:,
+                  interactive:, color:, width:)
+      end
+
+      def run_cli(program, *argv, **shell_options)
+        shell = test_shell(**shell_options)
+        code = program.call(argv.flatten.map(&:to_s), shell:)
+        Result.new(code:, out: shell.output.string, err: shell.error.string)
+      end
+
+      # Runs a block with R2UI::CLI.shell swapped for a test shell; returns [value, shell].
+      def with_shell(**shell_options)
+        shell = test_shell(**shell_options)
+        previous = CLI.instance_variable_get(:@shell)
+        CLI.shell = shell
+        [yield(shell), shell]
+      ensure
+        CLI.shell = previous
+      end
+    end
+  end
+end

data/lib/r2ui/cli.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+# r2ui for command-line tools: a declarative commands DSL plus inline helpers (tasks, prompts,
+# styled output) that look like npm/pnpm on a terminal and print plain, stable lines in a pipe.
+#
+#   require "r2ui/cli"
+#
+#   R2UI.cli "deployer" do
+#     summary "Ship apps to the fleet"
+#     command :deploy do
+#       argument :app
+#       option :env, default: "staging", in: %w[staging production]
+#       run do
+#         confirm("Deploy #{args[:app]} to #{options[:env]}?") or abort!("cancelled")
+#         tasks do
+#           step("Building") { build }
+#           step("Uploading") { upload }
+#         end
+#       end
+#     end
+#   end.start
+#
+# docs/cli.md is the design and the story list. Capabilities live one per file in
+# lib/r2ui/cli/ext/ and load automatically, like the dashboard DSL's lib/r2ui/ext/.
+#
+# This loads r2ui's pure-Ruby Bubbletea and Lipgloss by path (as `require "r2ui"` does for
+# Bubbletea), not the dashboard DSL: a CLI starts fast. `require "r2ui"` too for dashboards.
+require_relative "version"
+require_relative "compat/bubbletea"
+require_relative "compat/lipgloss"
+
+module R2UI
+  module CLI
+    # A failure the tool reports to the user: "✖ message" on stderr, exit code `code` (1).
+    class Error < StandardError
+      def code = 1
+    end
+
+    # Wrong arguments or options: the message, a "--help" hint, exit code 2.
+    class UsageError < Error
+      # The command whose usage it was (for the "--help" hint); set by the parser.
+      attr_accessor :command
+
+      def code = 2
+    end
+
+    # `abort!(message, code:)`: stop the command with a message (or none) and an exit code.
+    class Abort < Error
+      attr_reader :code
+
+      def initialize(message = nil, code: 1)
+        super(message)
+        @code = code
+        @silent = message.nil?
+      end
+
+      def silent? = @silent
+    end
+
+    # `halt(code)`: stop the command quietly. Not a StandardError, so `rescue => e` in a command
+    # doesn't swallow it.
+    class Halt < Exception # rubocop:disable Lint/InheritException
+      attr_reader :code
+
+      def initialize(code = 0)
+        super("halt #{code}")
+        @code = code
+      end
+    end
+  end
+end
+
+require_relative "cli/shell"
+require_relative "cli/live"
+require_relative "cli/definition"
+require_relative "cli/parser"
+require_relative "cli/help"
+require_relative "cli/helpers"
+require_relative "cli/context"
+require_relative "cli/extension"
+require_relative "cli/prompt"
+require_relative "cli/runner"
+
+module R2UI
+  module CLI
+    extend Helpers
+
+    class << self
+      # Defines a tool: the block runs on a Builder for the root command (see docs/cli.md).
+      # Returns the Program; the last one defined is `R2UI::CLI.program`.
+      def define(name = File.basename($PROGRAM_NAME), &)
+        @program = Program.build(name, &)
+      end
+
+      def program = @program || raise(Error, "no CLI defined: call R2UI.cli first")
+
+      # Runs the last defined tool on ARGV and exits with its code.
+      def start(argv = ARGV) = program.start(argv)
+
+      # The process's terminal (stdin, stdout, stderr, ENV). Helpers called outside a command
+      # (a plain script that includes R2UI::CLI::Helpers) use it; tests swap it.
+      def shell = @shell ||= Shell.new
+
+      attr_writer :shell
+
+      def extension(name, &) = Extensions.register(name, &)
+
+      # Prompt stories host bubbles components (TextInput, List, ...). Bubbles is optional, so
+      # call this when a prompt is first used, never at file load. It opts into r2ui/drop_in, so
+      # bubbles runs on r2ui's Bubbletea and Lipgloss.
+      def require_bubbles!
+        return if defined?(::Bubbles)
+
+        require_relative "drop_in"
+        begin
+          require "bubbles"
+        rescue LoadError
+          raise Error, "this needs the bubbles gem: add `gem \"bubbles\"` to your Gemfile"
+        end
+      end
+    end
+  end
+
+  # `R2UI.cli "name" do ... end`: the commands DSL entry point, next to R2UI.dashboard.
+  def self.cli(name = File.basename($PROGRAM_NAME), &) = CLI.define(name, &)
+end
+
+# Capabilities: one self-registering file each (docs/cli.md).
+R2UI::CLI::Extensions.load_all

data/lib/r2ui/compat/bubbletea/LICENSE-bubbletea.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Marco Roth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.