hecks 6.0.0 → 7.0.0

data/lib/hecks/hecks/adapters/settings_reading.rb

@@ -2,6 +2,12 @@
 
 require "hecks"
 require_relative "console_capture"
+require_relative "../../ports/persistence/binding_policy"
+require_relative "settings_reading/stores"
+require_relative "settings_reading/disposable_ledger"
+require_relative "settings_reading/push_nudge"
+require_relative "settings_reading/test_scope"
+require_relative "work_limits"
 
 module Hecks
   module Adapters
@@ -16,6 +22,15 @@ module Hecks
       # The variables no code reads; one that is set is reported as ignored.
       RETIRED = %w[HECKS_PRE_PUSH_GATE HECKS_EVAL HECKS_FUZZ_SCHEMA].freeze
 
+      # The persistence verb and the store a domain with no bind of its own uses.
+      VERB = Ports::Persistence::VERB
+      DEFAULT = Ports::Persistence::DEFAULT_ADAPTER
+
+      include Stores
+      include DisposableLedger
+      include PushNudge
+      include TestScope
+
       # The first line of a message.
       FIRST_LINE = /\A[^\n]*/
 
@@ -42,10 +57,12 @@ module Hecks
       private
 
       def rows(directory)
-        [environment, database(directory), mint_eras(directory), schema, project_environment,
+        [environment, database(directory), mint_eras(directory), disposable_ledger(directory), work_cap(directory),
+         push_nudge(directory), test_scope(directory),
+         schema, project_environment,
          variable_or_default("cache directory", "HECKS_CACHE_DIR", usage_cache_directory),
          variable_or_default("rust workspace", "HECKS_RUST_DIR", RustBuild.rust_dir),
-         registry_source(directory)]
+         registry_source(directory), *stores(directory)]
       end
 
       def line_of(name, value, source) = "#{name}: #{value} (#{source})"
@@ -92,6 +109,15 @@ module Hecks
         ["mint eras", "could not be read", first_line(e.message)]
       end
 
+      # How many Work rows may be started at once, and whether the world or the default says.
+      def work_cap(directory)
+        registry = Hecks.describe(directory).registry
+        declared = registry.world("Tickets")&.for_verb(WorkLimits::VERB)&.key?(:cap)
+        ["work cap", WorkLimits.cap(registry), declared ? "world" : "default"]
+      rescue StandardError => e
+        ["work cap", "could not be read", first_line(e.message)]
+      end
+
       def mint_wording(declared)
         require "hecks/adapters/driven/postgres_era"
         default = PostgresEra::LineageManager::EraResolver::MINT_BY_DEFAULT

data/lib/hecks/hecks/adapters/started_work.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    # The started `Tickets::Work` rows of a booted registry, with the area each one claims. The
+    # `WorkAreas` and `Landing` adapters both read claims through this.
+    module StartedWork
+      module_function
+
+      # @param registry [Runtime::Registry, nil] the booted registry; nil reads no rows
+      # @return [Array<Hash{Symbol => Object}>] `key:` and `area:` (strings) of each started row
+      def rows(registry)
+        aggregate = work_aggregate(registry)
+        return [] unless aggregate
+
+        registry.repository("Tickets", aggregate).all.filter_map { |record| row(record) }
+      end
+
+      # @return [Object, nil] the Work aggregate, nil when no Tickets bluebook is booted
+      def work_aggregate(registry)
+        bluebook = registry&.bluebook("Tickets")
+        bluebook&.aggregates&.find { |candidate| candidate.hecks_name == "Work" }
+      end
+
+      # @return [Hash, nil] the row's key and area, nil unless the row is started
+      def row(record)
+        return unless value(record, :status) == "started"
+
+        { key: value(record, :work).to_s, area: words(value(record, :area)) }
+      end
+
+      # @return [Array<String>] the areas of a list of Word values
+      def words(list) = Array(list).map { |word| (value(word, :value) || word).to_s }
+
+      # @return [Object] a field of a record or hash, unwrapped from its value object
+      def value(record, name)
+        found = record.respond_to?(name) ? record.public_send(name) : (record[name] if record.respond_to?(:[]))
+        found.respond_to?(:value) ? found.value : found
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/terminal.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "console_capture"
-require "hecks/cli/console"
+require "hecks/tools/console"
 
 module Hecks
   module Adapters
@@ -17,7 +17,7 @@ module Hecks
         attr_accessor :launcher
 
         # @return [#call, nil] serves MCP over stdio, given the arguments after the command;
