gsd-pi 2.77.0-dev.538325aea → 2.77.0-dev.58d3d4d6c

package/packages/mcp-server/package.json

@@ -3,6 +3,11 @@
   "version": "2.77.0",
   "description": "MCP server exposing GSD orchestration tools for Claude Code, Cursor, and other MCP clients",
   "license": "MIT",
+  "gsd": {
+    "linkable": true,
+    "scope": "@gsd-build",
+    "name": "mcp-server"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/gsd-build/gsd-2.git",

package/packages/mcp-server/src/env-writer.test.ts

@@ -3,7 +3,7 @@
 
 import { describe, it, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync, realpathSync, symlinkSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
@@ -14,6 +14,7 @@ import {
   applySecrets,
   isSafeEnvVarKey,
   isSupportedDeploymentEnvironment,
+  resolveProjectEnvFilePath,
   shellEscapeSingle,
 } from './env-writer.js';
 
@@ -181,6 +182,83 @@ describe('writeEnvKey', () => {
       rmSync(tmp, { recursive: true, force: true });
     }
   });
+
+  it('does not follow symlinked env files when writing', async () => {
+    const tmp = makeTempDir('write');
+    const outside = makeTempDir('write-outside');
+    try {
+      const outsideEnv = join(outside, '.env');
+      writeFileSync(outsideEnv, 'SECRET=outside\n');
+      symlinkSync(outsideEnv, join(tmp, '.env'));
+
+      await assert.rejects(
+        () => writeEnvKey(join(tmp, '.env'), 'SECRET', 'inside'),
+        /ELOOP|symbolic link|symlink/i,
+      );
+      assert.equal(readFileSync(outsideEnv, 'utf8'), 'SECRET=outside\n');
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+      rmSync(outside, { recursive: true, force: true });
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveProjectEnvFilePath
+// ---------------------------------------------------------------------------
+
+describe('resolveProjectEnvFilePath', () => {
+  it('allows .env under the project root', () => {
+    const tmp = makeTempDir('env-path');
+    try {
+      assert.equal(resolveProjectEnvFilePath(tmp, '.env'), join(realpathSync.native(tmp), '.env'));
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it('rejects envFilePath outside the project root', () => {
+    const tmp = makeTempDir('env-path');
+    try {
+      assert.throws(
+        () => resolveProjectEnvFilePath(tmp, '../outside.env'),
+        /inside the project directory/,
+      );
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it('rejects symlinked parent directories that escape the project root', () => {
+    const tmp = makeTempDir('env-path');
+    const outside = makeTempDir('env-path-outside');
+    try {
+      symlinkSync(outside, join(tmp, 'linked-outside'), 'dir');
+      assert.throws(
+        () => resolveProjectEnvFilePath(tmp, 'linked-outside/.env'),
+        /inside the project directory/,
+      );
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+      rmSync(outside, { recursive: true, force: true });
+    }
+  });
+
+  it('rejects existing env files that are symlinks outside the project root', () => {
+    const tmp = makeTempDir('env-path');
+    const outside = makeTempDir('env-path-outside');
+    try {
+      writeFileSync(join(outside, '.env'), 'SECRET=outside\n');
+      symlinkSync(join(outside, '.env'), join(tmp, '.env'));
+      assert.throws(
+        () => resolveProjectEnvFilePath(tmp, '.env'),
+        /inside the project directory/,
+      );
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+      rmSync(outside, { recursive: true, force: true });
+    }
+  });
 });
 
 // ---------------------------------------------------------------------------

package/packages/mcp-server/src/env-writer.ts

@@ -5,9 +5,9 @@
 // destinations, and checking existing keys. Used by secure_env_collect
 // MCP tool. No TUI dependencies — pure filesystem + process.env operations.
 
-import { readFile, writeFile } from "node:fs/promises";
-import { existsSync, statSync } from "node:fs";
-import { resolve } from "node:path";
+import { open, readFile, rename, rm } from "node:fs/promises";
+import { constants, existsSync, lstatSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 
 // ---------------------------------------------------------------------------
 // checkExistingEnvKeys
@@ -71,10 +71,19 @@ export async function writeEnvKey(filePath: string, key: string, value: string):
   if (typeof value !== "string") {
     throw new TypeError(`writeEnvKey expects a string value for key "${key}", got ${typeof value}`);
   }
+  assertWritableEnvFileTarget(filePath);
   let content = "";
   try {
-    content = await readFile(filePath, "utf8");
-  } catch {
+    const handle = await open(filePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+      content = await handle.readFile("utf8");
+    } finally {
+      await handle.close();
+    }
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw err;
+    }
     content = "";
   }
   const escaped = value.replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/\r/g, "");
@@ -86,7 +95,42 @@ export async function writeEnvKey(filePath: string, key: string, value: string):
     if (content.length > 0 && !content.endsWith("\n")) content += "\n";
     content += `${line}\n`;
   }
-  await writeFile(filePath, content, "utf8");
+  const tempPath = join(
+    dirname(filePath),
+    `.${basename(filePath)}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`,
+  );
+  let handle: Awaited<ReturnType<typeof open>> | undefined;
+  try {
+    handle = await open(tempPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+    await handle.writeFile(content, "utf8");
+    await handle.close();
+    handle = undefined;
+    assertWritableEnvFileTarget(filePath);
+    await rename(tempPath, filePath);
+  } catch (err) {
+    if (handle) {
+      try {
+        await handle.close();
+      } catch {
+        // Best-effort cleanup.
+      }
+    }
+    await rm(tempPath, { force: true }).catch(() => undefined);
+    throw err;
+  }
+}
+
+function assertWritableEnvFileTarget(filePath: string): void {
+  try {
+    if (lstatSync(filePath).isSymbolicLink()) {
+      throw new Error("Refusing to write symlinked env file");
+    }
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      return;
+    }
+    throw err;
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -101,6 +145,32 @@ export function isSupportedDeploymentEnvironment(env: string): boolean {
   return env === "development" || env === "preview" || env === "production";
 }
 
+function isWithinProjectRoot(projectRoot: string, candidatePath: string): boolean {
+  const rel = relative(projectRoot, candidatePath);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+export function resolveProjectEnvFilePath(projectDir: string, envFilePath = ".env"): string {
+  const projectRoot = realpathSync.native(resolve(projectDir));
+  const candidate = resolve(projectRoot, envFilePath);
+  if (!isWithinProjectRoot(projectRoot, candidate)) {
+    throw new Error("envFilePath must resolve inside the project directory");
+  }
+  if (existsSync(candidate)) {
+    const targetRealPath = realpathSync.native(candidate);
+    if (isWithinProjectRoot(projectRoot, targetRealPath)) {
+      return candidate;
+    }
+    throw new Error("envFilePath must resolve inside the project directory");
+  }
+  const candidateParent = dirname(candidate);
+  const parentRealPath = realpathSync.native(candidateParent);
+  if (isWithinProjectRoot(projectRoot, parentRealPath)) {
+    return candidate;
+  }
+  throw new Error("envFilePath must resolve inside the project directory");
+}
+
 // ---------------------------------------------------------------------------
 // Shell helpers (for vercel/convex CLI)
 // ---------------------------------------------------------------------------

package/packages/mcp-server/src/readers/readers.test.ts

@@ -503,7 +503,11 @@ describe('runDoctorLite', () => {
     const empty = tmpProject();
     const result = runDoctorLite(empty);
     assert.equal(result.ok, true);
-    assert.equal(result.issues[0].code, 'no_gsd_directory');
+    assert.ok(
+      result.issues.some(
+        (issue) => issue.code === 'no_gsd_directory' || issue.code === 'missing_project_md',
+      ),
+    );
     rmSync(empty, { recursive: true, force: true });
   });
 });

package/packages/mcp-server/src/server.ts

@@ -13,6 +13,7 @@
 
 import { readFile, readdir, stat } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
+import { spawn } from 'node:child_process';
 import { z } from 'zod';
 import type { SessionManager } from './session-manager.js';
 import { isRemoteConfigured, tryRemoteQuestions } from './remote-questions.js';
@@ -25,7 +26,7 @@ import { buildGraph, writeGraph, writeSnapshot, graphStatus, graphQuery, graphDi
 import { resolveGsdRoot } from './readers/paths.js';
 import { runDoctorLite } from './readers/doctor-lite.js';
 import { registerWorkflowTools, validateProjectDir } from './workflow-tools.js';
-import { applySecrets, checkExistingEnvKeys, detectDestination } from './env-writer.js';
+import { applySecrets, checkExistingEnvKeys, detectDestination, resolveProjectEnvFilePath } from './env-writer.js';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -38,6 +39,31 @@ const SERVER_VERSION = '2.53.0';
 /** User-interaction timeout — generous but bounded so elicitation can't hang indefinitely (#4586). */
 const ELICIT_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
 
+/**
+ * Default child-process runner used by secure_env_collect to push secrets
+ * into `vercel env add` / `npx convex env set`. Previously `applySecrets`
+ * was called without an `execFn`, so vercel/convex destinations silently
+ * dropped every collected key. This restores the write path.
+ */
+function defaultExecFn(
+  cmd: string,
+  args: string[],
+): Promise<{ code: number; stderr: string }> {
+  return new Promise((res) => {
+    // stdin: ignore — avoids hanging if the child ever prompts interactively.
+    // stdout: ignore — consumer only cares about stderr + exit code, and an
+    //   un-drained pipe deadlocks once the kernel buffer (~64KB) fills.
+    // stderr: pipe — captured below for error surfacing.
+    const child = spawn(cmd, args, { stdio: ['ignore', 'ignore', 'pipe'] });
+    let stderr = '';
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString('utf8');
+    });
+    child.on('error', (err) => res({ code: 1, stderr: err.message }));
+    child.on('close', (code) => res({ code: code ?? 1, stderr }));
+  });
+}
+
 /**
  * Race a promise against a timeout. Rejects with a typed error on timeout so
  * callers can return a specific MCP error response rather than hanging.
@@ -603,22 +629,10 @@ export async function createMcpServer(sessionManager: SessionManager): Promise<{
         const validationError = validateAskUserQuestionsPayload(questions);
         if (validationError) return errorContent(validationError);
 
-        // Prefer MCP elicitation when the client supports it (desktop/test stdio).
-        // If elicitation is unavailable (e.g. Claude Code headless), fall back
-        // to remote questions when configured.
-        const remoteConfigured = isRemoteConfigured();
-        try {
-          const elicitation = await withElicitTimeout(
-            server.server.elicitInput(buildAskUserQuestionsElicitRequest(questions)),
-            'ask_user_questions',
-          );
-          if (elicitation.action !== 'accept' || !elicitation.content) {
-            return textContent('ask_user_questions was cancelled before receiving a response');
-          }
-
-          return textContent(formatAskUserQuestionsElicitResult(questions, elicitation));
-        } catch (elicitationError) {
-          if (!remoteConfigured) throw elicitationError;
+        // Delegate to remote-questions manager when a remote channel is configured
+        // (Discord, Slack, Telegram). This path is the only one reachable for
+        // Claude Code-under-gsd sessions, which have no local TUI.
+        if (isRemoteConfigured()) {
           const remoteResult = await tryRemoteQuestions(questions, extra?.signal);
           if (remoteResult) {
             const details = remoteResult.details as Record<string, unknown> | undefined;
@@ -628,8 +642,19 @@ export async function createMcpServer(sessionManager: SessionManager): Promise<{
             }
             return textContent(remoteResult.content[0]?.text ?? '');
           }
-          throw elicitationError;
+          // resolveRemoteConfig() returned null between isRemoteConfigured() and
+          // tryRemoteQuestions() (e.g. env var was cleared) — fall through to local.
         }
+
+        const elicitation = await withElicitTimeout(
+          server.server.elicitInput(buildAskUserQuestionsElicitRequest(questions)),
+          'ask_user_questions',
+        );
+        if (elicitation.action !== 'accept' || !elicitation.content) {
+          return textContent('ask_user_questions was cancelled before receiving a response');
+        }
+
+        return textContent(formatAskUserQuestionsElicitResult(questions, elicitation));
       } catch (err) {
         return errorContent(err instanceof Error ? err.message : String(err));
       }
@@ -664,7 +689,7 @@ export async function createMcpServer(sessionManager: SessionManager): Promise<{
 
       try {
         const resolvedProjectDir = validateProjectDir(projectDir);
-        const resolvedEnvPath = resolve(resolvedProjectDir, envFilePath ?? '.env');
+        const resolvedEnvPath = resolveProjectEnvFilePath(resolvedProjectDir, envFilePath ?? '.env');
 
         // (1) Check which keys already exist
         const allKeyNames = keys.map((k) => k.key);
@@ -737,6 +762,7 @@ export async function createMcpServer(sessionManager: SessionManager): Promise<{
         const { applied, errors } = await applySecrets(provided, resolvedDestination, {
           envFilePath: resolvedEnvPath,
           environment,
+          execFn: defaultExecFn,
         });
 
         // (7) Build result — NEVER include secret values

package/packages/mcp-server/src/workflow-tools.test.ts

@@ -712,6 +712,50 @@ export const executeTaskComplete = async (params, projectDir) => {
     }
   });
 
+  it("gsd_plan_milestone surfaces the full-vs-sketch conditional requirement in the tool schema", () => {
+    // Regression: the four heavy slice fields (successCriteria, proofLevel,
+    // integrationClosure, observabilityImpact) are Zod-optional so sketch
+    // slices can omit them, but they are required for every other slice. That
+    // conditional requirement is invisible in the JSON Schema `required`
+    // array — agents discovered it only by hitting a -32602 error mid-call.
+    // Each heavy field's `.describe()` now states the constraint; this test
+    // pins that so future edits can't silently strip it.
+    const server = makeMockServer();
+    registerWorkflowTools(server as any);
+    const milestoneTool = server.tools.find((t) => t.name === "gsd_plan_milestone");
+    assert.ok(milestoneTool, "milestone planning tool should be registered");
+
+    const slicesParam: any = milestoneTool!.params.slices;
+    assert.ok(slicesParam, "slices parameter must be present");
+    const element: any = slicesParam._def?.element;
+    assert.ok(element, "expected z.array element schema");
+
+    // Top-level slice description should state the conditional requirement.
+    const sliceDescription: string | undefined = element.description;
+    assert.ok(
+      sliceDescription && /isSketch/i.test(sliceDescription),
+      `slice schema should describe the isSketch conditional; got: ${sliceDescription}`,
+    );
+    for (const field of ["successCriteria", "proofLevel", "integrationClosure", "observabilityImpact"]) {
+      assert.ok(
+        sliceDescription!.includes(field),
+        `slice schema description should name ${field} as part of the full-slice contract`,
+      );
+    }
+
+    // Each heavy field should carry a field-level description that marks it
+    // REQUIRED unless isSketch=true.
+    const shape: Record<string, any> = element._def.shape;
+    assert.ok(shape, "expected to introspect slice object shape");
+    for (const field of ["successCriteria", "proofLevel", "integrationClosure", "observabilityImpact"] as const) {
+      const fieldDescription: string | undefined = shape[field]?.description;
+      assert.ok(
+        fieldDescription && /REQUIRED\s+unless\s+isSketch/i.test(fieldDescription),
+        `${field} description must state "REQUIRED unless isSketch=true"; got: ${fieldDescription}`,
+      );
+    }
+  });
+
   it("gsd_plan_milestone requires sketchScope when isSketch=true and skips heavy fields", async () => {
     const base = makeTmpBase();
     try {

package/packages/mcp-server/src/workflow-tools.ts

@@ -875,6 +875,17 @@ const nonEmptyStringArray = (field: string) =>
 // empty/whitespace fields at parse time. Without this, MCP callers pass "" for
 // the heavy planning fields, Zod accepts it, and the executor rejects one
 // field per call — forcing the agent into a retry loop to discover every gap.
+//
+// #4759 follow-up: the four heavy fields are Zod-optional because sketch
+// slices (isSketch=true) legitimately omit them, but they are REQUIRED for
+// every other slice. The conditional requirement is invisible in the JSON
+// Schema `required` array, so callers can only discover it from the
+// descriptions or by hitting the runtime superRefine below. The `.describe()`
+// calls below make that contract unmistakable in the tool schema sent to
+// agents; the superRefine enforces it at parse time.
+const HEAVY_FIELD_DESCRIBE = (field: string) =>
+  `${field} for this slice. REQUIRED unless isSketch=true (sketch slices defer this to refine-slice).`;
+
 const planMilestoneSliceSchema = z.object({
   sliceId: nonEmptyString("sliceId"),
   title: nonEmptyString("title"),
@@ -883,14 +894,16 @@ const planMilestoneSliceSchema = z.object({
   demo: nonEmptyString("demo"),
   goal: nonEmptyString("goal"),
   // ADR-011: heavy planning fields are optional for sketch slices; required for full slices.
-  successCriteria: z.string().optional(),
-  proofLevel: z.string().optional(),
-  integrationClosure: z.string().optional(),
-  observabilityImpact: z.string().optional(),
+  successCriteria: z.string().optional().describe(HEAVY_FIELD_DESCRIBE("successCriteria")),
+  proofLevel: z.string().optional().describe(HEAVY_FIELD_DESCRIBE("proofLevel")),
+  integrationClosure: z.string().optional().describe(HEAVY_FIELD_DESCRIBE("integrationClosure")),
+  observabilityImpact: z.string().optional().describe(HEAVY_FIELD_DESCRIBE("observabilityImpact")),
   // ADR-011 sketch-then-refine fields.
-  isSketch: z.boolean().optional().describe("ADR-011: true marks this slice as a sketch awaiting refine-slice expansion"),
+  isSketch: z.boolean().optional().describe("ADR-011: true marks this slice as a sketch awaiting refine-slice expansion. When true, successCriteria/proofLevel/integrationClosure/observabilityImpact may be omitted and sketchScope becomes required."),
   sketchScope: z.string().optional().describe("ADR-011: 2-3 sentence scope boundary, required when isSketch=true"),
-}).superRefine((slice, ctx) => {
+}).describe(
+  "Planned slice. For full slices (isSketch omitted or false): successCriteria, proofLevel, integrationClosure, and observabilityImpact are all required. For sketch slices (isSketch=true): those four fields may be omitted, but sketchScope is required.",
+).superRefine((slice, ctx) => {
   if (slice.isSketch === true) {
     if (typeof slice.sketchScope !== "string" || slice.sketchScope.trim().length === 0) {
       ctx.addIssue({