@bugb-technologies/bravos 0.0.0-stage → 1.0.1

package/dist/install.js

@@ -0,0 +1,209 @@
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { installedGuardlinkSkills } from './guardlink.js';
+import { readLock, sha256, writeLock } from './lock.js';
+import { skillsDir as bundledSkillsDir, version } from './paths.js';
+import { listBundledSkills, MARKER, renderSkillFile, skillsRoot } from './skills.js';
+// @comment -- "Writes the bundled skills into each harness skills root, rendering placeholders and marking SKILL.md only; overwrites only files bravos wrote and nobody edited (lock hash, or the marker for an unlocked SKILL.md) unless forced, and records hashes in the skills lock."
+export function installSkills(root, harnesses, opts = {}) {
+    const report = { written: [], updated: [], unchanged: [], skipped: [] };
+    const lock = readLock(root);
+    const record = {};
+    for (const skill of listBundledSkills(opts.skillsDir)) {
+        for (const harness of harnesses) {
+            for (const file of skill.files) {
+                const path = `${skillsRoot(harness)}/${skill.name}/${file.rel}`;
+                const isMd = file.rel.endsWith('.md');
+                // Only SKILL.md carries the marker, so only SKILL.md can be recognised by it when unlocked.
+                const isSkillMd = file.rel === 'SKILL.md';
+                const content = isMd
+                    ? Buffer.from((opts.render ?? renderSkillFile)(file.content.toString('utf8'), harness, skill.name, file.rel))
+                    : file.content;
+                const newHash = sha256(content);
+                const abs = join(root, path);
+                try {
+                    let status = 'written';
+                    if (existsSync(abs)) {
+                        const disk = readFileSync(abs);
+                        const diskHash = sha256(disk);
+                        if (diskHash === newHash) {
+                            report.unchanged.push(path);
+                            record[path] = newHash;
+                            continue;
+                        }
+                        const locked = lock.files[path];
+                        if (locked !== undefined) {
+                            if (diskHash !== locked && !opts.force) {
+                                report.skipped.push({ path, reason: 'edited since last install (use --force to overwrite)', source: join(opts.skillsDir ?? bundledSkillsDir(), skill.name, file.rel) });
+                                continue;
+                            }
+                        }
+                        else if ((!isSkillMd || !disk.toString('utf8').includes(MARKER)) && !opts.force) {
+                            report.skipped.push({ path, reason: 'authored file, not managed by bravos (use --force to overwrite)' });
+                            continue;
+                        }
+                        status = 'updated';
+                    }
+                    if (opts.dryRun) {
+                        report[status].push(path);
+                        continue;
+                    }
+                    mkdirSync(dirname(abs), { recursive: true });
+                    writeFileSync(abs, content);
+                    // A sandbox can accept a write and keep the old file; count the file only when it really changed,
+                    // or the lock would claim content that is not on disk and the next sync would call it edited.
+                    if (sha256(readFileSync(abs)) !== newHash)
+                        throw new Error('the write did not reach the disk (a sandbox or read-only folder?)');
+                    report[status].push(path);
+                    record[path] = newHash;
+                }
+                catch (err) {
+                    // One failing file must not lose the lock entries for files already written this run.
+                    report.skipped.push({ path, reason: `error: ${err.message}` });
+                }
+            }
+        }
+    }
+    if (!opts.dryRun && Object.keys(record).length > 0) {
+        // The lock claims this version only when every file was written; a skipped or failed file keeps
+        // the old version, so a stale copy stays visible to the shadow check and the next sync retries it.
+        const complete = report.skipped.length === 0;
+        writeLock(root, { ...lock, bravos_version: complete ? version() : lock.bravos_version, files: { ...lock.files, ...record } });
+    }
+    return report;
+}
+// @comment -- "True when .agents/skills and .claude/skills resolve to the same directory (one is a symlink to the other), so the skills must be written once, not rendered twice into one folder."
+export function skillRootsLinked(root) {
+    try {
+        return realpathSync(join(root, skillsRoot('agents'))) === realpathSync(join(root, skillsRoot('claude')));
+    }
+    catch {
+        return false;
+    }
+}
+// @comment -- "Marker guardlink writes into each playbook skill it generates (src/playbooks/skills.ts); only files carrying it are mirrored or replaced."
+export const GUARDLINK_MARKER = '<!-- guardlink:generated -->';
+function filesUnder(dir, prefix = '') {
+    const out = [];
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+        const rel = prefix ? `${prefix}/${e.name}` : e.name;
+        if (e.isDirectory())
+            out.push(...filesUnder(join(dir, e.name), rel));
+        else if (e.isFile())
+            out.push(rel);
+    }
+    return out.sort();
+}
+/** Copies guardlink's generated playbook skills from .claude/skills into .agents/skills, verbatim, so Codex can open them too. */
+// @comment -- "guardlink init writes its guardlink-annotate-* / guardlink-report-* skills under .claude/skills only; this mirrors each one whose SKILL.md carries guardlink's marker into .agents/skills byte for byte. A destination file is replaced only when it is unchanged since bravos last wrote it (lock hash) or, unlocked, carries guardlink's marker, unless forced; every write is recorded in the lock."
+export function mirrorGuardlinkSkills(root, opts = {}) {
+    const report = { written: [], updated: [], unchanged: [], skipped: [] };
+    const lock = readLock(root);
+    const record = {};
+    const from = skillsRoot('claude');
+    const to = skillsRoot('agents');
+    let names;
+    try {
+        names = installedGuardlinkSkills(root, from);
+    }
+    catch {
+        return report;
+    }
+    for (const name of names) {
+        const srcDir = join(root, from, name);
+        if (!readFileSync(join(srcDir, 'SKILL.md'), 'utf8').includes(GUARDLINK_MARKER))
+            continue;
+        for (const rel of filesUnder(srcDir)) {
+            const path = `${to}/${name}/${rel}`;
+            const abs = join(root, path);
+            const content = readFileSync(join(srcDir, rel));
+            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];
+                const managed = locked !== undefined ? diskHash === locked : disk.toString('utf8').includes(GUARDLINK_MARKER);
+                if (!managed && !opts.force) {
+                    report.skipped.push({ path, reason: locked !== undefined ? 'edited since last install (use --force to overwrite)' : 'authored file, not generated by guardlink (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;
+}
+// @comment -- "Replaces .agents/skills with a relative link to .claude/skills so every skill exists once (tools that read both roots, such as Warp, stop listing each twice). Refuses, removing nothing, when .agents/skills holds a file bravos did not write unchanged, or a guardlink skill with no copy under .claude/skills; bravos's own copies are removed and their lock entries dropped."
+export function linkSkillRoots(root, opts = {}) {
+    if (skillRootsLinked(root))
+        return { status: 'already-linked' };
+    const agents = skillsRoot('agents');
+    const claude = skillsRoot('claude');
+    if (!existsSync(join(root, claude)))
+        return { status: 'refused', reason: `${claude} does not exist yet; install for claude first`, unknown: [] };
+    const lock = readLock(root);
+    let stat = null;
+    try {
+        stat = lstatSync(join(root, agents));
+    }
+    catch {
+        stat = null;
+    }
+    const present = stat !== null;
+    // Every entry, not only regular files, so a link or socket inside counts as unknown.
+    const files = stat?.isDirectory() ? allUnder(join(root, agents)).map((r) => `${agents}/${r}`) : [];
+    if (stat && !stat.isDirectory()) {
+        return { status: 'refused', reason: `${agents} exists and is not a folder or a link to ${claude}`, unknown: [agents] };
+    }
+    const unknown = files.filter((f) => {
+        if (!lstatSync(join(root, f)).isFile())
+            return true;
+        const disk = sha256(readFileSync(join(root, f)));
+        if (lock.files[f] === disk) {
+            // A mirrored guardlink skill is safe to drop only when its original is under .claude/skills.
+            const sub = f.slice(agents.length + 1);
+            return sub.startsWith('guardlink-') && !existsSync(join(root, claude, sub));
+        }
+        return true;
+    });
+    if (unknown.length > 0) {
+        return { status: 'refused', reason: `${agents} holds files bravos did not write (or that were edited); move them into ${claude} first, then rerun`, unknown };
+    }
+    if (!opts.dryRun) {
+        if (present)
+            rmSync(join(root, agents), { recursive: true, force: true });
+        mkdirSync(dirname(join(root, agents)), { recursive: true });
+        symlinkSync('../.claude/skills', join(root, agents), 'dir');
+        for (const f of files)
+            delete lock.files[f];
+        writeLock(root, lock);
+    }
+    return { status: 'linked', removed: files };
+}
+function allUnder(dir, prefix = '') {
+    const out = [];
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+        const rel = prefix ? `${prefix}/${e.name}` : e.name;
+        if (e.isDirectory())
+            out.push(...allUnder(join(dir, e.name), rel));
+        else
+            out.push(rel);
+    }
+    return out;
+}

package/dist/licence.js

@@ -0,0 +1,41 @@
+// @comment -- "The CLI's view of the licence: a typed wrapper over hooks/lib/licence.mjs (the one implementation, shared with the session hooks), plus the gate every paid command calls. Nothing here verifies on its own; it asks the library and turns a refusal into a BravosError the person can act on."
+import { pathToFileURL } from 'node:url';
+import { join } from 'node:path';
+import { hooksDir } from './paths.js';
+import { BravosError } from './types.js';
+let cached = null;
+export const licenceLib = () => (cached ??= import(pathToFileURL(join(hooksDir(), 'lib', 'licence.mjs')).href));
+export async function licenceStatus(env) {
+    return (await licenceLib()).status(env);
+}
+// @comment -- "The gate: returns the status when `feature` is unlocked, else throws a BravosError whose message says what `what` does, that it is on the Team plan, and how to start the trial or renew. Every paid command and flag goes through here, so a refusal always reads the same."
+export async function requireFeature(env, feature, what) {
+    const L = await licenceLib();
+    const v = L.status(env);
+    if (L.entitled(v, feature))
+        return v;
+    throw new BravosError(L.refusal(v, feature, what));
+}
+/** The JSON document `bravos licence --json` prints: the status without the tenant id (an account id is not for logs). */
+export function licenceDocument(v) {
+    const { tenant: _tenant, ...rest } = v;
+    return { schema: 'bravos.licence/v1', ...rest, expiresAt: v.expiresAt === null ? null : new Date(v.expiresAt * 1000).toISOString(), graceUntil: v.graceUntil === null ? null : new Date(v.graceUntil * 1000).toISOString(), trial: v.trial ? { startedAt: new Date(v.trial.startedAt * 1000).toISOString(), endsAt: new Date(v.trial.endsAt * 1000).toISOString() } : null };
+}
+// @comment -- "The human form of bravos licence: the plan line, then where the licence is, what it unlocks and what it does not, and the one next step."
+export function licenceLines(L, v) {
+    const lines = [L.planLine(v)];
+    lines.push(`Licence: ${v.state === 'absent' ? 'none' : v.source}${v.kid ? ` (key ${v.kid})` : ''}`);
+    if (v.state === 'valid' || v.state === 'grace' || v.state === 'expired') {
+        lines.push(`  tier ${v.tier} · ${v.seats} seat${v.seats === 1 ? '' : 's'} · expires ${new Date((v.expiresAt ?? 0) * 1000).toISOString().slice(0, 10)}${v.trial ? ' (trial)' : ''}${v.features.length ? ` · features ${v.features.join(', ')}` : ''}`);
+    }
+    else if (v.state === 'invalid' || v.state === 'unreadable')
+        lines.push(`  ${v.message}`);
+    lines.push(`Unlocked: ${v.unlocked.length ? v.unlocked.map((f) => L.PAID_FEATURE_LABELS[f]).join(', ') : 'the research loop (context, annotate, templatize, env, prove, recheck, report, watch), in one repository'}`);
+    if (v.locked.length)
+        lines.push(`On Team: ${v.locked.map((f) => L.PAID_FEATURE_LABELS[f]).join(', ')}`);
+    if (!v.licensed)
+        lines.push(v.state === 'expired' || v.state === 'grace' ? `Renew: ${L.ACCOUNT_LICENCES}` : `Next: bravos account activate (30-day Team trial, no card) · ${L.ACCOUNT_UPGRADE}`);
+    else if (v.state === 'grace')
+        lines.push(`Renew: ${L.ACCOUNT_LICENCES} — the grace window ends ${new Date((v.graceUntil ?? 0) * 1000).toISOString().slice(0, 10)}`);
+    return lines;
+}

package/dist/lock.js

@@ -0,0 +1,50 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { version } from './paths.js';
+import { BravosError } from './types.js';
+// @comment -- "Schema id of the skills lock file."
+export const LOCK_SCHEMA = 'bravos.skills-lock/v1';
+// @comment -- "Repo-relative path of the skills lock that records the hash of every file bravos wrote."
+export const LOCK_PATH = '.bravos/skills.lock';
+// @comment -- "Content hash used in the skills lock, prefixed sha256:."
+export function sha256(buf) {
+    return 'sha256:' + createHash('sha256').update(buf).digest('hex');
+}
+// @comment -- "Reads and validates <root>/.bravos/skills.lock, returning an empty lock when absent and refusing a malformed one with a BravosError; non-string hashes are dropped."
+export function readLock(root) {
+    const abs = join(root, LOCK_PATH);
+    if (!existsSync(abs))
+        return { schema: LOCK_SCHEMA, bravos_version: version(), files: {} };
+    const bad = (why) => new BravosError(`${LOCK_PATH} ${why}; fix it or delete it, nothing was written`);
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(abs, 'utf8'));
+    }
+    catch {
+        throw bad('is not valid JSON');
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        throw bad('is not a JSON object');
+    const p = parsed;
+    if (p.schema !== LOCK_SCHEMA)
+        throw bad(`has schema ${JSON.stringify(p.schema)}, expected ${LOCK_SCHEMA}`);
+    if (typeof p.files !== 'object' || p.files === null || Array.isArray(p.files))
+        throw bad('has a "files" field that is not an object');
+    // Entries whose hash is not a string are dropped (treated as unmanaged), not refused.
+    const files = {};
+    for (const [k, v] of Object.entries(p.files))
+        if (typeof v === 'string')
+            files[k] = v;
+    return {
+        schema: LOCK_SCHEMA,
+        bravos_version: typeof p.bravos_version === 'string' ? p.bravos_version : version(),
+        files,
+    };
+}
+// @comment -- "Writes the skills lock as 2-space JSON, creating .bravos/ if needed."
+export function writeLock(root, lock) {
+    const abs = join(root, LOCK_PATH);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, JSON.stringify(lock, null, 2) + '\n');
+}

package/dist/mcp.js

@@ -0,0 +1,139 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { parse as parseToml } from 'smol-toml';
+import { whichBin } from './guardlink.js';
+import { graphBin, graphStore } from './codegraph.js';
+import { isInstallGraphCommand } from './graphbin.js';
+import { BravosError } from './types.js';
+// @comment -- "The launch argv (command and args) for each of the three MCP servers bravos knows: guardlink, cxg and codegraph; frozen so no caller can mutate a shared entry."
+export const SERVERS = Object.freeze({
+    guardlink: Object.freeze({ command: 'guardlink', args: ['mcp'] }),
+    cxg: Object.freeze({ command: 'cxg', args: ['mcp'] }),
+    codegraph: Object.freeze({ command: 'codegraph-mcp', args: ['--project-path', '.'] }),
+});
+const BIN = { cxg: 'cxg', codegraph: 'codegraph-mcp' };
+// @comment -- "Picks the servers to register: guardlink always, cxg when on PATH, codegraph when codegraph-mcp is on PATH or inside the bravos install (registered by full path, with the graph store the bravos launcher uses as BRAVOS_CODEGRAPH_DIR so the MCP route reads the graphs bravos graph build writes); the rest are reported as deferred."
+export function selectServers(env = process.env) {
+    const selected = { guardlink: SERVERS.guardlink };
+    const deferred = [];
+    if (whichBin(BIN.cxg, env))
+        selected.cxg = SERVERS.cxg;
+    else
+        deferred.push('cxg');
+    // The graph server may live inside the bravos install rather than on PATH: register it by its full path then.
+    const mcpBin = graphBin('codegraph-mcp', env);
+    if (mcpBin && mcpBin === whichBin('codegraph-mcp', env))
+        selected.codegraph = SERVERS.codegraph;
+    else if (mcpBin) {
+        const store = graphStore(env);
+        selected.codegraph = { command: mcpBin, args: [...SERVERS.codegraph.args], ...(store ? { env: { BRAVOS_CODEGRAPH_DIR: store } } : {}) };
+    }
+    else
+        deferred.push('codegraph');
+    return { selected, deferred };
+}
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+// @comment -- "Whether an existing entry is bravos's own codegraph registration into a bravos install that no longer matches what bravos would write now (a replaced install, or a graph store it lacks); such an entry is refreshed, every other existing entry is kept as it is."
+export function staleGraphEntry(name, existing, next) {
+    if (name !== 'codegraph' || !next || !isObject(existing) || !isInstallGraphCommand(existing.command))
+        return false;
+    return JSON.stringify({ c: existing.command, a: existing.args, e: existing.env ?? null }) !== JSON.stringify({ c: next.command, a: next.args, e: next.env ?? null });
+}
+// @comment -- "Adds missing servers to <root>/.mcp.json for Claude Code and refreshes bravos's own stale codegraph entry (staleGraphEntry); never overwrites any other existing entry and refuses malformed files without writing. A write rewrites the whole file as 2-space JSON: existing values are preserved, their formatting is not."
+export function mergeMcpJson(root, servers, opts = {}) {
+    const rel = '.mcp.json';
+    const file = join(root, rel);
+    const names = Object.keys(servers);
+    let doc = {};
+    if (existsSync(file)) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(file, 'utf8'));
+        }
+        catch {
+            throw new BravosError(`${rel} is not valid JSON; fix it or remove it, nothing was written`);
+        }
+        if (!isObject(parsed)) {
+            throw new BravosError(`${rel} is not a JSON object; fix it or remove it, nothing was written`);
+        }
+        doc = parsed;
+    }
+    if (doc.mcpServers !== undefined && !isObject(doc.mcpServers)) {
+        throw new BravosError(`${rel} has an mcpServers value that is not an object; fix it or remove it, nothing was written`);
+    }
+    const existing = (doc.mcpServers ?? {});
+    const updated = names.filter((n) => Object.hasOwn(existing, n) && staleGraphEntry(n, existing[n], servers[n]));
+    const kept = names.filter((n) => Object.hasOwn(existing, n) && !updated.includes(n));
+    const added = names.filter((n) => !Object.hasOwn(existing, n));
+    if (added.length === 0 && updated.length === 0)
+        return { path: rel, changed: false, added, kept };
+    for (const n of [...added, ...updated])
+        existing[n] = servers[n];
+    doc.mcpServers = existing;
+    if (!opts.dryRun)
+        writeFileSync(file, JSON.stringify(doc, null, 2) + '\n');
+    return { path: rel, changed: true, added, kept, ...(updated.length ? { updated } : {}) };
+}
+const tomlString = (v) => JSON.stringify(v);
+const tomlBlock = (name, s) => `\n[mcp_servers.${name}]\ncommand = ${tomlString(s.command)}\nargs = [${s.args.map(tomlString).join(', ')}]\n` +
+    (s.env ? `env = { ${Object.entries(s.env).map(([k, v]) => `${k} = ${tomlString(v)}`).join(', ')} }\n` : '');
+/** The text of a `[mcp_servers.<name>]` table bravos wrote, from its header up to the next table or the end; null when the file holds no such table. */
+function tomlTable(text, name) {
+    const header = new RegExp(`^\\[mcp_servers\\.${name}\\]\\s*$`, 'm').exec(text);
+    if (!header)
+        return null;
+    const rest = text.slice(header.index + header[0].length);
+    const next = /^\[/m.exec(rest);
+    return { start: header.index, end: next ? header.index + header[0].length + next.index : text.length };
+}
+// @comment -- "Appends missing [mcp_servers.<name>] tables to <root>/.codex/config.toml for Codex, and replaces bravos's own stale codegraph table (staleGraphEntry) in place; no other existing bytes are rewritten, and unparsable files are refused."
+export function mergeCodexConfig(root, servers, opts = {}) {
+    const rel = '.codex/config.toml';
+    const file = join(root, rel);
+    const names = Object.keys(servers);
+    const present = existsSync(file);
+    const text = present ? readFileSync(file, 'utf8') : '';
+    let tables = {};
+    if (present) {
+        try {
+            const parsed = parseToml(text);
+            if (parsed.mcp_servers !== undefined) {
+                if (!isObject(parsed.mcp_servers)) {
+                    throw new BravosError(`${rel} has an mcp_servers value that is not a table; fix it or remove it, nothing was written`);
+                }
+                tables = parsed.mcp_servers;
+            }
+        }
+        catch (e) {
+            if (e instanceof BravosError)
+                throw e;
+            throw new BravosError(`${rel} is not valid TOML; fix it or remove it, nothing was written`);
+        }
+    }
+    const updated = names.filter((n) => Object.hasOwn(tables, n) && staleGraphEntry(n, tables[n], servers[n]) && tomlTable(text, n));
+    const kept = names.filter((n) => Object.hasOwn(tables, n) && !updated.includes(n));
+    const added = names.filter((n) => !Object.hasOwn(tables, n));
+    if (added.length === 0 && updated.length === 0)
+        return { path: rel, changed: false, added, kept };
+    let base = text;
+    for (const n of updated) {
+        const at = tomlTable(base, n);
+        base = base.slice(0, at.start) + tomlBlock(n, servers[n]).replace(/^\n/, '') + base.slice(at.end).replace(/^\n?/, at.end < base.length ? '\n' : '');
+    }
+    let body = added.map((n) => tomlBlock(n, servers[n])).join('');
+    if (!present || base === '')
+        body = body.replace(/^\n/, '');
+    else if (body && !base.endsWith('\n'))
+        body = '\n' + body;
+    try {
+        parseToml(base + body);
+    }
+    catch {
+        throw new BravosError(`${rel} would not parse after adding the bravos servers; fix it or remove it, nothing was written`);
+    }
+    if (!opts.dryRun) {
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, base + body);
+    }
+    return { path: rel, changed: true, added, kept, ...(updated.length ? { updated } : {}) };
+}