hecks 3.2.0 → 3.3.0

data/lib/hecks/projections/deploy/box.rb

@@ -1,6 +1,7 @@
 require "json"
 require_relative "../../projector"
 require_relative "box/settings"
+require_relative "box/hosting"
 
 module Hecks
   module Projections
@@ -94,7 +95,7 @@ module Hecks
             "fetch-secrets.sh" => File.read(File.join(TEMPLATE_DIR, "fetch-secrets.sh")),
             "deploy-box.sh" => deploy_box_sh(plan, region),
             "Makefile" => makefile(plan)
-          }.merge(migration_files(plan))
+          }.merge(migration_files(plan)).then { |files| Hosting.extend_files(files, plan: plan, region: region) }
         end
 
         # The tooling that moves a project's data from its old database into the RDS instance, for
@@ -379,9 +380,19 @@ module Hecks
         def route_blocks(plan)
           routes = plan.routes.each_with_index.map do |route, i|
             port = plan.containers.find { |c| c.name == route.container }.port
-            "@r#{i + 1} path #{route.paths.join(' ')}\nhandle @r#{i + 1} {\n\treverse_proxy 127.0.0.1:#{port}\n}\n\n"
+            "@r#{i + 1} path #{route.paths.join(' ')}\nhandle @r#{i + 1} {\n#{upstream(port)}}\n\n"
           end
-          "#{routes.join}handle {\n\treverse_proxy 127.0.0.1:#{plan.default.port}\n}\n"
+          "#{routes.join}handle {\n#{upstream(plan.default.port)}}\n"
+        end
+
+        # One upstream. A request that arrives while its container is being replaced
+        # waits, and is tried again every quarter second for up to 15 seconds, so a
+        # deploy shows a visitor a slow page instead of a 502.
+        #
+        # @param port [Integer] the container's port
+        # @return [String] the `reverse_proxy` block, one tab in, ending in a newline
+        def upstream(port)
+          "\treverse_proxy 127.0.0.1:#{port} {\n\t\tlb_try_duration 15s\n\t\tlb_try_interval 250ms\n\t}\n"
         end
 
         # @param plan [Settings::Plan] the resolved settings
@@ -425,6 +436,7 @@ module Hecks
         def services_json(plan)
           services = plan.containers.to_h { |c| [c.name, service_entry(plan, c)] }
           origin = plan.origin_secret ? { "header" => plan.origin_header, "secret" => plan.origin_secret } : nil
+          origin["env"] = plan.origin_env if origin && plan.origin_env.any?
           document = { "services" => services, "origin" => origin }
           document["task_definition"] = plan.task_definition if plan.task_definition
           document["tunnel"] = tunnel_entry(plan.tunnel_service) if plan.tunnel_service
@@ -535,7 +547,7 @@ module Hecks
         # @param plan [Settings::Plan] the resolved settings
         # @return [String] a Makefile whose targets create the two stacks and roll the box
         def makefile(plan)
-          <<~MAKE
+          base = <<~MAKE
             # #{plan.infra_name}: one app box and one RDS instance.
             #   make stacks VPC=vpc-... PRIVATE_SUBNETS=subnet-a,subnet-b PUBLIC_SUBNET=subnet-c [REHEARSAL=true]
             #   make deploy #{plan.task_definition ? '[TASKDEF=family:revision]' : '[TAGS="web=20260101 worker=20260101"]'}
