Skip to content

About

chock-site

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

406 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

chock.sh

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 (only sitegen/engine.py imports 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.

Local setup and preview (bash)

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 8080

serve 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".

Deploy (Cloudflare Pages)

Cloudflare Pages builds the site itself, through its Git integration. There is no deploy workflow and no Cloudflare token in GitHub.

  • Production is the release branch. chock.sh changes only when the release job (in open-coder-ai/chock-release) moves release to a release commit.
  • Every other branch, main and PR branches included, builds a preview on a *.chock-site.pages.dev URL. 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:

  1. reads .framework-ref and .catalog-ref and refuses any pin that is not a full 40-hex commit;
  2. fetches chock-catalog at .catalog-ref and refuses if HEAD is not exactly that commit;
  3. installs, in a fresh venv, requirements-build.txt with --require-hashes (every PyPI package pinned by version and sha256), then the engine at .framework-ref with --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 through scripts/install_engine_deps.py, which refuses any git source that is not an open-coder-ai repo at a full commit; then runs pip check;
  4. runs python -m sitegen --catalog <catalog> --out dist;
  5. checks that dist/_headers and dist/version.json exist.

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.

  1. Make chock-site public (branch rules on a private repo need a paid plan).
  2. Add a branch rule (ruleset) on release: only the owner and the GitHub App chock-release-bot may push it, or bypass the rule. No force-push, no deletion.
  3. In Cloudflare → Workers & Pages → Create → Pages → Connect to Git. Grant the Cloudflare GitHub app access to chock-site only, then pick it.
  4. Project settings:
    • production branch: release;
    • build command: sh build.sh;
    • build output directory: dist;
    • environment variable PYTHON_VERSION = 3.12 (production and preview).
  5. Preview deployments: all non-production branches.
  6. At launch: add the custom domain chock.sh in the Pages project, update DNS as Cloudflare shows, then set launched: true and 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.

Windows (PowerShell)

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

python -m sitegen options

  • --catalog PATH: required. A chock-catalog checkout at .catalog-ref; the build checks git -C <catalog> rev-parse HEAD and exits with code 2 on a mismatch.
  • --out PATH: required for a build (default dist for serve). Emptied first, then written, with a .sitegen-output marker. 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: default https://github.com/open-coder-ai/chock-catalog. What the selection's catalog.source says. Tests pass the local .catalog path.
  • --release vX.Y.Z: optional. Written to catalog.release when given; omitted otherwise.

Site events

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.

Layout

See AGENTS.md for the rules and templates/, data/, static/, sitegen/, tests/ for the sources. Everything under dist/ is generated and git-ignored.

Home page data

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, under landing:: 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) and static/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.

About

chock-site

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages