@phren/cli 0.0.10 → 0.0.12

package/mcp/dist/content-citation.js

@@ -1,5 +1,4 @@
 import * as fs from "fs";
-import { statSync } from "fs";
 import * as path from "path";
 import { debugLog, EXEC_TIMEOUT_MS, EXEC_TIMEOUT_QUICK_MS } from "./shared.js";
 import { errorMessage, runGitOrThrow } from "./utils.js";
@@ -170,8 +169,16 @@ function resolveCitationFile(citation) {
 }
 // Session-scoped caches for git I/O during citation validation.
 // Keyed by "repo\0commit" and "repo\0file\0line" respectively.
+const MAX_CACHE_ENTRIES = 500;
 const commitExistsCache = new Map();
 const blameCache = new Map();
+function evictOldest(cache) {
+    if (cache.size <= MAX_CACHE_ENTRIES)
+        return;
+    const first = cache.keys().next().value;
+    if (first !== undefined)
+        cache.delete(first);
+}
 function commitExists(repoPath, commit) {
     const key = `${repoPath}\0${commit}`;
     const cached = commitExistsCache.get(key);
@@ -180,11 +187,13 @@ function commitExists(repoPath, commit) {
     try {
         runGitOrThrow(repoPath, ["cat-file", "-e", `${commit}^{commit}`], EXEC_TIMEOUT_QUICK_MS);
         commitExistsCache.set(key, true);
+        evictOldest(commitExistsCache);
         return true;
     }
     catch (err) {
         debugLog(`commitExists: commit ${commit} not found in ${repoPath}: ${errorMessage(err)}`);
         commitExistsCache.set(key, false);
+        evictOldest(commitExistsCache);
         return false;
     }
 }
@@ -197,11 +206,13 @@ function cachedBlame(repoPath, relFile, line) {
         const out = runGitOrThrow(repoPath, ["blame", "-L", `${line},${line}`, "--porcelain", relFile], 10_000).trim();
         const first = out.split("\n")[0] || "";
         blameCache.set(key, first);
+        evictOldest(blameCache);
         return first;
     }
     catch (err) {
         debugLog(`cachedBlame: git blame failed for ${relFile}:${line}: ${errorMessage(err)}`);
         blameCache.set(key, false);
+        evictOldest(blameCache);
         return false;
     }
 }
@@ -274,7 +285,7 @@ function confidenceForAge(ageDays, decay) {
 }
 function wasFileModifiedAfter(filePath, findingDate) {
     try {
-        const stat = statSync(filePath);
+        const stat = fs.statSync(filePath);
         const fileModified = stat.mtime.toISOString().slice(0, 10);
         return fileModified > findingDate;
     }

package/mcp/dist/content-dedup.js

@@ -2,7 +2,7 @@ import * as fs from "fs";
 import * as path from "path";
 import * as crypto from "crypto";
 import { debugLog, runtimeFile, KNOWN_OBSERVATION_TAGS } from "./shared.js";
-import { isFeatureEnabled, safeProjectPath } from "./utils.js";
+import { isFeatureEnabled, safeProjectPath, errorMessage } from "./utils.js";
 import { UNIVERSAL_TECH_TERMS_RE, EXTRA_ENTITY_PATTERNS } from "./phren-core.js";
 import { isInactiveFindingLine } from "./finding-lifecycle.js";
 // ── LLM provider abstraction ────────────────────────────────────────────────
@@ -50,8 +50,8 @@ async function withCache(cachePath, key, ttlMs, compute) {
         }
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] withCache load (${path.basename(cachePath)}): ${err instanceof Error ? err.message : String(err)}\n`);
+        if ((process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] withCache load (${path.basename(cachePath)}): ${errorMessage(err)}\n`);
     }
     const result = await compute();
     // Persist result
@@ -61,8 +61,8 @@ async function withCache(cachePath, key, ttlMs, compute) {
         persistCache(cachePath, cache);
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] withCache persist (${path.basename(cachePath)}): ${err instanceof Error ? err.message : String(err)}\n`);
+        if ((process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] withCache persist (${path.basename(cachePath)}): ${errorMessage(err)}\n`);
     }
     return result;
 }
