hecks 2.7.0 → 2.9.0

data/lib/hecks/cli/mcp_door.rb

@@ -0,0 +1,366 @@
+require "json"
+require_relative "../../hecks"
+require_relative "mcp"
+
+module Hecks
+  module CLI
+    # The MCP door onto the storehouse bus: hand-rolled JSON-RPC over stdio, one
+    # server per booted domain. All logic and the JSON shape answered with live in
+    # `Storehouse`; this is plumbing only. A `role:`/`actor_id:` a caller sends is
+    # asserted, not verified, unless Governance is attached.
+    #
+    # There is no authentication: `domain:` boots real Ruby confined to
+    # `Storehouse::BOOT_ROOT`, so this is a code execution surface for anyone who
+    # can write to stdin (ADR 0062). Spawning with `HECKS_DOOR_TOOLS=readers` and
+    # `HECKS_DOOR_DOMAINS=<dir>[:<dir>...]` narrows a door to read-only tools and
+    # named domains (`McpDoorScope`); this limits what one agent can reach and is
+    # not itself authentication.
+    module McpDoor
+      PROTOCOL_VERSION = "2024-11-05".freeze
+
+      SUMMARY_PROPERTY = {
+        type:        "string",
+        description: "One line: why this call is happening. Required — it is what makes the audit trail legible later."
+      }.freeze
+
+      DOMAIN_PROPERTY = {
+        type:        "string",
+        description: "The domain directory, containing a .hecksagon (e.g. \"examples/banking\"). The `domains` tool " \
+                     "lists what's available."
+      }.freeze
+
+      ARGS_PROPERTY = {
+        type:        "object",
+        description: "The command/query's declared arguments, nested value-object literals included " \
+                     "(e.g. {\"reference\":{\"value\":\"BUG#1\"}})."
+      }.freeze
+
+      SOURCE_PROPERTY = {
+        type:        "string",
+        enum:        Hecks::Storehouse::SOURCE_TAGS,
+        description: "Optional: who is calling, for the audit log `follow` reads back."
+      }.freeze
+
+      ROLE_PROPERTY = {
+        type:        "string",
+        description: "Bind a caller identity for the call's duration, so a role-gated command's authorization is " \
+                     "checked rather than merely documented. Required by `dispatch` for any command that declares a " \
+                     "role — omitting it refuses the call rather than running it unchecked. Also required if " \
+                     "`actor_id` is given."
+      }.freeze
+
+      ACTOR_ID_PROPERTY = {
+        type:        "string",
+        description: "Optional, alongside `role`: WHO holds that role — once the domain attaches Governance, checked " \
+                     "against a real Governance::RoleAssignment instead of a bare string match. Requires `role`."
+      }.freeze
+
+      TOOLS = [
+        {
+          name:        "dispatch",
+          description: "Issue a command against a booted domain — or, with `steps`, several in one call. `command` is " \
+                       "the short or qualified verb name (the catalog/describe tools show what's available). Set " \
+                       "`dry_run: true` to check whether it WOULD succeed without committing anything. Answers the " \
+                       "record's id, its resulting state, and the events it announced — or a structured refusal, " \
+                       "never a crash.",
+          inputSchema: {
+            type:       "object",
+            properties: {
+              domain:   DOMAIN_PROPERTY,
+              command:  { type: "string", description: "The command's short or qualified name, e.g. \"open_account\". " \
+                                                       "Ignored when `steps` is given." },
+              args:     ARGS_PROPERTY,
+              summary:  SUMMARY_PROPERTY,
+              source:   SOURCE_PROPERTY,
+              role:     ROLE_PROPERTY,
+              actor_id: ACTOR_ID_PROPERTY,
+              dry_run:  { type: "boolean", description: "Preview only — check the command would succeed, commit nothing. " \
+                                                        "Ignored when `steps` is given." },
+              steps:    {
+                type:        "array",
+                description: "Run several commands in one call, in order. Each item: {command, args}. When given, " \
+                             "`command`/`args`/`dry_run` above are ignored.",
+                items:       {
+                  type:       "object",
+                  properties: { command: { type: "string" }, args: ARGS_PROPERTY },
+                  required:   %w[command]
+                }
+              }
+            },
+            required:   %w[domain summary]
+          }
+        },
+        {
+          name:        "query",
+          description: "Ask a declared question of a booted domain. `question` is the short or qualified query name. " \
+                       "Answers the row array the query itself declares.",
+          inputSchema: {
+            type:       "object",
+            properties: {
+              domain:   DOMAIN_PROPERTY,
+              question: { type: "string", description: "The query's short or qualified name." },
+              args:     ARGS_PROPERTY,
+              summary:  SUMMARY_PROPERTY,
+              source:   SOURCE_PROPERTY,
+              role:     ROLE_PROPERTY,
+              actor_id: ACTOR_ID_PROPERTY
+            },
+            required:   %w[domain question summary]
+          }
+        },
+        {
+          name:        "events",
+          description: "What actually HAPPENED, with payloads, to one aggregate/record — events THIS DOOR witnessed " \
+                       "(every real dispatch ever routed through it, sourced from its own audit log — not a full " \
+                       "domain-wide event-sourcing replay). Distinct from `state` (what's stored now) and `history` " \
+                       "(append-only operation snapshots, no payload). Narrow with `aggregate` and (requires " \
+                       "`aggregate`) `id`; `limit` keeps only the most recent.",
+          inputSchema: {
+            type:       "object",
+            properties: {
+              domain:    DOMAIN_PROPERTY,
+              aggregate: { type: "string", description: "Narrow to one aggregate, e.g. \"Account\"." },
+              id:        { type: "string", description: "Narrow to one record's own events. Requires `aggregate`." },
+              limit:     { type: "integer", description: "Keep only the most recent N events. Omit for all of them." }
+            },
+            required:   %w[domain]
+          }
+        },
+        {
+          name:        "state",
+          description: "Read what an aggregate actually has stored, no verb involved. Pass `id` for one record; " \
+                       "omit it to list every record the aggregate currently holds.",
+          inputSchema: {
+            type:       "object",
+            properties: {
+              domain:    DOMAIN_PROPERTY,
+              aggregate: { type: "string", description: "The aggregate's name, e.g. \"Account\"." },
+              id:        { type: "string", description: "A specific record's id. Omit to list every record." },
+              summary:   SUMMARY_PROPERTY
+            },
+            required:   %w[domain aggregate summary]
+          }
+        },
+        {
+          name:        "catalog",
+          description: "Zoom level one: every aggregate a domain declares, and every command/query name each " \
+                       "answers to. No summary needed — this changes nothing and commits nothing to any log.",
+          inputSchema: {
+            type:       "object",
+            properties: { domain: DOMAIN_PROPERTY },
+            required:   %w[domain]
+          }
+        },
+        {
+          name:        "describe",
+          description: "Zoom level two: one aggregate's full contract — every command's arguments, the states it " \
+                       "may be issued from, and every way it can refuse. Omit `aggregate` for the whole domain.",
+          inputSchema: {
+            type:       "object",
+            properties: {
+              domain:    DOMAIN_PROPERTY,
+              aggregate: { type: "string", description: "Narrow to one aggregate. Omit for the whole domain." }
+            },
+            required:   %w[domain]
+          }
+        },
+        {
+          name:        "validate",
+          description: "Zoom level three: is this domain's wiring sound — every bind names a declared aggregate, " \
+                       "every adapter satisfies its port, the default adapter is usable. {valid:false, error:…} " \
+                       "on a real wiring defect, never a bare crash. Set `deep: true` to also model-check the IR " \
+                       "for dead lifecycle transitions, unreachable saga states, and dispatches to nowhere.",
+          inputSchema: {
+            type:       "object",
+            properties: {
+              domain: DOMAIN_PROPERTY,
+              deep:   { type: "boolean", description: "Also run the static model checker (lifecycle/saga/policy IR)." }
+            },
+            required:   %w[domain]
+          }
+        },
+        {
+          name:        "domains",
+          description: "Zoom level zero: every domain directory found under a root (default \"examples\"), so a " \
+                       "caller who doesn't already know a path can find one.",
+          inputSchema: {
+            type:       "object",
+            properties: { under: { type: "string", description: "Root directory to scan. Defaults to \"examples\"." } }
+          }
+        },
+        {
+          name:        "history",
+          description: "The full write history for every aggregate in a domain — every operation an append-only " \
+                       "adapter ever recorded, not just current state. An aggregate on a non-append-only adapter " \
+                       "answers an empty history honestly.",
+          inputSchema: {
+            type:       "object",
+            properties: { domain: DOMAIN_PROPERTY },
+            required:   %w[domain]
+          }
+        },
+        {
+          name:        "behaviors",
+          description: "Run a domain's hand-curated `.behaviors` example tests and report pass/fail/error per test. " \
+                       "`target` is a single `.behaviors` file or a directory to sweep.",
+          inputSchema: {
+            type:       "object",
+            properties: { target: { type: "string", description: "A .behaviors file, or a directory to sweep." } },
+            required:   %w[target]
+          }
+        },
+        {
+          name:        "follow",
+          description: "Tail this door's own audit log for a domain — the last `limit` dispatch/query/state/dry-run " \
+                       "calls made through it, each carrying its summary, source, and outcome.",
+          inputSchema: {
+            type:       "object",
+            properties: {
+              domain: DOMAIN_PROPERTY,
+              limit:  { type: "integer", description: "How many recent entries to return. Defaults to 20." }
+            },
+            required:   %w[domain]
+          }
+        }
+      ].freeze
+
+      NOTES = [
+        "Identity is self-asserted: role:/actor_id: are claims made by the caller and are not verified.",
+        "state, events, history, follow, describe, catalog and query run with no role check at all.",
+        "domain: boots real Ruby under #{Storehouse::BOOT_ROOT}; anyone who can write to stdin can run it."
+      ].freeze
+
+      module_function
+
+      # Read once, so a bad setting refuses to start the door before anything is
+      # written to stdout.
+      def scope
+        @scope ||= McpDoorScope.start!(server: Mcp::SERVER)
+      end
+
+      # The standing notes, then what this door's scope says about `domain:`.
+      def warning_notes
+        NOTES[0, 2] + (scope.restricted? ? scope.notes : [NOTES[2]])
+      end
+
+      def serve
+        McpStdioGuard.warn!(server: Mcp::SERVER, notes: warning_notes)
+        $stdout.sync = true
+
+        $stdin.each_line do |line|
+          line = line.strip
+          next if line.empty?
+
+          begin
+            request = JSON.parse(line)
+          rescue JSON::ParserError => e
+            send_error(nil, -32_700, "Parse error: #{e.message}")
+            next
+          end
+
+          begin
+            handle(request)
+          rescue StandardError => e
+            send_error(request["id"], -32_603, "Internal error: #{e.class}: #{e.message}")
+          end
+        end
+      end
+
+      # `domain:` is confined to `Storehouse::BOOT_ROOT`, and further to a reader
+      # door's `HECKS_DOOR_DOMAINS`, before anything boots.
+      def boot(domain)
+        Hecks.boot(Storehouse.confine!(scope.admit_domain!(domain), "domain"), install_facade: false)
+      end
+
+      # One `when` per tool, so the shared `rescue` catches every branch's escape
+      # once; a domain refusal is already `{ok: false, ...}` from `Storehouse`.
+      def call_tool(name, args) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
+        case name
+        when "dispatch"
+          runtime = boot(args["domain"])
+          if args["steps"]
+            Storehouse.dispatch_batch(runtime: runtime, steps: args["steps"], summary: args["summary"],
+                                      source: args["source"], role: args["role"], actor_id: args["actor_id"])
+          else
+            Storehouse.dispatch(runtime: runtime, command: args["command"], summary: args["summary"],
+                                args: args["args"] || {}, source: args["source"],
+                                dry_run: args["dry_run"] == true, role: args["role"], actor_id: args["actor_id"])
+          end
+        when "query"
+          Storehouse.query(runtime: boot(args["domain"]), question: args["question"],
+                           summary: args["summary"], args: args["args"] || {}, source: args["source"],
+                           role: args["role"], actor_id: args["actor_id"])
+        when "events"
+          Storehouse.events(runtime: boot(args["domain"]), aggregate: args["aggregate"], id: args["id"],
+                            limit: args["limit"])
+        when "state"
+          Storehouse.state(runtime: boot(args["domain"]), aggregate: args["aggregate"],
+                           summary: args["summary"], id: args["id"])
+        when "catalog"
+          Storehouse.catalog(runtime: boot(args["domain"]))
+        when "describe"
+          Storehouse.describe(runtime: boot(args["domain"]), aggregate: args["aggregate"])
+        when "validate"
+          Storehouse.validate(domain: scope.admit_domain!(args["domain"]), deep: args["deep"] == true)
+        when "domains"
+          Storehouse.domains(under: args["under"] || "examples")
+        when "history"
+          Storehouse.history(runtime: boot(args["domain"]))
+        when "behaviors"
+          Storehouse.behaviors(target: args["target"])
+        when "follow"
+          Storehouse.follow(runtime: boot(args["domain"]), limit: args["limit"] || 20)
+        else
+          { ok: false, error: "no such tool: #{name.inspect} — known: #{TOOLS.map { |t| t[:name] }.join(', ')}" }
+        end
+      rescue StandardError => e
+        # A defect, not a refusal: reaching here means a bad domain path or an
+        # argument shape `Facade::JsonDoor` could not symbolize.
+        { ok: false, error: "#{e.class}: #{e.message}" }
+      end
+
+      def answer_tool(name, args)
+        return scope.refusal(name) unless scope.permits_tool?(name)
+
+        call_tool(name, args)
+      end
+
+      def tool_result(payload)
+        { content: [{ type: "text", text: JSON.pretty_generate(payload) }], isError: payload[:ok] == false }
+      end
+
+      def send_response(id, result)
+        puts JSON.generate({ jsonrpc: "2.0", id: id, result: result })
+      end
+
+      def send_error(id, code, message)
+        puts JSON.generate({ jsonrpc: "2.0", id: id, error: { code: code, message: message } })
+      end
+
+      def handle(request)
+        id     = request["id"]
+        method = request["method"]
+        params = request["params"] || {}
+
+        case method
+        when "initialize"
+          send_response(id, {
+                          protocolVersion: PROTOCOL_VERSION,
+                          capabilities:    { tools: {} },
+                          serverInfo:      { name: Mcp::SERVER, version: "1.1.0" }
+                        })
+        when "notifications/initialized"
+          nil # a notification — no id, no response
+        when "tools/list"
+          send_response(id, { tools: TOOLS.select { |tool| scope.permits_tool?(tool[:name]) } })
+        when "tools/call"
+          send_response(id, tool_result(answer_tool(params["name"], params["arguments"] || {})))
+        when "ping"
+          send_response(id, {})
+        else
+          send_error(id, -32_601, "Method not found: #{method}") unless id.nil?
+        end
+      end
+    end
+  end
+end

