cursedops 0.22.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedops",
-	"version": "0.22.0",
+	"version": "0.23.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 check that a launchd job imports only what the LOCKED versions of its packages export (a lib-preview overlay's extra subpath or name is a job that dies at the next forced reinstall), 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, the billed-CPU tail check around a deploy's walk and smoke, and each app's worker:secrets and worker:smoke main as one function of its data), the relay a Worker fronts a Mac-bound app with (the Durable Object, the frames, the Mac's dialer and key rotation — lifted from station for roms — and the signed-in stage walk's skeleton and the relay app's whole worker:deploy), the Worker import-graph and await-port checks every Worker app's suite runs over its own source, 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": {

package/src/stageLook.ts

@@ -13,6 +13,11 @@
  *    to binary-server too they turn every media fetch into a CORS preflight it refuses.
  *  - **Sign-in is the stage's own door**: `grantStageOwner` (auth-stage's emailed second factor) and
  *    the app's `/api/auth/sso/callback?grant=…`. Never production's accounts service.
+ *  - **An app with no sign-in is looked at signed out** (`signedIn: false`, `--signed-out`), and a stage
+ *    with no custom domain at its own `origin` (`--origin https://<app>-stage.<account>.workers.dev`).
+ *    patterns has neither (forge task 3918): asking auth-stage for its grant answered 400, so the one
+ *    command could not look at it at all. `tools/stage-look.ts` decides both from auth's registry and
+ *    the app's `wrangler.jsonc`, so nobody has to know.
  *  - **A reaped binary-server sandbox is SAID, not screenshotted.** Its images answer 404, or 503 with
  *    `x-bs-edge-cache: STAGE-ORIGIN-DOWN`; {@link brokenMediaOf} names them, and the CLI exits 1
  *    with the recovery (`apps/binary-server` → `bun run sandbox:up`, then upload again).
@@ -22,7 +27,7 @@
  *
  * CLI, from an app's directory (or `bun $FORGE/tools/stage-look.ts <app> …` from anywhere):
  *
- *     stage-look <app> [path] [--out <dir>]      → <dir>/stage-<app>-390.png, …-1440.png
+ *     stage-look <app> [path] [--out <dir>] [--signed-out] [--origin <url>]   → <dir>/stage-<app>-390.png, …-1440.png
  */
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
@@ -86,6 +91,70 @@ export function brokenMediaOf(r: LookResponse): string | null {
 	return null;
 }
 
