slipway 0.1.0

data/lib/slipway/cli/runner.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+require_relative 'style'
+require_relative 'theme'
+require_relative 'globals'
+require_relative 'parser'
+require_relative 'validator'
+require_relative 'help_renderer'
+require_relative 'builtins'
+
+module Slipway
+  module CLI
+    # Returns the exit status and never lets an exception escape as a backtrace.
+    class Runner
+      SIGINT_STATUS = 130
+      EPIPE_STATUS = 0
+      UNEXPECTED_STATUS = 1
+      COLOR_VARIABLE = 'SLIPWAY_COLOR'
+      THEME_VARIABLE = 'SLIPWAY_THEME'
+      DEBUG_VARIABLE = 'SLIPWAY_DEBUG'
+      COLOR_FLAG = "--#{Globals::COLOR.long}".freeze
+      COLOR_INLINE = "#{COLOR_FLAG}=".freeze
+
+      # `color` and `theme` are the fallbacks used when neither a flag nor the environment
+      # decides, which is where the configuration file values arrive.
+      def initialize(registry, context, color: nil, theme: nil)
+        @registry = registry
+        @context = context
+        @default_color = color
+        @default_theme = theme
+      end
+
+      # The Context drops output once a stream's reader is gone, so a broken pipe reaching here
+      # comes from a handler writing past the Context; it ends the run quietly.
+      def run(argv)
+        execute(argv.dup)
+      rescue Errno::EPIPE
+        EPIPE_STATUS
+      end
+
+      private
+
+      # Color is settled first, from `--color` typed anywhere on the line or from the
+      # environment, so even an error in the parse that follows is painted the way the user asked.
+      def execute(argv)
+        @flag_color = flag_color(argv)
+        colorize({})
+        dispatch(argv)
+      rescue Errno::EPIPE
+        raise
+      rescue Slipway::Error => e
+        report(e.problems, e.hint, layout: e.is_a?(UsageError))
+        e.exit_status
+      rescue Interrupt
+        @context.err.write("\n")
+        SIGINT_STATUS
+      rescue StandardError => e
+        report_unexpected(e)
+        UNEXPECTED_STATUS
+      end
+
+      def dispatch(argv)
+        values = {}
+        command, path, rest = walk(argv, values)
+        return run_raw(command, rest) if command.raw
+
+        args = parse(@registry.globals + command.options, path, values) { it.permute!(rest) }
+        opts = defaults(command, values)
+        return show_help(command, path) if opts[:help]
+        return show_version if opts[:version]
+        return show_help(command, path) if command.group?
+
+        Validator.new(command, path, @registry).call(args, opts)
+        invoke(command, path, args, opts)
+      end
+
+      # Globals are parsed before every word, so they may appear before the verb and between a
+      # group and its subcommand.
+      def walk(argv, values)
+        command = @registry.root
+        path = []
+        while command.group?
+          argv = parse(@registry.globals, path, values) { it.order!(argv) }
+          word = argv.shift
+          return [command, path, argv] if word.nil?
+
+          command = command.find(word) or raise unknown_command(word, path)
+          path << word
+        end
+        [command, path, argv]
+      end
+
+      def unknown_command(word, path)
+        UsageError.new(@registry.unknown_command(word, path), hint: @registry.run_hint(path))
+      end
+
+      # Color is re-resolved after every parse step, so a `--color` the parser has just
+      # read applies to the error that may follow it.
+      def parse(options, path, values)
+        parser = Parser.new(options, values)
+        yield parser
+      rescue OptionParser::InvalidOption => e
+        raise UsageError.new(@registry.unknown_option(e.args.first, options), hint: @registry.help_hint(path))
+      rescue OptionParser::ParseError => e
+        raise UsageError.new(e.message, hint: @registry.help_hint(path))
+      ensure
+        colorize(values)
+      end
+
+      def defaults(command, values)
+        Parser.new(@registry.globals + command.options, values).defaults.freeze
+      end
+
+      # Taken as typed; the Validator reports an invalid value once the parse reaches it.
+      def flag_color(argv)
+        argv.take_while { it != '--' }.reverse_each do |word|
+          return Globals::COLOR.implicit if word == COLOR_FLAG
+          return word.delete_prefix(COLOR_INLINE) if word.start_with?(COLOR_INLINE)
+        end
+        nil
+      end
+
+      def colorize(values)
+        @context = @context.with_color(values.fetch(:color) { @flag_color || fallback_color }, theme:)
+      end
+
+      def fallback_color
+        @fallback_color ||= environment(COLOR_VARIABLE, Style::MODES) || @default_color || Style::DEFAULT_MODE
+      end
+
+      def theme
+        @theme ||= Theme.fetch(environment(THEME_VARIABLE, Theme::NAMES) || @default_theme || Theme::DEFAULT_NAME)
+      end
+
+      # An invalid value is reported the way the configuration file reports the same key.
+      def environment(name, allowed = nil)
+        value = @context.env[name]
+        return nil if value.to_s.empty?
+        return value if allowed.nil? || allowed.include?(value)
+
+        raise Slipway::Error, "#{name}: must be one of #{allowed.join(', ')}"
+      end
+
+      def invoke(command, path, args, opts)
+        command.handler.call(@context, args, opts)
+        0
+      rescue UsageError => e
+        raise if e.hint
+
+        raise UsageError.new(e.message, hint: @registry.help_hint(path))
+      end
+
+      def run_raw(command, rest)
+        command.handler.call(@context, rest, {})
+        0
+      end
+
+      def show_help(command, path)
+        renderer = HelpRenderer.new(@registry, @context.style)
+        @context.print(command.equal?(@registry.root) ? renderer.root : renderer.command(command, path))
+        0
+      end
+
+      def show_version
+        @context.puts(Builtins.version_line(@registry.program, @registry.version))
+        0
+      end
+
+      # A problem can quote git's stderr, a manifest field, a path or a typed word, so nothing reaches
+      # stderr raw. Only a usage error keeps its line feeds, for its "Did you mean this?" list.
+      def report(problems, hint, layout: false)
+        prefix = @context.paint_err(:error, 'error:')
+        problems.each { @context.warn("#{prefix} #{Style.plain(it, layout:)}") }
+        @context.warn(Style.plain(hint)) if hint
+      end
+
+      def report_unexpected(error)
+        report([error.message], nil)
+        return unless environment(DEBUG_VARIABLE)
+
+        @context.warn(error.class.name, *Array(error.backtrace).map { "    #{it}" })
+      end
+    end
+  end
+end

