@jstn-sdk/ma 0.1.13 → 0.14.1

package/src/mcp-live-client.js

@@ -1,9 +1,26 @@
-import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { safeSpawn } from "./process-utils.js";
+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();
@@ -43,12 +60,46 @@ export function hasConfiguredMcpRemoteBridge() {
 
 export function createMcpLiveClient(endpoint) {
   if (hasConfiguredMcpRemoteBridge()) {
-    return new McpStdioBridgeClient(endpoint, process.env[BRIDGE_COMMAND_ENV]);
+    return new McpStdioBridgeClient(
+      endpoint,
+      process.env[BRIDGE_COMMAND_ENV],
+      safeSpawn,
+      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;
@@ -93,7 +144,7 @@ export class McpSseClient {
       capabilities: {},
       clientInfo: {
         name: "meta-architect",
-        version: "0.1.13-dev",
+        version: mcpClientVersion,
       },
     });
 
@@ -227,10 +278,11 @@ export class McpSseClient {
 }
 
 export class McpStdioBridgeClient {
-  constructor(endpoint, commandTemplate, spawnImpl = spawn) {
+  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();
@@ -240,10 +292,18 @@ export class McpStdioBridgeClient {
   }
 
   async connect() {
-    const { command, args } = buildBridgeCommand(this.commandTemplate, this.endpoint);
+    const { command, args } = buildBridgeCommand(
+      this.commandTemplate,
+      this.endpoint,
+      this.bridgeConfiguration,
+    );
     this.child = this.spawnImpl(command, args, {
       stdio: ["pipe", "pipe", "pipe"],
-      env: process.env,
+      env: buildBridgeEnv(),
+    });
+    await writeBridgeReceipt(this.endpoint, command, args, {
+      status: "started",
+      pid: this.child.pid ?? null,
     });
 
     this.child.stdout.setEncoding("utf8");
@@ -254,6 +314,10 @@ export class McpStdioBridgeClient {
     });
     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}`));
       }
@@ -261,6 +325,12 @@ export class McpStdioBridgeClient {
     });
     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}`;
@@ -275,7 +345,7 @@ export class McpStdioBridgeClient {
       capabilities: {},
       clientInfo: {
         name: "meta-architect",
-        version: "0.1.13-dev",
+        version: mcpClientVersion,
       },
     });
 
@@ -373,7 +443,7 @@ export class McpStdioBridgeClient {
   }
 }
 
-function buildBridgeCommand(commandTemplate, endpoint) {
+function buildBridgeCommand(commandTemplate, endpoint, bridgeConfiguration = {}) {
   const template = commandTemplate?.trim();
   if (!template) {
     throw new Error(`${BRIDGE_COMMAND_ENV} is empty`);
@@ -390,9 +460,49 @@ function buildBridgeCommand(commandTemplate, 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);
@@ -457,6 +567,29 @@ function splitCommand(command) {
   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() {

package/src/policy.js

@@ -1,5 +1,5 @@
 export function validateReleaseOrigin(originBranch) {
-  if (originBranch === "development") {
+  if (originBranch === "dev") {
     return true;
   }
 
@@ -15,7 +15,7 @@ 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) {

package/src/prelaunch.js

@@ -0,0 +1,223 @@
+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 { Agents } from "@jstn-sdk/agents";
+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.scope === "project" && selection.targets.includes("cursor")) {
+    results.push(await ensureSkillsInstalled({ targetRoot: path.join(cwd, ".agents", "skills") }));
+    results.push(
+      await Agents.compile(
+        {
+          version: 1,
+          project: { name: path.basename(path.resolve(cwd)) },
+          instructions: [
+            "Use Meta-Architect lanes for architecture, evidence, review, and gated build work.",
+            "Run `ma run '$maestro'` when the host supports shell execution, or invoke /maestro in Cursor Agent.",
+          ],
+        },
+        { targets: ["cursor"], output: cwd },
+      ),
+    );
+  }
+  if (selection.scope === "project" && selection.targets.includes("claude-code")) {
+    results.push(await ensureSkillsInstalled({ targetRoot: path.join(cwd, ".claude", "skills") }));
+    results.push(
+      await Agents.compile(
+        {
+          version: 1,
+          project: { name: path.basename(path.resolve(cwd)) },
+          instructions: [
+            "Use Meta-Architect lanes for architecture, evidence, review, and gated build work.",
+            "Invoke /maestro to run the autonomous Meta-Architect manager in Claude Code.",
+          ],
+        },
+        { targets: ["claude-code"], output: cwd },
+      ),
+    );
+  }
+  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,
+        renderAgentType: selection.targets.length > 1 ? "generic" : 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 };
+}

package/src/process-utils.js

@@ -0,0 +1,62 @@
+import { execFile, execFileSync, spawn, spawnSync } from "node:child_process";
+import { promisify } from "node:util";
+
+const unsafeExecutable = /[;&|<>`$]/;
+
+export function assertSafeExecutable(command, label = "Executable") {
+  if (
+    typeof command !== "string" ||
+    command.trim() === "" ||
+    command !== command.trim() ||
+    command.includes("\0") ||
+    command.includes("\r") ||
+    command.includes("\n") ||
+    unsafeExecutable.test(command)
+  ) {
+    throw new Error(`${label} contains an unsafe executable value`);
+  }
+  return command;
+}
+
+function assertArgs(args) {
+  if (!Array.isArray(args) || args.some((arg) => typeof arg !== "string" || arg.includes("\0")))
+    throw new Error("Process arguments must be an array of strings without NUL bytes");
+}
+
+function safeOptions(options = {}) {
+  return { ...options, shell: false };
+}
+
+export function safeSpawn(command, args = [], options = {}) {
+  assertSafeExecutable(command);
+  assertArgs(args);
+  return spawn(command, args, safeOptions(options));
+}
+
+export function safeSpawnSync(command, args = [], options = {}) {
+  assertSafeExecutable(command);
+  assertArgs(args);
+  return spawnSync(command, args, safeOptions(options));
+}
+
+export function safeExecFile(command, args = [], options = {}, callback) {
+  assertSafeExecutable(command);
+  assertArgs(args);
+  if (typeof options === "function") {
+    callback = options;
+    options = {};
+  }
+  return execFile(command, args, safeOptions(options), callback);
+}
+
+export function safeExecFileSync(command, args = [], options = {}) {
+  assertSafeExecutable(command);
+  assertArgs(args);
+  return execFileSync(command, args, safeOptions(options));
+}
+
+safeExecFile[promisify.custom] = (command, args = [], options = {}) => {
+  assertSafeExecutable(command);
+  assertArgs(args);
+  return promisify(execFile)(command, args, safeOptions(options));
+};