@shomra/agent 0.3.17 → 0.3.18

package/src/commands/git-hooks.mjs

@@ -0,0 +1,163 @@
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { EXIT_USAGE } from '../core/exit-codes.mjs';
+import { bold, dim, green, red, yellow } from '../core/terminal.mjs';
+
+export async function cmdInstallPrecommit(flags, positional) {
+
+  if (flags['pre-receive']) return installPreReceive(flags, positional);
+  const root = path.resolve(positional[0] || '.');
+  const hooksDir = gitHooksDir(root);
+  if (!hooksDir) {
+    console.error(red('✗') + ' Not a git repository (or git unavailable). cd into your repo first.');
+    process.exit(EXIT_USAGE);
+  }
+  const hookPath = path.join(hooksDir, 'pre-commit');
+  const marker = 'shomra check --staged';
+  const managed = [
+    '#!/bin/sh',
+    '# Shomra - block staged AI artifacts that fail the gate before they land.',
+    '# Managed by `shomra install-precommit`. Delete this file to uninstall.',
+
+    'command -v shomra >/dev/null 2>&1 || {',
+    '  echo "" >&2',
+    '  echo "!! ============================================================== !!" >&2',
+    '  echo "!!  WARNING: shomra not on PATH - the AI-artifact gate DID NOT RUN !!" >&2',
+    '  echo "!!  Staged MCP/skill/rules files were committed UNGATED.          !!" >&2',
+    '  echo "!!  Fix: npm i -g @shomra/agent   (then re-commit to gate)        !!" >&2',
+    '  echo "!! ============================================================== !!" >&2',
+    '  echo "" >&2',
+    '  exit 0',
+    '}',
+    'shomra check --staged',
+    'if [ "$?" -eq 1 ]; then',
+    '  echo "✗ Shomra blocked a staged AI artifact - run: shomra fix <file> --apply  (or: git commit --no-verify to override)"',
+    '  exit 1',
+    'fi',
+    'exit 0',
+    '',
+  ].join('\n');
+
+  let existing = null;
+  try {
+    existing = fs.readFileSync(hookPath, 'utf8');
+  } catch {}
+
+  if (existing && existing.includes(marker) && !flags.force) {
+    console.log(green('  ✓') + ' Shomra pre-commit hook already installed ' + dim('→ ' + hookPath));
+    return;
+  }
+  if (existing && !existing.includes(marker) && !flags.force) {
+    console.log('\n  ' + yellow('⚠') + ' A pre-commit hook already exists ' + dim('→ ' + hookPath));
+    console.log('  Add this line to it, or re-run with ' + bold('--force') + ' to replace it (a backup is kept):');
+    console.log('    ' + bold(marker) + '\n');
+    return;
+  }
+  if (existing && flags.force) {
+    try {
+      fs.writeFileSync(hookPath + '.bak', existing);
+      console.log(dim('  Backed up existing hook → ' + path.basename(hookPath) + '.bak'));
+    } catch {}
+  }
+  fs.writeFileSync(hookPath, managed, 'utf8');
+  try {
+    fs.chmodSync(hookPath, 0o755);
+  } catch {}
+  console.log('\n  ' + green('✓ Installed') + ' Shomra pre-commit hook ' + dim('→ ' + hookPath));
+  console.log(dim('  Staged AI artifacts are now gated on every commit. Override once with ') + bold('git commit --no-verify') + dim('.\n'));
+}
+
+function installPreReceive(flags, positional) {
+  const root = path.resolve(positional[0] || flags.path || '.');
+
+  const bareHooks = path.join(root, 'hooks');
+  const dir = fs.existsSync(bareHooks) && fs.statSync(bareHooks).isDirectory() ? bareHooks : gitHooksDir(root);
+  if (!dir) {
+    console.error(red('✗') + ` No git hooks directory under ${root}. Point this at a BARE repository (the one the server hosts), not a working checkout.`);
+    process.exit(EXIT_USAGE);
+  }
+
+  const hookPath = path.join(dir, 'pre-receive');
+  const marker = 'shomra gate --all';
+  const managed = [
+    '#!/bin/sh',
+    '# Shomra - refuse a push that carries a blocked AI artifact.',
+    '# Managed by `shomra install-precommit --pre-receive`. Delete this file to uninstall.',
+    '#',
+    '# Runs on the SERVER, so unlike pre-commit it cannot be skipped with',
+    '# --no-verify and it covers developers who never installed anything.',
+    'set -e',
+    '',
+    '# ⚠ FAIL CLOSED. The client-side hook fails open on a missing binary because',
+    '# blocking a local commit over a tooling problem is hostile. The opposite is',
+    '# true here: this is the enforcement point, so an environment that cannot run',
+    '# the check must refuse the push rather than wave it through - otherwise',
+    '# deleting the binary is the bypass.',
+    'command -v shomra >/dev/null 2>&1 || {',
+    '  echo "" >&2',
+    '  echo "REJECTED: shomra is not installed on this git server, so the AI-artifact" >&2',
+    '  echo "          gate could not run. Install it (npm i -g @shomra/agent) or" >&2',
+    '  echo "          remove this hook deliberately." >&2',
+    '  exit 1',
+    '}',
+    '',
+    'TMP=$(mktemp -d)',
+    'trap \'rm -rf "$TMP"\' EXIT',
+    'STATUS=0',
+    '',
+    '# stdin is "<old> <new> <ref>" per pushed ref. Export each ref\'s tree to a',
+    '# temp dir and gate it - the push is refused as a whole if any ref carries a',
+    '# blocked artifact.',
+    'while read -r oldrev newrev refname; do',
+    '  # All-zero newrev = branch deletion. Nothing arrives, nothing to gate.',
+    '  case "$newrev" in *[!0]*) ;; *) continue ;; esac',
+    '  WORK="$TMP/$(echo "$refname" | tr "/" "_")"',
+    '  mkdir -p "$WORK"',
+    '  git archive "$newrev" | tar -x -C "$WORK" 2>/dev/null || continue',
+    '  if ! shomra gate --all "$WORK"; then',
+    '    echo "" >&2',
+    '    echo "REJECTED: $refname carries an AI artifact Shomra blocks (see above)." >&2',
+    '    echo "          Fix it locally (shomra check --fix) and push again." >&2',
+    '    STATUS=1',
+    '  fi',
+    'done',
+    '',
+    'exit $STATUS',
+    '',
+  ].join('\n');
+
+  let existing = null;
+  try { existing = fs.readFileSync(hookPath, 'utf8'); } catch {  }
+  if (existing && existing.includes(marker) && !flags.force) {
+    console.log(green('  ✓') + ' Shomra pre-receive hook already installed ' + dim('→ ' + hookPath));
+    return;
+  }
+  if (existing && !existing.includes(marker) && !flags.force) {
+    console.log('\n  ' + yellow('⚠') + ' A pre-receive hook already exists ' + dim('→ ' + hookPath));
+    console.log('  Chain Shomra into it, or re-run with ' + bold('--force') + ' to replace it (a backup is kept).\n');
+    return;
+  }
+  if (existing && flags.force) {
+    try { fs.writeFileSync(hookPath + '.bak', existing); console.log(dim('  Backed up existing hook → pre-receive.bak')); } catch {  }
+  }
+  fs.writeFileSync(hookPath, managed, 'utf8');
+  try { fs.chmodSync(hookPath, 0o755); } catch {  }
+
+  console.log('\n  ' + green('✓ Installed') + ' Shomra pre-receive hook ' + dim('→ ' + hookPath));
+  console.log(dim('  Every push is now gated server-side - no --no-verify, and no per-developer install.'));
+  console.log(dim('  This hook FAILS CLOSED: if shomra is missing on the server, pushes are refused.'));
+  console.log(dim('  GitHub.com has no server-side hooks - there, use the Action as a required status check.\n'));
+}
+
+function gitHooksDir(root) {
+  try {
+    const dir = execSync('git rev-parse --git-path hooks', { cwd: root, stdio: ['ignore', 'pipe', 'ignore'], timeout: 3000 }).toString().trim();
+    if (!dir) return null;
+    const abs = path.isAbsolute(dir) ? dir : path.join(root, dir);
+    fs.mkdirSync(abs, { recursive: true });
+    return abs;
+  } catch {
+    return null;
+  }
+}

