hecks 2.8.0 → 3.0.0

data/lib/hecks/cli/release.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../release/runner"
+
+module Hecks
+  module CLI
+    # The command behind `hecks publish`: tags the merged release commit, publishes the gem, and
+    # gets `@hecks/client` published to npm. See "Releasing" in CONTRIBUTING.md for the release PR.
+    #
+    #   hecks publish --dry-run    # every check and build, nothing tagged or published
+    #   hecks publish              # tag, gem, then wait for CI to publish the client
+    module Release
+      # The flags a run starts with, before any is named.
+      DEFAULT_FLAGS = { dry_run: false, gem_only: false, npm_only: false, npm_local: false,
+                        no_wait: false, yes: false }.freeze
+
+      module_function
+
+      # Parses the flags and runs the release.
+      #
+      # @param argv [Array<String>] the command line's flags
+      # @param root [String] the repository root the release runs in
+      # @return [Integer] the release's exit status, or 2 for a flag it does not know
+      def call(argv, root:)
+        argv = argv.dup
+        flags = DEFAULT_FLAGS.dup
+        parser = parser_for(flags)
+        begin
+          parser.parse!(argv)
+          raise OptionParser::InvalidArgument, argv.join(" ") unless argv.empty?
+
+          return 0 if flags.delete(:help)
+
+          options = Hecks::Release::Runner::Options.new(**flags)
+        rescue OptionParser::ParseError, ArgumentError => e
+          warn "hecks publish: #{e.message}"
+          warn parser
+          return 2
+        end
+
+        Hecks::Release::Runner.new(root: root, options: options).call
+      end
+
+      # @param flags [Hash{Symbol => Boolean}] filled in as the parser reads each flag
+      # @return [OptionParser] the parser for `hecks publish`'s flags
+      def parser_for(flags)
+        OptionParser.new do |opts|
+          opts.banner = "Usage: hecks publish [--dry-run] [--gem-only | --npm-only] [--npm-local | --no-wait] [--yes]"
+          opts.separator("Tags the merged release commit, publishes the gem, and gets @hecks/client published.")
+          opts.separator("By default CI publishes the client from the tag and this waits for it.")
+          opts.on("--dry-run", "run every check and build; tag, push and publish nothing") { flags[:dry_run] = true }
+          opts.on("--gem-only", "publish the gem only") { flags[:gem_only] = true }
+          opts.on("--npm-only", "skip the gem: wait for CI's publish, or with --npm-local publish from here") do
+            flags[:npm_only] = true
+          end
+          opts.on("--npm-local", "publish @hecks/client from this machine (first publish, or CI is down)") do
+            flags[:npm_local] = true
+          end
+          opts.on("--no-wait", "do not wait for CI's publish to reach npm") { flags[:no_wait] = true }
+          opts.on("--yes", "answer the confirmations yes") { flags[:yes] = true }
+          opts.on("--help", "print this usage") do
+            puts opts
+            flags[:help] = true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/cli/release_gem.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../release/runner/commands"
+require_relative "../hecks/adapters/codebase/gem_registry"
+require_relative "../version"
+
+module Hecks
+  module CLI
+    # The command behind `hecks publish_gem` and the release runner's gem step: builds the hecks
+    # gem and pushes it to rubygems.org, using a push-scoped API key from 1Password instead of
+    # `~/.gem/credentials`. It pushes the version it is given, `Hecks::VERSION` by default.
+    module ReleaseGem
+      module_function
+
+      # Builds and pushes the gem, refusing unless `op` is installed and the JS client is at the
+      # same version (`spec/hecks_client_version_spec.rb` pins that rule too).
+      #
+      # @param root [String] the repository root the gem is built from
+      # @param commands [#run!, #capture, nil] runs the child commands; a real one when nil
+      # @param out [IO] where progress goes
+      # @param err [IO] where a refusal goes
+      # @param version [String] the version to build and push
+      # @return [Integer] 0 once pushed, 1 when refused
+      def call(root:, commands: nil, out: $stdout, err: $stderr, version: Hecks::VERSION)
+        Dir.chdir(root) do
+          commands ||= Hecks::Release::Runner::Commands.new
+          registry = Hecks::Adapters::Codebase::GemRegistry.new(root: root, commands: commands)
+          refusal = refusal_for(root, commands, version)
+          if refusal
+            err.puts refusal
+            return 1
+          end
+
+          out.puts "Building and pushing hecks-#{version}.gem to rubygems.org " \
+                   "(1Password will prompt for Touch ID)..."
+          registry.push!(version)
+          out.puts "Released hecks #{version}."
+          0
+        end
+      end
+
+      # @param root [String] the repository root
+      # @param commands [#run!, #capture] runs the child commands
+      # @param version [String] the version being released
+      # @return [String, nil] why the release cannot start, or nil when it can
+      def refusal_for(root, commands, version = Hecks::VERSION)
+        unless Hecks::Adapters::Codebase::SecretVault.new(commands: commands).installed?
+          return "1Password CLI (op) not found. Install: brew install 1password-cli"
+        end
+
+        client_version = JSON.parse(File.read(File.join(root, "packages/hecks-client/package.json"))).fetch("version")
+        return nil if client_version == version
+
+        "packages/hecks-client is at #{client_version} but Hecks::VERSION is #{version}; bump the package first."
+      end
+    end
+  end
+end

