hecks 3.5.0 → 3.7.0

data/lib/hecks/doors/cli_door.rb

@@ -24,85 +24,34 @@ module Hecks
       # @raise [Runtime::NotFound] if a path, flag or bare word does not fit the command
       # @raise [Runtime::TypeMismatch] if a value does not parse as its Integer or Float
       def arguments(spec, pairs)
-        # Extra accepted arguments stay out of help, which teaches only to=....
-        options = (spec[:arguments] + Array(spec[:legacy_arguments])).to_h do |argument|
-          [argument[:path], argument]
-        end
-
-        normalize(spec, pairs, options).each_with_object({}) do |pair, args|
-          path, value = split(pair)
-          # key? rather than `||`, so the lookup below honors the same spelling `full` chose.
-          full     = options.key?(path) ? path : expand(path, options)
-          argument = options.key?(full) ? options[full] : raise(Runtime::NotFound, unknown(path, options.keys))
-
-          next words(args, full.split("."), value, argument[:type]) if argument[:words]
-          next append(args, full.split("."), cast(value, argument[:type])) if argument[:list]
-
-          bury(args, full.split("."), cast(value, argument[:type]))
-        end
-      end
-
-      # Rewrites the short forms into `name=value`: `--name` for a Boolean (a following `yes`,
-      # `no`, `true`, `false`, `on`, `off`, `1` or `0` is that flag's value, not an argument),
-      # `--name=value` as `name=value`, and one bare word as the command's first argument (`to` for
-      # a command on an existing aggregate, the first attribute for one that creates).
-      def normalize(spec, words, options)
-        queue = words.dup
-        pairs = []
-        bare  = []
-        until queue.empty?
-          word = queue.shift
-          if word.start_with?("--") && word.include?("=")
-            pairs << underscored(word.delete_prefix("--"), options)
-          elsif word.start_with?("--")
-            path  = flag(word.delete_prefix("--"), options)
-            value = BOOLEAN_WORDS.key?(queue.first.to_s.downcase) ? queue.shift : "true"
-            pairs << "#{path}=#{value}"
-          elsif word.include?("=")
-            pairs << word
-          else
-            bare << word
-            pairs << word
-          end
-        end
-        raise Runtime::NotFound, too_many_bare(bare) if bare.length > 1
-
-        pairs.map { |pair| bare.include?(pair) && !pair.include?("=") ? positional(pair, spec) : pair }
+        options = declared_options(spec)
+        Shorthand.normalize(spec, pairs, options).each_with_object({}) { |pair, args| store(args, pair, options) }
       end
 
-      # A `name=value` pair whose name is spelled with dashes (`seed-start=3`), as the argument
-      # spelled with underscores, unless an argument is named with the dashes.
-      def underscored(pair, options)
-        name, value = pair.split("=", 2)
-        options.key?(name) ? pair : "#{name.tr('-', '_')}=#{value}"
+      # Every argument the command accepts, by path. Extra accepted arguments stay out of help,
+      # which teaches only to=....
+      def declared_options(spec)
+        (spec[:arguments] + Array(spec[:legacy_arguments])).to_h { |argument| [argument[:path], argument] }
       end
 
-      # A `--name` flag, as the path of the Boolean argument it stands for. A dashed name
-      # (`--gem-only`) is the argument spelled with underscores (`gem_only`).
-      def flag(name, options)
-        name = name.tr("-", "_") unless options.key?(name) || options.keys.any? { |key| key.start_with?("#{name}.") }
-        path = options.key?(name) ? name : expand(name, options)
-        return path if options.dig(path, :type) == "Boolean"
+      # Casts the value of one `name=value` pair and sets it into `args` at its path.
+      def store(args, pair, options)
+        path, value = split(pair)
+        full, argument = declared_argument(path, options)
+        keys = full.split(".")
+        return words(args, keys, value, argument[:type]) if argument[:words]
+        return Nesting.append(args, keys, cast(value, argument[:type])) if argument[:list]
 
-        raise Runtime::NotFound, "--#{name} is a flag, but this command has no Boolean argument #{name.inspect}"
+        Nesting.bury(args, keys, cast(value, argument[:type]))
       end
 
