hecks 3.4.2 → 3.6.0

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

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

@@ -0,0 +1,43 @@
+module Hecks
+  module Doors
+    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