@shomra/agent 0.3.16 → 0.3.18

package/src/commands/status.mjs

@@ -0,0 +1,50 @@
+import os from 'node:os';
+import { agentHookInstalled } from '../agents/hook-files.mjs';
+import { AGENT_KEYS, AGENT_LABELS } from '../agents/installers.mjs';
+import { keyScope } from '../core/api-key.mjs';
+import { breakerCooldownMs, breakerOpen, guardTimeoutMs } from '../core/circuit-breaker.mjs';
+import { CONFIG_FILE, loadConfig, resolveSettings } from '../core/config.mjs';
+import { bold, cyan, dim, gray, green, red, yellow } from '../core/terminal.mjs';
+import { VERSION } from '../core/version.mjs';
+import { envFlag } from '../guard/options.mjs';
+
+export function cmdStatus() {
+  const cfg = loadConfig();
+  const { apiKey, url } = resolveSettings(cfg);
+  const enrolled = !!apiKey;
+  console.log(bold(cyan('\n  Shomra agent')) + dim(` v${VERSION}`));
+
+  if (enrolled) {
+    console.log(`  ${dim('Mode     ')} ${green('● Enrolled')} ${dim(`(${keyScope(apiKey)} key)`)} - org policy, platform AI & dashboard telemetry active`);
+  } else {
+    console.log(`  ${dim('Mode     ')} ${cyan('● Local')} ${dim('- on-machine analysis only; nothing leaves this machine')}`);
+    console.log(`  ${dim('         ')} ${dim('Run')} ${bold('shomra init --key shm_…')} ${dim('to add org policy, AI fixes, deep scans & the dashboard.')}`);
+  }
+  console.log(`  ${dim('Backend  ')} ${url || dim('none (local mode - set with shomra init --url)')}`);
+  console.log(`  ${dim('API key  ')} ${apiKey ? green(apiKey.slice(0, 14) + '…') : dim('none (local mode)')}`);
+  console.log(`  ${dim('Machine  ')} ${os.hostname()} ${dim('(' + (cfg.machineId || 'unenrolled') + ')')}`);
+  console.log(`  ${dim('Config   ')} ${CONFIG_FILE}`);
+
+  console.log(bold('\n  Available now') + dim(enrolled ? '' : ' (local, no key)'));
+  console.log(`  ${green('✓')} ${dim('check · gate · doctor · protect · secrets · models · new · mcp add · why (offline)')}`);
+  console.log(`  ${enrolled ? green('✓') : gray('○')} ${(enrolled ? dim : gray)('fix (AI) · deep scans (scan-zip/model-scan/memory-scan) · org policy · dashboard telemetry')}`);
+
+  const localOff = process.env.SHOMRA_GUARD_LOCAL === '0' || String(process.env.SHOMRA_GUARD_LOCAL).toLowerCase() === 'false';
+  const strict = envFlag('SHOMRA_GUARD_STRICT');
+  console.log(bold('\n  Runtime firewall'));
+  const installedAgents = AGENT_KEYS.map((a) => ({ agent: a, files: agentHookInstalled(a) })).filter((x) => x.files.length);
+  if (installedAgents.length) {
+    let first = true;
+    for (const { agent, files } of installedAgents) {
+      console.log(`  ${dim(first ? 'Hooks    ' : '         ')} ${green('installed')} ${bold(AGENT_LABELS[agent])} ${dim('→ ' + files.join(', '))}`);
+      first = false;
+    }
+    const missing = AGENT_KEYS.filter((a) => !installedAgents.some((i) => i.agent === a));
+    if (missing.length) console.log(`  ${dim('         ')} ${dim('not installed: ' + missing.map((m) => AGENT_LABELS[m]).join(', '))}`);
+  } else {
+    console.log(`  ${dim('Hooks    ')} ${yellow('not installed for any agent')}${dim('  (run: shomra install-hook --agent all  or  shomra protect)')}`);
+  }
+  console.log(`  ${dim('Tier 0   ')} ${localOff ? yellow('off') + dim(' (server-only)') : green('on') + dim(' - dangerous calls blocked on-machine, zero network')}`);
+  console.log(`  ${dim('Mode     ')} ${strict ? 'fail-closed (strict)' : 'fail-open'}${dim(` · server timeout ${guardTimeoutMs()}ms · breaker ${breakerCooldownMs()}ms`)}`);
+  console.log(`  ${dim('Breaker  ')} ${breakerOpen() ? red('OPEN') + dim(' - backend recently unreachable; server tier is being skipped') : green('closed')}\n`);
+}

