hecks 3.1.3 → 3.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88b11874249737158a9451d66aa0842ef88fb3f1ff047cced68d97b2ce9fdc5f
-  data.tar.gz: 2872e381ce8e7fe5d46ef7a7623134dc23d923e57bdf194758effedaa1cc4671
+  metadata.gz: 9b963870a34a1483bc0156042a2967a72f8fc1b8e907ba5d8cac5a5382d4999d
+  data.tar.gz: 26697af02778cda282a44c1ca099e36a9866bf2d204ab5abb23df8ac2a86283a
 SHA512:
-  metadata.gz: 76a39ab361adfb4e07bb558cb917d46bf3d7b6bb21340ff9789cb7b6c10be47a3197df4f394e8da73129feeb5b8439d9401f5e83b8620e0a512fce966c891377
-  data.tar.gz: 58f1514450a234f3807897401daf7db410739463a8603bf58b7d73e548f14424211b4d1c5f3af1dc7421b769f39582e15c6f22188932af3de054961eed2cb641
+  metadata.gz: a81b0ffb4b0e04024518169e3c6dd51a3f55b5da39659a852c2a0c9528453fe0eb9facf07d7b18bd35d7924c5a08331b2f1ad82a7e5c4c43c61fae55490d46ed
+  data.tar.gz: f6780cb0c58069a5049081c7a319424787c9fea1fd94a5085153d7b99533c0e1974c23dfeb3515b66f3b2d8d3c7ca83a08dcd5f024df02da2b2fc9609c3ba6b7

data/lib/hecks/bluebook/dsl/hecksagon_builder.rb

@@ -57,9 +57,9 @@ module Hecks
           end
         end
 
-        # The release that drops the deprecated spellings of `attaches`; kept in step with
-        # `Hecks::Doors::REMOVAL`, which this file cannot require.
-        REMOVAL = "3.2.0".freeze
+        # The release that drops the deprecated spellings of `attaches`; independent of
+        # `Hecks::Doors::REMOVAL`, which covers the older `Facade` aliases.
+        REMOVAL = "3.3.0".freeze
 
         attr_reader :binds, :subscriptions, :attachments
 

data/lib/hecks/cli/check_era.rb

@@ -2,11 +2,9 @@ require_relative "../ports/persistence/plugins/era/expected_era"
 
 module Hecks
   module CLI
-    # The command behind `hecks check_era` and Custodian's `Host.CheckEra`: asks a running host
-    # which era it reports and compares it with an allow-list file. Read-only: one GET, no writes.
+    # The check behind Custodian's `Host.CheckEra`: asks a running host which era it reports and
+    # compares it with an allow-list file. Read-only: one GET, no writes.
     module CheckEra
-      USAGE = "usage: hecks check_era <url> <expected-era-file> [--timeout=<seconds>]".freeze
-
       # What a check found.
       #
       # @!attribute [r] verdict
@@ -14,7 +12,7 @@ module Hecks
       # @!attribute [r] version
       #   @return [String] the gem version the host reports, empty when it reports none
       # @!attribute [r] line
-      #   @return [String] the sentence `hecks check_era` prints for this finding
+      #   @return [String] the sentence the check reports for this finding
       Finding = Struct.new(:verdict, :version, :line)
 
       module_function
@@ -36,35 +34,6 @@ module Hecks
         Finding.new(verdict, document.fetch("version"), sentence(verdict, file))
       end
 
