hecks 3.1.3 → 3.2.1

data/lib/hecks/projections/site/table/checks.rb

@@ -1,19 +1,23 @@
 # frozen_string_literal: true
 
+require_relative "../edge/pattern"
+
 module Hecks
   module Projections
     module Site
       class Table
         # What no single row can show, and what a row contradicts in itself once its defaults are
-        # filled: a path declared twice, a switch the rows disagree on, an off route that sits in a
-        # navigation, an indexable route that is not public.
+        # filled: a path declared twice, a switch the rows disagree on, a navigation entry that
+        # cannot be linked to, an indexable route that is not public, a public route beneath a
+        # prefix that is not.
         class Checks
           SWITCH_ID = /\A[a-z][a-z0-9_]*\z/
+          FRAGMENT = /\A[A-Za-z0-9][\w:.-]*\z/
           PUBLIC_MENUS = %w[desktop mobile footer].freeze
 
           # The navigation slots a row sits in.
           #
-          # @param row [Row] a row
+          # @param row [Row, Link] a row or link
           # @return [Array<String>] some of `desktop`, `mobile`, `footer`, `admin`
           def self.navigation(row)
             { "desktop" => row.nav_order, "mobile" => row.mobile_order, "footer" => row.footer_column,
@@ -22,8 +26,10 @@ module Hecks
 
           # @param rows [Array<Row>] the table's rows, defaults filled in
           # @param problems [Array<String>] collects each problem found, one line each
-          def initialize(rows, problems)
+          # @param links [Array<Link>] the table's extra navigation entries
+          def initialize(rows, problems, links: [])
             @rows = rows
+            @links = links
             @problems = problems
           end
 
@@ -32,7 +38,8 @@ module Hecks
             check_duplicate_paths
             check_switches
             @rows.each { |row| check_row(row) }
-            check_unique(@rows.filter_map(&:admin_key), "admin key")
+            @links.each { |link| check_link(link) }
+            check_unique((@rows + @links).filter_map(&:admin_key), "admin key")
             check_unique(@rows.map(&:source).grep(/\Aglobal:/), "source")
           end
 
@@ -63,6 +70,7 @@ module Hecks
             check_redirect(row, path)
             check_navigation(row, path)
             check_indexing(row, path)
+            check_beneath_prefix(row, path)
             return unless row.preview == "draft" && row.source == "none"
 
             problem(path, "previews as a draft but has source none; a draft preview needs a global: or collection: source")
@@ -90,13 +98,51 @@ module Hecks
             slots = self.class.navigation(row)
             return if slots.empty?
 
-            problem(path, "is off and sits in the #{slots.join(' and ')} navigation") if row.off
-            problem(path, "sits in the navigation but is a #{row.kind}; only a page does") unless row.kind == "page"
+            unless row.verbs.include?("GET")
+              problem(path, "sits in the navigation but answers #{row.verbs.join(',')}; a link is a GET")
+            end
             problem(path, "sits in the navigation and has a parameter") if path.match?(/[:*]/)
             problem(path, "sits in the navigation and has no label") if row.label.to_s.empty?
+            check_heading(row, path)
             check_menu_audience(row, path, slots)
           end
 
+          def check_heading(item, path)
+            return unless item.mobile_heading
+            return problem(path, "has a mobile_heading but no mobile_order") if item.mobile_order.nil?
+
+            problem(path, "has an empty mobile_heading") if item.mobile_heading.strip.empty?
+          end
+
+          def check_link(link)
+            path = "NavLink #{link.path}"
+            slots = self.class.navigation(link)
+            problem(path, "sits in no navigation; give it nav_order, mobile_order, footer_column or admin_key") if slots.empty?
+            problem(path, "has a parameter; a link is to one page") if link.path.to_s.match?(/[:*]/)
+            problem(path, "has no label") if link.label.to_s.empty?
+            if link.fragment && !link.fragment.match?(FRAGMENT)
+              problem(path, "has fragment #{link.fragment.inspect}; a fragment is an element id, written without #")
+            end
+            check_heading(link, path)
+            check_menu_audience(link, path, slots)
+          end
+
+          # A public route under a prefix that is not public (the sign-in page beside the admin
+          # pages) inherits nothing from the prefix, so the row has to say what it is: its cache
+          # class is declared, not derived from its auth.
+          def check_beneath_prefix(row, path)
+            return if row.auth != "public" || row.explicit_cache || row.path.nil?
+
+            pattern = Edge::Pattern.edge(row.path)
+            prefix = @rows.find do |other|
+              other.auth != "public" && other.path && Edge::Pattern.strictly_covers?(Edge::Pattern.edge(other.path), pattern)
+            end
+            return unless prefix
+
+            problem(path, "is public but sits beneath #{prefix.path}, which is #{prefix.auth}; " \
+                          "name its cache class (cache: \"no_store\" for a sign-in page) to say that is meant")
+          end
+
           def check_menu_audience(row, path, slots)
             public_slots = slots & PUBLIC_MENUS
             if row.auth != "public" && public_slots.any?

data/lib/hecks/projections/site/table/link_builder.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      class Table
+        # One extra navigation entry that points at a route the table declares, optionally at a
+        # fragment of its page. `off` and `switch` are copied from the route it points at.
+        Link = Struct.new(:path, :fragment, :label, :nav_group, :nav_order, :mobile_order, :mobile_heading,
+                          :footer_column, :footer_order, :admin_key, :admin_order, :off, :switch, :auth,
+                          keyword_init: true)
+
+        # Turns a declared `NavLink` member into a `Link`: checks its fields and their types, and
+        # copies the facts it shares with the route it points at.
+        class LinkBuilder
+          # The fields a link may carry, with the Ruby class each takes.
+          FIELDS = { path: String, fragment: String, label: String, nav_group: String, nav_order: Integer,
+                     mobile_order: Integer, mobile_heading: String, footer_column: String,
+                     footer_order: Integer, admin_key: String, admin_order: Integer }.freeze
+
+          # @param rows [Array<Row>] the table's rows, which a link points at
+          # @param problems [Array<String>] collects each problem found, one line each
+          def initialize(rows, problems)
+            @rows = rows
+            @problems = problems
+          end
+
+          # @param member [Hash{Symbol => Object}] the declared fields of one link
+          # @param index [Integer] the link's position, for a message about a link with no path
+          # @return [Link] the link; its problems are in `problems`
+          def call(member, index)
+            label = "NavLink #{member[:path] || "row #{index + 1}"}"
+            fields = checked_fields(member, label)
+            target = @rows.find { |row| row.path == fields[:path] && row.verbs.include?("GET") }
+            problem(label, "points at no route that answers GET; declare the route first") unless target
+            link = Link.new(**fields, off: target ? target.off : false, switch: target ? target.switch : "",
+                                      auth: target ? target.auth : "public")
+            link.footer_order ||= 0 if link.footer_column
+            link.admin_order ||= 0 if link.admin_key
+            link
+          end
+
+          private
+
+          def checked_fields(member, label)
+            member.each_key do |key|
+              problem(label, "has no field #{key}; fields are #{FIELDS.keys.join(', ')}") unless FIELDS.key?(key)
+            end
+            known = member.slice(*FIELDS.keys)
+            known.each do |key, value|
+              next if value.is_a?(FIELDS.fetch(key))
+
+              problem(label, "has #{key} #{value.inspect}; #{key} is a #{FIELDS.fetch(key)}")
+            end
+            problem(label, "needs a path") unless known[:path]
+            known
+          end
+
+          def problem(label, text) = @problems << "#{label} #{text}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/table/row_builder.rb

@@ -8,7 +8,8 @@ module Hecks
         Row = Struct.new(:path, :kind, :render, :auth, :verbs, :cache, :origin, :source,
                          :indexable, :switch, :off, :preview, :label, :seo, :redirect_to, :aliases,
                          :nav_group, :nav_order, :mobile_order, :footer_column, :footer_order,
-                         :admin_key, :admin_order, :compress, :alb_rule, :cdn, keyword_init: true)
+                         :admin_key, :admin_order, :compress, :alb_rule, :cdn,
+                         :seo_title, :edge_verbs, :mobile_heading, :explicit_cache, keyword_init: true)
 
         # Turns a declared member into a `Row`: checks its fields and their types, fills the
         # defaults, and checks each closed-set value against the Site chapter's vocabulary.
