slipway 0.1.0

data/lib/slipway/commands/rollout_spec.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Slipway
+  module Commands
+    module Rollout
+      # Writes one spec field of each named project and prints what changed. No git command runs:
+      # the next fetch or sync reads the field.
+      class SpecChange < Base
+        def kinds = [Resources::PROJECTS]
+
+        def run(runtime, context, args, opts)
+          scope = scope(runtime, context, opts)
+          names = scope.project_targets(args, verb: self.class::VERB)
+          scope.select(Resources::PROJECTS, names) { |projects| projects.each { write(runtime, context, it) } }
+        end
+
+        private
+
+        def write(runtime, context, project)
+          changed = change(project)
+          runtime.store.save(changed) if changed
+          word, role = changed ? [self.class::DONE, :result_changed] : [self.class::NOTHING, :result_unchanged]
+          result_line(context, Resources::PROJECTS, project.name, word, role)
+        end
+      end
+
+      class Unpin < SpecChange
+        DESCRIPTION = "Stop holding projects at a revision.\n\n" \
+                      'Removes spec.revision from the manifest of each named project, so the next slipway sync ' \
+                      'fast-forwards its branch onto its upstream again. The repository is left as it is. A ' \
+                      'project without spec.revision prints not pinned.'
+        VERB = 'unpin'
+        DONE = 'unpinned'
+        NOTHING = 'not pinned'
+
+        def self.command(factory)
+          CLI::Command.new(
+            name: 'unpin', summary: 'Stop holding a project at a revision', description: DESCRIPTION,
+            usage: MANY_USAGE,
+            examples: [CLI::Example.new(comment: 'Let project hldr follow its upstream again',
+                                        command: 'rollout unpin hldr')],
+            positionals: [Options.project_positional(factory, required: true)], handler: new(factory)
+          )
+        end
+
+        private
+
+        def change(project) = project.revision && project.with(revision: nil)
+      end
+
+      class Pause < SpecChange
+        DESCRIPTION = "Mark the provided projects as paused.\n\n" \
+                      'Sets spec.paused in the manifest of each named project. Paused projects are left alone by ' \
+                      'slipway fetch and slipway sync, which run no git command in them; slipway rollout undo still ' \
+                      'acts on them. Use slipway rollout resume to resume a paused project.'
+        VERB = 'pause'
+        DONE = 'paused'
+        NOTHING = 'already paused'
+
+        def self.command(factory)
+          CLI::Command.new(
+            name: 'pause', summary: 'Mark the provided project as paused', description: DESCRIPTION,
+            usage: MANY_USAGE,
+            examples: [CLI::Example.new(comment: 'Keep fetch and sync away from project dots',
+                                        command: 'rollout pause dots')],
+            positionals: [Options.project_positional(factory, required: true)], handler: new(factory)
+          )
+        end
+
+        private
+
+        def change(project) = project.paused ? nil : project.with(paused: true)
+      end
+
+      class Resume < SpecChange
+        DESCRIPTION = "Resume paused projects.\n\n" \
+                      'Removes spec.paused from the manifest of each named project, so slipway fetch and slipway ' \
+                      'sync act on it again. A project that is not paused prints not paused.'
+        VERB = 'resume'
+        DONE = 'resumed'
+        NOTHING = 'not paused'
+
+        def self.command(factory)
+          CLI::Command.new(
+            name: 'resume', summary: 'Resume a paused project', description: DESCRIPTION, usage: MANY_USAGE,
+            examples: [CLI::Example.new(comment: 'Resume the paused project dots', command: 'rollout resume dots')],
+            positionals: [Options.project_positional(factory, required: true)], handler: new(factory)
+          )
+        end
+
+        private
+
+        def change(project) = project.paused ? project.with(paused: false) : nil
+      end
+    end
+  end
+end

