slipway 0.1.0

data/lib/slipway/commands/apply.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../manifest'
+require_relative '../store'
+
+module Slipway
+  module Commands
+    class Apply < Base
+      # Raised once, after every document that could be applied was.
+      class Failed < Error; end
+
+      DESCRIPTION = "Apply a configuration to a resource by file name or stdin.\n\n" \
+                    'The resource name must be specified in the manifest. A resource is created when it does ' \
+                    'not exist yet, configured when its manifest differs from the one stored, and reported ' \
+                    'unchanged otherwise. A directory applies every *.yaml and *.yml file it holds, sorted by ' \
+                    'name and without descending into subdirectories. A project manifest without ' \
+                    "metadata.group lands in the current group.\n\n" \
+                    'YAML is accepted, with several documents per file, and a document of kind List stands ' \
+                    'for each of its items. Documents are applied in order, so a group may be created by the ' \
+                    'document before the projects that use it.'
+      STDIN_FLAG = '-'
+      NO_OBJECTS = 'no objects passed to apply'
+
+      FILENAME = CLI::Option.new(long: 'filename', short: 'f', argument: 'FILE', repeatable: true, required: true,
+                                 completer: ->(_given, _current) { CLI::Completer::FILES },
+                                 description: 'The file that contains the manifests to apply; may be repeated. ' \
+                                              "A directory reads its *.yaml and *.yml files, '-' reads stdin.")
+
+      def self.command(factory)
+        CLI::Command.new(
+          name: 'apply', summary: 'Apply a configuration to a resource by file name or stdin',
+          section: 'Basic Commands', description: DESCRIPTION, examples:,
+          options: [FILENAME, Options::DRY_RUN],
+          handler: new(factory)
+        )
+      end
+
+      def self.examples
+        [
+          CLI::Example.new(comment: 'Apply the configuration in hldr.yaml to a project',
+                           command: 'apply -f hldr.yaml'),
+          CLI::Example.new(comment: 'Apply every manifest in a directory', command: 'apply -f ./projects'),
+          CLI::Example.new(comment: 'Apply the YAML passed into stdin', command: 'apply -f - < hldr.yaml'),
+          CLI::Example.new(comment: 'Show what would change without writing anything',
+                           command: 'apply -f hldr.yaml --dry-run')
+        ]
+      end
+      private_class_method :examples
+
+      def kinds = Resources::KINDS
+
+      def run(runtime, context, _args, opts)
+        dry_run = opts[:dry_run] == true
+        session = Session.new(runtime.store, default_group: scope(runtime, context, opts).group, dry_run:)
+        opts[:filename].each do |file|
+          session.apply(file) { |kind, name, word, role| result_line(context, kind, name, word, role, dry_run:) }
+        end
+        finish(session)
+      end
+
+      private
+
+      def finish(session)
+        raise Failed, NO_OBJECTS if session.problems.empty? && session.applied.zero?
+        raise Failed.new(problems: session.problems) unless session.problems.empty?
+      end
+
+      # A failed document is remembered in `problems` so the rest still run.
+      class Session
+        STDIN_SOURCE = 'STDIN'
+        EXTENSIONS = %w[.yaml .yml].freeze
+
+        attr_reader :problems, :applied
+
+        def initialize(store, default_group:, dry_run:)
+          @store = store
+          @default_group = default_group
+          @dry_run = dry_run
+          @problems = []
+          @applied = 0
+          @dry_run_groups = []
+        end
+
+        def apply(name, &)
+          read(name).each { |source, text| apply_stream(source, text, &) }
+        rescue Error => e
+          @problems << e.message
+        end
+
+        private
+
+        # The Context carries no input stream, so `-` reads the process's standard input.
+        def read(name)
+          return [[STDIN_SOURCE, $stdin.read]] if name == STDIN_FLAG
+          return directory(name) if File.directory?(name)
+
+          [[name, File.read(name)]]
+        rescue Errno::ENOENT
+          raise Error, "#{name}: no such file"
+        rescue SystemCallError => e
+          raise Error.from_system_call(e, name)
+        end
+
+        def directory(name)
+          files = Dir.children(name).select { EXTENSIONS.include?(File.extname(it)) }.sort
+          files = files.map { File.join(name, it) }.select { File.file?(it) }
+          raise Error, "#{name}: no .yaml or .yml files" if files.empty?
+
+          files.map { [it, File.read(it)] }
+        end
+
+        def apply_stream(source, text, &)
+          documents = Manifest.load_objects(text, source:)
+          documents.each_with_index do |document, index|
+            label = documents.size > 1 ? "#{source}:#{index + 1}" : source
+            collect(label) { apply_resource(Manifest.parse(document, source: label, default_group: @default_group), &) }
+          end
+        end
+
+        # A problem the manifest reader found already names its source; a store error is
+        # prefixed with it so every collected line reads `<source>: <problem>`.
+        def collect(source)
+          yield
+        rescue Manifest::Invalid => e
+          @problems << e.message
+        rescue Error => e
+          @problems << "#{source}: #{e.message}"
+        end
+
+        def apply_resource(resource)
+          kind = Resources.of(resource)
+          group = kind.namespaced? ? resource.group : nil
+          existing = @store.find(kind, resource.name, group:) if @store.exist?(kind, resource.name, group:)
+          word, role = existing ? update(existing, resource) : create(kind, resource)
+          @applied += 1
+          yield kind, resource.name, word, role
+        end
+
+        # The stored creationTimestamp is kept; anything else that differs is a change.
+        def update(existing, incoming)
+          incoming = incoming.with(created_at: existing.created_at)
+          return ['unchanged', :apply_unchanged] if Manifest.dump(existing) == Manifest.dump(incoming)
+
+          @store.save(incoming) unless @dry_run
+          ['configured', :apply_configured]
+        end
+
+        def create(kind, resource)
+          if @dry_run
+            check_group(resource) if kind.namespaced?
+            @dry_run_groups << resource.name unless kind.namespaced?
+          else
+            @store.create(resource)
+          end
+          ['created', :apply_created]
+        end
+
+        # A dry run writes nothing, so a group created earlier in the same run is remembered
+        # here for the projects that follow it.
+        def check_group(project)
+          group = project.group
+          return if @dry_run_groups.include?(group) || @store.group_available?(group)
+
+          raise Store::NotFound.of(Resources::GROUPS, group)
+        end
+      end
+
+      private_constant :Session
+    end
+  end
+end

