@henryqw/pi-pr 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henry Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# `@henryqw/pi-pr`
+
+Show the current branch pull request's lifecycle, CI, mergeability, and review state in the Pi footer.
+
+## Install
+
+```bash
+pi install npm:@henryqw/pi-pr
+```
+
+Requires authenticated GitHub CLI access (`gh auth login`) in a GitHub repository checkout.
+
+## Use
+
+| Surface | Type | Purpose |
+| --- | --- | --- |
+| Footer | UI | Show the current branch pull request. |
+| `/pr` | command | Open the current branch pull request in a browser. |
+
+Each entry is one linked `PR #number` plus one plain-language state: `draft`, `open`, `approved`, `CI running`, `CI failed`, `changes requested`, `merge conflict`, `merged`, or `closed`. Status priority favors action: merge conflict, changes requested, CI failure, then CI progress. Colors support text; they do not carry meaning alone.
+
+The status loads at session start, polls every 30 seconds, and refreshes after an agent successfully runs `gh pr create` or after `/pr`. No pull request leaves the footer blank.
+
+## Remove
+
+```bash
+pi remove npm:@henryqw/pi-pr
+```
+
+## Development
+
+```bash
+npm test --workspace @henryqw/pi-pr
+npm run typecheck --workspace @henryqw/pi-pr
+npm run pack:check --workspace @henryqw/pi-pr
+```

package/extensions/pr.ts