@@ -559,6 +571,18 @@ module Hecks
             deploy:
             \tbash ./deploy-box.sh $(#{plan.task_definition ? 'TASKDEF' : 'TAGS'})
           MAKE
+          "#{base}#{hosting_makefile_tail(plan)}"
+        end
+
+        # With hosting scripts, a deploy ends with the post-deploy smoke and the Makefile includes
+        # the fragment that adds the hosting targets.
+        #
+        # @param plan [Settings::Plan] the resolved settings
+        # @return [String] the Makefile lines that follow the `deploy` recipe, or nothing
+        def hosting_makefile_tail(plan)
+          return "" unless plan.hosting
+
+          "\t#{'TASKDEF="$(TASKDEF)" ' if plan.task_definition}bash ./smoke-after-deploy.sh\n\ninclude hosting.mk\n"
         end
 
         # Fills `@@NAME@@` markers. A marker alone on its line is replaced together with the line,

data/lib/hecks/projections/deploy/fargate.rb

@@ -100,7 +100,7 @@ module Hecks
                   deployed_to("AwsFargate") do
                     ...
                     database "Shared"
-                    owner "Embryonaut"
+                    owner "Core"
                   end
 
               naming the already-deployed domain whose Postgres instance this one borrows.
@@ -327,8 +327,8 @@ module Hecks
                   RetentionInDays: 30
 
               # Always minted — HECKS_SERVE_MODE always runs web.rs, which
-              # panics on an empty SESSION_SECRET (found live: hecksagain-pizzas
-              # 502 after the Aurora cutover). rust/host fetches this at cold
+              # panics on an empty SESSION_SECRET (seen live as a 502
+              # after a database cutover). rust/host fetches this at cold
               # start (secrets.rs), never a plain env var.
               #{session_secret_id}:
                 Type: AWS::SecretsManager::Secret

data/lib/hecks/projections/deploy/lambda.rb

@@ -147,7 +147,7 @@ module Hecks
                   deployed_to("AwsLambda") do
                     ...
                     database "Shared"
-                    owner "Embryonaut"
+                    owner "Core"
                   end
 
               naming the already-deployed domain whose Postgres instance this one borrows.
@@ -273,7 +273,7 @@ module Hecks
                 # GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET/GOOGLE_REDIRECT_URI
                 # deliberately NOT set here — #{domain}'s own .env.local has
                 # no real GOOGLE_CLIENT_ID yet, matching Fly's own current
-                # reality (fly secrets list -a embryonaut-founder-app: only
+                # reality (its secrets list holds only
                 # DATABASE_URL and SESSION_SECRET) that nobody has configured
                 # OAuth for this app at all. Drop real credentials into
                 # .env.local and regenerate to wire this up.
@@ -410,7 +410,7 @@ module Hecks
                   # `stack_name` above exactly — one name, two places it's read
                   # from, never out of sync since both derive from `infra_name`.
                   FunctionName: #{stack_name}
-                  # EXPLICIT, not omitted -- `sam build EmbryonautFunction` and
+                  # EXPLICIT, not omitted -- `sam build WebFunction` and
                   # `sam build --use-container WebFunction` run as TWO SEPARATE
                   # single-resource invocations (deploy:'s own comment on why:
                   # cargo-lambda cross-compiles on this host directly, pg's
@@ -434,7 +434,7 @@ module Hecks
                   # "." NOT "#{logical_id}" -- SAM's Makefile build workflow
                   # requires the Makefile to live INSIDE CodeUri itself
                   # (confirmed live: "Makefile not found at
-                  # .../EmbryonautFunction/Makefile" when CodeUri named a
+                  # .../WebFunction/Makefile" when CodeUri named a
                   # directory of its own). This project's one Makefile lives at
                   # the deploy directory's own root, alongside this template --
                   # "." is where it actually is.
@@ -568,7 +568,7 @@ module Hecks
                         "SubnetIds: [!Ref #{db_id}SubnetA, !Ref #{db_id}SubnetB]\n        SecurityGroupIds: [!Ref #{logical_id}SecurityGroup]"
                       end}
                   # AWS_IAM by default — this dispatches real domain commands
-                  # (cap-table/governance-shaped data, for Embryonaut's own use);
+                  # (cap-table/governance-shaped data);
                   # an unauthenticated public URL is the wrong default for that,
                   # even though it's the simpler one to demo with. NONE only when
                   # `web "Rust"` (rust/host/src/web.rs) makes this the public web
@@ -586,7 +586,7 @@ module Hecks
             # THE WEB APP'S OWN LAMBDA — opt-in, see `web_handler_present` above.
             # VPC-attached for the SAME reason #{logical_id} is (Member's own
             # persistence needs the private RDS instance directly, permanently —
-            # embryonaut.hecksagon's own comment on why), sharing
+            # the hecksagon's own comment on why), sharing
             # #{logical_id}SecurityGroup rather than minting a second one, since
             # both need the identical egress-to-DB rule. That VPC attachment
             # ALSO cuts off the public internet by default (this stack's own "NO
