premanmcp 0.8.0 → 0.10.0

package/bin/shared.js

@@ -7,8 +7,8 @@
  * over a module-level argv, so a command can pass its own slice.
  */
 
-import { spawnSync } from "node:child_process";
-import { chmodSync, existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
+import { chmodSync, existsSync, readFileSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { createInterface } from "node:readline/promises";
@@ -93,6 +93,18 @@ export function saveStoredCredentials(creds) {
   writeFileSync(CREDENTIALS_FILE, `${JSON.stringify(creds, null, 2)}\n`, { mode: 0o600 });
 }
 
+/** Forget the stored key. Returns whether there was one. */
+export function clearStoredCredentials() {
+  if (!existsSync(CREDENTIALS_FILE)) return false;
+  rmSync(CREDENTIALS_FILE, { force: true });
+  return true;
+}
+
+/** True when the key in play came from a flag or the environment, not our store. */
+export function apiKeyIsExplicit(args) {
+  return Boolean(args.value("--api-key", "") || process.env.PREMAN_API_KEY);
+}
+
 export function backendUrl(args) {
   return args.value("--backend", process.env.PREMAN_BACKEND || DEFAULT_BACKEND).replace(/\/+$/, "");
 }
@@ -101,6 +113,36 @@ export function frontendUrl(args) {
   return args.value("--frontend", process.env.PREMAN_FRONTEND || DEFAULT_FRONTEND).replace(/\/+$/, "");
 }
 
+/**
+ * Open a URL in the user's default browser, best effort.
+ *
+ * Returns false without spawning anything when nobody is there to look at it:
+ * `PREMAN_NO_BROWSER` for an explicit no, and a non-TTY stdout for CI, piped
+ * output, and test runs. Every caller prints the URL as well, so this is only
+ * ever a convenience — a suite that exercises these flows should not be able to
+ * throw tabs at whoever is running it.
+ */
+export function openUrl(url) {
+  const optOut = (process.env.PREMAN_NO_BROWSER || "").trim().toLowerCase();
+  if (optOut && !["0", "false", "no"].includes(optOut)) return false;
+  if (!process.stdout.isTTY) return false;
+
+  const opener =
+    process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  try {
+    const child = spawn(opener, [url], {
+      stdio: "ignore",
+      detached: true,
+      shell: process.platform === "win32",
+    });
+    child.unref();
+    return true;
+  } catch {
+    // Headless boxes and locked-down shells are normal.
+    return false;
+  }
+}
+
 export async function promptText(question) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {
@@ -235,7 +277,50 @@ async function verifyUnconfirmedAccount(args, email) {
   return verified.access_token;
 }
 
+/**
+ * A password only if the caller asked for one.
+ *
+ * The terminal's durable credential is the pm_live_ key, so signup does not
+ * need a password and no longer asks for one. `--password` is for anyone who
+ * wants to be able to sign in to the dashboard immediately; `--password <value>`
+ * skips the prompt for scripted runs.
+ */
+async function optionalPassword(args) {
+  if (!args.has("--password")) return "";
+  const supplied = args.value("--password", "");
+  // Bare `--password` followed by another flag means "prompt me", not "my
+  // password is --backend".
+  if (supplied && !supplied.startsWith("--")) {
+    if (supplied.length < 6) throw new Error("Password must be at least 6 characters.");
+    return supplied;
+  }
+  return promptPasswordTwice();
+}
+
+/**
+ * Turn a verification code into a session token.
+ *
+ * Without a password this is one call: verify-otp signs the user in and the
+ * backend keeps the account passwordless, so the dashboard knows to offer a
+ * code rather than a password field.
+ */
+async function completeWithCode(args, email, otp, password) {
+  if (password) {
+    const setPassword = await callBackendJson(args, "POST", "/auth/set-password", {
+      json: { email, otp, new_password: password },
+    });
+    assertOk(setPassword, "set password");
+    return String(setPassword.access_token || "");
+  }
+  const verified = await callBackendJson(args, "POST", "/auth/verify-otp", {
+    json: { email, otp },
+  });
+  assertOk(verified, "verify OTP");
+  return String(verified.access_token || "");
+}
+
 async function createAccountFromTerminal(args, email) {
+  const password = await optionalPassword(args);
   const signup = await callBackendJson(args, "POST", "/auth/start-signup", {
     json: { email },
   });
@@ -243,24 +328,21 @@ async function createAccountFromTerminal(args, 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 || "");
+    return completeWithCode(args, email, otp, password);
   }
 
   if (signup.status_code !== 404) {
     assertOk(signup, "start signup");
   }
 
+  // Backends predating start-signup have no passwordless route in, so this one
+  // path still has to ask.
   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 legacyPassword = password || (await promptPasswordTwice());
   const legacySignup = await callBackendJson(args, "POST", "/auth/signup", {
-    json: { email, password },
+    json: { email, password: legacyPassword },
   });
   assertOk(legacySignup, "signup");
   process.stdout.write("Verification code sent. Check your email.\n");
@@ -303,26 +385,31 @@ export async function authenticateTerminal(args) {
     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");
+    // No password on this account, so a code is the only way in.
+    const password = await optionalPassword(args);
+    process.stdout.write("Sending a sign-in code to your email.\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 || "");
+    accessToken = await completeWithCode(args, email, otp, password);
   } 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);
+    const password = await promptSecret("Password (Enter to get a code by email): ");
+    if (!password) {
+      const resend = await callBackendJson(args, "POST", "/auth/resend-otp", { json: { email } });
+      assertOk(resend, "resend OTP");
+      process.stdout.write("Sign-in code sent. Check your email.\n");
+      const otp = await promptText("Verification code: ");
+      accessToken = await completeWithCode(args, email, otp, "");
     } else {
-      assertOk(login, "login");
-      accessToken = String(login.access_token || "");
+      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 || "");
+      }
     }
   }
 

