@phren/cli 0.1.40 → 0.1.41

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.
Files changed (105) hide show
  1. package/dist/auth/profiles.js +59 -5
  2. package/dist/cli/actions.js +11 -3
  3. package/dist/cli/config-access.js +8 -1
  4. package/dist/cli/extract.d.ts +27 -1
  5. package/dist/cli/extract.js +243 -9
  6. package/dist/cli/govern.js +6 -87
  7. package/dist/cli/hooks-context.d.ts +1 -1
  8. package/dist/cli/hooks-context.js +1 -1
  9. package/dist/cli/namespaces-review.js +14 -1
  10. package/dist/cli/session-git.d.ts +18 -0
  11. package/dist/cli/session-git.js +47 -0
  12. package/dist/cli/session-start.js +2 -2
  13. package/dist/cli/session-stop.d.ts +11 -0
  14. package/dist/cli/session-stop.js +141 -33
  15. package/dist/cli/session-tool-hook.js +17 -5
  16. package/dist/cli-registry.d.ts +1 -1
  17. package/dist/cli-registry.js +1 -0
  18. package/dist/content/dedup.d.ts +1 -4
  19. package/dist/content/dedup.js +7 -63
  20. package/dist/content/learning.d.ts +20 -2
  21. package/dist/content/learning.js +21 -3
  22. package/dist/content/quality.d.ts +23 -0
  23. package/dist/content/quality.js +123 -0
  24. package/dist/content/secrets.d.ts +52 -0
  25. package/dist/content/secrets.js +193 -0
  26. package/dist/data/access.d.ts +56 -2
  27. package/dist/data/access.js +246 -24
  28. package/dist/entrypoint.js +5 -1
  29. package/dist/finding/impact.js +170 -43
  30. package/dist/finding/lifecycle.d.ts +19 -2
  31. package/dist/finding/lifecycle.js +15 -3
  32. package/dist/git-worktree.d.ts +19 -0
  33. package/dist/git-worktree.js +117 -0
  34. package/dist/governance/policy.d.ts +84 -4
  35. package/dist/governance/policy.js +209 -14
  36. package/dist/governance/rbac.d.ts +8 -0
  37. package/dist/governance/rbac.js +26 -0
  38. package/dist/hooks.d.ts +20 -0
  39. package/dist/hooks.js +113 -3
  40. package/dist/index.js +5 -1
  41. package/dist/init/guard-globals.d.ts +20 -0
  42. package/dist/init/guard-globals.js +72 -6
  43. package/dist/init/init-configure.js +6 -6
  44. package/dist/init/init.js +10 -6
  45. package/dist/init/setup.d.ts +4 -3
  46. package/dist/init/setup.js +120 -16
  47. package/dist/init/store-gitignore.d.ts +29 -0
  48. package/dist/init/store-gitignore.js +48 -0
  49. package/dist/link/doctor.js +86 -20
  50. package/dist/phren-core.d.ts +35 -8
  51. package/dist/phren-core.js +35 -8
  52. package/dist/phren-paths.d.ts +90 -1
  53. package/dist/phren-paths.js +150 -5
  54. package/dist/proactivity.js +1 -1
  55. package/dist/shared/embedding-cache.d.ts +16 -0
  56. package/dist/shared/embedding-cache.js +24 -0
  57. package/dist/shared/fragment-graph.js +10 -0
  58. package/dist/shared/index.d.ts +6 -0
  59. package/dist/shared/index.js +523 -138
  60. package/dist/shared/ollama.d.ts +14 -2
  61. package/dist/shared/ollama.js +84 -5
  62. package/dist/shared/retrieval.d.ts +22 -1
  63. package/dist/shared/retrieval.js +30 -1
  64. package/dist/shared/search-fallback.js +15 -3
  65. package/dist/shared/vector-index.d.ts +20 -1
  66. package/dist/shared/vector-index.js +18 -4
  67. package/dist/shared.d.ts +1 -1
  68. package/dist/shared.js +1 -1
  69. package/dist/status.js +18 -1
  70. package/dist/store-registry.d.ts +22 -0
  71. package/dist/store-registry.js +36 -3
  72. package/dist/task/lifecycle.js +31 -0
  73. package/dist/tools/config.js +16 -7
  74. package/dist/tools/data.js +1 -1
  75. package/dist/tools/extract.js +2 -2
  76. package/dist/tools/finding.js +14 -3
  77. package/dist/tools/graph.js +9 -1
  78. package/dist/tools/memory.js +1 -1
  79. package/dist/tools/notes.js +3 -3
  80. package/dist/tools/ops.js +19 -18
  81. package/dist/tools/search.js +2 -2
  82. package/dist/tools/session.js +2 -2
  83. package/dist/tools/tasks.js +2 -2
  84. package/dist/tools/types.d.ts +32 -2
  85. package/dist/tools/types.js +41 -8
  86. package/dist/ui/scripts.js +2 -2
  87. package/dist/ui/server.js +5 -0
  88. package/package.json +1 -1
  89. package/dist/cli-hooks-git.d.ts +0 -50
  90. package/dist/cli-hooks-git.js +0 -288
  91. package/starter/my-api/.claude/skills/README.md +0 -7
  92. package/starter/my-api/CLAUDE.md +0 -33
  93. package/starter/my-api/FINDINGS.md +0 -9
  94. package/starter/my-api/summary.md +0 -7
  95. package/starter/my-api/tasks.md +0 -7
  96. package/starter/my-first-project/.claude/skills/README.md +0 -7
  97. package/starter/my-first-project/CLAUDE.md +0 -49
  98. package/starter/my-first-project/FINDINGS.md +0 -24
  99. package/starter/my-first-project/summary.md +0 -11
  100. package/starter/my-first-project/tasks.md +0 -25
  101. package/starter/my-frontend/.claude/skills/README.md +0 -7
  102. package/starter/my-frontend/CLAUDE.md +0 -33
  103. package/starter/my-frontend/FINDINGS.md +0 -9
  104. package/starter/my-frontend/summary.md +0 -7
  105. package/starter/my-frontend/tasks.md +0 -7
