tlc-claude-code 2.4.3 → 2.4.5

package/server/lib/capture/index.test.js

@@ -0,0 +1,263 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { createRequire } from 'module';
+
+const SPOOL_PATH = path.join('.tlc', 'memory', '.spool.jsonl');
+const WARNING_LOG = path.join('.tlc', 'memory', '.capture-warnings.log');
+const require = createRequire(import.meta.url);
+
+function longOutput() {
+  return 'Decision '.repeat(80);
+}
+
+function readSpoolEntries(projectDir) {
+  const spoolPath = path.join(projectDir, SPOOL_PATH);
+  const content = fs.readFileSync(spoolPath, 'utf8').trim();
+
+  return content.split('\n').filter(Boolean).map((line) => JSON.parse(line));
+}
+
+function createFailingFs() {
+  return {
+    ...fs,
+    appendFileSync: vi.fn(() => {
+      throw new Error('append failed');
+    }),
+  };
+}
+
+describe('capture/index', () => {
+  let projectDir;
+  let captureFromProvider;
+  let captureFromStdout;
+  let captureFromApiResponse;
+
+  beforeEach(async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-03-28T12:34:56.000Z'));
+    projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tlc-capture-index-'));
+    delete process.env.TLC_CAPTURE_WARNINGS;
+    ({ captureFromProvider, captureFromStdout, captureFromApiResponse } = await import('./index.js'));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+    vi.resetModules();
+    delete process.env.TLC_CAPTURE_WARNINGS;
+    fs.rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it('routes claude to claude-capture', () => {
+    captureFromProvider({
+      provider: 'claude',
+      output: 'stdout fallback',
+      taskName: 'Task',
+      hookInput: JSON.stringify({
+        session_id: 'sess-1',
+        assistant_message: 'We decided to use Postgres.',
+      }),
+      projectDir,
+    });
+
+    const [entry] = readSpoolEntries(projectDir);
+
+    expect(entry).toMatchObject({
+      provider: 'claude',
+      source: 'stop-hook',
+      threadId: 'sess-1',
+      text: 'We decided to use Postgres.',
+    });
+  });
+
+  it('routes codex to codex-capture with the expected source resolution', () => {
+    captureFromProvider({
+      provider: 'codex',
+      output: 'stdout fallback',
+      taskName: 'Task',
+      threadId: null,
+      jsonStream: [
+        '{"type":"thread.started","thread_id":"thread-from-json"}',
+        JSON.stringify({
+          type: 'agent_message',
+          message: {
+            items: [
+              { type: 'text', text: 'First agent message' },
+              { type: 'text', text: 'Second agent message' },
+            ],
+          },
+        }),
+      ].join('\n'),
+      projectDir,
+    });
+
+    const [entry] = readSpoolEntries(projectDir);
+
+    expect(entry).toMatchObject({
+      provider: 'codex',
+      source: 'json-stream',
+      threadId: 'thread-from-json',
+      text: 'First agent message\n\nSecond agent message',
+    });
+  });
+
+  it('routes unknown providers to generic stdout capture', () => {
+    captureFromProvider({
+      provider: 'gemini',
+      output: 'Use Redis for caching.',
+      taskName: 'Task',
+      projectDir,
+    });
+
+    const [entry] = readSpoolEntries(projectDir);
+
+    expect(entry).toMatchObject({
+      provider: 'gemini',
+      source: 'stdout',
+      taskName: 'Task',
+      text: 'Use Redis for caching.',
+    });
+  });
+
+  it('re-exports generic capture functions', async () => {
+    const index = require('./index.js');
+    const generic = require('./generic-capture.js');
+
+    expect(index.captureFromStdout).toBe(generic.captureFromStdout);
+    expect(index.captureFromApiResponse).toBe(generic.captureFromApiResponse);
+  });
+
+  it('does not warn when captures succeed', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    captureFromProvider({
+      provider: 'gemini',
+      output: longOutput(),
+      taskName: 'Task',
+      projectDir,
+    });
+
+    expect(warnSpy).not.toHaveBeenCalled();
+    expect(fs.existsSync(path.join(projectDir, WARNING_LOG))).toBe(false);
+  });
+
+  it('does not warn when output is too short', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    captureFromProvider({
+      provider: 'claude',
+      output: 'short output',
+      taskName: 'Task',
+      hookInput: '{"session_id"',
+      projectDir,
+    });
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it('warns and writes to the warning log when a long output captures nothing', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    captureFromProvider({
+      provider: 'claude',
+      output: longOutput(),
+      taskName: 'Investigate retries',
+      hookInput: '{"session_id"',
+      projectDir,
+    });
+
+    const logPath = path.join(projectDir, WARNING_LOG);
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy.mock.calls[0][0]).toContain('No decisions captured from claude');
+    expect(warnSpy.mock.calls[0][0]).toContain('Investigate retries');
+    expect(fs.readFileSync(logPath, 'utf8')).toContain('2026-03-28T12:34:56.000Z');
+    expect(fs.readFileSync(logPath, 'utf8')).toContain('No decisions captured from claude');
+  });
+
+  it('escalates on the third consecutive zero capture for the same provider', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    captureFromProvider({ provider: 'claude', output: longOutput(), taskName: 'Task 1', hookInput: '{"bad"', projectDir });
+    captureFromProvider({ provider: 'claude', output: longOutput(), taskName: 'Task 2', hookInput: '{"bad"', projectDir });
+    captureFromProvider({ provider: 'claude', output: longOutput(), taskName: 'Task 3', hookInput: '{"bad"', projectDir });
+
+    expect(warnSpy).toHaveBeenCalledTimes(3);
+    expect(warnSpy.mock.calls[2][0]).toContain('claude has produced 0 memory captures for 3 consecutive tasks');
+  });
+
+  it('resets the consecutive zero counter after a successful capture', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    captureFromProvider({ provider: 'claude', output: longOutput(), taskName: 'Task 1', hookInput: '{"bad"', projectDir });
+    captureFromProvider({ provider: 'claude', output: longOutput(), taskName: 'Task 2', hookInput: '{"bad"', projectDir });
+    captureFromProvider({
+      provider: 'claude',
+      output: longOutput(),
+      taskName: 'Task 3',
+      hookInput: JSON.stringify({
+        session_id: 'sess-2',
+        assistant_message: 'We decided to use Redis.',
+      }),
+      projectDir,
+    });
+    captureFromProvider({ provider: 'claude', output: longOutput(), taskName: 'Task 4', hookInput: '{"bad"', projectDir });
+
+    expect(warnSpy).toHaveBeenCalledTimes(3);
+    expect(warnSpy.mock.calls[2][0]).toContain('No decisions captured from claude');
+    expect(warnSpy.mock.calls[2][0]).not.toContain('consecutive tasks');
+  });
+
+  it('tracks consecutive zero captures per provider independently', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const failingFs = createFailingFs();
+
+    captureFromProvider({ provider: 'claude', output: longOutput(), taskName: 'Task 1', hookInput: '{"bad"', projectDir });
+    captureFromProvider({
+      provider: 'codex',
+      output: longOutput(),
+      taskName: 'Task 2',
+      threadId: 'thread-1',
+      projectDir,
+      fs: failingFs,
+    });
+    captureFromProvider({ provider: 'claude', output: longOutput(), taskName: 'Task 3', hookInput: '{"bad"', projectDir });
+
+    expect(warnSpy).toHaveBeenCalledTimes(3);
+    expect(warnSpy.mock.calls[1][0]).toContain('No decisions captured from codex');
+    expect(warnSpy.mock.calls[2][0]).toContain('No decisions captured from claude');
+    expect(warnSpy.mock.calls[2][0]).not.toContain('consecutive tasks');
+  });
+
+  it('caps warnings at three per session', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    captureFromProvider({ provider: 'claude', output: longOutput(), taskName: 'Task 1', hookInput: '{"bad"', projectDir });
+    captureFromProvider({ provider: 'claude', output: longOutput(), taskName: 'Task 2', hookInput: '{"bad"', projectDir });
+    captureFromProvider({ provider: 'claude', output: longOutput(), taskName: 'Task 3', hookInput: '{"bad"', projectDir });
+    captureFromProvider({ provider: 'claude', output: longOutput(), taskName: 'Task 4', hookInput: '{"bad"', projectDir });
+    captureFromProvider({ provider: 'claude', output: longOutput(), taskName: 'Task 5', hookInput: '{"bad"', projectDir });
+
+    expect(warnSpy).toHaveBeenCalledTimes(3);
+    const logLines = fs.readFileSync(path.join(projectDir, WARNING_LOG), 'utf8').trim().split('\n');
+    expect(logLines).toHaveLength(3);
+  });
+
+  it('disables warnings entirely when TLC_CAPTURE_WARNINGS is false', () => {
+    process.env.TLC_CAPTURE_WARNINGS = 'false';
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    captureFromProvider({
+      provider: 'claude',
+      output: longOutput(),
+      taskName: 'Investigate retries',
+      hookInput: '{"session_id"',
+      projectDir,
+    });
+
+    expect(warnSpy).not.toHaveBeenCalled();
+    expect(fs.existsSync(path.join(projectDir, WARNING_LOG))).toBe(false);
+  });
+});

