slipway 0.1.0

data/exe/slipway

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# A checkout needs lib on the load path; an installed gem already has it there.
+lib = File.expand_path('../lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'slipway'
+
+exit Slipway.run(ARGV)

data/lib/slipway/cli/builtins.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Slipway
+  module CLI
+    module Builtins
+      MAN_DIR = File.expand_path('../../../man/man1', __dir__)
+
+      def self.all(program:, version:, resolve:, **man)
+        [help(program:, resolve:), version(program:, version:), completion(program:), man(program:, resolve:, **man),
+         complete(resolve:)]
+      end
+
+      def self.version_line(program, version)
+        "#{program} #{version} (ruby #{RUBY_VERSION}) [#{Gem::Platform.local}]"
+      end
+
+      def self.help(program:, resolve:)
+        Command.new(
+          name: 'help', summary: 'Help about any command', section: 'Other Commands',
+          description: "Help provides help for any command in the application.\n" \
+                       "Type #{program} help [path to command] for full details.",
+          examples: [Example.new(comment: 'Show the help of a nested command', command: 'help config view')],
+          positionals: [Positional.new(name: 'COMMAND', required: false, variadic: true,
+                                       completer: ->(given, _current) { subcommand_names(resolve.call, given) })],
+          handler: HelpCommand.new(resolve)
+        )
+      end
+
+      def self.version(program:, version:)
+        Command.new(
+          name: 'version', summary: "Print the version of #{program}", section: 'Other Commands',
+          description: "Print the version of #{program}, the Ruby it runs on and the platform.",
+          examples: [Example.new(comment: 'Print the version', command: 'version')],
+          handler: ->(context, _args, _opts) { context.puts(version_line(program, version)) }
+        )
+      end
+
+      def self.completion(program:)
+        shells = CompletionScripts::SHELLS.join(', ')
+        Command.new(
+          name: 'completion', section: 'Settings Commands',
+          summary: "Output shell completion code for the specified shell (#{shells})",
+          description: "Output shell completion code for the specified shell (#{shells}).\n" \
+                       'The shell code must be evaluated to provide interactive completion of commands, ' \
+                       'resource types and names.',
+          examples: completion_examples(program),
+          positionals: [Positional.new(name: 'SHELL', enum: CompletionScripts::SHELLS)],
+          handler: ->(context, args, _opts) { context.print(CompletionScripts.render(args.first, program)) }
+        )
+      end
+
+      # Keep these paths in step with the install lines in the CompletionScripts headers.
+      def self.completion_examples(program)
+        [
+          Example.new(comment: 'Install bash completions where bash-completion loads them',
+                      command: 'completion bash > "${XDG_DATA_HOME:-$HOME/.local/share}/bash-completion/completions/' \
+                               "#{program}\""),
+          Example.new(comment: 'Install zsh completions in a directory on your fpath',
+                      command: "completion zsh > ~/.zfunc/_#{program}"),
+          Example.new(comment: 'Install fish completions',
+                      command: "completion fish > ~/.config/fish/completions/#{program}.fish")
+        ]
+      end
+
+      # `paths` is called with the environment and answers man_install_dir and man_db_dir for
+      # a bare --install. `exec` and `paths` are injectable so tests can observe the calls.
+      def self.man(program:, resolve:, man_dir: MAN_DIR, exec: Kernel.method(:exec), paths: nil)
+        Command.new(
+          name: 'man', section: 'Settings Commands', summary: 'Show the manual page of a command',
+          description: "Show the manual page of #{program} or of one of its commands with man(1).\n" \
+                       'The pages ship with the gem; --install copies them into a man1 directory and ' \
+                       'says how man(1) finds them.',
+          examples: man_examples,
+          positionals: [Positional.new(name: 'COMMAND', required: false, variadic: true,
+                                       completer: ->(given, _current) { subcommand_names(resolve.call, given) })],
+          options: man_options,
+          handler: ManCommand.new(resolve, man_dir:, exec:, paths:)
+        )
+      end
+
+      def self.man_examples
+        [
+          Example.new(comment: 'Read the page of a command', command: 'man get'),
+          Example.new(comment: 'Install every page for man(1)', command: 'man --install'),
+          Example.new(comment: 'Print the bundled page directory', command: 'man --path')
+        ]
+      end
+
+      def self.man_options
+        [
+          Option.new(long: 'path', description: 'Print the directory of the bundled pages and exit.'),
+          Option.new(long: 'install', argument: 'DIR', optional: true, implicit: true,
+                     description: 'Copy every page into DIR, a man1 directory, or into ' \
+                                  '${XDG_DATA_HOME:-~/.local/share}/man/man1.')
+        ]
+      end
+
+      def self.complete(resolve:)
+        Command.new(
+          name: '__complete', summary: 'Print completion candidates for the given words', hidden: true, raw: true,
+          positionals: [Positional.new(name: 'WORDS', required: false, variadic: true)],
+          handler: ->(context, words, opts) { Completer.new(resolve.call).call(context, words, opts) }
+        )
+      end
+
+      def self.subcommand_names(registry, given)
+        registry.resolve(given).first.visible_subcommands.map(&:name)
+      end
+
+      # `resolve` returns the registry when called, since the builtin is built before the
+      # registry that holds it exists.
+      class HelpCommand
+        def initialize(resolve)
+          @resolve = resolve
+        end
+
+        def call(context, words, _opts)
+          registry = @resolve.call
+          renderer = HelpRenderer.new(registry, context.style)
+          command, path = registry.resolve(words)
+          context.print(words.empty? ? renderer.root : renderer.command(command, path))
+        end
+      end
+
+      class ManCommand
+        # Any of these means the user configured the pager's look, so it is left alone.
+        USER_PAGER_VARIABLES = %w[LESS_TERMCAP_md MANPAGER MANROFFOPT GROFF_NO_SGR].freeze
+        RESET = "\e[0m"
+        NO_DEFAULT_DIR = 'no default install directory is configured; pass --install=DIR'
+        # man(1) looks for section 1 pages in the man1 directory of each MANPATH entry, so the
+        # MANPATH line printed for any other directory would find nothing.
+        SECTION_DIR = 'man1'
+        NOT_A_SECTION_DIR = "invalid argument %s for --install: must be a #{SECTION_DIR} directory, " \
+                            "such as ~/.local/share/man/#{SECTION_DIR}".freeze
+        # An empty DIR would expand to the working directory.
+        INSTALL_EMPTY = 'flag --install must not be empty'
+
+        def initialize(resolve, man_dir:, exec:, paths:)
+          @resolve = resolve
+          @man_dir = man_dir
+          @exec = exec
+          @paths = paths
+        end
+
+        def call(context, args, opts)
+          refuse_arguments(args, opts) if opts[:path] || opts[:install]
+          return context.puts(@man_dir) if opts[:path]
+          return install(context, opts[:install]) if opts[:install]
+
+          show(context, args)
+        end
+
+        private
+
+        def registry = @resolve.call
+
+        # --path and --install ignore COMMAND, and since DIR is optional, a DIR given after a
+        # space arrives as one.
+        def refuse_arguments(args, opts)
+          return if args.empty?
+
+          hint = '; pass the directory as --install=DIR' if opts[:install] == true
+          raise UsageError, "unexpected argument #{args.first.inspect}#{hint}"
+        end
+
+        def show(context, words)
+          _, path = registry.resolve(words)
+          file = File.join(@man_dir, "#{[registry.program, *path].join('-')}.1")
+          raise Slipway::Error, "manual page #{File.basename(file)} not found in #{@man_dir}" unless File.file?(file)
+          raise Slipway::Error, missing_man_message(path) unless man?(context.env)
+
+          @exec.call(pager_env(context), 'man', file)
+        end
+
+        def missing_man_message(path)
+          "man(1) not found; run '#{[registry.program, 'help', *path].join(' ')}' instead"
+        end
+
+        def man?(env)
+          env.fetch('PATH', '').split(File::PATH_SEPARATOR).any? { File.executable?(File.join(it, 'man')) }
+        end
+
+        # LESS_TERMCAP colors only take effect when groff stops emitting SGR itself, hence
+        # GROFF_NO_SGR.
+        def pager_env(context)
+          return {} unless context.color? && USER_PAGER_VARIABLES.none? { set?(context.env[it]) }
+
+          theme = context.style.theme
+          { 'GROFF_NO_SGR' => '1',
+            'LESS_TERMCAP_md' => sgr(theme.sgr(:help_header)), 'LESS_TERMCAP_me' => RESET,
+            'LESS_TERMCAP_us' => sgr("4;#{theme.sgr(:help_flag)}"), 'LESS_TERMCAP_ue' => RESET,
+            'LESS_TERMCAP_so' => sgr("7;#{theme.sgr(:status_warning)}"), 'LESS_TERMCAP_se' => RESET }
+        end
+
+        def sgr(parameters) = "\e[#{parameters}m"
+
+        def set?(value) = !value.to_s.empty?
+
+        def install(context, target)
+          paths = @paths&.call(context.env)
+          dir = target == true ? default_install_dir(paths) : named_install_dir(target)
+          pages = Dir[File.join(@man_dir, '*.1')]
+          raise Slipway::Error, "no manual pages found in #{@man_dir}" if pages.empty?
+
+          FileUtils.mkdir_p(dir)
+          pages.each do |page|
+            FileUtils.cp(page, dir)
+            context.puts("installed #{File.join(dir, File.basename(page))}")
+          end
+          context.puts(install_note(paths, dir))
+        end
+
+        def default_install_dir(paths)
+          raise Slipway::Error, NO_DEFAULT_DIR if paths.nil?
+
+          paths.man_install_dir
+        end
+
+        def named_install_dir(target)
+          raise UsageError, INSTALL_EMPTY if target.strip.empty?
+
+          dir = File.expand_path(target)
+          raise UsageError, format(NOT_A_SECTION_DIR, target.inspect) unless File.basename(dir) == SECTION_DIR
+
+          dir
+        end
+
+        # man-db adds ~/.local/share/man on its own only when ~/.local/bin is on PATH.
+        def install_note(paths, dir)
+          if paths && dir == paths.man_db_dir
+            'man-db searches ~/.local/share/man when ~/.local/bin is on PATH; otherwise add it to MANPATH.'
+          else
+            %(export MANPATH="#{File.dirname(dir)}:$MANPATH")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/slipway/cli/completer.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Slipway
+  module CLI
+    # Speaks cobra's __complete protocol: one candidate per line, as `value` or
+    # `value<TAB>description`, then a final `:N` line. N is a sum of cobra's directives: 4 when
+    # the shell must not complete file names in place of the candidates, 2 when it must not add a
+    # space after the one it inserts, and 0 lets the shell complete file names.
+    #
+    # A completer proc on an Option or Positional receives the positional words typed so far and
+    # the word being completed, without a `--flag=` in front of it, and may return an Array of
+    # values, a Hash of value to description, either of them wrapped in NoSpace, or FILES to
+    # request file completion. The candidates are filtered by that word afterwards. Never raises:
+    # on any error only `:4` is printed.
+    class Completer
+      FILES = :files
+      FILES_DIRECTIVE = 0
+      NO_SPACE_DIRECTIVE = 2
+      NO_FILES_DIRECTIVE = 4
+      # Candidates the user goes on typing after, such as a field path that continues after a
+      # dot: the shell adds no space after the one it inserts. The directive covers the whole
+      # answer, so a completer returns NoSpace only when a candidate that matches the word goes
+      # on, and a finished value still gets its space.
+      NoSpace = Data.define(:candidates)
+      # bash splits `--flag=value` at the `=` (COMP_WORDBREAKS), so the separator may arrive
+      # as a word of its own between the flag and its value.
+      EQUALS = '='
+      INLINE_VALUE = /\A--[^=]+=/
+
+      def initialize(registry)
+        @registry = registry
+      end
+
+      def call(context, words, _opts)
+        candidates, directive = safely { complete(words) }
+        candidates.each { |value, description| context.puts(description ? "#{value}\t#{description}" : value) }
+        context.puts(":#{directive}")
+      end
+
+      def complete(words)
+        words = words.dup
+        current = words.pop || ''
+        state = replay(words)
+        return [[], NO_FILES_DIRECTIVE] unless state
+
+        case candidates_for(state, current)
+        in FILES then [[], FILES_DIRECTIVE]
+        in NoSpace(candidates:) then [select(candidates, state, current), NO_FILES_DIRECTIVE | NO_SPACE_DIRECTIVE]
+        in candidates then [select(candidates, state, current), NO_FILES_DIRECTIVE]
+        end
+      end
+
+      private
+
+      # `pending` is an option still waiting for its value; `literal` is set once `--` is seen.
+      State = Struct.new(:command, :args, :pending, :literal)
+      private_constant :State
+
+      def safely
+        yield
+      rescue StandardError
+        [[], NO_FILES_DIRECTIVE]
+      end
+
+      def replay(words)
+        words.reduce(State.new(@registry.root, [], nil, false)) { |state, word| consume(state, word) or return nil }
+      end
+
+      def consume(state, word)
+        if state.pending then consume_value(state, word)
+        elsif word == '--' && !state.literal then state.literal = true
+        elsif option_word?(word, state) then state.pending = pending_option(word, state)
+        elsif state.command.group? then state.command = state.command.find(word) or return nil
+        else state.args << word
+        end
+        state
+      end
+
+      # A lone `=` keeps the option open so the next word is still its value.
+      def consume_value(state, word)
+        state.pending = nil unless word == EQUALS
+      end
+
+      def option_word?(word, state) = word.start_with?('-') && !state.literal
+
+      # An optional-argument option only takes its value attached, so it never waits.
+      def pending_option(word, state)
+        name = option_name(word)
+        return nil unless name
+
+        option = option_for(state.command, name)
+        option unless option.nil? || option.flag? || option.optional
+      end
+
+      # nil when the value is attached: `--x=v`, `-ov`.
+      def option_name(word)
+        case word
+        when INLINE_VALUE then nil
+        when /\A--(.+)\z/, /\A-(.)\z/ then Regexp.last_match(1)
+        end
+      end
+
+      def option_for(command, name)
+        options_of(command).find { it.long == name || it.short == name }
+      end
+
+      def options_of(command) = @registry.globals + command.options
+
+      def candidates_for(state, current)
+        return values_of(state.pending, state.args, prefix(state, current)) if state.pending
+        return inline_value_candidates(state, current) if current.match?(INLINE_VALUE)
+        return switch_candidates(state.command) if option_word?(current, state)
+        return subcommand_candidates(state.command) if state.command.group?
+
+        values_of(state.command.positional_at(state.args.size), state.args, current)
+      end
+
+      def values_of(target, args, current)
+        within(target&.candidates(args, current) || []) do |values|
+          values.is_a?(Hash) ? values.to_a : values.map { [it, nil] }
+        end
+      end
+
+      # Values for `--flag=partial` carry the `--flag=` prefix so they replace the whole word.
+      def inline_value_candidates(state, current)
+        flag, typed = current.split(EQUALS, 2)
+        values = values_of(option_for(state.command, flag.delete_prefix('--')), state.args, typed)
+        within(values) { |pairs| pairs.map { |value, description| ["#{flag}=#{value}", description] } }
+      end
+
+      # Yields the candidates, unwrapped from a NoSpace and wrapped back; FILES passes through.
+      def within(values)
+        case values
+        in FILES then FILES
+        in NoSpace(candidates:) then NoSpace.new(yield(candidates))
+        else yield(values)
+        end
+      end
+
+      def switch_candidates(command)
+        options_of(command).flat_map { |option| option.switches.map { [it, option.description] } }
+      end
+
+      def subcommand_candidates(command)
+        command.visible_subcommands.map { [it.name, it.summary] }
+      end
+
+      def prefix(state, current)
+        state.pending && current == EQUALS ? '' : current
+      end
+
+      def select(candidates, state, current)
+        typed = prefix(state, current)
+        candidates.select { |value, _| value.start_with?(typed) && !state.args.include?(value) }
+      end
+    end
+  end
+end

data/lib/slipway/cli/completion_scripts.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Slipway
+  module CLI
+    # Every request goes to `PROGRAM __complete WORDS...`, so the scripts never change when
+    # commands do.
+    module CompletionScripts
+      SHELLS = %w[bash zsh fish].freeze
+
+      def self.render(shell, program)
+        RENDERERS.fetch(shell).render(program)
+      end
+
+      # _comp_initialize is bash-completion 2.12+ and _init_completion the older name; without
+      # either, COMP_WORDS is read directly.
+      module Bash
+        def self.render(program)
+          <<~BASH
+            # bash completion for #{program}                             -*- shell-script -*-
+            # Install to ${XDG_DATA_HOME:-~/.local/share}/bash-completion/completions/#{program}
+            # or load it with: eval "$(#{program} completion bash)"
+            _#{program}() {
+                # prev is filled by the bash-completion initializers; it stays local, not global.
+                # shellcheck disable=SC2034
+                local cur prev words cword
+                if declare -F _comp_initialize >/dev/null 2>&1; then
+                    _comp_initialize -n = -- "$@" || return
+                elif declare -F _init_completion >/dev/null 2>&1; then
+                    _init_completion -n = || return
+                else
+                    words=("${COMP_WORDS[@]}") cword=$COMP_CWORD cur=${COMP_WORDS[COMP_CWORD]}
+                fi
+
+                local out directive
+                out=$("${words[0]}" __complete "${words[@]:1:cword-1}" "$cur" 2>/dev/null) || return
+                directive=${out##*$'\\n':}
+                [[ $out == :* ]] && directive=${out#:}
+                out=${out%$'\\n'*}
+                [[ $out == :* ]] && out=""
+
+                COMPREPLY=()
+                local line
+                if [[ -n $out ]]; then
+                    while IFS= read -r line; do COMPREPLY+=("${line%%$'\\t'*}"); done <<<"$out"
+                fi
+                # readline still breaks the word at "=", so "--flag=" must leave the replies.
+                if [[ $cur == -*=* && $COMP_WORDBREAKS == *=* ]]; then
+                    local i prefix=${cur%%=*}=
+                    for i in "${!COMPREPLY[@]}"; do COMPREPLY[i]=${COMPREPLY[i]#"$prefix"}; done
+                fi
+                (( directive & 2 )) && compopt -o nospace 2>/dev/null
+                if (( ${#COMPREPLY[@]} == 0 )) && ! (( directive & 4 )); then
+                    if declare -F _comp_compgen_filedir >/dev/null 2>&1; then
+                        _comp_compgen_filedir
+                    elif declare -F _filedir >/dev/null 2>&1; then
+                        _filedir
+                    elif ! compopt -o default 2>/dev/null; then
+                        mapfile -t COMPREPLY < <(compgen -f -- "$cur")
+                    fi
+                fi
+            }
+            complete -F _#{program} #{program}
+          BASH
+        end
+      end
+
+      # Builds `value:description` pairs for _describe; a `--flag=` prefix is moved into
+      # IPREFIX with compset so the values alone are listed.
+      module Zsh
+        def self.render(program)
+          <<~ZSH
+            #compdef #{program}
+            # zsh completion for #{program}. Install it as _#{program} in a directory on your fpath,
+            # such as ~/.zfunc/_#{program} with `fpath+=~/.zfunc` before compinit, or load it
+            # with: source <(#{program} completion zsh)
+            compdef _#{program} #{program}
+
+            _#{program}() {
+                local -a lines candidates describe_opts
+                local line directive prefix="" ret=1
+                lines=("${(@f)$(${words[1]} __complete "${(@)words[2,CURRENT-1]}" "${words[CURRENT]}" 2>/dev/null)}")
+                (( ${#lines} )) || return 1
+                directive=${lines[-1]#:}
+                lines=("${(@)lines[1,-2]}")
+                compset -P '--[^=]#=' && prefix=$IPREFIX
+                for line in "${lines[@]}"; do
+                    [[ -z $line ]] && continue
+                    line=${line#"$prefix"}
+                    if [[ $line == *$'\\t'* ]]; then
+                        candidates+=("${${line%%$'\\t'*}//:/\\\\:}:${line#*$'\\t'}")
+                    else
+                        candidates+=("${line//:/\\\\:}")
+                    fi
+                done
+                (( directive & 2 )) && describe_opts+=(-S '')
+                if (( ${#candidates} )); then
+                    _describe -t values '#{program}' candidates "${describe_opts[@]}" && ret=0
+                fi
+                if (( ret )) && ! (( directive & 4 )); then
+                    _files && ret=0
+                fi
+                return ret
+            }
+
+            if [[ "$funcstack[1]" == "_#{program}" ]]; then
+                _#{program} "$@"
+            fi
+          ZSH
+        end
+      end
+
+      # Both completion conditions call __PROGRAM_complete, so the answer is cached per command
+      # line. fish reads `value<TAB>description` lines natively. It has no switch to leave out the
+      # space after a candidate: it adds none only after one that ends in one of @=/:., or while
+      # several remain. So, as cobra does, a lone candidate under the no-space directive gets a
+      # copy with a dot after it, and fish inserts what the two share.
+      module Fish
+        def self.render(program)
+          <<~FISH
+            # fish completion for #{program}. Install it to ~/.config/fish/completions/#{program}.fish
+            function __#{program}_complete
+                set -l line (commandline -cp)
+                if set -q __#{program}_line; and test "$__#{program}_line" = "$line"
+                    return 0
+                end
+                set -g __#{program}_line $line
+                set -g __#{program}_directive 4
+                set -g __#{program}_results
+                set -l tokens (commandline -opc)
+                set -l program $tokens[1]
+                set -e tokens[1]
+                set -l lines ($program __complete $tokens (commandline -ct) 2>/dev/null)
+                or return 0
+                if test (count $lines) -gt 0
+                    set -g __#{program}_directive (string replace -r '^:' '' -- $lines[-1])
+                    set -e lines[-1]
+                    set -g __#{program}_results $lines
+                end
+                if test (count $__#{program}_results) -eq 1; and test (math "bitand($__#{program}_directive, 2)") -ne 0
+                    set -l value (string split -m 1 \\t -- $__#{program}_results[1])[1]
+                    if not string match -qr '[@=/:.,]$' -- $value
+                        set -g __#{program}_results $value $value.
+                    end
+                end
+            end
+
+            function __#{program}_wants_files
+                __#{program}_complete
+                test (count $__#{program}_results) -eq 0
+                and test (math "bitand($__#{program}_directive, 4)") -eq 0
+            end
+
+            complete -c #{program} -e
+            complete -c #{program} -n '__#{program}_complete' -f -a '$__#{program}_results'
+            complete -c #{program} -n '__#{program}_wants_files' -a '(__fish_complete_path (commandline -ct))'
+          FISH
+        end
+      end
+
+      RENDERERS = { 'bash' => Bash, 'zsh' => Zsh, 'fish' => Fish }.freeze
+    end
+  end
+end

data/lib/slipway/cli/context.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative 'style'
+require_relative 'theme'
+
+module Slipway
+  module CLI
+    # Color is decided for stdout and stderr apart. A stream whose reader went away is
+    # remembered and its later output dropped, so a command finishes its work when `head`
+    # exits or a wrapper closed stderr.
+    class Context
+      attr_reader :out, :err, :env, :tty, :err_tty, :style, :err_style
+
+      def self.system
+        new(out: $stdout, err: $stderr, env: ENV, tty: $stdout.tty?, err_tty: $stderr.tty?)
+      end
+
+      def initialize(out:, err:, env: {}, tty: false, err_tty: false,
+                     style: Style.disabled, err_style: Style.disabled)
+        @out = out
+        @err = err
+        @env = env
+        @tty = tty
+        @err_tty = err_tty
+        @style = style
+        @err_style = err_style
+        @closed = {}
+      end
+
+      # The copy shares this context's memory of closed streams.
+      def with_color(mode, theme: Theme.default)
+        dup.tap { it.restyle(Style.for(mode, tty:, env:, theme:), Style.for(mode, tty: err_tty, env:, theme:)) }
+      end
+
+      def puts(*lines) = write(:out) { out.puts(*lines) }
+
+      def print(*parts) = write(:out) { out.print(*parts) }
+
+      def warn(*lines) = write(:err) { err.puts(*lines) }
+
+      def unbuffer = out.sync = true
+
+      def paint(role, text) = style.paint(role, text)
+
+      def paint_err(role, text) = err_style.paint(role, text)
+
+      def color? = style.enabled?
+
+      protected
+
+      def restyle(style, err_style)
+        @style = style
+        @err_style = err_style
+      end
+
+      private
+
+      def write(stream)
+        return if @closed[stream]
+
+        yield
+      rescue Errno::EPIPE
+        @closed[stream] = true
+      end
+    end
+  end
+end

data/lib/slipway/cli/errors.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative '../error'
+
+module Slipway
+  module CLI
+    class UsageError < Slipway::Error
+      # A nil hint is filled in by the Runner from the resolved command path.
+      attr_reader :hint
+
+      def initialize(message, hint: nil)
+        super(message)
+        @hint = hint
+      end
+
+      def exit_status = 2
+    end
+  end
+end