hecks 6.0.0 → 7.0.0

data/lib/hecks/adapters/driving/cli_runner/renamed_names.rb

@@ -0,0 +1,49 @@
+module Hecks
+  module Adapters
+    module Driving
+      module CliRunner
+        # The launcher's renamed table at run time: a line that spells a renamed command's old name
+        # is noted once on standard error, and its argument names translate before the command reads
+        # them. Extended into `CliRunner`.
+        module RenamedNames
+          # Notes a renamed spelling once, and returns the line's argv with its arguments translated.
+          #
+          # @param cli [Hash] the projection, holding `:names` with its `:renamed` table
+          # @param typed [String] the word typed, without its `!`
+          # @param name [String] the name the index resolved the word to
+          # @param argv [Array<String>] the line's words, the command name first
+          # @return [Array<String>] the words with renamed arguments translated
+          def renamed_line(cli, typed, name, argv)
+            table = cli.dig(:names, :renamed) || {}
+            note_renamed(cli, typed, name) if Array(table[:spellings]).include?(typed)
+            translate_arguments(table.dig(:arguments, typed), argv)
+          end
+
+          # Says once per process, on standard error, that a line used a renamed command's old name.
+          def note_renamed(cli, typed, name)
+            target = cli.dig(:names, :command, typed) || cli.dig(:names, :question, typed) || name
+            return unless VerbNames::NOTED.add?("spelling #{typed}")
+
+            warn "hecks: #{typed} is the former name of #{target}; use that spelling (this notice prints once)"
+          end
+
+          # Rewrites the argument names a renamed table translates (`old=value` to `new=value`); the
+          # name word and any other word pass through unchanged.
+          def translate_arguments(renames, argv)
+            return argv if renames.nil? || renames.empty?
+
+            [argv.first, *argv.drop(1).map { |word| translate_word(renames, word) }]
+          end
+
+          # One `old=value` word with its argument renamed when the table names it.
+          def translate_word(renames, word)
+            key, value = word.split("=", 2)
+            return word if value.nil? || !renames.key?(key)
+
+            "#{renames[key]}=#{value}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/cli_runner/resolution.rb

@@ -1,9 +1,13 @@
+require_relative "bang_rule"
+
 module Hecks
   module Adapters
     module Driving
       module CliRunner
         # Parses a command line against the projection. Extended into `CliRunner`.
         module Resolution
+          include BangRule
+
           # The words that ask for the usage.
           HELP_WORDS = ["--help", "-h", "help"].freeze
 
@@ -14,39 +18,58 @@ module Hecks
           #   bluebook:, launcher:}` for a command to dispatch
           def resolve(runtime, argv, program)
             refused = Admission.refusal(runtime.registry, "Cli")
-            return { answer: [refused, 1] } if refused
+            return { answer: [refused, ExitStatus::REFUSED] } if refused
 
             bluebook, argv, program = bluebook_for(runtime, argv, program)
             launcher = LauncherOptions.settings(runtime, bluebook.name)
             options  = LauncherOptions.projection(launcher, program)
-            cli = Projector.call(:cli, bluebook: bluebook, options: options.merge(audience(runtime, launcher)))
+            shown = options.merge(audience(runtime, launcher))
+            cli = Projector.call(:cli, bluebook: bluebook, options: shown)
             scope = { runtime: runtime, bluebook: bluebook, launcher: launcher, options: options,
-                      cli: cli, program: program }
-            usage_answer(scope, argv.first) || command_plan(scope, argv)
+                      shown: shown, cli: cli, program: program }
+            answer_for(scope, argv) || command_plan(scope, argv)
+          end
+
+          # The answer a line gets without naming a command, or nil when it names one.
+          def answer_for(scope, argv)
+            json_answer(scope, argv) || usage_answer(scope, argv.first) || module_answer(scope, argv.first) ||
+              search_answer(scope, argv) || completion_answer(scope, argv) || tour_answer(scope, argv) || resume(scope, argv)
           end
 
           # The answer to a line that is only a request for usage, or nil.
           def usage_answer(scope, name)