data/lib/hecks/cli/rspec_io_parallel_files.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module Hecks
+  module CLI
+    # The command behind `hecks list_io_parallel_specs`: prints, one per line, the spec files with
+    # at least one example matching an RSpec tag filter. ci.yml hands the list to `parallel_rspec`
+    # instead of the whole `spec` directory.
+    #
+    # Given every spec file, parallel_tests ignores the runtime log unless it covers about 67% of
+    # them, so a tag-filtered job silently groups by file size. A dry run, not grep, picks the
+    # files so inherited tags, `~fuzzing` and shared examples count.
+    #
+    # The list is committed (`.github/postgres_io_spec_files.txt`). `--write FILE` refreshes it;
+    # `--check FILE` (CI's postgres_io_file_list job) fails on a stale list.
+    #
+    #   hecks list_io_parallel_specs '<exclude-pattern regex>' -- --tag io --tag ~fuzzing
+    module RspecIoParallelFiles
+      module_function
+
+      # Lists the matching files, writes them, or checks a committed list.
+      #
+      # @param argv [Array<String>] `--check FILE` or `--write FILE` optionally, the exclude
+      #   pattern, `--`, then the RSpec tag arguments
+      # @param root [String] the checkout whose `spec/` is searched; the dry run runs there
+      # @param out [IO] where the list goes when neither flag is given
+      # @param err [IO] where the tally and any staleness go
+      # @return [Integer] the exit status, 0 once done
+      # @raise [SystemExit] on a bad command line, an empty candidate set, a failed dry run, or a
+      #   stale committed list
+      def call(argv, root: Dir.pwd, out: $stdout, err: $stderr)
+        argv = argv.dup
+        mode, list_path = argv.shift(2) if %w[--check --write].include?(argv.first)
+        abort "hecks list_io_parallel_specs: #{mode} needs a file path" if mode && list_path.nil?
+
+        exclude_arg, tag_args = parse(argv)
+        candidates = Dir.glob("spec/**/*_spec.rb", base: root).grep_v(Regexp.new(exclude_arg)).sort
+        refuse_empty_candidates(candidates)
+        files, example_count = matching_files(candidates, tag_args, root, err)
+        err.puts "hecks list_io_parallel_specs: #{files.size} of #{candidates.size} candidate files carry a " \
+                 "matching example (#{example_count} examples total) under `#{tag_args.join(' ')}`"
+
+        case mode
+        when "--write" then File.write(File.expand_path(list_path, root), "#{files.join("\n")}\n")
+        when "--check" then check(files, File.expand_path(list_path, root), list_path, exclude_arg, tag_args, err)
+        else out.puts files
+        end
+        0
+      end
+
+      # @param argv [Array<String>] the exclude pattern, `--`, and the tag arguments
+      # @return [Array(String, Array<String>)] the pattern and the tag arguments
+      # @raise [SystemExit] with the usage line when either is missing
+      def parse(argv)
+        exclude_arg, *rest = argv
+        separator = rest.index("--")
+        usage = "usage: hecks list_io_parallel_specs '<exclude-pattern regex>' -- <rspec tag args...>"
+        abort usage unless exclude_arg && separator
+        tag_args = rest[(separator + 1)..]
+        abort usage if tag_args.nil? || tag_args.empty?
+
+        [exclude_arg, tag_args]
+      end
+
+      # @param candidates [Array<String>] the spec files left after the exclude pattern
+      # @return [void]
+      # @raise [SystemExit] when there are none, which means a broken pattern or an empty checkout
+      def refuse_empty_candidates(candidates)
+        return unless candidates.empty?
+
+        abort "hecks list_io_parallel_specs: found ZERO candidate spec files after applying the exclude " \
+              "pattern — that's almost certainly a broken pattern or an empty checkout, not a real empty " \
+              "test suite. Refusing to silently hand parallel_rspec nothing to run."
+      end
+
+      # Asks RSpec for a dry run of the candidates under the tag filter.
+      #
+      # @param candidates [Array<String>] the spec files to ask about
+      # @param tag_args [Array<String>] the RSpec tag arguments
+      # @param root [String] the directory the dry run runs in
+      # @param err [IO] where a failed run's stderr goes
+      # @return [Array(Array<String>, Integer)] the files with a matching example, and how many
+      #   examples matched
+      # @raise [SystemExit] when the dry run fails, prints no JSON, or matches nothing
+      def matching_files(candidates, tag_args, root, err)
+        command = ["bundle", "exec", "rspec", "--dry-run", *tag_args, "--format", "json", *candidates]
+        stdout, stderr, status = Open3.capture3(*command, chdir: root)
+        unless status.success?
+          err.puts stderr
+          abort "hecks list_io_parallel_specs: `#{command.join(' ')}` exited #{status.exitstatus} — " \
+                "see stderr above. Refusing to guess a file list from a failed dry run."
+        end
+
+        start = stdout.index('{"version"')
+        abort "hecks list_io_parallel_specs: couldn't find RSpec's JSON output in the dry-run's stdout:\n#{stdout}" unless start
+
+        examples = JSON.parse(stdout[start..])["examples"] || []
+        files = examples.map { |e| e.fetch("file_path").sub(%r{\A\./}, "") }.uniq.sort
+        return [files, examples.size] unless files.empty?
+
+        abort "hecks list_io_parallel_specs: #{candidates.size} candidate files, but the dry run matched ZERO " \
+              "examples under `#{tag_args.join(' ')}` — that's almost certainly a broken tag filter, not a " \
+              "real empty set. Refusing to silently hand parallel_rspec nothing to run."
+      end
+
+      # @param files [Array<String>] the files that carry a matching example
+      # @param path [String] the committed list's absolute path
+      # @param shown [String] the path as the person typed it
+      # @param exclude_arg [String] the exclude pattern, for the refresh command
+      # @param tag_args [Array<String>] the tag arguments, for the refresh command
+      # @param err [IO] where the difference goes
+      # @return [void]
+      # @raise [SystemExit] when the committed list differs
+      def check(files, path, shown, exclude_arg, tag_args, err)
+        committed = File.exist?(path) ? File.readlines(path, chomp: true).reject(&:empty?) : []
+        missing = files - committed
+        stale = committed - files
+        return if missing.empty? && stale.empty?
+
+        err.puts "#{shown} is out of date."
+        err.puts named("carries a matching example but is not listed (would never run in the shards)", missing) if missing.any?
+        err.puts named("listed but carries no matching example any more", stale) if stale.any?
+        abort "Refresh it and commit the result:\n  " \
+              "hecks list_io_parallel_specs --write #{shown} '#{exclude_arg}' -- #{tag_args.join(' ')}"
+      end
+
+      # @param heading [String] what the paths have in common
+      # @param paths [Array<String>] the paths
+      # @return [String] the heading with the paths under it
+      def named(heading, paths)
+        "  #{heading}:\n    #{paths.join("\n    ")}"
+      end
+    end
+  end
+end

