hecks 5.0.0 → 7.0.0

data/lib/hecks/adapters/driving/mcp/progress_sink.rb

@@ -0,0 +1,45 @@
+require "json"
+require_relative "../../../tools/stage_progress"
+
+module Hecks
+  module Adapters
+    module Driving
+      module Mcp
+        # Where a stage's progress lines go when the client asked for them with a progress token: each
+        # line becomes one `notifications/progress` message on the server's output, ahead of the
+        # response to the call. Stands in for the standard error that `Tools::StageProgress` writes to.
+        class ProgressSink
+          # @param token [Object] the client's `progressToken`, echoed back on every notification
+          # @param out [#puts] the server's output, where each notification is written
+          def initialize(token, out:)
+            @token = token
+            @out   = out
+            @count = 0
+          end
+
+          # Sends one line as a progress notification. The count rises by one per line, so a client
+          # can order them.
+          # @param text [String] the line
+          # @return [void]
+          def puts(text)
+            @count += 1
+            @out.puts(JSON.generate(notification(text)))
+          end
+
+          # Nothing is buffered, so there is nothing to flush.
+          # @return [nil]
+          def flush = nil
+
+          private
+
+          # @param text [String] the line
+          # @return [Hash] the JSON-RPC notification carrying it
+          def notification(text)
+            { jsonrpc: "2.0", method: "notifications/progress",
+              params: { progressToken: @token, progress: @count, message: text } }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/mcp/tool_calls.rb

@@ -48,10 +48,10 @@ module Hecks
 
           # A question, once the scope has admitted its arguments.
           def query_tool(args)
-            Mcp.scope.admit_arguments!(args["args"])
+            Mcp.scope.admit_arguments!(args["args"], args["question"])
             Storehouse.query(runtime: Mcp.boot(args["domain"]), question: args["question"],
                              summary: args["summary"], args: args["args"] || {}, source: args["source"],
-                             role: args["role"], actor_id: args["actor_id"])
+                             role: args["role"], actor_id: args["actor_id"], surface: "mcp")
           end
 
           # A single command or a batch, once the scope has admitted every command in it.
@@ -62,14 +62,16 @@ module Hecks
             Mcp.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"])
+                                dry_run: args["dry_run"] == true, role: args["role"], actor_id: args["actor_id"],
+                                surface: "mcp")
           end
 
           # Several commands in one call.
           def dispatch_steps(runtime, args)
             Mcp.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"])
+                                      source: args["source"], role: args["role"], actor_id: args["actor_id"],
+                                      surface: "mcp")
           end
 
           def events_tool(args)
@@ -79,7 +81,7 @@ module Hecks
 
           def state_tool(args)
             Storehouse.state(runtime: Mcp.boot(args["domain"]), aggregate: args["aggregate"],
-                             summary: args["summary"], id: args["id"])
+                             summary: args["summary"], id: args["id"], surface: "mcp")
           end
 
           def catalog_tool(args)

data/lib/hecks/adapters/driving/mcp.rb

@@ -1,8 +1,9 @@
 require "json"
 require_relative "../.."
-require_relative "../../cli/mcp"
+require_relative "../../tools/mcp"
 require_relative "mcp/tool_definitions"
 require_relative "mcp/tool_calls"
+require_relative "mcp/progress_sink"
 
 module Hecks
   module Adapters
@@ -42,7 +43,7 @@ module Hecks
         # Read once, so a bad setting refuses to start the server before anything is
         # written to stdout.
         def scope
-          @scope ||= McpScope.start!(server: CLI::Mcp::SERVER)
+          @scope ||= McpScope.start!(server: Tools::Mcp::SERVER)
         end
 
         # The standing notes, then what this server's scope says about `domain:`.
@@ -51,7 +52,7 @@ module Hecks
         end
 
         def serve
-          McpStdioGuard.warn!(server: CLI::Mcp::SERVER, notes: warning_notes)
+          McpStdioGuard.warn!(server: Tools::Mcp::SERVER, notes: warning_notes)
           $stdout.sync = true
 
           $stdin.each_line { |line| answer_line(line.strip) }
@@ -138,7 +139,7 @@ module Hecks
 
         def initialize_result(_params)
           { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} },
