@phren/cli 0.1.39 → 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 (124) 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-background.js +4 -0
  11. package/dist/cli/session-git.d.ts +18 -0
  12. package/dist/cli/session-git.js +47 -0
  13. package/dist/cli/session-start.js +2 -2
  14. package/dist/cli/session-stop.d.ts +11 -0
  15. package/dist/cli/session-stop.js +157 -33
  16. package/dist/cli/session-tool-hook.js +17 -5
  17. package/dist/cli-handlers.d.ts +2 -0
  18. package/dist/cli-handlers.js +40 -0
  19. package/dist/cli-registry.d.ts +1 -1
  20. package/dist/cli-registry.js +16 -1
  21. package/dist/content/dedup.d.ts +1 -4
  22. package/dist/content/dedup.js +7 -63
  23. package/dist/content/learning.d.ts +20 -2
  24. package/dist/content/learning.js +21 -3
  25. package/dist/content/quality.d.ts +23 -0
  26. package/dist/content/quality.js +123 -0
  27. package/dist/content/secrets.d.ts +52 -0
  28. package/dist/content/secrets.js +193 -0
  29. package/dist/data/access.d.ts +56 -2
  30. package/dist/data/access.js +246 -24
  31. package/dist/entrypoint.js +5 -1
  32. package/dist/finding/impact.js +170 -43
  33. package/dist/finding/lifecycle.d.ts +19 -2
  34. package/dist/finding/lifecycle.js +15 -3
  35. package/dist/git-worktree.d.ts +19 -0
  36. package/dist/git-worktree.js +117 -0
  37. package/dist/governance/policy.d.ts +84 -4
  38. package/dist/governance/policy.js +209 -14
  39. package/dist/governance/rbac.d.ts +8 -0
  40. package/dist/governance/rbac.js +26 -0
  41. package/dist/hooks.d.ts +26 -0
  42. package/dist/hooks.js +119 -6
  43. package/dist/index.js +5 -1
  44. package/dist/init/guard-globals.d.ts +20 -0
  45. package/dist/init/guard-globals.js +72 -6
  46. package/dist/init/init-configure.d.ts +7 -2
  47. package/dist/init/init-configure.js +42 -16
  48. package/dist/init/init-preset.d.ts +3 -0
  49. package/dist/init/init-preset.js +122 -0
  50. package/dist/init/init-uninstall.js +9 -0
  51. package/dist/init/init-walkthrough.d.ts +2 -0
  52. package/dist/init/init-walkthrough.js +42 -17
  53. package/dist/init/init.d.ts +5 -0
  54. package/dist/init/init.js +71 -19
  55. package/dist/init/management-preset.d.ts +42 -0
  56. package/dist/init/management-preset.js +122 -0
  57. package/dist/init/preferences.d.ts +17 -0
  58. package/dist/init/preferences.js +3 -0
  59. package/dist/init/self-wiring.d.ts +5 -0
  60. package/dist/init/self-wiring.js +52 -0
  61. package/dist/init/setup.d.ts +9 -4
  62. package/dist/init/setup.js +139 -23
  63. package/dist/init/store-gitignore.d.ts +29 -0
  64. package/dist/init/store-gitignore.js +48 -0
  65. package/dist/init/teardown.d.ts +15 -0
  66. package/dist/init/teardown.js +241 -0
  67. package/dist/link/doctor.js +127 -34
  68. package/dist/link/link.js +49 -26
  69. package/dist/phren-core.d.ts +35 -8
  70. package/dist/phren-core.js +35 -8
  71. package/dist/phren-paths.d.ts +90 -1
  72. package/dist/phren-paths.js +150 -5
  73. package/dist/proactivity.js +1 -1
  74. package/dist/shared/embedding-cache.d.ts +16 -0
  75. package/dist/shared/embedding-cache.js +24 -0
  76. package/dist/shared/fragment-graph.js +10 -0
  77. package/dist/shared/index.d.ts +6 -0
  78. package/dist/shared/index.js +523 -138
  79. package/dist/shared/ollama.d.ts +14 -2
  80. package/dist/shared/ollama.js +84 -5
  81. package/dist/shared/retrieval.d.ts +22 -1
  82. package/dist/shared/retrieval.js +30 -1
  83. package/dist/shared/search-fallback.js +15 -3
  84. package/dist/shared/vector-index.d.ts +20 -1
  85. package/dist/shared/vector-index.js +18 -4
  86. package/dist/shared.d.ts +1 -1
  87. package/dist/shared.js +1 -1
  88. package/dist/status.js +31 -2
  89. package/dist/store-registry.d.ts +22 -0
  90. package/dist/store-registry.js +36 -3
  91. package/dist/task/lifecycle.js +31 -0
  92. package/dist/tools/config.js +16 -7
  93. package/dist/tools/data.js +1 -1
  94. package/dist/tools/extract.js +2 -2
  95. package/dist/tools/finding.js +14 -3
  96. package/dist/tools/graph.js +9 -1
  97. package/dist/tools/memory.js +1 -1
  98. package/dist/tools/notes.js +3 -3
  99. package/dist/tools/ops.js +19 -18
  100. package/dist/tools/search.js +2 -2
  101. package/dist/tools/session.js +2 -2
  102. package/dist/tools/tasks.js +2 -2
  103. package/dist/tools/types.d.ts +32 -2
  104. package/dist/tools/types.js +41 -8
  105. package/dist/ui/scripts.js +2 -2
  106. package/dist/ui/server.js +5 -0
  107. package/package.json +1 -1
  108. package/dist/cli-hooks-git.d.ts +0 -50
  109. package/dist/cli-hooks-git.js +0 -288
  110. package/starter/my-api/.claude/skills/README.md +0 -7
  111. package/starter/my-api/CLAUDE.md +0 -33
  112. package/starter/my-api/FINDINGS.md +0 -9
  113. package/starter/my-api/summary.md +0 -7
  114. package/starter/my-api/tasks.md +0 -7
  115. package/starter/my-first-project/.claude/skills/README.md +0 -7
  116. package/starter/my-first-project/CLAUDE.md +0 -49
  117. package/starter/my-first-project/FINDINGS.md +0 -24
  118. package/starter/my-first-project/summary.md +0 -11
  119. package/starter/my-first-project/tasks.md +0 -25
  120. package/starter/my-frontend/.claude/skills/README.md +0 -7
  121. package/starter/my-frontend/CLAUDE.md +0 -33
  122. package/starter/my-frontend/FINDINGS.md +0 -9
  123. package/starter/my-frontend/summary.md +0 -7
  124. package/starter/my-frontend/tasks.md +0 -7
