hecks 6.0.0 → 7.0.0

data/lib/hecks/adapters/driven/sqlite/outbox.rb

@@ -30,7 +30,7 @@ module Hecks
         # @return [Boolean] true when the row was pending and is now claimed; false when it is
         #   unknown or another claimer got there first
         # @raise [SQLite3::Exception] if the update fails
-        def outbox_claim(id) # rubocop:disable Naming/PredicateMethod -- the outbox port's verb
+        def outbox_claim(id)
           @db.execute(
             "UPDATE hecks_outbox SET status = 'claimed', attempts = attempts + 1, claimed_at = ? " \
             "WHERE id = ? AND status = 'pending'",
@@ -48,7 +48,7 @@ module Hecks
         # @param error [String, nil] the failure description, or nil to store NULL
         # @return [Boolean] true when exactly one row was updated; false when no row has `id`
         # @raise [SQLite3::Exception] if the update fails
-        def outbox_settle(id, status:, error: nil) # rubocop:disable Naming/PredicateMethod -- the outbox port's verb
+        def outbox_settle(id, status:, error: nil)
           @db.execute(
             "UPDATE hecks_outbox SET status = ?, error = ?, settled_at = ? WHERE id = ?",
             [status.to_s, error, Time.now.utc.iso8601, id]

data/lib/hecks/adapters/driven/sqlite/repository.rb

@@ -97,7 +97,7 @@ module Hecks
         # @param id [String, Object] the aggregate identity, journalled as `id.to_s`
         # @return [Boolean] always true
         # @raise [SQLite3::Exception] if either statement fails
-        def delete(id) # rubocop:disable Naming/PredicateMethod -- the repository port's verb, not a question
+        def delete(id)
           entry = Ports::Persistence::Entry.new(operation: "delete", id: id.to_s, state: nil)
           append(entry)
           project(entry)

data/lib/hecks/adapters/driven/sqlite/schema_builder.rb

@@ -15,10 +15,30 @@ module Hecks
           @db.execute(
             "CREATE TABLE IF NOT EXISTS #{quoted_table} (id TEXT PRIMARY KEY#{", " unless columns.empty?}#{columns.join(", ")})"
           )
+          ensure_aggregate_columns!
           # Called here so D1, which reuses this module, gets automatic indexing too.
           ensure_indexes!
         end
 
+        # CREATE TABLE IF NOT EXISTS never adds a column to an existing table, so an attribute the
+        # aggregate gained after its table was made gets its column here: nullable, since every row
+        # written before it holds no value. It only adds; a column the aggregate dropped is kept.
+        # SQLite column names are case-insensitive, so presence is compared that way too.
+        def ensure_aggregate_columns!
+          present = @db.execute("PRAGMA table_info(#{quoted_table})").map { |row| row["name"].to_s.downcase }
+          persisted_fields.reject { |field| present.include?(field[:name].to_s.downcase) }.each do |field|
+            add_column_once!(field)
+          end
+        end
+
+        # Another process or isolate may add the same column between the read and this ALTER;
+        # that duplicate is the outcome wanted, so only that error is let through.
+        def add_column_once!(field)
+          @db.execute("ALTER TABLE #{quoted_table} ADD COLUMN #{quote_ident(field[:name])} #{field[:sql_type]}")
+        rescue StandardError => e
+          raise unless e.message.include?("duplicate column name")
+        end
+
         def create_event_table!
           @db.execute(Ddl::EVENTS)
           # Backs #events_for's per-record lookup (a `corrects` command's history read).

data/lib/hecks/adapters/driven/sqlite.rb

@@ -3,6 +3,7 @@ require "fileutils"
 
 require_relative "sql_query_builder"
 require_relative "sqlite/schema_builder"
+require_relative "sqlite/name_guard"
 require_relative "sqlite/codec"
 require_relative "sqlite/dialect"
 require_relative "sqlite/events"
@@ -28,6 +29,7 @@ module Hecks
     class Sqlite
       include SqlQueryBuilder
       include SchemaBuilder
+      include NameGuard
       include Codec
       include Repository
       include Journal
@@ -70,6 +72,7 @@ module Hecks
         # Scopes saga rows; falls back to the aggregate's name for a directly built adapter.
         @domain = settings.fetch(:domain) { aggregate.name }.to_s
         open_database
+        refuse_orphaned_rows!
         create_tables!
       end
 
@@ -85,7 +88,9 @@ module Hecks
       def transaction(&)
         return yield if @db.transaction_active?
 
-        @db.transaction(&)
+        # Immediate, so the write lock is taken up front: a deferred transaction that reads and then
+        # writes fails at once when another process holds the file, and the busy timeout never runs.
+        @db.transaction(:immediate, &)
       end
 
       # Names the aggregate's table; the journal table and outbox rows are keyed off it.
@@ -98,6 +103,9 @@ module Hecks
       def open_database
         FileUtils.mkdir_p(File.dirname(@path))
         @db = SQLite3::Database.new(@path)
+        # Several processes may boot one journal at once (the gate's checks do), so a busy file
+        # is waited for rather than refused as "database is locked".
+        @db.busy_timeout = 10_000
         @db.results_as_hash = true
         # The append is the recovery commit point, so the fsync policy is explicit.
         @db.execute("PRAGMA synchronous = FULL")

data/lib/hecks/adapters/driven/tenant_provisioner.rb

@@ -37,7 +37,7 @@ module Hecks
       # @param adapter [String, Hash, nil] the adapter the overlay binds; PostgresEra when none
       # @return [Hash{Symbol => Object}] `:slug`, `:domain`, `:realm`, `:schema` and `:output`
       # @raise [Refused] when a value is outside its allow-list or the path leaves `environments/`
-      def write_overlay(slug:, domain:, realm:, schema:, database:, directory:, adapter: nil, **) # rubocop:disable Metrics/ParameterLists -- one keyword per command attribute
+      def write_overlay(slug:, domain:, realm:, schema:, database:, directory:, adapter: nil, **)
         values = { slug: unwrap(slug), domain: unwrap(domain), realm: unwrap(realm),
                    schema: unwrap(schema), database: unwrap(database),
                    adapter: adapter_name(adapter) }

data/lib/hecks/adapters/driven/worktree_overlay.rb

@@ -0,0 +1,117 @@
+module Hecks
+  module Adapters
+    # Says, once per process, when a linked worktree lacks the gitignored overlay files its main
+    # checkout keeps. Those files exist only in the main checkout, so a command run from a
+    # worktree stores in Memory without saying so. This warns; it never blocks the command.
+    module WorktreeOverlay
+      # The line a linked worktree's `.git` file holds, naming the directory in the main checkout.
+      GITDIR_LINE = /\Agitdir: (.+)\s*\z/
+
+      # Where the overlay files live, relative to a checkout's root.
+      OVERLAY_PATTERNS = ["lib/hecks/hecks/*.local.hecksagon", "lib/hecks/hecks/*.local.world",
+                          "environments/local.hecksagon", "environments/local.world"].freeze
+
+      module_function
+
+      # Warns on standard error the first time a domain loads from a linked worktree that lacks
+      # overlay files of its main checkout. Nothing is printed again in the same process.
+      #
+      # @param directory [String] the domain directory being loaded
+      # @param err [#puts] where the warning goes
+      # @return [String, nil] the warning printed, or nil when there was nothing to say
+      def warn_once(directory, err: $stderr)
+        return if @warned
+
+        text = warning_for(directory)
+        return unless text
+
+        @warned = true
+        err.puts(text)
+        text
+      end
+
+      # The warning for a directory inside a linked worktree, or nil when none applies.
+      #
+      # @param directory [String] a directory inside a checkout
+      # @return [String, nil]
+      def warning_for(directory)
+        _main, files = gap(directory)
+        message(files)
+      end
+
+      # The main checkout a linked worktree was made from, and the overlay files that checkout
+      # holds and this worktree lacks. Nothing is returned for a checkout that is not a worktree.
+      #
+      # @param directory [String] a directory inside a checkout
+      # @return [Array(String, Array<String>), Array(nil, Array)] the main checkout's root, then the
+      #   relative paths of the overlay files it holds and the worktree lacks
+      def gap(directory)
+        worktree = checkout_root(directory)
+        main = worktree && main_checkout(worktree)
+        return [nil, []] unless main
+
+        [main, missing(overlay_files(main), overlay_files(worktree))]
+      end
+
+      # Relative paths of the overlay files that a checkout holds.
+      #
+      # @param root [String] a checkout's root
+      # @return [Array<String>] sorted relative paths
+      def overlay_files(root)
+        OVERLAY_PATTERNS.flat_map { |pattern| Dir.glob(File.join(root, pattern)) }
+                        .map { |path| path.delete_prefix("#{root}/") }
+                        .sort
+      end
+
+      # The overlay files the main checkout holds and the worktree does not.
+      #
+      # @param main [Array<String>] relative paths in the main checkout
+      # @param worktree [Array<String>] relative paths in the worktree
+      # @return [Array<String>]
+      def missing(main, worktree)
+        main - worktree
+      end
+
+      # The one-line warning naming the files and the store they change.
+      #
+      # @param files [Array<String>] relative paths the worktree lacks
+      # @return [String, nil] the warning, or nil when no file is missing
+      def message(files)
+        return if files.empty?
+
+        "hecks: this worktree lacks #{files.join(", ")} from the main checkout; " \
+          "bluebooks that use them store in Memory here, not in the main checkout's store"
+      end
+
+      # The root of the checkout a directory is in, and whether that checkout is a linked worktree.
+      #
+      # @param directory [String]
+      # @return [String, nil] the root when it is a linked worktree, else nil
+      def checkout_root(directory)
+        root = ascend_to_git(File.expand_path(directory))
+        root if root && File.file?(File.join(root, ".git"))
+      end
+
+      # The main checkout a linked worktree was made from, found through its `.git` file.
+      #
+      # @param worktree [String] a linked worktree's root
+      # @return [String, nil]
+      def main_checkout(worktree)
+        gitdir = File.read(File.join(worktree, ".git"))[GITDIR_LINE, 1]
+        return unless gitdir
+
+        common = File.expand_path("../..", File.expand_path(gitdir, worktree))
+        File.dirname(common)
+      end
+
+      # Walks up from a directory to the first one holding a `.git` entry.
+      #
+      # @param directory [String] an absolute path
+      # @return [String, nil]
+      def ascend_to_git(directory)
+        root = Pathname.new(directory).ascend.find { |dir| dir.join(".git").exist? }
+        root&.to_s
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/cli/shorthand.rb

@@ -4,6 +4,10 @@ module Hecks
       module Cli
         # Rewrites the shorthand spellings of a command line into plain `name=value` words.
         module Shorthand
+          # The declared types a bare `--name` flag may stand for: a plain Boolean, or a `Switch`,
+          # which wraps one.
+          BOOLEAN_TYPES = %w[Boolean Switch].freeze
+
           module_function
 
           # Rewrites the short forms into `name=value`: `--name` for a Boolean (a following `yes`,
@@ -58,7 +62,7 @@ module Hecks
           def flag(name, options)
             name = name.tr("-", "_") unless options.key?(name) || options.keys.any? { |key| key.start_with?("#{name}.") }
             path = options.key?(name) ? name : Cli.expand(name, options)
-            return path if options.dig(path, :type) == "Boolean"
+            return path if BOOLEAN_TYPES.include?(options.dig(path, :type))
 
             raise Runtime::NotFound, "--#{name} is a flag, but this command has no Boolean argument #{name.inspect}"
           end

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

@@ -75,7 +75,7 @@ module Hecks
           case type
           when "Integer" then Integer(value)
           when "Float"   then Float(value)
-          when "Boolean" then boolean(value)
+          when "Boolean", "Switch" then boolean(value)
           else value
           end
         rescue ArgumentError

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

@@ -1,4 +1,6 @@
 require "json"
+require_relative "run_reference"
+require_relative "read_context"
 
 module Hecks
   module Adapters
@@ -9,41 +11,67 @@ module Hecks
         module Answers
           # What a dispatch needs beyond the spec: the parsed arguments, whether `--wait` was given,
           # and the bluebook and launcher setting the command belongs to.
-          Invocation = Struct.new(:args, :wait, :bluebook, :launcher, :text)
+          Invocation = Struct.new(:args, :wait, :bluebook, :launcher, :text, :plan)
 
           # The flag that asks for a command's recorded output as plain text and nothing else.
           TEXT = "--text".freeze
 
+          # The flag that asks what a command would write and announce, writing nothing.
+          PLAN = "--plan".freeze
+
           # 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.
+          # outcome, or the domain's refusal, into `[json_or_message, status]`. A word the command
+          # does not take, a value its type cannot hold or a flag it lacks is a line that could
+          # not be read (`ExitStatus::USAGE`); everything the domain says no to, a missing record
+          # included, is `REFUSED`. With `--wait`, a question whose report names a gap
+          # (`LauncherOptions.gap_reported?`) is refused too.
           #
           # @param bluebook [Bluebook::Declaration] the bluebook the command belongs to
           # @param launcher [Hash, nil] the bluebook'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, text = command_line(spec, rest, launcher)
-            return answer_query(runtime, spec, args, wait, launcher) if spec[:kind] == :query
+          def dispatch(runtime, spec, name, rest, program, asking, bluebook: nil, launcher: nil)
+            plan = rest.include?(PLAN)
+            args, wait, text = command_line(spec, plan ? rest - [PLAN] : rest, launcher)
+            run(runtime, spec, Invocation.new(args, wait, bluebook, launcher, text, plan), name, program, asking)
+          rescue Runtime::NotFound, Runtime::TypeMismatch => e
+            [help_pointer(e, name, program, asking), ExitStatus::USAGE]
+          end
+
+          # Runs a parsed line as a query or a command, and shapes the domain's refusal.
+          # @api private
+          def run(runtime, spec, invocation, name, program, asking)
+            return plan_or_refuse(runtime, spec, invocation, name) if invocation.plan
+            return answer_query(runtime, spec, invocation.args, invocation.wait, invocation.launcher) if spec[:kind] == :query
 
-            run_command(runtime, spec, Invocation.new(args, wait, bluebook, launcher, text))
+            run_command(runtime, spec, invocation)
           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]
+            # A missing record needs the same next step as a bad argument: read the help.
+            [help_pointer(e, name, program, asking), ExitStatus::REFUSED]
           rescue *Runtime::DOMAIN_REFUSALS => e
             # The refusal is the bluebook's own sentence, verbatim.
-            [e.message, 1]
+            [coded(e), ExitStatus::REFUSED]
           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]