data/lib/slipway/commands/rollout_undo.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'manual'
+require_relative 'results'
+require_relative '../outcome'
+require_relative '../rollback'
+
+module Slipway
+  module Commands
+    module Rollout
+      class Undo < Base
+        # Raised once the line has printed: it already says why, so this adds only exit status 1.
+        class Failed < Error
+          def initialize = super(problems: [])
+        end
+
+        DESCRIPTION = "Roll back a project to a previous revision.\n\n" \
+                      'Moves the checked-out branch to the revision before the current one, or to the one ' \
+                      '--to-revision names from slipway rollout history, and then writes that commit to ' \
+                      'spec.revision, so sync holds the project there until slipway rollout unpin. The branch moves ' \
+                      'back with git reset --keep, only when its upstream holds every commit the move drops, and ' \
+                      'forward, to undo an undo, with git merge --ff-only. Untracked files and unstaged changes to ' \
+                      'files the move leaves alone are kept; git refuses a move that would overwrite a local change ' \
+                      'or an untracked file, and slipway refuses one that would overwrite an ignored file. A move ' \
+                      'back skips a project with staged changes, and a move forward one with staged or unstaged ' \
+                      "changes.\n\n" \
+                      'A project whose HEAD is detached, whose branch has no commits or no upstream that exists, ' \
+                      'that is in the middle of a merge, rebase or other operation, or whose branch has commits its ' \
+                      'upstream lacks, is skipped with the reason and nothing is moved or written. A paused project ' \
+                      "can be rolled back: pausing only keeps fetch and sync away.\n\n" \
+                      'The project prints one line, one of the results listed below, with a reason in ' \
+                      "parentheses and the details under it.\n\n" \
+                      'With --dry-run nothing is moved or written, and the line ends in (dry run).'
+        EXIT_STATUSES = Manual::EXIT_STATUSES.merge(
+          '0' => 'The project was rolled back, or already stood at the revision and was held there.',
+          '1' => 'Runtime error, such as a missing resource or an unreadable manifest, or a project that was ' \
+                 'skipped or whose move was denied or failed.'
+        ).freeze
+        TO_REVISION = CLI::Option.new(long: 'to-revision', argument: 'N',
+                                      description: 'The revision to roll back to, as slipway rollout history ' \
+                                                   'numbers it. 0, the default, is the revision before the ' \
+                                                   'current one.')
+        REVISION_INVALID = 'invalid argument %p for --to-revision: must be a revision number, or 0'
+        RESULTS = CLI::Glossary.new(
+          title: 'Results',
+          entries: {
+            Rollback::ROLLED_BACK => 'The branch moved, or it already stood at the revision and only spec.revision ' \
+                                     'changed. The detail names the commits it crossed and the command that lets ' \
+                                     'sync follow the upstream again.',
+            Outcome::UNCHANGED => 'The branch already stood at the revision and spec.revision already held it.',
+            "#{Outcome::SKIPPED} (Reason)" => 'Nothing moved and nothing was written. git could not read the ' \
+                                              'repository (Missing, NotARepo, Unsafe, Unknown); the branch cannot ' \
+                                              'move (Conflicted, Detached, Unborn, NoUpstream, Gone, InProgress); ' \
+                                              'the history has no such revision (NoHistory, NoPrevious, ' \
+                                              'UnknownRevision) or the repository no such commit ' \
+                                              '(RevisionNotFound); a move back would drop commits the upstream ' \
+                                              'lacks (LocalCommits) or staged changes (Dirty), or the revision is ' \
+                                              "off the branch's history (Diverged); a move forward needs a tree " \
+                                              'without staged or unstaged changes (Dirty) and a revision on the ' \
+                                              'upstream (OffUpstream); or git refused the move (WouldLoseChanges, ' \
+                                              'WouldOverwrite for untracked or ignored files in the way, Busy, ' \
+                                              'NotFastForward for a branch that moved since the check).',
+            "#{Outcome::DENIED} (Reason)" => 'A partial clone had to fetch the files the move writes and the remote ' \
+                                             'asked for a password, a passphrase or a host key (AuthRequired), as ' \
+                                             'in slipway fetch.',
+            "#{Outcome::FAILED} (Reason)" => 'The move ran past networkTimeout (Timeout) or git failed for another ' \
+                                             'reason (Unknown), and spec.revision was not written, though a move ' \
+                                             'stopped at the deadline keeps the files git had already written, as ' \
+                                             'in slipway sync; or the branch moved but spec.revision could not be ' \
+                                             "written (#{Rollback::NOT_PINNED}), and the detail names the " \
+                                             '--to-revision command that writes it without moving the branch again.'
+          }
+        )
+        ROLES = { Rollback::ROLLED_BACK => :result_changed, Outcome::UNCHANGED => :result_unchanged,
+                  Outcome::SKIPPED => :result_skipped, Outcome::DENIED => :result_denied,
+                  Outcome::FAILED => :result_failed }.freeze
+
+        def self.command(factory)
+          CLI::Command.new(
+            name: 'undo', summary: 'Undo a previous rollout', description: DESCRIPTION, usage: SINGLE_USAGE,
+            examples:, exit_statuses: EXIT_STATUSES, glossaries: [RESULTS],
+            positionals: [Options.project_positional(factory, variadic: false, required: true)],
+            options: [TO_REVISION, Options::DRY_RUN],
+            handler: new(factory)
+          )
+        end
+
+        def self.examples
+          [
+            CLI::Example.new(comment: 'Roll back project hldr to the previous revision', command: 'rollout undo hldr'),
+            CLI::Example.new(comment: 'Roll back project hldr to revision 3',
+                             command: 'rollout undo hldr --to-revision=3'),
+            CLI::Example.new(comment: 'Show where undo would move project hldr, without moving or writing anything',
+                             command: 'rollout undo hldr --dry-run')
+          ]
+        end
+        private_class_method :examples
+
+        def kinds = [Resources::PROJECTS]
+
+        def run(runtime, context, args, opts)
+          scope = scope(runtime, context, opts)
+          names = scope.project_targets(args, verb: 'roll back')
+          number = revision(opts[:to_revision])
+          dry_run = opts[:dry_run] == true
+          rollback = Rollback.new(runtime, dry_run:, group: opts[:group] ? nil : runtime.settings.group)
+          results = Results.new(context, ROLES, dry_run:)
+          scope.select(Resources::PROJECTS, names) do |projects|
+            projects.each { results.report(rollback.undo(it, number:)) }
+          end
+          raise Failed if results.any?(Outcome::SKIPPED, Outcome::DENIED, Outcome::FAILED)
+        end
+
+        private
+
+        def revision(value)
+          return if value.nil?
+
+          number = Integer(value, 10, exception: false)
+          number && !number.negative? ? number : raise(CLI::UsageError, format(REVISION_INVALID, value))
+        end
+      end
+    end
+  end
+end

