cursedops 0.1.0

package/README.md

@@ -0,0 +1,124 @@
+# cursedops
+
+Three build-and-ops answers that two apps independently wrote the same way.
+
+```sh
+bun add cursedops
+```
+
+| subpath | what it is |
+|---|---|
+| `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 |
+
+Bun, zero runtime dependencies, ships TypeScript source. Nothing here knows an app's
+name, a hostname, a port or a route.
+
+## 🔴 The ceiling, and why this library has one
+
+This exists because `apps/desk` and `apps/flix` answered the same six build-and-ops
+questions independently, and **three of the six came out the same**. It does not exist
+because sharing is good.
+
+The library it replaces reached **277 files** in a previous generation, on the reasoning
+that a module used by 8 of 8 apps is a module worth sharing. What that produced was an
+app whose entire `vite.config.ts` was one line it could not read, a build system no app
+could opt out of, and a monorepo that could not be relocated. Every one of those 277
+files was individually defensible.
+
+So the entry rule here is arithmetic, not judgement:
+
+1. **Two apps wrote it independently.** Not one app and a plan for a second — two
+   working implementations, in the tree, that a `diff` says are the same.
+2. **It is mechanism, not identity.** If a function would need to know an app's name,
+   port, hostname, routes or health-payload shape, it belongs in the app. Every
+   function here takes those as arguments or does not see them at all.
+3. **It is a trap somebody paid for.** Each thing in here is a measured incident turned
+   into a check — the file headers carry the dates and the costs. A convenience that
+   has never prevented anything is not a reason to add a dependency to eight apps.
+
+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.
+
+### What was deliberately left in the apps
+
+The comparison that produced this library found three areas that are genuinely
+different and must stay that way. `tasks/Procedures/graduate-an-app.md` in the
+generation repo carries the full verdict table, because the next app to graduate is who
+needs to read it:
+
+- **the build** — `desk` compiles a single binary with `bun build --compile`; `flix` is
+  a Vite SPA with an asset budget. Not the same problem.
+- **the supervisor** — `desk` runs a watcher that rebuilds on a commit; `flix`
+  deliberately has none, and its deploy reinstalls the agent instead. That difference
+  changes what a rollback *is* in each app.
+- **the app config** — how an app decides it is deployed, and what that turns on, is the
+  app.
+
+`deploy.ts` is a fourth: the two scripts share a shape and roughly thirty lines of
+helpers, but they sequence genuinely different steps and a shared deploy driver is
+exactly the 277-file mistake starting again. What they share instead is the **exit-code
+contract** in `cursedops/smoke` — `0` keep, `1` roll back, `2` edge fault, do not roll
+back — which is the only part both deploy scripts actually read.
+
+## `cursedops/roots`
+
+```ts
+import { forgeRootFrom, packageRootFrom, requireForgeState } from "cursedops/roots";
+
+const generation = forgeRootFrom(import.meta.url);   // string | null
+const checkout = packageRootFrom(import.meta.url);   // string | null
+const state = requireForgeState(import.meta.dir);    // string, or a thrown message
+```
+
+A generation is defined by a `forge.env` above the checkout — the same rule its
+`check-paths` and its runner use, so the three cannot disagree. Everything returns
+`null` rather than guessing, because a function that invented a root would write files
+into a stranger's tree.
+
+🔴 The state root is **read out of `forge.env`**, never spelled here. A published
+library that hardcoded `$HOME/.<name>` would be correct for exactly one generation and
+silently wrong for its successor — which is the defect this replaced.
+
+## `cursedops/launchd`
+
+```ts
+import { renderPlist, replaceAgent, answering, declaredBy } from "cursedops/launchd";
+
+const conflict = await declaredBy(LABEL, "managed-by=olddeployer");
+if (conflict) throw new Error(`a retired deployer still declares ${LABEL}: ${conflict}`);
+
+const { boot } = await replaceAgent(LABEL, renderPlist(spec), { also: LEGACY_LABELS });
+if (boot.code !== 0) throw new Error(boot.out);
+if (!(await answering(`http://127.0.0.1:${port}/healthz`))) throw new Error("a pid is not a service");
+```
+
+`RunAtLoad` and `KeepAlive` are **not defaulted** — a server wants both, a nightly
+snapshot wants neither, and a kit that decides gets one of them wrong.
+
+## `cursedops/smoke`
+
+```ts
+import { createSmoke, guarded } from "cursedops/smoke";
+
+const smoke = createSmoke({ base: process.env.MYAPP_SMOKE_URL ?? "https://…" });
+await guarded(smoke, "gate", async () => {
+  const response = await smoke.anonymous("/api/v1/private");
+  smoke.record("gate", response.status === 401, `anonymous → ${response.status}`);
+});
+smoke.finish();   // exits 0, 1 or 2
+```
+
+No checks, ever. 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.
+
+## Verifying
+
+```sh
+cd "$FORGE/libs/cursedops" && bun run verify
+```
+
+`paths`, `typecheck`, `lint`, then the suite. It runs as `prepublishOnly`, so a publish
+cannot go out around it.

package/package.json

@@ -0,0 +1,48 @@
+{
+	"name": "cursedops",
+	"version": "0.1.0",
+	"description": "The three build-and-ops answers two apps independently wrote the same way: finding a generation's roots without knowing a path, macOS launchd agent install/replace/remove, and the scaffolding of a deployed smoke. 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 .",
+		"verify": "bun run paths && bun run typecheck && bun run lint && bun run test",
+		"prepublishOnly": "bun run verify"
+	},
+	"exports": {
+		"./roots": {
+			"types": "./src/roots.ts",
+			"bun": "./src/roots.ts",
+			"source": "./src/roots.ts",
+			"import": "./src/roots.ts"
+		},
+		"./launchd": {
+			"types": "./src/launchd.ts",
+			"bun": "./src/launchd.ts",
+			"source": "./src/launchd.ts",
+			"import": "./src/launchd.ts"
+		},
+		"./smoke": {
+			"types": "./src/smoke.ts",
+			"bun": "./src/smoke.ts",
+			"source": "./src/smoke.ts",
+			"import": "./src/smoke.ts"
+		},
+		"./package.json": "./package.json"
+	},
+	"files": [
+		"src",
+		"!src/**/*.test.ts"
+	],
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.14",
+		"@types/bun": "^1.3.14",
+		"typescript": "^5.7.2"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"license": "MIT"
+}

package/src/launchd.ts

@@ -0,0 +1,405 @@
+/**
+ * Installing, replacing and removing a macOS launchd user agent — the mechanism
+ * only, never the spec.
+ *
+ * ## What is here and what is deliberately not
+ *
+ * Two apps wrote this twice (`apps/desk/src/cli/service.ts`,
+ * `apps/flix/scripts/service.ts`). Measured 2026-09-16, {@link waitForLabelGone}
+ * was character-identical between them and {@link bootstrapWithRetry} differed
+ * only in how it spelled the same default. What was NOT the same — the labels, the
+ * environment, the command, which legacy names to sweep, whether there is a second
+ * job — is the part each app legitimately owns, and none of it is in here.
+ *
+ * 🔴 That split is the whole design. The previous generation's shared kit reached
+ * 277 files because "every app uses it" was treated as sufficient reason to share,
+ * and the result was an app whose entire deployment was one line it could not read.
+ * The line here: **launchd's traps are shared, an app's identity is not.** If a
+ * function in this file would need to know an app's name, it belongs in the app.
+ *
+ * ## The four traps, each of which was paid for
+ *
+ * 🔴 **A green install over a crash-looping agent.** `cursedesk service install`
+ * printed `running (pid 51073)` over an agent dying on every restart: launchd ran
+ * it as `…/node_modules/bun/bin/bun.exe`, a directory holding `bun.exe` and no
+ * `bun`, so every `Bun.spawn(["bun", …])` died with ENOENT. {@link answering} is
+ * why a pid is never reported as a service — and {@link launchPathEntries} is why
+ * the shim's real home goes on the agent's PATH rather than only `dirname(bun)`.
+ *
+ * 🔴 **`bootout` returning is not the job being gone.** launchd tears a job down
+ * asynchronously and bootstrapping into the gap answers `Bootstrap failed: 5:
+ * Input/output error`, a message about nothing. An `install` that reinstalls every
+ * time — which is every deploy — fails on its SECOND run without
+ * {@link waitForLabelGone}. Measured 2026-09-13 on a first real deploy.
+ *
+ * 🔴 **Deleting the plist before booting the job out** leaves launchd holding a job
+ * whose definition is gone, which nothing left on the machine can name. That is
+ * the one state here that needs a reboot to leave, and {@link clearAgents} is
+ * ordered so it cannot happen.
+ *
+ * 🔴 **A bootout that a sync job overrules is not a removal.** A retired
+ * generation's deployer re-renders every spec its apps declare and bootstraps
+ * whatever is missing — measured 2026-09-13, a label came back eleven minutes
+ * after being booted out and having its plist moved away. Only deleting the
+ * DECLARATION held, so {@link declaredBy} lets an install refuse to proceed while
+ * a foreign declaration for its label still exists.
+ *
+ * ## 🔴 Secrets are referenced, never inlined
+ *
+ * `~/Library/LaunchAgents` is an ordinary readable directory. Anything secret
+ * belongs in a 0600 file the agent SOURCES; {@link sourcedCommand} builds that
+ * one-liner, and a consumer should pin it with a test that fails if a secret value
+ * ever reaches the plist text.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export interface CommandResult {
+	code: number;
+	out: string;
+}
+
+/**
+ * How this module reaches launchd and the LaunchAgents directory.
+ *
+ * Injectable as one object because the interesting behaviour — clearing a label
+ * and *waiting* for it to go — cannot otherwise be reached from a test that does
+ * not install a real login agent first, and a test nobody runs is not a test.
+ */
+export interface LaunchdOps {
+	run: (...args: string[]) => CommandResult;
+	domain: string;
+	plistFor: (label: string) => string;
+	exists: (path: string) => boolean;
+	read: (path: string) => Promise<string>;
+	write: (path: string, body: string) => Promise<void>;
+	remove: (path: string) => Promise<void>;
+	sleep: (ms: number) => Promise<void>;
+}
+
+/** Where launchd insists on finding a user agent's declaration. */
+export function plistPath(label: string): string {
+	return join(homedir(), "Library", "LaunchAgents", `${label}.plist`);
+}
+
+/** The user launchd domain everything here talks to. */
+export function guiDomain(): string {
+	return `gui/${process.getuid?.() ?? 501}`;
+}
+
+export function realOps(overrides: Partial<LaunchdOps> = {}): LaunchdOps {
+	return {
+		run: (...args) => {
+			const result = spawnSync("launchctl", args, { encoding: "utf8" });
+			return { code: result.status ?? 1, out: `${result.stdout ?? ""}${result.stderr ?? ""}`.trim() };
+		},
+		domain: guiDomain(),
+		plistFor: plistPath,
+		exists: existsSync,
+		read: (path) => readFile(path, "utf8"),
+		write: async (path, body) => {
+			await writeFile(path, body, "utf8");
+		},
+		remove: async (path) => {
+			await rm(path, { force: true });
+		},
+		sleep: (ms) => new Promise<void>((resolve) => setTimeout(resolve, ms)),
+		...overrides,
+	};
+}
+
+/**
+ * The PATH an agent needs, given the absolute runtime it will run.
+ *
+ * 🔴 `dirname(bun)` alone is NOT enough — see the ENOENT trap in the header. The
+ * shim's real home goes on the list too, and a caller's own spawns should use an
+ * absolute runtime regardless rather than merely being luckier.
+ */
+export function launchPathEntries(runtime: string): string[] {
+	return [dirname(runtime), join(homedir(), ".bun", "bin"), "/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin"];
+}
+
+/** {@link launchPathEntries}, joined the way a `PATH` variable wants it. */
+export function launchPath(runtime: string): string {
+	return launchPathEntries(runtime).join(":");
+}
+
+export function escapeXml(value: string): string {
+	return value.replace(/[<>&'"]/g, (char) => ({ "<": "&lt;", ">": "&gt;", "&": "&amp;", "'": "&apos;", '"': "&quot;" })[char] as string);
+}
+
+/** Single-quote a string for `/bin/sh -c`, closing and reopening around any quote. */
+export function shellQuote(value: string): string {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * The one-liner for an agent whose credentials live in a 0600 file.
+ *
+ * `set -a` exports everything the file defines; `[ -f … ]` keeps a missing file
+ * from being a syntax error, because an app's OWN boot guard gives a far better
+ * message about a missing credential than `bash` does about a missing file. `exec`
+ * replaces the shell so launchd's `KeepAlive` supervises the real process rather
+ * than a wrapper that would outlive its crash.
+ */
+export function sourcedCommand(secretsFile: string, argv: readonly string[]): string {
+	const command = argv.map(shellQuote).join(" ");
+	return `set -a; [ -f ${shellQuote(secretsFile)} ] && . ${shellQuote(secretsFile)}; set +a; exec ${command}`;
+}
+
+export interface CalendarInterval {
+	Minute?: number;
+	Hour?: number;
+	Day?: number;
+	Month?: number;
+	Weekday?: number;
+}
+
+export interface PlistSpec {
+	label: string;
+	programArguments: readonly string[];
+	workingDirectory: string;
+	environment?: Record<string, string>;
+	standardOutPath?: string;
+	standardErrorPath?: string;
+	runAtLoad?: boolean;
+	keepAlive?: boolean;
+	throttleInterval?: number;
+	processType?: string;
+	startCalendarInterval?: CalendarInterval;
+	/**
+	 * The provenance comment written at the top of the file.
+	 *
+	 * 🔴 Not decoration. A machine that has run more than one generation carries
+	 * plists from each, and the ONLY way to tell whose a file is — before deciding
+	 * whether deleting it is safe — is a marker in its text. {@link declaredBy}
+	 * reads exactly this.
+	 */
+	managedBy?: string;
+	/** Recorded beside `managedBy`, so `grep` over LaunchAgents answers "whose is this". */
+	app?: string;
+}
+
+function entries(record: Record<string, string>, indent: string): string {
+	return Object.entries(record)
+		.map(([key, value]) => `${indent}<key>${escapeXml(key)}</key>\n${indent}<string>${escapeXml(value)}</string>`)
+		.join("\n");
+}
+
+function integers(record: Record<string, number>, indent: string): string {
+	return Object.entries(record)
+		.map(([key, value]) => `${indent}<key>${escapeXml(key)}</key>\n${indent}<integer>${value}</integer>`)
+		.join("\n");
+}
+
+/**
+ * Render a launchd agent declaration.
+ *
+ * Every key is optional except the three that make a job a job, because the
+ * alternative — a spec object with defaults for `KeepAlive` and `RunAtLoad` —
+ * quietly decides the most consequential property of a job on a consumer's behalf.
+ * A long-running server wants both; a nightly snapshot wants neither, and one of
+ * those two being wrong is an app that either never starts or never stops.
+ */
+export function renderPlist(spec: PlistSpec): string {
+	const lines: string[] = [];
+	lines.push(`\t<key>Label</key>`, `\t<string>${escapeXml(spec.label)}</string>`);
+	lines.push(`\t<key>ProgramArguments</key>`, `\t<array>`);
+	for (const argument of spec.programArguments) lines.push(`\t\t<string>${escapeXml(argument)}</string>`);
+	lines.push(`\t</array>`);
+	lines.push(`\t<key>WorkingDirectory</key>`, `\t<string>${escapeXml(spec.workingDirectory)}</string>`);
+	if (spec.environment && Object.keys(spec.environment).length > 0) {
+		lines.push(`\t<key>EnvironmentVariables</key>`, `\t<dict>`, entries(spec.environment, "\t\t"), `\t</dict>`);
+	}
+	if (spec.startCalendarInterval) {
+		const defined = Object.fromEntries(Object.entries(spec.startCalendarInterval).filter(([, value]) => typeof value === "number")) as Record<string, number>;
+		lines.push(`\t<key>StartCalendarInterval</key>`, `\t<dict>`, integers(defined, "\t\t"), `\t</dict>`);
+	}
+	if (spec.runAtLoad !== undefined) lines.push(`\t<key>RunAtLoad</key>`, `\t<${spec.runAtLoad}/>`);
+	if (spec.keepAlive !== undefined) lines.push(`\t<key>KeepAlive</key>`, `\t<${spec.keepAlive}/>`);
+	if (spec.throttleInterval !== undefined) lines.push(`\t<key>ThrottleInterval</key>`, `\t<integer>${spec.throttleInterval}</integer>`);
+	if (spec.standardOutPath) lines.push(`\t<key>StandardOutPath</key>`, `\t<string>${escapeXml(spec.standardOutPath)}</string>`);
+	if (spec.standardErrorPath) lines.push(`\t<key>StandardErrorPath</key>`, `\t<string>${escapeXml(spec.standardErrorPath)}</string>`);
+	if (spec.processType) lines.push(`\t<key>ProcessType</key>`, `\t<string>${escapeXml(spec.processType)}</string>`);
+
+	const provenance = spec.managedBy ? `<!-- managed-by=${escapeXml(spec.managedBy)} label=${escapeXml(spec.label)}${spec.app ? ` app=${escapeXml(spec.app)}` : ""} -->\n` : "";
+	return `<?xml version="1.0" encoding="UTF-8"?>
+${provenance}<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+${lines.join("\n")}
+</dict>
+</plist>
+`;
+}
+
+/**
+ * The agent's pid, or `null` when launchd has the job but nothing is running.
+ *
+ * A pid is the only honest evidence that a job STARTED: an agent can be loaded and
+ * failing to start on every attempt, and `launchctl print` reports that without
+ * complaining. It is still not evidence that the app is SERVING — that is
+ * {@link answering}.
+ */
+export function agentPid(label: string, ops: Partial<LaunchdOps> = {}): string | null {
+	const { run, domain } = realOps(ops);
+	const printed = run("print", `${domain}/${label}`);
+	if (printed.code !== 0) return null;
+	return /\bpid = (\d+)/.exec(printed.out)?.[1] ?? null;
+}
+
+/** What a machine actually carries for one label. */
+export interface AgentPresence {
+	label: string;
+	path: string;
+	/** The plist is in `~/Library/LaunchAgents`. */
+	onDisk: boolean;
+	/** launchd has the job, whether or not anything is running under it. */
+	loaded: boolean;
+}
+
+/**
+ * Every label in `labels` this machine carries an agent under, in the order given.
+ *
+ * Both halves matter and they come apart: a hand-edited machine can have a plist
+ * with nothing loaded, and an `rm` without a `bootout` leaves a job loaded with no
+ * file behind it. Either one is an agent, and either one has to be cleared before
+ * a new one is bootstrapped.
+ */
+export function findAgents(labels: readonly string[], ops: Partial<LaunchdOps> = {}): AgentPresence[] {
+	const { run, domain, exists, plistFor } = realOps(ops);
+	return labels
+		.map((label) => {
+			const path = plistFor(label);
+			return { label, path, onDisk: exists(path), loaded: run("print", `${domain}/${label}`).code === 0 };
+		})
+		.filter((found) => found.onDisk || found.loaded);
+}
+
+/**
+ * Wait for a booted-out label to actually leave launchd's domain.
+ *
+ * `launchctl print` failing is the only honest evidence: while the job is still
+ * shutting down it keeps printing, and `bootstrap` keeps failing with an I/O error
+ * that says nothing about why.
+ */
+export async function waitForLabelGone(label: string, ops: Partial<LaunchdOps> = {}, { timeoutMs = 10_000, stepMs = 200 } = {}): Promise<boolean> {
+	const { run, domain, sleep } = realOps(ops);
+	for (let waited = 0; waited <= timeoutMs; waited += stepMs) {
+		if (run("print", `${domain}/${label}`).code !== 0) return true;
+		if (waited + stepMs > timeoutMs) break;
+		await sleep(stepMs);
+	}
+	return false;
+}
+
+/**
+ * Remove every agent the machine carries under any of `labels`.
+ *
+ * The order inside one label is the whole of it: boot it out, wait for launchd to
+ * let go, THEN delete the file. See the header for what the other order costs.
+ *
+ * 🔴 Pass the legacy names too, not just the current one. An agent left loaded
+ * under a name a build no longer knows is a second copy of the app at the next
+ * login, fighting over one database and one port — strictly worse than the name
+ * being wrong, and invisible to the command whose whole job is removing it.
+ */
+export async function clearAgents(labels: readonly string[], ops: Partial<LaunchdOps> = {}): Promise<AgentPresence[]> {
+	const resolved = realOps(ops);
+	const cleared: AgentPresence[] = [];
+	for (const found of findAgents(labels, resolved)) {
+		if (found.loaded) {
+			resolved.run("bootout", `${resolved.domain}/${found.label}`);
+			await waitForLabelGone(found.label, resolved);
+		}
+		if (found.onDisk) await resolved.remove(found.path);
+		cleared.push(found);
+	}
+	return cleared;
+}
+
+/**
+ * Bootstrap, retrying the one error that means "ask again in a moment".
+ *
+ * Error 5 is launchd's answer while a previous incarnation of the label is still
+ * going away. Every other failure is real — a malformed plist, a missing program —
+ * and is returned on the first try rather than retried five times into a slower
+ * version of the same message.
+ */
+export async function bootstrapWithRetry(
+	path: string,
+	{ attempts = 5, stepMs = 500, ops = {} as Partial<LaunchdOps> } = {},
+): Promise<CommandResult & { tries: number }> {
+	const { run, domain, sleep } = realOps(ops);
+	const boot = (target: string) => run("bootstrap", domain, target);
+	let last = boot(path);
+	let tries = 1;
+	while (tries < attempts && last.code !== 0 && /Input\/output error|Bootstrap failed: 5/.test(last.out)) {
+		await sleep(stepMs);
+		last = boot(path);
+		tries++;
+	}
+	return { ...last, tries };
+}
+
+/**
+ * Clear, write, bootstrap — in that order, and the order is the point.
+ *
+ * Replacing a running agent means removing the old one first: launchd will not
+ * reload a label that is already bootstrapped, and the failure it reports for that
+ * is not obviously about a stale agent.
+ */
+export async function replaceAgent(
+	label: string,
+	contents: string,
+	{ also = [] as readonly string[], ops = {} as Partial<LaunchdOps>, attempts = 5 } = {},
+): Promise<{ path: string; cleared: AgentPresence[]; boot: CommandResult & { tries: number } }> {
+	const resolved = realOps(ops);
+	const path = resolved.plistFor(label);
+	const cleared = await clearAgents([label, ...also], resolved);
+	await resolved.write(path, contents);
+	return { path, cleared, boot: await bootstrapWithRetry(path, { attempts, ops: resolved }) };
+}
+
+/**
+ * Is somebody ELSE still declaring this label? Returns the offending path, or `null`.
+ *
+ * `marker` is the provenance string a foreign deployer stamps into its plists —
+ * see {@link PlistSpec.managedBy}. This is checked at install time rather than
+ * documented, because a warning in a document is exactly what the 2026-09-13
+ * measurement in the header disproved.
+ */
+export async function declaredBy(label: string, marker: string, ops: Partial<LaunchdOps> = {}): Promise<string | null> {
+	const { plistFor, exists, read } = realOps(ops);
+	const path = plistFor(label);
+	if (!exists(path)) return null;
+	const body = await read(path).catch(() => "");
+	return body.includes(marker) ? path : null;
+}
+
+/**
+ * Does the URL answer? A pid is not a service — see the header.
+ *
+ * `< 500` rather than `ok`, because a deployed app behind its own sign-in gate
+ * answers `401` to an unauthenticated probe and that is a SERVING app. A caller
+ * that has a health endpoint should name it and tighten the predicate.
+ */
+export async function answering(
+	url: string,
+	{ timeoutMs = 45_000, stepMs = 500, requestTimeoutMs = 2_000, accept = (response: Response) => response.status < 500, sleep = (ms: number) => new Promise<void>((done) => setTimeout(done, ms)) } = {},
+): Promise<boolean> {
+	const deadline = Date.now() + timeoutMs;
+	for (;;) {
+		try {
+			if (accept(await fetch(url, { signal: AbortSignal.timeout(requestTimeoutMs) }))) return true;
+		} catch {
+			// Not listening yet.
+		}
+		if (Date.now() + stepMs >= deadline) return false;
+		await sleep(stepMs);
+	}
+}

package/src/roots.ts

@@ -0,0 +1,174 @@
+/**
+ * Finding the generation — and this checkout's package — without knowing a path.
+ *
+ * ## Why this is a library rather than four lines in each app
+ *
+ * It was four lines in each app, twice, and the two copies had already drifted.
+ * `apps/desk/scripts/forgeRoot.ts` and `apps/flix/scripts/forgeRoot.ts` were
+ * written independently against the same problem; measured 2026-09-16 the
+ * `findForgeRoot` bodies were character-identical and the surrounding halves were
+ * not, which is the definition of an extraction that is measurable rather than
+ * speculative. Two implementations, one behaviour.
+ *
+ * ## The rule this serves
+ *
+ * Exactly ONE file in a generation may contain a literal path: its `forge.env`.
+ * Every script, doc, task and launchd job reaches the two roots through the
+ * variables that file exports, and the generation's `check-paths` fails the moment
+ * a second file knows a path. The measurement behind that rule: across previous
+ * generations 233 files hardcoded a state root, so no migration could ever be
+ * finished and a decommissioned host was still being cited weeks after it died.
+ *
+ * So nothing here knows a path either. `forge.env`'s presence above a directory is
+ * the definition of "inside a generation" — the same rule `check-paths` and the
+ * runner use, so the three cannot disagree — and the state root is read OUT of
+ * that file rather than spelled again here.
+ *
+ * 🔴 **Everything returns `null` rather than guessing.** A copy of a tree outside a
+ * generation — an archive, a clone somebody took, a `node_modules` from back when
+ * something published — has no `forge.env` above it, and a function that invented
+ * one would write files into a stranger's tree. Every caller must handle `null` by
+ * doing nothing and saying so; {@link requireForgeState} is the one-line way to do
+ * that with a message worth reading.
+ *
+ * 🔴 **This library is published, so it may not know a generation's NAME either.**
+ * `apps/flix/scripts/forgeRoot.ts` fell back to `$HOME/.cursedforge` when the
+ * environment carried no `FORGE_STATE`, which is correct for exactly one
+ * generation and silently wrong for its successor. {@link forgeState} parses the
+ * marker file instead, which is the only spelling that survives the next
+ * generation being called something else.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** The marker file whose presence defines "inside a generation". */
+export const MARKER = "forge.env";
+
+/**
+ * How far up either walk will look before giving up.
+ *
+ * A bound rather than "until `/`" so a misuse is a `null` in milliseconds instead
+ * of a stat of every ancestor of a path that was never going to match.
+ */
+const MAX_HOPS = 16;
+
+/** The directory holding the module at `fromUrl`. Pass `import.meta.url`. */
+export function fileDir(fromUrl: string): string {
+	return dirname(fileURLToPath(fromUrl));
+}
+
+/** Walk up from `from` looking for a directory that contains `marker`. */
+function walkUp(from: string, marker: string): string | null {
+	let dir = resolve(from);
+	for (let hops = 0; hops < MAX_HOPS; hops++) {
+		if (existsSync(join(dir, marker))) return dir;
+		const up = dirname(dir);
+		if (up === dir) return null;
+		dir = up;
+	}
+	return null;
+}
+
+/** The directory holding `forge.env`, or `null` when `from` is not inside a generation. */
+export function findForgeRoot(from: string): string | null {
+	return walkUp(from, MARKER);
+}
+
+/** {@link findForgeRoot} from a module's own location. Pass `import.meta.url`. */
+export function forgeRootFrom(fromUrl: string): string | null {
+	return findForgeRoot(fileDir(fromUrl));
+}
+
+/**
+ * The checkout a module belongs to — the nearest ancestor holding `package.json`.
+ *
+ * 🔴 Derived by walking, never by counting `..` from the caller. Both apps spelled
+ * their app root as `new URL("..", import.meta.url)`, which is correct only while
+ * the file stays exactly one directory deep: `desk` keeps this machinery in
+ * `src/cli/` and `flix` in `scripts/`, so the same expression means two different
+ * things in the two trees and neither survives the file being moved. Walking is
+ * also what makes it right in a worktree, where the checkout is not the one under
+ * the generation root at all.
+ */
+export function findPackageRoot(from: string): string | null {
+	return walkUp(from, "package.json");
+}
+
+/** {@link findPackageRoot} from a module's own location. Pass `import.meta.url`. */
+export function packageRootFrom(fromUrl: string): string | null {
+	return findPackageRoot(fileDir(fromUrl));
+}
+
+/**
+ * Read one `export NAME="…"` assignment out of a `forge.env`, expanding `$HOME`
+ * and any variable the file has already defined above the line being read.
+ *
+ * Deliberately not a shell: sourcing an arbitrary file to learn one value is a
+ * far larger permission than reading it, and every assignment in a `forge.env` is
+ * this shape by construction. A line the parser does not understand is skipped
+ * rather than guessed at.
+ */
+export function readForgeVar(marker: string, name: string, env: NodeJS.ProcessEnv = process.env): string | null {
+	let text: string;
+	try {
+		text = readFileSync(marker, "utf8");
+	} catch {
+		return null;
+	}
+	const known: Record<string, string> = { HOME: env.HOME?.trim() ?? "" };
+	for (const line of text.split("\n")) {
+		const match = /^\s*export\s+([A-Z_][A-Z0-9_]*)=(.*)$/.exec(line);
+		if (!match) continue;
+		const [, key, rawValue] = match as unknown as [string, string, string];
+		const unquoted = rawValue.trim().replace(/^"(.*)"$/s, "$1").replace(/^'(.*)'$/s, "$1");
+		const expanded = unquoted.replace(/\$\{?([A-Z_][A-Z0-9_]*)\}?/g, (_whole, ref: string) => known[ref] ?? "");
+		known[key] = expanded;
+		if (key === name) return expanded || null;
+	}
+	return null;
+}
+
+/**
+ * The generation's state root — secrets, data, logs, locks, binaries.
+ *
+ * `$FORGE_STATE` when the environment carries it, because that is both cheaper and
+ * the only answer available to a process started somewhere else entirely.
+ * Otherwise the `forge.env` above `from` is read, which is what makes this work
+ * inside a launchd job handed almost no environment at all, and inside a worktree
+ * whose parent generation is not the one the caller expected.
+ *
+ * `null` when neither is available. See the header: guessing writes into a
+ * stranger's tree.
+ */
+export function forgeState(from: string, env: NodeJS.ProcessEnv = process.env): string | null {
+	const named = env.FORGE_STATE?.trim();
+	if (named) return named;
+	const root = findForgeRoot(from);
+	if (!root) return null;
+	return readForgeVar(join(root, MARKER), "FORGE_STATE", env);
+}
+
+/** The generation's code root. Same resolution order as {@link forgeState}. */
+export function forgeCodeRoot(from: string, env: NodeJS.ProcessEnv = process.env): string | null {
+	const named = env.FORGE?.trim();
+	if (named) return named;
+	return findForgeRoot(from);
+}
+
+/**
+ * {@link forgeState}, or a thrown error naming both things the caller could do
+ * about it.
+ *
+ * For the call sites — a deploy, a service install — where `null` has no sensible
+ * handling and the alternative to throwing is a path built out of `undefined`.
+ */
+export function requireForgeState(from: string, env: NodeJS.ProcessEnv = process.env): string {
+	const state = forgeState(from, env);
+	if (state) return state;
+	throw new Error(
+		`No generation state root: $FORGE_STATE is unset and no ${MARKER} was found above ${from}.\n` +
+			`  Source the generation's ${MARKER} first, or run this from inside its checkout.`,
+	);
+}

