@skanl/brambo-projection 0.1.1

package/dist/remediate.js

@@ -0,0 +1,468 @@
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { parse as parseJsonc } from 'jsonc-parser';
+import { BRAMBO_ERROR_CODES, BramboError, isRecord, projectionTargetLocation } from '@skanl/brambo-contracts';
+import { atomicWriteText } from './atomic-write.js';
+import { hasFileChangedSince, resolveProjectionMode } from './engine.js';
+import { scanLegacyBramboBlock } from './formats.js';
+import { LEDGER_REPAIR_AUTHORITY, isUnderRoot, resolveOwnedPath, sameOwnedPath, serialiseLedgerDocument, } from './ledger.js';
+import { claimMaterialised } from './materialise.js';
+function refusalOf(message, code = BRAMBO_ERROR_CODES.projectionRemediationRefused) {
+    return { code, message };
+}
+function refused(remediation, targetId, entryId, location, refusal) {
+    return { remediation, targetId, entryId, location, changes: [], applied: false, refusal };
+}
+function ledgerChange(action, ledgerPath, location, detail, byteDelta = 0) {
+    return { subject: 'ledger', action, path: ledgerPath, location, byteDelta, detail };
+}
+/** The records one target holds at one location — the unit a ledger write replaces. */
+function scopeOf(target) {
+    return {
+        targetId: target.targetId,
+        filePath: resolveOwnedPath(projectionTargetLocation(target)),
+    };
+}
+/**
+ * The same predicate the engine uses to hand a target its own claims. Two
+ * spellings of "which records belong to this target at this location" is how a
+ * remediation comes to replace a set the projection would have computed
+ * differently.
+ */
+function claimsIn(records, scope) {
+    return records.filter((record) => record.targetId === scope.targetId &&
+        sameOwnedPath(resolveOwnedPath(record.filePath), scope.filePath));
+}
+async function readIfPresent(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return undefined;
+        throw new BramboError(BRAMBO_ERROR_CODES.projectionNativeUnclaimable, `native config file '${path}' cannot be read (${code ?? 'unknown error'})`, { cause: error });
+    }
+}
+/**
+ * Containment, applied to a record BEFORE it is written and again as the last
+ * thing before the write — the M4.B rule, unchanged, on the one path that
+ * creates a delete authority.
+ *
+ * A record's `ownedPaths` are what a later run takes to `rm`. `claimMaterialised`
+ * proves each of them inside the root while it builds them; this is the copy
+ * that runs next to `ledger.update`, so a record reaching here by any other
+ * route is still checked. Both halves are deliberate: the guard nobody can show
+ * firing is the guard that is not there.
+ */
+function escapingPath(record, scope) {
+    if (!sameOwnedPath(resolveOwnedPath(record.filePath), scope.filePath))
+        return record.filePath;
+    return (record.ownedPaths ?? []).find((item) => !isUnderRoot(resolveOwnedPath(item.path), scope.filePath))
+        ?.path;
+}
+/** Whether the REGISTRY still holds this id — what decides overwrite vs. removal. */
+function registered(entries, entryId) {
+    return Object.values(entries).some((kind) => kind.some((entry) => entry.id === entryId));
+}
+async function claimFor(options, claimed) {
+    const { target, entryId, entries } = options;
+    if (target.kind === 'materialise') {
+        return await claimMaterialised(target, entries, claimed, entryId);
+    }
+    if (target.claim === undefined) {
+        return {
+            location: entryId,
+            byteLength: 0,
+            refusal: `projection target '${target.targetId}' cannot say what occupies '${entryId}', so brambo will not claim it`,
+        };
+    }
+    const nativeText = (await readIfPresent(target.filePath)) ?? '';
+    // A config target answers about ONE file and knows nothing of the registry, so
+    // the consequence half is decided here. `removedNext` is what turns "the next
+    // run rewrites this" into "the next run deletes it", and a user has to be told
+    // which one before the claim is written, not after.
+    return { ...target.claim({ nativeText, entryId }), removedNext: !registered(entries, entryId) };
+}
+/**
+ * What taking this claim will let a LATER run do — the sentence the frozen
+ * Always clause requires and the first shipped version did not carry.
+ *
+ * Adoption writes no vendor byte, and the first wording said exactly that and
+ * stopped: *"no byte of that file is read again, written or removed"*. True of
+ * the ACT and false of its consequence, and it was inverted relative to risk —
+ * the branch where the occupant is a file the USER wrote got the reassuring
+ * sentence, while the branch where the file was brambo's to begin with got the
+ * warning.
+ *
+ * It takes no re-claim/fresh-claim argument on purpose: the two branches differ
+ * in what brambo is DOING (taking ownership versus re-taking it), which `adopt`
+ * says itself, and not in what ownership then permits. Making the consequence
+ * depend on which branch you are in is exactly how the wording came to reassure
+ * on the dangerous one.
+ */
+function consequenceOf(claim) {
+    const paths = claim.ownedPaths ?? [];
+    const authority = paths.length === 0
+        ? "brambo gains no authority to delete any FILE: a config claim covers one region inside the file and can never remove the file itself"
+        : `brambo gains authority to overwrite AND to REMOVE exactly these path(s) on a later run: ${paths.join(', ')}`;
+    // BOTH SPELLINGS, because this is the one site of its class where the scope is
+    // genuinely absent. `RemediationBase` carries none, and it is FR-29 public SDK
+    // surface — threading a CLI-grammar concept into a third-party type to render
+    // one sentence is a worse trade than naming two commands, and `doctor.ts`
+    // already sanctions the shape ("`brambo init` (or `brambo project init`) creates
+    // brambo's state here"). Driven before this: a project claim was told the next
+    // `brambo init` would replace the entry, and the hand-edited byte survived that
+    // command and died to `brambo project init`.
+    const projecting = '`brambo init` (or `brambo project init` for a project claim)';
+    const next = claim.removedNext === true
+        ? `the registry does not hold this entry, so the next ${projecting} REMOVES what this claim covers`
+        : // The SAME sentence on both branches, and that is the correction. The
+            // first version reassured on the fresh-claim branch — where the occupant
+            // is a file the USER wrote and the stakes are highest — and warned only
+            // on the re-claim one, where the file was brambo's to begin with. The
+            // wording was inverted relative to risk.
+            `the next ${projecting} REPLACES what is there with what the registry says`;
+    return `${authority}. Then ${next}. To keep what is there and have brambo stop tracking it, use 'release' instead`;
+}
+/**
+ * Brambo claims what is at its own location, exactly as it is now.
+ *
+ * This is the ownership TRANSFER decision AD-6 always implied and that no story
+ * had taken: ownership is a durable record brambo writes, so transferring it is
+ * writing that record — never inferring one from a path, and never widening what
+ * brambo would have written anyway. The claim's paths come from the TARGET's own
+ * plan, so a file the user put beside brambo's is not swept in and cannot later
+ * be removed on that authority.
+ *
+ * NOT A WRITE INTO A VENDOR FILE. Afterwards the location is brambo's, and the
+ * ordinary `brambo init` converges it — which is why there is no fourth verb that
+ * renders one entry outside the merge.
+ */
+async function adopt(options, apply) {
+    const { target, entryId, ledger } = options;
+    const scope = scopeOf(target);
+    const deny = (message, code) => refused('adopt', target.targetId, entryId, scope.filePath, refusalOf(message, code));
+    if (typeof entryId !== 'string' || entryId === '') {
+        return deny('an adoption names one registry entry, and brambo was given none');
+    }
+    const read = await ledger.read();
+    if (read.state === 'unreadable') {
+        return deny(`projection ledger '${ledger.filePath}' cannot be read, so brambo will not add a claim to it; repair the ledger first`, BRAMBO_ERROR_CODES.projectionLedgerUnavailable);
+    }
+    const claimed = claimsIn(read.records, scope);
+    const claim = await claimFor(options, claimed);
+    if (claim.refusal !== undefined)
+        return deny(claim.refusal);
+    const record = claim.record;
+    if (record === undefined) {
+        return deny(`nothing occupies '${claim.location}' at '${scope.filePath}', so there is nothing for brambo to claim`);
+    }
+    const escaping = escapingPath(record, scope);
+    if (escaping !== undefined) {
+        return deny(`claiming '${entryId}' would record '${escaping}', which is outside '${scope.filePath}'; brambo will not claim a path it cannot prove it owns`);
+    }
+    const existing = claimed.find((candidate) => candidate.entryId === entryId);
+    if (existing !== undefined && existing.contentHash === record.contentHash) {
+        return {
+            remediation: 'adopt',
+            targetId: target.targetId,
+            entryId,
+            location: claim.location,
+            changes: [],
+            applied: apply,
+        };
+    }
+    const changes = [
+        ledgerChange('claim', ledger.filePath, claim.location, `${existing === undefined
+            ? `brambo takes ownership of the ${claim.byteLength} byte(s) now at '${claim.location}' in '${scope.filePath}'`
+            : `brambo re-takes ownership of '${claim.location}' in '${scope.filePath}' at its CURRENT ${claim.byteLength} byte(s), replacing the hash it held`}. Nothing in that location is written by THIS command. ${consequenceOf(claim)}`),
+    ];
+    if (!apply) {
+        return { remediation: 'adopt', targetId: target.targetId, entryId, location: claim.location, changes, applied: false };
+    }
+    // Entry-granular, and re-read inside the ledger's own queue. Handing back a
+    // whole scope built from the read above would resurrect every claim another
+    // writer legitimately dropped in between — brambo would then claim a path it
+    // does not own, which on a materialisation root is an authority to delete it.
+    await ledger.updateEntry(scope, entryId, record);
+    return { remediation: 'adopt', targetId: target.targetId, entryId, location: claim.location, changes, applied: true };
+}
+/**
+ * Brambo stops claiming a location. The file is not read, not written, not
+ * looked at — this verb performs no filesystem operation except the ledger write
+ * itself, which is what makes it the safe exit from a state a user wants to keep
+ * exactly as they left it.
+ */
+async function release(options, apply) {
+    const { target, entryId, ledger } = options;
+    const scope = scopeOf(target);
+    const deny = (message, code) => refused('release', target.targetId, entryId, scope.filePath, refusalOf(message, code));
+    if (typeof entryId !== 'string' || entryId === '') {
+        return deny('a release names one registry entry, and brambo was given none');
+    }
+    const read = await ledger.read();
+    if (read.state === 'unreadable') {
+        return deny(`projection ledger '${ledger.filePath}' cannot be read, so brambo cannot tell which claim to drop; repair the ledger first`, BRAMBO_ERROR_CODES.projectionLedgerUnavailable);
+    }
+    const claimed = claimsIn(read.records, scope);
+    const dropped = claimed.filter((record) => record.entryId === entryId);
+    if (dropped.length === 0) {
+        return deny(`brambo holds no claim for '${entryId}' at '${scope.filePath}', so there is nothing to release`);
+    }
+    const changes = dropped.map((record) => ledgerChange('unclaim', ledger.filePath, record.nativeLocation, `brambo stops claiming '${record.nativeLocation}' in '${scope.filePath}'; whatever is there stays exactly as it is, and brambo will treat it as foreign until it is adopted again. Nothing on disk is removed by this or by any later run while the claim is gone`));
+    if (!apply) {
+        return { remediation: 'release', targetId: target.targetId, entryId, location: scope.filePath, changes, applied: false };
+    }
+    // Entry-granular for the same reason `adopt` is: a whole-scope replace built
+    // from the read above resurrects claims another writer dropped in between.
+    await ledger.updateEntry(scope, entryId, undefined);
+    return { remediation: 'release', targetId: target.targetId, entryId, location: scope.filePath, changes, applied: true };
+}
+/**
+ * Brambo rewrites its OWN ledger document to hold exactly the records it can
+ * still read.
+ *
+ * The one write in this file that does not merge, and the only exit from a
+ * ledger brambo carries and never repairs. Two shapes reach here and the
+ * description distinguishes them, because their consequences are not comparable:
+ * a document brambo can read but whose individual records are malformed loses
+ * only those records, while a document brambo cannot read AT ALL is replaced with
+ * an empty one — after which brambo claims nothing, and every entry it ever wrote
+ * reports as a foreign collision that `adopt` reclaims one at a time. That
+ * sentence is in the preview, before anything happens.
+ */
+async function repair(options, apply) {
+    const { ledger } = options;
+    const read = await ledger.read();
+    const location = ledger.filePath;
+    const base = { remediation: 'repair', targetId: '', entryId: '', location };
+    if (read.state === 'absent') {
+        return { ...base, changes: [], applied: apply };
+    }
+    if (read.state === 'readable' && read.warnings.length === 0) {
+        return { ...base, changes: [], applied: apply };
+    }
+    // SALVAGED, not just readable. Dropping the RECORD throws away far more than
+    // the broken FIELD: measured on the binary, a record whose only damage was its
+    // `contentHash` still carried all four identity fields, so brambo knew exactly
+    // which bytes it covered — and dropping it left `brambo doctor` reporting
+    // NOTHING, `brambo remediate adopt` refusing with exit 1, and `brambo remove` +
+    // `brambo init` leaving the entry in the user's config permanently. A salvaged
+    // record carries a hash brambo cannot vouch for, so the entry reads as `edited`
+    // — a state with an exit — instead of vanishing.
+    const kept = [...read.records, ...read.salvaged];
+    const lost = read.salvaged.length;
+    const current = await stat(ledger.filePath).then((stats) => stats.size, () => 0);
+    const next = Buffer.byteLength(serialiseLedgerDocument(kept), 'utf8');
+    // Built separately so the sentence below stays on ONE SOURCE LINE:
+    // `printed-commands.test.ts` scans line by line, and a printed sentence it
+    // cannot see is a printed sentence nothing checks.
+    const unvouched = lost === 0
+        ? ''
+        : `, and ${String(lost)} it can address but no longer vouch for, which report as edited until they are adopted or released`;
+    // THE OLD SENTENCE PROMISED SOMETHING BRAMBO DID NOT DELIVER. It said the
+    // records it drops leave entries that "report as foreign collisions until
+    // they are adopted". Driven on the binary, that was FALSE for config entries:
+    // after the drop the diagnosis reported NOTHING, the adopt remediation refused
+    // with exit 1, and removing the entry and re-initialising left it in the
+    // user's config permanently. The user consented to a rewrite on a promise
+    // brambo could not keep. (Command names are spelled out rather than quoted
+    // here: the printed-command scanner reads comments too, and a quoted one
+    // wrapped across two lines is exactly what it refuses.)
+    const detail = read.state === 'unreadable'
+        ? `brambo cannot read any of '${ledger.filePath}' and will REPLACE it with an empty ledger: brambo then claims nothing at all, every entry it has written anywhere reports as a foreign collision, and each one has to be adopted back deliberately`
+        : `brambo rewrites '${ledger.filePath}' holding ${String(kept.length)} record(s): ${String(read.records.length)} it can still vouch for${unvouched}. Any record with no readable identity left is dropped, and whatever it claimed becomes yours to remove by hand`;
+    const changes = [ledgerChange('rewrite', ledger.filePath, ledger.filePath, detail, Math.abs(next - current))];
+    if (!apply)
+        return { ...base, changes, applied: false };
+    // The read that DECIDES the write happens inside the ledger's own queue.
+    // Reading outside it and handing the result to the one write in the system
+    // that does not merge destroyed any claim written in between — deterministic,
+    // in-process, first try, and exactly the loss `ledger.ts`'s class header
+    // describes. `adopt` and `release` have the same shape and were saved by
+    // `update`'s merge; this method has no backstop, which is what made it the one
+    // that lost data.
+    //
+    // ponytail: this closes the IN-CALL window and not the cross-invocation one. A
+    // user who read a preview in one process and applied in another can still be
+    // told "drop 1 record" and get an empty ledger, because the two calls share no
+    // handle — the act reports what it really did, but only after doing it.
+    // Upgrade path: a receipt on the preview that the act must match, which is the
+    // same mechanism `adopt` needs for the same reason (deferred-work.md).
+    // `salvaged` too, and from the IN-QUEUE read rather than the one above: the
+    // write must be decided by the document as it is at the moment of writing.
+    await ledger.rewriteAll(LEDGER_REPAIR_AUTHORITY, (inQueue) => [
+        ...inQueue.records,
+        ...inQueue.salvaged,
+    ]);
+    return { ...base, changes, applied: true };
+}
+/**
+ * Brambo removes its OWN prior output from a vendor file — correction-01 C6.
+ *
+ * The one verb here that writes a file brambo did not author, and the bytes it
+ * takes are provably brambo's own vocabulary: a reserved `$.brambo` key or a
+ * `# BEGIN brambo-managed` block that no executor reads and that, in Codex's
+ * case, makes the user's whole `config.toml` fail to load under a documented
+ * flag. The region comes from `scanLegacyBramboBlock`, the SAME function
+ * `brambo doctor` reports it with, so the preview cannot name a region other
+ * than the one removed.
+ *
+ * In the JSON family the result is re-PARSED before it lands: a remediation that
+ * left a user's configuration unparseable would be a worse state than the one it
+ * repaired. TOML gets no such check and that is the existing rule rather than an
+ * omission — brambo never parses foreign TOML (see the header of `formats.ts`),
+ * and the removed region is bounded by brambo's own two marker lines, so nothing
+ * outside the block it wrote is inside the span.
+ */
+async function discard(options, apply) {
+    const { legacy } = options;
+    const filePath = resolveOwnedPath(legacy.filePath);
+    const root = resolveOwnedPath(legacy.rootPath);
+    const base = { remediation: 'discard', targetId: legacy.targetId, entryId: '', location: filePath };
+    const deny = (message) => refused('discard', legacy.targetId, '', filePath, refusalOf(message));
+    // Containment first, before the file is even opened, and against the REAL
+    // path. `resolve()` is string arithmetic: with `~/.claude` a junction into a
+    // dotfiles repository the write lands outside the very scope this refusal
+    // promises it will not, which is the sixth attack — the one M4.B's five cases
+    // do not cover, and the reason its removal rule checks links at every depth.
+    const real = await realPathOf(filePath);
+    const realRoot = await realPathOf(root);
+    if (!isUnderRoot(real, realRoot)) {
+        return deny(`'${filePath}' resolves to '${real}', which is outside '${realRoot}'; brambo will not rewrite a file beyond the scope it was given, whatever a link in the way says`);
+    }
+    const text = await readIfPresent(filePath);
+    if (text === undefined)
+        return { ...base, changes: [], applied: apply };
+    const snapshot = await statSnapshot(filePath);
+    const scan = scanLegacyBramboBlock(text, legacy.fileFormat);
+    if (scan.refusal !== undefined)
+        return deny(`${scan.refusal} in '${filePath}'`);
+    if (scan.block === undefined)
+        return { ...base, changes: [], applied: apply };
+    const next = text.slice(0, scan.block.start) + text.slice(scan.block.end);
+    if (legacy.fileFormat === 'jsonc') {
+        // JSONC-aware, not `JSON.parse`. The first version used `JSON.parse` and so
+        // SELF-DISABLED on exactly the inputs at risk — a file with a comment, a
+        // trailing comma or a byte-order mark never "originally parsed", and those
+        // are the same inputs `jsonRemovalSpan`'s whitespace walk handles worst (a
+        // `// note` between the member and its comma leaves a dangling comma the
+        // original did not have). Judged the way the vendor judges it, the guard
+        // fires on precisely those files.
+        if (parsesAsJsonc(text) && !parsesAsJsonc(next)) {
+            return deny(`removing brambo's own block from '${filePath}' would leave it unparseable, so brambo left it alone; remove the block by hand`);
+        }
+    }
+    const changes = [
+        {
+            subject: 'native-file',
+            action: 'rewrite',
+            path: filePath,
+            location: scan.block.detail,
+            byteDelta: Math.abs(Buffer.byteLength(next, 'utf8') - Buffer.byteLength(text, 'utf8')),
+            detail: `brambo removes ${scan.block.detail} from '${filePath}'; every other byte of the file is left exactly as it is`,
+        },
+    ];
+    if (!apply)
+        return { ...base, changes, applied: false };
+    // The same read-write race the engine defends against, restored after the
+    // argument for omitting it was falsified. The claim was that the failing case
+    // could not be built because the read and the write are one call; it can — the
+    // atomic writer performs six further filesystem round-trips after the read, and
+    // a competing write anywhere in that window is clobbered wholesale. The scope
+    // half was wrong too: Claude Code writes `~/.claude/settings.json` itself.
+    if (await hasFileChangedSince(filePath, snapshot)) {
+        return deny(`'${filePath}' was modified while brambo was reading it, so brambo would have overwritten that change; nothing was written`);
+    }
+    // A REFUSAL, NOT A THROW — the contract this file states about itself at the
+    // top: "A refusal is RETURNED, coded, not thrown". `discard` is the one
+    // remediation of four that writes a user's file, so this was the single state
+    // in the whole surface that left by a different door.
+    //
+    // And it did not escape uncoded, which would have been the ordinary hole. It
+    // escaped FALSELY coded: `describe()` duck-types `.code`, a Node
+    // `ErrnoException` has one, so a libuv errno rendered in brambo's coded-error
+    // position and the user read `EPERM: EPERM: ... rename '<file>.<uuid>.tmp'`.
+    // Doubled, exit 2 where every sibling refusal exits 1, and leaking the
+    // temporary path brambo writes through.
+    //
+    // BOTH shapes are caught deliberately. `atomicWriteText` can also throw a
+    // CODED `BRAMBO_PROJECTION_NATIVE_UNCLAIMABLE` from its own containment check,
+    // and catching only errnos would leave a coded error still escaping as a throw
+    // out of a function whose refusals are values.
+    //
+    // Modelled on `config-write.ts`, not on `ledger.ts`: both code their boundary,
+    // but the ledger speaks ledger vocabulary about brambo's OWN document, and this
+    // writes a VENDOR file — the same distinction `config-write.ts` already made
+    // as the first non-engine caller to reach this rule.
+    try {
+        await atomicWriteText(filePath, next);
+    }
+    catch (error) {
+        const detail = error instanceof BramboError ? error.code : error?.code;
+        return deny(`'${filePath}' could not be replaced (${detail ?? String(error)}) and brambo wrote nothing. A file made read-only was made read-only on purpose.`);
+    }
+    return { ...base, changes, applied: true };
+}
+/** File identity for the race check; `undefined` when the file is not there. */
+async function statSnapshot(path) {
+    return await stat(path).then((stats) => ({ mtimeMs: stats.mtimeMs, size: stats.size }), () => undefined);
+}
+/**
+ * The real path, with links resolved. Falls back to the nearest existing
+ * ancestor's real path when the target does not exist, so an absent file is
+ * still judged against where it WOULD be created.
+ */
+async function realPathOf(path) {
+    try {
+        return await realpath(path);
+    }
+    catch {
+        const parent = dirname(path);
+        return parent === path ? path : join(await realPathOf(parent), basename(path));
+    }
+}
+/**
+ * Whether jsonc-parser can read this document — comments, trailing commas and a
+ * byte-order mark included, which is what the vendors themselves accept.
+ */
+function parsesAsJsonc(text) {
+    const errors = [];
+    const parsed = parseJsonc(text.startsWith('\uFEFF') ? text.slice(1) : text, errors, {
+        allowTrailingComma: true,
+    });
+    return errors.length === 0 && isRecord(parsed);
+}
+/**
+ * Performs — or, under `'inspect'`, describes — exactly one remediation.
+ *
+ * The caller names the verb and its subject; nothing else is touched, and
+ * nothing runs by default. A state brambo will not leave is reported as a coded
+ * refusal in the result rather than thrown, because under inspection "brambo will
+ * not do this, and here is why" is part of the description.
+ */
+export async function runRemediation(options) {
+    // Every caller-controlled field read ONCE, before the first await — the same
+    // TOCTOU rule `runProjection` follows. An options object whose `mode` getter
+    // answered `'inspect'` now and `'apply'` on a second read would write on a
+    // machine the caller was promised would not be touched.
+    // `=== undefined`, not `??`: `null` is a value a caller PASSED, not an
+    // omission, and coalescing it into a default is the silent accept the shared
+    // validator exists to remove. Only a genuine omission becomes `'inspect'`.
+    const apply = resolveProjectionMode(options.mode === undefined ? 'inspect' : options.mode) === 'apply';
+    switch (options.remediation) {
+        case 'adopt':
+            return await adopt(options, apply);
+        case 'release':
+            return await release(options, apply);
+        case 'repair':
+            return await repair(options, apply);
+        case 'discard':
+            return await discard(options, apply);
+        default:
+            // Unreachable through the typed surface; a plain object reaching a
+            // published API must fail coded rather than silently do nothing.
+            throw new BramboError(BRAMBO_ERROR_CODES.projectionRemediationRefused, `remediation ${JSON.stringify(options.remediation)} is not recognised`);
+    }
+}

