The source of chock.sh: a static website for chock, a catalog of
policies (guardrails) for AI coding agents. The site lets a visitor browse the policies,
pick the ones they want, and get one chock install --selection command that builds a
Claude Code plugin from their picks on their own machine.
The site is generated by a Python script (sitegen/) from two pinned inputs:
.framework-ref— the chock engine commit (onlysitegen/engine.pyimports chock);.catalog-ref— the chock-catalog commit the pages are built from.
It is plain HTML, CSS and vanilla JavaScript, with no cookies. The only third-party request is
Cloudflare's cookieless Web Analytics beacon, which is skipped when the browser sends Global
Privacy Control or Do Not Track. The one
piece of backend is functions/api/event.js, a Cloudflare Pages Function that counts a few
anonymous actions (see "Site events" below). It is hosted on Cloudflare Pages (see "Deploy"
below); the local server binds 127.0.0.1 only.
python3.12 -m venv .venv && . .venv/bin/activate
pip install --require-hashes -r requirements-dev.txt
pip install --no-deps --no-build-isolation "chock @ git+https://github.com/open-coder-ai/chock@$(cat .framework-ref)"
python scripts/install_engine_deps.py
git clone https://github.com/open-coder-ai/chock-catalog .catalog
git -C .catalog checkout "$(cat .catalog-ref)"
python -m sitegen --catalog .catalog --out dist
python -m http.server 8000 -d dist # open http://localhost:8000
pytest -q # unit tests (build the site themselves)
pytest -q tests/e2e # browser tests (after: python -m playwright install chromium)
ruff check . && ruff format --check .One command to build and serve locally:
python -m sitegen serve --catalog .catalog # builds into dist/, then serves http://127.0.0.1:8000
python -m sitegen serve --catalog .catalog --port 8080serve runs the same build as python -m sitegen --catalog .catalog --out dist, then
serves dist/ with the standard library's http.server, bound to 127.0.0.1 only.
It prints Serving chock.sh locally at http://127.0.0.1:<port>/ (Ctrl+C to stop).
It is a local test server only. Cloudflare builds the hosted site; see "Deploy".
Cloudflare Pages builds the site itself, through its Git integration. There is no deploy workflow and no Cloudflare token in GitHub.
- Production is the
releasebranch. chock.sh changes only when the release job (in open-coder-ai/chock-release) movesreleaseto a release commit. - Every other branch,
mainand PR branches included, builds a preview on a*.chock-site.pages.devURL. Before launch, these previews are the staging site.
The build: sh build.sh (POSIX sh, set -eu). Cloudflare runs it, and CI's
build job runs it on every PR, so the Cloudflare build path is tested before merge.
It:
- reads
.framework-refand.catalog-refand refuses any pin that is not a full 40-hex commit; - fetches chock-catalog at
.catalog-refand refuses ifHEADis not exactly that commit; - installs, in a fresh venv,
requirements-build.txtwith--require-hashes(every PyPI package pinned by version and sha256), then the engine at.framework-refwith--no-deps --no-build-isolation(so it pulls nothing outside the lock), then the engine's own commit-pinned git dependencies (agentseam) the same way throughscripts/install_engine_deps.py, which refuses any git source that is not an open-coder-ai repo at a full commit; then runspip check; - runs
python -m sitegen --catalog <catalog> --out dist; - checks that
dist/_headersanddist/version.jsonexist.
It reads no secrets. Its only network sources are GitHub (the engine, the catalog and the engine's git pins) and PyPI. It needs Python 3.12 and stops otherwise. Both GitHub repos must be readable without credentials.
Lock files. requirements-build.txt, requirements-dev.txt and
requirements-workflows.txt are generated from the .in file of the same name, which
says how to regenerate it (uv pip compile --universal --generate-hashes). Change the
.in, never the .txt. When .framework-ref moves to an engine with new runtime
dependencies, add them to requirements-build.in; pip check fails until you do.
Version marker. data/version.json holds the site version, {"version": "X.Y.Z"};
chock-release's check.py reads this file and refuses a release whose version differs. The build
writes dist/version.json as {"version", "engine", "catalog"} (the version and the
two pins) and shows v<version> in every page footer. The release job reads
/version.json to check that the live site is the release it moved release to.
Response headers. deploy/_headers is copied into dist/_headers by the build.
It sets, on every path, the page CSP plus frame-ancestors 'none',
X-Content-Type-Options, Referrer-Policy, Permissions-Policy and
Cross-Origin-Opener-Policy. tests/test_headers.py checks that its CSP equals the
<meta> CSP in templates/base.html plus frame-ancestors; change both together.
Asset names are not content-hashed, so /css/*, /js/*, /img/* and /fonts/* get a
short cache (max-age=300). There is no HSTS until launch.
Not indexed. Every *.pages.dev URL is served with X-Robots-Tag: noindex:
https://:project.pages.dev/* covers production and https://:version.:project.pages.dev/*
covers previews (a placeholder stops at ., per Cloudflare's _headers docs).
CI hardening. ci.yml runs actionlint and zizmor on every workflow, every
action is pinned by commit SHA, and every checkout sets persist-credentials: false.
Owner setup, once.
- Make chock-site public (branch rules on a private repo need a paid plan).
- Add a branch rule (ruleset) on
release: only the owner and the GitHub Appchock-release-botmay push it, or bypass the rule. No force-push, no deletion. - In Cloudflare → Workers & Pages → Create → Pages → Connect to Git. Grant the Cloudflare GitHub app access to chock-site only, then pick it.
- Project settings:
- production branch:
release; - build command:
sh build.sh; - build output directory:
dist; - environment variable
PYTHON_VERSION=3.12(production and preview).
- production branch:
- Preview deployments: all non-production branches.
- At launch: add the custom domain
chock.shin the Pages project, update DNS as Cloudflare shows, then setlaunched: trueand add HSTS in a small PR.
Rollback. Pages keeps every deployment. In the Pages project → Deployments, pick an
earlier production deployment and choose Rollback to this deployment; or move
release back to the earlier release commit.
py -3.12 -m venv .venv; .\.venv\Scripts\Activate.ps1
pip install --require-hashes -r requirements-dev.txt
pip install --no-deps --no-build-isolation "chock @ git+https://github.com/open-coder-ai/chock@$(Get-Content .framework-ref)"
python scripts/install_engine_deps.py
git clone https://github.com/open-coder-ai/chock-catalog .catalog
git -C .catalog checkout (Get-Content .catalog-ref)
python -m sitegen serve --catalog .catalog
python -m playwright install chromium
pytest -q tests/e2e--catalog PATH: required. A chock-catalog checkout at.catalog-ref; the build checksgit -C <catalog> rev-parse HEADand exits with code 2 on a mismatch.--out PATH: required for a build (defaultdistforserve). Emptied first, then written, with a.sitegen-outputmarker. The build refuses (exit 2) a path that is the repo root, the home directory, a filesystem root, an ancestor of the repo, or a non-empty directory without that marker.--catalog-source URL_OR_PATH: defaulthttps://github.com/open-coder-ai/chock-catalog. What the selection'scatalog.sourcesays. Tests pass the local.catalogpath.--release vX.Y.Z: optional. Written tocatalog.releasewhen given; omitted otherwise.
data/analytics.yaml lists every action the site counts and the ids each may carry
(plan AN-1). track() in static/js/common.js sends one with navigator.sendBeacon to
/api/event on the same origin, and never when the browser sends Global Privacy Control
or Do Not Track. On localhost and 127.0.0.1 it sends nothing unless the page URL has
?track=1. functions/api/event.js checks the event again and writes it to Workers
Analytics Engine (binding EVENTS). Without that binding it returns 204 and stores nothing.
Both sides import the allowlist from functions/api/_allowlist.js, which is generated
from the data; the build copies it to dist/js/allowlist.js. After editing
data/analytics.yaml, run python -m sitegen allowlist. The build refuses (exit 2)
a stale _allowlist.js.
See AGENTS.md for the rules and templates/, data/, static/, sitegen/,
tests/ for the sources. Everything under dist/ is generated and git-ignored.
The landing page (sitegen/home.py) reads these files; every count, label and
policy line on it is computed from the catalog at build time.
data/home.yaml, underlanding:: the page copy. The site shows no video.data/demo.yaml: one entry per terminal-demo tab, a policy id and a case id from that policy's eval suite. The build fails if the case is missing or does not expect a block.data/incidents.yaml: the incident table. The build fails on a policy id that is not a visible catalog policy.static/js/home.js(tabs) andstatic/js/cost.js(the cost calculator) are optional: without JavaScript the demo and the use cases render as lists and the calculator shows its formula and worked example as text.