@decohere/ci-tools 0.0.1-dev.11 → 0.0.1-dev.111

package/src/bench/history.mjs

@@ -0,0 +1,225 @@
+/**
+ * Benchmark history: the results of each `pnpm bench` run, kept per machine so runs are only
+ * compared like for like (#660). Pure functions over plain data; bench.mjs does the I/O.
+ *
+ * Shape (version 2):
+ *   { version: 2, contexts: { [contextId]: { context, runs: [{ date, sha, results }] } } }
+ * newest run first. A result is { id, label, unit, median, p90?, min, max, samples, files? }.
+ */
+
+import crypto from "node:crypto";
+
+export const HISTORY_VERSION = 2;
+/** Nightly runs: a month per machine, enough for a trend and a regression baseline. */
+export const MAX_RUNS = 30;
+/** Printed by each suite before its JSON array of results (projects/flux/bench/harness.ts). */
+export const RESULT_PREFIX = "BENCH_RESULT ";
+
+/** The machine a run happened on. Runs are compared only within one context. */
+export function getContext(os, env, nodeVersion, date = new Date()) {
+	const cpus = os.cpus();
+	const nodeMajor = nodeVersion.match(/^v(\d+)/)?.[1] ?? "?";
+	const rawEnv = env.BENCH_ENV ?? null;
+	return {
+		benchEnv: rawEnv ? `${rawEnv}-node${nodeMajor}` : "(local)",
+		date: date.toISOString(),
+		os: { platform: os.platform(), arch: os.arch() },
+		cpu: { model: cpus[0]?.model?.trim() ?? "unknown", count: cpus.length },
+		memoryGb: Number.parseFloat((os.totalmem() / 1024 ** 3).toFixed(1)),
+		node: nodeVersion,
+	};
+}
+
+/** 16-char SHA-256 prefix of platform|arch|cpu|cores|memGB|node. */
+export function contextId(ctx) {
+	const key = [
+		ctx.os.platform,
+		ctx.os.arch,
+		ctx.cpu.model,
+		ctx.cpu.count,
+		ctx.memoryGb,
+		ctx.node,
+	].join("|");
+	return crypto.createHash("sha256").update(key).digest("hex").slice(0, 16);
+}
+
+/** The results a suite printed, from its whole output. Throws if it printed none. */
+export function parseResults(output, suite) {
+	const line = output
+		.split(/\r?\n/)
+		.reverse()
+		.find((candidate) => candidate.startsWith(RESULT_PREFIX));
+	if (line == null)
+		throw new Error(`suite "${suite}" printed no ${RESULT_PREFIX.trim()} line`);
+	return JSON.parse(line.slice(RESULT_PREFIX.length));
+}
+
+const FORGE_BENCHMARKS = [
+	["forge build es6 + types", "forge.build.local"],
+	["forge build es6 only", "forge.build.debug"],
+	["forge build types only", "forge.build.types-only"],
+];
+
+/**
+ * Results from `vitest bench --outputJson` for the forge build benchmark. Its names end in a
+ * file count, so they are mapped to stable ids; vitest reports no p90, so it is left out.
+ */
+export function fromVitest(vitestOutput) {
+	return vitestOutput.files
+		.flatMap((file) => file.groups)
+		.flatMap((group) => group.benchmarks)
+		.map((benchmark) => {
+			const id = FORGE_BENCHMARKS.find(([prefix]) => benchmark.name.startsWith(prefix))?.[1];
+			if (id == null) throw new Error(`unknown forge benchmark "${benchmark.name}"`);
+			const files = Number(benchmark.name.match(/\((\d+) files\)/)?.[1]);
+			return {
+				id,
+				label: benchmark.name.replace(/\s*\(\d+ files\)$/, ""),
+				unit: "ms",
+				median: benchmark.median ?? benchmark.mean,
+				min: benchmark.min,
+				max: benchmark.max,
+				samples: benchmark.sampleCount,
+				...(Number.isFinite(files) ? { files } : {}),
+			};
+		});
+}
+
+/** Throws when a result has no usable numbers: a suite that errored mid-run, not a slow one. */
+export function assertValid(results) {
+	const invalid = results.filter(
+		(result) => !Number.isFinite(result.median) || !(result.samples > 0),
+	);
+	if (invalid.length > 0) {
+		throw new Error(
+			`${invalid.length} benchmark(s) have no valid samples: ${invalid.map((r) => r.id).join(", ")}`,
+		);
+	}
+}
+
+/**
+ * Reads a stored history. Version 1 (forge build only, raw vitest output) is converted so its
+ * trend carries on; anything unrecognised starts empty rather than mixing formats.
+ */
+export function normalize(raw) {
+	if (raw?.version === HISTORY_VERSION && raw.contexts != null) return raw;
+	const contexts = {};
+	for (const [id, entry] of Object.entries(raw?.runs ?? {})) {
+		const runs = (entry.runs ?? [])
+			.filter((run) => run.vitestOutput != null)
+			.map((run) => ({ date: run.date, sha: null, results: fromVitest(run.vitestOutput) }));
+		if (runs.length > 0) contexts[id] = { context: entry.context, runs };
+	}
+	return { version: HISTORY_VERSION, contexts };
+}
+
+/** The previous run for this context, if any: what a new run is compared against. */
+export function previousRun(history, id) {
+	return history.contexts[id]?.runs[0];
+}
+
+/** A new history with `run` first in its context, trimmed to `max` runs. Does not mutate. */
+export function appendRun(history, ctx, run, max = MAX_RUNS) {
+	const id = contextId(ctx);
+	const runs = [run, ...(history.contexts[id]?.runs ?? [])].slice(0, max);
+	return {
+		version: HISTORY_VERSION,
+		contexts: { ...history.contexts, [id]: { context: ctx, runs } },
+	};
+}
+
+/** One row per current result, with the change in median against the previous run. */
+export function compare(results, previous) {
+	const before = new Map((previous?.results ?? []).map((result) => [result.id, result]));
+	return results.map((result) => {
+		const old = before.get(result.id);
+		if (old == null) return { id: result.id, current: result.median };
+		const delta = result.median - old.median;
+		return {
+			id: result.id,
+			current: result.median,
+			previous: old.median,
+			delta,
+			percent: old.median === 0 ? 0 : (delta / old.median) * 100,
+		};
+	});
+}
+
+/** The comparison as an aligned text table. */
+export function formatComparison(rows) {
+	const ms = (value) => (value == null ? "n/a" : `${value.toFixed(1)} ms`);
+	const signed = (value, suffix) =>
+		value == null ? "n/a" : `${value >= 0 ? "+" : ""}${value.toFixed(1)}${suffix}`;
+	const table = [
+		["Benchmark", "Median", "Previous", "Delta", "%"],
+		...rows.map((row) => [
+			row.id,
+			ms(row.current),
+			ms(row.previous),
+			signed(row.delta, " ms"),
+			signed(row.percent, "%"),
+		]),
+	];
+	const widths = table[0].map((_, column) =>
+		Math.max(...table.map((row) => row[column].length)),
+	);
+	const line = (row) =>
+		row
+			.map((cell, column) =>
+				(column === 0 ? cell.padEnd : cell.padStart).call(cell, widths[column]),
+			)
+			.join(" | ");
+	return [
+		line(table[0]),
+		widths.map((w) => "-".repeat(w)).join("-+-"),
+		...table.slice(1).map(line),
+	].join("\n");
+}
+
+/**
+ * When a benchmark counts as slower (#660): its median beat the baseline by more than
+ * `threshold` on each of the last `confirmRuns` runs, where the baseline is the median of the
+ * `baselineRuns` runs before those. Two nights in a row, so one noisy runner files nothing.
+ */
+export const REGRESSION = { threshold: 0.2, confirmRuns: 2, baselineRuns: 7, minBaseline: 3 };
+
+function medianOf(values) {
+	const sorted = [...values].sort((a, b) => a - b);
+	const middle = Math.floor(sorted.length / 2);
+	return sorted.length % 2 === 1 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2;
+}
+
+/** The benchmarks that regressed on one machine, given its runs newest first. */
+export function findRegressions(runs, options = REGRESSION) {
+	const recent = runs.slice(0, options.confirmRuns);
+	const before = runs.slice(options.confirmRuns, options.confirmRuns + options.baselineRuns);
+	if (recent.length < options.confirmRuns) return [];
+	const medianIn = (run, id) => run.results.find((result) => result.id === id)?.median;
+	const regressions = [];
+	for (const latest of recent[0].results) {
+		const baselineValues = before
+			.map((run) => medianIn(run, latest.id))
+			.filter((value) => Number.isFinite(value));
+		if (baselineValues.length < options.minBaseline) continue;
+		const baseline = medianOf(baselineValues);
+		const recentValues = recent.map((run) => medianIn(run, latest.id));
+		const slower = recentValues.every(
+			(value) => Number.isFinite(value) && value > baseline * (1 + options.threshold),
+		);
+		if (!slower) continue;
+		regressions.push({
+			id: latest.id,
+			label: latest.label,
+			baseline,
+			percent: (recentValues[0] / baseline - 1) * 100,
+			recent: recent.map((run, index) => ({
+				date: run.date,
+				sha: run.sha,
+				median: recentValues[index],
+			})),
+			// The change landed between the newest baseline run and the oldest slow one.
+			lastGood: before[0] == null ? null : { date: before[0].date, sha: before[0].sha },
+		});
+	}
+	return regressions;
+}

