slipway 0.1.0

data/lib/slipway/selector.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require_relative 'cli/errors'
+require_relative 'labels'
+
+module Slipway
+  # A kubectl label selector.
+  class Selector
+    # `values` is sorted and holds one value for = and !=, none for existence checks.
+    Requirement = Data.define(:key, :operator, :values) do
+      def match?(labels)
+        case operator
+        when :equals, :in then labels.key?(key) && values.include?(labels[key])
+        when :not_equals, :not_in then !labels.key?(key) || !values.include?(labels[key])
+        when :exists then labels.key?(key)
+        when :does_not_exist then !labels.key?(key)
+        end
+      end
+
+      # Also the sort key among requirements of one key.
+      def to_s
+        case operator
+        when :equals then "#{key}=#{values.first}"
+        when :not_equals then "#{key}!=#{values.first}"
+        when :in then "#{key} in (#{values.join(',')})"
+        when :not_in then "#{key} notin (#{values.join(',')})"
+        when :exists then key
+        when :does_not_exist then "!#{key}"
+        end
+      end
+    end
+
+    class Parser
+      TOKEN = /==|!=|[=!(),]|[^\s=!(),]+/
+      SYMBOLS = %w[( ) , = == != !].freeze
+      KEYWORDS = { 'in' => :in, 'notin' => :not_in }.freeze
+      EXACT = { '=' => :equals, '==' => :equals, '!=' => :not_equals }.freeze
+
+      def initialize(expression)
+        @expression = expression
+        @tokens = expression.scan(TOKEN)
+        @position = 0
+      end
+
+      def parse
+        return [] if @tokens.empty?
+
+        requirements = [requirement]
+        until peek.nil?
+          expect(',', "expected ',' or the end of the selector")
+          fail!("expected a requirement after ','") if peek.nil?
+          requirements << requirement
+        end
+        requirements.sort_by { [it.key, it.to_s] }
+      end
+
+      private
+
+      def requirement
+        return build(key_after_bang, :does_not_exist, []) if peek == '!'
+
+        key = key_token
+        case peek
+        when nil, ',' then build(key, :exists, [])
+        when *EXACT.keys then build(key, EXACT.fetch(advance), [exact_value])
+        when *KEYWORDS.keys then build(key, KEYWORDS.fetch(advance), set_values)
+        else fail!("unexpected #{peek.inspect} after #{key.inspect}")
+        end
+      end
+
+      def key_after_bang
+        advance
+        fail!("expected a key after '!'") unless identifier?(peek) && !KEYWORDS.key?(peek)
+        advance
+      end
+
+      def key_token
+        return advance if identifier?(peek) && !KEYWORDS.key?(peek)
+
+        fail!(peek.nil? ? 'expected a key' : "expected a key, found #{peek.inspect}")
+      end
+
+      # kubectl reads +key=+ and +key=,other+ as a comparison with the empty value.
+      def exact_value
+        return '' if peek.nil? || peek == ','
+        return advance if identifier?(peek)
+
+        fail!("expected a value, found #{peek.inspect}")
+      end
+
+      # An empty slot, as in +()+ or +(a,)+, is the empty value.
+      def set_values
+        expect('(', "expected '(' after #{@tokens[@position - 1].inspect}")
+        values = []
+        loop do
+          values << (identifier?(peek) ? advance : '')
+          break if accept(')')
+
+          expect(',', "expected ',' or ')' in the value set")
+        end
+        values.uniq.sort
+      end
+
+      def build(key, operator, values)
+        fail!("invalid label key #{key.inspect}") unless Labels.valid_key?(key)
+        values.each { fail!("invalid label value #{it.inspect}") unless Labels.valid_value?(it) }
+        Requirement.new(key:, operator:, values:)
+      end
+
+      def identifier?(token) = !token.nil? && !SYMBOLS.include?(token)
+
+      def peek = @tokens[@position]
+
+      def advance
+        token = peek
+        @position += 1
+        token
+      end
+
+      def accept(token)
+        return unless peek == token
+
+        advance
+      end
+
+      def expect(token, reason)
+        fail!(reason) unless accept(token)
+      end
+
+      def fail!(reason)
+        raise CLI::UsageError, "invalid selector #{@expression.inspect}: #{reason}"
+      end
+    end
+
+    # nil or a blank string selects everything.
+    def self.parse(expression) = new(Parser.new(expression.to_s).parse)
+
+    def initialize(requirements)
+      @requirements = requirements.freeze
+    end
+
+    def match?(labels) = @requirements.all? { it.match?(labels) }
+
+    def to_s = @requirements.join(',')
+  end
+end

