@shomra/agent 0.3.17 → 0.3.18

package/src/commands/mcp.mjs

@@ -0,0 +1,143 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { SELF_PATH } from '../agents/hook-command.mjs';
+import { EXIT_USAGE } from '../core/exit-codes.mjs';
+import { bold, dim, green, red, yellow } from '../core/terminal.mjs';
+import { MCP_HOST_CONFIGS, MCP_HOST_KEYS, shomraMcpEntry } from '../mcp/hosts.mjs';
+import { runMcpServer } from '../mcp/server.mjs';
+import { cmdMcpAdd, cmdMcpList } from './mcp-add.mjs';
+
+function cmdMcpInstall(flags) {
+  const requested = flags.agent
+    ? String(flags.agent).toLowerCase().split(',').map((s) => s.trim()).filter(Boolean)
+    : MCP_HOST_KEYS;
+  if (requested.includes('all')) requested.splice(0, requested.length, ...MCP_HOST_KEYS);
+  const bad = requested.filter((a) => !MCP_HOST_CONFIGS[a]);
+  if (bad.length) {
+    console.error(red('✗') + ` No MCP config is known for: ${bad.join(', ')}. Supported: ${MCP_HOST_KEYS.join(', ')}, all.`);
+    process.exit(EXIT_USAGE);
+  }
+
+  const global = !!flags.global;
+  const entry = shomraMcpEntry();
+  const out = [];
+
+  for (const key of requested) {
+    const host = MCP_HOST_CONFIGS[key];
+    const file = global ? host.global() : host.local();
+    let cfg = {};
+    if (fs.existsSync(file)) {
+      try { cfg = JSON.parse(fs.readFileSync(file, 'utf8')); } catch {
+        console.log(`  ${red('✗')} ${host.label} ${dim('- ' + file + ' is not valid JSON; fix or move it first.')}`);
+        out.push({ agent: key, file, changed: false, error: 'invalid json' });
+        continue;
+      }
+    }
+    cfg.mcpServers = cfg.mcpServers || {};
+    const before = JSON.stringify(cfg.mcpServers.shomra || null);
+    cfg.mcpServers.shomra = entry;
+    const changed = before !== JSON.stringify(entry);
+    if (changed) {
+      try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(cfg, null, 2) + '\n');
+      } catch (e) {
+        console.log(`  ${red('✗')} ${host.label} ${dim('- ' + e.message)}`);
+        out.push({ agent: key, file, changed: false, error: e.message });
+        continue;
+      }
+    }
+    out.push({ agent: key, file, changed });
+    if (!flags.json) {
+      if (changed) console.log(`  ${green('✓')} Registered the Shomra MCP server for ${bold(host.label)} ${dim('→ ' + file)}`);
+      else console.log(`  ${yellow('•')} ${host.label} ${dim('already registered (' + file + ')')}`);
+    }
+  }
+
+  if (flags.json) { console.log(JSON.stringify({ scope: global ? 'global' : 'project', installed: out }, null, 2)); return; }
+  console.log(dim('\n  The agent can now call Shomra in its own loop: ') + bold('shomra_review_change') + dim(' (gate content BEFORE writing it),'));
+  console.log(dim('  ') + bold('shomra_rules') + dim(' (what will be refused here), plus check / explain / fix / scan_models.'));
+  console.log(dim('  Restart the agent to pick up the new server.'));
+  if (!global) {
+
+    console.log(dim('  Note: the entry holds absolute paths for THIS machine. If you commit it, teammates should'));
+    console.log(dim('        run ') + bold('shomra mcp install') + dim(' themselves rather than rely on the committed path.'));
+  }
+  console.log('');
+}
+
+export async function cmdMcpGuard(flags, positional) {
+  const { runMcpShim } = await import('../mcp/shim.mjs');
+  return runMcpShim(flags, positional);
+}
+
+async function cmdMcpGuardInstall(flags) {
+  const { wrapMcpConfig, unwrapMcpConfig, mcpConfigCandidates } = await import('../mcp/shim.mjs');
+  const undo = !!flags.uninstall;
+  const files = flags.config
+    ? [{ label: 'config', file: path.resolve(String(flags.config)) }]
+    : mcpConfigCandidates();
+
+  if (!files.length) {
+    console.log(dim('\n  No MCP client config found on this machine. Nothing to guard.\n'));
+    return;
+  }
+
+  const results = [];
+  for (const { label, file } of files) {
+    let cfg;
+    try {
+      cfg = JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch (e) {
+      console.log(`  ${red('✗')} ${label} ${dim('- ' + file + ' is not valid JSON; fix or move it first.')}`);
+      results.push({ file, error: 'invalid json' });
+      continue;
+    }
+    const before = JSON.stringify(cfg);
+    const out = undo ? unwrapMcpConfig(cfg, SELF_PATH) : wrapMcpConfig(cfg, SELF_PATH, process.execPath);
+    const changed = JSON.stringify(cfg) !== before;
+    if (changed) {
+      try {
+
+        const bak = file + '.shomra-backup';
+        if (!undo && !fs.existsSync(bak)) fs.writeFileSync(bak, before);
+        fs.writeFileSync(file, JSON.stringify(cfg, null, 2) + '\n');
+      } catch (e) {
+        console.log(`  ${red('✗')} ${label} ${dim('- ' + e.message)}`);
+        results.push({ file, error: e.message });
+        continue;
+      }
+    }
+    results.push({ file, label, ...out, changed });
+    if (!flags.json) {
+      const names = undo ? out.restored : out.wrapped;
+      if (names.length) console.log(`  ${green('✓')} ${bold(label)} ${dim('- ' + (undo ? 'restored ' : 'guarded ') + names.join(', '))}`);
+      else console.log(`  ${yellow('•')} ${label} ${dim('- nothing to ' + (undo ? 'restore' : 'guard'))}`);
+      for (const s of out.skipped ?? []) console.log(`    ${dim('· ' + s.name + ' - ' + s.why)}`);
+    }
+  }
+
+  if (flags.json) { console.log(JSON.stringify({ mode: undo ? 'uninstall' : 'install', results }, null, 2)); return; }
+  if (!undo) {
+    console.log(dim('\n  Every stdio MCP server now starts through Shomra: a DENIED / REVOKED / QUARANTINED'));
+    console.log(dim('  server is refused before its process exists, and poisoned tool descriptions are'));
+    console.log(dim('  withheld from the model at tools/list rather than at the first call.'));
+    console.log(dim('  Restart the agent to pick up the change. Undo: ') + bold('shomra mcp guard --uninstall') + '\n');
+  } else {
+    console.log(dim('\n  Original launch lines restored. Restart the agent.\n'));
+  }
+}
+
+export async function cmdMcp(flags, positional) {
+  const sub = String(positional[0] || '').toLowerCase();
+  if (sub === 'guard') return cmdMcpGuardInstall(flags);
+  if (sub === 'serve') return runMcpServer(flags);
+  if (sub === 'install') return cmdMcpInstall(flags);
+
+  const configFile = path.resolve(flags.config ? String(flags.config) : '.mcp.json');
+  if (sub === 'list') return cmdMcpList(flags, configFile);
+  if (sub === 'add') return cmdMcpAdd(flags, positional, configFile);
+
+  console.error(red('✗') + ` Usage: ${bold('shomra mcp add <name> <command…> | --url <url>')} ${dim('|')} ${bold('shomra mcp list')}`);
+  process.exit(EXIT_USAGE);
+}

package/src/commands/memory-scan.mjs

@@ -0,0 +1,181 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { MAX_ARTIFACT_BYTES, SKIP_DIRS } from '../artifacts/matchers.mjs';
+import { api } from '../core/api-client.mjs';
+import { guardTimeoutMs } from '../core/circuit-breaker.mjs';
+import { loadConfig, resolveSettings } from '../core/config.mjs';
+import { EXIT_USAGE, exitNotConfigured } from '../core/exit-codes.mjs';
+import { SEV_COLOR, VERDICT_COLOR, bold, cyan, dim, gray, green, red, yellow } from '../core/terminal.mjs';
+
+const MEMORY_MATCHERS = [
+  /(^|\/)MEMOR(Y|IES)\.(md|json|jsonl|txt)$/i,
+  /(^|\/)memor(y|ies)\/[^/]+\.(md|mdx|json|jsonl|txt|ya?ml)$/i,
+  /(^|\/)\.(mem0|letta|memgpt)\/[^/]+\.(md|json|jsonl|txt)$/i,
+];
+
+const INSTRUCTION_MATCHERS = [
+  /(^|\/)(CLAUDE|AGENTS?|GEMINI|CONVENTIONS)\.md$/i,
+  /(^|\/)LLMS(-FULL)?\.txt$/i,
+  /(^|\/)\.(cursorrules|windsurfrules|clinerules|aiderrules|continuerules|goosehints)$/i,
+  /(^|\/)\.github\/copilot-instructions\.md$/i,
+  /(^|\/)copilot-instructions\.md$/i,
+  /(^|\/)\.cursor\/rules\/.+\.mdc$/i,
+  /(^|\/)\.clinerules\/.+\.md$/i,
+];
+
+export function isMemoryPath(p) {
+  const rel = String(p || '').split(path.sep).join('/');
+  return MEMORY_MATCHERS.some((re) => re.test(rel)) || INSTRUCTION_MATCHERS.some((re) => re.test(rel));
+}
+
+function walkMemoryFiles(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('/');
+      if (isMemoryPath(rel) || isMemoryPath(full)) found.push({ full, rel });
+    }
+  }
+  return found;
+}
+
+export async function reportMemoryWrite(url, apiKey, body) {
+  try {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), guardTimeoutMs());
+    await fetch(`${url}/memory/ingest`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'X-Shomra-Key': apiKey, Connection: 'close' },
+      body: JSON.stringify(body),
+      signal: ctrl.signal,
+    });
+    clearTimeout(timer);
+  } catch {
+
+  }
+}
+
+const NO_STORES_HINT = '(Looked for MEMORY.md, memory/ dirs, .mem0/.letta stores, and rules files: CLAUDE.md, AGENTS.md, .cursorrules, copilot-instructions.md, …)';
+
+function resolveMemoryTarget(positional) {
+  const argument = positional[0] || '.';
+  const target = path.resolve(String(argument));
+  if (!fs.existsSync(target)) {
+    console.error(`${red('✗')} Not found: ${argument}`);
+    process.exit(EXIT_USAGE);
+  }
+  return fs.statSync(target).isDirectory()
+    ? { target, files: walkMemoryFiles(target) }
+    : { target, files: [{ full: target, rel: path.basename(target) }] };
+}
+
+function readStoreContent(file, flags) {
+  try {
+    if (fs.statSync(file.full).size > MAX_ARTIFACT_BYTES) {
+      if (!flags.json) console.log(`  ${gray('•')} ${dim(file.rel)} ${yellow('skipped (too large)')}`);
+      return null;
+    }
+    return fs.readFileSync(file.full, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function worseVerdict(current, next) {
+  if (current === 'FAIL' || next === 'FAIL') return 'FAIL';
+  if (current === 'REVIEW' || next === 'REVIEW') return 'REVIEW';
+  return 'PASS';
+}
+
+function printStore(file, report) {
+  const verdict = report?.store?.verdict || 'PASS';
+  const colour = VERDICT_COLOR[verdict] || gray;
+  const poisonScore = report?.store?.poisonScore ?? 0;
+  const anomalous = report?.provenance?.anomalous;
+
+  const quarantineNote = report?.quarantined ? ` ${red('QUARANTINED')}` : '';
+  const provenanceNote = anomalous ? ` ${red('OUT-OF-BAND WRITE')}` : '';
+  console.log(`\n  ${colour('●')} ${bold(path.basename(file.rel))} ${dim(file.rel)} ${colour(verdict)} ${dim(`poison ${poisonScore}/100`)}${quarantineNote}${provenanceNote}`);
+
+  for (const finding of (report?.analysis?.findings || []).filter((f) => f.severity !== 'INFO')) {
+    console.log(`      ${SEV_COLOR[finding.severity](String(finding.severity).padEnd(8))} ${finding.title}`);
+  }
+  if (anomalous) console.log(`      ${red('provenance:')} ${dim(report.provenance.reason)}`);
+}
+
+function summaryLine(worst) {
+  if (worst === 'FAIL') return red('✗ Memory poisoning detected - roll back the affected stores.');
+  if (worst === 'REVIEW') return yellow('⚠ Review the flagged memory before the agent reloads it.');
+  return green('✓ No memory poisoning found.');
+}
+
+export async function cmdMemoryScan(flags, positional) {
+  const { apiKey, url } = resolveSettings(loadConfig());
+  if (!apiKey) exitNotConfigured();
+
+  const { target, files } = resolveMemoryTarget(positional);
+  if (!files.length) {
+    if (flags.json) console.log(JSON.stringify({ scanned: 0, stores: [] }, null, 2));
+    else console.log(dim(`\n  No memory or rules files found under ${target}.\n  ${NO_STORES_HINT}\n`));
+    return;
+  }
+
+  const ingestFields = {
+    scope: flags.scope ? String(flags.scope).toLowerCase() : undefined,
+    writer: flags.writer ? String(flags.writer).toUpperCase() : 'AGENT',
+    actor: `${os.hostname()}/${os.userInfo().username}`,
+    source: 'shomra memory-scan',
+    ...(flags.project ? { projectId: String(flags.project) } : {}),
+  };
+
+  if (!flags.json) {
+    console.log(bold(cyan('\n  Shomra Memory Integrity')) + dim(` - scanning ${files.length} store${files.length > 1 ? 's' : ''}`));
+  }
+
+  let worst = 'PASS';
+  const stores = [];
+  for (const file of files) {
+    const content = readStoreContent(file, flags);
+    if (content == null) continue;
+
+    let report;
+    try {
+      report = await api(url, apiKey, '/memory/ingest', {
+        ...ingestFields,
+        path: file.rel,
+        name: path.basename(file.rel),
+        content,
+      });
+    } catch (error) {
+      console.error(`  ${red('✗')} ${file.rel} ${red(`ingest error: ${error.message}`)}`);
+      continue;
+    }
+
+    worst = worseVerdict(worst, report?.store?.verdict || 'PASS');
+    stores.push({ path: file.rel, ...report });
+    if (!flags.json) printStore(file, report);
+  }
+
+  if (flags.json) {
+    console.log(JSON.stringify({ scanned: stores.length, worst, stores }, null, 2));
+  } else {
+    console.log(`\n  ${summaryLine(worst)}${dim(' Full timeline + rollback in the Shomra dashboard → Memory.\n')}`);
+  }
+
+  if (worst === 'FAIL') process.exitCode = 1;
+  else if (worst === 'REVIEW' && flags.strict) process.exitCode = 2;
+}

package/src/commands/model-scan.mjs

@@ -0,0 +1,99 @@
+import os from 'node:os';
+import { api } from '../core/api-client.mjs';
+import { loadConfig, resolveSettings } from '../core/config.mjs';
+import { EXIT_USAGE, exitNotConfigured } from '../core/exit-codes.mjs';
+import { SEV_COLOR, VERDICT_COLOR, bold, dim, gray, green, red, yellow } from '../core/terminal.mjs';
+import { modelLookup, printAlternatives } from '../models/lookup.mjs';
+
+const USAGE = 'shomra model-scan <hf-url | owner/model | github-url> [--project <id>] [--json]';
+
+async function requestModelScan({ url, apiKey, target, flags }) {
+  if (!flags.json) process.stdout.write(dim(`\n  Scanning ${target}… `));
+  try {
+    const report = await api(url, apiKey, '/projects/agent-model-scan', {
+      target: String(target),
+      actor: `${os.hostname()}/${os.userInfo().username}`,
+      ...(flags.project ? { projectId: String(flags.project) } : {}),
+    });
+    if (!flags.json) console.log(green('done'));
+    return report;
+  } catch (error) {
+    if (!flags.json) console.log(red('failed'));
+    console.error(`  ${red('✗')} ${error.message}\n`);
+    return process.exit(1);
+  }
+}
+
+function printAssetVulnerabilities(report) {
+  for (const asset of report.assets || []) {
+    const vulnerabilities = (asset.vulnerabilities || []).filter((v) => v.severity !== 'INFO');
+    if (!vulnerabilities.length) continue;
+
+    console.log(`\n  ${bold(asset.name)} ${dim(`(${asset.assetType})`)}`);
+    for (const vulnerability of vulnerabilities) {
+      console.log(`    ${SEV_COLOR[vulnerability.severity](String(vulnerability.severity).padEnd(8))} ${vulnerability.title}`);
+      const evidence = vulnerability.evidence?.analysis === 'sast' ? vulnerability.evidence : null;
+      if (!evidence) continue;
+      const source = evidence.source ? ` · source ${evidence.source}` : '';
+      console.log(`        ${dim(`${evidence.ruleId} · ${evidence.file}:${evidence.line} · sink ${evidence.sink}${source}`)}`);
+      if (evidence.snippet) console.log(`        ${gray(evidence.snippet)}`);
+    }
+  }
+}
+
+async function printSaferAlternatives(url, report, target) {
+  if (report.verdict !== 'FAIL' && report.verdict !== 'REVIEW') return;
+  const modelId = hfModelIdFromTarget(String(report.target || target));
+  if (!modelId) return;
+
+  try {
+    const lookup = await modelLookup(url, modelId);
+    if (!Array.isArray(lookup?.alternatives) || !lookup.alternatives.length) return;
+    console.log(`\n  ${bold('Safer alternatives')}${dim(' (same category, lower risk):')}`);
+    printAlternatives(lookup.alternatives, 'model', '    ');
+  } catch {
+    return;
+  }
+}
+
+function summaryLine(verdict) {
+  if (verdict === 'FAIL') return red('✗ Do not load this model unreviewed.');
+  if (verdict === 'REVIEW') return yellow('⚠ Review the findings above before trusting this model.');
+  return green('✓ No high-severity issues found.');
+}
+
+export async function cmdModelScan(flags, positional) {
+  const { apiKey, url } = resolveSettings(loadConfig());
+  if (!apiKey) exitNotConfigured();
+
+  const target = positional[0];
+  if (!target) {
+    console.error(`${red('✗')} Usage: ${bold(USAGE)}`);
+    process.exit(EXIT_USAGE);
+  }
+
+  const report = await requestModelScan({ url, apiKey, target, flags });
+
+  if (flags.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    const colour = VERDICT_COLOR[report.verdict] || gray;
+    console.log(`\n  ${bold(report.target || target)} ${dim(`· ${report.scanType} scan`)}`);
+    console.log(`  ${colour('●')} ${colour(bold(report.verdict))} ${dim(`risk ${report.riskScore}/100 · ${report.vulnCount} finding(s) · ${report.criticalCount} critical · ${report.highCount} high`)}`);
+
+    printAssetVulnerabilities(report);
+    await printSaferAlternatives(url, report, target);
+    console.log(`\n  ${summaryLine(report.verdict)}${dim(' Full report in the Shomra dashboard → Projects.\n')}`);
+  }
+
+  if (report.verdict === 'FAIL') process.exitCode = 1;
+  else if (report.verdict === 'REVIEW' && flags.strict) process.exitCode = 2;
+}
+
+function hfModelIdFromTarget(target) {
+  const t = String(target || '').trim();
+  const hf = t.match(/huggingface\.co\/([^/\s?#]+\/[^/\s?#]+)/i);
+  if (hf) return hf[1];
+  if (/^[\w.-]+\/[\w.-]+$/.test(t) && !/github\.com/i.test(t)) return t;
+  return null;
+}

package/src/commands/models.mjs

@@ -0,0 +1,145 @@
+import path from 'node:path';
+import { loadConfig, resolveSettings } from '../core/config.mjs';
+import { clampInt } from '../core/numbers.mjs';
+import { SEV_COLOR, bold, cyan, dim, gray, green, red, yellow } from '../core/terminal.mjs';
+import { printAlternatives } from '../models/lookup.mjs';
+import { assessModel, collectModelReferences, lookupModels, resolveScanScope } from '../models/references.mjs';
+import { walkFiles } from './secrets.mjs';
+
+const DEFAULT_CONCURRENCY = 6;
+const MIN_CONCURRENCY = 1;
+const MAX_CONCURRENCY = 16;
+const MAX_LOCATIONS_SHOWN = 3;
+const MAX_FINDINGS_SHOWN = 3;
+
+function lookupUrl(url, reference) {
+  const query = `id=${encodeURIComponent(reference.id)}${reference.sha ? `&sha=${reference.sha}` : ''}`;
+  return `${url}/models/lookup?${query}`;
+}
+
+function printNothingFound(flags, root) {
+  if (flags.json) {
+    console.log(JSON.stringify({ detected: 0, models: [] }, null, 2));
+    return;
+  }
+  const where = path.relative(process.cwd(), root).split(path.sep).join('/') || '.';
+  console.log(`${green('\n  ✓ No AI model references found in the code.')}${dim(` (looked under ${where})`)}\n`);
+}
+
+function printDryRun(flags, references, url) {
+  if (flags.json) {
+    console.log(JSON.stringify({
+      detected: references.length,
+      models: references.map((reference) => ({
+        id: reference.id,
+        sha: reference.sha,
+        source: reference.source,
+        lookup: lookupUrl(url, reference),
+        locations: reference.locations,
+      })),
+    }, null, 2));
+    return;
+  }
+  console.log(bold(cyan('\n  Shomra models')) + dim(` - ${references.length} reference(s) detected (dry run - no lookup)`));
+  for (const reference of references) {
+    const revision = reference.sha ? dim(`@${reference.sha}`) : '';
+    console.log(`  ${gray('•')} ${bold(reference.id)}${revision} ${dim(`(${reference.source})`)} ${dim(`→ ${url}/models/lookup?id=${reference.id}`)}`);
+  }
+  console.log('');
+}
+
+function statusLabel(model) {
+  if (model.error) return yellow('lookup failed');
+  if (model.notIndexed) {
+    return dim(model.source === 'ollama' ? 'local runtime - not in the index' : 'not in the index yet');
+  }
+  const verdictColour = model.verdict === 'FAIL' ? red : model.verdict === 'REVIEW' ? yellow : green;
+  return `${verdictColour(model.verdict)} ${dim(`risk ${model.riskScore} · ${model.findingCount} vuln(s)`)}`;
+}
+
+function alertMark(model) {
+  if (model.alert === 'BLOCK') return red('●');
+  if (model.alert === 'FLAG') return yellow('●');
+  return model.notIndexed ? gray('○') : green('●');
+}
+
+function printModel(model) {
+  const revision = model.sha ? dim(`@${String(model.sha).slice(0, 12)}`) : '';
+  console.log(`  ${alertMark(model)} ${bold(model.id)}${revision} ${dim(`(${model.source})`)}  ${statusLabel(model)}`);
+
+  const shown = model.locations.slice(0, MAX_LOCATIONS_SHOWN).map((l) => `${l.file}:${l.line}`).join(', ');
+  const more = model.locations.length > MAX_LOCATIONS_SHOWN ? ` (+${model.locations.length - MAX_LOCATIONS_SHOWN})` : '';
+  console.log(`      ${dim(`used in ${shown}${more}`)}`);
+
+  for (const finding of model.findings.slice(0, MAX_FINDINGS_SHOWN)) {
+    console.log(`      ${(SEV_COLOR[finding.severity] || dim)(String(finding.severity).padEnd(8))} ${finding.title}`);
+  }
+  printAlternatives(model.alternatives, 'model');
+
+  if (model.notIndexed && model.source !== 'ollama') {
+    console.log(`      ${dim('→ scan it now:')} ${bold(`shomra model-scan ${model.id}`)}`);
+  }
+}
+
+function uncheckedNotice(models, url) {
+  const failed = models.filter((model) => model.error).length;
+  if (!failed) return null;
+  const why = url ? ' (model index unreachable)' : ' (no backend configured - set SHOMRA_URL)';
+  return yellow(`⚠ ${failed} model reference(s) could not be checked`) + dim(why);
+}
+
+function summaryLine({ models, blocked, flagged, url }) {
+  const unchecked = uncheckedNotice(models, url);
+  const suffix = unchecked ? ` · ${unchecked}` : '';
+  if (blocked) return red(`✗ ${blocked} vulnerable`) + dim(` · ${flagged} to review`) + suffix;
+  if (flagged) return yellow(`⚠ ${flagged} to review`) + suffix;
+  return unchecked || green('✓ No known-vulnerable models');
+}
+
+function printReport({ models, blocked, flagged, url, indexUnreachable }) {
+  const indexNote = url ? ` · index at ${url}` : ' · local detection only';
+  console.log(bold(cyan('\n  Shomra models')) + dim(` - ${models.length} model reference(s)${indexNote}`));
+
+  if (indexUnreachable) {
+    const why = url
+      ? 'Model index unreachable - could not fetch vulnerability info.'
+      : 'Model index not configured - set SHOMRA_URL to check models against the Shomra Model Index.';
+    console.log(`  ${yellow('⚠')} ${dim(why)}`);
+  }
+
+  for (const model of models) printModel(model);
+  console.log(`\n  ${summaryLine({ models, blocked, flagged, url })}\n`);
+}
+
+export async function cmdModels(flags, positional) {
+  const { url } = resolveSettings(loadConfig());
+  const target = path.resolve(positional[0] || flags.path || '.');
+
+  const { root, entries } = resolveScanScope(target, walkFiles);
+  const references = collectModelReferences(root, entries);
+
+  if (!references.length) {
+    printNothingFound(flags, root);
+    return;
+  }
+  if (flags['dry-run']) {
+    printDryRun(flags, references, url);
+    return;
+  }
+
+  const concurrency = clampInt(process.env.SHOMRA_GATE_CONCURRENCY, DEFAULT_CONCURRENCY, MIN_CONCURRENCY, MAX_CONCURRENCY);
+  const { results, indexUnreachable } = await lookupModels(url, references, concurrency);
+  const models = references.map((reference, index) => assessModel(reference, results[index]));
+
+  const blocked = models.filter((model) => model.alert === 'BLOCK').length;
+  const flagged = models.filter((model) => model.alert === 'FLAG').length;
+
+  if (flags.json) {
+    console.log(JSON.stringify({ detected: models.length, blocked, flagged, apiDown: indexUnreachable, url, models }, null, 2));
+  } else {
+    printReport({ models, blocked, flagged, url, indexUnreachable });
+  }
+
+  if (blocked) process.exitCode = 1;
+  else if (flagged && flags.strict) process.exitCode = 2;
+}

package/src/commands/new.mjs

@@ -0,0 +1,64 @@
+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';
+import { localGate } from '../detect/guard-signals.mjs';
+import { AGENT_FRAMEWORKS, agentProjectFiles } from '../scaffold/agent-project.mjs';
+import { NEW_TEMPLATES } from '../scaffold/artifact-templates.mjs';
+
+function cmdNewAgent(flags, positional) {
+  const framework = String(flags.framework || AGENT_FRAMEWORKS[0]).toLowerCase();
+  if (!AGENT_FRAMEWORKS.includes(framework)) {
+    console.error(red('✗') + ` Unknown --framework: ${framework}. Supported: ${AGENT_FRAMEWORKS.join(', ')}.`);
+    process.exit(EXIT_USAGE);
+  }
+  const name = (positional[0] || 'my-agent').replace(/[^a-zA-Z0-9._-]/g, '-');
+  const dir = path.resolve(name);
+  if (fs.existsSync(dir) && fs.readdirSync(dir).length && !flags.force) {
+    console.error(red('✗') + ` ${name}/ already exists and is not empty. Use ${bold('--force')} to write into it anyway.`);
+    process.exit(EXIT_USAGE);
+  }
+
+  const files = agentProjectFiles(name);
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = path.join(dir, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content);
+  }
+
+  if (flags.json) {
+    console.log(JSON.stringify({ created: name, framework, files: Object.keys(files) }, null, 2));
+    return;
+  }
+  console.log(`\n  ${green('✓ Created')} ${bold(name + '/')} ${dim('· ' + framework + ' · ' + Object.keys(files).length + ' files')}`);
+  for (const rel of Object.keys(files)) console.log(`    ${dim('+')} ${rel}`);
+  console.log(`\n  ${bold('Next')}`);
+  console.log(`    cd ${name} && cp .env.example .env && npm install`);
+  console.log(`    ${bold('shomra rules --write')} ${dim('- write the agent rules block into CLAUDE.md')}`);
+  console.log(`    ${bold('shomra check')}         ${dim('- confirm it starts clean')}`);
+  console.log(dim('\n  Guard enforcing, egress allowlisted, secrets in env, gate in CI - from commit zero.\n'));
+}
+
+export function cmdNew(flags, positional) {
+  const kind = String(positional[0] || '').toLowerCase();
+
+  if (kind === 'agent') return cmdNewAgent(flags, positional.slice(1));
+  const tmpl = NEW_TEMPLATES[kind];
+  if (!tmpl) {
+    console.error(red('✗') + ` Usage: ${bold('shomra new ' + Object.keys(NEW_TEMPLATES).join('|') + '|agent [name]')}`);
+    process.exit(EXIT_USAGE);
+  }
+  const name = (positional[1] || (kind === 'rules' ? 'rules' : `my-${kind}`)).replace(/[^a-zA-Z0-9._-]/g, '-');
+  const { file, content } = tmpl(name);
+  const target = path.resolve(file);
+  if (fs.existsSync(target) && !flags.force) {
+    console.error(red('✗') + ` ${file} already exists. Use ${bold('--force')} to overwrite.`);
+    process.exit(EXIT_USAGE);
+  }
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, content);
+  const g = localGate(content, { kind: kind === 'agent-card' ? 'agent-card' : kind === 'mcp' ? 'mcp' : kind === 'rules' ? 'rules' : kind, path: file });
+  if (flags.json) { console.log(JSON.stringify({ created: file, kind, verdict: g.verdict }, null, 2)); return; }
+  console.log(`\n  ${green('✓ Created')} ${bold(file)} ${dim(`(${kind})`)}`);
+  console.log(`  ${g.verdict === 'ALLOW' ? green('✓ gate: clean') : yellow('gate: ' + g.verdict)} ${dim('- secure-by-default template. Edit, then')} ${bold('shomra gate ' + file)}${dim('.')}\n`);
+}