@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.8e6112e9

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/shared/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

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/executable-code.md

@@ -45,7 +45,7 @@ skill-name/
 **Reference pattern**: In SKILL.md, reference scripts using the `scripts/` path:
 
 ```bash
-python ~/.claude/skills/skill-name/scripts/analyze.py input.har
+python ~/.agents/skills/skill-name/scripts/analyze.py input.har
 ```
 </scripts_directory>
 </file_organization>

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/src/resources/skills/create-skill/workflows/add-reference.md

@@ -10,16 +10,21 @@
 ## Step 1: Select the Skill
 
 ```bash
-ls ~/.claude/skills/
+# User-global skills
+ls ~/.agents/skills/ 2>/dev/null
+# Project-local skills
+ls .agents/skills/ 2>/dev/null
 ```
 
 Present numbered list, ask: "Which skill needs a new reference?"
 
+Determine `{skill-path}`: use `.agents/skills/{skill-name}` (project-local) if found there, otherwise `~/.agents/skills/{skill-name}` (user-global). Project-local takes precedence because the skill catalog loads it first on name collision.
+
 ## Step 2: Analyze Current Structure
 
 ```bash
-cat ~/.claude/skills/{skill-name}/SKILL.md
-ls ~/.claude/skills/{skill-name}/references/ 2>/dev/null
+cat {skill-path}/SKILL.md
+ls {skill-path}/references/ 2>/dev/null
 ```
 
 Determine:

package/src/resources/skills/create-skill/workflows/add-script.md

@@ -12,6 +12,8 @@ Ask (if not already provided):
 - Which skill needs a script?
 - What operation should the script perform?
 
+Determine `{skill-path}`: use `.agents/skills/{skill-name}` (project-local) if found there, otherwise `~/.agents/skills/{skill-name}` (user-global). Project-local takes precedence because the skill catalog loads it first on name collision.
+
 ## Step 2: Analyze Script Need
 
 Confirm this is a good script candidate:
