gsd-pi 2.69.0 → 2.70.0

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

@@ -2,8 +2,9 @@
  * 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
  * Read-only tools (6): gsd_progress, gsd_roadmap, gsd_history, gsd_doctor, gsd_captures, gsd_knowledge
- * Workflow tools (17): planning, replanning, completion, validation, reassessment, gate result, and milestone status tools
+ * Workflow tools (29): headless-safe planning, metadata persistence, replanning, completion, validation, reassessment, gate result, status, and journal tools
  *
  * Uses dynamic imports for @modelcontextprotocol/sdk because TS Node16
  * cannot resolve the SDK's subpath exports statically (same pattern as
@@ -44,6 +45,11 @@ function errorContent(message: string): { isError: true; content: Array<{ type:
   return { isError: true, content: [{ type: 'text' as const, text: message }] };
 }
 
+/** Return raw text content without JSON wrapping. */
+function textContent(text: string): { content: Array<{ type: 'text'; text: string }> } {
+  return { content: [{ type: 'text' as const, text }] };
+}
+
 // ---------------------------------------------------------------------------
 // gsd_query filesystem reader
 // ---------------------------------------------------------------------------
@@ -108,10 +114,155 @@ async function fileExists(path: string): Promise<boolean> {
 
 interface McpServerInstance {
   tool(name: string, description: string, params: Record<string, unknown>, handler: (args: Record<string, unknown>) => Promise<unknown>): unknown;
+  server: {
+    elicitInput(
+      params: AskUserQuestionsElicitRequest,
+      options?: unknown,
+    ): Promise<AskUserQuestionsElicitResult>;
+  };
   connect(transport: unknown): Promise<void>;
   close(): Promise<void>;
 }
 
+interface AskUserQuestionOption {
+  label: string;
+  description: string;
+}
+
+interface AskUserQuestion {
+  id: string;
+  header: string;
+  question: string;
+  options: AskUserQuestionOption[];
+  allowMultiple?: boolean;
+}
+
+interface AskUserQuestionsParams {
+  questions: AskUserQuestion[];
+}
+
+type AskUserQuestionsContentValue = string | number | boolean | string[];
+
+interface AskUserQuestionsElicitResult {
+  action: 'accept' | 'decline' | 'cancel';
+  content?: Record<string, AskUserQuestionsContentValue>;
+}
+
+interface AskUserQuestionsElicitRequest {
+  mode: 'form';
+  message: string;
+  requestedSchema: {
+    type: 'object';
+    properties: Record<string, Record<string, unknown>>;
+    required?: string[];
+  };
+}
+
+const OTHER_OPTION_LABEL = 'None of the above';
+
+function normalizeAskUserQuestionsNote(value: AskUserQuestionsContentValue | undefined): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function normalizeAskUserQuestionsAnswers(
+  value: AskUserQuestionsContentValue | undefined,
+  allowMultiple: boolean,
+): string[] {
+  if (allowMultiple) {
+    return Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : [];
+  }
+
+  return typeof value === 'string' && value.length > 0 ? [value] : [];
+}
+
+function validateAskUserQuestionsPayload(questions: AskUserQuestion[]): string | null {
+  if (questions.length === 0 || questions.length > 3) {
+    return 'Error: questions must contain 1-3 items';
+  }
+
+  for (const question of questions) {
+    if (!question.options || question.options.length === 0) {
+      return `Error: ask_user_questions requires non-empty options for every question (question "${question.id}" has none)`;
+    }
+  }
+
+  return null;
+}
+
+export function buildAskUserQuestionsElicitRequest(questions: AskUserQuestion[]): AskUserQuestionsElicitRequest {
+  const properties: Record<string, Record<string, unknown>> = {};
+  const required = questions.map((question) => question.id);
+
+  for (const question of questions) {
+    if (question.allowMultiple) {
+      properties[question.id] = {
+        type: 'array',
+        title: question.header,
+        description: question.question,
+        minItems: 1,
+        maxItems: question.options.length,
+        items: {
+          anyOf: question.options.map((option) => ({
+            const: option.label,
+            title: option.label,
+          })),
+        },
+      };
+      continue;
+    }
+
+    properties[question.id] = {
+      type: 'string',
+      title: question.header,
+      description: question.question,
+      oneOf: [...question.options, { label: OTHER_OPTION_LABEL, description: 'Choose this when the listed options do not fit.' }].map((option) => ({
+        const: option.label,
+        title: option.label,
+      })),
+    };
+
+    properties[`${question.id}__note`] = {
+      type: 'string',
+      title: `${question.header} Note`,
+      description: `Optional note for "${OTHER_OPTION_LABEL}".`,
+      maxLength: 500,
+    };
+  }
+
+  return {
+    mode: 'form',
+    message: 'Please answer the following question(s). For single-select questions, choose "None of the above" and add a note if the provided options do not fit.',
+    requestedSchema: {
+      type: 'object',
+      properties,
+      required,
+    },
+  };
+}
+
+export function formatAskUserQuestionsElicitResult(
+  questions: AskUserQuestion[],
+  result: AskUserQuestionsElicitResult,
+): string {
+  const answers: Record<string, { answers: string[] }> = {};
+  const content = result.content ?? {};
+
+  for (const question of questions) {
+    const answerList = normalizeAskUserQuestionsAnswers(content[question.id], !!question.allowMultiple);
+
+    if (!question.allowMultiple && answerList[0] === OTHER_OPTION_LABEL) {
+      const note = normalizeAskUserQuestionsNote(content[`${question.id}__note`]);
+      if (note) {
+        answerList.push(`user_note: ${note}`);
+      }
+    }
+
+    answers[question.id] = { answers: answerList };
+  }
+
+  return JSON.stringify({ answers });
+}
+
 // ---------------------------------------------------------------------------
 // createMcpServer
 // ---------------------------------------------------------------------------
@@ -285,6 +436,42 @@ export async function createMcpServer(sessionManager: SessionManager): Promise<{
     },
   );
 
+  // -----------------------------------------------------------------------
+  // ask_user_questions — structured user input via MCP form elicitation
+  // -----------------------------------------------------------------------
+  server.tool(
+    'ask_user_questions',
+    'Request user input for one to three short questions and wait for the response. Single-select questions include a free-form "None of the above" path. Multi-select questions allow multiple choices.',
+    {
+      questions: z.array(z.object({
+        id: z.string().describe('Stable identifier for mapping answers (snake_case)'),
+        header: z.string().describe('Short header label shown in the UI (12 or fewer chars)'),
+        question: z.string().describe('Single-sentence prompt shown to the user'),
+        options: z.array(z.object({
+          label: z.string().describe('User-facing label (1-5 words)'),
+          description: z.string().describe('One short sentence explaining impact/tradeoff if selected'),
+        })).describe('Provide 2-3 mutually exclusive choices. Put the recommended option first and suffix its label with "(Recommended)". Do not include an "Other" option for single-select questions.'),
+        allowMultiple: z.boolean().optional().describe('If true, the user can select multiple options. No "None of the above" option is added.'),
+      })).describe('Questions to show the user. Prefer 1 and do not exceed 3.'),
+    },
+    async (args: Record<string, unknown>) => {
+      const { questions } = args as unknown as AskUserQuestionsParams;
+      try {
+        const validationError = validateAskUserQuestionsPayload(questions);
+        if (validationError) return errorContent(validationError);
+
+        const elicitation = await server.server.elicitInput(buildAskUserQuestionsElicitRequest(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));
+      }
+    },
+  );
+
   // =======================================================================
   // READ-ONLY TOOLS — no session required, pure filesystem reads
   // =======================================================================

package/packages/mcp-server/src/tool-credentials.test.ts

@@ -0,0 +1,95 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { loadStoredCredentialEnvKeys, resolveAuthPath } from "./tool-credentials.js";
+
+describe("tool credentials", () => {
+  it("hydrates supported model and tool keys from auth.json", () => {
+    const tempRoot = mkdtempSync(join(tmpdir(), "gsd-mcp-auth-"));
+    const authPath = join(tempRoot, "auth.json");
+    const env: NodeJS.ProcessEnv = {};
+
+    try {
+      writeFileSync(authPath, JSON.stringify({
+        anthropic: { type: "api_key", key: "sk-ant-secret" },
+        openai: { type: "api_key", key: "sk-openai-secret" },
+        tavily: { type: "api_key", key: "tvly-secret" },
+        context7: [{ type: "api_key", key: "ctx7-secret" }],
+      }));
+
+      const loaded = loadStoredCredentialEnvKeys({ authPath, env });
+      assert.deepEqual(loaded.sort(), [
+        "ANTHROPIC_API_KEY",
+        "CONTEXT7_API_KEY",
+        "OPENAI_API_KEY",
+        "TAVILY_API_KEY",
+      ]);
+      assert.equal(env.ANTHROPIC_API_KEY, "sk-ant-secret");
+      assert.equal(env.OPENAI_API_KEY, "sk-openai-secret");
+      assert.equal(env.TAVILY_API_KEY, "tvly-secret");
+      assert.equal(env.CONTEXT7_API_KEY, "ctx7-secret");
+    } finally {
+      rmSync(tempRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("does not overwrite explicit environment variables", () => {
+    const tempRoot = mkdtempSync(join(tmpdir(), "gsd-mcp-auth-"));
+    const authPath = join(tempRoot, "auth.json");
+    const env: NodeJS.ProcessEnv = {
+      BRAVE_API_KEY: "already-set",
+    };
+
+    try {
+      writeFileSync(authPath, JSON.stringify({
+        brave: { type: "api_key", key: "from-auth-json" },
+        anthropic: { type: "api_key", key: "sk-ant-from-auth-json" },
+      }));
+
+      const loaded = loadStoredCredentialEnvKeys({ authPath, env });
+      assert.deepEqual(loaded, ["ANTHROPIC_API_KEY"]);
+      assert.equal(env.BRAVE_API_KEY, "already-set");
+      assert.equal(env.ANTHROPIC_API_KEY, "sk-ant-from-auth-json");
+    } finally {
+      rmSync(tempRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("ignores oauth credentials because they are resolved through auth storage, not env hydration", () => {
+    const tempRoot = mkdtempSync(join(tmpdir(), "gsd-mcp-auth-"));
+    const authPath = join(tempRoot, "auth.json");
+    const env: NodeJS.ProcessEnv = {};
+
+    try {
+      writeFileSync(authPath, JSON.stringify({
+        openai: { type: "oauth", access: "oauth-access-token" },
+        "google-gemini-cli": { type: "oauth", token: "ya29.oauth-token" },
+      }));
+
+      const loaded = loadStoredCredentialEnvKeys({ authPath, env });
+      assert.deepEqual(loaded, []);
+      assert.equal(env.OPENAI_API_KEY, undefined);
+      assert.equal(env.GEMINI_API_KEY, undefined);
+    } finally {
+      rmSync(tempRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("resolves auth.json from GSD_CODING_AGENT_DIR", () => {
+    const tempRoot = mkdtempSync(join(tmpdir(), "gsd-mcp-agent-dir-"));
+    const agentDir = join(tempRoot, "agent");
+    mkdirSync(agentDir, { recursive: true });
+
+    try {
+      assert.equal(
+        resolveAuthPath({ GSD_CODING_AGENT_DIR: agentDir }),
+        join(agentDir, "auth.json"),
+      );
+    } finally {
+      rmSync(tempRoot, { recursive: true, force: true });
+    }
+  });
+});

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

@@ -0,0 +1,97 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+type AuthCredential =
+  | { type?: unknown; key?: unknown }
+  | Array<{ type?: unknown; key?: unknown }>;
+
+type AuthStorageData = Record<string, AuthCredential>;
+
+const AUTH_ENV_KEYS = [
+  ["anthropic", "ANTHROPIC_API_KEY"],
+  ["openai", "OPENAI_API_KEY"],
+  ["github-copilot", "GITHUB_TOKEN"],
+  ["google", "GEMINI_API_KEY"],
+  ["groq", "GROQ_API_KEY"],
+  ["xai", "XAI_API_KEY"],
+  ["openrouter", "OPENROUTER_API_KEY"],
+  ["mistral", "MISTRAL_API_KEY"],
+  ["ollama-cloud", "OLLAMA_API_KEY"],
+  ["custom-openai", "CUSTOM_OPENAI_API_KEY"],
+  ["cerebras", "CEREBRAS_API_KEY"],
+  ["azure-openai-responses", "AZURE_OPENAI_API_KEY"],
+  ["vercel-ai-gateway", "AI_GATEWAY_API_KEY"],
+  ["zai", "ZAI_API_KEY"],
+  ["minimax", "MINIMAX_API_KEY"],
+  ["minimax-cn", "MINIMAX_CN_API_KEY"],
+  ["huggingface", "HF_TOKEN"],
+  ["opencode", "OPENCODE_API_KEY"],
+  ["opencode-go", "OPENCODE_API_KEY"],
+  ["kimi-coding", "KIMI_API_KEY"],
+  ["alibaba-coding-plan", "ALIBABA_API_KEY"],
+  ["brave", "BRAVE_API_KEY"],
+  ["brave_answers", "BRAVE_ANSWERS_KEY"],
+  ["context7", "CONTEXT7_API_KEY"],
+  ["jina", "JINA_API_KEY"],
+  ["tavily", "TAVILY_API_KEY"],
+  ["slack_bot", "SLACK_BOT_TOKEN"],
+  ["discord_bot", "DISCORD_BOT_TOKEN"],
+  ["telegram_bot", "TELEGRAM_BOT_TOKEN"],
+] as const;
+
+function expandHome(pathValue: string): string {
+  if (pathValue === "~") return homedir();
+  if (pathValue.startsWith("~/")) return join(homedir(), pathValue.slice(2));
+  return pathValue;
+}
+
+function getStoredApiKey(data: AuthStorageData, providerId: string): string | undefined {
+  const raw = data[providerId];
+  const credentials = Array.isArray(raw) ? raw : raw ? [raw] : [];
+
+  for (const credential of credentials) {
+    if (credential?.type !== "api_key") continue;
+    if (typeof credential.key !== "string") continue;
+    if (credential.key.trim().length === 0) continue;
+    return credential.key;
+  }
+
+  return undefined;
+}
+
+export function resolveAuthPath(env: NodeJS.ProcessEnv = process.env): string {
+  const agentDir = env.GSD_CODING_AGENT_DIR?.trim();
+  if (agentDir) return join(expandHome(agentDir), "auth.json");
+  return join(homedir(), ".gsd", "agent", "auth.json");
+}
+
+export function loadStoredCredentialEnvKeys(options: {
+  env?: NodeJS.ProcessEnv;
+  authPath?: string;
+} = {}): string[] {
+  const env = options.env ?? process.env;
+  const authPath = options.authPath ?? resolveAuthPath(env);
+  if (!existsSync(authPath)) return [];
+
+  let parsed: AuthStorageData;
+  try {
+    const raw = readFileSync(authPath, "utf-8");
+    const data = JSON.parse(raw) as unknown;
+    if (!data || typeof data !== "object" || Array.isArray(data)) return [];
+    parsed = data as AuthStorageData;
+  } catch {
+    return [];
+  }
+
+  const loaded: string[] = [];
+  for (const [providerId, envVar] of AUTH_ENV_KEYS) {
+    if (env[envVar]) continue;
+    const key = getStoredApiKey(parsed, providerId);
+    if (!key) continue;
+    env[envVar] = key;
+    loaded.push(envVar);
+  }
+
+  return loaded;
+}

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

@@ -6,7 +6,7 @@ import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
 
 import { _getAdapter, closeDatabase } from "../../../src/resources/extensions/gsd/gsd-db.ts";
-import { registerWorkflowTools } from "./workflow-tools.ts";
+import { registerWorkflowTools, WORKFLOW_TOOL_NAMES } from "./workflow-tools.ts";
 
 function makeTmpBase(): string {
   const base = join(tmpdir(), `gsd-mcp-workflow-${randomUUID()}`);
@@ -68,33 +68,12 @@ function makeMockServer() {
 }
 
 describe("workflow MCP tools", () => {
-  it("registers the seventeen workflow tools", () => {
+  it("registers the full headless-safe workflow tool surface", () => {
     const server = makeMockServer();
     registerWorkflowTools(server as any);
 
-    assert.equal(server.tools.length, 17);
-    assert.deepEqual(
-      server.tools.map((t) => t.name),
-      [
-        "gsd_plan_milestone",
-        "gsd_plan_slice",
-        "gsd_replan_slice",
-        "gsd_slice_replan",
-        "gsd_slice_complete",
-        "gsd_complete_slice",
-        "gsd_complete_milestone",
-        "gsd_milestone_complete",
-        "gsd_validate_milestone",
-        "gsd_milestone_validate",
-        "gsd_reassess_roadmap",
-        "gsd_roadmap_reassess",
-        "gsd_save_gate_result",
-        "gsd_summary_save",
-        "gsd_task_complete",
-        "gsd_complete_task",
-        "gsd_milestone_status",
-      ],
-    );
+    assert.equal(server.tools.length, WORKFLOW_TOOL_NAMES.length);
+    assert.deepEqual(server.tools.map((t) => t.name), [...WORKFLOW_TOOL_NAMES]);
   });
 
   it("gsd_summary_save writes artifact through the shared executor", async () => {
@@ -974,3 +953,31 @@ describe("workflow MCP tools", () => {
     }
   });
 });
+
+describe("URL scheme regex — Windows drive letter safety", () => {
+  // This is the regex used in getWriteGateModuleCandidates() and
+  // getWorkflowExecutorModuleCandidates() to reject non-file URL schemes.
+  // It must NOT match single-letter Windows drive prefixes (C:, D:, etc.).
+  const urlSchemeRegex = /^[a-z]{2,}:/i;
+
+  it("rejects multi-letter URL schemes", () => {
+    assert.ok(urlSchemeRegex.test("http://example.com"), "http: should match");
+    assert.ok(urlSchemeRegex.test("https://example.com"), "https: should match");
+    assert.ok(urlSchemeRegex.test("ftp://files.example.com"), "ftp: should match");
+    assert.ok(urlSchemeRegex.test("file:///C:/Users"), "file: should match");
+    assert.ok(urlSchemeRegex.test("node:fs"), "node: should match");
+  });
+
+  it("allows single-letter Windows drive prefixes", () => {
+    assert.ok(!urlSchemeRegex.test("C:\\Users\\user\\project"), "C:\\ should not match");
+    assert.ok(!urlSchemeRegex.test("D:\\other\\path"), "D:\\ should not match");
+    assert.ok(!urlSchemeRegex.test("c:\\lowercase\\drive"), "c:\\ should not match");
+    assert.ok(!urlSchemeRegex.test("E:/forward/slash/path"), "E:/ should not match");
+  });
+
+  it("allows bare filesystem paths", () => {
+    assert.ok(!urlSchemeRegex.test("/usr/local/lib/module.js"), "unix absolute path should not match");
+    assert.ok(!urlSchemeRegex.test("./relative/path.js"), "relative path should not match");
+    assert.ok(!urlSchemeRegex.test("../parent/path.js"), "parent relative path should not match");
+  });
+});