hecks 3.6.0 → 3.9.0

data/lib/hecks/projections/deploy/shared_database_instance/templates/Makefile.tmpl

@@ -0,0 +1,11 @@
+# @@STACK@@: the shared RDS instance that each site's own box stack keeps a database on.
+#   make stack VPC=vpc-... PRIVATE_SUBNETS=subnet-a,subnet-b [BASTION_SG=sg-...] [ALERT_EMAIL=you@example.com] [REHEARSAL=true]
+STACK = @@STACK@@
+# true makes a throwaway copy: no deletion protection and no final snapshot. The default is the real instance.
+REHEARSAL ?= false
+
+.PHONY: stack
+stack:
+	aws cloudformation deploy --template-file rds.yaml --stack-name $(STACK) --capabilities CAPABILITY_IAM \
+		--parameter-overrides VpcId=$(VPC) PrivateSubnetIds=$(PRIVATE_SUBNETS) Rehearsal=$(REHEARSAL) \
+		$(if $(BASTION_SG),BastionSecurityGroupId=$(BASTION_SG)) $(if $(ALERT_EMAIL),AlertEmail=$(ALERT_EMAIL))

data/lib/hecks/projections/deploy/shared_database_instance/templates/README.md.tmpl

@@ -0,0 +1,25 @@
+# @@STACK@@
+
+The shared RDS Postgres instance (@@DATABASE_CLASS@@, @@STORAGE_GB@@ GB, Postgres @@ENGINE_VERSION@@, @@BACKUP_DAYS@@-day backups) on which several
+sites each keep their own database and login role. Generated by `hecks deploy project`; do not edit `rds.yaml`.
+
+## Create it
+
+```
+make stack VPC=vpc-... PRIVATE_SUBNETS=subnet-a,subnet-b BASTION_SG=sg-... ALERT_EMAIL=you@example.com
+```
+
+`BASTION_SG` is the security group of the machine that tunnels to the instance over SSM (a site's own box works).
+Outputs: `DbEndpoint`, `DbSecurityGroupId`, `DbSecretArn` (the master secret) and `AlertTopicArn`.
+
+## Add a site
+
+A site's world says `shared_database "@@STACK@@"`. Its generated `provision-database.sh` creates that site's role, its
+database, and the secret `<site>/database` that its containers read; its box stack adds its own ingress rule to this
+instance's security group. Nothing else needs to change here.
+
+## Things to know
+
+- The master secret is read only by the person who provisions a site, never by a box.
+- This stack cannot be deleted while any site's box stack still references its security group.
+- One maintenance window, restart or failure touches every site. Alarms (storage, CPU, memory) are for the instance.

data/lib/hecks/projections/deploy/shared_database_instance/templates/rds.yaml.tmpl

@@ -0,0 +1,180 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Description: >
+  The shared RDS Postgres instance @@STACK@@, on which several sites each keep their own database and
+  login role. Private subnets only; each site's box stack admits itself on 5432, so nothing else can reach
+  it. The master password is managed by RDS in Secrets Manager ({username, password}); only the operator
+  who runs a site's provision-database.sh reads it, and no box does.
+
+Parameters:
+  VpcId:
+    Type: AWS::EC2::VPC::Id
+  BastionSecurityGroupId:
+    Type: String
+    Default: ""
+    Description: >
+      A security group allowed to reach the instance on 5432, for the bastion that provision-database.sh and
+      restore-to-rds.sh tunnel through. Blank admits nothing but the sites' boxes.
+  PrivateSubnetIds:
+    Type: List<AWS::EC2::Subnet::Id>
+    Description: At least two subnets in different availability zones (an RDS subnet group needs them).
+  InstanceClass:
+    Type: String
+    Default: @@DB_CLASS@@
+  AllocatedStorageGb:
+    Type: Number
+    Default: @@STORAGE_GB@@
+  EngineVersion:
+    Type: String
+    Default: "@@ENGINE_VERSION@@"
+    Description: A major version ("16") lets RDS pick its current minor release.
+  BackupRetentionDays:
+    Type: Number
+    Default: @@BACKUP_DAYS@@
+  ExistingAlertTopicArn:
+    Type: String
+    Default: ""
+    Description: An SNS topic that already has subscribers. Blank creates a new topic.
+  AlertEmail:
+    Type: String
+    Default: ""
+    Description: Subscribed to a new topic (AWS sends one confirmation link). Ignored when ExistingAlertTopicArn is set.
+  Rehearsal:
+    Type: String
+    Default: "false"
+    AllowedValues: ["true", "false"]
+    Description: >
+      true is a throwaway copy (no deletion protection, no final snapshot). false is the real
+      database: deletion protection on and a snapshot taken on delete.
+
+Conditions:
+  NewTopic: !Equals [!Ref ExistingAlertTopicArn, ""]
+  NewTopicWithEmail: !And [!Condition NewTopic, !Not [!Equals [!Ref AlertEmail, ""]]]
+  IsRehearsal: !Equals [!Ref Rehearsal, "true"]
+  HasBastion: !Not [!Equals [!Ref BastionSecurityGroupId, ""]]
+
+Resources:
+  # No inline rules: every site's box stack adds its own ingress rule to this group, and CloudFormation can
+  # revoke an externally added rule when it updates an inline list. The bastion's rule is its own resource.
+  DbSecurityGroup:
+    Type: AWS::EC2::SecurityGroup
+    Properties:
+      GroupDescription: @@STACK@@ RDS, 5432 from each site box (the box stacks add the rules) and a bastion if given
+      VpcId: !Ref VpcId
+
+  BastionIngress:
+    Type: AWS::EC2::SecurityGroupIngress
+    Condition: HasBastion
+    Properties:
+      GroupId: !Ref DbSecurityGroup
+      IpProtocol: tcp
+      FromPort: 5432
+      ToPort: 5432
+      SourceSecurityGroupId: !Ref BastionSecurityGroupId
+      Description: Bastion for provision-database.sh and restore-to-rds.sh
+
+  DbSubnetGroup:
+    Type: AWS::RDS::DBSubnetGroup
+    Properties:
+      DBSubnetGroupDescription: @@STACK@@ RDS subnets
+      SubnetIds: !Ref PrivateSubnetIds
+
+  Database:
+    Type: AWS::RDS::DBInstance
+    DeletionPolicy: !If [IsRehearsal, Delete, Snapshot]
+    UpdateReplacePolicy: !If [IsRehearsal, Delete, Snapshot]
+    Properties:
+      Engine: postgres
+      EngineVersion: !Ref EngineVersion
+      DBInstanceClass: !Ref InstanceClass
+      AllocatedStorage: !Ref AllocatedStorageGb
+      StorageType: gp3
+      StorageEncrypted: true
+      MasterUsername: postgres
+      ManageMasterUserPassword: true
+      DBSubnetGroupName: !Ref DbSubnetGroup
+      VPCSecurityGroups: [!Ref DbSecurityGroup]
+      PubliclyAccessible: false
+      MultiAZ: false
+      BackupRetentionPeriod: !Ref BackupRetentionDays
+      DeletionProtection: !If [IsRehearsal, false, true]
+      AutoMinorVersionUpgrade: true
+      CopyTagsToSnapshot: true
+      Tags:
+        - Key: Name
+          Value: @@STACK@@-rds
+
+  AlertTopic:
+    Type: AWS::SNS::Topic
+    Condition: NewTopic
+    Properties:
+      DisplayName: @@STACK@@-alerts
+
+  AlertSubscription:
+    Type: AWS::SNS::Subscription
+    Condition: NewTopicWithEmail
+    Properties:
+      TopicArn: !Ref AlertTopic
+      Protocol: email
+      Endpoint: !Ref AlertEmail
+
+  # Every site's journal only grows, and RDS stops accepting writes when storage is full.
+  StorageLowAlarm:
+    Type: AWS::CloudWatch::Alarm
+    Properties:
+      AlarmDescription: RDS free storage under 3 GB
+      Namespace: AWS/RDS
+      MetricName: FreeStorageSpace
+      Dimensions: [{ Name: DBInstanceIdentifier, Value: !Ref Database }]
+      Statistic: Minimum
+      Period: 300
+      EvaluationPeriods: 3
+      Threshold: 3221225472
+      ComparisonOperator: LessThanThreshold
+      TreatMissingData: breaching
+      AlarmActions: [!If [NewTopic, !Ref AlertTopic, !Ref ExistingAlertTopicArn]]
+      OKActions: [!If [NewTopic, !Ref AlertTopic, !Ref ExistingAlertTopicArn]]
+
+  CpuHighAlarm:
+    Type: AWS::CloudWatch::Alarm
+    Properties:
+      AlarmDescription: "RDS CPU above 80% for 15 minutes (a burstable class may be out of credits)"
+      Namespace: AWS/RDS
+      MetricName: CPUUtilization
+      Dimensions: [{ Name: DBInstanceIdentifier, Value: !Ref Database }]
+      Statistic: Average
+      Period: 300
+      EvaluationPeriods: 3
+      Threshold: 80
+      ComparisonOperator: GreaterThanThreshold
+      TreatMissingData: notBreaching
+      AlarmActions: [!If [NewTopic, !Ref AlertTopic, !Ref ExistingAlertTopicArn]]
+      OKActions: [!If [NewTopic, !Ref AlertTopic, !Ref ExistingAlertTopicArn]]
+
+  MemoryLowAlarm:
+    Type: AWS::CloudWatch::Alarm
+    Properties:
+      AlarmDescription: RDS freeable memory under 100 MB for 15 minutes
+      Namespace: AWS/RDS
+      MetricName: FreeableMemory
+      Dimensions: [{ Name: DBInstanceIdentifier, Value: !Ref Database }]
+      Statistic: Minimum
+      Period: 300
+      EvaluationPeriods: 3
+      Threshold: 104857600
+      ComparisonOperator: LessThanThreshold
+      TreatMissingData: notBreaching
+      AlarmActions: [!If [NewTopic, !Ref AlertTopic, !Ref ExistingAlertTopicArn]]
+      OKActions: [!If [NewTopic, !Ref AlertTopic, !Ref ExistingAlertTopicArn]]
+
+Outputs:
+  AlertTopicArn:
+    Description: Pass as AlertTopicArn to the box stack.
+    Value: !If [NewTopic, !Ref AlertTopic, !Ref ExistingAlertTopicArn]
+  DbEndpoint:
+    Value: !GetAtt Database.Endpoint.Address
+  DbSecretArn:
+    Description: RDS-managed master secret ({username, password}).
+    Value: !GetAtt Database.MasterUserSecret.SecretArn
+  DbSecurityGroupId:
+    Description: Pass as DbSecurityGroupId to the box stack.
+    Value: !Ref DbSecurityGroup

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

@@ -0,0 +1,106 @@
+require "json"
+require_relative "../../projector"
+require_relative "box/settings"
+
+module Hecks
+  module Projections
+    module Deploy
+      # The shared database target for `deployed_to("AwsSharedDatabase")`: one RDS Postgres instance
+      # that several sites each keep a database on (ADR 0092). It renders the instance's stack
+      # (`rds.yaml`), a `Makefile` that deploys it, and a README. A site's own world says
+      # `shared_database "<this stack>"`, and its box generates the provisioning of its database.
+      #
+      # The stack's name is the world's `stack_name` exactly, with no prefix or suffix, because
+      # every site names it by that string.
+      module SharedDatabaseInstance
+        extend Projector::Target
+
+        projects_as :aws_shared_database, needs_world: true, emits: :files
+
+        TEMPLATE_DIR = File.join(__dir__, "shared_database_instance", "templates").freeze
+
+        # What the world leaves out resolves to these.
+        DEFAULTS = { database_class: "db.t4g.small", storage_gb: 30, engine_version: "16", backup_days: 7 }.freeze
+
+        # The checked settings the templates are filled from.
+        Plan = Struct.new(:stack, :database_class, :storage_gb, :engine_version, :backup_days, keyword_init: true)
+
+        module_function
+
+        # @param bluebook [Bluebook::Behaviour::Chapter] the domain's own booted chapter
+        # @param options [Hash] generation options; same shape as `Box.call`'s
+        # @return [Hash{String => String}] the generated file contents, keyed by filename
+        # @raise [ArgumentError] if the domain's deploy settings are invalid
+        def call(bluebook:, options: {})
+          world, _domain, world_file = options.values_at(:world, :domain_dir, :world_file)
+          settings = world.for_verb("deployed_to")
+          target = declare(world.domain, settings, world_file)
+          render_all(resolve(settings, target))
+        end
+
+        # Validates the target through the Deploy bluebook's own `SharedDatabaseTarget.Declare`.
+        #
+        # @return [Object] the declared target aggregate
+        # @raise [ArgumentError] when the bluebook refuses a value
+        def declare(domain, settings, world_file)
+          dispatcher = Hecks.boot(File.expand_path("../../deploy", __dir__))
+          dispatcher.dispatch("Deploy::SharedDatabaseTarget.Declare", with: declare_arguments(domain, settings)).instance
+        rescue *Hecks::Runtime::DOMAIN_REFUSALS => e
+          raise ArgumentError, "#{world_file}'s deployed_to(\"AwsSharedDatabase\") is invalid: #{e.message}"
+        end
+
+        # @return [Hash{Symbol => Hash}] the `Declare` arguments, each `{ value: }`
+        def declare_arguments(domain, settings)
+          {
+            domain: { value: domain }, region: { value: settings[:region] },
+            database_class: { value: settings.fetch(:database_class, DEFAULTS[:database_class]) },
+            storage_gb: { value: settings.fetch(:storage_gb, DEFAULTS[:storage_gb]) }
+          }
+        end
+
+        # @param settings [Hash{Symbol => Object}] the world's `AwsSharedDatabase` settings
+        # @param target [Object] the declared target, whose class and storage `Declare` has checked
+        # @return [Plan] the checked settings
+        # @raise [ArgumentError] when the stack name is missing or a setting is malformed
+        def resolve(settings, target)
+          Plan.new(stack: read_stack(settings), database_class: target.state[:database_class].value,
+                   storage_gb: target.state[:storage_gb].value, engine_version: read_engine(settings),
+                   backup_days: Box::Settings.integer(:backup_days, settings.fetch(:backup_days, DEFAULTS[:backup_days]), 1, 35))
+        end
+
+        # @return [String] the stack's name, which every site's `shared_database` repeats
+        def read_stack(settings)
+          stack = settings.fetch(:stack_name) do
+            raise ArgumentError, "stack_name: the shared instance's stack, which every site names in shared_database"
+          end
+          Box::Settings.check(:stack_name, stack, Box::Settings::NAME)
+        end
+
+        # @return [String] the Postgres major (or major.minor) version
+        def read_engine(settings)
+          Box::Settings.check(:engine_version, settings.fetch(:engine_version, DEFAULTS[:engine_version]).to_s,
+                              Box::Settings::ENGINE)
+        end
+
+        # @param plan [Plan] the checked settings
+        # @return [Hash{String => String}] every generated file
+        def render_all(plan)
+          values = { "STACK" => plan.stack, "DB_CLASS" => plan.database_class, "DATABASE_CLASS" => plan.database_class,
+                     "STORAGE_GB" => plan.storage_gb.to_s, "ENGINE_VERSION" => plan.engine_version,
+                     "BACKUP_DAYS" => plan.backup_days.to_s }
+          { "rds.yaml" => template("rds.yaml.tmpl", values), "Makefile" => template("Makefile.tmpl", values),
+            "README.md" => template("README.md.tmpl", values) }
+        end
+
+        # Fills `@@NAME@@` markers.
+        #
+        # @param file [String] the template's name in `TEMPLATE_DIR`
+        # @param values [Hash{String => String}] marker name => text
+        # @return [String] the rendered file
+        def template(file, values)
+          values.reduce(File.read(File.join(TEMPLATE_DIR, file))) { |text, (marker, value)| text.gsub("@@#{marker}@@", value) }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/deploy/vercel/settings.rb

@@ -0,0 +1,83 @@
+module Hecks
+  module Projections
+    module Deploy
+      module Vercel
+        # Resolves a world's `deployed_to("Vercel")` settings into the checked plan the generator
+        # renders from.
+        #
+        # Every string that reaches `vercel.json` or the deploy script is matched against a
+        # conservative pattern first, so a world file cannot splice shell or JSON into the output.
+        # Secrets are named here, never held: `env` lists variable names, and the deploy script
+        # reads each value from the caller's environment.
+        module Settings
+          NAME      = /\A[a-z0-9][a-z0-9-]{0,99}\z/
+          SCOPE     = /\A[a-z0-9][a-z0-9_-]{0,99}\z/
+          ENV_VAR   = /\A[A-Z][A-Z0-9_]{0,99}\z/
+          CRON_PATH = %r{\A/[A-Za-z0-9/_.-]{0,200}\z}
+          SCHEDULE  = %r{\A[0-9*/,-]+( [0-9A-Za-z*/,-]+){4}\z}
+
+          # The variable the hecksagon's Postgres adapter reads; always set on deploy.
+          DATABASE_ENV = "DATABASE_URL".freeze
+
+          Plan = Data.define(:project, :scope, :region, :memory, :max_duration, :crons, :env)
+
+          module_function
+
+          # @param deploy_settings [Hash{Symbol => Object}] the world's `Vercel` settings
+          # @param target [Object] the validated `VercelTarget` (region, memory and duration,
+          #   already checked by `Declare`)
+          # @param infra_name [String] the project name the world or the domain gives
+          # @return [Plan] the resolved plan
+          # @raise [ArgumentError] when a setting is malformed
+          def resolve(deploy_settings:, target:, infra_name:)
+            s = deploy_settings
+            Plan.new(project: check(:project, infra_name, NAME), scope: optional(:scope, s[:scope], SCOPE),
+                     **declared_sizes(target), crons: read_crons(s.fetch(:crons, [])),
+                     env: read_env(s.fetch(:env, [])))
+          end
+
+          # @param target [Object] the declared `VercelTarget`
+          # @return [Hash{Symbol => Object}] the values `Declare` has already validated
+          def declared_sizes(target)
+            %i[region memory max_duration].to_h { |key| [key, target.state[key].value] }
+          end
+
+          # @return [String] the value, when it matches
+          # @raise [ArgumentError] when it does not
+          def check(key, value, pattern)
+            return value.to_s if value.to_s.match?(pattern)
+
+            raise ArgumentError, "#{key} #{value.inspect} is not allowed here (it must match #{pattern.source})"
+          end
+
+          # @return [String, nil] the value, or nil when the world left it out
+          def optional(key, value, pattern)
+            value.nil? ? nil : check(key, value, pattern)
+          end
+
+          # @param list [Array<Hash>] `[{ path: "/cron/tick", schedule: "0 * * * *" }]`
+          # @return [Array<Hash{Symbol => String}>] the checked crons
+          def read_crons(list)
+            raise ArgumentError, "crons must be a list of { path:, schedule: }" unless list.is_a?(Array)
+
+            list.map do |cron|
+              unless cron.is_a?(Hash) && cron.key?(:path) && cron.key?(:schedule)
+                raise ArgumentError, "a cron needs a path and a schedule, got #{cron.inspect}"
+              end
+
+              { path: check(:cron_path, cron[:path], CRON_PATH), schedule: check(:cron_schedule, cron[:schedule], SCHEDULE) }
+            end
+          end
+
+          # @param list [Array<String>] environment variable names the deploy sets on Vercel
+          # @return [Array<String>] the names, `DATABASE_URL` first, each once
+          def read_env(list)
+            raise ArgumentError, "env must be a list of variable names" unless list.is_a?(Array)
+
+            ([DATABASE_ENV] + list.map { |name| check(:env, name, ENV_VAR) }).uniq
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,134 @@
+require "json"
+require_relative "../../projector"
+require_relative "vercel/settings"
+
+module Hecks
+  module Projections
+    module Deploy
+      # The Vercel deploy target for `deployed_to("Vercel")`: the domain's Rust host as one Vercel
+      # function. It renders `vercel.json` (the function's size, region, the rewrite that sends
+      # every path to it, crons), `.vercelignore`, `deploy-vercel.sh` and a `Makefile`.
+      #
+      # Persistence is the hecksagon's: the host reads `DATABASE_URL`, which the deploy script sets
+      # from the caller's environment. This projection creates no database and holds no secret.
+      module Vercel
+        extend Projector::Target
+
+        projects_as :vercel, needs_world: true, emits: :files
+
+        # The function every request is rewritten to; its file is the host's Vercel entry point.
+        FUNCTION = "api/host".freeze
+
+        # Keeps only the release binaries in an uploaded `target/`, as Vercel's Rust guide advises.
+        VERCELIGNORE = <<~IGNORE.freeze
+          target/**
+          !target/release
+          !target/x86_64-unknown-linux-gnu/release/**
+          !target/aarch64-unknown-linux-gnu/release/**
+        IGNORE
+
+        module_function
+
+        # @param bluebook [Bluebook::Behaviour::Chapter] the domain's own booted chapter
+        # @param options [Hash] generation options; same shape as `Box.call`'s
+        # @return [Hash{String => String}] the generated file contents, keyed by filename
+        # @raise [ArgumentError] if the domain's deploy settings are invalid
+        def call(bluebook:, options: {})
+          world, domain, world_file = options.values_at(:world, :domain_dir, :world_file)
+          settings = tenant_settings(world.for_verb("deployed_to"), options[:tenant] || {}, File.basename(domain))
+          target = declare(world.domain, settings, world_file)
+          infra_name = (settings[:stack_name] || File.basename(domain)).to_s.tr("_", "-").downcase
+          plan = Settings.resolve(deploy_settings: settings, target: target, infra_name: infra_name)
+          render_all(plan)
+        end
+
+        # @return [Hash{Symbol => Object}] the settings with the `--tenant` suffix on the stack name
+        def tenant_settings(settings, tenant, domain_name)
+          return settings unless tenant[:tenant]
+
+          settings.merge(stack_name: "#{settings[:stack_name] || domain_name}-#{tenant[:tenant]}")
+        end
+
+        # Validates the target through the Deploy bluebook's own `VercelTarget.Declare`.
+        #
+        # @return [Object] the declared target aggregate
+        # @raise [ArgumentError] when the bluebook refuses a value
+        def declare(domain, settings, world_file)
+          dispatcher = Hecks.boot(File.expand_path("../../deploy", __dir__))
+          dispatcher.dispatch("Deploy::VercelTarget.Declare", with: declare_arguments(domain, settings)).instance
+        rescue *Hecks::Runtime::DOMAIN_REFUSALS => e
+          raise ArgumentError, "#{world_file}'s deployed_to(\"Vercel\") is invalid: #{e.message}"
+        end
+
+        # @return [Hash{Symbol => Hash}] the `VercelTarget.Declare` arguments, each a `{ value: }`
+        def declare_arguments(domain, settings)
+          {
+            domain: { value: domain }, region: { value: settings.fetch(:region, "iad1") },
+            memory: { value: settings.fetch(:memory, 1024) },
+            max_duration: { value: settings.fetch(:max_duration, 30) }
+          }
+        end
+
+        # @param plan [Settings::Plan] the resolved settings
+        # @return [Hash{String => String}] every generated file
+        def render_all(plan)
+          { "vercel.json" => vercel_json(plan), ".vercelignore" => VERCELIGNORE,
+            "deploy-vercel.sh" => deploy_script(plan), "Makefile" => makefile(plan) }
+        end
+
+        # @param plan [Settings::Plan] the resolved settings
+        # @return [String] `vercel.json`
+        def vercel_json(plan)
+          config = {
+            "$schema"   => "https://openapi.vercel.sh/vercel.json",
+            "functions" => { "#{FUNCTION}.rs" => { "memory" => plan.memory, "maxDuration" => plan.max_duration } },
+            "regions"   => [plan.region],
+            "rewrites"  => [{ "source" => "/(.*)", "destination" => "/#{FUNCTION}" }]
+          }
+          config["crons"] = plan.crons.map { |cron| cron.transform_keys(&:to_s) } if plan.crons.any?
+          "#{JSON.pretty_generate(config)}\n"
+        end
+
+        # The script sets each named variable on the project from the caller's environment over
+        # stdin, so no value is on a command line or in a file, then deploys to production.
+        #
+        # @param plan [Settings::Plan] the resolved settings
+        # @return [String] `deploy-vercel.sh`
+        def deploy_script(plan)
+          scope = plan.scope ? " --scope #{plan.scope}" : ""
+          sets = plan.env.map { |name| env_command(name, scope) }
+          <<~SH
+            #!/bin/bash
+            # Deploys #{plan.project} to Vercel production. Needs VERCEL_TOKEN and each variable below in the
+            # environment, e.g. `op run --env-file=.env.tpl -- make deploy`; no value is written to disk.
+            set -euo pipefail
+            cd "$(dirname "$0")"
+            vercel link --yes --project #{plan.project}#{scope}
+            #{sets.join("\n")}
+            vercel deploy --prod --yes#{scope}
+          SH
+        end
+
+        # @param name [String] a checked variable name
+        # @param scope [String] the ` --scope team` flag, or empty
+        # @return [String] the line that reads the variable and sets it on the project
+        def env_command(name, scope)
+          "printf '%s' \"${#{name}:?#{name} must be set in the environment}\" | " \
+            "vercel env add #{name} production --sensitive --force --yes#{scope}"
+        end
+
+        # @param plan [Settings::Plan] the resolved settings
+        # @return [String] the `Makefile`
+        def makefile(plan)
+          <<~MAKE
+            # #{plan.project}: one Vercel function.
+            #   make deploy   (needs VERCEL_TOKEN and #{plan.env.join(", ")} in the environment)
+            .PHONY: deploy
+            deploy:
+            \t./deploy-vercel.sh
+          MAKE
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      # The requests a live site must answer as its route table says, and the verdict on each
+      # answer. It sends nothing: the caller makes the requests and hands each response back.
+      # A route with a parameter or a prefix (`/blog/:slug.html`, `/auth/*`) has no one URL to ask.
+      #
+      # - an `admin` route refuses an anonymous GET (and POST, where it takes one), uncached
+      # - an indexable `public` page answers 200 and names its canonical link
+      # - a row that is `off` answers 404, and a `redirect` row redirects to `redirect_to`
+      # - a path no row declares answers 404
+      class Probe
+        # One request to make and what a good answer to it looks like.
+        #
+        # @!attribute [r] label
+        #   @return [String] what is being checked, for the report
+        # @!attribute [r] verb
+        #   @return [String] GET or POST
+        # @!attribute [r] path
+        #   @return [String] the path to ask
+        # @!attribute [r] expect
+        #   @return [Symbol] one of `:refused`, `:page`, `:missing`, `:redirect`
+        # @!attribute [r] to
+        #   @return [String, nil] where a `:redirect` must lead
+        Check = Struct.new(:label, :verb, :path, :expect, :to, keyword_init: true)
+
+        # What one answer was: its status, its headers (lower-case names) and its body.
+        Response = Struct.new(:status, :headers, :body, keyword_init: true)
+
+        # The statuses that turn an anonymous caller away from an admin route.
+        REFUSED = [301, 302, 303, 307, 308, 401, 403].freeze
+
+        # The redirect statuses.
+        REDIRECTS = [301, 302, 303, 307, 308].freeze
+
+        # @param rows [Array<Table::Row>] the checked rows of a route table
+        # @param run [String] the run's name, which makes the missing path unique to it
+        def initialize(rows, run:)
+          @rows = rows
+          @run = run
+        end
+
+        # @return [Array<Check>] every request worth making, in the table's order, then the
+        #   path that must not exist
+        def checks
+          @rows.select { |row| askable?(row) }.flat_map { |row| for_row(row) } + [missing]
+        end
+
+        # Judges one answer.
+        #
+        # @param check [Check] the request that was made
+        # @param response [Response] what came back
+        # @return [String, nil] why the answer is wrong, or nil when it is right
+        def verdict(check, response)
+          case check.expect
+          when :refused  then refused(response)
+          when :page     then page(response)
+          when :missing  then response.status == 404 ? nil : "expected 404, got HTTP #{response.status}"
+          when :redirect then redirect(check, response)
+          end
+        end
+
+        private
+
+        def askable?(row) = !row.path.empty? && !row.path.match?(/[:*]/)
+
+        def for_row(row)
+          return [off(row)] if row.off
+          return admin(row) if row.auth == "admin"
+          return [redirecting(row)] if row.kind == "redirect" && row.redirect_to
+          return [page_of(row)] if page?(row)
+
+          []
+        end
+
+        def page?(row) = row.auth == "public" && row.kind == "page" && row.indexable && row.verbs.include?("GET")
+
+        def off(row) = Check.new(label: "#{row.path} is switched off: 404", verb: "GET", path: row.path, expect: :missing)
+
+        def admin(row)
+          row.verbs.select { |verb| %w[GET POST].include?(verb) }.map do |verb|
+            Check.new(label: "#{verb} #{row.path} without a session is refused and not cached",
+                      verb: verb, path: row.path, expect: :refused)
+          end
+        end
+
+        def redirecting(row)
+          Check.new(label: "#{row.path} redirects to #{row.redirect_to}", verb: "GET", path: row.path,
+                    expect: :redirect, to: row.redirect_to)
+        end
+
+        def page_of(row)
+          Check.new(label: "#{row.path} answers 200 with a canonical link", verb: "GET", path: row.path, expect: :page)
+        end
+
+        def missing
+          Check.new(label: "a path no row declares is a real 404", verb: "GET", path: "/probe-#{@run}-missing",
+                    expect: :missing)
+        end
+
+        def refused(response)
+          return "expected a redirect, 401 or 403, got HTTP #{response.status}" unless REFUSED.include?(response.status)
+          return nil if response.status >= 400
+
+          control = response.headers["cache-control"].to_s
+          return nil unless control.match?(/public|max-age=[1-9]/) && !control.match?(/no-store|private/)
+
+          "the redirect is cacheable (Cache-Control: #{control})"
+        end
+
+        def page(response)
+          return "expected 200, got HTTP #{response.status}" unless response.status == 200
+          return nil if response.body.to_s.match?(/<link[^>]+rel=["']canonical["']/i)
+
+          "the page has no canonical link"
+        end
+
+        def redirect(check, response)
+          return "expected a redirect, got HTTP #{response.status}" unless REDIRECTS.include?(response.status)
+
+          location = response.headers["location"].to_s
+          return nil if location == check.to || (location.end_with?(check.to) && location.start_with?("http"))
+
+          "redirects to #{location.inspect}, expected #{check.to.inspect}"
+        end
+      end
+    end
+  end
+end