@@ -4,14 +4,14 @@
4
4
  import * as fs from "fs";
5
5
  import * as path from "path";
6
6
  import * as yaml from "js-yaml";
7
- import { phrenErr, PhrenError, phrenOk, forwardErr, getProjectDirs, isRecord, } from "../shared.js";
7
+ import { appendAuditLog, phrenErr, PhrenError, phrenOk, forwardErr, getProjectDirs, isRecord, } from "../shared.js";
8
8
  import { normalizeQueueEntryText, } from "../shared/governance.js";
9
9
  import { addFindingToFile, } from "../shared/content.js";
10
10
  import { isValidProjectName, queueFilePath, safeProjectPath } from "../utils.js";
11
11
  import { parseCitationComment, parseScopeComment, parseSourceComment, } from "../content/citation.js";
12
12
  import { parseFindingLifecycle, } from "../finding/lifecycle.js";
13
13
  import { METADATA_REGEX, isCitationLine, isArchiveStart, isArchiveEnd, parseFindingId, parseAllContradictions, stripComments, normalizeFindingText, } from "../content/metadata.js";
14
- import { withSafeLock, ensureProject } from "../shared/data-utils.js";
14
+ import { withSafeLock, ensureProject, walkDirectory } from "../shared/data-utils.js";
15
15
  import { getNonPrimaryStores, getStoreProjectDirs } from "../store-registry.js";
16
16
  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 "./tasks.js";
17
17
  export { addProjectToProfile, listMachines, listProfiles, listProjectCards, removeProjectFromProfile, setMachineProfile, } from "../profile-store.js";
@@ -439,8 +439,7 @@ function parseQueueLine(line) {
439
439
  const rawText = parsed ? parsed[2] : line.replace(/^-\s+/, "").trim();
440
440
  const confidence = rawText.match(/\[confidence\s+([01](?:\.\d+)?)\]/i);
441
441
  const source = parseSourceComment(line);
442
- let machine = source?.machine;
443
- let model = source?.model;
442
+ const citation = parseCitationComment(line);
444
443
  // Strip the confidence marker from the canonical text so it doesn't pollute FINDINGS.md
445
444
  const sanitized = normalizeQueueEntryText(rawText.replace(/\s*\[confidence\s+[01](?:\.\d+)?\]/gi, "").trim(), { truncate: true });
446
445
  const text = sanitized.ok ? sanitized.data.text : "";
@@ -448,8 +447,10 @@ function parseQueueLine(line) {
448
447
  date: parsed?.[1],
449
448
  text,
450
449
  confidence: confidence ? Number.parseFloat(confidence[1]) : undefined,
451
- machine,
452
- model,
450
+ machine: source?.machine,
451
+ model: source?.model,
452
+ provenance: source ?? undefined,
453
+ citation: citation ?? undefined,
453
454
  };
454
455
  }
