gsd-pi 2.71.0 → 2.72.0-dev.3118184

package/dist/resource-loader.js

@@ -2,7 +2,7 @@ import { DefaultResourceLoader, sortExtensionPaths } from '@gsd/pi-coding-agent'
 import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
 import { chmodSync, copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, openSync, closeSync, readFileSync, readlinkSync, readdirSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
-import { dirname, join, relative, resolve } from 'node:path';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { compareSemver } from './update-check.js';
 import { discoverExtensionEntryPaths } from './extension-discovery.js';
@@ -254,34 +254,160 @@ function copyDirRecursive(src, dest) {
  * ~/.gsd/agent/extensions/ have no ancestor node_modules, so imports of
  * @gsd/* packages fail. The symlink makes Node's standard resolution find
  * them without requiring every call site to use jiti.
+ *
+ * Layout differences by install method:
+ * - Source/monorepo: packageRoot/node_modules has everything → simple symlink
+ * - npm/bun global: deps hoisted to dirname(packageRoot), including @gsd/* → simple symlink
+ * - pnpm global: external deps hoisted, but @gsd/* stays in packageRoot/node_modules
+ *   → merged directory with symlinks from both roots (#3529, #3564)
  */
 function ensureNodeModulesSymlink(agentDir) {
     const agentNodeModules = join(agentDir, 'node_modules');
-    const gsdNodeModules = join(packageRoot, 'node_modules');
+    const internalNodeModules = join(packageRoot, 'node_modules');
+    const hoistedNodeModules = dirname(packageRoot);
+    const isGlobalInstall = basename(hoistedNodeModules) === 'node_modules';
+    if (!isGlobalInstall) {
+        // Source/monorepo: internal node_modules has everything
+        reconcileSymlink(agentNodeModules, internalNodeModules);
+        return;
+    }
+    // Global install: check if workspace scopes (@gsd/*) are hoisted.
+    // npm/bun hoist everything; pnpm keeps workspace packages internal.
+    if (!hasMissingWorkspaceScopes(hoistedNodeModules, internalNodeModules)) {
+        // Everything is hoisted — simple symlink to parent node_modules
+        reconcileSymlink(agentNodeModules, hoistedNodeModules);
+        return;
+    }
+    // pnpm-style layout: create a real directory merging both roots
+    reconcileMergedNodeModules(agentNodeModules, hoistedNodeModules, internalNodeModules);
+}
+/** Check if any @gsd* scopes exist in internal but not in hoisted node_modules */
+function hasMissingWorkspaceScopes(hoisted, internal) {
+    if (!existsSync(internal))
+        return false;
     try {
-        const stat = lstatSync(agentNodeModules);
+        for (const entry of readdirSync(internal, { withFileTypes: true })) {
+            if (entry.isDirectory() && entry.name.startsWith('@gsd') &&
+                !existsSync(join(hoisted, entry.name))) {
+                return true;
+            }
+        }
+    }
+    catch { /* non-fatal */ }
+    return false;
+}
+/** Ensure a symlink at `link` points to `target`, fixing stale/wrong entries */
+function reconcileSymlink(link, target) {
+    try {
+        const stat = lstatSync(link);
         if (stat.isSymbolicLink()) {
-            const existing = readlinkSync(agentNodeModules);
-            // Symlink exists — verify it points to the correct, existing target
-            if (existing === gsdNodeModules && existsSync(agentNodeModules))
+            const existing = readlinkSync(link);
+            if (existing === target && existsSync(link))
                 return; // correct and target exists
-            // Stale or wrong target — remove and recreate
+            unlinkSync(link);
+        }
+        else {
+            // Real directory (or merged dir from previous pnpm fix) — remove it
+            rmSync(link, { recursive: true, force: true });
+        }
+    }
+    catch {
+        // lstatSync throws if path doesn't exist — fine, we'll create below
+    }
+    try {
+        symlinkSync(target, link, 'junction');
+    }
+    catch (err) {
+        console.error(`[gsd] WARN: Failed to symlink ${link} → ${target}: ${err instanceof Error ? err.message : err}`);
+    }
+}
+/**
+ * Create a real node_modules directory containing symlinks from both the
+ * hoisted root (external deps) and internal root (@gsd/* workspace packages).
+ * Used for pnpm global installs where @gsd/* isn't hoisted.
+ */
+function reconcileMergedNodeModules(agentNodeModules, hoisted, internal) {
+    // Fast path: if already merged for this packageRoot + same directory contents, skip.
+    // The fingerprint includes entry names from both roots so `pnpm add/remove` triggers rebuild.
+    const marker = join(agentNodeModules, '.gsd-merged');
+    const fingerprint = mergedFingerprint(hoisted, internal);
+    try {
+        if (existsSync(marker) && readFileSync(marker, 'utf-8').trim() === fingerprint)
+            return;
+    }
+    catch { /* rebuild */ }
+    // Remove any existing symlink or stale merged directory
+    try {
+        const stat = lstatSync(agentNodeModules);
+        if (stat.isSymbolicLink()) {
             unlinkSync(agentNodeModules);
         }
         else {
-            // Real directory (not a symlink) is blocking — remove it
             rmSync(agentNodeModules, { recursive: true, force: true });
         }
     }
-    catch {
-        // lstatSync throws if path doesn't exist — that's fine, we'll create below
+    catch { /* doesn't exist */ }
+    mkdirSync(agentNodeModules, { recursive: true });
+    let linkedCount = 0;
+    // Symlink entries from the hoisted node_modules (external deps)
+    try {
+        for (const entry of readdirSync(hoisted, { withFileTypes: true })) {
+            // Skip the gsd-pi package itself and dotfiles
+            if (entry.name === basename(packageRoot))
+                continue;
+            if (entry.name.startsWith('.'))
+                continue;
+            try {
+                symlinkSync(join(hoisted, entry.name), join(agentNodeModules, entry.name));
+                linkedCount++;
+            }
+            catch { /* skip individual */ }
+        }
     }
+    catch (err) {
+        console.error(`[gsd] WARN: Failed to read hoisted node_modules at ${hoisted}: ${err instanceof Error ? err.message : err}`);
+    }
+    // Overlay internal node_modules entries that weren't hoisted.
+    // This covers @gsd/* workspace packages AND optional deps like
+    // @anthropic-ai/claude-agent-sdk that npm keeps internal.
     try {
-        symlinkSync(gsdNodeModules, agentNodeModules, 'junction');
+        for (const entry of readdirSync(internal, { withFileTypes: true })) {
+            if (entry.name.startsWith('.'))
+                continue;
+            const link = join(agentNodeModules, entry.name);
+            // Replace hoisted symlink with internal version (internal takes precedence)
+            try {
+                lstatSync(link);
+                unlinkSync(link);
+            }
+            catch { /* didn't exist — will create below */ }
+            try {
+                symlinkSync(join(internal, entry.name), link);
+                linkedCount++;
+            }
+            catch { /* skip individual */ }
+        }
     }
     catch (err) {
-        // This failure makes GSD non-functional — extensions can't resolve @gsd/* packages
-        console.error(`[gsd] WARN: Failed to symlink ${agentNodeModules} → ${gsdNodeModules}: ${err instanceof Error ? err.message : err}`);
+        console.error(`[gsd] WARN: Failed to read internal node_modules at ${internal}: ${err instanceof Error ? err.message : err}`);
+    }
+    // Only stamp marker if we actually linked something — avoids caching a broken state
+    if (linkedCount > 0) {
+        try {
+            writeFileSync(marker, fingerprint);
+        }
+        catch { /* non-fatal */ }
+    }
+}
+/** Build a cache fingerprint from packageRoot + sorted entry names of both directories */
+function mergedFingerprint(hoisted, internal) {
+    try {
+        const h = readdirSync(hoisted).sort().join(',');
+        const i = readdirSync(internal).sort().join(',');
+        return `${packageRoot}\n${h}\n${i}`;
+    }
+    catch {
+        return packageRoot; // fallback: at least invalidate on version change
     }
 }
 /**

package/dist/resources/GSD-WORKFLOW.md

@@ -275,7 +275,7 @@ Work flows through these phases. Each phase produces a file.
 **How to do it manually:**
 1. Read the roadmap to understand the scope.
 2. Identify 3-5 gray areas — implementation decisions the user cares about.
-3. Use `ask_user_questions` to discuss each area.
+3. Use `ask_user_questions` to discuss each area, one round at a time. Never fabricate user input; wait for the user's actual response before the next round.
 4. Write decisions to the appropriate context file (`M###-CONTEXT.md` or `S##-CONTEXT.md`).
 5. Do NOT discuss how to implement — only what the user wants.
 

package/dist/resources/agents/debugger.md

@@ -0,0 +1,58 @@
+---
+name: debugger
+description: Hypothesis-driven bug investigation with root cause analysis
+model: sonnet
+---
+
+You are a debugger. Investigate bugs using a systematic, hypothesis-driven approach. Your goal is to find the root cause, not just suppress symptoms.
+
+## Process
+
+1. **Reproduce**: Understand the symptoms — what happens vs. what should happen
+2. **Hypothesize**: List 2-3 most likely causes based on symptoms
+3. **Investigate**: For each hypothesis, gather evidence (read code, check logs, trace execution)
+4. **Narrow**: Eliminate hypotheses that don't match the evidence
+5. **Root cause**: Identify the actual cause with file:line references
+6. **Fix**: Propose the minimal change that addresses the root cause
+
+## Investigation Tools
+
+- Read source files at specific line ranges
+- Grep for error messages, function names, variable usage
+- Check git blame for recent changes to suspect areas
+- Read test files to understand expected behavior
+- Run tests to reproduce failures
+
+## Output Format
+
+## Symptoms
+
+What's happening vs. what's expected.
+
+## Hypotheses
+
+1. **[hypothesis]** — why this could be the cause
+2. **[hypothesis]** — why this could be the cause
+
+## Investigation
+
+### Hypothesis 1: [name]
+
+Evidence gathered, files read, what was found.
+**Verdict:** Confirmed / Eliminated — reason.
+
+### Hypothesis 2: [name]
+
+(same structure)
+
+## Root Cause
+
+**File:** `path/to/file.ts:42`
+**Cause:** Clear explanation of the bug.
+**Why it wasn't caught:** Missing test, edge case, etc.
+
+## Recommended Fix
+
+```typescript
+// minimal fix with explanation
+```

package/dist/resources/agents/doc-writer.md

@@ -0,0 +1,43 @@
+---
+name: doc-writer
+description: Documentation generation from code — API docs, inline comments, READMEs
+model: sonnet
+---
+
+You are a documentation specialist. You read code and produce clear, accurate documentation. You write for the reader, not the author — explain what they need to know to use or maintain the code.
+
+## Process
+
+1. Read the code thoroughly — understand what it does, not just how
+2. Identify the audience — users (API docs), maintainers (inline docs), or newcomers (guides)
+3. Write documentation that answers the reader's actual questions
+4. Verify accuracy — every code reference must match the current implementation
+
+## Documentation Types
+
+- **API docs**: Function signatures, parameters, return values, examples, error cases
+- **Inline comments**: Explain *why*, not *what* — the code shows what, comments explain intent
+- **Module docs**: What this module does, its public API, and how it fits in the architecture
+- **Guides**: Step-by-step instructions for common tasks with working examples
+
+## Quality Rules
+
+- Every claim must be verifiable against the current code
+- Examples must be working code, not pseudocode
+- Don't document the obvious — focus on non-obvious behavior, gotchas, and edge cases
+- Keep it concise — more docs isn't better docs
+- Use the project's existing documentation style and format
+
+## Output Format
+
+## Documentation Plan
+
+What to document and for whom.
+
+## Documentation
+
+(The actual documentation content, formatted appropriately for its type)
+
+## Accuracy Check
+
+Files referenced and verified against current implementation.

package/dist/resources/agents/git-ops.md

@@ -0,0 +1,56 @@
+---
+name: git-ops
+description: Conflict resolution, rebase strategy, PR preparation, and changelog generation
+model: sonnet
+---
+
+You are a git operations specialist. You handle merge conflicts, plan rebase strategies, prepare pull requests, and generate changelogs. You understand git internals well enough to choose the right strategy for each situation.
+
+## Capabilities
+
+### Conflict Resolution
+- Analyze conflict markers and understand both sides' intent
+- Choose the correct resolution based on code context, not just recency
+- Verify resolved code compiles and tests pass
+
+### Rebase Strategy
+- Assess whether rebase or merge is appropriate for the situation
+- Plan interactive rebase sequences (squash, reorder, edit)
+- Handle complex rebase conflicts with minimal manual intervention
+
+### PR Preparation
+- Write clear PR titles and descriptions from commit history
+- Organize commits into logical, reviewable units
+- Ensure CI checks will pass before pushing
+
+### Changelog Generation
+- Extract user-facing changes from commit messages and code diffs
+- Categorize changes (features, fixes, breaking changes)
+- Write changelog entries for the target audience (users, not developers)
+
+## Process
+
+1. Assess the git state — branches, commits, conflicts, divergence
+2. Determine the goal — clean history, resolved conflicts, PR ready
+3. Plan the steps — in order, with rollback points
+4. Execute carefully — verify after each step
+5. Confirm the result — clean history, passing tests
+
+## Output Format
+
+## Git State
+
+Current branch, commits, conflicts, or divergence summary.
+
+## Strategy
+
+What to do and why this approach.
+
+## Steps
+
+1. Command or action — with expected outcome
+2. Command or action — with verification
+
+## Result
+
+Final state after operations complete.