package/src/bench/regression-issue.mjs

@@ -0,0 +1,51 @@
+/**
+ * The GitHub issue for a benchmark that got slower (#660): one open issue per benchmark,
+ * found again by its exact title and updated in place while the regression lasts.
+ */
+
+const PAGES_URL = "https://typesmiths.github.io/decohere/benchmark.html";
+
+export function issueTitle(regression) {
+	return `perf(bench): ${regression.id} is slower`;
+}
+
+function ms(value) {
+	return `${value.toFixed(1)} ms`;
+}
+
+function commitLink(repoUrl, sha) {
+	return sha == null ? "unknown" : `[\`${sha.slice(0, 7)}\`](${repoUrl}/commit/${sha})`;
+}
+
+export function issueBody(regression, { repoUrl, runUrl, machine, threshold }) {
+	const newest = regression.recent[0];
+	const oldestSlow = regression.recent.at(-1);
+	const range =
+		regression.lastGood?.sha != null && newest.sha != null
+			? `[${regression.lastGood.sha.slice(0, 7)}...${newest.sha.slice(0, 7)}](${repoUrl}/compare/${regression.lastGood.sha}...${newest.sha})`
+			: "unknown (no baseline commit recorded)";
+	return [
+		"## Problem",
+		"",
+		`The nightly benchmark **${regression.label}** (\`${regression.id}\`) has a median ${regression.percent.toFixed(0)}% above its baseline, on each of the last ${regression.recent.length} nightly runs. A benchmark counts as slower above ${Math.round(threshold * 100)}%.`,
+		"",
+		`- Baseline (median of the runs before): **${ms(regression.baseline)}**`,
+		...regression.recent.map(
+			(run) =>
+				`- ${run.date.slice(0, 10)}, ${commitLink(repoUrl, run.sha)}: **${ms(run.median)}**`,
+		),
+		`- Machine: ${machine}`,
+		"",
+		`The change landed after the last normal run (${regression.lastGood?.date.slice(0, 10) ?? "unknown"}) and by ${oldestSlow.date.slice(0, 10)}: commits ${range}.`,
+		"",
+		"## What to do",
+		"",
+		"1. Check the trend on the [benchmark page](" +
+			PAGES_URL +
+			"). A step that holds is a real change; a single machine type jumping may be the runner.",
+		"2. Reproduce locally: check out the last normal commit, `pnpm bench:save`, then the newest commit, `pnpm bench`, and read the comparison.",
+		"3. Fix the cause, or if the slowdown is intended, say why here and close the issue.",
+		"",
+		`Updated by the nightly bench workflow: ${runUrl}`,
+	].join("\n");
+}

