@bugb-technologies/bravos 0.0.0-stage → 1.0.0

package/dist/review.js

@@ -0,0 +1,274 @@
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { hooksDir, templatesDir } from './paths.js';
+import { BravosError } from './types.js';
+// @comment -- "bravos review: the drafts an agent wrote (.guardlink/<kind>-draft.json) rendered as a bravos-branded page people answer in, a loopback-only server that saves each person's answers to .guardlink/<kind>-answers/<name>.json, and a plain-text summary of agreement and disagreement for the agent. Draft text comes from repo files and is untrusted: it travels as JSON and the page renders it with textContent."
+export const REVIEW_SCHEMA = 'bravos.review/v1';
+export const ANSWERS_SCHEMA = 'bravos.review-answers/v1';
+const MAX_BODY = 256 * 1024;
+const IDLE_MS = 30 * 60 * 1000;
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const str = (v, max = 4000) => typeof v === 'string' && v.length <= max;
+// @comment -- "Kind names become file names: lowercase letters and hyphens only."
+export function checkKind(kind) {
+    if (!/^[a-z][a-z-]{0,30}$/.test(kind))
+        throw new BravosError(`review kind must be lowercase letters and hyphens, got '${kind}'`);
+    return kind;
+}
+export const draftPath = (kind) => `.guardlink/${checkKind(kind)}-draft.json`;
+export const answersDir = (kind) => `.guardlink/${checkKind(kind)}-answers`;
+export const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40);
+// @comment -- "Validates a draft's shape (schema, kind, unique ids, known question types, bounded strings) and returns it; anything else is refused with the reason, so a malformed draft never reaches the page."
+export function validateDraft(value, kind) {
+    const bad = (why) => new BravosError(`${draftPath(kind)}: ${why}`);
+    if (!isObject(value))
+        throw bad('is not a JSON object');
+    if (value.schema !== REVIEW_SCHEMA)
+        throw bad(`schema must be ${REVIEW_SCHEMA}`);
+    if (value.kind !== kind)
+        throw bad(`kind must be '${kind}'`);
+    if (!Array.isArray(value.questions) || value.questions.length === 0 || value.questions.length > 300)
+        throw bad('needs 1 to 300 questions');
+    if (value.perspective !== undefined && value.perspective !== 'researcher' && value.perspective !== 'owner')
+        throw bad('perspective must be researcher or owner');
+    const seen = new Set();
+    for (const [n, q] of value.questions.entries()) {
+        if (!isObject(q))
+            throw bad(`question ${n + 1} is not an object`);
+        if (!str(q.id, 80) || !/^[A-Za-z0-9_.-]+$/.test(q.id))
+            throw bad(`question ${n + 1} needs an id of letters, digits, . _ -`);
+        if (seen.has(q.id))
+            throw bad(`duplicate id ${q.id}`);
+        seen.add(q.id);
+        if (!['choice', 'multi', 'item', 'text'].includes(q.type))
+            throw bad(`${q.id}: type must be choice, multi, item or text`);
+        for (const f of ['section', 'title', 'why', 'text', 'draft', 'reason'])
+            if (q[f] !== undefined && !str(q[f]))
+                throw bad(`${q.id}: ${f} must be a string`);
+        if ((q.type === 'choice' || q.type === 'multi') && (!Array.isArray(q.options) || q.options.length < 2 || !q.options.every((o) => isObject(o) && str(o.id, 40) && str(o.label, 400)))) {
+            throw bad(`${q.id}: a ${q.type} needs two or more options with id and label`);
+        }
+        const optionIds = new Set(Array.isArray(q.options) ? q.options.map((o) => o.id) : []);
+        if (q.suggested !== undefined) {
+            const ok = q.type === 'choice' ? typeof q.suggested === 'string' && optionIds.has(q.suggested)
+                : q.type === 'multi' ? Array.isArray(q.suggested) && q.suggested.every((v) => typeof v === 'string' && optionIds.has(v))
+                    : q.type === 'item' ? q.suggested === 'agree' || q.suggested === 'no'
+                        : str(q.suggested);
+            if (!ok)
+                throw bad(`${q.id}: suggested does not fit a ${q.type} question`);
+        }
+        if (q.confidence !== undefined && q.confidence !== 'high' && q.confidence !== 'low')
+            throw bad(`${q.id}: confidence must be high or low`);
+        for (const f of ['mustTouch', 'folded'])
+            if (q[f] !== undefined && typeof q[f] !== 'boolean')
+                throw bad(`${q.id}: ${f} must be true or false`);
+        if (q.type === 'item' && !str(q.text))
+            throw bad(`${q.id}: an item needs its text`);
+        if (q.sources !== undefined && !(Array.isArray(q.sources) && q.sources.every((s) => str(s, 400))))
+            throw bad(`${q.id}: sources must be strings`);
+    }
+    return value;
+}
+// @comment -- "Validates one person's answers against the draft: the answers schema, a non-empty name, and only ids the draft has; returns the cleaned record."
+export function validateAnswers(value, draft) {
+    if (!isObject(value) || value.schema !== ANSWERS_SCHEMA)
+        throw new BravosError(`answers must use schema ${ANSWERS_SCHEMA}`);
+    if (!str(value.by, 80) || !slug(value.by))
+        throw new BravosError('answers need the name of the person giving them');
+    if (!isObject(value.answers))
+        throw new BravosError('answers must be an object keyed by question id');
+    const ids = new Set(draft.questions.map((q) => q.id));
+    const answers = {};
+    for (const [id, a] of Object.entries(value.answers)) {
+        if (!ids.has(id) || !isObject(a))
+            continue;
+        if (!str(a.verdict, 20))
+            continue;
+        const v = a.value;
+        const okValue = str(v) || (Array.isArray(v) && v.length <= 20 && v.every((x) => str(x, 40)));
+        answers[id] = {
+            verdict: a.verdict,
+            ...(okValue ? { value: v } : {}),
+            ...(str(a.choice, 40) ? { choice: a.choice } : {}),
+            ...(str(a.text) ? { text: a.text } : {}),
+            ...(str(a.comment) ? { comment: a.comment } : {}),
+        };
+    }
+    return { schema: ANSWERS_SCHEMA, kind: draft.kind, by: value.by.trim(), date: str(value.date, 40) ? value.date : new Date().toISOString().slice(0, 10), answers };
+}
+// A must-touch decision counts only when a person acted on it; accepting untouched does not.
+const DECIDED = new Set(['chosen', 'edited', 'no', 'choice', 'change', 'agree']);
+// @comment -- "Lists the must-touch decisions an answers record leaves without a deliberate answer; the server refuses such a record, so Confirm cannot rubber-stamp them."
+export function missingDecisions(draft, a) {
+    return draft.questions.filter((q) => q.mustTouch && !DECIDED.has(a.answers[q.id]?.verdict ?? '')).map((q) => q.id);
+}
+export function readDraft(root, kind) {
+    const abs = join(root, draftPath(kind));
+    if (!existsSync(abs))
+        throw new BravosError(`${draftPath(kind)} not found: the agent writes it first (bravos-context step 3)`);
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(abs, 'utf8'));
+    }
+    catch {
+        throw new BravosError(`${draftPath(kind)} is not valid JSON`);
+    }
+    return validateDraft(parsed, kind);
+}
+// @comment -- "Every saved answers file for a kind, each validated against the draft; unreadable or malformed files are skipped and named."
+export function readAllAnswers(root, draft) {
+    const dir = join(root, answersDir(draft.kind));
+    const files = [];
+    const skipped = [];
+    if (!existsSync(dir))
+        return { files, skipped };
+    for (const f of readdirSync(dir).filter((n) => n.endsWith('.json')).sort()) {
+        try {
+            files.push(validateAnswers(JSON.parse(readFileSync(join(dir, f), 'utf8')), draft));
+        }
+        catch {
+            skipped.push(f);
+        }
+    }
+    return { files, skipped };
+}
+/** The brand art for the page header, from the hook's own constants (one source for banner and page). */
+async function brandArt() {
+    const lib = await import(pathToFileURL(join(hooksDir(), 'lib', 'briefing.mjs')).href);
+    return { mascot: lib.MASCOT, logo: lib.LOGO };
+}
+// @comment -- "Renders the self-contained review page: the template with the draft, mode and brand art embedded as JSON in a non-executing script tag, every '<' escaped so draft text cannot close the tag."
+export async function renderReview(draft, mode) {
+    const template = readFileSync(join(templatesDir(), 'review', 'review.html'), 'utf8');
+    const art = await brandArt();
+    const heading = draft.kind !== 'intent' ? `bravos asks: ${draft.kind}` : draft.perspective === 'owner' ? 'What does this product intend?' : `How should bravos judge ${draft.repo ?? 'this project'}?`;
+    const data = JSON.stringify({ draft, mode, heading, ...art }).replace(/</g, '\\u003c').replace(/[\u2028\u2029]/g, (c) => `\\u${c.charCodeAt(0).toString(16)}`);
+    const page = template.replace('__BRAVOS_DATA__', () => data);
+    // On claude.ai the runtime bridge supplies the shared database, so the page drops its own CSP there.
+    return mode.kind === 'artifact' ? page.replace(/<meta http-equiv="Content-Security-Policy"[^>]*>\n?/, '') : page;
+}
+/** What an answer amounts to, for comparing people: the suggestion when accepted, otherwise the value given. */
+function effective(q, a) {
+    if (a.verdict === 'no')
+        return 'no';
+    const legacy = a.verdict === 'choice' ? a.choice : a.verdict === 'change' ? a.text : undefined;
+    const asIs = a.verdict === 'accepted' || a.verdict === 'agree' ? (q.suggested ?? 'agree') : undefined;
+    const v = a.value ?? legacy ?? asIs ?? a.verdict;
+    return Array.isArray(v) ? [...v].sort().join(', ') : String(v);
+}
+// @comment -- "Plain-text summary for the agent, most important first: disagreements, edits and rejections, the must-touch decisions with who made them, unanswered questions, then one line per group of suggestions accepted as is, with names; no model involved."
+export function summarize(draft, files, skipped = []) {
+    const out = [];
+    out.push(`bravos review ${draft.kind}${draft.perspective ? ` (${draft.perspective})` : ''}: ${files.length} ${files.length === 1 ? 'person' : 'people'} answered${files.length ? ` (${files.map((f) => `${f.by}, ${f.date}`).join('; ')})` : ''}`);
+    if (skipped.length)
+        out.push(`skipped unreadable answer files: ${skipped.join(', ')}`);
+    const groups = { DISAGREE: [], EDITED: [], DECIDED: [], 'NO ANSWER': [] };
+    const accepted = {};
+    let acceptedCount = 0;
+    for (const q of draft.questions) {
+        const rows = files.map((f) => ({ by: f.by, a: f.answers[q.id] })).filter((r) => !!r.a);
+        const values = new Set(rows.map((r) => effective(q, r.a)));
+        const head = `${q.id}${q.title ? ` — ${q.title}` : ''}`;
+        const sugg = q.suggested !== undefined ? (Array.isArray(q.suggested) ? q.suggested.join(', ') : q.suggested) : (q.text ?? q.draft ?? '—');
+        const block = [head, `  bravos suggested: ${sugg}`, ...rows.map((r) => `  ${r.by}: ${r.a.verdict} → ${effective(q, r.a)}${r.a.comment ? ` (${r.a.comment})` : ''}`)];
+        if (rows.length === 0)
+            groups['NO ANSWER'].push(block);
+        else if (values.size > 1)
+            groups.DISAGREE.push(block);
+        else if (rows.some((r) => ['edited', 'no', 'change'].includes(r.a.verdict)))
+            groups.EDITED.push(block);
+        else if (q.mustTouch || rows.some((r) => r.a.verdict === 'chosen' || r.a.verdict === 'choice'))
+            groups.DECIDED.push(block);
+        else {
+            acceptedCount++;
+            (accepted[rows.map((r) => r.by).join(', ')] ??= []).push(q.id);
+        }
+    }
+    for (const k of ['DISAGREE', 'EDITED', 'DECIDED', 'NO ANSWER']) {
+        for (const b of groups[k])
+            out.push('', `[${k}] ${b[0]}`, ...b.slice(1));
+    }
+    for (const [who, ids] of Object.entries(accepted))
+        out.push('', `[ACCEPTED as suggested by ${who}] ${ids.join(', ')}`);
+    out.push('', `totals: ${groups.DISAGREE.length} disagreements, ${groups.EDITED.length} edited or rejected, ${groups.DECIDED.length} decisions made, ${acceptedCount} accepted as suggested, ${groups['NO ANSWER'].length} unanswered of ${draft.questions.length}`);
+    return out.join('\n');
+}
+// @comment -- "The loopback review server: GET / (the page), GET /answers (everyone's answers), POST /answers (one person's answers, validated, written as .guardlink/<kind>-answers/<slug>.json), POST /done (stop). Every request needs the token; the Host must be the loopback address it listens on; bodies over 256 KB are refused; it stops after 30 minutes idle."
+export function startReviewServer(root, draft, page, token, port = 0) {
+    let idle;
+    const server = createServer((req, res) => {
+        clearTimeout(idle);
+        idle = setTimeout(() => server.close(), IDLE_MS);
+        const send = (code, body, type = 'text/plain; charset=utf-8') => {
+            res.writeHead(code, { 'content-type': type, 'cache-control': 'no-store', 'x-content-type-options': 'nosniff' });
+            res.end(body);
+        };
+        const addr = server.address();
+        const p = typeof addr === 'object' && addr ? addr.port : 0;
+        if (req.headers.host !== `127.0.0.1:${p}` && req.headers.host !== `localhost:${p}`)
+            return send(403, 'wrong host');
+        const url = new URL(req.url ?? '/', `http://127.0.0.1:${p}`);
+        if (url.searchParams.get('t') !== token)
+            return send(403, 'wrong token');
+        if (req.method === 'GET' && url.pathname === '/')
+            return send(200, page, 'text/html; charset=utf-8');
+        if (req.method === 'GET' && url.pathname === '/answers')
+            return send(200, JSON.stringify(readAllAnswers(root, draft).files), 'application/json');
+        if (req.method === 'POST' && (url.pathname === '/answers' || url.pathname === '/done')) {
+            let size = 0;
+            const chunks = [];
+            req.on('data', (c) => {
+                size += c.length;
+                if (size > MAX_BODY) {
+                    send(413, 'too large');
+                    req.destroy();
+                }
+                else
+                    chunks.push(c);
+            });
+            req.on('end', () => {
+                if (size > MAX_BODY)
+                    return;
+                if (url.pathname === '/done') {
+                    send(200, 'ok');
+                    setTimeout(() => server.close(), 50);
+                    return;
+                }
+                try {
+                    const a = validateAnswers(JSON.parse(Buffer.concat(chunks).toString('utf8')), draft);
+                    const missing = missingDecisions(draft, a);
+                    if (missing.length)
+                        return send(400, `these decisions still need your call: ${missing.join(', ')}`);
+                    const rel = `${answersDir(draft.kind)}/${slug(a.by)}.json`;
+                    mkdirSync(dirname(join(root, rel)), { recursive: true });
+                    writeFileSync(join(root, rel), JSON.stringify(a, null, 2) + '\n');
+                    send(200, JSON.stringify({ saved: rel }), 'application/json');
+                }
+                catch (e) {
+                    send(400, e instanceof Error ? e.message : 'bad answers');
+                }
+            });
+            return;
+        }
+        send(404, 'not found');
+    });
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, '127.0.0.1', () => {
+            idle = setTimeout(() => server.close(), IDLE_MS);
+            const addr = server.address();
+            resolve({ server, port: typeof addr === 'object' && addr ? addr.port : port });
+        });
+    });
+}
+export const newToken = () => randomBytes(16).toString('hex');
+// @comment -- "Writes the rendered page for file mode (no server) to .bravos/review/<kind>.html and returns its path."
+export function writePage(root, kind, page) {
+    const rel = `.bravos/review/${checkKind(kind)}.html`;
+    mkdirSync(dirname(join(root, rel)), { recursive: true });
+    writeFileSync(join(root, rel), page);
+    return rel;
+}

