cursedops 0.2.7 → 0.3.0

package/README.md

@@ -13,6 +13,7 @@ bun add cursedops
 | `cursedops/smoke` | the scaffolding of a deployed smoke — the ledger, the fetch, the DNS hint, the exit code — and the one check no app owns: every address of a deployment serving the same built client |
 | `cursedops/serve` | the static tier's four helpers — the path-traversal guard, the MIME table, the hashed-asset test, the crash handlers |
 | `cursedops/api-floor` | the rule that an unmatched `/api/...` is a phrase and never the app shell — the namespace predicates, the trailing-slash normaliser and the default 404 body. No `node:` import, so it mounts inside a Worker |
+| `cursedops/build-info` | which commit a checkout-served process is running and whether its tree was dirty — read once at load, and a `null` retried in the background rather than cached for the life of the process. `node:child_process`, so never in a Worker |
 | `cursedops/public-surface` | the ratchet on a LIBRARY's public surface — a symbol count per export subpath against a committed baseline that may only fall — and its `public-surface` bin. Not an app's: the one entry here admitted for three published libraries, see below |
 
 Bun, zero runtime dependencies, ships TypeScript source. Nothing here knows an app's

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "cursedops",
-	"version": "0.2.7",
-	"description": "The build-and-ops answers this generation's apps wrote independently and identically: finding a generation's roots without knowing a path, macOS launchd agent install/replace/remove, the scaffolding of a deployed smoke, and the static-serving helpers eight apps copied — the path-traversal guard among them — and the API floor that keeps an unmatched /api/... from ever being answered with the app shell — and the public-surface ratchet three published libraries each carried a forked copy of. Mechanism only — no app knows its name from here. Bun, zero runtime dependencies (typescript is an optional peer, for public-surface only), ships source.",
+	"version": "0.3.0",
+	"description": "The build-and-ops answers this generation's apps wrote independently and identically: finding a generation's roots without knowing a path, macOS launchd agent install/replace/remove, the scaffolding of a deployed smoke, and the static-serving helpers eight apps copied — the path-traversal guard among them — and the API floor that keeps an unmatched /api/... from ever being answered with the app shell — the commit and dirty flag a checkout-served process reports, retried rather than cached when git loses a boot race — and the public-surface ratchet three published libraries each carried a forked copy of. Mechanism only — no app knows its name from here. Bun, zero runtime dependencies (typescript is an optional peer, for public-surface only), ships source.",
 	"type": "module",
 	"scripts": {
 		"typecheck": "tsc -p tsconfig.json --noEmit",
@@ -42,6 +42,12 @@
 			"source": "./src/smoke.ts",
 			"import": "./src/smoke.ts"
 		},
