premanmcp 0.7.1 → 0.9.0

package/bin/hook.js

@@ -0,0 +1,165 @@
+/**
+ * `preman hook install|uninstall|status` — the git pre-push entry point.
+ *
+ * The single most important property here: **PreMan must never block a push.**
+ * No backend, no credentials, no detectable local target, a crash, or a timeout
+ * all exit 0 with a notice. A tool that stops `git push` when its own
+ * infrastructure is down gets uninstalled the same day, so the hook is advisory
+ * by construction rather than by configuration.
+ */
+
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+import { cliInvocation, makeArgs } 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
+  --force               Overwrite a foreign pre-push hook (a backup is kept)
+`;
+
+const MARKER = "# >>> preman pre-push >>>";
+const END_MARKER = "# <<< preman pre-push <<<";
+const HOOK_TIMEOUT_SECONDS = 120;
+
+function gitDir() {
+  const result = spawnSync("git", ["rev-parse", "--git-dir"], { encoding: "utf8" });
+  if (result.status !== 0) {
+    throw new Error("not inside a git repository");
+  }
+  return path.resolve(result.stdout.trim());
+}
+
+function hookPath() {
+  return path.join(gitDir(), "hooks", "pre-push");
+}
+
+function hookBody() {
+  // `exec` is deliberately absent: we want the wrapper to survive the CLI exiting
+  // non-zero and still exit 0 itself.
+  //
+  // Git's ref payload arrives on this script's stdin and is what tells PreMan
+  // which commits are actually being pushed, so it is piped straight through.
+  return `#!/bin/sh
+${MARKER}
+# Managed by PreMan. Runs the local endpoint suite before the push leaves.
+# 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_status=$?
+  if [ "$preman_status" -eq ${BLOCK_EXIT_CODE} ]; then
+    exit ${BLOCK_EXIT_CODE}
+  fi
+  if [ "$preman_status" -ne 0 ]; then
+    printf '[preman] checks skipped (%s)\\n' "advisory" >&2
+  fi
+fi
+${END_MARKER}
+exit 0
+`;
+}
+
+function isOurHook(text) {
+  return text.includes(MARKER);
+}
+
+export function installHook(args) {
+  const target = hookPath();
+  mkdirSync(path.dirname(target), { recursive: true });
+
+  if (existsSync(target)) {
+    const existing = readFileSync(target, "utf8");
+    if (isOurHook(existing)) {
+      writeFileSync(target, hookBody(), { mode: 0o755 });
+      chmodSync(target, 0o755);
+      return { path: target, action: "updated" };
+    }
+    if (!args.has("--force")) {
+      return {
+        path: target,
+        action: "conflict",
+        detail: "a pre-push hook already exists; re-run with --force to replace it",
+      };
+    }
+    const backup = `${target}.preman-backup`;
+    writeFileSync(backup, existing, { mode: 0o755 });
+    writeFileSync(target, hookBody(), { mode: 0o755 });
+    chmodSync(target, 0o755);
+    return { path: target, action: "replaced", detail: `previous hook saved to ${backup}` };
+  }
+
+  writeFileSync(target, hookBody(), { mode: 0o755 });
+  chmodSync(target, 0o755);
+  return { path: target, action: "installed" };
+}
+
+export function uninstallHook() {
+  const target = hookPath();
+  if (!existsSync(target)) return { path: target, action: "absent" };
+  const existing = readFileSync(target, "utf8");
+  if (!isOurHook(existing)) {
+    return { path: target, action: "foreign", detail: "left in place; PreMan did not write it" };
+  }
+  unlinkSync(target);
+  const backup = `${target}.preman-backup`;
+  if (existsSync(backup)) {
+    writeFileSync(target, readFileSync(backup, "utf8"), { mode: 0o755 });
+    unlinkSync(backup);
+    return { path: target, action: "restored", detail: "previous hook restored from backup" };
+  }
+  return { path: target, action: "removed" };
+}
+
+export function hookStatus() {
+  const target = hookPath();
+  if (!existsSync(target)) return { path: target, state: "absent" };
+  const existing = readFileSync(target, "utf8");
+  return { path: target, state: isOurHook(existing) ? "installed" : "foreign" };
+}
+
+export async function hookCommand(commandArgs = []) {
+  const sub = commandArgs.find((value) => !value.startsWith("-")) || "status";
+  const args = makeArgs(commandArgs);
+
+  if (sub === "install") {
+    const result = installHook(args);
+    if (result.action === "conflict") {
+      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` : "") +
+        `\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 === "uninstall") {
+    const result = uninstallHook();
+    process.stdout.write(
+      `Pre-push hook ${result.action}: ${result.path}\n` + (result.detail ? `  ${result.detail}\n` : "")
+    );
+    return result;
+  }
+
+  if (sub === "status") {
+    const result = hookStatus();
+    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`);
+    return result;
+  }
+
+  throw new Error(`unknown hook subcommand: ${sub}${HOOK_HELP}`);
+}

