slipway 0.1.0

data/lib/slipway/manifest.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+require 'psych'
+require 'time'
+require_relative 'error'
+require_relative 'git/branch_name'
+require_relative 'git/url'
+require_relative 'names'
+require_relative 'labels'
+require_relative 'resources'
+require_relative 'schema'
+require_relative 'yaml'
+
+module Slipway
+  module Manifest
+    class Invalid < Error
+      attr_reader :source, :problem
+
+      def initialize(source, problem)
+        @source = source
+        @problem = problem
+        super("#{source}: #{problem}")
+      end
+    end
+
+    # Turns one parsed document into a Project or a Group, or raises Invalid with the source and
+    # the first field that breaks its rule. Which fields exist, which are required, their defaults
+    # and the words of each refusal come from Schema, so a field Schema does not name is refused.
+    # Every field that can reach git or a command slipway prints is checked here, so a resource
+    # read from the store or applied from a file can be handed to Git::Repository as it is.
+    class Reader
+      TIMESTAMP = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})\z/
+      # SHA-1 or SHA-256; an abbreviation can become ambiguous as the repository grows.
+      REVISION = /\A(?:[0-9a-f]{40}|[0-9a-f]{64})\z/
+
+      def initialize(document, source, default_group)
+        @document = document
+        @source = source
+        @default_group = default_group
+      end
+
+      def resource
+        invalid('document is not a mapping') unless @document.is_a?(Hash)
+        @schema = Schema::KINDS.fetch(kind)
+        reject_unknown(@document, @schema, nil)
+        @metadata = mapping('metadata')
+        @spec = mapping('spec')
+        kind == 'Project' ? project : group
+      end
+
+      private
+
+      def kind
+        case @document['kind']
+        in String => kind if Schema::KINDS.key?(kind) then kind
+        in nil then required('kind')
+        in String => other then invalid("\"kind\" must be #{Schema::KINDS.keys.join(' or ')}, not #{other.inspect}")
+        else mistyped('kind', Schema::STRING)
+        end
+      end
+
+      def project
+        Project.new(name:, group: group_name, labels:, created_at:, path:, description:, remote:, branch:, revision:,
+                    sync_policy:, paused:)
+      end
+
+      def group = Group.new(name:, labels:, created_at:, description:)
+
+      def name
+        checked { Names.validate!(string(@metadata, 'metadata', 'name'), what: "#{kind.downcase} name") }
+      end
+
+      def group_name
+        checked { Names.validate!(string(@metadata, 'metadata', 'group') || @default_group, what: 'group name') }
+      end
+
+      # An empty path would be resolved against whatever directory the reader happens to be in.
+      def path
+        value = string(@spec, 'spec', 'path')
+        broken('spec', 'path') if value.strip.empty?
+        value
+      end
+
+      def description = string(@spec, 'spec', 'description')
+
+      def remote
+        url = string(@spec, 'spec', 'remote')
+        url && checked { Git::Url.validate!(url, field: '"spec.remote"') }
+      end
+
+      def branch
+        name = string(@spec, 'spec', 'branch')
+        name && checked { Git::BranchName.validate!(name) }
+      end
+
+      def revision
+        case @spec['revision']
+        in nil then nil
+        in String => sha if REVISION.match?(sha) then sha
+        else broken('spec', 'revision')
+        end
+      end
+
+      def sync_policy
+        field = @schema.dig('spec', 'syncPolicy')
+        case @spec['syncPolicy']
+        in nil then field.default
+        in String => policy if field.enum.include?(policy) then policy
+        in String => other then invalid("\"spec.syncPolicy\" #{field.rule}, not #{other.inspect}")
+        else mistyped('spec.syncPolicy', Schema::STRING)
+        end
+      end
+
+      def paused
+        case @spec['paused']
+        in nil then @schema.dig('spec', 'paused').default
+        in true | false => paused then paused
+        else mistyped('spec.paused', Schema::BOOLEAN)
+        end
+      end
+
+      def labels
+        case @metadata['labels']
+        in nil then {}
+        in Hash => labels then checked { Labels.validate!(string_pairs(labels)) }
+        else mistyped('metadata.labels', Schema::LABEL_MAP)
+        end
+      end
+
+      def string_pairs(labels)
+        labels.each do |key, value|
+          invalid('"metadata.labels" keys must be strings') unless key.is_a?(String)
+          mistyped("metadata.labels.#{key}", Schema::STRING) unless value.is_a?(String)
+        end
+      end
+
+      def created_at
+        case @metadata['creationTimestamp']
+        in nil then nil
+        in String => text if TIMESTAMP.match?(text) then time(text)
+        else broken('metadata', 'creationTimestamp')
+        end
+      end
+
+      # Second precision, so the value read back equals the value written.
+      def time(text)
+        Time.iso8601(text).getutc.floor
+      rescue ArgumentError
+        broken('metadata', 'creationTimestamp')
+      end
+
+      def mapping(key)
+        case @document[key]
+        in nil then {}
+        in Hash => section then reject_unknown(section, @schema.field(key), key)
+        else mistyped(key, Schema::OBJECT)
+        end
+      end
+
+      def reject_unknown(section, schema, prefix)
+        section.each_key do |key|
+          next if schema.field(key)
+
+          invalid("unknown field #{[prefix, key].compact.join('.').inspect}")
+        end
+      end
+
+      def string(section, prefix, key)
+        case section[key]
+        in String => value then value
+        in nil if @schema.dig(prefix, key).required then required("#{prefix}.#{key}")
+        in nil then nil
+        else mistyped("#{prefix}.#{key}", Schema::STRING)
+        end
+      end
+
+      def checked
+        yield
+      rescue Names::Invalid, Labels::Invalid, Git::Url::Invalid, Git::BranchName::Invalid => e
+        invalid(e.message)
+      end
+
+      def required(path) = invalid("\"#{path}\" is required")
+
+      def mistyped(path, type) = invalid("\"#{path}\" must be #{Schema::NOUNS.fetch(type)}")
+
+      # For the fields whose rule this class checks itself rather than a module such as Names.
+      def broken(prefix, key) = invalid("\"#{prefix}.#{key}\" #{@schema.dig(prefix, key).rule}")
+
+      def invalid(problem)
+        raise Invalid.new(@source, problem)
+      end
+    end
+
+    private_constant :Reader
+
+    LIST_KIND = 'List'
+    LIST_FIELDS = %w[kind items].freeze
+
+    # `hash` must have string keys.
+    def self.parse(hash, source:, default_group: 'default') = Reader.new(hash, source, default_group).resource
+
+    def self.load_documents(text, source:)
+      documents(text, source).each_with_index.filter_map do |document, index|
+        case document
+        in nil then nil
+        in Hash then document
+        else raise Invalid.new(source, "document #{index + 1} is not a mapping")
+        end
+      end
+    rescue Psych::SyntaxError => e
+      raise Invalid.new(source, "#{e.problem} at line #{e.line}, column #{e.column}")
+    rescue Psych::DisallowedClass => e
+      raise Invalid.new(source, disallowed(e))
+    rescue Psych::BadAlias => e
+      raise Invalid.new(source, e.message)
+    end
+
+    # kubectl prints several objects as one List and applies such a List back item by item, so
+    # each item stands for a document of its own.
+    def self.load_objects(text, source:)
+      load_documents(text, source:).flat_map { it['kind'] == LIST_KIND ? list_items(it, source) : [it] }
+    end
+
+    def self.list_items(list, source)
+      unknown = list.keys - LIST_FIELDS
+      raise Invalid.new(source, "unknown field #{unknown.first.inspect} in a List") unless unknown.empty?
+
+      case list['items']
+      in nil then []
+      in Array => items if items.all?(Hash) then items
+      else raise Invalid.new(source, '"items" of a List must be a sequence of mappings')
+      end
+    end
+    private_class_method :list_items
+
+    def self.parse_yaml(text, source:, default_group: 'default')
+      case load_documents(text, source:)
+      in [document] then parse(document, source:, default_group:)
+      in [] then raise Invalid.new(source, 'expected one document, found none')
+      in documents then raise Invalid.new(source, "expected one document, found #{documents.size}")
+      end
+    end
+
+    # Psych.safe_load_stream only exists from psych 5.3 and the gem supports Ruby 3.4, so the
+    # stream is parsed first and every document re-emitted alone for Psych.safe_load.
+    def self.documents(text, source)
+      Psych.parse_stream(text, filename: source).children.map do |document|
+        stream = Psych::Nodes::Stream.new
+        stream.children << document
+        Psych.safe_load(stream.to_yaml, filename: source)
+      end
+    end
+    private_class_method :documents
+
+    # YAML types an unquoted 2026-09-29T00:12:33Z as a Time, which the safe loader refuses.
+    def self.disallowed(error)
+      klass = error.message.delete_prefix('Tried to load unspecified class: ')
+      "#{klass} values are not accepted; timestamps, dates and symbols must be quoted strings"
+    end
+    private_class_method :disallowed
+
+    def self.dump(resource) = Yaml.dump(resource.to_manifest)
+  end
+end