+/**
+ * A read of the page's OWN that the stage failed — a same-origin `/api/` answer of 5xx — as
+ * `<status> <path>`. A look shot over one is a picture of an error card or a skeleton, not of the
+ * change (forge task 3914: station's `#/deploys` read 503 "station's Mac is not connected", because a
+ * relay stage has a Mac end only while its `worker:stage-walk` runs).
+ */
+export function failedReadOf(r: Pick<LookResponse, "url" | "status">, origin: string): string | null {
+	const url = new URL(r.url());
+	if (url.origin !== origin || !url.pathname.startsWith("/api/") || r.status() < 500) return null;
+	return `${r.status()} ${url.pathname}`;
+}
+
+/** How long the network may stay busy before the look goes on without it — a player streams for good. */
+export const IDLE_CEILING_MS = 15_000;
+/** How long a page's pending regions (`aria-busy="true"`, cursedbelt's skeletons) may read before the look gives up. */
+export const SETTLE_CEILING_MS = 90_000;
+
+/** The slice of a playwright `Page` that {@link settle} drives. */
+export interface SettlePage {
+	waitForLoadState(state: "networkidle", options: { timeout: number }): Promise<unknown>;
+	evaluate<T>(fn: () => T): Promise<T>;
+}
+
+export interface Settled {
+	/** False when the network never went quiet inside {@link IDLE_CEILING_MS} — said, never fatal. */
+	idle: boolean;
+	/** The pending regions still reading at the ceiling, by their text; empty when the page settled. */
+	busy: string[];
+	ms: number;
+}
+
+/**
+ * Wait until the page has DRAWN, not until the network is quiet: both of the looks that went wrong
+ * waited for `networkidle` alone. music's never came (its player keeps a stream open), so the look threw;
+ * station's `#/deploys` came while its read was still in flight, so the look shot four skeleton tiles
+ * and "Reading the apps' deploys…" (forge task 3914). So: `networkidle` with a ceiling, then every
+ * `aria-busy="true"` region gone on two reads in a row, up to {@link SETTLE_CEILING_MS} — and what is
+ * still busy then is SAID, so a look of a loading state never reads as a look of the page.
+ */
+export async function settle(
+	page: SettlePage,
+	options: { idleMs?: number; settleMs?: number; pollMs?: number; sleep?: (ms: number) => Promise<unknown>; now?: () => number } = {},
+): Promise<Settled> {
+	const { idleMs = IDLE_CEILING_MS, settleMs = SETTLE_CEILING_MS, pollMs = 500, sleep = Bun.sleep, now = Date.now } = options;
+	const start = now();
+	const idle = await page.waitForLoadState("networkidle", { timeout: idleMs }).then(
+		() => true,
+		() => false,
+	);
+	const pending = () =>
+		page.evaluate(() =>
+			[...document.querySelectorAll('[aria-busy="true"]')].map((el) => (el.textContent ?? "").replace(/\s+/g, " ").trim().slice(0, 80) || el.tagName.toLowerCase()),
+		);
+	let quiet = 0;
+	let busy: string[] = [];
+	while (true) {
+		busy = await pending();
+		quiet = busy.length === 0 ? quiet + 1 : 0;
+		if (quiet >= 2) return { idle, busy: [], ms: now() - start };
+		if (now() - start >= settleMs) return { idle, busy, ms: now() - start };
+		await sleep(pollMs);
+	}
+}
+
 /** The slices of playwright this drives. Structural, so cursedops needs no dependency on it. */
 interface LookRoute {
 	request(): { headers(): Record<string, string> };
@@ -117,6 +186,10 @@ export interface StageLookSpec {
 	state?: string;
 	/** playwright's `chromium`; default: `playwright` resolved from the working directory. */
 	chromium?: LookChromium;
+	/** False for an app with no sign-in: no grant is asked for and no callback is opened. Default true. */
+	signedIn?: boolean;
+	/** The stage's origin when it is not {@link stageOrigin} — a stage on workers.dev alone. */
+	origin?: string;
 	/** Extra Chromium flags — collections' audio daemon, say. */
 	args?: string[];
 	/** Seams for the suite. */
@@ -140,14 +213,14 @@ async function defaultChromium(): Promise<LookChromium> {
 }
 
 /**
- * A page on `<app>-stage`, signed in as its owner, with Access headers on the stage's requests only.
+ * A page on `<app>-stage`, signed in as its owner (unless `signedIn: false`), with Access headers on the stage's requests only.
  * `Page` is the caller's playwright `Page` — the look builds it, so the cast is the caller's word.
  */
 export async function openStagePage<Page = LookPage>(spec: StageLookSpec): Promise<StageLook<Page>> {
 	const cwd = process.cwd();
 	const forge = spec.forge ?? forgeCodeRoot(cwd);
 	if (!forge) throw new Error(`no forge.env above ${cwd} — run the look from inside the generation`);
-	const origin = stageOrigin(spec.app);
+	const origin = spec.origin ? new URL(spec.origin).origin : stageOrigin(spec.app);
 	const access = spec.headers ?? accessHeaders(spec.state ?? requireForgeState(cwd));
 	const chromium = spec.chromium ?? (await defaultChromium());
 	const browser = await chromium.launch({ args: [...(spec.args ?? []), ...pinnedResolverArgs(new URL(origin).hostname, spec.dig)] });
@@ -164,10 +237,12 @@ export async function openStagePage<Page = LookPage>(spec: StageLookSpec): Promi
 			const b = brokenMediaOf(r);
 			if (b) broken.push(b);
 		});
-		const granted = (spec.grant ?? (() => grantStageOwner({ forge, app: spec.app })))();
-		if (!granted.ok) throw new Error(`auth-stage gave no grant for ${spec.app} — its output above says why`);
-		const back = await page.goto(`${origin}/api/auth/sso/callback?grant=${encodeURIComponent(granted.grant)}`, { waitUntil: "load" });
-		if (back && back.status() >= 400) throw new Error(`${origin}'s sign-in callback answered ${back.status()}`);
+		if (spec.signedIn !== false) {
+			const granted = (spec.grant ?? (() => grantStageOwner({ forge, app: spec.app })))();
+			if (!granted.ok) throw new Error(`auth-stage gave no grant for ${spec.app} — its output above says why (an app with no sign-in is looked at with --signed-out)`);
+			const back = await page.goto(`${origin}/api/auth/sso/callback?grant=${encodeURIComponent(granted.grant)}`, { waitUntil: "load" });
+			if (back && back.status() >= 400) throw new Error(`${origin}'s sign-in callback answered ${back.status()}`);
+		}
 		return { page: page as Page, origin, brokenMedia: () => [...broken], close: () => browser.close() };
 	} catch (e) {
 		await browser.close();
@@ -175,27 +250,76 @@ export async function openStagePage<Page = LookPage>(spec: StageLookSpec): Promi
 	}
 }
 
