@shomra/agent 0.3.17 → 0.3.19

package/src/commands/design.mjs

@@ -0,0 +1,168 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { MAX_ARTIFACT_BYTES, SKIP_DIRS } from '../artifacts/matchers.mjs';
+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, bold, cyan, dim, green, red, yellow } from '../core/terminal.mjs';
+import { CAP_LABEL, analyzeDesign, designChecklist } from '../detect/design.mjs';
+
+export async function cmdDesign(flags, positional) {
+  const target = positional[0] || flags.path;
+  if (!target) {
+    console.error(red('✗') + ' Usage: ' + bold('shomra design <file|dir|->') + dim('  (use - to read a ticket/RFC on stdin)'));
+    console.error(dim('  e.g. ') + 'gh issue view 42 --json body -q .body | shomra design -');
+    process.exit(EXIT_USAGE);
+  }
+
+  const docs = [];
+  if (target === '-' || flags.stdin) {
+    docs.push({ name: flags.name ? String(flags.name) : 'stdin', text: fs.readFileSync(0, 'utf8') });
+  } else {
+    const abs = path.resolve(String(target));
+    if (!fs.existsSync(abs)) {
+      console.error(red('✗') + ` Not found: ${target}`);
+      process.exit(EXIT_USAGE);
+    }
+    if (fs.statSync(abs).isDirectory()) {
+      for (const f of walkDesignDocs(abs)) {
+        try { if (fs.statSync(f.full).size <= MAX_ARTIFACT_BYTES) docs.push({ name: f.rel, text: fs.readFileSync(f.full, 'utf8') }); } catch {  }
+      }
+      if (!docs.length) {
+        console.error(red('✗') + ` No design documents (.md / .txt / .rst) found under ${target}.`);
+        process.exit(EXIT_USAGE);
+      }
+    } else {
+      docs.push({ name: path.relative(process.cwd(), abs).split(path.sep).join('/'), text: fs.readFileSync(abs, 'utf8') });
+    }
+  }
+
+  const results = docs.map((d) => analyzeDesign(d.text, { name: d.name }));
+  const open = results.filter((r) => r.verdict === 'OPEN_PATH');
+  const critical = results.filter((r) => r.worst === 'CRITICAL');
+
+  if (flags.json) {
+    console.log(JSON.stringify({ documents: results.length, openPaths: open.length, critical: critical.length, results }, null, 2));
+  } else if (flags.checklist) {
+
+    console.log(results.map(designChecklist).join('\n---\n\n'));
+  } else {
+    for (const r of results) printDesign(r);
+    if (results.length > 1) {
+      console.log(
+        `  ${open.length ? red(`✗ ${open.length} of ${results.length} documents describe a closed attack path`) : yellow(`• no closed path described in ${results.length} documents`)}\n`,
+      );
+    }
+  }
+
+  if (flags.save) await saveDesign(results, flags);
+
+  if (critical.length) process.exitCode = 1;
+  else if (open.length && flags.strict) process.exitCode = 2;
+}
+
+async function saveDesign(results, flags) {
+  const { apiKey, url } = resolveSettings(loadConfig());
+  const subject = String(flags.subject ?? '').trim();
+  const m = /^(AGENT|PROJECT|DESIGN):(.+)$/i.exec(subject);
+  if (!m) {
+    console.error(red('✗') + ' --save needs ' + bold('--subject KIND:id') + dim('  (AGENT | PROJECT | DESIGN)'));
+    console.error(dim('  e.g. ') + 'shomra design docs/rfc.md --save --subject DESIGN:inbox-agent');
+    process.exit(EXIT_USAGE);
+  }
+  if (results.length !== 1) {
+    console.error(red('✗') + ` --save takes one document; ${results.length} were modelled.`);
+    console.error(dim('  Save each against its own subject.'));
+    process.exit(EXIT_USAGE);
+  }
+  if (!apiKey || !url) exitNotConfigured();
+
+  const [, kind, id] = m;
+  const r = results[0];
+  process.stdout.write(dim('  Saving to the platform… '));
+  try {
+    const res = await api(url, apiKey, '/threat-models/agent-author', {
+      subjectKind: kind.toUpperCase(),
+      subjectId: id,
+      title: flags.title ? String(flags.title) : r.name,
+      analysis: r,
+      note: flags.note ? String(flags.note) : `Modelled from ${r.name}.`,
+      actor: flags.actor ? String(flags.actor) : undefined,
+    });
+    const v = res?.version;
+    const c = res?.coverage;
+    console.log(green('saved') + dim(` - v${v?.seq ?? '?'}, ${v?.reviewState ?? 'IN_REVIEW'}`));
+
+    console.log(dim('  It is not approved yet - a threat model must be reviewed by someone other than its author.'));
+    if (c?.headline) console.log(dim('  ') + c.headline);
+  } catch (e) {
+    console.log(red('failed'));
+    console.error(dim('  ') + (e?.message || String(e)));
+    process.exitCode = 1;
+  }
+}
+
+const DESIGN_DOC_RE = /\.(md|markdown|txt|rst|adoc)$/i;
+
+const DESIGN_MAX_DOCS = 50;
+
+function walkDesignDocs(root) {
+  const found = [];
+  const stack = [root];
+  while (stack.length && found.length < DESIGN_MAX_DOCS) {
+    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; }
+      if (!DESIGN_DOC_RE.test(ent.name)) continue;
+      found.push({ full, rel: path.relative(root, full).split(path.sep).join('/') });
+      if (found.length >= DESIGN_MAX_DOCS) break;
+    }
+  }
+  return found;
+}
+
+function printDesign(r) {
+  const vColor = r.verdict === 'OPEN_PATH' ? red : yellow;
+  console.log(bold(cyan('\n  Shomra design')) + dim(` - ${r.name}`));
+
+  if (r.verdict === 'NOT_DESCRIBED') {
+    console.log(`\n  ${yellow('• Nothing recognised')} ${dim('- no untrusted input, sensitive data, or agent action was described here.')}`);
+    console.log(dim('    That is a statement about the document, not about the system. If the agent will read'));
+    console.log(dim('    anything untrusted or take any action, write that down and re-run.\n'));
+    return;
+  }
+
+  const capLine = (list, kind) =>
+    list.length
+      ? `  ${bold(kind)}  ${list.map((c) => CAP_LABEL[c]).join(dim(' · '))}`
+      : `  ${bold(kind)}  ${dim('none described')}`;
+  console.log('');
+  console.log(capLine(r.sources, 'Sources'));
+  console.log(capLine(r.sinks, 'Sinks  '));
+
+  if (r.verdict === 'PARTIAL') {
+    console.log(`\n  ${yellow('• Only one side of a path is described.')} ${dim('No closed path - yet.')}`);
+    console.log(dim('    This is not a clean result: the other side may simply be unwritten, or land next sprint.\n'));
+    return;
+  }
+
+  console.log(`\n  ${vColor(`✗ ${r.paths.length} attack path${r.paths.length === 1 ? '' : 's'} closed by this design:`)}\n`);
+  for (const p of r.paths.slice(0, 6)) {
+    const sc = SEV_COLOR[p.severity] || dim;
+    console.log(`    ${sc(String(p.severity).padEnd(8))} ${bold(CAP_LABEL[p.source])} ${dim('→')} ${bold(CAP_LABEL[p.sink])}`);
+    console.log(`             ${p.story}`);
+    if (p.sourceEvidence) console.log(dim(`             ↳ line ${p.sourceEvidence.line}: "${p.sourceEvidence.quote}"`));
+  }
+  if (r.paths.length > 6) console.log(dim(`    … and ${r.paths.length - 6} more (run with --json for all)`));
+
+  console.log(`\n  ${bold('Conditions to satisfy before this ships')}`);
+  for (const c of r.controls.slice(0, 8)) console.log(`    ${dim('☐')} ${c.text}`);
+  if (r.controls.length > 8) console.log(dim(`    … and ${r.controls.length - 8} more`));
+
+  console.log(dim('\n  Paste these into the ticket: ') + bold(`shomra design ${r.name} --checklist`));
+  console.log(dim('  It reads prose - it sees only what was written down. A capability nobody documented'));
+  console.log(dim('  is not a capability you do not have.\n'));
+}