data/lib/slipway/names.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative 'error'
+
+module Slipway
+  # The RFC 1123 label rule kubectl applies to object names.
+  module Names
+    # Callers decide whether the name came from the command line or a file.
+    class Invalid < Error; end
+
+    PATTERN = /\A[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\z/
+    RULE = 'lowercase letters, digits and dashes, starting and ending with a letter or digit, at most 63 characters'
+
+    def self.valid?(name) = name.is_a?(String) && PATTERN.match?(name)
+
+    def self.validate!(name, what: 'name')
+      return name if valid?(name)
+
+      raise Invalid, "#{name.inspect} is not a valid #{what}: #{RULE}"
+    end
+  end
+end

data/lib/slipway/outcome.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative 'git'
+require_relative 'state'
+
+module Slipway
+  # One project's result line in a verb that acts on each selected repository: `word` starts it,
+  # `reason` follows in parentheses and `details` are printed under it as they are; the printer
+  # redacts them and makes them plain.
+  Outcome = Data.define(:project, :word, :reason, :details)
+
+  class Outcome
+    # The words more than one verb prints. A word only one verb prints stays with that verb.
+    FETCHED = 'fetched'
+    UNCHANGED = 'unchanged'
+    SKIPPED = 'skipped'
+    PAUSED = 'paused'
+    DENIED = 'denied'
+    FAILED = 'failed'
+    ERROR_WORDS = { Git::AuthRequired => DENIED, Git::LocalUpstream => SKIPPED }.freeze
+    REASONS = { Git::AuthRequired => 'AuthRequired', Git::LocalUpstream => 'LocalUpstream',
+                Git::Timeout => 'Timeout', Git::WriteTimeout => 'Timeout',
+                Git::ProtocolNotAllowed => 'ProtocolNotAllowed' }.freeze
+
+    def initialize(project:, word:, reason: nil, details: []) = super
+
+    # The line above already names the project, so the path is cut from the message.
+    def self.failure(project, error)
+      reason = REASONS.fetch(error.class) { State.for_error(error) }
+      new(project:, word: ERROR_WORDS.fetch(error.class, FAILED), reason:,
+          details: [detail(error), error.hint].compact)
+    end
+
+    # Nothing else in the result says which directory could not be read, so it leads the detail,
+    # as the manifest writes it.
+    def self.unreadable(project, inspection)
+      error = inspection.error
+      new(project:, word: SKIPPED, reason: inspection.state,
+          details: ["#{project.path}: #{detail(error)}", error.hint].compact)
+    end
+
+    def self.detail(error) = error.message.delete_prefix("#{error.path}: ")
+    private_class_method :detail
+  end
+end

data/lib/slipway/output/age.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Slipway
+  module Output
+    # Formats an elapsed time the way kubectl's AGE column does: two units at most, the
+    # precision dropping as the duration grows, and integer truncation at every step.
+    module Age
+      INVALID = '<invalid>'
+      MINUTE = 60
+      HOUR = 60
+      DAY = 24
+      YEAR = 365
+
+      def self.humanize(from, to)
+        return nil if from.nil?
+
+        format(to - from)
+      end
+
+      # Two or more seconds in the future is invalid; a little clock skew rounds to zero.
+      def self.format(seconds)
+        seconds = seconds.to_i
+        return INVALID if seconds < -1
+        return '0s' if seconds.negative?
+        return "#{seconds}s" if seconds < 2 * MINUTE
+
+        from_minutes(seconds)
+      end
+
+      def self.from_minutes(seconds)
+        minutes = seconds / MINUTE
+        return pair(minutes, 'm', seconds % MINUTE, 's') if minutes < 10
+        return "#{minutes}m" if minutes < 3 * HOUR
+
+        from_hours(minutes)
+      end
+
+      def self.from_hours(minutes)
+        hours = minutes / HOUR
+        return pair(hours, 'h', minutes % HOUR, 'm') if hours < 8
+        return "#{hours}h" if hours < 2 * DAY
+
+        from_days(hours)
+      end
+
+      def self.from_days(hours)
+        days = hours / DAY
+        return pair(days, 'd', hours % DAY, 'h') if days < 8
+        return "#{days}d" if days < 2 * YEAR
+
+        from_years(days)
+      end
+
+      def self.from_years(days)
+        years = days / YEAR
+        return pair(years, 'y', days % YEAR, 'd') if years < 8
+
+        "#{years}y"
+      end
+
+      def self.pair(major, major_unit, minor, minor_unit)
+        return "#{major}#{major_unit}" if minor.zero?
+
+        "#{major}#{major_unit}#{minor}#{minor_unit}"
+      end
+
+      private_class_method :from_minutes, :from_hours, :from_days, :from_years, :pair
+    end
+  end
+end

data/lib/slipway/output/describe.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Slipway
+  module Output
+    # A value whose color the caller has already chosen, such as a STATUS word.
+    Painted = Data.define(:role, :text)
+
+    class Describe
+      NONE = '<none>'
+      INDENT = '  '
+      GAP = 2
+      TIME_FORMAT = '%Y-%m-%dT%H:%M:%SZ'
+
+      def initialize(context)
+        @context = context
+      end
+
+      # A value that is a non-empty list of [key, value] pairs renders as a nested block; any
+      # other list prints one item per line.
+      def render(entries)
+        return '' if entries.empty?
+
+        "#{block(entries, 0).join("\n")}\n"
+      end
+
+      def print(entries) = @context.print(render(entries))
+
+      private
+
+      def block(entries, depth)
+        width = entries.map { |key, _| key.to_s.size + 1 }.max + GAP
+        entries.flat_map { |key, value| entry(key.to_s, value, depth, width) }
+      end
+
+      def entry(key, value, depth, width)
+        indent = INDENT * depth
+        label = "#{indent}#{@context.style.paint_cycle(:describe_keys, depth, key)}:"
+        return [label, *block(value, depth + 1)] if section?(value)
+
+        first, *rest = values(value)
+        column = ' ' * (indent.size + width)
+        [label + (' ' * (width - key.size - 1)) + first, *rest.map { column + it }]
+      end
+
+      def section?(value)
+        value.is_a?(Array) && !value.empty? && value.all? { it.is_a?(Array) && it.size == 2 }
+      end
+
+      # Never empty: #entry puts the first line beside the key.
+      def values(value)
+        case value
+        when nil, [], {} then [@context.paint(:none, NONE)]
+        when Hash then value.sort.map { |key, item| Output.plain("#{key}=#{item}") }
+        when Array then value.map { Output.plain(it) }
+        else [scalar(value)]
+        end
+      end
+
+      def scalar(value)
+        case value
+        when Painted then @context.paint(value.role, Output.plain(value.text))
+        when Numeric then @context.paint(:number, value)
+        when true then @context.paint(:boolean_true, value)
+        when false then @context.paint(:boolean_false, value)
+        when Time then value.utc.strftime(TIME_FORMAT)
+        else Output.plain(value)
+        end
+      end
+    end
+  end
+end

data/lib/slipway/output/explain.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Slipway
+  module Output
+    # The plaintext layout of kubectl explain: the KIND line, the FIELD line when a field was named,
+    # its DESCRIPTION wrapped at 80 columns and the FIELDS under it, each with its description or,
+    # with `recursive`, as a tree of names and types. The types line up in one column, where
+    # kubectl puts a tab. Colors follow kubecolor: the labels, the field names and the -required-
+    # mark.
+    class Explain
+      # `description` is the text to print whole; `fields` are the fields under this one.
+      Field = Data.define(:name, :type, :required, :description, :fields)
+
+      WIDTH = 80
+      INDENT = '  '
+      GAP = 3
+      REQUIRED = '-required-'
+
+      def initialize(context)
+        @context = context
+      end
+
+      # `named` prints the FIELD line, for a field below the resource type itself.
+      def render(kind:, field:, named: false, recursive: false)
+        sections = ["#{label('KIND')} #{kind}"]
+        sections << "#{label('FIELD')} #{field.name} #{type(field)}" if named
+        sections << "#{label('DESCRIPTION')}\n#{paragraph(field.description, INDENT * 2)}"
+        sections << fields(field, recursive) unless field.fields.empty?
+        "#{sections.join("\n\n")}\n"
+      end
+
+      def print(**) = @context.print(render(**))
+
+      private
+
+      def label(word) = "#{@context.style.paint_cycle(:describe_keys, 0, word)}:"
+
+      def type(field)
+        mark = " #{@context.paint(:explain_required, REQUIRED)}" if field.required
+        "<#{field.type}>#{mark}"
+      end
+
+      # Each row is [depth, field], with depth 1 for the fields right under the one explained.
+      def fields(field, recursive)
+        rows = recursive ? tree(field.fields, 1) : field.fields.map { [1, it] }
+        width = rows.map { |depth, child| (INDENT * depth).size + child.name.size }.max + GAP
+        entries = rows.map { |depth, child| entry(child, depth, width, recursive) }
+        "#{label('FIELDS')}\n#{entries.join(recursive ? "\n" : "\n\n")}"
+      end
+
+      def tree(fields, depth) = fields.flat_map { [[depth, it], *tree(it.fields, depth + 1)] }
+
+      # A recursive listing cycles the name colors by depth, as kubecolor does.
+      def entry(field, depth, width, recursive)
+        indent = INDENT * depth
+        name = @context.style.paint_cycle(:describe_keys, recursive ? depth - 1 : 0, field.name)
+        line = "#{indent}#{name}#{' ' * (width - indent.size - field.name.size)}#{type(field)}"
+        recursive ? line : "#{line}\n#{paragraph(field.description, indent + INDENT)}"
+      end
+
+      def paragraph(text, indent) = wrap(text, WIDTH - indent.size).map { "#{indent}#{it}" }.join("\n")
+
+      # A word longer than the width gets a line of its own rather than being cut.
+      def wrap(text, width)
+        text.split.each_with_object([]) do |word, lines|
+          if lines.empty? || lines.last.size + word.size >= width
+            lines << word
+          else
+            lines[-1] = "#{lines.last} #{word}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/slipway/output/serializer.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative '../yaml'
+
+module Slipway
+  module Output
+    # Callers pass Hashes with string keys and strings for timestamps, because the YAML dump
+    # admits only the core scalar types.
+    module Serializer
+      STRUCTURED = %w[json yaml].freeze
+      LIST_KIND = 'List'
+
+      def self.render(format, items, single:)
+        document = single ? items.first : { 'kind' => LIST_KIND, 'items' => items }
+        case format
+        when 'json' then json(document)
+        when 'yaml' then Yaml.dump(document)
+        else raise ArgumentError, unknown_format(format)
+        end
+      end
+
+      # Required lazily: most runs print a table and never need json.
+      def self.json(document)
+        require 'json'
+        "#{JSON.pretty_generate(document)}\n"
+      end
+
+      def self.unknown_format(format)
+        "unknown structured format #{format.inspect} (known formats: #{STRUCTURED.join(', ')})"
+      end
+
+      private_class_method :json, :unknown_format
+    end
+  end
+end

data/lib/slipway/output/table.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Slipway
+  module Output
+    # Widths come from the plain text, so color never shifts a column.
+    class Table
+      NONE = '<none>'
+      GAP = '   '
+
+      # `roles` is called with the header and the plain cell text and may return a theme role
+      # that replaces the column color. `color_offset` leading columns stay out of the color cycle.
+      def initialize(context, headers:, show_headers: true, roles: nil, color_offset: 0)
+        @context = context
+        @headers = headers
+        @show_headers = show_headers
+        @roles = roles
+        @color_offset = color_offset
+      end
+
+      def render(rows)
+        cells = rows.map { |row| @headers.each_index.map { text(row[it]) } }
+        widths = column_widths(cells)
+        lines = cells.map { row_line(it, widths) }
+        lines.unshift(header_line(widths)) if @show_headers
+        lines.map { "#{it}\n" }.join
+      end
+
+      def print(rows) = @context.print(render(rows))
+
+      private
+
+      def text(value)
+        value = Output.plain(value)
+        value.empty? ? NONE : value
+      end
+
+      def column_widths(cells)
+        @headers.each_index.map do |index|
+          sizes = cells.map { it[index].size }
+          sizes << @headers[index].to_s.size if @show_headers
+          sizes.max
+        end
+      end
+
+      def header_line(widths)
+        titles = @headers.each_with_index.map { |header, index| header.to_s.upcase.ljust(widths[index]) }
+        @context.paint(:table_header, titles.join(GAP).rstrip)
+      end
+
+      def row_line(cells, widths)
+        painted = cells.each_with_index.map do |cell, index|
+          paint_cell(cell, index) + (' ' * (widths[index] - cell.size))
+        end
+        painted.join(GAP).rstrip
+      end
+
+      def paint_cell(cell, index)
+        return @context.paint(:none, cell) if cell == NONE
+
+        role = @roles&.call(@headers[index], cell)
+        return @context.paint(role, cell) if role
+
+        @context.style.paint_cycle(:table_columns, index - @color_offset, cell)
+      end
+    end
+  end
+end

data/lib/slipway/output.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'cli/style'
+require_relative 'output/age'
+require_relative 'output/table'
+require_relative 'output/describe'
+require_relative 'output/explain'
+require_relative 'output/serializer'
+
+module Slipway
+  module Output
+    TABLE = 'table'
+    WIDE = 'wide'
+    NAME = 'name'
+    # Help lists the formats in this order.
+    FORMATS = [TABLE, WIDE, *Serializer::STRUCTURED, NAME].freeze
+
+    # The rule lives in the command layer, whose runner prints the error lines and cannot
+    # require Output.
+    def self.plain(text) = CLI::Style.plain(text)
+
+    # A warning can quote a manifest path or git's stderr. Every warning line is built here, and
+    # the conventions test refuses the prefix anywhere else, so none reaches stderr raw.
+    def self.warning(context, message)
+      context.warn("#{context.paint_err(:warning, 'warning:')} #{plain(message)}")
+    end
+  end
+end