-        #   `Hecks::CLI::Mcp.call` when nil
+        #   `Hecks::Tools::Mcp.call` when nil
         attr_accessor :server
       end
 
@@ -38,7 +38,7 @@ module Hecks
         subject = held[:subject]
         domain  = subject.is_a?(Hash) ? subject[:value] : subject
         launcher = self.class.launcher
-        launcher ? CLI::Console.call(domain, launcher: launcher) : CLI::Console.call(domain)
+        launcher ? Tools::Console.call(domain, launcher: launcher) : Tools::Console.call(domain)
 
         { output: { value: "console session ended (#{domain || "pizzas"})" } }
       end
@@ -49,13 +49,15 @@ module Hecks
       # only once the client is gone.
       #
       # @param held [Hash] the `Launch` record: `stdio` (whether `--stdio` was given)
-      # @return [Hash{Symbol => Hash}] `output:` a one-line note that the server closed
+      # @return [Hash{Symbol => Hash}] `report:` a one-line note that the server closed, which the
+      #   run records as its outcome; `output:` carries the same note for the launcher's answer
       # @raise [ConsoleCapture::Failure] when the process is not set up for stdio: the server
       #   refused to start, and said why on stderr
       def serve(**held)
         run_server(plain(held[:stdio]) ? ["--stdio"] : [])
 
-        { output: { value: "mcp server closed" } }
+        note = { value: "mcp server closed" }
+        { report: note, output: note }
       rescue SystemExit => e
         raise ConsoleCapture::Failure, "the mcp server refused to start (status #{e.status}); see stderr"
       end
@@ -68,9 +70,9 @@ module Hecks
       # @return [Hash{Symbol => Hash}] `output:` what the interview wrote, or that it wrote nothing
       # @raise [ConsoleCapture::Failure] when the name or adapter is refused, or a file is there
       def converse(**held)
-        require "hecks/cli/interview_run"
-        report = CLI::InterviewRun.call(name: plain(held[:name]), adapter: plain(held[:adapter]), dir: plain(held[:dir]),
-                                        expert: plain(held[:expert]), use_ai: !plain(held[:no_ai]))
+        require "hecks/tools/interview_run"
+        report = Tools::InterviewRun.call(name: plain(held[:name]), adapter: plain(held[:adapter]), dir: plain(held[:dir]),
+                                          expert: plain(held[:expert]), use_ai: !plain(held[:no_ai]))
         { output: { value: report.empty? ? "no interview was written" : report } }
       rescue ArgumentError => e
         raise ConsoleCapture::Failure, e.message
@@ -84,8 +86,8 @@ module Hecks
         if server
           server.call(argv)
         else
-          require "hecks/cli/mcp"
-          CLI::Mcp.call(argv)
+          require "hecks/tools/mcp"
+          Tools::Mcp.call(argv)
         end
       end
 

data/lib/hecks/hecks/adapters/where_reading.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/where_reading"
+
+Hecks.adapter "WhereReading" do
+  port "Where"
+end

data/lib/hecks/hecks/adapters/where_reading.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "hecks"
+require_relative "settings_reading"
+require_relative "../../adapters/driven/worktree_overlay"
+require_relative "../../adapters/driving/launcher_options"
+
+module Hecks
+  module Adapters
+    # The `Where` port's adapter for `Checkout`: the store each bluebook of a checkout's domain
+    # uses and why, the audience and environment with their reasons, and any overlay file this
+    # worktree lacks. It reads and never writes.
+    class WhereReading
+      # The variable that names the environment a copy runs in.
+      VARIABLE = "HECKS_ENVIRONMENT"
+
+      # Accepts the arguments every driven adapter is built with and keeps none of them.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      # @param held [Hash] `domain`, a checkout directory (the current directory when absent)
+      # @return [Hash{Symbol => String}] `text:` one line per fact, each with its reason
+      def where(**held)
+        directory = plain(held[:domain]) || Dir.pwd
+        { text: lines(directory).join("\n") }
+      end
+
+      private
+
+      def lines(directory)
+        ["domain: #{directory}", *store_lines(directory), audience_line(directory), environment_line,
+         *missing_line(directory)]
+      end
+
+      def store_lines(directory)
+        SettingsReading.new.stores(directory).map { |label, value, source| "#{label}: #{value} (#{source})" }
+      end
+
+      def audience_line(directory)
+        return "audience: maintainer (a hecks checkout holds this directory)" if Driving::LauncherOptions.maintainer?(directory)
+
+        "audience: person (no hecks checkout holds this directory)"
+      end
+
+      def environment_line
+        return "environment: #{ENV[VARIABLE]} (#{VARIABLE})" if ENV.key?(VARIABLE)
+
+        "environment: default (#{VARIABLE} is not set)"
+      end
+
+      def missing_line(directory)
+        main, files = WorktreeOverlay.gap(directory)
+        return [] if files.empty?
+
+        ["overlay files this worktree lacks: #{files.join(", ")} (from the main checkout at #{main})"]
+      end
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