package/src/commands/init.mjs

@@ -0,0 +1,36 @@
+import os from 'node:os';
+import { api, machineInfo } from '../core/api-client.mjs';
+import { CONFIG_FILE, getMachineId, loadConfig, saveConfig } from '../core/config.mjs';
+import { EXIT_USAGE } from '../core/exit-codes.mjs';
+import { bold, dim, green, red } from '../core/terminal.mjs';
+
+export async function cmdInit(flags) {
+  const cfg = loadConfig();
+  const key = flags.key || process.env.SHOMRA_API_KEY;
+
+  const url = (flags.url || cfg.url || '').replace(/\/$/, '');
+  if (!key) {
+    console.error(red('✗') + ' Missing API key. Run: ' + bold('shomra init --key shm_live_… --url <your backend>'));
+    process.exit(EXIT_USAGE);
+  }
+  if (!url) {
+    console.error(red('✗') + ' Missing backend URL. Run: ' + bold('shomra init --key shm_live_… --url <your backend>'));
+    process.exit(EXIT_USAGE);
+  }
+  cfg.apiKey = key;
+  cfg.url = url;
+  getMachineId(cfg);
+  saveConfig(cfg);
+  process.stdout.write(dim('Enrolling this machine… '));
+  try {
+    const res = await api(url, key, '/agent/enroll', { machine: machineInfo(cfg) });
+    console.log(green('done'));
+    console.log(`  ${green('✓')} Enrolled ${bold(os.hostname())} into org ${bold(res.org?.name ?? '?')}`);
+    console.log(`  ${dim('Config saved to ' + CONFIG_FILE)}`);
+    console.log(`\n  Next: ${bold('shomra report')} to send your first inventory.`);
+  } catch (e) {
+    console.log(red('failed'));
+    console.error(`  ${red('✗')} ${e.message}`);
+    process.exit(1);
+  }
+}

