hullproof 0.0.0-stage → 0.5.0

package/dist/ci/sarif-check.js

@@ -0,0 +1,157 @@
+// A strict structural check of the SARIF 2.1.0 file the engine writes. The official JSON Schema of SARIF 2.1.0 is not shipped with
+// the engine and was not available offline when this was written, so this checks the parts of that schema the engine uses: required
+// properties, types, enum values, array minimums, the allowed property names of every object the engine writes, and the links
+// between a result and its rule. It does not claim to be the whole schema. GitHub code scanning applies the real schema on upload.
+const LEVELS = new Set(['none', 'note', 'warning', 'error']);
+const OBJ = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+// The property names the engine may write in each object, taken from the SARIF 2.1.0 definitions of those objects.
+const ALLOWED = {
+    log: ['$schema', 'version', 'runs'],
+    run: ['tool', 'results', 'automationDetails', 'columnKind'],
+    driver: ['name', 'version', 'semanticVersion', 'rules', 'informationUri'],
+    rule: ['id', 'name', 'shortDescription', 'fullDescription', 'defaultConfiguration', 'properties'],
+    result: ['ruleId', 'ruleIndex', 'level', 'message', 'locations', 'partialFingerprints', 'properties'],
+    location: ['physicalLocation', 'message'],
+    physical: ['artifactLocation', 'region'],
+    artifact: ['uri'],
+    region: ['startLine'],
+};
+export function checkSarif(doc) {
+    const errs = [];
+    const e = (path, why) => { errs.push(`${path}: ${why}`); };
+    const only = (v, kind, path) => {
+        for (const k of Object.keys(v))
+            if (!ALLOWED[kind].includes(k))
+                e(path, `property "${k}" is not one the engine writes`);
+    };
+    const text = (v, path) => {
+        if (!OBJ(v) || typeof v.text !== 'string' || v.text.length === 0)
+            e(path, 'needs a non empty "text"');
+    };
+    if (!OBJ(doc))
+        return ['$: not an object'];
+    only(doc, 'log', '$');
+    if (doc.version !== '2.1.0')
+        e('$.version', 'must be "2.1.0"');
+    if (typeof doc.$schema !== 'string' || !doc.$schema.includes('sarif-2.1.0'))
+        e('$.$schema', 'must name the 2.1.0 schema');
+    if (!Array.isArray(doc.runs) || doc.runs.length < 1) {
+        e('$.runs', 'needs at least one run');
+        return errs;
+    }
+    doc.runs.forEach((run, ri) => {
+        const rp = `$.runs[${ri}]`;
+        if (!OBJ(run)) {
+            e(rp, 'not an object');
+            return;
+        }
+        only(run, 'run', rp);
+        const tool = run.tool;
+        if (!OBJ(tool) || !OBJ(tool.driver)) {
+            e(`${rp}.tool.driver`, 'required');
+            return;
+        }
+        const d = tool.driver;
+        only(d, 'driver', `${rp}.tool.driver`);
+        if (typeof d.name !== 'string' || !d.name)
+            e(`${rp}.tool.driver.name`, 'required');
+        const rules = d.rules === undefined ? [] : d.rules;
+        if (!Array.isArray(rules))
+            e(`${rp}.tool.driver.rules`, 'must be an array');
+        const ruleIds = [];
+        (Array.isArray(rules) ? rules : []).forEach((r, i) => {
+            const p = `${rp}.tool.driver.rules[${i}]`;
+            if (!OBJ(r)) {
+                e(p, 'not an object');
+                return;
+            }
+            only(r, 'rule', p);
+            if (typeof r.id !== 'string' || !r.id)
+                e(`${p}.id`, 'required');
+            else {
+                if (ruleIds.includes(r.id))
+                    e(`${p}.id`, 'duplicate rule id');
+                ruleIds.push(r.id);
+            }
+            if (r.shortDescription !== undefined)
+                text(r.shortDescription, `${p}.shortDescription`);
+            if (r.fullDescription !== undefined)
+                text(r.fullDescription, `${p}.fullDescription`);
+            if (OBJ(r.defaultConfiguration) && r.defaultConfiguration.level !== undefined && !LEVELS.has(String(r.defaultConfiguration.level)))
+                e(`${p}.defaultConfiguration.level`, 'not a SARIF level');
+            const sev = OBJ(r.properties) ? r.properties['security-severity'] : undefined;
+            if (sev !== undefined && !(typeof sev === 'string' && /^\d+(\.\d+)?$/.test(sev) && Number(sev) <= 10))
+                e(`${p}.properties.security-severity`, 'must be a string number from 0 to 10');
+        });
+        if (!Array.isArray(run.results)) {
+            e(`${rp}.results`, 'must be an array');
+            return;
+        }
+        run.results.forEach((res, i) => {
+            const p = `${rp}.results[${i}]`;
+            if (!OBJ(res)) {
+                e(p, 'not an object');
+                return;
+            }
+            only(res, 'result', p);
+            text(res.message, `${p}.message`);
+            if (res.level !== undefined && !LEVELS.has(String(res.level)))
+                e(`${p}.level`, 'not a SARIF level');
+            if (typeof res.ruleId !== 'string' || !res.ruleId)
+                e(`${p}.ruleId`, 'required');
+            if (res.ruleIndex !== undefined) {
+                if (!Number.isInteger(res.ruleIndex) || res.ruleIndex < 0 || res.ruleIndex >= ruleIds.length)
+                    e(`${p}.ruleIndex`, 'not an index into tool.driver.rules');
+                else if (ruleIds[res.ruleIndex] !== res.ruleId)
+                    e(`${p}.ruleIndex`, 'points at a rule with another id');
+            }
+            else if (!ruleIds.includes(String(res.ruleId)))
+                e(`${p}.ruleId`, 'names no rule in tool.driver.rules');
+            if (!Array.isArray(res.locations) || res.locations.length < 1)
+                e(`${p}.locations`, 'needs at least one location');
+            else
+                res.locations.forEach((l, li) => {
+                    const lp = `${p}.locations[${li}]`;
+                    if (!OBJ(l)) {
+                        e(lp, 'not an object');
+                        return;
+                    }
+                    only(l, 'location', lp);
+                    if (l.message !== undefined)
+                        text(l.message, `${lp}.message`);
+                    const ph = l.physicalLocation;
+                    if (!OBJ(ph)) {
+                        e(`${lp}.physicalLocation`, 'required');
+                        return;
+                    }
+                    only(ph, 'physical', `${lp}.physicalLocation`);
+                    const al = ph.artifactLocation;
+                    if (!OBJ(al))
+                        e(`${lp}.physicalLocation.artifactLocation`, 'required');
+                    else {
+                        only(al, 'artifact', `${lp}.physicalLocation.artifactLocation`);
+                        const u = al.uri;
+                        if (typeof u !== 'string' || !u)
+                            e(`${lp}.physicalLocation.artifactLocation.uri`, 'required');
+                        else if (/^[a-z][a-z0-9+.-]*:|^\/|(^|\/)\.\.(\/|$)|\\/i.test(u))
+                            e(`${lp}.physicalLocation.artifactLocation.uri`, 'must be a relative path inside the repository');
+                    }
+                    const rg = ph.region;
+                    if (rg !== undefined) {
+                        if (!OBJ(rg))
+                            e(`${lp}.physicalLocation.region`, 'not an object');
+                        else {
+                            only(rg, 'region', `${lp}.physicalLocation.region`);
+                            if (!Number.isInteger(rg.startLine) || rg.startLine < 1)
+                                e(`${lp}.physicalLocation.region.startLine`, 'must be an integer of 1 or more');
+                        }
+                    }
+                });
+            if (res.partialFingerprints !== undefined) {
+                if (!OBJ(res.partialFingerprints) || Object.values(res.partialFingerprints).some((x) => typeof x !== 'string' || !x))
+                    e(`${p}.partialFingerprints`, 'must map names to non empty strings');
+            }
+        });
+    });
+    return errs;
+}

