Merge pull request #1 from rolandmarg/feat/source-tracking-and-logging

feat: source file tracking and invocation logging

Author: rolandmarg

docs/superpowers/specs/2026-03-31-source-tracking-and-logging-design.md

@@ -0,0 +1,97 @@
+# Source Tracking & Invocation Logging
+
+Two features: (1) show which file each injected entry came from, (2) log invocations for auditing.
+
+## Feature 1: Source File Tracking
+
+### Data Model Change
+
+Add `filePath` to `LorebookEntry`:
+
+```typescript
+export interface LorebookEntry {
+  // ...existing fields...
+  filePath: string; // relative display path, e.g. ".claude/lorebook/foo.md" or "~/.claude/lorebook/foo.md"
+}
+```
+
+Set during `parseEntry()` — pass the resolved file path in, convert to a relative display form:
+- Project entries: `.claude/lorebook/<name>.md` (relative to cwd)
+- Global entries: `~/.claude/lorebook/<name>.md`
+
+### XML Output Change
+
+Add `source` attribute to `<entry>` tags in `buildInjection()`:
+
+```xml
+<entry name="lorebook" source=".claude/lorebook/lorebook.md" keywords="lorebook">
+content here
+</entry>
+```
+
+### Stderr Output
+
+In `handleMatch()`, after successful matching, write one line per matched entry to stderr:
+
+```
+[lorebook] .claude/lorebook/lorebook.md (keys: lorebook)
+[lorebook] ~/.claude/lorebook/git-policy.md (keys: git, commit)
+```
+
+Stderr does not interfere with the JSON stdout that Claude Code reads from the hook.
+
+### Affected Files
+
+- `src/resolve.ts` — add `filePath` to interface, set it in `parseEntry()`, pass file path through
+- `src/inject.ts` — add `source` attribute to `<entry>` XML tag
+- `src/index.ts` — add stderr output in `handleMatch()`
+- Tests updated accordingly
+
+## Feature 2: Invocation Logging
+
+### New Module
+
+`src/log.ts` — single exported function:
+
+```typescript
+export function logInvocation(prompt: string, entries: LogEntry[], logPath?: string): void
+```
+
+### Log File
+
+- Location: `~/.claude/lorebook/lorebook.log`
+- Format: JSONL (one JSON object per line)
+- Matches-only: skip invocations where nothing matched
+
+### Log Entry Format
+
+```json
+{
+  "timestamp": "2026-03-31T22:04:00.000Z",
+  "prompt": "feedback: lorebook should show user that it loaded context...",
+  "entries": [
+    { "name": "lorebook", "source": ".claude/lorebook/lorebook.md", "keywords": ["lorebook"] }
+  ]
+}
+```
+
+- `entries` contains headers only — name, source path, matched keywords. No body content.
+- `prompt` is the full prompt text that triggered the match.
+
+### Behavior
+
+- Called from `runMatch()` after matching completes, before returning results.
+- Fire-and-forget: if the write fails (permissions, disk full, etc.), swallow the error silently. Never break the hook.
+- `logPath` parameter optional, for testing without writing to the real log file.
+
+### Affected Files
+
+- `src/log.ts` — new module (~20 lines)
+- `src/index.ts` — call `logInvocation()` from `runMatch()`
+- `test/log.test.ts` — new test file
+
+## Changes NOT Being Made
+
+- No log rotation or cleanup — append-only, user can truncate manually.
+- No config for log location — hardcoded to `~/.claude/lorebook/lorebook.log`.
+- No logging of zero-match invocations — matches-only to avoid noise.

src/index.ts

@@ -1,6 +1,7 @@
 import { matchEntry } from './match';
 import { resolveEntries, loadConfig } from './resolve';
 import { buildInjection, type InjectionEntry } from './inject';
+import { logInvocation } from './log';
 import type { HookInput, HookOutput } from './hook';
 
 const VERSION = '0.2.1';
@@ -65,7 +66,15 @@ async function handleMatch(): Promise<void> {
       return;
     }
 