package/dist/targets/claude-mcp.d.ts

@@ -0,0 +1,6 @@
+import type { ProjectionConfigTarget } from '@skanl/brambo-contracts';
+import type { ProjectionTargetTraits, TraitTargetOptions } from '../formats.ts';
+export declare const CLAUDE_MCP_TARGET_ID = "claude-mcp";
+export declare const CLAUDE_MCP_TRAITS: ProjectionTargetTraits;
+export type ClaudeMcpTargetOptions = TraitTargetOptions;
+export declare function createClaudeMcpTarget(options?: ClaudeMcpTargetOptions): ProjectionConfigTarget;

package/dist/targets/claude-mcp.js

@@ -0,0 +1,36 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createProjectionTargetFromTraits, readNativeCommand } from '../formats.js';
+// Claude Code MCP target.
+//
+// Verified against Claude Code itself: `settings.json` has NO `mcpServers` key
+// — the reason the previous build's output was inert. User-scope MCP servers
+// live in `~/.claude.json`; project scope is the SAME `{mcpServers: {...}}`
+// shape in `<project>/.mcp.json`, so it is this trait record with an injected
+// filePath, not a second target.
+//
+// `~/.claude.json` is Claude's own state file, so brambo touches nothing in it
+// but the `mcpServers` key. It is strict JSON, expressed as trait data.
+export const CLAUDE_MCP_TARGET_ID = 'claude-mcp';
+export const CLAUDE_MCP_TRAITS = {
+    targetId: CLAUDE_MCP_TARGET_ID,
+    fileFormat: 'jsonc',
+    defaultPath: join(homedir(), '.claude.json'),
+    strictJson: true,
+    mcpContainerKey: 'mcpServers',
+    renderMcpEntry: (entry) => ({ type: 'stdio', command: entry.command, args: entry.args }),
+    // The inverse, beside the renderer it inverts. A `type` other than `stdio` is
+    // a server with no command at all — an HTTP or SSE entry carries a `url` —
+    // and brambo says so instead of inventing one. Which keys count as CONSUMED is
+    // not spelled here: the reader derives that from `renderMcpEntry` above, so a
+    // key added to the renderer cannot be reported to a user as dropped.
+    readMcpEntry: (native) => native['type'] !== undefined && native['type'] !== 'stdio'
+        ? {
+            ok: false,
+            detail: `its 'type' is ${JSON.stringify(native['type'])} rather than 'stdio', and brambo projects a command with arguments`,
+        }
+        : readNativeCommand(native),
+};
+export function createClaudeMcpTarget(options = {}) {
+    return createProjectionTargetFromTraits(CLAUDE_MCP_TRAITS, options);
+}

