@m2-ai/lattice-cli 0.0.0-stage → 0.8.7

package/dist/security-runtime/src/cli/doctor.mjs

@@ -0,0 +1,82 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { platformFor, resolveTool, resolveVerifiedArchive, verifyTool } from '../core/installer.mjs';
+import { platformKey, toolsDir } from '../core/paths.mjs';
+import { loadRegistry } from '../core/registry.mjs';
+import { runProcess } from '../core/runner.mjs';
+
+const GIT_NEEDED_FOR = 'secrets history, posture, and the dependency-change base diff';
+const firstLine = (r) => `${r.stdout}\n${r.stderr}`.trim().split('\n')[0].trim();
+const probe = async (command, args) => {
+  const r = await runProcess({ command, args, timeoutMs: 15_000 });
+  return r.status === 'ran' ? r : null;
+};
+
+function findDefender() {
+  if (process.platform !== 'win32') return null;
+  const candidates = [path.join(process.env.ProgramFiles ?? 'C:\\Program Files', 'Windows Defender', 'MpCmdRun.exe')];
+  const platformDir = path.join(process.env.ProgramData ?? 'C:\\ProgramData', 'Microsoft', 'Windows Defender', 'Platform');
+  try { for (const v of fs.readdirSync(platformDir).sort().reverse()) candidates.unshift(path.join(platformDir, v, 'MpCmdRun.exe')); } catch { /* no platform folder */ }
+  return candidates.find((c) => fs.existsSync(c)) ?? null;
+}
+
+export default {
+  name: 'doctor',
+  summary: 'Report which tools, Docker and antivirus engines are available',
+  usage: '',
+  maxPositionals: 0,
+  purpose: 'Lists each registry tool with its installed version, and reports Node, git, Docker, Microsoft Defender and ClamAV status. Read-only; it changes nothing.',
+  options: [],
+  examples: ['vsg doctor', 'vsg doctor --json'],
+  async run({ flags }, io) {
+    const registry = loadRegistry(io.registryDir);
+    const tools = [];
+    for (const tool of registry.values()) {
+      if (tool.image) { tools.push({ name: tool.name, version: tool.version, status: 'image', detail: `${tool.image} (pulled by digest when used)` }); continue; }
+      if (process.platform === 'win32' && tool.name === 'semgrep-rules') {
+        const archive = resolveVerifiedArchive(tool);
+        tools.push({ name: tool.name, version: tool.version, status: archive ? 'installed' : 'not installed', detail: archive ? `${archive.path} (verified archive; Linux runner)` : 'run vsg setup --repair' });
+        continue;
+      }
+      const resolved = resolveTool(tool);
+      if (!resolved) { tools.push({ name: tool.name, version: tool.version, status: tool.platforms[platformFor(tool)] ? 'not installed' : `no build for ${platformKey()}`, detail: 'run vsg setup' }); continue; }
+      const check = await verifyTool(tool, resolved);
+      const linuxRunner = check.ok && process.platform === 'win32' && tool.name === 'opengrep' ? resolveTool(tool, 'linux-x64') : null;
+      if (check.ok && process.platform === 'win32' && tool.name === 'opengrep' && !linuxRunner) {
+        tools.push({ name: tool.name, version: tool.version, status: 'broken', detail: 'Linux runner binary missing; run vsg setup --repair' });
+      } else {
+        tools.push({ name: tool.name, version: tool.version, status: check.ok ? 'installed' : 'broken', detail: check.ok ? `${resolved.path}${linuxRunner ? `; Linux runner: ${linuxRunner.path}` : ''}` : `version check failed: ${check.output}; run vsg setup --repair` });
+      }
+    }
+    const git = await probe('git', ['--version']);
+    const dockerClient = await probe('docker', ['version', '--format', '{{.Client.Version}}']);
+    const dockerServer = dockerClient?.exitCode === 0 ? await probe('docker', ['version', '--format', '{{.Server.Version}}']) : null;
+    const clam = await probe('clamscan', ['--version']);
+    const defender = findDefender();
+    const env = {
+      platform: platformKey(), node: process.version, toolsDir: toolsDir(), os: `${os.type()} ${os.release()}`,
+      git: git?.exitCode === 0 ? firstLine(git) : 'not found',
+      gitNeededFor: GIT_NEEDED_FOR,
+      docker: !dockerClient || dockerClient.exitCode !== 0 ? 'not found' : dockerServer?.exitCode === 0 ? `client ${firstLine(dockerClient)}, engine ${firstLine(dockerServer)}` : `client ${firstLine(dockerClient)}, engine not running`,
+      defender: process.platform === 'win32' ? (defender ?? 'MpCmdRun.exe not found') : 'not applicable on this platform',
+      clamav: clam?.exitCode === 0 ? firstLine(clam) : 'not found',
+    };
+    const missing = tools.filter((t) => t.status !== 'installed' && t.status !== 'image');
+    const headline = !tools.length ? 'READY: the registry has no tools yet'
+      : missing.length ? `NOT READY: ${missing.length} of ${tools.length} tools missing. Run vsg setup.`
+        : `READY: all ${tools.length} tools installed`;
+    if (flags.json) io.stdout(JSON.stringify({ headline, ...env, tools }));
+    else {
+      io.stdout(headline);
+      io.stdout(`Platform: ${env.platform} (${env.os}), Node ${env.node}`);
+      io.stdout(`Tools cache: ${env.toolsDir}`);
+      for (const t of tools) io.stdout(`  ${t.name} ${t.version}: ${t.status}${t.detail ? ` (${t.detail})` : ''}`);
+      io.stdout(env.git === 'not found' ? `git: NOT FOUND. These checks cannot run without it: ${GIT_NEEDED_FOR}. Install git.` : `git: ${env.git} (needed for ${GIT_NEEDED_FOR})`);
+      io.stdout(`Docker: ${env.docker}`);
+      io.stdout(`Microsoft Defender: ${env.defender}`);
+      io.stdout(`ClamAV: ${env.clamav}`);
+    }
+    return 0;
+  },
+};