data/lib/hecks/hecks/adapters/work_areas.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "area_overlap"
+require_relative "started_work"
+require_relative "console_capture"
+
+module Hecks
+  module Adapters
+    # The `WorkAreas` port's adapter for `Tickets::Work`: says whether a step that was just started
+    # holds ground another started step already holds.
+    #
+    # It reads the other Work rows from the registry it is built with and decides nothing about
+    # the claim beyond the overlap rule in {AreaOverlap}; the bluebook sends a refused step back to
+    # the plan. A step with no area claims nothing and is never refused.
+    class WorkAreas
+      # @param registry [Runtime::Registry, nil] the booted registry whose Work rows are read
+      # @param aggregate [Object, nil] unused
+      def initialize(registry: nil, aggregate: nil)
+        @registry = registry
+      end
+
+      # Clears a started step's area against every other started step's.
+      #
+      # @param held [Hash] the Work row: `work` and `area`
+      # @return [Hash{Symbol => Hash}] `output:` the line that says the area is free
+      # @raise [ConsoleCapture::Failure] naming the row and the overlapping path
+      def check_area(**held)
+        key = plain(held[:work])
+        mine = areas(held[:area])
+        other, pair = mine.empty? ? nil : rival(key, mine)
+        raise ConsoleCapture::Failure, "#{key} cannot claim #{pair[0]}: #{other} holds #{pair[1]}" if other
+
+        { output: { value: "#{key} holds #{mine.empty? ? "no area" : mine.join(", ")}" } }
+      end
+
+      private
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+
+      def areas(list) = Array(list).map { |word| plain(word).to_s }.reject(&:empty?)
+
+      def rival(key, mine)
+        started.each do |row|
+          next if row[:key] == key
+
+          pair = AreaOverlap.first_overlap(mine, row[:area])
+          return [row[:key], pair] if pair
+        end
+        nil
+      end
+
+      def started
+        StartedWork.rows(@registry)
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/work_limits.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "started_work"
+require_relative "console_capture"
+
+module Hecks
+  module Adapters
+    # The `WorkLimits` port's adapter for `Tickets::Work`: the concurrency cap on started rows.
+    #
+    # It reads the other Work rows from the registry it is built with, the cap from the Tickets
+    # world's `work_limit` setting. It decides nothing
+    # about what happens next: the bluebook sends a refused start back to the plan.
+    class WorkLimits
+      # The cap when the Tickets world declares none.
+      DEFAULT_CAP = 8
+
+      # The world verb that carries the cap.
+      VERB = "work_limit"
+
+      # @param registry [Runtime::Registry, nil] the booted registry whose Work rows are read
+      # @param aggregate [Object, nil] unused
+      def initialize(registry: nil, aggregate: nil)
+        @registry = registry
+      end
+
+      # The cap on started rows a registry's Tickets world declares.
+      #
+      # @param registry [Runtime::Registry, nil]
+      # @return [Integer] the declared cap, else {DEFAULT_CAP}
+      def self.cap(registry)
+        declared = registry&.world("Tickets")&.for_verb(VERB)
+        declared && !declared[:cap].nil? ? Integer(declared[:cap]) : DEFAULT_CAP
+      end
+
+      # Clears a just-started row against the cap.
+      #
+      # @param held [Hash] the Work row: `work`
+      # @return [Hash{Symbol => Hash}] `output:` the line that says the cap holds
+      # @raise [ConsoleCapture::Failure] naming the cap, the count and the holders
+      def check_cap(**held)
+        key = plain(held[:work])
+        holders = StartedWork.rows(@registry).map { |row| row[:key] }
+        limit = self.class.cap(@registry)
+        if holders.include?(key) && holders.size > limit
+          raise ConsoleCapture::Failure,
+                "#{key} would be started row #{holders.size} of a cap of #{limit}; started: #{holders.join(", ")}"
+        end
+
+        { output: { value: "#{key} is within the cap of #{limit} (#{holders.size} started)" } }
+      end
+
+      private
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end