@shomra/agent 0.3.16 → 0.3.18

package/src/agents/hook-command.mjs

@@ -0,0 +1,19 @@
+import { CLI_ENTRY_PATH } from '../core/package-root.mjs';
+
+export const LLM_PROXY_BASE = process.env.SHOMRA_LLM_PROXY_BASE || 'http://127.0.0.1:4141/openai/v1';
+
+export const SELF_PATH = CLI_ENTRY_PATH;
+
+function quoteArg(argument) {
+  return /\s/.test(argument) ? `"${argument}"` : argument;
+}
+
+export function hookCommand(args) {
+  return `${quoteArg(process.execPath)} ${quoteArg(SELF_PATH)} ${args}`;
+}
+
+export function shomraHookRe(verb) {
+  return new RegExp(`shomra(\\.mjs"?)?\\s+${verb}`, 'i');
+}
+
+export const SHOMRA_ANY_HOOK_RE = /shomra(\.mjs"?)?\s+(tool-guard|result-guard|prompt-guard|plan-guard)/i;

package/src/agents/hook-files.mjs

@@ -0,0 +1,41 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { SHOMRA_ANY_HOOK_RE, shomraHookRe } from './hook-command.mjs';
+
+function agentHookFiles(agent) {
+  const home = os.homedir();
+  const cwd = process.cwd();
+  switch (agent) {
+    case 'claude': return [path.join(home, '.claude', 'settings.json'), path.join(cwd, '.claude', 'settings.json')];
+    case 'codex': return [path.join(home, '.codex', 'hooks.json'), path.join(cwd, '.codex', 'hooks.json')];
+    case 'gemini': return [path.join(home, '.gemini', 'settings.json'), path.join(cwd, '.gemini', 'settings.json')];
+    case 'cursor': return [path.join(home, '.cursor', 'hooks.json'), path.join(cwd, '.cursor', 'hooks.json')];
+    case 'windsurf': return [path.join(home, '.codeium', 'windsurf', 'hooks.json'), path.join(cwd, '.windsurf', 'hooks.json')];
+    case 'copilot': return [path.join(home, '.copilot', 'hooks', 'shomra.json'), path.join(cwd, '.github', 'hooks', 'shomra.json')];
+    case 'cline': return [path.join(home, '.cline', 'hooks.json'), path.join(cwd, '.cline', 'hooks.json')];
+    case 'aider': return [path.join(home, '.aider.conf.yml'), path.join(cwd, '.aider.conf.yml')];
+    default: return [];
+  }
+}
+
+export function agentHookInstalled(agent) {
+  return agentHookFiles(agent).filter((f) => {
+    try {
+      const text = fs.readFileSync(f, 'utf8');
+      if (agent === 'aider') return /shomra llm guard/i.test(text);
+      return SHOMRA_ANY_HOOK_RE.test(text);
+    } catch {
+      return false;
+    }
+  });
+}
+
+export function hasGroupedHook(list, verb) {
+  const re = shomraHookRe(verb);
+  return Array.isArray(list) && list.some((g) => Array.isArray(g.hooks) && g.hooks.some((h) => re.test(String(h.command || ''))));
+}
+
+export function hasFlatHook(list) {
+  return Array.isArray(list) && list.some((h) => SHOMRA_ANY_HOOK_RE.test(String(h.command || '')));
+}

package/src/agents/installers.mjs

@@ -0,0 +1,203 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { readJsonFile } from '../core/json-file.mjs';
+import { LLM_PROXY_BASE, hookCommand } from './hook-command.mjs';
+import { hasFlatHook, hasGroupedHook } from './hook-files.mjs';
+
+export const AGENT_LABELS = {
+  claude: 'Claude Code',
+  cursor: 'Cursor',
+  windsurf: 'Windsurf',
+  gemini: 'Gemini CLI',
+  codex: 'OpenAI Codex CLI',
+  copilot: 'GitHub Copilot CLI',
+  cline: 'Cline',
+  aider: 'Aider',
+};
+
+export const AGENT_KEYS = Object.keys(AGENT_LABELS);
+
+export const AGENT_INSTALLERS = {
+  claude(global) {
+    const dir = global ? path.join(os.homedir(), '.claude') : path.join(process.cwd(), '.claude');
+    const file = path.join(dir, 'settings.json');
+    const settings = readJsonFile(file);
+    settings.hooks = settings.hooks || {};
+    const pre = (settings.hooks.PreToolUse = settings.hooks.PreToolUse || []);
+    const post = (settings.hooks.PostToolUse = settings.hooks.PostToolUse || []);
+    let changed = false;
+    if (!hasGroupedHook(pre, 'tool-guard')) {
+      pre.push({ matcher: 'Bash|Write|Edit|MultiEdit|NotebookEdit|mcp__.*', hooks: [{ type: 'command', command: hookCommand('tool-guard --agent claude') }] });
+      changed = true;
+    }
+    if (!hasGroupedHook(post, 'result-guard')) {
+      post.push({ matcher: 'WebFetch|WebSearch|Read|NotebookRead|mcp__.*', hooks: [{ type: 'command', command: hookCommand('result-guard --agent claude') }] });
+      changed = true;
+    }
+
+    const prompt = (settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit || []);
+    if (!hasGroupedHook(prompt, 'prompt-guard')) {
+      prompt.push({ hooks: [{ type: 'command', command: hookCommand('prompt-guard --agent claude') }] });
+      changed = true;
+    }
+
+    if (!hasGroupedHook(pre, 'plan-guard')) {
+      pre.push({ matcher: 'ExitPlanMode', hooks: [{ type: 'command', command: hookCommand('plan-guard --agent claude') }] });
+      changed = true;
+    }
+    if (changed) {
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(file, JSON.stringify(settings, null, 2));
+    }
+    return { file, changed };
+  },
+
+  codex(global) {
+    const dir = global ? path.join(os.homedir(), '.codex') : path.join(process.cwd(), '.codex');
+    const file = path.join(dir, 'hooks.json');
+    const settings = readJsonFile(file);
+    const pre = (settings.PreToolUse = settings.PreToolUse || []);
+    const post = (settings.PostToolUse = settings.PostToolUse || []);
+    let changed = false;
+    if (!hasGroupedHook(pre, 'tool-guard')) {
+      pre.push({ matcher: 'Bash|Write|Edit|mcp__.*', hooks: [{ type: 'command', command: hookCommand('tool-guard --agent codex') }] });
+      changed = true;
+    }
+    if (!hasGroupedHook(post, 'result-guard')) {
+      post.push({ matcher: 'WebFetch|WebSearch|Read|mcp__.*', hooks: [{ type: 'command', command: hookCommand('result-guard --agent codex') }] });
+      changed = true;
+    }
+    if (changed) {
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(file, JSON.stringify(settings, null, 2));
+    }
+    return { file, changed };
+  },
+
+  gemini(global) {
+    const dir = global ? path.join(os.homedir(), '.gemini') : path.join(process.cwd(), '.gemini');
+    const file = path.join(dir, 'settings.json');
+    const settings = readJsonFile(file);
+    settings.hooks = settings.hooks || {};
+    const before = (settings.hooks.BeforeTool = settings.hooks.BeforeTool || []);
+    const after = (settings.hooks.AfterTool = settings.hooks.AfterTool || []);
+    let changed = false;
+    if (!hasGroupedHook(before, 'tool-guard')) {
+      before.push({ matcher: '.*', hooks: [{ type: 'command', command: hookCommand('tool-guard --agent gemini') }] });
+      changed = true;
+    }
+    if (!hasGroupedHook(after, 'result-guard')) {
+      after.push({ matcher: '.*', hooks: [{ type: 'command', command: hookCommand('result-guard --agent gemini') }] });
+      changed = true;
+    }
+    if (changed) {
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(file, JSON.stringify(settings, null, 2));
+    }
+    return { file, changed };
+  },
+
+  cursor(global) {
+    const dir = global ? path.join(os.homedir(), '.cursor') : path.join(process.cwd(), '.cursor');
+    const file = path.join(dir, 'hooks.json');
+    const cfg = readJsonFile(file);
+    if (cfg.version === undefined) cfg.version = 1;
+    cfg.hooks = cfg.hooks || {};
+    let changed = false;
+    const wire = (event, command) => {
+      const list = (cfg.hooks[event] = cfg.hooks[event] || []);
+      if (!hasFlatHook(list)) {
+        list.push({ command });
+        changed = true;
+      }
+    };
+    wire('beforeShellExecution', hookCommand('tool-guard --agent cursor'));
+    wire('beforeMCPExecution', hookCommand('tool-guard --agent cursor'));
+    wire('afterFileEdit', hookCommand('result-guard --agent cursor'));
+    wire('afterMCPExecution', hookCommand('result-guard --agent cursor'));
+
+    wire('beforeSubmitPrompt', hookCommand('prompt-guard --agent cursor'));
+    if (changed) {
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(file, JSON.stringify(cfg, null, 2));
+    }
+    return { file, changed };
+  },
+
+  windsurf(global) {
+    const dir = global ? path.join(os.homedir(), '.codeium', 'windsurf') : path.join(process.cwd(), '.windsurf');
+    const file = path.join(dir, 'hooks.json');
+    const cfg = readJsonFile(file);
+    cfg.hooks = cfg.hooks || {};
+    let changed = false;
+    const wire = (event, command) => {
+      const list = (cfg.hooks[event] = cfg.hooks[event] || []);
+      if (!hasFlatHook(list)) {
+        list.push({ command });
+        changed = true;
+      }
+    };
+    wire('pre_run_command', hookCommand('tool-guard --agent windsurf'));
+    wire('pre_write_code', hookCommand('tool-guard --agent windsurf'));
+    wire('pre_mcp_tool_use', hookCommand('tool-guard --agent windsurf'));
+    wire('post_mcp_tool_use', hookCommand('result-guard --agent windsurf'));
+    if (changed) {
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(file, JSON.stringify(cfg, null, 2));
+    }
+    return { file, changed };
+  },
+
+  copilot(global) {
+    const dir = global ? path.join(os.homedir(), '.copilot', 'hooks') : path.join(process.cwd(), '.github', 'hooks');
+    const file = path.join(dir, 'shomra.json');
+    if (fs.existsSync(file)) return { file, changed: false };
+    const cfg = {
+      preToolUse: [{ command: hookCommand('tool-guard --agent copilot') }],
+      postToolUse: [{ command: hookCommand('result-guard --agent copilot') }],
+    };
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(cfg, null, 2));
+    return { file, changed: true };
+  },
+
+  cline(global) {
+    const dir = global ? path.join(os.homedir(), '.cline') : path.join(process.cwd(), '.cline');
+    const file = path.join(dir, 'hooks.json');
+    const settings = readJsonFile(file);
+    settings.hooks = settings.hooks || {};
+    const pre = (settings.hooks.PreToolUse = settings.hooks.PreToolUse || []);
+    const post = (settings.hooks.PostToolUse = settings.hooks.PostToolUse || []);
+    let changed = false;
+    if (!hasGroupedHook(pre, 'tool-guard')) {
+      pre.push({ matcher: 'execute_command|write_to_file|replace_in_file|new_rule|use_mcp_tool', hooks: [{ type: 'command', command: hookCommand('tool-guard --agent cline') }] });
+      changed = true;
+    }
+    if (!hasGroupedHook(post, 'result-guard')) {
+      post.push({ matcher: 'read_file|web_fetch|use_mcp_tool', hooks: [{ type: 'command', command: hookCommand('result-guard --agent cline') }] });
+      changed = true;
+    }
+    if (changed) {
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(file, JSON.stringify(settings, null, 2));
+    }
+    return { file, changed };
+  },
+
+  aider(global) {
+    const file = global ? path.join(os.homedir(), '.aider.conf.yml') : path.join(process.cwd(), '.aider.conf.yml');
+    let text = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+    if (/#\s*shomra llm guard/i.test(text) || text.includes(LLM_PROXY_BASE)) {
+      return { file, changed: false };
+    }
+    const block =
+      `\n# --- shomra llm guard ---\n` +
+      `# Routes Aider's model traffic through the Shomra LLM Guard proxy so every\n` +
+      `# prompt/response is policy-screened. Requires: shomra llm-proxy (running).\n` +
+      `openai-api-base: ${LLM_PROXY_BASE}\n` +
+      `# --- end shomra ---\n`;
+    fs.writeFileSync(file, (text.endsWith('\n') || !text ? text : text + '\n') + block);
+    return { file, changed: true };
+  },
+};

