Andreas Heige

· 8 min · harness engineering, guardrails

How this site works, part 3: deploy and guards

Cloudflare builds and deploys every push, and the build runs the type checks, lint and tests before anything else. A few more checks are written into the build itself.

Contents · 5 sections

Abstract

Part 3 of a guided tour of andreasheige.cc: how a push becomes a deploy through Cloudflare Workers Builds and wrangler.jsonc, how the build writes a strict Content Security Policy from hashes of its own output, why the tests now run inside the build and what the local gate still adds, and what Lighthouse is and is not used for.

Part 1 built dist/ from one data API. Part 2 added the islands and the one Worker route. This part is the last clause of the home page’s opening line, “the harness that lets them work on their own”: what decides that a change is allowed to reach andreasheige.cc, and what the site carries with it once it is there.

A push is a deploy

Production is a Cloudflare Worker named blog. Cloudflare Workers Builds is connected to the repository. On every push it installs the dependencies, runs npm run build, then npx wrangler deploy. A push to main is production; other branches get preview builds, which show up on a pull request as the “Workers Builds: blog” check. Those two commands live in the Cloudflare dashboard, not in the repo.

What the deploy does is in wrangler.jsonc:

  "name": "blog",
  // POST /api/ask (v4.1 §5): the only path the Worker sees; everything else
  // is still served straight from dist/ as static assets.
  "main": "src/worker.ts",
  "compatibility_date": "2026-11-01",
  "assets": {
    "directory": "./dist",
    "not_found_handling": "404-page",
    // The Worker reads dist/search-index.json through this binding to pick the passages.
    "binding": "ASSETS",
    "run_worker_first": ["/api/ask"]
  },

The comment’s “the only path the Worker sees” is the intent; in practice a fetch or POST to a path no file matches can also reach the Worker, which answers it with a JSON 404.

The file exists because of a failure. The repo root is an npm workspace (Gödels machine lives in apps/godel/), and wrangler’s framework detection refuses to run at a workspace root, so every v4 build failed until a config named the assets folder directly (D74). The old GitHub Actions workflow deployed to a Cloudflare Pages project that no longer existed and had failed on every run since 27 October; it was removed in the same change.

The rest of the file is the Worker’s budget: ASK_LIMITER, 10 requests a minute per caller, and ASK_GLOBAL, 60 model calls a minute for everyone together, counted per Cloudflare location. Part 2 showed where the Worker checks them. The hard stop behind both is the account’s Workers AI quota: on the free plan it ends at 10,000 neurons a day, and Ask falls back to the keyword hits.

A test pins this file as policy rather than as text: the Worker’s name, the assets block, main, the ASSETS and AI bindings, the two rate limits, and nothing else (tests/site/build.test.ts). A new binding cannot slip in without changing a test, and wrangler.jsonc was a change Andreas approved before it was written (D80).

Headers written from the build’s own output

The static files carry their security headers in dist/_headers, which Cloudflare applies as written. The Content Security Policy is strict: scripts and styles from the site’s own origin, plus a list of hashes, and no 'unsafe-inline' for scripts. The hashes can only be known after the build, because Astro inlines small scripts and every page’s CSS. So the last step of astro build is a hook that reads every built page and SVG, hashes every inline script and <style>, and fills them into the template (astro.config.mjs):

      const file = join(root, "_headers");
      writeFileSync(
        file,
        fillHeaders(readFileSync(file, "utf8"), {
          scripts: hashesOf(pages, inlineScripts),
          styles: hashesOf([...pages, ...svgs], inlineStyles),
        }),
      );

fillHeaders refuses the two easiest ways to weaken it (src/lib/csp.ts):

  for (const m of rules.matchAll(/script-src[^;\n]*/g)) {
    if (m[0].includes("'unsafe-inline'"))
      throw new Error("csp: script-src must not allow 'unsafe-inline'");
  }

It also throws when a placeholder is missing and when a header line passes Cloudflare’s 2,000-character limit. Since a throw in the build stops the deploy, a page cannot ship with 'unsafe-inline' in its script policy or without the hashes filled in. That is not a proof that the policy is strong; the template’s other sources are reviewed like any other code. The Worker’s JSON responses do not go through _headers, so they set their own: no-store, nosniff, and default-src 'none'. Gödels machine, which loads a Google Font, gets its own rule with its own policy.