+export interface LookArgs {
+	app: string;
+	path: string;
+	out?: string;
+	signedIn: boolean;
+	origin?: string;
+}
+
+/** The CLI's words, or what is wrong with them. A flag that takes a value and has none is a usage fault, never a path. */
+export function parseLookArgs(argv: readonly string[]): LookArgs | { usage: string } {
+	const plain: string[] = [];
+	let out: string | undefined;
+	let origin: string | undefined;
+	let signedIn = true;
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i] as string;
+		if (a === "--signed-out") signedIn = false;
+		else if (a === "--out" || a === "--origin") {
+			const v = argv[++i];
+			if (!v || v.startsWith("--")) return { usage: `${a} needs a value` };
+			if (a === "--out") out = v;
+			else if (!URL.canParse(v) || !/^https?:$/.test(new URL(v).protocol)) return { usage: `--origin ${v} is not an http(s) URL` };
+			else origin = new URL(v).origin;
+		} else if (a.startsWith("--")) return { usage: `unknown flag ${a}` };
+		else plain.push(a);
+	}
+	const [app, path = "/", extra] = plain;
+	if (!app) return { usage: "which app?" };
+	if (extra) return { usage: `one path at a time (got ${path} and ${extra})` };
+	return { app, path, signedIn, ...(out ? { out } : {}), ...(origin ? { origin } : {}) };
+}
+
 /** Shoot `path` at 390 and 1440. Exit 1 when the page or its media is broken, so a look never passes on broken tiles. */
 async function main(argv: string[]): Promise<number> {
-	const outAt = argv.indexOf("--out");
-	const out = outAt >= 0 ? argv[outAt + 1] : undefined;
-	const [app, path = "/"] = outAt >= 0 ? argv.filter((_, i) => i !== outAt && i !== outAt + 1) : argv;
-	if (!app || (outAt >= 0 && !out)) {
-		console.error("usage: stage-look <app> [path] [--out <dir>]   (run in the app's directory, or `bun $FORGE/tools/stage-look.ts <app> …`)");
+	const parsed = parseLookArgs(argv);
+	if ("usage" in parsed) {
+		console.error(`${parsed.usage}\nusage: stage-look <app> [path] [--out <dir>] [--signed-out] [--origin <url>]   (run in the app's directory, or \`bun $FORGE/tools/stage-look.ts <app> …\`)`);
 		return 2;
 	}
+	const { app, path, out, signedIn, origin } = parsed;
 	const dir = out ?? join(process.env.FORGE_BATCH_TMP ?? requireForgeState(process.cwd()), "stage-look");
 	mkdirSync(dir, { recursive: true });
 	let bad = false;
 	for (const width of [390, 1440]) {
-		type ShotPage = LookPage & { screenshot(o: { path: string; fullPage?: boolean }): Promise<unknown>; url(): string };
-		const look = await openStagePage<ShotPage>({ app, width });
+		type ShotPage = LookPage & SettlePage & { screenshot(o: { path: string; fullPage?: boolean }): Promise<unknown>; url(): string };
+		const look = await openStagePage<ShotPage>({ app, width, signedIn, ...(origin ? { origin } : {}) });
 		try {
-			const res = await look.page.goto(`${look.origin}${path}`, { waitUntil: "networkidle" });
+			const failed: string[] = [];
+			look.page.on("response", (r) => {
+				const f = failedReadOf(r, look.origin);
+				if (f && !failed.includes(f)) failed.push(f);
+			});
+			const res = await look.page.goto(`${look.origin}${path}`, { waitUntil: "load" });
+			const settled = await settle(look.page);
 			const shot = join(dir, `stage-${app}-${width}.png`);
 			await look.page.screenshot({ path: shot });
-			console.log(`${width}: ${res?.status() ?? "?"} ${look.page.url()} → ${shot}`);
-			if (!res || res.status() >= 400) bad = true;
+			// 🔴 `null` is not a failure: the sign-in callback already landed on `/`, so a `/#/deploys` is a
+			// same-document hash change, which playwright answers with no response (forge task 3914's `?`).
+			console.log(`${width}: ${res?.status() ?? "same document"} ${look.page.url()} → ${shot} (drawn in ${(settled.ms / 1000).toFixed(1)} s)`);
+			if (res && res.status() >= 400) bad = true;
+			if (!settled.idle) console.log(`  · the network never went quiet in ${IDLE_CEILING_MS / 1000} s (a stream or a poll) — the look waited on the page's own pending regions instead`);
+			if (settled.busy.length) {
+				bad = true;
+				console.error(`  🔴 still READING after ${SETTLE_CEILING_MS / 1000} s — this shot is the loading state, not the page: ${settled.busy.slice(0, 3).join(" · ")}`);
+			}
+			if (failed.length) {
+				bad = true;
+				console.error(`  🔴 the stage failed ${failed.length} of the page's own read(s) — the shot shows what it does without them: ${failed.slice(0, 5).join(", ")}`);
+				console.error("     a 503 on a relay app's stage is often its Mac end being down — that end is up only while its `worker:stage-walk` runs");
+			}
 			const broken = look.brokenMedia();
 			if (broken.length) {
 				bad = true;