@phren/cli 0.0.1

package/mcp/dist/mcp-config.js

@@ -0,0 +1,254 @@
+import { mcpResponse } from "./mcp-types.js";
+import { z } from "zod";
+import { getRetentionPolicy, updateRetentionPolicy, getWorkflowPolicy, updateWorkflowPolicy, getIndexPolicy, updateIndexPolicy, } from "./shared-governance.js";
+import { PROACTIVITY_LEVELS, getProactivityLevel, getProactivityLevelForFindings, getProactivityLevelForTask, } from "./proactivity.js";
+import { readGovernanceInstallPreferences, writeGovernanceInstallPreferences, } from "./init-preferences.js";
+import { FINDING_SENSITIVITY_CONFIG } from "./cli-config.js";
+// ── Helpers ─────────────────────────────────────────────────────────────────
+function normalizeProactivityLevel(raw) {
+    if (!raw)
+        return undefined;
+    const normalized = raw.trim().toLowerCase();
+    return PROACTIVITY_LEVELS.includes(normalized)
+        ? normalized
+        : undefined;
+}
+function proactivitySnapshot(phrenPath) {
+    const prefs = readGovernanceInstallPreferences(phrenPath);
+    return {
+        configured: {
+            proactivity: prefs.proactivity ?? null,
+            proactivityFindings: prefs.proactivityFindings ?? null,
+            proactivityTask: prefs.proactivityTask ?? null,
+        },
+        effective: {
+            proactivity: getProactivityLevel(phrenPath),
+            proactivityFindings: getProactivityLevelForFindings(phrenPath),
+            proactivityTask: getProactivityLevelForTask(phrenPath),
+        },
+    };
+}
+const TASK_MODES = ["off", "manual", "suggest", "auto"];
+const FINDING_SENSITIVITY_LEVELS = ["minimal", "conservative", "balanced", "aggressive"];
+// ── Registration ────────────────────────────────────────────────────────────
+export function register(server, ctx) {
+    const { phrenPath } = ctx;
+    // ── get_config ────────────────────────────────────────────────────────────
+    server.registerTool("get_config", {
+        title: "◆ phren · get config",
+        description: "Read current configuration for one or all config domains: proactivity, taskMode, " +
+            "findingSensitivity, retention (policy), workflow, access, index. " +
+            "Returns both configured and effective values.",
+        inputSchema: z.object({
+            domain: z
+                .enum(["proactivity", "taskMode", "findingSensitivity", "retention", "workflow", "access", "index", "all"])
+                .optional()
+                .describe("Config domain to read. Defaults to 'all'."),
+        }),
+    }, async ({ domain }) => {
+        const d = domain ?? "all";
+        const result = {};
+        if (d === "all" || d === "proactivity") {
+            result.proactivity = proactivitySnapshot(phrenPath);
+        }
+        if (d === "all" || d === "taskMode") {
+            const wf = getWorkflowPolicy(phrenPath);
+            result.taskMode = { taskMode: wf.taskMode };
+        }
+        if (d === "all" || d === "findingSensitivity") {
+            const wf = getWorkflowPolicy(phrenPath);
+            const level = wf.findingSensitivity;
+            const config = FINDING_SENSITIVITY_CONFIG[level];
+            result.findingSensitivity = { level, ...config };
+        }
+        if (d === "all" || d === "retention") {
+            result.retention = getRetentionPolicy(phrenPath);
+        }
+        if (d === "all" || d === "workflow") {
+            result.workflow = getWorkflowPolicy(phrenPath);
+        }
+        if (d === "all" || d === "index") {
+            result.index = getIndexPolicy(phrenPath);
+        }
+        return mcpResponse({
+            ok: true,
+            message: `Config for ${d === "all" ? "all domains" : d}.`,
+            data: result,
+        });
+    });
+    // ── set_proactivity ───────────────────────────────────────────────────────
+    server.registerTool("set_proactivity", {
+        title: "◆ phren · set proactivity",
+        description: "Set the proactivity level for auto-capture. Controls how aggressively phren " +
+            "captures findings and tasks. Supports base level, findings-specific, and task-specific overrides.",
+        inputSchema: z.object({
+            level: z.enum(PROACTIVITY_LEVELS).describe("Proactivity level: high, medium, or low."),
+            scope: z
+                .enum(["base", "findings", "tasks"])
+                .optional()
+                .describe("Which proactivity to set. Defaults to 'base'."),
+        }),
+    }, async ({ level, scope }) => {
+        const s = scope ?? "base";
+        const patch = {};
+        if (s === "base")
+            patch.proactivity = level;
+        else if (s === "findings")
+            patch.proactivityFindings = level;
+        else if (s === "tasks")
+            patch.proactivityTask = level;
+        writeGovernanceInstallPreferences(phrenPath, patch);
+        return mcpResponse({
+            ok: true,
+            message: `Proactivity ${s} set to ${level}.`,
+            data: proactivitySnapshot(phrenPath),
+        });
+    });
+    // ── set_task_mode ─────────────────────────────────────────────────────────
+    server.registerTool("set_task_mode", {
+        title: "◆ phren · set task mode",
+        description: "Set the task automation mode: off (no auto-tasks), manual (user creates), " +
+            "suggest (phren suggests, user approves), auto (phren creates automatically).",
+        inputSchema: z.object({
+            mode: z.enum(TASK_MODES).describe("Task mode: off, manual, suggest, or auto."),
+        }),
+    }, async ({ mode }) => {
+        const result = updateWorkflowPolicy(phrenPath, { taskMode: mode });
+        if (!result.ok) {
+            return mcpResponse({ ok: false, error: result.error, errorCode: result.code });
+        }
+        return mcpResponse({
+            ok: true,
+            message: `Task mode set to ${mode}.`,
+            data: { taskMode: mode },
+        });
+    });
+    // ── set_finding_sensitivity ───────────────────────────────────────────────
+    server.registerTool("set_finding_sensitivity", {
+        title: "◆ phren · set finding sensitivity",
+        description: "Set the finding capture sensitivity level. Controls how many findings phren captures per session. " +
+            "minimal: only explicit asks. conservative: decisions/pitfalls only. " +
+            "balanced: non-obvious patterns. aggressive: capture everything.",
+        inputSchema: z.object({
+            level: z.enum(FINDING_SENSITIVITY_LEVELS).describe("Sensitivity level."),
+        }),
+    }, async ({ level }) => {
+        const result = updateWorkflowPolicy(phrenPath, { findingSensitivity: level });
+        if (!result.ok) {
+            return mcpResponse({ ok: false, error: result.error, errorCode: result.code });
+        }
+        const config = FINDING_SENSITIVITY_CONFIG[level];
+        return mcpResponse({
+            ok: true,
+            message: `Finding sensitivity set to ${level}.`,
+            data: { level, ...config },
+        });
+    });
+    // ── set_retention_policy ──────────────────────────────────────────────────
+    server.registerTool("set_retention_policy", {
+        title: "◆ phren · set retention policy",
+        description: "Update memory retention policy: TTL, retention days, auto-accept threshold, " +
+            "minimum injection confidence, and decay curve.",
+        inputSchema: z.object({
+            ttlDays: z.number().int().min(1).optional().describe("Days before a finding is considered for expiry."),
+            retentionDays: z.number().int().min(1).optional().describe("Hard retention limit in days."),
+            autoAcceptThreshold: z.number().min(0).max(1).optional().describe("Score threshold (0-1) for auto-accepting extracted memories."),
+            minInjectConfidence: z.number().min(0).max(1).optional().describe("Minimum confidence (0-1) to inject a finding into context."),
+            decay: z
+                .object({
+                d30: z.number().min(0).max(1).optional(),
+                d60: z.number().min(0).max(1).optional(),
+                d90: z.number().min(0).max(1).optional(),
+                d120: z.number().min(0).max(1).optional(),
+            })
+                .optional()
+                .describe("Decay multipliers at 30/60/90/120 day marks."),
+        }),
+    }, async ({ ttlDays, retentionDays, autoAcceptThreshold, minInjectConfidence, decay }) => {
+        const patch = {};
+        if (ttlDays !== undefined)
+            patch.ttlDays = ttlDays;
+        if (retentionDays !== undefined)
+            patch.retentionDays = retentionDays;
+        if (autoAcceptThreshold !== undefined)
+            patch.autoAcceptThreshold = autoAcceptThreshold;
+        if (minInjectConfidence !== undefined)
+            patch.minInjectConfidence = minInjectConfidence;
+        if (decay !== undefined)
+            patch.decay = decay;
+        const result = updateRetentionPolicy(phrenPath, patch);
+        if (!result.ok) {
+            return mcpResponse({ ok: false, error: result.error, errorCode: result.code });
+        }
+        return mcpResponse({
+            ok: true,
+            message: "Retention policy updated.",
+            data: result.data,
+        });
+    });
+    // ── set_workflow_policy ───────────────────────────────────────────────────
+    server.registerTool("set_workflow_policy", {
+        title: "◆ phren · set workflow policy",
+        description: "Update workflow policy: low-confidence threshold, " +
+            "risky sections list, task mode, and finding sensitivity.",
+        inputSchema: z.object({
+            lowConfidenceThreshold: z.number().min(0).max(1).optional()
+                .describe("Confidence below which items are flagged as low-confidence."),
+            riskySections: z.array(z.enum(["Review", "Stale", "Conflicts"])).optional()
+                .describe("Which queue sections are considered risky."),
+            taskMode: z.enum(TASK_MODES).optional()
+                .describe("Task automation mode."),
+            findingSensitivity: z.enum(FINDING_SENSITIVITY_LEVELS).optional()
+                .describe("Finding capture sensitivity."),
+        }),
+    }, async ({ lowConfidenceThreshold, riskySections, taskMode, findingSensitivity }) => {
+        const patch = {};
+        if (lowConfidenceThreshold !== undefined)
+            patch.lowConfidenceThreshold = lowConfidenceThreshold;
+        if (riskySections !== undefined)
+            patch.riskySections = riskySections;
+        if (taskMode !== undefined)
+            patch.taskMode = taskMode;
+        if (findingSensitivity !== undefined)
+            patch.findingSensitivity = findingSensitivity;
+        const result = updateWorkflowPolicy(phrenPath, patch);
+        if (!result.ok) {
+            return mcpResponse({ ok: false, error: result.error, errorCode: result.code });
+        }
+        return mcpResponse({
+            ok: true,
+            message: "Workflow policy updated.",
+            data: result.data,
+        });
+    });
+    // ── set_index_policy ──────────────────────────────────────────────────────
+    server.registerTool("set_index_policy", {
+        title: "◆ phren · set index policy",
+        description: "Update the FTS indexer policy: include/exclude glob patterns and hidden file inclusion.",
+        inputSchema: z.object({
+            includeGlobs: z.array(z.string()).optional()
+                .describe("Glob patterns for files to include in the index."),
+            excludeGlobs: z.array(z.string()).optional()
+                .describe("Glob patterns for files to exclude from the index."),
+            includeHidden: z.boolean().optional()
+                .describe("Whether to index hidden (dot-prefixed) files."),
+        }),
+    }, async ({ includeGlobs, excludeGlobs, includeHidden }) => {
+        const patch = {};
+        if (includeGlobs !== undefined)
+            patch.includeGlobs = includeGlobs;
+        if (excludeGlobs !== undefined)
+            patch.excludeGlobs = excludeGlobs;
+        if (includeHidden !== undefined)
+            patch.includeHidden = includeHidden;
+        const result = updateIndexPolicy(phrenPath, patch);
+        if (!result.ok) {
+            return mcpResponse({ ok: false, error: result.error, errorCode: result.code });
+        }
+        return mcpResponse({
+            ok: true,
+            message: "Index policy updated.",
+            data: result.data,
+        });
+    });
+}

