mergen-server 1.4.0

package/dist/cli.js

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+import { error, VERSION } from "./commands/shared.js";
+import { loginCommand, setupCommand, testCommand, ciCommand, startCommand, doctorCommand, quickstartCommand } from "./commands/setup.js";
+import { postmortemCommand, timelineCommand, watchCommand, explainCommand, statusCommand, resolvedCommand, replayCommand } from "./commands/incident.js";
+import { approveCommand, shadowReportCommand, allowCommand, verifyLogCommand, guardCommand, policyPushCommand, policyPullCommand, policyDiffCommand, testSafetyCommand, policySimulateCommand, policyTestCommand, policyVersionsCommand, policyRollbackCommand, traceReplayCommand } from "./commands/policy.js";
+import { prCommand, prShadowCommand, feedbackCommand, backfillCommand, connectCommand } from "./commands/github.js";
+import { inviteCommand, joinCommand, impactReportCommand, exportCommand, initCommand, demoCommand, exportRiskReportCommand, partnerShortlistCommand, execCommand } from "./commands/team.js";
+import { agentRegisterCommand, agentListCommand } from "./commands/agent-identity.js";
+import { gateCheckCommand } from "./commands/gate.js";
+import { scanCommand } from "./commands/scan.js";
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+  switch (command) {
+    case "init":
+      await initCommand();
+      break;
+    case "resolved":
+      await resolvedCommand(args.slice(1));
+      break;
+    case "demo":
+      await demoCommand();
+      break;
+    case "pr":
+      await prCommand(args.slice(1));
+      break;
+    case "connect":
+      await connectCommand(args.slice(1));
+      break;
+    case "backfill":
+      await backfillCommand(args.slice(1));
+      break;
+    case "feedback":
+      await feedbackCommand(args.slice(1));
+      break;
+    case "pr-shadow":
+      await prShadowCommand();
+      break;
+    case "approve":
+      await approveCommand(args.slice(1));
+      break;
+    case "shadow-report":
+      await shadowReportCommand();
+      break;
+    case "allow":
+      await allowCommand(args.slice(1));
+      break;
+    case "impact-report":
+      await impactReportCommand(args.slice(1));
+      break;
+    case "setup":
+      await setupCommand();
+      break;
+    case "login":
+      await loginCommand();
+      break;
+    case "test":
+      await testCommand();
+      break;
+    case "start":
+      await startCommand();
+      break;
+    case "ci":
+      await ciCommand();
+      break;
+    case "invite":
+      await inviteCommand();
+      break;
+    case "join":
+      await joinCommand(args);
+      break;
+    case "postmortem":
+      await postmortemCommand(args);
+      break;
+    case "timeline":
+      await timelineCommand(args);
+      break;
+    case "watch":
+      await watchCommand(args);
+      break;
+    case "explain":
+      await explainCommand(args.slice(1));
+      break;
+    case "quickstart":
+      await quickstartCommand();
+      break;
+    case "status":
+      await statusCommand();
+      break;
+    case "doctor":
+      await doctorCommand();
+      break;
+    case "export":
+      await exportCommand(args);
+      break;
+    case "export-risk-report":
+      await exportRiskReportCommand(args.slice(1));
+      break;
+    case "partner-shortlist":
+      await partnerShortlistCommand(args.slice(1));
+      break;
+    case "exec":
+      await execCommand(args.slice(1));
+      break;
+    case "test-safety":
+      await testSafetyCommand();
+      break;
+    case "policy-push":
+      await policyPushCommand();
+      break;
+    case "policy-pull":
+      await policyPullCommand(args.slice(1));
+      break;
+    case "policy-diff":
+      await policyDiffCommand();
+      break;
+    case "policy-simulate":
+      await policySimulateCommand(args.slice(1));
+      break;
+    case "policy-test":
+      await policyTestCommand(args.slice(1));
+      break;
+    case "policy-versions":
+      await policyVersionsCommand();
+      break;
+    case "policy-rollback":
+      await policyRollbackCommand(args.slice(1));
+      break;
+    case "trace-replay":
+      await traceReplayCommand(args.slice(1));
+      break;
+    case "verify-log":
+      await verifyLogCommand();
+      break;
+    case "guard":
+      await guardCommand(args);
+      break;
+    case "replay":
+      await replayCommand(args.slice(1));
+      break;
+    case "agent-register":
+      await agentRegisterCommand(args.slice(1));
+      break;
+    case "agent-list":
+      await agentListCommand();
+      break;
+    case "gate-check":
+      await gateCheckCommand(args.slice(1));
+      break;
+    case "scan":
+      await scanCommand(args.slice(1));
+      break;
+    case "version":
+    case "--version":
+    case "-v":
+      console.log(`mergen-server v${VERSION}`);
+      break;
+    case void 0:
+      await demoCommand();
+      break;
+    case "help":
+    case "--help":
+    case "-h":
+      console.log(`
+Mergen \u2014 production incident intelligence
+
+Usage:
+  mergen-server                    Zero-config demo \u2014 loads 50 sample incidents instantly
+  mergen-server start              Start server (production mode)
+  mergen-server login              Authenticate Mergen CLI (automatic browser & manual fallback)
+  mergen-server login --key <key>  Directly authenticate using a license key
+  mergen-server approve <id>       Temporarily bypass a blocked command block (10 min)
+  mergen-server setup              Quick setup: Node check \u2192 IDE \u2192 login \u2192 start (no questions)
+  mergen-server setup --full       Full wizard: also connects Slack, PagerDuty, GitHub, git hooks
+  mergen-server setup --yes        Non-interactive full setup (skip all prompts, use defaults)
+  mergen-server setup --ide cursor Configure a specific IDE (cursor|vscode|claude-code|windsurf)
+  mergen-server demo               Same as no args \u2014 demo with sample incidents
+  mergen-server status             Live snapshot: server health, buffer, errors, MCP activity
+  mergen-server doctor             Full health-check: env vars, IDE config, integrations
+  mergen-server connect github     Auto-register GitHub webhook \u2192 populates intent archive
+  mergen-server backfill github    Import historical PRs \u2192 enables explain_why on day 1
+  mergen-server init               Connect Datadog (guided setup)
+  mergen-server pr                 Generate a PR description from your debug session
+  mergen-server pr --copy          Same, but copies to clipboard
+  mergen-server quickstart         Guided wizard \u2014 from zero to first real insight in 2 min
+  mergen-server watch <cmd>        Stream any process into Mergen (auto-starts server if needed)
+  mergen-server explain [file]     Analyze a log file or piped input \u2014 no server required
+  mergen-server invite             Generate a team invite URL
+  mergen-server join <url>         Join a team Mergen instance
+  mergen-server postmortem [h]     Generate a postmortem document (default: last 1 hour)
+  mergen-server timeline [seconds] Unified causal timeline
+  mergen-server export [label]     Export session as JSON + HTML report
+  mergen-server export-risk-report Print CISO security risk report
+  mergen-server export-risk-report --markdown  Save as shareable Markdown file
+  mergen-server exec -- <cmd>      Run a command through the full Mergen gate (policy, HITL, blast radius), then execute
+  mergen-server exec --allow-offline -- <cmd>  Same, but degrade to a local-only check if mergen-server isn't running
+  mergen-server gate-check -- <cmd>  Evaluate only, no execution (exit 0=pass 1=blocked). Used by the Claude Code PreToolUse hook
+  mergen-server impact-report      Print the 5 pre-agreed Day-30 metrics
+  mergen-server impact-report --slide     Screenshot-ready 5-number card
+  mergen-server impact-report --baseline  Save Day-1 numbers (compare at Day 30)
+  mergen-server impact-report --compare   Show delta vs. saved baseline
+  mergen-server impact-report --html      Write full HTML report to disk
+  mergen-server partner-shortlist  Print design-partner filter criteria and commands
+  mergen-server partner-shortlist --add <name> <company> [role] [reach] [notes]
+  mergen-server partner-shortlist --list  Show saved candidates
+  mergen-server test-safety        Run adversarial bypass test suite against the gate
+  mergen-server scan <url>         Scan an MCP server for injection vectors and risk signals
+  mergen-server scan <url> --json  Machine-readable JSON output (exits 1 if CRITICAL found)
+  mergen-server policy-push        Save live server policy \u2192 .mergen/policy.json (for git)
+  mergen-server policy-pull        Apply .mergen/policy.json \u2192 live server
+  mergen-server policy-pull --merge  Merge (add new rules only, keep existing)
+  mergen-server policy-diff        Show diff between .mergen/policy.json and live server
+  mergen-server policy-simulate <file> [--window-days=N]  Replay a candidate policy file against
+                                   historical traffic \u2014 blocks/holds/passes, agents & services affected
+  mergen-server policy-test [file.json]  Run {input,expectedVerdict} test cases against the live
+                                   policy \u2014 no server required, CI-usable. Defaults to a built-in 8-case suite.
+  mergen-server policy-versions    List restorable full-policy snapshots (one per policy save)
+  mergen-server policy-rollback <versionId>  Restore policy to a prior snapshot (immutable rules always survive)
+  mergen-server trace-replay <traceId>  Reconstruct the full gate-event + blunder-log timeline for one cross-process trace
+  mergen-server replay <dir>       Score historical incidents against the detector pipeline
+  mergen-server agent-register <id>  Issue a signed identity token for an agent profile (see agent-profiles API)
+  mergen-server agent-list         List issued agent identity tokens on this machine
+  mergen-server verify-log         Verify Agent Blunder Log hash chain (tamper-evident audit)
+  mergen-server guard              Pre-commit runtime check (includes incident history for staged services)
+  mergen-server guard --install    Install as git pre-commit hook
+  mergen-server test               Validate installation
+  mergen-server ci                 CI smoke test (exit 0 = healthy)
+  mergen-server --version          Show version
+
+Examples:
+  npx mergen-server                # instant demo \u2014 no config needed
+  mergen-server setup --yes        # non-interactive setup in CI
+  mergen-server setup --ide cursor --skip-github
+  mergen-server start &            # production server in background
+  mergen-server connect github --repo acme/api
+  mergen-server watch npm start
+
+Documentation: https://github.com/omertt27/Mergen
+      `);
+      break;
+    default:
+      error(`Unknown command: ${command}`);
+      console.log("Run: mergen-server --help");
+      process.exit(1);
+  }
+}
+main().catch((err) => {
+  error(err.message);
+  process.exit(1);
+});