@@ -674,7 +674,7 @@ module Hecks
               # without reworking that whole from-source pg build for a newer
               # image is a real, separate undertaking (untested container image
               # availability, a different vendor/bundle native-extension path)
-              # out of scope here. Matches Embryonaut's own live, currently-
+              # out of scope here. Matches the live, currently-
               # deployed choice exactly, so both consumers of this one shared
               # WebFunction code path stay on the same, PROVEN runtime.
               Properties:
@@ -763,7 +763,7 @@ module Hecks
                     # documents. But THIS function's consumer (`lambda_handler.rb`)
                     # is not a file this generator writes or this repo carries --
                     # it lives in the deploying app's own domain directory (real,
-                    # live example: Embryonaut's own Sinatra app), outside this
+                    # live example: a Sinatra app), outside this
                     # codebase entirely. Redeploying a domain with an existing
                     # `lambda_handler.rb` BEFORE that handler is updated to fetch
                     # these itself (`aws-sdk-secretsmanager`, not yet in this

data/lib/hecks/projections/model/deviations.rb

@@ -48,7 +48,7 @@ module Hecks
         # Fields emitted by `to_h`'s own merge rather than `emits_ir`, for constructs
         # whose shape is not fixed.
         DYNAMIC_TAIL = {
-          "Query"     => %i[options returns],
+          "Query"     => %i[options returns needs],
           "ReadModel" => %i[options group_by aggregate_heads count median_field sum_field avg_field
                             min_field max_field percentile_field percentile_at any_field all_field]
         }.freeze

data/lib/hecks/projections/site/edge/behaviours.rb

@@ -63,9 +63,11 @@ module Hecks
 
           def reference(text) = text.nil? || text == "none" ? nil : Checks.resolve(text)
 
-          # CloudFront takes three sets of methods: read, read with `OPTIONS`, and all.
+          # CloudFront takes three sets of methods: read, read with `OPTIONS`, and all. A route's
+          # `edge_methods` are the verbs the edge lets through; they are its own `methods` unless
+          # the row says more.
           def methods(rows)
-            verbs = rows.flat_map(&:verbs).uniq
+            verbs = rows.flat_map(&:edge_verbs).uniq
             return Deploy::Fargate::Cdn::METHODS.fetch("all") unless (verbs - ["GET"]).empty?
 
             assets = rows.all? { |row| row.origin == "assets" }
@@ -76,7 +78,7 @@ module Hecks
           # http and redirected; anything else (a form, an API, a signed or admin page, a route of
           # the cms or the domain) is served over https only.
           def protocol(row)
-            plain = row.auth == "public" && row.verbs == ["GET"] && %w[website assets].include?(row.origin)
+            plain = row.auth == "public" && row.edge_verbs == ["GET"] && %w[website assets].include?(row.origin)
             plain ? "redirect-to-https" : "https-only"
           end
 

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

@@ -28,7 +28,9 @@ module Hecks
           # @param rows [Array<Table::Row>] the route table's rows
           # @param vocabulary [Hash{Symbol => Array<String>}] the Site chapter's closed sets
           # @param problems [Array<String>] collects each problem found, one line each
-          def initialize(edge, rows, vocabulary, problems)
+          # @param template_named [Boolean] whether the caller names the template itself
+          def initialize(edge, rows, vocabulary, problems, template_named: false)
+            @template_named = template_named
             @edge = edge
             @rows = rows
             @vocabulary = vocabulary
@@ -48,15 +50,21 @@ module Hecks
 
           def check_setting
             setting = @edge.setting
-            return problem("Edge", "has no row naming the template; declare one member with template:") unless setting
+            return problem("Edge", "has no row; declare one member with template:") unless setting
+
+            check_template(setting.template) if setting.template || !@template_named
 
-            template = setting.template.to_s
-            problem("Edge", "template #{template.inspect} must be a path inside the project") if
-              template.empty? || template.start_with?("/") || template.split("/").include?("..")
             problem("Edge", "has secret_header but no secret_value") if setting.secret_header && !setting.secret_value
             problem("Edge", "has secret_value but no secret_header") if setting.secret_value && !setting.secret_header
           end
 
