@skanl/brambo-projection 0.1.1

package/dist/engine.js

@@ -0,0 +1,235 @@
+import { readFile, stat } from 'node:fs/promises';
+import { BramboError, BRAMBO_ERROR_CODES, REGISTRY_ENTRY_TYPES, isRegistryEntryType, projectionTargetLocation, } from '@skanl/brambo-contracts';
+import { atomicWriteText } from './atomic-write.js';
+import { resolveOwnedPath, sameOwnedPath } from './ledger.js';
+import { materialiseTarget } from './materialise.js';
+// Projection engine (FR-12): reads the ownership ledger once, then runs every
+// target SEQUENTIALLY — targets are never executed concurrently. Every failure
+// — malformed native file, unclaimable container, mid-projection external
+// modification, anything else — is CONTAINED per target: it becomes a typed
+// failure for that target alone and never affects sibling targets or escapes
+// runProjection.
+//
+// Each target records its claims IMMEDIATELY after its own file lands, and a
+// ledger write that fails FAILS THAT TARGET. Deferring the ledger to the end of
+// the run leaves a window where the file already holds new bytes while the
+// ledger still holds the old hash — and a warning there would leave brambo
+// permanently locked out of an entry it owns.
+//
+// An UNREADABLE ledger turns every target into an INSPECTION, and REFUSES the
+// ones that would have written. This paragraph used to say the opposite -- that
+// brambo wrote anyway
+// because "under-claiming for one run is recoverable (brambo reports its own
+// entries as foreign and touches nothing)" -- and that recovery does not exist
+// on the config path. DRIVEN: `brambo init` over an unreadable ledger exits 0 and
+// lands the bytes; repairing the ledger by hand afterwards leaves `brambo doctor`
+// at exit 0 with ZERO findings, and `brambo remove` + `brambo init` leaves the
+// server in the user's `.claude.json` permanently. `formats.ts`'s
+// ALREADY-SATISFIED branch swallows it precisely because brambo wrote it
+// CORRECTLY, so the orphan is invisible exactly when it is brambo's own doing.
+//
+// `ingest` already refuses this state before it lists a single vendor document,
+// for the reason written at `ingest.ts:106-119`: without the ledger brambo cannot
+// tell its own projections from the user's servers. `init` is the command that
+// WRITES into that config, so it cannot be the lenient one.
+/**
+ * The registry as the projection engine reads it: one bucket per DECLARED entry
+ * type.
+ *
+ * Derived from `REGISTRY_ENTRY_TYPES` rather than listed — a second table here
+ * is how the engine comes to project a word the contract no longer has, or to
+ * miss one it just gained. It is also the boundary that keeps a RETIRED type out
+ * of projection: an entry whose type is not declared has no bucket, so it is
+ * dropped here and no target is ever asked to express it. The store still reads
+ * it, `brambo list` still shows it and `brambo remove` still takes it out.
+ */
+export function groupByKind(entries) {
+    const grouped = Object.fromEntries(REGISTRY_ENTRY_TYPES.map((kind) => [kind, []]));
+    for (const entry of entries) {
+        // A type with no bucket is skipped, never crashed on, and there are two of
+        // them: a RETIRED word, dropped deliberately because no target renders it,
+        // and an unknown one, which post-validation means a hand-corrupted entry.
+        if (!isRegistryEntryType(entry.type))
+            continue;
+        grouped[entry.type].push(entry);
+    }
+    return grouped;
+}
+/**
+ * FAIL CLOSED. Not `mode !== 'inspect'`: that writes for `'Inspect'`,
+ * `'inspect '`, `'dry-run'` and `null`, and the one thing this field decides is
+ * whether brambo writes into files it does not own. A no-op run is visible in its
+ * own output; a write into a user's config on the say-so of a typo is not. So
+ * both failures are loud. `=== undefined`, not `??`: `null` is a value a caller
+ * PASSED, not an omission, and coalescing it into the writing default is the
+ * same silent accept this guard exists to remove.
+ *
+ * Shared by `runProjection` and `runRemediation` so the two commands that can
+ * write cannot disagree about what "do not touch this machine" means.
+ */
+export function resolveProjectionMode(mode) {
+    const resolved = mode === undefined ? 'apply' : mode;
+    if (resolved !== 'apply' && resolved !== 'inspect') {
+        throw new BramboError(BRAMBO_ERROR_CODES.projectionModeInvalid, `projection mode ${JSON.stringify(resolved)} is not recognised; use 'apply' or 'inspect' (omitted means 'apply')`);
+    }
+    return resolved;
+}
+async function readNativeFile(filePath) {
+    try {
+        const [text, stats] = await Promise.all([readFile(filePath, 'utf8'), stat(filePath)]);
+        return { text, snapshot: { mtimeMs: stats.mtimeMs, size: stats.size } };
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === 'ENOENT')
+            return { text: '', snapshot: undefined };
+        // A directory where the vendor's config file belongs, an unreadable mode, a
+        // dangling link: all reach here as a bare errno naming neither the path nor
+        // what brambo wanted with it. Coded, and both facts in the message.
+        throw new BramboError(BRAMBO_ERROR_CODES.projectionNativeUnclaimable, `native config file '${filePath}' cannot be read (${code ?? 'unknown error'}), so brambo cannot place entries there`, { cause: error });
+    }
+}
+/**
+ * Defense against a read-write race: if the native file changed on disk between
+ * the read and the write, the projection is stale and MUST NOT land. An ABSENT
+ * snapshot is not "nothing to compare": the merge was computed against an empty
+ * document, so the file appearing in the meantime — a vendor CLI creating
+ * `~/.claude.json` — is exactly the case where landing would overwrite it
+ * wholesale.
+ */
+export async function hasFileChangedSince(filePath, snapshot) {
+    if (snapshot === undefined) {
+        return await stat(filePath).then(() => true, (error) => error.code !== 'ENOENT');
+    }
+    const current = await stat(filePath);
+    return current.mtimeMs !== snapshot.mtimeMs || current.size !== snapshot.size;
+}
+function toTargetFailure(targetId, error) {
+    if (error instanceof BramboError)
+        return { targetId, error };
+    const detail = error instanceof Error ? error.message : String(error);
+    return {
+        targetId,
+        error: new BramboError(BRAMBO_ERROR_CODES.projectionTargetFailed, `projection target '${targetId}' failed: ${detail}`, { cause: error }),
+    };
+}
+async function projectTarget(target, entries, records, apply) {
+    const { text: nativeText, snapshot } = await readNativeFile(target.filePath);
+    const outcome = await target.merge({ entries, records, nativeText });
+    const written = outcome.text !== nativeText;
+    if (written) {
+        // Checked in BOTH modes, and that is the point rather than an oversight. It
+        // is true that an inspection has no write window to lose — but the
+        // PREDICTION is doctor's whole artifact, and a mode that skipped this would
+        // answer "this file would be rewritten" for a target where applying returns
+        // no result row and a failure instead. `~/.claude.json` is rewritten by
+        // Claude Code itself, so this is the machine doctor gets run on.
+        if (await hasFileChangedSince(target.filePath, snapshot)) {
+            throw new BramboError(BRAMBO_ERROR_CODES.projectionTargetFailed, `projection target '${target.targetId}' failed: file modified during projection: '${target.filePath}'`);
+        }
+        if (apply)
+            await atomicWriteText(target.filePath, outcome.text);
+    }
+    return {
+        result: {
+            targetId: target.targetId,
+            written,
+            byteDelta: written
+                ? Math.abs(Buffer.byteLength(outcome.text, 'utf8') - Buffer.byteLength(nativeText, 'utf8'))
+                : 0,
+            drift: outcome.drift,
+            skippedEntryIds: outcome.skippedEntryIds ?? [],
+        },
+        records: outcome.records,
+    };
+}
+export async function runProjection(options) {
+    // Every caller-controlled field read ONCE, here, before the first await. A
+    // caller object whose `mode` getter answers `'inspect'` now and `'apply'` on
+    // the second read would land bytes on a machine the caller was promised would
+    // not be touched, and `brambo doctor` is precisely the command that promises it.
+    const { entries, targets, ledger: store } = options;
+    const apply = resolveProjectionMode(options.mode) === 'apply';
+    const ledger = await store.read();
+    const warnings = [...ledger.warnings];
+    const results = [];
+    const failures = [];
+    for (const target of targets) {
+        // EVERYTHING derived from the target lives inside the try, including the
+        // ownership scope. Computing it outside was a hole in the engine's own
+        // containment promise: a target that is neither kind — a plain object
+        // reaching a published port — threw out of `runProjection` and took every
+        // sibling target with it.
+        let projected;
+        let scope;
+        // Reaches the write below, which is the whole reason it is declared out
+        // here: `store.update` drops exactly the entries this run TOOK A POSITION
+        // ON, and this snapshot is the record of which ones those were. Left inside
+        // the try, the write had no way to say "these are mine to retire" and said
+        // "the scope is mine to replace" instead — which erased whatever a
+        // concurrent run had claimed in between.
+        let claimed;
+        try {
+            // One ownership scope for both kinds: a config target's file, or a
+            // materialisation target's root. The ledger keys on it either way, so a
+            // target's claims are exactly the ones taken under the location it owns.
+            scope = {
+                targetId: target.targetId,
+                filePath: resolveOwnedPath(projectionTargetLocation(target)),
+            };
+            claimed = ledger.records.filter((record) => record.targetId === scope.targetId &&
+                sameOwnedPath(resolveOwnedPath(record.filePath), scope.filePath));
+            // An unreadable ledger runs the target as an INSPECTION even in apply
+            // mode. The merge, the drift classification and the verdict are all still
+            // computed — a caller learns exactly what it would have learned — but no
+            // byte lands, because a byte brambo cannot claim is a byte brambo can never
+            // take back.
+            const claimable = !apply || ledger.state !== 'unreadable';
+            projected =
+                target.kind === 'materialise'
+                    ? await materialiseTarget(target, entries, claimed, apply && claimable)
+                    : await projectTarget(target, entries, claimed, apply && claimable);
+            // `written` under an inspection reads as "these bytes WOULD have changed",
+            // so this fires ONLY when the run had something to write. A target whose
+            // location already holds exactly what brambo would write has nothing to
+            // orphan and is reported as the no-op it is, which is what the damaged
+            // ledger left behind by a successful earlier run looks like.
+            if (!claimable && projected.result.written) {
+                // Deliberately not opened with the word `brambo`: `test/printed-commands.ts`
+                // treats a backtick-quoted string that starts that way as a COMMAND, and
+                // this is a sentence.
+                throw new BramboError(BRAMBO_ERROR_CODES.projectionLedgerUnavailable, `refusing to write '${scope.filePath}' without the ownership ledger, because brambo could not then tell those bytes from yours: ${ledger.warnings.map((warning) => warning.detail).join('; ')}`);
+            }
+        }
+        catch (error) {
+            failures.push(toTargetFailure(target.targetId, error));
+            continue;
+        }
+        // The result is reported EVEN IF the ledger write below fails, and that
+        // ordering is the whole point: by this line the vendor's file already holds
+        // the new bytes. Reporting `written: false` for them — which is what
+        // dropping the result on a ledger failure amounts to at every caller — makes
+        // brambo accuse the user of editing bytes brambo wrote on the very next run,
+        // after which the entry never tracks the registry again. The failure still
+        // travels, so a caller learns the projection did not COMPLETE; what it no
+        // longer learns is a falsehood about what landed on disk.
+        results.push(projected.result);
+        // The SECOND of the two writes, and inspection skips it here rather than
+        // inside the ledger: a diagnosis that recorded claims for entries it did not
+        // write would tell the next real run that brambo owns bytes it never placed.
+        // NOT dead code, and driving it is what proved that. The guard above throws
+        // only when the target WOULD have written; a target with nothing to write
+        // falls through to here, and without the unreadable clause it reached
+        // `store.update` and failed the target on a ledger it was never going to
+        // touch — turning a harmless no-op into `brambo project init` exit 1.
+        if (!apply || ledger.state === 'unreadable')
+            continue;
+        try {
+            await store.update(scope, projected.records, claimed.map((record) => record.entryId));
+        }
+        catch (error) {
+            failures.push(toTargetFailure(target.targetId, error));
+        }
+    }
+    return { results, failures, warnings };
+}