package/src/commands/why.mjs

@@ -0,0 +1,88 @@
+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 { localGate } from '../detect/guard-signals.mjs';
+import { GATE_KINDS } from '../gate/environment.mjs';
+
+export async function cmdWhy(flags, positional) {
+  const file = positional[0];
+  if (!file) {
+    console.error(red('✗') + ' Usage: ' + bold('shomra why <file> [--kind mcp|skill|command|subagent|hook|rules] [--json]'));
+    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);
+  }
+  const content = fs.readFileSync(target, 'utf8');
+  const rel = path.relative(process.cwd(), target).split(path.sep).join('/');
+  const kind = flags.kind && GATE_KINDS.includes(String(flags.kind)) ? String(flags.kind) : undefined;
+
+  const cfg = loadConfig();
+  const { apiKey, url } = resolveSettings(cfg);
+
+  if (apiKey) {
+    try {
+      if (!flags.json) process.stdout.write(dim(`  Explaining ${rel}… `));
+      const res = await api(url, apiKey, '/gate/explain', { ...(kind ? { kind } : {}), path: rel, name: rel.split('/').pop(), content });
+      if (!flags.json) console.log('');
+      if (flags.json) console.log(JSON.stringify({ path: rel, ...res }, null, 2));
+      else printWhy(res);
+      return;
+    } catch (e) {
+      if (!flags.json) console.log(yellow('backend unavailable') + dim(` - on-machine explanation (${e.message})`));
+
+    }
+  }
+  whyLocal(content, kind, rel, flags);
+}
+
+function whyLocal(content, kind, rel, flags) {
+  const local = localGate(content, { kind, path: rel });
+  if (flags.json) {
+    console.log(JSON.stringify({ path: rel, source: 'local', ...local }, null, 2));
+    return;
+  }
+  console.log(bold(cyan('\n  Shomra why')) + dim(` - ${rel} · on-machine`));
+  if (!local.findings.length) {
+    console.log(green('\n  ✓ No findings - nothing to explain.\n'));
+    return;
+  }
+  for (const f of local.findings) {
+    const at = f.line ? dim(` (line ${f.line})`) : '';
+    console.log(`\n  ${SEV_COLOR[f.severity]('●')} ${SEV_COLOR[f.severity](f.severity)}  ${bold(f.title)}${at}`);
+    if (f.remediationText) console.log(`     ${dim('fix: ' + f.remediationText)}`);
+  }
+  console.log(dim('\n  Enroll (') + bold('shomra init') + dim(') for an AI-distilled why + false-positive read.\n'));
+}
+
+function printWhy(res) {
+  console.log(bold(cyan('\n  Shomra why')) + dim(` - ${res.path}${res.aiEnabled ? '' : ' · rule rationale (AI off)'}`));
+  if (res.summary) console.log('  ' + res.summary);
+  if (!res.findings || !res.findings.length) {
+    console.log(green('\n  ✓ Nothing to explain.\n'));
+    return;
+  }
+  for (const f of res.findings) {
+    const at = f.line ? dim(` (line ${f.line})`) : '';
+    const fp = f.likelyFalsePositive ? yellow('  · likely false positive') : '';
+    console.log(`\n  ${SEV_COLOR[f.severity]('●')} ${SEV_COLOR[f.severity](f.severity)}  ${bold(f.title)}${at}${fp}`);
+    if (f.why) console.log(`     ${f.why}`);
+    if (f.exploit) console.log(`     ${dim('exploit: ' + f.exploit)}`);
+    if (f.assessment) console.log(`     ${dim(f.assessment)}`);
+    if (f.remediationText) console.log(`     ${dim('fix: ' + f.remediationText)}`);
+  }
+  console.log('');
+}

package/src/core/api-client.mjs

