tlc-claude-code 2.0.1 → 2.2.0

package/server/lib/memory-bridge-e2e.test.js

@@ -0,0 +1,160 @@
+/**
+ * Memory Bridge E2E Tests - Phase 82 Task 5
+ *
+ * Tests the full pipeline: capture → observeAndRemember → pattern detect → file store.
+ * Proves the memory system achieves its original goal.
+ *
+ * RED: depends on capture-bridge.js (Task 1) and capture-guard.js (Task 4).
+ */
+
+import { describe, it, beforeEach, afterEach, expect, vi } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+import { captureExchange, drainSpool, SPOOL_FILENAME } from './capture-bridge.js';
+import { observeAndRemember } from './memory-observer.js';
+
+describe('memory-bridge e2e', () => {
+  let testDir;
+
+  beforeEach(() => {
+    testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tlc-bridge-e2e-'));
+    // Create memory directory structure
+    fs.mkdirSync(path.join(testDir, '.tlc', 'memory', 'team', 'decisions'), { recursive: true });
+    fs.mkdirSync(path.join(testDir, '.tlc', 'memory', 'team', 'gotchas'), { recursive: true });
+    fs.mkdirSync(path.join(testDir, '.tlc', 'memory', '.local'), { recursive: true });
+    fs.writeFileSync(path.join(testDir, '.tlc.json'), JSON.stringify({ project: 'e2e-test' }));
+  });
+
+  afterEach(() => {
+    fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it('decision in exchange creates decision file', async () => {
+    // Pattern detector analyzes the user field for decision patterns
+    const exchange = {
+      user: "let's use PostgreSQL instead of MySQL because we need JSONB support.",
+      assistant: 'Good choice. PostgreSQL has excellent JSONB support.',
+    };
+
+    await observeAndRemember(testDir, exchange);
+
+    // Wait for setImmediate-based async processing
+    await new Promise(resolve => setTimeout(resolve, 500));
+
+    // Check that a decision file was created
+    const decisionsDir = path.join(testDir, '.tlc', 'memory', 'team', 'decisions');
+    const files = fs.readdirSync(decisionsDir);
+    expect(files.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it('gotcha in exchange creates gotcha file', async () => {
+    // Pattern detector looks for "watch out for X" in user field
+    const exchange = {
+      user: 'watch out for the PGlite WASM driver under concurrent writes.',
+      assistant: 'Good catch. Serialize database operations to avoid crashes.',
+    };
+
+    await observeAndRemember(testDir, exchange);
+
+    await new Promise(resolve => setTimeout(resolve, 500));
+
+    const gotchasDir = path.join(testDir, '.tlc', 'memory', 'team', 'gotchas');
+    const files = fs.readdirSync(gotchasDir);
+    expect(files.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it('full pipeline: captureExchange → observe → file stored', async () => {
+    // Simulate what the Stop hook does: POST to a mock server that calls observeAndRemember
+    let capturedExchange = null;
+
+    // Mock fetch that simulates the server calling observeAndRemember
+    const mockFetch = vi.fn().mockImplementation(async (url, opts) => {
+      const body = JSON.parse(opts.body);
+      for (const ex of body.exchanges) {
+        capturedExchange = ex;
+        await observeAndRemember(testDir, ex);
+      }
+      return { ok: true, json: async () => ({ captured: body.exchanges.length }) };
+    });
+
+    await captureExchange({
+      cwd: testDir,
+      // Pattern detector analyzes user field — put decision language there
+      assistantMessage: 'Good choice, JWT is better for horizontal scaling.',
+      userMessage: "let's use JWT tokens instead of sessions for authentication.",
+      sessionId: 'e2e-sess-1',
+    }, { fetch: mockFetch });
+
+    await new Promise(resolve => setTimeout(resolve, 300));
+
+    // Verify the exchange was captured
+    expect(capturedExchange).not.toBeNull();
+    expect(capturedExchange.user).toContain('JWT tokens');
+
+    // Verify a decision file was created
+    const decisionsDir = path.join(testDir, '.tlc', 'memory', 'team', 'decisions');
+    const files = fs.readdirSync(decisionsDir);
+    expect(files.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it('spool entry captured after drain', async () => {
+    const spoolDir = path.join(testDir, '.tlc', 'memory');
+    const spoolPath = path.join(spoolDir, SPOOL_FILENAME);
+
+    // Write a spooled entry with a decision (pattern in user field)
+    const spooledEntry = JSON.stringify({
+      projectId: 'e2e-test',
+      exchanges: [{
+        user: "we decided to use SQLite for the vector store.",
+        assistant: 'SQLite embeds directly and needs no separate process.',
+        timestamp: Date.now(),
+      }],
+    });
+    fs.writeFileSync(spoolPath, spooledEntry + '\n');
+
+    // Mock fetch that calls observeAndRemember (like the real server would)
+    const mockFetch = vi.fn().mockImplementation(async (url, opts) => {
+      const body = JSON.parse(opts.body);
+      for (const ex of body.exchanges) {
+        await observeAndRemember(testDir, ex);
+      }
+      return { ok: true, json: async () => ({ captured: body.exchanges.length }) };
+    });
+
+    await drainSpool(spoolDir, { fetch: mockFetch });
+
+    await new Promise(resolve => setTimeout(resolve, 500));
+
+    // Spool should be drained
+    if (fs.existsSync(spoolPath)) {
+      expect(fs.readFileSync(spoolPath, 'utf-8').trim()).toBe('');
+    }
+
+    // Decision file should have been created from the spooled exchange
+    const decisionsDir = path.join(testDir, '.tlc', 'memory', 'team', 'decisions');
+    const files = fs.readdirSync(decisionsDir);
+    expect(files.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it('capture guard deduplicates identical exchanges', async () => {
+    // Dedup happens at the capture guard level, not the observer
+    const { createCaptureGuard } = await import('./capture-guard.js');
+    const guard = createCaptureGuard();
+
+    const exchange = {
+      user: "we decided to use Redis as our caching layer.",
+      assistant: 'Redis is great for caching.',
+      timestamp: Date.now(),
+    };
+
+    // First call returns the exchange
+    const first = guard.deduplicate([exchange], 'e2e-test');
+    expect(first).toHaveLength(1);
+
+    // Same exchange immediately — deduplicated
+    const second = guard.deduplicate([exchange], 'e2e-test');
+    expect(second).toHaveLength(0);
+  });
+});

package/server/lib/memory-committer.js

@@ -23,7 +23,24 @@ async function detectUncommittedMemory(projectRoot) {
     return [];
   }
 
-  // Get all files in team directory
+  // Try git status first — only return modified/untracked files
+  try {
+    const teamRelative = path.relative(projectRoot, teamDir);
+    const { stdout } = await execAsync(
+      `git status --porcelain -- "${teamRelative}"`,
+      { cwd: projectRoot }
+    );
+    if (stdout.trim().length === 0) return [];
+
+    return stdout.trim().split('\n')
+      .map(line => line.slice(3).trim()) // strip status prefix (e.g. "?? ", " M ")
+      .filter(f => f.endsWith('.json') || f.endsWith('.md'))
+      .filter(f => !f.endsWith('conventions.md'));
+  } catch {
+    // Not a git repo or git not available — fall back to walkDir
+  }
+
+  // Fallback: return all files (non-git directory)
   const files = [];
 
   async function walkDir(dir) {
@@ -33,10 +50,7 @@ async function detectUncommittedMemory(projectRoot) {
       if (entry.isDirectory()) {
         await walkDir(fullPath);
       } else if (entry.name.endsWith('.json') || entry.name.endsWith('.md')) {
-        // Skip template files like conventions.md
         if (entry.name === 'conventions.md') continue;
-
-        // Get path relative to projectRoot
         const relativePath = path.relative(projectRoot, fullPath);
         files.push(relativePath);
       }

package/server/lib/memory-committer.test.js

@@ -58,6 +58,27 @@ describe('memory-committer', () => {
 
       expect(uncommitted.every(f => !f.includes('.local'))).toBe(true);
     });
+
+    // Phase 81 Task 4: detectUncommittedMemory should use git status
+    it('returns empty for already-committed files in a git repo', async () => {
+      // Create a git repo, add a decision, and commit it
+      const { execSync } = await import('child_process');
+      execSync('git init', { cwd: testDir, stdio: 'pipe' });
+      execSync('git config user.email "test@test.com"', { cwd: testDir, stdio: 'pipe' });
+      execSync('git config user.name "Test"', { cwd: testDir, stdio: 'pipe' });
+
+      await writeTeamDecision(testDir, {
+        title: 'Committed Decision',
+        reasoning: 'Already committed',
+      });
+
+      execSync('git add -A', { cwd: testDir, stdio: 'pipe' });
+      execSync('git commit -m "initial"', { cwd: testDir, stdio: 'pipe' });
+
+      // Now detect uncommitted — should be empty since everything is committed
+      const uncommitted = await detectUncommittedMemory(testDir);
+      expect(uncommitted).toHaveLength(0);
+    });
   });
 
   describe('generateCommitMessage', () => {

package/server/lib/memory-hooks-capture.test.js

@@ -297,18 +297,20 @@ describe('memory-hooks capture (auto-capture hooks)', () => {
     it('buffer resets after chunk written', async () => {
       const hooks = createCaptureHooks(testDir, makeDeps());
 
-      // Fill buffer to threshold
+      // Fill buffer to threshold — the 5th exchange triggers processBuffer
+      // which atomically swaps the buffer before async processing
       for (let i = 0; i < 5; i++) {
         hooks.onExchange(makeExchange(`q${i}`, `a${i}`));
       }
 
-      expect(hooks.getBufferSize()).toBe(5);
-
       // Wait for async processing to complete
       await new Promise(resolve => setTimeout(resolve, 100));
 
-      // Buffer should be reset after chunking
+      // Buffer should be empty after processing
       expect(hooks.getBufferSize()).toBe(0);
+      // Chunker should have received the 5 exchanges
+      expect(mockChunker.chunkConversation).toHaveBeenCalled();
+      expect(mockChunker.chunkConversation.mock.calls[0][0]).toHaveLength(5);
     });
 
     it('flush() forces processing regardless of buffer size', async () => {
@@ -346,5 +348,68 @@ describe('memory-hooks capture (auto-capture hooks)', () => {
       expect(indexCallArgs).toBeDefined();
       expect(indexCallArgs[0]).toHaveProperty('id', 'chunk-1');
     });
+
+    // Phase 81 Task 3: Buffer race condition tests
+    it('exchanges added during async processing are not lost', async () => {
+      // Use a synchronous chunker but slow richCapture to simulate the race
+      const slowRichCapture = {
+        writeConversationChunk: vi.fn().mockImplementation(async () => {
+          // Simulate slow async write — yields control back to event loop
+          await new Promise(resolve => setTimeout(resolve, 80));
+          return '/tmp/slow-write.md';
+        }),
+      };
+
+      const hooks = createCaptureHooks(testDir, makeDeps({ richCapture: slowRichCapture }));
+
+      // Add 5 exchanges to trigger processing
+      for (let i = 0; i < 5; i++) {
+        hooks.onExchange(makeExchange(`q${i}`, `a${i}`));
+      }
+
+      // Wait briefly for processing to start (microtask scheduled)
+      await new Promise(resolve => setTimeout(resolve, 20));
+
+      // Now add more exchanges DURING the slow processing
+      hooks.onExchange(makeExchange('late-q1', 'late-a1'));
+      hooks.onExchange(makeExchange('late-q2', 'late-a2'));
+
+      // Wait for processing to complete
+      await new Promise(resolve => setTimeout(resolve, 200));
+
+      // The late exchanges must NOT have been lost
+      // They should be in the buffer (preserved) or processed in a second batch
+      const bufferSize = hooks.getBufferSize();
+      const chunkCalls = mockChunker.chunkConversation.mock.calls.length;
+      // Either late exchanges remain in buffer, or they triggered a second batch
+      expect(bufferSize === 2 || chunkCalls > 1).toBe(true);
+    });
+
+    it('error during processing preserves new exchanges', async () => {
+      const slowFailRichCapture = {
+        writeConversationChunk: vi.fn().mockImplementation(async () => {
+          await new Promise(resolve => setTimeout(resolve, 30));
+          throw new Error('Write failed');
+        }),
+      };
+
+      const hooks = createCaptureHooks(testDir, makeDeps({ richCapture: slowFailRichCapture }));
+
+      // Trigger processing (will fail during write)
+      for (let i = 0; i < 5; i++) {
+        hooks.onExchange(makeExchange(`q${i}`, `a${i}`));
+      }
+
+      // Wait for processing to start, then add exchange during failure
+      await new Promise(resolve => setTimeout(resolve, 10));
+      hooks.onExchange(makeExchange('after-error-q', 'after-error-a'));
+
+      // Wait for error processing to complete
+      await new Promise(resolve => setTimeout(resolve, 100));
+
+      // The new exchange added during the failing processing must be preserved
+      const bufferSize = hooks.getBufferSize();
+      expect(bufferSize).toBeGreaterThanOrEqual(1);
+    });
   });
 });

package/server/lib/memory-hooks-integration.test.js

@@ -0,0 +1,98 @@
+/**
+ * Memory Hooks Integration Tests - Phase 81 Task 6
+ *
+ * Tests for createServerMemoryCapture() which wires memory hooks
+ * into the TLC server lifecycle so that conversations are automatically
+ * captured without user action.
+ */
+
+import { describe, it, beforeEach, afterEach, expect, vi } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+// The function under test — will be created in implementation
+import { createServerMemoryCapture } from './memory-hooks.js';
+
+describe('memory-hooks server integration', () => {
+  let testDir;
+
+  beforeEach(() => {
+    testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tlc-hooks-integration-'));
+    // Create minimal memory structure
+    fs.mkdirSync(path.join(testDir, '.tlc', 'memory', 'team', 'decisions'), { recursive: true });
+    fs.mkdirSync(path.join(testDir, '.tlc', 'memory', '.local', 'sessions'), { recursive: true });
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it('createServerMemoryCapture returns object with expected methods', () => {
+    const capture = createServerMemoryCapture({
+      projectRoot: testDir,
+      observeAndRemember: vi.fn(),
+    });
+
+    expect(capture).toHaveProperty('onAssistantResponse');
+    expect(capture).toHaveProperty('onTlcCommand');
+    expect(typeof capture.onAssistantResponse).toBe('function');
+    expect(typeof capture.onTlcCommand).toBe('function');
+  });
+
+  it('onAssistantResponse triggers observeAndRemember', async () => {
+    const mockObserve = vi.fn();
+    const capture = createServerMemoryCapture({
+      projectRoot: testDir,
+      observeAndRemember: mockObserve,
+    });
+
+    await capture.onAssistantResponse('We should use PostgreSQL for better JSON support');
+
+    expect(mockObserve).toHaveBeenCalledTimes(1);
+    expect(mockObserve).toHaveBeenCalledWith(
+      testDir,
+      expect.objectContaining({ assistant: 'We should use PostgreSQL for better JSON support' })
+    );
+  });
+
+  it('onTlcCommand triggers capture flush', async () => {
+    const mockObserve = vi.fn();
+    const capture = createServerMemoryCapture({
+      projectRoot: testDir,
+      observeAndRemember: mockObserve,
+    });
+
+    // Add some responses first
+    await capture.onAssistantResponse('first response');
+    await capture.onAssistantResponse('second response');
+
+    // TLC command should work without error
+    expect(() => capture.onTlcCommand('build')).not.toThrow();
+  });
+
+  it('capture failure does not throw', async () => {
+    const failingObserve = vi.fn().mockRejectedValue(new Error('Observation failed'));
+    const capture = createServerMemoryCapture({
+      projectRoot: testDir,
+      observeAndRemember: failingObserve,
+    });
+
+    // Should not throw despite observer failure
+    await expect(
+      capture.onAssistantResponse('this will fail to observe')
+    ).resolves.not.toThrow();
+  });
+
+  it('works when projectRoot has no memory structure', () => {
+    const emptyDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tlc-empty-'));
+
+    expect(() => createServerMemoryCapture({
+      projectRoot: emptyDir,
+      observeAndRemember: vi.fn(),
+    })).not.toThrow();
+
+    fs.rmSync(emptyDir, { recursive: true, force: true });
+  });
+});

package/server/lib/memory-hooks.js

@@ -158,19 +158,21 @@ function createCaptureHooks(projectRoot, deps) {
 
     processing = true;
 
+    // Snapshot and reset buffer atomically BEFORE async processing.
+    // New exchanges arriving during processing go into the fresh buffer.
+    const snapshot = buffer;
+    buffer = [];
+
     Promise.resolve().then(async () => {
       try {
-        const exchanges = buffer.slice();
-        const chunks = chunker.chunkConversation(exchanges);
+        const chunks = chunker.chunkConversation(snapshot);
         for (const chunk of chunks) {
           await richCapture.writeConversationChunk(projectRoot, chunk);
           await vectorIndexer.indexChunk(chunk);
         }
-        buffer = [];
       } catch (_err) {
         // Error resilience: capture failures must not propagate.
         // Hooks remain functional after errors.
-        buffer = [];
       } finally {
         processing = false;
       }
@@ -221,8 +223,44 @@ function createCaptureHooks(projectRoot, deps) {
   };
 }
 
+/**
+ * Create server-level memory capture that wires observeAndRemember into
+ * the TLC server lifecycle so conversations are automatically captured.
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectRoot - Project root directory
+ * @param {Function} opts.observeAndRemember - The observe-and-remember function from memory-observer
+ * @returns {{ onAssistantResponse: Function, onTlcCommand: Function }}
+ */
+function createServerMemoryCapture({ projectRoot, observeAndRemember }) {
+  /**
+   * Called after each assistant response — fires observeAndRemember.
+   * Errors are swallowed to avoid disrupting the response flow.
+   * @param {string} response - The assistant response text
+   */
+  async function onAssistantResponse(response) {
+    try {
+      await observeAndRemember(projectRoot, { assistant: response });
+    } catch (_err) {
+      // Capture failures must not propagate
+    }
+  }
+
+  /**
+   * Called when a TLC command is invoked — currently a no-op placeholder
+   * for future flush/capture logic.
+   * @param {string} _command - The TLC command name
+   */
+  function onTlcCommand(_command) {
+    // Placeholder for future capture flush on TLC commands
+  }
+
+  return { onAssistantResponse, onTlcCommand };
+}
+
 module.exports = {
   createMemoryHooks,
   MemoryHooks,
   createCaptureHooks,
+  createServerMemoryCapture,
 };

package/server/lib/memory-store-adapter.js

@@ -0,0 +1,105 @@
+/**
+ * File-based memory store adapter.
+ *
+ * Reads decisions and gotchas from `.tlc/memory/team/` markdown files on disk.
+ * No vector DB required — just file-based reading. Returns empty arrays when
+ * no files exist.
+ *
+ * @module memory-store-adapter
+ */
+
+const path = require('path');
+const realFs = require('fs');
+
+/**
+ * Parse a markdown file into a memory entry.
+ * Extracts the title from the first `# Heading` line.
+ *
+ * @param {string} content - Raw markdown content
+ * @param {string} filename - Original filename
+ * @returns {{ title: string, content: string, filename: string }}
+ */
+function parseMarkdownEntry(content, filename) {
+  const headingMatch = content.match(/^#\s+(.+)$/m);
+  const title = headingMatch ? headingMatch[1].trim() : filename.replace(/\.md$/, '');
+  return { title, content, filename };
+}
+
+/**
+ * Read markdown files from a directory and parse them into entries.
+ *
+ * @param {string} dirPath - Directory to read
+ * @param {object} fsImpl - fs implementation (for testing)
+ * @returns {Array<{ title: string, content: string, filename: string }>}
+ */
+function readMarkdownDir(dirPath, fsImpl) {
+  if (!fsImpl.existsSync(dirPath)) {
+    return [];
+  }
+
+  const files = fsImpl.readdirSync(dirPath);
+  const entries = [];
+
+  for (const file of files) {
+    if (!file.endsWith('.md')) continue;
+    try {
+      const content = fsImpl.readFileSync(path.join(dirPath, file), 'utf-8');
+      entries.push(parseMarkdownEntry(content, file));
+    } catch {
+      // Skip files that can't be read
+    }
+  }
+
+  return entries;
+}
+
+/**
+ * Create a file-based memory store adapter for a project.
+ *
+ * @param {string} projectPath - Absolute path to the project root
+ * @param {object} [options]
+ * @param {object} [options.fs] - fs implementation (for testing)
+ * @returns {{ listDecisions: Function, listGotchas: Function, getStats: Function }}
+ */
+function createMemoryStoreAdapter(projectPath, options = {}) {
+  const fsImpl = options.fs || realFs;
+  const decisionsDir = path.join(projectPath, '.tlc', 'memory', 'team', 'decisions');
+  const gotchasDir = path.join(projectPath, '.tlc', 'memory', 'team', 'gotchas');
+
+  /**
+   * List all decisions from the project's memory directory.
+   * @param {object} [options] - Filter options (unused for file-based)
+   * @returns {Promise<Array>}
+   */
+  async function listDecisions() {
+    return readMarkdownDir(decisionsDir, fsImpl);
+  }
+
+  /**
+   * List all gotchas from the project's memory directory.
+   * @param {object} [options] - Filter options (unused for file-based)
+   * @returns {Promise<Array>}
+   */
+  async function listGotchas() {
+    return readMarkdownDir(gotchasDir, fsImpl);
+  }
+
+  /**
+   * Get basic stats about the memory store.
+   * @returns {Promise<{ decisions: number, gotchas: number, total: number }>}
+   */
+  async function getStats() {
+    const dCount = fsImpl.existsSync(decisionsDir)
+      ? fsImpl.readdirSync(decisionsDir).filter(f => f.endsWith('.md')).length
+      : 0;
+    const gCount = fsImpl.existsSync(gotchasDir)
+      ? fsImpl.readdirSync(gotchasDir).filter(f => f.endsWith('.md')).length
+      : 0;
+
+    return { decisions: dCount, gotchas: gCount, total: dCount + gCount };
+  }
+
+  return { listDecisions, listGotchas, getStats };
+}
+
+module.exports = { createMemoryStoreAdapter };