-      # Runs `hecks check_era`: prints the finding and answers the exit status.
-      #
-      # @param argv [Array<String>] the url, the allow-list file and an optional `--timeout=N`
-      # @param out [IO] where a finding goes
-      # @param err [IO] where a refusal goes
-      # @return [Integer] 0 when the era is expected or unlisted, 1 on a mismatch, 2 on bad
-      #   usage or an unreadable file, 3 when the host cannot be reached or answers no era
-      def run(argv, out: $stdout, err: $stderr)
-        timeout = 10
-        args = argv.reject do |arg|
-          next false unless arg.start_with?("--timeout=")
-
-          timeout = arg.delete_prefix("--timeout=").to_f
-          true
-        end
-        url, file = args
-        return usage(err) unless url && file && args.size == 2 && timeout.positive?
-
-        finding = assess(url, file, timeout: timeout)
-        (finding.verdict.ok? ? out : err).puts(finding.line)
-        finding.verdict.ok? ? 0 : 1
-      rescue Errno::ENOENT, Errno::EACCES => e
-        err.puts("cannot read #{file}: #{e.message}")
-        2
-      rescue Runtime::EraCheck::ExpectedEra::Unreachable, Runtime::EraCheck::ExpectedEra::BadResponse => e
-        err.puts("era check failed: #{e.message}")
-        3
-      end
-
       # @param verdict [Runtime::EraCheck::ExpectedEra::Verdict] the comparison
       # @param file [String] the allow-list file, named in the sentence
       # @return [String] the one line that says what the comparison found
@@ -78,11 +47,6 @@ module Hecks
           "host reports era #{verdict.era}, which is not in #{file} (expected: #{verdict.allowed.join(', ')})"
         end
       end
-
-      def usage(err)
-        err.puts(USAGE)
-        2
-      end
     end
   end
 end

data/lib/hecks/deploy/bluebook/deploy.bluebook

@@ -665,6 +665,111 @@ Hecks.bluebook "Deploy" do
     trigger MakefileCheck::Flag, with: { refusal: :refusal }
   end
 
+  aggregate "CostCheck" do
+    description "One reading of what hosting costs a month, against a budget."
+
+    attribute :run,     RunKey
+    attribute :budget,  Budget
+    attribute :since,   Since
+    attribute :report,  Report, optional: true
+    attribute :refusal, Report, optional: true
+    identified_by :run
+
+    value_object "RunKey" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a run is named") { !value.to_s.empty? }
+    end
+
+    # Whole dollars a month.
+    value_object "Budget" do
+      attribute :value, Integer
+
+      invariant("a budget is positive") { value.positive? }
+    end
+
+    # The first day to count, as `YYYY-MM-DD`: the first complete day after the last change to
+    # what is running, so a bill that still carries the old setup is not read as the new one.
+    value_object "Since" do
+      attribute :value, String, pattern: '[0-9]{4}-[0-9]{2}-[0-9]{2}'
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    lifecycle :status, default: "requested" do
+      transition "Pass" => "within_budget", from: "requested"
+      transition "Flag" => "flagged",       from: "requested"
+    end
+
+    # The reading is the billed daily total from the first complete day since `since` up to
+    # yesterday, scaled to a month; today is left out because its bill is still partial.
+    command "Check" do
+      goal "Read what hosting has billed since a day and compare its monthly rate to a budget"
+
+      attribute :run,    RunKey
+      attribute :budget, Budget
+      attribute :since,  Since
+
+      sets :run
+      sets :budget
+      sets :since
+
+      emits "CostCheckRequested"
+    end
+
+    command "Pass" do
+      goal "Record that the monthly rate is within the budget, and what it was"
+
+      reference_to CostCheck
+      attribute :report, Report
+
+      sets :report
+
+      emits "CostWithinBudget"
+    end
+
+    command "Flag" do
+      goal "Record that the monthly rate is over the budget, or that it could not be read, and what was said"
+
+      reference_to CostCheck
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits "CostFlagged"
+    end
+
+    query "Verdict" do
+      description "What one reading found: its status, and the report or the reason it was flagged."
+      attribute :run, RunKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "Flagged" do
+      description "Every reading that was over its budget or could not be taken."
+      where(status: "flagged")
+      order_by :run
+    end
+  end
+
+  policy "MeasureWhenChecked" do
+    on      "CostCheck.CostCheckRequested"
+    trigger CostCheck::CostExplorer::Measure, with: { run: :run }
+  end
+
+  policy "RecordTheCostWithinBudget" do
+    on      "CostCheck.CostAnswered"
+    trigger CostCheck::Pass, with: { report: :report }
+  end
+
+  policy "RecordTheFlaggedCost" do
+    on      "CostCheck.CostRefused"
+    trigger CostCheck::Flag, with: { refusal: :refusal }
+  end
+
   aggregate "TemplateComparison" do
     description "One offline comparison of two CloudFormation templates, by logical id."
 