package/bin/integrations.js

@@ -14,12 +14,11 @@
  * hand, and no third-party credential ever touches the terminal.
  */
 
-import { spawn } from "node:child_process";
-
 import {
   assertOk,
   callBackendJson,
   frontendUrl,
+  openUrl,
   promptText,
   resolveApiKey,
 } from "./shared.js";
@@ -42,9 +41,9 @@ function paint(code, text) {
 }
 
 export const MARK = {
-  ok: () => paint("32", "✓"),
-  skip: () => paint("90", "○"),
-  fail: () => paint("31", "✗"),
+  ok: () => paint("32", "?"),
+  skip: () => paint("90", "?"),
+  fail: () => paint("31", "?"),
 };
 
 /** A finished step, marked so it can be found at a glance. */
@@ -52,25 +51,6 @@ export function connected(message) {
   process.stdout.write(`${MARK.ok()} ${message}\n`);
 }
 
-/** Open a URL in the customer's default browser, best effort. */
-export function openUrl(url) {
-  const command =
-    process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-  try {
-    const child = spawn(command, [url], {
-      stdio: "ignore",
-      detached: true,
-      shell: process.platform === "win32",
-    });
-    child.unref();
-    return true;
-  } catch {
-    // Headless boxes and locked-down shells are normal. The URL is printed
-    // either way, so this is a convenience, never the only path.
-    return false;
-  }
-}
-
 function present(url, what) {
   process.stdout.write(`\n  ${url}\n\n`);
   if (openUrl(url)) process.stdout.write(`Opened ${what} in your browser.\n`);
@@ -349,7 +329,7 @@ export async function onboardCommand(commandArgs, { makeArgs, authenticateTermin
   let i = 0;
   while (i < steps.length) {
     const step = steps[i];
-    process.stdout.write(`\n── ${step.name} ──\n`);
+    process.stdout.write(`\n?? ${step.name} ??\n`);
 
     const choice = await askStep(step.question, { assumeYes, canGoBack: i > 0 });
     if (choice === "back") {
@@ -377,7 +357,7 @@ export async function onboardCommand(commandArgs, { makeArgs, authenticateTermin
     i += 1;
   }
 
-  process.stdout.write("\n── done ──\n");
+  process.stdout.write("\n?? done ??\n");
   // One line per step, marked, so the outcome is scannable rather than prose.
   for (const step of steps) {
     const result = outcome.get(step.name);

package/bin/progress.js

@@ -0,0 +1,110 @@
+/**
+ * Live terminal rendering for concurrent work.
+ *
+ * A pre-push run is the moment the developer is watching, so silence for the
+ * length of a 120-second budget reads as a hang. This renders one line per
+ * worker, updated in place, with finished results scrolling above them.
+ *
+ * Everything degrades to plain sequential lines when stdout is not a TTY. A
+ * hook's output is routinely piped, captured by a GUI git client, or read in
+ * CI, and cursor-movement escapes in a log file are worse than no animation.
+ */
+
+const FRAMES = ["\u280b", "\u2819", "\u2839", "\u2838", "\u283c", "\u2834", "\u2826", "\u2827", "\u2807", "\u280f"];
+const FRAME_MS = 80;
+
+const CLEAR_LINE = "\u001b[2K";
+const HIDE_CURSOR = "\u001b[?25l";
+const SHOW_CURSOR = "\u001b[?25h";
+
+const GREEN = "\u001b[32m";
+const RED = "\u001b[31m";
+const YELLOW = "\u001b[33m";
+const DIM = "\u001b[2m";
+const RESET = "\u001b[0m";
+
+function truncate(text, width) {
+  const value = String(text ?? "");
+  return value.length <= width ? value : `${value.slice(0, Math.max(0, width - 1))}\u2026`;
+}
+
+export function createReporter({ stream = process.stdout, live } = {}) {
+  const isLive = live ?? Boolean(stream.isTTY);
+  const slots = new Map();
+  let rendered = 0;
+  let frame = 0;
+  let timer = null;
+  const colour = (code, text) => (isLive ? `${code}${text}${RESET}` : text);
+
+  function width() {
+    return Math.max(40, Math.min(stream.columns || 100, 140));
+  }
+
+  function clearLive() {
+    if (!isLive || rendered === 0) return;
+    stream.write(`\u001b[${rendered}A`);
+    for (let i = 0; i < rendered; i += 1) stream.write(`${CLEAR_LINE}\n`);
+    stream.write(`\u001b[${rendered}A`);
+    rendered = 0;
+  }
+
+  function drawLive() {
+    if (!isLive || slots.size === 0) return;
+    const spin = FRAMES[frame % FRAMES.length];
+    for (const label of slots.values()) {
+      stream.write(`${CLEAR_LINE}  ${colour(YELLOW, spin)} ${truncate(label, width() - 6)}\n`);
+    }
+    rendered = slots.size;
+  }
+
+  function repaint() {
+    clearLive();
+    drawLive();
+  }
+
+  return {
+    isLive,
+
+    /** Print a line that stays in the scrollback, above the live region. */
+    line(text) {
+      clearLive();
+      stream.write(`${text}\n`);
+      drawLive();
+    },
+
+    /** Claim a worker line. `slot` is any stable key for that worker. */
+    busy(slot, label) {
+      slots.set(slot, label);
+      if (!isLive) return;
+      if (timer === null) {
+        stream.write(HIDE_CURSOR);
+        timer = setInterval(() => {
+          frame += 1;
+          repaint();
+        }, FRAME_MS);
+        if (typeof timer.unref === "function") timer.unref();
+      }
+      repaint();
+    },
+
+    /** Release a worker line and record its outcome in the scrollback. */
+    done(slot, { ok, skipped, label, detail }) {
+      slots.delete(slot);
+      const mark = skipped ? colour(DIM, "\u00b7") : ok ? colour(GREEN, "\u2713") : colour(RED, "\u2717");
+      const tail = detail ? ` ${colour(DIM, detail)}` : "";
+      clearLive();
+      stream.write(`  ${mark} ${truncate(label, width() - 12)}${tail}\n`);
+      drawLive();
+    },
+
+    stop() {
+      if (timer !== null) {
+        clearInterval(timer);
+        timer = null;
+      }
+      clearLive();
+      slots.clear();
+      if (isLive) stream.write(SHOW_CURSOR);
+    },
+  };
+}

package/bin/shared.js

@@ -7,7 +7,7 @@
  * over a module-level argv, so a command can pass its own slice.
  */
 
-import { spawnSync } from "node:child_process";
+import { 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";
@@ -101,6 +101,36 @@ export function frontendUrl(args) {
   return args.value("--frontend", process.env.PREMAN_FRONTEND || DEFAULT_FRONTEND).replace(/\/+$/, "");
 }
 
+/**
+ * Open a URL in the user's default browser, best effort.
+ *
+ * Returns false without spawning anything when nobody is there to look at it:
+ * `PREMAN_NO_BROWSER` for an explicit no, and a non-TTY stdout for CI, piped
+ * output, and test runs. Every caller prints the URL as well, so this is only
+ * ever a convenience — a suite that exercises these flows should not be able to
+ * throw tabs at whoever is running it.
+ */
+export function openUrl(url) {
+  const optOut = (process.env.PREMAN_NO_BROWSER || "").trim().toLowerCase();
+  if (optOut && !["0", "false", "no"].includes(optOut)) return false;
+  if (!process.stdout.isTTY) return false;
+
+  const opener =
+    process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  try {
+    const child = spawn(opener, [url], {
+      stdio: "ignore",
+      detached: true,
+      shell: process.platform === "win32",
+    });
+    child.unref();
+    return true;
+  } catch {
+    // Headless boxes and locked-down shells are normal.
+    return false;
+  }
+}
+
 export async function promptText(question) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {
@@ -171,7 +201,12 @@ export async function promptPasswordTwice() {
   return password;
 }
 
-export async function callBackendJson(args, method, routePath, { json, token, query } = {}) {
+export async function callBackendJson(
+  args,
+  method,
+  routePath,
+  { json, token, query, headers: extraHeaders } = {}
+) {
   const url = new URL(routePath.replace(/^\/+/, ""), `${backendUrl(args)}/`);
   if (query) {
     for (const [key, value] of Object.entries(query)) {
@@ -183,6 +218,11 @@ export async function callBackendJson(args, method, routePath, { json, token, qu
   const hasBody = json !== undefined && json !== null;
   if (hasBody) headers["Content-Type"] = "application/json";
   if (token) headers.Authorization = `Bearer ${token}`;
+  if (extraHeaders) {
+    for (const [key, value] of Object.entries(extraHeaders)) {
+      if (value != null && value !== "") headers[key] = String(value);
+    }
+  }
 
   const resp = await fetch(url, {
     method,
@@ -225,7 +265,50 @@ async function verifyUnconfirmedAccount(args, email) {
   return verified.access_token;
 }
 
+/**
+ * A password only if the caller asked for one.
+ *
+ * The terminal's durable credential is the pm_live_ key, so signup does not
+ * need a password and no longer asks for one. `--password` is for anyone who
+ * wants to be able to sign in to the dashboard immediately; `--password <value>`
+ * skips the prompt for scripted runs.
+ */
+async function optionalPassword(args) {
+  if (!args.has("--password")) return "";
+  const supplied = args.value("--password", "");
+  // Bare `--password` followed by another flag means "prompt me", not "my
+  // password is --backend".
+  if (supplied && !supplied.startsWith("--")) {
+    if (supplied.length < 6) throw new Error("Password must be at least 6 characters.");
+    return supplied;
+  }
+  return promptPasswordTwice();
+}
+
+/**
+ * Turn a verification code into a session token.
+ *
+ * Without a password this is one call: verify-otp signs the user in and the
+ * backend keeps the account passwordless, so the dashboard knows to offer a
+ * code rather than a password field.
+ */
+async function completeWithCode(args, email, otp, password) {
+  if (password) {
+    const setPassword = await callBackendJson(args, "POST", "/auth/set-password", {
+      json: { email, otp, new_password: password },
+    });
+    assertOk(setPassword, "set password");
+    return String(setPassword.access_token || "");
+  }
+  const verified = await callBackendJson(args, "POST", "/auth/verify-otp", {
+    json: { email, otp },
+  });
+  assertOk(verified, "verify OTP");
+  return String(verified.access_token || "");
+}
+
 async function createAccountFromTerminal(args, email) {
+  const password = await optionalPassword(args);
   const signup = await callBackendJson(args, "POST", "/auth/start-signup", {
     json: { email },
   });
@@ -233,24 +316,21 @@ async function createAccountFromTerminal(args, email) {
   if (signup.ok) {
     process.stdout.write("Verification code sent. Check your email.\n");
     const otp = await promptText("Verification code: ");
-    const password = await promptPasswordTwice();
-    const setPassword = await callBackendJson(args, "POST", "/auth/set-password", {
-      json: { email, otp, new_password: password },
-    });
-    assertOk(setPassword, "set password");
-    return String(setPassword.access_token || "");
+    return completeWithCode(args, email, otp, password);
   }
 
   if (signup.status_code !== 404) {
     assertOk(signup, "start signup");
   }
 
+  // Backends predating start-signup have no passwordless route in, so this one
+  // path still has to ask.
   process.stdout.write(
     "This PreMan backend uses the password-first signup flow. Create your password now, then enter the email code.\n"
   );
-  const password = await promptPasswordTwice();
+  const legacyPassword = password || (await promptPasswordTwice());
   const legacySignup = await callBackendJson(args, "POST", "/auth/signup", {
-    json: { email, password },
+    json: { email, password: legacyPassword },
   });
   assertOk(legacySignup, "signup");
   process.stdout.write("Verification code sent. Check your email.\n");
@@ -293,26 +373,31 @@ export async function authenticateTerminal(args) {
     process.stdout.write("No PreMan account found. Creating one now.\n");
     accessToken = await createAccountFromTerminal(args, email);
   } else if (account.needs_password) {
-    process.stdout.write("This account needs a password. Sending an OTP first.\n");
+    // No password on this account, so a code is the only way in.
+    const password = await optionalPassword(args);
+    process.stdout.write("Sending a sign-in code to your email.\n");
     const resend = await callBackendJson(args, "POST", "/auth/resend-otp", { json: { email } });
     assertOk(resend, "resend OTP");
     const otp = await promptText("Verification code: ");
-    const password = await promptPasswordTwice();
-    const setPassword = await callBackendJson(args, "POST", "/auth/set-password", {
-      json: { email, otp, new_password: password },
-    });
-    assertOk(setPassword, "set password");
-    accessToken = String(setPassword.access_token || "");
+    accessToken = await completeWithCode(args, email, otp, password);
   } else {
-    const password = await promptSecret("Password: ");
-    const login = await callBackendJson(args, "POST", "/auth/login", {
-      json: { email, password },
-    });
-    if (!login.ok && login.status_code === 403 && String(login.detail || "").toLowerCase().includes("not verified")) {
-      accessToken = await verifyUnconfirmedAccount(args, email);
+    const password = await promptSecret("Password (Enter to get a code by email): ");
+    if (!password) {
+      const resend = await callBackendJson(args, "POST", "/auth/resend-otp", { json: { email } });
+      assertOk(resend, "resend OTP");
+      process.stdout.write("Sign-in code sent. Check your email.\n");
+      const otp = await promptText("Verification code: ");
+      accessToken = await completeWithCode(args, email, otp, "");
     } else {
-      assertOk(login, "login");
-      accessToken = String(login.access_token || "");
+      const login = await callBackendJson(args, "POST", "/auth/login", {
+        json: { email, password },
+      });
+      if (!login.ok && login.status_code === 403 && String(login.detail || "").toLowerCase().includes("not verified")) {
+        accessToken = await verifyUnconfirmedAccount(args, email);
+      } else {
+        assertOk(login, "login");
+        accessToken = String(login.access_token || "");
+      }
     }
   }
 
@@ -360,6 +445,16 @@ export function resolveApiKey(args) {
  * Matches the backend's install snippets (`build_install_snippets`) so the
  * copy-paste path and this writer cannot drift.
  */
+// npm exec rather than npx: same resolution, but it is the command every install
+// of npm ships, and it is what the rest of our instructions use. The trailing "--"
+// stops npm from claiming flags meant for the server.
+//
+// Exported so the post-write verifier checks for the launcher we actually emit.
+// These drifted once already -- every writer emitted "npm" while the verifier
+// demanded "npx", so every connect printed a mismatch warning.
+export const LAUNCHER_COMMAND = "npm";
+export const LAUNCHER_ARGS = ["exec", "-y", "premanmcp@latest", "--"];
+
 export function buildServerConfig(args, { pairCode = "" } = {}) {
   const env = {
     PREMAN_BACKEND: backendUrl(args),
@@ -370,11 +465,8 @@ export function buildServerConfig(args, { pairCode = "" } = {}) {
   if (pairCode) env.PREMAN_PAIR_CODE = pairCode;
 
   return {
-    // npm exec rather than npx: same resolution, but it is the command every
-    // install of npm ships, and it is what the rest of our instructions use.
-    // The trailing "--" stops npm from claiming flags meant for the server.
-    command: "npm",
-    args: ["exec", "-y", "premanmcp@latest", "--"],
+    command: LAUNCHER_COMMAND,
+    args: [...LAUNCHER_ARGS],
     env,
   };
 }