gsd-pi 2.77.0-dev.eaa4973bc → 2.78.0-dev.aeeb2ca00

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

@@ -387,6 +387,126 @@ export function formatAskUserQuestionsElicitResult(
   return JSON.stringify({ answers });
 }
 
+// ---------------------------------------------------------------------------
+// secure_env_collect handler (extracted so tests can drive it directly)
+// ---------------------------------------------------------------------------
+
+export type ElicitInputFn = (params: {
+  message: string;
+  requestedSchema: { type: 'object'; properties: Record<string, unknown>; required: string[] };
+}) => Promise<{ action: 'accept' | 'cancel' | 'decline'; content?: Record<string, unknown> }>;
+
+type ToolContent =
+  | { content: Array<{ type: 'text'; text: string }> }
+  | { isError: true; content: Array<{ type: 'text'; text: string }> };
+
+export async function secureEnvCollectHandler(
+  args: Record<string, unknown>,
+  elicitInput: ElicitInputFn,
+): Promise<ToolContent> {
+  const { projectDir, keys, destination, envFilePath, environment } = args as {
+    projectDir: string;
+    keys: Array<{ key: string; hint?: string; guidance?: string[] }>;
+    destination?: 'dotenv' | 'vercel' | 'convex';
+    envFilePath?: string;
+    environment?: 'development' | 'preview' | 'production';
+  };
+
+  try {
+    const resolvedProjectDir = validateProjectDir(projectDir);
+    const resolvedEnvPath = resolveProjectEnvFilePath(resolvedProjectDir, envFilePath ?? '.env');
+
+    // (1) Check which keys already exist
+    const allKeyNames = keys.map((k) => k.key);
+    const existingKeys = await checkExistingEnvKeys(allKeyNames, resolvedEnvPath);
+    const existingSet = new Set(existingKeys);
+    const pendingKeys = keys.filter((k) => !existingSet.has(k.key));
+
+    // If all keys already exist, return immediately
+    if (pendingKeys.length === 0) {
+      const lines = existingKeys.map((k) => `• ${k}: already set`);
+      return textContent(`All ${existingKeys.length} key(s) already set.\n${lines.join('\n')}`);
+    }
+
+    // (2) Build elicitation form — one string field per pending key
+    const properties: Record<string, Record<string, unknown>> = {};
+    const required: string[] = [];
+
+    for (const item of pendingKeys) {
+      const descParts: string[] = [];
+      if (item.hint) descParts.push(`Format: ${item.hint}`);
+      if (item.guidance && item.guidance.length > 0) {
+        descParts.push('How to get this:');
+        item.guidance.forEach((step, i) => descParts.push(`${i + 1}. ${step}`));
+      }
+      descParts.push('Leave empty to skip.');
+
+      properties[item.key] = {
+        type: 'string',
+        title: item.key,
+        description: descParts.join('\n'),
+      };
+      // Don't mark as required — empty string = skip
+    }
+
+    // (3) Elicit input from the MCP client
+    const elicitation = await withElicitTimeout(
+      elicitInput({
+        message: `Enter values for ${pendingKeys.length} environment variable(s). Values are written directly to the project and never shown to the AI.`,
+        requestedSchema: {
+          type: 'object',
+          properties,
+          required,
+        },
+      }),
+      'secure_env_collect',
+    );
+
+    if (elicitation.action !== 'accept' || !elicitation.content) {
+      return textContent('secure_env_collect was cancelled by user.');
+    }
+
+    // (4) Separate provided vs skipped from form response
+    const provided: Array<{ key: string; value: string }> = [];
+    const skipped: string[] = [];
+
+    for (const item of pendingKeys) {
+      const raw = elicitation.content[item.key];
+      const value = typeof raw === 'string' ? raw.trim() : '';
+      if (value.length > 0) {
+        provided.push({ key: item.key, value });
+      } else {
+        skipped.push(item.key);
+      }
+    }
+
+    // (5) Auto-detect destination if not specified
+    const resolvedDestination = destination ?? detectDestination(resolvedProjectDir);
+
+    // (6) Write secrets to destination
+    const { applied, errors } = await applySecrets(provided, resolvedDestination, {
+      envFilePath: resolvedEnvPath,
+      environment,
+      execFn: defaultExecFn,
+    });
+
+    // (7) Build result — NEVER include secret values
+    const lines: string[] = [
+      `destination: ${resolvedDestination}${!destination ? ' (auto-detected)' : ''}${environment ? ` (${environment})` : ''}`,
+    ];
+    for (const k of applied) lines.push(`✓ ${k}: applied`);
+    for (const k of skipped) lines.push(`• ${k}: skipped`);
+    for (const k of existingKeys) lines.push(`• ${k}: already set`);
+    for (const e of errors) lines.push(`✗ ${e}`);
+
+    return errors.length > 0 && applied.length === 0
+      ? errorContent(lines.join('\n'))
+      : textContent(lines.join('\n'));
+  } catch (err) {
+    return errorContent(err instanceof Error ? err.message : String(err));
+  }
+}
+
 // ---------------------------------------------------------------------------
 // createMcpServer
 // ---------------------------------------------------------------------------
