r2ui 0.1.0 → 0.2.0

data/lib/r2ui/cli/extension.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module R2UI
+  module CLI
+    # One CLI capability in one file, the same shape as the dashboard DSL's R2UI.extension
+    # (docs/dsl.md). Files in lib/r2ui/cli/ext/ load automatically, in name order. See docs/cli.md
+    # and the reference ones, lib/r2ui/cli/ext/tasks.rb and confirm.rb.
+    #
+    #   R2UI::CLI.extension :version do
+    #     dsl(:command) { def version(v) = declare(:version, v) }
+    #     setup { flag :version, short: "V", desc: "Print the version" if declared(:version).any? }
+    #     before_run { (say(program.declared(:version).last) || halt) if options[:version] }
+    #   end
+    #
+    #   dsl(:command) { def kw ... end }   keywords on Builder (`definition`, `declare`), at definition
+    #   helpers { def h ... end }          methods on Helpers (so on every Context too)
+    #   setup { }                          on the root's Builder, after the R2UI.cli block
+    #   after_parse { }                    on the Context, argv parsed, before defaults, required
+    #                                      checks and positional arguments (`args` is empty here)
+    #   before_run { }                     on the Context, before the command's run block
+    #   after_run { }                      on the Context, after it returned normally
+    #   help_header { |command, shell| }   returns a String (or nil) shown first in --help
+    #   help_section { |command, shell| }  returns [heading, lines] (or nil) to append to --help
+    #   on_error(Klass) { |error| }        on the Context when an error escapes; returning an Integer
+    #                                      makes it the exit code and skips the core's report
+    class Extension
+      TARGETS = { command: -> { Builder } }.freeze
+
+      Hook = Data.define(:extension, :matcher, :order, :block) do
+        def match?(value) = matcher.nil? || matcher === value # rubocop:disable Style/CaseEquality
+      end
+
+      attr_reader :name, :hooks
+
+      def initialize(name)
+        @name = name.to_sym
+        @modules = []
+        @hooks = Hash.new { |h, k| h[k] = [] }
+      end
+
+      def dsl(target = :command, &body)
+        builder = TARGETS.fetch(target) { raise Error, "unknown DSL target #{target.inspect}" }.call
+        add_module(builder, Module.new(&body))
+      end
+
+      def helpers(&body) = add_module(Helpers, Module.new(&body), also: Context)
+
+      def setup(&block) = hook(:setup, nil, block)
+
+      def after_parse(&block) = hook(:after_parse, nil, block)
+
+      def before_run(&block) = hook(:before_run, nil, block)
+
+      def after_run(&block) = hook(:after_run, nil, block)
+
+      def help_section(&block) = hook(:help_section, nil, block)
+
+      def help_header(&block) = hook(:help_header, nil, block)
+
+      def on_error(matcher = StandardError, &block) = hook(:on_error, matcher, block)
+
+      def remove!
+        @modules.each do |mod|
+          (mod.instance_methods(false) + mod.private_instance_methods(false)).each { |m| mod.send(:remove_method, m) }
+        end
+        @hooks.clear
+      end
+
+      private
+
+      def hook(kind, matcher, block)
+        raise ArgumentError, "#{kind} needs a block" unless block
+
+        @hooks[kind] << Hook.new(extension: name, matcher:, order: Extensions.next_order, block:)
+      end
+
+      def add_module(target, mod, also: nil)
+        defined = mod.instance_methods(false) + mod.private_instance_methods(false)
+        taken = defined.select do |m|
+          [target, also].compact.any? { |t| t.method_defined?(m) || t.private_method_defined?(m) && t.instance_method(m).owner != Kernel }
+        end
+        raise Error, "extension #{name}: #{target} already has #{taken.join(", ")}" if taken.any?
+
+        target.include(mod)
+        @modules << mod
+        mod
+      end
+    end
+
+    # The loaded CLI extensions, in load order.
+    module Extensions
+      @all = {}
+      @order = 0
+      @lock = Mutex.new
+
+      class << self
+        def register(name, &block)
+          name = name.to_sym
+          raise Error, "CLI extension #{name} is already registered" if @all.key?(name)
+
+          extension = Extension.new(name)
+          @all[name] = extension
+          begin
+            extension.instance_eval(&block) if block
+          rescue StandardError
+            remove(name)
+            raise
+          end
+          extension
+        end
+
+        def [](name) = @all[name.to_sym]
+
+        def names = @all.keys
+
+        # Unregisters an extension and empties its modules (for tests).
+        def remove(name) = @all.delete(name.to_sym)&.remove!
+
+        def hooks(kind) = @all.values.flat_map { |e| e.hooks.fetch(kind, []) }.sort_by(&:order)
+
+        def next_order = @lock.synchronize { @order += 1 }
+
+        def load_all(dir = File.expand_path("ext", __dir__))
+          Dir[File.join(dir, "*.rb")].sort.each { |file| require file }
+        end
+      end
+    end
+  end
+end