data/lib/slipway/cli/style.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Slipway
+  module CLI
+    class Style
+      MODES = %w[auto always never].freeze
+      DEFAULT_MODE = 'auto'
+      FORCE_VARIABLES = %w[FORCE_COLOR CLICOLOR_FORCE].freeze
+      # C0 and C1 control characters, DEL, and the bidirectional embedding, override and isolate
+      # controls: everything a terminal would obey, or use to reorder a line, instead of show.
+      CONTROL = /[\x00-\x1F\x7F\u0080-\u009F\u202A-\u202E\u2066-\u2069]/
+      REPLACEMENT = "\uFFFD"
+      LAYOUT = "\t\n"
+
+      attr_reader :theme
+
+      def self.for(mode, tty:, env:, theme: Theme.default)
+        new(enabled: enabled?(mode, tty:, env:), theme:)
+      end
+
+      def self.enabled?(mode, tty:, env:)
+        case mode
+        when 'always' then true
+        when 'never' then false
+        else auto?(tty:, env:)
+        end
+      end
+
+      def self.auto?(tty:, env:)
+        return false if set?(env['NO_COLOR'])
+        return true if FORCE_VARIABLES.any? { set?(env[it]) }
+        return false if env['TERM'] == 'dumb'
+
+        tty
+      end
+
+      def self.set?(value) = !value.to_s.empty?
+
+      private_class_method :enabled?, :auto?, :set?
+
+      def self.disabled = new(enabled: false, theme: Theme.default)
+
+      # Painting is how slipway's own escape sequences reach a stream. Text from anywhere else is
+      # made visible, so a commit subject, a git message or a manifest field can neither move the
+      # cursor nor paint a STATUS of its own: C0 characters and DEL take caret notation
+      # (ESC is ^[, DEL is ^?), the rest the replacement character. `layout` keeps line feeds and
+      # tabs, for a message laid out on several lines such as "Did you mean this?". Under the C
+      # locale Ruby hands ARGV, ENV and paths over as BINARY, which a UTF-8 pattern cannot match;
+      # reading the bytes as UTF-8 keeps the valid ones and scrubs the rest.
+      def self.plain(text, layout: false)
+        String.new(text.to_s, encoding: Encoding::UTF_8).scrub.gsub(CONTROL) do |char|
+          next char if layout && LAYOUT.include?(char)
+
+          char.ord < 0x80 ? "^#{((char.ord + 0x40) & 0x7F).chr}" : REPLACEMENT
+        end
+      end
+
+      def initialize(enabled:, theme:)
+        @enabled = enabled
+        @theme = theme
+      end
+
+      def enabled? = @enabled
+
+      def paint(role, text)
+        wrap(theme.sgr(role), text)
+      end
+
+      def paint_cycle(role, index, text)
+        wrap(theme.sgr_at(role, index), text)
+      end
+
+      private
+
+      def wrap(sgr, text)
+        return text.to_s unless @enabled
+
+        "\e[#{sgr}m#{text}\e[0m"
+      end
+    end
+  end
+end

