hecks 2.9.0 → 3.0.0

data/lib/hecks/chapters.rb

@@ -0,0 +1,102 @@
+require_relative "naming"
+require_relative "runtime/registry"
+require_relative "bluebook/meta_validator"
+
+module Hecks
+  # The chapters the gem carries that a hecksagon can attach by name (ADR 0080): the language
+  # declared in itself, Expression, Tenancy, Deploy and QualityControl. Framework members stay in
+  # `Framework`.
+  #
+  # A chapter is named by the `Hecks.bluebook "Name"` header of its files, and may span several.
+  # Beside its bluebook a chapter may carry what every hecksagon attaching it needs, whatever
+  # its store: `<snake_name>.ports.hecksagon` (the ports it declares, as a `Hecks.hecksagon`
+  # block that merges into the attaching one) and `adapters/*.adapter` (the adapters binding them).
+  module Chapters
+    # Where attachable chapters live, relative to `lib/hecks/`.
+    GLOBS = %w[language/**/*.bluebook grammar/expression.bluebook tenancy/bluebook/*.bluebook
+               deploy/bluebook/*.bluebook quality_control/*.bluebook].freeze
+
+    # Every attachable chapter, by name, with the files that declare it.
+    #
+    # @return [Hash{String => Array<String>}] chapter name to its files' absolute paths, sorted
+    def self.index
+      @index ||= GLOBS.flat_map { |glob| Dir.glob(File.join(__dir__, glob)) }.sort
+                      .group_by { |path| chapter_name(path) }
+                      .reject { |name, _| name.nil? }
+                      .freeze
+    end
+
+    # Loads a chapter's files into the current registry, unless it already holds the chapter.
+    #
+    # The files load together inside `MetaValidator.defer`, so a chapter spread over several files
+    # is judged once, whole. The chapter's ports file and adapters load after it, since a port
+    # names the chapter's aggregates.
+    #
+    # @param name [String] the chapter's name, such as `"Deploy"`
+    # @return [Boolean, nil] true when this call loaded the chapter, nil when it was already held
+    # @raise [Runtime::WiringError] if no attachable chapter has that name
+    def self.load!(name)
+      paths = index.fetch(name.to_s) do
+        raise Runtime::WiringError,
+              "no attachable chapter named #{name.inspect} — known: #{index.keys.join(', ')}"
+      end
+      registry = Hecks.current_registry or
+        raise Runtime::WiringError, "attaches #{name.to_s.inspect} outside a boot: no registry is open"
+      return refuse_own_chapter(registry, name.to_s) if registry.bluebook(name.to_s)
+
+      load_atomically(registry, name.to_s, paths)
+      true
+    end
+
+    # Loads a chapter whole or not at all: a raise anywhere leaves the registry as it was, so a
+    # retry loads the chapter again instead of finding a half-built one already held.
+    def self.load_atomically(registry, name, paths)
+      queued = Bluebook::MetaValidator.deferred_chapters.dup
+      ports    = registry.ports.keys
+      adapters = registry.adapters.keys
+      Bluebook::MetaValidator.defer { paths.each { |path| Kernel.load(path) } }
+      Bluebook::MetaValidator.judge_deferred!(registry)
+      load_wiring(name, paths)
+    rescue Exception # rubocop:disable Lint/RescueException -- rolls back, then re-raises
+      registry.forget_chapter(name)
+      Bluebook::MetaValidator.deferred_chapters.replace(queued)
+      registry.ports.delete_if { |key, _| !ports.include?(key) }
+      registry.adapters.delete_if { |key, _| !adapters.include?(key) }
+      raise
+    end
+    private_class_method :load_atomically
+
+    # Returns nil for a chapter this gem already loaded; raises for a chapter of the same name
+    # that a user's own file declared, which `attaches` would otherwise silently take for the
+    # gem's.
+    def self.refuse_own_chapter(registry, name)
+      foreign = Array(registry.bluebook_sources[name]).compact
+                                                      .reject { |path| File.expand_path(path).start_with?("#{__dir__}/") }
+      return if foreign.empty?
+
+      raise Runtime::WiringError,
+            "attaches #{name.inspect}, but a chapter named #{name.inspect} is already declared in " \
+            "#{foreign.join(', ')} — rename it, since the gem's own #{name} chapter cannot merge into it"
+    end
+    private_class_method :refuse_own_chapter
+
+    # Loads what a chapter ships beside its bluebook: its ports file, then its adapters.
+    #
+    # @param name [String] the chapter's name
+    # @param paths [Array<String>] the chapter's bluebook files
+    # @return [void]
+    def self.load_wiring(name, paths)
+      directory = File.dirname(paths.first)
+      ports     = File.join(directory, "#{Naming.snake(name)}.ports.hecksagon")
+      Kernel.load(ports) if File.file?(ports)
+      Dir.glob(File.join(directory, "adapters", "*.adapter")).each { |adapter| Kernel.load(adapter) }
+    end
+    private_class_method :load_wiring
+
+    # The name a file's `Hecks.bluebook "Name"` header declares, or nil for a file without one.
+    def self.chapter_name(path)
+      File.foreach(path) { |line| return Regexp.last_match(1) if line =~ /\A\s*Hecks\.bluebook\s+"([^"]+)"/ }
+      nil
+    end
+  end
+end

data/lib/hecks/cli/behaviors.rb

@@ -0,0 +1,61 @@
+require_relative "../../hecks"
+require_relative "../behaviors"
+
+module Hecks
+  module CLI
+    # The command behind `hecks run_behaviors` and Custodian's `Operation.RunBehaviors`: runs
+    # `.behaviors` files and reports pass, fail or error per test (docs/guides/behaviors.md).
+    module Behaviors
+      module_function
+
+      # Runs one `.behaviors` file, or every one under a directory, and exits with the verdict.
+      #
+      # @param argv [Array<String>] the file or directory to run
+      # @param program [String] the name the usage message calls this command by
+      # @return [void]
+      # @raise [SystemExit] always: 0 when every test passed, 1 when any failed, errored or did
+      #   not parse, or when a directory holds no `.behaviors` file
+      def call(argv, program:)
+        target = argv.first or abort "usage: #{program} <file.behaviors | directory>"
+        abort "no such file or directory: #{target}" unless File.exist?(target)
+
+        if File.directory?(target)
+          sweep = Hecks::Behaviors.run_all(target)
+          abort "no .behaviors files under #{target}" if sweep.files_swept.zero?
+
+          sweep.files.each { |file| report_file(file) }
+          summary = sweep.summary
+          puts
+          puts "#{sweep.files_swept} file(s) swept — #{summary[:total]} test(s): " \
+               "#{summary[:passed]} passed, #{summary[:failed]} failed, #{summary[:errored]} errored, " \
+               "#{summary[:parse_errors]} file(s) failed to parse"
+        else
+          result = Hecks::Behaviors.run(target)
+          report_file(result)
+          summary = Hecks::Behaviors.summarize([result])
+        end
+        exit(bad?(summary) ? 1 : 0)
+      end
+
+      # @api private
+      def report_file(result)
+        puts result.path
+        if result.parse_error
+          puts "  PARSE ERROR — #{result.parse_error}"
+          return
+        end
+
+        result.runs.each do |run|
+          marker = { pass: "ok", fail: "FAIL", error: "ERROR" }.fetch(run.status)
+          puts "  #{marker.ljust(5)} #{run.description}"
+          puts "        #{run.message}" if run.message
+        end
+      end
+
+      # @api private
+      def bad?(summary)
+        ((summary[:failed] || 0) + (summary[:errored] || 0) + (summary[:parse_errors] || 0)).positive?
+      end
+    end
+  end
+end

data/lib/hecks/cli/canonicalise.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "../canonical_json"
+
+module Hecks
+  module CLI
+    # The command behind `hecks canonicalise`: prints a JSON document with every object's keys
+    # sorted, recursively. Key order is not semantics, so a diff a person reads should not have
+    # to notice it moved.
+    module Canonicalise
+      module_function
+
+      # Prints the document at the path in `argv`, canonicalised.
+      #
+      # @param argv [Array<String>] the path of the JSON file, first
+      # @param out [IO] where the document goes
+      # @return [Integer] the exit status, always 0
+      # @raise [IndexError] when no path is given
+      def call(argv, out: $stdout)
+        out.puts Hecks::CanonicalJson.pretty(File.read(argv.fetch(0)))
+        0
+      end
+    end
+  end
+end

data/lib/hecks/cli/check_engine_agreement.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "../../hecks"
+require_relative "../engine_agreement"
+
+module Hecks
+  module CLI
+    # The command behind `hecks check_engine_agreement`: fails when a query engine re-grows its
+    # own comparator dispatch, or when a declared comparator lacks a shared `Comparison` case or
+    # a cross-engine agreement spec. Grep-based.
+    module CheckEngineAgreement
+      module_function
+
+      # Checks the tree and prints the verdict.
+      #
+      # @param root [String] the repository root to check
+      # @param out [IO] where a clean verdict goes
+      # @param err [IO] where the problems go
+      # @return [Integer] 0 when clean, 1 with problems
+      def call(root:, out: $stdout, err: $stderr)
+        finding = Hecks::EngineAgreement.check(root: root)
+        if finding.problems.empty?
+          out.puts Hecks::EngineAgreement.clean_line(finding)
+          return 0
+        end
+
+        err.puts Hecks::EngineAgreement.problem_lines(finding)
+        1
+      end
+    end
+  end
+end

data/lib/hecks/cli/check_era.rb

@@ -0,0 +1,88 @@
+require_relative "../ports/persistence/plugins/era/expected_era"
+
+module Hecks
+  module CLI
+    # The command behind `hecks check_era` and Custodian's `Host.CheckEra`: asks a running host
+    # which era it reports and compares it with an allow-list file. Read-only: one GET, no writes.
+    module CheckEra
+      USAGE = "usage: hecks check_era <url> <expected-era-file> [--timeout=<seconds>]".freeze
+
+      # What a check found.
+      #
+      # @!attribute [r] verdict
+      #   @return [Runtime::EraCheck::ExpectedEra::Verdict] the era compared with the list
+      # @!attribute [r] version
+      #   @return [String] the gem version the host reports, empty when it reports none
+      # @!attribute [r] line
+      #   @return [String] the sentence `hecks check_era` prints for this finding
+      Finding = Struct.new(:verdict, :version, :line)
+
+      module_function
+
+      # Fetches the host's `/version` and compares its era with the allow-list file.
+      #
+      # @param url [String] the host's base URL, or its `/version` URL
+      # @param file [String] path of the allow-list file
+      # @param timeout [Numeric] seconds allowed for connecting and for reading
+      # @return [Finding] the comparison, whether or not the era is listed
+      # @raise [Errno::ENOENT, Errno::EACCES] if the file cannot be read
+      # @raise [Runtime::EraCheck::ExpectedEra::Unreachable] if the host cannot be reached
+      # @raise [Runtime::EraCheck::ExpectedEra::BadResponse] if it answers no era
+      def assess(url, file, timeout: 10)
+        expected = Runtime::EraCheck::ExpectedEra
+        allowed  = expected.parse(File.read(file))
+        document = expected.fetch_version(url, timeout: timeout)
+        verdict  = expected.verdict(document.fetch("era"), allowed)
+        Finding.new(verdict, document.fetch("version"), sentence(verdict, file))
+      end
+
+      # Runs `hecks check_era`: prints the finding and answers the exit status.
+      #
+      # @param argv [Array<String>] the url, the allow-list file and an optional `--timeout=N`
+      # @param out [IO] where a finding goes
+      # @param err [IO] where a refusal goes
+      # @return [Integer] 0 when the era is expected or unlisted, 1 on a mismatch, 2 on bad
+      #   usage or an unreadable file, 3 when the host cannot be reached or answers no era
+      def run(argv, out: $stdout, err: $stderr)
+        timeout = 10
+        args = argv.reject do |arg|
+          next false unless arg.start_with?("--timeout=")
+
+          timeout = arg.delete_prefix("--timeout=").to_f
+          true
+        end
+        url, file = args
+        return usage(err) unless url && file && args.size == 2 && timeout.positive?
+
+        finding = assess(url, file, timeout: timeout)
+        (finding.verdict.ok? ? out : err).puts(finding.line)
+        finding.verdict.ok? ? 0 : 1
+      rescue Errno::ENOENT, Errno::EACCES => e
+        err.puts("cannot read #{file}: #{e.message}")
+        2
+      rescue Runtime::EraCheck::ExpectedEra::Unreachable, Runtime::EraCheck::ExpectedEra::BadResponse => e
+        err.puts("era check failed: #{e.message}")
+        3
+      end
+
+      # @param verdict [Runtime::EraCheck::ExpectedEra::Verdict] the comparison
+      # @param file [String] the allow-list file, named in the sentence
+      # @return [String] the one line that says what the comparison found
+      def sentence(verdict, file)
+        case verdict.status
+        when :match
+          "era #{verdict.era} is expected (#{verdict.allowed.join(', ')})"
+        when :unlisted
+          "host reports era #{verdict.era}; #{file} lists no era, so nothing was compared"
+        else
+          "host reports era #{verdict.era}, which is not in #{file} (expected: #{verdict.allowed.join(', ')})"
+        end
+      end
+
+      def usage(err)
+        err.puts(USAGE)
+        2
+      end
+    end
+  end
+end

data/lib/hecks/cli/console.rb

@@ -0,0 +1,66 @@
+require_relative "../../hecks"
+require "irb"
+# The era/lineage subsystem is a persistence plugin core does not require by default (ADR 0033);
+# a domain passed to the console may bind it.
+require_relative "../ports/persistence/plugins/era"
+
+module Hecks
+  module CLI
+    # The command behind `hecks console` and Custodian's `Operation.OpenConsole`: boots a domain
+    # (pizzas on Memory by default) and drops into IRB with its door installed, for dispatching a
+    # real command by hand. No argument needs no database (ADR 0073); a domain directory boots as
+    # it is wired, which may bind PostgresEra.
+    module Console
+      PIZZAS = File.expand_path("../../../examples/pizzas", __dir__)
+
+      DEFAULT_FILES = [
+        File.join(PIZZAS, "bluebook/pizzas.bluebook"),
+        File.join(PIZZAS, "pizzas_behaviors.hecksagon")
+      ].freeze
+
+      module_function
+
+      # Boots the domain, prints what it declares, and starts IRB; returns when the session ends.
+      #
+      # @param domain [String, nil] a domain directory; the bundled pizzas domain when nil
+      # @param launcher [#call] starts the interactive session; IRB unless a caller stands in
+      # @return [Runtime] the runtime the session ran against
+      def call(domain = nil, launcher: -> { IRB.start(__FILE__) })
+        runtime = domain ? Hecks.boot(domain) : Hecks.boot_files(DEFAULT_FILES)
+        puts overview(runtime)
+        puts banner
+        launcher.call
+        runtime
+      end
+
+      # @param runtime [Runtime] a booted domain
+      # @return [String] each chapter's vision and its aggregates' commands
+      def overview(runtime)
+        runtime.registry.bluebooks.each_value.map do |bluebook|
+          aggregates = bluebook.aggregates.map do |aggregate|
+            commands = aggregate.commands.map { |command| "#{Naming.snake(command.hecks_name)}!" }.sort.join(", ")
+            "    #{aggregate.name}: #{commands}"
+          end
+
+          "\n    #{bluebook.name} — #{bluebook.vision}\n#{aggregates.join("\n")}\n"
+        end.join
+      end
+
+      # @return [String] the version and a first session to try against the pizzas domain
+      def banner
+        <<~BANNER
+
+          hecks #{Hecks::VERSION}
+
+          try:
+            order = Order.create_pizza!(name: { value: "Margherita" }, pizza: { price_cents: { cents: 1200 }, size: { value: "large" } })
+            order.add_topping!(topping: { value: "Basil" }, amount: { value: 3 })
+            order.purchase!(customer_name: { value: "Chris" }, amount: { cents: 1200 })
+            order.status
+            order.events.last
+
+        BANNER
+      end
+    end
+  end
+end

data/lib/hecks/cli/deploy_template_diff.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../projections/deploy/template_diff"
+
+module Hecks
+  module CLI
+    # The command behind `hecks deploy diff` and `hecks deploy diff`: compares two
+    # CloudFormation templates offline and reports differences by logical id; `--strict` also
+    # counts cosmetic differences (comments, key order).
+    module DeployTemplateDiff
+      module_function
+
+      # Prints the comparison and answers the exit status.
+      #
+      # @param argv [Array<String>] `<before.yaml> <after.yaml> [--json] [--strict]`
+      # @param program [String] the name the usage message calls this command by
+      # @return [Integer] 0 when the templates match, 1 when they differ, 2 for bad input
+      # @raise [SystemExit] when there are not exactly two templates
+      def call(argv, program: "hecks deploy diff")
+        options = { json: false, strict: false }
+        parser = OptionParser.new do |opts|
+          opts.banner = "usage: #{program} <before.yaml> <after.yaml> [--json] [--strict]"
+          opts.on("--json", "write the report as JSON") { options[:json] = true }
+          opts.on("--strict", "count cosmetic differences too") { options[:strict] = true }
+        end
+        files = parser.parse(argv)
+        abort parser.banner unless files.size == 2
+
+        diff = Hecks::Projections::Deploy::TemplateDiff
+        report = diff.diff_files(files[0], files[1], strict: options[:strict])
+        puts(options[:json] ? diff.render_json(report) : diff.render(report))
+        report.different? ? 1 : 0
+      rescue ArgumentError => e
+        warn e.message
+        2
+      end
+    end
+  end
+end

data/lib/hecks/cli/doc_coverage.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "../../hecks"
+require_relative "../doc/reference"
+
+module Hecks
+  module CLI
+    # The command behind `hecks measure_doc_coverage`: refuses unless every live word in
+    # `docs/implemented/reference/` has prose and a running example. It checks that an example
+    # exists; `spec/reference_doctest_spec.rb` checks that it passes. `ruby skip` fences and
+    # hidden `<!-- doctest:boot -->` blocks do not count as examples.
+    module DocCoverage
+      module_function
+
+      # Prints the coverage report.
+      #
+      # @param root [String] the repository root
+      # @param out [IO] where the report goes
+      # @param err [IO] where the refusal goes
+      # @return [Integer] 0 when every word is covered, 1 otherwise
+      def call(root:, out: $stdout, err: $stderr)
+        clean, report = Hecks::Doc::Reference.coverage_report(File.join(root, "docs/implemented/reference"))
+        out.puts report
+        return 0 if clean
+
+        err.puts "docs/implemented/reference/ is behind the language. " \
+                 "Regenerate with hecks project_reference to see the words in place."
+        1
+      end
+    end
+  end
+end

data/lib/hecks/cli/document.rb

@@ -2,7 +2,7 @@ require_relative "../../hecks"
 
 module Hecks
   module CLI
-    # The command behind `bin/docs`, `bin/narrate`, `hecks docs` and `hecks narrate`:
+    # The command behind `hecks docs` and `hecks narrate`:
     # one domain's document, projected from its own bluebook, to stdout.
     #
     # Nothing is written for the caller: redirect it, so git decides whether it drifted.
@@ -31,7 +31,7 @@ module Hecks
         refuse_without_domain(program, root) unless path
 
         begin
-          runtime = Hecks.boot(path, install_facade: false)
+          runtime = Hecks.boot(path, install_doors: false)
         rescue StandardError => e
           abort "cannot read #{path}: #{e.message.lines.first.strip}"
         end

data/lib/hecks/cli/expression_projection.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "../projection_files"
+
+module Hecks
+  module CLI
+    # The command behind `hecks project_expression_tables`: projects the expression machinery's
+    # operator and normalisation tables from the grammar chapter into
+    # `lib/hecks/bluebook/expression/projection.json`.
+    #
+    # It never redirects with `>`: the shell would truncate the file the framework requires at
+    # boot. The default mode replaces the file atomically, and it refuses a projection that drops
+    # a self-bearing operator (one the chapter's own `status != "retired"` givens evaluate
+    # through), since that would wedge every later boot. Recover a broken file with
+    # `git checkout -- lib/hecks/bluebook/expression/projection.json`.
+    module ExpressionProjection
+      module_function
+
+      # Rewrites the projection file, or with `--stdout` prints it instead.
+      #
+      # @param argv [Array<String>] `--stdout` for the diff mode
+      # @param out [IO] where the result goes
+      # @return [Integer] the exit status, 0 once written or printed
+      # @raise [SystemExit] with the refusal when the projection drops a self-bearing operator
+      def call(argv, out: $stdout)
+        result = begin
+          Hecks::ProjectionFiles.build(:expression_tables)
+        rescue Hecks::ProjectionFiles::Refused => e
+          abort e.message
+        end
+
+        if argv.include?("--stdout")
+          out.print result.content.values.first
+        else
+          out.puts Hecks::ProjectionFiles.write(:expression_tables)
+        end
+        0
+      end
+    end
+  end
+end

data/lib/hecks/cli/follow.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "../../hecks"
+
+module Hecks
+  module CLI
+    # The command behind `hecks follow`: live-tails a domain's persisted event log as JSON lines.
+    #
+    # Events are one table per domain, so this polls the first repository that answers `:events`
+    # and diffs its size each tick, filtering client-side when `--aggregate` is given.
+    module Follow
+      module_function
+
+      # Tails until interrupted.
+      #
+      # @param argv [Array<String>] `<domain> [--aggregate name] [--interval seconds] [--from-now]`
+      # @param program [String] the name the usage message calls this command by
+      # @return [void]
+      # @raise [SystemExit] when no domain is named or no adapter persists an event log
+      def call(argv, program: "hecks follow")
+        argv = argv.dup
+        domain_name = argv.shift or abort "usage: #{program} <domain> [options]"
+        options = parse(argv, program)
+        repository = event_repository(Hecks.boot(domain_name), domain_name, program)
+        tail(repository, options)
+      end
+
+      # @param argv [Array<String>] the options after the domain; consumed in place
+      # @param program [String] the name the usage banner calls this command by
+      # @return [Hash] `:interval`, `:from_now` and, when given, `:aggregate`
+      def parse(argv, program)
+        options = { interval: 0.5, from_now: false }
+        OptionParser.new do |parser|
+          parser.banner = "usage: #{program} <domain> [options]"
+          parser.on("-a", "--aggregate=NAME", "Only follow events for this aggregate (e.g. Order)") do |name|
+            options[:aggregate] = name
+          end
+          parser.on("-i", "--interval=SECONDS", Float, "Poll interval in seconds (default: 0.5)") { |v| options[:interval] = v }
+          parser.on("--from-now", "Skip existing events; only print ones emitted from now on") { options[:from_now] = true }
+        end.parse!(argv)
+        options
+      end
+
+      # @param runtime [Runtime] a booted domain
+      # @param domain_name [String] its name, for the refusal
+      # @param program [String] the name the refusal calls this command by
+      # @return [Object] the first repository that answers `:events`
+      # @raise [SystemExit] when none does
+      def event_repository(runtime, domain_name, program)
+        repositories = runtime.registry.bluebooks.flat_map do |bluebook_domain, bluebook|
+          bluebook.aggregates.map { |aggregate| runtime.registry.repository(bluebook_domain, aggregate) }
+        end
+        repositories.find { |repo| repo.respond_to?(:events) } or
+          abort "#{program}: no adapter in #{domain_name} persists an event log"
+      end
+
+      # Says whether `event` passes the `--aggregate` filter: a bare name matched
+      # case-insensitively, or the exact name.
+      #
+      # @param event [Object] a logged event
+      # @param filter [String, nil] the aggregate name asked for
+      # @return [Boolean]
+      def matches?(event, filter)
+        filter.nil? || event.aggregate.to_s.split("::").last.casecmp?(filter) || event.aggregate == filter
+      end
+
+      # @param repository [Object] answers `events`
+      # @param options [Hash] the parsed options
+      # @return [void]
+      def tail(repository, options)
+        seen = options[:from_now] ? repository.events.size : 0
+        $stdout.sync = true
+        trap("INT") { exit }
+
+        loop do
+          events = repository.events
+          if events.size > seen
+            events[seen..].each { |event| puts JSON.generate(event.to_h) if matches?(event, options[:aggregate]) }
+            seen = events.size
+          end
+          sleep options[:interval]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/cli/history.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../../hecks"
+
+module Hecks
+  module CLI
+    # The command behind `hecks history` and `hecks history`: every journal entry a domain's
+    # append-only adapters hold, as JSON, the full write history rather than the current head.
+    module History
+      module_function
+
+      # Boots the domain `argv` names and prints its history as one JSON document.
+      #
+      # @param argv [Array<String>] the domain directory, first
+      # @param program [String] the name the usage message calls this command by
+      # @return [void]
+      # @raise [SystemExit] when `argv` is empty
+      def call(argv, program: "hecks history")
+        domain = argv.first or abort "usage: #{program} <domain>"
+        puts JSON.generate(document(Hecks.boot(domain).registry))
+      end
+
+      # @param registry [Runtime::Registry] a booted domain's registry
+      # @return [Hash{String => Array<Hash>}] each aggregate's storage name mapped to its entries
+      def document(registry)
+        registry.bluebooks.each_with_object({}) do |(name, bluebook), all|
+          bluebook.aggregates.each do |aggregate|
+            all[aggregate.storage_name] = entries(registry.repository(name, aggregate))
+          end
+        end
+      end
+
+      # @param repository [Object] an aggregate's repository
+      # @return [Array<Hash{String => Object}>] its journal entries; empty
+      #   when it is not append-only
+      def entries(repository)
+        return [] unless repository.is_a?(Ports::Persistence::AppendOnly)
+
+        repository.entries.map { |entry| { "operation" => entry.operation, "id" => entry.id, "state" => entry.state } }
+      end
+    end
+  end
+end

data/lib/hecks/cli/ir.rb

@@ -5,7 +5,7 @@ require_relative "../ports/persistence/plugins/era"
 
 module Hecks
   module CLI
-    # The command behind `bin/ir` and `hecks ir`: a booted domain's IR as JSON, the
+    # The command behind `hecks ir`: a booted domain's IR as JSON, the
     # same `to_h` the golden specs pin and `StorageShape` hashes into an era.
     module Ir
       module_function

data/lib/hecks/cli/mcp.rb

@@ -2,7 +2,7 @@ require_relative "../mcp_stdio_guard"
 
 module Hecks
   module CLI
-    # The command behind `bin/hecks_mcp_door` and `hecks mcp`: the MCP door onto the
+    # The command behind `hecks mcp`: the MCP door onto the
     # storehouse bus, over stdio only.
     #
     # This file loads nothing but `McpStdioGuard`, so the transport check runs
@@ -23,8 +23,8 @@ module Hecks
       #   set up for stdio
       def call(argv)
         McpStdioGuard.enforce_stdio!(server: SERVER, argv: argv)
-        require_relative "mcp_door"
-        McpDoor.serve
+        require_relative "../doors/mcp_door"
+        Doors::McpDoor.serve
       end
     end
   end