+            [e.message, ExitStatus::REFUSED]
+          end
+
+          # A refusal's text, led by its stable code so a script can branch on it.
+          # @api private
+          def coded(error) = "[#{error.code}] #{error.message}"
+
+          # An error's message, then the line that prints the command's help.
+          # @api private
+          def help_pointer(error, name, program, asking)
+            "#{coded(error)}\n\n  #{program} #{"query " if asking}#{name} --help"
           end
 
           # The parsed arguments of a command line, whether to wait for the reactions, and whether
           # `--text` asked for the recorded output alone (which waits).
           def command_line(spec, rest, launcher)
             text = launcher ? rest.include?(TEXT) : false
-            rest, wait = LauncherOptions.take_wait(spec, rest - [TEXT]) if launcher
+            rest, wait = LauncherOptions.take_wait(spec, launcher ? rest - [TEXT] : rest)
             [Cli.arguments(spec, rest), text || wait || LauncherOptions.settled?(launcher, spec), text]
           end
 
@@ -55,16 +83,43 @@ module Hecks
             ancestor_names.include?(CliRunner::TOOL_REFUSAL)
           end
 
+          # Answers `--plan`: a command's plan, or usage for a query, which writes nothing to plan.
+          # @api private
+          def plan_or_refuse(runtime, spec, invocation, name)
+            return plan_refused_for_query(name) if spec[:kind] == :query
+
+            plan_answer(runtime, spec, invocation)
+          end
+
+          # Lists what a command would write and announce, writing nothing. A refusal the real run
+          # would give is answered as that refusal.
+          # @api private
+          def plan_answer(runtime, spec, invocation)
+            lines = runtime.plan_flat(spec[:command], **normalized_request(spec, invocation.args))
+            [lines.empty? ? "would not write or announce anything" : lines.join("\n"), ExitStatus::ANSWERED]
+          rescue *Runtime::DOMAIN_REFUSALS, Runtime::NotFound, Runtime::TypeMismatch => e
+            [coded(e), ExitStatus::REFUSED]
+          end
+
+          # A query has nothing to write, so `--plan` on one is a usage mistake.
+          # @api private
+          def plan_refused_for_query(name)
+            ["hecks: #{name} is a query and writes nothing, so --plan has nothing to show", ExitStatus::USAGE]
+          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)
+            args, minted = RunReference.prepare(runtime, spec, invocation.args, invocation.launcher)
+            replayed = RunReplay.answer(runtime, spec, args)
+            return replayed if replayed
+
             handle = runtime.dispatch_flat(spec[:command], normalized_request(spec, args))
