hecks 2.7.0 → 2.9.0

data/lib/hecks/cli/project_diagrams.rb

@@ -0,0 +1,36 @@
+require_relative "../../hecks"
+
+module Hecks
+  module CLI
+    # The command behind `bin/project_diagrams` and `hecks project_diagrams`: boots a
+    # domain, finds the chapter it names, and writes its Mermaid diagrams
+    # (`Projections::Diagrams`) under `docs/generated/diagrams/<chapter>/` below the
+    # root.
+    module ProjectDiagrams
+      module_function
+
+      def call(argv, program:, root:)
+        usage = "usage: #{program} <domain-path> <ChapterName>"
+        domain_path  = argv[0] or abort usage
+        chapter_name = argv[1] or abort usage
+
+        runtime   = Hecks.boot(File.expand_path(domain_path, Dir.pwd))
+        chapter   = runtime.registry.bluebook(chapter_name)
+        hecksagon = runtime.registry.hecksagon(chapter_name)
+        directory = File.expand_path("docs/generated/diagrams/#{Naming.snake(chapter_name)}", root)
+
+        written = Projector.write(
+          Projector.call(:diagrams, bluebook: chapter, options: { hecksagon: hecksagon }),
+          directory, as: :files
+        )
+
+        if written.empty?
+          puts "#{chapter_name} declares no lifecycle, relationship, or dispatch to project yet"
+        else
+          puts "wrote #{written.size} diagram(s) to #{directory}:"
+          written.each { |path| puts "  #{path}" }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/cli/run.rb