package/src/artifacts/matchers.mjs

@@ -0,0 +1,59 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const ARTIFACT_MATCHERS = [
+  { kind: 'mcp', re: /(^|\/)\.?mcp\.json$/i },
+  { kind: 'mcp', re: /(^|\/)\.(vscode|cursor)\/mcp\.json$/i },
+  { kind: 'skill', re: /(^|\/)SKILL\.md$/i },
+  { kind: 'command', re: /(^|\/)\.claude\/commands\/[^/]+\.md$/i },
+  { kind: 'subagent', re: /(^|\/)\.claude\/agents\/[^/]+\.md$/i },
+  { kind: 'hook', re: /(^|\/)\.claude\/settings(\.local)?\.json$/i },
+
+  { kind: 'hook', re: /(^|\/)\.cursor\/hooks\.json$/i },
+  { kind: 'hook', re: /(^|\/)(\.windsurf|\.codeium\/windsurf)\/hooks\.json$/i },
+  { kind: 'hook', re: /(^|\/)\.gemini\/settings\.json$/i },
+  { kind: 'hook', re: /(^|\/)\.cline\/hooks\.json$/i },
+  { kind: 'hook', re: /(^|\/)\.codex\/hooks\.json$/i },
+  { kind: 'hook', re: /(^|\/)(\.github|\.copilot)\/hooks\/[^/]+\.json$/i },
+  { kind: 'hook', re: /(^|\/)\.aider\.conf\.yml$/i },
+  { kind: 'agent-card', re: /(^|\/)\.well-known\/agent(-card)?\.json$/i },
+  { kind: 'agent-card', re: /(^|\/)agent[-_]card\.json$/i },
+  { kind: 'rules', re: /(^|\/)(CLAUDE|AGENTS|GEMINI|CONVENTIONS)\.md$/i },
+  { kind: 'rules', re: /(^|\/)\.(cursorrules|windsurfrules|clinerules|aiderrules|continuerules|goosehints)$/i },
+  { kind: 'rules', re: /(^|\/)\.github\/copilot-instructions\.md$/i },
+  { kind: 'rules', re: /(^|\/)\.cursor\/rules\/[^/]+\.mdc$/i },
+
+  { kind: 'env', re: /(^|\/)\.env(\.(local|development|dev|production|prod|staging|stage|test))?$/i },
+  { kind: 'memory', re: /(^|\/)MEMORY\.md$/i },
+  { kind: 'memory', re: /(^|\/)(mem0|letta_memory|memgpt_memory)\.json$/i },
+  { kind: 'memory', re: /(^|\/)(\.mem0|\.letta|\.memgpt|memory)\/[^/]+\.(md|json)$/i },
+];
+
+export const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'out', 'vendor', '.venv', '__pycache__']);
+
+export const MAX_ARTIFACT_BYTES = 1_000_000;
+
+export function walkArtifacts(root) {
+  const found = [];
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const ent of entries) {
+      const full = path.join(dir, ent.name);
+      if (ent.isDirectory()) {
+        if (!SKIP_DIRS.has(ent.name)) stack.push(full);
+        continue;
+      }
+      const rel = path.relative(root, full).split(path.sep).join('/');
+      const match = ARTIFACT_MATCHERS.find((m) => m.re.test(rel));
+      if (match) found.push({ full, rel, kind: match.kind });
+    }
+  }
+  return found;
+}

