slipway 0.1.0

data/lib/slipway/editor.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+require_relative 'error'
+
+module Slipway
+  class Editor
+    class Failed < Slipway::Error; end
+
+    VARIABLE = 'SLIPWAY_EDITOR'
+    FALLBACK_VARIABLES = %w[VISUAL EDITOR].freeze
+    DEFAULT = 'vi'
+    TMPDIR_PREFIX = 'slipway-edit-'
+
+    # `preferred` is the config file's editor.
+    def initialize(env:, preferred: nil)
+      @env = env
+      @preferred = preferred
+    end
+
+    # An argv Array, so `code --wait` and quoted paths work without a shell.
+    def command
+      Shellwords.split(command_line)
+    rescue ArgumentError => e
+      raise Failed, "editor #{command_line.inspect} is not a valid command line: #{e.message}"
+    end
+
+    def edit(text, filename: 'resource.yaml')
+      require 'tmpdir'
+      Dir.mktmpdir(TMPDIR_PREFIX) do |dir|
+        path = File.join(dir, filename)
+        File.write(path, text)
+        run(command, path)
+        read_back(path, filename)
+      end
+    end
+
+    private
+
+    def command_line
+      [@env[VARIABLE], @preferred, *FALLBACK_VARIABLES.map { @env[it] }].find { present?(it) } || DEFAULT
+    end
+
+    def present?(value) = !value.nil? && !value.strip.empty?
+
+    def run(argv, path)
+      started = system(*argv, path)
+      return if started
+
+      program = argv.first.inspect
+      raise Failed, "editor #{program} not found" if started.nil?
+
+      raise Failed, "editor #{program} #{describe(Process.last_status)}"
+    end
+
+    def describe(status)
+      return "exited with status #{status.exitstatus}" if status.exited?
+
+      "was killed by signal #{status.termsig}"
+    end
+
+    # An editor may delete or replace the file instead of saving over it.
+    def read_back(path, filename)
+      File.read(path)
+    rescue Errno::ENOENT
+      raise Failed, "editor removed #{filename}; edit cancelled"
+    rescue SystemCallError => e
+      raise Failed.from_system_call(e, path)
+    end
+  end
+end

data/lib/slipway/error.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Slipway
+  # Base class for every failure reported to the user. The front controller prints each of
+  # `problems` on its own `error:` line.
+  class Error < StandardError
+    # Ruby appends ` @ rb_sysopen - /path` to a SystemCallError; the user needs the path
+    # they typed and the strerror text alone.
+    SYSTEM_SUFFIX = / @ \S+ - .*\z/m
+
+    def self.from_system_call(error, path)
+      new("#{path}: #{error.message.sub(SYSTEM_SUFFIX, '')}")
+    end
+
+    def initialize(message = nil, problems: nil)
+      @problems = problems&.dup&.freeze
+      super(problems ? problems.join("\n") : message)
+    end
+
+    def problems = @problems || [message]
+
+    def exit_status = 1
+
+    # Usage errors point at a help page; every other error prints its message alone.
+    def hint = nil
+  end
+end

