From 0214ee634fbff275dbaa6551e310002ef9137786 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 14 Nov 2026 02:25:10 +0000 Subject: [PATCH] Build the public site without the private HALLUX repo; publish docs/ atomically - HTML-2: HALLUX tokens fall back to dev/hallux-snapshot.json, which every build with HALLUX checked out rewrites; BLVKWARE_REQUIRE_HALLUX=1 refuses it - The build runs in a staging copy and swaps into docs/ only on success, so an abort no longer leaves a half-written site - dev/check-public-build.py checks both paths; CI runs it Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011GFY8v4QeVYzawpSLcJCzz --- .github/workflows/public-build.yml | 22 ++++++++ .gitignore | 4 ++ README.md | 4 ++ dev/build-static.py | 31 +++++++++++ dev/check-public-build.py | 89 ++++++++++++++++++++++++++++++ dev/hallux-snapshot.json | 23 ++++++++ dev/hallux_bridge.py | 51 +++++++++++++++-- 7 files changed, 220 insertions(+), 4 deletions(-) create mode 100644 .github/workflows/public-build.yml create mode 100644 dev/check-public-build.py create mode 100644 dev/hallux-snapshot.json diff --git a/.github/workflows/public-build.yml b/.github/workflows/public-build.yml new file mode 100644 index 0000000..0484c47 --- /dev/null +++ b/.github/workflows/public-build.yml @@ -0,0 +1,22 @@ +name: Public build +on: + push: + branches: [main] + pull_request: +permissions: + contents: read +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 # article dates come from git history + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + - uses: actions/setup-node@v4 + with: + node-version: 22 + - name: Build without the private HALLUX repository, and check the publish is atomic + run: python dev/check-public-build.py diff --git a/.gitignore b/.gitignore index 627484b..18637ab 100644 --- a/.gitignore +++ b/.gitignore @@ -24,3 +24,7 @@ ops/*.json # The demo video is rebuilt by marketing/video/record.mjs; too big for git. marketing/video/out/*.mp4 + +# Build staging (dev/build-static.py) +.docs-staging-*/ +docs.previous/ diff --git a/README.md b/README.md index f9b67c3..c94e111 100644 --- a/README.md +++ b/README.md @@ -106,6 +106,10 @@ python dev/embed-logo.py # regenerate logo assets from the master Stdlib only for the server; the logo tooling needs Pillow and numpy. +The build writes to a staging copy and replaces `docs/` only if every step passes, so an aborted build never publishes a half-updated site. + +HALLUX prices and coverage come from the private `hallux` repository when it is checked out beside this one. Each such build also refreshes `dev/hallux-snapshot.json`. A clone without `hallux` fills the same tokens from that snapshot, so the public repository still builds. Set `BLVKWARE_REQUIRE_HALLUX=1` to refuse the snapshot (for the production publish), and run `python dev/check-public-build.py` to verify both paths. + --- ## Limitations diff --git a/dev/build-static.py b/dev/build-static.py index 42f25ef..f3b28ec 100644 --- a/dev/build-static.py +++ b/dev/build-static.py @@ -19,6 +19,7 @@ import os import re import shutil +import tempfile import sys sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) @@ -1795,6 +1796,36 @@ def point_social_cards(): def main(): + """Build into a staging copy of docs/ and swap it in only on success. + + The build writes hundreds of files. Writing them straight into docs/ + meant an abort halfway through (an unresolved token, a price mismatch) + left a published tree that was part old, part new. + """ + global OUT_DIR + final = OUT_DIR + stage = tempfile.mkdtemp(prefix=".docs-staging-", dir=ROOT) + try: + if os.path.isdir(final): + shutil.copytree(final, stage, symlinks=True, dirs_exist_ok=True) + OUT_DIR = stage + code = _build() + if code != 0: + print("docs/ left unchanged") + return code + previous = final + ".previous" + shutil.rmtree(previous, ignore_errors=True) + if os.path.isdir(final): + os.rename(final, previous) + os.rename(stage, final) + shutil.rmtree(previous, ignore_errors=True) + return 0 + finally: + OUT_DIR = final + shutil.rmtree(stage, ignore_errors=True) + + +def _build(): if not os.path.isdir(OUT_DIR): os.makedirs(OUT_DIR) diff --git a/dev/check-public-build.py b/dev/check-public-build.py new file mode 100644 index 0000000..711c3fa --- /dev/null +++ b/dev/check-public-build.py @@ -0,0 +1,89 @@ +""" +Regression check for the public build (audit HTML-2). + +Copies the tracked files of this repository into a temporary directory with +no HALLUX checkout beside it, then asserts: + +1. the build succeeds and leaves no {{HALLUX_*}} token in docs/, using + dev/hallux-snapshot.json; +2. with BLVKWARE_REQUIRE_HALLUX=1 the build aborts, and the aborted run + leaves docs/ byte for byte as it was (the publish is atomic). + +Usage: python3 dev/check-public-build.py +""" +import hashlib +import os +import re +import shutil +import subprocess +import sys +import tempfile + +ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) + + +def tree_hash(path): + digest = hashlib.sha256() + for dirpath, dirs, files in os.walk(path): + dirs.sort() + for name in sorted(files): + full = os.path.join(dirpath, name) + digest.update(os.path.relpath(full, path).encode()) + with open(full, "rb") as fh: + digest.update(hashlib.sha256(fh.read()).digest()) + return digest.hexdigest() + + +def main(): + files = subprocess.run(["git", "-C", ROOT, "ls-files", "-co", "--exclude-standard", "-z"], + check=True, capture_output=True).stdout.decode().split("\0") + work = tempfile.mkdtemp(prefix="public-build-") + repo = os.path.join(work, "site-repo") # no ../hallux beside it + try: + for rel in filter(None, files): + src = os.path.join(ROOT, rel) + if not os.path.isfile(src): + continue + dst = os.path.join(repo, rel) + os.makedirs(os.path.dirname(dst), exist_ok=True) + shutil.copy2(src, dst) + subprocess.run(["git", "init", "-q"], cwd=repo, check=True) + env = {k: v for k, v in os.environ.items() if k not in ("HALLUX_PATH", "BLVKWARE_REQUIRE_HALLUX")} + build = [sys.executable, os.path.join("dev", "build-static.py")] + + run = subprocess.run(build, cwd=repo, env=env, capture_output=True, text=True) + if run.returncode != 0: + print(run.stdout[-3000:], run.stderr[-3000:]) + print("FAIL: public build without HALLUX exited %d" % run.returncode) + return 1 + leftovers = set() + for dirpath, _dirs, names in os.walk(os.path.join(repo, "docs")): + for name in names: + if name.endswith((".html", ".txt", ".json", ".xml")): + with open(os.path.join(dirpath, name), encoding="utf-8", errors="replace") as fh: + leftovers.update(re.findall(r"\{\{HALLUX_[A-Z0-9_]+\}\}", fh.read())) + if leftovers: + print("FAIL: unresolved tokens in docs/: %s" % ", ".join(sorted(leftovers))) + return 1 + print("ok: public build succeeded with no unresolved HALLUX tokens") + + before = tree_hash(os.path.join(repo, "docs")) + strict = dict(env, BLVKWARE_REQUIRE_HALLUX="1") + run = subprocess.run(build, cwd=repo, env=strict, capture_output=True, text=True) + if run.returncode == 0: + print("FAIL: BLVKWARE_REQUIRE_HALLUX=1 should abort without HALLUX") + return 1 + if tree_hash(os.path.join(repo, "docs")) != before: + print("FAIL: an aborted build changed docs/") + return 1 + if any(n.startswith(".docs-staging-") for n in os.listdir(repo)): + print("FAIL: staging directory left behind") + return 1 + print("ok: aborted build left docs/ unchanged and cleaned up") + return 0 + finally: + shutil.rmtree(work, ignore_errors=True) + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/dev/hallux-snapshot.json b/dev/hallux-snapshot.json new file mode 100644 index 0000000..7e8fb65 --- /dev/null +++ b/dev/hallux-snapshot.json @@ -0,0 +1,23 @@ +{ + "{{HALLUX_API_BASE}}": "https://api.blvkware.dev/hallux/v1", + "{{HALLUX_CAP_IDENTIFIERS}}": "373,750", + "{{HALLUX_EMBEDDED_FROM}}": "from $2,500", + "{{HALLUX_FEED_MONTH}}": "$1,500", + "{{HALLUX_FEED_YEAR}}": "$15,000", + "{{HALLUX_FREE_DAILY}}": "500", + "{{HALLUX_MCP}}": "

