cursedops 0.10.7 → 0.10.9

package/README.md

@@ -28,6 +28,7 @@ bun add cursedops
 | `cursedops/relay` | the WORKER half of a relay — a Worker in front of a Mac-bound app over ONE outbound WebSocket: the frames (station's wire, byte for byte), the key-digest door (`acceptLink`), and `RelayLink`, the Durable Object an app subclasses with its name, body ceiling, timeout and (optionally) station's per-cookie offline cache. No `node:` import (0.10.0, lifted from station for roms, task 065) |
 | `cursedops/relay-link` | the MAC half — `dialLink` (answer each frame with the app's own `fetch`, redial 1 s → 60 s on close, no timer otherwise), `readLinkSettings` for `<APP>_LINK_URL`/`<APP>_LINK_KEY`, and `rotateLinkKey` (digest to the Worker FIRST, the key to the 0600 file only if it took) (0.10.0) |
 | `cursedops/relay-stage` | the signed-in STAGE WALK's skeleton both relay apps shared — `stageByteCheck` (SHA-256 of every built file, a stale byte re-asked 4 × 10 s), `putStageLinkDigest` (`--env stage` only), `grantStageOwner` (auth-stage's 2FA grant, never production's), `oldKeyRefused` (the rotation leg: 20 s refused window, 3 min ceiling), `awaitSystemResolver`, `servedPath`, `STAGE_AUTH_URL`. With `relayWorkerDeployCli` in `cursedops/worker-deploy`, a relay app's whole `worker:deploy` as data (0.10.6) |
+| `cursedops/public-client` | does a relay app's PUBLIC hostname serve the client this release built? `comparePublicClient` (built assets the shells name, never bodies), `stagedShell`, `publicShell` (cache-busted, Access headers as an option), `recordPublicClient` — the smoke's `public-client` row, an EDGE fault (exit 2, never a rollback) — and `shipClientIfBehind`, the deploy step that runs `worker:deploy` when the public shell is behind. Lifted from roms for station (0.10.8) |
 | `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,6 +1,6 @@
 {
 	"name": "cursedops",
-	"version": "0.10.7",
+	"version": "0.10.9",
 	"description": "The build-and-ops answers this generation's apps wrote independently and identically: finding a generation's roots — and printing a command that runs when pasted — without knowing a path, the generation's whole-tree laws run over one repo from a checkout or a worktree, macOS launchd agent install/replace/remove and the live port a job serves, the scaffolding and verdicts of a deployed smoke (origin probe, the smoke's own environment, a network that lies about DNS, a settled version), the static-serving helpers eight apps copied — the path-traversal guard among them — 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, the Cloudflare Worker deploy toolkit four apps copied (the deploy sequence, exact-set secrets over a pipe, origin-first rollback, the curl edge fetch, the row-for-row D1 import proof, the billed-CPU tail check around a deploy's walk and smoke, and each app's worker:secrets and worker:smoke main as one function of its data), the relay a Worker fronts a Mac-bound app with (the Durable Object, the frames, the Mac's dialer and key rotation — lifted from station for roms — and the signed-in stage walk's skeleton and the relay app's whole worker:deploy), the Worker import-graph and await-port checks every Worker app's suite runs over its own source, 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": {
@@ -139,6 +139,12 @@
 			"bun": "./src/relayStage.ts",
 			"source": "./src/relayStage.ts",
 			"import": "./src/relayStage.ts"
+		},
+		"./public-client": {
+			"types": "./src/publicClient.ts",
+			"bun": "./src/publicClient.ts",
+			"source": "./src/publicClient.ts",
+			"import": "./src/publicClient.ts"
 		}
 	},
 	"bin": {

package/src/edgeFetch.ts

@@ -242,3 +242,35 @@ export function fleetEdgeFetch(
 	if (!state) throw new Error(`no generation state root above ${from}: set $FORGE_STATE or run inside a checkout with forge.env`);
 	return createStageEdgeFetch(join(state, "secrets", "cloudflare-access.env"), options);
 }
+
+/** The status {@link settledFetch} answers when the fetch THREW — outside HTTP's range on purpose, so no leg can mistake it for an answer. */
+export const NO_ANSWER_STATUS = 599;
+
+/**
+ * A fetch that never throws: a rejection (curl's timeout, DNS, a reset) becomes a
+ * {@link NO_ANSWER_STATUS} `Response` whose body and `x-edge-error` header carry the reason, and
+ * `onThrow` hears it first so the smoke's ledger can name it.
+ *
+ * 🔴 Why (2026-09-25): roms' `worker:smoke` asked a relayed path while the Mac's link redialled,
+ * `edgeFetch` threw on curl exit 28, and the process died with a stack trace and no ledger — so a
+ * healthy release exited 1. Every leg of a smoke is supposed to be RECORDED: a throw is a failed
+ * leg naming its path, never the end of the run.
+ */
+export function settledFetch(
+	fetcher: (url: string, init?: RequestInit) => Promise<Response>,
+	onThrow: (url: string, error: Error) => void = () => {},
+): (url: string, init?: RequestInit) => Promise<Response> {
+	return async (url, init) => {
+		try {
+			return await fetcher(url, init);
+		} catch (thrown) {
+			const error = thrown instanceof Error ? thrown : new Error(String(thrown));
+			onThrow(url, error);
+			const reason = error.message.replace(/[^\x20-\x7e]+/g, " ").slice(0, 300);
+			return new Response(`no answer: ${reason}`, {
+				status: NO_ANSWER_STATUS,
+				headers: { "content-type": "text/plain", "x-edge-error": reason },
+			});
+		}
+	};
+}

package/src/publicClient.ts

@@ -0,0 +1,175 @@
+/**
+ * `cursedops/public-client` — does the PUBLIC hostname of a relay app hand people the client this
+ * release built? Lifted from roms for station (0.10.8); both are relay apps.
+ *
+ * ## Why this is its own question (2026-09-24, measured on roms)
+ *
+ * A relay app's shell — `/`, `/assets/*` — is the relay WORKER's static assets, uploaded only by
+ * `worker:deploy`. The Mac end still stages a client and reports it on `/healthz`, so a smoke's
+ * `client-commit` row went green for roms `7e13f8b5` (the 30 Hz fix) while the public `/` kept
+ * naming `/assets/index-BgukLK5o.js` — the build before it — even cache-busted. Nothing that asks
+ * the ORIGIN can see that; only the public shell can. station had the same gap, hidden only
+ * because `worker:deploy` was run by hand first.
+ *
+ * The comparison is by the built assets the shell NAMES (`cursedops/smoke` `builtAssetsIn`), never
+ * by body: the zone injects a beacon at the edge that loopback never carries.
+ *
+ * ```ts
+ * import { recordPublicClient, shipClientIfBehind, stagedShell } from "cursedops/public-client";
+ * // deploy.ts, between the origin probe and the public smoke:
+ * const shipped = await shipClientIfBehind({ base, staged: stagedShell(dataDir), root, headers });
+ * // smoke-deployed.ts — a mismatch is an EDGE fault (exit 2), never a rollback:
+ * await guarded(smoke, PUBLIC_CLIENT_CHECK, () => recordPublicClient(smoke, staged, { root, headers }));
+ * ```
+ *
+ * `headers` is how an app behind Cloudflare Access (station) passes the fleet's service token; an
+ * anonymous `/` there is a 302 to the Access issuer, which names no built asset and never matches.
+ */
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { builtAssetsIn, type Smoke } from "cursedops/smoke";
+import { stagedClientDir } from "cursedops/staged-client";
+
+/** The smoke row's name — one spelling for every relay app. */
+export const PUBLIC_CLIENT_CHECK = "public-client";
+
+export interface PublicClientVerdict {
+	matched: boolean;
+	/** The built files the public shell names. */
+	served: string[];
+	/** The built files this release's staged shell names. */
+	built: string[];
+}
+
+/** Pure: the two shells' built assets, compared. An empty list on either side never matches. */
+export function comparePublicClient(publicHtml: string, stagedHtml: string, base: string): PublicClientVerdict {
+	const served = builtAssetsIn(publicHtml, base);
+	const built = builtAssetsIn(stagedHtml, base);
+	return { matched: built.length > 0 && served.join(",") === built.join(","), served, built };
+}
+
+/** The staged client's `index.html` under an app's data dir — the shell this release built — or `null` when nothing is staged. */
+export function stagedShell(dataDir: string): string | null {
+	const dir = stagedClientDir(dataDir);
+	if (!dir) return null;
+	try {
+		return readFileSync(join(dir, "index.html"), "utf8");
+	} catch {
+		return null;
+	}
+}
+
+export interface PublicShellOptions {
+	/** Sent with the request — Cloudflare Access service-token headers for an app behind Access. */
+	headers?: Record<string, string>;
+	timeoutMs?: number;
+	/** Injected for tests. */
+	fetch?: (url: string, init: RequestInit) => Promise<Response>;
+}
+
+/** Fetch the public `/`, cache-busted — the question is what the hostname HAS, not what a repeat visitor gets. */
+export async function publicShell(base: string, options: PublicShellOptions = {}): Promise<{ status: number; html: string }> {
+	const url = new URL("/", base);
+	url.searchParams.set("cb", Math.random().toString(36).slice(2));
+	const ask = options.fetch ?? ((u: string, init: RequestInit) => fetch(u, init));
+	const response = await ask(url.toString(), {
+		redirect: "manual",
+		signal: AbortSignal.timeout(options.timeoutMs ?? 20_000),
+		headers: { accept: "text/html", ...(options.headers ?? {}) },
+	});
+	return { status: response.status, html: await response.text().catch(() => "") };
+}
+
+/** The sentence both the smoke and the deploy print when the halves disagree. `root` is the app's checkout. */
+export function workerBehind(verdict: PublicClientVerdict, base: string, root: string): string {
+	return (
+		`🔴 ${base} serves a client naming ${verdict.served.join(", ") || "(no built assets)"}, but this release built ` +
+		`${verdict.built.join(", ") || "(nothing staged)"}. The public shell is the relay Worker's static assets, which only ` +
+		`\`worker:deploy\` uploads — people are still on the previous client. \`cd ${root} && bun run worker:deploy\``
+	);
+}
+
+export interface RecordPublicClientOptions extends PublicShellOptions {
+	/** The app's checkout, for the pasteable `worker:deploy` command. */
+	root: string;
+}
+
+/**
+ * The smoke's `public-client` row. A mismatch — or nothing staged to compare with — is recorded as
+ * a failure AND marked an edge fault, so the run settles to exit 2: the Mac end this deploy put up
+ * is correct, and reverting it cannot upload a Worker. Returns whether it matched.
+ */
+export async function recordPublicClient(smoke: Smoke, staged: string | null, options: RecordPublicClientOptions): Promise<boolean> {
+	if (staged === null) {
+		smoke.record(
+			PUBLIC_CLIENT_CHECK,
+			false,
+			"🔴 no staged client to compare with — `bun run deploy` stages one; nothing says which client people should have",
+		);
+		smoke.markEdgeFault();
+		return false;
+	}
+	const { html } = await publicShell(smoke.base, options);
+	const verdict = comparePublicClient(html, staged, smoke.base);
+	smoke.record(
+		PUBLIC_CLIENT_CHECK,
+		verdict.matched,
+		verdict.matched
+			? `the public shell names this release's build — ${verdict.built.join(", ")}`
+			: workerBehind(verdict, smoke.base, options.root),
+	);
+	if (!verdict.matched) smoke.markEdgeFault();
+	return verdict.matched;
+}
+
+export interface ShipClientOptions extends PublicShellOptions {
+	/** The public origin, e.g. `https://roms.cursedalchemy.com`. */
+	base: string;
+	/** The staged shell ({@link stagedShell}); `null` means nothing staged — the Worker is shipped anyway. */
+	staged: string | null;
+	/** The app's checkout — where `bun run worker:deploy` runs. */
+	root: string;
+	/** Runs `bun run worker:deploy` in `root`; returns its exit status. Injected for tests. */
+	runWorkerDeploy?: (root: string) => number | null;
+	log?: (line: string) => void;
+}
+
+export interface ShipClientResult {
+	/** `already` — the public shell named this build; `shipped` — worker:deploy ran and exited 0; `failed` — it did not. */
+	outcome: "already" | "shipped" | "failed";
+	/** worker:deploy's exit status when it ran. */
+	status?: number | null;
+	before: PublicClientVerdict | null;
+}
+
+const spawnWorkerDeploy = (root: string): number | null =>
+	spawnSync("bun", ["run", "worker:deploy"], { cwd: root, stdio: ["ignore", "inherit", "inherit"] }).status;
+
+/**
+ * The deploy step: when the public shell does not name this build, run `worker:deploy` (its own
+ * stage walk first) so ONE command ships the release. Never throws for a fetch that fails — an
+ * unreadable public shell is "behind", because shipping the Worker is idempotent and the smoke's
+ * `public-client` row is what proves it took.
+ */
+export async function shipClientIfBehind(options: ShipClientOptions): Promise<ShipClientResult> {
+	const log = options.log ?? console.log;
+	let before: PublicClientVerdict | null = null;
+	if (options.staged !== null) {
+		const html = await publicShell(options.base, options).then(
+			(shell) => shell.html,
+			() => "",
+		);
+		before = comparePublicClient(html, options.staged, options.base);
+		if (before.matched) {
+			log(`  already serving it — ${before.built.join(", ")}`);
+			return { outcome: "already", before };
+		}
+		log(`  ${workerBehind(before, options.base, options.root)}`);
+	} else {
+		log("  nothing staged to compare with — shipping the Worker's client anyway");
+	}
+	log("  running `bun run worker:deploy` — the stage walk, then production");
+	const status = (options.runWorkerDeploy ?? spawnWorkerDeploy)(options.root);
+	return { outcome: status === 0 ? "shipped" : "failed", status, before };
+}

package/src/relay.ts

@@ -316,6 +316,20 @@ const json = (status: number, body: unknown) =>
  * the edge has noticed its old socket died, and a relay that sent to the dead one would time every
  * request out for as long as that took.
  *
+ * 🔴 **Never a hang across a redial (2026-09-25).** roms' post-deploy smoke died on curl's timeout
+ * asking a relayed path while the Mac's link reconnected twice in one minute. Two holes, both shut:
+ *
+ *  · a replaced socket is closed by US, so no `webSocketClose` ever fires for it — its pending
+ *    requests waited out {@link DEFAULT_RELAY_TIMEOUT_MS}. `accept` now answers each the link-down
+ *    503 before closing it;
+ *  · workerd keeps listing a closed socket until its close handshake completes, which a dead Mac
+ *    never finishes — and it was `getWebSockets()[0]`, ahead of the new one. {@link RelayLink.live}
+ *    picks the NEWEST link not marked replaced.
+ *
+ * A request caught by either answers the same JSON 503 (`link: "down"`) as a Mac away, which is
+ * what every smoke already accepts. `relay.test.ts` holds both paths against a state that lists
+ * closed sockets the way workerd does.
+ *
  * 🔴 A plain class with a `fetch` method, NOT `extends DurableObject`: importing
  * `cloudflare:workers` leaks Worker globals over a Bun host's type graph. The hibernation handlers
  * are found by name.
@@ -344,14 +358,43 @@ export class RelayLink {
 		return this.relay(request);
 	}
 
+	/**
+	 * The link requests go to: the newest by `since` that `accept` has not marked replaced. Never
+	 * `getWebSockets()[0]` — see the class header.
+	 */
+	protected live(): LinkSocket | undefined {
+		let best: LinkSocket | undefined;
+		let bestSince = "";
+		for (const socket of this.state.getWebSockets()) {
+			const attachment = socket.deserializeAttachment() as { since?: string; replaced?: boolean } | null | undefined;
+			if (attachment?.replaced) continue;
+			const since = attachment?.since ?? "";
+			if (best === undefined || since >= bestSince) {
+				best = socket;
+				bestSince = since;
+			}
+		}
+		return best;
+	}
+
 	status(): LinkStatus {
-		const socket = this.state.getWebSockets()[0];
+		const socket = this.live();
 		const attachment = socket?.deserializeAttachment() as { since?: string } | null | undefined;
 		return { connected: socket !== undefined, since: attachment?.since ?? null };
 	}
 
 	private accept(): Response {
-		for (const old of this.state.getWebSockets()) old.close(4000, "replaced by a newer link");
+		for (const old of this.state.getWebSockets()) {
+			// Closed by us, so no `webSocketClose` fires for it: fail what it holds NOW, or each waits
+			// out the timeout. Marked first, because workerd goes on listing it until the handshake ends.
+			try {
+				old.serializeAttachment({ ...((old.deserializeAttachment() as object | null) ?? {}), replaced: true });
+			} catch {}
+			this.failPending(old, "replaced by a newer link");
+			try {
+				old.close(4000, "replaced by a newer link");
+			} catch {}
+		}
 		const { client, server } = this.makePair();
 		this.state.acceptWebSocket(server);
 		server.serializeAttachment({ since: new Date().toISOString() });
@@ -362,17 +405,27 @@ export class RelayLink {
 		return json(503, { error: this.options.offlineMessage, link: "down" });
 	}
 
+	/** Answer every request waiting on `socket` with the link-down 503 — it will never be answered. */
+	private failPending(socket: LinkSocket, why: string): void {
+		for (const [id, waiting] of this.pending) {
+			if (waiting.socket !== socket) continue;
+			clearTimeout(waiting.timer);
+			this.pending.delete(id);
+			waiting.resolve(json(503, { error: `${this.options.app}'s link went down mid-request (${why}) — ask again`, link: "down" }));
+		}
+	}
+
 	/** Relay, and keep or drop what the answer says about the cookie that asked — see {@link OfflineCache}. */
 	private async relay(request: Request): Promise<Response> {
 		const cache = this.options.offline;
-		if (!cache) return this.state.getWebSockets()[0] ? this.send(request) : this.offline();
+		if (!cache) return this.live() ? this.send(request) : this.offline();
 		const url = new URL(request.url);
 		const cookie = cookieValue(request.headers.get("cookie"), cache.cookie);
 		const owner = cookie ? await sha256Hex(cookie) : null;
 		const keyed = `${url.pathname}${url.search}`;
 		const cacheable = owner !== null && request.method === "GET" && url.pathname.startsWith("/api/");
 		if (owner && cache.signOut.includes(url.pathname)) await this.forget(owner);
-		if (!this.state.getWebSockets()[0]) {
+		if (!this.live()) {
 			if (cacheable) {
 				const kept = await this.state.storage.get<Kept>(`c:${owner}:${keyed}`);
 				if (kept && this.now() - kept.at < cache.ttlMs) {
@@ -413,13 +466,13 @@ export class RelayLink {
 		const warm = await this.state.storage.get<{ cookie: string; at: number }>("warm");
 		if (!warm || this.now() - warm.at >= cache.ttlMs) return;
 		for (const path of paths) {
-			if (!this.state.getWebSockets()[0]) return;
+			if (!this.live()) return;
 			await this.relay(new Request(`https://relay.link${path}`, { headers: { cookie: `${cache.cookie}=${warm.cookie}` } }));
 		}
 	}
 
 	private async send(request: Request): Promise<Response> {
-		const socket = this.state.getWebSockets()[0];
+		const socket = this.live();
 		if (!socket) return this.offline();
 		const tooBig = () => json(413, { error: `request body over the link's ${this.maxBodyBytes} bytes` });
 		const declared = Number(request.headers.get("content-length") ?? 0);
@@ -460,12 +513,7 @@ export class RelayLink {
 	}
 
 	webSocketClose(socket: LinkSocket, code: number, reason: string): void {
-		for (const [id, waiting] of this.pending) {
-			if (waiting.socket !== socket) continue;
-			clearTimeout(waiting.timer);
-			this.pending.delete(id);
-			waiting.resolve(json(502, { error: `${this.options.app}'s link closed mid-request (${code}${reason ? ` ${reason}` : ""})` }));
-		}
+		this.failPending(socket, `closed ${code}${reason ? ` ${reason}` : ""}`);
 		try {
 			socket.close(code, reason);
 		} catch {}
@@ -492,3 +540,23 @@ export async function acceptLink(
 	if (!(await linkKeyMatches(request.headers.get("authorization"), digest))) return json(401, { error: `not ${names.app}'s Mac` });
 	return link.fetch(new Request(`${new URL(request.url).origin}/__link`, request));
 }
+
+/**
+ * The Worker's call into the link object, with a THROW turned into the link-down 503.
+ *
+ * A Worker upload resets every Durable Object, and a request in flight in the old one rejects
+ * ("Durable Object reset because its code was updated"). Unhandled, that is Cloudflare's HTML
+ * error page — not JSON, not a 503, and a smoke's leg reads it as a broken release. The same
+ * answer as a Mac away is the honest one: ask again in a second.
+ */
+export async function askLink(
+	link: { fetch(request: Request): Promise<Response> },
+	request: Request,
+	app: string,
+): Promise<Response> {
+	try {
+		return await link.fetch(request);
+	} catch (error) {
+		return json(503, { error: `${app}'s link object restarted mid-request (${(error as Error).message}) — ask again`, link: "down" });
+	}
+}