hecks 3.5.0 → 3.6.0

data/lib/hecks/cli/project_cli/launcher_source.rb

@@ -0,0 +1,177 @@
+require_relative "../../naming"
+require_relative "templates"
+
+module Hecks
+  module CLI
+    module ProjectCli
+      # The source of one launcher, built from `Templates`. `ProjectCli` extends it.
+      module LauncherSource
+        include Templates
+
+        # What a chapter name, a domain path and a launcher command may be made of.
+        NAME = /\A[A-Za-z][A-Za-z0-9_ ]*\z/
+        PATH = %r{\A[\w./-]+\z}
+        VERB = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+
+        # Set first in an opted-in launcher, before anything reads a file.
+        ENCODING = "Encoding.default_external = Encoding::UTF_8\nEncoding.default_internal = Encoding::UTF_8\n\n".freeze
+
+        # How every launcher ends.
+        PLAIN_ENDING = "status.zero? ? puts(text) : abort(text)".freeze
+
+        # How an opted-in launcher ends: a failed `--wait` run still prints its settled record.
+        OPTED_ENDING = <<~LAUNCHER_TAIL.chomp.freeze
+          # A `--wait` run that failed answers its settled record on stdout, so `| jq` reads it
+          # either way, and says why on stderr.
+          if reason
+            puts text
+            warn reason
+            exit status
+          end
+          status.zero? ? puts(text) : abort(text)
+        LAUNCHER_TAIL
+
+        # What a Memory command does when refused: say why, from the record's `refusal`.
+        MEMORY_REFUSAL = <<~'LAUNCHER_REFUSAL'.gsub(/^/, "  ").freeze
+          if MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))
+            why = begin
+              require "json"
+              JSON.parse(text).dig("state", "refusal", "value")
+            rescue JSON::ParserError
+              nil
+            end
+            warn(why ? why.sub(/\A(\w+::)+\w+: /, "") : reason)
+          else
+            puts text
+            warn reason
+          end
+        LAUNCHER_REFUSAL
+
+        # The generator's name as an executable launcher's header states it, whoever ran it.
+        GENERATOR = "hecks project_cli".freeze
+
+        # The launcher's test for a Memory command; a trailing `!` is not part of the name.
+        RUNS_ON_MEMORY = 'MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))'.freeze
+
+        # Where a launcher sits: the path up to the root, how it finds its domain, the program
+        # name its header states, the path its usage shows, and the name it runs under.
+        Site = Struct.new(:up, :boot, :program, :where, :shown)
+
+        # The source of one launcher; names and paths go in as they are, so each must be plain.
+        # An `opted` one also sets UTF-8 and prints a failed `--wait` record on stdout. An
+        # executable's program name is its file's basename, and its header names the generator.
+        # @param path [String] the domain's directory under the root
+        # @param name [String] the chapter's name
+        # @param program [String] the generator's invocation, named in the header
+        # @param executable [String, nil] the file's path under the root when not beside the domain
+        # @param legacy [Array<String>, nil] commands an executable hands to `Hecks::CLI` first
+        # @param memory_commands [Array<String>, nil] commands that default to Memory
+        # @param opted [Boolean] whether the chapter's world declares a `launcher` setting
+        # @return [String] the Ruby source
+        # @raise [ArgumentError] if a name, path, executable or legacy command is not plain
+        def launcher(path, name, program, executable: nil, legacy: nil, memory_commands: nil, opted: !executable.nil?) # rubocop:disable Metrics/ParameterLists -- the generator's documented signature
+          plain!("chapter name", name, NAME)
+          plain!("domain path", path, PATH)
+          site = executable ? executable_site(path, executable) : plain_site(path, name, program)
+          quiet = !Array(memory_commands).empty?
+
+          render(LAUNCHER, name: name, program: site.program, where: site.where, up: site.up,
+                           encoding: opted ? ENCODING : "", handoff: handoff_for(executable, legacy, memory_commands),
+                           ending: ending_for(opted, executable && quiet),
+                           entry: entry(name, site.boot, site.shown, opted, quiet: quiet))
+        end
+
+        # @api private
+        # @return [String] what an executable launcher does before it boots, or nothing
+        def handoff_for(executable, legacy, memory_commands)
+          return "" unless executable
+
+          legacy_handoff(Array(legacy)) + memory_default(Array(memory_commands))
+        end
+
+        # @api private
+        # @return [String] the launcher's closing lines; quiet when a memory command is listed
+        def ending_for(opted, quiet)
+          ending = opted ? OPTED_ENDING : PLAIN_ENDING
+          quiet ? quiet_ending(ending) : ending
+        end
+
+        # @api private
+        # @return [Site] where an executable launcher sits, named by its path under the root
+        def executable_site(path, executable)
+          plain!("launcher executable", executable, PATH)
+          if executable.split("/").include?("..")
+            raise ArgumentError, "launcher executable #{executable.inspect} must stay inside the root"
+          end
+
+          up = "../" * File.dirname(executable).split("/").count { |part| part != "." }
+          Site.new(up, %(File.expand_path("#{up}#{path}", __dir__)), GENERATOR, executable, File.basename(executable))
+        end
+
+        # @api private
+        # @return [Site] where a launcher sits beside its domain, named after its chapter
+        def plain_site(path, name, program)
+          where = "#{path}/#{Naming.snake(name)}"
+          Site.new("../" * path.count("/").succ, "__dir__", program, where, where)
+        end
+
+        # @api private
+        # @return [String] the launcher's middle: for an opted-in launcher, usage answered from the
+        #   projection and a boot only for a line that runs a command; for any other, the boot and
+        #   dispatch every launcher has always had, byte for byte
+        def entry(name, boot, shown, opted, quiet: false)
+          opted ? described_entry(name, boot, shown, quiet: quiet) : plain_entry(name, boot, shown)
+        end
+
+        # @api private
+        # @return [String] the opted-in launcher's middle
+        def described_entry(name, boot, shown, quiet: false)
+          started = "Hecks.boot_described(described, install_doors: false)"
+          started = "Hecks::Doors::LauncherOptions.quietly(hold: #{RUNS_ON_MEMORY}) { #{started} }" if quiet
+          render(DESCRIBED_ENTRY, boot: boot, shown: shown, name: name, started: started).chomp
+        end
+
+        # @api private
+        # @return [String] the middle every launcher had before opted-in ones answered usage alone
+        def plain_entry(name, boot, shown)
+          render(PLAIN_ENTRY, boot: boot, shown: shown, name: name).chomp
+        end
+
+        # @api private
+        def plain!(what, value, pattern)
+          return if value.to_s.match?(pattern)
+
+          raise ArgumentError, "#{what} #{value.to_s.inspect} is not a plain word or path"
+        end
+
+        # @api private
+        # @param ending [String] the launcher's closing lines
+        # @return [String] the same lines, except that a memory command prints no settled record,
+        #   only the reason it was refused: a person is at it, so the record is noise
+        def quiet_ending(ending)
+          ending.sub("  puts text\n  warn reason\n", MEMORY_REFUSAL)
+                .sub("status.zero? ? puts(text)",
+                     "exit 0 if status.zero? && #{RUNS_ON_MEMORY}\nstatus.zero? ? puts(text)")
+        end
+
+        # @api private
+        # @return [String] the lines that default the listed commands to Memory, or nothing
+        def memory_default(commands)
+          return "" if commands.empty?
+
+          commands.each { |command| plain!("memory command", command, VERB) }
+          render(MEMORY_DEFAULT, commands: commands.join(" "))
+        end
+
+        # @api private
+        # @return [String] the lines that hand the legacy commands to `Hecks::CLI`, or nothing
+        def legacy_handoff(legacy)
+          return "" if legacy.empty?
+
+          legacy.each { |command| plain!("legacy command", command, VERB) }
+          render(LEGACY_HANDOFF, commands: legacy.join(" "))
+        end
+      end
+    end
+  end
+end

