hecks 3.5.0 → 3.6.0

data/lib/hecks/doors/launcher_options.rb

@@ -1,3 +1,4 @@
+require "pathname"
 require "stringio"
 require_relative "../ports/identity_generation"
 require_relative "../runtime/errors"
@@ -12,16 +13,21 @@ module Hecks
     #
     # - **run_keys** mints the `run` key of a creating command that was given none.
     # - **failure_states** are the lifecycle states `--wait` reports as a failure (exit 1).
-    # - **settled** lists the commands (`aggregate.command`) that always behave as if `--wait`
-    #   was given, so a script gets their outcome in its exit status.
+    # - **settled** lists the commands (`aggregate.command`) that always act as if given `--wait`.
     # - **report** lists the settled commands whose answer is the report they recorded, as text.
     # - **names** maps a launcher name to the command it stands for (see `CliProjector`).
     # - **streams** lists the questions `--stream` may tail, one JSON line per new entry.
+    # - **maintainer**, **chapters**, **maintainer_chapters** shape the help for its audience.
     module LauncherOptions
       SETTING = "launcher".freeze
       WAIT    = "--wait".freeze
       STREAM  = "--stream".freeze
       RUN_KEY = "run.value".freeze
+      # What makes a directory a hecks checkout: this file stands beside `lib/`, the same test
+      # the Codebase aggregate's `Accept` applies before it runs anything.
+      CHECKOUT_MARKER = "hecks.gemspec".freeze
+      # `HECKS_MAINTAINER=1` shows the maintainer help anywhere, `0` hides it even in a checkout.
+      MAINTAINER_VARIABLE = "HECKS_MAINTAINER".freeze
 
       module_function
 
@@ -47,6 +53,36 @@ module Hecks
         { program: program, names: settings && settings[:names], mint_run_keys: settings && settings[:run_keys] }
       end
 
+      # Whether the person is working on a hecks checkout: `dir` or a directory above it holds
+      # `hecks.gemspec` beside `lib/`. `HECKS_MAINTAINER` overrides the look.
+      #
+      # @param dir [String] where the command line was typed
+      # @param env [#[]] the environment
+      # @return [Boolean] true for the maintainer's view of the help
+      def maintainer?(dir = Dir.pwd, env = ENV)
+        forced = env[MAINTAINER_VARIABLE].to_s
+        return forced != "0" unless forced.empty?
+
+        Pathname.new(File.expand_path(dir)).ascend.any? do |root|
+          root.join(CHECKOUT_MARKER).exist? && root.join("lib").directory?
+        end
+      end
+
+      # The help options one audience gets: the aggregates left out of the lists (`maintainer`,
+      # shown only in a hecks checkout or to `--maintainer`) and the chapters pointed at
+      # (`chapters`, plus `maintainer_chapters` in a checkout). A chapter that did not opt in
+      # gets neither.
+      #
+      # @param settings [Hash, nil] the chapter's `launcher` setting
+      # @param maintainer [Boolean] whether the help is for someone working on a hecks checkout
+      # @return [Hash{Symbol => Object}] `:hide` and `:chapters`, to merge into the projection
+      def audience(settings, maintainer)
+        return {} unless settings
+
+        chapters = Array(settings[:chapters]) + (maintainer ? Array(settings[:maintainer_chapters]) : [])
+        { hide: maintainer ? [] : Array(settings[:maintainer]).map(&:to_s), chapters: chapters.map(&:to_s) }
+      end
+
       # Runs the block with standard error held back, so the wiring notes hecks prints about its own
       # chapters (a Memory journal loses sagas on restart) do not open a console session. They are
       # for an operator running a stored journal. A raised error still surfaces, unchanged.
@@ -74,9 +110,20 @@ module Hecks
       # @return [Array(Array<String>, Boolean)] the remaining words, and whether `--wait` was given
       # @raise [Runtime::TypeMismatch] if `--wait=` carries something that is not a Boolean word
       def take_wait(spec, words)
-        return [words, false] unless words.any? { |word| wait_word?(word) }
-        return [words, false] if spec[:arguments].any? { |argument| argument[:path].split(".").first == "wait" }
+        return [words, false] unless words.any? { |word| wait_word?(word) } && !declares_wait?(spec)
 
