@shomra/agent 0.3.17 → 0.3.18

package/src/commands/add.mjs

@@ -0,0 +1,149 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { didYouMean, levenshtein } from '../cli/suggestions.mjs';
+import { loadConfig, resolveSettings } from '../core/config.mjs';
+import { EXIT_USAGE } from '../core/exit-codes.mjs';
+import { SEV_COLOR, bold, dim, green, red, yellow } from '../core/terminal.mjs';
+import { AI_USAGE_CATEGORY_LABEL, KNOWN_AI_PACKAGES } from '../detect/ai-usage.mjs';
+import { localGate } from '../detect/guard-signals.mjs';
+import { collectLocalSast, mergeSastIntoResult } from '../gate/sast.mjs';
+import { MODEL_SEV_RANK, modelFixPlan, modelLookup, printAlternatives } from '../models/lookup.mjs';
+import { cmdMcp } from './mcp.mjs';
+
+const ADD_KINDS = ['mcp', 'skill', 'model', 'package'];
+
+export async function cmdAdd(flags, positional) {
+  const kind = String(positional[0] || '').toLowerCase();
+  if (!ADD_KINDS.includes(kind)) {
+    const near = didYouMean(kind, ADD_KINDS);
+    console.error(red('✗') + ` Usage: ${bold('shomra add ' + ADD_KINDS.join('|') + ' <ref>')}` + (near ? dim(`  (did you mean ${near}?)`) : ''));
+    console.error(dim('  mcp     ') + 'shomra add mcp files npx -y @modelcontextprotocol/server-filesystem /tmp');
+    console.error(dim('  skill   ') + 'shomra add skill ./downloaded-skill');
+    console.error(dim('  model   ') + 'shomra add model openai-community/gpt2');
+    console.error(dim('  package ') + 'shomra add package langchain --type pypi');
+    process.exit(EXIT_USAGE);
+  }
+
+  if (kind === 'mcp') return cmdMcp(flags, ['add', ...positional.slice(1)]);
+  if (kind === 'skill') return addSkill(flags, positional.slice(1));
+  if (kind === 'model') return addModel(flags, positional.slice(1));
+  return addPackage(flags, positional.slice(1));
+}
+
+function finishAdd(kind, ref, verdict, lines, flags, extra = {}) {
+  if (flags.json) {
+    console.log(JSON.stringify({ kind, ref, verdict, accepted: verdict !== 'BLOCK' || !!flags.force, ...extra }, null, 2));
+  } else {
+    const vc = verdict === 'BLOCK' ? red : verdict === 'FLAG' ? yellow : green;
+    console.log(`\n  ${vc(verdict === 'BLOCK' ? '✗ BLOCK' : verdict === 'FLAG' ? '⚠ FLAG' : '✓ ALLOW')} ${bold(ref)} ${dim('· ' + kind)}`);
+    for (const l of lines) console.log('    ' + l);
+    if (verdict === 'BLOCK' && !flags.force) console.log(`\n  ${red('Not acquired.')} ${dim('Review the findings, or override deliberately with')} ${bold('--force')}${dim('.')}`);
+    else if (verdict === 'BLOCK') console.log(`\n  ${yellow('Forced past a BLOCK.')} ${dim('This is recorded as a deliberate override.')}`);
+    console.log('');
+  }
+  if (verdict === 'BLOCK' && !flags.force) process.exitCode = 1;
+  else if (verdict === 'FLAG' && flags.strict) process.exitCode = 2;
+}
+
+async function addSkill(flags, positional) {
+  const ref = positional[0];
+  if (!ref) { console.error(red('✗') + ' Usage: ' + bold('shomra add skill <path>')); process.exit(EXIT_USAGE); }
+  let target = path.resolve(String(ref));
+  if (!fs.existsSync(target)) { console.error(red('✗') + ` Not found: ${ref}`); process.exit(EXIT_USAGE); }
+  if (fs.statSync(target).isDirectory()) {
+    const md = path.join(target, 'SKILL.md');
+    if (!fs.existsSync(md)) { console.error(red('✗') + ` ${ref} has no SKILL.md - point at the skill's directory or its SKILL.md.`); process.exit(EXIT_USAGE); }
+    target = md;
+  }
+  const rel = path.relative(process.cwd(), target).split(path.sep).join('/');
+  const content = fs.readFileSync(target, 'utf8');
+
+  const merged = mergeSastIntoResult(
+    { ...localGate(content, { kind: 'skill', path: rel }), decision: localGate(content, { kind: 'skill', path: rel }).verdict },
+    collectLocalSast({ fullPath: target, relPath: rel, kind: 'skill', content }),
+  );
+  const findings = merged.findings || [];
+  const lines = findings.slice(0, 8).map((f) => `${(SEV_COLOR[f.severity] || dim)(String(f.severity).padEnd(8))} ${f.title}${f.line ? dim(' (line ' + f.line + ')') : ''}`);
+  if (!findings.length) lines.push(dim('no findings - manifest and bundled scripts both clean'));
+  finishAdd('skill', rel, merged.decision, lines, flags, { findings, riskScore: merged.riskScore });
+}
+
+async function addModel(flags, positional) {
+  const raw = String(positional[0] || '');
+  if (!raw) { console.error(red('✗') + ' Usage: ' + bold('shomra add model <owner/model[@revision]>')); process.exit(EXIT_USAGE); }
+  const [id, revision] = raw.split('@');
+  const { url } = resolveSettings(loadConfig());
+
+  let lk;
+  try { lk = await modelLookup(url, id, revision); } catch (e) {
+
+    return finishAdd('model', raw, 'FLAG', [
+      yellow('could not check the Model Index') + dim(` - ${e.message}`),
+      dim('This is unverified, not clean. Re-run when the index is reachable, or accept the risk explicitly.'),
+    ], flags, { checked: false, error: e.message });
+  }
+  if (!lk || !lk.found) {
+    return finishAdd('model', raw, 'FLAG', [
+      yellow('not in the Model Index') + dim(' - nobody has scanned this model'),
+      dim('Unscanned is not safe. `shomra admin model-scan ' + id + '` scans it on the platform.'),
+    ], flags, { checked: true, found: false });
+  }
+
+  const findings = lk.findings || [];
+  const worst = findings.reduce((m, f) => Math.max(m, MODEL_SEV_RANK[f.severity] || 0), 0);
+  const verdict = lk.verdict === 'FAIL' || worst >= MODEL_SEV_RANK.CRITICAL ? 'BLOCK' : lk.verdict === 'REVIEW' || worst >= MODEL_SEV_RANK.HIGH ? 'FLAG' : 'ALLOW';
+  const lines = [
+    `${dim('index verdict')} ${lk.verdict === 'FAIL' ? red(lk.verdict) : lk.verdict === 'REVIEW' ? yellow(lk.verdict) : green(lk.verdict)} ${dim('· risk ' + (lk.riskScore ?? '?') + '/100')}${lk.cached ? dim(lk.stale ? ' · cached (stale)' : ' · cached') : ''}`,
+    ...findings.slice(0, 6).map((f) => `${(SEV_COLOR[f.severity] || dim)(String(f.severity).padEnd(8))} ${f.title}`),
+  ];
+  const fix = modelFixPlan(findings, lk.sha);
+  if (fix) lines.push(dim('load it safely with: ') + fix.kwargs.map((k) => `${k.name}=${k.value}`).join(', '));
+  finishAdd('model', raw, verdict, lines, flags, { checked: true, found: true, indexVerdict: lk.verdict, riskScore: lk.riskScore, findings, fix });
+  if (!flags.json) printAlternatives(lk.alternatives, 'model', '    ');
+}
+
+const TYPOSQUAT_MAX_DISTANCE = 2;
+
+async function addPackage(flags, positional) {
+  const name = String(positional[0] || '').trim();
+  if (!name) { console.error(red('✗') + ' Usage: ' + bold('shomra add package <name> [--type npm|pypi]')); process.exit(EXIT_USAGE); }
+  const type = flags.type ? String(flags.type).toLowerCase() : null;
+  if (type && type !== 'npm' && type !== 'pypi') { console.error(red('✗') + ' --type must be npm or pypi.'); process.exit(EXIT_USAGE); }
+
+  const pool = KNOWN_AI_PACKAGES.filter((p) => !type || p.ecosystem === type);
+  const exact = pool.find((p) => p.name.toLowerCase() === name.toLowerCase());
+
+  const near = exact || name.length <= 4
+    ? []
+    : pool
+        .map((p) => ({ p, d: levenshtein(name.toLowerCase(), p.name.toLowerCase()) }))
+        .filter((x) => x.d > 0 && x.d <= TYPOSQUAT_MAX_DISTANCE)
+        .sort((a, b) => a.d - b.d)
+        .slice(0, 3);
+
+  const otherEco = exact ? null : KNOWN_AI_PACKAGES.find((p) => p.name.toLowerCase() === name.toLowerCase());
+
+  let verdict = 'ALLOW';
+  const lines = [];
+  if (near.length) {
+    verdict = 'BLOCK';
+    lines.push(red('possible typosquat') + dim(` - ${near.length === 1 ? 'this is' : 'these are'} ${near.map((x) => `${x.d} edit${x.d === 1 ? '' : 's'} from ${bold(x.p.name)} (${x.p.label}, ${x.p.ecosystem})`).join('; ')}`));
+    lines.push(dim('If you meant the real package, install that exact name. If this IS a distinct package, --force.'));
+  } else if (otherEco && type) {
+    verdict = 'FLAG';
+    lines.push(yellow(`"${name}" is a known ${otherEco.ecosystem} package (${otherEco.label}), not ${type}`));
+    lines.push(dim(`A ${type} package under a ${otherEco.ecosystem} project's name is a common squat. Confirm the publisher before installing.`));
+  } else if (exact) {
+    lines.push(green('known AI package') + dim(` - ${exact.label} · ${AI_USAGE_CATEGORY_LABEL[exact.category] || exact.category} · ${exact.ecosystem}`));
+    lines.push(dim('Name recognised. That is not a supply-chain review: pin the version and check the publisher.'));
+  } else {
+
+    verdict = 'FLAG';
+    lines.push(yellow('not in the AI package catalog') + dim(' - no typosquat signal, and no verification either'));
+    lines.push(dim('Shomra knows AI packages by name only. Check the publisher, the download count, and the repo link yourself.'));
+  }
+  finishAdd('package', name + (type ? ` (${type})` : ''), verdict, lines, flags, {
+    known: !!exact, ecosystem: exact ? exact.ecosystem : otherEco ? otherEco.ecosystem : null,
+    nearMatches: near.map((x) => ({ name: x.p.name, distance: x.d, ecosystem: x.p.ecosystem, label: x.p.label })),
+  });
+}