package/dist/targets/codex-config.d.ts

@@ -0,0 +1,6 @@
+import type { ProjectionConfigTarget } from '@skanl/brambo-contracts';
+import type { ProjectionTargetTraits, TraitTargetOptions } from '../formats.ts';
+export declare const CODEX_CONFIG_TARGET_ID = "codex-config";
+export declare const CODEX_CONFIG_TRAITS: ProjectionTargetTraits;
+export type CodexConfigTargetOptions = TraitTargetOptions;
+export declare function createCodexConfigTarget(options?: CodexConfigTargetOptions): ProjectionConfigTarget;

package/dist/targets/codex-config.js

@@ -0,0 +1,27 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createProjectionTargetFromTraits, readNativeCommand } from '../formats.js';
+// Codex config.toml target.
+//
+// The key is `mcp_servers` — snake_case, the name `ConfigToml` actually
+// declares. The previous build wrote `[mcpServers.<id>]` plus foreign sub-keys
+// into `[tools]` and `[skills]`, which are REAL fixed structs; under the
+// documented `--strict-config` flag that made the user's entire config.toml
+// fail to load. Brambo now emits only `command`/`args` inside a table Codex
+// owns, so strict mode has nothing to reject.
+export const CODEX_CONFIG_TARGET_ID = 'codex-config';
+export const CODEX_CONFIG_TRAITS = {
+    targetId: CODEX_CONFIG_TARGET_ID,
+    fileFormat: 'toml',
+    defaultPath: join(homedir(), '.codex', 'config.toml'),
+    mcpContainerKey: 'mcp_servers',
+    renderMcpEntry: (entry) => ({ command: entry.command, args: entry.args }),
+    // The inverse, beside the renderer it inverts. Codex's table carries no
+    // discriminator, so the reading is the shared one; anything else a user put in
+    // the table (`env`, `startup_timeout_sec`) is reported as dropped rather than
+    // silently discarded, against the key set the renderer above emits.
+    readMcpEntry: (native) => readNativeCommand(native),
+};
+export function createCodexConfigTarget(options = {}) {
+    return createProjectionTargetFromTraits(CODEX_CONFIG_TRAITS, options);
+}

