slipway 0.1.0

data/lib/slipway/commands/diff.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'manual'
+require_relative '../inspector'
+require_relative '../plan'
+
+module Slipway
+  module Commands
+    class Diff < Base
+      # Raised once every project has printed: the lines say what differs, so it adds no error
+      # line, only the exit status a script tests.
+      class Differs < Error
+        def initialize = super(problems: [])
+
+        def exit_status = 3
+      end
+
+      # A project that could not be compared, because its manifest could not be read or git could
+      # not answer for it, must not pass for one in sync. The reason is already on stderr, so this
+      # adds only exit status 1.
+      class Unanswered < Error
+        def initialize = super(problems: [])
+      end
+
+      DESCRIPTION = "Show where each selected project differs from its manifest.\n\n" \
+                    'Compares every project of the current group, the projects named, the ones a label selector ' \
+                    'matches, or with --all-groups every project, with its manifest. Each project that differs ' \
+                    'prints its name and one line per difference: Missing, Remote, Branch, Revision or Behind, ' \
+                    'then the blocker that keeps sync from fast-forwarding the branch, if any. A line is followed ' \
+                    'by the git command that shows or resolves it when there is one; slipway never runs it. A ' \
+                    "project that matches its manifest prints nothing.\n\n" \
+                    'The repositories are read as they are on disk: diff contacts no remote and writes nothing, ' \
+                    'so Behind is as of the last fetch, which slipway fetch refreshes. A project pinned by ' \
+                    'spec.revision is compared with that commit instead of its upstream, and is blocked when the ' \
+                    'repository lacks the commit, HEAD is past it or its upstream does not hold it. A paused or ' \
+                    'FetchOnly project shows a blocker only when git cannot read its repository.'
+      USAGE = '[NAME... | project/NAME...]'
+      EXIT_STATUSES = Manual::EXIT_STATUSES.merge(
+        '0' => 'Every selected project matches its manifest.',
+        '1' => 'Runtime error, such as a missing resource or an unreadable manifest, or a project whose state is ' \
+               'Unknown because git failed or did not finish.',
+        '3' => 'At least one selected project differs from its manifest or is blocked, including a directory that ' \
+               'holds no repository (NotARepo) and a repository git refuses (Unsafe).'
+      ).sort_by { |status, _| Integer(status) }.to_h.freeze
+      GLOSSARIES = [
+        CLI::Glossary.new(title: 'Drift', entries: Drift::TYPE_MEANINGS),
+        CLI::Glossary.new(
+          title: 'Blockers',
+          intro: 'A blocker says why the checked-out branch cannot be fast-forwarded, onto its upstream or, for a ' \
+                 'project pinned by spec.revision, onto the pin. The first three mean git could not read the ' \
+                 'repository and apply to every project; the others apply only under FastForward to a project that ' \
+                 'is not paused, and RevisionNotFound, PastRevision and OffUpstream only to a pinned one.',
+          entries: Drift::BLOCKER_MEANINGS
+        )
+      ].freeze
+      INDENT = '  '
+      COMMAND_INDENT = '    '
+      ALL_GROUPS = Options::ALL_GROUPS.with(description: 'If present, compare every project across all groups with ' \
+                                                         'its manifest. The group in the current configuration is ' \
+                                                         'ignored even if specified with --group.')
+
+      def self.command(factory)
+        CLI::Command.new(
+          name: 'diff', summary: 'Show where projects differ from their manifests', section: 'Repository Commands',
+          description: DESCRIPTION, examples:, usage: USAGE, exit_statuses: EXIT_STATUSES, glossaries: GLOSSARIES,
+          positionals: [Options.project_positional(factory)],
+          options: [Options::SELECTOR, ALL_GROUPS],
+          handler: new(factory)
+        )
+      end
+
+      def self.examples
+        [
+          CLI::Example.new(comment: 'Show where the projects of the current group differ from their manifests',
+                           command: 'diff'),
+          CLI::Example.new(comment: 'Show every project that differs, in every group', command: 'diff -A'),
+          CLI::Example.new(comment: 'Compare two projects of the work group', command: 'diff api web -n work'),
+          CLI::Example.new(comment: 'Compare the projects labeled lang=rust', command: 'diff -l lang=rust')
+        ]
+      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: 'diff')
+        failure = nil
+        scope.select(Resources::PROJECTS, names) do |projects|
+          next scope.report_none(Resources::PROJECTS) if projects.empty?
+
+          failure = compare(context, Base.examine(runtime, context, projects))
+        end
+        failure = Unanswered.new if scope.skipped?
+        raise failure if failure
+      end
+
+      private
+
+      def compare(context, inspections)
+        plans = inspections.map { Plan.for(it) }
+        inspections.zip(plans).each { |inspection, plan| report(context, inspection.project, plan) }
+        return Unanswered.new if inspections.any? { it.state == Inspector::UNKNOWN }
+
+        Differs.new unless plans.all?(&:converged?)
+      end
+
+      # Messages and commands arrive redacted; git's text in them is made plain here.
+      def report(context, project, plan)
+        return if plan.converged?
+
+        lines = plan.items.flat_map do |item|
+          word = context.paint(item.blocker ? :status_danger : :status_warning, "#{item.type}:")
+          line = "#{INDENT}#{word} #{Output.plain(item.message)}"
+          item.command ? [line, COMMAND_INDENT + context.paint(:muted, Output.plain(item.command))] : [line]
+        end
+        context.puts("#{Resources::PROJECTS.singular}/#{project.name}", *lines)
+      end
+    end
+  end
+end