data/lib/slipway/commands/base.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative '../cli'
+require_relative '../resources'
+require_relative '../output'
+require_relative 'options'
+require_relative 'scope'
+
+module Slipway
+  module Commands
+    # Subclasses define `self.command(factory)`, the registry entry whose handler is an
+    # instance, and `run(runtime, context, args, opts)`, which raises Slipway::Error to fail.
+    class Base
+      # Prints the warnings here so neither read verb can forget them.
+      def self.examine(runtime, context, resources)
+        batch = runtime.inspector.examine_all(resources)
+        batch.warnings.each { Output.warning(context, it) }
+        batch.inspections
+      end
+
+      # Shared by the verbs that print one line per resource, so the name is neutralized whichever
+      # of them prints it.
+      def self.result_text(context, kind, name, verb_word, role, reason: nil, dry_run: false)
+        line = "#{kind.singular}/#{Output.plain(name)} #{context.paint(role, verb_word)}"
+        line = "#{line} (#{reason})" if reason
+        dry_run ? "#{line} #{context.paint(:dry_run, '(dry run)')}" : line
+      end
+
+      def initialize(factory)
+        @factory = factory
+      end
+
+      def call(context, args, opts)
+        runtime = @factory.call(context, opts)
+        run(runtime, context, args, opts)
+      end
+
+      # The resource types the verb acts on, the ones api-resources lists it under.
+      def kinds = []
+
+      private
+
+      def scope(runtime, context, opts) = Scope.new(runtime, context, opts)
+
+      def result_line(context, kind, name, verb_word, role, dry_run: false)
+        context.puts(Base.result_text(context, kind, name, verb_word, role, dry_run:))
+      end
+    end
+  end
+end

