perimetercli 0.1.0

package/src/discover.js

@@ -0,0 +1,262 @@
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs";
+import { readIfExists, readJson, sha256, walkFiles } from "./util.js";
+import { catalogFor } from "./catalog.js";
+
+const HOME = os.homedir();
+
+const MCP_FILE_NAMES = [
+  ".mcp.json",
+  ".cursor/mcp.json",
+  ".claude/settings.json",
+  "claude_desktop_config.json",
+  ".mcp/servers.json",
+];
+
+const CONTEXT_FILE_NAMES = [
+  "AGENTS.md",
+  "CLAUDE.md",
+  ".cursorrules",
+  "GEMINI.md",
+  "CONTEXT.md",
+];
+
+const SKILL_DIRS = [".claude/skills", ".cursor/skills", ".codex/skills"];
+
+function extractMcpServers(json) {
+  if (!json || typeof json !== "object") return {};
+  return json.mcpServers || json.servers || json.mcp || {};
+}
+
+function readServersFrom(json, label) {
+  const map = extractMcpServers(json);
+  const out = [];
+  for (const [name, entry] of Object.entries(map)) {
+    if (!entry || typeof entry !== "object") continue;
+    out.push(makeServer(name, entry, label));
+  }
+  return out;
+}
+
+function makeServer(name, entry, source) {
+  const command = entry.command || null;
+  const args = Array.isArray(entry.args) ? entry.args : [];
+  const env = entry.env && typeof entry.env === "object" ? entry.env : {};
+  const transport =
+    entry.type || (entry.url ? "http" : entry.command ? "stdio" : "unknown");
+  const url = entry.url || null;
+  const packageName = extractPackage(command, args);
+  const tools = normalizeTools(entry.tools);
+  const catalog = catalogFor(packageName) || catalogFor(name);
+  const contentForSig = [
+    name,
+    command,
+    args.join(" "),
+    JSON.stringify(env),
+    tools.map((t) => `${t.name}:${t.description}`).join("|"),
+  ].join("\u0000");
+  return {
+    id: sha256(`${source}\u0000${name}`).slice(0, 16),
+    kind: "mcp-server",
+    displayName: name,
+    source,
+    transport,
+    command,
+    args,
+    env,
+    url,
+    packageName,
+    tools,
+    catalog,
+    signature: sha256(contentForSig),
+  };
+}
+
+function normalizeTools(tools) {
+  if (!Array.isArray(tools)) return [];
+  return tools.map((t) => ({
+    name: t.name || t.title || "tool",
+    description: t.description || t.title || "",
+    inputSchema: t.inputSchema || t.input_schema || t.schema || {},
+  }));
+}
+
+function extractPackage(command, args) {
+  if (!command) return null;
+  const commands = [
+    "npx", "npm", "pnpm", "yarn", "bunx", "uvx", "pipx", "deno",
+    "node", "python", "python3", "poetry", "go", "cargo", "pip",
+  ];
+  const normalized = command.toLowerCase();
+  if (commands.includes(normalized)) {
+    for (const a of args) {
+      if (a.startsWith("-")) continue;
+      if (/^[@A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+/.test(a) || /^[A-Za-z0-9_.-]+$/.test(a)) {
+        return a.replace(/^--/, "");
+      }
+    }
+    return null;
+  }
+  return normalized === "python" || normalized === "node" ? null : command;
+}
+
+/** Parse Claude Code hooks (and similar) into server-like action objects. */
+function parseHooks(json, label) {
+  const hooks = json?.hooks;
+  if (!hooks || typeof hooks !== "object") return [];
+  const out = [];
+  for (const [event, defs] of Object.entries(hooks)) {
+    if (!Array.isArray(defs)) continue;
+    for (const def of defs) {
+      const matcher = def.matcher || "any";
+      const entries = Array.isArray(def.hooks) ? def.hooks : [];
+      for (const h of entries) {
+        const command = h?.command || "";
+        if (!command) continue;
+        const name = `hook:${event}/${matcher}`;
+        const buildId = [label, event, matcher, command].join("\u0000");
+        out.push({
+          id: sha256(buildId).slice(0, 16),
+          kind: "hook",
+          displayName: name,
+          source: `${label} · hook`,
+          transport: "hook",
+          command,
+          args: [],
+          env: {},
+          url: null,
+          packageName: extractPackage(command, []),
+          tools: [{ name: "hook", description: command }],
+          catalog: catalogFor(extractPackage(command, [])),
+          signature: sha256(buildId),
+        });
+      }
+    }
+  }
+  return out;
+}
+
+function collectSkills(cwd, { home = true } = {}) {
+  const roots = SKILL_DIRS.map((d) => path.join(cwd, d));
+  if (home && HOME !== cwd) {
+    roots.push(path.join(HOME, ".codex", "skills"));
+    roots.push(path.join(HOME, ".claude", "skills"));
+  }
+  const files = [];
+  for (const root of roots) {
+    if (!fs.existsSync(root)) continue;
+    for (const f of walkFiles(root, [])) {
+      if (f.endsWith(".md")) files.push(f);
+    }
+  }
+  return files.slice(0, 200);
+}
+
+/**
+ * Discover agent/MCP configs, hooks, instruction files and skills.
+ */
+export function discover(cwd = process.cwd(), opts = {}) {
+  const servers = [];
+  const hooks = [];
+  const contextFiles = [];
+  const errors = [];
+  const files = [];
+  const includeHome = opts.home !== false;
+
+  for (const rel of MCP_FILE_NAMES) {
+    const file = path.join(cwd, rel);
+    if (!fs.existsSync(file)) continue;
+    files.push(file);
+    const json = readJson(file);
+    if (!json) {
+      errors.push({ file, message: "Could not parse JSON" });
+      continue;
+    }
+    const label = relLabel(rel);
+    servers.push(...readServersFrom(json, label));
+    hooks.push(...parseHooks(json, label));
+  }
+
+  if (opts.recursive) {
+    for (const file of walkFiles(cwd, [".git", "node_modules"])) {
+      if (!file.endsWith("mcp.json") && !file.endsWith("claude_desktop_config.json")) {
+        continue;
+      }
+      if (file.includes(path.join("node_modules"))) continue;
+      if (!files.includes(file)) {
+        files.push(file);
+        const json = readJson(file);
+        if (json) servers.push(...readServersFrom(json, path.relative(cwd, file)));
+      }
+    }
+  }
+
+  if (includeHome && HOME !== cwd) {
+    const homeCandidates = [
+      [path.join(HOME, ".claude.json"), ".claude.json"],
+      [path.join(HOME, ".claude", "settings.json"), ".claude/settings.json"],
+      [path.join(HOME, ".cursor", "mcp.json"), ".cursor/mcp.json"],
+    ];
+    for (const [file, label] of homeCandidates) {
+      if (!fs.existsSync(file)) continue;
+      const json = readJson(file);
+      if (!json) continue;
+      files.push(file);
+      servers.push(...readServersFrom(json, label));
+      hooks.push(...parseHooks(json, label));
+    }
+    const codex = path.join(HOME, ".codex");
+    if (fs.existsSync(codex)) files.push(codex);
+  }
+
+  for (const rel of CONTEXT_FILE_NAMES) {
+    const file = path.join(cwd, rel);
+    if (!fs.existsSync(file)) continue;
+    files.push(file);
+    contextFiles.push({
+      file,
+      kind: "instructions",
+      label: rel,
+      content: readIfExists(file) || "",
+    });
+  }
+
+  for (const file of collectSkills(cwd, { home: includeHome })) {
+    files.push(file);
+    contextFiles.push({
+      file,
+      kind: "skill",
+      label: path.relative(cwd, file),
+      content: readIfExists(file) || "",
+    });
+  }
+
+  const seen = new Set();
+  const dedupe = (arr) =>
+    arr.filter((s) => {
+      const key = `${s.source}:${s.displayName}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+
+  return {
+    servers: dedupe(servers),
+    hooks: dedupe(hooks),
+    contextFiles,
+    errors,
+    files,
+  };
+}
+
+function relLabel(rel) {
+  const base = path.basename(rel);
+  const dir = path.dirname(rel);
+  return dir && dir !== "." ? `${dir}/${base}` : base;
+}
+
+/** Read the configured policy, if any. */
+export function loadPolicy(cwd) {
+  return readJson(path.join(cwd, ".perimeter", "config.json"));
+}

package/src/guard.js

@@ -0,0 +1,159 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import fs from "node:fs";
+import path from "node:path";
+
+// Claude Code / common agent tool name → capability.
+const CAPABILITY_BY_TOOL = {
+  Bash: "shell",
+  Write: "filesystem-write",
+  Edit: "filesystem-write",
+  MultiEdit: "filesystem-write",
+  NotebookEdit: "code-exec",
+  Task: "subagent",
+  WebFetch: "network-in",
+  WebSearch: "network-in",
+  Grep: "search",
+  Read: "filesystem-read",
+  Glob: "filesystem-read",
+};
+
+export function describeTool(name) {
+  return { capability: CAPABILITY_BY_TOOL[name] || "unrecognised" };
+}
+
+export function defaultPolicy() {
+  return {
+    allowTools: [],
+    denyTools: [],
+    allowCapabilities: [],
+    denyCapabilities: ["shell", "code-exec", "filesystem-write"],
+    log: ".perimeter/guard.log.jsonl",
+  };
+}
+
+/** Decide whether a tool call should be blocked. Fail-closed by default. */
+export function shouldBlock(tool, policy) {
+  const p = { ...defaultPolicy(), ...policy };
+  if (!tool) return true;
+  if (p.allowTools.includes(tool)) return false;
+  if (p.denyTools.includes(tool)) return true;
+  const cap = CAPABILITY_BY_TOOL[tool];
+  if (!cap) return p.denyTools.includes(tool); // unknown tools are allowed only if explicitly denied
+  if (p.allowCapabilities.includes(cap)) return false;
+  return p.denyCapabilities.includes(cap);
+}
+
+function openLog(logPath) {
+  if (!logPath) return { write: () => {} };
+  const dir = path.dirname(logPath);
+  if (dir) fs.mkdirSync(dir, { recursive: true });
+  return fs.createWriteStream(logPath, { flags: "a" });
+}
+
+function parseCommand(command) {
+  const matches = (command || "").match(/(?:[^\s"]+|"[^"]*")+/g) || [];
+  return matches.map((s) => s.replace(/^"|"$/g, ""));
+}
+
+/**
+ * A controllable MCP guard. It spawns the real MCP server as a child and proxies
+ * JSON-RPC over stdio, intercepting blocked `tools/call` requests.
+ */
+export function createGuard({ command, policy = {} }) {
+  const parts = parseCommand(command);
+  if (!parts.length) throw new Error("guard requires --server <command>");
+  const child = spawn(parts[0], parts.slice(1), {
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+  const mergedPolicy = { ...defaultPolicy(), ...policy };
+  const log = openLog(mergedPolicy.log);
+  const watchers = [];
+
+  const rl = createInterface({ input: child.stdout });
+  rl.on("line", (line) => {
+    for (const watcher of watchers) watcher(line);
+  });
+  child.stderr.on("data", (chunk) => {
+    process.stderr.write(chunk);
+  });
+
+  return {
+    child,
+    policy: mergedPolicy,
+    send(line) {
+      let msg;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        child.stdin.write(line + "\n");
+        return;
+      }
+      if (msg && msg.method === "tools/call" && msg.id !== undefined) {
+        const tool = msg.params && msg.params.name;
+        const blocked = shouldBlock(tool, mergedPolicy);
+        log.write(
+          JSON.stringify({
+            ts: new Date().toISOString(),
+            tool,
+            method: msg.method,
+            allowed: !blocked,
+          }) + "\n"
+        );
+        if (blocked) {
+          const response = JSON.stringify({
+            jsonrpc: "2.0",
+            id: msg.id,
+            error: {
+              code: -32602,
+              message: `Blocked by Perimeter policy: ${tool}`,
+            },
+          });
+          for (const watcher of watchers) watcher(response);
+          return;
+        }
+      }
+      child.stdin.write(line + "\n");
+    },
+    onResponse(cb) {
+      watchers.push(cb);
+    },
+    close() {
+      try {
+        child.stdin.end();
+        child.kill();
+      } catch {
+        /* ignore */
+      }
+    },
+  };
+}
+
+/**
+ * Command-line entry: wire the guard to this process's stdio and run until the
+ * child exits or stdin ends.
+ */
+export function runGuardCli({ command, policy }) {
+  const guard = createGuard({ command, policy });
+  const rl = createInterface({ input: process.stdin });
+  rl.on("line", (line) => {
+    if (line.trim()) guard.send(line.trim());
+  });
+  rl.on("close", () => {
+    try {
+      process.exit(0);
+    } catch {
+      /* ignore */
+    }
+  });
+  guard.onResponse((line) => process.stdout.write(line + "\n"));
+  guard.child.on("exit", (code) => {
+    try {
+      rl.close();
+      process.exit(code ?? 0);
+    } catch {
+      /* ignore */
+    }
+  });
+  return guard;
+}

package/src/index.js

@@ -0,0 +1,9 @@
+export { runAudit } from "./audit.js";
+export { discover } from "./discover.js";
+export { catalogFor, KNOWN_SERVERS } from "./catalog.js";
+export { tokensForText, tokensForTools, estimateCost, MODEL_PRICES } from "./tokens.js";
+export { runRules, runContextRules, verdictOf, SEVERITIES } from "./rules.js";
+export { buildSessionReport, parseSessionFile, findSessions } from "./sessions.js";
+export { createGuard, shouldBlock, describeTool, defaultPolicy } from "./guard.js";
+export { createServer as createPerimeterServer, listen as listenPerimeter } from "./server.js";
+export { VERSION } from "./version.js";