package/server/lib/capture/redactor.js

@@ -0,0 +1,68 @@
+function redactKeyValue(input, key, replacement) {
+  const quotedPattern = new RegExp(`(["']?${key}["']?)(\\s*[:=]\\s*)(["'])(.*?)\\3`, 'gi');
+  const barePattern = new RegExp(`(["']?${key}["']?)(\\s*[:=]\\s*)([^\\s"',}]+)`, 'gi');
+
+  return input
+    .replace(quotedPattern, (_, matchedKey, separator, quote) => `${matchedKey}${separator}${quote}${replacement}${quote}`)
+    .replace(barePattern, (_, matchedKey, separator) => `${matchedKey}${separator}${replacement}`);
+}
+
+function redactPaths(input) {
+  return input
+    .replace(/\/Users\/[^/\s]+\/([^\s]+)/g, '~/$1')
+    .replace(/\/home\/[^/\s]+\/([^\s]+)/g, '~/$1');
+}
+
+function collapseStackTrace(input) {
+  const lines = input.split('\n');
+
+  if (lines.length < 4) {
+    return input;
+  }
+
+  const stackLikeLineCount = lines.slice(1).filter((line) => /^\s+at\b/.test(line) || /^(Caused by|Error:)/.test(line)).length;
+
+  if (stackLikeLineCount < 2) {
+    return input;
+  }
+
+  return `${lines[0]}\n... ${lines.length - 2} more lines\n${lines[lines.length - 1]}`;
+}
+
+function applyExtraPatterns(input, extraPatterns) {
+  let output = input;
+
+  for (const entry of extraPatterns) {
+    if (!entry || !(entry.pattern instanceof RegExp) || typeof entry.replacement !== 'string') {
+      continue;
+    }
+
+    output = output.replace(entry.pattern, entry.replacement);
+  }
+
+  return output;
+}
+
+function redact(text, { extraPatterns = [] } = {}) {
+  let output = String(text);
+
+  output = output.replace(/\bsk-[A-Za-z0-9_-]+\b/g, '[API_KEY_REDACTED]');
+  output = output.replace(/\bgh[pus]_[A-Za-z0-9_]+\b/g, '[API_KEY_REDACTED]');
+  output = output.replace(/\bBearer\s+[A-Za-z0-9._-]+\b/gi, 'Bearer [TOKEN_REDACTED]');
+
+  output = redactKeyValue(output, 'token', '[TOKEN_REDACTED]');
+  output = redactKeyValue(output, 'password', '[REDACTED]');
+  output = redactKeyValue(output, 'secret', '[REDACTED]');
+
+  output = redactPaths(output);
+  output = output.replace(/([=:])([A-Za-z0-9+/=]{101,})(?=[^A-Za-z0-9+/=]|$)/g, '$1[BASE64_REDACTED]');
+  output = output.replace(/(^|[\s([{,])([A-Za-z0-9+/=]{101,})(?=$|[\s)\]},])/g, (_, prefix) => `${prefix}[BASE64_REDACTED]`);
+  output = collapseStackTrace(output);
+  output = applyExtraPatterns(output, extraPatterns);
+
+  return output;
+}
+
+module.exports = {
+  redact,
+};