data/lib/hecks/cli/project_cli/templates.rb

@@ -0,0 +1,106 @@
+module Hecks
+  module CLI
+    module ProjectCli
+      # The text of a launcher, as templates: each `{{name}}` is filled in by `render`.
+      module Templates
+        # The whole launcher: its header, the load path, the hand-offs, the entry and the ending.
+        LAUNCHER = <<~RUBY.freeze
+          #!/usr/bin/env ruby
+
+          # {{name}}'s command line — GENERATED by {{program}}. Do not edit.
+          #
+          # A launcher, not a CLI: the commands, their arguments and their refusals are
+          # projected from the bluebook beside it every time this runs, so a change
+          # to the chapter shows up here without re-minting anything.
+          #
+          #   {{where}}                  every command, and every question
+          #   {{where}} <command> --help    what it wants, and how it refuses
+
+          {{encoding}}$LOAD_PATH.unshift File.expand_path("{{up}}lib", __dir__)
+          {{handoff}}
+          require "hecks"
+
+          {{entry}}
+          {{ending}}
+        RUBY
+
+        # An opted-in launcher's middle: usage answered from the projection, a boot only for a
+        # line that runs a command.
+        DESCRIBED_ENTRY = <<~'RUBY'.freeze
+          # Usage is answered from the projected chapter alone: no adapter is bound and no
+          # database is opened. Only a line that runs a command boots the domain,
+          # and it boots from what the usage check already loaded.
+          domain = {{boot}}
+          program = "{{shown}}"
+          described = begin
+            Hecks.describe(domain)
+          rescue StandardError => e
+            abort "cannot open {{name}}: #{e.message.lines.first.strip}"
+          end
+
+          text, status, reason = Hecks::Doors::CliRunner.usage(
+            runtime: described, argv: ARGV, program: program
+          )
+          unless text
+            runtime = begin
+              {{started}}
+            rescue StandardError => e
+              abort "cannot open {{name}}: #{e.message.lines.first.strip}"
+            end
+            # A question the world lists under `streams`, given `--stream`, tails until interrupted.
+            streamed = Hecks::Doors::CliRunner.stream(runtime: runtime, argv: ARGV, program: program)
+            exit streamed unless streamed.nil?
+            text, status, reason = Hecks::Doors::CliRunner.call(
+              runtime: runtime, argv: ARGV, program: program
+            )
+          end
+        RUBY
+
+        # The middle every launcher had before opted-in ones answered usage alone.
+        PLAIN_ENTRY = <<~'RUBY'.freeze
+          runtime = begin
+            Hecks.boot({{boot}}, install_doors: false)
+          rescue StandardError => e
+            abort "cannot open {{name}}: #{e.message.lines.first.strip}"
+          end
+
+          text, status = Hecks::Doors::CliRunner.call(
+            runtime: runtime, argv: ARGV, program: "{{shown}}"
+          )
+        RUBY
+
+        # The lines that default listed commands to Memory.
+        MEMORY_DEFAULT = <<~RUBY.freeze
+
+          # These commands keep nothing worth a database, so they run on Memory unless told otherwise.
+          # A person is at them: they wait for their result, say why when they are refused, and print
+          # no record when they end well.
+          MEMORY_COMMANDS = %w[{{commands}}].freeze
+          ENV["HECKS_ENVIRONMENT"] ||= "memory" if MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))
+          ARGV << "--wait" if MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!")) && !ARGV.include?("--wait")
+        RUBY
+
+        # The lines that hand the legacy commands to `Hecks::CLI`.
+        LEGACY_HANDOFF = <<~RUBY.freeze
+
+          # The names the gem has always shipped keep their positional forms.
+          LEGACY = %w[{{commands}}].freeze
+          if LEGACY.include?(ARGV.first)
+            require "hecks/cli"
+            exit Hecks::CLI.start(ARGV) unless Hecks::CLI.launcher_form?(ARGV)
+          end
+        RUBY
+
+        # Fills a template's `{{name}}` placeholders.
+        #
+        # @param template [String] the template text
+        # @param values [Hash{Symbol => String}] each placeholder's value
+        # @return [String] the text with every placeholder replaced
+        # @raise [KeyError] if the template names a placeholder `values` lacks
+        def render(template, values)
+          template.gsub(/\{\{(\w+)\}\}/) { values.fetch(Regexp.last_match(1).to_sym) }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/cli/project_cli.rb

