@skanl/brambo-environment 0.1.1

package/dist/remediate.d.ts

@@ -0,0 +1,51 @@
+import type { RemediationKind, RemediationOutcome, RemediationRefusal } from '@skanl/brambo-contracts';
+import type { ProjectionMode } from '@skanl/brambo-projection';
+import type { Diagnosis, DiagnosisFinding } from './doctor.ts';
+export interface RemediateOptions {
+    /** 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` and `brambo doctor`. */
+    readonly scope?: 'machine' | 'project';
+    readonly remediation: RemediationKind;
+    /** Narrows the finding; required whenever more than one would match. */
+    readonly executorId?: string;
+    readonly entryId?: string;
+    /**
+     * Defaults to `'inspect'` — the OPPOSITE default from `runProjection`, and
+     * deliberately so. A projection converges a machine a user asked brambo to
+     * manage; a remediation changes who owns what, and describing it first is the
+     * frozen requirement. A caller that wants the act asks for `'apply'`.
+     */
+    readonly mode?: ProjectionMode;
+}
+export interface RemediationReport {
+    readonly scope: 'machine' | 'project';
+    readonly remediation: RemediationKind;
+    readonly mode: ProjectionMode;
+    /** The finding acted on, exactly as `brambo doctor` reports it. */
+    readonly finding?: DiagnosisFinding;
+    readonly outcome?: RemediationOutcome;
+    /** Why brambo did not select a finding to act on. */
+    readonly refusal?: RemediationRefusal;
+    /**
+     * Every finding this remediation is the exit for, in this run. Present
+     * whenever the request matched none or more than one, because "name one of
+     * these" is only actionable if the user can see them.
+     */
+    readonly candidates: readonly DiagnosisFinding[];
+    /** The full diagnosis the selection was made from; nothing here is invented. */
+    readonly diagnosis: Diagnosis;
+}
+/**
+ * Describes — or, with `mode: 'apply'`, performs — exactly one remediation for
+ * exactly one finding this run reported.
+ *
+ * Nothing else is touched. `adopt` and `release` change only what brambo claims;
+ * `repair` rewrites only brambo's own ledger; `discard` removes only brambo's own
+ * prior output from one vendor file. No other entry, no other finding and no
+ * foreign neighbour is read or written, which is what makes "nothing unnamed is
+ * touched" a property of the design rather than a promise about the code.
+ */
+export declare function remediate(options: RemediateOptions): Promise<RemediationReport>;

package/dist/remediate.js

