@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.
- package/dist/auth/profiles.js +59 -5
- package/dist/cli/actions.js +11 -3
- package/dist/cli/config-access.js +8 -1
- package/dist/cli/extract.d.ts +27 -1
- package/dist/cli/extract.js +243 -9
- package/dist/cli/govern.js +6 -87
- package/dist/cli/hooks-context.d.ts +1 -1
- package/dist/cli/hooks-context.js +1 -1
- package/dist/cli/namespaces-review.js +14 -1
- package/dist/cli/session-git.d.ts +18 -0
- package/dist/cli/session-git.js +47 -0
- package/dist/cli/session-start.js +2 -2
- package/dist/cli/session-stop.d.ts +11 -0
- package/dist/cli/session-stop.js +141 -33
- package/dist/cli/session-tool-hook.js +17 -5
- package/dist/cli-registry.d.ts +1 -1
- package/dist/cli-registry.js +1 -0
- package/dist/content/dedup.d.ts +1 -4
- package/dist/content/dedup.js +7 -63
- package/dist/content/learning.d.ts +20 -2
- package/dist/content/learning.js +21 -3
- package/dist/content/quality.d.ts +23 -0
- package/dist/content/quality.js +123 -0
- package/dist/content/secrets.d.ts +52 -0
- package/dist/content/secrets.js +193 -0
- package/dist/data/access.d.ts +56 -2
- package/dist/data/access.js +246 -24
- package/dist/entrypoint.js +5 -1
- package/dist/finding/impact.js +170 -43
- package/dist/finding/lifecycle.d.ts +19 -2
- package/dist/finding/lifecycle.js +15 -3
- package/dist/git-worktree.d.ts +19 -0
- package/dist/git-worktree.js +117 -0
- package/dist/governance/policy.d.ts +84 -4
- package/dist/governance/policy.js +209 -14
- package/dist/governance/rbac.d.ts +8 -0
- package/dist/governance/rbac.js +26 -0
- package/dist/hooks.d.ts +20 -0
- package/dist/hooks.js +113 -3
- package/dist/index.js +5 -1
- package/dist/init/guard-globals.d.ts +20 -0
- package/dist/init/guard-globals.js +72 -6
- package/dist/init/init-configure.js +6 -6
- package/dist/init/init.js +10 -6
- package/dist/init/setup.d.ts +4 -3
- package/dist/init/setup.js +120 -16
- package/dist/init/store-gitignore.d.ts +29 -0
- package/dist/init/store-gitignore.js +48 -0
- package/dist/link/doctor.js +86 -20
- package/dist/phren-core.d.ts +35 -8
- package/dist/phren-core.js +35 -8
- package/dist/phren-paths.d.ts +90 -1
- package/dist/phren-paths.js +150 -5
- package/dist/proactivity.js +1 -1
- package/dist/shared/embedding-cache.d.ts +16 -0
- package/dist/shared/embedding-cache.js +24 -0
- package/dist/shared/fragment-graph.js +10 -0
- package/dist/shared/index.d.ts +6 -0
- package/dist/shared/index.js +523 -138
- package/dist/shared/ollama.d.ts +14 -2
- package/dist/shared/ollama.js +84 -5
- package/dist/shared/retrieval.d.ts +22 -1
- package/dist/shared/retrieval.js +30 -1
- package/dist/shared/search-fallback.js +15 -3
- package/dist/shared/vector-index.d.ts +20 -1
- package/dist/shared/vector-index.js +18 -4
- package/dist/shared.d.ts +1 -1
- package/dist/shared.js +1 -1
- package/dist/status.js +18 -1
- package/dist/store-registry.d.ts +22 -0
- package/dist/store-registry.js +36 -3
- package/dist/task/lifecycle.js +31 -0
- package/dist/tools/config.js +16 -7
- package/dist/tools/data.js +1 -1
- package/dist/tools/extract.js +2 -2
- package/dist/tools/finding.js +14 -3
- package/dist/tools/graph.js +9 -1
- package/dist/tools/memory.js +1 -1
- package/dist/tools/notes.js +3 -3
- package/dist/tools/ops.js +19 -18
- package/dist/tools/search.js +2 -2
- package/dist/tools/session.js +2 -2
- package/dist/tools/tasks.js +2 -2
- package/dist/tools/types.d.ts +32 -2
- package/dist/tools/types.js +41 -8
- package/dist/ui/scripts.js +2 -2
- package/dist/ui/server.js +5 -0
- package/package.json +1 -1
- package/dist/cli-hooks-git.d.ts +0 -50
- package/dist/cli-hooks-git.js +0 -288
- package/starter/my-api/.claude/skills/README.md +0 -7
- package/starter/my-api/CLAUDE.md +0 -33
- package/starter/my-api/FINDINGS.md +0 -9
- package/starter/my-api/summary.md +0 -7
- package/starter/my-api/tasks.md +0 -7
- package/starter/my-first-project/.claude/skills/README.md +0 -7
- package/starter/my-first-project/CLAUDE.md +0 -49
- package/starter/my-first-project/FINDINGS.md +0 -24
- package/starter/my-first-project/summary.md +0 -11
- package/starter/my-first-project/tasks.md +0 -25
- package/starter/my-frontend/.claude/skills/README.md +0 -7
- package/starter/my-frontend/CLAUDE.md +0 -33
- package/starter/my-frontend/FINDINGS.md +0 -9
- package/starter/my-frontend/summary.md +0 -7
- package/starter/my-frontend/tasks.md +0 -7
package/dist/data/access.js
CHANGED
|
@@ -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
|
-
|
|
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
|
-
/**
|
|
526
|
-
|
|
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(
|
|
552
|
+
return phrenOk(undefined);
|
|
531
553
|
});
|
|
532
554
|
}
|
|
533
|
-
/**
|
|
534
|
-
|
|
535
|
-
const
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
const
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
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
|
|
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) {
|
package/dist/entrypoint.js
CHANGED
|
@@ -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")) {
|
package/dist/finding/impact.js
CHANGED
|
@@ -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
|
-
|
|
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
|
|
63
|
-
|
|
64
|
-
|
|
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
|
-
//
|
|
91
|
-
//
|
|
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
|
-
|
|
112
|
-
|
|
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
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 {};
|