@bensandee/forgejo-cli 0.4.3 → 0.5.0

package/README.md

@@ -55,6 +55,7 @@ command takes `--json`, which prints exactly one JSON document, failures include
 | `pr:files`          | List the files a pull request changes                                                                                                                                                                                |
 | `pr:merge`          | Merge an open, non-draft, mergeable PR pinned to the head it read; refuses closed, draft, conflicted, unconfirmed or non-green checks (zero statuses included) unless `--ignore-checks`; `--delete-branch` is opt-in |
 | `pr:ready`          | Mark a draft pull request ready, dropping one `WIP:` prefix or taking `--title`, and confirm the forge no longer reports a draft                                                                                     |
+| `pr:close`          | Close an open pull request, optionally posting `--comment`/`--comment-file` first; reports an already-closed or merged PR without writing; refuses an issue                                                          |
 | `pr:retarget`       | Repoint an open pull request at a new base branch, confirm the forge took it, and report its mergeability as advice                                                                                                  |
 | `workflow:dispatch` | Dispatch a workflow with `--workflow`, `--ref` and repeatable `--input`; takes `--repo owner/repo`, not a URL                                                                                                        |
 | `ci:runs`           | List a repository's workflow runs with their jobs, filtered by workflow, ref, pull request, head SHA or status                                                                                                       |

package/dist/bin.mjs

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync, writeSync } from "node:fs";
-import * as path$1 from "node:path";
-import path from "node:path";
+import path, * as path$1 from "node:path";
 import { parseArgs, parseEnv } from "node:util";
 import { FatalError, TransientError, UnexpectedError, describeError, redact, redact as redact$1 } from "@bensandee/common";
 import { z } from "zod";