Whether the policy actually holds in a browser is checked by hand: scripts/csp-check.ts serves dist/ with the headers applied, loads every page type and the Gödel app in Chromium, fails on any violation, and checks that the islands still work. A negative control with the hashes removed fails every page.

The gate runs before the build

Workers Builds runs npm run build and then deploys. Until v4.1 that was the build alone: a bad record, a bad figure reference or a weak CSP stopped the deploy, but a failing test did not, because the tests ran only on my machine. That was a bug, not a choice. Now the build runs the checks first, type checking, lint and format with npm run check and both test suites with npm test, so a red test stops the deploy the same way a broken build does.

The local gate came first, and it is a rule rather than a lock. The workflow says every commit is one chained command, npm run build && git commit … (the build runs the check and the tests first), so a red step stops the commit. It is chained because twice during v4 a commit went in after a failing test when the commands ran one after another. The installed pre-commit hook enforces less: it runs Biome only, so a commit made by hand can skip the tests. Before the gate moved into the build, nothing at deploy would have noticed. npm run check is astro check and Biome with warnings as errors. npm test runs both suites; on 8 November 2026 that was 6,080 site tests and 72 for Gödels machine.

The site suite is layered the way the code is:

  • tests/guards/ read the source: no loose strings, tokens only, import boundaries, theme contrast, hidden Unicode. These are the tests behind the principles in part 1.
  • tests/data/, tests/lib/ and tests/components/ test schemas, pure helpers and components rendered through Astro’s container API.
  • tests/dist/ tests the built site. One setup step builds a temporary copy of the repo once per run, so every dist test reads the same output and a test run never touches the real dist/. Islands run there over a stubbed DOM, links are resolved, and the JavaScript budget is enforced (tests/dist/budget.test.ts):
const budgetBytes = 30 * 1024;
  • tests/worker/ runs the Ask handler with fake bindings, plus an adversarial suite written in a fresh context by a tester agent whose job is to break it.

A test pins what something does, not how it is written today: npm run check is proven by planting an explicit any in a temporary copy and watching it fail, not by comparing the script’s text. Each guard also proves itself: it runs on planted violations in memory, so a checker that silently stops finding anything is itself a failure.

Check
npm run check

astro check, then Biome with warnings as errors. An explicit any or a console call fails.

Test
npm test

Guards, data, components, the built site and the Worker. Both suites; either failing stops here.

Commit
git commit

By the workflow rule, chained on npm run build, which runs check and test first; the hook itself runs Biome only.

Push
git push

Main is production: Workers Builds starts from the push.

Gate, then build
npm run build

Workers Builds runs check and test first, then Astro, the CSP hook and Gödels machine. A red test, a bad record or a weak CSP stops the deploy.

Deploy
npx wrangler deploy

dist/ as static assets, the Worker on /api/ask.

Fig. 1 — From a change to production: the gate runs on my machine, and again before Cloudflare builds.

Lighthouse, measured, not gated

scripts/lighthouse.ts runs Lighthouse 13.5.0 against the built site with the headers and compression applied, for the home page, About, a post, a project, the talk and the 404, on the mobile and desktop presets. It exits with an error under 98 (with one narrow, recorded exception for the About portrait’s faint characters, D83, which no longer fires since the shading moved into a CSS mask, D90). It is a manual tool, not a step in the deploy.

In the recorded run of 8 November 2026, after v4.1, every page scored 100 for accessibility, best practices and SEO, and 100 for desktop performance. Mobile performance was 100 for the project, the talk and the 404, 99 for About, and 98 for the home page and the longest post. The home page was 99 on 4 November; it lost the point to the faint TV noise on its title, which is also its largest element. The recorded cause: on Lighthouse’s simulated slow 4G the post loads four font files and two module scripts before its largest element, the italic dek, and more preloads would compete with the page itself. Closing it means fewer font bytes, dropping a weight or the italic, which is a design change, so the 98 stays.

Where this sits on the thread

This post hangs on harness engineering and guardrails. Harness, because this is the step the About page calls “how it’s checked”: rules, gates and code, not a model, deciding what blocks. The build refuses an 'unsafe-inline' script policy, the guards refuse a broken principle, and the chained commit stops on a red test. Guardrails, because they all fail closed, as the Worker’s limiters do in part 2. How the agents that built the site were held to the same gates, and what got past them, is in the companion post; the review loop that checks every ticket is in review-loop, and the server-side floor under it in security-floor.