cursedops 0.2.1 → 0.2.3

package/README.md

@@ -11,7 +11,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 — 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 |
+| `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 |
 
 Bun, zero runtime dependencies, ships TypeScript source. Nothing here knows an app's
 name, a hostname, a port or a route.
@@ -143,6 +144,41 @@ Nothing else. The checks are the part `desk` and `flix` wrote differently on pur
 and a shared kit that starts absorbing route lists and health-payload shapes is how the
 last one reached 277 files.
 
+## `cursedops/api-floor`
+
+```ts
+import { API_PREFIX, apiNotFoundBody, canonicalApiPath, canonicalApiRequest } from "cursedops/api-floor";
+
+// AFTER the app's routes, BEFORE the static catch-all, and `all` not `get`.
+const floor = (c) => {
+  const urlPath = new URL(c.req.url).pathname;
+  // A trailing slash is never meaningful under /api/ — re-dispatch, once.
+  if (canonicalApiPath(urlPath) !== null) return app.fetch(canonicalApiRequest(c.req.raw));
+  return Response.json(apiNotFoundBody(c.req.method, urlPath, "myapp", commit), { status: 404 });
+};
+app.all(API_PREFIX, floor);        // `"/api/*"` alone does NOT match a bare `/api`
+app.all(`${API_PREFIX}/*`, floor);
+```
+
+🔴 Measured 2026-09-17 on `station`: a page that had never loaded on any commit, because
+its client asked for `/api/openclaw/`, Hono mounts a sub-app's `get("/")` at the mount
+point without the trailing slash and matches strictly, and the miss fell into
+`app.get("*")` and came back as 1.7 KB of `index.html` **with a 200**. The client read
+that HTML honestly — *"an API older than this page"* — and sent the owner to deploy a
+commit that could not have helped.
+
+🔴 Wire it **inside the router**, never as a wrapper around the host's `fetch`. A router
+has more callers than `Bun.serve` — a Worker's `export default`, and every harness that
+drives `app.fetch` — and a wrap installed at one of them is absent from the rest. That is
+the exact fault the previous generation's artifact shipped for six days with a green
+harness.
+
+No `node:` import, no `Bun.` global, no `process` — asserted by `apiFloor.test.ts`, not
+by this paragraph — so it mounts unchanged inside a Cloudflare Worker, which is where
+`patterns` mounts it. `apiNotFoundBody` is the DEFAULT body and not the only one: an app
+whose API namespace is not behind a gate keeps a terser phrase of its own and takes the
+predicates.
+
 ## `cursedops/serve`
 
 ```ts

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "cursedops",
-	"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.",
+	"version": "0.2.3",
+	"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. Mechanism only — no app knows its name from here. Bun, zero dependencies, ships source.",
 	"type": "module",
 	"scripts": {
 		"typecheck": "tsc -p tsconfig.json --noEmit",
@@ -24,6 +24,12 @@
 			"source": "./src/launchd.ts",
 			"import": "./src/launchd.ts"
 		},
+		"./api-floor": {
+			"types": "./src/apiFloor.ts",
+			"bun": "./src/apiFloor.ts",
+			"source": "./src/apiFloor.ts",
+			"import": "./src/apiFloor.ts"
+		},
 		"./serve": {
 			"types": "./src/serve.ts",
 			"bun": "./src/serve.ts",

package/src/apiFloor.ts

@@ -0,0 +1,139 @@
+/**
+ * `cursedops/api-floor` — the rule that an unmatched `/api/...` is answered with a
+ * phrase and NEVER with the single-page app shell.
+ *
+ * It arrives by this library's own entry arithmetic, not by taste. `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 four 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.
+ *
+ * ## 🔴 Why this is its own subpath and not part of `cursedops/serve`
+ *
+ * Nothing below imports `node:` anything, and that is a requirement rather than an
+ * accident: `patterns` mounts its floor inside a Cloudflare Worker, where the static
+ * tier next door — `fileWithin`, `statSync`, a disk to read — does not exist and must
+ * not be dragged into the bundle to reach four pure functions. `nodejs_compat` would
+ * have RESOLVED the import and shipped a partial `node:fs` shim to the edge, so the
+ * failure would have been silent weight rather than a build error. One subpath per
+ * runtime requirement is what keeps that honest; `subpathsReachNoBunBuiltin`-shaped
+ * checks can then say so rather than a comment.
+ */
+
+/** 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 a caller that guards on {@link canonicalApiPath}
+ * allocates nothing.
+ *
+ * 🔴 **Call it from INSIDE the floor handler and re-dispatch, not from the host's
+ * `fetch`.** Both work; only one of them cannot be wired up wrong. A router has many
+ * callers — `Bun.serve`, a Worker's `export default`, and every test harness that drives
+ * `app.fetch` directly — and a wrap installed at one of them is absent from the others.
+ * That is the shape of the fault this whole family exists to close: the previous
+ * generation's artifact had a floor its harness mounted correctly and production did not,
+ * and it stayed green for six days. A floor that answers
+ *
+ *     const canonical = canonicalApiPath(new URL(c.req.url).pathname);
+ *     if (canonical !== null) return app.fetch(canonicalApiRequest(c.req.raw));
+ *     return c.json(apiNotFoundBody(...), 404, ...);
+ *
+ * is reached by every caller there will ever be, costs nothing on the hot path — only a
+ * MISS gets here — and cannot loop, because the canonical path has no trailing slash left
+ * to strip and a second miss falls straight to the body.
+ *
+ * It must not be a Hono middleware either: Hono matches the route before the chain runs,
+ * so a middleware cannot change which handler answers, 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,
+	};
+}

package/src/serve.ts

@@ -1,6 +1,6 @@
 /**
- * The helpers every app's `src/server/serve.ts` wrote the same way — the
- * path-traversal guard among them, and the API floor.
+ * The four helpers every app's `src/server/serve.ts` wrote the same way — the
+ * path-traversal guard among them.
  *
  * ## Why this is a library and not eight copies
  *
@@ -48,37 +48,11 @@
  * `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.
+ * 🔴 **The API floor is deliberately NOT here — it is `cursedops/api-floor`.** It is the
+ * same family of answer (an app's HTTP tier, written the same way twice) and it has a
+ * requirement this module cannot meet: `patterns` mounts its floor inside a Cloudflare
+ * Worker, and everything in this file exists to read a disk. Splitting the subpath is
+ * what stops `node:fs` being bundled to the edge to reach four pure functions.
  */
 
 import { existsSync, realpathSync, statSync } from "node:fs";
@@ -173,86 +147,6 @@ 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);