data/lib/slipway/fetcher.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative 'git'
+require_relative 'outcome'
+require_relative 'paths'
+
+module Slipway
+  # Fetches one project and reports its Outcome. Several workers call it at once.
+  class Fetcher
+    # With no remote to pick, git fetch exits 0 and prints nothing, which would read as unchanged.
+    NO_REMOTE = 'NoRemote'
+    NO_REMOTE_DETAIL = 'no upstream, no origin and no single remote to fetch from'
+    REF_LIMIT = 5
+    ABBREV = Git::Porcelain::ABBREVIATION
+    ZERO_ID = /\A0+\z/
+    SHORT_REF = %r{\Arefs/(?:remotes|tags|heads)/}
+
+    def initialize(runtime, prune:, dry_run:)
+      @runtime = runtime
+      @prune = prune
+      @dry_run = dry_run
+      @locks = Hash.new { |locks, key| locks[key] = Mutex.new }
+      @guard = Mutex.new
+    end
+
+    # The whole of the fetch verb for one project.
+    def attempt(project)
+      return Outcome.new(project:, word: Outcome::PAUSED) if project.paused
+
+      inspection = @runtime.inspector.examine(project)
+      return Outcome.unreadable(project, inspection) if inspection.error
+
+      fetch(project, inspection)
+    end
+
+    # `inspection` is the project's, read without an error. An error git reports becomes the
+    # outcome; anything else is a bug and leaves through the caller.
+    def fetch(project, inspection)
+      return no_remote(project) if remoteless?(inspection)
+      return rehearse(project) if @dry_run
+
+      fetched(project, exclusively(project) { @runtime.git.fetch(path(project), prune: @prune) })
+    rescue Git::Error => e
+      Outcome.failure(project, e)
+    end
+
+    # Two writes into one ref store race on its ref locks, and one of them fails.
+    def exclusively(project, &)
+      key = @runtime.git.common_dir(path(project))
+      @guard.synchronize { @locks[key] }.synchronize(&)
+    end
+
+    def path(project) = Paths.expand(project.path, home: @runtime.paths.home)
+
+    private
+
+    # A fetch refuses a branch that tracks a local one before it contacts any remote, so a dry
+    # run can tell the same without fetching.
+    def rehearse(project)
+      raise Git::LocalUpstream, path(project) if @runtime.git.local_upstream?(path(project))
+
+      Outcome.new(project:, word: Outcome::FETCHED)
+    end
+
+    # An origin or an upstream settles it without a spawn; git is asked only when neither
+    # exists, since it may still pick a sole remote.
+    def remoteless?(inspection)
+      inspection.remote.nil? && inspection.status.upstream.nil? &&
+        !@runtime.git.default_remote?(path(inspection.project))
+    end
+
+    def no_remote(project)
+      Outcome.new(project:, word: Outcome::SKIPPED, reason: NO_REMOTE, details: [NO_REMOTE_DETAIL])
+    end
+
+    # Git before 2.41 lists no refs, so a fetch that succeeded there reads as fetched.
+    def fetched(project, result)
+      updates = result.updates
+      return Outcome.new(project:, word: Outcome::FETCHED) if updates.nil?
+      return Outcome.new(project:, word: Outcome::UNCHANGED) if updates.empty?
+
+      Outcome.new(project:, word: Outcome::FETCHED, details: refs(updates))
+    end
+
+    def refs(updates)
+      lines = updates.first(REF_LIMIT).map { |ref, old_id, new_id| ref_line(ref.sub(SHORT_REF, ''), old_id, new_id) }
+      lines << "and #{updates.size - REF_LIMIT} more" if updates.size > REF_LIMIT
+      lines
+    end
+
+    # Git writes the all-zero id for the old side of a new ref and the new side of a pruned one.
+    def ref_line(name, old_id, new_id)
+      return "#{name} #{new_id[0, ABBREV]} (new)" if ZERO_ID.match?(old_id)
+      return "#{name} deleted (was #{old_id[0, ABBREV]})" if ZERO_ID.match?(new_id)
+
+      "#{name} #{old_id[0, ABBREV]}..#{new_id[0, ABBREV]}"
+    end
+  end
+end