-            serverInfo: { name: CLI::Mcp::SERVER, version: "1.1.0" } }
+            serverInfo: { name: Tools::Mcp::SERVER, version: "1.1.0" } }
         end
 
         # The tools this server's scope permits, each presented with the command guide.
@@ -149,9 +150,28 @@ module Hecks
         end
 
         def tools_call(params)
-          tool_result(answer_tool(params["name"], params["arguments"] || {}))
+          token = params.dig("_meta", "progressToken")
+          return tool_result(answer_tool(params["name"], params["arguments"] || {})) if token.nil?
+
+          with_progress(token) { tool_result(answer_tool(params["name"], params["arguments"] || {})) }
+        end
+
+        # Runs the block with a progress seam for this call's stages, so their lines reach the client as
+        # notifications. The seam is per thread and removed when the call ends.
+        # @param token [Object] the client's progress token
+        # @return [Object] the block's value
+        def with_progress(token)
+          previous = Thread.current[:mcp_progress]
+          Thread.current[:mcp_progress] = Tools::StageProgress.new(ProgressSink.new(token, out: $stdout))
+          yield
+        ensure
+          Thread.current[:mcp_progress] = previous
         end
 
+        # The progress seam of the call on this thread: nil when the client sent no progress token.
+        # @return [Tools::StageProgress, nil]
+        def progress = Thread.current[:mcp_progress]
+
         def ping_result(_params) = {}
       end
     end

data/lib/hecks/adapters/driving/mcp_scope/argument_policy.rb

@@ -13,17 +13,40 @@ module Hecks
           # Checks every argument in `args`, nested or not, and refuses the first one the policy
           # forbids.
           #
+          # Read-only questions whose `path` names one file of the checkout. `path` is denied by name
+          # for every other command, since it can name a place to write; these reads are allowed it,
+          # and admit_path! still confines it to the checkout.
+          READ_PATH_QUESTIONS = %w[codebase.read_source codebase.outline].freeze
+
+          # The line window those reads take: plain numbers that name no place, so they pass.
+          READ_WINDOW_ARGUMENTS = %w[from to top].freeze
+
+          # The boundary between a lower-case letter or digit and the upper-case letter after it.
+          CAMEL_BOUNDARY = /([a-z\d])([A-Z])/
+
           # @param args [Hash, Array, nil] the arguments as the caller gave them
           # @param label [String] how the server describes its mode, for the refusal
+          # @param question [String, nil] the query asked, when the arguments are a question's
           # @raise [Runtime::TypeMismatch] on the first argument refused
-          def admit!(args, label)
-            each_argument(args) do |name, value|
-              if DENIED_ARGUMENTS.include?(name)
-                refuse!(name, label, "never passes it on: it names a host, a binary, an output or a change of state")
-              end
-              admit_path!(name, value, label) if PATH_ARGUMENTS.include?(name)
-              admit_ref!(name, value, label) if REF_ARGUMENTS.include?(name)
+          def admit!(args, label, question = nil)
+            read_question = READ_PATH_QUESTIONS.include?(snake_question(question))
+            each_argument(args) { |name, value| admit_one!(name, value, label, read_question) }
+          end
+
+          # Whether an argument is a line window the read questions take, which names no place.
+          def window?(name, read_question) = read_question && READ_WINDOW_ARGUMENTS.include?(name)
+
+          # Checks one argument by its name: a read path is allowed its path, and anything else is
+          # refused, confined to the checkout, or checked as a ref.
+          def admit_one!(name, value, label, read_question)
+            return if window?(name, read_question)
+            return admit_path!(name, value, label) if name == "path" && read_question
+
+            if DENIED_ARGUMENTS.include?(name)
+              refuse!(name, label, "never passes it on: it names a host, a binary, an output or a change of state")
             end
+            admit_path!(name, value, label) if PATH_ARGUMENTS.include?(name)
+            admit_ref!(name, value, label) if REF_ARGUMENTS.include?(name)
           end
 
           # Yields every argument name with its value, descending into nested objects and lists, so
@@ -47,6 +70,16 @@ module Hecks
             value.fetch("value") { value.fetch(:value, value) }
           end
 