@@ -0,0 +1,183 @@
+import {
+	isBashToolResult,
+	type ExtensionAPI,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { hyperlink } from "@earendil-works/pi-tui";
+
+const POLL_INTERVAL_MS = 30_000;
+const PR_FIELDS = "number,url,state,isDraft,mergeable,reviewDecision,statusCheckRollup";
+const GH_PR_CREATE = /(?:^|[;&|]\s*|\n\s*)gh\s+pr\s+create(?=\s|$|[;&|])/;
+const FAILED_CHECK_STATES = new Set(["ACTION_REQUIRED", "CANCELLED", "ERROR", "FAILURE", "STALE", "STARTUP_FAILURE", "TIMED_OUT"]);
+const SUCCESSFUL_CHECK_STATES = new Set(["NEUTRAL", "SKIPPED", "SUCCESS"]);
+
+type Lifecycle = "D" | "O" | "M" | "C";
+type CiStatus = "success" | "running" | "failure" | "none";
+type PullRequest = {
+	number: number;
+	url: string;
+	lifecycle: Lifecycle;
+	mergeable: string;
+	reviewDecision: string | null;
+	statusCheckRollup: unknown[];
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function pullRequestUrl(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	try {
+		const url = new URL(value);
+		return url.protocol === "http:" || url.protocol === "https:" ? url.href : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export function parsePullRequest(value: unknown): PullRequest | undefined {
+	if (!isRecord(value)) return undefined;
+
+	const number = value.number;
+	const url = pullRequestUrl(value.url);
+	const state = value.state;
+	const isDraft = value.isDraft;
+	const mergeable = value.mergeable;
+	const reviewDecision = value.reviewDecision;
+	const statusCheckRollup = value.statusCheckRollup;
+	if (
+		typeof number !== "number" || !Number.isSafeInteger(number) || number <= 0 || !url || typeof state !== "string" ||
+		typeof isDraft !== "boolean" || typeof mergeable !== "string" ||
+		(reviewDecision !== null && typeof reviewDecision !== "string") ||
+		(statusCheckRollup !== null && !Array.isArray(statusCheckRollup))
+	) return undefined;
+
+	const lifecycle = state === "MERGED" ? "M" : state === "CLOSED" ? "C" : state === "OPEN" ? isDraft ? "D" : "O" : undefined;
+	if (!lifecycle) return undefined;
+
+	return { number, url, lifecycle, mergeable, reviewDecision, statusCheckRollup: statusCheckRollup ?? [] };
+}
+
+function ciStatus(rollup: unknown[]): CiStatus {
+	if (!rollup.length) return "none";
+	let running = false;
+	for (const check of rollup) {
+		const record = isRecord(check) ? check : undefined;
+		const value = record?.conclusion ?? record?.state ?? record?.status;
+		const state = typeof value === "string" ? value.toUpperCase() : undefined;
+		if (state && FAILED_CHECK_STATES.has(state)) return "failure";
+		if (!state || !SUCCESSFUL_CHECK_STATES.has(state)) running = true;
+	}
+	return running ? "running" : "success";
+}
+
+type Status = {
+	text: string;
+	color: "accent" | "warning" | "success" | "error" | "dim";
+};
+
+function statusFor(pullRequest: PullRequest, ci: CiStatus): Status {
+	if (pullRequest.lifecycle === "M") return { text: "merged", color: "success" };
+	if (pullRequest.lifecycle === "C") return { text: "closed", color: "dim" };
+	if (pullRequest.mergeable === "CONFLICTING") return { text: "merge conflict", color: "error" };
+	if (pullRequest.reviewDecision === "CHANGES_REQUESTED") return { text: "changes requested", color: "error" };
+	if (ci === "failure") return { text: "CI failed", color: "error" };
+	if (ci === "running") return { text: "CI running", color: "warning" };
+	if (pullRequest.lifecycle === "D") return { text: "draft", color: "warning" };
+	if (pullRequest.reviewDecision === "APPROVED") return { text: "approved", color: "success" };
+	return { text: "open", color: "accent" };
+}
+
+export function formatPullRequest(pullRequest: PullRequest, theme: ExtensionContext["ui"]["theme"]): string {
+	const link = hyperlink(theme.fg("text", `PR #${pullRequest.number}`), pullRequest.url);
+	const status = statusFor(pullRequest, ciStatus(pullRequest.statusCheckRollup));
+	return `${link} · ${theme.fg(status.color, status.text)}`;
+}
+
+export default function pullRequestExtension(pi: ExtensionAPI): void {
+	let context: ExtensionContext | undefined;
+	let timer: ReturnType<typeof setInterval> | undefined;
+	let active: AbortController | undefined;
+	let queued = false;
+
+	const stop = () => {
+		context = undefined;
+		queued = false;
+		if (timer !== undefined) clearInterval(timer);
+		timer = undefined;
+		active?.abort();
+		active = undefined;
+	};
+
+	const refresh = async (afterActive = false): Promise<void> => {
+		const ctx = context;
+		if (!ctx) return;
+		if (active) {
+			queued ||= afterActive;
+			return;
+		}
+
+		const controller = new AbortController();
+		active = controller;
+		try {
+			const result = await pi.exec(
+				"gh",
+				["pr", "view", "--json", PR_FIELDS],
+				{ cwd: ctx.cwd, signal: controller.signal, timeout: 10_000 },
+			);
+			if (controller.signal.aborted || context !== ctx) return;
+			if (result.code !== 0) {
+				ctx.ui.setStatus("pi-pr", undefined);
+				return;
+			}
+
+			const pullRequest = parsePullRequest(JSON.parse(result.stdout));
+			ctx.ui.setStatus("pi-pr", pullRequest ? formatPullRequest(pullRequest, ctx.ui.theme) : undefined);
+		} catch {
+			if (!controller.signal.aborted && context === ctx) ctx.ui.setStatus("pi-pr", undefined);
+		} finally {
+			if (active !== controller) return;
+			active = undefined;
+			if (queued) {
+				queued = false;
+				await refresh();
+			}
+		}
+	};
+
+	pi.on("session_start", async (_event, ctx) => {
+		if (!ctx.hasUI) return;
+		stop();
+		context = ctx;
+		await refresh();
+		if (context === ctx) timer = setInterval(() => { void refresh(); }, POLL_INTERVAL_MS);
+	});
+
+	pi.on("session_shutdown", stop);
+
+	pi.on("tool_result", async (event, ctx) => {
+		if (!ctx.hasUI || event.isError || !isBashToolResult(event)) return;
+		const command = event.input.command;
+		if (typeof command === "string" && GH_PR_CREATE.test(command)) await refresh(true);
+	});
+
+	pi.registerCommand("pr", {
+		description: "Open the pull request for the current branch",
+		handler: async (_args, ctx) => {
+			if (!ctx.hasUI) return;
+			let result;
+			try {
+				result = await pi.exec("gh", ["pr", "view", "--web"], { cwd: ctx.cwd, signal: ctx.signal, timeout: 10_000 });
+			} catch (error) {
+				void refresh(true);
+				throw new Error(`Open pull request failed: ${error instanceof Error ? error.message : String(error)}`);
+			}
+			void refresh(true);
+			if (result.code !== 0) {
+				const detail = result.stderr.trim() || result.stdout.trim() || (result.killed ? "command was cancelled" : `exit code ${result.code}`);
+				throw new Error(`Open pull request failed: ${detail}`);
+			}
+		},
+	});
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@henryqw/pi-pr",
+  "version": "0.1.0",
+  "description": "Show the current branch pull request status in the Pi footer.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "github",
+    "pull-request",
+    "footer"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "license": "MIT",
+  "files": [
+    "extensions",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.ts",
+    "typecheck": "tsc --noEmit --allowImportingTsExtensions --target ES2022 --module NodeNext --moduleResolution NodeNext --skipLibCheck extensions/*.ts test/*.test.ts",
+    "pack:check": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "@earendil-works/pi-tui": "^0.84.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HenryQW/pi-packages.git",
+    "directory": "packages/pi-pr"
+  },
+  "bugs": {
+    "url": "https://github.com/HenryQW/pi-packages/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/pr.ts"
+    ]
+  }
+}