data/lib/slipway/field_selector.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative 'cli/errors'
+
+module Slipway
+  # A kubectl field selector, matched against the object json and yaml print. `fields` maps
+  # each path a resource supports to the value the path compares as when the object leaves
+  # it out.
+  class FieldSelector
+    Requirement = Data.define(:path, :operator, :value, :absent) do
+      def match?(object)
+        found = object.dig(*path.split('.'))
+        equal = (found.nil? ? absent : found.to_s) == value
+        operator == :equals ? equal : !equal
+      end
+    end
+
+    class Parser
+      # A backslash escapes the character after it, so an escaped comma stays in its term.
+      TERM = /(?:\\.|[^\\,])*\\?/m
+      # As in kubectl, the leftmost operator splits the term, and at one position != and ==
+      # win over =.
+      OPERATOR = /\A(.*?)(!=|==|=)(.*)\z/m
+      OPERATORS = { '=' => :equals, '==' => :equals, '!=' => :not_equals }.freeze
+      ESCAPE = /\\(.?)|=/m
+      # The three characters kubectl escapes in a value; any other escape is refused.
+      ESCAPABLE = ['\\', ',', '='].freeze
+
+      # Under the C locale ARGV arrives as BINARY, and a BINARY value holding non-ASCII bytes
+      # never equals the UTF-8 string git or the manifest gave, so the bytes are read as UTF-8.
+      def initialize(expression, fields)
+        @expression = String.new(expression.to_s, encoding: Encoding::UTF_8)
+        @fields = fields
+      end
+
+      # kubectl skips empty terms, so a trailing comma is not an error.
+      def parse
+        fail!('invalid UTF-8') unless @expression.valid_encoding?
+
+        @expression.strip.scan(TERM).reject(&:empty?).map { requirement(it) }
+      end
+
+      private
+
+      def requirement(term)
+        match = OPERATOR.match(term)
+        fail!("can't understand #{term.inspect}") if match.nil?
+        path, operator, value = match.captures
+        fail!("field label not supported: #{path.inspect}") unless @fields.key?(path)
+
+        Requirement.new(path:, operator: OPERATORS.fetch(operator), value: unescape(value), absent: @fields.fetch(path))
+      end
+
+      def unescape(value)
+        value.gsub(ESCAPE) do |found|
+          escaped = Regexp.last_match(1)
+          next escaped if ESCAPABLE.include?(escaped)
+
+          fail!(escaped.nil? ? "unescaped character in value: #{found}" : "invalid escape sequence: #{found}")
+        end
+      end
+
+      def fail!(reason)
+        raise CLI::UsageError, "invalid field selector #{@expression.inspect}: #{reason}"
+      end
+    end
+
+    # nil or a blank string selects everything.
+    def self.parse(expression, fields:) = new(Parser.new(expression, fields).parse)
+
+    def initialize(requirements)
+      @requirements = requirements.freeze
+    end
+
+    def empty? = @requirements.empty?
+
+    def match?(object) = @requirements.all? { it.match?(object) }
+
+    # The block turns an item into the object its fields are read from.
+    def filter(items)
+      return items if empty?
+
+      items.select { match?(yield(it)) }
+    end
+  end
+end