+		"./build-info": {
+			"types": "./src/buildInfo.ts",
+			"bun": "./src/buildInfo.ts",
+			"source": "./src/buildInfo.ts",
+			"import": "./src/buildInfo.ts"
+		},
 		"./public-surface": {
 			"types": "./src/publicSurface.ts",
 			"bun": "./src/publicSurface.ts",

package/src/buildInfo.ts

@@ -0,0 +1,174 @@
+/**
+ * Which commit a checkout-served process is running, and whether its tree was dirty.
+ *
+ * ## Why this is a library and not six copies
+ *
+ * `family`, `flix`, `music`, `roms`, `station` and `vault` each carried a
+ * `src/server/buildInfo.ts`, measured 2026-09-22: six files, three distinct
+ * `md5`s, and the CODE character-identical in all six — only the prose differed.
+ * `/healthz` publishes the answer, `apiNotFoundBody` (`./apiFloor.ts`) puts it in
+ * every unmatched `/api/...` 404, and each app's `smoke:deployed` compares it
+ * against HEAD. A deploy on this Mac is a launchd swap over a working tree — there
+ * is no artifact, only source — so "did the new code take?" has no other
+ * observable answer.
+ *
+ * ## 🔴 The defect this fixes: a failure cached as if it were an answer
+ *
+ * All six read `git rev-parse HEAD` and `git status --porcelain` ONCE, at module
+ * load, and cached the result for the life of the process — `null` included. On
+ * 2026-09-22 all nine host processes started in the same second at login, against
+ * a cold page cache, each with a 5 s `spawnSync` timeout, and SEVEN of nine then
+ * answered `/healthz` with `"commit": null` until someone restarted them. `family`
+ * won the commit read and lost the dirty one; `music` lost the commit and won
+ * dirty — opposite halves, which is what a race looks like and what a missing
+ * binary or a bad `PATH` cannot do. One `launchctl kickstart` of `flix`, with no
+ * code change, turned `null` into its sha. The cost: `smoke:deployed` red on
+ * healthy apps after every reboot (a check that cries wolf gets skipped), and the
+ * API floor's 404 naming "an unreadable commit" on six apps.
+ *
+ * So: the eager read stays — it is right about WHEN to read — and a `null` is no
+ * longer final. Whatever half did not answer is retried in the BACKGROUND, with a
+ * capped backoff, until it does. A success is read once and never spawns again.
+ *
+ * 🔴 **The request path never spawns.** The accessors are plain reads of what is
+ * known. The obvious fix — "retry on the next access while null" — puts a
+ * synchronous 5 s `spawnSync` inside `/healthz` exactly when git is broken, and
+ * `/healthz` is the probe a deploy polls once a second. Retries use the async
+ * runner and an `unref`'d timer, so they cannot block a request and cannot hold a
+ * process open.
+ *
+ * 🔴 **Never throws and never blocks boot beyond the one eager read.** A checkout
+ * without git, a `git` not on the launchd job's `PATH`, a broken repo — all answer
+ * `null` until they stop being true. An app that will not start is far worse than
+ * one that cannot yet name its commit, and a smoke should still treat a `null`
+ * that PERSISTS as a failure.
+ *
+ * Entry rule (`../README.md`): rule 1, six apps; rule 2, it is handed the checkout
+ * directory and knows nothing else; rule 3, the 2026-09-22 reboot above.
+ * `buildInfo.test.ts` drives the failure path — a first read that loses and a
+ * retry that wins — because the six copies' own suites could only ever see HEAD.
+ */
+
+import { execFile, spawnSync } from "node:child_process";
+
+/** Runs `git <args>` in `cwd`; the stdout on exit 0, otherwise `null`. Never throws. */
+export type GitRun = (args: readonly string[], cwd: string) => string | null;
+/** {@link GitRun}, without blocking. Never rejects. */
+export type GitRunAsync = (args: readonly string[], cwd: string) => Promise<string | null>;
+
+/** Per git call — the six copies' figure, kept. */
+export const GIT_TIMEOUT_MS = 5_000;
+
+/**
+ * Delays between background retries of a half that has not answered. The last is
+ * repeated for as long as it keeps failing: once a minute costs nothing, and a
+ * process that ran for a week after a bad boot should still recover by itself.
+ */
+export const RETRY_DELAYS_MS: readonly number[] = [1_000, 2_000, 5_000, 10_000, 30_000, 60_000];
+
+const HEAD_ARGS = ["rev-parse", "HEAD"] as const;
+const STATUS_ARGS = ["status", "--porcelain"] as const;
+
+export const runGitSync: GitRun = (args, cwd) => {
+	try {
+		const result = spawnSync("git", [...args], { cwd, encoding: "utf8", timeout: GIT_TIMEOUT_MS });
+		return result.status === 0 ? (result.stdout ?? "") : null;
+	} catch {
+		return null;
+	}
+};
+
+export const runGitAsync: GitRunAsync = (args, cwd) =>
+	new Promise((resolve) => {
+		try {
+			execFile("git", [...args], { cwd, encoding: "utf8", timeout: GIT_TIMEOUT_MS }, (error, stdout) =>
+				resolve(error ? null : stdout),
+			);
+		} catch {
+			resolve(null);
+		}
+	});
+
+/** A full 40-hex sha, or `null` for anything else — a placeholder is not a commit. */
+export function parseCommit(stdout: string | null): string | null {
+	const sha = (stdout ?? "").trim();
+	return /^[0-9a-f]{40}$/.test(sha) ? sha : null;
+}
+
+/** Any porcelain output means dirty; no output at all (`null`) means unknown. */
+export function parseDirty(stdout: string | null): boolean | null {
+	return stdout === null ? null : stdout.trim().length > 0;
+}
+
+export interface BuildInfo {
+	/** The full sha, or `null` while git has not answered. */
+	commit(): string | null;
+	/** The 8-character form `/healthz` publishes. */
+	commitShort(): string | null;
+	/** Was the tree dirty when it was read? `null` while git has not answered. */
+	dirty(): boolean | null;
+	/**
+	 * One async attempt at whatever is still unknown. The background retry calls
+	 * this; it is exported for tests and for a caller that wants to force one.
+	 */
+	refresh(): Promise<void>;
+}
+
+export interface BuildInfoOptions {
+	runSync?: GitRun;
+	runAsync?: GitRunAsync;
+	retryDelaysMs?: readonly number[];
+	/** `setTimeout`, `unref`'d, by default. Injected so a test can step it. */
+	schedule?: (fn: () => void, ms: number) => void;
+}
+
+const unrefTimeout = (fn: () => void, ms: number): void => {
+	const timer = setTimeout(fn, ms) as { unref?: () => void };
+	timer.unref?.();
+};
+
+/**
+ * Read `repoDir`'s commit and dirty flag now, and keep retrying in the background
+ * whichever half did not answer. Call once, at module load, with the checkout the
+ * process serves — `findPackageRoot` from `cursedops/roots` finds it.
+ */
+export function buildInfo(repoDir: string, options: BuildInfoOptions = {}): BuildInfo {
+	const runSync = options.runSync ?? runGitSync;
+	const runAsync = options.runAsync ?? runGitAsync;
+	const delays = options.retryDelaysMs?.length ? options.retryDelaysMs : RETRY_DELAYS_MS;
+	const schedule = options.schedule ?? unrefTimeout;
+
+	let commit = parseCommit(runSync(HEAD_ARGS, repoDir));
+	let dirty = parseDirty(runSync(STATUS_ARGS, repoDir));
+	let attempt = 0;
+
+	const unanswered = (): boolean => commit === null || dirty === null;
+
+	async function refresh(): Promise<void> {
+		const [nextCommit, nextDirty] = await Promise.all([
+			commit === null ? runAsync(HEAD_ARGS, repoDir).then(parseCommit) : commit,
+			dirty === null ? runAsync(STATUS_ARGS, repoDir).then(parseDirty) : dirty,
+		]);
+		// A half that has answered is final — never overwritten, never re-read.
+		commit ??= nextCommit;
+		dirty ??= nextDirty;
+	}
+
+	function arm(): void {
+		if (!unanswered()) return;
+		const delay = delays[Math.min(attempt, delays.length - 1)] as number;
+		attempt++;
+		schedule(() => {
+			refresh().then(arm, arm);
+		}, delay);
+	}
+
+	arm();
+
+	return {
+		commit: () => commit,
+		commitShort: () => (commit ? commit.slice(0, 8) : null),
+		dirty: () => dirty,
+		refresh,
+	};
+}