package/src/commands/install-hook.mjs

@@ -0,0 +1,51 @@
+import { AGENT_INSTALLERS, AGENT_KEYS, AGENT_LABELS } from '../agents/installers.mjs';
+import { EXIT_USAGE } from '../core/exit-codes.mjs';
+import { bold, dim, green, red, yellow } from '../core/terminal.mjs';
+import { PROMPT_HOOK_AGENTS } from '../guard/prompt-guard.mjs';
+
+export function cmdInstallHook(flags) {
+  const global = !!flags.global;
+  const requested = flags.agent
+    ? String(flags.agent).toLowerCase().split(',').map((s) => s.trim()).filter(Boolean)
+    : ['claude'];
+  const unknown = requested.filter((a) => a !== 'all' && !AGENT_KEYS.includes(a));
+  if (unknown.length) {
+    console.error(red('✗') + ` Unknown agent(s): ${unknown.join(', ')}. Supported: ${AGENT_KEYS.join(', ')}, all.`);
+    process.exit(EXIT_USAGE);
+  }
+  const targets = requested.includes('all') ? AGENT_KEYS : requested;
+  if (!flags.agent) {
+    console.log(dim('  No --agent given - installing for Claude Code only. Use ') + bold('--agent all') + dim(' (or ') + bold('shomra protect') + dim(') to cover every agent.'));
+  }
+
+  for (const agent of targets) {
+    const { file, changed } = AGENT_INSTALLERS[agent](global);
+    if (changed) {
+      console.log(green('✓') + ` Installed the Shomra runtime firewall for ${bold(AGENT_LABELS[agent])} → ${bold(file)}`);
+    } else {
+      console.log(yellow('•') + ` Shomra runtime firewall already installed for ${AGENT_LABELS[agent]} in ${bold(file)}`);
+    }
+    if (agent === 'windsurf') {
+      console.log(dim('    Note: Windsurf\'s post-hooks can flag/log but not withhold a tool result.'));
+    }
+    if (agent === 'aider') {
+      console.log(dim('    Note: Aider has no tool hook - this routes its model calls through the'));
+      console.log(dim('          Shomra LLM Guard proxy. Start it with ') + 'shomra llm-proxy' + dim(' and set your API key.'));
+    }
+  }
+  console.log(dim('\n  PreToolUse:  screens every shell command, artifact write, and MCP call BEFORE it runs -'));
+  console.log(dim('               and vets AI model loads the agent writes (from_pretrained / hf_hub /'));
+  console.log(dim('               torch.hub …) against the Shomra Model Index, so a known-vulnerable model'));
+  console.log(dim('               is flagged with its fix BEFORE the load lands. (SHOMRA_MODEL_GUARD=0 to silence.)'));
+  console.log(dim('  PostToolUse: screens content fetched pages / file reads / MCP responses bring BACK'));
+  console.log(dim('               into the agent context - prompt injection, exfil sinks, hidden payloads.'));
+  if (targets.some((a) => PROMPT_HOOK_AGENTS.has(a))) {
+    console.log(dim('  Prompt:      screens what YOU submit before it leaves the machine - a pasted live'));
+    console.log(dim('               credential is refused; pasted injection text is flagged to the model as'));
+    console.log(dim('               untrusted data. (SHOMRA_PROMPT_GUARD_OFF=1 to disable just this one.)'));
+  }
+  console.log(dim('  Blocked calls/results are refused with a reason; every decision lands in Shomra → Gate Activity.'));
+  console.log(dim('  Dangerous calls (curl|sh, reverse shells, secrets, injection) are blocked ON-MACHINE with'));
+  console.log(dim('  no network; only policy-relevant calls escalate to the backend, so a slow/down backend'));
+  console.log(dim('  never freezes the agent. Tip: ') + 'SHOMRA_GUARD_STRICT=1' + dim(' also fails-closed on the server tier.'));
+}

