cursedops 0.4.0 → 0.5.0

package/src/paths.ts

@@ -0,0 +1,173 @@
+#!/usr/bin/env bun
+/**
+ * `cursedops/paths` — the generation's whole-tree laws, run over ONE repo's tree, found the same
+ * way from a primary checkout and from a git worktree.
+ *
+ * ```jsonc
+ * // package.json — the whole wiring; no scripts/paths.ts at all
+ * "paths": "forge-paths"                                  // check-paths + check-doc-citations
+ * "paths": "forge-paths --also check-gate-graph.ts"       // cursedbelt's extra law, as an OPTION
+ * ```
+ *
+ * ```ts
+ * // or, for a repo that wants a file: scripts/paths.ts
+ * import { runGenerationLaws } from "cursedops/paths";
+ * process.exit(runGenerationLaws(import.meta.dir, { also: ["check-no-clock.ts"] }));
+ * ```
+ *
+ * ## Why this is a library entry and not a file every repo copies
+ *
+ * Measured 2026-09-22 (task 2089): `scripts/paths.ts` was in EIGHTEEN packages — every app,
+ * `autopilot`, and every library — sixteen of them byte-identical, and three had already forked:
+ * `libs/cursedbelt` added `check-gate-graph.ts`, `apps/station` added `check-no-clock.ts`, and
+ * `autopilot` split the walk into a `scripts/generation.ts` of its own. `check-copies` prices
+ * exported definitions, and a script that exports nothing registered as ZERO duplication — the
+ * same blindness that let three `publicSurface.ts` bodies fork unremarked. The generation's own
+ * `check-paths.ts` named one of the copies as the template to copy, so the count could only grow.
+ *
+ * ## 🔴 Why a wrapper at all, and not `bun ../../tools/check-paths.ts .`
+ *
+ * That spelling assumes the checkout sits at a fixed depth under the generation root, and a
+ * WORKTREE never does: the working agreement puts worktrees outside every generation by
+ * construction. Measured 2026-09-17 in a worktree — `error: Module not found
+ * "../../tools/check-paths.ts"`, and the gate stopped on its FIRST step in seventeen packages.
+ * The failure mode is not the error but the workaround: an agent that cannot run its gate moves
+ * back into a checkout another agent holds, or lands without a green gate.
+ *
+ * So the generation is found by walking up for `forge.env` — the marker `check-paths` and the
+ * runner use, so the three cannot disagree — and, in a worktree, by following
+ * `git rev-parse --git-common-dir` back to the primary checkout. The walk is inlined here rather
+ * than imported from `cursedops/roots`: a shipped file imports no sibling (`publishShape.test.ts`).
+ *
+ * 🔴 **No generation, no pass.** A lone clone has no generation above it and is not a worktree of
+ * one, and answering "fine" because the laws could not be located is how a rule stops being
+ * enforced without anybody deciding to stop enforcing it. Every failure to locate is exit 1 with
+ * a sentence saying which walk came back empty — the same posture the eighteen copies had.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+/** The laws every repo runs over itself, in the order they should fail. */
+export const DEFAULT_LAWS: readonly string[] = ["check-paths.ts", "check-doc-citations.ts"];
+
+const MAX_HOPS = 16;
+
+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;
+}
+
+function viaWorktree(from: string): string | null {
+	try {
+		const git = spawnSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
+			cwd: from,
+			encoding: "utf8",
+			timeout: 5_000,
+		});
+		if (git.status !== 0) return null;
+		const common = (git.stdout ?? "").trim();
+		if (!common.startsWith("/")) return null;
+		return walkUp(dirname(common), "forge.env");
+	} catch {
+		return null;
+	}
+}
+
+/** The checkout `from` is in, and the generation its laws live in — either may be `null`. */
+export function locateLaws(from: string): { repo: string | null; generation: string | null } {
+	return { repo: walkUp(from, "package.json"), generation: walkUp(from, "forge.env") ?? viaWorktree(from) };
+}
+
+export interface LawsOptions {
+	/** Laws on top of {@link DEFAULT_LAWS} — a file name under the generation's `tools/`. */
+	also?: readonly string[];
+	/** Replace the list entirely. Rarely right: a repo that drops a law has stopped checking it. */
+	laws?: readonly string[];
+	/** Passed through to every law, e.g. `--prune`. */
+	argv?: readonly string[];
+	/** Injected for tests. Runs one law and returns its exit code. */
+	run?: (runtime: string, args: readonly string[]) => number;
+	error?: (line: string) => void;
+}
+
+/** A law is a file NAME under `tools/`, never a path — a path is a second place that knows one. */
+function checkedLaw(name: string): string {
+	if (!/^[A-Za-z0-9._-]+\.(?:ts|js|mjs)$/.test(name)) throw new Error(`not a law's file name: ${JSON.stringify(name)} — e.g. "check-gate-graph.ts"`);
+	return name;
+}
+
+/** The runtime to hand each law: this bun when running under bun, else `bun` from PATH. */
+function runtime(): string {
+	return process.versions.bun ? process.execPath : "bun";
+}
+
+/**
+ * Run every law over the checkout `from` is in. Returns the first non-zero exit code, or 0.
+ *
+ * Laws run in order and stop at the first red, exactly as the copies did — a later law's output
+ * under an earlier red is noise the reader has to scroll past.
+ */
+export function runGenerationLaws(from: string, options: LawsOptions = {}): number {
+	const error = options.error ?? ((line: string) => console.error(line));
+	const run =
+		options.run ?? ((bin: string, args: readonly string[]) => spawnSync(bin, [...args], { stdio: "inherit" }).status ?? 1);
+	let laws: string[];
+	try {
+		laws = [...new Set([...(options.laws ?? DEFAULT_LAWS), ...(options.also ?? [])].map(checkedLaw))];
+	} catch (thrown) {
+		error(`✗ ${(thrown as Error).message}`);
+		return 1;
+	}
+	const { repo, generation } = locateLaws(from);
+	if (!repo) {
+		error(`✗ no package.json above ${from}, so there is no repo to check.`);
+		return 1;
+	}
+	if (!generation) {
+		error("✗ this checkout is not inside a generation and is not a worktree of one, so");
+		error(`  tools/{${laws.join(",")}} cannot be located. Run it from a checkout under a`);
+		error("  generation, or from a worktree cut from one — a skipped check is not a passed one.");
+		return 1;
+	}
+	for (const name of laws) {
+		const tool = join(generation, "tools", name);
+		if (!existsSync(tool)) {
+			error(`✗ ${tool} does not exist. The generation at ${generation} has no ${name},`);
+			error("  so this repo cannot prove it obeys that law. That is a failure, not a skip.");
+			return 1;
+		}
+		const code = run(runtime(), [tool, repo, ...(options.argv ?? [])]);
+		if (code !== 0) return code;
+	}
+	return 0;
+}
+
+/**
+ * The bin's arguments: `--also <law>` / `--also=<law>` (repeatable) are this wrapper's; every
+ * other argument goes through to the laws untouched, so `bun run paths --prune` still prunes.
+ */
+export function parseLawsArgv(argv: readonly string[]): { also: string[]; argv: string[] } {
+	const also: string[] = [];
+	const rest: string[] = [];
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i] as string;
+		if (arg === "--also") {
+			const next = argv[i + 1];
+			if (next !== undefined) also.push(next);
+			i++;
+		} else if (arg.startsWith("--also=")) also.push(arg.slice("--also=".length));
+		else rest.push(arg);
+	}
+	return { also, argv: rest };
+}
+
+if (import.meta.main) {
+	process.exit(runGenerationLaws(process.cwd(), parseLawsArgv(process.argv.slice(2))));
+}