package/server/lib/capture/redactor.test.js

@@ -0,0 +1,93 @@
+import { describe, it, expect } from 'vitest';
+
+describe('capture/redactor', () => {
+  it('redacts OpenAI style API keys', async () => {
+    const { redact } = await import('./redactor.js');
+
+    expect(redact('token sk-abcdefghijklmnopqrstuvwxyz123456')).toContain('[API_KEY_REDACTED]');
+  });
+
+  it('redacts GitHub tokens with ghp_ and ghu_ prefixes', async () => {
+    const { redact } = await import('./redactor.js');
+
+    const output = redact('ghp_abcdefghijklmnopqrstuvwxyz123456 and ghu_abcdefghijklmnopqrstuvwxyz123456');
+
+    expect(output).not.toContain('ghp_abcdefghijklmnopqrstuvwxyz123456');
+    expect(output).not.toContain('ghu_abcdefghijklmnopqrstuvwxyz123456');
+  });
+
+  it('redacts bearer tokens', async () => {
+    const { redact } = await import('./redactor.js');
+
+    expect(redact('Authorization: Bearer abc.def.ghi')).toBe('Authorization: Bearer [TOKEN_REDACTED]');
+  });
+
+  it('redacts token fields inside quoted JSON-like text', async () => {
+    const { redact } = await import('./redactor.js');
+
+    expect(redact('{"token":"abc123secret"}')).toBe('{"token":"[TOKEN_REDACTED]"}');
+  });
+
+  it('redacts password and secret assignments', async () => {
+    const { redact } = await import('./redactor.js');
+
+    const output = redact('password=hunter2 secret=abc PASSWORD="quoted-secret"');
+
+    expect(output).toContain('password=[REDACTED]');
+    expect(output).toContain('secret=[REDACTED]');
+    expect(output).toContain('PASSWORD="[REDACTED]"');
+  });
+
+  it('rewrites absolute user paths under /Users and /home', async () => {
+    const { redact } = await import('./redactor.js');
+
+    const output = redact('See /Users/jurgen/project/file.js and /home/alice/work/app.js');
+
+    expect(output).toBe('See ~/project/file.js and ~/work/app.js');
+  });
+
+  it('collapses stack traces to first and last line with omitted count', async () => {
+    const { redact } = await import('./redactor.js');
+    const input = [
+      'Error: boom',
+      '    at a (/tmp/a.js:1:1)',
+      '    at b (/tmp/b.js:2:2)',
+      '    at c (/tmp/c.js:3:3)',
+      'Caused by: root issue',
+    ].join('\n');
+
+    expect(redact(input)).toBe('Error: boom\n... 3 more lines\nCaused by: root issue');
+  });
+
+  it('does not collapse short multi-line text that is not a stack trace', async () => {
+    const { redact } = await import('./redactor.js');
+    const input = 'line one\nline two';
+
+    expect(redact(input)).toBe('line one\nline two');
+  });
+
+  it('redacts long base64 blobs', async () => {
+    const { redact } = await import('./redactor.js');
+    const blob = 'QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVo='.repeat(4);
+
+    expect(redact(`payload=${blob}`)).toBe('payload=[BASE64_REDACTED]');
+  });
+
+  it('applies extra custom patterns after built-in redaction', async () => {
+    const { redact } = await import('./redactor.js');
+
+    const output = redact('Order ID: 12345', {
+      extraPatterns: [
+        { pattern: /12345/g, replacement: '[ORDER_ID]' },
+      ],
+    });
+
+    expect(output).toBe('Order ID: [ORDER_ID]');
+  });
+
+  it('returns the original string when there is nothing to redact', async () => {
+    const { redact } = await import('./redactor.js');
+
+    expect(redact('plain text only')).toBe('plain text only');
+  });
+});

