@plannotator/pi-extension 0.16.7 → 0.17.1

package/generated/resolve-file.ts

@@ -79,6 +79,20 @@ function isSearchableMarkdownPath(input: string): boolean {
 	return MARKDOWN_PATH_REGEX.test(input.trim());
 }
 
+function stripWrappingQuotes(input: string): string {
+	if (input.length < 2) {
+		return input;
+	}
+
+	const first = input[0];
+	const last = input[input.length - 1];
+	if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+		return input.slice(1, -1);
+	}
+
+	return input;
+}
+
 /** Check if a path looks like a Windows absolute path (e.g. C:\ or C:/) */
 function hasWindowsDriveLetter(input: string): boolean {
 	return /^[a-zA-Z]:[/\\]/.test(input);
@@ -156,12 +170,10 @@ export function isAbsoluteMarkdownPath(
  * @param input - User-provided path (absolute, relative, or bare filename)
  * @param projectRoot - Project root directory to search within
  */
-export function resolveMarkdownFile(
+function resolveMarkdownFileCore(
 	input: string,
 	projectRoot: string,
 ): ResolveResult {
-	// Trim whitespace/CR that may leak from Windows shell pipelines
-	input = input.trim();
 	const normalizedInput = normalizeMarkdownPathInput(input);
 	const searchInput = normalizeSeparators(normalizedInput);
 	const isBareFilename = !searchInput.includes("/");
@@ -219,6 +231,47 @@ export function resolveMarkdownFile(
 	return { kind: "not_found", input };
 }
 
+/**
+ * Resolve a markdown file path within a project root.
+ *
+ * @param input - User-provided path (absolute, relative, or bare filename)
+ * @param projectRoot - Project root directory to search within
+ */
+export function resolveMarkdownFile(
+	input: string,
+	projectRoot: string,
+): ResolveResult {
+	const originalInput = input.trim();
+	const unquotedInput = stripWrappingQuotes(originalInput);
+
+	const primary = resolveMarkdownFileCore(unquotedInput, projectRoot);
+	if (primary.kind === "found") {
+		return primary;
+	}
+	if (primary.kind === "ambiguous") {
+		return { ...primary, input: originalInput };
+	}
+
+	if (!unquotedInput.startsWith("@")) {
+		return { kind: "not_found", input: originalInput };
+	}
+
+	const normalizedInput = unquotedInput.replace(/^@+/, "");
+	if (!normalizedInput) {
+		return { kind: "not_found", input: originalInput };
+	}
+
+	const fallback = resolveMarkdownFileCore(normalizedInput, projectRoot);
+	if (fallback.kind === "found") {
+		return fallback;
+	}
+	if (fallback.kind === "ambiguous") {
+		return { ...fallback, input: originalInput };
+	}
+
+	return { kind: "not_found", input: originalInput };
+}
+
 /**
  * Check if a directory contains at least one markdown file.
  * Used to validate folder annotation targets.

package/generated/review-core.ts

@@ -14,6 +14,7 @@ export type DiffType =
   | "unstaged"
   | "last-commit"
   | "branch"
+  | "merge-base"
   | `worktree:${string}`
   | "p4-default"
   | `p4-changelist:${string}`;
@@ -151,6 +152,7 @@ export async function getGitContext(
 
   if (currentBranch !== defaultBranch) {
     diffOptions.push({ id: "branch", label: `vs ${defaultBranch}` });
+    diffOptions.push({ id: "merge-base", label: `Current PR Diff` });
   }
 
   const [worktrees, currentTreePathResult] = await Promise.all([
@@ -386,6 +388,28 @@ export async function runGitDiff(
         break;
       }
 
+      case "merge-base": {
+        const mergeBaseResult = assertGitSuccess(
+          await runtime.runGit(["merge-base", defaultBranch, "HEAD"], { cwd }),
+          ["merge-base", defaultBranch, "HEAD"],
+        );
+        const mergeBase = mergeBaseResult.stdout.trim();
+        const mergeBaseDiffArgs = [
+          "diff",
+          "--no-ext-diff",
+          `${mergeBase}..HEAD`,
+          "--src-prefix=a/",
+          "--dst-prefix=b/",
+        ];
+        const mergeBaseDiff = assertGitSuccess(
+          await runtime.runGit(mergeBaseDiffArgs, { cwd }),
+          mergeBaseDiffArgs,
+        );
+        patch = mergeBaseDiff.stdout;
+        label = `PR diff vs ${defaultBranch}`;
+        break;
+      }
+
       default:
         return { patch: "", label: "Unknown diff type" };
     }
@@ -475,6 +499,14 @@ export async function getFileContentsForDiff(
         oldContent: await gitShow(defaultBranch, oldFilePath),
         newContent: await gitShow("HEAD", filePath),
       };
+    case "merge-base": {
+      const mbResult = await runtime.runGit(["merge-base", defaultBranch, "HEAD"], { cwd });
+      const mb = mbResult.exitCode === 0 ? mbResult.stdout.trim() : defaultBranch;
+      return {
+        oldContent: await gitShow(mb, oldFilePath),
+        newContent: await gitShow("HEAD", filePath),
+      };
+    }
     default:
       return { oldContent: null, newContent: null };
   }

package/generated/worktree.ts

@@ -0,0 +1,120 @@
+// @generated — DO NOT EDIT. Source: packages/shared/worktree.ts
+/**
+ * Worktree — runtime-agnostic git worktree primitives.
+ *
+ * Uses ReviewGitRuntime so both Bun and Node runtimes can use the same logic.
+ * Lives in packages/shared/ and gets vendored to Pi via vendor.sh.
+ *
+ * Designed as composable primitives, not tied to any specific use case.
+ * PR local checkout, agent sandboxes, parallel sessions — all compose from these.
+ */
+
+import type { ReviewGitRuntime } from "./review-core";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface CreateWorktreeOptions {
+  /** Git ref to check out (branch name, SHA, FETCH_HEAD, etc.) */
+  ref: string;
+  /** Absolute path where the worktree will be created. */
+  path: string;
+  /** Create in detached HEAD mode (no branch). Default: false. */
+  detach?: boolean;
+  /** CWD of the source repository. Defaults to process.cwd(). */
+  cwd?: string;
+}
+
+export interface RemoveWorktreeOptions {
+  /** Force removal even if the worktree has modifications. Default: false. */
+  force?: boolean;
+  /** CWD of the source repository. Required if the worktree was created from a different cwd. */
+  cwd?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Primitives
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch a ref from origin.
+ * Runs: `git fetch origin <ref>`
+ * Throws on failure.
+ */
+export async function fetchRef(
+  runtime: ReviewGitRuntime,
+  ref: string,
+  options?: { cwd?: string },
+): Promise<void> {
+  const result = await runtime.runGit(["fetch", "origin", "--", ref], { cwd: options?.cwd });
+  if (result.exitCode !== 0) {
+    throw new Error(`git fetch origin ${ref} failed: ${result.stderr.trim() || `exit code ${result.exitCode}`}`);
+  }
+}
+
+/**
+ * Ensure a git object (commit SHA) is available locally.
+ * Checks with `git cat-file -t`, fetches from origin if missing.
+ * Returns true if the object is available after the attempt.
+ */
+export async function ensureObjectAvailable(
+  runtime: ReviewGitRuntime,
+  sha: string,
+  options?: { cwd?: string },
+): Promise<boolean> {
+  const check = await runtime.runGit(["cat-file", "-t", sha], { cwd: options?.cwd });
+  if (check.exitCode === 0) return true;
+
+  // Object missing locally — try fetching it
+  const fetch = await runtime.runGit(["fetch", "origin", "--", sha], { cwd: options?.cwd });
+  if (fetch.exitCode !== 0) return false;
+
+  // Verify it's now available
+  const recheck = await runtime.runGit(["cat-file", "-t", sha], { cwd: options?.cwd });
+  return recheck.exitCode === 0;
+}
+
+/**
+ * Create a git worktree.
+ * Runs: `git worktree add [--detach] <path> <ref>`
+ * Throws on failure with a descriptive error.
+ */
+export async function createWorktree(
+  runtime: ReviewGitRuntime,
+  options: CreateWorktreeOptions,
+): Promise<{ worktreePath: string }> {
+  const args = ["worktree", "add"];
+  if (options.detach) args.push("--detach");
+  args.push(options.path, options.ref);
+
+  const result = await runtime.runGit(args, { cwd: options.cwd });
+  if (result.exitCode !== 0) {
+    throw new Error(`git worktree add failed: ${result.stderr.trim() || `exit code ${result.exitCode}`}`);
+  }
+
+  return { worktreePath: options.path };
+}
+
+/**
+ * Remove a git worktree. Best-effort — logs errors but does not throw.
+ * Runs: `git worktree remove [--force] <path>`
+ */
+export async function removeWorktree(
+  runtime: ReviewGitRuntime,
+  worktreePath: string,
+  options?: RemoveWorktreeOptions,
+): Promise<void> {
+  const args = ["worktree", "remove"];
+  if (options?.force) args.push("--force");
+  args.push(worktreePath);
+
+  try {
+    const result = await runtime.runGit(args, { cwd: options?.cwd });
+    if (result.exitCode !== 0) {
+      console.error(`Warning: git worktree remove failed for ${worktreePath}: ${result.stderr.trim()}`);
+    }
+  } catch (err) {
+    console.error(`Warning: worktree cleanup error: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}

package/index.ts

@@ -333,8 +333,8 @@ export default function plannotator(pi: ExtensionAPI): void {
 	});
 
 	pi.registerCommand("plannotator-review", {
-		description: "Open interactive code review for current changes",
-		handler: async (_args, ctx) => {
+		description: "Open interactive code review for current changes or a PR URL",
+		handler: async (args, ctx) => {
 			if (!hasReviewBrowserHtml()) {
 				ctx.ui.notify(
 					"Code review UI not available. Run 'bun run build' in the pi-extension directory.",
@@ -344,12 +344,18 @@ export default function plannotator(pi: ExtensionAPI): void {
 			}
 
 			try {
-				const result = await openCodeReview(ctx);
+				const prUrl = args?.trim() || undefined;
+				const isPRReview = prUrl?.startsWith("http://") || prUrl?.startsWith("https://");
+				const result = await openCodeReview(ctx, { prUrl });
 				if (result.feedback) {
 					if (result.approved) {
 						pi.sendUserMessage(
 							`# Code Review\n\nCode review completed — no changes requested.`,
 						);
+					} else if (isPRReview) {
+						// Platform PR actions (approve/comment) return approved:false with a
+						// status message — don't tell the agent to "address" a platform action.
+						pi.sendUserMessage(result.feedback);
 					} else {
 						pi.sendUserMessage(
 							`${result.feedback}\n\nPlease address this feedback.`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/pi-extension",
-  "version": "0.16.7",
+  "version": "0.17.1",
   "type": "module",
   "description": "Plannotator extension for Pi coding agent - interactive plan review with visual annotation",
   "author": "backnotprop",

package/plannotator-browser.ts

@@ -1,9 +1,12 @@
-import { existsSync, readFileSync, statSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { existsSync, readFileSync, realpathSync, rmSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
 import {
 	getGitContext,
+	reviewRuntime,
 	runGitDiff,
 	startAnnotateServer,
 	startPlanReviewServer,
@@ -11,6 +14,16 @@ import {
 	type DiffType,
 } from "./server.js";
 import { openBrowser } from "./server/network.js";
+import { parsePRUrl, checkPRAuth, fetchPR } from "./server/pr.js";
+import {
+	getMRLabel,
+	getMRNumberLabel,
+	getDisplayRepo,
+	getCliName,
+	getCliInstallUrl,
+} from "./generated/pr-provider.js";
+import { parseRemoteUrl } from "./generated/repo.js";
+import { fetchRef, createWorktree, removeWorktree, ensureObjectAvailable } from "./generated/worktree.js";
 
 export type AnnotateMode = "annotate" | "annotate-folder" | "annotate-last";
 export interface PlanReviewDecision {
@@ -151,27 +164,198 @@ export async function openPlanReviewBrowser(
 
 export async function openCodeReview(
 	ctx: ExtensionContext,
-	options: { cwd?: string; defaultBranch?: string; diffType?: DiffType } = {},
+	options: { cwd?: string; defaultBranch?: string; diffType?: DiffType; prUrl?: string } = {},
 ): Promise<{ approved: boolean; feedback?: string; annotations?: unknown[]; agentSwitch?: string }> {
 	if (!ctx.hasUI || !reviewHtmlContent) {
 		throw new Error("Plannotator code review browser is unavailable in this session.");
 	}
 
-	const cwd = options.cwd ?? ctx.cwd;
-	const gitCtx = await getGitContext(cwd);
-	const defaultBranch = options.defaultBranch ?? gitCtx.defaultBranch;
-	const diffType: DiffType = options.diffType ?? "uncommitted";
-	const { patch: rawPatch, label: gitRef, error } = await runGitDiff(diffType, defaultBranch, cwd);
+	const urlArg = options.prUrl;
+	const isPRMode = urlArg?.startsWith("http://") || urlArg?.startsWith("https://");
+
+	let rawPatch: string;
+	let gitRef: string;
+	let diffError: string | undefined;
+	let gitCtx: Awaited<ReturnType<typeof getGitContext>> | undefined;
+	let prMetadata: Awaited<ReturnType<typeof fetchPR>>["metadata"] | undefined;
+	let diffType: DiffType | undefined;
+	let agentCwd: string | undefined;
+	let worktreeCleanup: (() => void | Promise<void>) | undefined;
+	let exitHandler: (() => void) | undefined;
+
+	if (isPRMode && urlArg) {
+		// --- PR Review Mode ---
+		const prRef = parsePRUrl(urlArg);
+		if (!prRef) {
+			throw new Error(
+				`Invalid PR/MR URL: ${urlArg}\n` +
+				"Supported formats:\n" +
+				"  GitHub: https://github.com/owner/repo/pull/123\n" +
+				"  GitLab: https://gitlab.com/group/project/-/merge_requests/42",
+			);
+		}
+
+		const cliName = getCliName(prRef);
+		const cliUrl = getCliInstallUrl(prRef);
+
+		try {
+			await checkPRAuth(prRef);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			if (msg.includes("not found") || msg.includes("ENOENT")) {
+				throw new Error(`${cliName === "gh" ? "GitHub" : "GitLab"} CLI (${cliName}) is not installed. Install it from ${cliUrl}`);
+			}
+			throw err;
+		}
+
+		console.error(`Fetching ${getMRLabel(prRef)} ${getMRNumberLabel(prRef)} from ${getDisplayRepo(prRef)}...`);
+		const pr = await fetchPR(prRef);
+		rawPatch = pr.rawPatch;
+		gitRef = `${getMRLabel(prRef)} ${getMRNumberLabel(prRef)}`;
+		prMetadata = pr.metadata;
+
+		// Create local worktree for agent file access (--local is the default for PR reviews)
+		let localPath: string | undefined;
+		try {
+			const repoDir = options.cwd ?? ctx.cwd;
+			const identifier = prMetadata.platform === "github"
+				? `${prMetadata.owner}-${prMetadata.repo}-${prMetadata.number}`
+				: `${prMetadata.projectPath.replace(/\//g, "-")}-${prMetadata.iid}`;
+			const suffix = Math.random().toString(36).slice(2, 8);
+			localPath = join(realpathSync(tmpdir()), `plannotator-pr-${identifier}-${suffix}`);
+			const fetchRefStr = prMetadata.platform === "github"
+				? `refs/pull/${prMetadata.number}/head`
+				: `refs/merge-requests/${prMetadata.iid}/head`;
+
+			// Validate inputs from platform API to prevent git flag/path injection
+			if (prMetadata.baseBranch.includes('..') || prMetadata.baseBranch.startsWith('-')) throw new Error(`Invalid base branch: ${prMetadata.baseBranch}`);
+			if (!/^[0-9a-f]{40,64}$/i.test(prMetadata.baseSha)) throw new Error(`Invalid base SHA: ${prMetadata.baseSha}`);
+
+			// Detect same-repo vs cross-repo (must match both owner/repo AND host)
+			let isSameRepo = false;
+			try {
+				const remoteResult = await reviewRuntime.runGit(["remote", "get-url", "origin"], { cwd: repoDir });
+				if (remoteResult.exitCode === 0) {
+					const remoteUrl = remoteResult.stdout.trim();
+					const currentRepo = parseRemoteUrl(remoteUrl);
+					const prRepo = prMetadata.platform === "github"
+						? `${prMetadata.owner}/${prMetadata.repo}`
+						: prMetadata.projectPath;
+					const repoMatches = !!currentRepo && currentRepo.toLowerCase() === prRepo.toLowerCase();
+					const sshHost = remoteUrl.match(/^[^@]+@([^:]+):/)?.[1];
+					const httpsHost = (() => { try { return new URL(remoteUrl).hostname; } catch { return null; } })();
+					const remoteHost = (sshHost || httpsHost || "").toLowerCase();
+					const prHost = prMetadata.host.toLowerCase();
+					isSameRepo = repoMatches && remoteHost === prHost;
+				}
+			} catch { /* not in a git repo — cross-repo path */ }
+
+			if (isSameRepo) {
+				// ── Same-repo: fast worktree path ──
+				console.error("Fetching PR branch and creating local worktree...");
+				await fetchRef(reviewRuntime, prMetadata.baseBranch, { cwd: repoDir });
+				await ensureObjectAvailable(reviewRuntime, prMetadata.baseSha, { cwd: repoDir });
+				await fetchRef(reviewRuntime, fetchRefStr, { cwd: repoDir });
+
+				await createWorktree(reviewRuntime, {
+					ref: "FETCH_HEAD",
+					path: localPath,
+					detach: true,
+					cwd: repoDir,
+				});
+
+				const worktreePath = localPath;
+				const wtRepoDir = repoDir;
+				exitHandler = () => {
+					try { spawnSync("git", ["worktree", "remove", "--force", worktreePath], { cwd: wtRepoDir }); } catch {}
+				};
+				worktreeCleanup = () => {
+					if (exitHandler) { process.removeListener("exit", exitHandler); exitHandler = undefined; }
+					return removeWorktree(reviewRuntime, worktreePath, { force: true, cwd: wtRepoDir });
+				};
+				process.once("exit", exitHandler);
+			} else {
+				// ── Cross-repo: shallow clone + fetch PR head ──
+				const prRepo = prMetadata.platform === "github"
+					? `${prMetadata.owner}/${prMetadata.repo}`
+					: prMetadata.projectPath;
+				if (/^-/.test(prRepo)) throw new Error(`Invalid repository identifier: ${prRepo}`);
+				const cli = prMetadata.platform === "github" ? "gh" : "glab";
+				const host = prMetadata.host;
+				// gh/glab repo clone doesn't accept --hostname; set GH_HOST/GITLAB_HOST env instead
+				const isDefaultHost = host === "github.com" || host === "gitlab.com";
+				const cloneEnv = isDefaultHost ? undefined : {
+					...process.env,
+					...(prMetadata.platform === "github" ? { GH_HOST: host } : { GITLAB_HOST: host }),
+				};
+
+				console.error(`Cloning ${prRepo} (shallow)...`);
+				const cloneResult = spawnSync(cli, ["repo", "clone", prRepo, localPath, "--", "--depth=1", "--no-checkout"], { encoding: "utf-8", env: cloneEnv });
+				if ((cloneResult.status ?? 1) !== 0) {
+					throw new Error(`${cli} repo clone failed: ${(cloneResult.stderr ?? "").trim()}`);
+				}
+
+				console.error("Fetching PR branch...");
+				const fetchResult = await reviewRuntime.runGit(["fetch", "--depth=200", "origin", fetchRefStr], { cwd: localPath });
+				if (fetchResult.exitCode !== 0) throw new Error(`Failed to fetch PR head ref: ${fetchResult.stderr.trim()}`);
+
+				const checkoutResult = await reviewRuntime.runGit(["checkout", "FETCH_HEAD"], { cwd: localPath });
+				if (checkoutResult.exitCode !== 0) {
+					throw new Error(`git checkout FETCH_HEAD failed: ${checkoutResult.stderr.trim()}`);
+				}
+
+				// Best-effort: create base refs so agent diffs work
+				const baseFetch = await reviewRuntime.runGit(["fetch", "--depth=200", "origin", prMetadata.baseSha], { cwd: localPath });
+				if (baseFetch.exitCode !== 0) console.error("Warning: failed to fetch baseSha, agent diffs may be inaccurate");
+				await reviewRuntime.runGit(["branch", "--", prMetadata.baseBranch, prMetadata.baseSha], { cwd: localPath });
+				await reviewRuntime.runGit(["update-ref", `refs/remotes/origin/${prMetadata.baseBranch}`, prMetadata.baseSha], { cwd: localPath });
+
+				const clonePath = localPath;
+				exitHandler = () => {
+					try { rmSync(clonePath, { recursive: true, force: true }); } catch {}
+				};
+				worktreeCleanup = () => {
+					if (exitHandler) { process.removeListener("exit", exitHandler); exitHandler = undefined; }
+					try { rmSync(clonePath, { recursive: true, force: true }); } catch {}
+				};
+				process.once("exit", exitHandler);
+			}
+
+			agentCwd = localPath;
+			console.error(`Local checkout ready at ${localPath}`);
+		} catch (err) {
+			console.error("Warning: local worktree creation failed, falling back to remote diff");
+			console.error(err instanceof Error ? err.message : String(err));
+			if (exitHandler) { process.removeListener("exit", exitHandler); exitHandler = undefined; }
+			if (localPath) try { rmSync(localPath, { recursive: true, force: true }); } catch {}
+			agentCwd = undefined;
+			worktreeCleanup = undefined;
+		}
+	} else {
+		// --- Local Review Mode ---
+		const cwd = options.cwd ?? ctx.cwd;
+		gitCtx = await getGitContext(cwd);
+		const defaultBranch = options.defaultBranch ?? gitCtx.defaultBranch;
+		diffType = options.diffType ?? "uncommitted";
+		const result = await runGitDiff(diffType, defaultBranch, cwd);
+		rawPatch = result.patch;
+		gitRef = result.label;
+		diffError = result.error;
+	}
+
 	const server = await startReviewServer({
 		rawPatch,
 		gitRef,
-		error,
+		error: diffError,
 		origin: "pi",
 		diffType,
 		gitContext: gitCtx,
+		prMetadata,
+		agentCwd,
 		htmlContent: reviewHtmlContent,
 		sharingEnabled: process.env.PLANNOTATOR_SHARE !== "disabled",
 		shareBaseUrl: process.env.PLANNOTATOR_SHARE_URL || undefined,
+		onCleanup: worktreeCleanup,
 	});
 
 	return openBrowserAndWait(server, ctx, server.waitForDecision);

package/plannotator-events.ts

@@ -85,6 +85,7 @@ export interface PlannotatorCodeReviewPayload {
 	diffType?: DiffType;
 	defaultBranch?: string;
 	cwd?: string;
+	prUrl?: string;
 }
 
 export interface PlannotatorCodeReviewResult {
@@ -254,6 +255,7 @@ export function registerPlannotatorEventListeners(pi: ExtensionAPI): void {
 						cwd: request.payload?.cwd,
 						defaultBranch: request.payload?.defaultBranch,
 						diffType: request.payload?.diffType,
+						prUrl: request.payload?.prUrl,
 					});
 					request.respond({ status: "handled", result });
 					return;