data/lib/slipway/commands/scope.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require_relative '../cli/errors'
+require_relative '../field_selector'
+require_relative '../names'
+require_relative '../output'
+require_relative '../resources'
+require_relative '../selector'
+require_relative '../store'
+require_relative '../views'
+
+module Slipway
+  module Commands
+    # Names typed on the command line are checked here, so a bad one is a usage error rather
+    # than a failure deep in the store.
+    class Scope
+      NONE = 'No resources found.'
+      NONE_IN = 'No resources found in '
+      GROUP_SUFFIX = ' group.'
+      NAMES_WITH_SELECTOR = 'name cannot be provided when a selector is specified'
+      NAMES_WITH_ALL_GROUPS = 'a resource cannot be retrieved by name across all groups'
+      MIXED_TYPES = 'all resources must share one type'
+      MIXED_FORMS = 'a name in TYPE/NAME form cannot be combined with a bare name'
+      NAME_MISSING = 'missing required argument "NAME"'
+
+      def initialize(runtime, context, opts)
+        @runtime = runtime
+        @context = context
+        @opts = opts
+        @skipped = false
+      end
+
+      def kind(word) = Resources.resolve(word)
+
+      # `TYPE/NAME...` is the form `get -o name` prints.
+      def targets(words)
+        type, *names = words
+        kind, names = type.include?('/') ? slashed(words) : [kind(type), names]
+        names.each { check_name(kind, it) }
+        [kind, names]
+      end
+
+      # A verb that acts on repositories names projects alone, bare or in the TYPE/NAME form
+      # `get projects -o name` prints, since a group holds no repository of its own.
+      def project_targets(words, verb:)
+        kind, names = words.any? { it.include?('/') } ? slashed(words) : [Resources::PROJECTS, words]
+        raise CLI::UsageError, "cannot #{verb} a group" unless kind == Resources::PROJECTS
+
+        names.each { check_name(kind, it) }
+        check_names(kind, across: "cannot #{verb} a project by name across all groups") unless names.empty?
+        names
+      end
+
+      def target(words)
+        kind, names = targets(words)
+        raise CLI::UsageError, NAME_MISSING if names.empty?
+        raise CLI::UsageError, "unexpected argument #{names[1].inspect}" if names.size > 1
+
+        [kind, names.first]
+      end
+
+      def group
+        flag = @opts[:group]
+        as_usage_error { Names.validate!(flag, what: 'group name') } unless flag.nil?
+        @runtime.group_for(@opts)
+      end
+
+      def all_groups? = @opts[:all_groups] == true
+
+      def selector = Selector.parse(@opts[:selector])
+
+      def field_selector(kind, names)
+        check_names(kind) unless names.empty?
+        FieldSelector.parse(@opts[:field_selector], fields: kind.namespaced? ? Views::Project::FIELDS : Views::Group::FIELDS)
+      end
+
+      # A verb whose exit status vouches for every project must not report success when a listing
+      # left a manifest out.
+      def skipped? = @skipped
+
+      # As in kubectl, the resources that exist are shown before the names that do not are
+      # reported, one `error:` line each.
+      def select(kind, names)
+        return yield(listed(kind)) if names.empty?
+
+        check_names(kind)
+        found, missing = resolve(kind, names)
+        yield found unless found.empty?
+        raise Error.new(problems: missing) unless missing.empty?
+      end
+
+      def report_none(kind)
+        return @context.warn(@context.paint_err(:muted, NONE)) if all_groups? || !kind.namespaced?
+
+        @context.warn(@context.paint_err(:muted, NONE_IN) + @context.paint_err(:string, group) +
+                      @context.paint_err(:muted, GROUP_SUFFIX))
+      end
+
+      private
+
+      def slashed(words)
+        pairs = words.map do |word|
+          type, name = word.split('/', 2)
+          raise CLI::UsageError, MIXED_FORMS if name.nil?
+
+          [kind(type), name]
+        end
+        kinds = pairs.map(&:first).uniq
+        raise CLI::UsageError, MIXED_TYPES if kinds.size > 1
+
+        [kinds.first, pairs.map(&:last)]
+      end
+
+      def check_name(kind, name)
+        as_usage_error { Names.validate!(name, what: "#{kind.singular} name") }
+      end
+
+      def as_usage_error
+        yield
+      rescue Names::Invalid => e
+        raise CLI::UsageError, e.message
+      end
+
+      # A manifest that cannot be read is reported and skipped, so one bad file does not
+      # hide the rest of the registry.
+      def listed(kind)
+        matcher = selector
+        scope_group = kind.namespaced? && !all_groups? ? group : nil
+        resources = @runtime.store.list(kind, group: scope_group) do |problem|
+          @skipped = true
+          Output.warning(@context, problem.message)
+        end
+        resources.select { matcher.match?(it.labels) }
+      end
+
+      def resolve(kind, names)
+        found = []
+        missing = []
+        names.each do |name|
+          found << @runtime.store.find(kind, name, group:)
+        rescue Store::NotFound => e
+          missing << e.message
+        end
+        [found, missing]
+      end
+
+      # kubectl refuses a label or field selector or --all-namespaces next to explicit names.
+      # `across` replaces kubectl's "retrieved" for a verb that acts on the projects it names.
+      def check_names(kind, across: NAMES_WITH_ALL_GROUPS)
+        selectors = @opts.values_at(:selector, :field_selector)
+        raise CLI::UsageError, NAMES_WITH_SELECTOR unless selectors.all? { it.to_s.strip.empty? }
+        raise CLI::UsageError, across if kind.namespaced? && all_groups?
+      end
+    end
+  end
+end