data/lib/hecks/cli/model_check.rb

@@ -0,0 +1,203 @@
+require_relative "../../hecks"
+require_relative "../bluebook/model_check"
+
+module Hecks
+  module CLI
+    # The command behind `bin/model_check` and `hecks model_check`: static analysis
+    # over the IR, printed per domain, exiting non-zero when any error-severity
+    # finding is left — unreachable lifecycle states, dead transitions, unreached
+    # saga states, dispatches to a nonexistent command, handlers for an event
+    # nothing emits. The runtime checks none of these; a dead transition never
+    # fires, in silence.
+    #
+    # Given domain paths it checks just those, cross-domain; given none it sweeps
+    # the repository's corpus and the language's own chapters, which needs `root:`.
+    module ModelCheck
+      # The directory the framework's own `.port` and `.adapter` files live under.
+      HECKS_DIR = File.expand_path("..", __dir__)
+
+      # How one run is configured: `strict` and `profile` from the command line,
+      # `rust_dir` from the root (nil without one).
+      Options = Struct.new(:strict, :profile, :rust_dir)
+
+      module_function
+
+      # Runs the model check `argv` describes and exits with its verdict.
+      #
+      # @param argv [Array<String>] `--strict`, `--profile NAME` and domain paths
+      # @param program [String] the name the usage message calls this command by
+      # @param root [String, nil] the repository root, for the corpus sweep and the
+      #   Rust-target check; nil when there is no checkout
+      # @return [void]
+      # @raise [SystemExit] always: 0 when clean, 1 with findings or a usage error,
+      #   2 for an unknown profile
+      def call(argv, program:, root: nil)
+        argv = argv.dup
+        strict = !argv.delete("--strict").nil?
+        profile = take_profile(argv)
+        unless profile.nil? || Bluebook::ModelCheck::PROFILES.include?(profile)
+          warn "unknown profile #{profile.inspect} (known: #{Bluebook::ModelCheck::PROFILES.join(', ')})"
+          exit 2
+        end
+
+        options = Options.new(strict, profile, root && File.join(root, "rust"))
+        ok = if argv.any? then check_domains(argv, options)
+             elsif root then check_corpus(root, options)
+             else abort "usage: #{program} [--strict] [--profile client] <domain> [<domain> …]"
+             end
+
+        puts
+        puts ok ? "No dead states, no unreachable protocol steps." : "THE MODEL HAS FINDINGS."
+        exit(ok ? 0 : 1)
+      end
+
+      def take_profile(argv)
+        inline = argv.find { |arg| arg.start_with?("--profile=") }
+        index = argv.index("--profile")
+        return unless inline || index
+
+        name = inline ? inline.delete_prefix("--profile=") : argv[index + 1].to_s
+        argv.delete(inline) if inline
+        argv.slice!(index, 2) if index
+        name.to_sym
+      end
+
+      # Examines every named domain against one shared set of known domains and
+      # emitted events, so a cross-domain reaction between two of them is checked.
+      def check_domains(domain_args, options)
+        booted = domain_args.map do |domain_arg|
+          [File.basename(domain_arg.chomp("/")), boot(bluebook_dir(domain_arg.chomp("/")) || domain_arg)]
+        end
+        examine_all(booted, options)
+      end
+
+      # Two passes over the same boots, because a single boot's own registry cannot
+      # answer whether a target domain exists anywhere in the corpus.
+      def check_corpus(root, options)
+        require_relative "../corpus"
+        targets = Corpus.model_check_members(root: root).map { |member| [member.stem, Corpus.source_of(member)] }
+        booted = targets.map { |name, source| [name, boot(source)] }
+        ok = examine_all(booted, options)
+        examine_language(options) && ok
+      end
+
+      # `root:` is the source's parent, so a member declaring
+      # `uses_embryonaut_bluebook` can vendor from it.
+      def boot(source)
+        root = File.directory?(source) ? File.dirname(source) : nil
+        registry = Runtime::Registry.new(root: root)
+        Hecks.with_registry(registry) { load_source(source) }
+        registry
+      end
+
+      # @api private
+      def load_source(source)
+        Kernel.load(File.join(HECKS_DIR, "ports/persistence.port"))
+        Kernel.load(File.join(HECKS_DIR, "ports/extraction.port"))
+        Kernel.load(File.join(HECKS_DIR, "adapters/driven/memory.adapter"))
+        Kernel.load(File.join(HECKS_DIR, "adapters/driven/prism.adapter"))
+        folder = Adapters::Folder.new
+        if File.directory?(source)
+          folder.load_bluebooks(source)
+        else
+          folder.load_bluebooks(File.dirname(source), [File.basename(source)])
+        end
+
+        # A port attaches to its aggregate from the hecksagon, not the bluebook, so a
+        # deaf-policy check that skipped it would miss a policy reacting to an event
+        # nothing emits. Recording a bind builds IR only; no adapter resolves here.
+        hecksagons = if File.directory?(source)
+                       Dir.glob(File.join(source, "*.hecksagon"))
+                     else
+                       [source.sub(/\.bluebook\z/, ".hecksagon")]
+                     end
+        hecksagons.each { |hecksagon| Kernel.load(hecksagon) if File.exist?(hecksagon) }
+      end
+
+      # @api private
+      def examine_all(booted, options)
+        known_domains = booted.flat_map { |_, registry| registry.bluebooks.keys + registry.hecksagons.keys }.to_set
+        global_emitted_events = booted.flat_map do |_, registry|
+          registry.bluebooks.values.flat_map { |chapter| Bluebook::ModelCheck.emitted_events(chapter) }
+        end.to_set
+
+        booted.reduce(true) do |all_ok, (name, registry)|
+          domain_passes?(name, registry, options,
+                         known_domains: known_domains, global_emitted_events: global_emitted_events) && all_ok
+        end
+      end
+
+      def domain_passes?(name, registry, options, known_domains:, global_emitted_events:)
+        puts "── #{name}"
+
+        rust_target = rust_target?(name, options.rust_dir)
+        chapters = registry.bluebooks.values
+        findings = chapters.flat_map do |chapter|
+          Bluebook::ModelCheck.call(chapter, hecksagon: registry.hecksagon(chapter.name), known_domains: known_domains,
+                                             global_emitted_events: global_emitted_events,
+                                             rust_target: rust_target,
+                                             strict: options.strict, profile: options.profile)
+        end
+
+        allowed = Bluebook::ModelCheck::ALLOWED_FINDINGS.fetch(name, [])
+        matched, findings = findings.partition { |f| allowed.include?([f.kind, f.subject]) }
+        matched.each { |f| puts "   ALLOWLISTED  #{f}" }
+
+        stale = allowed - matched.map { |f| [f.kind, f.subject] }
+        unless stale.empty?
+          puts "   STALE ALLOWLIST ENTRIES (no longer found — remove them): #{stale.inspect}"
+          return false
+        end
+
+        passes?(findings, "   clean — #{chapters.size} chapter(s), no dead states, no unreachable protocol steps")
+      end
+
+      # Checked through `MetaValidator.grammar_registry`, the judged graph its
+      # conformance specs use, because any one grammar file booted alone is a
+      # fraction of the language.
+      def examine_language(options)
+        ok = true
+        ["Bluebook", "World"].each do |name|
+          chapter = Bluebook::MetaValidator.grammar_registry.bluebook(name)
+          next unless chapter
+
+          puts "── #{name} (the language itself)"
+          findings = Bluebook::ModelCheck.call(chapter, strict: options.strict, profile: options.profile)
+          ok = passes?(findings, "   clean — no dead states, no unreachable protocol steps") && ok
+        end
+        ok
+      end
+
+      # @api private
+      def passes?(findings, clean_line)
+        if findings.empty?
+          puts clean_line
+          return true
+        end
+
+        errors, warnings = findings.partition { |f| f.severity == :error }
+        puts "   #{errors.size} error(s), #{warnings.size} warning(s)"
+        findings.each { |f| puts "     #{f}" }
+        errors.empty?
+      end
+
+      # The repository-only fuzzing tooling is loaded lazily, only when there is a
+      # `rust/` to read.
+      def rust_target?(name, rust_dir)
+        return false unless rust_dir
+
+        require_relative "../fuzzing/target_capabilities"
+        Fuzzing::TargetCapabilities.rust_feature?(name, rust_dir)
+      end
+
+      # The same rule `Corpus.bluebook_dir` applies.
+      def bluebook_dir(domain_path)
+        [File.join(domain_path, "bluebook"), domain_path].each do |dir|
+          files = Dir[File.join(dir, "*.bluebook")]
+          return File.dirname(files.first) unless files.empty?
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/hecks/cli/project_cli.rb