package/src/commands/agent-identity.mjs

@@ -0,0 +1,46 @@
+import { api } from '../core/api-client.mjs';
+import { loadConfig, resolveSettings } from '../core/config.mjs';
+import { EXIT_USAGE, exitNotConfigured } from '../core/exit-codes.mjs';
+import { bold, cyan, dim, green, red } from '../core/terminal.mjs';
+
+export async function cmdAgentIdentity(flags, positional) {
+  const sub = (positional[0] || 'register').toLowerCase();
+  const cfg = loadConfig();
+  const { apiKey, url } = resolveSettings(cfg);
+  if (!apiKey) {
+    exitNotConfigured();
+  }
+  if (sub !== 'register') {
+    console.error(`\n  ${red('✗')} Unknown subcommand "${sub}". Use: ${bold('shomra agent-identity register --name "…" --type coding-agent')}`);
+    console.error(dim('  (List / govern / revoke identities in the dashboard → Agent Identities.)\n'));
+    process.exit(EXIT_USAGE);
+  }
+  let res;
+  try {
+    res = await api(url, apiKey, '/agents/register', {
+      name: flags.name ? String(flags.name) : undefined,
+      slug: flags.slug ? String(flags.slug) : undefined,
+      type: flags.type ? String(flags.type) : undefined,
+    });
+  } catch (e) {
+    console.error(`\n  ${red('✗')} ${e.message}\n`);
+    process.exit(1);
+  }
+  if (flags.json) {
+    console.log(JSON.stringify(res, null, 2));
+    return;
+  }
+  console.log(`\n  ${green('✓')} Registered agent identity ${bold(res.name)} ${dim('(' + res.slug + ' · ' + res.type + ')')}`);
+  if (res.credential) {
+    console.log(`\n  ${bold('Credential')} ${dim('(shown once - store it securely):')}`);
+    console.log(`    ${cyan(res.credential)}`);
+  }
+  console.log(`\n  Present this identity so every call is authorized as it:`);
+  console.log(dim(`    export SHOMRA_AGENT=${res.slug}        # or use the credential above`));
+  console.log(dim(`  Then set its least-privilege capabilities in the dashboard → Agent Identities.\n`));
+}
+
+export function resolveAgentIdentityHandle(flags) {
+  const v = (flags && flags['agent-id'] && String(flags['agent-id'])) || process.env.SHOMRA_AGENT || '';
+  return v && String(v).trim() ? String(v).trim() : null;
+}