data/lib/hecks/cli/rspec_shard_files.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "parallel_tests/test/runner"
+
+module Hecks
+  module CLI
+    # The command behind `hecks shard_specs`: prints the spec files assigned to one group
+    # (1-indexed) of a runtime-balanced N-way split. `rspec_shard` in ci-rspec.yml passes the
+    # committed runtime baseline so every leg agrees.
+    #
+    # It does not use `parallel_rspec --only-group`, which forces one process per leg; this suite
+    # is CPU-bound, so each leg would use one of four vCPUs. The group's list comes from
+    # `tests_in_groups`, leaving `parallel_rspec` its own workers.
+    module RspecShardFiles
+      USAGE = "usage: hecks shard_specs <group 1-indexed> <num_groups> [runtime_log_path]"
+
+      module_function
+
+      # Prints the files of one group.
+      #
+      # @param argv [Array<String>] the group, the number of groups, and optionally a runtime log
+      # @param root [String] the checkout whose `spec/` is split
+      # @param out [IO] where the files go, one per line
+      # @param err [IO] where the group's size goes
+      # @return [Integer] the exit status, 0 once printed
+      # @raise [SystemExit] on missing or out-of-range arguments, or when there are no spec files
+      def call(argv, root: Dir.pwd, out: $stdout, err: $stderr)
+        group_arg, num_groups_arg, runtime_log = argv
+        abort USAGE unless group_arg && num_groups_arg
+
+        group = Integer(group_arg)
+        num_groups = Integer(num_groups_arg)
+        abort "group must be between 1 and #{num_groups}, got #{group}" unless (1..num_groups).cover?(group)
+
+        files = Dir.glob("spec/**/*_spec.rb", base: root)
+        if files.empty?
+          abort "hecks shard_specs: found ZERO spec files under spec/ — " \
+                "refusing to hand parallel_rspec nothing to run"
+        end
+
+        groups = Dir.chdir(root) { groups_of(files, num_groups, runtime_log && File.expand_path(runtime_log, root)) }
+        selected = groups[group - 1] || []
+        err.puts "hecks shard_specs: group #{group}/#{num_groups} has #{selected.size} of #{files.size} files"
+        out.puts selected
+        0
+      end
+
+      # Splits the files by recorded runtime, falling back to file size on a cold cache.
+      #
+      # `allowed_missing_percent` covers gaps inside a log, not a missing file (`Runner.runtimes`
+      # raises `Errno::ENOENT`).
+      #
+      # @param files [Array<String>] the spec files, relative to the checkout
+      # @param num_groups [Integer] how many groups to split into
+      # @param runtime_log [String, nil] the runtime log's path, used when the file exists
+      # @return [Array<Array<String>>] the files of each group
+      def groups_of(files, num_groups, runtime_log)
+        options = { group_by: :runtime, allowed_missing_percent: 100 }
+        options[:runtime_log] = runtime_log if runtime_log && File.exist?(runtime_log)
+        ParallelTests::Test::Runner.tests_in_groups(files, num_groups, **options)
+      rescue Errno::ENOENT
+        ParallelTests::Test::Runner.tests_in_groups(files, num_groups, group_by: :filesize)
+      end
+    end
+  end
+end

