premanmcp 0.10.6 → 0.10.7

package/bin/connect/configs.js

@@ -0,0 +1,276 @@
+/**
+ * Writing PreMan into each agent's own config, and proving it landed.
+ *
+ * Every agent stores MCP servers somewhere different and one of them owns its
+ * file through a CLI, so each writer is separate and each is followed by a read
+ * back: a silently failed write must not be reported as a success. The
+ * copy-paste renderers exist for the machines where we cannot write at all.
+ */
+
+import os from "node:os";
+import path from "node:path";
+import { execFileSync, spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { LAUNCHER_ARGS, LAUNCHER_COMMAND, backendUrl, frontendUrl, onPath, readJsonFile, writeJsonFile } from "../shared.js";
+import { AGENTS } from "./agents.js";
+
+// ── Config writers ──────────────────────────────────────────────────────
+
+function cursorConfigPath(projectInstall) {
+  return projectInstall
+    ? path.join(process.cwd(), ".cursor", "mcp.json")
+    : path.join(os.homedir(), ".cursor", "mcp.json");
+}
+
+/** The `cursor-agent mcp enable` invocation, shared by the writer and tests. */
+export function cursorMcpEnableArgs(serverName) {
+  return ["mcp", "enable", serverName];
+}
+
+export function writeCursorConfig({ serverName, serverConfig, projectInstall }) {
+  const configPath = cursorConfigPath(projectInstall);
+  const config = { ...readJsonFile(configPath) };
+  config.mcpServers = { ...(config.mcpServers || {}), [serverName]: serverConfig };
+  writeJsonFile(configPath, config);
+
+  // Writing mcp.json is not enough for cursor-agent. Newly added servers stay
+  // off the CLI's approved list until `mcp enable`, so a first-time connect
+  // that then launches the agent finds only built-in tools and reports PreMan
+  // as missing. Desktop still reads the file after a restart.
+  if (onPath("cursor-agent")) {
+    try {
+      execFileSync("cursor-agent", cursorMcpEnableArgs(serverName), {
+        stdio: "pipe",
+        timeout: 15000,
+      });
+      return { path: configPath, how: "wrote and enabled" };
+    } catch (error) {
+      const detail = error?.stderr?.toString().trim() || error.message;
+      process.stdout.write(
+        `Note: cursor-agent mcp enable failed (${detail}); the server is written to ${configPath}.\n`
+      );
+    }
+  }
+  return { path: configPath, how: "wrote" };
+}
+
+/** The `claude mcp add` invocation, shared by the writer and the printed fallback. */
+export function claudeMcpAddArgs(serverName, serverConfig, projectInstall) {
+  const envArgs = Object.entries(serverConfig.env).flatMap(([k, v]) => ["--env", `${k}=${v}`]);
+  return [
+    "mcp",
+    "add",
+    serverName,
+    "--scope",
+    projectInstall ? "project" : "user",
+    ...envArgs,
+    "--",
+    serverConfig.command,
+    ...serverConfig.args,
+  ];
+}
+
+/**
+ * Claude Code owns ~/.claude.json, so prefer its own CLI. Fall back to writing
+ * the config directly when `claude` is not installed — a user can connect before
+ * installing the agent.
+ */
+export function writeClaudeConfig({ serverName, serverConfig, projectInstall }) {
+  if (onPath("claude")) {
+    const args = claudeMcpAddArgs(serverName, serverConfig, projectInstall);
+    try {
+      execFileSync("claude", args, { stdio: "pipe" });
+      return { path: projectInstall ? ".mcp.json" : "Claude Code user config", how: "registered via claude mcp add" };
+    } catch (error) {
+      const detail = error?.stderr?.toString().trim() || error.message;
+      process.stdout.write(`Note: claude mcp add failed (${detail}); writing the config directly.\n`);
+    }
+  }
+
+  if (projectInstall) {
+    const configPath = path.join(process.cwd(), ".mcp.json");
+    const config = { ...readJsonFile(configPath) };
+    config.mcpServers = { ...(config.mcpServers || {}), [serverName]: serverConfig };
+    writeJsonFile(configPath, config);
+    return { path: configPath, how: "wrote" };
+  }
+
+  // Merge only mcpServers: the user config holds a lot of unrelated state.
+  // CLAUDE_CONFIG_DIR relocates that file, and writing to ~ when it is set
+  // produces a config Claude Code never reads.
+  const configPath = path.join(process.env.CLAUDE_CONFIG_DIR || os.homedir(), ".claude.json");
+  const config = { ...readJsonFile(configPath) };
+  config.mcpServers = { ...(config.mcpServers || {}), [serverName]: serverConfig };
+  writeJsonFile(configPath, config);
+  return { path: configPath, how: "wrote" };
+}
+
+/**
+ * Render the `[mcp_servers.<name>]` block for Codex's TOML config. Only strings
+ * and string arrays appear here, so a hand-rolled writer is enough — no TOML
+ * dependency for one fixed shape.
+ */
+export function renderCodexToml(serverName, serverConfig) {
+  const str = (value) => JSON.stringify(String(value));
+  const lines = [
+    `[mcp_servers.${serverName}]`,
+    `command = ${str(serverConfig.command)}`,
+    `args = [${serverConfig.args.map(str).join(", ")}]`,
+  ];
+  const env = Object.entries(serverConfig.env);
+  if (env.length) {
+    lines.push("", `[mcp_servers.${serverName}.env]`);
+    for (const [key, value] of env) lines.push(`${key} = ${str(value)}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/** Replace an existing preman block, or append a new one, leaving the rest alone. */
+export function upsertCodexToml(existing, serverName, block) {
+  const header = new RegExp(`^\\[mcp_servers\\.${serverName}(\\.|\\])`, "m");
+  if (!header.test(existing)) {
+    const separator = existing.trim() ? "\n" : "";
+    return `${existing.trimEnd()}${separator}\n${block}`;
+  }
+
+  const lines = existing.split("\n");
+  const out = [];
+  let skipping = false;
+  for (const line of lines) {
+    const isOurHeader = new RegExp(`^\\[mcp_servers\\.${serverName}(\\.|\\])`).test(line);
+    if (isOurHeader) {
+      skipping = true;
+      continue;
+    }
+    if (skipping && /^\[/.test(line) && !isOurHeader) skipping = false;
+    if (!skipping) out.push(line);
+  }
+  return `${out.join("\n").trimEnd()}\n\n${block}`;
+}
+
+export function writeCodexConfig({ serverName, serverConfig }) {
+  const configPath = path.join(
+    process.env.CODEX_HOME || path.join(os.homedir(), ".codex"),
+    "config.toml"
+  );
+  const existing = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
+  const next = upsertCodexToml(existing, serverName, renderCodexToml(serverName, serverConfig));
+  mkdirSync(path.dirname(configPath), { recursive: true });
+  writeFileSync(configPath, next, { mode: 0o600 });
+  chmodSync(configPath, 0o600); // mode above is ignored for an existing file
+  return { path: configPath, how: "wrote" };
+}
+
+export const WRITERS = {
+  cursor: writeCursorConfig,
+  claude_code: writeClaudeConfig,
+  codex: writeCodexConfig,
+};
+
+// ── Copy-paste fallbacks ────────────────────────────────────────────────
+
+/** Quote only what a shell would otherwise mangle, so the line stays readable. */
+export function shellQuote(value) {
+  return /^[A-Za-z0-9_@%+=:,./-]+$/.test(value) ? value : `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+/** What a user would paste by hand to get exactly what the writer would have written. */
+export function renderAgentSnippet(agentId, serverName, serverConfig, { projectInstall = false } = {}) {
+  if (agentId === "codex") return renderCodexToml(serverName, serverConfig);
+  if (agentId === "claude_code") {
+    const args = claudeMcpAddArgs(serverName, serverConfig, projectInstall);
+    return `claude ${args.map(shellQuote).join(" ")}\n`;
+  }
+  return `${JSON.stringify({ mcpServers: { [serverName]: serverConfig } }, null, 2)}\n`;
+}
+
+/** Every agent's snippet, for when we could not pick one for the user. */
+export function renderAllAgentSnippets(args, serverName, { projectInstall = false } = {}) {
+  // Build config WITHOUT resolved API key to avoid leaking secrets in CI logs.
+  // Users must supply --api-key or set PREMAN_API_KEY separately.
+  const env = {
+    PREMAN_BACKEND: backendUrl(args),
+    PREMAN_FRONTEND: frontendUrl(args),
+  };
+  const serverConfig = {
+    command: LAUNCHER_COMMAND,
+    args: [...LAUNCHER_ARGS],
+    env,
+  };
+
+  return AGENTS.map((agent) => {
+    // Adjust hint based on projectInstall, matching verifyWrittenConfig logic
+    let hint = agent.snippetHint;
+    if (agent.id === "cursor" && projectInstall) {
+      hint = "merge into .cursor/mcp.json, then run: cursor-agent mcp enable " + serverName;
+    } else if (agent.id === "claude_code") {
+      hint = projectInstall ? "run (with --scope project):" : "run:";
+    }
+    return `# ${agent.label} — ${hint}\n` + renderAgentSnippet(agent.id, serverName, serverConfig, { projectInstall });
+  }).join("\n");
+}
+
+// ── Post-write validation ───────────────────────────────────────────────
+
+/** The lines belonging to our `[mcp_servers.<name>]` block, or null if absent. */
+function codexBlockLines(text, serverName) {
+  const lines = text.split("\n");
+  const start = lines.findIndex((line) => line.trim() === `[mcp_servers.${serverName}]`);
+  if (start === -1) return null;
+  const block = [];
+  for (let i = start + 1; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (/^\[/.test(line) && !line.startsWith(`[mcp_servers.${serverName}.`)) break;
+    block.push(line);
+  }
+  return block;
+}
+
+/**
+ * Read back what we just wrote, so a silently-failed write is not reported as a
+ * success. Proves the entry is on disk (or that Claude Code knows about it) —
+ * whether the agent has actually loaded it is only ever proven by a check-in.
+ *
+ * Never throws: a verification that cannot run must not fail the connect. An
+ * unreadable state reports "unknown" and stays quiet, because a wrong warning
+ * costs more trust than a missing one.
+ */
+export function verifyWrittenConfig(agent, { serverName, written }) {
+  try {
+    if (agent.id === "codex") {
+      const text = written.path && existsSync(written.path) ? readFileSync(written.path, "utf8") : "";
+      const block = codexBlockLines(text, serverName);
+      if (!block) {
+        return { status: "mismatch", detail: `no [mcp_servers.${serverName}] block in ${written.path}` };
+      }
+      if (!block.some((line) => line.trim() === `command = "${LAUNCHER_COMMAND}"`)) {
+        return {
+          status: "mismatch",
+          detail: `${written.path} does not launch ${LAUNCHER_COMMAND}`,
+        };
+      }
+      return { status: "verified" };
+    }
+
+    // Claude Code registered the server itself — ask its CLI what it ended up with.
+    if (agent.id === "claude_code" && written.how !== "wrote") {
+      const probe = spawnSync("claude", ["mcp", "get", serverName], { stdio: "ignore" });
+      if (probe.error) return { status: "unknown", detail: "could not run claude" };
+      return probe.status === 0
+        ? { status: "verified" }
+        : { status: "mismatch", detail: `claude mcp get ${serverName} did not find the server` };
+    }
+
+    const entry = readJsonFile(written.path).mcpServers?.[serverName];
+    if (!entry) return { status: "mismatch", detail: `${serverName} is missing from ${written.path}` };
+    if (entry.command !== LAUNCHER_COMMAND) {
+      return {
+        status: "mismatch",
+        detail: `${written.path} does not launch ${LAUNCHER_COMMAND}`,
+      };
+    }
+    return { status: "verified" };
+  } catch (error) {
+    return { status: "unknown", detail: error.message };
+  }
+}

package/bin/connect/dispatch.js

@@ -0,0 +1,131 @@
+/**
+ * The cloud-dispatch credential (SCRUM-124).
+ *
+ * With it PreMan can start an agent run; without it PreMan can only describe the
+ * fix. Always skippable, never able to fail a connect -- which is why it lives
+ * apart from the connect flow rather than inside it.
+ */
+
+import { callBackendJson, cliInvocation, makeArgs, promptSecret, promptText, resolveApiKey } from "../shared.js";
+import { ConnectError, EXIT_USAGE } from "./errors.js";
+import { findAgent } from "./agents.js";
+
+// ── Dispatch credential (SCRUM-124) ─────────────────────────────────────
+
+export async function captureDispatchCredential(args, agent, apiKey, { prompt = true } = {}) {
+  if (!agent.dispatch) return;
+  if (args.has("--skip-dispatch-credential")) return;
+
+  let secret = args.value("--dispatch-credential", "");
+  let routineId = args.value("--routine-id", "");
+
+  if (!secret) {
+    if (!prompt || !process.stdin.isTTY) return;
+    // Framed as the expected step rather than an optional aside. Without it
+    // PreMan can only suggest fixes; with it, it can run them. Presenting it as
+    // "optional, press Enter to skip" meant almost everyone skipped the thing
+    // that makes the product act rather than advise.
+    process.stdout.write(
+      `\nOptional — let PreMan start ${agent.label} runs for you, so it can apply\n` +
+        `fixes and run checks on a schedule instead of only telling you what to do.\n` +
+        `Get the token from ${agent.dispatch.source}.\n`
+    );
+    secret = await promptSecret(`Paste your ${agent.dispatch.credential} (Enter to skip): `);
+    if (!secret) {
+      process.stdout.write(
+        `Skipped. Run '${cliInvocation()} dispatch --agent ${agent.id.replace("_", "-")}' when you have the token.\n`
+      );
+      return;
+    }
+    if (agent.dispatch.needsRoutine && !routineId) {
+      routineId = await promptText("Routine id or URL: ");
+    }
+  }
+
+  if (agent.dispatch.needsRoutine && !routineId) {
+    process.stdout.write("Skipped: a routine id is required alongside the token.\n");
+    return;
+  }
+
+  const body = agent.dispatch.needsRoutine
+    ? { provider: agent.id, secret, routine_id: extractRoutineId(routineId) }
+    : { provider: agent.id, secret };
+
+  const result = await callBackendJson(args, "PUT", "/workbench/coding-agent/dispatch", {
+    token: apiKey,
+    json: body,
+  });
+
+  if (result.ok) {
+    process.stdout.write("Cloud dispatch enabled — PreMan can now start runs for you.\n");
+  } else if (result.status_code === 404 || result.status_code === 405) {
+    process.stdout.write("Note: this PreMan backend does not support cloud dispatch yet; skipped.\n");
+  } else {
+    process.stdout.write(`Note: could not save the credential (${result.status_code}); skipped.\n`);
+  }
+}
+
+export const DISPATCH_HELP = `
+Dispatch options:
+  --agent <name>              cursor | claude-code (defaults to the connected agent)
+  --dispatch-credential <t>   Cloud-dispatch token (non-interactive)
+  --routine-id <id>           Claude Code routine id, with --dispatch-credential
+  --api-key <key>             PreMan API key. If omitted, stored credentials are used
+  --backend <url>             PreMan backend URL
+`;
+
+/**
+ * `preman dispatch` — store the cloud-dispatch credential on its own.
+ *
+ * Exists so connect never has to ask for a token mid-onboarding. Someone who
+ * skipped it (or did not have it yet) comes back here instead of re-running the
+ * whole connect.
+ */
+export async function dispatchCommand(commandArgs) {
+  const args = makeArgs(commandArgs);
+  const apiKey = resolveApiKey(args);
+  if (!apiKey) {
+    throw new ConnectError(
+      `No PreMan credentials. Run '${cliInvocation()} connect' first, or pass --api-key pm_live_….`,
+      EXIT_USAGE
+    );
+  }
+
+  let agent = findAgent(args.value("--agent", ""));
+  if (!agent && args.value("--agent", "")) {
+    throw new ConnectError(
+      `Unknown agent: ${args.value("--agent", "")}. Use cursor or claude-code.`,
+      EXIT_USAGE
+    );
+  }
+
+  if (!agent) {
+    const current = await callBackendJson(args, "GET", "/workbench/coding-agent", { token: apiKey });
+    agent = findAgent(current.ok ? current.agent : "");
+    if (!agent) {
+      throw new ConnectError(
+        "Could not tell which agent to set up. Pass --agent cursor or --agent claude-code.",
+        EXIT_USAGE
+      );
+    }
+  }
+
+  if (!agent.dispatch) {
+    throw new ConnectError(`${agent.label} has no cloud-dispatch API yet.`, EXIT_USAGE);
+  }
+  if (!args.value("--dispatch-credential", "") && !process.stdin.isTTY) {
+    throw new ConnectError(
+      "preman dispatch needs a terminal, or --dispatch-credential <token>.",
+      EXIT_USAGE
+    );
+  }
+
+  await captureDispatchCredential(args, agent, apiKey);
+}
+
+/** Accept either a bare trig_… id or the routine URL it appears in. */
+export function extractRoutineId(value) {
+  const raw = String(value || "").trim();
+  const match = raw.match(/trig_[A-Za-z0-9]+/);
+  return match ? match[0] : raw;
+}

package/bin/connect/errors.js

@@ -0,0 +1,16 @@
+/**
+ * The one error type the connect modules share.
+ *
+ * Its own file because every other module needs it and none of them should have
+ * to import a sibling to raise. `exitCode` is what the CLI exits with, so a
+ * usage mistake (2) stays distinguishable from a run that genuinely failed (1).
+ */
+
+export const EXIT_USAGE = 2;
+
+export class ConnectError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.exitCode = exitCode;
+  }
+}