cursedops 0.2.0 → 0.2.1

package/README.md

@@ -10,8 +10,8 @@ bun add cursedops
 |---|---|
 | `cursedops/roots` | finding a generation's roots, and a checkout's package root, without knowing a path |
 | `cursedops/launchd` | installing, replacing and removing a macOS launchd user agent |
-| `cursedops/smoke` | the scaffolding of a deployed smoke — the ledger, the fetch, the DNS hint, the exit code |
-| `cursedops/serve` | the static tier's four helpers — the path-traversal guard, the MIME table, the hashed-asset test, the crash handlers |
+| `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 — and the API floor: the predicates, the trailing-slash normaliser and the default 404 body that keep an unmatched `/api/...` from ever being answered with the app shell |
 
 Bun, zero runtime dependencies, ships TypeScript source. Nothing here knows an app's
 name, a hostname, a port or a route.
@@ -42,6 +42,15 @@ So the entry rule here is arithmetic, not judgement:
 A fourth rule follows from the first three: **an addition that only one app will use
 does not go in.** That is a library that exists to be refactored later.
 
+🔴 **`sameDeployedShell` is the one entry that rule 1 did not let in, and it is recorded
+here rather than quietly excepted.** It was written once, by `patterns`, not twice —
+what admits it is rule 3 at a size rule 1 cannot measure: the fault it catches was
+invisible for six days on the app that had it, and the other five apps behind or moving
+behind an edge Worker still cannot tell a working deploy from a working cache. A check
+told ONE NAME is a check about that name; this one is about a property every deployment
+with two addresses has. It buys the exception by being pinned to a failure it has
+actually caught — `src/smoke.test.ts` runs it against the genuine 2026-09-12 shell.
+
 ### What was deliberately left in the apps
 
 The comparison that produced this library found three areas that are genuinely
@@ -111,7 +120,26 @@ await guarded(smoke, "gate", async () => {
 smoke.finish();   // exits 0, 1 or 2
 ```
 
