premanmcp 0.3.5 → 0.5.0

package/bin/shared.js

@@ -0,0 +1,348 @@
+/**
+ * Shared CLI helpers: prompts, credential storage, backend calls, terminal auth.
+ *
+ * Extracted from bin/cli.js so `connect` and `install` can use the same login
+ * and config-writing behavior instead of growing a second copy. Every function
+ * that reads flags takes an `args` accessor (see makeArgs) rather than closing
+ * over a module-level argv, so a command can pass its own slice.
+ */
+
+import { chmodSync, existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+
+export const DEFAULT_BACKEND = "https://api.preman.live";
+export const DEFAULT_FRONTEND = "https://app.preman.live";
+export const CREDENTIALS_DIR = path.join(os.homedir(), ".preman");
+export const CREDENTIALS_FILE = path.join(CREDENTIALS_DIR, "credentials.json");
+
+/** Wrap a raw argv slice in the positional lookup the CLI has always used. */
+export function makeArgs(commandArgs = []) {
+  return {
+    raw: commandArgs,
+    value(name, fallback = "") {
+      const index = commandArgs.indexOf(name);
+      if (index === -1) return fallback;
+      return commandArgs[index + 1] || fallback;
+    },
+    has(name) {
+      return commandArgs.includes(name);
+    },
+  };
+}
+
+export function readJsonFile(filePath) {
+  if (!existsSync(filePath)) return {};
+  const raw = readFileSync(filePath, "utf8").trim();
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`Could not parse ${filePath}: ${error.message}`);
+  }
+}
+
+export function writeJsonFile(filePath, value) {
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  // writeFileSync's mode only applies when it creates the file, and these
+  // configs can hold a pm_live_ key — tighten an existing file explicitly.
+  chmodSync(filePath, 0o600);
+}
+
+export function readStoredCredentials() {
+  try {
+    const raw = readFileSync(CREDENTIALS_FILE, "utf8").trim();
+    if (!raw) return null;
+    const creds = JSON.parse(raw);
+    if (creds && typeof creds.api_key === "string" && creds.api_key.startsWith("pm_live_")) {
+      return creds;
+    }
+  } catch {
+    // No stored credentials yet.
+  }
+  return null;
+}
+
+export function saveStoredCredentials(creds) {
+  mkdirSync(CREDENTIALS_DIR, { recursive: true, mode: 0o700 });
+  writeFileSync(CREDENTIALS_FILE, `${JSON.stringify(creds, null, 2)}\n`, { mode: 0o600 });
+}
+
+export function backendUrl(args) {
+  return args.value("--backend", process.env.PREMAN_BACKEND || DEFAULT_BACKEND).replace(/\/+$/, "");
+}
+
+export function frontendUrl(args) {
+  return args.value("--frontend", process.env.PREMAN_FRONTEND || DEFAULT_FRONTEND).replace(/\/+$/, "");
+}
+
+export async function promptText(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return (await rl.question(question)).trim();
+  } finally {
+    rl.close();
+  }
+}
+
+export async function promptSecret(question) {
+  if (!process.stdin.isTTY || !process.stdin.setRawMode) {
+    return promptText(question);
+  }
+
+  return new Promise((resolve) => {
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+    const wasRaw = stdin.isRaw;
+    let value = "";
+
+    function cleanup() {
+      stdin.off("data", onData);
+      stdin.setRawMode(Boolean(wasRaw));
+      stdin.pause();
+    }
+
+    function onData(chunk) {
+      const text = String(chunk);
+      if (text === "\u0003") {
+        stdout.write("\n");
+        cleanup();
+        process.exit(130);
+      }
+      if (text === "\r" || text === "\n" || text === "\u0004") {
+        stdout.write("\n");
+        cleanup();
+        resolve(value);
+        return;
+      }
+      if (text === "\u007f" || text === "\b") {
+        if (value.length) {
+          value = value.slice(0, -1);
+          stdout.write("\b \b");
+        }
+        return;
+      }
+      value += text;
+      stdout.write("*");
+    }
+
+    stdout.write(question);
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding("utf8");
+    stdin.on("data", onData);
+  });
+}
+
+export async function promptPasswordTwice() {
+  const password = await promptSecret("Create password: ");
+  if (!password || password.length < 6) {
+    throw new Error("Password must be at least 6 characters.");
+  }
+  const confirm = await promptSecret("Confirm password: ");
+  if (password !== confirm) {
+    throw new Error("Passwords do not match.");
+  }
+  return password;
+}
+
+export async function callBackendJson(args, method, routePath, { json, token, query } = {}) {
+  const url = new URL(routePath.replace(/^\/+/, ""), `${backendUrl(args)}/`);
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value != null && value !== "") url.searchParams.set(key, String(value));
+    }
+  }
+
+  const headers = { Accept: "application/json" };
+  const hasBody = json !== undefined && json !== null;
+  if (hasBody) headers["Content-Type"] = "application/json";
+  if (token) headers.Authorization = `Bearer ${token}`;
+
+  const resp = await fetch(url, {
+    method,
+    headers,
+    body: hasBody ? JSON.stringify(json) : undefined,
+  });
+  const text = await resp.text();
+  let body = {};
+  try {
+    body = text ? JSON.parse(text) : {};
+  } catch {
+    body = { raw: text };
+  }
+  return {
+    status_code: resp.status,
+    ok: resp.ok,
+    ...body,
+  };
+}
+
+export function assertOk(result, action) {
+  if (result.ok) return;
+  const detail = result.detail || result.message || result.raw || `${action} failed`;
+  throw new Error(`${action} failed: ${result.status_code} ${detail}`);
+}
+
+async function verifyUnconfirmedAccount(args, email) {
+  process.stdout.write("This email exists but is not verified. Sending a new OTP.\n");
+  const resend = await callBackendJson(args, "POST", "/auth/resend-otp", { json: { email } });
+  assertOk(resend, "resend OTP");
+  const otp = await promptText("Verification code: ");
+  const verified = await callBackendJson(args, "POST", "/auth/verify-otp", { json: { email, otp } });
+  assertOk(verified, "verify OTP");
+  return verified.access_token;
+}
+
+async function createAccountFromTerminal(args, email) {
+  const signup = await callBackendJson(args, "POST", "/auth/start-signup", {
+    json: { email },
+  });
+
+  if (signup.ok) {
+    process.stdout.write("Verification code sent. Check your email.\n");
+    const otp = await promptText("Verification code: ");
+    const password = await promptPasswordTwice();
+    const setPassword = await callBackendJson(args, "POST", "/auth/set-password", {
+      json: { email, otp, new_password: password },
+    });
+    assertOk(setPassword, "set password");
+    return String(setPassword.access_token || "");
+  }
+
+  if (signup.status_code !== 404) {
+    assertOk(signup, "start signup");
+  }
+
+  process.stdout.write(
+    "This PreMan backend uses the password-first signup flow. Create your password now, then enter the email code.\n"
+  );
+  const password = await promptPasswordTwice();
+  const legacySignup = await callBackendJson(args, "POST", "/auth/signup", {
+    json: { email, password },
+  });
+  assertOk(legacySignup, "signup");
+  process.stdout.write("Verification code sent. Check your email.\n");
+  const otp = await promptText("Verification code: ");
+  const verified = await callBackendJson(args, "POST", "/auth/verify-otp", {
+    json: { email, otp },
+  });
+  assertOk(verified, "verify OTP");
+  return String(verified.access_token || "");
+}
+
+/**
+ * Get a usable pm_live_ key: an explicit one, or by logging in / signing up
+ * right here in the terminal. Always persists to ~/.preman/credentials.json.
+ */
+export async function authenticateTerminal(args) {
+  const explicitKey = args.value("--api-key", process.env.PREMAN_API_KEY || "");
+  if (explicitKey && explicitKey.startsWith("pm_live_")) {
+    const creds = {
+      api_key: explicitKey,
+      backend_url: backendUrl(args),
+      user_email: args.value("--email", ""),
+      device_name: os.hostname(),
+      created_at: new Date().toISOString(),
+    };
+    saveStoredCredentials(creds);
+    return creds;
+  }
+
+  const email = (args.value("--email", "") || await promptText("Email: ")).trim().toLowerCase();
+  if (!email) throw new Error("Email is required.");
+
+  process.stdout.write(`Checking PreMan account for ${email}...\n`);
+  const account = await callBackendJson(args, "GET", "/auth/needs-password", { query: { email } });
+  assertOk(account, "check account");
+
+  let accessToken = "";
+
+  if (!account.exists) {
+    process.stdout.write("No PreMan account found. Creating one now.\n");
+    accessToken = await createAccountFromTerminal(args, email);
+  } else if (account.needs_password) {
+    process.stdout.write("This account needs a password. Sending an OTP first.\n");
+    const resend = await callBackendJson(args, "POST", "/auth/resend-otp", { json: { email } });
+    assertOk(resend, "resend OTP");
+    const otp = await promptText("Verification code: ");
+    const password = await promptPasswordTwice();
+    const setPassword = await callBackendJson(args, "POST", "/auth/set-password", {
+      json: { email, otp, new_password: password },
+    });
+    assertOk(setPassword, "set password");
+    accessToken = String(setPassword.access_token || "");
+  } else {
+    const password = await promptSecret("Password: ");
+    const login = await callBackendJson(args, "POST", "/auth/login", {
+      json: { email, password },
+    });
+    if (!login.ok && login.status_code === 403 && String(login.detail || "").toLowerCase().includes("not verified")) {
+      accessToken = await verifyUnconfirmedAccount(args, email);
+    } else {
+      assertOk(login, "login");
+      accessToken = String(login.access_token || "");
+    }
+  }
+
+  if (!accessToken) throw new Error("PreMan did not return an access token.");
+
+  const keyName = `PreMan MCP CLI (${os.hostname()})`;
+  const key = await callBackendJson(args, "POST", "/api-keys", {
+    token: accessToken,
+    json: { name: keyName },
+  });
+  assertOk(key, "create API key");
+  if (!key.key || !String(key.key).startsWith("pm_live_")) {
+    throw new Error("PreMan did not return a valid API key.");
+  }
+
+  const creds = {
+    api_key: String(key.key),
+    backend_url: backendUrl(args),
+    user_email: email,
+    device_name: os.hostname(),
+    created_at: new Date().toISOString(),
+  };
+  saveStoredCredentials(creds);
+  return creds;
+}
+
+/** Does this invocation already have a key, without prompting for one? */
+export function hasKeyAvailable(args) {
+  return Boolean(
+    args.value("--api-key", "") || process.env.PREMAN_API_KEY || readStoredCredentials()
+  );
+}
+
+/** Resolve the key to embed in a written config, if any. */
+export function resolveApiKey(args) {
+  const explicit = args.value("--api-key", process.env.PREMAN_API_KEY || "");
+  if (explicit) return explicit;
+  const stored = readStoredCredentials();
+  return stored ? stored.api_key : "";
+}
+
+/**
+ * The MCP server block written into every agent's config.
+ *
+ * Matches the backend's install snippets (`build_install_snippets`) so the
+ * copy-paste path and this writer cannot drift.
+ */
+export function buildServerConfig(args, { pairCode = "" } = {}) {
+  const env = {
+    PREMAN_BACKEND: backendUrl(args),
+    PREMAN_FRONTEND: frontendUrl(args),
+  };
+  const apiKey = resolveApiKey(args);
+  if (apiKey) env.PREMAN_API_KEY = apiKey;
+  if (pairCode) env.PREMAN_PAIR_CODE = pairCode;
+
+  return {
+    command: "npx",
+    args: ["-y", "premanmcp@latest"],
+    env,
+  };
+}