package/src/commands/check.mjs

@@ -0,0 +1,194 @@
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { ARTIFACT_MATCHERS, walkArtifacts } from '../artifacts/matchers.mjs';
+import { loadConfig, resolveSettings } from '../core/config.mjs';
+import { bold, cyan, dim, green, red, yellow } from '../core/terminal.mjs';
+import { VERSION } from '../core/version.mjs';
+import { failOnHit, gateArtifactList } from '../gate/batch.mjs';
+import { detectEnv } from '../gate/environment.mjs';
+import { toSarif } from '../gate/sarif.mjs';
+import { findingFingerprint } from '../gate/suppressions.mjs';
+import { fixOneFile } from './fix.mjs';
+
+const GIT_TIMEOUT_MS = 3000;
+
+function gitChangedArtifacts(root, { staged }) {
+  const run = (args) => {
+    try {
+      return execSync(`git ${args}`, { cwd: root, stdio: ['ignore', 'pipe', 'ignore'], timeout: GIT_TIMEOUT_MS }).toString();
+    } catch {
+      return null;
+    }
+  };
+
+  const output = staged
+    ? run('diff --cached --name-only --relative --diff-filter=ACM')
+    : run('diff HEAD --name-only --relative --diff-filter=ACM');
+  if (output === null) return null;
+
+  return output
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .filter((relativePath) => ARTIFACT_MATCHERS.some((matcher) => matcher.re.test(relativePath)));
+}
+
+function narrowToChanged(artifacts, root, flags) {
+  if (!flags.staged && !flags.changed) return artifacts;
+
+  const changed = gitChangedArtifacts(root, { staged: !!flags.staged });
+  if (changed === null) {
+    if (!flags.json) console.error(`  ${yellow('⚠')} ${dim('not a git repo (or git unavailable) - checking the whole tree')}`);
+    return artifacts;
+  }
+  const changedSet = new Set(changed);
+  return artifacts.filter((artifact) => changedSet.has(artifact.rel));
+}
+
+function printNothingToCheck(flags, root) {
+  if (flags.json) {
+    console.log(JSON.stringify({ scanned: 0, blocked: 0, flagged: 0, results: [] }, null, 2));
+    return;
+  }
+  const where = flags.staged || flags.changed ? ' in the changed set.' : ` under ${root}.`;
+  console.log(`${green('\n  ✓ No AI artifacts to check')}${dim(where)}\n`);
+}
+
+function printHeader({ flags, artifacts, env, apiKey }) {
+  if (flags.json || flags.sarif) return;
+
+  const scope = flags.staged ? 'staged' : flags.changed ? 'changed' : env.environment;
+  const provider = env.ciProvider ? ` · ${env.ciProvider}` : '';
+  console.log(bold(cyan('\n  Shomra check')) + dim(` - ${artifacts.length} artifact${artifacts.length > 1 ? 's' : ''} · ${scope}${provider}`));
+  if (!apiKey) console.error(`  ${dim('On-machine analysis only - run')} ${bold('shomra init')} ${dim('to also apply org policy.')}`);
+}
+
+async function applyFixes({ results, flags, apiKey, url, blocked, flagged }) {
+  if (!flags.fix || !(blocked || flagged)) return 0;
+
+  if (!apiKey) {
+    if (!flags.json) {
+      console.error(`  ${yellow('⚠')} ${dim('--fix needs enrollment (the fix runs on the platform). Run')} ${bold('shomra init')}${dim('.')}`);
+    }
+    return 0;
+  }
+
+  if (!flags.json) console.log(dim('\n  Fixing flagged artifacts…'));
+  let fixed = 0;
+  for (const result of results) {
+    if (result.decision === 'ALLOW') continue;
+    const done = await fixOneFile(result.full, { apiKey, url, flags: { ...flags, apply: true, quiet: flags.json } });
+    if (done) fixed += 1;
+  }
+  return fixed;
+}
+
+function verdictLine({ blocked, flagged, suppressed, total }) {
+  if (blocked) return red(`✗ ${blocked} blocked`) + dim(` · ${flagged} flagged · ${total - blocked - flagged} clean`);
+  if (flagged) return yellow(`⚠ ${flagged} flagged`) + dim(` · ${total - flagged} clean`);
+  if (suppressed) return green(`✓ ${total} passing`) + dim(' - nothing NEW; previously accepted findings are still there');
+  return green(`✓ All ${total} clean.`);
+}
+
+function printSummary({ results, blocked, flagged, suppressed, backendDown, rejected, fixed, flags, strictOutage }) {
+  const suppressedNote = suppressed ? dim(` · ${suppressed} accepted by baseline/ignore`) : '';
+  const outageNote = backendDown ? yellow('  (on-machine only - org policy not applied)') : '';
+  const rejectedNote = rejected.length
+    ? yellow(`  (${rejected.length} artifact(s) the backend refused - org policy not applied to those)`)
+    : '';
+
+  console.log(`\n  ${verdictLine({ blocked, flagged, suppressed, total: results.length })}${suppressedNote}${outageNote}${rejectedNote}`);
+
+  for (const entry of rejected) console.log(`  ${yellow('!')} ${dim(`${entry.path} (${entry.kind}) - ${entry.reason}`)}`);
+
+  if (flags.fix && fixed) {
+    console.log(`  ${green('✓')} ${dim(`applied ${fixed} fix${fixed > 1 ? 'es' : ''} - re-run`)} ${bold('shomra check')} ${dim('to confirm.')}`);
+  } else if (!flags.fix && (blocked || flagged)) {
+    console.log(dim('  Run ') + bold('shomra fix <file>') + dim(' or ') + bold('shomra check --fix') + dim(' to remediate.'));
+  }
+  if (strictOutage) console.log(`  ${red('✗ Failing closed (--strict): backend unreachable, org policy unverified.')}`);
+  console.log('');
+}
+
+export async function cmdCheck(flags, positional) {
+  const { apiKey, url } = resolveSettings(loadConfig());
+  const root = path.resolve(positional[0] || flags.path || '.');
+  const env = detectEnv();
+
+  const artifacts = narrowToChanged(walkArtifacts(root), root, flags);
+  if (!artifacts.length) {
+    printNothingToCheck(flags, root);
+    return;
+  }
+
+  printHeader({ flags, artifacts, env, apiKey });
+  const { results, blocked, flagged, suppressed, backendDown, rejected } =
+    await gateArtifactList(artifacts, { apiKey, url, env, flags, root });
+
+  if (flags.sarif) {
+    console.log(JSON.stringify(toSarif(results), null, 2));
+    if (blocked) process.exitCode = 1;
+    else if (flagged && flags.strict) process.exitCode = 2;
+    return;
+  }
+
+  const fixed = await applyFixes({ results, flags, apiKey, url, blocked, flagged });
+  const strictOutage = backendDown && flags.strict;
+
+  if (flags.json) {
+    console.log(JSON.stringify({
+      scanned: results.length, blocked, flagged, suppressed, fixed, backendDown, rejected,
+      environment: env.environment, results,
+    }, null, 2));
+  } else {
+    printSummary({ results, blocked, flagged, suppressed, backendDown, rejected, fixed, flags, strictOutage });
+  }
+
+  if (blocked > 0 || strictOutage) process.exitCode = 1;
+  else if (failOnHit(flags, blocked, flagged)) process.exitCode = 1;
+  else if (flagged > 0 && flags.strict) process.exitCode = 2;
+}
+
+export async function cmdBaseline(flags, positional) {
+  const { apiKey, url } = resolveSettings(loadConfig());
+  const root = path.resolve(positional[0] || flags.path || '.');
+  const env = detectEnv();
+
+  const artifacts = walkArtifacts(root);
+  if (!artifacts.length) {
+    console.log(dim(`\n  No AI artifacts under ${root} - nothing to baseline.\n`));
+    return;
+  }
+  if (!flags.json) {
+    process.stdout.write(dim(`  Scanning ${artifacts.length} artifact${artifacts.length > 1 ? 's' : ''} to baseline… `));
+  }
+
+  const { results } = await gateArtifactList(artifacts, {
+    apiKey, url, env, root, flags: { ...flags, json: true, 'no-suppress': true },
+  });
+
+  const fingerprints = new Set();
+  for (const result of results) {
+    for (const finding of result.findings || []) fingerprints.add(findingFingerprint(result.path, finding));
+  }
+
+  const directory = path.join(root, '.shomra');
+  fs.mkdirSync(directory, { recursive: true });
+  const file = path.join(directory, 'baseline.json');
+  fs.writeFileSync(file, JSON.stringify({
+    createdAt: new Date().toISOString(),
+    agentVersion: VERSION,
+    count: fingerprints.size,
+    fingerprints: [...fingerprints],
+  }, null, 2));
+
+  const relative = path.relative(process.cwd(), file).split(path.sep).join('/');
+  if (flags.json) {
+    console.log(JSON.stringify({ baseline: relative, count: fingerprints.size, artifacts: results.length }, null, 2));
+    return;
+  }
+  console.log(green('done'));
+  console.log(`\n  ${green('✓ Baseline written')} ${dim(`- ${fingerprints.size} finding(s) across ${results.length} artifact(s) accepted.`)}`);
+  console.log(`${dim(`  ${relative} - commit it so your team shares the baseline. Only NEW findings will fail now.`)}\n`);
+}