-            return { answer: [scope[:cli][:usage], 0] } if name.nil? || HELP_WORDS.include?(name)
-            return { answer: [all_usage(*scope.values_at(:runtime, :bluebook, :launcher, :options)), 0] } if name == "--all"
-            return unless name == "--maintainer"
+            return { answer: [scope[:cli][:usage], ExitStatus::ANSWERED] } if name.nil? || HELP_WORDS.include?(name)
+            return unless %w[--all --maintainer].include?(name)
+
+            shown = scope.values_at(:runtime, :bluebook, :launcher, :options)
+            { answer: [name == "--all" ? all_usage(*shown) : maintainer_usage(*shown), ExitStatus::ANSWERED] }
+          end
+
+          # The help of the module a line is only the word of, or nil. A module groups aggregates of
+          # one bluebook (ADR 0163), so `hecks deliver` lists what `deliver` holds.
+          def module_answer(scope, word)
+            name = Projector::CliProjector.module_named(scope[:bluebook], word)
+            return unless name
 
-            { answer: [maintainer_usage(*scope.values_at(:runtime, :bluebook, :launcher, :options)), 0] }
+            shown = scope[:shown].merge(module: name, program: scope[:program])
+            { answer: [Projector.call(:cli, bluebook: scope[:bluebook], options: shown)[:usage], ExitStatus::ANSWERED] }
           end
 
-          # The command a line names, or the answer when it names none or asks for its help.
+          # The command a line names, or the answer when it names none or asks for its help. A
+          # line that names nothing, or something the bluebook does not declare, could not be read.
           def command_plan(scope, argv)
             cli = scope[:cli]
+            word = typed_word(argv)
             asking, name, argv = entry_word(cli, argv)
-            return { answer: [cli[:usage], 1] } if name.nil?
+            return { answer: [cli[:usage], ExitStatus::USAGE] } if name.nil?
 
             spec = find_spec(cli, asking, name)
-            return { answer: [unknown(cli, name, asking, scope[:program]), 1] } unless spec
+            return { answer: [unknown(cli, name, asking, scope[:program]), ExitStatus::USAGE] } unless spec
 
-            rest = argv[1..]
-            return { answer: [command_help(scope, name, asking), 0] } if rest.include?("--help")
+            answer = early_answer(scope, cli, { asking: asking, word: word, name: name, argv: argv })
+            return { answer: answer } if answer
 