data/lib/slipway/commands/config.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../yaml'
+
+module Slipway
+  module Commands
+    module Config
+      DESCRIPTION = 'Inspect the configuration that slipway resolved from flags, environment variables and ' \
+                    'the configuration file.'
+      NOT_FOUND = ' (not found)'
+
+      def self.command(factory)
+        CLI::Command.new(
+          name: 'config', summary: 'Inspect the configuration in effect', section: 'Settings Commands',
+          description: DESCRIPTION, subcommands: [View.command(factory), Path.command(factory)]
+        )
+      end
+
+      class View < Base
+        DESCRIPTION = "Display the configuration in effect.\n\n" \
+                      'Prints every setting as YAML after applying the precedence flag, then SLIPWAY_* ' \
+                      'environment variable, then configuration file, then built-in default. The first line ' \
+                      'names the configuration file that was consulted, and says (not found) when the default ' \
+                      'file does not exist. A file named by --config or SLIPWAY_CONFIG must exist.'
+
+        def self.command(factory)
+          CLI::Command.new(
+            name: 'view', summary: 'Display the configuration in effect', description: DESCRIPTION,
+            examples: [
+              CLI::Example.new(comment: 'Show the settings in effect', command: 'config view'),
+              CLI::Example.new(comment: 'Show the settings another file would give',
+                               command: 'config view --config ~/work/slipway.yaml')
+            ],
+            handler: new(factory)
+          )
+        end
+
+        def run(runtime, context, _args, _opts)
+          settings = runtime.settings
+          comment = "# #{settings.path}"
+          comment += NOT_FOUND unless settings.exists?
+          context.puts(context.paint(:muted, comment))
+          context.print(Yaml.dump(settings.to_h))
+        end
+      end
+
+      class Path < Base
+        DESCRIPTION = "Display the path of the configuration file.\n\n" \
+                      'Prints the file that slipway reads: --config, then SLIPWAY_CONFIG, then ' \
+                      '$XDG_CONFIG_HOME/slipway/config.yaml. When the default file does not exist, its path is ' \
+                      'still printed and a note on stderr says so; a file named by --config or SLIPWAY_CONFIG ' \
+                      'must exist.'
+        MISSING = 'The file does not exist; slipway uses its defaults.'
+
+        def self.command(factory)
+          CLI::Command.new(
+            name: 'path', summary: 'Display the path of the configuration file', description: DESCRIPTION,
+            examples: [CLI::Example.new(comment: 'Print the path of the configuration file', command: 'config path')],
+            handler: new(factory)
+          )
+        end
+
+        # stdout stays the bare path so "$(slipway config path)" can open the file before it exists.
+        def run(runtime, context, _args, _opts)
+          settings = runtime.settings
+          context.puts(settings.path)
+          context.warn(context.paint_err(:muted, MISSING)) unless settings.exists?
+        end
+      end
+    end
+  end
+end

