gsd-pi 2.38.0-dev.add4f78 → 2.38.0-dev.d533afb

package/packages/pi-coding-agent/src/core/extensions/loader.ts

@@ -23,6 +23,12 @@ import * as _bundledYaml from "yaml";
 import * as _bundledMcpClient from "@modelcontextprotocol/sdk/client";
 import * as _bundledMcpStdio from "@modelcontextprotocol/sdk/client/stdio.js";
 import * as _bundledMcpStreamableHttp from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import * as _bundledMcpSse from "@modelcontextprotocol/sdk/client/sse.js";
+import * as _bundledMcpServer from "@modelcontextprotocol/sdk/server";
+import * as _bundledMcpServerStdio from "@modelcontextprotocol/sdk/server/stdio.js";
+import * as _bundledMcpServerSse from "@modelcontextprotocol/sdk/server/sse.js";
+import * as _bundledMcpServerStreamableHttp from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import * as _bundledMcpTypes from "@modelcontextprotocol/sdk/types.js";
 import { getAgentDir, isBunBinary } from "../../config.js";
 // NOTE: This import works because loader.ts exports are NOT re-exported from index.ts,
 // avoiding a circular dependency. Extensions can import from @gsd/pi-coding-agent.
@@ -44,8 +50,11 @@ import type {
 	ToolDefinition,
 } from "./types.js";
 