package/src/artifacts/report.mjs

@@ -0,0 +1,50 @@
+import path from 'node:path';
+import { bold, cyan, dim, gray, yellow } from '../core/terminal.mjs';
+import { rollupArtifacts } from '../inventory/agent-artifacts.mjs';
+
+export function printAssets(assets) {
+  const byType = {};
+  for (const a of assets) byType[a.type] = (byType[a.type] ?? 0) + 1;
+  console.log(bold('\n  Discovered AI assets'));
+  console.log(
+    '  ' +
+      Object.entries(byType)
+        .map(([t, n]) => `${cyan(n)} ${dim(t.replace('_', ' ').toLowerCase())}`)
+        .join(dim('  ·  ')),
+  );
+  for (const a of assets) {
+    console.log(`  ${gray('•')} ${bold(a.name)} ${dim(a.type)} ${a.vendor ? gray('(' + a.vendor + ')') : ''}`);
+    if (a.identifier && a.identifier !== a.name) console.log(`      ${dim(a.identifier)}`);
+  }
+}
+
+export function printArtifacts(artifacts, capped = [], available = []) {
+  if (!artifacts.length && !capped.length && !available.length) return;
+  const by = rollupArtifacts(artifacts);
+  console.log(bold('\n  Installed agent artifacts'));
+  console.log(
+    '  ' +
+      (Object.keys(by).length
+        ? Object.entries(by)
+            .map(([k, n]) => `${cyan(n)} ${dim(k + (n === 1 ? '' : 's'))}`)
+            .join(dim('  ·  '))
+        : dim('none found')),
+  );
+  for (const a of artifacts) {
+    const scope = a.scope === 'user' ? yellow('user') : dim('project');
+    console.log(`  ${gray('•')} ${bold(a.name)} ${dim(a.kind)} ${scope} ${a.vendor ? gray('(' + a.vendor + ')') : ''}`);
+    console.log(`      ${dim(a.path)}`);
+    if (a.files?.length) console.log(`      ${dim(a.files.length + ' bundled file(s)')}`);
+  }
+  if (available.length) {
+    const total = available.reduce((n, a) => n + a.count, 0);
+
+    console.log(
+      dim(`\n  ${total} more available in ${available.length} checked-out catalogue(s), none enabled:`),
+    );
+    for (const a of available) console.log(`      ${dim(a.marketplace)} ${gray(a.count)}`);
+  }
+  if (capped.length) {
+    console.log(dim(`\n  Sweep capped (${capped.length}) - this list is a floor, not a total.`));
+  }
+}