package/dist/formats.d.ts

@@ -0,0 +1,132 @@
+import type { ProjectionMcpEntry, ProjectionConfigTarget } from '@skanl/brambo-contracts';
+export type FileFormat = 'jsonc' | 'toml';
+/** A vendor-native entry: keys and values in the vendor's own vocabulary. */
+export type NativeEntryShape = Readonly<Record<string, string | readonly string[]>>;
+/**
+ * What ONE vendor entry means in brambo's vocabulary, or why it means nothing
+ * brambo can hold — a typed absence rather than a bare `undefined` (AD-5), so a
+ * caller has to say what it does about an entry it cannot represent.
+ */
+export type ReadMcpEntry = {
+    readonly ok: true;
+    readonly command: string;
+    readonly args: readonly string[];
+} | {
+    readonly ok: false;
+    readonly detail: string;
+};
+/** The data that fully describes a projection target (FR-8). */
+export interface ProjectionTargetTraits {
+    readonly targetId: string;
+    readonly fileFormat: FileFormat;
+    /** Absolute path used when the caller injects no filePath override. */
+    readonly defaultPath: string;
+    /** The vendor's OWN container for MCP servers: JSON key or TOML table prefix. */
+    readonly mcpContainerKey: string;
+    /** The vendor's OWN entry shape. Its keys are the only keys brambo writes. */
+    readonly renderMcpEntry: (entry: ProjectionMcpEntry) => NativeEntryShape;
+    /**
+     * The exact inverse of {@link renderMcpEntry}, and REQUIRED for the same
+     * reason it sits here rather than in a reader module: the three vendors
+     * disagree about the shape, and OpenCode's `command` IS the argv, so the
+     * un-join belongs beside the join and nowhere else. Optional, it would permit
+     * a target that can be projected into and never read back — precisely the
+     * asymmetry M11.A exists to remove — so the type system carries the rule and
+     * a fourth trait record cannot forget it.
+     */
+    readonly readMcpEntry: (native: NativeEntryShape) => ReadMcpEntry;
+    /** JSON family only: treat comments/trailing commas as malformed native input. */
+    readonly strictJson?: boolean;
+}
+/**
+ * The keys THIS vendor's renderer emits, which are exactly the keys its reader
+ * consumes — asked of the renderer rather than written down beside it.
+ *
+ * A hand-written list here was a THIRD spelling of the same fact, and a key
+ * added to a renderer and forgotten in that list would be reported to the user
+ * as `dropped` while brambo was writing it. The sample is arbitrary: every
+ * renderer emits a fixed key set, which `vendor-conformance.test.ts` pins.
+ */
+export declare function renderedKeys(traits: ProjectionTargetTraits): readonly string[];
+/**
+ * The reading Claude Code and Codex SHARE: a `command` string beside an optional
+ * `args` array of strings.
+ *
+ * OpenCode deliberately does NOT use it. Its `command` is the whole argv, and
+ * D1 keeps that un-join in `opencode-config.ts` alone; what is shared here is
+ * only the vocabulary the other two already spell identically, so the sentence a
+ * user reads for a missing command cannot differ between two vendors that failed
+ * the same way.
+ */
+export declare function readNativeCommand(native: NativeEntryShape): ReadMcpEntry;
+export interface TraitTargetOptions {
+    /** Overrides the trait record's defaultPath (default paths are injectable). */
+    readonly filePath?: string;
+}
+/** One vendor MCP entry, read back into the vocabulary the registry stores. */
+export interface NativeMcpEntry {
+    readonly id: string;
+    readonly command: string;
+    readonly args: readonly string[];
+    /** Vendor keys the registry envelope cannot carry; reported, never lost (D10). */
+    readonly dropped: readonly string[];
+}
+/** An id that is present and out of which brambo can read no entry, and why. */
+export interface UnreadableNativeMcpEntry {
+    readonly id: string;
+    readonly detail: string;
+}
+export interface NativeMcpRead {
+    /** The document these were read from — the same path every detail names. */
+    readonly filePath: string;
+    readonly entries: readonly NativeMcpEntry[];
+    readonly unreadable: readonly UnreadableNativeMcpEntry[];
+    /**
+     * The file is THERE and brambo could not read it, in the OS's own errno.
+     *
+     * Distinct from `undefined` (absent, AD-5) and from a throw (malformed, D8):
+     * an `EACCES` on one vendor's config is neither "this executor is not
+     * installed" nor "this document is broken", and collapsing it into either
+     * makes one unreadable file either invisible or fatal to the whole run —
+     * including the skills half, which has nothing to do with it.
+     */
+    readonly unreadableFile?: string;
+}
+/**
+ * Every MCP server one vendor's own config file declares, or `undefined` when
+ * there is no such file.
+ *
+ * ABSENCE IS NOT FAILURE (AD-5): an executor is allowed not to be installed, so
+ * a missing `~/.codex/config.toml` contributes nothing and is not an error.
+ * Everything else is coded and names the path — a malformed document, a
+ * container holding something brambo cannot address, a file brambo may not read.
+ */
+export declare function readNativeMcpEntries(traits: ProjectionTargetTraits, options?: TraitTargetOptions): Promise<NativeMcpRead | undefined>;
+export interface LegacyBramboBlock {
+    /** Half-open range of the ORIGINAL text, byte-order mark included in the offsets. */
+    readonly start: number;
+    readonly end: number;
+    readonly detail: string;
+}
+/**
+ * `block` — brambo's own prior output, and exactly what removing it takes out.
+ * `refusal` — something that looks like it and brambo will not touch, with why.
+ * Neither — the file holds none.
+ */
+export interface LegacyBramboScan {
+    readonly block?: LegacyBramboBlock;
+    readonly refusal?: string;
+}
+/**
+ * Brambo's own prior output in one vendor file, if any is there.
+ *
+ * READS ONLY. `brambo doctor` calls it to report the state and the `discard`
+ * remediation calls it to remove exactly the region it returns.
+ */
+export declare function scanLegacyBramboBlock(nativeText: string, fileFormat: FileFormat): LegacyBramboScan;
+/**
+ * The ONE factory every target flows through: adding a target means writing a
+ * trait record — no engine or strategy code changes. An unknown file format is
+ * a coded configuration error, not a crash at splice time.
+ */
+export declare function createProjectionTargetFromTraits(traits: ProjectionTargetTraits, options?: TraitTargetOptions): ProjectionConfigTarget;