package/mcp/dist/mcp-data.js

@@ -0,0 +1,315 @@
+import { mcpResponse } from "./mcp-types.js";
+import { z } from "zod";
+import * as fs from "fs";
+import * as path from "path";
+import { isValidProjectName } from "./utils.js";
+import { readFindings, readTasks, resolveTaskFilePath, TASKS_FILENAME } from "./data-access.js";
+import { debugLog, findProjectNameCaseInsensitive, normalizeProjectNameForCreate } from "./shared.js";
+const importPayloadSchema = z.object({
+    project: z.string(),
+    overwrite: z.boolean().optional(),
+    summary: z.string().optional(),
+    claudeMd: z.string().optional(),
+    taskRaw: z.string().optional(),
+    learnings: z
+        .array(z.object({
+        text: z.string(),
+    }).passthrough())
+        .optional(),
+    task: z
+        .object({
+        Active: z.array(z.object({ line: z.string(), checked: z.boolean().optional(), context: z.string().optional(), priority: z.string().optional(), pinned: z.boolean().optional(), id: z.string().optional(), githubIssue: z.number().optional(), githubUrl: z.string().optional() }).passthrough()).optional(),
+        Queue: z.array(z.object({ line: z.string(), checked: z.boolean().optional(), context: z.string().optional(), priority: z.string().optional(), pinned: z.boolean().optional(), id: z.string().optional(), githubIssue: z.number().optional(), githubUrl: z.string().optional() }).passthrough()).optional(),
+        Done: z.array(z.object({ line: z.string(), checked: z.boolean().optional(), context: z.string().optional(), priority: z.string().optional(), pinned: z.boolean().optional(), id: z.string().optional(), githubIssue: z.number().optional(), githubUrl: z.string().optional() }).passthrough()).optional(),
+    })
+        .partial()
+        .optional(),
+}).passthrough();
+export function register(server, ctx) {
+    const { phrenPath, withWriteQueue, rebuildIndex } = ctx;
+    server.registerTool("export_project", {
+        title: "◆ phren · export",
+        description: "Export a project's data (findings, task, summary) as portable JSON for sharing or backup.",
+        inputSchema: z.object({
+            project: z.string().describe("Project name to export."),
+        }),
+    }, async ({ project }) => {
+        if (!isValidProjectName(project))
+            return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
+        const projectDir = path.join(phrenPath, project);
+        if (!fs.existsSync(projectDir))
+            return mcpResponse({ ok: false, error: `Project "${project}" not found.` });
+        const exported = { project, exportedAt: new Date().toISOString(), version: 1 };
+        const summaryPath = path.join(projectDir, "summary.md");
+        if (fs.existsSync(summaryPath))
+            exported.summary = fs.readFileSync(summaryPath, "utf8");
+        const learningsResult = readFindings(phrenPath, project);
+        if (learningsResult.ok)
+            exported.learnings = learningsResult.data;
+        const findingsPath = path.join(projectDir, "FINDINGS.md");
+        if (fs.existsSync(findingsPath))
+            exported.findingsRaw = fs.readFileSync(findingsPath, "utf8");
+        const taskResult = readTasks(phrenPath, project);
+        if (taskResult.ok) {
+            exported.task = taskResult.data.items;
+            // Also export the raw task file string for lossless round-trip (preserves priority/pinned/stable IDs)
+            const taskRawPath = resolveTaskFilePath(phrenPath, project);
+            if (taskRawPath && fs.existsSync(taskRawPath))
+                exported.taskRaw = fs.readFileSync(taskRawPath, "utf8");
+        }
+        const claudePath = path.join(projectDir, "CLAUDE.md");
+        if (fs.existsSync(claudePath))
+            exported.claudeMd = fs.readFileSync(claudePath, "utf8");
+        return mcpResponse({ ok: true, message: `Exported project "${project}".`, data: exported });
+    });
+    server.registerTool("import_project", {
+        title: "◆ phren · import",
+        description: "Import project data from a previously exported JSON payload. Creates the project directory if needed.",
+        inputSchema: z.object({
+            data: z.string().describe("JSON string from a previous export_project call."),
+        }),
+    }, async ({ data: rawData }) => {
+        return withWriteQueue(async () => {
+            let decoded;
+            try {
+                decoded = JSON.parse(rawData);
+            }
+            catch (err) {
+                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                    process.stderr.write(`[phren] import_project jsonParse: ${err instanceof Error ? err.message : String(err)}\n`);
+                return mcpResponse({ ok: false, error: "Invalid JSON input." });
+            }
+            const parsedResult = importPayloadSchema.safeParse(decoded);
+            if (!parsedResult.success) {
+                return mcpResponse({ ok: false, error: `Invalid import payload: ${parsedResult.error.issues[0]?.message ?? "schema validation failed"}` });
+            }
+            const parsed = parsedResult.data;
+            // Warn about unknown fields silently discarded by .passthrough()
+            const knownTopLevel = new Set(["project", "overwrite", "summary", "claudeMd", "learnings", "task", "exportedAt", "version", "findingsRaw"]);
+            const unknownFields = Object.keys(decoded).filter(k => !knownTopLevel.has(k));
+            if (unknownFields.length > 0) {
+                debugLog(`import_project: unknown fields will be ignored: ${unknownFields.join(", ")}`);
+            }
+            const projectName = normalizeProjectNameForCreate(parsed.project);
+            if (!isValidProjectName(projectName)) {
+                return mcpResponse({ ok: false, error: `Invalid project name: "${parsed.project}"` });
+            }
+            const existingProject = findProjectNameCaseInsensitive(phrenPath, projectName);
+            if (existingProject && existingProject !== projectName) {
+                return mcpResponse({
+                    ok: false,
+                    error: `Project "${existingProject}" already exists with different casing. Refusing to import "${projectName}" because it would split the same project on case-sensitive filesystems.`,
+                });
+            }
+            const projectDir = path.join(phrenPath, projectName);
+            const overwrite = parsed.overwrite === true;
+            if (fs.existsSync(projectDir) && !overwrite) {
+                return mcpResponse({
+                    ok: false,
+                    error: `Project "${projectName}" already exists. Re-run with "overwrite": true to replace it.`,
+                });
+            }
+            const stagingRoot = fs.mkdtempSync(path.join(phrenPath, `.phren-import-${projectName}-`));
+            const stagedProjectDir = path.join(stagingRoot, projectName);
+            const imported = [];
+            const cleanupDir = (dir) => {
+                if (fs.existsSync(dir))
+                    fs.rmSync(dir, { recursive: true, force: true });
+            };
+            const buildFindingsContent = () => {
+                if (!parsed.learnings || parsed.learnings.length === 0)
+                    return null;
+                const date = new Date().toISOString().slice(0, 10);
+                const lines = [`# ${projectName} Findings`, "", `## ${date}`, ""];
+                for (const item of parsed.learnings) {
+                    lines.push(`- ${item.text}`);
+                }
+                lines.push("");
+                return lines.join("\n");
+            };
+            const buildTaskContent = () => {
+                // Prefer the raw task string (lossless: preserves priority/pinned/stable IDs)
+                const taskRaw = parsed.taskRaw;
+                if (typeof taskRaw === "string")
+                    return taskRaw;
+                if (!parsed.task)
+                    return null;
+                const sections = ["Active", "Queue", "Done"];
+                const lines = [`# ${projectName} tasks`, ""];
+                for (const section of sections) {
+                    lines.push(`## ${section}`, "");
+                    const items = parsed.task[section];
+                    if (items) {
+                        for (const item of items) {
+                            const prefix = item.checked || section === "Done" ? "- [x] " : "- [ ] ";
+                            const priorityTag = item.priority ? ` [${item.priority}]` : "";
+                            lines.push(`${prefix}${item.line}${priorityTag}`);
+                            if (item.context)
+                                lines.push(`  Context: ${item.context}`);
+                            if (item.githubIssue || item.githubUrl) {
+                                const githubRef = item.githubIssue && item.githubUrl
+                                    ? `#${item.githubIssue} ${item.githubUrl}`
+                                    : item.githubIssue
+                                        ? `#${item.githubIssue}`
+                                        : item.githubUrl;
+                                lines.push(`  GitHub: ${githubRef}`);
+                            }
+                        }
+                    }
+                    lines.push("");
+                }
+                return lines.join("\n");
+            };
+            try {
+                fs.mkdirSync(stagedProjectDir, { recursive: true });
+                if (parsed.summary) {
+                    fs.writeFileSync(path.join(stagedProjectDir, "summary.md"), parsed.summary);
+                    imported.push("summary.md");
+                }
+                if (parsed.claudeMd) {
+                    fs.writeFileSync(path.join(stagedProjectDir, "CLAUDE.md"), parsed.claudeMd);
+                    imported.push("CLAUDE.md");
+                }
+                const findingsRaw = parsed.findingsRaw;
+                const findingsContent = typeof findingsRaw === "string" ? findingsRaw : buildFindingsContent();
+                if (findingsContent) {
+                    fs.writeFileSync(path.join(stagedProjectDir, "FINDINGS.md"), findingsContent);
+                    imported.push("FINDINGS.md");
+                }
+                const taskContent = buildTaskContent();
+                if (taskContent) {
+                    fs.writeFileSync(path.join(stagedProjectDir, TASKS_FILENAME), taskContent);
+                    imported.push(TASKS_FILENAME);
+                }
+                const backupDir = overwrite ? path.join(phrenPath, `${projectName}.import-backup-${Date.now()}`) : null;
+                try {
+                    if (overwrite && fs.existsSync(projectDir)) {
+                        fs.renameSync(projectDir, backupDir);
+                    }
+                    fs.renameSync(stagedProjectDir, projectDir);
+                    cleanupDir(stagingRoot);
+                }
+                catch (error) {
+                    if (backupDir && fs.existsSync(backupDir) && !fs.existsSync(projectDir)) {
+                        fs.renameSync(backupDir, projectDir);
+                    }
+                    cleanupDir(stagingRoot);
+                    return mcpResponse({
+                        ok: false,
+                        error: error instanceof Error ? `Failed to finalize import: ${error.message}` : "Failed to finalize import.",
+                        errorCode: "INTERNAL_ERROR",
+                    });
+                }
+            }
+            catch (error) {
+                cleanupDir(stagingRoot);
+                return mcpResponse({
+                    ok: false,
+                    error: error instanceof Error ? `Failed to stage import: ${error.message}` : "Failed to stage import.",
+                    errorCode: "INTERNAL_ERROR",
+                });
+            }
+            // Wrap rebuildIndex in a try/catch so that indexing failures trigger backup restore.
+            try {
+                await rebuildIndex();
+            }
+            catch (indexError) {
+                // Index rebuild failed — restore backup if we replaced the project dir
+                if (overwrite) {
+                    // Find the backup dir that was created earlier
+                    try {
+                        for (const entry of fs.readdirSync(phrenPath)) {
+                            if (entry.startsWith(`${projectName}.import-backup-`)) {
+                                const backupPath = path.join(phrenPath, entry);
+                                if (fs.existsSync(backupPath) && !fs.existsSync(projectDir)) {
+                                    fs.renameSync(backupPath, projectDir);
+                                }
+                                else if (fs.existsSync(backupPath)) {
+                                    // Active dir exists — remove imported dir then restore backup
+                                    fs.rmSync(projectDir, { recursive: true, force: true });
+                                    fs.renameSync(backupPath, projectDir);
+                                }
+                                break;
+                            }
+                        }
+                    }
+                    catch (err) {
+                        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                            process.stderr.write(`[phren] import_project backupRestore: ${err instanceof Error ? err.message : String(err)}\n`);
+                    }
+                }
+                return mcpResponse({
+                    ok: false,
+                    error: indexError instanceof Error ? `Index rebuild failed after import: ${indexError.message}` : "Index rebuild failed after import.",
+                    errorCode: "INTERNAL_ERROR",
+                });
+            }
+            // Backup is only deleted after successful rebuild so we can restore on failure
+            if (overwrite) {
+                try {
+                    for (const entry of fs.readdirSync(phrenPath)) {
+                        if (entry.startsWith(`${projectName}.import-backup-`)) {
+                            fs.rmSync(path.join(phrenPath, entry), { recursive: true, force: true });
+                        }
+                    }
+                }
+                catch (err) {
+                    if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                        process.stderr.write(`[phren] import_project backupCleanup: ${err instanceof Error ? err.message : String(err)}\n`);
+                }
+            }
+            return mcpResponse({
+                ok: true,
+                message: `Imported project "${projectName}": ${imported.join(", ")}`,
+                data: { project: projectName, files: imported, overwrite },
+            });
+        });
+    });
+    server.registerTool("manage_project", {
+        title: "◆ phren · manage project",
+        description: "Archive or unarchive a project. Archive moves it out of the active index without deleting data (renamed with .archived suffix). Unarchive restores it.",
+        inputSchema: z.object({
+            project: z.string().describe("Project name."),
+            action: z.enum(["archive", "unarchive"]).describe("Action to perform."),
+        }),
+    }, async ({ project, action }) => {
+        if (!isValidProjectName(project))
+            return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
+        return withWriteQueue(async () => {
+            const activeProject = findProjectNameCaseInsensitive(phrenPath, project);
+            const projectDir = path.join(phrenPath, project);
+            const archiveDir = path.join(phrenPath, `${project}.archived`);
+            if (action === "archive") {
+                if (!fs.existsSync(projectDir)) {
+                    return mcpResponse({ ok: false, error: `Project "${project}" not found.` });
+                }
+                if (fs.existsSync(archiveDir)) {
+                    return mcpResponse({ ok: false, error: `Archive "${project}.archived" already exists. Unarchive or remove it first.` });
+                }
+                fs.renameSync(projectDir, archiveDir);
+                await rebuildIndex();
+                return mcpResponse({
+                    ok: true,
+                    message: `Archived project "${project}". Data preserved at ${archiveDir}.`,
+                    data: { project, archivePath: archiveDir },
+                });
+            }
+            // unarchive
+            if (activeProject) {
+                return mcpResponse({ ok: false, error: `Project "${activeProject}" already exists as an active project.` });
+            }
+            if (!fs.existsSync(archiveDir)) {
+                const entries = fs.readdirSync(phrenPath).filter((e) => e.endsWith(".archived"));
+                const available = entries.map((e) => e.replace(/\.archived$/, ""));
+                return mcpResponse({ ok: false, error: `No archive found for "${project}".`, data: { availableArchives: available } });
+            }
+            fs.renameSync(archiveDir, projectDir);
+            await rebuildIndex();
+            return mcpResponse({
+                ok: true,
+                message: `Unarchived project "${project}". It is now active again.`,
+                data: { project, path: projectDir },
+            });
+        }); // end withWriteQueue
+    });
+}