data/lib/r2ui/cli/help.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module R2UI
+  module CLI
+    # The generated `--help` for a command:
+    #
+    #   Deploy an app to the fleet
+    #
+    #   Usage
+    #     deployer deploy <app> [sha] [options]
+    #
+    #   Arguments
+    #     app   App to deploy
+    #
+    #   Options
+    #     -e, --env <env>   Target environment (staging, production) [default: staging]
+    #         --[no-]force  Skip the checks
+    #     -h, --help        Show help
+    #
+    # Headings bold, names in the accent colour, defaults muted, when the shell has colour; the
+    # same text without escapes otherwise. Extensions put lines on top with `help_header` (e.g.
+    # "deployer 1.4.0") and append sections with `help_section`.
+    class Help
+      INDENT = "  "
+      GAP = "  "
+
+      def initialize(command, shell)
+        @command = command
+        @shell = shell
+      end
+
+      def to_s
+        sections = Extensions.hooks(:help_header).filter_map do |hook|
+          text = hook.block.call(@command, @shell)
+          text.nil? || text.to_s.empty? ? nil : text.to_s.chomp
+        end
+        about = @command.description || @command.summary
+        sections << about if about
+        sections << section("Usage", [INDENT + usage])
+        sections << table("Arguments", @command.arguments.map { |a| [a.name.to_s.tr("_", "-"), describe_argument(a)] })
+        sections << table("Commands", visible_commands.map { |c| [[c.name, *c.aliases].join(", "), c.summary.to_s] })
+        sections << table("Options", option_rows)
+        Extensions.hooks(:help_section).each do |hook|
+          heading, body = hook.block.call(@command, @shell)
+          sections << section(heading, Array(body).flat_map { |b| b.to_s.split("\n") }.map { |l| INDENT + l }) if heading
+        end
+        sections << footer if @command.group?
+        "#{sections.compact.join("\n\n")}\n"
+      end
+
+      def usage
+        parts = [@command.full_name]
+        parts << "<command>" if @command.group? && !@command.action
+        parts << "[command]" if @command.group? && @command.action
+        parts.concat(@command.arguments.map(&:usage))
+        parts << "[options]"
+        @shell.paint(parts.join(" "), :accent)
+      end
+
+      private
+
+      def visible_commands = @command.commands.reject(&:hidden)
+
+      def option_rows
+        options = @command.all_options.reject(&:hidden)
+        rows = options.map { |o| [option_label(o), describe_option(o)] }
+        rows << ["-h, --help", "Show help"]
+        rows
+      end
+
+      def option_label(option)
+        short = option.short ? "-#{option.short}, " : "    "
+        long = option.boolean? && option.default == true ? "--[no-]#{option.long.delete_prefix("--")}" : option.long
+        long += " <#{option.value_name}>" unless option.boolean?
+        long += "..." if option.many
+        short + long
+      end
+
+      def describe_option(option)
+        notes = []
+        notes << option.choices.join(", ") if option.choices
+        notes << "required" if option.required
+        default = option.default
+        notes << "default: #{default}" if !default.nil? && !default.respond_to?(:call) && default != false && default != []
+        [option.desc, notes.empty? ? nil : @shell.paint("(#{notes.join("; ")})", :muted)].compact.join(" ")
+      end
+
+      def describe_argument(argument)
+        notes = argument.default.nil? ? nil : @shell.paint("(default: #{argument.default})", :muted)
+        [argument.desc, notes].compact.join(" ")
+      end
+
+      def section(heading, lines)
+        return nil if lines.empty?
+
+        [@shell.paint(heading, :heading), *lines].join("\n")
+      end
+
+      def table(heading, rows)
+        return nil if rows.empty?
+
+        width = rows.map { |name, _| name.size }.max
+        lines = rows.map do |name, text|
+          line = INDENT + @shell.paint(name, :accent)
+          text.to_s.empty? ? line : line + (" " * (width - name.size)) + GAP + text
+        end
+        section(heading, lines)
+      end
+
+      def footer
+        @shell.paint("Run '#{@command.full_name} <command> --help' for more about a command.", :muted)
+      end
+    end
+  end
+end

