@bugb-technologies/bravos 0.0.0-stage → 1.0.0

package/dist/report/export.js

@@ -0,0 +1,105 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { templatesDir, version } from '../paths.js';
+import { BravosError } from '../types.js';
+import { lib } from '../watch.js';
+import { checkReport } from './check.js';
+import { readEvidence, readMeta, reportDir, writeMeta } from './data.js';
+import { renderReportHtml, renderReportText } from './markdown.js';
+import { printPdf } from './pdf.js';
+// @comment -- "bravos report export: renders .bravos/reports/<id>/report.md, after it passes bravos report check, to md, txt, html and pdf beside it, and records each in meta.json. HTML is the branded self-contained page (no script, strict CSP, no external request); PDF prints that page with an installed Chromium-family browser."
+export const FORMATS = ['md', 'txt', 'html', 'pdf'];
+const escHtml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+export function readReportMd(root, id) {
+    const file = join(reportDir(root, id), 'report.md');
+    if (!existsSync(file))
+        throw new BravosError(`no report.md in .bravos/reports/${id}: write it first (/bravos-report)`);
+    return readFileSync(file, 'utf8');
+}
+// @comment -- "Runs the check on a report and stores its verdict and finding counts in meta.json, so bravos watch can show them without re-reading the markdown."
+export function checkAndRecord(root, id) {
+    const bundle = readEvidence(root, id);
+    const result = checkReport(readReportMd(root, id), bundle, bundle.kind);
+    const meta = readMeta(root, id) ?? { schema: 'bravos.report-meta/v1', id, kind: bundle.kind, createdAt: bundle.generatedAt, sha: bundle.git.sha, title: null, check: null, exports: {} };
+    const byLevel = {};
+    const bySeverity = {};
+    for (const f of result.findings) {
+        if (f.level)
+            byLevel[f.level] = (byLevel[f.level] ?? 0) + 1;
+        if (f.severity)
+            bySeverity[f.severity] = (bySeverity[f.severity] ?? 0) + 1;
+    }
+    meta.title = result.title;
+    meta.check = {
+        ok: result.ok,
+        errors: result.errors.length,
+        warnings: result.warnings.length,
+        at: new Date().toISOString(),
+        findings: result.findings.length,
+        byLevel,
+        bySeverity,
+        index: result.findings.map((f) => ({ id: f.id, title: f.title, level: f.level, severity: f.severity, priority: f.priority })),
+    };
+    writeMeta(root, meta);
+    return { result, bundle, meta };
+}
+// @comment -- "The branded HTML page for a report: the rendered body, a contents list from the sections and findings, the mascot, and a header and footer naming the repository, commit, kind, check verdict and bravos version."
+export async function renderHtmlPage(md, bundle, check) {
+    const template = readFileSync(join(templatesDir(), 'report', 'report.html'), 'utf8');
+    const { html, toc } = renderReportHtml(md);
+    const briefing = await lib('briefing.mjs');
+    const mascot = briefing.MASCOT ?? [];
+    const title = check?.title ?? md.match(/^#\s+(.+)$/m)?.[1] ?? `${bundle.repo} report`;
+    const meta = [
+        `<b>${escHtml(title)}</b>`,
+        `${escHtml(bundle.repo)} · ${escHtml(bundle.kind)} · commit ${escHtml(bundle.git.short ?? '?')}${bundle.git.branch ? ` (${escHtml(bundle.git.branch)})` : ''}`,
+        `evidence gathered ${escHtml(bundle.generatedAt.slice(0, 16).replace('T', ' '))} UTC · guardlink ${escHtml(bundle.tools.guardlink ?? '?')} · ${escHtml(bundle.tools.cxg ?? 'cxg ?')}`,
+    ].join('<br>');
+    const tocHtml = toc.map((t) => `<a class="l${t.level}" href="#${escHtml(t.id)}">${escHtml(t.text)}</a>`).join('');
+    const footer = `Written by bravos ${escHtml(version())} from report.md and evidence.json (${escHtml(bundle.id)}). ${check ? (check.ok ? 'bravos report check: passes.' : `bravos report check: ${check.errors.length} problem${check.errors.length === 1 ? '' : 's'}.`) : ''} This report quotes evidence from the assessment; share it deliberately.`;
+    return template
+        .replace('__TITLE__', () => escHtml(title))
+        .replace('__ART__', () => escHtml(mascot.join('\n')))
+        .replace('__META__', () => meta)
+        .replace('__TOC__', () => tocHtml)
+        .replace('__BODY__', () => html)
+        .replace('__FOOTER__', () => footer);
+}
+// @comment -- "Writes the requested formats beside report.md. Refuses while the report fails its check unless force is set; pdf also writes the html it prints; a missing browser skips pdf with the reason and keeps the rest."
+export async function exportReport(root, id, formats, opts = {}) {
+    const { result, bundle, meta } = checkAndRecord(root, id);
+    if (!result.ok && !opts.force) {
+        throw new BravosError(`report ${id} fails bravos report check with ${result.errors.length} problem${result.errors.length === 1 ? '' : 's'}; fix them (bravos report check ${id}) or pass --force`);
+    }
+    const dir = reportDir(root, id);
+    const md = readReportMd(root, id);
+    const written = [];
+    const skipped = [];
+    const now = new Date().toISOString();
+    const want = new Set(formats);
+    if (want.has('md'))
+        written.push({ format: 'md', path: join(dir, 'report.md') });
+    if (want.has('txt')) {
+        const head = `${bundle.repo} · ${bundle.kind} · commit ${bundle.git.short ?? '?'} · bravos ${version()}`;
+        writeFileSync(join(dir, 'report.txt'), `${head}\n\n${renderReportText(md, 80)}`);
+        written.push({ format: 'txt', path: join(dir, 'report.txt') });
+    }
+    if (want.has('html') || want.has('pdf')) {
+        writeFileSync(join(dir, 'report.html'), await renderHtmlPage(md, bundle, result));
+        if (want.has('html'))
+            written.push({ format: 'html', path: join(dir, 'report.html') });
+    }
+    if (want.has('pdf')) {
+        const r = printPdf(join(dir, 'report.html'), join(dir, 'report.pdf'), opts.env ?? process.env);
+        if (r.ok)
+            written.push({ format: 'pdf', path: join(dir, 'report.pdf') });
+        else
+            skipped.push({ format: 'pdf', reason: r.reason });
+        if (!want.has('html'))
+            written.push({ format: 'html', path: join(dir, 'report.html') });
+    }
+    for (const w of written)
+        meta.exports[w.format] = { path: w.path, at: now };
+    writeMeta(root, meta);
+    return { written, skipped, check: result };
+}

package/dist/report/markdown.js

@@ -0,0 +1,310 @@
+import { LEVEL_LABEL } from './data.js';
+// @comment -- "Renders a bravos report's markdown to HTML and to plain text, with no dependency. The report is model-written, so it is untrusted: every character is HTML-escaped first and only the constructs below become markup again; raw HTML shows as text; links keep only http(s), mailto, in-page # and relative targets. Ported from guardlink's dashboard renderer, plus heading anchors, field lines, evidence and severity chips, and a section per finding."
+const escHtml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+function safeHref(raw) {
+    const href = raw.trim();
+    if (/^(https?:|mailto:)/i.test(href) || href.startsWith('#') || /^[./\w-][^:]*$/.test(href))
+        return href;
+    return null;
+}
+const LEVEL_CLASS = { reproduced: 'lv-repro', held: 'lv-held', 'code-review': 'lv-review', suspected: 'lv-suspect' };
+const LEVEL_TAG = { reproduced: 'REPRODUCED', held: 'HELD', 'code-review': 'CODE REVIEW', suspected: 'SUSPECTED' };
+/** Inline constructs over ESCAPED text; code spans are cut out first so nothing inside them changes. */
+function inline(text) {
+    const codes = [];
+    let s = text.replace(//g, '').replace(/`([^`]+)`/g, (_, c) => {
+        codes.push(c);
+        return `${codes.length - 1}`;
+    });
+    s = escHtml(s);
+    s = s.replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (_w, label, url) => {
+        const href = safeHref(url.replace(/&amp;/g, '&'));
+        return href ? `<a href="${escHtml(href)}"${/^https?:/i.test(href) ? ' rel="noopener"' : ''}>${label}</a>` : label;
+    });
+    s = s.replace(/\*\*([^*]+)\*\*|__([^_]+)__/g, (_, a, b) => `<strong>${a ?? b}</strong>`);
+    s = s.replace(/(^|[^*\w])\*([^*\s][^*]*)\*(?!\w)|(^|[^_\w])_([^_\s][^_]*)_(?!\w)/g, (_, p1, a, p3, b) => `${p1 ?? p3 ?? ''}<em>${a ?? b}</em>`);
+    for (const [k, label] of Object.entries(LEVEL_LABEL)) {
+        s = s.replace(new RegExp(`(^|[\\s(>])(${label})`, 'gi'), (_, pre, l) => `${pre}<span class="chip ${LEVEL_CLASS[k]}">${l}</span>`);
+    }
+    // Evidence ids become links into the appendix index when the page has one.
+    s = s.replace(/(?<![\w:-])((?:[a-z0-9][a-z0-9._-]{0,40}:)?(?:RUN-\d+(?:\/[FXHN]-\d+)?|(?:EXP|SAST|CTL|BND|ACC|EDGE|UNR)-\d+|LED-[a-f0-9]{8}))\b/g, '<span class="eid">$1</span>');
+    return s.replace(/(\d+)/g, (_, i) => `<code>${escHtml(codes[Number(i)])}</code>`);
+}
+const isTableSep = (l) => /^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)*\|?\s*$/.test(l);
+const cells = (l) => l.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim());
+const listItem = /^(\s*)([-*+]|\d+[.)])\s+(.*)$/;
+const fieldLine = /^\s*\*\*[^*]{1,40}?(?::\*\*|\*\*:)/;
+const slug = (s) => s.toLowerCase().replace(/<[^>]+>/g, '').replace(/&[a-z]+;/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 60);
+// @comment -- "Markdown to HTML for a report body: headings with anchors (F-nn headings anchor as f-nn), each **Label:** line as its own field paragraph, severity values as chips, and every finding wrapped in <section class=\"finding\"> so print keeps it together."
+export function renderReportHtml(src) {
+    const lines = src.replace(/\r\n?/g, '\n').split('\n');
+    const out = [];
+    const toc = [];
+    const used = new Set();
+    let i = 0;
+    let inFinding = false;
+    const para = [];
+    const flush = () => {
+        if (para.length) {
+            out.push(`<p>${inline(para.join(' '))}</p>`);
+            para.length = 0;
+        }
+    };
+    const list = () => {
+        const base = (listItem.exec(lines[i])[1] ?? '').length;
+        const ordered = /\d/.test(listItem.exec(lines[i])[2]);
+        const items = [];
+        while (i < lines.length) {
+            const m = listItem.exec(lines[i]);
+            if (!m || m[1].length < base)
+                break;
+            if (m[1].length > base) {
+                items[items.length - 1] = (items[items.length - 1] ?? '') + list();
+                continue;
+            }
+            let body = inline(m[3]);
+            i++;
+            while (i < lines.length && lines[i].trim() && !listItem.test(lines[i]) && /^\s+/.test(lines[i])) {
+                body += ` ${inline(lines[i].trim())}`;
+                i++;
+            }
+            items.push(body);
+        }
+        return `<${ordered ? 'ol' : 'ul'}>${items.map((b) => `<li>${b}</li>`).join('')}</${ordered ? 'ol' : 'ul'}>`;
+    };
+    while (i < lines.length) {
+        const line = lines[i];
+        const fence = /^\s*(```|~~~)\s*([\w-]*)\s*$/.exec(line);
+        if (fence) {
+            flush();
+            const body = [];
+            i++;
+            while (i < lines.length && !lines[i].trim().startsWith(fence[1]))
+                body.push(lines[i++]);
+            i++;
+            out.push(`<pre${fence[2] ? ` data-lang="${escHtml(fence[2])}"` : ''}><code>${escHtml(body.join('\n'))}</code></pre>`);
+            continue;
+        }
+        if (!line.trim()) {
+            flush();
+            i++;
+            continue;
+        }
+        const h = /^(#{1,6})\s+(.*?)\s*#*\s*$/.exec(line);
+        if (h) {
+            flush();
+            const level = h[1].length;
+            const f = /^(F-\d{2,3})\b/.exec(h[2]);
+            if (inFinding && (level <= 3 || f)) {
+                out.push('</section>');
+                inFinding = false;
+            }
+            let id = f ? f[1].toLowerCase() : slug(h[2]) || 'section';
+            while (used.has(id))
+                id += '-x';
+            used.add(id);
+            if (f) {
+                out.push('<section class="finding">');
+                inFinding = true;
+            }
+            out.push(`<h${level} id="${id}">${inline(h[2])}</h${level}>`);
+            if (level === 2 || f)
+                toc.push({ id, text: h[2].replace(/[*_`]/g, ''), level: f ? 3 : level });
+            i++;
+            continue;
+        }
+        if (/^\s*([-*_])(\s*\1){2,}\s*$/.test(line)) {
+            flush();
+            out.push('<hr>');
+            i++;
+            continue;
+        }
+        if (/^\s*>/.test(line)) {
+            flush();
+            const q = [];
+            while (i < lines.length && /^\s*>/.test(lines[i]))
+                q.push(lines[i++].replace(/^\s*>\s?/, ''));
+            out.push(`<blockquote>${renderReportHtml(q.join('\n')).html}</blockquote>`);
+            continue;
+        }
+        if (line.includes('|') && i + 1 < lines.length && isTableSep(lines[i + 1])) {
+            flush();
+            const head = cells(line);
+            i += 2;
+            const rows = [];
+            while (i < lines.length && lines[i].includes('|') && lines[i].trim())
+                rows.push(cells(lines[i++]));
+            out.push(`<div class="table-wrap"><table><thead><tr>${head.map((c) => `<th>${inline(c)}</th>`).join('')}</tr></thead><tbody>${rows.map((r) => `<tr>${head.map((_, k) => `<td>${inline(r[k] ?? '')}</td>`).join('')}</tr>`).join('')}</tbody></table></div>`);
+            continue;
+        }
+        if (listItem.test(line) && !fieldLine.test(line)) {
+            flush();
+            out.push(list());
+            continue;
+        }
+        if (fieldLine.test(line)) {
+            flush();
+            let html = inline(line.trim());
+            // A severity value becomes a chip.
+            html = html.replace(/^(<strong>Severity:?<\/strong>:?\s*)(critical|high|medium|low|informational|info)\b/i, (_, lead, sev) => `${lead}<span class="chip sev-${sev.toLowerCase()}">${sev}</span>`);
+            out.push(`<p class="field">${html}</p>`);
+            i++;
+            continue;
+        }
+        para.push(line.trim());
+        i++;
+    }
+    flush();
+    if (inFinding)
+        out.push('</section>');
+    return { html: out.join('\n'), toc };
+}
+/* ------------------------------------------------------------------ text */
+/** Word-wraps one paragraph to width with a first-line prefix and a hanging indent. */
+function wrap(text, width, first = '', rest = '') {
+    const words = text.split(/\s+/).filter(Boolean);
+    const out = [];
+    let line = first;
+    let lead = first;
+    for (const w0 of words) {
+        let w = w0;
+        // A single word longer than a line is broken hard.
+        while ([...w].length > width - rest.length) {
+            if (line.trim() !== lead.trim())
+                out.push(line.trimEnd());
+            const room = width - rest.length;
+            out.push(rest + [...w].slice(0, room).join(''));
+            w = [...w].slice(room).join('');
+            line = rest;
+            lead = rest;
+        }
+        if (!w)
+            continue;
+        const next = line === lead ? line + w : `${line} ${w}`;
+        if ([...next].length > width && line !== lead) {
+            out.push(line.trimEnd());
+            line = rest + w;
+            lead = rest;
+        }
+        else
+            line = next;
+    }
+    if (line.trim())
+        out.push(line.trimEnd());
+    return out.length ? out : [first.trimEnd()];
+}
+const plainInline = (s, tags = false) => {
+    let t = s.replace(/`([^`]+)`/g, '$1').replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (_, l, u) => (u.startsWith('#') ? l : `${l} <${u}>`));
+    t = t.replace(/\*\*([^*]+)\*\*|__([^_]+)__/g, (_, a, b) => a ?? b ?? '');
+    t = t.replace(/(^|[^*\w])\*([^*\s][^*]*)\*(?!\w)|(^|[^_\w])_([^_\s][^_]*)_(?!\w)/g, (_, p1, a, p3, b) => `${p1 ?? p3 ?? ''}${a ?? b}`);
+    // Evidence labels are tagged on field lines (Evidence, Result), where a reader scans for them; prose keeps the plain words.
+    if (tags)
+        for (const [k, label] of Object.entries(LEVEL_LABEL))
+            t = t.replace(new RegExp(`(^|[\\s(])(${label})`, 'gi'), (_, pre, l) => `${pre}[${LEVEL_TAG[k]}] ${l}`);
+    return t;
+};
+// @comment -- "Markdown to plain text at a fixed width (default 80): underlined headings, wrapped paragraphs with hanging indents for lists and fields, tables as aligned columns when they fit and as label: value blocks when they do not, code indented and hard-wrapped, evidence labels tagged [REPRODUCED] and the like. Every output line is at most width columns."
+export function renderReportText(src, width = 80) {
+    const lines = src.replace(/\r\n?/g, '\n').split('\n');
+    const out = [];
+    const para = [];
+    const flush = () => {
+        if (para.length) {
+            out.push(...wrap(plainInline(para.join(' ')), width), '');
+            para.length = 0;
+        }
+    };
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        const fence = /^\s*(```|~~~)/.exec(line);
+        if (fence) {
+            flush();
+            i++;
+            while (i < lines.length && !lines[i].trim().startsWith(fence[1])) {
+                const l = '    ' + lines[i++];
+                for (let k = 0; k < Math.max(1, [...l].length); k += width)
+                    out.push([...l].slice(k, k + width).join('').trimEnd());
+            }
+            i++;
+            out.push('');
+            continue;
+        }
+        if (!line.trim()) {
+            flush();
+            i++;
+            continue;
+        }
+        const h = /^(#{1,6})\s+(.*?)\s*#*\s*$/.exec(line);
+        if (h) {
+            flush();
+            const text = plainInline(h[2]);
+            const wrapped = wrap(h[1].length === 1 ? text.toUpperCase() : text, width);
+            out.push(...wrapped);
+            if (h[1].length <= 2)
+                out.push((h[1].length === 1 ? '=' : '-').repeat(Math.min(width, Math.max(...wrapped.map((w) => [...w].length)))));
+            out.push('');
+            i++;
+            continue;
+        }
+        if (line.includes('|') && i + 1 < lines.length && isTableSep(lines[i + 1])) {
+            flush();
+            const head = cells(line).map((c) => plainInline(c));
+            i += 2;
+            const rows = [];
+            while (i < lines.length && lines[i].includes('|') && lines[i].trim())
+                rows.push(cells(lines[i++]).map((c) => plainInline(c)));
+            const widths = head.map((c, k) => Math.max([...c].length, ...rows.map((r) => [...(r[k] ?? '')].length)));
+            const total = widths.reduce((a, b) => a + b, 0) + 2 * (widths.length - 1);
+            if (total <= width) {
+                const row = (r) => r.map((c, k) => (c ?? '').padEnd(widths[k])).join('  ').trimEnd();
+                out.push(row(head), widths.map((w) => '-'.repeat(w)).join('  '), ...rows.map(row), '');
+            }
+            else {
+                for (const r of rows) {
+                    head.forEach((hd, k) => out.push(...wrap(r[k] ?? '', width, `${hd}: `, '  ')));
+                    out.push('');
+                }
+            }
+            continue;
+        }
+        const li = listItem.exec(line);
+        if (li && !fieldLine.test(line)) {
+            flush();
+            const indent = ' '.repeat(Math.min(8, li[1].length));
+            const marker = /\d/.test(li[2]) ? `${li[2]} ` : '- ';
+            let body = li[3];
+            i++;
+            while (i < lines.length && lines[i].trim() && !listItem.test(lines[i]) && /^\s+/.test(lines[i]))
+                body += ` ${lines[i++].trim()}`;
+            out.push(...wrap(plainInline(body), width, indent + marker, indent + ' '.repeat(marker.length)));
+            if (!(i < lines.length && listItem.test(lines[i])))
+                out.push('');
+            continue;
+        }
+        if (/^\s*>/.test(line)) {
+            flush();
+            const q = [];
+            while (i < lines.length && /^\s*>/.test(lines[i]))
+                q.push(lines[i++].replace(/^\s*>\s?/, ''));
+            out.push(...renderReportText(q.join('\n'), width - 2).split('\n').map((l) => (l ? `| ${l}` : '|')));
+            continue;
+        }
+        if (fieldLine.test(line)) {
+            flush();
+            out.push(...wrap(plainInline(line.trim().replace(/^[-*]\s+/, ''), true), width, '', '  '));
+            i++;
+            continue;
+        }
+        if (/^\s*([-*_])(\s*\1){2,}\s*$/.test(line)) {
+            flush();
+            out.push('-'.repeat(Math.min(width, 40)), '');
+            i++;
+            continue;
+        }
+        para.push(line.trim());
+        i++;
+    }
+    flush();
+    return out.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+}