+          def check_template(template)
+            template = template.to_s
+            problem("Edge", "has no template; declare template: or name the file to the tool") if template.empty?
+            problem("Edge", "template #{template.inspect} must be a path inside the project") if
+              template.start_with?("/") || template.split("/").include?("..")
+          end
+
           def check_policies
             @edge.policies.each do |policy|
               label = "EdgePolicy #{policy.cache_class}#{" on #{policy.origin}" if policy.origin}"
@@ -86,12 +94,30 @@ module Hecks
           end
 
           def check_rules
+            return check_no_alb unless @edge.alb?
+
             problem("EdgeRule", "rows need an Edge row with listener:") if @edge.rules.any? && !@edge.setting&.listener
             @edge.rules.each { |rule| check_rule(rule) }
             repeated(@edge.rules.map(&:rule), "EdgeRule", &:itself)
             repeated(@edge.rules.map(&:priority), "EdgeRule priority", &:to_s)
           end
 
+          # With `alb: false` nothing routes by listener rule, so a rule row, or a route that names
+          # one, describes a load balancer the project says it does not have. Every route that is
+          # served by a server behind the edge still needs the origin that reaches it.
+          def check_no_alb
+            problem("EdgeRule", "rows describe a load balancer, and the Edge row says alb: false") if @edge.rules.any?
+            @rows.select(&:alb_rule).each do |row|
+              problem(row.path, "names alb_rule #{row.alb_rule}, and the Edge row says alb: false")
+            end
+            @rows.each do |row|
+              next if row.cdn || !%w[cms domain].include?(row.origin) || @edge.upstream(row.origin)
+
+              problem(row.path, "is served from #{row.origin}, which no EdgeOrigin maps, and with alb: false " \
+                                "nothing else reaches it")
+            end
+          end
+
           def check_rule(rule)
             label = "EdgeRule #{rule.rule}"
             member_of(label, "origin", rule.origin, :origin)

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

@@ -19,7 +19,7 @@ module Hecks
       # `EdgePolicy`, `EdgeOrigin` and `EdgeRule`. `docs/site-routes.md` lists their fields. A
       # project that declares none of the four has no edge to project.
       class Edge
-        Setting  = Struct.new(:template, :listener, :secret_header, :secret_value, keyword_init: true)
+        Setting  = Struct.new(:template, :listener, :secret_header, :secret_value, :alb, keyword_init: true)
         Policy   = Struct.new(:cache_class, :origin, :cache, :origin_request, :response_headers, keyword_init: true)
         Upstream = Struct.new(:origin, :id, :target_group, keyword_init: true)
         Rule     = Struct.new(:rule, :priority, :origin, keyword_init: true)
@@ -29,15 +29,15 @@ module Hecks
 
         # The fields each kind of row may carry, with the Ruby class each takes.
         FIELDS = {
-          setting:  { template: String, listener: String, secret_header: String, secret_value: String },
+          setting:  { template: String, listener: String, secret_header: String, secret_value: String, alb: :bool },
           policy:   { cache_class: String, origin: String, cache: String, origin_request: String,
                     response_headers: String },
           upstream: { origin: String, id: String, target_group: String },
           rule:     { rule: String, priority: Integer, origin: String }
         }.freeze
 
