hecks 5.0.0 → 7.0.0

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

@@ -0,0 +1,36 @@
+module Hecks
+  module Adapters
+    module Driving
+      module CliRunner
+        # The launcher word `completion <shell>` (ADR 0163, plan step 7): the script that completes
+        # the launcher's words in that shell, written from the same listing the help prints.
+        module CompletionWords
+          # The answer to `completion <shell>`: the script on stdout, or the usage line when the
+          # shell is missing or not one this projection writes.
+          def completion_answer(scope, argv)
+            return unless argv.first == "completion"
+
+            shell = argv[1]
+            script = script_for(scope, shell)
+            return { answer: ["usage: #{scope[:program]} completion <#{shells_word}>", ExitStatus::USAGE] } unless script
+
+            { answer: [script, ExitStatus::ANSWERED] }
+          end
+
+          # The script for one shell, or nil when the projection writes none for it.
+          def script_for(scope, shell)
+            return unless Projector::CliProjector::Completion::SHELLS.include?(shell)
+
+            words = Projector::CliProjector.completion_words(scope[:bluebook], scope[:cli], scope[:shown])
+            Projector::CliProjector.completion_script(shell, scope[:program], words)
+          end
+
+          # The shells named in the usage line.
+          def shells_word
+            Projector::CliProjector::Completion::SHELLS.join("|")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+module Hecks
+  module Adapters
+    module Driving
+      module CliRunner
+        # The launcher's `--json` flag (ADR 0163, plan step 9): `hecks --json` and
+        # `hecks <module> --json` print the listing's entries as JSON, from the same projection the
+        # help prints. Extended into `CliRunner`.
+        module JsonWords
+          JSON_FLAG = "--json".freeze
+
+          # The answer to a line that asks for the listing as JSON, or nil when it does not.
+          #
+          # @param scope [Hash] the runner's scope for the line: the bluebook, its projection, the
+          #   launcher and the options the help is shown with
+          # @param argv [Array<String>] the words of the line
+          # @return [Hash, nil] the answer, or nil when the line does not carry the flag
+          def json_answer(scope, argv)
+            return unless argv.include?(JSON_FLAG)
+
+            words = argv.reject { |word| word == JSON_FLAG }
+            module_word = words.find { |word| !word.start_with?("--") }
+            return { answer: [json_text(scope, module_word, words), ExitStatus::ANSWERED] } if known_or_none?(scope, module_word)
+
+            { answer: ["usage: #{scope[:program]} [<module>] --json", ExitStatus::USAGE] }
+          end
+
+          # The JSON text for the listing, limited to the module named, if any.
+          def json_text(scope, module_word, words)
+            name = module_word && Projector::CliProjector.module_named(scope[:bluebook], module_word)
+            options = json_options(scope, words).merge(module: name)
+            Projector::CliProjector.json_listing(scope[:bluebook], scope[:cli][:commands], scope[:cli][:questions], options)
+          end
+
+          # The listing's options for JSON: the audience the help shows, or with `--all` the
+          # maintainer's audience and the internal entries too.
+          def json_options(scope, words)
+            return scope[:shown] unless words.include?("--all")
+
+            search_options(scope, true)
+          end
+
+          # Whether a line names no module, or a module the bluebook declares.
+          def known_or_none?(scope, word)
+            word.nil? || known_module?(scope, word)
+          end
+
+          # Whether a word names a module of the bluebook.
+          def known_module?(scope, word)
+            !Projector::CliProjector.module_named(scope[:bluebook], word).nil?
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+require "json"
+require_relative "../usage_cache"
+
+module Hecks
+  module Adapters
+    module Driving
+      module CliRunner
+        # Every name the launcher accepts, by the scope it is typed in, for a check that reads text
+        # rather than running a line. Extended into `CliRunner`.
+        #
+        # The index is the projection's own name table: the same one `hecks --all` lists from and
+        # `resolve` looks a typed word up in, so a name the launcher would refuse is not in it. It
+        # is worked out once and remembered through `UsageCache`, which keys it to the declarations
+        # and the code that projects them.
+        module NameIndex
+          # The command line a remembered index stands for, which no real line can be.
+          CACHE_LINE = ["--name-index"].freeze
+
+          # The scope of the program's own bluebook; an attached bluebook's scope is its first word
+          # (`deploy` for `hecks deploy ...`).
+          OWN_SCOPE = "".freeze
+
+          # @param runtime [#registry] a booted domain, or what `Hecks.describe` answers
+          # @param program [String] how the caller is invoked
+          # @return [Hash{String => Hash}] per scope: `"command"` and `"question"` map each accepted
+          #   spelling to the name as listed, and `"modules"` lists the module words
+          def name_index(runtime:, program: "hecks")
+            text, = UsageCache.fetch(runtime, CACHE_LINE, program, audience: "maintainer") do
+              [JSON.generate(scopes_of(runtime, program)), 0]
+            end
+            JSON.parse(text)
+          end
+
+          # @return [Hash{String => Hash}] every scope's table, worked out from the projections
+          def scopes_of(runtime, program)
+            own = { OWN_SCOPE => scope_table(runtime, [], program) }
+            attached_bluebooks(runtime).each_with_object(own) do |name, scopes|
+              word = Naming.snake(name)
+              scopes[word] = scope_table(runtime, [word], program)
+            end
+          end
+
+          # @return [Hash] one scope's `"command"`, `"question"` and `"modules"` tables
+          def scope_table(runtime, argv, program)
+            bluebook, _, program = bluebook_for(runtime, argv, program)
+            launcher = LauncherOptions.settings(runtime, bluebook.name)
+            options = LauncherOptions.projection(launcher, program).merge(audience(runtime, launcher, maintainer: true))
+            cli = Projector.call(:cli, bluebook: bluebook, options: options)
+            { "command" => listed(cli, :command, :commands), "question" => listed(cli, :question, :questions),
+              "modules" => Projector::CliProjector.module_names(bluebook).map { |name| Naming.snake(name) } }
+          end
+
+          # @return [Hash{String => String}] each spelling of a kind, with the name as listed
+          def listed(cli, kind, specs)
+            cli[:names][kind].to_h do |spelling, id|
+              [spelling, Projector::CliProjector.verb_form(cli[specs][id] || {}, spelling)]
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+module Hecks
+  module Adapters
+    module Driving
+      module CliRunner
+        # The session's checkout, for reads only. A read of a checkout's state that names no checkout
+        # takes the one the session set in `HECKS_CHECKOUT`; a command never does. A command names its
+        # own target, because a write must land where it was asked to, not where the session last was.
+        module ReadContext
+          # The environment variable a session sets to name its checkout.
+          VARIABLE = "HECKS_CHECKOUT".freeze
+
+          # The aggregate whose queries read a checkout's state.
+          READS = /Workspace\./
+
+          module_function
+
+          # @param spec [Hash] the resolved question or command
+          # @param args [Hash] the parsed arguments, keyed by name
+          # @param env [Hash] the process environment
+          # @return [Hash] the arguments, with checkout set from the session when a read names none
+          def fill(spec, args, env: ENV)
+            checkout = env[VARIABLE]
+            return args if checkout.nil? || checkout.empty? || args.key?(:checkout)
+            return args unless spec[:kind] == :query && spec[:command].to_s.match?(READS)
+
+            args.merge(checkout: { value: checkout })
+          end
+        end
+      end
+    end
+  end
+end

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 = chapter_for(runtime, argv, program)
+            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
 