package/dist/security-runtime/src/cli/index.mjs

@@ -0,0 +1,60 @@
+// Command dispatch. main() returns the exit code (0 PASS, 1 BLOCKED, 2 INCOMPLETE, 3 usage, configuration, authorization or lock error).
+import { UsageError } from '../core/errors.mjs';
+import { assertStandaloneExecution } from '../lattice/execution.mjs';
+import { vsgVersion } from '../core/pipeline.mjs';
+import { commandHelp, EXIT_TEXT, parseArgs } from './parse.mjs';
+import deep from './deep.mjs';
+import doctor from './doctor.mjs';
+import portfolio from './portfolio.mjs';
+import report from './report.mjs';
+import release from './release.mjs';
+import scan from './scan.mjs';
+import setup from './setup.mjs';
+import url from './url.mjs';
+
+const byName = new Map([setup, doctor, scan, deep, report, url, release, portfolio].map((c) => [c.name, c]));
+const QUALIFICATION_COMMANDS = new Set(['scan', 'deep', 'report', 'release']);
+export const isQualificationCommand = (name) => QUALIFICATION_COMMANDS.has(name);
+export const COMMANDS = [...byName.values()].map((c) => [c.name, c.summary]);
+export const EXIT = { PASS: 0, BLOCKED: 1, INCOMPLETE: 2, USAGE: 3 };
+
+export function helpText() {
+  const width = Math.max(...COMMANDS.map(([name]) => name.length));
+  return [
+    'Usage: vsg <command> [options]',
+    '',
+    'Commands:',
+    ...COMMANDS.map(([name, summary]) => `  ${name.padEnd(width)}  ${summary}`),
+    '',
+    'Run vsg <command> --help for a command\'s options and examples.',
+    'Common options: --out <dir> (output directory), --json (one JSON summary on stdout), --help; vsg --version prints the version.',
+    EXIT_TEXT,
+  ].join('\n');
+}
+
+const defaultIo = () => ({
+  stdout: (l) => process.stdout.write(`${l}\n`),
+  stderr: (l) => process.stderr.write(`${l}\n`),
+  cwd: process.cwd(),
+  env: process.env,
+});
+
+export async function main(argv, ioOverrides = {}) {
+  const io = { ...defaultIo(), ...ioOverrides };
+  const [name, ...rest] = argv;
+  if (name === '--version' || name === '-v') { io.stdout(`vsg ${vsgVersion()}`); return EXIT.PASS; }
+  if (!name || name === '--help' || name === '-h' || name === 'help') { io.stdout(helpText()); return EXIT.PASS; }
+  const cmd = byName.get(name);
+  if (!cmd) { io.stderr(`Unknown command "${name}". Run vsg --help.`); return EXIT.USAGE; }
+  try {
+    const args = parseArgs(name, rest, cmd.options);
+    if (args.flags.help) { io.stdout(commandHelp(cmd)); return EXIT.PASS; }
+    if (args.positionals.length > cmd.maxPositionals) throw new UsageError(`Too many arguments for vsg ${name}. Run vsg ${name} --help.`);
+    assertStandaloneExecution({ allowQualification: isQualificationCommand(name) });
+    return await cmd.run(args, io);
+  } catch (e) {
+    if (e instanceof UsageError) { io.stderr(e.message); return EXIT.USAGE; }
+    io.stderr(`vsg ${name} failed: ${e.message}`);
+    return EXIT.INCOMPLETE; // an unexpected internal error is never a PASS
+  }
+}

package/dist/security-runtime/src/cli/live-common.mjs

