@phren/cli 0.0.28 → 0.0.33

package/mcp/dist/init-env.js

@@ -0,0 +1,114 @@
+/**
+ * Environment flags, onboarding preferences, and repair asset helpers for init.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import * as crypto from "crypto";
+import { writeInstallPreferences, writeGovernanceInstallPreferences, } from "./init/preferences.js";
+import { updateWorkflowPolicy } from "./shared/governance.js";
+import { ensureGitignoreEntry, upsertProjectEnvVar, } from "./init/setup.js";
+export function applyOnboardingPreferences(phrenPath, opts) {
+    if (opts.projectOwnershipDefault) {
+        writeInstallPreferences(phrenPath, { projectOwnershipDefault: opts.projectOwnershipDefault });
+    }
+    const runtimePatch = {};
+    if (opts.findingsProactivity)
+        runtimePatch.proactivityFindings = opts.findingsProactivity;
+    if (opts.taskProactivity)
+        runtimePatch.proactivityTask = opts.taskProactivity;
+    if (Object.keys(runtimePatch).length > 0) {
+        writeInstallPreferences(phrenPath, runtimePatch);
+    }
+    const governancePatch = {};
+    if (opts.findingsProactivity)
+        governancePatch.proactivityFindings = opts.findingsProactivity;
+    if (opts.taskProactivity)
+        governancePatch.proactivityTask = opts.taskProactivity;
+    if (Object.keys(governancePatch).length > 0) {
+        writeGovernanceInstallPreferences(phrenPath, governancePatch);
+    }
+    const workflowPatch = {};
+    if (typeof opts.lowConfidenceThreshold === "number")
+        workflowPatch.lowConfidenceThreshold = opts.lowConfidenceThreshold;
+    if (Array.isArray(opts.riskySections))
+        workflowPatch.riskySections = opts.riskySections;
+    if (opts.taskMode)
+        workflowPatch.taskMode = opts.taskMode;
+    if (opts.findingSensitivity)
+        workflowPatch.findingSensitivity = opts.findingSensitivity;
+    if (Object.keys(workflowPatch).length > 0) {
+        updateWorkflowPolicy(phrenPath, workflowPatch);
+    }
+}
+export function writeWalkthroughEnvDefaults(phrenPath, opts) {
+    const envFile = path.join(phrenPath, ".env");
+    let envContent = fs.existsSync(envFile) ? fs.readFileSync(envFile, "utf8") : "# phren feature flags — generated by init\n";
+    const envFlags = [];
+    const autoCaptureChoice = opts._walkthroughAutoCapture;
+    const hasAutoCaptureFlag = /^\s*PHREN_FEATURE_AUTO_CAPTURE=.*$/m.test(envContent);
+    if (typeof autoCaptureChoice === "boolean") {
+        envFlags.push({
+            flag: `PHREN_FEATURE_AUTO_CAPTURE=${autoCaptureChoice ? "1" : "0"}`,
+            label: `Auto-capture ${autoCaptureChoice ? "enabled" : "disabled"}`,
+        });
+    }
+    else if (!hasAutoCaptureFlag) {
+        // Default to enabled on fresh installs and non-walkthrough init.
+        envFlags.push({ flag: "PHREN_FEATURE_AUTO_CAPTURE=1", label: "Auto-capture enabled" });
+    }
+    if (opts._walkthroughSemanticDedup)
+        envFlags.push({ flag: "PHREN_FEATURE_SEMANTIC_DEDUP=1", label: "Semantic dedup" });
+    if (opts._walkthroughSemanticConflict)
+        envFlags.push({ flag: "PHREN_FEATURE_SEMANTIC_CONFLICT=1", label: "Conflict detection" });
+    if (envFlags.length === 0)
+        return [];
+    let changed = false;
+    const enabledLabels = [];
+    for (const { flag, label } of envFlags) {
+        const key = flag.split("=")[0];
+        const lineRe = new RegExp(`^\\s*${key}=.*$`, "m");
+        if (lineRe.test(envContent)) {
+            const before = envContent;
+            envContent = envContent.replace(lineRe, flag);
+            if (envContent !== before) {
+                changed = true;
+                enabledLabels.push(label);
+            }
+        }
+        else {
+            if (!envContent.endsWith("\n"))
+                envContent += "\n";
+            envContent += `${flag}\n`;
+            changed = true;
+            enabledLabels.push(label);
+        }
+    }
+    if (changed) {
+        const tmpPath = `${envFile}.tmp-${crypto.randomUUID()}`;
+        fs.writeFileSync(tmpPath, envContent);
+        fs.renameSync(tmpPath, envFile);
+    }
+    return enabledLabels.map((label) => `${label} (${envFile})`);
+}
+export function collectRepairedAssetLabels(repaired) {
+    const repairedAssets = [];
+    if (repaired.createdContextFile)
+        repairedAssets.push("~/.phren-context.md");
+    if (repaired.createdRootMemory)
+        repairedAssets.push("generated MEMORY.md");
+    repairedAssets.push(...repaired.createdGlobalAssets);
+    repairedAssets.push(...repaired.createdRuntimeAssets);
+    repairedAssets.push(...repaired.createdFeatureDefaults);
+    repairedAssets.push(...repaired.createdSkillArtifacts);
+    return repairedAssets;
+}
+export function applyProjectStorageBindings(repoRoot, phrenPath) {
+    const updates = [];
+    if (ensureGitignoreEntry(repoRoot, ".phren/")) {
+        updates.push(`${path.join(repoRoot, ".gitignore")} (.phren/)`);
+    }
+    if (upsertProjectEnvVar(repoRoot, "PHREN_PATH", phrenPath)) {
+        updates.push(`${path.join(repoRoot, ".env")} (PHREN_PATH=${phrenPath})`);
+    }
+    return updates;
+}

package/mcp/dist/init-fresh.js

@@ -0,0 +1,234 @@
+/**
+ * Fresh install logic: copy starter, scaffold project, write initial config.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { atomicWriteText, debugLog, hookConfigPath, writeRootManifest, } from "./shared.js";
+import { isValidProjectName, errorMessage } from "./utils.js";
+import { getMachineName, persistMachineName } from "./machine-identity.js";
+import { writeInstallPreferences, } from "./init/preferences.js";
+import { ensureGovernanceFiles, repairPreexistingInstall, runPostInitVerify, listTemplates, applyTemplate, ensureProjectScaffold, ensureLocalGitRepo, updateMachinesYaml, detectProjectDir, } from "./init/setup.js";
+import { getWorkflowPolicy } from "./shared/governance.js";
+import { addProjectToProfile } from "./profile-store.js";
+import { STARTER_DIR, VERSION, log, confirmPrompt } from "./init/shared.js";
+import { configureMcpTargets } from "./init-mcp.js";
+import { configureHooksIfEnabled } from "./init-hooks.js";
+import { applyOnboardingPreferences, writeWalkthroughEnvDefaults, collectRepairedAssetLabels, } from "./init-env.js";
+import { warmSemanticSearch } from "./init-semantic.js";
+import { bootstrapProject } from "./init-bootstrap.js";
+import { logger } from "./logger.js";
+function copyDir(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        if (src === STARTER_DIR && entry.isDirectory() && ["my-api", "my-frontend", "my-first-project"].includes(entry.name)) {
+            continue;
+        }
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            copyDir(srcPath, destPath);
+        }
+        else {
+            fs.copyFileSync(srcPath, destPath);
+        }
+    }
+}
+export async function runFreshInstall(phrenPath, opts, params) {
+    const { mcpEnabled, hooksEnabled, skillsScope, ownershipDefault, syncIntent, shouldBootstrapCurrentProject, bootstrapOwnership, } = params;
+    log("\nSetting up phren...\n");
+    const walkthroughProject = opts._walkthroughProject;
+    if (walkthroughProject) {
+        if (!walkthroughProject.trim()) {
+            console.error("Error: project name cannot be empty.");
+            process.exit(1);
+        }
+        if (walkthroughProject.length > 100) {
+            console.error("Error: project name must be 100 characters or fewer.");
+            process.exit(1);
+        }
+        if (!isValidProjectName(walkthroughProject)) {
+            console.error(`Error: invalid project name "${walkthroughProject}". Use lowercase letters, numbers, and hyphens.`);
+            process.exit(1);
+        }
+    }
+    const cwdProjectPath = !walkthroughProject ? detectProjectDir(process.cwd(), phrenPath) : null;
+    const useTemplateProject = Boolean(walkthroughProject) || Boolean(opts.template);
+    const firstProjectName = walkthroughProject || "my-first-project";
+    const firstProjectDomain = opts._walkthroughDomain ?? "software";
+    if (fs.existsSync(STARTER_DIR)) {
+        copyDir(STARTER_DIR, phrenPath);
+        writeRootManifest(phrenPath, {
+            version: 1,
+            installMode: "shared",
+            syncMode: "managed-git",
+        });
+        if (useTemplateProject) {
+            const targetProject = walkthroughProject || firstProjectName;
+            const projectDir = path.join(phrenPath, targetProject);
+            const templateApplied = Boolean(opts.template && applyTemplate(projectDir, opts.template, targetProject));
+            if (templateApplied) {
+                log(`  Applied "${opts.template}" template to ${targetProject}`);
+            }
+            ensureProjectScaffold(projectDir, targetProject, firstProjectDomain, opts._walkthroughInferredScaffold);
+            const targetProfile = opts.profile || "default";
+            const addToProfile = addProjectToProfile(phrenPath, targetProfile, targetProject);
+            if (!addToProfile.ok) {
+                debugLog(`fresh init addProjectToProfile failed for ${targetProfile}/${targetProject}: ${addToProfile.error}`);
+            }
+            if (opts.template && !templateApplied) {
+                log(`  Template "${opts.template}" not found. Available: ${listTemplates().join(", ") || "none"}`);
+            }
+            log(`  Seeded project "${targetProject}"`);
+        }
+        log(`  Created phren v${VERSION} \u2192 ${phrenPath}`);
+    }
+    else {
+        log(`  Starter not found in package, creating minimal structure...`);
+        writeRootManifest(phrenPath, {
+            version: 1,
+            installMode: "shared",
+            syncMode: "managed-git",
+        });
+        fs.mkdirSync(path.join(phrenPath, "global", "skills"), { recursive: true });
+        fs.mkdirSync(path.join(phrenPath, "profiles"), { recursive: true });
+        atomicWriteText(path.join(phrenPath, "global", "CLAUDE.md"), `# Global Context\n\nThis file is loaded in every project.\n\n## General preferences\n\n<!-- Your coding style, preferred tools, things Claude should always know -->\n`);
+        if (useTemplateProject) {
+            const projectDir = path.join(phrenPath, firstProjectName);
+            if (opts.template && applyTemplate(projectDir, opts.template, firstProjectName)) {
+                log(`  Applied "${opts.template}" template to ${firstProjectName}`);
+            }
+            ensureProjectScaffold(projectDir, firstProjectName, firstProjectDomain, opts._walkthroughInferredScaffold);
+        }
+        const profileName = opts.profile || "default";
+        const profileProjects = useTemplateProject
+            ? `  - global\n  - ${firstProjectName}`
+            : `  - global`;
+        atomicWriteText(path.join(phrenPath, "profiles", `${profileName}.yaml`), `name: ${profileName}\ndescription: Default profile\nprojects:\n${profileProjects}\n`);
+    }
+    // Bootstrap CWD project if opted in
+    if (cwdProjectPath && shouldBootstrapCurrentProject) {
+        bootstrapProject(phrenPath, cwdProjectPath, opts.profile, bootstrapOwnership, "Added current project");
+    }
+    // Persist machine and config
+    const effectiveMachine = opts.machine?.trim() || getMachineName();
+    persistMachineName(effectiveMachine);
+    updateMachinesYaml(phrenPath, effectiveMachine, opts.profile);
+    ensureGovernanceFiles(phrenPath);
+    const repaired = repairPreexistingInstall(phrenPath);
+    applyOnboardingPreferences(phrenPath, opts);
+    const localGitRepo = ensureLocalGitRepo(phrenPath);
+    log(`  Updated machines.yaml with machine "${effectiveMachine}"`);
+    const mcpLabel = mcpEnabled ? "ON (recommended)" : "OFF (hooks-only fallback)";
+    const hooksLabel = hooksEnabled ? "ON (active)" : "OFF (disabled)";
+    log(`  MCP mode: ${mcpLabel}`);
+    log(`  Hooks mode: ${hooksLabel}`);
+    log(`  Default project ownership: ${ownershipDefault}`);
+    log(`  Task mode: ${getWorkflowPolicy(phrenPath).taskMode}`);
+    log(`  Git repo: ${localGitRepo.detail}`);
+    if (repaired.removedLegacyProjects > 0) {
+        log(`  Removed ${repaired.removedLegacyProjects} legacy starter project entr${repaired.removedLegacyProjects === 1 ? "y" : "ies"} from profiles.`);
+    }
+    const repairedAssets = collectRepairedAssetLabels(repaired);
+    if (repairedAssets.length > 0) {
+        log(`  Recreated missing generated assets: ${repairedAssets.join(", ")}`);
+    }
+    // Confirmation prompt before writing agent config
+    if (!opts.yes) {
+        const settingsPath = hookConfigPath("claude");
+        log(`\nWill modify:`);
+        log(`  ${settingsPath}  (add MCP server + hooks)`);
+        const confirmed = await confirmPrompt("\nProceed?");
+        if (!confirmed) {
+            log("Aborted.");
+            return;
+        }
+    }
+    // Configure MCP and hooks
+    configureMcpTargets(phrenPath, { mcpEnabled, hooksEnabled }, "Configured");
+    configureHooksIfEnabled(phrenPath, hooksEnabled, "Configured");
+    writeInstallPreferences(phrenPath, { mcpEnabled, hooksEnabled, skillsScope, installedVersion: VERSION, syncIntent });
+    // Post-init verification
+    log(`\nVerifying setup...`);
+    const verify = runPostInitVerify(phrenPath);
+    for (const check of verify.checks) {
+        log(`  ${check.ok ? "pass" : "FAIL"} ${check.name}: ${check.detail}`);
+    }
+    log(`\nWhat was created:`);
+    log(`  ${phrenPath}/global/CLAUDE.md    Global instructions loaded in every session`);
+    log(`  ${phrenPath}/global/skills/      Phren slash commands`);
+    log(`  ${phrenPath}/profiles/           Machine-to-project mappings`);
+    log(`  ${phrenPath}/.config/        Memory quality settings and config`);
+    // Ollama status summary (skip if already covered in walkthrough)
+    const walkthroughCoveredOllama = Boolean(process.env._PHREN_WALKTHROUGH_OLLAMA_SKIP) || !opts.yes;
+    if (!walkthroughCoveredOllama) {
+        try {
+            const { checkOllamaStatus } = await import("./shared/ollama.js");
+            const status = await checkOllamaStatus();
+            if (status === "ready") {
+                log("\n  Semantic search: Ollama + nomic-embed-text ready.");
+            }
+            else if (status === "no_model") {
+                log("\n  Semantic search: Ollama running, but nomic-embed-text not pulled.");
+                log("  Run: ollama pull nomic-embed-text");
+            }
+            else if (status === "not_running") {
+                log("\n  Tip: Install Ollama for semantic search (optional).");
+                log("  https://ollama.com → then: ollama pull nomic-embed-text");
+                log("  (Set PHREN_OLLAMA_URL=off to hide this message)");
+            }
+        }
+        catch (err) {
+            logger.debug("init ollamaInstallHint", errorMessage(err));
+        }
+    }
+    for (const envLabel of writeWalkthroughEnvDefaults(phrenPath, opts)) {
+        log(`  ${envLabel}`);
+    }
+    if (opts._walkthroughSemanticSearch) {
+        log(`\nWarming semantic search...`);
+        try {
+            log(`  ${await warmSemanticSearch(phrenPath, opts.profile)}`);
+        }
+        catch (err) {
+            log(`  Semantic search warmup failed: ${errorMessage(err)}`);
+        }
+    }
+    log(`\n\x1b[95m◆\x1b[0m phren initialized`);
+    log(`\nNext steps:`);
+    let step = 1;
+    log(`  ${step++}. Start a new Claude session in your project directory — phren injects context automatically`);
+    log(`  ${step++}. Run \`npx phren doctor\` to verify everything is wired correctly`);
+    log(`  ${step++}. Change defaults anytime: \`npx phren config project-ownership\`, \`npx phren config workflow\`, \`npx phren config proactivity.findings\`, \`npx phren config proactivity.tasks\``);
+    const gh = opts._walkthroughGithub;
+    if (gh) {
+        const remote = gh.username
+            ? `git@github.com:${gh.username}/${gh.repo}.git`
+            : `git@github.com:YOUR_USERNAME/${gh.repo}.git`;
+        log(`  ${step++}. Push your phren to GitHub (private repo recommended):`);
+        log(`     cd ${phrenPath}`);
+        log(`     git add . && git commit -m "Initial phren setup"`);
+        if (gh.username) {
+            log(`     gh repo create ${gh.username}/${gh.repo} --private --source=. --push`);
+            log(`     # or manually: git remote add origin ${remote} && git push -u origin main`);
+        }
+        else {
+            log(`     git remote add origin ${remote}`);
+            log(`     git push -u origin main`);
+        }
+    }
+    else {
+        log(`  ${step++}. Push to GitHub for cross-machine sync (private repo recommended):`);
+        log(`     cd ${phrenPath}`);
+        log(`     git add . && git commit -m "Initial phren setup"`);
+        log(`     git remote add origin git@github.com:YOUR_USERNAME/my-phren.git`);
+        log(`     git push -u origin main`);
+    }
+    log(`  ${step++}. Add more projects: cd ~/your-project && npx phren add`);
+    if (!mcpEnabled) {
+        log(`  ${step++}. Turn MCP on: npx phren mcp-mode on`);
+    }
+    log(`  ${step++}. After your first week, run phren-discover to surface gaps in your project knowledge`);
+    log(`  ${step++}. After working across projects, run phren-consolidate to find cross-project patterns`);
+    log(`\n  Read ${phrenPath}/README.md for a guided tour of each file.`);
+    log(``);
+}

package/mcp/dist/init-hooks.js

@@ -0,0 +1,26 @@
+/**
+ * Hook configuration helper for init.
+ */
+import { configureAllHooks } from "./hooks.js";
+import { debugLog } from "./shared.js";
+import { errorMessage } from "./utils.js";
+import { log } from "./init/shared.js";
+/**
+ * Configure hooks if enabled, or log a disabled message.
+ * @param verb - label used in log messages, e.g. "Updated" or "Configured"
+ */
+export function configureHooksIfEnabled(phrenPath, hooksEnabled, verb) {
+    if (hooksEnabled) {
+        try {
+            const hooked = configureAllHooks(phrenPath, { allTools: true });
+            if (hooked.length)
+                log(`  ${verb} hooks: ${hooked.join(", ")}`);
+        }
+        catch (err) {
+            debugLog(`configureAllHooks failed: ${errorMessage(err)}`);
+        }
+    }
+    else {
+        log(`  Hooks are disabled by preference (run: npx phren hooks-mode on)`);
+    }
+}