+        split_wait(words)
+      end
+
+      # Whether the command declares an argument of its own named `wait`.
+      # @api private
+      def declares_wait?(spec)
+        spec[:arguments].any? { |argument| argument[:path].split(".").first == "wait" }
+      end
+
+      # The words without `--wait`, and whether it was given.
+      # @api private
+      def split_wait(words)
         wait  = false
         rest  = []
         queue = words.dup
@@ -165,9 +212,7 @@ module Hecks
       # @return [Array(Hash, String)] the arguments, and the key minted (nil when none was)
       # @raise [Runtime::NotFound] if a key is owed but no identity adapter is bound
       def run_key(runtime, spec, args, settings)
-        return [args, nil] unless settings && settings[:run_keys] && spec[:creates]
-        return [args, nil] unless spec[:arguments].any? { |argument| argument[:path] == RUN_KEY }
-        return [args, nil] if args.key?(:run) || !runtime.respond_to?(:registry)
+        return [args, nil] unless key_owed?(runtime, spec, args, settings)
 
         key = Ports::IdentityGeneration.uuid(runtime.registry)
         [args.merge(run: { value: key }), key]
@@ -175,6 +220,16 @@ module Hecks
         raise Runtime::NotFound, "cannot mint a run key (#{e.message.lines.first.strip}); name one with run=<key>"
       end
 
+      # Whether the command is a creating one of an opted-in chapter, takes a run key and was
+      # given none.
+      # @api private
+      def key_owed?(runtime, spec, args, settings)
+        return false unless settings && settings[:run_keys] && spec[:creates]
+        return false unless spec[:arguments].any? { |argument| argument[:path] == RUN_KEY }
+
+        !args.key?(:run) && runtime.respond_to?(:registry)
+      end
+
       # Whether a settled record sits in one of the chapter's failure states.
       #
       # @param aggregate [Bluebook::Aggregate, nil] the record's aggregate

data/lib/hecks/doors/mcp_door/properties.rb

@@ -0,0 +1,47 @@
+require_relative "../../../hecks"
+
+module Hecks
+  module Doors
+    module McpDoor
+      # The input-schema properties the MCP door's tools share.
+      module Properties
+        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
+      end
+    end
+  end
+end

data/lib/hecks/doors/mcp_door/tool_calls.rb

