@jstn-sdk/ma 0.1.12 → 0.14.0

package/src/mcp-live-client.js

@@ -1,3 +1,105 @@
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { maskSensitiveText } from "./runtime/redaction-gateway.js";
+
+const packageMetadata = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+);
+
+export function resolveMcpClientVersion(metadata) {
+  return typeof metadata?.version === "string" && metadata.version.trim()
+    ? metadata.version
+    : "0.0.0-dev";
+}
+
+export const mcpClientVersion = resolveMcpClientVersion(packageMetadata);
+
+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;
+const BRIDGE_POLICY_PATH = path.join("mcp", "bridge.json");
+
+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],
+      spawn,
+      getMcpBridgeConfiguration(),
+    );
+  }
+
+  return new McpSseClient(endpoint);
+}
+
+export function getMcpBridgeConfiguration(root = process.env.MA_ROOT ?? process.cwd()) {
+  const allowedCommands = new Set(
+    (process.env.MA_MCP_REMOTE_BRIDGE_ALLOWLIST ?? "")
+      .split(",")
+      .map((value) => value.trim())
+      .filter(Boolean),
+  );
+  const configPath = path.join(root, BRIDGE_POLICY_PATH);
+  try {
+    const config = JSON.parse(readFileSync(configPath, "utf8"));
+    for (const command of config.allowedCommands ?? []) {
+      if (typeof command === "string" && command.trim()) allowedCommands.add(command.trim());
+    }
+    return {
+      configured: true,
+      configPath,
+      allowedCommands: [...allowedCommands],
+      source: "environment+project",
+    };
+  } catch {
+    return {
+      configured: true,
+      configPath,
+      allowedCommands: [...allowedCommands],
+      source: allowedCommands.size > 0 ? "environment" : "none",
+    };
+  }
+}
+
 export class McpSseClient {
   constructor(baseUrl) {
     this.baseUrl = baseUrl;
@@ -17,6 +119,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 +132,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 +144,7 @@ export class McpSseClient {
       capabilities: {},
       clientInfo: {
         name: "meta-architect",
-        version: "0.1.12-dev",
+        version: mcpClientVersion,
       },
     });
 
@@ -52,7 +158,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 +277,319 @@ export class McpSseClient {
   }
 }
 
