@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
@@ -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 = crypto.randomBytes(4).toString("hex");
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
+ }
@@ -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
- /** Remove a queue item's line from review.md (finding stays in FINDINGS.md). */
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
- /** Remove a queue item from review.md AND remove the corresponding finding from FINDINGS.md. */
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>;