@@ -1,5 +1,6 @@
 require "fileutils"
 require_relative "../../hecks"
+require_relative "project_cli/launcher_source"
 
 module Hecks
   module CLI
@@ -17,50 +18,11 @@ module Hecks
       # Build output and other trees under a root that hold no domain a caller means.
       IGNORED = %r{\A(rust|deploy|tmp|coverage)/}
 
-      # What a chapter name, a domain path and a launcher command may be made of.
-      NAME = /\A[A-Za-z][A-Za-z0-9_ ]*\z/
-      PATH = %r{\A[\w./-]+\z}
-      VERB = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+      # One launcher to write: its chapter's name, its label under the root, its file, its text,
+      # the snake-cased name and the executable path its chapter's world named (nil when none).
+      Target = Struct.new(:name, :label, :file, :text, :snake, :executable)
 
-      # Set first in an opted-in launcher, before anything reads a file.
-      ENCODING = "Encoding.default_external = Encoding::UTF_8\nEncoding.default_internal = Encoding::UTF_8\n\n".freeze
-
-      # How every launcher ends.
-      PLAIN_ENDING = "status.zero? ? puts(text) : abort(text)".freeze
-
-      # How an opted-in launcher ends: a failed `--wait` run still prints its settled record.
-      OPTED_ENDING = <<~LAUNCHER_TAIL.chomp.freeze
-        # A `--wait` run that failed answers its settled record on stdout, so `| jq` reads it
-        # either way, and says why on stderr.
-        if reason
-          puts text
-          warn reason
-          exit status
-        end
-        status.zero? ? puts(text) : abort(text)
-      LAUNCHER_TAIL
-
-      # What a Memory command does when refused: say why, from the record's `refusal`.
-      MEMORY_REFUSAL = <<~'LAUNCHER_REFUSAL'.gsub(/^/, "  ").freeze
-        if MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))
-          why = begin
-            require "json"
-            JSON.parse(text).dig("state", "refusal", "value")
-          rescue JSON::ParserError
-            nil
-          end
-          warn(why ? why.sub(/\A(\w+::)+\w+: /, "") : reason)
-        else
-          puts text
-          warn reason
-        end
-      LAUNCHER_REFUSAL
-
-      # The generator's name as an executable launcher's header states it, whoever ran it.
-      GENERATOR = "hecks project_cli".freeze
-
-      # The launcher's test for a Memory command; a trailing `!` is not part of the name.
-      RUNS_ON_MEMORY = 'MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))'.freeze
+      extend LauncherSource
 
       module_function
 