@@ -0,0 +1,173 @@
+require "json"
+require_relative "../../hecks"
+# ADR 0033 — a domain wired to PostgresEra needs this plugin loaded
+# explicitly; the era/lineage subsystem does not load with core.
+require_relative "../ports/persistence/plugins/era"
+
+module Hecks
+  module CLI
+    # The command behind `bin/run` and `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.
+    #
+    # `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
+
+      # Runs `argv` as a verb invocation or a step list against a domain.
+      #
+      # @param argv [Array<String>] the arguments: an optional domain directory, then
+      #   a verb with `name=value` pairs, a script path, `-`, or inline JSON
+      # @param program [String] the name usage and help messages call this command by
+      # @return [void]
+      # @raise [SystemExit] on any refusal, usage error or unmet expectation, and
+      #   after the command-line form answers
+      def call(argv, program:)
+        usage = "usage: #{program} [domain] <verb [name=value …] | script.json | - | '{\"steps\":[…]}'>"
+        argv = argv.dup
+        here = Adapters::Folder.new.domain_root
+        domain = argv.first && File.directory?(argv.first) ? argv.shift : here
+        abort "no bluebook here — #{Dir.pwd} is not inside a domain. #{usage}" unless domain
+
+        # The command-line form answers unless the first argument is script-shaped,
+        # in which case the step-list form takes over.
+        cli_form(domain, argv, program) unless argv.first && script_shaped?(argv.first)
+
+        script = argv.first or abort usage
+        document = parse(read_source(script))
+        steps = document["steps"] or abort %(the script has no "steps" — #{usage})
+        report = execute(Hecks.boot(domain), steps)
+
+        # The run is reported before it is judged: an expectation that fails says
+        # what was wanted and never what happened, so the evidence goes to stdout
+        # first and every unmet expectation is collected rather than aborted on.
+        puts JSON.pretty_generate(report)
+        unmet = unmet_expectations(document["expectations"] || {}, report)
+        abort unmet.join("\n") unless unmet.empty?
+      end
+
+      # 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)
+        status.zero? ? puts(text) : abort(text)
+        exit 0
+      end
+
+      def script_shaped?(arg) = arg == "-" || arg.match?(/\A\s*\{/) || File.file?(arg)
+
+      # Decided by looking, because a script beginning with `{` is not a filename
+      # anybody meant.
+      def read_source(script)
+        case script
+        when "-" then $stdin.read
+        when /\A\s*\{/ then script
+        else
+          File.exist?(script) ? File.read(script) : abort("no such script: #{script}")
+        end
+      end
+
+      # 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
+
+      def execute(runtime, steps)
+        refusals = []
+        queries = []
+        steps.each { |step| run_step(runtime, step, refusals, queries) }
+
+        { instances: instances(runtime), events: events(runtime), refusals: refusals,
+          reactions: runtime.reactions, sagas: runtime.sagas, queries: queries }
+      end
+
+      # @api private
+      def run_step(runtime, step, refusals, queries)
+        args = (step["args"] || {}).transform_keys(&:to_sym)
+        if (question = step["query"])
+          queries << ask(runtime, question, args)
+          return
+        end
+
+        verb = step["verb"]
+        begin
+          runtime.dispatch_flat(verb, args)
+        rescue StandardError => e
+          refusals << { verb: verb, error: e.message.to_s }
+        end
+      end
+
+      # @api private
+      def ask(runtime, question, args)
+        { query: question, args: args, rows: runtime.query(question, **args) }
+      rescue StandardError => e
+        { query: question, args: args, error: e.message }
+      end
+
+      # @api private
+      def instances(runtime)
+        runtime.registry.bluebooks.each_with_object({}) do |(domain_name, bluebook), all|
+          bluebook.aggregates.each do |aggregate|
+            runtime.registry.repository(domain_name, aggregate).all.each do |record|
+              all["#{domain_name}::#{aggregate.name}##{record.id}"] = record.state
+            end
+          end
+        end
+      end
+
+      # @api private
+      def events(runtime)
+        runtime.events.map do |event|
+          { name: event.name, aggregate: event.aggregate, id: event.id, payload: event.payload }
+        end
+      end
+
+      def unmet_expectations(expectations, report)
+        missing_events = Array(expectations["event_names"]) - report[:events].map { |event| event[:name] }
+        unmet = []
+        unmet << "matrix expected events missing: #{missing_events.join(', ')}" unless missing_events.empty?
+        unmet.concat(unmet_refusals(Array(expectations["refusals"]), report[:refusals]))
+        unmet.concat(unmet_instances(expectations["instances"] || {}, report[:instances]))
+      end
+
+      # @api private
+      def unmet_refusals(expected_refusals, refusals)
+        expected_refusals.filter_map do |expected|
+          verb = expected.fetch("verb")
+          matched = refusals.any? do |refusal|
+            refusal[:verb] == verb && refusal[:error].include?(expected.fetch("includes"))
+          end
+          next if matched
+
+          # A refusal that changed its words is a different story from one that never
+          # happened, so the actual errors are printed beside the wanted one.
+          said = refusals.select { |refusal| refusal[:verb] == verb }.map { |refusal| refusal[:error] }.uniq
+          "matrix expected refusal missing: #{expected}\n  " \
+            "#{verb} actually refused with: #{said.empty? ? '(nothing — every attempt was accepted)' : said.inspect}"
+        end
+      end
+
+      # @api private
+      def unmet_instances(expected_instances, instances)
+        expected_instances.flat_map do |key, fields|
+          actual = instances[key] || {}
+          fields.filter_map do |field, value|
+            next if actual[field.to_sym] == value
+
+            "matrix expected #{key}.#{field}=#{value.inspect}, got #{actual[field.to_sym].inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/cli/smoke_test.rb

@@ -0,0 +1,45 @@
+require_relative "../../hecks"
+require_relative "../bluebook/smoke_test"
+
+module Hecks
+  module CLI
+    # The command behind `bin/smoke_test` and `hecks smoke_test`: boots a real domain
+    # and dispatches one synthesized call per declared command and report
+    # (`Bluebook::SmokeTest`), printing every failure rather than the first.
+    #
+    # Needs a real `.hecksagon`; a failure may be a domain bug or a value the
+    # synthesizer's naive choices cannot satisfy — smoke-testing proves nothing
+    # crashes, not that an answer is right.
+    module SmokeTest
+      module_function
+
+      def call(argv, root:)
+        dir_arg = argv.first
+        targets = dir_arg ? [dir_arg] : Dir.glob("#{root}/examples/*/").map { |d| d.chomp("/") }.select { |d| wired?(d) }
+        abort "no wired example domains found (none of examples/* has a .hecksagon)" if targets.empty?
+
+        ok = targets.reduce(true) { |all_ok, dir| clean?(dir) && all_ok }
+
+        puts
+        puts ok ? "Every declared command and report dispatched cleanly." : "SMOKE TEST FOUND PROBLEMS."
+        exit(ok ? 0 : 1)
+      end
+
+      def wired?(dir) = !Dir.glob(File.join(dir, "**/*.hecksagon")).empty?
+
+      # @api private
+      def clean?(dir)
+        puts "── #{File.basename(dir)}"
+        failures = Bluebook::SmokeTest.call(dir)
+        if failures.empty?
+          puts "   clean — every declared command and report dispatched cleanly"
+          return true
+        end
+
+        puts "   #{failures.size} failure(s)"
+        failures.each { |f| puts "     #{f}" }
+        false
+      end
+    end
+  end
+end

data/lib/hecks/cli/stores.rb

@@ -0,0 +1,53 @@
+require "json"
+require_relative "../../hecks"
+
+module Hecks
+  module CLI
+    # The command behind `bin/stores` and `hecks stores`: every aggregate's current
+    # records as JSON (the head, not the journal — see `bin/history` for that).
+    module Stores
+      module_function
+
+      # Boots the domain `argv` names and prints its stores as one JSON document.
+      #
+      # @param argv [Array<String>] the domain directory, first
+      # @param program [String] the name the error message calls this command by
+      # @return [void]
+      # @raise [IndexError] when `argv` is empty
+      # @raise [SystemExit] when the domain directory does not exist
+      def call(argv, program:)
+        domain = argv.fetch(0)
+        unless Dir.exist?(domain)
+          warn "#{program}: no such domain #{domain.inspect}"
+          exit 1
+        end
+
+        registry = Hecks.boot(domain).registry
+        stores = registry.bluebooks.each_with_object({}) do |(name, bluebook), all|
+          bluebook.aggregates.each do |aggregate|
+            all[aggregate.storage_name] = data_for(registry.repository(name, aggregate))
+          end
+        end
+
+        puts JSON.generate(stores)
+      end
+
+      # Reads one aggregate's current records as plain JSON-ready hashes, ordered by id.
+      #
+      # @param repository [Ports::Persistence::AppendOnly] the aggregate's repository
+      # @return [Array<Hash{String => Object}>] one hash per stored `Runtime::Instance`,
+      #   sorted by id; `[]` when the aggregate has no records
+      def records(repository)
+        repository.all.sort_by(&:id).map { |instance| JSON.parse(JSON.generate(instance.to_h)) }
+      end
+
+      # Shapes one aggregate's dump for the top-level stores document.
+      #
+      # @param repository [Ports::Persistence::AppendOnly] the aggregate's repository
+      # @return [Hash{String => Object}] `"authoritative"` mapped to `records(repository)`
+      def data_for(repository)
+        { "authoritative" => records(repository) }
+      end
+    end
+  end
+end

data/lib/hecks/cli.rb

@@ -0,0 +1,160 @@
+module Hecks
+  # The `hecks` command an installed gem puts on the path: one router over the
+  # domain-operator tools, each also runnable from a checkout as `bin/<name>`.
+  #
+  # Every subcommand's logic lives under `cli/`, with `bin/<name>` a thin wrapper
+  # over the same entry point, so the two can't drift apart.
+  #
+  # See `docs/decisions/0066-the-gem-ships-a-hecks-executable-and-dev-tooling-stays-in-the-repo.md`.
+  module CLI
+    # One subcommand's help: a one-line summary and its usage line.
+    Command = Struct.new(:summary, :usage)
+
+    # Every subcommand, in the order the help lists them.
+    COMMANDS = {
+      "run"              => Command.new(
+        "Dispatch a verb, or run a JSON step list, against a domain.",
+        "hecks run [domain] <verb [name=value …] | script.json | - | '{\"steps\":[…]}'>"
+      ),
+      "docs"             => Command.new(
+        "Print a domain's usage document, projected from its bluebook.",
+        "hecks docs [domain-path] [aggregate]"
+      ),
+      "narrate"          => Command.new(
+        "Print a domain read back in English, projected from its bluebook.",
+        "hecks narrate [domain-path] [aggregate]"
+      ),
+      "ir"               => Command.new(
+        "Print a booted domain's IR as JSON.",
+        "hecks ir <domain> [--translations] | hecks ir --meta"
+      ),
+      "stores"           => Command.new(
+        "Print every aggregate's current records as JSON.",
+        "hecks stores <domain>"
+      ),
+      "model_check"      => Command.new(
+        "Statically check a domain's IR for dead states and unreachable steps.",
+        "hecks model_check [--strict] [--profile client] <domain> [<domain> …]"
+      ),
+      "smoke_test"       => Command.new(
+        "Boot a domain and dispatch every declared command and report once.",
+        "hecks smoke_test [domain]"
+      ),
+      "project_diagrams" => Command.new(
+        "Write a domain's Mermaid diagrams under ./docs/generated/diagrams/.",
+        "hecks project_diagrams <domain-path> <ChapterName>"
+      ),
+      "project_cli"      => Command.new(
+        "Write a command-line launcher beside each domain, named after its bluebook.",
+        "hecks project_cli [domain-path …]"
+      ),
+      "mcp"              => Command.new(
+        "Serve the MCP door over stdio (no authentication; stdio only).",
+        "hecks mcp [--stdio]"
+      )
+    }.freeze
+
+    HELP_FLAGS = ["--help", "-h"].freeze
+
+    # Printed above the usage line by `overview`, on every path that reaches it
+    # (a bare `hecks`, `hecks --help`, and an unknown subcommand alike).
+    HERO = <<~BANNER.freeze
+      #   #  #####   ####  #  #    ####
+      #   #  #      #      # #    #
+      #####  ####   #      ##      ###
+      #   #  #      #      # #        #
+      #   #  #####   ####  #  #   ####
+
+          It's all about the specs
+    BANNER
+
+    # Exit status for a missing or unknown subcommand.
+    USAGE_STATUS = 2
+
+    module_function
+
+    # Routes `argv` to its subcommand and runs it.
+    #
+    # A subcommand followed only by `--help`/`-h` prints its usage without
+    # running it; other arguments still reach the verb itself.
+    #
+    # @param argv [Array<String>] the command line, subcommand first
+    # @param out [#puts] where help goes
+    # @param err [#puts] where usage errors go
+    # @return [Integer] the process exit status for a subcommand that returns; a
+    #   subcommand that fails exits the process itself
+    def start(argv, out: $stdout, err: $stderr)
+      name, *rest = argv
+      if name.nil? || !COMMANDS.key?(name)
+        asked = HELP_FLAGS.include?(name) || name == "help"
+        err.puts "hecks: unknown command #{name.inspect}" unless asked || name.nil?
+        overview(asked ? out : err)
+        return asked ? 0 : USAGE_STATUS
+      end
+
+      if rest.length == 1 && HELP_FLAGS.include?(rest.first)
+        help(COMMANDS.fetch(name), out)
+      else
+        dispatch(name, rest)
+      end
+      0
+    end
+
+    # Runs one known subcommand with the working directory as its root.
+    #
+    # @param name [String] a key of `COMMANDS`
+    # @param argv [Array<String>] the arguments after the subcommand
+    # @return [void]
+    # @raise [SystemExit] when the subcommand exits the process itself
+    def dispatch(name, argv)
+      program = "hecks #{name}"
+      case name
+      when "run"
+        require_relative "cli/run"
+        Run.call(argv, program: program)
+      when "docs", "narrate"
+        require_relative "cli/document"
+        Document.call(argv, projection: name.to_sym, program: program, root: Dir.pwd)
+      when "ir"
+        require_relative "cli/ir"
+        Ir.call(argv, program: program)
+      when "stores"
+        require_relative "cli/stores"
+        Stores.call(argv, program: program)
+      when "model_check"
+        require_relative "cli/model_check"
+        ModelCheck.call(argv, program: program)
+      when "smoke_test"
+        require_relative "cli/smoke_test"
+        SmokeTest.call(argv, root: Dir.pwd)
+      when "project_diagrams"
+        require_relative "cli/project_diagrams"
+        ProjectDiagrams.call(argv, program: program, root: Dir.pwd)
+      when "project_cli"
+        require_relative "cli/project_cli"
+        ProjectCli.call(argv, program: program, root: Dir.pwd, remove_stale_bin: false)
+      when "mcp"
+        require_relative "cli/mcp"
+        Mcp.call(argv)
+      end
+    end
+
+    # @api private
+    def overview(io)
+      io.puts HERO
+      io.puts "usage: hecks <command> [arguments]"
+      io.puts ""
+      width = COMMANDS.keys.map(&:length).max
+      COMMANDS.each { |name, command| io.puts "  #{name.ljust(width)}  #{command.summary}" }
+      io.puts ""
+      io.puts "Run `hecks <command> --help` for one command's usage."
+    end
+
+    # @api private
+    def help(command, io)
+      io.puts "usage: #{command.usage}"
+      io.puts ""
+      io.puts command.summary
+    end
+  end
+end

data/lib/hecks/construct.rb

@@ -1,29 +1,12 @@
 module Hecks
-  # The invisible field a built construct carries.
+  # The invisible identity a built construct carries: an owner chain under `hecks_`-prefixed
+  # fields, not an attribute and not a key in `to_h`.
   #
-  # ## Identity
+  # The fully-qualified name walks owners and matches the id `MetaValidator::Judge#identify` mints.
   #
-  # A construct is a record with an owner chain — the chapter (Bluebook)
-  # owns its aggregates, an aggregate owns everything declared on it — and the
-  # bluebook identity is carried in its own field, under a `hecks_` prefix that
-  # no domain attribute can collide with. Invisible means exactly that: not an
-  # attribute, not a key in `to_h`, not a reader on instances. Framework
-  # metadata about the construct, not part of the domain it describes.
-  #
-  # The identity is computed by walking owners rather than stamped, so nothing
-  # has to be re-stamped when a chapter is assembled after its aggregates:
-  #
-  #     Pizzas                     the chapter — no owner
+  #     Pizzas                     the chapter, no owner
   #     Pizzas::Pizza              an aggregate joins its chapter with ::
   #     Pizzas::Pizza.Price        everything else joins its owner with .
-  #
-  # That spelling is not invented here. It is the id `MetaValidator::Judge`
-  # already mints in `#identify`, so a construct and the meta-domain's
-  # record of that construct carry the same identity, and there is no
-  # translation table between them to be quietly wrong in.
-  #
-  # ## Usage
-  #
   #     price = Class.new(ValueObject)   # a declaration holder
   #     price.hecks_name  = "Price"
   #     price.hecks_owner = pizza_ir         # the Aggregate that declares it
@@ -32,15 +15,12 @@ module Hecks
     # A construct asked for an identity it cannot compute.
     class Unowned < StandardError; end
 
-    # What declares this one — the chapter above an aggregate, the aggregate
-    # above a value object. nil for a chapter, which is the top.
+    # What declares this construct; nil for a chapter, which is the top.
     attr_accessor :hecks_owner
 
     attr_writer :hecks_name
 
-    # A chapter is the only construct that legitimately has no owner. Everything
-    # else is declared in something, so a missing owner is an unstamped construct
-    # rather than a top — see hecks_fqn.
+    # Marks a chapter, the only construct that legitimately has no owner.
     attr_writer :hecks_root
 
     # Whether this construct is the top of its own owner chain.
@@ -53,18 +33,12 @@ module Hecks
     # @return [String] the construct's own name, without any owner prefix
     def hecks_name = @hecks_name
 
-    # How this construct joins its owner. An aggregate is a member of its
-    # chapter's namespace (`::`) ; everything else is declared on its owner
-    # (`.`). Overridden by Aggregate, defaulted here for every other construct.
+    # How this construct joins its owner: `::` for an aggregate, `.` for everything else.
     #
     # @return [String] `"."`, the separator this construct uses in `hecks_fqn`
     def hecks_separator = "."
 
-    # Refuses rather than guesses. A construct with no owner and no claim to be a
-    # chapter has simply not been stamped yet — entity commands are in that state
-    # while entities are still IR objects — and answering the bare name would be a
-    # plausible half-truth that no test would notice. That shape of falsehood is
-    # what this repo keeps finding, so it goes red instead.
+    # Refuses rather than answering a bare name for an unstamped construct.
     #
     # @return [String] the fully-qualified name, joining every owner from the
     #   chapter down to this construct