data/lib/slipway/commands/create.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'from_dir'
+require_relative '../git/branch_name'
+require_relative '../git/url'
+require_relative '../labels'
+require_relative '../scanner'
+require_relative '../store'
+
+module Slipway
+  module Commands
+    class Create < Base
+      DESCRIPTION = "Create a resource by name.\n\n" \
+                    'A project registers the git repository at --path in the current group, which must ' \
+                    'exist unless it is the default group. A group is created empty and holds the projects ' \
+                    "you register with --group later.\n\n" \
+                    'With --from-dir DIR in place of NAME, create project registers every git repository at DIR ' \
+                    'or under it, down to --depth levels. Each project is named after its directory, lowercased ' \
+                    'with each run of characters other than ASCII letters, digits and dashes made one dash, and ' \
+                    'records its path and the URL of its origin without any credentials; the checked-out branch ' \
+                    'is not recorded. A path the group already holds is reported unchanged, so running it again ' \
+                    "adds only new clones.\n\n" \
+                    'Use --dry-run to check the arguments without writing anything, and -o yaml with it ' \
+                    "to print the manifest instead, ready for apply -f.\n\n" \
+                    "#{Options::TYPES_SENTENCE}".freeze
+      PATH_MISSING = 'required flag(s) "--path" not set'
+      PATH_EMPTY = 'flag --path must not be empty'
+      PROJECT_ONLY = 'flag --%s applies to projects only'
+      PROJECT_FLAGS = %i[path remote branch].freeze
+      EITHER = 'give either NAME or --from-dir, not both'
+      NOT_WITH_FROM_DIR = 'flag --%s cannot be used with --from-dir'
+      FROM_DIR_EXCLUSIVE = %i[path description remote branch].freeze
+      FROM_DIR_EMPTY = 'flag --from-dir must not be empty'
+      DEPTHS = 1..Scanner::MAX_DEPTH
+      DEPTH_INVALID = "invalid argument %p for --depth: must be an integer from #{DEPTHS.min} to #{DEPTHS.max}".freeze
+      DEPTH_WITHOUT_FROM_DIR = 'flag --depth requires --from-dir'
+      USAGE = '(TYPE NAME | project --from-dir DIR)'
+
+      # The resource as written, or as it would be on a dry run, and the word and role of its result line.
+      Result = Data.define(:resource, :word, :role)
+
+      PATH = CLI::Option.new(long: 'path', argument: 'DIR',
+                             description: 'Directory of the git repository to register; required for a project ' \
+                                          'given by NAME. ' \
+                                          'A relative directory is stored resolved against the current ' \
+                                          'directory, a ~ path as written.')
+      TEXT = CLI::Option.new(long: 'description', argument: 'TEXT',
+                             description: 'A short description of the resource.')
+      LABEL = CLI::Option.new(long: 'label', argument: 'KEY=VALUE', repeatable: true,
+                              description: 'A label to set on the new resource; may be repeated.')
+      REMOTE = CLI::Option.new(long: 'remote', argument: 'URL',
+                               description: 'The URL the origin remote is expected to have, written to spec.remote. ' \
+                                            'A URL that embeds credentials is refused; use a credential helper.')
+      BRANCH = CLI::Option.new(long: 'branch', argument: 'NAME',
+                               description: 'The branch the project is expected to have checked out, written to ' \
+                                            'spec.branch.')
+      FROM_DIR = CLI::Option.new(long: 'from-dir', argument: 'DIR',
+                                 completer: ->(_given, _current) { CLI::Completer::FILES },
+                                 description: 'Register every git repository at or under DIR as a project, in ' \
+                                              'place of NAME.')
+      # No option default: one would hide whether --depth was typed without --from-dir.
+      DEPTH = CLI::Option.new(long: 'depth', argument: 'N',
+                              description: "How many directory levels under --from-dir to search, from #{DEPTHS.min} " \
+                                           "to #{DEPTHS.max}. The search stops at a repository and never follows " \
+                                           "a symbolic link under --from-dir. (default #{Scanner::DEFAULT_DEPTH})")
+      OUTPUT = CLI::Option.new(long: 'output', short: 'o', argument: 'FORMAT',
+                               enum: [*Output::Serializer::STRUCTURED, Output::NAME],
+                               description: 'Output format; without it, each resource prints a result line such as ' \
+                                            'project/hldr created.')
+
+      def self.command(factory)
+        CLI::Command.new(
+          name: 'create', summary: 'Create a resource by name', section: 'Basic Commands',
+          description: DESCRIPTION, examples:, usage: USAGE,
+          positionals: [Options::TYPE, Options.name_positional(factory, variadic: false, required: false)],
+          options: [PATH, TEXT, LABEL, REMOTE, BRANCH, FROM_DIR, DEPTH, Options::DRY_RUN, OUTPUT],
+          handler: new(factory)
+        )
+      end
+
+      def self.examples = named_examples + directory_examples
+
+      def self.named_examples
+        [
+          CLI::Example.new(comment: 'Register the repository at ~/dev/hldr as a project in the current group',
+                           command: "create project hldr --path '~/dev/hldr'"),
+          CLI::Example.new(comment: 'Register a project in the work group with two labels',
+                           command: "create project api --path '~/work/api' -n work --label lang=go --label tier=api"),
+          CLI::Example.new(comment: 'Register a project with the remote and the branch it is expected to have',
+                           command: "create project hldr --path '~/dev/hldr' " \
+                                    '--remote git@github.com:hvpaiva/hldr.git --branch main'),
+          CLI::Example.new(comment: 'Create a group with a description',
+                           command: 'create group work --description "Projects for the day job"'),
+          CLI::Example.new(comment: 'Check the arguments without writing the project',
+                           command: "create project hldr --path '~/dev/hldr' --dry-run"),
+          CLI::Example.new(comment: 'Print the manifest of a project without registering it',
+                           command: "create project hldr --path '~/dev/hldr' --dry-run -o yaml")
+        ]
+      end
+
+      def self.directory_examples
+        [
+          CLI::Example.new(comment: 'Register every repository in ~/dev/personal in the personal group',
+                           command: 'create project --from-dir ~/dev/personal -n personal'),
+          CLI::Example.new(comment: 'Write the manifests of the repositories two levels under ~/work to a file',
+                           command: 'create project --from-dir ~/work --depth 2 --dry-run -o yaml > work.yaml')
+        ]
+      end
+      private_class_method :examples, :named_examples, :directory_examples
+
+      def kinds = Resources::KINDS
+
+      def run(runtime, context, args, opts)
+        scope = scope(runtime, context, opts)
+        kind, names = scope.targets(args)
+        return register_directory(runtime, context, scope, opts) if from_dir?(kind, names, opts)
+        raise CLI::UsageError, DEPTH_WITHOUT_FROM_DIR unless opts[:depth].nil?
+
+        _, name = scope.target(args)
+        resource = build(kind, name, scope.group, opts)
+        resource = dry_run?(opts) ? check(runtime.store, kind, resource) : runtime.store.create(resource)
+        report(context, kind, [Result.new(resource, 'created', :create_created)], opts, single: true)
+      end
+
+      private
+
+      def dry_run?(opts) = opts[:dry_run] == true
+
+      # NAME and --from-dir are the two ways to say which project to register; a group has only NAME.
+      def from_dir?(kind, names, opts)
+        return false if opts[:from_dir].nil?
+        raise CLI::UsageError, format(PROJECT_ONLY, 'from-dir') unless kind.namespaced?
+        raise CLI::UsageError, EITHER unless names.empty?
+
+        true
+      end
+
+      def register_directory(runtime, context, scope, opts)
+        check_directory_flags(opts)
+        labels = Labels.parse_pairs(opts[:label] || [])
+        registrar = FromDir.new(runtime, context, group: scope.group, labels:, dry_run: dry_run?(opts))
+        entries = registrar.register(opts[:from_dir], depth: depth(opts[:depth] || Scanner::DEFAULT_DEPTH))
+        report(context, Resources::PROJECTS, entries.map { result_of(it) }, opts, single: false)
+        raise Error.new(problems: registrar.problems) unless registrar.problems.empty?
+      end
+
+      def check_directory_flags(opts)
+        flag = FROM_DIR_EXCLUSIVE.find { !opts[it].nil? }
+        raise CLI::UsageError, format(NOT_WITH_FROM_DIR, flag) if flag
+        raise CLI::UsageError, FROM_DIR_EMPTY if opts[:from_dir].strip.empty?
+      end
+
+      def depth(value)
+        depth = Integer(value.to_s, 10, exception: false)
+        DEPTHS.cover?(depth) ? depth : raise(CLI::UsageError, format(DEPTH_INVALID, value.to_s))
+      end
+
+      def result_of(entry)
+        if entry.created then Result.new(entry.project, 'created', :create_created)
+        else Result.new(entry.project, 'unchanged', :apply_unchanged)
+        end
+      end
+
+      def report(context, kind, results, opts, single:)
+        dry_run = dry_run?(opts)
+        case opts[:output]
+        when nil then results.each { result_line(context, kind, it.resource.name, it.word, it.role, dry_run:) }
+        when Output::NAME then results.each { context.puts("#{kind.singular}/#{it.resource.name}") }
+        else context.print(Output::Serializer.render(opts[:output], results.map { it.resource.to_manifest }, single:))
+        end
+      end
+
+      def build(kind, name, group, opts)
+        labels = Labels.parse_pairs(opts[:label] || [])
+        return project(name, group, labels, opts) if kind.namespaced?
+
+        flag = PROJECT_FLAGS.find { !opts[it].nil? }
+        raise CLI::UsageError, format(PROJECT_ONLY, flag) if flag
+
+        Group.new(name:, labels:, description: opts[:description])
+      end
+
+      def project(name, group, labels, opts)
+        Project.new(name:, group:, labels:, path: project_path(opts[:path]), description: opts[:description],
+                    remote: opts[:remote] && usage { Git::Url.validate!(opts[:remote], field: 'flag --remote') },
+                    branch: opts[:branch] && usage { Git::BranchName.validate!(opts[:branch]) })
+      end
+
+      # A manifest has no working directory, so a relative --path is resolved here, against
+      # the directory the command was typed in; a ~ path stays portable as written.
+      def project_path(path)
+        raise CLI::UsageError, PATH_MISSING if path.nil?
+        raise CLI::UsageError, PATH_EMPTY if path.strip.empty?
+        return path if path.start_with?('~') || File.absolute_path?(path)
+
+        File.absolute_path(path)
+      end
+
+      # The checks a manifest's spec.remote and spec.branch pass, so a refusal reads the same; typed on
+      # the command line, it is a usage error.
+      def usage
+        yield
+      rescue Git::Url::Invalid, Git::BranchName::Invalid => e
+        raise CLI::UsageError, e.message
+      end
+
+      # What a real create would reject before writing.
+      def check(store, kind, resource)
+        if kind.namespaced? && !store.group_available?(resource.group)
+          raise Store::NotFound.of(Resources::GROUPS, resource.group)
+        end
+
+        resource
+      end
+    end
+  end
+end