+          # The question as `Aggregate.query` or `aggregate_run.query` names it, in the snake form
+          # `READ_PATH_QUESTIONS` uses.
+          def snake_question(question)
+            parts = question.to_s.split(".")
+            parts.map { |part| snake_part(part) }.join(".")
+          end
+
+          # One part of a question name, in snake form: `ReadSource` is `read_source`.
+          def snake_part(part) = part.gsub(CAMEL_BOUNDARY, '\1_\2').downcase
+
           def refuse!(name, label, why)
             raise Runtime::TypeMismatch, "argument: #{name.inspect} is refused: this server runs in #{label} and #{why}"
           end

data/lib/hecks/adapters/driving/mcp_scope/env_problems.rb

@@ -1,3 +1,5 @@
+require_relative "../../../text"
+
 module Hecks
   module Adapters
     module Driving
@@ -61,7 +63,7 @@ module Hecks
 
           def split_paths(value) = value.to_s.split(File::PATH_SEPARATOR).reject(&:empty?)
 
-          def split_names(value) = value.to_s.split(",").map(&:strip).reject(&:empty?).uniq
+          def split_names(value) = Text.comma_list(value).uniq
         end
       end
     end

data/lib/hecks/adapters/driving/mcp_scope.rb

@@ -27,12 +27,13 @@ module Hecks
 
         # Argument names a restricted server never passes on, whatever command carries them: each
         # one
-        # names a host or a URL, a binary to run, a place to write, a port to open, a store to
-        # switch to, or flips a command from a preview to a change of state.
+        # names a host or a URL, a binary to run, what a spawned session is told to do, a place to
+        # write, a port to open, a store to switch to, or flips a command from a preview to a
+        # change of state.
         DENIED_ARGUMENTS = %w[
-          adapter artifact confirm expected from gem_only header health_path host live no_wait npm_local
-          npm_only output path payload payload_file port rust_binary scheme stage_dir state_path stdio url
-          write
+          adapter artifact brief claimed confirm expected force from gem_only header health_path host live
+          no_wait npm_local npm_only output path payload payload_file port prebuilt remote row rust_binary
+          scheme stage_dir state_path stdio url write
         ].freeze
 
         # Argument names whose values are paths (a comma-separated list for some). A restricted
@@ -40,11 +41,11 @@ module Hecks
         # passes them on only when each resolves, symlinks followed, inside `Storehouse::BOOT_ROOT`,
         # and holds no colon: `host:repo` and `https://host/x` would otherwise pass as relative
         # paths.
-        PATH_ARGUMENTS = %w[dir domain domains file fixture paths root script].freeze
+        PATH_ARGUMENTS = %w[checkout dir directory domain domains file files fixture paths repo root script].freeze
 
         # Argument names whose values are git refs: plain names only, so a value cannot read as an
         # option to git.
-        REF_ARGUMENTS = %w[commit ref].freeze
+        REF_ARGUMENTS = %w[base branch commit onto ref].freeze
 
         # What a plain git ref looks like: no leading dash, no `..`, no spaces.
         PLAIN_REF = %r{\A[A-Za-z0-9][A-Za-z0-9._/~^@-]*\z}
@@ -154,11 +155,12 @@ module Hecks
         # files should name it in `DENIED_ARGUMENTS` or `PATH_ARGUMENTS` (ADR 0089).
         #
         # @param args [Hash, Array, nil] the arguments as the caller gave them, nested or not
+        # @param question [String, nil] the query asked, when these are a question's arguments
         # @raise [Runtime::TypeMismatch] on the first argument refused
-        def admit_arguments!(args)
+        def admit_arguments!(args, question = nil)
           return unless restricted?
 
-          ArgumentPolicy.admit!(args, mode_label)
+          ArgumentPolicy.admit!(args, mode_label, question)
         end
 
         # The one domain a restricted server serves, when it serves exactly one: a call may leave

data/lib/hecks/adapters/driving/newcomer.rb

@@ -5,7 +5,7 @@ module Hecks
     module Driving
       # The launcher's help for someone starting out: a folder with no bluebook in it has no use yet
       # for the commands that act on a domain, so the help lists only the `newcomer` commands the
-      # chapter's `launcher` setting names (`hecks --all` lists the rest).
+      # bluebook's `launcher` setting names (`hecks --all` lists the rest).
       module Newcomer
         # How deep under a directory a bluebook may sit and still make it a project:
         # `Hecks.bluebook` beside it, or `bluebook/pizzas.bluebook` one folder down, as the