package/src/commands/doctor.mjs

@@ -0,0 +1,209 @@
+import os from 'node:os';
+import path from 'node:path';
+import { loadConfig } from '../core/config.mjs';
+import { bold, cyan, dim, green, red, yellow } from '../core/terminal.mjs';
+import { localGate } from '../detect/guard-signals.mjs';
+import { discoverAll } from '../inventory/discovery.mjs';
+
+const MAX_ISSUES_SHOWN = 6;
+const UNGUARDED_AGENT_PENALTY = 8;
+const MAX_UNGUARDED_PENALTY = 40;
+const BLOCK_PENALTY = 15;
+const FLAG_PENALTY = 5;
+const DOTENV_KEY_PENALTY = 10;
+const MAX_DOTENV_PENALTY = 30;
+
+function assetPath(asset) {
+  return asset.identifier || asset.metadata?.configFile || asset.metadata?.file || asset.name;
+}
+
+function riskyArtifactsIn(assets, kind) {
+  const risky = [];
+  for (const asset of assets) {
+    const content = asset.content || asset.metadata?.content;
+    if (!content) continue;
+    const location = assetPath(asset);
+    const verdict = localGate(content, { kind, path: location });
+    if (verdict.verdict === 'ALLOW') continue;
+    risky.push({
+      name: asset.name,
+      kind,
+      decision: verdict.verdict,
+      riskScore: verdict.riskScore,
+      top: (verdict.findings[0] || {}).title,
+      path: location,
+    });
+  }
+  return risky;
+}
+
+function dedupeRisky(risky) {
+  const seen = new Set();
+  return risky.filter((entry) => {
+    const key = `${entry.path}|${entry.decision}|${entry.top}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function groupIntoIssues(risky) {
+  const byIssue = new Map();
+  for (const entry of risky) {
+    const key = `${entry.name}|${entry.kind}|${entry.decision}|${entry.top}`;
+    const group = byIssue.get(key) ?? {
+      name: entry.name, kind: entry.kind, decision: entry.decision, top: entry.top, riskScore: entry.riskScore, paths: [],
+    };
+    group.paths.push(entry.path);
+    byIssue.set(key, group);
+  }
+  return [...byIssue.values()];
+}
+
+function postureScore({ unguarded, issues, dotenvKeys }) {
+  let score = 100;
+  score -= Math.min(MAX_UNGUARDED_PENALTY, unguarded.length * UNGUARDED_AGENT_PENALTY);
+  for (const issue of issues) score -= issue.decision === 'BLOCK' ? BLOCK_PENALTY : FLAG_PENALTY;
+  score -= Math.min(MAX_DOTENV_PENALTY, dotenvKeys.length * DOTENV_KEY_PENALTY);
+  return Math.max(0, Math.round(score));
+}
+
+function postureGrade(score) {
+  if (score >= 90) return 'A';
+  if (score >= 75) return 'B';
+  if (score >= 60) return 'C';
+  if (score >= 40) return 'D';
+  return 'F';
+}
+
+function scoreColour(score) {
+  if (score >= 75) return green;
+  if (score >= 50) return yellow;
+  return red;
+}
+
+function collectInventory() {
+  const assets = discoverAll();
+  const ofType = (type) => assets.filter((asset) => asset.type === type);
+  return {
+    agents: ofType('AI_AGENT'),
+    mcpServers: ofType('MCP_SERVER'),
+    rulesFiles: ofType('AI_RULES'),
+    modelKeys: ofType('MODEL_KEY'),
+    aiTools: ofType('AI_TOOL'),
+  };
+}
+
+function printCountRow(label, count, note) {
+  console.log(`  ${dim(String(label).padEnd(16))} ${bold(String(count).padStart(3))}${note ? `  ${note}` : ''}`);
+}
+
+function printInventoryRows({ inventory, risky, unguarded, dotenvKeys }) {
+  const riskyOfKind = (kind) => risky.filter((entry) => entry.kind === kind).length;
+  const { agents, mcpServers, rulesFiles, modelKeys, aiTools } = inventory;
+
+  printCountRow('Coding agents', agents.length, unguarded.length
+    ? red(`${unguarded.length} UNGUARDED`) + dim(` · ${agents.length - unguarded.length} protected`)
+    : green('all protected'));
+  printCountRow('MCP servers', mcpServers.length, riskyOfKind('mcp') ? yellow(`${riskyOfKind('mcp')} risky`) : '');
+  printCountRow('Rules files', rulesFiles.length, riskyOfKind('rules') ? yellow(`${riskyOfKind('rules')} risky`) : '');
+  printCountRow('Model keys', modelKeys.length, dotenvKeys.length ? yellow(`${dotenvKeys.length} in .env files`) : '');
+  printCountRow('AI tools', aiTools.length, '');
+}
+
+function printRiskyIssues(issues) {
+  if (!issues.length) return;
+  console.log(dim('\n  Risky artifacts:'));
+
+  const shortDir = (target) => path.dirname(String(target || '')).replace(os.homedir(), '~').split(path.sep).join('/');
+  const shown = issues.slice(0, MAX_ISSUES_SHOWN);
+  for (const issue of shown) {
+    const colour = issue.decision === 'BLOCK' ? red : yellow;
+    const location = shortDir(issue.paths[0]);
+    const where = issue.paths.length > 1
+      ? dim(`×${issue.paths.length}`) + dim(` · ${location}, …`)
+      : dim(location);
+    console.log(`    ${colour('●')} ${bold(issue.name)} ${where} ${dim(`(${issue.kind})`)} ${colour(issue.decision)} ${dim(issue.top || '')}`);
+  }
+
+  const remaining = issues.length - shown.length;
+  if (remaining > 0) console.log(dim(`    …and ${remaining} more distinct issue${remaining > 1 ? 's' : ''}`));
+}
+
+function topFixes({ unguarded, issues, risky, dotenvKeys }) {
+  const fixes = [];
+  if (unguarded.length) {
+    fixes.push(`${red('!')} ${unguarded.length} coding agent${unguarded.length > 1 ? 's have' : ' has'} no runtime firewall → ${bold('shomra protect')}`);
+  }
+  if (issues.length) {
+    const spread = risky.length > issues.length ? dim(` across ${risky.length} files`) : '';
+    fixes.push(`${yellow('!')} ${issues.length} risky MCP/rules issue${issues.length > 1 ? 's' : ''}${spread} → ${bold('shomra check')} ${dim('or')} ${bold('shomra gate <file>')}`);
+  }
+  if (dotenvKeys.length) {
+    fixes.push(`${yellow('!')} ${dotenvKeys.length} model key${dotenvKeys.length > 1 ? 's' : ''} in .env file${dotenvKeys.length > 1 ? 's' : ''} → rotate + ensure .gitignore covers them`);
+  }
+  return fixes;
+}
+
+function printFixes(fixes) {
+  if (!fixes.length) {
+    console.log(green('\n  ✓ No urgent fixes - nice posture.'));
+    return;
+  }
+  console.log(bold('\n  Top fixes:'));
+  for (const fix of fixes) console.log(`    ${fix}`);
+}
+
+function printEnrollmentHint() {
+  const enrolled = !!loadConfig().apiKey;
+  const message = enrolled
+    ? `Enrolled - run ${bold('shomra report')}${dim(' to sync this to your Shomra org.')}`
+    : `Run ${bold('shomra init')}${dim(' to apply org policy and sync posture.')}`;
+  console.log(`${dim(`\n  ${message}`)}\n`);
+}
+
+function jsonReport({ inventory, score, grade, risky, issues, unguarded, dotenvKeys }) {
+  return {
+    score,
+    grade,
+    hostname: os.hostname(),
+    codingAgents: inventory.agents.length,
+    unguarded: unguarded.length,
+    mcpServers: inventory.mcpServers.length,
+    rulesFiles: inventory.rulesFiles.length,
+    aiTools: inventory.aiTools.length,
+    modelKeys: inventory.modelKeys.length,
+    modelKeysInDotenv: dotenvKeys.length,
+    riskyArtifacts: risky.length,
+    riskyIssues: issues.length,
+    risky,
+  };
+}
+
+export function cmdDoctor(flags) {
+  const inventory = collectInventory();
+  const risky = dedupeRisky([
+    ...riskyArtifactsIn(inventory.mcpServers, 'mcp'),
+    ...riskyArtifactsIn(inventory.rulesFiles, 'rules'),
+  ]);
+  const issues = groupIntoIssues(risky);
+  const unguarded = inventory.agents.filter((agent) => !agent.metadata?.guarded);
+  const dotenvKeys = inventory.modelKeys.filter((key) => key.metadata?.source === 'dotenv');
+
+  const score = postureScore({ unguarded, issues, dotenvKeys });
+  const grade = postureGrade(score);
+
+  if (flags.json) {
+    console.log(JSON.stringify(jsonReport({ inventory, score, grade, risky, issues, unguarded, dotenvKeys }), null, 2));
+    return;
+  }
+
+  const colour = scoreColour(score);
+  console.log(bold(cyan('\n  Shomra doctor')) + dim(` - ${os.hostname()}`));
+  console.log(`\n  ${bold('Posture')}  ${colour(bold(`${score}/100`))} ${dim('· grade')} ${colour(bold(grade))}\n`);
+
+  printInventoryRows({ inventory, risky, unguarded, dotenvKeys });
+  printRiskyIssues(issues);
+  printFixes(topFixes({ unguarded, issues, risky, dotenvKeys }));
+  printEnrollmentHint();
+}

package/src/commands/fix.mjs

@@ -0,0 +1,115 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { api } from '../core/api-client.mjs';
+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 { GATE_KINDS } from '../gate/environment.mjs';
+
+export async function cmdFix(flags, positional) {
+  const file = positional[0];
+  if (!file) {
+    console.error(red('✗') + ' Usage: ' + bold('shomra fix <file> [--apply] [--kind mcp|skill|command|subagent|hook|rules] [--json]'));
+    process.exit(EXIT_USAGE);
+  }
+  const cfg = loadConfig();
+  const { apiKey, url } = resolveSettings(cfg);
+  if (!apiKey) {
+    console.error('\n' + red('✗') + ' ' + bold('shomra fix') + ' needs enrollment - the fix is generated on the platform with your org AI key.');
+    console.error('  ' + dim('Run ') + bold('shomra init --key shm_live_…') + dim(', or apply the guidance from ') + bold('shomra check') + dim(' by hand.\n'));
+    process.exit(EXIT_USAGE);
+  }
+  let target = path.resolve(String(file));
+  if (fs.existsSync(target) && fs.statSync(target).isDirectory()) {
+    const skillMd = path.join(target, 'SKILL.md');
+    if (!fs.existsSync(skillMd)) {
+      console.error(red('✗') + ` ${file} is a directory with no SKILL.md - point at a file instead.`);
+      process.exit(EXIT_USAGE);
+    }
+    target = skillMd;
+  }
+  if (!fs.existsSync(target)) {
+    console.error(red('✗') + ` File not found: ${file}`);
+    process.exit(EXIT_USAGE);
+  }
+  await fixOneFile(target, { apiKey, url, flags });
+}
+
+export async function fixOneFile(target, { apiKey, url, flags }) {
+  const rel = path.relative(process.cwd(), target).split(path.sep).join('/');
+  let content;
+  try {
+    content = fs.readFileSync(target, 'utf8');
+  } catch (e) {
+    if (!flags.json) console.error(`  ${red('✗')} cannot read ${rel}: ${e.message}`);
+    return false;
+  }
+  const kind = flags.kind && GATE_KINDS.includes(String(flags.kind)) ? String(flags.kind) : undefined;
+
+  let res;
+  try {
+    if (!flags.json && !flags.quiet) process.stdout.write(dim(`  Generating fix for ${rel}… `));
+    res = await api(url, apiKey, '/gate/fix', {
+      ...(kind ? { kind } : {}),
+      path: rel,
+      name: rel.split('/').pop(),
+      content,
+    });
+    if (!flags.json && !flags.quiet) console.log('');
+  } catch (e) {
+    if (flags.json) console.log(JSON.stringify({ path: rel, canFix: false, error: e.message }, null, 2));
+    else console.error(`  ${red('✗')} ${e.message}`);
+    return false;
+  }
+
+  if (flags.json) console.log(JSON.stringify({ path: rel, ...res }, null, 2));
+
+  if (!res.canFix) {
+    if (!flags.json) {
+      if (res.reason === 'clean') console.log(`  ${green('✓')} ${dim(rel + ' - nothing to fix.')}`);
+      else if (res.reason === 'ai-disabled') {
+        console.log(`  ${yellow('⚠')} ${res.message}`);
+        for (const g of res.guidance || []) {
+          console.log(`     ${SEV_COLOR[g.severity](String(g.severity).padEnd(8))} ${g.title}`);
+          if (g.remediationText) console.log(`     ${dim('fix: ' + g.remediationText)}`);
+        }
+        console.log('');
+      } else console.log(`  ${yellow('⚠')} ${dim(rel + ' - ')}${res.message || 'no fix produced.'}`);
+    }
+    return false;
+  }
+
+  if (!flags.json) {
+    printDiff(res.diff);
+    if (res.explanation) console.log(`  ${dim(res.explanation)}`);
+    const conf = res.confidence != null ? `  ${dim('confidence ' + Math.round(res.confidence * 100) + '%')}` : '';
+    if (conf) console.log(conf);
+    console.log('');
+  }
+
+  const apply = flags.apply || flags.write || flags.yes;
+  if (!apply) {
+    if (!flags.json) console.log(`  ${dim('Preview only - re-run with')} ${bold('--apply')} ${dim('to write this fix to ' + rel + '.')}\n`);
+    return true;
+  }
+  try {
+    fs.writeFileSync(target, res.fixedContent, 'utf8');
+    if (!flags.json && !flags.quiet) {
+      console.log(`  ${green('✓ Applied')} ${dim('→ ' + rel + '  (' + (res.findingCount || (res.findings || []).length) + ' finding(s) addressed)')}\n`);
+    }
+    return true;
+  } catch (e) {
+    if (!flags.json) console.error(`  ${red('✗')} could not write ${rel}: ${e.message}`);
+    return false;
+  }
+}
+
+function printDiff(diff) {
+  if (!diff) return;
+  for (const line of String(diff).split('\n')) {
+    if (line.startsWith('+') && !line.startsWith('+++')) console.log('  ' + green(line));
+    else if (line.startsWith('-') && !line.startsWith('---')) console.log('  ' + red(line));
+    else if (line.startsWith('@@')) console.log('  ' + cyan(line));
+    else console.log('  ' + dim(line));
+  }
+}

package/src/commands/gate.mjs

@@ -0,0 +1,154 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { walkArtifacts } from '../artifacts/matchers.mjs';
+import { api, gateMachine } from '../core/api-client.mjs';
+import { loadConfig, resolveSettings } from '../core/config.mjs';
+import { EXIT_USAGE } from '../core/exit-codes.mjs';
+import { bold, cyan, dim, green, red, yellow } from '../core/terminal.mjs';
+import { localGate } from '../detect/guard-signals.mjs';
+import { failOnHit, gateArtifactList } from '../gate/batch.mjs';
+import { GATE_KINDS, collectSiblings, detectEnv } from '../gate/environment.mjs';
+import { localAsGateResult, printGateResult } from '../gate/result.mjs';
+import { toSarif } from '../gate/sarif.mjs';
+import { collectLocalSast, mergeSastIntoResult } from '../gate/sast.mjs';
+
+const GATE_USAGE = 'shomra gate <file> [--kind mcp|skill|command|subagent|hook|rules|agent-card|memory] [--name x] [--strict] [--json]';
+
+function resolveGateFile(file) {
+  let target = path.resolve(String(file));
+
+  if (fs.existsSync(target) && fs.statSync(target).isDirectory()) {
+    const skillFile = path.join(target, 'SKILL.md');
+    if (!fs.existsSync(skillFile)) {
+      console.error(`${red('✗')} ${file} is a directory with no SKILL.md - point at a file instead.`);
+      process.exit(EXIT_USAGE);
+    }
+    target = skillFile;
+  }
+  if (!fs.existsSync(target)) {
+    console.error(`${red('✗')} File not found: ${file}`);
+    process.exit(EXIT_USAGE);
+  }
+  return target;
+}
+
+function readGateTarget(flags, positional) {
+  if (flags.stdin) {
+    return { content: fs.readFileSync(0, 'utf8'), relPath: flags.path || null, fullTarget: null };
+  }
+
+  const file = positional[0];
+  if (!file) {
+    console.error(`${red('✗')} Usage: ${bold(GATE_USAGE)}`);
+    process.exit(EXIT_USAGE);
+  }
+  const target = resolveGateFile(file);
+  return {
+    content: fs.readFileSync(target, 'utf8'),
+    relPath: path.relative(process.cwd(), target).split(path.sep).join('/'),
+    fullTarget: target,
+  };
+}
+
+async function requestGateVerdict({ url, apiKey, flags, kind, relPath, content, fullTarget }) {
+  if (!flags.json) process.stdout.write(dim('  Checking with Shomra gate… '));
+  try {
+    const siblings = collectSiblings(fullTarget, relPath);
+    const verdict = await api(url, apiKey, '/gate/check', {
+      ...(kind ? { kind } : {}),
+      ...(flags.name ? { name: String(flags.name) } : {}),
+      ...(relPath ? { path: relPath } : {}),
+      content,
+      ...(siblings.length ? { siblings } : {}),
+      machine: gateMachine(),
+      env: detectEnv(),
+      ...(flags.project ? { projectId: String(flags.project) } : {}),
+    });
+    if (!flags.json) console.log('');
+    return { verdict };
+  } catch (error) {
+    if (!flags.json) {
+      console.log(yellow('backend unavailable'));
+      console.error(`  ${yellow('⚠')} ${error.message} ${dim('- falling back to on-machine analysis')}`);
+    }
+    return { verdict: null };
+  }
+}
+
+export async function cmdGate(flags, positional) {
+  const { apiKey, url } = resolveSettings(loadConfig());
+  if (flags.all) return cmdGateAll(flags, positional, { apiKey, url });
+
+  const { content, relPath, fullTarget } = readGateTarget(flags, positional);
+  const kind = flags.kind && GATE_KINDS.includes(String(flags.kind)) ? String(flags.kind) : undefined;
+  const name = flags.name ? String(flags.name) : (relPath ? relPath.split('/').pop() : 'artifact');
+  const local = localGate(content, { kind, path: relPath });
+
+  let serverVerdict = null;
+  if (apiKey) {
+    ({ verdict: serverVerdict } = await requestGateVerdict({ url, apiKey, flags, kind, relPath, content, fullTarget }));
+    if (!serverVerdict && flags.strict) {
+      printGateResult(localAsGateResult(local, name, kind), 'local', flags);
+      if (!flags.json) console.log(`  ${red('✗ Failing closed (--strict): backend unreachable, org policy unverified.')}\n`);
+      process.exitCode = 1;
+      return;
+    }
+  } else if (!flags.json) {
+    console.error(`  ${dim('Not enrolled - on-machine analysis only. Run')} ${bold('shomra init')} ${dim('to also apply org policy.')}`);
+  }
+
+  const base = serverVerdict || localAsGateResult(local, name, kind);
+  const result = mergeSastIntoResult(base, collectLocalSast({ fullPath: fullTarget, relPath, kind, content }));
+  printGateResult(result, serverVerdict ? 'server' : 'local', flags);
+
+  if (result.decision === 'BLOCK') process.exitCode = 1;
+  else if (result.decision === 'FLAG' && flags.strict) process.exitCode = 2;
+}
+
+async function cmdGateAll(flags, positional, { apiKey, url }) {
+
+  const dirArg = typeof flags.all === 'string' ? flags.all : positional[0] || '.';
+  const root = path.resolve(dirArg);
+  const env = detectEnv();
+  const artifacts = walkArtifacts(root);
+
+  if (!artifacts.length) {
+    if (flags.json) console.log(JSON.stringify({ scanned: 0, results: [] }, null, 2));
+    else console.log(dim(`\n  No AI artifacts found under ${root}. Nothing to gate.\n`));
+    return;
+  }
+
+  if (!flags.json && !flags.sarif) console.log(bold(cyan('\n  Shomra gate')) + dim(` - batch (${artifacts.length} artifact${artifacts.length > 1 ? 's' : ''} · ${env.environment}${env.ciProvider ? ' · ' + env.ciProvider : ''})`));
+
+  const { results, blocked, flagged, suppressed, backendDown, rejected } = await gateArtifactList(artifacts, { apiKey, url, env, flags, root });
+
+  const strictOutage = backendDown && flags.strict;
+
+  if (flags.sarif) {
+    console.log(JSON.stringify(toSarif(results), null, 2));
+    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;
+    return;
+  }
+  if (flags.json) {
+    console.log(JSON.stringify({ scanned: results.length, blocked, flagged, suppressed, backendDown, rejected, environment: env.environment, results }, null, 2));
+  } else {
+    console.log(
+      '\n  ' +
+        (blocked > 0
+          ? red(`✗ ${blocked} blocked`) + dim(` · ${flagged} flagged · ${results.length - blocked - flagged} allowed`)
+          : flagged > 0
+            ? yellow(`⚠ ${flagged} flagged`) + dim(` · ${results.length - flagged} allowed`)
+            : green(`✓ All ${results.length} artifacts allowed.`)) +
+        (suppressed ? dim(` · ${suppressed} suppressed`) : '') +
+        (backendDown ? yellow('  (on-machine analysis - org policy not applied)') : dim(' - full activity in the Shomra dashboard → Gate Activity')) +
+        '\n',
+    );
+    if (strictOutage) console.log(`  ${red('✗ Failing closed (--strict): backend unreachable, org policy unverified.')}\n`);
+  }
+
+  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;
+}