package/dist/commands/agent-identity.js

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { log, error, success, hr } from "./shared.js";
+function readLocalSecret() {
+  const secretPath = process.env.MERGEN_AGENT_TOKEN_SECRET ? "" : join(homedir(), ".mergen", "secret");
+  if (process.env.MERGEN_AGENT_TOKEN_SECRET) return process.env.MERGEN_AGENT_TOKEN_SECRET;
+  if (secretPath && existsSync(secretPath)) {
+    try {
+      return readFileSync(secretPath, "utf8").trim();
+    } catch {
+    }
+  }
+  return "";
+}
+async function agentRegisterCommand(args) {
+  const profileId = args.find((a) => !a.startsWith("--"));
+  const parentFlag = args.find((a) => a.startsWith("--parent="));
+  const parentAgentId = parentFlag ? parentFlag.split("=")[1] : void 0;
+  const userFlag = args.find((a) => a.startsWith("--user="));
+  const userId = (userFlag ? userFlag.split("=")[1] : void 0) || process.env.MERGEN_USER_ID || void 0;
+  if (!profileId) {
+    error("Usage: mergen-server agent-register <profile-id> [--parent=<parentAgentId>] [--user=<email>]");
+    console.log("  Issues a signed MERGEN_AGENT_TOKEN for the given agent-profile id.");
+    console.log("  Register the profile first with the agent-profiles API (POST /agent-profiles), then run this.");
+    console.log("  --parent=<id>  Mints this as a sub-agent token, recording lineage (which agent spawned it)");
+    console.log("                 in the blunder log and replay view \u2014 use when a coordinating/planner agent");
+    console.log("                 spawns this one.");
+    console.log("  --user=<email> Binds the human principal this agent acts on behalf of into the signed token");
+    console.log("                 (Layer 3 SSO attribution). Falls back to MERGEN_USER_ID. Flows onto every");
+    console.log('                 action-ledger row as user_id \u2014 "which human is this agent acting for."');
+    process.exit(1);
+  }
+  const secret = readLocalSecret();
+  if (!secret) {
+    error("No signing secret found \u2014 start mergen-server at least once to generate ~/.mergen/secret, or set MERGEN_AGENT_TOKEN_SECRET.");
+    process.exit(1);
+  }
+  const { setAgentTokenSecret, issueToken } = await import("../intelligence/agent-identity.js");
+  setAgentTokenSecret(secret);
+  const token = issueToken(profileId, void 0, parentAgentId, userId);
+  hr();
+  success(`Issued agent identity token for profile "${profileId}"${userId ? ` (on behalf of ${userId})` : ""}`);
+  console.log("");
+  console.log("  Add this to the MCP server env block for the agent that should carry this identity:");
+  console.log("");
+  console.log(`    MERGEN_AGENT_TOKEN=${token}`);
+  console.log("");
+  console.log('  For Cursor/VSCode/Windsurf, add it to the "env" object in your mcp.json mergen entry.');
+  console.log("  For Claude Code: claude mcp add mergen --env MERGEN_AGENT_TOKEN=<token> --transport stdio -- node <server-path>");
+  console.log("");
+  console.log("  This token is long-lived (1 year) and is NOT stored server-side beyond a local record for");
+  console.log("  operator visibility (mergen-server agent-list) \u2014 verification is stateless. Re-run this");
+  console.log("  command to issue a fresh token; the old one keeps working until it expires (no revocation list yet).");
+  hr();
+}
+async function agentListCommand() {
+  const { listIssuedTokenRecords } = await import("../intelligence/agent-identity.js");
+  const records = listIssuedTokenRecords();
+  if (records.length === 0) {
+    log("No agent identity tokens have been issued on this machine. Run: mergen-server agent-register <profile-id>");
+    return;
+  }
+  hr();
+  console.log("Issued agent identity tokens:\n");
+  for (const r of records) {
+    const expired = Date.now() > r.expiresAt ? " (EXPIRED)" : "";
+    console.log(`  ${r.agentId}`);
+    console.log(`    issued:  ${new Date(r.issuedAt).toISOString()}`);
+    console.log(`    expires: ${new Date(r.expiresAt).toISOString()}${expired}`);
+    if (r.userId) console.log(`    on behalf of: ${r.userId}`);
+    console.log("");
+  }
+  hr();
+}
+export {
+  agentListCommand,
+  agentRegisterCommand
+};