@@ -25,15 +25,16 @@ module Hecks
           PROJECT_GLOBS.none? { |pattern| bluebook_under?(dir, pattern) }
         end
 
-        # The help options a newcomer gets: only the setting's `newcomer` commands, and no chapters.
+        # The help options a newcomer gets: only the setting's `newcomer` commands, and no
+        # bluebooks.
         #
-        # @param settings [Hash, nil] the chapter's `launcher` setting
-        # @return [Hash{Symbol => Object}, nil] `:only` and `:chapters`, or nil when the chapter
+        # @param settings [Hash, nil] the bluebook's `launcher` setting
+        # @return [Hash{Symbol => Object}, nil] `:only` and `:bluebooks`, or nil when the bluebook
         #   names no newcomer commands
         def audience(settings)
           return unless settings && settings[:newcomer]
 
-          { only: Array(settings[:newcomer]).map(&:to_s), chapters: [] }
+          { only: Array(settings[:newcomer]).map(&:to_s), declarations: [] }
         end
 
         # Whether `pattern` finds a bluebook under `dir`; a folder the person may not read holds

data/lib/hecks/adapters/driving/ruby/aggregate_module/hooks.rb

@@ -0,0 +1,154 @@
+module Hecks
+  module Adapters
+    module Driving
+      module Ruby
+        module AggregateModule
+          # The hooks an aggregate module lands on: a port declared inside a repeat boot, the bare and
+          # qualified binding calls a `.hecksagon` and a `.world` make, and constant lookup. Each is a
+          # module function, called as `Hooks.name` from the blocks that define the module's methods, since
+          # a block defined with `define_singleton_method` runs with the module as `self`.
+          module Hooks
+            # What `bound_outcome` answers for a call that is not a binding, so `super` handles it.
+            UNBOUND = Object.new.freeze
+
+            # What `bound_outcome` answers for a call that recorded a binding, so the module answers itself.
+            BOUND = Object.new.freeze
+
+            module_function
+
+            # Defines `port`, which declares a port on the aggregate during a repeat boot.
+            #
+            # @param mod [Module] the aggregate module
+            # @param domain [String] the domain the aggregate belongs to
+            # @param aggregate [Bluebook::Aggregate] the aggregate
+            # @param fqn [String] the aggregate's qualified name
+            # @return [void]
+            def define_port_hook(mod, domain, aggregate, fqn)
+              mod.define_singleton_method(:port) do |name, &block|
+                Hooks.attach_port(name, domain, aggregate, fqn, &block)
+                self
+              end
+            end
+
+            # Defines `ask_via`, the repeat-boot form of `BindingProxy#ask_via`.
+            #
+            # @param mod [Module] the aggregate module
+            # @param domain [String] the domain the aggregate belongs to
+            # @param aggregate [Bluebook::Aggregate] the aggregate
+            # @return [void]
+            def define_ask_via(mod, domain, aggregate)
+              mod.define_singleton_method(:ask_via) do |name, port:|
+                declaration = Hecks.current_registry&.bluebook(domain)
+                Bluebook::AskResolution.pick!(declaration, aggregate.hecks_name, name, port)
+                self
+              end
+            end
+
+            # Defines `method_missing`: a bare call starts a Privacy marking chain, and a qualified
+            # call records a binding. Anything else falls through to `super`.
+            #
+            # @param mod [Module] the aggregate module
+            # @param fqn [String] the aggregate's qualified name
+            # @return [void]
+            def define_method_missing(mod, fqn)
+              mod.define_singleton_method(:method_missing) do |verb, *args, **kwargs, &block|
+                outcome = Hooks.bound_outcome(fqn, verb, args, kwargs, block)
+                return super(verb, *args, **kwargs, &block) if outcome.equal?(Hooks::UNBOUND)
+
+                outcome.equal?(Hooks::BOUND) ? self : outcome
+              end
+            end
+
+            # Defines `respond_to_missing?`, answering true while a `.hecksagon` or `.world` is being declared.
+            #
+            # @param mod [Module] the aggregate module
+            # @return [void]
+            def define_respond_to_missing(mod)
+              mod.define_singleton_method(:respond_to_missing?) do |name, include_private = false|
+                !Bluebook::DSL::HecksagonBuilder.collector.nil? || !Bluebook::DSL::WorldBuilder.current.nil? ||
+                  super(name, include_private)
+              end
+            end
+
+            # Defines `const_missing`. It uses `aggregate.hecks_name`, not the qualified name: qualifying it
+            # would make `Account::Debit`'s meaning depend on whether a stale module from an earlier boot is
+            # still on this process.
+            #
+            # @param mod [Module] the aggregate module
+            # @param aggregate [Bluebook::Aggregate] the aggregate
+            # @return [void]
+            def define_const_missing(mod, aggregate)
+              mod.define_singleton_method(:const_missing) do |name|
+                resolver = Bluebook::DSL::ConstShim.resolver
+                return resolver.call("#{aggregate.hecks_name}::#{name}") if resolver
+
+                super(name)
+              end
+            end
+
+            # Declares a port on an aggregate during a repeat boot, and registers it with the live registry.
+            # Re-resolves the aggregate via `Hecks.current_registry` rather than the closed-over `aggregate`,
+            # which can be stale from an earlier boot.
+            #
+            # @raise [Bluebook::DSL::Malformed] when called outside a boot
+            def attach_port(name, domain, aggregate, fqn, &block)
+              current = current_aggregate(name, domain, aggregate, fqn)
+              built = Bluebook::DSL::ConstShim.with(->(const) { const }) do
+                Bluebook::DSL::DomainPortBuilder.build(name, owner: current.hecks_name, &block)
+              end
+              # A `verb`-shaped port is a plain `Port`, the same struct `Hecks.port` registers. It belongs to
+              # no aggregate IR, so it takes the registry's `add_port` directly. Mirrors `DSL::BindingProxy#port`,
+              # which handles the identical shape on a domain's first in-process boot.
+              return Hecks.current_registry.add_port(built) if built.is_a?(Bluebook::Port)
+
+              reference_operations(built, current)
+              current.add_port(built)
+            end
+
+            # @return [Bluebook::Aggregate] the live registry's copy of the aggregate
+            # @raise [Bluebook::DSL::Malformed] when no boot is in progress
+            def current_aggregate(name, domain, aggregate, fqn)
+              Hecks.current_registry&.bluebook(domain)&.aggregate(aggregate.hecks_name) or
+                raise Bluebook::DSL::Malformed, "#{fqn}.port(#{name.inspect}) called outside a boot"
+            end
+
+            # Points each reference attribute of a port's operations at the aggregate that declares it.
+            def reference_operations(built, current)
+              built.operations.each do |operation|
+                operation.attributes.select(&:reference?).each { |attribute| attribute.type.declared_in = current }
+              end
+            end
+
+            # Answers what a method-missing call means: a bare call's attribute path, the world's record of
+            # a setting, a recorded binding (BOUND), or nothing to bind (UNBOUND).
+            #
+            # @return [Object] the answer, or BOUND or UNBOUND
+            def bound_outcome(fqn, verb, args, kwargs, block)
+              return Bluebook::DSL::AttributePath.new(fqn, [verb.to_s]) if bare_call?(args, kwargs, block)
+
+              collector = Bluebook::DSL::HecksagonBuilder.collector
+              world = Bluebook::DSL::WorldBuilder.current
+              # Inside a `.world` block the same qualified spelling records a world setting.
+              return world.record_binding(verb, args, kwargs, block) if world && !collector
+              return UNBOUND unless collector
+
+              collector << bind_for(fqn, verb, args, kwargs)
+              block&.call
+              BOUND
+            end
+
+            # @return [Boolean] whether the call names no arguments and no block, so it is a bare attribute path
+            def bare_call?(args, kwargs, block)
+              args.empty? && kwargs.empty? && !block
+            end
+
+            # @return [Bluebook::Bind] the binding a qualified call declares
+            def bind_for(fqn, verb, args, kwargs)
+              Bluebook::Bind.new(aggregate: fqn, verb: verb.to_s, adapter: args.first.to_s, role: kwargs[:role]&.to_s)
+            end
+          end
+        end
+      end
+    end
+  end
+end