@@ -0,0 +1,140 @@
+import { homedir } from 'node:os';
+import { BRAMBO_ERROR_CODES, projectionTargetLocation } from '@skanl/brambo-contracts';
+import { ProjectionLedger, groupByKind, runRemediation } from '@skanl/brambo-projection';
+// The exit table lives in `doctor.ts`, beside the finding kinds it is total
+// over, and this file only ASKS it which kinds a verb resolves. Owning it here
+// is what shipped the first time, and the consequence was a product that printed
+// a terminal resolution for four states it could actually leave: the report and
+// the exit have to be one table.
+import { diagnose, findingKindsFor } from './doctor.js';
+import { EXECUTOR_PROFILES } from './executors.js';
+import { scopeDirectory, storeFor, targetsFor } from './init.js';
+function refusalOf(message) {
+    return { code: BRAMBO_ERROR_CODES.projectionRemediationRefused, message };
+}
+function describeFinding(found) {
+    const about = [found.executorId, found.entryId, found.location, found.filePath].filter((part) => part !== undefined);
+    return `${found.kind}${about.length === 0 ? '' : ` (${about.join(' · ')})`}`;
+}
+/** The target whose location a finding is about, out of the ones this scope runs. */
+function targetFor(finding, planned) {
+    return planned.find((candidate) => candidate.profile.executorId === finding.executorId &&
+        projectionTargetLocation(candidate.target) === finding.filePath)?.target;
+}
+/**
+ * Describes — or, with `mode: 'apply'`, performs — exactly one remediation for
+ * exactly one finding this run reported.
+ *
+ * Nothing else is touched. `adopt` and `release` change only what brambo claims;
+ * `repair` rewrites only brambo's own ledger; `discard` removes only brambo's own
+ * prior output from one vendor file. No other entry, no other finding and no
+ * foreign neighbour is read or written, which is what makes "nothing unnamed is
+ * touched" a property of the design rather than a promise about the code.
+ */
+export async function remediate(options) {
+    // Every caller-controlled field read ONCE, before the first await — the same
+    // TOCTOU rule `initMachine` and `diagnose` follow, and it decides here which
+    // machine gets written to.
+    const { homeDir = homedir(), projectDir, scope = 'machine', remediation, executorId, entryId, mode = 'inspect', } = options;
+    const home = await scopeDirectory('the home directory', homeDir);
+    const root = scope === 'machine'
+        ? home
+        : await scopeDirectory('the project directory', projectDir ?? process.cwd());
+    const diagnosis = await diagnose({ homeDir: home, projectDir: root, scope });
+    const base = { scope, remediation, mode, diagnosis };
+    const kinds = findingKindsFor(remediation);
+    if (kinds.length === 0) {
+        return {
+            ...base,
+            candidates: [],
+            refusal: refusalOf(`'${remediation}' is not the exit for any state brambo reports, so there is nothing it could be asked to do`),
+        };
+    }
+    const candidates = diagnosis.findings.filter((found) => kinds.includes(found.kind));
+    const selected = candidates.filter((found) => (executorId === undefined || found.executorId === executorId) &&
+        (entryId === undefined || found.entryId === entryId));
+    if (selected.length === 0) {
+        return {
+            ...base,
+            candidates,
+            refusal: refusalOf(candidates.length === 0
+                ? `brambo reported no ${kinds.join(' or ')} finding in this run, so there is nothing for '${remediation}' to resolve; brambo never remediates a state it did not just report`
+                : `no ${kinds.join(' or ')} finding in this run matches ${JSON.stringify({ executorId, entryId })}; brambo reported ${candidates.map(describeFinding).join(', ')}`),
+        };
+    }
+    if (selected.length > 1) {
+        return {
+            ...base,
+            candidates: selected,
+            refusal: refusalOf(`'${remediation}' resolves one finding at a time and ${selected.length} match: ${selected
+                .map(describeFinding)
+                .join(', ')}. Name one with --executor and --entry`),
+        };
+    }
+    const finding = selected[0];
+    const ledger = new ProjectionLedger({ homeDir: home });
+    if (remediation === 'repair') {
+        return { ...base, finding, candidates: [], outcome: await runRemediation({ remediation, ledger, mode }) };
+    }
+    if (remediation === 'discard') {
+        const profile = EXECUTOR_PROFILES.find((candidate) => candidate.executorId === finding.executorId);
+        const location = profile?.legacyConfig?.(home);
+        if (profile === undefined || location === undefined) {
+            return {
+                ...base,
+                finding,
+                candidates: [],
+                refusal: refusalOf(`brambo knows no location where a previous build could have written into '${finding.executorId ?? 'an unnamed executor'}'`),
+            };
+        }
+        return {
+            ...base,
+            finding,
+            candidates: [],
+            // `rootPath: home`, so the containment check in `runRemediation` is against
+            // the scope brambo was pointed at rather than against a path this file made
+            // up. A legacy location is machine-scoped by measurement (see the profile).
+            outcome: await runRemediation({
+                remediation,
+                legacy: { targetId: profile.targetId, rootPath: home, ...location },
+                mode,
+            }),
+        };
+    }
+    const { planned, skills } = targetsFor(scope, diagnosis.detected, home, root);
+    const target = targetFor(finding, [...planned, ...skills]);
+    if (target === undefined || finding.entryId === undefined) {
+        return {
+            ...base,
+            finding,
+            candidates: [],
+            refusal: refusalOf(`brambo could not tie ${describeFinding(finding)} back to one projection target and one registry entry, so it will not act on it`),
+        };
+    }
+    if (remediation === 'release') {
+        return {
+            ...base,
+            finding,
+            candidates: [],
+            outcome: await runRemediation({ remediation, target, entryId: finding.entryId, ledger, mode }),
+        };
+    }
+    // `adopt` alone needs the registry: the claim's paths come from the TARGET's
+    // own plan of what brambo would write, never from a directory listing, so a
+    // file the user put beside brambo's is not swept into a record that later
+    // authorises deleting it.
+    const store = storeFor(scope, home, root);
+    let entries;
+    try {
+        entries = groupByKind(await store.list());
+    }
+    finally {
+        await store.dispose();
+    }
+    return {
+        ...base,
+        finding,
+        candidates: [],
+        outcome: await runRemediation({ remediation, target, entryId: finding.entryId, entries, ledger, mode }),
+    };
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@skanl/brambo-environment",
+  "version": "0.1.1",
+  "description": "Executor detection, projection orchestration, and the diagnosis `brambo doctor` prints.",
+  "keywords": [
+    "ai-agent",
+    "brambo",
+    "doctor",
+    "diagnostics",
+    "environment"
+  ],
+  "homepage": "https://github.com/SKANL/brambo#readme",
+  "bugs": {
+    "url": "https://github.com/SKANL/brambo/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SKANL/brambo.git",
+    "directory": "packages/environment"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "brambo-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@skanl/brambo-contracts": "0.1.1",
+    "@skanl/brambo-kernel": "0.1.1",
+    "@skanl/brambo-projection": "0.1.1",
+    "@skanl/brambo-registry": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "typescript": "~7.0.2",
+    "vitest": "^4.1.11"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "build": "node ../../scripts/clean-dist.mjs && tsc -p tsconfig.build.json"
+  }
+}