tlc-claude-code 2.4.2 → 2.4.4

package/server/lib/capture/ensure-ready.js

@@ -0,0 +1,56 @@
+const path = require('path');
+
+const REQUIRED_DIRECTORIES = [
+  path.join('.tlc', 'memory', 'team', 'decisions'),
+  path.join('.tlc', 'memory', 'team', 'gotchas'),
+  path.join('.tlc', 'memory', '.local', 'sessions'),
+];
+
+const REQUIRED_GITKEEPS = [
+  path.join('.tlc', 'memory', 'team', 'decisions', '.gitkeep'),
+  path.join('.tlc', 'memory', 'team', 'gotchas', '.gitkeep'),
+];
+
+function ensureDirectory(projectDir, relativePath, fs, created, existing) {
+  const fullPath = path.join(projectDir, relativePath);
+
+  if (fs.existsSync(fullPath)) {
+    existing.push(relativePath);
+    return;
+  }
+
+  fs.mkdirSync(fullPath, { recursive: true });
+  created.push(relativePath);
+}
+
+function ensureFile(projectDir, relativePath, fs, created, existing) {
+  const fullPath = path.join(projectDir, relativePath);
+
+  if (fs.existsSync(fullPath)) {
+    existing.push(relativePath);
+    return;
+  }
+
+  fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+  fs.writeFileSync(fullPath, '');
+  created.push(relativePath);
+}
+
+function ensureMemoryReady(projectDir, { fs = require('fs') } = {}) {
+  const created = [];
+  const existing = [];
+
+  for (const relativePath of REQUIRED_DIRECTORIES) {
+    ensureDirectory(projectDir, relativePath, fs, created, existing);
+  }
+
+  for (const relativePath of REQUIRED_GITKEEPS) {
+    ensureFile(projectDir, relativePath, fs, created, existing);
+  }
+
+  return { created, existing };
+}
+
+module.exports = {
+  ensureMemoryReady,
+};

package/server/lib/capture/ensure-ready.test.js