@@ -3,7 +3,7 @@ import * as path from "path";
3
3
  import * as crypto from "crypto";
4
4
  import { debugLog, runtimeFile, KNOWN_OBSERVATION_TAGS } from "../shared.js";
5
5
  import { isFeatureEnabled, safeProjectPath, errorMessage } from "../utils.js";
6
- import { UNIVERSAL_TECH_TERMS_RE, EXTRA_ENTITY_PATTERNS } from "../phren-core.js";
6
+ import { UNIVERSAL_TECH_TERMS_RE, EXTRA_FRAGMENT_PATTERNS } from "../phren-core.js";
7
7
  import { isInactiveFindingLine } from "../finding/lifecycle.js";
8
8
  import { logger } from "../logger.js";
9
9
  import { FINDINGS_FILENAME } from "../data/access.js";
@@ -258,7 +258,7 @@ function extractProseEntities(text, dynamicEntities) {
258
258
  while ((m = re.exec(text)) !== null)
259
259
  found.add(m[0].toLowerCase());
260
260
  // Match additional fragment patterns (versions, env keys, file paths, error codes, dates)
261
- for (const { re: pattern } of EXTRA_ENTITY_PATTERNS) {
261
+ for (const { re: pattern } of EXTRA_FRAGMENT_PATTERNS) {
262
262
  const pRe = new RegExp(pattern.source, pattern.flags);
263
263
  let pm;
264
264
  while ((pm = pRe.exec(text)) !== null)
@@ -404,67 +404,11 @@ export function normalizeObservationTags(text) {
404
404
  : undefined;
405
405
  return { text: normalized, warning };
406
406
  }
407
- /**
408
- * Scan text for secrets and PII patterns. Returns the type of secret found, or null if clean.
409
- */
410
- export function scanForSecrets(text) {
411
- // AWS Access Key
412
- if (/AKIA[0-9A-Z]{16}/.test(text))
413
- return 'AWS access key';
414
- // AWS Secret Access Key (variable assignment pattern)
415
- if (/(?:aws[_-]?secret|AWS_SECRET)[_-]?(?:access[_-]?)?key[_-]?(?:id)?['":\s]+[A-Za-z0-9/+=]{40}/i.test(text))
416
- return 'AWS secret access key';
417
- // JWT token
418
- if (/eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/.test(text))
419
- return 'JWT token';
420
- // Long base64-encoded secret-like blob (requires base64 chars including +/= and must not be
421
- // a plain hex digest like a git commit SHA — 40-char lowercase hex is explicitly exempt).
422
- 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, "")))
423
- return 'long base64 secret';
424
- // Connection string with credentials
425
- if (/(mongodb|postgres|mysql|redis):\/\/[^@\s]+:[^@\s]+@/i.test(text))
426
- return 'connection string with credentials';
427
- // SSH private key
428
- if (/-----BEGIN (RSA|EC|OPENSSH) PRIVATE KEY-----/.test(text))
429
- return 'SSH private key';
430
- // Anthropic API key
431
- if (/sk-ant-api\d{2}-[A-Za-z0-9_\-]{10,}/.test(text))
432
- return 'Anthropic API key';
433
- // OpenAI API key
434
- if (/sk-proj-[A-Za-z0-9_\-]{30,}/.test(text))
435
- return 'OpenAI API key';
436
- // GitHub PAT classic
437
- if (/ghp_[A-Za-z0-9]{36}/.test(text))
438
- return 'GitHub personal access token';
439
- // GitHub OAuth token
440
- if (/gho_[A-Za-z0-9]{36}/.test(text))
441
- return 'GitHub OAuth token';
442
- // GitHub tokens (classic, OAuth, user, org, server)
443
- if (/gh[pousr]_[A-Za-z0-9]{36}/.test(text))
444
- return 'GitHub token';
445
- // Slack bot token
446
- if (/xoxb-[0-9]+-[A-Za-z0-9-]+/.test(text))
447
- return 'Slack bot token';
448
- // Slack user token
449
- if (/xoxp-[0-9]+-[A-Za-z0-9-]+/.test(text))
450
- return 'Slack user token';
451
- // Stripe secret key
452
- if (/sk_live_[A-Za-z0-9]{24,}/.test(text))
453
- return 'Stripe secret key';
454
- // Stripe publishable key
455
- if (/pk_live_[A-Za-z0-9]{24,}/.test(text))
456
- return 'Stripe publishable key';
457
- // npm access token
458
- if (/npm_[A-Za-z0-9]{36}/.test(text))
459
- return 'npm access token';
460
- // GCP service account
461
- if (/"private_key_id"\s*:\s*"[^"]{20,}"/.test(text))
462
- return 'GCP service account key';
463
- // Generic API key (only when variable name suggests it)
464
- if (/['"]?(api_?key|secret|token|password)['"]?\s*[=:]\s*['"]?[a-zA-Z0-9_\-\.]{20,}/i.test(text))
465
- return 'API key or secret';
466
- return null;
467
- }
407
+ // Credential detection lives in a dependency-free leaf module so hooks.ts can
408
+ // use it without dragging in this file's import graph. Re-exported here
409
+ // because content/learning.ts, data/notes.ts and shared/content.ts all import
410
+ // scanForSecrets from dedup.
411
+ export { looksLikePlaceholderSecret, scanForSecrets, redactSecretsForLog } from "./secrets.js";
468
412
  /**
469
413
  * Resolve coreferences in learning text by replacing vague pronouns with concrete names.
470
414
  */
@@ -1,16 +1,34 @@
1
- import { type PhrenResult } from "../shared.js";
1
+ import { type PhrenResult, type FindingTag } from "../shared.js";
2
2
  import { type FindingCitation, type FindingProvenance } from "./citation.js";
3
3
  interface AddFindingOptions {
4
4
  extraAnnotations?: string[];
5
5
  sessionId?: string;
6
6
  scope?: string;
7
7
  provenance?: FindingProvenance;
8
+ /**
9
+ * Clock and id-source overrides. Both default to the real clock/CSPRNG, so
10
+ * omitting them is byte-identical to today's behaviour; they exist solely so
11
+ * `generate-fixtures.mjs` can make its output reproducible the same way
12
+ * `notes.addNote`'s `now` option and `tasks.addTask`'s `createdAt` option
13
+ * already let the fixture generator fix the clock for notes and tasks.
14
+ */
15
+ now?: Date;
16
+ idSource?: () => string;
8
17
  }
9
18
  export interface AddFindingResult {
10
19
  message: string;
11
20
  status: "added" | "created" | "skipped";
12
21
  }
13
- export declare function autoDetectFindingType(text: string): string | null;
22
+ /**
23
+ * Heuristically infer a finding's type tag from its own wording when the
24
+ * caller didn't supply one. Return type is FindingTag (not FindingType)
25
+ * because "workaround" and "context" are valid outputs here even though
26
+ * they aren't part of the smaller offered/pickable FINDING_TYPES set —
27
+ * both still have a FINDING_TYPE_DECAY row and are searchable via
28
+ * search_knowledge's `tag` filter (FINDING_TAGS), so this function agrees
29
+ * with both.
30
+ */
31
+ export declare function autoDetectFindingType(text: string): FindingTag | null;
14
32
  export declare function upsertCanonical(phrenPath: string, project: string, memory: string): PhrenResult<string>;
15
33
  export declare function addFindingToFile(phrenPath: string, project: string, learning: string, citationInput?: Partial<FindingCitation>, opts?: AddFindingOptions): PhrenResult<AddFindingResult>;
16
34
  export declare function addFindingsToFile(phrenPath: string, project: string, learnings: string[], opts?: {
@@ -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
+ }