data/lib/slipway/commands/edit.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../editor'
+require_relative '../manifest'
+require_relative '../store'
+
+module Slipway
+  module Commands
+    class Edit < Base
+      DESCRIPTION = "Edit a resource from the default editor.\n\n" \
+                    'The edit command allows you to directly edit any resource in the registry. It will open ' \
+                    'the editor named by the SLIPWAY_EDITOR environment variable, then the editor key of the ' \
+                    "configuration file, then VISUAL or EDITOR, or fall back to 'vi'.\n\n" \
+                    'The kind, name, group and creation timestamp of a resource cannot be changed. If an error ' \
+                    'occurs while saving, the file is reopened with the relevant failures as comments at the ' \
+                    "top; saving it again without changes cancels the edit.\n\n" \
+                    "#{Options::TYPES_SENTENCE}".freeze
+      USAGE = '(TYPE NAME | TYPE/NAME)'
+      HEADER = <<~TEXT
+        # Please edit the object below. Lines beginning with a '#' will be ignored,
+        # and an empty file will abort the edit. If an error occurs while saving this
+        # file will be reopened with the relevant failures.
+        #
+      TEXT
+      UNCHANGED = 'Edit cancelled, no changes made.'
+      EMPTY = 'Edit cancelled, saved file was empty.'
+      ABORTED = 'Edit cancelled, no valid changes were saved.'
+      IMMUTABLE = 'kind, metadata.name and metadata.group cannot be changed'
+      SOURCE = 'edited manifest'
+      COMMENT = /\A\s*#/
+
+      class Aborted < Slipway::Error; end
+
+      def self.command(factory)
+        CLI::Command.new(
+          name: 'edit', summary: 'Edit a resource from the default editor', section: 'Basic Commands',
+          description: DESCRIPTION, examples:, usage: USAGE,
+          positionals: [Options::TYPE, Options.name_positional(factory, variadic: false, required: false)],
+          handler: new(factory)
+        )
+      end
+
+      def self.examples
+        [
+          CLI::Example.new(comment: "Edit the project named 'hldr'", command: 'edit project hldr'),
+          CLI::Example.new(comment: 'Edit a project in the work group', command: 'edit project job -n work'),
+          CLI::Example.new(comment: "Edit the group named 'work'", command: 'edit group work')
+        ]
+      end
+      private_class_method :examples
+
+      def kinds = Resources::KINDS
+
+      def run(runtime, context, args, opts)
+        scope = scope(runtime, context, opts)
+        kind, name = scope.target(args)
+        resource = runtime.store.find(kind, name, group: scope.group)
+        editor = Editor.new(env: context.env, preferred: runtime.settings.editor)
+        edited = Session.new(editor, kind, resource).edit
+        return context.warn(UNCHANGED) if edited.nil?
+
+        finish(runtime, context, kind, resource, edited)
+      end
+
+      private
+
+      # kubectl reports `skipped` when the text changed but the object did not.
+      def finish(runtime, context, kind, original, edited)
+        return result_line(context, kind, original.name, 'skipped', :apply_unchanged) if edited == original
+
+        runtime.store.save(edited)
+        result_line(context, kind, original.name, 'edited', :apply_configured)
+      end
+
+      class Session
+        def initialize(editor, kind, resource)
+          @editor = editor
+          @kind = kind
+          @resource = resource
+          @original = Manifest.dump(resource)
+        end
+
+        def edit
+          text = @original
+          problem = nil
+          loop do
+            edited = strip(@editor.edit(buffer(text, problem), filename: "#{@resource.name}.yaml"))
+            raise Aborted, EMPTY if edited.strip.empty?
+            raise Aborted, ABORTED if problem && edited == text
+            return nil if edited == @original
+
+            return parse(edited)
+          rescue Manifest::Invalid => e
+            problem = e.problem
+            text = edited
+          end
+        end
+
+        private
+
+        # The failure is worded as kubectl words it.
+        def buffer(text, problem)
+          return "#{HEADER}#{text}" if problem.nil?
+
+          "#{HEADER}# #{@kind.plural} #{@resource.name.inspect} was not valid:\n# * #{problem}\n#\n#{text}"
+        end
+
+        def strip(text) = text.lines.grep_v(COMMENT).join
+
+        # The stored creationTimestamp is kept whatever the buffer says, as apply keeps it.
+        def parse(text)
+          parsed = Manifest.parse_yaml(text, source: SOURCE, default_group: group)
+          raise Manifest::Invalid.new(SOURCE, IMMUTABLE) unless same_identity?(parsed)
+
+          parsed.with(created_at: @resource.created_at)
+        end
+
+        def group = @kind.namespaced? ? @resource.group : Store::DEFAULT_GROUP
+
+        def same_identity?(parsed)
+          parsed.instance_of?(@kind.klass) && parsed.name == @resource.name &&
+            (!@kind.namespaced? || parsed.group == @resource.group)
+        end
+      end
+
+      private_constant :Session
+    end
+  end
+end

