tlc-claude-code 2.0.1 → 2.1.0

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 };

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

@@ -0,0 +1,141 @@
+/**
+ * @file memory-store-adapter.test.js
+ * @description Tests for the file-based memory store adapter.
+ *
+ * The adapter reads decisions and gotchas from .tlc/memory/team/ markdown
+ * files on disk. Returns empty arrays when directories don't exist.
+ */
+import { describe, it, beforeEach, expect, vi } from 'vitest';
+
+const { createMemoryStoreAdapter } = await import('./memory-store-adapter.js');
+
+describe('memory-store-adapter', () => {
+  let mockFs;
+
+  beforeEach(() => {
+    mockFs = {
+      existsSync: vi.fn().mockReturnValue(false),
+      readdirSync: vi.fn().mockReturnValue([]),
+      readFileSync: vi.fn().mockReturnValue(''),
+    };
+  });
+
+  describe('createMemoryStoreAdapter', () => {
+    it('returns an object with listDecisions, listGotchas, getStats', () => {
+      const adapter = createMemoryStoreAdapter('/fake/project', { fs: mockFs });
+      expect(adapter).toHaveProperty('listDecisions');
+      expect(adapter).toHaveProperty('listGotchas');
+      expect(adapter).toHaveProperty('getStats');
+      expect(typeof adapter.listDecisions).toBe('function');
+      expect(typeof adapter.listGotchas).toBe('function');
+      expect(typeof adapter.getStats).toBe('function');
+    });
+  });
+
+  describe('listDecisions', () => {
+    it('returns empty array when decisions directory does not exist', async () => {
+      mockFs.existsSync.mockReturnValue(false);
+      const adapter = createMemoryStoreAdapter('/fake/project', { fs: mockFs });
+      const result = await adapter.listDecisions();
+      expect(result).toEqual([]);
+    });
+
+    it('reads markdown files from decisions directory', async () => {
+      mockFs.existsSync.mockReturnValue(true);
+      mockFs.readdirSync.mockReturnValue(['001-use-postgres.md', '002-rest-api.md']);
+      mockFs.readFileSync
+        .mockReturnValueOnce('# Use Postgres\n\nWe chose Postgres for the database.\n\n**Date:** 2026-01-20\n**Status:** accepted')
+        .mockReturnValueOnce('# REST over GraphQL\n\nREST is simpler for our use case.\n\n**Date:** 2026-01-22\n**Status:** accepted');
+
+      const adapter = createMemoryStoreAdapter('/fake/project', { fs: mockFs });
+      const result = await adapter.listDecisions();
+
+      expect(result).toHaveLength(2);
+      expect(result[0]).toHaveProperty('title', 'Use Postgres');
+      expect(result[0]).toHaveProperty('content');
+      expect(result[1]).toHaveProperty('title', 'REST over GraphQL');
+    });
+
+    it('handles malformed markdown gracefully', async () => {
+      mockFs.existsSync.mockReturnValue(true);
+      mockFs.readdirSync.mockReturnValue(['bad.md']);
+      mockFs.readFileSync.mockReturnValue('no heading here just text');
+
+      const adapter = createMemoryStoreAdapter('/fake/project', { fs: mockFs });
+      const result = await adapter.listDecisions();
+
+      expect(result).toHaveLength(1);
+      expect(result[0]).toHaveProperty('title');
+    });
+
+    it('skips non-markdown files', async () => {
+      mockFs.existsSync.mockReturnValue(true);
+      mockFs.readdirSync.mockReturnValue(['decision.md', 'notes.txt', '.DS_Store']);
+      mockFs.readFileSync.mockReturnValue('# A Decision\n\nContent here');
+
+      const adapter = createMemoryStoreAdapter('/fake/project', { fs: mockFs });
+      const result = await adapter.listDecisions();
+
+      expect(result).toHaveLength(1);
+    });
+  });
+
+  describe('listGotchas', () => {
+    it('returns empty array when gotchas directory does not exist', async () => {
+      mockFs.existsSync.mockReturnValue(false);
+      const adapter = createMemoryStoreAdapter('/fake/project', { fs: mockFs });
+      const result = await adapter.listGotchas();
+      expect(result).toEqual([]);
+    });
+
+    it('reads markdown files from gotchas directory', async () => {
+      mockFs.existsSync.mockReturnValue(true);
+      mockFs.readdirSync.mockReturnValue(['001-cold-starts.md']);
+      mockFs.readFileSync.mockReturnValue('# Cold Start Delay\n\nLambda cold starts cause 2s delay.\n\n**Severity:** high');
+
+      const adapter = createMemoryStoreAdapter('/fake/project', { fs: mockFs });
+      const result = await adapter.listGotchas();
+
+      expect(result).toHaveLength(1);
+      expect(result[0]).toHaveProperty('title', 'Cold Start Delay');
+      expect(result[0]).toHaveProperty('content');
+    });
+
+    it('handles read errors gracefully', async () => {
+      mockFs.existsSync.mockReturnValue(true);
+      mockFs.readdirSync.mockReturnValue(['broken.md']);
+      mockFs.readFileSync.mockImplementation(() => { throw new Error('EACCES'); });
+
+      const adapter = createMemoryStoreAdapter('/fake/project', { fs: mockFs });
+      const result = await adapter.listGotchas();
+
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe('getStats', () => {
+    it('returns zero counts when no directories exist', async () => {
+      mockFs.existsSync.mockReturnValue(false);
+      const adapter = createMemoryStoreAdapter('/fake/project', { fs: mockFs });
+      const stats = await adapter.getStats();
+
+      expect(stats).toHaveProperty('decisions', 0);
+      expect(stats).toHaveProperty('gotchas', 0);
+      expect(stats).toHaveProperty('total', 0);
+    });
+
+    it('returns file counts from both directories', async () => {
+      mockFs.existsSync.mockReturnValue(true);
+      mockFs.readdirSync
+        .mockReturnValueOnce(['d1.md', 'd2.md', 'd3.md'])
+        .mockReturnValueOnce(['g1.md']);
+
+      const adapter = createMemoryStoreAdapter('/fake/project', { fs: mockFs });
+      const stats = await adapter.getStats();
+
+      expect(stats.decisions).toBe(3);
+      expect(stats.gotchas).toBe(1);
+      expect(stats.total).toBe(4);
+    });
+  });
+});

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

@@ -0,0 +1,93 @@
+/**
+ * Memory wiring E2E tests - Phase 84 Task 4
+ *
+ * Proves the full memory loop: exchange → observeAndRemember → file written → adapter reads back.
+ * This is the definitive test that memory actually works end-to-end.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+import { observeAndRemember } from './memory-observer.js';
+import { createMemoryStoreAdapter } from './memory-store-adapter.js';
+
+describe('memory wiring e2e', () => {
+  let testDir;
+
+  beforeEach(() => {
+    testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tlc-wiring-e2e-'));
+    // Create full 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', 'preferences'), { recursive: true });
+    fs.mkdirSync(path.join(testDir, '.tlc', 'memory', '.local', 'sessions'), { recursive: true });
+    fs.writeFileSync(path.join(testDir, '.tlc.json'), JSON.stringify({ project: 'wiring-test' }));
+  });
+
+  afterEach(() => {
+    fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it('decision exchange → file created → adapter reads it back', async () => {
+    const exchange = {
+      user: "let's use PostgreSQL instead of MySQL for better JSONB support.",
+      assistant: 'Good choice. PostgreSQL has excellent JSONB support.',
+    };
+
+    await observeAndRemember(testDir, exchange);
+    await new Promise(resolve => setTimeout(resolve, 500));
+
+    // Adapter reads it back
+    const adapter = createMemoryStoreAdapter(testDir);
+    const decisions = await adapter.listDecisions();
+    expect(decisions.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it('gotcha exchange → file created → adapter reads it back', async () => {
+    const exchange = {
+      user: 'watch out for the SQLite WAL mode issue under concurrent writes.',
+      assistant: 'Noted. Serialize database operations to avoid corruption.',
+    };
+
+    await observeAndRemember(testDir, exchange);
+    await new Promise(resolve => setTimeout(resolve, 500));
+
+    const adapter = createMemoryStoreAdapter(testDir);
+    const gotchas = await adapter.listGotchas();
+    expect(gotchas.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it('stats reflect actual file counts', async () => {
+    // Write a decision
+    const exchange = {
+      user: "we decided to use Redis as our caching layer instead of Memcached.",
+      assistant: 'Redis is more versatile for caching.',
+    };
+
+    await observeAndRemember(testDir, exchange);
+    await new Promise(resolve => setTimeout(resolve, 500));
+
+    const adapter = createMemoryStoreAdapter(testDir);
+    const stats = await adapter.getStats();
+    expect(stats.decisions).toBeGreaterThanOrEqual(1);
+    expect(stats.total).toBeGreaterThanOrEqual(1);
+  });
+
+  it('empty project returns empty arrays without crashing', async () => {
+    const emptyDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tlc-empty-'));
+    fs.writeFileSync(path.join(emptyDir, '.tlc.json'), JSON.stringify({ project: 'empty' }));
+
+    const adapter = createMemoryStoreAdapter(emptyDir);
+    const decisions = await adapter.listDecisions();
+    const gotchas = await adapter.listGotchas();
+    const stats = await adapter.getStats();
+
+    expect(decisions).toEqual([]);
+    expect(gotchas).toEqual([]);
+    expect(stats.total).toBe(0);
+
+    fs.rmSync(emptyDir, { recursive: true, force: true });
+  });
+});