premanmcp 1.1.11 → 1.1.12

package/bin/account.js

@@ -9,18 +9,23 @@
 
 import { existsSync, rmSync } from "node:fs";
 import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 
 import { detectCandidates } from "./detect.js";
 import { DESKTOP_SESSION_FILE } from "./desktop.js";
 import { hookStatus } from "./hook.js";
 import {
   CREDENTIALS_FILE,
+  MIN_NODE_MAJOR,
   backendUrl,
   callBackendJson,
   cliInvocation,
   frontendUrl,
   makeArgs,
+  nodeTooOld,
   openUrl,
+  pathPremanOwner,
   readStoredCredentials,
   resolveApiKey,
   saveStoredCredentials,
@@ -110,6 +115,49 @@ export async function doctorCommand(commandArgs = []) {
   const results = [];
   let failures = 0;
 
+  // The install itself, first, because everything below assumes it works.
+  // Doctor checked the account, the backend, the repo and the hook -- five
+  // things on the far side of a CLI that can run -- and nothing about the CLI.
+  // So the two failures that make every other line meaningless, a Node too old
+  // for fetch and a `preman` on PATH that belongs to something else, were the
+  // two it could not report.
+  const oldNode = nodeTooOld();
+  results.push(
+    line(
+      "node",
+      !oldNode,
+      oldNode ? `${process.versions.node} — needs ${MIN_NODE_MAJOR}+` : process.versions.node
+    )
+  );
+  if (oldNode) failures += 1;
+
+  // `preman` resolving to something other than this package is why a hook
+  // installed under one Node reports "Unknown command: verify" after an nvm
+  // switch, and why the printed instructions fall back to re-resolving the
+  // package from the network on every push.
+  const owner = pathPremanOwner();
+  results.push(
+    line(
+      "preman on PATH",
+      owner === "premanmcp",
+      owner === "premanmcp"
+        ? "premanmcp"
+        : owner
+          ? `owned by ${owner}, not premanmcp — commands will use \`${cliInvocation()}\``
+          : `not on PATH — commands will use \`${cliInvocation()}\``
+    )
+  );
+
+  // The MCP server is compiled, and `npm exec` fetches the published package
+  // rather than this checkout, so a missing dist is invisible until a host
+  // launches the server and gets nothing.
+  const serverPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "dist", "server.js");
+  const built = existsSync(serverPath);
+  results.push(
+    line("mcp server", built, built ? "dist/server.js" : "dist/server.js missing — run `npm run build`")
+  );
+  if (!built) failures += 1;
+
   const stored = readStoredCredentials();
   const token = resolveApiKey(args);
   results.push(

package/bin/cli.js

@@ -40,6 +40,7 @@ import { HOOK_HELP, hookCommand, installHook, scheduleHookRepair } from "./hook.
 import { EVAL_HELP } from "./eval.js";
 import { TARGET_HELP, targetCommand } from "./target.js";
 import { RUNNER_HELP, runnerCommand } from "./runner.js";
+import { PROBE_HELP, probeCommand } from "./probe.js";
 import { VERIFY_HELP, verifyCommand } from "./verify.js";
 import {
   DESKTOP_HELP,
@@ -59,6 +60,7 @@ import {
   buildServerConfig,
   hasKeyAvailable,
   makeArgs,
+  nodeTooOld,
   readStoredCredentials,
 } from "./shared.js";
 
@@ -73,6 +75,16 @@ const ROOT = path.join(__dirname, "..");
 // argument parsing is still attributable.
 process.title = "preman";
 
+// Before anything else that could need it. `start` is exempt: an MCP host
+// launched it, the host is the only thing reading this stream, and a line of
+// prose on stdout is a protocol violation -- the preflight inside `connect`
+// already refuses that case in a way the host can render.
+const tooOld = nodeTooOld();
+if (tooOld && !(process.argv[2] === "start" || !process.stdin.isTTY)) {
+  process.stderr.write(tooOld);
+  process.exit(1);
+}
+
 const args = process.argv.slice(2);
 // A bare `preman` in a terminal opens the agent session: that is what the
 // product is in a terminal, and it signs the caller in on the way if they are
@@ -85,9 +97,25 @@ const args = process.argv.slice(2);
 // explicit way to ask for the server from a terminal.
 const bare = args.length === 0;
 const leadingFlag = Boolean(args[0]) && args[0].startsWith("-");
-const command = args[0] === "--help" || args[0] === "-h"
+// Asking for help anywhere in the line is asking for help. Only the leading
+// position was recognised, so `preman install --help` was dispatched to
+// `install` with `--help` as an argument -- and a command whose job is to
+// explain itself instead went and did the thing it was being asked about.
+// Only the first two positions, because `run` and `dispatch` forward arguments
+// to a tool and one of those may legitimately be asking that tool for help.
+const wantsHelp = args.slice(0, 2).some((arg) => arg === "--help" || arg === "-h");
+// Leading position only, unlike help: `update --version 1.1.9` is how somebody
+// pins a version to install, so reading `--version` anywhere would answer that
+// with a number and never run the update. Asking a CLI its version is also the
+// one question it must not answer by starting something -- and it did: the flag
+// fell through to the session, so `preman --version` opened a chat, and with a
+// pipe on stdin it started the MCP server and said nothing at all.
+const wantsVersion = args[0] === "--version" || args[0] === "-v";
+const command = wantsHelp
   ? "help"
-  : bare || leadingFlag
+  : wantsVersion
+    ? "version"
+    : bare || leadingFlag
     ? (process.stdin.isTTY ? "agent" : "start")
     : args[0];
 // A session or the server started this way owns every argument; a named
@@ -115,9 +143,12 @@ function printHelp() {
     ["chat [message] [--continue]", "The same session, named explicitly"],
     ["status", "Healthy / failing / recently fixed endpoints"],
     ["verify [options]", "Test endpoints against your local app"],
+    ["probe [options]", "Fire a population of simulated users at your local app"],
     ["hook install|uninstall|status", "Manage the git pre-push hook"],
     ["runner start|status|stop", "Run PreMan's queued agent work on this machine"],
-    ["eval run|doctor", "Run PreMan's queued agent eval against your local agent"],
+    ["runner work", "Take one queued eval and run it here, then exit"],
+    ["eval", "Measure your agent: priced and confirmed before it starts"],
+    ["eval target|doctor", "Find the agent to measure; check this can run"],
     ["doctor", "Diagnose credentials, backend, target, integrations"],
     ["install-desktop", "Download and install the PreMan desktop app"],
     ["predict [options]", "Local dev: bring the stack up and measure the forecaster"],
@@ -134,7 +165,7 @@ function printHelp() {
     ["start", "Start the PreMan MCP server (what an MCP host runs)"],
     ["link|tools|run ...", "Drive a published hosted MCP"],
     ["endpoints list|discover|setup ...", "Discover, list, and set up API endpoints"],
-    ["test --agent [--only <id>]", "Measure your agent against the behaviours you turned on"],
+    ["test --agent [--only <id>]", "Older spelling of `eval`; still works"],
     ["test <id> [--scenario ...] [--stress]", "Generate + run tests for an endpoint"],
     ["tests generate|review|setup|enrich", "Collections: generate, review, fixtures, enrich"],
   ];
@@ -147,7 +178,7 @@ function printHelp() {
 
 Usage:
 ${usageLines}
-${AGENT_HELP}${INTEGRATIONS_HELP}${CONNECT_HELP}${DISPATCH_HELP}${STATUS_HELP}${VERIFY_HELP}${HOOK_HELP}${RUNNER_HELP}${EVAL_HELP}${TARGET_HELP}${ACCOUNT_HELP}${DESKTOP_HELP}${PREDICT_HELP}${ENDPOINTS_HELP}${TEST_HELP}${TESTS_HELP}
+${AGENT_HELP}${INTEGRATIONS_HELP}${CONNECT_HELP}${DISPATCH_HELP}${STATUS_HELP}${VERIFY_HELP}${PROBE_HELP}${HOOK_HELP}${RUNNER_HELP}${EVAL_HELP}${TARGET_HELP}${ACCOUNT_HELP}${DESKTOP_HELP}${PREDICT_HELP}${ENDPOINTS_HELP}${TEST_HELP}${TESTS_HELP}
 Login options:
   --email <email>       Pre-fill the email prompt
   --backend <url>       PreMan backend URL. Defaults to ${DEFAULT_BACKEND}
@@ -233,6 +264,7 @@ async function updateCommand(commandArgs = []) {
 
   process.stdout.write(`Updating ${PACKAGE_NAME} (have ${before})…\n`);
   const done = spawnSync("npm", ["install", "-g", `${PACKAGE_NAME}@${wanted}`], {
+    shell: process.platform === "win32",
     stdio: "inherit",
   });
   if (done.error || done.status !== 0) {
@@ -247,7 +279,10 @@ async function updateCommand(commandArgs = []) {
   }
   // Read from the freshly installed copy rather than this process, which is
   // still running the version we just replaced.
-  const now = spawnSync("npm", ["view", PACKAGE_NAME, "version"], { encoding: "utf8" });
+  const now = spawnSync("npm", ["view", PACKAGE_NAME, "version"], {
+    encoding: "utf8",
+    shell: process.platform === "win32",
+  });
   const after = String(now.stdout || "").trim();
   process.stdout.write(
     after && after !== before
@@ -330,7 +365,9 @@ async function main() {
   // would only race with the one the user is watching.
   if (!["hook", "verify", "connect"].includes(command)) scheduleHookRepair();
 
-  if (command === "agent" || command === "chat") {
+  if (command === "version") {
+    process.stdout.write(`${packageVersion() || "unknown"}\n`);
+  } else if (command === "agent" || command === "chat") {
     await agentCommand(commandArgs);
   } else if (command === "target") {
     await targetCommand(commandArgs, { makeArgs });
@@ -340,6 +377,8 @@ async function main() {
     await statusCommand(commandArgs);
   } else if (command === "verify") {
     await verifyCommand(commandArgs);
+  } else if (command === "probe") {
+    await probeCommand(commandArgs);
   } else if (command === "hook") {
     await hookCommand(commandArgs);
   } else if (command === "runner") {
@@ -353,7 +392,11 @@ async function main() {
     // Passing them in keeps the dependency one-directional.
     const { evalCommand } = await import("./eval.js");
     const runner = await import("./runner.js");
-    await evalCommand(commandArgs, {
+    // `preman eval && deploy` has to be able to tell "the agent behaved" from
+    // "we never found out", so the code the command worked out is the code the
+    // shell sees. Left alone when there is none: a path that did not measure
+    // anything has no verdict to report, and forcing one would invent it.
+    const outcome = await evalCommand(commandArgs, {
       makeArgs,
       registerRunner: runner.registerRunner,
       readRunnerState: runner.readRunnerState,
@@ -363,6 +406,7 @@ async function main() {
       pairingIsLive: runner.pairingIsLive,
       resolveAgent: resolveAgentForPairing,
     });
+    if (Number.isInteger(outcome?.exitCode)) process.exitCode = outcome.exitCode;
   } else if (command === "logout") {
     await logoutCommand();
   } else if (command === "doctor") {
@@ -399,12 +443,18 @@ async function main() {
   } else if (command === "update" || command === "upgrade") {
     await updateCommand(commandArgs);
   } else if (command === "install") {
-    // `install` meant "write Cursor's MCP config", and every documented form of
-    // it passes a flag (`--api-key`, `--project`, `--backend`). Bare `install`
-    // never had a use, so it is the one spelling free to become what people
-    // actually type it expecting: set me up. Flagged forms keep working
-    // untouched, and `--cursor` names the old behaviour explicitly.
-    if (commandArgs.length > 0) {
+    // `install` meant "write Cursor's MCP config", and bare `install` never had
+    // a use, so it became what people actually type it expecting: set me up.
+    //
+    // That fork used to be "were there any arguments at all", which routed on
+    // the presence of a flag rather than on what the flag asked for. So
+    // `install --yes` -- the documented way to run an unattended setup -- wrote
+    // a Cursor config instead, and `install --help` did too, which is a command
+    // that cannot create an account answering by creating one. Cursor intent is
+    // now named. `--backend` is deliberately absent: every command takes it, so
+    // it says which deployment, never which program.
+    const CURSOR_INTENT = ["--cursor", "--name", "--project", "--print", "--skip-login", "--api-key"];
+    if (CURSOR_INTENT.some((flag) => commandArgs.includes(flag))) {
       await installCursorMcp();
     } else {
       await onboardCommand(commandArgs, {
@@ -436,6 +486,15 @@ async function main() {
     // differs. Routed here rather than inside testCommand because the two share
     // no arguments beyond the word `test`, and matched in first position only so
     // that an endpoint id is never overtaken by a flag further along the line.
+    // Signposted rather than removed. This spelling is in circulation, in
+    // scripts and in people's shell history, and breaking it to make a point
+    // about naming would cost more than the confusion it fixes.
+    const invocation = cliInvocation();
+    process.stderr.write(
+      `\`${invocation} test --agent\` is now \`${invocation} eval\`, which ` +
+        `checks the agent can be found and prices the run before starting it. ` +
+        `Running it for you.\n\n`
+    );
     const { agentTestCommand } = await import("./eval.js");
     const runner = await import("./runner.js");
     await agentTestCommand(commandArgs, {

package/bin/connect/configs.js

@@ -11,7 +11,7 @@ import os from "node:os";
 import path from "node:path";
 import { execFileSync, spawnSync } from "node:child_process";
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { LAUNCHER_ARGS, LAUNCHER_COMMAND, backendUrl, frontendUrl, onPath, readJsonFile, writeJsonFile } from "../shared.js";
+import { LAUNCHER_ARGS, LAUNCHER_COMMAND, backendUrl, frontendUrl, launcherFor, onPath, readJsonFile, writeJsonFile } from "../shared.js";
 import { AGENTS } from "./agents.js";
 
 // ── Config writers ──────────────────────────────────────────────────────
@@ -42,6 +42,10 @@ export function writeCursorConfig({ serverName, serverConfig, projectInstall })
       execFileSync("cursor-agent", cursorMcpEnableArgs(serverName), {
         stdio: "pipe",
         timeout: 15000,
+        // Both agent CLIs install as `.cmd` shims on Windows, and execFile
+        // cannot run a batch file: it fails with EINVAL, which reads as the
+        // agent being broken rather than as us spawning it wrongly.
+        shell: process.platform === "win32",
       });
       return { path: configPath, how: "wrote and enabled" };
     } catch (error) {
@@ -79,7 +83,7 @@ export function writeClaudeConfig({ serverName, serverConfig, projectInstall })
   if (onPath("claude")) {
     const args = claudeMcpAddArgs(serverName, serverConfig, projectInstall);
     try {
-      execFileSync("claude", args, { stdio: "pipe" });
+      execFileSync("claude", args, { stdio: "pipe", shell: process.platform === "win32" });
       return { path: projectInstall ? ".mcp.json" : "Claude Code user config", how: "registered via claude mcp add" };
     } catch (error) {
       const detail = error?.stderr?.toString().trim() || error.message;
@@ -171,6 +175,17 @@ export const WRITERS = {
 
 /** Quote only what a shell would otherwise mangle, so the line stays readable. */
 export function shellQuote(value) {
+  // cmd.exe does not read single quotes as quoting at all, so the POSIX form
+  // was handed to Windows users as something to paste and arrived at the agent
+  // with the quotes still in it -- an API key wrapped in apostrophes is a
+  // different API key. A value with a double quote in it cannot be expressed
+  // safely on cmd.exe, and saying so beats emitting something that will run
+  // and do the wrong thing.
+  if (process.platform === "win32") {
+    if (/^[A-Za-z0-9_@%+=:,./\\-]+$/.test(value)) return value;
+    if (value.includes('"')) return `<value containing a double quote: set it by hand>`;
+    return `"${value}"`;
+  }
   return /^[A-Za-z0-9_@%+=:,./-]+$/.test(value) ? value : `'${String(value).replace(/'/g, `'\\''`)}'`;
 }
 
@@ -193,8 +208,7 @@ export function renderAllAgentSnippets(args, serverName, { projectInstall = fals
     PREMAN_FRONTEND: frontendUrl(args),
   };
   const serverConfig = {
-    command: LAUNCHER_COMMAND,
-    args: [...LAUNCHER_ARGS],
+    ...launcherFor(),
     env,
   };
 
@@ -243,7 +257,7 @@ 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 = "${LAUNCHER_COMMAND}"`)) {
+      if (!block.some((line) => line.trim() === `command = "${launcherFor().command}"`)) {
         return {
           status: "mismatch",
           detail: `${written.path} does not launch ${LAUNCHER_COMMAND}`,
@@ -263,7 +277,7 @@ 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 !== LAUNCHER_COMMAND) {
+    if (entry.command !== launcherFor().command) {
       return {
         status: "mismatch",
         detail: `${written.path} does not launch ${LAUNCHER_COMMAND}`,