@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.65546769

package/src/resources/extensions/gsd/web-app-uat.ts

@@ -0,0 +1,144 @@
+// Project/App: gsd-pi
+// File Purpose: Web-app detection and browser-UAT guidance for planning and slice closeout.
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { resolveAmbientBrowserEngineResolution, type BrowserEngineResolution } from "../browser-tools/engine/selection.js";
+import { detectWebApp } from "../browser-tools/web-app-detect.js";
+import { UAT_MODE_POLICIES, type UatType } from "./uat-policy.js";
+
+export { detectWebApp };
+
+interface MinimalPackageJson {
+  dependencies?: Record<string, unknown>;
+  devDependencies?: Record<string, unknown>;
+  scripts?: Record<string, unknown>;
+}
+
+function readPackageJson(projectRoot: string): MinimalPackageJson | null {
+  const packageJsonPath = resolve(projectRoot, "package.json");
+  if (!existsSync(packageJsonPath)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(packageJsonPath, "utf-8")) as unknown;
+    return parsed && typeof parsed === "object" ? (parsed as MinimalPackageJson) : null;
+  } catch {
+    return null;
+  }
+}
+
+export function hasPlaywrightTestDependency(projectRoot: string): boolean {
+  const pkg = readPackageJson(projectRoot);
+  if (!pkg) return false;
+  const names = [
+    ...Object.keys(pkg.dependencies ?? {}),
+    ...Object.keys(pkg.devDependencies ?? {}),
+  ];
+  return names.some((name) => name === "playwright" || name === "@playwright/test");
+}
+
+export function findPlaywrightTestScript(projectRoot: string): string | null {
+  const pkg = readPackageJson(projectRoot);
+  if (!pkg?.scripts) return null;
+  for (const [name, value] of Object.entries(pkg.scripts)) {
+    if (typeof value !== "string") continue;
+    if (/\bplaywright\s+test\b/.test(value)) {
+      return `npm run ${name}`;
+    }
+  }
+  return null;
+}
+
+function describeBrowserToolBacking(engineResolution: BrowserEngineResolution): string {
+  switch (engineResolution.engine) {
+    case "gsd-browser":
+      return "This project looks browser-facing. GSD exposes `browser_*` tools backed by the managed gsd-browser engine for run-uat.";
+    case "legacy":
+      return "This project looks browser-facing. GSD exposes Playwright-backed `browser_*` tools for run-uat.";
+    case "off":
+      return "This project looks browser-facing, but Pi browser tools are disabled (GSD_BROWSER_ENGINE=off) — prefer `runtime-executable` UAT with automated browser test commands.";
+  }
+}
+
+// One bullet per recommended UAT mode; `mode` keys into UAT_MODE_POLICIES so
+// modes that require browser tools drop out of the guidance when the resolved
+// engine provides none (mixed/live-runtime share one bullet and one policy bit).
+const UAT_MODE_GUIDANCE: ReadonlyArray<{ mode: UatType; bullet: string }> = [
+  {
+    mode: "browser-executable",
+    bullet: "- `browser-executable` — navigate to `http://localhost:…`, click, screenshot, assert via `browser_*` tools during run-uat",
+  },
+  {
+    mode: "runtime-executable",
+    bullet: "- `runtime-executable` — run an automated browser test command via `gsd_uat_exec` (for example `npx playwright test`)",
+  },
+  {
+    mode: "mixed",
+    bullet: "- `mixed` / `live-runtime` — combine runtime startup checks with interactive browser verification",
+  },
+];
+
+/**
+ * Markdown block injected into plan/complete-slice prompts when the project
+ * looks browser-facing. Returns null for CLI/library-only repos. Guidance is
+ * composed from the resolved Browser Automation Engine so prompts never claim
+ * an engine the runtime is not using; `engineResolution` is injectable for
+ * tests and defaults to the ambient resolution.
+ */
+export function buildWebAppUatGuidanceBlock(
+  projectRoot: string,
+  engineResolution?: BrowserEngineResolution,
+): string | null {
+  if (!detectWebApp(projectRoot)) return null;
+
+  const resolvedEngine = engineResolution ?? resolveAmbientBrowserEngineResolution(projectRoot);
+  const browserToolsAvailable = resolvedEngine.engine !== "off";
+  const playwrightScript = findPlaywrightTestScript(projectRoot);
+  const hasPlaywright = hasPlaywrightTestDependency(projectRoot) || playwrightScript !== null;
+  const lines = [
+    "### Web App UAT (detected)",
+    "",
+    describeBrowserToolBacking(resolvedEngine),
+    "",
+    "**UAT modes (pick one per slice — do not use `artifact-driven` for browser steps):**",
+    ...UAT_MODE_GUIDANCE
+      .filter(({ mode }) => browserToolsAvailable || !UAT_MODE_POLICIES[mode].browserTools)
+      .map(({ bullet }) => bullet),
+    "",
+    "**Planning / closeout rules:**",
+    "- Preconditions must name the dev-server command and URL (for example `npm run dev` → `http://localhost:3000`)",
+    "- Slice Verification and UAT test cases must not say \"open in browser\" under `artifact-driven` — complete-slice rejects that",
+    "- Milestone `Verification Classes` → UAT row must describe browser-observable acceptance, not \"manual spot check\" alone",
+  ];
+
+  if (hasPlaywright) {
+    lines.push(
+      "",
+      "**Playwright:** dependency detected.",
+    );
+    if (playwrightScript) {
+      lines.push(
+        `- Prefer slice verification and runtime-executable UAT referencing \`${playwrightScript}\` or a focused \`npx playwright test <spec>\` command`,
+      );
+    } else {
+      lines.push(
+        "- Prefer runtime-executable UAT with `npx playwright test` (or a focused spec path) when UI behavior is covered by specs",
+      );
+    }
+    lines.push("- Name concrete spec paths in slice Verification (for example `e2e/smoke.spec.ts`)");
+  } else {
+    lines.push(
+      "",
+      "**Playwright scaffolding (first UI slice):** no `playwright` / `@playwright/test` dependency yet.",
+      "- Add a planning task that installs Playwright, adds `playwright.config.ts`, and creates a minimal smoke spec (for example `e2e/smoke.spec.ts`)",
+      "- Task `verify` should run `npx playwright test` (or the focused spec) with a safe, simple command",
+    );
+    if (browserToolsAvailable) {
+      lines.push(
+        "- Until specs exist, use `browser-executable` UAT with localhost preconditions and interactive `browser_*` checks at slice closeout",
+      );
+    }
+  }
+
+  return lines.join("\n");
+}