There is also an MCP server exposing the same capability as tools, so a coding agent can check a command before running it without anyone wiring an integration. It answers at https://api.blvkware.dev/hallux/mcp over Streamable HTTP, with no account and no key:

\n
claude mcp add --transport http hallux https://api.blvkware.dev/hallux/mcp
\n

Any other MCP host takes the same address. The tools are hallux_check_command, to call before an install, hallux_check_manifest, after editing a dependency file, and hallux_check for identifiers; hallux_watch is refused until durable storage is configured. Every identifier a tool resolves counts against the open tier, like any other check.

", + "{{HALLUX_NAMESPACES}}": "cite.doi, pkg.crates, pkg.go, pkg.maven, pkg.npm, pkg.nuget, pkg.pypi", + "{{HALLUX_NAMESPACE_COUNT}}": "7", + "{{HALLUX_NEUTRALITY}}": "HALLUX is never paid more because it blocked you. Billing is a function of identifiers submitted, not of the verdicts returned. A verification vendor paid per finding has a commercial reason to find more.", + "{{HALLUX_OPEN_POOL}}": "50,000", + "{{HALLUX_PAID_NOTICE}}": "

Metered credit is on sale now. Prepaid packs of $5, $20 and $100 are sold through PayPal at api.blvkware.dev/buy, and one key works across HALLUX and CORDON. Team, Feed and Embedded are priced below but are not yet sold through the site, and watches are not available yet. The open tier needs no account and no key.