@@ -24,7 +26,7 @@ If not a good fit, suggest alternatives (inline code in workflow, reference exam
 ## Step 3: Create Scripts Directory
 
 ```bash
-mkdir -p ~/.claude/skills/{skill-name}/scripts
+mkdir -p {skill-path}/scripts
 ```
 
 ## Step 4: Design Script
@@ -58,7 +60,7 @@ set -euo pipefail
 ## Step 6: Make Executable (if bash)
 
 ```bash
-chmod +x ~/.claude/skills/{skill-name}/scripts/{script-name}.sh
+chmod +x {skill-path}/scripts/{script-name}.sh
 ```
 
 ## Step 7: Update Workflow to Use Script

package/src/resources/skills/create-skill/workflows/add-template.md

@@ -12,6 +12,8 @@ Ask (if not already provided):
 - Which skill needs a template?
 - What output does this template structure?
 
+Determine `{skill-path}`: use `.agents/skills/{skill-name}` (project-local) if found there, otherwise `~/.agents/skills/{skill-name}` (user-global). Project-local takes precedence because the skill catalog loads it first on name collision.
+
 ## Step 2: Analyze Template Need
 
 Confirm this is a good template candidate:
@@ -24,7 +26,7 @@ If not a good fit, suggest alternatives (workflow guidance, reference examples).
 ## Step 3: Create Templates Directory
 
 ```bash
-mkdir -p ~/.claude/skills/{skill-name}/templates
+mkdir -p {skill-path}/templates
 ```
 
 ## Step 4: Design Template Structure

package/src/resources/skills/create-skill/workflows/add-workflow.md

@@ -12,17 +12,22 @@
 **DO NOT use AskUserQuestion** - there may be many skills.
 
 ```bash
-ls ~/.claude/skills/
+# User-global skills
+ls ~/.agents/skills/ 2>/dev/null
+# Project-local skills
+ls .agents/skills/ 2>/dev/null
 ```
 
 Present numbered list, ask: "Which skill needs a new workflow?"
 
+Determine `{skill-path}`: use `.agents/skills/{skill-name}` (project-local) if found there, otherwise `~/.agents/skills/{skill-name}` (user-global). Project-local takes precedence because the skill catalog loads it first on name collision.
+
 ## Step 2: Analyze Current Structure
 
 Read the skill:
 ```bash
-cat ~/.claude/skills/{skill-name}/SKILL.md
-ls ~/.claude/skills/{skill-name}/workflows/ 2>/dev/null
+cat {skill-path}/SKILL.md
+ls {skill-path}/workflows/ 2>/dev/null
 ```
 
 Determine:

package/src/resources/skills/create-skill/workflows/upgrade-to-router.md

@@ -10,17 +10,22 @@
 ## Step 1: Select the Skill
 
 ```bash
-ls ~/.claude/skills/
+# User-global skills
+ls ~/.agents/skills/ 2>/dev/null
+# Project-local skills
+ls .agents/skills/ 2>/dev/null
 ```
 
 Present numbered list, ask: "Which skill should be upgraded to the router pattern?"
 
+Determine `{skill-path}`: use `.agents/skills/{skill-name}` (project-local) if found there, otherwise `~/.agents/skills/{skill-name}` (user-global). Project-local takes precedence because the skill catalog loads it first on name collision.
+
 ## Step 2: Verify It Needs Upgrading
 
 Read the skill:
 ```bash
-cat ~/.claude/skills/{skill-name}/SKILL.md
-ls ~/.claude/skills/{skill-name}/
+cat {skill-path}/SKILL.md
+ls {skill-path}/
 ```
 
 **Already a router?** (has workflows/ and intake question)
@@ -65,8 +70,8 @@ Ask: "Does this breakdown look right? Any adjustments?"
 ## Step 4: Create Directory Structure
 
 ```bash
-mkdir -p ~/.claude/skills/{skill-name}/workflows
-mkdir -p ~/.claude/skills/{skill-name}/references
+mkdir -p {skill-path}/workflows
+mkdir -p {skill-path}/references
 ```
 
 ## Step 5: Extract Workflows

package/src/resources/skills/create-skill/workflows/verify-skill.md

@@ -15,18 +15,23 @@ Skills contain claims about external things: APIs, CLI tools, frameworks, servic
 ## Step 1: Select the Skill
 
 ```bash
-ls ~/.claude/skills/
+# User-global skills
+ls ~/.agents/skills/ 2>/dev/null
+# Project-local skills
+ls .agents/skills/ 2>/dev/null
 ```
 
 Present numbered list, ask: "Which skill should I verify for accuracy?"
 
+Determine `{skill-path}`: use `.agents/skills/{skill-name}` (project-local) if found there, otherwise `~/.agents/skills/{skill-name}` (user-global). Project-local takes precedence because the skill catalog loads it first on name collision.
+
 ## Step 2: Read and Categorize
 
 Read the entire skill (SKILL.md + workflows/ + references/):
 ```bash
-cat ~/.claude/skills/{skill-name}/SKILL.md
-cat ~/.claude/skills/{skill-name}/workflows/*.md 2>/dev/null
-cat ~/.claude/skills/{skill-name}/references/*.md 2>/dev/null
+cat {skill-path}/SKILL.md
+cat {skill-path}/workflows/*.md 2>/dev/null
+cat {skill-path}/references/*.md 2>/dev/null
 ```
 
 Categorize by primary dependency type:

package/src/resources/skills/spike-wrap-up/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: spike-wrap-up
-description: Package findings from a completed spike into a durable project-local skill that auto-loads on future similar work. Reads the latest `.gsd/workflows/spikes/` dir, interviews the user on what's reusable, then writes `.claude/skills/<name>/SKILL.md`. Use when asked to "wrap up the spike", "package this as a skill", "make this reusable", "turn findings into a skill", or at the synthesize phase of `/gsd start spike`.
+description: Package findings from a completed spike into a durable project-local skill that auto-loads on future similar work. Reads the latest `.gsd/workflows/spikes/` dir, interviews the user on what's reusable, then writes `.agents/skills/<name>/SKILL.md`. Use when asked to "wrap up the spike", "package this as a skill", "make this reusable", "turn findings into a skill", or at the synthesize phase of `/gsd start spike`.
 ---
 
 <objective>
-Convert the output of a research spike (`SCOPE.md`, `research/*.md`, `RECOMMENDATION.md`) into a project-local skill under `.claude/skills/` so that the next time a similar task comes up, the agent loads the skill automatically. This is how throwaway spikes become durable capital.
+Convert the output of a research spike (`SCOPE.md`, `research/*.md`, `RECOMMENDATION.md`) into a project-local skill under `.agents/skills/` so that the next time a similar task comes up, the agent loads the skill automatically. This is how throwaway spikes become durable capital.
 </objective>
 
 <context>
 GSD's spike workflow (`src/resources/extensions/gsd/workflow-templates/spike.md`) produces documents in `.gsd/workflows/spikes/<slug>/`. Those documents are useful once and then forgotten unless something packages them for reuse.
 
-GSD already watches `.claude/skills/` (and `.agents/skills/`) at both user and project levels — see `src/resources/extensions/gsd/skill-discovery.ts`. Any skill written there is picked up on the next session without further wiring. This skill is the bridge from "spike done" to "skill available."
+GSD already watches `.agents/skills/` (and `.claude/skills/` as a legacy compat path) at both user and project levels — see `src/resources/extensions/gsd/skill-discovery.ts`. Any skill written there is picked up on the next session without further wiring. This skill is the bridge from "spike done" to "skill available."
 
 Invocation points:
 - End of Phase 3 (synthesize) in `/gsd start spike` — prompt suggests running this skill
@@ -21,7 +21,7 @@ Invocation points:
 <core_principle>
 **NOT EVERY SPIKE DESERVES A SKILL.** If the recommendation was "don't do X," there may be no reusable guidance. Ask the user first; exit without writing if the answer is no.
 
-**PROJECT-LOCAL, NOT USER-GLOBAL.** Write to `.claude/skills/` in the repo, not `~/.claude/skills/`. The skill encodes project-specific choices that should not leak into unrelated projects.
+**PROJECT-LOCAL, NOT USER-GLOBAL.** Write to `.agents/skills/` in the project root, not `~/.agents/skills/`. The skill encodes project-specific choices that should not leak into unrelated projects.
 
 **DESCRIPTION IS THE DISCOVERABILITY SIGNAL.** The `description` field in frontmatter is the primary signal the agent uses to judge relevance and decide whether to load the skill — it is a heuristic, not a deterministic trigger. Write it as keywords the future agent will plausibly encounter, not a summary.
 </core_principle>
@@ -65,7 +65,7 @@ Show this sketch to the user. One round of feedback. Iterate.
 
 ## Step 4: Write the skill
 
-Write to `.claude/skills/<name>/SKILL.md` (create the directory). Match the frontmatter + XML-tag structure used by other bundled skills — see `src/resources/skills/review/SKILL.md` for the canonical shape.
+Write to `.agents/skills/<name>/SKILL.md` (create the directory). Match the frontmatter + XML-tag structure used by other bundled skills — see `src/resources/skills/review/SKILL.md` for the canonical shape.
 
 Minimum structure:
 
@@ -102,7 +102,7 @@ description: <one sentence with trigger keywords>
 </success_criteria>
 ```
 
-If the spike produced a reusable template (a config file, a starter script), copy it into `.claude/skills/<name>/templates/` or `.claude/skills/<name>/references/` and reference it from the skill body.
+If the spike produced a reusable template (a config file, a starter script), copy it into `.agents/skills/<name>/templates/` or `.agents/skills/<name>/references/` and reference it from the skill body.
 
 ## Step 5: Archive the spike, link from the skill
 
@@ -112,13 +112,13 @@ If the spike produced a reusable template (a config file, a starter script), cop
 
 ## Step 6: Confirm pickup
 
-Tell the user the skill will be surfaced on the next session via `skill-discovery.ts`. If they want to use it immediately, they can `Read .claude/skills/<name>/SKILL.md` now.
+Tell the user the skill will be surfaced on the next session via `skill-discovery.ts`. If they want to use it immediately, they can `Read .agents/skills/<name>/SKILL.md` now.
 
 </process>
 
 <anti_patterns>
 
-- **Writing to `~/.claude/skills/`.** That's user-global. Project spikes produce project skills — keep them scoped.
+- **Writing to `~/.claude/skills/` or `.claude/skills/`.** These are legacy Claude Code compatibility paths. Write project skills to `.agents/skills/` in the project root instead.
 - **Verbose frontmatter description.** The description is an index entry, not a tutorial. Keywords over prose.
 - **Packaging every spike.** If the outcome was "we decided X once," append to DECISIONS.md and move on.
 - **Copy-pasting the spike verbatim into the skill.** The spike is research; the skill is executable guidance. Re-author.
@@ -128,7 +128,7 @@ Tell the user the skill will be surfaced on the next session via `skill-discover
 
 <success_criteria>
 
-- [ ] A new `.claude/skills/<name>/SKILL.md` exists with well-formed frontmatter.
+- [ ] A new `.agents/skills/<name>/SKILL.md` exists with well-formed frontmatter.
 - [ ] The `description` field uses keywords that will plausibly match future agent work.
 - [ ] The skill body is executable on its own without re-reading the originating spike.
 - [ ] The originating spike is referenced from the skill.