@bugb-technologies/bravos 0.0.0-stage → 1.0.0

package/dist/artifacts.js

@@ -0,0 +1,450 @@
+// @comment -- "Fetches, verifies and stages the two binary bundles bravos owns: the licensed analyzer (bravos-cli and its scanners) and the code graph (codegraph-build, codegraph-mcp). A port of the Python CLI's analyzer.py and artifact.py: each published file has a detached bravos-artifact-signature/1 statement signed under the artifact key (never the licence key), the manifest is verified before it is read, the tarball before it is opened, and the unpack refuses links, absolute paths, '..', duplicates and anything past a size ceiling. Nothing touches the network without a licence the portal accepts: the download URLs come from the account portal, which checks the licence server-side and presigns a short-lived link to the private bucket; BRAVOS_ARTIFACT_BASE_URL points at a plain directory instead, for tests and air-gapped mirrors."
+import { createHash, createPublicKey, verify as cryptoVerify } from 'node:crypto';
+import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, symlinkSync, unlinkSync, writeSync } from 'node:fs';
+import { arch, platform } from 'node:os';
+import { dirname, join } from 'node:path';
+import { gunzipSync } from 'node:zlib';
+import { licenceLib } from './licence.js';
+import { BravosError } from './types.js';
+import { ANALYZER_VERSION, CODEGRAPH_VERSION } from './versions.js';
+export const MAGIC = 'bravos-artifact-signature/1';
+export const ARTIFACT_KID = 'bugb-artifact-2026a';
+// @comment -- "The artifact signing key's public half, fixed in the source like the licence key and distinct from it: a licence says who may run the analyzer, a signature says these bytes are the ones Bugb published. No environment variable, flag or file adds a key; tests hand verify() a throwaway set in-process."
+export const TRUSTED_ARTIFACT_KEYS = Object.freeze({
+    [ARTIFACT_KID]: '-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAX2x2o4eSFTU+Ti1Kkew+/t9LO4POT4D0r9aoRtJbz9o=\n-----END PUBLIC KEY-----\n',
+});
+export const MANIFEST_SCHEMAS = { analyzer: 'bravos-analyzer-manifest/2', codegraph: 'bravos-codegraph-manifest/1' };
+export const BUNDLE_FILE = 'BUNDLE.json';
+const MAX_MANIFEST_BYTES = 256 * 1024;
+const MAX_SIGNATURE_BYTES = 4096;
+const MAX_ARTIFACT_BYTES = 512 * 1024 * 1024;
+const MAX_UNPACKED_BYTES = 1024 * 1024 * 1024;
+const MAX_MEMBERS = 20_000;
+export const BASE_URL_ENV = 'BRAVOS_ARTIFACT_BASE_URL';
+export const NO_FETCH_ENV = 'BRAVOS_NO_FETCH';
+export const TARGETS = ['aarch64-apple-darwin', 'x86_64-apple-darwin', 'x86_64-unknown-linux-gnu', 'aarch64-unknown-linux-gnu'];
+export const REQUIRED = {
+    analyzer: ['bravos-cli', BUNDLE_FILE, 'rules/semgrep/PACK.toml', 'rules/sinks.yaml', 'rules/middleware.yaml', 'bin/gitleaks', 'bin/osv-scanner', 'bin/kics', 'bin/zizmor', 'share/kics/assets/queries', 'licences/NOTICE'],
+    codegraph: ['codegraph-build', 'codegraph-mcp', BUNDLE_FILE],
+};
+export const EXECUTABLES = {
+    analyzer: ['bravos-cli', 'bin/gitleaks', 'bin/osv-scanner', 'bin/kics', 'bin/zizmor'],
+    codegraph: ['codegraph-build', 'codegraph-mcp'],
+};
+export const VERSIONS = { analyzer: ANALYZER_VERSION, codegraph: CODEGRAPH_VERSION };
+export function hostTarget() {
+    const p = platform();
+    const a = arch();
+    if (p === 'darwin')
+        return a === 'arm64' ? 'aarch64-apple-darwin' : a === 'x64' ? 'x86_64-apple-darwin' : null;
+    if (p === 'linux')
+        return a === 'x64' ? 'x86_64-unknown-linux-gnu' : a === 'arm64' ? 'aarch64-unknown-linux-gnu' : null;
+    return null;
+}
+const KID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const HEX64 = /^[0-9a-f]{64}$/;
+export class SignatureError extends Error {
+}
+/** The five header lines, as signed: the one place these bytes are assembled. */
+export function signedStatement(kid, name, size, sha256) {
+    if (!KID_RE.test(kid))
+        throw new SignatureError(`malformed kid: ${JSON.stringify(kid)}`);
+    if (!NAME_RE.test(name))
+        throw new SignatureError(`malformed artifact name: ${JSON.stringify(name)}`);
+    if (!Number.isInteger(size) || size < 0)
+        throw new SignatureError(`malformed size: ${String(size)}`);
+    if (!HEX64.test(sha256))
+        throw new SignatureError(`malformed sha256: ${JSON.stringify(sha256)}`);
+    return Buffer.from(`${MAGIC}\nkid: ${kid}\nname: ${name}\nsize: ${size}\nsha256: ${sha256}\n`, 'utf8');
+}
+export function parseSignature(text) {
+    if (text.length > MAX_SIGNATURE_BYTES)
+        throw new SignatureError('signature file is far larger than a signature (is it HTML?)');
+    const lines = text.split('\n');
+    while (lines.length && lines[lines.length - 1] === '')
+        lines.pop();
+    if (lines.length !== 6)
+        throw new SignatureError(`expected 6 lines, found ${lines.length}`);
+    if (lines[0] !== MAGIC)
+        throw new SignatureError(`not a ${MAGIC} file: first line is ${JSON.stringify(lines[0])}`);
+    const fields = {};
+    for (const line of lines.slice(1)) {
+        const i = line.indexOf(': ');
+        if (i < 0)
+            throw new SignatureError(`malformed field line: ${JSON.stringify(line)}`);
+        const key = line.slice(0, i);
+        if (key in fields)
+            throw new SignatureError(`repeated field line: ${JSON.stringify(line)}`);
+        fields[key] = line.slice(i + 2);
+    }
+    const expected = ['kid', 'name', 'sha256', 'sig', 'size'];
+    if (Object.keys(fields).sort().join(',') !== expected.join(','))
+        throw new SignatureError(`fields are ${Object.keys(fields).sort().join(', ')}, expected ${expected.join(', ')}`);
+    if (!/^(0|[1-9]\d*)$/.test(fields.size))
+        throw new SignatureError(`size is not canonical: ${JSON.stringify(fields.size)}`);
+    const size = Number(fields.size);
+    if (!/^[A-Za-z0-9+/]+={0,2}$/.test(fields.sig))
+        throw new SignatureError('sig is not valid base64');
+    const signature = Buffer.from(fields.sig, 'base64');
+    if (signature.length !== 64)
+        throw new SignatureError(`signature is ${signature.length} bytes, expected 64`);
+    const st = { kid: fields.kid, name: fields.name, size, sha256: fields.sha256, signature };
+    signedStatement(st.kid, st.name, st.size, st.sha256);
+    return st;
+}
+export const renderSignature = (st) => signedStatement(st.kid, st.name, st.size, st.sha256).toString('utf8') + 'sig: ' + st.signature.toString('base64') + '\n';
+// @comment -- "Verifies `data` against its signature file: the digest and size are computed from the bytes on hand and the statement is rebuilt from them, so the signature can only ever vouch for what was actually downloaded, never for what the file said about itself."
+export function verifyArtifact(name, data, sigText, keys = TRUSTED_ARTIFACT_KEYS) {
+    const st = parseSignature(sigText);
+    if (st.name !== name)
+        throw new SignatureError(`the signature is for ${JSON.stringify(st.name)}, not ${JSON.stringify(name)}`);
+    const sha256 = createHash('sha256').update(data).digest('hex');
+    if (st.size !== data.length || st.sha256 !== sha256)
+        throw new SignatureError(`${name} does not match its signature statement (size ${data.length} vs ${st.size}, sha256 ${sha256.slice(0, 12)}… vs ${st.sha256.slice(0, 12)}…)`);
+    const pem = keys[st.kid];
+    if (!pem)
+        throw new SignatureError(`unknown artifact signing key ${JSON.stringify(st.kid)}: either it is not ours, or this bravos predates a key rotation — upgrade bravos, then retry`);
+    let ok = false;
+    try {
+        ok = cryptoVerify(null, signedStatement(st.kid, st.name, st.size, st.sha256), createPublicKey({ key: pem, format: 'pem' }), st.signature);
+    }
+    catch {
+        ok = false;
+    }
+    if (!ok)
+        throw new SignatureError(`${name} is not signed by Bugb (bad signature); nothing was installed. If this machine fetches through a proxy or a mirror, that is where to look`);
+    return st;
+}
+function* tarMembers(tar) {
+    let off = 0;
+    let longName = null;
+    let paxPath = null;
+    const str = (b) => b.toString('utf8').replace(/\0.*$/s, '');
+    while (off + 512 <= tar.length) {
+        const h = tar.subarray(off, off + 512);
+        if (h.every((b) => b === 0))
+            break;
+        const sizeField = str(h.subarray(124, 136)).trim();
+        const size = sizeField.charCodeAt(0) === 0x80 ? Number(BigInt('0x' + h.subarray(125, 136).toString('hex'))) : parseInt(sizeField || '0', 8);
+        if (!Number.isFinite(size) || size < 0)
+            throw new Error('tar: bad size field');
+        const type = String.fromCharCode(h[156]) || '0';
+        let name = str(h.subarray(0, 100));
+        const prefix = str(h.subarray(345, 500));
+        if (prefix && str(h.subarray(257, 263)) === 'ustar')
+            name = `${prefix}/${name}`;
+        const mode = parseInt(str(h.subarray(100, 108)).trim() || '0', 8);
+        const data = tar.subarray(off + 512, off + 512 + size);
+        if (data.length !== size)
+            throw new Error('tar: truncated member');
+        off += 512 + Math.ceil(size / 512) * 512;
+        if (type === 'L') {
+            longName = str(data);
+            continue;
+        }
+        if (type === 'x') {
+            for (const rec of data.toString('utf8').split('\n')) {
+                const m = /^\d+ path=(.*)$/.exec(rec);
+                if (m)
+                    paxPath = m[1];
+            }
+            continue;
+        }
+        if (type === 'g')
+            continue;
+        const finalName = paxPath ?? longName ?? name;
+        longName = null;
+        paxPath = null;
+        yield { name: finalName, size, mode, type: type === '\0' ? '0' : type, data };
+    }
+}
+function checkedParts(name) {
+    if (!name || name.includes('\0') || name.includes('\\') || name.startsWith('/'))
+        throw new Error(`${JSON.stringify(name)} is not a plain relative path`);
+    const parts = name.replace(/\/+$/, '').split('/');
+    if (parts.some((p) => p === '' || p === '.' || p === '..'))
+        throw new Error(`${JSON.stringify(name)} has an empty, '.' or '..' segment`);
+    return parts;
+}
+// @comment -- "Unpacks a verified .tar.gz into an empty folder with the Python CLI's rules: a gunzip ceiling, a member ceiling, plain relative paths only, regular files and directories only (a link is refused, and the tree is checked for links afterwards), each file created O_EXCL so nothing is overwritten, modes 0755 or 0644."
+export function unpack(packed, into, name) {
+    let tar;
+    try {
+        tar = gunzipSync(packed, { maxOutputLength: MAX_UNPACKED_BYTES + 1 });
+    }
+    catch (e) {
+        throw new BravosError(`${name} verified and will not decompress: ${e.message}. Nothing was installed`);
+    }
+    if (tar.length > MAX_UNPACKED_BYTES)
+        throw new BravosError(`${name} verified and expands past ${MAX_UNPACKED_BYTES} bytes. Nothing was installed`);
+    const seen = new Set();
+    let count = 0;
+    try {
+        for (const m of tarMembers(tar)) {
+            if (++count > MAX_MEMBERS)
+                throw new Error(`holds more than ${MAX_MEMBERS} entries`);
+            const parts = checkedParts(m.name);
+            const key = parts.join('/');
+            if (seen.has(key))
+                throw new Error(`holds ${JSON.stringify(m.name)} twice`);
+            seen.add(key);
+            const target = join(into, ...parts);
+            if (m.type === '5') {
+                mkdirSync(target, { recursive: true, mode: 0o755 });
+                continue;
+            }
+            if (m.type !== '0')
+                throw new Error(`holds ${JSON.stringify(m.name)}, which is not a regular file or a directory`);
+            mkdirSync(dirname(target), { recursive: true });
+            const mode = m.mode & 0o100 ? 0o755 : 0o644;
+            const fd = openSync(target, 'wx', mode);
+            try {
+                writeSync(fd, m.data);
+            }
+            finally {
+                closeSync(fd);
+            }
+            chmodSync(target, mode);
+        }
+    }
+    catch (e) {
+        throw new BravosError(`${name} verified and ${e.message}. Nothing was installed; report the bravos version and platform to Bugb support`);
+    }
+    const walk = (dir) => {
+        for (const n of readdirSync(dir)) {
+            const p = join(dir, n);
+            const st = lstatSync(p);
+            if (st.isSymbolicLink())
+                throw new BravosError(`${name} verified and left a link at ${p.slice(into.length + 1)}. Nothing was installed`);
+            if (st.isDirectory())
+                walk(p);
+        }
+    };
+    walk(into);
+}
+// ---------------------------------------------------------------------------------------------
+// Where things are staged
+// ---------------------------------------------------------------------------------------------
+export const homeDir = (env) => {
+    const h = env.BRAVOS_HOME || (env.HOME ? join(env.HOME, '.bravos') : null);
+    if (!h)
+        throw new BravosError('no home directory: set BRAVOS_HOME to where bravos should keep its binaries');
+    return h;
+};
+export const stageDir = (env, kind, version, target) => join(homeDir(env), kind, version, target);
+export const currentLink = (env, kind) => join(homeDir(env), kind, 'current');
+/** What is missing from a staged bundle, or [] when it is complete and executable. */
+export function missingPaths(kind, root) {
+    const out = REQUIRED[kind].filter((p) => !existsSync(join(root, p)));
+    for (const p of EXECUTABLES[kind]) {
+        const abs = join(root, p);
+        if (existsSync(abs)) {
+            try {
+                if (!(lstatSync(abs).mode & 0o100))
+                    out.push(`${p} (not executable)`);
+            }
+            catch {
+                out.push(p);
+            }
+        }
+    }
+    return out;
+}
+// @comment -- "The staged bundle this CLI would run: $BRAVOS_HOME/<kind>/current when it is complete, else the pinned version's folder for this host, else null."
+export function staged(env, kind) {
+    let home;
+    try {
+        home = homeDir(env);
+    }
+    catch {
+        return null;
+    }
+    const candidates = [join(home, kind, 'current')];
+    const t = hostTarget();
+    if (t)
+        candidates.push(join(home, kind, VERSIONS[kind], t));
+    for (const c of candidates) {
+        try {
+            if (existsSync(c) && missingPaths(kind, c).length === 0)
+                return realpathSync(c);
+        }
+        catch {
+            /* next */
+        }
+    }
+    return null;
+}
+/** The environment a staged bundle declares in BUNDLE.json: `env` (relative paths made absolute) and `path_prepend`. */
+export function bundleEnvironment(root, base) {
+    const env = { ...base };
+    let doc = null;
+    try {
+        doc = JSON.parse(readFileSync(join(root, BUNDLE_FILE), 'utf8'));
+    }
+    catch {
+        doc = null;
+    }
+    const inside = (rel) => {
+        try {
+            const parts = checkedParts(rel);
+            return join(root, ...parts);
+        }
+        catch {
+            return null;
+        }
+    };
+    if (doc && typeof doc === 'object') {
+        for (const [k, rel] of Object.entries(doc.env ?? {}).sort()) {
+            const p = typeof rel === 'string' ? inside(rel) : null;
+            if (p && !env[k])
+                env[k] = p;
+        }
+        const first = (Array.isArray(doc.path_prepend) ? doc.path_prepend : []).map((r) => (typeof r === 'string' ? inside(r) : null)).filter((p) => !!p);
+        if (first.length)
+            env.PATH = [...first, ...(env.PATH ? [env.PATH] : [])].join(':');
+    }
+    env.SEMGREP_ENABLE_VERSION_CHECK ??= '0';
+    env.SEMGREP_SEND_METRICS ??= 'off';
+    return env;
+}
+async function get(f, url, limit, what, headers = {}) {
+    let r;
+    try {
+        r = await f(url, { headers: { 'User-Agent': 'bravos-cli', ...headers }, redirect: 'follow' });
+    }
+    catch (e) {
+        throw new BravosError(`could not fetch the ${what} (${url.split('?')[0]}): ${e.message}`);
+    }
+    // A presigned link carries its signature in the query; the message names the object, not the credential.
+    const where = url.split('?')[0];
+    if (r.status === 404)
+        throw new BravosError(`the ${what} is not published yet (${where}); run bravos setup again later — everything on the Free plan works without it`);
+    if (!r.ok)
+        throw new BravosError(`the ${what} answered HTTP ${r.status} (${where})`);
+    const len = Number(r.headers.get('content-length') || 0);
+    if (len > limit)
+        throw new BravosError(`the ${what} is ${len} bytes, past the ${limit}-byte ceiling (${url.split('?')[0]})`);
+    const buf = Buffer.from(await r.arrayBuffer());
+    if (buf.length > limit)
+        throw new BravosError(`the ${what} is ${buf.length} bytes, past the ${limit}-byte ceiling (${url.split('?')[0]})`);
+    return buf;
+}
+// @comment -- "Where the files come from. With BRAVOS_ARTIFACT_BASE_URL, a plain layout <base>/<kind>/<version>/<file> (tests, mirrors). Otherwise the account portal: GET /api/v1/cli/artifacts/<kind>/<version>/<triple> with the licence as the bearer; the portal verifies it, counts the pull, and answers presigned URLs into the private bucket. The licence token goes to the portal origin and nowhere else; the presigned URLs carry their own authorization."
+async function urlsFor(kind, version, target, io) {
+    const f = io.fetch ?? fetch;
+    const base = (io.env[BASE_URL_ENV] || '').trim();
+    if (base) {
+        const root = `${base.replace(/\/+$/, '')}/${kind}/${version}`;
+        return { manifest: `${root}/manifest.json`, manifestSig: `${root}/manifest.json.sig`, artifact: (file) => `${root}/${file}`, artifactSig: (file) => `${root}/${file}.sig` };
+    }
+    const L = await licenceLib();
+    const found = L.find(io.env);
+    if (!found.token)
+        throw new BravosError(`no licence at ${found.source}: the ${kind} download is licensed — bravos account activate (30-day Team trial, no card)`);
+    const originRaw = (io.env.BRAVOS_ACCOUNT_ORIGIN || '').trim();
+    const origin = originRaw || L.ACCOUNT_ORIGIN;
+    const url = `${origin}/api/v1/cli/artifacts/${kind}/${version}/${target}`;
+    let r;
+    try {
+        r = await f(url, { headers: { 'User-Agent': 'bravos-cli', Accept: 'application/json', Authorization: `Bearer ${found.token}` } });
+    }
+    catch (e) {
+        throw new BravosError(`could not reach ${origin} for the ${kind} download: ${e.message}`);
+    }
+    if (r.status === 402)
+        throw new BravosError(`${origin} refused the ${kind} download: the licence from ${found.source} does not cover it (${L.ACCOUNT_UPGRADE})`);
+    if (r.status === 401)
+        throw new BravosError(`${origin} did not accept the licence from ${found.source}; bravos licence says why, ${L.ACCOUNT_LICENCES} has a fresh one`);
+    // 404: a portal that predates licensed downloads; 503: the portal has them but no bucket behind them yet. Both mean "not yet", not "broken".
+    if (r.status === 404 || r.status === 503)
+        throw new BravosError(`${origin} is not handing out the ${kind} download yet (HTTP ${r.status}); run bravos setup again later — everything on the Free plan works without it`);
+    if (!r.ok)
+        throw new BravosError(`${origin} answered HTTP ${r.status} for the ${kind} download`);
+    const body = (await r.json());
+    const need = ['url', 'sig_url', 'manifest_url', 'manifest_sig_url'];
+    for (const k of need)
+        if (typeof body[k] !== 'string' || !/^https?:\/\//.test(body[k]))
+            throw new BravosError(`${origin} answered without ${k}; report this to Bugb support`);
+    return { manifest: body.manifest_url, manifestSig: body.manifest_sig_url, artifact: () => body.url, artifactSig: () => body.sig_url };
+}
+// @comment -- "Fetch, verify and stage one bundle: manifest (+sig) → this host's artifact entry → tarball (+sig, size, sha256) → unpack into a temporary sibling folder → required paths present and executable → rename into place → the `current` link. Nothing under $BRAVOS_HOME changes until every check has passed, and BRAVOS_NO_FETCH refuses before the first request."
+export async function install(kind, io, opts = {}) {
+    if (io.env[NO_FETCH_ENV])
+        throw new BravosError(`${NO_FETCH_ENV} is set: refusing to download the ${kind} bundle`);
+    const version = opts.version ?? VERSIONS[kind];
+    const target = opts.target ?? hostTarget();
+    if (!target)
+        throw new BravosError(`no ${kind} bundle is published for this platform (${platform()} ${arch()}); the targets are ${TARGETS.join(', ')}`);
+    const f = io.fetch ?? fetch;
+    const keys = io.keys ?? TRUSTED_ARTIFACT_KEYS;
+    const echo = io.echo ?? (() => { });
+    const urls = await urlsFor(kind, version, target, io);
+    echo(`${kind} ${version}: fetching the manifest`);
+    const manifestBytes = await get(f, urls.manifest, MAX_MANIFEST_BYTES, `${kind} manifest`);
+    const manifestSig = await get(f, urls.manifestSig, MAX_SIGNATURE_BYTES, `${kind} manifest signature`);
+    try {
+        verifyArtifact('manifest.json', manifestBytes, manifestSig.toString('utf8'), keys);
+    }
+    catch (e) {
+        throw new BravosError(`the ${kind} manifest did not verify: ${e.message}`);
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(manifestBytes.toString('utf8'));
+    }
+    catch (e) {
+        throw new BravosError(`the signed ${kind} manifest is not JSON: ${e.message}; report this to Bugb support`);
+    }
+    if (manifest.schema !== MANIFEST_SCHEMAS[kind])
+        throw new BravosError(`the ${kind} manifest is ${JSON.stringify(manifest.schema)} and this bravos reads ${MANIFEST_SCHEMAS[kind]}: upgrade bravos, then retry`);
+    if (manifest.version !== version)
+        throw new BravosError(`the ${kind} manifest is version ${JSON.stringify(manifest.version)}, not ${version}`);
+    const entry = manifest.artifacts?.[target];
+    if (!entry || typeof entry.file !== 'string')
+        throw new BravosError(`no ${kind} ${version} build for ${target} in the manifest (it has ${Object.keys(manifest.artifacts ?? {}).join(', ') || 'none'})`);
+    const file = entry.file;
+    if (file !== file.split('/').pop() || file.startsWith('.'))
+        throw new BravosError(`the manifest names an artifact ${JSON.stringify(file)}; report this to Bugb support`);
+    echo(`${kind} ${version}: fetching ${file} (${Number(entry.size) ? `${Math.round(Number(entry.size) / 1048576)} MB` : 'size unknown'})`);
+    const packed = await get(f, urls.artifact(file), MAX_ARTIFACT_BYTES, `${kind} bundle`);
+    const sig = await get(f, urls.artifactSig(file), MAX_SIGNATURE_BYTES, `${kind} bundle signature`);
+    let st;
+    try {
+        st = verifyArtifact(file, packed, sig.toString('utf8'), keys);
+    }
+    catch (e) {
+        throw new BravosError(`${file} did not verify: ${e.message}`);
+    }
+    if ((typeof entry.sha256 === 'string' && entry.sha256 !== st.sha256) || (typeof entry.size === 'number' && entry.size !== st.size))
+        throw new BravosError(`${file} verified but is not the build the manifest names; report this to Bugb support`);
+    const dest = stageDir(io.env, kind, version, target);
+    const tmp = `${dest}.installing-${process.pid}`;
+    rmSync(tmp, { recursive: true, force: true });
+    mkdirSync(tmp, { recursive: true, mode: 0o755 });
+    try {
+        echo(`${kind} ${version}: verified; unpacking`);
+        unpack(packed, tmp, file);
+        const missing = missingPaths(kind, tmp);
+        if (missing.length)
+            throw new BravosError(`${file} verified and unpacked, but the bundle lacks ${missing.join(', ')}. Nothing was installed; report this to Bugb support`);
+        rmSync(dest, { recursive: true, force: true });
+        mkdirSync(dirname(dest), { recursive: true });
+        renameSync(tmp, dest);
+    }
+    catch (e) {
+        rmSync(tmp, { recursive: true, force: true });
+        throw e;
+    }
+    const link = currentLink(io.env, kind);
+    try {
+        if (lstatSync(link).isSymbolicLink() || existsSync(link))
+            unlinkSync(link);
+    }
+    catch {
+        /* absent */
+    }
+    symlinkSync(join(version, target), link, 'dir');
+    echo(`${kind} ${version}: staged at ${dest}`);
+    return { kind, version, target, dir: dest, manifest };
+}

package/dist/ci.js

@@ -0,0 +1,52 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { readLock, sha256, writeLock } from './lock.js';
+import { templatesDir } from './paths.js';
+// @comment -- "Token every bravos workflow carries in its first line, so an unlocked workflow can still be recognised as bravos-managed."
+export const WORKFLOW_MARKER = 'bravos:generated';
+// @comment -- "Copies each bundled templates/workflows/*.yml into .github/workflows/; an existing workflow is replaced only if bravos wrote it (lock hash or marker) unless --force, and the lock records each file written."
+export function writeWorkflows(root, opts = {}) {
+    const src = join(opts.templates ?? templatesDir(), 'workflows');
+    const report = { written: [], updated: [], unchanged: [], skipped: [] };
+    if (!existsSync(src))
+        return report;
+    const lock = readLock(root);
+    const record = {};
+    for (const name of readdirSync(src).filter((n) => n.endsWith('.yml')).sort()) {
+        const path = `.github/workflows/${name}`;
+        const abs = join(root, path);
+        const content = readFileSync(join(src, name));
+        const hash = sha256(content);
+        let status = 'written';
+        if (existsSync(abs)) {
+            const disk = readFileSync(abs);
+            const diskHash = sha256(disk);
+            if (diskHash === hash) {
+                report.unchanged.push(path);
+                record[path] = hash;
+                continue;
+            }
+            const locked = lock.files[path];
+            if (locked !== undefined && diskHash !== locked && !opts.force) {
+                report.skipped.push({ path, reason: 'edited since last install (use --force to overwrite)' });
+                continue;
+            }
+            if (locked === undefined && !disk.toString('utf8').includes(WORKFLOW_MARKER) && !opts.force) {
+                report.skipped.push({ path, reason: 'authored workflow, not managed by bravos (use --force to overwrite)' });
+                continue;
+            }
+            status = 'updated';
+        }
+        report[status].push(path);
+        if (opts.dryRun)
+            continue;
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, content);
+        record[path] = hash;
+    }
+    if (!opts.dryRun && Object.keys(record).length > 0) {
+        const fresh = readLock(root);
+        writeLock(root, { ...fresh, files: { ...fresh.files, ...record } });
+    }
+    return report;
+}