tlc-claude-code 2.4.2 → 2.4.4

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

package/server/lib/health-check.test.js

@@ -0,0 +1,243 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+const {
+  ensureMemoryDirs,
+  checkGitignoreTeamMemory,
+  checkSpoolEntries,
+  checkCaptureHookInstalled,
+  checkRoutingConfigReadable,
+  checkProviderAvailable,
+  checkCaptureWarningsLog,
+  runHealthChecks,
+} = require('./health-check.js');
+
+describe('health-check', () => {
+  let projectDir;
+
+  beforeEach(() => {
+    projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tlc-health-check-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it('ensureMemoryDirs creates missing memory directories and reports autofixes', async () => {
+    const result = await ensureMemoryDirs(projectDir, { fs });
+
+    expect(fs.existsSync(path.join(projectDir, '.tlc', 'memory', 'team', 'decisions'))).toBe(true);
+    expect(fs.existsSync(path.join(projectDir, '.tlc', 'memory', 'team', 'gotchas'))).toBe(true);
+    expect(fs.existsSync(path.join(projectDir, '.tlc', 'memory', '.local', 'sessions'))).toBe(true);
+    expect(result.passed).toBe('Memory directories ready');
+    expect(result.autoFixed).toHaveLength(3);
+  });
+
+  it('ensureMemoryDirs does not autofix directories that already exist', async () => {
+    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 = await ensureMemoryDirs(projectDir, { fs });
+
+    expect(result.autoFixed).toEqual([]);
+    expect(result.passed).toBe('Memory directories ready');
+  });
+
+  it('ensureMemoryDirs converts fs failures into warnings', async () => {
+    const failingFs = {
+      existsSync: vi.fn(() => false),
+      mkdirSync: vi.fn(() => {
+        throw new Error('mkdir failed');
+      }),
+    };
+
+    const result = await ensureMemoryDirs(projectDir, { fs: failingFs });
+
+    expect(result.passed).toBeNull();
+    expect(result.warning).toContain('[TLC WARNING]');
+    expect(result.warning).toContain('memory directories');
+  });
+
+  it('checkGitignoreTeamMemory warns when team memory path is ignored', async () => {
+    const execSync = vi.fn(() => Buffer.from('.tlc/memory/team/test.md\n'));
+
+    const result = await checkGitignoreTeamMemory(projectDir, { execSync });
+
+    expect(execSync).toHaveBeenCalledWith(
+      'git check-ignore .tlc/memory/team/test.md 2>/dev/null',
+      expect.objectContaining({ cwd: projectDir })
+    );
+    expect(result.warning).toContain('[TLC WARNING]');
+    expect(result.warning).toContain('gitignore');
+    expect(result.passed).toBeNull();
+  });
+
+  it('checkGitignoreTeamMemory passes when git check-ignore does not match', async () => {
+    const execSync = vi.fn(() => Buffer.from(''));
+
+    const result = await checkGitignoreTeamMemory(projectDir, { execSync });
+
+    expect(result.passed).toBe('Team memory is not ignored by git');
+    expect(result.warning).toBeNull();
+  });
+
+  it('checkSpoolEntries warns with byte count when spool file has content', async () => {
+    const spoolPath = path.join(projectDir, '.tlc', 'memory', '.spool.jsonl');
+    fs.mkdirSync(path.dirname(spoolPath), { recursive: true });
+    fs.writeFileSync(spoolPath, '{"event":"queued"}\n');
+
+    const result = await checkSpoolEntries(projectDir, { fs });
+
+    expect(result.warning).toContain('[TLC WARNING]');
+    expect(result.warning).toContain('unprocessed spool entries');
+    expect(result.warning).toContain('19 bytes');
+  });
+
+  it('checkSpoolEntries passes when spool file is missing or empty', async () => {
+    expect((await checkSpoolEntries(projectDir, { fs })).passed).toBe('No unprocessed spool entries');
+
+    const spoolPath = path.join(projectDir, '.tlc', 'memory', '.spool.jsonl');
+    fs.mkdirSync(path.dirname(spoolPath), { recursive: true });
+    fs.writeFileSync(spoolPath, '');
+
+    const result = await checkSpoolEntries(projectDir, { fs });
+    expect(result.passed).toBe('No unprocessed spool entries');
+  });
+
+  it('checkCaptureHookInstalled warns when capture hook is missing', async () => {
+    const result = await checkCaptureHookInstalled(projectDir, { fs });
+
+    expect(result.warning).toContain('[TLC WARNING]');
+    expect(result.warning).toContain('capture hook');
+  });
+
+  it('checkCaptureHookInstalled passes when capture hook exists', async () => {
+    const hookPath = path.join(projectDir, '.claude', 'hooks', 'tlc-capture-exchange.sh');
+    fs.mkdirSync(path.dirname(hookPath), { recursive: true });
+    fs.writeFileSync(hookPath, '#!/bin/sh\n');
+
+    const result = await checkCaptureHookInstalled(projectDir, { fs });
+
+    expect(result.passed).toBe('Capture hook installed');
+    expect(result.warning).toBeNull();
+  });
+
+  it('checkRoutingConfigReadable warns when .tlc.json is invalid JSON', async () => {
+    fs.writeFileSync(path.join(projectDir, '.tlc.json'), '{invalid');
+
+    const result = await checkRoutingConfigReadable(projectDir, { fs });
+
+    expect(result.warning).toContain('[TLC WARNING]');
+    expect(result.warning).toContain('.tlc.json');
+  });
+
+  it('checkRoutingConfigReadable passes when .tlc.json can be parsed', async () => {
+    fs.writeFileSync(path.join(projectDir, '.tlc.json'), JSON.stringify({ ok: true }));
+
+    const result = await checkRoutingConfigReadable(projectDir, { fs });
+
+    expect(result.passed).toBe('Routing config is readable');
+  });
+
+  it('checkProviderAvailable warns when router state has no available providers', async () => {
+    const statePath = path.join(projectDir, '.tlc', '.router-state.json');
+    fs.mkdirSync(path.dirname(statePath), { recursive: true });
+    fs.writeFileSync(statePath, JSON.stringify({ summary: { available_count: 0 } }));
+
+    const result = await checkProviderAvailable(projectDir, { fs });
+
+    expect(result.warning).toContain('[TLC WARNING]');
+    expect(result.warning).toContain('provider available');
+  });
+
+  it('checkProviderAvailable passes when router state reports available providers', async () => {
+    const statePath = path.join(projectDir, '.tlc', '.router-state.json');
+    fs.mkdirSync(path.dirname(statePath), { recursive: true });
+    fs.writeFileSync(statePath, JSON.stringify({ summary: { available_count: 2 } }));
+
+    const result = await checkProviderAvailable(projectDir, { fs });
+
+    expect(result.passed).toBe('At least one provider is available');
+  });
+
+  it('checkCaptureWarningsLog warns when recent capture warnings exist', async () => {
+    const warningsPath = path.join(projectDir, '.tlc', 'memory', '.capture-warnings.log');
+    fs.mkdirSync(path.dirname(warningsPath), { recursive: true });
+    fs.writeFileSync(warningsPath, `${new Date().toISOString()} capture lag detected\n`);
+
+    const result = await checkCaptureWarningsLog(projectDir, { fs });
+
+    expect(result.warning).toContain('[TLC WARNING]');
+    expect(result.warning).toContain('capture warnings');
+    expect(result.warning).toContain('last 24h');
+  });
+
+  it('checkCaptureWarningsLog passes when warnings are older than 24 hours', async () => {
+    const warningsPath = path.join(projectDir, '.tlc', 'memory', '.capture-warnings.log');
+    const oldDate = new Date(Date.now() - (25 * 60 * 60 * 1000)).toISOString();
+    fs.mkdirSync(path.dirname(warningsPath), { recursive: true });
+    fs.writeFileSync(warningsPath, `${oldDate} old warning\n`);
+
+    const result = await checkCaptureWarningsLog(projectDir, { fs });
+
+    expect(result.passed).toBe('No recent capture warnings');
+  });
+
+  it('runHealthChecks aggregates passed checks, warnings, and autofixes', async () => {
+    fs.writeFileSync(path.join(projectDir, '.tlc.json'), JSON.stringify({ ok: true }));
+    fs.mkdirSync(path.join(projectDir, '.claude', 'hooks'), { recursive: true });
+    fs.writeFileSync(
+      path.join(projectDir, '.claude', 'hooks', 'tlc-capture-exchange.sh'),
+      '#!/bin/sh\n'
+    );
+    fs.mkdirSync(path.join(projectDir, '.tlc'), { recursive: true });
+    fs.writeFileSync(
+      path.join(projectDir, '.tlc', '.router-state.json'),
+      JSON.stringify({ summary: { available_count: 1 } })
+    );
+
+    const execSync = vi.fn(() => Buffer.from(''));
+    const result = await runHealthChecks(projectDir, { fs, execSync });
+
+    expect(result.passed).toContain('Memory directories ready');
+    expect(result.passed).toContain('Team memory is not ignored by git');
+    expect(result.passed).toContain('Capture hook installed');
+    expect(result.passed).toContain('Routing config is readable');
+    expect(result.passed).toContain('At least one provider is available');
+    expect(result.warnings).toEqual([]);
+    expect(result.autoFixed).toHaveLength(3);
+  });
+
+  it('runHealthChecks never throws when dependencies fail and returns warnings instead', async () => {
+    const failingFs = {
+      existsSync: vi.fn(() => {
+        throw new Error('exists failed');
+      }),
+      mkdirSync: vi.fn(() => {
+        throw new Error('mkdir failed');
+      }),
+      readFileSync: vi.fn(() => {
+        throw new Error('read failed');
+      }),
+      statSync: vi.fn(() => {
+        throw new Error('stat failed');
+      }),
+    };
+    const execSync = vi.fn(() => {
+      throw new Error('git failed');
+    });
+
+    const result = await runHealthChecks(projectDir, { fs: failingFs, execSync });
+
+    expect(Array.isArray(result.passed)).toBe(true);
+    expect(Array.isArray(result.warnings)).toBe(true);
+    expect(Array.isArray(result.autoFixed)).toBe(true);
+    expect(result.warnings.length).toBeGreaterThan(0);
+    expect(result.warnings.every((warning) => warning.startsWith('[TLC WARNING]'))).toBe(true);
+  });
+});

package/server/lib/model-router.js

@@ -13,6 +13,10 @@ const DEFAULT_CONFIG = {
   devserver: { url: null },
 };
 
+function isMissingConfigError(error) {
+  return error?.code === 'ENOENT' || error?.message?.includes('ENOENT');
+}
+
 export class ModelRouter {
   constructor(config = {}) {
     this.config = { ...DEFAULT_CONFIG, ...config };
@@ -88,8 +92,13 @@ export class ModelRouter {
         this.config = { ...DEFAULT_CONFIG, ...configData.router };
         this.devserverUrl = configData.router.devserver?.url || null;
       }
-    } catch {
-      // Use defaults
+    } catch (error) {
+      if (!isMissingConfigError(error)) {
+        const message = error instanceof SyntaxError
+          ? 'Failed to parse .tlc.json router config; using defaults'
+          : `Failed to load .tlc.json router config; using defaults (${error?.message || 'unknown error'})`;
+        console.warn(`[TLC WARNING] ${message}`);
+      }
     }
   }
 }

package/server/lib/model-router.test.js

@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import {
   ModelRouter,
   resolveProvider,
@@ -22,6 +22,10 @@ describe('Model Router', () => {
     });
   });
 
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
   describe('resolveProvider', () => {
     it('returns local when CLI detected', async () => {
       router._detectCLI = vi.fn().mockResolvedValue({ found: true, path: '/usr/bin/claude' });
@@ -105,6 +109,28 @@ describe('Model Router', () => {
 
       expect(router.config).toBeDefined();
     });
+
+    it('warns when config JSON is invalid', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      router._readConfig = vi.fn().mockRejectedValue(new SyntaxError('Unexpected token }'));
+
+      await router.loadConfig();
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        '[TLC WARNING] Failed to parse .tlc.json router config; using defaults'
+      );
+    });
+
+    it('stays silent when config file is missing', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const error = new Error('ENOENT');
+      error.code = 'ENOENT';
+      router._readConfig = vi.fn().mockRejectedValue(error);
+
+      await router.loadConfig();
+
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
   });
 
   describe('handleUnavailable', () => {