package/dist/ci/sarif.js

@@ -0,0 +1,61 @@
+// results.sarif: the fail records of the findings file as SARIF 2.1.0, for GitHub code scanning and other viewers.
+// Same findings, same bytes: no clock, no absolute path, everything sorted. Only fail records are results. Observations, leads and
+// routed items stay out, as they stay out of the gate.
+import { cmp, stableJson } from '../util.js';
+import { ENGINE_VERSION } from '../version.js';
+export const SARIF_VERSION = '2.1.0';
+export const SARIF_SCHEMA = 'https://json.schemastore.org/sarif-2.1.0.json';
+// GitHub reads the security-severity property as a score: above 9 critical, 7 to 8.9 high, 4 to 6.9 medium, below 4 low.
+const SCORE = { BLOCKER: '9.8', CRITICAL: '9.1', HIGH: '7.5', MEDIUM: '5.0', LOW: '2.0' };
+const LEVEL = { BLOCKER: 'error', CRITICAL: 'error', HIGH: 'warning', MEDIUM: 'warning', LOW: 'note' };
+// A repository path as a relative URI: no leading slash or dot segment, percent encoded where a URI needs it.
+export const uriOf = (file) => file.replace(/\\/g, '/').replace(/^(\.\/)+/, '').replace(/^\/+/, '').split('/').map(encodeURIComponent).join('/');
+export function buildSarif(findings, kit, fallbackFile) {
+    const fails = findings.records.filter((r) => r.kind === 'fail').sort((a, b) => cmp(a.fingerprint, b.fingerprint));
+    // One SARIF rule per requirement id that appears in a fail record, in id order.
+    const ids = [...new Set(fails.flatMap((f) => f.sec_ids))].sort(cmp);
+    const rules = ids.map((id) => {
+        const c = kit.byId.get(id);
+        return {
+            id,
+            name: id.replace(/[^A-Za-z0-9]/g, ''),
+            shortDescription: { text: c?.title ?? id },
+            fullDescription: { text: c ? `${c.title}. Severity ${c.severity}, ${c.authority} authority, ${c.edition} edition.` : id },
+            defaultConfiguration: { level: LEVEL[c?.severity ?? 'HIGH'] },
+            properties: { 'security-severity': SCORE[c?.severity ?? 'HIGH'], tags: ['security', c?.severity ?? 'HIGH'] },
+        };
+    });
+    const ruleIndex = new Map(ids.map((id, i) => [id, i]));
+    const results = fails.map((f) => {
+        const primary = f.sec_ids[0];
+        const ev = f.evidence.length ? f.evidence : [{ file: fallbackFile, line: 1, note: '' }];
+        const locations = ev.slice(0, 8).map((e) => ({
+            physicalLocation: { artifactLocation: { uri: uriOf(e.file) }, region: { startLine: Math.max(1, e.line) } },
+            ...(e.note ? { message: { text: e.note } } : {}),
+        }));
+        return {
+            ruleId: primary,
+            ruleIndex: ruleIndex.get(primary),
+            level: LEVEL[f.severity],
+            message: { text: `${f.severity}: ${f.title}. ${f.impact_statement} How to fix it: ${f.remediation.strategy}` },
+            locations,
+            partialFingerprints: { 'hullproofFingerprint/v1': f.fingerprint },
+            properties: {
+                severity: f.severity, confidence: f.confidence, requirements: f.sec_ids, tool: f.machine_evidence?.tool ?? 'unknown',
+                'security-severity': SCORE[f.severity],
+            },
+        };
+    });
+    return {
+        $schema: SARIF_SCHEMA,
+        version: SARIF_VERSION,
+        runs: [{
+                tool: { driver: { name: 'Hullproof Engine', version: ENGINE_VERSION, semanticVersion: ENGINE_VERSION, rules } },
+                // Paths are relative to the repository root. The category keeps one code scanning history for the engine.
+                automationDetails: { id: 'hullproof/' },
+                columnKind: 'utf16CodeUnits',
+                results,
+            }],
+    };
+}
+export const sarifJson = (s) => stableJson(s);