package/dist/commands/gate.js

@@ -0,0 +1,107 @@
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { error, hr } from "./shared.js";
+import { findPort } from "./shared.js";
+function readLocalSecret() {
+  const secretPath = join(homedir(), ".mergen", "secret");
+  if (existsSync(secretPath)) {
+    try {
+      return readFileSync(secretPath, "utf8").trim();
+    } catch {
+    }
+  }
+  return "";
+}
+async function evaluateViaGate(command, toolName) {
+  const port = await findPort();
+  if (!port) return { reachable: false };
+  const secret = readLocalSecret();
+  const headers = { "Content-Type": "application/json" };
+  if (secret) headers["x-mergen-secret"] = secret;
+  const resp = await fetch(`http://127.0.0.1:${port}/gate/evaluate`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ command, toolName }),
+    signal: AbortSignal.timeout(5 * 6e4)
+    // generous — a HOLD suspends until a human approves/denies
+  });
+  if (!resp.ok) {
+    throw new Error(`gate evaluation request failed: HTTP ${resp.status}`);
+  }
+  const body = await resp.json();
+  return { reachable: true, isError: body.isError, text: body.text };
+}
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = "";
+    if (process.stdin.isTTY) {
+      resolve("");
+      return;
+    }
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on("end", () => resolve(data));
+    process.stdin.on("error", () => resolve(data));
+  });
+}
+function extractCommandFromHookPayload(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const obj = parsed;
+  const toolInput = obj.tool_input;
+  const candidate = toolInput?.command ?? toolInput?.cmd ?? obj.command ?? obj.cmd;
+  return typeof candidate === "string" && candidate.length > 0 ? candidate : null;
+}
+async function gateCheckCommand(args) {
+  const dashDash = args.indexOf("--");
+  const cmdParts = dashDash >= 0 ? args.slice(dashDash + 1) : args;
+  let fullCommand;
+  if (cmdParts.length > 0) {
+    fullCommand = cmdParts.join(" ");
+  } else {
+    const raw = await readStdin();
+    const extracted = raw ? extractCommandFromHookPayload(raw) : null;
+    if (!extracted) {
+      error("gate-check: no command given (pass -- <command>, or a Claude Code hook JSON payload on stdin) \u2014 failing closed.");
+      process.exit(1);
+      return;
+    }
+    fullCommand = extracted;
+  }
+  let evaluation;
+  try {
+    evaluation = await evaluateViaGate(fullCommand);
+  } catch (err) {
+    error(`gate-check: could not reach mergen-server \u2014 ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+    return;
+  }
+  if (!evaluation.reachable) {
+    hr();
+    error("gate-check: no mergen-server is running \u2014 refusing to allow (fail closed).");
+    console.error("  Start it with: mergen-server start");
+    hr();
+    process.exit(1);
+  }
+  if (evaluation.isError) {
+    hr();
+    console.error("\u2B21 Mergen \u2014 BLOCKED\n");
+    console.error(evaluation.text);
+    hr();
+    process.exit(1);
+  }
+  process.exit(0);
+}
+export {
+  evaluateViaGate,
+  extractCommandFromHookPayload,
+  gateCheckCommand
+};