@@ -78,19 +40,31 @@ module Hecks
       #   path outside `root` or an unknown flag
       def call(argv, program:, root:, remove_stale_bin: true)
         flags, paths = argv.partition { |word| word.start_with?("-") }
-        unknown = flags - ["--check"]
-        abort "hecks project_cli: unknown option #{unknown.first} (the only option is --check)" unless unknown.empty?
+        refuse_unknown(flags)
 
         check  = flags.include?("--check")
         wanted = paths.empty? ? domains(root) : paths.map { |path| under_root(root, path) }
 
         outcomes = wanted.to_h { |path| [path, one(root, path, program, check, remove_stale_bin)] }
-        drifted  = outcomes.select { |_, outcome| outcome == :drifted }.keys
-        failed   = outcomes.select { |_, outcome| outcome == :failed }.keys
+        report(outcomes)
+      end
+
+      # @api private
+      def refuse_unknown(flags)
+        unknown = flags - ["--check"]
+        abort "hecks project_cli: unknown option #{unknown.first} (the only option is --check)" unless unknown.empty?
+      end
+
+      # Says which launchers drifted or could not be made, and exits 1 if any did.
+      #
+      # @api private
+      def report(outcomes)
+        drifted = outcomes.select { |_, outcome| outcome == :drifted }.keys
+        failed  = outcomes.select { |_, outcome| outcome == :failed }.keys
         return if drifted.empty? && failed.empty?
 
-        warn "launcher out of date for: #{drifted.join(', ')}; run `hecks project_cli #{drifted.join(' ')}`" unless drifted.empty?
-        warn "no launcher could be checked or written for: #{failed.join(', ')}" unless failed.empty?
+        warn "launcher out of date for: #{drifted.join(", ")}; run `hecks project_cli #{drifted.join(" ")}`" unless drifted.empty?
+        warn "no launcher could be checked or written for: #{failed.join(", ")}" unless failed.empty?
         exit 1
       end
 
