@phren/cli 0.1.33 → 0.1.35
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/cli/config-proactivity.js +12 -6
- package/dist/cli/config-synonyms.js +7 -4
- package/dist/cli/hooks.js +7 -3
- package/dist/cli/session-background.js +5 -6
- package/dist/cli/session-tool-hook.js +2 -0
- package/dist/cli/team.js +26 -13
- package/dist/cli-registry.js +11 -0
- package/dist/content/dedup.js +25 -3
- package/dist/content/learning.js +10 -16
- package/dist/finding/impact.js +4 -0
- package/dist/governance/scores.js +26 -45
- package/dist/index.js +67 -32
- package/dist/init/config.js +2 -2
- package/dist/link/skills.js +1 -1
- package/dist/logger.js +19 -0
- package/dist/phren-paths.d.ts +6 -0
- package/dist/phren-paths.js +17 -0
- package/dist/shared/index.d.ts +16 -0
- package/dist/shared/index.js +163 -17
- package/dist/shared/retrieval.js +25 -6
- package/dist/telemetry.js +4 -1
- package/dist/tools/finding.d.ts +1 -0
- package/dist/tools/finding.js +40 -2
- package/package.json +3 -3
package/dist/init/config.js
CHANGED
|
@@ -305,11 +305,11 @@ export function configureClaude(phrenPath, opts = {}) {
|
|
|
305
305
|
upsertPhrenHook("UserPromptSubmit", {
|
|
306
306
|
type: "command",
|
|
307
307
|
command: lifecycle.userPromptSubmit || `node "${entryScript}" hook-prompt`,
|
|
308
|
-
timeout:
|
|
308
|
+
timeout: 10,
|
|
309
309
|
});
|
|
310
310
|
// Mirror pre-prompt custom hooks into Claude's settings.json as
|
|
311
311
|
// peer UserPromptSubmit entries so they run in parallel with phren
|
|
312
|
-
// and don't share its
|
|
312
|
+
// and don't share its timeout budget. See
|
|
313
313
|
// upsertCustomPrePromptSiblings docstring for details.
|
|
314
314
|
try {
|
|
315
315
|
upsertCustomPrePromptSiblings(hooksMap, phrenPath);
|
package/dist/link/skills.js
CHANGED
package/dist/logger.js
CHANGED
|
@@ -1,13 +1,32 @@
|
|
|
1
1
|
import * as fs from "fs";
|
|
2
2
|
import { runtimeFile, findPhrenPath } from "./shared.js";
|
|
3
3
|
let _cachedPhrenPath;
|
|
4
|
+
const LOG_MAX_BYTES = 5_000_000; // rotate debug.log past ~5MB
|
|
5
|
+
const LOG_KEEP_LINES = 2000; // keep the most recent lines on rotation
|
|
6
|
+
/** Truncate debug.log to its last LOG_KEEP_LINES if it has grown past the cap. */
|
|
7
|
+
function rotateIfLarge(logPath) {
|
|
8
|
+
try {
|
|
9
|
+
if (fs.statSync(logPath).size <= LOG_MAX_BYTES)
|
|
10
|
+
return;
|
|
11
|
+
const lines = fs.readFileSync(logPath, "utf-8").split("\n");
|
|
12
|
+
fs.writeFileSync(logPath, lines.slice(-LOG_KEEP_LINES).join("\n"));
|
|
13
|
+
}
|
|
14
|
+
catch {
|
|
15
|
+
// statSync ENOENT (no file yet) or any IO error — nothing to rotate
|
|
16
|
+
}
|
|
17
|
+
}
|
|
4
18
|
export function log(level, tool, message, extra) {
|
|
5
19
|
try {
|
|
20
|
+
// debug-level logging is opt-in (matches debugLog). It was the bulk of the
|
|
21
|
+
// 30MB debug.log — mostly expected-ENOENT noise logged on the normal path.
|
|
22
|
+
if (level === "debug" && !process.env.PHREN_DEBUG)
|
|
23
|
+
return;
|
|
6
24
|
if (_cachedPhrenPath === undefined)
|
|
7
25
|
_cachedPhrenPath = findPhrenPath();
|
|
8
26
|
if (!_cachedPhrenPath)
|
|
9
27
|
return;
|
|
10
28
|
const logPath = runtimeFile(_cachedPhrenPath, "debug.log");
|
|
29
|
+
rotateIfLarge(logPath);
|
|
11
30
|
const line = JSON.stringify({ ts: new Date().toISOString(), level, tool, message, ...extra });
|
|
12
31
|
fs.appendFileSync(logPath, line + "\n");
|
|
13
32
|
}
|
package/dist/phren-paths.d.ts
CHANGED
|
@@ -47,6 +47,12 @@ export declare function sessionMarker(phrenPath: string, name: string): string;
|
|
|
47
47
|
export declare function debugLog(msg: string): void;
|
|
48
48
|
/** Always-on structured error log (no PHREN_DEBUG gate). */
|
|
49
49
|
export declare function errorLog(tool: string, msg: string): void;
|
|
50
|
+
/**
|
|
51
|
+
* Truncate an append-only .jsonl to its last `keepLines` lines once it exceeds
|
|
52
|
+
* `maxBytes`. Best-effort: any IO error (including ENOENT) is ignored so callers
|
|
53
|
+
* never fail on rotation.
|
|
54
|
+
*/
|
|
55
|
+
export declare function rotateJsonlIfLarge(filePath: string, maxBytes?: number, keepLines?: number): void;
|
|
50
56
|
export declare function appendIndexEvent(phrenPath: string, event: Record<string, unknown>): void;
|
|
51
57
|
/** Resolve the canonical findings file for a project directory. */
|
|
52
58
|
export declare function resolveFindingsPath(projectDir: string): string | undefined;
|
package/dist/phren-paths.js
CHANGED
|
@@ -307,9 +307,26 @@ export function errorLog(tool, msg) {
|
|
|
307
307
|
// Logging must never throw
|
|
308
308
|
}
|
|
309
309
|
}
|
|
310
|
+
/**
|
|
311
|
+
* Truncate an append-only .jsonl to its last `keepLines` lines once it exceeds
|
|
312
|
+
* `maxBytes`. Best-effort: any IO error (including ENOENT) is ignored so callers
|
|
313
|
+
* never fail on rotation.
|
|
314
|
+
*/
|
|
315
|
+
export function rotateJsonlIfLarge(filePath, maxBytes = 2_000_000, keepLines = 2000) {
|
|
316
|
+
try {
|
|
317
|
+
if (fs.statSync(filePath).size <= maxBytes)
|
|
318
|
+
return;
|
|
319
|
+
const lines = fs.readFileSync(filePath, "utf-8").split("\n");
|
|
320
|
+
fs.writeFileSync(filePath, lines.slice(-keepLines).join("\n"));
|
|
321
|
+
}
|
|
322
|
+
catch {
|
|
323
|
+
// no file yet or IO error — nothing to rotate
|
|
324
|
+
}
|
|
325
|
+
}
|
|
310
326
|
export function appendIndexEvent(phrenPath, event) {
|
|
311
327
|
try {
|
|
312
328
|
const file = runtimeFile(phrenPath, "index-events.jsonl");
|
|
329
|
+
rotateJsonlIfLarge(file);
|
|
313
330
|
fs.appendFileSync(file, JSON.stringify({ at: new Date().toISOString(), ...event }) + "\n");
|
|
314
331
|
}
|
|
315
332
|
catch (err) {
|
package/dist/shared/index.d.ts
CHANGED
|
@@ -4,6 +4,8 @@ export { cosineFallback } from "./search-fallback.js";
|
|
|
4
4
|
export { queryFragmentLinks, getFragmentBoostDocs, ensureGlobalEntitiesTable, queryCrossProjectFragments, logFragmentMiss, extractFragmentNames, } from "./fragment-graph.js";
|
|
5
5
|
export { buildSourceDocKey, decodeFiniteNumber, decodeStringRow, extractSnippet, getDocSourceKey, normalizeMemoryId, queryDocBySourceKey, queryDocRows, queryRows, rowToDoc, rowToDocWithRowid, } from "../index-query.js";
|
|
6
6
|
export type { SqlValue, DbRow, DocRow, SqlJsDatabase } from "../index-query.js";
|
|
7
|
+
/** Drain pending embeddings immediately (used by the MCP server's graceful shutdown). */
|
|
8
|
+
export declare function flushEmbeddingQueue(): Promise<void>;
|
|
7
9
|
export declare function classifyFile(filename: string, relPath: string): string;
|
|
8
10
|
/**
|
|
9
11
|
* Resolve `@import shared/file.md` directives in document content.
|
|
@@ -21,6 +23,20 @@ export declare function normalizeIndexedContent(content: string, type: string, p
|
|
|
21
23
|
*/
|
|
22
24
|
export declare function updateFileInIndex(db: SqlJsDatabase, filePath: string, phrenPath: string): void;
|
|
23
25
|
export declare function buildIndex(phrenPath: string, profile?: string): Promise<SqlJsDatabase>;
|
|
26
|
+
/**
|
|
27
|
+
* Non-blocking index loader for the UserPromptSubmit / PostToolUse hooks.
|
|
28
|
+
* Unlike buildIndex(), this NEVER blocks a hook on a 2-12s rebuild:
|
|
29
|
+
* - exact stat-hash cache hit → serve it immediately (fast path);
|
|
30
|
+
* - miss but a usable (possibly stale) cache exists → serve the stale snapshot
|
|
31
|
+
* now and kick a *detached* `background-reindex` (deduped by the rebuild
|
|
32
|
+
* lock) so the next prompt gets fresh results. A single prompt's context may
|
|
33
|
+
* lag one write — far better than freezing the prompt;
|
|
34
|
+
* - cold start (no cache at all) → block once on a full build so the very first
|
|
35
|
+
* prompt isn't empty.
|
|
36
|
+
* Freshness stays correct over time: an edit bumps mtime → new stat-hash → this
|
|
37
|
+
* misses → a rebuild is scheduled → the following prompt hits the new cache.
|
|
38
|
+
*/
|
|
39
|
+
export declare function loadIndexForHook(phrenPath: string, profile?: string): Promise<SqlJsDatabase>;
|
|
24
40
|
/** Find the FTS cache file for a specific phrenPath+profile. Returns exists + size. */
|
|
25
41
|
export declare function findFtsCacheForPath(phrenPath: string, profile?: string): {
|
|
26
42
|
exists: boolean;
|
package/dist/shared/index.js
CHANGED
|
@@ -71,8 +71,9 @@ import { logger } from "../logger.js";
|
|
|
71
71
|
import { formatActorAttribution, parseSourceComment } from "../content/citation.js";
|
|
72
72
|
import { beginUserFragmentBuildCache, endUserFragmentBuildCache, extractAndLinkFragments, ensureGlobalEntitiesTable, } from "./fragment-graph.js";
|
|
73
73
|
import { bootstrapSqlJs } from "./sqljs.js";
|
|
74
|
+
import { spawnDetachedChild } from "./process.js";
|
|
74
75
|
import { getProjectOwnershipMode, getProjectSourcePath, readProjectConfig } from "../project-config.js";
|
|
75
|
-
import { buildSourceDocKey,
|
|
76
|
+
import { buildSourceDocKey, decodeStringRow, getDocSourceKey, queryDocRows, queryRows, } from "../index-query.js";
|
|
76
77
|
import { classifyTopicForText, readProjectTopics, } from "../project-topics.js";
|
|
77
78
|
export { porterStem } from "./stemmer.js";
|
|
78
79
|
export { cosineFallback } from "./search-fallback.js";
|
|
@@ -92,9 +93,19 @@ function scheduleEmbedding(phrenPath, docPath, content) {
|
|
|
92
93
|
if (_embTimer)
|
|
93
94
|
clearTimeout(_embTimer);
|
|
94
95
|
_embTimer = setTimeout(() => { _embTimer = null; void _drainEmbQueue(); }, 500);
|
|
95
|
-
// Unref so the timer doesn't keep short-lived CLI processes alive
|
|
96
|
+
// Unref so the timer doesn't keep short-lived CLI processes alive. Pending
|
|
97
|
+
// embeddings are lost if such a process exits first (acceptable: they're
|
|
98
|
+
// regenerated on demand); the MCP server calls flushEmbeddingQueue on shutdown.
|
|
96
99
|
_embTimer.unref();
|
|
97
100
|
}
|
|
101
|
+
/** Drain pending embeddings immediately (used by the MCP server's graceful shutdown). */
|
|
102
|
+
export async function flushEmbeddingQueue() {
|
|
103
|
+
if (_embTimer) {
|
|
104
|
+
clearTimeout(_embTimer);
|
|
105
|
+
_embTimer = null;
|
|
106
|
+
}
|
|
107
|
+
await _drainEmbQueue();
|
|
108
|
+
}
|
|
98
109
|
async function _drainEmbQueue() {
|
|
99
110
|
if (_embQueue.size === 0)
|
|
100
111
|
return;
|
|
@@ -375,10 +386,17 @@ function computePhrenHash(phrenPath, profile, preGlobbed) {
|
|
|
375
386
|
}
|
|
376
387
|
const INDEX_HASHES_FILENAME = "index-hashes.json";
|
|
377
388
|
const INDEX_SCHEMA_VERSION = 3; // bump when FTS schema changes to force full rebuild
|
|
389
|
+
// Deletion share above which an incremental update falls back to a full rebuild.
|
|
390
|
+
const MAX_INCREMENTAL_DELETE_RATIO = 0.5;
|
|
378
391
|
function hashFileContent(filePath) {
|
|
379
392
|
const content = fs.readFileSync(filePath, "utf-8");
|
|
380
393
|
return crypto.createHash("sha256").update(content).digest("hex");
|
|
381
394
|
}
|
|
395
|
+
/** Errors expected from idempotent schema migrations run against older cached DBs. */
|
|
396
|
+
function isExpectedMigrationError(err) {
|
|
397
|
+
const msg = errorMessage(err).toLowerCase();
|
|
398
|
+
return msg.includes("duplicate column name") || msg.includes("no such table");
|
|
399
|
+
}
|
|
382
400
|
function loadHashMap(phrenPath) {
|
|
383
401
|
const runtimeDir = path.join(phrenPath, ".runtime");
|
|
384
402
|
const hashFile = path.join(runtimeDir, INDEX_HASHES_FILENAME);
|
|
@@ -392,7 +410,7 @@ function loadHashMap(phrenPath) {
|
|
|
392
410
|
}
|
|
393
411
|
return { hashes: {} };
|
|
394
412
|
}
|
|
395
|
-
function saveHashMap(phrenPath, hashes, knownPaths) {
|
|
413
|
+
function saveHashMap(phrenPath, hashes, knownPaths, meta) {
|
|
396
414
|
const runtimeDir = path.join(phrenPath, ".runtime");
|
|
397
415
|
try {
|
|
398
416
|
fs.mkdirSync(runtimeDir, { recursive: true });
|
|
@@ -402,24 +420,34 @@ function saveHashMap(phrenPath, hashes, knownPaths) {
|
|
|
402
420
|
// Prune entries for files that no longer exist to prevent ghost paths from causing
|
|
403
421
|
// repeated full rebuilds when deleted files are found in the hash map.
|
|
404
422
|
let existing = {};
|
|
423
|
+
let existingMeta = {};
|
|
405
424
|
try {
|
|
406
425
|
const data = JSON.parse(fs.readFileSync(hashFile, "utf-8"));
|
|
407
426
|
if (data.hashes && typeof data.hashes === "object")
|
|
408
427
|
existing = data.hashes;
|
|
428
|
+
if (data.meta && typeof data.meta === "object")
|
|
429
|
+
existingMeta = data.meta;
|
|
409
430
|
}
|
|
410
431
|
catch (err) {
|
|
411
432
|
logger.debug("saveHashMap readExisting", errorMessage(err));
|
|
412
433
|
}
|
|
413
434
|
const merged = { ...existing, ...hashes };
|
|
435
|
+
const mergedMeta = { ...existingMeta, ...meta };
|
|
414
436
|
// Remove entries for paths that no longer exist. When knownPaths is provided
|
|
415
437
|
// (build passes supply the full file list), use set membership instead of
|
|
416
438
|
// hitting the filesystem — avoids N sync stat calls inside the lock.
|
|
417
439
|
for (const filePath of Object.keys(merged)) {
|
|
418
440
|
if (knownPaths ? !knownPaths.has(filePath) : !fs.existsSync(filePath)) {
|
|
419
441
|
delete merged[filePath];
|
|
442
|
+
delete mergedMeta[filePath];
|
|
420
443
|
}
|
|
421
444
|
}
|
|
422
|
-
|
|
445
|
+
// Drop meta for paths without a hash entry (meta is only an optimization).
|
|
446
|
+
for (const filePath of Object.keys(mergedMeta)) {
|
|
447
|
+
if (!(filePath in merged))
|
|
448
|
+
delete mergedMeta[filePath];
|
|
449
|
+
}
|
|
450
|
+
fs.writeFileSync(hashFile, JSON.stringify({ version: INDEX_SCHEMA_VERSION, hashes: merged, meta: mergedMeta }, null, 2));
|
|
423
451
|
});
|
|
424
452
|
}
|
|
425
453
|
catch (err) {
|
|
@@ -680,7 +708,8 @@ export function updateFileInIndex(db, filePath, phrenPath) {
|
|
|
680
708
|
try {
|
|
681
709
|
const hashData = loadHashMap(phrenPath);
|
|
682
710
|
hashData.hashes[resolvedPath] = hashFileContent(resolvedPath);
|
|
683
|
-
|
|
711
|
+
const stat = fs.statSync(resolvedPath);
|
|
712
|
+
saveHashMap(phrenPath, hashData.hashes, undefined, { [resolvedPath]: { mtimeMs: stat.mtimeMs, size: stat.size } });
|
|
684
713
|
}
|
|
685
714
|
catch (err) {
|
|
686
715
|
logger.debug("updateFileInIndex hashMap", errorMessage(err));
|
|
@@ -839,13 +868,29 @@ function mergeManualLinks(db, phrenPath) {
|
|
|
839
868
|
return;
|
|
840
869
|
try {
|
|
841
870
|
const manualLinks = JSON.parse(fs.readFileSync(manualLinksPath, 'utf8'));
|
|
871
|
+
// Resolve all sourceDoc keys in one query instead of one lookup per link.
|
|
872
|
+
// Mirrors queryDocBySourceKey semantics: match project + basename(filename),
|
|
873
|
+
// then compare the full source-doc key.
|
|
874
|
+
const projects = [...new Set(manualLinks.map((l) => l.sourceDoc.match(/^([^/]+)\//)?.[1]).filter((p) => !!p))];
|
|
875
|
+
const filenames = [...new Set(manualLinks
|
|
876
|
+
.map((l) => l.sourceDoc.match(/^[^/]+\/(.+)$/)?.[1])
|
|
877
|
+
.filter((rest) => !!rest)
|
|
878
|
+
.map((rest) => path.basename(rest)))];
|
|
879
|
+
const validSourceKeys = new Set();
|
|
880
|
+
if (projects.length && filenames.length) {
|
|
881
|
+
const sql = `SELECT project, filename, path FROM docs WHERE project IN (${projects.map(() => "?").join(",")}) AND filename IN (${filenames.map(() => "?").join(",")})`;
|
|
882
|
+
const rows = queryRows(db, sql, [...projects, ...filenames]) ?? [];
|
|
883
|
+
for (const row of rows) {
|
|
884
|
+
const [project, filename, docPath] = decodeStringRow(row, 3, "mergeManualLinks");
|
|
885
|
+
validSourceKeys.add(getDocSourceKey({ project, filename, path: docPath }, phrenPath));
|
|
886
|
+
}
|
|
887
|
+
}
|
|
842
888
|
let pruned = false;
|
|
843
889
|
const validLinks = [];
|
|
844
890
|
for (const link of manualLinks) {
|
|
845
891
|
try {
|
|
846
892
|
// Validate: skip manual links whose sourceDoc no longer exists in the index
|
|
847
|
-
|
|
848
|
-
if (!docCheck) {
|
|
893
|
+
if (!validSourceKeys.has(link.sourceDoc)) {
|
|
849
894
|
logger.debug("manualLinks", `pruning stale link to "${link.sourceDoc}"`);
|
|
850
895
|
pruned = true;
|
|
851
896
|
continue;
|
|
@@ -952,7 +997,11 @@ async function buildIndexImpl(phrenPath, profile) {
|
|
|
952
997
|
try {
|
|
953
998
|
db.run("ALTER TABLE entities ADD COLUMN first_seen_at TEXT");
|
|
954
999
|
}
|
|
955
|
-
catch {
|
|
1000
|
+
catch (err) {
|
|
1001
|
+
// Usually "duplicate column name" — column already exists
|
|
1002
|
+
if (!isExpectedMigrationError(err))
|
|
1003
|
+
logger.warn("buildIndex migration", errorMessage(err));
|
|
1004
|
+
}
|
|
956
1005
|
debugLog(`Loaded FTS index from cache (${hash.slice(0, 8)}) in ${Date.now() - t0}ms [sentinel-hit]`);
|
|
957
1006
|
appendIndexEvent(phrenPath, {
|
|
958
1007
|
event: "build_index",
|
|
@@ -992,16 +1041,31 @@ async function buildIndexImpl(phrenPath, profile) {
|
|
|
992
1041
|
try {
|
|
993
1042
|
db.run("ALTER TABLE entities ADD COLUMN first_seen_at TEXT");
|
|
994
1043
|
}
|
|
995
|
-
catch {
|
|
996
|
-
|
|
1044
|
+
catch (err) {
|
|
1045
|
+
// Usually "duplicate column name" — column already exists
|
|
1046
|
+
if (!isExpectedMigrationError(err))
|
|
1047
|
+
logger.warn("buildIndex migration", errorMessage(err));
|
|
1048
|
+
}
|
|
1049
|
+
// Compute current file hashes and determine what changed.
|
|
1050
|
+
// Files whose mtime+size match the stored snapshot reuse the stored hash,
|
|
1051
|
+
// skipping a read+SHA256 per file; the content hash stays the source of
|
|
1052
|
+
// truth whenever the stat changed.
|
|
997
1053
|
const allFiles = globResult.entries;
|
|
1054
|
+
const savedMeta = savedHashData.meta ?? {};
|
|
998
1055
|
const currentHashes = {};
|
|
1056
|
+
const currentMeta = {};
|
|
999
1057
|
const changedFiles = [];
|
|
1000
1058
|
const newFiles = [];
|
|
1001
1059
|
for (const entry of allFiles) {
|
|
1002
1060
|
try {
|
|
1003
|
-
const
|
|
1061
|
+
const stat = fs.statSync(entry.fullPath);
|
|
1062
|
+
const prevHash = savedHashes[entry.fullPath];
|
|
1063
|
+
const prevMeta = savedMeta[entry.fullPath];
|
|
1064
|
+
const statUnchanged = prevHash !== undefined && prevMeta !== undefined
|
|
1065
|
+
&& prevMeta.mtimeMs === stat.mtimeMs && prevMeta.size === stat.size;
|
|
1066
|
+
const fileHash = statUnchanged ? prevHash : hashFileContent(entry.fullPath);
|
|
1004
1067
|
currentHashes[entry.fullPath] = fileHash;
|
|
1068
|
+
currentMeta[entry.fullPath] = { mtimeMs: stat.mtimeMs, size: stat.size };
|
|
1005
1069
|
if (!(entry.fullPath in savedHashes)) {
|
|
1006
1070
|
newFiles.push(entry);
|
|
1007
1071
|
}
|
|
@@ -1016,10 +1080,13 @@ async function buildIndexImpl(phrenPath, profile) {
|
|
|
1016
1080
|
// Check for files missing from the index (deleted files)
|
|
1017
1081
|
const currentPaths = new Set(Object.keys(currentHashes));
|
|
1018
1082
|
const missingFromIndex = Object.keys(savedHashes).filter(p => !currentPaths.has(p));
|
|
1019
|
-
// Force full rebuild
|
|
1083
|
+
// Force a full rebuild when a large share of saved files vanished at once —
|
|
1084
|
+
// guards against pathological glob results (e.g. a temporarily unmounted
|
|
1085
|
+
// store dir) and bounds FTS bloat from mass tombstones. Smaller deletions
|
|
1086
|
+
// are removed incrementally.
|
|
1020
1087
|
const totalSaved = Object.keys(savedHashes).length;
|
|
1021
|
-
if (totalSaved > 0 && missingFromIndex.length / totalSaved >
|
|
1022
|
-
debugLog(
|
|
1088
|
+
if (totalSaved > 0 && missingFromIndex.length / totalSaved > MAX_INCREMENTAL_DELETE_RATIO) {
|
|
1089
|
+
debugLog(`>${MAX_INCREMENTAL_DELETE_RATIO * 100}% files missing (${missingFromIndex.length}/${totalSaved}), forcing full rebuild`);
|
|
1023
1090
|
// Fall through to full rebuild below
|
|
1024
1091
|
}
|
|
1025
1092
|
else if (changedFiles.length === 0 && newFiles.length === 0 && missingFromIndex.length === 0) {
|
|
@@ -1076,7 +1143,11 @@ async function buildIndexImpl(phrenPath, profile) {
|
|
|
1076
1143
|
try {
|
|
1077
1144
|
db.run("DELETE FROM global_entities WHERE doc_key = ?", [sourceDocKey]);
|
|
1078
1145
|
}
|
|
1079
|
-
catch {
|
|
1146
|
+
catch (err) {
|
|
1147
|
+
// Usually "no such table" — table may not exist in older cached DBs
|
|
1148
|
+
if (!isExpectedMigrationError(err))
|
|
1149
|
+
logger.warn("buildIndex migration", errorMessage(err));
|
|
1150
|
+
}
|
|
1080
1151
|
db.run("DELETE FROM docs WHERE path = ?", [entry.fullPath]);
|
|
1081
1152
|
}
|
|
1082
1153
|
if (insertFileIntoIndex(db, entry, phrenPath, { scheduleEmbeddings: true })) {
|
|
@@ -1103,7 +1174,7 @@ async function buildIndexImpl(phrenPath, profile) {
|
|
|
1103
1174
|
throw err;
|
|
1104
1175
|
}
|
|
1105
1176
|
}
|
|
1106
|
-
saveHashMap(phrenPath, currentHashes, new Set(Object.keys(currentHashes)));
|
|
1177
|
+
saveHashMap(phrenPath, currentHashes, new Set(Object.keys(currentHashes)), currentMeta);
|
|
1107
1178
|
touchSentinel(phrenPath);
|
|
1108
1179
|
invalidateDfCache();
|
|
1109
1180
|
// Save updated cache
|
|
@@ -1160,6 +1231,7 @@ async function buildIndexImpl(phrenPath, profile) {
|
|
|
1160
1231
|
ensureGlobalEntitiesTable(db);
|
|
1161
1232
|
const allFiles = globResult.entries;
|
|
1162
1233
|
const newHashes = {};
|
|
1234
|
+
const newMeta = {};
|
|
1163
1235
|
let fileCount = 0;
|
|
1164
1236
|
// Try loading cached fragment graph
|
|
1165
1237
|
const graphPath = runtimeFile(phrenPath, 'entity-graph.json');
|
|
@@ -1167,6 +1239,8 @@ async function buildIndexImpl(phrenPath, profile) {
|
|
|
1167
1239
|
for (const entry of allFiles) {
|
|
1168
1240
|
try {
|
|
1169
1241
|
newHashes[entry.fullPath] = hashFileContent(entry.fullPath);
|
|
1242
|
+
const stat = fs.statSync(entry.fullPath);
|
|
1243
|
+
newMeta[entry.fullPath] = { mtimeMs: stat.mtimeMs, size: stat.size };
|
|
1170
1244
|
}
|
|
1171
1245
|
catch (err) {
|
|
1172
1246
|
logger.debug("computePhrenHash skip", errorMessage(err));
|
|
@@ -1202,7 +1276,7 @@ async function buildIndexImpl(phrenPath, profile) {
|
|
|
1202
1276
|
// Always merge manual links (survive rebuild)
|
|
1203
1277
|
mergeManualLinks(db, phrenPath);
|
|
1204
1278
|
// ── Finalize: persist hashes, save cache, log ─────────────────────────────
|
|
1205
|
-
saveHashMap(phrenPath, newHashes, new Set(Object.keys(newHashes)));
|
|
1279
|
+
saveHashMap(phrenPath, newHashes, new Set(Object.keys(newHashes)), newMeta);
|
|
1206
1280
|
touchSentinel(phrenPath);
|
|
1207
1281
|
invalidateDfCache();
|
|
1208
1282
|
const buildMs = Date.now() - t0;
|
|
@@ -1360,6 +1434,78 @@ export async function buildIndex(phrenPath, profile) {
|
|
|
1360
1434
|
_lastBuildKey = buildKey;
|
|
1361
1435
|
return db;
|
|
1362
1436
|
}
|
|
1437
|
+
/** Resolve the per-user FTS cache directory (os.tmpdir()/phren-fts-<uid>). */
|
|
1438
|
+
function ftsCacheDir() {
|
|
1439
|
+
let userSuffix;
|
|
1440
|
+
try {
|
|
1441
|
+
userSuffix = String(os.userInfo().uid);
|
|
1442
|
+
}
|
|
1443
|
+
catch (err) {
|
|
1444
|
+
logger.debug("ftsCacheDir userInfo", errorMessage(err));
|
|
1445
|
+
userSuffix = crypto.createHash("sha1").update(homeDir()).digest("hex").slice(0, 12);
|
|
1446
|
+
}
|
|
1447
|
+
return path.join(os.tmpdir(), `phren-fts-${userSuffix}`);
|
|
1448
|
+
}
|
|
1449
|
+
/**
|
|
1450
|
+
* Non-blocking index loader for the UserPromptSubmit / PostToolUse hooks.
|
|
1451
|
+
* Unlike buildIndex(), this NEVER blocks a hook on a 2-12s rebuild:
|
|
1452
|
+
* - exact stat-hash cache hit → serve it immediately (fast path);
|
|
1453
|
+
* - miss but a usable (possibly stale) cache exists → serve the stale snapshot
|
|
1454
|
+
* now and kick a *detached* `background-reindex` (deduped by the rebuild
|
|
1455
|
+
* lock) so the next prompt gets fresh results. A single prompt's context may
|
|
1456
|
+
* lag one write — far better than freezing the prompt;
|
|
1457
|
+
* - cold start (no cache at all) → block once on a full build so the very first
|
|
1458
|
+
* prompt isn't empty.
|
|
1459
|
+
* Freshness stays correct over time: an edit bumps mtime → new stat-hash → this
|
|
1460
|
+
* misses → a rebuild is scheduled → the following prompt hits the new cache.
|
|
1461
|
+
*/
|
|
1462
|
+
export async function loadIndexForHook(phrenPath, profile) {
|
|
1463
|
+
const cacheDir = ftsCacheDir();
|
|
1464
|
+
const globResult = globAllFiles(phrenPath, profile);
|
|
1465
|
+
const hash = computePhrenHash(phrenPath, profile, globResult.filePaths);
|
|
1466
|
+
const cacheFile = path.join(cacheDir, `${hash}.db`);
|
|
1467
|
+
const SQL = await bootstrapSqlJs();
|
|
1468
|
+
// Fast path: exact stat-hash hit (no file changed mtime/size since the build).
|
|
1469
|
+
if (fs.existsSync(cacheFile)) {
|
|
1470
|
+
try {
|
|
1471
|
+
const db = new SQL.Database(fs.readFileSync(cacheFile));
|
|
1472
|
+
const docCount = db.exec("SELECT COUNT(*) FROM docs")?.[0]?.values?.[0]?.[0] ?? 0;
|
|
1473
|
+
if (docCount > 0) {
|
|
1474
|
+
appendIndexEvent(phrenPath, { event: "build_index", cache: "hit", hash: hash.slice(0, 12), elapsedMs: 0, profile: profile || "" });
|
|
1475
|
+
return db;
|
|
1476
|
+
}
|
|
1477
|
+
db.close();
|
|
1478
|
+
}
|
|
1479
|
+
catch (err) {
|
|
1480
|
+
debugLog(`loadIndexForHook fast-path load failed: ${errorMessage(err)}`);
|
|
1481
|
+
}
|
|
1482
|
+
}
|
|
1483
|
+
// Miss. Serve stale immediately if any cache exists; else cold-build once.
|
|
1484
|
+
let hasStale = false;
|
|
1485
|
+
try {
|
|
1486
|
+
hasStale = fs.existsSync(cacheDir) && fs.readdirSync(cacheDir).some(f => f.endsWith(".db"));
|
|
1487
|
+
}
|
|
1488
|
+
catch (err) {
|
|
1489
|
+
logger.debug("loadIndexForHook staleScan", errorMessage(err));
|
|
1490
|
+
}
|
|
1491
|
+
if (!hasStale) {
|
|
1492
|
+
return buildIndex(phrenPath, profile);
|
|
1493
|
+
}
|
|
1494
|
+
// Schedule a detached rebuild for next time (rebuild lock dedups concurrent hooks).
|
|
1495
|
+
if (!isRebuildLockHeld(phrenPath)) {
|
|
1496
|
+
const entry = process.argv[1];
|
|
1497
|
+
if (entry && /index\.(c?js|mjs|ts)$/.test(entry) && fs.existsSync(entry)) {
|
|
1498
|
+
try {
|
|
1499
|
+
spawnDetachedChild([entry, "background-reindex"], { phrenPath }).unref();
|
|
1500
|
+
debugLog(`loadIndexForHook: scheduled detached background-reindex (stat-hash miss ${hash.slice(0, 8)})`);
|
|
1501
|
+
}
|
|
1502
|
+
catch (err) {
|
|
1503
|
+
debugLog(`loadIndexForHook: detached reindex spawn failed: ${errorMessage(err)}`);
|
|
1504
|
+
}
|
|
1505
|
+
}
|
|
1506
|
+
}
|
|
1507
|
+
return loadIndexSnapshotOrEmpty(phrenPath, profile);
|
|
1508
|
+
}
|
|
1363
1509
|
async function _buildIndexGuarded(phrenPath, profile) {
|
|
1364
1510
|
const lockTarget = runtimeFile(phrenPath, "index-rebuild");
|
|
1365
1511
|
if (isRebuildLockHeld(phrenPath)) {
|
package/dist/shared/retrieval.js
CHANGED
|
@@ -68,17 +68,36 @@ function intentBoost(intent, docType) {
|
|
|
68
68
|
return 2;
|
|
69
69
|
return 0;
|
|
70
70
|
}
|
|
71
|
+
// fileRelevanceBoost runs once per candidate doc during ranking, all sharing the
|
|
72
|
+
// same changedFiles Set. Cache the normalized view (keyed by the Set instance) so
|
|
73
|
+
// path normalization happens once per ranking pass instead of once per doc.
|
|
74
|
+
const _normalizedChangedFiles = new WeakMap();
|
|
75
|
+
function normalizeChangedFiles(changedFiles) {
|
|
76
|
+
let cached = _normalizedChangedFiles.get(changedFiles);
|
|
77
|
+
if (cached)
|
|
78
|
+
return cached;
|
|
79
|
+
const basenames = new Set();
|
|
80
|
+
const paths = [];
|
|
81
|
+
for (const cf of changedFiles) {
|
|
82
|
+
const n = cf.replace(/\\/g, "/");
|
|
83
|
+
basenames.add(path.basename(n));
|
|
84
|
+
paths.push(n);
|
|
85
|
+
}
|
|
86
|
+
cached = { basenames, paths };
|
|
87
|
+
_normalizedChangedFiles.set(changedFiles, cached);
|
|
88
|
+
return cached;
|
|
89
|
+
}
|
|
71
90
|
export function fileRelevanceBoost(filePath, changedFiles) {
|
|
72
91
|
if (changedFiles.size === 0)
|
|
73
92
|
return 0;
|
|
74
93
|
const normalized = filePath.replace(/\\/g, "/");
|
|
75
94
|
const docBasename = path.basename(normalized);
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
95
|
+
const { basenames, paths } = normalizeChangedFiles(changedFiles);
|
|
96
|
+
// Exact basename match to avoid 'index.ts' matching 'shared-index.ts'
|
|
97
|
+
if (basenames.has(docBasename))
|
|
98
|
+
return 3;
|
|
99
|
+
// Also match if the full changed-file path is a suffix of the doc path
|
|
100
|
+
for (const n of paths) {
|
|
82
101
|
if (normalized.endsWith(`/${n}`))
|
|
83
102
|
return 3;
|
|
84
103
|
}
|
package/dist/telemetry.js
CHANGED
|
@@ -55,7 +55,10 @@ function flushTelemetryForPath(phrenPath) {
|
|
|
55
55
|
const file = telemetryPath(phrenPath);
|
|
56
56
|
try {
|
|
57
57
|
fs.mkdirSync(path.dirname(file), { recursive: true });
|
|
58
|
-
|
|
58
|
+
// Usage stats are private to the user: owner-only perms, including files
|
|
59
|
+
// created by older versions (mode only applies on create).
|
|
60
|
+
fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n", { mode: 0o600 });
|
|
61
|
+
fs.chmodSync(file, 0o600);
|
|
59
62
|
}
|
|
60
63
|
catch (err) {
|
|
61
64
|
logger.debug("telemetry flush", errorMessage(err));
|
package/dist/tools/finding.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
1
|
import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
2
2
|
import { type McpContext } from "./types.js";
|
|
3
|
+
export declare function findConflictCandidates(phrenPath: string, project: string, finding: string): string[];
|
|
3
4
|
export declare function register(server: McpServer, ctx: McpContext): void;
|
package/dist/tools/finding.js
CHANGED
|
@@ -8,7 +8,7 @@ import { removeFinding as removeFindingCore, removeFindings as removeFindingsCor
|
|
|
8
8
|
import { debugLog, EXEC_TIMEOUT_MS, FINDING_TYPES, normalizeMemoryScope, } from "../shared.js";
|
|
9
9
|
import { getCurrentActor, getMachineName } from "../machine-identity.js";
|
|
10
10
|
import { addFindingToFile, addFindingsToFile, checkSemanticConflicts, autoMergeConflicts, } from "../shared/content.js";
|
|
11
|
-
import { jaccardTokenize, jaccardSimilarity, stripMetadata } from "../content/dedup.js";
|
|
11
|
+
import { jaccardTokenize, jaccardSimilarity, stripMetadata, detectConflicts, extractDynamicEntities } from "../content/dedup.js";
|
|
12
12
|
import { runCustomHooks } from "../hooks.js";
|
|
13
13
|
import { incrementSessionFindings } from "./session.js";
|
|
14
14
|
import { extractFragmentNames } from "../shared/fragment-graph.js";
|
|
@@ -49,6 +49,30 @@ function findJaccardCandidates(phrenPath, project, finding) {
|
|
|
49
49
|
return [];
|
|
50
50
|
}
|
|
51
51
|
}
|
|
52
|
+
// Heuristic conflict candidates surfaced to the calling agent so it can decide whether a
|
|
53
|
+
// genuine contradiction exists — no extra LLM/API call, the agent in the loop is the judge.
|
|
54
|
+
// Mirrors findJaccardCandidates (potential duplicates). Capped to keep the response small.
|
|
55
|
+
const MAX_CONFLICT_CANDIDATES = 5;
|
|
56
|
+
export function findConflictCandidates(phrenPath, project, finding) {
|
|
57
|
+
try {
|
|
58
|
+
const findingsPath = path.join(phrenPath, project, FINDINGS_FILENAME);
|
|
59
|
+
if (!fs.existsSync(findingsPath))
|
|
60
|
+
return [];
|
|
61
|
+
const content = fs.readFileSync(findingsPath, "utf8");
|
|
62
|
+
const activeBullets = content.split("\n").filter((l) => l.startsWith("- ") && !isInactiveFindingLine(l));
|
|
63
|
+
if (activeBullets.length === 0)
|
|
64
|
+
return [];
|
|
65
|
+
const dynamicEntities = extractDynamicEntities(phrenPath, project);
|
|
66
|
+
return detectConflicts(finding, activeBullets, dynamicEntities)
|
|
67
|
+
.map((line) => stripMetadata(line).replace(/^-\s+/, "").trim().slice(0, 80))
|
|
68
|
+
.filter((snippet) => snippet.length > 0)
|
|
69
|
+
.slice(0, MAX_CONFLICT_CANDIDATES);
|
|
70
|
+
}
|
|
71
|
+
catch (err) {
|
|
72
|
+
logger.debug("add_finding", `findConflictCandidates: ${errorMessage(err)}`);
|
|
73
|
+
return [];
|
|
74
|
+
}
|
|
75
|
+
}
|
|
52
76
|
function extractConflictsWith(annotations) {
|
|
53
77
|
return annotations
|
|
54
78
|
.map((annotation) => annotation.match(/<!--\s*conflicts_with:\s*"([^"]+)"/)?.[1])
|
|
@@ -142,11 +166,15 @@ async function handleAddFinding(ctx, params) {
|
|
|
142
166
|
return withWriteQueue(async () => {
|
|
143
167
|
runCustomHooks(phrenPath, "pre-finding", { PHREN_PROJECT: project });
|
|
144
168
|
const allPotentialDuplicates = [];
|
|
169
|
+
const allPotentialConflicts = [];
|
|
145
170
|
const extraAnnotationsByFinding = [];
|
|
146
171
|
for (const f of findings) {
|
|
147
172
|
const candidates = findJaccardCandidates(phrenPath, project, f);
|
|
148
173
|
if (candidates.length > 0)
|
|
149
174
|
allPotentialDuplicates.push({ finding: f, candidates });
|
|
175
|
+
const conflictCandidates = findConflictCandidates(phrenPath, project, f);
|
|
176
|
+
if (conflictCandidates.length > 0)
|
|
177
|
+
allPotentialConflicts.push({ finding: f, candidates: conflictCandidates });
|
|
150
178
|
try {
|
|
151
179
|
const conflicts = await checkSemanticConflicts(phrenPath, project, f);
|
|
152
180
|
extraAnnotationsByFinding.push(conflicts.checked && conflicts.annotations.length > 0 ? conflicts.annotations : []);
|
|
@@ -180,6 +208,7 @@ async function handleAddFinding(ctx, params) {
|
|
|
180
208
|
skipped,
|
|
181
209
|
rejected,
|
|
182
210
|
...(allPotentialDuplicates.length > 0 ? { potentialDuplicates: allPotentialDuplicates } : {}),
|
|
211
|
+
...(allPotentialConflicts.length > 0 ? { potentialConflicts: allPotentialConflicts } : {}),
|
|
183
212
|
},
|
|
184
213
|
});
|
|
185
214
|
});
|
|
@@ -191,6 +220,8 @@ async function handleAddFinding(ctx, params) {
|
|
|
191
220
|
const taggedFinding = applyFindingTypePrefix(finding, findingType);
|
|
192
221
|
// Jaccard "maybe zone" scan — free, no LLM call. Return candidates so the agent decides.
|
|
193
222
|
const potentialDuplicates = findJaccardCandidates(phrenPath, project, taggedFinding);
|
|
223
|
+
// Heuristic contradiction candidates — also free, also agent-decides. No extra API call.
|
|
224
|
+
const potentialConflicts = findConflictCandidates(phrenPath, project, taggedFinding);
|
|
194
225
|
const semanticConflicts = await checkSemanticConflicts(phrenPath, project, taggedFinding);
|
|
195
226
|
runCustomHooks(phrenPath, "pre-finding", { PHREN_PROJECT: project });
|
|
196
227
|
const result = addFindingToFile(phrenPath, project, taggedFinding, citation, {
|
|
@@ -249,9 +280,15 @@ async function handleAddFinding(ctx, params) {
|
|
|
249
280
|
// Full DB fragment linking happens on the next index rebuild via updateFileInIndex →
|
|
250
281
|
// extractAndLinkFragments. We surface hints here so callers can see what was detected.
|
|
251
282
|
const detectedFragments = extractFragmentNames(taggedFinding);
|
|
283
|
+
// Surface heuristic conflict candidates for the agent to judge (only when the LLM path
|
|
284
|
+
// didn't already confirm a conflict, to avoid double-reporting the same relationship).
|
|
285
|
+
const conflictNote = (potentialConflicts.length > 0 && conflictsWithList.length === 0)
|
|
286
|
+
? ` ⚠ Possible contradiction with existing finding(s): ${potentialConflicts.map((c) => `"${c}"`).join("; ")}.` +
|
|
287
|
+
` If this genuinely contradicts one, resolve it with resolve_contradiction (or supersede_finding); if they're unrelated, ignore this note.`
|
|
288
|
+
: "";
|
|
252
289
|
return mcpResponse({
|
|
253
290
|
ok: true,
|
|
254
|
-
message: result.data.message,
|
|
291
|
+
message: result.data.message + conflictNote,
|
|
255
292
|
data: {
|
|
256
293
|
project,
|
|
257
294
|
finding: taggedFinding,
|
|
@@ -260,6 +297,7 @@ async function handleAddFinding(ctx, params) {
|
|
|
260
297
|
...(conflictsWithList.length > 0 ? { conflicts: conflictsWithList } : {}),
|
|
261
298
|
...(detectedFragments.length > 0 ? { detectedFragments } : {}),
|
|
262
299
|
...(potentialDuplicates.length > 0 ? { potentialDuplicates } : {}),
|
|
300
|
+
...(potentialConflicts.length > 0 ? { potentialConflicts } : {}),
|
|
263
301
|
scope: normalizedScope,
|
|
264
302
|
}
|
|
265
303
|
});
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@phren/cli",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.35",
|
|
4
4
|
"description": "Knowledge layer for AI agents — CLI, MCP server, and data layer",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -79,8 +79,8 @@
|
|
|
79
79
|
"glob": "^13.0.6",
|
|
80
80
|
"graphology": "^0.26.0",
|
|
81
81
|
"graphology-layout-forceatlas2": "^0.10.1",
|
|
82
|
-
"inquirer": "^
|
|
83
|
-
"js-yaml": "^4.
|
|
82
|
+
"inquirer": "^14.0.2",
|
|
83
|
+
"js-yaml": "^4.2.0",
|
|
84
84
|
"sigma": "^3.0.3",
|
|
85
85
|
"sql.js-fts5": "^1.4.0",
|
|
86
86
|
"zod": "^4.4.3"
|