package/mcp/dist/init-mcp.js

@@ -0,0 +1,65 @@
+/**
+ * MCP target configuration for all detected AI coding tools.
+ */
+import { configureClaude, configureVSCode, configureCursorMcp, configureCopilotMcp, configureCodexMcp, logMcpTargetStatus, } from "./init/config.js";
+import { debugLog } from "./shared.js";
+import { errorMessage } from "./utils.js";
+import { log } from "./init/shared.js";
+/**
+ * Configure MCP for all detected AI coding tools (Claude, VS Code, Cursor, Copilot, Codex).
+ * @param verb - label used in log messages, e.g. "Updated" or "Configured"
+ */
+export function configureMcpTargets(phrenPath, opts, verb = "Configured") {
+    let claudeStatus = "no_settings";
+    try {
+        const status = configureClaude(phrenPath, { mcpEnabled: opts.mcpEnabled, hooksEnabled: opts.hooksEnabled });
+        claudeStatus = status ?? "installed";
+        if (status === "disabled" || status === "already_disabled") {
+            log(`  ${verb} Claude Code hooks (MCP disabled)`);
+        }
+        else {
+            log(`  ${verb} Claude Code MCP + hooks`);
+        }
+    }
+    catch (e) {
+        log(`  Could not configure Claude Code settings (${e}), add manually`);
+    }
+    let vsStatus = "no_vscode";
+    try {
+        vsStatus = configureVSCode(phrenPath, { mcpEnabled: opts.mcpEnabled }) ?? "no_vscode";
+        logMcpTargetStatus("VS Code", vsStatus, verb);
+    }
+    catch (err) {
+        debugLog(`configureVSCode failed: ${errorMessage(err)}`);
+    }
+    let cursorStatus = "no_cursor";
+    try {
+        cursorStatus = configureCursorMcp(phrenPath, { mcpEnabled: opts.mcpEnabled }) ?? "no_cursor";
+        logMcpTargetStatus("Cursor", cursorStatus, verb);
+    }
+    catch (err) {
+        debugLog(`configureCursorMcp failed: ${errorMessage(err)}`);
+    }
+    let copilotStatus = "no_copilot";
+    try {
+        copilotStatus = configureCopilotMcp(phrenPath, { mcpEnabled: opts.mcpEnabled }) ?? "no_copilot";
+        logMcpTargetStatus("Copilot CLI", copilotStatus, verb);
+    }
+    catch (err) {
+        debugLog(`configureCopilotMcp failed: ${errorMessage(err)}`);
+    }
+    let codexStatus = "no_codex";
+    try {
+        codexStatus = configureCodexMcp(phrenPath, { mcpEnabled: opts.mcpEnabled }) ?? "no_codex";
+        logMcpTargetStatus("Codex", codexStatus, verb);
+    }
+    catch (err) {
+        debugLog(`configureCodexMcp failed: ${errorMessage(err)}`);
+    }
+    const allStatuses = [claudeStatus, vsStatus, cursorStatus, copilotStatus, codexStatus];
+    if (allStatuses.some((s) => s === "installed" || s === "already_configured"))
+        return "installed";
+    if (allStatuses.some((s) => s === "disabled" || s === "already_disabled"))
+        return "disabled";
+    return claudeStatus;
+}