@@ -0,0 +1,27 @@
+// Shared by vsg url and vsg release: authorize the target before any request, then build the rate-limited live session.
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadConfig } from '../core/accept.mjs';
+import { UsageError } from '../core/errors.mjs';
+import { vsgHome } from '../core/paths.mjs';
+import { createSession } from '../live/session.mjs';
+import { authorize, resolveRate } from '../live/targets.mjs';
+
+export const LIVE_OPTIONS = [
+  { flag: '--rate', type: 'string', arg: 'n', help: 'Requests per second (default 2; more only for a loopback origin registered as local in ~/.vsg/targets.json)' },
+];
+
+/** Returns { session, info: { target, authorization }, flags } for run flags. Throws UsageError (exit 3) for an unregistered origin; sends nothing. */
+export function prepareLive(urlText, { io, repo, rateFlag }) {
+  const home = io.env?.VSG_HOME || vsgHome();
+  const repoConfig = repo && fs.existsSync(path.join(repo, 'vsg.config.json')) ? loadConfig(repo) : null;
+  const auth = authorize(urlText, { home, repoConfig, repoPath: repo });
+  const rps = resolveRate(rateFlag, auth);
+  for (const n of auth.notes) io.stderr(`Note: ${n}`);
+  const session = createSession({ origin: auth.origin, url: auth.url, displayUrl: auth.displayUrl, environment: auth.environment, rps, fetchImpl: io.fetchImpl });
+  return { session, auth, info: { target: auth.displayUrl, authorization: auth.description }, flags: { live: session } };
+}
+
+export function requireDirectory(dir, label = 'repository') {
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) throw new UsageError(`"${dir}" is not a directory. Pass the ${label} path.`);
+}

package/dist/security-runtime/src/cli/parse.mjs

@@ -0,0 +1,56 @@
+// Minimal argument parser driven by each command's option table. Unknown flags are a usage error (exit 3).
+import { UsageError } from '../core/errors.mjs';
+
+export const COMMON_OPTIONS = [
+  { flag: '--json', type: 'bool', help: 'Print one JSON summary to stdout instead of text' },
+  { flag: '--help', alias: '-h', type: 'bool', help: 'Show this help' },
+];
+
+export function parseArgs(command, argv, options) {
+  const all = [...options, ...COMMON_OPTIONS];
+  const flags = {};
+  const positionals = [];
+  const find = (token) => all.find((o) => o.flag === token || o.alias === token);
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (token === '--') { positionals.push(...argv.slice(i + 1)); break; }
+    if (!token.startsWith('-') || token === '-') { positionals.push(token); continue; }
+    const eq = token.indexOf('=');
+    const name = token.startsWith('--') && eq > 0 ? token.slice(0, eq) : token;
+    const opt = find(name);
+    if (!opt) throw new UsageError(`Unknown option "${name}" for vsg ${command}. Run vsg ${command} --help.`);
+    const key = opt.flag.slice(2);
+    if (opt.type === 'bool') {
+      if (eq > 0) throw new UsageError(`Option ${opt.flag} does not take a value. Run vsg ${command} --help.`);
+      flags[key] = true;
+    } else {
+      const value = eq > 0 ? token.slice(eq + 1) : argv[++i];
+      if (value === undefined || value.startsWith('--')) throw new UsageError(`Option ${opt.flag} needs a value. Run vsg ${command} --help.`);
+      flags[key] = value;
+    }
+  }
+  return { flags, positionals };
+}
+
+export const EXIT_TEXT = 'Exit codes: 0 PASS, 1 BLOCKED, 2 INCOMPLETE, 3 usage, configuration, authorization or lock error';
+
+export function commandHelp(cmd) {
+  const opts = [...cmd.options, ...COMMON_OPTIONS];
+  const label = (o) => `${o.alias ? `${o.alias}, ` : ''}${o.flag}${o.type === 'string' ? ` <${o.arg ?? 'value'}>` : ''}`;
+  const width = Math.max(...opts.map((o) => label(o).length));
+  return [
+    `vsg ${cmd.name}: ${cmd.summary}`,
+    '',
+    `Usage: vsg ${cmd.name}${cmd.usage ? ` ${cmd.usage}` : ''} [options]`,
+    '',
+    cmd.purpose,
+    '',
+    'Options:',
+    ...opts.map((o) => `  ${label(o).padEnd(width)}  ${o.help}`),
+    '',
+    'Examples:',
+    ...cmd.examples.map((e) => `  ${e}`),
+    '',
+    EXIT_TEXT,
+  ].join('\n');
+}

package/dist/security-runtime/src/cli/portfolio.mjs