-        # The fields a row of each kind must carry.
-        REQUIRED = { setting: [:template], policy: %i[cache_class cache], upstream: %i[origin id],
+        # The fields a row of each kind must carry. The template may instead be named to the tool.
+        REQUIRED = { setting: [], policy: %i[cache_class cache], upstream: %i[origin id],
                      rule: %i[rule priority origin] }.freeze
 
         STRUCTS = { setting: Setting, policy: Policy, upstream: Upstream, rule: Rule }.freeze
@@ -62,15 +62,17 @@ module Hecks
         # @param chapter [Bluebook::Chapter] the chapter that declares the route table
         # @param table [Table] the checked route table
         # @param vocabulary [Hash{Symbol => Array<String>}] the Site chapter's closed sets
+        # @param template [String, nil] the template the caller names, which stands in for the
+        #   `Edge` row's own `template:`
         # @return [Edge, nil] the checked edge, or nil when the chapter declares none
         # @raise [Table::Invalid] when a row is refused or the edge contradicts the routes
-        def self.read(chapter, table:, vocabulary:)
+        def self.read(chapter, table:, vocabulary:, template: nil)
           declared = OBJECTS.transform_values { |name| Table.rows_of(chapter, name) }
           return nil if declared.values.all?(&:empty?)
 
           problems = []
           records = declared.to_h { |kind, members| [kind, build(kind, members, problems)] }
-          new(records, table: table, vocabulary: vocabulary, problems: problems)
+          new(records, table: table, vocabulary: vocabulary, problems: problems, template: template)
         end
 
         # @param kind [Symbol] a key of `OBJECTS`
@@ -86,27 +88,35 @@ module Hecks
             end
             (REQUIRED.fetch(kind) - member.keys).each { |field| problems << "#{label} needs #{field}" }
             typed = member.slice(*FIELDS.fetch(kind).keys).select do |field, value|
-              value.is_a?(FIELDS.fetch(kind).fetch(field)) || (problems << "#{label} has #{field} #{value.inspect}; " \
-                                                                           "#{field} is a #{FIELDS.fetch(kind).fetch(field)}")
+              typed?(value, FIELDS.fetch(kind).fetch(field)) ||
+                (problems << "#{label} has #{field} #{value.inspect}; " \
+                             "#{field} is #{type_name(FIELDS.fetch(kind).fetch(field))}")
             end
             STRUCTS.fetch(kind).new(**typed)
           end
         end
         private_class_method :build
 
+        def self.typed?(value, type) = type == :bool ? [true, false].include?(value) : value.is_a?(type)
+        private_class_method :typed?
+
+        def self.type_name(type) = type == :bool ? "true or false" : "a #{type}"
+        private_class_method :type_name
+
         # @param records [Hash{Symbol => Array<Struct>}] the rows of each kind
         # @param table [Table] the checked route table
         # @param vocabulary [Hash{Symbol => Array<String>}] the closed sets
         # @param problems [Array<String>] the problems already found in reading the rows
+        # @param template [String, nil] the template the caller names, if any
         # @raise [Table::Invalid] naming every problem when there is one
-        def initialize(records, table:, vocabulary:, problems:)
+        def initialize(records, table:, vocabulary:, problems:, template: nil)
           @setting = records.fetch(:setting).first
           @policies = records.fetch(:policy)
           @upstreams = records.fetch(:upstream)
           @rules = records.fetch(:rule)
-          Checks.new(self, table.rows, vocabulary, problems).call
+          Checks.new(self, table.rows, vocabulary, problems, template_named: !template.nil?).call
           if problems.empty?
-            @listener_rules = Rules.new(self, table.rows, problems).call
+            @listener_rules = alb? ? Rules.new(self, table.rows, problems).call : []
             built = Behaviours.new(self, table.rows, problems).call
             @default_behaviour = built.fetch(:default)
             @behaviours = built.fetch(:list)
@@ -116,6 +126,10 @@ module Hecks
           raise Table::Invalid, "the edge is refused:\n#{problems.map { |line| "  - #{line}" }.join("\n")}"
         end
 
+        # @return [Boolean] whether the project has a load balancer, and so listener rules; true
+        #   unless the `Edge` row says `alb: false`
+        def alb? = setting.nil? || setting.alb != false
+
         # @param origin [String] an origin of the Origin set
         # @return [Upstream, nil] its CloudFront origin and target group
         def upstream(origin) = upstreams.find { |candidate| candidate.origin == origin }

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

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "edge"
+
+module Hecks
+  module Projections
+    module Site
+      # Compares the CloudFront behaviours a site's edge generates with the ones a live
+      # distribution has, and says every way they differ. It only reads: the live side is a
+      # `get-distribution-config` answer, however it was obtained.
+      #
+      # A behaviour is identified by its path pattern (`(default)` for the default one) and judged
+      # on its origin, allowed and cached methods, viewer protocol, compression and three policy
+      # ids. The edge may name a policy by a CloudFormation intrinsic (`!Ref PageCachePolicy`) that
+      # the live distribution holds as an id, so a reference is compared through the `refs` the
+      # caller gives for it, and one with none is reported as unchecked. The behaviours a change is
+      # about to add (`expect_new`) are reported as expected additions, not differences.
+      class LiveEdge
+        # The default behaviour's name, since it has no path pattern.
+        DEFAULT = "(default)"
+
+        # The fields a behaviour is compared on, besides its path.
+        FIELDS = %i[origin methods cached protocol compress cache request response].freeze
+
+        # What a comparison found.
+        #
+        # @!attribute [r] expected
+        #   @return [Array<String>] a line per behaviour only the project has, that was expected
+        # @!attribute [r] differences
+        #   @return [Array<String>] a line per difference that was not expected
+        # @!attribute [r] unchecked
+        #   @return [Array<String>] the policy references no `refs` entry resolves
+        # @!attribute [r] counts
+        #   @return [Array<Integer>] the number of generated and of live behaviours, default aside
+        Comparison = Struct.new(:expected, :differences, :unchecked, :counts, keyword_init: true) do
+          # @return [Boolean] whether live is as generated, expected additions aside
+          def clean? = differences.empty? && unchecked.empty?
+
+          # @return [String] the report, one section per kind of finding
+          def to_s
+            lines = ["generated: #{counts[0]} behaviours + default; live: #{counts[1]} + default"]
+            lines += section("expected additions (only in the project):", expected)
+            lines += section("differences:", differences)
+            lines += section("policy references with no refs entry (unchecked):", unchecked)
+            lines << "the live distribution matches the project" if clean?
+            lines.join("\n")
+          end
+
+          private
+
+          def section(title, entries) = entries.empty? ? [] : [title, *entries.map { |entry| "  #{entry}" }]
+        end
+
+        # @param edge [Edge] the project's checked edge
+        # @param live [Hash] a CloudFront distribution configuration, or an answer wrapping one in
+        #   `DistributionConfig`
+        # @param expect_new [Array<String>] path patterns the project may have and the live one not
+        # @param refs [Hash{String => String}] a policy intrinsic to the id it stands for live
+        def initialize(edge, live, expect_new: [], refs: {})
+          @edge = edge
+          @live = live.fetch("DistributionConfig", live)
+          @expect_new = expect_new
+          @refs = refs
+        end
+
+        # @return [Comparison] every way the project and the live distribution differ
+        def call
+          generated = generated_behaviours
+          current = live_behaviours
+          unchecked = unresolved(generated.values)
+          generated = generated.transform_values { |entry| resolve(entry) }
+          expected, differences = missing(generated, current)
+          differences.concat(changed(generated, current), order(generated, current))
+          Comparison.new(expected: expected, differences: differences, unchecked: unchecked,
+                         counts: [generated.size - 1, current.size - 1])
+        end
+
+        # Reads a policy reference mapping written as `!Ref Name=id` words.
+        #
+        # @param text [String, nil] the words, separated by commas
+        # @return [Hash{String => String}] each intrinsic to its id
+        def self.refs_from(text)
+          text.to_s.split(",").to_h { |pair| pair.strip.split("=", 2).map(&:strip) }
+        end
+
+        private
+
+        def generated_behaviours
+          list = [[DEFAULT, @edge.default_behaviour], *@edge.behaviours.map { |entry| [entry[:path], entry] }]
+          list.to_h do |path, entry|
+            [path, { path: path, origin: entry[:origin], methods: Array(entry[:methods]).sort, cached: %w[GET HEAD],
+                     protocol: entry[:viewer_protocol], compress: entry[:compress] == true,
+                     cache: policy_id(entry[:cache_policy]), request: policy_id(entry[:origin_request_policy]),
+                     response: policy_id(entry[:response_headers_policy]) }]
+          end
+        end
+
+        def policy_id(policy) = policy&.first
+
+        def live_behaviours
+          list = [[DEFAULT, @live.fetch("DefaultCacheBehavior")],
+                  *Array(@live.dig("CacheBehaviors", "Items")).map { |entry| [entry.fetch("PathPattern"), entry] }]
+          list.to_h do |path, entry|
+            [path, { path: path, origin: entry.fetch("TargetOriginId"), methods: methods_of(entry, "Items"),
+                     cached: cached_of(entry), protocol: entry.fetch("ViewerProtocolPolicy"),
+                     compress: entry.fetch("Compress", false) == true, cache: entry["CachePolicyId"],
+                     request: blank(entry["OriginRequestPolicyId"]), response: blank(entry["ResponseHeadersPolicyId"]) }]
+          end
+        end
+
+        def methods_of(entry, key) = entry.fetch("AllowedMethods").fetch(key).sort
+
+        def cached_of(entry) = entry.dig("AllowedMethods", "CachedMethods", "Items").sort
+
+        def blank(value) = value.to_s.empty? ? nil : value
+
+        def intrinsic?(value) = value.is_a?(String) && value.start_with?("!")
+
+        def unresolved(entries)
+          entries.flat_map { |entry| entry.values_at(:cache, :request, :response) }
+                 .select { |value| intrinsic?(value) && !@refs.key?(value) }.uniq.sort
+        end
+
+        def resolve(entry) = entry.transform_values { |value| intrinsic?(value) ? @refs.fetch(value, value) : value }
+
+        def missing(generated, current)
+          expected = []
+          differences = []
+          generated.each do |path, entry|
+            next if current.key?(path)
+
+            detail = entry.except(:path).map { |key, value| "#{key}=#{value.inspect}" }.join(" ")
+            (@expect_new.include?(path) ? expected : differences) << "only in the project: #{path} #{detail}"
+          end
+          current.each_key { |path| differences << "only live: #{path}" unless generated.key?(path) }
+          [expected, differences]
+        end
+
+        def changed(generated, current)
+          generated.flat_map do |path, entry|
+            next [] unless current.key?(path)
+
+            FIELDS.filter_map do |field|
+              next if entry[field] == current[path][field]
+
+              "#{path} differs in #{field}: project=#{entry[field].inspect} live=#{current[path][field].inspect}"
+            end
+          end
+        end
+
+        def order(generated, current)
+          mine = generated.keys.reject { |path| path == DEFAULT || !current.key?(path) }
+          theirs = current.keys.reject { |path| path == DEFAULT || !generated.key?(path) }
+          return [] if mine == theirs
+
+          ["order differs among the behaviours both have:\n    project: #{mine.join(' ')}\n    live:    #{theirs.join(' ')}"]
+        end
+      end
+    end
+  end
+end

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

@@ -77,10 +77,12 @@ module Hecks
         end
 
         def route_fields(row)
-          { path: row.path, kind: row.kind, render: row.render, auth: row.auth, methods: row.verbs,
-            cache: row.cache, origin: row.origin, source: row.source, indexable: row.indexable,
-            switch: blank_to_nil(row.switch), off: row.off, preview: row.preview,
-            label: blank_to_nil(row.label), seo: blank_to_nil(row.seo), redirectTo: row.redirect_to }
+          fields = { path: row.path, kind: row.kind, render: row.render, auth: row.auth, methods: row.verbs,
+                     cache: row.cache, origin: row.origin, source: row.source, indexable: row.indexable,
+                     switch: blank_to_nil(row.switch), off: row.off, preview: row.preview,
+                     label: blank_to_nil(row.label), seo: blank_to_nil(row.seo), redirectTo: row.redirect_to }
+          fields[:seoTitle] = row.seo_title if row.seo_title
+          fields
         end
 
         def switches(rows)
@@ -112,13 +114,16 @@ module Hecks
           TS
         end
 
+        # The navigation arrays hold every entry that has a slot, a switched-off page's too: an
+        # entry of an off page carries its `switch` and `on: false`, and the site drops it while
+        # `pageIsOn(switch)` is false. An entry of a page that is on carries neither.
         def navigation(table)
-          rows = live(table.rows)
+          items = table.rows + table.links
           [nav_const("NAV_DESKTOP", "The desktop navigation: a page with no group is its own entry; a group holds its pages.",
-                     desktop(rows)),
-           nav_const("NAV_MOBILE", "The mobile navigation, in its own order.", mobile(rows)),
-           nav_const("NAV_FOOTER", "The footer columns, left to right, each with its links.", footer(rows)),
-           nav_const("NAV_ADMIN", "The admin navigation: each admin page under its key.", admin(rows))].join("\n\n")
+                     desktop(items)),
+           nav_const("NAV_MOBILE", "The mobile navigation, in its own order.", mobile(items)),
+           nav_const("NAV_FOOTER", "The footer columns, left to right, each with its links.", footer(items)),
+           nav_const("NAV_ADMIN", "The admin navigation: each admin page under its key.", admin(items))].join("\n\n")
         end
 
         def nav_const(name, comment, entries)
