hecks 3.10.0 → 3.12.0

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

@@ -0,0 +1,160 @@
+require "json"
+
+module Hecks
+  module Adapters
+    module Driving
+      module CliRunner
+        # Runs one resolved command or question and shapes what it answers. Extended into
+        # `CliRunner`.
+        module Answers
+          # What a dispatch needs beyond the spec: the parsed arguments, whether `--wait` was given,
+          # and the chapter and launcher setting the command belongs to.
+          Invocation = Struct.new(:args, :wait, :bluebook, :launcher)
+
+          # Parses one resolved command's arguments, runs it as a query or command, and turns the
+          # outcome, or the domain's refusal, into `[json_or_message, status]`. With `--wait`, a
+          # question whose report names a gap (`LauncherOptions.gap_reported?`) answers status 1.
+          #
+          # @param bluebook [Bluebook::Chapter] the chapter the command belongs to
+          # @param launcher [Hash, nil] the chapter's `launcher` world setting; nil when not opted
+          #   in
+          def dispatch(runtime, spec, name, rest, program, asking, bluebook: nil, launcher: nil) # rubocop:disable Metrics/ParameterLists -- the signature is what `call` passes
+            args, wait = command_line(spec, rest, launcher)
+            return answer_query(runtime, spec, args, wait, launcher) if spec[:kind] == :query
+
+            run_command(runtime, spec, Invocation.new(args, wait, bluebook, launcher))
+          rescue Runtime::NotFound, Runtime::TypeMismatch => e
+            # A bad argument and a missing record both need the same next step: read the help.
+            ["#{e.message}\n\n  #{program} #{"query " if asking}#{name} --help", 1]
+          rescue *Runtime::DOMAIN_REFUSALS => e
+            # The refusal is the chapter's own sentence, verbatim.
+            [e.message, 1]
+          rescue StandardError => e
+            # So is a wrapped tool's, when a question's adapter refuses to answer.
+            raise unless tool_refusal?(e)
+
+            [e.message, 1]
+          end
+
+          # The parsed arguments of a command line and whether to wait for the reactions.
+          def command_line(spec, rest, launcher)
+            rest, wait = LauncherOptions.take_wait(spec, rest) if launcher
+            [Cli.arguments(spec, rest), wait || LauncherOptions.settled?(launcher, spec)]
+          end
+
+          # Whether the error is a wrapped tool's refusal. Matched by name: the adapters belong to
+          # the
+          # Hecks chapter, which a client's runtime never loads.
+          def tool_refusal?(error)
+            error.class.ancestors.map(&:name).include?(CliRunner::TOOL_REFUSAL)
+          end
+
+          # Runs a command and answers its outcome, settled when `--wait` asks for it.
+          def run_command(runtime, spec, invocation)
+            args, minted = LauncherOptions.run_key(runtime, spec, invocation.args, invocation.launcher)
+            handle = runtime.dispatch_flat(spec[:command], normalized_request(spec, args))
+            extra  = refusals_and_run(handle, minted)
+            return settled(runtime, spec, handle, invocation.bluebook, invocation.launcher, extra) if invocation.wait
+
+            [JSON.pretty_generate(outcome(handle, extra)), 0]
+          end
+
+          # The request a command takes from its parsed arguments.
+          def normalized_request(spec, args)
+            CommandRequest.normalize(args, receiver: spec[:receiver], legacy_receiver: spec[:legacy_receiver])
+          end
+
+          # The refused reactions of the dispatch, led by the minted run key when one was.
+          def refusals_and_run(handle, minted)
+            extra = refused_answer(handle)
+            minted ? { run: minted }.merge(extra) : extra
+          end
+
+          # Answers with only this command's outcome; a full store dump is every record there is.
+          def outcome(handle, extra)
+            return answered(handle).merge(extra) if handle.state.nil?
+
+            { id: handle.id, state: Json.materialize(handle.state), events: handle.events.map(&:name) }.merge(extra)
+          end
+
+          # Runs a question and answers its rows, or its text when an adapter answered in text.
+          #
+          # @param wait [Boolean, nil] whether `--wait` was given: a report naming a gap then fails
+          # @param launcher [Hash, nil] the chapter's `launcher` setting, which may name the
+          #   questions that refuse a run they do not hold
+          # @return [Array(String, Integer)] the answer and the status
+          def answer_query(runtime, spec, args, wait, launcher = nil)
+            rows = runtime.query(spec[:command], **args)
+            return [unknown_run(args), 1] if rows.empty? && LauncherOptions.unknown_run?(launcher, spec)
+
+            text = text_answer(spec, rows)
+            [text || JSON.pretty_generate(rows.map { |row| Json.materialize(row) }),
+             wait && LauncherOptions.gap_reported?(text) ? 1 : 0]
+          end
+
+          # What a question about one run answers when the process holds no such run, for a
+          # question the launcher setting lists under `unknown_runs`: a run lives in the process
+          # that made it, so a later call has nothing to read, and saying so beats an empty list
+          # that reads as "no outcome yet".
+          #
+          # @param args [Hash] the question's parsed arguments, `run` among them
+          # @return [String] the message
+          def unknown_run(args)
+            key = args[:run].is_a?(Hash) ? args[:run][:value] : args[:run]
+            "no run #{key.to_s.inspect} is held by this process: a run is kept in memory by the process " \
+              "that made it, so read its outcome from the call that requested it (`--wait` prints it whole)"
+          end
+
+          # The text a query answered by a port gave, when that is the whole answer.
+          #
+          # A query declared `returns Document` (one value object of the single String attribute
+          # `text`) answers one document; printing it raw keeps the document (JSON, Markdown,
+          # sentences) readable and pipeable instead of quoted inside another JSON document. What a
+          # query declares decides it, not how many rows came back: any other query prints JSON,
+          # so a script reading it sees an array whether it held one row or two.
+          #
+          # @param spec [Hash] the question's projected spec
+          # @param rows [Array<Hash>] the query's rows
+          # @return [String, nil] the text, or nil when the query does not return a Document
+          def text_answer(spec, rows)
+            return unless spec[:returns] == "Document" && rows.length == 1 && rows.first.keys == [:text]
+            return unless rows.first[:text].is_a?(String)
+
+            rows.first[:text]
+          end
+
+          # The reactions one dispatch caused that the domain refused, as `refused_reactions:`.
+          #
+          # A policy's trigger that a `given` refuses is not the command's own refusal: the command
+          # has already persisted. The dispatch result carries them (`Result#refused_reactions`);
+          # without this the answer would say nothing of it. A defect (a crash) is shown apart, as
+          # `reaction_defects:`, and fails `--wait`.
+          #
+          # @param handle [Runtime::Dispatcher::Result, Runtime::RemoteDispatcher::Result] the
+          #   outcome
+          # @return [Hash] `refused_reactions:` each with the `policy`, its `trigger`, the `reason`;
+          #   empty when every reaction was delivered (or a remote host sent no per-step log), plus
+          #   `reaction_defects:` when one crashed
+          def refused_answer(handle)
+            refused = handle.respond_to?(:refused_reactions) ? handle.refused_reactions : []
+            defects = handle.respond_to?(:reaction_defects) ? handle.reaction_defects : []
+            answer  = refused.empty? ? {} : { refused_reactions: refused }
+            defects.empty? ? answer : answer.merge(reaction_defects: defects)
+          end
+
+          # Shapes a port operation's outcome, which has no state: each event with its full payload.
+          #
+          # The answer lives only in the payloads, so names alone would drop it. Exit status stays 0
+          # for refusal events too, since a healthy no is an answer, not a misuse.
+          def answered(handle)
+            # A port operation hydrates no instance, so the handle's `id` is nil by design.
+            { id:     handle.id || handle.events.first&.id,
+              events: handle.events.map do |event|
+                { name: event.name, payload: Json.materialize(event.payload) }
+              end }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,158 @@
+module Hecks
+  module Adapters
+    module Driving
+      module CliRunner
+        # Parses a command line against the projection. Extended into `CliRunner`.
+        module Resolution
+          # The words that ask for the usage.
+          HELP_WORDS = ["--help", "-h", "help"].freeze
+
+          # Parses a command line against the projection: either the answer it gives without
+          # running anything, or the command it would run.
+          #
+          # @return [Hash] `{answer: [text, status]}`, or `{spec:, name:, rest:, asking:, program:,
+          #   bluebook:, launcher:}` for a command to dispatch
+          def resolve(runtime, argv, program)
+            refused = Admission.refusal(runtime.registry, "Cli")
+            return { answer: [refused, 1] } if refused
+
+            bluebook, argv, program = chapter_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)))
+            scope = { runtime: runtime, bluebook: bluebook, launcher: launcher, options: options,
+                      cli: cli, program: program }
+            usage_answer(scope, argv.first) || command_plan(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"
+
+            { answer: [maintainer_usage(*scope.values_at(:runtime, :bluebook, :launcher, :options)), 0] }
+          end
+
+          # The command a line names, or the answer when it names none or asks for its help.
+          def command_plan(scope, argv)
+            cli = scope[:cli]
+            asking, name, argv = entry_word(cli, argv)
+            return { answer: [cli[:usage], 1] } if name.nil?
+
+            spec = find_spec(cli, asking, name)
+            return { answer: [unknown(cli, name, asking, scope[:program]), 1] } unless spec
+
+            rest = argv[1..]
+            return { answer: [command_help(scope, name, asking), 0] } if rest.include?("--help")
+
+            { spec: spec, name: name, rest: rest, asking: asking, program: scope[:program],
+              bluebook: scope[:bluebook], launcher: scope[:launcher] }
+          end
+
+          # The spec a name reaches; the alias map lets `create_pizza` and `order.create_pizza`
+          # reach the same command.
+          def find_spec(cli, asking, name)
+            pool = asking ? cli[:questions] : cli[:commands]
+            pool[cli[:names][asking ? :question : :command][name]]
+          end
+
+          # The usage of one command or question, which its `--help` asks for.
+          def command_help(scope, name, asking)
+            options = scope[:options].merge(command: name, ask: asking)
+            Projector.call(:cli, bluebook: scope[:bluebook], options: options)[:usage]
+          end
+
+          # The usage with the internal commands and queries listed too, which `--all` asks for, and
+          # with the maintainer's too.
+          def all_usage(runtime, bluebook, launcher, options)
+            shown = options.merge(audience(runtime, launcher, maintainer: true))
+            Projector.call(:cli, bluebook: bluebook, options: shown.merge(all: true))[:usage]
+          end
+
+          # The usage a maintainer of the hecks checkout sees, which `--maintainer` asks for
+          # anywhere.
+          def maintainer_usage(runtime, bluebook, launcher, options)
+            shown = options.merge(audience(runtime, launcher, maintainer: true))
+            Projector.call(:cli, bluebook: bluebook, options: shown)[:usage]
+          end
+
+          # What the help leaves out and points at for whoever typed the line: the maintainer's
+          # aggregates only in a hecks checkout, and the chapters the chapter's launcher names, each
+          # with the first sentence of what it is for.
+          #
+          # @return [Hash{Symbol => Object}] `:hide` and `:chapters` (pairs of word and summary)
+          def audience(runtime, launcher, maintainer: LauncherOptions.maintainer?,
+                       newcomer: !maintainer && Newcomer.applies?)
+            shown = (newcomer && Newcomer.audience(launcher)) || LauncherOptions.audience(launcher, maintainer)
+            return shown unless shown[:chapters]
+
+            shown.merge(chapters: chapter_summaries(runtime, shown[:chapters]))
+          end
+
+          # Each named chapter the domain attaches, as its word and the first sentence of its
+          # vision.
+          def chapter_summaries(runtime, names)
+            known = attached_chapters(runtime)
+            names.filter_map do |name|
+              next unless known.include?(name)
+
+              [Naming.snake(name), Projector::CliProjector.first_sentence(runtime.registry.bluebook(name).vision)]
+            end
+          end
+
+          # Names who the help is for, so the help remembered for one is not given to the other.
+          def audience_key
+            return "maintainer" if LauncherOptions.maintainer?
+
+            Newcomer.applies? ? "newcomer" : "project"
+          end
+
+          # Reads the entry words of a line: whether it asks a query, the bare name, and the words
+          # from the name on.
+          #
+          # `query` gives queries their own namespace (`ask` is its older spelling); a chapter may
+          # 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.
+          #
+          # @return [Array(Boolean, String, Array<String>)] `asking`, `name` (nil when absent),
+          #   `argv`
+          def entry_word(cli, argv)
+            asking = CliRunner::QUERY_WORDS.include?(argv.first)
+            argv   = argv[1..] if asking
+            name   = argv.first
+            return [asking, nil, argv] if name.nil?
+
+            bang = name.end_with?("!")
+            name = name.chomp("!")
+            [asking || (!bang && query_only?(cli, name)), name, argv]
+          end
+
+          # Whether the name belongs to a query and to no command.
+          def query_only?(cli, name)
+            !cli[:names][:command].key?(name) && cli[:names][:question].key?(name)
+          end
+
+          # The chapter a command line speaks to: the booted domain's own, or, when the first word
+          # names a chapter its hecksagon attaches or uses as a framework member (`deploy`,
+          # `governance`), that chapter, with the word dropped and added to the program name.
+          def chapter_for(runtime, argv, program)
+            own    = runtime.registry.bluebooks.values.first
+            target = attached_chapters(runtime).find { |name| Naming.snake(name) == argv.first }
+            return [own, argv, program] unless target
+
+            [runtime.registry.bluebook(target), argv[1..], "#{program} #{argv.first}"]
+          end
+
+          # The chapters the booted domain's hecksagon attaches or uses as framework members.
+          def attached_chapters(runtime)
+            own = runtime.registry.bluebooks.values.first
+            Array(runtime.registry.hecksagon(own.name)&.member_chapters)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,120 @@
+require "json"
+
+module Hecks
+  module Adapters
+    module Driving
+      module CliRunner
+        # The answer `--wait` gives once every reaction has run. Extended into `CliRunner`.
+        module Settling
+          # The answer `--wait` gives: the record re-read after every reaction has run, with all its
+          # events, and a status of 1 when its lifecycle ended in a failure state, a refused
+          # reaction
+          # blocks the run or a reaction crashed.
+          #
+          # A refusal blocks unless a sibling reaction delivered another command on the same
+          # aggregate (`Runtime::ReactionOutcome`). The settled record is always the text, so a
+          # failed
+          # run pipes like a passing one; the reason a human reads is a third element.
+          #
+          # @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) # rubocop:disable Metrics/ParameterLists -- pinned by the callers and specs
+            why = reactions_failed(handle)
+            return finish(stateless_json(handle, extra), why) if handle.state.nil?
+
+            aggregate = aggregate_of(bluebook, spec)
+            state     = reread(runtime, bluebook, aggregate, handle) || handle.state
+            answer    = settled_answer(handle, state, settled_event_names(runtime, bluebook, aggregate, handle), extra)
+            why      += failure_reasons(aggregate, state, launcher)
+            settled_result(answer, LauncherOptions.report?(launcher, spec), why)
+          end
+
+          # The settled answer as the launcher's report when it prints one, else as JSON.
+          def settled_result(answer, report, why)
+            report ? report_of(answer[:state], why) : finish(JSON.pretty_generate(answer), why)
+          end
+
+          # The JSON of a port operation's outcome, which has no record to re-read.
+          def stateless_json(handle, extra)
+            JSON.pretty_generate(answered(handle).merge(extra))
+          end
+
+          # The record, as the JSON answer holds it, with the names of its events.
+          def settled_answer(handle, state, events, extra)
+            { id: handle.id, state: Json.materialize(state), events: events }.merge(extra)
+          end
+
+          # The names of the events the record's run emitted, as the runtime now holds them.
+          def settled_event_names(runtime, bluebook, aggregate, handle)
+            fqn    = "#{bluebook.name}::#{aggregate&.hecks_name}"
+            events = runtime.events.select { |event| event.aggregate == fqn && event.id == handle.id }
+            (events.empty? ? handle.events : events).map(&:name)
+          end
+
+          # The sentence for a record that ended in a failure state, as a list: empty otherwise.
+          def failure_reasons(aggregate, state, launcher)
+            return [] unless LauncherOptions.failed?(aggregate, state, launcher)
+
+            [failure_sentence(aggregate, state, aggregate.lifecycle.field)]
+          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.
+          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]
+          end
+
+          # The sentence for a record that ended in a failure state: the state, then the record's
+          # own
+          # `refusal` when it keeps one, without the class name an adapter's failure carries.
+          def failure_sentence(aggregate, state, field)
+            sentence = "#{aggregate.hecks_name} ended in the failure state #{state[field.to_sym].to_s.inspect}"
+            refusal  = state[:refusal]
+            refusal  = refusal.value if refusal.respond_to?(:value)
+            refusal  = refusal[:value] if refusal.is_a?(Hash)
+            return sentence if refusal.to_s.strip.empty?
+
+            "#{sentence}: #{refusal.to_s.strip.sub(/\A(\w+::)+\w+: /, "")}"
+          end
+
+          # The answer and its status: 0 when nothing failed, else 1 with the reasons joined.
+          def finish(text, reasons)
+            reasons.empty? ? [text, 0] : [text, 1, reasons.join("\n")]
+          end
+
+          # What the reactions of the run the handle reports did wrong: each refusal that blocks it
+          # and each crash, as one sentence apiece.
+          def reactions_failed(handle)
+            blocking = handle.respond_to?(:blocking_reactions) ? handle.blocking_reactions : []
+            crashed  = handle.respond_to?(:reaction_defects) ? handle.reaction_defects : []
+            blocking.map { |row| "reaction #{row[:policy]} was refused (#{row[:trigger]}): #{row[:reason]}" } +
+              crashed.map { |row| "reaction #{row[:policy]} crashed (#{row[:error_class]}): #{row[:reason]}" }
+          end
+
+          # Whether a reaction the domain refused blocks the run the handle reports.
+          def blocked?(handle)
+            handle.respond_to?(:blocking_reactions) && !handle.blocking_reactions.empty?
+          end
+
+          # The aggregate a top-level command belongs to; nil for an entity command or a port.
+          def aggregate_of(bluebook, spec)
+            head = spec[:command].split("::", 2).last
+            return if head.count(".") != 1
+
+            bluebook.aggregates.find { |aggregate| aggregate.hecks_name == head.split(".").first }
+          end
+
+          # The record as its repository holds it now, or nil when it cannot be read.
+          def reread(runtime, bluebook, aggregate, handle)
+            return unless aggregate && runtime.respond_to?(:registry)
+
+            runtime.registry.repository(bluebook.name, aggregate)&.find(handle.id)&.to_h
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,93 @@
+require "json"
+
+module Hecks
+  module Adapters
+    module Driving
+      module CliRunner
+        # Tails a question: asks again from the cursor each answer gave, printing new entries as
+        # JSON lines. Extended into `CliRunner`, so its methods are the runner's own.
+        module Streaming
+          # Tails a question: asks, prints each new entry as one JSON line, and asks again from the
+          # cursor the answer gave, until the reader interrupts. Only for a question the `launcher`
+          # setting lists under `streams`, given `--stream`; `from_now` applies to the first ask
+          # only.
+          #
+          # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain
+          # @param argv [Array<String>] as for `call`, with `--stream`
+          # @param program [String] how the caller was invoked
+          # @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)
+            words = stream_words(plan)
+            return unless words
+
+            run_stream(runtime, plan[:spec], words, out, max_polls)
+          rescue Interrupt, Errno::EPIPE
+            0
+          rescue Runtime::NotFound, Runtime::TypeMismatch => e
+            refuse(err, "#{e.message}\n\n  #{program} #{plan[:name]} --help")
+          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.
+          def run_stream(runtime, spec, words, out, max_polls)
+            tail(runtime, spec, Cli.arguments(spec, words), out, max_polls)
+            0
+          end
+
+          # Prints a refusal and answers status 1.
+          def refuse(err, text)
+            err.puts(text)
+            1
+          end
+
+          # One ask after another, each from the cursor the last gave.
+          def tail(runtime, spec, args, out, max_polls)
+            args   = args.merge(wait: { value: 30 }) unless args.key?(:wait)
+            polls  = 0
+            cursor = nil
+            loop do
+              row = runtime.query(spec[:command], **next_ask(args, cursor)).first || {}
+              print_entries(out, row[:events])
+              cursor = row[:cursor]
+              polls += 1
+              break if cursor.nil? || (max_polls && polls >= max_polls)
+            end
+          end
+
+          # An entry as a line: its payload, which the answer holds as JSON text, back as an object.
+          def entry_line(event)
+            line = JSON.parse(JSON.generate(event))
+            line["payload"] = JSON.parse(line["payload"]) if line["payload"].is_a?(String)
+            line
+          rescue JSON::ParserError
+            line
+          end
+
+          # The words to ask with when the line is a stream of a streamable question; nil otherwise.
+          def stream_words(plan)
+            return if plan[:answer] || !LauncherOptions.streams?(plan[:launcher], plan[:spec])
+
+            words, streaming = LauncherOptions.take_stream(plan[:rest])
+            words if streaming
+          end
+
+          # The arguments of the next ask: the first as given, later ones from the cursor.
+          def next_ask(args, cursor)
+            cursor ? args.except(:from_now).merge(since: { value: cursor }) : args
+          end
+
+          # Prints each event of an answer as one JSON line and flushes.
+          def print_entries(out, events)
+            Array(events).each { |event| out.puts(JSON.generate(entry_line(Json.materialize(event)))) }
+            out.flush
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+module Hecks
+  module Adapters
+    module Driving
+      module CliRunner
+        # Words the answer for a command or question the chapter does not declare. Extended into
+        # `CliRunner`.
+        module Suggestions
+          # Words the answer for an unknown command or question, suggesting up to five near names.
+          # Ranked by shared prefix, which survives a dropped letter where a substring would not.
+          def unknown(cli, name, asking, program)
+            near  = near_names(cli, name, asking)
+            lines = ["no such #{asking ? "query" : "command"}: #{name}"]
+            lines += ["", "did you mean:", *near.first(5).map { |candidate| "  #{candidate}" }] unless near.empty?
+            lines += ["", "  #{program}#{" query" if asking}   for the full list"]
+            lines.join("\n")
+          end
+
+          # The names worth suggesting: the bare name's homes first, then the names sharing a
+          # prefix.
+          def near_names(cli, name, asking)
+            # Both spellings are candidates: `order.create_piza` shares no prefix with
+            # `create_pizza`.
+            pool = cli[:names][asking ? :question : :command].keys
+            # A bare name is the commonest slip now that the aggregate is required: its homes first.
+            homes = (pool + cli[:names][asking ? :command : :question].keys)
+                    .select { |candidate| candidate.split(".").last == name }.uniq
+            homes + (similar_names(pool, name) - homes)
+          end
+
+          # The pool's names that share at least half of `name` (and three letters) as a prefix.
+          def similar_names(pool, name)
+            pool.map { |candidate| [shared_prefix(candidate, name), candidate] }
+                .select { |shared, _| shared >= [name.length / 2, 3].max }
+                .sort_by { |shared, candidate| [-shared, candidate] }
+                .map(&:last)
+          end
+
+          # The length of the prefix two words share.
+          def shared_prefix(one, other)
+            length = [one.length, other.length].min
+            (0...length).find { |index| one[index] != other[index] } || length
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+require "json"
+require_relative "cli"
+require_relative "command_request"
+require_relative "json"
+require_relative "launcher_options"
+require_relative "newcomer"
+require_relative "../../projector"
+require_relative "../../ports/clock"
+require_relative "cli_runner/answers"
+require_relative "cli_runner/resolution"
+require_relative "cli_runner/settling"
+require_relative "cli_runner/streaming"
+require_relative "cli_runner/suggestions"
+
+module Hecks
+  module Adapters
+    module Driving
+      # Parses and dispatches a command line against a `Projector::CliProjector` projection.
+      # Does no IO: it answers `[text, status]` and leaves printing and exiting to its callers.
+      module CliRunner
+        # The class an adapter raises when the tool it wraps refuses.
+        TOOL_REFUSAL = "Hecks::Adapters::ConsoleCapture::Failure".freeze
+        # The words that open the query namespace; `ask` is the older spelling.
+        QUERY_WORDS = %w[query ask].freeze
+
+        extend Resolution
+        extend Suggestions
+        extend Answers
+        extend Settling
+        extend Streaming
+
+        module_function
+
+        # Runs one command line against a booted domain and answers the text to print.
+        # The booted domain's own chapter is projected, or an attached one its first word names.
+        #
+        # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain
+        # @param argv [Array<String>] an optional `query` (or `ask`), the command or query name,
+        #   then
+        #   `path=value` pairs; `--help`, `-h`, `help` or nothing answers usage
+        # @param program [String] how the caller was invoked, echoed in usage and hints
+        # @return [Array(String, Integer)] the text and the status: 0 answered, 1 refused or misused
+        # @raise [Runtime::WiringError] if a repository or the clock adapter cannot be resolved
+        # @raise [Runtime::StaleWrite] if concurrent writers beat the command through every retry
+        def call(runtime:, argv:, program: "hecks run")
+          plan = resolve(runtime, argv, program)
+          return plan[:answer] if plan[:answer]
+
+          dispatch(runtime, plan[:spec], plan[:name], plan[:rest], plan[:program], plan[:asking],
+                   bluebook: plan[:bluebook], launcher: plan[:launcher])
+        end
+
+        # Answers a command line that asks only for usage, from the projection alone.
+        #
+        # Needs a registry and no bound adapter, so a `Runtime::Loader::Described` serves: the
+        # help text, the no-argument usage, a command's `--help` and an unknown one's hint all come
+        # out byte-identical to `call`'s.
+        #
+        # @param runtime [#registry] a booted domain, or what `Hecks.describe` answers
+        # @param argv [Array<String>] as for `call`
+        # @param program [String] how the caller was invoked
+        # @return [Array(String, Integer), nil] the text and status, or nil when the line would
+        #   run a command or question and so needs a booted domain
+        def usage(runtime:, argv:, program: "hecks run")
+          UsageCache.fetch(runtime, argv, program, audience: audience_key) { resolve(runtime, argv, program)[:answer] }
+        end
+      end
+    end
+  end
+end