premanmcp 0.10.4 → 0.10.6

package/bin/hook.js

@@ -8,24 +8,37 @@
  * by construction rather than by configuration.
  */
 
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 
-import { cliInvocation, makeArgs } from "./shared.js";
+import { cliInvocation, makeArgs, packageVersion } from "./shared.js";
 import { BLOCK_EXIT_CODE } from "./verify.js";
 
 export const HOOK_HELP = `
 Hook options:
   install               Write the pre-push hook into this repository
   uninstall             Remove PreMan's pre-push hook
-  status                Report whether the hook is installed
+  status                Report whether the hook is installed, and still works
+  repair                Rewrite a hook of ours whose command no longer answers
   --force               Overwrite a foreign pre-push hook (a backup is kept)
+  PREMAN_HOOK_INVOCATION=<cmd>  Use this command line instead of probing for one
+  PREMAN_NO_HOOK_REPAIR=1       Never repair a hook in the background
 `;
 
 const MARKER = "# >>> preman pre-push >>>";
 const END_MARKER = "# <<< preman pre-push <<<";
 const HOOK_TIMEOUT_SECONDS = 120;
+const PROBE_TIMEOUT_MS = 45000;
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const HEALTH_FILE = path.join(os.homedir(), ".preman", "hook-health.json");
+// How long a healthy answer is believed for. The repair costs a probe, and a
+// hook that worked an hour ago almost always still works, so this is the knob
+// that keeps a background check off the critical path of every command.
+const RECHECK_MS = 60 * 60 * 1000;
+const HEALTH_TTL_MS = 30 * 24 * 60 * 60 * 1000;
 
 function gitDir() {
   const result = spawnSync("git", ["rev-parse", "--git-dir"], { encoding: "utf8" });
@@ -39,7 +52,90 @@ function hookPath() {
   return path.join(gitDir(), "hooks", "pre-push");
 }
 
-function hookBody() {
+/**
+ * The command lines a hook could carry, best first.
+ *
+ * A hook is written once and read at every push, so `@latest` quietly hands each
+ * push to whatever we ship next; the version that wrote the hook is the one that
+ * keeps running it, and `preman hook install` is how that moves. `@latest` is
+ * left only for the case where we cannot read our own manifest to know it.
+ *
+ * The bare `preman` form is offered first when it is ours — see `pathPremanOwner`
+ * — because it starts in milliseconds where npm exec does not.
+ */
+export function hookInvocations() {
+  const version = packageVersion();
+  const pinned = `npm exec -y premanmcp@${version || "latest"} --`;
+  const preferred = cliInvocation();
+  return preferred.startsWith("npm exec") ? [pinned] : [preferred, pinned];
+}
+
+const probed = new Map();
+
+/** An invocation the user pinned by hand, or "". */
+function declaredInvocation() {
+  return String(process.env.PREMAN_HOOK_INVOCATION || "").trim();
+}
+
+/**
+ * Does this command line reach a PreMan CLI that knows `verify`, from a process
+ * that is not this one?
+ *
+ * This is the check whose absence produced `Unknown command: verify` on every
+ * push: the hook is generated shell run minutes or months later, so the only
+ * evidence that matters is a separate process answering. `help` is the cheapest
+ * subcommand that proves both halves — that something ran, and that it was us
+ * rather than another package's identically named `preman`.
+ *
+ * Memoized per command line, because a connect installs and then re-reads the
+ * hook, and npm exec is slow enough that paying twice shows.
+ */
+export function invocationAnswers(invocation) {
+  // Declaring an invocation means "use this and stop asking", so the same answer
+  // has to hold when we later read it back out of a hook -- otherwise the escape
+  // hatch writes a hook that every status then calls broken.
+  if (invocation && invocation === declaredInvocation()) return true;
+  if (probed.has(invocation)) return probed.get(invocation);
+  let answered = false;
+  try {
+    const probe = spawnSync(`${invocation} help`, {
+      shell: true,
+      encoding: "utf8",
+      timeout: Number(process.env.PREMAN_HOOK_PROBE_MS) || PROBE_TIMEOUT_MS,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    answered = probe.status === 0 && /\bverify\b/.test(String(probe.stdout || ""));
+  } catch {
+    answered = false;
+  }
+  probed.set(invocation, answered);
+  return answered;
+}
+
+/** Test seam: the probe above is memoized for the life of the process. */
+export function resetInvocationProbe() {
+  probed.clear();
+}
+
+/**
+ * The invocation to write into a hook, or "" when nothing here can run PreMan.
+ *
+ * `PREMAN_HOOK_INVOCATION` is taken on trust: it exists for the setups we cannot
+ * probe our way to — a wrapper script, a monorepo runner, a pinned mirror.
+ */
+export function provenInvocation() {
+  return (
+    declaredInvocation() || hookInvocations().find((candidate) => invocationAnswers(candidate)) || ""
+  );
+}
+
+/** The command line an already-written hook calls, or "". */
+function embeddedInvocation(text) {
+  const match = /^\s*PREMAN_HOOK=1 (.+) verify --pre-push\b/m.exec(text);
+  return match ? match[1].trim() : "";
+}
+
+function hookBody(invocation) {
   // `exec` is deliberately absent: we want the wrapper to survive the CLI exiting
   // non-zero and still exit 0 itself.
   //
@@ -51,7 +147,7 @@ ${MARKER}
 # Advisory unless this repository opted into blocking: only exit code
 # ${BLOCK_EXIT_CODE} stops a push, so a crash or a timeout still lets it through.
 if [ -z "\${PREMAN_SKIP_HOOK}" ]; then
-  PREMAN_HOOK=1 ${cliInvocation()} verify --pre-push --timeout ${HOOK_TIMEOUT_SECONDS}
+  PREMAN_HOOK=1 ${invocation} verify --pre-push --timeout ${HOOK_TIMEOUT_SECONDS}
   preman_status=$?
   if [ "$preman_status" -eq ${BLOCK_EXIT_CODE} ]; then
     exit ${BLOCK_EXIT_CODE}
@@ -71,16 +167,31 @@ function isOurHook(text) {
   return text.includes(MARKER);
 }
 
-export function installHook(args) {
+export function installHook(args, { invocation = provenInvocation() } = {}) {
   const target = hookPath();
+
+  // A hook holding a command that does not run is worse than no hook: it is
+  // silent, it says "installed" in every status we print, and the only sign of
+  // it is one skipped line scrolling past a push nobody reads.
+  if (!invocation) {
+    return {
+      path: target,
+      action: "unproven",
+      detail:
+        "no way to run the PreMan CLI from a hook was found here" +
+        " -- install it globally (npm i -g premanmcp) or set PREMAN_HOOK_INVOCATION",
+    };
+  }
+
+  const body = hookBody(invocation);
   mkdirSync(path.dirname(target), { recursive: true });
 
   if (existsSync(target)) {
     const existing = readFileSync(target, "utf8");
     if (isOurHook(existing)) {
-      writeFileSync(target, hookBody(), { mode: 0o755 });
+      writeFileSync(target, body, { mode: 0o755 });
       chmodSync(target, 0o755);
-      return { path: target, action: "updated" };
+      return { path: target, action: "updated", invocation };
     }
     if (!args.has("--force")) {
       return {
@@ -91,14 +202,19 @@ export function installHook(args) {
     }
     const backup = `${target}.preman-backup`;
     writeFileSync(backup, existing, { mode: 0o755 });
-    writeFileSync(target, hookBody(), { mode: 0o755 });
+    writeFileSync(target, body, { mode: 0o755 });
     chmodSync(target, 0o755);
-    return { path: target, action: "replaced", detail: `previous hook saved to ${backup}` };
+    return {
+      path: target,
+      action: "replaced",
+      invocation,
+      detail: `previous hook saved to ${backup}`,
+    };
   }
 
-  writeFileSync(target, hookBody(), { mode: 0o755 });
+  writeFileSync(target, body, { mode: 0o755 });
   chmodSync(target, 0o755);
-  return { path: target, action: "installed" };
+  return { path: target, action: "installed", invocation };
 }
 
 export function uninstallHook() {
@@ -122,17 +238,124 @@ export function uninstallHook() {
  * `current` is what tells a caller an installed hook still needs rewriting.
  *
  * A hook is generated shell holding one invocation, and that invocation can go
- * stale — the machine gained a `preman` that is not ours, or lost the one that
- * was. "Installed" then means a file exists that calls the wrong thing on every
- * push, so anything that skips work when the hook is present has to be able to
- * tell the difference.
+ * stale — the machine gained a `preman` that is not ours, lost the one that was,
+ * or upgraded past the version the hook pins. "Installed" then means a file
+ * exists that calls the wrong thing on every push, so anything that skips work
+ * when the hook is present has to be able to tell the difference.
+ *
+ * `works` answers the harder question — does the command in the file still run
+ * PreMan — so callers ask for it: `preman hook status` and `preman doctor` do,
+ * connect does not. Both answers cost a probe for an installed hook, since
+ * "up to date" means "equal to what we would write now", and what we would write
+ * is whatever answers here. An absent or foreign hook costs nothing.
  */
-export function hookStatus() {
+export function hookStatus({ probe = false } = {}) {
   const target = hookPath();
-  if (!existsSync(target)) return { path: target, state: "absent", current: false };
+  const missing = { path: target, current: false, invocation: "", works: null };
+  if (!existsSync(target)) return { ...missing, state: "absent" };
   const existing = readFileSync(target, "utf8");
-  if (!isOurHook(existing)) return { path: target, state: "foreign", current: false };
-  return { path: target, state: "installed", current: existing === hookBody() };
+  if (!isOurHook(existing)) return { ...missing, state: "foreign" };
+
+  const invocation = embeddedInvocation(existing);
+  // Falling back to what the file already carries keeps a machine that can no
+  // longer prove any invocation -- offline, say -- from reporting a hook as out
+  // of date and sending its owner to a reinstall that would refuse to write.
+  const wanted = provenInvocation() || invocation;
+  return {
+    path: target,
+    state: "installed",
+    invocation,
+    current: Boolean(wanted) && existing === hookBody(wanted),
+    works: probe ? Boolean(invocation) && invocationAnswers(invocation) : null,
+  };
+}
+
+function readHookChecks() {
+  try {
+    const parsed = JSON.parse(readFileSync(HEALTH_FILE, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Remember what a check found, so the next command does not pay for it again. */
+function rememberHookCheck(cwd, now, fields) {
+  const checks = readHookChecks();
+  for (const [key, value] of Object.entries(checks)) {
+    if (now - Number(value?.at || 0) > HEALTH_TTL_MS) delete checks[key];
+  }
+  checks[cwd] = { at: now, ...fields };
+  try {
+    mkdirSync(path.dirname(HEALTH_FILE), { recursive: true });
+    writeFileSync(HEALTH_FILE, JSON.stringify(checks, null, 2) + "\n", { mode: 0o600 });
+  } catch {
+    // A cache we cannot write costs a probe next time and nothing else.
+  }
+  return { cwd, ...fields };
+}
+
+/**
+ * Put a hook of ours back into working order, without being asked.
+ *
+ * The failure this exists for is invisible: a hook written by a version that
+ * embedded the wrong command keeps printing one skipped line per push, and
+ * nothing re-runs `connect` after an upgrade to notice. So anything that proves
+ * PreMan is running here -- any command, the MCP server starting -- is taken as
+ * the moment to check.
+ *
+ * Deliberately narrow. It only ever rewrites a hook we wrote that no longer
+ * answers: an absent hook is not installed behind the user, a foreign hook is
+ * not touched, and a hook that works is left on whatever version it pins.
+ */
+export function repairDeadHook({ cwd = process.cwd(), now = Date.now(), force = false } = {}) {
+  const remember = (fields) => rememberHookCheck(cwd, now, fields);
+  if (!force) {
+    const last = readHookChecks()[cwd];
+    if (last && now - Number(last.at || 0) < RECHECK_MS) return { cwd, action: "recent" };
+  }
+
+  let status;
+  try {
+    status = hookStatus({ probe: true });
+  } catch {
+    return remember({ action: "not-a-repository" });
+  }
+  if (status.state !== "installed") return remember({ action: status.state });
+  if (status.works) return remember({ action: "healthy", invocation: status.invocation });
+
+  const result = installHook(makeArgs([]));
+  return remember({
+    action: result.action === "updated" ? "repaired" : result.action,
+    invocation: result.invocation || "",
+    replaced: status.invocation,
+  });
+}
+
+/**
+ * Run the repair in a detached child, because every step of it is synchronous
+ * and one of them shells out to npm. Nothing that merely wants a healthy hook
+ * should wait on a probe, least of all the MCP server, whose stdout is a
+ * protocol -- hence stdio ignored rather than inherited.
+ */
+export function scheduleHookRepair({ cwd = process.cwd(), now = Date.now() } = {}) {
+  if (process.env.PREMAN_HOOK) return { action: "skipped", reason: "running inside the hook" };
+  if (process.env.PREMAN_NO_HOOK_REPAIR) return { action: "skipped", reason: "disabled" };
+  const last = readHookChecks()[cwd];
+  if (last && now - Number(last.at || 0) < RECHECK_MS) {
+    return { action: "skipped", reason: "checked recently" };
+  }
+  try {
+    const child = spawn(process.execPath, [path.join(__dirname, "cli.js"), "hook", "repair"], {
+      cwd,
+      detached: true,
+      stdio: "ignore",
+    });
+    child.unref();
+    return { action: "spawned", pid: child.pid };
+  } catch {
+    return { action: "skipped", reason: "could not spawn" };
+  }
 }
 
 export async function hookCommand(commandArgs = []) {
@@ -141,19 +364,36 @@ export async function hookCommand(commandArgs = []) {
 
   if (sub === "install") {
     const result = installHook(args);
-    if (result.action === "conflict") {
+    if (result.action === "conflict" || result.action === "unproven") {
       process.stdout.write(`Not installed: ${result.detail}\n  ${result.path}\n`);
       return result;
     }
     process.stdout.write(
       `Pre-push hook ${result.action}: ${result.path}\n` +
         (result.detail ? `  ${result.detail}\n` : "") +
+        `  Runs: ${result.invocation} verify --pre-push\n` +
         `\nPreMan will now check affected endpoints before each push.\n` +
         `It never blocks a push -- set PREMAN_SKIP_HOOK=1 to silence it entirely.\n`
     );
     return result;
   }
 
+  if (sub === "repair") {
+    // Asked for by hand, "repair" means now: the hourly gate exists to keep this
+    // off the critical path of unrelated commands, not to refuse a person.
+    const result = repairDeadHook({ force: !args.has("--if-stale") });
+    const said = {
+      repaired: () => `Pre-push hook repaired: it now runs ${result.invocation}\n`,
+      healthy: () => "Pre-push hook already works here.\n",
+      recent: () => "Pre-push hook checked recently; nothing to do.\n",
+      absent: () => `No PreMan hook here. Install one: ${cliInvocation()} hook install\n`,
+      foreign: () => "The pre-push hook here is not ours; left alone.\n",
+      unproven: () => "Cannot repair: no way to run the PreMan CLI was found here.\n",
+    }[result.action];
+    process.stdout.write(said ? said() : `Pre-push hook: ${result.action}\n`);
+    return result;
+  }
+
   if (sub === "uninstall") {
     const result = uninstallHook();
     process.stdout.write(
@@ -163,13 +403,27 @@ export async function hookCommand(commandArgs = []) {
   }
 
   if (sub === "status") {
-    const result = hookStatus();
+    const result = hookStatus({ probe: true });
     const label = {
       installed: "installed (PreMan)",
       foreign: "present, but not written by PreMan",
       absent: "not installed",
     }[result.state];
     process.stdout.write(`Pre-push hook: ${label}\n  ${result.path}\n`);
+    if (result.state === "installed") {
+      process.stdout.write(`  Runs: ${result.invocation || "(unreadable)"}\n`);
+      // "Installed" was never the question -- a hook that cannot reach the CLI
+      // prints one skipped line per push and is otherwise indistinguishable.
+      process.stdout.write(
+        result.works
+          ? "  That command answers here.\n"
+          : `  That command does not answer here -- pushes are being skipped.\n` +
+              `    Repair it: ${cliInvocation()} hook install --force\n`
+      );
+      if (!result.current) {
+        process.stdout.write(`  Out of date: ${cliInvocation()} hook install --force\n`);
+      }
+    }
     return result;
   }
 

package/bin/integrations.js

@@ -26,6 +26,12 @@ import {
 
 const POLL_INTERVAL_MS = 3000;
 const POLL_TIMEOUT_MS = 300000;
+// GitHub is the one install where waiting longer buys nothing. A CloudFormation
+// stack genuinely takes minutes, but the App either redirects back seconds after
+// the customer confirms or it never does — and five more minutes of dots turns a
+// hand-off into an outage. PREMAN_GITHUB_POLL_MS shortens it, so a test of the
+// hand-off does not have to spend three quarters of a minute reaching it.
+const GITHUB_POLL_TIMEOUT_MS = 45000;
 
 /**
  * Colour only when someone is actually watching.
@@ -75,9 +81,13 @@ export class Unrecoverable extends Error {}
  * Returns the truthy value from ``check``, or null on timeout. Ordinary
  * exceptions are swallowed and retried; :class:`Unrecoverable` stops the wait.
  */
-async function waitFor(label, check, { hint = "", hintAfterMs = 60000 } = {}) {
+async function waitFor(
+  label,
+  check,
+  { hint = "", hintAfterMs = 60000, timeoutMs = POLL_TIMEOUT_MS } = {}
+) {
   const startedAt = Date.now();
-  const deadline = startedAt + POLL_TIMEOUT_MS;
+  const deadline = startedAt + timeoutMs;
   let hinted = false;
   process.stdout.write(`Waiting for ${label}`);
   while (Date.now() < deadline) {
@@ -232,6 +242,10 @@ export async function githubCommand(args) {
   present(url, "install the PreMan GitHub App");
   process.stdout.write("Pick the repositories PreMan may read.\n");
 
+  // The refresh answer is the diagnosis. A 409 means GitHub never called back;
+  // a success carrying no repositories means the App is installed and sharing
+  // nothing — two dead ends that are indistinguishable from the repository list.
+  let refresh = null;
   const done = await waitFor(
     "the installation",
     async () => {
@@ -239,7 +253,7 @@ export async function githubCommand(args) {
       // callback records the installation, and a refresh materialises the repos.
       // Polling the repo list alone waits for something that may never arrive on
       // its own.
-      await callBackendJson(args, "POST", "/integrations/github/app/refresh", {
+      refresh = await callBackendJson(args, "POST", "/integrations/github/app/refresh", {
         token,
         json: {},
       });
@@ -249,24 +263,46 @@ export async function githubCommand(args) {
       return fresh.length ? fresh : null;
     },
     {
+      timeoutMs: Number(process.env.PREMAN_GITHUB_POLL_MS) || GITHUB_POLL_TIMEOUT_MS,
+      hintAfterMs: 20000,
       hint:
-        "PreMan has not heard from GitHub yet. Finish the install in the browser tab —\n" +
-        "pick at least one repository and confirm — and GitHub will send you back here.",
+        "Still nothing from GitHub. Picking at least one repository and confirming\n" +
+        "is what sends you back here.",
     }
   );
 
   if (!done) {
-    process.stdout.write(
-      `Timed out: GitHub never told PreMan about an installation.\n` +
-        `  - Check that the App is installed: https://github.com/settings/installations\n` +
-        `  - Then re-run '${cliInvocation()} github'.\n`
-    );
+    process.stdout.write(githubHandOff(args, refresh));
     return;
   }
   connected(`GitHub connected: ${done.length} repository(ies).`);
   for (const repo of done.slice(0, 5)) process.stdout.write(`  - ${repo.repo_url}\n`);
 }
 
+/**
+ * Stop waiting, and name the dead end instead of the timeout.
+ *
+ * Holding the terminal for five minutes taught nobody anything: the install
+ * finishes in the browser whether this process is watching or not, and the two
+ * ways it can complete and still leave PreMan with nothing are both actionable.
+ */
+function githubHandOff(args, refresh) {
+  const installed = Boolean(refresh?.ok) && Number(refresh.installations_refreshed || 0) > 0;
+  if (installed) {
+    return (
+      `The App is installed, but no repositories are shared with it.\n` +
+      `  - Add some: https://github.com/settings/installations\n` +
+      `  - Then re-run '${cliInvocation()} github'.\n`
+    );
+  }
+  return (
+    `Nothing from GitHub yet — no need to wait here.\n` +
+    `  - Finish the install in the browser; it records itself when you confirm.\n` +
+    `  - Check it: ${frontendUrl(args)}  or  https://github.com/settings/installations\n` +
+    `  - Then re-run '${cliInvocation()} github'.\n`
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Slack
 // ---------------------------------------------------------------------------
@@ -301,6 +337,17 @@ export async function slackCommand(args) {
 // The guided run
 // ---------------------------------------------------------------------------
 
+/**
+ * Why a step that needs a connected agent cannot run on its own.
+ *
+ * Both of these drive the agent `connect` just linked, so skipping that step
+ * leaves them without one -- which is a thing to say plainly, with the command
+ * that does it later, rather than a stack trace about a missing id.
+ */
+function needsAgent(command) {
+  return `no coding agent connected yet -- run '${cliInvocation()} connect', then '${cliInvocation()} ${command}'`;
+}
+
 /** "yes" | "no" | "back" -- back only offered once there is somewhere to go. */
 async function askStep(question, { assumeYes, canGoBack }) {
   if (assumeYes) return "yes";
@@ -319,7 +366,10 @@ async function askStep(question, { assumeYes, canGoBack }) {
  * throws is reported and the run continues rather than unwinding the ones that
  * already worked.
  */
-export async function onboardCommand(commandArgs, { makeArgs, authenticateTerminal, connectCommand }) {
+export async function onboardCommand(
+  commandArgs,
+  { makeArgs, authenticateTerminal, connectCommand, discoverEndpoints, runnerCommand }
+) {
   const args = makeArgs(commandArgs);
   const assumeYes = args.has("--yes");
 
@@ -328,11 +378,33 @@ export async function onboardCommand(commandArgs, { makeArgs, authenticateTermin
   const creds = await authenticateTerminal(args);
   connected(`Signed in as ${creds.user_email || "your account"}.`);
 
+  // Which agent the endpoints and runner steps drive. `connect` decided it, by
+  // detection or by asking, and this is the answer rather than a second prompt.
+  let linked = null;
+
   const steps = [
     {
       name: "coding agent",
       question: "Connect your coding agent?",
-      run: () => connectCommand([...commandArgs, "--skip-login"]),
+      run: async () => {
+        linked = (await connectCommand([...commandArgs, "--skip-login"])) || null;
+      },
+    },
+    {
+      name: "endpoints",
+      question: "Map this repository's endpoints?",
+      run: () => {
+        if (!linked?.agent) throw new Error(needsAgent("endpoints discover"));
+        return discoverEndpoints(args, linked.agent, linked.serverName);
+      },
+    },
+    {
+      name: "runner",
+      question: "Let PreMan run your agent here when it finds something to fix?",
+      run: () => {
+        if (!linked?.agent) throw new Error(needsAgent("runner start --background"));
+        return runnerCommand(["start", "--background", "--agent", linked.agent.id]);
+      },
     },
     { name: "GitHub", question: "Connect GitHub?", run: () => githubCommand(args) },
     { name: "AWS logs", question: "Connect AWS?", run: () => awsCommand(args) },
@@ -392,7 +464,8 @@ export async function onboardCommand(commandArgs, { makeArgs, authenticateTermin
 
 export const INTEGRATIONS_HELP = `
 Setup options:
-  preman onboard              Sign in, then connect agent, GitHub, AWS and Slack
+  preman onboard              Sign in, then agent, endpoints, runner, GitHub,
+                              AWS and Slack, one prompt per step
   preman aws                  Connect an AWS account and stream a log group
   preman github               Install the PreMan GitHub App
   preman slack                Add PreMan to a Slack workspace