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.
Rust agent-memoryai-agentsbm25claude-codeclicode-searchcursordatabaseelasticsearchfull-text-searchhybrid-searchjsonllocal-firstmcpmcp-servermodel-context-protocolragrustsearch-enginevector-search
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.mjsnew file mode 100644index 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.shnew file mode 100755index 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.ymlindex 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 Rustuses: dtolnay/rust-toolchain@stablediff --git a/.github/workflows/release-metrics.yml b/.github/workflows/release-metrics.ymlnew file mode 100644index 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.mdindex 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### Securitydiff --git a/functions/get.js b/functions/get.jsnew file mode 100644index 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.jsnew file mode 100644index 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/_headersindex 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./getContent-Type: text/plain; charset=utf-8Cache-Control: public, max-age=300diff --git a/landing/_routes.json b/landing/_routes.jsonnew file mode 100644index 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.htmlindex 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">> 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/getindex 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" inaarch64|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}"+fitarget="${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.mdnew file mode 100644index 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.jsonlnew file mode 100644index 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.shnew file mode 100755index 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"+echodiff --git a/wrangler.toml b/wrangler.tomlindex 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"