package/src/resources/extensions/gsd/workflow-event-ledger.ts

@@ -0,0 +1,131 @@
+import { createHash } from "node:crypto";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { atomicWriteSync } from "./atomic-write.js";
+import { resolveGsdPathContract } from "./paths.js";
+import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
+import { isUnifiedAuditEnabled } from "./uok/audit-toggle.js";
+import { normalizeWorkflowEventCommand } from "./workflow-event-vocabulary.js";
+import type { WorkflowEvent } from "./workflow-events.js";
+
+export const WORKFLOW_EVENT_LOG_FILENAME = "event-log.jsonl";
+
+export interface WorkflowEventLedgerLocation {
+  projectRoot: string;
+  workRoot: string;
+  projectGsd: string;
+  worktreeGsd: string | null;
+  projectLogPath: string;
+  worktreeLogPath: string | null;
+  isWorktree: boolean;
+}
+
+export type WorkflowEventInput = Omit<WorkflowEvent, "hash" | "session_id"> & {
+  actor_name?: string;
+  trigger_reason?: string;
+};
+
+export function resolveWorkflowEventLedgerLocation(
+  basePath: string,
+  originalProjectRoot?: string | null,
+): WorkflowEventLedgerLocation {
+  const contract = resolveGsdPathContract(basePath, originalProjectRoot);
+  return {
+    projectRoot: contract.projectRoot,
+    workRoot: contract.workRoot,
+    projectGsd: contract.projectGsd,
+    worktreeGsd: contract.worktreeGsd,
+    projectLogPath: join(contract.projectGsd, WORKFLOW_EVENT_LOG_FILENAME),
+    worktreeLogPath: contract.worktreeGsd
+      ? join(contract.worktreeGsd, WORKFLOW_EVENT_LOG_FILENAME)
+      : null,
+    isWorktree: contract.isWorktree,
+  };
+}
+
+export function workflowEventLogPath(basePath: string): string {
+  return resolveWorkflowEventLedgerLocation(basePath).projectLogPath;
+}
+
+export function workflowEventArchivePath(basePath: string, milestoneId: string): string {
+  const location = resolveWorkflowEventLedgerLocation(basePath);
+  return join(location.projectGsd, `event-log-${milestoneId}.jsonl.archived`);
+}
+
+export function readWorktreeEventLogPath(worktreeBasePath: string): string {
+  const location = resolveWorkflowEventLedgerLocation(worktreeBasePath);
+  return location.worktreeLogPath ?? location.projectLogPath;
+}
+
+export function buildWorkflowEvent(event: WorkflowEventInput, sessionId: string): WorkflowEvent {
+  const hash = createHash("sha256")
+    .update(JSON.stringify({ cmd: event.cmd, params: event.params }))
+    .digest("hex")
+    .slice(0, 16);
+
+  return {
+    v: 2,
+    ...event,
+    hash,
+    session_id: sessionId,
+  };
+}
+
+export function appendWorkflowEvent(
+  basePath: string,
+  event: WorkflowEventInput,
+  sessionId: string,
+): WorkflowEvent {
+  const fullEvent = buildWorkflowEvent(event, sessionId);
+  const location = resolveWorkflowEventLedgerLocation(basePath);
+
+  mkdirSync(location.projectGsd, { recursive: true });
+  appendFileSync(location.projectLogPath, `${JSON.stringify(fullEvent)}\n`, "utf-8");
+  emitWorkflowEventAudit(location.projectRoot, fullEvent);
+  return fullEvent;
+}
+
+export function writeWorkflowEventLog(basePath: string, events: readonly WorkflowEvent[]): void {
+  const location = resolveWorkflowEventLedgerLocation(basePath);
+  mkdirSync(location.projectGsd, { recursive: true });
+  const content = events.map((event) => JSON.stringify(event)).join("\n") + (events.length > 0 ? "\n" : "");
+  atomicWriteSync(location.projectLogPath, content);
+}
+
+export function writeWorktreeEventLog(
+  worktreeBasePath: string,
+  events: readonly WorkflowEvent[],
+): void {
+  const location = resolveWorkflowEventLedgerLocation(worktreeBasePath);
+  const logPath = location.worktreeLogPath ?? location.projectLogPath;
+  mkdirSync(dirname(logPath), { recursive: true });
+  const content = events.map((event) => JSON.stringify(event)).join("\n") + (events.length > 0 ? "\n" : "");
+  atomicWriteSync(logPath, content);
+}
+
+function emitWorkflowEventAudit(basePath: string, event: WorkflowEvent): void {
+  if (!isUnifiedAuditEnabled()) return;
+  try {
+    const normalized = normalizeWorkflowEventCommand(event.cmd) ?? "unknown";
+    emitUokAuditEvent(
+      basePath,
+      buildAuditEnvelope({
+        traceId: event.session_id,
+        category: "orchestration",
+        type: `workflow-event-${normalized}`,
+        payload: {
+          cmd: event.cmd,
+          params: event.params,
+          actor: event.actor,
+          actorName: event.actor_name,
+          triggerReason: event.trigger_reason,
+          eventTs: event.ts,
+          hash: event.hash,
+        },
+      }),
+    );
+  } catch {
+    // Best-effort: audit projection must never block the workflow event ledger.
+  }
+}

