premanmcp 1.1.0 → 1.1.2

package/bin/eval.js

@@ -34,7 +34,7 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { discoverTarget, startAdapter, stepFeed } from "./eval_target.js";
+import { adapterStats, discoverTarget, startAdapter, stepFeed } from "./eval_target.js";
 import { resolveEvalSurface } from "./link.js";
 import {
   backendUrl,
@@ -799,6 +799,29 @@ export async function executeEvalRun(
   }
 
   if (exitCode === 0) {
+    // A harness that exited 0 having never once reached the agent is not a
+    // result, and it is the most misleading shape a run can take: every case
+    // was scored, the numbers look like measurements, and what the judge
+    // actually read was the adapter's apology on each turn. The one that
+    // prompted this presented an `api.preman.live` key to an agent on
+    // localhost, 401ed eighteen times, and finished ok.
+    //
+    // Turns are counted rather than failures, because a run where the agent
+    // answered some of the time is a real measurement of a flaky agent and
+    // deciding otherwise here would throw away the finding.
+    const stats = adapterStats();
+    if (stats && stats.turns === 0 && stats.failures > 0) {
+      const outcome = await finish(false, {
+        summary,
+        error:
+          `not one of the ${stats.failures} turns reached the agent, so nothing here was ` +
+          `measured against it. The last reason was: ${stats.lastFailure || "unknown"}`,
+        exitCode,
+      });
+      rmSync(scratch, { recursive: true, force: true });
+      return { ...outcome, summary, artifacts };
+    }
+
     const outcome = await finish(true, { summary, exitCode });
     rmSync(scratch, { recursive: true, force: true });
     return { ...outcome, summary, artifacts };

package/bin/eval_target.js

@@ -35,7 +35,46 @@
 import { createServer } from "node:http";
 import { createHash } from "node:crypto";
 
-import { backendUrl, resolveApiKey } from "./shared.js";
+import { backendUrl, resolveApiKey, storedKeyOrigin } from "./shared.js";
+
+/**
+ * The credential to present to the agent under test.
+ *
+ * When the agent *is* a PreMan deployment, this is a PreMan key -- but not
+ * necessarily the one this CLI reports results with. Those are two different
+ * systems that happen to be the same product: the control plane is whichever
+ * deployment issued the saved key, and the agent is whatever answered on this
+ * machine. A run that presented an `api.preman.live` key to a backend on
+ * localhost 401ed on all eighteen turns and still reported a score, because the
+ * adapter turns a failure into a transcript the judge can read.
+ *
+ * Refusing beats warning. Every turn would fail, the whole run would be scored
+ * against the adapter's apology, and it would cost a full round of model calls
+ * to arrive at a number about nothing.
+ */
+function agentToken(args, baseUrl, log) {
+  const named = args.value("--agent-key", process.env.PREMAN_AGENT_KEY || "");
+  if (named) return named;
+
+  const key = resolveApiKey(args);
+  const origin = storedKeyOrigin(args);
+  if (!origin || sameDeployment(origin, baseUrl)) return key;
+
+  throw new TargetError(
+    `the agent here is ${baseUrl}, but the only PreMan key on this machine was issued by ` +
+      `${origin}. It would be refused on every turn and the run would score the refusals. ` +
+      `Set PREMAN_AGENT_KEY to a key ${baseUrl} accepts, or stop that agent so this measures ` +
+      `${origin} instead.`
+  );
+}
+
+function sameDeployment(a, b) {
+  try {
+    return new URL(a).host === new URL(b).host;
+  } catch {
+    return false;
+  }
+}
 
 export class TargetError extends Error {}
 
@@ -130,7 +169,7 @@ export async function discoverTarget(args, { log = () => {} } = {}) {
         // The agent's own credential, held here and never sent to PreMan's
         // control plane. The adapter is the only thing that ever presents it,
         // which is the whole reason the adapter runs on this machine.
-        token: resolveApiKey(args),
+        token: agentToken(args, `http://127.0.0.1:${port}`, log),
         label: `PreMan agent (local, port ${port})`,
         how: `probed localhost and got a PreMan /health on port ${port}`,
         probed,
@@ -146,7 +185,7 @@ export async function discoverTarget(args, { log = () => {} } = {}) {
     return {
       kind: "preman-chat",
       baseUrl: configured,
-      token: resolveApiKey(args),
+      token: agentToken(args, configured, log),
       label: `PreMan agent (${configured})`,
       how: `nothing local answered, so this is the backend the CLI is configured against`,
       probed,
@@ -463,6 +502,7 @@ export async function startAdapter(target, args, { log = () => {}, onStep = null
     conversations: new Map(),
     turns: 0,
     failures: 0,
+    lastFailure: "",
     streamFailures: 0,
     log,
     /**
@@ -500,6 +540,7 @@ export async function startAdapter(target, args, { log = () => {}, onStep = null
         reply(200, result);
       } catch (error) {
         state.failures += 1;
+        state.lastFailure = error.message;
         // 200 with an error string in `response`, not a 5xx. A transport failure
         // aborts the case and loses it; an agent that said something unhelpful is
         // a transcript the judge can score. Which of those this is depends on
@@ -519,12 +560,32 @@ export async function startAdapter(target, args, { log = () => {}, onStep = null
   const url = `http://127.0.0.1:${port}/chat`;
   log(`Adapter listening on ${url} -> ${target.label}`);
 
+  activeStats = state;
   return {
     url,
     translated: true,
     stats: state,
     close: async () => {
+      activeStats = null;
       await new Promise((resolve) => server.close(resolve));
     },
   };
 }
+
+/**
+ * The counters for the adapter this process is running, if it is running one.
+ *
+ * A module-level handle rather than an argument threaded down, because the
+ * adapter is started by the command and the counters are needed by
+ * `executeEvalRun`, which the runner loop calls — and the loop sits between
+ * them knowing nothing about either. There is at most one adapter per process:
+ * it is opened once for the whole invocation and the runs share it.
+ *
+ * Null when the target is a URL the customer named, which the CLI does not
+ * mediate and therefore cannot count.
+ */
+let activeStats = null;
+
+export function adapterStats() {
+  return activeStats;
+}

package/bin/shared.js

@@ -235,6 +235,20 @@ function activeLogin(args) {
   return apiKeyIsExplicit(args) ? null : readStoredCredentials();
 }
 
+/**
+ * Which deployment the saved key was minted against, or "" if that is unknown.
+ *
+ * Unknown is the honest answer for a key given on the command line or in the
+ * environment: nothing records where it came from, and guessing would be worse
+ * than admitting it. Callers presenting a key to something other than PreMan's
+ * own control plane need this to tell "this will work" from "this is a key for
+ * somewhere else".
+ */
+export function storedKeyOrigin(args) {
+  const login = activeLogin(args);
+  return login?.backend_url || "";
+}
+
 /**
  * Which PreMan deployment this invocation talks to.
  *
@@ -250,6 +264,27 @@ export function backendUrl(args) {
     .replace(/\/+$/, "");
 }
 
+/**
+ * Why this invocation is talking to that deployment.
+ *
+ * Only ever shown when reaching it failed. An unreachable backend is nearly
+ * always a stale override rather than an outage -- a shell that exported
+ * PREMAN_BACKEND at a local server hours ago keeps pointing there long after
+ * the server is gone, and the CLI cannot tell that apart from the deployment
+ * being down. The address alone does not help: the question a person has at
+ * that moment is not "what did you call" but "why on earth are you calling
+ * *that*", and the answer is somewhere they are not looking.
+ *
+ * Mirrors the precedence in `backendUrl` above, which is the only way it can
+ * be right; the two would have to be changed together.
+ */
+export function backendSource(args) {
+  if (args.value("--backend", "")) return "the --backend flag";
+  if (process.env.PREMAN_BACKEND) return "PREMAN_BACKEND, exported in this shell";
+  if (activeLogin(args)?.backend_url) return "the deployment you last logged in to";
+  return "the default";
+}
+
 /**
  * Where the dashboard lives for this user.
  *
@@ -482,11 +517,21 @@ export async function callBackendJson(
     }
   }
 
-  const resp = await fetch(url, {
-    method,
-    headers,
-    body: form !== undefined && form !== null ? form : hasBody ? JSON.stringify(json) : undefined,
-  });
+  let resp;
+  try {
+    resp = await fetch(url, {
+      method,
+      headers,
+      body: form !== undefined && form !== null ? form : hasBody ? JSON.stringify(json) : undefined,
+    });
+  } catch (error) {
+    // `fetch failed` is what Node says when nothing accepted the connection,
+    // and on its own it is unactionable -- it names neither the address nor
+    // the reason that address was chosen. Both are known here.
+    throw new Error(
+      `could not reach ${url.origin} (${backendSource(args)}): ${error?.cause?.message || error.message}`
+    );
+  }
   const text = await resp.text();
   let body = {};
   try {

package/dist/auth_flow_ui.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Auth flow endpoints (signup, verify OTP, login, resend OTP) with JSON schemas
+ * for share_endpoints_with_ui / agent-sessions push.
+ */
+export type AuthFlowEndpoint = {
+    method: string;
+    path_template: string;
+    description: string;
+    tags: string[];
+    source_file: string;
+    request_body_schema: Record<string, unknown>;
+    response_schema: Record<string, unknown>;
+    mcp_tool?: string;
+};
+/** Core auth endpoints aligned with routes/auth/routes.py and user_auth_* MCP tools. */
+export declare function buildAuthFlowEndpoints(): AuthFlowEndpoint[];
+export type ShareAuthFlowResult = {
+    session_id: string;
+    url: string;
+    endpoint_count: number;
+    user_id: number | null;
+    auto_discoverable: boolean;
+    upstream_base_url: string;
+    endpoints: AuthFlowEndpoint[];
+    ui: {
+        url: string;
+        note: string;
+    };
+    related_tools: string[];
+};
+export declare function shareAuthFlowToUi(opts: {
+    backendUrl: string;
+    frontendUrl: string;
+    upstreamBaseUrl?: string;
+    sessionId?: string;
+    intent?: string;
+    apiKey?: string;
+}): Promise<ShareAuthFlowResult>;

package/dist/auth_flow_ui.js

@@ -0,0 +1,170 @@
+/**
+ * Auth flow endpoints (signup, verify OTP, login, resend OTP) with JSON schemas
+ * for share_endpoints_with_ui / agent-sessions push.
+ */
+const EMAIL_PROP = { type: "string", format: "email", description: "User email" };
+const PASSWORD_PROP = {
+    type: "string",
+    minLength: 6,
+    description: "Password (min 6 characters on the server)",
+};
+const OTP_PROP = { type: "string", description: "6-digit code from email" };
+const TOKEN_RESPONSE = {
+    type: "object",
+    properties: {
+        access_token: { type: "string", description: "JWT bearer token" },
+        token_type: { type: "string", enum: ["bearer"] },
+        user: {
+            type: "object",
+            properties: {
+                id: { type: "string" },
+                email: { type: "string", format: "email" },
+            },
+            required: ["id", "email"],
+        },
+    },
+    required: ["access_token", "token_type", "user"],
+};
+const OTP_SENT_RESPONSE = {
+    type: "object",
+    properties: {
+        message: { type: "string" },
+        email_sent: { type: "boolean" },
+    },
+    required: ["message", "email_sent"],
+};
+/** Core auth endpoints aligned with routes/auth/routes.py and user_auth_* MCP tools. */
+export function buildAuthFlowEndpoints() {
+    return [
+        {
+            method: "POST",
+            path_template: "/auth/signup",
+            description: "Register with email and password. Sends OTP to email; next: verify-otp.",
+            tags: ["auth", "signup"],
+            source_file: "routes/auth/routes.py",
+            mcp_tool: "user_auth_signup",
+            request_body_schema: {
+                type: "object",
+                properties: { email: EMAIL_PROP, password: PASSWORD_PROP },
+                required: ["email", "password"],
+                additionalProperties: false,
+            },
+            response_schema: {
+                type: "object",
+                properties: {
+                    message: { type: "string" },
+                    user_id: { type: "string" },
+                    email: { type: "string", format: "email" },
+                    email_sent: { type: "boolean" },
+                },
+                required: ["message", "user_id", "email", "email_sent"],
+            },
+        },
+        {
+            method: "POST",
+            path_template: "/auth/verify-otp",
+            description: "Verify email OTP after signup; returns JWT access_token.",
+            tags: ["auth", "otp"],
+            source_file: "routes/auth/routes.py",
+            mcp_tool: "user_auth_verify_otp",
+            request_body_schema: {
+                type: "object",
+                properties: { email: EMAIL_PROP, otp: OTP_PROP },
+                required: ["email", "otp"],
+                additionalProperties: false,
+            },
+            response_schema: TOKEN_RESPONSE,
+        },
+        {
+            method: "POST",
+            path_template: "/auth/login",
+            description: "Login with email and password. Returns access_token if email is verified.",
+            tags: ["auth", "login"],
+            source_file: "routes/auth/routes.py",
+            mcp_tool: "user_auth_login",
+            request_body_schema: {
+                type: "object",
+                properties: { email: EMAIL_PROP, password: PASSWORD_PROP },
+                required: ["email", "password"],
+                additionalProperties: false,
+            },
+            response_schema: TOKEN_RESPONSE,
+        },
+        {
+            method: "POST",
+            path_template: "/auth/resend-otp",
+            description: "Send (resend) verification OTP to email.",
+            tags: ["auth", "otp"],
+            source_file: "routes/auth/routes.py",
+            mcp_tool: "user_auth_resend_otp",
+            request_body_schema: {
+                type: "object",
+                properties: { email: EMAIL_PROP },
+                required: ["email"],
+                additionalProperties: false,
+            },
+            response_schema: OTP_SENT_RESPONSE,
+        },
+    ];
+}
+export async function shareAuthFlowToUi(opts) {
+    const backend = opts.backendUrl.replace(/\/+$/, "");
+    const frontend = opts.frontendUrl.replace(/\/+$/, "");
+    const apiKey = opts.apiKey?.trim();
+    if (!apiKey) {
+        throw new Error("PreMan authentication required. Run preman_login first so auth-flow sessions can stream to your dashboard.");
+    }
+    const upstream = (opts.upstreamBaseUrl || backend).replace(/\/+$/, "") || backend;
+    const sessionId = opts.sessionId?.trim() || crypto.randomUUID();
+    const endpoints = buildAuthFlowEndpoints().map((ep) => ({
+        ...ep,
+        base_url: upstream,
+    }));
+    const resp = await fetch(`${backend}/agent-sessions/${encodeURIComponent(sessionId)}/endpoints`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+            endpoints,
+            upstream_base_url: upstream,
+            intent: opts.intent || "Auth flow: signup, verify OTP, login, resend OTP",
+            client_label: "premanmcp",
+        }),
+    });
+    const text = await resp.text();
+    let body = {};
+    try {
+        body = text ? JSON.parse(text) : {};
+    }
+    catch {
+        throw new Error(`Agent session push failed: ${resp.status} ${text.slice(0, 500)}`);
+    }
+    if (!resp.ok) {
+        throw new Error(String(body.detail ?? body.error ?? `Agent session push failed: ${resp.status}`));
+    }
+    const sid = String(body.id ?? sessionId);
+    const url = `${frontend}/try?session=${encodeURIComponent(sid)}`;
+    return {
+        session_id: sid,
+        url,
+        endpoint_count: Number(body.endpoint_count ?? endpoints.length),
+        user_id: typeof body.user_id === "number" ? body.user_id : null,
+        auto_discoverable: Boolean(body.auto_discoverable),
+        upstream_base_url: upstream,
+        endpoints: buildAuthFlowEndpoints(),
+        ui: {
+            url,
+            note: "Open in Cursor Agent Browser or the Playground session list. Test signup → verify-otp → login, or resend-otp. " +
+                "Schemas are prefilled from routes/auth Pydantic models.",
+        },
+        related_tools: [
+            "user_auth_signup",
+            "user_auth_verify_otp",
+            "user_auth_login",
+            "user_auth_resend_otp",
+        ],
+    };
+}

package/dist/mcp-preview-panel.d.ts

@@ -0,0 +1,30 @@
+export declare const MCP_PREVIEW_RESOURCE_URI = "ui://preman/mcp-preview";
+export declare const RESOURCE_URI_META_KEY = "ui/resourceUri";
+export declare function escapeHtmlAttr(s: string): string;
+export declare function escapeHtmlText(s: string): string;
+export interface PreviewTool {
+    name?: string;
+    description?: string;
+    inputSchema?: unknown;
+    _endpoint_ref?: {
+        method?: string;
+        path_template?: string;
+        tags?: string[];
+        source?: string;
+    };
+}
+export interface PreviewPayload {
+    intent?: string | string[];
+    selection_method?: string | string[];
+    rationale?: string | string[] | Record<string, string>;
+    selected_count?: number;
+    spec_preview?: {
+        upstream_base_url?: string | string[];
+        tools?: PreviewTool[];
+    };
+}
+export declare function buildConversionPanelHtml(data: PreviewPayload): string;
+export declare function writeMcpPreviewFile(panelHtml: string): Promise<{
+    absolutePath: string;
+    fileUrl: string;
+}>;

package/dist/mcp-preview-panel.js

@@ -0,0 +1,166 @@
+/**
+ * Two-pane HTML for mcp_preview — shared by the MCP stdio server and
+ * scripts/emit-mcp-preview.mjs (browser tab fallback when Cursor does not render mcp-app).
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+export const MCP_PREVIEW_RESOURCE_URI = "ui://preman/mcp-preview";
+export const RESOURCE_URI_META_KEY = "ui/resourceUri";
+export function escapeHtmlAttr(s) {
+    return s.replace(/&/g, "&").replace(/"/g, """);
+}
+export function escapeHtmlText(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+export function buildConversionPanelHtml(data) {
+    const toStr = (v) => {
+        if (v == null)
+            return "";
+        if (Array.isArray(v))
+            return v.filter((x) => x != null).map((x) => String(x)).join("; ");
+        if (typeof v === "object") {
+            try {
+                return Object.entries(v)
+                    .map(([k, val]) => `${k}: ${val == null ? "" : String(val)}`)
+                    .join(" · ");
+            }
+            catch {
+                try {
+                    return JSON.stringify(v);
+                }
+                catch {
+                    return String(v);
+                }
+            }
+        }
+        return String(v);
+    };
+    const intent = toStr(data.intent).trim() || "(unspecified)";
+    const method = toStr(data.selection_method).trim() || "unknown";
+    const rationale = toStr(data.rationale).trim();
+    const upstream = toStr(data.spec_preview?.upstream_base_url).trim();
+    const tools = Array.isArray(data.spec_preview?.tools) ? data.spec_preview.tools : [];
+    const selectedCount = typeof data.selected_count === "number" ? data.selected_count : tools.length;
+    const linkKey = (m, p) => `${(m || "").toUpperCase()} ${p || ""}`.trim();
+    const endpointRows = tools
+        .map((t) => {
+        const ref = t._endpoint_ref ?? {};
+        const m = (ref.method ?? "").toUpperCase();
+        const p = ref.path_template ?? "";
+        const key = linkKey(m, p);
+        const tags = Array.isArray(ref.tags) && ref.tags.length > 0 ? ref.tags.join(", ") : "";
+        return `
+        <div class="row" data-link="${escapeHtmlAttr(key)}">
+          <div class="row-head">
+            <span class="method ${escapeHtmlAttr(m)}">${escapeHtmlText(m)}</span>
+            <span class="path">${escapeHtmlText(p)}</span>
+          </div>
+          ${tags ? `<div class="row-meta">tags: ${escapeHtmlText(tags)}</div>` : ""}
+        </div>`;
+    })
+        .join("");
+    const toolRows = tools
+        .map((t) => {
+        const ref = t._endpoint_ref ?? {};
+        const key = linkKey(ref.method, ref.path_template);
+        const schemaJson = (() => {
+            try {
+                return JSON.stringify(t.inputSchema ?? {}, null, 2);
+            }
+            catch {
+                return "{}";
+            }
+        })();
+        return `
+        <div class="row" data-link="${escapeHtmlAttr(key)}">
+          <div class="tool-name">${escapeHtmlText(t.name ?? "(unnamed)")}</div>
+          ${t.description ? `<div class="tool-desc">${escapeHtmlText(t.description)}</div>` : ""}
+          <pre class="tool-schema">${escapeHtmlText(schemaJson)}</pre>
+        </div>`;
+    })
+        .join("");
+    const empty = tools.length === 0
+        ? `<div class="empty">No matching endpoints. Try a different intent or run <code>verify_endpoints_live</code> first.</div>`
+        : "";
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>PreMan · MCP Preview</title>
+<style>
+  :root { color-scheme: light dark; --bg:#0d1117; --bg2:#161b22; --border:#30363d; --fg:#e6edf3; --muted:#8b949e; --accent:#58a6ff; --green:#2ea043; --orange:#bf8700; --red:#cf222e; --purple:#8957e5; }
+  * { margin:0; padding:0; box-sizing:border-box; }
+  html, body { height:100%; background:var(--bg); color:var(--fg); font-family:-apple-system,BlinkMacSystemFont,sans-serif; font-size:13px; }
+  body { display:flex; flex-direction:column; overflow:hidden; }
+  header { padding:10px 14px; border-bottom:1px solid var(--border); background:var(--bg2); flex-shrink:0; }
+  header h1 { font-size:13px; font-weight:600; color:var(--accent); }
+  header .meta { font-size:11px; color:var(--muted); margin-top:3px; }
+  header .meta strong { color:var(--fg); font-weight:600; }
+  header .rationale { font-size:11px; color:var(--muted); margin-top:5px; font-style:italic; max-width:900px; }
+  .columns { flex:1; display:grid; grid-template-columns:1fr 1fr; gap:1px; background:var(--border); overflow:hidden; min-height:0; }
+  .col { background:var(--bg); overflow-y:auto; }
+  .col-header { padding:7px 12px; font-size:10px; font-weight:700; letter-spacing:0.06em; text-transform:uppercase; color:var(--muted); border-bottom:1px solid var(--border); position:sticky; top:0; background:var(--bg2); z-index:1; }
+  .row { padding:9px 12px; border-bottom:1px solid var(--border); transition:background 0.1s; }
+  .row:last-child { border-bottom:none; }
+  .row:hover, .row.linked { background:rgba(88,166,255,0.08); }
+  .row-head { display:flex; align-items:center; gap:8px; }
+  .row-meta { font-size:10px; color:var(--muted); margin-top:3px; padding-left:56px; }
+  .method { display:inline-block; min-width:48px; text-align:center; padding:2px 6px; border-radius:3px; font-weight:700; font-size:10px; color:white; font-family:SFMono-Regular,Consolas,monospace; }
+  .method.GET{background:var(--accent);} .method.POST{background:var(--green);} .method.PATCH{background:var(--orange);} .method.PUT{background:var(--purple);} .method.DELETE{background:var(--red);}
+  .path { font-family:SFMono-Regular,Consolas,monospace; font-size:12px; word-break:break-all; }
+  .tool-name { font-family:SFMono-Regular,Consolas,monospace; font-size:12px; font-weight:600; color:var(--accent); }
+  .tool-desc { font-size:11px; color:var(--muted); margin-top:3px; line-height:1.4; }
+  .tool-schema { font-family:SFMono-Regular,Consolas,monospace; font-size:10px; background:var(--bg2); padding:6px 8px; border-radius:3px; margin-top:6px; white-space:pre-wrap; word-break:break-all; max-height:120px; overflow-y:auto; line-height:1.4; color:var(--muted); }
+  .empty { padding:24px; text-align:center; color:var(--muted); font-style:italic; }
+  .empty code { font-family:SFMono-Regular,Consolas,monospace; color:var(--accent); background:var(--bg2); padding:1px 5px; border-radius:3px; font-style:normal; }
+  footer { padding:8px 14px; border-top:1px solid var(--border); background:var(--bg2); display:flex; gap:10px; align-items:center; flex-shrink:0; font-size:11px; color:var(--muted); }
+  footer .upstream { font-family:SFMono-Regular,Consolas,monospace; color:var(--accent); }
+  footer .deploy-hint { margin-left:auto; }
+  footer .deploy-hint code { font-family:SFMono-Regular,Consolas,monospace; color:var(--fg); background:var(--bg); padding:2px 6px; border-radius:3px; }
+</style>
+</head>
+<body>
+  <header>
+    <h1>API → MCP Conversion preview</h1>
+    <div class="meta">
+      Intent: <strong>${escapeHtmlText(intent)}</strong> · Selected <strong>${selectedCount}</strong> endpoint${selectedCount === 1 ? "" : "s"} · Method: ${escapeHtmlText(method)}
+    </div>
+    ${rationale ? `<div class="rationale">${escapeHtmlText(rationale)}</div>` : ""}
+  </header>
+  <main class="columns">
+    <div class="col">
+      <div class="col-header">Your API endpoints (${tools.length})</div>
+      ${endpointRows}${tools.length === 0 ? empty : ""}
+    </div>
+    <div class="col">
+      <div class="col-header">Generated MCP tools (${tools.length})</div>
+      ${toolRows}${tools.length === 0 ? empty : ""}
+    </div>
+  </main>
+  <footer>
+    <span>Upstream: <span class="upstream">${escapeHtmlText(upstream || "(not set)")}</span></span>
+    <span class="deploy-hint">Next: ask the agent to call <code>mcp_deploy</code></span>
+  </footer>
+  <script>
+    document.querySelectorAll('.row[data-link]').forEach(row => {
+      const key = row.getAttribute('data-link');
+      if (!key) return;
+      const matches = () => document.querySelectorAll('[data-link="' + CSS.escape(key) + '"]');
+      row.addEventListener('mouseenter', () => matches().forEach(r => r.classList.add('linked')));
+      row.addEventListener('mouseleave', () => matches().forEach(r => r.classList.remove('linked')));
+    });
+  </script>
+</body>
+</html>`;
+}
+export async function writeMcpPreviewFile(panelHtml) {
+    const outPath = path.join(process.cwd(), "preman-mcp", "mcp-preview-last.html");
+    await fs.mkdir(path.dirname(outPath), { recursive: true });
+    await fs.writeFile(outPath, panelHtml, "utf8");
+    return {
+        absolutePath: outPath,
+        fileUrl: pathToFileURL(outPath).href,
+    };
+}

package/dist/user_auth_flow.d.ts

@@ -0,0 +1,11 @@
+/**
+ * App user auth (JWT) — tools that call the FastAPI backend at PREMAN_BACKEND /auth/*.
+ * Separate from preman_login (device flow + pm_live_ API key). No API key is required
+ * for these tools; for JWT-protected routes, pass the access_token from login/verify.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Register MCP tools for routes/auth (email, OTP, password, JWT).
+ * Proxies to the same process as preman-local (PREMAN_BACKEND, e.g. http://127.0.0.1:8000).
+ */
+export declare function registerUserAuthFlowTools(server: McpServer, backendUrl: string): void;

package/dist/user_auth_flow.js

@@ -0,0 +1,279 @@
+import { z } from "zod";
+function toolError(message, code = "backend_error", hints) {
+    const payload = { error: message, error_code: code };
+    if (hints)
+        payload._agent_hints = hints;
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload) }],
+        isError: true,
+    };
+}
+function jsonOk(obj) {
+    return { content: [{ type: "text", text: JSON.stringify(obj) }] };
+}
+function normalizeBase(backendUrl) {
+    return backendUrl.replace(/\/+$/, "");
+}
+async function callAuthJson(base, method, path, opts) {
+    const url = new URL(path.startsWith("/") ? path.slice(1) : path, `${base}/`);
+    if (opts?.query) {
+        for (const [k, v] of Object.entries(opts.query)) {
+            if (v != null && v !== "")
+                url.searchParams.set(k, v);
+        }
+    }
+    const headers = { Accept: "application/json" };
+    const hasBody = opts?.json != null && (method === "POST" || method === "PUT" || method === "PATCH" || method === "DELETE");
+    if (hasBody) {
+        headers["Content-Type"] = "application/json";
+    }
+    if (opts?.token) {
+        headers.Authorization = `Bearer ${opts.token.trim()}`;
+    }
+    const init = { method, headers };
+    if (hasBody && opts?.json) {
+        init.body = JSON.stringify(opts.json);
+    }
+    const resp = await fetch(url, init);
+    const text = await resp.text();
+    let parsed;
+    try {
+        parsed = text ? JSON.parse(text) : {};
+    }
+    catch {
+        parsed = { raw: text };
+    }
+    const body = typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+        ? parsed
+        : { value: parsed };
+    return {
+        status_code: resp.status,
+        ok: resp.ok,
+        ...body,
+    };
+}
+/**
+ * Register MCP tools for routes/auth (email, OTP, password, JWT).
+ * Proxies to the same process as preman-local (PREMAN_BACKEND, e.g. http://127.0.0.1:8000).
+ */
+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). If the backend does not support this endpoint yet, use user_auth_signup instead.", {
+        email: z.string().describe("User email"),
+    }, async (args) => {
+        try {
+            const r = await callAuthJson(base, "POST", "/auth/start-signup", {
+                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"],
+                });
+            }
+            return jsonOk(r);
+        }
+        catch (e) {
+            const m = e instanceof Error ? e.message : String(e);
+            return toolError(m, "backend_error", {
+                next_actions: ["Ensure PREMAN_BACKEND is running and JWT_SECRET is set on the server."],
+            });
+        }
+    });
+    server.tool("user_auth_signup", "Register with email and password. Sends an OTP; next call user_auth_verify_otp. Uses POST /auth/signup on PREMAN_BACKEND (no API key).", {
+        email: z.string().describe("User email"),
+        password: z.string().describe("Password (min 6 characters on the server)"),
+    }, async (args) => {
+        try {
+            const r = await callAuthJson(base, "POST", "/auth/signup", {
+                json: { email: args.email, password: args.password },
+            });
+            if (!r.ok) {
+                return toolError(String(r.detail ?? r.message ?? "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_verify_otp", "user_auth_login"],
+                });
+            }
+            return jsonOk(r);
+        }
+        catch (e) {
+            const m = e instanceof Error ? e.message : String(e);
+            return toolError(m, "backend_error", {
+                next_actions: ["Ensure PREMAN_BACKEND is running and JWT_SECRET is set on the server."],
+            });
+        }
+    });
+    server.tool("user_auth_verify_otp", "Verify the email OTP and receive access_token (JWT). POST /auth/verify-otp.", { email: z.string(), otp: z.string().describe("6-digit code from email") }, async (args) => {
+        try {
+            const r = await callAuthJson(base, "POST", "/auth/verify-otp", {
+                json: { email: args.email, otp: args.otp },
+            });
+            if (!r.ok) {
+                return toolError(String(r.detail ?? "verify failed"), "auth_required", {
+                    next_actions: ["Request a new code with user_auth_resend_otp if expired."],
+                    related_tools: ["user_auth_resend_otp", "user_auth_signup"],
+                });
+            }
+            return jsonOk(r);
+        }
+        catch (e) {
+            return toolError(e instanceof Error ? e.message : String(e), "backend_error");
+        }
+    });
+    server.tool("user_auth_login", "Login with email and password. Returns access_token if email is verified. POST /auth/login.", { email: z.string(), password: z.string() }, async (args) => {
+        try {
+            const r = await callAuthJson(base, "POST", "/auth/login", {
+                json: { email: args.email, password: args.password },
+            });
+            if (!r.ok) {
+                const sc = r.status_code;
+                const code = sc === 403 || sc === 401 ? "auth_required" : "backend_error";
+                return toolError(String(r.detail ?? "login failed"), code, {
+                    next_actions: [
+                        "If 403 email not verified: use user_auth_verify_otp or user_auth_resend_otp.",
+                        "If 403 migrated account: use user_auth_forgot_password or user_auth_set_password flow.",
+                    ],
+                    related_tools: ["user_auth_verify_otp", "user_auth_needs_password", "user_auth_set_password"],
+                });
+            }
+            return jsonOk(r);
+        }
+        catch (e) {
+            return toolError(e instanceof Error ? e.message : String(e), "backend_error");
+        }
+    });
+    server.tool("user_auth_needs_password", "Check if an account must set a password (e.g. migrated user). GET /auth/needs-password?email=", { email: z.string().optional().describe("Email to check; omit to return false/false from server") }, async (args) => {
+        try {
+            const r = await callAuthJson(base, "GET", "/auth/needs-password", {
+                query: { email: args.email },
+            });
+            if (!r.ok) {
+                return toolError(String(r.detail ?? "request failed"), "backend_error");
+            }
+            return jsonOk(r);
+        }
+        catch (e) {
+            return toolError(e instanceof Error ? e.message : String(e), "backend_error");
+        }
+    });
+    server.tool("user_auth_resend_otp", "Resend verification OTP. POST /auth/resend-otp with { email }.", { email: z.string() }, async (args) => {
+        try {
+            const r = await callAuthJson(base, "POST", "/auth/resend-otp", {
+                json: { email: args.email },
+            });
+            if (!r.ok) {
+                return toolError(String(r.detail ?? "resend failed"), "invalid_input");
+            }
+            return jsonOk(r);
+        }
+        catch (e) {
+            return toolError(e instanceof Error ? e.message : String(e), "backend_error");
+        }
+    });
+    server.tool("user_auth_forgot_password", "Request password reset OTP. POST /auth/forgot-password with { email }.", { email: z.string() }, async (args) => {
+        try {
+            const r = await callAuthJson(base, "POST", "/auth/forgot-password", {
+                json: { email: args.email },
+            });
+            if (!r.ok) {
+                return toolError(String(r.detail ?? "forgot failed"), "backend_error");
+            }
+            return jsonOk(r);
+        }
+        catch (e) {
+            return toolError(e instanceof Error ? e.message : String(e), "backend_error");
+        }
+    });
+    server.tool("user_auth_set_password", "Set a new password using OTP (migrated / forgot flow). Returns access_token. POST /auth/set-password.", {
+        email: z.string(),
+        otp: z.string(),
+        new_password: z.string().min(6),
+    }, async (args) => {
+        try {
+            const r = await callAuthJson(base, "POST", "/auth/set-password", {
+                json: {
+                    email: args.email,
+                    otp: args.otp,
+                    new_password: args.new_password,
+                },
+            });
+            if (!r.ok) {
+                return toolError(String(r.detail ?? "set password failed"), "auth_required", {
+                    next_actions: ["Request a new OTP with user_auth_forgot_password or user_auth_resend_otp."],
+                    related_tools: ["user_auth_forgot_password"],
+                });
+            }
+            return jsonOk(r);
+        }
+        catch (e) {
+            return toolError(e instanceof Error ? e.message : String(e), "backend_error");
+        }
+    });
+    server.tool("user_auth_me", "Current user profile (JWT). GET /auth/me with Authorization: Bearer access_token from login/verify.", {
+        access_token: z.string().describe("JWT from user_auth_login or user_auth_verify_otp"),
+    }, async (args) => {
+        try {
+            const r = await callAuthJson(base, "GET", "/auth/me", {
+                token: args.access_token,
+            });
+            if (!r.ok) {
+                return toolError(String(r.detail ?? "unauthorized"), "auth_required", {
+                    next_actions: ["Call user_auth_login to obtain a fresh access_token."],
+                    related_tools: ["user_auth_login"],
+                });
+            }
+            return jsonOk(r);
+        }
+        catch (e) {
+            return toolError(e instanceof Error ? e.message : String(e), "backend_error");
+        }
+    });
+    server.tool("user_auth_change_password", "Change password for the signed-in user. POST /auth/change-password with JWT.", {
+        access_token: z.string(),
+        current_password: z.string(),
+        new_password: z.string().min(6),
+    }, async (args) => {
+        try {
+            const r = await callAuthJson(base, "POST", "/auth/change-password", {
+                token: args.access_token,
+                json: {
+                    current_password: args.current_password,
+                    new_password: args.new_password,
+                },
+            });
+            if (!r.ok) {
+                return toolError(String(r.detail ?? "change password failed"), r.status_code === 401 ? "auth_required" : "invalid_input", {
+                    related_tools: ["user_auth_login", "user_auth_me"],
+                });
+            }
+            return jsonOk(r);
+        }
+        catch (e) {
+            return toolError(e instanceof Error ? e.message : String(e), "backend_error");
+        }
+    });
+    server.tool("user_auth_delete_account", "Delete the current account. DELETE /auth/me with JWT. Irreversible.", {
+        access_token: z.string().describe("JWT from user_auth_login or user_auth_verify_otp"),
+    }, async (args) => {
+        try {
+            const r = await callAuthJson(base, "DELETE", "/auth/me", {
+                token: args.access_token,
+            });
+            if (!r.ok) {
+                return toolError(String(r.detail ?? "delete failed"), "auth_required", {
+                    related_tools: ["user_auth_login"],
+                });
+            }
+            return jsonOk(r);
+        }
+        catch (e) {
+            return toolError(e instanceof Error ? e.message : String(e), "backend_error");
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "premanmcp",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "PreMan CLI and stdio proxy for PreMan's hosted MCP server",
   "type": "module",
   "bin": {