data/lib/slipway/commands/delete.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../store'
+
+module Slipway
+  module Commands
+    class Delete < Base
+      DESCRIPTION = "Delete resources by type and name.\n\n" \
+                    'Every name is resolved before anything is deleted, so a name that does not exist leaves ' \
+                    'the others untouched unless --ignore-not-found is set. Deleting a group also deletes the ' \
+                    "registrations of its projects; the default group cannot be deleted.\n\n" \
+                    "Deleting a project removes its registration only. The repository on disk is not touched.\n\n" \
+                    "#{Options::TYPES_SENTENCE}".freeze
+      USAGE = '(TYPE NAME... | TYPE/NAME...)'
+      NO_NAMES = 'resource(s) were provided, but no name was specified'
+
+      IGNORE_NOT_FOUND = CLI::Option.new(long: 'ignore-not-found',
+                                         description: 'Treat "resource not found" as a successful delete.')
+
+      def self.command(factory)
+        CLI::Command.new(
+          name: 'delete', summary: 'Delete resources by type and name', section: 'Basic Commands',
+          description: DESCRIPTION, examples:, usage: USAGE,
+          positionals: [Options::TYPE, Options.name_positional(factory, variadic: true, required: false)],
+          options: [Options::DRY_RUN, IGNORE_NOT_FOUND],
+          handler: new(factory)
+        )
+      end
+
+      def self.examples
+        [
+          CLI::Example.new(comment: 'Delete a project from the current group', command: 'delete project hldr'),
+          CLI::Example.new(comment: 'Delete two projects from the work group',
+                           command: 'delete projects api web -n work'),
+          CLI::Example.new(comment: 'Delete a group and the registrations of its projects',
+                           command: 'delete group work'),
+          CLI::Example.new(comment: 'Delete a project if it exists, quietly otherwise',
+                           command: 'delete project hldr --ignore-not-found')
+        ]
+      end
+      private_class_method :examples
+
+      def kinds = Resources::KINDS
+
+      def run(runtime, context, args, opts)
+        scope = scope(runtime, context, opts)
+        kind, names = scope.targets(args)
+        raise CLI::UsageError, NO_NAMES if names.empty?
+
+        group = kind.namespaced? ? scope.group : nil
+        dry_run = opts[:dry_run] == true
+        resolve(runtime.store, kind, names.uniq, group, ignore: opts[:ignore_not_found] == true).each do |resource|
+          runtime.store.delete(kind, resource.name, group:) unless dry_run
+          context.puts(line(context, kind, resource, dry_run:))
+        end
+      end
+
+      private
+
+      # Runs before anything is removed, so one bad name deletes nothing.
+      def resolve(store, kind, names, group, ignore:)
+        names.filter_map do |name|
+          raise Error, Store::PROTECTED_GROUP if !kind.namespaced? && name == Store::DEFAULT_GROUP
+
+          store.find(kind, name, group:)
+        rescue Store::NotFound
+          raise unless ignore
+
+          nil
+        end
+      end
+
+      def line(context, kind, resource, dry_run:)
+        parts = ["#{kind.singular} #{resource.name.inspect}", context.paint(:delete_deleted, 'deleted')]
+        parts << "from #{resource.group} group" if kind.namespaced?
+        parts << context.paint(:dry_run, '(dry run)') if dry_run
+        parts.join(' ')
+      end
+    end
+  end
+end