package/dist/cli.js

@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+// hullproof: the engine command line. Node 22.18 or later runs this TypeScript file directly. No dependencies.
+import { mkdirSync, realpathSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { discover } from './discover/discover.js';
+import { mapCommand } from './commands/map.js';
+import { scan } from './commands/scan.js';
+import { huntCommand } from './commands/hunt.js';
+import { ciCommand } from './commands/ci.js';
+import { hooksCommand } from './commands/hooks.js';
+import { mcpCommand } from './commands/mcp.js';
+import { FAIL_ON_LEVELS } from './ci/comment.js';
+import { proveCommand } from './commands/prove.js';
+import { packCommand } from './commands/pack.js';
+import { gate, report } from './commands/report-gate.js';
+import { stableJson } from './util.js';
+import { ENGINE_VERSION } from './version.js';
+// Exit codes. 0, 1 and 2 match the kit gate; 3 is reserved for a command that exists but is not built yet (none today).
+export const EXIT = { ok: 0, open: 1, badInput: 2, notImplemented: 3 };
+const HELP = `hullproof ${ENGINE_VERSION}
+
+Usage: hullproof <command> [repository] [options]
+
+Commands:
+  discover   Detect the stack of a repository and write stack.json
+  map        Build the code map of a repository (entry points and what protects them) and write codemap.json
+  scan       Run discovery, the scanners and the checks; write <out>/<commit>/
+  ci         One command for CI: scan, map, check, gate; write findings.json, report.md, results.sarif, pr-comment.md
+  hooks      Install or remove the git pre-commit hook (install, uninstall), or run its fast check (run)
+  mcp        Serve the scan results to an AI tool over MCP on stdio (read only; run_scan with --allow-run)
+  hunt       Hunt for leads with a model, confirm them with evidence, or replay saved outputs (--replay)
+  prove      Run test specs against a local copy of the app in a sandbox and keep the transcripts as evidence
+  pack       Validate the stack packs (validate), list them (list), or print the coverage table from their recorded results (table)
+  report     Write report.md from a scan folder
+  gate       Apply the release gate to a scan folder and exit with its code
+  version    Print the engine version
+  help       Print this help
+
+Options for discover:
+  --out DIR  Folder for stack.json (default: .hullproof inside the repository). Use --out - to print to standard output.
+
+Options for map:
+  --out DIR  Folder for codemap.json (default: .hullproof inside the repository). Use --out - to print to standard output.
+
+Options for scan, report and gate:
+  --out DIR         Base folder (default: .hullproof inside the repository). Files go to DIR/<commit>/.
+  --kit DIR         The kit folder holding docs/hullproof/security-controls.json (default: HULLPROOF_KIT, the
+                    repository itself when the kit is installed there, then a folder called hullproof-free/kit next to the engine)
+scan only:
+  --edition free|pro  Which requirements are in scope (default pro)
+  --stage LAUNCH|GROWTH|SCALE  Default: docs/security/STAGE.md, else LAUNCH
+  --allow-network   Let OSV Scanner reach osv.dev (off by default)
+  --tools a,b       Limit the scanners (semgrep, gitleaks, osv-scanner, trivy)
+  --rule-pack DIR   Add the Semgrep rule files in DIR (for example a rule pack of your own) to the engine rules; a file with
+                    the same name as an engine rule file replaces it (default: HULLPROOF_RULE_PACK, else none)
+report and gate:
+  --commit SHA      Read the scan folder of this commit (default: HEAD)
+  --owner FILE      Owner evidence: audit_report, rollback, results rows, acceptances (see README)
+  --date YYYY-MM-DD The day acceptances are judged on (default: today, UTC)
+
+Options for ci (also --out, --kit, --edition, --stage, --allow-network, --tools, --rule-pack as for scan; --owner, --date as for gate):
+  --fail-on LEVEL   blocker, critical, high, medium, low or none (default blocker). Exit 1 when a finding at or above LEVEL failed.
+  --artifacts DIR   Flat folder for the four output files (default: ci inside the --out folder)
+  --hunt            Pro only: run the model hunt first. Needs a provider key in the environment (a CI secret); fork pull requests get none.
+  --provider, --model as for hunt
+  ci runs no model and no container unless --hunt is given. The same commit gives the same four files, byte for byte.
+
+Options for hooks (hullproof hooks install|uninstall|run [repository]):
+  --mode git|husky|pre-commit  Where the hook goes (default: Husky if the repository uses it, else the pre-commit framework if it has a config, else plain git)
+  --dry-run         install and uninstall: say what would change and change nothing
+  --kit DIR         run: the kit folder (as for scan)
+  --no-semgrep      run: check secrets and the deterministic checks only (also: HULLPROOF_HOOK_SEMGREP=0)
+  run looks at the staged files only, blocks (exit 1) on a secret or a BLOCKER finding in them, and sends nothing anywhere. An error never blocks a commit.
+
+Options for mcp (hullproof mcp [repository]):
+  --kit DIR         The kit folder (as for scan)
+  --edition free|pro  Which requirements are served (default: the kit decides)
+  --allow-run       Also offer run_scan, which runs hullproof ci and writes only under .hullproof/. Off by default.
+  mcp makes no network call, runs no model, and never leaves the repository folder. It writes nothing but JSON-RPC to standard output.
+
+Options for hunt:
+  --provider NAME   anthropic, openai, gemini or local (default: HULLPROOF_PROVIDER, else the one provider whose key is set)
+  --model NAME      The model to call (default: HULLPROOF_MODEL). Keys come from the environment or a .env.local file, never from a flag.
+  --runs N          Hunting runs per entry point (default 3), then one synthesis call
+  --dry-run         List the entry points and calls and make no model call
+  --resume          Continue an interrupted hunt from the answers already saved
+  --replay          Rerun the confirmation from the saved answers; no model, same bytes every time
+  --out, --kit, --commit as for report
+
+Options for prove:
+  --allow-run       Required to run the app. The owner must also type the confirmation (asked on a terminal, or pass --confirm).
+  --confirm TEXT    The confirmation phrase, for a run with no terminal. Nothing else (no variable, no CI setting) can stand in for it.
+  --spec FILE[,FILE] Test specs written by hand (see docs/INTERFACES.md); they are checked and copied into the scan folder.
+  --allow-install-scripts  Let dependency install scripts run in the build container (default off). Needed for native modules such
+                    as better-sqlite3, bcrypt and sharp. Third party code runs with network access to the package registry.
+  --gen             Write specs from hunt leads with a model (Pro). Runs nothing unless --allow-run is also given.
+  --replay          Rebuild result.json from the saved specs and transcripts. No sandbox, no app, same bytes every time.
+  --self-test       Run the escape attempts (network call, host file read, fork bomb, long loop) against this machine's container runtime.
+  --runtime NAME    The container command: docker (Colima and Docker Desktop) or podman (default: HULLPROOF_CONTAINER_BIN, else docker)
+  --provider, --model, --out, --commit as for hunt
+  prove accepts no address. It only ever runs a copy of the app inside the sandbox, and refuses --target.
+
+Options for pack (hullproof pack validate|list|table [pack folder ...]):
+  --root DIR        The engine checkout the packs name their files in (default: this engine). Folders given by name are validated in place.
+  validate rejects a pack that is missing a part for its level, lists a rule without a test, has no fixture result, uses a bad level or claims
+  a level its recorded fixture result does not support. It reads files only. Exit 1 when a pack fails.
+
+Exit codes: 0 done (gate: READY or READY WITH ACCEPTED RISK), 1 open items (gate: NOT READY),
+2 bad input, a refused run or a records problem.
+`;
+const TOOLS = ['semgrep', 'osv-scanner', 'gitleaks', 'trivy', 'checkov'];
+const VALUE_FLAGS = new Set(['--mode', '--fail-on', '--artifacts', '--provider', '--model', '--runs', '--out', '--kit', '--edition', '--stage', '--tools', '--commit', '--owner', '--date', '--rule-pack', '--confirm', '--spec', '--runtime', '--target']);
+const BOOL_FLAGS = new Set(['--no-semgrep', '--hunt', '--allow-network', '--dry-run', '--resume', '--replay', '--allow-run', '--gen', '--self-test', '--allow-install-scripts']);
+function parse(cmd, rest, allowed) {
+    const flags = new Map();
+    let repo = '.';
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        if (!a.startsWith('-')) {
+            repo = a;
+            continue;
+        }
+        if (!allowed.includes(a))
+            return `unknown option ${a}`;
+        if (BOOL_FLAGS.has(a)) {
+            flags.set(a, true);
+            continue;
+        }
+        const v = rest[++i];
+        if (v === undefined || (VALUE_FLAGS.has(a) && v.startsWith('--')))
+            return `${a} needs a value`;
+        flags.set(a, v);
+    }
+    return { repo, flags };
+}
+function discoverCmd(rest, out, err) {
+    const p = parse('discover', rest, ['--out']);
+    if (typeof p === 'string') {
+        err(`hullproof discover: ${p}${p.startsWith('--out') ? ', or - for standard output' : ''}.\n`);
+        return EXIT.badInput;
+    }
+    const outDir = p.flags.get('--out') ?? null;
+    let json;
+    try {
+        json = stableJson(discover(p.repo));
+    }
+    catch (e) {
+        err(`hullproof discover: ${e.message}\n`);
+        return EXIT.badInput;
+    }
+    if (outDir === '-') {
+        out(json);
+        return EXIT.ok;
+    }
+    const dir = resolve(outDir ?? join(p.repo, '.hullproof'));
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'stack.json'), json);
+    out(`hullproof discover: wrote ${join(dir, 'stack.json')}\n`);
+    return EXIT.ok;
+}
+function mapCmd(rest, out, err) {
+    const p = parse('map', rest, ['--out']);
+    if (typeof p === 'string') {
+        err(`hullproof map: ${p}${p.startsWith('--out') ? ', or - for standard output' : ''}.\n`);
+        return EXIT.badInput;
+    }
+    return mapCommand(p.repo, p.flags.get('--out') ?? null, out, err);
+}
+async function scanCmd(rest, err) {
+    const p = parse('scan', rest, ['--out', '--kit', '--edition', '--stage', '--allow-network', '--tools', '--rule-pack']);
+    if (typeof p === 'string') {
+        err(`hullproof scan: ${p}\n`);
+        return EXIT.badInput;
+    }
+    const edition = p.flags.get('--edition') ?? 'pro';
+    const stage = p.flags.get('--stage') ?? null;
+    const tools = p.flags.has('--tools') ? String(p.flags.get('--tools')).split(',').map((t) => t.trim()) : null;
+    if (edition !== 'free' && edition !== 'pro') {
+        err('hullproof scan: --edition is free or pro\n');
+        return EXIT.badInput;
+    }
+    if (stage && !['LAUNCH', 'GROWTH', 'SCALE'].includes(stage)) {
+        err('hullproof scan: --stage is LAUNCH, GROWTH or SCALE\n');
+        return EXIT.badInput;
+    }
+    if (tools && tools.some((t) => !TOOLS.includes(t))) {
+        err(`hullproof scan: --tools takes ${TOOLS.join(', ')}\n`);
+        return EXIT.badInput;
+    }
+    return scan({
+        repo: p.repo, out: p.flags.get('--out') ?? null, kit: p.flags.get('--kit') ?? null,
+        edition, stage: stage, allowNetwork: p.flags.has('--allow-network'), tools: tools,
+        rulePack: p.flags.get('--rule-pack') ?? null, log: (s) => err(s + '\n'),
+    });
+}
+async function ciCmd(rest, out, err) {
+    const p = parse('ci', rest, ['--out', '--kit', '--edition', '--stage', '--allow-network', '--tools', '--rule-pack', '--owner', '--date', '--fail-on', '--artifacts', '--hunt', '--provider', '--model']);
+    if (typeof p === 'string') {
+        err(`hullproof ci: ${p}\n`);
+        return EXIT.badInput;
+    }
+    const get = (f) => p.flags.get(f) ?? null;
+    const edition = get('--edition');
+    const stage = get('--stage');
+    const failOn = (get('--fail-on') ?? 'blocker').toLowerCase();
+    const tools = get('--tools') ? String(get('--tools')).split(',').map((t) => t.trim()) : null;
+    if (edition && edition !== 'free' && edition !== 'pro') {
+        err('hullproof ci: --edition is free or pro\n');
+        return EXIT.badInput;
+    }
+    if (stage && !['LAUNCH', 'GROWTH', 'SCALE'].includes(stage)) {
+        err('hullproof ci: --stage is LAUNCH, GROWTH or SCALE\n');
+        return EXIT.badInput;
+    }
+    if (!FAIL_ON_LEVELS.includes(failOn)) {
+        err(`hullproof ci: --fail-on takes ${FAIL_ON_LEVELS.join(', ')}\n`);
+        return EXIT.badInput;
+    }
+    if (tools && tools.some((t) => !TOOLS.includes(t))) {
+        err(`hullproof ci: --tools takes ${TOOLS.join(', ')}\n`);
+        return EXIT.badInput;
+    }
+    if (get('--date') && !/^\d{4}-\d{2}-\d{2}$/.test(get('--date'))) {
+        err('hullproof ci: --date needs YYYY-MM-DD\n');
+        return EXIT.badInput;
+    }
+    return ciCommand({
+        repo: p.repo, out: get('--out'), kit: get('--kit'), edition: edition, stage: stage,
+        failOn: failOn, artifacts: get('--artifacts'), allowNetwork: p.flags.has('--allow-network'), tools: tools,
+        rulePack: get('--rule-pack'), owner: get('--owner'), date: get('--date'), hunt: p.flags.has('--hunt'), provider: get('--provider'), model: get('--model'),
+        log: (s) => err(s + '\n'), print: (s) => out(s + '\n'),
+    });
+}
+async function hooksCmd(rest, err) {
+    const [action, ...more] = rest;
+    const p = parse('hooks', more, ['--mode', '--dry-run', '--kit', '--no-semgrep']);
+    if (typeof p === 'string') {
+        err(`hullproof hooks: ${p}\n`);
+        return EXIT.badInput;
+    }
+    const get = (f) => p.flags.get(f) ?? null;
+    return hooksCommand({ action: action ?? '', repo: p.repo, mode: get('--mode'), dryRun: p.flags.has('--dry-run'), kit: get('--kit'), noSemgrep: p.flags.has('--no-semgrep'), log: (s) => err(s + '\n') });
+}
+async function mcpCmd(rest, err) {
+    const p = parse('mcp', rest, ['--kit', '--edition', '--allow-run']);
+    if (typeof p === 'string') {
+        err(`hullproof mcp: ${p}\n`);
+        return EXIT.badInput;
+    }
+    const get = (f) => p.flags.get(f) ?? null;
+    const edition = get('--edition');
+    if (edition && edition !== 'free' && edition !== 'pro') {
+        err('hullproof mcp: --edition is free or pro\n');
+        return EXIT.badInput;
+    }
+    return mcpCommand({ repo: p.repo, kit: get('--kit'), edition: edition, allowRun: p.flags.has('--allow-run'), log: (s) => err(s + '\n') });
+}
+async function readCmd(cmd, rest, err) {
+    const p = parse(cmd, rest, ['--out', '--kit', '--commit', '--owner', '--date']);
+    if (typeof p === 'string') {
+        err(`hullproof ${cmd}: ${p}\n`);
+        return EXIT.badInput;
+    }
+    const get = (f) => p.flags.get(f) ?? null;
+    const o = { repo: p.repo, out: get('--out'), kit: get('--kit'), commit: get('--commit'), owner: get('--owner'), date: get('--date'), log: (s) => err(s + '\n') };
+    return cmd === 'report' ? report(o) : gate(o);
+}
+async function huntCmd(rest, err) {
+    const p = parse('hunt', rest, ['--out', '--kit', '--commit', '--provider', '--model', '--runs', '--dry-run', '--resume', '--replay']);
+    if (typeof p === 'string') {
+        err(`hullproof hunt: ${p}\n`);
+        return EXIT.badInput;
+    }
+    const get = (f) => p.flags.get(f) ?? null;
+    const runsRaw = get('--runs');
+    if (runsRaw !== null && !/^[1-9]\d*$/.test(runsRaw)) {
+        err('hullproof hunt: --runs needs a whole number of 1 or more\n');
+        return EXIT.badInput;
+    }
+    return huntCommand({ repo: p.repo, out: get('--out'), kit: get('--kit'), commit: get('--commit'), provider: get('--provider'), model: get('--model'),
+        runs: runsRaw === null ? null : Number(runsRaw), dryRun: p.flags.has('--dry-run'), resume: p.flags.has('--resume'), replay: p.flags.has('--replay'), log: (s) => err(s + '\n') });
+}
+function packCmd(rest, out, err) {
+    const [action, ...more] = rest;
+    const targets = [];
+    let root = null;
+    for (let i = 0; i < more.length; i++) {
+        if (more[i] === '--root') {
+            root = more[++i] ?? null;
+            if (!root) {
+                err('hullproof pack: --root needs a folder.\n');
+                return EXIT.badInput;
+            }
+        }
+        else if (more[i].startsWith('-')) {
+            err(`hullproof pack: unknown option ${more[i]}.\n`);
+            return EXIT.badInput;
+        }
+        else
+            targets.push(more[i]);
+    }
+    return packCommand({ action: action ?? '', targets, root, out, err });
+}
+async function proveCmd(rest, err) {
+    const p = parse('prove', rest, ['--out', '--commit', '--allow-run', '--confirm', '--target', '--spec', '--allow-install-scripts', '--gen', '--provider', '--model', '--replay', '--self-test', '--runtime']);
+    if (typeof p === 'string') {
+        err(`hullproof prove: ${p}\n`);
+        return EXIT.badInput;
+    }
+    const get = (f) => p.flags.get(f) ?? null;
+    return proveCommand({ repo: p.repo, out: get('--out'), commit: get('--commit'), allowRun: p.flags.has('--allow-run'), allowInstallScripts: p.flags.has('--allow-install-scripts'), confirm: get('--confirm'), target: get('--target'),
+        specs: (get('--spec') ?? '').split(',').map((x) => x.trim()).filter(Boolean), gen: p.flags.has('--gen'), provider: get('--provider'), model: get('--model'),
+        replay: p.flags.has('--replay'), selfTest: p.flags.has('--self-test'), runtime: get('--runtime'), log: (s) => err(s + '\n') });
+}
+export function main(argv) {
+    const [cmd, ...rest] = argv;
+    const out = (s) => { process.stdout.write(s); };
+    const err = (s) => { process.stderr.write(s); };
+    if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+        out(HELP);
+        return EXIT.ok;
+    }
+    if (cmd === 'version' || cmd === '--version') {
+        out(`${ENGINE_VERSION}\n`);
+        return EXIT.ok;
+    }
+    if (cmd === 'discover')
+        return discoverCmd(rest, out, err);
+    if (cmd === 'map')
+        return mapCmd(rest, out, err);
+    if (cmd === 'scan')
+        return scanCmd(rest, err);
+    if (cmd === 'ci')
+        return ciCmd(rest, out, err);
+    if (cmd === 'hooks')
+        return hooksCmd(rest, err);
+    if (cmd === 'mcp')
+        return mcpCmd(rest, err);
+    if (cmd === 'hunt')
+        return huntCmd(rest, err);
+    if (cmd === 'prove')
+        return proveCmd(rest, err);
+    if (cmd === 'pack')
+        return packCmd(rest, out, err);
+    if (cmd === 'report' || cmd === 'gate')
+        return readCmd(cmd, rest, err);
+    err(`hullproof: unknown command "${cmd}". Run hullproof help.\n`);
+    return EXIT.badInput;
+}
+const invokedAs = () => { try {
+    return pathToFileURL(realpathSync(process.argv[1] ?? '')).href;
+}
+catch {
+    return '';
+} };
+if (import.meta.url === invokedAs())
+    process.exitCode = await main(process.argv.slice(2));