package/src/smoke.ts

@@ -0,0 +1,226 @@
+/**
+ * The scaffolding a deployed smoke needs — and none of the checks.
+ *
+ * ## 🔴 A smoke that asserts `200` on `/` passes every incident this fleet has had
+ *
+ * Six of them, and all six have the same shape: **the deploy reported success and
+ * the app did not work.**
+ *
+ *   1. `npm publish` printed `+ name@version` and exited 0 without publishing. The
+ *      registry 404d for an hour and the retry 409d against the stage.
+ *   2. A first deploy landed with no body-size declaration. Every upload became a
+ *      413 raised by the layer in front, so the app never saw one and nothing in
+ *      its logs was wrong.
+ *   3. A deploy *succeeded* while every byte of media was unreachable, because the
+ *      failing layer answered before the thing being health-checked ran.
+ *   4. An app was up, green, and serving a catalogue a MONTH out of date.
+ *   5. Two apps went live answering `no built client at …/public` at `/` while the
+ *      edge returned 200 out of its cache of the RETIRED deployment. Gate green,
+ *      deploy green, smoke green, app down; the owner found it, not a check.
+ *   6. A launchd swap "succeeded" onto a process still running the previous
+ *      commit, which serves perfectly and is indistinguishable from a release.
+ *
+ * So none of the checks an app writes on top of this is a liveness check, and this
+ * module holds **no checks at all**. What two apps wrote twice is the harness —
+ * the ledger, the timeout-and-header-carrying fetch, the DNS hint, and the exit
+ * code — and that is exactly what is here.
+ *
+ * ## 🔴 The exit code is a CONTRACT, not a detail
+ *
+ * | code | meaning | what a deploy script does |
+ * |---|---|---|
+ * | `0` | every check passed | keep the release |
+ * | `1` | the APP is wrong | roll back |
+ * | `2` | the EDGE is wrong — DNS, tunnel, hostname, policy | do **not** roll back |
+ *
+ * Two is the load-bearing one and it is why {@link Smoke.edgeFault} exists.
+ * Reverting good application code cannot restore a DNS record, a tunnel route or
+ * an access policy: a rollback there discards work while leaving the real fault
+ * 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.
+ *
+ * ## What this module will never grow
+ *
+ * No route lists, no health-payload shapes, no upload sizes, no titles. Those are
+ * the parts `desk` and `flix` wrote DIFFERENTLY, on purpose, because they are
+ * different apps — and a shared kit that starts absorbing them is how the previous
+ * generation's reached 277 files.
+ *
+ * ```ts
+ * const smoke = createSmoke({ base: process.env.MYAPP_SMOKE_URL ?? "https://…" });
+ * const response = await smoke.get("/healthz");
+ * smoke.record("health", response.status === 200, `GET /healthz → ${response.status}`);
+ * smoke.finish();
+ * ```
+ */
+
+import { spawnSync } from "node:child_process";
+
+export interface Failure {
+	check: string;
+	detail: string;
+}
+
+export interface SmokeOptions {
+	/** The origin every relative path is asked against. A trailing slash is trimmed. */
+	base: string;
+	/** Per-request ceiling. A smoke that hangs is a deploy that hangs. */
+	timeoutMs?: number;
+	/**
+	 * Headers added to {@link Smoke.get} and to nothing else.
+	 *
+	 * A function rather than a value so a credential is read at call time, and so
+	 * an app whose outer gate needs no credential can simply not pass one.
+	 */
+	headers?: () => Record<string, string>;
+	/** Injected for tests. Resolves a hostname against a public resolver. */
+	resolve?: (host: string) => string;
+	log?: (line: string) => void;
+	error?: (line: string) => void;
+}
+
+export interface Smoke {
+	readonly base: string;
+	readonly passed: readonly string[];
+	readonly failures: readonly Failure[];
+	/** True once something could not be reached AT ALL. Drives the exit code. */
+	readonly edgeFault: boolean;
+	/** Ledger one result. Returns `ok`, so it can be the tail of an `if`. */
+	record(check: string, ok: boolean, detail: string): boolean;
+	/** Ask `path` WITH whatever {@link SmokeOptions.headers} returns. */
+	get(path: string, init?: RequestInit): Promise<Response>;
+	/** Ask `path` with NO credentials — the shape every gate check needs. */
+	anonymous(path: string, init?: RequestInit): Promise<Response>;
+	/** Mark the run as an edge fault: reached nothing, so code 2 rather than 1. */
+	markEdgeFault(): void;
+	/** A sentence to append to a fetch failure, or `""`. See {@link createSmoke}. */
+	dnsHint(error: Error): string;
+	/** Print the ledger and return the exit code. Does not exit. */
+	report(): number;
+	/** {@link report}, then `process.exit` with it. */
+	finish(): never;
+}
+
+/**
+ * 🔴 Tell "the hostname does not exist" apart from "this Mac remembers that it
+ * didn't", which are the same error message and completely different problems.
+ *
+ * Measured 2026-09-13, and it cost half an hour of a first deploy: curling a
+ * hostname *before* its DNS record exists puts an NXDOMAIN in mDNSResponder's
+ * negative cache for the zone's SOA minimum — half an hour on the zone this fleet
+ * uses. For all of that time `dig` answers correctly, the record is live, the app
+ * is serving, and every program on the Mac that uses the system resolver says the
+ * host does not exist. Nothing about that reads as a caching problem while it is
+ * happening, which is exactly why the question is asked in code instead of left in
+ * a document somebody has to remember to go and read.
+ */
+function publicResolve(host: string): string {
+	const dig = spawnSync("dig", ["+short", host, "@1.1.1.1"], { encoding: "utf8" });
+	return (dig.stdout ?? "").trim();
+}
+
+const LOOKS_LIKE_DNS = /ENOTFOUND|getaddrinfo|Could not resolve|dns/i;
+
+export function createSmoke(options: SmokeOptions): Smoke {
+	const base = options.base.replace(/\/+$/, "");
+	const timeoutMs = options.timeoutMs ?? 20_000;
+	const headers = options.headers ?? (() => ({}));
+	const resolve = options.resolve ?? publicResolve;
+	const log = options.log ?? ((line: string) => console.log(line));
+	const error = options.error ?? ((line: string) => console.error(line));
+
+	const passed: string[] = [];
+	const failures: Failure[] = [];
+	let edgeFault = false;
+
+	const smoke: Smoke = {
+		base,
+		get passed() {
+			return passed;
+		},
+		get failures() {
+			return failures;
+		},
+		get edgeFault() {
+			return edgeFault;
+		},
+
+		record(check, ok, detail) {
+			if (ok) passed.push(`${check} — ${detail}`);
+			else failures.push({ check, detail });
+			return ok;
+		},
+
+		async get(path, init = {}) {
+			return await fetch(`${base}${path}`, {
+				...init,
+				// 🔴 Never `follow`. A redirect to a sign-in page is the single most
+				// common way a gate check turns into a green 200 on somebody else's
+				// HTML, and following it destroys the evidence.
+				redirect: "manual",
+				signal: AbortSignal.timeout(timeoutMs),
+				headers: { ...headers(), ...(init.headers ?? {}) },
+			});
+		},
+
+		async anonymous(path, init = {}) {
+			return await fetch(`${base}${path}`, { ...init, redirect: "manual", signal: AbortSignal.timeout(timeoutMs) });
+		},
+
+		markEdgeFault() {
+			edgeFault = true;
+		},
+
+		dnsHint(failed: Error) {
+			if (!LOOKS_LIKE_DNS.test(failed.message)) return "";
+			const host = new URL(base).hostname;
+			const resolved = resolve(host);
+			if (!resolved) return `\n    ${host} does not resolve publicly either — the DNS record is genuinely missing.`;
+			return [
+				`\n    🔴 But ${host} DOES resolve publicly (${resolved.split("\n").join(", ")}).`,
+				"    This is the macOS negative DNS cache, not a broken deploy — something asked for the",
+				"    name before its record existed, and mDNSResponder holds that for the zone's SOA",
+				"    minimum. Clear it and re-run:",
+				"      sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder",
+			].join("\n");
+		},
+
+		report() {
+			for (const line of passed) log(`  ✓ ${line}`);
+			for (const failure of failures) error(`  ✗ ${failure.check} — ${failure.detail}`);
+			const total = passed.length + failures.length;
+			if (failures.length === 0) {
+				log(`\n✓ deploy smoke passed — ${total} checks against ${base}`);
+				return 0;
+			}
+			error(`\n✗ deploy smoke FAILED — ${failures.length} of ${total} checks against ${base}`);
+			if (edgeFault) error("  (exit 2 — an EDGE fault. Rolling the app back would not change it.)");
+			return edgeFault ? 2 : 1;
+		},
+
+		finish() {
+			process.exit(smoke.report());
+		},
+	};
+
+	return smoke;
+}
+
+/**
+ * Wrap a check so a fetch that throws becomes a recorded edge fault rather than an
+ * unhandled rejection.
+ *
+ * 🔴 The failure this closes: an uncaught throw exits non-zero with a stack trace
+ * and NO ledger, so a deploy script reads `1` — "the app is wrong, roll back" —
+ * for a hostname that was never reachable. That is the exact case code 2 exists
+ * for, arriving as a 1.
+ */
+export async function guarded(smoke: Smoke, check: string, body: () => Promise<void>): Promise<void> {
+	try {
+		await body();
+	} catch (thrown) {
+		const failed = thrown as Error;
+		smoke.markEdgeFault();
+		smoke.record(check, false, `could not complete against ${smoke.base}: ${failed.message}${smoke.dnsHint(failed)}`);
+	}
+}