-No checks, ever. The checks are the part `desk` and `flix` wrote differently on purpose,
+One check, and it is about the ADDRESSES of a deployment rather than about any app:
+
+```ts
+import { sameDeployedShell } from "cursedops/smoke";
+
+// every address of one deployment, not "edge vs origin" — an app may have no
+// origin left. A Worker's second address is its uncached *.workers.dev preview.
+await sameDeployedShell(smoke, [smoke.base, `http://127.0.0.1:${port}`]);
+```
+
+🔴 It refuses when the addresses name different built assets, and it records that as an
+**edge fault (exit 2), never a rollback** — the origin is serving what this checkout
+built, and reverting it cannot reach the Worker, cache rule or Assets binding in front.
+Measured 2026-09-18 on `patterns`: the edge served a shell built 2026-09-12 out of a
+Worker nobody knew about, and every automated surface stayed green for **six days**.
+Only same-origin `.js`/`.css` references are compared, because the zone injects a Web
+Analytics beacon in front of the edge and not on loopback — a check that reds on a
+healthy deploy is one somebody turns off.
+
+Nothing else. The checks are the part `desk` and `flix` wrote differently on purpose,
 and a shared kit that starts absorbing route lists and health-payload shapes is how the
 last one reached 277 files.
 

package/package.json

@@ -1,13 +1,13 @@
 {
 	"name": "cursedops",
-	"version": "0.2.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. Mechanism only — no app knows its name from here. Bun, zero dependencies, ships source.",
+	"version": "0.2.1",
+	"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 and the API floor among them. Mechanism only — no app knows its name from here. Bun, zero dependencies, ships source.",
 	"type": "module",
 	"scripts": {
 		"typecheck": "tsc -p tsconfig.json --noEmit",
 		"lint": "biome check .",
 		"test": "bun test src",
-		"paths": "bun ../../tools/check-paths.ts .",
+		"paths": "bun run scripts/paths.ts",
 		"verify": "bun run paths && bun run typecheck && bun run lint && bun run test",
 		"prepublishOnly": "bun run verify"
 	},

package/src/serve.ts

@@ -1,6 +1,6 @@
 /**
- * The four helpers every app's `src/server/serve.ts` wrote the same way — the
- * path-traversal guard among them.
+ * The helpers every app's `src/server/serve.ts` wrote the same way — the
+ * path-traversal guard among them, and the API floor.
  *
  * ## Why this is a library and not eight copies
  *
@@ -47,6 +47,38 @@
  *
  * `serve.test.ts` drives both halves, including the symlink escape, because a guard
  * that has only ever been seen passing is a guard nobody has proved can fail.
+ *
+ * ## 🔴 The API floor, added 2026-09-18 — and why it is here rather than in an app
+ *
+ * The second family in this file, and it arrives by the same arithmetic. `station` and
+ * `patterns` each wrote a floor — a rule that an unmatched `/api/...` is answered with a
+ * phrase and never with the single-page shell — independently, in different shapes, for
+ * the same incident. That is entry rule 1 twice over. Rule 2 holds because nothing below
+ * looks anything up: the app's name, its commit and the body it chooses to send all
+ * arrive as arguments, and there is no Hono type in this file, so the three lines of
+ * `app.all(...)` wiring stay in the app that owns the router. Rule 3 is the measurement:
+ *
+ *   > 2026-09-17. `station`'s Openclaw page had never loaded on any commit. The client
+ *   > asked for `/api/openclaw/`; Hono mounts that sub-app's `get("/")` at
+ *   > `/api/openclaw` — `mergePath("/api/openclaw", "/")` drops the trailing slash — and
+ *   > then matches strictly, so the request matched nothing, fell into `app.get("*")`,
+ *   > and came back as 1.7 KB of `index.html` with a **200**. The client's honest reading
+ *   > of an HTML body was *"that is what an API older than this page looks like — deploy
+ *   > this commit and reload"*, which sent the owner at a deploy that could not have
+ *   > helped.
+ *
+ * Both halves of that are here, because a floor without the normaliser fixes the symptom
+ * the owner did not have: {@link canonicalApiPath} makes the trailing slash a non-event,
+ * and {@link isApiPath} + {@link apiNotFoundBody} make every remaining miss a JSON 404
+ * that names the route, the app and the commit answering. A wrong path says "wrong path";
+ * a stale process says which commit it is.
+ *
+ * 🔴 **{@link apiNotFoundBody} is the DEFAULT body, not the only one.** `patterns` sends
+ * `{status, code, error}` through its own `reply.refuse` and deliberately says less —
+ * its floor faces the public internet, where the app's name and commit are one bit more
+ * than a scanner should get. An app that knows something this library cannot keeps its
+ * own body and takes the two predicates; that is the `cwip/asset-budget` shape, and it is
+ * what stops this growing into the kit it replaced.
  */
 
 import { existsSync, realpathSync, statSync } from "node:fs";
@@ -141,6 +173,86 @@ export function fileWithin(root: string, urlPath: string): string | null {
  * the whole of rule 2: the only app-shaped thing these four helpers touch arrives
  * as an argument.
  */
+/** The API namespace. See the module header: nothing under it may answer with the shell. */
+export const API_PREFIX = "/api";
+
+/**
+ * Is this path inside the API namespace? `/api` itself counts; `/apiary` does not.
+ *
+ * 🔴 The namespace ITSELF is the case every hand-rolled floor missed. A Hono
+ * `app.all("/api/*")` does not match a bare `/api` — the pattern requires the slash — so
+ * the one path most likely to be typed by hand fell through to the shell in the two apps
+ * that already believed they had a floor.
+ */
+export const isApiPath = (urlPath: string): boolean =>
+	urlPath === API_PREFIX || urlPath.startsWith(`${API_PREFIX}/`);
+
+/**
+ * The path an API request SHOULD have asked for, or `null` when it already did.
+ *
+ * 🔴 One rule, and it is the one that broke the Openclaw page: a trailing slash on an API
+ * path is never meaningful. Hono mounts a sub-app's `get("/")` at the mount point WITHOUT
+ * a trailing slash and then matches strictly, so `/api/openclaw/` is a different path
+ * from `/api/openclaw` and matched nothing at all. Normalising once, in front of the
+ * router, means no caller anywhere can spell it the losing way again — which a fix in the
+ * one client module that happened to do it would not have bought.
+ *
+ * The query string is untouched: only the path is rewritten.
+ */
+export function canonicalApiPath(urlPath: string): string | null {
+	if (!isApiPath(urlPath) || !urlPath.endsWith("/")) return null;
+	const trimmed = urlPath.replace(/\/+$/, "");
+	return trimmed === urlPath ? null : trimmed;
+}
+
+/**
+ * The same normalisation, applied to a whole request. Returns the request unchanged when
+ * there is nothing to normalise, so the hot path allocates nothing.
+ *
+ * 🔴 Wrap it around the ONE function every response leaves through — the `fetch` a host
+ * hands `Bun.serve` or exports from a Worker — and never as a Hono middleware. Hono runs
+ * middleware in registration order against handlers registered AFTER it, and an app's
+ * routes are mounted before the host is built; a middleware added at that point runs for
+ * none of them. It also cannot change which route matches, which is the entire job here.
+ */
+export function canonicalApiRequest(request: Request): Request {
+	const url = new URL(request.url);
+	const canonical = canonicalApiPath(url.pathname);
+	if (canonical === null) return request;
+	url.pathname = canonical;
+	return new Request(url, request);
+}
+
+/**
+ * What an unmatched API path answers — a JSON 404 that names itself.
+ *
+ * 🔴 The commit is in the body on purpose. The two reasons a route is missing are "this
+ * path never existed" and "this process is older than the page that asked", and they need
+ * different hands; without the commit a client can only guess, and the guess one printed
+ * for the owner sent him to deploy a commit that would not have fixed anything.
+ *
+ * 🔴 Safe to publish only where the floor sits BEHIND the app's gate, which is where every
+ * caller puts it — an unauthenticated request is answered 401 by the gate, matched or not.
+ * An app whose API namespace is open sends its own, terser body instead; see the module
+ * header.
+ */
+export function apiNotFoundBody(
+	method: string,
+	urlPath: string,
+	app: string,
+	commit: string | null | undefined,
+): { error: string; route: string; app: string; commit: string | null } {
+	return {
+		error:
+			`no such route: ${method} ${urlPath}. ${app} is serving ${commit ?? "an unreadable commit"} ` +
+			"and has no such API route — either the path is wrong, or this process is older than the page " +
+			"that asked for it. It is NOT the app shell: nothing under /api/ is ever answered with HTML.",
+		route: `${method} ${urlPath}`,
+		app,
+		commit: commit ?? null,
+	};
+}
+
 export function installCrashHandlers(name: string): void {
 	process.on("uncaughtException", (error) => {
 		console.error(`[${name}] uncaught exception — exiting`, error);

package/src/smoke.ts

@@ -39,6 +39,22 @@
  * exactly where it is. {@link Smoke.finish} is the single place that code is
  * decided, so the two apps reading it cannot disagree about what a `2` meant.
  *
+ * ## The ONE check that lives here, and why it is not an app's to write
+ *
+ * {@link sameDeployedShell} is the exception to "no checks", and the paragraph
+ * above is its argument rather than an argument against it: every incident in that
+ * list is *the deploy said yes and the visitor got something else*, and asking one
+ * address can never see that. It is a check about the ADDRESSES of a deployment,
+ * which every app has and no app owns — not about any app's routes, payloads or
+ * titles, which stay out.
+ *
+ * Measured 2026-09-18 on `patterns`: the origin served the shell this checkout
+ * built, `patterns.cursedalchemy.com` served one built on 2026-09-12 out of a
+ * Worker nobody knew about, and **every automated surface was green for six days.**
+ * The app-local implementation that found it — `apps/patterns/scripts/worker-smoke.ts`,
+ * `CROSS_CHECKS` — is what this generalises, because five more apps are moving
+ * behind an edge Worker and a check told ONE NAME is a check about that name.
+ *
  * ## What this module will never grow
  *
  * No route lists, no health-payload shapes, no upload sizes, no titles. Those are
@@ -224,3 +240,184 @@ export async function guarded(smoke: Smoke, check: string, body: () => Promise<v
 		smoke.record(check, false, `could not complete against ${smoke.base}: ${failed.message}${smoke.dnsHint(failed)}`);
 	}
 }
+
+/** What one address said when it was asked for the shell. */
+export interface AddressShell {
+	/** The address as it was passed in. */
+	address: string;
+	/** Same-origin built files the shell references, de-duplicated and sorted. */
+	assets: string[];
+}
+
+export interface ShellAgreement {
+	/** True only when every address named the same non-empty set of built files. */
+	agreed: boolean;
+	/** One line naming which address served what — the whole point on a failure. */
+	detail: string;
+	shells: AddressShell[];
+}
+
+export interface ShellOptions {
+	/** The document to compare. The shell, so `/` unless an app's entry is elsewhere. */
+	path?: string;
+	/** Per-request ceiling, matching {@link SmokeOptions.timeoutMs}'s default. */
+	timeoutMs?: number;
+	/** The cache-busting query value. Injected so a test can be deterministic. */
+	cacheBust?: () => string;
+	/** Injected for tests. Defaults to the global `fetch`. */
+	fetch?: (url: string, init: RequestInit) => Promise<Response>;
+}
+
+/**
+ * `src="…"` and `href="…"`, either quote. Attribute scan, not a parser — see
+ * {@link builtAssetsIn}. The leading whitespace is what keeps `data-src` and
+ * `xlink:href` out of the comparison.
+ */
+const REFERENCE = /\s(?:src|href)\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
+/** What a bundler emits and a shell names. Extensions, because hashes are not universal. */
+const BUILT_FILE = /\.(?:js|mjs|cjs|css)$/i;
+
+function hostOf(address: string): string | null {
+	try {
+		return new URL(address).host;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * The built files a shell references, as paths — the stable part of an HTML body.
+ *
+ * 🔴 **Same-origin only, and that is load-bearing rather than tidy.** The two
+ * addresses of one deployment legitimately differ in what a third party injected:
+ * on the app this check was built for, the zone's Web Analytics Automatic Setup
+ * appends `static.cloudflareinsights.com/beacon.min.js` at the edge and not on
+ * loopback. Comparing bodies, or comparing every `.js` a shell names, fails on that
+ * every time — a check that reds on a healthy deploy is one somebody turns off.
+ *
+ * Nothing here parses HTML: a bundler-emitted shell is machine-written, and the
+ * comparison only has to be STABLE between two copies of the same one.
+ */
+export function builtAssetsIn(html: string, address: string): string[] {
+	const host = hostOf(address);
+	const found = new Set<string>();
+	for (const match of html.matchAll(REFERENCE)) {
+		const raw = (match[1] ?? match[2] ?? "").trim();
+		if (!raw) continue;
+		let url: URL;
+		try {
+			url = new URL(raw, address);
+		} catch {
+			continue;
+		}
+		if (url.host !== host) continue;
+		if (!BUILT_FILE.test(url.pathname)) continue;
+		found.add(url.pathname);
+	}
+	return [...found].sort();
+}
+
+/**
+ * Ask every address of ONE deployment for the shell, and say whether they agree.
+ *
+ * 🔴 The assertion is **"every address agrees"**, not "the edge matches the
+ * origin" — which is the shape that survives an app having no origin left to
+ * compare against, and the reason this takes a list rather than a pair. Two is the
+ * usual list (the public hostname and `http://127.0.0.1:<port>`); a Worker's is the
+ * custom domain and its `*.workers.dev` preview, because a preview URL is not
+ * behind the cache.
+ *
+ * Every request is cache-busted, because the question is what that address HAS,
+ * not what it hands a repeat visitor.
+ */
+export async function compareDeployedShells(addresses: string[], options: ShellOptions = {}): Promise<ShellAgreement> {
+	const path = options.path ?? "/";
+	const timeoutMs = options.timeoutMs ?? 20_000;
+	const cacheBust = options.cacheBust ?? (() => Math.random().toString(36).slice(2));
+	const send = options.fetch ?? ((url: string, init: RequestInit) => fetch(url, init));
+
+	// 🔴 Loud, not silent. One address cannot disagree with itself, so a run that
+	// quietly passed here would be a skip wearing a pass — the exact reading that
+	// let a six-day-old shell sit behind six green surfaces.
+	if (addresses.length < 2) {
+		return {
+			agreed: false,
+			detail:
+				`needs at least two addresses of the same deployment and got ${addresses.length}` +
+				` (${addresses.join(", ") || "none"}) — one address cannot disagree with itself,` +
+				" so there is nothing here that could have failed.",
+			shells: [],
+		};
+	}
+
+	const shells: AddressShell[] = [];
+	const problems: string[] = [];
+	for (const address of addresses) {
+		const url = new URL(path, address);
+		url.searchParams.set("cb", cacheBust());
+		// 🔴 Re-thrown WITH the address and with the original message intact: which
+		// of the addresses could not be reached is the whole diagnosis, and
+		// {@link Smoke.dnsHint} still has to recognise an ENOTFOUND inside it.
+		const response = await send(url.toString(), {
+			redirect: "manual",
+			signal: AbortSignal.timeout(timeoutMs),
+			headers: { accept: "text/html" },
+		}).catch((thrown: unknown) => {
+			const failed = thrown as Error;
+			throw new Error(`${address} could not be reached — ${failed.message}`);
+		});
+		if (response.status !== 200) {
+			problems.push(`${address} answered ${response.status} for ${path}`);
+			shells.push({ address, assets: [] });
+			continue;
+		}
+		const assets = builtAssetsIn(await response.text(), address);
+		if (assets.length === 0) problems.push(`${address} served a shell naming no built assets`);
+		shells.push({ address, assets });
+	}
+
+	const named = (shell: AddressShell) => `${shell.address} → ${shell.assets.join(", ") || "(none)"}`;
+	if (problems.length > 0) {
+		return { agreed: false, detail: `${problems.join("; ")} — ${shells.map(named).join(" | ")}`, shells };
+	}
+
+	const distinct = new Set(shells.map((shell) => shell.assets.join(",")));
+	if (distinct.size > 1) {
+		return {
+			agreed: false,
+			detail:
+				`the addresses of one deployment serve DIFFERENT built assets — ${shells.map(named).join(" | ")}.` +
+				" Something in front of this app is answering with bytes this checkout did not build.",
+			shells,
+		};
+	}
+
+	return { agreed: true, detail: `${shells.length} addresses agree — ${shells[0]?.assets.join(", ")}`, shells };
+}
+
+/** The check's name in the ledger. Exported so a caller can talk about its own result. */
+export const SAME_SHELL_CHECK = "every address serves the same built client";
+
+/**
+ * {@link compareDeployedShells}, recorded — and an EDGE fault when it disagrees.
+ *
+ * 🔴 **Code 2, deliberately: a disagreement is never a reason to roll back.** The
+ * origin in that comparison is serving what this checkout built; what is wrong sits
+ * in FRONT of it — a shadowing Worker, a cache rule, a stale Assets binding — and
+ * reverting the application code cannot reach any of them. It would discard the
+ * good deploy and leave the visitor on the same old bytes, which is the failure the
+ * exit-code contract at the top of this file exists to prevent.
+ *
+ * ```ts
+ * await sameDeployedShell(smoke, [smoke.base, `http://127.0.0.1:${port}`]);
+ * ```
+ */
+export async function sameDeployedShell(smoke: Smoke, addresses: string[], options: ShellOptions = {}): Promise<boolean> {
+	let agreed = false;
+	await guarded(smoke, SAME_SHELL_CHECK, async () => {
+		const agreement = await compareDeployedShells(addresses, options);
+		agreed = smoke.record(SAME_SHELL_CHECK, agreement.agreed, agreement.detail);
+		if (!agreement.agreed) smoke.markEdgeFault();
+	});
+	return agreed;
+}