@@ -0,0 +1,66 @@
+import os from 'node:os';
+import { getMachineId, loadConfig } from './config.mjs';
+import { clampInt } from './numbers.mjs';
+import { VERSION } from './version.mjs';
+
+export function gateMachine() {
+  let machineId;
+  try {
+    machineId = loadConfig().machineId;
+  } catch {
+
+  }
+  return { ...(machineId ? { machineId } : {}), hostname: os.hostname(), username: os.userInfo().username };
+}
+
+export function machineInfo(cfg) {
+  return {
+    machineId: getMachineId(cfg),
+    hostname: os.hostname(),
+    platform: process.platform,
+    osRelease: os.release(),
+    username: os.userInfo().username,
+    agentVersion: VERSION,
+  };
+}
+
+export async function api(url, key, route, body, opts = {}) {
+
+  if (!url) throw new Error('no backend configured - set SHOMRA_URL or run `shomra init --url <your backend>`');
+
+  const timeoutMs = opts.timeoutMs ?? clampInt(process.env.SHOMRA_API_TIMEOUT_MS, 30000, 1000, 600000);
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  let res;
+  try {
+    const method = opts.method ?? 'POST';
+    res = await fetch(`${url}${route}`, {
+      method,
+
+      headers: { 'Content-Type': 'application/json', 'X-Shomra-Key': key, Connection: 'close' },
+      ...(method === 'GET' ? {} : { body: JSON.stringify(body) }),
+      signal: ctrl.signal,
+    });
+  } catch (e) {
+    if (e?.name === 'AbortError') throw new Error(`request timed out after ${timeoutMs}ms (raise SHOMRA_API_TIMEOUT_MS or check the backend)`);
+    throw e;
+  } finally {
+    clearTimeout(timer);
+  }
+  const text = await res.text();
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    json = { raw: text };
+  }
+  if (!res.ok) {
+    const msg = json?.message || json?.raw || res.statusText;
+    const err = new Error(`${res.status} ${Array.isArray(msg) ? msg.join(', ') : msg}`);
+
+    err.status = res.status;
+    err.rejected = res.status >= 400 && res.status < 500 && res.status !== 408 && res.status !== 429;
+    throw err;
+  }
+  return json;
+}

package/src/core/api-key.mjs

@@ -0,0 +1,6 @@
+export function keyScope(key) {
+  if (!key) return null;
+  if (/^(shm|dgx)_gw_/.test(key)) return 'gateway';
+  if (/^(shm|dgx)_ci_/.test(key)) return 'CI';
+  return 'agent';
+}

package/src/core/circuit-breaker.mjs

@@ -0,0 +1,42 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { CONFIG_DIR } from './config.mjs';
+import { clampInt } from './numbers.mjs';
+
+const BREAKER_FILE = path.join(CONFIG_DIR, 'guard-breaker.json');
+
+export function guardTimeoutMs() {
+  return clampInt(process.env.SHOMRA_GUARD_TIMEOUT_MS, 2000, 200, 30000);
+}
+
+export function breakerCooldownMs() {
+  return clampInt(process.env.SHOMRA_GUARD_BREAKER_MS, 30000, 0, 600000);
+}
+
+export function breakerOpen() {
+  const cooldown = breakerCooldownMs();
+  if (cooldown === 0) return false;
+  try {
+    const { at } = JSON.parse(fs.readFileSync(BREAKER_FILE, 'utf8'));
+    return typeof at === 'number' && Date.now() - at < cooldown;
+  } catch {
+    return false;
+  }
+}
+
+export function breakerTrip() {
+  try {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    fs.writeFileSync(BREAKER_FILE, JSON.stringify({ at: Date.now() }));
+  } catch {
+
+  }
+}
+
+export function breakerReset() {
+  try {
+    fs.rmSync(BREAKER_FILE, { force: true });
+  } catch {
+
+  }
+}

package/src/core/config.mjs

@@ -0,0 +1,37 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const CONFIG_DIR = path.join(os.homedir(), '.shomra');
+
+export const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+export function loadConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+export function saveConfig(cfg) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2));
+}
+
+export function getMachineId(cfg) {
+  if (cfg.machineId) return cfg.machineId;
+  cfg.machineId = crypto.randomUUID();
+  saveConfig(cfg);
+  return cfg.machineId;
+}
+
+export function resolveSettings(cfg) {
+
+  const raw = process.env.SHOMRA_URL || cfg.url || '';
+  return {
+    apiKey: process.env.SHOMRA_API_KEY || cfg.apiKey,
+    url: raw ? raw.replace(/\/$/, '').replace('://localhost', '://127.0.0.1') : null,
+  };
+}

package/src/core/exit-codes.mjs

@@ -0,0 +1,9 @@
+import { bold, dim, red } from './terminal.mjs';
+
+export const EXIT_USAGE = 3;
+
+export function exitNotConfigured() {
+  console.error('\n' + red('✗') + ' Not configured. Run ' + bold('shomra init --key shm_live_… --url <your backend>') + ' first.');
+  console.error('  ' + dim('Get a key in the Shomra app → Settings → API Keys.'));
+  process.exit(EXIT_USAGE);
+}