@@ -126,32 +131,41 @@ module Hecks
           "// #{comment}\nexport const #{name} = #{body.empty? ? '[]' : "[\n#{body.join("\n")}\n]"} as const;"
         end
 
-        def desktop(rows)
-          items = rows.reject { |row| row.nav_order.nil? }.sort_by { |row| [row.nav_order, row.path] }
+        # One link: a row's or a link's path and label, the fragment a link names, and for a page
+        # that is off the switch that turns it on.
+        def entry(item, **before)
+          link = { **before, path: item.path, label: item.label }
+          link[:fragment] = item.fragment if item.respond_to?(:fragment) && item.fragment
+          link.merge!(switch: item.switch, on: false) if item.off
+          link
+        end
+
+        def order_key(item, order) = [order, item.path, item.respond_to?(:fragment) ? item.fragment.to_s : ""]
+
+        def desktop(items)
           entries = []
-          items.each do |row|
-            item = { path: row.path, label: row.label }
-            group = row.nav_group
-            slot = group && entries.find { |entry| entry[:group] == group }
-            slot ? slot[:items] << item : entries << { group: group, items: [item] }
+          items.reject { |item| item.nav_order.nil? }.sort_by { |item| order_key(item, item.nav_order) }.each do |item|
+            group = item.nav_group
+            slot = group && entries.find { |candidate| candidate[:group] == group }
+            slot ? slot[:items] << entry(item) : entries << { group: group, items: [entry(item)] }
           end
           entries
         end
 
-        def mobile(rows)
-          rows.reject { |row| row.mobile_order.nil? }.sort_by { |row| [row.mobile_order, row.path] }
-              .map { |row| { path: row.path, label: row.label } }
+        def mobile(items)
+          items.reject { |item| item.mobile_order.nil? }.sort_by { |item| order_key(item, item.mobile_order) }
+               .map { |item| item.mobile_heading ? entry(item, heading: item.mobile_heading) : entry(item) }
         end
 
-        def footer(rows)
-          columns = rows.select(&:footer_column).sort_by { |row| [row.footer_order, row.path] }.group_by(&:footer_column)
+        def footer(items)
+          columns = items.select(&:footer_column).sort_by { |item| order_key(item, item.footer_order) }.group_by(&:footer_column)
           columns.sort_by { |name, group| [group.first.footer_order, name] }
-                 .map { |name, group| { column: name, items: group.map { |row| { path: row.path, label: row.label } } } }
+                 .map { |name, group| { column: name, items: group.map { |item| entry(item) } } }
         end
 
-        def admin(rows)
-          rows.select(&:admin_key).sort_by { |row| [row.admin_order, row.admin_key] }
-              .map { |row| { key: row.admin_key, path: row.path, label: row.label } }
+        def admin(items)
+          items.select(&:admin_key).sort_by { |item| [item.admin_order, item.admin_key] }
+               .map { |item| entry(item, key: item.admin_key) }
         end
 
         def search(rows)
@@ -216,13 +230,22 @@ module Hecks
               const source = stripHtml(pattern)
                 .split("/")
                 .map((part) =>
-                  part === "*" ? ".*" : part.startsWith(":") ? "[^/]+" : part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"),
+                  part.startsWith(":")
+                    ? "[^/]+"
+                    : part
+                        .split("*")
+                        .map((piece) => piece.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+                        .join(".*"),
                 )
                 .join("/");
               return new RegExp("^" + source + "$");
             }
 
-            /** Whether a pathname is one a route pattern (`/blog/:slug.html`, `/pay/*`) describes, with or without `.html`. */
+            /**
+             * Whether a pathname is one a route pattern describes, with or without `.html`. A `:name` is one
+             * segment; a `*` is any run of characters, `/` included, wherever it stands, as in a CDN's path
+             * pattern: `/pay/*` matches `/pay/7` and `/admin*` matches `/admin`, `/admin-inbox` and `/admin/x`.
+             */
             export function matchesPath(pattern: string, pathname: string): boolean {
               return toRegExp(pattern).test(stripHtml(pathname));
             }