data/lib/slipway/git/branch_name.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative '../error'
+
+module Slipway
+  module Git
+    # A subset of what `git check-ref-format --branch` accepts, closed so that a name can never
+    # read as an option or carry a control character.
+    module BranchName
+      # Callers decide whether the name came from the command line or a file.
+      class Invalid < Slipway::Error; end
+
+      PATTERN = %r{\A[A-Za-z0-9][A-Za-z0-9._/-]*\z}
+      FORBIDDEN = %r{\.\.|//|/\.|\.lock(?:/|\z)|[/.]\z}
+      MAX = 255
+      RULE = 'letters, digits, ".", "_", "/" and "-", starting with a letter or digit, at most 255 characters, ' \
+             'with no "..", no "//", no component that starts with "." or ends with ".lock", no trailing "/" ' \
+             'or ".", and not HEAD'
+
+      def self.valid?(name)
+        name.is_a?(String) && name.valid_encoding? && name.size <= MAX && name != 'HEAD' &&
+          PATTERN.match?(name) && !FORBIDDEN.match?(name)
+      end
+
+      def self.validate!(name)
+        return name if valid?(name)
+
+        raise Invalid, "#{name.scrub.inspect} is not a valid branch name: #{RULE}"
+      end
+    end
+  end
+end

data/lib/slipway/git/commit.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Slipway
+  module Git
+    Commit = Data.define(:sha, :short, :time, :author, :email, :subject) do
+      # One record in the field order of Repository::LOG_ARGS.
+      def self.parse(text)
+        sha, short, epoch, author, email, subject = text.chomp("\0").split("\0", 6)
+        new(sha:, short:, time: Time.at(Integer(epoch)).utc, author:, email:, subject: subject.to_s)
+      end
+    end
+  end
+end

data/lib/slipway/git/distance.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Slipway
+  module Git
+    # Where HEAD stands against another commit: `ahead` counts the commits only HEAD reaches,
+    # `behind` the ones only the other commit reaches, and `off_upstream` the ones the other commit
+    # reaches and @{upstream} does not. That last count is taken only when HEAD is behind the other
+    # commit on a branch whose upstream exists, and is nil otherwise.
+    Distance = Data.define(:ahead, :behind, :off_upstream) do
+      def initialize(ahead:, behind:, off_upstream: nil) = super
+    end
+  end
+end

data/lib/slipway/git/errors.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+require_relative '../error'
+
+module Slipway
+  module Git
+    class Error < Slipway::Error
+      attr_reader :path
+
+      def initialize(path, detail = 'git command failed')
+        @path = path
+        super("#{path}: #{detail}")
+      end
+    end
+
+    class NotInstalled < Error
+      def initialize(path, binary: Runner::DEFAULT_BINARY)
+        super(path, "git executable #{binary.inspect} not found on PATH")
+      end
+    end
+
+    class Timeout < Error
+      DETAIL = 'git did not finish within %<seconds>g %<unit>s'
+
+      def initialize(path, seconds: Runner::DEFAULT_TIMEOUT)
+        unit = seconds == 1 ? 'second' : 'seconds'
+        super(path, format(self.class::DETAIL, seconds:, unit:))
+      end
+    end
+
+    # Git stopped partway through writing the working tree leaves the branch and the index where
+    # they were, but keeps the files it had written, and they then show as changes.
+    class WriteTimeout < Timeout
+      DETAIL = "#{Timeout::DETAIL}; the files it had written stay in the working tree".freeze
+
+      def hint = "Run 'git -C #{Shellwords.escape(path)} status' to see them."
+    end
+
+    class MissingPath < Error
+      def initialize(path, detail = 'no such directory') = super
+    end
+
+    # A manifest has no directory to resolve a relative path against.
+    class RelativePath < MissingPath
+      def initialize(path) = super(path, 'relative path; register an absolute path or one starting with ~/')
+    end
+
+    class NotARepository < Error
+      def initialize(path) = super(path, 'not a git repository')
+    end
+
+    # Git refuses a repository another user owns unless safe.directory lists it.
+    class UnsafeRepository < Error
+      def initialize(path) = super(path, 'repository has dubious ownership')
+
+      # Git's own remedy, so the user can decide whether to trust the directory.
+      def command = "git config --global --add safe.directory #{Shellwords.escape(path)}"
+
+      def hint = "Run '#{command}' to trust it."
+    end
+
+    # Credentials, a passphrase or a host key confirmation were missing or refused, and network
+    # commands never prompt for them.
+    class AuthRequired < Error
+      def initialize(path, detail = 'authentication required and prompts are disabled') = super
+
+      def hint = "Run 'git -C #{Shellwords.escape(path)} fetch' once in a terminal to see what git needs."
+    end
+
+    class LocalUpstream < Error
+      def initialize(path) = super(path, 'the current branch tracks a local branch, not a remote one')
+    end
+
+    # The branch was left where it was. `reason` names why in one word: a state in which a
+    # fast-forward is never attempted or, for the subclasses, git's own refusal.
+    class Blocked < Error
+      attr_reader :reason
+
+      def initialize(path, reason, detail)
+        @reason = reason
+        super(path, detail)
+      end
+    end
+
+    # Git cannot tell a running process from one that died holding the lock, and neither can
+    # slipway, so the lock stays.
+    class Busy < Blocked
+      def initialize(path, lock = 'index.lock')
+        super(path, 'Busy', "another git process holds #{lock}, or one left it behind")
+      end
+    end
+
+    class WouldOverwrite < Blocked
+      def initialize(path) = super(path, 'WouldOverwrite', 'the incoming commits would overwrite untracked files')
+    end
+
+    class WouldLoseChanges < Blocked
+      def initialize(path) = super(path, 'WouldLoseChanges', 'the incoming commits would overwrite local changes')
+    end
+
+    class NotFastForward < Blocked
+      def initialize(path) = super(path, 'NotFastForward', 'the branch cannot be fast-forwarded')
+    end
+
+    # Git refuses a transport that GIT_ALLOW_PROTOCOL, built from the "protocols" setting, does not list.
+    class ProtocolNotAllowed < Error
+      # The transports the "protocols" setting refuses to list, so no hint suggests adding one.
+      UNSAFE = %w[ext fd].freeze
+
+      attr_reader :protocol
+
+      # `source` says where the transports are listed, worded for the hint.
+      def initialize(path, protocol:, source:)
+        @protocol = protocol
+        @source = source
+        super(path, "transport '#{protocol}' not allowed")
+      end
+
+      def hint
+        "Add #{protocol} to #{@source} to allow it." unless UNSAFE.include?(protocol)
+      end
+    end
+  end
+end

data/lib/slipway/git/fake.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require_relative 'fetch_result'
+require_relative 'fast_forward'
+require_relative 'move_back'
+
+module Slipway
+  module Git
+    # `calls` lists every question asked and every move made, as [name, path] or
+    # [name, path, options], so a test can tell which repositories a command reached and what it
+    # changed.
+    class Fake
+      Entry = Data.define(:status, :commit, :remote, :remotes, :operation, :fetch, :fetched_at, :fast_forward,
+                          :distance, :reflog, :between, :roll_back)
+
+      NOTHING_FETCHED = FetchResult.new(updates: [].freeze)
+
+      def initialize
+        @entries = {}
+        @failures = {}
+        @calls = []
+        @lock = Mutex.new
+      end
+
+      # `fetch` is the FetchResult a fetch returns, and `fast_forward` the FastForward the next
+      # move returns (nil moves nothing and names `commit`); either may instead be an error, raised
+      # the way fail raises it. `remotes` names the configured remotes, origin alone when `remote`
+      # is its URL. `operation` is what in_progress answers, and `distance` what distance answers
+      # for any revision (nil: no such commit). `reflog` is what reflog answers for any branch,
+      # `between` what commits_between answers for any two commits, and `roll_back` the MoveBack
+      # the next roll back returns, or the error it raises.
+      def add(path, status:, commit: nil, remote: nil, remotes: nil, operation: nil, fetch: NOTHING_FETCHED,
+              fetched_at: nil, fast_forward: nil, distance: nil, reflog: [], between: nil, roll_back: nil)
+        key = File.expand_path(path)
+        @failures.delete(key)
+        remotes ||= remote ? ['origin'] : []
+        @entries[key] = Entry.new(status:, commit:, remote:, remotes:, operation:, fetch:, fetched_at:, fast_forward:,
+                                  distance:, reflog:, between:, roll_back:)
+        self
+      end
+
+      # `error` is an exception instance or a Git error class that takes the path as its only
+      # argument.
+      def fail(path, error)
+        key = File.expand_path(path)
+        @entries.delete(key)
+        @failures[key] = error
+        self
+      end
+
+      def calls = @lock.synchronize { @calls.dup }
+
+      def status(path) = entry(:status, path).status
+
+      def last_commit(path) = entry(:last_commit, path).commit
+
+      def remote_url(path) = entry(:remote_url, path).remote
+
+      def in_progress(path) = entry(:in_progress, path).operation
+
+      def distance(path, revision, tracking: false) = entry(:distance, path, revision:, tracking:).distance
+
+      def reflog(path, branch) = entry(:reflog, path, branch:).reflog
+
+      def commits_between(path, from, to) = entry(:commits_between, path, from:, to:).between
+
+      def fetch(path, prune:)
+        outcome = entry(:fetch, path, prune:).fetch
+        raise failure(File.expand_path(path), outcome) unless outcome.is_a?(FetchResult)
+
+        outcome
+      end
+
+      # Read from the canned fetch, since the real fetch raises LocalUpstream exactly when this holds.
+      def local_upstream?(path)
+        key = File.expand_path(path)
+        failure(key, entry(:local_upstream?, key).fetch).is_a?(LocalUpstream)
+      end
+
+      # Git takes the branch's remote, which an upstream implies, else the only remote, else origin.
+      def default_remote?(path)
+        answer = entry(:default_remote?, path)
+        [answer.status.upstream, answer.remote].any? || answer.remotes.size == 1
+      end
+
+      def fetched_at(path) = entry(:fetched_at, path).fetched_at
+
+      # Each path is a repository of its own.
+      def common_dir(path) = File.expand_path(path)
+
+      # A move happens once, as on a real branch: the status and the last commit then show the new
+      # head, that many commits fewer behind, and the next fast-forward moves nothing.
+      def fast_forward(path, onto: Repository::UPSTREAM, reflog_action: Repository::REFLOG_ACTION)
+        move(:fast_forward, path, FastForward, 1, onto:, reflog_action:)
+      end
+
+      # A move back happens once too, and leaves the branch that many commits further behind.
+      def roll_back(path, to:, reflog_action: Repository::ROLLBACK_ACTION)
+        move(:roll_back, path, MoveBack, -1, to:, reflog_action:)
+      end
+
+      private
+
+      def entry(name, path, **) = @lock.synchronize { lookup(name, File.expand_path(path), **) }
+
+      # A path nobody registered is a path that does not exist, as for the real Repository.
+      # Called with the lock held.
+      def lookup(name, key, **options)
+        @calls << (options.empty? ? [name, key] : [name, key, options])
+        raise failure(key, @failures[key]) if @failures.key?(key)
+
+        @entries.fetch(key) { raise MissingPath, key }
+      end
+
+      def move(name, path, type, direction, **)
+        key = File.expand_path(path)
+        @lock.synchronize do
+          current = lookup(name, key, **)
+          move = current.public_send(name) || still(key, current, type)
+          raise failure(key, move) unless move.is_a?(type)
+
+          @entries[key] = moved(current, move, direction * move.count).with(name => nil) if move.moved?
+          move
+        end
+      end
+
+      # A real move names HEAD in full, as only the last commit does.
+      def still(key, entry, type)
+        head = entry.commit&.sha
+        raise ArgumentError, "#{key}: a move that goes nowhere names the last commit; add one" unless head
+
+        type.new(from: head, to: head, count: 0)
+      end
+
+      def moved(entry, move, gained)
+        status = entry.status
+        behind = [status.behind.to_i - gained, 0].max
+        short = move.to[0, Porcelain::ABBREVIATION]
+        entry.with(status: status.with(head: short, behind:), commit: entry.commit&.with(sha: move.to, short:))
+      end
+
+      def failure(key, error)
+        error.is_a?(Class) ? error.new(key) : error
+      end
+    end
+  end
+end

data/lib/slipway/git/fast_forward.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Slipway
+  module Git
+    # `from` and `to` are the full object names the branch pointed at before and after the move,
+    # and `count` the commits it gained: 0, with `to` equal to `from`, when the branch already
+    # held the target.
+    FastForward = Data.define(:from, :to, :count) do
+      def moved? = to != from
+    end
+  end
+end