@bensandee/forgejo-cli 0.3.2 → 0.4.0

package/README.md

@@ -1,7 +1,7 @@
 # @bensandee/forgejo-cli
 
 `bst-fj`: the Forgejo API commands, without the rest of `bst`. Most of these commands used to ship on
-`@bensandee/tooling`'s `bst` bin; `issue:*`, `pr:create` and `pr:update` still do, and run the same code.
+`@bensandee/tooling`'s `bst` bin; `issue:*`, `pr:create`, `pr:update`, `pr:ready` and `pr:retarget` still do, and run the same code.
 
 ## Installation
 
@@ -54,10 +54,12 @@ command takes `--json`, which prints exactly one JSON document, failures include
 | `branch:delete`     | Delete a branch through the API; reports the forge's reason when it refuses                                                                                                                                          |
 | `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: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                                                                                                       |
 | `ci:log`            | Print one workflow job's whole log, or with `--grep` only the lines whose text matches                                                                                                                               |
 
 Zero posted statuses reads as `no-status`, never as green. Every command is Forgejo-only: on
-GitHub, use `gh`. The `issue:*`, `pr:create` and `pr:update` commands take the same flags and print the
+GitHub, use `gh`. The `issue:*`, `pr:create`, `pr:update`, `pr:ready` and `pr:retarget` commands take the same flags and print the
 same `--json` documents as `bst`'s, except that `issue:create` has no config default for assignees.

package/dist/bin.mjs

@@ -245,7 +245,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.3.2",
+	version: "0.4.0",
 	description: "bst-fj: Forgejo API commands without the rest of bst",
 	license: "MIT",
 	repository: {
@@ -1936,6 +1936,26 @@ async function getBranchHeadSha(executor, conn, branch) {
 	if (!parsed.success) throw new UnexpectedError(`Unexpected branch response: ${parsed.error.message}`);
 	return parsed.data.commit.id;
 }
+/**
+* Whether the forge knows this branch at all -- the probe a caller runs before it asks the forge
+* to point a pull request at a branch.
+*
+* {@link getBranchHeadSha} cannot serve as this probe: its 404 goes through `throwForgejoFailure`
+* and throws `ForgeAccessError`, the same class a 403 throws, so a caller catching it would read a
+* token that cannot see the repository as a branch that was never pushed. Only a 404 answers
+* `false` here; every other non-ok status throws, because "I cannot tell" is never "it is
+* missing".
+*/
+async function branchExists(executor, conn, branch) {
+	const url = `${repoBase$1(conn)}/branches/${encodeURIComponent(branch)}`;
+	const res = await executor.fetch(url, { headers: authHeaders$1(conn) });
+	if (res.status === 404) return false;
+	if (!res.ok) await throwForgejoFailure(res, {
+		verb: "check branch",
+		resource: branch
+	}, branchNotFoundMessage(conn, branch));
+	return true;
+}
 //#endregion
 //#region ../cli-kit/src/git.ts
 const BRANCH_REF_PREFIX = "refs/heads/";
@@ -2029,6 +2049,15 @@ function resolveRepoUrl(cwd) {
 	return resolveRepoUrlFrom(() => readOriginUrl(cwd), () => readPackageRepositoryUrl(cwd));
 }
 /**
+* The connection a `--repo` value names. Every command in this bin needs both halves -- parse the
+* value, then resolve it against the working directory -- and this module already owns the second
+* and already imports the module the first lives in, so the pair is composed once here rather than
+* repeated per command.
+*/
+function requireForgejoTargetFromRepo(cwd, repo, githubRefusal, env = process.env) {
+	return requireForgejoTarget(cwd, parseRepoTarget(repo), githubRefusal, env);
+}
+/**
 * The Forgejo connection a command acts on. An explicit target (from an issue URL or `--repo`)
 * wins over the working directory. `githubRefusal` is the command's own sentence for a github.com
 * repository, which owes the reader the `gh` alternative. The environment settles the connection
@@ -5094,7 +5123,8 @@ const CommentResponseSchema = z.object({
 	user: z.object({ login: z.string() }).nullish(),
 	created_at: z.string(),
 	updated_at: z.string().nullish(),
-	html_url: z.string().nullish()
+	html_url: z.string().nullish(),
+	assets: AttachmentListSchema.nullish()
 });
 const CommentListSchema = z.array(CommentResponseSchema);
 function parseCommentOrThrow(raw) {
@@ -5114,7 +5144,8 @@ function normalizeComment(raw) {
 		createdAt: raw.created_at,
 		updatedAt: raw.updated_at ?? raw.created_at,
 		body: raw.body ?? "",
-		...raw.html_url === void 0 || raw.html_url === null ? {} : { url: raw.html_url }
+		...raw.html_url === void 0 || raw.html_url === null ? {} : { url: raw.html_url },
+		attachments: (raw.assets ?? []).map(normalizeAttachment)
 	};
 }
 /**
@@ -5172,17 +5203,6 @@ const RepoCommentResponseSchema = CommentResponseSchema.extend({
 	updated_at: z.string().nullish()
 });
 z.array(RepoCommentResponseSchema);
-/** List a comment's attachments. */
-async function listForgejoCommentAssets(executor, conn, commentId) {
-	const res = await executor.fetch(`${issuesBase(conn)}/comments/${String(commentId)}/assets`, { headers: authHeaders$2(conn) });
-	if (!res.ok) await throwForgejoFailure(res, {
-		verb: "list comment attachments",
-		resource: `#${String(commentId)}`
-	}, `Comment #${String(commentId)} not found in ${conn.repository}`);
-	const parsed = AttachmentListSchema.safeParse(await res.json());
-	if (!parsed.success) throw new UnexpectedError(`Unexpected attachment-list response: ${parsed.error.message}`);
-	return parsed.data.map(normalizeAttachment);
-}
 /** Post a new comment on an issue. */
 async function addForgejoComment(executor, conn, number, body) {
 	const res = await executor.fetch(`${issuesBase(conn)}/${String(number)}/comments`, {
@@ -5472,6 +5492,63 @@ function normalizePrDetail(data) {
 async function getForgejoPrDetail(executor, conn, prNumber) {
 	return normalizePrDetail(await readPrField(executor, conn, prNumber, PrDetailSchema, "detail"));
 }
+const PrEditStateSchema = z.object({
+	state: z.string(),
+	merged: z.boolean(),
+	draft: z.boolean(),
+	title: z.string(),
+	head: z.object({ ref: z.string() }),
+	base: z.object({ ref: z.string() }),
+	mergeable: z.boolean().nullish(),
+	html_url: z.string().optional()
+});
+/**
+* Read a pull request's edit state in one `/pulls/<n>` GET -- the read both editors run before
+* they write, and the one they run again to confirm the write took.
+*
+* `url` prefers the forge's own `html_url` because an instance that serves it knows its real web
+* route (a reverse-proxied path included), and falls back to {@link prWebUrl} when it does not.
+* `mergeable` stays tri-state for {@link PrDetail}'s reason: absent is "still computing", not
+* "conflicted".
+*/
+async function getPrEditState(executor, conn, prNumber) {
+	const parsed = await readPrField(executor, conn, prNumber, PrEditStateSchema, "edit state");
+	return {
+		state: parsed.state,
+		merged: parsed.merged,
+		draft: parsed.draft,
+		title: parsed.title,
+		head: parsed.head.ref,
+		base: parsed.base.ref,
+		mergeable: parsed.mergeable ?? null,
+		url: parsed.html_url ?? prWebUrl(conn, prNumber)
+	};
+}
+/**
+* Repoint a pull request at a new base branch with a PATCH carrying `base` and nothing else.
+*
+* Its own function rather than another field on {@link UpdatePrOptions}: that interface is the
+* title-and-body pair whose whole contract is "an omitted key is left alone", and widening it to
+* carry a branch name would let a caller that only means to fix a title move a pull request's
+* base by accident. The caller confirms the write by re-reading -- Forgejo accepts an unknown
+* `EditPullRequestOption` field silently, so a PATCH that answered 200 is not proof the base
+* moved.
+*/
+async function retargetPr(executor, conn, prNumber, base) {
+	const url = `${conn.serverUrl}/api/v1/repos/${conn.repository}/pulls/${String(prNumber)}`;
+	const res = await executor.fetch(url, {
+		method: "PATCH",
+		headers: {
+			Authorization: `token ${conn.token}`,
+			"Content-Type": "application/json"
+		},
+		body: JSON.stringify({ base })
+	}, { idempotent: true });
+	if (!res.ok) await throwForgejoFailure(res, {
+		verb: "retarget PR",
+		resource: `#${String(prNumber)}`
+	});
+}
 const PrContentSchema = z.object({
 	title: z.string(),
 	body: z.string().nullish()
@@ -6212,6 +6289,12 @@ function resolveTargetPath(outDir, name, taken) {
 * login page with a 200 status. Verifying the length is what stops that login page
 * from landing on disk named `plan.md`, where a reader would then act on it.
 * Nothing is written until the bytes check out.
+*
+* Exported because a caller that wants the bytes in memory rather than on disk -- one
+* collecting an issue's images for a container -- needs exactly this check and has no way
+* to write it without the same reasoning about the login page. It lives here, beside its
+* only other caller, rather than in a new module: `packages/forgejo/src` sits at its
+* crowding ceiling.
 */
 async function downloadAttachment(fetcher, token, attachment) {
 	const res = await fetcher.fetch(attachment.downloadUrl, { headers: { Authorization: `token ${token}` } }, { timeoutMs: LONG_FETCH_TIMEOUT_MS });
@@ -6235,8 +6318,7 @@ async function downloadIssueAttachments(resolve, request) {
 	const files = request.files ?? diskFiles;
 	const issue = await getForgejoIssue(fetcher, conn, number);
 	const comments = await listForgejoComments(fetcher, conn, number);
-	const commentAttachments = await Promise.all(comments.map((comment) => listForgejoCommentAssets(fetcher, conn, comment.id)));
-	const attachments = [...issue.attachments, ...commentAttachments.flat()];
+	const attachments = [...issue.attachments, ...comments.flatMap((comment) => comment.attachments)];
 	const outDir = request.outDir;
 	const taken = /* @__PURE__ */ new Set();
 	const downloaded = [];
@@ -8099,6 +8181,20 @@ function forgejoPrHost(fetcher, conn) {
 		}
 	};
 }
+/**
+* The Forgejo {@link PrEditHost}, over the API calls in `pr.ts` and `repo.ts`. Its `ready` is a
+* title-only PATCH and never a body write: the body is the author's text, and the draft flag has
+* no PATCH field of its own on this forge.
+*/
+function forgejoPrEditHost(fetcher, conn) {
+	return {
+		wipTitles: true,
+		readLive: (number) => getPrEditState(fetcher, conn, number),
+		branchExists: (name) => branchExists(fetcher, conn, name),
+		setBase: (number, base) => retargetPr(fetcher, conn, number, base),
+		ready: (number, write) => updatePr(fetcher, conn, number, { title: write.title })
+	};
+}
 //#endregion
 //#region src/git.ts
 /** Exit codes reported when this module ends a child itself, following the shell's convention. */
@@ -8331,16 +8427,22 @@ async function listPrFiles(executor, conn, prNumber, options) {
 	};
 }
 //#endregion
-//#region src/pr-files.ts
+//#region ../forgejo/src/pr-number.ts
 /**
-* `bst-fj pr:files`: the files a pull request changes, over `@bensandee/forgejo/pr-files`.
-* Forgejo-only; `gh pr diff --name-only` already serves GitHub.
+* The one parser for a pull request number given as text, shared by every bin's positional so a
+* malformed number refuses the same way whether a person or a script typed it.
 */
 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
+/**
+* `bst-fj pr:files`: the files a pull request changes, over `@bensandee/forgejo/pr-files`.
+* Forgejo-only; `gh pr diff --name-only` already serves GitHub.
+*/
 /** List the files a pull request changes. */
 function runPrFiles(fetcher, options) {
 	const number = parsePrNumber(options.number);
@@ -8685,16 +8787,237 @@ function renderPrMerge(result) {
 	return result.merged ? `Merged ${what}.` : `Dry run: would merge ${what}.`;
 }
 //#endregion
+//#region src/commands/pr-merge.ts
+const prMergeCommand = defineCommand({
+	meta: {
+		name: "pr:merge",
+		description: "Merge an open, non-draft pull request the forge confirms is mergeable and whose checks are green, pinned to the head SHA it read (Forgejo-only; use gh pr merge on GitHub)"
+	},
+	args: {
+		number: {
+			type: "positional",
+			required: true,
+			description: "Pull request number"
+		},
+		method: {
+			type: "string",
+			description: "Merge method: merge, rebase or squash (default: merge)"
+		},
+		"delete-branch": {
+			type: "boolean",
+			description: "Delete the head branch after the merge"
+		},
+		"ignore-checks": {
+			type: "boolean",
+			description: "Merge even when the head's combined status is not green"
+		},
+		"dry-run": {
+			type: "boolean",
+			description: "Run every check and report, but do not merge"
+		},
+		repo: {
+			type: "string",
+			description: "Repository URL (default: this repo)"
+		},
+		json: {
+			type: "boolean",
+			description: "Emit one JSON document: number, merged, method (merge | rebase | squash), headSha, verdict (mergeable), checks (green | red | pending | no-status | unparseable). merged is false on a dry run; a refusal is an error, never this document."
+		},
+		verbose: {
+			type: "boolean",
+			description: "Emit detailed debug output"
+		}
+	},
+	async run({ args }) {
+		const out = createCliOutput(args.json === true);
+		const result = await runPrMerge(cliFetcher(), {
+			cwd: process.cwd(),
+			number: args.number,
+			method: args.method ?? void 0,
+			deleteBranch: args["delete-branch"] === true,
+			ignoreChecks: args["ignore-checks"] === true,
+			dryRun: args["dry-run"] === true,
+			repo: args.repo ?? void 0
+		});
+		out.json(result);
+		out.text(renderPrMerge(result));
+	}
+});
+//#endregion
+//#region ../forgejo/src/pr-edit.ts
+/**
+* The two pull-request editing engines, forge-generic: what a base change and a ready write check,
+* send, and confirm. Each one drives a {@link PrEditHost}, so the sequence is written once and only
+* the writes differ per forge -- the refusals and the confirming re-read are the parts a person
+* relies on, and they must not be re-derived on each side of the seam.
+*
+* Engines and renderers share this module because every importer of either is the same command: a
+* renderer kept apart would be a second module for the same four callers.
+*/
+/** The wait before the one mergeability re-read after a retarget; both bins pass it. */
+const MERGEABLE_RECHECK_DELAY_MS = 2e3;
+/** What both forges call an editable pull request. One predicate, so the two engines cannot
+* disagree about it and a caller cannot read "open" as its own looser thing. */
+function isOpen(live) {
+	return live.state === "open" && live.merged === false;
+}
+function notOpenMessage(prNumber, live) {
+	const what = live.merged ? "merged" : live.state;
+	return `Pull request #${String(prNumber)} is ${what}, so it has no base or draft state left to change. Reopen it first if this work is still live.`;
+}
+/**
+* Point an open pull request at a new base branch, then prove the forge took it.
+*
+* The re-read is the whole point of the command: a forge that does not implement the base field
+* answers the PATCH with 200 and changes nothing, so a report built from the request would claim a
+* move that never happened. `mergeable` rides along as advice only and never decides the outcome --
+* it is tri-state on both forges and a pull request whose base just moved is being recomputed by
+* definition -- so a `false` earns exactly one more read after a wait, and `null` and `true` are
+* taken as final.
+*/
+async function runPrRetarget(host, options) {
+	const live = await host.readLive(options.number);
+	if (!isOpen(live)) throw new FatalError(notOpenMessage(options.number, live));
+	if (options.base === live.head) throw new FatalError(`Pull request #${String(options.number)} cannot target its own head branch "${options.base}" -- choose a branch it is meant to merge into.`);
+	if (options.base === live.base) return {
+		action: "unchanged",
+		number: options.number,
+		url: live.url,
+		previousBase: live.base,
+		base: live.base,
+		head: live.head,
+		mergeable: live.mergeable,
+		dryRun: options.dryRun
+	};
+	if (!await host.branchExists(options.base)) throw new FatalError(`Branch "${options.base}" does not exist in this repository, so pull request #${String(options.number)} cannot target it -- push the branch, or pass a base the forge has.`);
+	if (options.dryRun) return {
+		action: "would-retarget",
+		number: options.number,
+		url: live.url,
+		previousBase: live.base,
+		base: options.base,
+		head: live.head,
+		mergeable: live.mergeable,
+		dryRun: true
+	};
+	await host.setBase(options.number, options.base);
+	const recheck = await host.readLive(options.number);
+	if (recheck.base !== options.base) throw new FatalError(`Pull request #${String(options.number)} still reports its base as "${recheck.base}" after the request to move it to "${options.base}" -- this forge accepted the field and ignored it, so change the base in its web interface.`);
+	let mergeable = recheck.mergeable;
+	if (mergeable === false) {
+		await options.sleep(options.recheckDelayMs);
+		mergeable = (await host.readLive(options.number)).mergeable;
+	}
+	return {
+		action: "retargeted",
+		number: options.number,
+		url: recheck.url,
+		previousBase: live.base,
+		base: options.base,
+		head: live.head,
+		mergeable,
+		dryRun: false
+	};
+}
+/**
+* Mark an open pull request ready, dropping its WIP marker or writing the title given.
+*
+* The draft is the forge's flag, never the title prefix: a prefix is how a title reads and a draft
+* is what the forge refuses to merge, and the two disagree on both forges. So the title is the
+* mechanism (it is the only lever Forgejo's PATCH has) and the flag is the question of whether
+* there is anything to do -- which is also why a successful write is re-read rather than trusted.
+* A draft whose title carries no marker this side recognises is refused rather than readied by
+* guessing at one: on that forge only the title can clear the flag, and an invented title is a
+* rewrite of someone's headline.
+*/
+async function runPrReady(host, options) {
+	const live = await host.readLive(options.number);
+	if (!isOpen(live)) throw new FatalError(notOpenMessage(options.number, live));
+	const given = options.title;
+	if (given !== void 0) {
+		if (given.trim() === "") throw new FatalError(`--title is empty -- pass the title to write, or omit --title to drop the WIP marker from pull request #${String(options.number)}'s current title.`);
+		if (hasWipPrefix(given)) {
+			const reason = host.wipTitles ? "which on this forge keeps the pull request a draft" : "so the pull request would still read as work in progress";
+			throw new FatalError(`--title ${JSON.stringify(given)} carries a WIP marker, ${reason} -- pass the title you want it to read without one.`);
+		}
+	}
+	const finalTitle = given ?? stripWipPrefix(live.title);
+	if (finalTitle.trim() === "") throw new FatalError(`Pull request #${String(options.number)} would be left with an empty title, which neither forge accepts -- pass --title with the title to write.`);
+	if (host.wipTitles && live.draft && given === void 0 && !hasWipPrefix(live.title)) throw new FatalError(`Pull request #${String(options.number)} is a draft and its title ${JSON.stringify(live.title)} carries no WIP marker this tool recognises, so there is nothing to strip -- pass --title "<title>" to write the title that clears the draft.`);
+	const titleChanged = finalTitle !== live.title;
+	if (!live.draft && !titleChanged) return {
+		action: "already-ready",
+		number: options.number,
+		url: live.url,
+		previousTitle: live.title,
+		title: live.title,
+		draft: live.draft,
+		dryRun: options.dryRun
+	};
+	if (options.dryRun) return {
+		action: live.draft ? "would-ready" : "would-retitle",
+		number: options.number,
+		url: live.url,
+		previousTitle: live.title,
+		title: finalTitle,
+		draft: live.draft,
+		dryRun: true
+	};
+	await host.ready(options.number, {
+		draft: live.draft,
+		title: finalTitle,
+		titleChanged
+	});
+	const recheck = await host.readLive(options.number);
+	if (recheck.draft) throw new FatalError(`Pull request #${String(options.number)} is still a draft after the title ${JSON.stringify(finalTitle)} was written -- its draft state is set by something other than the title, so clear it in the forge's interface.`);
+	return {
+		action: live.draft ? "readied" : "retitled",
+		number: options.number,
+		url: recheck.url,
+		previousTitle: live.title,
+		title: recheck.title,
+		draft: recheck.draft,
+		dryRun: false
+	};
+}
+const PR_RETARGET_JSON_HELP = "Emit one JSON document: action (retargeted | unchanged | would-retarget), number, url, previousBase, base, head, mergeable (true | false | null, advice only), dryRun; a refusal is an error, never this document.";
+const PR_READY_JSON_HELP = "Emit one JSON document: action (readied | retitled | already-ready | would-ready | would-retitle), number, url, previousTitle, title, draft, dryRun; a refusal is an error, never this document.";
+function mergeabilityLine(mergeable) {
+	if (mergeable === true) return "Mergeability: mergeable.";
+	if (mergeable === false) return "Mergeability: not mergeable -- advice, not a verdict.";
+	return "Mergeability: unknown -- the forge has not computed it.";
+}
+/** What happened to the base, and the mergeability reading as advice. */
+function renderPrRetarget(result) {
+	const number = `#${String(result.number)}`;
+	const lines = [];
+	if (result.action === "retargeted") lines.push(`Pull request ${number} now targets "${result.base}" (was "${result.previousBase}").`);
+	else if (result.action === "unchanged") lines.push(`Pull request ${number} already targets "${result.base}".`);
+	else lines.push(`Dry run: pull request ${number} would move from "${result.previousBase}" to "${result.base}".`);
+	lines.push(mergeabilityLine(result.mergeable));
+	return lines.join("\n");
+}
+/** What happened to the draft state and the title. */
+function renderPrReady(result) {
+	const number = `#${String(result.number)}`;
+	if (result.action === "readied") return `Pull request ${number} is no longer a draft, reading as "${result.title}".`;
+	if (result.action === "retitled") return `Pull request ${number} now reads "${result.title}".`;
+	if (result.action === "already-ready") return `Pull request ${number} is already ready and reads "${result.title}".`;
+	if (result.action === "would-ready") return `Dry run: pull request ${number} would stop being a draft, reading "${result.title}".`;
+	return `Dry run: pull request ${number} would read "${result.title}".`;
+}
+//#endregion
 //#region src/registry-pr.ts
 const prSubCommands = {
 	"pr:checks": prChecksCommand,
 	"pr:create": prCreateCommand,
 	"pr:files": prFilesCommand,
 	"pr:list": prListCommand,
-	"pr:merge": defineCommand({
+	"pr:merge": prMergeCommand,
+	"pr:ready": defineCommand({
 		meta: {
-			name: "pr:merge",
-			description: "Merge an open, non-draft pull request the forge confirms is mergeable and whose checks are green, pinned to the head SHA it read (Forgejo-only; use gh pr merge on GitHub)"
+			name: "pr:ready",
+			description: "Mark a draft pull request ready, dropping one WIP: prefix or taking --title, and confirm the forge no longer reports a draft (Forgejo-only; use gh pr ready on GitHub)"
 		},
 		args: {
 			number: {
@@ -8702,29 +9025,66 @@ const prSubCommands = {
 				required: true,
 				description: "Pull request number"
 			},
-			method: {
+			title: {
+				type: "string",
+				description: "Write this title instead of stripping the WIP prefix from the current one"
+			},
+			repo: {
 				type: "string",
-				description: "Merge method: merge, rebase or squash (default: merge)"
+				description: "Repository URL (default: this repo)"
 			},
-			"delete-branch": {
+			"dry-run": {
 				type: "boolean",
-				description: "Delete the head branch after the merge"
+				description: "Run every read and report, but do not write"
 			},
-			"ignore-checks": {
+			json: {
 				type: "boolean",
-				description: "Merge even when the head's combined status is not green"
+				description: PR_READY_JSON_HELP
 			},
-			"dry-run": {
+			verbose: {
 				type: "boolean",
-				description: "Run every check and report, but do not merge"
+				description: "Emit detailed debug output"
+			}
+		},
+		async run({ args }) {
+			const out = createCliOutput(args.json === true);
+			const conn = requireForgejoTargetFromRepo(process.cwd(), args.repo ?? void 0, "pr:ready is Forgejo-only -- use gh pr ready <n> on GitHub.");
+			const result = await runPrReady(forgejoPrEditHost(cliFetcher(), conn), {
+				number: parsePrNumber(args.number),
+				title: args.title ?? void 0,
+				dryRun: args["dry-run"] === true
+			});
+			out.json(result);
+			out.text(renderPrReady(result));
+		}
+	}),
+	"pr:retarget": defineCommand({
+		meta: {
+			name: "pr:retarget",
+			description: "Change an open pull request's base branch, confirm the forge took it, and report its mergeability as advice (Forgejo-only; use gh pr edit on GitHub)"
+		},
+		args: {
+			number: {
+				type: "positional",
+				required: true,
+				description: "Pull request number"
+			},
+			base: {
+				type: "string",
+				required: true,
+				description: "The branch to retarget the pull request onto"
 			},
 			repo: {
 				type: "string",
 				description: "Repository URL (default: this repo)"
 			},
+			"dry-run": {
+				type: "boolean",
+				description: "Run every read and report, but do not write"
+			},
 			json: {
 				type: "boolean",
-				description: "Emit one JSON document: number, merged, method (merge | rebase | squash), headSha, verdict (mergeable), checks (green | red | pending | no-status | unparseable). merged is false on a dry run; a refusal is an error, never this document."
+				description: PR_RETARGET_JSON_HELP
 			},
 			verbose: {
 				type: "boolean",
@@ -8733,17 +9093,16 @@ const prSubCommands = {
 		},
 		async run({ args }) {
 			const out = createCliOutput(args.json === true);
-			const result = await runPrMerge(cliFetcher(), {
-				cwd: process.cwd(),
-				number: args.number,
-				method: args.method ?? void 0,
-				deleteBranch: args["delete-branch"] === true,
-				ignoreChecks: args["ignore-checks"] === true,
+			const conn = requireForgejoTargetFromRepo(process.cwd(), args.repo ?? void 0, "pr:retarget is Forgejo-only -- use gh pr edit <n> --base <branch> on GitHub.");
+			const result = await runPrRetarget(forgejoPrEditHost(cliFetcher(), conn), {
+				number: parsePrNumber(args.number),
+				base: args.base,
 				dryRun: args["dry-run"] === true,
-				repo: args.repo ?? void 0
+				recheckDelayMs: MERGEABLE_RECHECK_DELAY_MS,
+				sleep
 			});
 			out.json(result);
-			out.text(renderPrMerge(result));
+			out.text(renderPrRetarget(result));
 		}
 	}),
 	"pr:update": defineCommand({
@@ -8766,7 +9125,7 @@ const prSubCommands = {
 			},
 			base: {
 				type: "string",
-				description: "Base branch to diff against (default: the repo's); never repoints the PR"
+				description: "Base branch to diff against (default: the repo's); never repoints the PR (pr:retarget does)"
 			},
 			"allow-unlink": {
 				type: "boolean",

package/package.json

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