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

package/dist/server.js

@@ -580,7 +580,7 @@ function registerDashboardTools(server2) {
         yamlLines.push(`          header: Status`);
         yamlLines.push(`          type: badge`);
       }
-      const yaml = yamlLines.join("\n");
+      const yaml2 = yamlLines.join("\n");
       return {
         content: [
           {
@@ -590,7 +590,7 @@ function registerDashboardTools(server2) {
 Layout: ${layout}
 
 \`\`\`yaml
-${yaml}
+${yaml2}
 \`\`\`
 
 \u{1F4A1} Add this to pages/dashboard/content.yml and validate with stackwright_validate_pages.`
@@ -671,7 +671,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: [
           {
@@ -679,7 +679,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.`
@@ -2451,7 +2451,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,
@@ -2461,7 +2461,7 @@ function handleValidateYamlFragment(input) {
   const name = schemaName;
   let parsed;
   try {
-    parsed = (0, import_js_yaml.load)(yaml);
+    parsed = (0, import_js_yaml.load)(yaml2);
   } catch (err) {
     return {
       valid: false,
@@ -2487,8 +2487,8 @@ function registerValidateYamlFragmentTool(server2) {
       ),
       yaml: import_zod11.z.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) }]
       };
@@ -2963,7 +2963,8 @@ function defaultPhaseStatus() {
     answered: false,
     executed: false,
     artifactWritten: false,
-    retryCount: 0
+    retryCount: 0,
+    inFlight: false
   };
 }
 function createDefaultState() {
@@ -3080,7 +3081,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({
@@ -4139,6 +4146,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 {
@@ -4195,7 +4210,8 @@ function registerPipelineTools(server2) {
     `Atomic read\u2192modify\u2192write pipeline state. ${DESC}`,
     {
       phase: import_zod13.z.string().optional().describe('Phase to update, e.g. "designer"'),
-      field: import_zod13.z.enum(["questionsCollected", "answered", "executed", "artifactWritten"]).optional().describe("Boolean field to set"),
+      field: import_zod13.z.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(import_zod13.z.boolean().optional()).describe(
         'Value for the field \u2014 must be a JSON boolean (true/false), NOT the string "true"/"false"'
       ),
@@ -4207,7 +4223,13 @@ function registerPipelineTools(server2) {
         import_zod13.z.array(
           import_zod13.z.object({
             phase: import_zod13.z.string(),
-            field: import_zod13.z.enum(["questionsCollected", "answered", "executed", "artifactWritten"]),
+            field: import_zod13.z.enum([
+              "questionsCollected",
+              "answered",
+              "executed",
+              "artifactWritten",
+              "inFlight"
+            ]),
             value: import_zod13.z.boolean()
           })
         ).optional()
@@ -4331,7 +4353,15 @@ function registerPipelineTools(server2) {
     "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}`,
     {
-      type: import_zod13.z.enum(["phase_start", "phase_complete", "agent_invoke_start", "agent_invoke_complete"]).describe("Event type to emit"),
+      type: import_zod13.z.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: import_zod13.z.string().optional().describe("Current phase name"),
       targetOtter: import_zod13.z.string().optional().describe("For agent_invoke_* events: which otter is being invoked"),
       success: boolCoerce(import_zod13.z.boolean().optional()).describe(
@@ -4442,7 +4472,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.
@@ -5757,7 +5797,7 @@ var import_path9 = require("path");
 var _checksums = /* @__PURE__ */ new Map([
   [
     "stackwright-pro-api-otter.json",
-    "175cca39127beea84ed8f1b264b8cd5cf58733db050d32328c039cca0cf0b981"
+    "a5ff25531c330289af89e433e696ba1ffef8f7ea09985a559cf915592c9734ad"
   ],
   [
     "stackwright-pro-auth-otter.json",
@@ -5765,7 +5805,7 @@ var _checksums = /* @__PURE__ */ new Map([
   ],
   [
     "stackwright-pro-dashboard-otter.json",
-    "6918b51d1007c69e635f252b20b82774fa7c942fa1d2399769c14f8d1df4df70"
+    "f8d594b14e05efea30cf253052d7c7df3e8c4174d739be4cd33f9c96cecdc451"
   ],
   [
     "stackwright-pro-data-otter.json",
@@ -5781,7 +5821,7 @@ var _checksums = /* @__PURE__ */ new Map([
   ],
   [
     "stackwright-pro-foreman-otter.json",
-    "9191e176241c15f3d77180e1b843cc3a517b708737b5bd3cda7db62f2d6675d1"
+    "c23436769a9db06fa6f9d312b4fdd8b2cef6646461020eeaf227303350073593"
   ],
   [
     "stackwright-pro-form-wizard-otter.json",
@@ -5797,7 +5837,7 @@ var _checksums = /* @__PURE__ */ new Map([
   ],
   [
     "stackwright-pro-polish-otter.json",
-    "9d0c53651b60507607efc0d9a0f9d166bf5ae8571f1645682e0b151d42c276ab"
+    "fd8f8963266c6179eebf8eac4f656e8274aa3a721e5296abdbde5b00ad8a2297"
   ],
   [
     "stackwright-pro-qa-otter.json",
@@ -5805,7 +5845,7 @@ var _checksums = /* @__PURE__ */ new Map([
   ],
   [
     "stackwright-pro-scaffold-otter.json",
-    "5756ea77178334684b4df1d9d3395bca62cedb4991ab07dc4cf61aa7e540ea14"
+    "92930c732547c90a19e89ee0e25b5f037b7366f770941f0a01e148ff240a1b6d"
   ],
   [
     "stackwright-pro-theme-otter.json",
@@ -7448,14 +7488,191 @@ function registerStripLegacyIntegrationsTool(server2) {
   );
 }
 
-// src/tools/list-specs.ts
+// src/tools/emitters.ts
 var import_zod22 = require("zod");
 var import_fs14 = require("fs");
 var import_path14 = require("path");
+var import_js_yaml3 = __toESM(require("js-yaml"));
+var import_emitters = require("@stackwright-pro/emitters");
+function readIntegrations(cwd) {
+  const filePath = (0, import_path14.join)(cwd, "stackwright.integrations.yml");
+  if (!(0, import_fs14.existsSync)(filePath)) return [];
+  try {
+    const raw = import_js_yaml3.default.load((0, import_fs14.readFileSync)(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 = (0, import_path14.join)(cwd, "services");
+  if (!(0, import_fs14.existsSync)(servicesDir)) return [];
+  try {
+    const files = (0, import_fs14.readdirSync)(servicesDir).filter((f) => f.endsWith(".yml") || f.endsWith(".yaml"));
+    const refs = [];
+    for (const file of files) {
+      try {
+        const raw = import_js_yaml3.default.load(
+          (0, import_fs14.readFileSync)((0, import_path14.join)(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 ENV_LOCAL_DESC = "Returns { envLocal, envLocalExample } as JSON. The otter writes both files via stackwright_pro_safe_write.";
+var PROVIDERS_DESC = "Returns { providersFile } as JSON. The otter writes the file via stackwright_pro_safe_write.";
+var PORTS_DESC = "Returns { ports } as JSON \u2014 map of integration name \u2192 port number.";
+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. ${ENV_LOCAL_DESC}`,
+    {
+      cwd: import_zod22.z.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 = (0, import_emitters.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
+            )
+          }
+        ]
+      };
+    }
+  );
+  server2.tool(
+    "stackwright_pro_emit_providers_file",
+    `Emit app/_components/providers.tsx from stackwright.integrations.yml. Deterministic emitter \u2014 uses LITERAL env access per integration so Next.js can inline NEXT_PUBLIC_* vars at build time. Also registers the map provider (default: Cesium for Pro). 
+
+\u26A0\uFE0F CRITICAL: DO NOT compose providers.tsx by hand. Computed env access (process.env[varName]) returns undefined in browser bundles for NEXT_PUBLIC_* vars \u2014 this silently drops all auth headers and causes 401s on every integration.
+
+Workflow:
+  1. stackwright_pro_emit_providers_file({ cwd, mapProvider: 'cesium' }) \u2192 { providersFile }
+  2. stackwright_pro_safe_write({ filePath: 'app/_components/providers.tsx', content: providersFile, ... })
+
+mapProvider options:
+  - 'cesium' (default for Pro): 3D globe + terrain, @stackwright-pro/cesium + cesium peer dep
+  - 'maplibre': free-tier 2D maps, no API key \u2014 OSS-style 2D dashboards only (opt-out)
+  - 'none': skip map registration (ONLY if no pages use map content_items)
+
+This is the second concrete instance of the swp-zf9y deterministic emitter pattern. Refs: swp-57ku, swp-2m89, swp-zf9y, drawer 957. ${PROVIDERS_DESC}`,
+    {
+      cwd: import_zod22.z.string().describe("Absolute path to the project root containing stackwright.integrations.yml"),
+      mapProvider: import_zod22.z.enum(["maplibre", "cesium", "none"]).optional().describe(
+        "Map provider to register (default: cesium for Pro \u2014 3D globe + terrain). Use maplibre for OSS-style 2D dashboards (explicit opt-out). Use none if pages have no map content_items."
+      )
+    },
+    async ({ cwd, mapProvider }) => {
+      const integrations = readIntegrations(cwd);
+      const providersFile = (0, import_emitters.emitProvidersFile)({ integrations, mapProvider });
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                providersFile,
+                meta: {
+                  integrationsRead: integrations.length,
+                  integrationsWithAuth: integrations.filter((i) => i.auth?.envVar).length,
+                  mapProvider: mapProvider ?? "cesium"
+                }
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  );
+  server2.tool(
+    "stackwright_pro_emit_mock_ports",
+    `Emit mock backend port assignments from stackwright.integrations.yml. Deterministic emitter \u2014 assigns consecutive ports starting at 4011 to each integration in declaration order. Skipped integrations (skipMockPort=true) are omitted and do not consume a port number.
+
+\u26A0\uFE0F DO NOT pick mockUrl port numbers yourself. Port collisions occur when different models pick different defaults (Opus always picked 4010 for all integrations in run-4).
+
+Workflow:
+  1. stackwright_pro_emit_mock_ports({ cwd }) \u2192 { ports }
+  2. For each integration, set mockUrl to http://localhost:<ports[name]>
+  3. Write stackwright.integrations.yml via stackwright_pro_safe_write
+
+This is the third concrete instance of the swp-zf9y deterministic emitter pattern. Refs: swp-phkh, swp-zf9y. ${PORTS_DESC}`,
+    {
+      cwd: import_zod22.z.string().describe("Absolute path to the project root containing stackwright.integrations.yml")
+    },
+    async ({ cwd }) => {
+      const integrations = readIntegrations(cwd);
+      const { ports } = (0, import_emitters.emitMockPorts)({ integrations });
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                ports,
+                meta: {
+                  integrationsRead: integrations.length,
+                  portsAssigned: Object.keys(ports).length,
+                  portRange: Object.keys(ports).length > 0 ? `${Math.min(...Object.values(ports))}\u2013${Math.max(...Object.values(ports))}` : "none"
+                }
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/tools/list-specs.ts
+var import_zod23 = require("zod");
+var import_fs15 = require("fs");
+var import_path15 = require("path");
 var STRIP_SUFFIXES = ["-openapi", "-asyncapi", "-api", "-spec"];
 var ALLOWED_EXTS = /* @__PURE__ */ new Set([".yaml", ".yml", ".json"]);
 function deriveIntegrationName(fileName) {
-  let name = (0, import_path14.basename)(fileName, (0, import_path14.extname)(fileName));
+  let name = (0, import_path15.basename)(fileName, (0, import_path15.extname)(fileName));
   for (const suffix of STRIP_SUFFIXES) {
     if (name.endsWith(suffix)) {
       name = name.slice(0, -suffix.length);
@@ -7473,29 +7690,29 @@ function detectFormat(snippet) {
 }
 function handleListSpecs(input) {
   const { projectRoot } = input;
-  const specsDir = (0, import_path14.join)(projectRoot, "specs");
+  const specsDir = (0, import_path15.join)(projectRoot, "specs");
   const empty = { projectRoot, specs: [], totalCount: 0 };
-  if (!(0, import_fs14.existsSync)(specsDir)) return empty;
+  if (!(0, import_fs15.existsSync)(specsDir)) return empty;
   let entries;
   try {
-    entries = (0, import_fs14.readdirSync)(specsDir);
+    entries = (0, import_fs15.readdirSync)(specsDir);
   } catch {
     return empty;
   }
   const specs = [];
   for (const entry of entries) {
-    const fullPath = (0, import_path14.join)(specsDir, entry);
+    const fullPath = (0, import_path15.join)(specsDir, entry);
     let stat;
     try {
-      stat = (0, import_fs14.statSync)(fullPath);
+      stat = (0, import_fs15.statSync)(fullPath);
     } catch {
       continue;
     }
     if (!stat.isFile()) continue;
-    if (!ALLOWED_EXTS.has((0, import_path14.extname)(entry).toLowerCase())) continue;
+    if (!ALLOWED_EXTS.has((0, import_path15.extname)(entry).toLowerCase())) continue;
     let snippet = "";
     try {
-      snippet = (0, import_fs14.readFileSync)(fullPath, "utf-8").slice(0, 2048);
+      snippet = (0, import_fs15.readFileSync)(fullPath, "utf-8").slice(0, 2048);
     } catch {
     }
     specs.push({
@@ -7514,7 +7731,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: import_zod22.z.string().describe("Absolute path to the project root directory")
+      projectRoot: import_zod23.z.string().describe("Absolute path to the project root directory")
     },
     async ({ projectRoot }) => {
       const result = handleListSpecs({ projectRoot });
@@ -7531,6 +7748,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:*",
@@ -7558,7 +7776,7 @@ var package_default = {
     "test:coverage": "vitest run --coverage"
   },
   name: "@stackwright-pro/mcp",
-  version: "0.2.0-alpha.101",
+  version: "0.2.0-alpha.103",
   description: "MCP tools for Stackwright Pro - Data Explorer, Security, ISR, and Dashboard generation",
   license: "SEE LICENSE IN LICENSE",
   main: "./dist/server.js",
@@ -7625,6 +7843,7 @@ registerScaffoldCleanupTools(server);
 registerContrastTools(server);
 registerCompileTools(server);
 registerStripLegacyIntegrationsTool(server);
+registerEmitterTools(server);
 registerListSpecsTool(server);
 (0, import_register.registerContentTypeTools)(server);
 (0, import_register.registerPageTools)(server);