hecks 2.9.0 → 3.0.0

data/lib/hecks/facade/cli_door.rb

@@ -1,96 +0,0 @@
-require_relative "../runtime/errors"
-
-module Hecks
-  module Facade
-    # Turns `path=value` command-line words into a nested, typed argument Hash.
-    # Types come from the projection, never from guessing at the value ("99" may be a String).
-    module CliDoor
-      module_function
-
-      # Builds a verb's nested, typed argument Hash from its `name=value` words.
-      #
-      #   arguments(spec, ["reference.value=A-1", "sequence.value=99"])
-      #   # => { reference: { value: "A-1" }, sequence: { value: 99 } }
-      #
-      # @param spec [Hash{Symbol => Object}] one verb's entry from `Projector::CliProjector`
-      # @param pairs [Array<String>] the words after the verb; a path may be the short form
-      #   of a single-field value object (`reference` for `reference.value`)
-      # @return [Hash{Symbol => Object}] the arguments nested by path, leaves cast to type
-      # @raise [Runtime::NotFound] if a pair has no `=` or names a path the verb lacks
-      # @raise [Runtime::TypeMismatch] if a value does not parse as its Integer or Float
-      def arguments(spec, pairs)
-        # Extra accepted arguments stay out of help, which teaches only to=....
-        options = (spec[:arguments] + Array(spec[:legacy_arguments])).to_h do |argument|
-          [argument[:path], argument]
-        end
-
-        pairs.each_with_object({}) do |pair, args|
-          path, value = split(pair)
-          # key? rather than `||`, so the lookup below honors the same spelling `full` chose.
-          full     = options.key?(path) ? path : expand(path, options)
-          argument = options.key?(full) ? options[full] : raise(Runtime::NotFound, unknown(path, options.keys))
-
-          next append(args, full.split("."), cast(value, argument[:type])) if argument[:list]
-
-          bury(args, full.split("."), cast(value, argument[:type]))
-        end
-      end
-
-      # Cuts one word at its first `=`, so a value may itself contain `=`.
-      def split(pair)
-        name, value = pair.split("=", 2)
-        raise Runtime::NotFound, "#{pair.inspect} is not name=value" if value.nil?
-
-        [name, value]
-      end
-
-      # Expands a bare value-object name into the path of its only field.
-      # Left unchanged when several fields match, since guessing which was meant is worse.
-      def expand(path, options)
-        candidates = options.keys.select { |key| key.start_with?("#{path}.") }
-        candidates.length == 1 ? candidates.first : path
-      end
-
-      # Converts one value to its declared type; only Integer, Float and Boolean convert.
-      # A Boolean is true only for `true`, `yes` or `1` in any letter case.
-      def cast(value, type)
-        case type
-        when "Integer" then Integer(value)
-        when "Float"   then Float(value)
-        when "Boolean" then %w[true yes 1].include?(value.downcase)
-        else value
-        end
-      rescue ArgumentError
-        raise Runtime::TypeMismatch, "#{value.inspect} is not #{type} — the chapter declares this field as #{type}"
-      end
-
-      # Appends one element to a list argument, creating the list on first use.
-      #
-      # Repeats must grow the list (`bury` would silently keep only the last), and a single
-      # element is still a one-item list, since a `list_of` attribute must never see a bare
-      # object. Multi-field elements are left to `JsonDoor`: a flat command line cannot say
-      # which `a.x=` pairs with which `a.y=`.
-      def append(hash, path, value)
-        *branches, leaf = path.map(&:to_sym)
-        holder = branches[0..-2].reduce(hash) { |node, key| node[key] ||= {} }
-        list   = holder[branches.last] ||= []
-
-        list << { leaf => value }
-        hash
-      end
-
-      # Sets one value at a nested path, creating intermediate Hashes and overwriting the leaf.
-      def bury(hash, path, value)
-        *branches, leaf = path.map(&:to_sym)
-        target = branches.reduce(hash) { |node, key| node[key] ||= {} }
-        target[leaf] = value
-        hash
-      end
-
-      # Words the refusal for an argument the verb does not take, listing what it does.
-      def unknown(path, known)
-        "no argument #{path.inspect} — this verb takes #{known.sort.join(', ')}"
-      end
-    end
-  end
-end

data/lib/hecks/facade/cli_runner.rb