@@ -0,0 +1,135 @@
+import { describe, it, beforeEach, afterEach, expect, vi } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+const TARGETS = [
+  path.join('.tlc', 'memory', 'team', 'decisions'),
+  path.join('.tlc', 'memory', 'team', 'gotchas'),
+  path.join('.tlc', 'memory', '.local', 'sessions'),
+];
+
+const GITKEEPS = [
+  path.join('.tlc', 'memory', 'team', 'decisions', '.gitkeep'),
+  path.join('.tlc', 'memory', 'team', 'gotchas', '.gitkeep'),
+];
+
+describe('ensureMemoryReady', () => {
+  let projectDir;
+  let ensureMemoryReady;
+
+  beforeEach(async () => {
+    projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tlc-ensure-ready-test-'));
+    ({ ensureMemoryReady } = await import('./ensure-ready.js'));
+  });
+
+  afterEach(() => {
+    vi.resetModules();
+    fs.rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it('creates the canonical memory directories and team .gitkeep files', () => {
+    const result = ensureMemoryReady(projectDir);
+
+    expect(result.created.slice().sort()).toEqual([...TARGETS, ...GITKEEPS].sort());
+    expect(result.existing).toEqual([]);
+
+    for (const relativePath of TARGETS) {
+      expect(fs.existsSync(path.join(projectDir, relativePath))).toBe(true);
+    }
+
+    for (const relativePath of GITKEEPS) {
+      expect(fs.existsSync(path.join(projectDir, relativePath))).toBe(true);
+      expect(fs.readFileSync(path.join(projectDir, relativePath), 'utf8')).toBe('');
+    }
+  });
+
+  it('is idempotent across repeated calls', () => {
+    const first = ensureMemoryReady(projectDir);
+    const second = ensureMemoryReady(projectDir);
+
+    expect(first.created.slice().sort()).toEqual([...TARGETS, ...GITKEEPS].sort());
+    expect(second.created).toEqual([]);
+    expect(second.existing.slice().sort()).toEqual([...TARGETS, ...GITKEEPS].sort());
+  });
+
+  it('reports pre-existing directories and .gitkeep files separately from new ones', () => {
+    fs.mkdirSync(path.join(projectDir, '.tlc', 'memory', 'team', 'decisions'), { recursive: true });
+    fs.writeFileSync(path.join(projectDir, '.tlc', 'memory', 'team', 'decisions', '.gitkeep'), '');
+    fs.mkdirSync(path.join(projectDir, '.tlc', 'memory', '.local', 'sessions'), { recursive: true });
+
+    const result = ensureMemoryReady(projectDir);
+
+    expect(result.created.slice().sort()).toEqual([
+      path.join('.tlc', 'memory', 'team', 'gotchas'),
+      path.join('.tlc', 'memory', 'team', 'gotchas', '.gitkeep'),
+    ].sort());
+    expect(result.existing.slice().sort()).toEqual([
+      path.join('.tlc', 'memory', 'team', 'decisions'),
+      path.join('.tlc', 'memory', 'team', 'decisions', '.gitkeep'),
+      path.join('.tlc', 'memory', '.local', 'sessions'),
+    ].sort());
+  });
+
+  it('creates missing .gitkeep files when team directories already exist', () => {
+    fs.mkdirSync(path.join(projectDir, '.tlc', 'memory', 'team', 'decisions'), { recursive: true });
+    fs.mkdirSync(path.join(projectDir, '.tlc', 'memory', 'team', 'gotchas'), { recursive: true });
+    fs.mkdirSync(path.join(projectDir, '.tlc', 'memory', '.local', 'sessions'), { recursive: true });
+
+    const result = ensureMemoryReady(projectDir);
+
+    expect(result.created.slice().sort()).toEqual(GITKEEPS.slice().sort());
+    expect(result.existing.slice().sort()).toEqual(TARGETS.slice().sort());
+  });
+
+  it('does not overwrite existing .gitkeep content', () => {
+    const decisionsGitkeep = path.join(projectDir, '.tlc', 'memory', 'team', 'decisions', '.gitkeep');
+    const gotchasGitkeep = path.join(projectDir, '.tlc', 'memory', 'team', 'gotchas', '.gitkeep');
+
+    fs.mkdirSync(path.dirname(decisionsGitkeep), { recursive: true });
+    fs.mkdirSync(path.dirname(gotchasGitkeep), { recursive: true });
+    fs.mkdirSync(path.join(projectDir, '.tlc', 'memory', '.local', 'sessions'), { recursive: true });
+    fs.writeFileSync(decisionsGitkeep, 'keep me\n');
+    fs.writeFileSync(gotchasGitkeep, 'still here\n');
+
+    const result = ensureMemoryReady(projectDir);
+
+    expect(result.created).toEqual([]);
+    expect(result.existing.slice().sort()).toEqual([...TARGETS, ...GITKEEPS].sort());
+    expect(fs.readFileSync(decisionsGitkeep, 'utf8')).toBe('keep me\n');
+    expect(fs.readFileSync(gotchasGitkeep, 'utf8')).toBe('still here\n');
+  });
+
+  it('creates parent directories recursively from an empty project root', () => {
+    ensureMemoryReady(projectDir);
+
+    expect(fs.existsSync(path.join(projectDir, '.tlc'))).toBe(true);
+    expect(fs.existsSync(path.join(projectDir, '.tlc', 'memory', 'team'))).toBe(true);
+    expect(fs.existsSync(path.join(projectDir, '.tlc', 'memory', '.local'))).toBe(true);
+  });
+
+  it('supports injected fs implementations', () => {
+    const injectedFs = {
+      ...fs,
+      mkdirSync: vi.fn(fs.mkdirSync),
+      writeFileSync: vi.fn(fs.writeFileSync),
+      existsSync: vi.fn(fs.existsSync),
+    };
+
+    const result = ensureMemoryReady(projectDir, { fs: injectedFs });
+
+    expect(result.created.slice().sort()).toEqual([...TARGETS, ...GITKEEPS].sort());
+    expect(injectedFs.mkdirSync).toHaveBeenCalled();
+    expect(injectedFs.writeFileSync).toHaveBeenCalledTimes(2);
+  });
+
+  it('handles partially initialized local memory trees', () => {
+    fs.mkdirSync(path.join(projectDir, '.tlc', 'memory', '.local'), { recursive: true });
+
+    const result = ensureMemoryReady(projectDir);
+
+    expect(result.created.slice().sort()).toEqual([...TARGETS, ...GITKEEPS].sort());
+    expect(result.existing).toEqual([]);
+    expect(fs.existsSync(path.join(projectDir, '.tlc', 'memory', '.local', 'sessions'))).toBe(true);
+  });
+});

package/server/lib/capture/envelope.js

@@ -0,0 +1,77 @@
+const crypto = require('crypto');
+
+function normalizeMessage(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+
+  return value.trim();
+}
+
+function createEnvelope({
+  provider,
+  source,
+  taskName,
+  threadId,
+  userMessage,
+  assistantMessage,
+  timestamp,
+}) {
+  const normalizedUserMessage = normalizeMessage(userMessage);
+  const normalizedAssistantMessage = normalizeMessage(assistantMessage);
+  const parts = [normalizedUserMessage, normalizedAssistantMessage].filter(Boolean);
+
+  if (parts.length === 0) {
+    throw new Error('createEnvelope requires at least one non-empty message');
+  }
+
+  return {
+    provider,
+    source,
+    taskName,
+    threadId,
+    text: parts.join('\n\n'),
+    timestamp: typeof timestamp === 'string' ? timestamp : new Date().toISOString(),
+    metadata: {
+      userMessage,
+      assistantMessage,
+    },
+  };
+}
+
+function validateEnvelope(obj) {
+  const errors = [];
+  const value = obj || {};
+
+  if (typeof value.provider !== 'string') {
+    errors.push('provider must be a string');
+  }
+
+  if (typeof value.text !== 'string' || value.text.trim() === '') {
+    errors.push('text must be a non-empty string');
+  }
+
+  if (typeof value.timestamp !== 'string') {
+    errors.push('timestamp must be a string');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+function idempotencyKey(envelope) {
+  const provider = typeof envelope.provider === 'string' ? envelope.provider : '';
+  const timestamp = typeof envelope.timestamp === 'string' ? envelope.timestamp : '';
+  const text = typeof envelope.text === 'string' ? envelope.text : '';
+  const payload = provider + timestamp + text.slice(0, 100);
+
+  return crypto.createHash('sha256').update(payload).digest('hex');
+}
+
+module.exports = {
+  createEnvelope,
+  validateEnvelope,
+  idempotencyKey,
+};

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

@@ -0,0 +1,169 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import crypto from 'crypto';
+
+describe('capture/envelope', () => {
+  let envelopeModule;
+
+  beforeEach(async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-03-28T10:11:12.000Z'));
+    envelopeModule = await import('./envelope.js');
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.resetModules();
+  });
+
+  it('creates a normalized envelope with combined text and metadata', () => {
+    const envelope = envelopeModule.createEnvelope({
+      provider: 'openai',
+      source: 'chat',
+      taskName: 'capture',
+      threadId: 'thread-1',
+      userMessage: 'User asks a question',
+      assistantMessage: 'Assistant answers it',
+      timestamp: '2026-03-27T00:00:00.000Z',
+    });
+
+    expect(envelope).toEqual({
+      provider: 'openai',
+      source: 'chat',
+      taskName: 'capture',
+      threadId: 'thread-1',
+      text: 'User asks a question\n\nAssistant answers it',
+      timestamp: '2026-03-27T00:00:00.000Z',
+      metadata: {
+        userMessage: 'User asks a question',
+        assistantMessage: 'Assistant answers it',
+      },
+    });
+  });
+
+  it('trims both messages before combining them', () => {
+    const envelope = envelopeModule.createEnvelope({
+      provider: 'openai',
+      userMessage: '  hello  ',
+      assistantMessage: '\n world \n',
+    });
+
+    expect(envelope.text).toBe('hello\n\nworld');
+    expect(envelope.metadata).toEqual({
+      userMessage: '  hello  ',
+      assistantMessage: '\n world \n',
+    });
+  });
+
+  it('supports an envelope with only a user message', () => {
+    const envelope = envelopeModule.createEnvelope({
+      provider: 'openai',
+      userMessage: 'Only user content',
+      assistantMessage: '   ',
+    });
+
+    expect(envelope.text).toBe('Only user content');
+  });
+
+  it('supports an envelope with only an assistant message', () => {
+    const envelope = envelopeModule.createEnvelope({
+      provider: 'openai',
+      userMessage: '',
+      assistantMessage: 'Only assistant content',
+    });
+
+    expect(envelope.text).toBe('Only assistant content');
+  });
+
+  it('defaults timestamp to the current ISO string', () => {
+    const envelope = envelopeModule.createEnvelope({
+      provider: 'openai',
+      userMessage: 'hello',
+      assistantMessage: 'world',
+    });
+
+    expect(envelope.timestamp).toBe('2026-03-28T10:11:12.000Z');
+  });
+
+  it('throws when both messages are empty after trimming', () => {
+    expect(() => envelopeModule.createEnvelope({
+      provider: 'openai',
+      userMessage: '   ',
+      assistantMessage: '\n\t',
+    })).toThrow(/at least one/i);
+  });
+
+  it('validateEnvelope returns valid for a complete minimal envelope', () => {
+    expect(envelopeModule.validateEnvelope({
+      provider: 'openai',
+      text: 'combined text',
+      timestamp: '2026-03-28T10:11:12.000Z',
+    })).toEqual({
+      valid: true,
+      errors: [],
+    });
+  });
+
+  it('validateEnvelope reports missing required fields', () => {
+    const result = envelopeModule.validateEnvelope({
+      provider: 42,
+      text: '   ',
+      timestamp: null,
+    });
+
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain('provider must be a string');
+    expect(result.errors).toContain('text must be a non-empty string');
+    expect(result.errors).toContain('timestamp must be a string');
+  });
+
+  it('validateEnvelope allows optional fields and metadata', () => {
+    const result = envelopeModule.validateEnvelope({
+      provider: 'openai',
+      source: 'cli',
+      taskName: 'summarize',
+      threadId: 'thread-9',
+      text: 'combined text',
+      timestamp: '2026-03-28T10:11:12.000Z',
+      metadata: {
+        userMessage: 'u',
+        assistantMessage: 'a',
+      },
+    });
+
+    expect(result).toEqual({
+      valid: true,
+      errors: [],
+    });
+  });
+
+  it('creates a stable idempotency key from provider timestamp and truncated text', () => {
+    const envelope = {
+      provider: 'openai',
+      timestamp: '2026-03-28T10:11:12.000Z',
+      text: 'x'.repeat(120),
+    };
+
+    const expected = crypto
+      .createHash('sha256')
+      .update(`openai2026-03-28T10:11:12.000Z${'x'.repeat(100)}`)
+      .digest('hex');
+
+    expect(envelopeModule.idempotencyKey(envelope)).toBe(expected);
+  });
+
+  it('idempotency key ignores text beyond the first 100 characters', () => {
+    const prefix = 'p'.repeat(100);
+    const first = envelopeModule.idempotencyKey({
+      provider: 'openai',
+      timestamp: '2026-03-28T10:11:12.000Z',
+      text: `${prefix}AAA`,
+    });
+    const second = envelopeModule.idempotencyKey({
+      provider: 'openai',
+      timestamp: '2026-03-28T10:11:12.000Z',
+      text: `${prefix}BBB`,
+    });
+
+    expect(first).toBe(second);
+  });
+});

package/server/lib/capture/extractor.js

@@ -0,0 +1,51 @@
+const { classify } = require('./classifier.js');
+
+function splitSentences(text) {
+  if (typeof text !== 'string' || !text.trim()) {
+    return [];
+  }
+
+  return text
+    .match(/[^.!?\n]+[.!?]?/g)
+    .map((sentence) => sentence.trim())
+    .filter(Boolean);
+}
+
+function extractDecisions(text, { role = 'unknown' } = {}) {
+  const sentences = splitSentences(text);
+  const seen = new Set();
+  const results = [];
+
+  for (const sentence of sentences) {
+    const classification = classify(sentence);
+
+    if (classification.type === 'session') {
+      continue;
+    }
+
+    const statement = sentence;
+
+    if (seen.has(statement)) {
+      continue;
+    }
+
+    seen.add(statement);
+
+    const confidence = role === 'assistant'
+      ? classification.confidence * 1.5
+      : classification.confidence;
+
+    results.push({
+      statement,
+      context: sentence,
+      confidence,
+      role,
+    });
+  }
+
+  return results;
+}
+
+module.exports = {
+  extractDecisions,
+};

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

@@ -0,0 +1,92 @@
+import { describe, it, expect } from 'vitest';
+
+const { extractDecisions } = require('./extractor.js');
+
+describe('capture/extractor', () => {
+  it('extracts a decision statement from explicit decision language', () => {
+    const results = extractDecisions('We decided to use Postgres for the event store.');
+
+    expect(results).toHaveLength(1);
+    expect(results[0]).toMatchObject({
+      statement: 'We decided to use Postgres for the event store.',
+      context: 'We decided to use Postgres for the event store.',
+      role: 'unknown',
+    });
+    expect(results[0].confidence).toBeGreaterThan(0);
+  });
+
+  it('boosts confidence by 1.5x for assistant role', () => {
+    const text = 'We decided to use Postgres.';
+
+    const base = extractDecisions(text)[0];
+    const boosted = extractDecisions(text, { role: 'assistant' })[0];
+
+    expect(boosted.confidence).toBeCloseTo(base.confidence * 1.5, 5);
+    expect(boosted.role).toBe('assistant');
+  });
+
+  it('extracts gotchas from warning phrases', () => {
+    const results = extractDecisions("Don't use synchronous fs calls in request handlers.");
+
+    expect(results).toHaveLength(1);
+    expect(results[0].statement).toBe("Don't use synchronous fs calls in request handlers.");
+    expect(results[0].context).toBe("Don't use synchronous fs calls in request handlers.");
+  });
+
+  it('extracts preferences from personal preference phrases', () => {
+    const results = extractDecisions('I prefer dark theme for late-night debugging.');
+
+    expect(results).toHaveLength(1);
+    expect(results[0].statement).toBe('I prefer dark theme for late-night debugging.');
+  });
+
+  it('returns an empty array when no phrases match', () => {
+    expect(extractDecisions('The server responded in 120ms and all tests passed.')).toEqual([]);
+  });
+
+  it('dedupes repeated statements with the same text', () => {
+    const text = 'We decided to use Postgres. We decided to use Postgres.';
+
+    const results = extractDecisions(text);
+
+    expect(results).toHaveLength(1);
+    expect(results[0].statement).toBe('We decided to use Postgres.');
+  });
+
+  it('extracts the containing sentence as context from multi-sentence input', () => {
+    const text = 'We reviewed the tradeoffs. The approach is to split into worker and api modules. Shipping stays on Friday.';
+
+    const results = extractDecisions(text);
+
+    expect(results).toHaveLength(1);
+    expect(results[0].statement).toBe('The approach is to split into worker and api modules.');
+    expect(results[0].context).toBe('The approach is to split into worker and api modules.');
+  });
+
+  it('extracts multiple unique matches across decision, gotcha, and preference sentences', () => {
+    const text = [
+      'We decided to use Postgres.',
+      'Careful with long transactions on SQLite.',
+      'I like terminal-first workflows.',
+    ].join(' ');
+
+    const results = extractDecisions(text);
+
+    expect(results).toHaveLength(3);
+    expect(results.map((entry) => entry.statement)).toEqual([
+      'We decided to use Postgres.',
+      'Careful with long transactions on SQLite.',
+      'I like terminal-first workflows.',
+    ]);
+  });
+
+  it('captures code-change style decision phrases such as created and implemented', () => {
+    const text = 'Created 3 modules for auth boundaries. Implemented request tracing for retries.';
+
+    const results = extractDecisions(text);
+
+    expect(results).toHaveLength(2);
+    expect(results[0].statement).toBe('Created 3 modules for auth boundaries.');
+    expect(results[1].statement).toBe('Implemented request tracing for retries.');
+  });
+});

package/server/lib/capture/generic-capture.js

@@ -0,0 +1,96 @@
+const path = require('path');
+
+const { createEnvelope } = require('./envelope');
+const { redact } = require('./redactor');
+const { ensureMemoryReady } = require('./ensure-ready');
+
+const SPOOL_PATH = path.join('.tlc', 'memory', '.spool.jsonl');
+
+function appendEnvelope(projectDir, envelope, fs) {
+  ensureMemoryReady(projectDir, { fs });
+
+  const spoolPath = path.join(projectDir, SPOOL_PATH);
+  fs.appendFileSync(spoolPath, `${JSON.stringify(envelope)}\n`, 'utf8');
+}
+
+function createRedactedEnvelope({ text, provider, source, taskName }) {
+  const envelope = createEnvelope({
+    provider,
+    source,
+    taskName,
+    assistantMessage: text,
+  });
+  const redactedText = redact(envelope.text);
+
+  return {
+    ...envelope,
+    text: redactedText,
+    metadata: {
+      ...envelope.metadata,
+      assistantMessage: redact(envelope.metadata.assistantMessage || ''),
+    },
+  };
+}
+
+function captureFromStdout({
+  stdout,
+  provider,
+  taskName,
+  projectDir,
+  fs = require('fs'),
+}) {
+  try {
+    const envelope = createRedactedEnvelope({
+      text: stdout,
+      provider,
+      source: 'stdout',
+      taskName,
+    });
+
+    appendEnvelope(projectDir, envelope, fs);
+
+    return { captured: 1, skipped: 0 };
+  } catch (_) {
+    return { captured: 0, skipped: 1 };
+  }
+}
+
+function extractResponseText(response) {
+  if (typeof response?.content === 'string') {
+    return response.content;
+  }
+
+  if (typeof response?.choices?.[0]?.message?.content === 'string') {
+    return response.choices[0].message.content;
+  }
+
+  return JSON.stringify(response);
+}
+
+function captureFromApiResponse({
+  response,
+  provider,
+  taskName,
+  projectDir,
+  fs = require('fs'),
+}) {
+  try {
+    const envelope = createRedactedEnvelope({
+      text: extractResponseText(response),
+      provider,
+      source: 'api-response',
+      taskName,
+    });
+
+    appendEnvelope(projectDir, envelope, fs);
+
+    return { captured: 1, skipped: 0 };
+  } catch (_) {
+    return { captured: 0, skipped: 1 };
+  }
+}
+
+module.exports = {
+  captureFromStdout,
+  captureFromApiResponse,
+};