-            extra  = refusals_and_run(handle, minted)
+            extra  = refusals_and_run(handle, minted, args)
             if invocation.wait
               return settled(runtime, spec, handle, invocation.bluebook, invocation.launcher, extra, text: invocation.text)
             end
 
-            [JSON.pretty_generate(outcome(handle, extra)), 0]
+            [JSON.pretty_generate(outcome(handle, extra)), ExitStatus::ANSWERED]
           end
 
           # The request a command takes from its parsed arguments.
@@ -73,8 +128,8 @@ module Hecks
           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)
+          def refusals_and_run(handle, minted, args = {})
+            extra = refused_answer(handle).merge(ids: RunReference.ids(args, handle.id))
             minted ? { run: minted }.merge(extra) : extra
           end
 
@@ -92,12 +147,12 @@ module Hecks
           #   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)
+            rows = runtime.query(spec[:command], **ReadContext.fill(spec, args))
+            return [unknown_run(args), ExitStatus::REFUSED] 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]
+             wait && LauncherOptions.gap_reported?(text) ? ExitStatus::REFUSED : ExitStatus::ANSWERED]
           end
 
           # What a question about one run answers when the process holds no such run, for a
@@ -151,8 +206,8 @@ module Hecks
 
           # 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.
+          # The answer lives only in the payloads, so names alone would drop it. The status stays
+          # `ANSWERED` 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,

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

