@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/content/learning.js
CHANGED
|
@@ -16,6 +16,13 @@ import { FINDINGS_FILENAME } from "../data/access.js";
|
|
|
16
16
|
/** Default cap for active findings before auto-archiving is triggered. */
|
|
17
17
|
const DEFAULT_FINDINGS_CAP = 20;
|
|
18
18
|
const LIFECYCLE_ANNOTATION_RE = METADATA_REGEX.lifecycleAnnotation;
|
|
19
|
+
/** Default finding-id source: 8 lowercase hex chars from a CSPRNG. Overridable
|
|
20
|
+
* via `AddFindingOptions.idSource` for deterministic fixture generation
|
|
21
|
+
* (apps/ios/scripts/generate-fixtures.mjs) — production callers never set it,
|
|
22
|
+
* so this is the only thing that ever runs outside tests. */
|
|
23
|
+
function defaultFindingIdSource() {
|
|
24
|
+
return crypto.randomBytes(4).toString("hex");
|
|
25
|
+
}
|
|
19
26
|
function buildFindingCitation(citationInput, nowIso, inferredRepo, headCommit) {
|
|
20
27
|
const citation = {
|
|
21
28
|
created_at: nowIso ?? new Date().toISOString(),
|
|
@@ -64,6 +71,15 @@ function resolveFindingCitationInput(phrenPath, project, citationInput) {
|
|
|
64
71
|
}
|
|
65
72
|
return phrenOk(Object.keys(resolved).length > 0 ? resolved : undefined);
|
|
66
73
|
}
|
|
74
|
+
/**
|
|
75
|
+
* Heuristically infer a finding's type tag from its own wording when the
|
|
76
|
+
* caller didn't supply one. Return type is FindingTag (not FindingType)
|
|
77
|
+
* because "workaround" and "context" are valid outputs here even though
|
|
78
|
+
* they aren't part of the smaller offered/pickable FINDING_TYPES set —
|
|
79
|
+
* both still have a FINDING_TYPE_DECAY row and are searchable via
|
|
80
|
+
* search_knowledge's `tag` filter (FINDING_TAGS), so this function agrees
|
|
81
|
+
* with both.
|
|
82
|
+
*/
|
|
67
83
|
export function autoDetectFindingType(text) {
|
|
68
84
|
const lower = text.toLowerCase();
|
|
69
85
|
if (/\b(we decided|decision:|chose .+ over|went with)\b/.test(lower))
|
|
@@ -81,7 +97,7 @@ export function autoDetectFindingType(text) {
|
|
|
81
97
|
return null;
|
|
82
98
|
}
|
|
83
99
|
function prepareFinding(opts) {
|
|
84
|
-
const { finding: learning, project, fullHistory, extraAnnotations, citationInput, scope, provenance, nowIso, inferredRepo, headCommit } = opts;
|
|
100
|
+
const { finding: learning, project, fullHistory, extraAnnotations, citationInput, scope, provenance, nowIso, inferredRepo, headCommit, idSource } = opts;
|
|
85
101
|
const secretType = scanForSecrets(learning);
|
|
86
102
|
if (secretType) {
|
|
87
103
|
return { status: "rejected", reason: `Contains ${secretType}` };
|
|
@@ -99,7 +115,7 @@ function prepareFinding(opts) {
|
|
|
99
115
|
normalizedLearning = `[${detected}] ${normalizedLearning}`;
|
|
100
116
|
}
|
|
101
117
|
}
|
|
102
|
-
const fid =
|
|
118
|
+
const fid = (idSource ?? defaultFindingIdSource)();
|
|
103
119
|
const fidComment = `<!-- fid:${fid} -->`;
|
|
104
120
|
const createdComment = `<!-- created: ${today} -->`;
|
|
105
121
|
const scopeComment = buildScopeComment(scope);
|
|
@@ -221,7 +237,7 @@ export function addFindingToFile(phrenPath, project, learning, citationInput, op
|
|
|
221
237
|
return phrenErr(`Invalid project name: "${project}".`, PhrenError.INVALID_PROJECT_NAME);
|
|
222
238
|
const learningsPath = path.join(resolvedDir, FINDINGS_FILENAME);
|
|
223
239
|
// Secret/PII scan — reject before anything else (before existence check, before lock)
|
|
224
|
-
const nowIso = new Date().toISOString();
|
|
240
|
+
const nowIso = (opts?.now ?? new Date()).toISOString();
|
|
225
241
|
const today = nowIso.slice(0, 10);
|
|
226
242
|
const resolvedCitationInputResult = resolveFindingCitationInput(phrenPath, project, citationInput);
|
|
227
243
|
if (!resolvedCitationInputResult.ok)
|
|
@@ -249,6 +265,7 @@ export function addFindingToFile(phrenPath, project, learning, citationInput, op
|
|
|
249
265
|
const preparedForNewFile = prepareFinding({
|
|
250
266
|
finding: learning, project, fullHistory: "", extraAnnotations: opts?.extraAnnotations,
|
|
251
267
|
citationInput: resolvedCitationInput, scope, provenance: opts?.provenance, nowIso, inferredRepo, headCommit, phrenPath,
|
|
268
|
+
idSource: opts?.idSource,
|
|
252
269
|
});
|
|
253
270
|
if (!fs.existsSync(learningsPath)) {
|
|
254
271
|
if (preparedForNewFile.status === "rejected") {
|
|
@@ -282,6 +299,7 @@ export function addFindingToFile(phrenPath, project, learning, citationInput, op
|
|
|
282
299
|
const prepared = prepareFinding({
|
|
283
300
|
finding: learning, project, fullHistory: historyForDedup, extraAnnotations: opts?.extraAnnotations,
|
|
284
301
|
citationInput: resolvedCitationInput, scope, provenance: opts?.provenance, nowIso, inferredRepo, headCommit, phrenPath,
|
|
302
|
+
idSource: opts?.idSource,
|
|
285
303
|
});
|
|
286
304
|
if (prepared.status === "rejected") {
|
|
287
305
|
return phrenErr(`Rejected: finding appears to contain a secret (${prepared.reason.replace(/^Contains /, "")}). Strip credentials before saving.`, PhrenError.VALIDATION_ERROR);
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shared low-value / junk detection for finding text.
|
|
3
|
+
*
|
|
4
|
+
* Generalizes the "low value" filter that used to live inline in `cli/govern.ts` so that
|
|
5
|
+
* every capture site agrees with the governance sweep on what counts as junk:
|
|
6
|
+
*
|
|
7
|
+
* - `cli/extract.ts` — git/GitHub mining candidates
|
|
8
|
+
* - `cli/session-tool-hook.ts` — PostToolUse tool-output scraping
|
|
9
|
+
* - `cli/govern.ts` — surfaces junk already sitting in FINDINGS.md
|
|
10
|
+
*
|
|
11
|
+
* Every class below was observed polluting a real store: 56 transient shell-failure
|
|
12
|
+
* captures, 22 machine-generated diff-scrape templates, and 18 non-prose fragments
|
|
13
|
+
* (including phren's own prompt text captured as a finding) in a single project.
|
|
14
|
+
*/
|
|
15
|
+
/** Why a finding is not worth keeping. */
|
|
16
|
+
export type FindingQualityReason = "too_short" | "boilerplate_phrase" | "transient_tool_error" | "diff_scrape_template" | "prompt_template_echo" | "non_prose_fragment";
|
|
17
|
+
/**
|
|
18
|
+
* Classify a finding candidate. Returns null when the text is worth keeping.
|
|
19
|
+
* Accepts raw capture text, a `- ` bullet from FINDINGS.md, or a `- [date] ` queue line.
|
|
20
|
+
*/
|
|
21
|
+
export declare function findingQualityReason(raw: string): FindingQualityReason | null;
|
|
22
|
+
/** True when a finding line is junk: boilerplate, machine noise, or a non-prose fragment. */
|
|
23
|
+
export declare function isLowValueFinding(raw: string): boolean;
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shared low-value / junk detection for finding text.
|
|
3
|
+
*
|
|
4
|
+
* Generalizes the "low value" filter that used to live inline in `cli/govern.ts` so that
|
|
5
|
+
* every capture site agrees with the governance sweep on what counts as junk:
|
|
6
|
+
*
|
|
7
|
+
* - `cli/extract.ts` — git/GitHub mining candidates
|
|
8
|
+
* - `cli/session-tool-hook.ts` — PostToolUse tool-output scraping
|
|
9
|
+
* - `cli/govern.ts` — surfaces junk already sitting in FINDINGS.md
|
|
10
|
+
*
|
|
11
|
+
* Every class below was observed polluting a real store: 56 transient shell-failure
|
|
12
|
+
* captures, 22 machine-generated diff-scrape templates, and 18 non-prose fragments
|
|
13
|
+
* (including phren's own prompt text captured as a finding) in a single project.
|
|
14
|
+
*/
|
|
15
|
+
/** Minimum useful length once bullet/date/confidence decoration is stripped. */
|
|
16
|
+
const MIN_FINDING_LENGTH = 16;
|
|
17
|
+
/** Finding type tags phren renders in front of a finding body (FINDING_TAGS in phren-core.ts). */
|
|
18
|
+
const FINDING_TYPE_TAG_RE = /^\[(?:decision|pitfall|pattern|bug|workaround|context)\]\s*/i;
|
|
19
|
+
/**
|
|
20
|
+
* Placeholder wording that carries no information (the original cli/govern.ts filter).
|
|
21
|
+
* Word-bounded: as a capture-time reject this must not fire on "attempt" or "template".
|
|
22
|
+
*/
|
|
23
|
+
const BOILERPLATE_PHRASE_RE = /\b(?:fixed stuff|updated things|misc|temp|wip|quick note)\b/i;
|
|
24
|
+
/**
|
|
25
|
+
* PostToolUse Bash captures render as `[bug] command '<cmd>' failed: <first error line>`.
|
|
26
|
+
* They record one machine's transient environment failure (EACCES on a managed install,
|
|
27
|
+
* a missing binary, a full disk) and are worthless on any other machine or day.
|
|
28
|
+
*/
|
|
29
|
+
const TOOL_ERROR_CAPTURE_RE = /\bcommand\s+['"`][^'"`]*['"`]\s+failed\b/i;
|
|
30
|
+
/** Raw runtime/OS error output — only junk when nothing durable is said about it. */
|
|
31
|
+
const TRANSIENT_ERROR_SIGNAL_RE = /\b(?:EACCES|EPERM|ENOENT|EEXIST|ENOTDIR|ENOTEMPTY|EMFILE|ENOSPC|ECONNREFUSED|EADDRINUSE|ETIMEDOUT)\b|\bcommand not found\b|\bpermission denied\b|\bno such file or directory\b|npm ERR!|Traceback \(most recent call last\)/i;
|
|
32
|
+
/** Wording that turns a quoted error into a durable finding rather than a log line. */
|
|
33
|
+
const DURABLE_INSIGHT_RE = /\b(?:workaround|root cause|because|must|always|never|avoid|instead|caused by|fixed by|fix by|reproduce|regression|prefer)\b/i;
|
|
34
|
+
/**
|
|
35
|
+
* Machine-generated diff scrapes: `<file>: <thing> added near "<code>"`. The template
|
|
36
|
+
* names a file and a code landmark but says nothing about why either matters.
|
|
37
|
+
*/
|
|
38
|
+
const DIFF_SCRAPE_TEMPLATE_RE = /\b(?:error handling|try\/catch|logging|validation|null checks?|type annotations?)\s+added\s+near\b|^[\w.\-]+\.[a-z]{1,4}:\s.*\bnear\s+["'`]/i;
|
|
39
|
+
/**
|
|
40
|
+
* Fragments of phren's own prompts and templates. The PostToolUse tag scraper matched the
|
|
41
|
+
* type-tag list inside `tools/extract.ts`'s EXTRACT_PROMPT and stored the rest of the line
|
|
42
|
+
* as a finding. Anything that is a slice of a phren instruction is never a finding.
|
|
43
|
+
*/
|
|
44
|
+
const PHREN_TEMPLATE_FRAGMENTS = [
|
|
45
|
+
"you are extracting non-obvious engineering insights from text",
|
|
46
|
+
"output only a json array of strings",
|
|
47
|
+
"each string is a specific, actionable finding",
|
|
48
|
+
"only extract non-obvious patterns, bugs, decisions, pitfalls, or workarounds",
|
|
49
|
+
"do not extract obvious facts or things any developer would know",
|
|
50
|
+
"do not extract credentials, api keys, or personal information",
|
|
51
|
+
"each finding must be self-contained",
|
|
52
|
+
"prefix each finding with its type in brackets: [decision], [pitfall], [pattern], [bug], or [workaround]",
|
|
53
|
+
"if nothing is worth extracting, return []",
|
|
54
|
+
"return only the json array, no explanation, no markdown",
|
|
55
|
+
].map((fragment) => fragment.toLowerCase());
|
|
56
|
+
/** A body that is nothing but phren's type vocabulary, e.g. ", [pitfall], [pattern], or [bug]". */
|
|
57
|
+
const TAG_VOCABULARY_ECHO_RE = /^[\s,]*(?:(?:and|or)\s+)?(?:\[(?:decision|pitfall|pattern|bug|workaround)\][\s,]*(?:(?:and|or)\s+)?){2,}$/i;
|
|
58
|
+
/** Delimiters that come in pairs in prose. Apostrophes are excluded — "don't" is prose. */
|
|
59
|
+
const DELIMITER_PAIRS = [
|
|
60
|
+
["(", ")"],
|
|
61
|
+
["[", "]"],
|
|
62
|
+
["{", "}"],
|
|
63
|
+
];
|
|
64
|
+
function countChar(text, char) {
|
|
65
|
+
let count = 0;
|
|
66
|
+
for (const c of text) {
|
|
67
|
+
if (c === char)
|
|
68
|
+
count++;
|
|
69
|
+
}
|
|
70
|
+
return count;
|
|
71
|
+
}
|
|
72
|
+
function hasUnbalancedDelimiters(text) {
|
|
73
|
+
for (const [open, close] of DELIMITER_PAIRS) {
|
|
74
|
+
if (countChar(text, open) !== countChar(text, close))
|
|
75
|
+
return true;
|
|
76
|
+
}
|
|
77
|
+
return countChar(text, "`") % 2 !== 0 || countChar(text, '"') % 2 !== 0;
|
|
78
|
+
}
|
|
79
|
+
/** Strip bullet, review-queue date stamp, and confidence prefixes — decoration, not content. */
|
|
80
|
+
function stripFindingDecoration(raw) {
|
|
81
|
+
return String(raw ?? "")
|
|
82
|
+
.replace(/^\s*-\s+/, "")
|
|
83
|
+
.replace(/^\[\d{4}-\d{2}-\d{2}\]\s*/, "")
|
|
84
|
+
.replace(/^\[confidence\s+[\d.]+\]\s*/i, "")
|
|
85
|
+
.trim();
|
|
86
|
+
}
|
|
87
|
+
function normalizeForFragmentMatch(text) {
|
|
88
|
+
return text.toLowerCase().replace(/\s+/g, " ").trim();
|
|
89
|
+
}
|
|
90
|
+
/**
|
|
91
|
+
* Classify a finding candidate. Returns null when the text is worth keeping.
|
|
92
|
+
* Accepts raw capture text, a `- ` bullet from FINDINGS.md, or a `- [date] ` queue line.
|
|
93
|
+
*/
|
|
94
|
+
export function findingQualityReason(raw) {
|
|
95
|
+
const body = stripFindingDecoration(raw);
|
|
96
|
+
if (body.length < MIN_FINDING_LENGTH)
|
|
97
|
+
return "too_short";
|
|
98
|
+
if (BOILERPLATE_PHRASE_RE.test(body))
|
|
99
|
+
return "boilerplate_phrase";
|
|
100
|
+
if (TOOL_ERROR_CAPTURE_RE.test(body))
|
|
101
|
+
return "transient_tool_error";
|
|
102
|
+
if (TRANSIENT_ERROR_SIGNAL_RE.test(body) && !DURABLE_INSIGHT_RE.test(body))
|
|
103
|
+
return "transient_tool_error";
|
|
104
|
+
// The type tag is phren's own decoration; judge prose on what follows it.
|
|
105
|
+
const content = body.replace(FINDING_TYPE_TAG_RE, "").trim();
|
|
106
|
+
if (DIFF_SCRAPE_TEMPLATE_RE.test(content))
|
|
107
|
+
return "diff_scrape_template";
|
|
108
|
+
if (TAG_VOCABULARY_ECHO_RE.test(content))
|
|
109
|
+
return "prompt_template_echo";
|
|
110
|
+
const normalized = normalizeForFragmentMatch(content);
|
|
111
|
+
if (normalized.length >= 12 && PHREN_TEMPLATE_FRAGMENTS.some((fragment) => fragment.includes(normalized))) {
|
|
112
|
+
return "prompt_template_echo";
|
|
113
|
+
}
|
|
114
|
+
if (hasUnbalancedDelimiters(content))
|
|
115
|
+
return "non_prose_fragment";
|
|
116
|
+
if ((content.match(/[A-Za-z]{2,}/g) ?? []).length < 2)
|
|
117
|
+
return "non_prose_fragment";
|
|
118
|
+
return null;
|
|
119
|
+
}
|
|
120
|
+
/** True when a finding line is junk: boilerplate, machine noise, or a non-prose fragment. */
|
|
121
|
+
export function isLowValueFinding(raw) {
|
|
122
|
+
return findingQualityReason(raw) !== null;
|
|
123
|
+
}
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Credential detection for anything phren is about to persist or hand back to
|
|
3
|
+
* an agent.
|
|
4
|
+
*
|
|
5
|
+
* Deliberately a dependency-free leaf module. It used to live inside
|
|
6
|
+
* content/dedup.ts, whose import graph pulls in data/access, finding/lifecycle
|
|
7
|
+
* and phren-core — far too heavy for hooks.ts, which runs in a subprocess on
|
|
8
|
+
* every PostToolUse and is explicitly budgeted for cold-start time. dedup.ts
|
|
9
|
+
* re-exports everything here, so existing importers are unchanged.
|
|
10
|
+
*/
|
|
11
|
+
/**
|
|
12
|
+
* Whether a value captured by one of the *name-based* rules below is obviously
|
|
13
|
+
* a placeholder rather than a credential.
|
|
14
|
+
*
|
|
15
|
+
* This exists to raise precision, not recall. A hit here does not scrub the
|
|
16
|
+
* finding — it silently throws the whole finding away, so a false positive
|
|
17
|
+
* costs the user real knowledge and leaves no trace that it happened. The
|
|
18
|
+
* name-based rules are the ones that fire on shape alone ("something called
|
|
19
|
+
* token was assigned something long"), and source code is full of exactly that
|
|
20
|
+
* shape with nothing secret in it: this store already contains an
|
|
21
|
+
* auto-captured finding quoting `_authToken = '__PHRE…'` from phren's own
|
|
22
|
+
* web UI, which is a template marker, not a credential.
|
|
23
|
+
*
|
|
24
|
+
* Only whole values count as placeholders. `TESTONLYFAKEKEY0000001` contains
|
|
25
|
+
* "FAKE" but is not itself a placeholder word, so it is still treated as a
|
|
26
|
+
* secret. The high-confidence rules (AKIA…, ghp_…, sk-ant-…, PEM headers)
|
|
27
|
+
* never consult this — those shapes are unambiguous and a documented example
|
|
28
|
+
* key is still a key.
|
|
29
|
+
*/
|
|
30
|
+
export declare function looksLikePlaceholderSecret(value: string): boolean;
|
|
31
|
+
/**
|
|
32
|
+
* Scan text for secrets and PII patterns. Returns the type of secret found, or null if clean.
|
|
33
|
+
*/
|
|
34
|
+
export declare function scanForSecrets(text: string): string | null;
|
|
35
|
+
/**
|
|
36
|
+
* Make a diagnostic string safe to write to a log or hand back to an agent.
|
|
37
|
+
*
|
|
38
|
+
* Custom hook failures compose their message from the hook's own command plus
|
|
39
|
+
* the child's stderr — `${event}: ${hook.command}: ${errorMessage(err)}` — and
|
|
40
|
+
* that string goes to two places: `.runtime/hook-errors.log`, and the MCP
|
|
41
|
+
* response, which lands in the agent's context and its transcript. Hook
|
|
42
|
+
* commands legitimately carry inline credentials (`curl -H "Authorization:
|
|
43
|
+
* Bearer …"` passes validateCustomHookCommand — it contains none of the
|
|
44
|
+
* blocked shell metacharacters), and a failing child prints whatever it likes
|
|
45
|
+
* to stderr.
|
|
46
|
+
*
|
|
47
|
+
* Fails closed rather than trying to excise the secret in place: if the text
|
|
48
|
+
* trips the detector at all, none of it is emitted. A partially-redacted
|
|
49
|
+
* diagnostic is worth less than an honest statement that it was withheld, and
|
|
50
|
+
* substring surgery on an unknown format is how redactors leak.
|
|
51
|
+
*/
|
|
52
|
+
export declare function redactSecretsForLog(text: string): string;
|
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Credential detection for anything phren is about to persist or hand back to
|
|
3
|
+
* an agent.
|
|
4
|
+
*
|
|
5
|
+
* Deliberately a dependency-free leaf module. It used to live inside
|
|
6
|
+
* content/dedup.ts, whose import graph pulls in data/access, finding/lifecycle
|
|
7
|
+
* and phren-core — far too heavy for hooks.ts, which runs in a subprocess on
|
|
8
|
+
* every PostToolUse and is explicitly budgeted for cold-start time. dedup.ts
|
|
9
|
+
* re-exports everything here, so existing importers are unchanged.
|
|
10
|
+
*/
|
|
11
|
+
/**
|
|
12
|
+
* Whether a value captured by one of the *name-based* rules below is obviously
|
|
13
|
+
* a placeholder rather than a credential.
|
|
14
|
+
*
|
|
15
|
+
* This exists to raise precision, not recall. A hit here does not scrub the
|
|
16
|
+
* finding — it silently throws the whole finding away, so a false positive
|
|
17
|
+
* costs the user real knowledge and leaves no trace that it happened. The
|
|
18
|
+
* name-based rules are the ones that fire on shape alone ("something called
|
|
19
|
+
* token was assigned something long"), and source code is full of exactly that
|
|
20
|
+
* shape with nothing secret in it: this store already contains an
|
|
21
|
+
* auto-captured finding quoting `_authToken = '__PHRE…'` from phren's own
|
|
22
|
+
* web UI, which is a template marker, not a credential.
|
|
23
|
+
*
|
|
24
|
+
* Only whole values count as placeholders. `TESTONLYFAKEKEY0000001` contains
|
|
25
|
+
* "FAKE" but is not itself a placeholder word, so it is still treated as a
|
|
26
|
+
* secret. The high-confidence rules (AKIA…, ghp_…, sk-ant-…, PEM headers)
|
|
27
|
+
* never consult this — those shapes are unambiguous and a documented example
|
|
28
|
+
* key is still a key.
|
|
29
|
+
*/
|
|
30
|
+
export function looksLikePlaceholderSecret(value) {
|
|
31
|
+
const v = value.trim().replace(/^['"`]+|['"`]+$/g, "").trim();
|
|
32
|
+
if (!v)
|
|
33
|
+
return true;
|
|
34
|
+
// Template syntax: <TOKEN>, {{token}}, ${TOKEN}, %TOKEN%, __TOKEN__, and
|
|
35
|
+
// bare shell interpolation ($TOKEN), which is how captured command output
|
|
36
|
+
// usually spells a credential it did not actually expand.
|
|
37
|
+
if (/^(?:<[^<>]*>|\{\{[^{}]*\}\}|\$\{[^{}]*\}|%[^%]*%|__.+__|\$[A-Za-z_][A-Za-z0-9_]*)$/.test(v))
|
|
38
|
+
return true;
|
|
39
|
+
// Masked or elided values: ****, xxxxxxxx, ......, 00000000.
|
|
40
|
+
if (/^(?:[*.]{3,}|[xX]{4,}|0{8,})$/.test(v))
|
|
41
|
+
return true;
|
|
42
|
+
// SCREAMING_SNAKE identifiers — YOUR_API_KEY, PHREN_AUTH_TOKEN. Real tokens
|
|
43
|
+
// are mixed-case or mixed-charset; an all-caps underscore identifier is a
|
|
44
|
+
// variable name standing in for one.
|
|
45
|
+
if (/^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/.test(v))
|
|
46
|
+
return true;
|
|
47
|
+
// Whole-value placeholder words, and `your_*` / `my_*` template names.
|
|
48
|
+
if (/^(?:changeme|change[_-]?me|placeholder|redacted|example|dummy|sample|fake|todo|fixme|none|null|undefined|secret|pass|passwd|password|token|apikey|api[_-]?key)$/i.test(v))
|
|
49
|
+
return true;
|
|
50
|
+
if (/^(?:your|my|the|some)[_-][a-z0-9_-]*$/i.test(v))
|
|
51
|
+
return true;
|
|
52
|
+
if (/[_-]?goes[_-]?here$/i.test(v))
|
|
53
|
+
return true;
|
|
54
|
+
return false;
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* Return the first non-placeholder value captured by `re` (capture group 1),
|
|
58
|
+
* or null when every match looks like a template marker.
|
|
59
|
+
*/
|
|
60
|
+
function firstRealSecretValue(text, re) {
|
|
61
|
+
for (const match of text.matchAll(re)) {
|
|
62
|
+
const value = match[1];
|
|
63
|
+
if (value && !looksLikePlaceholderSecret(value))
|
|
64
|
+
return value;
|
|
65
|
+
}
|
|
66
|
+
return null;
|
|
67
|
+
}
|
|
68
|
+
/** Something called api_key/secret/token/password assigned a long literal. */
|
|
69
|
+
const NAMED_SECRET_RE = /['"]?(?:api_?key|secret|token|password)['"]?\s*[=:]\s*['"]?([a-zA-Z0-9_\-.]{20,})/gi;
|
|
70
|
+
/** `Authorization: Bearer <token>` as captured from command output or code. */
|
|
71
|
+
const BEARER_RE = /\bauthorization['"]?\s*[=:]\s*['"]?\s*bearer\s+([A-Za-z0-9\-._~+/]{20,}=*)/gi;
|
|
72
|
+
/** npm/yarn registry auth line, e.g. `//registry.example.com/:_authToken=…`. */
|
|
73
|
+
const NPM_AUTH_TOKEN_RE = /_auth(?:Token)?\s*=\s*['"]?([A-Za-z0-9\-._~+/]{16,}=*)/gi;
|
|
74
|
+
/** Any URL carrying inline credentials, not just the four db schemes below. */
|
|
75
|
+
const URL_CREDENTIALS_RE = /\bhttps?:\/\/[^/\s:@]+:([^/\s:@]+)@[^\s]+/gi;
|
|
76
|
+
/**
|
|
77
|
+
* Scan text for secrets and PII patterns. Returns the type of secret found, or null if clean.
|
|
78
|
+
*/
|
|
79
|
+
export function scanForSecrets(text) {
|
|
80
|
+
// AWS Access Key
|
|
81
|
+
if (/AKIA[0-9A-Z]{16}/.test(text))
|
|
82
|
+
return 'AWS access key';
|
|
83
|
+
// AWS Secret Access Key (variable assignment pattern)
|
|
84
|
+
if (/(?:aws[_-]?secret|AWS_SECRET)[_-]?(?:access[_-]?)?key[_-]?(?:id)?['":\s]+[A-Za-z0-9/+=]{40}/i.test(text))
|
|
85
|
+
return 'AWS secret access key';
|
|
86
|
+
// JWT token
|
|
87
|
+
if (/eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/.test(text))
|
|
88
|
+
return 'JWT token';
|
|
89
|
+
// Fixed-prefix, fixed-shape credentials. These sit above the generic base64
|
|
90
|
+
// rule below so the rejection message names the actual credential — "Slack
|
|
91
|
+
// webhook URL" tells the user what to strip, "long base64 secret" does not.
|
|
92
|
+
// GitHub fine-grained PAT: different prefix and length from the classic
|
|
93
|
+
// ghp_ form, so none of the existing rules saw it.
|
|
94
|
+
if (/github_pat_[A-Za-z0-9_]{22,}/.test(text))
|
|
95
|
+
return 'GitHub fine-grained token';
|
|
96
|
+
// Google / Firebase API key. Fixed prefix, fixed length, no FP surface.
|
|
97
|
+
if (/\bAIza[0-9A-Za-z_-]{35}\b/.test(text))
|
|
98
|
+
return 'Google API key';
|
|
99
|
+
// Slack incoming-webhook URL — possession of the URL is the credential.
|
|
100
|
+
if (/https:\/\/hooks\.slack\.com\/services\/T[A-Za-z0-9]+\/B[A-Za-z0-9]+\/[A-Za-z0-9]+/.test(text))
|
|
101
|
+
return 'Slack webhook URL';
|
|
102
|
+
// Long base64-encoded secret-like blob (requires base64 chars including +/= and must not be
|
|
103
|
+
// a plain hex digest like a git commit SHA — 40-char lowercase hex is explicitly exempt).
|
|
104
|
+
if (!/^[0-9a-f]{40}$/.test(text) && /(?=[A-Za-z0-9+/]*[+/][A-Za-z0-9+/]*)[A-Za-z0-9+/]{40,}={0,2}/.test(text.replace(/[0-9a-f]{40}/g, "")))
|
|
105
|
+
return 'long base64 secret';
|
|
106
|
+
// Connection string with credentials
|
|
107
|
+
if (/(mongodb|postgres|mysql|redis):\/\/[^@\s]+:[^@\s]+@/i.test(text))
|
|
108
|
+
return 'connection string with credentials';
|
|
109
|
+
// Private key PEM block. The alternation used to be RSA|EC|OPENSSH only,
|
|
110
|
+
// which misses the most common header of all — PKCS#8 keys are written as a
|
|
111
|
+
// bare `-----BEGIN PRIVATE KEY-----`, and that is what `openssl genpkey`,
|
|
112
|
+
// every GCP service-account .pem and most Java tooling emit.
|
|
113
|
+
if (/-----BEGIN (?:[A-Z0-9 ]+ )?PRIVATE KEY-----/.test(text))
|
|
114
|
+
return 'SSH private key';
|
|
115
|
+
// Anthropic API key
|
|
116
|
+
if (/sk-ant-api\d{2}-[A-Za-z0-9_\-]{10,}/.test(text))
|
|
117
|
+
return 'Anthropic API key';
|
|
118
|
+
// OpenAI API key
|
|
119
|
+
if (/sk-proj-[A-Za-z0-9_\-]{30,}/.test(text))
|
|
120
|
+
return 'OpenAI API key';
|
|
121
|
+
// GitHub PAT classic
|
|
122
|
+
if (/ghp_[A-Za-z0-9]{36}/.test(text))
|
|
123
|
+
return 'GitHub personal access token';
|
|
124
|
+
// GitHub OAuth token
|
|
125
|
+
if (/gho_[A-Za-z0-9]{36}/.test(text))
|
|
126
|
+
return 'GitHub OAuth token';
|
|
127
|
+
// GitHub tokens (classic, OAuth, user, org, server)
|
|
128
|
+
if (/gh[pousr]_[A-Za-z0-9]{36}/.test(text))
|
|
129
|
+
return 'GitHub token';
|
|
130
|
+
// Slack bot token
|
|
131
|
+
if (/xoxb-[0-9]+-[A-Za-z0-9-]+/.test(text))
|
|
132
|
+
return 'Slack bot token';
|
|
133
|
+
// Slack user token
|
|
134
|
+
if (/xoxp-[0-9]+-[A-Za-z0-9-]+/.test(text))
|
|
135
|
+
return 'Slack user token';
|
|
136
|
+
// Stripe secret key
|
|
137
|
+
if (/sk_live_[A-Za-z0-9]{24,}/.test(text))
|
|
138
|
+
return 'Stripe secret key';
|
|
139
|
+
// Stripe publishable key
|
|
140
|
+
if (/pk_live_[A-Za-z0-9]{24,}/.test(text))
|
|
141
|
+
return 'Stripe publishable key';
|
|
142
|
+
// npm access token
|
|
143
|
+
if (/npm_[A-Za-z0-9]{36}/.test(text))
|
|
144
|
+
return 'npm access token';
|
|
145
|
+
// GCP service account
|
|
146
|
+
if (/"private_key_id"\s*:\s*"[^"]{20,}"/.test(text))
|
|
147
|
+
return 'GCP service account key';
|
|
148
|
+
// ── Name-based rules ──────────────────────────────────────────────────────
|
|
149
|
+
// Below here a match is inferred from a *name* plus a long value, not from
|
|
150
|
+
// an unambiguous credential shape, so each one skips values that are plainly
|
|
151
|
+
// template markers. See looksLikePlaceholderSecret for why that matters:
|
|
152
|
+
// a hit discards the user's finding outright rather than redacting it.
|
|
153
|
+
// Any URL carrying inline credentials. The connection-string rule above only
|
|
154
|
+
// covers mongodb/postgres/mysql/redis, so `https://user:pat@github.com/…` —
|
|
155
|
+
// the form that actually shows up in captured command output and in remote
|
|
156
|
+
// URLs — went straight through.
|
|
157
|
+
if (firstRealSecretValue(text, URL_CREDENTIALS_RE))
|
|
158
|
+
return 'URL with embedded credentials';
|
|
159
|
+
// `Authorization: Bearer …`, as copied out of curl invocations and logs.
|
|
160
|
+
if (firstRealSecretValue(text, BEARER_RE))
|
|
161
|
+
return 'bearer token';
|
|
162
|
+
// npm/yarn registry auth line. `npm_…` tokens are caught above, but a
|
|
163
|
+
// self-hosted or GitHub Packages registry uses an arbitrary token string.
|
|
164
|
+
if (firstRealSecretValue(text, NPM_AUTH_TOKEN_RE))
|
|
165
|
+
return 'registry auth token';
|
|
166
|
+
// Generic API key (only when the variable name suggests it).
|
|
167
|
+
if (firstRealSecretValue(text, NAMED_SECRET_RE))
|
|
168
|
+
return 'API key or secret';
|
|
169
|
+
return null;
|
|
170
|
+
}
|
|
171
|
+
/**
|
|
172
|
+
* Make a diagnostic string safe to write to a log or hand back to an agent.
|
|
173
|
+
*
|
|
174
|
+
* Custom hook failures compose their message from the hook's own command plus
|
|
175
|
+
* the child's stderr — `${event}: ${hook.command}: ${errorMessage(err)}` — and
|
|
176
|
+
* that string goes to two places: `.runtime/hook-errors.log`, and the MCP
|
|
177
|
+
* response, which lands in the agent's context and its transcript. Hook
|
|
178
|
+
* commands legitimately carry inline credentials (`curl -H "Authorization:
|
|
179
|
+
* Bearer …"` passes validateCustomHookCommand — it contains none of the
|
|
180
|
+
* blocked shell metacharacters), and a failing child prints whatever it likes
|
|
181
|
+
* to stderr.
|
|
182
|
+
*
|
|
183
|
+
* Fails closed rather than trying to excise the secret in place: if the text
|
|
184
|
+
* trips the detector at all, none of it is emitted. A partially-redacted
|
|
185
|
+
* diagnostic is worth less than an honest statement that it was withheld, and
|
|
186
|
+
* substring surgery on an unknown format is how redactors leak.
|
|
187
|
+
*/
|
|
188
|
+
export function redactSecretsForLog(text) {
|
|
189
|
+
const secretType = scanForSecrets(text);
|
|
190
|
+
if (!secretType)
|
|
191
|
+
return text;
|
|
192
|
+
return `[redacted: withheld, contained ${secretType}]`;
|
|
193
|
+
}
|
package/dist/data/access.d.ts
CHANGED
|
@@ -73,9 +73,63 @@ export declare function removeFindings(phrenPath: string, project: string, match
|
|
|
73
73
|
}>;
|
|
74
74
|
export declare function editFinding(phrenPath: string, project: string, oldText: string, newText: string): PhrenResult<string>;
|
|
75
75
|
export declare function readReviewQueue(phrenPath: string, project: string): PhrenResult<QueueItem[]>;
|
|
76
|
-
|
|
76
|
+
export type QueueApproveOutcome = "promoted" | "already_present" | "already_archived";
|
|
77
|
+
export interface QueueApproveResult {
|
|
78
|
+
outcome: QueueApproveOutcome;
|
|
79
|
+
message: string;
|
|
80
|
+
/** Canonical finding text the verb acted on (confidence marker stripped, type tag kept). */
|
|
81
|
+
text: string;
|
|
82
|
+
}
|
|
83
|
+
export type QueueRejectOutcome =
|
|
84
|
+
/** Removed from the live FINDINGS.md tier. */
|
|
85
|
+
"removed"
|
|
86
|
+
/** Removed from reference/topics/*.md, where auto-archive had moved it. */
|
|
87
|
+
| "removed_from_archive"
|
|
88
|
+
/** Nothing to remove: the candidate was never written anywhere. Dequeuing *is* the rejection. */
|
|
89
|
+
| "discarded";
|
|
90
|
+
export interface QueueRejectResult {
|
|
91
|
+
outcome: QueueRejectOutcome;
|
|
92
|
+
message: string;
|
|
93
|
+
text: string;
|
|
94
|
+
}
|
|
95
|
+
/**
|
|
96
|
+
* Approve a queue item: make it real, then dequeue.
|
|
97
|
+
*
|
|
98
|
+
* Three outcomes, because a queue line can point at three different realities:
|
|
99
|
+
*
|
|
100
|
+
* - `promoted` — the text is not in FINDINGS.md, so approving *writes* it. This is the
|
|
101
|
+
* case for every extraction candidate that scored below `autoAcceptThreshold`:
|
|
102
|
+
* extraction queues those without ever adding them, so the old "just splice the line
|
|
103
|
+
* out" behaviour silently discarded them. Promotion goes through `addFindingToFile`,
|
|
104
|
+
* the same path a direct add uses, so dedup, fid assignment, citation metadata, and
|
|
105
|
+
* the findings-cap auto-archive all behave identically.
|
|
106
|
+
* - `already_present` — the text is already a live finding (govern queues existing
|
|
107
|
+
* findings for Stale/Conflicts review). Approving means "keep it"; just dequeue.
|
|
108
|
+
* - `already_archived` — the content only exists in `reference/topics/`, because
|
|
109
|
+
* auto-archive moved it after it was queued. It is still live for retrieval, so the
|
|
110
|
+
* archive is left untouched and the item is dequeued.
|
|
111
|
+
*/
|
|
112
|
+
export declare function approveQueueItemDetailed(phrenPath: string, project: string, lineText: string): PhrenResult<QueueApproveResult>;
|
|
113
|
+
/** Remove a queue item's line from review.md, promoting it to a finding when needed. */
|
|
77
114
|
export declare function approveQueueItem(phrenPath: string, project: string, lineText: string): PhrenResult<string>;
|
|
78
|
-
/**
|
|
115
|
+
/**
|
|
116
|
+
* Reject a queue item: destroy the content wherever it actually lives, then dequeue.
|
|
117
|
+
*
|
|
118
|
+
* Rejection removes from the live FINDINGS.md tier *and* from `reference/topics/*.md`,
|
|
119
|
+
* because auto-archive moves findings there without reconciling their queue lines and
|
|
120
|
+
* archived content is still injected into agent prompts. Leaving it would make reject a
|
|
121
|
+
* lie — the hosts tell users rejection removes the finding permanently.
|
|
122
|
+
*
|
|
123
|
+
* Two situations deliberately do NOT succeed quietly:
|
|
124
|
+
* - the content sits in a FINDINGS.md archive block (`<details>` / `phren:archive`),
|
|
125
|
+
* which the rest of the codebase treats as read-only history; and
|
|
126
|
+
* - several *different* bullets match, so deleting one would be a guess.
|
|
127
|
+
*
|
|
128
|
+
* Both return an error and leave the queue line in place, so the user sees the problem
|
|
129
|
+
* instead of a success message over undeleted content.
|
|
130
|
+
*/
|
|
131
|
+
export declare function rejectQueueItemDetailed(phrenPath: string, project: string, lineText: string): PhrenResult<QueueRejectResult>;
|
|
132
|
+
/** Remove a queue item from review.md AND the corresponding finding wherever it lives. */
|
|
79
133
|
export declare function rejectQueueItem(phrenPath: string, project: string, lineText: string): PhrenResult<string>;
|
|
80
134
|
/** Edit a queue item's text in review.md and the corresponding finding in FINDINGS.md. */
|
|
81
135
|
export declare function editQueueItem(phrenPath: string, project: string, lineText: string, newText: string): PhrenResult<string>;
|