package/mcp/dist/mcp-extract-facts.js

@@ -0,0 +1,78 @@
+/**
+ * Structured fact extraction from findings (PHREN_FEATURE_FACT_EXTRACT=1).
+ * Each new finding is passed to an LLM that extracts a preference or fact
+ * ("prefers X", "uses Y", "avoids Z"). Stored in project/preferences.json
+ * and surfaced in session_start.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { debugLog } from "./shared.js";
+import { safeProjectPath, isFeatureEnabled, errorMessage } from "./utils.js";
+import { callLlm } from "./content-dedup.js";
+const FACT_EXTRACT_FLAG = "PHREN_FEATURE_FACT_EXTRACT";
+const MAX_FACTS = 50;
+function preferencesPath(phrenPath, project) {
+    const dir = safeProjectPath(phrenPath, project);
+    return dir ? path.join(dir, "preferences.json") : null;
+}
+export function readExtractedFacts(phrenPath, project) {
+    const p = preferencesPath(phrenPath, project);
+    if (!p)
+        return [];
+    try {
+        const data = JSON.parse(fs.readFileSync(p, "utf8"));
+        return Array.isArray(data) ? data : [];
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] readExtractedFacts: ${errorMessage(err)}\n`);
+        return [];
+    }
+}
+function writeExtractedFacts(phrenPath, project, facts) {
+    const p = preferencesPath(phrenPath, project);
+    if (!p)
+        return;
+    try {
+        const trimmed = facts.slice(-MAX_FACTS);
+        const tmp = `${p}.tmp-${process.pid}-${Date.now()}`;
+        fs.writeFileSync(tmp, JSON.stringify(trimmed, null, 2));
+        fs.renameSync(tmp, p);
+    }
+    catch (err) {
+        debugLog(`writeExtractedFacts: ${errorMessage(err)}`);
+    }
+}
+/**
+ * Fire-and-forget: extract a structured fact from a new finding using an LLM.
+ * Skips silently if the feature flag is off or no LLM is configured.
+ */
+export function extractFactFromFinding(phrenPath, project, finding) {
+    if (!isFeatureEnabled(FACT_EXTRACT_FLAG, false))
+        return;
+    // no LLM configured, skip
+    if (!(process.env.PHREN_LLM_ENDPOINT) && !process.env.ANTHROPIC_API_KEY && !process.env.OPENAI_API_KEY)
+        return;
+    const prompt = `Extract a single user preference, technology choice, or architectural fact from this finding. ` +
+        `Return ONLY a short statement in the format "prefers X", "uses Y", "avoids Z", ` +
+        `or "decided to X because Y". If no clear preference or fact exists, return "none".\n\nFinding: ${finding.slice(0, 500)}`;
+    callLlm(prompt, undefined, 60)
+        .then(raw => {
+        if (!raw || raw.toLowerCase() === "none")
+            return;
+        // cap and strip newlines before storing
+        const fact = raw.replace(/[\r\n]+/g, " ").trim().slice(0, 200);
+        if (!fact)
+            return;
+        // Re-read inside the callback to minimize race window (best-effort; not locked)
+        const existing = readExtractedFacts(phrenPath, project);
+        const normalized = fact.toLowerCase();
+        if (existing.some(f => f.fact.toLowerCase() === normalized))
+            return;
+        existing.push({ fact, source: finding.slice(0, 120), at: new Date().toISOString() });
+        writeExtractedFacts(phrenPath, project, existing);
+    })
+        .catch((err) => {
+        debugLog(`extractFactFromFinding: ${errorMessage(err)}`);
+    });
+}