@opengsd/gsd-pi 1.2.0-dev.fb12b103 → 1.2.0-dev.fbdca60b

package/src/resources/shared/gsd-browser-path-sync.ts

@@ -0,0 +1,273 @@
+import { execFileSync } from 'node:child_process'
+import { chmodSync, copyFileSync, existsSync, lstatSync, readlinkSync, realpathSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, isAbsolute, join, delimiter as pathDelimiter, resolve as resolvePath } from 'node:path'
+import { isPnpmInstall, pathStartsWith } from './package-manager-detection.js'
+
+export interface GsdBrowserPathReconcileResult {
+  action: 'none' | 'synced' | 'shadowed'
+  pathCli?: string
+  installedCli?: string
+  syncTarget?: string
+  message?: string
+}
+
+function isBunGlobalInstall(argv1: string | undefined, env: NodeJS.ProcessEnv): boolean {
+  if ('bun' in process.versions) return true
+  if (!argv1) return false
+
+  const bunBinDirs: string[] = []
+  if (env.BUN_INSTALL) bunBinDirs.push(join(env.BUN_INSTALL, 'bin'))
+  bunBinDirs.push(join(homedir(), '.bun', 'bin'))
+
+  return bunBinDirs.some((dir) => pathStartsWith(argv1, dir))
+}
+
+function gsdBrowserBinaryName(platform: NodeJS.Platform): string {
+  return platform === 'win32' ? 'gsd-browser.cmd' : 'gsd-browser'
+}
+
+function tryResolveFromBinDir(binDir: string, platform: NodeJS.Platform): string | null {
+  const primary = join(binDir, gsdBrowserBinaryName(platform))
+  if (existsSync(primary)) return primary
+
+  if (platform === 'win32') {
+    const fallback = join(binDir, 'gsd-browser')
+    if (existsSync(fallback)) return fallback
+  }
+
+  return null
+}
+
+function tryResolveFromPackageRoot(
+  rootDir: string,
+  platform: NodeJS.Platform,
+): string | null {
+  const candidate = join(rootDir, '@opengsd', 'gsd-browser', 'bin', gsdBrowserBinaryName(platform))
+  if (existsSync(candidate)) return candidate
+
+  if (platform === 'win32') {
+    const fallback = join(rootDir, '@opengsd', 'gsd-browser', 'bin', 'gsd-browser')
+    if (existsSync(fallback)) return fallback
+  }
+
+  return null
+}
+
+function tryExecLookup(
+  command: string,
+  args: string[],
+  env: NodeJS.ProcessEnv,
+  platform: NodeJS.Platform,
+  resolve: (dir: string, platform: NodeJS.Platform) => string | null,
+): string | null {
+  try {
+    const dir = execFileSync(command, args, {
+      encoding: 'utf-8',
+      env,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 5000,
+    }).trim()
+    return resolve(dir, platform)
+  } catch {
+    return null
+  }
+}
+
+function resolvePathBinary(env: NodeJS.ProcessEnv, platform: NodeJS.Platform): string | null {
+  if (platform === 'win32') {
+    try {
+      const out = execFileSync('where', ['gsd-browser'], {
+        encoding: 'utf-8',
+        env,
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 5000,
+      }).trim()
+      const first = out.split(/\r?\n/).map((line) => line.trim()).find(Boolean)
+      return first && existsSync(first) ? first : null
+    } catch {
+      return null
+    }
+  }
+
+  for (const entry of (env.PATH ?? '').split(pathDelimiter)) {
+    if (!entry) continue
+    const candidate = join(entry, 'gsd-browser')
+    if (existsSync(candidate)) return candidate
+  }
+
+  return null
+}
+
+function resolveRealPath(pathValue: string): string {
+  try {
+    return realpathSync(pathValue)
+  } catch {
+    return resolvePath(pathValue)
+  }
+}
+
+function resolveSymlinkTarget(pathCli: string): string {
+  try {
+    const stat = lstatSync(pathCli)
+    if (!stat.isSymbolicLink()) return pathCli
+
+    const target = readlinkSync(pathCli)
+    return isAbsolute(target) ? target : resolvePath(dirname(pathCli), target)
+  } catch {
+    // PATH entry vanished or is inaccessible between resolution and sync.
+    // Fall back to the original path; subsequent sync will surface a useful
+    // error rather than escaping as an unhandled throw.
+    return pathCli
+  }
+}
+
+function resolveHomeDir(env: NodeJS.ProcessEnv): string {
+  const fromEnv = env.HOME?.trim() || env.USERPROFILE?.trim()
+  return resolvePath(fromEnv || homedir())
+}
+
+function canAutoSyncTarget(targetPath: string, env: NodeJS.ProcessEnv): boolean {
+  const home = resolveHomeDir(env)
+  const resolved = resolvePath(targetPath)
+  return pathStartsWith(resolved, home)
+}
+
+function syncBinary(installedCli: string, targetPath: string, platform: NodeJS.Platform): void {
+  const source = resolveRealPath(installedCli)
+  copyFileSync(source, targetPath)
+  if (platform !== 'win32') {
+    chmodSync(targetPath, 0o755)
+  }
+}
+
+/**
+ * Resolve the gsd-browser binary installed by the active global package manager.
+ */
+export function resolveGlobalGsdBrowserCliPath(
+  options: { env?: NodeJS.ProcessEnv; argv1?: string; platform?: NodeJS.Platform } = {},
+): string | null {
+  const env = options.env ?? process.env
+  const argv1 = options.argv1 ?? process.argv[1]
+  const platform = options.platform ?? process.platform
+
+  if (isBunGlobalInstall(argv1, env)) {
+    return (
+      tryExecLookup('bun', ['pm', 'bin', '-g'], env, platform, tryResolveFromBinDir)
+      ?? (env.BUN_INSTALL ? tryResolveFromBinDir(join(env.BUN_INSTALL, 'bin'), platform) : null)
+      ?? tryResolveFromBinDir(join(homedir(), '.bun', 'bin'), platform)
+    )
+  }
+
+  if (isPnpmInstall(argv1, env)) {
+    return (
+      tryExecLookup('pnpm', ['bin', '-g'], env, platform, tryResolveFromBinDir)
+      ?? tryExecLookup('pnpm', ['root', '-g'], env, platform, tryResolveFromPackageRoot)
+    )
+  }
+
+  return (
+    tryExecLookup('npm', ['bin', '-g'], env, platform, tryResolveFromBinDir)
+    ?? tryExecLookup('npm', ['root', '-g'], env, platform, tryResolveFromPackageRoot)
+  )
+}
+
+/**
+ * Resolve the gsd-browser binary that wins on PATH (`command -v` / `where`).
+ */
+export function resolveGsdBrowserOnPath(
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+): string | null {
+  return resolvePathBinary(env, platform)
+}
+
+/**
+ * After a global gsd-browser install, ensure the PATH-resolved binary matches
+ * the freshly installed global binary when an older copy is shadowing it.
+ */
+export function reconcileGsdBrowserPathAfterInstall(
+  options: {
+    latestVersion: string
+    compareSemver: (a: string, b: string) => number
+    resolvePathVersion: (env: NodeJS.ProcessEnv) => string | null
+    env?: NodeJS.ProcessEnv
+    argv1?: string
+    platform?: NodeJS.Platform
+  },
+): GsdBrowserPathReconcileResult {
+  const env = options.env ?? process.env
+  const argv1 = options.argv1 ?? process.argv[1]
+  const platform = options.platform ?? process.platform
+
+  const installedCli = resolveGlobalGsdBrowserCliPath({ env, argv1, platform })
+  if (!installedCli) {
+    return { action: 'none' }
+  }
+
+  const pathCli = resolveGsdBrowserOnPath(env, platform)
+  const installedReal = resolveRealPath(installedCli)
+  if (pathCli && resolveRealPath(pathCli) === installedReal) {
+    return { action: 'none', pathCli, installedCli }
+  }
+
+  const pathVersion = options.resolvePathVersion(env)
+  if (pathVersion && options.compareSemver(pathVersion, options.latestVersion) >= 0) {
+    return { action: 'none', pathCli: pathCli ?? undefined, installedCli }
+  }
+
+  if (!pathCli) {
+    return {
+      action: 'shadowed',
+      installedCli,
+      message:
+        'Installed gsd-browser globally, but no gsd-browser was found on PATH. Add your package manager global bin directory to PATH.',
+    }
+  }
+
+  const syncTarget = resolveSymlinkTarget(pathCli)
+  if (!canAutoSyncTarget(syncTarget, env)) {
+    return {
+      action: 'shadowed',
+      pathCli,
+      installedCli,
+      syncTarget,
+      message:
+        `PATH resolves gsd-browser to ${pathCli}, but the updated global install is at ${installedCli}. ` +
+        'Move your package manager global bin directory ahead of the stale location on PATH, or update the stale binary manually.',
+    }
+  }
+
+  let syncSucceeded = false
+  try {
+    syncBinary(installedCli, syncTarget, platform)
+    syncSucceeded = true
+  } catch {
+    // Fall through to shadowed guidance.
+  }
+
+  if (syncSucceeded) {
+    const refreshedVersion = options.resolvePathVersion(env)
+    const verified = refreshedVersion !== null
+      && options.compareSemver(refreshedVersion, options.latestVersion) >= 0
+    return {
+      action: 'synced',
+      pathCli,
+      installedCli,
+      syncTarget,
+      message: verified
+        ? `Synced PATH-resolved gsd-browser at ${syncTarget} to the updated global install.`
+        : `Synced PATH-resolved gsd-browser at ${syncTarget} to the updated global install. Could not verify the new version on PATH; restart your shell or rerun if it still reports the old version.`,
+    }
+  }
+
+  return {
+    action: 'shadowed',
+    pathCli,
+    installedCli,
+    syncTarget,
+    message:
+      `PATH resolves gsd-browser to ${pathCli}, but the updated global install is at ${installedCli}. ` +
+      'Move your package manager global bin directory ahead of the stale location on PATH, or update the stale binary manually.',
+  }
+}