package/server/lib/capture/spool-processor.js

@@ -0,0 +1,155 @@
+const path = require('path');
+
+const { validateEnvelope } = require('./envelope');
+const { redact } = require('./redactor');
+const { extractDecisions } = require('./extractor');
+const { classify } = require('./classifier');
+const { ensureMemoryReady } = require('./ensure-ready');
+
+const SPOOL_PATH = path.join('.tlc', 'memory', '.spool.jsonl');
+
+function escapeYamlString(value) {
+  return String(value ?? '').replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+function slugify(statement) {
+  const words = String(statement)
+    .toLowerCase()
+    .replace(/['"]/g, '')
+    .match(/[a-z0-9]+/g) || [];
+
+  const slug = words.slice(0, 5).join('-').slice(0, 40).replace(/-+$/g, '');
+
+  return slug || 'entry';
+}
+
+function dateFromTimestamp(timestamp) {
+  const value = typeof timestamp === 'string' ? timestamp.slice(0, 10) : '';
+  return /^\d{4}-\d{2}-\d{2}$/.test(value) ? value : 'unknown-date';
+}
+
+function buildFrontmatter(envelope, classification, confidence, statement) {
+  return [
+    '---',
+    `provider: ${envelope.provider}`,
+    `source: ${envelope.source || 'unknown'}`,
+    `timestamp: ${envelope.timestamp}`,
+    `taskName: "${escapeYamlString(envelope.taskName || '')}"`,
+    `confidence: ${Number(confidence.toFixed(4))}`,
+    `type: ${classification.type}`,
+    `scope: ${classification.scope}`,
+    '---',
+    '',
+    statement,
+    '',
+  ].join('\n');
+}
+
+function resolveTargetDir(classification) {
+  if (classification.scope === 'team' && classification.type === 'decision') {
+    return path.join('.tlc', 'memory', 'team', 'decisions');
+  }
+
+  if (classification.scope === 'team' && classification.type === 'gotcha') {
+    return path.join('.tlc', 'memory', 'team', 'gotchas');
+  }
+
+  return path.join('.tlc', 'memory', '.local', 'sessions');
+}
+
+function nextAvailableFilePath(projectDir, relativeDir, baseName, fs) {
+  const directory = path.join(projectDir, relativeDir);
+  let candidate = `${baseName}.md`;
+  let counter = 2;
+
+  while (fs.existsSync(path.join(directory, candidate))) {
+    candidate = `${baseName}-${counter}.md`;
+    counter += 1;
+  }
+
+  return path.join(directory, candidate);
+}
+
+function writeStatements(projectDir, envelope, statements, fs) {
+  for (const entry of statements) {
+    const classification = classify(entry.statement);
+
+    if (!classification || classification.type === 'session') {
+      continue;
+    }
+
+    const relativeDir = resolveTargetDir(classification);
+    const baseName = `${dateFromTimestamp(envelope.timestamp)}-${slugify(entry.statement)}`;
+    const targetPath = nextAvailableFilePath(projectDir, relativeDir, baseName, fs);
+    const content = buildFrontmatter(envelope, classification, entry.confidence, entry.statement);
+
+    fs.writeFileSync(targetPath, content);
+  }
+}
+
+function processSpool(projectDir, { fs = require('fs') } = {}) {
+  const spoolPath = path.join(projectDir, SPOOL_PATH);
+
+  if (!fs.existsSync(spoolPath)) {
+    return { processed: 0, skipped: 0, warnings: [] };
+  }
+
+  const input = fs.readFileSync(spoolPath, 'utf8');
+  const lines = input === '' ? [] : input.split('\n');
+  const warnings = [];
+  const remainingLines = [];
+  let processed = 0;
+  let skipped = 0;
+  let ensured = false;
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+
+    if (!line.trim()) {
+      continue;
+    }
+
+    let envelope;
+
+    try {
+      envelope = JSON.parse(line);
+    } catch (error) {
+      skipped += 1;
+      remainingLines.push(line);
+      warnings.push(`Malformed JSON on line ${index + 1}: ${error.message}`);
+      continue;
+    }
+
+    const validation = validateEnvelope(envelope);
+
+    if (!validation.valid) {
+      skipped += 1;
+      remainingLines.push(line);
+      warnings.push(`Invalid envelope on line ${index + 1}: ${validation.errors.join(', ')}`);
+      continue;
+    }
+
+    const redactedText = redact(envelope.text);
+    const statements = extractDecisions(redactedText);
+
+    if (!ensured) {
+      ensureMemoryReady(projectDir, { fs });
+      ensured = true;
+    }
+
+    writeStatements(projectDir, envelope, statements, fs);
+    processed += 1;
+  }
+
+  fs.writeFileSync(spoolPath, remainingLines.join('\n'));
+
+  return {
+    processed,
+    skipped,
+    warnings,
+  };
+}
+
+module.exports = {
+  processSpool,
+};