+export class McpStdioBridgeClient {
+  constructor(endpoint, commandTemplate, spawnImpl = spawn, bridgeConfiguration = {}) {
+    this.endpoint = endpoint;
+    this.commandTemplate = commandTemplate;
+    this.spawnImpl = spawnImpl;
+    this.bridgeConfiguration = bridgeConfiguration;
+    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.bridgeConfiguration,
+    );
+    this.child = this.spawnImpl(command, args, {
+      stdio: ["pipe", "pipe", "pipe"],
+      env: buildBridgeEnv(),
+    });
+    await writeBridgeReceipt(this.endpoint, command, args, {
+      status: "started",
+      pid: this.child.pid ?? null,
+    });
+
+    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;
+      void writeBridgeReceipt(this.endpoint, command, args, {
+        status: "failed",
+        error: error.message,
+      });
+      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;
+      void writeBridgeReceipt(this.endpoint, command, args, {
+        status: "exited",
+        code,
+        signal,
+        stderr: this.stderr,
+      });
+      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: mcpClientVersion,
+      },
+    });
+
+    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, bridgeConfiguration = {}) {
+  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;
+  const allowedCommands = new Set(bridgeConfiguration.allowedCommands ?? []);
+  const commandName = path.basename(command);
+  if (!allowedCommands.has(command) && !allowedCommands.has(commandName)) {
+    throw new Error(
+      `${BRIDGE_COMMAND_ENV} command is not allowlisted: ${command}. ` +
+        "Add its exact command or basename to MA_MCP_REMOTE_BRIDGE_ALLOWLIST or mcp/bridge.json.",
+    );
+  }
+  return { command, args };
+}
+
+async function writeBridgeReceipt(endpoint, command, args, details) {
+  const root = process.env.MA_ROOT ?? process.cwd();
+  const receiptDir = path.join(root, ".ma", "evidence", "mcp-bridge-receipts");
+  const safeError = details.error
+    ? maskSensitiveText(String(details.error)).sanitizedText
+    : undefined;
+  const safeStderr = details.stderr
+    ? maskSensitiveText(String(details.stderr)).sanitizedText
+    : undefined;
+  await fs.mkdir(receiptDir, { recursive: true }).catch(() => {});
+  await fs
+    .writeFile(
+      path.join(receiptDir, `bridge-${Date.now()}-${process.pid}.json`),
+      `${JSON.stringify(
+        {
+          schemaVersion: "0.1.0",
+          record_type: "mcp_bridge_receipt",
+          generatedAt: new Date().toISOString(),
+          endpoint,
+          command,
+          args,
+          ...details,
+          ...(safeError ? { error: safeError } : {}),
+          ...(safeStderr ? { stderr: safeStderr } : {}),
+        },
+        null,
+      )}\n`,
+      { mode: 0o600 },
+    )
+    .catch(() => {});
+}
+
+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;
+}
+
+function buildBridgeEnv() {
+  const passthroughKeys = new Set([
+    "PATH",
+    "HOME",
+    "USERPROFILE",
+    "TMPDIR",
+    "TMP",
+    "TEMP",
+    "LANG",
+    "LC_ALL",
+    "SYSTEMROOT",
+    "COMSPEC",
+    "MA_ROOT",
+  ]);
+  const env = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (passthroughKeys.has(key)) {
+      env[key] = value;
+    }
+  }
+  return env;
+}
+
 export function parseSseEvent(rawEvent) {
   const event = { event: "message", data: "" };
   for (const line of rawEvent.split("\n")) {

package/src/paths.js

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -6,7 +7,11 @@ const __dirname = path.dirname(__filename);
 
 export const packageRoot = path.resolve(__dirname, "..");
 export function getRepoRoot() {
-  return process.env.MA_ROOT ? path.resolve(process.env.MA_ROOT) : process.cwd();
+  const root = process.env.MA_ROOT ? path.resolve(process.env.MA_ROOT) : process.cwd();
+  if (fs.realpathSync(root) !== root) {
+    throw new Error(`Repository root cannot traverse symlinks: ${root}`);
+  }
+  return root;
 }
 
 export function getRuntimeRoot() {
@@ -45,6 +50,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

@@ -1,5 +1,5 @@
 export function validateReleaseOrigin(originBranch) {
-  if (originBranch === "development") {
+  if (originBranch === "dev") {
     return true;
   }
 
@@ -15,9 +15,9 @@ export function rejectsDirectProdPromotion(originBranch) {
 }
 
 export function validateMergeTarget(sourceBranch, targetBranch) {
-  return sourceBranch.startsWith("feature/") && targetBranch === "development";
+  return sourceBranch.startsWith("feature/") && targetBranch === "dev";
 }
 
 export function canMarkBuildDone(releaseState) {
-  return ["READY", "RUNNING"].includes(releaseState.build_status);
+  return releaseState.build_status === "DONE";
 }

package/src/prelaunch.js

@@ -0,0 +1,189 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { stdin as input, stdout as output } from "node:process";
+import readline from "node:readline/promises";
+import { agentRegistry, detectInstalled, listAgents } from "./agents.js";
+import {
+  createSkillCompatibilityPayload,
+  writeSkillCompatibilityExport,
+} from "./runtime/skills-registry-export.js";
+import { ensureSkillsInstalled, ensureSupportBundleInstalled } from "./skill-installer.js";
+
+const selectionFile = ".ma/prelaunch.json";
+const projectSignals = {
+  codex: [".codex", "AGENTS.md"],
+  opencode: [".opencode"],
+  "gemini-cli": [".gemini", "GEMINI.md"],
+  amp: [".amp"],
+  cursor: [".cursor"],
+  windsurf: [".windsurf"],
+  cline: [".cline"],
+  continue: [".continue"],
+  roo: [".roo"],
+  "kiro-cli": [".kiro"],
+  junie: [".junie"],
+};
+const globalSignals = {
+  codex: ["~/.codex"],
+  opencode: ["~/.config/opencode"],
+  "gemini-cli": ["~/.gemini"],
+  amp: ["~/.config/agents"],
+  cursor: ["~/.cursor"],
+  windsurf: ["~/.codeium/windsurf"],
+  cline: ["~/.cline"],
+  continue: ["~/.continue"],
+  roo: ["~/.roo"],
+  "kiro-cli": ["~/.kiro"],
+  junie: ["~/.junie"],
+};
+
+function expandHome(value) {
+  return value.startsWith("~/") ? path.join(os.homedir(), value.slice(2)) : value;
+}
+
+async function exists(target) {
+  try {
+    await fs.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function detectPrelaunchTargets(cwd = process.cwd()) {
+  const targets = listAgents().map((agent) => {
+    const definition = agentRegistry[agent.id];
+    const projectPath =
+      definition?.isUniversal && agent.id === "universal"
+        ? path.join(cwd, ".agents")
+        : path.join(cwd, agent.skillsDir);
+    const globalPath = expandHome(agent.globalSkillsDir);
+    return {
+      id: agent.id,
+      displayName: agent.displayName,
+      surface: agent.surface,
+      project: projectPath,
+      global: globalPath,
+      projectSignals: (projectSignals[agent.id] ?? []).map((signal) => path.join(cwd, signal)),
+      globalSignals: (globalSignals[agent.id] ?? []).map(expandHome),
+      projectDetected: false,
+      globalDetected: false,
+    };
+  });
+
+  for (const target of targets) {
+    const installed = target.surface === "cli" && detectInstalled(target.id).installed;
+    target.projectDetected =
+      (target.id === "universal" && (await exists(target.project))) ||
+      (await Promise.all(target.projectSignals.map(exists))).some(Boolean);
+    target.globalDetected =
+      installed ||
+      (target.id === "universal" && (await exists(target.global))) ||
+      (await Promise.all(target.globalSignals.map(exists))).some(Boolean);
+    delete target.projectSignals;
+    delete target.globalSignals;
+  }
+  return targets;
+}
+
+async function readSelection(cwd) {
+  try {
+    const value = JSON.parse(await fs.readFile(path.join(cwd, selectionFile), "utf8"));
+    if (
+      (value.scope === "project" || value.scope === "global") &&
+      Array.isArray(value.targets) &&
+      value.targets.every((target) => typeof target === "string" && agentRegistry[target])
+    ) {
+      return value;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+export async function choosePrelaunchInstall({
+  cwd = process.cwd(),
+  interactive = Boolean(input.isTTY && output.isTTY),
+} = {}) {
+  if (!interactive || process.env.MA_SKIP_PRELAUNCH === "1") return null;
+  const previous = await readSelection(cwd);
+  if (previous) return previous;
+
+  const detected = await detectPrelaunchTargets(cwd);
+  const detectedIds = detected
+    .filter((target) => target.projectDetected || target.globalDetected)
+    .map((target) => target.id);
+  const suggested = detectedIds.length > 0 ? detectedIds : ["codex"];
+  console.log("Meta-Architect pre-launch setup");
+  console.log("Detected targets:");
+  for (const target of detected) {
+    if (target.projectDetected || target.globalDetected) {
+      console.log(`- ${target.id}: ${target.projectDetected ? "project" : "user"}`);
+    }
+  }
+  const rl = readline.createInterface({ input, output });
+  try {
+    const answer = await rl.question(
+      `Install scope and targets [project:${suggested.join(",")}]: `,
+    );
+    const value = answer.trim() || `project:${suggested.join(",")}`;
+    const [scope, targetValue] = value.split(":", 2);
+    const targets = (targetValue || "codex")
+      .split(",")
+      .map((target) => target.trim())
+      .filter((target, index, values) => agentRegistry[target] && values.indexOf(target) === index);
+    if (!(scope === "project" || scope === "global") || targets.length === 0) {
+      throw new Error("Use project:codex,cursor or global:codex,cursor");
+    }
+    return { schemaVersion: "0.1.0", scope, targets };
+  } finally {
+    rl.close();
+  }
+}
+
+export async function installPrelaunchSelection(selection, cwd = process.cwd()) {
+  if (
+    !selection ||
+    !["project", "global"].includes(selection.scope) ||
+    !Array.isArray(selection.targets) ||
+    selection.targets.length === 0 ||
+    selection.targets.some((target) => typeof target !== "string" || !agentRegistry[target])
+  ) {
+    throw new Error("Invalid pre-launch selection");
+  }
+  const payload = createSkillCompatibilityPayload({
+    name: "meta-architect",
+    description: "Meta-Architect host compatibility entrypoint.",
+    capabilities: ["maestro", "agent-compatibility"],
+  });
+  const results = [];
+  if (selection.targets.includes("codex")) {
+    const skillsRoot =
+      selection.scope === "global" ? undefined : path.join(cwd, ".agents", "skills");
+    const supportRoot =
+      selection.scope === "global" ? undefined : path.join(cwd, ".ma", "support-bundle");
+    results.push(
+      await ensureSkillsInstalled({ targetRoot: skillsRoot }),
+      await ensureSupportBundleInstalled({ targetRoot: supportRoot }),
+    );
+  }
+  for (const target of selection.targets) {
+    if (selection.scope === "global" && target === "codex") continue;
+    results.push(
+      await writeSkillCompatibilityExport({
+        payload,
+        agentType: target,
+        cwd,
+        global: selection.scope === "global",
+        agentRootExists: true,
+      }),
+    );
+  }
+  await fs.mkdir(path.join(cwd, ".ma"), { recursive: true });
+  await fs.writeFile(path.join(cwd, selectionFile), `${JSON.stringify(selection, null, 2)}\n`, {
+    mode: 0o600,
+  });
+  return { selection, results };
+}