data/lib/slipway/commands/explain.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require_relative '../cli'
+require_relative '../resources'
+require_relative '../schema'
+require_relative '../output'
+require_relative 'options'
+
+module Slipway
+  module Commands
+    # Reads only Schema, so it builds no runtime and answers even where the configuration file is
+    # broken or git is missing.
+    class Explain
+      DESCRIPTION = "Describe fields and structure of the resource types.\n\n" \
+                    'This command describes the fields of each resource type, as a manifest holds them. Fields ' \
+                    'are identified by a dotted path after the type word, such as project.spec.syncPolicy. Each ' \
+                    'field shows its type, -required- when a manifest must have it, and a description with the ' \
+                    'rule its value follows and its default; --recursive prints the whole tree of names and ' \
+                    "types instead.\n\n" \
+                    "#{Options::TYPES_SENTENCE} Field names are case-sensitive, as in a manifest.".freeze
+      USAGE = 'TYPE[.FIELD...]'
+      SEPARATOR = '.'
+      RECURSIVE = CLI::Option.new(long: 'recursive',
+                                  description: 'If present, print the name of all the fields recursively. ' \
+                                               'Otherwise, print the available fields with their description.')
+
+      def self.command(_factory)
+        CLI::Command.new(
+          name: 'explain', summary: 'Get documentation for a resource', section: 'Basic Commands',
+          description: DESCRIPTION, examples:, usage: USAGE, options: [RECURSIVE], handler: new,
+          positionals: [CLI::Positional.new(name: 'TYPE', completer: ->(_given, current) { paths(current) })]
+        )
+      end
+
+      def self.examples
+        [
+          CLI::Example.new(comment: 'Get the documentation of the resource and its fields',
+                           command: 'explain projects'),
+          CLI::Example.new(comment: 'Get all the fields in the resource', command: 'explain projects --recursive'),
+          CLI::Example.new(comment: 'Get the documentation of a specific field of a resource',
+                           command: 'explain project.spec.syncPolicy')
+        ]
+      end
+      private_class_method :examples
+
+      # The type words, then the fields one level under the path typed so far, as whole paths.
+      # A path with fields under it goes on after a dot, so the shell adds no space after it. A
+      # path naming no type or field has no candidates, never an error in the shell.
+      def self.paths(current)
+        parent, dot, = current.rpartition(SEPARATOR)
+        offered = (dot.empty? ? types : children(parent)).select { |path, _, _| path.start_with?(current) }
+        candidates = offered.to_h { |path, description, _| [path, description] }
+        offered.any? { |_, _, continues| continues } ? CLI::Completer::NoSpace.new(candidates) : candidates
+      rescue Slipway::Error
+        []
+      end
+
+      def self.types = Options::TYPE_DESCRIPTIONS.map { |word, description| [word, description, true] }
+
+      def self.children(path)
+        _, field = lookup(path)
+        field.fields.map { ["#{path}#{SEPARATOR}#{it.name}", "<#{it.type}>", !it.fields.empty?] }
+      end
+
+      # The kind the type word names and the field the path leads to; raises UsageError for a field
+      # that does not exist, in kubectl's words.
+      def self.lookup(path)
+        # split turns an empty word into no words at all, not into one empty type word.
+        type, *names = path.split(SEPARATOR, -1)
+        kind = Resources.resolve(type || '')
+        field = names.reduce(Schema::KINDS.fetch(kind.title)) do |parent, name|
+          parent.field(name) || raise(CLI::UsageError, "field #{name.inspect} does not exist")
+        end
+        [kind, field]
+      end
+      private_class_method :types, :children
+
+      def kinds = Resources::KINDS
+
+      def call(context, args, opts)
+        kind, field = Explain.lookup(args.fetch(0))
+        Output::Explain.new(context).print(kind: kind.title, field: document(field),
+                                           named: args.fetch(0).include?(SEPARATOR), recursive: opts[:recursive])
+      end
+
+      private
+
+      def document(field)
+        Output::Explain::Field.new(name: field.name, type: field.type, required: field.required,
+                                   description: description(field), fields: field.fields.map { document(it) })
+      end
+
+      # The Kubernetes API reference words a default the same way: "Defaults to 1."
+      def description(field) = field.default.nil? ? field.meaning : "#{field.meaning} Defaults to #{field.default}."
+    end
+  end
+end

