premanmcp 0.7.0 → 0.8.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

@@ -224,8 +224,13 @@ export async function awsCommand(args) {
 export async function githubCommand(args) {
   const token = requireKey(args);
 
-  const before = await callBackendJson(args, "GET", "/integrations/github", { token });
-  const seen = new Set((before.integrations || before.repos || []).map((r) => r.id));
+  // This route answers with a bare array; callBackendJson exposes it as `list`.
+  const listRepos = async () => {
+    const resp = await callBackendJson(args, "GET", "/integrations/github", { token });
+    return resp.list || resp.integrations || resp.repos || [];
+  };
+
+  const seen = new Set((await listRepos()).map((r) => r.id));
 
   const started = await callBackendJson(args, "POST", "/integrations/github/app/install", {
     token,
@@ -239,11 +244,17 @@ export async function githubCommand(args) {
   process.stdout.write("Pick the repositories PreMan may read.\n");
 
   const done = await waitFor("the installation", async () => {
-    const now = await callBackendJson(args, "GET", "/integrations/github", { token });
-    const rows = now.integrations || now.repos || [];
+    // Installing the App and having repositories appear are two events: the
+    // 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", {
+      token,
+      json: {},
+    });
     // Compare against what existed before, so a user who already had repos
     // connected is not told they are done the moment polling starts.
-    const fresh = rows.filter((r) => !seen.has(r.id));
+    const fresh = (await listRepos()).filter((r) => !seen.has(r.id));
     return fresh.length ? fresh : null;
   });
 
@@ -289,10 +300,14 @@ export async function slackCommand(args) {
 // The guided run
 // ---------------------------------------------------------------------------
 
-async function askYes(question, { assumeYes }) {
-  if (assumeYes) return true;
-  const answer = (await promptText(`${question} [Y/n]: `)).trim().toLowerCase();
-  return answer === "" || answer === "y" || answer === "yes";
+/** "yes" | "no" | "back" -- back only offered once there is somewhere to go. */
+async function askStep(question, { assumeYes, canGoBack }) {
+  if (assumeYes) return "yes";
+  const hint = canGoBack ? "[Y/n/b]" : "[Y/n]";
+  const answer = (await promptText(`${question} ${hint}: `)).trim().toLowerCase();
+  if (canGoBack && (answer === "b" || answer === "back")) return "back";
+  if (answer === "" || answer === "y" || answer === "yes") return "yes";
+  return "no";
 }
 
 /**
@@ -323,32 +338,54 @@ export async function onboardCommand(commandArgs, { makeArgs, authenticateTermin
     { name: "Slack", question: "Connect Slack?", run: () => slackCommand(args) },
   ];
 
-  const done = [];
-  const skipped = [];
-  const failed = [];
-
-  for (const step of steps) {
+  // Outcome per step rather than three lists, so revisiting a step replaces its
+  // result instead of recording it twice.
+  const outcome = new Map();
+
+  // Indexed rather than for..of so "back" can move the cursor. Re-running a
+  // step is safe: every one of these is idempotent on the backend -- an AWS
+  // grant returns the existing link, and an App install that already happened
+  // is detected rather than duplicated.
+  let i = 0;
+  while (i < steps.length) {
+    const step = steps[i];
     process.stdout.write(`\n── ${step.name} ──\n`);
-    if (!(await askYes(step.question, { assumeYes }))) {
-      skipped.push(step.name);
+
+    const choice = await askStep(step.question, { assumeYes, canGoBack: i > 0 });
+    if (choice === "back") {
+      // Drop the result we are about to redo, or the summary would report the
+      // stale outcome of a step the customer chose to revisit.
+      outcome.delete(steps[i - 1].name);
+      i -= 1;
       continue;
     }
+    if (choice === "no") {
+      outcome.set(step.name, { state: "skipped" });
+      i += 1;
+      continue;
+    }
+
     try {
       await step.run();
-      done.push(step.name);
+      outcome.set(step.name, { state: "done" });
     } catch (err) {
       // Report and carry on: a failed Slack install must not cost the customer
       // the AWS connection they just finished.
-      failed.push(`${step.name}: ${err.message}`);
+      outcome.set(step.name, { state: "failed", detail: err.message });
       process.stdout.write(`Could not finish ${step.name}: ${err.message}\n`);
     }
+    i += 1;
   }
 
   process.stdout.write("\n── done ──\n");
   // One line per step, marked, so the outcome is scannable rather than prose.
-  for (const name of done) process.stdout.write(`${MARK.ok()} ${name}\n`);
-  for (const name of skipped) process.stdout.write(`${MARK.skip()} ${name} (skipped)\n`);
-  for (const failure of failed) process.stdout.write(`${MARK.fail()} ${failure}\n`);
+  for (const step of steps) {
+    const result = outcome.get(step.name);
+    if (!result) continue;
+    if (result.state === "done") process.stdout.write(`${MARK.ok()} ${step.name}\n`);
+    else if (result.state === "skipped") process.stdout.write(`${MARK.skip()} ${step.name} (skipped)\n`);
+    else process.stdout.write(`${MARK.fail()} ${step.name}: ${result.detail}\n`);
+  }
   process.stdout.write(`\nOpen ${frontendUrl(args)} to see your logs and endpoints.\n`);
 }
 
@@ -360,6 +397,7 @@ Setup options:
   preman slack                Add PreMan to a Slack workspace
 
   --yes                       Accept every step without prompting (onboard)
+  b at any onboard prompt     Go back to the previous step
   --account <id>              AWS account id, skips the prompt
   --region <region>           AWS region for log groups. Defaults to us-east-1
   --project-id <id>           PreMan project to attach the log connector to

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,6 +7,7 @@
  * over a module-level argv, so a command can pass its own slice.
  */
 
+import { spawnSync } from "node:child_process";
 import { chmodSync, existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -18,6 +19,28 @@ export const CREDENTIALS_DIR = path.join(os.homedir(), ".preman");
 export const CREDENTIALS_FILE = path.join(CREDENTIALS_DIR, "credentials.json");
 
 /** Wrap a raw argv slice in the positional lookup the CLI has always used. */
+/**
+ * How to tell this user to invoke us.
+ *
+ * The help used to say "preman connect" unconditionally, which is only true
+ * after a global install. Anyone reading it straight out of
+ * `npm exec premanmcp -- --help` -- the way the docs tell them to run it --
+ * copied a command that answers "command not found".
+ */
+let _invocation = null;
+
+export function cliInvocation() {
+  if (_invocation) return _invocation;
+  const probe = process.platform === "win32" ? "where" : "which";
+  try {
+    const found = spawnSync(probe, ["preman"], { stdio: "pipe", encoding: "utf8" });
+    _invocation = found.status === 0 && found.stdout.trim() ? "preman" : null;
+  } catch {
+    _invocation = null;
+  }
+  return (_invocation ||= "npm exec -y premanmcp@latest --");
+}
+
 export function makeArgs(commandArgs = []) {
   return {
     raw: commandArgs,
@@ -148,7 +171,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)) {
@@ -160,6 +188,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,
@@ -173,6 +206,12 @@ export async function callBackendJson(args, method, routePath, { json, token, qu
   } catch {
     body = { raw: text };
   }
+  // Some routes answer with a bare array. Spreading one into this object turns
+  // it into {0:…,1:…} and quietly loses the list, so it gets its own key.
+  if (Array.isArray(body)) {
+    return { status_code: resp.status, ok: resp.ok, list: body };
+  }
+
   return {
     status_code: resp.status,
     ok: resp.ok,
@@ -331,6 +370,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),
@@ -341,11 +390,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,
   };
 }