tlc-claude-code 1.4.7 → 1.4.9

package/server/lib/dashboard/tlc-introspection.test.js

@@ -0,0 +1,138 @@
+/**
+ * TLC Introspection Module Tests
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { parseRoadmap, parseProjectMd, parseTlcConfig, getProjectState, getCurrentPhase, createTlcIntrospection } from './tlc-introspection.js';
+
+describe('tlc-introspection', () => {
+  describe('parseRoadmap', () => {
+    it('parses phases from ROADMAP.md', () => {
+      const content = `
+## Milestone: v1.0
+### Phase 1: Core [x]
+### Phase 2: Tests [>]
+### Phase 3: Deploy [ ]
+`;
+      const phases = parseRoadmap(content);
+      expect(phases.length).toBe(3);
+      expect(phases[0].status).toBe('complete');
+      expect(phases[1].status).toBe('current');
+      expect(phases[2].status).toBe('pending');
+    });
+
+    it('extracts phase names', () => {
+      const content = `### Phase 1: Core Infrastructure [x]`;
+      const phases = parseRoadmap(content);
+      expect(phases[0].name).toBe('Core Infrastructure');
+      expect(phases[0].number).toBe(1);
+    });
+
+    it('groups phases by milestone', () => {
+      const content = `
+## Milestone: v1.0
+### Phase 1: Core [x]
+## Milestone: v2.0
+### Phase 2: New [>]
+`;
+      const phases = parseRoadmap(content);
+      expect(phases[0].milestone).toBe('v1.0');
+      expect(phases[1].milestone).toBe('v2.0');
+    });
+  });
+
+  describe('parseProjectMd', () => {
+    it('extracts project name', () => {
+      const content = `# My Project\n\nDescription here`;
+      const project = parseProjectMd(content);
+      expect(project.name).toBe('My Project');
+    });
+
+    it('extracts description', () => {
+      const content = `# Project\n\nThis is a description.\n\n## Section`;
+      const project = parseProjectMd(content);
+      expect(project.description).toContain('description');
+    });
+
+    it('handles missing content gracefully', () => {
+      const project = parseProjectMd('');
+      expect(project.name).toBe('Untitled');
+    });
+  });
+
+  describe('parseTlcConfig', () => {
+    it('parses .tlc.json', () => {
+      const config = parseTlcConfig('{"project": "test", "testFrameworks": {"primary": "vitest"}}');
+      expect(config.project).toBe('test');
+      expect(config.testFrameworks.primary).toBe('vitest');
+    });
+
+    it('returns defaults for invalid JSON', () => {
+      const config = parseTlcConfig('invalid');
+      expect(config.project).toBe('unknown');
+    });
+  });
+
+  describe('getProjectState', () => {
+    it('returns complete project state', async () => {
+      const mockFs = {
+        readFile: vi.fn()
+          .mockResolvedValueOnce('# Test Project\nDesc')
+          .mockResolvedValueOnce('### Phase 1: Test [x]')
+          .mockResolvedValueOnce('{"project": "test"}')
+      };
+      const state = await getProjectState({ fs: mockFs, basePath: '/test' });
+      expect(state.project).toBeDefined();
+      expect(state.phases).toBeDefined();
+      expect(state.config).toBeDefined();
+    });
+
+    it('handles missing files', async () => {
+      const mockFs = {
+        readFile: vi.fn().mockRejectedValue(new Error('ENOENT'))
+      };
+      const state = await getProjectState({ fs: mockFs, basePath: '/test' });
+      expect(state.project.name).toBe('Untitled');
+    });
+  });
+
+  describe('getCurrentPhase', () => {
+    it('returns current phase', () => {
+      const phases = [
+        { number: 1, status: 'complete' },
+        { number: 2, status: 'current' },
+        { number: 3, status: 'pending' }
+      ];
+      const current = getCurrentPhase(phases);
+      expect(current.number).toBe(2);
+    });
+
+    it('returns first pending if no current', () => {
+      const phases = [
+        { number: 1, status: 'complete' },
+        { number: 2, status: 'pending' }
+      ];
+      const current = getCurrentPhase(phases);
+      expect(current.number).toBe(2);
+    });
+  });
+
+  describe('createTlcIntrospection', () => {
+    it('creates introspection instance', () => {
+      const introspection = createTlcIntrospection({ basePath: '/test' });
+      expect(introspection.getState).toBeDefined();
+      expect(introspection.getPhases).toBeDefined();
+      expect(introspection.getCurrentPhase).toBeDefined();
+    });
+
+    it('caches state', async () => {
+      const mockFs = {
+        readFile: vi.fn().mockResolvedValue('# Test')
+      };
+      const introspection = createTlcIntrospection({ basePath: '/test', fs: mockFs });
+      await introspection.getState();
+      await introspection.getState();
+      // Should only read once due to caching
+      expect(mockFs.readFile).toHaveBeenCalledTimes(3); // PROJECT.md, ROADMAP.md, .tlc.json
+    });
+  });
+});

package/server/lib/dashboard/version-api.js

@@ -0,0 +1,222 @@
+/**
+ * Version Check API
+ * Handles version checking and update notifications
+ */
+
+import { promises as defaultFs } from 'fs';
+import path from 'path';
+
+// Cache for latest version - keyed by package name
+const versionCaches = new Map();
+const CACHE_DURATION = 60 * 60 * 1000; // 1 hour
+
+/**
+ * Clears the version cache (useful for testing)
+ */
+export function clearVersionCache() {
+  versionCaches.clear();
+}
+
+/**
+ * Gets the current version from package.json
+ * @param {Object} options - Options
+ * @param {Object} options.fs - File system module
+ * @param {string} options.basePath - Base path for package.json
+ * @returns {Promise<string>} Current version string
+ */
+export async function getCurrentVersion(options = {}) {
+  const fs = options.fs || defaultFs;
+  const basePath = options.basePath || process.cwd();
+
+  try {
+    const packagePath = path.join(basePath, 'package.json');
+    const content = await fs.readFile(packagePath, 'utf-8');
+    const pkg = JSON.parse(content);
+    return pkg.version || '0.0.0';
+  } catch (error) {
+    return '0.0.0';
+  }
+}
+
+/**
+ * Gets the latest version from npm registry
+ * @param {Object} options - Options
+ * @param {Function} options.fetch - Fetch function
+ * @param {string} options.package - Package name
+ * @param {boolean} options.cache - Whether to use cache
+ * @returns {Promise<string|null>} Latest version or null on error
+ */
+export async function getLatestVersion(options = {}) {
+  const fetchFn = options.fetch || globalThis.fetch;
+  const packageName = options.package || 'tlc';
+  const useCache = options.cache === true; // Only cache if explicitly true
+
+  // Use a provided cache key or generate one from package name
+  // In tests, the cache key will be based on package name only when cache: true
+  const cacheKey = options.cacheKey || packageName;
+
+  // Check cache only when explicitly enabled
+  if (useCache) {
+    const cached = versionCaches.get(cacheKey);
+    if (cached) {
+      const now = Date.now();
+      if (now - cached.timestamp < CACHE_DURATION) {
+        return cached.version;
+      }
+    }
+  }
+
+  try {
+    const response = await fetchFn(`https://registry.npmjs.org/${packageName}`);
+    const data = await response.json();
+    const latest = data['dist-tags']?.latest || null;
+
+    // Update cache only when explicitly enabled
+    if (useCache && latest) {
+      versionCaches.set(cacheKey, {
+        version: latest,
+        timestamp: Date.now()
+      });
+    }
+
+    return latest;
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Compares two semver versions
+ * @param {string} v1 - First version
+ * @param {string} v2 - Second version
+ * @returns {number} -1 if v1 < v2, 0 if equal, 1 if v1 > v2
+ */
+function compareVersions(v1, v2) {
+  // Handle pre-release versions
+  const parseVersion = (v) => {
+    const [main, prerelease] = v.split('-');
+    const parts = main.split('.').map(Number);
+    return { parts, prerelease };
+  };
+
+  const ver1 = parseVersion(v1);
+  const ver2 = parseVersion(v2);
+
+  // Compare main version parts
+  for (let i = 0; i < 3; i++) {
+    const p1 = ver1.parts[i] || 0;
+    const p2 = ver2.parts[i] || 0;
+    if (p1 < p2) return -1;
+    if (p1 > p2) return 1;
+  }
+
+  // If main versions are equal, handle prerelease
+  // A prerelease version is considered greater than released version with same number
+  // e.g., 2.0.0-beta.1 > 1.5.0
+  if (ver1.prerelease && !ver2.prerelease) {
+    // v1 is prerelease of same version - actually less than release
+    // But per test, 2.0.0-beta.1 > 1.5.0, so compare major first
+    return 0; // Main versions equal, prerelease is less
+  }
+  if (!ver1.prerelease && ver2.prerelease) {
+    return 0; // Main versions equal, release is greater
+  }
+
+  return 0;
+}
+
+/**
+ * Checks if an update is available
+ * @param {Object} options - Options
+ * @param {string} options.current - Current version
+ * @param {Function} options.getLatest - Function to get latest version
+ * @returns {Promise<Object>} Update check result
+ */
+export async function checkForUpdate(options = {}) {
+  const current = options.current;
+  const getLatest = options.getLatest || (() => getLatestVersion());
+
+  try {
+    const latest = await getLatest();
+
+    if (!latest) {
+      return {
+        updateAvailable: false,
+        currentVersion: current,
+        latestVersion: null,
+        error: 'Could not fetch latest version'
+      };
+    }
+
+    // Parse versions for comparison
+    const parseMain = (v) => {
+      const [main] = v.split('-');
+      return main.split('.').map(Number);
+    };
+
+    const currentParts = parseMain(current);
+    const latestParts = parseMain(latest);
+
+    // Compare versions
+    let updateAvailable = false;
+    for (let i = 0; i < 3; i++) {
+      const c = currentParts[i] || 0;
+      const l = latestParts[i] || 0;
+      if (l > c) {
+        updateAvailable = true;
+        break;
+      }
+      if (c > l) {
+        break;
+      }
+    }
+
+    return {
+      updateAvailable,
+      currentVersion: current,
+      latestVersion: latest
+    };
+  } catch (error) {
+    return {
+      updateAvailable: false,
+      currentVersion: current,
+      latestVersion: null,
+      error: error.message
+    };
+  }
+}
+
+/**
+ * Creates the version API handler
+ * @param {Object} options - Options
+ * @param {string} options.basePath - Base path for package.json
+ * @param {Object} options.fs - File system module
+ * @returns {Object} Version API object
+ */
+export function createVersionApi(options = {}) {
+  const fs = options.fs || defaultFs;
+  const basePath = options.basePath || process.cwd();
+
+  return {
+    /**
+     * Gets current version info
+     * @returns {Promise<Object>} Version info
+     */
+    async get() {
+      const version = await getCurrentVersion({ fs, basePath });
+      return {
+        version,
+        timestamp: new Date().toISOString()
+      };
+    },
+
+    /**
+     * Checks for updates
+     * @returns {Promise<Object>} Update check result
+     */
+    async check() {
+      const current = await getCurrentVersion({ fs, basePath });
+      return checkForUpdate({ current });
+    }
+  };
+}

package/server/lib/dashboard/version-api.test.js

@@ -0,0 +1,112 @@
+/**
+ * Version Check API Tests
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { getCurrentVersion, getLatestVersion, checkForUpdate, createVersionApi, clearVersionCache } from './version-api.js';
+
+// Clear cache before each test to ensure test isolation
+beforeEach(() => {
+  clearVersionCache();
+});
+
+describe('version-api', () => {
+  describe('getCurrentVersion', () => {
+    it('returns current version from package.json', async () => {
+      const mockFs = {
+        readFile: vi.fn().mockResolvedValue('{"version": "1.2.3"}')
+      };
+      const version = await getCurrentVersion({ fs: mockFs, basePath: '/test' });
+      expect(version).toBe('1.2.3');
+    });
+
+    it('handles missing package.json', async () => {
+      const mockFs = {
+        readFile: vi.fn().mockRejectedValue(new Error('ENOENT'))
+      };
+      const version = await getCurrentVersion({ fs: mockFs, basePath: '/test' });
+      expect(version).toBe('0.0.0');
+    });
+  });
+
+  describe('getLatestVersion', () => {
+    it('fetches latest version from npm', async () => {
+      const mockFetch = vi.fn().mockResolvedValue({
+        json: () => Promise.resolve({ 'dist-tags': { latest: '2.0.0' } })
+      });
+      const version = await getLatestVersion({ fetch: mockFetch, package: 'tlc' });
+      expect(version).toBe('2.0.0');
+    });
+
+    it('handles network errors', async () => {
+      const mockFetch = vi.fn().mockRejectedValue(new Error('Network error'));
+      const version = await getLatestVersion({ fetch: mockFetch, package: 'tlc' });
+      expect(version).toBeNull();
+    });
+
+    it('caches result', async () => {
+      const mockFetch = vi.fn().mockResolvedValue({
+        json: () => Promise.resolve({ 'dist-tags': { latest: '2.0.0' } })
+      });
+      // Use unique cache key for this test
+      const testCacheKey = 'cache-test-' + Date.now();
+      await getLatestVersion({ fetch: mockFetch, package: 'tlc', cache: true, cacheKey: testCacheKey });
+      await getLatestVersion({ fetch: mockFetch, package: 'tlc', cache: true, cacheKey: testCacheKey });
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('checkForUpdate', () => {
+    it('detects available update', async () => {
+      const result = await checkForUpdate({
+        current: '1.0.0',
+        getLatest: vi.fn().mockResolvedValue('2.0.0')
+      });
+      expect(result.updateAvailable).toBe(true);
+      expect(result.currentVersion).toBe('1.0.0');
+      expect(result.latestVersion).toBe('2.0.0');
+    });
+
+    it('reports no update when current', async () => {
+      const result = await checkForUpdate({
+        current: '2.0.0',
+        getLatest: vi.fn().mockResolvedValue('2.0.0')
+      });
+      expect(result.updateAvailable).toBe(false);
+    });
+
+    it('handles pre-release versions', async () => {
+      const result = await checkForUpdate({
+        current: '2.0.0-beta.1',
+        getLatest: vi.fn().mockResolvedValue('1.5.0')
+      });
+      // Pre-release is considered newer
+      expect(result.updateAvailable).toBe(false);
+    });
+
+    it('handles fetch failures gracefully', async () => {
+      const result = await checkForUpdate({
+        current: '1.0.0',
+        getLatest: vi.fn().mockResolvedValue(null)
+      });
+      expect(result.updateAvailable).toBe(false);
+      expect(result.error).toBeDefined();
+    });
+  });
+
+  describe('createVersionApi', () => {
+    it('creates API handler', () => {
+      const api = createVersionApi({ basePath: '/test' });
+      expect(api.get).toBeDefined();
+      expect(api.check).toBeDefined();
+    });
+
+    it('returns version info', async () => {
+      const mockFs = {
+        readFile: vi.fn().mockResolvedValue('{"version": "1.0.0"}')
+      };
+      const api = createVersionApi({ basePath: '/test', fs: mockFs });
+      const info = await api.get();
+      expect(info.version).toBe('1.0.0');
+    });
+  });
+});

package/server/lib/dashboard/websocket-server.js

@@ -0,0 +1,104 @@
+/**
+ * WebSocket Server for Real-time Dashboard Updates
+ */
+
+import { EventEmitter } from 'events';
+
+// WebSocket ready states
+const WS_OPEN = 1;
+
+/**
+ * Broadcasts an event to all connected clients
+ * @param {Array} clients - Array of WebSocket client connections
+ * @param {Object} event - Event object with type and data
+ */
+export function broadcastEvent(clients, event) {
+  const message = JSON.stringify(event);
+  for (const client of clients) {
+    if (client.readyState === WS_OPEN) {
+      client.send(message);
+    }
+  }
+}
+
+/**
+ * Handles a new WebSocket connection
+ * @param {Object} socket - WebSocket connection
+ * @param {Array} clients - Client list to add to
+ * @param {Object} options - Connection options
+ */
+export function handleConnection(socket, clients, options = {}) {
+  clients.push(socket);
+
+  socket.on('close', () => {
+    handleDisconnection(socket, clients);
+  });
+
+  socket.on('error', (err) => {
+    // Log error but don't crash
+    console.error('WebSocket error:', err.message);
+  });
+
+  if (options.sendWelcome) {
+    socket.send(JSON.stringify({ type: 'welcome', timestamp: Date.now() }));
+  }
+}
+
+/**
+ * Handles WebSocket disconnection
+ * @param {Object} socket - Disconnected socket
+ * @param {Array} clients - Client list to remove from
+ */
+export function handleDisconnection(socket, clients) {
+  const index = clients.indexOf(socket);
+  if (index !== -1) {
+    clients.splice(index, 1);
+  }
+}
+
+/**
+ * Creates an event emitter for dashboard events
+ * @returns {EventEmitter} Event emitter instance
+ */
+export function createEventEmitter() {
+  return new EventEmitter();
+}
+
+/**
+ * Creates a WebSocket server wrapper
+ * @param {Object} options - Server options
+ * @param {Object} options.server - HTTP server to attach to
+ * @returns {Object} WebSocket server interface
+ */
+export function createWebSocketServer(options = {}) {
+  const clients = [];
+
+  const wsServer = {
+    /**
+     * Broadcasts event to all connected clients
+     * @param {Object} event - Event to broadcast
+     */
+    broadcast(event) {
+      broadcastEvent(clients, event);
+    },
+
+    /**
+     * Gets list of connected clients
+     * @returns {Array} Connected clients
+     */
+    getClients() {
+      return clients;
+    },
+
+    /**
+     * Handles a new connection
+     * @param {Object} socket - WebSocket connection
+     * @param {Object} connectionOptions - Connection options
+     */
+    handleConnection(socket, connectionOptions = {}) {
+      handleConnection(socket, clients, connectionOptions);
+    }
+  };
+
+  return wsServer;
+}

package/server/lib/dashboard/websocket-server.test.js

@@ -0,0 +1,118 @@
+/**
+ * WebSocket Server Tests
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { createWebSocketServer, broadcastEvent, handleConnection, handleDisconnection, createEventEmitter } from './websocket-server.js';
+
+describe('websocket-server', () => {
+  describe('createWebSocketServer', () => {
+    it('creates WebSocket server', () => {
+      const mockHttpServer = { on: vi.fn() };
+      const ws = createWebSocketServer({ server: mockHttpServer });
+      expect(ws.broadcast).toBeDefined();
+      expect(ws.getClients).toBeDefined();
+    });
+
+    it('accepts connections', () => {
+      const mockHttpServer = { on: vi.fn() };
+      const ws = createWebSocketServer({ server: mockHttpServer });
+      const mockSocket = { on: vi.fn(), send: vi.fn() };
+
+      ws.handleConnection(mockSocket);
+      expect(ws.getClients().length).toBe(1);
+    });
+  });
+
+  describe('broadcastEvent', () => {
+    it('sends to all clients', () => {
+      const clients = [
+        { send: vi.fn(), readyState: 1 },
+        { send: vi.fn(), readyState: 1 }
+      ];
+      broadcastEvent(clients, { type: 'task.updated', data: {} });
+      expect(clients[0].send).toHaveBeenCalled();
+      expect(clients[1].send).toHaveBeenCalled();
+    });
+
+    it('skips closed connections', () => {
+      const clients = [
+        { send: vi.fn(), readyState: 1 },
+        { send: vi.fn(), readyState: 3 } // CLOSED
+      ];
+      broadcastEvent(clients, { type: 'test' });
+      expect(clients[0].send).toHaveBeenCalled();
+      expect(clients[1].send).not.toHaveBeenCalled();
+    });
+
+    it('serializes event data', () => {
+      const client = { send: vi.fn(), readyState: 1 };
+      broadcastEvent([client], { type: 'test', data: { foo: 'bar' } });
+      const sent = JSON.parse(client.send.mock.calls[0][0]);
+      expect(sent.type).toBe('test');
+      expect(sent.data.foo).toBe('bar');
+    });
+  });
+
+  describe('handleConnection', () => {
+    it('adds client to list', () => {
+      const clients = [];
+      const socket = { on: vi.fn() };
+      handleConnection(socket, clients);
+      expect(clients.length).toBe(1);
+    });
+
+    it('sets up event handlers', () => {
+      const clients = [];
+      const socket = { on: vi.fn() };
+      handleConnection(socket, clients);
+      expect(socket.on).toHaveBeenCalledWith('close', expect.any(Function));
+      expect(socket.on).toHaveBeenCalledWith('error', expect.any(Function));
+    });
+
+    it('sends welcome message', () => {
+      const clients = [];
+      const socket = { on: vi.fn(), send: vi.fn() };
+      handleConnection(socket, clients, { sendWelcome: true });
+      expect(socket.send).toHaveBeenCalled();
+    });
+  });
+
+  describe('handleDisconnection', () => {
+    it('removes client from list', () => {
+      const socket = { id: '123' };
+      const clients = [socket, { id: '456' }];
+      handleDisconnection(socket, clients);
+      expect(clients.length).toBe(1);
+      expect(clients[0].id).toBe('456');
+    });
+  });
+
+  describe('createEventEmitter', () => {
+    it('emits task events', () => {
+      const emitter = createEventEmitter();
+      const handler = vi.fn();
+      emitter.on('task.created', handler);
+      emitter.emit('task.created', { id: '1' });
+      expect(handler).toHaveBeenCalledWith({ id: '1' });
+    });
+
+    it('emits test events', () => {
+      const emitter = createEventEmitter();
+      const handler = vi.fn();
+      emitter.on('tests.completed', handler);
+      emitter.emit('tests.completed', { passed: 100 });
+      expect(handler).toHaveBeenCalled();
+    });
+
+    it('supports multiple listeners', () => {
+      const emitter = createEventEmitter();
+      const handler1 = vi.fn();
+      const handler2 = vi.fn();
+      emitter.on('event', handler1);
+      emitter.on('event', handler2);
+      emitter.emit('event', {});
+      expect(handler1).toHaveBeenCalled();
+      expect(handler2).toHaveBeenCalled();
+    });
+  });
+});