@@ -0,0 +1,113 @@
+require_relative "../../../hecks"
+
+module Hecks
+  module Doors
+    module McpDoor
+      # Answers one `tools/call`: the tool a name stands for, run against the booted domain the
+      # call names. A domain refusal is already `{ok: false, ...}` from `Storehouse`.
+      module ToolCalls
+        # The method that answers each tool.
+        HANDLERS = {
+          "dispatch"  => :dispatch_tool,
+          "query"     => :query_tool,
+          "events"    => :events_tool,
+          "state"     => :state_tool,
+          "catalog"   => :catalog_tool,
+          "describe"  => :describe_tool,
+          "validate"  => :validate_tool,
+          "domains"   => :domains_tool,
+          "history"   => :history_tool,
+          "behaviors" => :behaviors_tool,
+          "follow"    => :follow_tool
+        }.freeze
+
+        module_function
+
+        # Runs the tool `name` with `args`, so the shared `rescue` catches every tool's escape once.
+        #
+        # @param name [String] the tool's name
+        # @param args [Hash{String => Object}] the call's arguments
+        # @return [Hash{Symbol => Object}] the tool's answer, or `{ok: false, error: ...}`
+        def call(name, args)
+          handler = HANDLERS[name]
+          return unknown(name) unless handler
+
+          public_send(handler, args)
+        rescue StandardError => e
+          # A defect, not a refusal: reaching here means a bad domain path or an
+          # argument shape `Doors::JsonDoor` could not symbolize.
+          { ok: false, error: "#{e.class}: #{e.message}" }
+        end
+
+        # The refusal for a tool the door does not have.
+        def unknown(name)
+          { ok: false, error: "no such tool: #{name.inspect} — known: #{HANDLERS.keys.join(", ")}" }
+        end
+
+        # A question, once the scope has admitted its arguments.
+        def query_tool(args)
+          McpDoor.scope.admit_arguments!(args["args"])
+          Storehouse.query(runtime: McpDoor.boot(args["domain"]), question: args["question"],
+                           summary: args["summary"], args: args["args"] || {}, source: args["source"],
+                           role: args["role"], actor_id: args["actor_id"])
+        end
+
+        # A single command or a batch, once the scope has admitted every command in it.
+        def dispatch_tool(args)
+          runtime = McpDoor.boot(args["domain"])
+          return dispatch_steps(runtime, args) if args["steps"]
+
+          McpDoor.scope.admit_command!(runtime, args["command"], args["args"])
+          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
+
+        # Several commands in one call.
+        def dispatch_steps(runtime, args)
+          McpDoor.scope.admit_steps!(runtime, args["steps"])
+          Storehouse.dispatch_batch(runtime: runtime, steps: args["steps"], summary: args["summary"],
+                                    source: args["source"], role: args["role"], actor_id: args["actor_id"])
+        end
+
+        def events_tool(args)
+          Storehouse.events(runtime: McpDoor.boot(args["domain"]), aggregate: args["aggregate"], id: args["id"],
+                            limit: args["limit"])
+        end
+
+        def state_tool(args)
+          Storehouse.state(runtime: McpDoor.boot(args["domain"]), aggregate: args["aggregate"],
+                           summary: args["summary"], id: args["id"])
+        end
+
+        def catalog_tool(args)
+          Storehouse.catalog(runtime: McpDoor.boot(args["domain"]))
+        end
+
+        def describe_tool(args)
+          Storehouse.describe(runtime: McpDoor.boot(args["domain"]), aggregate: args["aggregate"])
+        end
+
+        def validate_tool(args)
+          Storehouse.validate(domain: McpDoor.scope.admit_domain!(args["domain"]), deep: args["deep"] == true)
+        end
+
+        def domains_tool(args)
+          Storehouse.domains(under: args["under"] || "examples")
+        end
+
+        def history_tool(args)
+          Storehouse.history(runtime: McpDoor.boot(args["domain"]))
+        end
+
+        def behaviors_tool(args)
+          Storehouse.behaviors(target: args["target"])
+        end
+
+        def follow_tool(args)
+          Storehouse.follow(runtime: McpDoor.boot(args["domain"]), limit: args["limit"] || 20)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/doors/mcp_door/tool_definitions/auditing.rb

@@ -0,0 +1,51 @@
+require_relative "../properties"
+
+module Hecks
+  module Doors
+    module McpDoor
+      module ToolDefinitions
+        # The tools that read what has been recorded: write history, behaviors and the audit log.
+        module Auditing
+          include Properties
+
+          LIST = [
+            {
+              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
+        end
+      end
+    end
+  end
+end

data/lib/hecks/doors/mcp_door/tool_definitions/calling.rb

@@ -0,0 +1,69 @@
+require_relative "../properties"
+
+module Hecks
+  module Doors
+    module McpDoor
+      module ToolDefinitions
+        # The tools that issue a command or ask a question.
+        module Calling
+          include Properties
+
+          LIST = [
+            {
+              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]
+              }
+            }
+          ].freeze
+        end
+      end
+    end
+  end
+end

data/lib/hecks/doors/mcp_door/tool_definitions/reading.rb

@@ -0,0 +1,97 @@
+require_relative "../properties"
+
+module Hecks
+  module Doors
+    module McpDoor
+      module ToolDefinitions
+        # The tools that read a domain: its events, state, shape and wiring.
+        module Reading
+          include Properties
+
+          LIST = [
+            {
+              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\"." } }
+              }
+            }
+          ].freeze
+        end
+      end
+    end
+  end
+end

data/lib/hecks/doors/mcp_door/tool_definitions.rb

@@ -0,0 +1,15 @@
+require_relative "tool_definitions/calling"
+require_relative "tool_definitions/reading"
+require_relative "tool_definitions/auditing"
+
+module Hecks
+  module Doors
+    module McpDoor
+      # The tools the MCP door answers: their names, descriptions and input schemas, in the order
+      # `tools/list` shows them.
+      module ToolDefinitions
+        TOOLS = (Calling::LIST + Reading::LIST + Auditing::LIST).freeze
+      end
+    end
+  end
+end