@@ -0,0 +1,35 @@
+module Hecks
+  module Adapters
+    module Driving
+      module CliRunner
+        # The bang rule: a line that writes says so with `!`, and a command written without it is
+        # refused, naming the spelling that writes. Extended into `CliRunner`.
+        module BangRule
+          # The word a line names as typed, before the launcher's own rewrites.
+          def typed_word(argv)
+            CliRunner::QUERY_WORDS.include?(argv.first) ? argv[1] : argv.first
+          end
+
+          # The answer a line gets before any command runs: its help, or its refusal for a
+          # command written without its bang.
+          def early_answer(scope, cli, line)
+            return [command_help(scope, line[:name], line[:asking]), ExitStatus::ANSWERED] if line[:argv][1..].include?("--help")
+
+            bang_less_refusal(cli, line[:asking], line[:word], line[:name], scope[:program])
+          end
+
+          # A command written without its `!` is refused. A query, and a name that is not a
+          # command, pass.
+          #
+          # @return [Array(String, Integer), nil] the refusal and its usage status, or nil
+          def bang_less_refusal(cli, asking, word, name, program)
+            return nil if asking || word.nil? || word.end_with?("!")
+            return nil unless cli[:names][:command].key?(name)
+
+            ["#{program}: #{word} is a command and writes; write it as #{word}!", ExitStatus::USAGE]
+          end
+        end
+      end
+    end
+  end
+end

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