hecks 3.6.0 → 3.7.0

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/site_host/templates.rb

@@ -71,9 +71,13 @@ module Hecks
 
             const client = new SecretsManagerClient({});
 
-            async function secretField(arn, field) {
+            async function secretJson(arn) {
               const { SecretString } = await client.send(new GetSecretValueCommand({ SecretId: arn }));
-              const value = JSON.parse(SecretString)[field];
+              return JSON.parse(SecretString);
+            }
+
+            async function secretField(arn, field) {
+              const value = (await secretJson(arn))[field];
               if (!value) throw new Error(`secret ${arn} has no "${field}" field`);
               return value;
             }
@@ -81,12 +85,16 @@ module Hecks
             if (process.env.DB_SECRET_ARN) {
               const { DB_HOST, DB_NAME } = process.env;
               if (!DB_HOST || !DB_NAME) throw new Error("DB_HOST and DB_NAME are required when DB_SECRET_ARN is set");
-              const password = await secretField(process.env.DB_SECRET_ARN, "password");
+              // The user and port come from the secret: RDS's master secret says postgres, and a client that shares
+              // an instance with others has its own role. A secret without them is read as postgres on 5432.
+              const { username = "postgres", password, port = 5432 } = await secretJson(process.env.DB_SECRET_ARN);
+              if (!password) throw new Error(`secret ${process.env.DB_SECRET_ARN} has no "password" field`);
               // The password goes through encodeURIComponent: the generated one can hold characters (@ / #)
               // that would otherwise split the URL. RDS enforces TLS; verify against Amazon's CA bundle,
               // which the image holds beside this file.
               const ssl = "sslmode=verify-full&sslrootcert=" + new URL("./rds-global-bundle.pem", import.meta.url).pathname;
-              process.env.DATABASE_URL = `postgres://postgres:${encodeURIComponent(password)}@${DB_HOST}:5432/${DB_NAME}?${ssl}`;
+              process.env.DATABASE_URL =
+                `postgres://${encodeURIComponent(username)}:${encodeURIComponent(password)}@${DB_HOST}:${port}/${DB_NAME}?${ssl}`;
             } else if (!process.env.DATABASE_URL) {
               throw new Error("either DB_SECRET_ARN (+ DB_HOST/DB_NAME) or DATABASE_URL is required");
             }

data/lib/hecks/projections.rb

@@ -23,6 +23,8 @@ require_relative "projections/deploy/shared"
 require_relative "projections/deploy/lambda"
 require_relative "projections/deploy/fargate"
 require_relative "projections/deploy/box"
+require_relative "projections/deploy/shared_database_instance"
+require_relative "projections/deploy/vercel"
 require_relative "projections/deploy/smoke"
 require_relative "projections/deploy/template_diff"
 require_relative "projections/site/routes_ts"

data/lib/hecks/quality_control/adapters/github_checks.rb

@@ -14,6 +14,10 @@ module Hecks
       # Check-run conclusions that count as green; `skipped` covers path-filtered workflows.
       PASSING = %w[success neutral skipped].freeze
 
+      # The GitHub Actions app. A promotion counts only the checks it reported: a check of the same
+      # name posted by another app, a token or a person certifies nothing.
+      GITHUB_ACTIONS_APP_ID = 15_368
+
       # A commit sha as GitHub accepts it in an API path.
       SHA_PATTERN = /\A[0-9a-fA-F]{7,40}\z/
 
@@ -38,7 +42,8 @@ module Hecks
 
       # Where each named check stands against a commit, for a caller that must tell a check that is
       # still running from one that failed (`run` raises for both). A name that reported more than
-      # once (a re-run) stands as its most recent report.
+      # once (a re-run) stands as its most recent report. Only reports of the GitHub Actions app
+      # count; a name reported by any other app stands as `:missing`.
       #
       # @param commit [Hash, String] a materialized value object (`{value: sha}`) or a bare sha
       # @param names [Array<String>] the checks to look up
@@ -46,13 +51,15 @@ module Hecks
       #   not completed) or `:missing` (not reported at all)
       # @raise [RuntimeError] when the sha is malformed or `gh` is missing or fails
       def states(commit:, names:)
-        reported = check_runs(valid_sha(commit)).group_by { |run| run["name"] }
+        reported = check_runs(valid_sha(commit)).select { |run| actions?(run) }.group_by { |run| run["name"] }
         latest = reported.transform_values { |runs| runs.max_by { |run| run["id"].to_i } }
         names.to_h { |name| [name, state_of(latest[name])] }
       end
 
       private
 
+      def actions?(run) = run.dig("app", "id") == GITHUB_ACTIONS_APP_ID
+
       def valid_sha(commit)
         sha = sha_of(commit)
         raise "not a commit sha: #{sha.inspect}" unless sha.match?(SHA_PATTERN)

data/lib/hecks/quality_control/cli/qa_sweep/dials.rb

@@ -41,6 +41,7 @@ module Hecks
           @guided_generation = dial(:GUIDED_GENERATION, false)
           @corpus_splice_probability = dial(:CORPUS_SPLICE_PROBABILITY, 0.5)
           @favor_rare_verbs = dial(:FAVOR_RARE_VERBS, 3)
+          @runtime_coverage_feedback = dial(:RUNTIME_COVERAGE_FEEDBACK, false)
         end
 
         def read_limit_dials

data/lib/hecks/quality_control/cli/qa_sweep/seed_loop.rb

@@ -57,8 +57,8 @@ module Hecks
         # @return [Hash, nil] the seed's result with its surprised checks, or nil when every
         #   check held
         def run_seed(seed)
-          result = run_one_seed(@mode, seed)
-          @campaign.record(seed, result[:plan], result[:trace]) if @campaign && result[:trace]
+          result, runtime = measured_seed(seed)
+          @campaign.record(seed, result[:plan], result[:trace], runtime: runtime) if @campaign && result[:trace]
 
           surprised = log_seed_checks(result)
           if surprised.empty?
@@ -70,6 +70,14 @@ module Hecks
           result.merge(seed: seed, checks: surprised)
         end
 
+        # The seed's result, and the runtime lines and branches it reached when the dial asks for
+        # that feedback; nil otherwise, so a campaign falls back to tuples alone.
+        def measured_seed(seed)
+          return [run_one_seed(@mode, seed), nil] unless @campaign && @runtime_coverage_feedback
+
+          Hecks::Fuzzing::RuntimeCoverage.measure { run_one_seed(@mode, seed) }
+        end
+
         def check_modes(checks)
           checks.map { |c| c[:mode] }.join(", ")
         end

data/lib/hecks/rust_build/native_build.rb

@@ -12,6 +12,9 @@ module Hecks
     # so a built binary is cached per `[rust_dir, feature, sources]`, where `sources` is a digest of
     # the workspace's Rust sources and manifests. Regenerating the domain changes the digest, so the
     # next call rebuilds instead of answering with a stale binary or a stale failure.
+    #
+    # A binary already pinned and newer than every source is used as it is, so binaries restored
+    # from a cache of an earlier run are not built again.
     module NativeBuild
       # Raised when a declared feature fails to build; nil is reserved for "feature not declared".
       class BuildFailed < StandardError; end
@@ -94,12 +97,37 @@ module Hecks
 
         File.open(lock_path, File::CREAT | File::RDWR) do |lock|
           lock.flock(File::LOCK_EX)
+          pinned = pinned_path(rust_dir, domain_feature)
+          next pinned if pinned_fresh?(pinned, rust_dir)
+
           command = ["cargo", "build", "--no-default-features", "--features", domain_feature]
           cargo(command, rust_dir, domain_feature)
           pin(rust_dir, domain_feature, command)
         end
       end
 
+      def pinned_path(rust_dir, domain_feature)
+        File.join(rust_dir, "target", "debug", "rust-#{domain_feature}")
+      end
+
+      # A binary pinned ahead of time, by an earlier run whose build was restored from a cache, is
+      # current when no source is newer than it: the rule `make` applies to any target.
+      #
+      # @return [Boolean] whether `pinned` exists and every source predates it
+      def pinned_fresh?(pinned, rust_dir)
+        return false unless File.executable?(pinned)
+
+        built = File.mtime(pinned)
+        source_files(rust_dir).none? { |path| File.mtime(path) > built }
+      end
+
+      # @return [Array<String>] every `.rs` and `.toml` file and `Cargo.lock` outside `target/`
+      def source_files(rust_dir)
+        paths = Dir.glob(File.join(rust_dir, "**", "*.{rs,toml}"), File::FNM_DOTMATCH)
+        paths << File.join(rust_dir, "Cargo.lock")
+        paths.select { |path| File.file?(path) && !path.delete_prefix("#{rust_dir}/").start_with?("target/") }
+      end
+
       def cargo(command, rust_dir, domain_feature)
         _stdout, stderr, status = Open3.capture3(*command, chdir: rust_dir)
         return if status.success?
@@ -118,7 +146,7 @@ module Hecks
           raise BuildFailed, "`#{command.join(" ")}` succeeded in #{rust_dir} but left no executable at #{binary}"
         end
 
-        pinned = File.join(rust_dir, "target", "debug", "rust-#{domain_feature}")
+        pinned = pinned_path(rust_dir, domain_feature)
         FileUtils.cp(binary, pinned)
         File.chmod(0o755, pinned)
         pinned

data/lib/hecks/rust_build/wasm.rb

@@ -15,10 +15,15 @@ module Hecks
     # `wasmtime run rust/dist/<domain>.wasm < script.json`, and the domain's `ir.json` beside it,
     # which `rust/host` reads at runtime. `HECKS_RUST_DIR` names the workspace to build in and
     # `CARGO_TARGET_DIR` where build output goes, beside the workspace by default.
+    # `HECKS_WASM_PROFILE=dev` builds without `--release`: a much faster compile, for tests that
+    # only run the module, not for one that ships.
     module Wasm
       # The Cargo target the module is built for.
       TARGET = "wasm32-wasip1"
 
+      # The Cargo flags and the `target/<target>/` directory of each build profile.
+      PROFILES = { "release" => { flags: ["--release"], dir: "release" }, "dev" => { flags: [], dir: "debug" } }.freeze
+
       module_function
 
       # @param argv [Array<String>] the domain's directory
@@ -83,18 +88,26 @@ module Hecks
       # `rustup run`, not bare `cargo`: a `cargo` earlier on PATH may never have seen
       # `rustup target add` and fail with "can't find crate for `std`".
       def compile(scratch)
-        puts "== cargo build --release --target #{TARGET} =="
+        flags = profile.fetch(:flags)
+        puts "== cargo build #{flags.join(" ")} --target #{TARGET} =="
         target_dir = ENV.fetch("CARGO_TARGET_DIR", File.join(RustBuild.rust_dir, "target"))
-        RustBuild.command!("rustup", "run", "stable", "cargo", "build", "--release", "--target", TARGET,
+        RustBuild.command!("rustup", "run", "stable", "cargo", "build", *flags, "--target", TARGET,
                            chdir: scratch, env: { "CARGO_TARGET_DIR" => target_dir })
       end
 
+      # @return [Hash] the flags and directory of the profile `HECKS_WASM_PROFILE` names
+      # @raise [Failure] when the name is not `release` or `dev`
+      def profile
+        name = ENV.fetch("HECKS_WASM_PROFILE", "release")
+        PROFILES.fetch(name) { raise Failure, "HECKS_WASM_PROFILE=#{name} is not release or dev" }
+      end
+
       def publish(scratch, rust_dir, name)
         dist = File.join(rust_dir, "dist")
         FileUtils.mkdir_p(dist)
         target_dir = ENV.fetch("CARGO_TARGET_DIR", File.join(rust_dir, "target"))
         out = File.join(dist, "#{name}.wasm")
-        FileUtils.cp(File.join(target_dir, TARGET, "release", "rust.wasm"), out)
+        FileUtils.cp(File.join(target_dir, TARGET, profile.fetch(:dir), "rust.wasm"), out)
         puts "wrote #{out}"
         puts %(run it: wasmtime run #{out} < script.json)
         publish_sidecar(scratch, dist, name)

data/lib/hecks/tools/deploy_recipe/generation.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+require_relative "targets"
+
+module Hecks
+  module Tools
+    module DeployRecipe
+      # Writing the recipe for each `deployed_to` block a world declares: a client may declare
+      # several deploy kinds (Vercel beside AwsBox), and each is generated, none locked out.
+      module Generation
+        # @param deployment [Deployment] what the generator resolved about the domain
+        # @param root [String] the checkout
+        # @return [String] `--out`, else `deploy/<name>` in the checkout
+        def output_dir(deployment, root)
+          out = deployment.options.out
+          out ? File.expand_path(out) : File.join(root, "deploy", deployment.infra_name)
+        end
+
+        # One declared target, written straight into `out_dir` as it always was.
+        #
+        # @param block [Hash, nil] the target's settings; nil takes the world's plain `deployed_to`
+        # @return [Integer] 0
+        def generate_one(deployment, root, out_dir, block = nil)
+          emit(block ? for_target(deployment, block) : deployment, root, out_dir)
+          0
+        end
+
+        # Several declared targets, each under its own `out_dir/<adapter>` so their `Makefile`s and
+        # scripts do not collide.
+        #
+        # @return [Integer] 0
+        def generate_each(deployment, root, out_dir, blocks)
+          blocks.each do |block|
+            emit(for_target(deployment, block), root, File.join(out_dir, block[:adapter].downcase))
+          end
+          0
+        end
+
+        # @param view [Deployment] the deployment as one target sees it
+        # @return [void] writes the files the target projects into `out_dir`
+        def emit(view, root, out_dir)
+          write(project(target_key(view.settings, view.world_file, view.domain), view, root), out_dir)
+        end
+
+        # @param block [Hash] one declared `deployed_to` block
+        # @return [Deployment] the deployment as that target sees it: its settings, name and world
+        def for_target(deployment, block)
+          settings = tenant_settings(block, deployment.options, File.basename(deployment.domain))
+          deployment.dup.tap do |view|
+            view.world = Targets::TargetWorld.new(deployment.world, block)
+            view.settings = settings
+            view.infra_name = settings[:stack_name] || File.basename(deployment.domain)
+          end
+        end
+      end
+    end
+  end
+end