@@ -163,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.4.3",
+	version: "0.5.0",
 	description: "bst-fj: Forgejo API commands without the rest of bst",
 	license: "MIT",
 	repository: {
@@ -2337,8 +2336,8 @@ async function createRelease(executor, conn, tag, options = {}) {
 	const url = `${conn.serverUrl}/api/v1/repos/${conn.repository}/releases`;
 	const payload = {
 		tag_name: tag,
-		name: tag,
-		body: `Published ${tag}`,
+		name: options.name ?? tag,
+		body: options.body ?? `Published ${tag}`,
 		prerelease: options.prerelease ?? false
 	};
 	if (options.target) payload["target_commitish"] = options.target;
@@ -2434,7 +2433,9 @@ async function ensureRelease(executor, conn, tag, options = {}) {
 		try {
 			await createRelease(executor, conn, tag, {
 				target: options.target,
-				prerelease: options.prerelease
+				prerelease: options.prerelease,
+				name: options.name,
+				body: options.body
 			});
 		} catch (error) {
 			const raced = await getReleaseByTag(executor, conn, tag);
@@ -2458,6 +2459,8 @@ async function ensureRelease(executor, conn, tag, options = {}) {
 	const recreated = options.target ? await recreateTagViaApi(executor, conn, tag, {
 		target: options.target,
 		prerelease: options.prerelease,
+		name: options.name,
+		body: options.body,
 		current,
 		attempts,
 		baseDelayMs
@@ -2469,7 +2472,7 @@ async function ensureRelease(executor, conn, tag, options = {}) {
 	throw new TransientError(`Release for ${tag} never got a real (non-epoch) created date after ${String(attempts)} attempts. This is an intermittent Forgejo bug: a pushed tag's date settles asynchronously and a racing release creation freezes it at the Unix epoch (1969/1970). ` + (options.target ? `Recreating the tag via the API did not help -- investigate the server or upgrade Forgejo.` : `Pass the release tag's target commit so the tag can be recreated, or retry the release.`));
 }
 async function recreateTagViaApi(executor, conn, tag, opts) {
-	const { target, prerelease, current, attempts, baseDelayMs } = opts;
+	const { target, prerelease, name, body, current, attempts, baseDelayMs } = opts;
 	log.warn(`Release for ${tag} stayed epoch-dated -- recreating the tag via the API so Forgejo stamps a real date (the tag becomes lightweight)`);
 	if (current) await deleteRelease(executor, conn, current.id);
 	await deleteTag(executor, conn, tag);
@@ -2477,7 +2480,9 @@ async function recreateTagViaApi(executor, conn, tag, opts) {
 		try {
 			await createRelease(executor, conn, tag, {
 				target,
-				prerelease
+				prerelease,
+				name,
+				body
 			});
 		} catch (error) {
 			if (attempt >= attempts) throw new TransientError(`Release for ${tag} was deleted to repair its epoch date, but recreating it from ${target} failed: ${describeError(error)}. The tag no longer exists on the server -- re-push it (or re-run the release) to restore it.`);
@@ -2501,6 +2506,24 @@ async function settleBackoff(attempt, baseDelayMs) {
 	const delay = Math.min(baseDelayMs * 2 ** (attempt - 1), SETTLE_MAX_DELAY_MS);
 	await new Promise((resolve) => setTimeout(resolve, delay));
 }
+z.looseObject({
+	id: z.number(),
+	tag_name: z.string(),
+	name: z.string().nullish(),
+	target_commitish: z.string().nullish(),
+	created_at: z.string().nullish(),
+	html_url: z.string().nullish(),
+	draft: z.boolean().optional(),
+	prerelease: z.boolean().optional(),
+	assets: z.array(z.unknown()).nullish()
+});
+z.looseObject({
+	name: z.string(),
+	commit: z.looseObject({
+		sha: z.string(),
+		created: z.string().nullish()
+	})
+});
 //#endregion
 //#region src/commands/release-create.ts
 const releaseCreateCommand = defineCommand({
@@ -5040,6 +5063,9 @@ var EmptyCommentError = class extends FatalError {
 		super("The comment resolved to empty text.");
 	}
 };
+function rejectEmptyComment(comment) {
+	if (comment !== void 0 && comment.trim() === "") throw new EmptyCommentError();
+}
 var PullRequestStateError = class extends FatalError {
 	number;
 	action;
@@ -5049,20 +5075,35 @@ var PullRequestStateError = class extends FatalError {
 		this.action = action;
 	}
 };
+var NotAPullRequestError = class extends FatalError {
+	number;
+	constructor(number) {
+		super(`#${String(number)} is an issue, not a pull request.`);
+		this.number = number;
+	}
+};
+var StateNotTakenError = class extends FatalError {
+	number;
+	expected;
+	actual;
+	constructor(number, expected, actual) {
+		super(`The forge did not change #${String(number)}: it is still ${actual}, not ${expected}.`);
+		this.number = number;
+		this.expected = expected;
+		this.actual = actual;
+	}
+};
 const TARGET_STATE = {
 	close: "closed",
 	reopen: "open"
 };
-async function setIssueState(resolve, request) {
-	const ref = parseIssueRef(request.ref);
-	const number = requireIssueNumber(ref);
-	if (request.comment !== void 0 && request.comment.trim() === "") throw new EmptyCommentError();
-	const commentGiven = request.comment !== void 0;
-	const { api } = resolve(resolveIssueTarget(ref.target, request.repo));
+async function changeState(api, number, request, subject) {
 	const before = await api.get(number);
-	if (before.isPullRequest) throw new PullRequestStateError(number, request.action);
+	if (subject === "issue" && before.isPullRequest) throw new PullRequestStateError(number, request.action);
+	if (subject === "pull-request" && !before.isPullRequest) throw new NotAPullRequestError(number);
+	const commentGiven = request.comment !== void 0;
 	const targetState = TARGET_STATE[request.action];
-	const buildResult = (url, current, changed, posted) => ({
+	const buildResult = (url, current, changed, posted, merged) => ({
 		number,
 		url,
 		action: request.action,
@@ -5071,20 +5112,32 @@ async function setIssueState(resolve, request) {
 			current
 		},
 		changed,
-		...commentGiven ? { comment: { posted } } : {}
+		...commentGiven ? { comment: { posted } } : {},
+		...merged === void 0 ? {} : { merged }
 	});
-	if (before.state === targetState) return buildResult(before.url, before.state, false, false);
+	if (before.state === targetState) {
+		const merged = subject === "pull-request" ? (await api.pullRequest(number)).merged : void 0;
+		return buildResult(before.url, before.state, false, false, merged);
+	}
 	if (request.dryRun) return buildResult(before.url, targetState, true, true);
 	if (commentGiven) await api.addComment(number, request.comment ?? "");
 	let after;
 	try {
 		after = await api.setState(number, targetState);
+		if (after.state !== targetState) throw new StateNotTakenError(number, targetState, after.state);
 	} catch (error) {
 		if (commentGiven && error instanceof Error) error.message = `The comment on #${String(number)} was already posted; a retry will duplicate it. ` + error.message;
 		throw error;
 	}
 	return buildResult(after.url, after.state, true, true);
 }
+async function setIssueState(resolve, request) {
+	const ref = parseIssueRef(request.ref);
+	const number = requireIssueNumber(ref);
+	rejectEmptyComment(request.comment);
+	const { api } = resolve(resolveIssueTarget(ref.target, request.repo));
+	return changeState(api, number, request, "issue");
+}
 const PAST_TENSE = {
 	close: "Closed",
 	reopen: "Reopened"
@@ -5163,10 +5216,13 @@ function defineIssueStateCommand(action) {
 			} catch (error) {
 				if (error instanceof IssueNumberRequiredError) throw new FatalError(describeIssueNumberRequired(`bst-fj ${name} 273`));
 				if (error instanceof EmptyCommentError) throw new FatalError(describeEmptyComment(flags));
-				if (error instanceof PullRequestStateError) throw new FatalError(describePullRequestState(error, {
-					command: `bst-fj ${name}`,
-					advice: "Use the forge UI to change a pull request's state."
-				}));
+				if (error instanceof PullRequestStateError) {
+					const advice = action === "close" ? `Run \`bst-fj pr:close ${String(error.number)}\` to close it.` : "Use the forge UI to change a pull request's state.";
+					throw new FatalError(describePullRequestState(error, {
+						command: `bst-fj ${name}`,
+						advice
+					}));
+				}
 				throw error;
 			}
 		}
@@ -5636,6 +5692,95 @@ const prChecksCommand = defineCommand({
 	}
 });
 //#endregion
+//#region ../forgejo/src/pr-close.ts
+async function closePullRequest(api, request) {
+	rejectEmptyComment(request.comment);
+	return changeState(api, request.number, {
+		action: "close",
+		dryRun: request.dryRun,
+		...request.comment === void 0 ? {} : { comment: request.comment }
+	}, "pull-request");
+}
+function formatPrClose(result, dryRun) {
+	if (result.changed) return formatIssueState(result, dryRun);
+	const what = result.merged === true ? "merged" : "closed";
+	const lines = [`#${String(result.number)} is already ${what} -- nothing to close. (${result.url})`];
+	if (result.comment !== void 0) lines.push("  comment: not posted (pull request was already closed)");
+	return lines.join("\n");
+}
+const PR_CLOSE_JSON_HELP = "Emit one JSON document: number, url, action (close), state ({previous, current}), changed, merged? (present only when the pull request was already closed), comment? ({posted}; present only when a comment was given).";
+//#endregion
+//#region ../forgejo/src/pr-number.ts
+function parsePrNumber(raw) {
+	const value = Number(raw);
+	if (!/^\d+$/.test(raw) || !Number.isSafeInteger(value) || value < 1) throw new FatalError(`Invalid pull request number "${raw}" (expected a positive integer).`);
+	return value;
+}
+//#endregion
+//#region src/commands/pr-close.ts
+const prCloseCommand = defineCommand({
+	meta: {
+		name: "pr:close",
+		description: "Close an open pull request, optionally posting a comment first. A pull request already closed or merged is reported, not an error, and no comment is posted. An issue is refused (Forgejo-only; use gh pr close on GitHub)"
+	},
+	args: {
+		number: {
+			type: "positional",
+			required: true,
+			description: "Pull request number"
+		},
+		comment: {
+			type: "string",
+			description: "Post this comment before writing state"
+		},
+		"comment-file": {
+			type: "string",
+			description: "Read the comment from a file ('-' for stdin)"
+		},
+		repo: {
+			type: "string",
+			description: "Target repository URL (default: this repo's origin)"
+		},
+		"dry-run": {
+			type: "boolean",
+			description: "Report what would change, mutate nothing"
+		},
+		json: {
+			type: "boolean",
+			description: PR_CLOSE_JSON_HELP
+		},
+		verbose: {
+			type: "boolean",
+			description: "Emit detailed debug output"
+		}
+	},
+	async run({ args }) {
+		const out = createCliOutput(args.json === true);
+		const flags = {
+			text: "--comment",
+			file: "--comment-file"
+		};
+		const number = parsePrNumber(args.number);
+		const comment = readBodySource(args.comment ?? void 0, args["comment-file"] ?? void 0, { flags });
+		const conn = requireForgejoTargetFromRepo(process.cwd(), args.repo ?? void 0, "pr:close is Forgejo-only -- use gh pr close <n> on GitHub.");
+		const dryRun = args["dry-run"] === true;
+		try {
+			const result = await closePullRequest(forgejoIssueApi(cliFetcher(), conn), {
+				number,
+				dryRun,
+				...comment === void 0 ? {} : { comment }
+			});
+			out.json(result);
+			out.text(formatPrClose(result, dryRun));
+			if (dryRun && comment !== void 0 && result.comment?.posted === true) out.text(`[dry-run] Comment that would be posted:\n${comment}`);
+		} catch (error) {
+			if (error instanceof EmptyCommentError) throw new FatalError(describeEmptyComment(flags));
+			if (error instanceof NotAPullRequestError) throw new FatalError(`#${String(error.number)} is an issue, not a pull request -- pr:close refuses to write issue state. Use \`bst-fj issue:close ${String(error.number)}\` to close it.`);
+			throw error;
+		}
+	}
+});
+//#endregion
 //#region ../forgejo/src/closing-refs.ts
 const CLOSING_REF = /(?:^|[\s([])(clos(?:e|es|ed)|fix(?:es|ed)?|resolv(?:e|es|ed))(?::[ \t]*|[ \t]+)((?:[\w.-]+\/[\w.-]+)?#\d+)(?![\w-])/gim;
 function capitalize(word) {
@@ -6315,13 +6460,6 @@ async function readPrFilesPage(executor, conn, prNumber, page, limit) {
 	};
 }
 //#endregion
-//#region ../forgejo/src/pr-number.ts
-function parsePrNumber(raw) {
-	const value = Number(raw);
-	if (!/^\d+$/.test(raw) || !Number.isSafeInteger(value) || value < 1) throw new FatalError(`Invalid pull request number "${raw}" (expected a positive integer).`);
-	return value;
-}
-//#endregion
 //#region src/pr-files.ts
 function runPrFiles(fetcher, options) {
 	const number = parsePrNumber(options.number);
@@ -6565,36 +6703,52 @@ z.object({
 	})
 });
 //#endregion
-//#region src/pr-merge.ts
-const METHODS = [
+//#region ../forgejo/src/pr-merge-run.ts
+const MERGE_METHODS = [
 	"merge",
 	"rebase",
 	"squash"
 ];
 const RECHECK_DELAY_MS = 2e3;
-function parseMethod(raw) {
-	if (raw === void 0) return "merge";
-	const method = METHODS.find((candidate) => candidate === raw);
-	if (method === void 0) throw new FatalError(`Invalid --method "${raw}" (expected one of: ${METHODS.join(", ")}).`);
-	return method;
+const MIN_SHA_PREFIX = 7;
+function sleepDefault(ms) {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
 }
-async function runPrMerge(fetcher, options) {
-	const number = parsePrNumber(options.number);
-	const method = parseMethod(options.method);
-	const conn = requireForgejoTarget(options.cwd, parseRepoTarget(options.repo), "pr:merge is Forgejo-only -- use gh pr merge on GitHub.");
+function headMatches(expected, actual) {
+	const want = expected.trim().toLowerCase();
+	return want.length >= MIN_SHA_PREFIX && actual.toLowerCase().startsWith(want);
+}
+async function runPrMergeCore(fetcher, conn, number, options = {}) {
 	const pr = `PR #${String(number)}`;
+	const method = options.method ?? "merge";
+	const expected = options.expectedHeadSha;
+	const moved = (headSha) => expected !== void 0 && !headMatches(expected, headSha);
 	const confirmation = await confirmMergeable(fetcher, conn, number, {
 		delayMs: RECHECK_DELAY_MS,
-		sleep: options.sleep ?? sleep,
-		settleOnFirstRead: (gate) => !gate.open || gate.draft
+		sleep: options.sleep ?? sleepDefault,
+		settleOnFirstRead: (gate) => !gate.open || gate.draft || moved(gate.headSha)
 	});
 	const { gate, verdict } = confirmation;
-	if (!gate.open) throw new FatalError(`Refusing to merge ${pr}: it is closed.`);
-	if (gate.draft) throw new FatalError(`Refusing to merge ${pr}: it is a draft.`);
-	if (verdict === "conflicted") throw new FatalError(`Refusing to merge ${pr}: it has conflicts. ${confirmation.evidence ?? ""}`.trimEnd());
-	if (verdict === "unconfirmed") throw new FatalError(`Refusing to merge ${pr}: the forge could not confirm it is mergeable. ${confirmation.evidence ?? ""}`.trimEnd());
-	const checks = classifyBaseStatus(await readCommitChecks(fetcher, conn, gate.headSha));
-	if (checks !== "green" && !options.ignoreChecks) throw new FatalError(`Refusing to merge ${pr}: its checks at ${gate.headSha} are ${checks}, not green. Pass --ignore-checks to merge anyway.`);
+	const refuse = (why) => ({
+		kind: "refused",
+		reason: `Refusing to merge ${pr}: ${why}`
+	});
+	if (!gate.open) return refuse("it is closed.");
+	if (gate.draft) return refuse("it is a draft.");
+	if (options.refuseEmpty === true && (gate.headSha === gate.mergeBase || gate.changedFiles === 0)) return refuse("its diff against its base is empty, so its branch is left alone.");
+	if (expected !== void 0 && moved(gate.headSha)) return refuse(`its head is ${gate.headSha}, not the approved ${expected}.`);
+	if (verdict === "conflicted") return refuse(`it has conflicts. ${confirmation.evidence ?? ""}`.trimEnd());
+	if (verdict === "unconfirmed") return refuse(`the forge could not confirm it is mergeable. ${confirmation.evidence ?? ""}`.trimEnd());
+	const read = await readCommitChecks(fetcher, conn, gate.headSha);
+	const checks = classifyBaseStatus(read);
+	const skippedOnly = read.parsed && read.contexts.length > 0 && read.contexts.every((context) => context.verdict === "skipped");
+	if (!(checks === "green" || options.ignoreChecks === true || (checks === "no-status" || skippedOnly) && options.allowNoStatus === true)) return {
+		kind: "refused",
+		reason: `Refusing to merge ${pr}: its checks at ${gate.headSha} are ${checks}, not green.`,
+		checks
+	};
 	const result = {
 		number,
 		merged: false,
@@ -6603,17 +6757,47 @@ async function runPrMerge(fetcher, options) {
 		verdict,
 		checks
 	};
-	if (options.dryRun) return result;
+	if (options.dryRun === true) return {
+		kind: "ok",
+		result
+	};
 	await mergePr(fetcher, conn, number, {
 		method,
-		deleteBranch: options.deleteBranch,
+		deleteBranch: options.deleteBranch ?? false,
 		expectedHeadSha: gate.headSha
 	});
 	return {
-		...result,
-		merged: true
+		kind: "ok",
+		result: {
+			...result,
+			merged: true
+		}
 	};
 }
+//#endregion
+//#region src/pr-merge.ts
+function parseMethod(raw) {
+	if (raw === void 0) return "merge";
+	const method = MERGE_METHODS.find((candidate) => candidate === raw);
+	if (method === void 0) throw new FatalError(`Invalid --method "${raw}" (expected one of: ${MERGE_METHODS.join(", ")}).`);
+	return method;
+}
+async function runPrMerge(fetcher, options) {
+	const number = parsePrNumber(options.number);
+	const method = parseMethod(options.method);
+	const outcome = await runPrMergeCore(fetcher, requireForgejoTarget(options.cwd, parseRepoTarget(options.repo), "pr:merge is Forgejo-only -- use gh pr merge on GitHub."), number, {
+		method,
+		deleteBranch: options.deleteBranch,
+		ignoreChecks: options.ignoreChecks,
+		dryRun: options.dryRun,
+		sleep: options.sleep ?? sleep
+	});
+	if (outcome.kind === "refused") {
+		const hint = outcome.checks === void 0 ? "" : " Pass --ignore-checks to merge anyway.";
+		throw new FatalError(`${outcome.reason}${hint}`);
+	}
+	return outcome.result;
+}
 function renderPrMerge(result) {
 	const what = `PR #${String(result.number)} (${result.method}) at ${result.headSha.slice(0, 12)}, checks ${result.checks}`;
 	return result.merged ? `Merged ${what}.` : `Dry run: would merge ${what}.`;
@@ -6807,6 +6991,7 @@ function renderPrReady(result) {
 //#region src/registry-pr.ts
 const prSubCommands = {
 	"pr:checks": prChecksCommand,
+	"pr:close": prCloseCommand,
 	"pr:create": prCreateCommand,
 	"pr:files": prFilesCommand,
 	"pr:list": prListCommand,

package/package.json

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