data/lib/r2ui/cli/helpers.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module R2UI
+  module CLI
+    # The inline helpers (tasks, confirm, ...). Every extension's `helpers` block adds a module
+    # here, so they are available
+    # - in a command's `run` block (a Context, whose `shell` is the runner's),
+    # - in any script that does `include R2UI::CLI::Helpers` (they use R2UI::CLI.shell),
+    # - as `R2UI::CLI.confirm(...)` and friends.
+    #
+    # A helper writes only through `shell` (Shell#puts, #err_puts, #paint, #symbol), so it works on
+    # a terminal, in a pipe and in tests alike.
+    module Helpers
+      def shell = CLI.shell
+
+      # Prints a line, styled with theme styles when the shell has colour: `say "Done", :success`.
+      def say(text = "", *styles) = shell.puts(shell.paint(text, *styles))
+    end
+  end
+end

data/lib/r2ui/cli/live.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module R2UI
+  module CLI
+    # An inline region redrawn in place: spinners, task lists, progress bars. It draws with the
+    # compat engine's inline renderer (R2UI::Compat::Tea::Renderer, Bubbletea's standard
+    # renderer), so lines are redrawn and erased exactly the way an inline Bubbletea program's are,
+    # but it takes no raw mode and reads no keys: the work runs on the caller's thread, ctrl+c is an
+    # ordinary Interrupt, and typed input stays in the terminal's buffer.
+    #
+    #   live = Live.new(shell) { |frame| "#{Live.spinner(frame)} Building" }
+    #   live.run { build }          # draws at FPS until the block returns, then the last frame stays
+    #
+    # Off a live terminal (a pipe, TERM=dumb) it draws nothing: `run` just yields and the caller
+    # prints its own plain lines (check `live?`). The cursor is hidden while drawing and shown
+    # again on every exit path (the block's return, an exception, ctrl+c).
+    class Live
+      # bubbles' Spinner::MINI_DOT frames, at its 12 fps.
+      SPINNER = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏].freeze
+      FPS = 12
+      HIDE_CURSOR = "\e[?25l"
+      SHOW_CURSOR = "\e[?25h"
+      ERASE_BELOW = "\e[J"
+
+      def self.spinner(frame) = SPINNER[frame % SPINNER.size]
+
+      attr_reader :shell, :frame
+
+      # When true, `stop` erases the region instead of leaving its last frame (a spinner that
+      # disappears on success). Set it at any time before the region stops.
+      attr_accessor :clear
+
+      # `view` gets the frame number (it ticks at `fps`) and returns the region's lines.
+      def initialize(shell, fps: FPS, clear: false, &view)
+        raise ArgumentError, "Live needs a view block" unless view
+
+        @shell = shell
+        @fps = fps
+        @clear = clear
+        @view = view
+        @lock = Monitor.new
+        @frame = 0
+        @running = false
+        @lines = 0
+        @error = nil
+      end
+
+      def live? = shell.live?
+
+      def running? = @running
+
+      # Draws while the block runs; returns the block's value. If the view raised while the
+      # ticker was drawing, that error is raised here once the terminal is restored.
+      def run
+        start
+        value = yield self
+        stop
+        raise @error if @error
+
+        value
+      ensure
+        stop
+      end
+
+      def start
+        return self if @running || !live?
+
+        @running = true
+        @renderer = new_renderer
+        shell.print(HIDE_CURSOR)
+        shell.live = self
+        refresh
+        @ticker = Thread.new do
+          Thread.current.report_on_exception = false
+          loop do
+            sleep(1.0 / @fps)
+            @lock.synchronize do
+              @frame += 1
+              draw
+            end
+          end
+        rescue StandardError => e
+          @error = e # the ticker stops; `run` (or the next refresh) surfaces it
+        end
+        self
+      end
+
+      # Redraws now (call after changing what the view shows, so it doesn't wait for a tick).
+      def refresh
+        @lock.synchronize { draw if @running }
+        self
+      end
+
+      # Prints a line above the region; it stays in the scrollback. Shell#puts calls this while
+      # the region is drawing.
+      def println(text)
+        @lock.synchronize do
+          erase if @running
+          shell.output.write("#{text}\n")
+          next unless @running
+
+          @renderer = new_renderer
+          draw
+        end
+        nil
+      end
+
+      # Draws the last frame and leaves it in the scrollback (or erases the region when `clear`),
+      # then shows the cursor again. The terminal is restored even if the last draw raises or a
+      # second ctrl+c arrives while the ticker stops; that error then propagates.
+      def stop
+        return unless @running
+
+        begin
+          @ticker&.kill
+          @ticker&.join
+          @lock.synchronize { @clear ? erase : (draw unless @error) }
+        ensure
+          @running = false
+          shell.live = nil
+          shell.output.write(@clear ? SHOW_CURSOR : "\n#{SHOW_CURSOR}")
+          shell.output.flush if shell.output.respond_to?(:flush)
+        end
+        nil
+      end
+
+      private
+
+      def draw
+        raise @error if @error
+
+        view = @view.call(@frame).to_s
+        @renderer.render(view)
+        @lines = [view.empty? ? 1 : view.split("\n", -1).size, shell.height].min
+      end
+
+      # Moves to the region's first line and erases it and everything below.
+      def erase
+        up = @lines - 1
+        shell.output.write("#{up.positive? ? "\e[#{up}A" : ""}\r#{ERASE_BELOW}")
+      end
+
+      def new_renderer
+        Compat::Tea::Renderer.new(shell.output).tap { |r| r.set_size(shell.width, shell.height) }
+      end
+    end
+  end
+end

data/lib/r2ui/cli/parser.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module R2UI
+  module CLI
+    # argv → which command, its options and arguments. Errors are UsageErrors with a "did you
+    # mean" when a near name exists. Options may come anywhere after the command that owns them
+    # (or an ancestor that declared them); `--` ends options.
+    #
+    # Parsing happens in two steps so extensions can act in between (the runner's `after_parse`
+    # hooks): `parse` reads argv (commands and options); `finish` applies defaults, checks
+    # required options and reads the positional arguments.
+    class Parser
+      # `options` holds the given options (converted); `given` their names.
+      Invocation = Struct.new(:command, :options, :given, :args, :positionals, :help, :argv, keyword_init: true)
+
+      NEGATIVE_NUMBER = /\A-\d+(\.\d+)?\z/
+
+      def initialize(program)
+        @program = program
+      end
+
+      def parse(argv)
+        argv = argv.map(&:to_s)
+        command = @program
+        options = {}
+        positionals = []
+        help = false
+        only_positionals = false
+        i = 0
+
+        while i < argv.size
+          token = argv[i]
+          i += 1
+          if only_positionals
+            positionals << token
+          elsif token == "--"
+            only_positionals = true
+          elsif %w[--help -h].include?(token)
+            help = true
+          elsif token.start_with?("--")
+            i = long(command, token, argv, i, options)
+          elsif token.start_with?("-") && token.size > 1 && !(token.match?(NEGATIVE_NUMBER) && command.arguments.any?)
+            i = short(command, token, argv, i, options)
+          elsif positionals.empty? && command.group? && (sub = command.find(token))
+            command = sub
+          elsif positionals.empty? && command.group? && token == "help" && !help
+            help = true
+          elsif positionals.empty? && command.group? && !(command.action && command.arguments.any?)
+            raise UsageError, unknown("command", token, command.commands.reject(&:hidden).flat_map { |c| [c.name, *c.aliases] },
+                                      "for '#{command.full_name}'")
+          else
+            positionals << token
+          end
+        end
+
+        Invocation.new(command:, options:, given: options.keys, args: {}, positionals:, help:, argv:)
+      rescue UsageError => e
+        e.command ||= command
+        raise
+      end
+
+      # After the `after_parse` hooks: defaults for options still missing, required checks, then
+      # the positional arguments (filled into `invocation.args` in place, so a Context holding it
+      # sees them). A hook that halts (`--version`) never meets these checks.
+      def finish(invocation)
+        options = invocation.options
+        invocation.command.all_options.each do |option|
+          next if options.key?(option.name)
+
+          value = option.default_value
+          if option.required && (value.nil? || value == [])
+            raise UsageError, "missing required option #{option.long}"
+          end
+
+          options[option.name] = value
+        end
+        invocation.args.replace(arguments(invocation.command, invocation.positionals))
+        invocation
+      rescue UsageError => e
+        e.command ||= invocation.command
+        raise
+      end
+
+      private
+
+      def long(command, token, argv, i, options)
+        name, value = token.delete_prefix("--").split("=", 2)
+        option = find_long(command, name)
+        if option.nil? && name.start_with?("no-") && value.nil?
+          negated = find_long(command, name.delete_prefix("no-"))
+          return store(options, negated, false, i) if negated&.boolean?
+        end
+        raise UsageError, unknown("option", "--#{name}", command.all_options.reject(&:hidden).map(&:long)) unless option
+
+        if option.boolean?
+          store(options, option, value.nil? ? true : option.convert(value), i)
+        elsif value
+          store(options, option, option.convert(value), i)
+        else
+          raise UsageError, "option #{option.long} needs a value" if i >= argv.size
+
+          store(options, option, option.convert(argv[i]), i + 1)
+        end
+      end
+
+      def short(command, token, argv, i, options)
+        chars = token.delete_prefix("-").chars
+        chars.each_with_index do |char, j|
+          option = command.all_options.find { |o| o.short == char }
+          raise UsageError, unknown("option", "-#{char}", command.all_options.filter_map { |o| "-#{o.short}" if o.short }) unless option
+          next store(options, option, true, i) if option.boolean?
+
+          attached = chars[(j + 1)..].join
+          return store(options, option, option.convert(attached), i) unless attached.empty?
+          raise UsageError, "option -#{char} (#{option.long}) needs a value" if i >= argv.size
+
+          return store(options, option, option.convert(argv[i]), i + 1)
+        end
+        i
+      end
+
+      def store(options, option, value, i)
+        if option.many
+          (options[option.name] ||= []) << value
+        else
+          options[option.name] = value
+        end
+        i
+      end
+
+      def find_long(command, name)
+        name = name.tr("-", "_")
+        command.all_options.find { |o| o.name.to_s == name }
+      end
+
+      def arguments(command, positionals)
+        args = {}
+        command.arguments.each_with_index do |argument, index|
+          if argument.many
+            values = positionals[index..] || []
+            raise UsageError, "missing argument #{argument.usage}" if argument.required && values.empty?
+
+            args[argument.name] = values.empty? && argument.default ? Array(argument.default) : values.map { |v| argument.convert(v) }
+          elsif index < positionals.size
+            args[argument.name] = argument.convert(positionals[index])
+          elsif argument.required
+            raise UsageError, "missing argument #{argument.usage}"
+          else
+            args[argument.name] = argument.default
+          end
+        end
+        extra = command.arguments.last&.many ? [] : positionals.drop(command.arguments.size)
+        raise UsageError, "unexpected argument #{extra.first.inspect}" if extra.any?
+
+        args
+      end
+
+      def unknown(kind, word, candidates, suffix = nil)
+        message = "unknown #{kind} '#{word}'#{" #{suffix}" if suffix}"
+        guess = DidYouMean::SpellChecker.new(dictionary: candidates).correct(word).first if defined?(DidYouMean)
+        guess ? "#{message}. Did you mean '#{guess}'?" : message
+      end
+    end
+  end
+end