tlc-claude-code 2.4.3 → 2.4.4

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

@@ -0,0 +1,278 @@
+import { describe, it, beforeEach, afterEach, expect, vi } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+const spoolRelativePath = path.join('.tlc', 'memory', '.spool.jsonl');
+
+function readFile(filePath) {
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+function readSpool(projectDir) {
+  const spoolPath = path.join(projectDir, spoolRelativePath);
+
+  if (!fs.existsSync(spoolPath)) {
+    return null;
+  }
+
+  return readFile(spoolPath);
+}
+
+function writeSpool(projectDir, lines) {
+  const spoolPath = path.join(projectDir, spoolRelativePath);
+  fs.mkdirSync(path.dirname(spoolPath), { recursive: true });
+  fs.writeFileSync(spoolPath, lines.join('\n'));
+}
+
+function findMarkdownFiles(projectDir, relativeDir) {
+  const targetDir = path.join(projectDir, relativeDir);
+
+  if (!fs.existsSync(targetDir)) {
+    return [];
+  }
+
+  return fs.readdirSync(targetDir)
+    .filter((entry) => entry.endsWith('.md') && entry !== '.gitkeep')
+    .sort();
+}
+
+describe('capture/spool-processor', () => {
+  let projectDir;
+  let processSpool;
+
+  beforeEach(async () => {
+    projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tlc-spool-processor-test-'));
+    ({ processSpool } = await import('./spool-processor.js'));
+  });
+
+  afterEach(() => {
+    vi.resetModules();
+    fs.rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it('returns zero counts when the spool file is missing', () => {
+    const result = processSpool(projectDir);
+
+    expect(result).toEqual({
+      processed: 0,
+      skipped: 0,
+      warnings: [],
+    });
+  });
+
+  it('writes team decisions, team gotchas, and personal sessions to their target directories', () => {
+    writeSpool(projectDir, [
+      JSON.stringify({
+        provider: 'codex',
+        source: 'stdout',
+        taskName: 'Build auth module',
+        timestamp: '2026-03-28T12:34:56.000Z',
+        text: [
+          'We decided to use Postgres for auth state.',
+          "Don't use synchronous fs calls in request handlers.",
+          'I prefer terminal-first workflows for debugging.',
+        ].join(' '),
+      }),
+    ]);
+
+    const result = processSpool(projectDir);
+
+    expect(result).toEqual({
+      processed: 1,
+      skipped: 0,
+      warnings: [],
+    });
+
+    const decisionFiles = findMarkdownFiles(projectDir, path.join('.tlc', 'memory', 'team', 'decisions'));
+    const gotchaFiles = findMarkdownFiles(projectDir, path.join('.tlc', 'memory', 'team', 'gotchas'));
+    const sessionFiles = findMarkdownFiles(projectDir, path.join('.tlc', 'memory', '.local', 'sessions'));
+
+    expect(decisionFiles).toEqual(['2026-03-28-we-decided-to-use-postgres.md']);
+    expect(gotchaFiles).toEqual(['2026-03-28-dont-use-synchronous-fs-calls.md']);
+    expect(sessionFiles).toEqual(['2026-03-28-i-prefer-terminal-first-workflows.md']);
+
+    expect(readFile(path.join(projectDir, '.tlc', 'memory', 'team', 'decisions', decisionFiles[0]))).toContain([
+      '---',
+      'provider: codex',
+      'source: stdout',
+      'timestamp: 2026-03-28T12:34:56.000Z',
+      'taskName: "Build auth module"',
+      'confidence: 0.9',
+      'type: decision',
+      'scope: team',
+      '---',
+      '',
+      'We decided to use Postgres for auth state.',
+    ].join('\n'));
+
+    expect(readFile(path.join(projectDir, '.tlc', 'memory', 'team', 'gotchas', gotchaFiles[0]))).toContain('type: gotcha');
+    expect(readFile(path.join(projectDir, '.tlc', 'memory', '.local', 'sessions', sessionFiles[0]))).toContain('scope: personal');
+    expect(readSpool(projectDir)).toBe('');
+  });
+
+  it('skips malformed JSON lines and keeps them in the spool with a warning', () => {
+    writeSpool(projectDir, [
+      '{"provider":"codex"',
+      JSON.stringify({
+        provider: 'codex',
+        source: 'stdout',
+        taskName: 'Build auth module',
+        timestamp: '2026-03-28T12:34:56.000Z',
+        text: 'We decided to use Postgres for auth state.',
+      }),
+    ]);
+
+    const result = processSpool(projectDir);
+
+    expect(result.processed).toBe(1);
+    expect(result.skipped).toBe(1);
+    expect(result.warnings).toHaveLength(1);
+    expect(result.warnings[0]).toContain('Malformed JSON');
+    expect(readSpool(projectDir)).toBe('{"provider":"codex"');
+  });
+
+  it('skips invalid envelopes and leaves them in the spool', () => {
+    writeSpool(projectDir, [
+      JSON.stringify({
+        provider: 'codex',
+        source: 'stdout',
+        taskName: 'Build auth module',
+        timestamp: '2026-03-28T12:34:56.000Z',
+      }),
+      JSON.stringify({
+        provider: 'codex',
+        source: 'stdout',
+        taskName: 'Build auth module',
+        timestamp: '2026-03-28T12:34:56.000Z',
+        text: 'We decided to use Postgres for auth state.',
+      }),
+    ]);
+
+    const result = processSpool(projectDir);
+
+    expect(result.processed).toBe(1);
+    expect(result.skipped).toBe(1);
+    expect(result.warnings).toHaveLength(1);
+    expect(result.warnings[0]).toContain('Invalid envelope');
+    expect(readSpool(projectDir)).toBe(JSON.stringify({
+      provider: 'codex',
+      source: 'stdout',
+      taskName: 'Build auth module',
+      timestamp: '2026-03-28T12:34:56.000Z',
+    }));
+  });
+
+  it('treats valid envelopes with no extracted statements as processed and removes them from the spool', () => {
+    writeSpool(projectDir, [
+      JSON.stringify({
+        provider: 'codex',
+        source: 'stdout',
+        taskName: 'Build auth module',
+        timestamp: '2026-03-28T12:34:56.000Z',
+        text: 'The server responded in 120ms and all tests passed.',
+      }),
+    ]);
+
+    const result = processSpool(projectDir);
+
+    expect(result).toEqual({
+      processed: 1,
+      skipped: 0,
+      warnings: [],
+    });
+    expect(findMarkdownFiles(projectDir, path.join('.tlc', 'memory', 'team', 'decisions'))).toEqual([]);
+    expect(findMarkdownFiles(projectDir, path.join('.tlc', 'memory', 'team', 'gotchas'))).toEqual([]);
+    expect(findMarkdownFiles(projectDir, path.join('.tlc', 'memory', '.local', 'sessions'))).toEqual([]);
+    expect(readSpool(projectDir)).toBe('');
+  });
+
+  it('redacts secrets before extraction and writing files', () => {
+    writeSpool(projectDir, [
+      JSON.stringify({
+        provider: 'codex',
+        source: 'stdout',
+        taskName: 'Build auth module',
+        timestamp: '2026-03-28T12:34:56.000Z',
+        text: 'We decided to store token=abc123secret in env docs.',
+      }),
+    ]);
+
+    processSpool(projectDir);
+
+    const [decisionFile] = findMarkdownFiles(projectDir, path.join('.tlc', 'memory', 'team', 'decisions'));
+    const content = readFile(path.join(projectDir, '.tlc', 'memory', 'team', 'decisions', decisionFile));
+
+    expect(content).toContain('We decided to store token=[TOKEN_REDACTED] in env docs.');
+    expect(content).not.toContain('abc123secret');
+  });
+
+  it('truncates slugs to 40 characters and uses the timestamp date prefix', () => {
+    writeSpool(projectDir, [
+      JSON.stringify({
+        provider: 'codex',
+        source: 'stdout',
+        taskName: 'Build auth module',
+        timestamp: '2026-03-29T00:00:01.000Z',
+        text: 'We decided to use extremely descriptive boundary names across packages for clarity.',
+      }),
+    ]);
+
+    processSpool(projectDir);
+
+    const decisionFiles = findMarkdownFiles(projectDir, path.join('.tlc', 'memory', 'team', 'decisions'));
+
+    expect(decisionFiles).toEqual(['2026-03-29-we-decided-to-use-extremely.md']);
+  });
+
+  it('preserves skipped lines in order after processing other entries', () => {
+    const invalidLine = '{"provider":';
+    const validDecision = JSON.stringify({
+      provider: 'codex',
+      source: 'stdout',
+      taskName: 'Build auth module',
+      timestamp: '2026-03-28T12:34:56.000Z',
+      text: 'We decided to use Postgres for auth state.',
+    });
+    const invalidEnvelope = JSON.stringify({
+      provider: 'codex',
+      source: 'stdout',
+      taskName: 'Build auth module',
+      timestamp: '2026-03-28T12:34:56.000Z',
+    });
+
+    writeSpool(projectDir, [invalidLine, validDecision, invalidEnvelope]);
+
+    const result = processSpool(projectDir);
+
+    expect(result.processed).toBe(1);
+    expect(result.skipped).toBe(2);
+    expect(readSpool(projectDir)).toBe([invalidLine, invalidEnvelope].join('\n'));
+  });
+
+  it('supports injected fs implementations', () => {
+    writeSpool(projectDir, [
+      JSON.stringify({
+        provider: 'codex',
+        source: 'stdout',
+        taskName: 'Build auth module',
+        timestamp: '2026-03-28T12:34:56.000Z',
+        text: 'We decided to use Postgres for auth state.',
+      }),
+    ]);
+
+    const injectedFs = {
+      ...fs,
+      existsSync: vi.fn(fs.existsSync),
+      mkdirSync: vi.fn(fs.mkdirSync),
+      readFileSync: vi.fn(fs.readFileSync),
+      writeFileSync: vi.fn(fs.writeFileSync),
+    };
+
+    const result = processSpool(projectDir, { fs: injectedFs });
+
+    expect(result.processed).toBe(1);
+    expect(injectedFs.readFileSync).toHaveBeenCalled();
+    expect(injectedFs.writeFileSync).toHaveBeenCalled();
+  });
+});

package/server/lib/health-check.js

@@ -0,0 +1,255 @@
+const path = require('path');
+
+const DAY_IN_MS = 24 * 60 * 60 * 1000;
+const MEMORY_DIRS = [
+  '.tlc/memory/team/decisions',
+  '.tlc/memory/team/gotchas',
+  '.tlc/memory/.local/sessions',
+];
+
+function passResult(message, autoFixed = []) {
+  return {
+    passed: message,
+    warning: null,
+    autoFixed,
+  };
+}
+
+function warningResult(message, autoFixed = []) {
+  return {
+    passed: null,
+    warning: `[TLC WARNING] ${message}`,
+    autoFixed,
+  };
+}
+
+async function ensureMemoryDirs(projectDir, { fs = require('fs') } = {}) {
+  const autoFixed = [];
+
+  try {
+    for (const relativeDir of MEMORY_DIRS) {
+      const fullPath = path.join(projectDir, relativeDir);
+      if (!fs.existsSync(fullPath)) {
+        fs.mkdirSync(fullPath, { recursive: true });
+        autoFixed.push(relativeDir);
+      }
+    }
+
+    return passResult('Memory directories ready', autoFixed);
+  } catch (error) {
+    return warningResult(
+      `Unable to verify memory directories under .tlc/memory: ${error.message}`,
+      autoFixed
+    );
+  }
+}
+
+async function checkGitignoreTeamMemory(
+  projectDir,
+  { execSync = require('child_process').execSync } = {}
+) {
+  try {
+    const output = execSync('git check-ignore .tlc/memory/team/test.md 2>/dev/null', {
+      cwd: projectDir,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+
+    if (String(output || '').trim()) {
+      return warningResult(
+        'gitignore is blocking team memory. Remove ignore rules covering .tlc/memory/team/.'
+      );
+    }
+
+    return passResult('Team memory is not ignored by git');
+  } catch (error) {
+    if (error && error.status === 1) {
+      return passResult('Team memory is not ignored by git');
+    }
+
+    return warningResult(
+      `Unable to confirm gitignore rules for .tlc/memory/team/. Run git check-ignore manually. ${error.message}`
+    );
+  }
+}
+
+async function checkSpoolEntries(projectDir, { fs = require('fs') } = {}) {
+  const spoolPath = path.join(projectDir, '.tlc', 'memory', '.spool.jsonl');
+
+  try {
+    if (!fs.existsSync(spoolPath)) {
+      return passResult('No unprocessed spool entries');
+    }
+
+    const size = fs.statSync(spoolPath).size;
+    if (size > 0) {
+      return warningResult(
+        `Found unprocessed spool entries in .tlc/memory/.spool.jsonl (${size} bytes). Drain or inspect the spool.`
+      );
+    }
+
+    return passResult('No unprocessed spool entries');
+  } catch (error) {
+    return warningResult(
+      `Unable to inspect .tlc/memory/.spool.jsonl for unprocessed entries: ${error.message}`
+    );
+  }
+}
+
+async function checkCaptureHookInstalled(projectDir, { fs = require('fs') } = {}) {
+  const hookPath = path.join(projectDir, '.claude', 'hooks', 'tlc-capture-exchange.sh');
+
+  try {
+    if (fs.existsSync(hookPath)) {
+      return passResult('Capture hook installed');
+    }
+
+    return warningResult(
+      'Missing capture hook at .claude/hooks/tlc-capture-exchange.sh. Install the TLC capture hook.'
+    );
+  } catch (error) {
+    return warningResult(`Unable to verify capture hook installation: ${error.message}`);
+  }
+}
+
+async function checkRoutingConfigReadable(projectDir, { fs = require('fs') } = {}) {
+  const configPath = path.join(projectDir, '.tlc.json');
+
+  try {
+    const content = fs.readFileSync(configPath, 'utf8');
+    JSON.parse(content);
+    return passResult('Routing config is readable');
+  } catch (error) {
+    return warningResult(`Unable to read valid JSON from .tlc.json. Fix the routing config. ${error.message}`);
+  }
+}
+
+async function checkProviderAvailable(projectDir, { fs = require('fs') } = {}) {
+  const statePath = path.join(projectDir, '.tlc', '.router-state.json');
+
+  try {
+    const content = fs.readFileSync(statePath, 'utf8');
+    const state = JSON.parse(content);
+    const availableCount = Number(state && state.summary && state.summary.available_count);
+
+    if (availableCount > 0) {
+      return passResult('At least one provider is available');
+    }
+
+    return warningResult(
+      'No provider available in .tlc/.router-state.json. Refresh router state or configure a provider.'
+    );
+  } catch (error) {
+    return warningResult(
+      `Unable to read provider availability from .tlc/.router-state.json. Refresh router state. ${error.message}`
+    );
+  }
+}
+
+function countRecentTimestampedLines(content, now = Date.now()) {
+  const cutoff = now - DAY_IN_MS;
+  const lines = String(content || '')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  let recentCount = 0;
+
+  for (const line of lines) {
+    const timestampMatch = line.match(
+      /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z/
+    );
+    if (!timestampMatch) {
+      continue;
+    }
+
+    const timestamp = Date.parse(timestampMatch[0]);
+    if (!Number.isNaN(timestamp) && timestamp >= cutoff) {
+      recentCount += 1;
+    }
+  }
+
+  return recentCount;
+}
+
+async function checkCaptureWarningsLog(projectDir, { fs = require('fs') } = {}) {
+  const warningsPath = path.join(projectDir, '.tlc', 'memory', '.capture-warnings.log');
+
+  try {
+    if (!fs.existsSync(warningsPath)) {
+      return passResult('No recent capture warnings');
+    }
+
+    const content = fs.readFileSync(warningsPath, 'utf8');
+    const recentCount = countRecentTimestampedLines(content);
+
+    if (recentCount > 0) {
+      return warningResult(
+        `Found ${recentCount} capture warnings in the last 24h. Review .tlc/memory/.capture-warnings.log.`
+      );
+    }
+
+    return passResult('No recent capture warnings');
+  } catch (error) {
+    return warningResult(
+      `Unable to inspect .tlc/memory/.capture-warnings.log for recent warnings: ${error.message}`
+    );
+  }
+}
+
+async function runHealthChecks(
+  projectDir,
+  {
+    fs = require('fs'),
+    execSync = require('child_process').execSync,
+  } = {}
+) {
+  const results = {
+    passed: [],
+    warnings: [],
+    autoFixed: [],
+  };
+
+  const checks = [
+    () => ensureMemoryDirs(projectDir, { fs }),
+    () => checkGitignoreTeamMemory(projectDir, { execSync }),
+    () => checkSpoolEntries(projectDir, { fs }),
+    () => checkCaptureHookInstalled(projectDir, { fs }),
+    () => checkRoutingConfigReadable(projectDir, { fs }),
+    () => checkProviderAvailable(projectDir, { fs }),
+    () => checkCaptureWarningsLog(projectDir, { fs }),
+  ];
+
+  for (const check of checks) {
+    try {
+      const result = await check();
+      if (result.passed) {
+        results.passed.push(result.passed);
+      }
+      if (result.warning) {
+        results.warnings.push(result.warning);
+      }
+      if (Array.isArray(result.autoFixed) && result.autoFixed.length > 0) {
+        results.autoFixed.push(...result.autoFixed);
+      }
+    } catch (error) {
+      results.warnings.push(
+        `[TLC WARNING] Health check execution failed unexpectedly: ${error.message}`
+      );
+    }
+  }
+
+  return results;
+}
+
+module.exports = {
+  ensureMemoryDirs,
+  checkGitignoreTeamMemory,
+  checkSpoolEntries,
+  checkCaptureHookInstalled,
+  checkRoutingConfigReadable,
+  checkProviderAvailable,
+  checkCaptureWarningsLog,
+  countRecentTimestampedLines,
+  runHealthChecks,
+};