@jstn-sdk/ma 0.1.12 → 0.1.13

package/src/mcp-live-client.js

@@ -1,3 +1,54 @@
+import { spawn } from "node:child_process";
+
+const GITMCP_ENDPOINT_PATTERN = /^https:\/\/gitmcp\.io\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const BRIDGE_COMMAND_ENV = "MA_MCP_REMOTE_BRIDGE_CMD";
+const REQUEST_TIMEOUT_ENV = "MA_MCP_REQUEST_TIMEOUT_MS";
+const DEFAULT_REQUEST_TIMEOUT_MS = 15000;
+
+function readRequestTimeoutMs() {
+  const raw = process.env[REQUEST_TIMEOUT_ENV]?.trim();
+  if (!raw) return DEFAULT_REQUEST_TIMEOUT_MS;
+
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return DEFAULT_REQUEST_TIMEOUT_MS;
+  }
+
+  return Math.max(50, Math.floor(parsed));
+}
+
+export class McpRemoteTransportRequiredError extends Error {
+  constructor(endpoint, status, bodyPreview = "") {
+    const bridgeHint =
+      `Set ${BRIDGE_COMMAND_ENV} to a trusted stdio bridge command with {url}, ` +
+      "for example a preinstalled mcp-remote wrapper, then rerun $sage.";
+    const bodyHint = bodyPreview ? ` Response preview: ${bodyPreview}` : "";
+    super(
+      `Remote MCP endpoint requires a bridge transport: ${endpoint} returned HTTP ${status}. ${bridgeHint}${bodyHint}`,
+    );
+    this.name = "McpRemoteTransportRequiredError";
+    this.endpoint = endpoint;
+    this.status = status;
+    this.bridgeEnv = BRIDGE_COMMAND_ENV;
+  }
+}
+
+export function isGitMcpEndpoint(endpoint) {
+  return GITMCP_ENDPOINT_PATTERN.test(endpoint);
+}
+
+export function hasConfiguredMcpRemoteBridge() {
+  return Boolean(process.env[BRIDGE_COMMAND_ENV]?.trim());
+}
+
+export function createMcpLiveClient(endpoint) {
+  if (hasConfiguredMcpRemoteBridge()) {
+    return new McpStdioBridgeClient(endpoint, process.env[BRIDGE_COMMAND_ENV]);
+  }
+
+  return new McpSseClient(endpoint);
+}
+
 export class McpSseClient {
   constructor(baseUrl) {
     this.baseUrl = baseUrl;
@@ -17,6 +68,10 @@ export class McpSseClient {
     });
 
     if (!response.ok || !response.body) {
+      const bodyPreview = await readResponsePreview(response);
+      if (isGitMcpEndpoint(this.baseUrl) && response.status === 405) {
+        throw new McpRemoteTransportRequiredError(this.baseUrl, response.status, bodyPreview);
+      }
       throw new Error(`Failed to open MCP SSE stream: ${response.status}`);
     }
 
@@ -26,7 +81,7 @@ export class McpSseClient {
       5000,
       "Timed out waiting for MCP endpoint event",
     );
-    if (!endpointEvent || endpointEvent.event !== "endpoint") {
+    if (endpointEvent?.event !== "endpoint") {
       throw new Error("MCP server did not provide an endpoint event");
     }
 
@@ -38,7 +93,7 @@ export class McpSseClient {
       capabilities: {},
       clientInfo: {
         name: "meta-architect",
-        version: "0.1.12-dev",
+        version: "0.1.13-dev",
       },
     });
 
@@ -52,7 +107,7 @@ export class McpSseClient {
       const timeout = setTimeout(() => {
         this.pending.delete(id);
         reject(new Error(`Timed out waiting for MCP response to ${method}`));
-      }, 15000);
+      }, readRequestTimeoutMs());
 
       this.pending.set(id, {
         resolve: (payload) => {
@@ -171,6 +226,237 @@ export class McpSseClient {
   }
 }
 
+export class McpStdioBridgeClient {
+  constructor(endpoint, commandTemplate, spawnImpl = spawn) {
+    this.endpoint = endpoint;
+    this.commandTemplate = commandTemplate;
+    this.spawnImpl = spawnImpl;
+    this.child = null;
+    this.buffer = "";
+    this.pending = new Map();
+    this.nextId = 1;
+    this.stderr = "";
+    this.closed = false;
+  }
+
+  async connect() {
+    const { command, args } = buildBridgeCommand(this.commandTemplate, this.endpoint);
+    this.child = this.spawnImpl(command, args, {
+      stdio: ["pipe", "pipe", "pipe"],
+      env: process.env,
+    });
+
+    this.child.stdout.setEncoding("utf8");
+    this.child.stderr.setEncoding("utf8");
+    this.child.stdout.on("data", (chunk) => this.#handleStdout(chunk));
+    this.child.stderr.on("data", (chunk) => {
+      this.stderr = `${this.stderr}${chunk}`.slice(-2000);
+    });
+    this.child.on("error", (error) => {
+      this.closed = true;
+      for (const [, handlers] of this.pending) {
+        handlers.reject(new Error(`MCP bridge failed to start: ${error.message}`));
+      }
+      this.pending.clear();
+    });
+    this.child.on("exit", (code, signal) => {
+      this.closed = true;
+      const reason = signal
+        ? `MCP bridge exited with signal ${signal}`
+        : `MCP bridge exited with code ${code}`;
+      for (const [, handlers] of this.pending) {
+        handlers.reject(new Error(`${reason}${this.stderr ? `: ${this.stderr.trim()}` : ""}`));
+      }
+      this.pending.clear();
+    });
+
+    const initResult = await this.request("initialize", {
+      protocolVersion: "2025-03-26",
+      capabilities: {},
+      clientInfo: {
+        name: "meta-architect",
+        version: "0.1.13-dev",
+      },
+    });
+
+    await this.notify("notifications/initialized");
+    return initResult;
+  }
+
+  async request(method, params = {}) {
+    const id = this.nextId++;
+    const responsePromise = new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`Timed out waiting for MCP bridge response to ${method}`));
+      }, readRequestTimeoutMs());
+
+      this.pending.set(id, {
+        resolve: (payload) => {
+          clearTimeout(timeout);
+          resolve(payload);
+        },
+        reject: (error) => {
+          clearTimeout(timeout);
+          reject(error);
+        },
+      });
+    });
+
+    this.#send({
+      jsonrpc: "2.0",
+      id,
+      method,
+      params,
+    });
+
+    return responsePromise;
+  }
+
+  async notify(method, params = {}) {
+    this.#send({
+      jsonrpc: "2.0",
+      method,
+      params,
+    });
+  }
+
+  async close() {
+    if (!this.child || this.closed) return;
+    this.child.stdin.end();
+    this.child.kill();
+    await new Promise((resolve) => {
+      const timeout = setTimeout(resolve, 1000);
+      this.child.once("exit", () => {
+        clearTimeout(timeout);
+        resolve();
+      });
+    });
+  }
+
+  #send(message) {
+    if (!this.child?.stdin.writable) {
+      throw new Error("MCP bridge is not writable");
+    }
+    this.child.stdin.write(`${JSON.stringify(message)}\n`);
+  }
+
+  #handleStdout(chunk) {
+    this.buffer += chunk;
+    while (true) {
+      const newlineIndex = this.buffer.indexOf("\n");
+      if (newlineIndex === -1) return;
+
+      const line = this.buffer.slice(0, newlineIndex).trim();
+      this.buffer = this.buffer.slice(newlineIndex + 1);
+      if (!line?.startsWith("{")) continue;
+
+      let payload;
+      try {
+        payload = JSON.parse(line);
+      } catch {
+        continue;
+      }
+
+      if (typeof payload.id !== "number" || !this.pending.has(payload.id)) {
+        continue;
+      }
+
+      const handlers = this.pending.get(payload.id);
+      this.pending.delete(payload.id);
+      if (payload.error) {
+        handlers.reject(new Error(payload.error.message ?? "Unknown MCP bridge error"));
+      } else {
+        handlers.resolve(payload.result);
+      }
+    }
+  }
+}
+
+function buildBridgeCommand(commandTemplate, endpoint) {
+  const template = commandTemplate?.trim();
+  if (!template) {
+    throw new Error(`${BRIDGE_COMMAND_ENV} is empty`);
+  }
+
+  const parts = splitCommand(template);
+  if (parts.length === 0) {
+    throw new Error(`${BRIDGE_COMMAND_ENV} is empty`);
+  }
+
+  const substituted = parts.map((part) => part.replaceAll("{url}", endpoint));
+  if (!template.includes("{url}")) {
+    substituted.push(endpoint);
+  }
+
+  const [command, ...args] = substituted;
+  return { command, args };
+}
+
+async function readResponsePreview(response) {
+  try {
+    return (await response.text()).replace(/\s+/g, " ").trim().slice(0, 240);
+  } catch {
+    return "";
+  }
+}
+
+function splitCommand(command) {
+  const parts = [];
+  let current = "";
+  let quote = null;
+  let escaping = false;
+
+  for (const char of command) {
+    if (escaping) {
+      current += char;
+      escaping = false;
+      continue;
+    }
+
+    if (char === "\\") {
+      escaping = true;
+      continue;
+    }
+
+    if (quote) {
+      if (char === quote) {
+        quote = null;
+      } else {
+        current += char;
+      }
+      continue;
+    }
+
+    if (char === "'" || char === '"') {
+      quote = char;
+      continue;
+    }
+
+    if (/\s/.test(char)) {
+      if (current) {
+        parts.push(current);
+        current = "";
+      }
+      continue;
+    }
+
+    current += char;
+  }
+
+  if (escaping) {
+    current += "\\";
+  }
+  if (quote) {
+    throw new Error(`${BRIDGE_COMMAND_ENV} has an unterminated quote`);
+  }
+  if (current) {
+    parts.push(current);
+  }
+
+  return parts;
+}
+
 export function parseSseEvent(rawEvent) {
   const event = { event: "message", data: "" };
   for (const line of rawEvent.split("\n")) {

package/src/paths.js

@@ -45,6 +45,10 @@ export function getMcpLocalCapabilitiesPath() {
   return path.join(getMcpRootPath(), "local-capabilities.json");
 }
 
+export function getRuntimeMcpPolicyPath() {
+  return getRuntimeWritePath(".mcp.json");
+}
+
 export function getBundledNativePlaybooksPath() {
   return getBundledMcpPath("native-playbooks.json");
 }

package/src/policy.js

@@ -19,5 +19,5 @@ export function validateMergeTarget(sourceBranch, targetBranch) {
 }
 
 export function canMarkBuildDone(releaseState) {
-  return ["READY", "RUNNING"].includes(releaseState.build_status);
+  return releaseState.build_status === "DONE";
 }

package/src/release-issue-gates.js

@@ -0,0 +1,190 @@
+const ALLOWED_STATUSES = new Set(["pending", "in_progress", "blocked", "failed", "passed"]);
+const REQUIRED_PROOF_FIELDS = [
+  "implementationEvidence",
+  "verificationEvidence",
+  "productionEvidence",
+];
+
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function hasStringItems(value) {
+  return Array.isArray(value) && value.length > 0 && value.every(isNonEmptyString);
+}
+
+export function validateReleaseIssueGates(document, options = {}) {
+  const version = options.version;
+  const requirePassed = options.requirePassed ?? true;
+  const errors = [];
+
+  if (!document || typeof document !== "object" || Array.isArray(document)) {
+    return {
+      valid: false,
+      errors: ["release issue gate document must be an object"],
+    };
+  }
+
+  const expectedTag = version ? `v${version}` : document.releaseTag;
+
+  if (document.schemaVersion !== "1.0.0") {
+    errors.push("schemaVersion must be 1.0.0");
+  }
+
+  if (version && document.releaseVersion !== version) {
+    errors.push(`releaseVersion must match package version ${version}`);
+  }
+
+  if (!isNonEmptyString(document.releaseTag)) {
+    errors.push("releaseTag is required");
+  } else if (expectedTag && document.releaseTag !== expectedTag) {
+    errors.push(`releaseTag must be ${expectedTag}`);
+  }
+
+  if (document.passContract?.allIssuesMustPassProduction !== true) {
+    errors.push("passContract.allIssuesMustPassProduction must be true");
+  }
+
+  if (document.passContract?.allIssuesMustHaveLabels !== true) {
+    errors.push("passContract.allIssuesMustHaveLabels must be true");
+  }
+
+  if (!Array.isArray(document.issues) || document.issues.length === 0) {
+    errors.push("issues must be a non-empty array");
+    return { valid: errors.length === 0, errors };
+  }
+
+  const seen = new Set();
+  for (const issue of document.issues) {
+    const issueLabel = Number.isInteger(issue?.number) ? `#${issue.number}` : "<unknown issue>";
+
+    if (!Number.isInteger(issue?.number) || issue.number <= 0) {
+      errors.push(`${issueLabel}: number must be a positive integer`);
+      continue;
+    }
+
+    if (seen.has(issue.number)) {
+      errors.push(`${issueLabel}: duplicate issue number`);
+    }
+    seen.add(issue.number);
+
+    if (!isNonEmptyString(issue.title)) {
+      errors.push(`${issueLabel}: title is required`);
+    }
+
+    if (!isNonEmptyString(issue.url) || !issue.url.includes(`/issues/${issue.number}`)) {
+      errors.push(`${issueLabel}: url must reference the GitHub issue`);
+    }
+
+    if (issue.releaseVersion !== document.releaseVersion) {
+      errors.push(`${issueLabel}: releaseVersion must match document releaseVersion`);
+    }
+
+    if (issue.releaseTag !== document.releaseTag) {
+      errors.push(`${issueLabel}: releaseTag must match document releaseTag`);
+    }
+
+    if (issue.milestone !== document.releaseTag) {
+      errors.push(`${issueLabel}: milestone must match document releaseTag`);
+    }
+
+    if (!ALLOWED_STATUSES.has(issue.status)) {
+      errors.push(`${issueLabel}: invalid status ${issue.status}`);
+    }
+
+    if (document.passContract?.allIssuesMustHaveLabels === true && !hasStringItems(issue.labels)) {
+      errors.push(`${issueLabel}: labels must contain at least one issue label`);
+    }
+
+    if (!hasStringItems(issue.requiredProof)) {
+      errors.push(`${issueLabel}: requiredProof must contain at least one proof requirement`);
+    }
+
+    if (!isNonEmptyString(issue.loopAction)) {
+      errors.push(`${issueLabel}: loopAction is required until production proof passes`);
+    }
+
+    const proof = issue.proof;
+    if (!proof || typeof proof !== "object" || Array.isArray(proof)) {
+      errors.push(`${issueLabel}: proof object is required`);
+      continue;
+    }
+
+    for (const field of REQUIRED_PROOF_FIELDS) {
+      if (!Array.isArray(proof[field])) {
+        errors.push(`${issueLabel}: proof.${field} must be an array`);
+      }
+    }
+
+    if (issue.status === "passed") {
+      for (const field of REQUIRED_PROOF_FIELDS) {
+        if (!hasStringItems(proof[field])) {
+          errors.push(`${issueLabel}: status passed requires non-empty proof.${field}`);
+        }
+      }
+    }
+
+    if (requirePassed && issue.status !== "passed") {
+      errors.push(`${issueLabel}: status is ${issue.status}; continue loopAction before release`);
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+export function summarizeReleaseIssueGateStatus(document, options = {}) {
+  const structural = validateReleaseIssueGates(document, {
+    ...options,
+    requirePassed: false,
+  });
+
+  if (!structural.valid) {
+    return {
+      valid: false,
+      total: 0,
+      passed: 0,
+      pending: 0,
+      inProgress: 0,
+      blocked: 0,
+      failed: 0,
+      blockers: structural.errors,
+    };
+  }
+
+  const summary = {
+    valid: true,
+    total: document.issues.length,
+    passed: 0,
+    pending: 0,
+    inProgress: 0,
+    blocked: 0,
+    failed: 0,
+    blockers: [],
+  };
+
+  for (const issue of document.issues) {
+    if (issue.status === "passed") {
+      summary.passed += 1;
+      continue;
+    }
+
+    if (issue.status === "pending") {
+      summary.pending += 1;
+    } else if (issue.status === "in_progress") {
+      summary.inProgress += 1;
+    } else if (issue.status === "blocked") {
+      summary.blocked += 1;
+    } else if (issue.status === "failed") {
+      summary.failed += 1;
+    }
+
+    summary.blockers.push(
+      `#${issue.number}: ${issue.status}; ${issue.loopAction || "continue implementation loop"}`,
+    );
+  }
+
+  return summary;
+}