premanmcp 0.7.1 → 0.9.0

package/README.md

@@ -19,11 +19,12 @@ Local development form:
 node bin/cli.js connect
 ```
 
-First-time users are prompted for email, OTP, and password directly in the terminal.
-PreMan creates or connects the account, generates an API key, saves it to
-`~/.preman/credentials.json`, then writes a `preman` MCP server into the config your
-agent actually reads (`~/.cursor/mcp.json`, Claude Code's MCP config, or
-`~/.codex/config.toml`):
+First-time users are asked for an email and the code sent to it — no password: the
+terminal's credential is the `pm_live_` key. Pass `--password` to also set one for
+dashboard sign-in, or set it later from the dashboard. PreMan creates or connects the
+account, generates an API key, saves it to `~/.preman/credentials.json`, then writes a
+`preman` MCP server into the config your agent actually reads (`~/.cursor/mcp.json`,
+Claude Code's MCP config, or `~/.codex/config.toml`):
 
 ```json
 {
@@ -40,11 +41,12 @@ agent actually reads (`~/.cursor/mcp.json`, Claude Code's MCP config, or
 }
 ```
 
-Restart your agent afterwards, then ask it to `run preman_status` to finish linking.
-
 `connect` reads the config back after writing it, and prints a copy-paste snippet if it
-cannot confirm the entry landed. It then waits for your agent to check in — that
-check-in is the only real proof the agent loaded the server.
+cannot confirm the entry landed. It then finishes the link itself by running your agent
+headlessly (`claude -p`, `cursor-agent -p`, `codex exec`) so it makes one PreMan call —
+that check-in is the only real proof the agent loaded the server. If the agent's CLI is
+not on PATH, `connect` asks you to restart it and waits instead. `--no-auto-checkin`
+turns the spawn off.
 
 Once the agent has checked in, `connect` walks you into your first test: it runs one
 against an endpoint you already have, or prints the discovery brief to hand your agent,
@@ -62,10 +64,18 @@ setup blocks for all three agents and exits 2.
 
 ### Cloud dispatch (optional)
 
-`connect` offers to store a coding-agent credential — a Cursor API key, or a Claude
-Code routine token and id. With one saved, PreMan can start an agent run for you when
-it finds a failing endpoint instead of handing back a prompt to paste. Press Enter to
-skip; everything else still works.
+With a coding-agent credential saved — a Cursor API key from
+`cursor.com/dashboard → Integrations → API Keys`, or a Claude Code routine token and id
+from `claude.ai/code/routines → your routine → Add API trigger` — PreMan can start an
+agent run for you when it finds a failing endpoint, instead of handing back a prompt to
+paste.
+
+`connect` asks for it once you are already set up, so skipping costs nothing. Come back
+to it any time:
+
+```bash
+npm exec -y premanmcp@latest -- dispatch
+```
 
 You can also create or connect your account first:
 

package/bin/account.js

@@ -0,0 +1,212 @@
+/**
+ * Account-adjacent commands: browser login, logout, doctor, and watch.
+ *
+ * `loginBrowser` drives the device-code flow at /auth/device/*, which has existed
+ * in the backend with no client. It is the right path for anyone who does not
+ * want to type a password into a terminal, and the only one that works when the
+ * account is behind SSO.
+ */
+
+import { existsSync, rmSync } from "node:fs";
+import os from "node:os";
+
+import { detectCandidates } from "./detect.js";
+import {
+  CREDENTIALS_FILE,
+  backendUrl,
+  callBackendJson,
+  cliInvocation,
+  frontendUrl,
+  makeArgs,
+  openUrl,
+  readStoredCredentials,
+  resolveApiKey,
+  saveStoredCredentials,
+} from "./shared.js";
+
+export const ACCOUNT_HELP = `
+Account options:
+  login --browser       Approve sign-in in the browser instead of typing a password
+  logout                Delete stored CLI credentials
+  doctor                Check backend, credentials, target, and integrations
+  watch <run-id>        Follow a push simulation as it runs
+`;
+
+const POLL_INTERVAL_MS = 3000;
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export async function loginBrowser(args) {
+  const start = await callBackendJson(args, "POST", "/auth/device/request", {
+    json: { device_name: `PreMan CLI (${os.hostname()})` },
+  });
+  if (!start.ok) {
+    throw new Error(`could not start browser login: ${start.status_code} ${start.detail || ""}`);
+  }
+
+  const verificationUrl = start.verification_url || `${frontendUrl(args)}/device/verify?code=${start.device_code}`;
+  process.stdout.write(
+    `\nApprove this device in your browser:\n  ${verificationUrl}\n\n` +
+      `Confirmation code: ${start.user_code}\n\n`
+  );
+  if (!openUrl(verificationUrl)) {
+    process.stdout.write("Could not open a browser automatically — open the link above.\n");
+  }
+  process.stdout.write("Waiting for approval…\n");
+
+  const deadline = Date.now() + LOGIN_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    await sleep(POLL_INTERVAL_MS);
+    const poll = await callBackendJson(args, "POST", "/auth/device/poll", {
+      json: { device_code: start.device_code },
+    });
+    const status = String(poll.status || "").toLowerCase();
+    if (poll.ok && poll.api_key) {
+      const creds = {
+        api_key: String(poll.api_key),
+        backend_url: backendUrl(args),
+        user_email: poll.user_email || "",
+        device_name: os.hostname(),
+        created_at: new Date().toISOString(),
+      };
+      saveStoredCredentials(creds);
+      process.stdout.write(`\nSigned in${creds.user_email ? ` as ${creds.user_email}` : ""}.\n`);
+      process.stdout.write(`Saved to ${CREDENTIALS_FILE}\n`);
+      return creds;
+    }
+    if (status === "expired" || status === "denied") {
+      throw new Error(`browser login ${status}. Run \`${cliInvocation()} login --browser\` again.`);
+    }
+  }
+  throw new Error("browser login timed out after 5 minutes.");
+}
+
+export async function logoutCommand() {
+  if (existsSync(CREDENTIALS_FILE)) {
+    rmSync(CREDENTIALS_FILE, { force: true });
+    process.stdout.write(`Removed ${CREDENTIALS_FILE}\n`);
+  } else {
+    process.stdout.write("No stored credentials to remove.\n");
+  }
+  process.stdout.write(
+    "Note: this does not revoke the API key. Revoke it in the dashboard if the machine is shared.\n"
+  );
+}
+
+function line(label, ok, detail) {
+  const mark = ok === null ? "–" : ok ? "✓" : "✗";
+  return `  ${mark} ${label}${detail ? `  ${detail}` : ""}`;
+}
+
+export async function doctorCommand(commandArgs = []) {
+  const args = makeArgs(commandArgs);
+  const results = [];
+  let failures = 0;
+
+  const stored = readStoredCredentials();
+  const token = resolveApiKey(args);
+  results.push(
+    line(
+      "credentials",
+      Boolean(token),
+      token
+        ? `${stored?.user_email || "key present"} (${CREDENTIALS_FILE})`
+        : `none — run \`${cliInvocation()} login\``
+    )
+  );
+  if (!token) failures += 1;
+
+  let health = { ok: false, status_code: 0, detail: "" };
+  try {
+    health = await callBackendJson(args, "GET", "/health");
+  } catch (error) {
+    health = { ok: false, status_code: 0, detail: String(error?.message || error) };
+  }
+  results.push(line("backend", health.ok, `${backendUrl(args)}${health.ok ? "" : ` — ${health.detail || health.status_code}`}`));
+  if (!health.ok) failures += 1;
+
+  let status = null;
+  if (token && health.ok) {
+    try {
+      status = await callBackendJson(args, "GET", "/cli/status", { token });
+    } catch (error) {
+      status = { ok: false, detail: String(error?.message || error) };
+    }
+    results.push(
+      line("api key", Boolean(status.ok), status.ok ? `workspace ${status.workspace?.name || "?"}` : status.detail || `status ${status.status_code}`)
+    );
+    if (!status.ok) failures += 1;
+  }
+
+  const candidates = detectCandidates(process.cwd());
+  results.push(
+    line(
+      "local target",
+      candidates.length > 0,
+      candidates.length
+        ? `${candidates.length} candidate${candidates.length === 1 ? "" : "s"} (${candidates[0].url} from ${candidates[0].source})`
+        : "no signals in this directory"
+    )
+  );
+
+  if (status?.ok) {
+    const integrations = status.integrations || {};
+    for (const [name, section] of Object.entries(integrations)) {
+      results.push(line(name, Boolean(section?.connected), section?.connected ? "" : "not connected"));
+    }
+    results.push(
+      line("project link", Boolean(status.workspace?.project_id), status.workspace?.project_id ? "" : "workspace is not linked to a project")
+    );
+  }
+
+  process.stdout.write(`PreMan doctor\n\n${results.join("\n")}\n\n`);
+  process.stdout.write(failures ? `${failures} problem${failures === 1 ? "" : "s"} found.\n` : "Everything looks healthy.\n");
+  if (failures) process.exitCode = 1;
+  return { failures };
+}
+
+const TERMINAL_STATUSES = new Set(["complete", "completed", "failed", "error", "cancelled"]);
+
+export async function watchCommand(commandArgs = []) {
+  const args = makeArgs(commandArgs);
+  const token = resolveApiKey(args);
+  if (!token) throw new Error(`no API key. Run \`${cliInvocation()} login\` first.`);
+
+  const positional = commandArgs.filter((value) => !value.startsWith("-"));
+  const runId = args.value("--run", positional[0] || "");
+  const integrationId = args.value("--integration", positional[1] || "");
+  if (!runId || !integrationId) {
+    throw new Error(
+      "usage: watch <run-id> <integration-id>  (both are shown by `preman status`)"
+    );
+  }
+
+  const seen = new Set();
+  const deadline = Date.now() + 15 * 60 * 1000;
+  while (Date.now() < deadline) {
+    const result = await callBackendJson(
+      args,
+      "GET",
+      `/integrations/github/${integrationId}/simulations/${runId}`,
+      { token }
+    );
+    if (!result.ok) throw new Error(`could not read run: ${result.status_code} ${result.detail || ""}`);
+
+    for (const step of result.steps || []) {
+      const key = `${step.key}:${step.status}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const mark = step.status === "succeeded" ? "✓" : step.status === "failed" ? "✗" : "·";
+      process.stdout.write(`  ${mark} ${String(step.key || "").padEnd(14)} ${step.message || ""}\n`);
+    }
+
+    if (TERMINAL_STATUSES.has(String(result.status || "").toLowerCase())) {
+      const verdict = result.summary?.verdict || result.status;
+      process.stdout.write(`\nRun ${result.status}: ${verdict}\n`);
+      return result;
+    }
+    await sleep(POLL_INTERVAL_MS);
+  }
+  throw new Error("stopped watching after 15 minutes; the run is still in progress.");
+}

package/bin/changed.js

@@ -0,0 +1,175 @@
+/**
+ * Which files a push actually touches.
+ *
+ * Git hands a pre-push hook one line per ref on stdin —
+ * `<local ref> <local sha> <remote ref> <remote sha>` — which is the only
+ * authoritative statement of what is about to leave the machine. Everything
+ * else (diffing against HEAD, against a guessed upstream) is a guess that goes
+ * wrong on exactly the pushes that matter: a first push of a new branch, an
+ * amend, a force push.
+ *
+ * Reading it is best-effort by design. If stdin is absent, empty, or malformed,
+ * we fall back rather than fail, because a hook that cannot decide what changed
+ * must still let the push through.
+ */
+
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+// Git's "this ref does not exist yet" sentinel, in both SHA-1 and SHA-256 form.
+const NULL_SHAS = new Set(["0".repeat(40), "0".repeat(64)]);
+
+// A push of a brand-new branch has no remote counterpart to diff against, so
+// walking its full history could mean scanning the entire repository. Cap it.
+const NEW_BRANCH_DEPTH = 50;
+
+const CODE_EXTENSIONS = new Set([
+  ".py", ".js", ".ts", ".mjs", ".cjs", ".tsx", ".jsx", ".go", ".rb", ".java", ".php", ".cs", ".rs",
+]);
+
+const SPEC_NAMES = new Set([
+  "openapi.json", "openapi.yaml", "openapi.yml",
+  "swagger.json", "swagger.yaml", "swagger.yml",
+]);
+
+function git(cwdArgs, { cwd } = {}) {
+  const result = spawnSync("git", cwdArgs, { encoding: "utf8", cwd, maxBuffer: 32 * 1024 * 1024 });
+  if (result.status !== 0) return null;
+  return String(result.stdout || "");
+}
+
+export function repoRoot() {
+  const out = git(["rev-parse", "--show-toplevel"]);
+  return out ? out.trim() : null;
+}
+
+/** Parse git's pre-push stdin payload into the ref pairs being pushed. */
+export function parsePushRefs(raw) {
+  return String(raw || "")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const [localRef, localSha, remoteRef, remoteSha] = line.split(/\s+/);
+      return { localRef, localSha, remoteRef, remoteSha };
+    })
+    .filter((ref) => ref.localSha && !NULL_SHAS.has(ref.localSha));
+}
+
+/** Read git's stdin payload without hanging when the hook was run by hand. */
+export function readPushRefsFromStdin() {
+  // A TTY means a human typed the command, so there is no ref payload coming
+  // and a blocking read would hang the terminal.
+  if (process.stdin.isTTY) return [];
+  try {
+    return parsePushRefs(readFileSync(0, "utf8"));
+  } catch {
+    return [];
+  }
+}
+
+function diffNames(range, cwd) {
+  const out = git(["diff", "--name-only", "--diff-filter=ACMR", range], { cwd });
+  if (out === null) return null;
+  return out.split("\n").map((line) => line.trim()).filter(Boolean);
+}
+
+/**
+ * Files touched by the last `depth` commits reachable from `sha`.
+ *
+ * A new branch has no remote counterpart, and the obvious `sha~N..sha` range
+ * fails outright when the branch is younger than N commits -- which is most
+ * new branches. Walking the log bounds the work the same way without needing
+ * the ancestor to exist.
+ */
+function logNames(sha, depth, cwd) {
+  const out = git(
+    ["log", "--format=", "--name-only", "--diff-filter=ACMR", `-n${depth}`, sha],
+    { cwd }
+  );
+  if (out === null) return null;
+  return out.split("\n").map((line) => line.trim()).filter(Boolean);
+}
+
+/**
+ * The files this push introduces, relative to the repo root.
+ *
+ * Uncommitted work is deliberately excluded: a push ships commits, so testing
+ * the dirty working tree would report on code the teammate pulling this branch
+ * will never receive.
+ */
+export function changedFilesForPush(refs, { cwd } = {}) {
+  const root = cwd || repoRoot();
+  if (!root) return { files: [], reason: "not_a_git_repository" };
+
+  const names = new Set();
+  let reason = null;
+
+  for (const ref of refs) {
+    const isNewBranch = !ref.remoteSha || NULL_SHAS.has(ref.remoteSha);
+    // Never fall back to a bare `git diff <sha>`: that compares the working
+    // tree, so a clean checkout reports nothing at all and a dirty one reports
+    // edits this push does not carry.
+    let found;
+    if (isNewBranch) {
+      found = logNames(ref.localSha, NEW_BRANCH_DEPTH, root);
+      reason = "new_branch_bounded_history";
+    } else {
+      found = diffNames(`${ref.remoteSha}..${ref.localSha}`, root);
+    }
+    for (const name of found ?? []) names.add(name);
+  }
+
+  if (!refs.length) {
+    // Run by hand rather than by git: compare against the tracked upstream.
+    const upstream = git(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"], { cwd: root });
+    const fallback = upstream ? diffNames(`${upstream.trim()}..HEAD`, root) : null;
+    for (const name of fallback ?? []) names.add(name);
+    reason = upstream ? "upstream_diff" : "no_refs_no_upstream";
+  }
+
+  return { files: [...names], reason, root };
+}
+
+/** Only files a scanner could find an endpoint in. */
+export function isScannable(relPath) {
+  const base = path.basename(relPath).toLowerCase();
+  if (SPEC_NAMES.has(base)) return true;
+  return CODE_EXTENSIONS.has(path.extname(relPath).toLowerCase());
+}
+
+/**
+ * Read the pushed files' contents for the backend to scan.
+ *
+ * Reads from the working tree rather than the commit. They agree on the
+ * overwhelmingly common push-what-you-committed path, and when they disagree
+ * the working tree is what the developer's running dev server is serving —
+ * which is what the plan is about to be tested against.
+ */
+export function readChangedFiles(files, { root, maxFiles = 300, maxBytes = 512 * 1024 } = {}) {
+  const out = [];
+  let skipped = 0;
+
+  for (const rel of files) {
+    if (out.length >= maxFiles) {
+      skipped += 1;
+      continue;
+    }
+    if (!isScannable(rel)) continue;
+    try {
+      const content = readFileSync(path.join(root, rel), "utf8");
+      if (Buffer.byteLength(content, "utf8") > maxBytes) {
+        skipped += 1;
+        continue;
+      }
+      out.push({ path: rel, content });
+    } catch {
+      // Deleted in the working tree, or unreadable. Either way there is nothing
+      // to scan, and the diff still reports the endpoint as removed.
+      skipped += 1;
+    }
+  }
+
+  return { files: out, skipped };
+}

package/bin/cli.js

@@ -17,7 +17,13 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { ENDPOINTS_HELP, TEST_HELP, endpointsCommand, testCommand } from "./api_tools.js";
-import { CONNECT_HELP, connectCommand, writeCursorConfig } from "./connect.js";
+import {
+  CONNECT_HELP,
+  DISPATCH_HELP,
+  connectCommand,
+  dispatchCommand,
+  writeCursorConfig,
+} from "./connect.js";
 import {
   INTEGRATIONS_HELP,
   awsCommand,
@@ -26,6 +32,11 @@ import {
   slackCommand,
 } from "./integrations.js";
 import { HOSTED_HELP, linkCommand, runCommand, toolsCommand } from "./hosted.js";
+import { STATUS_HELP, statusCommand } from "./status.js";
+import { HOOK_HELP, hookCommand } from "./hook.js";
+import { VERIFY_HELP, verifyCommand } from "./verify.js";
+import { DESKTOP_HELP, installDesktopCommand } from "./desktop.js";
+import { ACCOUNT_HELP, doctorCommand, loginBrowser, logoutCommand, watchCommand } from "./account.js";
 import {
   CREDENTIALS_FILE,
   cliInvocation,
@@ -66,10 +77,18 @@ function printHelp() {
   // for a global install and 38 for npm exec, so a fixed layout is wrong for
   // one of them.
   const usage = [
+    ["status", "Healthy / failing / recently fixed endpoints"],
+    ["verify [options]", "Test endpoints against your local app"],
+    ["hook install|uninstall|status", "Manage the git pre-push hook"],
+    ["doctor", "Diagnose credentials, backend, target, integrations"],
+    ["install-desktop", "Download and install the PreMan desktop app"],
     ["onboard", "Sign in, then connect agent, GitHub, AWS, Slack"],
     ["connect [options]", "Pick a coding agent and connect it"],
+    ["dispatch [options]", "Let PreMan start agent runs for you"],
     ["aws | github | slack", "Connect one integration on its own"],
-    ["login", "Create/login to PreMan from the terminal"],
+    ["login [--browser]", "Create/login to PreMan from the terminal"],
+    ["logout", "Delete stored CLI credentials"],
+    ["watch <run> <integration>", "Follow a push simulation live"],
     ["install [options]", "Install PreMan into Cursor MCP config"],
     ["", "Start the PreMan MCP server"],
     ["link|tools|run ...", "Drive a published hosted MCP"],
@@ -85,7 +104,7 @@ function printHelp() {
 
 Usage:
 ${usageLines}
-${INTEGRATIONS_HELP}${CONNECT_HELP}${ENDPOINTS_HELP}${TEST_HELP}
+${INTEGRATIONS_HELP}${CONNECT_HELP}${DISPATCH_HELP}${STATUS_HELP}${VERIFY_HELP}${HOOK_HELP}${ACCOUNT_HELP}${DESKTOP_HELP}${ENDPOINTS_HELP}${TEST_HELP}
 Login options:
   --email <email>       Pre-fill the email prompt
   --backend <url>       PreMan backend URL. Defaults to ${DEFAULT_BACKEND}
@@ -109,6 +128,10 @@ ${HOSTED_HELP}`);
 }
 
 async function loginCommand() {
+  if (hasFlag("--browser")) {
+    await loginBrowser(cliArgs);
+    return;
+  }
   const creds = await authenticateTerminal(cliArgs);
   process.stdout.write(`PreMan account ready.
 
@@ -192,8 +215,24 @@ function startServer() {
 async function main() {
   if (command === "login") {
     await loginCommand();
+  } else if (command === "status") {
+    await statusCommand(commandArgs);
+  } else if (command === "verify") {
+    await verifyCommand(commandArgs);
+  } else if (command === "hook") {
+    await hookCommand(commandArgs);
+  } else if (command === "logout") {
+    await logoutCommand();
+  } else if (command === "doctor") {
+    await doctorCommand(commandArgs);
+  } else if (command === "watch") {
+    await watchCommand(commandArgs);
+  } else if (command === "install-desktop") {
+    await installDesktopCommand(commandArgs);
   } else if (command === "connect") {
     await connectCommand(commandArgs);
+  } else if (command === "dispatch") {
+    await dispatchCommand(commandArgs);
   } else if (command === "onboard" || command === "setup") {
     // makeArgs/authenticateTerminal/connectCommand are injected rather than
     // imported there, so integrations.js stays free of a cycle back into the CLI.