gsd-pi 2.67.0-dev.509bd95 → 2.67.0-dev.5399650

package/scripts/link-workspace-packages.cjs

@@ -2,7 +2,8 @@
 /**
  * link-workspace-packages.cjs
  *
- * Creates node_modules/@gsd/* symlinks pointing to packages/* directories.
+ * Creates node_modules/@gsd/* and node_modules/@gsd-build/* symlinks pointing
+ * to shipped packages/* directories.
  *
  * During development, npm workspaces creates these automatically. But in the
  * published tarball, workspace packages are shipped under packages/ (via the
@@ -20,27 +21,33 @@ const { resolve, join } = require('path')
 
 const root = resolve(__dirname, '..')
 const packagesDir = join(root, 'packages')
-const nodeModulesGsd = join(root, 'node_modules', '@gsd')
+const scopeDirs = {
+  '@gsd': join(root, 'node_modules', '@gsd'),
+  '@gsd-build': join(root, 'node_modules', '@gsd-build'),
+}
 
-// Map directory names to package names
+// Map directory names to scoped package names
 const packageMap = {
-  'native': 'native',
-  'pi-agent-core': 'pi-agent-core',
-  'pi-ai': 'pi-ai',
-  'pi-coding-agent': 'pi-coding-agent',
-  'pi-tui': 'pi-tui',
+  'native': { scope: '@gsd', name: 'native' },
+  'pi-agent-core': { scope: '@gsd', name: 'pi-agent-core' },
+  'pi-ai': { scope: '@gsd', name: 'pi-ai' },
+  'pi-coding-agent': { scope: '@gsd', name: 'pi-coding-agent' },
+  'pi-tui': { scope: '@gsd', name: 'pi-tui' },
+  'rpc-client': { scope: '@gsd-build', name: 'rpc-client' },
 }
 
-// Ensure @gsd scope directory exists
-if (!existsSync(nodeModulesGsd)) {
-  mkdirSync(nodeModulesGsd, { recursive: true })
+for (const scopeDir of Object.values(scopeDirs)) {
+  if (!existsSync(scopeDir)) {
+    mkdirSync(scopeDir, { recursive: true })
+  }
 }
 
 let linked = 0
 let copied = 0
-for (const [dir, name] of Object.entries(packageMap)) {
+for (const [dir, pkg] of Object.entries(packageMap)) {
   const source = join(packagesDir, dir)
-  const target = join(nodeModulesGsd, name)
+  const scopeDir = scopeDirs[pkg.scope]
+  const target = join(scopeDir, pkg.name)
 
   if (!existsSync(source)) continue
 
@@ -50,7 +57,7 @@ for (const [dir, name] of Object.entries(packageMap)) {
       const stat = lstatSync(target)
       if (stat.isSymbolicLink()) {
         const linkTarget = readlinkSync(target)
-        if (resolve(join(nodeModulesGsd, linkTarget)) === source || linkTarget === source) {
+        if (resolve(join(scopeDir, linkTarget)) === source || linkTarget === source) {
           continue // Already correct
         }
         unlinkSync(target) // Wrong target, relink

package/src/resources/extensions/gsd/auto/session.ts

@@ -84,6 +84,9 @@ export class AutoSession {
   // ── Paths ────────────────────────────────────────────────────────────────
   basePath = "";
   originalBasePath = "";
+  previousProjectRootEnv: string | null = null;
+  hadProjectRootEnv = false;
+  projectRootEnvCaptured = false;
   gitService: GitServiceImpl | null = null;
 
   // ── Dispatch counters ────────────────────────────────────────────────────
@@ -192,6 +195,9 @@ export class AutoSession {
     // Paths
     this.basePath = "";
     this.originalBasePath = "";
+    this.previousProjectRootEnv = null;
+    this.hadProjectRootEnv = false;
+    this.projectRootEnvCaptured = false;
     this.gitService = null;
 
     // Dispatch

package/src/resources/extensions/gsd/auto.ts

@@ -241,6 +241,29 @@ const s = new AutoSession();
 /** Throttle STATE.md rebuilds — at most once per 30 seconds */
 const STATE_REBUILD_MIN_INTERVAL_MS = 30_000;
 