-      # The one bare word, as a pair for the command's first argument the launcher does not mint.
-      def positional(word, spec)
-        first = spec[:arguments].find { |argument| !argument[:minted] }
-        return "#{first[:path]}=#{word}" if first
-
-        if spec[:arguments].any?
-          raise Runtime::NotFound, "#{word.inspect} is not name=value; this command's only argument is its run key, " \
-                                   "which is minted when omitted (run=<key> names one)"
-        end
-
-        raise Runtime::NotFound, "#{word.inspect} is not name=value, and this command takes no arguments"
-      end
+      # The full path and declaration of the argument `path` names, expanding a value object's
+      # short form. `key?` rather than `||`, so the lookup honors the same spelling `full` chose.
+      def declared_argument(path, options)
+        full = options.key?(path) ? path : expand(path, options)
+        return [full, options[full]] if options.key?(full)
 
-      # Words the refusal for more than one unnamed argument.
-      def too_many_bare(bare)
-        "only one argument may go unnamed, not #{bare.map(&:inspect).join(', ')}; name the rest as name=value"
+        raise Runtime::NotFound, unknown(path, options.keys)
       end
 
       # Cuts one word at its first `=`, so a value may itself contain `=`.
@@ -146,21 +95,6 @@ module Hecks
         end
       end
 
-      # Appends one element to a list argument, creating the list on first use.
-      #
-      # Repeats must grow the list (`bury` would silently keep only the last), and a single
-      # element is still a one-item list, since a `list_of` attribute must never see a bare
-      # object. Multi-field elements are left to `JsonDoor`: a flat command line cannot say
-      # which `a.x=` pairs with which `a.y=`.
-      def append(hash, path, value)
-        *branches, leaf = path.map(&:to_sym)
-        holder = branches[0..-2].reduce(hash) { |node, key| node[key] ||= {} }
-        list   = holder[branches.last] ||= []
-
-        list << { leaf => value }
-        hash
-      end
-
       # Adds the words of a `list_of` scalar argument to its Array: a comma-separated value is
       # several elements and a repeated name adds more, each cast to the element type. The
       # runtime refuses a lone scalar for a list, so the door is where every spelling becomes an
@@ -179,18 +113,12 @@ module Hecks
         hash
       end
 
-      # Sets one value at a nested path, creating intermediate Hashes and overwriting the leaf.
-      def bury(hash, path, value)
-        *branches, leaf = path.map(&:to_sym)
-        target = branches.reduce(hash) { |node, key| node[key] ||= {} }
-        target[leaf] = value
-        hash
-      end
-
       # Words the refusal for an argument the command does not take, listing what it does.
       def unknown(path, known)
-        "no argument #{path.inspect} — this command takes #{known.sort.join(', ')}"
+        "no argument #{path.inspect} — this command takes #{known.sort.join(", ")}"
       end
     end
   end
 end
+require_relative "cli_door/nesting"
+require_relative "cli_door/shorthand"

data/lib/hecks/doors/cli_runner/answers.rb

@@ -0,0 +1,138 @@
+require "json"
+
+module Hecks
+  module Doors
+    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) 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
+          [CliDoor.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: JsonDoor.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
+        # @return [Array(String, Integer)] the answer and the status
+        def answer_query(runtime, spec, args, wait)
+          rows = runtime.query(spec[:command], **args)
+          text = text_answer(spec, rows)
+          [text || JSON.pretty_generate(rows.map { |row| JsonDoor.materialize(row) }),
+           wait && LauncherOptions.gap_reported?(text) ? 1 : 0]
+        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: JsonDoor.materialize(event.payload) }
+            end }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/doors/cli_runner/resolution.rb

@@ -0,0 +1,146 @@
+module Hecks
+  module Doors
+    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)
+          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?)
+          shown = 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
+          LauncherOptions.maintainer? ? "maintainer" : "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

data/lib/hecks/doors/cli_runner/settling.rb

@@ -0,0 +1,115 @@
+require "json"
+
+module Hecks
+  module Doors
+    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: JsonDoor.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

data/lib/hecks/doors/cli_runner/streaming.rb

@@ -0,0 +1,90 @@
+require "json"
+
+module Hecks
+  module Doors
+    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, CliDoor.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(JsonDoor.materialize(event)))) }
+          out.flush
+        end
+      end
+    end
+  end
+end