@skanl/brambo-environment 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SKANL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @skanl/brambo-environment
+
+The verbs that change a machine: `init`, `doctor` and `remediate`, as a library.
+`@skanl/brambo-cli` is a thin binding over this package and holds no capability of its
+own — that is FR-29, and the consumer-install proof enforces it.
+
+```bash
+npm i @skanl/brambo-environment
+```
+
+## What it gives you
+
+- **`initMachine` / `initProject`** — project the registry into every executor's
+  NATIVE configuration, at the locations those executors actually read, and
+  record what brambo wrote so it can be taken back exactly.
+- **`diagnose`** — every state brambo can see, as a closed union of finding kinds.
+  `FINDING_EXITS` is a `Record` over that union, so **a finding kind without a
+  way out does not compile.**
+- **`remediate`** — `adopt`, `release`, `repair` and `discard`, each the exit for
+  a finding rather than a general-purpose editor.
+- **`detectExecutors`** — which executors this machine has, with the evidence
+  paths that decided it, so an absence is reportable rather than assumed.
+
+## The rule it exists to keep
+
+Brambo writes NATIVE vocabulary at NATIVE locations and never invents a location a
+vendor does not read. A concept no target can express is REPORTED as
+`unprojectable` — never approximated into a namespace that would look right and
+do nothing.

package/dist/doctor.d.ts

