cursedops 0.5.3 → 0.6.0

package/README.md

@@ -21,6 +21,8 @@ bun add cursedops
 | `cursedops/api-floor` | the rule that an unmatched `/api/...` is a phrase and never the app shell — the namespace predicates, the trailing-slash normaliser and the default 404 body. No `node:` import, so it mounts inside a Worker |
 | `cursedops/build-info` | which commit a checkout-served process is running and whether its tree was dirty — read once at load, and a `null` retried in the background rather than cached for the life of the process. `node:child_process`, so never in a Worker |
 | `cursedops/bound-lists` | the static check that no SQL builds an `IN (…)` list one `?` per value — the shape D1 500s on past 100 ids. Test-time only; the recorded third exception, see below |
+| `cursedops/staged-client` | the IMMUTABLE client a checkout-served app serves — a build staged into `<APP_DATA_DIR>/client/<commit>/` behind `CURRENT`, so another agent's `vite build` in the checkout never changes live bytes — and its `forge-client stamp` / `forge-client stage` bin (0.6.0, lifted from family, flix, roms, station) |
+| `cursedops/deploy-tree` | the two refusals a checkout-served deploy needs — never deploy a dirty tree, never `git revert` in one (`readTreeStatus`, `refuseToDeploy`, `refuseToRevert`; 0.6.0, lifted from nine apps) |
 | `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.5.3",
+	"version": "0.6.0",
 	"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), 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": {
@@ -97,11 +97,24 @@
 			"source": "./src/d1Import.ts",
 			"import": "./src/d1Import.ts"
 		},
-		"./package.json": "./package.json"
+		"./package.json": "./package.json",
+		"./staged-client": {
+			"types": "./src/stagedClient.ts",
+			"bun": "./src/stagedClient.ts",
+			"source": "./src/stagedClient.ts",
+			"import": "./src/stagedClient.ts"
+		},
+		"./deploy-tree": {
+			"types": "./src/deployTree.ts",
+			"bun": "./src/deployTree.ts",
+			"source": "./src/deployTree.ts",
+			"import": "./src/deployTree.ts"
+		}
 	},
 	"bin": {
 		"public-surface": "./src/publicSurface.ts",
-		"forge-paths": "./src/paths.ts"
+		"forge-paths": "./src/paths.ts",
+		"forge-client": "./src/stagedClient.ts"
 	},
 	"files": [
 		"src",

package/src/deployTree.ts

@@ -0,0 +1,181 @@
+/**
+ * `cursedops/deploy-tree` — is this checkout in a state where a deploy's rollback would be a rollback?
+ *
+ * Lifted 2026-09-23 (0.6.0) from the nine apps that each carried `scripts/deployTree.ts` —
+ * collections, desk, family, flix, music, patterns, roms, station and vault; identical in logic,
+ * differing only in comments and indentation. vault's `deployTree.test.ts` came with it.
+ *
+ * ```ts
+ * import { readTreeStatus, refuseToDeploy, refuseToRevert } from "cursedops/deploy-tree";
+ * ```
+ *
+ * ## The incident this exists because of — 2026-09-18, six of eight apps
+ *
+ * A fleet deploy ran `bun run deploy` in eight app checkouts. Six failed, all on the same
+ * smoke check and none on their own code:
+ *
+ * ```
+ * ✗ clean-tree — 🔴 the served checkout has uncommitted changes — `git revert` would not undo this deploy
+ * ```
+ *
+ * Every other check passed in every app; the apps installed and served correctly. The trees
+ * were dirty because somebody else's in-flight sweep was sitting in them, uncommitted.
+ *
+ * 🔴 **Then the failure did something far worse than fail.** A non-edge smoke failure rolls
+ * back with `git revert`, and the rollback ran in that same dirty tree. Both outcomes were
+ * bad, and both happened inside four minutes:
+ *
+ *  · **It succeeded** in `family`, `flix`, `music` and `roms` — landing a commit that reverted
+ *    work a stranger had written and had never been told was touched. (`706d1106`, `50aa95ed`,
+ *    `c6ef8cb6`, `88fececc`; each reverted-back the same session.)
+ *  · **It failed** in `station` — `error: Your local changes to src/api/console.ts would be
+ *    overwritten by merge … fatal: revert failed`, then `🔴 THE ROLLBACK DID NOT LAND.`, which
+ *    leaves a live hostname on a deploy the script had already decided to undo.
+ *
+ * ## The shape of the bug, which is the reason this is a module and not an `if`
+ *
+ * 🔴 **The rollback was unsafe in exactly the condition that triggered it.** `clean-tree` fires
+ * only when the tree is dirty; `git revert` is only safe when it is not. The two met on every
+ * run. Nothing else in this generation can commit on an agent's behalf, and this did it to a
+ * stranger's work.
+ *
+ * So the fix is two refusals, not one, and they are here rather than inline in `deploy.ts`
+ * because a refusal nobody can test is a comment:
+ *
+ *  1. {@link refuseToDeploy} — run BEFORE the build, so the deploy never starts. A dirty tree
+ *     means the thing that would deploy is not the thing `HEAD` names, so there is no commit a
+ *     revert could undo. A pre-flight refusal costs a second; not having one cost four commits.
+ *  2. {@link refuseToRevert} — run immediately before `git revert`, because the pre-flight
+ *     passing is not a promise about ten minutes later. A build, a stage run, or another agent
+ *     working in this same checkout can all dirty the tree between the two, and one agent per
+ *     checkout is a convention, not a lock.
+ *
+ * Neither takes an override flag, deliberately. `deploy.ts`'s own `--allow-empty` note records
+ * what an escape hatch on a gate that fires every day turns into: the flag becomes the habit,
+ * and the habit is what lets the real case through.
+ */
+
+/** One uncommitted path, with the two-letter porcelain code git gave it. */
+export type DirtyPath = {
+	/** The index/worktree code, e.g. `" M"`, `"D "`, `"??"`. */
+	code: string;
+	path: string;
+};
+
+export type TreeStatus = {
+	clean: boolean;
+	paths: DirtyPath[];
+	/**
+	 * The subset that are DELETIONS. Called out separately because a rollback landing one is
+	 * the worst case of all: `apps/music` and `apps/station` both sat with
+	 * `D scripts/guardrails.ts` uncommitted — a deleted guardrails script, one blanket commit
+	 * away from being deleted for real, by a script whose whole job was to be safe.
+	 */
+	deletions: DirtyPath[];
+};
+
+/**
+ * One porcelain v1 line: `XY<space><path>`, `X` the index state and `Y` the worktree state.
+ *
+ * 🔴 The second branch is not hypothetical — it is the bug this module shipped with for about
+ * ten minutes. `deploy.ts`'s `shell()` helper `.trim()`s the output it returns, which strips
+ * the LEADING SPACE off the first line of ` M scripts/deploy.ts` and nothing else. The
+ * fixed-offset parse then read one character late and reported `M  cripts/deploy.ts` — a path
+ * that does not exist, in a refusal whose whole job is to name paths a person can go and look
+ * at. `deploy.ts` now reads the status untrimmed; this branch means a caller that forgets
+ * still gets the right answer rather than a plausible wrong one.
+ */
+function parseLine(line: string): DirtyPath {
+	const [code, rest] = line[2] === " " ? [line.slice(0, 2), line.slice(3)] : [` ${line.slice(0, 1)}`, line.slice(2)];
+	const path = rest.trim();
+	// A rename is `R  old -> new`; keep the destination, which is the path that exists on disk.
+	const arrow = path.indexOf(" -> ");
+	return { code, path: arrow >= 0 ? path.slice(arrow + 4).trim() : path };
+}
+
+/** Parse `git status --porcelain` output. */
+export function readTreeStatus(porcelain: string): TreeStatus {
+	const paths: DirtyPath[] = [];
+	for (const line of porcelain.split("\n")) {
+		if (line.trim() === "") continue;
+		paths.push(parseLine(line));
+	}
+	return {
+		clean: paths.length === 0,
+		paths,
+		deletions: paths.filter((p) => p.code.includes("D")),
+	};
+}
+
+/** `git status --porcelain`'s own rendering of a path, for an error message. */
+function listed(paths: DirtyPath[], limit = 8): string {
+	const shown = paths.slice(0, limit).map((p) => `    ${p.code} ${p.path}`);
+	if (paths.length > limit) shown.push(`    … and ${paths.length - limit} more`);
+	return shown.join("\n");
+}
+
+/**
+ * The pre-flight. Returns the refusal to print, or `null` if the deploy may proceed.
+ *
+ * 🔴 This runs before the build — before anything is built, staged, installed or swapped — so
+ * that the deploy simply does not start. The alternative, which is what happened, is that the
+ * deploy runs all the way to the smoke, the smoke's `clean-tree` check fails on this exact
+ * condition, and the rollback then commits against a stranger.
+ */
+export function refuseToDeploy(status: TreeStatus): string | null {
+	if (status.clean) return null;
+	const lines = [
+		`\n✗ clean-tree — this checkout has ${status.paths.length} uncommitted path(s), so it must not deploy.`,
+		"",
+		"  What deploys here is the WORKING TREE — there is no artifact to swap back. With",
+		"  uncommitted changes in it, the code that would go live is not the code HEAD names,",
+		"  so there is no commit a `git revert` could undo. The rollback this script would reach",
+		"  for is not a rollback, and on 2026-09-18 it committed reverts of four other agents'",
+		"  work rather than admit that. Nothing has been built, installed or swapped.",
+		"",
+		listed(status.paths),
+	];
+	if (status.deletions.length > 0) {
+		lines.push(
+			"",
+			`  🔴 ${status.deletions.length} of those is a DELETION. If this is not your work, do not commit it —`,
+			"     two app checkouts on this fleet sat with a guardrails script deleted and uncommitted,",
+			"     one blanket commit away from losing the file. This module's header names them.",
+		);
+	}
+	lines.push(
+		"",
+		"  Commit them, or find whoever owns them and let them land — then deploy. `git status`",
+		"  and `git diff` say whose they are; the runner commits by name, so a tree it left dirty",
+		"  is somebody's live work, not litter.",
+	);
+	return lines.join("\n");
+}
+
+/**
+ * The rollback guard. Returns the refusal to print, or `null` if `git revert` is safe to run.
+ *
+ * 🔴 Never `git revert` in a dirty tree AT ALL — not only when `clean-tree` was the failing
+ * check. `station` proves the other half: its revert hit `error: Your local changes to
+ * src/api/console.ts would be overwritten by merge`, aborted, and left the live host on a
+ * deploy the script had decided to undo. A revert that half-lands is worse than one that never
+ * started, because the second one still has an honest error message.
+ */
+export function refuseToRevert(status: TreeStatus, sha: string): string | null {
+	if (status.clean) return null;
+	return [
+		`\n🔴 NOT ROLLING BACK. The deploy failed, and ${sha.slice(0, 8)} is still what this checkout serves.`,
+		"",
+		`  This tree has ${status.paths.length} uncommitted path(s), and \`git revert\` in a dirty tree either`,
+		"  commits somebody else's work as reverted or aborts halfway and leaves the host on the",
+		"  code it was told to undo. Both happened on 2026-09-18. Neither is a rollback, so this",
+		"  script will not do it — a deploy that needs a person is a better outcome than a commit",
+		"  nobody asked for.",
+		"",
+		listed(status.paths),
+		"",
+		"  A person: land or set aside the paths above, then `git revert --no-edit " +
+			`${sha.slice(0, 8)}\`, then`,
+		"  `bun run build && bun run deploy` — the app's own deploy doc, § 'by hand', is the long form.",
+	].join("\n");
+}