@@ -1,127 +0,0 @@
-require "json"
-require_relative "cli_door"
-require_relative "command_request"
-require_relative "json_door"
-require_relative "../projector"
-require_relative "../ports/clock"
-
-module Hecks
-  module Facade
-    # Parses and dispatches a command line against a `Projector::CliProjector` projection.
-    # Does no IO: it answers `[text, status]` and leaves printing and exiting to `bin/` scripts.
-    module CliRunner
-      module_function
-
-      # Runs one command line against a booted domain and answers the text to print.
-      # Only the first bluebook in the registry, the booted domain's own, is projected.
-      #
-      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain
-      # @param argv [Array<String>] an optional `ask`, the verb or question name, then
-      #   `path=value` pairs; `--help`, `-h`, `help` or nothing answers usage
-      # @param program [String] how the caller was invoked, echoed in usage and hints
-      # @return [Array(String, Integer)] the text and the status: 0 answered, 1 refused or misused
-      # @raise [Runtime::WiringError] if a repository or the clock adapter cannot be resolved
-      # @raise [Runtime::StaleWrite] if concurrent writers beat the command through every retry
-      def call(runtime:, argv:, program: "bin/run")
-        bluebook = runtime.registry.bluebooks.values.first
-        cli      = Projector.call(:cli, bluebook: bluebook, options: { program: program })
-
-        name = argv.first
-        return [cli[:usage], 0] if name.nil? || %w[--help -h help].include?(name)
-
-        # `ask` gives questions their own namespace; a chapter may declare a command and query
-        # of one name.
-        asking = name == "ask"
-        argv   = argv[1..] if asking
-        name   = argv.first
-        return [cli[:usage], 1] if name.nil?
-
-        # The alias map lets `create_pizza` and `order.create_pizza` reach the same verb.
-        pool = asking ? cli[:questions] : cli[:verbs]
-        key  = cli[:names][asking ? :question : :command][name]
-        spec = pool[key]
-        return [unknown(cli, name, asking, program), 1] unless spec
-
-        rest = argv[1..]
-        if rest.include?("--help")
-          help = Projector.call(:cli, bluebook: bluebook,
-                                      options:  { program: program, verb: name, ask: asking })[:usage]
-          return [help, 0]
-        end
-
-        dispatch(runtime, spec, name, rest, program, asking)
-      end
-
-      # Parses one resolved verb's arguments, runs it as a query or command, and turns the
-      # outcome, or the domain's refusal, into `[json_or_message, status]`.
-      def dispatch(runtime, spec, name, rest, program, asking)
-        args = stamp_time(runtime, spec, CliDoor.arguments(spec, rest))
-
-        if spec[:kind] == :query
-          rows = runtime.query(spec[:verb], **args)
-          return [JSON.pretty_generate(rows.map { |row| JsonDoor.materialize(row) }), 0]
-        end
-
-        # Answers with only this verb's outcome; a full store dump is every record there is.
-        request = CommandRequest.normalize(args, receiver:        spec[:receiver],
-                                                 legacy_receiver: spec[:legacy_receiver])
-        handle = runtime.dispatch_flat(spec[:verb], request)
-        return [JSON.pretty_generate(answered(handle)), 0] if handle.state.nil?
-
-        [JSON.pretty_generate(id:     handle.id,
-                              state:  JsonDoor.materialize(handle.state),
-                              events: handle.events.map(&:name)), 0]
-      rescue Runtime::NotFound, Runtime::TypeMismatch => e
-        # A bad argument and a missing record both need the same next step: read the help.
-        ["#{e.message}\n\n  #{program} #{'ask ' if asking}#{name} --help", 1]
-      rescue *Runtime::DOMAIN_REFUSALS => e
-        # The refusal is the chapter's own sentence, verbatim.
-        [e.message, 1]
-      end
-
-      # Fills in a `now` argument the caller left out, from the clock port; an explicit one wins.
-      #
-      # Done at the door, not in the runtime: a clock read inside the interpreter would give a
-      # replayed corpus step the replay day's time. Matched by the argument's name alone.
-      def stamp_time(runtime, spec, args)
-        return args unless spec[:arguments].any? { |argument| argument[:path].start_with?("now.") }
-        return args if args.key?(:now)
-
-        args.merge(now: { value: Ports::Clock.now(runtime.registry) })
-      end
-
-      # Shapes a port operation's outcome, which has no state: each event with its full payload.
-      #
-      # The answer lives only in the payloads, so names alone would drop it. Exit status stays 0
-      # for refusal events too, since a healthy no is an answer, not a misuse.
-      def answered(handle)
-        # A port operation hydrates no instance, so the handle's `id` is nil by design.
-        { id:     handle.id || handle.events.first&.id,
-          events: handle.events.map do |event|
-            { name: event.name, payload: JsonDoor.materialize(event.payload) }
-          end }
-      end
-
-      # Words the answer for an unknown verb or question, suggesting up to five near names.
-      # Ranked by shared prefix, which survives a dropped letter where a substring match would not.
-      def unknown(cli, name, asking, program)
-        # Both spellings are candidates: `order.create_piza` shares no prefix with `create_pizza`.
-        pool = cli[:names][asking ? :question : :command].keys
-        near = pool.map    { |candidate| [shared_prefix(candidate, name), candidate] }
-                   .select { |shared, _| shared >= [name.length / 2, 3].max }
-                   .sort_by { |shared, candidate| [-shared, candidate] }
-                   .map(&:last)
-
-        lines = ["no such #{asking ? 'question' : 'verb'}: #{name}"]
-        lines += ["", "did you mean:", *near.first(5).map { |candidate| "  #{candidate}" }] unless near.empty?
-        lines += ["", "  #{program}#{' ask' if asking}   for the full list"]
-        lines.join("\n")
-      end
-
-      def shared_prefix(one, other)
-        length = [one.length, other.length].min
-        (0...length).find { |index| one[index] != other[index] } || length
-      end
-    end
-  end
-end