package/dist/server.js

@@ -42,6 +42,62 @@ applyRepoPremanConfig();
 const BACKEND_URL = process.env.PREMAN_BACKEND || "https://api.preman.live";
 const FRONTEND_URL = process.env.PREMAN_FRONTEND || "https://app.preman.live";
 let API_KEY = process.env.PREMAN_API_KEY || "";
+function detectCodingAgent() {
+    const forced = (process.env.PREMAN_CODING_AGENT || "").trim().toLowerCase();
+    if (forced)
+        return forced.replace("-", "_");
+    if (process.env.CLAUDECODE || process.env.CLAUDE_CODE)
+        return "claude_code";
+    if (process.env.CODEX_HOME || process.env.OPENAI_CODEX)
+        return "codex";
+    if (process.env.CURSOR_AGENT || process.env.CURSOR_TRACE_ID || process.env.CURSOR_SESSION_ID) {
+        return "cursor";
+    }
+    return "cursor";
+}
+/** Prove this MCP session is live to the workbench coding-agent link. */
+async function heartbeatWorkbenchLink() {
+    if (!API_KEY)
+        return null;
+    try {
+        const resp = await fetch(`${BACKEND_URL}/workbench/coding-agent/heartbeat`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${API_KEY}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                pair_code: process.env.PREMAN_PAIR_CODE || undefined,
+                agent: detectCodingAgent(),
+                project_path: process.cwd(),
+                client_label: "premanmcp",
+                source: "preman_status",
+            }),
+        });
+        const text = await resp.text();
+        let data = {};
+        try {
+            data = text ? JSON.parse(text) : {};
+        }
+        catch {
+            data = { detail: text };
+        }
+        if (!resp.ok) {
+            return {
+                ok: false,
+                status: resp.status,
+                detail: data.detail || data.message || text,
+            };
+        }
+        return { ok: true, ...data };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            detail: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
 const PREMAN_CONTROL_PLANE_HOSTS = new Set([
     "api.preman.live",
     "preman.live",
@@ -920,6 +976,7 @@ export function createServer() {
                     }],
             };
         }
