@henryqw/pi-pr 0.3.7 → 1.0.1

package/extensions/pr-merge.ts

@@ -0,0 +1,288 @@
+import { lstat } from "node:fs/promises";
+import { resolve } from "node:path";
+import type { LocalMergeSafety } from "./pr-routing.ts";
+
+export type ExecResult = {
+	stdout: string;
+	stderr: string;
+	code: number;
+	killed?: boolean;
+};
+
+export type Exec = (
+	command: string,
+	args: string[],
+	options: { cwd: string },
+) => Promise<ExecResult>;
+
+export type MergeMethod = "merge" | "rebase" | "squash";
+
+const MERGE_PULL_REQUEST_MUTATION = "mutation($pullRequestId:ID!,$expectedHeadOid:GitObjectID!,$mergeMethod:PullRequestMergeMethod!){mergePullRequest(input:{pullRequestId:$pullRequestId,expectedHeadOid:$expectedHeadOid,mergeMethod:$mergeMethod}){pullRequest{id state}}}";
+const GIT_OPERATION_STATES = ["MERGE_HEAD", "rebase-merge", "rebase-apply", "CHERRY_PICK_HEAD", "REVERT_HEAD", "sequencer"];
+const OID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+
+export type InspectLocalMergeSafetyInput = {
+	exec: Exec;
+	cwd: string;
+	expectedHead: string;
+	headFetchSource: string;
+};
+
+export type MergeMethodSelectionInput = {
+	allowedMergeMethods: readonly MergeMethod[];
+	viewerDefaultMergeMethod?: MergeMethod | null;
+};
+
+export type InspectedLocalMergeSafety = LocalMergeSafety & {
+	headOid: string;
+};
+
+export type ExecuteGitHubMergeInput = MergeMethodSelectionInput & InspectLocalMergeSafetyInput & {
+	pullRequestId: string;
+	hostname: string;
+	expectedBase: {
+		repository: string;
+		ref: string;
+		oid: string;
+	};
+	revalidateReadiness: (local: InspectedLocalMergeSafety) => Promise<void>;
+};
+
+function commandText(command: string, args: string[]): string {
+	return [command, ...args].join(" ");
+}
+
+function errorText(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function commandFailure(command: string, args: string[], detail: string): Error {
+	return new Error(`${commandText(command, args)} failed: ${detail}`);
+}
+
+async function runCommand(
+	exec: Exec,
+	cwd: string,
+	command: string,
+	args: string[],
+	allowedCodes: readonly number[] = [0],
+): Promise<ExecResult> {
+	let result: ExecResult;
+	try {
+		result = await exec(command, args, { cwd });
+	} catch (error) {
+		throw commandFailure(command, args, errorText(error));
+	}
+
+	if (result.killed || !allowedCodes.includes(result.code)) {
+		const detail = result.stderr.trim() || result.stdout.trim() || (result.killed ? "command was killed" : `exit code ${result.code}`);
+		throw commandFailure(command, args, detail);
+	}
+	return result;
+}
+
+function requiredText(value: unknown, label: string): string {
+	if (typeof value !== "string" || !value || value.trim() !== value || /[\u0000-\u001f\u007f]/.test(value)) {
+		throw new TypeError(`${label} must be a non-empty string`);
+	}
+	return value;
+}
+
+function requiredOid(value: unknown, label: string): string {
+	const parsed = requiredText(value, label);
+	if (!OID.test(parsed)) throw new TypeError(`${label} must be a full Git OID`);
+	return parsed;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function requiredOutput(result: ExecResult, label: string): string {
+	const output = result.stdout.trim();
+	if (!output) throw new Error(`${label} returned no output`);
+	return output;
+}
+
+function validateInspectionInput(input: InspectLocalMergeSafetyInput): void {
+	requiredText(input.cwd, "cwd");
+	requiredOid(input.expectedHead, "expected PR head");
+	requiredText(input.headFetchSource, "PR head fetch source");
+	if (typeof input.exec !== "function") throw new TypeError("exec must be a function");
+}
+
+async function inspectWorktree(exec: Exec, cwd: string): Promise<"clean" | "dirty"> {
+	const status = await runCommand(exec, cwd, "git", ["status", "--porcelain=v1", "--untracked-files=all"]);
+	const stateOutput = requiredOutput(
+		await runCommand(exec, cwd, "git", [
+			"rev-parse",
+			...GIT_OPERATION_STATES.flatMap((state) => ["--git-path", state]),
+		]),
+		"Git operation state paths",
+	);
+	const statePaths = stateOutput.replace(/\r\n/g, "\n").split("\n");
+	if (statePaths.length !== GIT_OPERATION_STATES.length || statePaths.some((path) => !path)) {
+		throw new Error("Git operation state path resolution returned invalid output");
+	}
+	let operationInProgress = false;
+	for (const [index, path] of statePaths.entries()) {
+		try {
+			await lstat(resolve(cwd, path));
+			operationInProgress = true;
+		} catch (error) {
+			if (isRecord(error) && error.code === "ENOENT") continue;
+			const detail = isRecord(error) && typeof error.code === "string" ? error.code : errorText(error);
+			throw new Error(`Git operation state inspection failed for ${GIT_OPERATION_STATES[index]}: ${detail}`);
+		}
+	}
+	return status.stdout.length === 0 && !operationInProgress ? "clean" : "dirty";
+}
+
+async function readLocalHead(exec: Exec, cwd: string): Promise<string> {
+	return requiredOid(
+		requiredOutput(await runCommand(exec, cwd, "git", ["rev-parse", "--verify", "HEAD^{commit}"]), "local HEAD"),
+		"local HEAD",
+	);
+}
+
+/** Inspect local state without changing branches, the index, or the worktree. */
+export async function inspectLocalMergeSafety(input: InspectLocalMergeSafetyInput): Promise<InspectedLocalMergeSafety> {
+	validateInspectionInput(input);
+
+	const worktree = await inspectWorktree(input.exec, input.cwd);
+	await runCommand(input.exec, input.cwd, "git", [
+		"fetch",
+		"--no-write-fetch-head",
+		"--no-tags",
+		"--no-recurse-submodules",
+		input.headFetchSource,
+		input.expectedHead,
+	]);
+	await runCommand(input.exec, input.cwd, "git", ["cat-file", "-e", `${input.expectedHead}^{commit}`]);
+
+	const headOid = await readLocalHead(input.exec, input.cwd);
+	if (headOid === input.expectedHead) return { worktree, head: "equal", headOid };
+
+	const localAncestor = await runCommand(
+		input.exec,
+		input.cwd,
+		"git",
+		["merge-base", "--is-ancestor", headOid, input.expectedHead],
+		[0, 1],
+	);
+	if (localAncestor.code === 0) return { worktree, head: "behind", headOid };
+
+	const expectedAncestor = await runCommand(
+		input.exec,
+		input.cwd,
+		"git",
+		["merge-base", "--is-ancestor", input.expectedHead, headOid],
+		[0, 1],
+	);
+	return { worktree, head: expectedAncestor.code === 0 ? "ahead" : "diverged", headOid };
+}
+
+function validateMergeMethods(input: MergeMethodSelectionInput): void {
+	if (!Array.isArray(input.allowedMergeMethods)) throw new TypeError("allowedMergeMethods must be an array");
+	if (input.allowedMergeMethods.some((method) => method !== "merge" && method !== "rebase" && method !== "squash")) {
+		throw new TypeError("allowedMergeMethods contains an unsupported method");
+	}
+	if (
+		input.viewerDefaultMergeMethod !== undefined &&
+		input.viewerDefaultMergeMethod !== null &&
+		input.viewerDefaultMergeMethod !== "merge" &&
+		input.viewerDefaultMergeMethod !== "rebase" &&
+		input.viewerDefaultMergeMethod !== "squash"
+	) throw new TypeError("viewerDefaultMergeMethod is unsupported");
+}
+
+export function selectMergeMethod(input: MergeMethodSelectionInput): MergeMethod {
+	validateMergeMethods(input);
+	if (input.allowedMergeMethods.length === 1) return input.allowedMergeMethods[0]!;
+	if (input.allowedMergeMethods.includes("squash")) return "squash";
+	if (
+		input.viewerDefaultMergeMethod !== undefined &&
+		input.viewerDefaultMergeMethod !== null &&
+		input.allowedMergeMethods.includes(input.viewerDefaultMergeMethod)
+	) return input.viewerDefaultMergeMethod;
+	throw new Error("No deterministic GitHub merge method is available");
+}
+
+function validateExecuteInput(input: ExecuteGitHubMergeInput): void {
+	validateInspectionInput(input);
+	requiredText(input.pullRequestId, "pullRequestId");
+	requiredText(input.hostname, "hostname");
+	if (!isRecord(input.expectedBase)) throw new TypeError("expectedBase must be an object");
+	requiredText(input.expectedBase.repository, "expected base repository");
+	requiredText(input.expectedBase.ref, "expected base ref");
+	requiredText(input.expectedBase.oid, "expected base OID");
+	if (typeof input.revalidateReadiness !== "function") throw new TypeError("revalidateReadiness must be a function");
+}
+
+function parseGraphQLResponse(output: string, action: string): Record<string, unknown> {
+	let value: unknown;
+	try {
+		value = JSON.parse(output);
+	} catch {
+		throw new Error(`${action}: invalid GraphQL output`);
+	}
+	if (!isRecord(value)) throw new Error(`${action}: invalid GraphQL output`);
+	const errors = value.errors;
+	if (errors !== undefined) {
+		if (!Array.isArray(errors)) throw new Error(`${action}: invalid GraphQL output`);
+		if (errors.length > 0) {
+			const messages = errors.map((error) => isRecord(error) && typeof error.message === "string" && error.message ? error.message : undefined);
+			if (messages.some((message) => message === undefined)) throw new Error(`${action}: invalid GraphQL errors`);
+			throw new Error(`${action}: ${messages.join("; ")}`);
+		}
+	}
+	return value;
+}
+
+function parseMergeResponse(output: string, expectedId: string): void {
+	const value = parseGraphQLResponse(output, "GitHub merge failed");
+	const data = value.data;
+	const mutation = isRecord(data) ? data.mergePullRequest : undefined;
+	const pullRequest = isRecord(mutation) ? mutation.pullRequest : undefined;
+	if (!isRecord(pullRequest)) throw new Error("GitHub merge failed: invalid GraphQL output");
+	const id = pullRequest.id;
+	const state = pullRequest.state;
+	if (typeof id !== "string" || !id || typeof state !== "string" || !state) {
+		throw new Error("GitHub merge failed: invalid GraphQL output");
+	}
+	if (id !== expectedId) throw new Error(`GitHub merge returned unexpected pull request id ${id}`);
+	if (state !== "MERGED") throw new Error(`GitHub merge returned pull request ${id} in state ${state}`);
+}
+
+export async function executeGitHubMerge(input: ExecuteGitHubMergeInput): Promise<void> {
+	validateExecuteInput(input);
+	const method = selectMergeMethod(input);
+	const local = await inspectLocalMergeSafety(input);
+	if (local.worktree !== "clean" || (local.head !== "equal" && local.head !== "behind")) {
+		throw new Error(`Local merge safety check failed: worktree is ${local.worktree}, HEAD is ${local.head}`);
+	}
+	await input.revalidateReadiness(local);
+	const finalWorktree = await inspectWorktree(input.exec, input.cwd);
+	if (finalWorktree !== "clean") {
+		throw new Error("Final local merge safety check failed: worktree is dirty");
+	}
+	const finalHead = await readLocalHead(input.exec, input.cwd);
+	if (finalHead !== local.headOid) {
+		throw new Error(`Final local merge safety check failed: HEAD changed from ${local.headOid} to ${finalHead}`);
+	}
+	const merged = await runCommand(input.exec, input.cwd, "gh", [
+		"api",
+		"graphql",
+		"--hostname",
+		input.hostname,
+		"-f",
+		`query=${MERGE_PULL_REQUEST_MUTATION}`,
+		"-F",
+		`pullRequestId=${input.pullRequestId}`,
+		"-F",
+		`expectedHeadOid=${input.expectedHead}`,
+		"-F",
+		`mergeMethod=${method.toUpperCase()}`,
+	]);
+	parseMergeResponse(requiredOutput(merged, "GitHub merge"), input.pullRequestId);
+}

package/extensions/pr-routing.ts

@@ -0,0 +1,59 @@
+export type PullRequestLifecycle = "open" | "merged" | "closed";
+export type CiStatus = "none" | "running" | "success" | "failure";
+export type ReviewReadiness = "ready" | "pending";
+export type PolicyReadiness = "ready" | "pending";
+export type LocalWorktree = "clean" | "dirty";
+export type LocalHeadRelation = "equal" | "behind" | "ahead" | "diverged";
+
+export type PullRequestConditions = {
+	draft: boolean;
+	baseUpdateRequired: boolean;
+	conflict: boolean;
+	changesRequested: boolean;
+	unresolvedThreads: number;
+	ci: CiStatus;
+	review: ReviewReadiness;
+	policy: PolicyReadiness;
+};
+
+export type LocalMergeSafety = {
+	worktree: LocalWorktree;
+	head: LocalHeadRelation;
+};
+
+export type PullRequest = {
+	lifecycle: PullRequestLifecycle;
+	conditions: PullRequestConditions;
+	local: LocalMergeSafety;
+};
+
+export type NextStep = "create" | "none" | "update-branch" | "sweep" | "fix-ci" | "merge";
+
+function localMutationSafe(local: LocalMergeSafety): boolean {
+	return local.worktree === "clean" && local.head === "equal";
+}
+
+function localMergeSafe(local: LocalMergeSafety): boolean {
+	return local.worktree === "clean" && (local.head === "equal" || local.head === "behind");
+}
+
+export function deriveNextStep(pullRequest: PullRequest | null): NextStep {
+	if (pullRequest === null) return "create";
+
+	const { lifecycle, conditions, local } = pullRequest;
+	if (lifecycle !== "open" || conditions.draft) return "none";
+	if (conditions.baseUpdateRequired || conditions.conflict) {
+		return localMutationSafe(local) ? "update-branch" : "none";
+	}
+	if (conditions.changesRequested || conditions.unresolvedThreads > 0) {
+		return localMutationSafe(local) ? "sweep" : "none";
+	}
+	if (conditions.ci === "failure") return localMutationSafe(local) ? "fix-ci" : "none";
+	if (
+		conditions.ci === "running" ||
+		conditions.review === "pending" ||
+		conditions.policy === "pending" ||
+		!localMergeSafe(local)
+	) return "none";
+	return "merge";
+}

package/extensions/pr-ui.ts

@@ -0,0 +1,98 @@
+import { getCapabilities, hyperlink } from "@earendil-works/pi-tui";
+import {
+	deriveNextStep,
+	type NextStep,
+	type PullRequest,
+} from "./pr-routing.ts";
+
+export type PrDisplayInput = PullRequest & {
+	number: number;
+	url: string | URL;
+	approved: boolean;
+};
+
+export type PrStatusColor = "accent" | "warning" | "success" | "error" | "dim";
+
+export type PrFooter = {
+	number: number;
+	url: string;
+	text: string;
+	color: PrStatusColor;
+};
+
+export type PrDisplay = {
+	nextStep: NextStep;
+	footer?: PrFooter;
+	widget?: string;
+};
+
+export type PrTheme = {
+	fg(color: PrStatusColor | "text", text: string): string;
+};
+
+function footerStatus(input: PrDisplayInput, nextStep: NextStep): Pick<PrFooter, "text" | "color"> {
+	if (input.lifecycle === "merged") return { text: "merged", color: "success" };
+	if (input.lifecycle === "closed") return { text: "closed", color: "dim" };
+
+	const { conditions } = input;
+	if (conditions.draft) return { text: "draft", color: "warning" };
+	if (conditions.conflict) return { text: "merge conflict", color: "error" };
+	if (conditions.baseUpdateRequired) return { text: "base update required", color: "warning" };
+	if (conditions.unresolvedThreads > 0) return { text: `${conditions.unresolvedThreads} unresolved`, color: "warning" };
+	if (conditions.changesRequested) return { text: "changes requested", color: "error" };
+	if (conditions.ci === "failure") return { text: "CI failed", color: "error" };
+	if (conditions.ci === "running") return { text: "CI running", color: "warning" };
+	if (nextStep === "merge") return { text: "merge-ready", color: "success" };
+	if (input.approved) return { text: "approved", color: "success" };
+	return { text: "open", color: "accent" };
+}
+
+function widgetText(input: PrDisplayInput, nextStep: NextStep): string | undefined {
+	switch (nextStep) {
+		case "update-branch":
+			return input.conditions.conflict
+				? "Run /pr to resolve merge conflict"
+				: "Run /pr to update branch";
+		case "sweep":
+			return "Run /pr to address review feedback";
+		case "fix-ci":
+			return "Run /pr to fix CI";
+		case "merge":
+			return "Run /pr to merge pull request";
+		case "create":
+		case "none":
+			return undefined;
+	}
+}
+
+export function projectPrDisplay(input: PrDisplayInput | null, hasLocalCommit = false): PrDisplay {
+	const nextStep = deriveNextStep(input);
+	if (input === null) {
+		return {
+			nextStep,
+			widget: hasLocalCommit ? "Run /pr to create pull request" : undefined,
+		};
+	}
+
+	const status = footerStatus(input, nextStep);
+	return {
+		nextStep,
+		footer: {
+			number: input.number,
+			url: typeof input.url === "string" ? input.url : input.url.href,
+			...status,
+		},
+		widget: widgetText(input, nextStep),
+	};
+}
+
+export function formatPrFooter(display: PrDisplay, theme: PrTheme): string | undefined {
+	if (!display.footer) return undefined;
+	const prText = theme.fg("text", `PR #${display.footer.number}`);
+	const link = getCapabilities().hyperlinks ? hyperlink(prText, display.footer.url) : prText;
+	return `${link} · ${theme.fg(display.footer.color, display.footer.text)}`;
+}
+
+export function formatPrWidget(display: PrDisplay): string | undefined {
+	return display.widget;
+}