@phren/cli 0.0.1

package/mcp/dist/index.js

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import * as fs from "fs";
+import * as path from "path";
+import { findPhrenPathWithArg, debugLog, runtimeDir, } from "./shared.js";
+import { log as structuredLog } from "./logger.js";
+import { buildIndex, updateFileInIndex as updateFileInIndexFn, } from "./shared-index.js";
+import { runCustomHooks } from "./hooks.js";
+import { register as registerSearch } from "./mcp-search.js";
+import { register as registerTask } from "./mcp-tasks.js";
+import { register as registerFinding } from "./mcp-finding.js";
+import { register as registerMemory } from "./mcp-memory.js";
+import { register as registerData } from "./mcp-data.js";
+import { register as registerGraph } from "./mcp-graph.js";
+import { register as registerSession } from "./mcp-session.js";
+import { register as registerOps } from "./mcp-ops.js";
+import { register as registerSkills } from "./mcp-skills.js";
+import { register as registerHooks } from "./mcp-hooks.js";
+import { register as registerExtract } from "./mcp-extract.js";
+import { register as registerConfig } from "./mcp-config.js";
+import { errorMessage } from "./utils.js";
+import { runTopLevelCommand } from "./entrypoint.js";
+import { startEmbeddingWarmup } from "./startup-embedding.js";
+import { resolveRuntimeProfile } from "./runtime-profile.js";
+import { VERSION as PACKAGE_VERSION } from "./package-metadata.js";
+const handledTopLevelCommand = await runTopLevelCommand(process.argv.slice(2));
+// MCP mode: first non-flag arg is the phren path. Resolve it lazily so CLI commands
+// like `maintain` are not misinterpreted as a filesystem path after the command has run.
+const phrenArg = handledTopLevelCommand ? undefined : process.argv.find((a, i) => i >= 2 && !a.startsWith("-"));
+const phrenPath = handledTopLevelCommand ? "" : findPhrenPathWithArg(phrenArg);
+const STALE_LOCK_MS = 120_000; // 2 min — slightly above EXEC_TIMEOUT_MS (30s) to avoid blocking healthy writers
+function cleanStaleLocks(phrenPath) {
+    const dir = runtimeDir(phrenPath);
+    try {
+        if (!fs.existsSync(dir))
+            return;
+        for (const entry of fs.readdirSync(dir)) {
+            if (!entry.endsWith(".lock"))
+                continue;
+            const lockPath = path.join(dir, entry);
+            try {
+                const stat = fs.statSync(lockPath);
+                if (Date.now() - stat.mtimeMs > STALE_LOCK_MS) {
+                    fs.unlinkSync(lockPath);
+                    debugLog(`Cleaned stale lock: ${entry}`);
+                }
+            }
+            catch (err) {
+                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                    process.stderr.write(`[phren] cleanStaleLocks statFile: ${errorMessage(err)}\n`);
+            }
+        }
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] cleanStaleLocks readdir: ${errorMessage(err)}\n`);
+    }
+}
+async function main() {
+    const profile = resolveRuntimeProfile(phrenPath);
+    cleanStaleLocks(phrenPath);
+    let db = null;
+    let indexReady = false;
+    try {
+        db = await buildIndex(phrenPath, profile);
+        indexReady = true;
+        // Load embedding cache and kick off background embedding (fire-and-forget)
+        const { getEmbeddingCache } = await import("./shared-embedding-cache.js");
+        const embCache = getEmbeddingCache(phrenPath);
+        void startEmbeddingWarmup(db, embCache);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        structuredLog("error", "startup", `Failed to build phren index: ${msg}`);
+        console.error("Failed to build phren index at startup:", error);
+        process.exit(1);
+    }
+    let writeQueue = Promise.resolve();
+    let writeQueueDepth = 0;
+    const MAX_QUEUE_DEPTH = 50;
+    const WRITE_TIMEOUT_MS = 30_000;
+    async function rebuildIndex() {
+        runCustomHooks(phrenPath, "pre-index");
+        indexReady = false;
+        try {
+            db?.close();
+        }
+        catch (err) {
+            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                process.stderr.write(`[phren] rebuildIndex dbClose: ${errorMessage(err)}\n`);
+        }
+        db = await buildIndex(phrenPath, profile);
+        indexReady = true;
+        runCustomHooks(phrenPath, "post-index");
+    }
+    async function withWriteQueue(fn) {
+        if (writeQueueDepth >= MAX_QUEUE_DEPTH) {
+            throw new Error(`Write queue full (${MAX_QUEUE_DEPTH} items). Try again shortly.`);
+        }
+        writeQueueDepth++;
+        const run = writeQueue.then(async () => {
+            try {
+                return await Promise.race([
+                    fn(),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error("Write timeout after 30s")), WRITE_TIMEOUT_MS))
+                ]);
+            }
+            catch (err) {
+                const message = errorMessage(err);
+                if (message.includes("Write timeout") || message.includes("Write queue full")) {
+                    debugLog(`Write queue timeout: ${message}`);
+                    return { ok: false, error: `Write queue timeout: ${message}`, errorCode: "TIMEOUT" };
+                }
+                throw err;
+            }
+            finally {
+                writeQueueDepth = Math.max(0, writeQueueDepth - 1);
+            }
+        });
+        writeQueue = run.then(() => undefined).catch((error) => {
+            try {
+                const message = error instanceof Error
+                    ? error.stack || error.message
+                    : String(error);
+                debugLog(`Write queue error: ${message}`);
+            }
+            catch (logError) {
+                const message = logError instanceof Error ? logError.message : String(logError);
+                structuredLog("error", "write-queue", `Failed to log write queue error: ${message}`);
+            }
+        });
+        return run;
+    }
+    const server = new McpServer({
+        name: "phren-mcp",
+        version: PACKAGE_VERSION,
+    });
+    // Track MCP tool calls for telemetry (opt-in only, best-effort)
+    const { trackToolCall } = await import("./telemetry.js");
+    const origRegisterTool = server.registerTool.bind(server);
+    server.registerTool = function (name, config, handler) {
+        const registeredName = name;
+        const wrapped = async (...args) => {
+            if (!indexReady || !db) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                ok: false,
+                                error: "Index unavailable - check phren setup",
+                            }, null, 2),
+                        }],
+                };
+            }
+            try {
+                trackToolCall(phrenPath, registeredName);
+            }
+            catch (err) {
+                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                    process.stderr.write(`[phren] trackToolCall: ${errorMessage(err)}\n`);
+            }
+            return handler(...args);
+        };
+        return origRegisterTool(registeredName, config, wrapped);
+    };
+    // Register all tool handlers from domain modules
+    const ctx = {
+        phrenPath,
+        profile,
+        db: () => {
+            if (!db)
+                throw new Error("Index unavailable - check phren setup");
+            return db;
+        },
+        rebuildIndex,
+        withWriteQueue,
+        updateFileInIndex: (filePath) => {
+            if (!db)
+                throw new Error("Index unavailable - check phren setup");
+            updateFileInIndexFn(db, filePath, phrenPath);
+        },
+    };
+    registerSearch(server, ctx);
+    registerTask(server, ctx);
+    registerFinding(server, ctx);
+    registerMemory(server, ctx);
+    registerData(server, ctx);
+    registerGraph(server, ctx);
+    registerSession(server, ctx);
+    registerOps(server, ctx);
+    registerSkills(server, ctx);
+    registerHooks(server, ctx);
+    registerExtract(server, ctx);
+    registerConfig(server, ctx);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`phren-mcp running (${phrenPath})`);
+}
+if (!handledTopLevelCommand) {
+    main().catch((err) => {
+        console.error("Failed to start phren-mcp:", err);
+        process.exit(1);
+    });
+}

package/mcp/dist/init-config.js

@@ -0,0 +1,336 @@
+/**
+ * Provider-specific MCP configuration backends.
+ * Handles IDE/tool config files for Claude, VS Code, Cursor, Copilot CLI, and Codex.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { randomUUID } from "crypto";
+import { execFileSync } from "child_process";
+import { buildLifecycleCommands } from "./hooks.js";
+import { EXEC_TIMEOUT_QUICK_MS, isRecord, hookConfigPath, homePath, readRootManifest, } from "./shared.js";
+import { isFeatureEnabled, errorMessage } from "./utils.js";
+import { probeVsCodeConfig, resolveCodexMcpConfig, resolveCopilotMcpConfig, resolveCursorMcpConfig, } from "./provider-adapters.js";
+import { getMcpEnabledPreference, getHooksEnabledPreference } from "./init-preferences.js";
+import { resolveEntryScript, VERSION } from "./init-shared.js";
+function log(msg) {
+    process.stdout.write(msg + "\n");
+}
+function getObjectProp(value, key) {
+    const candidate = value[key];
+    return isRecord(candidate) ? candidate : undefined;
+}
+function atomicWriteText(filePath, content) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tmpPath = `${filePath}.tmp-${randomUUID()}`;
+    fs.writeFileSync(tmpPath, content);
+    fs.renameSync(tmpPath, filePath);
+}
+export function patchJsonFile(filePath, patch) {
+    let data = {};
+    if (fs.existsSync(filePath)) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+            if (!isRecord(parsed))
+                throw new Error("top-level JSON value must be an object");
+            data = parsed;
+        }
+        catch (err) {
+            throw new Error(`Malformed JSON in ${filePath}: ${errorMessage(err)}`);
+        }
+    }
+    else {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    }
+    patch(data);
+    atomicWriteText(filePath, JSON.stringify(data, null, 2) + "\n");
+}
+function commandExists(cmd) {
+    try {
+        const whichCmd = process.platform === "win32" ? "where.exe" : "which";
+        execFileSync(whichCmd, [cmd], { stdio: ["ignore", "ignore", "ignore"], timeout: EXEC_TIMEOUT_QUICK_MS });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function buildMcpServerConfig(phrenPath) {
+    const entryScript = resolveEntryScript();
+    if (entryScript && fs.existsSync(entryScript)) {
+        return {
+            command: "node",
+            args: [entryScript, phrenPath],
+        };
+    }
+    return {
+        command: "npx",
+        args: ["-y", `phren@${VERSION}`, phrenPath],
+    };
+}
+function upsertMcpServer(data, mcpEnabled, preferredRoot, phrenPath) {
+    const knownRoots = ["mcpServers", "servers"];
+    const hadMcp = knownRoots.some((key) => Boolean(getObjectProp(data, key)?.phren));
+    if (mcpEnabled) {
+        let preferredRootValue = getObjectProp(data, preferredRoot);
+        if (!preferredRootValue) {
+            preferredRootValue = {};
+            data[preferredRoot] = preferredRootValue;
+        }
+        preferredRootValue.phren = buildMcpServerConfig(phrenPath);
+        return hadMcp ? "already_configured" : "installed";
+    }
+    for (const key of knownRoots) {
+        const root = getObjectProp(data, key);
+        if (root?.phren)
+            delete root.phren;
+    }
+    return hadMcp ? "disabled" : "already_disabled";
+}
+function configureMcpAtPath(filePath, mcpEnabled, preferredRoot, phrenPath) {
+    if (!mcpEnabled && !fs.existsSync(filePath))
+        return "already_disabled";
+    let status = "already_disabled";
+    patchJsonFile(filePath, (data) => {
+        status = upsertMcpServer(data, mcpEnabled, preferredRoot, phrenPath);
+    });
+    return status;
+}
+/**
+ * Read/write a TOML config file to upsert or remove [mcp_servers.phren].
+ * Lightweight: preserves all other content, only touches the phren section.
+ */
+function patchTomlMcpServer(filePath, mcpEnabled, phrenPath) {
+    let content = "";
+    const existed = fs.existsSync(filePath);
+    if (existed) {
+        content = fs.readFileSync(filePath, "utf8");
+    }
+    else if (!mcpEnabled) {
+        return "already_disabled";
+    }
+    const cfg = buildMcpServerConfig(phrenPath);
+    const escToml = (s) => s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    const argsToml = "[" + cfg.args.map((a) => `"${escToml(a)}"`).join(", ") + "]";
+    const newSection = `[mcp_servers.phren]\ncommand = "${escToml(cfg.command)}"\nargs = ${argsToml}\nstartup_timeout_sec = 30`;
+    const sectionRe = /^\[mcp_servers\.phren\]\s*\n(?:(?!\[)[^\n]*\n?)*/m;
+    const hadSection = sectionRe.test(content);
+    if (mcpEnabled) {
+        if (hadSection) {
+            content = content.replace(sectionRe, newSection + "\n");
+            atomicWriteText(filePath, content);
+            return "already_configured";
+        }
+        if (!existed) {
+            fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        }
+        const sep = content.length > 0 && !content.endsWith("\n\n") ? (content.endsWith("\n") ? "\n" : "\n\n") : "";
+        content += sep + newSection + "\n";
+        atomicWriteText(filePath, content);
+        return "installed";
+    }
+    if (!hadSection)
+        return "already_disabled";
+    content = content.replace(sectionRe, "");
+    content = content.replace(/\n{3,}/g, "\n\n");
+    atomicWriteText(filePath, content);
+    return "disabled";
+}
+export function removeTomlMcpServer(filePath) {
+    if (!fs.existsSync(filePath))
+        return false;
+    let content = fs.readFileSync(filePath, "utf8");
+    const sectionRe = /^\[mcp_servers\.phren\]\s*\n(?:(?!\[)[^\n]*\n?)*/m;
+    if (!sectionRe.test(content))
+        return false;
+    content = content.replace(sectionRe, "").replace(/\n{3,}/g, "\n\n");
+    atomicWriteText(filePath, content);
+    return true;
+}
+export function removeMcpServerAtPath(filePath) {
+    if (!fs.existsSync(filePath))
+        return false;
+    let removed = false;
+    patchJsonFile(filePath, (data) => {
+        for (const key of ["mcpServers", "servers"]) {
+            const root = data[key];
+            if (isRecord(root) && root.phren) {
+                delete root.phren;
+                removed = true;
+            }
+        }
+    });
+    return removed;
+}
+export function isPhrenCommand(command) {
+    // Detect PHREN_PATH= or legacy PHREN_PATH= env var prefix (present in all lifecycle hook commands)
+    if (/\b(?:PHREN_PATH|PHREN_PATH)=/.test(command))
+        return true;
+    // Detect npx phren/phren package references
+    if (command.includes("phren") || command.includes("phren"))
+        return true;
+    // Detect bare "phren" or "phren" executable segment
+    const segments = command.split(/[/\\\s]+/);
+    if (segments.some(seg => seg === "phren" || seg.startsWith("phren@") || seg === "phren" || seg.startsWith("phren@")))
+        return true;
+    // Also match commands that include hook subcommands (used when installed via absolute path)
+    const HOOK_MARKERS = ["hook-prompt", "hook-stop", "hook-session-start", "hook-tool"];
+    if (HOOK_MARKERS.some(m => command.includes(m)))
+        return true;
+    return false;
+}
+export function configureClaude(phrenPath, opts = {}) {
+    const settingsPath = hookConfigPath("claude");
+    const claudeJsonPath = homePath(".claude.json");
+    const entryScript = resolveEntryScript();
+    const mcpEnabled = opts.mcpEnabled ?? getMcpEnabledPreference(phrenPath);
+    const hooksEnabled = opts.hooksEnabled ?? getHooksEnabledPreference(phrenPath);
+    const lifecycle = buildLifecycleCommands(phrenPath);
+    let status = "already_disabled";
+    if (fs.existsSync(claudeJsonPath)) {
+        patchJsonFile(claudeJsonPath, (data) => {
+            status = upsertMcpServer(data, mcpEnabled, "mcpServers", phrenPath);
+        });
+    }
+    patchJsonFile(settingsPath, (data) => {
+        const settingsStatus = upsertMcpServer(data, mcpEnabled, "mcpServers", phrenPath);
+        if (status === "already_disabled")
+            status = settingsStatus;
+        const hooksMap = isRecord(data.hooks) ? data.hooks : (data.hooks = {});
+        const upsertPhrenHook = (eventName, hookBody) => {
+            if (!Array.isArray(hooksMap[eventName]))
+                hooksMap[eventName] = [];
+            const eventHooks = hooksMap[eventName];
+            const marker = eventName === "UserPromptSubmit" ? "hook-prompt"
+                : eventName === "Stop" ? "hook-stop"
+                    : eventName === "PostToolUse" ? "hook-tool"
+                        : "hook-session-start";
+            // Find the HookEntry containing a phren hook command
+            const existingEntryIdx = eventHooks.findIndex((h) => h?.hooks?.some((hook) => typeof hook?.command === "string" &&
+                (hook.command.includes(marker) ||
+                    isPhrenCommand(hook.command))));
+            if (existingEntryIdx >= 0) {
+                // Only rewrite the matching inner hook item; preserve sibling non-phren hooks
+                const entry = eventHooks[existingEntryIdx];
+                const innerIdx = (entry.hooks ?? []).findIndex((hook) => typeof hook?.command === "string" &&
+                    (hook.command.includes(marker) ||
+                        isPhrenCommand(hook.command)));
+                if (innerIdx >= 0 && entry.hooks) {
+                    entry.hooks[innerIdx] = hookBody;
+                }
+                else {
+                    // No matching inner hook found; append our hook body
+                    if (!entry.hooks)
+                        entry.hooks = [];
+                    entry.hooks.push(hookBody);
+                }
+            }
+            else {
+                eventHooks.push({ matcher: "", hooks: [hookBody] });
+            }
+        };
+        const toolHookEnabled = hooksEnabled && (isFeatureEnabled("PHREN_FEATURE_TOOL_HOOK", false) || isFeatureEnabled("PHREN_FEATURE_TOOL_HOOK", false));
+        if (hooksEnabled) {
+            upsertPhrenHook("UserPromptSubmit", {
+                type: "command",
+                command: lifecycle.userPromptSubmit || `node "${entryScript}" hook-prompt`,
+                timeout: 3,
+            });
+            upsertPhrenHook("Stop", {
+                type: "command",
+                command: lifecycle.stop,
+            });
+            upsertPhrenHook("SessionStart", {
+                type: "command",
+                command: lifecycle.sessionStart,
+            });
+            if (toolHookEnabled) {
+                upsertPhrenHook("PostToolUse", {
+                    type: "command",
+                    command: lifecycle.hookTool,
+                });
+            }
+        }
+        else {
+            for (const hookEvent of ["UserPromptSubmit", "Stop", "SessionStart", "PostToolUse"]) {
+                const hooks = hooksMap[hookEvent];
+                if (!Array.isArray(hooks))
+                    continue;
+                hooksMap[hookEvent] = hooks.filter((h) => !h.hooks?.some((hook) => typeof hook.command === "string" && isPhrenCommand(hook.command)));
+            }
+        }
+    });
+    return status;
+}
+let _vscodeProbeCache = null;
+/** Reset the VS Code path probe cache (for testing). */
+export function resetVSCodeProbeCache() { _vscodeProbeCache = null; }
+function probeVSCodePath() {
+    if (_vscodeProbeCache)
+        return _vscodeProbeCache;
+    _vscodeProbeCache = probeVsCodeConfig(commandExists);
+    return _vscodeProbeCache;
+}
+export function configureVSCode(phrenPath, opts = {}) {
+    const mcpEnabled = opts.mcpEnabled ?? getMcpEnabledPreference(phrenPath);
+    if (opts.scope === "workspace") {
+        const manifest = readRootManifest(phrenPath);
+        if (manifest?.installMode !== "project-local" || !manifest.workspaceRoot)
+            return "no_vscode";
+        const mcpFile = path.join(manifest.workspaceRoot, ".vscode", "mcp.json");
+        return configureMcpAtPath(mcpFile, mcpEnabled, "servers", "${workspaceFolder}/.phren");
+    }
+    const probe = probeVSCodePath();
+    if (!probe.installed || !probe.targetDir)
+        return "no_vscode";
+    const mcpFile = path.join(probe.targetDir, "mcp.json");
+    return configureMcpAtPath(mcpFile, mcpEnabled, "servers", phrenPath);
+}
+export function configureCursorMcp(phrenPath, opts = {}) {
+    const mcpEnabled = opts.mcpEnabled ?? getMcpEnabledPreference(phrenPath);
+    const resolved = resolveCursorMcpConfig(commandExists);
+    if (!resolved.installed)
+        return "no_cursor";
+    return configureMcpAtPath(resolved.target, mcpEnabled, "mcpServers", phrenPath);
+}
+export function configureCopilotMcp(phrenPath, opts = {}) {
+    const mcpEnabled = opts.mcpEnabled ?? getMcpEnabledPreference(phrenPath);
+    const resolved = resolveCopilotMcpConfig(commandExists);
+    if (!resolved.installed)
+        return "no_copilot";
+    let status = "already_disabled";
+    if (resolved.hasCliDir) {
+        status = configureMcpAtPath(resolved.cliConfig, mcpEnabled, "mcpServers", phrenPath);
+    }
+    if (resolved.existing && resolved.existing !== resolved.cliConfig) {
+        status = configureMcpAtPath(resolved.existing, mcpEnabled, "mcpServers", phrenPath);
+    }
+    if (!resolved.hasCliDir && !resolved.existing) {
+        status = configureMcpAtPath(resolved.cliConfig, mcpEnabled, "mcpServers", phrenPath);
+    }
+    return status;
+}
+export function configureCodexMcp(phrenPath, opts = {}) {
+    const mcpEnabled = opts.mcpEnabled ?? getMcpEnabledPreference(phrenPath);
+    const resolved = resolveCodexMcpConfig(phrenPath, commandExists);
+    if (!resolved.installed)
+        return "no_codex";
+    if (resolved.preferToml) {
+        return patchTomlMcpServer(resolved.tomlPath, mcpEnabled, phrenPath);
+    }
+    return configureMcpAtPath(resolved.existingJson, mcpEnabled, "mcpServers", phrenPath);
+}
+export function logMcpTargetStatus(tool, status, phase = "Configured") {
+    const text = {
+        installed: `${phase} ${tool} MCP`,
+        already_configured: `${tool} MCP already configured`,
+        disabled: `${tool} MCP disabled`,
+        already_disabled: `${tool} MCP already disabled`,
+        no_settings: `${tool} settings not found`,
+        no_vscode: `${tool} not detected`,
+        no_cursor: `${tool} not detected`,
+        no_copilot: `${tool} not detected`,
+        no_codex: `${tool} not detected`,
+    };
+    if (text[status])
+        log(`  ${text[status]}`);
+}

package/mcp/dist/init-preferences.js

@@ -0,0 +1,62 @@
+/**
+ * Install preferences: MCP/hooks mode, version tracking.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import * as crypto from "crypto";
+import { debugLog, installPreferencesFile } from "./phren-paths.js";
+import { errorMessage } from "./utils.js";
+function preferencesFile(phrenPath) {
+    return installPreferencesFile(phrenPath);
+}
+export function governanceInstallPreferencesFile(phrenPath) {
+    return path.join(phrenPath, ".governance", "install-preferences.json");
+}
+function readPreferencesFile(file) {
+    if (!fs.existsSync(file))
+        return {};
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch (err) {
+        debugLog(`readInstallPreferences: failed to parse ${file}: ${errorMessage(err)}`);
+        return {};
+    }
+}
+function writePreferencesFile(file, current, patch) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmpPath = `${file}.tmp-${crypto.randomUUID()}`;
+    fs.writeFileSync(tmpPath, JSON.stringify({
+        ...current,
+        ...patch,
+        updatedAt: new Date().toISOString(),
+    }, null, 2) + "\n");
+    fs.renameSync(tmpPath, file);
+}
+export function readInstallPreferences(phrenPath) {
+    return readPreferencesFile(preferencesFile(phrenPath));
+}
+export function readGovernanceInstallPreferences(phrenPath) {
+    return readPreferencesFile(governanceInstallPreferencesFile(phrenPath));
+}
+export function writeInstallPreferences(phrenPath, patch) {
+    writePreferencesFile(preferencesFile(phrenPath), readInstallPreferences(phrenPath), patch);
+}
+export function writeGovernanceInstallPreferences(phrenPath, patch) {
+    writePreferencesFile(governanceInstallPreferencesFile(phrenPath), readGovernanceInstallPreferences(phrenPath), patch);
+}
+export function getMcpEnabledPreference(phrenPath) {
+    const prefs = readInstallPreferences(phrenPath);
+    return prefs.mcpEnabled !== false;
+}
+export function setMcpEnabledPreference(phrenPath, enabled) {
+    writeInstallPreferences(phrenPath, { mcpEnabled: enabled });
+}
+export function getHooksEnabledPreference(phrenPath) {
+    const prefs = readInstallPreferences(phrenPath);
+    return prefs.hooksEnabled !== false;
+}
+export function setHooksEnabledPreference(phrenPath, enabled) {
+    writeInstallPreferences(phrenPath, { hooksEnabled: enabled });
+}