package/src/core/json-file.mjs

@@ -0,0 +1,13 @@
+import fs from 'node:fs';
+import { EXIT_USAGE } from './exit-codes.mjs';
+import { red } from './terminal.mjs';
+
+export function readJsonFile(file) {
+  if (!fs.existsSync(file)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    console.error(red('✗') + ` ${file} is not valid JSON - fix or move it first.`);
+    process.exit(EXIT_USAGE);
+  }
+}

package/src/core/numbers.mjs

@@ -0,0 +1,4 @@
+export function clampInt(v, def, min, max) {
+  const n = parseInt(v, 10);
+  return Number.isFinite(n) ? Math.min(max, Math.max(min, n)) : def;
+}

package/src/core/package-root.mjs

@@ -0,0 +1,10 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const CORE_DIR = path.dirname(fileURLToPath(import.meta.url));
+
+export const PACKAGE_ROOT = path.resolve(CORE_DIR, '..', '..');
+
+export const PACKAGE_MANIFEST_PATH = path.join(PACKAGE_ROOT, 'package.json');
+
+export const CLI_ENTRY_PATH = path.join(PACKAGE_ROOT, 'shomra.mjs');

package/src/core/terminal.mjs

@@ -0,0 +1,16 @@
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+
+const ansi = (code) => (value) => (useColor ? `\x1b[${code}m${value}\x1b[0m` : String(value));
+
+export const bold = ansi('1');
+export const dim = ansi('2');
+export const red = ansi('31');
+export const green = ansi('32');
+export const yellow = ansi('33');
+export const magenta = ansi('35');
+export const cyan = ansi('36');
+export const gray = ansi('90');
+
+export const SEV_COLOR = { CRITICAL: red, HIGH: red, MEDIUM: yellow, LOW: cyan, INFO: gray };
+
+export const VERDICT_COLOR = { FAIL: red, REVIEW: yellow, PASS: green };

package/src/core/version.mjs

@@ -0,0 +1,14 @@
+import fs from 'node:fs';
+import { PACKAGE_MANIFEST_PATH } from './package-root.mjs';
+
+const FALLBACK_VERSION = '0.0.0';
+
+function readPackageVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(PACKAGE_MANIFEST_PATH, 'utf8')).version ?? FALLBACK_VERSION;
+  } catch {
+    return FALLBACK_VERSION;
+  }
+}
+
+export const VERSION = readPackageVersion();

package/src/core/wire-limits.mjs

@@ -0,0 +1,53 @@
+
+import { createHash } from 'node:crypto';
+
+export const WIRE_LIMITS = {
+  asset: { name: 255, identifier: 1024, content: 200_000 },
+  artifact: { name: 200, path: 1024, content: 200_000 },
+  artifactFile: { path: 1024, content: 200_000 },
+};
+
+const FINGERPRINT = 12;
+
+export function clampField(value, max) {
+  if (typeof value !== 'string' || value.length <= max) return value;
+  const digest = createHash('sha256').update(value).digest('hex').slice(0, 10);
+  return `${value.slice(0, Math.max(1, max - FINGERPRINT))}…#${digest}`;
+}
+
+export function clampAsset(asset) {
+  const L = WIRE_LIMITS.asset;
+  return {
+    ...asset,
+    name: clampField(asset.name, L.name),
+    ...(asset.identifier != null ? { identifier: clampField(asset.identifier, L.identifier) } : {}),
+    ...(typeof asset.content === 'string' && asset.content.length > L.content
+      ? { content: asset.content.slice(0, L.content) }
+      : {}),
+  };
+}
+
+export function clampArtifact(artifact) {
+  const L = WIRE_LIMITS.artifact;
+  const F = WIRE_LIMITS.artifactFile;
+  return {
+    ...artifact,
+    name: clampField(artifact.name, L.name),
+    path: clampField(artifact.path, L.path),
+    ...(typeof artifact.content === 'string' && artifact.content.length > L.content
+      ? { content: artifact.content.slice(0, L.content) }
+      : {}),
+    ...(Array.isArray(artifact.files)
+      ? {
+          files: artifact.files.map((f) => ({
+            ...f,
+            path: clampField(f.path, F.path),
+
+            ...(typeof f.content === 'string' && f.content.length > F.content
+              ? { content: f.content.slice(0, F.content) }
+              : {}),
+          })),
+        }
+      : {}),
+  };
+}