package/src/bench/trace.mjs

@@ -6,8 +6,8 @@ import { join } from "node:path";
 
 const WORKSPACE_ROOT = process.cwd();
 const VITEST_BIN = join(WORKSPACE_ROOT, "node_modules/.bin/vitest");
-const CONFIG = join(WORKSPACE_ROOT, "vitest.e2e.config.ts");
-const TRACE_SPEC = "projects/terminal/e2e/build.trace.e2e.spec.ts";
+const CONFIG = join(WORKSPACE_ROOT, "vitest.config.ts");
+const TRACE_SPEC = "projects/cli/e2e/build.trace.e2e.spec.ts";
 const TRACE_LOG_DIR = join(WORKSPACE_ROOT, ".decohere", "logs");
 
 function truthy(value, defaultValue = false) {
@@ -149,19 +149,23 @@ if (traceLogPath != null) {
 	mkdirSync(TRACE_LOG_DIR, { recursive: true });
 }
 
-const result = spawnSync(VITEST_BIN, ["run", "--config", CONFIG, TRACE_SPEC], {
-	cwd: WORKSPACE_ROOT,
-	stdio: "pipe",
-	encoding: "utf8",
-	maxBuffer: 1024 * 1024 * 200,
-	env: {
-		...process.env,
-		NODE_OPTIONS: "",
-		FORGE_TRACE: "1",
-		FORGE_TRACE_STRUCTURED: "1",
-		LOG_LEVEL: process.env.LOG_LEVEL ?? "trace",
+const result = spawnSync(
+	VITEST_BIN,
+	["run", "--config", CONFIG, "--project", "e2e", TRACE_SPEC],
+	{
+		cwd: WORKSPACE_ROOT,
+		stdio: "pipe",
+		encoding: "utf8",
+		maxBuffer: 1024 * 1024 * 200,
+		env: {
+			...process.env,
+			NODE_OPTIONS: "",
+			FORGE_TRACE: "1",
+			FORGE_TRACE_STRUCTURED: "1",
+			LOG_LEVEL: process.env.LOG_LEVEL ?? "trace",
+		},
 	},
-});
+);
 
 const stdout = typeof result.stdout === "string" ? result.stdout : "";
 const stderr = typeof result.stderr === "string" ? result.stderr : "";

package/src/github/credential-nudge.mjs

@@ -0,0 +1,320 @@
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const LIST_ID = process.env.CLICKUP_LIST_ID ?? "901220171084";
+const API = "https://api.clickup.com/api/v2";
+const WARN_DAYS = 14;
+const MS_PER_DAY = 86_400_000;
+const CHORE_TYPE = 1004;
+const DEFAULT_REPO = "typesmiths/decohere";
+
+/**
+ * One profile per credential. Date math, ClickUp upsert, and fail-closed live below.
+ * `ghEnv` unset means repo secret / repo variable (not an Actions environment).
+ *
+ * @typedef {{
+ *   id: string,
+ *   secret: string,
+ *   expiresVar: string,
+ *   ghEnv?: string,
+ *   mint: string,
+ *   failImpact: string,
+ *   rejectedWhy: string,
+ *   revokeUrl: string,
+ * }} CredentialProfile
+ */
+
+/** @type {Record<string, CredentialProfile>} */
+export const CREDENTIALS = {
+	ghcr: {
+		id: "ghcr",
+		secret: "GHCR_PUSH_TOKEN",
+		expiresVar: "GHCR_TOKEN_EXPIRES_AT",
+		ghEnv: "ghcr-publish",
+		mint: "Create a **classic** GitHub PAT (fine-grained tokens cannot push to GHCR): https://github.com/settings/tokens/new?scopes=write:packages",
+		failImpact:
+			"npm may already have published. Docker login/push and the `v*` tag will **fail**. The SHA stays untagged, so the next successful Publish of that tip can finish Docker + tag after you rotate. Images are not pushed with `GITHUB_TOKEN`.",
+		rejectedWhy: "GHCR `docker login` returned 401 (expired, revoked, or wrong secret name).",
+		revokeUrl: "https://github.com/settings/tokens",
+	},
+	npm: {
+		id: "npm",
+		secret: "NODE_AUTH_TOKEN",
+		expiresVar: "NODE_AUTH_TOKEN_EXPIRES_AT",
+		mint: "Create an npm **read** token (granular/classic) at https://www.npmjs.com/settings/~/tokens — Publish PUTs are OIDC; this token is only for private `npm view` and create smoke.",
+		failImpact:
+			"Verify cannot see private packages, so skipIfPublished and create smoke are unsafe. Publish **fails closed** before OIDC/Docker. After you rotate, re-run the failed Publish jobs.",
+		rejectedWhy: "`npm whoami` failed (expired, revoked, or missing `NODE_AUTH_TOKEN`).",
+		revokeUrl: "https://www.npmjs.com/settings/~/tokens",
+	},
+};
+
+export function utcDayMs(date) {
+	return Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate());
+}
+
+/** @param {string | undefined} raw */
+export function parseExpiresAt(raw) {
+	const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(String(raw ?? "").trim());
+	if (!match) {
+		return null;
+	}
+	return Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3]));
+}
+
+/**
+ * @param {{ now?: number, expiresAtMs: number | null, warnDays?: number }} options
+ * @returns {{ kind: "missing" | "ok" | "warn" | "expired", daysLeft: number | null }}
+ */
+export function assessTokenLifetime(options) {
+	const { expiresAtMs, warnDays = WARN_DAYS } = options;
+	if (expiresAtMs == null) {
+		return { kind: "missing", daysLeft: null };
+	}
+	const today = utcDayMs(new Date(options.now ?? Date.now()));
+	const daysLeft = Math.round((expiresAtMs - today) / MS_PER_DAY);
+	if (daysLeft <= 0) {
+		return { kind: "expired", daysLeft };
+	}
+	if (daysLeft <= warnDays) {
+		return { kind: "warn", daysLeft };
+	}
+	return { kind: "ok", daysLeft };
+}
+
+/** @param {CredentialProfile} credential */
+export function resolveRepo() {
+	return process.env.GITHUB_REPOSITORY?.trim() || DEFAULT_REPO;
+}
+
+/** @param {CredentialProfile} credential */
+export function ghScopeFlags(credential) {
+	return credential.ghEnv ? `--env ${credential.ghEnv} ` : "";
+}
+
+/** @param {string} id */
+export function credentialProfile(id) {
+	const credential = CREDENTIALS[id];
+	if (!credential) {
+		throw new Error(
+			`Unknown NUDGE_CREDENTIAL=${id}. Expected one of: ${Object.keys(CREDENTIALS).join(", ")}`,
+		);
+	}
+	return credential;
+}
+
+/** @param {CredentialProfile} credential */
+export function taskName(credential, expiresYmd) {
+	return `chore(security): rotate ${credential.secret} (expires ${expiresYmd})`;
+}
+
+/** @param {CredentialProfile} credential */
+export function rotationCommands(credential, nextExpiresYmd, repo = resolveRepo()) {
+	const next = nextExpiresYmd ?? "YYYY-MM-DD";
+	const flags = ghScopeFlags(credential);
+	return [
+		credential.mint,
+		"",
+		"Then from a trusted machine (do not paste the token into Actions or this task):",
+		"",
+		"```bash",
+		`gh secret set ${credential.secret} ${flags}--repo ${repo}`,
+		`gh variable set ${credential.expiresVar} ${flags}--repo ${repo} --body ${next}`,
+		"```",
+		"",
+		`Revoke the old token: ${credential.revokeUrl}`,
+		"Mark this task complete, then retry Publish:",
+		"",
+		"```bash",
+		`gh run list --repo ${repo} --workflow Publish --limit 5`,
+		`gh run rerun --failed <run-id> --repo ${repo}`,
+		"```",
+	].join("\n");
+}
+
+export function suggestedNextExpiry(fromMs, days = 90) {
+	const start = utcDayMs(new Date(fromMs));
+	const next = new Date(start + days * MS_PER_DAY);
+	const y = next.getUTCFullYear();
+	const m = String(next.getUTCMonth() + 1).padStart(2, "0");
+	const d = String(next.getUTCDate()).padStart(2, "0");
+	return `${y}-${m}-${d}`;
+}
+
+/** @param {CredentialProfile} credential */
+export function buildDescription(credential, options) {
+	const { kind, expiresYmd, daysLeft, rejected, runUrl } = options;
+	const next = suggestedNextExpiry(Date.now());
+	const why = rejected
+		? credential.rejectedWhy
+		: kind === "expired"
+			? `${credential.expiresVar} (${expiresYmd}) is today or in the past. Rotate ${credential.secret} and this date before Publish can continue.`
+			: `${credential.secret} expires on ${expiresYmd} (${daysLeft} day(s) left). Rotate before that date so Publish does not fail closed.`;
+	return [
+		"## Summary",
+		"",
+		why,
+		"",
+		"## If this is not done in time",
+		"",
+		credential.failImpact,
+		"",
+		"## Commands",
+		"",
+		rotationCommands(credential, next),
+		"",
+		runUrl ? `- Workflow run: ${runUrl}` : null,
+	]
+		.filter((line) => line != null)
+		.join("\n");
+}
+
+async function clickup(method, path, body) {
+	const key = process.env.CLICKUP_API_KEY;
+	if (key == null || key.length === 0) {
+		throw new Error("Missing CLICKUP_API_KEY");
+	}
+	const response = await fetch(`${API}${path}`, {
+		method,
+		headers: {
+			Authorization: key,
+			"Content-Type": "application/json",
+		},
+		body: body == null ? undefined : JSON.stringify(body),
+	});
+	const text = await response.text();
+	if (!response.ok) {
+		throw new Error(
+			`ClickUp ${method} ${path} failed (${response.status}): ${text.slice(0, 500)}`,
+		);
+	}
+	return text.length === 0 ? undefined : JSON.parse(text);
+}
+
+async function findTaskByName(name) {
+	for (let page = 0; page < 10; page += 1) {
+		const qs = new URLSearchParams({
+			include_closed: "true",
+			subtasks: "false",
+			page: String(page),
+		});
+		const data = await clickup("GET", `/list/${LIST_ID}/task?${qs}`);
+		const tasks = Array.isArray(data) ? data : (data?.tasks ?? []);
+		const match = tasks.find((task) => task.name === name);
+		if (match) {
+			return match;
+		}
+		if (tasks.length < 100) {
+			break;
+		}
+	}
+	return null;
+}
+
+async function firstOpenStatus() {
+	const list = await clickup("GET", `/list/${LIST_ID}`);
+	return (list.statuses ?? []).find((status) => status.type === "open")?.status;
+}
+
+function runUrl() {
+	if (
+		process.env.GITHUB_SERVER_URL &&
+		process.env.GITHUB_REPOSITORY &&
+		process.env.GITHUB_RUN_ID
+	) {
+		return `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}`;
+	}
+	return "";
+}
+
+/** @param {CredentialProfile} credential */
+export async function upsertRotationTask(credential, options) {
+	const { expiresYmd, kind, daysLeft, rejected } = options;
+	const name = taskName(credential, expiresYmd ?? "unknown");
+	const existing = await findTaskByName(name);
+	const dueMs = parseExpiresAt(expiresYmd);
+	const payload = {
+		name,
+		markdown_description: buildDescription(credential, {
+			kind,
+			expiresYmd,
+			daysLeft,
+			rejected,
+			runUrl: runUrl(),
+		}),
+		custom_item_id: CHORE_TYPE,
+		priority: rejected || kind === "expired" ? 1 : 2,
+		due_date: dueMs == null ? undefined : dueMs,
+		due_date_time: false,
+	};
+	const assignee = process.env.CLICKUP_ASSIGNEE_ID?.trim();
+	if (assignee) {
+		payload.assignees = [Number(assignee)];
+	}
+
+	if (existing) {
+		const update = {
+			markdown_description: payload.markdown_description,
+			priority: payload.priority,
+			due_date: payload.due_date,
+			due_date_time: false,
+		};
+		if (existing.closed || existing.status?.type === "closed") {
+			const status = await firstOpenStatus();
+			if (status) {
+				update.status = status;
+			}
+		}
+		await clickup("PUT", `/task/${existing.id}`, update);
+		return { id: existing.id, url: existing.url, created: false };
+	}
+	const created = await clickup("POST", `/list/${LIST_ID}/task`, payload);
+	return { id: created.id, url: created.url, created: true };
+}
+
+export async function runNudge(env = process.env) {
+	const credential = credentialProfile(String(env.NUDGE_CREDENTIAL ?? "").trim());
+	const rejected = env.NUDGE_REJECTED === "1";
+	const expiresYmd = String(env[credential.expiresVar] ?? "").trim();
+	const expiresAtMs = parseExpiresAt(expiresYmd);
+	const assessment = assessTokenLifetime({ expiresAtMs });
+	const flags = ghScopeFlags(credential);
+	const repo = env.GITHUB_REPOSITORY?.trim() || DEFAULT_REPO;
+
+	if (assessment.kind === "missing" && !rejected) {
+		process.stderr.write(
+			`${credential.ghEnv ? `${credential.ghEnv} environment` : "repository"} variable ${credential.expiresVar}=YYYY-MM-DD is required\n` +
+				`  gh variable set ${credential.expiresVar} ${flags}--repo ${repo} --body YYYY-MM-DD\n`,
+		);
+		return 1;
+	}
+
+	if (rejected || assessment.kind === "warn" || assessment.kind === "expired") {
+		const result = await upsertRotationTask(credential, {
+			expiresYmd: expiresYmd || "unknown",
+			kind: assessment.kind,
+			daysLeft: assessment.daysLeft,
+			rejected,
+		});
+		process.stdout.write(
+			`${result.created ? "Created" : "Updated"} ClickUp ${result.id} ${result.url ?? ""}\n`,
+		);
+	}
+
+	if (rejected || assessment.kind === "expired" || assessment.kind === "missing") {
+		if (assessment.kind === "expired") {
+			process.stderr.write(
+				`${credential.secret} calendar expiry ${expiresYmd} has been reached — refusing to continue\n`,
+			);
+		}
+		return 1;
+	}
+	return 0;
+}
+
+const isCli =
+	process.argv[1] != null && import.meta.url === pathToFileURL(resolve(process.argv[1])).href;
+
+if (isCli) {
+	process.exit(await runNudge());
+}