hecks 3.4.1 → 3.5.0

data/lib/hecks/projections/site/site_host/templates.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hecks
+  module Projections
+    module Site
+      module SiteHost
+        # The text of the two files, written as the file a project would write by hand.
+        module Templates
+          BANNER = "Generated by hecks site site_projection.project_site. Do not edit."
+
+          module_function
+
+          # @param cms [Hash{Symbol => Object}] the checked `Cms` row
+          # @return [String] the image's build file
+          def dockerfile(cms)
+            format(DOCKERFILE, banner: BANNER, node: cms[:node], port: cms[:port], heap: cms[:heap_mb])
+          end
+
+          # @param secrets [Array<Hash{Symbol => Object}>] the checked `BootSecret` rows
+          # @return [String] the start-up script
+          def boot(secrets)
+            ["// #{BANNER}", BOOT_HEAD, *secrets.map { |secret| extra(secret) }, BOOT_TAIL].join("\n\n") << "\n"
+          end
+
+          def extra(secret)
+            from = JSON.generate(secret[:from])
+            env = JSON.generate(secret[:env])
+            return field_secret(from, env, JSON.generate(secret[:field])) if secret[:field]
+
+            whole_secret(secret, from, env)
+          end
+
+          def field_secret(from, env, field)
+            <<~JS.chomp
+              if (process.env[#{from}]) {
+                process.env[#{env}] = await secretField(process.env[#{from}], #{field});
+              }
+            JS
+          end
+
+          def whole_secret(secret, from, env)
+            <<~JS.chomp
+              // #{secret[:env]} is the whole of the secret named by #{secret[:from]}. Optional and non-fatal.
+              if (process.env[#{from}] && !process.env[#{env}]) {
+                try {
+                  const { SecretString } = await client.send(new GetSecretValueCommand({ SecretId: process.env[#{from}] }));
+                  if (SecretString) process.env[#{env}] = SecretString;
+                } catch (err) {
+                  console.warn(`boot: could not read #{secret[:from]}: ${err instanceof Error ? err.message : err}`);
+                }
+              }
+            JS
+          end
+
+          BOOT_HEAD = <<~JS.chomp
+            // Cold-start bootstrap: resolve the secrets, then start Next.
+            //
+            // The database password and the signing secret are fetched from Secrets Manager here, in the
+            // process, and composed into the environment keys payload.config.ts reads (DATABASE_URL,
+            // PAYLOAD_SECRET), so neither is ever a plaintext environment variable of the task. A
+            // DATABASE_URL / PAYLOAD_SECRET already in the environment is used when the *_ARN variables are
+            // absent: a person running this file locally.
+            import { SecretsManagerClient, GetSecretValueCommand } from "@aws-sdk/client-secrets-manager";
+
+            const client = new SecretsManagerClient({});
+
+            async function secretField(arn, field) {
+              const { SecretString } = await client.send(new GetSecretValueCommand({ SecretId: arn }));
+              const value = JSON.parse(SecretString)[field];
+              if (!value) throw new Error(`secret ${arn} has no "${field}" field`);
+              return value;
+            }
+
+            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 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}`;
+            } else if (!process.env.DATABASE_URL) {
+              throw new Error("either DB_SECRET_ARN (+ DB_HOST/DB_NAME) or DATABASE_URL is required");
+            }
+
+            if (process.env.PAYLOAD_SECRET_ARN) {
+              process.env.PAYLOAD_SECRET = await secretField(process.env.PAYLOAD_SECRET_ARN, "secret");
+            } else if (!process.env.PAYLOAD_SECRET) {
+              throw new Error("either PAYLOAD_SECRET_ARN or PAYLOAD_SECRET is required");
+            }
+          JS
+
+          BOOT_TAIL = <<~JS.chomp
+            // Next's standalone server starts listening on import (PORT and HOSTNAME come from the environment).
+            await import("./server.js");
+          JS
+
+          DOCKERFILE = <<~'DOCKER'
+            # %<banner>s
+            #
+            # The content system (Payload on Next's standalone server) as a container. Build from this
+            # directory. deploy-aws/boot.mjs resolves the secrets named by the *_ARN variables into
+            # DATABASE_URL and PAYLOAD_SECRET before it starts the server, so nothing here is a secret.
+            #
+            # Runtime environment, supplied by the task definition:
+            #   NODE_ENV=production, USE_POSTGRES=true, USE_S3_STORAGE=true, S3_MEDIA_BUCKET
+            #   DB_HOST, DB_NAME, DB_SECRET_ARN, PAYLOAD_SECRET_ARN, CORS_ORIGINS, AWS_REGION
+
+            # ---- build stage ----
+            FROM node:%<node>s-slim AS build
+            WORKDIR /app
+
+            # A lockfile written on macOS omits the Linux entries of optional native packages
+            # (sharp), and `next build` then fails deep inside page-data collection. Write it on the
+            # image's own platform: remove node_modules and package-lock.json and run npm install.
+            COPY package.json package-lock.json ./
+            RUN npm ci
+
+            COPY . .
+            # payload-types.ts is generated and untracked, so a clean checkout has none and the type check
+            # inside `next build` would see untyped results. Generating it only loads the config
+            # (no database); the values are placeholders and the flags are the ones production boots with.
+            RUN USE_POSTGRES=true USE_S3_STORAGE=true PAYLOAD_SECRET=build-only \
+                S3_MEDIA_BUCKET=build-only AWS_REGION=us-east-1 DATABASE_URL=postgres://build-only/build-only \
+                npm run generate:types
+            RUN npm run build
+
+            # ---- runtime stage ----
+            FROM node:%<node>s-slim
+            WORKDIR /app
+            ENV NODE_ENV=production
+            # The task is shared with sibling containers; without a cap Node sizes its heap from the whole task.
+            ENV NODE_OPTIONS=--max-old-space-size=%<heap>d
+
+            # Next's standalone output holds a minimal server.js and its traced node_modules; the static
+            # files are not part of it and are copied separately.
+            COPY --from=build /app/.next/standalone/ ./
+            COPY --from=build /app/.next/static ./.next/static
+
+            COPY deploy-aws/boot.mjs ./
+            # RDS enforces TLS; boot.mjs verifies against Amazon's CA bundle.
+            ADD https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem ./rds-global-bundle.pem
+
+            # boot.mjs sits outside the Next app, so `next build` does not trace its import of the AWS SDK.
+            COPY --from=build /app/node_modules/@aws-sdk ./node_modules/@aws-sdk
+            COPY --from=build /app/node_modules/@smithy ./node_modules/@smithy
+            COPY --from=build /app/node_modules/tslib ./node_modules/tslib
+
+            # Next's standalone server reads HOSTNAME for its bind address.
+            ENV HOSTNAME=0.0.0.0
+            ENV PORT=%<port>d
+            EXPOSE %<port>d
+
+            # Nothing writes to /app at runtime (media goes to S3), so no root.
+            USER node
+            CMD ["node", "boot.mjs"]
+          DOCKER
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../../projector"
+require_relative "root_rows"
+require_relative "site_host/templates"
+
+module Hecks
+  module Projections
+    module Site
+      # The content system's container image and its start-up script, from rows beside the route
+      # table: `cms/Dockerfile` and `cms/deploy-aws/boot.mjs`.
+      #
+      # The script resolves the content system's secrets before it starts the server: the database
+      # password and the signing secret always, and any further secret a `BootSecret` row names.
+      # Each is
+      # fetched from Secrets Manager in the process, so none is ever a plaintext environment
+      # variable of
+      # the task. The image is a plain two-stage build of a Next standalone server that runs the
+      # script.
+      module SiteHost
+        extend Projector::Target
+
+        projects_as :site_host, emits: :files
+
+        # The `Cms` row: where the content system lives and how its image is built.
+        CMS = RootRows.new("Cms", fields:   { dir: String, node: String, port: Integer, heap_mb: Integer,
+                                             dockerfile: [TrueClass, FalseClass] },
+                                  defaults: { dir: "cms", node: "22", port: 8080, heap_mb: 1024, dockerfile: true })
+
+        # A `BootSecret` row: an environment variable filled from a secret whose id the variable
+        # `from`
+        # holds. With `field` the secret is JSON and that field is the value, required once the
+        # secret
+        # is named; without it the whole secret is the value and failing to read it only warns.
+        BOOT_SECRETS = RootRows.new("BootSecret", fields: { env: String, from: String, field: String },
+                                                  required: %i[env from], many: true)
+
+        module_function
+
+        # @param bluebook [Bluebook::Chapter] the chapter that declares the route table
+        # @param options [Hash{Symbol => Object}] unused
+        # @return [Hash{String => String}] each file's path relative to the project root to its
+        #   text;
+        #   empty when the project declares no `Cms` row
+        # @raise [Table::Invalid] when a row is refused
+        def call(bluebook:, options: {})
+          cms = CMS.read(bluebook).first
+          return {} unless cms
+
+          files = { "#{cms[:dir]}/deploy-aws/boot.mjs" => Templates.boot(BOOT_SECRETS.read(bluebook)) }
+          files["#{cms[:dir]}/Dockerfile"] = Templates.dockerfile(cms) if cms[:dockerfile]
+          files
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require_relative "../../projector"
+require_relative "root_rows"
+
+module Hecks
+  module Projections
+    module Site
+      # The files at a project's root that are written from rows beside its route table: the
+      # local-stack settings template (`.env.tpl`, from `Secrets` and `Env` rows) and the workflow
+      # that
+      # keeps the generated files current (`.github/workflows/site-routes.yml`, from a `Ci` row).
+      #
+      # Each file is written only when its rows are declared. Settings that are secrets are
+      # references
+      # into 1Password, never values, so nothing secret is written to disk.
+      module SiteRoot
+        extend Projector::Target
+
+        projects_as :site_root, emits: :files
+
+        # The `Secrets` row: where the secrets live and what starts the stack.
+        SECRETS = RootRows.new("Secrets", fields:   { vault: String, item: String, section: String, launcher: String },
+                                          required: %i[vault item])
+
+        # An `Env` row: a plain setting when it carries `value`, a secret reference when it does
+        # not. `group` heads the rows from it on with a comment; `off` comments the line out.
+        ENV_ROWS = RootRows.new("Env", required: %i[name], many: true,
+                                       fields: { name: String, value: [String, Integer, TrueClass, FalseClass], group: String,
+                                                off: [TrueClass, FalseClass] })
+
+        # The `Ci` row: the workflow that checks the generated files.
+        CI = RootRows.new("Ci", fields:   { name: String, ruby: String, node: String, gem_dir: String, script: String,
+                                          test: String, paths: String, install: String },
+                                required: %i[gem_dir],
+                                defaults: { name: "Site routes", ruby: "3.3", node: "22", script: "bin/site_routes",
+                                            test: "npm test", paths: "", install: "npm ci" })
+
+        # The workflow's path and the steps' action pins, which a project does not choose.
+        WORKFLOW = ".github/workflows/site-routes.yml"
+        BANNER = "# Generated by hecks site site_projection.project_site. Do not edit."
+
+        module_function
+
+        # @param bluebook [Bluebook::Chapter] the chapter that declares the route table
+        # @param options [Hash{Symbol => Object}] unused
+        # @return [Hash{String => String}] each file's path relative to the project root to its
+        #   text;
+        #   empty when the project declares no such rows
+        # @raise [Table::Invalid] when a row is refused
+        def call(bluebook:, options: {})
+          files = {}
+          env = env_template(bluebook)
+          files[".env.tpl"] = env if env
+          ci = CI.read(bluebook).first
+          files[WORKFLOW] = workflow(ci) if ci
+          files
+        end
+
+        # @return [String, nil] the template, or nil with no `Env` rows
+        def env_template(chapter)
+          vars = ENV_ROWS.read(chapter)
+          return nil if vars.empty?
+
+          secrets = SECRETS.read(chapter).first
+          if secrets.nil? && vars.any? { |var| !var.key?(:value) }
+            raise Table::Invalid, "Env rows without a value are secrets; the project declares no Secrets row"
+          end
+
+          [BANNER, *header(secrets), *body(vars, secrets)].join("\n") << "\n"
+        end
+
+        def header(secrets)
+          return [] unless secrets
+
+          where = ["vault \"#{secrets[:vault]}\"", "item \"#{secrets[:item]}\"",
+                   *(secrets[:section] ? ["section \"#{secrets[:section]}\""] : [])].join(", ")
+          starter = secrets[:launcher] ? " (#{secrets[:launcher]} does this)" : ""
+          ["# Local-stack settings. Secrets are op:// references into 1Password (#{where}),",
+           "# resolved at start-up by `op run --env-file=.env.tpl -- <command>`#{starter};",
+           "# no secret is ever written to disk. The plain lines are not secret."]
+        end
+
+        def body(vars, secrets)
+          group = nil
+          vars.flat_map do |var|
+            heading = var[:group] && var[:group] != group ? ["", "# #{var[:group]}"] : []
+            group = var[:group] if var[:group]
+            [*heading, line(var, secrets)]
+          end
+        end
+
+        def line(var, secrets)
+          text = "#{var[:name]}=#{var.key?(:value) ? var[:value] : reference(var, secrets)}"
+          var[:off] ? "# #{text}" : text
+        end
+
+        def reference(var, secrets)
+          "op://#{[secrets[:vault], secrets[:item], secrets[:section], var[:name]].compact.join('/')}"
+        end
+
+        # @param row [Hash{Symbol => Object}] the checked `Ci` row
+        # @return [String] the workflow
+        def workflow(row)
+          paths = path_list(row).map { |path| "      - #{path.to_s.inspect}" }.join("\n")
+          format(WORKFLOW_TEXT, banner: BANNER, name: row[:name], paths: paths, ruby: row[:ruby].inspect,
+                                node: row[:node].inspect, gem_dir: row[:gem_dir], script: row[:script], test: row[:test],
+                                install_steps: install_steps(row[:install]))
+        end
+
+        # The steps that install the project's dependencies; a project that installs with yarn gets
+        # corepack enabled first, so the version it pins is the one that runs.
+        def install_steps(install)
+          steps = []
+          steps << "- name: Enable corepack\n        run: corepack enable" if install.start_with?("yarn")
+          steps << "- name: Install dependencies\n        run: #{install}"
+          steps.join("\n\n      ")
+        end
+
+        def path_list(row)
+          listed = row[:paths].split(",").map(&:strip).reject(&:empty?)
+          [*listed, row[:script], "#{row[:gem_dir]}/Gemfile.lock", WORKFLOW].uniq
+        end
+
+        WORKFLOW_TEXT = <<~YAML
+          %<banner>s
+          # Two checks, neither needing AWS or a database:
+          #
+          #   1. the generated files are current: `%<script>s --check` regenerates them with the hecks
+          #      gem the Gemfile.lock pins and exits 1, naming each file, if a row was edited without
+          #      regenerating or a generated file was hand-edited;
+          #   2. `%<test>s`, which holds the generated code to what the hand-written code does.
+          name: %<name>s
+
+          on:
+            push:
+              branches: [main]
+              paths:
+          %<paths>s
+            pull_request:
+              paths:
+          %<paths>s
+            # Lets a GitHub merge queue run this check on each queued PR (paths do not apply to merge_group).
+            merge_group:
+            workflow_dispatch: {}
+
+          permissions:
+            contents: read
+
+          jobs:
+            routes-current-and-parity:
+              runs-on: ubuntu-24.04
+              timeout-minutes: 15
+
+              steps:
+                - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+                - uses: ruby/setup-ruby@14594264cd68ce8a2345dd349bc3d138a4ef85c8 # v1
+                  with:
+                    ruby-version: %<ruby>s
+                    bundler-cache: true
+                    working-directory: %<gem_dir>s
+
+                - name: The generated files are current
+                  run: %<script>s --check
+
+                - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+                  with:
+                    node-version: %<node>s
+
+                %<install_steps>s
+
+                - name: Parity between the generated code and the hand-written code
+                  run: %<test>s
+        YAML
+      end
+    end
+  end
+end

data/lib/hecks/runtime/value.rb

@@ -47,6 +47,13 @@ module Hecks
       # @param field [String, Symbol] the field name; `:value` resolves the same way `[]` does
       # @return [Boolean] true when the field is held
       def key?(field) = @fields.key?(resolve_field(field))
+
+      # Reads the held fields as they are stored, without materializing nested values.
+      #
+      # @return [Hash{Symbol => Object}] the frozen, Symbol-keyed field Hash, in storage order;
+      #   a nested `Runtime::Value` stays a `Runtime::Value`
+      def raw_fields = @fields
+
       def to_h = @fields.transform_values { |value| self.class.materialize(value) }
 
       # Renders this value object as JSON, through the same shape `to_h` builds.

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

@@ -99,6 +99,8 @@ Hecks.bluebook "Site" do
     attribute :run,       RunKey
     attribute :out,       Location,  optional: true
     attribute :template,  Location,  optional: true
+    attribute :cms,       Location,  optional: true
+    attribute :root,      Location,  optional: true
     attribute :extension, Extension, optional: true
     attribute :check,     Switch,    optional: true
     attribute :live,      Location,  optional: true
@@ -162,7 +164,7 @@ Hecks.bluebook "Site" do
       transition "Fault"    => "faulted",   from: "requested"
     end
 
-    # `hecks site site_projection.project_site <project> [out=<dir>] [template=<file>] [extension=ts|mts] [--check]`.
+    # `hecks site site_projection.project_site <project> [out=<dir>] [template=<file>] [cms=<dir>] [root=<dir>] [extension=ts|mts] [--check]`.
     # With `check` nothing is written: a routes.ts that differs from the table is faulted, naming the
     # file, so a CI job fails on drift.
     command "ProjectSite" do
@@ -172,6 +174,8 @@ Hecks.bluebook "Site" do
       attribute :run,       RunKey
       attribute :out,       Location,  optional: true
       attribute :template,  Location,  optional: true
+      attribute :cms,       Location,  optional: true
+      attribute :root,      Location,  optional: true
       attribute :extension, Extension, optional: true
       attribute :check,     Switch,    optional: true
 
@@ -179,6 +183,8 @@ Hecks.bluebook "Site" do
       sets :run
       sets :out
       sets :template
+      sets :cms
+      sets :root
       sets :extension
       sets :check
 
@@ -186,14 +192,18 @@ Hecks.bluebook "Site" do
     end
 
     # `hecks site site_projection.check_live <project> live=<saved-config.json> | distribution=<id>
-    # [expect_new=<paths>] [refs=<!Ref Name=id,...>]`. Compares the project's generated CloudFront
+    # [template=<file>] [expect_new=<paths>] [refs=<!Ref Name=id,...>]`. Compares the project's generated CloudFront
     # behaviours with a live distribution's, changing neither. `live` is a saved answer of
     # `aws cloudfront get-distribution-config`; `distribution` fetches it with that one read-only call.
+    # `template` stands in for the `Edge` row's `template:` as it does for `project_site`; the check
+    # reads no template, so the file need not exist. It prints the report alone and exits 1 on a
+    # difference.
     command "CheckLive" do
       goal "Compare a project's generated CloudFront behaviours with a live distribution's"
 
       attribute :domain,       DomainPath
       attribute :run,          RunKey
+      attribute :template,     Location,       optional: true
       attribute :live,         Location,       optional: true
       attribute :distribution, DistributionId, optional: true
       attribute :expect_new,   PathList,       optional: true
@@ -205,6 +215,7 @@ Hecks.bluebook "Site" do
 
       sets :domain
       sets :run
+      sets :template
       sets :live
       sets :distribution
       sets :expect_new

data/lib/hecks/tools/site_routes.rb

@@ -7,15 +7,21 @@ require_relative "../tools"
 require_relative "../projections/site/routes_ts"
 require_relative "../projections/site/site_cdn"
 require_relative "../projections/site/regions"
+require_relative "../projections/site/admin"
+require_relative "../projections/site/site_admin"
+require_relative "../projections/site/admin_cms"
+require_relative "../projections/site/site_root"
+require_relative "../projections/site/site_host"
+require_relative "../projections/site/payload_driver"
 
 module Hecks
   module Tools
-    # Projects a project's route table into `routes.ts` (`Projections::Site::RoutesTs`) and, when
-    # it declares an edge, into the behaviours and listener rules of its template
-    # (`Projections::Site::SiteCdn`).
+    # Projects a project's route table into `routes.ts` (`Projections::Site::RoutesTs`), its edge
+    # into the behaviours and listener rules of its template (`Projections::Site::SiteCdn`) and its
+    # `Admin` row into `admin.ts` (`Projections::Site::SiteAdmin`), each when it declares one.
     #
     #   hecks site site_projection.project_site [<project>] [--out=<dir>] [--template=<file>]
-    #                                           [--extension=ts|mts] [--check]
+    #       [--cms=<dir>] [--root=<dir>] [--extension=ts|mts] [--check]
     #
     # `<project>` (default: the working directory) holds `bluebook/` and the `vendor/` it attaches
     # from. `routes.ts` goes to `<project>/generated` or to `--out`, anywhere. The template is the
@@ -30,7 +36,7 @@ module Hecks
       EXTENSIONS = %w[ts mts].freeze
 
       USAGE = "usage: hecks site site_projection.project_site [<project>] [--out=<dir>] " \
-              "[--template=<file>] [--extension=#{EXTENSIONS.join('|')}] [--check]".freeze
+              "[--template=<file>] [--cms=<dir>] [--root=<dir>] [--extension=#{EXTENSIONS.join('|')}] [--check]".freeze
 
       module_function
 
@@ -43,18 +49,20 @@ module Hecks
       #   table is refused, or a flag is refused
       def main(argv, root: Dir.pwd)
         argv = argv.dup
-        out = template = extension = nil
+        out = template = extension = cms = root_dir = nil
         check = false
         OptionParser.new do |parser|
           parser.on("--out=DIR") { |value| out = value }
           parser.on("--template=FILE") { |value| template = value }
+          parser.on("--cms=DIR") { |value| cms = value }
+          parser.on("--root=DIR") { |value| root_dir = value }
           parser.on("--extension=EXT") { |value| extension = value }
           parser.on("--check") { check = true }
         end.parse!(argv)
         project = argv.empty? ? root : File.expand_path(argv.shift)
         abort USAGE unless argv.empty?
 
-        files = projection(project, out: out, template: template, extension: extension)
+        files = projection(project, out: out, template: template, extension: extension, cms: cms, root_dir: root_dir)
         stale = files.reject { |path, text| File.file?(path) && File.read(path) == text }.keys
         return report(stale, project, check) if check
 
@@ -75,7 +83,7 @@ module Hecks
       # @return [Hash{String => String}] each file's absolute path to the text it should hold
       # @raise [SystemExit] when the project declares no route table, the table is refused, or a
       #   path or the extension is refused
-      def projection(root, out: nil, template: nil, extension: nil)
+      def projection(root, out: nil, template: nil, extension: nil, cms: nil, root_dir: nil)
         extension ||= EXTENSIONS.first
         unless EXTENSIONS.include?(extension)
           abort "project_site: --extension is one of #{EXTENSIONS.join(', ')}, not #{extension.inspect}"
@@ -88,11 +96,73 @@ module Hecks
         table = Projections::Site::Table.read(chapter, registry: registry)
         files = Projector.call(:site_routes_ts, bluebook: chapter, options: { table: table })
         written = files.to_h { |name, text| [File.join(dir, name.sub(/\.ts\z/, ".#{extension}")), text] }
+        admin = Projections::Site::Admin.read(chapter, table: table)
+        written.merge!(admin_files(dir, chapter, admin, extension))
+        written.merge!(cms_files(cms, chapter, admin)) if cms
+        written.merge!(root_files(root_dir, chapter)) if root_dir
         written.merge(template_files(root, out, chapter, table, registry, template: template))
       rescue Projections::Site::Table::Invalid => e
         abort "project_site: #{e.message}"
       end
 
+      # The admin sign-in module, when the project declares an `Admin` row.
+      #
+      # @param dir [String] the directory the route table module is written to
+      # @param chapter [Bluebook::Chapter] the chapter that declares the route table
+      # @param admin [Projections::Site::Admin, nil] the checked admin row
+      # @param extension [String] the extension the modules are written with
+      # @return [Hash{String => String}] the module's path to its text; empty with no admin row
+      def admin_files(dir, chapter, admin, extension)
+        files = Projector.call(:site_admin, bluebook: chapter, options: { admin: admin, extension: extension })
+        files.to_h { |name, text| [File.join(dir, name.sub(/\.ts\z/, ".#{extension}")), text] }
+      end
+
+      # The files at the project's root that its rows write: the settings template, the workflow,
+      # the
+      # content system's image and start-up script, and the files that drive the domain.
+      #
+      # @param dir [String] the directory they are written under, relative to the working directory
+      # @param chapter [Bluebook::Chapter] the chapter that declares the route table
+      # @return [Hash{String => String}] each file's absolute path to its text; empty with no rows
+      def root_files(dir, chapter)
+        base = File.expand_path(dir)
+        files = Projector.call(:site_root, bluebook: chapter).merge(Projector.call(:site_host, bluebook: chapter))
+        files = files.merge(payload_files(base, chapter))
+        files.to_h { |name, text| [File.join(base, name), text] }
+      end
+
+      # The files that drive the project's domain from the content system, when it declares a
+      # `Payload` row.
+      #
+      # @param base [String] the directory the project's root files are written under
+      # @param chapter [Bluebook::Chapter] the chapter that declares the route table and the rows
+      # @return [Hash{String => String}] each file's path relative to `base` to its text
+      def payload_files(base, chapter)
+        row = Projections::Site::PayloadDriver::PAYLOAD.read(chapter).first
+        return {} unless row
+
+        domain_root = File.join(base, row[:domain])
+        domain = registry_for(domain_root).bluebooks.values.find { |candidate| candidate.name == row[:chapter] }
+        abort "project_site: #{domain_root} declares no chapter #{row[:chapter]}" unless domain
+        Projector.call(:payload_driver, bluebook: chapter, options: { domain_chapter: domain })
+      rescue ArgumentError => e
+        abort "project_site: #{e.message}"
+      end
+
+      # The content system's half of the admin sign-in: four files under the `--cms` directory.
+      #
+      # @param cms [String] the directory the files are written under
+      # @param chapter [Bluebook::Chapter] the chapter that declares the route table
+      # @param admin [Projections::Site::Admin, nil] the checked admin row
+      # @return [Hash{String => String}] each file's absolute path to its text
+      # @raise [SystemExit] when `--cms` is named and the project declares no `Admin` row
+      def cms_files(cms, chapter, admin)
+        abort "project_site: --cms names #{cms}, but the project declares no Admin row" if admin.nil?
+
+        files = Projector.call(:site_admin_cms, bluebook: chapter, options: { admin: admin })
+        files.to_h { |name, text| [File.join(File.expand_path(cms), name), text] }
+      end
+
       # The template with the edge's regions rewritten, when the project declares an edge.
       #
       # @param root [String] the project directory

data/lib/hecks/version.rb

@@ -1,5 +1,5 @@
 module Hecks
   # Read directly by the gemspec, so this file must never require the
   # rest of the gem (its dependencies aren't resolved yet at that point).
-  VERSION = "3.4.1".freeze
+  VERSION = "3.5.0".freeze
 end

data/rust/host/HECKS_RELEASE

@@ -1 +1 @@
-3.4.1
+3.5.0