data/lib/hecks/deploy/bluebook/deploy.hecksagon

@@ -35,6 +35,14 @@ Hecks.hecksagon "Deploy" do
     end
   end
 
+  Deploy::CostCheck.port "CostExplorer" do
+    asks "Measure", to: CostCheck do
+      attribute :run, RunKey
+      answers "CostAnswered"
+      refuses "CostRefused"
+    end
+  end
+
   Deploy::TemplateComparison.port "DeployToolchain" do
     asks "Compare", to: TemplateComparison do
       attribute :run, RunKey

data/lib/hecks/deploy/oidc.json

@@ -6,6 +6,21 @@
       "verb": "Deploy::BoxTarget.Declare",
       "role": null
     },
+    {
+      "scope": "deploy:cost_check.check",
+      "verb": "Deploy::CostCheck.Check",
+      "role": null
+    },
+    {
+      "scope": "deploy:cost_check.flag",
+      "verb": "Deploy::CostCheck.Flag",
+      "role": null
+    },
+    {
+      "scope": "deploy:cost_check.pass",
+      "verb": "Deploy::CostCheck.Pass",
+      "role": null
+    },
     {
       "scope": "deploy:fargate_target.declare",
       "verb": "Deploy::FargateTarget.Declare",

data/lib/hecks/doors/mcp_door.rb

@@ -343,7 +343,20 @@ module Hecks
       def answer_tool(name, args)
         return scope.refusal(name) unless scope.permits_tool?(name)
 
-        call_tool(name, args)
+        call_tool(name, scope.with_default_domain(args))
+      end
+
+      # One line per allowed command: what it takes and the role it declares, read from the booted
+      # domain the door serves. Nil when the door serves no single domain or it will not boot, so
+      # `tools/list` still answers, with the commands as a bare list.
+      def command_guide
+        return unless scope.commands_mode? && scope.default_domain
+
+        McpGuideCache.remember(scope.default_domain, scope.allowed_commands) do
+          Storehouse.command_guide(boot(scope.default_domain), scope.allowed_commands)
+        end
+      rescue StandardError
+        nil
       end
 
       def tool_result(payload)
@@ -374,7 +387,8 @@ module Hecks
           nil # a notification — no id, no response
         when "tools/list"
           served = TOOLS.select { |tool| scope.permits_tool?(tool[:name]) }
-          send_response(id, { tools: served.map { |tool| scope.present(tool) } })
+          guide = command_guide
+          send_response(id, { tools: served.map { |tool| scope.present(tool, guide) } })
         when "tools/call"
           send_response(id, tool_result(answer_tool(params["name"], params["arguments"] || {})))
         when "ping"

data/lib/hecks/doors/mcp_door_scope.rb

@@ -201,18 +201,40 @@ module Hecks
         end
       end
 
-      # The tool as `tools/list` shows it: on a commands door, `dispatch` names the commands it
-      # serves, so a caller sees them as an enum instead of finding out by being refused.
+      # The one domain a restricted door serves, when it serves exactly one: a call may leave
+      # `domain:` out and get it. Nil for an unrestricted door and for one that names several.
+      #
+      # @return [String, nil] the domain path as `HECKS_DOOR_DOMAINS` named it, resolved
+      def default_domain
+        @allowed_domains.first if restricted? && @allowed_domains.size == 1
+      end
+
+      # The arguments with the default domain filled in when the caller left it out.
+      #
+      # @param args [Hash] a tool call's arguments
+      # @return [Hash] `args`, with `"domain"` set when the door has a default and none was given
+      def with_default_domain(args)
+        return args unless default_domain && args["domain"].to_s.strip.empty?
+
+        args.merge("domain" => default_domain)
+      end
+
+      # The tool as `tools/list` shows it. A door that serves one domain makes `domain:` optional.
+      # On a commands door, `dispatch` also names the commands it serves as an enum, so a caller
+      # sees them as typed choices instead of finding out by being refused, and says what each
+      # takes and which role it declares.
       #
       # @param tool [Hash] a tool definition from `McpDoor::TOOLS`
+      # @param guide [Array<String>, nil] one line per allowed command (`Storehouse.command_guide`)
       # @return [Hash] the definition, narrowed for this door
-      def present(tool)
+      def present(tool, guide = nil)
+        tool = domain_optional(tool) if default_domain
         return tool unless commands_mode? && tool[:name] == "dispatch"
 
         properties = tool[:inputSchema][:properties]
         narrowed = properties.merge(command: with_enum(properties[:command]),
                                     steps:   properties[:steps].merge(items: step_items(properties[:steps][:items])))
-        tool.merge(description: "#{tool[:description]} This door dispatches only: #{allowed_commands.join(', ')}.",
+        tool.merge(description: dispatch_description(tool[:description], guide),
                    inputSchema: tool[:inputSchema].merge(properties: narrowed))
       end
 
@@ -287,6 +309,23 @@ module Hecks
         File.join(File.realpath(current), *missing)
       end
 
+      def domain_optional(tool)
+        schema = tool[:inputSchema]
+        return tool unless schema[:properties].key?(:domain)
+
+        note = "Optional: this door serves one domain, #{default_domain}, and uses it when you leave this out."
+        properties = schema[:properties].merge(domain: schema[:properties][:domain].merge(description: note))
+        tool.merge(inputSchema: schema.merge(properties: properties, required: schema[:required] - ["domain"]))
+      end
+
+      def dispatch_description(base, guide)
+        intro = "#{base} This door dispatches only the commands below, each with the role it declares: pass " \
+                "that role as `role`. A command that takes `run` takes a key you choose, and the call answers " \
+                "the record as it stands once its reactions have run; an argument marked * is required."
+        entries = Array(guide).empty? ? allowed_commands : guide
+        ([intro] + entries.map { |entry| "- #{entry}" }).join("\n")
+      end
+
       def with_enum(property)
         property.merge(enum: allowed_commands)
       end

data/lib/hecks/doors/mcp_guide_cache.rb

@@ -0,0 +1,75 @@
+require "digest"
+require "fileutils"
+require "json"
+require_relative "../cache_dir"
+require_relative "../storehouse"
+require_relative "../bluebook/meta_validator/verdict_cache"
+
+module Hecks
+  module Doors
+    # Remembers the command guide a commands door builds for `tools/list`, so a door that starts
+    # again does not boot its domain to describe its commands. A client waits only a moment for a
+    # server's tools, and a boot at that point costs more than the wait.
+    #
+    # An entry is keyed by the domain directory's files, a digest of the hecks code, and the
+    # allowed commands, so a change to any of them builds a new guide. The file is JSON, read only
+    # from a directory and a file that only this user can write (the verdict cache's own check),
+    # and only when it is a list of strings: a guide is text an agent reads as instructions.
+    module McpGuideCache
+      module_function
+
+      # The guide for a domain and its allowed commands, from the cache or else from the block,
+      # which is then remembered. A cache that cannot be written is not an error: the next start
+      # builds the guide again.
+      #
+      # @param domain [String] the domain directory the guide describes
+      # @param commands [Array<String>] the allowed command names
+      # @yieldreturn [Array<String>, nil] the guide, built when none is remembered
+      # @return [Array<String>, nil] the guide
+      def remember(domain, commands)
+        file = File.join(dir, "#{key(domain, commands)}.json")
+        cached = read(file)
+        return cached if cached
+
+        guide = yield
+        write(file, guide) if guide.is_a?(Array) && guide.any?
+        guide
+      end
+
+      # @return [String] the directory entries live in
+      def dir = Hecks::CacheDir.path("mcp_door_guides")
+
+      # @param domain [String] the domain directory
+      # @param commands [Array<String>] the allowed command names
+      # @return [String] a hex SHA-256 over the domain's files, the hecks code and the commands
+      def key(domain, commands)
+        parts = [Storehouse.fingerprint(domain), Bluebook::MetaValidator::VerdictCache.code_digest,
+                 commands.sort.join(",")]
+        Digest::SHA256.hexdigest(parts.join("\0"))
+      end
+
+      # @param file [String] an entry's path
+      # @return [Array<String>, nil] the guide, or nil when absent, untrusted or malformed
+      def read(file)
+        return unless File.file?(file) && Bluebook::MetaValidator::VerdictCache.trusted?(file)
+
+        guide = JSON.parse(File.read(file))
+        guide if guide.is_a?(Array) && guide.all?(String)
+      rescue StandardError
+        nil
+      end
+
+      # @param file [String] an entry's path
+      # @param guide [Array<String>] the guide to remember
+      # @return [void]
+      def write(file, guide)
+        FileUtils.mkdir_p(dir, mode: 0o700)
+        temp = "#{file}.#{Process.pid}.tmp"
+        File.write(temp, JSON.generate(guide), perm: 0o600)
+        File.rename(temp, file)
+      rescue StandardError
+        FileUtils.rm_f(temp) if temp
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/properties/dispatch_and_mutations.rb

@@ -118,8 +118,9 @@ module Hecks
 
             owner = owner_for_verb(bluebooks, entry[:verb]) || aggregate
 
+            args = with_declared_defaults(command, entry[:args])
             command.mutations.select { |m| RECOMPUTABLE_MUTATION_OPS.include?(m.op) }.filter_map do |mutation|
-              expected = recompute_mutation(mutation, entry[:before][mutation.target], entry[:args], entry[:before],
+              expected = recompute_mutation(mutation, entry[:before][mutation.target], args, entry[:before],
                                             aggregate, command, owner)
               next if expected == :unrecomputable
 
@@ -134,6 +135,21 @@ module Hecks
           offenders.empty? || offenders.join("; ")
         end
 
+        # The arguments the command actually ran with: an argument the caller left out takes the
+        # default its attribute declares, as dispatch fills it, so the recomputation starts from
+        # the same facts.
+        #
+        # @param command [Object] the command the step dispatched
+        # @param args [Hash] the arguments the step offered
+        # @return [Hash] `args`, with each omitted defaulted argument filled
+        def with_declared_defaults(command, args)
+          command.attributes.each_with_object(args.dup) do |attribute, held|
+            next if attribute.default.nil? || held.key?(attribute.name.to_sym) || held.key?(attribute.name.to_s)
+
+            held[attribute.name.to_sym] = attribute.default
+          end
+        end
+
         # Root aggregate for `verb`, derived from the verb alone because hand-built
         # entries may lack `:domain`/`:aggregate`. Value-object types resolve against
         # the root's namespace only.

data/lib/hecks/hecks/adapters/codebase/test_runner.rb

@@ -38,7 +38,9 @@ module Hecks
           status = Dir.chdir(@tree.root) { runner.call(["--example", example, path], out, out) }
           raise ConsoleCapture::Failure, out.string.strip unless status.zero?
 
-          out.string.strip
+          out.string.strip.tap do |report|
+            raise ConsoleCapture::Failure, "the test runner printed nothing for #{file}" if report.empty?
+          end
         end
 
         private
@@ -47,7 +49,13 @@ module Hecks
           return self.class.runner if self.class.runner
 
           require "rspec/core"
-          RSpec::Core::Runner.method(:run)
+          # A process that runs one example after another, as a resident door does, has to reset
+          # RSpec between runs: its reporter keeps the first run's output stream, so a later run
+          # would write into that and answer an empty report.
+          lambda do |args, err, out|
+            RSpec.reset
+            RSpec::Core::Runner.run(args, err, out)
+          end
         end
       end
     end

data/lib/hecks/hecks/adapters/cost_explorer.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/cost_explorer"
+
+Hecks.adapter "CostExplorer" do
+  port "CostExplorer"
+end

data/lib/hecks/hecks/adapters/cost_explorer.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "open3"
+require "json"
+require "date"
+
+module Hecks
+  module Adapters
+    # The `CostExplorer` port's adapter: reads what an AWS account has billed, with the `aws`
+    # command, and compares the monthly rate to a budget.
+    #
+    # It reads the daily unblended cost from the check's `since` day up to yesterday. Today is left
+    # out because its bill is still partial, and a day is counted whatever Cost Explorer marks it
+    # (a day stays "estimated" for a while after it ends). The rate is the mean daily cost scaled
+    # to an average month. A rate within the budget is answered with a one-line report; a rate over
+    # it, a span with no complete day, or a failed `aws` call is refused with a reason, which the
+    # runtime records on the check.
+    class CostExplorer
+      # Days in an average month, for scaling a daily mean to a monthly rate.
+      DAYS_IN_MONTH = 30.4375
+
+      # How many of the biggest services the report names.
+      TOP_SERVICES = 3
+
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] `today:` pins the day the span ends before, for tests
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil)
+        @today = settings[:today]
+      end
+
+      # Reads the billed cost since a day and compares its monthly rate to the budget.
+      #
+      # @param held [Hash] the check's fields: `budget:` whole dollars a month and `since:` the
+      #   first day to count (`YYYY-MM-DD`), each a value object or a plain value
+      # @return [Hash{Symbol => Hash}] `report:` the rate against the budget, the shape
+      #   `CostCheck.Pass` takes
+      # @raise [RuntimeError] when no complete day has passed since `since`, `aws` fails, or the
+      #   rate is over the budget
+      def measure(**held)
+        budget = Integer(plain(held[:budget]))
+        first = Date.iso8601(plain(held[:since]).to_s)
+        last = today
+        raise "no complete day since #{first}; today (#{last}) is still being billed" if first >= last
+
+        days = daily_costs(first, last)
+        line = report_line(first, last, days, budget)
+        raise "over budget: #{line}" if monthly_rate(days) > budget
+
+        { report: { value: line } }
+      end
+
+      private
+
+      # @return [Date] the day the span ends before: today, in UTC
+      def today = @today ? Date.iso8601(@today.to_s) : Time.now.utc.to_date
+
+      # @return [Hash{String => Hash{String => Float}}] day => service => dollars
+      def daily_costs(first, last)
+        out, err, status = Open3.capture3(
+          "aws", "ce", "get-cost-and-usage", "--time-period", "Start=#{first},End=#{last}",
+          "--granularity", "DAILY", "--metrics", "UnblendedCost",
+          "--group-by", "Type=DIMENSION,Key=SERVICE", "--output", "json"
+        )
+        raise "aws ce get-cost-and-usage failed: #{err.strip.empty? ? out.strip : err.strip}" unless status.success?
+
+        rows = JSON.parse(out).fetch("ResultsByTime")
+        raise "Cost Explorer returned no days for #{first}..#{last}" if rows.empty?
+
+        rows.to_h { |row| [row.dig("TimePeriod", "Start"), by_service(row)] }
+      end
+
+      def by_service(row)
+        row.fetch("Groups").to_h do |group|
+          [group.fetch("Keys").first, group.dig("Metrics", "UnblendedCost", "Amount").to_f]
+        end
+      end
+
+      # @return [Float] the mean daily total, scaled to an average month
+      def monthly_rate(days)
+        mean = days.values.sum { |services| services.values.sum } / days.size
+        mean * DAYS_IN_MONTH
+      end
+
+      def report_line(first, last, days, budget)
+        mean = days.values.sum { |services| services.values.sum } / days.size
+        biggest = totals_by_service(days).max_by(TOP_SERVICES) { |_name, dollars| dollars }
+        named = biggest.map { |name, dollars| "#{name} $#{format('%.2f', dollars / days.size)}/day" }.join(", ")
+        "#{first}..#{last - 1} (#{days.size} days): $#{format('%.2f', mean)}/day, " \
+          "$#{format('%.2f', monthly_rate(days))}/month against $#{budget}; biggest: #{named}"
+      end
+
+      def totals_by_service(days)
+        days.values.each_with_object(Hash.new(0.0)) do |services, totals|
+          services.each { |name, dollars| totals[name] += dollars }
+        end
+      end
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

data/lib/hecks/hecks/adapters/rust_workspace.rb

@@ -22,7 +22,7 @@ module Hecks
       CHECKOUT_MARKER = "hecks.gemspec"
 
       # What a copy holds: the workspace manifest, the kernel and every crate a domain build uses.
-      PACKAGED = %w[Cargo.toml Cargo.lock project.rb project_rust_pipeline.rb project src codegen parser
+      PACKAGED = %w[Cargo.toml Cargo.lock src codegen parser
                     host build web lsp].freeze
 
       # Left out of a copy: build output anywhere, the corpus tests, and the corpus domains.

data/lib/hecks/hecks/adapters/site_toolchain.rb

@@ -9,13 +9,16 @@ module Hecks
     # The `SiteToolchain` port's adapter: projects a site's route table into its `routes.ts`, or
     # checks the file on disk is current.
     #
-    # The projection runs the `project_site` tool in a child of the checkout, with its printing and
-    # exit status captured: a tool that ends non-zero is a refusal whose reason is what it printed.
-    # Outside a hecks checkout the ask is refused with "needs a hecks checkout".
+    # The projection runs the `project_site` tool in this process, with its printing and exit status
+    # captured: a tool that ends non-zero is a refusal whose reason is what it printed. The tool
+    # ships in the gem and reads only the project it is given, so it needs no hecks checkout.
     class SiteToolchain
       # The `Hecks::Tools` tool the ask runs, by ask.
       SCRIPTS = { project: "project_site" }.freeze
 
+      # The tool's flag for each `SiteProjection` field that takes a value.
+      FLAGS = { "out" => :out, "template" => :template, "extension" => :extension }.freeze
+
       # Accepts the arguments every driven adapter is built with and keeps none of them.
       #
       # @param aggregate [Object, nil] unused
@@ -25,17 +28,17 @@ module Hecks
 
       # Writes a project's `routes.ts` from its declared route table, or with `check` only compares.
       #
-      # @param held [Hash] the `SiteProjection` record: `domain`, and `out` and `check` when set
+      # @param held [Hash] the `SiteProjection` record: `domain`, and `out`, `template`, `extension`
+      #   and `check` when set
       # @return [Hash{Symbol => Hash}] `output:` one line per file written or found current
-      # @raise [ConsoleCapture::Failure] when the tree is not a checkout, the route table is
-      #   refused (an unknown cache class, a duplicate path), or under `check` a file is out of date
+      # @raise [ConsoleCapture::Failure] when the route table is refused (an unknown cache class,
+      #   a duplicate path), a path or the extension is refused, or under `check` a file is out
+      #   of date
       def project(**held)
-        flags = []
-        flags << "--out=#{plain(held[:out])}" unless plain(held[:out]).nil?
+        flags = FLAGS.filter_map { |flag, key| "--#{flag}=#{located(key, held[key])}" unless plain(held[key]).nil? }
         flags << "--check" if plain(held[:check]) == true
-        tree = Codebase::Tree.new
-        tree.require_checkout!
-        result = Codebase::RubyChild.new(tree).capture(SCRIPTS.fetch(:project), *flags, plain(held[:domain]))
+        result = Codebase::RubyChild.new(Codebase::Tree.new).capture(SCRIPTS.fetch(:project), *flags,
+                                                                     located(:domain, held[:domain]))
         raise ConsoleCapture::Failure, message_of(result) unless result.ok?
 
         { output: { value: result.out } }
@@ -48,6 +51,13 @@ module Hecks
         text.empty? ? "the tool ended with status #{result.status.exitstatus}" : text
       end
 
+      # The tool runs from the tool's own root, so a path the caller gave relative to where they
+      # stand is made absolute first; the extension is not a path.
+      def located(key, argument)
+        value = plain(argument)
+        value.nil? || key == :extension ? value : File.expand_path(value)
+      end
+
       def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
     end
   end