+        const workbench = await heartbeatWorkbenchLink();
         return {
             content: [{
                     type: "text",
@@ -930,13 +987,17 @@ export function createServer() {
                         backend_url: BACKEND_URL,
                         frontend_base_url: FRONTEND_BASE,
                         endpoints_page_url: buildAgentDashboardUrl("/endpoints"),
+                        coding_agent: workbench,
                         _agent_hints: {
                             next_actions: [
+                                workbench && workbench.connected
+                                    ? "Coding agent is linked to PreMan workbench — call discover_endpoints_from_codebase or get_endpoints."
+                                    : "If PreMan workbench shows pairing, set PREMAN_PAIR_CODE then call preman_status again.",
                                 "browser_navigate to `endpoints_page_url` (SPA shell + ot_agent_route) to open PreMan on the Endpoints page (sign in if prompted), then call get_endpoints.",
                                 "Call get_endpoints to see registered API endpoints.",
                                 "Call test_api to test an endpoint.",
                             ],
-                            related_tools: ["get_endpoints", "test_api", "import_collection"],
+                            related_tools: ["get_endpoints", "test_api", "import_collection", "discover_endpoints_from_codebase"],
                         },
                     }),
                 }],
@@ -1206,6 +1267,54 @@ export function createServer() {
             return toolError(e.message, inferErrorCode(e.message));
         }
     });