package/src/cli/flags.mjs

@@ -0,0 +1,68 @@
+const BOOLEAN_FLAGS = new Set([
+  'strict', 'json', 'sarif', 'fix', 'staged', 'changed', 'all', 'history', 'force',
+  'apply', 'dry-run', 'global', 'local', 'trailer', 'evolve', 'report', 'init',
+  'no-suppress', 'no-baseline', 'no-policy', 'no-index', 'adaptive',
+  'fail-on-regression', 'fail-on-blocked', 'write', 'yes', 'stdin', 'quiet', 'help',
+  'check', 'checklist', 'pre-receive', 'uninstall', 'save', 'list',
+]);
+
+const VALUE_FLAGS = new Set([
+  'key', 'url', 'path', 'kind', 'name', 'project', 'agent', 'agent-id', 'min',
+  'scenarios', 'objectives', 'turns', 'target', 'run', 'port', 'config', 'env',
+  'command', 'base', 'repo', 'pr', 'token', 'sha', 'session', 'since', 'depth',
+  'scope', 'writer', 'type', 'slug', 'framework', 'chunk-size', 'manifest',
+
+  'fail-on',
+
+  'subject', 'title', 'note', 'actor',
+
+  'input',
+]);
+
+export const KNOWN_FLAGS = new Set([...BOOLEAN_FLAGS, ...VALUE_FLAGS]);
+
+const REPEATABLE_FLAGS = new Set(['input']);
+
+function setFlag(flags, name, value) {
+  if (!REPEATABLE_FLAGS.has(name)) {
+    flags[name] = value;
+    return;
+  }
+  const prev = flags[name];
+  flags[name] = prev === undefined ? value : [].concat(prev, value);
+}
+
+export function parseFlags(argv) {
+  const flags = {};
+  const positional = [];
+  const unknown = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const body = a.slice(2);
+
+      const eq = body.indexOf('=');
+      if (eq !== -1) {
+        const name = body.slice(0, eq);
+        if (!KNOWN_FLAGS.has(name)) unknown.push(name);
+        setFlag(flags, name, body.slice(eq + 1));
+        continue;
+      }
+      if (!KNOWN_FLAGS.has(body)) {
+        unknown.push(body);
+        flags[body] = true;
+        continue;
+      }
+      if (BOOLEAN_FLAGS.has(body)) {
+        flags[body] = true;
+        continue;
+      }
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith('--')) {
+        setFlag(flags, body, next);
+        i++;
+      } else flags[body] = true;
+    } else positional.push(a);
+  }
+  return { flags, positional, unknown };
+}