data/lib/hecks/mcp_door_scope.rb

@@ -1,95 +0,0 @@
-require_relative "runtime/errors"
-
-module Hecks
-  # What a spawned bin/hecks_mcp_door may do: every tool by default, or only
-  # reader tools against named domains in reader mode — reach, not identity (ADR 0072).
-  class McpDoorScope
-    ENV_PREFIX       = "HECKS_DOOR_".freeze
-    TOOLS_VARIABLE   = "HECKS_DOOR_TOOLS".freeze
-    DOMAINS_VARIABLE = "HECKS_DOOR_DOMAINS".freeze
-    READERS          = "readers".freeze
-    EXIT_STATUS      = 2
-
-    # The tools a reader door serves — each reads a domain or the door's own
-    # audit log and writes no domain state. `validate` still boots its
-    # domain, so it stays bound to the allowed set like every other tool.
-    READER_TOOLS = %w[query events state catalog describe validate domains history follow].freeze
-
-    # Unrestricted when no HECKS_DOOR_* variable is set.
-    def self.from_env(env = ENV)
-      problems = setting_problems(env)
-      raise ArgumentError, problems.join("\n") unless problems.empty?
-      return new(allowed_domains: nil) unless env[TOOLS_VARIABLE]
-
-      new(allowed_domains: env[DOMAINS_VARIABLE].split(File::PATH_SEPARATOR).reject(&:empty?))
-    end
-
-    # Refuses to stderr, not stdout, which carries the MCP protocol.
-    def self.start!(server:, env: ENV, stderr: $stderr)
-      from_env(env)
-    rescue ArgumentError, Runtime::TypeMismatch => e
-      e.message.each_line { |line| stderr.puts("#{server}: refusing to start: #{line.chomp}") }
-      exit(EXIT_STATUS)
-    end
-
-    def self.setting_problems(env)
-      unknown = env.keys.select { |name| name.start_with?(ENV_PREFIX) } - [TOOLS_VARIABLE, DOMAINS_VARIABLE]
-      problems = unknown.map do |name|
-        "environment #{name} is not accepted; the door takes only #{TOOLS_VARIABLE} and #{DOMAINS_VARIABLE}"
-      end
-      problems + mode_problems(env[TOOLS_VARIABLE], env[DOMAINS_VARIABLE])
-    end
-
-    def self.mode_problems(tools, domains)
-      if tools.nil?
-        domains.nil? ? [] : ["#{DOMAINS_VARIABLE} is set without #{TOOLS_VARIABLE}=#{READERS}; it only narrows a reader door"]
-      elsif tools != READERS
-        ["#{TOOLS_VARIABLE}=#{tools.inspect} is not accepted; the only value is #{READERS.inspect}"]
-      elsif domains.to_s.split(File::PATH_SEPARATOR).none? { |path| !path.empty? }
-        ["#{TOOLS_VARIABLE}=#{READERS} needs #{DOMAINS_VARIABLE}, the domains this door may read"]
-      else
-        []
-      end
-    end
-
-    # The named domains, resolved against Storehouse::BOOT_ROOT; nil when unrestricted.
-    attr_reader :allowed_domains
-
-    def initialize(allowed_domains:)
-      @allowed_domains = allowed_domains&.map { |path| Storehouse.confine!(path, DOMAINS_VARIABLE) }.freeze
-    end
-
-    def restricted?
-      !@allowed_domains.nil?
-    end
-
-    def permits_tool?(name)
-      !restricted? || READER_TOOLS.include?(name)
-    end
-
-    def refusal(name)
-      { ok:    false,
-        error: "#{name.inspect} is refused: this door runs in reader mode (#{TOOLS_VARIABLE}=#{READERS}), " \
-               "which serves only #{READER_TOOLS.join(', ')}" }
-    end
-
-    # Checked before anything boots, so a path outside the allowed set never reaches Kernel.load.
-    def admit_domain!(domain)
-      return domain unless restricted?
-      return domain if @allowed_domains.include?(Storehouse.confine!(domain, "domain"))
-
-      raise Runtime::TypeMismatch,
-            "domain: #{domain.inspect} is refused: this door runs in reader mode (#{TOOLS_VARIABLE}=#{READERS}) " \
-            "and reads only #{DOMAINS_VARIABLE}: #{@allowed_domains.join(', ')}"
-    end
-
-    def notes
-      return [] unless restricted?
-
-      ["Reader mode (#{TOOLS_VARIABLE}=#{READERS}): serves #{READER_TOOLS.join(', ')}; " \
-       "refuses dispatch (with dry_run and steps), behaviors and every other tool.",
-       "domain: boots only #{DOMAINS_VARIABLE}: #{@allowed_domains.join(', ')}.",
-       "Reader mode limits reach and identifies no one; it is not authentication."]
-    end
-  end
-end