@@ -0,0 +1,34 @@
+import path from 'node:path';
+import { discoverChecks } from '../core/checks.mjs';
+import { defaultChecksDir, vsgHome } from '../core/paths.mjs';
+import { loadRegistry } from '../core/registry.mjs';
+import { loadPortfolio, runPortfolio } from '../portfolio/index.mjs';
+import { prepareLive } from './live-common.mjs';
+
+export default {
+  name: 'portfolio',
+  summary: 'Run across every product in ~/.vsg/portfolio.json',
+  usage: '',
+  maxPositionals: 0,
+  purpose: 'Runs each registered product through scan or deep, one after another, and writes the outputs plus summary.md and summary.json to ~/.vsg/portfolio/<date>/ (never inside a product). A product with a registered "url" also gets the passive live checks. A product that fails is recorded and the run continues. The exit code is the worst verdict. Dated folders older than 90 days are removed. Schedule it with Windows Task Scheduler (see README); vsg never creates scheduled tasks.',
+  options: [{ flag: '--config', type: 'string', arg: 'file', help: 'Portfolio file (default: ~/.vsg/portfolio.json)' }],
+  examples: ['vsg portfolio', 'vsg portfolio --config ./portfolio.json --json'],
+  async run({ flags }, io) {
+    const home = io.env?.VSG_HOME || vsgHome();
+    const products = loadPortfolio(flags.config ? path.resolve(io.cwd, flags.config) : path.join(home, 'portfolio.json'));
+    const dirs = [defaultChecksDir, ...(io.env.VSG_EXTRA_CHECKS_DIR ? [io.env.VSG_EXTRA_CHECKS_DIR] : [])];
+    const checks = io.checks ?? await discoverChecks(dirs);
+    const registry = loadRegistry(io.registryDir);
+    const { summary, dir, pruned, exitCode } = await runPortfolio(products, {
+      home, checks, registry, now: io.now, progress: (l) => io.stderr(l),
+      prepareLive: (url, repo) => prepareLive(url, { io, repo }),
+    });
+    if (flags.json) io.stdout(JSON.stringify({ ...summary, outputs: { dir, summary: path.join(dir, 'summary.md') }, pruned }));
+    else {
+      io.stdout(`Portfolio ${summary.verdict}: ${summary.products.length} product(s)`);
+      for (const p of summary.products) io.stdout(`  ${p.name}: ${p.verdict}, ${p.mustFix} must fix, ${p.error ? `run failed: ${p.error}` : `${p.notRun.length} check(s) did not run`}`);
+      io.stdout(`Summary: ${path.join(dir, 'summary.md')}`);
+    }
+    return exitCode;
+  },
+};

package/dist/security-runtime/src/cli/release.mjs

@@ -0,0 +1,28 @@
+import path from 'node:path';
+import { LIVE_OPTIONS, prepareLive, requireDirectory } from './live-common.mjs';
+import { RUN_OPTIONS, runMode } from './run-common.mjs';
+
+export default {
+  name: 'release',
+  summary: 'Deep audit plus passive live checks against a registered preview URL, with the SBOM',
+  usage: '[path]',
+  maxPositionals: 1,
+  purpose: 'Runs the deep audit in release mode (project scripts and SBOM included), then the passive live checks against the registered preview URL, and writes one combined set of outputs and one verdict. The URL must be registered (see vsg url --help). Without --url the live checks are reported as did-not-run, so the verdict is INCOMPLETE rather than PASS. vsg never starts the app.',
+  options: [
+    ...RUN_OPTIONS,
+    { flag: '--url', type: 'string', arg: 'url', help: 'Registered preview URL to check (required for a PASS)' },
+    { flag: '--no-validate', type: 'bool', help: 'Do not validate found credentials against their issuers' },
+    ...LIVE_OPTIONS,
+  ],
+  examples: ['vsg release --url https://preview.example.com', 'vsg release ../my-app --url http://127.0.0.1:3000 --json'],
+  async run(args, io) {
+    const repo = path.resolve(io.cwd, args.positionals[0] ?? '.');
+    requireDirectory(repo);
+    if (!args.flags.url) {
+      io.stderr('No --url was given, so the live checks will not run and the verdict cannot be PASS.');
+      return runMode('release', args, io);
+    }
+    const live = prepareLive(args.flags.url, { io, repo, rateFlag: args.flags.rate });
+    return runMode('release', args, io, { repo, flags: live.flags, info: live.info });
+  },
+};

package/dist/security-runtime/src/cli/report.mjs

@@ -0,0 +1,18 @@
+import path from 'node:path';
+import { reportWithAgentFindings } from '../agent/report.mjs';
+import { printResult } from './run-common.mjs';
+
+export default {
+  name: 'report',
+  summary: 'Merge agent findings and recompute the verdict',
+  usage: '[path]',
+  maxPositionals: 1,
+  purpose: 'Reads the previous deep run in the output directory plus <out>/agent/findings.json. It validates the file, rejects findings that cite missing files, runs each reproduction command (at most 20, 120 seconds each, no shell), and rewrites the report and verdict. It does not rescan.',
+  options: [{ flag: '--out', type: 'string', arg: 'dir', help: 'Output directory of the deep run (default: <path>/.vsg)' }],
+  examples: ['vsg report', 'vsg report ../my-app --out ../scan-output', 'vsg report --json'],
+  async run({ flags, positionals }, io) {
+    const repo = path.resolve(io.cwd, positionals[0] ?? '.');
+    const result = await reportWithAgentFindings({ repo, out: flags.out ? path.resolve(io.cwd, flags.out) : undefined, now: io.now, progress: (l) => io.stderr(l) });
+    return printResult('deep', result, flags, io);
+  },
+};