@@ -0,0 +1,261 @@
+import type { DriftEntry, DriftKind, ProjectionWarning, RemediationKind } from '@skanl/brambo-contracts';
+import type { ExecutorDetection } from './executors.ts';
+import type { LegacyBlock, SkippedExecutor, TargetFailure, UnprojectableEntry } from './init.ts';
+/**
+ * What one finding is about. The three drift kinds are the CONTRACT's
+ * (`DriftKind`), not a second vocabulary: a doctor that classified drift itself
+ * would be the divergence this command exists to not have, and widening
+ * `DriftKind` upstream turns the two total records below red until this file
+ * answers for the new kind.
+ */
+export type DiagnosisFindingKind = DriftKind
+/** Brambo has no registry document for this scope; nothing was initialised. */
+ | 'not-initialised'
+/** Brambo knows executors, and this machine has a configuration for none. */
+ | 'no-executor'
+/** Brambo's own registry document exists and cannot be read. */
+ | 'registry-unreadable'
+/**
+ * The registry document was written by a build NEWER than this one.
+ *
+ * Not `registry-unreadable`, and the split is the whole of spec M31.A: that
+ * kind's exit says *"Repair or remove that document"*, and this document is
+ * healthy — following the instruction destroys intact data. Brambo knows both
+ * version numbers, so it can name the one action that works. Routed on the
+ * store's CODE, never on its message text (AD-7).
+ */
+ | 'registry-version-ahead'
+/**
+ * A stored entry whose TYPE brambo has retired (story M4.E).
+ *
+ * Not `unprojectable`: that one is about an entry brambo still declares which
+ * no target happens to express, and it is reported per target because a target
+ * is what refused it. This one is about the REGISTRY holding a word brambo no
+ * longer has — no target ever saw it, so no target can report it, and the file
+ * it is about is brambo's own registry document.
+ */
+ | 'retired-type'
+/** Brambo's own ownership ledger cannot be read, or has lost records. */
+ | 'ledger-damaged'
+/** A projection warning with no more specific reading than its own code. */
+ | 'projection-warning'
+/**
+ * The bytes on disk differ from what projecting would produce.
+ *
+ * ponytail: FILE-level, not per entry. `ProjectionResult` reports THAT the
+ * merged text differs, never which entries account for the difference, so a
+ * per-entry answer here would have to be a second computation — the exact
+ * divergence this command exists to not have. Upgrade path: the engine
+ * surfaces the planned entries alongside `written` (deferred-work.md).
+ */
+ | 'out-of-date'
+/** Brambo would write here and the location refused a writability check. */
+ | 'not-writable'
+/** A registry entry this target cannot express (correction-01 C5). */
+ | 'unprojectable'
+/**
+ * Brambo's OWN prior output, still in a vendor file at a location no executor
+ * reads (correction-01 C6).
+ *
+ * Not drift: no ledger record claims it and no corrected build can produce it.
+ * It is litter a PREVIOUS build left, and until `brambo remediate discard`
+ * existed nothing in the product could take it back — which is why it was not
+ * reported before this story. A state brambo reports and cannot leave is
+ * exactly what M4.C exists to abolish, so the report and the exit ship
+ * together.
+ */
+ | 'legacy-block'
+/** This target could not be diagnosed at all; the others still were. */
+ | 'target-failed'
+/**
+ * A worktree removal that was interrupted between recording its intent and
+ * finishing it (spec M16.A, D3/D4).
+ *
+ * It is REPORTED here and resolved by a verb, never swept at startup: a sweep
+ * that removed on every process start would make brambo destructive on a run
+ * the user did not ask to be destructive — the same reasoning `remediate`
+ * rests on, which is why the exit below is a command rather than something
+ * this command performs.
+ *
+ * The leftovers arrive through {@link DiagnoseOptions.worktreeLeftovers}
+ * rather than being discovered here. `@skanl/brambo-environment` may not import a
+ * workspace implementation (`test/guard.test.ts`), and doctor may not open a
+ * file of its own; the caller that already holds the worktree capability
+ * hands the facts in, and this file phrases them — the same shape every other
+ * row here has, where `runScope` supplies and doctor words.
+ */
+ | 'worktree-leftover';
+/**
+ * Whether a finding is something WRONG or something merely true.
+ *
+ * The distinction exists because the exit code is a promise: a non-zero exit a
+ * user cannot ever get back to zero is not a diagnosis, it is a stuck light. A
+ * `tool` entry in the registry is an ordinary thing to register and is
+ * unprojectable by every executor permanently — reporting it is required
+ * (correction-01 C5), failing on it forever is not.
+ */
+export type DiagnosisFindingSeverity = 'problem' | 'info';
+/**
+ * One diagnosed problem, named so a user can act on it.
+ *
+ * The four locating fields are present EXACTLY when the finding is about them:
+ * an entry-level finding carries all four, a target-level one carries the
+ * executor and the file, a finding about brambo's own state carries the file
+ * alone, and a machine-level one carries none — which is why they are optional
+ * rather than filled with a placeholder that reads as a fact.
+ */
+export interface DiagnosisFinding {
+    readonly kind: DiagnosisFindingKind;
+    readonly severity: DiagnosisFindingSeverity;
+    /** The executor whose configuration this is about. */
+    readonly executorId?: string;
+    /** The file this is about — a vendor's own, or one of brambo's two. */
+    readonly filePath?: string;
+    /** Vendor-native location, e.g. `mcpServers.context7`. */
+    readonly location?: string;
+    readonly entryId?: string;
+    readonly detail: string;
+    /** What `brambo init` / `brambo project init` would do about it. */
+    readonly resolution: string;
+}
+/**
+ * What `brambo init` WOULD do about each kind — and only ever what brambo can
+ * itself perform. A `Record` over the closed kind union, so a kind added without
+ * an answer here does not compile: "each finding carries what brambo would do
+ * about it" is a type error away from being false, rather than a promise.
+ */
+export declare const RESOLUTION: Record<DiagnosisFindingKind, string>;
+/**
+ * How one reported state is LEFT. Three shapes, because they are three different
+ * promises and collapsing them is how a diagnosis starts lying:
+ *
+ *   `remediation`  — brambo performs it, named by the user, one at a time. These
+ *                    are the states whose only previous exit was hand-editing
+ *                    `~/.brambo/projection-ledger.json`.
+ *   `command`      — an existing brambo command already leaves this state.
+ *   `outside-brambo`— brambo cannot leave it and says what does. Naming a
+ *                    remediation here would be the same false promise the
+ *                    `out-of-date`/`not-writable` split was written to remove.
+ */
+export type FindingExit = {
+    readonly by: 'remediation';
+    readonly remediations: readonly RemediationKind[];
+    readonly detail: string;
+} | {
+    readonly by: 'command';
+    readonly command: string;
+    readonly detail: string;
+} | {
+    readonly by: 'outside-brambo';
+    readonly detail: string;
+};
+/**
+ * The exit for every state brambo reports — TOTAL over {@link DiagnosisFindingKind},
+ * so a finding kind added without one does not compile.
+ *
+ * IT LIVES IN DOCTOR, beside the kinds, and not beside `remediate` — because the
+ * first version put it beside the capability, nothing outside the tests consumed
+ * it, and `brambo doctor` went on printing *"brambo never overwrites an entry that
+ * changed since it wrote it; projecting again leaves your edit exactly as it is"*
+ * for four of the five states this story gave an exit to. The trap was closed in
+ * the code and left open on the only surface a user reads. Every `resolution`
+ * below is now composed from this record, so the product cannot know an exit the
+ * report does not print.
+ */
+export declare const FINDING_EXITS: Record<DiagnosisFindingKind, FindingExit>;
+/** Every kind this remediation is the named exit for. Derived, never listed. */
+export declare function findingKindsFor(remediation: RemediationKind): DiagnosisFindingKind[];
+/**
+ * Every kind, derived from a record TypeScript proves total. Exported for the
+ * tests that partition the kinds by what a finding of that kind must name — a
+ * hand-written list there would fall behind the union silently.
+ */
+export declare const DIAGNOSIS_FINDING_KINDS: readonly DiagnosisFindingKind[];
+/** What happened to ONE executor's configuration, in the read-only reading. */
+export interface DiagnosisTarget {
+    readonly executorId: string;
+    readonly targetId: string;
+    /** The vendor's own file, at the location that vendor reads. */
+    readonly filePath: string;
+    /** True when projecting WOULD change this file. Doctor changed nothing. */
+    readonly wouldWrite: boolean;
+    readonly drift: readonly DriftEntry[];
+    readonly unprojectable: readonly UnprojectableEntry[];
+    readonly error?: TargetFailure;
+}
+export interface Diagnosis {
+    readonly scope: 'machine' | 'project';
+    /** Brambo's own state directory for this scope. Doctor never creates it. */
+    readonly bramboDir: string;
+    /** This scope's registry document. Its absence is `not-initialised`. */
+    readonly registryPath: string;
+    readonly ledgerPath: string;
+    /** Registry entries the diagnosis read from, across every scope it can see. */
+    readonly entryCount: number;
+    /** EVERY executor brambo knows, found or not, with the paths consulted. */
+    readonly detected: readonly ExecutorDetection[];
+    readonly targets: readonly DiagnosisTarget[];
+    /**
+     * The same reading for each VERIFIED skills root. Separate from `targets`
+     * because `filePath` there names a file and here names a directory tree, and
+     * because a skills root is the one location where "projecting would change
+     * this" can mean brambo REMOVING something.
+     */
+    readonly skills: readonly DiagnosisTarget[];
+    /**
+     * Brambo's own prior output found in a vendor file (correction-01 C6). Every
+     * row here was produced by the `discard` remediation under INSPECTION, so the
+     * sentence reported is the sentence that remediation acts on.
+     */
+    readonly legacy: readonly LegacyBlock[];
+    readonly skipped: readonly SkippedExecutor[];
+    readonly warnings: readonly ProjectionWarning[];
+    /** Empty means clean. `severity: 'problem'` is what a non-zero exit answers for. */
+    readonly findings: readonly DiagnosisFinding[];
+}
+/**
+ * One interrupted worktree removal, as the caller who found it describes it.
+ *
+ * A STRUCTURAL shape, deliberately: `@skanl/brambo-environment` may not import the
+ * worktree implementation, and the one type both sides would otherwise share
+ * would have to live in `@skanl/brambo-contracts` — a third-party port surface, for a
+ * detail of one provider's own store. The caller holds the capability that
+ * discovers these; this file only phrases them.
+ */
+export interface WorktreeLeftover {
+    /** The workspace id, e.g. `w-3`. It is what the exit command takes. */
+    readonly id: string;
+    /** The tree the interrupted removal was working on. */
+    readonly path: string;
+    /** What the capability found, in its own words. */
+    readonly detail: string;
+}
+export interface DiagnoseOptions {
+    /** Defaults to the OS home directory. */
+    readonly homeDir?: string;
+    /** Read only for the project scope, where it defaults to `process.cwd()`. */
+    readonly projectDir?: string;
+    /** Defaults to `'machine'`, mirroring `brambo init`. */
+    readonly scope?: 'machine' | 'project';
+    /**
+     * Interrupted worktree removals the caller already found (spec M16.A, D4).
+     *
+     * Supplied rather than discovered, for the reason `WorktreeLeftover` gives.
+     * Absent means the caller did not look — which is NOT the same as "there are
+     * none", so nothing here reports an empty list as a clean bill of health; a
+     * caller that did look and found nothing simply produces no findings, exactly
+     * as it would for any other row.
+     */
+    readonly worktreeLeftovers?: readonly WorktreeLeftover[];
+}
+/** True when at least one finding is something wrong — the non-zero condition. */
+export declare function hasProblem(diagnosis: Diagnosis): boolean;
+/**
+ * Diagnoses one scope and writes nothing at all.
+ *
+ * A clean environment yields no findings; anything wrong yields at least one
+ * with `severity: 'problem'`, which is what lets a script branch on it.
+ * Reporting stops at the scope the caller named: doctor never goes looking for
+ * other projects brambo has bound.
+ */
+export declare function diagnose(options?: DiagnoseOptions): Promise<Diagnosis>;