r2ui 0.1.0 → 0.2.0

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

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+# c27-config: options from a config file.
+#
+#   R2UI.cli "deployer" do
+#     config_file "~/.deployer.yml"          # YAML, or JSON when the name ends in .json
+#     option :region, default: "eu"
+#     command :deploy do
+#       option :replicas, :integer, default: 2
+#       ...
+#     end
+#     command(:db) { command(:migrate) { option :steps, :integer; ... } }
+#   end
+#
+#   # ~/.deployer.yml
+#   region: us              # top-level keys: options of every command that has them
+#   deploy:                 # a section per command: only that command's options
+#     replicas: 4
+#     dry-run: true         # dashes or underscores, like on the command line
+#   db:
+#     migrate:              # sections nest by command path
+#       steps: 3
+#
+# `config_file` (on the root) adds `--config <path>` to every command, so one run can read
+# another file. Before defaults and required checks, every option the command line didn't give
+# is filled from the file: the nearest section wins (`deploy:` over the top level), and a value
+# satisfies `required: true`. Values are converted and checked like typed input (`replicas: "4"`
+# and `replicas: 4` are both 4; `in:` choices apply); `many:` options take a list or one value.
+#
+# What wins: the command line, then the option's environment variable (`env:`, c26), then the
+# file, then the option's `default:`.
+#
+# A missing default file is fine (nothing is read). A missing `--config` file, a file that isn't
+# YAML/JSON or isn't a mapping, a key that names no option or command anywhere in its section's
+# subtree (so a typo fails whatever runs, with "Did you mean"), or a bad value is a usage error:
+#
+#   ✖ unknown key 'replicaz' in ~/.deployer.yml (deploy). Did you mean 'replicas'?
+#   Run 'deployer deploy --help' for usage.
+#
+# The file is only read when a command runs, so `--help` works with a broken one. Output is the
+# core's error report: styled on a terminal, plain lines off it.
+module R2UI
+  module CLI
+    module Ext
+      module ConfigFile
+        module_function
+
+        # [path to read, how to name it in messages], or nil when there's nothing to read.
+        def source(context)
+          declared = context.program.declared(:config_file).last
+          if context.given?(:config)
+            path = File.expand_path(context.options[:config].to_s)
+            raise UsageError, "config file #{path} not found" unless File.file?(path)
+
+            [path, path]
+          else
+            path = File.expand_path(declared)
+            [path, declared] if File.file?(path)
+          end
+        end
+
+        # The file's contents as a Hash ({} when empty). YAML and JSON load only when a file is read.
+        def read(path, label)
+          require "json"
+          require "yaml"
+          json = File.extname(path).casecmp?(".json")
+          text = File.read(path)
+          data = if text.strip.empty? then {}
+                 elsif json then JSON.parse(text)
+                 else YAML.safe_load(text, aliases: true)
+                 end
+          raise UsageError, "#{label}: expected a mapping of option names to values" unless data.nil? || data.is_a?(Hash)
+
+          data || {}
+        rescue SystemCallError => e
+          raise UsageError, "can't read config file #{label}: #{e.message}"
+        rescue JSON::ParserError, Psych::Exception => e
+          raise UsageError, "#{label}: not valid #{json ? "JSON" : "YAML"} (#{e.message.lines.first.to_s.strip})"
+        end
+
+        def key(name) = name.to_s.tr("-", "_")
+
+        # Options a section may set: those of its command and of every command under it.
+        def settable(command)
+          (command.all_options + command.commands.flat_map { |c| settable(c) }).reject { |o| o.name == :config }
+        end
+
+        # Every key in the file names an option in its section's subtree or a subcommand section.
+        def validate!(section, command, label)
+          names = settable(command).map { |o| o.name.to_s }.uniq
+          section.each do |name, value|
+            sub = command.find(name.to_s)
+            next validate!(value, sub, label) if sub && value.is_a?(Hash)
+            next if names.include?(key(name))
+
+            where = command.root? ? label : "#{label} (#{command.path.drop(1).join(" ")})"
+            candidates = names + names.map { |n| n.tr("_", "-") } + command.commands.flat_map { |c| [c.name, *c.aliases] }
+            guess = DidYouMean::SpellChecker.new(dictionary: candidates.uniq).correct(name.to_s).first if defined?(DidYouMean)
+            raise UsageError, "unknown key '#{name}' in #{where}#{". Did you mean '#{guess}'?" if guess}"
+          end
+        end
+
+        # name => value for `command`: the top level, then each section down its path (a section
+        # may be keyed by the command's name or an alias), so the nearest wins.
+        def values_for(data, command)
+          values = {}
+          take = lambda do |section, owner|
+            section.each { |name, value| values[key(name)] = value unless value.is_a?(Hash) && owner.find(name.to_s) }
+          end
+          section = data
+          current = command.root
+          take.call(section, current)
+          command.path.drop(1).each do |name|
+            parent = current
+            current = parent.find(name)
+            section = section.find { |k, v| v.is_a?(Hash) && parent.find(k.to_s) == current }&.last
+            break unless section
+
+            take.call(section, current)
+          end
+          values
+        end
+
+        def convert(option, value, label, name)
+          option.many ? Array(value).map { |v| scalar(option, v) } : scalar(option, value)
+        rescue UsageError => e
+          raise UsageError, "#{label}: #{name} #{e.message.delete_prefix("#{option.long} ")}"
+        end
+
+        def scalar(option, value)
+          raise UsageError, "expects one value" if value.is_a?(Array) || value.is_a?(Hash)
+
+          option.convert(value.is_a?(String) ? value : value.to_s)
+        end
+
+        def env_set?(context, option)
+          var = option.meta[:env]
+          var && !context.shell.env[var.to_s].to_s.empty?
+        end
+
+        def fill(context)
+          path, label = source(context)
+          return unless path
+
+          data = read(path, label)
+          validate!(data, context.program, label)
+          values = values_for(data, context.command)
+          context.command.all_options.each do |option|
+            next if option.name == :config || context.options.key?(option.name) || env_set?(context, option)
+            next unless values.key?(option.name.to_s)
+
+            value = values[option.name.to_s]
+            context.options[option.name] = convert(option, value, label, option.name.to_s.tr("_", "-")) unless value.nil?
+          end
+        end
+      end
+    end
+
+    extension :config do
+      dsl(:command) do
+        # The file whose keys fill options the command line didn't give (on the root only).
+        def config_file(path)
+          raise ArgumentError, "config_file belongs on the root command" unless definition.root?
+
+          declare(:config_file, path.to_s)
+        end
+      end
+
+      setup do
+        file = declared(:config_file).last
+        if file && !definition.option(:config)
+          option :config, :path, placeholder: "path", desc: "Read options from this file (default: #{file})"
+        end
+      end
+
+      after_parse { Ext::ConfigFile.fill(self) if program.declared(:config_file).any? }
+    end
+  end
+end

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

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+# c03-confirm: a yes/no question.
+#
+#   confirm("Deploy api to production?")                 # => true / false
+#   confirm("Overwrite config?", default: true)
+#   confirm("Deploy?") or abort!("cancelled")
+#
+# On a terminal (Shell#interactive?) it asks inline, like gum confirm:
+#
+#   ? Deploy api to production?    Yes  › No      ←/→ (h/l, tab) move, enter picks, y/n answer
+#
+# and leaves "✔ Deploy api to production? · Yes" 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: "y", "yes", "n", "no" (any case); an empty line or end of
+# input means `default:`. When a person can still type (stdin is a terminal, stdout piped) it asks
+# "Deploy? [y/N] " on stderr and asks again after an answer it can't read; from a pipe (`yes |
+# tool`, CI) it doesn't ask, records "✔ Deploy? · yes" on stderr, and an unreadable answer is an
+# error.
+#
+# This is the reference extension for prompts (docs/cli.md): a Prompt::Model run inline on the
+# terminal, a line-reading fallback off it. Copy its shape and its test.
+module R2UI
+  module CLI
+    module Ext
+      module Confirm
+        YES = %w[y yes true].freeze
+        NO = %w[n no false].freeze
+
+        # The inline prompt: a Bubbletea model on R2UI::CLI::Prompt.
+        class Model < Prompt::Model
+          attr_reader :question, :choice
+
+          def initialize(shell, question, default)
+            super(shell)
+            @question = question
+            @choice = default ? true : false
+          end
+
+          def view
+            return "#{shell.symbol(:error)} #{question}" if interrupted?
+            return Confirm.answered(shell, question, value) if done?
+
+            "#{shell.paint("?", :accent)} #{question}  #{option("Yes", choice)}  #{option("No", !choice)}"
+          end
+
+          private
+
+          def key(name, _message)
+            case name
+            when "y", "Y" then submit(true)
+            when "n", "N" then submit(false)
+            when "enter" then submit(choice)
+            when "left", "right", "h", "l", "tab", "shift+tab"
+              @choice = !@choice
+              nil
+            end
+          end
+
+          # The pointer marks the choice without colour too (NO_COLOR on a terminal).
+          def option(label, selected)
+            selected ? shell.paint("#{shell.theme.symbol(:pointer)} #{label}", :highlight) : shell.paint("  #{label}", :muted)
+          end
+        end
+
+        module_function
+
+        def answered(shell, question, value)
+          "#{shell.symbol(:success)} #{question} #{shell.paint("·", :muted)} #{shell.paint(value ? "Yes" : "No", :accent)}"
+        end
+
+        # true / false for a typed answer; `default` for none; nil for one it can't read.
+        def parse(line, default)
+          answer = line.to_s.strip.downcase
+          return default if answer.empty?
+          return true if YES.include?(answer)
+
+          false if NO.include?(answer)
+        end
+
+        def ask_line(shell, question, default)
+          hint = default ? "[Y/n]" : "[y/N]"
+          loop do
+            line = Prompt.read_line(shell, "#{question} #{hint} ")
+            value = parse(line, default)
+            unless value.nil?
+              shell.err_puts("#{shell.symbol(:success)} #{question} · #{value ? "yes" : "no"}") unless shell.input_tty?
+              return value
+            end
+            raise Error, "expected yes or no for #{question.inspect}, got #{line.strip.inspect}" unless shell.input_tty?
+
+            shell.err_puts("Please answer yes or no.")
+          end
+        end
+      end
+    end
+
+    extension :confirm do
+      helpers do
+        def confirm(question, default: false)
+          default = default ? true : false
+          return Ext::Confirm.ask_line(shell, question, default) unless shell.interactive?
+
+          Prompt.run(shell, Ext::Confirm::Model.new(shell, question, default)).value
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+# c25-dashboard: a command opens an r2ui dashboard.
+#
+#   command :top do
+#     summary "Watch the fleet"
+#     run { dashboard :fleet, file: "dashboards.rb" }
+#   end
+#
+# `dashboard(name, file: nil, height: nil)` loads the dashboard DSL (`require "r2ui"`; a CLI
+# doesn't load it until a command opens a dashboard), then `file`, which defines the dashboards and
+# resources with `R2UI.dashboard` / `R2UI.resource`. A relative `file` is looked up next to the
+# Ruby file that calls `dashboard` (like require_relative), then in the working directory. Leave
+# `file` out when the tool defines its dashboards itself. `name` is what `R2UI.run` takes: a
+# dashboard, a resource shown full screen, or nil for :main / the first one.
+#
+# On a terminal (Shell#interactive?) it runs `R2UI.run(name)` full screen on the alternate
+# screen, exactly as `r2ui dashboards.rb fleet` does, and returns when the user quits (q, or
+# ctrl+c); raw mode, the alternate screen and the cursor are restored on every exit path, so the
+# command carries on (or exits) with the shell as it was.
+#
+# Off an interactive shell (a pipe, CI, `tool top > frame.txt`) nothing waits for keys: it prints
+# one `R2UI.snapshot` frame as plain text, no escape codes, at the shell's width and height
+# (`height:` to choose), the same frame `r2ui --snapshot` draws:
+#
+#   ╭─ Ship ─────────────────────────────────────────╮
+#   │Name                    Status                  │
+#   │alpha                   up                      │
+#   │beta                    down                    │
+#   ╰────────────────────────────────────────────────╯
+#
+# A missing file, or a name no dashboard or resource has, is an error (exit 1, "✖ message").
+module R2UI
+  module CLI
+    module Ext
+      module OpenDashboard
+        # Bubbletea's runner on the shell's input and output (the upstream runner always uses the
+        # process's stdin/stdout), with the app's own program options (alternate screen, fps, and
+        # whatever dashboard extensions add).
+        class ShellRunner < Bubbletea::Runner
+          def initialize(app, shell)
+            super(app, **app.program_options)
+            @shell = shell
+            @program = Bubbletea::Program.new(input: shell.input, output: shell.output)
+          end
+
+          private
+
+          # The runner ends inline runs with `print "\r\n"`: send it to the shell, not $stdout.
+          def print(*args) = @shell.output.print(*args)
+        end
+
+        module_function
+
+        def load_dsl
+          require_relative "../../../r2ui" unless defined?(::R2UI::App)
+        end
+
+        # An absolute path as is; a relative one next to the calling file, else the working dir.
+        def resolve(file, base_dir)
+          path = file.to_s
+          candidates = [File.expand_path(path)]
+          candidates.unshift(File.expand_path(path, base_dir)) if base_dir && !File.absolute_path?(path)
+          found = candidates.find { |c| File.file?(c) }
+          found or raise Error, "no dashboard file #{path} (looked for #{candidates.uniq.join(", ")})"
+        end
+
+        # R2UI.run(name) on the shell's terminal (R2UI.run itself always uses $stdin/$stdout).
+        def run(shell, name)
+          return R2UI.run(name) if shell.input.equal?($stdin) && shell.output.equal?($stdout)
+
+          app = R2UI::App.new(R2UI.registry, name)
+          begin
+            ShellRunner.new(app, shell).run
+          ensure
+            app.stop
+          end
+        end
+
+        def snapshot(shell, name, height)
+          shell.puts(R2UI.snapshot(name, width: shell.width, height: height || shell.height))
+        end
+      end
+    end
+
+    extension :dashboard do
+      helpers do
+        def dashboard(name = nil, file: nil, height: nil)
+          Ext::OpenDashboard.load_dsl
+          if file
+            location = caller_locations(1, 1).first
+            caller_file = location && (location.absolute_path || location.path)
+            load Ext::OpenDashboard.resolve(file, caller_file && File.dirname(File.expand_path(caller_file)))
+          end
+          if shell.interactive?
+            Ext::OpenDashboard.run(shell, name)
+          else
+            Ext::OpenDashboard.snapshot(shell, name, height)
+          end
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+# c11-diff: a unified diff of two texts, the way `git diff` and `diff -u` print one.
+#
+#   changed = diff(deployed_config, local_config, labels: ["config.yml (deployed)", "config.yml (local)"])
+#   say "Nothing to deploy", :muted unless changed
+#
+# prints
+#
+#   --- config.yml (deployed)
+#   +++ config.yml (local)
+#   @@ -2,4 +2,4 @@
+#    env: production
+#   -replicas: 2
+#   +replicas: 4
+#    region: eu
+#    timeout: 30
+#
+# and returns true. Equal texts print nothing and return false, so `diff(a, b) or say("up to date")`
+# reads naturally.
+#
+# `old` and `new` are Strings (split into lines) or Arrays of lines. `labels:` names the two sides
+# in the `---`/`+++` header (default `a` and `b`); `context:` is how many unchanged lines surround
+# each change (default 3, 0 for none); changes closer than twice that share a hunk. Hunk headers
+# use diff's numbering (`@@ -3,0 +4 @@` is an insertion after line 3), and a last line without a
+# newline is followed by "", so the output is a patch `patch`/`git apply`
+# accept. The edit is minimal: a pure-Ruby LCS (Myers' O(ND) algorithm, after trimming the common
+# head and tail), fast on large files with few changes.
+#
+# On a terminal (Shell#color?) the header is bold, hunk headers muted, removed lines red and added
+# lines green; tabs and trailing spaces are kept as they are. Off a terminal (a pipe, CI,
+# `NO_COLOR`) the same text without escape codes. It goes to stdout through the Shell; inside a
+# Live region (tasks, spinners) it prints above it.
+module R2UI
+  module CLI
+    module Ext
+      module UnifiedDiff
+        # One line of the edit: :same, :del or :ins, the line (with its newline, if it has one),
+        # and how many lines of each side come before it.
+        Op = Struct.new(:kind, :line, :a, :b)
+
+        SIGNS = { same: " ", del: "-", ins: "+" }.freeze
+        STYLES = { same: [], del: [:error], ins: [:success] }.freeze
+        NO_NEWLINE = "\"
+
+        module_function
+
+        # The diff's lines (without newlines), painted for the shell; [] when the texts are equal.
+        def render(shell, old, new, labels:, context:)
+          ops = edits(lines(old), lines(new))
+          groups = hunks(ops, context)
+          return [] if groups.empty?
+
+          out = ["--- #{labels[0]}", "+++ #{labels[1]}"].map { |l| shell.paint(l, :heading) }
+          groups.each do |hunk|
+            out << shell.paint(header(hunk), :muted)
+            hunk.each do |op|
+              text = op.line.chomp
+              out << paint_line(shell, "#{SIGNS[op.kind]}#{text}", STYLES[op.kind])
+              out << shell.paint(NO_NEWLINE, :muted) unless op.line.end_with?("\n")
+            end
+          end
+          out
+        end
+
+        def lines(text)
+          return text.map { |line| "#{line.to_s.chomp}\n" } if text.is_a?(Array)
+
+          text.to_s.lines
+        end
+
+        # Paints around tabs: lipgloss would expand them, and the text must stay the same.
+        def paint_line(shell, line, styles)
+          return line if styles.empty?
+
+          line.split("\t", -1).map { |part| shell.paint(part, *styles) }.join("\t")
+        end
+
+        # The edit from a to b, as Ops in order.
+        def edits(a, b)
+          head = 0
+          head += 1 while head < a.size && head < b.size && a[head] == b[head]
+          tail = 0
+          tail += 1 while tail < a.size - head && tail < b.size - head && a[-1 - tail] == b[-1 - tail]
+          kinds = Array.new(head, :same) +
+                  myers(a[head...(a.size - tail)], b[head...(b.size - tail)]) +
+                  Array.new(tail, :same)
+
+          i = j = 0
+          kinds.map do |kind|
+            op = Op.new(kind, kind == :ins ? b[j] : a[i], i, j)
+            i += 1 unless kind == :ins
+            j += 1 unless kind == :del
+            op
+          end
+        end
+
+        # Myers' greedy shortest edit script: the kinds of each step, deletions before insertions.
+        def myers(a, b)
+          n = a.size
+          m = b.size
+          return Array.new(m, :ins) if n.zero?
+          return Array.new(n, :del) if m.zero?
+
+          v = { 1 => 0 }
+          trace = []
+          (0..(n + m)).each do |d|
+            trace << v.dup
+            (-d..d).step(2) do |k|
+              x = down?(v, k, d) ? v[k + 1] : v[k - 1] + 1
+              y = x - k
+              while x < n && y < m && a[x] == b[y]
+                x += 1
+                y += 1
+              end
+              v[k] = x
+              return backtrack(trace, n, m) if x >= n && y >= m
+            end
+          end
+        end
+
+        def down?(v, k, d) = k == -d || (k != d && v[k - 1] < v[k + 1])
+
+        def backtrack(trace, n, m)
+          x = n
+          y = m
+          kinds = []
+          (trace.size - 1).downto(0) do |d|
+            v = trace[d]
+            k = x - y
+            prev_k = down?(v, k, d) ? k + 1 : k - 1
+            prev_x = v[prev_k]
+            prev_y = prev_x - prev_k
+            while x > prev_x && y > prev_y
+              kinds << :same
+              x -= 1
+              y -= 1
+            end
+            kinds << (x == prev_x ? :ins : :del) if d.positive?
+            x = prev_x
+            y = prev_y
+          end
+          kinds.reverse
+        end
+
+        # The Ops of each hunk: changes with `context` lines around them, merged when they'd touch.
+        def hunks(ops, context)
+          ranges = []
+          ops.each_with_index do |op, i|
+            next if op.kind == :same
+
+            if ranges.any? && i - ranges.last[1] - 1 <= 2 * context
+              ranges.last[1] = i
+            else
+              ranges << [i, i]
+            end
+          end
+          ranges.map do |first, last|
+            ops[[first - context, 0].max..[last + context, ops.size - 1].min]
+          end
+        end
+
+        def header(hunk)
+          old_count = hunk.count { |op| op.kind != :ins }
+          new_count = hunk.count { |op| op.kind != :del }
+          "@@ -#{range(hunk.first.a, old_count)} +#{range(hunk.first.b, new_count)} @@"
+        end
+
+        # diff's numbering: 1-based; an empty range names the line before it.
+        def range(start, count)
+          case count
+          when 0 then "#{start},0"
+          when 1 then (start + 1).to_s
+          else "#{start + 1},#{count}"
+          end
+        end
+      end
+    end
+
+    extension :diff do
+      helpers do
+        def diff(old, new, labels: %w[a b], context: 3)
+          unless context.is_a?(Integer) && !context.negative?
+            raise ArgumentError, "context must be a non-negative Integer, not #{context.inspect}"
+          end
+          raise ArgumentError, "labels must be two names" unless labels.respond_to?(:size) && labels.size == 2
+
+          lines = Ext::UnifiedDiff.render(shell, old, new, labels: labels.to_a, context:)
+          lines.each { |line| shell.puts(line) }
+          !lines.empty?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "shellwords"
+require "tempfile"
+
+# c22-editor: let the user write something in their own editor, like `git commit`.
+#
+#   notes = edit("# Release notes\n\n")                  # => what they saved
+#   config = edit(File.read("app.yml"), ext: ".yml")     # the extension picks the syntax highlighting
+#
+# On a terminal (Shell#interactive?) it writes `text` to a temp file, runs `$VISUAL`, else
+# `$EDITOR`, else `vi` on it in the foreground (on the tool's own terminal) and returns the saved
+# contents. While the editor is open the tool shows
+#
+#   ℹ Waiting for your editor to close the file…
+#
+# (seen behind GUI editors such as `code --wait`), and erases it when the editor exits. The editor
+# command may carry arguments (`EDITOR="code --wait"`). The temp file is removed on every path:
+# return, an editor that fails ("editor vi exited with status 1", a CLI::Error), one that can't be
+# started, or ctrl+c.
+#
+# Off an interactive shell (a pipe, CI, TERM=dumb) there is nobody to edit, so it raises a
+# CLI::Error ("edit needs a terminal ...") without starting the editor; a command exits 1 with
+# that message on stderr. Read the text from a file or stdin instead in that case.
+module R2UI
+  module CLI
+    module Ext
+      module Editor
+        DEFAULT = "vi"
+
+        module_function
+
+        # The editor command as argv words: $VISUAL, $EDITOR, then vi.
+        def command(shell)
+          [shell.env["VISUAL"], shell.env["EDITOR"]].each do |value|
+            words = value.to_s.strip.empty? ? [] : Shellwords.split(value)
+            return words unless words.empty?
+          end
+          [DEFAULT]
+        end
+
+        def edit(shell, text, ext)
+          unless shell.interactive?
+            raise Error, "edit needs a terminal: run this from an interactive shell (it opens $VISUAL or $EDITOR)"
+          end
+
+          words = command(shell)
+          Tempfile.create(["r2ui-edit-", ext.to_s]) do |file|
+            file.write(text.to_s)
+            file.close
+            run(shell, words, file.path)
+            File.read(file.path, mode: "r:UTF-8")
+          end
+        end
+
+        def run(shell, words, path)
+          hint(shell)
+          ok = begin
+            system(*words, path, **redirects(shell))
+          ensure
+            shell.print("\r\e[2K") if shell.live?
+          end
+          name = File.basename(words.first)
+          raise Error, "could not start editor #{name.inspect}: set $VISUAL or $EDITOR" if ok.nil?
+          return if ok
+
+          status = $?
+          raise Error, "editor #{name} exited with status #{status.exitstatus}" if status.exitstatus
+
+          raise Error, "editor #{name} was stopped (signal #{status.termsig})"
+        end
+
+        def hint(shell)
+          return unless shell.live?
+
+          shell.print("#{shell.symbol(:info)} #{shell.paint("Waiting for your editor to close the file…", :muted)}")
+        end
+
+        # The editor gets the tool's own terminal (only real IOs can be handed to a child).
+        def redirects(shell)
+          { in: shell.input, out: shell.output, err: shell.error }.select { |_, io| io.is_a?(IO) }
+        end
+      end
+    end
+
+    extension :editor do
+      helpers do
+        def edit(text = "", ext: ".md")
+          Ext::Editor.edit(shell, text, ext)
+        end
+      end
+    end
+  end
+end