data/lib/hecks/cli/run.rb

@@ -6,24 +6,16 @@ require_relative "../ports/persistence/plugins/era"
 
 module Hecks
   module CLI
-    # The command behind `bin/run` and `hecks run`: dispatches one verb from the
+    # The command behind `hecks run`: dispatches one verb from the
     # command line, or executes a JSON step list and reports instances, events,
     # refusals, reactions, sagas and query rows.
     #
-    # ## Two forms, one argument
-    #
-    # `run bug.discover reference=BUG#1 severity=high …` needs no JSON. The verb
-    # tree, every argument, its declared type and every way the verb can refuse are
-    # projected out of the bluebook (`Projector::CliProjector`) and run by
-    # `Facade::CliRunner`, so this knows nothing about any domain and its help
-    # cannot go stale. The step-list form takes a script path, `-` for stdin, or the
-    # JSON itself, which is how the corpus scripts under `spec/corpus/` are run.
-    #
-    # ## Standing in a domain is enough
-    #
-    # `Adapters::Folder#domain_root` walks up for the nearest `.hecksagon`, so inside
-    # a domain the path can be left off. The first argument is a domain only when it
-    # is a directory.
+    # `run bug.discover reference=BUG#1 severity=high …` needs no JSON; the verb
+    # tree and its arguments are projected from the bluebook, so this knows nothing
+    # about any domain and its help cannot go stale. The step-list form takes a
+    # script path, `-` for stdin, or the JSON itself. The first argument is a
+    # domain only when it is a directory; otherwise the nearest enclosing one is
+    # used.
     module Run
       module_function
 