@@ -397,12 +517,17 @@ export function formatAskUserQuestionsElicitResult(
  * Returns the McpServer instance — call `connect(transport)` to start serving.
  * Uses dynamic imports for the MCP SDK to avoid TS subpath resolution issues.
  */
-export async function createMcpServer(sessionManager: SessionManager): Promise<{
+export async function createMcpServer(
+  sessionManager: SessionManager,
+): Promise<{
   server: McpServerInstance;
 }> {
   // Dynamic import — same workaround as src/mcp-server.ts
   const mcpMod = await import(`${MCP_PKG}/server/mcp.js`);
-  const McpServer = mcpMod.McpServer;
+  const McpServer = mcpMod.McpServer as new (
+    info: { name: string; version: string },
+    opts: { capabilities: Record<string, unknown> },
+  ) => McpServerInstance;
 
   const server: McpServerInstance = new McpServer(
     { name: SERVER_NAME, version: SERVER_VERSION },
@@ -678,109 +803,10 @@ export async function createMcpServer(sessionManager: SessionManager): Promise<{
       envFilePath: z.string().optional().describe('Path to .env file (dotenv only). Defaults to .env in projectDir.'),
       environment: z.enum(['development', 'preview', 'production']).optional().describe('Target environment (vercel/convex only)'),
     },
-    async (args: Record<string, unknown>) => {
-      const { projectDir, keys, destination, envFilePath, environment } = args as {
-        projectDir: string;
-        keys: Array<{ key: string; hint?: string; guidance?: string[] }>;
-        destination?: 'dotenv' | 'vercel' | 'convex';
-        envFilePath?: string;
-        environment?: 'development' | 'preview' | 'production';
-      };
-
-      try {
-        const resolvedProjectDir = validateProjectDir(projectDir);
-        const resolvedEnvPath = resolveProjectEnvFilePath(resolvedProjectDir, envFilePath ?? '.env');
-
-        // (1) Check which keys already exist
-        const allKeyNames = keys.map((k) => k.key);
-        const existingKeys = await checkExistingEnvKeys(allKeyNames, resolvedEnvPath);
-        const existingSet = new Set(existingKeys);
-        const pendingKeys = keys.filter((k) => !existingSet.has(k.key));
-
-        // If all keys already exist, return immediately
-        if (pendingKeys.length === 0) {
-          const lines = existingKeys.map((k) => `• ${k}: already set`);
-          return textContent(`All ${existingKeys.length} key(s) already set.\n${lines.join('\n')}`);
-        }
-
-        // (2) Build elicitation form — one string field per pending key
-        const properties: Record<string, Record<string, unknown>> = {};
-        const required: string[] = [];
-
-        for (const item of pendingKeys) {
-          const descParts: string[] = [];
-          if (item.hint) descParts.push(`Format: ${item.hint}`);
-          if (item.guidance && item.guidance.length > 0) {
-            descParts.push('How to get this:');
-            item.guidance.forEach((step, i) => descParts.push(`${i + 1}. ${step}`));
-          }
-          descParts.push('Leave empty to skip.');
-
-          properties[item.key] = {
-            type: 'string',
-            title: item.key,
-            description: descParts.join('\n'),
-          };
-          // Don't mark as required — empty string = skip
-        }
-
-        // (3) Elicit input from the MCP client
-        const elicitation = await withElicitTimeout(
-          server.server.elicitInput({
-            message: `Enter values for ${pendingKeys.length} environment variable(s). Values are written directly to the project and never shown to the AI.`,
-            requestedSchema: {
-              type: 'object',
-              properties,
-              required,
-            },
-          }),
-          'secure_env_collect',
-        );
-
-        if (elicitation.action !== 'accept' || !elicitation.content) {
-          return textContent('secure_env_collect was cancelled by user.');
-        }
-
-        // (4) Separate provided vs skipped from form response
-        const provided: Array<{ key: string; value: string }> = [];
-        const skipped: string[] = [];
-
-        for (const item of pendingKeys) {
-          const raw = elicitation.content[item.key];
-          const value = typeof raw === 'string' ? raw.trim() : '';
-          if (value.length > 0) {
-            provided.push({ key: item.key, value });
-          } else {
-            skipped.push(item.key);
-          }
-        }
-
-        // (5) Auto-detect destination if not specified
-        const resolvedDestination = destination ?? detectDestination(resolvedProjectDir);
-
-        // (6) Write secrets to destination
-        const { applied, errors } = await applySecrets(provided, resolvedDestination, {
-          envFilePath: resolvedEnvPath,
-          environment,
-          execFn: defaultExecFn,
-        });
-
-        // (7) Build result — NEVER include secret values
-        const lines: string[] = [
-          `destination: ${resolvedDestination}${!destination ? ' (auto-detected)' : ''}${environment ? ` (${environment})` : ''}`,
-        ];
-        for (const k of applied) lines.push(`✓ ${k}: applied`);
-        for (const k of skipped) lines.push(`• ${k}: skipped`);
-        for (const k of existingKeys) lines.push(`• ${k}: already set`);
-        for (const e of errors) lines.push(`✗ ${e}`);
-
-        return errors.length > 0 && applied.length === 0
-          ? errorContent(lines.join('\n'))
-          : textContent(lines.join('\n'));
-      } catch (err) {
-        return errorContent(err instanceof Error ? err.message : String(err));
-      }
-    },
+    async (args: Record<string, unknown>) =>
+      secureEnvCollectHandler(args, (params) =>
+        server.server.elicitInput(params as ElicitRequestFormParams),
+      ),
   );
 
   // =======================================================================

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

@@ -712,6 +712,91 @@ export const executeTaskComplete = async (params, projectDir) => {
     }
   });
 
+  it("gsd_plan_milestone rejects a full slice with missing heavy fields via a behavioral round-trip", async () => {
+    // Behavioral guard for the full-vs-sketch conditional. The original
+    // regression (invisible "required unless isSketch" requirement) is
+    // surfaced to users through two distinct runtime channels:
+    //   1. A parse-time rejection when the tool is called with empty heavy
+    //      fields on a non-sketch slice (no isSketch=true).
+    //   2. An acceptance when isSketch=true + sketchScope is supplied and
+    //      heavy fields are omitted.
+    // Both arms are exercised below against the live handler — any schema
+    // refactor that preserves the user-observable contract (rejection +
+    // acceptance) passes, and any refactor that breaks the contract
+    // fails, regardless of whether internal `.describe()` prose changes.
+    const base = makeTmpBase();
+    try {
+      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");
+
+      // Arm 1: full slice (isSketch omitted) with the heavy fields missing
+      // must reject and name ALL four fields so the agent can self-correct.
+      let fullError: unknown;
+      try {
+        await milestoneTool!.handler({
+          projectDir: base,
+          milestoneId: "M001",
+          title: "Full slice path",
+          vision: "Behavioral test for isSketch conditional.",
+          slices: [
+            {
+              sliceId: "S01",
+              title: "Heavy slice",
+              risk: "medium",
+              depends: [],
+              demo: "Demo.",
+              goal: "Goal.",
+              // heavy fields intentionally omitted
+            },
+          ],
+        });
+      } catch (err) {
+        fullError = err;
+      }
+      assert.ok(fullError, "a non-sketch slice without heavy fields must reject");
+      const fullMsg = fullError instanceof Error ? fullError.message : String(fullError);
+      for (const field of ["successCriteria", "proofLevel", "integrationClosure", "observabilityImpact"]) {
+        assert.ok(
+          fullMsg.includes(field),
+          `rejection must name ${field} so agents can recover without a second round-trip; got: ${fullMsg}`,
+        );
+      }
+
+      // Arm 2: sketch slice (isSketch=true + sketchScope) with heavy fields
+      // omitted must be accepted — proving the conditional is live. Assert
+      // success directly rather than just checking a thrown message omits
+      // the heavy-field names: a generic failure would otherwise silently
+      // pass this arm.
+      const sketchResult = await milestoneTool!.handler({
+        projectDir: base,
+        milestoneId: "M002",
+        title: "Sketch slice path",
+        vision: "Behavioral test for isSketch conditional.",
+        slices: [
+          {
+            sliceId: "S01",
+            title: "Sketch slice",
+            risk: "medium",
+            depends: [],
+            demo: "Demo.",
+            goal: "Goal.",
+            isSketch: true,
+            sketchScope: "Two-sentence scope. Boundary defined.",
+          },
+        ],
+      });
+      assert.match(
+        (sketchResult as any).content[0].text as string,
+        /Planned milestone M002/,
+        "sketch slice with isSketch=true must be accepted by the handler",
+      );
+    } finally {
+      cleanup(base);
+    }
+  });
+
   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({