-            { spec: spec, name: name, rest: rest, asking: asking, program: scope[:program],
+            { spec: spec, name: name, rest: argv[1..], asking: asking, program: scope[:program],
               bluebook: scope[:bluebook], launcher: scope[:launcher] }
           end
 
@@ -116,7 +139,7 @@ module Hecks
           # declare a command and a query of one name. A trailing `!` says the word is a command and
           # is not part of the name. A query answers to its bare name too; `query` is needed only
           # when a command shares it. The name may be written in the bluebook's verb form
-          # (`Hecks::PushTrain.board!`), which reaches the same command (see `VerbNames`).
+          # (`Hecks::SendTrain.board!`), which reaches the same command (see `VerbNames`).
           #
           # @return [Array(Boolean, String, Array<String>)] `asking`, `name` (nil when absent),
           #   `argv`
@@ -126,8 +149,11 @@ module Hecks
             name   = argv.first
             return [asking, nil, argv] if name.nil?
 
-            bang = name.end_with?("!")
-            name = canonical_name(cli, name.chomp("!"))
+            bang  = name.end_with?("!")
+            typed = name.chomp("!")
+            name  = canonical_name(cli, typed)
+            note_former_name(cli, typed, name)
+            argv = renamed_line(cli, typed, name, argv)
             [asking || (!bang && query_only?(cli, name)), name, argv]
           end
 

data/lib/hecks/adapters/driving/cli_runner/resume_words.rb

@@ -0,0 +1,63 @@
+module Hecks
+  module Adapters
+    module Driving
+      module CliRunner
+        # The launcher word `resume <run>` (ADR 0163, plan step 31): continues a saga that faulted
+        # from the stage it faulted in. The saga saved its arguments and the stage; the process
+        # manager's `resumes` list names the command that re-runs that stage, and that command is
+        # dispatched with the saved arguments through the ordinary line path.
+        module ResumeWords
+          SAGA = "GateAndBoard".freeze
+
+          # The answer to `resume <run>`, or nil when the line is not a resume.
+          def resume(scope, argv)
+            return unless argv.first == "resume"
+            return { answer: [resume_usage, ExitStatus::USAGE] } unless argv[1] && booted?(scope)
+
+            outcome = scope[:runtime].saga_interpreter.resume(scope[:bluebook].name, SAGA, argv[1])
+            return { answer: [resume_refusal(outcome), ExitStatus::REFUSED] } unless outcome[:resumed]
+
+            resume_stage(scope, outcome)
+          end
+
+          # Whether the line runs against a booted domain: a describe-only runtime (the usage path)
+          # has no saga interpreter, so a resume there answers its usage rather than failing.
+          def booted?(scope)
+            scope[:runtime].respond_to?(:saga_interpreter)
+          end
+
+          # Dispatches the stage's resume command with the saved arguments, or refuses when the
+          # stage declares none.
+          def resume_stage(scope, outcome)
+            command = resume_command(scope[:bluebook], outcome[:stage])
+            unless command
+              return { answer: ["resume refused: stage #{outcome[:stage]} declares no resume command",
+                                ExitStatus::REFUSED] }
+            end
+
+            line = [command, *outcome[:arguments].map { |key, value| "#{key}=#{value}" }]
+            text, status = CliRunner.call(runtime: scope[:runtime], argv: line, program: scope[:program])
+            { answer: [text, status] }
+          end
+
+          # The command the process manager's `resumes` list names for a stage, as a bang line.
+          def resume_command(bluebook, stage)
+            process_manager = bluebook.process_managers.find { |pm| pm.name == SAGA }
+            entry = process_manager&.resumes&.find { |line| line.start_with?("#{stage}=") }
+            entry && "#{entry.split("=", 2).last}!"
+          end
+
+          # The reason a resume refuses: the saga is missing, or it is not waiting for a person.
+          def resume_refusal(outcome)
+            "resume refused: #{outcome[:reason]}"
+          end
+
+          # The usage line of `resume`.
+          def resume_usage
+            "usage: resume <run>  (continues a GateAndBoard saga that faulted, from the stage it faulted in)"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/cli_runner/run_reference.rb

@@ -0,0 +1,66 @@
+require_relative "../../../storehouse"
+
+module Hecks
+  module Adapters
+    module Driving
+      module CliRunner
+        # Lets a landing name the linked worktree it lands by its run id, rather than repeating its
+        # checkout and branch. An explicit checkout or branch always wins over the one the worktree holds.
+        module RunReference
+          # The aggregate whose record a landing's `from` names.
+          SOURCE = "LinkedTree".freeze
+
+          # The arguments a result names as the ids a command used.
+          IDENTITY = %i[run from checkout branch].freeze
+
+          # The command that lands a branch: `Hecks::Landing.Land`, and its qualified forms.
+          LANDING = /Landing\.Land\z/
+
+          module_function
+
+          # Mints the run key a creating command is owed, then fills the arguments a `from` names.
+          #
+          # @return [Array(Hash, String, nil)] the arguments and the minted key, if one was minted
+          def prepare(runtime, spec, args, settings)
+            args, minted = LauncherOptions.run_key(runtime, spec, args, settings)
+            [fill(runtime, spec, args), minted]
+          end
+
+          # @param runtime [Runtime::Registry] the booted domain the command runs against
+          # @param spec [Hash] the resolved command
+          # @param args [Hash] the parsed arguments, keyed by name
+          # @return [Hash] the arguments, with checkout and branch filled from the named worktree when the
+          #   caller gave a `from` and left them out
+          def fill(runtime, spec, args)
+            from = args[:from]&.fetch(:value, nil)
+            return args unless from && spec[:command].to_s.match?(LANDING)
+
+            tree = Storehouse.state(runtime: runtime, aggregate: SOURCE, id: from,
+                                    summary: "landing reads the worktree it names")
+            return args unless tree[:ok]
+
+            record = tree[:record]
+            args.merge(checkout: args[:checkout] || { value: value_of(record[:path]) },
+                       branch:   args[:branch] || { value: value_of(record[:branch]) })
+          end
+
+          # The ids a result names: the run key, the record written, and the references the command used,
+          # with the checkout and branch it resolved. Absent ones are left out.
+          #
+          # @param args [Hash] the arguments the command ran with, after any reference was filled
+          # @param record_id [String, nil] the id of the record the command wrote
+          # @return [Hash] the ids the command used
+          def ids(args, record_id)
+            named = IDENTITY.to_h { |key| [key, value_of(args[key])] }
+            named.merge(id: record_id).compact
+          end
+
+          # A stored field is its value, or the `{value:}` wrapper a word carries.
+          def value_of(field)
+            field.is_a?(Hash) ? field[:value] : field
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/cli_runner/run_replay.rb

@@ -0,0 +1,118 @@
+module Hecks
+  module Adapters
+    module Driving
+      module CliRunner
+        # Answers a creating command that names a run key the store already holds.
+        #
+        # Where the aggregate persists (SQLite, Postgres), a repeat with the same key and the same
+        # arguments answers the record written first, and a repeat with other arguments is refused:
+        # the key names a different run. Memory holds nothing across processes, so it cannot
+        # answer a repeat; it refuses the key and says which store would answer it.
+        module RunReplay
+          MEMORY = "Memory".freeze
+
+          module_function
+
+          # @param runtime [Runtime::Dispatcher] the booted domain
+          # @param spec [Hash] the command's projected spec
+          # @param args [Hash] the parsed arguments, including `run` when one was given
+          # @return [Array(String, Integer), nil] the answer and its status, or nil when the
+          #   key is not recorded and the command should run
+          def answer(runtime, spec, args)
+            return unless replayable?(runtime, spec, args)
+
+            target = target(runtime, spec)
+            record = target && recorded(target, run_key(args))
+            return unless record
+
+            return memory_refusal(args) if memory?(target)
+
+            same?(record, args) ? [recorded_text(record, args), ExitStatus::ANSWERED] : [different_text(args), ExitStatus::REFUSED]
+          end
+
+          # Whether the command creates a record under a run key the caller gave.
+          def replayable?(runtime, spec, args)
+            spec[:creates] && args.key?(:run) && runtime.respond_to?(:registry)
+          end
+
+          # The registry, domain and aggregate the command writes to, or nil when it has none.
+          def target(runtime, spec)
+            registry = runtime.registry
+            domain = registry.first_domain_name
+            aggregate = registry.bluebook(domain)&.aggregate(spec[:group].to_s)
+            aggregate && { registry: registry, domain: domain, aggregate: aggregate }
+          end
+
+          # Whether the aggregate's authoritative store is Memory.
+          def memory?(target)
+            bind = Ports::Persistence::BindingPolicy.resolve(target[:registry], target[:domain], target[:aggregate])
+            bind.adapter.to_s == MEMORY
+          end
+
+          # The run key's value, whether given bare or as `{ value: }`.
+          def run_key(args)
+            value = args[:run]
+            value.is_a?(Hash) ? value[:value] : value
+          end
+
+          # The stored record of the key, or nil when none is held.
+          def recorded(target, key)
+            registry, domain = target.values_at(:registry, :domain)
+            registry.repository(domain, target[:aggregate]).find(key.to_s)
+          end
+
+          # Whether the stored record holds every argument the repeat gave.
+          def same?(record, args)
+            given(args).all? { |name, value| stored(record, name) == value.to_s }
+          end
+
+          # A stored field as its text: a value object answers its `value` field.
+          def stored(record, name)
+            held = record.state[name.to_sym]
+            (held.is_a?(Hecks::Runtime::Value) ? held[:value] : held).to_s
+          end
+
+          # The arguments that describe the record, without the run key.
+          def given(args)
+            args.except(:run).transform_values { |value| plain(value) }
+          end
+
+          # A value as its text: `{ value: x }` and `{ cents: x }` both answer `x`.
+          def plain(value)
+            return value unless value.is_a?(Hash)
+
+            value.values.first
+          end
+
+          # The first answer's text: the run key, the record it already holds and the ids it named.
+          def recorded_text(record, args)
+            JSON.pretty_generate("id" => run_key(args).to_s, "state" => recorded_state(record), "events" => [],
+                                 "ids" => { "run" => run_key(args).to_s, "id" => record.id.to_s })
+          end
+
+          # The stored fields as text, keyed by name, then the record's id, as the first answer
+          # printed them.
+          def recorded_state(record)
+            fields = record.state.keys.to_h { |name| [name.to_s, stored(record, name)] }
+            fields.merge("id" => record.id.to_s)
+          end
+
+          # The refusal for a key held with other arguments.
+          def different_text(args)
+            "[already_recorded] refused: run #{run_key(args)} is already recorded with other arguments: nothing written"
+          end
+
+          # The refusal for a key held in Memory, which does not remember runs across processes.
+          def memory_refusal(args) = [refusal_text(args), ExitStatus::REFUSED]
+
+          # The text naming Memory and the persisting stores that would answer the repeat.
+          def refusal_text(args)
+            "[memory_store] refused: run #{run_key(args)} is held in Memory, which does not remember runs across " \
+              "processes: nothing written. A persisting store (SQLite or Postgres) answers a repeat " \
+              "with the first outcome."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/cli_runner/search_words.rb

@@ -0,0 +1,35 @@
+module Hecks
+  module Adapters
+    module Driving
+      module CliRunner
+        # The launcher word `search`: the commands and queries a word appears in, read from the same
+        # projection the help prints (ADR 0163, step 20). Extended into `CliRunner`.
+        module SearchWords
+          # The answer to `search <word> [--all]`: the commands and queries a word appears in, or
+          # the line saying none does.
+          def search_answer(scope, argv)
+            return unless argv.first == "search"
+
+            word = argv.drop(1).find { |arg| !arg.start_with?("--") }
+            return { answer: ["usage: #{scope[:program]} search <word> [--all]", ExitStatus::USAGE] } unless word
+
+            options = search_options(scope, argv.include?("--all"))
+            lines = Projector::CliProjector.search_lines(scope[:bluebook], scope[:cli][:commands],
+                                                         scope[:cli][:questions], options, word)
+            return { answer: ["no command or query matches #{word}", ExitStatus::REFUSED] } unless lines
+
+            { answer: [lines.join("\n"), ExitStatus::ANSWERED] }
+          end
+
+          # The listing's options for a search: the audience the help shows, or with `--all` the
+          # maintainer's audience and the internal commands too.
+          def search_options(scope, all)
+            return scope[:shown] unless all
+
+            scope[:options].merge(audience(scope[:runtime], scope[:launcher], maintainer: true)).merge(all: true)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/cli_runner/settling.rb

@@ -21,7 +21,7 @@ module Hecks
           #
           # @return [Array(String, Integer)] the JSON and the status, plus (Array(String, Integer,
           #   String)) why the run failed when it did
-          def settled(runtime, spec, handle, bluebook, launcher, extra, text: false) # rubocop:disable Metrics/ParameterLists -- pinned by the callers and specs
+          def settled(runtime, spec, handle, bluebook, launcher, extra, text: false)
             why = reactions_failed(handle)
             return finish(stateless_json(handle, extra), why) if handle.state.nil?
 
@@ -62,12 +62,12 @@ module Hecks
           end
 
           # The answer of a command the launcher prints as its report: the text it recorded, with
-          # the status 1 when the run failed, and nothing else.
+          # the status `REFUSED` when the run failed, and nothing else.
           def report_of(state, why)
             text = state[why.empty? ? :output : :refusal]
             text = text[:value] if text.is_a?(Hash)
             text = why.join("\n") if text.to_s.strip.empty?
-            [text.to_s, why.empty? ? 0 : 1]
+            [text.to_s, why.empty? ? ExitStatus::ANSWERED : ExitStatus::REFUSED]
           end
 
           # The sentence for a record that ended in a failure state: the state, then the record's
@@ -83,9 +83,10 @@ module Hecks
             "#{sentence}: #{refusal.to_s.strip.sub(QUALIFIED_CLASS_PREFIX, "")}"
           end
 
-          # The answer and its status: 0 when nothing failed, else 1 with the reasons joined.
+          # The answer and its status: `ANSWERED` when nothing failed, else `REFUSED` with the
+          # reasons joined.
           def finish(text, reasons)
-            reasons.empty? ? [text, 0] : [text, 1, reasons.join("\n")]
+            reasons.empty? ? [text, ExitStatus::ANSWERED] : [text, ExitStatus::REFUSED, reasons.join("\n")]
           end
 
           # What the reactions of the run the handle reports did wrong: each refusal that blocks it

data/lib/hecks/adapters/driving/cli_runner/streaming.rb

@@ -18,31 +18,32 @@ module Hecks
           # @param out [IO] where each entry's line goes
           # @param err [IO] where a refusal goes
           # @param max_polls [Integer, nil] stop after this many asks; unbounded when nil
-          # @return [Integer, nil] 0 or 1 for a stream, nil when `call` should run the line
-          def stream(runtime:, argv:, program: "hecks run", out: $stdout, err: $stderr, max_polls: nil) # rubocop:disable Metrics/ParameterLists -- the keyword API is what callers pass
-            plan  = resolve(runtime, argv, program)
+          # @return [Integer, nil] the stream's `ExitStatus`, nil when `call` should run the line
+          def stream(runtime:, argv:, program: "hecks run", out: $stdout, err: $stderr, max_polls: nil)
+            plan  = resolve(runtime, split_verbosity(argv).last, program)
             words = stream_words(plan)
             return unless words
 
             run_stream(runtime, plan[:spec], words, out, max_polls)
           rescue Interrupt, Errno::EPIPE
-            0
+            ExitStatus::ANSWERED
           rescue Runtime::NotFound, Runtime::TypeMismatch => e
-            refuse(err, "#{e.message}\n\n  #{program} #{plan[:name]} --help")
+            refuse(err, "#{e.message}\n\n  #{program} #{plan[:name]} --help", ExitStatus::USAGE)
           rescue *Runtime::DOMAIN_REFUSALS => e
             refuse(err, e.message)
           end
 
-          # Tails the question the line names and answers 0, the status of a stream that ended.
+          # Tails the question the line names and answers `ANSWERED`, the status of a stream that
+          # ended.
           def run_stream(runtime, spec, words, out, max_polls)
             tail(runtime, spec, Cli.arguments(spec, words), out, max_polls)
-            0
+            ExitStatus::ANSWERED
           end
 
-          # Prints a refusal and answers status 1.
-          def refuse(err, text)
+          # Prints a refusal and answers its status, `REFUSED` unless told otherwise.
+          def refuse(err, text, status = ExitStatus::REFUSED)
             err.puts(text)
-            1
+            status
           end
 
           # One ask after another, each from the cursor the last gave.

data/lib/hecks/adapters/driving/cli_runner/suggestions.rb

@@ -9,7 +9,7 @@ module Hecks
           # Ranked by shared prefix, which survives a dropped letter where a substring would not.
           def unknown(cli, name, asking, program)
             near  = near_names(cli, snake_form(name), asking)
-            lines = ["no such #{asking ? "query" : "command"}: #{name}"]
+            lines = ["[unknown_#{asking ? "query" : "command"}] no such #{asking ? "query" : "command"}: #{name}"]
             shown = near.first(5).map { |candidate| "  #{shown_name(cli, candidate, asking)}" }
             lines += ["", "did you mean:", *shown] unless near.empty?
             lines += ["", "  #{program}#{" query" if asking}   for the full list"]

data/lib/hecks/adapters/driving/cli_runner/tour_words.rb

@@ -0,0 +1,77 @@
+require "fileutils"
+require "stringio"
+
+module Hecks
+  module Adapters
+    module Driving
+      module CliRunner
+        # The launcher word `tour [dir]` (ADR 0163, plan step 40): writes a sample domain into a new
+        # directory, runs one command against it in memory, and says what to type next. It writes
+        # only into a directory that does not exist yet.
+        module TourWords
+          TOUR_NAME = "Tour".freeze
+          TOUR_COMMAND = %w[Example.create! name=hello].freeze
+          TOUR_DIRECTORY = "hecks-tour".freeze
+
+          # The answer to `tour [dir]`, or nil when the line is not a tour.
+          def tour_answer(scope, argv)
+            return unless argv.first == "tour"
+
+            target = File.expand_path(argv[1] || TOUR_DIRECTORY, Dir.pwd)
+            return { answer: [tour_refusal(target), ExitStatus::REFUSED] } if File.exist?(target)
+
+            write_tour(target)
+            { answer: [tour_report(scope, target), ExitStatus::ANSWERED] }
+          end
+
+          # The reason a tour refuses a directory that already exists.
+          def tour_refusal(target)
+            "tour refused: #{shown_tour(target)} already exists; name a new directory: hecks tour <dir>"
+          end
+
+          # Writes each stub file of the sample domain under `target`.
+          def write_tour(target)
+            require_relative "../../../tools/domain_stub"
+            Tools::DomainStub.files(name: TOUR_NAME).each do |path, text|
+              full = File.join(target, path)
+              FileUtils.mkdir_p(File.dirname(full))
+              File.write(full, text)
+            end
+          end
+
+          # The report of a tour: what was written, the command's result, and the next command.
+          def tour_report(scope, target)
+            shown = shown_tour(target)
+            result = capture_run(target)
+            ran = "ran: #{tour_line(scope, shown, TOUR_COMMAND)}"
+            lines = ["wrote a sample domain in #{shown}/", "", ran, result]
+            lines + ["", "next: #{tour_line(scope, shown, %w[Example.create! name=yourname])}"]
+          end
+
+          # The launcher line that runs `command` (a verb and its arguments) against the domain in
+          # `shown`: `run` is a verb of Operation, not a launcher word.
+          def tour_line(scope, shown, command)
+            verb, *arguments = command
+            given = arguments.map { |argument| "arguments.value=#{argument}" }
+            [scope[:program], "Operation.run!", "subject.value=#{shown}", "verb.value=#{verb}",
+             *given].join(" ")
+          end
+
+          # The command's own answer, from a booted copy of the sample domain. The runner answers
+          # without exiting, unlike the launcher's `run`, so the report can carry the text.
+          def capture_run(target)
+            runtime = Hecks.boot(target, install_driving: false)
+            Assembly.bind_ported_runtime(runtime)
+            text, _status = CliRunner.call(runtime: runtime, argv: TOUR_COMMAND, program: "hecks run #{target}")
+            text.to_s.strip
+          end
+
+          # The directory as the user typed it, relative to where they are, when it is inside.
+          def shown_tour(target)
+            target.delete_prefix("#{Dir.pwd}/")
+          end
+        end
+      end
+    end
+  end
+end