@rumen.rusanov/pi-github 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-github contributors
+
+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,103 @@
+# pi-github
+
+A [`pi`](https://pi.dev) extension that browses the current repo's open GitHub Pull Requests and Issues from a full-screen TUI inside `pi` — list, drill into details, and (for PRs) approve or merge — without leaving your terminal.
+
+## Prerequisites
+
+- The [`gh` CLI](https://cli.github.com) installed and authenticated (`gh auth login`)
+- The current directory must be a git repository with a GitHub remote
+
+`/github` checks both of these on invocation and shows a clear error instead of opening the screen if either is missing.
+
+## Usage
+
+Run `/github` inside `pi`. It detects `owner/repo` from your git remote and opens a full-screen browser for that repo's open Pull Requests and Issues, sorted most-recently-updated first.
+
+### Keybindings
+
+**List view** (Pull Requests / Issues):
+
+| Key | Action |
+|-----|--------|
+| `↑` / `↓` | Move selection |
+| `Enter` | Open the selected item's detail view |
+| `Tab` | Switch between Pull Requests and Issues |
+| _(type)_ | Fuzzy-filter the visible list by title or number |
+| `Backspace` | Remove the last filter character |
+| `r` | Refresh the current section from GitHub |
+| `Esc` | Clear the filter, then close the screen |
+
+**Detail view** (Pull Request or Issue):
+
+| Key | Action |
+|-----|--------|
+| `↑` / `↓` / `PageUp` / `PageDown` | Scroll |
+| `r` | Refresh this item |
+| `a` | Approve (Pull Requests only) |
+| `m` | Merge (Pull Requests only) |
+| `Esc` | Back to the list |
+
+Issues are read-only — no approve/merge actions are shown on the Issue detail screen.
+
+### Approve
+
+`a` on a PR detail screen shows a confirm dialog naming the PR number, title, and the GitHub account the action will run as. Confirming runs `gh pr review --approve` and refreshes the detail view.
+
+### Merge
+
+`m` on a PR detail screen detects which merge methods the repository allows (squash / merge commit / rebase). If more than one is allowed, you're prompted to pick one first. It then shows a confirm dialog naming the PR, chosen method, and acting account before running `gh pr merge`. `pi-github` doesn't pre-check CI or review status — a blocked merge simply surfaces GitHub's own error.
+
+## Configuration
+
+The number of PRs/Issues fetched per section is configurable (default: **20**). Set it in `.pi/settings.json` (project) or `~/.pi/agent/settings.json` (global) under a `pi-github` key — project settings take precedence:
+
+```json
+{
+  "pi-github": {
+    "fetchLimit": 50
+  }
+}
+```
+
+## Installing locally for development
+
+Add a project-local extension entry to `.pi/settings.json`:
+
+```json
+{
+  "extensions": ["/absolute/path/to/pi-github/src/index.ts"]
+}
+```
+
+Or symlink the package into `.pi/extensions/`:
+
+```bash
+mkdir -p .pi/extensions
+ln -s /absolute/path/to/pi-github .pi/extensions/pi-github
+```
+
+Either way, run `npm install` in this directory first (needed for typechecking and tests; `pi` itself loads the TypeScript source directly via `jiti`, no build step required). After editing the source, run `/reload` inside `pi` to pick up changes without restarting.
+
+Once this repository has a pushed remote, it can also be installed with:
+
+```bash
+pi install git:github.com/hpstuff/pi-github
+```
+
+Once published to npm, it can also be installed with:
+
+```bash
+pi install npm:@rumen.rusanov/pi-github
+```
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,36 @@
+{
+	"name": "@rumen.rusanov/pi-github",
+	"version": "0.1.0",
+	"private": false,
+	"type": "module",
+	"license": "MIT",
+	"description": "Browse and act on the current repo's open GitHub Pull Requests and Issues from a full-screen pi TUI.",
+	"keywords": ["pi-package"],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/hpstuff/pi-github.git"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"test": "vitest run"
+	},
+	"pi": {
+		"extensions": ["./src/index.ts"]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*",
+		"typebox": "*"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-coding-agent": "^0.84.4",
+		"@earendil-works/pi-tui": "^0.84.4",
+		"typebox": "^1.3.24",
+		"typescript": "^5.7.0",
+		"vitest": "^2.1.0",
+		"@types/node": "^22.10.0"
+	}
+}

package/src/format.ts

@@ -0,0 +1,22 @@
+const UNITS: Array<{ limit: number; divisor: number; suffix: string }> = [
+	{ limit: 60, divisor: 1, suffix: "s" },
+	{ limit: 60 * 60, divisor: 60, suffix: "m" },
+	{ limit: 60 * 60 * 24, divisor: 60 * 60, suffix: "h" },
+	{ limit: 60 * 60 * 24 * 30, divisor: 60 * 60 * 24, suffix: "d" },
+	{ limit: 60 * 60 * 24 * 365, divisor: 60 * 60 * 24 * 30, suffix: "mo" },
+];
+
+/** Formats an ISO timestamp as a relative "Xs/m/h/d/mo/y ago" string, given the reference time. */
+export function relativeTime(iso: string, now: Date = new Date()): string {
+	const deltaSeconds = Math.floor((now.getTime() - new Date(iso).getTime()) / 1000);
+	if (deltaSeconds < 1) return "just now";
+
+	for (const unit of UNITS) {
+		if (deltaSeconds < unit.limit) {
+			return `${Math.floor(deltaSeconds / unit.divisor)}${unit.suffix} ago`;
+		}
+	}
+
+	const years = Math.floor(deltaSeconds / (60 * 60 * 24 * 365));
+	return `${years}y ago`;
+}

package/src/gh-cli.ts

@@ -0,0 +1,23 @@
+import type { ExecFn } from "./types.ts";
+
+export type CheckResult = { ok: true } | { ok: false; error: string };
+
+export async function checkGhInstalled(exec: ExecFn): Promise<CheckResult> {
+	try {
+		const result = await exec("gh", ["--version"], { timeout: 5_000 });
+		if (result.code !== 0) {
+			return { ok: false, error: "The `gh` CLI is installed but `gh --version` failed. Install it from https://cli.github.com." };
+		}
+		return { ok: true };
+	} catch {
+		return { ok: false, error: "The `gh` CLI is not installed. Install it from https://cli.github.com." };
+	}
+}
+
+export async function checkGhAuthenticated(exec: ExecFn, cwd: string): Promise<CheckResult> {
+	const result = await exec("gh", ["auth", "status"], { cwd, timeout: 5_000 });
+	if (result.code !== 0) {
+		return { ok: false, error: "The `gh` CLI is not authenticated. Run `gh auth login` and try again." };
+	}
+	return { ok: true };
+}

package/src/gh-data.ts

@@ -0,0 +1,393 @@
+import type {
+	CheckRun,
+	CheckState,
+	Comment,
+	ExecFn,
+	FileChange,
+	IssueDetail,
+	IssueSummary,
+	MergeMethod,
+	PullRequestDetail,
+	PullRequestSummary,
+	Result,
+	Review,
+	ReviewState,
+} from "./types.ts";
+
+export type GhResult<T> = Result<T>;
+
+interface RawActor {
+	login?: string;
+	name?: string;
+}
+
+interface RawLabel {
+	name: string;
+}
+
+interface RawComment {
+	author?: RawActor;
+	body?: string;
+	createdAt?: string;
+}
+
+interface RawCheckRun {
+	__typename?: string;
+	name?: string;
+	context?: string;
+	status?: string;
+	conclusion?: string | null;
+	state?: string;
+}
+
+interface RawReview {
+	author?: RawActor;
+	state?: string;
+}
+
+interface RawFile {
+	path: string;
+	additions: number;
+	deletions: number;
+}
+
+interface RawPrListItem {
+	number: number;
+	title: string;
+	author?: RawActor;
+	isDraft?: boolean;
+	updatedAt: string;
+	statusCheckRollup?: RawCheckRun[];
+	latestReviews?: RawReview[];
+}
+
+interface RawIssueListItem {
+	number: number;
+	title: string;
+	author?: RawActor;
+	updatedAt: string;
+	comments?: RawComment[];
+	labels?: RawLabel[];
+}
+
+interface RawPrDetail {
+	number: number;
+	title: string;
+	author?: RawActor;
+	state: string;
+	isDraft?: boolean;
+	labels?: RawLabel[];
+	assignees?: RawActor[];
+	createdAt: string;
+	updatedAt: string;
+	body?: string;
+	comments?: RawComment[];
+	baseRefName: string;
+	headRefName: string;
+	statusCheckRollup?: RawCheckRun[];
+	latestReviews?: RawReview[];
+	files?: RawFile[];
+}
+
+interface RawIssueDetail {
+	number: number;
+	title: string;
+	author?: RawActor;
+	state: string;
+	labels?: RawLabel[];
+	assignees?: RawActor[];
+	createdAt: string;
+	updatedAt: string;
+	body?: string;
+	comments?: RawComment[];
+}
+
+interface RawRepoView {
+	squashMergeAllowed?: boolean;
+	mergeCommitAllowed?: boolean;
+	rebaseMergeAllowed?: boolean;
+}
+
+function actorLogin(actor: RawActor | undefined): string {
+	return actor?.login ?? "unknown";
+}
+
+function mapCheck(check: RawCheckRun): CheckRun {
+	const name = check.name ?? check.context ?? "check";
+	if (check.status !== undefined) {
+		// CheckRun: status is QUEUED | IN_PROGRESS | COMPLETED; conclusion set once COMPLETED.
+		if (check.status !== "COMPLETED") return { name, state: "pending" };
+		const conclusion = (check.conclusion ?? "").toUpperCase();
+		if (conclusion === "SUCCESS" || conclusion === "NEUTRAL" || conclusion === "SKIPPED") {
+			return { name, state: "pass" };
+		}
+		return { name, state: "fail" };
+	}
+	// StatusContext: state is SUCCESS | PENDING | FAILURE | ERROR.
+	const state = (check.state ?? "").toUpperCase();
+	if (state === "SUCCESS") return { name, state: "pass" };
+	if (state === "PENDING" || state === "EXPECTED") return { name, state: "pending" };
+	return { name, state: "fail" };
+}
+
+function overallCheckState(rollup: RawCheckRun[] | undefined): CheckState | "none" {
+	if (!rollup || rollup.length === 0) return "none";
+	const mapped = rollup.map(mapCheck);
+	if (mapped.some((c) => c.state === "fail")) return "fail";
+	if (mapped.some((c) => c.state === "pending")) return "pending";
+	return "pass";
+}
+
+function reviewCounts(reviews: RawReview[] | undefined): { approvals: number; changesRequested: number } {
+	const list = reviews ?? [];
+	return {
+		approvals: list.filter((r) => r.state === "APPROVED").length,
+		changesRequested: list.filter((r) => r.state === "CHANGES_REQUESTED").length,
+	};
+}
+
+async function runGhJson<T>(exec: ExecFn, args: string[], cwd: string): Promise<GhResult<T>> {
+	const result = await exec("gh", args, { cwd, timeout: 15_000 });
+	if (result.code !== 0) {
+		return { ok: false, error: result.stderr.trim() || `gh exited with code ${result.code}` };
+	}
+	try {
+		return { ok: true, data: JSON.parse(result.stdout) as T };
+	} catch {
+		return { ok: false, error: "Failed to parse gh output as JSON." };
+	}
+}
+
+export async function fetchPullRequests(
+	exec: ExecFn,
+	options: { repo: string; cwd: string; limit: number },
+): Promise<GhResult<PullRequestSummary[]>> {
+	const result = await runGhJson<RawPrListItem[]>(
+		exec,
+		[
+			"pr",
+			"list",
+			"--repo",
+			options.repo,
+			"--state",
+			"open",
+			"--search",
+			"sort:updated-desc",
+			"--limit",
+			String(options.limit),
+			"--json",
+			"number,title,author,updatedAt,isDraft,statusCheckRollup,latestReviews",
+		],
+		options.cwd,
+	);
+	if (!result.ok) return result;
+
+	const items: PullRequestSummary[] = result.data
+		.map((pr) => {
+			const { approvals, changesRequested } = reviewCounts(pr.latestReviews);
+			return {
+				number: pr.number,
+				title: pr.title,
+				author: actorLogin(pr.author),
+				isDraft: pr.isDraft ?? false,
+				checkState: overallCheckState(pr.statusCheckRollup),
+				approvals,
+				changesRequested,
+				updatedAt: pr.updatedAt,
+			};
+		})
+		.sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : -1));
+
+	return { ok: true, data: items };
+}
+
+export async function fetchIssues(
+	exec: ExecFn,
+	options: { repo: string; cwd: string; limit: number },
+): Promise<GhResult<IssueSummary[]>> {
+	const result = await runGhJson<RawIssueListItem[]>(
+		exec,
+		[
+			"issue",
+			"list",
+			"--repo",
+			options.repo,
+			"--state",
+			"open",
+			"--search",
+			"sort:updated-desc",
+			"--limit",
+			String(options.limit),
+			"--json",
+			"number,title,author,updatedAt,comments,labels",
+		],
+		options.cwd,
+	);
+	if (!result.ok) return result;
+
+	const items: IssueSummary[] = result.data
+		.map((issue) => ({
+			number: issue.number,
+			title: issue.title,
+			author: actorLogin(issue.author),
+			commentCount: issue.comments?.length ?? 0,
+			labels: (issue.labels ?? []).map((l) => l.name),
+			updatedAt: issue.updatedAt,
+		}))
+		.sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : -1));
+
+	return { ok: true, data: items };
+}
+
+function mapComment(comment: RawComment): Comment {
+	return {
+		author: actorLogin(comment.author),
+		body: comment.body ?? "",
+		createdAt: comment.createdAt ?? "",
+	};
+}
+
+export async function fetchPullRequestDetail(
+	exec: ExecFn,
+	options: { repo: string; cwd: string; number: number },
+): Promise<GhResult<PullRequestDetail>> {
+	const result = await runGhJson<RawPrDetail>(
+		exec,
+		[
+			"pr",
+			"view",
+			String(options.number),
+			"--repo",
+			options.repo,
+			"--json",
+			"number,title,author,state,isDraft,labels,assignees,createdAt,updatedAt,body,comments,baseRefName,headRefName,statusCheckRollup,latestReviews,files",
+		],
+		options.cwd,
+	);
+	if (!result.ok) return result;
+
+	const pr = result.data;
+	const reviews: Review[] = (pr.latestReviews ?? [])
+		.filter((r) => r.state && r.state !== "PENDING" && r.state !== "COMMENTED")
+		.map((r) => ({ author: actorLogin(r.author), state: (r.state as ReviewState) ?? "PENDING" }));
+
+	return {
+		ok: true,
+		data: {
+			number: pr.number,
+			title: pr.title,
+			author: actorLogin(pr.author),
+			state: pr.state,
+			isDraft: pr.isDraft ?? false,
+			labels: (pr.labels ?? []).map((l) => l.name),
+			assignees: (pr.assignees ?? []).map(actorLogin),
+			createdAt: pr.createdAt,
+			updatedAt: pr.updatedAt,
+			body: pr.body ?? "",
+			comments: (pr.comments ?? []).map(mapComment),
+			baseRefName: pr.baseRefName,
+			headRefName: pr.headRefName,
+			checks: (pr.statusCheckRollup ?? []).map(mapCheck),
+			reviews,
+			files: (pr.files ?? []).map((f: FileChange) => ({ path: f.path, additions: f.additions, deletions: f.deletions })),
+		},
+	};
+}
+
+export async function fetchIssueDetail(
+	exec: ExecFn,
+	options: { repo: string; cwd: string; number: number },
+): Promise<GhResult<IssueDetail>> {
+	const result = await runGhJson<RawIssueDetail>(
+		exec,
+		[
+			"issue",
+			"view",
+			String(options.number),
+			"--repo",
+			options.repo,
+			"--json",
+			"number,title,author,state,labels,assignees,createdAt,updatedAt,body,comments",
+		],
+		options.cwd,
+	);
+	if (!result.ok) return result;
+
+	const issue = result.data;
+	return {
+		ok: true,
+		data: {
+			number: issue.number,
+			title: issue.title,
+			author: actorLogin(issue.author),
+			state: issue.state,
+			labels: (issue.labels ?? []).map((l) => l.name),
+			assignees: (issue.assignees ?? []).map(actorLogin),
+			createdAt: issue.createdAt,
+			updatedAt: issue.updatedAt,
+			body: issue.body ?? "",
+			comments: (issue.comments ?? []).map(mapComment),
+		},
+	};
+}
+
+export async function getAllowedMergeMethods(
+	exec: ExecFn,
+	options: { repo: string; cwd: string },
+): Promise<GhResult<MergeMethod[]>> {
+	const result = await runGhJson<RawRepoView>(
+		exec,
+		["repo", "view", options.repo, "--json", "squashMergeAllowed,mergeCommitAllowed,rebaseMergeAllowed"],
+		options.cwd,
+	);
+	if (!result.ok) return result;
+
+	const methods: MergeMethod[] = [];
+	if (result.data.squashMergeAllowed) methods.push("squash");
+	if (result.data.mergeCommitAllowed) methods.push("merge");
+	if (result.data.rebaseMergeAllowed) methods.push("rebase");
+
+	return { ok: true, data: methods };
+}
+
+export async function getCurrentAccount(exec: ExecFn, cwd: string): Promise<string | undefined> {
+	const result = await exec("gh", ["api", "user", "--jq", ".login"], { cwd, timeout: 10_000 });
+	if (result.code !== 0) return undefined;
+	const login = result.stdout.trim();
+	return login.length > 0 ? login : undefined;
+}
+
+export async function approvePullRequest(
+	exec: ExecFn,
+	options: { repo: string; cwd: string; number: number },
+): Promise<GhResult<true>> {
+	const result = await exec("gh", ["pr", "review", String(options.number), "--repo", options.repo, "--approve"], {
+		cwd: options.cwd,
+		timeout: 15_000,
+	});
+	if (result.code !== 0) {
+		return { ok: false, error: result.stderr.trim() || `gh exited with code ${result.code}` };
+	}
+	return { ok: true, data: true };
+}
+
+const MERGE_FLAG: Record<MergeMethod, string> = {
+	squash: "--squash",
+	merge: "--merge",
+	rebase: "--rebase",
+};
+
+export async function mergePullRequest(
+	exec: ExecFn,
+	options: { repo: string; cwd: string; number: number; method: MergeMethod },
+): Promise<GhResult<true>> {
+	const result = await exec(
+		"gh",
+		["pr", "merge", String(options.number), "--repo", options.repo, MERGE_FLAG[options.method]],
+		{ cwd: options.cwd, timeout: 30_000 },
+	);
+	if (result.code !== 0) {
+		return { ok: false, error: result.stderr.trim() || `gh exited with code ${result.code}` };
+	}
+	return { ok: true, data: true };
+}