+function captureProjectRootEnv(projectRoot: string): void {
+  if (!s.projectRootEnvCaptured) {
+    s.hadProjectRootEnv = Object.prototype.hasOwnProperty.call(process.env, "GSD_PROJECT_ROOT");
+    s.previousProjectRootEnv = process.env.GSD_PROJECT_ROOT ?? null;
+    s.projectRootEnvCaptured = true;
+  }
+  process.env.GSD_PROJECT_ROOT = projectRoot;
+}
+
+function restoreProjectRootEnv(): void {
+  if (!s.projectRootEnvCaptured) return;
+
+  if (s.hadProjectRootEnv && s.previousProjectRootEnv !== null) {
+    process.env.GSD_PROJECT_ROOT = s.previousProjectRootEnv;
+  } else {
+    delete process.env.GSD_PROJECT_ROOT;
+  }
+
+  s.previousProjectRootEnv = null;
+  s.hadProjectRootEnv = false;
+  s.projectRootEnvCaptured = false;
+}
+
 export function shouldUseWorktreeIsolation(): boolean {
   const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
   if (prefs?.isolation === "worktree") return true;
@@ -542,6 +565,7 @@ function handleLostSessionLock(
   s.active = false;
   s.paused = false;
   clearUnitTimeout();
+  restoreProjectRootEnv();
   deregisterSigtermHandler();
   clearCmuxSidebar(loadEffectiveGSDPreferences()?.preferences);
   const base = lockBase();
@@ -577,6 +601,7 @@ function cleanupAfterLoopExit(ctx: ExtensionContext): void {
   s.currentUnit = null;
   s.active = false;
   clearUnitTimeout();
+  restoreProjectRootEnv();
 
   // Clear crash lock and release session lock so the next `/gsd next` does
   // not see a stale lock with the current PID and treat it as a "remote"
@@ -846,6 +871,7 @@ export async function stopAuto(
     ctx?.ui.setStatus("gsd-auto", undefined);
     ctx?.ui.setWidget("gsd-progress", undefined);
     ctx?.ui.setFooter(undefined);
+    restoreProjectRootEnv();
 
     // Reset all session state in one call
     s.reset();
@@ -934,6 +960,7 @@ export async function pauseAuto(
 
   s.active = false;
   s.paused = true;
+  restoreProjectRootEnv();
   s.pendingVerificationRetry = null;
   s.verificationRetryCount.clear();
   ctx?.ui.setStatus("gsd-auto", "paused");
@@ -1305,6 +1332,7 @@ export async function startAuto(
     );
     logCmuxEvent(loadEffectiveGSDPreferences()?.preferences, s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", "progress");
 
+    captureProjectRootEnv(s.originalBasePath || s.basePath);
     await autoLoop(ctx, pi, s, buildLoopDeps());
     cleanupAfterLoopExit(ctx);
     return;
@@ -1329,6 +1357,7 @@ export async function startAuto(
   );
   if (!ready) return;
 
+  captureProjectRootEnv(s.originalBasePath || s.basePath);
   try {
     syncCmuxSidebar(loadEffectiveGSDPreferences()?.preferences, await deriveState(s.basePath));
   } catch (err) {
@@ -1569,4 +1598,3 @@ export {
   buildLoopRemediationSteps,
 } from "./auto-recovery.js";
 export { resolveExpectedArtifactPath } from "./auto-artifact-paths.js";
-

package/src/resources/extensions/gsd/init-wizard.ts

@@ -235,6 +235,20 @@ export async function showProjectInit(
   // ── Step 9: Bootstrap .gsd/ ────────────────────────────────────────────────
   bootstrapGsdDirectory(basePath, prefs, signals);
 
+  // Initialize SQLite database so GSD starts in full-capability mode (#3880).
+  // Without this, isDbAvailable() returns false and GSD enters degraded
+  // markdown-only mode until a tool handler happens to call ensureDbOpen().
+  let dbReady = false;
+  try {
+    const { ensureDbOpen } = await import("./bootstrap/dynamic-tools.js");
+    dbReady = await ensureDbOpen(basePath);
+  } catch {
+    // Swallowed — warning surfaced below
+  }
+  if (!dbReady) {
+    ctx.ui.notify("Warning: database initialization failed — GSD will run in degraded mode until the next /gsd invocation.", "warning");
+  }
+
   // Ensure .gitignore
   ensureGitignore(basePath);
   untrackRuntimeFiles(basePath);
@@ -250,6 +264,25 @@ export async function showProjectInit(
     // Non-fatal — codebase map generation failure should never block project init
   }
 
+  // Write initial STATE.md so it exists before the first /gsd invocation.
+  // The explicit /gsd init path (ops.ts) returns without entering showSmartEntry(),
+  // which would otherwise generate STATE.md at guided-flow.ts:1358.
+  let stateReady = false;
+  try {
+    const { deriveState } = await import("./state.js");
+    const { buildStateMarkdown } = await import("./doctor.js");
+    const { saveFile } = await import("./files.js");
+    const { resolveGsdRootFile } = await import("./paths.js");
+    const state = await deriveState(basePath);
+    await saveFile(resolveGsdRootFile(basePath, "STATE"), buildStateMarkdown(state));
+    stateReady = true;
+  } catch {
+    // Swallowed — warning surfaced below
+  }
+  if (!stateReady) {
+    ctx.ui.notify("Warning: initial STATE.md generation failed — it will be created on the next /gsd invocation.", "warning");
+  }
+
   ctx.ui.notify("GSD initialized. Starting your first milestone...", "info");
 
   return { completed: true, bootstrapped: true };
@@ -433,6 +466,7 @@ function bootstrapGsdDirectory(
 
   const gsd = gsdRoot(basePath);
   mkdirSync(join(gsd, "milestones"), { recursive: true });
+  mkdirSync(join(gsd, "runtime"), { recursive: true });
 
   // Write PREFERENCES.md from wizard answers
   const preferencesContent = buildPreferencesFile(prefs);

package/src/resources/extensions/gsd/tests/auto-project-root-env.test.ts

@@ -0,0 +1,29 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const sourcePath = join(import.meta.dirname, "..", "auto.ts");
+const source = readFileSync(sourcePath, "utf-8");
+
+test("auto-mode captures GSD_PROJECT_ROOT before entering the dispatch loop", () => {
+  const captureDeclIdx = source.indexOf("function captureProjectRootEnv(projectRoot: string): void {");
+  assert.ok(captureDeclIdx > -1, "auto.ts should define captureProjectRootEnv()");
+
+  const resumeCallIdx = source.indexOf("captureProjectRootEnv(s.originalBasePath || s.basePath);");
+  assert.ok(resumeCallIdx > -1, "auto.ts should capture GSD_PROJECT_ROOT before resume autoLoop");
+
+  const firstAutoLoopIdx = source.indexOf("await autoLoop(ctx, pi, s, buildLoopDeps());");
+  assert.ok(firstAutoLoopIdx > -1, "auto.ts should invoke autoLoop()");
+  assert.ok(
+    resumeCallIdx < firstAutoLoopIdx,
+    "auto.ts must set GSD_PROJECT_ROOT before the first autoLoop() call",
+  );
+});
+
+test("auto-mode restores GSD_PROJECT_ROOT when execution stops or pauses", () => {
+  assert.match(source, /function restoreProjectRootEnv\(\): void \{/);
+  assert.match(source, /cleanupAfterLoopExit\(ctx: ExtensionContext\): void \{[\s\S]*restoreProjectRootEnv\(\);/);
+  assert.match(source, /export async function pauseAuto\([\s\S]*restoreProjectRootEnv\(\);/);
+  assert.match(source, /\} finally \{[\s\S]*restoreProjectRootEnv\(\);[\s\S]*s\.reset\(\);/);
+});

package/src/resources/extensions/gsd/tests/init-bootstrap-completeness.test.ts

@@ -0,0 +1,121 @@
+/**
+ * GSD Init Wizard — Bootstrap completeness regression tests
+ *
+ * Regression test for #3880 — fresh install never creates gsd.db.
+ *
+ * The init wizard must create all artifacts needed for full-capability
+ * mode: gsd.db (via ensureDbOpen), runtime/ directory, and STATE.md
+ * (via deriveState + buildStateMarkdown). Without these, GSD enters
+ * degraded markdown-only mode on every fresh install.
+ *
+ * These are structural tests that verify the init-wizard.ts source
+ * contains the required calls in the correct order.
+ */
+
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const wizardSrc = readFileSync(
+  join(__dirname, "..", "init-wizard.ts"),
+  "utf-8",
+);
+
+describe("init-wizard bootstrap completeness (#3880)", () => {
+  // ── Gap 1: gsd.db must be created during init ─────────────────────────
+
+  test("bootstrapGsdDirectory is followed by ensureDbOpen", () => {
+    const bootstrapIdx = wizardSrc.indexOf("bootstrapGsdDirectory(basePath");
+    const ensureDbIdx = wizardSrc.indexOf("ensureDbOpen(basePath)");
+    assert.ok(bootstrapIdx > -1, "bootstrapGsdDirectory call should exist");
+    assert.ok(ensureDbIdx > -1, "ensureDbOpen(basePath) call should exist");
+    assert.ok(
+      ensureDbIdx > bootstrapIdx,
+      "ensureDbOpen must appear after bootstrapGsdDirectory so .gsd/ exists first",
+    );
+  });
+
+  test("ensureDbOpen is imported from dynamic-tools", () => {
+    assert.match(
+      wizardSrc,
+      /import.*dynamic-tools/,
+      "init-wizard should import from dynamic-tools for ensureDbOpen",
+    );
+  });
+
+  // ── Gap 2: runtime/ directory must be created during init ──────────────
+
+  test("bootstrapGsdDirectory creates runtime/ directory", () => {
+    // Find the bootstrapGsdDirectory function body
+    const fnStart = wizardSrc.indexOf("function bootstrapGsdDirectory(");
+    assert.ok(fnStart > -1, "bootstrapGsdDirectory function should exist");
+
+    // Find the next function definition to bound the search
+    const fnBody = wizardSrc.slice(fnStart, wizardSrc.indexOf("\nfunction ", fnStart + 1));
+
+    assert.match(
+      fnBody,
+      /mkdirSync\(.*"runtime"/,
+      'bootstrapGsdDirectory should create "runtime" directory',
+    );
+  });
+
+  // ── Gap 3: STATE.md must be written during init ────────────────────────
+
+  test("showProjectInit generates STATE.md after bootstrap", () => {
+    const bootstrapIdx = wizardSrc.indexOf("bootstrapGsdDirectory(basePath");
+    const deriveIdx = wizardSrc.indexOf("deriveState(basePath)");
+    const stateIdx = wizardSrc.indexOf("buildStateMarkdown(state)");
+    const saveIdx = wizardSrc.indexOf('resolveGsdRootFile(basePath, "STATE")');
+
+    assert.ok(deriveIdx > -1, "deriveState call should exist in init-wizard");
+    assert.ok(stateIdx > -1, "buildStateMarkdown call should exist in init-wizard");
+    assert.ok(saveIdx > -1, "resolveGsdRootFile STATE call should exist in init-wizard");
+    assert.ok(
+      deriveIdx > bootstrapIdx,
+      "deriveState must appear after bootstrapGsdDirectory",
+    );
+  });
+
+  // ── Ordering: DB must be open before deriveState ───────────────────────
+
+  test("ensureDbOpen appears before deriveState", () => {
+    const ensureDbIdx = wizardSrc.indexOf("ensureDbOpen(basePath)");
+    const deriveIdx = wizardSrc.indexOf("deriveState(basePath)");
+    assert.ok(ensureDbIdx > -1, "ensureDbOpen should exist");
+    assert.ok(deriveIdx > -1, "deriveState should exist");
+    assert.ok(
+      ensureDbIdx < deriveIdx,
+      "ensureDbOpen must appear before deriveState so DB is ready for state derivation",
+    );
+  });
+
+  // ── Failure visibility: user must be warned on partial bootstrap ───────
+
+  test("ensureDbOpen failure surfaces a warning to the user", () => {
+    assert.match(
+      wizardSrc,
+      /if\s*\(\s*!dbReady\s*\)/,
+      "init-wizard should check dbReady and warn the user on failure",
+    );
+    // The warning must reference degraded mode so the user knows what happened
+    assert.match(
+      wizardSrc,
+      /degraded mode/,
+      "DB failure warning should mention degraded mode",
+    );
+  });
+
+  test("STATE.md failure surfaces a warning to the user", () => {
+    assert.match(
+      wizardSrc,
+      /if\s*\(\s*!stateReady\s*\)/,
+      "init-wizard should check stateReady and warn the user on failure",
+    );
+  });
+});

package/src/resources/extensions/gsd/tests/workflow-mcp.test.ts

@@ -1,7 +1,8 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 
 import {
@@ -70,6 +71,43 @@ test("buildWorkflowMcpServers mirrors explicit launch config", () => {
   });
 });
 
+test("detectWorkflowMcpLaunchConfig resolves the bundled server from GSD_PROJECT_ROOT", () => {
+  const repoRoot = mkdtempSync(join(tmpdir(), "gsd-workflow-root-"));
+  const worktreeRoot = mkdtempSync(join(tmpdir(), "gsd-workflow-worktree-"));
+  const cliPath = join(repoRoot, "packages", "mcp-server", "dist", "cli.js");
+
+  mkdirSync(join(repoRoot, "packages", "mcp-server", "dist"), { recursive: true });
+  writeFileSync(cliPath, "#!/usr/bin/env node\n", "utf-8");
+
+  const launch = detectWorkflowMcpLaunchConfig(worktreeRoot, {
+    GSD_PROJECT_ROOT: repoRoot,
+  });
+
+  assert.deepEqual(launch, {
+    name: "gsd-workflow",
+    command: process.execPath,
+    args: [cliPath],
+    cwd: repoRoot,
+    env: {
+      GSD_PERSIST_WRITE_GATE_STATE: "1",
+      GSD_WORKFLOW_PROJECT_ROOT: repoRoot,
+    },
+  });
+});
+
+test("detectWorkflowMcpLaunchConfig resolves the bundled server relative to the installed GSD package", () => {
+  const launch = detectWorkflowMcpLaunchConfig("/tmp/project", {
+    GSD_BIN_PATH: "/tmp/gsd-loader.js",
+  });
+
+  assert.equal(launch?.command, process.execPath);
+  assert.equal(launch?.cwd, "/tmp/project");
+  assert.equal(launch?.env?.GSD_CLI_PATH, "/tmp/gsd-loader.js");
+  assert.equal(launch?.env?.GSD_WORKFLOW_PROJECT_ROOT, "/tmp/project");
+  assert.equal(typeof launch?.args?.[0], "string");
+  assert.match(launch?.args?.[0] ?? "", /packages[\/\\]mcp-server[\/\\]dist[\/\\]cli\.js$/);
+});
+
 test("usesWorkflowMcpTransport matches local externalCli providers", () => {
   assert.equal(usesWorkflowMcpTransport("externalCli", "local://claude-code"), true);
   assert.equal(usesWorkflowMcpTransport("externalCli", "https://api.example.com"), false);

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

@@ -1,6 +1,7 @@
 import { execSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 
 export interface WorkflowMcpLaunchConfig {
   name: string;
@@ -66,6 +67,21 @@ function lookupCommand(command: string, platform: NodeJS.Platform = process.plat
   }
 }
 
+function getBundledWorkflowMcpCliPath(env: NodeJS.ProcessEnv): string | null {
+  if (!env.GSD_BIN_PATH?.trim() && !env.GSD_CLI_PATH?.trim()) return null;
+
+  const candidates = [
+    resolve(fileURLToPath(new URL("../../../../packages/mcp-server/dist/cli.js", import.meta.url))),
+    resolve(fileURLToPath(new URL("../../../../../packages/mcp-server/dist/cli.js", import.meta.url))),
+  ];
+
+  for (const bundledCli of candidates) {
+    if (existsSync(bundledCli)) return bundledCli;
+  }
+
+  return null;
+}
+
 export function detectWorkflowMcpLaunchConfig(
   projectRoot = process.cwd(),
   env: NodeJS.ProcessEnv = process.env,
@@ -75,16 +91,19 @@ export function detectWorkflowMcpLaunchConfig(
   const explicitArgs = parseJsonEnv<unknown>(env, "GSD_WORKFLOW_MCP_ARGS");
   const explicitEnv = parseJsonEnv<Record<string, string>>(env, "GSD_WORKFLOW_MCP_ENV");
   const explicitCwd = env.GSD_WORKFLOW_MCP_CWD?.trim();
+  const gsdCliPath = env.GSD_CLI_PATH?.trim() || env.GSD_BIN_PATH?.trim();
   const workflowProjectRoot =
     explicitEnv?.GSD_WORKFLOW_PROJECT_ROOT?.trim() ||
     env.GSD_WORKFLOW_PROJECT_ROOT?.trim() ||
+    env.GSD_PROJECT_ROOT?.trim() ||
     explicitCwd ||
     projectRoot;
+  const resolvedWorkflowProjectRoot = resolve(workflowProjectRoot);
 
   if (explicitCommand) {
     const launchEnv = {
       ...(explicitEnv ?? {}),
-      ...(env.GSD_CLI_PATH ? { GSD_CLI_PATH: env.GSD_CLI_PATH } : {}),
+      ...(gsdCliPath ? { GSD_CLI_PATH: gsdCliPath } : {}),
       GSD_PERSIST_WRITE_GATE_STATE: "1",
       GSD_WORKFLOW_PROJECT_ROOT: resolve(workflowProjectRoot),
     };
@@ -97,17 +116,32 @@ export function detectWorkflowMcpLaunchConfig(
     };
   }
 
-  const distCli = resolve(projectRoot, "packages", "mcp-server", "dist", "cli.js");
+  const distCli = resolve(resolvedWorkflowProjectRoot, "packages", "mcp-server", "dist", "cli.js");
   if (existsSync(distCli)) {
     return {
       name,
       command: process.execPath,
       args: [distCli],
-      cwd: projectRoot,
+      cwd: resolvedWorkflowProjectRoot,
+      env: {
+        ...(gsdCliPath ? { GSD_CLI_PATH: gsdCliPath } : {}),
+        GSD_PERSIST_WRITE_GATE_STATE: "1",
+        GSD_WORKFLOW_PROJECT_ROOT: resolvedWorkflowProjectRoot,
+      },
+    };
+  }
+
+  const bundledCli = getBundledWorkflowMcpCliPath(env);
+  if (bundledCli) {
+    return {
+      name,
+      command: process.execPath,
+      args: [bundledCli],
+      cwd: resolvedWorkflowProjectRoot,
       env: {
-        ...(env.GSD_CLI_PATH ? { GSD_CLI_PATH: env.GSD_CLI_PATH } : {}),
+        ...(gsdCliPath ? { GSD_CLI_PATH: gsdCliPath } : {}),
         GSD_PERSIST_WRITE_GATE_STATE: "1",
-        GSD_WORKFLOW_PROJECT_ROOT: resolve(projectRoot),
+        GSD_WORKFLOW_PROJECT_ROOT: resolvedWorkflowProjectRoot,
       },
     };
   }
@@ -118,9 +152,9 @@ export function detectWorkflowMcpLaunchConfig(
       name,
       command: binPath,
       env: {
-        ...(env.GSD_CLI_PATH ? { GSD_CLI_PATH: env.GSD_CLI_PATH } : {}),
+        ...(gsdCliPath ? { GSD_CLI_PATH: gsdCliPath } : {}),
         GSD_PERSIST_WRITE_GATE_STATE: "1",
-        GSD_WORKFLOW_PROJECT_ROOT: resolve(projectRoot),
+        GSD_WORKFLOW_PROJECT_ROOT: resolvedWorkflowProjectRoot,
       },
     };
   }