package/dist/security-runtime/src/cli/run-common.mjs

@@ -0,0 +1,54 @@
+// Shared run path for scan and deep (and later url and release): load checks and registry, run the pipeline, print the result.
+import path from 'node:path';
+import { discoverChecks } from '../core/checks.mjs';
+import { EXIT_CODES, headline } from '../core/gate.mjs';
+import { scrubText, scrubUrl } from '../core/findings.mjs';
+import { defaultChecksDir } from '../core/paths.mjs';
+import { runPipeline } from '../core/pipeline.mjs';
+import { loadRegistry } from '../core/registry.mjs';
+
+export const RUN_OPTIONS = [
+  { flag: '--out', type: 'string', arg: 'dir', help: 'Output directory (default: <path>/.vsg)' },
+  { flag: '--base', type: 'string', arg: 'ref', help: 'Git base ref for acceptance and policy change review (default: vsg.config.json baseRef, then the merge-base with the remote default branch)' },
+  { flag: '--compare', type: 'string', arg: 'findings.json', help: 'Earlier findings.json; findings absent from it are marked new' },
+];
+
+/**
+ * extra (used by url and release): { repo, out (default), flags (merged into pipeline flags), info: { target, authorization } }.
+ */
+export async function runMode(mode, { flags, positionals }, io, extra = {}) {
+  const repo = extra.repo ?? path.resolve(io.cwd, positionals[0] ?? '.');
+  const dirs = [defaultChecksDir, ...(io.env.VSG_EXTRA_CHECKS_DIR ? [io.env.VSG_EXTRA_CHECKS_DIR] : [])];
+  const checks = io.checks ?? await discoverChecks(dirs);
+  const registry = loadRegistry(io.registryDir);
+  const result = await runPipeline({
+    mode, repo, out: flags.out ? path.resolve(io.cwd, flags.out) : extra.out, checks, registry,
+    flags: { base: flags.base, noValidate: !!flags['no-validate'], compare: flags.compare ? path.resolve(io.cwd, flags.compare) : undefined,
+      ...(extra.flags ?? {}), ...(extra.info ? { target: extra.info.target, authorization: extra.info.authorization } : {}) },
+    now: io.now, progress: (line) => io.stderr(line),
+  });
+  return printResult(mode, result, flags, io, extra);
+}
+
+/** Prints a run's result (text or --json) and returns the exit code. Shared by scan, deep and report. */
+export function printResult(mode, result, flags, io, extra = {}) {
+  const line = headline(result.verdict, result.counts, result.coverage);
+  const exitCode = EXIT_CODES[result.verdict];
+  if (flags.json) {
+    io.stdout(JSON.stringify({
+      verdict: result.verdict, headline: line, mode, exitCode, counts: result.counts,
+      notRun: result.coverage.filter((c) => c.status === 'not_run').map((c) => ({ id: c.id, required: c.required, reason: c.reason })),
+      outputs: result.outputs,
+      ...(extra.info ? { target: scrubUrl(extra.info.target), authorizedBy: scrubText(extra.info.authorization) } : {}),
+    }));
+  } else {
+    io.stdout(line);
+    if (extra.info) io.stdout(`Target: ${scrubUrl(extra.info.target)} (authorized by ${scrubText(extra.info.authorization)})`);
+    for (const f of result.findings.filter((x) => x.blocking).slice(0, 10)) {
+      io.stdout(`  Must fix: ${f.severity}: ${f.title}${f.location.file ? ` (${f.location.file}${f.location.line ? `:${f.location.line}` : ''})` : ''}`);
+    }
+    for (const c of result.coverage.filter((x) => x.status === 'not_run')) io.stdout(`  Did not run: ${c.id}${c.required ? ' (required)' : ''}: ${c.reason}`);
+    io.stdout(`Report: ${result.outputs.report}`);
+  }
+  return exitCode;
+}

package/dist/security-runtime/src/cli/scan.mjs

@@ -0,0 +1,12 @@
+import { RUN_OPTIONS, runMode } from './run-common.mjs';
+
+export default {
+  name: 'scan',
+  summary: 'Fast repository scan; never runs repository code',
+  usage: '[path]',
+  maxPositionals: 1,
+  purpose: 'Runs the fast checks (dependencies, working-tree secrets, code, agent surface, workflows) on a repository and gives a PASS, BLOCKED or INCOMPLETE verdict. It never installs packages or runs repository code, and it writes only to its output directory.',
+  options: RUN_OPTIONS,
+  examples: ['vsg scan', 'vsg scan ../my-app --out ../scan-output', 'vsg scan --json'],
+  run: (args, io) => runMode('scan', args, io),
+};

package/dist/security-runtime/src/cli/setup.mjs