data/lib/slipway/cli/theme.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Slipway
+  module CLI
+    # The presets follow kubecolor's dark and light themes.
+    class Theme
+      # Roles whose value is a list are cycled by an index (column or nesting depth).
+      DARK = {
+        table_header: '1',
+        table_columns: %w[37 36],
+        describe_keys: %w[96 36],
+        explain_required: '31',
+        string: '93',
+        number: '35',
+        boolean_true: '32',
+        boolean_false: '31',
+        none: '90;3',
+        status_success: '32',
+        status_warning: '33',
+        status_danger: '31',
+        muted: '90;3',
+        help_header: '1',
+        help_flag: '36',
+        help_command: '32',
+        help_comment: '90;3',
+        apply_created: '32',
+        apply_configured: '33',
+        apply_unchanged: '35',
+        create_created: '32',
+        delete_deleted: '31',
+        label_labeled: '32',
+        label_unlabeled: '33',
+        label_not_labeled: '90;3',
+        result_changed: '32',
+        result_unchanged: '35',
+        result_skipped: '33',
+        result_paused: '90;3',
+        result_denied: '31',
+        result_failed: '31',
+        dry_run: '36',
+        error: '31',
+        warning: '33'
+      }.freeze
+
+      # White becomes black, cyan blue and bright yellow plain yellow, to read on a light background.
+      LIGHT = DARK.merge(
+        table_columns: %w[30 34],
+        describe_keys: %w[94 34],
+        string: '33',
+        help_flag: '34',
+        dry_run: '34'
+      ).freeze
+
+      PRESETS = { 'dark' => DARK, 'light' => LIGHT }.freeze
+      NAMES = PRESETS.keys.freeze
+      DEFAULT_NAME = 'dark'
+
+      attr_reader :name
+
+      # Callers check `name` against NAMES first, so an unknown name here is a bug.
+      def self.fetch(name)
+        new(name, PRESETS.fetch(name))
+      end
+
+      def self.default = fetch(DEFAULT_NAME)
+
+      def initialize(name, roles)
+        @name = name
+        @roles = roles
+      end
+
+      def sgr(role)
+        value = @roles.fetch(role)
+        raise ArgumentError, "role #{role.inspect} is a list; use sgr_at" if value.is_a?(Array)
+
+        value
+      end
+
+      def sgr_at(role, index)
+        values = Array(@roles.fetch(role))
+        values[index % values.size]
+      end
+    end
+  end
+end

