premanmcp 0.7.1 → 0.9.0

package/bin/connect.js

@@ -10,7 +10,7 @@
  * never fails the connect.
  */
 
-import { execFileSync, spawnSync } from "node:child_process";
+import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { chmodSync, existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -25,6 +25,8 @@ import {
   cliInvocation,
   frontendUrl,
   hasKeyAvailable,
+  LAUNCHER_ARGS,
+  LAUNCHER_COMMAND,
   makeArgs,
   promptSecret,
   promptText,
@@ -51,7 +53,11 @@ const AGENTS = [
     id: "cursor",
     label: "Cursor",
     aliases: ["cursor"],
-    dispatch: { credential: "Cursor API key", needsRoutine: false },
+    dispatch: {
+      credential: "Cursor API key",
+      needsRoutine: false,
+      source: "cursor.com/dashboard → Integrations → API Keys",
+    },
     snippetHint: "merge into ~/.cursor/mcp.json",
     restartHint: 'Fully quit and reopen Cursor, then Settings → MCP → toggle "preman" off and on.',
   },
@@ -59,7 +65,13 @@ const AGENTS = [
     id: "claude_code",
     label: "Claude Code",
     aliases: ["claude", "claude-code", "claude_code", "claudecode"],
-    dispatch: { credential: "Claude Code routine token", needsRoutine: true },
+    dispatch: {
+      credential: "Claude Code routine token",
+      needsRoutine: true,
+      // Named explicitly because "Claude Code routine token" reads like an
+      // Anthropic API key, which is a different credential from a different page.
+      source: "claude.ai/code/routines → your routine → Add API trigger",
+    },
     snippetHint: "run:",
     restartHint: 'Start a new Claude Code session and run `claude mcp list` — "preman" should be listed.',
   },
@@ -95,17 +107,36 @@ function detectAgents() {
   };
 }
 
-async function promptAgentChoice(detected) {
+/**
+ * The agent whose session this command is running inside, if any.
+ *
+ * A better default than "first one installed": someone who types this into an
+ * agent's terminal almost always means that agent, and on a machine with all
+ * three installed the detected-order default is usually wrong.
+ */
+export function runningInside(env = process.env) {
+  if (env.CLAUDECODE || env.CLAUDE_CODE) return "claude_code";
+  if (env.CURSOR_TRACE_ID) return "cursor";
+  return "";
+}
+
+async function promptAgentChoice(detected, insideId = runningInside()) {
   process.stdout.write("Which coding agent?\n");
   AGENTS.forEach((agent, index) => {
-    const mark = detected[agent.id] ? "  (detected)" : "";
+    let mark = "";
+    if (agent.id === insideId) mark = "  (this session)";
+    else if (detected[agent.id]) mark = "  (detected)";
     process.stdout.write(`  ${index + 1}. ${agent.label}${mark}\n`);
   });
 
-  const defaultIndex = Math.max(
-    0,
-    AGENTS.findIndex((a) => detected[a.id])
-  );
+  const inside = AGENTS.findIndex((a) => a.id === insideId);
+  const defaultIndex =
+    inside >= 0
+      ? inside
+      : Math.max(
+          0,
+          AGENTS.findIndex((a) => detected[a.id])
+        );
   const answer = await promptText(`Pick [${defaultIndex + 1}]: `);
   if (!answer) return AGENTS[defaultIndex];
 
@@ -272,8 +303,13 @@ export function renderAllAgentSnippets(args, serverName, { projectInstall = fals
     PREMAN_BACKEND: backendUrl(args),
     PREMAN_FRONTEND: frontendUrl(args),
   };
-  const serverConfig = { command: "npx", args: ["-y", "premanmcp@latest"], env };
-  
+  const serverConfig = {
+    command: LAUNCHER_COMMAND,
+    args: [...LAUNCHER_ARGS],
+    env,
+  };
+
+
   return AGENTS.map((agent) => {
     // Adjust hint based on projectInstall, matching verifyWrittenConfig logic
     let hint = agent.snippetHint;
@@ -319,8 +355,11 @@ export function verifyWrittenConfig(agent, { serverName, written }) {
       if (!block) {
         return { status: "mismatch", detail: `no [mcp_servers.${serverName}] block in ${written.path}` };
       }
-      if (!block.some((line) => line.trim() === 'command = "npx"')) {
-        return { status: "mismatch", detail: `${written.path} does not launch npx` };
+      if (!block.some((line) => line.trim() === `command = "${LAUNCHER_COMMAND}"`)) {
+        return {
+          status: "mismatch",
+          detail: `${written.path} does not launch ${LAUNCHER_COMMAND}`,
+        };
       }
       return { status: "verified" };
     }
@@ -336,8 +375,11 @@ export function verifyWrittenConfig(agent, { serverName, written }) {
 
     const entry = readJsonFile(written.path).mcpServers?.[serverName];
     if (!entry) return { status: "mismatch", detail: `${serverName} is missing from ${written.path}` };
-    if (entry.command !== "npx") {
-      return { status: "mismatch", detail: `${written.path} does not launch npx` };
+    if (entry.command !== LAUNCHER_COMMAND) {
+      return {
+        status: "mismatch",
+        detail: `${written.path} does not launch ${LAUNCHER_COMMAND}`,
+      };
     }
     return { status: "verified" };
   } catch (error) {
@@ -368,6 +410,7 @@ export async function waitForConnection(
   {
     intervalMs = Number(process.env.PREMAN_CONNECT_POLL_MS) || 3000,
     timeoutMs = Number(process.env.PREMAN_CONNECT_WAIT_MS) || 300000,
+    stopWhen = null,
   } = {}
 ) {
   const deadline = Date.now() + timeoutMs;
@@ -383,6 +426,7 @@ export async function waitForConnection(
         token: apiKey,
       });
       if (status.ok && status.connected) return true;
+      if (stopWhen && stopWhen()) return false;
       await new Promise((resolve) => setTimeout(resolve, intervalMs));
     }
   } finally {
@@ -391,9 +435,94 @@ export async function waitForConnection(
   return false;
 }
 
+// ── Auto check-in ───────────────────────────────────────────────────────
+
+/**
+ * How to ask each agent to make one PreMan call without opening its UI.
+ *
+ * The link is established by the agent's first call, so anything that reaches
+ * `preman_status` finishes the connect. Claude Code needs the server on its
+ * allow-list because print mode refuses un-allowed MCP tools rather than
+ * prompting.
+ */
+export function headlessCheckIn(agent, serverName) {
+  const prompt = `Call the ${serverName} MCP tool preman_status and report the result.`;
+  if (agent.id === "cursor") return { bin: "cursor-agent", args: ["-p", prompt] };
+  if (agent.id === "claude_code") {
+    return { bin: "claude", args: ["-p", prompt, "--allowedTools", `mcp__${serverName}`] };
+  }
+  if (agent.id === "codex") return { bin: "codex", args: ["exec", prompt] };
+  return null;
+}
+
+/**
+ * Finish the link ourselves instead of asking the user to go restart their agent.
+ *
+ * The config on disk is already correct at this point; all that is missing is
+ * one call from the agent, and telling someone to make it from another terminal
+ * is a dead end in the one terminal they are sitting in. So run the agent
+ * headlessly and poll for the check-in it produces.
+ *
+ * Returns `ran: false` when the agent's binary is absent or will not start, and
+ * the caller falls back to the printed instructions.
+ */
+export async function autoCheckIn(
+  args,
+  agent,
+  apiKey,
+  {
+    // Never outlast the connect's own wait budget: this phase is part of it, not
+    // an extra one bolted on the front.
+    timeoutMs = Math.min(
+      Number(process.env.PREMAN_AUTO_CHECKIN_MS) || 120000,
+      Number(process.env.PREMAN_CONNECT_WAIT_MS) || 300000
+    ),
+    serverName = "preman",
+    intervalMs = Number(process.env.PREMAN_CONNECT_POLL_MS) || 3000,
+  } = {}
+) {
+  const spec = headlessCheckIn(agent, serverName);
+  if (!spec) return { ran: false, connected: false, reason: "no headless mode" };
+  if (!onPath(spec.bin)) return { ran: false, connected: false, reason: `${spec.bin} is not on PATH` };
+
+  let child;
+  try {
+    child = spawn(spec.bin, spec.args, { stdio: "ignore" });
+  } catch (error) {
+    return { ran: false, connected: false, reason: error.message };
+  }
+
+  let spawnError = null;
+  let exitedAt = 0;
+  child.on("error", (error) => {
+    spawnError = error;
+    exitedAt = exitedAt || Date.now();
+  });
+  child.on("exit", () => {
+    exitedAt = exitedAt || Date.now();
+  });
+
+  // The check-in can land moments after the agent's own process ends, so keep
+  // polling briefly past its exit rather than declaring failure at the edge.
+  const grace = intervalMs * 2;
+  try {
+    const connected = await waitForConnection(args, apiKey, {
+      intervalMs,
+      timeoutMs,
+      stopWhen: () => Boolean(exitedAt) && Date.now() - exitedAt > grace,
+    });
+    if (spawnError && !connected) {
+      return { ran: false, connected: false, reason: spawnError.message };
+    }
+    return { ran: true, connected, command: spec.bin };
+  } finally {
+    if (child.exitCode === null && child.signalCode === null) child.kill();
+  }
+}
+
 // ── Dispatch credential (SCRUM-124) ─────────────────────────────────────
 
-async function captureDispatchCredential(args, agent, apiKey) {
+async function captureDispatchCredential(args, agent, apiKey, { prompt = true } = {}) {
   if (!agent.dispatch) return;
   if (args.has("--skip-dispatch-credential")) return;
 
@@ -401,19 +530,20 @@ async function captureDispatchCredential(args, agent, apiKey) {
   let routineId = args.value("--routine-id", "");
 
   if (!secret) {
-    if (!process.stdin.isTTY) return;
+    if (!prompt || !process.stdin.isTTY) return;
     // Framed as the expected step rather than an optional aside. Without it
     // PreMan can only suggest fixes; with it, it can run them. Presenting it as
     // "optional, press Enter to skip" meant almost everyone skipped the thing
     // that makes the product act rather than advise.
     process.stdout.write(
-      `\nLet PreMan start ${agent.label} runs for you — it can then apply fixes and\n` +
-        `run checks on a schedule instead of only telling you what to do.\n`
+      `\nOptional — let PreMan start ${agent.label} runs for you, so it can apply\n` +
+        `fixes and run checks on a schedule instead of only telling you what to do.\n` +
+        `Get the token from ${agent.dispatch.source}.\n`
     );
-    secret = await promptSecret(`Paste your ${agent.dispatch.credential} (Enter to set up later): `);
+    secret = await promptSecret(`Paste your ${agent.dispatch.credential} (Enter to skip): `);
     if (!secret) {
       process.stdout.write(
-        `Skipped. Run '${cliInvocation()} connect --agent ${agent.id.replace("_", "-")}' when you have the token.\n`
+        `Skipped. Run '${cliInvocation()} dispatch --agent ${agent.id.replace("_", "-")}' when you have the token.\n`
       );
       return;
     }
@@ -445,6 +575,64 @@ async function captureDispatchCredential(args, agent, apiKey) {
   }
 }
 
+export const DISPATCH_HELP = `
+Dispatch options:
+  --agent <name>              cursor | claude-code (defaults to the connected agent)
+  --dispatch-credential <t>   Cloud-dispatch token (non-interactive)
+  --routine-id <id>           Claude Code routine id, with --dispatch-credential
+  --api-key <key>             PreMan API key. If omitted, stored credentials are used
+  --backend <url>             PreMan backend URL
+`;
+
+/**
+ * `preman dispatch` — store the cloud-dispatch credential on its own.
+ *
+ * Exists so connect never has to ask for a token mid-onboarding. Someone who
+ * skipped it (or did not have it yet) comes back here instead of re-running the
+ * whole connect.
+ */
+export async function dispatchCommand(commandArgs) {
+  const args = makeArgs(commandArgs);
+  const apiKey = resolveApiKey(args);
+  if (!apiKey) {
+    throw new ConnectError(
+      `No PreMan credentials. Run '${cliInvocation()} connect' first, or pass --api-key pm_live_….`,
+      EXIT_USAGE
+    );
+  }
+
+  let agent = findAgent(args.value("--agent", ""));
+  if (!agent && args.value("--agent", "")) {
+    throw new ConnectError(
+      `Unknown agent: ${args.value("--agent", "")}. Use cursor or claude-code.`,
+      EXIT_USAGE
+    );
+  }
+
+  if (!agent) {
+    const current = await callBackendJson(args, "GET", "/workbench/coding-agent", { token: apiKey });
+    agent = findAgent(current.ok ? current.agent : "");
+    if (!agent) {
+      throw new ConnectError(
+        "Could not tell which agent to set up. Pass --agent cursor or --agent claude-code.",
+        EXIT_USAGE
+      );
+    }
+  }
+
+  if (!agent.dispatch) {
+    throw new ConnectError(`${agent.label} has no cloud-dispatch API yet.`, EXIT_USAGE);
+  }
+  if (!args.value("--dispatch-credential", "") && !process.stdin.isTTY) {
+    throw new ConnectError(
+      "preman dispatch needs a terminal, or --dispatch-credential <token>.",
+      EXIT_USAGE
+    );
+  }
+
+  await captureDispatchCredential(args, agent, apiKey);
+}
+
 /** Accept either a bare trig_… id or the routine URL it appears in. */
 export function extractRoutineId(value) {
   const raw = String(value || "").trim();
@@ -589,6 +777,7 @@ Connect options:
   --project                   Write project-local config instead of the user config
   --api-key <key>             PreMan API key. If omitted, stored credentials are used
   --email <email>             Pre-fill the email prompt when logging in
+  --password [value]          Also set a dashboard password (signup asks for none)
   --backend <url>             PreMan backend URL
   --frontend <url>            PreMan frontend URL
   --name <name>               MCP server name. Defaults to preman
@@ -597,6 +786,7 @@ Connect options:
   --skip-dispatch-credential  Do not ask for a cloud-dispatch credential
   --skip-login                Write config without interactive terminal auth
   --no-pair                   Do not mint a pair code
+  --no-auto-checkin           Do not run the agent to finish the link
   --no-wait                   Do not wait for the agent to check in
   --no-guide                  Skip the guided first run after connecting
   --print                     Print the config instead of writing it
@@ -617,31 +807,23 @@ export async function connectCommand(commandArgs) {
     );
   }
 
-  if (!agent) {
-    if (!interactive) {
-      // Nothing to prompt on, so leave behind everything a CI log needs to
-      // finish the setup by hand rather than just the reason it stopped.
-      process.stdout.write(
-        `preman connect needs a terminal to pick an agent. Copy-paste setup instead:\n\n${renderAllAgentSnippets(args, serverName, { projectInstall })}\n` +
-          'Then restart your agent and ask it: "run preman_status".\n' +
-          "Or rerun: preman connect --agent <cursor|claude-code|codex> --api-key pm_live_…\n"
-      );
-      throw new ConnectError(
-        "preman connect needs a terminal. In CI pass --agent <cursor|claude-code|codex> " +
-          "and --api-key pm_live_… (or --print), or use one of the snippets above.",
-        EXIT_USAGE
-      );
-    }
-    agent = await promptAgentChoice(detectAgents());
-  }
-
-  if (!printOnly) {
-    // Verify the machine can run what we are about to write — before any
-    // config edits or logins, so failures leave nothing half-done.
-    await preflight(args);
+  // Nothing to prompt on, so leave behind everything a CI log needs to finish
+  // the setup by hand rather than just the reason it stopped.
+  if (!agent && !interactive) {
+    process.stdout.write(
+      `preman connect needs a terminal to pick an agent. Copy-paste setup instead:\n\n${renderAllAgentSnippets(args, serverName, { projectInstall })}\n` +
+        'Then restart your agent and ask it: "run preman_status".\n' +
+        "Or rerun: preman connect --agent <cursor|claude-code|codex> --api-key pm_live_…\n"
+    );
+    throw new ConnectError(
+      "preman connect needs a terminal. In CI pass --agent <cursor|claude-code|codex> " +
+        "and --api-key pm_live_… (or --print), or use one of the snippets above.",
+      EXIT_USAGE
+    );
   }
 
   if (printOnly) {
+    if (!agent) agent = await promptAgentChoice(detectAgents());
     const serverConfig = buildServerConfig(args);
     if (agent.id === "codex") {
       process.stdout.write(renderCodexToml(serverName, serverConfig));
@@ -651,6 +833,12 @@ export async function connectCommand(commandArgs) {
     return;
   }
 
+  // Verify the machine can run what we are about to write — before any config
+  // edits or logins, so failures leave nothing half-done.
+  await preflight(args);
+
+  // Account first, so "First, let's connect your PreMan account" is not the
+  // second thing that happens.
   if (!args.has("--skip-login") && !hasKeyAvailable(args)) {
     if (!interactive) {
       throw new ConnectError(
@@ -663,6 +851,8 @@ export async function connectCommand(commandArgs) {
     process.stdout.write("\n");
   }
 
+  if (!agent) agent = await promptAgentChoice(detectAgents());
+
   const apiKey = resolveApiKey(args);
 
   let pairCode = "";
@@ -695,27 +885,19 @@ export async function connectCommand(commandArgs) {
     );
   }
 
-  // Not gated on TTY: --dispatch-credential is the non-interactive path, and the
-  // prompt inside only runs when there is a terminal to prompt on.
-  await captureDispatchCredential(args, agent, apiKey);
-
+  // A non-interactive run can still be handed the credential up front, so this
+  // stays reachable; the prompt inside only fires when there is a TTY, and by
+  // then onboarding is done.
   if (!pairCode || args.has("--no-wait") || !interactive) {
+    await captureDispatchCredential(args, agent, apiKey);
     process.stdout.write(nextStepsBlock(agent));
     return;
   }
 
-  process.stdout.write(
-    `\nRestart ${agent.label} and ask it: "run preman_status"\n` +
-      "Waiting for your agent to check in… (Ctrl+C to stop waiting)\n"
-  );
-
-  if (!(await waitForConnection(args, apiKey))) {
-    process.stdout.write(
-      "No check-in yet. Troubleshooting:\n" +
-        `  - ${agent.restartHint}\n` +
-        `  - Config written to: ${written.path}\n` +
-        `  - Then ask ${agent.label} to "run preman_status" — it links on its first PreMan call.\n`
-    );
+  if (!(await establishCheckIn(args, agent, apiKey, { serverName, written }))) {
+    // Still honour an explicitly-passed credential, but do not open a new prompt
+    // on top of a connect that just told the user something went wrong.
+    await captureDispatchCredential(args, agent, apiKey, { prompt: false });
     return;
   }
 
@@ -723,4 +905,42 @@ export async function connectCommand(commandArgs) {
   if (!args.has("--no-guide")) {
     await guidedFirstRun(args, agent);
   }
+  await captureDispatchCredential(args, agent, apiKey);
+}
+
+/**
+ * Get the agent to make its first PreMan call, by whatever means work here.
+ *
+ * Prefers running it for the user; falls back to asking them to restart it and
+ * waiting, which is all this ever did. Returns whether the check-in landed, and
+ * prints the troubleshooting block itself when it did not.
+ */
+async function establishCheckIn(args, agent, apiKey, { serverName, written }) {
+  if (!args.has("--no-auto-checkin")) {
+    const spec = headlessCheckIn(agent, serverName);
+    if (spec && onPath(spec.bin)) {
+      process.stdout.write(`\nStarting ${agent.label} to finish the link…\n`);
+    }
+    const auto = await autoCheckIn(args, agent, apiKey, { serverName });
+    if (auto.connected) return true;
+    if (auto.ran) {
+      process.stdout.write(`${agent.label} ran but did not check in.\n`);
+    }
+  }
+
+  process.stdout.write(
+    `\nRestart ${agent.label} and ask it: "run preman_status"\n` +
+      "Waiting for your agent to check in… (Ctrl+C to stop waiting)\n"
+  );
+
+  if (await waitForConnection(args, apiKey)) return true;
+
+  process.stdout.write(
+    "No check-in yet. Troubleshooting:\n" +
+      `  - ${agent.restartHint}\n` +
+      `  - Config written to: ${written.path}\n` +
+      `  - Then ask ${agent.label} to "run preman_status" — it links on its first PreMan call.\n` +
+      `  - Then: ${cliInvocation()} connect --agent ${agent.id.replace("_", "-")}\n`
+  );
+  return false;
 }