@stackwright-pro/mcp 0.2.0-alpha.21 → 0.2.0-alpha.23

package/dist/server.js

@@ -1135,6 +1135,7 @@ function setupPackages(opts) {
 
 // src/tools/questions.ts
 var import_promises = require("fs/promises");
+var import_node_fs = require("fs");
 var import_node_path = require("path");
 var import_zod8 = require("zod");
 
@@ -1407,12 +1408,12 @@ function registerQuestionTools(server2) {
           content: [
             {
               type: "text",
-              text: JSON.stringify({
-                phase,
-                skipped: true,
-                reason: "No questions to present (all filtered by dependsOn conditions)",
-                answers: []
-              })
+              text: `Phase "${phase}" has no questions to present. Do NOT call ask_user_question. Call stackwright_pro_save_phase_answers({ phase: "${phase}", rawAnswers: [] }) directly, then proceed to the execution step for this phase.`
+            },
+            {
+              type: "text",
+              // Empty array — second block always present so the foreman's two-block contract holds
+              text: JSON.stringify([])
             }
           ],
           isError: false
@@ -1433,6 +1434,144 @@ function registerQuestionTools(server2) {
       };
     }
   );
+  server2.tool(
+    "stackwright_pro_get_next_question",
+    "Returns the next unanswered question for a phase as a plain JSON object \u2014 one question at a time. Returns { done: true } when all questions are answered or the phase has no questions. Call this in a loop: present the question in plain chat, get user reply, call record_answer, repeat.",
+    { phase: import_zod8.z.string().describe('Phase name e.g. "designer", "api", "auth"') },
+    async ({ phase }) => {
+      const SAFE_PHASE = /^[a-z][a-z0-9-]{0,30}$/;
+      if (!SAFE_PHASE.test(phase)) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: `Invalid phase name: "${phase.slice(0, 50)}"` })
+            }
+          ],
+          isError: true
+        };
+      }
+      const cwd = process.cwd();
+      const questionsPath = (0, import_node_path.join)(cwd, ".stackwright", "questions", `${phase}.json`);
+      let questions = [];
+      try {
+        const raw = await (0, import_promises.readFile)(questionsPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        questions = parsed.questions ?? [];
+      } catch {
+        return { content: [{ type: "text", text: JSON.stringify({ done: true }) }] };
+      }
+      if (questions.length === 0) {
+        return { content: [{ type: "text", text: JSON.stringify({ done: true }) }] };
+      }
+      const answersPath = (0, import_node_path.join)(cwd, ".stackwright", "answers", `${phase}.json`);
+      let answeredIds = /* @__PURE__ */ new Set();
+      try {
+        const raw = await (0, import_promises.readFile)(answersPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        answeredIds = new Set(Object.keys(parsed.answers ?? {}));
+      } catch {
+      }
+      const next = questions.find((q) => !answeredIds.has(q.id));
+      if (!next) {
+        return { content: [{ type: "text", text: JSON.stringify({ done: true }) }] };
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              done: false,
+              questionId: next.id,
+              question: next.question,
+              type: next.type,
+              options: next.options ?? null,
+              help: next.help ?? null,
+              index: questions.indexOf(next) + 1,
+              total: questions.length
+            })
+          }
+        ]
+      };
+    }
+  );
+  server2.tool(
+    "stackwright_pro_record_answer",
+    "Records a single answer to a phase question. Appends to .stackwright/answers/{phase}.json incrementally. Idempotent \u2014 calling twice for the same questionId overwrites. Call after receiving each user reply in the conversational question loop.",
+    {
+      phase: import_zod8.z.string().describe('Phase name e.g. "designer"'),
+      questionId: import_zod8.z.string().describe('The question ID from get_next_question, e.g. "designer-1"'),
+      answer: import_zod8.z.string().describe("The user's free-text answer")
+    },
+    async ({ phase, questionId, answer }) => {
+      const SAFE_PHASE = /^[a-z][a-z0-9-]{0,30}$/;
+      if (!SAFE_PHASE.test(phase)) {
+        return {
+          content: [
+            { type: "text", text: JSON.stringify({ error: "Invalid phase name" }) }
+          ],
+          isError: true
+        };
+      }
+      if (!/^[a-z0-9][a-z0-9-]{0,63}$/i.test(questionId)) {
+        return {
+          content: [
+            { type: "text", text: JSON.stringify({ error: "Invalid questionId" }) }
+          ],
+          isError: true
+        };
+      }
+      const safeAnswer = answer.slice(0, 2e3);
+      const cwd = process.cwd();
+      const answersDir = (0, import_node_path.join)(cwd, ".stackwright", "answers");
+      const answersPath = (0, import_node_path.join)(answersDir, `${phase}.json`);
+      if ((0, import_node_fs.existsSync)(answersDir) && (0, import_node_fs.lstatSync)(answersDir).isSymbolicLink()) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: "answers dir is a symlink \u2014 refusing to write" })
+            }
+          ],
+          isError: true
+        };
+      }
+      (0, import_node_fs.mkdirSync)(answersDir, { recursive: true });
+      let existing = {
+        version: "1.0",
+        phase,
+        answers: {}
+      };
+      try {
+        if ((0, import_node_fs.existsSync)(answersPath)) {
+          if ((0, import_node_fs.lstatSync)(answersPath).isSymbolicLink()) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify({ error: "answers file is a symlink \u2014 refusing to write" })
+                }
+              ],
+              isError: true
+            };
+          }
+          const raw = await (0, import_promises.readFile)(answersPath, "utf-8");
+          existing = JSON.parse(raw);
+        }
+      } catch {
+      }
+      existing.answers[questionId] = safeAnswer;
+      existing.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+      const tmp = `${answersPath}.tmp`;
+      await (0, import_promises.writeFile)(tmp, JSON.stringify(existing, null, 2), "utf-8");
+      (0, import_node_fs.renameSync)(tmp, answersPath);
+      return {
+        content: [
+          { type: "text", text: JSON.stringify({ recorded: true, phase, questionId }) }
+        ]
+      };
+    }
+  );
 }
 
 // src/tools/orchestration.ts