+    // ── preman_get_fix_task ───────────────────────────────────────────
+    server.tool("preman_get_fix_task", "Pull pending coding-agent fix tasks built from fired PreMan alerts. Each task packages a failing endpoint: title, expected vs actual, failure stats, and a reproducible curl (package.repro.curl). Fix the endpoint using the curl, then call preman_complete_fix_task with the fix_task_id. Check package.auto_pr: when eligible is true, push your fix on the branch it names and call preman_open_fix_pr.", {
+        status: z.enum(["open", "delivered", "resolved"]).optional().default("open").describe("'open' (default) hands out new tasks and marks them delivered; 'delivered' re-fetches ones already pulled; 'resolved' for history"),
+        limit: z.number().optional().default(5).describe("Max tasks to return (capped at 20)"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("preman_get_fix_task", args);
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["No open fix tasks means no alerts have been handed off. Create a handoff from a fired alert in the dashboard."],
+            });
+        }
+    });
+    // ── preman_complete_fix_task ──────────────────────────────────────
+    server.tool("preman_complete_fix_task", "Mark a fix task resolved once its endpoint failure is fixed.", {
+        fix_task_id: z.string().describe("The id from a preman_get_fix_task result"),
+        resolution_note: z.string().optional().default("").describe("Optional note on what was fixed"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("preman_complete_fix_task", args);
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                related_tools: ["preman_get_fix_task"],
+            });
+        }
+    });
+    // ── preman_open_fix_pr ────────────────────────────────────────────
+    server.tool("preman_open_fix_pr", "Open a pull request for a fix branch you already pushed (Auto-PR, Tier 2). Only for fix tasks whose package.auto_pr.eligible is true. Patch and push the preman/fix-* branch with your own git credentials first — PreMan never pushes code. PreMan then verifies the branch exists, re-checks the endpoint in production, and opens a PR with that evidence. PreMan never merges: a human reviews and merges.", {
+        fix_task_id: z.string().describe("The id from a preman_get_fix_task result"),
+        branch: z.string().describe("The branch you pushed — must match package.auto_pr.branch"),
+        summary: z.string().optional().default("").describe("Short description of the fix, included in the PR body"),
+        local_rerun: z.string().optional().default("").describe("Your local test/re-run output, included as agent-reported evidence"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("preman_open_fix_pr", args);
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                related_tools: ["preman_get_fix_task", "preman_complete_fix_task"],
+                next_actions: ["Auto-PR requires the repo to have opted in and the fix task to be an API_BUG failure mapped to that repo."],
+            });
+        }
+    });
     return server;
 }
 // ── Start ─────────────────────────────────────────────────────────────