data/lib/slipway/commands/sync.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'manual'
+require_relative 'fetch'
+require_relative 'results'
+require_relative '../fetcher'
+require_relative '../outcome'
+require_relative '../syncer'
+
+module Slipway
+  module Commands
+    class Sync < Base
+      # Raised once every line has printed: the lines already say what went wrong, so it adds no
+      # error line, only exit status 1.
+      class Failed < Error
+        def initialize = super(problems: [])
+      end
+
+      DESCRIPTION = "Fetch each selected project and fast-forward its branch.\n\n" \
+                    'Runs in every project of the current group, in the projects named, in the ones a label ' \
+                    'selector matches, or with --all-groups in every project. Each project is fetched as slipway ' \
+                    'fetch fetches it and compared with its manifest as slipway diff compares it, and its ' \
+                    'checked-out branch is fast-forwarded onto its upstream when the branch tracks an upstream ' \
+                    'that still exists, is behind it without commits of its own, has no staged, unstaged or ' \
+                    'conflicted changes and no merge, rebase or other operation in progress. Untracked files do ' \
+                    'not stop it, and git refuses a fast-forward that would overwrite one. Sync never merges, ' \
+                    "rebases, stashes, resets, switches a branch or changes a remote.\n\n" \
+                    'A project whose spec.syncPolicy is FetchOnly is only fetched, and one whose spec.paused is ' \
+                    'true is left alone: no git command runs in it. A project pinned by spec.revision is ' \
+                    'fast-forwarded up to that commit instead of its upstream, only when its upstream holds the ' \
+                    "commit, never past it, and never moved back to it.\n\n" \
+                    'Each project prints one line, one of the results listed below, with a reason in parentheses ' \
+                    'and the details under it. The parallel setting caps how many projects fetch at once, ' \
+                    'fast-forwards run one at a time, and the results print in the order the projects are ' \
+                    "listed.\n\n" \
+                    'With --dry-run nothing is fetched or written: the plan is made from the last fetch.'
+      USAGE = '[NAME... | project/NAME...]'
+      EXIT_STATUSES = Manual::EXIT_STATUSES.merge(
+        '0' => 'Every selected project was fast-forwarded, fetched, left unchanged, skipped or paused.',
+        '1' => 'Runtime error, such as a missing resource or an unreadable manifest, or a project whose fetch or ' \
+               'fast-forward was denied or failed.'
+      ).freeze
+      RESULTS = CLI::Glossary.new(
+        title: 'Results',
+        intro: 'When more than one project ran, a count of the results closes the run on stderr. With ' \
+               '--dry-run every line and the count end in (dry run). Ctrl-C stops the git processes slipway ' \
+               'started and exits with status 130; a fast-forward it stops ends as one stopped at the deadline.',
+        entries: {
+          Syncer::FAST_FORWARDED => 'The branch moved. For a move onto the upstream, the detail names the commits ' \
+                                    'it gained, as main a1b2c3d..e4f5a6b (3 commits), and the command that undoes ' \
+                                    "the move; a move up to a spec.revision pin ends in #{Syncer::TO_PIN}.",
+          Outcome::FETCHED => 'The fetch of a FetchOnly project moved refs; the refs follow as in slipway fetch.',
+          Outcome::UNCHANGED => 'The branch stayed where it was and nothing blocked it; the fetch may still have ' \
+                                'moved remote-tracking refs.',
+          "#{Outcome::SKIPPED} (Reason)" => 'The branch stayed where it was: a blocker stopped it, under the name ' \
+                                            'slipway diff gives it; git refused the fast-forward (WouldOverwrite ' \
+                                            'for untracked files in the way, WouldLoseChanges for local changes git ' \
+                                            'status does not show, Busy for a lock another git process holds on ' \
+                                            'the index, HEAD or the branch, NotFastForward for a branch that ' \
+                                            'gained a commit since the check); or the project was skipped before ' \
+                                            'its fetch, as in slipway fetch (Missing, NotARepo, Unsafe, Unknown, ' \
+                                            'NoRemote, LocalUpstream).',
+          Outcome::PAUSED => 'spec.paused is true, so no git command ran in the project.',
+          "#{Outcome::DENIED} (Reason)" => 'The fetch or the fast-forward needed a password, a passphrase or a ' \
+                                           'host key (AuthRequired), as in slipway fetch.',
+          "#{Outcome::FAILED} (Reason)" => 'The fetch or the fast-forward ran past networkTimeout (Timeout), used ' \
+                                           'a transport protocols leaves out (ProtocolNotAllowed), or git failed ' \
+                                           'for another reason (Unknown). A fast-forward stopped at the deadline ' \
+                                           'leaves the branch where it was, but the files git had already written ' \
+                                           'stay in the working tree, and the detail names the command that lists ' \
+                                           'them.'
+        }
+      )
+      # In the order the closing summary counts them.
+      ROLES = { Syncer::FAST_FORWARDED => :result_changed, Outcome::FETCHED => :result_changed,
+                Outcome::UNCHANGED => :result_unchanged, Outcome::SKIPPED => :result_skipped,
+                Outcome::PAUSED => :result_paused, Outcome::DENIED => :result_denied,
+                Outcome::FAILED => :result_failed }.freeze
+      ALL_GROUPS = Options::ALL_GROUPS.with(description: 'If present, sync every project across all groups. The ' \
+                                                         'group in the current configuration is ignored even if ' \
+                                                         'specified with --group.')
+
+      def self.command(factory)
+        CLI::Command.new(
+          name: 'sync', summary: 'Fetch projects and fast-forward their branches', section: 'Repository Commands',
+          description: DESCRIPTION, examples:, usage: USAGE, exit_statuses: EXIT_STATUSES, glossaries: [RESULTS],
+          positionals: [Options.project_positional(factory)],
+          options: [Options::SELECTOR, ALL_GROUPS, Fetch::PRUNE, Options::DRY_RUN],
+          handler: new(factory)
+        )
+      end
+
+      def self.examples
+        [
+          CLI::Example.new(comment: 'Sync every project in the current group', command: 'sync'),
+          CLI::Example.new(comment: 'Sync every project in every group', command: 'sync -A'),
+          CLI::Example.new(comment: 'Sync two projects of the work group', command: 'sync api web -n work'),
+          CLI::Example.new(comment: 'Show what sync would do from the last fetch, without contacting any remote',
+                           command: 'sync -A --dry-run')
+        ]
+      end
+      private_class_method :examples
+
+      def kinds = [Resources::PROJECTS]
+
+      def run(runtime, context, args, opts)
+        scope = scope(runtime, context, opts)
+        names = scope.project_targets(args, verb: 'sync')
+        dry_run = opts[:dry_run] == true
+        fetcher = Fetcher.new(runtime, prune: opts[:prune] == true, dry_run:)
+        syncer = Syncer.new(runtime, fetcher, dry_run:, group: configured_group(runtime, opts))
+        results = Results.new(context, ROLES, dry_run:)
+        scope.select(Resources::PROJECTS, names) do |projects|
+          next scope.report_none(Resources::PROJECTS) if projects.empty?
+
+          results.stream(projects, workers: runtime.settings.parallel, work: syncer.method(:observe)) do |step|
+            syncer.settle(step)
+          end
+          unfetched(context, syncer.unfetched)
+          results.summarize
+        end
+        raise Failed if results.any?(Outcome::DENIED, Outcome::FAILED)
+      end
+
+      private
+
+      # settings.group already holds a typed -n, and the undo line is run later without it.
+      def configured_group(runtime, opts) = opts[:group] ? nil : runtime.settings.group
+
+      def unfetched(context, count)
+        return if count.zero?
+
+        subject = count == 1 ? '1 project was' : "#{count} projects were"
+        Output.warning(context, "#{subject} never fetched and a dry run does not fetch; run 'slipway fetch' " \
+                                'first for an up-to-date plan')
+      end
+    end
+  end
+end