package/dist/server.js

@@ -9,11 +9,7 @@ import path from "node:path";
 import os from "node:os";
 import { randomUUID } from "node:crypto";
 import { MCP_PREVIEW_RESOURCE_URI, RESOURCE_URI_META_KEY, buildConversionPanelHtml, writeMcpPreviewFile, } from "./mcp-preview-panel.js";
-/**
- * Load ``PREMAN_*`` from repo JSON so project URLs win over stale **global** Cursor MCP env
- * (which often sets the wrong ``PREMAN_BACKEND``, e.g. app port instead of API port).
- * First match wins: ``.cursor/preman-mcp.config.json``, then ``preman-mcp.config.json`` (cwd).
- */
+let REPO_CONFIG = null;
 function applyRepoPremanConfig() {
     const candidates = [
         path.join(process.cwd(), ".cursor", "preman-mcp.config.json"),
@@ -24,13 +20,19 @@ function applyRepoPremanConfig() {
             if (!existsSync(p))
                 continue;
             const j = JSON.parse(readFileSync(p, "utf8"));
+            const override = j.PREMAN_CONFIG_OVERRIDE === true || j.PREMAN_CONFIG_OVERRIDE === "true";
+            const applied = [];
             for (const [key, val] of Object.entries(j)) {
-                if (!key.startsWith("PREMAN_"))
+                if (!key.startsWith("PREMAN_") || key === "PREMAN_CONFIG_OVERRIDE")
                     continue;
-                if (typeof val === "string" && val.trim()) {
-                    process.env[key] = val.trim();
-                }
+                if (typeof val !== "string" || !val.trim())
+                    continue;
+                if (!override && process.env[key])
+                    continue;
+                process.env[key] = val.trim();
+                applied.push(key);
             }
+            REPO_CONFIG = { path: p, override, applied };
             return;
         }
         catch {
@@ -42,6 +44,22 @@ 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 || "";
+/**
+ * Where the URLs this process is using came from.
+ *
+ * Reported by `preman_status` because the most confusing failure in setup is a
+ * server that works perfectly against the wrong backend: the key is fine, the
+ * config on disk is fine, and every call still 401s. Naming the file that
+ * redirected it turns that into a one-line diagnosis.
+ */
+function configSource() {
+    return {
+        backend_url: BACKEND_URL,
+        repo_config: REPO_CONFIG
+            ? { path: REPO_CONFIG.path, override: REPO_CONFIG.override, applied: REPO_CONFIG.applied }
+            : null,
+    };
+}
 function detectCodingAgent() {
     const forced = (process.env.PREMAN_CODING_AGENT || "").trim().toLowerCase();
     if (forced)
@@ -1040,6 +1058,7 @@ export function createServer() {
                             backend_url: BACKEND_URL,
                             frontend_base_url: FRONTEND_BASE,
                             endpoints_page_url: buildAgentDashboardUrl("/endpoints"),
+                            config: configSource(),
                             message: "Stored API key is no longer valid. Run `npm exec -y premanmcp@latest -- login`, or use user_auth_* then preman_create_api_key, or run preman_login.",
                         }),
                     }],
@@ -1056,6 +1075,7 @@ export function createServer() {
                         backend_url: BACKEND_URL,
                         frontend_base_url: FRONTEND_BASE,
                         endpoints_page_url: buildAgentDashboardUrl("/endpoints"),
+                        config: configSource(),
                         coding_agent: workbench,
                         _agent_hints: {
                             next_actions: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "premanmcp",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Turn APIs into agent-callable MCP tools with auth, testing, and audit logs",
   "type": "module",
   "bin": {