@@ -0,0 +1,90 @@
+require "fileutils"
+require_relative "../../hecks"
+
+module Hecks
+  module CLI
+    # The command behind `bin/project_cli` and `hecks project_cli`: writes a
+    # command-line launcher beside each domain, named after its bluebook, so
+    # `Hecks.bluebook "QualityControl"` in `qa/` becomes `qa/quality_control`.
+    #
+    # Each launcher is a dozen lines pinning one directory and handing over to
+    # `Facade::CliRunner`; the surface itself is projected at the moment it runs,
+    # so editing a chapter changes behaviour without regenerating anything.
+    module ProjectCli
+      # Build output and other trees under a root that hold no domain a caller means.
+      IGNORED = %r{\A(rust|deploy|tmp|coverage)/}
+
+      module_function
+
+      # `remove_stale_bin` deletes `root/bin/<name>`, where a launcher for the same
+      # chapter would otherwise linger as a second front door.
+      def call(argv, program:, root:, remove_stale_bin: true)
+        wanted = argv.empty? ? domains(root) : argv.map { |path| path.delete_prefix("#{root}/").chomp("/") }
+
+        wanted.each do |path|
+          name  = bluebook_name(root, path) or next
+          snake = Naming.snake(name)
+          file  = File.join(root, path, snake)
+
+          File.write(file, launcher(path, name, program))
+          FileUtils.chmod("+x", file)
+          FileUtils.rm_f(File.join(root, "bin", snake)) if remove_stale_bin
+
+          puts "  #{path}/#{snake}  ->  #{name}"
+        end
+      end
+
+      def domains(root)
+        folder = Adapters::Folder.new
+        Dir.glob(File.join(root, "**/*.hecksagon"))
+           .map { |path| folder.domain_root(File.dirname(path)) }
+           .compact
+           .map { |path| path.delete_prefix("#{root}/") }
+           .grep_v(IGNORED)
+           .uniq.sort
+      end
+
+      # Reads the name from `Hecks.bluebook "…"` rather than the directory, so a
+      # domain using `formerly_known_as` gets a launcher under its current name.
+      def bluebook_name(root, path)
+        Hecks.boot(File.join(root, path), install_facade: false).registry.bluebooks.keys.first
+      rescue StandardError => e
+        warn "  #{path}: cannot boot — #{e.message.lines.first.strip}"
+        nil
+      end
+
+      def launcher(path, name, program)
+        snake = Naming.snake(name)
+        up    = "../" * path.count("/").succ
+
+        <<~RUBY
+          #!/usr/bin/env ruby
+
+          # #{name}'s command line — GENERATED by #{program}. Do not edit.
+          #
+          # A launcher, not a CLI: the verbs, their arguments and their refusals are
+          # projected from the bluebook beside it every time this runs, so a change
+          # to the chapter shows up here without re-minting anything.
+          #
+          #   #{path}/#{snake}                  every verb, and every question
+          #   #{path}/#{snake} <verb> --help    what it wants, and how it refuses
+
+          $LOAD_PATH.unshift File.expand_path("#{up}lib", __dir__)
+
+          require "hecks"
+
+          runtime = begin
+            Hecks.boot(__dir__, install_facade: false)
+          rescue StandardError => e
+            abort "cannot open #{name}: \#{e.message.lines.first.strip}"
+          end
+
+          text, status = Hecks::Facade::CliRunner.call(
+            runtime: runtime, argv: ARGV, program: "#{path}/#{snake}"
+          )
+          status.zero? ? puts(text) : abort(text)
+        RUBY
+      end
+    end
+  end
+end