@@ -19,7 +20,8 @@ module Hecks
                      off: :bool, preview: String, label: String, seo: String, redirect_to: String,
                      aliases: String, nav_group: String, nav_order: Integer, mobile_order: Integer,
                      footer_column: String, footer_order: Integer, admin_key: String,
-                     admin_order: Integer, compress: :bool, alb_rule: String, cdn: :bool }.freeze
+                     admin_order: Integer, compress: :bool, alb_rule: String, cdn: :bool,
+                     seo_title: String, edge_methods: String, mobile_heading: String }.freeze
 
           # The value objects of the Site chapter's `Route` aggregate whose members are the closed
           # sets, by the row field each constrains.
@@ -50,7 +52,9 @@ module Hecks
             label = path || label
             check_source(label, source)
             verbs = fields.delete(:methods)
-            row = Row.new(**fields, verbs: verbs, path: path, source: source,
+            edge_verbs = fields.delete(:edge_methods)
+            row = Row.new(**fields, verbs: verbs, edge_verbs: edge_verbs, path: path, source: source,
+                                    explicit_cache: !fields[:cache].nil?,
                                     kind: fields[:kind] || default_kind(source), auth: fields[:auth] || "public",
                                     origin: fields[:origin] || default_origin(source))
             fill_defaults(row)
@@ -94,6 +98,7 @@ module Hecks
             row.cdn = true if row.cdn.nil?
             row.render ||= row.kind == "page" ? "prerender" : "ssr"
             row.verbs = list(row.verbs || (row.source.start_with?("command:") ? "POST" : "GET"))
+            row.edge_verbs = row.edge_verbs.nil? ? row.verbs : list(row.edge_verbs)
             row.aliases = list(row.aliases)
             row.cache ||= default_cache(row)
             row.indexable = indexable_by_default?(row) if row.indexable.nil?
@@ -123,11 +128,21 @@ module Hecks
 
               problem(label, "has #{field} #{row[field].inspect}; #{field} is one of #{@vocabulary.fetch(field).join(', ')}")
             end
-            row.verbs.each do |verb|
-              next if @vocabulary.fetch(:http_method).include?(verb)
+            check_verbs(row, label)
+          end
+
+          def check_verbs(row, label)
+            { "method" => row.verbs, "edge method" => row.edge_verbs }.each do |what, verbs|
+              verbs.each do |verb|
+                next if @vocabulary.fetch(:http_method).include?(verb)
 
-              problem(label, "has method #{verb.inspect}; methods are #{@vocabulary.fetch(:http_method).join(', ')}")
+                problem(label, "has #{what} #{verb.inspect}; methods are #{@vocabulary.fetch(:http_method).join(', ')}")
+              end
             end
+            return if (row.verbs - row.edge_verbs).empty?
+
+            problem(label, "has edge_methods #{row.edge_verbs.join(',')}, which leave out its methods " \
+                           "#{(row.verbs - row.edge_verbs).join(',')}; the edge must allow every verb the route answers")
           end
 
           def check_source(label, source)

data/lib/hecks/projections/site/table.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "table/row_builder"
+require_relative "table/link_builder"
 require_relative "table/checks"
 
 module Hecks
@@ -21,9 +22,15 @@ module Hecks
         # The name of the value object a client declares its rows in.
         ROW_OBJECT = "Route"
 
+        # The name of the value object a client declares its extra navigation entries in.
+        LINK_OBJECT = "NavLink"
+
         # @return [Array<Row>] the rows, in the order the client declared them
         attr_reader :rows
 
+        # @return [Array<Link>] the extra navigation entries, in the order the client declared them
+        attr_reader :links
+
         # Finds the one chapter of a project that declares the route table.
         #
         # @param registry [Runtime::Registry] the registry the project booted into
@@ -47,7 +54,8 @@ module Hecks
         # @return [Table] the checked table
         # @raise [Invalid] when the Site chapter is not attached or a row is refused
         def self.read(chapter, registry:)
-          new(rows_of(chapter), vocabulary: vocabulary(registry), registry: registry)
+          new(rows_of(chapter), vocabulary: vocabulary(registry), registry: registry,
+                                links: rows_of(chapter, LINK_OBJECT))
         end
 
         # @param registry [Runtime::Registry] a registry holding the Site chapter
@@ -76,20 +84,23 @@ module Hecks
         # @param vocabulary [Hash{Symbol => Array<String>}] the closed sets
         # @param registry [Runtime::Registry, nil] where a `command:` or `query:` source is looked
         #   up; nil skips that check
+        # @param links [Array<Hash{Symbol => Object}>] the declared `NavLink` rows
         # @raise [Invalid] when a row is refused
-        def initialize(members, vocabulary:, registry: nil)
+        def initialize(members, vocabulary:, registry: nil, links: [])
           problems = []
           builder = RowBuilder.new(vocabulary: vocabulary, registry: registry, problems: problems)
           @rows = members.each_with_index.map { |member, index| builder.call(member, index) }
-          Checks.new(@rows, problems).call
+          link_builder = LinkBuilder.new(@rows, problems)
+          @links = links.each_with_index.map { |member, index| link_builder.call(member, index) }
+          Checks.new(@rows, problems, links: @links).call
           return if problems.empty?
 
           raise Invalid, "the route table is refused:\n#{problems.map { |line| "  - #{line}" }.join("\n")}"
         end
 
-        # The navigation slots a row sits in.
+        # The navigation slots a row or link sits in.
         #
-        # @param row [Row] a row
+        # @param row [Row, Link] a row or link
         # @return [Array<String>] some of `desktop`, `mobile`, `footer`, `admin`
         def navigation(row) = Checks.navigation(row)
       end

data/lib/hecks/rust_build/kernel_input.rb

@@ -30,7 +30,8 @@ module Hecks
       # @return [String] the input as JSON, ready for the binary's stdin
       def json(domain_path, steps) = JSON.generate(build(domain_path, steps))
 
-      # Each command's declared defaults, read from the domain's generated IR.
+      # Each command's declared defaults, entity commands included, read from the domain's
+      # generated IR. An entity's commands sit under `Domain::Aggregate.Entity[.Entity].Command`.
       #
       # @param domain_path [String] the domain's directory
       # @return [Hash{String => Hash{String => Object}}] empty when the IR is absent or has none
@@ -38,14 +39,25 @@ module Hecks
         ir = generated_ir(domain_path) or return {}
         domain = ir["name"].to_s
         Array(ir["aggregates"]).each_with_object({}) do |aggregate, table|
-          Array(aggregate["commands"]).each do |command|
-            held = Array(command["attributes"]).reject { |attribute| attribute["default"].nil? }
-                                               .to_h { |attribute| [attribute["name"], attribute["default"]] }
-            table["#{domain}::#{aggregate['name']}.#{command['name']}"] = held unless held.empty?
-          end
+          collect_defaults(aggregate, "#{domain}::#{aggregate['name']}", table)
         end
       end
 
+      # Adds the defaults of `node`'s commands, then of each entity nested in it, under `prefix`.
+      #
+      # @param node [Hash] an aggregate or entity of the IR
+      # @param prefix [String] the verb path down to `node`
+      # @param table [Hash] filled in place
+      # @return [void]
+      def collect_defaults(node, prefix, table)
+        Array(node["commands"]).each do |command|
+          held = Array(command["attributes"]).reject { |attribute| attribute["default"].nil? }
+                                             .to_h { |attribute| [attribute["name"], attribute["default"]] }
+          table["#{prefix}.#{command['name']}"] = held unless held.empty?
+        end
+        Array(node["entities"]).each { |entity| collect_defaults(entity, "#{prefix}.#{entity['name']}", table) }
+      end
+
       # @param domain_path [String] the domain's directory
       # @return [Hash, nil] the parsed generated IR, or nil when the domain has none
       def generated_ir(domain_path)

data/lib/hecks/rust_build/project_rust.rb

@@ -17,9 +17,8 @@ module Hecks
     #   ProjectRust.call(["path/to/domain"])
     #
     # `hecks-codegen` is the generator (ADR 0086): this class builds the IR from the live registry
-    # and `CodegenRun` runs the binary on it. `HECKS_CODEGEN=ruby` selects the Ruby generator in
-    # `rust/project` until that is deleted; `HECKS_PARSER=rust` with `HECKS_CODEGEN=rust` runs
-    # `rust/project_rust_pipeline.rb` instead, with no Ruby load of the domain.
+    # and `CodegenRun` runs the binary on it. The Ruby-free path is `hecks-build`, which feeds the
+    # same binary from `hecks-parse`.
     #
     # The era plugin is required unconditionally so the generator works for any domain, lineage
     # capable or not; `pg` stays lazy inside it, so nothing here opens a database connection.
@@ -46,13 +45,7 @@ module Hecks
       # @return [Integer] the exit status
       def call
         validate_name!
-        if ENV["HECKS_PARSER"] == "rust" && ENV["HECKS_CODEGEN"] == "rust"
-          require_relative "../../../rust/project"
-          require_relative "../../../rust/project_rust_pipeline"
-          RustProjectPipeline.call(@domain)
-        else
-          generate
-        end
+        generate
         0
       end
 
@@ -78,18 +71,11 @@ module Hecks
         FileUtils.mkdir_p(@out_root)
         build_target_ir
         FileUtils.rm_rf(File.join(@out_root, "active"))
-        ENV["HECKS_CODEGEN"] == "ruby" ? generate_with_ruby : generate_with_codegen
+        generate_with_codegen
         write_root_mod
         sync_cargo_features
       end
 
-      # The rollback path (ADR 0086): the Ruby generator in `rust/project`, until it is deleted.
-      def generate_with_ruby
-        require_relative "../../../rust/project"
-        write_meta
-        write_target
-      end
-
       # `hecks-codegen` is the generator; this process only builds the IR it reads from the live
       # registry, so a domain's persistence, seams, translations and source text reach `ir.json`.
       def generate_with_codegen
@@ -105,8 +91,8 @@ module Hecks
         ).call
       end
 