", + "{{HALLUX_PRICE_PER_IDENTIFIER}}": "$0.0008", + "{{HALLUX_STATUS_NOTICE}}": "", + "{{HALLUX_TEAM_MONTH}}": "$299", + "{{HALLUX_TEAM_WATCHES}}": "100", + "{{HALLUX_TEAM_YEAR}}": "$2,990", + "{{HALLUX_TRY_HEADING}}": "Try it now", + "{{HALLUX_TRY_INTRO}}": "

No account, no key, no signup. One command:

", + "{{HALLUX_TRY_RESPONSE}}": "
{\n  "namespace": "pkg.pypi",\n  "value": "requests-oauth2-helper",\n  "evidence": {\n    "registryStatus": "not_found",\n    "source": "https://pypi.org/pypi/requests-oauth2-helper/json",\n    "attestations": 0,\n    "observedFrom": [],\n    "firstObserved": "2026-11-12T01:54:43Z",\n    "lastObserved": "2026-11-14T02:24:11Z",\n    "checksWhileAbsent": 90,\n    "nearestExisting": [\n      "requests",\n      "requests-oauthlib",\n      "requests-toolbelt"\n    ],\n    "conflation": {\n      "parents": [\n        "oauth2client",\n        "requests"\n      ],\n      "confidence": 0.78,\n      "note": "Every token comes from a real package but the combination does not exist: the shape of an LLM conflation."\n    }\n  },\n  "verdict": "absent",\n  "confidence": 1,\n  "recommendation": "do_not_install",\n  "billing": {\n    "tier": "free",\n    "charged": 1,\n    "remaining": 495\n  }\n}
", + "{{HALLUX_WATCH_MONTH}}": "$0.02" +} diff --git a/dev/hallux_bridge.py b/dev/hallux_bridge.py index 9f57225..b523785 100644 --- a/dev/hallux_bridge.py +++ b/dev/hallux_bridge.py @@ -225,15 +225,58 @@ def _try_response(deployed): return "
%s
" % text +#: The token values from the last build that had HALLUX checked out. Every +#: full build rewrites it, so it is committed beside the docs/ it produced and +#: cannot drift from them. A public clone without the private HALLUX +#: repository fills the pages from it instead of aborting. +SNAPSHOT = os.path.join(HERE, "hallux-snapshot.json") + +_SNAPSHOT_NOTED = [] + + +def _write_snapshot(values): + text = json.dumps(values, indent=2, sort_keys=True, ensure_ascii=False) + "\n" + try: + with io.open(SNAPSHOT, encoding="utf-8") as fh: + if fh.read() == text: + return + except OSError: + pass + with io.open(SNAPSHOT, "w", encoding="utf-8") as fh: + fh.write(text) + + +def _read_snapshot(): + try: + with io.open(SNAPSHOT, encoding="utf-8") as fh: + values = json.load(fh) + except (OSError, ValueError): + return None + if not _SNAPSHOT_NOTED: + _SNAPSHOT_NOTED.append(True) + print("note: HALLUX not checked out; HALLUX tokens filled from " + "dev/hallux-snapshot.json (the last full build's values)") + return values + + def tokens(): - """The `{{HALLUX_*}}` substitutions, or None when HALLUX is absent. + """The `{{HALLUX_*}}` substitutions, or None when HALLUX is absent and no + snapshot exists. - Every value here is read from HALLUX at build time. Nothing in this - function may be a literal price. + Every value here is read from HALLUX at build time, or from the snapshot + the last such build wrote. Nothing in this function may be a literal price. """ path = locate() if path is None: - return None + if os.environ.get("BLVKWARE_REQUIRE_HALLUX") == "1": + return None + return _read_snapshot() + values = _live_tokens(path) + _write_snapshot(values) + return values + + +def _live_tokens(path): payment, authorities = _load(path) # Named apart from `namespaces` on purpose: an earlier version called both # of these `live`, the namespace list overwrote the probe result, and the