data/lib/slipway/commands.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative 'version'
+require_relative 'cli'
+require_relative 'settings'
+require_relative 'paths'
+require_relative 'commands/manual'
+require_relative 'commands/options'
+require_relative 'commands/base'
+require_relative 'commands/scope'
+require_relative 'commands/get'
+require_relative 'commands/describe'
+require_relative 'commands/create'
+require_relative 'commands/apply'
+require_relative 'commands/delete'
+require_relative 'commands/edit'
+require_relative 'commands/label'
+require_relative 'commands/explain'
+require_relative 'commands/fetch'
+require_relative 'commands/diff'
+require_relative 'commands/sync'
+require_relative 'commands/rollout'
+require_relative 'commands/config'
+require_relative 'commands/api_resources'
+
+module Slipway
+  module Commands
+    PROGRAM = 'slipway'
+    DESCRIPTION = 'A kubectl-style registry of the git repositories on your machine'
+    # The space after each newline indents the paragraphs, as kubectl's root help does.
+    LONG_DESCRIPTION = "#{DESCRIPTION}.\n\n " \
+                       "A project is a registered git repository. get and describe show where each one\n " \
+                       "stands, and fetch fetches them all without prompting. Its manifest can also\n " \
+                       "declare where the repository should be: the remote, the branch and a commit to\n " \
+                       "hold it at. diff shows where a repository differs from that, sync fast-forwards\n " \
+                       "the branches that can move without losing work, and rollout undo takes such a\n " \
+                       "move back.\n\n " \
+                       "Projects live in groups the way pods live in namespaces. The group is\n " \
+                       "\"#{Resources::DEFAULT_GROUP}\", or the one SLIPWAY_GROUP or the group key sets, unless -n\n " \
+                       "is given, and -A covers every group.\n\n " \
+                       "#{Options::TYPES_SENTENCE}".freeze
+    # Help lists the verbs in this order within their sections.
+    VERBS = [Get, Describe, Create, Apply, Delete, Edit, Label, Explain, Fetch, Diff, Sync, Rollout, Config,
+             APIResources].freeze
+
+    def self.registry(factory)
+      CLI::Registry.new(program: PROGRAM, version: VERSION, description: DESCRIPTION,
+                        long_description: LONG_DESCRIPTION,
+                        globals: CLI::Globals.all(group_completer: Options.group_completer(factory)),
+                        commands: VERBS.map { it.command(factory) },
+                        builtins: { paths: Paths.method(:new) })
+    end
+  end
+end