@@ -116,26 +90,45 @@ module Hecks
       def one(root, path, program, check, remove_stale_bin)
         runtime = Hecks.boot(File.join(root, path), install_doors: false)
         name    = runtime.registry.bluebooks.keys.first or raise "it loads no bluebook"
-        setting    = Doors::LauncherOptions.settings(runtime, name) || {}
+        setting = Doors::LauncherOptions.settings(runtime, name) || {}
+        settle(launcher_target(name, path, setting, root, program), path, root, check, remove_stale_bin)
+      rescue StandardError, LoadError => e
+        refuse(path, "cannot boot — #{e.message.lines.first.to_s.strip}")
+      end
+
+      # Checks the launcher against its file, or writes it.
+      #
+      # @api private
+      # @return [Symbol] as `one` answers
+      def settle(target, path, root, check, remove_stale_bin)
+        return skip(path, "#{target.label} is a directory") if File.directory?(target.file)
+        return :drifted if check && !(File.file?(target.file) && File.read(target.file) == target.text)
+
+        write_launcher(target, root, remove_stale_bin) unless check
+        puts "  #{target.label}  ->  #{target.name}"
+        :current
+      end
+
+      # Works out where one launcher goes and what it says.
+      #
+      # @api private
+      # @return [Target]
+      def launcher_target(name, path, setting, root, program)
         snake      = Naming.snake(name)
         executable = setting[:executable]
         label      = executable || "#{path}/#{snake}"
-        file       = File.join(root, label)
         text       = launcher(path, name, program, executable: executable, legacy: setting[:legacy],
-                          memory_commands: setting[:memory_commands], opted: !setting.empty?)
-        return skip(path, "#{label} is a directory") if File.directory?(file)
-
-        return :drifted if check && !(File.file?(file) && File.read(file) == text)
+                                                   memory_commands: setting[:memory_commands], opted: !setting.empty?)
+        Target.new(name, label, File.join(root, label), text, snake, executable)
+      end
 
-        unless check
-          File.write(file, text)
-          FileUtils.chmod("+x", file)
-          FileUtils.rm_f(File.join(root, "bin", snake)) if remove_stale_bin && !executable
-        end
-        puts "  #{label}  ->  #{name}"
-        :current
-      rescue StandardError, LoadError => e
-        refuse(path, "cannot boot — #{e.message.lines.first.to_s.strip}")
+      # Writes the launcher, makes it executable, and removes the second front door in `bin/`.
+      #
+      # @api private
+      def write_launcher(target, root, remove_stale_bin)
+        File.write(target.file, target.text)
+        FileUtils.chmod("+x", target.file)
+        FileUtils.rm_f(File.join(root, "bin", target.snake)) if remove_stale_bin && !target.executable
       end
 
       # @api private
@@ -160,178 +153,6 @@ module Hecks
            .grep_v(IGNORED)
            .uniq.sort
       end