package/src/resources/extensions/gsd/workflow-event-vocabulary.ts

@@ -0,0 +1,59 @@
+import type { WorkflowEvent } from "./workflow-events.js";
+
+export interface WorkflowEventEntityKey {
+  type: string;
+  id: string;
+}
+
+export function normalizeWorkflowEventCommand(cmd: unknown): string | null {
+  return typeof cmd === "string" ? cmd.replace(/-/g, "_") : null;
+}
+
+/**
+ * Workflow progress events are keyed by the domain entity they mutate.
+ * Keep command aliases and conflict identity in this module so replay,
+ * conflict detection, and tests do not each grow their own vocabulary.
+ */
+export function workflowEventEntityKey(event: WorkflowEvent): WorkflowEventEntityKey | null {
+  const p = event.params;
+  const cmd = normalizeWorkflowEventCommand(event.cmd);
+  if (!cmd) return null;
+
+  switch (cmd) {
+    case "complete_task":
+    case "start_task":
+    case "skip_task":
+    case "report_blocker":
+    case "record_verification":
+    case "plan_task":
+      return typeof p["taskId"] === "string"
+        ? { type: "task", id: p["taskId"] }
+        : null;
+
+    case "complete_slice":
+    case "replan_slice":
+      return typeof p["sliceId"] === "string"
+        ? { type: "slice", id: p["sliceId"] }
+        : null;
+
+    case "plan_slice":
+      return typeof p["sliceId"] === "string"
+        ? { type: "slice_plan", id: p["sliceId"] }
+        : null;
+
+    case "complete_milestone":
+    case "plan_milestone":
+      return typeof p["milestoneId"] === "string"
+        ? { type: "milestone", id: p["milestoneId"] }
+        : null;
+
+    case "save_decision":
+      if (typeof p["scope"] === "string" && typeof p["decision"] === "string") {
+        return { type: "decision", id: `${p["scope"]}:${p["decision"]}` };
+      }
+      return null;
+
+    default:
+      return null;
+  }
+}