package/src/resources/shared/package-manager-detection.ts

@@ -12,7 +12,7 @@ function hasPnpmPath(value: string | undefined): boolean {
   )
 }
 
-function pathStartsWith(pathValue: string | undefined, dir: string): boolean {
+export function pathStartsWith(pathValue: string | undefined, dir: string): boolean {
   if (!pathValue) return false
   const resolvedPath = resolvePath(pathValue)
   const resolvedDir = resolvePath(dir)

package/src/resources/skills/create-skill/SKILL.md

@@ -174,6 +174,9 @@ description: ...          # What it does AND when to use it (third person)
 ---
 ```
 
+Frontmatter must parse as YAML. Quote description values containing `:` or use
+a folded block (`description: >`) for longer trigger descriptions.
+
 Name conventions: `create-*`, `manage-*`, `setup-*`, `generate-*`, `build-*`
 </yaml_requirements>
 

package/src/resources/skills/create-skill/references/skill-structure.md

@@ -109,6 +109,7 @@ description: What it does and when to use it (third person, specific triggers)
 - No XML tags
 - Third person (never first or second person)
 - Include what it does AND when to use it
+- Must parse as YAML; quote values containing `:` or use `description: >`
 
 **Critical rule**: Always write in third person.
 - ✅ "Processes Excel files and generates reports"

package/dist/resources/extensions/gsd/user-input-boundary.js

@@ -1,218 +0,0 @@
-const USER_APPROVAL_UNIT_TYPES = new Set([
-    "discuss-project",
-    "discuss-requirements",
-    "discuss-milestone",
-    "research-decision",
-]);
-const REMOTE_QUESTION_FAILURE_RE = /(?:Remote (?:auth failed|questions failed|channel configured but returned no result|questions timed out|questions timed out or failed)|Failed to send questions via)/i;
-const APPROVAL_WAIT_RE = /\bwait(?:ing)?\s+for\s+(?:your\s+)?(?:confirmation|approval|input|response|answer)\b/i;
-const APPROVAL_QUESTION_RE = /\b(?:confirm|confirmation|approve|approval|approved|captured|correct|correctly|happy\s+with|ready\s+to\s+(?:write|save|proceed|ship)|(?:want|need)\s+to\s+adjust|should\s+I\s+(?:write|save|proceed)|do\s+you\s+want\s+me\s+to\s+(?:write|save|proceed)|ship\s+it)\b/i;
-const APPROVAL_RIGHT_QUESTION_RE = /\b(?:does|do|is|are|was|were|did)\b[^\n?]{0,120}\bright\b/i;
-const APPROVAL_CHANGE_QUESTION_RE = /\b(?:anything\s+else|anything|something)\s+to\s+(?:adjust|add|remove|reclassify)\b/i;
-const RESEARCH_DECISION_QUESTION_RE = /\b(?:research|skip)\b/i;
-function extractVisibleTextFromMessage(msg) {
-    if (!msg || typeof msg !== "object")
-        return "";
-    const content = msg.content;
-    if (typeof content === "string")
-        return content;
-    if (!Array.isArray(content))
-        return "";
-    const parts = [];
-    for (const block of content) {
-        if (!block || typeof block !== "object")
-            continue;
-        const typed = block;
-        if (typed.type === "text" && typeof typed.text === "string") {
-            parts.push(typed.text);
-        }
-        // thinking blocks intentionally excluded — they are internal reasoning, not user-visible
-    }
-    return parts.join("\n");
-}
-function extractTextFromMessage(msg) {
-    if (!msg || typeof msg !== "object")
-        return "";
-    const content = msg.content;
-    if (typeof content === "string")
-        return content;
-    if (!Array.isArray(content))
-        return "";
-    const parts = [];
-    for (const block of content) {
-        if (!block || typeof block !== "object")
-            continue;
-        const typed = block;
-        if (typed.type === "text" && typeof typed.text === "string") {
-            parts.push(typed.text);
-        }
-        if (typed.type === "thinking" && typeof typed.thinking === "string") {
-            parts.push(typed.thinking);
-        }
-    }
-    return parts.join("\n");
-}
-export function lastAssistantText(messages) {
-    if (!Array.isArray(messages))
-        return "";
-    for (let i = messages.length - 1; i >= 0; i--) {
-        const msg = messages[i];
-        if (!msg || typeof msg !== "object")
-            continue;
-        if (msg.role !== "assistant")
-            continue;
-        const text = extractTextFromMessage(msg).trim();
-        if (text)
-            return text;
-    }
-    return "";
-}
-function lastAssistantVisibleText(messages) {
-    if (!Array.isArray(messages))
-        return "";
-    for (let i = messages.length - 1; i >= 0; i--) {
-        const msg = messages[i];
-        if (!msg || typeof msg !== "object")
-            continue;
-        if (msg.role !== "assistant")
-            continue;
-        const text = extractVisibleTextFromMessage(msg).trim();
-        if (text)
-            return text;
-    }
-    return "";
-}
-function anyMessageMatches(messages, pattern) {
-    if (!Array.isArray(messages))
-        return false;
-    return messages.some((msg) => {
-        if (!msg || typeof msg !== "object")
-            return false;
-        if (msg.role === "user")
-            return false;
-        return pattern.test(extractVisibleTextFromMessage(msg));
-    });
-}
-function hasApprovalQuestion(text) {
-    for (let i = 0; i < text.length; i++) {
-        if (text[i] !== "?")
-            continue;
-        const previousBreak = Math.max(text.lastIndexOf("\n", i), text.lastIndexOf(".", i), text.lastIndexOf("!", i), text.lastIndexOf("?", i - 1));
-        const fragment = text.slice(previousBreak + 1, i + 1);
-        if (APPROVAL_QUESTION_RE.test(fragment))
-            return true;
-        if (APPROVAL_RIGHT_QUESTION_RE.test(fragment))
-            return true;
-        if (APPROVAL_CHANGE_QUESTION_RE.test(fragment))
-            return true;
-    }
-    return false;
-}
-function hasResearchDecisionQuestion(text) {
-    for (let i = 0; i < text.length; i++) {
-        if (text[i] !== "?")
-            continue;
-        const previousBreak = Math.max(text.lastIndexOf("\n", i), text.lastIndexOf(".", i), text.lastIndexOf("!", i), text.lastIndexOf("?", i - 1));
-        const fragment = text.slice(previousBreak + 1, i + 1);
-        if (RESEARCH_DECISION_QUESTION_RE.test(fragment))
-            return true;
-    }
-    return false;
-}
-export function approvalGateIdForUnit(unitType, unitId) {
-    if (!unitType)
-        return null;
-    if (unitType === "discuss-project")
-        return "depth_verification_project_confirm";
-    if (unitType === "discuss-requirements")
-        return "depth_verification_requirements_confirm";
-    if (unitType === "research-decision")
-        return "depth_verification_research_decision_confirm";
-    if (unitType === "discuss-milestone") {
-        const safeUnitId = typeof unitId === "string" && /^[A-Za-z0-9_-]+$/.test(unitId)
-            ? unitId
-            : "milestone";
-        return `depth_verification_${safeUnitId}_confirm`;
-    }
-    return null;
-}
-const CHANGE_REQUEST_RESPONSE_RE = /\b(?:no|nope|nah|not\s+yet|don't|do\s+not|change|add|remove|reclassify|adjust|clarify|missing|instead|but|however|wait|hold)\b/i;
-const APPROVAL_RESPONSE_RE = /^(?:y|yes|yeah|yep|approve|approved|confirm|confirmed|correct|right|looks\s+(?:good|right)|sounds\s+good|all\s+good|ok|okay|go\s+ahead|proceed|write\s+it|save\s+it|do\s+it)\b/i;
-const RESEARCH_DECISION_RESPONSE_RE = /^(?:research|run\s+research|do\s+research|skip|skip\s+research|no\s+research)\b/i;
-export function isExplicitApprovalResponse(input, pendingGateId) {
-    const text = input?.trim() ?? "";
-    if (!text)
-        return false;
-    if (pendingGateId?.includes("research_decision")) {
-        return RESEARCH_DECISION_RESPONSE_RE.test(text);
-    }
-    if (CHANGE_REQUEST_RESPONSE_RE.test(text))
-        return false;
-    return APPROVAL_RESPONSE_RE.test(text);
-}
-export function isAwaitingUserInput(messages) {
-    if (anyMessageMatches(messages, /ask_user_questions was cancelled before receiving a response/i))
-        return true;
-    if (anyMessageMatches(messages, REMOTE_QUESTION_FAILURE_RE))
-        return true;
-    const text = lastAssistantVisibleText(messages);
-    if (!text)
-        return false;
-    if (APPROVAL_WAIT_RE.test(text))
-        return true;
-    const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
-    if (lines.some((line) => line.endsWith("?")))
-        return true;
-    return hasApprovalQuestion(text);
-}
-export function isAwaitingApprovalBoundary(messages) {
-    if (anyMessageMatches(messages, /ask_user_questions was cancelled before receiving a response/i))
-        return true;
-    if (anyMessageMatches(messages, REMOTE_QUESTION_FAILURE_RE))
-        return true;
-    const text = lastAssistantVisibleText(messages);
-    if (!text)
-        return false;
-    if (APPROVAL_WAIT_RE.test(text))
-        return true;
-    return hasApprovalQuestion(text);
-}
-/** True when an assistant message already has an in-flight ask_user_questions tool call. */
-export function messageHasPendingAskUserQuestionsTool(message) {
-    if (!message || typeof message !== "object")
-        return false;
-    const content = message.content;
-    if (!Array.isArray(content))
-        return false;
-    return content.some((block) => {
-        if (!block || typeof block !== "object")
-            return false;
-        // Claude Code marks completion by attaching externalResult, not by setting state.
-        // Streaming blocks often carry no state; serverToolUse is the claude-code-cli MCP path.
-        const tool = block;
-        if (tool.type !== "toolCall" && tool.type !== "serverToolUse")
-            return false;
-        const name = String(tool.name ?? "").toLowerCase();
-        if (!name.includes("ask_user_questions"))
-            return false;
-        if (tool.externalResult !== undefined)
-            return false;
-        return tool.state !== "completed" && tool.state !== "done";
-    });
-}
-export function shouldPauseForUserApprovalQuestion(unitType, messages) {
-    if (!unitType || !USER_APPROVAL_UNIT_TYPES.has(unitType))
-        return false;
-    if (anyMessageMatches(messages, /ask_user_questions was cancelled before receiving a response/i))
-        return true;
-    if (anyMessageMatches(messages, REMOTE_QUESTION_FAILURE_RE))
-        return true;
-    const text = lastAssistantVisibleText(messages);
-    if (!text)
-        return false;
-    if (APPROVAL_WAIT_RE.test(text))
-        return true;
-    if (unitType === "research-decision")
-        return hasResearchDecisionQuestion(text);
-    return hasApprovalQuestion(text);
-}

package/dist/resources/skills/gsd-browser/SKILL.md

@@ -1,41 +0,0 @@
----
-name: gsd-browser
-description: "Use gsd-browser for browser automation and UAT: navigating local apps, inspecting pages, clicking or filling controls, taking screenshots, asserting UI behavior, collecting console/network diagnostics, visual diffing, and creating evidence bundles. Prefer this over legacy Playwright browser tooling when both are available."
-allowed-tools: Bash(gsd-browser:*), Bash(gsd-browser *)
----
-
-# gsd-browser
-
-Use `gsd-browser` as the default browser surface for automated UAT and real UI verification.
-
-## MCP First
-
-When MCP tools are available, prefer the `gsd-browser` server:
-
-- Discovery: `browser_snapshot_refs`, `browser_find`, `browser_get_accessibility_tree`
-- Actions: `browser_act`, `browser_batch`, `browser_click_ref`, `browser_fill_ref`
-- Verification: `browser_assert`, `browser_screenshot`, `browser_visual_diff`
-- Diagnostics: `browser_get_console_logs`, `browser_get_network_logs`, `browser_debug_bundle`
-
-If the host namespaces MCP tools, use names like `mcp__gsd-browser__browser_snapshot_refs`.
-
-## CLI Fallback
-
-The daemon starts automatically on first browser command.
-
-```bash
-gsd-browser navigate http://localhost:3000
-gsd-browser snapshot
-gsd-browser click-ref @v1:e1
-gsd-browser wait-for --condition network_idle
-gsd-browser assert --checks '[{"kind":"url_contains","text":"dashboard"}]'
-gsd-browser screenshot --output /tmp/gsd-browser-uat.png --format png
-```
-
-After any navigation, submit, or dynamic DOM change, take a fresh snapshot before using refs again. Refs are versioned, such as `@v1:e1` and `@v2:e3`, and old refs can become stale.
-
-Use `--json` when parsing output programmatically. Use named sessions for parallel or project-specific work:
-
-```bash
-gsd-browser --session gsd-pi navigate http://localhost:3000
-```