package/src/corpus/screening.mjs

@@ -0,0 +1,127 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { MAX_ARTIFACT_BYTES, SKIP_DIRS } from '../artifacts/matchers.mjs';
+import { INVISIBLE_CHARS_RE, downrankCodeContext, localScan } from '../detect/guard-signals.mjs';
+
+export const CORPUS_TEXT_RE = /\.(md|markdown|txt|rst|adoc|html?|json|jsonl|ya?ml|csv|tsv|tex)$/i;
+export const CORPUS_OPAQUE_RE = /\.(pdf|docx?|pptx?|xlsx?|epub|rtf|odt|pages|key|numbers)$/i;
+export const CORPUS_DEFAULT_CHUNK = 1200;
+
+const CORPUS_MAX_FILES = 5000;
+const MAX_FINDINGS_PER_DOC = 6;
+const OPAQUE_REASON = 'binary format - no text extractor';
+const SCAN_CATEGORIES = ['injection', 'secret', 'pii'];
+
+export function chunkIndexForLine(text, line, chunkSize) {
+  if (!line || line < 1) return null;
+  const lines = text.split(/\r?\n/);
+  let offset = 0;
+  for (let index = 0; index < Math.min(line - 1, lines.length); index += 1) offset += lines[index].length + 1;
+  return Math.floor(offset / chunkSize);
+}
+
+export function walkCorpus(root) {
+  const files = [];
+  const opaque = [];
+  const stack = [root];
+
+  while (stack.length && files.length + opaque.length < CORPUS_MAX_FILES) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name)) stack.push(full);
+        continue;
+      }
+      const rel = path.relative(root, full).split(path.sep).join('/');
+      if (CORPUS_TEXT_RE.test(entry.name)) files.push({ full, rel });
+      else if (CORPUS_OPAQUE_RE.test(entry.name)) opaque.push({ full, rel, reason: OPAQUE_REASON });
+    }
+  }
+  return { files, opaque };
+}
+
+export function collectCorpusFiles(absolutePath, isDirectory) {
+  if (isDirectory) return walkCorpus(absolutePath);
+  return {
+    files: CORPUS_TEXT_RE.test(absolutePath) ? [{ full: absolutePath, rel: path.basename(absolutePath) }] : [],
+    opaque: CORPUS_OPAQUE_RE.test(absolutePath)
+      ? [{ full: absolutePath, rel: path.basename(absolutePath), reason: OPAQUE_REASON }]
+      : [],
+  };
+}
+
+function readDocument(file) {
+  try {
+    const { size } = fs.statSync(file.full);
+    if (size > MAX_ARTIFACT_BYTES) return { reason: `too large (${Math.round(size / 1e6)}MB)` };
+    const text = fs.readFileSync(file.full, 'utf8');
+    if (text.includes('\0')) return { reason: 'not UTF-8 text' };
+    return { text };
+  } catch (error) {
+    return { reason: error.message };
+  }
+}
+
+function documentVerdict(scanFindings, rankedFindings, hasInvisibleChars) {
+  const liveInjection = scanFindings.some((f) => f.category === 'injection' && !f.codeContext);
+  const liveCritical = scanFindings.some((f) => f.severity === 'CRITICAL' && !f.codeContext);
+  if (liveInjection || liveCritical || hasInvisibleChars) return 'BLOCK';
+  return rankedFindings.length ? 'FLAG' : 'ALLOW';
+}
+
+function findingRows(findings, text, chunkSize) {
+  return findings.slice(0, MAX_FINDINGS_PER_DOC).map((finding) => ({
+    severity: finding.severity,
+    category: finding.category,
+    label: finding.label,
+    line: finding.line ?? null,
+    chunk: chunkIndexForLine(text, finding.line, chunkSize),
+    codeContext: !!finding.codeContext,
+    concealed: !!finding.concealed,
+  }));
+}
+
+export function screenCorpus(files, opaque, chunkSize) {
+  const results = [];
+  const unreadable = [...opaque];
+
+  for (const file of files) {
+    const read = readDocument(file);
+    if (!read.text) {
+      unreadable.push({ ...file, reason: read.reason });
+      continue;
+    }
+
+    const scan = localScan(read.text, { categories: SCAN_CATEGORIES });
+    const ranked = downrankCodeContext(scan.findings || []);
+    const hasInvisibleChars = INVISIBLE_CHARS_RE.test(read.text);
+    const verdict = documentVerdict(scan.findings, ranked, hasInvisibleChars);
+
+    if (verdict === 'ALLOW') {
+      results.push({ path: file.rel, verdict, findings: [] });
+      continue;
+    }
+
+    const rows = findingRows(ranked, read.text, chunkSize);
+    if (hasInvisibleChars) {
+      rows.unshift({
+        severity: 'CRITICAL',
+        category: 'injection',
+        label: 'Invisible / bidirectional characters',
+        line: null,
+        chunk: null,
+        codeContext: false,
+      });
+    }
+    results.push({ path: file.rel, verdict, findings: rows });
+  }
+
+  return { results, unreadable };
+}

