premanmcp 0.3.4 → 0.4.0

package/bin/hosted.js

@@ -0,0 +1,455 @@
+/**
+ * Hosted MCP commands: link / tools / run.
+ *
+ * Drives a published PreMan hosted MCP from the terminal over the same surface
+ * agents use — POST /h/{id}/mcp, same selection, same consumer token, same
+ * audit trail. Nothing here talks to a PreMan control-plane API: this is
+ * packaging over the shipped runtime.
+ *
+ * Profiles live in ~/.preman/cli.json so `--env staging` picks a target. The
+ * runtime has no server-side notion of an environment; an env is a named
+ * profile pointing at one published hosted MCP.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+
+const PREMAN_DIR = path.join(os.homedir(), ".preman");
+const CLI_CONFIG_FILE = path.join(PREMAN_DIR, "cli.json");
+const DEFAULT_BACKEND = "https://api.preman.live";
+const CONSUMER_TOKEN_PREFIX = "pm_hmcp_";
+const DEFAULT_TIMEOUT_MS = 60000;
+
+export const EXIT_TOOL_ERROR = 1;
+export const EXIT_USAGE = 2;
+export const EXIT_AUTH = 3;
+export const EXIT_RPC = 4;
+export const EXIT_NETWORK = 5;
+
+export class CliError extends Error {
+  constructor(message, exitCode = EXIT_USAGE) {
+    super(message);
+    this.exitCode = exitCode;
+  }
+}
+
+// --- arg parsing (mirrors bin/cli.js; no --flag=value form) -----------------
+
+function makeArgs(commandArgs) {
+  return {
+    positional: commandArgs.filter((a, i) => {
+      if (a.startsWith("-")) return false;
+      const prev = commandArgs[i - 1];
+      return !(prev && prev.startsWith("-") && !FLAGS.has(prev));
+    }),
+    value(name, fallback = "") {
+      const index = commandArgs.indexOf(name);
+      if (index === -1) return fallback;
+      return commandArgs[index + 1] || fallback;
+    },
+    all(name) {
+      const out = [];
+      commandArgs.forEach((a, i) => {
+        if (a === name && commandArgs[i + 1]) out.push(commandArgs[i + 1]);
+      });
+      return out;
+    },
+    has(name) {
+      return commandArgs.includes(name);
+    },
+  };
+}
+
+// Boolean flags take no value, so the token after them is still positional.
+const FLAGS = new Set(["--default", "--no-verify", "--json-out", "--quiet"]);
+
+// --- profile store ---------------------------------------------------------
+
+export function readCliConfig() {
+  if (!existsSync(CLI_CONFIG_FILE)) return { version: 1, profiles: {} };
+  const raw = readFileSync(CLI_CONFIG_FILE, "utf8").trim();
+  if (!raw) return { version: 1, profiles: {} };
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new CliError(`Could not parse ${CLI_CONFIG_FILE}: ${error.message}`);
+  }
+  if (!parsed.profiles || typeof parsed.profiles !== "object") parsed.profiles = {};
+  if (!parsed.version) parsed.version = 1;
+  return parsed;
+}
+
+function writeCliConfig(config) {
+  mkdirSync(PREMAN_DIR, { recursive: true, mode: 0o700 });
+  writeFileSync(CLI_CONFIG_FILE, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+}
+
+export function maskToken(token) {
+  if (!token) return "(none)";
+  return `${CONSUMER_TOKEN_PREFIX}…${String(token).slice(-4)}`;
+}
+
+/** Accept a full /h/<id>/mcp URL or a bare hosted MCP id. */
+export function resolveMcpUrl(target, backend) {
+  const value = String(target || "").trim();
+  if (!value) throw new CliError("Missing hosted MCP URL or id.");
+  if (/^https?:\/\//i.test(value)) {
+    return value.replace(/\/+$/, "");
+  }
+  if (value.includes("/")) {
+    throw new CliError(`Not a hosted MCP id or URL: ${value}`);
+  }
+  const base = (backend || process.env.PREMAN_BACKEND || DEFAULT_BACKEND).replace(/\/+$/, "");
+  return `${base}/h/${value}/mcp`;
+}
+
+/**
+ * Pick the target profile.
+ *
+ * --env wins, then PREMAN_MCP_URL (so CI needs no config file), then the
+ * default profile, then a lone profile. Anything else is ambiguous.
+ */
+export function resolveProfile(config, envName, { toolPrefix = "" } = {}) {
+  const profiles = config.profiles || {};
+  const names = Object.keys(profiles);
+
+  if (envName && toolPrefix) {
+    throw new CliError(
+      `Ambiguous target: --env ${envName} together with the dotted form '${toolPrefix}.…'. Use one.`,
+    );
+  }
+
+  const wanted = envName || toolPrefix;
+  if (wanted) {
+    if (profiles[wanted]) return { name: wanted, ...profiles[wanted] };
+    const byAlias = names.find((n) => profiles[n].alias === wanted);
+    if (byAlias) return { name: byAlias, ...profiles[byAlias] };
+    const known = names.length ? names.join(", ") : "none";
+    throw new CliError(`No profile named '${wanted}'. Linked profiles: ${known}.`);
+  }
+
+  if (process.env.PREMAN_MCP_URL) {
+    return {
+      name: "(env)",
+      mcp_url: process.env.PREMAN_MCP_URL.replace(/\/+$/, ""),
+      token: process.env.PREMAN_MCP_TOKEN || "",
+    };
+  }
+
+  const preferred = config.default_profile;
+  if (preferred && profiles[preferred]) return { name: preferred, ...profiles[preferred] };
+  if (names.length === 1) return { name: names[0], ...profiles[names[0]] };
+
+  if (!names.length) {
+    throw new CliError(
+      "No hosted MCP linked. Run: preman link <mcp-url-or-id> --env <name> [--token pm_hmcp_…]",
+    );
+  }
+  throw new CliError(`Multiple profiles linked (${names.join(", ")}). Pass --env <name>.`);
+}
+
+// --- JSON-RPC over the hosted runtime --------------------------------------
+
+let cachedVersion = null;
+function cliVersion() {
+  if (cachedVersion) return cachedVersion;
+  try {
+    const pkgPath = new URL("../package.json", import.meta.url);
+    cachedVersion = JSON.parse(readFileSync(pkgPath, "utf8")).version || "0.0.0";
+  } catch {
+    cachedVersion = "0.0.0";
+  }
+  return cachedVersion;
+}
+
+/**
+ * The runtime answers HTTP 200 even for errors — the JSON-RPC envelope is the
+ * only source of truth, so never branch on resp.status here.
+ */
+export async function mcpRpc(profile, method, params, { timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const headers = {
+    "Content-Type": "application/json",
+    Accept: "application/json, text/event-stream",
+  };
+  if (profile.token) headers.Authorization = `Bearer ${profile.token}`;
+
+  let resp;
+  try {
+    resp = await fetch(profile.mcp_url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (error) {
+    const reason = error?.name === "TimeoutError" ? "timed out" : error.message;
+    throw new CliError(`Could not reach ${profile.mcp_url}: ${reason}`, EXIT_NETWORK);
+  }
+
+  const text = await resp.text();
+  let envelope;
+  try {
+    envelope = JSON.parse(text);
+  } catch {
+    throw new CliError(
+      `Unexpected non-JSON response from ${profile.mcp_url} (HTTP ${resp.status}).`,
+      EXIT_NETWORK,
+    );
+  }
+
+  if (envelope.error) {
+    const { code, message } = envelope.error;
+    if (code === -32001) {
+      throw new CliError(
+        `Authentication failed for profile '${profile.name}'. ` +
+          "Re-link with a valid consumer token: preman link <url> --env <name> --token pm_hmcp_…",
+        EXIT_AUTH,
+      );
+    }
+    if (code === -32601 && method === "tools/call") {
+      throw new CliError(
+        `${message || "Unknown tool"}. Run 'preman tools${
+          profile.name && profile.name !== "(env)" ? ` --env ${profile.name}` : ""
+        }' to list available tools.`,
+        EXIT_RPC,
+      );
+    }
+    throw new CliError(message || `JSON-RPC error ${code}`, EXIT_RPC);
+  }
+  return envelope.result;
+}
+
+async function initialize(profile, timeoutMs) {
+  // Sending clientInfo lets the runtime attribute invocations to the CLI.
+  return mcpRpc(
+    profile,
+    "initialize",
+    {
+      protocolVersion: "2024-11-05",
+      capabilities: {},
+      clientInfo: { name: "preman-cli", version: cliVersion() },
+    },
+    { timeoutMs },
+  );
+}
+
+// --- argument assembly -----------------------------------------------------
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+/** `key=value` is a string; `key:=value` is parsed as JSON. */
+export function parseArgPairs(pairs, base = {}) {
+  const out = { ...base };
+  for (const pair of pairs) {
+    const jsonIndex = pair.indexOf(":=");
+    const eqIndex = pair.indexOf("=");
+    if (jsonIndex !== -1 && (eqIndex === -1 || jsonIndex < eqIndex)) {
+      const key = pair.slice(0, jsonIndex);
+      const raw = pair.slice(jsonIndex + 2);
+      try {
+        out[key] = JSON.parse(raw);
+      } catch {
+        throw new CliError(`--arg ${key}:= expects JSON, got ${raw === "" ? "(empty)" : raw}`);
+      }
+      continue;
+    }
+    if (eqIndex === -1) {
+      throw new CliError(`--arg expects key=value or key:=json, got '${pair}'`);
+    }
+    out[pair.slice(0, eqIndex)] = pair.slice(eqIndex + 1);
+  }
+  return out;
+}
+
+async function buildToolArguments(args) {
+  let base = {};
+  const jsonArg = args.value("--json", "");
+  if (jsonArg) {
+    const raw = jsonArg === "-" ? await readStdin() : jsonArg;
+    try {
+      base = JSON.parse(raw);
+    } catch (error) {
+      throw new CliError(`--json expects a JSON object: ${error.message}`);
+    }
+    if (base === null || typeof base !== "object" || Array.isArray(base)) {
+      throw new CliError("--json must be a JSON object.");
+    }
+  }
+  return parseArgPairs(args.all("--arg"), base);
+}
+
+async function promptToken() {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return (await rl.question("Consumer token (pm_hmcp_…, blank for public MCPs): ")).trim();
+  } finally {
+    rl.close();
+  }
+}
+
+// --- commands --------------------------------------------------------------
+
+export async function linkCommand(commandArgs) {
+  const args = makeArgs(commandArgs);
+  const target = args.positional[0];
+  const envName = args.value("--env", "");
+  if (!target) throw new CliError("Usage: preman link <mcp-url-or-id> --env <name> [--token pm_hmcp_…]");
+  if (!envName) throw new CliError("preman link requires --env <name> to save the profile under.");
+
+  const mcpUrl = resolveMcpUrl(target, args.value("--backend", ""));
+  let token = args.value("--token", "") || process.env.PREMAN_MCP_TOKEN || "";
+  if (!token && process.stdin.isTTY) token = await promptToken();
+
+  if (token && !token.startsWith(CONSUMER_TOKEN_PREFIX)) {
+    process.stderr.write(
+      `[preman] Warning: consumer tokens normally start with ${CONSUMER_TOKEN_PREFIX}.\n`,
+    );
+  }
+
+  const profile = { name: envName, mcp_url: mcpUrl, token };
+  let alias = args.value("--alias", "");
+  let toolCount = null;
+
+  if (!args.has("--no-verify")) {
+    const info = await initialize(profile);
+    if (!alias) alias = info?.serverInfo?.name || "";
+    const listed = await mcpRpc(profile, "tools/list", {});
+    toolCount = (listed?.tools || []).length;
+  }
+
+  const config = readCliConfig();
+  config.profiles[envName] = {
+    mcp_url: mcpUrl,
+    ...(token ? { token } : {}),
+    ...(alias ? { alias } : {}),
+    linked_at: new Date().toISOString(),
+  };
+  if (args.has("--default") || !config.default_profile) config.default_profile = envName;
+  writeCliConfig(config);
+
+  process.stdout.write(
+    `Linked '${envName}' → ${mcpUrl}\n` +
+      `  token: ${token ? maskToken(token) : "(none — public access)"}\n` +
+      (toolCount === null ? "  (verification skipped)\n" : `  tools available: ${toolCount}\n`) +
+      `  saved to ${CLI_CONFIG_FILE}\n`,
+  );
+}
+
+export async function toolsCommand(commandArgs) {
+  const args = makeArgs(commandArgs);
+  const config = readCliConfig();
+  const profile = resolveProfile(config, args.value("--env", ""));
+  const timeoutMs = Number(args.value("--timeout", "")) * 1000 || DEFAULT_TIMEOUT_MS;
+
+  const result = await mcpRpc(profile, "tools/list", {}, { timeoutMs });
+  const tools = result?.tools || [];
+  if (args.has("--json-out")) {
+    process.stdout.write(`${JSON.stringify(tools, null, 2)}\n`);
+    return;
+  }
+  if (!tools.length) {
+    process.stdout.write(`No tools published on '${profile.name}'.\n`);
+    return;
+  }
+  process.stdout.write(`${tools.length} tool(s) on '${profile.name}':\n`);
+  for (const tool of tools) {
+    const required = tool.inputSchema?.required || [];
+    const suffix = required.length ? `  (required: ${required.join(", ")})` : "";
+    process.stdout.write(`  ${tool.name}${suffix}\n`);
+    if (tool.description) process.stdout.write(`      ${tool.description}\n`);
+  }
+}
+
+export async function runCommand(commandArgs) {
+  const args = makeArgs(commandArgs);
+  const selection = args.positional[0];
+  if (!selection) {
+    throw new CliError(
+      "Usage: preman run <tool> [--env <name>] [--arg key=value] [--json '{...}']",
+    );
+  }
+
+  // Dotted form addresses a profile explicitly: <profile-or-alias>.<tool>
+  const dot = selection.indexOf(".");
+  const toolPrefix = dot > 0 ? selection.slice(0, dot) : "";
+  const toolName = dot > 0 ? selection.slice(dot + 1) : selection;
+  if (dot > 0 && !toolName) throw new CliError(`Missing tool name after '${toolPrefix}.'`);
+
+  const config = readCliConfig();
+  const profile = resolveProfile(config, args.value("--env", ""), { toolPrefix });
+  const toolArguments = await buildToolArguments(args);
+  const timeoutMs = Number(args.value("--timeout", "")) * 1000 || DEFAULT_TIMEOUT_MS;
+
+  const result = await mcpRpc(
+    profile,
+    "tools/call",
+    { name: toolName, arguments: toolArguments },
+    { timeoutMs },
+  );
+
+  if (args.has("--json-out")) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    for (const block of result?.content || []) {
+      if (typeof block?.text === "string") process.stdout.write(`${block.text}\n`);
+    }
+    const status = result?._meta?.status;
+    if (status !== undefined && !args.has("--quiet")) {
+      process.stderr.write(`[preman] upstream status ${status}\n`);
+    }
+  }
+
+  if (result?.isError) {
+    // The runtime reports an unmatched tool name as an isError result rather
+    // than a JSON-RPC error, so point at the discovery command from here too.
+    const text = (result.content || []).map((b) => b?.text || "").join(" ");
+    if (/unknown tool/i.test(text)) {
+      process.stderr.write(
+        `[preman] Run 'preman tools${
+          profile.name && profile.name !== "(env)" ? ` --env ${profile.name}` : ""
+        }' to list available tools.\n`,
+      );
+    }
+    process.exitCode = EXIT_TOOL_ERROR;
+  }
+}
+
+export const HOSTED_HELP = `
+Hosted MCP (drive a published selection from the terminal):
+  preman link <mcp-url-or-id> --env <name>   Save a hosted MCP profile and verify it
+  preman tools [--env <name>]                List callable tools on the linked MCP
+  preman run <tool> [--env <name>] [args]    Call a tool and print the result
+
+Link options:
+  --env <name>          Profile name to save under (required)
+  --token <pm_hmcp_…>   Consumer token (or PREMAN_MCP_TOKEN, or prompted; omit for public MCPs)
+  --backend <url>       Backend URL when passing a bare MCP id. Defaults to ${DEFAULT_BACKEND}
+  --alias <name>        Short name usable in the dotted form
+  --default             Make this the default profile
+  --no-verify           Skip the initialize + tools/list check
+
+Run options:
+  --env <name>          Profile to use. Falls back to PREMAN_MCP_URL, then the default profile
+  --arg key=value       String argument (repeatable)
+  --arg key:=json       JSON-typed argument, e.g. --arg qty:=2 (repeatable)
+  --json '{...}'        Full arguments object ('--json -' reads stdin)
+  --timeout <seconds>   Client-side timeout. Defaults to 60
+  --json-out            Print the raw JSON-RPC result
+  <tool> may be dotted: <profile-or-alias>.<tool_name>
+
+Hosted MCP environment:
+  PREMAN_MCP_URL        Hosted MCP endpoint (…/h/<id>/mcp); used when --env is omitted
+  PREMAN_MCP_TOKEN      Consumer token for PREMAN_MCP_URL
+
+Examples:
+  preman link https://api.preman.live/h/2f6c…/mcp --env staging --token pm_hmcp_xxx
+  preman tools --env staging
+  preman run post_users_id_orders --env staging --arg id=42 --json '{"body":{"sku":"A1"}}'
+`;

package/dist/auth_flow_ui.d.ts

@@ -18,6 +18,8 @@ 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: {
@@ -32,4 +34,5 @@ export declare function shareAuthFlowToUi(opts: {
     upstreamBaseUrl?: string;
     sessionId?: string;
     intent?: string;
+    apiKey?: string;
 }): Promise<ShareAuthFlowResult>;

package/dist/auth_flow_ui.js

@@ -110,6 +110,10 @@ export function buildAuthFlowEndpoints() {
 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) => ({
@@ -118,11 +122,16 @@ export async function shareAuthFlowToUi(opts) {
     }));
     const resp = await fetch(`${backend}/agent-sessions/${encodeURIComponent(sessionId)}/endpoints`, {
         method: "POST",
-        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        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();
@@ -142,11 +151,13 @@ export async function shareAuthFlowToUi(opts) {
         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. Test signup → verify-otp → login, or resend-otp. " +
+            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: [