package/mcp/dist/init-modes.js

@@ -0,0 +1,135 @@
+/**
+ * MCP-mode and hooks-mode toggle commands.
+ */
+import { configureClaude, configureVSCode, configureCursorMcp, configureCopilotMcp, configureCodexMcp, } from "./init/config.js";
+import { configureAllHooks } from "./hooks.js";
+import { debugLog, findPhrenPath, readRootManifest, } from "./shared.js";
+import { errorMessage } from "./utils.js";
+import { getMcpEnabledPreference, getHooksEnabledPreference, setMcpEnabledPreference, setHooksEnabledPreference, } from "./init/preferences.js";
+import { DEFAULT_PHREN_PATH, log } from "./init/shared.js";
+export function parseMcpMode(raw) {
+    if (!raw)
+        return undefined;
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === "on" || normalized === "off")
+        return normalized;
+    return undefined;
+}
+export async function runMcpMode(modeArg) {
+    const phrenPath = findPhrenPath() || (process.env.PHREN_PATH) || DEFAULT_PHREN_PATH;
+    const manifest = readRootManifest(phrenPath);
+    const normalizedArg = modeArg?.trim().toLowerCase();
+    if (!normalizedArg || normalizedArg === "status") {
+        const current = getMcpEnabledPreference(phrenPath);
+        const hooks = getHooksEnabledPreference(phrenPath);
+        log(`MCP mode: ${current ? "on (recommended)" : "off (hooks-only fallback)"}`);
+        log(`Hooks mode: ${hooks ? "on (active)" : "off (disabled)"}`);
+        log(`Change mode: npx phren mcp-mode on|off`);
+        log(`Hooks toggle: npx phren hooks-mode on|off`);
+        return;
+    }
+    const mode = parseMcpMode(normalizedArg);
+    if (!mode) {
+        throw new Error(`Invalid mode "${modeArg}". Use: on | off | status`);
+    }
+    const enabled = mode === "on";
+    if (manifest?.installMode === "project-local") {
+        const vscodeStatus = configureVSCode(phrenPath, { mcpEnabled: enabled, scope: "workspace" });
+        setMcpEnabledPreference(phrenPath, enabled);
+        log(`MCP mode set to ${mode}.`);
+        log(`VS Code status: ${vscodeStatus}`);
+        log(`Project-local mode only configures workspace VS Code MCP.`);
+        return;
+    }
+    let claudeStatus = "no_settings";
+    let vscodeStatus = "no_vscode";
+    let cursorStatus = "no_cursor";
+    let copilotStatus = "no_copilot";
+    let codexStatus = "no_codex";
+    try {
+        claudeStatus = configureClaude(phrenPath, { mcpEnabled: enabled }) ?? claudeStatus;
+    }
+    catch (err) {
+        debugLog(`mcp-mode: configureClaude failed: ${errorMessage(err)}`);
+    }
+    try {
+        vscodeStatus = configureVSCode(phrenPath, { mcpEnabled: enabled }) ?? vscodeStatus;
+    }
+    catch (err) {
+        debugLog(`mcp-mode: configureVSCode failed: ${errorMessage(err)}`);
+    }
+    try {
+        cursorStatus = configureCursorMcp(phrenPath, { mcpEnabled: enabled }) ?? cursorStatus;
+    }
+    catch (err) {
+        debugLog(`mcp-mode: configureCursorMcp failed: ${errorMessage(err)}`);
+    }
+    try {
+        copilotStatus = configureCopilotMcp(phrenPath, { mcpEnabled: enabled }) ?? copilotStatus;
+    }
+    catch (err) {
+        debugLog(`mcp-mode: configureCopilotMcp failed: ${errorMessage(err)}`);
+    }
+    try {
+        codexStatus = configureCodexMcp(phrenPath, { mcpEnabled: enabled }) ?? codexStatus;
+    }
+    catch (err) {
+        debugLog(`mcp-mode: configureCodexMcp failed: ${errorMessage(err)}`);
+    }
+    // Persist preference only after config writes have been attempted
+    setMcpEnabledPreference(phrenPath, enabled);
+    log(`MCP mode set to ${mode}.`);
+    log(`Claude status: ${claudeStatus}`);
+    log(`VS Code status: ${vscodeStatus}`);
+    log(`Cursor status: ${cursorStatus}`);
+    log(`Copilot CLI status: ${copilotStatus}`);
+    log(`Codex status: ${codexStatus}`);
+    log(`Restart your agent to apply changes.`);
+}
+export async function runHooksMode(modeArg) {
+    const phrenPath = findPhrenPath() || (process.env.PHREN_PATH) || DEFAULT_PHREN_PATH;
+    const manifest = readRootManifest(phrenPath);
+    const normalizedArg = modeArg?.trim().toLowerCase();
+    if (!normalizedArg || normalizedArg === "status") {
+        const current = getHooksEnabledPreference(phrenPath);
+        log(`Hooks mode: ${current ? "on (active)" : "off (disabled)"}`);
+        log(`Change mode: npx phren hooks-mode on|off`);
+        return;
+    }
+    const mode = parseMcpMode(normalizedArg);
+    if (!mode) {
+        throw new Error(`Invalid mode "${modeArg}". Use: on | off | status`);
+    }
+    if (manifest?.installMode === "project-local") {
+        throw new Error("hooks-mode is unsupported in project-local mode");
+    }
+    const enabled = mode === "on";
+    let claudeStatus = "no_settings";
+    try {
+        claudeStatus = configureClaude(phrenPath, {
+            mcpEnabled: getMcpEnabledPreference(phrenPath),
+            hooksEnabled: enabled,
+        }) ?? claudeStatus;
+    }
+    catch (err) {
+        debugLog(`hooks-mode: configureClaude failed: ${errorMessage(err)}`);
+    }
+    if (enabled) {
+        try {
+            const hooked = configureAllHooks(phrenPath, { allTools: true });
+            if (hooked.length)
+                log(`Updated hooks: ${hooked.join(", ")}`);
+        }
+        catch (err) {
+            debugLog(`hooks-mode: configureAllHooks failed: ${errorMessage(err)}`);
+        }
+    }
+    else {
+        log("Hooks will no-op immediately via preference and Claude hooks are removed.");
+    }
+    // Persist preference only after config writes have been attempted
+    setHooksEnabledPreference(phrenPath, enabled);
+    log(`Hooks mode set to ${mode}.`);
+    log(`Claude status: ${claudeStatus}`);
+    log(`Restart your agent to apply changes.`);
+}