@@ -78,26 +101,27 @@ module Hecks
           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
+          # aggregates only in a hecks checkout, and the bluebooks the bluebook'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)
+          # @return [Hash{Symbol => Object}] `:hide` and `:bluebooks` (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]
+            return shown unless shown[:declarations]
 
-            shown.merge(chapters: chapter_summaries(runtime, shown[:chapters]))
+            shown.merge(declarations: bluebook_summaries(runtime, shown[:declarations]))
           end
 
-          # Each named chapter the domain attaches, as its word and the first sentence of its
+          # Each named bluebook the domain attaches, as its word and the first sentence of its
           # vision.
-          def chapter_summaries(runtime, names)
-            known = attached_chapters(runtime)
+          def bluebook_summaries(runtime, names)
+            known = attached_bluebooks(runtime)
             names.filter_map do |name|
               next unless known.include?(name)
 
-              [Naming.snake(name), Projector::CliProjector.first_sentence(runtime.registry.bluebook(name).vision)]
+              [Naming.snake(name), Projector::CliProjector.first_sentence(runtime.bluebook(name).vision)]
             end
           end
 
@@ -111,11 +135,11 @@ module Hecks
           # 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
+          # `query` gives queries their own namespace (`ask` is its older spelling); a bluebook 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.
+          # when a command shares it. The name may be written in the bluebook's verb form
+          # (`Hecks::SendTrain.board!`), which reaches the same command (see `VerbNames`).
           #
           # @return [Array(Boolean, String, Array<String>)] `asking`, `name` (nil when absent),
           #   `argv`
@@ -125,8 +149,11 @@ module Hecks
             name   = argv.first
             return [asking, nil, argv] if name.nil?
 
-            bang = name.end_with?("!")
-            name = 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
 
@@ -135,21 +162,21 @@ module Hecks
             !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 }
+          # The bluebook a command line speaks to: the booted domain's own, or, when the first word
+          # names a bluebook its hecksagon attaches or uses as a framework member (`deploy`,
+          # `governance`), that bluebook, with the word dropped and added to the program name.
+          def bluebook_for(runtime, argv, program)
+            own    = runtime.first_bluebook
+            target = attached_bluebooks(runtime).find { |name| Naming.snake(name) == argv.first }
             return [own, argv, program] unless target
 
-            [runtime.registry.bluebook(target), argv[1..], "#{program} #{argv.first}"]
+            [runtime.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)
+          # The bluebooks the booted domain's hecksagon attaches or uses as framework members.
+          def attached_bluebooks(runtime)
+            own = runtime.first_bluebook
+            Array(runtime.hecksagon(own.name)&.member_bluebooks)
           end
         end
       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