-
-      # The source of one launcher; names and paths go in as they are, so each must be plain.
-      # An `opted` one also sets UTF-8 and prints a failed `--wait` record on stdout.
-      # @param path [String] the domain's directory under the root
-      # @param name [String] the chapter's name
-      # @param program [String] the generator's invocation, named in the header
-      # @param executable [String, nil] the file's path under the root when it is not beside the
-      #   domain; its program name is then that file's basename, and its header names the generator
-      # @param legacy [Array<String>, nil] commands an executable hands to `Hecks::CLI` first
-      # @param memory_commands [Array<String>, nil] commands that default to Memory
-      # @param opted [Boolean] whether the chapter's world declares a `launcher` setting
-      # @return [String] the Ruby source
-      # @raise [ArgumentError] if a name, path, executable or legacy command is not plain
-      def launcher(path, name, program, executable: nil, legacy: nil, memory_commands: nil, opted: !executable.nil?)
-        plain!("chapter name", name, NAME)
-        plain!("domain path", path, PATH)
-        snake = Naming.snake(name)
-        if executable
-          plain!("launcher executable", executable, PATH)
-          if executable.split("/").include?("..")
-            raise ArgumentError, "launcher executable #{executable.inspect} must stay inside the root"
-          end
-
-          up      = "../" * File.dirname(executable).split("/").reject { |part| part == "." }.length
-          boot    = %(File.expand_path("#{up}#{path}", __dir__))
-          program = GENERATOR
-          where   = executable
-          shown   = File.basename(executable)
-        else
-          up    = "../" * path.count("/").succ
-          boot  = "__dir__"
-          where = shown = "#{path}/#{snake}"
-        end
-
-        handoff  = legacy_handoff(Array(legacy)) + memory_default(Array(memory_commands)) if executable
-        encoding = opted ? ENCODING : ""
-        ending   = opted ? OPTED_ENDING : PLAIN_ENDING
-        ending   = quiet_ending(ending) if executable && !Array(memory_commands).empty?
-
-        <<~RUBY
-          #!/usr/bin/env ruby
-
-          # #{name}'s command line — GENERATED by #{program}. Do not edit.
-          #
-          # A launcher, not a CLI: the commands, their arguments and their refusals are
-          # projected from the bluebook beside it every time this runs, so a change
-          # to the chapter shows up here without re-minting anything.
-          #
-          #   #{where}                  every command, and every question
-          #   #{where} <command> --help    what it wants, and how it refuses
-
-          #{encoding}$LOAD_PATH.unshift File.expand_path("#{up}lib", __dir__)
-          #{handoff}
-          require "hecks"
-
-          #{entry(name, boot, shown, opted, quiet: !Array(memory_commands).empty?)}
-          #{ending}
-        RUBY
-      end
-
-      # @api private
-      # @return [String] the launcher's middle: for an opted-in launcher, usage answered from the
-      #   projection and a boot only for a line that runs a command; for any other, the boot and
-      #   dispatch every launcher has always had, byte for byte
-      def entry(name, boot, shown, opted, quiet: false)
-        opted ? described_entry(name, boot, shown, quiet: quiet) : plain_entry(name, boot, shown)
-      end
-
-      # @api private
-      # @return [String] the opted-in launcher's middle
-      def described_entry(name, boot, shown, quiet: false)
-        started = "Hecks.boot_described(described, install_doors: false)"
-        started = "Hecks::Doors::LauncherOptions.quietly(hold: #{RUNS_ON_MEMORY}) { #{started} }" if quiet
-        <<~RUBY.chomp
-          # Usage is answered from the projected chapter alone: no adapter is bound and no
-          # database is opened. Only a line that runs a command boots the domain,
-          # and it boots from what the usage check already loaded.
-          domain = #{boot}
-          program = "#{shown}"
-          described = begin
-            Hecks.describe(domain)
-          rescue StandardError => e
-            abort "cannot open #{name}: \#{e.message.lines.first.strip}"
-          end
-
-          text, status, reason = Hecks::Doors::CliRunner.usage(
-            runtime: described, argv: ARGV, program: program
-          )
-          unless text
-            runtime = begin
-              #{started}
-            rescue StandardError => e
-              abort "cannot open #{name}: \#{e.message.lines.first.strip}"
-            end
-            # A question the world lists under `streams`, given `--stream`, tails until interrupted.
-            streamed = Hecks::Doors::CliRunner.stream(runtime: runtime, argv: ARGV, program: program)
-            exit streamed unless streamed.nil?
-            text, status, reason = Hecks::Doors::CliRunner.call(
-              runtime: runtime, argv: ARGV, program: program
-            )
-          end
-        RUBY
-      end
-
-      # @api private
-      # @return [String] the middle every launcher had before opted-in ones answered usage alone
-      def plain_entry(name, boot, shown)
-        <<~RUBY.chomp
-          runtime = begin
-            Hecks.boot(#{boot}, install_doors: false)
-          rescue StandardError => e
-            abort "cannot open #{name}: \#{e.message.lines.first.strip}"
-          end
-
-          text, status = Hecks::Doors::CliRunner.call(
-            runtime: runtime, argv: ARGV, program: "#{shown}"
-          )
-        RUBY
-      end
-
-      # @api private
-      def plain!(what, value, pattern)
-        return if value.to_s.match?(pattern)
-
-        raise ArgumentError, "#{what} #{value.to_s.inspect} is not a plain word or path"
-      end
-
-      # @api private
-      # @param ending [String] the launcher's closing lines
-      # @return [String] the same lines, except that a memory command prints no settled record, only
-      #   the reason it was refused: a person is at it, so the record is noise
-      def quiet_ending(ending)
-        ending.sub("  puts text\n  warn reason\n", MEMORY_REFUSAL)
-              .sub("status.zero? ? puts(text)",
-                   "exit 0 if status.zero? && MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp(\"!\"))\nstatus.zero? ? puts(text)")
-      end
-
-      # @api private
-      # @return [String] the lines that default the listed commands to Memory, or nothing
-      def memory_default(commands)
-        return "" if commands.empty?
-
-        commands.each { |command| plain!("memory command", command, VERB) }
-
-        <<~RUBY
-
-          # These commands keep nothing worth a database, so they run on Memory unless told otherwise.
-          # A person is at them: they wait for their result, say why when they are refused, and print
-          # no record when they end well.
-          MEMORY_COMMANDS = %w[#{commands.join(' ')}].freeze
-          ENV["HECKS_ENVIRONMENT"] ||= "memory" if MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))
-          ARGV << "--wait" if MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!")) && !ARGV.include?("--wait")
-        RUBY
-      end
-
-      # @api private
-      # @return [String] the lines that hand the legacy commands to `Hecks::CLI`, or nothing
-      def legacy_handoff(legacy)
-        return "" if legacy.empty?
-
-        legacy.each { |command| plain!("legacy command", command, VERB) }
-
-        <<~RUBY
-
-          # The names the gem has always shipped keep their positional forms.
-          LEGACY = %w[#{legacy.join(' ')}].freeze
-          if LEGACY.include?(ARGV.first)
-            require "hecks/cli"
-            exit Hecks::CLI.start(ARGV) unless Hecks::CLI.launcher_form?(ARGV)
-          end
-        RUBY
-      end
     end
   end
 end

data/lib/hecks/cli/project_diagrams.rb

@@ -10,21 +10,43 @@ module Hecks
     module ProjectDiagrams
       module_function
 
+      # Writes the chapter's diagrams and prints each file written.
+      #
+      # @param argv [Array<String>] the domain path, then the chapter's name
+      # @param program [String] the name the usage line shows
+      # @param root [String] the directory `docs/generated/diagrams/` lives under
+      # @return [void]
+      # @raise [SystemExit] with the usage line when an argument is missing, or when the
+      #   domain has no chapter of that name
       def call(argv, program:, root:)
         usage = "usage: #{program} <domain-path> <ChapterName>"
         domain_path  = argv[0] or abort usage
         chapter_name = argv[1] or abort usage
 
-        runtime   = Hecks.boot(File.expand_path(domain_path, Dir.pwd))
-        chapter   = runtime.registry.bluebook(chapter_name) or abort "no chapter named #{chapter_name}"
-        hecksagon = runtime.registry.hecksagon(chapter_name)
+        chapter, hecksagon = boot_chapter(domain_path, chapter_name)
         directory = File.expand_path("docs/generated/diagrams/#{Naming.snake(chapter_name)}", root)
 
-        written = Projector.write(
+        report(chapter_name, directory, write_diagrams(chapter, hecksagon, directory))
+      end
+
+      # @api private
+      # @return [Array(Object, Object)] the named chapter and its hecksagon
+      def boot_chapter(domain_path, chapter_name)
+        registry = Hecks.boot(File.expand_path(domain_path, Dir.pwd)).registry
+        chapter = registry.bluebook(chapter_name) or abort "no chapter named #{chapter_name}"
+        [chapter, registry.hecksagon(chapter_name)]
+      end
+
+      # @api private
+      def write_diagrams(chapter, hecksagon, directory)
+        Projector.write(
           Projector.call(:diagrams, bluebook: chapter, options: { hecksagon: hecksagon }),
           directory, as: :files
         )
+      end
 
+      # @api private
+      def report(chapter_name, directory, written)
         if written.empty?
           puts "#{chapter_name} declares no lifecycle, relationship, or dispatch to project yet"
         else