-      # The IR as `rust/project` hands it to its generators: string-keyed through JSON, with the
-      # append-optional fields marked, since `ir.json` records them.
+      # The IR as the generator reads it: string-keyed through JSON, with the append-optional
+      # fields marked, since `ir.json` records them.
       def prepared_ir(tree, shaped: true)
         AppendOptionals.mark(shaped ? json_shaped(tree) : tree)
       end
@@ -186,78 +172,6 @@ module Hecks
         )
       end
 
-      # The self-hosted language goes through the same codegen as the target, read from the
-      # grammar registry `MetaValidator` boots with.
-      def write_meta
-        meta_ir = json_shaped(
-          Hecks::Projector::Exporter.call(Hecks::Bluebook::MetaValidator.grammar_registry).fetch("Bluebook")
-        )
-        dir = File.join(@out_root, "meta")
-        # Tracked per directory: several domains coexist on disk, and `pop_and_prune` deletes only
-        # the files this run never touched. `active` is a set of feature re-exports in the root
-        # `mod.rs`, never a directory.
-        WriteIfChanged.push_directory(dir)
-        result = RustProjection::DomainGenerator.call(
-          meta_ir, "the self-hosted language (lib/hecks/language/bluebook)", dir, "meta"
-        )
-        write_merged(File.join(dir, "merged.rs"), result[:aggregates], result[:queries], result[:read_models],
-                     policies: RustProjection::Projector.emit_policy_table(meta_ir[:name], meta_ir[:policies],
-                                                                           meta_ir[:aggregates]),
-                     cross:    RustProjection::Projector.emit_cross_domain_policy_table(meta_ir[:name],
-                                                                                        meta_ir[:policies]),
-                     managers: meta_ir[:process_managers],
-                     keys:     [[meta_ir[:name], result[:aggregates].map { |a| a[:name] }]])
-        append_merged_mod(File.join(dir, "mod.rs"))
-        WriteIfChanged.pop_and_prune(dir)
-      end
-
-      def write_target
-        dir = File.join(@out_root, @mod_name)
-        WriteIfChanged.push_directory(dir)
-        result = RustProjection::DomainGenerator.call(@ir, @domain, dir, @mod_name)
-        chapters = write_chapters
-        aggregates = result[:aggregates] + chapters[:aggregates]
-        write_merged(File.join(dir, "merged.rs"), aggregates, result[:queries] + chapters[:queries],
-                     result[:read_models] + chapters[:read_models],
-                     policies: RustProjection::Projector.emit_merged_policy_table(chapters[:policy_sources]),
-                     cross:    RustProjection::Projector.emit_merged_cross_domain_policy_table(chapters[:policy_sources]),
-                     managers: @ir[:process_managers] + chapters[:process_managers],
-                     keys:     reference_keys(result[:aggregates], chapters))
-        append_merged_mod(File.join(dir, "mod.rs"))
-        WriteIfChanged.pop_and_prune(dir)
-      end
-
-      # Every other bluebook the target's `attaches` calls pulled into the registry, each
-      # generated into its own module. A framework chapter is a function of its bluebook alone, so
-      # regenerating one is safe whichever domain last touched it.
-      def write_chapters
-        totals = { aggregates: [], queries: [], read_models: [], process_managers: [],
-                   policy_sources: [{ domain_name: @domain_name, policies: @ir[:policies],
-                                      aggregates: @ir[:aggregates] }],
-                   mod_names: { @mod_name => @domain_name } }
-        vendored = @registry.hecksagons.values.flat_map(&:vendored_packages)
-        (@registry.bluebooks.keys - [@domain_name]).each { |chapter| write_chapter(chapter, vendored, totals) }
-        totals
-      end
-
-      def write_chapter(chapter_name, vendored, totals)
-        mod_name = chapter_name.downcase
-        totals[:mod_names][mod_name] = chapter_name
-        chapter_ir = json_shaped(Hecks::Projector::Exporter.call(@registry).fetch(chapter_name))
-        result = nil
-        WriteIfChanged.track_directory(File.join(@out_root, mod_name)) do
-          result = RustProjection::DomainGenerator.call(chapter_ir, "#{@domain} (#{attachment(chapter_name, vendored)})",
-                                                        File.join(@out_root, mod_name), mod_name,
-                                                        merged_module: false)
-        end
-        totals[:aggregates].concat(result[:aggregates])
-        totals[:queries].concat(result[:queries])
-        totals[:read_models].concat(result[:read_models])
-        totals[:process_managers].concat(chapter_ir[:process_managers])
-        totals[:policy_sources] << { domain_name: chapter_name, policies: chapter_ir[:policies],
-                                     aggregates: chapter_ir[:aggregates] }
-      end
-
       # How the target attached a chapter, across every hecksagon the registry loaded: a chapter a
       # sibling hecksagon vendors in is labelled as vendored.
       def attachment(chapter_name, vendored)