455
456
  export function readReviewQueue(phrenPath, project) {
@@ -522,31 +523,252 @@ function writeQueueLines(file, lines) {
522
523
  fs.writeFileSync(tmp, content);
523
524
  fs.renameSync(tmp, file);
524
525
  }
525
- /** Remove a queue item's line from review.md (finding stays in FINDINGS.md). */
526
- export function approveQueueItem(phrenPath, project, lineText) {
526
+ /**
527
+ * Read-only lookup of a queue line. Returns the *stored* line (not the caller's
528
+ * approximation of it) so callers can read metadata comments the caller never had.
529
+ *
530
+ * Approve and reject both resolve the line first, act on FINDINGS.md second, and
531
+ * dequeue last. Dequeuing first — the old order — meant a failed content operation
532
+ * still destroyed the queue entry, which is how "approve" became a silent discard.
533
+ */
534
+ function locateQueueLine(phrenPath, project, lineText) {
535
+ const ensured = ensureProject(phrenPath, project);
536
+ if (!ensured.ok)
537
+ return forwardErr(ensured);
538
+ const file = queuePath(phrenPath, project);
539
+ if (!fs.existsSync(file))
540
+ return phrenErr(`No review queue found for "${project}".`, PhrenError.FILE_NOT_FOUND);
541
+ const lines = fs.readFileSync(file, "utf8").split("\n");
542
+ const idx = lines.findIndex((l) => l.trim() === lineText.trim());
543
+ if (idx === -1)
544
+ return phrenErr(`Queue item not found in "${project}".`, PhrenError.NOT_FOUND);
545
+ return phrenOk(lines[idx]);
546
+ }
547
+ /** Drop a queue line from review.md. */
548
+ function dequeueLine(phrenPath, project, lineText) {
527
549
  return withQueueLineOp(phrenPath, project, lineText, (lines, idx, file) => {
528
550
  lines.splice(idx, 1);
529
551
  writeQueueLines(file, lines);
530
- return phrenOk(`Approved queue item in ${project}`);
552
+ return phrenOk(undefined);
531
553
  });
532
554
  }
533
- /** Remove a queue item from review.md AND remove the corresponding finding from FINDINGS.md. */
534
- export function rejectQueueItem(phrenPath, project, lineText) {
535
- const lockResult = withQueueLineOp(phrenPath, project, lineText, (lines, idx, file) => {
536
- lines.splice(idx, 1);
537
- writeQueueLines(file, lines);
538
- return phrenOk("ok");
539
- });
540
- if (!lockResult.ok)
541
- return lockResult;
542
- const parsed = parseQueueLine(lineText);
543
- if (parsed.text) {
544
- const removeResult = removeFinding(phrenPath, project, parsed.text);
545
- if (!removeResult.ok) {
546
- return phrenOk(`Rejected queue item from ${project} (note: finding not found in FINDINGS.md — may have already been removed)`);
555
+ /** Does this text already exist as a live (non-archived) bullet in FINDINGS.md? */
556
+ function existsAsLiveFinding(phrenPath, project, text) {
557
+ const dir = safeProjectPath(phrenPath, project);
558
+ if (!dir)
559
+ return false;
560
+ const findingsPath = path.join(dir, FINDINGS_FILENAME);
561
+ if (!fs.existsSync(findingsPath))
562
+ return false;
563
+ const lines = fs.readFileSync(findingsPath, "utf8").split("\n");
564
+ const active = collectFindingBulletLines(lines).filter(({ archived }) => !archived);
565
+ const match = findMatchingFindingBullet(active, normalizeFindingText(text), text);
566
+ // "ambiguous" means several bullets matched — it is still present, just not uniquely
567
+ // addressable, so approve must not write yet another copy.
568
+ return match.kind === "found" || match.kind === "ambiguous";
569
+ }
570
+ /**
571
+ * Find a queue item's content in the project's `reference/` tier.
572
+ *
573
+ * `autoArchiveToReference` moves findings out of FINDINGS.md into
574
+ * `reference/topics/*.md` once a project exceeds the findings cap, without touching
575
+ * the review queue lines that point at them. Those queue items are the reason
576
+ * approve and reject used to be no-ops, so both verbs have to look here.
577
+ */
578
+ function findArchivedReferenceMatches(phrenPath, project, text) {
579
+ const referenceDir = safeProjectPath(phrenPath, project, "reference");
580
+ if (!referenceDir || !fs.existsSync(referenceDir))
581
+ return [];
582
+ const needle = normalizeFindingText(text);
583
+ if (!needle)
584
+ return [];
585
+ const topicsDir = path.join(referenceDir, "topics") + path.sep;
586
+ const exact = [];
587
+ const partial = [];
588
+ for (const filePath of walkDirectory(referenceDir)) {
589
+ const lines = fs.readFileSync(filePath, "utf8").split("\n");
590
+ for (let i = 0; i < lines.length; i++) {
591
+ if (!lines[i].startsWith("- "))
592
+ continue;
593
+ const normalized = normalizeFindingText(lines[i]);
594
+ if (!normalized)
595
+ continue;
596
+ const hit = {
597
+ file: filePath,
598
+ autoArchived: filePath.startsWith(topicsDir),
599
+ idx: i,
600
+ line: lines[i],
601
+ };
602
+ if (normalized === needle)
603
+ exact.push(hit);
604
+ else if (normalized.includes(needle))
605
+ partial.push(hit);
606
+ }
607
+ }
608
+ return exact.length > 0 ? exact : partial;
609
+ }
610
+ /** Bullet content of archived matches, ignoring metadata — used to detect true ambiguity. */
611
+ function archivedMatchesAreIdentical(matches) {
612
+ const first = bulletContentKey(matches[0].line);
613
+ return matches.every(({ line }) => bulletContentKey(line) === first);
614
+ }
615
+ /**
616
+ * Approve a queue item: make it real, then dequeue.
617
+ *
618
+ * Three outcomes, because a queue line can point at three different realities:
619
+ *
620
+ * - `promoted` — the text is not in FINDINGS.md, so approving *writes* it. This is the
621
+ * case for every extraction candidate that scored below `autoAcceptThreshold`:
622
+ * extraction queues those without ever adding them, so the old "just splice the line
623
+ * out" behaviour silently discarded them. Promotion goes through `addFindingToFile`,
624
+ * the same path a direct add uses, so dedup, fid assignment, citation metadata, and
625
+ * the findings-cap auto-archive all behave identically.
626
+ * - `already_present` — the text is already a live finding (govern queues existing
627
+ * findings for Stale/Conflicts review). Approving means "keep it"; just dequeue.
628
+ * - `already_archived` — the content only exists in `reference/topics/`, because
629
+ * auto-archive moved it after it was queued. It is still live for retrieval, so the
630
+ * archive is left untouched and the item is dequeued.
631
+ */
632
+ export function approveQueueItemDetailed(phrenPath, project, lineText) {
633
+ const located = locateQueueLine(phrenPath, project, lineText);
634
+ if (!located.ok)
635
+ return forwardErr(located);
636
+ const parsed = parseQueueLine(located.data);
637
+ const text = parsed.text;
638
+ if (!text) {
639
+ // Nothing usable to promote — dequeue so the malformed line stops blocking the queue.
640
+ const dequeued = dequeueLine(phrenPath, project, lineText);
641
+ if (!dequeued.ok)
642
+ return forwardErr(dequeued);
643
+ appendAuditLog(phrenPath, "review_approve", `project=${project} outcome=empty`);
644
+ return phrenOk({
645
+ outcome: "already_present",
646
+ message: `Approved queue item in ${project} (empty entry, nothing to promote)`,
647
+ text: "",
648
+ });
649
+ }
650
+ const finish = (outcome, message) => {
651
+ const dequeued = dequeueLine(phrenPath, project, lineText);
652
+ if (!dequeued.ok)
653
+ return forwardErr(dequeued);
654
+ appendAuditLog(phrenPath, "review_approve", `project=${project} outcome=${outcome}`);
655
+ return phrenOk({ outcome, message, text });
656
+ };
657
+ if (existsAsLiveFinding(phrenPath, project, text)) {
658
+ return finish("already_present", `Approved queue item in ${project} (already in ${FINDINGS_FILENAME}; kept as-is)`);
659
+ }
660
+ const archived = findArchivedReferenceMatches(phrenPath, project, text);
661
+ if (archived.length > 0) {
662
+ return finish("already_archived", `Approved queue item in ${project} (already archived to ${path.basename(archived[0].file)}; still available for retrieval, archive left untouched)`);
663
+ }
664
+ // Not anywhere: this queue line IS the only copy. Write it as a finding, preserving
665
+ // the entry's type tag (carried in the text) and its capture provenance.
666
+ const citationInput = parsed.citation
667
+ ? {
668
+ ...(parsed.citation.repo ? { repo: parsed.citation.repo } : {}),
669
+ ...(parsed.citation.file ? { file: parsed.citation.file } : {}),
670
+ ...(parsed.citation.line !== undefined ? { line: parsed.citation.line } : {}),
671
+ ...(parsed.citation.commit ? { commit: parsed.citation.commit } : {}),
547
672
  }
673
+ : undefined;
674
+ // The queue entry's own date is the day the observation was captured; the finding is
675
+ // written today, so keep the original date as an explicit annotation rather than
676
+ // losing it.
677
+ const extraAnnotations = parsed.date ? [`<!-- phren:queued "${parsed.date}" -->`] : undefined;
678
+ const added = addFindingToFile(phrenPath, project, text, citationInput, {
679
+ ...(parsed.provenance ? { provenance: parsed.provenance } : {}),
680
+ ...(parsed.provenance?.session_id ? { sessionId: parsed.provenance.session_id } : {}),
681
+ ...(extraAnnotations ? { extraAnnotations } : {}),
682
+ });
683
+ if (!added.ok)
684
+ return forwardErr(added);
685
+ // A fuzzy-dedup skip means an equivalent finding already exists — the item is
686
+ // effectively already present, not newly promoted.
687
+ if (added.data.status === "skipped") {
688
+ return finish("already_present", `Approved queue item in ${project} (equivalent finding already in ${FINDINGS_FILENAME}; not duplicated)`);
548
689
  }
549
- return phrenOk(`Rejected and removed queue item from ${project}`);
690
+ return finish("promoted", `Approved and promoted queue item to ${FINDINGS_FILENAME} in ${project}`);
691
+ }
692
+ /** Remove a queue item's line from review.md, promoting it to a finding when needed. */
693
+ export function approveQueueItem(phrenPath, project, lineText) {
694
+ const result = approveQueueItemDetailed(phrenPath, project, lineText);
695
+ return result.ok ? phrenOk(result.data.message) : result;
696
+ }
697
+ /**
698
+ * Reject a queue item: destroy the content wherever it actually lives, then dequeue.
699
+ *
700
+ * Rejection removes from the live FINDINGS.md tier *and* from `reference/topics/*.md`,
701
+ * because auto-archive moves findings there without reconciling their queue lines and
702
+ * archived content is still injected into agent prompts. Leaving it would make reject a
703
+ * lie — the hosts tell users rejection removes the finding permanently.
704
+ *
705
+ * Two situations deliberately do NOT succeed quietly:
706
+ * - the content sits in a FINDINGS.md archive block (`<details>` / `phren:archive`),
707
+ * which the rest of the codebase treats as read-only history; and
708
+ * - several *different* bullets match, so deleting one would be a guess.
709
+ *
710
+ * Both return an error and leave the queue line in place, so the user sees the problem
711
+ * instead of a success message over undeleted content.
712
+ */
713
+ export function rejectQueueItemDetailed(phrenPath, project, lineText) {
714
+ const located = locateQueueLine(phrenPath, project, lineText);
715
+ if (!located.ok)
716
+ return forwardErr(located);
717
+ const parsed = parseQueueLine(located.data);
718
+ const text = parsed.text;
719
+ const finish = (outcome, message) => {
720
+ const dequeued = dequeueLine(phrenPath, project, lineText);
721
+ if (!dequeued.ok)
722
+ return forwardErr(dequeued);
723
+ appendAuditLog(phrenPath, "review_reject", `project=${project} outcome=${outcome}`);
724
+ return phrenOk({ outcome, message, text });
725
+ };
726
+ if (!text)
727
+ return finish("discarded", `Rejected queue item from ${project} (empty entry)`);
728
+ const removed = removeFinding(phrenPath, project, text);
729
+ if (removed.ok) {
730
+ return finish("removed", `Rejected and removed finding from ${FINDINGS_FILENAME} in ${project}`);
731
+ }
732
+ // Anything other than "it isn't there" is a real problem — an ambiguous match, a
733
+ // read-only FINDINGS.md archive block, a lock timeout. Surface it and keep the queue
734
+ // line so the user can act on it, rather than reporting success over live content.
735
+ if (removed.code !== PhrenError.NOT_FOUND && removed.code !== PhrenError.FILE_NOT_FOUND) {
736
+ return forwardErr(removed);
737
+ }
738
+ const matches = findArchivedReferenceMatches(phrenPath, project, text);
739
+ if (matches.length === 0) {
740
+ return finish("discarded", `Rejected and discarded queue item from ${project} (candidate was never added to ${FINDINGS_FILENAME}; nothing to remove)`);
741
+ }
742
+ const external = matches.filter((match) => !match.autoArchived);
743
+ if (external.length > 0) {
744
+ return phrenErr(`Cannot reject: "${text.slice(0, 60)}" lives in ${path.relative(phrenPath, external[0].file)}, which phren does not auto-manage. Remove it there, then reject again.`, PhrenError.VALIDATION_ERROR);
745
+ }
746
+ if (matches.length > 1 && !archivedMatchesAreIdentical(matches)) {
747
+ return phrenErr(`Cannot reject: "${text.slice(0, 60)}" matches ${matches.length} different archived entries. Remove the right one manually, then reject again.`, PhrenError.AMBIGUOUS_MATCH);
748
+ }
749
+ const target = matches[0];
750
+ const purge = withSafeLock(target.file, () => {
751
+ const lines = fs.readFileSync(target.file, "utf8").split("\n");
752
+ // Re-resolve under the lock — the file may have moved since the scan.
753
+ const idx = lines[target.idx] === target.line ? target.idx : lines.indexOf(target.line);
754
+ if (idx === -1)
755
+ return phrenErr(`Archived entry vanished from ${path.basename(target.file)} before it could be removed.`, PhrenError.NOT_FOUND);
756
+ const removeCount = isCitationLine(lines[idx + 1] || "") ? 2 : 1;
757
+ lines.splice(idx, removeCount);
758
+ const normalized = lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
759
+ const tmp = `${target.file}.tmp.${process.pid}`;
760
+ fs.writeFileSync(tmp, normalized);
761
+ fs.renameSync(tmp, target.file);
762
+ return phrenOk(undefined);
763
+ });
764
+ if (!purge.ok)
765
+ return forwardErr(purge);
766
+ return finish("removed_from_archive", `Rejected and removed archived finding from reference/topics/${path.basename(target.file)} in ${project}`);
767
+ }
768
+ /** Remove a queue item from review.md AND the corresponding finding wherever it lives. */
769
+ export function rejectQueueItem(phrenPath, project, lineText) {
770
+ const result = rejectQueueItemDetailed(phrenPath, project, lineText);
771
+ return result.ok ? phrenOk(result.data.message) : result;
550
772
  }
551
773
  /** Edit a queue item's text in review.md and the corresponding finding in FINDINGS.md. */
552
774
  export function editQueueItem(phrenPath, project, lineText, newText) {
@@ -2,7 +2,7 @@ import * as fs from "fs";
2
2
  import * as path from "path";
3
3
  import { errorMessage } from "./utils.js";
4
4
  import { logger } from "./logger.js";
5
- import { defaultPhrenPath, expandHomePath, getPhrenPath, readRootManifest, } from "./shared.js";
5
+ import { defaultPhrenPath, ensureFtsCacheRootPrivate, expandHomePath, getPhrenPath, readRootManifest, } from "./shared.js";
6
6
  import { resolveRuntimeProfile } from "./runtime-profile.js";
7
7
  import { VERSION } from "./package-metadata.js";
8
8
  import { TOPIC_ORDER, helpTopicNames, lookupCommand, } from "./cli-registry.js";
@@ -127,6 +127,10 @@ export async function runTopLevelCommand(argv, opts = {}) {
127
127
  const cmd = lookupCommand(argvCommand);
128
128
  if (!cmd)
129
129
  return false;
130
+ // Any command can end up building or reading the FTS snapshot cache, which
131
+ // is a SQLite export of the whole store landing in os.tmpdir() — /tmp (1777)
132
+ // on Linux and WSL. Harden the per-user cache root before the command runs.
133
+ ensureFtsCacheRootPrivate();
130
134
  // Intercept before any handler runs - in particular before namespace
131
135
  // handlers that used to print their own per-subcommand help text.
132
136
  if (argv.includes("--help") || argv.includes("-h")) {
@@ -1,13 +1,121 @@
1
1
  import * as crypto from "crypto";
2
2
  import * as fs from "fs";
3
3
  import { impactLogFile } from "../shared.js";
4
- import { rotateJsonlIfLarge } from "../phren-paths.js";
4
+ import { rotateJsonlIfLarge, runtimeFile } from "../phren-paths.js";
5
5
  import { withFileLock } from "../shared/governance.js";
6
6
  import { normalizeFindingText } from "../content/metadata.js";
7
- let highImpactCache = null;
7
+ import { logger } from "../logger.js";
8
+ import { errorMessage } from "../utils.js";
9
+ /**
10
+ * Impact aggregation, and why it is not a plain memoised read.
11
+ *
12
+ * `getHighImpactFindings()` runs inside `applyTrustFilter()` on the prompt hot
13
+ * path, and `logImpact()` appends to the same file later in the *same* prompt.
14
+ * The old mtime+size cache was therefore invalidated by the very writer it was
15
+ * meant to protect: every prompt re-parsed the whole log, line by line, and at
16
+ * the log's steady-state ceiling of 2MB (13,773 lines) that cost ~9ms per
17
+ * prompt. Worse, `hook-prompt` is a fresh `node` process per prompt, so an
18
+ * in-process cache could never hit on the path that actually needed it.
19
+ *
20
+ * So the aggregate is (a) derived once, (b) persisted to a sidecar keyed by the
21
+ * log's exact [mtimeMs, size], and (c) folded forward on append rather than
22
+ * discarded — appending a record only ever increments one counter. A reader in
23
+ * the next process validates the sidecar's marker against the log and falls
24
+ * back to a full derive on any mismatch, so being wrong is impossible; the
25
+ * worst case is the work we used to do every time.
26
+ */
27
+ const IMPACT_SUMMARY_VERSION = 1;
28
+ let summaryCache = null;
8
29
  function nowIso() {
9
30
  return new Date().toISOString();
10
31
  }
32
+ function statMarker(file) {
33
+ try {
34
+ const stat = fs.statSync(file);
35
+ return { mtimeMs: stat.mtimeMs, size: stat.size };
36
+ }
37
+ catch {
38
+ return null;
39
+ }
40
+ }
41
+ function markersMatch(a, b) {
42
+ if (!a || !b)
43
+ return false;
44
+ return a.mtimeMs === b.mtimeMs && a.size === b.size;
45
+ }
46
+ function impactSummaryFile(phrenPath) {
47
+ return runtimeFile(phrenPath, "impact-summary.json");
48
+ }
49
+ function emptySummary() {
50
+ return { surfaceCountByFinding: new Map(), completedByFinding: new Set() };
51
+ }
52
+ function readSidecarSummary(phrenPath, marker) {
53
+ try {
54
+ const parsed = JSON.parse(fs.readFileSync(impactSummaryFile(phrenPath), "utf8"));
55
+ if (parsed?.version !== IMPACT_SUMMARY_VERSION)
56
+ return null;
57
+ if (!parsed.source || !markersMatch(parsed.source, marker))
58
+ return null;
59
+ if (!parsed.counts || typeof parsed.counts !== "object" || !Array.isArray(parsed.completed))
60
+ return null;
61
+ const surfaceCountByFinding = new Map();
62
+ for (const [findingId, count] of Object.entries(parsed.counts)) {
63
+ if (typeof count === "number" && Number.isFinite(count))
64
+ surfaceCountByFinding.set(findingId, count);
65
+ }
66
+ return {
67
+ surfaceCountByFinding,
68
+ completedByFinding: new Set(parsed.completed.filter((id) => typeof id === "string")),
69
+ };
70
+ }
71
+ catch {
72
+ return null;
73
+ }
74
+ }
75
+ function writeSidecarSummary(phrenPath, marker, summary) {
76
+ const target = impactSummaryFile(phrenPath);
77
+ const payload = {
78
+ version: IMPACT_SUMMARY_VERSION,
79
+ source: marker,
80
+ counts: Object.fromEntries(summary.surfaceCountByFinding),
81
+ completed: [...summary.completedByFinding],
82
+ };
83
+ // Atomic replace, no lock: readers validate the marker, so a lost race costs
84
+ // one re-derive and can never surface a torn or mismatched aggregate.
85
+ const tmp = `${target}.tmp-${process.pid}-${crypto.randomUUID()}`;
86
+ try {
87
+ fs.writeFileSync(tmp, JSON.stringify(payload));
88
+ fs.renameSync(tmp, target);
89
+ }
90
+ catch (err) {
91
+ logger.debug("writeSidecarSummary", errorMessage(err));
92
+ try {
93
+ fs.unlinkSync(tmp);
94
+ }
95
+ catch { /* nothing to clean up */ }
96
+ }
97
+ }
98
+ function invalidateImpactSummary(phrenPath) {
99
+ summaryCache = null;
100
+ try {
101
+ fs.unlinkSync(impactSummaryFile(phrenPath));
102
+ }
103
+ catch { /* already absent */ }
104
+ }
105
+ /** The aggregate for the log's current revision, without ever re-parsing it. Null when unavailable. */
106
+ function peekSummary(phrenPath, file, marker) {
107
+ if (summaryCache && summaryCache.file === file && markersMatch(summaryCache.marker, marker)) {
108
+ return summaryCache.summary;
109
+ }
110
+ return readSidecarSummary(phrenPath, marker);
111
+ }
112
+ function foldEntriesIntoSummary(summary, entries) {
113
+ for (const entry of entries) {
114
+ summary.surfaceCountByFinding.set(entry.findingId, (summary.surfaceCountByFinding.get(entry.findingId) ?? 0) + 1);
115
+ if (entry.taskCompleted)
116
+ summary.completedByFinding.add(entry.findingId);
117
+ }
118
+ }
11
119
  export function findingIdFromLine(line) {
12
120
  const fid = line.match(/<!--\s*fid:([a-z0-9]{8})\s*-->/i);
13
121
  if (fid?.[1])
@@ -57,41 +165,56 @@ function parseImpactLine(line) {
57
165
  return null;
58
166
  }
59
167
  }
168
+ /** The expensive path: derive the aggregate by parsing every line of the log. */
60
169
  function readImpactSummary(phrenPath) {
61
170
  const file = impactLogFile(phrenPath);
62
- const surfaceCountByFinding = new Map();
63
- const completedByFinding = new Set();
64
- if (!fs.existsSync(file)) {
65
- return {
66
- surfaceCountByFinding,
67
- completedByFinding,
68
- };
69
- }
171
+ const summary = emptySummary();
172
+ if (!fs.existsSync(file))
173
+ return summary;
70
174
  const content = fs.readFileSync(file, "utf8");
71
175
  for (const line of content.split("\n")) {
72
176
  const entry = parseImpactLine(line);
73
177
  if (!entry)
74
178
  continue;
75
- surfaceCountByFinding.set(entry.findingId, (surfaceCountByFinding.get(entry.findingId) ?? 0) + 1);
179
+ summary.surfaceCountByFinding.set(entry.findingId, (summary.surfaceCountByFinding.get(entry.findingId) ?? 0) + 1);
76
180
  if (entry.taskCompleted) {
77
- completedByFinding.add(entry.findingId);
181
+ summary.completedByFinding.add(entry.findingId);
78
182
  }
79
183
  }
80
- return {
81
- surfaceCountByFinding,
82
- completedByFinding,
83
- };
184
+ return summary;
84
185
  }
85
186
  function appendImpact(phrenPath, entries) {
86
187
  if (entries.length === 0)
87
188
  return;
88
189
  const file = impactLogFile(phrenPath);
89
190
  withFileLock(file, () => {
90
- // getHighImpactFindings re-parses this whole file on the hook hot path, so cap
91
- // it — otherwise it grows unbounded (seen at 2MB) and every prompt re-parses it.
191
+ // Cap the log. Rotation drops the oldest records, which changes the surface
192
+ // counts, so the aggregate cannot be folded across it.
193
+ const sizeBeforeRotate = statMarker(file)?.size ?? 0;
92
194
  rotateJsonlIfLarge(file);
195
+ const preAppendMarker = statMarker(file);
196
+ const rotated = (preAppendMarker?.size ?? 0) !== sizeBeforeRotate;
197
+ // An aggregate that already describes the pre-append log can absorb these
198
+ // records directly — they are exactly the delta, and appending one only
199
+ // ever increments one counter. A file that does not exist yet has an empty
200
+ // aggregate by definition.
201
+ const known = rotated
202
+ ? null
203
+ : preAppendMarker
204
+ ? peekSummary(phrenPath, file, preAppendMarker)
205
+ : emptySummary();
93
206
  const lines = entries.map((entry) => JSON.stringify(entry));
94
207
  fs.appendFileSync(file, lines.join("\n") + "\n");
208
+ const markerAfter = statMarker(file);
209
+ if (!known || !markerAfter) {
210
+ // No aggregate at hand. Drop the sidecar and let the next read rebuild
211
+ // it — deriving it here would put the whole parse on the write path.
212
+ invalidateImpactSummary(phrenPath);
213
+ return;
214
+ }
215
+ foldEntriesIntoSummary(known, entries);
216
+ summaryCache = { file, marker: markerAfter, summary: known };
217
+ writeSidecarSummary(phrenPath, markerAfter, known);
95
218
  });
96
219
  }
97
220
  export function logImpact(phrenPath, entries) {
@@ -108,37 +231,26 @@ export function logImpact(phrenPath, entries) {
108
231
  }
109
232
  export function getHighImpactFindings(phrenPath, minSurfaceCount = 3) {
110
233
  const file = impactLogFile(phrenPath);
111
- let stat = null;
112
- try {
113
- stat = fs.existsSync(file) ? fs.statSync(file) : null;
114
- }
115
- catch {
116
- stat = null;
117
- }
118
- if (!stat)
234
+ const marker = statMarker(file);
235
+ if (!marker)
119
236
  return new Set();
120
- if (highImpactCache
121
- && highImpactCache.file === file
122
- && highImpactCache.mtimeMs === stat.mtimeMs
123
- && highImpactCache.size === stat.size
124
- && highImpactCache.minSurfaceCount === minSurfaceCount) {
125
- return new Set(highImpactCache.ids);
237
+ let summary = peekSummary(phrenPath, file, marker);
238
+ if (!summary) {
239
+ summary = readImpactSummary(phrenPath);
240
+ // Persist it so the *next* prompt's process — hook-prompt is a new process
241
+ // every prompt — starts from the aggregate instead of the log.
242
+ writeSidecarSummary(phrenPath, marker, summary);
126
243
  }
127
- const summary = readImpactSummary(phrenPath);
244
+ summaryCache = { file, marker, summary };
245
+ // Derived per call: the threshold is a caller's choice, not a property of the
246
+ // aggregate, so it does not belong in the cache key.
128
247
  const ids = new Set();
129
248
  for (const [findingId, surfaceCount] of summary.surfaceCountByFinding.entries()) {
130
249
  if (surfaceCount >= minSurfaceCount && summary.completedByFinding.has(findingId)) {
131
250
  ids.add(findingId);
132
251
  }
133
252
  }
134
- highImpactCache = {
135
- file,
136
- mtimeMs: stat.mtimeMs,
137
- size: stat.size,
138
- minSurfaceCount,
139
- ids,
140
- };
141
- return new Set(ids);
253
+ return ids;
142
254
  }
143
255
  export function markImpactEntriesCompletedForSession(phrenPath, sessionId, project) {
144
256
  if (!sessionId)
@@ -149,8 +261,11 @@ export function markImpactEntriesCompletedForSession(phrenPath, sessionId, proje
149
261
  const updated = withFileLock(file, () => {
150
262
  if (!fs.existsSync(file))
151
263
  return 0;
264
+ const preMarker = statMarker(file);
265
+ const known = preMarker ? peekSummary(phrenPath, file, preMarker) : null;
152
266
  const lines = fs.readFileSync(file, "utf8").split("\n");
153
267
  let updatedCount = 0;
268
+ const flipped = new Set();
154
269
  const rewritten = lines
155
270
  .filter((line) => line.trim().length > 0)
156
271
  .map((line) => {
@@ -164,14 +279,26 @@ export function markImpactEntriesCompletedForSession(phrenPath, sessionId, proje
164
279
  if (project && entry.project !== project)
165
280
  return line;
166
281
  updatedCount += 1;
282
+ flipped.add(entry.findingId);
167
283
  return JSON.stringify({ ...entry, taskCompleted: true });
168
284
  });
169
285
  if (updatedCount > 0) {
170
286
  fs.writeFileSync(file, rewritten.join("\n") + "\n");
287
+ // This rewrite flips taskCompleted on existing records; it never adds or
288
+ // removes any, so the surface counts are untouched and the aggregate only
289
+ // gains completed ids.
290
+ const postMarker = statMarker(file);
291
+ if (known && postMarker) {
292
+ for (const findingId of flipped)
293
+ known.completedByFinding.add(findingId);
294
+ summaryCache = { file, marker: postMarker, summary: known };
295
+ writeSidecarSummary(phrenPath, postMarker, known);
296
+ }
297
+ else {
298
+ invalidateImpactSummary(phrenPath);
299
+ }
171
300
  }
172
301
  return updatedCount;
173
302
  });
174
- if (updated > 0)
175
- highImpactCache = null;
176
303
  return updated;
177
304
  }
@@ -1,8 +1,24 @@
1
1
  import { type PhrenResult } from "../phren-core.js";
2
- export declare const FINDING_TYPE_DECAY: Record<string, {
2
+ interface FindingDecayConfig {
3
3
  maxAgeDays: number;
4
4
  decayMultiplier: number;
5
- }>;
5
+ }
6
+ /**
7
+ * Decay rule per finding tag. Keyed with `satisfies Record<FindingTag, ...>`
8
+ * so this object is required to have exactly one row per tag in FINDING_TAGS
9
+ * (phren-core.ts) — no more, no less. Add a tag there and TypeScript forces a
10
+ * decay row here; remove one and the corresponding row becomes a compile
11
+ * error instead of silently-dead data.
12
+ *
13
+ * Previously this table had 9 rows against a 6-entry offered enum that
14
+ * disagreed with it in both directions: `anti-pattern`, `observation`, and
15
+ * `tooling` had rows here but nothing ever wrote those tags, while
16
+ * `tradeoff` and `architecture` were offered/writable but had no row here
17
+ * (so they never decayed and had no max-age). The exported type stays
18
+ * `Record<string, FindingDecayConfig>` so existing string-keyed lookups
19
+ * (e.g. content/citation.ts) don't need to change.
20
+ */
21
+ export declare const FINDING_TYPE_DECAY: Record<string, FindingDecayConfig>;
6
22
  export declare function extractFindingType(line: string): string | null;
7
23
  export declare const FINDING_LIFECYCLE_STATUSES: readonly ["active", "superseded", "contradicted", "stale", "invalid_citation", "retracted"];
8
24
  export type FindingLifecycleStatus = typeof FINDING_LIFECYCLE_STATUSES[number];
@@ -38,3 +54,4 @@ export declare function resolveFindingContradiction(phrenPath: string, project:
38
54
  status: FindingLifecycleStatus;
39
55
  };
40
56
  }>;
57
+ export {};