@@ -562,8 +562,8 @@ export async function checkSemanticConflicts(phrenPath, project, newFinding, sig
                 return { name: e.name, mtime: fs.statSync(fp).mtimeMs, fp };
             }
             catch (err) {
-                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
-                    process.stderr.write(`[phren] crossProjectScan stat: ${err instanceof Error ? err.message : String(err)}\n`);
+                if ((process.env.PHREN_DEBUG))
+                    process.stderr.write(`[phren] crossProjectScan stat: ${errorMessage(err)}\n`);
                 return null;
             }
         })
@@ -577,8 +577,8 @@ export async function checkSemanticConflicts(phrenPath, project, newFinding, sig
         }
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] crossProjectScan: ${err instanceof Error ? err.message : String(err)}\n`);
+        if ((process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] crossProjectScan: ${errorMessage(err)}\n`);
     }
     const annotations = [];
     const deadline = Date.now() + CONFLICT_CHECK_TOTAL_TIMEOUT_MS;

package/mcp/dist/content-learning.js

@@ -378,7 +378,7 @@ export function addFindingToFile(phrenPath, project, learning, citationInput, op
     if (!result.ok)
         return result;
     if (typeof result.data === "string")
-        return phrenOk(result.data);
+        return phrenOk({ message: result.data, status: "skipped" });
     appendAuditLog(phrenPath, "add_finding", `project=${project}${result.data.created ? " created=true" : ""} citation_commit=${result.data.citation.commit ?? "none"} citation_file=${result.data.citation.file ?? "none"}`);
     const cap = Number.parseInt((process.env.PHREN_FINDINGS_CAP) || "", 10) || DEFAULT_FINDINGS_CAP;
     const activeCount = countActiveFindings(result.data.content);
@@ -390,10 +390,12 @@ export function addFindingToFile(phrenPath, project, learning, citationInput, op
     }
     if (result.data.created) {
         const createdMsg = `Created FINDINGS.md for "${project}" and added insight.`;
-        return phrenOk(result.data.tagWarning ? `${createdMsg} Warning: ${result.data.tagWarning}` : createdMsg);
+        const message = result.data.tagWarning ? `${createdMsg} Warning: ${result.data.tagWarning}` : createdMsg;
+        return phrenOk({ message, status: "created" });
     }
     const addedMsg = `Added finding to ${project}: ${result.data.bullet} (with citation metadata)`;
-    return phrenOk(result.data.tagWarning ? `${addedMsg} Warning: ${result.data.tagWarning}` : addedMsg);
+    const message = result.data.tagWarning ? `${addedMsg} Warning: ${result.data.tagWarning}` : addedMsg;
+    return phrenOk({ message, status: "added" });
 }
 export function addFindingsToFile(phrenPath, project, learnings, opts) {
     if (!isValidProjectName(project))
@@ -402,8 +404,8 @@ export function addFindingsToFile(phrenPath, project, learnings, opts) {
     if (!resolvedDir)
         return phrenErr(`Invalid project name: "${project}".`, PhrenError.INVALID_PROJECT_NAME);
     const learningsPath = path.join(resolvedDir, "FINDINGS.md");
-    const today = new Date().toISOString().slice(0, 10);
     const nowIso = new Date().toISOString();
+    const today = nowIso.slice(0, 10);
     const resolvedCitationInputResult = resolveFindingCitationInput(phrenPath, project);
     if (!resolvedCitationInputResult.ok)
         return resolvedCitationInputResult;

package/mcp/dist/content-metadata.js

@@ -172,6 +172,16 @@ export function stripAllMetadata(line) {
 export function stripComments(text) {
     return text.replace(METADATA_REGEX.anyComment, "").trim();
 }
+/** Normalize finding text for comparison: strips bullet prefix, HTML comments, confidence tags, normalizes whitespace, lowercases. */
+export function normalizeFindingText(raw) {
+    return raw
+        .replace(/^-\s+/, "")
+        .replace(/<!--.*?-->/g, " ")
+        .replace(/\[confidence\s+[01](?:\.\d+)?\]/gi, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .toLowerCase();
+}
 // ---------------------------------------------------------------------------
 // Add helpers — append metadata comments to a line
 // ---------------------------------------------------------------------------

package/mcp/dist/core-finding.js

@@ -18,7 +18,7 @@ export function addFinding(phrenPath, project, finding, citation, findingType) {
     if (!result.ok) {
         return { ok: false, message: result.error };
     }
-    return { ok: true, message: result.data, data: { project, finding: taggedFinding } };
+    return { ok: true, message: result.data.message, data: { project, finding: taggedFinding } };
 }
 /**
  * Remove a finding by partial text match.

package/mcp/dist/data-access.js

@@ -2,38 +2,17 @@ import * as fs from "fs";
 import * as path from "path";
 import * as yaml from "js-yaml";
 import { phrenErr, PhrenError, phrenOk, forwardErr, getProjectDirs, isRecord, } from "./shared.js";
-import { normalizeQueueEntryText, withFileLock as withFileLockRaw, } from "./shared-governance.js";
+import { normalizeQueueEntryText, } from "./shared-governance.js";
 import { addFindingToFile, } from "./shared-content.js";
-import { isValidProjectName, queueFilePath, safeProjectPath, errorMessage } from "./utils.js";
+import { isValidProjectName, queueFilePath, safeProjectPath } from "./utils.js";
 import { parseCitationComment, parseSourceComment, } from "./content-citation.js";
 import { parseFindingLifecycle, } from "./finding-lifecycle.js";
-import { METADATA_REGEX, isCitationLine, isArchiveStart, isArchiveEnd, parseFindingId, parseAllContradictions, stripComments, } from "./content-metadata.js";
+import { METADATA_REGEX, isCitationLine, isArchiveStart, isArchiveEnd, parseFindingId, parseAllContradictions, stripComments, normalizeFindingText, } from "./content-metadata.js";
+import { withSafeLock, ensureProject } from "./shared-data-utils.js";
 export { readTasks, readTasksAcrossProjects, resolveTaskItem, addTask, addTasks, completeTasks, completeTask, removeTask, removeTasks, updateTask, linkTaskIssue, pinTask, unpinTask, workNextTask, tidyDoneTasks, taskMarkdown, appendChildFinding, promoteTask, TASKS_FILENAME, TASK_FILE_ALIASES, canonicalTaskFilePath, resolveTaskFilePath, isTaskFileName, } from "./data-tasks.js";
 export { addProjectToProfile, listMachines, listProfiles, listProjectCards, removeProjectFromProfile, setMachineProfile, } from "./profile-store.js";
-export { loadShellState, readRuntimeHealth, resetShellState, saveShellState, } from "./shell-state-store.js";
-function withSafeLock(filePath, fn) {
-    try {
-        return withFileLockRaw(filePath, fn);
-    }
-    catch (err) {
-        const msg = errorMessage(err);
-        if (msg.includes("could not acquire lock")) {
-            return phrenErr(`Could not acquire write lock for "${path.basename(filePath)}". Another write may be in progress; please retry.`, PhrenError.LOCK_TIMEOUT);
-        }
-        throw err;
-    }
-}
-function ensureProject(phrenPath, project) {
-    if (!isValidProjectName(project))
-        return phrenErr(`Project name "${project}" is not valid. Use lowercase letters, numbers, and hyphens (e.g. "my-project").`, PhrenError.INVALID_PROJECT_NAME);
-    const dir = safeProjectPath(phrenPath, project);
-    if (!dir)
-        return phrenErr(`Project name "${project}" is not valid. Use lowercase letters, numbers, and hyphens (e.g. "my-project").`, PhrenError.INVALID_PROJECT_NAME);
-    if (!fs.existsSync(dir)) {
-        return phrenErr(`No project "${project}" found. Add it with 'cd ~/your-project && phren add'.`, PhrenError.PROJECT_NOT_FOUND);
-    }
-    return phrenOk(dir);
-}
+export { loadShellState, resetShellState, saveShellState, } from "./shell-state-store.js";
+export { getRuntimeHealth as readRuntimeHealth } from "./shared-governance.js";
 function extractDateHeading(line) {
     const heading = line.match(/^##\s+(.+)$/);
     if (!heading)
@@ -79,8 +58,8 @@ function findMatchingFindingBullet(bulletLines, needle, match) {
     const fidMatch = /^[a-z0-9]{8}$/.test(fidNeedle)
         ? bulletLines.filter(({ line }) => new RegExp(`<!--\\s*fid:${fidNeedle}\\s*-->`).test(line))
         : [];
-    const exactMatches = bulletLines.filter(({ line }) => line.replace(/^-\s+/, "").replace(/<!--.*?-->/g, "").trim().toLowerCase() === needle);
-    const partialMatches = bulletLines.filter(({ line }) => line.toLowerCase().includes(needle));
+    const exactMatches = bulletLines.filter(({ line }) => normalizeFindingText(line) === needle);
+    const partialMatches = bulletLines.filter(({ line }) => normalizeFindingText(line).includes(needle));
     if (fidMatch.length === 1)
         return { kind: "found", idx: fidMatch[0].i };
     if (exactMatches.length === 1)
@@ -276,7 +255,7 @@ export function removeFinding(phrenPath, project, match) {
         return phrenErr(`No FINDINGS.md file found for "${project}". Add a finding first with add_finding or :find add.`, PhrenError.FILE_NOT_FOUND);
     return withSafeLock(filePath, () => {
         const lines = fs.readFileSync(filePath, "utf8").split("\n");
-        const needle = match.trim().toLowerCase();
+        const needle = normalizeFindingText(match);
         const bulletLines = collectFindingBulletLines(lines);
         const activeMatch = findMatchingFindingBullet(bulletLines.filter(({ archived }) => !archived), needle, match);
         if (activeMatch.kind === "ambiguous") {
@@ -313,7 +292,7 @@ export function editFinding(phrenPath, project, oldText, newText) {
         return phrenErr(`No FINDINGS.md file found for "${project}".`, PhrenError.FILE_NOT_FOUND);
     return withSafeLock(findingsPath, () => {
         const lines = fs.readFileSync(findingsPath, "utf8").split("\n");
-        const needle = oldText.trim().toLowerCase();
+        const needle = normalizeFindingText(oldText);
         const bulletLines = collectFindingBulletLines(lines);
         const activeMatch = findMatchingFindingBullet(bulletLines.filter(({ archived }) => !archived), needle, oldText);
         if (activeMatch.kind === "ambiguous") {

package/mcp/dist/data-tasks.js

@@ -2,21 +2,9 @@ import * as fs from "fs";
 import * as path from "path";
 import { randomBytes, randomUUID } from "crypto";
 import { phrenErr, PhrenError, phrenOk, forwardErr, getProjectDirs, } from "./shared.js";
-import { withFileLock as withFileLockRaw } from "./shared-governance.js";
 import { validateTaskFormat } from "./shared-content.js";
-import { isValidProjectName, safeProjectPath, errorMessage } from "./utils.js";
-function withSafeLock(filePath, fn) {
-    try {
-        return withFileLockRaw(filePath, fn);
-    }
-    catch (err) {
-        const msg = errorMessage(err);
-        if (msg.includes("could not acquire lock")) {
-            return phrenErr(`Could not acquire write lock for "${path.basename(filePath)}". Another write may be in progress; please retry.`, PhrenError.LOCK_TIMEOUT);
-        }
-        throw err;
-    }
-}
+import { safeProjectPath } from "./utils.js";
+import { withSafeLock, ensureProject } from "./shared-data-utils.js";
 const ACTIVE_HEADINGS = new Set(["active", "in progress", "in-progress", "current", "wip"]);
 const QUEUE_HEADINGS = new Set(["queue", "queued", "task", "todo", "upcoming", "next"]);
 const DONE_HEADINGS = new Set(["done", "completed", "finished", "archived"]);
@@ -108,17 +96,6 @@ function parseContinuation(lines, idx) {
     }
     return { context, githubIssue, githubUrl, linesToSkip };
 }
-function ensureProject(phrenPath, project) {
-    if (!isValidProjectName(project))
-        return phrenErr(`Project name "${project}" is not valid. Use lowercase letters, numbers, and hyphens (e.g. "my-project").`, PhrenError.INVALID_PROJECT_NAME);
-    const dir = safeProjectPath(phrenPath, project);
-    if (!dir)
-        return phrenErr(`Project name "${project}" is not valid. Use lowercase letters, numbers, and hyphens (e.g. "my-project").`, PhrenError.INVALID_PROJECT_NAME);
-    if (!fs.existsSync(dir)) {
-        return phrenErr(`No project "${project}" found. Add it with 'cd ~/your-project && phren add'.`, PhrenError.PROJECT_NOT_FOUND);
-    }
-    return phrenOk(dir);
-}
 /** Pattern that matches the task metadata comment embedded in task item lines.
  *  Format: <!-- bid:HASH [rank:N] [lastActivity:ISO] -->
  */
@@ -808,7 +785,9 @@ export function tidyDoneTasks(phrenPath, project, keep = 30, dryRun) {
         const lines = archived.map((item) => `- [x] ${item.line}${item.context ? `\n  Context: ${item.context}` : ""}`);
         const block = `## ${stamp}\n\n${lines.join("\n")}\n\n`;
         const prior = fs.existsSync(archiveFile) ? fs.readFileSync(archiveFile, "utf8") : `# ${project} tasks archive\n\n`;
-        fs.writeFileSync(archiveFile, prior + block);
+        const tmpPath = `${archiveFile}.tmp-${randomUUID()}`;
+        fs.writeFileSync(tmpPath, prior + block);
+        fs.renameSync(tmpPath, archiveFile);
         writeTaskDoc(parsed.data);
         return phrenOk(`Tidied ${project}: archived ${archived.length} done item(s), kept ${safeKeep}.`);
     });

package/mcp/dist/embedding.js

@@ -79,7 +79,7 @@ async function openCacheDb(phrenPath) {
             db?.close();
         }
         catch (e2) {
-            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            if ((process.env.PHREN_DEBUG))
                 process.stderr.write(`[phren] embedding openCacheDb dbClose: ${e2 instanceof Error ? e2.message : String(e2)}\n`);
         }
         throw err;
@@ -126,13 +126,13 @@ function persistDb(phrenPath, db) {
                 }
             }
             catch (err) {
-                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
-                    process.stderr.write(`[phren] embedding persistDb onDiskLoad: ${err instanceof Error ? err.message : String(err)}\n`);
+                if ((process.env.PHREN_DEBUG))
+                    process.stderr.write(`[phren] embedding persistDb onDiskLoad: ${errorMessage(err)}\n`);
                 try {
                     onDisk?.close();
                 }
                 catch (e2) {
-                    if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                    if ((process.env.PHREN_DEBUG))
                         process.stderr.write(`[phren] embedding persistDb onDiskClose: ${e2 instanceof Error ? e2.message : String(e2)}\n`);
                 }
                 onDisk = null;
@@ -149,7 +149,7 @@ function persistDb(phrenPath, db) {
                         onDisk.close();
                     }
                     catch (e2) {
-                        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                        if ((process.env.PHREN_DEBUG))
                             process.stderr.write(`[phren] embedding persistDb onDiskCloseFinally: ${e2 instanceof Error ? e2.message : String(e2)}\n`);
                     }
             }
@@ -269,7 +269,7 @@ export async function getCachedEmbedding(phrenPath, text, apiKey, model) {
             db?.close();
         }
         catch (e2) {
-            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            if ((process.env.PHREN_DEBUG))
                 process.stderr.write(`[phren] embedding getCachedEmbedding dbClose: ${e2 instanceof Error ? e2.message : String(e2)}\n`);
         }
     }
@@ -320,7 +320,7 @@ export async function getCachedEmbeddings(phrenPath, texts, apiKey, model) {
             db?.close();
         }
         catch (e2) {
-            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            if ((process.env.PHREN_DEBUG))
                 process.stderr.write(`[phren] embedding getCachedEmbeddings dbClose: ${e2 instanceof Error ? e2.message : String(e2)}\n`);
         }
     }
@@ -340,5 +340,4 @@ export function cosineSimilarity(a, b) {
     const denom = Math.sqrt(normA) * Math.sqrt(normB);
     return denom === 0 ? 0 : dot / denom;
 }
-// Export helpers for testing
 export { encodeEmbedding, decodeEmbedding, openCacheDb };