package/dist/targets/opencode-config.d.ts

@@ -0,0 +1,6 @@
+import type { ProjectionConfigTarget } from '@skanl/brambo-contracts';
+import type { ProjectionTargetTraits, TraitTargetOptions } from '../formats.ts';
+export declare const OPENCODE_CONFIG_TARGET_ID = "opencode-config";
+export declare const OPENCODE_CONFIG_TRAITS: ProjectionTargetTraits;
+export type OpenCodeConfigTargetOptions = TraitTargetOptions;
+export declare function createOpenCodeConfigTarget(options?: OpenCodeConfigTargetOptions): ProjectionConfigTarget;

package/dist/targets/opencode-config.js

@@ -0,0 +1,58 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createProjectionTargetFromTraits } from '../formats.js';
+// OpenCode config target.
+//
+// `mcp.<id>` in opencode.json, shape `{type:'local', command: string[]}`.
+// OpenCode's `command` IS the argv — there is no `args` field — so the split
+// brambo keeps internally is joined here and nowhere else. opencode.json is
+// JSONC-tolerant (comments and trailing commas are legal), so it reuses the
+// shared splice WITHOUT the strict-JSON guard.
+export const OPENCODE_CONFIG_TARGET_ID = 'opencode-config';
+export const OPENCODE_CONFIG_TRAITS = {
+    targetId: OPENCODE_CONFIG_TARGET_ID,
+    fileFormat: 'jsonc',
+    defaultPath: join(homedir(), '.config', 'opencode', 'opencode.json'),
+    mcpContainerKey: 'mcp',
+    renderMcpEntry: (entry) => ({ type: 'local', command: [entry.command, ...entry.args] }),
+    // The UN-JOIN, and it lives here because the join does: `readNativeCommand`
+    // is the other two vendors' shared reading and would be the wrong answer for
+    // this one. A `remote` server carries a url and no argv at all, and an argv
+    // whose first element is not an executable name is a server with nothing to
+    // run — both are reported and skipped rather than turned into an entry no
+    // executor could start.
+    readMcpEntry: (native) => {
+        if (native['type'] !== undefined && native['type'] !== 'local') {
+            return {
+                ok: false,
+                detail: `its 'type' is ${JSON.stringify(native['type'])} rather than 'local', and brambo projects a command with arguments`,
+            };
+        }
+        const argv = native['command'];
+        if (argv === undefined || typeof argv === 'string') {
+            return {
+                ok: false,
+                detail: argv === undefined
+                    ? "it declares no 'command', so there is nothing for brambo to run"
+                    : "'command' is a string, and OpenCode spells a local server's whole argv as an array",
+            };
+        }
+        const [command, ...args] = argv;
+        if (command === undefined || command === '') {
+            // Two different documents, one honest sentence each: `[]` has no first
+            // element at all, and `['', 'x']` has one that names no executable.
+            // Saying "empty array" for the second described a file the user does not
+            // have, which is the kind of detail that sends someone to the wrong line.
+            return {
+                ok: false,
+                detail: command === undefined
+                    ? "'command' is an empty array, so there is no command to run"
+                    : "the first element of 'command' is empty, so the argv names no executable to run",
+            };
+        }
+        return { ok: true, command, args };
+    },
+};
+export function createOpenCodeConfigTarget(options = {}) {
+    return createProjectionTargetFromTraits(OPENCODE_CONFIG_TRAITS, options);
+}