@@ -1604,7 +1743,57 @@ function handleGetOtterName(input) {
     isError: false
   };
 }
+function handleSaveBuildContext(input) {
+  const cwd = input._cwd ?? process.cwd();
+  const dir = (0, import_path3.join)(cwd, ".stackwright");
+  const filePath = (0, import_path3.join)(dir, "build-context.json");
+  try {
+    (0, import_fs3.mkdirSync)(dir, { recursive: true });
+    if ((0, import_fs3.existsSync)(filePath)) {
+      const stat = (0, import_fs3.lstatSync)(filePath);
+      if (stat.isSymbolicLink()) {
+        return {
+          text: JSON.stringify({
+            success: false,
+            error: `Refusing to write to symlink: ${filePath}`
+          }),
+          isError: true
+        };
+      }
+    }
+    const payload = {
+      version: "1.0",
+      savedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      buildContext: input.buildContext
+    };
+    (0, import_fs3.writeFileSync)(filePath, JSON.stringify(payload, null, 2) + "\n");
+    return {
+      text: JSON.stringify({ success: true, path: filePath }),
+      isError: false
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      text: JSON.stringify({ success: false, error: message }),
+      isError: true
+    };
+  }
+}
 function registerOrchestrationTools(server2) {
+  server2.tool(
+    "stackwright_pro_save_build_context",
+    `Save the user's initial build description to .stackwright/build-context.json. Call this once at startup after the user answers the opening "what are you building" question. The saved context is automatically prepended to specialist prompts by stackwright_pro_build_specialist_prompt.`,
+    {
+      buildContext: import_zod9.z.string().describe("Free-text description of what the user wants to build")
+    },
+    async ({ buildContext }) => {
+      const { text, isError } = handleSaveBuildContext({ buildContext });
+      return {
+        content: [{ type: "text", text }],
+        isError
+      };
+    }
+  );
   server2.tool(
     "stackwright_pro_parse_otter_response",
     "Parse and validate a specialist otter's QUESTION_COLLECTION_MODE JSON response. Handles JSON extraction from LLM responses (strips markdown, fixes single quotes, trailing commas). Detects the phase from the otter name. Use this immediately after invoke_agent() to get a validated manifest phase object.",
@@ -1883,28 +2072,62 @@ function handleSetPipelineState(input) {
     return { text: JSON.stringify({ error: true, message: String(err) }), isError: true };
   }
 }
-function handleCheckExecutionReady(_cwd) {
+function handleCheckExecutionReady(_cwd, phase) {
   const cwd = _cwd ?? process.cwd();
+  if (phase) {
+    if (!isValidPhase(phase)) {
+      return {
+        text: JSON.stringify({
+          error: true,
+          message: `Invalid phase: ${phase}. Valid phases are: ${PHASE_ORDER.join(", ")}`
+        }),
+        isError: true
+      };
+    }
+    const answerFile = (0, import_path4.join)(cwd, ".stackwright", "answers", `${phase}.json`);
+    if (!(0, import_fs4.existsSync)(answerFile)) {
+      return {
+        text: JSON.stringify({ ready: false, phase, reason: "Answer file not found" }),
+        isError: false
+      };
+    }
+    try {
+      const raw = safeReadSync(answerFile);
+      const parsed = JSON.parse(raw);
+      if (typeof parsed["version"] !== "string" || typeof parsed["phase"] !== "string" || typeof parsed["answers"] !== "object" || parsed["answers"] === null) {
+        return {
+          text: JSON.stringify({ ready: false, phase, reason: "Answer file is malformed" }),
+          isError: false
+        };
+      }
+      return { text: JSON.stringify({ ready: true, phase }), isError: false };
+    } catch {
+      return {
+        text: JSON.stringify({ ready: false, phase, reason: "Answer file could not be parsed" }),
+        isError: false
+      };
+    }
+  }
   try {
     const answersDir = (0, import_path4.join)(cwd, ".stackwright", "answers");
     const answeredPhases = [];
     const missingPhases = [];
-    for (const phase of PHASE_ORDER) {
-      const answerFile = (0, import_path4.join)(answersDir, `${phase}.json`);
+    for (const phase2 of PHASE_ORDER) {
+      const answerFile = (0, import_path4.join)(answersDir, `${phase2}.json`);
       if ((0, import_fs4.existsSync)(answerFile)) {
         try {
           const raw = safeReadSync(answerFile);
           const parsed = JSON.parse(raw);
           if (typeof parsed["version"] !== "string" || typeof parsed["phase"] !== "string" || typeof parsed["answers"] !== "object" || parsed["answers"] === null) {
-            missingPhases.push(phase);
+            missingPhases.push(phase2);
             continue;
           }
-          answeredPhases.push(phase);
+          answeredPhases.push(phase2);
         } catch {
-          missingPhases.push(phase);
+          missingPhases.push(phase2);
         }
       } else {
-        missingPhases.push(phase);
+        missingPhases.push(phase2);
       }
     }
     return {
@@ -2014,6 +2237,17 @@ function handleBuildSpecialistPrompt(input) {
     if ((0, import_fs4.existsSync)(answersPath)) {
       answers = JSON.parse(safeReadSync(answersPath));
     }
+    let buildContextText = "";
+    const buildContextPath = (0, import_path4.join)(cwd, ".stackwright", "build-context.json");
+    if ((0, import_fs4.existsSync)(buildContextPath)) {
+      try {
+        const bcRaw = JSON.parse(safeReadSync(buildContextPath));
+        if (typeof bcRaw.buildContext === "string" && bcRaw.buildContext.trim().length > 0) {
+          buildContextText = bcRaw.buildContext.trim();
+        }
+      } catch {
+      }
+    }
     const deps = PHASE_DEPENDENCIES[phase];
     const artifactSections = [];
     const missingDependencies = [];
@@ -2024,13 +2258,14 @@ function handleBuildSpecialistPrompt(input) {
         const content = JSON.parse(safeReadSync(artifactPath));
         const expectedOtter = PHASE_TO_OTTER2[dep];
         const artifactOtter = content["generatedBy"];
+        const normalizedOtter = artifactOtter?.replace(/-[a-f0-9]{6}$/, "");
         if (!artifactOtter) {
           missingDependencies.push(dep);
           artifactSections.push(
             `[${artifactFile}]:
 (integrity check failed: missing generatedBy field)`
           );
-        } else if (artifactOtter !== expectedOtter) {
+        } else if (normalizedOtter !== expectedOtter) {
           missingDependencies.push(dep);
           artifactSections.push(
             `[${artifactFile}]:
@@ -2046,7 +2281,11 @@ ${JSON.stringify(content, null, 2)}`);
 (not yet available)`);
       }
     }
-    const parts = ["ANSWERS:", JSON.stringify(answers, null, 2)];
+    const parts = [];
+    if (buildContextText) {
+      parts.push("BUILD_CONTEXT:", buildContextText, "");
+    }
+    parts.push("ANSWERS:", JSON.stringify(answers, null, 2));
     if (artifactSections.length > 0) {
       parts.push("", "UPSTREAM ARTIFACTS:", "", ...artifactSections);
     }
@@ -2205,9 +2444,11 @@ function registerPipelineTools(server2) {
   );
   server2.tool(
     "stackwright_pro_check_execution_ready",
-    `Check all phases have answer files in .stackwright/answers/. ${DESC}`,
-    {},
-    async () => res(handleCheckExecutionReady())
+    `Check all phases have answer files in .stackwright/answers/. If phase is provided, check only that phase. ${DESC}`,
+    {
+      phase: import_zod10.z.string().optional().describe("If provided, check only this phase's readiness. Omit to check all phases.")
+    },
+    async ({ phase }) => res(handleCheckExecutionReady(void 0, phase))
   );
   server2.tool(
     "stackwright_pro_list_artifacts",
@@ -2217,12 +2458,49 @@ function registerPipelineTools(server2) {
   );
   server2.tool(
     "stackwright_pro_write_phase_questions",
-    `Parse otter question-collection response \u2192 .stackwright/questions/{phase}.json. ${DESC}`,
+    `Parse otter question-collection response \u2192 .stackwright/questions/{phase}.json. Specialists may also call this directly with a parsed questions array. ${DESC}`,
     {
-      phase: import_zod10.z.string().describe('Phase name, e.g. "designer"'),
-      responseText: import_zod10.z.string().describe("Raw LLM response from QUESTION_COLLECTION_MODE")
+      phase: import_zod10.z.string().optional().describe('Phase name, e.g. "designer" (required for direct write)'),
+      responseText: import_zod10.z.string().optional().describe("Raw LLM response from QUESTION_COLLECTION_MODE"),
+      questions: jsonCoerce(import_zod10.z.array(import_zod10.z.any()).optional()).describe(
+        "Questions array for direct specialist write"
+      )
     },
-    async ({ phase, responseText }) => res(handleWritePhaseQuestions({ phase, responseText }))
+    async ({ phase, responseText, questions }) => {
+      if (phase && questions && Array.isArray(questions)) {
+        const SAFE_PHASE = /^[a-z][a-z0-9-]{0,30}$/;
+        if (!SAFE_PHASE.test(phase)) {
+          return {
+            content: [
+              { type: "text", text: JSON.stringify({ error: `Invalid phase name` }) }
+            ],
+            isError: true
+          };
+        }
+        const questionsDir = (0, import_path4.join)(process.cwd(), ".stackwright", "questions");
+        (0, import_fs4.mkdirSync)(questionsDir, { recursive: true });
+        const outPath = (0, import_path4.join)(questionsDir, `${phase}.json`);
+        (0, import_fs4.writeFileSync)(
+          outPath,
+          JSON.stringify({ phase, questions, writtenAt: (/* @__PURE__ */ new Date()).toISOString() }, null, 2)
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                written: true,
+                phase,
+                count: questions.length
+              })
+            }
+          ]
+        };
+      }
+      return res(
+        handleWritePhaseQuestions({ phase: phase ?? "", responseText: responseText ?? "" })
+      );
+    }
   );
   server2.tool(
     "stackwright_pro_build_specialist_prompt",
@@ -2477,7 +2755,9 @@ function registerSafeWriteTools(server2) {
       callerOtter: import_zod11.z.string().describe('The otter agent name requesting the write, e.g. "stackwright-pro-page-otter"'),
       filePath: import_zod11.z.string().describe('Relative path from project root, e.g. "pages/dashboard/content.yml"'),
       content: import_zod11.z.string().describe("File content to write"),
-      createDirectories: import_zod11.z.boolean().optional().describe("Create parent directories if they don't exist. Default: true")
+      createDirectories: boolCoerce(import_zod11.z.boolean().optional().default(true)).describe(
+        "Create parent directories if they don't exist. Default: true"
+      )
     },
     async ({ callerOtter, filePath, content, createDirectories }) => {
       const result = handleSafeWrite({
@@ -2891,39 +3171,39 @@ var import_path7 = require("path");
 var _checksums = /* @__PURE__ */ new Map([
   [
     "stackwright-pro-api-otter.json",
-    "f1cc9edf2dd1df3ebcea1d0ab33d17a358faaf8aa97ee232cd7994042f2eac0d"
+    "0ac26d85a5ad35b072a58965e1d5e090dd5c5f16dc14e68c452c3e99fcbb5510"
   ],
   [
     "stackwright-pro-auth-otter.json",
-    "a19e06c503209a8a35fe321d30448623545b36b48c47a6ec064d13406ad1f725"
+    "d789b71f196659d5745ebfca87a7bda60a1bb63cfeccd17b4a273ac1e29bb08d"
   ],
   [
     "stackwright-pro-dashboard-otter.json",
-    "b3cb3d7554f2e9eed3b57d5e0e3bf85d6ba5b4db5d3af5514391cf0575fcc001"
+    "600e8597429c353e5b886f316731be84a86cd8b93617bf046e3cbf390b31a431"
   ],
   [
     "stackwright-pro-data-otter.json",
-    "bfacb87ae82867472a75982215554336a105a658d6cd3dd2c8b819fa1e11d7ac"
+    "b2946e3da3b53282c122d150e6db86b0cb89d2edba2a94a7666b26d27051be96"
   ],
   [
     "stackwright-pro-designer-otter.json",
-    "c58fa7c7ead9e6398074e1c7ce3f31a8ef4eb3679f5fa18cc03cae3a87878c88"
+    "f4dbff5149051c77be1645de5ee12c0bd7d590c687a0b2d86737b915a5a6d5f0"
   ],
   [
     "stackwright-pro-foreman-otter.json",
-    "f52264c1f6297b72f3da6d92d41b6d63356db776242caeab25571e6a8df628e4"
+    "7464523d7288374dc6efa5c213c825ec0616e00cf4f739d8039eb41df812cbc5"
   ],
   [
     "stackwright-pro-page-otter.json",
-    "65bec3a3a0dda6b7591bba2de9399f1e3a4fb99cfe1075342f4f4be98d917b67"
+    "12aca7b666b3c85c1d96c700a2da7f209604cb75d0f064995e052711ddafd657"
   ],
   [
     "stackwright-pro-theme-otter.json",
-    "1f182326f1acd3d4091a38c7012085cbb4945893e95be4ca3de72318ad092767"
+    "a303ec6c045420f2c916583e3f6efcda469e9610fedfc84a508ed8a8a75866bc"
   ],
   [
     "stackwright-pro-workflow-otter.json",
-    "0eec9d6a731678cf547c2a7b0b6fc338ca143c35501365a1e4e5dd2779dd5510"
+    "16da6c109d0b5ee60d0a14e009dbeab02a7bbac3b0947795769da053565b9821"
   ]
 ]);
 Object.freeze(_checksums);
@@ -3529,7 +3809,7 @@ var package_default = {
     "test:coverage": "vitest run --coverage"
   },
   name: "@stackwright-pro/mcp",
-  version: "0.2.0-alpha.13",
+  version: "0.2.0-alpha.23",
   description: "MCP tools for Stackwright Pro - Data Explorer, Security, ISR, and Dashboard generation",
   license: "PROPRIETARY",
   main: "./dist/server.js",