package/src/index.ts

@@ -0,0 +1,47 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { checkGhAuthenticated, checkGhInstalled } from "./gh-cli.ts";
+import { detectRepo } from "./repo.ts";
+import { getFetchLimit } from "./settings.ts";
+import { GithubApp } from "./ui/app.ts";
+
+export default function (pi: ExtensionAPI) {
+	pi.registerCommand("github", {
+		description: "Browse this repo's open GitHub Pull Requests and Issues",
+		handler: async (_args, ctx) => {
+			const exec = pi.exec;
+
+			const installed = await checkGhInstalled(exec);
+			if (!installed.ok) {
+				ctx.ui.notify(installed.error, "error");
+				return;
+			}
+
+			const authenticated = await checkGhAuthenticated(exec, ctx.cwd);
+			if (!authenticated.ok) {
+				ctx.ui.notify(authenticated.error, "error");
+				return;
+			}
+
+			const repoResult = await detectRepo(exec, ctx.cwd);
+			if (!repoResult.ok) {
+				ctx.ui.notify(repoResult.error, "error");
+				return;
+			}
+
+			const limit = await getFetchLimit({ cwd: ctx.cwd });
+
+			await ctx.ui.custom<void>((tui, theme, _keybindings, done) => {
+				return new GithubApp({
+					repo: repoResult.repo,
+					cwd: ctx.cwd,
+					exec,
+					limit,
+					ui: ctx.ui,
+					theme,
+					tui,
+					done,
+				});
+			});
+		},
+	});
+}

