@bensandee/forgejo-cli 0.2.0 → 0.3.0

package/README.md

@@ -55,6 +55,8 @@ 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 |
 | `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

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.2.0",
+	version: "0.3.0",
 	description: "bst-fj: Forgejo API commands without the rest of bst",
 	license: "MIT",
 	repository: {
@@ -1039,11 +1039,17 @@ function jsonDocumentWritten() {
 //#endregion
 //#region ../cli-kit/src/path-probe.ts
 /** The real {@link PathKind} probe the pre-run argument check uses. A path that exists but is not
-* a directory (a file, a socket) reads as `"file"`. */
+* a directory (a file, a socket) reads as `"file"`. A path stat cannot resolve at all -- a symlink
+* loop, an unsearchable parent -- reads as `"missing"`: `throwIfNoEntry` covers ENOENT and ENOTDIR
+* only, and a stat failure here would surface as a crash where the check owes a usage error. */
 function probeCliPath(value) {
-	const stat = statSync(value, { throwIfNoEntry: false });
-	if (stat === void 0) return "missing";
-	return stat.isDirectory() ? "directory" : "file";
+	try {
+		const stat = statSync(value, { throwIfNoEntry: false });
+		if (stat === void 0) return "missing";
+		return stat.isDirectory() ? "directory" : "file";
+	} catch {
+		return "missing";
+	}
 }
 //#endregion
 //#region ../cli-kit/src/run.ts
@@ -2325,7 +2331,7 @@ const commitStatusCommand = defineCommand({
 		},
 		json: {
 			type: "boolean",
-			description: "Emit the machine-readable report on stdout. Keys: sha, ref, repository, url, status (green | red | pending | no-status | unparseable | timeout), settled, combinedState, waited, elapsedMs, checks (each: context, name, state, verdict, description, targetUrl, updatedAt; description, targetUrl and updatedAt can be null), detail? (unparseable only). no-status means no check was posted and is never green"
+			description: "Emit one JSON document: sha, ref, repository, url, status (green | red | pending | no-status | unparseable | timeout), settled, combinedState, waited, elapsedMs, checks ([{context, name, state, verdict, description (or null), targetUrl (or null), updatedAt (or null)}]), detail? (unparseable only). no-status means no check was posted and is never green."
 		},
 		verbose: {
 			type: "boolean",
@@ -3080,7 +3086,7 @@ const listCommand$1 = defineCommand({
 		},
 		json: {
 			type: "boolean",
-			description: "Emit results as JSON instead of a human-readable list"
+			description: "Emit one JSON document: repository, labels ([{id, name, color?, description?, exclusive?}])."
 		}
 	},
 	async run({ args, rawArgs }) {
@@ -3134,7 +3140,7 @@ const syncCommand = defineCommand({
 		},
 		json: {
 			type: "boolean",
-			description: "Emit results as JSON instead of a human-readable summary. Keys: set, mode (apply | check | dry-run), repos (each: repository, created, updated, unchanged, omitted, stale), failures (each: repository, error), drifted (boolean; 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}], 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."
 		}
 	},
 	async run({ args, rawArgs }) {
@@ -3174,7 +3180,7 @@ const labelsCommand = defineCommand({
 	},
 	args: { json: {
 		type: "boolean",
-		description: "Emit results as JSON instead of a human-readable summary"
+		description: "Emit one JSON document; the keys are the subcommand's (see labels list --help and labels sync --help)."
 	} },
 	subCommands: {
 		list: listCommand$1,
@@ -3504,7 +3510,7 @@ const releaseCreateCommand = defineCommand({
 		},
 		json: {
 			type: "boolean",
-			description: "Emit the release result as JSON. Keys: status (created | exists | race | repaired), tag, target, prerelease (boolean), release ({ id, url }, where url can be null)"
+			description: "Emit one JSON document: status (created | exists | race | repaired), tag, target, prerelease, release ({id, url (or null)})."
 		}
 	},
 	async run({ args }) {
@@ -3697,7 +3703,7 @@ const setCommand = defineCommand({
 		},
 		json: {
 			type: "boolean",
-			description: "Emit results as JSON instead of a human-readable summary. Keys: status (set | would-set), name, repository. The secret value is never included"
+			description: "Emit one JSON document: status (set | would-set), name, repository. The secret value is never included."
 		}
 	},
 	async run({ args }) {
@@ -3726,7 +3732,7 @@ const listCommand = defineCommand({
 		},
 		json: {
 			type: "boolean",
-			description: "Emit results as JSON instead of a human-readable summary. Keys: repository, secrets (an array of secret names). Values are never returned"
+			description: "Emit one JSON document: repository, secrets (secret names). Values are never returned."
 		}
 	},
 	async run({ args }) {
@@ -3760,7 +3766,7 @@ const deleteCommand = defineCommand({
 		},
 		json: {
 			type: "boolean",
-			description: "Emit results as JSON instead of a human-readable summary. Keys: status (deleted | would-delete), name, repository"
+			description: "Emit one JSON document: status (deleted | would-delete), name, repository."
 		}
 	},
 	async run({ args }) {
@@ -3781,7 +3787,7 @@ const secretsCommand = defineCommand({
 	},
 	args: { json: {
 		type: "boolean",
-		description: "Emit results as JSON instead of a human-readable summary"
+		description: "Emit one JSON document; the keys are the subcommand's (see secrets set --help, secrets list --help and secrets delete --help)."
 	} },
 	subCommands: {
 		set: setCommand,
@@ -3986,7 +3992,7 @@ const webhooksCommand = defineCommand({
 	},
 	args: { json: {
 		type: "boolean",
-		description: "Emit results as JSON instead of a human-readable summary"
+		description: "Emit one JSON document: user, isAdmin, groups ([{label, hooks ([{id, type, active, config?}])}]), totalCount."
 	} },
 	async run({ args }) {
 		const conn = requireForgejoTarget(process.cwd(), void 0, "bst-fj webhooks requires a Forgejo repository");
@@ -3999,48 +4005,241 @@ const webhooksCommand = defineCommand({
 	}
 });
 //#endregion
-//#region ../cli-kit/src/workflow-inputs.ts
-const INPUT_FLAG = "--input";
-const INPUT_FLAG_EQ = "--input=";
+//#region ../forgejo/src/actions.ts
 /**
-* Collect every `--input` value from a command's raw CLI args.
+* The Actions reads: the one place in this package that talks to Forgejo's Actions surface, beside
+* `secrets.ts` which already speaks to `/actions/`. What used to be one composed read is now the
+* pieces that compose it -- {@link getActionsRunByNumber}, {@link listActionsRunJobs},
+* {@link fetchActionsJobLogById} -- with {@link fetchActionsJobLog} kept as the composed read its
+* existing callers use, and {@link listActionsRuns} beside them as the paged listing.
 *
-* citty@0.2.2 keeps only the LAST occurrence of a repeated named flag, so a
-* declared `input` arg cannot capture `--input a=1 --input b=2` -- it silently
-* yields just `b=2`. Scanning the raw argv directly recovers all occurrences.
-* Both `--input k=v` (two tokens) and `--input=k=v` (one token) forms are
-* supported. Throws {@link FatalError} when `--input` has no following value.
+* **Checked against a live instance (2026-09-29).** A status entry's `targetUrl` carries
+* `{run, index}` and `run` there is the repo's
+* run **number**, not the run id the API's `/actions/runs/{id}` paths take -- passing the number
+* as an id silently reads an unrelated, older run. So the resolution is three reads: the run by
+* `?run_number=`, its jobs (a bare array, in the web UI's `/jobs/<index>` order), then the job's
+* log. It is **not** derived from `GET .../actions/tasks`, which was measured returning an
+* unrelated job's log for the same input. Every caller of {@link fetchActionsJobLog} must fail open on any error --
+* this module throws on one rather than swallowing it, exactly like every other read in this
+* package, so the caller's fail-open decision is made once, in one place, rather than half-hidden
+* in here.
+*/
+/**
+* A forge timestamp as the instance wrote it, or `null`. Nullish and empty are `null`, and so is
+* any time at or before the Unix epoch: the instance writes the epoch (in its own zone, such as
+* `1969-12-31T18:00:00-06:00`) for a run that has not started, and Go's zero time (`0001-...`)
+* elsewhere. Passing either through would make every duration derived from it meaningless.
+*/
+function forgeTimestamp(value) {
+	if (value === null || value === void 0 || value === "") return null;
+	const ms = Date.parse(value);
+	if (!Number.isFinite(ms) || ms <= 0) return null;
+	return value;
+}
+const ActionsRunRecordSchema = z.object({
+	id: z.number(),
+	index_in_repo: z.number().nullish(),
+	workflow_id: z.string().nullish(),
+	title: z.string().nullish(),
+	prettyref: z.string().nullish(),
+	commit_sha: z.string().nullish(),
+	event: z.string().nullish(),
+	status: z.string().nullish(),
+	started: z.string().nullish(),
+	stopped: z.string().nullish(),
+	/** Nanoseconds (a Go `time.Duration`); absent until the run finishes. */
+	duration: z.number().nullish(),
+	html_url: z.string().nullish()
+});
+const RunLookupResponseSchema = z.object({ workflow_runs: z.array(ActionsRunRecordSchema) });
+const ActionsJobRecordSchema = z.object({
+	id: z.number(),
+	name: z.string(),
+	status: z.string()
+});
+const RunJobsResponseSchema = z.array(ActionsJobRecordSchema);
+function toActionsRun(record) {
+	const duration = record.duration ?? null;
+	return {
+		id: record.id,
+		number: record.index_in_repo ?? null,
+		workflow: record.workflow_id ?? null,
+		title: record.title ?? null,
+		ref: record.prettyref ?? null,
+		headSha: record.commit_sha ?? null,
+		event: record.event ?? null,
+		status: record.status ?? null,
+		startedAt: forgeTimestamp(record.started),
+		completedAt: forgeTimestamp(record.stopped),
+		durationMs: duration === null || duration <= 0 ? null : Math.round(duration / 1e6),
+		url: record.html_url ?? null
+	};
+}
+/** A ceiling for a reader of the whole log, passed as `{ head: MAX_WHOLE_LOG_CHARS }`: well over
+* the 5 MB logs measured on this repo, and low enough that no reader receives an unbounded body. */
+const MAX_WHOLE_LOG_CHARS = 67108864;
+/**
+* Look a run up by the number the web UI and every `targetUrl` use, and report the whole record
+* rather than only its id. Sends `page` and `limit` with the filter -- without them the instance
+* answers a `run_number` query with every run it holds.
+*
+* No run with that number is a {@link FatalError}: the caller named something that does not
+* exist. A record whose number is not the one asked for is an {@link UnexpectedError}, because
+* an instance that ignored the filter would otherwise hand back its newest run under the
+* caller's number. Also throws on a non-2xx or an unparseable response.
+*/
+async function getActionsRunByNumber(executor, conn, runNumber) {
+	const params = new URLSearchParams({
+		run_number: runNumber,
+		page: "1",
+		limit: "1"
+	});
+	const url = `${conn.serverUrl}/api/v1/repos/${conn.repository}/actions/runs?${params.toString()}`;
+	const res = await executor.fetch(url, { headers: { Authorization: `token ${conn.token}` } });
+	if (!res.ok) await throwForgejoFailure(res, {
+		verb: "look up run",
+		resource: runNumber
+	});
+	const parsed = RunLookupResponseSchema.safeParse(await res.json());
+	if (!parsed.success) throw new UnexpectedError(`Unexpected run lookup response for run ${runNumber}: ${parsed.error.message}`);
+	const [run] = parsed.data.workflow_runs;
+	if (run === void 0) throw new FatalError(`No run numbered ${runNumber} in ${conn.repository}`);
+	const found = toActionsRun(run);
+	if (found.number !== null && String(found.number) !== runNumber) throw new UnexpectedError(`Asked ${conn.repository} for run ${runNumber} and got run ${String(found.number)}: the forge ignored the run_number filter`);
+	return found;
+}
+/**
+* A run's jobs, as a bare array, with `index` set to array position -- the same order the web UI's
+* `/jobs/<index>` links use. Throws on a non-2xx, an unparseable response, or a job record without
+* the three fields this module requires.
 */
-function collectInputArgs(rawArgs) {
-	const values = [];
-	for (let i = 0; i < rawArgs.length; i += 1) {
-		const arg = rawArgs[i];
-		if (arg === void 0) continue;
-		if (arg === INPUT_FLAG) {
-			const next = rawArgs[i + 1];
-			if (next === void 0) throw new FatalError("Missing value for --input: expected `--input key=value`");
-			values.push(next);
-			i += 1;
-		} else if (arg.startsWith(INPUT_FLAG_EQ)) values.push(arg.slice(8));
-	}
-	return values;
+async function listActionsRunJobs(executor, conn, runId) {
+	const url = `${conn.serverUrl}/api/v1/repos/${conn.repository}/actions/runs/${String(runId)}/jobs`;
+	const res = await executor.fetch(url, { headers: { Authorization: `token ${conn.token}` } });
+	if (!res.ok) await throwForgejoFailure(res, {
+		verb: "list run jobs",
+		resource: String(runId)
+	});
+	const parsed = RunJobsResponseSchema.safeParse(await res.json());
+	if (!parsed.success) throw new UnexpectedError(`Unexpected run-jobs response for run ${String(runId)}: ${parsed.error.message}`);
+	const jobs = [];
+	for (const [index, job] of parsed.data.entries()) jobs.push({
+		index,
+		id: job.id,
+		name: job.name,
+		status: job.status
+	});
+	return jobs;
 }
 /**
-* Parse `key=value` workflow-input strings (as collected by
-* {@link collectInputArgs}) into an inputs object. Throws {@link FatalError} on
-* a malformed entry -- no `=`, or an empty key.
+* Read one job's log by the numeric id the log endpoint wants, bounded by `bound`. Never throws on
+* a long log: the bound is what keeps a 68 MB-class response from reaching a caller, and
+* {@link ActionsJobLogText.truncated} says when it cut something. Throws on a non-2xx.
 */
-function parseInputs(raw) {
-	const inputs = {};
-	for (const value of raw) {
-		const eq = value.indexOf("=");
-		if (eq <= 0) throw new FatalError(`Invalid --input "${value}": expected key=value`);
-		inputs[value.slice(0, eq)] = value.slice(eq + 1);
+async function fetchActionsJobLogById(executor, conn, jobId, bound) {
+	const url = `${conn.serverUrl}/api/v1/repos/${conn.repository}/actions/jobs/${String(jobId)}/logs`;
+	const res = await executor.fetch(url, { headers: { Authorization: `token ${conn.token}` } });
+	if (!res.ok) await throwForgejoFailure(res, {
+		verb: "read job log",
+		resource: String(jobId)
+	});
+	const text = await res.text();
+	if ("head" in bound) return {
+		text: text.slice(0, bound.head),
+		truncated: text.length > bound.head
+	};
+	const tail = bound.tail;
+	if (text.length <= tail) return {
+		text,
+		truncated: false
+	};
+	return {
+		text: text.slice(text.length - tail),
+		truncated: true
+	};
+}
+const RunsListResponseSchema = z.object({ workflow_runs: z.array(ActionsRunRecordSchema) });
+/**
+* The repository's workflow runs, newest first, paged **always** (spec decision 9). Every request
+* carries `page` and `limit`: measured against a live instance (2026-09-30), a runs query without
+* `page` ignores `limit` and answers with the whole table -- 3443 runs, 68 MB -- so paging is
+* structural here rather than a caller's obligation.
+*
+* The walk stops on an empty page or once `limit` rows are in hand. A page **shorter** than asked
+* for does not stop it: the server may clamp `limit` to its own page size, and reading a short page
+* as the end of the table would silently answer about part of it. Hitting the page cap with rows
+* still arriving warns, because a truncated listing otherwise reads as absence.
+*/
+async function listActionsRuns(executor, conn, options) {
+	const headers = { Authorization: `token ${conn.token}` };
+	const pageSize = Math.min(options.limit, 50);
+	const runs = [];
+	for (let page = 1; page <= 20; page++) {
+		const params = new URLSearchParams({
+			page: String(page),
+			limit: String(pageSize)
+		});
+		if (options.workflow !== void 0) params.set("workflow_id", options.workflow);
+		if (options.ref !== void 0) params.set("ref", options.ref);
+		if (options.headSha !== void 0) params.set("head_sha", options.headSha);
+		if (options.status !== void 0) params.set("status", options.status);
+		const url = `${conn.serverUrl}/api/v1/repos/${conn.repository}/actions/runs?${params.toString()}`;
+		const res = await executor.fetch(url, { headers });
+		if (!res.ok) await throwForgejoFailure(res, {
+			verb: "list workflow runs",
+			resource: conn.repository
+		});
+		const parsed = RunsListResponseSchema.safeParse(await res.json());
+		if (!parsed.success) throw new UnexpectedError(`Unexpected workflow-runs response for ${conn.repository}: ${parsed.error.message}`);
+		const pageRuns = parsed.data.workflow_runs.map(toActionsRun);
+		runs.push(...pageRuns);
+		if (pageRuns.length === 0) break;
+		if (runs.length >= options.limit) break;
+		if (page === 20) {
+			log.warn(`Workflow run listing on ${conn.repository} hit the ${String(20)}-page cap without an empty page; results may be truncated`);
+			options.onPageCap?.();
+		}
 	}
-	return inputs;
+	return runs.slice(0, options.limit);
+}
+/** A `targetUrl` path of the shape `/actions/runs/{run}/jobs/{index}`, tolerating a scheme and
+* host in front of it and a trailing path segment, query, or fragment after it. */
+const ACTIONS_JOB_TARGET_URL = /\/actions\/runs\/(\d+)\/jobs\/(\d+)(?:[/?#]|$)/u;
+/**
+* Parse a status entry's `targetUrl` into the `{run, index}` the job-log read needs. A `targetUrl`
+* of any other shape -- including `null` -- yields `null`, full stop: **the id is never derived
+* from the `/actions/tasks` listing**, which was measured (against a live instance, in an earlier
+* investigation) returning an unrelated job's log for the same input. This module's job-log read
+* accepts nothing but this parser's output for exactly that reason.
+*
+* The parser lives here rather than beside the incident sweep that first needed it (spec decision
+* 15) because a caller holding a pasted `targetUrl` must be able to read the same object, the URL
+* shape is this package's domain, and a second copy in a command-line tool would be a forked
+* declaration.
+*/
+function parseActionsJobTargetUrl(targetUrl) {
+	if (targetUrl === null) return null;
+	const match = ACTIONS_JOB_TARGET_URL.exec(targetUrl);
+	if (match === null) return null;
+	return {
+		run: match[1],
+		index: Number(match[2])
+	};
+}
+/**
+* The repository half of the same URL: everything before the first `/actions/runs/` is a
+* repository URL when it carries a scheme, so a pasted `targetUrl` can name the repository it came
+* from instead of leaving that to a separate option. A bare path carries no repository and yields
+* `undefined`; a prefixed value that is not a repository URL is refused by
+* {@link parseRepoTarget}, which is the answer a caller who pasted the wrong thing needs.
+*/
+function parseActionsJobTargetRepo(targetUrl) {
+	const boundary = targetUrl.indexOf("/actions/runs/");
+	if (boundary === -1) return void 0;
+	const prefix = targetUrl.slice(0, boundary);
+	if (!prefix.startsWith("http://") && !prefix.startsWith("https://")) return void 0;
+	return parseRepoTarget(prefix);
 }
-z.object({ workflow_runs: z.array(z.object({ id: z.number() })) });
-z.array(z.object({ id: z.number() }));
 /**
 * Trigger a `workflow_dispatch` event. Any 2xx is success (the instance's swagger lists 201 and
 * 204). A failure is a {@link FatalError} carrying {@link forgejoErrorMessage}'s text for every
@@ -4070,79 +4269,551 @@ async function dispatchWorkflow(executor, conn, options) {
 	};
 }
 //#endregion
-//#region src/workflow-dispatch.ts
+//#region ../forgejo/src/actions-log.ts
+/** A CSI sequence: `ESC [` , parameter bytes, intermediate bytes, one final byte. Removed whole --
+* dropping only the escape byte would leave the parameters behind as text. */
+const CSI_SEQUENCE = /\u001b\[[0-?]*[ -/]*[@-~]/gu;
+/** An OSC sequence: `ESC ]` up to a BEL or a string terminator (`ESC \`). */
+const OSC_SEQUENCE = /\u001b\][^\u0007]*(?:\u0007|\u001b\\)/gu;
+/** An escape byte that began neither of those. */
+const LONE_ESCAPE = /\u001b/gu;
+/** The C0 controls that may still be left, tab excepted, plus DEL. */
+const CONTROL_CHARS = /[\u0000-\u0008\u000a-\u001f\u007f]/gu;
+/** The first token of a line, when it is shaped like the timestamp the runner writes. */
+const LINE_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\S+$/u;
+/** Remove every control sequence and control character, whole. */
+function stripControlSequences(text) {
+	return text.replace(CSI_SEQUENCE, "").replace(OSC_SEQUENCE, "").replace(LONE_ESCAPE, "").replace(CONTROL_CHARS, "");
+}
+/**
+* Split one line into its timestamp and its text. The first whitespace-delimited token is the
+* timestamp only when it is shaped like one **and** a clock accepts it -- a job printing a
+* date-shaped word keeps it in its body rather than losing it to a `null`.
+*/
+function splitLogLine(line) {
+	const spaceAt = line.indexOf(" ");
+	const head = spaceAt === -1 ? line : line.slice(0, spaceAt);
+	if (LINE_TIMESTAMP.test(head) && Number.isFinite(Date.parse(head))) return {
+		at: head,
+		text: stripControlSequences(spaceAt === -1 ? "" : line.slice(spaceAt + 1))
+	};
+	return {
+		at: null,
+		text: stripControlSequences(line)
+	};
+}
+function spanBetween(start, end) {
+	if (start === null || end === null) return null;
+	const startMs = Date.parse(start);
+	const endMs = Date.parse(end);
+	if (!Number.isFinite(startMs) || !Number.isFinite(endMs)) return null;
+	return endMs - startMs;
+}
 /**
-* `bst-fj workflow:dispatch`: a thin command over `@bensandee/forgejo/actions`. Forgejo-only;
-* `gh workflow run` already serves GitHub.
+* Read a job log as lines. The carriage return of a CRLF pair and the empty line a trailing
+* newline leaves are both dropped.
 */
-/** Dispatch a `workflow_dispatch` event on the current repository or on `options.repo`. */
-async function runWorkflowDispatch(fetcher, options) {
-	const dispatched = await dispatchWorkflow(fetcher, requireForgejoTarget(options.cwd, void 0, "workflow:dispatch is Forgejo-only -- use gh workflow run on GitHub."), {
-		...options.repo === void 0 ? {} : { repository: options.repo },
-		workflow: options.workflow,
-		ref: options.ref,
-		inputs: options.inputs
-	});
+function readActionsJobLog(text) {
+	const raw = text.split("\n");
+	if (raw.length > 0 && raw[raw.length - 1] === "") raw.pop();
+	const lines = raw.map((entry) => splitLogLine(entry.endsWith("\r") ? entry.slice(0, -1) : entry));
+	const firstLineAt = lines.find((line) => line.at !== null)?.at ?? null;
+	let lastLineAt = null;
+	for (let i = lines.length - 1; i >= 0 && lastLineAt === null; i--) lastLineAt = lines[i]?.at ?? null;
 	return {
-		status: "dispatched",
-		host: "forgejo",
-		repo: dispatched.repository,
-		workflow: dispatched.workflow,
-		ref: dispatched.ref,
-		inputs: dispatched.inputs
+		firstLineAt,
+		lastLineAt,
+		spanMs: spanBetween(firstLineAt, lastLineAt),
+		lines
 	};
 }
 //#endregion
-//#region src/registry-actions.ts
-const actionsSubCommands = { "workflow:dispatch": defineCommand({
+//#region src/ci-log.ts
+/**
+* `bst-fj ci:log` -- one CI job's log, whole, or the lines of it a `--grep` matches. GitHub has
+* `gh run view --log` for this, so the command is Forgejo-only, like every other command in this
+* bin.
+*
+* The positional is a run number, a run URL (what `ci:runs` prints), or a status `target_url` (what
+* `pr:checks` and `commit:status` print beside a red check), so a caller pastes rather than
+* transcribes.
+*
+* The log is read **whole** up to the library's ceiling, not as the 2 MiB tail the incident body
+* keeps: a `--grep` over a tail would answer "not mentioned" about lines it never saw. A log cut
+* by the ceiling says so in `log.truncated` and in a notice.
+*
+* There is no step table. The runner on the instance this was built against writes a step marker
+* for its first main step only, so a step split read off the log text was wrong for every later
+* step (see `@bensandee/forgejo/actions-log`).
+*
+* Under `--json` the payload carries `lines` only with `--grep`: a whole log is megabytes, and a
+* reader that wants it all reads the text output.
+*/
+/** A run page URL: `/actions/runs/{run}`, with nothing after it but a slash, query or fragment. */
+const ACTIONS_RUN_URL = /\/actions\/runs\/(\d+)\/?(?:[?#]|$)/u;
+/**
+* The positional: all digits is a run number; a job URL gives the run and the job index; a run
+* URL gives the run alone. A URL carrying a host and `owner/repo` also names the repository,
+* which then stands in for `--repo`.
+*/
+function parseCiLogTarget(target) {
+	if (/^\d+$/.test(target)) return {
+		run: target,
+		index: null,
+		repoTarget: void 0
+	};
+	const location = parseActionsJobTargetUrl(target);
+	if (location !== null) return {
+		run: location.run,
+		index: location.index,
+		repoTarget: parseActionsJobTargetRepo(target)
+	};
+	const runOnly = ACTIONS_RUN_URL.exec(target);
+	if (runOnly !== null) return {
+		run: runOnly[1],
+		index: null,
+		repoTarget: parseActionsJobTargetRepo(target)
+	};
+	throw new FatalError(`Not a run number or an Actions run or job URL: "${target}" (expected e.g. 6693, https://host/owner/repo/actions/runs/6693 or .../actions/runs/6693/jobs/0).`);
+}
+/** What the run's jobs are, in the shape an error message lists them in for a caller to read. */
+function jobTable(jobs) {
+	return jobs.map((candidate) => `  ${String(candidate.index)} ${candidate.name} ${candidate.status}`).join("\n");
+}
+function jobAtIndex(jobs, index, label) {
+	const found = jobs.find((candidate) => candidate.index === index);
+	if (found === void 0) throw new FatalError(`${label} ${String(index)} is not one of this run's jobs. Jobs in this run:\n${jobTable(jobs)}`);
+	return found;
+}
+/**
+* Which job's log to read.
+*
+* A `--job` of all digits is an index -- the same index a `target_url` carries -- and anything else
+* is an exact, case-insensitive job name. When the URL already named an index, a `--job` that
+* disagrees with it is a refusal naming both, because either could be what the caller meant.
+*
+* With neither and several jobs, this refuses rather than defaulting to index 0: the answer would
+* be about the wrong job, confidently, with nothing said.
+*/
+function chooseJob(jobs, job, urlIndex) {
+	if (job !== void 0) {
+		const chosen = /^\d+$/.test(job) ? jobAtIndex(jobs, Number(job), `--job ${job}`) : jobs.find((candidate) => candidate.name.toLowerCase() === job.toLowerCase());
+		if (chosen === void 0) throw new FatalError(`No job is named "${job}". Jobs in this run:\n${jobTable(jobs)}`);
+		if (urlIndex !== null && chosen.index !== urlIndex) throw new FatalError(`--job "${job}" is job ${String(chosen.index)}, but the URL names job ${String(urlIndex)} -- give one of them.`);
+		return chosen;
+	}
+	if (urlIndex !== null) return jobAtIndex(jobs, urlIndex, "The URL's job index");
+	const only = jobs.length === 1 ? jobs[0] : void 0;
+	if (only !== void 0) return only;
+	throw new FatalError(`This run has ${String(jobs.length)} jobs, so --job must say which one (a name or the index).\nJobs in this run:\n${jobTable(jobs)}`);
+}
+/**
+* Read one job's log: run by number, its jobs, the chosen job, the whole log. A refused target, a
+* missing run or job, and a non-2xx from the forge all throw; a successful read of a failed job
+* does not, because this is a readout and not a verdict.
+*/
+async function runCiLog(fetcher, options) {
+	const target = parseCiLogTarget(options.target);
+	let grep;
+	if (options.grep !== void 0) try {
+		grep = new RegExp(options.grep);
+	} catch {
+		throw new FatalError(`--grep is not a valid JavaScript regular expression: "${options.grep}"`);
+	}
+	const conn = requireForgejoTarget(options.cwd, resolveIssueTarget(target.repoTarget, options.repo), "ci:log is Forgejo-only -- gh run view --log already serves GitHub, first-class. Use that instead.");
+	rootLogger.debug(`ci:log repository=${conn.repository} run=${target.run}`);
+	const run = await getActionsRunByNumber(fetcher, conn, target.run);
+	const chosen = chooseJob(await listActionsRunJobs(fetcher, conn, run.id), options.job, target.index);
+	const jobLog = await fetchActionsJobLogById(fetcher, conn, chosen.id, { head: MAX_WHOLE_LOG_CHARS });
+	const read = readActionsJobLog(jobLog.text);
+	const notices = [];
+	if (jobLog.truncated) notices.push("The job log is longer than the whole-log ceiling, so only its head was read: later lines are missing.");
+	return {
+		repository: conn.repository,
+		run: {
+			number: run.number ?? Number.parseInt(target.run, 10),
+			id: run.id,
+			workflow: run.workflow,
+			ref: run.ref,
+			headSha: run.headSha,
+			status: run.status
+		},
+		job: {
+			index: chosen.index,
+			id: chosen.id,
+			name: chosen.name,
+			status: chosen.status
+		},
+		log: {
+			firstLineAt: read.firstLineAt,
+			lastLineAt: read.lastLineAt,
+			spanMs: read.spanMs,
+			lineCount: read.lines.length,
+			truncated: jobLog.truncated
+		},
+		lines: grep === void 0 ? read.lines : read.lines.filter((line) => grep.test(line.text)),
+		grep: grep !== void 0,
+		notices
+	};
+}
+/** A two-line header naming the run and job, then each line kept with its timestamp. */
+function renderCiLog(result) {
+	const lines = [`run ${String(result.run.number)} ${result.run.status ?? "?"} ${result.run.workflow ?? "?"}`, `job ${String(result.job.index)} ${result.job.name} (${result.job.status})`];
+	for (const line of result.lines) lines.push(line.at === null ? line.text : `${line.at} ${line.text}`);
+	return lines.join("\n");
+}
+//#endregion
+//#region src/commands/ci-log.ts
+const ciLogCommand = defineCommand({
 	meta: {
-		name: "workflow:dispatch",
-		description: "Trigger a workflow_dispatch event for a workflow in any repo on the same Forgejo host (Forgejo-only; use gh workflow run on GitHub). The token must have rights on --repo when it differs from the current repo."
+		name: "ci:log",
+		description: "Show one workflow job's log, or the lines matching --grep (Forgejo-only; use gh run view --log on GitHub)"
 	},
 	args: {
+		target: {
+			type: "positional",
+			required: true,
+			description: "Run number, run URL (actions/runs/<run>), or a status target_url (actions/runs/<run>/jobs/<index>)"
+		},
+		job: {
+			type: "string",
+			description: "Job name (case-insensitive) or zero-based index (refused when a URL names one)"
+		},
+		grep: {
+			type: "string",
+			description: "JavaScript regular expression over each line's text; prints only matching lines"
+		},
 		repo: {
 			type: "string",
-			description: "Target repository as owner/repo, not a URL (default: the current repo)",
-			required: false
+			description: "Repository URL (default: this repo)"
 		},
+		json: {
+			type: "boolean",
+			description: "Emit one JSON document: {repository, run: {number, id, workflow, ref, headSha, status}, job: {index, id, name, status}, log: {firstLineAt, lastLineAt, spanMs, lineCount, truncated}, lines ([{at, text}], with --grep only)}."
+		},
+		verbose: {
+			type: "boolean",
+			description: "Emit detailed debug output"
+		}
+	},
+	async run({ args }) {
+		const out = createCliOutput(args.json === true);
+		const target = args.target ?? "";
+		const result = await runCiLog(cliFetcher(), {
+			cwd: process.cwd(),
+			target,
+			...args.job === void 0 ? {} : { job: args.job },
+			...args.grep === void 0 ? {} : { grep: args.grep },
+			...args.repo === void 0 ? {} : { repo: args.repo }
+		});
+		for (const notice of result.notices) out.notice(notice);
+		out.json({
+			repository: result.repository,
+			run: result.run,
+			job: result.job,
+			log: result.log,
+			...result.grep ? { lines: result.lines } : {}
+		});
+		out.text(renderCiLog(result));
+	}
+});
+//#endregion
+//#region src/ci-runs.ts
+/**
+* `bst-fj ci:runs` -- a read-only, Forgejo-only listing of a repository's workflow runs and their
+* jobs, over the shared paged read in `@bensandee/forgejo/actions`. GitHub run listing already has
+* a first-class tool (`gh run list`), the same precedent `pr:list` follows for the same structural
+* reason (spec decision 2 and 13's target form: `--repo` is a repository URL, like every `pr:*`
+* and `issue:*` read).
+*
+* `--ref` and `--pr` are one filter spelled two ways (spec decision 6): a pull-request run carries
+* `refs/pull/<n>/head`, which no caller should have to know, and the branch's own push runs stay
+* one `--ref <branch>` away.
+*/
+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;
+}
+/**
+* The `ref` filter, from whichever of `--ref` and `--pr` was given. A bare `--ref main` names a
+* branch, so it becomes `refs/heads/main`; a value that is already a full ref is sent as is;
+* `--pr` becomes `refs/pull/<n>/head` (spec decision 6) and carries the repository off a PR URL so
+* the URL can stand in for `--repo`.
+*
+* Both together is a refusal rather than a precedence: they are the same filter, and quietly
+* ignoring one answers about a different set of runs than the caller asked for.
+*/
+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) {
+		const parsed = parseIssueRef(pr);
+		if (parsed.number === void 0) throw new FatalError(`Not a pull request number or URL: "${pr}"`);
+		return {
+			ref: `refs/pull/${String(parsed.number)}/head`,
+			target: parsed.target
+		};
+	}
+	if (ref === void 0) return {
+		ref: void 0,
+		target: void 0
+	};
+	if (ref.startsWith("refs/")) return {
+		ref,
+		target: void 0
+	};
+	return {
+		ref: `refs/heads/${ref}`,
+		target: void 0
+	};
+}
+/**
+* List a repository's workflow runs, newest first, each with its jobs. Paging is never optional on
+* this read (spec decision 9): an unpaged runs query answers with the whole table. Refuses a
+* github.com target before any fetch.
+*/
+async function runCiRuns(fetcher, options) {
+	const limit = parseLimit$2(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)}`);
+	const notices = [];
+	const runs = await listActionsRuns(fetcher, conn, {
+		limit,
+		workflow: options.workflow,
+		ref: resolved.ref,
+		headSha: options.sha,
+		status: options.status,
+		onPageCap: () => {
+			notices.push("Workflow run listing hit the page cap before an empty page; results may be truncated.");
+		}
+	});
+	const fetched = await Promise.all(runs.map(async (run) => ({
+		run,
+		jobs: await listActionsRunJobs(fetcher, conn, run.id)
+	})));
+	const rows = [];
+	for (const { run, jobs } of fetched) rows.push({
+		...run,
+		jobs
+	});
+	return {
+		repository: conn.repository,
+		runs: rows,
+		notices
+	};
+}
+/** A duration, or the dash that says the forge reported none (the run has not finished). */
+function durationText(durationMs) {
+	return durationMs === null ? "-" : `${String(durationMs)}ms`;
+}
+/**
+* One line per run, then one indented line per job. The run number leads its line because it is
+* what `ci:log` takes as its positional.
+*/
+function renderCiRuns(result) {
+	if (result.runs.length === 0) return `No workflow runs in ${result.repository}.`;
+	const lines = [];
+	for (const run of result.runs) {
+		lines.push([
+			run.number === null ? "?" : String(run.number),
+			run.status ?? "?",
+			run.workflow ?? "?",
+			run.event ?? "?",
+			run.ref ?? "?",
+			run.headSha ?? "?",
+			durationText(run.durationMs),
+			run.url ?? "?"
+		].join(" "));
+		for (const job of run.jobs) lines.push(`  ${String(job.index)} ${job.status} ${job.name}`);
+	}
+	return lines.join("\n");
+}
+//#endregion
+//#region src/commands/ci-runs.ts
+const ciRunsCommand = defineCommand({
+	meta: {
+		name: "ci:runs",
+		description: "List a repository's workflow runs with their jobs, newest first (Forgejo-only; use gh run list on GitHub)"
+	},
+	args: {
 		workflow: {
 			type: "string",
-			description: "Workflow filename (e.g. deploy.yml) or numeric ID",
-			required: true
+			description: "Workflow file name, e.g. check.yml (the forge's workflow_id)"
 		},
 		ref: {
 			type: "string",
-			description: "Git ref to dispatch on (default: main)",
-			required: false
+			description: "Branch or full ref; a bare name means refs/heads/<name> (refuses --pr)"
 		},
-		input: {
+		pr: {
 			type: "string",
-			description: "Workflow input as key=value (repeatable)",
-			required: false
+			description: "Pull request number or URL: its own runs (refs/pull/<n>/head)"
+		},
+		sha: {
+			type: "string",
+			description: "Head SHA (the forge's head_sha)"
+		},
+		status: {
+			type: "string",
+			description: "Run status: pending | queued | in_progress | failure | success | skipped (the forge interprets the string)"
+		},
+		limit: {
+			type: "string",
+			default: "20",
+			description: "Maximum runs to return"
+		},
+		repo: {
+			type: "string",
+			description: "Repository URL (default: this repo)"
 		},
 		json: {
 			type: "boolean",
-			description: "Emit the dispatch result as one JSON document. Keys: status (always dispatched), host (always forgejo), repo (owner/repo), workflow, ref, inputs."
+			description: "Emit one JSON document: {repository, runs: [{number, id, workflow, title, ref (main, or #<pr> for a PR run), headSha, event, status, startedAt, completedAt, durationMs, url (each nullable but id), jobs: [{index, id, name, status}]}]}."
 		},
 		verbose: {
 			type: "boolean",
 			description: "Emit detailed debug output"
 		}
 	},
-	async run({ args, rawArgs }) {
+	async run({ args }) {
 		const out = createCliOutput(args.json === true);
-		if (!args.workflow) throw new FatalError("--workflow is required");
-		const result = await runWorkflowDispatch(cliFetcher(), {
+		const result = await runCiRuns(cliFetcher(), {
 			cwd: process.cwd(),
-			repo: args.repo ?? void 0,
-			workflow: args.workflow,
-			ref: args.ref ?? "main",
-			inputs: parseInputs(collectInputArgs(rawArgs))
+			workflow: args.workflow ?? void 0,
+			ref: args.ref ?? void 0,
+			pr: args.pr ?? void 0,
+			sha: args.sha ?? void 0,
+			status: args.status ?? void 0,
+			limit: args.limit,
+			repo: args.repo ?? void 0
 		});
-		out.json(result);
-		out.text(`Dispatched ${result.workflow} on ${result.repo} (ref: ${result.ref})`);
+		for (const notice of result.notices) out.notice(notice);
+		out.json({
+			repository: result.repository,
+			runs: result.runs
+		});
+		out.text(renderCiRuns(result));
 	}
-}) };
+});
+//#endregion
+//#region ../cli-kit/src/workflow-inputs.ts
+const INPUT_FLAG = "--input";
+const INPUT_FLAG_EQ = "--input=";
+/**
+* Collect every `--input` value from a command's raw CLI args.
+*
+* citty@0.2.2 keeps only the LAST occurrence of a repeated named flag, so a
+* declared `input` arg cannot capture `--input a=1 --input b=2` -- it silently
+* yields just `b=2`. Scanning the raw argv directly recovers all occurrences.
+* Both `--input k=v` (two tokens) and `--input=k=v` (one token) forms are
+* supported. Throws {@link FatalError} when `--input` has no following value.
+*/
+function collectInputArgs(rawArgs) {
+	const values = [];
+	for (let i = 0; i < rawArgs.length; i += 1) {
+		const arg = rawArgs[i];
+		if (arg === void 0) continue;
+		if (arg === INPUT_FLAG) {
+			const next = rawArgs[i + 1];
+			if (next === void 0) throw new FatalError("Missing value for --input: expected `--input key=value`");
+			values.push(next);
+			i += 1;
+		} else if (arg.startsWith(INPUT_FLAG_EQ)) values.push(arg.slice(8));
+	}
+	return values;
+}
+/**
+* Parse `key=value` workflow-input strings (as collected by
+* {@link collectInputArgs}) into an inputs object. Throws {@link FatalError} on
+* a malformed entry -- no `=`, or an empty key.
+*/
+function parseInputs(raw) {
+	const inputs = {};
+	for (const value of raw) {
+		const eq = value.indexOf("=");
+		if (eq <= 0) throw new FatalError(`Invalid --input "${value}": expected key=value`);
+		inputs[value.slice(0, eq)] = value.slice(eq + 1);
+	}
+	return inputs;
+}
+//#endregion
+//#region src/workflow-dispatch.ts
+/**
+* `bst-fj workflow:dispatch`: a thin command over `@bensandee/forgejo/actions`. Forgejo-only;
+* `gh workflow run` already serves GitHub.
+*/
+/** Dispatch a `workflow_dispatch` event on the current repository or on `options.repo`. */
+async function runWorkflowDispatch(fetcher, options) {
+	const dispatched = await dispatchWorkflow(fetcher, requireForgejoTarget(options.cwd, void 0, "workflow:dispatch is Forgejo-only -- use gh workflow run on GitHub."), {
+		...options.repo === void 0 ? {} : { repository: options.repo },
+		workflow: options.workflow,
+		ref: options.ref,
+		inputs: options.inputs
+	});
+	return {
+		status: "dispatched",
+		host: "forgejo",
+		repo: dispatched.repository,
+		workflow: dispatched.workflow,
+		ref: dispatched.ref,
+		inputs: dispatched.inputs
+	};
+}
+//#endregion
+//#region src/registry-actions.ts
+const actionsSubCommands = {
+	"ci:log": ciLogCommand,
+	"ci:runs": ciRunsCommand,
+	"workflow:dispatch": defineCommand({
+		meta: {
+			name: "workflow:dispatch",
+			description: "Trigger a workflow_dispatch event for a workflow in any repo on the same Forgejo host (Forgejo-only; use gh workflow run on GitHub). The token must have rights on --repo when it differs from the current repo."
+		},
+		args: {
+			repo: {
+				type: "string",
+				description: "Target repository as owner/repo, not a URL (default: the current repo)",
+				required: false
+			},
+			workflow: {
+				type: "string",
+				description: "Workflow filename (e.g. deploy.yml) or numeric ID",
+				required: true
+			},
+			ref: {
+				type: "string",
+				description: "Git ref to dispatch on (default: main)",
+				required: false
+			},
+			input: {
+				type: "string",
+				description: "Workflow input as key=value (repeatable)",
+				required: false
+			},
+			json: {
+				type: "boolean",
+				description: "Emit one JSON document: status (dispatched), host (forgejo), repo (owner/repo), workflow, ref, inputs."
+			},
+			verbose: {
+				type: "boolean",
+				description: "Emit detailed debug output"
+			}
+		},
+		async run({ args, rawArgs }) {
+			const out = createCliOutput(args.json === true);
+			if (!args.workflow) throw new FatalError("--workflow is required");
+			const result = await runWorkflowDispatch(cliFetcher(), {
+				cwd: process.cwd(),
+				repo: args.repo ?? void 0,
+				workflow: args.workflow,
+				ref: args.ref ?? "main",
+				inputs: parseInputs(collectInputArgs(rawArgs))
+			});
+			out.json(result);
+			out.text(`Dispatched ${result.workflow} on ${result.repo} (ref: ${result.ref})`);
+		}
+	})
+};
 z.object({
 	content: z.string(),
 	encoding: z.literal("base64")
@@ -4328,7 +4999,7 @@ const branchSubCommands = {
 			},
 			json: {
 				type: "boolean",
-				description: "Emit JSON on stdout"
+				description: "Emit one JSON document: deleted."
 			},
 			verbose: {
 				type: "boolean",
@@ -4358,7 +5029,7 @@ const branchSubCommands = {
 			},
 			json: {
 				type: "boolean",
-				description: "Emit JSON on stdout"
+				description: "Emit one JSON document: branches ([{name, protected, commitSha (or null), commitDate (or null)}]), truncated."
 			},
 			verbose: {
 				type: "boolean",
@@ -4914,7 +5585,12 @@ function forgejoIssueApi(fetcher, conn) {
 const ISSUE_LIST_JSON_HELP = "Emit one JSON document: issues ([{number, title, state, url, author, labels, createdAt, updatedAt, closedAt (null while open), isPullRequest, assignees, attachments ([{id, name, size, createdAt, downloadUrl}])}]), truncated.";
 const ISSUE_CREATE_JSON_HELP = "Emit one JSON document: number, url, assignees. A dry run reports number 0 and an empty url.";
 const ISSUE_STATE_JSON_HELP = "Emit one JSON document: number, url, action (close | reopen), state ({previous, current}), changed, comment? ({posted}; present only when a comment was given).";
-const ISSUE_VIEW_JSON_HELP = "Emit JSON on stdout: the issue's own fields (number, title, state, url, author, labels, createdAt, updatedAt, closedAt, body, isPullRequest, assignees, attachments), comments (each with id, author, createdAt, updatedAt?, body, url?), commentsTruncated (true when the comment read hit its cap of about 1000), and, on a pull request only, either pr (head and base, each with ref, sha and repo, which is null for a deleted fork; draft; merged; mergeable, true, false or null; state) or prUnavailable (reason)";
+const ISSUE_COMMENT_JSON_HELP = "Emit one JSON document: number, url.";
+const ISSUE_UPDATE_JSON_HELP = "Emit one JSON document: number, url, previous ({title, body}), current ({title, body}), changed ([title | body]). A dry run reports current as it would be and writes nothing.";
+const ISSUE_DOWNLOAD_JSON_HELP = "Emit one JSON document: dir, files ([{name, size, path}]). A dry run lists the files it would write and writes nothing.";
+const ISSUE_LABEL_JSON_HELP = "Emit one JSON document: number, label, action (add | remove), url.";
+const ISSUE_SET_LABELS_JSON_HELP = "Emit one JSON document: number, labels, previous, added, removed, url. A dry run reports the change it would make and writes nothing.";
+const ISSUE_VIEW_JSON_HELP = "Emit one JSON document: number, title, state, url, author, labels, createdAt, updatedAt, closedAt, body, isPullRequest, assignees, attachments, comments ([{id, author, createdAt, updatedAt?, body, url?}]), commentsTruncated, pr? ({head ({ref, sha, repo (or null)}), base ({ref, sha, repo (or null)}), draft, merged, mergeable (true | false | null), state}), prUnavailable? ({reason}). On a pull request exactly one of pr and prUnavailable is present, and neither is otherwise; repo is null for a deleted fork; commentsTruncated is true when the comment read hit its cap of about 1000.";
 /**
 * The refusal for an {@link IssueNumberRequiredError}. `example` is the program's own complete
 * invocation, for instance the program name, the command and a sample number, so every program
@@ -5361,7 +6037,7 @@ const issueCommentCommand = defineCommand({
 		},
 		json: {
 			type: "boolean",
-			description: "Emit JSON on stdout"
+			description: ISSUE_COMMENT_JSON_HELP
 		},
 		"dry-run": {
 			type: "boolean",
@@ -5618,7 +6294,7 @@ const issueDownloadCommand = defineCommand({
 		},
 		json: {
 			type: "boolean",
-			description: "Emit JSON on stdout"
+			description: ISSUE_DOWNLOAD_JSON_HELP
 		},
 		"dry-run": {
 			type: "boolean",
@@ -5858,7 +6534,7 @@ function defineIssueLabelCommand(action) {
 			},
 			json: {
 				type: "boolean",
-				description: "Emit JSON on stdout"
+				description: ISSUE_LABEL_JSON_HELP
 			},
 			"dry-run": {
 				type: "boolean",
@@ -5920,7 +6596,7 @@ const issueSetLabelsCommand = defineCommand({
 		},
 		json: {
 			type: "boolean",
-			description: "Emit JSON on stdout"
+			description: ISSUE_SET_LABELS_JSON_HELP
 		},
 		"dry-run": {
 			type: "boolean",
@@ -6202,7 +6878,7 @@ const issueUpdateCommand = defineCommand({
 		},
 		json: {
 			type: "boolean",
-			description: "Emit JSON on stdout"
+			description: ISSUE_UPDATE_JSON_HELP
 		},
 		"dry-run": {
 			type: "boolean",
@@ -6628,7 +7304,7 @@ const prChecksCommand = defineCommand({
 		},
 		json: {
 			type: "boolean",
-			description: "Emit the machine-readable report on stdout. Keys: pr, repository, url, state, headSha, baseRef, status (green | red | pending | no-status | unparseable | head-moved | timeout), settled, combinedState, waited, elapsedMs, checks (each: context, name, state, verdict, description, targetUrl, updatedAt, preexisting; description, targetUrl and updatedAt can be null), baseline (ref, sha?, status, reason?, redNames), detail? (unparseable only), previousHeadSha? (head-moved only). no-status means no check was posted and is never green"
+			description: "Emit one JSON document: pr, repository, url, state, headSha, baseRef, status (green | red | pending | no-status | unparseable | head-moved | timeout), settled, combinedState, waited, elapsedMs, checks ([{context, name, state, verdict, description (or null), targetUrl (or null), updatedAt (or null), preexisting}]), baseline ({ref, sha?, status, reason?, redNames}), detail? (unparseable only), previousHeadSha? (head-moved only). no-status means no check was posted and is never green."
 		},
 		verbose: {
 			type: "boolean",
@@ -7588,7 +8264,7 @@ const prCreateCommand = defineCommand({
 		},
 		json: {
 			type: "boolean",
-			description: "Emit the result as JSON: action (created | updated | would-create | would-update), number, url, branch, base, title, body, droppedRefs? (array of {text, issue}; a create or would-create carries it), dryRun. On a dry run, number and url are null."
+			description: "Emit one JSON document: action (created | updated | would-create | would-update), number (or null), url (or null), branch, base, title, body, droppedRefs? ([{text, issue}]), dryRun. A create or would-create carries droppedRefs; on a dry run, number and url are null."
 		},
 		verbose: {
 			type: "boolean",
@@ -7696,7 +8372,7 @@ const prFilesCommand = defineCommand({
 		},
 		json: {
 			type: "boolean",
-			description: "Emit JSON on stdout"
+			description: "Emit one JSON document: files ([{filename, status (or null), additions, deletions}]), truncated."
 		},
 		verbose: {
 			type: "boolean",
@@ -7855,7 +8531,8 @@ const MergeGateSchema = z.object({
 	merge_base: z.string(),
 	changed_files: z.number().nullish(),
 	base: z.object({ ref: z.string() }),
-	labels: z.array(z.object({ name: z.string() })).nullable()
+	labels: z.array(z.object({ name: z.string() })).nullable(),
+	updated_at: z.string().nullish()
 });
 /**
 * Read a PR's live open/draft/mergeable state and current head SHA in one `/pulls/<n>` GET --
@@ -7880,7 +8557,8 @@ async function readMergeGate(executor, conn, prNumber) {
 		mergeBase: parsed.data.merge_base,
 		changedFiles: parsed.data.changed_files ?? null,
 		baseRef: parsed.data.base.ref,
-		labels: (parsed.data.labels ?? []).map((label) => label.name)
+		labels: (parsed.data.labels ?? []).map((label) => label.name),
+		updatedAt: parsed.data.updated_at ?? null
 	};
 }
 /**
@@ -8046,7 +8724,7 @@ const prSubCommands = {
 			},
 			json: {
 				type: "boolean",
-				description: "Emit JSON on stdout"
+				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",
@@ -8100,7 +8778,7 @@ const prSubCommands = {
 			},
 			json: {
 				type: "boolean",
-				description: "Emit the result as JSON: action (updated | would-update), number, url, branch, base, title, body, dryRun, rewrites. On a dry run, number and url are null."
+				description: "Emit one JSON document: action (updated | would-update), number (or null), url (or null), branch, base, title, body, dryRun, rewrites. On a dry run, number and url are null."
 			},
 			verbose: {
 				type: "boolean",
@@ -8155,7 +8833,7 @@ setForgejoLogger(rootLogger);
 await runCli({
 	name: "bst-fj",
 	version: BST_FJ_VERSION,
-	description: "Forgejo API commands: labels, secrets, webhooks, releases, issues, PRs, branches, workflows and commit checks",
+	description: "Forgejo API commands: labels, secrets, webhooks, releases, issues, PRs, branches, workflows, CI runs and logs, and commit checks",
 	banner: void 0,
 	subCommands: bstFjSubCommands,
 	describeError: describeForgeError

package/package.json

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