@phren/cli 0.1.23 → 0.1.24

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.
@@ -39,6 +39,8 @@ export declare function inferCitationLocation(repoPath: string, commit: string):
39
39
  line?: number;
40
40
  };
41
41
  export declare function buildCitationComment(citation: FindingCitation): string;
42
+ /** Format actor/machine attribution for human-readable display. */
43
+ export declare function formatActorAttribution(actor: string | undefined, machine: string | undefined): string;
42
44
  export declare function buildSourceComment(source: FindingProvenance): string;
43
45
  /** Build a standalone scope comment. Returns empty string if scope is unset or "shared". */
44
46
  export declare function buildScopeComment(scope: string | undefined): string;
@@ -72,6 +72,12 @@ function readSourceToken(match) {
72
72
  }
73
73
  return raw;
74
74
  }
75
+ /** Format actor/machine attribution for human-readable display. */
76
+ export function formatActorAttribution(actor, machine) {
77
+ if (!actor && !machine)
78
+ return "";
79
+ return `[from:${actor ?? "?"}${machine ? `@${machine}` : ""}]`;
80
+ }
75
81
  export function buildSourceComment(source) {
76
82
  const parts = [];
77
83
  if (source.source)
@@ -1,9 +1,10 @@
1
1
  import { type PhrenResult } from "../shared.js";
2
- import { type FindingCitation } from "./citation.js";
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
+ provenance?: FindingProvenance;
7
8
  }
