premanmcp 0.10.2 → 0.10.4

package/README.md

@@ -58,9 +58,11 @@ to go restart anything, in cheapest-first order:
 A self-test that answers from an unexpected backend is reported with the file that
 redirected it — a repo-local `preman-mcp.config.json` with `"PREMAN_CONFIG_OVERRIDE": true`
 wins over the MCP config env, and otherwise only fills in what the env leaves unset. When
-that file overrides `PREMAN_BACKEND`, `connect` stops there rather than waiting: an agent
-started in that directory reads the same file and checks in somewhere else, so it names the
-file and tells you how to connect to either backend.
+that file overrides `PREMAN_BACKEND`, the config `connect` wrote is still correct: the
+server reads that file only from the directory it starts in, so `connect` names the file
+and then retries from your home directory, where the override cannot reach it — self-test
+first, then your agent. Agents you start in the overriding directory keep using its
+backend, which is the point of the file.
 
 Once linked, `connect` finishes onboarding without handing you homework:
 

package/bin/connect.js

@@ -690,6 +690,11 @@ export function openInNewTerminal(command, options = {}) {
  * machine with no terminal emulator — does this fall back to the headless run,
  * which still finishes the link even though nobody sees it happen.
  *
+ * `cwd` is where the agent starts, and it is load-bearing rather than tidiness:
+ * the MCP server reads its repo config out of the working directory, so starting
+ * the agent elsewhere is how a caller escapes a directory that would otherwise
+ * redirect it to a backend this key was never issued for.
+ *
  * Returns `ran: false` when the agent's binary is absent or will not start, and
  * the caller falls back to the printed instructions.
  */
@@ -706,13 +711,14 @@ export async function autoCheckIn(
     ),
     serverName = "preman",
     intervalMs = Number(process.env.PREMAN_CONNECT_POLL_MS) || 3000,
+    cwd = process.cwd(),
     onLaunch = () => {},
     onPoll = null,
   } = {}
 ) {
   const session = interactiveCheckIn(agent, serverName);
   if (session && onPath(session.bin)) {
-    const { opened, terminal } = openInNewTerminal(commandLine(session), { cwd: process.cwd() });
+    const { opened, terminal } = openInNewTerminal(commandLine(session), { cwd });
     if (opened) {
       onLaunch({ mode: "interactive", bin: session.bin, terminal });
       // Detached, so there is no exit to watch for and no output to quote: the
@@ -732,7 +738,7 @@ export async function autoCheckIn(
     // Piped rather than ignored: an agent that runs and does not check in used to
     // report exactly that and nothing else, which is the least useful sentence
     // available. Its own last words usually name the cause.
-    child = spawn(spec.bin, spec.args, { stdio: ["ignore", "pipe", "pipe"] });
+    child = spawn(spec.bin, spec.args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
   } catch (error) {
     return { ran: false, connected: false, reason: error.message };
   }
@@ -1124,7 +1130,7 @@ export function headlessDiscovery(agent, serverName, instructions = []) {
  *
  * Never throws: a failed discovery must not fail the connect.
  */
-async function discoverEndpoints(args, agent, serverName) {
+async function discoverEndpoints(args, agent, serverName, blockedHere = "") {
   try {
     const before = await endpointCounts(args);
     if (before.registered) {
@@ -1136,7 +1142,10 @@ async function discoverEndpoints(args, agent, serverName) {
 
     const brief = await callPremanTool(args, "discover_endpoints_from_codebase", { base_path: "." });
     const spec = headlessDiscovery(agent, serverName, brief.instructions || []);
-    const blocker = spec && onPath(spec.bin) ? agentBlocker(agent.id) : "";
+    // Discovery has to read *this* repo, so it cannot be moved out of a directory
+    // that redirects it the way the check-in was — it can only be skipped, before
+    // it spends ten minutes proving what the self-test already found out.
+    const blocker = blockedHere || (spec && onPath(spec.bin) ? agentBlocker(agent.id) : "");
     if (!spec || !onPath(spec.bin) || blocker) {
       // Say why before printing homework: "here is a brief" reads as PreMan not
       // working, when the actual answer is one login away.
@@ -1436,11 +1445,11 @@ async function setUpPushTesting(args) {
  * Order follows what a new account needs to see: what PreMan found, then where to
  * watch it, then who to tell, then when to run it.
  */
-async function guidedFirstRun(args, agent, apiKey, serverName) {
+async function guidedFirstRun(args, agent, apiKey, serverName, { blockedHere = "" } = {}) {
   const assumeYes = args.has("--yes");
 
   step("Endpoints");
-  const counts = await discoverEndpoints(args, agent, serverName);
+  const counts = await discoverEndpoints(args, agent, serverName, blockedHere);
 
   if (counts.first) {
     step("First test");
@@ -1655,7 +1664,13 @@ export async function connectCommand(commandArgs) {
     return;
   }
 
-  if (!(await establishCheckIn(args, agent, apiKey, { serverName, written, serverConfig }))) {
+  const checkIn = await establishCheckIn(args, agent, apiKey, {
+    serverName,
+    written,
+    serverConfig,
+    projectInstall,
+  });
+  if (!checkIn.linked) {
     // 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 });
@@ -1664,7 +1679,7 @@ export async function connectCommand(commandArgs) {
 
   process.stdout.write(`${MARK.ok()} Connected as ${agent.label}.\n`);
   if (!args.has("--no-guide")) {
-    await guidedFirstRun(args, agent, apiKey, serverName);
+    await guidedFirstRun(args, agent, apiKey, serverName, { blockedHere: checkIn.blockedHere });
   }
   await captureDispatchCredential(args, agent, apiKey);
 }
@@ -1687,6 +1702,30 @@ function backendRedirect(repo, status, serverConfig) {
   return { path: repo.path, actual, wanted };
 }
 
+/**
+ * Somewhere to start the agent when this directory would redirect its backend.
+ *
+ * The server reads its repo config from the working directory and nowhere else —
+ * no walk up to the parents — so any directory without one of those two files is
+ * already out of the override's reach. Home first, because an agent started there
+ * is in a place the user recognises; a temp dir only if home is itself a repo
+ * carrying a config.
+ *
+ * Null means every candidate was covered, and the caller has nothing to offer but
+ * the instructions.
+ */
+export function neutralCwd(candidates = [os.homedir(), os.tmpdir()]) {
+  return (
+    candidates.find(
+      (dir) =>
+        dir &&
+        existsSync(dir) &&
+        !existsSync(path.join(dir, ".cursor", "preman-mcp.config.json")) &&
+        !existsSync(path.join(dir, "preman-mcp.config.json"))
+    ) || null
+  );
+}
+
 /**
  * Finish the link here, by whatever means work, in cheapest-first order.
  *
@@ -1697,15 +1736,33 @@ function backendRedirect(repo, status, serverConfig) {
  *    the config we wrote.
  * 3. Failing that, ask them to restart it and wait, which is all this ever did.
  *
+ * A directory whose repo config redirects the backend moves steps 1 and 2 out of
+ * that directory rather than giving up in it: the config on disk is right, and
+ * where the server and the agent stand is the only thing that has to change. Not
+ * step 2 under `--project`, though — that config exists in that directory alone,
+ * so an agent sent anywhere else would have no server to call.
+ *
  * Every diagnosis is printed the moment it is known rather than saved for the
  * end: the steps below are measured in minutes, and a note that explains what is
  * happening is worth nothing after it has stopped happening.
  *
- * Returns whether the check-in landed, and prints the troubleshooting block
- * itself when it did not.
+ * Returns whether the check-in landed and, when this directory redirects it, why
+ * nothing started here can use PreMan — the caller has its own agent to run once
+ * this is done. Prints the troubleshooting block itself when the link did not
+ * land.
  */
-async function establishCheckIn(args, agent, apiKey, { serverName, written, serverConfig }) {
+async function establishCheckIn(
+  args,
+  agent,
+  apiKey,
+  { serverName, written, serverConfig, projectInstall = false }
+) {
   const notes = [];
+  // Both set only when this directory redirects the agent: where it can be
+  // started instead, and why an agent left standing here cannot use PreMan at all.
+  let elsewhere = null;
+  let blockedHere = "";
+  const done = (linked) => ({ linked, blockedHere });
   const ticker = pollTicker();
   const say = (text) => {
     ticker.end();
@@ -1730,7 +1787,7 @@ async function establishCheckIn(args, agent, apiKey, { serverName, written, serv
       );
     }
     if (test.ok && status.authenticated && (await waitForConnection(args, apiKey, { timeoutMs: 15000 }))) {
-      return true;
+      return done(true);
     }
     note(
       test.ok
@@ -1741,15 +1798,68 @@ async function establishCheckIn(args, agent, apiKey, { serverName, written, serv
     const redirect = backendRedirect(repo, status, serverConfig);
     if (redirect) {
       const flag = `--agent ${agent.id.replace("_", "-")}`;
+      const notLinked = (why) =>
+        say(
+          `\nNot linked: ${redirect.path} forces PREMAN_BACKEND=${redirect.actual} for anything\n` +
+            `started in this directory, so ${agent.label} cannot check in against ${redirect.wanted}.\n` +
+            `  - ${why}\n` +
+            `  - Or connect to that backend: ${cliInvocation()} connect ${flag} --backend ${redirect.actual}\n` +
+            `    (needs a key issued by it, and that API running).\n` +
+            `  - Config written to: ${written.path}\n`
+        );
+      notes.push(
+        `start ${agent.label} from another project, or connect to the backend this ` +
+          `directory forces: ${cliInvocation()} connect ${flag} --backend ${redirect.actual} ` +
+          `(needs a key issued by it, and that API running).`
+      );
+      // Linking is not the only thing this directory breaks: whatever runs here
+      // next gets the same redirected, unauthenticated server, and the callers
+      // that would start an agent in it need to hear so.
+      blockedHere =
+        `${redirect.path} sends ${agent.label} to ${redirect.actual} in this directory, ` +
+        `where this key is not valid.`;
+
+      // The config we wrote is correct; the directory around it is not. Since the
+      // server only reads the file it is standing in, everything this does next
+      // happens somewhere the override cannot reach.
+      const outside = neutralCwd();
+      if (!outside) {
+        notLinked(`Run '${cliInvocation()} connect' from your own project instead of this directory.`);
+        return done(false);
+      }
+
       say(
-        `\nNot linked: ${redirect.path} forces PREMAN_BACKEND=${redirect.actual} for anything\n` +
-          `started in this directory, so ${agent.label} cannot check in against ${redirect.wanted}.\n` +
-          `  - Run '${cliInvocation()} connect' from your own project instead of this directory.\n` +
-          `  - Or connect to that backend: ${cliInvocation()} connect ${flag} --backend ${redirect.actual}\n` +
-          `    (needs a key issued by it, and that API running).\n` +
-          `  - Config written to: ${written.path}\n`
+        (projectInstall
+          ? `\nThe key and backend written are right: ${redirect.path}\n` +
+            `only redirects what starts in this directory. `
+          : `\nThe config is written and works anywhere else: ${redirect.path}\n` +
+            `only redirects agents started in this directory. `) +
+          `Trying again from\n${outside}, which is out of that file's reach.\n`
       );
-      return false;
+      // Nothing was wrong with the self-test but where it stood, and a self-test
+      // is what completes the link — so re-run it before spending an agent window
+      // on the same question. This works under --project too: it runs the config
+      // in memory rather than loading it from disk.
+      const retry = await mcpSelfTest(serverConfig, { cwd: outside });
+      if (
+        retry.ok &&
+        retry.status?.authenticated &&
+        (await waitForConnection(args, apiKey, { timeoutMs: 15000 }))
+      ) {
+        return done(true);
+      }
+
+      if (projectInstall) {
+        // --project put the server in this directory and nowhere else, so there
+        // is no config to load anywhere the override cannot reach, and no agent
+        // worth starting to look for one.
+        notLinked(
+          `This --project config exists only here; started anywhere else, ` +
+            `${agent.label} has no ${serverName} server to call.`
+        );
+        return done(false);
+      }
+      elsewhere = outside;
     }
   }
 
@@ -1758,6 +1868,7 @@ async function establishCheckIn(args, agent, apiKey, { serverName, written, serv
   if (!args.has("--no-auto-checkin") && !blocker) {
     launch = await autoCheckIn(args, agent, apiKey, {
       serverName,
+      cwd: elsewhere || process.cwd(),
       onPoll: ticker.tick,
       onLaunch: ({ mode, terminal }) =>
         say(
@@ -1768,7 +1879,7 @@ async function establishCheckIn(args, agent, apiKey, { serverName, written, serv
     });
     if (launch.connected) {
       ticker.end();
-      return true;
+      return done(true);
     }
     if (launch.ran && !launch.interactive) {
       const why = lastLine(launch.output);
@@ -1787,13 +1898,17 @@ async function establishCheckIn(args, agent, apiKey, { serverName, written, serv
     launch.interactive
       ? `\nAnswer it in the ${agent.label} window — it links on its first PreMan call.\n` +
           "Waiting for your agent to check in… (Ctrl+C to stop waiting)\n"
-      : `\nRestart ${agent.label} and ask it: "run preman_status"\n` +
+      : // Restarting it here would read the same redirecting file again, so the
+        // one instruction that works is to start it somewhere else.
+        (elsewhere
+          ? `\nStart ${agent.label} in another project and ask it: "run preman_status"\n`
+          : `\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, { onPoll: ticker.tick })) {
     ticker.end();
-    return true;
+    return done(true);
   }
 
   say(
@@ -1804,5 +1919,5 @@ async function establishCheckIn(args, agent, apiKey, { serverName, written, serv
       `  - 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;
+  return done(false);
 }

package/package.json

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