package/dist/setup.js

@@ -0,0 +1,121 @@
+// @comment -- "bravos setup: puts the binaries bravos drives onto this machine. The analyzer and the code graph are licensed bundles fetched through the account portal (artifacts.ts); guardlink and cxg are free CLIs installed with their own package managers. --check reports without changing anything, --dry-run says what would run, and nothing is fetched or installed without a licence for it. Also the SAST runner: `bravos sast run` invokes the staged analyzer with the argv the Python CLI used and writes the run folder the briefing and `bravos sast` read."
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { bundleEnvironment, hostTarget, install, missingPaths, staged, VERSIONS } from './artifacts.js';
+import { graphBin } from './codegraph.js';
+import { whichBin } from './guardlink.js';
+import { findAnalyzer } from './graphbin.js';
+import { licenceLib, requireFeature } from './licence.js';
+import { BravosError } from './types.js';
+import { CXG_VERSION, GUARDLINK_VERSION } from './versions.js';
+// @comment -- "What is here and what setup would do, read-only: for each piece its path when present, the pinned version, whether the licence covers it, and the one action."
+export async function plan(env) {
+    const L = await licenceLib();
+    const v = L.status(env);
+    const sast = L.entitled(v, 'sast');
+    const graph = L.entitled(v, 'codegraph');
+    const t = hostTarget();
+    const items = [
+        { id: 'analyzer', present: staged(env, 'analyzer') ?? findAnalyzer(env), wanted: VERSIONS.analyzer, licensed: sast, action: !t ? 'no build for this platform' : sast ? 'fetch, verify and stage the analyzer bundle' : 'on the Team plan: bravos account activate' },
+        { id: 'codegraph', present: staged(env, 'codegraph') ?? graphBin('codegraph-build', env), wanted: VERSIONS.codegraph, licensed: graph, action: !t ? 'no build for this platform' : graph ? 'fetch, verify and stage codegraph-build and codegraph-mcp' : 'on the Team plan: bravos account activate' },
+        { id: 'guardlink', present: whichBin('guardlink', env), wanted: GUARDLINK_VERSION, licensed: null, action: `npm install -g guardlink@${GUARDLINK_VERSION}` },
+        { id: 'cxg', present: whichBin('cxg', env), wanted: CXG_VERSION, licensed: null, action: `cargo install cert-x-gen@${CXG_VERSION} --force && cxg pentest update` },
+    ];
+    return { items, licence: v };
+}
+export const formatPlan = (items) => items.map((i) => `${i.present ? '✔' : '✘'} ${i.id.padEnd(10)} ${i.present ? i.present : `absent — ${i.action}`}${i.present && i.licensed === false ? ' (licence does not cover it now)' : ''}`);
+// @comment -- "The setup itself. Default: the two licensed bundles for a licensed machine; --tools adds guardlink and cxg; --analyzer/--codegraph narrow it. Each licensed piece passes the gate before the first request. --dry-run prints the actions; -y is required for the package-manager installs because they run other people's installers."
+export async function runSetup(env, opts, io) {
+    const lines = [];
+    const { items } = await plan(env);
+    if (opts.check) {
+        lines.push(...formatPlan(items));
+        return lines;
+    }
+    const pick = opts.analyzer || opts.codegraph || opts.tools ? { analyzer: !!opts.analyzer, codegraph: !!opts.codegraph, tools: !!opts.tools } : { analyzer: true, codegraph: true, tools: false };
+    const bundles = [...(pick.codegraph ? ['codegraph'] : []), ...(pick.analyzer ? ['analyzer'] : [])];
+    for (const kind of bundles) {
+        const what = `bravos setup --${kind}`;
+        await requireFeature(env, kind === 'analyzer' ? 'sast' : 'codegraph', what);
+        const have = staged(env, kind);
+        if (have && !opts.yes) {
+            lines.push(`${kind}: already staged at ${have} (add -y to fetch ${VERSIONS[kind]} again)`);
+            continue;
+        }
+        if (opts.dryRun) {
+            lines.push(`dry-run: would fetch ${kind} ${VERSIONS[kind]} for ${hostTarget() ?? 'this platform'} through the account portal, verify its signature and stage it under $BRAVOS_HOME/${kind}/`);
+            continue;
+        }
+        const r = await install(kind, { env, fetch: io.fetch, keys: io.keys, echo: io.echo });
+        const missing = missingPaths(kind, r.dir);
+        lines.push(`${kind}: ${r.version} staged at ${r.dir}${missing.length ? ` — missing ${missing.join(', ')}` : ''}`);
+        lines.push(...selfTest(kind, r.dir, env));
+    }
+    if (pick.tools) {
+        for (const i of items.filter((x) => x.id === 'guardlink' || x.id === 'cxg')) {
+            if (i.present) {
+                lines.push(`${i.id}: present at ${i.present}`);
+                continue;
+            }
+            if (opts.dryRun || !opts.yes) {
+                lines.push(`${i.id}: absent — ${opts.dryRun ? 'would run' : 'run'} ${i.action}${opts.yes ? '' : ' (add -y to run it here)'}`);
+                continue;
+            }
+            lines.push(`${i.id}: running ${i.action}`);
+            for (const cmd of i.action.split(' && ')) {
+                const [bin, ...args] = cmd.split(' ');
+                const r = spawnSync(bin, args, { env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 20 * 60 * 1000 });
+                if (r.status !== 0)
+                    throw new BravosError(`${cmd} failed (exit ${r.status}): ${(r.stderr || r.stdout || '').trim().split('\n').slice(-3).join(' ')}`);
+            }
+            lines.push(`${i.id}: installed`);
+        }
+    }
+    return lines;
+}
+// @comment -- "A staged bundle proves it runs: codegraph-build --ladder, bravos-cli --version, each under the bundle's own environment. A bundle that verifies but does not run is reported, not hidden."
+export function selfTest(kind, dir, env) {
+    const out = [];
+    const bins = kind === 'analyzer' ? [['bravos-cli', ['--version']]] : [['codegraph-build', ['--ladder']], ['codegraph-mcp', ['--help']]];
+    for (const [name, args] of bins) {
+        const r = spawnSync(join(dir, name), args, { env: bundleEnvironment(dir, env), encoding: 'utf8', timeout: 60000, stdio: ['ignore', 'pipe', 'pipe'] });
+        const ok = r.status === 0 || (name === 'codegraph-mcp' && (r.stdout + r.stderr).includes('usage'));
+        out.push(`  ${ok ? '✔' : '✘'} ${name}${ok ? ` ${(r.stdout || r.stderr).trim().split('\n')[0].slice(0, 80)}` : ` did not run: ${(r.stderr || r.error?.message || '').trim().split('\n')[0]}`}`);
+    }
+    return out;
+}
+// @comment -- "Runs the analyzer the way the Python adapter did: bravos-cli analyze ROOT --ci --fail-on never --allow-incomplete-analysis --codegraph <reuse when a graph store exists> --scip off -f json,sarif -o .bravos/sast/<run>/report, under the bundle's environment, then writes meta.json (sha, exit, at) so the briefing's SAST line and bravos sast candidates read it. The exit code is a health signal; findings are read from the report."
+export async function runSast(root, env, opts = {}) {
+    await requireFeature(env, 'sast', 'bravos sast run');
+    const dir = staged(env, 'analyzer');
+    const bin = dir ? join(dir, 'bravos-cli') : findAnalyzer(env);
+    if (!bin)
+        throw new BravosError('bravos-cli is not installed: bravos setup --analyzer fetches it');
+    const base = join(root, '.bravos', 'sast');
+    mkdirSync(base, { recursive: true });
+    if (!existsSync(join(base, '.gitignore')))
+        writeFileSync(join(base, '.gitignore'), '*\n');
+    const run = new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d+Z$/, '').replace('T', '-');
+    const runDir = join(base, run);
+    mkdirSync(runDir, { recursive: true });
+    const sha = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf8', timeout: 5000 }).stdout?.trim() || null;
+    const codegraph = opts.codegraph ?? (graphBin('codegraph-mcp', env) ? 'reuse' : 'off');
+    const argv = ['analyze', root, '--ci', '--fail-on', 'never', '--allow-incomplete-analysis', '--codegraph', codegraph, '--scip', opts.scip ?? 'off', '-f', 'json,sarif', '-o', join(runDir, 'report')];
+    if (opts.scope?.length)
+        argv.push('--scope', opts.scope.join(','));
+    if (opts.exclude?.length)
+        argv.push('--exclude', opts.exclude.join(','));
+    if (opts.minSeverity)
+        argv.push('--min-severity', opts.minSeverity);
+    if (opts.timeoutS)
+        argv.push('--timeout', String(Math.max(1, opts.timeoutS - 1)));
+    const runEnv = dir ? bundleEnvironment(dir, env) : env;
+    const r = spawnSync(bin, argv, { cwd: root, env: runEnv, encoding: 'utf8', timeout: (opts.timeoutS ?? 1800) * 1000, maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] });
+    writeFileSync(join(runDir, 'meta.json'), JSON.stringify({ sha, base: null, scope: opts.scope?.length ? opts.scope.join(',') : 'all', exit: r.status, at: new Date().toISOString(), analyzer: bin, codegraph }, null, 2) + '\n');
+    const lines = [`SAST run ${run}: bravos-cli exited ${r.status ?? 'by signal'} (0 clean at the level, 1 findings, 3 licence refused or analysis failed, 4 a stage failed)`, `  report: ${join(runDir, 'report.json')}`];
+    if (r.status !== 0 && r.status !== 1)
+        lines.push(`  ${(r.stderr || r.stdout || '').trim().split('\n').slice(-3).join('\n  ')}`);
+    lines.push('  next: bravos sast candidates');
+    return { dir: runDir, exit: r.status, lines };
+}