package/src/resources/extensions/gsd/workflow-events.ts

@@ -1,8 +1,13 @@
-import { createHash, randomUUID } from "node:crypto";
-import { appendFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { readFileSync, existsSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
 import { withFileLockSync } from "./file-lock.js";
+import {
+  appendWorkflowEvent,
+  workflowEventArchivePath,
+  workflowEventLogPath,
+  type WorkflowEventInput,
+} from "./workflow-event-ledger.js";
 import { logWarning } from "./workflow-logger.js";
 
 // ─── Session ID ───────────────────────────────────────────────────────────
@@ -40,22 +45,9 @@ export interface WorkflowEvent {
  */
 export function appendEvent(
   basePath: string,
-  event: Omit<WorkflowEvent, "hash" | "session_id"> & { actor_name?: string; trigger_reason?: string },
+  event: WorkflowEventInput,
 ): void {
-  const hash = createHash("sha256")
-    .update(JSON.stringify({ cmd: event.cmd, params: event.params }))
-    .digest("hex")
-    .slice(0, 16);
-
-  const fullEvent: WorkflowEvent = {
-    v: 2,
-    ...event,
-    hash,
-    session_id: ENGINE_SESSION_ID,
-  };
-  const dir = join(basePath, ".gsd");
-  mkdirSync(dir, { recursive: true });
-  appendFileSync(join(dir, "event-log.jsonl"), JSON.stringify(fullEvent) + "\n", "utf-8");
+  appendWorkflowEvent(basePath, event, ENGINE_SESSION_ID);
 }
 
 // ─── readEvents ──────────────────────────────────────────────────────────
@@ -125,8 +117,8 @@ export function compactMilestoneEvents(
   basePath: string,
   milestoneId: string,
 ): { archived: number } {
-  const logPath = join(basePath, ".gsd", "event-log.jsonl");
-  const archivePath = join(basePath, ".gsd", `event-log-${milestoneId}.jsonl.archived`);
+  const logPath = workflowEventLogPath(basePath);
+  const archivePath = workflowEventArchivePath(basePath, milestoneId);
 
   return withFileLockSync(logPath, () => {
     const allEvents = readEvents(logPath);

package/src/resources/extensions/gsd/workflow-logger.ts

@@ -109,6 +109,11 @@ export function setStderrLoggingEnabled(enabled: boolean): boolean {
   return previous;
 }
 
+/** Whether GSD extension diagnostics may write directly to process.stderr. */
+export function isGsdExtensionStderrEnabled(): boolean {
+  return _stderrEnabled;
+}
+
 // ─── Public API ─────────────────────────────────────────────────────────
 
 /**

package/src/resources/extensions/gsd/workflow-mcp-auto-prep.ts

@@ -4,6 +4,7 @@ import {
   type EnsureProjectWorkflowMcpConfigResult,
   ensureProjectWorkflowMcpConfig,
 } from "./mcp-project-config.js";
+import { warmWorkflowMcpProbeInBackground } from "./workflow-mcp-readiness-cache.js";
 import { usesWorkflowMcpTransport } from "./workflow-mcp.js";
 
 interface WorkflowMcpAutoPrepContext {
@@ -75,6 +76,7 @@ export function prepareWorkflowMcpForProject(
     if (result.status !== "unchanged") {
       prepCtx.ui?.notify?.(`GSD MCP Server Prepared at ${result.configPath}`, "info");
     }
+    warmWorkflowMcpProbeInBackground(projectRoot);
     return result;
   } catch (err) {
     prepCtx.ui?.notify?.(

package/src/resources/extensions/gsd/workflow-mcp-readiness-cache.ts

@@ -0,0 +1,150 @@
+// Project/App: gsd-pi
+// File Purpose: Share recent workflow MCP probe results across guided-flow and Claude Code SDK preflight.
+
+import { testMcpServerConnection } from "../mcp-client/manager.js";
+import { mcpToolMatchesBaseName } from "./mcp-tool-name.js";
+import {
+  detectWorkflowMcpLaunchConfig,
+  resolveWorkflowMcpProjectRoot,
+} from "./workflow-mcp.js";
+import { isWorkflowToolSurfaceName } from "./workflow-tool-surface.js";
+
+/** Reuse a recent successful probe instead of spawning another stdio server. */
+export const WORKFLOW_MCP_PROBE_CACHE_TTL_MS = 120_000;
+/** Per-probe connect + tools/list budget (server typically ready in ~1–2s). */
+export const WORKFLOW_MCP_PROBE_TIMEOUT_MS = 5_000;
+
+export interface WorkflowMcpProbeCacheEntry {
+  serverName: string;
+  tools: readonly string[];
+  probedAt: number;
+}
+
+type WorkflowMcpProbeResult = {
+  ok: boolean;
+  tools: readonly string[];
+  serverName?: string;
+  error?: string;
+};
+
+const cacheByProject = new Map<string, WorkflowMcpProbeCacheEntry>();
+const probeInFlightByProject = new Map<string, Promise<WorkflowMcpProbeResult>>();
+let activeWorkflowMcpSdkSessions = 0;
+
+function cacheKey(projectRoot: string): string {
+  return resolveWorkflowMcpProjectRoot(projectRoot);
+}
+
+export function beginWorkflowMcpSdkSession(): void {
+  activeWorkflowMcpSdkSessions++;
+}
+
+export function endWorkflowMcpSdkSession(): void {
+  activeWorkflowMcpSdkSessions = Math.max(0, activeWorkflowMcpSdkSessions - 1);
+}
+
+export function getCachedWorkflowMcpProbe(projectRoot: string): WorkflowMcpProbeCacheEntry | null {
+  const entry = cacheByProject.get(cacheKey(projectRoot));
+  if (!entry) return null;
+  if (Date.now() - entry.probedAt > WORKFLOW_MCP_PROBE_CACHE_TTL_MS) {
+    cacheByProject.delete(cacheKey(projectRoot));
+    return null;
+  }
+  return entry;
+}
+
+export function recordWorkflowMcpProbe(
+  projectRoot: string,
+  serverName: string,
+  tools: readonly string[],
+): void {
+  cacheByProject.set(cacheKey(projectRoot), {
+    serverName,
+    tools: [...tools],
+    probedAt: Date.now(),
+  });
+}
+
+export function clearWorkflowMcpProbeCache(projectRoot?: string): void {
+  if (projectRoot === undefined) {
+    cacheByProject.clear();
+    probeInFlightByProject.clear();
+    activeWorkflowMcpSdkSessions = 0;
+    return;
+  }
+  const key = cacheKey(projectRoot);
+  cacheByProject.delete(key);
+  probeInFlightByProject.delete(key);
+}
+
+export function workflowMcpProbeAdvertisesSurface(tools: readonly string[]): boolean {
+  return tools.some((tool) => isWorkflowToolSurfaceName(tool));
+}
+
+export function cachedWorkflowMcpCoversRequired(
+  projectRoot: string,
+  serverName: string,
+  required: readonly string[],
+): boolean {
+  const entry = getCachedWorkflowMcpProbe(projectRoot);
+  if (!entry || entry.serverName !== serverName) return false;
+  return required.every((tool) =>
+    entry.tools.some((name) => name === tool || mcpToolMatchesBaseName(name, tool)),
+  );
+}
+
+async function runProbeAndCacheWorkflowMcp(
+  projectRoot: string,
+  options: { timeoutMs?: number } = {},
+): Promise<WorkflowMcpProbeResult> {
+  const root = cacheKey(projectRoot);
+  const launch = detectWorkflowMcpLaunchConfig(root);
+  const serverName = launch?.name ?? "gsd-workflow";
+
+  const cached = getCachedWorkflowMcpProbe(projectRoot);
+  if (cached && workflowMcpProbeAdvertisesSurface(cached.tools)) {
+    return { ok: true, tools: cached.tools, serverName: cached.serverName };
+  }
+
+  const result = await testMcpServerConnection(serverName, {
+    projectDir: root,
+    timeoutMs: options.timeoutMs ?? WORKFLOW_MCP_PROBE_TIMEOUT_MS,
+  });
+  if (result.ok && workflowMcpProbeAdvertisesSurface(result.tools)) {
+    recordWorkflowMcpProbe(projectRoot, serverName, result.tools);
+  }
+  return {
+    ok: result.ok,
+    tools: result.tools,
+    serverName,
+    error: result.error,
+  };
+}
+
+export async function probeAndCacheWorkflowMcp(
+  projectRoot: string,
+  options: { timeoutMs?: number } = {},
+): Promise<WorkflowMcpProbeResult> {
+  const key = cacheKey(projectRoot);
+  const inFlight = probeInFlightByProject.get(key);
+  if (inFlight) return inFlight;
+
+  const promise = runProbeAndCacheWorkflowMcp(projectRoot, options).finally(() => {
+    probeInFlightByProject.delete(key);
+  });
+  probeInFlightByProject.set(key, promise);
+  return promise;
+}
+
+/** Fire-and-forget probe so /gsd dispatch often hits a warm cache. */
+export function warmWorkflowMcpProbeInBackground(projectRoot: string): void {
+  if (activeWorkflowMcpSdkSessions > 0) return;
+
+  const key = cacheKey(projectRoot);
+  if (getCachedWorkflowMcpProbe(projectRoot)) return;
+  if (probeInFlightByProject.has(key)) return;
+
+  void probeAndCacheWorkflowMcp(projectRoot).catch(() => {
+    // Background warm is best-effort.
+  });
+}