@@ -265,46 +179,6 @@ module Hecks
         name ? "attaches #{name.inspect}, from: :vendor" : "attaches #{chapter_name.inspect}"
       end
 
-      def reference_keys(target_aggregates, chapters)
-        chapters[:mod_names].map do |mod_name, chapter_name|
-          own = mod_name == @mod_name ? target_aggregates : chapters[:aggregates].select { |a| a[:chapter_mod] == mod_name }
-          [chapter_name, own.map { |a| a[:name] }]
-        end
-      end
-
-      # Writes a module's `merged.rs`: the registry and every dispatch table over its aggregates.
-      def write_merged(path, aggregates, queries, read_models, policies:, cross:, managers:, keys:)
-        projector = RustProjection::Projector
-        wrote = WriteIfChanged.block(path) do |file|
-          [projector.emit_registry(aggregates), projector.emit_reference_lookup(aggregates), policies, cross,
-           projector.emit_process_manager_table(managers), projector.emit_reference_key_table(keys),
-           projector.emit_creates_table(aggregates), projector.emit_identity_head_table(aggregates),
-           projector.emit_entity_identity_head_table(aggregates),
-           projector.emit_command_attributes_table(aggregates), projector.emit_query_table(queries),
-           projector.emit_query_arg_check_table(queries)].each do |table|
-            file.puts table
-            file.puts
-          end
-          # A read model's `group_by` function is written before the table names it.
-          read_models.each do |model|
-            next unless model[:group_by_fn_body]
-
-            file.puts model[:group_by_fn_body]
-            file.puts
-          end
-          file.puts projector.emit_read_model_table(read_models)
-        end
-        puts(wrote ? "wrote #{path}" : "#{path} unchanged")
-      end
-
-      # Appends the `pub mod merged;` line once; appending it again would grow the file and bump
-      # its mtime on every run.
-      def append_merged_mod(path)
-        return if File.exist?(path) && File.read(path).include?("pub mod merged;")
-
-        File.open(path, "a") { |file| file.puts "pub mod merged;" }
-      end
-
       # `src/generated/mod.rs`: every domain ever generated, scanned off disk. A directory is a
       # selectable domain exactly when it carries its own `merged.rs`; a framework chapter has
       # none and is always compiled in.