package/src/roots.ts

@@ -218,3 +218,129 @@ export function requireForgeState(from: string, env: NodeJS.ProcessEnv = process
 			`  Source the generation's ${MARKER} first, or run this from inside its checkout.`,
 	);
 }
+
+// ── A printed command that RUNS when it is pasted ─────────────────────────────────────────
+
+/**
+ * Where a repo is, as a person's shell should reach it: the directory, and the `forge.env` that
+ * makes `$FORGE` real in the reader's shell. `forgeEnv` is non-null **exactly when** `dir` is the
+ * repo's home inside a located generation, so the two can never describe different places.
+ */
+export interface RepoLocation {
+	readonly dir: string;
+	readonly forgeEnv: string | null;
+}
+
+/**
+ * A repo's place inside a generation — `apps/auth`, `libs/cwip`, `autopilot` — checked, never
+ * trusted: relative, no `..`, no shell metacharacter.
+ *
+ * 🔴 The segment is always the CALLER's. This library is published and may not know a repo's
+ * name any more than a generation's (the header's third 🔴), and a segment that could carry
+ * `"` or `$` would be interpolated into a line a person pastes into a shell.
+ */
+function checkedSegment(segment: string): string {
+	const clean = segment.trim().replace(/^\.\/+/, "").replace(/\/+$/, "");
+	if (!/^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/.test(clean) || clean.split("/").some((part) => part === ".." || part === ".")) {
+		throw new Error(`not a repo segment: ${JSON.stringify(segment)} — pass the repo's place in the generation, e.g. "apps/auth"`);
+	}
+	return clean;
+}
+
+/** `"…"` for a POSIX shell: the four characters a double-quoted string still interprets are escaped. */
+function shellDoubleQuoted(value: string): string {
+	return `"${value.replace(/(["\\$`])/g, "\\$1")}"`;
+}
+
+/**
+ * The generation root a printed command should name — `$FORGE` when the directory it names
+ * really holds a `forge.env`, otherwise the walk up from `from` (worktree-aware, see
+ * {@link findForgeRoot}).
+ *
+ * 🔴 **Verified, never trusted.** A `$FORGE` pointing at a directory with no `forge.env` is a
+ * stale export from a shell that outlived a move, and honouring it re-creates the exact defect
+ * {@link repoCd} exists to end: a command naming a directory that is not there.
+ * {@link forgeCodeRoot} deliberately keeps its older contract (the variable wins unchecked); this
+ * is the one for text a person will paste.
+ */
+export function verifiedForgeRoot(from: string, env: NodeJS.ProcessEnv = process.env): string | null {
+	const named = env.FORGE?.trim();
+	if (named && existsSync(join(named, MARKER))) return resolve(named);
+	return findForgeRoot(from);
+}
+
+/**
+ * {@link RepoLocation} for the repo at `segment`, as seen from `from` (pass `import.meta.dir`).
+ *
+ * `from` is REQUIRED: a default here would be this library's own directory — inside somebody's
+ * `node_modules` — and the fallback would print a `cd` into it.
+ *
+ * Never throws on a location (only on a malformed segment), and `dir` always EXISTS: the repo's
+ * home in the located generation, else the checkout `from` is in (a clone, or a checkout
+ * somebody moved — the one thing always true there is that a command run from it runs against
+ * this code), else `from` itself.
+ */
+export function locateRepo(segment: string, from: string, env: NodeJS.ProcessEnv = process.env): RepoLocation {
+	const clean = checkedSegment(segment);
+	const forge = verifiedForgeRoot(from, env);
+	if (forge) {
+		const home = join(forge, clean);
+		if (existsSync(home)) return { dir: home, forgeEnv: join(forge, MARKER) };
+	}
+	return { dir: findPackageRoot(from) ?? resolve(from), forgeEnv: null };
+}
+
+/**
+ * The prefix every command a repo prints should carry — pasteable into any shell, from any
+ * directory. The owner's standing rule: *"Commands you show me must RUN. I paste them into a
+ * terminal whose directory you do not know."*
+ *
+ * With a generation located it sources `forge.env` FIRST and then goes through the variable, so
+ * the reader's shell ends up with `$FORGE`/`$FORGE_STATE` set the way every CLI here expects and
+ * the line shows where the value comes from instead of asserting a path. Without one it is the
+ * plain `cd` into a directory that exists. It never spells `~/`: `check-paths` reds a `cd ~/…`
+ * in source, and cannot see one composed at runtime — which is why this is the one place that
+ * composes it.
+ *
+ * Measured 2026-09-19 by `check-paths`'s `deadCd` rule: twelve printed commands in five repos
+ * `cd`'d into directories two generations gone, each read at a moment something was already
+ * wrong. Four repos then wrote this function; `apps/binary-server/src/repoCommand.ts` (the
+ * original), `apps/auth/src/kit/repoCommand.ts`, and `scripts/forgeRoot.ts` in `family` and `roms`.
+ */
+export function repoCd(segment: string, from: string, env: NodeJS.ProcessEnv = process.env): string {
+	const clean = checkedSegment(segment);
+	const { dir, forgeEnv } = locateRepo(clean, from, env);
+	return forgeEnv ? `source ${shellDoubleQuoted(forgeEnv)} && cd "$FORGE/${clean}"` : `cd ${shellDoubleQuoted(dir)}`;
+}
+
+/** {@link repoCd} joined to `rest` with `&&`, so a failed `cd` stops the line. */
+export function repoCommand(segment: string, rest: string, from: string, env: NodeJS.ProcessEnv = process.env): string {
+	return `${repoCd(segment, from, env)} && ${rest}`;
+}
+
+/**
+ * The same prefix aimed at ANOTHER repo in this generation — what a guard shared by several
+ * apps needs when it is told the other app's place and nothing else (`apps/auth`'s
+ * artifact-boot refusal, which names the app that would not boot).
+ *
+ * Falls back to {@link repoCd} for `selfSegment` when `segment` is not in the located
+ * generation: a line aimed at the wrong-but-real repo is runnable, and a line naming a
+ * directory that is not there is the whole defect.
+ */
+export function otherRepoCd(segment: string, selfSegment: string, from: string, env: NodeJS.ProcessEnv = process.env): string {
+	const clean = checkedSegment(segment);
+	const forge = verifiedForgeRoot(from, env);
+	if (forge && existsSync(join(forge, clean))) return `source ${shellDoubleQuoted(join(forge, MARKER))} && cd "$FORGE/${clean}"`;
+	return repoCd(selfSegment, from, env);
+}
+
+/** {@link otherRepoCd} joined to `rest` with `&&`. */
+export function otherRepoCommand(
+	segment: string,
+	selfSegment: string,
+	rest: string,
+	from: string,
+	env: NodeJS.ProcessEnv = process.env,
+): string {
+	return `${otherRepoCd(segment, selfSegment, from, env)} && ${rest}`;
+}