package/dist/skills.js

@@ -0,0 +1,81 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { skillsDir } from './paths.js';
+// @comment -- "Marker bravos inserts into every SKILL.md it renders, so an unlocked skill can still be recognised as bravos-managed."
+export const MARKER = '<!-- bravos:generated -->';
+// @comment -- "Repo-relative skills root for a harness: .claude/skills for Claude Code, .agents/skills for Codex and other agents."
+export function skillsRoot(harness) {
+    return harness === 'claude' ? '.claude/skills' : '.agents/skills';
+}
+function walk(dir, prefix = '') {
+    const out = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory())
+            out.push(...walk(join(dir, entry.name), rel));
+        else if (entry.isFile())
+            out.push(rel);
+    }
+    return out;
+}
+/** Every bundled skill folder with all of its files. A missing directory yields []. */
+// @comment -- "Reads every bundled skill folder and its files from the package; a missing directory yields []."
+export function listBundledSkills(dir = skillsDir()) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((n) => statSync(join(dir, n)).isDirectory())
+        .sort()
+        .map((name) => ({
+        name,
+        files: walk(join(dir, name))
+            .sort()
+            .map((rel) => ({ rel, content: readFileSync(join(dir, name, rel)) })),
+    }));
+}
+// @comment -- "Inserts the generated marker after the frontmatter (or at line 1) of a skill's SKILL.md only; sibling .md data files (operator-guidance.md, loop.md) are copied without it, since the skills that read them would carry the marker into what they write."
+function withMarker(content, rel) {
+    if (rel !== 'SKILL.md')
+        return content;
+    const lines = content.split('\n');
+    let at = 0;
+    if (lines[0]?.trim() === '---') {
+        const close = lines.findIndex((l, i) => i > 0 && l.trim() === '---');
+        if (close !== -1)
+            at = close + 1;
+    }
+    lines.splice(at, 0, MARKER);
+    return lines.join('\n');
+}
+/** Insert the generated marker into SKILL.md after the frontmatter (or at line 1) and substitute placeholders. */
+// @comment -- "Renders a bundled skill file for one harness: inserts the generated marker into SKILL.md (rel is the file's path inside the skill folder) and substitutes {{SKILL_DIR}} and {{SKILLS_ROOT}} in every .md file."
+export function renderSkillFile(content, harness, name, rel = 'SKILL.md') {
+    const root = skillsRoot(harness);
+    return withMarker(content, rel)
+        .split('{{SKILL_DIR}}')
+        .join(`${root}/${name}`)
+        .split('{{SKILLS_ROOT}}')
+        .join(root);
+}
+/** Render a bundled skill file for the Claude Code / Codex plugin build instead of a repo install. */
+// @comment -- "Plugin render: {{SKILL_DIR}} becomes ${CLAUDE_SKILL_DIR}, which Claude Code substitutes inside SKILL.md; {{SKILLS_ROOT}}/bravos* points into the plugin, any other {{SKILLS_ROOT}} (guardlink's generated skills) stays at the repo's .claude/skills."
+export function renderPluginSkillFile(content, rel = 'SKILL.md') {
+    return withMarker(content, rel)
+        .split('{{SKILL_DIR}}')
+        .join('${CLAUDE_SKILL_DIR}')
+        .split('{{SKILLS_ROOT}}/bravos')
+        .join('${CLAUDE_PLUGIN_ROOT}/skills/bravos')
+        .split('{{SKILLS_ROOT}}')
+        .join('.claude/skills');
+}
+// @comment -- "User-level render (bravos init --global): bravos's own paths become absolute under the home folder (skills in ~/.claude/skills, hook scripts in ~/.bravos/hooks), while {{SKILLS_ROOT}} for guardlink's generated skills stays at the repo's .claude/skills."
+export function renderGlobalSkillFile(home) {
+    return (content, _harness, name, rel = 'SKILL.md') => withMarker(content, rel)
+        .split('{{SKILL_DIR}}')
+        .join(`${home}/.claude/skills/${name}`)
+        .split('{{SKILLS_ROOT}}/bravos')
+        .join(`${home}/.claude/skills/bravos`)
+        .split('{{SKILLS_ROOT}}')
+        .join('.claude/skills')
+        .replace(/node \.bravos\/hooks\/([\w.-]+)/g, (_m, file) => `node "${home}/.bravos/hooks/${file}"`);
+}

package/dist/types.js

@@ -0,0 +1,9 @@
+// @comment -- "Expected, user-facing failure (bad config file, failed guardlink init) carrying the CLI exit code; anything else is a bug."
+export class BravosError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = 'BravosError';
+    }
+}