data/lib/hecks/site/bluebook/site.bluebook

@@ -95,12 +95,14 @@ Hecks.bluebook "Site" do
   aggregate "SiteProjection" do
     description "One projection of a site's route table into its routes.ts, or the check that the file on disk is current."
 
-    attribute :domain,  DomainPath
-    attribute :run,     RunKey
-    attribute :out,     Location, optional: true
-    attribute :check,   Switch,   optional: true
-    attribute :output,  Report,   optional: true
-    attribute :refusal, Report,   optional: true
+    attribute :domain,    DomainPath
+    attribute :run,       RunKey
+    attribute :out,       Location,  optional: true
+    attribute :template,  Location,  optional: true
+    attribute :extension, Extension, optional: true
+    attribute :check,     Switch,    optional: true
+    attribute :output,    Report,    optional: true
+    attribute :refusal,   Report,    optional: true
     identified_by :run
 
     value_object "RunKey" do
@@ -116,11 +118,18 @@ Hecks.bluebook "Site" do
       invariant("a project is named by its path") { !value.to_s.empty? }
     end
 
-    # Where routes.ts is written, when not beside the project's bluebook.
+    # A directory or file anywhere on disk, relative to where the command runs: where routes.ts is
+    # written when not in the project's generated/ directory, or the template to rewrite in place.
     value_object "Location" do
       attribute :value, String, pattern: '[^\t\n\r]'
     end
 