package/dist/targets/skills.d.ts

@@ -0,0 +1,22 @@
+import type { ProjectionMaterialiseTarget } from '@skanl/brambo-contracts';
+/** The file name every one of the three executors requires. */
+export declare const SKILL_ENTRY_FILE = "SKILL.md";
+export interface SkillsTargetTraits {
+    readonly targetId: string;
+    /** Absolute machine-scope root, used when the caller injects none. */
+    readonly defaultRoot: string;
+}
+export interface SkillsTargetOptions {
+    /** Overrides the trait record's defaultRoot (default roots are injectable). */
+    readonly rootPath?: string;
+}
+export declare const CLAUDE_SKILLS_TARGET_ID = "claude-skills";
+export declare const CODEX_SKILLS_TARGET_ID = "codex-skills";
+export declare const OPENCODE_SKILLS_TARGET_ID = "opencode-skills";
+export declare const CLAUDE_SKILLS_TRAITS: SkillsTargetTraits;
+export declare const CODEX_SKILLS_TRAITS: SkillsTargetTraits;
+export declare const OPENCODE_SKILLS_TRAITS: SkillsTargetTraits;
+export declare function createSkillsTargetFromTraits(traits: SkillsTargetTraits, options?: SkillsTargetOptions): ProjectionMaterialiseTarget;
+export declare function createClaudeSkillsTarget(options?: SkillsTargetOptions): ProjectionMaterialiseTarget;
+export declare function createCodexSkillsTarget(options?: SkillsTargetOptions): ProjectionMaterialiseTarget;
+export declare function createOpenCodeSkillsTarget(options?: SkillsTargetOptions): ProjectionMaterialiseTarget;