@@ -59,40 +51,20 @@ module Hecks
         abort unmet.join("\n") unless unmet.empty?
       end
 
-      # Boots `domain` and dispatches `argv` as a projected verb invocation, printing
-      # the result and exiting the process.
-      #
-      # **No fall-through**. This is reached only when the argument is not
-      # script-shaped, so a near miss deserves the runner's "did you mean" rather
-      # than the step-list form's "no such script".
-      #
-      # @param domain [String] the domain's directory path
-      # @param argv [Array<String>] the arguments after the domain, e.g.
-      #   `["bug.discover", "reference=BUG#1"]`
-      # @param program [String] the name the runner's help calls this command by
-      # @return [void]
-      # @raise [SystemExit] always
+      # No fall-through: reached only when the argument is not script-shaped, so a
+      # near miss deserves the runner's "did you mean" rather than the step-list
+      # form's "no such script".
       def cli_form(domain, argv, program)
-        runtime = Hecks.boot(domain, install_facade: false)
-        text, status = Facade::CliRunner.call(runtime: runtime, argv: argv, program: program)
+        runtime = Hecks.boot(domain, install_doors: false)
+        text, status = Doors::CliRunner.call(runtime: runtime, argv: argv, program: program)
         status.zero? ? puts(text) : abort(text)
         exit 0
       end
 