package/src/commands/llm-proxy.mjs

@@ -0,0 +1,153 @@
+import os from 'node:os';
+import { loadConfig, resolveSettings } from '../core/config.mjs';
+import { exitNotConfigured } from '../core/exit-codes.mjs';
+import { bold, cyan, dim, green, red, yellow } from '../core/terminal.mjs';
+import { VERSION } from '../core/version.mjs';
+import { resolveAgentIdentityHandle } from './agent-identity.mjs';
+
+export const LLM_PROVIDERS = ['openai', 'anthropic', 'gemini', 'groq', 'mistral', 'xai', 'deepseek', 'openrouter', 'together'];
+
+const OPENAI_COMPATIBLE = ['groq', 'mistral', 'xai', 'deepseek', 'openrouter', 'together'];
+const DEFAULT_PORT = 4141;
+const BODYLESS_METHODS = ['GET', 'HEAD'];
+const HOP_BY_HOP_REQUEST_HEADERS = ['host', 'connection', 'content-length', 'accept-encoding', 'expect'];
+const HOP_BY_HOP_RESPONSE_HEADERS = ['content-length', 'transfer-encoding', 'content-encoding', 'connection'];
+
+function newSessionId() {
+  return `proxy-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function forwardHeaders(incoming, { apiKey, actor, machineId, sessionId, project, agentId }) {
+  const headers = { ...incoming };
+  for (const name of HOP_BY_HOP_REQUEST_HEADERS) delete headers[name];
+
+  headers['x-shomra-key'] = apiKey;
+  headers['x-shomra-actor'] = actor;
+  if (machineId) headers['x-shomra-machine'] = machineId;
+  headers['x-shomra-source'] = 'shomra llm-proxy';
+  if (!headers['x-shomra-session']) headers['x-shomra-session'] = sessionId;
+  if (project) headers['x-shomra-project'] = project;
+  if (agentId && !headers['x-shomra-agent']) headers['x-shomra-agent'] = agentId;
+  return headers;
+}
+
+async function readBody(request) {
+  const chunks = [];
+  for await (const chunk of request) chunks.push(chunk);
+  return Buffer.concat(chunks);
+}
+
+function sendJson(response, status, payload) {
+  response.writeHead(status, { 'content-type': 'application/json' });
+  response.end(JSON.stringify(payload));
+}
+
+async function streamUpstreamBody(upstream, response) {
+  try {
+    if (upstream.body) for await (const chunk of upstream.body) response.write(chunk);
+  } catch {
+    return;
+  }
+}
+
+async function relayResponse(upstream, response) {
+  const headers = {};
+  for (const [name, value] of upstream.headers) {
+    if (!HOP_BY_HOP_RESPONSE_HEADERS.includes(name)) headers[name] = value;
+  }
+  response.writeHead(upstream.status, headers);
+  await streamUpstreamBody(upstream, response);
+  response.end();
+}
+
+function statusMark(status) {
+  if (status === 403) return red('BLOCKED');
+  return status >= 400 ? yellow(String(status)) : green(String(status));
+}
+
+function logCall(provider, request, suffix, status) {
+  const time = new Date().toTimeString().slice(0, 8);
+  console.log(`  ${dim(time)} ${bold(provider.padEnd(10))} ${dim(request.method)} ${suffix} ${statusMark(status)}`);
+}
+
+function createProxyHandler({ url, headerContext, providerPattern }) {
+  return async (request, response) => {
+    const requestPath = String(request.url).replace(/^\/llm(?=\/)/, '');
+    const match = requestPath.match(providerPattern);
+    if (!match) {
+      sendJson(response, 404, {
+        error: { message: `Unknown route - use /<provider>/… (providers: ${LLM_PROVIDERS.join(', ')})` },
+      });
+      return;
+    }
+
+    const [, provider, suffix] = match;
+    const route = `/llm/${provider}${suffix ?? '/'}`;
+    const body = await readBody(request);
+    const headers = forwardHeaders(request.headers, headerContext);
+
+    let upstream;
+    try {
+      upstream = await fetch(`${url}${route}`, {
+        method: request.method,
+        headers,
+        body: BODYLESS_METHODS.includes(request.method) ? undefined : body,
+      });
+    } catch (error) {
+      const cause = error.cause ? ` (${error.cause.code ?? ''} ${error.cause.message ?? error.cause})` : '';
+      sendJson(response, 502, { error: { message: `Shomra backend unreachable at ${url}: ${error.message}${cause}` } });
+      console.log(`  ${red('✗')} ${request.method} ${request.url} ${red('backend unreachable')}${dim(cause)} ${dim(`hdrs: ${Object.keys(headers).join(',')}`)}`);
+      return;
+    }
+
+    await relayResponse(upstream, response);
+    logCall(provider, request, suffix ?? '/', upstream.status);
+  };
+}
+
+function printStartupBanner({ port, url, project, actor }) {
+  console.log(bold(cyan('\n  Shomra LLM Guard')) + dim(` - local proxy v${VERSION}`));
+  console.log(`  ${green('●')} Listening on ${bold(`http://127.0.0.1:${port}`)} ${dim(`→ ${url} → provider`)}`);
+  if (project) console.log(`  ${dim('Project  ')} ${project}`);
+  console.log(`  ${dim('Actor    ')} ${actor}\n`);
+
+  console.log(bold('  Route your SDKs through the guard (no code changes):'));
+  console.log(dim('    OpenAI / Anthropic (PowerShell)'));
+  console.log(`      $env:OPENAI_BASE_URL    = "http://127.0.0.1:${port}/openai/v1"`);
+  console.log(`      $env:ANTHROPIC_BASE_URL = "http://127.0.0.1:${port}/anthropic"`);
+  console.log(dim('    OpenAI / Anthropic (bash/zsh)'));
+  console.log(`      export OPENAI_BASE_URL=http://127.0.0.1:${port}/openai/v1`);
+  console.log(`      export ANTHROPIC_BASE_URL=http://127.0.0.1:${port}/anthropic`);
+  console.log(dim('    Gemini - point the Google GenAI SDK base URL at'));
+  console.log(`      http://127.0.0.1:${port}/gemini`);
+  console.log(dim(`    OpenAI-compatible (${OPENAI_COMPATIBLE.join(', ')}) - set the SDK baseURL to`));
+  console.log(`      http://127.0.0.1:${port}/<provider>/v1`);
+  console.log(dim('\n  Prompts and completions are screened against org policy;'));
+  console.log(dim('  blocked calls return HTTP 403 with the reason. Ctrl+C to stop.\n'));
+}
+
+export async function cmdLlmProxy(flags) {
+  const config = loadConfig();
+  const { apiKey, url } = resolveSettings(config);
+  if (!apiKey) exitNotConfigured();
+
+  const port = parseInt(flags.port, 10) || DEFAULT_PORT;
+  const project = flags.project ? String(flags.project) : null;
+  const actor = `${os.hostname()}/${os.userInfo().username}`;
+
+  const handler = createProxyHandler({
+    url,
+    providerPattern: new RegExp(`^/(${LLM_PROVIDERS.join('|')})(/.*)?$`),
+    headerContext: {
+      apiKey,
+      actor,
+      project,
+      machineId: config.machineId,
+      sessionId: newSessionId(),
+      agentId: resolveAgentIdentityHandle(flags),
+    },
+  });
+
+  const { createServer } = await import('node:http');
+  createServer(handler).listen(port, '127.0.0.1', () => printStartupBanner({ port, url, project, actor }));
+}