data/lib/slipway/drift.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative 'git/url'
+
+module Slipway
+  # The ways a project can differ from its manifest, and the blockers that keep sync from
+  # resolving them. Plan decides which apply; this module holds the words and their sentences.
+  module Drift
+    # `command` is a git command line that shows or resolves the item; slipway prints it and never
+    # runs it. Either can quote a URL git answered with, so both are redacted here, once for every
+    # reader.
+    Item = Data.define(:type, :message, :command, :blocker) do
+      def initialize(type:, message:, command: nil, blocker: false)
+        super(type:, message: Git::Url.redact(message), command: command && Git::Url.redact(command), blocker:)
+      end
+    end
+
+    MISSING = 'Missing'
+    REMOTE = 'Remote'
+    BRANCH = 'Branch'
+    REVISION = 'Revision'
+    BEHIND = 'Behind'
+    # In the order they are listed.
+    TYPES = [MISSING, REMOTE, BRANCH, REVISION, BEHIND].freeze
+    # When each type is reported, in the same order. The help of diff prints these, and the README
+    # table says the same with its code spans marked.
+    TYPE_MEANINGS = {
+      MISSING => 'The registered path is relative or is not a directory. For a path that is not a directory, a ' \
+                 'project with spec.remote shows the git clone command that recreates it.',
+      REMOTE => 'origin is absent or differs from spec.remote. Sync never changes a remote.',
+      BRANCH => 'HEAD is detached or on another branch than spec.branch. Sync never switches branches.',
+      REVISION => 'HEAD is not the commit spec.revision pins. The pin replaces the upstream, so a pinned project is ' \
+                  'never Behind; under FastForward sync will fast-forward a branch behind the pin to it unless a ' \
+                  'blocker stops it, and never moves a branch back.',
+      BEHIND => 'The checked-out branch is behind its upstream. Under FastForward sync will fast-forward it unless a ' \
+                'blocker stops it; under FetchOnly, or while spec.paused is true, it is only reported.'
+    }.freeze
+    # The drift sync resolves by fast-forwarding the checked-out branch.
+    MOVES = [REVISION, BEHIND].freeze
+
+    # In the order Plan checks them. Each sentence says what holds sync back, so the line reads
+    # the same in diff, describe and sync. Rollback refuses with Conflicted and InProgress too,
+    # so those two name no verb.
+    BLOCKERS = {
+      'NotARepo' => '%<path>s holds files but no repository; sync clones only into an absent directory',
+      'Unsafe' => '%<reason>s',
+      'Unknown' => '%<reason>s',
+      'Detached' => 'HEAD is detached at %<head>s; sync never moves a detached HEAD',
+      'Unborn' => 'no commits yet; nothing to fast-forward',
+      'Gone' => 'upstream %<upstream>s no longer exists; sync never retargets a branch',
+      'NoUpstream' => '%<branch>s tracks no upstream; sync fast-forwards only a tracking branch',
+      'RevisionNotFound' => 'spec.revision %<revision>s is not in this repository; fetch it or unpin',
+      'PastRevision' => '%<branch>s is past the pinned revision; sync never moves a branch back',
+      'OffUpstream' => 'spec.revision %<revision>s is not on %<upstream>s; sync moves a branch only along its upstream',
+      'Conflicted' => '%<paths>s; finish or abort the merge first',
+      'Dirty' => '%<changes>s; sync fast-forwards only a tree without staged or unstaged changes',
+      'Diverged' => '%<ahead>d ahead, %<behind>d behind %<upstream>s; sync never merges or rebases',
+      'InProgress' => 'a %<operation>s is in progress'
+    }.freeze
+
+    # What each blocker means, in the same order, for the help of diff and the README table.
+    BLOCKER_MEANINGS = {
+      'NotARepo' => 'The directory exists but holds no repository.',
+      'Unsafe' => 'git refused the repository because another user owns it (safe.directory); the git command that ' \
+                  'trusts it follows.',
+      'Unknown' => 'git could not answer; the reason is also printed once on stderr.',
+      'Detached' => 'HEAD points at a commit rather than a branch.',
+      'Unborn' => 'The branch has no commits yet.',
+      'Gone' => 'The upstream is configured but its ref no longer exists.',
+      'NoUpstream' => 'The branch tracks no upstream.',
+      'RevisionNotFound' => 'The repository has no commit by the name spec.revision pins.',
+      'PastRevision' => 'HEAD is past the pinned commit or on another line of history, so reaching the pin would ' \
+                        'move the branch back.',
+      'OffUpstream' => 'The upstream does not hold the pinned commit, which may be on another branch or a fork; sync ' \
+                       'moves a branch only along its upstream.',
+      'Conflicted' => 'The branch is behind and the working tree has unmerged paths.',
+      'Dirty' => 'The branch is behind and has staged or unstaged changes; untracked files do not block.',
+      'Diverged' => 'The branch is behind and has commits of its own.',
+      'InProgress' => 'The branch would be fast-forwarded, but a merge, rebase, cherry-pick, revert, bisect or ' \
+                      'git am is in progress.'
+    }.freeze
+
+    def self.blocker(word, command: nil, **values)
+      Item.new(type: word, message: format(BLOCKERS.fetch(word), **values), command:, blocker: true)
+    end
+  end
+end