+    # The file extension of the generated module: `ts` (routes.ts), or `mts` (routes.mts), which
+    # Node loads as an ES module even in a package whose "type" is "commonjs".
+    value_object "Extension" do
+      attribute :value, String, one_of: ["ts", "mts"]
+    end
+
     value_object "Switch" do
       attribute :value, Boolean
     end
@@ -134,19 +143,24 @@ Hecks.bluebook "Site" do
       transition "Fault"    => "faulted",   from: "requested"
     end
 
-    # `hecks site site_projection.project_site <project> [out=<dir>] [--check]`. With `check` nothing is written: a
-    # routes.ts that differs from the table is faulted, naming the file, so a CI job fails on drift.
+    # `hecks site site_projection.project_site <project> [out=<dir>] [template=<file>] [extension=ts|mts] [--check]`.
+    # With `check` nothing is written: a routes.ts that differs from the table is faulted, naming the
+    # file, so a CI job fails on drift.
     command "ProjectSite" do
       goal "Project a site's route table into routes.ts, or with check only compare it with the file on disk"
 
-      attribute :domain, DomainPath
-      attribute :run,    RunKey
-      attribute :out,    Location, optional: true
-      attribute :check,  Switch,   optional: true
+      attribute :domain,    DomainPath
+      attribute :run,       RunKey
+      attribute :out,       Location,  optional: true
+      attribute :template,  Location,  optional: true
+      attribute :extension, Extension, optional: true
+      attribute :check,     Switch,    optional: true
 
       sets :domain
       sets :run
       sets :out