package/src/roots.ts

@@ -163,15 +163,29 @@ export function readForgeVar(marker: string, name: string, env: NodeJS.ProcessEn
 	} catch {
 		return null;
 	}
-	const known: Record<string, string> = { HOME: env.HOME?.trim() ?? "" };
+	// 🔴 `null` is UNRESOLVABLE, and it propagates: a value that references an unset or empty
+	// variable — `$HOME` from an env that has none — is not a path with a hole in it. Until 0.5.4
+	// an empty HOME expanded `"$HOME/.code/$FORGE_NAME"` to `/.code/cursedforge`, a root-relative
+	// state root that exists on no machine, and `assertTestSafeDbPath(…, { env: {} })` compared
+	// against it — the guard against a test opening the owner's database was silently OFF (task 2130).
+	const home = env.HOME?.trim();
+	const known: Record<string, string | null> = { HOME: home ? home : null };
 	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;
+		let unresolved = false;
+		const expanded = unquoted.replace(/\$\{?([A-Z_][A-Z0-9_]*)\}?/g, (_whole, ref: string) => {
+			const value = known[ref];
+			if (value === null || value === undefined || value === "") {
+				unresolved = true;
+				return "";
+			}
+			return value;
+		});
+		known[key] = unresolved ? null : expanded;
+		if (key === name) return unresolved ? null : expanded || null;
 	}
 	return null;
 }