8
9
  export interface AddFindingResult {
9
10
  message: string;
@@ -16,6 +17,7 @@ export declare function addFindingsToFile(phrenPath: string, project: string, le
16
17
  extraAnnotationsByFinding?: string[][];
17
18
  sessionId?: string;
18
19
  scope?: string;
20
+ provenance?: FindingProvenance;
19
21
  }): PhrenResult<{
20
22
  added: string[];
21
23
  skipped: string[];
@@ -5,7 +5,7 @@ import { debugLog, appendAuditLog, phrenOk, phrenErr, PhrenError } from "../shar
5
5
  import { normalizeMemoryScope } from "../shared.js";
6
6
  import { withFileLock } from "../shared/governance.js";
7
7
  import { isValidProjectName, safeProjectPath } from "../utils.js";
8
- import { buildCitationComment, buildScopeComment, getHeadCommit, getRepoRoot, inferCitationLocation, } from "./citation.js";
8
+ import { buildCitationComment, buildScopeComment, buildSourceComment, getHeadCommit, getRepoRoot, inferCitationLocation, } from "./citation.js";
9
9
  import { isDuplicateFinding, scanForSecrets, normalizeObservationTags, resolveCoref, detectConflicts, extractDynamicEntities } from "./dedup.js";
10
10
  import { validateFindingsFormat, validateFinding } from "./validate.js";
11
11
  import { countActiveFindings, autoArchiveToReference } from "./archive.js";
@@ -81,7 +81,7 @@ export function autoDetectFindingType(text) {
81
81
  return null;
82
82
  }
83
83
  function prepareFinding(opts) {
84
- const { finding: learning, project, fullHistory, extraAnnotations, citationInput, scope, nowIso, inferredRepo, headCommit, phrenPath } = opts;
84
+ const { finding: learning, project, fullHistory, extraAnnotations, citationInput, scope, provenance, nowIso, inferredRepo, headCommit, phrenPath } = opts;
85
85
  const secretType = scanForSecrets(learning);
86
86
  if (secretType) {
87
87
  return { status: "rejected", reason: `Contains ${secretType}` };
@@ -107,6 +107,9 @@ function prepareFinding(opts) {
107
107
  let bullet = `${normalizedLearning.startsWith("- ") ? normalizedLearning : `- ${normalizedLearning}`} ${fidComment} ${createdComment}`;
108
108
  if (scopeComment)
109
109
  bullet += ` ${scopeComment}`;
110
+ const sourceComment = provenance ? buildSourceComment(provenance) : "";
111
+ if (sourceComment)
112
+ bullet += ` ${sourceComment}`;
110
113
  if (isDuplicateFinding(fullHistory, bullet)) {
111
114
  return { status: "duplicate" };
112
115
  }
@@ -251,7 +254,7 @@ export function addFindingToFile(phrenPath, project, learning, citationInput, op
251
254
  const result = withFileLock(learningsPath, () => {
252
255
  const preparedForNewFile = prepareFinding({
253
256
  finding: learning, project, fullHistory: "", extraAnnotations: opts?.extraAnnotations,
254
- citationInput: resolvedCitationInput, scope, nowIso, inferredRepo, headCommit, phrenPath,
257
+ citationInput: resolvedCitationInput, scope, provenance: opts?.provenance, nowIso, inferredRepo, headCommit, phrenPath,
255
258
  });
256
259
  if (!fs.existsSync(learningsPath)) {
257
260
  if (preparedForNewFile.status === "rejected") {
@@ -284,7 +287,7 @@ export function addFindingToFile(phrenPath, project, learning, citationInput, op
284
287
  : content;
285
288
  const prepared = prepareFinding({
286
289
  finding: learning, project, fullHistory: historyForDedup, extraAnnotations: opts?.extraAnnotations,
287
- citationInput: resolvedCitationInput, scope, nowIso, inferredRepo, headCommit, phrenPath,
290
+ citationInput: resolvedCitationInput, scope, provenance: opts?.provenance, nowIso, inferredRepo, headCommit, phrenPath,
288
291
  });
289
292
  if (prepared.status === "rejected") {
290
293
  return phrenErr(`Rejected: finding appears to contain a secret (${prepared.reason.replace(/^Contains /, "")}). Strip credentials before saving.`, PhrenError.VALIDATION_ERROR);
@@ -400,7 +403,7 @@ export function addFindingsToFile(phrenPath, project, learnings, opts) {
400
403
  }
401
404
  const prepared = prepareFinding({
402
405
  finding: learning, project, fullHistory: content, extraAnnotations,
403
- citationInput: resolvedCitationInput, scope, nowIso, inferredRepo, headCommit, phrenPath,
406
+ citationInput: resolvedCitationInput, scope, provenance: opts?.provenance, nowIso, inferredRepo, headCommit, phrenPath,
404
407
  });
405
408
  if (prepared.status === "rejected") {
406
409
  rejected.push({ text: learning, reason: prepared.reason });
@@ -19,6 +19,10 @@ export interface FindingItem {
19
19
  taskItem?: string;
20
20
  confidence?: number;
21
21
  scope?: string;
22
+ /** Machine hostname where this finding was originally recorded. */
23
+ machine?: string;
24
+ /** Actor (username) who recorded this finding. */
25
+ actor?: string;
22
26
  /** First 60 chars of the newer finding that supersedes this one. Set when this finding is stale. */
23
27
  supersededBy?: string;
24
28
  /** First 60 chars of the older finding this one replaces. */
@@ -174,7 +174,10 @@ export function readFindings(phrenPath, project, opts = {}) {
174
174
  const next = lines[i + 1] || "";
175
175
  const citation = isCitationLine(next) ? next.trim() : undefined;
176
176
  const citationData = citation ? parseCitationComment(citation) ?? undefined : undefined;
177
- const scope = parseScopeComment(line) ?? parseSourceComment(line)?.scope;
177
+ const provenance = parseSourceComment(line);
178
+ const scope = parseScopeComment(line) ?? provenance?.scope;
179
+ const machine = provenance?.machine;
180
+ const actor = provenance?.actor;
178
181
  const stableId = parseFindingId(line);
179
182
  const rawText = line.replace(/^-\s+/, "").trim();
180
183
  const textWithoutComments = stripComments(rawText);
@@ -198,6 +201,8 @@ export function readFindings(phrenPath, project, opts = {}) {
198
201
  citationData,
199
202
  taskItem: citationData?.task_item,
200
203
  scope,
204
+ machine,
205
+ actor,
201
206
  supersededBy: supersededByMatch ? supersededByMatch[1] : undefined,
202
207
  supersedes: supersedesMatch ? supersedesMatch[1] : undefined,
203
208
  contradicts: contradictsMatches.length > 0 ? contradictsMatches : undefined,
@@ -1,5 +1,5 @@
1
1
  import { PhrenResult } from "../shared.js";
2
- import type { FindingProvenanceSource } from "../content/citation.js";
2
+ import { type FindingProvenanceSource } from "../content/citation.js";
3
3
  interface FindingJournalCompactResult {
4
4
  filesProcessed: number;
5
5
  entriesProcessed: number;
@@ -20,7 +20,7 @@ export declare function compactFindingJournals(phrenPath: string, project?: stri
20
20
  * Each actor gets one file per day — no merge conflicts possible.
21
21
  * These are markdown files committed to git (not runtime JSONL).
22
22
  */
23
- export declare function appendTeamJournal(storePath: string, project: string, finding: string, actor?: string): PhrenResult<string>;
23
+ export declare function appendTeamJournal(storePath: string, project: string, finding: string, actor?: string, machine?: string): PhrenResult<string>;
24
24
  /**
25
25
  * Read all team journal entries for a project, newest first.
26
26
  */
@@ -5,6 +5,8 @@ import { runtimeDir, phrenOk, phrenErr, PhrenError, atomicWriteText } from "../s
5
5
  import { withFileLock } from "../shared/governance.js";
6
6
  import { addFindingToFile } from "../shared/content.js";
7
7
  import { isValidProjectName, errorMessage } from "../utils.js";
8
+ import { buildSourceComment } from "../content/citation.js";
9
+ import { getCurrentActor } from "../machine-identity.js";
8
10
  import { FINDINGS_FILENAME } from "../data/access.js";
9
11
  function journalRoot(phrenPath) {
10
12
  const dir = path.join(runtimeDir(phrenPath), "finding-journal");
@@ -127,15 +129,16 @@ const TEAM_JOURNAL_DIR = "journal";
127
129
  * Each actor gets one file per day — no merge conflicts possible.
128
130
  * These are markdown files committed to git (not runtime JSONL).
129
131
  */
130
- export function appendTeamJournal(storePath, project, finding, actor) {
131
- const resolvedActor = actor || process.env.PHREN_ACTOR || process.env.USER || "unknown";
132
+ export function appendTeamJournal(storePath, project, finding, actor, machine) {
133
+ const resolvedActor = actor || getCurrentActor();
132
134
  const date = new Date().toISOString().slice(0, 10);
133
135
  const journalDir = path.join(storePath, project, TEAM_JOURNAL_DIR);
134
136
  const journalFile = `${date}-${resolvedActor}.md`;
135
137
  const journalPath = path.join(journalDir, journalFile);
136
138
  try {
137
139
  fs.mkdirSync(journalDir, { recursive: true });
138
- const entry = `- ${finding}\n`;
140
+ const sourceComment = buildSourceComment({ source: "human", machine, actor: resolvedActor });
141
+ const entry = `- ${finding}${sourceComment ? ` ${sourceComment}` : ""}\n`;
139
142
  if (fs.existsSync(journalPath)) {
140
143
  fs.appendFileSync(journalPath, entry);
141
144
  }
@@ -192,7 +195,9 @@ export function materializeTeamFindings(storePath, project) {
192
195
  lines.push(`## ${date}`);
193
196
  for (const { actor, entries } of actors) {
194
197
  for (const entry of entries) {
195
- lines.push(`- ${entry} <!-- author:${actor} -->`);
198
+ const hasSource = /<!--\s*source:.*?-->/.test(entry);
199
+ const fallback = hasSource ? "" : ` ${buildSourceComment({ source: "human", actor })}`;
200
+ lines.push(`- ${entry}${fallback}`);
196
201
  count++;
197
202
  }
198
203
  }
@@ -2,3 +2,4 @@ export declare function machineFilePath(): string;
2
2
  export declare function defaultMachineName(): string;
3
3
  export declare function getMachineName(): string;
4
4
  export declare function persistMachineName(machine: string): void;
5
+ export declare function getCurrentActor(): string;
@@ -13,18 +13,25 @@ export function defaultMachineName() {
13
13
  }
14
14
  return os.hostname();
15
15
  }
16
+ let cachedMachineName = null;
16
17
  export function getMachineName() {
18
+ if (cachedMachineName !== null)
19
+ return cachedMachineName;
17
20
  const filePath = machineFilePath();
18
21
  if (fs.existsSync(filePath)) {
19
22
  const persisted = fs.readFileSync(filePath, "utf8").trim();
20
23
  if (persisted)
21
- return persisted;
24
+ return (cachedMachineName = persisted);
22
25
  }
23
- return defaultMachineName();
26
+ return (cachedMachineName = defaultMachineName());
24
27
  }
25
28
  export function persistMachineName(machine) {
26
29
  const normalized = machine.trim();
27
30
  if (!normalized)
28
31
  return;
29
32
  atomicWriteText(machineFilePath(), `${normalized}\n`);
33
+ cachedMachineName = normalized;
34
+ }
35
+ export function getCurrentActor() {
36
+ return process.env.PHREN_ACTOR || process.env.USER || "unknown";
30
37
  }
@@ -68,6 +68,7 @@ import { isInactiveFindingLine } from "../finding/lifecycle.js";
68
68
  import { invalidateDfCache } from "./search-fallback.js";
69
69
  import { errorMessage } from "../utils.js";
70
70
  import { logger } from "../logger.js";
71
+ import { formatActorAttribution, parseSourceComment } from "../content/citation.js";
71
72
  import { beginUserFragmentBuildCache, endUserFragmentBuildCache, extractAndLinkFragments, ensureGlobalEntitiesTable, } from "./fragment-graph.js";
72
73
  import { bootstrapSqlJs } from "./sqljs.js";
73
74
  import { getProjectOwnershipMode, getProjectSourcePath, readProjectConfig } from "../project-config.js";
@@ -521,7 +522,10 @@ export function normalizeIndexedContent(content, type, phrenPath, maxChars) {
521
522
  .replace(/<!-- phren:archive:start -->[\s\S]*?<!-- phren:archive:end -->/g, "")
522
523
  .replace(/<details>[\s\S]*?<\/details>/gi, "")
523
524
  .replace(/<!--\s*created:\s*.*?-->/g, "")
524
- .replace(/<!--\s*source:\s*.*?-->/g, "")
525
+ .replace(/<!--\s*source:.*?-->/g, (match) => {
526
+ const parsed = parseSourceComment(match);
527
+ return formatActorAttribution(parsed?.actor, parsed?.machine);
528
+ })
525
529
  .replace(/<!--\s*phren:cite\s+\{[\s\S]*?\}\s*-->/g, "");
526
530
  normalized = resolveImports(normalized, phrenPath);
527
531
  if (type === "task") {
@@ -6,6 +6,7 @@ import { logger } from "../logger.js";
6
6
  import { isValidProjectName, safeProjectPath, errorMessage } from "../utils.js";
7
7
  import { removeFinding as removeFindingCore, removeFindings as removeFindingsCore, } from "../core/finding.js";
8
8
  import { debugLog, EXEC_TIMEOUT_MS, FINDING_TYPES, normalizeMemoryScope, } from "../shared.js";
9
+ import { getCurrentActor, getMachineName } from "../machine-identity.js";
9
10
  import { addFindingToFile, addFindingsToFile, checkSemanticConflicts, autoMergeConflicts, } from "../shared/content.js";
10
11
  import { jaccardTokenize, jaccardSimilarity, stripMetadata } from "../content/dedup.js";
11
12
  import { runCustomHooks } from "../hooks.js";
@@ -103,6 +104,12 @@ async function handleAddFinding(ctx, params) {
103
104
  const addFindingDenied = permissionDeniedError(phrenPath, "add_finding", project);
104
105
  if (addFindingDenied)
105
106
  return mcpResponse({ ok: false, error: addFindingDenied });
107
+ const provenance = {
108
+ source: "human",
109
+ machine: getMachineName(),
110
+ actor: getCurrentActor(),
111
+ session_id: sessionId,
112
+ };
106
113
  // Team stores: use append-only journal (no FINDINGS.md mutation, no merge conflicts)
107
114
  {
108
115
  const storeResolved = resolveStoreForProject(ctx, params.project);
@@ -112,7 +119,7 @@ async function handleAddFinding(ctx, params) {
112
119
  const added = [];
113
120
  for (const f of findings) {
114
121
  const taggedFinding = findingType ? `[${findingType}] ${f}` : f;
115
- const result = appendTeamJournal(phrenPath, project, taggedFinding);
122
+ const result = appendTeamJournal(phrenPath, project, taggedFinding, provenance.actor, provenance.machine);
116
123
  if (result.ok)
117
124
  added.push(taggedFinding);
118
125
  }
@@ -150,6 +157,7 @@ async function handleAddFinding(ctx, params) {
150
157
  extraAnnotationsByFinding,
151
158
  sessionId,
152
159
  scope: normalizedScope,
160
+ provenance,
153
161
  });
154
162
  if (!result.ok)
155
163
  return mcpResponse({ ok: false, error: result.error });
@@ -189,6 +197,7 @@ async function handleAddFinding(ctx, params) {
189
197
  sessionId,
190
198
  scope: normalizedScope,
191
199
  extraAnnotations: semanticConflicts.checked ? semanticConflicts.annotations : undefined,
200
+ provenance,
192
201
  });
193
202
  if (!result.ok) {
194
203
  return mcpResponse({ ok: false, error: result.error });
@@ -14,7 +14,7 @@ import { runCustomHooks } from "../hooks.js";
14
14
  import { entryScoreKey, getQualityMultiplier, getRetentionPolicy } from "../shared/governance.js";
15
15
  import { callLlm } from "../content/dedup.js";
16
16
  import { rankResults, searchKnowledgeRows, applyTrustFilter, searchFederatedStores } from "../shared/retrieval.js";
17
- import { parseScopeComment, parseSourceComment } from "../content/citation.js";
17
+ import { formatActorAttribution, parseScopeComment, parseSourceComment } from "../content/citation.js";
18
18
  import { resolveActiveSessionScope } from "./session.js";
19
19
  import { logger } from "../logger.js";
20
20
  /**
@@ -668,7 +668,8 @@ async function handleGetFindings(ctx, { project, limit, include_superseded, incl
668
668
  if (entry.tier === "archived")
669
669
  metadata.push("tier=archived");
670
670
  const idLabel = entry.stableId ? `${entry.id}|fid:${entry.stableId}` : entry.id;
671
- return `- [${idLabel}] ${entry.date}: ${entry.text}${entry.confidence !== undefined ? ` [confidence ${entry.confidence.toFixed(2)}]` : ""}${metadata.length > 0 ? ` [${metadata.join(" ")}]` : ""}${entry.citation ? ` (${entry.citation})` : ""}`;
671
+ const attribution = formatActorAttribution(entry.actor, entry.machine);
672
+ return `- [${idLabel}] ${entry.date}: ${entry.text}${attribution ? ` ${attribution}` : ""}${entry.confidence !== undefined ? ` [confidence ${entry.confidence.toFixed(2)}]` : ""}${metadata.length > 0 ? ` [${metadata.join(" ")}]` : ""}${entry.citation ? ` (${entry.citation})` : ""}`;
672
673
  });
673
674
  const hiddenHistoryCount = includeHistory ? 0 : historyCount;
674
675
  const historyNote = hiddenHistoryCount > 0 ? ` (${hiddenHistoryCount} historical hidden)` : "";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@phren/cli",
3
- "version": "0.1.23",
3
+ "version": "0.1.24",
4
4
  "description": "Knowledge layer for AI agents — CLI, MCP server, and data layer",
5
5
  "type": "module",
6
6
  "bin": {