-/** Modules available to extensions via virtualModules (for compiled Bun binary) */
-const VIRTUAL_MODULES: Record<string, unknown> = {
+/**
+ * Statically imported modules for Bun binary virtualModules.
+ * Maps specifier -> module object for subpaths that must be available in compiled binaries.
+ */
+const STATIC_BUNDLED_MODULES: Record<string, unknown> = {
 	"@sinclair/typebox": _bundledTypebox,
 	"@gsd/pi-agent-core": _bundledPiAgentCore,
 	"@gsd/pi-tui": _bundledPiTui,
@@ -58,6 +67,17 @@ const VIRTUAL_MODULES: Record<string, unknown> = {
 	"@modelcontextprotocol/sdk/client/stdio.js": _bundledMcpStdio,
 	"@modelcontextprotocol/sdk/client/streamableHttp": _bundledMcpStreamableHttp,
 	"@modelcontextprotocol/sdk/client/streamableHttp.js": _bundledMcpStreamableHttp,
+	"@modelcontextprotocol/sdk/client/sse": _bundledMcpSse,
+	"@modelcontextprotocol/sdk/client/sse.js": _bundledMcpSse,
+	"@modelcontextprotocol/sdk/server": _bundledMcpServer,
+	"@modelcontextprotocol/sdk/server/stdio": _bundledMcpServerStdio,
+	"@modelcontextprotocol/sdk/server/stdio.js": _bundledMcpServerStdio,
+	"@modelcontextprotocol/sdk/server/sse": _bundledMcpServerSse,
+	"@modelcontextprotocol/sdk/server/sse.js": _bundledMcpServerSse,
+	"@modelcontextprotocol/sdk/server/streamableHttp": _bundledMcpServerStreamableHttp,
+	"@modelcontextprotocol/sdk/server/streamableHttp.js": _bundledMcpServerStreamableHttp,
+	"@modelcontextprotocol/sdk/types": _bundledMcpTypes,
+	"@modelcontextprotocol/sdk/types.js": _bundledMcpTypes,
 	// Aliases for external PI ecosystem packages that import from the original scope
 	"@mariozechner/pi-agent-core": _bundledPiAgentCore,
 	"@mariozechner/pi-tui": _bundledPiTui,
@@ -66,9 +86,198 @@ const VIRTUAL_MODULES: Record<string, unknown> = {
 	"@mariozechner/pi-coding-agent": _bundledPiCodingAgent,
 };
 
+/** Modules available to extensions via virtualModules (for compiled Bun binary) */
+const VIRTUAL_MODULES: Record<string, unknown> = { ...STATIC_BUNDLED_MODULES };
+
 const require = createRequire(import.meta.url);
 const EXTENSION_TIMING_ENABLED = process.env.GSD_STARTUP_TIMING === "1" || process.env.PI_TIMING === "1";
 
+/**
+ * Bundled npm packages whose subpath exports should be auto-resolved for extensions.
+ * Each package listed here will have its `exports` field read from package.json,
+ * and all subpath exports will be registered as jiti aliases (Node.js mode) so that
+ * extensions can import any standard subpath without hitting jiti's CJS double-resolve bug.
+ */
+const BUNDLED_PACKAGES_WITH_EXPORTS = [
+	"@modelcontextprotocol/sdk",
+	"yaml",
+];
+
+/**
+ * Read a package's `exports` field and return alias entries mapping
+ * specifiers (e.g. `@modelcontextprotocol/sdk/server`) to resolved file paths.
+ *
+ * Handles:
+ * - Explicit subpath exports: `./client` -> `@pkg/client`
+ * - Wildcard exports (`./*`): scans the package's dist directory for actual files
+ * - Both `.js`-suffixed and bare specifiers for each subpath
+ */
+function resolveSubpathExports(packageName: string): Record<string, string> {
+	const aliases: Record<string, string> = {};
+
+	let packageJsonPath: string;
+	try {
+		// Resolve the package's root directory via its package.json
+		packageJsonPath = require.resolve(`${packageName}/package.json`);
+	} catch {
+		// Package doesn't allow importing package.json via exports — find it manually
+		try {
+			const anyEntry = require.resolve(packageName);
+			// Walk up from the resolved entry to find package.json
+			let dir = path.dirname(anyEntry);
+			while (dir !== path.dirname(dir)) {
+				const candidate = path.join(dir, "package.json");
+				if (fs.existsSync(candidate)) {
+					try {
+						const pkg = JSON.parse(fs.readFileSync(candidate, "utf-8"));
+						if (pkg.name === packageName) {
+							packageJsonPath = candidate;
+							break;
+						}
+					} catch {
+						// not valid JSON, keep walking
+					}
+				}
+				dir = path.dirname(dir);
+			}
+		} catch {
+			return aliases;
+		}
+		if (!packageJsonPath!) return aliases;
+	}
+
+	let pkg: { exports?: Record<string, unknown> };
+	try {
+		pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+	} catch {
+		return aliases;
+	}
+
+	const exports = pkg.exports;
+	if (!exports || typeof exports !== "object") return aliases;
+
+	const packageDir = path.dirname(packageJsonPath);
+
+	for (const [subpath, target] of Object.entries(exports)) {
+		if (subpath === ".") continue; // Root export handled by static imports
+
+		// Handle wildcard exports like "./*"
+		if (subpath.includes("*")) {
+			resolveWildcardExports(packageName, packageDir, subpath, target, aliases);
+			continue;
+		}
+
+		// Explicit subpath: "./client" -> "@pkg/client"
+		const specifier = `${packageName}/${subpath.replace(/^\.\//, "")}`;
+
+		try {
+			const resolved = require.resolve(specifier);
+			aliases[specifier] = resolved;
+
+			// Add .js-suffixed variant if the specifier doesn't already end in .js
+			if (!specifier.endsWith(".js")) {
+				const jsSpecifier = `${specifier}.js`;
+				try {
+					const jsResolved = require.resolve(jsSpecifier);
+					aliases[jsSpecifier] = jsResolved;
+				} catch {
+					// .js variant doesn't resolve — that's fine
+				}
+			}
+
+			// Add bare variant (without .js) if it ends in .js
+			if (specifier.endsWith(".js")) {
+				const bareSpecifier = specifier.slice(0, -3);
+				try {
+					const bareResolved = require.resolve(bareSpecifier);
+					aliases[bareSpecifier] = bareResolved;
+				} catch {
+					// bare variant doesn't resolve — that's fine
+				}
+			}
+		} catch {
+			// Subpath doesn't resolve — skip it
+		}
+	}
+
+	return aliases;
+}
+
+/**
+ * Resolve wildcard export patterns (e.g. `./*`) by scanning the package's
+ * file structure to find all matching files and generate alias entries.
+ */
+function resolveWildcardExports(
+	packageName: string,
+	packageDir: string,
+	subpathPattern: string,
+	target: unknown,
+	aliases: Record<string, string>,
+): void {
+	// Extract the target directory pattern from the export target
+	// e.g. { "require": "./dist/cjs/*" } -> "dist/cjs"
+	let targetDir: string | null = null;
+
+	if (typeof target === "string") {
+		targetDir = target.replace(/\/\*$/, "").replace(/^\.\//, "");
+	} else if (target && typeof target === "object") {
+		const targetObj = target as Record<string, unknown>;
+		// Prefer "require" for CJS compatibility with jiti, fall back to "import"
+		const resolved = targetObj.require ?? targetObj.import ?? targetObj.default;
+		if (typeof resolved === "string") {
+			targetDir = resolved.replace(/\/\*$/, "").replace(/^\.\//, "");
+		}
+	}
+
+	if (!targetDir) return;
+
+	const fullTargetDir = path.join(packageDir, targetDir);
+	if (!fs.existsSync(fullTargetDir)) return;
+
+	// Scan for .js files and generate specifiers
+	const subpathPrefix = subpathPattern.replace(/\/?\*$/, "").replace(/^\.\//, "");
+	scanDirForExports(packageName, fullTargetDir, subpathPrefix, aliases);
+}
+
+/**
+ * Recursively scan a directory for .js files and register them as aliases.
+ */
+function scanDirForExports(
+	packageName: string,
+	dir: string,
+	relativePath: string,
+	aliases: Record<string, string>,
+): void {
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return;
+	}
+
+	for (const entry of entries) {
+		const entryRelative = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+
+		if (entry.isDirectory()) {
+			// Skip examples/test directories — extensions don't need them
+			if (entry.name === "examples" || entry.name === "__tests__" || entry.name === "test") continue;
+			scanDirForExports(packageName, path.join(dir, entry.name), entryRelative, aliases);
+		} else if (entry.name.endsWith(".js") && !entry.name.endsWith(".d.js")) {
+			const filePath = path.join(dir, entry.name);
+			const specifier = `${packageName}/${entryRelative}`;
+			// Only add if not already covered by an explicit export
+			if (!(specifier in aliases)) {
+				aliases[specifier] = filePath;
+			}
+			// Also add bare (no .js) variant
+			const bareSpecifier = specifier.replace(/\.js$/, "");
+			if (!(bareSpecifier in aliases)) {
+				aliases[bareSpecifier] = filePath;
+			}
+		}
+	}
+}
+
 function logExtensionTiming(extensionPath: string, ms: number, outcome: "loaded" | "failed"): void {
 	if (!EXTENSION_TIMING_ENABLED) return;
 	console.error(`[startup] extension ${outcome}: ${extensionPath} (${ms}ms)`);
@@ -100,7 +309,19 @@ function getAliases(): Record<string, string> {
 		return fileURLToPath(import.meta.resolve(specifier));
 	};
 
+	// Auto-discover subpath exports from bundled npm packages.
+	// This ensures extensions can import any standard subpath (e.g. @modelcontextprotocol/sdk/server)
+	// without hitting jiti's CJS double-resolve bug.
+	const autoDiscovered: Record<string, string> = {};
+	for (const packageName of BUNDLED_PACKAGES_WITH_EXPORTS) {
+		const subpathAliases = resolveSubpathExports(packageName);
+		Object.assign(autoDiscovered, subpathAliases);
+	}
+
 	_aliases = {
+		// Auto-discovered subpath exports (lowest priority — overridden by manual entries below)
+		...autoDiscovered,
+		// Manual entries for workspace packages and packages needing special resolution
 		"@gsd/pi-coding-agent": packageIndex,
 		"@gsd/pi-agent-core": resolveWorkspaceOrImport("agent/dist/index.js", "@gsd/pi-agent-core"),
 		"@gsd/pi-tui": resolveWorkspaceOrImport("tui/dist/index.js", "@gsd/pi-tui"),
@@ -108,11 +329,6 @@ function getAliases(): Record<string, string> {
 		"@gsd/pi-ai/oauth": resolveWorkspaceOrImport("ai/dist/oauth.js", "@gsd/pi-ai/oauth"),
 		"@sinclair/typebox": typeboxRoot,
 		"yaml": yamlRoot,
-		"@modelcontextprotocol/sdk/client": require.resolve("@modelcontextprotocol/sdk/client"),
-		"@modelcontextprotocol/sdk/client/stdio": require.resolve("@modelcontextprotocol/sdk/client/stdio.js"),
-		"@modelcontextprotocol/sdk/client/stdio.js": require.resolve("@modelcontextprotocol/sdk/client/stdio.js"),
-		"@modelcontextprotocol/sdk/client/streamableHttp": require.resolve("@modelcontextprotocol/sdk/client/streamableHttp.js"),
-		"@modelcontextprotocol/sdk/client/streamableHttp.js": require.resolve("@modelcontextprotocol/sdk/client/streamableHttp.js"),
 		// Aliases for external PI ecosystem packages that import from the original scope
 		"@mariozechner/pi-coding-agent": packageIndex,
 		"@mariozechner/pi-agent-core": resolveWorkspaceOrImport("agent/dist/index.js", "@gsd/pi-agent-core"),

package/src/resources/extensions/github-sync/cli.ts

@@ -0,0 +1,364 @@
+/**
+ * Thin wrapper around the `gh` CLI.
+ *
+ * Every public function returns `GhResult<T>` — never throws.
+ * Uses `execFileSync` (not `execSync`) for safety.
+ */
+
+import { execFileSync } from "node:child_process";
+
+// ─── Result Type ────────────────────────────────────────────────────────────
+
+export interface GhResult<T> {
+  ok: boolean;
+  data?: T;
+  error?: string;
+}
+
+function ok<T>(data: T): GhResult<T> {
+  return { ok: true, data };
+}
+
+function fail<T>(error: string): GhResult<T> {
+  return { ok: false, error };
+}
+
+// ─── gh Availability ────────────────────────────────────────────────────────
+
+let _ghAvailable: boolean | null = null;
+
+export function ghIsAvailable(): boolean {
+  if (_ghAvailable !== null) return _ghAvailable;
+  try {
+    execFileSync("gh", ["--version"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5_000,
+    });
+    _ghAvailable = true;
+  } catch {
+    _ghAvailable = false;
+  }
+  return _ghAvailable;
+}
+
+/** Reset cached availability (for testing). */
+export function _resetGhCache(): void {
+  _ghAvailable = null;
+}
+
+// ─── Rate Limit Check ───────────────────────────────────────────────────────
+
+let _rateLimitCheckedAt = 0;
+let _rateLimitOk = true;
+const RATE_LIMIT_CHECK_INTERVAL_MS = 300_000; // 5 minutes
+
+export function ghHasRateLimit(cwd: string): boolean {
+  const now = Date.now();
+  if (now - _rateLimitCheckedAt < RATE_LIMIT_CHECK_INTERVAL_MS) return _rateLimitOk;
+  _rateLimitCheckedAt = now;
+  try {
+    const raw = execFileSync("gh", ["api", "rate_limit", "--jq", ".rate.remaining"], {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 10_000,
+    }).trim();
+    const remaining = parseInt(raw, 10);
+    _rateLimitOk = Number.isFinite(remaining) && remaining >= 100;
+  } catch {
+    // Can't check — assume OK so we don't silently disable sync
+    _rateLimitOk = true;
+  }
+  return _rateLimitOk;
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+const GH_TIMEOUT = 15_000;
+const MAX_BODY_LENGTH = 65_000;
+
+function truncateBody(body: string): string {
+  if (body.length <= MAX_BODY_LENGTH) return body;
+  return body.slice(0, MAX_BODY_LENGTH) + "\n\n---\n*Body truncated (exceeded 65K characters)*";
+}
+
+function runGh(args: string[], cwd: string): GhResult<string> {
+  try {
+    const stdout = execFileSync("gh", args, {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: GH_TIMEOUT,
+    }).trim();
+    return ok(stdout);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return fail(msg);
+  }
+}
+
+function runGhJson<T>(args: string[], cwd: string): GhResult<T> {
+  const result = runGh(args, cwd);
+  if (!result.ok) return fail(result.error!);
+  try {
+    return ok(JSON.parse(result.data!) as T);
+  } catch {
+    return fail(`Failed to parse JSON: ${result.data}`);
+  }
+}
+
+// ─── Repo Detection ─────────────────────────────────────────────────────────
+
+export function ghDetectRepo(cwd: string): GhResult<string> {
+  const result = runGh(
+    ["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"],
+    cwd,
+  );
+  if (!result.ok) return fail(result.error!);
+  const repo = result.data!.trim();
+  if (!repo || !repo.includes("/")) return fail("Could not detect repo");
+  return ok(repo);
+}
+
+// ─── Issues ─────────────────────────────────────────────────────────────────
+
+export interface CreateIssueOpts {
+  repo: string;
+  title: string;
+  body: string;
+  labels?: string[];
+  milestone?: number;
+  parentIssue?: number;
+}
+
+export function ghCreateIssue(cwd: string, opts: CreateIssueOpts): GhResult<number> {
+  const args = [
+    "issue", "create",
+    "--repo", opts.repo,
+    "--title", opts.title,
+    "--body", truncateBody(opts.body),
+  ];
+  if (opts.labels?.length) {
+    args.push("--label", opts.labels.join(","));
+  }
+  if (opts.milestone) {
+    args.push("--milestone", String(opts.milestone));
+  }
+
+  const result = runGh(args, cwd);
+  if (!result.ok) return fail(result.error!);
+
+  // gh issue create returns the URL; extract issue number
+  const match = result.data!.match(/\/issues\/(\d+)/);
+  if (!match) return fail(`Could not parse issue number from: ${result.data}`);
+  const issueNumber = parseInt(match[1], 10);
+
+  // If parent specified, add as sub-issue via GraphQL
+  if (opts.parentIssue) {
+    ghAddSubIssue(cwd, opts.repo, opts.parentIssue, issueNumber);
+  }
+
+  return ok(issueNumber);
+}
+
+export function ghCloseIssue(cwd: string, repo: string, issueNumber: number, comment?: string): GhResult<void> {
+  if (comment) {
+    ghAddComment(cwd, repo, issueNumber, comment);
+  }
+  const result = runGh(
+    ["issue", "close", String(issueNumber), "--repo", repo],
+    cwd,
+  );
+  if (!result.ok) return fail(result.error!);
+  return ok(undefined);
+}
+
+export function ghAddComment(cwd: string, repo: string, issueNumber: number, body: string): GhResult<void> {
+  const result = runGh(
+    ["issue", "comment", String(issueNumber), "--repo", repo, "--body", truncateBody(body)],
+    cwd,
+  );
+  if (!result.ok) return fail(result.error!);
+  return ok(undefined);
+}
+
+// ─── Sub-Issues (GraphQL) ───────────────────────────────────────────────────
+
+function ghAddSubIssue(cwd: string, repo: string, parentNumber: number, childNumber: number): GhResult<void> {
+  // Get node IDs for both issues
+  const parentResult = runGhJson<{ id: string }>(
+    ["api", `repos/${repo}/issues/${parentNumber}`, "--jq", "{id: .node_id}"],
+    cwd,
+  );
+  const childResult = runGhJson<{ id: string }>(
+    ["api", `repos/${repo}/issues/${childNumber}`, "--jq", "{id: .node_id}"],
+    cwd,
+  );
+
+  if (!parentResult.ok || !childResult.ok) {
+    return fail("Could not resolve issue node IDs for sub-issue linking");
+  }
+
+  const mutation = `mutation { addSubIssue(input: { issueId: "${parentResult.data!.id}", subIssueId: "${childResult.data!.id}" }) { issue { id } } }`;
+  return runGh(["api", "graphql", "-f", `query=${mutation}`], cwd) as GhResult<void>;
+}
+
+// ─── Milestones ─────────────────────────────────────────────────────────────
+
+export function ghCreateMilestone(cwd: string, repo: string, title: string, description: string): GhResult<number> {
+  const result = runGhJson<{ number: number }>(
+    [
+      "api", `repos/${repo}/milestones`,
+      "-X", "POST",
+      "-f", `title=${title}`,
+      "-f", `description=${truncateBody(description)}`,
+      "-f", "state=open",
+      "--jq", "{number: .number}",
+    ],
+    cwd,
+  );
+  if (!result.ok) return fail(result.error!);
+  return ok(result.data!.number);
+}
+
+export function ghCloseMilestone(cwd: string, repo: string, milestoneNumber: number): GhResult<void> {
+  const result = runGh(
+    [
+      "api", `repos/${repo}/milestones/${milestoneNumber}`,
+      "-X", "PATCH",
+      "-f", "state=closed",
+    ],
+    cwd,
+  );
+  if (!result.ok) return fail(result.error!);
+  return ok(undefined);
+}
+
+// ─── Pull Requests ──────────────────────────────────────────────────────────
+
+export interface CreatePROpts {
+  repo: string;
+  base: string;
+  head: string;
+  title: string;
+  body: string;
+  draft?: boolean;
+}
+
+export function ghCreatePR(cwd: string, opts: CreatePROpts): GhResult<number> {
+  const args = [
+    "pr", "create",
+    "--repo", opts.repo,
+    "--base", opts.base,
+    "--head", opts.head,
+    "--title", opts.title,
+    "--body", truncateBody(opts.body),
+  ];
+  if (opts.draft) args.push("--draft");
+
+  const result = runGh(args, cwd);
+  if (!result.ok) return fail(result.error!);
+
+  const match = result.data!.match(/\/pull\/(\d+)/);
+  if (!match) return fail(`Could not parse PR number from: ${result.data}`);
+  return ok(parseInt(match[1], 10));
+}
+
+export function ghMarkPRReady(cwd: string, repo: string, prNumber: number): GhResult<void> {
+  const result = runGh(
+    ["pr", "ready", String(prNumber), "--repo", repo],
+    cwd,
+  );
+  if (!result.ok) return fail(result.error!);
+  return ok(undefined);
+}
+
+export function ghMergePR(cwd: string, repo: string, prNumber: number, strategy: "squash" | "merge" = "squash"): GhResult<void> {
+  const args = [
+    "pr", "merge", String(prNumber),
+    "--repo", repo,
+    strategy === "squash" ? "--squash" : "--merge",
+    "--delete-branch",
+  ];
+  const result = runGh(args, cwd);
+  if (!result.ok) return fail(result.error!);
+  return ok(undefined);
+}
+
+// ─── Projects v2 ────────────────────────────────────────────────────────────
+
+export function ghAddToProject(cwd: string, repo: string, projectNumber: number, issueNumber: number): GhResult<void> {
+  // Get the issue's node ID first
+  const issueResult = runGhJson<{ id: string }>(
+    ["api", `repos/${repo}/issues/${issueNumber}`, "--jq", "{id: .node_id}"],
+    cwd,
+  );
+  if (!issueResult.ok) return fail(issueResult.error!);
+
+  // Get the project's node ID
+  const [owner] = repo.split("/");
+  const projectResult = runGhJson<{ id: string }>(
+    [
+      "api", "graphql",
+      "-f", `query=query { user(login: "${owner}") { projectV2(number: ${projectNumber}) { id } } }`,
+      "--jq", ".data.user.projectV2.id",
+    ],
+    cwd,
+  );
+
+  // Try org if user fails
+  let projectId: string | undefined;
+  if (projectResult.ok && projectResult.data?.id) {
+    projectId = projectResult.data.id;
+  } else {
+    const orgResult = runGhJson<{ id: string }>(
+      [
+        "api", "graphql",
+        "-f", `query=query { organization(login: "${owner}") { projectV2(number: ${projectNumber}) { id } } }`,
+        "--jq", ".data.organization.projectV2.id",
+      ],
+      cwd,
+    );
+    if (orgResult.ok) projectId = orgResult.data?.id;
+  }
+
+  if (!projectId) return fail("Could not find project");
+
+  const mutation = `mutation { addProjectV2ItemById(input: { projectId: "${projectId}", contentId: "${issueResult.data!.id}" }) { item { id } } }`;
+  return runGh(["api", "graphql", "-f", `query=${mutation}`], cwd) as GhResult<void>;
+}
+
+// ─── Branch Operations ──────────────────────────────────────────────────────
+
+export function ghPushBranch(cwd: string, branch: string, setUpstream = true): GhResult<void> {
+  const args = ["git", "push"];
+  if (setUpstream) args.push("-u", "origin", branch);
+  else args.push("origin", branch);
+
+  try {
+    execFileSync(args[0], args.slice(1), {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 30_000,
+    });
+    return ok(undefined);
+  } catch (err) {
+    return fail(err instanceof Error ? err.message : String(err));
+  }
+}
+
+export function ghCreateBranch(cwd: string, branch: string, from: string): GhResult<void> {
+  try {
+    execFileSync("git", ["branch", branch, from], {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 10_000,
+    });
+    return ok(undefined);
+  } catch (err) {
+    return fail(err instanceof Error ? err.message : String(err));
+  }
+}