package/src/stagedClient.ts

@@ -0,0 +1,273 @@
+#!/usr/bin/env bun
+/**
+ * `cursedops/staged-client` — the IMMUTABLE client a checkout-served app serves: a build copied
+ * into `<APP_DATA_DIR>/client/<commit>/`, named by `CURRENT`, so another agent's `vite build` in
+ * the shared checkout can never change the bytes production is serving.
+ *
+ * ── Why (tasks 163-314, 2026-09-17 → 23) ────────────────────────────────────
+ * The launchd agent runs `server.ts` out of `$FORGE/apps/<app>`, and until this module it also
+ * served that checkout's `dist/` — so any `bun run verify` or `bun run build` by anybody in the
+ * checkout rewrote the live client under a server built from a different commit. Measured on
+ * station first (`/healthz` said one commit, `dist/index.html` another, a page asking for routes
+ * its server had never heard of); family, flix and roms had the same shape and took the same
+ * module. It lived as a byte-identical `src/server/clientDir.ts` in those four apps, with
+ * `scripts/stamp-build.ts` (four) and `scripts/stage-client.ts` (family, roms); lifted here 0.6.0.
+ *
+ * ```ts
+ * import { resolveClientDir, stageClient } from "cursedops/staged-client";
+ * const client = resolveClientDir({ appDir, dataDir: config.dataDir }); // serve client.dir
+ * ```
+ *
+ * ```jsonc
+ * "build": "vite build && forge-client stamp"        // writes dist/build.json — the commit
+ * // deploy: stageClient({ from: dist, dataDir, commit }), or `forge-client stage`
+ * ```
+ *
+ * `stageClient` copies FULLY, verifies the shell arrived, and only then moves `CURRENT`, so a
+ * failed stage leaves the previous release serving. The directory is keyed on the commit (a
+ * dirty build gets `-dirty`), so a rollback is a directory that is still there, and
+ * {@link pruneStagedClients} keeps the newest few plus whatever `CURRENT` names. Nothing staged
+ * falls back to `<appDir>/dist` and SAYS so (`staged: false`), because dev, preview and e2e serve
+ * the bytes vite just wrote, and a production instance falling back is worth a log line.
+ *
+ * Standalone by construction: node builtins only, and `cursedops/roots` by its package name for
+ * the one CLI default that needs the state root (a shipped file imports no sibling by path).
+ */
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+/** The directory under the app's state root that holds every staged build. */
+export const CLIENT_ROOT = "client";
+
+/** The file inside {@link CLIENT_ROOT} naming the build that should be served. */
+export const CURRENT_FILE = "CURRENT";
+
+/** What `bun run build` stamps beside the shell so a build can name its own commit. */
+const BUILD_STAMP = "build.json";
+
+/** How many staged builds are kept. Enough for a rollback, not a disk leak. */
+const KEEP_BUILDS = 3;
+
+export interface BuildStamp {
+	/** The full 40-char commit the client was built from, or `null` if unreadable. */
+	commit: string | null;
+	/** Whether the tree was dirty when it was built. */
+	dirty: boolean | null;
+	/** When it was built — ISO 8601. */
+	builtAt: string;
+}
+
+/** A directory is a usable client only if it actually holds the shell. */
+export const holdsShell = (dir: string): boolean => existsSync(join(dir, "index.html"));
+
+/** The stamp a build wrote, or `null`. Never throws: an unreadable stamp is a `null` commit. */
+export function readBuildStamp(dir: string): BuildStamp | null {
+	try {
+		const parsed = JSON.parse(readFileSync(join(dir, BUILD_STAMP), "utf8")) as Partial<BuildStamp>;
+		if (typeof parsed !== "object" || parsed === null) return null;
+		return {
+			commit: typeof parsed.commit === "string" && /^[0-9a-f]{40}$/.test(parsed.commit) ? parsed.commit : null,
+			dirty: typeof parsed.dirty === "boolean" ? parsed.dirty : null,
+			builtAt: typeof parsed.builtAt === "string" ? parsed.builtAt : "",
+		};
+	} catch {
+		return null;
+	}
+}
+
+/** Write the stamp. `forge-client stamp` calls it immediately after `vite build`. */
+export function writeBuildStamp(dir: string, stamp: BuildStamp): void {
+	writeFileSync(join(dir, BUILD_STAMP), `${JSON.stringify(stamp, null, "\t")}\n`);
+}
+
+/**
+ * The staged build this app should serve, or `null` when nothing is staged.
+ *
+ * 🔴 A `CURRENT` naming a directory that is missing or shell-less answers `null`
+ * rather than throwing. The fallback to `dist/` keeps the app UP, and the smoke's
+ * `client-commit` row is what makes the miss loud — an app that refuses to boot
+ * because a pointer file is stale is a worse outcome than one serving the previous
+ * client and saying so.
+ */
+export function stagedClientDir(dataDir: string): string | null {
+	const root = join(dataDir, CLIENT_ROOT);
+	let named: string;
+	try {
+		named = readFileSync(join(root, CURRENT_FILE), "utf8").trim();
+	} catch {
+		return null;
+	}
+	// One path segment, never joined from anything a request can influence — but the
+	// file is on disk and a hand edit is exactly how this would become a traversal.
+	if (!/^[A-Za-z0-9._-]+$/.test(named) || named === "." || named === "..") return null;
+	const dir = join(root, named);
+	return holdsShell(dir) ? dir : null;
+}
+
+export interface ResolvedClient {
+	/** The directory to serve. */
+	dir: string;
+	/** True when it came from the state root, false when it is the checkout's `dist/`. */
+	staged: boolean;
+	/** The commit the served client was BUILT from, full sha, or `null`. */
+	commit: string | null;
+}
+
+/**
+ * Where this process's client lives. `dataDir` is `null` in a context with no state
+ * root at all, which resolves to the checkout exactly as before.
+ */
+export function resolveClientDir(options: { appDir: string; dataDir: string | null }): ResolvedClient {
+	const staged = options.dataDir ? stagedClientDir(options.dataDir) : null;
+	const dir = staged ?? join(options.appDir, "dist");
+	return { dir, staged: staged !== null, commit: readBuildStamp(dir)?.commit ?? null };
+}
+
+/**
+ * Copy a build into the state root and point `CURRENT` at it. Returns the directory.
+ *
+ * 🔴 The order is the whole safety property: copy fully, verify the shell arrived,
+ * and only THEN write `CURRENT`. A pointer is never updated to a half-copied build,
+ * so the worst a failed stage can do is leave the previous release serving.
+ *
+ * 🔴 The directory is keyed on the commit, so re-staging the same commit is
+ * idempotent and a rollback is a directory that is still there. `dirty` builds get a
+ * suffix, because two dirty builds of the same commit are genuinely different bytes
+ * and must not collide.
+ */
+export function stageClient(options: {
+	from: string;
+	dataDir: string;
+	commit: string;
+	dirty?: boolean;
+	keep?: number;
+}): string {
+	if (!holdsShell(options.from)) {
+		throw new Error(`${options.from} holds no index.html — there is no built client to stage`);
+	}
+	const root = join(options.dataDir, CLIENT_ROOT);
+	mkdirSync(root, { recursive: true });
+	const name = options.dirty ? `${options.commit.slice(0, 12)}-dirty` : options.commit.slice(0, 12);
+	const dir = join(root, name);
+	rmSync(dir, { recursive: true, force: true });
+	cpSync(options.from, dir, { recursive: true });
+	if (!holdsShell(dir)) throw new Error(`staging ${options.from} into ${dir} did not produce an index.html`);
+	writeFileSync(join(root, CURRENT_FILE), `${name}\n`);
+	pruneStagedClients(options.dataDir, options.keep ?? KEEP_BUILDS);
+	return dir;
+}
+
+/** Keep the newest `keep` staged builds plus whatever `CURRENT` names. */
+export function pruneStagedClients(dataDir: string, keep: number = KEEP_BUILDS): string[] {
+	const root = join(dataDir, CLIENT_ROOT);
+	if (!existsSync(root)) return [];
+	let current = "";
+	try {
+		current = readFileSync(join(root, CURRENT_FILE), "utf8").trim();
+	} catch {
+		// No pointer — every directory here is a candidate but the newest still stay.
+	}
+	const dirs = readdirSync(root, { withFileTypes: true })
+		.filter((entry) => entry.isDirectory())
+		.map((entry) => ({ name: entry.name, at: statSync(join(root, entry.name)).mtimeMs }))
+		.sort((a, b) => b.at - a.at);
+	const removed: string[] = [];
+	for (const [index, entry] of dirs.entries()) {
+		if (index < keep || entry.name === current) continue;
+		rmSync(join(root, entry.name), { recursive: true, force: true });
+		removed.push(entry.name);
+	}
+	return removed;
+}
+
+
+// ── the `forge-client` bin ────────────────────────────────────────────────────────────────
+
+/** The commit and dirtiness of the checkout at `root`, read from git; `null`s when unreadable. */
+export function checkoutState(root: string): { commit: string | null; dirty: boolean | null } {
+	const git = (args: string[]): string | null => {
+		try {
+			const result = spawnSync("git", args, { cwd: root, encoding: "utf8", timeout: 5_000 });
+			return result.status === 0 ? (result.stdout ?? "").trim() : null;
+		} catch {
+			return null;
+		}
+	};
+	const sha = git(["rev-parse", "HEAD"]);
+	const status = git(["status", "--porcelain"]);
+	return { commit: sha && /^[0-9a-f]{40}$/.test(sha) ? sha : null, dirty: status === null ? null : status.length > 0 };
+}
+
+/** The nearest directory at or above `from` holding a `package.json` — the app. */
+function packageRoot(from: string): string | null {
+	let dir = resolve(from);
+	for (let hops = 0; hops < 16; hops++) {
+		if (existsSync(join(dir, "package.json"))) return dir;
+		const up = dirname(dir);
+		if (up === dir) return null;
+		dir = up;
+	}
+	return null;
+}
+
+/**
+ * `forge-client stamp [dir]` writes `build.json` into a build (default `<app>/dist`);
+ * `forge-client stage [--data-dir <dir>]` stages `<app>/dist` into the app's data directory —
+ * `--data-dir`, else `APP_DATA_DIR`, else `<FORGE_STATE>/apps/<package name>` — and refuses a
+ * build whose stamp is not this checkout's HEAD. Returns the exit code.
+ */
+export async function runClientCli(argv: readonly string[], cwd: string = process.cwd(), env: NodeJS.ProcessEnv = process.env): Promise<number> {
+	const [command, ...rest] = argv;
+	const app = packageRoot(cwd);
+	if (!app) {
+		console.error(`✗ no package.json above ${cwd} — run this from an app.`);
+		return 2;
+	}
+	if (command === "stamp") {
+		const dir = rest[0] ? resolve(cwd, rest[0]) : join(app, "dist");
+		if (!holdsShell(dir)) {
+			console.error(`✗ ${dir} holds no index.html — nothing to stamp. Did the build run?`);
+			return 1;
+		}
+		const { commit, dirty } = checkoutState(app);
+		writeBuildStamp(dir, { commit, dirty, builtAt: new Date().toISOString() });
+		console.log(`  stamped ${dir}/build.json — ${commit?.slice(0, 8) ?? "no commit"}${dirty ? " (dirty)" : ""}`);
+		return 0;
+	}
+	if (command === "stage") {
+		const at = rest.indexOf("--data-dir");
+		let dataDir = at >= 0 ? rest[at + 1] : env.APP_DATA_DIR?.trim() || undefined;
+		if (!dataDir) {
+			const { forgeState } = await import("cursedops/roots");
+			const state = forgeState(app, env);
+			const name = (JSON.parse(readFileSync(join(app, "package.json"), "utf8")) as { name?: string }).name;
+			if (!state || !name) {
+				console.error("✗ no --data-dir, no APP_DATA_DIR, and no state root (or no package name) to derive one from.");
+				return 2;
+			}
+			dataDir = join(state, "apps", name);
+		}
+		const dist = join(app, "dist");
+		const stamp = readBuildStamp(dist);
+		const head = checkoutState(app).commit;
+		if (!stamp?.commit) {
+			console.error(`✗ ${dist} carries no build.json commit — build first (\`forge-client stamp\` runs after vite).`);
+			return 1;
+		}
+		if (stamp.commit !== head) {
+			console.error(`✗ ${dist} was built from ${stamp.commit.slice(0, 8)}, but HEAD is ${head?.slice(0, 8) ?? "unreadable"}.`);
+			console.error("  Staging it would serve a client that is not this commit. Build again first.");
+			return 1;
+		}
+		const where = stageClient({ from: dist, dataDir, commit: stamp.commit, dirty: stamp.dirty !== false });
+		console.log(`✓ staged ${where}${stamp.dirty !== false ? " (from a DIRTY tree)" : ""}`);
+		return 0;
+	}
+	console.error("usage: forge-client stamp [dir] | forge-client stage [--data-dir <dir>]");
+	return 2;
+}
+
+if (import.meta.main) {
+	process.exit(await runClientCli(process.argv.slice(2)));
+}