gsd-pi 2.70.1 → 2.71.0-dev.06b86c6

package/packages/mcp-server/src/secure-env-collect.test.ts

@@ -0,0 +1,265 @@
+// @gsd-build/mcp-server — Tests for secure_env_collect MCP tool
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+//
+// Tests the secure_env_collect tool registered in createMcpServer.
+// Uses a mock MCP server to intercept tool registration and elicitInput calls.
+
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { createMcpServer } from './server.js';
+import { SessionManager } from './session-manager.js';
+
+// ---------------------------------------------------------------------------
+// Mock infrastructure
+// ---------------------------------------------------------------------------
+
+/**
+ * We intercept McpServer construction by monkey-patching the dynamic import.
+ * Instead, we'll test the tool handler indirectly through the exported
+ * createMcpServer function — capturing the registered tool handlers.
+ *
+ * Since createMcpServer dynamically imports McpServer, we need to test at
+ * a level that exercises the tool handler logic. We do this by extracting
+ * the tool handler through the server.tool() calls.
+ */
+
+interface RegisteredTool {
+  name: string;
+  description: string;
+  params: Record<string, unknown>;
+  handler: (args: Record<string, unknown>) => Promise<unknown>;
+}
+
+interface ToolResult {
+  content?: Array<{ type: string; text: string }>;
+  isError?: boolean;
+}
+
+/**
+ * Mock McpServer that captures tool registrations and provides
+ * a controllable elicitInput response.
+ */
+class MockMcpServer {
+  registeredTools: RegisteredTool[] = [];
+  elicitResponse: { action: string; content?: Record<string, unknown> } = { action: 'accept', content: {} };
+
+  server = {
+    elicitInput: async (_params: unknown) => {
+      return this.elicitResponse;
+    },
+  };
+
+  tool(name: string, description: string, params: Record<string, unknown>, handler: (args: Record<string, unknown>) => Promise<unknown>) {
+    this.registeredTools.push({ name, description, params, handler });
+  }
+
+  async connect(_transport: unknown) { /* no-op */ }
+  async close() { /* no-op */ }
+
+  getToolHandler(name: string): ((args: Record<string, unknown>) => Promise<unknown>) | undefined {
+    return this.registeredTools.find((t) => t.name === name)?.handler;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helper to create a mock MCP server with secure_env_collect registered
+// ---------------------------------------------------------------------------
+
+/**
+ * Since createMcpServer uses dynamic import for McpServer, we can't easily
+ * mock it. Instead, we test the env-writer utilities directly (in env-writer.test.ts)
+ * and test the tool integration by verifying:
+ * 1. The tool exists in the registered tools list
+ * 2. The handler produces correct results with mock data
+ *
+ * For handler-level testing, we create a standalone test that replicates
+ * the tool handler logic with a controllable mock.
+ */
+
+function makeTempDir(prefix: string): string {
+  return mkdtempSync(join(tmpdir(), `${prefix}-`));
+}
+
+// ---------------------------------------------------------------------------
+// Integration test — verify tool is registered
+// ---------------------------------------------------------------------------
+
+describe('secure_env_collect tool registration', () => {
+  it('createMcpServer registers secure_env_collect tool', async () => {
+    // This test verifies the tool exists — createMcpServer internally calls
+    // server.tool('secure_env_collect', ...) which we can't intercept without
+    // module mocking, but we can verify the server creates successfully
+    const sm = new SessionManager();
+    try {
+      const { server } = await createMcpServer(sm);
+      assert.ok(server, 'server should be created');
+      // The McpServer internally tracks registered tools — we verify no error
+    } finally {
+      await sm.cleanup();
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Handler logic tests — using env-writer directly to test the flow
+// ---------------------------------------------------------------------------
+
+describe('secure_env_collect handler logic', () => {
+  it('skips keys that already exist in .env', async () => {
+    const tmp = makeTempDir('sec-collect');
+    try {
+      const envPath = join(tmp, '.env');
+      writeFileSync(envPath, 'ALREADY_SET=existing-value\n');
+
+      // Import the utility directly to test the pre-check logic
+      const { checkExistingEnvKeys } = await import('./env-writer.js');
+      const existing = await checkExistingEnvKeys(['ALREADY_SET', 'NEW_KEY'], envPath);
+      assert.deepStrictEqual(existing, ['ALREADY_SET']);
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it('writes collected values to .env without returning secret values', async () => {
+    const tmp = makeTempDir('sec-collect');
+    try {
+      const envPath = join(tmp, '.env');
+      const savedKey = process.env.SEC_COLLECT_TEST_KEY;
+
+      const { applySecrets } = await import('./env-writer.js');
+      const { applied, errors } = await applySecrets(
+        [{ key: 'SEC_COLLECT_TEST_KEY', value: 'super-secret-value' }],
+        'dotenv',
+        { envFilePath: envPath },
+      );
+
+      assert.deepStrictEqual(applied, ['SEC_COLLECT_TEST_KEY']);
+      assert.deepStrictEqual(errors, []);
+
+      // Verify the value was written
+      const content = readFileSync(envPath, 'utf8');
+      assert.ok(content.includes('SEC_COLLECT_TEST_KEY=super-secret-value'));
+
+      // Verify process.env was hydrated
+      assert.equal(process.env.SEC_COLLECT_TEST_KEY, 'super-secret-value');
+
+      // Cleanup
+      if (savedKey === undefined) delete process.env.SEC_COLLECT_TEST_KEY;
+      else process.env.SEC_COLLECT_TEST_KEY = savedKey;
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it('auto-detects vercel destination from vercel.json', async () => {
+    const tmp = makeTempDir('sec-collect');
+    try {
+      writeFileSync(join(tmp, 'vercel.json'), '{}');
+      const { detectDestination } = await import('./env-writer.js');
+      assert.equal(detectDestination(tmp), 'vercel');
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it('handles empty form values as skipped', async () => {
+    // Simulate what happens when user leaves a field empty in the form
+    const formContent: Record<string, string> = {
+      'API_KEY': 'provided-value',
+      'OPTIONAL_KEY': '',        // empty = skip
+    };
+
+    const provided: Array<{ key: string; value: string }> = [];
+    const skipped: string[] = [];
+
+    for (const [key, raw] of Object.entries(formContent)) {
+      const value = typeof raw === 'string' ? raw.trim() : '';
+      if (value.length > 0) {
+        provided.push({ key, value });
+      } else {
+        skipped.push(key);
+      }
+    }
+
+    assert.deepStrictEqual(provided, [{ key: 'API_KEY', value: 'provided-value' }]);
+    assert.deepStrictEqual(skipped, ['OPTIONAL_KEY']);
+  });
+
+  it('result text never contains secret values', async () => {
+    const tmp = makeTempDir('sec-collect');
+    try {
+      const envPath = join(tmp, '.env');
+      const savedKey = process.env.RESULT_TEXT_TEST;
+
+      const { applySecrets } = await import('./env-writer.js');
+      const { applied } = await applySecrets(
+        [{ key: 'RESULT_TEXT_TEST', value: 'sk-super-secret-abc123' }],
+        'dotenv',
+        { envFilePath: envPath },
+      );
+
+      // Simulate building result text (same logic as the tool handler)
+      const lines: string[] = [
+        'destination: dotenv (auto-detected)',
+        ...applied.map((k) => `✓ ${k}: applied`),
+      ];
+      const resultText = lines.join('\n');
+
+      // The result MUST NOT contain the secret value
+      assert.ok(!resultText.includes('sk-super-secret-abc123'), 'result text must not contain secret value');
+      assert.ok(resultText.includes('RESULT_TEXT_TEST'), 'result text should contain key name');
+
+      // Cleanup
+      if (savedKey === undefined) delete process.env.RESULT_TEXT_TEST;
+      else process.env.RESULT_TEXT_TEST = savedKey;
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it('handles multiple keys with mixed existing/new/skipped', async () => {
+    const tmp = makeTempDir('sec-collect');
+    try {
+      const envPath = join(tmp, '.env');
+      writeFileSync(envPath, 'EXISTING_A=already-here\n');
+      const savedB = process.env.NEW_B;
+      const savedC = process.env.SKIP_C;
+
+      const { checkExistingEnvKeys, applySecrets } = await import('./env-writer.js');
+
+      const allKeys = ['EXISTING_A', 'NEW_B', 'SKIP_C'];
+      const existing = await checkExistingEnvKeys(allKeys, envPath);
+      assert.deepStrictEqual(existing, ['EXISTING_A']);
+
+      // Simulate form response: NEW_B has value, SKIP_C is empty
+      const formContent = { NEW_B: 'new-value', SKIP_C: '' };
+      const provided: Array<{ key: string; value: string }> = [];
+      const skipped: string[] = [];
+
+      for (const key of allKeys.filter((k) => !existing.includes(k))) {
+        const raw = formContent[key as keyof typeof formContent] ?? '';
+        if (raw.trim().length > 0) provided.push({ key, value: raw.trim() });
+        else skipped.push(key);
+      }
+
+      const { applied, errors } = await applySecrets(provided, 'dotenv', { envFilePath: envPath });
+
+      assert.deepStrictEqual(applied, ['NEW_B']);
+      assert.deepStrictEqual(skipped, ['SKIP_C']);
+      assert.deepStrictEqual(errors, []);
+      assert.deepStrictEqual(existing, ['EXISTING_A']);
+
+      // Cleanup
+      if (savedB === undefined) delete process.env.NEW_B;
+      else process.env.NEW_B = savedB;
+      if (savedC === undefined) delete process.env.SKIP_C;
+      else process.env.SKIP_C = savedC;
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+});

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

@@ -2,7 +2,7 @@
  * MCP Server — registers GSD orchestration, project-state, and workflow tools.
  *
  * Session tools (6): gsd_execute, gsd_status, gsd_result, gsd_cancel, gsd_query, gsd_resolve_blocker
- * Interactive tools (1): ask_user_questions via MCP form elicitation
+ * Interactive tools (2): ask_user_questions, secure_env_collect via MCP form elicitation
  * Read-only tools (6): gsd_progress, gsd_roadmap, gsd_history, gsd_doctor, gsd_captures, gsd_knowledge
  * Workflow tools (29): headless-safe planning, metadata persistence, replanning, completion, validation, reassessment, gate result, status, and journal tools
  *
@@ -22,6 +22,7 @@ import { readCaptures } from './readers/captures.js';
 import { readKnowledge } from './readers/knowledge.js';
 import { runDoctorLite } from './readers/doctor-lite.js';
 import { registerWorkflowTools } from './workflow-tools.js';
+import { applySecrets, checkExistingEnvKeys, detectDestination } from './env-writer.js';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -112,11 +113,26 @@ async function fileExists(path: string): Promise<boolean> {
 // MCP Server type — minimal interface for the dynamically-imported McpServer
 // ---------------------------------------------------------------------------
 
+interface ElicitResult {
+  action: 'accept' | 'decline' | 'cancel';
+  content?: Record<string, string | number | boolean | string[]>;
+}
+
+interface ElicitRequestFormParams {
+  mode?: 'form';
+  message: string;
+  requestedSchema: {
+    type: 'object';
+    properties: Record<string, Record<string, unknown>>;
+    required?: string[];
+  };
+}
+
 interface McpServerInstance {
   tool(name: string, description: string, params: Record<string, unknown>, handler: (args: Record<string, unknown>) => Promise<unknown>): unknown;
   server: {
     elicitInput(
-      params: AskUserQuestionsElicitRequest,
+      params: AskUserQuestionsElicitRequest | ElicitRequestFormParams,
       options?: unknown,
     ): Promise<AskUserQuestionsElicitResult>;
   };
@@ -282,7 +298,7 @@ export async function createMcpServer(sessionManager: SessionManager): Promise<{
 
   const server: McpServerInstance = new McpServer(
     { name: SERVER_NAME, version: SERVER_VERSION },
-    { capabilities: { tools: {} } },
+    { capabilities: { tools: {}, elicitation: {} } },
   );
 
   // -----------------------------------------------------------------------
@@ -472,6 +488,124 @@ export async function createMcpServer(sessionManager: SessionManager): Promise<{
     },
   );
 
+  // -----------------------------------------------------------------------
+  // secure_env_collect — collect secrets via MCP form elicitation
+  // -----------------------------------------------------------------------
+  server.tool(
+    'secure_env_collect',
+    'Collect environment variables securely via form input. Values are written directly to .env (or Vercel/Convex) and NEVER appear in tool output — only key names and applied/skipped status are returned. Use this instead of asking users to manually edit .env files or paste secrets into chat.',
+    {
+      projectDir: z.string().describe('Absolute path to the project directory'),
+      keys: z.array(z.object({
+        key: z.string().describe('Env var name, e.g. OPENAI_API_KEY'),
+        hint: z.string().optional().describe('Format hint shown to user, e.g. "starts with sk-"'),
+        guidance: z.array(z.string()).optional().describe('Step-by-step instructions for obtaining this key'),
+      })).min(1).describe('Environment variables to collect'),
+      destination: z.enum(['dotenv', 'vercel', 'convex']).optional().describe('Where to write secrets. Auto-detected from project files if omitted.'),
+      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 = resolve(projectDir);
+        const resolvedEnvPath = resolve(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 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,
+          },
+        });
+
+        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,
+        });
+
+        // (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));
+      }
+    },
+  );
+
   // =======================================================================
   // READ-ONLY TOOLS — no session required, pure filesystem reads
   // =======================================================================

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

@@ -384,6 +384,116 @@ describe("workflow MCP tools", () => {
     }
   });
 
+  it("gsd_requirement_save opens the DB before inline requirement writes", async () => {
+    const base = makeTmpBase();
+    try {
+      const server = makeMockServer();
+      registerWorkflowTools(server as any);
+      const requirementTool = server.tools.find((t) => t.name === "gsd_requirement_save");
+      assert.ok(requirementTool, "requirement tool should be registered");
+
+      closeDatabase();
+
+      const result = await requirementTool!.handler({
+        projectDir: base,
+        class: "operability",
+        description: "Inline MCP requirement save regression",
+        why: "Reproduce missing ensureDbOpen in workflow-tools",
+        source: "user",
+        status: "active",
+        primary_owner: "M010/S10",
+        validation: "n/a",
+      });
+
+      assert.match((result as any).content[0].text as string, /Saved requirement R\d+/);
+      assert.ok(existsSync(join(base, ".gsd", "REQUIREMENTS.md")), "REQUIREMENTS.md should be written to disk");
+      const row = _getAdapter()!
+        .prepare("SELECT id, class, description FROM requirements WHERE description = ?")
+        .get("Inline MCP requirement save regression") as Record<string, unknown> | undefined;
+      assert.ok(row, "requirement should be written to the database");
+      assert.equal(row["class"], "operability");
+    } finally {
+      cleanup(base);
+    }
+  });
+
+  it("gsd_plan_task reopens the DB before inline task planning writes", async () => {
+    const base = makeTmpBase();
+    try {
+      const server = makeMockServer();
+      registerWorkflowTools(server as any);
+      const milestoneTool = server.tools.find((t) => t.name === "gsd_plan_milestone");
+      const sliceTool = server.tools.find((t) => t.name === "gsd_plan_slice");
+      const taskTool = server.tools.find((t) => t.name === "gsd_plan_task");
+      assert.ok(milestoneTool, "milestone planning tool should be registered");
+      assert.ok(sliceTool, "slice planning tool should be registered");
+      assert.ok(taskTool, "task planning tool should be registered");
+
+      await milestoneTool!.handler({
+        projectDir: base,
+        milestoneId: "M010",
+        title: "Inline task planning DB reopen",
+        vision: "Seed a slice, close the DB, then plan another task inline.",
+        slices: [
+          {
+            sliceId: "S10",
+            title: "Inline task planning",
+            risk: "medium",
+            depends: [],
+            demo: "Inline gsd_plan_task reopens the DB after it was closed.",
+            goal: "Preserve MCP task planning after the DB adapter is closed.",
+            successCriteria: "The second task plan persists after a closed DB is reopened.",
+            proofLevel: "integration",
+            integrationClosure: "The inline MCP handler reopens the DB before planning.",
+            observabilityImpact: "workflow-tools MCP tests cover the inline reopen path.",
+          },
+        ],
+      });
+      await sliceTool!.handler({
+        projectDir: base,
+        milestoneId: "M010",
+        sliceId: "S10",
+        goal: "Create the initial slice plan before closing the DB.",
+        tasks: [
+          {
+            taskId: "T10",
+            title: "Seed existing task",
+            description: "Create the initial task plan before closing the DB.",
+            estimate: "5m",
+            files: ["packages/mcp-server/src/workflow-tools.ts"],
+            verify: "node --test",
+            inputs: ["M010-ROADMAP.md"],
+            expectedOutput: ["T10-PLAN.md"],
+          },
+        ],
+      });
+
+      closeDatabase();
+
+      const result = await taskTool!.handler({
+        projectDir: base,
+        milestoneId: "M010",
+        sliceId: "S10",
+        taskId: "T11",
+        title: "Reopen and plan",
+        description: "Exercise the inline plan-task path after the DB was closed.",
+        estimate: "5m",
+        files: ["packages/mcp-server/src/workflow-tools.ts"],
+        verify: "node --test",
+        inputs: ["M010-ROADMAP.md", "S10-PLAN.md"],
+        expectedOutput: ["T11-PLAN.md"],
+      });
+
+      assert.match((result as any).content[0].text as string, /Planned task T11/);
+      assert.ok(
+        existsSync(join(base, ".gsd", "milestones", "M010", "slices", "S10", "tasks", "T11-PLAN.md")),
+        "T11 plan should be written after reopening the DB",
+      );
+    } finally {
+      cleanup(base);
+    }
+  });
+
   it("gsd_replan_slice and gsd_slice_replan work end-to-end", async () => {
     const base = makeTmpBase();
     try {