@bensandee/forgejo-cli 0.5.5 → 0.6.0

package/dist/bin.mjs

@@ -162,7 +162,7 @@ function loadEnvFileForBin(rawArgs, bin, io = processIo) {
 //#region src/version.ts
 const parsed = z.object({ version: z.string() }).safeParse({
 	name: "@bensandee/forgejo-cli",
-	version: "0.5.5",
+	version: "0.6.0",
 	description: "bst-fj: Forgejo API commands without the rest of bst",
 	license: "MIT",
 	repository: {
@@ -643,6 +643,11 @@ function listFlagPresent(rawArgs, flag) {
 	const long = `--${flag}`;
 	return rawArgs.some((token) => token === long || token.startsWith(`${long}=`));
 }
+function parseLimitFlag(raw) {
+	const value = Number(raw);
+	if (!Number.isInteger(value) || value < 1) throw new FatalError(`--limit must be a positive integer, got "${raw}"`);
+	return value;
+}
 //#endregion
 //#region ../cli-kit/src/output.ts
 const stdout = (msg) => console.log(msg);
@@ -1073,20 +1078,23 @@ function cliFetcher() {
 //#endregion
 //#region ../forgejo/src/errors.ts
 var ForgeAccessError = class extends FatalError {};
-function authHeaders$2(conn) {
+function authHeaders(conn) {
 	return { Authorization: `token ${conn.token}` };
 }
 function jsonHeaders(conn) {
 	return {
-		...authHeaders$2(conn),
+		...authHeaders(conn),
 		"Content-Type": "application/json"
 	};
 }
 function repoNotFoundMessage(conn) {
 	return `Repository ${conn.repository} not found (or the token cannot see it)`;
 }
+function repoBase(conn) {
+	return `${conn.serverUrl}/api/v1/repos/${conn.repository}`;
+}
 function issuesBase(conn) {
-	return `${conn.serverUrl}/api/v1/repos/${conn.repository}/issues`;
+	return `${repoBase(conn)}/issues`;
 }
 function issueNotFoundMessage(conn, number) {
 	return `Issue #${String(number)} not found in ${conn.repository}`;
@@ -1286,18 +1294,12 @@ z.object({
 	created: z.string()
 });
 z.array(z.unknown());
-function repoBase$1(conn) {
-	return `${conn.serverUrl}/api/v1/repos/${conn.repository}`;
-}
-function authHeaders$1(conn) {
-	return { Authorization: `token ${conn.token}` };
-}
 function branchNotFoundMessage(conn, branch) {
 	return `Branch ${branch} not found in ${conn.repository}`;
 }
 async function getBranchHeadSha(executor, conn, branch) {
-	const url = `${repoBase$1(conn)}/branches/${encodeURIComponent(branch)}`;
-	const res = await executor.fetch(url, { headers: authHeaders$1(conn) });
+	const url = `${repoBase(conn)}/branches/${encodeURIComponent(branch)}`;
+	const res = await executor.fetch(url, { headers: authHeaders(conn) });
 	if (!res.ok) await throwForgejoFailure(res, {
 		verb: "read branch",
 		resource: branch
@@ -1307,8 +1309,8 @@ async function getBranchHeadSha(executor, conn, branch) {
 	return parsed.data.commit.id;
 }
 async function branchExists(executor, conn, branch) {
-	const url = `${repoBase$1(conn)}/branches/${encodeURIComponent(branch)}`;
-	const res = await executor.fetch(url, { headers: authHeaders$1(conn) });
+	const url = `${repoBase(conn)}/branches/${encodeURIComponent(branch)}`;
+	const res = await executor.fetch(url, { headers: authHeaders(conn) });
 	if (res.status === 404) return false;
 	if (!res.ok) await throwForgejoFailure(res, {
 		verb: "check branch",
@@ -1441,17 +1443,69 @@ async function readPollChecks(fetcher, conn, sha) {
 		return { failureDetail: describeError(error) };
 	}
 }
+async function settleChecks(fetcher, conn, poll, round) {
+	const { timeoutMs, intervalMs, sleep, now } = poll;
+	const startedAt = now();
+	const elapsed = () => now() - startedAt;
+	let consecutiveFailures = 0;
+	let lastFailureDetail;
+	let lastGoodChecks;
+	let previousSettledContexts = null;
+	for (;;) {
+		const sha = round.sha();
+		const { checks, failureDetail } = await readPollChecks(fetcher, conn, sha);
+		if (failureDetail !== void 0) lastFailureDetail = failureDetail;
+		if (checks === void 0) {
+			consecutiveFailures += 1;
+			if (consecutiveFailures >= 3) return round.report(EMPTY_CHECKS, {
+				exit: "retry-budget",
+				elapsed,
+				failureDetail: lastFailureDetail
+			});
+		} else {
+			consecutiveFailures = 0;
+			lastGoodChecks = checks;
+			pushDisagreementNotice(round.notices, sha, checks);
+			if (isSettled(checks)) {
+				const contexts = new Set(checks.contexts.map((check) => check.context));
+				if (previousSettledContexts !== null && previousSettledContexts.size === contexts.size && [...previousSettledContexts].every((context) => contexts.has(context))) return round.report(checks, {
+					exit: "settled",
+					elapsed
+				});
+				previousSettledContexts = contexts;
+			} else previousSettledContexts = null;
+		}
+		if (elapsed() >= timeoutMs) return round.report(lastGoodChecks ?? EMPTY_CHECKS, {
+			exit: "timeout",
+			elapsed
+		});
+		await sleep(intervalMs);
+		if (round.afterSleep !== void 0) {
+			const after = await round.afterSleep(sha, elapsed);
+			if (after !== "retry" && after !== "next") return after.done;
+		}
+	}
+}
+function renderCheckLine(check) {
+	const parts = [check.state, check.context];
+	if (check.description !== null) parts.push(check.description);
+	let line = parts.join(" -- ");
+	if (check.verdict === "red" && check.targetUrl !== null) line += ` (${check.targetUrl})`;
+	return line;
+}
 //#endregion
-//#region src/poll-timings.ts
-const DEFAULT_TIMEOUT_MS = 12e5;
-const DEFAULT_INTERVAL_MS = 15e3;
-const MIN_INTERVAL_MS = 5e3;
+//#region ../cli-kit/src/env-override.ts
 function envMsOverride(raw, productionMs) {
 	if (raw === void 0) return productionMs;
 	const parsed = Number(raw.trim());
 	if (!Number.isSafeInteger(parsed) || parsed <= 0) return productionMs;
 	return Math.min(parsed, productionMs);
 }
+//#endregion
+//#region src/poll-timings.ts
+const DEFAULT_TIMEOUT_MS = 12e5;
+const DEFAULT_INTERVAL_MS = 15e3;
+const MIN_INTERVAL_MS = 5e3;
 function resolvePollTimings(options) {
 	const timeoutMs = options.timeout !== void 0 ? parseDuration(options.timeout, "--timeout") : DEFAULT_TIMEOUT_MS;
 	const requestedIntervalMs = options.interval !== void 0 ? parseDuration(options.interval, "--interval") : DEFAULT_INTERVAL_MS;
@@ -1528,47 +1582,23 @@ function buildReport$1(target, checks, ctx, extras = {}) {
 	return report;
 }
 async function waitForSettledChecks$1(fetcher, target, notices, poll) {
-	const { timeoutMs, intervalMs, sleep, now } = poll;
-	const startedAt = now();
-	let consecutiveFailures = 0;
-	let lastFailureDetail;
-	let lastGoodChecks;
-	let previousSettledContexts = null;
-	for (;;) {
-		const sha = target.sha;
-		const { checks, failureDetail } = await readPollChecks(fetcher, target.conn, sha);
-		if (failureDetail !== void 0) lastFailureDetail = failureDetail;
-		if (checks === void 0) {
-			consecutiveFailures += 1;
-			if (consecutiveFailures >= 3) return buildReport$1(target, EMPTY_CHECKS, {
+	return settleChecks(fetcher, target.conn, poll, {
+		sha: () => target.sha,
+		notices,
+		report: (checks, extras) => {
+			const extrasForReport = {};
+			if (extras.exit === "timeout") extrasForReport.statusOverride = "timeout";
+			else if (extras.exit === "retry-budget") {
+				extrasForReport.statusOverride = "unparseable";
+				if (extras.failureDetail !== void 0) extrasForReport.detailOverride = extras.failureDetail;
+			}
+			return buildReport$1(target, checks, {
 				notices,
 				waited: true,
-				elapsedMs: now() - startedAt
-			}, {
-				statusOverride: "unparseable",
-				detailOverride: lastFailureDetail
-			});
-		} else {
-			consecutiveFailures = 0;
-			lastGoodChecks = checks;
-			pushDisagreementNotice(notices, sha, checks);
-			if (isSettled(checks)) {
-				const contexts = new Set(checks.contexts.map((check) => check.context));
-				if (previousSettledContexts !== null && previousSettledContexts.size === contexts.size && [...previousSettledContexts].every((context) => contexts.has(context))) return buildReport$1(target, checks, {
-					notices,
-					waited: true,
-					elapsedMs: now() - startedAt
-				});
-				previousSettledContexts = contexts;
-			} else previousSettledContexts = null;
+				elapsedMs: extras.elapsed()
+			}, extrasForReport);
 		}
-		if (now() - startedAt >= timeoutMs) return buildReport$1(target, lastGoodChecks ?? EMPTY_CHECKS, {
-			notices,
-			waited: true,
-			elapsedMs: now() - startedAt
-		}, { statusOverride: "timeout" });
-		await sleep(intervalMs);
-	}
+	});
 }
 async function runCommitStatus(fetcher, options) {
 	const timings = options.wait === true ? resolvePollTimings(options) : void 0;
@@ -1588,13 +1618,7 @@ async function runCommitStatus(fetcher, options) {
 	});
 }
 function renderCommitStatus(report) {
-	const lines = report.checks.map((check) => {
-		const parts = [check.state, check.context];
-		if (check.description !== null) parts.push(check.description);
-		let line = parts.join(" -- ");
-		if (check.verdict === "red" && check.targetUrl !== null) line += ` (${check.targetUrl})`;
-		return line;
-	});
+	const lines = report.checks.map(renderCheckLine);
 	const shortSha = FULL_SHA.test(report.sha) ? report.sha.slice(0, 12) : report.sha;
 	const redCount = report.checks.filter((c) => c.verdict === "red").length;
 	const pendingCount = report.checks.filter((c) => c.verdict === "pending").length;
@@ -1664,6 +1688,16 @@ const commitStatusCommand = defineCommand({
 	}
 });
 //#endregion
+//#region ../forgejo/src/fetcher.ts
+const LONG_FETCH_TIMEOUT_MS = 6e5;
+function morePagesFollow(res, pageLength, received, pageSize) {
+	if (pageLength === 0) return false;
+	const raw = res.headers.get("x-total-count")?.trim() ?? "";
+	const total = raw === "" ? NaN : Number(raw);
+	if (!Number.isSafeInteger(total) || total < 0) return pageLength >= pageSize;
+	return received < total;
+}
+//#endregion
 //#region ../forgejo/src/label-provisioning.ts
 const LabelSchema = z.object({
 	id: z.number(),
@@ -1673,12 +1707,12 @@ const LabelSchema = z.object({
 	exclusive: z.boolean().optional()
 });
 const LabelListSchema = z.array(LabelSchema);
-const LABELS_PAGE_SIZE = 100;
+const LABELS_PAGE_SIZE = 50;
 const LABELS_MAX_PAGES = 20;
 async function fetchAllForgejoLabels(executor, conn) {
 	const labels = [];
 	for (let page = 1; page <= LABELS_MAX_PAGES; page++) {
-		const res = await executor.fetch(`${conn.serverUrl}/api/v1/repos/${conn.repository}/labels?limit=${String(LABELS_PAGE_SIZE)}&page=${String(page)}`, { headers: authHeaders$2(conn) });
+		const res = await executor.fetch(`${conn.serverUrl}/api/v1/repos/${conn.repository}/labels?limit=${String(LABELS_PAGE_SIZE)}&page=${String(page)}`, { headers: authHeaders(conn) });
 		if (!res.ok) await throwForgejoFailure(res, {
 			verb: "list labels",
 			resource: conn.repository
@@ -1686,7 +1720,7 @@ async function fetchAllForgejoLabels(executor, conn) {
 		const parsed = LabelListSchema.safeParse(await res.json());
 		if (!parsed.success) throw new UnexpectedError(`Unexpected label-list response: ${parsed.error.message}`);
 		labels.push(...parsed.data);
-		if (parsed.data.length < LABELS_PAGE_SIZE) break;
+		if (!morePagesFollow(res, parsed.data.length, labels.length, LABELS_PAGE_SIZE)) break;
 	}
 	return labels;
 }
@@ -1702,6 +1736,17 @@ async function resolveLabelIds(executor, conn, names) {
 		return match.id;
 	});
 }
+function isRetiringExpired(spec, today) {
+	return today > spec.until;
+}
+function retiringAsLabelSpec(spec) {
+	return {
+		name: spec.name,
+		color: spec.color,
+		description: spec.description,
+		exclusive: false
+	};
+}
 const LabelSpecSchema = z.strictObject({
 	name: z.string().min(1),
 	color: z.string().regex(/^#[0-9a-fA-F]{6}$/),
@@ -1751,13 +1796,14 @@ function labelScope(name) {
 	const slash = name.indexOf("/");
 	return slash === -1 ? null : name.slice(0, slash + 1);
 }
-function staleLabelNames(specs, live) {
+function staleLabelNames(specs, live, retiring = []) {
 	const owned = /* @__PURE__ */ new Set();
 	for (const spec of specs) {
 		const scope = labelScope(spec.name);
 		if (scope !== null) owned.add(scope);
 	}
 	const wanted = new Set(specs.map((spec) => spec.name));
+	for (const spec of retiring) wanted.add(spec.name);
 	const stale = [];
 	for (const name of live) {
 		if (wanted.has(name)) continue;
@@ -1818,7 +1864,7 @@ async function ensureForgejoLabels(executor, conn, specs) {
 async function deleteForgejoLabel(executor, conn, id) {
 	const res = await executor.fetch(`${conn.serverUrl}/api/v1/repos/${conn.repository}/labels/${String(id)}`, {
 		method: "DELETE",
-		headers: authHeaders$2(conn)
+		headers: authHeaders(conn)
 	}, { idempotent: true });
 	if (!res.ok) await throwForgejoFailure(res, {
 		verb: "delete label",
@@ -1871,7 +1917,7 @@ function normalizeIssue(raw) {
 	};
 }
 async function getForgejoIssue(executor, conn, number) {
-	const res = await executor.fetch(`${issuesBase(conn)}/${String(number)}`, { headers: authHeaders$2(conn) });
+	const res = await executor.fetch(`${issuesBase(conn)}/${String(number)}`, { headers: authHeaders(conn) });
 	if (!res.ok) await throwForgejoFailure(res, {
 		verb: "get issue",
 		resource: `#${String(number)}`
@@ -1895,12 +1941,15 @@ function issueListParams(type, query) {
 	return params;
 }
 async function fetchIssueListPage(executor, conn, params) {
-	const res = await executor.fetch(`${issuesBase(conn)}?${params.toString()}`, { headers: authHeaders$2(conn) });
+	const res = await executor.fetch(`${issuesBase(conn)}?${params.toString()}`, { headers: authHeaders(conn) });
 	if (!res.ok) await throwForgejoFailure(res, {
 		verb: "list issues",
 		resource: conn.repository
 	}, repoNotFoundMessage(conn));
-	return parseIssueListOrThrow(await res.json());
+	return {
+		raw: parseIssueListOrThrow(await res.json()),
+		res
+	};
 }
 function normalizeDetailedIssues(raw, type) {
 	const normalized = raw.map(normalizeIssue);
@@ -1911,7 +1960,7 @@ const DETAILED_LIST_MAX_PAGES = 20;
 async function listForgejoIssuesDetailedPaged(executor, conn, query, options) {
 	const issues = [];
 	for (let page = 1; page <= DETAILED_LIST_MAX_PAGES; page++) {
-		const raw = await fetchIssueListPage(executor, conn, issueListParams(query.type, {
+		const { raw } = await fetchIssueListPage(executor, conn, issueListParams(query.type, {
 			...query,
 			limit: DETAILED_LIST_PAGE_SIZE,
 			page
@@ -1926,6 +1975,29 @@ async function listForgejoIssuesDetailedPaged(executor, conn, query, options) {
 	}
 	return issues;
 }
+async function listOpenObjectsWithLabel(executor, conn, label) {
+	const objects = [];
+	for (let page = 1; page <= DETAILED_LIST_MAX_PAGES; page++) {
+		const { raw } = await fetchIssueListPage(executor, conn, issueListParams("all", {
+			state: "open",
+			label,
+			limit: DETAILED_LIST_PAGE_SIZE,
+			page
+		}));
+		for (const issue of raw.map(normalizeIssue)) {
+			if (!issue.labels.includes(label)) continue;
+			objects.push({
+				number: issue.number,
+				kind: issue.isPullRequest ? "pull" : "issue",
+				title: issue.title,
+				url: issue.url
+			});
+		}
+		if (raw.length === 0) break;
+		if (page === DETAILED_LIST_MAX_PAGES) log.warn(`Open-object listing on ${conn.repository} hit the ${String(DETAILED_LIST_MAX_PAGES)}-page cap without an empty page; results may be truncated`);
+	}
+	return objects;
+}
 const USER_REPOS_PAGE_SIZE = 50;
 const USER_REPOS_MAX_PAGES = 20;
 const UserRepoSchema = z.object({
@@ -2046,24 +2118,77 @@ function outcomeFromAudit(conn, specs, audit, lists) {
 		...lists
 	};
 }
+async function checkPruneCandidate(fetcher, conn, name) {
+	let objects;
+	try {
+		objects = await listOpenObjectsWithLabel(fetcher, conn, name);
+	} catch (error) {
+		return {
+			ok: false,
+			reason: `could not check open objects: ${describeError(error)}`,
+			objects: []
+		};
+	}
+	if (objects.length === 0) return { ok: true };
+	return {
+		ok: false,
+		reason: `on ${String(objects.length)} open object(s)`,
+		objects
+	};
+}
 async function syncOneRepo(params) {
-	const { fetcher, conn, specs, mode, prune, allowedPruneNames, resolveTargetSpecs } = params;
+	const { fetcher, conn, specs, mode, prune, allowedPruneNames, resolveTargetSpecs, retiring, today } = params;
 	const target = resolveTargetSpecs === void 0 ? {
 		specs,
 		omitted: [],
 		aliasNames: []
 	} : await resolveTargetSpecs(conn, specs);
-	const audit = await auditForgejoLabels(fetcher, conn, target.specs);
-	const stale = staleLabelNames(specs, audit.labelIds.keys()).filter((name) => !target.aliasNames.includes(name));
-	const pruneCandidates = prune ? [...target.omitted, ...stale].filter((name) => audit.labelIds.has(name) && (allowedPruneNames === void 0 || allowedPruneNames.includes(name))) : [];
+	const retiringNames = new Set(retiring.map((spec) => spec.name));
+	const fullAudit = await auditForgejoLabels(fetcher, conn, [...target.specs, ...retiring.map(retiringAsLabelSpec)]);
+	const presentRetiring = retiring.filter((spec) => fullAudit.labelIds.has(spec.name));
+	const audit = {
+		...fullAudit,
+		missing: fullAudit.missing.filter((name) => !retiringNames.has(name))
+	};
+	const stale = staleLabelNames(specs, audit.labelIds.keys(), retiring).filter((name) => !target.aliasNames.includes(name));
+	const expiredRetiring = presentRetiring.filter((spec) => isRetiringExpired(spec, today)).map((spec) => spec.name);
+	const pruneCandidates = prune ? [
+		...target.omitted,
+		...stale,
+		...expiredRetiring
+	].filter((name) => audit.labelIds.has(name) && (allowedPruneNames === void 0 || allowedPruneNames.includes(name))) : [];
+	const pruned = [];
+	const refused = [];
+	for (const name of pruneCandidates) {
+		const verdict = await checkPruneCandidate(fetcher, conn, name);
+		if (verdict.ok) {
+			pruned.push(name);
+			continue;
+		}
+		refused.push({
+			name,
+			reason: verdict.reason,
+			objects: verdict.objects
+		});
+	}
+	const retiringReports = [];
+	for (const spec of presentRetiring) retiringReports.push({
+		name: spec.name,
+		replacement: spec.replacement,
+		until: spec.until,
+		expired: isRetiringExpired(spec, today),
+		openObjects: await listOpenObjectsWithLabel(fetcher, conn, spec.name)
+	});
 	const outcome = outcomeFromAudit(conn, target.specs, audit, {
 		omitted: target.omitted,
-		pruned: pruneCandidates,
-		stale: prune ? stale.filter((name) => !pruneCandidates.includes(name)) : stale
+		pruned,
+		stale: prune ? stale.filter((name) => !pruneCandidates.includes(name)) : stale,
+		retiring: retiringReports,
+		refused
 	});
 	if (mode === "apply") {
-		if (outcome.created.length > 0 || outcome.updated.length > 0) await ensureForgejoLabels(fetcher, conn, target.specs);
-		for (const name of pruneCandidates) {
+		if (outcome.created.length > 0 || outcome.updated.length > 0) await ensureForgejoLabels(fetcher, conn, [...target.specs, ...presentRetiring.map(retiringAsLabelSpec)]);
+		for (const name of pruned) {
 			const id = audit.labelIds.get(name);
 			if (id === void 0) throw new UnexpectedError(`Prune candidate "${name}" had no known id after the audit`);
 			await deleteForgejoLabel(fetcher, conn, id);
@@ -2073,6 +2198,9 @@ async function syncOneRepo(params) {
 }
 async function syncLabelSet(params) {
 	const { fetcher, targets, specs, setName, mode, contained, prune, pruneAllowlist } = params;
+	const retiring = params.retiring ?? [];
+	const today = params.today ?? "";
+	if (retiring.length > 0 && params.today === void 0) throw new UnexpectedError("syncLabelSet was given retiring label specs but no `today` to compare their expiry against: an expired entry is a prune candidate, and a guessed date could delete a name whose retirement window is still open.");
 	const specList = [...specs];
 	const repos = [];
 	const failures = [];
@@ -2085,7 +2213,9 @@ async function syncLabelSet(params) {
 			mode,
 			prune: prune === true,
 			allowedPruneNames,
-			resolveTargetSpecs: params.resolveTargetSpecs
+			resolveTargetSpecs: params.resolveTargetSpecs,
+			retiring,
+			today
 		};
 		if (contained !== true) {
 			repos.push(await syncOneRepo(syncOneRepoParams));
@@ -2118,6 +2248,11 @@ function syncSummaryLines(result) {
 		if (repo.omitted.length > 0) actions.push(`omitted (repo declares its own priority vocabulary): ${repo.omitted.join(", ")}`);
 		if (repo.pruned.length > 0) actions.push(`${verb}prune: ${repo.pruned.join(", ")}`);
 		if (repo.stale.length > 0) actions.push(`stale (present, not in this set): ${repo.stale.join(", ")}`);
+		for (const refusal of repo.refused) {
+			const objects = refusal.objects.map((object) => `#${String(object.number)} (${object.kind}) ${object.title}`).join(", ");
+			actions.push(`refused to prune ${refusal.name}: ${refusal.reason}${objects === "" ? "" : ` (${objects})`}`);
+		}
+		for (const retiring of repo.retiring) actions.push(`retiring ${retiring.name}: replaced by ${retiring.replacement}, prunable after ${retiring.until}${retiring.expired ? " (expired)" : ""}; ${String(retiring.openObjects.length)} open object(s)`);
 		if (actions.length === 0) {
 			repoLines.push(`${repo.repository}: up to date (${String(repo.unchanged.length)} unchanged)`);
 			continue;
@@ -2257,7 +2392,7 @@ const syncCommand = defineCommand({
 		},
 		json: {
 			type: "boolean",
-			description: "Emit one JSON document: set, mode (apply | check | dry-run), repos ([{repository, created, updated, unchanged, omitted, stale}], every field but repository a list of label names), failures ([{repository, error}]; always present, filled only under --fleet), drifted. drifted is true when any label is missing or drifted, and sets the exit code only under --check."
+			description: "Emit one JSON document: set, mode (apply | check | dry-run), repos ([{repository, created, updated, unchanged, omitted, stale, retiring, refused}], every field but repository and those two a list of label names; retiring and refused are always empty here, since this command never prunes), failures ([{repository, error}]; always present, filled only under --fleet), drifted. drifted is true when any label is missing or drifted, and sets the exit code only under --check."
 		}
 	},
 	async run({ args, rawArgs }) {
@@ -2301,9 +2436,6 @@ const labelsCommand = defineCommand({
 	}
 });
 //#endregion
-//#region ../forgejo/src/fetcher.ts
-const LONG_FETCH_TIMEOUT_MS = 6e5;
-//#endregion
 //#region ../forgejo/src/releases.ts
 const SETTLE_ATTEMPTS = 4;
 const SETTLE_BASE_DELAY_MS = 2e3;
@@ -2814,7 +2946,7 @@ const AuthenticatedUserSchema = z.object({
 });
 async function getAuthenticatedUser(executor, conn, signal = null) {
 	const res = await executor.fetch(`${conn.serverUrl}/api/v1/user`, {
-		headers: authHeaders$2(conn),
+		headers: authHeaders(conn),
 		signal
 	});
 	if (!res.ok) return {
@@ -2891,7 +3023,7 @@ async function paginate(executor, conn, endpoint, verb, extract) {
 		}));
 		const items = extract(await res.json());
 		all.push(...items);
-		if (items.length < PAGE_LIMIT) break;
+		if (!morePagesFollow(res, items.length, all.length, PAGE_LIMIT)) break;
 		if (page === 101) throw new UnexpectedError(`${endpoint} still returns full pages after ${String(MAX_PAGES)} pages; refusing to report a prefix of it`);
 	}
 	return all;
@@ -3360,11 +3492,6 @@ const ciLogCommand = defineCommand({
 });
 //#endregion
 //#region src/ci-runs.ts
-function parseLimit$2(raw) {
-	const limit = Number(raw);
-	if (!Number.isInteger(limit) || limit < 1) throw new FatalError(`Invalid --limit "${raw}" (expected a positive integer).`);
-	return limit;
-}
 function resolveRunsRef(ref, pr) {
 	if (ref !== void 0 && pr !== void 0) throw new FatalError("--ref and --pr are the same filter -- give one of them (--pr 273 for a pull request's own runs, --ref main for a branch's).");
 	if (pr !== void 0) {
@@ -3389,7 +3516,7 @@ function resolveRunsRef(ref, pr) {
 	};
 }
 async function runCiRuns(fetcher, options) {
-	const limit = parseLimit$2(options.limit);
+	const limit = parseLimitFlag(options.limit);
 	const resolved = resolveRunsRef(options.ref, options.pr);
 	const conn = requireForgejoTarget(options.cwd, resolveIssueTarget(resolved.target, options.repo), "ci:runs is Forgejo-only -- gh run list already serves GitHub, first-class. Use that instead.");
 	rootLogger.debug(`ci:runs repository=${conn.repository} limit=${String(limit)}`);
@@ -3634,12 +3761,6 @@ const BranchEntrySchema = z.object({
 });
 const BRANCHES_PAGE_SIZE = 50;
 const DEFAULT_MAX_PAGES = 20;
-function repoBase(conn) {
-	return `${conn.serverUrl}/api/v1/repos/${conn.repository}`;
-}
-function authHeaders(conn) {
-	return { Authorization: `token ${conn.token}` };
-}
 async function listBranches(executor, conn, options = {}) {
 	const signal = options.signal;
 	const maxPages = options.maxPages ?? DEFAULT_MAX_PAGES;
@@ -3869,14 +3990,14 @@ async function listForgejoComments(executor, conn, number, options = {}) {
 			limit: String(COMMENTS_PAGE_SIZE),
 			page: String(page)
 		});
-		const res = await executor.fetch(`${issuesBase(conn)}/${String(number)}/comments?${params.toString()}`, { headers: authHeaders$2(conn) });
+		const res = await executor.fetch(`${issuesBase(conn)}/${String(number)}/comments?${params.toString()}`, { headers: authHeaders(conn) });
 		if (!res.ok) await throwForgejoFailure(res, {
 			verb: "list comments",
 			resource: `#${String(number)}`
 		}, issueNotFoundMessage(conn, number));
 		const parsed = parseCommentListOrThrow(await res.json());
 		comments.push(...parsed.map(normalizeComment));
-		if (parsed.length < COMMENTS_PAGE_SIZE) break;
+		if (!morePagesFollow(res, parsed.length, comments.length, COMMENTS_PAGE_SIZE)) break;
 		if (page === COMMENTS_MAX_PAGES) {
 			log.warn(`Comment listing for #${String(number)} hit the ${String(COMMENTS_MAX_PAGES)}-page cap; results may be truncated`);
 			options.onPageCap?.();
@@ -4352,7 +4473,7 @@ function parseState$1(state) {
 	if (state === "open" || state === "closed" || state === "all") return state;
 	throw new InvalidListQueryError("state", state);
 }
-function parseLimit$1(raw) {
+function parseLimit(raw) {
 	const limit = Number(raw);
 	if (!Number.isInteger(limit) || limit <= 0) throw new InvalidListQueryError("limit", raw);
 	return limit;
@@ -4365,7 +4486,7 @@ async function listIssues(resolve, request) {
 	const label = normalizeLabel(request.label);
 	const query = {
 		state: parseState$1(request.state),
-		limit: parseLimit$1(request.limit),
+		limit: parseLimit(request.limit),
 		...label === void 0 ? {} : { label }
 	};
 	const { api } = resolve(parseRepoTarget(request.repo));
@@ -4847,7 +4968,7 @@ async function removeForgejoIssueLabel(executor, conn, number, name, labelIds) {
 	const id = await resolveLabelId(executor, conn, name, labelIds);
 	const res = await executor.fetch(`${issuesBase(conn)}/${String(number)}/labels/${String(id)}`, {
 		method: "DELETE",
-		headers: authHeaders$2(conn)
+		headers: authHeaders(conn)
 	}, { idempotent: true });
 	if (!res.ok) await throwForgejoFailure(res, {
 		verb: "remove label",
@@ -5511,75 +5632,45 @@ function buildReport(detail, checks, ctx, extras = {}) {
 	return report;
 }
 async function waitForSettledChecks(fetcher, target, baseline, notices, poll) {
-	const { timeoutMs, intervalMs, sleep, now } = poll;
-	const startedAt = now();
 	let currentDetail = target.detail;
-	let consecutiveFailures = 0;
 	let consecutiveDetailFailures = 0;
-	let lastFailureDetail;
-	let lastGoodChecks;
-	let previousSettledContexts = null;
-	for (;;) {
-		const sha = currentDetail.head.sha;
-		const { checks, failureDetail } = await readPollChecks(fetcher, target.conn, sha);
-		if (failureDetail !== void 0) lastFailureDetail = failureDetail;
-		if (checks === void 0) {
-			consecutiveFailures += 1;
-			if (consecutiveFailures >= 3) return buildReport(currentDetail, EMPTY_CHECKS, {
-				target,
-				baseline,
-				notices,
-				waited: true,
-				elapsedMs: now() - startedAt
-			}, {
-				statusOverride: "unparseable",
-				detailOverride: lastFailureDetail
-			});
-		} else {
-			consecutiveFailures = 0;
-			lastGoodChecks = checks;
-			pushDisagreementNotice(notices, sha, checks);
-			if (isSettled(checks)) {
-				const contexts = new Set(checks.contexts.map((check) => check.context));
-				if (previousSettledContexts !== null && previousSettledContexts.size === contexts.size && [...previousSettledContexts].every((context) => contexts.has(context))) return buildReport(currentDetail, checks, {
-					target,
-					baseline,
-					notices,
-					waited: true,
-					elapsedMs: now() - startedAt
-				});
-				previousSettledContexts = contexts;
-			} else previousSettledContexts = null;
-		}
-		if (now() - startedAt >= timeoutMs) return buildReport(currentDetail, lastGoodChecks ?? EMPTY_CHECKS, {
-			target,
-			baseline,
-			notices,
-			waited: true,
-			elapsedMs: now() - startedAt
-		}, { statusOverride: "timeout" });
-		await sleep(intervalMs);
-		let nextDetail;
-		try {
-			nextDetail = await getForgejoPrDetail(fetcher, target.conn, target.prNumber);
-			consecutiveDetailFailures = 0;
-		} catch (error) {
-			consecutiveDetailFailures += 1;
-			if (consecutiveDetailFailures >= 3) throw error;
-			continue;
+	const reportFor = (detail, checks, elapsedMs, extras = {}) => buildReport(detail, checks, {
+		target,
+		baseline,
+		notices,
+		waited: true,
+		elapsedMs
+	}, extras);
+	return settleChecks(fetcher, target.conn, poll, {
+		sha: () => currentDetail.head.sha,
+		notices,
+		report: (checks, extras) => {
+			const reportExtras = {};
+			if (extras.exit === "timeout") reportExtras.statusOverride = "timeout";
+			else if (extras.exit === "retry-budget") {
+				reportExtras.statusOverride = "unparseable";
+				if (extras.failureDetail !== void 0) reportExtras.detailOverride = extras.failureDetail;
+			}
+			return reportFor(currentDetail, checks, extras.elapsed(), reportExtras);
+		},
+		afterSleep: async (sha, elapsed) => {
+			let nextDetail;
+			try {
+				nextDetail = await getForgejoPrDetail(fetcher, target.conn, target.prNumber);
+				consecutiveDetailFailures = 0;
+			} catch (error) {
+				consecutiveDetailFailures += 1;
+				if (consecutiveDetailFailures >= 3) throw error;
+				return "retry";
+			}
+			if (nextDetail.head.sha !== sha) return { done: reportFor(nextDetail, EMPTY_CHECKS, elapsed(), {
+				statusOverride: "head-moved",
+				previousHeadSha: sha
+			}) };
+			currentDetail = nextDetail;
+			return "next";
 		}
-		if (nextDetail.head.sha !== sha) return buildReport(nextDetail, EMPTY_CHECKS, {
-			target,
-			baseline,
-			notices,
-			waited: true,
-			elapsedMs: now() - startedAt
-		}, {
-			statusOverride: "head-moved",
-			previousHeadSha: sha
-		});
-		currentDetail = nextDetail;
-	}
+	});
 }
 async function runPrChecks(fetcher, options) {
 	const timings = options.wait === true ? resolvePollTimings(options) : void 0;
@@ -5612,13 +5703,7 @@ function baselineClause(report) {
 	return `${String(redChecks.length)} red, ${String(preexistingCount)} of them already red on ` + report.baseline.ref;
 }
 function renderPrChecks(report) {
-	const lines = report.checks.map((check) => {
-		const parts = [check.state, check.context];
-		if (check.description !== null) parts.push(check.description);
-		let line = parts.join(" -- ");
-		if (check.verdict === "red" && check.targetUrl !== null) line += ` (${check.targetUrl})`;
-		return line;
-	});
+	const lines = report.checks.map((check) => renderCheckLine(check));
 	const summaryParts = [`head ${report.headSha.slice(0, 12)}: ${report.status}`];
 	const clause = baselineClause(report);
 	if (clause !== null) summaryParts.push(clause);
@@ -6533,14 +6618,9 @@ function parseState(state) {
 	if (state === "open" || state === "closed" || state === "all") return state;
 	throw new FatalError(`Invalid --state "${state}" (expected open, closed, or all).`);
 }
-function parseLimit(raw) {
-	const limit = Number(raw);
-	if (!Number.isInteger(limit) || limit < 1) throw new FatalError(`Invalid --limit "${raw}" (expected a positive integer).`);
-	return limit;
-}
 async function runPrList(fetcher, options) {
 	const state = parseState(options.state);
-	const limit = parseLimit(options.limit);
+	const limit = parseLimitFlag(options.limit);
 	rootLogger.debug(`pr:list state=${state} limit=${String(limit)}`);
 	const conn = requireForgejoTarget(options.cwd, parseRepoTarget(options.repo), "pr:list is Forgejo-only -- gh pr list already serves GitHub, first-class. Use that instead.");
 	const notices = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bensandee/forgejo-cli",
-  "version": "0.5.5",
+  "version": "0.6.0",
   "description": "bst-fj: Forgejo API commands without the rest of bst",
   "license": "MIT",
   "repository": {