data/lib/slipway/cli/validator.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Slipway
+  module CLI
+    class Validator
+      def initialize(command, path, registry)
+        @command = command
+        @path = path
+        @registry = registry
+      end
+
+      def call(args, opts)
+        check_arity(args)
+        check_positional_enums(args)
+        check_required(opts)
+        check_option_enums(opts)
+      end
+
+      private
+
+      def check_arity(args)
+        if args.size < @command.min_args
+          missing = @command.positionals[args.size]
+          usage_error("missing required argument #{missing.name.inspect}")
+        end
+        max = @command.max_args
+        usage_error("unexpected argument #{args[max].inspect}") if max && args.size > max
+      end
+
+      def check_positional_enums(args)
+        args.each_with_index do |arg, index|
+          positional = @command.positional_at(index)
+          next unless positional&.enum && !positional.enum.include?(arg)
+
+          usage_error("invalid argument #{arg.inspect} for #{positional.name}: #{allowed(positional.enum)}")
+        end
+      end
+
+      def check_required(opts)
+        @command.options.select(&:required).each do |opt|
+          usage_error("required flag(s) #{"--#{opt.long}".inspect} not set") if opts[opt.key].nil?
+        end
+      end
+
+      def check_option_enums(opts)
+        (@registry.globals + @command.options).select(&:enum).each do |opt|
+          value = opts[opt.key]
+          next if value.nil? || opt.enum.include?(value)
+
+          usage_error("invalid argument #{value.inspect} for --#{opt.long}: #{allowed(opt.enum)}")
+        end
+      end
+
+      def allowed(values) = "must be one of #{values.join(', ')}"
+
+      def usage_error(message)
+        raise UsageError.new(message, hint: @registry.help_hint(@path))
+      end
+    end
+  end
+end

data/lib/slipway/cli.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'did_you_mean'
+require_relative 'cli/errors'
+require_relative 'cli/theme'
+require_relative 'cli/style'
+require_relative 'cli/context'
+require_relative 'cli/registry'
+require_relative 'cli/globals'
+require_relative 'cli/parser'
+require_relative 'cli/validator'
+require_relative 'cli/help_renderer'
+require_relative 'cli/completer'
+require_relative 'cli/completion_scripts'
+require_relative 'cli/manpage'
+require_relative 'cli/builtins'
+require_relative 'cli/runner'
+
+module Slipway
+  module CLI
+  end
+end

data/lib/slipway/command_line.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+require_relative 'paths'
+
+module Slipway
+  # The git command lines slipway prints for the user to run. Slipway never runs them.
+  module CommandLine
+    # Joins `words` as given, so a literal such as @{upstream}..HEAD prints as it is typed; a
+    # caller quotes any word a manifest or git supplied, as Plan does.
+    def self.git(project, *words) = ['git', '-C', path(project.path), *words].join(' ')
+
+    # The path as the manifest writes it, so the line matches what was registered. Only the part
+    # after ~ is quoted, since a shell does not expand a quoted ~.
+    def self.path(path)
+      rest = path.sub(Paths::TILDE, '')
+      return Shellwords.escape(path) if rest == path
+
+      rest.empty? ? '~' : "~#{Shellwords.escape(rest)}"
+    end
+  end
+end

data/lib/slipway/commands/api_resources.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Slipway
+  module Commands
+    class APIResources < Base
+      DESCRIPTION = "Print the supported resource types.\n\n" \
+                    'Prints a table of the resource types slipway knows, sorted by name. A command accepts a type ' \
+                    'by its NAME, its singular or one of its SHORTNAMES. Type words are case-insensitive. Use -o ' \
+                    'wide to add the verbs that act on each type, and -o name to print only the names.'
+      COLUMNS = {
+        'NAME' => 'The name of the type, in the plural.',
+        'SHORTNAMES' => 'The aliases of the type, besides its singular.',
+        'KIND' => 'The kind a manifest of the type declares.',
+        'GROUPED' => 'Whether resources of the type live in a group, so that -n and -A scope them. kubectl\'s ' \
+                     'NAMESPACED column says the same about namespaces.',
+        'VERBS' => 'The commands that act on resources of the type.'
+      }.freeze
+      WIDE_HEADERS = COLUMNS.keys.freeze
+      HEADERS = (WIDE_HEADERS - ['VERBS']).freeze
+      GLOSSARIES = [
+        CLI::Glossary.new(title: 'Columns',
+                          intro: 'Every type shows NAME, SHORTNAMES, KIND and GROUPED, and -o wide adds VERBS. A ' \
+                                 "type without aliases reads #{Output::Table::NONE} in SHORTNAMES.",
+                          entries: COLUMNS)
+      ].freeze
+      OUTPUT = Options::OUTPUT.with(enum: [Output::TABLE, Output::WIDE, Output::NAME])
+
+      def self.command(factory)
+        CLI::Command.new(
+          name: 'api-resources', summary: 'Print the supported resource types', section: 'Other Commands',
+          description: DESCRIPTION, examples:, glossaries: GLOSSARIES, options: [OUTPUT, Options::NO_HEADERS],
+          handler: new(factory)
+        )
+      end
+
+      def self.examples
+        [
+          CLI::Example.new(comment: 'Print the supported resource types', command: 'api-resources'),
+          CLI::Example.new(comment: 'Print the supported resource types with more information',
+                           command: 'api-resources -o wide'),
+          CLI::Example.new(comment: 'Print the names of the supported resource types', command: 'api-resources -o name')
+        ]
+      end
+      private_class_method :examples
+
+      def run(_runtime, context, _args, opts)
+        types = Resources::KINDS.sort_by(&:plural)
+        case opts[:output]
+        when Output::NAME then types.each { context.puts(it.plural) }
+        when Output::WIDE
+          verbs = verbs_by_kind
+          table(context, opts, WIDE_HEADERS, types.map { [*row(it), verbs.fetch(it)] })
+        else table(context, opts, HEADERS, types.map { row(it) })
+        end
+      end
+
+      private
+
+      def row(kind) = [kind.plural, kind.aliases.join(','), kind.title, kind.namespaced?]
+
+      # The registry that holds this verb is built after it, so the verbs are built again from
+      # VERBS to read what each one acts on.
+      def verbs_by_kind
+        commands = VERBS.map { it.command(@factory) }
+        Resources::KINDS.to_h { |kind| [kind, commands.select { acts_on?(it, kind) }.map(&:name).sort.join(',')] }
+      end
+
+      # A group such as rollout acts on a kind when one of its subcommands does.
+      def acts_on?(command, kind)
+        return command.subcommands.any? { acts_on?(it, kind) } if command.group?
+
+        command.handler.kinds.include?(kind)
+      end
+
+      def table(context, opts, headers, rows)
+        Output::Table.new(context, headers:, show_headers: !opts[:no_headers]).print(rows)
+      end
+    end
+  end
+end