Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions .github/workflows/public-build.yml
Original file line number Diff line number Diff line change
@@ -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
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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/
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
31 changes: 31 additions & 0 deletions dev/build-static.py
Original file line number Diff line number Diff line change
Expand Up @@ -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__)))
Expand Down Expand Up @@ -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)

Expand Down
89 changes: 89 additions & 0 deletions dev/check-public-build.py
Original file line number Diff line number Diff line change
@@ -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())
23 changes: 23 additions & 0 deletions dev/hallux-snapshot.json
Original file line number Diff line number Diff line change
@@ -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}}": "<p>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 <code>https://api.blvkware.dev/hallux/mcp</code> over Streamable HTTP, with no account and no key:</p>\n<pre><code><span class=\"c\">claude</span> mcp add --transport http hallux https://api.blvkware.dev/hallux/mcp</code></pre>\n<p>Any other MCP host takes the same address. The tools are <code>hallux_check_command</code>, to call before an install, <code>hallux_check_manifest</code>, after editing a dependency file, and <code>hallux_check</code> for identifiers; <code>hallux_watch</code> is refused until durable storage is configured. Every identifier a tool resolves counts against the open tier, like any other check.</p>",
"{{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}}": "<p class=\"note\"><strong>Metered credit is on sale now.</strong> Prepaid packs of $5, $20 and $100 are sold through PayPal at <a href=\"https://api.blvkware.dev/buy\">api.blvkware.dev/buy</a>, 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.</p>",
"{{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}}": "<p>No account, no key, no signup. One command:</p>",
"{{HALLUX_TRY_RESPONSE}}": "<pre><code>{\n &quot;namespace&quot;: &quot;pkg.pypi&quot;,\n &quot;value&quot;: &quot;requests-oauth2-helper&quot;,\n &quot;evidence&quot;: {\n &quot;registryStatus&quot;: &quot;not_found&quot;,\n &quot;source&quot;: &quot;https://pypi.org/pypi/requests-oauth2-helper/json&quot;,\n &quot;attestations&quot;: 0,\n &quot;observedFrom&quot;: [],\n &quot;firstObserved&quot;: &quot;2026-11-12T01:54:43Z&quot;,\n &quot;lastObserved&quot;: &quot;2026-11-14T02:24:11Z&quot;,\n &quot;checksWhileAbsent&quot;: 90,\n &quot;nearestExisting&quot;: [\n &quot;requests&quot;,\n &quot;requests-oauthlib&quot;,\n &quot;requests-toolbelt&quot;\n ],\n &quot;conflation&quot;: {\n &quot;parents&quot;: [\n &quot;oauth2client&quot;,\n &quot;requests&quot;\n ],\n &quot;confidence&quot;: 0.78,\n &quot;note&quot;: &quot;Every token comes from a real package but the combination does not exist: the shape of an LLM conflation.&quot;\n }\n },\n &quot;verdict&quot;: <span class=\"s\">&quot;absent&quot;</span>,\n &quot;confidence&quot;: 1,\n &quot;recommendation&quot;: &quot;do_not_install&quot;,\n &quot;billing&quot;: {\n &quot;tier&quot;: &quot;free&quot;,\n &quot;charged&quot;: 1,\n &quot;remaining&quot;: 495\n }\n}</code></pre>",
"{{HALLUX_WATCH_MONTH}}": "$0.02"
}
51 changes: 47 additions & 4 deletions dev/hallux_bridge.py
Original file line number Diff line number Diff line change
Expand Up @@ -225,15 +225,58 @@ def _try_response(deployed):
return "<pre><code>%s</code></pre>" % 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
Expand Down
Loading