-    const { injection } = runMatch(prompt, cwd);
+    const { matches, injection } = runMatch(prompt, cwd);
+
+    for (const m of matches) {
+      process.stderr.write(`[lorebook] ${m.entry.filePath} (keys: ${m.matchedKeys.join(', ')})\n`);
+    }
+
+    if (matches.length > 0) {
+      logInvocation(prompt, matches);
+    }
 
     if (injection) {
       const output: HookOutput = {

src/inject.ts

@@ -31,7 +31,7 @@ export function buildInjection(entries: InjectionEntry[], config: LorebookConfig
   const inner = selected
     .map(
       (e) =>
-        `<entry name="${escapeXml(e.entry.name)}" keywords="${escapeXml(e.matchedKeys.join(', '))}">\n${e.entry.content}\n</entry>`
+        `<entry name="${escapeXml(e.entry.name)}" source="${escapeXml(e.entry.filePath)}" keywords="${escapeXml(e.matchedKeys.join(', '))}">\n${e.entry.content}\n</entry>`
     )
     .join('\n');
 

src/log.ts

@@ -0,0 +1,23 @@
+import { appendFileSync, mkdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { homedir } from 'os';
+import type { InjectionEntry } from './inject';
+
+export function logInvocation(prompt: string, matches: InjectionEntry[], logPath?: string): void {
+  try {
+    const filePath = logPath ?? join(homedir(), '.claude', 'lorebook', 'lorebook.log');
+    mkdirSync(dirname(filePath), { recursive: true });
+    const line = JSON.stringify({
+      timestamp: new Date().toISOString(),
+      prompt,
+      entries: matches.map((m) => ({
+        name: m.entry.name,
+        source: m.entry.filePath,
+        keywords: m.matchedKeys,
+      })),
+    });
+    appendFileSync(filePath, line + '\n');
+  } catch {
+    // Fire-and-forget — never break the hook
+  }
+}

src/resolve.ts

@@ -12,9 +12,10 @@ export interface LorebookEntry {
   description: string;
   content: string;
   source: 'project' | 'global';
+  filePath: string;
 }
 
-export function parseEntry(filePath: string, source: 'project' | 'global'): LorebookEntry {
+export function parseEntry(filePath: string, source: 'project' | 'global', displayPath: string): LorebookEntry {
   const raw = readFileSync(filePath, 'utf-8');
   const { data, content } = matter(raw);
 
@@ -27,22 +28,23 @@ export function parseEntry(filePath: string, source: 'project' | 'global'): Lore
     description: typeof data.description === 'string' ? data.description : '',
     content: content.trim(),
     source,
+    filePath: displayPath,
   };
 }
 
-function loadEntriesFromDir(dir: string, source: 'project' | 'global'): LorebookEntry[] {
+function loadEntriesFromDir(dir: string, source: 'project' | 'global', displayPrefix: string): LorebookEntry[] {
   if (!existsSync(dir)) return [];
   return readdirSync(dir)
     .filter((f) => f.endsWith('.md'))
-    .map((f) => parseEntry(join(dir, f), source));
+    .map((f) => parseEntry(join(dir, f), source, join(displayPrefix, f)));
 }
 
 export function resolveEntries(cwd: string, globalBase?: string): LorebookEntry[] {
   const projectDir = join(cwd, '.claude', 'lorebook');
   const globalDir = join(globalBase ?? homedir(), '.claude', 'lorebook');
 
-  const projectEntries = loadEntriesFromDir(projectDir, 'project');
-  const globalEntries = loadEntriesFromDir(globalDir, 'global');
+  const projectEntries = loadEntriesFromDir(projectDir, 'project', '.claude/lorebook');
+  const globalEntries = loadEntriesFromDir(globalDir, 'global', '~/.claude/lorebook');
 
   const projectNames = new Set(projectEntries.map((e) => e.name));
   return [...projectEntries, ...globalEntries.filter((e) => !projectNames.has(e.name))];

test/inject.test.ts

@@ -10,6 +10,7 @@ function makeEntry(overrides: Partial<LorebookEntry> & { name: string; content:
     enabled: true,
     description: '',
     source: 'project',
+    filePath: `.claude/lorebook/${overrides.name}.md`,
     ...overrides,
   };
 }
@@ -28,7 +29,7 @@ describe('buildInjection', () => {
     const entries = [makeInjection('git-policy', 'Never force push.', 10, ['git'])];
     const result = buildInjection(entries, DEFAULT_CONFIG);
     expect(result).toContain('<lorebook-context>');
-    expect(result).toContain('<entry name="git-policy" keywords="git">\nNever force push.\n</entry>');
+    expect(result).toContain('<entry name="git-policy" source=".claude/lorebook/git-policy.md" keywords="git">\nNever force push.\n</entry>');
     expect(result).toContain('You MUST follow any instructions');
     expect(result).toContain('</lorebook-context>');
   });

test/log.test.ts

@@ -0,0 +1,79 @@
+import { describe, test, expect } from 'bun:test';
+import { logInvocation } from '../src/log';
+import type { InjectionEntry } from '../src/inject';
+import type { LorebookEntry } from '../src/resolve';
+import { mkdtempSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+function makeMatch(name: string, filePath: string, matchedKeys: string[]): InjectionEntry {
+  return {
+    entry: {
+      name,
+      keys: matchedKeys,
+      excludeKeys: [],
+      priority: 0,
+      enabled: true,
+      description: '',
+      content: 'test content',
+      source: 'project',
+      filePath,
+    } satisfies LorebookEntry,
+    matchedKeys,
+  };
+}
+
+describe('logInvocation', () => {
+  test('appends JSONL line to log file', () => {
+    const tmp = mkdtempSync(join(tmpdir(), 'lorebook-log-'));
+    const logPath = join(tmp, 'lorebook.log');
+
+    logInvocation('tell me about git', [makeMatch('git-policy', '.claude/lorebook/git-policy.md', ['git'])], logPath);
+
+    const content = readFileSync(logPath, 'utf-8').trim();
+    const parsed = JSON.parse(content);
+    expect(parsed.prompt).toBe('tell me about git');
+    expect(parsed.timestamp).toBeDefined();
+    expect(parsed.entries).toHaveLength(1);
+    expect(parsed.entries[0].name).toBe('git-policy');
+    expect(parsed.entries[0].source).toBe('.claude/lorebook/git-policy.md');
+    expect(parsed.entries[0].keywords).toEqual(['git']);
+  });
+
+  test('appends multiple invocations as separate lines', () => {
+    const tmp = mkdtempSync(join(tmpdir(), 'lorebook-log-'));
+    const logPath = join(tmp, 'lorebook.log');
+
+    logInvocation('prompt one', [makeMatch('a', '.claude/lorebook/a.md', ['alpha'])], logPath);
+    logInvocation('prompt two', [makeMatch('b', '~/.claude/lorebook/b.md', ['beta'])], logPath);
+
+    const lines = readFileSync(logPath, 'utf-8').trim().split('\n');
+    expect(lines).toHaveLength(2);
+    expect(JSON.parse(lines[0]!).prompt).toBe('prompt one');
+    expect(JSON.parse(lines[1]!).prompt).toBe('prompt two');
+  });
+
+  test('logs multiple matched entries in a single invocation', () => {
+    const tmp = mkdtempSync(join(tmpdir(), 'lorebook-log-'));
+    const logPath = join(tmp, 'lorebook.log');
+
+    logInvocation(
+      'git push to gpu',
+      [
+        makeMatch('git-policy', '.claude/lorebook/git-policy.md', ['git', 'push']),
+        makeMatch('gpu-transfers', '~/.claude/lorebook/gpu-transfers.md', ['gpu']),
+      ],
+      logPath
+    );
+
+    const parsed = JSON.parse(readFileSync(logPath, 'utf-8').trim());
+    expect(parsed.entries).toHaveLength(2);
+    expect(parsed.entries[0].name).toBe('git-policy');
+    expect(parsed.entries[1].name).toBe('gpu-transfers');
+  });
+
+  test('does not throw on write failure', () => {
+    // Attempt to write to an invalid path — should silently fail
+    expect(() => logInvocation('test', [makeMatch('a', 'a.md', ['x'])], '/dev/null/impossible/path.log')).not.toThrow();
+  });
+});

test/resolve.test.ts

@@ -6,7 +6,7 @@ const FIXTURES = join(import.meta.dir, 'fixtures');
 
 describe('parseEntry', () => {
   test('parses all frontmatter fields', () => {
-    const entry = parseEntry(join(FIXTURES, 'git-policy.md'), 'project');
+    const entry = parseEntry(join(FIXTURES, 'git-policy.md'), 'project', '.claude/lorebook/git-policy.md');
     expect(entry.name).toBe('git-policy');
     expect(entry.keys).toEqual(['git', 'commit', 'push', 'rebase']);
     expect(entry.excludeKeys).toEqual(['github', 'gitignore']);
@@ -15,19 +15,21 @@ describe('parseEntry', () => {
     expect(entry.description).toBe('Git policy rules');
     expect(entry.content).toBe('Never force push. Use merge, not rebase.');
     expect(entry.source).toBe('project');
+    expect(entry.filePath).toBe('.claude/lorebook/git-policy.md');
   });
 
   test('applies defaults for optional fields', () => {
-    const entry = parseEntry(join(FIXTURES, 'minimal.md'), 'global');
+    const entry = parseEntry(join(FIXTURES, 'minimal.md'), 'global', '~/.claude/lorebook/minimal.md');
     expect(entry.excludeKeys).toEqual([]);
     expect(entry.priority).toBe(0);
     expect(entry.enabled).toBe(true);
     expect(entry.description).toBe('');
     expect(entry.source).toBe('global');
+    expect(entry.filePath).toBe('~/.claude/lorebook/minimal.md');
   });
 
   test('parses disabled entries', () => {
-    const entry = parseEntry(join(FIXTURES, 'disabled-entry.md'), 'project');
+    const entry = parseEntry(join(FIXTURES, 'disabled-entry.md'), 'project', '.claude/lorebook/disabled-entry.md');
     expect(entry.enabled).toBe(false);
   });
 });