@phren/cli 0.0.11 → 0.0.13

package/mcp/dist/link-doctor.js

@@ -2,6 +2,7 @@ import * as fs from "fs";
 import * as path from "path";
 import { execFileSync } from "child_process";
 import { debugLog, EXEC_TIMEOUT_QUICK_MS, getProjectDirs, isRecord, homeDir, homePath, hookConfigPath, runtimeHealthFile, } from "./shared.js";
+import { commandVersion, versionAtLeast, nearestWritableTarget } from "./init-shared.js";
 import { validateGovernanceJson } from "./shared-governance.js";
 import { errorMessage } from "./utils.js";
 import { buildIndex, queryRows } from "./shared-index.js";
@@ -34,53 +35,6 @@ function isWrapperActive(tool) {
         return false;
     }
 }
-function commandVersion(cmd, args = ["--version"]) {
-    try {
-        return execFileSync(cmd, args, {
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"],
-            timeout: EXEC_TIMEOUT_QUICK_MS,
-        }).trim();
-    }
-    catch (err) {
-        debugLog(`doctor: commandVersion ${cmd} failed: ${errorMessage(err)}`);
-        return null;
-    }
-}
-function parseSemverTriple(raw) {
-    const match = raw.match(/(\d+)\.(\d+)\.(\d+)/);
-    if (!match)
-        return null;
-    return [Number.parseInt(match[1], 10), Number.parseInt(match[2], 10), Number.parseInt(match[3], 10)];
-}
-function versionAtLeast(raw, major, minor = 0) {
-    if (!raw)
-        return false;
-    const parsed = parseSemverTriple(raw);
-    if (!parsed)
-        return false;
-    const [m, n] = parsed;
-    if (m !== major)
-        return m > major;
-    return n >= minor;
-}
-function nearestWritableTarget(filePath) {
-    let probe = fs.existsSync(filePath) ? filePath : path.dirname(filePath);
-    while (!fs.existsSync(probe)) {
-        const parent = path.dirname(probe);
-        if (parent === probe)
-            return false;
-        probe = parent;
-    }
-    try {
-        fs.accessSync(probe, fs.constants.W_OK);
-        return true;
-    }
-    catch (err) {
-        debugLog(`doctor: writable check failed for ${filePath}: ${errorMessage(err)}`);
-        return false;
-    }
-}
 function gitRemoteStatus(phrenPath) {
     try {
         execFileSync("git", ["-C", phrenPath, "rev-parse", "--is-inside-work-tree"], {
@@ -375,6 +329,7 @@ export async function runDoctor(phrenPath, fix = false, checkData = false) {
     const detected = detectInstalledTools();
     if (detected.has("copilot")) {
         const copilotHooks = hookConfigPath("copilot", phrenPath);
+        const copilotWritable = nearestWritableTarget(copilotHooks);
         checks.push({
             name: "copilot-hooks",
             ok: fs.existsSync(copilotHooks),
@@ -382,12 +337,13 @@ export async function runDoctor(phrenPath, fix = false, checkData = false) {
         });
         checks.push({
             name: "copilot-config-writable",
-            ok: nearestWritableTarget(copilotHooks),
-            detail: nearestWritableTarget(copilotHooks) ? `writable: ${copilotHooks}` : `not writable: ${copilotHooks}`,
+            ok: copilotWritable,
+            detail: copilotWritable ? `writable: ${copilotHooks}` : `not writable: ${copilotHooks}`,
         });
     }
     if (detected.has("cursor")) {
         const cursorHooks = hookConfigPath("cursor", phrenPath);
+        const cursorWritable = nearestWritableTarget(cursorHooks);
         checks.push({
             name: "cursor-hooks",
             ok: fs.existsSync(cursorHooks),
@@ -395,12 +351,13 @@ export async function runDoctor(phrenPath, fix = false, checkData = false) {
         });
         checks.push({
             name: "cursor-config-writable",
-            ok: nearestWritableTarget(cursorHooks),
-            detail: nearestWritableTarget(cursorHooks) ? `writable: ${cursorHooks}` : `not writable: ${cursorHooks}`,
+            ok: cursorWritable,
+            detail: cursorWritable ? `writable: ${cursorHooks}` : `not writable: ${cursorHooks}`,
         });
     }
     if (detected.has("codex")) {
         const codexHooks = hookConfigPath("codex", phrenPath);
+        const codexWritable = nearestWritableTarget(codexHooks);
         checks.push({
             name: "codex-hooks",
             ok: fs.existsSync(codexHooks),
@@ -408,8 +365,8 @@ export async function runDoctor(phrenPath, fix = false, checkData = false) {
         });
         checks.push({
             name: "codex-config-writable",
-            ok: nearestWritableTarget(codexHooks),
-            detail: nearestWritableTarget(codexHooks) ? `writable: ${codexHooks}` : `not writable: ${codexHooks}`,
+            ok: codexWritable,
+            detail: codexWritable ? `writable: ${codexHooks}` : `not writable: ${codexHooks}`,
         });
     }
     for (const tool of ["copilot", "cursor", "codex"]) {
@@ -446,7 +403,7 @@ export async function runDoctor(phrenPath, fix = false, checkData = false) {
     }
     else {
         // Read-only mode: just check if hook configs exist, don't write anything
-        const detectedTools = detectInstalledTools();
+        const detectedTools = detected;
         const hookChecks = [];
         const missing = [];
         for (const tool of detectedTools) {

package/mcp/dist/link.js

@@ -4,7 +4,7 @@ import * as readline from "readline";
 import * as yaml from "js-yaml";
 import { execFileSync } from "child_process";
 import { ROOT } from "./package-metadata.js";
-import { configureClaude, configureCodexMcp, configureCopilotMcp, configureCursorMcp, configureVSCode, ensureGovernanceFiles, getHooksEnabledPreference, getMcpEnabledPreference, isVersionNewer, logMcpTargetStatus, patchJsonFile, setMcpEnabledPreference, } from "./init.js";
+import { configureMcpTargets, ensureGovernanceFiles, getHooksEnabledPreference, getMcpEnabledPreference, isVersionNewer, patchJsonFile, setMcpEnabledPreference, } from "./init.js";
 import { configureAllHooks, detectInstalledTools } from "./hooks.js";
 import { getMachineName, persistMachineName } from "./machine-identity.js";
 import { debugLog, EXEC_TIMEOUT_MS, EXEC_TIMEOUT_QUICK_MS, isRecord, homePath, hookConfigPath, installPreferencesFile, atomicWriteText, } from "./shared.js";
@@ -34,7 +34,7 @@ function listProfiles(phrenPath) {
     const listed = listProfilesShared(phrenPath);
     if (!listed.ok)
         return [];
-    return listed.data.map((profile) => ({ name: profile.name, description: "" }));
+    return listed.data.map((profile) => ({ name: profile.name }));
 }
 export function findProfileFile(phrenPath, profileName) {
     const profilesDir = path.join(phrenPath, "profiles");
@@ -94,7 +94,7 @@ async function registerMachine(phrenPath) {
     }
     log("\nAvailable profiles:");
     for (const p of listProfiles(phrenPath))
-        log(`  ${p.name}  (${p.description})`);
+        log(`  ${p.name}`);
     log("");
     const profile = (await ask("Which profile? ")).trim();
     rl.close();
@@ -491,56 +491,7 @@ export async function runLink(phrenPath, opts = {}) {
     log(`  MCP mode: ${mcpEnabled ? "ON (recommended)" : "OFF (hooks-only fallback)"}`);
     log(`  Hooks mode: ${hooksEnabled ? "ON (active)" : "OFF (disabled)"}`);
     maybeOfferStarterTemplateUpdate(phrenPath);
-    let mcpStatus = "no_settings";
-    try {
-        mcpStatus = configureClaude(phrenPath, { mcpEnabled, hooksEnabled }) ?? "installed";
-    }
-    catch (err) {
-        if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] link configureClaude: ${errorMessage(err)}\n`);
-    }
-    logMcpTargetStatus("Claude", mcpStatus);
-    let vsStatus = "no_vscode";
-    try {
-        vsStatus = configureVSCode(phrenPath, { mcpEnabled }) ?? "no_vscode";
-    }
-    catch (err) {
-        if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] link configureVSCode: ${errorMessage(err)}\n`);
-    }
-    logMcpTargetStatus("VS Code", vsStatus);
-    let cursorStatus = "no_cursor";
-    try {
-        cursorStatus = configureCursorMcp(phrenPath, { mcpEnabled }) ?? "no_cursor";
-    }
-    catch (err) {
-        if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] link configureCursorMcp: ${errorMessage(err)}\n`);
-    }
-    logMcpTargetStatus("Cursor", cursorStatus);
-    let copilotStatus = "no_copilot";
-    try {
-        copilotStatus = configureCopilotMcp(phrenPath, { mcpEnabled }) ?? "no_copilot";
-    }
-    catch (err) {
-        if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] link configureCopilotMcp: ${errorMessage(err)}\n`);
-    }
-    logMcpTargetStatus("Copilot CLI", copilotStatus);
-    let codexStatus = "no_codex";
-    try {
-        codexStatus = configureCodexMcp(phrenPath, { mcpEnabled }) ?? "no_codex";
-    }
-    catch (err) {
-        if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] link configureCodexMcp: ${errorMessage(err)}\n`);
-    }
-    logMcpTargetStatus("Codex", codexStatus);
-    const mcpStatusForContext = [mcpStatus, vsStatus, cursorStatus, copilotStatus, codexStatus].some((s) => s === "installed" || s === "already_configured")
-        ? "installed"
-        : [mcpStatus, vsStatus, cursorStatus, copilotStatus, codexStatus].some((s) => s === "disabled" || s === "already_disabled")
-            ? "disabled"
-            : mcpStatus;
+    const mcpStatusForContext = configureMcpTargets(phrenPath, { mcpEnabled, hooksEnabled });
     // Register hooks for Copilot CLI, Cursor, Codex
     if (hooksEnabled) {
         const hookedTools = configureAllHooks(phrenPath, { tools: detectedTools });

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

@@ -9,6 +9,7 @@ import * as path from "path";
 import { debugLog } from "./shared.js";
 import { safeProjectPath, isFeatureEnabled, errorMessage } from "./utils.js";
 import { callLlm } from "./content-dedup.js";
+import { withFileLock } from "./shared-governance.js";
 const FACT_EXTRACT_FLAG = "PHREN_FEATURE_FACT_EXTRACT";
 const MAX_FACTS = 50;
 function preferencesPath(phrenPath, project) {
@@ -64,13 +65,17 @@ export function extractFactFromFinding(phrenPath, project, finding) {
         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))
+        const p = preferencesPath(phrenPath, project);
+        if (!p)
             return;
-        existing.push({ fact, source: finding.slice(0, 120), at: new Date().toISOString() });
-        writeExtractedFacts(phrenPath, project, existing);
+        withFileLock(p, () => {
+            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)}`);

package/mcp/dist/mcp-finding.js

@@ -4,7 +4,7 @@ import * as fs from "fs";
 import * as path from "path";
 import { isValidProjectName, safeProjectPath, errorMessage } from "./utils.js";
 import { removeFinding as removeFindingCore, removeFindings as removeFindingsCore, } from "./core-finding.js";
-import { debugLog, EXEC_TIMEOUT_MS, FINDING_TYPES, normalizeMemoryScope, } from "./shared.js";
+import { debugLog, EXEC_TIMEOUT_MS, FINDING_TYPES, normalizeMemoryScope, RESERVED_PROJECT_DIR_NAMES, } from "./shared.js";
 import { addFindingToFile, addFindingsToFile, checkSemanticConflicts, autoMergeConflicts, } from "./shared-content.js";
 import { jaccardTokenize, jaccardSimilarity, stripMetadata } from "./content-dedup.js";
 import { runCustomHooks } from "./hooks.js";
@@ -17,7 +17,6 @@ import { FINDING_PROVENANCE_SOURCES } from "./content-citation.js";
 import { isInactiveFindingLine, supersedeFinding, retractFinding as retractFindingLifecycle, resolveFindingContradiction, } from "./finding-lifecycle.js";
 const JACCARD_MAYBE_LOW = 0.30;
 const JACCARD_MAYBE_HIGH = 0.55; // above this isDuplicateFinding already catches it
-const RESERVED_PROJECT_DIRS = new Set(["global", ".runtime", ".sessions", ".governance"]);
 function findJaccardCandidates(phrenPath, project, finding) {
     try {
         const findingsPath = path.join(phrenPath, project, "FINDINGS.md");
@@ -134,14 +133,11 @@ export function register(server, ctx) {
                 if (!result.ok) {
                     return mcpResponse({ ok: false, error: result.error });
                 }
-                // Determine status from the returned message string
-                const isSkipped = result.data.startsWith("Skipped duplicate");
-                const isAdded = !isSkipped;
-                if (isSkipped) {
-                    return mcpResponse({ ok: true, message: result.data, data: { project, finding: taggedFinding, status: "skipped" } });
+                if (result.data.status === "skipped") {
+                    return mcpResponse({ ok: true, message: result.data.message, data: { project, finding: taggedFinding, status: "skipped" } });
                 }
                 updateFileInIndex(path.join(phrenPath, project, "FINDINGS.md"));
-                if (isAdded) {
+                if (result.data.status === "added" || result.data.status === "created") {
                     runCustomHooks(phrenPath, "post-finding", { PHREN_PROJECT: project });
                     incrementSessionFindings(phrenPath, 1, sessionId, project);
                     extractFactFromFinding(phrenPath, project, taggedFinding);
@@ -178,7 +174,7 @@ export function register(server, ctx) {
                 }
                 const conflictsWithList = semanticConflicts.checked
                     ? extractConflictsWith(semanticConflicts.annotations)
-                    : (result.data.match(/<!--\s*conflicts_with:\s*"([^"]+)"/)?.[1] ? [result.data.match(/<!--\s*conflicts_with:\s*"([^"]+)"/)[1]] : []);
+                    : (result.data.message.match(/<!--\s*conflicts_with:\s*"([^"]+)"/)?.[1] ? [result.data.message.match(/<!--\s*conflicts_with:\s*"([^"]+)"/)[1]] : []);
                 const conflictsWith = conflictsWithList[0];
                 // Extract fragment hints synchronously from the finding text (regex only, no DB).
                 // Full DB fragment linking happens on the next index rebuild via updateFileInIndex →
@@ -186,11 +182,11 @@ export function register(server, ctx) {
                 const detectedFragments = extractFragmentNames(taggedFinding);
                 return mcpResponse({
                     ok: true,
-                    message: result.data,
+                    message: result.data.message,
                     data: {
                         project,
                         finding: taggedFinding,
-                        status: "added",
+                        status: result.data.status,
                         ...(conflictsWith ? { conflictsWith } : {}),
                         ...(conflictsWithList.length > 0 ? { conflicts: conflictsWithList } : {}),
                         ...(detectedFragments.length > 0 ? { detectedFragments } : {}),
@@ -356,7 +352,7 @@ export function register(server, ctx) {
         const projects = project
             ? [project]
             : fs.readdirSync(phrenPath, { withFileTypes: true })
-                .filter((entry) => entry.isDirectory() && !RESERVED_PROJECT_DIRS.has(entry.name) && isValidProjectName(entry.name))
+                .filter((entry) => entry.isDirectory() && !RESERVED_PROJECT_DIR_NAMES.has(entry.name) && isValidProjectName(entry.name))
                 .map((entry) => entry.name);
         const contradictions = [];
         for (const p of projects) {
@@ -490,8 +486,8 @@ export function register(server, ctx) {
                     .filter((name) => name && !name.startsWith(".") && name !== "profiles")));
                 const commitMsg = message || `phren: save ${files.length} file(s) across ${projectNames.length} project(s)`;
                 runCustomHooks(phrenPath, "pre-save");
-                // Restrict to known phren file types to avoid staging .env or credential files
-                runGit(["add", "--", "*.md", "*.json", "*.yaml", "*.yml", "*.jsonl", "*.txt"]);
+                // Stage all files including untracked (new project dirs, first FINDINGS.md, etc.)
+                runGit(["add", "-A"]);
                 runGit(["commit", "-m", commitMsg]);
                 let hasRemote = false;
                 try {

package/mcp/dist/mcp-graph.js

@@ -9,7 +9,7 @@ import { withFileLock } from "./shared-governance.js";
 export function register(server, ctx) {
     // ── search_fragments ──────────────────────────────────────────────────
     server.registerTool("search_fragments", {
-        title: "phren : search fragments",
+        title: "◆ phren · search fragments",
         description: "Search named fragments in the knowledge graph (libraries, tools, concepts mentioned in findings). " +
             "Returns matching fragment names and how many findings reference each.",
         inputSchema: z.object({
@@ -209,7 +209,7 @@ export function register(server, ctx) {
                 db.run("INSERT OR IGNORE INTO entities (name, type, first_seen_at) VALUES (?, ?, ?)", [fragmentName, resolvedFragmentType, new Date().toISOString().slice(0, 10)]);
             }
             catch (err) {
-                if (process.env.PHREN_DEBUG || (process.env.PHREN_DEBUG))
+                if (process.env.PHREN_DEBUG)
                     process.stderr.write(`[phren] link_findings fragmentInsert: ${errorMessage(err)}\n`);
             }
             const fragmentResult = db.exec("SELECT id FROM entities WHERE name = ? AND type = ?", [fragmentName, resolvedFragmentType]);
@@ -232,7 +232,7 @@ export function register(server, ctx) {
                 db.run("INSERT OR IGNORE INTO entities (name, type, first_seen_at) VALUES (?, ?, ?)", [sourceDoc, "document", new Date().toISOString().slice(0, 10)]);
             }
             catch (err) {
-                if (process.env.PHREN_DEBUG || (process.env.PHREN_DEBUG))
+                if (process.env.PHREN_DEBUG)
                     process.stderr.write(`[phren] link_findings docFragmentInsert: ${errorMessage(err)}\n`);
             }
             const docFragmentResult = db.exec("SELECT id FROM entities WHERE name = ? AND type = ?", [sourceDoc, "document"]);
@@ -245,7 +245,7 @@ export function register(server, ctx) {
                 db.run("INSERT OR IGNORE INTO entity_links (source_id, target_id, rel_type, source_doc) VALUES (?, ?, ?, ?)", [sourceId, targetId, relType, sourceDoc]);
             }
             catch (err) {
-                if (process.env.PHREN_DEBUG || (process.env.PHREN_DEBUG))
+                if (process.env.PHREN_DEBUG)
                     process.stderr.write(`[phren] link_findings linkInsert: ${errorMessage(err)}\n`);
                 return mcpResponse({ ok: false, error: "Failed to insert fragment link." });
             }
@@ -255,7 +255,7 @@ export function register(server, ctx) {
                 db.run("INSERT OR IGNORE INTO global_entities (entity, project, doc_key) VALUES (?, ?, ?)", [fragmentName, project, sourceDoc]);
             }
             catch (err) {
-                if (process.env.PHREN_DEBUG || (process.env.PHREN_DEBUG))
+                if (process.env.PHREN_DEBUG)
                     process.stderr.write(`[phren] link_findings globalFragments: ${errorMessage(err)}\n`);
             }
             // 4b. Persist manual link so it survives index rebuilds (mandatory — failure aborts the operation)
@@ -268,7 +268,7 @@ export function register(server, ctx) {
                             existing = JSON.parse(fs.readFileSync(manualLinksPath, "utf8"));
                         }
                         catch (err) {
-                            if (process.env.PHREN_DEBUG || (process.env.PHREN_DEBUG))
+                            if (process.env.PHREN_DEBUG)
                                 process.stderr.write(`[phren] link_findings manualLinksRead: ${errorMessage(err)}\n`);
                         }
                     }

package/mcp/dist/mcp-hooks.js

@@ -23,7 +23,7 @@ function validateHookCommand(command) {
         return "Command too long (max 1000 characters).";
     // Reject shell metacharacters that allow injection or arbitrary execution
     // when the command is later run via `sh -c`.
-    if (/[`$(){}&|;<>]/.test(trimmed)) {
+    if (/[`$(){}&|;<>\n\r#]/.test(trimmed)) {
         return "Command contains disallowed shell characters: ` $ ( ) { } & | ; < >";
     }
     // eval and source can execute arbitrary code

package/mcp/dist/mcp-search.js

@@ -567,17 +567,12 @@ export function register(server, ctx) {
         if (!isValidProjectName(project))
             return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
         const includeHistory = include_history ?? include_superseded ?? false;
-        const result = readFindings(phrenPath, project, { includeArchived: includeHistory });
+        // Always read with archive so we can compute historyCount without a second read
+        const result = readFindings(phrenPath, project, { includeArchived: true });
         if (!result.ok)
             return mcpResponse({ ok: false, error: result.error });
         const allItems = result.data;
-        let historyCount = allItems.filter(f => f.tier === "archived" || HISTORY_FINDING_STATUSES.has(f.status)).length;
-        if (!includeHistory) {
-            const withArchive = readFindings(phrenPath, project, { includeArchived: true });
-            if (withArchive.ok) {
-                historyCount = withArchive.data.filter(f => f.tier === "archived" || HISTORY_FINDING_STATUSES.has(f.status)).length;
-            }
-        }
+        const historyCount = allItems.filter(f => f.tier === "archived" || HISTORY_FINDING_STATUSES.has(f.status)).length;
         const visibleItems = includeHistory
             ? allItems
             : allItems.filter(f => f.tier !== "archived" && !HISTORY_FINDING_STATUSES.has(f.status));

package/mcp/dist/mcp-session.js

@@ -90,6 +90,7 @@ function extractResumptionHint(summary, fallbackNextStep, fallbackLastAttempt) {
     };
 }
 /** Per-connection session map keyed by arbitrary connection ID (if provided). */
+const MAX_SESSION_MAP_ENTRIES = 200;
 const _sessionMap = new Map();
 function sessionsDir(phrenPath) {
     const dir = path.join(phrenPath, ".runtime", "sessions");
@@ -151,7 +152,10 @@ function lastSummaryPath(phrenPath) {
 function writeLastSummary(phrenPath, summary, sessionId, project) {
     try {
         const data = { summary, sessionId, project, endedAt: new Date().toISOString() };
-        fs.writeFileSync(lastSummaryPath(phrenPath), JSON.stringify(data, null, 2));
+        const summaryFile = lastSummaryPath(phrenPath);
+        const tmpPath = `${summaryFile}.tmp-${crypto.randomUUID()}`;
+        fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2));
+        fs.renameSync(tmpPath, summaryFile);
     }
     catch (err) {
         debugError("writeLastSummary", err);
@@ -417,8 +421,14 @@ export function register(server, ctx) {
         };
         const newFile = sessionFileForId(phrenPath, sessionId);
         writeSessionStateFile(newFile, next);
-        if (connectionId)
+        if (connectionId) {
             _sessionMap.set(connectionId, sessionId);
+            if (_sessionMap.size > MAX_SESSION_MAP_ENTRIES) {
+                const oldest = _sessionMap.keys().next().value;
+                if (oldest !== undefined)
+                    _sessionMap.delete(oldest);
+            }
+        }
         const parts = [];
         if (priorSummary) {
             parts.push(`## Last session\n${priorSummary}`);