data/lib/slipway/commands/fetch.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'results'
+require_relative '../fetcher'
+require_relative '../outcome'
+
+module Slipway
+  module Commands
+    class Fetch < 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 from the remote of each selected project.\n\n" \
+                    'Runs git fetch 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. Git fetches from the ' \
+                    'remote of the checked-out branch, else from the only remote, else from origin, as a git ' \
+                    'fetch typed in the repository would, and updates the references that remote\'s fetch ' \
+                    'refspecs name (remote-tracking references by default) and its tags, never the ' \
+                    'checked-out branch or the working tree. The parallel setting caps how many projects ' \
+                    "fetch at once, and the results print in the order the projects are listed.\n\n" \
+                    'Each project prints one line, one of the results listed below, with a reason in parentheses ' \
+                    'and the details under it. A project whose repository cannot be read, or in which git finds ' \
+                    'no remote to fetch from, is skipped before git fetch runs. A project whose spec.paused is ' \
+                    "true is paused: no git command runs in it.\n\n" \
+                    'Git never prompts: a fetch that needs a password, a passphrase or a host key is denied, one ' \
+                    'that runs past the networkTimeout setting is killed, and only the transports in the ' \
+                    'protocols setting are allowed. The exit status is 1 when any project was denied or failed.'
+      USAGE = '[NAME... | project/NAME...]'
+      # In the order the closing summary counts them.
+      ROLES = { 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
+
+      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 no remote is contacted: a project that would be fetched reads fetched, and every ' \
+               'line and the count end in (dry run). Ctrl-C stops the git processes slipway started and exits with ' \
+               'status 130.',
+        entries: {
+          Outcome::FETCHED => "The remote moved refs, and up to #{Fetcher::REF_LIMIT} follow: origin/main " \
+                              'a1b2c3d..e4f5a6b for a ref that moved, origin/feature d09a085 (new) for a new one ' \
+                              'and origin/feature deleted (was d09a085) for one --prune removed. A last line, and ' \
+                              'N more, counts the rest. Tags appear under their bare name. With git before 2.41, ' \
+                              'every fetch that succeeds reads fetched, without the refs.',
+          Outcome::UNCHANGED => 'The remote answered and had nothing new.',
+          "#{Outcome::SKIPPED} (Reason)" => 'No fetch ran: git could not read the repository (Missing, NotARepo, ' \
+                                            'Unsafe, Unknown), git has no remote to pick because there is no ' \
+                                            'upstream, no origin and either no remote or more than one ' \
+                                            "(#{Fetcher::NO_REMOTE}), or the branch tracks a local branch " \
+                                            '(LocalUpstream).',
+          Outcome::PAUSED => 'spec.paused is true, so no git command ran in the project.',
+          "#{Outcome::DENIED} (Reason)" => 'Git needed a password, a passphrase or a host key (AuthRequired). Run ' \
+                                           'the git -C PATH fetch printed below it once in a terminal to see what ' \
+                                           'git needs.',
+          "#{Outcome::FAILED} (Reason)" => 'The fetch ran past networkTimeout (Timeout), used a transport ' \
+                                           'protocols leaves out (ProtocolNotAllowed), or git failed for another ' \
+                                           'reason (Unknown).'
+        }
+      )
+      ALL_GROUPS = Options::ALL_GROUPS.with(description: 'If present, fetch every project across all groups. The ' \
+                                                         'group in the current configuration is ignored even if ' \
+                                                         'specified with --group.')
+      PRUNE = CLI::Option.new(long: 'prune', description: 'Before fetching, remove any remote-tracking references ' \
+                                                          'that no longer exist on the remote.')
+
+      def self.command(factory)
+        CLI::Command.new(
+          name: 'fetch', summary: 'Fetch from the remote of each project', section: 'Repository Commands',
+          description: DESCRIPTION, examples:, usage: USAGE, glossaries: [RESULTS],
+          positionals: [Options.project_positional(factory)],
+          options: [Options::SELECTOR, ALL_GROUPS, PRUNE, Options::DRY_RUN],
+          handler: new(factory)
+        )
+      end
+
+      def self.examples
+        [
+          CLI::Example.new(comment: 'Fetch every project in the current group', command: 'fetch'),
+          CLI::Example.new(comment: 'Fetch every project in every group', command: 'fetch -A'),
+          CLI::Example.new(comment: 'Fetch two projects of the work group', command: 'fetch api web -n work'),
+          CLI::Example.new(comment: 'Fetch the projects labeled lang=rust and prune deleted branches',
+                           command: 'fetch -l lang=rust --prune'),
+          CLI::Example.new(comment: 'List the projects a fetch would reach, without contacting any remote',
+                           command: 'fetch -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: 'fetch')
+        dry_run = opts[:dry_run] == true
+        fetcher = Fetcher.new(runtime, prune: opts[:prune] == true, dry_run:)
+        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: fetcher.method(:attempt))
+          results.summarize
+        end
+        raise Failed if results.any?(Outcome::DENIED, Outcome::FAILED)
+      end
+    end
+  end
+end

data/lib/slipway/commands/from_dir.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require_relative '../error'
+require_relative '../git/errors'
+require_relative '../git/url'
+require_relative '../names'
+require_relative '../output'
+require_relative '../paths'
+require_relative '../resources'
+require_relative '../scanner'
+require_relative '../store'
+
+module Slipway
+  module Commands
+    # Registers the repositories Scanner finds for create project --from-dir. Each is keyed by
+    # its path within the group, so a second run over the same directory adds only new clones.
+    class FromDir
+      # `created` is false for a path the group already held; `project` is then the stored one.
+      Entry = Data.define(:project, :created)
+
+      NONE_FOUND = 'no git repositories found under %s to depth %d'
+      TAKEN = 'project %p already exists at %s'
+      ORIGIN_FIELD = 'origin'
+      NOT_UTF8 = 'path is not valid UTF-8'
+      SEPARATOR = /[^a-z0-9-]+/
+      EDGE_DASHES = /\A-+|-+\z/
+
+      attr_reader :problems
+
+      def initialize(runtime, context, group:, labels:, dry_run:)
+        @store = runtime.store
+        @git = runtime.git
+        @home = File.expand_path(runtime.paths.home)
+        @context = context
+        @group = group
+        @labels = labels
+        @dry_run = dry_run
+        @problems = []
+      end
+
+      def register(directory, depth:)
+        raise Store::NotFound.of(Resources::GROUPS, @group) unless @store.group_available?(@group)
+
+        scan = Scanner.scan(File.absolute_path(Paths.expand(directory, home: @home)), depth:)
+        @problems.concat(scan.problems.map { "#{stored_path(it.path)}: #{it.detail}" })
+        raise Error, format(NONE_FOUND, directory, depth) if scan.repositories.empty? && scan.problems.empty?
+
+        index_registered
+        scan.repositories.filter_map { entry(it) }
+      end
+
+      private
+
+      # A failure is kept with the path it concerns, so the other repositories are still registered.
+      def entry(path)
+        shown = stored_path(path)
+        raise Error, NOT_UTF8 unless path.valid_encoding?
+
+        existing = @by_path[identity(path)]
+        return Entry.new(project: existing, created: false) if existing
+
+        Entry.new(project: create(path, shown), created: true)
+      rescue Error => e
+        @problems << problem(shown, e)
+        nil
+      end
+
+      # A git error starts with the absolute path, which the line already names as the manifest would.
+      def problem(shown, error)
+        detail = error.is_a?(Git::Error) ? error.message.delete_prefix("#{error.path}: ") : error.message
+        ["#{shown}: #{detail}", error.hint].compact.join('. ')
+      end
+
+      def create(path, shown)
+        project = Project.new(name: claim(name_for(path)), group: @group, labels: @labels, path: shown,
+                              remote: remote(path, shown))
+        project = @store.create(project) unless @dry_run
+        remember(project)
+        project
+      end
+
+      def name_for(path)
+        Names.validate!(File.basename(path).downcase.gsub(SEPARATOR, '-').gsub(EDGE_DASHES, ''), what: 'project name')
+      end
+
+      # The listing skips a manifest it cannot read, whose name the store still holds.
+      def claim(name)
+        taken = @by_name[name]
+        raise Error, format(TAKEN, name, taken.path) if taken
+
+        unreadable = @store.exist?(Resources::PROJECTS, name, group: @group)
+        raise Store::Conflict, "project #{name.inspect} already exists" if unreadable
+
+        name
+      end
+
+      # A manifest that cannot be read is reported the way get reports it.
+      def index_registered
+        @by_path = {}
+        @by_name = {}
+        @store.list(Resources::PROJECTS, group: @group) { Output.warning(@context, it.message) }.each { remember(it) }
+      end
+
+      # Slipway never expands a ~user path, so such a project holds its name but no directory.
+      def remember(project)
+        path = Paths.expand(project.path, home: @home)
+        @by_path[identity(File.absolute_path(path))] = project if File.absolute_path?(path)
+        @by_name[project.name] = project
+      end
+
+      # A clone reached through a symbolic link, or registered from a directory reached through
+      # one, is still the same clone; a stored path that no longer resolves keeps its spelling.
+      def identity(path)
+        File.realpath(path)
+      rescue SystemCallError
+        path
+      end
+
+      # A remote that is refused once its credentials are dropped is left out rather than
+      # failing the registration: the path alone is enough to track the clone. git config reads a
+      # repository it distrusts or cannot open as one without an origin, so a missing origin is
+      # trusted only once git has read the repository.
+      def remote(path, shown)
+        url = @git.remote_url(path)
+        @git.status(path) if url.nil?
+        url && Git::Url.validate!(Git::Url.without_credentials(url), field: ORIGIN_FIELD)
+      rescue Git::Url::Invalid => e
+        Output.warning(@context, "#{shown}: spec.remote left out: #{e.message}")
+        nil
+      end
+
+      # Under HOME the path is written with ~/, so the manifest names the same clone on another machine.
+      def stored_path(path)
+        return '~' if path == @home
+        return path unless path.start_with?("#{@home}/")
+
+        "~/#{path.delete_prefix("#{@home}/")}"
+      end
+    end
+  end
+end