@stackwright-pro/mcp 0.2.0-alpha.101 → 0.2.0-alpha.102

package/dist/server.mjs

@@ -556,7 +556,7 @@ function registerDashboardTools(server2) {
         yamlLines.push(`          header: Status`);
         yamlLines.push(`          type: badge`);
       }
-      const yaml = yamlLines.join("\n");
+      const yaml2 = yamlLines.join("\n");
       return {
         content: [
           {
@@ -566,7 +566,7 @@ function registerDashboardTools(server2) {
 Layout: ${layout}
 
 \`\`\`yaml
-${yaml}
+${yaml2}
 \`\`\`
 
 \u{1F4A1} Add this to pages/dashboard/content.yml and validate with stackwright_validate_pages.`
@@ -647,7 +647,7 @@ ${yaml}
       yamlLines.push("          action: navigate");
       yamlLines.push(`          href: "/${entity}"`);
       yamlLines.push("          style: secondary");
-      const yaml = yamlLines.join("\n");
+      const yaml2 = yamlLines.join("\n");
       return {
         content: [
           {
@@ -655,7 +655,7 @@ ${yaml}
             text: `\u{1F4C4} Generated Detail Page for: ${entity}
 
 \`\`\`yaml
-${yaml}
+${yaml2}
 \`\`\`
 
 \u{1F4A1} Add this to pages/${entity}/[${slugField}]/content.yml and validate.`
@@ -2455,7 +2455,7 @@ function enrichErrors(issues, synonyms) {
   });
 }
 function handleValidateYamlFragment(input) {
-  const { schemaName, yaml } = input;
+  const { schemaName, yaml: yaml2 } = input;
   if (!SUPPORTED_SCHEMA_NAMES.includes(schemaName)) {
     return {
       valid: false,
@@ -2465,7 +2465,7 @@ function handleValidateYamlFragment(input) {
   const name = schemaName;
   let parsed;
   try {
-    parsed = yamlLoad(yaml);
+    parsed = yamlLoad(yaml2);
   } catch (err) {
     return {
       valid: false,
@@ -2491,8 +2491,8 @@ function registerValidateYamlFragmentTool(server2) {
       ),
       yaml: z11.string().describe("YAML string to validate (can also be JSON \u2014 js-yaml parses both)")
     },
-    async ({ schemaName, yaml }) => {
-      const result = handleValidateYamlFragment({ schemaName, yaml });
+    async ({ schemaName, yaml: yaml2 }) => {
+      const result = handleValidateYamlFragment({ schemaName, yaml: yaml2 });
       return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
       };
@@ -2967,7 +2967,8 @@ function defaultPhaseStatus() {
     answered: false,
     executed: false,
     artifactWritten: false,
-    retryCount: 0
+    retryCount: 0,
+    inFlight: false
   };
 }
 function createDefaultState() {
@@ -3084,7 +3085,13 @@ function handleSetPipelineState(input) {
       isError: true
     };
   }
-  const VALID_FIELDS = ["questionsCollected", "answered", "executed", "artifactWritten"];
+  const VALID_FIELDS = [
+    "questionsCollected",
+    "answered",
+    "executed",
+    "artifactWritten",
+    "inFlight"
+  ];
   if (input.field && !VALID_FIELDS.includes(input.field)) {
     return {
       text: JSON.stringify({
@@ -4143,6 +4150,14 @@ function handleEmitEvent(input) {
         };
       }
       emitted = emitFn({ type: "phase_start", phase: input.phase, otter: caller });
+    } else if (input.type === "phase_ready") {
+      if (!input.phase) {
+        return {
+          text: JSON.stringify({ emitted: false, reason: "phase required for phase_ready" }),
+          isError: false
+        };
+      }
+      emitted = emitFn({ type: "phase_ready", phase: input.phase, otter: caller });
     } else if (input.type === "phase_complete") {
       if (!input.phase) {
         return {
@@ -4183,23 +4198,24 @@ function handleEmitEvent(input) {
   }
 }
 function registerPipelineTools(server2) {
-  const DESC = "Writes state to .stackwright/ \u2014 the filesystem is the state machine.";
+  const DESC2 = "Writes state to .stackwright/ \u2014 the filesystem is the state machine.";
   const res = (r) => ({
     content: [{ type: "text", text: r.text }],
     isError: r.isError
   });
   server2.tool(
     "stackwright_pro_get_pipeline_state",
-    `Read pipeline state from .stackwright/pipeline-state.json. ${DESC}`,
+    `Read pipeline state from .stackwright/pipeline-state.json. ${DESC2}`,
     {},
     async () => res(handleGetPipelineState())
   );
   server2.tool(
     "stackwright_pro_set_pipeline_state",
-    `Atomic read\u2192modify\u2192write pipeline state. ${DESC}`,
+    `Atomic read\u2192modify\u2192write pipeline state. ${DESC2}`,
     {
       phase: z13.string().optional().describe('Phase to update, e.g. "designer"'),
-      field: z13.enum(["questionsCollected", "answered", "executed", "artifactWritten"]).optional().describe("Boolean field to set"),
+      field: z13.enum(["questionsCollected", "answered", "executed", "artifactWritten", "inFlight"]).optional().describe("Boolean field to set"),
+      // inFlight: set true BEFORE specialist invoke (dataflow mode, swp-ioc7); false after.
       value: boolCoerce(z13.boolean().optional()).describe(
         'Value for the field \u2014 must be a JSON boolean (true/false), NOT the string "true"/"false"'
       ),
@@ -4211,7 +4227,13 @@ function registerPipelineTools(server2) {
         z13.array(
           z13.object({
             phase: z13.string(),
-            field: z13.enum(["questionsCollected", "answered", "executed", "artifactWritten"]),
+            field: z13.enum([
+              "questionsCollected",
+              "answered",
+              "executed",
+              "artifactWritten",
+              "inFlight"
+            ]),
             value: z13.boolean()
           })
         ).optional()
@@ -4230,7 +4252,7 @@ function registerPipelineTools(server2) {
   );
   server2.tool(
     "stackwright_pro_check_execution_ready",
-    `Check all phases have answer files in .stackwright/answers/. If phase is provided, check only that phase. ${DESC}`,
+    `Check all phases have answer files in .stackwright/answers/. If phase is provided, check only that phase. ${DESC2}`,
     {
       phase: z13.string().optional().describe("If provided, check only this phase's readiness. Omit to check all phases.")
     },
@@ -4238,19 +4260,19 @@ function registerPipelineTools(server2) {
   );
   server2.tool(
     "stackwright_pro_get_ready_phases",
-    `Return phases whose dependencies are all satisfied (executed=true). Use to determine which phases can run next \u2014 enables wave-based execution. ${DESC}`,
+    `Return phases whose dependencies are all satisfied (executed=true). Use to determine which phases can run next \u2014 enables wave-based execution. ${DESC2}`,
     {},
     async () => res(handleGetReadyPhases())
   );
   server2.tool(
     "stackwright_pro_list_artifacts",
-    `List phase artifacts in .stackwright/artifacts/ with completedCount/totalCount. ${DESC}`,
+    `List phase artifacts in .stackwright/artifacts/ with completedCount/totalCount. ${DESC2}`,
     {},
     async () => res(handleListArtifacts())
   );
   server2.tool(
     "stackwright_pro_write_phase_questions",
-    `Parse otter question-collection response \u2192 .stackwright/questions/{phase}.json. Specialists may also call this directly with a parsed questions array. ${DESC}`,
+    `Parse otter question-collection response \u2192 .stackwright/questions/{phase}.json. Specialists may also call this directly with a parsed questions array. ${DESC2}`,
     {
       phase: z13.string().optional().describe('Phase name, e.g. "designer" (required for direct write)'),
       responseText: z13.string().optional().describe("Raw LLM response from QUESTION_COLLECTION_MODE"),
@@ -4295,13 +4317,13 @@ function registerPipelineTools(server2) {
   );
   server2.tool(
     "stackwright_pro_build_specialist_prompt",
-    `Assemble execution prompt from answers + upstream artifacts. Foreman passes verbatim. ${DESC}`,
+    `Assemble execution prompt from answers + upstream artifacts. Foreman passes verbatim. ${DESC2}`,
     { phase: z13.string().describe('Phase to build prompt for, e.g. "pages"') },
     async ({ phase }) => res(handleBuildSpecialistPrompt({ phase }))
   );
   server2.tool(
     "stackwright_pro_validate_artifact",
-    `Validate and write artifact to .stackwright/artifacts/. Returns retryPrompt on failure. ${DESC}`,
+    `Validate and write artifact to .stackwright/artifacts/. Returns retryPrompt on failure. ${DESC2}`,
     {
       phase: z13.string().describe('Phase that produced this artifact, e.g. "designer"'),
       responseText: z13.string().optional().describe("Raw response text from the specialist otter (Foreman-mediated path, legacy)"),
@@ -4333,9 +4355,17 @@ function registerPipelineTools(server2) {
   );
   server2.tool(
     "stackwright_pro_emit_event",
-    `FOREMAN ONLY \u2014 specialist otters that call this will receive an authorization rejection (no-op, not an error). Emit a telemetry event to .stackwright/pipeline-events.ndjson. Foreman calls this at phase boundaries and agent-invoke boundaries. Best-effort: failures are silent and never block. ${DESC}`,
+    `FOREMAN ONLY \u2014 specialist otters that call this will receive an authorization rejection (no-op, not an error). Emit a telemetry event to .stackwright/pipeline-events.ndjson. Foreman calls this at phase boundaries and agent-invoke boundaries. Best-effort: failures are silent and never block. ${DESC2}`,
     {
-      type: z13.enum(["phase_start", "phase_complete", "agent_invoke_start", "agent_invoke_complete"]).describe("Event type to emit"),
+      type: z13.enum([
+        "phase_start",
+        "phase_complete",
+        "phase_ready",
+        "agent_invoke_start",
+        "agent_invoke_complete"
+      ]).describe("Event type to emit"),
+      // phase_ready: emitted in dataflow mode (swp-ioc7) when a phase enters the ready set
+      // (deps satisfied, not inFlight, not yet complete) — BEFORE invoking the specialist.
       phase: z13.string().optional().describe("Current phase name"),
       targetOtter: z13.string().optional().describe("For agent_invoke_* events: which otter is being invoked"),
       success: boolCoerce(z13.boolean().optional()).describe(
@@ -4446,7 +4476,17 @@ var OTTER_WRITE_ALLOWLISTS = {
     { prefix: "pages/", suffix: "/content.yml", description: "Landing page content" },
     { prefix: "pages/", suffix: "/content.yaml", description: "Landing page content" },
     { prefix: ".stackwright/artifacts/", suffix: ".json", description: "Polish artifact" },
-    { prefix: "README.md", suffix: "", description: "Project README rewrite" }
+    { prefix: "README.md", suffix: "", description: "Project README rewrite" },
+    {
+      prefix: ".env.local",
+      suffix: "",
+      description: ".env.local runtime config \u2014 emitter output from stackwright_pro_emit_env_local (swp-8qdd)"
+    },
+    {
+      prefix: ".env.local.example",
+      suffix: "",
+      description: ".env.local.example template \u2014 emitter output from stackwright_pro_emit_env_local (swp-8qdd)"
+    }
   ],
   // QA otter writes ONLY to the qa/ directory and the qa-findings artifact.
   // It never writes .tsx, .ts, .yml, or .json outside these paths.
@@ -4814,10 +4854,10 @@ function handleSafeWrite(input) {
   return result;
 }
 function registerSafeWriteTools(server2) {
-  const DESC = "Controlled file-write chokepoint. Every write from specialist otters goes through this tool with per-otter path allowlists. The LLM cannot write to arbitrary filesystem paths.";
+  const DESC2 = "Controlled file-write chokepoint. Every write from specialist otters goes through this tool with per-otter path allowlists. The LLM cannot write to arbitrary filesystem paths.";
   server2.tool(
     "stackwright_pro_safe_write",
-    DESC,
+    DESC2,
     {
       callerOtter: z14.string().describe('The otter agent name requesting the write, e.g. "stackwright-pro-page-otter"'),
       filePath: z14.string().describe('Relative path from project root, e.g. "pages/dashboard/content.yml"'),
@@ -5785,7 +5825,7 @@ var _checksums = /* @__PURE__ */ new Map([
   ],
   [
     "stackwright-pro-foreman-otter.json",
-    "9191e176241c15f3d77180e1b843cc3a517b708737b5bd3cda7db62f2d6675d1"
+    "c23436769a9db06fa6f9d312b4fdd8b2cef6646461020eeaf227303350073593"
   ],
   [
     "stackwright-pro-form-wizard-otter.json",
@@ -5801,7 +5841,7 @@ var _checksums = /* @__PURE__ */ new Map([
   ],
   [
     "stackwright-pro-polish-otter.json",
-    "9d0c53651b60507607efc0d9a0f9d166bf5ae8571f1645682e0b151d42c276ab"
+    "fd8f8963266c6179eebf8eac4f656e8274aa3a721e5296abdbde5b00ad8a2297"
   ],
   [
     "stackwright-pro-qa-otter.json",
@@ -5809,7 +5849,7 @@ var _checksums = /* @__PURE__ */ new Map([
   ],
   [
     "stackwright-pro-scaffold-otter.json",
-    "5756ea77178334684b4df1d9d3395bca62cedb4991ab07dc4cf61aa7e540ea14"
+    "c2ae10733d8bd66bd965b29a77193b0abf0ea6765cd02886df1413bf598e0588"
   ],
   [
     "stackwright-pro-theme-otter.json",
@@ -6890,10 +6930,10 @@ function handleCleanupScaffold(_cwd) {
   };
 }
 function registerScaffoldCleanupTools(server2) {
-  const DESC = "Deterministic scaffold remnant cleanup \u2014 removes stale OSS scaffold files after raft run.";
+  const DESC2 = "Deterministic scaffold remnant cleanup \u2014 removes stale OSS scaffold files after raft run.";
   server2.tool(
     "stackwright_pro_cleanup_scaffold",
-    `Remove/rewrite stale scaffold files (blog posts, hardcoded not-found page) after the raft pipeline completes. ${DESC}`,
+    `Remove/rewrite stale scaffold files (blog posts, hardcoded not-found page) after the raft pipeline completes. ${DESC2}`,
     {},
     async () => {
       const r = handleCleanupScaffold();
@@ -7461,10 +7501,100 @@ function registerStripLegacyIntegrationsTool(server2) {
   );
 }
 
-// src/tools/list-specs.ts
+// src/tools/emitters.ts
 import { z as z22 } from "zod";
-import { readdirSync as readdirSync5, readFileSync as readFileSync12, statSync, existsSync as existsSync12 } from "fs";
-import { join as join13, extname, basename as basename2 } from "path";
+import { readFileSync as readFileSync12, existsSync as existsSync12, readdirSync as readdirSync5 } from "fs";
+import { join as join13 } from "path";
+import yaml from "js-yaml";
+import { emitEnvLocal } from "@stackwright-pro/emitters";
+function readIntegrations(cwd) {
+  const filePath = join13(cwd, "stackwright.integrations.yml");
+  if (!existsSync12(filePath)) return [];
+  try {
+    const raw = yaml.load(readFileSync12(filePath, "utf-8"));
+    if (!raw?.integrations || !Array.isArray(raw.integrations)) return [];
+    return raw.integrations.filter((i) => typeof i.name === "string").map((i) => ({
+      name: i.name,
+      auth: i.auth ? { type: i.auth.type, header: i.auth.header, envVar: i.auth.envVar } : void 0
+    }));
+  } catch {
+    return [];
+  }
+}
+function readServiceTokenRefs(cwd) {
+  const servicesDir = join13(cwd, "services");
+  if (!existsSync12(servicesDir)) return [];
+  try {
+    const files = readdirSync5(servicesDir).filter((f) => f.endsWith(".yml") || f.endsWith(".yaml"));
+    const refs = [];
+    for (const file of files) {
+      try {
+        const raw = yaml.load(
+          readFileSync12(join13(servicesDir, file), "utf-8")
+        );
+        if (raw?.tokenEnv && typeof raw.tokenEnv === "string") {
+          refs.push({
+            name: raw.name ?? file.replace(/\.ya?ml$/, ""),
+            tokenEnv: raw.tokenEnv
+          });
+        }
+      } catch {
+      }
+    }
+    return refs;
+  } catch {
+    return [];
+  }
+}
+var DESC = "Returns { envLocal, envLocalExample } as JSON. The otter writes both files via stackwright_pro_safe_write.";
+function registerEmitterTools(server2) {
+  server2.tool(
+    "stackwright_pro_emit_env_local",
+    `Emit .env.local + .env.local.example contents from stackwright.integrations.yml and services/*.yml. Deterministic emitter \u2014 same project config produces byte-identical output. 
+
+Call this tool, then write both files with stackwright_pro_safe_write:
+  1. stackwright_pro_emit_env_local({ cwd }) \u2192 { envLocal, envLocalExample }
+  2. stackwright_pro_safe_write({ filePath: '.env.local', content: envLocal, ... })
+  3. stackwright_pro_safe_write({ filePath: '.env.local.example', content: envLocalExample, ... })
+
+Do NOT compose the contents by hand. This emitter is the source of truth. If an env var is missing, update integrations.yml or the emitter \u2014 not the file. This is the first concrete instance of the swp-zf9y deterministic emitter pattern. ${DESC}`,
+    {
+      cwd: z22.string().describe(
+        "Absolute path to the project root containing stackwright.integrations.yml and optionally services/*.yml"
+      )
+    },
+    async ({ cwd }) => {
+      const integrations = readIntegrations(cwd);
+      const services = readServiceTokenRefs(cwd);
+      const output = emitEnvLocal({ integrations, services });
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                envLocal: output.envLocal,
+                envLocalExample: output.envLocalExample,
+                meta: {
+                  integrationsRead: integrations.length,
+                  serviceTokenRefsRead: services.length,
+                  envVarsEmitted: (output.envLocal.match(/^NEXT_PUBLIC_[A-Z0-9_]+=.+$/m) ? output.envLocal.match(/^NEXT_PUBLIC_[A-Z0-9_]+=.+$/gm) ?? [] : []).length
+                }
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/tools/list-specs.ts
+import { z as z23 } from "zod";
+import { readdirSync as readdirSync6, readFileSync as readFileSync13, statSync, existsSync as existsSync13 } from "fs";
+import { join as join14, extname, basename as basename2 } from "path";
 var STRIP_SUFFIXES = ["-openapi", "-asyncapi", "-api", "-spec"];
 var ALLOWED_EXTS = /* @__PURE__ */ new Set([".yaml", ".yml", ".json"]);
 function deriveIntegrationName(fileName) {
@@ -7486,18 +7616,18 @@ function detectFormat(snippet) {
 }
 function handleListSpecs(input) {
   const { projectRoot } = input;
-  const specsDir = join13(projectRoot, "specs");
+  const specsDir = join14(projectRoot, "specs");
   const empty = { projectRoot, specs: [], totalCount: 0 };
-  if (!existsSync12(specsDir)) return empty;
+  if (!existsSync13(specsDir)) return empty;
   let entries;
   try {
-    entries = readdirSync5(specsDir);
+    entries = readdirSync6(specsDir);
   } catch {
     return empty;
   }
   const specs = [];
   for (const entry of entries) {
-    const fullPath = join13(specsDir, entry);
+    const fullPath = join14(specsDir, entry);
     let stat;
     try {
       stat = statSync(fullPath);
@@ -7508,7 +7638,7 @@ function handleListSpecs(input) {
     if (!ALLOWED_EXTS.has(extname(entry).toLowerCase())) continue;
     let snippet = "";
     try {
-      snippet = readFileSync12(fullPath, "utf-8").slice(0, 2048);
+      snippet = readFileSync13(fullPath, "utf-8").slice(0, 2048);
     } catch {
     }
     specs.push({
@@ -7527,7 +7657,7 @@ function registerListSpecsTool(server2) {
     "stackwright_pro_list_specs",
     "Enumerate OpenAPI/AsyncAPI specs in the project's specs/ directory. Returns one entry per spec with integration name (derived from filename), detected format, and size. Used by the foreman to fan out the api phase with one api-otter invocation per spec.",
     {
-      projectRoot: z22.string().describe("Absolute path to the project root directory")
+      projectRoot: z23.string().describe("Absolute path to the project root directory")
     },
     async ({ projectRoot }) => {
       const result = handleListSpecs({ projectRoot });
@@ -7544,6 +7674,7 @@ var package_default = {
     "@modelcontextprotocol/sdk": "^1.10.0",
     "@stackwright/cli": "^0.9.0",
     "@stackwright-pro/auth-nextjs": "workspace:*",
+    "@stackwright-pro/emitters": "workspace:*",
     "@stackwright-pro/cli-data-explorer": "workspace:*",
     "@stackwright-pro/openapi": "workspace:*",
     "@stackwright-pro/pulse": "workspace:*",
@@ -7571,7 +7702,7 @@ var package_default = {
     "test:coverage": "vitest run --coverage"
   },
   name: "@stackwright-pro/mcp",
-  version: "0.2.0-alpha.101",
+  version: "0.2.0-alpha.102",
   description: "MCP tools for Stackwright Pro - Data Explorer, Security, ISR, and Dashboard generation",
   license: "SEE LICENSE IN LICENSE",
   main: "./dist/server.js",
@@ -7651,6 +7782,7 @@ registerScaffoldCleanupTools(server);
 registerContrastTools(server);
 registerCompileTools(server);
 registerStripLegacyIntegrationsTool(server);
+registerEmitterTools(server);
 registerListSpecsTool(server);
 registerContentTypeTools(server);
 registerPageTools(server);