package/src/commands/corpus.mjs

@@ -0,0 +1,126 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { CORPUS_DEFAULT_CHUNK, collectCorpusFiles, screenCorpus } from '../corpus/screening.mjs';
+import { EXIT_USAGE } from '../core/exit-codes.mjs';
+import { clampInt } from '../core/numbers.mjs';
+import { SEV_COLOR, bold, cyan, dim, green, red, yellow } from '../core/terminal.mjs';
+
+const MIN_CHUNK = 100;
+const MAX_CHUNK = 100000;
+
+const plural = (count, word) => `${word}${count === 1 ? '' : 's'}`;
+
+function usageExit() {
+  console.error(`${red('✗')} Usage: ${bold('shomra corpus <dir|file> [--chunk-size 1200] [--manifest <file>] [--strict]')}`);
+  console.error(dim('  Screens documents BEFORE they are embedded, so a poisoned one never enters the index.'));
+  process.exit(EXIT_USAGE);
+}
+
+function resolveTarget(flags, positional) {
+  const target = positional[0] || flags.path;
+  if (!target) usageExit();
+
+  const absolutePath = path.resolve(String(target));
+  if (!fs.existsSync(absolutePath)) {
+    console.error(`${red('✗')} Not found: ${target}`);
+    process.exit(EXIT_USAGE);
+  }
+  return { absolutePath, isDirectory: fs.statSync(absolutePath).isDirectory() };
+}
+
+function buildManifest({ absolutePath, isDirectory, chunkSize, results, unreadable, quarantined }) {
+  return {
+    root: isDirectory ? absolutePath : path.dirname(absolutePath),
+    chunkSize,
+    screened: results.length,
+    unreadable: unreadable.length,
+    quarantine: quarantined.map(({ path: file, verdict, findings }) => ({ path: file, verdict, findings })),
+    unreadableFiles: unreadable.map(({ rel, reason }) => ({ path: rel, reason })),
+  };
+}
+
+function writeManifest(flags, manifest) {
+  if (!flags.manifest) return;
+  const target = path.resolve(String(flags.manifest));
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, `${JSON.stringify(manifest, null, 2)}\n`);
+}
+
+function findingContext(finding) {
+  if (finding.concealed) return yellow(' [hidden in an HTML comment - invisible to a reader, read by the model]');
+  if (finding.codeContext) return dim(' [quoted in a code block]');
+  return '';
+}
+
+function findingLocation(finding) {
+  if (finding.chunk !== null && finding.chunk !== undefined) return dim(` (line ${finding.line} · chunk ${finding.chunk})`);
+  return finding.line ? dim(` (line ${finding.line})`) : '';
+}
+
+function printQuarantined(quarantined) {
+  for (const document of quarantined) {
+    const colour = document.verdict === 'BLOCK' ? red : yellow;
+    console.log(`\n  ${colour(document.verdict === 'BLOCK' ? '✗ QUARANTINE' : '⚠ REVIEW')} ${bold(document.path)}`);
+    for (const finding of document.findings) {
+      const severity = (SEV_COLOR[finding.severity] || dim)(String(finding.severity).padEnd(8));
+      console.log(`    ${severity} ${finding.label}${findingLocation(finding)}${findingContext(finding)}`);
+    }
+  }
+}
+
+function summaryLine({ blocked, flagged, total }) {
+  if (blocked.length) {
+    const clean = total - blocked.length - flagged.length;
+    return red(`✗ ${blocked.length} ${plural(blocked.length, 'document')} must not be indexed`)
+      + dim(` · ${flagged.length} to review · ${clean} clean`);
+  }
+  if (flagged.length) {
+    return yellow(`⚠ ${flagged.length} to review`) + dim(` · ${total - flagged.length} clean`);
+  }
+  return green(`✓ All ${total} screened documents clean.`);
+}
+
+function printUnreadable(unreadable) {
+  if (!unreadable.length) return;
+  const heading = `${unreadable.length} ${plural(unreadable.length, 'file')} could not be read`;
+  console.log(`  ${yellow('⚠')} ${bold(heading)} ${dim('- they are NOT covered by the result above:')}`);
+
+  const byReason = new Map();
+  for (const entry of unreadable) byReason.set(entry.reason, (byReason.get(entry.reason) || 0) + 1);
+  for (const [reason, count] of byReason) console.log(dim(`      ${count} × ${reason}`));
+  console.log(dim('      Extract them to text and re-run, or exclude them from the index.'));
+}
+
+function printReport({ flags, chunkSize, results, unreadable, blocked, flagged, quarantined }) {
+  console.log(bold(cyan('\n  Shomra corpus')) + dim(` - ${results.length} ${plural(results.length, 'document')} · chunk size ${chunkSize}`));
+  printQuarantined(quarantined);
+  console.log('');
+  console.log(`  ${summaryLine({ blocked, flagged, total: results.length })}`);
+  printUnreadable(unreadable);
+  if (flags.manifest) console.log(dim(`  Quarantine manifest → ${flags.manifest}`));
+  console.log(dim('  Feed the manifest to your ingestion job so a quarantined document is never embedded.\n'));
+}
+
+export async function cmdCorpus(flags, positional) {
+  const { absolutePath, isDirectory } = resolveTarget(flags, positional);
+  const chunkSize = clampInt(flags['chunk-size'], CORPUS_DEFAULT_CHUNK, MIN_CHUNK, MAX_CHUNK);
+
+  const { files, opaque } = collectCorpusFiles(absolutePath, isDirectory);
+  const { results, unreadable } = screenCorpus(files, opaque, chunkSize);
+
+  const blocked = results.filter((document) => document.verdict === 'BLOCK');
+  const flagged = results.filter((document) => document.verdict === 'FLAG');
+  const quarantined = [...blocked, ...flagged];
+
+  const manifest = buildManifest({ absolutePath, isDirectory, chunkSize, results, unreadable, quarantined });
+  writeManifest(flags, manifest);
+
+  if (flags.json) {
+    console.log(JSON.stringify({ ...manifest, blocked: blocked.length, flagged: flagged.length, results }, null, 2));
+  } else {
+    printReport({ flags, chunkSize, results, unreadable, blocked, flagged, quarantined });
+  }
+
+  if (blocked.length) process.exitCode = 1;
+  else if ((flagged.length || unreadable.length) && flags.strict) process.exitCode = 2;
+}