data/lib/slipway/commands/describe.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../views'
+
+module Slipway
+  module Commands
+    class Describe < Base
+      DESCRIPTION = "Show details of one or many resources.\n\n" \
+                    'Print a detailed description of the selected resources, including the state of the ' \
+                    'repository at the registered path and where it differs from the manifest. You may select ' \
+                    "a single object by name, all objects of that type, or use a label or field selector.\n\n" \
+                    'Status is one of the words listed below. Last Fetch reads ' \
+                    "#{Views::Project::NEVER} when git answered and no fetch is on record, and a field with no " \
+                    "value reads #{Output::Describe::NONE}. When git cannot read the repository, the Repository " \
+                    "block holds git's reason instead of the fields.\n\n" \
+                    "#{Options::TYPES_SENTENCE}".freeze
+
+      def self.command(factory)
+        CLI::Command.new(
+          name: 'describe', summary: 'Show details of one or many resources',
+          section: 'Basic Commands', description: DESCRIPTION, examples:, usage: Get::USAGE,
+          glossaries: [Get::STATUS_WORDS],
+          positionals: [Options::TYPE, Options.name_positional(factory, variadic: true, required: false)],
+          options: [Options::SELECTOR, Options::FIELD_SELECTOR, Options::ALL_GROUPS],
+          handler: new(factory)
+        )
+      end
+
+      def self.examples
+        [
+          CLI::Example.new(comment: 'Describe a project', command: 'describe project hldr'),
+          CLI::Example.new(comment: 'Describe every project in the work group', command: 'describe projects -n work'),
+          CLI::Example.new(comment: 'Describe the projects labeled lang=rust',
+                           command: 'describe projects -l lang=rust'),
+          CLI::Example.new(comment: 'Describe the projects on the main branch',
+                           command: 'describe projects --field-selector status.branch=main'),
+          CLI::Example.new(comment: 'Describe a group', command: 'describe group work')
+        ]
+      end
+      private_class_method :examples
+
+      def kinds = Resources::KINDS
+
+      def run(runtime, context, args, opts)
+        scope = scope(runtime, context, opts)
+        kind, names = scope.targets(args)
+        fields = scope.field_selector(kind, names)
+        scope.select(kind, names) do |resources|
+          blocks = kind.namespaced? ? projects(runtime, context, resources, fields) : groups(runtime, resources, fields)
+          next scope.report_none(kind) if blocks.empty?
+
+          renderer = Output::Describe.new(context)
+          context.print(blocks.map { renderer.render(it) }.join("\n"))
+        end
+      end
+
+      private
+
+      def projects(runtime, context, resources, fields)
+        inspections = fields.filter(Base.examine(runtime, context, resources)) { Views::Project.object(it) }
+        now = runtime.clock.call
+        inspections.map { Views::Project.describe(it, now:) }
+      end
+
+      def groups(runtime, groups, fields)
+        now = runtime.clock.call
+        counted = groups.map { [it, runtime.store.project_count(it.name)] }
+        fields.filter(counted) { |group, count| Views::Group.object(group, count:) }
+              .map { |group, count| Views::Group.describe(group, count:, now:) }
+      end
+    end
+  end
+end