package/src/commands/mcp-add.mjs

@@ -0,0 +1,185 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadConfig, resolveSettings } from '../core/config.mjs';
+import { EXIT_USAGE } from '../core/exit-codes.mjs';
+import { SEV_COLOR, bold, cyan, dim, green, red, yellow } from '../core/terminal.mjs';
+import { localGate } from '../detect/guard-signals.mjs';
+import { mcpIndexAlert, mcpLookup, mcpLookupId, parseEnvKV, worstMcpVerdict } from '../mcp/lookup.mjs';
+import { printAlternatives } from '../models/lookup.mjs';
+
+const MAX_FINDINGS_SHOWN = 6;
+const RUNNER_NAMES = /^(npx|bunx|pnpx|uvx|uv|node|deno|bun|python3?|py|docker|podman|sh|bash|zsh|ruby|go|cargo|dotnet)$/i;
+
+function usageExit(message, hint) {
+  console.error(`${red('✗')} ${message}`);
+  if (hint) console.error(dim('  Try: ') + bold(hint));
+  process.exit(EXIT_USAGE);
+}
+
+function buildServerEntry(flags, positional) {
+  const server = {};
+  if (flags.url) server.url = String(flags.url);
+
+  const tokens = flags.command ? String(flags.command).split(/\s+/) : positional.slice(2);
+  if (tokens.length) {
+    [server.command] = tokens;
+    if (tokens.length > 1) server.args = tokens.slice(1);
+  }
+  if (flags.env) server.env = parseEnvKV(flags.env);
+  return { server, tokens };
+}
+
+function assertUsableArguments(name, server, tokens) {
+  if (!server.command) return;
+  if (String(server.command).startsWith('-')) {
+    usageExit(
+      `"${server.command}" is a flag, not a command - the server NAME comes first.`,
+      `shomra mcp add <name> ${[server.command, ...(server.args || [])].join(' ')}`,
+    );
+  }
+  if (RUNNER_NAMES.test(String(name))) {
+    usageExit(
+      `"${name}" is a runner, not a server name - it looks like the NAME argument was left out.`,
+      `shomra mcp add <name> ${[name, ...tokens].join(' ')}`,
+    );
+  }
+}
+
+async function lookupSecurityIndex(flags, server, name) {
+  if (flags['no-index']) return null;
+  const { url } = resolveSettings(loadConfig());
+  if (!url) return { error: 'no backend configured - set SHOMRA_URL or run shomra init --url' };
+  try {
+    return await mcpLookup(url, mcpLookupId(server, name));
+  } catch (error) {
+    return { error: error.message };
+  }
+}
+
+function printIndexSummary(index) {
+  if (!index) return;
+  if (index.found && index.scanned) {
+    const colour = index.verdict === 'FAIL' ? red : index.verdict === 'REVIEW' ? yellow : green;
+    console.log(dim('    ── MCP Security Index: ') + bold(index.slug) + dim(' · verdict ') + colour(String(index.verdict)) + dim(` · risk ${index.riskScore} ──`));
+    for (const finding of (index.findings || []).slice(0, MAX_FINDINGS_SHOWN)) {
+      console.log(`    ${(SEV_COLOR[finding.severity] || dim)(String(finding.severity).padEnd(8))} ${finding.title} ${dim('(index)')}`);
+    }
+    printAlternatives(index.alternatives, 'mcp', '    ');
+    return;
+  }
+  if (index.found && !index.scanned) {
+    console.log(dim(`    MCP Security Index: found "${index.slug}" but it hasn't been scanned yet.`));
+    return;
+  }
+  if (index.error) {
+    console.log(dim(`    MCP Security Index: unavailable (${index.error}) - using local checks only.`));
+    return;
+  }
+  console.log(dim('    MCP Security Index: not indexed - using local checks only.'));
+}
+
+function printVettingReport(name, localVerdict, index) {
+  console.log(bold(cyan(`\n  Vetting MCP server "${name}"…`)));
+  for (const finding of localVerdict.findings.slice(0, MAX_FINDINGS_SHOWN)) {
+    console.log(`    ${SEV_COLOR[finding.severity](String(finding.severity).padEnd(8))} ${finding.title} ${dim('(local)')}`);
+  }
+  printIndexSummary(index);
+}
+
+function readConfigOrEmpty(configFile) {
+  if (!fs.existsSync(configFile)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(configFile, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function readConfigOrExit(configFile) {
+  if (!fs.existsSync(configFile)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(configFile, 'utf8'));
+  } catch {
+    console.error(`${red('✗')} ${configFile} is not valid JSON.`);
+    return process.exit(EXIT_USAGE);
+  }
+}
+
+function writeServerEntry(configFile, name, server) {
+  const config = readConfigOrExit(configFile);
+  config.mcpServers = config.mcpServers || {};
+  const existed = !!config.mcpServers[name];
+  config.mcpServers[name] = server;
+  fs.mkdirSync(path.dirname(configFile), { recursive: true });
+  fs.writeFileSync(configFile, `${JSON.stringify(config, null, 2)}\n`);
+  return existed;
+}
+
+function outcomeNote(verdict) {
+  if (verdict === 'FLAG') return yellow('  (flagged - review the findings above)');
+  if (verdict === 'BLOCK') return red('  (forced past a BLOCK)');
+  return green('  ✓ clean');
+}
+
+export async function cmdMcpAdd(flags, positional, configFile) {
+  const name = positional[1];
+  if (!name) usageExit(`Usage: ${bold('shomra mcp add <name> <command…>')}`);
+
+  const { server, tokens } = buildServerEntry(flags, positional);
+  if (!server.url && !server.command) usageExit('Provide a launch command or --url.');
+  assertUsableArguments(name, server, tokens);
+
+  const candidate = JSON.stringify({ mcpServers: { [name]: server } }, null, 2);
+  const localVerdict = localGate(candidate, { kind: 'mcp', path: '.mcp.json' });
+  const index = await lookupSecurityIndex(flags, server, name);
+  const verdict = worstMcpVerdict(localVerdict.verdict, mcpIndexAlert(index));
+
+  if (!flags.json) printVettingReport(name, localVerdict, index);
+
+  if (verdict === 'BLOCK' && !flags.force) {
+    if (flags.json) {
+      console.log(JSON.stringify({
+        installed: false, verdict, local: localVerdict.verdict, index, findings: localVerdict.findings,
+      }, null, 2));
+    } else {
+      console.log(`\n  ${red('✗ Blocked - not installed.')} ${dim('Review the findings, or override with')} ${bold('--force')}${dim('.')}\n`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  const existed = writeServerEntry(configFile, name, server);
+  const relative = path.relative(process.cwd(), configFile).split(path.sep).join('/');
+
+  if (flags.json) {
+    console.log(JSON.stringify({
+      installed: true, name, verdict, local: localVerdict.verdict, index, config: relative, updated: existed,
+    }, null, 2));
+    return;
+  }
+  console.log(`\n  ${green(existed ? '✓ Updated' : '✓ Added')} MCP server ${bold(name)} ${dim(`→ ${relative}`)}${outcomeNote(verdict)}\n`);
+}
+
+export function cmdMcpList(flags, configFile) {
+  const config = readConfigOrEmpty(configFile);
+  const servers = config.mcpServers || config.servers || {};
+  const names = Object.keys(servers);
+
+  if (flags.json) {
+    console.log(JSON.stringify({ config: configFile, servers }, null, 2));
+    return;
+  }
+
+  const relative = path.relative(process.cwd(), configFile).split(path.sep).join('/');
+  console.log(bold(cyan('\n  MCP servers')) + dim(` - ${relative}`));
+  if (!names.length) {
+    console.log(dim('  (none)\n'));
+    return;
+  }
+  for (const name of names) {
+    const entry = servers[name];
+    const launch = entry.url || [entry.command, ...(entry.args || [])].filter(Boolean).join(' ');
+    console.log(`  ${green('●')} ${bold(name)} ${dim(launch)}`);
+  }
+  console.log('');
+}