@@ -0,0 +1,59 @@
+import { FetchError, InstallError, UsageError } from '../core/errors.mjs';
+import { installTool, installVerifiedArchive } from '../core/installer.mjs';
+import { toolsDir } from '../core/paths.mjs';
+import { loadRegistry } from '../core/registry.mjs';
+import { runProcess } from '../core/runner.mjs';
+
+export default {
+  name: 'setup',
+  summary: 'Download and verify the pinned scanner tools',
+  usage: '[tool...]',
+  maxPositionals: 99,
+  purpose: 'Installs every tool in the registry for this platform into the tools cache. Each download is checked against its pinned SHA-256 before anything is extracted. PATH and system settings are never changed.',
+  options: [{ flag: '--repair', type: 'bool', help: 'Reinstall tools even if they look installed' }],
+  examples: ['vsg setup', 'vsg setup osv-scanner', 'vsg setup --repair'],
+  async run({ flags, positionals }, io) {
+    const registry = loadRegistry(io.registryDir);
+    const names = positionals.length ? positionals : [...registry.keys()];
+    for (const n of names) if (!registry.has(n)) throw new UsageError(`Unknown tool "${n}". Run vsg doctor to list registry tools.`);
+    const results = [];
+    for (const name of names) {
+      const tool = registry.get(name);
+      try {
+        if (tool.image) {
+          const docker = await runProcess({ command: 'docker', args: ['pull', tool.image], timeoutMs: 600_000 });
+          if (docker.status !== 'ran' || docker.exitCode !== 0) throw new InstallError(`Docker could not pull ${tool.image}. Start Docker Desktop and rerun vsg setup.`);
+          results.push({ name, status: 'installed', detail: tool.image });
+        } else {
+          const options = { force: !!flags.repair, log: (l) => io.stderr(l) };
+          if (process.platform === 'win32' && name === 'semgrep-rules') {
+            const r = await installVerifiedArchive(tool, options);
+            results.push({ name, status: r.status, detail: `${r.path} (verified archive; extracted only in Linux)` });
+          } else {
+            const r = await installTool(tool, options);
+            if (process.platform === 'win32' && name === 'opengrep') {
+              const linux = await installTool(tool, { ...options, platform: 'linux-x64' });
+              results.push({ name, status: r.status === 'already' && linux.status === 'already' ? 'already' : 'installed', detail: `${r.path}; Linux runner: ${linux.path}` });
+            } else {
+              results.push({ name, status: r.status, detail: r.path });
+            }
+          }
+        }
+      } catch (e) {
+        if (!(e instanceof InstallError) && !(e instanceof FetchError)) throw e;
+        results.push({ name, status: 'failed', detail: e.message });
+      }
+    }
+    const failed = results.filter((r) => r.status === 'failed');
+    const headline = !results.length ? 'SETUP: the registry has no tools yet'
+      : failed.length ? `SETUP FAILED: ${failed.length} of ${results.length} tools were not installed`
+        : `SETUP OK: ${results.length} of ${results.length} tools ready`;
+    if (flags.json) io.stdout(JSON.stringify({ headline, toolsDir: toolsDir(), results }));
+    else {
+      io.stdout(headline);
+      for (const r of results) io.stdout(`  ${r.name}: ${r.status}${r.detail ? `: ${r.detail}` : ''}`);
+      if (failed.length) io.stdout('Fix the problem above and rerun vsg setup. Nothing was installed from a failed download.');
+    }
+    return failed.length ? 2 : 0;
+  },
+};

package/dist/security-runtime/src/cli/url.mjs

@@ -0,0 +1,38 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { UsageError } from '../core/errors.mjs';
+import { vsgHome } from '../core/paths.mjs';
+import { LIVE_OPTIONS, prepareLive, requireDirectory } from './live-common.mjs';
+import { runMode } from './run-common.mjs';
+
+export default {
+  name: 'url',
+  summary: 'Passive live checks of a registered target (headers, cookies, CORS, exposed files, served JavaScript)',
+  usage: '<url>',
+  maxPositionals: 1,
+  purpose: 'Reads pages and files of a registered target with ordinary GET requests (2 per second or less) and reports headers, cookie flags, CORS, exposed sensitive files, source maps, secrets in served JavaScript and mail DNS records. The origin must be listed in ~/.vsg/targets.json or in the "urls" of the repository\'s vsg.config.json; otherwise it exits 3 before any request. Nothing is written to the target.',
+  options: [
+    { flag: '--out', type: 'string', arg: 'dir', help: 'Output directory (default: ~/.vsg/url/<host>)' },
+    { flag: '--repo', type: 'string', arg: 'dir', help: 'Product repository whose vsg.config.json urls and vsg.accept.json apply (default: the current directory when it has a vsg.config.json)' },
+    ...LIVE_OPTIONS,
+  ],
+  examples: ['vsg url https://staging.example.com', 'vsg url http://127.0.0.1:3000 --json', 'vsg url https://preview.example.com --repo ../my-app'],
+  async run(args, io) {
+    const urlText = args.positionals[0];
+    if (!urlText) throw new UsageError('vsg url needs the URL to check. Run vsg url --help.');
+    let repo = args.flags.repo ? path.resolve(io.cwd, args.flags.repo) : null;
+    if (repo) requireDirectory(repo);
+    else if (fs.existsSync(path.join(io.cwd, 'vsg.config.json'))) repo = io.cwd;
+    const live = prepareLive(urlText, { io, repo, rateFlag: args.flags.rate });
+    const home = io.env?.VSG_HOME || vsgHome();
+    const out = path.join(home, 'url', live.auth.host.replace(/[^A-Za-z0-9.-]/g, '_'));
+    // The pipeline wants a repository directory for config and acceptances. With none, an empty scratch directory stands in.
+    const scratch = repo ? null : fs.mkdtempSync(path.join(os.tmpdir(), 'vsg-url-'));
+    try {
+      return await runMode('url', args, io, { repo: repo ?? scratch, out, flags: { ...live.flags, noReview: !repo }, info: live.info });
+    } finally {
+      if (scratch) fs.rmSync(scratch, { recursive: true, force: true });
+    }
+  },
+};