package/src/repo.ts

@@ -0,0 +1,54 @@
+import type { ExecFn } from "./types.ts";
+
+export type RepoResolution = { ok: true; repo: string } | { ok: false; error: string };
+
+export function parseGitHubRemote(remoteUrl: string): string | undefined {
+	const sshMatch = remoteUrl.match(/^git@github\.com:([^/]+\/[^/]+?)(?:\.git)?$/);
+	if (sshMatch) return sshMatch[1];
+
+	const sshProtoMatch = remoteUrl.match(/^ssh:\/\/git@github\.com\/([^/]+\/[^/]+?)(?:\.git)?$/);
+	if (sshProtoMatch) return sshProtoMatch[1];
+
+	const httpsMatch = remoteUrl.match(/^https?:\/\/github\.com\/([^/]+\/[^/]+?)(?:\.git)?$/);
+	if (httpsMatch) return httpsMatch[1];
+
+	return undefined;
+}
+
+/** Picks the URL to check from `git remote -v` output: prefers "origin", else the first remote listed. */
+export function pickRemoteUrl(remoteVOutput: string): string | undefined {
+	let firstUrl: string | undefined;
+	let originUrl: string | undefined;
+
+	for (const line of remoteVOutput.split("\n")) {
+		const columns = line.trim().split(/\s+/);
+		const name = columns[0];
+		const url = columns[1];
+		if (!name || !url) continue;
+		firstUrl ??= url;
+		if (name === "origin") {
+			originUrl ??= url;
+		}
+	}
+
+	return originUrl ?? firstUrl;
+}
+
+export async function detectRepo(exec: ExecFn, cwd: string): Promise<RepoResolution> {
+	const result = await exec("git", ["remote", "-v"], { cwd, timeout: 5_000 });
+	if (result.code !== 0) {
+		return { ok: false, error: "Not a git repository (or no remotes configured)." };
+	}
+
+	const remoteUrl = pickRemoteUrl(result.stdout);
+	if (!remoteUrl) {
+		return { ok: false, error: "This repository has no git remote configured." };
+	}
+
+	const repo = parseGitHubRemote(remoteUrl);
+	if (!repo) {
+		return { ok: false, error: "This repository's remote is not a GitHub repository." };
+	}
+
+	return { ok: true, repo };
+}