package/{ai-usage.mjs → src/detect/ai-usage.mjs}

@@ -1,16 +1,4 @@
-/**
- * AI-USAGE inventory extractor (CLI port of the backend's checks/ai-usage.ts,
- * kept in sync so both surfaces detect the same thing). Finds where a repo USES
- * an LLM/AI provider in its own source — SDK imports + provider-specific call
- * sites — so `shomra` can inventory "this code talks to OpenAI / a local model"
- * as plain shadow-AI usage, independent of whether that usage is vulnerable.
- *
- * Dependency-free, line-oriented, low-false-positive: a provider is only claimed
- * when a line either IMPORTS its SDK module or matches a provider-specific CALL
- * signature — never from a bare mention of the word "openai" in prose.
- */
 
-/** Human label per category — shared by the report + backend. */
 export const AI_USAGE_CATEGORY_LABEL = {
   'llm-api': 'hosted LLM API',
   'llm-framework': 'LLM framework',
@@ -18,7 +6,6 @@ export const AI_USAGE_CATEGORY_LABEL = {
   'inference-gateway': 'inference gateway',
 };
 
-// The provider catalog — every entry is an LLM/AI *usage* surface.
 const PROVIDERS = [
   { id: 'openai', label: 'OpenAI', category: 'llm-api', npm: ['openai'], npmPrefix: ['@azure/openai'], py: ['openai'],
     call: [/\b(?:Async)?(?:Azure)?OpenAI\s*\(/, /\bchat\.completions\.create\s*\(/, /\bresponses\.create\s*\(/, /\bembeddings\.create\s*\(/, /\bChatCompletion\.create\s*\(/, /\bopenai\.(?:ChatCompletion|Completion|Embedding)\b/] },
@@ -60,17 +47,6 @@ const PROVIDERS = [
   { id: 'llama-cpp', label: 'llama.cpp', category: 'local-runtime', npm: ['node-llama-cpp'], py: ['llama_cpp'], call: [/\bLlama\s*\(\s*model_path\s*=/] },
 ];
 
-/**
- * Every AI package name this catalog knows, flattened for name comparison at
- * ACQUISITION time (`shomra add package`). A typosquat is only detectable
- * against a list of the real names, and this catalog is already that list —
- * maintaining a second copy is how the two drift and the check quietly stops
- * matching the packages people actually install.
- *
- * `ecosystem` matters: `openai` exists on both npm and PyPI, but `crewai` is
- * PyPI-only, so `npm i crewai` is a different and more suspicious event than
- * `pip install crewai`.
- */
 export const KNOWN_AI_PACKAGES = (() => {
   const out = [];
   const seen = new Set();
@@ -117,7 +93,6 @@ function importMatches(spec, p) {
   return false;
 }
 
-/** Extract AI-usage sightings from one source file's text. */
 export function scanAiUsage(text, file = '') {
   if (!text || !isAiUsageScannable(file)) return [];
   const out = [];
@@ -155,10 +130,8 @@ export function scanAiUsage(text, file = '') {
   return out;
 }
 
-/** Cap on individual sites carried per provider row. */
 const MAX_SITES_PER_PROVIDER = 60;
 
-/** One inventory row per provider, aggregated across all files. */
 export function rollupAiUsage(usages) {
   const byProvider = new Map();
   for (const u of usages) {

package/src/detect/code-sast.mjs

@@ -0,0 +1,2 @@
+export { isStaticPathExpr } from './sast/path-expressions.mjs';
+export { isModelConfig, isScannableSource, scanJsSource, scanModelConfig, scanNotebook, scanPythonSource, scanSourceFile } from './sast/scanner.mjs';