+      sets :template
+      sets :extension
       sets :check
 
       emits "SiteProjectionRequested"

data/lib/hecks/storehouse.rb

@@ -230,10 +230,44 @@ module Hecks
       result = runtime.dispatch_flat(spec[:command], envelope)
       ok(summary: summary,
          id:      result.id,
-         state:   result.state.nil? ? nil : Doors::JsonDoor.materialize(result.state),
+         state:   settled_state(runtime, spec, result),
          events:  result.events.map { |event| { name: event.name, payload: Doors::JsonDoor.materialize(event.payload) } })
     end
 
+    # The record as its repository holds it once every reaction has run, which is the state the
+    # dispatch resulted in; the handle's own state is the record as the command left it, so a run
+    # record that a reaction completes would otherwise read as `requested`. Falls back to the
+    # handle's state for a command that belongs to no top-level aggregate or whose record cannot be
+    # read.
+    # :nodoc:
+    def settled_state(runtime, spec, result)
+      return if result.state.nil?
+
+      bluebook = bluebook_for(runtime)
+      head = spec[:command].split("::", 2).last
+      aggregate = bluebook.aggregates.find { |candidate| candidate.hecks_name == head.split(".").first } if
+        head.count(".") == 1
+      record = aggregate && runtime.registry.repository(bluebook.name, aggregate)&.find(result.id)&.to_h
+      Doors::JsonDoor.materialize(record || result.state)
+    end
+
+    # What a caller needs to call each of the named commands: its qualified name, the role it
+    # declares, what it does, and its argument names, a trailing `*` marking a required one.
+    #
+    # @param runtime [Runtime::Dispatcher] the booted domain
+    # @param names [Array<String>] short or qualified command names
+    # @return [Array<String>] one line per name that resolves, in order
+    def command_guide(runtime, names)
+      cli = Projector.call(:cli, bluebook: bluebook_for(runtime), options: { program: "mcp" })
+      names.filter_map do |name|
+        spec = resolve!(cli, name.to_s, asking: false)
+        arguments = spec[:arguments].map { |arg| arg[:path].split(".").first + (arg[:required] ? "*" : "") }
+        "#{name} (role #{spec[:role] || 'none'}): #{spec[:summary]}. Arguments: #{arguments.uniq.join(', ')}"
+      rescue Runtime::NotFound
+        nil
+      end
+    end
+
     # :nodoc:
     def dry_run_outcome(runtime, spec, envelope, summary:)
       flat = flatten_legacy(envelope, spec[:receiver], spec[:legacy_receiver])

data/lib/hecks/tools/comment_style.rb

@@ -946,10 +946,12 @@ module Hecks
           $CHILD_STATUS.success? ? out : nil
         end
 
-        # `.rb` files, plus extensionless scripts with a Ruby shebang.
+        # `.rb` files, plus extensionless scripts with a Ruby shebang. The first line is read as
+        # bytes, so an extensionless binary (a compiled test fixture's output) is passed over
+        # rather than refused for not being UTF-8.
         def ruby_files(dir)
           scripts = Dir[File.join(dir, "**", "*")].select do |path|
-            File.file?(path) && File.extname(path).empty? && File.open(path, &:gets).to_s.match?(/\A#!.*ruby/)
+            File.file?(path) && File.extname(path).empty? && File.open(path, "rb", &:gets).to_s.match?(/\A#!.*ruby/n)
           end
           Dir[File.join(dir, "**", "*.rb")] + scripts
         end