Skip to content

armgit / xerj

Public Imported from GitHub
0

AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.

feat(adoption): instrument the distribution surface, and fix three installer bugs

xerj-orga2fc56654461
diff --git a/.github/scripts/functions-get-test.mjs b/.github/scripts/functions-get-test.mjs
new file mode 100644
index 000000000..702e258e6
--- /dev/null
+++ b/.github/scripts/functions-get-test.mjs
@@ -0,0 +1,274 @@
+// Behaviour + privacy test for functions/get.js (the /get, /get.ps1 install
+// counter). Runs on plain Node — no wrangler, no network, no Cloudflare
+// account — by stubbing the two bindings the function touches: env.ASSETS
+// (static asset reads) and env.INSTALLS (the R2 bucket).
+//
+// What this DOES prove: the handler's logic — fail-open on every counter
+// failure, correct headers, correct classification, and that no IP or stable
+// identifier is ever written.
+// What this does NOT prove: that Cloudflare routes /get to this function, or
+// that the R2 binding resolves in production. Those need a real deploy (or
+// `wrangler pages dev`) and cannot be checked here.
+//
+// node .github/scripts/functions-get-test.mjs
+import { readFileSync, writeFileSync, mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const SRC = join(REPO, 'functions', 'get.js');
+const SCRIPT_BODY = readFileSync(join(REPO, 'landing', 'get'), 'utf8');
+const PS1_BODY = readFileSync(join(REPO, 'landing', 'get.ps1'), 'utf8');
+
+// functions/get.js is an ES module, but package.json has no "type":"module",
+// so Node would parse a bare .js import as CommonJS. Copying the real bytes to
+// a .mjs and importing that keeps the test honest (same source) without
+// changing the repo's module mode.
+const src = readFileSync(SRC, 'utf8');
+const tmp = join(mkdtempSync(join(tmpdir(), 'xerj-fn-')), 'get.mjs');
+writeFileSync(tmp, src);
+const fn = await import(tmp);
+
+let failures = 0;
+const ok = (cond, name, extra = '') => {
+ if (cond) { console.log(` PASS ${name}`); }
+ else { console.log(` FAIL ${name}${extra ? ' — ' + extra : ''}`); failures++; }
+};
+
+/** In-memory stand-in for an R2 bucket. `mode` forces the failure paths. */
+function fakeR2(mode = 'ok') {
+ const store = new Map();
+ return {
+ store,
+ async put(key, value) {
+ if (mode === 'throw') throw new Error('R2 unavailable');
+ store.set(key, value);
+ },
+ async list({ prefix, limit, cursor }) {
+ const keys = [...store.keys()].filter((k) => k.startsWith(prefix)).sort();
+ return { objects: keys.map((k) => ({ key: k })), truncated: false, cursor: undefined };
+ },
+ async get(key) {
+ const v = store.get(key);
+ return v === undefined ? null : { text: async () => v };
+ },
+ };
+}
+
+function fakeAssets(mode = 'ok') {
+ return {
+ async fetch(url) {
+ if (mode === 'throw') throw new Error('assets down');
+ const p = new URL(url).pathname;
+ if (mode === '500') return new Response('boom', { status: 500 });
+ if (p === '/get') return new Response(SCRIPT_BODY, { status: 200 });
+ if (p === '/get.ps1') return new Response(PS1_BODY, { status: 200 });
+ return new Response('not found', { status: 404 });
+ },
+ };
+}
+
+/** Build a request that carries request.cf, the way the edge delivers it. */
+function req(path, ua, country = 'DE') {
+ const r = new Request(`https://xerj.org${path}`, { headers: ua ? { 'user-agent': ua } : {} });
+ Object.defineProperty(r, 'cf', { value: { country, city: 'Berlin', asn: 3320, latitude: '52.5', longitude: '13.4' } });
+ return r;
+}
+
+/** Invoke the handler and settle everything waitUntil() deferred. */
+async function call(request, env, method = 'GET') {
+ const pending = [];
+ const context = { request, env, waitUntil: (p) => pending.push(p) };
+ const res = method === 'HEAD' ? await fn.onRequestHead(context) : await fn.onRequestGet(context);
+ await Promise.allSettled(pending);
+ return res;
+}
+
+const rowsOf = (r2) => [...r2.store.values()].map((v) => JSON.parse(v));
+
+console.log('── functions/get.js ──');
+
+// 1. Happy path: the script is served byte-for-byte and the request is counted.
+{
+ const INSTALLS = fakeR2();
+ const res = await call(req('/get', 'curl/8.5.0'), { ASSETS: fakeAssets(), INSTALLS });
+ const body = await res.text();
+ ok(res.status === 200, 'GET /get -> 200', `got ${res.status}`);
+ ok(body === SCRIPT_BODY, 'body is landing/get byte-for-byte');
+ ok(res.headers.get('content-type') === 'text/plain; charset=utf-8', 'content-type is text/plain');
+ ok(res.headers.get('cache-control') === 'no-store', 'cache-control is no-store (a cache hit is an uncounted install)');
+ ok(res.headers.get('x-content-type-options') === 'nosniff', 'nosniff set');
+ const rows = rowsOf(INSTALLS);
+ ok(rows.length === 1, 'exactly one record written', `got ${rows.length}`);
+ ok(rows[0].kind === 'installer', 'curl classified as installer', JSON.stringify(rows[0]));
+ ok(rows[0].country === 'DE', 'country recorded');
+ ok(rows[0].script === 'get', 'script recorded');
+ ok([...INSTALLS.store.keys()][0].startsWith('installs/' + new Date().toISOString().slice(0, 10) + '/'), 'key is date-prefixed');
+}
+
+// 2. PowerShell path.
+{
+ const INSTALLS = fakeR2();
+ const ua = 'Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.19045; en-US) WindowsPowerShell/5.1.19041.4291';
+ const res = await call(req('/get.ps1', ua, 'US'), { ASSETS: fakeAssets(), INSTALLS });
+ const body = await res.text();
+ ok(res.status === 200 && body === PS1_BODY, 'GET /get.ps1 serves landing/get.ps1');
+ const r = rowsOf(INSTALLS)[0];
+ ok(r.script === 'get.ps1', 'script=get.ps1');
+ ok(r.kind === 'installer', 'PowerShell classified as installer', JSON.stringify(r));
+ ok(r.os === 'windows', 'os=windows from UA', JSON.stringify(r));
+}
+
+// 3. Classification of the traffic we must NOT count as installs.
+{
+ const cases = [
+ ['Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)', 'bot'],
+ ['Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 Chrome/126 Safari/537.36', 'browser'],
+ ['python-requests/2.31.0', 'bot'],
+ ['curl/7.68.0', 'installer'],
+ ['Wget/1.21.2', 'installer'],
+ ['', 'unknown'],
+ ];
+ for (const [ua, want] of cases) {
+ const INSTALLS = fakeR2();
+ await call(req('/get', ua), { ASSETS: fakeAssets(), INSTALLS });
+ const got = rowsOf(INSTALLS)[0].kind;
+ ok(got === want, `classify(${ua.slice(0, 28) || '<empty>'}) = ${want}`, `got ${got}`);
+ }
+}
+
+// 4. FAIL-OPEN: no binding, and a bucket that throws. The install must survive.
+{
+ const res = await call(req('/get', 'curl/8.5.0'), { ASSETS: fakeAssets() });
+ ok(res.status === 200 && (await res.text()) === SCRIPT_BODY, 'no INSTALLS binding -> script still served');
+
+ const INSTALLS = fakeR2('throw');
+ const res2 = await call(req('/get', 'curl/8.5.0'), { ASSETS: fakeAssets(), INSTALLS });
+ ok(res2.status === 200 && (await res2.text()) === SCRIPT_BODY, 'R2 put throws -> script still served');
+ ok(INSTALLS.store.size === 0, 'nothing stored when the bucket throws');
+
+ const res3 = await call(req('/get', 'curl/8.5.0'), { ASSETS: fakeAssets(), INSTALLS: {} });
+ ok(res3.status === 200, 'malformed binding -> script still served', `got ${res3.status}`);
+}
+
+// 5. Asset failure is the one case that cannot degrade silently.
+{
+ for (const mode of ['throw', '500']) {
+ const res = await call(req('/get', 'curl/8.5.0'), { ASSETS: fakeAssets(mode), INSTALLS: fakeR2() });
+ const body = await res.text();
+ ok(res.status === 503, `assets ${mode} -> 503`, `got ${res.status}`);
+ ok(body.includes('releases/latest') && body.trim().endsWith('exit 1'), `assets ${mode} -> shell-safe fallback that exits non-zero`);
+ }
+}
+
+// 6. Unknown paths and HEAD.
+{
+ const INSTALLS = fakeR2();
+ const res = await call(req('/nope', 'curl/8.5.0'), { ASSETS: fakeAssets(), INSTALLS });
+ ok(res.status === 404, 'unrelated path -> 404', `got ${res.status}`);
+ ok(INSTALLS.store.size === 0, '404 writes no record');
+
+ const head = await call(req('/get', 'curl/8.5.0'), { ASSETS: fakeAssets(), INSTALLS }, 'HEAD');
+ ok(head.status === 200, 'HEAD /get -> 200', `got ${head.status}`);
+ ok((await head.text()) === '', 'HEAD has no body');
+ ok(INSTALLS.store.size === 0, 'HEAD is not counted as an install attempt');
+}
+
+// 7. PRIVACY — the assertions this whole file exists for.
+{
+ const INSTALLS = fakeR2();
+ const r = new Request('https://xerj.org/get', {
+ headers: {
+ 'user-agent': 'curl/8.5.0',
+ 'cf-connecting-ip': '203.0.113.7',
+ 'x-forwarded-for': '203.0.113.7, 198.51.100.2',
+ 'x-real-ip': '203.0.113.7',
+ referer: 'https://example.com/secret-internal-wiki',
+ cookie: 'session=abcdef123456',
+ 'accept-language': 'de-DE,de;q=0.9',
+ },
+ });
+ Object.defineProperty(r, 'cf', {
+ value: { country: 'DE', city: 'Berlin', postalCode: '10115', asn: 3320, asOrganization: 'Deutsche Telekom', latitude: '52.52', longitude: '13.40' },
+ });
+ await call(r, { ASSETS: fakeAssets(), INSTALLS });
+ const stored = [...INSTALLS.store.values()].join('\n');
+ const row = JSON.parse([...INSTALLS.store.values()][0]);
+
+ ok(!stored.includes('203.0.113.7'), 'no IP address stored');
+ ok(!stored.includes('198.51.100.2'), 'no forwarded-for IP stored');
+ ok(!/\b\d{1,3}(\.\d{1,3}){3}\b/.test(stored), 'stored record contains no IPv4 literal at all');
+ ok(!stored.includes('example.com'), 'no Referer stored');
+ ok(!stored.includes('abcdef123456'), 'no cookie stored');
+ ok(!stored.includes('de-DE'), 'no Accept-Language stored');
+ ok(!stored.includes('Berlin') && !stored.includes('10115'), 'no city/postcode from request.cf');
+ ok(!stored.includes('52.52') && !stored.includes('13.40'), 'no lat/long from request.cf');
+ ok(!stored.includes('3320') && !stored.includes('Telekom'), 'no ASN/network operator from request.cf');
+ const allowed = new Set(['ts', 'script', 'kind', 'country', 'os', 'arch', 'ua', 'ver']);
+ const unexpected = Object.keys(row).filter((k) => !allowed.has(k));
+ ok(unexpected.length === 0, 'record has only the documented fields', 'unexpected: ' + unexpected.join(','));
+ // The R2 key holds a random UUID; it is a write key, never returned to the
+ // client, so it cannot correlate two requests. Assert it stays out of the body.
+ ok(!('id' in row) && !('uuid' in row), 'no identifier inside the record body');
+
+ // Source-level guard: these header names must never appear in the function.
+ for (const forbidden of ['cf-connecting-ip', 'x-forwarded-for', 'x-real-ip', 'set-cookie']) {
+ const codeOnly = src.split('\n').filter((l) => !l.trim().startsWith('//')).join('\n');
+ ok(!codeOnly.toLowerCase().includes(forbidden), `source never reads ${forbidden}`);
+ }
+}
+
+// 8. UA is bounded, so one hostile request cannot balloon an object.
+{
+ const INSTALLS = fakeR2();
+ await call(req('/get', 'curl/' + 'A'.repeat(5000)), { ASSETS: fakeAssets(), INSTALLS });
+ ok(rowsOf(INSTALLS)[0].ua.length === 200, 'user-agent truncated to 200 chars', `got ${rowsOf(INSTALLS)[0].ua.length}`);
+}
+
+// 9. The export must never be reachable without BOTH a caller token and a
+// configured secret. Any miss serves the installer, and — because it took
+// the install path — is itself counted; hence a bucket of its own here.
+{
+ const INSTALLS = fakeR2();
+ const env = { ASSETS: fakeAssets(), INSTALLS, INSTALLS_TOKEN: 's3cret' };
+ const noTok = await call(req('/get', 'curl/8.5.0'), env);
+ ok((await noTok.text()) === SCRIPT_BODY, 'no token -> installer script, not stats');
+ const badTok = await call(new Request('https://xerj.org/get?token=wrong'), env);
+ ok((await badTok.text()) === SCRIPT_BODY, 'wrong token -> installer script, not stats');
+ const unset = await call(new Request('https://xerj.org/get?token=s3cret'), { ASSETS: fakeAssets(), INSTALLS: fakeR2() });
+ ok((await unset.text()) === SCRIPT_BODY, 'token sent but no secret configured -> script, never stats');
+ const empty = await call(new Request('https://xerj.org/get?token='), { ...env, INSTALLS_TOKEN: '' });
+ ok((await empty.text()) === SCRIPT_BODY, 'empty token vs empty secret -> script, never stats');
+}
+
+// 10. Export aggregation, on a bucket nothing else has written to.
+{
+ const INSTALLS = fakeR2();
+ const env = { ASSETS: fakeAssets(), INSTALLS, INSTALLS_TOKEN: 's3cret' };
+ await call(req('/get', 'curl/8.5.0', 'DE'), env);
+ await call(req('/get', 'curl/8.5.0', 'FR'), env);
+ await call(req('/get.ps1', 'WindowsPowerShell/5.1', 'US'), env);
+ await call(req('/get', 'Mozilla/5.0 (compatible; Googlebot/2.1)', 'US'), env);
+ ok(INSTALLS.store.size === 4, 'four requests recorded', `got ${INSTALLS.store.size}`);
+
+ const res = await call(new Request('https://xerj.org/get?token=s3cret'), env);
+ const j = JSON.parse(await res.text());
+ ok(j.ok === true, 'export returns json');
+ ok(res.headers.get('content-type') === 'application/json', 'export is json, not text/plain');
+ ok(j.total_requests === 4, 'export counts every recorded request', `got ${j.total_requests}`);
+ ok(j.installer_shaped_requests === 3, 'export separates installer-shaped from bot', `got ${j.installer_shaped_requests}`);
+ ok(j.by_country.DE === 1 && j.by_country.FR === 1 && j.by_country.US === 2, 'country histogram', JSON.stringify(j.by_country));
+ ok(j.by_script.get === 3 && j.by_script['get.ps1'] === 1, 'script histogram', JSON.stringify(j.by_script));
+ ok(typeof j.caveat === 'string' && j.caveat.includes('not an install'), 'export ships its own caveat');
+ const raw = await call(new Request('https://xerj.org/get?token=s3cret&format=raw'), env);
+ ok(JSON.parse(await raw.text()).rows.length === 4, 'raw export returns rows');
+ const capped = await call(new Request('https://xerj.org/get?token=s3cret&days=99999'), env);
+ ok(JSON.parse(await capped.text()).window_days === 365, 'days window is capped at 365');
+ const floored = await call(new Request('https://xerj.org/get?token=s3cret&days=-5'), env);
+ ok(JSON.parse(await floored.text()).window_days === 1, 'negative days floored to 1');
+}
+
+console.log('──');
+if (failures) { console.log(`FUNCTIONS TEST FAILED (${failures} failing)`); process.exit(1); }
+console.log('FUNCTIONS TEST PASSED');
diff --git a/.github/scripts/snapshot-release-downloads.sh b/.github/scripts/snapshot-release-downloads.sh
new file mode 100755
index 000000000..6b67b9213
--- /dev/null
+++ b/.github/scripts/snapshot-release-downloads.sh
@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+# Append today's per-asset release download counts to metrics/release-downloads.jsonl.
+#
+# WHY THIS EXISTS: GitHub reports `download_count` per asset as a running
+# total and keeps no history. Nothing was snapshotting it, so the only
+# uninflated adoption number this project has existed solely as a
+# point-in-time reading — you could say "145 downloads" but never "how many
+# last week". One line a day turns that scalar into a series, at zero
+# infrastructure cost.
+#
+# PRIVACY: this reads public repository metadata only. GitHub exposes no IP,
+# no user agent and no identity per download; there is nothing personal in
+# this data and nothing here that could make it personal.
+#
+# .github/scripts/snapshot-release-downloads.sh [--out FILE] [--repo OWNER/NAME] [--dry-run]
+#
+# Needs: gh (authenticated), jq. Re-running on the same day REPLACES that
+# day's line rather than appending a second one, so it is safe to run by hand.
+set -euo pipefail
+
+REPO="${XERJ_REPO:-xerj-org/xerj}"
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$HERE/../.." && pwd)"
+OUT="$ROOT/metrics/release-downloads.jsonl"
+DRY=0
+
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --out) OUT="$2"; shift 2 ;;
+ --repo) REPO="$2"; shift 2 ;;
+ --dry-run) DRY=1; shift ;;
+ -h|--help) sed -n '2,20p' "$0"; exit 0 ;;
+ *) echo "unknown argument: $1" >&2; exit 2 ;;
+ esac
+done
+
+command -v gh >/dev/null || { echo "gh is required" >&2; exit 2; }
+command -v jq >/dev/null || { echo "jq is required" >&2; exit 2; }
+
+DAY="$(date -u +%F)"
+NOW="$(date -u +%FT%TZ)"
+
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+
+# API payloads travel via files, not argv: the full /releases response is
+# hundreds of KB (every asset carries an embedded uploader object) and
+# --argjson blew past ARG_MAX. Trim to the fields we keep, up front.
+#
+# --paginate emits either one merged array or one array per page depending on
+# the gh version; `jq -s 'flatten(1)'` normalises both to a single array.
+gh api --paginate "repos/${REPO}/releases?per_page=100" \
+ | jq -s 'flatten(1) | map({tag_name, published_at, prerelease,
+ assets: ((.assets // []) | map({name, download_count}))})' \
+ > "$WORK/releases.json"
+
+# Traffic clones/views are a 14-DAY ROLLING WINDOW: GitHub drops the oldest day
+# every day, so any day not snapshotted is gone for good. That is the strongest
+# reason to run this daily. The endpoint needs push access; when the token has
+# not got it we store null rather than guessing, and the series stays honest.
+gh api "repos/${REPO}/traffic/clones" 2>/dev/null | jq '{count, uniques}' > "$WORK/clones.json" || echo null > "$WORK/clones.json"
+gh api "repos/${REPO}/traffic/views" 2>/dev/null | jq '{count, uniques}' > "$WORK/views.json" || echo null > "$WORK/views.json"
+[ -s "$WORK/clones.json" ] || echo null > "$WORK/clones.json"
+[ -s "$WORK/views.json" ] || echo null > "$WORK/views.json"
+
+snapshot="$(jq -cn \
+ --arg date "$DAY" --arg ts "$NOW" --arg repo "$REPO" \
+ --slurpfile releases_in "$WORK/releases.json" \
+ --slurpfile clones_in "$WORK/clones.json" \
+ --slurpfile views_in "$WORK/views.json" '
+ ($releases_in[0]) as $releases |
+ ($clones_in[0]) as $clones |
+ ($views_in[0]) as $views |
+ # An asset name ending in .sha256 is a checksum. The split matters: the
+ # installer fetches exactly one binary and one checksum per run, so a
+ # binary:checksum ratio near 1:1 is installer-shaped traffic and a ratio
+ # far below 1 is something else (direct fetches, mirrors, scanners).
+ def is_sum: (.name | endswith(".sha256"));
+ ($releases | map(.assets // []) | flatten(1)) as $assets |
+ {
+ date: $date,
+ collected_at: $ts,
+ repo: $repo,
+ totals: {
+ releases: ($releases | length),
+ binary: ($assets | map(select(is_sum | not) | .download_count) | add // 0),
+ checksum: ($assets | map(select(is_sum) | .download_count) | add // 0),
+ all: ($assets | map(.download_count) | add // 0)
+ },
+ releases: ($releases | map({
+ key: .tag_name,
+ value: {
+ published_at: .published_at,
+ prerelease: .prerelease,
+ assets: (.assets // [] | map({key: .name, value: .download_count}) | from_entries)
+ }
+ }) | from_entries),
+ # 14-day rolling windows, not lifetime totals. Never sum these across days:
+ # consecutive snapshots overlap by 13 days.
+ traffic_14d: { clones: $clones, views: $views }
+ }')"
+
+if [ "$DRY" = 1 ]; then
+ printf '%s\n' "$snapshot" | jq .
+ exit 0
+fi
+
+mkdir -p "$(dirname "$OUT")"
+touch "$OUT"
+# Idempotent: drop any existing line for today, then append the fresh one.
+jq -c --arg date "$DAY" 'select(.date != $date)' "$OUT" > "$WORK/out.jsonl" || true
+printf '%s\n' "$snapshot" >> "$WORK/out.jsonl"
+mv "$WORK/out.jsonl" "$OUT"
+
+echo "wrote $DAY -> $OUT"
+jq -c '{date, totals}' <<<"$snapshot"
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 590ef201e..be6f25c10 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -260,7 +260,9 @@ jobs:
# them was manual until this job, so a regression in any was caught by
# nothing. The installer lint rides along: landing/get{,.ps1} had no
# verification of any kind and needs no toolchain, so it gates first and
- # cheaply.
+ # cheaply. The /get counter test rides along for the same reason — it is the
+ # only gate on the promise that the install counter stores no IP and never
+ # breaks an install, and it needs nothing but Node.
usecase-smoke:
name: Use-case harnesses (brain + MCP + autoindex)
runs-on: ubuntu-latest
@@ -270,6 +272,13 @@ jobs:
- name: Installer script lint (landing/get, landing/get.ps1)
run: bash .github/scripts/installer-lint.sh
+ - uses: actions/setup-node@v4
+ with:
+ node-version: '20'
+
+ - name: Install counter behaviour + privacy (functions/get.js)
+ run: node .github/scripts/functions-get-test.mjs
+
- name: Install Rust
uses: dtolnay/rust-toolchain@stable
diff --git a/.github/workflows/release-metrics.yml b/.github/workflows/release-metrics.yml
new file mode 100644
index 000000000..280d2adf8
--- /dev/null
+++ b/.github/workflows/release-metrics.yml
@@ -0,0 +1,66 @@
+name: Release download snapshot
+
+# GitHub reports release asset `download_count` as a running total and keeps no
+# history, so the only uninflated adoption number this project has was a
+# point-in-time reading that could never show a trend. This appends one line a
+# day to metrics/release-downloads.jsonl. No new infrastructure, no service, no
+# secret: it reads public repo metadata with the built-in GITHUB_TOKEN.
+#
+# It also snapshots the 14-day traffic windows (clones/views), which GitHub
+# expires day by day — a day that is not captured is gone permanently. Those
+# fields land as null if the token lacks push scope, which is honest and fine.
+#
+# Privacy: nothing here reads or stores anything about a person. GitHub exposes
+# no IP, user agent or identity per download.
+
+on:
+ schedule:
+ # 06:17 UTC daily — off the hour, because the top of the hour is the most
+ # congested slot on GitHub's scheduler and delays runs by 10-30 minutes.
+ - cron: '17 6 * * *'
+ workflow_dispatch:
+
+permissions:
+ contents: write
+
+concurrency:
+ group: release-metrics
+ cancel-in-progress: false
+
+jobs:
+ snapshot:
+ name: Snapshot release download counts
+ runs-on: ubuntu-latest
+ # Scheduled workflows run on forks too; a fork has nothing to snapshot.
+ if: github.repository == 'xerj-org/xerj'
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Collect
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ run: .github/scripts/snapshot-release-downloads.sh
+
+ - name: Commit if changed
+ run: |
+ set -euo pipefail
+ if git diff --quiet -- metrics/; then
+ echo "no change — nothing to commit"
+ exit 0
+ fi
+ # Commits in this repo are authored as xerj-org.
+ git config user.name "xerj-org"
+ git config user.email "[email protected]"
+ total=$(tail -n1 metrics/release-downloads.jsonl | jq -r '.totals.all')
+ bins=$(tail -n1 metrics/release-downloads.jsonl | jq -r '.totals.binary')
+ git add metrics/
+ # [skip ci] is belt-and-braces. A push made with the default
+ # GITHUB_TOKEN already triggers no workflow runs (GitHub blocks that
+ # to prevent recursion), so this commit does NOT kick off the CI or
+ # the 8-target cross-compile in release.yml. The marker keeps that
+ # true if someone ever swaps in a PAT.
+ git commit -m "chore(metrics): release downloads $(date -u +%F) — ${total} assets, ${bins} binaries [skip ci]" \
+ -m "Automated daily snapshot (.github/workflows/release-metrics.yml). GitHub keeps no history for download_count; this line is the history."
+ # Rebase rather than fail if a human pushed while we were collecting.
+ git pull --rebase --autostash origin "${GITHUB_REF_NAME}"
+ git push origin "HEAD:${GITHUB_REF_NAME}"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 27f1e8eff..83d7c03fa 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Fixed
+
+- **The installer is now fail-closed on checksum *verification*, not just on
+ checksum *download*.** `landing/get` printed
+ `warning: sha256sum/shasum not found — skipping checksum verification` and
+ installed anyway — which is not what "refusing to install an unverified
+ binary", three lines above it, implies. It now searches `sha256sum`,
+ `shasum`, `openssl`, `sha256`, `busybox` and `cksum`, and stops if none is
+ present. A machine with no hashing tool at all can still proceed, but only by
+ setting `XERJ_INSECURE_SKIP_CHECKSUM=1` — an explicit choice, made by the
+ user, not a silent default. The downloaded checksum is also validated as 64
+ hex characters before use.
+
+- **`XERJ_LIBC=gnu` makes the glibc Linux builds reachable from the one-line
+ installer again.** `landing/get:61` unconditionally overrode the target with
+ `unknown-linux-musl` after the `case` arm had set `unknown-linux-gnu`, so the
+ script could never request a linux-gnu asset — while the code read as though
+ it could. musl remains the deliberate default (static, no glibc-version
+ floor, and xerj links jemalloc so musl's allocator is not in the path), and
+ the comment now says so; `XERJ_LIBC=gnu` opts into the glibc build.
+
+### Added
+
+- **`/get` and `/get.ps1` are counted.** `functions/get.js` (a Cloudflare Pages
+ Function) serves the installer straight out of `landing/get`, unchanged, and
+ records the request. The install path had never had a counter of any kind —
+ `curl` runs no JavaScript, so no page beacon could ever observe it, and the
+ number of installs was simply unknown. It records timestamp, country,
+ User-Agent and a coarse OS guess; it records **no IP address, no cookie and
+ no identifier of any kind**, so two installs by one person cannot be
+ distinguished from two installs by two people. It is fail-open: if the
+ storage binding is missing or the write throws, the installer is still
+ served. **No telemetry was added to the xerj binary, and none is planned.**
+
+- **`metrics/release-downloads.jsonl` + a daily GitHub Action.** GitHub reports
+ release `download_count` as a running total and keeps no history, so the one
+ uninflated adoption number this project has could be read but never trended.
+ One committed line per day turns it into a series. `scripts/adoption-snapshot.sh`
+ prints the funnel on demand, including which repo-level numbers are
+ contaminated and why.
+
## [1.0.0-rc.13] - 2026-08-08
### Security
diff --git a/functions/get.js b/functions/get.js
new file mode 100644
index 000000000..a2fb25c15
--- /dev/null
+++ b/functions/get.js
@@ -0,0 +1,281 @@
+// /get and /get.ps1 — serve the installer script and count the request.
+//
+// ─────────────────────────── PRIVACY POSTURE ────────────────────────────
+// This counts REQUESTS TO OUR WEB SERVER. It is not telemetry: nothing is
+// compiled into the xerj binary, nothing runs on the user's machine, and
+// nothing is sent back after the install. `curl` executes no JavaScript, so
+// there is no beacon, no cookie and no storage on the client side either.
+//
+// What is recorded, per request:
+// ts ISO-8601 timestamp
+// country request.cf.country — Cloudflare's 2-letter country code
+// ua User-Agent header, truncated to 200 chars
+// kind installer | browser | bot | unknown (derived from ua)
+// os/arch coarse guess derived from ua only (may be "unknown")
+// script "get" or "get.ps1"
+// ver the XERJ_VERSION-ish ?v= query param, if the caller sent one
+//
+// What is deliberately NOT recorded:
+// - NO IP address. Not cf-connecting-ip, not x-forwarded-for, not a hash
+// of either. functions/lead.js DOES store `ip`; that was a deliberate
+// divergence, not an oversight — a lead is a person who typed their
+// email in, an installer request is not.
+// - NO cookie, NO Set-Cookie, NO localStorage, NO unique or stable
+// identifier of any kind. Two installs by the same person are
+// indistinguishable from two installs by two people, by design.
+// - NO Referer, NO Accept-Language, NO TLS/JA3 fingerprint, no
+// request.cf fields beyond `country` (city, ASN, postal code and
+// latitude/longitude are all available here and all discarded).
+// - NO Ray ID / request id.
+// The result is a count with a coarse platform and country breakdown, and
+// nothing that can follow a person between two requests. That is the entire
+// intended capability. If you extend this file, keep it that way.
+//
+// ──────────────────────────── FAIL-OPEN RULE ────────────────────────────
+// The install must never depend on the counter. The script body is resolved
+// and the Response is built FIRST; the R2 write is handed to waitUntil() so
+// it runs after the response is already on its way, and every failure path
+// (no binding, throw, timeout) is swallowed. A broken counter degrades to
+// "we learn nothing", never to "the install breaks".
+//
+// ───────────────────────────── DEPLOYMENT ───────────────────────────────
+// Bucket bound as INSTALLS (see wrangler.toml). Until that bucket exists the
+// function serves the script and logs one line to the Pages console —
+// working install, no counting.
+//
+// landing/_routes.json is what guarantees this function actually owns /get
+// rather than the static asset shadowing it. If you delete that file, the
+// counter may silently stop being invoked while /get keeps working.
+
+const CT = 'text/plain; charset=utf-8';
+
+// Cache-Control on the installer used to be `public, max-age=300` (set in
+// landing/_headers). A cached response never reaches this function, so a
+// counter behind a 5-minute cache would undercount by exactly the cache hit
+// rate — an unknown number. no-store is the price of the count; the body is
+// ~8 KB and `curl | sh` fetches it once per install.
+const HEADERS = {
+ 'content-type': CT,
+ 'cache-control': 'no-store',
+ 'x-content-type-options': 'nosniff',
+};
+
+// Bot/crawler UA substrings (lowercase). Kept deliberately short: this
+// classifies, it does not block. Anything unmatched stays "unknown" rather
+// than being quietly counted as a human.
+const BOT_HINTS = [
+ 'bot', 'crawler', 'spider', 'slurp', 'facebookexternalhit', 'preview',
+ 'monitor', 'uptime', 'scanner', 'python-requests', 'go-http-client',
+ 'okhttp', 'java/', 'libwww-perl', 'headlesschrome', 'axios', 'node-fetch',
+];
+
+/** Coarse request class from the UA alone. No other input. */
+function classify(ua) {
+ const s = ua.toLowerCase();
+ if (!s) return 'unknown';
+ // Order matters: curl/wget/powershell are checked first because some
+ // scanners advertise "curl" *and* "bot"; an installer-shaped fetch is the
+ // thing we are counting, so it wins ties only when no bot hint is present.
+ const looksBot = BOT_HINTS.some((h) => s.includes(h));
+ if (!looksBot && /^(curl|wget|fetch)\//.test(s)) return 'installer';
+ if (!looksBot && (s.includes('powershell') || s.includes('windowspowershell'))) return 'installer';
+ if (looksBot) return 'bot';
+ if (s.startsWith('mozilla/')) return 'browser';
+ return 'unknown';
+}
+
+/**
+ * Coarse OS/arch guess from the UA. Returns "unknown" freely — a wrong guess
+ * is worse than no guess, because the platform mix is used to decide which
+ * targets get built.
+ *
+ * Note the honest limit: `curl/8.5.0` (the overwhelmingly common installer
+ * UA) carries NO platform at all, so most installer rows are unknown/unknown.
+ * The platform breakdown that matters still comes from the per-asset release
+ * download counts (metrics/release-downloads.jsonl), not from here.
+ */
+function platform(ua) {
+ const s = ua.toLowerCase();
+ let os = 'unknown';
+ if (s.includes('windows') || s.includes('win32') || s.includes('win64') || s.includes('mingw')) os = 'windows';
+ else if (s.includes('mac os') || s.includes('macos') || s.includes('darwin')) os = 'macos';
+ else if (s.includes('android')) os = 'android';
+ else if (s.includes('linux')) os = 'linux';
+ else if (s.includes('freebsd')) os = 'freebsd';
+
+ let arch = 'unknown';
+ if (s.includes('aarch64') || s.includes('arm64')) arch = 'aarch64';
+ else if (s.includes('x86_64') || s.includes('x64') || s.includes('amd64') || s.includes('win64')) arch = 'x86_64';
+ return { os, arch };
+}
+
+/** Which script this request is for. Anything else is not ours to serve. */
+function scriptFor(pathname) {
+ if (pathname === '/get') return 'get';
+ if (pathname === '/get.ps1') return 'get.ps1';
+ return null;
+}
+
+/**
+ * Write one immutable record. One object per request: no read-modify-write,
+ * so concurrent installs cannot lose each other's counts. Aggregation happens
+ * at read time (scripts/adoption-snapshot.sh, or the ?token= export below).
+ * Date-prefixed so a range read never has to list the whole bucket.
+ */
+async function record(env, req, script) {
+ if (!env || !env.INSTALLS) {
+ console.log('[get] no INSTALLS binding; not counting', script);
+ return;
+ }
+ const ua = (req.headers.get('user-agent') || '').slice(0, 200);
+ const { os, arch } = platform(ua);
+ const now = new Date();
+ const day = now.toISOString().slice(0, 10);
+ let ver = '';
+ try { ver = (new URL(req.url).searchParams.get('v') || '').slice(0, 40); } catch (_) {}
+
+ const row = {
+ ts: now.toISOString(),
+ script,
+ kind: classify(ua),
+ country: (req.cf && req.cf.country) || '',
+ os,
+ arch,
+ ua,
+ ...(ver ? { ver } : {}),
+ };
+ // crypto.randomUUID() here is a KEY, not an identity: it is generated
+ // server-side per request and never returned to the client, so it cannot
+ // correlate two requests. It exists only so two simultaneous writes do not
+ // overwrite one another.
+ await env.INSTALLS.put(
+ `installs/${day}/${now.toISOString()}_${crypto.randomUUID()}.json`,
+ JSON.stringify(row),
+ { httpMetadata: { contentType: 'application/json' } },
+ );
+}
+
+export async function onRequestGet(context) {
+ const { request, env } = context;
+ const url = new URL(request.url);
+ const script = scriptFor(url.pathname);
+ if (!script) return new Response('not found\n', { status: 404, headers: HEADERS });
+
+ // Export path: ?token=… returns the aggregate instead of the script. Guarded
+ // exactly like lead.js — needs BOTH a caller token and a configured secret,
+ // so an unset secret can never open the export.
+ const token = url.searchParams.get('token');
+ if (token && env && env.INSTALLS_TOKEN && token === env.INSTALLS_TOKEN) {
+ return exportStats(env, url);
+ }
+
+ // 1. Resolve the script body. env.ASSETS bypasses Functions and reads the
+ // static file straight out of the deployment, so landing/get stays the
+ // single source of truth — this function never carries a copy that can
+ // drift from the file people audit at https://xerj.org/get.
+ let body;
+ try {
+ const asset = await env.ASSETS.fetch(new URL(`/${script}`, url.origin).toString());
+ if (!asset.ok) throw new Error(`asset ${script} -> ${asset.status}`);
+ body = await asset.text();
+ } catch (e) {
+ // Nothing sane to fall back to: serving a stale inlined copy of an
+ // installer would be worse than failing loudly, and redirecting to a
+ // third-party raw-file host would change what `curl | sh` trusts.
+ // The body below is valid in BOTH target shells — `#` starts a comment and
+ // `exit 1` is a statement in sh and in PowerShell alike — so whichever of
+ // the two pipelines receives it stops with a non-zero status and a message,
+ // instead of executing a fragment of an error page.
+ console.log('[get] asset fetch failed:', String(e));
+ return new Response(
+ `# xerj: the installer could not be served right now.\n` +
+ `# Install directly from the release page instead:\n` +
+ `# https://github.com/xerj-org/xerj/releases/latest\n` +
+ `exit 1\n`,
+ { status: 503, headers: HEADERS },
+ );
+ }
+
+ // 2. Count AFTER the body is in hand and OFF the response path. waitUntil
+ // keeps the worker alive for the write without delaying a single byte to
+ // the installer. Errors are swallowed here, on purpose.
+ // (context.waitUntil, not a destructured copy — never rely on the method
+ // staying bound after destructuring.)
+ try {
+ const p = record(env, request, script).catch((e) => console.log('[get] count failed:', String(e)));
+ if (typeof context.waitUntil === 'function') context.waitUntil(p);
+ } catch (e) {
+ console.log('[get] count dispatch failed:', String(e));
+ }
+
+ return new Response(body, { headers: HEADERS });
+}
+
+// HEAD is what link checkers and some proxies send. Serve the right headers
+// without a body, and do not count it — it is not an install attempt.
+export async function onRequestHead(context) {
+ const url = new URL(context.request.url);
+ if (!scriptFor(url.pathname)) return new Response(null, { status: 404, headers: HEADERS });
+ return new Response(null, { headers: HEADERS });
+}
+
+/**
+ * Token-guarded read-out. Returns aggregates by default (that is all anyone
+ * should need); ?format=raw dumps the rows so they can be re-aggregated.
+ * Bounded by ?days= (default 30, max 365) so this can never walk an unbounded
+ * bucket.
+ */
+async function exportStats(env, url) {
+ const jsonHeaders = { 'content-type': 'application/json', 'cache-control': 'no-store' };
+ if (!env.INSTALLS) {
+ return new Response(JSON.stringify({ ok: false, error: 'no INSTALLS binding' }), { status: 503, headers: jsonHeaders });
+ }
+ const days = Math.min(Math.max(parseInt(url.searchParams.get('days') || '30', 10) || 30, 1), 365);
+ const today = new Date();
+ const wanted = [];
+ for (let i = 0; i < days; i++) {
+ const d = new Date(today.getTime() - i * 86400000);
+ wanted.push(d.toISOString().slice(0, 10));
+ }
+
+ const rows = [];
+ for (const day of wanted) {
+ let cursor;
+ do {
+ const page = await env.INSTALLS.list({ prefix: `installs/${day}/`, limit: 1000, cursor });
+ for (const obj of page.objects) {
+ const o = await env.INSTALLS.get(obj.key);
+ if (!o) continue;
+ try { rows.push(JSON.parse(await o.text())); } catch (_) {}
+ }
+ cursor = page.truncated ? page.cursor : undefined;
+ } while (cursor);
+ }
+
+ if (url.searchParams.get('format') === 'raw') {
+ return new Response(JSON.stringify({ ok: true, days, count: rows.length, rows }, null, 2), { headers: jsonHeaders });
+ }
+
+ const bump = (m, k) => { m[k || 'unknown'] = (m[k || 'unknown'] || 0) + 1; };
+ const by_day = {}, by_kind = {}, by_country = {}, by_os = {}, by_script = {};
+ for (const r of rows) {
+ bump(by_day, String(r.ts || '').slice(0, 10));
+ bump(by_kind, r.kind);
+ bump(by_country, r.country);
+ bump(by_os, r.os);
+ bump(by_script, r.script);
+ }
+ const installerish = rows.filter((r) => r.kind === 'installer').length;
+ return new Response(JSON.stringify({
+ ok: true,
+ window_days: days,
+ total_requests: rows.length,
+ installer_shaped_requests: installerish,
+ caveat:
+ 'A request to /get is a request, not an install. It does not prove the ' +
+ 'download succeeded, the checksum matched, or the binary was ever run. ' +
+ 'kind=installer is a User-Agent heuristic and can be spoofed. Compare ' +
+ 'against metrics/release-downloads.jsonl before quoting either number.',
+ by_day, by_script, by_kind, by_os, by_country,
+ }, null, 2), { headers: jsonHeaders });
+}
diff --git a/functions/get.ps1.js b/functions/get.ps1.js
new file mode 100644
index 000000000..6d4fb770f
--- /dev/null
+++ b/functions/get.ps1.js
@@ -0,0 +1,11 @@
+// /get.ps1 — the Windows installer, same counter as /get.
+//
+// PRIVACY POSTURE: identical to functions/get.js, which is the only place the
+// behaviour is implemented. Read the header comment there — it is the whole
+// contract (no IP, no cookie, no identifier, fail-open).
+//
+// Pages derives the route from the file name minus the .js extension, so this
+// file answers /get.ps1. It holds no logic of its own on purpose: the handler
+// branches on request pathname, so there is exactly one implementation and
+// exactly one set of privacy rules to audit.
+export { onRequestGet, onRequestHead } from './get.js';
diff --git a/landing/_headers b/landing/_headers
index 5783cb288..b961201f8 100644
--- a/landing/_headers
+++ b/landing/_headers
@@ -33,7 +33,20 @@
# The one-line installer: curl -fsSL https://xerj.org/get | sh
# Serve as plain text so browsers display it (auditable) and curl gets
-# a clean script. Short cache so a fixed installer propagates quickly.
+# a clean script.
+#
+# NOTE (2026-08-08): /get and /get.ps1 are now answered by the Pages
+# Function functions/get.js, which counts the request before serving the
+# script body straight out of these same static files (env.ASSETS). The
+# Function sets its own Content-Type / Cache-Control / nosniff, because
+# _headers rules are not guaranteed to apply to Function responses. The
+# two blocks below therefore describe the FALLBACK path — what a client
+# gets if the Function is not invoked (Functions disabled, or the route
+# dropped from landing/_routes.json). Keep them in sync with the headers
+# in functions/get.js.
+#
+# The Function serves no-store rather than max-age=300: a cached response
+# never reaches the origin, so a cache hit is an uncounted install.
/get
Content-Type: text/plain; charset=utf-8
Cache-Control: public, max-age=300
diff --git a/landing/_routes.json b/landing/_routes.json
new file mode 100644
index 000000000..83e205634
--- /dev/null
+++ b/landing/_routes.json
@@ -0,0 +1,5 @@
+{
+ "version": 1,
+ "include": ["/get", "/get.ps1", "/lead"],
+ "exclude": []
+}
diff --git a/landing/docs/install.html b/landing/docs/install.html
index 54fb1fd74..a1c3bd8d1 100644
--- a/landing/docs/install.html
+++ b/landing/docs/install.html
@@ -136,6 +136,10 @@
<pre class="code">$ curl -fsSL https://xerj.org/get | sh</pre>
<p><strong>Windows</strong> (x64 and ARM64, PowerShell):</p>
<pre class="code">&gt; powershell -ExecutionPolicy Bypass -c "irm https://xerj.org/get.ps1 | iex"</pre>
+ <p>Verification is <strong>fail-closed</strong>: if the checksum cannot be downloaded, or no SHA-256 tool (<code class="inline">sha256sum</code>, <code class="inline">shasum</code>, <code class="inline">openssl</code>, <code class="inline">busybox</code>…) can be found, the installer stops rather than installing an unverified binary.</p>
+ <p>On Linux the one-liner installs the <strong>static musl</strong> build by default — it runs on any distro including Alpine and has no glibc-version floor. Ask for the glibc build explicitly if you need it:</p>
+<pre class="code">$ curl -fsSL https://xerj.org/get | XERJ_LIBC=gnu sh</pre>
+ <p>Other environment overrides: <code class="inline">XERJ_VERSION</code> (install a specific tag), <code class="inline">XERJ_INSTALL_DIR</code> (default <code class="inline">~/.local/bin</code>), <code class="inline">XERJ_REPO</code>.</p>
<h2>Manual download</h2>
<p>Every release publishes eight targets, each with a <code class="inline">.sha256</code> alongside: <code class="inline">x86_64</code>/<code class="inline">aarch64</code> × <code class="inline">unknown-linux-musl</code> (static, any distro), <code class="inline">unknown-linux-gnu</code>, <code class="inline">apple-darwin</code>, and <code class="inline">pc-windows-msvc</code> (.zip).</p>
diff --git a/landing/get b/landing/get
index 28ba4aad2..d3c69b42f 100644
--- a/landing/get
+++ b/landing/get
@@ -10,6 +10,11 @@
# XERJ_VERSION=v0.1.0 install a specific tag (default: latest release)
# XERJ_INSTALL_DIR=/path install location (default: ~/.local/bin, else ./ )
# XERJ_REPO=owner/name source repo (default: xerj-org/xerj)
+# XERJ_LIBC=gnu|musl Linux C library (default: musl — see below)
+# XERJ_INSECURE_SKIP_CHECKSUM=1
+# install without verifying SHA-256. Only useful on a
+# box with no hashing tool at all; you are choosing to
+# run an unverified binary.
# =============================================================================
set -eu
@@ -46,8 +51,20 @@ fi
# Windows x64 / ARM64 (via Git Bash / MSYS here; native PowerShell:
# powershell -ExecutionPolicy Bypass -c "irm https://xerj.org/get.ps1 | iex")
os=$(uname -s); arch=$(uname -m)
+# Linux defaults to the fully-static musl build. That is a deliberate choice,
+# not a fallback:
+# * it runs on any distro including Alpine, with no glibc-version floor —
+# a gnu binary linked against a newer glibc dies at exec on an older host
+# ("GLIBC_2.xx not found"), which is an install failure we cannot see;
+# * the usual objection to musl, its slow malloc, does not apply: xerj links
+# jemalloc as the global allocator on every non-MSVC target
+# (engine/crates/xerj-server/Cargo.toml).
+# The gnu artifacts are still published and still supported — ask for them
+# with XERJ_LIBC=gnu. (Before 2026-08-08 an unconditional override below made
+# gnu unreachable from this script while the case arm still claimed gnu; the
+# comment and the behaviour now agree.)
case "$os" in
- Linux) plat="unknown-linux-gnu"; ext="tar.gz"; bin="xerj" ;;
+ Linux) plat="unknown-linux-musl"; ext="tar.gz"; bin="xerj" ;;
Darwin) plat="apple-darwin"; ext="tar.gz"; bin="xerj" ;;
MINGW*|MSYS*|CYGWIN*) plat="pc-windows-msvc"; ext="zip"; bin="xerj.exe" ;;
*) die "unsupported OS: $os (xerj ships Linux, macOS and Windows builds)" ;;
@@ -57,8 +74,15 @@ case "$arch" in
aarch64|arm64) cpu="aarch64" ;;
*) die "unsupported CPU: $arch (xerj ships x86_64/amd64 and aarch64/arm64 builds for Linux, macOS and Windows)" ;;
esac
-# Linux: prefer the fully-static musl build (runs on any distro, incl. Alpine).
-if [ "$os" = "Linux" ]; then plat="unknown-linux-musl"; fi
+if [ "$os" = "Linux" ]; then
+ case "${XERJ_LIBC:-musl}" in
+ musl) ;; # the default set above
+ gnu) plat="unknown-linux-gnu" ;;
+ *) die "XERJ_LIBC must be 'gnu' or 'musl' (got '${XERJ_LIBC}')" ;;
+ esac
+elif [ -n "${XERJ_LIBC:-}" ]; then
+ say "${YEL}note:${RST} XERJ_LIBC only applies to Linux — ignoring it on ${os}"
+fi
target="${cpu}-${plat}"
# --- resolve version --------------------------------------------------------
@@ -89,16 +113,52 @@ DL "${base}/${asset}" "${tmp}/${asset}" \
|| die "download failed for ${target}. Available assets: https://github.com/${REPO}/releases/tag/${tag}"
# --- verify checksum (fail closed — every release publishes the .sha256) ----
+#
+# DO NOT REORDER THE NEXT LINE BELOW THE TOOL SEARCH. The checksum is fetched
+# unconditionally, before we look for a hashing tool, so every installer run
+# downloads exactly one binary and exactly one matching .sha256. That 1:1
+# pairing is the ONLY fingerprint that lets GitHub's per-asset download counts
+# be read as installer runs (see metrics/README.md); checking for the tool
+# first would skip the fetch on some machines and silently destroy the only
+# install metric this project has.
DL "${base}/${asset}.sha256" "${tmp}/${asset}.sha256" 2>/dev/null \
|| die "could not download checksum ${asset}.sha256 — refusing to install an unverified binary"
-want=$(awk '{print $1}' "${tmp}/${asset}.sha256")
-if command -v sha256sum >/dev/null 2>&1; then got=$(sha256sum "${tmp}/${asset}" | awk '{print $1}')
-elif command -v shasum >/dev/null 2>&1; then got=$(shasum -a 256 "${tmp}/${asset}" | awk '{print $1}')
-else got=""; fi
-if [ -n "$got" ]; then
- [ "$got" = "$want" ] && ok "sha256 verified" || die "sha256 mismatch (want $want, got $got)"
+want=$(awk '{print $1}' "${tmp}/${asset}.sha256" | tr 'A-F' 'a-f')
+[ "${#want}" -eq 64 ] || die "malformed ${asset}.sha256 (expected 64 hex chars) — refusing to install an unverified binary"
+case "$want" in *[!0-9a-f]*) die "malformed ${asset}.sha256 (not hex) — refusing to install an unverified binary" ;; esac
+
+# Try hard to find a SHA-256 implementation before giving up: coreutils,
+# perl-shasum, openssl, busybox, and the BSD/macOS spellings.
+got=''
+if command -v sha256sum >/dev/null 2>&1; then got=$(sha256sum "${tmp}/${asset}" | awk '{print $1}')
+elif command -v shasum >/dev/null 2>&1; then got=$(shasum -a 256 "${tmp}/${asset}" | awk '{print $1}')
+elif command -v openssl >/dev/null 2>&1; then got=$(openssl dgst -sha256 "${tmp}/${asset}" | awk '{print $NF}')
+elif command -v sha256 >/dev/null 2>&1; then got=$(sha256 -q "${tmp}/${asset}" | awk '{print $NF}')
+elif command -v busybox >/dev/null 2>&1; then got=$(busybox sha256sum "${tmp}/${asset}" | awk '{print $1}')
+elif command -v cksum >/dev/null 2>&1; then got=$(cksum -a sha256 "${tmp}/${asset}" 2>/dev/null | awk '{print $NF}')
+fi
+got=$(printf '%s' "$got" | tr 'A-F' 'a-f')
+
+# Fail CLOSED. Until 2026-08-08 this branch printed a warning and installed
+# anyway, which is not what "refusing to install an unverified binary" three
+# lines up promises. If a machine genuinely has no hashing tool, the user can
+# still opt in explicitly — but it has to be their decision, not ours.
+if [ -z "$got" ]; then
+ if [ "${XERJ_INSECURE_SKIP_CHECKSUM:-}" = "1" ]; then
+ say "${YEL}warning:${RST} no SHA-256 tool found and XERJ_INSECURE_SKIP_CHECKSUM=1 —"
+ say "${YEL} ${RST} installing an ${BOLD}unverified${RST} binary at your request (expected ${want})"
+ else
+ die "no SHA-256 tool found (tried sha256sum, shasum, openssl, sha256, busybox, cksum)
+ — refusing to install an unverified binary.
+ Install coreutils or openssl and re-run, or verify by hand:
+ expected sha256: ${want}
+ source: ${base}/${asset}
+ To install anyway (not recommended): XERJ_INSECURE_SKIP_CHECKSUM=1"
+ fi
+elif [ "$got" = "$want" ]; then
+ ok "sha256 verified"
else
- say "${YEL}warning:${RST} sha256sum/shasum not found — skipping checksum verification"
+ die "sha256 mismatch (want $want, got $got)"
fi
# --- extract ----------------------------------------------------------------
diff --git a/metrics/README.md b/metrics/README.md
new file mode 100644
index 000000000..deaf48481
--- /dev/null
+++ b/metrics/README.md
@@ -0,0 +1,102 @@
+# metrics/
+
+Committed adoption data, and the rules for reading it.
+
+Everything here is either public GitHub metadata or a count of requests to a
+web server we operate. **Nothing in this directory came from a user's machine.**
+
+---
+
+## Privacy posture, in one paragraph
+
+XERJ ships **no telemetry**. The binary does not phone home, on first run or
+ever, and there is no plan to add it: this is an Apache-2.0 tool that engineers
+run on their own hardware, and a silent phone-home would cost more credibility
+than the data is worth. What *is* instrumented is the **distribution surface** —
+the website and the installer download — because a request to a web server is
+already observable to whoever operates that server. The install counter
+(`functions/get.js`) stores a timestamp, a country, a User-Agent string and a
+coarse OS guess derived from it. It stores **no IP address, no cookie, and no
+identifier of any kind**, so two installs by the same person are
+indistinguishable from two installs by two people. That is by design and it is
+the whole intended capability.
+
+---
+
+## `release-downloads.jsonl`
+
+One JSON object per line, one line per day, appended by
+[`.github/workflows/release-metrics.yml`](../.github/workflows/release-metrics.yml)
+(collector: [`.github/scripts/snapshot-release-downloads.sh`](../.github/scripts/snapshot-release-downloads.sh)).
+
+```jsonc
+{
+ "date": "2026-08-08",
+ "collected_at": "2026-08-08T06:00:12Z",
+ "repo": "xerj-org/xerj",
+ "totals": { "releases": 12, "binary": 88, "checksum": 57, "all": 145 },
+ "releases": {
+ "v1.0.0-rc.12": {
+ "published_at": "…", "prerelease": false,
+ "assets": { "xerj-1.0.0-rc.12-x86_64-unknown-linux-musl.tar.gz": 1, … }
+ }
+ },
+ "traffic_14d": { "clones": {"count":…, "uniques":…}, "views": {…} }
+}
+```
+
+**Why this file exists.** GitHub reports `download_count` as a running total and
+keeps no history. Nothing was snapshotting it, so the only uninflated adoption
+number the project had could be read once but never trended. One line a day
+turns a scalar into a series, at zero infrastructure cost.
+
+JSONL, not JSON: a day is one appended line, so the diff is one line, two
+concurrent writers cannot corrupt the array, and `jq -c` streams it. Re-running
+the collector on the same day **replaces** that day's line rather than adding a
+second one.
+
+### Reading it correctly
+
+- `totals.binary` counts **asset fetches, not installs**. It includes CI,
+ mirrors, scanners and re-downloads.
+- `totals.binary` vs `totals.checksum` is the useful pair. `landing/get` fetches
+ exactly one binary and exactly one matching `.sha256` per run, in that order,
+ **deliberately** — so installer-shaped traffic pairs 1:1. A binary count well
+ above the checksum count is traffic that is not the installer. Do not reorder
+ those two fetches in `landing/get` without replacing this fingerprint first.
+- `traffic_14d` is a **14-day rolling window**, not a daily figure and not a
+ lifetime total. Consecutive snapshots overlap by 13 days: **never sum them.**
+ It is captured only because GitHub expires it — a day not snapshotted is gone
+ permanently. It is `null` when the collecting token lacks push scope.
+- Nothing here says whether a downloaded binary was ever run. Nothing can.
+
+---
+
+## What is *not* in this directory
+
+Install-counter records live in the Cloudflare R2 bucket `xerj-installs`
+(`functions/get.js`), not in git — they are request logs, they grow per request,
+and they do not belong in the repository. Read them through the token-guarded
+export:
+
+```sh
+curl -s "https://xerj.org/get?token=$INSTALLS_TOKEN&days=30" | jq .
+```
+
+The export returns aggregates and ships its own caveat text. The short version:
+a request to `/get` is a request. It does not prove the download succeeded, the
+checksum matched, or that the binary was ever executed.
+
+---
+
+## Getting the honest funnel
+
+```sh
+scripts/adoption-snapshot.sh
+```
+
+Pulls the numbers live and prints them in three sections: what you can quote,
+what is contaminated (with the reason for each), and what is genuinely blind.
+Repo-level totals on this project — stars, forks, clones — are inflated by a
+synthetic cohort and must not be used as adoption signals; the script computes
+the defensible pre-spike star count for you rather than making you remember it.
diff --git a/metrics/release-downloads.jsonl b/metrics/release-downloads.jsonl
new file mode 100644
index 000000000..f392beccc
--- /dev/null
+++ b/metrics/release-downloads.jsonl
@@ -0,0 +1 @@
+{"date":"2026-08-08","collected_at":"2026-08-08T05:59:50Z","repo":"xerj-org/xerj","totals":{"releases":12,"binary":88,"checksum":57,"all":145},"releases":{"v1.0.0-rc.12":{"published_at":"2026-08-07T18:08:16Z","prerelease":false,"assets":{"xerj-1.0.0-rc.12-aarch64-apple-darwin.tar.gz":1,"xerj-1.0.0-rc.12-aarch64-apple-darwin.tar.gz.sha256":1,"xerj-1.0.0-rc.12-aarch64-pc-windows-msvc.zip":1,"xerj-1.0.0-rc.12-aarch64-pc-windows-msvc.zip.sha256":1,"xerj-1.0.0-rc.12-aarch64-unknown-linux-gnu.tar.gz":1,"xerj-1.0.0-rc.12-aarch64-unknown-linux-gnu.tar.gz.sha256":1,"xerj-1.0.0-rc.12-aarch64-unknown-linux-musl.tar.gz":1,"xerj-1.0.0-rc.12-aarch64-unknown-linux-musl.tar.gz.sha256":1,"xerj-1.0.0-rc.12-x86_64-apple-darwin.tar.gz":1,"xerj-1.0.0-rc.12-x86_64-apple-darwin.tar.gz.sha256":1,"xerj-1.0.0-rc.12-x86_64-pc-windows-msvc.zip":1,"xerj-1.0.0-rc.12-x86_64-pc-windows-msvc.zip.sha256":1,"xerj-1.0.0-rc.12-x86_64-unknown-linux-gnu.tar.gz":2,"xerj-1.0.0-rc.12-x86_64-unknown-linux-gnu.tar.gz.sha256":2,"xerj-1.0.0-rc.12-x86_64-unknown-linux-musl.tar.gz":1,"xerj-1.0.0-rc.12-x86_64-unknown-linux-musl.tar.gz.sha256":1}},"v1.0.0-rc.11":{"published_at":"2026-08-04T19:35:43Z","prerelease":false,"assets":{"xerj-1.0.0-rc.11-aarch64-apple-darwin.tar.gz":3,"xerj-1.0.0-rc.11-aarch64-apple-darwin.tar.gz.sha256":2,"xerj-1.0.0-rc.11-aarch64-pc-windows-msvc.zip":1,"xerj-1.0.0-rc.11-aarch64-pc-windows-msvc.zip.sha256":1,"xerj-1.0.0-rc.11-aarch64-unknown-linux-gnu.tar.gz":1,"xerj-1.0.0-rc.11-aarch64-unknown-linux-gnu.tar.gz.sha256":1,"xerj-1.0.0-rc.11-aarch64-unknown-linux-musl.tar.gz":2,"xerj-1.0.0-rc.11-aarch64-unknown-linux-musl.tar.gz.sha256":2,"xerj-1.0.0-rc.11-x86_64-apple-darwin.tar.gz":1,"xerj-1.0.0-rc.11-x86_64-apple-darwin.tar.gz.sha256":1,"xerj-1.0.0-rc.11-x86_64-pc-windows-msvc.zip":3,"xerj-1.0.0-rc.11-x86_64-pc-windows-msvc.zip.sha256":3,"xerj-1.0.0-rc.11-x86_64-unknown-linux-gnu.tar.gz":3,"xerj-1.0.0-rc.11-x86_64-unknown-linux-gnu.tar.gz.sha256":2,"xerj-1.0.0-rc.11-x86_64-unknown-linux-musl.tar.gz":3,"xerj-1.0.0-rc.11-x86_64-unknown-linux-musl.tar.gz.sha256":3}},"v1.0.0-rc.10":{"published_at":"2026-08-03T18:08:24Z","prerelease":false,"assets":{"xerj-1.0.0-rc.10-aarch64-apple-darwin.tar.gz":2,"xerj-1.0.0-rc.10-aarch64-apple-darwin.tar.gz.sha256":2,"xerj-1.0.0-rc.10-aarch64-pc-windows-msvc.zip":1,"xerj-1.0.0-rc.10-aarch64-pc-windows-msvc.zip.sha256":1,"xerj-1.0.0-rc.10-aarch64-unknown-linux-gnu.tar.gz":1,"xerj-1.0.0-rc.10-aarch64-unknown-linux-gnu.tar.gz.sha256":1,"xerj-1.0.0-rc.10-aarch64-unknown-linux-musl.tar.gz":1,"xerj-1.0.0-rc.10-aarch64-unknown-linux-musl.tar.gz.sha256":1,"xerj-1.0.0-rc.10-x86_64-apple-darwin.tar.gz":3,"xerj-1.0.0-rc.10-x86_64-apple-darwin.tar.gz.sha256":2,"xerj-1.0.0-rc.10-x86_64-pc-windows-msvc.zip":2,"xerj-1.0.0-rc.10-x86_64-pc-windows-msvc.zip.sha256":2,"xerj-1.0.0-rc.10-x86_64-unknown-linux-gnu.tar.gz":1,"xerj-1.0.0-rc.10-x86_64-unknown-linux-gnu.tar.gz.sha256":1,"xerj-1.0.0-rc.10-x86_64-unknown-linux-musl.tar.gz":2,"xerj-1.0.0-rc.10-x86_64-unknown-linux-musl.tar.gz.sha256":2}},"v1.0.0-rc.9":{"published_at":"2026-08-01T06:03:51Z","prerelease":false,"assets":{"xerj-1.0.0-rc.9-aarch64-apple-darwin.tar.gz":1,"xerj-1.0.0-rc.9-aarch64-apple-darwin.tar.gz.sha256":1,"xerj-1.0.0-rc.9-aarch64-pc-windows-msvc.zip":0,"xerj-1.0.0-rc.9-aarch64-pc-windows-msvc.zip.sha256":0,"xerj-1.0.0-rc.9-aarch64-unknown-linux-gnu.tar.gz":0,"xerj-1.0.0-rc.9-aarch64-unknown-linux-gnu.tar.gz.sha256":0,"xerj-1.0.0-rc.9-aarch64-unknown-linux-musl.tar.gz":0,"xerj-1.0.0-rc.9-aarch64-unknown-linux-musl.tar.gz.sha256":0,"xerj-1.0.0-rc.9-x86_64-apple-darwin.tar.gz":0,"xerj-1.0.0-rc.9-x86_64-apple-darwin.tar.gz.sha256":0,"xerj-1.0.0-rc.9-x86_64-pc-windows-msvc.zip":0,"xerj-1.0.0-rc.9-x86_64-pc-windows-msvc.zip.sha256":0,"xerj-1.0.0-rc.9-x86_64-unknown-linux-gnu.tar.gz":2,"xerj-1.0.0-rc.9-x86_64-unknown-linux-gnu.tar.gz.sha256":1,"xerj-1.0.0-rc.9-x86_64-unknown-linux-musl.tar.gz":2,"xerj-1.0.0-rc.9-x86_64-unknown-linux-musl.tar.gz.sha256":2}},"v1.0.0-rc.8":{"published_at":"2026-07-31T15:36:16Z","prerelease":false,"assets":{"xerj-1.0.0-rc.8-aarch64-apple-darwin.tar.gz":4,"xerj-1.0.0-rc.8-aarch64-apple-darwin.tar.gz.sha256":5,"xerj-1.0.0-rc.8-aarch64-pc-windows-msvc.zip":0,"xerj-1.0.0-rc.8-aarch64-pc-windows-msvc.zip.sha256":0,"xerj-1.0.0-rc.8-aarch64-unknown-linux-gnu.tar.gz":0,"xerj-1.0.0-rc.8-aarch64-unknown-linux-gnu.tar.gz.sha256":0,"xerj-1.0.0-rc.8-aarch64-unknown-linux-musl.tar.gz":0,"xerj-1.0.0-rc.8-aarch64-unknown-linux-musl.tar.gz.sha256":0,"xerj-1.0.0-rc.8-x86_64-apple-darwin.tar.gz":0,"xerj-1.0.0-rc.8-x86_64-apple-darwin.tar.gz.sha256":0,"xerj-1.0.0-rc.8-x86_64-pc-windows-msvc.zip":0,"xerj-1.0.0-rc.8-x86_64-pc-windows-msvc.zip.sha256":0,"xerj-1.0.0-rc.8-x86_64-unknown-linux-gnu.tar.gz":0,"xerj-1.0.0-rc.8-x86_64-unknown-linux-gnu.tar.gz.sha256":0,"xerj-1.0.0-rc.8-x86_64-unknown-linux-musl.tar.gz":2,"xerj-1.0.0-rc.8-x86_64-unknown-linux-musl.tar.gz.sha256":2}},"v1.0.0-rc.7":{"published_at":"2026-07-30T21:58:44Z","prerelease":false,"assets":{"xerj-1.0.0-rc.7-aarch64-apple-darwin.tar.gz":3,"xerj-1.0.0-rc.7-aarch64-apple-darwin.tar.gz.sha256":3,"xerj-1.0.0-rc.7-aarch64-pc-windows-msvc.zip":0,"xerj-1.0.0-rc.7-aarch64-pc-windows-msvc.zip.sha256":0,"xerj-1.0.0-rc.7-aarch64-unknown-linux-gnu.tar.gz":0,"xerj-1.0.0-rc.7-aarch64-unknown-linux-gnu.tar.gz.sha256":0,"xerj-1.0.0-rc.7-aarch64-unknown-linux-musl.tar.gz":0,"xerj-1.0.0-rc.7-aarch64-unknown-linux-musl.tar.gz.sha256":0,"xerj-1.0.0-rc.7-x86_64-apple-darwin.tar.gz":0,"xerj-1.0.0-rc.7-x86_64-apple-darwin.tar.gz.sha256":0,"xerj-1.0.0-rc.7-x86_64-pc-windows-msvc.zip":0,"xerj-1.0.0-rc.7-x86_64-pc-windows-msvc.zip.sha256":0,"xerj-1.0.0-rc.7-x86_64-unknown-linux-gnu.tar.gz":1,"xerj-1.0.0-rc.7-x86_64-unknown-linux-gnu.tar.gz.sha256":0,"xerj-1.0.0-rc.7-x86_64-unknown-linux-musl.tar.gz":0,"xerj-1.0.0-rc.7-x86_64-unknown-linux-musl.tar.gz.sha256":0}},"v1.0.0-rc.6":{"published_at":"2026-07-28T18:20:12Z","prerelease":false,"assets":{"xerj-1.0.0-rc.6-aarch64-apple-darwin.tar.gz":2,"xerj-1.0.0-rc.6-aarch64-apple-darwin.tar.gz.sha256":1,"xerj-1.0.0-rc.6-aarch64-pc-windows-msvc.zip":0,"xerj-1.0.0-rc.6-aarch64-pc-windows-msvc.zip.sha256":0,"xerj-1.0.0-rc.6-aarch64-unknown-linux-gnu.tar.gz":0,"xerj-1.0.0-rc.6-aarch64-unknown-linux-gnu.tar.gz.sha256":0,"xerj-1.0.0-rc.6-aarch64-unknown-linux-musl.tar.gz":0,"xerj-1.0.0-rc.6-aarch64-unknown-linux-musl.tar.gz.sha256":0,"xerj-1.0.0-rc.6-x86_64-apple-darwin.tar.gz":0,"xerj-1.0.0-rc.6-x86_64-apple-darwin.tar.gz.sha256":0,"xerj-1.0.0-rc.6-x86_64-pc-windows-msvc.zip":0,"xerj-1.0.0-rc.6-x86_64-pc-windows-msvc.zip.sha256":0,"xerj-1.0.0-rc.6-x86_64-unknown-linux-gnu.tar.gz":0,"xerj-1.0.0-rc.6-x86_64-unknown-linux-gnu.tar.gz.sha256":0,"xerj-1.0.0-rc.6-x86_64-unknown-linux-musl.tar.gz":0,"xerj-1.0.0-rc.6-x86_64-unknown-linux-musl.tar.gz.sha256":0}},"v1.0.0-rc.5":{"published_at":"2026-07-27T18:29:11Z","prerelease":false,"assets":{"xerj-1.0.0-rc.5-aarch64-apple-darwin.tar.gz":0,"xerj-1.0.0-rc.5-aarch64-apple-darwin.tar.gz.sha256":0,"xerj-1.0.0-rc.5-aarch64-pc-windows-msvc.zip":0,"xerj-1.0.0-rc.5-aarch64-pc-windows-msvc.zip.sha256":0,"xerj-1.0.0-rc.5-aarch64-unknown-linux-gnu.tar.gz":0,"xerj-1.0.0-rc.5-aarch64-unknown-linux-gnu.tar.gz.sha256":0,"xerj-1.0.0-rc.5-aarch64-unknown-linux-musl.tar.gz":2,"xerj-1.0.0-rc.5-aarch64-unknown-linux-musl.tar.gz.sha256":2,"xerj-1.0.0-rc.5-x86_64-apple-darwin.tar.gz":0,"xerj-1.0.0-rc.5-x86_64-apple-darwin.tar.gz.sha256":0,"xerj-1.0.0-rc.5-x86_64-pc-windows-msvc.zip":0,"xerj-1.0.0-rc.5-x86_64-pc-windows-msvc.zip.sha256":0,"xerj-1.0.0-rc.5-x86_64-unknown-linux-gnu.tar.gz":1,"xerj-1.0.0-rc.5-x86_64-unknown-linux-gnu.tar.gz.sha256":1,"xerj-1.0.0-rc.5-x86_64-unknown-linux-musl.tar.gz":2,"xerj-1.0.0-rc.5-x86_64-unknown-linux-musl.tar.gz.sha256":0}},"v1.0.0-rc.4":{"published_at":"2026-07-22T19:45:08Z","prerelease":false,"assets":{"xerj-1.0.0-rc.4-aarch64-apple-darwin.tar.gz":4,"xerj-1.0.0-rc.4-aarch64-apple-darwin.tar.gz.sha256":1,"xerj-1.0.0-rc.4-aarch64-pc-windows-msvc.zip":0,"xerj-1.0.0-rc.4-aarch64-pc-windows-msvc.zip.sha256":0,"xerj-1.0.0-rc.4-aarch64-unknown-linux-gnu.tar.gz":1,"xerj-1.0.0-rc.4-aarch64-unknown-linux-gnu.tar.gz.sha256":0,"xerj-1.0.0-rc.4-aarch64-unknown-linux-musl.tar.gz":1,"xerj-1.0.0-rc.4-aarch64-unknown-linux-musl.tar.gz.sha256":0,"xerj-1.0.0-rc.4-x86_64-apple-darwin.tar.gz":0,"xerj-1.0.0-rc.4-x86_64-apple-darwin.tar.gz.sha256":0,"xerj-1.0.0-rc.4-x86_64-pc-windows-msvc.zip":0,"xerj-1.0.0-rc.4-x86_64-pc-windows-msvc.zip.sha256":0,"xerj-1.0.0-rc.4-x86_64-unknown-linux-gnu.tar.gz":1,"xerj-1.0.0-rc.4-x86_64-unknown-linux-gnu.tar.gz.sha256":0,"xerj-1.0.0-rc.4-x86_64-unknown-linux-musl.tar.gz":2,"xerj-1.0.0-rc.4-x86_64-unknown-linux-musl.tar.gz.sha256":0}},"v1.0.0-rc.3":{"published_at":"2026-07-10T20:37:47Z","prerelease":false,"assets":{"xerj-1.0.0-rc.3-aarch64-apple-darwin.tar.gz":0,"xerj-1.0.0-rc.3-aarch64-apple-darwin.tar.gz.sha256":0,"xerj-1.0.0-rc.3-aarch64-pc-windows-msvc.zip":0,"xerj-1.0.0-rc.3-aarch64-pc-windows-msvc.zip.sha256":0,"xerj-1.0.0-rc.3-aarch64-unknown-linux-gnu.tar.gz":0,"xerj-1.0.0-rc.3-aarch64-unknown-linux-gnu.tar.gz.sha256":0,"xerj-1.0.0-rc.3-aarch64-unknown-linux-musl.tar.gz":0,"xerj-1.0.0-rc.3-aarch64-unknown-linux-musl.tar.gz.sha256":0,"xerj-1.0.0-rc.3-x86_64-apple-darwin.tar.gz":0,"xerj-1.0.0-rc.3-x86_64-apple-darwin.tar.gz.sha256":0,"xerj-1.0.0-rc.3-x86_64-pc-windows-msvc.zip":15,"xerj-1.0.0-rc.3-x86_64-pc-windows-msvc.zip.sha256":2,"xerj-1.0.0-rc.3-x86_64-unknown-linux-gnu.tar.gz":2,"xerj-1.0.0-rc.3-x86_64-unknown-linux-gnu.tar.gz.sha256":0,"xerj-1.0.0-rc.3-x86_64-unknown-linux-musl.tar.gz":1,"xerj-1.0.0-rc.3-x86_64-unknown-linux-musl.tar.gz.sha256":0}},"v1.0.0-rc.2":{"published_at":"2026-07-10T16:31:33Z","prerelease":false,"assets":{"xerj-1.0.0-rc.2-aarch64-apple-darwin.tar.gz":0,"xerj-1.0.0-rc.2-aarch64-apple-darwin.tar.gz.sha256":0,"xerj-1.0.0-rc.2-aarch64-pc-windows-msvc.zip":0,"xerj-1.0.0-rc.2-aarch64-pc-windows-msvc.zip.sha256":0,"xerj-1.0.0-rc.2-aarch64-unknown-linux-gnu.tar.gz":0,"xerj-1.0.0-rc.2-aarch64-unknown-linux-gnu.tar.gz.sha256":0,"xerj-1.0.0-rc.2-aarch64-unknown-linux-musl.tar.gz":0,"xerj-1.0.0-rc.2-aarch64-unknown-linux-musl.tar.gz.sha256":0,"xerj-1.0.0-rc.2-x86_64-apple-darwin.tar.gz":0,"xerj-1.0.0-rc.2-x86_64-apple-darwin.tar.gz.sha256":0,"xerj-1.0.0-rc.2-x86_64-pc-windows-msvc.zip":0,"xerj-1.0.0-rc.2-x86_64-pc-windows-msvc.zip.sha256":0,"xerj-1.0.0-rc.2-x86_64-unknown-linux-gnu.tar.gz":0,"xerj-1.0.0-rc.2-x86_64-unknown-linux-gnu.tar.gz.sha256":0,"xerj-1.0.0-rc.2-x86_64-unknown-linux-musl.tar.gz":0,"xerj-1.0.0-rc.2-x86_64-unknown-linux-musl.tar.gz.sha256":0}},"v1.0.0-rc.1":{"published_at":"2026-07-08T15:31:33Z","prerelease":false,"assets":{"xerj-1.0.0-rc.1-aarch64-apple-darwin.tar.gz":0,"xerj-1.0.0-rc.1-aarch64-apple-darwin.tar.gz.sha256":0,"xerj-1.0.0-rc.1-aarch64-pc-windows-msvc.zip":0,"xerj-1.0.0-rc.1-aarch64-pc-windows-msvc.zip.sha256":0,"xerj-1.0.0-rc.1-aarch64-unknown-linux-gnu.tar.gz":0,"xerj-1.0.0-rc.1-aarch64-unknown-linux-gnu.tar.gz.sha256":0,"xerj-1.0.0-rc.1-aarch64-unknown-linux-musl.tar.gz":0,"xerj-1.0.0-rc.1-aarch64-unknown-linux-musl.tar.gz.sha256":0,"xerj-1.0.0-rc.1-x86_64-apple-darwin.tar.gz":0,"xerj-1.0.0-rc.1-x86_64-apple-darwin.tar.gz.sha256":0,"xerj-1.0.0-rc.1-x86_64-pc-windows-msvc.zip":0,"xerj-1.0.0-rc.1-x86_64-pc-windows-msvc.zip.sha256":0,"xerj-1.0.0-rc.1-x86_64-unknown-linux-gnu.tar.gz":0,"xerj-1.0.0-rc.1-x86_64-unknown-linux-gnu.tar.gz.sha256":0,"xerj-1.0.0-rc.1-x86_64-unknown-linux-musl.tar.gz":0,"xerj-1.0.0-rc.1-x86_64-unknown-linux-musl.tar.gz.sha256":0}}},"traffic_14d":{"clones":{"count":4638,"uniques":422},"views":{"count":9195,"uniques":4006}}}
diff --git a/scripts/adoption-snapshot.sh b/scripts/adoption-snapshot.sh
new file mode 100755
index 000000000..86207c452
--- /dev/null
+++ b/scripts/adoption-snapshot.sh
@@ -0,0 +1,236 @@
+#!/usr/bin/env bash
+# ─────────────────────────────────────────────────────────────────────────────
+# adoption-snapshot.sh — the honest adoption funnel for xerj, on demand.
+#
+# Prints three sections, in this order and on purpose:
+# 1. numbers you can quote
+# 2. numbers you must NOT quote, each with the reason it is contaminated
+# 3. numbers that do not exist at all
+#
+# It exists because the repo-level totals GitHub shows on the front page
+# (stars, forks, clones) are, for this repository, inflated by roughly 13x by a
+# synthetic cohort, and quoting them is the fastest available way to lose
+# technical credibility — the evidence is public and anyone can re-run the same
+# queries. Section 2 is therefore not a disclaimer; it is the point.
+#
+# PRIVACY: read-only, public GitHub metadata via `gh api`. Nothing is stored,
+# nothing is sent anywhere, no personal data is collected. Star/fork account
+# names are counted, never printed.
+#
+# Usage:
+# scripts/adoption-snapshot.sh # full report
+# scripts/adoption-snapshot.sh --no-stars # skip the star-cohort scan (~13 API calls)
+# scripts/adoption-snapshot.sh --repo o/n # another repo
+#
+# Requires: gh (authenticated: `gh auth login`), jq.
+# ─────────────────────────────────────────────────────────────────────────────
+set -euo pipefail
+
+REPO="${XERJ_REPO:-xerj-org/xerj}"
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$HERE/.." && pwd)"
+SERIES="$ROOT/metrics/release-downloads.jsonl"
+DO_STARS=1
+
+# Accounts that are us. There is no API for this: xerj-org is a personal
+# account, not an Organization, so /orgs/.../members 404s. Keep this list
+# current or the external-contributor count silently drifts up.
+FIRST_PARTY='["xerj-org","xerj-team"]'
+
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --repo) REPO="$2"; shift 2 ;;
+ --no-stars) DO_STARS=0; shift ;;
+ -h|--help) sed -n '2,26p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+ *) echo "unknown argument: $1" >&2; exit 2 ;;
+ esac
+done
+
+command -v gh >/dev/null || { echo "gh is required (https://cli.github.com)" >&2; exit 2; }
+command -v jq >/dev/null || { echo "jq is required" >&2; exit 2; }
+gh auth status >/dev/null 2>&1 || { echo "gh is not authenticated — run: gh auth login" >&2; exit 2; }
+
+W="$(mktemp -d)"; trap 'rm -rf "$W"' EXIT
+b() { printf '\033[1m%s\033[0m\n' "$*"; }
+rule() { printf '%s\n' "────────────────────────────────────────────────────────────────────────"; }
+
+echo
+b "xerj adoption snapshot — ${REPO} — $(date -u +'%F %T UTC')"
+rule
+
+# ── data pulls ───────────────────────────────────────────────────────────────
+gh api "repos/${REPO}" > "$W/repo.json"
+gh api --paginate "repos/${REPO}/releases?per_page=100" \
+ | jq -s 'flatten(1) | map({tag_name, published_at,
+ assets: ((.assets // []) | map({name, download_count}))})' \
+ > "$W/releases.json"
+gh api --paginate "repos/${REPO}/pulls?state=all&per_page=100" \
+ | jq -s 'flatten(1) | map({user: (.user.login // ""), created_at, merged_at})' > "$W/pulls.json"
+gh api --paginate "repos/${REPO}/issues?state=all&per_page=100" \
+ | jq -s 'flatten(1) | map(select(.pull_request == null) | {user: (.user.login // ""), created_at})' > "$W/issues.json"
+
+# ═════════════════════════ 1. NUMBERS YOU CAN QUOTE ══════════════════════════
+b "1. QUOTABLE — nothing has inflated these"
+echo
+
+jq -r --argjson fp "$FIRST_PARTY" '
+ def is_sum: (.name | endswith(".sha256"));
+ (map(.assets) | flatten(1)) as $a |
+ ($a | map(select(is_sum | not) | .download_count) | add // 0) as $bin |
+ ($a | map(select(is_sum) | .download_count) | add // 0) as $sum |
+ # Paired ceiling: the installer fetches exactly one binary and exactly one
+ # matching .sha256 per run (landing/get keeps that order deliberately), so
+ # min(binary, its checksum) is an UPPER BOUND on installer runs for that
+ # asset. Unpaired binary downloads cannot be installer runs.
+ ( map(. as $r
+ | ($r.assets | map(select(is_sum | not))) as $bins
+ | ($r.assets | map(select(is_sum)) | map({key: (.name|rtrimstr(".sha256")), value: .download_count}) | from_entries) as $sums
+ | ($bins | map([.download_count, ($sums[.name] // 0)] | min) | add // 0))
+ | add // 0 ) as $paired |
+ # A release where every one of its 8 platform archives AND all 8 checksums
+ # were downloaded is an automated all-platform sweep, not eight humans: no
+ # machine is eight platforms at once. Subtract one sweep from each.
+ ( map(select((.assets | map(select(is_sum|not) | select(.download_count > 0)) | length) >= 8
+ and (.assets | map(select(is_sum) | select(.download_count > 0)) | length) >= 8))
+ | length ) as $swept |
+ " release asset downloads \($bin + $sum) (\($bin) binaries + \($sum) checksums, all-time)",
+ " binary:checksum ratio \(if $sum == 0 then "n/a" else ((($bin*100/$sum)|floor)/100) end) (installer traffic pairs 1:1; far from 1.0 = something else)",
+ " installer runs (ceiling) ≤ \($paired) matched binary+checksum pairs",
+ " minus one sweep per swept release ≤ \($paired - ($swept * 8)) (\($swept) release\(if $swept == 1 then "" else "s" end) show all 16 assets downloaded)",
+ "",
+ " A ceiling is not a count. It counts fetch pairs, not people, and says",
+ " nothing about whether the archive was ever extracted or run. This is the",
+ " mechanical rule; the 2026-08-08 hand audit applied two extra judgements",
+ " (capping one 15-download outlier, and excluding targets the installer",
+ " could not then request) and landed at ≤28. Expect this figure to sit a",
+ " little above any hand-adjusted one — that is the direction a ceiling",
+ " should err."
+' "$W/releases.json"
+
+echo
+# Trend, straight out of the committed series.
+if [ -s "$SERIES" ]; then
+ lines=$(wc -l < "$SERIES")
+ jq -rs --argjson n "$lines" '
+ sort_by(.date) as $s |
+ ($s | last) as $now |
+ " download series \($n) daily snapshot\(if $n == 1 then "" else "s" end) in metrics/release-downloads.jsonl",
+ " latest \($now.date): \($now.totals.all) assets (\($now.totals.binary) binaries)",
+ (if $n >= 2 then
+ ($s[-2]) as $prev |
+ " change since \($prev.date) \(if ($now.totals.binary - $prev.totals.binary) >= 0 then "+" else "" end)\($now.totals.binary - $prev.totals.binary) binaries"
+ else
+ " change not computable yet — one snapshot only. The series starts the day this lands."
+ end)
+ ' "$SERIES"
+else
+ echo " download series absent — run .github/scripts/snapshot-release-downloads.sh"
+fi
+
+echo
+jq -rs --argjson fp "$FIRST_PARTY" '
+ .[0] as $pulls | .[1] as $issues |
+ (($pulls + $issues) | map(.user)
+ | map(select(. != "" and (IN($fp[]) | not) and (endswith("[bot]") | not)))
+ | unique) as $ext |
+ ($pulls | map(.user) | map(select(. != "" and (IN($fp[]) | not) and (endswith("[bot]") | not))) | unique) as $extpr |
+ " external humans, PR or issue \($ext | length) distinct accounts, all-time",
+ " └ of which opened a PR \($extpr | length)",
+ " first-party PRs \($pulls | map(select(.user | IN($fp[]))) | length) of \($pulls | length)",
+ "",
+ " This is the community. At this size it is a list of people, not a metric."
+' "$W/pulls.json" "$W/issues.json"
+
+echo
+rule
+# ═══════════════════════ 2. NUMBERS YOU MUST NOT QUOTE ═══════════════════════
+b "2. CONTAMINATED — do not put these in a README, a deck, or a post"
+echo
+
+jq -r '
+ " stars (raw) \(.stargazers_count)",
+ " forks (raw) \(.forks_count)",
+ " watchers \(.subscribers_count)"
+' "$W/repo.json"
+
+if [ "$DO_STARS" = 1 ]; then
+ # starred_at needs the star+json media type. ~1 call per 100 stars.
+ gh api --paginate -H "Accept: application/vnd.github.star+json" \
+ "repos/${REPO}/stargazers?per_page=100" \
+ | jq -s 'flatten(1) | map(.starred_at // .created_at // "")' > "$W/stars.json" 2>/dev/null || echo '[]' > "$W/stars.json"
+
+ jq -r '
+ map(select(. != "") | .[0:10]) | sort as $days |
+ ($days | length) as $total |
+ (reduce $days[] as $d ({}; .[$d] += 1)) as $hist |
+ ($hist | to_entries | max_by(.value)) as $peak |
+ if $total == 0 then " star timestamps unavailable"
+ else
+ " ── star arrival ───────────────────────────────────────────────────",
+ " busiest single day \($peak.key): \($peak.value) stars (\(($peak.value * 100 / $total) | floor)% of all stars)",
+ (if ($peak.value * 4) > $total then
+ ($days | map(select(. < $peak.key)) | length) as $before |
+ " stars BEFORE that day \($before) ← the defensible number",
+ " stars on/after that day \($total - $before) ← a single-day arrival of \(($peak.value * 100 / $total)|floor)% of all",
+ " stars is not organic. Composition analysis of that",
+ " cohort (account age, followers, username shape) is in",
+ " docs/gtm/ADOPTION.md. It is not an abuse determination,",
+ " but it is not adoption either."
+ else
+ " no single-day spike dominates — the raw star count may be usable here."
+ end)
+ end
+ ' "$W/stars.json"
+fi
+
+echo
+echo " ── why each of the above is contaminated ──────────────────────────"
+echo " stars a synthetic-looking cohort arrived in one day; see the split above."
+echo " forks a fork is free and costs nothing to abandon. The only fork number"
+echo " worth anything is 'forks with a commit after forking', which for"
+echo " this repo was 4 of 351 at the last audit (98.9% never touched)."
+echo " clones 14-DAY ROLLING window, not a lifetime total, and it counts our own"
+echo " CI and indexing runs. ~11 clone events per unique cloner is machine"
+echo " traffic, not 11 developers. Never sum consecutive snapshots: they"
+echo " overlap by 13 days."
+echo " views same window, sampled the same way, and self-referral inflates it."
+echo
+
+echo " ── /get and /get.ps1 requests ─────────────────────────────────────"
+echo " Instrumented since 2026-08-08 by functions/get.js (a Pages Function that"
+echo " counts the request and serves the script). It is NOT readable from here:"
+echo " the counts live in R2 and come out of the token-guarded export —"
+echo " curl -s 'https://xerj.org/get?token=\$INSTALLS_TOKEN&days=30' | jq ."
+echo " Read it with its own caveat: a request to /get is a request. It does not"
+echo " prove a download, a checksum match, or that the binary was ever run."
+echo
+
+rule
+# ══════════════════════════ 3. NUMBERS THAT DO NOT EXIST ═════════════════════
+b "3. BLIND — no number exists, and none should be invented"
+echo
+cat <<'BLIND'
+ Whether an installed binary was ever executed, even once.
+ Deliberate. There is no telemetry in the xerj binary and none is planned:
+ it is an Apache-2.0 tool that engineers run on their own hardware, and a
+ silent phone-home would cost more credibility than the data is worth.
+ This gap is a choice, not an oversight — do not close it silently.
+
+ Site visits.
+ The Cloudflare RUM beacon stopped recording on 2026-07-22. Until it is
+ re-injected, the analytics dashboard reads zero and that zero is false.
+
+ Install failures.
+ A run that dies on an unsupported platform, a missing curl, or (since
+ 2026-08-08) a missing SHA-256 tool leaves no trace. Every install number
+ here counts successes; the denominator is unknown.
+
+ Attribution.
+ Nothing links a visit, a clone, a download and an install. Any funnel
+ conversion rate computed across those rows is fiction.
+BLIND
+echo
+rule
+echo " Source of the contamination analysis: docs/gtm/ADOPTION.md (internal)."
+echo " Instrumentation: functions/get.js, .github/workflows/release-metrics.yml"
+echo
diff --git a/wrangler.toml b/wrangler.toml
index 591ad5629..f3eec7027 100644
--- a/wrangler.toml
+++ b/wrangler.toml
@@ -1,5 +1,17 @@
# Cloudflare Pages project config for the xerj marketing site + Functions.
-# Binds the R2 bucket that /functions/lead.js writes captured emails to.
+#
+# Bindings:
+# LEADS — functions/lead.js writes captured emails here.
+# INSTALLS — functions/get.js writes one record per /get, /get.ps1 request.
+# No IP, no cookie, no identifier: see the privacy header in
+# functions/get.js. The bucket must be created once in the
+# Cloudflare dashboard (R2 → Create bucket → `xerj-installs`);
+# until it exists the function serves the installer normally and
+# simply does not count. Fail-open is deliberate.
+#
+# Routing: landing/_routes.json pins Function invocation to /get, /get.ps1 and
+# /lead. A NEW FUNCTION ADDED UNDER functions/ WILL NOT BE ROUTED until its
+# path is added to that include list.
name = "xerj"
pages_build_output_dir = "landing"
compatibility_date = "2024-09-01"
@@ -7,3 +19,7 @@ compatibility_date = "2024-09-01"
[[r2_buckets]]
binding = "LEADS"
bucket_name = "xerj-leads"
+
+[[r2_buckets]]
+binding = "INSTALLS"
+bucket_name = "xerj-installs"