youmd 0.10.0 → 0.10.2

package/dist/commands/brain.js

@@ -0,0 +1,683 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateBrainMapPaths = validateBrainMapPaths;
+exports.brainCommand = brainCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const render_1 = require("../lib/render");
+const brain_1 = require("../lib/brain");
+const apply_control_plane_1 = require("../lib/brain/apply-control-plane");
+const ACCENT = chalk_1.default.hex("#C46A3A");
+const DIM = chalk_1.default.dim;
+class BrainProposalInputError extends Error {
+    constructor() {
+        super(...arguments);
+        this.code = "PROJECT_BRAIN_PROPOSAL_INPUT_INVALID";
+    }
+}
+class BrainMapError extends Error {
+    constructor(code, safeMessage) {
+        super(safeMessage);
+        this.code = code;
+        this.safeMessage = safeMessage;
+        this.name = "BrainMapError";
+    }
+}
+function expandHome(value) {
+    if (value === "~")
+        return os.homedir();
+    if (value.startsWith(`~${path.sep}`) || value.startsWith("~/"))
+        return path.join(os.homedir(), value.slice(2));
+    return value;
+}
+function canonicalPath(value) {
+    const absolute = path.resolve(expandHome(value));
+    const missing = [];
+    let existing = absolute;
+    while (!fs.existsSync(existing)) {
+        const parent = path.dirname(existing);
+        if (parent === existing)
+            break;
+        missing.unshift(path.basename(existing));
+        existing = parent;
+    }
+    const canonicalExisting = fs.existsSync(existing) ? fs.realpathSync(existing) : existing;
+    return path.resolve(canonicalExisting, ...missing);
+}
+function pathsOverlap(left, right) {
+    const relative = path.relative(left, right);
+    return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== "..");
+}
+/** Validate before scanning so a map can never write into a source repository. */
+function validateBrainMapPaths(rootsValue, outValue) {
+    const roots = commaList(rootsValue)?.map(canonicalPath);
+    if (!roots?.length || !outValue?.trim()) {
+        throw new BrainMapError("PROJECT_BRAIN_MAP_OPTIONS_INVALID", "Brain mapping requires explicit --roots and --out values; nothing was written.");
+    }
+    const outDir = canonicalPath(outValue.trim());
+    for (const root of roots) {
+        if (pathsOverlap(root, outDir) || pathsOverlap(outDir, root)) {
+            throw new BrainMapError("PROJECT_BRAIN_MAP_OPTIONS_INVALID", "The brain map output must be disjoint from every scanned root; nothing was written.");
+        }
+    }
+    return { roots: [...new Set(roots)].sort((a, b) => a.localeCompare(b)), outDir };
+}
+function commaList(value) {
+    const items = value
+        ?.split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+    return items?.length ? items : undefined;
+}
+function isOpaqueHostedId(value) {
+    return typeof value === "string" && /^[A-Za-z0-9_-]{10,128}$/.test(value);
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function readinessReady(value) {
+    const record = asRecord(value);
+    const readiness = asRecord(record.readiness);
+    if (typeof readiness.ready === "boolean")
+        return readiness.ready;
+    if (typeof record.valid === "boolean")
+        return record.valid;
+    if (typeof record.ok === "boolean")
+        return record.ok;
+    if (record.kind === "project-brain-batch" && typeof readiness.status === "string") {
+        return !["cancelled", "unavailable"].includes(readiness.status);
+    }
+    return undefined;
+}
+function safeFailure(error) {
+    if (error instanceof BrainProposalInputError) {
+        return { code: error.code, message: "The proposal input is invalid or unsafe; nothing was changed." };
+    }
+    if (error instanceof brain_1.BrainSafeFileError) {
+        return { code: error.code, message: "The guarded Project Brain file operation failed safely; inspect the local apply journal before retrying." };
+    }
+    if (error instanceof brain_1.BrainStagedApplyError) {
+        return { code: error.code, message: "The staged Project Brain apply is unavailable, stale, unsafe, or already consumed; nothing was changed." };
+    }
+    if (error instanceof apply_control_plane_1.BrainApplyControlPlaneError) {
+        const message = error.phase === "claim"
+            ? "The server did not issue the exact guarded-apply claim; no repository file was changed."
+            : error.phase === "applying"
+                ? "The encrypted rollback journal was prepared, but the server did not accept applying; the repository file was not changed."
+                : error.phase === "applied"
+                    ? "The local patch was applied, but the server did not accept the applied receipt; inspect the local apply journal before continuing."
+                    : "The server did not accept the rollback-failure lifecycle receipt; the artifact remains frozen for manual recovery.";
+        return { code: error.code, message };
+    }
+    if (error instanceof BrainMapError) {
+        return { code: error.code, message: error.safeMessage };
+    }
+    if (error instanceof brain_1.BrainSafetyError) {
+        return {
+            code: "PROJECT_BRAIN_PERSISTENCE_REFUSED",
+            message: "The project brain safety gate rejected the payload; nothing was persisted.",
+        };
+    }
+    return {
+        code: "PROJECT_BRAIN_INTERNAL",
+        message: "The project brain operation failed; no repository state was changed.",
+    };
+}
+function readSafeJsonFile(fileValue, maxBytes = 1024 * 1024) {
+    const resolved = canonicalPath(fileValue);
+    let stat;
+    try {
+        stat = fs.lstatSync(resolved);
+    }
+    catch {
+        throw new BrainProposalInputError("proposal input is unavailable");
+    }
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > maxBytes)
+        throw new BrainProposalInputError("proposal input is unsafe");
+    const content = fs.readFileSync(resolved, "utf8");
+    try {
+        return { path: resolved, value: JSON.parse(content), content };
+    }
+    catch {
+        throw new BrainProposalInputError("proposal input is not JSON");
+    }
+}
+function readProposalCandidate(fileValue) {
+    const resolved = canonicalPath(fileValue);
+    let stat;
+    try {
+        stat = fs.lstatSync(resolved);
+    }
+    catch {
+        return null;
+    }
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024)
+        throw new BrainProposalInputError("proposal validation input is unsafe");
+    try {
+        const value = JSON.parse(fs.readFileSync(resolved, "utf8"));
+        return asRecord(value).kind === "project-brain-proposal" ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function proposalGenerationResult(type, generated) {
+    return {
+        schemaVersion: "you-md/project-brain-proposal-generation/v1",
+        kind: "project-brain-proposal-generation",
+        proposalType: type,
+        readiness: {
+            ready: generated.proposals.length > 0 && generated.errors.length === 0,
+            status: generated.proposals.length > 0 && generated.errors.length === 0 ? "ready" : "unavailable",
+            reason: generated.proposals.length > 0 ? undefined : "no_valid_proposal",
+        },
+        counts: { proposals: generated.proposals.length, errors: generated.errors.length },
+        proposals: generated.proposals,
+        errors: generated.errors,
+        applyAvailable: false,
+    };
+}
+function resultLabel(subcommand, value) {
+    const result = asRecord(value);
+    if (result.kind === "project-brain-batch") {
+        const count = Array.isArray(result.workspaces) ? result.workspaces.length : 0;
+        return `${subcommand} · ${count} workspace${count === 1 ? "" : "s"}`;
+    }
+    if (result.kind === "project-brain-map") {
+        const counts = asRecord(result.counts);
+        return `${subcommand} · ${counts.projects ?? 0} project${counts.projects === 1 ? "" : "s"}`;
+    }
+    const scan = asRecord(result.scan);
+    const scanRevision = asRecord(scan.revision);
+    const revision = typeof result.revision === "string"
+        ? result.revision
+        : typeof asRecord(result.brain).revision === "string"
+            ? String(asRecord(result.brain).revision)
+            : typeof scanRevision.digest === "string"
+                ? scanRevision.digest
+                : "";
+    const project = asRecord(result.project);
+    const projectName = typeof project.slug === "string"
+        ? project.slug
+        : typeof project.name === "string"
+            ? project.name
+            : typeof result.projectSlug === "string"
+                ? result.projectSlug
+                : "";
+    return [subcommand, projectName, revision ? revision.slice(0, 12) : ""]
+        .filter(Boolean)
+        .join(" · ");
+}
+function printBatchHuman(value) {
+    const result = asRecord(value);
+    const readiness = asRecord(result.readiness);
+    const workspaces = Array.isArray(result.workspaces) ? result.workspaces : [];
+    const status = typeof readiness.status === "string" ? readiness.status : "unavailable";
+    const failed = ["cancelled", "unavailable"].includes(status);
+    console.log("");
+    console.log("  " + chalk_1.default.bold("project brain") + DIM(` -- ${workspaces.length} workspace${workspaces.length === 1 ? "" : "s"}`));
+    console.log("");
+    console.log(`  ${failed ? ACCENT("×") : status === "degraded" ? ACCENT("!") : chalk_1.default.green("✓")} ${status}`);
+    console.log(`  ${DIM([
+        `total=${readiness.total ?? workspaces.length}`,
+        `ready=${readiness.ready ?? 0}`,
+        `degraded=${readiness.degraded ?? 0}`,
+        `unavailable=${readiness.unavailable ?? 0}`,
+    ].join("  "))}`);
+    console.log("");
+    for (const item of workspaces) {
+        const workspace = asRecord(item);
+        const workspaceReadiness = asRecord(workspace.readiness);
+        const workspaceStatus = typeof workspaceReadiness.status === "string" ? workspaceReadiness.status : "unavailable";
+        const projectRef = typeof workspace.projectRef === "string" ? workspace.projectRef : "project:unknown";
+        const workspaceRef = typeof workspace.workspaceRef === "string" ? workspace.workspaceRef : "workspace:unknown";
+        const revision = typeof workspace.revision === "string" ? workspace.revision : "";
+        const persistence = asRecord(workspace.persistence);
+        const persisted = Object.keys(persistence).length
+            ? persistence.written === true ? "written" : "unchanged"
+            : "memory-only";
+        console.log(`  ${workspaceStatus === "ready" ? chalk_1.default.green("✓") : ACCENT("!")} ${projectRef.replace(/^project:/, "")}`);
+        console.log(`    ${DIM(`${workspaceRef.slice(0, 28)}…  ${revision.slice(0, 20)}…  ${persisted}`)}`);
+    }
+    if (Array.isArray(result.diagnostics) && result.diagnostics.length) {
+        console.log("");
+        console.log(`  ${ACCENT(`${result.diagnostics.length} diagnostic(s)`)}`);
+    }
+    console.log("");
+}
+function printHumanResult(subcommand, value) {
+    const result = asRecord(value);
+    if (result.kind === "project-brain-batch") {
+        printBatchHuman(value);
+        return;
+    }
+    const scan = asRecord(result.scan);
+    const ready = readinessReady(value);
+    const label = resultLabel(subcommand, value);
+    console.log("");
+    console.log("  " + chalk_1.default.bold("project brain") + DIM(` -- ${label || subcommand}`));
+    console.log("");
+    const readiness = asRecord(result.readiness);
+    const status = typeof readiness.status === "string"
+        ? readiness.status
+        : ready === false ? "not ready" : ready === true ? "ready" : "complete";
+    console.log(`  ${ready === false ? ACCENT("×") : chalk_1.default.green("✓")} ${status}`);
+    const reason = typeof readiness.reason === "string" ? readiness.reason : undefined;
+    if (reason)
+        console.log(`    ${DIM(reason)}`);
+    const revision = typeof result.revision === "string"
+        ? result.revision
+        : typeof asRecord(scan.revision).digest === "string"
+            ? String(asRecord(scan.revision).digest)
+            : undefined;
+    if (revision)
+        console.log(`  ${DIM("revision")}  ${revision}`);
+    const outputPath = typeof result.path === "string"
+        ? result.path
+        : typeof result.outputPath === "string"
+            ? result.outputPath
+            : undefined;
+    if (outputPath)
+        console.log(`  ${DIM("path")}      ${outputPath}`);
+    const counts = asRecord(result.counts);
+    if (Object.keys(counts).length) {
+        const summary = Object.entries(counts)
+            .filter(([, count]) => typeof count === "number")
+            .map(([name, count]) => `${name}=${count}`)
+            .join("  ");
+        if (summary)
+            console.log(`  ${DIM(summary)}`);
+    }
+    if (Array.isArray(scan.projects))
+        console.log(`  ${DIM(`${scan.projects.length} project(s) indexed`)}`);
+    if (Array.isArray(result.diagnostics) && result.diagnostics.length) {
+        console.log(`  ${ACCENT(`${result.diagnostics.length} diagnostic(s)`)}`);
+    }
+    console.log("");
+}
+function printHelp() {
+    console.log("");
+    console.log("  " + chalk_1.default.bold("you brain") + DIM(" -- provenance-aware project truth catalog"));
+    console.log("");
+    console.log("  " + ACCENT("Commands"));
+    console.log("    " + chalk_1.default.cyan("scan") + DIM("      scan declared roots and atomically update the local brain"));
+    console.log("    " + chalk_1.default.cyan("map") + DIM("       render a portable project-brain catalog into a separate output repo"));
+    console.log("    " + chalk_1.default.cyan("adopt") + DIM("     propose a reviewable .you-project descriptor without writing it"));
+    console.log("    " + chalk_1.default.cyan("propose") + DIM("   import an overrides/notes JSON patch as an exact proposal"));
+    console.log("    " + chalk_1.default.cyan("stage") + DIM("     stage exact proposal/approval/root bindings for one native apply id"));
+    console.log("    " + chalk_1.default.cyan("apply") + DIM("     apply an approved, explicitly granted local artifact patch"));
+    console.log("    " + chalk_1.default.cyan("recover") + DIM("   recover an interrupted local apply from encrypted rollback"));
+    console.log("    " + chalk_1.default.cyan("validate") + DIM("  validate a manifest, snapshot, or current project brain"));
+    console.log("    " + chalk_1.default.cyan("show") + DIM("      read the latest or selected project brain snapshot"));
+    console.log("");
+    console.log("  " + DIM("Examples:"));
+    console.log("    " + chalk_1.default.cyan("you brain scan --roots ~/Desktop/CODE_2025,~/Desktop/CODE_YOU"));
+    console.log("    " + chalk_1.default.cyan("you brain map --roots ~/code/youmd,~/code/hubify --out ~/brain-repo"));
+    console.log("    " + chalk_1.default.cyan("you brain adopt --project legacy-app --json"));
+    console.log("    " + chalk_1.default.cyan("you brain propose --path overrides/legacy-app.json --json"));
+    console.log("    " + chalk_1.default.cyan("you brain stage --path proposal.json --proposal-id <hosted-id> --apply-id <id> --approval approval.json --root . --json"));
+    console.log("    " + chalk_1.default.cyan("you brain apply --path proposal.json --proposal-id <hosted-id> --apply-id <correlation-id> --approval approval.json --root . --json"));
+    console.log("    " + chalk_1.default.cyan("you brain recover --proposal-ref proposal:brain/... --project app --root . --json"));
+    console.log("    " + chalk_1.default.cyan("you brain validate --project youmd --json"));
+    console.log("    " + chalk_1.default.cyan("you brain show --project youmd --json"));
+    console.log("");
+}
+async function brainCommand(subcommand, args = [], options = {}) {
+    const command = subcommand?.trim().toLowerCase();
+    if (!command || command === "help" || command === "--help" || command === "-h") {
+        printHelp();
+        return;
+    }
+    if (!new Set(["scan", "map", "adopt", "propose", "stage", "apply", "recover", "validate", "show"]).has(command)) {
+        console.error(ACCENT(`unknown brain command: ${subcommand}`));
+        printHelp();
+        process.exitCode = 1;
+        return;
+    }
+    const spinner = options.json ? null : new render_1.BrailleSpinner(command === "scan"
+        ? "indexing project truth without touching its owners"
+        : command === "map"
+            ? "rendering a portable map from repository-owned truth"
+            : command === "adopt" || command === "propose"
+                ? "drafting an exact proposal without applying it"
+                : command === "stage" || command === "apply" || command === "recover"
+                    ? "checking grants, journal, and encrypted rollback boundaries"
+                    : command === "validate"
+                        ? "checking provenance and revision integrity"
+                        : "opening the latest trusted project snapshot");
+    spinner?.start();
+    try {
+        let result;
+        if (command === "scan") {
+            const roots = commaList(options.roots);
+            result = roots
+                ? await (0, brain_1.scanAllProjectBrains)({ roots, persist: options.persist !== false })
+                : await (0, brain_1.scanProjectBrain)({ project: options.project, persist: options.persist !== false });
+        }
+        else if (command === "map") {
+            const { roots, outDir } = validateBrainMapPaths(options.roots, options.out);
+            const batch = await (0, brain_1.scanAllProjectBrains)({ roots, persist: false });
+            if (batch.workspaces.length === 0 ||
+                batch.readiness.cancelled ||
+                ["cancelled", "unavailable"].includes(batch.readiness.status)) {
+                throw new BrainMapError("PROJECT_BRAIN_MAP_SCAN_UNAVAILABLE", "The project brain scan was unavailable, so no portable output was written.");
+            }
+            const rendered = (0, brain_1.renderPortableProjectBrainBatch)(batch);
+            const write = (0, brain_1.writePortableProjectBrainOutput)(rendered, outDir);
+            const projects = batch.workspaces
+                .map((workspace) => ({
+                projectRef: workspace.projectRef,
+                workspaceRef: workspace.workspaceRef,
+                revision: workspace.revision,
+            }))
+                .sort((a, b) => a.projectRef.localeCompare(b.projectRef)
+                || a.workspaceRef.localeCompare(b.workspaceRef)
+                || a.revision.localeCompare(b.revision));
+            result = {
+                schemaVersion: "you-md/project-brain-map/v1",
+                kind: "project-brain-map",
+                revision: rendered.revision,
+                readiness: {
+                    ...batch.readiness,
+                    ready: !batch.readiness.cancelled && batch.readiness.unavailable === 0,
+                },
+                counts: {
+                    projects: new Set(projects.map((project) => project.projectRef)).size,
+                    workspaces: projects.length,
+                    written: write.written.length,
+                    unchanged: write.unchanged.length,
+                    pruned: write.pruned.length,
+                },
+                projects,
+                files: write,
+            };
+        }
+        else if (command === "adopt") {
+            const scanned = await (0, brain_1.scanProjectBrain)({ project: options.project || args[0], persist: false });
+            const generated = (0, brain_1.proposeProjectBrainAdoption)(scanned.scan, {
+                projectRef: options.project ? `project:${options.project.replace(/^project:/, "")}` : undefined,
+                name: options.name,
+                rationale: options.rationale,
+            });
+            result = proposalGenerationResult("descriptor_adoption", generated);
+        }
+        else if (command === "propose") {
+            const requestedPath = options.path || args[0];
+            if (!requestedPath)
+                throw new BrainProposalInputError("proposal input path is required");
+            const source = readSafeJsonFile(requestedPath, 256 * 1024);
+            const sourcePath = path.relative(process.cwd(), source.path).split(path.sep).join("/");
+            const scanned = await (0, brain_1.scanProjectBrain)({ project: options.project, persist: false });
+            const generated = (0, brain_1.importProjectBrainOverrides)(scanned.scan, [{ sourcePath, content: source.content }]);
+            result = proposalGenerationResult("personal_override", generated);
+        }
+        else if (command === "stage") {
+            const proposalPath = options.path || args[0];
+            if (!proposalPath || !options.approval || !options.root
+                || !isOpaqueHostedId(options.proposalId) || !isOpaqueHostedId(options.applyId)) {
+                throw new BrainProposalInputError("staging requires exact proposal, approval, root, proposal id, and apply id inputs");
+            }
+            const proposalInput = readSafeJsonFile(proposalPath);
+            const proposalValidation = (0, brain_1.validateProjectBrainProposal)(proposalInput.value);
+            if (!proposalValidation.valid || !proposalValidation.proposal)
+                throw new BrainProposalInputError("proposal is invalid");
+            const approvalInput = readSafeJsonFile(options.approval, 256 * 1024);
+            const staged = (0, brain_1.stageProjectBrainApply)({
+                brainRoot: options.brainRoot,
+                proposalId: options.proposalId,
+                applyId: options.applyId,
+                root: canonicalPath(options.root),
+                proposalPath: proposalInput.path,
+                proposalContent: proposalInput.content,
+                proposal: proposalValidation.proposal,
+                approvalPath: approvalInput.path,
+                approvalContent: approvalInput.content,
+                approval: approvalInput.value,
+            });
+            result = {
+                schemaVersion: staged.schemaVersion,
+                kind: staged.kind,
+                status: staged.state,
+                proposalId: staged.proposalId,
+                applyId: staged.applyId,
+                proposalRef: staged.proposalRef,
+                rootPathHash: staged.rootPathHash,
+                proposalContentHash: staged.proposalContentHash,
+                approvalContentHash: staged.approvalContentHash,
+                createdAt: staged.createdAt,
+                expiresAt: staged.expiresAt,
+                secretValuesExposed: false,
+            };
+        }
+        else if (command === "apply") {
+            let proposalPath = options.path || args[0];
+            let approvalPath = options.approval;
+            let rootValue = options.root;
+            let stagedResolution;
+            if (options.applyId && !proposalPath && !approvalPath && !rootValue) {
+                if (!isOpaqueHostedId(options.proposalId) || !isOpaqueHostedId(options.applyId)) {
+                    throw new BrainProposalInputError("hosted proposal or apply correlation id is invalid");
+                }
+                stagedResolution = (0, brain_1.consumeProjectBrainStagedApply)({
+                    brainRoot: options.brainRoot,
+                    proposalId: options.proposalId,
+                    applyId: options.applyId,
+                });
+                proposalPath = stagedResolution.proposalPath;
+                approvalPath = stagedResolution.approvalPath;
+                rootValue = stagedResolution.root;
+            }
+            else if (options.applyId && (!proposalPath || !approvalPath || !rootValue)) {
+                throw new BrainProposalInputError("hosted apply correlation requires explicit proposal, approval, and repository root inputs");
+            }
+            if (!proposalPath || !approvalPath || !options.proposalId) {
+                throw new BrainProposalInputError("proposal, hosted proposal id, and approval paths are required");
+            }
+            if (!isOpaqueHostedId(options.proposalId) || (options.applyId !== undefined && !isOpaqueHostedId(options.applyId))) {
+                throw new BrainProposalInputError("hosted proposal or apply correlation id is invalid");
+            }
+            const proposalInput = readSafeJsonFile(proposalPath);
+            if (stagedResolution && `sha256:${(0, brain_1.sha256)(proposalInput.content)}` !== stagedResolution.proposalContentHash) {
+                throw new brain_1.BrainStagedApplyError("PROJECT_BRAIN_STAGE_STALE_HASH", "proposal changed after staged consumption");
+            }
+            const proposalValidation = (0, brain_1.validateProjectBrainProposal)(proposalInput.value);
+            if (!proposalValidation.valid || !proposalValidation.proposal)
+                throw new BrainProposalInputError("proposal is invalid");
+            const approvalInput = readSafeJsonFile(approvalPath, 256 * 1024);
+            if (stagedResolution && `sha256:${(0, brain_1.sha256)(approvalInput.content)}` !== stagedResolution.approvalContentHash) {
+                throw new brain_1.BrainStagedApplyError("PROJECT_BRAIN_STAGE_STALE_HASH", "approval changed after staged consumption");
+            }
+            const root = canonicalPath(rootValue || process.cwd());
+            const scanned = await (0, brain_1.scanProjectBrain)({
+                roots: [root],
+                project: proposalValidation.proposal.projectRef.replace(/^project:/, ""),
+                persist: false,
+            });
+            const proposal = proposalValidation.proposal;
+            const project = scanned.scan.projects.find((candidate) => candidate.projectRef === proposal.projectRef);
+            const artifact = project?.artifacts.find((candidate) => candidate.artifactRef === proposal.target.artifactRef);
+            const capability = artifact?.writePolicy === "managed_write" || artifact?.writePolicy === "task_write"
+                ? artifact.writePolicy
+                : null;
+            if (!capability || !proposal.target.path)
+                throw new BrainProposalInputError("proposal target lacks a local write grant");
+            const device = (0, brain_1.readProjectBrainTrustedDeviceIdentity)();
+            const grantCredential = options.applyId
+                ? (0, brain_1.deriveProjectBrainApplyCredential)(options.proposalId, options.applyId)
+                : undefined;
+            const claimInput = {
+                proposalId: options.proposalId,
+                claimNonce: (0, apply_control_plane_1.newProjectBrainApplyClaimNonce)(options.applyId),
+                deviceId: device.deviceId,
+                machineRef: proposal.machineRef,
+                workspaceRef: proposal.workspaceRef,
+                baseRevision: proposal.baseRevision,
+                baseContentHash: proposal.target.baseContentHash,
+                patchDigest: proposal.patchDigest,
+                targetPath: proposal.target.path,
+                capability,
+                secretValuesExposed: false,
+            };
+            const claim = grantCredential
+                ? await (0, apply_control_plane_1.claimBoundProjectBrainApply)(claimInput, { grantCredential })
+                : await (0, apply_control_plane_1.claimBoundProjectBrainApply)(claimInput);
+            let rollbackCiphertextHash;
+            let localResult;
+            try {
+                localResult = await (0, brain_1.applyProjectBrainSafeFile)({
+                    root,
+                    brainRoot: options.brainRoot,
+                    proposal,
+                    approval: approvalInput.value,
+                    scan: scanned.scan,
+                    onPrepared: async (evidence) => {
+                        rollbackCiphertextHash = evidence.rollbackCiphertextHash;
+                        await (0, apply_control_plane_1.recordBoundProjectBrainApplyEvent)({
+                            attemptId: claim.attemptId,
+                            grantCredential: claim.grantCredential,
+                            status: "applying",
+                            rollbackCiphertextHash: evidence.rollbackCiphertextHash,
+                            secretValuesExposed: false,
+                        }, claim.applyAttemptRef);
+                    },
+                });
+            }
+            catch (error) {
+                if (error instanceof brain_1.BrainSafeFileError && error.code === "PROJECT_BRAIN_ROLLBACK_FAILED" && rollbackCiphertextHash) {
+                    await (0, apply_control_plane_1.recordBoundProjectBrainApplyEvent)({
+                        attemptId: claim.attemptId,
+                        grantCredential: claim.grantCredential,
+                        status: "rollback_failed",
+                        rollbackCiphertextHash,
+                        failureCode: "rollback_failed",
+                        secretValuesExposed: false,
+                    }, claim.applyAttemptRef);
+                    await (0, apply_control_plane_1.recordBoundProjectBrainApplyEvent)({
+                        attemptId: claim.attemptId,
+                        grantCredential: claim.grantCredential,
+                        status: "manual_recovery_required",
+                        rollbackCiphertextHash,
+                        failureCode: "manual_recovery_required",
+                        secretValuesExposed: false,
+                    }, claim.applyAttemptRef);
+                }
+                throw error;
+            }
+            await (0, apply_control_plane_1.recordBoundProjectBrainApplyEvent)({
+                attemptId: claim.attemptId,
+                grantCredential: claim.grantCredential,
+                status: "applied",
+                resultContentHash: localResult.afterHash,
+                rollbackCiphertextHash: localResult.rollbackCiphertextHash,
+                secretValuesExposed: false,
+            }, claim.applyAttemptRef);
+            result = {
+                ...localResult,
+                serverClaim: {
+                    status: "applied",
+                    proposalId: options.proposalId,
+                    applyId: options.applyId,
+                    applyAttemptRef: claim.applyAttemptRef,
+                    grantRef: claim.grant.grantRef,
+                    applyingReported: true,
+                    appliedReported: true,
+                    secretValuesExposed: false,
+                },
+            };
+        }
+        else if (command === "recover") {
+            const proposalRef = options.proposalRef || args[0];
+            if (!proposalRef || !options.project)
+                throw new BrainProposalInputError("proposalRef and project are required for recovery");
+            const root = canonicalPath(options.root || process.cwd());
+            const stateRoot = options.brainRoot ? canonicalPath(options.brainRoot) : (0, brain_1.defaultBrainRoot)();
+            // Safe existence check also prevents recovery from accepting a fabricated ref.
+            readSafeJsonFile((0, brain_1.projectBrainApplyJournalPath)(stateRoot, proposalRef), 1024 * 1024);
+            const scanned = await (0, brain_1.scanProjectBrain)({ roots: [root], project: options.project, persist: false });
+            result = (0, brain_1.recoverProjectBrainSafeFile)({ root, brainRoot: stateRoot, proposalRef, scan: scanned.scan });
+        }
+        else if (command === "validate") {
+            const requestedPath = options.path || args[0];
+            if (requestedPath) {
+                const proposal = readProposalCandidate(requestedPath);
+                result = proposal
+                    ? (0, brain_1.validateProjectBrainProposal)(proposal)
+                    : await (0, brain_1.validateProjectBrain)({ path: requestedPath, project: options.project });
+            }
+            else
+                result = await (0, brain_1.validateProjectBrain)({ project: options.project });
+        }
+        else {
+            result = await (0, brain_1.showProjectBrain)({
+                project: options.project || args[0],
+                workspace: options.workspace,
+                revision: options.revision,
+            });
+        }
+        if (spinner)
+            spinner.stop(resultLabel(command, result));
+        if (options.json)
+            console.log(JSON.stringify(result, null, 2));
+        else
+            printHumanResult(command, result);
+        if (readinessReady(result) === false)
+            process.exitCode = 1;
+    }
+    catch (error) {
+        const failure = safeFailure(error);
+        if (spinner)
+            spinner.fail(failure.message);
+        if (options.json) {
+            console.log(JSON.stringify({
+                schemaVersion: "you-md/project-brain-error/v1",
+                command,
+                error: failure,
+            }, null, 2));
+        }
+        else {
+            console.error(`  ${ACCENT("brain command failed")} ${DIM(failure.message)}`);
+        }
+        process.exitCode = 1;
+    }
+}
+//# sourceMappingURL=brain.js.map