premanmcp 0.7.1 → 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/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

@@ -171,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)) {
@@ -183,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,
@@ -360,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),
@@ -370,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,
   };
 }

package/bin/status.js

@@ -0,0 +1,210 @@
+/**
+ * `preman status` — endpoint health in the terminal.
+ *
+ * One request to GET /cli/status, rendered as a table. The backend degrades
+ * individual sections rather than failing, so this renderer must treat every
+ * section as possibly empty.
+ */
+
+import { backendUrl, callBackendJson, cliInvocation, makeArgs, resolveApiKey } from "./shared.js";
+
+export const STATUS_HELP = `
+Status options:
+  --workspace <id>      Workspace to report on. Defaults to your primary workspace
+  --json                Print the raw JSON payload instead of a table
+  --no-color            Disable ANSI colour
+`;
+
+// Honour the conventions people already expect from CLIs, so status can be piped
+// into a file or a CI log without escape codes landing in it.
+function makePaint(enabled) {
+  const wrap = (code) => (text) => (enabled ? `\u001b[${code}m${text}\u001b[0m` : String(text));
+  return {
+    green: wrap("32"),
+    red: wrap("31"),
+    yellow: wrap("33"),
+    blue: wrap("36"),
+    dim: wrap("2"),
+    bold: wrap("1"),
+  };
+}
+
+function colourEnabled(args) {
+  if (args.has("--no-color") || args.has("--no-colour")) return false;
+  if (process.env.NO_COLOR) return false;
+  if (process.env.FORCE_COLOR) return true;
+  return Boolean(process.stdout.isTTY);
+}
+
+function relativeTime(iso) {
+  if (!iso) return "";
+  const then = Date.parse(iso);
+  if (Number.isNaN(then)) return "";
+  const seconds = Math.max(0, Math.round((Date.now() - then) / 1000));
+  if (seconds < 60) return `${seconds}s ago`;
+  if (seconds < 3600) return `${Math.round(seconds / 60)}m ago`;
+  if (seconds < 86400) return `${Math.round(seconds / 3600)}h ago`;
+  return `${Math.round(seconds / 86400)}d ago`;
+}
+
+function truncate(value, width) {
+  const text = String(value ?? "");
+  return text.length <= width ? text : `${text.slice(0, width - 1)}…`;
+}
+
+const MAX_TARGET_WIDTH = 46;
+
+/** Column widths are measured across every row we will print, so the failing and
+ *  healthy blocks line up with each other rather than each aligning internally. */
+function endpointColumns(groups) {
+  const all = groups.flat();
+  return {
+    method: Math.max(3, ...all.map((e) => String(e.method || "GET").length)),
+    target: Math.min(
+      MAX_TARGET_WIDTH,
+      Math.max(8, ...all.map((e) => String(e.url || e.name || "").length))
+    ),
+  };
+}
+
+function renderEndpointRows(entries, { symbol, paint, colour, columns }) {
+  return entries.map((entry) => {
+    const method = String(entry.method || "GET").padEnd(columns.method);
+    const target = truncate(entry.url || entry.name || "", columns.target).padEnd(columns.target);
+    const code = entry.status_code ? String(entry.status_code) : "";
+    const trailing = [code, entry.error ? truncate(entry.error, 38) : "", relativeTime(entry.last_run_at)]
+      .filter(Boolean)
+      .join("  ");
+    return `  ${colour(symbol)} ${paint.dim(method)}  ${target}  ${paint.dim(trailing)}`.trimEnd();
+  });
+}
+
+export function renderStatus(payload, { colour = false } = {}) {
+  const paint = makePaint(colour);
+  const lines = [];
+
+  const workspace = payload.workspace || {};
+  lines.push(`${paint.bold("PreMan")} ${paint.dim("·")} ${workspace.name || "workspace"}`);
+  lines.push("");
+
+  const endpoints = payload.endpoints || {};
+  const healthy = Number(endpoints.healthy || 0);
+  const failing = Number(endpoints.failing || 0);
+  const untested = Number(endpoints.untested || 0);
+  const total = Number(endpoints.total || 0);
+
+  if (total === 0) {
+    lines.push(paint.dim("No saved endpoints yet."));
+    lines.push(paint.dim(`Run \`${cliInvocation()} endpoints discover\` to scan this repo.`));
+  } else {
+    const summary = [
+      failing ? paint.red(`${failing} failing`) : null,
+      healthy ? paint.green(`${healthy} healthy`) : null,
+      untested ? paint.yellow(`${untested} untested`) : null,
+    ]
+      .filter(Boolean)
+      .join(paint.dim(" · "));
+    lines.push(`${paint.bold("Endpoints")}  ${summary} ${paint.dim(`(${total} total)`)}`);
+
+    const failingExamples = endpoints.failing_examples || [];
+    const healthyExamples = endpoints.healthy_examples || [];
+    const columns = endpointColumns([failingExamples, healthyExamples]);
+    if (failingExamples.length) {
+      lines.push("");
+      lines.push(
+        ...renderEndpointRows(failingExamples, { symbol: "✗", paint, colour: paint.red, columns })
+      );
+    }
+    if (healthyExamples.length) {
+      lines.push("");
+      lines.push(
+        ...renderEndpointRows(healthyExamples, { symbol: "✓", paint, colour: paint.green, columns })
+      );
+    }
+  }
+
+  const fixed = payload.recently_fixed || [];
+  if (fixed.length) {
+    lines.push("");
+    lines.push(`${paint.bold("Recently fixed")} ${paint.dim("(7d)")}`);
+    for (const entry of fixed) {
+      const label = truncate(entry.title || entry.source_kind || "fix", 40).padEnd(40);
+      const pr = entry.pr_url ? paint.blue(entry.pr_url) : paint.dim("no PR recorded");
+      lines.push(`  ${paint.green("✓")} ${label} ${pr} ${paint.dim(relativeTime(entry.resolved_at))}`);
+    }
+  }
+
+  const push = payload.last_push;
+  lines.push("");
+  if (push) {
+    const verdict = push.verdict || push.status || "unknown";
+    const paintVerdict =
+      verdict === "impact_detected" ? paint.red : verdict === "no_impact" ? paint.green : paint.yellow;
+    lines.push(
+      `${paint.bold("Last push")}  ${push.repo || ""} ${paint.dim(`${push.branch || ""}@${push.commit || ""}`)} ` +
+        `${paintVerdict(verdict)} ${paint.dim(relativeTime(push.finished_at))}`
+    );
+  } else {
+    lines.push(`${paint.bold("Last push")}  ${paint.dim("no simulations yet")}`);
+  }
+
+  const observed = payload.observed_prod || {};
+  const routes = observed.routes || [];
+  if (routes.length) {
+    lines.push("");
+    lines.push(`${paint.bold("Production")} ${paint.dim("(24h)")}`);
+    const shown = routes.slice(0, 5);
+    const columns = endpointColumns([shown.map((r) => ({ method: r.method, url: r.route }))]);
+    const callsWidth = Math.max(...shown.map((r) => `${r.observations || 0} calls`.length));
+    for (const route of shown) {
+      const method = String(route.method || "GET").padEnd(columns.method);
+      const target = truncate(route.route, columns.target).padEnd(columns.target);
+      const errors = Number(route.errors || 0);
+      const errText = errors ? paint.red(`${errors} errors`) : paint.dim("clean");
+      const calls = `${route.observations || 0} calls`.padStart(callsWidth);
+      lines.push(`    ${paint.dim(method)}  ${target}  ${paint.dim(calls)}  ${errText}`);
+    }
+  } else if (observed.hint) {
+    lines.push("");
+    lines.push(`${paint.bold("Production")}  ${paint.dim(observed.hint)}`);
+  }
+
+  const integrations = payload.integrations || {};
+  const mark = (section) => (section && section.connected ? paint.green("✓") : paint.dim("–"));
+  lines.push("");
+  lines.push(
+    `${paint.bold("Integrations")}  github ${mark(integrations.github)}  ` +
+      `logs ${mark(integrations.logs)}  slack ${mark(integrations.slack)}`
+  );
+
+  return `${lines.join("\n")}\n`;
+}
+
+export async function statusCommand(commandArgs = []) {
+  const args = makeArgs(commandArgs);
+  const token = resolveApiKey(args);
+  if (!token) {
+    throw new Error(
+      `no PreMan API key found. Run \`${cliInvocation()} login\` first, or pass --api-key.`
+    );
+  }
+
+  const result = await callBackendJson(args, "GET", "/cli/status", {
+    token,
+    headers: { "x-workspace-id": args.value("--workspace", "") },
+  });
+
+  if (!result.ok) {
+    const detail = result.detail || result.raw || "request failed";
+    throw new Error(`could not read status from ${backendUrl(args)}: ${result.status_code} ${detail}`);
+  }
+
+  const { status_code, ok, ...payload } = result;
+  if (args.has("--json")) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return payload;
+  }
+
+  process.stdout.write(renderStatus(payload, { colour: colourEnabled(args) }));
+  return payload;
+}