@shomra/agent 0.3.17 → 0.3.18

package/src/commands/rules.mjs

@@ -0,0 +1,220 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { api, gateMachine } from '../core/api-client.mjs';
+import { loadConfig, resolveSettings } from '../core/config.mjs';
+import { bold, cyan, dim, green, red, yellow } from '../core/terminal.mjs';
+import { localGate } from '../detect/guard-signals.mjs';
+import { detectEnv } from '../gate/environment.mjs';
+import { DEC_RANK } from '../gate/sast.mjs';
+import { rulesContext } from '../rules/context.mjs';
+import { generateRules, mergeRulesBlock, resolveRulesTargets, rulesBlock } from '../rules/generate.mjs';
+import { RULES_BEGIN, RULES_TARGETS } from '../rules/sections.mjs';
+
+const ORG_POLICY_TIMEOUT_MS = 5000;
+const MAX_ORG_DIRECTIVES = 20;
+
+const plural = (count, word) => `${word}${count === 1 ? '' : 's'}`;
+
+async function fetchOrgDirectives(root, flags) {
+  const { apiKey, url } = resolveSettings(loadConfig());
+  if (!apiKey || !url || flags['no-policy']) return { apiKey, orgLines: [], orgError: null };
+
+  try {
+    const response = await api(
+      url,
+      apiKey,
+      '/gate/rules',
+      { cwd: root, env: detectEnv(), machine: gateMachine() },
+      { timeoutMs: ORG_POLICY_TIMEOUT_MS },
+    );
+    const directives = Array.isArray(response?.directives) ? response.directives : [];
+    const orgLines = directives.filter((line) => typeof line === 'string' && line.trim()).slice(0, MAX_ORG_DIRECTIVES);
+    return { apiKey, orgLines, orgError: null };
+  } catch (error) {
+    return { apiKey, orgLines: [], orgError: error.message };
+  }
+}
+
+function gateRank(content, targetFile) {
+  try {
+    return DEC_RANK[localGate(content, { kind: 'rules', path: targetFile }).verdict] ?? 0;
+  } catch {
+    return 0;
+  }
+}
+
+function planTarget(root, key, block) {
+  const target = RULES_TARGETS[key];
+  const absolutePath = path.join(root, target.file);
+
+  let existing = '';
+  try {
+    existing = fs.readFileSync(absolutePath, 'utf8');
+  } catch {
+    existing = '';
+  }
+
+  const next = mergeRulesBlock(existing, block, target);
+  const hadBlock = existing.includes(RULES_BEGIN);
+  const worsens = next !== null && gateRank(next, target.file) > (existing ? gateRank(existing, target.file) : 0);
+
+  return {
+    key,
+    label: target.label,
+    file: target.file,
+    abs: absolutePath,
+    next,
+    worsens,
+    state: next === null ? 'current' : hadBlock ? 'stale' : 'absent',
+  };
+}
+
+function buildJsonReport({ root, sections, orgLines, orgError, gate, context, written, plan, flags, body }) {
+  return {
+    root,
+    sections,
+    orgDirectives: orgLines.length,
+    orgError,
+    gate: gate ? { verdict: gate.verdict, riskScore: gate.riskScore } : null,
+    observed: context.observed,
+    artifacts: context.artifactCount,
+    modelRefs: context.modelRefs,
+    aiUsage: context.aiUsage,
+    written,
+    targets: plan.map(({ key, label, file, state, worsens }) => ({
+      key, label, file, state, ...(worsens ? { skipped: 'would-worsen' } : {}),
+    })),
+    ...(flags.write ? {} : { block: body }),
+  };
+}
+
+function printDriftReport(plan, drifted) {
+  if (!drifted.length) {
+    console.log(`\n  ${green(`✓ Shomra rules current in ${plan.length} ${plural(plan.length, 'file')}.`)}\n`);
+    return;
+  }
+  console.log(`\n  ${red(`✗ Shomra rules out of date in ${drifted.length} ${plural(drifted.length, 'file')}:`)}`);
+  for (const target of drifted) {
+    const state = target.state === 'absent' ? red('absent') : yellow('stale ');
+    console.log(`    ${state} ${bold(target.file)} ${dim(`· ${target.label}`)}`);
+  }
+  console.log(dim('\n  Run ') + bold('shomra rules --write') + dim(' and commit the result.\n'));
+}
+
+function writeTarget(target, flags) {
+  if (target.state === 'current') {
+    if (!flags.json) console.log(`  ${yellow('•')} ${target.label} ${dim(`already current (${target.file})`)}`);
+    return { wrote: false, failed: false };
+  }
+  if (target.worsens) {
+    if (!flags.json) {
+      console.log(`  ${red('✗')} ${target.file} ${dim("- skipped: writing the block would raise this file's own gate verdict. Please report it.")}`);
+    }
+    return { wrote: false, failed: true };
+  }
+  try {
+    fs.mkdirSync(path.dirname(target.abs), { recursive: true });
+    fs.writeFileSync(target.abs, target.next);
+    if (!flags.json) {
+      console.log(`  ${green('✓')} ${target.state === 'stale' ? 'Updated' : 'Wrote'} ${bold(target.file)} ${dim(`· ${target.label}`)}`);
+    }
+    return { wrote: true, failed: false };
+  } catch (error) {
+    if (!flags.json) console.log(`  ${red('✗')} ${target.file} ${dim(`- ${error.message}`)}`);
+    return { wrote: false, failed: true };
+  }
+}
+
+function printWriteSummary(wrote, sections, orgLines) {
+  const headline = wrote
+    ? green(`✓ ${wrote} rules ${plural(wrote, 'file')} updated`)
+    : green('✓ Already current');
+  const orgNote = orgLines.length ? ` · ${orgLines.length} org ${plural(orgLines.length, 'directive')}` : '';
+  console.log(`\n  ${headline}${dim(` · ${sections.length} ${plural(sections.length, 'section')}${orgNote}`)}`);
+  console.log(dim('  Commit these - the agent reads them before it writes, so the blocked pattern is never generated.'));
+  console.log(dim('  Keep them honest in CI with ') + bold('shomra rules --check') + dim('.\n'));
+}
+
+function printPreview({ root, context, sections, apiKey, orgError, body, gate, plan }) {
+  const artifacts = `${context.artifactCount} ${plural(context.artifactCount, 'artifact')}`;
+  console.log(bold(cyan('\n  Shomra rules')) + dim(` - ${sections.length} ${plural(sections.length, 'section')} for ${artifacts} under ${root}`));
+
+  if (orgError) console.log(`  ${yellow('⚠')} ${dim(`org policy not applied - ${orgError}`)}`);
+  else if (!apiKey) console.log(`  ${dim('On-machine rules only - run')} ${bold('shomra init')} ${dim('to layer your org policy on top.')}`);
+
+  console.log('');
+  console.log(body.split('\n').map((line) => `  ${dim(line)}`).join('\n'));
+
+  const gateLabel = gate && gate.verdict === 'ALLOW'
+    ? green('✓ gate: clean')
+    : yellow(`gate: ${gate ? gate.verdict : 'unknown'}`);
+  console.log(`  ${gateLabel}${dim(" - the block passes Shomra's own rules-file check.")}`);
+  console.log('');
+
+  for (const target of plan) {
+    const mark = target.state === 'current' ? green('✓') : target.state === 'stale' ? yellow('~') : dim('+');
+    console.log(`  ${mark} ${bold(target.file)} ${dim(`· ${target.label} · ${target.state}`)}`);
+  }
+  console.log(dim('\n  Write them with ') + bold('shomra rules --write') + dim(' (nothing outside the markers is touched).\n'));
+}
+
+export async function cmdRules(flags, positional) {
+  const root = path.resolve(positional[0] || flags.path || '.');
+  const context = rulesContext(root);
+  const { apiKey, orgLines, orgError } = await fetchOrgDirectives(root, flags);
+
+  const { body, sections, gate, observedOmitted } = generateRules(context, { orgLines });
+  const block = rulesBlock(body);
+  const plan = resolveRulesTargets(root, flags).map((key) => planTarget(root, key, block));
+  const drifted = plan.filter((target) => target.state !== 'current');
+
+  const written = [];
+  const emitJson = () => {
+    if (!flags.json) return;
+    console.log(JSON.stringify(
+      buildJsonReport({ root, sections, orgLines, orgError, gate, context, written, plan, flags, body }),
+      null,
+      2,
+    ));
+  };
+
+  if (gate && gate.verdict === 'BLOCK') {
+    emitJson();
+    if (!flags.json) {
+      console.error(`\n${red('✗')} The generated block does not pass Shomra's own rules-file gate - refusing to write. This is a bug in the CLI; please report it.`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  if (observedOmitted && !flags.json) {
+    const issues = `${observedOmitted} ${plural(observedOmitted, 'issue')}`;
+    console.log(`  ${yellow('!')} ${dim(`Left out the "already present in this repo" section (${issues}) - quoting those titles tripped the rules gate. Run `)}${bold('shomra check')}${dim(' to see them.')}`);
+  }
+
+  if (flags.check) {
+    emitJson();
+    if (!flags.json) printDriftReport(plan, drifted);
+    if (drifted.length) process.exitCode = 1;
+    return;
+  }
+
+  if (flags.write) {
+    let wrote = 0;
+    for (const target of plan) {
+      const result = writeTarget(target, flags);
+      if (result.wrote) {
+        wrote += 1;
+        written.push(target.file);
+      }
+      if (result.failed) process.exitCode = 1;
+    }
+    emitJson();
+    if (!flags.json) printWriteSummary(wrote, sections, orgLines);
+    return;
+  }
+
+  emitJson();
+  if (flags.json) return;
+  printPreview({ root, context, sections, apiKey, orgError, body, gate, plan });
+}

package/src/commands/run.mjs

@@ -0,0 +1,128 @@
+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 { bold, cyan, dim, green, red, yellow } from '../core/terminal.mjs';
+
+const STEP_MARK = {
+  SUCCESS: () => green('✓'),
+  FAILED: () => red('✗'),
+  SKIPPED: () => dim('-'),
+  RUNNING: () => cyan('•'),
+  PENDING: () => dim('·'),
+};
+
+const NUMERIC = /^-?\d+(\.\d+)?$/;
+
+function coerceInputValue(raw) {
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+  return NUMERIC.test(raw) ? Number(raw) : raw;
+}
+
+function parseInputs(flags) {
+  const inputs = {};
+  for (const entry of [].concat(flags.input ?? [])) {
+    const text = String(entry);
+    const separator = text.indexOf('=');
+    if (separator < 0) {
+      console.error(`  ${red('✗')} --input expects key=value (got ${JSON.stringify(entry)})\n`);
+      process.exit(EXIT_USAGE);
+    }
+    inputs[text.slice(0, separator).trim()] = coerceInputValue(text.slice(separator + 1));
+  }
+  return inputs;
+}
+
+async function requestOrExit(request, flags) {
+  try {
+    return await request();
+  } catch (error) {
+    if (!flags.json) console.log(red('failed'));
+    console.error(`  ${red('✗')} ${error.message}\n`);
+    return process.exit(1);
+  }
+}
+
+function printCatalog(catalog) {
+  console.log(`\n  ${bold('Playbooks')} ${dim('- run one end-to-end, exit non-zero when a gate holds')}\n`);
+  for (const playbook of catalog) {
+    console.log(`  ${cyan(playbook.id)} ${dim(`v${playbook.version} · ${playbook.steps.length} steps`)}`);
+    console.log(`    ${playbook.name}`);
+    const required = Object.entries(playbook.inputs || {}).filter(([, spec]) => spec.required).map(([key]) => key);
+    if (required.length) console.log(`    ${dim('needs')} ${required.map((key) => bold(key)).join(', ')}`);
+    console.log('');
+  }
+  console.log(dim(`  Run one:  ${bold('shomra run <id> --input key=value')}\n`));
+}
+
+async function listPlaybooks({ url, apiKey, flags, hasId }) {
+  const catalog = await requestOrExit(
+    () => api(url, apiKey, '/playbooks/agent/catalog', null, { method: 'GET' }),
+    { json: true },
+  );
+  if (flags.json) {
+    console.log(JSON.stringify(catalog, null, 2));
+    return;
+  }
+  printCatalog(catalog);
+  if (!hasId) process.exitCode = EXIT_USAGE;
+}
+
+function stepNote(step) {
+  if (step.status === 'SKIPPED') return dim('skipped - its condition was false');
+  if (!step.error) return '';
+  return step.uses === 'gate' ? yellow(step.error) : red(step.error);
+}
+
+function printOutcome(run) {
+  const failedStep = (run.steps || []).find((step) => step.status === 'FAILED');
+  const gateHeld = run.status === 'FAILED' && failedStep?.uses === 'gate';
+  console.log('');
+
+  if (gateHeld) {
+    console.log(`  ${yellow('⚠')} ${bold('The gate held.')} ${dim('That is the assertion firing - exiting non-zero.')}\n`);
+    return;
+  }
+  if (run.status === 'FAILED') {
+    console.log(`  ${red('✗')} ${bold('A step failed.')} ${dim(run.error || '')}\n`);
+    return;
+  }
+  console.log(`  ${green('✓')} ${bold('Completed.')} ${dim('Every step that was meant to run did.')}\n`);
+}
+
+function printRun(run) {
+  console.log(`\n  ${bold(run.playbookName)} ${dim(`· ${run.playbookId}`)}\n`);
+  for (const step of run.steps || []) {
+    const mark = (STEP_MARK[step.status] || STEP_MARK.PENDING)();
+    const note = stepNote(step);
+    console.log(`  ${mark} ${step.name}${note ? ` ${dim('·')} ${note}` : ''}`);
+  }
+  printOutcome(run);
+}
+
+export async function cmdRun(flags, positional) {
+  const id = positional[0];
+  const inputs = parseInputs(flags);
+
+  const { apiKey, url } = resolveSettings(loadConfig());
+  if (!apiKey) exitNotConfigured();
+
+  if (!id || flags.list) {
+    await listPlaybooks({ url, apiKey, flags, hasId: !!id });
+    return;
+  }
+
+  if (!flags.json) process.stdout.write(dim(`\n  Running ${bold(id)}… `));
+  const run = await requestOrExit(() => api(url, apiKey, `/playbooks/agent/${encodeURIComponent(id)}/run`, {
+    inputs,
+    ...(flags.project ? { projectId: String(flags.project) } : {}),
+    actor: `${os.hostname()}/${os.userInfo().username}`,
+  }), flags);
+  if (!flags.json) console.log(green('done'));
+
+  if (flags.json) console.log(JSON.stringify(run, null, 2));
+  else printRun(run);
+
+  if (run.status === 'FAILED') process.exitCode = 1;
+}

package/src/commands/scan-zip.mjs

@@ -0,0 +1,118 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+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';
+
+const MAX_POLICY_HITS_SHOWN = 3;
+
+function resolveArchive(positional) {
+  const file = positional[0];
+  if (!file) {
+    console.error(`${red('✗')} Usage: ${bold('shomra scan-zip <workspace.zip> [--project <id>] [--json]')}`);
+    process.exit(EXIT_USAGE);
+  }
+  const target = path.resolve(String(file));
+  if (!fs.existsSync(target) || !fs.statSync(target).isFile()) {
+    console.error(`${red('✗')} File not found: ${file}`);
+    process.exit(EXIT_USAGE);
+  }
+  if (!/\.zip$/i.test(target)) {
+    console.error(`${red('✗')} ${file} is not a .zip archive.`);
+    process.exit(EXIT_USAGE);
+  }
+  return target;
+}
+
+function buildUploadForm(target, flags) {
+  const form = new FormData();
+  form.append('file', new Blob([fs.readFileSync(target)], { type: 'application/zip' }), path.basename(target));
+  form.append('actor', `${os.hostname()}/${os.userInfo().username}`);
+  if (flags.project) form.append('projectId', String(flags.project));
+  return form;
+}
+
+async function readResponse(response) {
+  const text = await response.text();
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    body = { raw: text };
+  }
+  if (response.ok) return body;
+
+  const message = body?.message || body?.raw || response.statusText;
+  throw new Error(`${response.status} ${Array.isArray(message) ? message.join(', ') : message}`);
+}
+
+async function uploadArchive({ url, apiKey, target, flags }) {
+  if (!flags.json) process.stdout.write(dim('\n  Uploading to Workspace Scan… '));
+  try {
+    const response = await fetch(`${url}/bundle/agent-scan`, {
+      method: 'POST',
+      headers: { 'X-Shomra-Key': apiKey, Connection: 'close' },
+      body: buildUploadForm(target, flags),
+    });
+    const report = await readResponse(response);
+    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 printPolicyDecision(report) {
+  if (!report.policyDecision || report.policyDecision === 'ALLOW') return;
+  const colour = report.policyDecision === 'BLOCK' ? red : yellow;
+  const policies = (report.policyHits || []).map((hit) => hit.policy).slice(0, MAX_POLICY_HITS_SHOWN).join(', ');
+  console.log(`  ${colour('▎')} ${colour(`org policy: ${report.policyDecision}`)}${policies ? dim(` - ${policies}`) : ''}`);
+}
+
+function printArtifactGroups(report) {
+  for (const group of report.groups || []) {
+    if (!group.count) continue;
+    console.log(`\n  ${bold(group.kind.replace(/_/g, ' ').toLowerCase())} ${dim(`(${group.count})`)}`);
+
+    for (const artifact of group.artifacts || []) {
+      const colour = VERDICT_COLOR[artifact.verdict] || gray;
+      console.log(`    ${colour('●')} ${bold(artifact.name)} ${dim(artifact.path)} ${colour(artifact.verdict)} ${dim(`risk ${artifact.riskScore}`)}`);
+      for (const finding of (artifact.findings || []).filter((f) => f.severity !== 'INFO')) {
+        console.log(`        ${SEV_COLOR[finding.severity](String(finding.severity).padEnd(8))} ${finding.title}`);
+      }
+    }
+  }
+}
+
+function summaryLine(verdict) {
+  if (verdict === 'FAIL') return red('✗ Do not install this workspace unreviewed.');
+  if (verdict === 'REVIEW') return yellow('⚠ Review the findings above before trusting this workspace.');
+  return green('✓ Clean.');
+}
+
+function printReport(report) {
+  const colour = VERDICT_COLOR[report.verdict] || gray;
+  console.log(`\n  ${bold(report.filename)} ${dim(`· ${report.fileCount} files · ${report.artifactCount} AI artifact(s)`)}`);
+  console.log(`  ${colour('●')} ${colour(bold(report.verdict))} ${dim(`risk ${report.riskScore}/100 · ${report.findingCount} finding(s) · ${report.criticalCount} critical · ${report.highCount} high`)}`);
+
+  printPolicyDecision(report);
+  printArtifactGroups(report);
+  console.log(`\n  ${summaryLine(report.verdict)}${dim(' Full report in the Shomra dashboard → Workspace Scan.\n')}`);
+}
+
+export async function cmdScanZip(flags, positional) {
+  const { apiKey, url } = resolveSettings(loadConfig());
+  if (!apiKey) exitNotConfigured();
+
+  const target = resolveArchive(positional);
+  const report = await uploadArchive({ url, apiKey, target, flags });
+
+  if (flags.json) console.log(JSON.stringify(report, null, 2));
+  else printReport(report);
+
+  if (report.policyDecision === 'BLOCK' || report.verdict === 'FAIL') process.exitCode = 1;
+  else if ((report.policyDecision === 'FLAG' || report.verdict === 'REVIEW') && flags.strict) process.exitCode = 2;
+}

package/src/commands/scan.mjs

@@ -0,0 +1,102 @@
+import path from 'node:path';
+import { printArtifacts, printAssets } from '../artifacts/report.mjs';
+import { api, machineInfo } from '../core/api-client.mjs';
+import { loadConfig, resolveSettings } from '../core/config.mjs';
+import { exitNotConfigured } from '../core/exit-codes.mjs';
+import { clampInt } from '../core/numbers.mjs';
+import { SEV_COLOR, VERDICT_COLOR, bold, cyan, dim, gray, green, red, yellow } from '../core/terminal.mjs';
+import { VERSION } from '../core/version.mjs';
+import { discoverAgentArtifacts } from '../inventory/agent-artifacts.mjs';
+import { discoverAll } from '../inventory/discovery.mjs';
+
+function discover(flags) {
+
+  const roots = flags.path ? [path.resolve(String(flags.path))] : [process.cwd()];
+  return discoverAll(roots, { autoExpand: !flags.path });
+}
+
+function discoverArtifacts(flags) {
+  const cwd = flags.path ? path.resolve(String(flags.path)) : process.cwd();
+  return discoverAgentArtifacts(cwd);
+}
+
+export async function cmdScan(flags) {
+  const cfg = loadConfig();
+  const assets = discover(flags);
+  const { artifacts, capped, available } = discoverArtifacts(flags);
+  if (flags.json && !flags.report) {
+    console.log(JSON.stringify({ machine: machineInfo(cfg), assets, artifacts, capped, available }, null, 2));
+    return;
+  }
+  console.log(bold(cyan('\n  Shomra')) + dim(` agent v${VERSION} - local scan`));
+  printAssets(assets);
+  printArtifacts(artifacts, capped, available);
+
+  if (flags.report) {
+    await sendReport(cfg, assets, flags, { artifacts, capped, available });
+  } else {
+    console.log(
+      dim('\n  Run ') + bold('shomra report') + dim(' to analyze these on the platform and see findings.\n'),
+    );
+  }
+}
+
+async function sendReport(cfg, assets, flags, extra = {}) {
+  const { apiKey, url } = resolveSettings(cfg);
+  if (!apiKey) {
+    exitNotConfigured();
+  }
+  const artifacts = extra.artifacts ?? [];
+  const capped = extra.capped ?? [];
+  const available = extra.available ?? [];
+  process.stdout.write(dim('\n  Reporting to platform… '));
+  try {
+    const res = await api(url, apiKey, '/agent/report', {
+      machine: machineInfo(cfg),
+      assets,
+      artifacts,
+
+      capped,
+
+      available,
+    }, {
+
+      timeoutMs: clampInt(process.env.SHOMRA_API_TIMEOUT_MS, 180000, 1000, 600000),
+    });
+    console.log(
+      green('done') +
+        dim(` (${res.assets} assets analyzed`) +
+        (res.artifacts ? dim(`, ${res.artifacts.registered} artifacts registered`) : '') +
+        dim(')'),
+    );
+    if (flags.json) {
+      console.log(JSON.stringify(res, null, 2));
+      return;
+    }
+    console.log('');
+    if (Array.isArray(res.results)) {
+      for (const r of res.results.filter((x) => x.findingCount > 0)) {
+        const vc = VERDICT_COLOR[r.verdict] || gray;
+        console.log(`  ${vc('●')} ${bold(r.name)} ${dim('risk ' + r.riskScore)} ${vc(r.verdict)}`);
+        for (const f of r.findings || []) {
+          console.log(`      ${SEV_COLOR[f.severity](f.severity.padEnd(8))} ${f.title}`);
+        }
+      }
+    }
+    const crit = res.critical ?? 0;
+    const high = res.high ?? 0;
+    console.log(
+      '\n  ' +
+        (crit + high > 0
+          ? `${red(crit + ' critical')} · ${yellow(high + ' high')} ${dim('- view & remediate at the Shomra dashboard')}`
+          : green('No high-severity findings. ') + dim('Nice and clean.')),
+    );
+    console.log(dim(`  Endpoint: ${res.endpointId}\n`));
+    if (crit > 0) process.exitCode = 1;
+  } catch (e) {
+    console.log(red('failed'));
+    console.error(`  ${red('✗')} ${e.message}\n`);
+
+    process.exitCode = 1;
+  }
+}

package/src/commands/secrets.mjs

@@ -0,0 +1,99 @@
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { MAX_ARTIFACT_BYTES, SKIP_DIRS } from '../artifacts/matchers.mjs';
+import { clampInt } from '../core/numbers.mjs';
+import { bold, cyan, dim, green, red, yellow } from '../core/terminal.mjs';
+import { SECRET_PATTERNS, localScan } from '../detect/guard-signals.mjs';
+
+function redactSecret(s) {
+  const t = String(s).trim();
+  return t.length <= 8 ? t[0] + '••••' : `${t.slice(0, 4)}…${t.slice(-2)}`;
+}
+
+function isGitRepo(root) {
+  try { execSync('git rev-parse --is-inside-work-tree', { cwd: root, stdio: ['ignore', 'pipe', 'ignore'] }); return true; }
+  catch { return false; }
+}
+
+export function walkFiles(root, cap = 8000) {
+  const found = [];
+  const stack = [root];
+  while (stack.length && found.length < cap) {
+    const dir = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const ent of entries) {
+      if (ent.isDirectory()) { if (!SKIP_DIRS.has(ent.name) && ent.name !== '.git') stack.push(path.join(dir, ent.name)); continue; }
+      found.push(path.relative(root, path.join(dir, ent.name)).split(path.sep).join('/'));
+      if (found.length >= cap) break;
+    }
+  }
+  return found;
+}
+
+function scanGitHistory(root, depth) {
+  let out;
+  try { out = execSync(`git log --all -p -n ${depth} --no-color --format="commit %H %an %ad"`, { cwd: root, stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 128 * 1024 * 1024 }).toString(); }
+  catch { return null; }
+  const hits = [];
+  const seen = new Set();
+  let commit = '', file = '';
+  for (const line of out.split(/\r?\n/)) {
+    if (line.startsWith('commit ')) { commit = line.slice(7, 19); continue; }
+    if (line.startsWith('+++ b/')) { file = line.slice(6); continue; }
+    if (line[0] !== '+' || line.startsWith('+++')) continue;
+    const added = line.slice(1);
+    for (const { name, re } of SECRET_PATTERNS) {
+      const m = added.match(re);
+      if (!m) continue;
+      const key = `${commit}:${file}:${name}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      hits.push({ where: 'history', commit, file, secret: name, sample: redactSecret(m[0]) });
+    }
+  }
+  return hits;
+}
+
+export function cmdSecrets(flags, positional) {
+  const root = path.resolve(positional[0] || '.');
+  const hits = [];
+  const isGit = isGitRepo(root);
+  for (const rel of walkFiles(root)) {
+    let content;
+    try {
+      const full = path.join(root, rel);
+      if (fs.statSync(full).size > MAX_ARTIFACT_BYTES) continue;
+      content = fs.readFileSync(full, 'utf8');
+    } catch { continue; }
+    if (content.includes('\0')) continue;
+    for (const f of localScan(content, { categories: ['secret'] }).findings) {
+      hits.push({ where: 'working-tree', file: rel, line: f.line, secret: f.label.replace(/^Live credential:\s*/, '') });
+    }
+  }
+  let history = null;
+  if (flags.history) {
+    history = scanGitHistory(root, clampInt(flags.depth, 300, 1, 5000));
+    if (history) hits.push(...history);
+  }
+
+  if (flags.json) { console.log(JSON.stringify({ workingTree: hits.filter((h) => h.where === 'working-tree').length, history: history ? history.length : null, hits }, null, 2)); return; }
+
+  console.log(bold(cyan('\n  Shomra secrets')) + dim(` - ${path.relative(process.cwd(), root).split(path.sep).join('/') || '.'}${flags.history ? ' · working tree + git history' : ' · working tree'}`));
+  if (!isGit) console.log(dim('  (not a git repo - working tree only; --history unavailable)'));
+  else if (!flags.history) console.log(dim('  Tip: add ') + bold('--history') + dim(' to also scan past commits (a leaked key removed from HEAD is still live).'));
+  const wt = hits.filter((h) => h.where === 'working-tree');
+  const hi = hits.filter((h) => h.where === 'history');
+  if (!hits.length) { console.log(green('\n  ✓ No secret-shaped values found.\n')); return; }
+  if (wt.length) {
+    console.log(red(`\n  ${wt.length} in the working tree:`));
+    for (const h of wt.slice(0, 25)) console.log(`    ${red('●')} ${bold(h.file)}${h.line ? dim(':' + h.line) : ''} ${dim(h.secret)}`);
+  }
+  if (hi.length) {
+    console.log(yellow(`\n  ${hi.length} in git history ${dim('(rotate - still reachable):')}`));
+    for (const h of hi.slice(0, 25)) console.log(`    ${yellow('●')} ${dim(h.commit)} ${bold(h.file)} ${dim(h.secret + ' ' + (h.sample || ''))}`);
+  }
+  console.log(dim(`\n  Rotate every matched credential now. A committed secret is compromised even after you delete it - history keeps it.\n`));
+  process.exitCode = 1;
+}