package/mcp/dist/init-npm.js

@@ -0,0 +1,37 @@
+/**
+ * Version comparison utilities for phren init and update flows.
+ */
+function parseVersion(version) {
+    const match = version.trim().match(/^(\d+)\.(\d+)\.(\d+)(?:-(.+))?/);
+    if (!match)
+        return { major: 0, minor: 0, patch: 0, pre: "" };
+    return {
+        major: Number.parseInt(match[1], 10) || 0,
+        minor: Number.parseInt(match[2], 10) || 0,
+        patch: Number.parseInt(match[3], 10) || 0,
+        pre: match[4] || "",
+    };
+}
+/**
+ * Compare two semver strings. Returns true when `current` is strictly newer
+ * than `previous`. Pre-release versions (e.g. 1.2.3-rc.1) sort before the
+ * corresponding release (1.2.3). Among pre-release tags, comparison is
+ * lexicographic.
+ */
+export function isVersionNewer(current, previous) {
+    if (!previous)
+        return false;
+    const c = parseVersion(current);
+    const p = parseVersion(previous);
+    if (c.major !== p.major)
+        return c.major > p.major;
+    if (c.minor !== p.minor)
+        return c.minor > p.minor;
+    if (c.patch !== p.patch)
+        return c.patch > p.patch;
+    if (c.pre && !p.pre)
+        return false;
+    if (!c.pre && p.pre)
+        return true;
+    return c.pre > p.pre;
+}