package/dist/user_auth_flow.js

@@ -58,7 +58,7 @@ async function callAuthJson(base, method, path, opts) {
  */
 export function registerUserAuthFlowTools(server, backendUrl) {
     const base = normalizeBase(backendUrl);
-    server.tool("user_auth_start_signup", "Start signup with email only. Sends an OTP; next call user_auth_set_password with email, OTP, and new password. Uses POST /auth/start-signup on PREMAN_BACKEND (no API key).", {
+    server.tool("user_auth_start_signup", "Start signup with email only. Sends an OTP; next call user_auth_set_password with email, OTP, and new password. Uses POST /auth/start-signup on PREMAN_BACKEND (no API key). If the backend does not support this endpoint yet, use user_auth_signup instead.", {
         email: z.string().describe("User email"),
     }, async (args) => {
         try {
@@ -66,6 +66,12 @@ export function registerUserAuthFlowTools(server, backendUrl) {
                 json: { email: args.email },
             });
             if (!r.ok) {
+                if (r.status_code === 404) {
+                    return toolError("This backend does not support email-only signup yet. Use user_auth_signup with email and password, then user_auth_verify_otp.", "backend_error", {
+                        next_actions: ["Call user_auth_signup with email and password.", "Then call user_auth_verify_otp with the email code."],
+                        related_tools: ["user_auth_signup", "user_auth_verify_otp"],
+                    });
+                }
                 return toolError(String(r.detail ?? r.message ?? "start signup failed"), r.status_code === 400 ? "invalid_input" : "backend_error", {
                     next_actions: ["If email exists, use user_auth_login or user_auth_resend_otp."],
                     related_tools: ["user_auth_set_password", "user_auth_login"],

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "premanmcp",
-  "version": "0.3.5",
+  "version": "0.5.0",
   "description": "Turn APIs into agent-callable MCP tools with auth, testing, and audit logs",
   "type": "module",
   "bin": {
     "premanmcp": "bin/cli.js",
-    "preman-mcp": "bin/cli.js"
+    "preman-mcp": "bin/cli.js",
+    "preman": "bin/cli.js"
   },
   "scripts": {
     "build": "tsc -p tsconfig.server.json",