-      # Says whether `arg` is a step list rather than a verb: stdin, inline JSON, or
-      # a file that exists.
-      #
-      # @param arg [String] the first argument after the domain
-      # @return [Boolean] true when `arg` is script-shaped
       def script_shaped?(arg) = arg == "-" || arg.match?(/\A\s*\{/) || File.file?(arg)
 
-      # Reads the step list from stdin, from the argument itself, or from a file,
-      # decided by looking, because a script beginning with `{` is not a filename
+      # Decided by looking, because a script beginning with `{` is not a filename
       # anybody meant.
-      #
-      # @param script [String] `-`, inline JSON, or a file path
-      # @return [String] the script's JSON text
-      # @raise [SystemExit] when `script` names no file
       def read_source(script)
         case script
         when "-" then $stdin.read
@@ -102,25 +74,14 @@ module Hecks
         end
       end
 
-      # Parses the step list before anything boots, because booting opens a real
-      # store and a typo in the JSON should cost a sentence, not a connection.
-      #
-      # @param source [String] the script's JSON text
-      # @return [Hash{String => Object}] the parsed script
-      # @raise [SystemExit] when `source` is not JSON
+      # Parsed before anything boots, because booting opens a real store and a typo
+      # in the JSON should cost a sentence, not a connection.
       def parse(source)
         JSON.parse(source)
       rescue JSON::ParserError => e
         abort "that is not JSON: #{e.message.lines.first.strip}"
       end
 
-      # Runs every step and gathers what the runtime holds afterwards.
-      #
-      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain
-      # @param steps [Array<Hash{String => Object}>] the script's steps, each a
-      #   `"verb"` or a `"query"` with optional `"args"`
-      # @return [Hash{Symbol => Object}] `:instances`, `:events`, `:refusals`,
-      #   `:reactions`, `:sagas` and `:queries`, in the order they are printed
       def execute(runtime, steps)
         refusals = []
         queries = []
@@ -171,13 +132,6 @@ module Hecks
         end
       end
 
-      # Checks the script's `"expectations"` against what the run produced.
-      #
-      # @param expectations [Hash{String => Object}] the script's `"event_names"`,
-      #   `"refusals"` and `"instances"` expectations; `{}` when it declares none
-      # @param report [Hash{Symbol => Object}] what `execute` answered
-      # @return [Array<String>] one message per unmet expectation; empty when every
-      #   one held
       def unmet_expectations(expectations, report)
         missing_events = Array(expectations["event_names"]) - report[:events].map { |event| event[:name] }
         unmet = []

data/lib/hecks/cli/seed_semantics_corpus.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../../hecks"
+require_relative "../fuzzing"
+
+module Hecks
+  module CLI
+    # The command behind `hecks seed_semantics_corpus`: seeds (or deliberately re-seeds) the
+    # `expect` block of semantics-corpus fixtures from the Ruby runtime. Review the result
+    # against `docs/semantics/bluebook-semantics.md` before committing.
+    #
+    #   hecks seed_semantics_corpus                                # fill fixtures missing an expect
+    #   SEED=refusal_kind_lifecycle hecks seed_semantics_corpus    # re-seed one, deliberately
+    #
+    # The seeded expectation is the definition, not a recording: both runtimes are compared to it.
+    # `occurred_at` is stripped from events (C7.3/C9.1); refusals keep verb, error and kind (C8.2).
+    module SeedSemanticsCorpus
+      module_function
+
+      # Seeds the fixtures that need it and reports which.
+      #
+      # @param root [String] the checkout whose `spec/corpus/semantics/` is seeded
+      # @param env [Hash{String => String}] `SEED` names the one fixture to re-seed
+      # @param out [IO] where the report goes
+      # @return [Integer] the exit status, always 0
+      def call(root:, env: ENV, out: $stdout)
+        only = env.fetch("SEED", nil)
+        seeded = Dir.glob(File.join(root, "spec/corpus/semantics", "*.json")).filter_map do |path|
+          fixture = JSON.parse(File.read(path))
+          name = File.basename(path, ".json")
+          next if only ? only != name : fixture.key?("expect")
+
+          fixture["expect"] = expectation_for(root, fixture)
+          File.write(path, "#{JSON.pretty_generate(fixture)}\n")
+          name
+        end
+        report(out, seeded)
+        0
+      end
+
+      # Replays the fixture's script against the Ruby runtime. Each refusal's `"kind"` is reduced
+      # to its class name; `occurred_at` is stripped from events.
+      #
+      # @param root [String] the checkout the fixture's domain path is relative to
+      # @param fixture [Hash] the parsed fixture: `domain` and `steps`
+      # @return [Hash{String => Array}] its `"expect"` block: refusals, instances, events
+      def expectation_for(root, fixture)
+        result = Hecks::Fuzzing::Replay.call(File.join(root, fixture["domain"]), fixture["steps"])
+        {
+          "refusals"  => JSON.parse(JSON.generate(result[:refusals])).each { |r| r["kind"] = r["kind"]&.split("::")&.last },
+          "instances" => JSON.parse(JSON.generate(result[:instances])),
+          "events"    => JSON.parse(JSON.generate(result[:events])).each { |e| e.delete("occurred_at") }
+        }
+      end
+
+      # @param out [IO] where the report goes
+      # @param seeded [Array<String>] the fixtures written
+      # @return [void]
+      def report(out, seeded)
+        if seeded.empty?
+          out.puts "nothing to seed — every fixture carries its expect (pass SEED=<name> to re-seed one deliberately)"
+        else
+          out.puts "seeded: #{seeded.join(', ')}"
+          out.puts "review each expect against docs/semantics/bluebook-semantics.md before committing — " \
+                   "it is the definition now"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/cli/serve_query_ir_mcp.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "../mcp_stdio_guard"
+
+module Hecks
+  module CLI
+    # The command behind `hecks serve_query_ir_mcp` and `hecks serve_query_ir_mcp`: an MCP server
+    # exposing `Hecks::QueryIR`'s queries as tools, over newline-delimited JSON-RPC on stdio.
+    #
+    # Stdio only and unauthenticated (ADR 0062); the protocol lives in `Hecks::QueryIrMcp` and the
+    # query logic in `Hecks::QueryIR`. The stdio guard runs before the runtime loads, so a refused
+    # transport never boots anything.
+    module ServeQueryIrMcp
+      module_function
+
+      # Enforces stdio, then serves until stdin closes.
+      #
+      # @param argv [Array<String>] the arguments the server was started with
+      # @return [void]
+      # @raise [SystemExit] when the guard refuses the transport
+      def call(argv)
+        Hecks::McpStdioGuard.enforce_stdio!(server: "hecks-query-ir")
+
+        require_relative "../../hecks"
+        require_relative "../query_ir_mcp"
+        Hecks::QueryIrMcp.start(argv: argv)
+      end
+    end
+  end
+end

data/lib/hecks/cli/shape.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../../hecks"
+# The `:shape` projection reads `Runtime::StorageShape`, which lives in the era persistence plugin
+# core does not load by default (ADR 0033).
+require_relative "../ports/persistence/plugins/era"
+
+module Hecks
+  module CLI
+    # The command behind `hecks shape` and `hecks shape`: a bluebook's storage-shape projection, the
+    # same hash PostgresEra mints an era's label from, so two runs diff to show whether a bluebook
+    # change would bump an era.
+    module Shape
+      module_function
+
+      # Prints the projection of a bluebook file as JSON, or one `<Domain> <label>` line per domain
+      # of a directory (files in subdirectories are not read).
+      #
+      # @param argv [Array<String>] the bluebook file or directory, first
+      # @param program [String] the name the usage message calls this command by
+      # @return [void]
+      # @raise [SystemExit] when `argv` is empty, the path is missing or holds no bluebook
+      def call(argv, program: "hecks shape")
+        target = argv.first or abort "usage: #{program} <bluebook | directory of *.bluebook files>"
+        puts render(target)
+      rescue Runtime::NotFound => e
+        abort e.message
+      end
+
+      # @param target [String] a bluebook file, or a directory of them
+      # @return [String] the storage-shape projection as JSON for a file, or one
+      #   `<Domain> <label>` line per domain for a directory
+      # @raise [Runtime::NotFound] if the path does not exist or holds no bluebook
+      def render(target)
+        raise Runtime::NotFound, "#{target} does not exist" unless File.exist?(target)
+
+        directory = File.directory?(target)
+        files = directory ? Dir[File.join(target, "*.bluebook")] : [target]
+        raise Runtime::NotFound, "no *.bluebook files in #{target}" if files.empty?
+
+        registry = load_files(files)
+        return labels(registry) if directory
+
+        bluebook = registry.bluebooks.values.first or raise Runtime::NotFound, "#{target} declares no bluebook"
+        JSON.pretty_generate(Projector.call(:shape, bluebook: bluebook))
+      end
+
+      # @param files [Array<String>] bluebook files
+      # @return [Runtime::Registry] a registry holding every bluebook the files declare
+      def load_files(files)
+        registry = Runtime::Registry.new
+        loading  = Ports::Loading.bootstrap
+        Hecks.with_registry(registry) do
+          loading.load_library
+          files.each { |file| Kernel.eval(File.read(file), TOPLEVEL_BINDING, File.expand_path(file), 1) }
+        end
+        registry
+      end
+
+      # @param registry [Runtime::Registry] a loaded registry
+      # @return [String] one `<Domain> <label>` line per bluebook, sorted by name
+      def labels(registry)
+        registry.bluebooks.sort_by { |name, _| name.to_s }
+                .map { |name, bluebook| "#{name} #{Runtime::StorageShape.mint_label(bluebook)}" }
+                .join("\n")
+      end
+    end
+  end
+end