data/lib/slipway/settings.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require_relative 'error'
+require_relative 'cli/theme'
+require_relative 'cli/style'
+require_relative 'names'
+
+module Slipway
+  # The settings in effect for one run. Settings.load resolves each from the flag typed on the
+  # command line, then its `SLIPWAY_*` variable, then the configuration file, then its default,
+  # and raises Settings::Error naming the file or the variable whose value is refused.
+  # `variables` maps each key whose value came from its variable to the variable's name.
+  Settings = Data.define(:color, :theme, :editor, :group, :network_timeout, :parallel, :protocols, :path, :exists,
+                         :variables)
+
+  class Settings
+    class Error < Slipway::Error; end
+
+    # A git transport name, spelled as a URL scheme. The names reach GIT_ALLOW_PROTOCOL joined by
+    # colons, so a name holding a colon would allow a transport nobody listed.
+    PROTOCOL = /\A[a-z][a-z0-9+.-]*\z/
+    INTEGER = ->(text) { Integer(text, 10, exception: false) }
+    PARALLEL = 1..16
+    # Capped at a day: Thread#join, which enforces the deadline, takes a timeout past about 1.8e10
+    # seconds as already passed.
+    NETWORK_TIMEOUT = 1..86_400
+    # Colon-separated like GIT_ALLOW_PROTOCOL; an empty field is kept so the check refuses it.
+    LIST = ->(text) { text.split(':', -1) }
+    # Once GIT_ALLOW_PROTOCOL is set it is git's whole policy, and git's own refusal of ext no
+    # longer applies, so these stay refused even when listed.
+    UNSAFE_PROTOCOLS = {
+      'ext' => 'runs a command named in the URL',
+      'fd' => 'reads from file descriptors'
+    }.freeze
+
+    # `parse` reads the string an environment variable holds; what it cannot read comes back as
+    # nil and fails the check with the key's expectation, or with `variable_expectation` when the
+    # variable is written in another form than the file's value. `refusal` says why a value of the
+    # right form is still refused, or returns nil.
+    Setting = Data.define(:key, :variable, :default, :description, :valid, :expectation, :parse,
+                          :variable_expectation, :refusal) do
+      def initialize(parse: :itself.to_proc, variable_expectation: nil, refusal: ->(_) {}, **) = super
+
+      def attribute = key.gsub(/(?=[A-Z])/, '_').downcase.to_sym
+
+      def check(value, prefix, subject: "\"#{key}\" ", expectation: self.expectation)
+        problem = valid.call(value) ? refusal.call(value) : expectation
+        return value if problem.nil?
+
+        raise Error, "#{prefix}: #{subject}#{problem}"
+      end
+
+      def from_variable(text)
+        check(parse.call(text), variable, subject: '', expectation: variable_expectation || expectation)
+      end
+
+      def documentation = [description, default && "Default: #{Array(default).join(', ')}."].compact.join(' ')
+    end
+
+    ALL = [
+      Setting.new(key: 'color', variable: 'SLIPWAY_COLOR', default: CLI::Style::DEFAULT_MODE,
+                  description: 'When to color output: auto, always or never.',
+                  valid: ->(value) { CLI::Style::MODES.include?(value) },
+                  expectation: "must be one of #{CLI::Style::MODES.join(', ')}"),
+      Setting.new(key: 'editor', variable: 'SLIPWAY_EDITOR', default: nil,
+                  description: 'Command line of the editor that slipway edit opens.',
+                  valid: ->(value) { value.is_a?(String) }, expectation: 'must be a string'),
+      Setting.new(key: 'group', variable: 'SLIPWAY_GROUP', default: 'default',
+                  description: 'Group used when -n is not given.',
+                  valid: ->(value) { Names.valid?(value) },
+                  expectation: "must be a valid group name: #{Names::RULE}"),
+      Setting.new(key: 'networkTimeout', variable: 'SLIPWAY_NETWORK_TIMEOUT', default: 60,
+                  description: "Seconds, from #{NETWORK_TIMEOUT.min} to #{NETWORK_TIMEOUT.max}, a git network " \
+                               'command may run before it is killed with the processes it started.',
+                  valid: ->(value) { value.is_a?(Integer) && NETWORK_TIMEOUT.cover?(value) },
+                  expectation: "must be an integer from #{NETWORK_TIMEOUT.min} to #{NETWORK_TIMEOUT.max}",
+                  parse: INTEGER),
+      Setting.new(key: 'parallel', variable: 'SLIPWAY_PARALLEL', default: 4,
+                  description: "How many git network commands run at once, from #{PARALLEL.min} to #{PARALLEL.max}.",
+                  valid: ->(value) { value.is_a?(Integer) && PARALLEL.cover?(value) },
+                  expectation: "must be an integer from #{PARALLEL.min} to #{PARALLEL.max}", parse: INTEGER),
+      Setting.new(key: 'protocols', variable: 'SLIPWAY_PROTOCOLS', default: %w[ssh https].freeze,
+                  description: 'Transports git may use in network commands, as a list; any other transport is ' \
+                               'refused, and so are ext and fd. Add file for local mirrors.',
+                  valid: lambda { |value|
+                    value.is_a?(Array) && !value.empty? && value.all? { it.is_a?(String) && PROTOCOL.match?(it) }
+                  },
+                  expectation: 'must be a list of lowercase git transport names, such as ssh, https or file',
+                  variable_expectation: 'must be lowercase git transport names separated by colons, such as ssh:https',
+                  parse: LIST,
+                  refusal: lambda { |names|
+                    unsafe = names.find { UNSAFE_PROTOCOLS.key?(it) }
+                    "must not include #{unsafe}, which #{UNSAFE_PROTOCOLS[unsafe]}" if unsafe
+                  }),
+      Setting.new(key: 'theme', variable: 'SLIPWAY_THEME', default: CLI::Theme::DEFAULT_NAME,
+                  description: 'Color theme: dark or light.',
+                  valid: ->(value) { CLI::Theme::NAMES.include?(value) },
+                  expectation: "must be one of #{CLI::Theme::NAMES.join(', ')}")
+    ].freeze
+
+    KEYS = ALL.map(&:key).freeze
+    DOCUMENTATION = ALL.to_h { [it.key, it.documentation] }.freeze
+
+    class Document
+      Contents = Data.define(:values, :exists)
+
+      def self.read(path, explicit:)
+        text = File.read(path)
+      rescue Errno::ENOENT
+        raise Error, "#{path}: no such file" if explicit
+
+        Contents.new(values: {}, exists: false)
+      rescue SystemCallError => e
+        raise Error.from_system_call(e, path)
+      else
+        Contents.new(values: new(path, text).values, exists: true)
+      end
+
+      def initialize(path, text)
+        @path = path
+        @text = text
+      end
+
+      def values
+        document = parse
+        return {} if document.nil?
+        raise Error, "#{@path}: expected a mapping of keys to values" unless document.is_a?(Hash)
+
+        document.to_h { |key, value| [key.to_s, setting(key).check(value, @path)] }
+      end
+
+      private
+
+      def parse
+        Psych.safe_load(@text, filename: @path, symbolize_names: false)
+      rescue Psych::SyntaxError => e
+        raise Error, "#{@path}: #{e.message.delete_prefix("(#{@path}): ")}"
+      rescue Psych::Exception => e
+        raise Error, "#{@path}: #{e.message}"
+      end
+
+      def setting(key)
+        ALL.find { it.key == key } ||
+          raise(Error, "#{@path}: unknown key \"#{key}\" (known keys: #{KEYS.join(', ')})")
+      end
+    end
+
+    def self.load(paths, env:, flags: {})
+      path = paths.config_file
+      contents = Document.read(path, explicit: paths.config_explicit?)
+      resolved = ALL.to_h { |setting| [setting.attribute, resolve(setting, flags, env, contents.values)] }
+      # Each key whose value its environment variable supplied, with that variable's name, so a
+      # message can point at the variable rather than at a file it outranks.
+      variables = ALL.select { from_variable?(it, flags, env) }.to_h { [it.key, it.variable] }.freeze
+      new(path:, exists: contents.exists, variables:, **resolved)
+    end
+
+    def self.resolve(setting, flags, env, file)
+      flag = flags[setting.attribute]
+      return flag unless flag.nil?
+      return setting.from_variable(env[setting.variable]) if from_variable?(setting, flags, env)
+
+      file.fetch(setting.key, setting.default)
+    end
+
+    def self.from_variable?(setting, flags, env) = flags[setting.attribute].nil? && !env[setting.variable].to_s.empty?
+    private_class_method :resolve, :from_variable?
+
+    def exists? = exists
+
+    def to_h = ALL.to_h { [it.key, public_send(it.attribute)] }
+  end
+end

data/lib/slipway/state.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative 'git/runner'
+
+module Slipway
+  # A repository can be dirty and behind at once; the STATUS column shows one word, for the
+  # fact that needs attention first.
+  module State
+    # In precedence order.
+    ROLES = {
+      'Missing' => :status_danger,
+      'NotARepo' => :status_danger,
+      'Unsafe' => :status_danger,
+      'Conflicted' => :status_danger,
+      'Detached' => :status_warning,
+      'Unborn' => :status_warning,
+      'Dirty' => :status_warning,
+      'Gone' => :status_warning,
+      'Diverged' => :status_warning,
+      'Ahead' => :status_warning,
+      'Behind' => :status_warning,
+      'Clean' => :status_success,
+      'Unknown' => :muted
+    }.freeze
+
+    # What each word means, in the same order. The help of get and describe prints these, and the
+    # README table says the same with its code spans marked.
+    MEANINGS = {
+      'Missing' => 'The registered path is relative, or is not a directory on this machine.',
+      'NotARepo' => 'The directory exists but no repository contains it.',
+      'Unsafe' => 'git refused the repository because another user owns it (safe.directory); describe, diff and ' \
+                  'fetch print the git command that trusts it.',
+      'Conflicted' => 'The working tree has unmerged paths.',
+      'Detached' => 'HEAD points at a commit rather than a branch.',
+      'Unborn' => 'The branch has no commits yet.',
+      'Dirty' => 'Staged, modified or untracked files are present.',
+      'Gone' => 'An upstream is configured but its remote-tracking ref is gone, as of the last fetch --prune (or a ' \
+                'fetch with fetch.prune set).',
+      'Diverged' => 'The branch is both ahead of and behind its upstream, as of the last fetch (FETCHED).',
+      'Ahead' => 'Commits not yet pushed to the upstream, as of the last fetch (FETCHED).',
+      'Behind' => 'Commits on the upstream not yet pulled, as of the last fetch (FETCHED).',
+      'Clean' => 'Nothing to do.',
+      'Unknown' => 'git could not answer: it is not installed, it did not finish within ' \
+                   "#{Git::Runner::DEFAULT_TIMEOUT.to_i} seconds, or it failed for a reason slipway does not " \
+                   'classify. Each distinct reason is printed once on stderr per run.'
+    }.freeze
+
+    # A conflict outranks everything, then the states in which a commit could be lost, then
+    # uncommitted work, then the position against upstream.
+    def self.derive(status)
+      return 'Conflicted' if status.conflicted.positive?
+      return 'Detached' if status.detached?
+      return 'Unborn' if status.unborn?
+      return 'Dirty' unless status.clean?
+      return 'Gone' if status.upstream_gone?
+
+      position(status)
+    end
+
+    def self.for_error(error)
+      case error
+      when Git::MissingPath then 'Missing'
+      when Git::NotARepository then 'NotARepo'
+      when Git::UnsafeRepository then 'Unsafe'
+      else 'Unknown'
+      end
+    end
+
+    def self.role(word) = ROLES.fetch(word)
+
+    def self.position(status)
+      ahead = status.ahead.to_i.positive?
+      behind = status.behind.to_i.positive?
+      return 'Diverged' if ahead && behind
+      return 'Ahead' if ahead
+      return 'Behind' if behind
+
+      'Clean'
+    end
+    private_class_method :position
+  end
+end

data/lib/slipway/store.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require_relative 'error'
+require_relative 'names'
+require_relative 'resources'
+require_relative 'manifest'
+
+module Slipway
+  # The registry on disk: one manifest per resource, `groups/NAME.yaml` and
+  # `projects/GROUP/NAME.yaml` under `root`. A write goes to a temporary file renamed over the
+  # target, so a reader sees the old manifest or the new one and never part of one. Nothing is
+  # locked: two processes that write the same resource at once leave the one that renamed last.
+  # A file is trusted only when its kind, name and group match where it was found.
+  class Store
+    class NotFound < Error
+      # kubectl's form for every kind: `projects "hldr" not found`, `groups "work" not found`.
+      def self.of(kind, name) = new("#{kind.plural} #{name.inspect} not found")
+    end
+
+    class Conflict < Error; end
+
+    DEFAULT_GROUP = Resources::DEFAULT_GROUP
+    PROTECTED_GROUP = 'the default group cannot be deleted'
+
+    attr_reader :root
+
+    def initialize(root:, clock: -> { Time.now.utc })
+      @root = root
+      @clock = clock
+    end
+
+    # A file that does not hold a valid manifest raises, or is handed to the block and skipped.
+    def list(kind, group: nil, &on_problem)
+      files = kind.namespaced? ? project_files(group) : group_files
+      resources = files.filter_map { read_or_report(kind, it, &on_problem) }
+      kind.namespaced? ? resources.sort_by { [it.group, it.name] } : resources.sort_by(&:name)
+    end
+
+    # A nil `group` means the default group for projects.
+    def find(kind, name, group: nil)
+      file = path_for(kind, name, group)
+      raise NotFound.of(kind, name) unless File.file?(file)
+
+      read(kind, file)
+    end
+
+    # A nil `group` means the default group for projects.
+    def exist?(kind, name, group: nil) = File.file?(path_for(kind, name, group))
+
+    # Unique because project names repeat across groups; completion wants each once.
+    def names(kind, group: nil) = list(kind, group:).map(&:name).uniq.sort
+
+    def create(resource)
+      kind = Resources.of(resource)
+      target = path_of(kind, resource)
+      ensure_group!(resource.group) if kind.namespaced?
+      raise Conflict, "#{kind.singular} #{resource.name.inspect} already exists" if File.exist?(target)
+
+      stamped = resource.created_at ? resource : resource.with(created_at: @clock.call.getutc.floor)
+      write(target, stamped)
+      stamped
+    end
+
+    def save(resource)
+      kind = Resources.of(resource)
+      target = path_of(kind, resource)
+      ensure_group!(resource.group) if kind.namespaced?
+      write(target, resource)
+      resource
+    end
+
+    # Deleting a group also removes the registrations of its projects.
+    def delete(kind, name, group: nil)
+      file = path_for(kind, name, group)
+      raise Error, PROTECTED_GROUP if !kind.namespaced? && name == DEFAULT_GROUP
+      raise NotFound.of(kind, name) unless File.file?(file)
+
+      File.delete(file)
+      kind.namespaced? ? prune(File.dirname(file)) : FileUtils.rm_rf(File.join(root, 'projects', name))
+    end
+
+    def project_count(group_name) = project_files(group_name).size
+
+    def group_available?(name)
+      Names.validate!(name, what: 'group name')
+      name == DEFAULT_GROUP || File.file?(group_file(name))
+    end
+
+    private
+
+    def ensure_group!(name)
+      raise NotFound.of(Resources::GROUPS, name) unless group_available?(name)
+
+      create(Group.new(name: DEFAULT_GROUP)) if name == DEFAULT_GROUP && !File.file?(group_file(name))
+      name
+    end
+
+    def path_for(kind, name, group)
+      Names.validate!(name, what: "#{kind.singular} name")
+      kind.namespaced? ? project_file(group || DEFAULT_GROUP, name) : group_file(name)
+    end
+
+    def path_of(kind, resource) = path_for(kind, resource.name, kind.namespaced? ? resource.group : nil)
+
+    def project_file(group, name)
+      File.join(root, 'projects', Names.validate!(group, what: 'group name'), "#{name}.yaml")
+    end
+
+    def group_file(name) = File.join(root, 'groups', "#{name}.yaml")
+
+    # A group's project directory exists only while it holds a project. rmdir refuses a
+    # directory that is not empty, which is the check itself; there is no locking to lose.
+    def prune(directory)
+      Dir.rmdir(directory)
+    rescue Errno::ENOTEMPTY, Errno::ENOENT
+      nil
+    end
+
+    # The root is a path the user chose, so it is the glob's base rather than part of the
+    # pattern: a bracket or a star in it must not be read as a wildcard.
+    def group_files = Dir.glob(File.join('groups', '*.yaml'), base: root).map { File.join(root, it) }
+
+    def project_files(group)
+      pattern = group ? Names.validate!(group, what: 'group name') : '*'
+      Dir.glob(File.join('projects', pattern, '*.yaml'), base: root).map { File.join(root, it) }
+    end
+
+    def read_or_report(kind, file)
+      read(kind, file)
+    rescue Error => e
+      raise unless block_given?
+
+      yield e
+      nil
+    end
+
+    # A manifest is only trusted when its kind, name and group agree with where it was found.
+    def read(kind, file)
+      resource = Manifest.parse_yaml(read_text(file), source: file)
+      return resource if resource.is_a?(kind.klass) && path_of(kind, resource) == file
+
+      raise Manifest::Invalid.new(file, "describes #{resource.kind.downcase} #{resource.name.inspect}, " \
+                                        'which does not belong at this path')
+    end
+
+    def read_text(file)
+      File.read(file)
+    rescue SystemCallError => e
+      raise Error.from_system_call(e, file)
+    end
+
+    # A temporary file in the target directory renamed over the target, so a reader never sees a partial file.
+    def write(target, resource)
+      require 'tempfile'
+      FileUtils.mkdir_p(root, mode: 0o700)
+      directory = File.dirname(target)
+      FileUtils.mkdir_p(directory)
+      Tempfile.create([".#{File.basename(target)}.", '.tmp'], directory) do |tmp|
+        tmp.write(Manifest.dump(resource))
+        tmp.fsync
+        # Tempfile creates the file 0600; a manifest gets the mode File.write would give it.
+        tmp.chmod(0o666 & ~File.umask)
+        File.rename(tmp.path, target)
+      end
+    rescue SystemCallError => e
+      raise Error.from_system_call(e, target)
+    end
+  end
+end