package/dist/security-runtime/src/core/accept.mjs

@@ -0,0 +1,141 @@
+// Acceptances (vsg.accept.json), product config (vsg.config.json), and the human-review listing against a base ref.
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveBase } from './base-ref.mjs';
+import { UsageError } from './errors.mjs';
+
+const DAY = 24 * 60 * 60 * 1000;
+const dateMs = (s, endOfDay = false) => {
+  if (typeof s !== 'string') return NaN;
+  return Date.parse(/^\d{4}-\d{2}-\d{2}$/.test(s) ? `${s}T${endOfDay ? '23:59:59' : '00:00:00'}Z` : s);
+};
+
+function readJson(file, label) {
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return undefined; }
+  try { return JSON.parse(text); } catch (e) { throw new UsageError(`${label} is not valid JSON (${e.message}). Fix it and rerun.`); }
+}
+
+/** Checks one acceptance entry. Returns an error string, or null when it is well formed. A day of clock skew is allowed for approvedAt. */
+export function acceptanceProblem(a, now = Date.now()) {
+  if (!a || typeof a !== 'object') return 'not an object';
+  if (!/^[0-9a-f]{64}$/.test(a.fingerprint ?? '')) return 'fingerprint must be 64 hex characters';
+  for (const k of ['reason', 'approvedBy']) if (typeof a[k] !== 'string' || !a[k].trim()) return `${k} is required`;
+  const approved = dateMs(a.approvedAt);
+  const expires = dateMs(a.expires, true);
+  if (Number.isNaN(approved)) return 'approvedAt must be a date';
+  if (Number.isNaN(expires)) return 'expires is required and must be a date';
+  if (approved > now + DAY) return 'approvedAt is in the future';
+  if (expires <= approved) return 'expires must be after approvedAt';
+  if (expires - approved > 90 * DAY + DAY) return 'expires must be within 90 days of approvedAt';
+  return null;
+}
+
+/** Loads vsg.accept.json (an array, or { acceptances: [...] }). Returns { valid, invalid }. Invalid or expired entries suppress nothing. */
+export function loadAcceptances(repo, { now = Date.now() } = {}) {
+  const data = readJson(path.join(repo, 'vsg.accept.json'), 'vsg.accept.json');
+  const list = Array.isArray(data) ? data : data?.acceptances ?? [];
+  if (data !== undefined && !Array.isArray(list)) throw new UsageError('vsg.accept.json must be an array or { "acceptances": [] }.');
+  const valid = [];
+  const invalid = [];
+  for (const a of list) {
+    const problem = acceptanceProblem(a, now);
+    if (problem) { invalid.push({ entry: a, problem }); continue; }
+    valid.push({ ...a, expired: dateMs(a.expires, true) < now });
+  }
+  return { valid, invalid };
+}
+
+/** Marks findings accepted (valid, unexpired entry) or expired-acceptance. Everything else is left open. */
+export function applyAcceptances(findings, { valid }) {
+  for (const f of findings) {
+    const mine = valid.filter((a) => a.fingerprint === f.fingerprint);
+    if (mine.some((a) => !a.expired)) f.status = 'accepted';
+    else if (mine.length) f.status = 'expired-acceptance';
+  }
+  return findings;
+}
+
+const strArray = (v, name) => {
+  if (v === undefined) return [];
+  if (!Array.isArray(v) || !v.every((x) => typeof x === 'string')) throw new UsageError(`vsg.config.json: ${name} must be an array of strings.`);
+  return v;
+};
+
+/** authHelpers: function names the code check accepts as a caller check. They go into a regex, so only plain identifiers are allowed. */
+const authHelperNames = (v) => {
+  const names = strArray(v, 'authHelpers');
+  const bad = names.find((n) => !/^[A-Za-z_$][\w$]*$/.test(n));
+  if (bad !== undefined) throw new UsageError(`vsg.config.json: authHelpers entries must be plain function names (letters, digits, _ or $), not "${bad}".`);
+  return names;
+};
+
+/** Loads and validates vsg.config.json (optional). */
+export function loadConfig(repo) {
+  const data = readJson(path.join(repo, 'vsg.config.json'), 'vsg.config.json') ?? {};
+  if (typeof data !== 'object' || Array.isArray(data)) throw new UsageError('vsg.config.json must be a JSON object.');
+  const remove = data.requiredChecks?.remove ?? [];
+  if (!Array.isArray(remove) || remove.some((r) => typeof r?.check !== 'string' || typeof r?.reason !== 'string' || !r.reason.trim())) {
+    throw new UsageError('vsg.config.json: requiredChecks.remove entries need { "check", "reason" } with a reason.');
+  }
+  if (data.baseRef !== undefined && typeof data.baseRef !== 'string') throw new UsageError('vsg.config.json: baseRef must be a string.');
+  return {
+    baseRef: data.baseRef ?? null,
+    urls: strArray(data.urls, 'urls'),
+    supabase: { projectRef: data.supabase?.projectRef ?? null },
+    publicTables: strArray(data.publicTables, 'publicTables'),
+    authHelpers: authHelperNames(data.authHelpers),
+    artifacts: strArray(data.artifacts, 'artifacts'),
+    licenseAllow: strArray(data.licenseAllow, 'licenseAllow'),
+    agentReview: { command: data.agentReview?.command ?? null },
+    mobile: { apk: typeof data.mobile?.apk === 'string' && data.mobile.apk ? data.mobile.apk : null },
+    requiredChecks: { remove },
+  };
+}
+
+const git = (repo, args) => {
+  try {
+    return execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 20_000 }).trim();
+  } catch {
+    return null;
+  }
+};
+
+/** The base commit (a SHA): --base flag, then config.baseRef, then the merge-base with the remote default branch (see base-ref.mjs). Null when git can't tell. */
+export function resolveBaseRef(repo, opts = {}) {
+  return resolveBase(repo, opts).sha;
+}
+
+const parseJson = (text) => { try { return JSON.parse(text); } catch { return undefined; } };
+
+/** Lists acceptance and policy changes against the base ref for human review. `why` says why there is no base (see resolveBase). Returns [string]. */
+export function reviewItems(repo, baseRef, why) {
+  if (!baseRef) return [`No base ref is available (${why ?? 'no git history or remote default branch'}), so acceptance and policy changes could not be compared. Review vsg.accept.json and vsg.config.json by hand.`];
+  const items = [];
+  const baseOf = (file) => { const t = git(repo, ['show', `${baseRef}:./${file}`]); return t === null ? undefined : parseJson(t); };
+  const nowOf = (file) => parseJson((() => { try { return fs.readFileSync(path.join(repo, file), 'utf8'); } catch { return 'undefined'; } })());
+
+  const accList = (d) => (Array.isArray(d) ? d : d?.acceptances ?? []);
+  const before = new Map(accList(baseOf('vsg.accept.json')).map((a) => [a?.fingerprint, a]));
+  const after = new Map(accList(nowOf('vsg.accept.json')).map((a) => [a?.fingerprint, a]));
+  for (const [fp, a] of after) {
+    const short = String(fp).slice(0, 12);
+    if (!before.has(fp)) items.push(`Acceptance added for ${short}: ${a.reason ?? '(no reason)'} (approved by ${a.approvedBy ?? 'nobody'}, expires ${a.expires ?? 'never'}).`);
+    else if (JSON.stringify(before.get(fp)) !== JSON.stringify(a)) items.push(`Acceptance changed for ${short}: now expires ${a.expires ?? 'never'}, approved by ${a.approvedBy ?? 'nobody'}.`);
+  }
+  for (const fp of before.keys()) if (!after.has(fp)) items.push(`Acceptance removed for ${String(fp).slice(0, 12)}.`);
+
+  const b = baseOf('vsg.config.json') ?? {};
+  const n = nowOf('vsg.config.json') ?? {};
+  const diff = (label, was, is) => {
+    const w = new Set(was.map((x) => JSON.stringify(x)));
+    const i = new Set(is.map((x) => JSON.stringify(x)));
+    for (const x of i) if (!w.has(x)) items.push(`${label} added: ${x}`);
+    for (const x of w) if (!i.has(x)) items.push(`${label} removed: ${x}`);
+  };
+  diff('publicTables entry', b.publicTables ?? [], n.publicTables ?? []);
+  diff('authHelpers entry', b.authHelpers ?? [], n.authHelpers ?? []);
+  diff('requiredChecks.remove entry', b.requiredChecks?.remove ?? [], n.requiredChecks?.remove ?? []);
+  return items;
+}