perimetercli 0.1.0

package/src/cli.js

@@ -0,0 +1,469 @@
+import path from "node:path";
+import fs from "node:fs";
+import {
+  log,
+  info,
+  success,
+  warn,
+  error,
+  green,
+  cyan,
+  yellow,
+  red,
+  bold,
+  dim,
+} from "./util.js";
+import { VERSION } from "./version.js";
+import { runAudit, writeBaseline, makeBaseline, policyPath, DEFAULT_POLICY } from "./audit.js";
+import { discover } from "./discover.js";
+import { buildSessionReport } from "./sessions.js";
+import { resolveModel } from "./tokens.js";
+import { createStaticServer, listen } from "./serve.js";
+import { runGuardCli, defaultPolicy } from "./guard.js";
+import { createServer as createPerimeterServer, listen as listenPerimeter } from "./server.js";
+import { SEVERITY_RANK } from "./rules.js";
+import {
+  formatText,
+  formatJson,
+  formatMarkdown,
+  formatSarif,
+  formatHtml,
+  formatSessionText,
+  formatSessionJson,
+} from "./report.js";
+
+function parseArgs(argv) {
+  const BOOLEAN_FLAGS = new Set([
+    "json",
+    "md",
+    "sarif",
+    "html",
+    "enforce",
+    "recursive",
+    "debug",
+    "silent",
+    "home",
+    "no-home",
+    "baseline",
+    "no-baseline",
+    "help",
+    "version",
+  ]);
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith("--")) {
+      const eq = arg.indexOf("=");
+      let name, value;
+      if (eq !== -1) {
+        name = arg.slice(2, eq);
+        value = arg.slice(eq + 1);
+      } else {
+        name = arg.slice(2);
+        if (BOOLEAN_FLAGS.has(name)) {
+          const camel = name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+          flags[camel] = true;
+          continue;
+        }
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith("--")) {
+          value = next;
+          i++;
+        } else {
+          const camel = name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+          flags[camel] = true;
+          continue;
+        }
+      }
+      const camel = name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+      flags[camel] = value;
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { flags, positional };
+}
+
+function printVersion() {
+  log(VERSION);
+}
+
+function printHelp() {
+  log(`perimeter ${VERSION}
+
+${bold("Usage")}
+  perimeter <command> [path] [options]
+
+${bold("Commands")}
+  audit        Scan agent/MCP configs for risk, cost and drift
+  baseline     Record a signature baseline for drift detection
+  list         List detected servers, tools and capabilities
+  init         Write a .perimeter/config.json policy
+  cost         Show the token/cost footprint only
+  session      Observe what agents actually ran (session logs)
+  serve        Serve a generated report locally
+  guard        Proxy an MCP server with a runtime policy gate
+  server       Run a self-hosted audit dashboard (Pro)
+  push         Push an audit JSON to a Perimeter server
+  version      Print the version
+  help         Show this help
+
+${bold("Audit options")}
+  --json              Print machine-readable JSON
+  --md                Print a Markdown report
+  --sarif             Print SARIF (for GitHub code scanning)
+  --html              Print an HTML report
+  --out <dir>         Write all report formats to a directory
+  --enforce           Exit non-zero if verdict >= fail-on
+  --fail-on <sev>     Fail threshold (default: critical)
+  --model <model>     Model for cost estimation
+  --budget <amt>      Daily spend budget in dollars
+  --no-baseline       Skip drift comparison
+  --no-home           Do not scan home-directory configs
+  --recursive         Also scan nested .mcp.json files
+
+${bold("Examples")}
+  perimeter audit
+  perimeter audit --enforce --fail-on high
+  perimeter audit --json | jq '.verdict'
+  perimeter baseline
+  perimeter init
+`);
+}
+
+function resolveDir(flags) {
+  const dir = path.resolve(flags._dir || process.cwd());
+  if (!fs.existsSync(dir)) {
+    throw new Error(`Directory not found: ${dir}`);
+  }
+  return dir;
+}
+
+async function cmdAudit(flags) {
+  const cwd = resolveDir(flags);
+  const audit = await runAudit({
+    cwd,
+    model: flags.model,
+    budget: flags.budget !== undefined && flags.budget !== true ? Number(flags.budget) : undefined,
+    failOn: flags.failOn,
+    maxTokensPerServer: flags.maxTokens,
+    useBaseline: flags.baseline !== false && flags.noBaseline !== true,
+    home: effectiveHome(flags),
+    recursive: flags.recursive === true,
+  });
+
+  const wantOut = flags.out ? path.resolve(flags.out) : null;
+
+  if (wantOut) {
+    fs.mkdirSync(wantOut, { recursive: true });
+    const files = {
+      "audit.txt": formatText(audit),
+      "audit.json": formatJson(audit),
+      "audit.md": formatMarkdown(audit),
+      "audit.sarif": formatSarif(audit),
+      "index.html": formatHtml(audit),
+    };
+    for (const [name, content] of Object.entries(files)) {
+      fs.writeFileSync(path.join(wantOut, name), content);
+    }
+    success(`Reports written to ${cyan(wantOut)}`);
+    log(textHeader(audit));
+  } else if (flags.json) {
+    log(formatJson(audit));
+  } else if (flags.md) {
+    log(formatMarkdown(audit));
+  } else if (flags.sarif) {
+    log(formatSarif(audit));
+  } else if (flags.html) {
+    log(formatHtml(audit));
+  } else {
+    log(formatText(audit));
+  }
+
+  if (flags.enforce) {
+    const threshold = flags.failOn || audit.config.failOn || DEFAULT_POLICY.failOn;
+    const thresholdRank = SEVERITY_RANK[threshold] ?? 4;
+    const verdictRank = SEVERITY_RANK[audit.effectiveVerdict] ?? 1;
+    const budgetFail = Boolean(audit.costs && audit.costs.overBudget);
+    if (verdictRank >= thresholdRank || budgetFail) {
+      log(
+        `${red("✗")} Failed — verdict ${audit.effectiveVerdict}${
+          verdictRank >= thresholdRank ? ` >= threshold ${threshold}` : ""
+        }${budgetFail ? ` · single load over daily budget` : ""}`
+      );
+      process.exitCode = 1;
+    } else {
+      log(`${green("✓")} Passed — verdict ${audit.effectiveVerdict} < threshold ${threshold}`);
+    }
+  }
+}
+
+async function cmdBaseline(flags) {
+  const cwd = resolveDir(flags);
+  const { servers, hooks } = discover(cwd, {
+    recursive: flags.recursive === true,
+    home: effectiveHome(flags),
+  });
+  writeBaseline(cwd, [...servers, ...hooks]);
+  success(
+    `Baseline written to ${cyan(policyBaseline(cwd))} (${servers.length} servers, ${hooks.length} hooks)`
+  );
+}
+
+async function cmdList(flags) {
+  const cwd = resolveDir(flags);
+  const { servers, hooks, contextFiles, errors, files } = discover(cwd, {
+    recursive: flags.recursive === true,
+    home: effectiveHome(flags),
+  });
+  if (servers.length === 0 && hooks.length === 0) {
+    log("No MCP servers or agent tooling found.");
+  } else {
+    log(
+      `${green("Detected")} ${servers.length} server${servers.length === 1 ? "" : "s"}, ${hooks.length} hook${hooks.length === 1 ? "" : "s"}`
+    );
+    for (const s of servers) {
+      const caps = s.catalog ? s.catalog.capabilities.join(", ") : "(unverified)";
+      log(
+        `  ${cyan(s.displayName)}  ${dim(s.source)}  ${s.transport}  ${dim(caps)}`
+      );
+    }
+    for (const h of hooks) {
+      log(`  ${cyan(h.displayName)}  ${dim(h.source)}  ${yellow("code-exec")}`);
+    }
+  }
+  if (contextFiles.length) {
+    log(`\n${dim(`${contextFiles.length} context/instruction file(s):`)}`);
+    for (const c of contextFiles) log(`  ${dim(c.label)}`);
+  }
+  if (flags.json) {
+    log("\n" + JSON.stringify({ servers, hooks, contextFiles, errors }, null, 2));
+  }
+}
+
+async function cmdInit(flags) {
+  const cwd = resolveDir(flags);
+  const target = policyPath(cwd);
+  if (fs.existsSync(target)) {
+    warn(`${policyPath(cwd)} already exists — leaving it unchanged`);
+    return;
+  }
+  const config = {
+    name: "agent-toolchain",
+    ...DEFAULT_POLICY,
+    model: "claude-sonnet",
+    block: ["@modelcontextprotocol/server-everything"],
+    ignoredRules: [],
+  };
+  fs.writeFileSync(target, JSON.stringify(config, null, 2) + "\n");
+  success(`Wrote ${cyan(target)}`);
+  info(dim("Set failOn, model, budget, and server allow/block lists to match your policy."));
+}
+
+async function cmdCost(flags) {
+  const cwd = resolveDir(flags);
+  const model = resolveModel(flags.model || DEFAULT_POLICY.model);
+  const audit = await runAudit({
+    cwd,
+    model: model.name,
+    budget: flags.budget !== undefined && flags.budget !== true ? Number(flags.budget) : undefined,
+    useBaseline: false,
+  });
+  const rows = audit.servers
+    .sort((a, b) => b.estimatedTokens - a.estimatedTokens)
+    .map(
+      (s) =>
+        `${s.displayName.padEnd(20)} ${String(s.estimatedTokens).padStart(8)} tokens  ${dim(`(${s.capabilities.length} caps)`)}`
+    )
+    .join("\n");
+  log(`Cost footprint — model ${cyan(model.name)}${audit.costs.estimated ? " (estimated)" : ""}`);
+  log(`\n${rows}`);
+  log("");
+  log(`~${audit.costs.totalTokens.toLocaleString()} tokens per load`);
+  log(
+    `${audit.costs.perLoadCost ? green("~$" + audit.costs.perLoadCost.toFixed(2)) : "—"} per load`
+  );
+  if (audit.costs.budget) {
+    log(
+      `budget ${audit.costs.budget}/day → ${audit.costs.loadsPerDayWithinBudget ?? 0} loads/day`
+    );
+  }
+}
+
+async function cmdSession(flags) {
+  const cwd = resolveDir(flags);
+  const report = buildSessionReport(cwd, {
+    model: flags.model || DEFAULT_POLICY.model,
+    sessions: flags.sessions,
+    home: effectiveHome(flags),
+  });
+  if (flags.json) log(formatSessionJson(report));
+  else log(formatSessionText(report));
+}
+
+async function cmdServe(flags) {
+  const cwd = resolveDir(flags);
+  const dir =
+    flags.dir && flags.dir !== true
+      ? path.resolve(flags.dir)
+      : fs.existsSync(path.join(cwd, ".perimeter", "report"))
+        ? path.join(cwd, ".perimeter", "report")
+        : cwd;
+  const port = Number(flags.port || 4173);
+  const host = flags.host || "127.0.0.1";
+  const { server } = createStaticServer(dir, { host, port });
+  await listen(server, { host, port });
+  const addr = server.address();
+  const shown = typeof addr === "object" && addr ? addr.port : port;
+  log(`${green("Serving")} ${cyan(dir)} at ${cyan(`http://${host}:${shown}`)}`);
+  log(dim("Press Ctrl+C to stop."));
+}
+
+async function cmdGuard(flags) {
+  if (!flags.server) {
+    error("guard requires --server \"<command>\"");
+    process.exitCode = 1;
+    return;
+  }
+  const policy = { ...defaultPolicy() };
+  if (flags.policy && flags.policy !== true) {
+    const filePolicy = JSON.parse(fs.readFileSync(flags.policy, "utf8"));
+    Object.assign(policy, filePolicy);
+  }
+  if (flags.allow) policy.allowTools = splitList(flags.allow);
+  if (flags.deny) policy.denyTools = splitList(flags.deny);
+  if (flags.denyCapabilities) {
+    policy.denyCapabilities = splitList(flags.denyCapabilities);
+  }
+  if (flags.allowCapabilities) {
+    policy.allowCapabilities = splitList(flags.allowCapabilities);
+  }
+  if (flags.log) policy.log = flags.log;
+  runGuardCli({ command: flags.server, policy });
+}
+
+async function cmdServer(flags) {
+  const cwd = resolveDir(flags);
+  const port = Number(flags.port || 4173);
+  const host = flags.host || "127.0.0.1";
+  const dataDir = flags.data && flags.data !== true ? path.resolve(flags.data) : path.join(cwd, ".perimeter", "data");
+  const { server } = createPerimeterServer({ dataDir, host, port });
+  await listenPerimeter(server, { host, port });
+  const addr = server.address();
+  const shown = typeof addr === "object" && addr ? addr.port : port;
+  log(`${green("Perimeter server")} listening at ${cyan(`http://${host}:${shown}`)}`);
+  log(dim("Press Ctrl+C to stop."));
+}
+
+async function cmdPush(flags) {
+  const url = flags._dir || flags._url;
+  if (!url) {
+    error("push requires <url> e.g. perimeter push http://localhost:4173 --project acme");
+    process.exitCode = 1;
+    return;
+  }
+  const project = flags.project || "project";
+  let body;
+  if (flags.file && flags.file !== true) {
+    body = fs.readFileSync(flags.file, "utf8");
+  } else {
+    body = await readStdin();
+  }
+  try {
+    const target = url.replace(/\/$/, "") + "/audit?project=" + encodeURIComponent(project);
+    const res = await fetch(target, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body,
+    });
+    const data = await res.json();
+    if (data.ok) success(`Pushed audit for ${cyan(project)} to ${cyan(target)}`);
+    else error(data.error || "push failed");
+  } catch (err) {
+    error(`Could not reach ${url} — ${err.message}`);
+    process.exitCode = 1;
+  }
+}
+
+function splitList(value) {
+  return String(value)
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function effectiveHome(flags) {
+  if (flags.noHome === true) return false;
+  return flags.home === true;
+}
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (c) => (data += c));
+    process.stdin.on("end", () => resolve(data));
+    process.stdin.on("error", reject);
+  });
+}
+
+function textHeader(audit) {
+  return dim(`${audit.servers.length} servers · verdict ${audit.effectiveVerdict}`);
+}
+
+function policyBaseline(cwd) {
+  return path.join(cwd, ".perimeter", "baseline.json");
+}
+
+export async function main(argv) {
+  const { flags, positional } = parseArgs(argv);
+  if (flags.debug) process.env.PERIMETER_DEBUG = "1";
+  const command = positional[0] || "help";
+  flags._dir = positional[1];
+  try {
+    switch (command) {
+      case "audit":
+        await cmdAudit(flags);
+        break;
+      case "baseline":
+        await cmdBaseline(flags);
+        break;
+      case "list":
+        await cmdList(flags);
+        break;
+      case "init":
+        await cmdInit(flags);
+        break;
+      case "cost":
+        await cmdCost(flags);
+        break;
+      case "session":
+        await cmdSession(flags);
+        break;
+      case "serve":
+        await cmdServe(flags);
+        break;
+      case "guard":
+        await cmdGuard(flags);
+        break;
+      case "server":
+        await cmdServer(flags);
+        break;
+      case "push":
+        await cmdPush(flags);
+        break;
+      case "version":
+      case "--version":
+      case "-v":
+        printVersion();
+        break;
+      default:
+        printHelp();
+    }
+  } catch (err) {
+    error(err.message || String(err));
+    if (process.env.PERIMETER_DEBUG) console.error(err);
+    process.exitCode = 1;
+  }
+}