scripts/website/README.md

Aureon website release tooling

This directory is the single automated release stack for the static site in website/:

audit -> commit-bound build -> fresh backup gate -> non-pruning FTPS upload -> exact read-back

An upload is not publication proof. The release is complete only when the read-back comparison passes for the exact package.

1. Audit

python -m scripts.website.audit_site --root website

The deterministic audit fails on broken internal links/assets, invalid JSON or JSON-LD, sitemap/canonical drift, and the static accessibility/SEO contracts it implements. It is not a substitute for the separate claim, browser, a11y, or Core Web Vitals gates.

2. Build an exact release

The source commit is mandatory. In a Git worktree it must equal checked-out HEAD, and the bounded website/ tree must be clean. An uncommitted public file cannot be described as belonging to a commit.

$sourceCommit = (git rev-parse HEAD).Trim()
python -m scripts.website.build_package `
  --root website `
  --out artifacts/website-releases `
  --source-commit $sourceCommit

The build writes:

• website_package/ with index.html at its root;
• website_package/HOMEPL_PACKAGE_MANIFEST.txt, which names the exact source commit and package contract;
• website_package/HOMEPL_FILE_HASHES.json, a sorted SHA-256 record for every other package file, including the summary manifest;
• aureon-zorza-website.zip, produced with deterministic ordering and timestamps; and
• aureon-zorza-website.zip.sha256.txt, the external companion containing the ZIP hash and the hash of HOMEPL_FILE_HASHES.json.

HOMEPL_FILE_HASHES.json intentionally excludes itself to avoid recursive self-hashing. Its own SHA-256 is in the external companion.

For byte-identical reproduction, also pass the same --created-at value. A standalone test fixture outside Git can build with an explicit valid commit, but the manifest labels that binding declared-only-isolated-source; a real repository build is labelled verified-git-head-clean-site.

3. Create and verify a fresh backup

Before any remote write, map the authenticated Home.pl served root and create a fresh recursive backup with a non-zero manifest. The audited backup tool is website/backup-homepl-ftps.ps1. It emits an aureon.homepl-backup-transfer.v1 receipt only after a complete, read-only transfer and manifest verification.

Do not assume that the root is / or /public_html. The exact current provider mapping controls. If the existing backup tool's strict root/preflight contract does not match the current provider mapping, stop and use the Home.pl provider backup as a named human host gate; do not weaken the mapping check or fabricate a receipt.

4. Plan and deploy without pruning

The Python deployer and the audited PowerShell tools use one environment-name contract:

Variable	Required	Meaning
HOMEPL_FTPS_HOST	yes	FTPS hostname only
HOMEPL_FTPS_USER	yes	temporary or approved FTPS account
HOMEPL_FTPS_PASSWORD	yes	process-only secret; never logged
HOMEPL_FTPS_REMOTE_ROOT	yes	exact authenticated served root
HOMEPL_FTPS_PORT	yes	exact authenticated port; never inferred from mode
HOMEPL_FTPS_MODE	yes	exactly explicit or implicit
HOMEPL_FTPS_CERT_THUMBPRINT	PowerShell only	optional pinned certificate thumbprint

Retained Home.pl configuration evidence points to implicit FTPS on port 990. The Python uploader supports that transport and explicit FTPS as two separate, fail-closed modes. Both use the operating system trust store with certificate and hostname verification and require PROT P; implicit mode wraps the control socket before reading the server welcome and never sends AUTH TLS, while explicit mode negotiates TLS after the welcome. Mode and port remain mandatory and are never inferred from one another. The exact provider hostname, served root, and approved credentials are still unresolved operator gates, and no live Home.pl connection or publication is claimed here. Do not silently substitute explicit port 21.

Dry-run still requires the target binding and process-only credentials because it prints the exact authenticated-account plan, but it performs no network operation:

python -m scripts.website.ftp_deploy `
  --package artifacts/website-releases/website_package `
  --dry-run

A live upload additionally requires the fresh backup transfer receipt:

python -m scripts.website.ftp_deploy `
  --package artifacts/website-releases/website_package `
  --backup-receipt C:\absolute\path\to\backup-transfer.json

The deployer verifies the local package against its per-file manifest before opening a connection. It also verifies that the backup receipt was produced by the checked website/backup-homepl-ftps.ps1, that its deterministic CSV Path,Bytes,Sha256 manifest matches the exact downloaded directory, and that its counts, byte totals, root and freshness agree. A hand-authored receipt or a manifest detached from the backed-up files is refused. The deployer creates/overwrites package files only. Pruning and remote deletion are disabled; --prune is always refused.

5. Compare exact read-back

Capture the served-root files through the authenticated operator or fetch the public paths into an isolated directory, then compare without credentials or network access:

python -m scripts.website.readback `
  --package artifacts/website-releases/website_package `
  --readback-dir C:\absolute\path\to\captured-served-root

The directory helper verifies HOMEPL_FILE_HASHES.json itself, every listed file by size and SHA-256, and the absence of unexpected files in the downloaded served-root mirror. This exact-mirror rule prevents a mixed release from passing when non-pruning upload leaves stale public files.

compare_http_observations() verifies every expected package path from already captured status/body objects. It cannot discover an unknown stale URL that was not requested, so it is expected-path evidence, not proof of an exact served-root file set. Reports never contain bodies, URLs, headers, cookies, or credentials.

TLS, cache headers, public route rendering, visual regression, accessibility, claim lint, and Core Web Vitals remain separate mandatory release evidence.

Manual provider alternatives

Home.pl WebFTP ZIP upload/unzip is a manual host-gate alternative, not a second release stack. It must use the exact audited ZIP, the same fresh backup gate, the exact served root, and the same per-file read-back comparison. The legacy website/publish-homepl-ftps.ps1 CSV flow and website/build-homepl-package.ps1 are not the canonical V45 automated path. Do not mix their legacy manifests with HOMEPL_FILE_HASHES.json.

Focused verification

$env:PYTHONDONTWRITEBYTECODE = '1'
python -m pytest -p no:cacheprovider tests/test_website_tooling.py -q
python -m ruff check scripts/website tests/test_website_tooling.py
python -m mypy --strict scripts/website/build_package.py scripts/website/ftp_deploy.py scripts/website/readback.py