gsd-pi 2.38.0-dev.eeb3520 → 2.39.0-dev.64cd3ed

package/src/resources/extensions/browser-tools/index.ts

@@ -33,6 +33,7 @@ async function registerBrowserTools(pi: ExtensionAPI): Promise<void> {
         codegen,
         actionCache,
         injectionDetection,
+        verify,
       ] = await Promise.all([
         importExtensionModule<typeof import("./lifecycle.js")>(import.meta.url, "./lifecycle.js"),
         importExtensionModule<typeof import("./capture.js")>(import.meta.url, "./capture.js"),
@@ -60,6 +61,7 @@ async function registerBrowserTools(pi: ExtensionAPI): Promise<void> {
         importExtensionModule<typeof import("./tools/codegen.js")>(import.meta.url, "./tools/codegen.js"),
         importExtensionModule<typeof import("./tools/action-cache.js")>(import.meta.url, "./tools/action-cache.js"),
         importExtensionModule<typeof import("./tools/injection-detect.js")>(import.meta.url, "./tools/injection-detect.js"),
+        importExtensionModule<typeof import("./tools/verify.js")>(import.meta.url, "./tools/verify.js"),
       ]);
 
       const deps = {
@@ -132,6 +134,7 @@ async function registerBrowserTools(pi: ExtensionAPI): Promise<void> {
       codegen.registerCodegenTools(pi, deps);
       actionCache.registerActionCacheTools(pi, deps);
       injectionDetection.registerInjectionDetectionTools(pi, deps);
+      verify.registerVerifyTools(pi, deps);
     })().catch((error) => {
       registrationPromise = null;
       throw error;

package/src/resources/extensions/browser-tools/tools/verify.ts

@@ -0,0 +1,117 @@
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import type { ToolDeps } from "../state.js";
+
+export function registerVerifyTools(pi: ExtensionAPI, deps: ToolDeps): void {
+	pi.registerTool({
+		name: "browser_verify",
+		label: "Browser Verify",
+		description:
+			"Run a structured browser verification flow: navigate to a URL, run checks (element visibility, text content), capture screenshots as evidence, and return structured pass/fail results.",
+		promptGuidelines: [
+			"Use browser_verify for UAT verification flows that need structured evidence.",
+			"Each check produces a pass/fail result with captured evidence.",
+			"Prefer this over manual navigation + assertion sequences for verification tasks.",
+		],
+		parameters: Type.Object({
+			url: Type.String({ description: "URL to navigate to" }),
+			checks: Type.Array(
+				Type.Object({
+					description: Type.String({ description: "What this check verifies" }),
+					selector: Type.Optional(Type.String({ description: "CSS selector to check" })),
+					expectedText: Type.Optional(Type.String({ description: "Expected text content" })),
+					expectedVisible: Type.Optional(Type.Boolean({ description: "Whether element should be visible" })),
+					screenshot: Type.Optional(Type.Boolean({ description: "Capture screenshot as evidence" })),
+				}),
+				{ description: "Verification checks to run" },
+			),
+			timeout: Type.Optional(Type.Number({ description: "Navigation timeout in ms", default: 10000 })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			const startTime = Date.now();
+			const { page } = await deps.ensureBrowser();
+			const timeout = params.timeout ?? 10000;
+
+			try {
+				await page.goto(params.url, { waitUntil: "domcontentloaded", timeout });
+			} catch (navErr) {
+				const msg = navErr instanceof Error ? navErr.message : String(navErr);
+				return {
+					content: [{ type: "text" as const, text: `Navigation failed: ${msg}` }],
+					details: {
+						url: params.url,
+						passed: false,
+						checks: params.checks.map((c) => ({ description: c.description, passed: false, error: msg })),
+						duration: Date.now() - startTime,
+					},
+				};
+			}
+
+			const results: Array<{
+				description: string;
+				passed: boolean;
+				actual?: string;
+				evidence?: string;
+				error?: string;
+			}> = [];
+
+			for (const check of params.checks) {
+				try {
+					let passed = true;
+					let actual: string | undefined;
+					let evidence: string | undefined;
+
+					if (check.selector) {
+						const element = await page.$(check.selector);
+
+						if (check.expectedVisible !== undefined) {
+							const isVisible = element ? await element.isVisible() : false;
+							passed = isVisible === check.expectedVisible;
+							actual = `visible=${isVisible}`;
+						}
+
+						if (check.expectedText !== undefined && element) {
+							const text = await element.textContent();
+							passed = passed && (text?.includes(check.expectedText) ?? false);
+							actual = `text="${text?.slice(0, 200)}"`;
+						}
+
+						if (!element && (check.expectedVisible === true || check.expectedText)) {
+							passed = false;
+							actual = "element not found";
+						}
+					}
+
+					if (check.screenshot) {
+						try {
+							const buf = await page.screenshot({ type: "png" });
+							evidence = `screenshot captured (${buf.length} bytes)`;
+						} catch {
+							evidence = "screenshot failed";
+						}
+					}
+
+					results.push({ description: check.description, passed, actual, evidence });
+				} catch (checkErr) {
+					results.push({
+						description: check.description,
+						passed: false,
+						error: checkErr instanceof Error ? checkErr.message : String(checkErr),
+					});
+				}
+			}
+
+			const allPassed = results.every((r) => r.passed);
+			const summary = results.map((r) => `${r.passed ? "PASS" : "FAIL"}: ${r.description}${r.actual ? ` (${r.actual})` : ""}${r.error ? ` — ${r.error}` : ""}`).join("\n");
+			return {
+				content: [{ type: "text" as const, text: `Verification ${allPassed ? "PASSED" : "FAILED"} (${results.filter(r => r.passed).length}/${results.length})\n\n${summary}` }],
+				details: {
+					url: params.url,
+					passed: allPassed,
+					checks: results,
+					duration: Date.now() - startTime,
+				},
+			};
+		},
+	});
+}

package/src/resources/extensions/cmux/index.ts

@@ -289,10 +289,17 @@ export class CmuxClient {
   }
 
   async createSplit(direction: "right" | "down" | "left" | "up"): Promise<string | null> {
+    return this.createSplitFrom(this.config.surfaceId, direction);
+  }
+
+  async createSplitFrom(
+    sourceSurfaceId: string | undefined,
+    direction: "right" | "down" | "left" | "up",
+  ): Promise<string | null> {
     if (!this.config.splits) return null;
     const before = new Set(await this.listSurfaceIds());
     const args = ["new-split", direction];
-    const scopedArgs = this.appendSurface(this.appendWorkspace(args), this.config.surfaceId);
+    const scopedArgs = this.appendSurface(this.appendWorkspace(args), sourceSurfaceId);
     await this.runAsync(scopedArgs);
     const after = await this.listSurfaceIds();
     for (const id of after) {
@@ -301,6 +308,55 @@ export class CmuxClient {
     return null;
   }
 
+  /**
+   * Create a grid of surfaces for parallel agent execution.
+   *
+   * Layout strategy (gsd stays in the original surface):
+   *   1 agent:  [gsd | A]
+   *   2 agents: [gsd | A]
+   *             [    | B]
+   *   3 agents: [gsd | A]
+   *             [ C  | B]
+   *   4 agents: [gsd | A]
+   *             [ C  | B]  (D splits from B downward)
+   *             [    | D]
+   *
+   * Returns surface IDs in order, or empty array on failure.
+   */
+  async createGridLayout(count: number): Promise<string[]> {
+    if (!this.config.splits || count <= 0) return [];
+    const surfaces: string[] = [];
+
+    // First split: create right column from the gsd surface
+    const rightCol = await this.createSplitFrom(this.config.surfaceId, "right");
+    if (!rightCol) return [];
+    surfaces.push(rightCol);
+    if (count === 1) return surfaces;
+
+    // Second split: split right column down → bottom-right
+    const bottomRight = await this.createSplitFrom(rightCol, "down");
+    if (!bottomRight) return surfaces;
+    surfaces.push(bottomRight);
+    if (count === 2) return surfaces;
+
+    // Third split: split gsd surface down → bottom-left
+    const bottomLeft = await this.createSplitFrom(this.config.surfaceId, "down");
+    if (!bottomLeft) return surfaces;
+    surfaces.push(bottomLeft);
+    if (count === 3) return surfaces;
+
+    // Fourth+: split subsequent surfaces down from the last created
+    let lastSurface = bottomRight;
+    for (let i = 3; i < count; i++) {
+      const next = await this.createSplitFrom(lastSurface, "down");
+      if (!next) break;
+      surfaces.push(next);
+      lastSurface = next;
+    }
+
+    return surfaces;
+  }
+
   async sendSurface(surfaceId: string, text: string): Promise<boolean> {
     const payload = text.endsWith("\n") ? text : `${text}\n`;
     const stdout = await this.runAsync(["send-surface", "--surface", surfaceId, payload]);

package/src/resources/extensions/env-utils.ts

@@ -0,0 +1,31 @@
+// GSD Extension — Environment variable utilities
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+//
+// Pure utility for checking existing env keys in .env files and process.env.
+// Extracted from get-secrets-from-user.ts to avoid pulling in @gsd/pi-tui
+// when only env-checking is needed (e.g. from files.ts during report generation).
+
+import { readFile } from "node:fs/promises";
+
+/**
+ * Check which keys already exist in a .env file or process.env.
+ * Returns the subset of `keys` that are already set.
+ */
+export async function checkExistingEnvKeys(keys: string[], envFilePath: string): Promise<string[]> {
+	let fileContent = "";
+	try {
+		fileContent = await readFile(envFilePath, "utf8");
+	} catch {
+		// ENOENT or other read error — proceed with empty content
+	}
+
+	const existing: string[] = [];
+	for (const key of keys) {
+		const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		const regex = new RegExp(`^${escaped}\\s*=`, "m");
+		if (regex.test(fileContent) || key in process.env) {
+			existing.push(key);
+		}
+	}
+	return existing;
+}

package/src/resources/extensions/get-secrets-from-user.ts

@@ -67,30 +67,11 @@ async function writeEnvKey(filePath: string, key: string, value: string): Promis
 
 // ─── Exported utilities ───────────────────────────────────────────────────────
 
-/**
- * Check which keys already exist in the .env file or process.env.
- * Returns the subset of `keys` that are already set.
- * Handles ENOENT gracefully (still checks process.env).
- * Empty-string values count as existing.
- */
-export async function checkExistingEnvKeys(keys: string[], envFilePath: string): Promise<string[]> {
-	let fileContent = "";
-	try {
-		fileContent = await readFile(envFilePath, "utf8");
-	} catch {
-		// ENOENT or other read error — proceed with empty content
-	}
-
-	const existing: string[] = [];
-	for (const key of keys) {
-		const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-		const regex = new RegExp(`^${escaped}\\s*=`, "m");
-		if (regex.test(fileContent) || key in process.env) {
-			existing.push(key);
-		}
-	}
-	return existing;
-}
+// Re-export from env-utils.ts so existing consumers still work.
+// The implementation lives in env-utils.ts to avoid pulling @gsd/pi-tui
+// into modules that only need env-checking (e.g. files.ts during reports).
+import { checkExistingEnvKeys } from "./env-utils.js";
+export { checkExistingEnvKeys };
 
 /**
  * Detect the write destination based on project files in basePath.

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));
+  }
+}