package/dist/report/meta.js

@@ -0,0 +1,48 @@
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { BravosError } from '../types.js';
+// @comment -- "The report folders under .bravos/reports and their meta.json (kind, title, check verdict with finding counts, exported formats): the small read/write layer bravos report and bravos watch share. No dependency on the evidence gathering, so watch can read reports cheaply."
+export const META_SCHEMA = 'bravos.report-meta/v1';
+export const REPORTS_DIR = join('.bravos', 'reports');
+// @comment -- "The folder of report id under root; ids are refused unless they are a plain name, so a report id can never point outside .bravos/reports."
+export const reportDir = (root, id) => {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,80}$/.test(id))
+        throw new BravosError(`not a report id: ${id}`);
+    return join(root, REPORTS_DIR, id);
+};
+// @comment -- "Reads a report's meta.json; a missing, unreadable or foreign file reads as null."
+export function readMeta(root, id) {
+    try {
+        const m = JSON.parse(readFileSync(join(reportDir(root, id), 'meta.json'), 'utf8'));
+        return m?.schema === META_SCHEMA ? m : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeMeta(root, meta) {
+    writeFileSync(join(reportDir(root, meta.id), 'meta.json'), JSON.stringify(meta, null, 2) + '\n');
+}
+// @comment -- "Lists report folders newest first by their meta.json creation time (falling back to the folder's mtime); 'latest' resolves to the first."
+export function listReports(root) {
+    const base = join(root, REPORTS_DIR);
+    if (!existsSync(base))
+        return [];
+    return readdirSync(base, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && existsSync(join(base, e.name, 'evidence.json')))
+        .map((e) => ({ id: e.name, at: readMeta(root, e.name)?.createdAt ?? statSync(join(base, e.name)).mtime.toISOString() }))
+        .sort((a, b) => (a.at < b.at ? 1 : a.at > b.at ? -1 : a.id < b.id ? 1 : -1))
+        .map((r) => r.id);
+}
+export function resolveReport(root, ref) {
+    if (!ref || ref === 'latest') {
+        const first = listReports(root)[0];
+        if (!first)
+            throw new BravosError('no reports yet: run bravos report data, then write report.md (/bravos-report)');
+        return first;
+    }
+    reportDir(root, ref);
+    if (!existsSync(join(root, REPORTS_DIR, ref)))
+        throw new BravosError(`no report ${ref} under ${REPORTS_DIR}`);
+    return ref;
+}

package/dist/report/pdf.js

@@ -0,0 +1,96 @@
+import { spawnSync } from 'node:child_process';
+import { accessSync, constants, existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { delimiter, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+// @comment -- "PDF without a dependency: finds an installed Chromium-family browser (BRAVOS_PDF_BROWSER, then Chrome, Edge, Brave or Chromium at their usual install paths or on PATH, then Playwright's Chromium) and prints the report's own HTML file with --headless --print-to-pdf. argv, no shell, a throwaway profile directory so the person's browser profile is never touched, and a timeout."
+const executable = (p) => {
+    try {
+        accessSync(p, constants.X_OK);
+        return statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+function onPath(names, env) {
+    for (const dir of (env.PATH ?? '').split(delimiter)) {
+        if (!dir)
+            continue;
+        for (const n of names)
+            if (executable(join(dir, n)))
+                return join(dir, n);
+    }
+    return null;
+}
+/** Playwright's downloaded Chromium builds, newest first. */
+function playwrightChromium(env) {
+    const home = env.HOME ?? homedir();
+    for (const cache of [env.PLAYWRIGHT_BROWSERS_PATH, join(home, 'Library', 'Caches', 'ms-playwright'), join(home, '.cache', 'ms-playwright')].filter((d) => !!d)) {
+        let dirs = [];
+        try {
+            dirs = readdirSync(cache).filter((d) => /^chromium(_headless_shell)?-\d+$/.test(d)).sort((a, b) => Number(b.split('-').pop()) - Number(a.split('-').pop()));
+        }
+        catch {
+            continue;
+        }
+        for (const d of dirs) {
+            for (const rel of [
+                'chrome-mac/Chromium.app/Contents/MacOS/Chromium',
+                'chrome-mac-arm64/Chromium.app/Contents/MacOS/Chromium',
+                'chrome-mac/headless_shell',
+                'chrome-mac-arm64/headless_shell',
+                'chrome-headless-shell-mac-arm64/chrome-headless-shell',
+                'chrome-headless-shell-mac-x64/chrome-headless-shell',
+                'chrome-linux/chrome',
+                'chrome-linux/headless_shell',
+                'chrome-headless-shell-linux64/chrome-headless-shell',
+            ]) {
+                const p = join(cache, d, rel);
+                if (executable(p))
+                    return p;
+            }
+        }
+    }
+    return null;
+}
+// @comment -- "The browser that can print a PDF here, or null: BRAVOS_PDF_BROWSER when it is executable, then the usual macOS and Windows install paths, then Chrome/Chromium/Edge/Brave names on PATH, then Playwright's Chromium."
+export function findBrowser(env = process.env) {
+    if (env.BRAVOS_PDF_BROWSER)
+        return executable(env.BRAVOS_PDF_BROWSER) ? env.BRAVOS_PDF_BROWSER : null;
+    const home = env.HOME ?? homedir();
+    const mac = ['Google Chrome.app/Contents/MacOS/Google Chrome', 'Chromium.app/Contents/MacOS/Chromium', 'Microsoft Edge.app/Contents/MacOS/Microsoft Edge', 'Brave Browser.app/Contents/MacOS/Brave Browser'];
+    const win = [env.PROGRAMFILES, env['PROGRAMFILES(X86)'], env.LOCALAPPDATA]
+        .filter((d) => !!d)
+        .flatMap((d) => [join(d, 'Google', 'Chrome', 'Application', 'chrome.exe'), join(d, 'Microsoft', 'Edge', 'Application', 'msedge.exe'), join(d, 'BraveSoftware', 'Brave-Browser', 'Application', 'brave.exe')]);
+    const candidates = [
+        ...(process.platform === 'darwin' && !env.BRAVOS_PDF_NO_SYSTEM ? mac.flatMap((m) => [join('/Applications', m), join(home, 'Applications', m)]) : []),
+        ...(process.platform === 'win32' ? win : []),
+    ];
+    for (const c of candidates)
+        if (executable(c))
+            return c;
+    return onPath(['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', 'microsoft-edge', 'msedge', 'brave-browser', 'chrome'], env) ?? playwrightChromium(env);
+}
+// @comment -- "Prints htmlFile to pdfFile with the browser in headless mode and checks the result starts with %PDF; a fresh profile directory is created and removed around the run."
+export function printPdf(htmlFile, pdfFile, env = process.env, timeoutMs = 90000) {
+    const browser = findBrowser(env);
+    if (!browser)
+        return { ok: false, reason: 'no Chrome, Edge, Brave or Chromium found (set BRAVOS_PDF_BROWSER to one, or print the HTML to PDF from a browser)' };
+    const profile = mkdtempSync(join(tmpdir(), 'bravos-pdf-'));
+    try {
+        rmSync(pdfFile, { force: true });
+        const r = spawnSync(browser, ['--headless=new', '--disable-gpu', '--no-first-run', '--no-default-browser-check', '--disable-extensions', `--user-data-dir=${profile}`, '--no-pdf-header-footer', `--print-to-pdf=${pdfFile}`, pathToFileURL(htmlFile).href], { env, stdio: ['ignore', 'ignore', 'pipe'], encoding: 'utf8', timeout: timeoutMs });
+        if (r.error)
+            return { ok: false, reason: `${browser} did not run: ${r.error.message}` };
+        if (!existsSync(pdfFile))
+            return { ok: false, reason: `${browser} wrote no PDF${r.stderr ? `: ${String(r.stderr).split('\n').find((l) => l.trim()) ?? ''}` : ''}` };
+        const head = readFileSync(pdfFile).subarray(0, 5).toString('latin1');
+        if (head !== '%PDF-')
+            return { ok: false, reason: `${browser} wrote a file that is not a PDF` };
+        return { ok: true, browser };
+    }
+    finally {
+        rmSync(profile, { recursive: true, force: true });
+    }
+}

package/dist/review-server.js

@@ -0,0 +1,7 @@
+// @comment -- "Detached child that serves one review: argv root, kind, token, port. Started by bravos review so the command can return at once in any harness; it exits on Done or after 30 minutes idle."
+import { readDraft, renderReview, startReviewServer } from './review.js';
+const [root, kind, token, port] = process.argv.slice(2);
+const draft = readDraft(root, kind);
+const page = await renderReview(draft, { kind: 'serve', token });
+const { server } = await startReviewServer(root, draft, page, token, Number(port));
+server.on('close', () => process.exit(0));