tlc-claude-code 1.8.5 → 2.0.1

package/server/lib/project-scanner.js

@@ -0,0 +1,267 @@
+/**
+ * Project Scanner - Recursively discovers TLC projects within configured root paths
+ *
+ * Scans directory trees looking for:
+ * - TLC projects (.tlc.json present)
+ * - Planning-only projects (.planning/ directory present)
+ * - Candidate projects (package.json + .git/ present, not yet initialized with TLC)
+ *
+ * Returns structured project metadata including phase info from ROADMAP.md.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Directories to skip during recursive scanning
+ */
+const IGNORED_DIRS = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  'coverage',
+  'vendor',
+  '.next',
+  '.nuxt',
+]);
+
+/**
+ * Parse phase information from a ROADMAP.md file
+ * @param {string} roadmapPath - Absolute path to ROADMAP.md
+ * @returns {{ phase: number|null, phaseName: string|null, totalPhases: number, completedPhases: number }}
+ */
+function parseRoadmap(roadmapPath) {
+  const result = {
+    phase: null,
+    phaseName: null,
+    totalPhases: 0,
+    completedPhases: 0,
+  };
+
+  let content;
+  try {
+    content = fs.readFileSync(roadmapPath, 'utf-8');
+  } catch {
+    return result;
+  }
+
+  // Format 1: Heading format — ### Phase N: Name [x] / [ ] / [>]
+  const headingRegex = /###\s+Phase\s+(\d+)(?:\.\d+)?[:\s]+(.+?)\s*\[([x >])\]\s*$/gm;
+  let headingMatch;
+  let foundHeadings = false;
+  let firstIncomplete = null;
+
+  while ((headingMatch = headingRegex.exec(content)) !== null) {
+    foundHeadings = true;
+    result.totalPhases++;
+    const phaseNum = parseInt(headingMatch[1], 10);
+    const phaseName = headingMatch[2].trim();
+    const marker = headingMatch[3];
+
+    if (marker === 'x') {
+      result.completedPhases++;
+    } else if (!firstIncomplete) {
+      firstIncomplete = { phase: phaseNum, phaseName };
+    }
+  }
+
+  if (foundHeadings) {
+    if (firstIncomplete) {
+      result.phase = firstIncomplete.phase;
+      result.phaseName = firstIncomplete.phaseName;
+    }
+    return result;
+  }
+
+  // Format 2: Table format — | N | [Name](link) | status |
+  const tableRegex = /\|\s*(\d+)\s*\|\s*\[([^\]]+)\][^|]*\|\s*(\w+)\s*\|/g;
+  let tableMatch;
+
+  while ((tableMatch = tableRegex.exec(content)) !== null) {
+    result.totalPhases++;
+    const phaseNum = parseInt(tableMatch[1], 10);
+    const phaseName = tableMatch[2].trim();
+    const status = tableMatch[3].trim().toLowerCase();
+    const completed = status === 'complete' || status === 'done' || status === 'verified';
+
+    if (completed) {
+      result.completedPhases++;
+    } else if (!firstIncomplete) {
+      firstIncomplete = { phase: phaseNum, phaseName };
+    }
+  }
+
+  if (firstIncomplete) {
+    result.phase = firstIncomplete.phase;
+    result.phaseName = firstIncomplete.phaseName;
+  }
+
+  return result;
+}
+
+/**
+ * Read project metadata from a project directory
+ * @param {string} projectDir - Absolute path to the project directory
+ * @returns {object} Project metadata
+ */
+function readProjectMetadata(projectDir) {
+  const hasTlc = fs.existsSync(path.join(projectDir, '.tlc.json'));
+  const hasPlanning = fs.existsSync(path.join(projectDir, '.planning'));
+
+  // Read name and version from package.json if present
+  let name = path.basename(projectDir);
+  let version = null;
+
+  const pkgPath = path.join(projectDir, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+      if (pkg.name) {
+        name = pkg.name;
+      }
+      if (pkg.version) {
+        version = pkg.version;
+      }
+    } catch {
+      // Ignore malformed package.json
+    }
+  }
+
+  // Parse phase info from ROADMAP.md if .planning exists
+  let phaseInfo = { phase: null, phaseName: null, totalPhases: 0, completedPhases: 0 };
+  if (hasPlanning) {
+    const roadmapPath = path.join(projectDir, '.planning', 'ROADMAP.md');
+    if (fs.existsSync(roadmapPath)) {
+      phaseInfo = parseRoadmap(roadmapPath);
+    }
+  }
+
+  return {
+    name,
+    path: projectDir,
+    hasTlc,
+    hasPlanning,
+    version,
+    phase: phaseInfo.phase,
+    phaseName: phaseInfo.phaseName,
+    totalPhases: phaseInfo.totalPhases,
+    completedPhases: phaseInfo.completedPhases,
+  };
+}
+
+/**
+ * ProjectScanner - Recursively discovers TLC projects within configured root paths
+ */
+class ProjectScanner {
+  /**
+   * @param {object} [options]
+   * @param {number} [options.scanDepth=5] - Maximum recursion depth
+   * @param {number} [options.cacheTTL=60000] - Cache time-to-live in milliseconds
+   */
+  constructor(options = {}) {
+    this.scanDepth = options.scanDepth || 5;
+    this.cacheTTL = options.cacheTTL || 60000;
+    this._cache = null;
+    this._cacheTime = 0;
+  }
+
+  /**
+   * Scan root directories for TLC projects
+   * @param {string[]} roots - Array of root directory paths to scan
+   * @param {object} [options]
+   * @param {boolean} [options.force=false] - Force re-scan bypassing cache
+   * @param {function} [options.onProgress] - Progress callback receiving discovered count
+   * @returns {object[]} Array of project metadata objects, sorted by name
+   */
+  scan(roots, options = {}) {
+    const { force = false, onProgress } = options;
+
+    // Check cache
+    if (!force && this._cache !== null) {
+      const age = Date.now() - this._cacheTime;
+      if (age < this.cacheTTL) {
+        return this._cache;
+      }
+    }
+
+    const projectsByPath = new Map();
+
+    for (const root of roots) {
+      // Check that root exists
+      if (!fs.existsSync(root)) {
+        console.warn(`ProjectScanner: root path does not exist: ${root}`);
+        continue;
+      }
+
+      this._scanDir(root, 0, projectsByPath, onProgress);
+    }
+
+    const projects = Array.from(projectsByPath.values());
+    projects.sort((a, b) => a.name.localeCompare(b.name));
+
+    // Update cache
+    this._cache = projects;
+    this._cacheTime = Date.now();
+
+    return projects;
+  }
+
+  /**
+   * Recursively scan a directory for projects
+   * @param {string} dir - Directory to scan
+   * @param {number} depth - Current recursion depth
+   * @param {Map} projectsByPath - Accumulated projects (keyed by absolute path for dedup)
+   * @param {function} [onProgress] - Progress callback
+   * @private
+   */
+  _scanDir(dir, depth, projectsByPath, onProgress) {
+    if (depth > this.scanDepth) {
+      return;
+    }
+
+    // Check if this directory IS a project
+    const hasTlc = fs.existsSync(path.join(dir, '.tlc.json'));
+    const hasPlanning = fs.existsSync(path.join(dir, '.planning'));
+    const hasPackageJson = fs.existsSync(path.join(dir, 'package.json'));
+    const hasGit = fs.existsSync(path.join(dir, '.git'));
+
+    const isProject = hasTlc || hasPlanning || (hasPackageJson && hasGit);
+
+    if (isProject && !projectsByPath.has(dir)) {
+      const metadata = readProjectMetadata(dir);
+      projectsByPath.set(dir, metadata);
+
+      if (typeof onProgress === 'function') {
+        onProgress(projectsByPath.size);
+      }
+    }
+
+    // Recurse into subdirectories
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (err) {
+      if (err.code === 'EACCES' || err.code === 'EPERM') {
+        console.warn(`ProjectScanner: permission denied reading directory: ${dir}`);
+        return;
+      }
+      throw err;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+
+      if (IGNORED_DIRS.has(entry.name)) {
+        continue;
+      }
+
+      const childPath = path.join(dir, entry.name);
+      this._scanDir(childPath, depth + 1, projectsByPath, onProgress);
+    }
+  }
+}
+
+module.exports = { ProjectScanner };

package/server/lib/project-scanner.test.js

@@ -0,0 +1,389 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+const { ProjectScanner } = await import('./project-scanner.js');
+
+describe('ProjectScanner', () => {
+  let tempDir;
+  let scanner;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'project-scanner-test-'));
+    scanner = new ProjectScanner();
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  /**
+   * Helper: create a minimal TLC project directory structure
+   */
+  function createTlcProject(parentDir, name, options = {}) {
+    const projectDir = path.join(parentDir, name);
+    fs.mkdirSync(projectDir, { recursive: true });
+
+    // .tlc.json
+    if (options.tlcJson !== false) {
+      fs.writeFileSync(
+        path.join(projectDir, '.tlc.json'),
+        JSON.stringify(options.tlcJson || { name })
+      );
+    }
+
+    // package.json
+    if (options.packageJson !== false) {
+      const pkg = options.packageJson || { name, version: '1.0.0' };
+      fs.writeFileSync(
+        path.join(projectDir, 'package.json'),
+        JSON.stringify(pkg)
+      );
+    }
+
+    // .planning directory
+    if (options.planning !== false) {
+      fs.mkdirSync(path.join(projectDir, '.planning'), { recursive: true });
+    }
+
+    // .git directory
+    if (options.git !== false) {
+      fs.mkdirSync(path.join(projectDir, '.git'), { recursive: true });
+    }
+
+    // ROADMAP.md
+    if (options.roadmap) {
+      fs.writeFileSync(
+        path.join(projectDir, '.planning', 'ROADMAP.md'),
+        options.roadmap
+      );
+    }
+
+    return projectDir;
+  }
+
+  // Test 1: Discovers project with .tlc.json
+  it('discovers project with .tlc.json', () => {
+    createTlcProject(tempDir, 'alpha-project');
+
+    const results = scanner.scan([tempDir]);
+
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('alpha-project');
+    expect(results[0].hasTlc).toBe(true);
+  });
+
+  // Test 2: Discovers project with .planning/ directory (no .tlc.json)
+  it('discovers project with .planning/ directory (no .tlc.json)', () => {
+    createTlcProject(tempDir, 'planning-only', {
+      tlcJson: false,
+      packageJson: { name: 'planning-only', version: '2.0.0' },
+    });
+
+    const results = scanner.scan([tempDir]);
+
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('planning-only');
+    expect(results[0].hasTlc).toBe(false);
+    expect(results[0].hasPlanning).toBe(true);
+  });
+
+  // Test 3: Discovers candidate project with package.json + .git/ (marked hasTlc: false)
+  it('discovers candidate project with package.json + .git/ (marked hasTlc: false)', () => {
+    createTlcProject(tempDir, 'candidate-project', {
+      tlcJson: false,
+      planning: false,
+      packageJson: { name: 'candidate-project', version: '0.1.0' },
+      git: true,
+    });
+
+    const results = scanner.scan([tempDir]);
+
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('candidate-project');
+    expect(results[0].hasTlc).toBe(false);
+    expect(results[0].hasPlanning).toBe(false);
+    expect(results[0].version).toBe('0.1.0');
+  });
+
+  // Test 4: Skips node_modules directories
+  it('skips node_modules directories', () => {
+    // Create a project inside node_modules — should be ignored
+    const nmDir = path.join(tempDir, 'node_modules');
+    fs.mkdirSync(nmDir, { recursive: true });
+    createTlcProject(nmDir, 'hidden-project');
+
+    // Create a valid project at the top level
+    createTlcProject(tempDir, 'visible-project');
+
+    const results = scanner.scan([tempDir]);
+
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('visible-project');
+  });
+
+  // Test 5: Skips all ignored directories (dist, build, coverage, etc.)
+  it('skips all ignored directories (dist, build, coverage, vendor, .next, .nuxt)', () => {
+    const ignoreDirs = ['dist', 'build', 'coverage', 'vendor', '.next', '.nuxt'];
+
+    for (const dir of ignoreDirs) {
+      const ignored = path.join(tempDir, dir);
+      fs.mkdirSync(ignored, { recursive: true });
+      createTlcProject(ignored, `project-in-${dir}`);
+    }
+
+    // One valid project
+    createTlcProject(tempDir, 'valid-project');
+
+    const results = scanner.scan([tempDir]);
+
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('valid-project');
+  });
+
+  // Test 6: Respects depth limit (default 5)
+  it('respects depth limit (default 5)', () => {
+    // Create a project nested 4 levels deep — within default depth of 5
+    let nested = tempDir;
+    for (let i = 0; i < 4; i++) {
+      nested = path.join(nested, `level${i}`);
+      fs.mkdirSync(nested, { recursive: true });
+    }
+    createTlcProject(nested, 'deep-project');
+
+    const results = scanner.scan([tempDir]);
+
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('deep-project');
+  });
+
+  // Test 7: Depth 1 only scans immediate children
+  it('depth 1 only scans immediate children', () => {
+    const shallowScanner = new ProjectScanner({ scanDepth: 1 });
+
+    // Immediate child — should be found
+    createTlcProject(tempDir, 'shallow-project');
+
+    // Nested one level deeper — should NOT be found
+    const subDir = path.join(tempDir, 'subdir');
+    fs.mkdirSync(subDir, { recursive: true });
+    createTlcProject(subDir, 'nested-project');
+
+    const results = shallowScanner.scan([tempDir]);
+
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('shallow-project');
+  });
+
+  // Test 8: Returns empty array for empty root directory
+  it('returns empty array for empty root directory', () => {
+    const results = scanner.scan([tempDir]);
+
+    expect(results).toEqual([]);
+  });
+
+  // Test 9: Handles multiple root paths
+  it('handles multiple root paths', () => {
+    const root1 = fs.mkdtempSync(path.join(os.tmpdir(), 'root1-'));
+    const root2 = fs.mkdtempSync(path.join(os.tmpdir(), 'root2-'));
+
+    try {
+      createTlcProject(root1, 'project-a');
+      createTlcProject(root2, 'project-b');
+
+      const results = scanner.scan([root1, root2]);
+
+      expect(results).toHaveLength(2);
+      const names = results.map(r => r.name);
+      expect(names).toContain('project-a');
+      expect(names).toContain('project-b');
+    } finally {
+      fs.rmSync(root1, { recursive: true, force: true });
+      fs.rmSync(root2, { recursive: true, force: true });
+    }
+  });
+
+  // Test 10: Deduplicates projects found in overlapping roots
+  it('deduplicates projects found in overlapping roots', () => {
+    createTlcProject(tempDir, 'unique-project');
+
+    // Pass the same root twice
+    const results = scanner.scan([tempDir, tempDir]);
+
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('unique-project');
+  });
+
+  // Test 11: Caches results on repeated calls within TTL
+  it('caches results on repeated calls within TTL', () => {
+    createTlcProject(tempDir, 'cached-project');
+
+    const results1 = scanner.scan([tempDir]);
+    expect(results1).toHaveLength(1);
+
+    // Remove the project on disk
+    fs.rmSync(path.join(tempDir, 'cached-project'), { recursive: true, force: true });
+
+    // Second scan within TTL should return cached results
+    const results2 = scanner.scan([tempDir]);
+    expect(results2).toHaveLength(1);
+    expect(results2[0].name).toBe('cached-project');
+  });
+
+  // Test 12: Force re-scan bypasses cache
+  it('force re-scan bypasses cache', () => {
+    createTlcProject(tempDir, 'cached-project');
+
+    const results1 = scanner.scan([tempDir]);
+    expect(results1).toHaveLength(1);
+
+    // Remove the project on disk
+    fs.rmSync(path.join(tempDir, 'cached-project'), { recursive: true, force: true });
+
+    // Force re-scan should see the project is gone
+    const results2 = scanner.scan([tempDir], { force: true });
+    expect(results2).toHaveLength(0);
+  });
+
+  // Test 13: Handles permission denied errors gracefully
+  it('handles permission denied errors gracefully', () => {
+    createTlcProject(tempDir, 'accessible-project');
+
+    // Create a directory that can't be read
+    const restrictedDir = path.join(tempDir, 'restricted');
+    fs.mkdirSync(restrictedDir, { recursive: true });
+    fs.chmodSync(restrictedDir, 0o000);
+
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    try {
+      const results = scanner.scan([tempDir]);
+
+      // Should still find the accessible project
+      expect(results).toHaveLength(1);
+      expect(results[0].name).toBe('accessible-project');
+
+      // Should have logged a warning about the restricted dir
+      expect(warnSpy).toHaveBeenCalled();
+    } finally {
+      warnSpy.mockRestore();
+      // Restore permissions for cleanup
+      fs.chmodSync(restrictedDir, 0o755);
+    }
+  });
+
+  // Test 14: Returns project metadata (name, version from package.json)
+  it('returns project metadata (name, version from package.json)', () => {
+    createTlcProject(tempDir, 'meta-project', {
+      packageJson: { name: 'meta-project', version: '3.2.1' },
+    });
+
+    const results = scanner.scan([tempDir]);
+
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('meta-project');
+    expect(results[0].path).toBe(path.join(tempDir, 'meta-project'));
+    expect(results[0].version).toBe('3.2.1');
+    expect(results[0].hasTlc).toBe(true);
+    expect(results[0].hasPlanning).toBe(true);
+  });
+
+  // Test 15: Reads phase info from ROADMAP.md (heading format)
+  it('reads phase info from ROADMAP.md (heading format)', () => {
+    const roadmap = [
+      '# Roadmap',
+      '',
+      '### Phase 1: Core Infrastructure [x]',
+      '',
+      '### Phase 2: Test Quality [x]',
+      '',
+      '### Phase 3: Dev Server [>]',
+      '',
+      '### Phase 4: API Docs [ ]',
+      '',
+      '### Phase 5: CI/CD [ ]',
+    ].join('\n');
+
+    createTlcProject(tempDir, 'roadmap-heading-project', { roadmap });
+
+    const results = scanner.scan([tempDir]);
+
+    expect(results).toHaveLength(1);
+    expect(results[0].phase).toBe(3);
+    expect(results[0].phaseName).toBe('Dev Server');
+    expect(results[0].totalPhases).toBe(5);
+    expect(results[0].completedPhases).toBe(2);
+  });
+
+  // Test 16: Reads phase info from ROADMAP.md (table format)
+  it('reads phase info from ROADMAP.md (table format)', () => {
+    const roadmap = [
+      '# Roadmap',
+      '',
+      '| # | Phase | Status |',
+      '|---|-------|--------|',
+      '| 1 | [Auth](./phases/1-PLAN.md) | complete |',
+      '| 2 | [API](./phases/2-PLAN.md) | done |',
+      '| 3 | [UI](./phases/3-PLAN.md) | active |',
+      '| 4 | [Deploy](./phases/4-PLAN.md) | pending |',
+    ].join('\n');
+
+    createTlcProject(tempDir, 'roadmap-table-project', { roadmap });
+
+    const results = scanner.scan([tempDir]);
+
+    expect(results).toHaveLength(1);
+    expect(results[0].phase).toBe(3);
+    expect(results[0].phaseName).toBe('UI');
+    expect(results[0].totalPhases).toBe(4);
+    expect(results[0].completedPhases).toBe(2);
+  });
+
+  // Test 17: Projects sorted alphabetically by name
+  it('projects sorted alphabetically by name', () => {
+    createTlcProject(tempDir, 'zulu-project');
+    createTlcProject(tempDir, 'alpha-project');
+    createTlcProject(tempDir, 'mike-project');
+
+    const results = scanner.scan([tempDir]);
+
+    expect(results).toHaveLength(3);
+    expect(results[0].name).toBe('alpha-project');
+    expect(results[1].name).toBe('mike-project');
+    expect(results[2].name).toBe('zulu-project');
+  });
+
+  // Test 18: Handles root path that doesn't exist (returns empty, logs warning)
+  it('handles root path that does not exist (returns empty, logs warning)', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    try {
+      const results = scanner.scan(['/tmp/nonexistent-root-path-xyz-123']);
+
+      expect(results).toEqual([]);
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('/tmp/nonexistent-root-path-xyz-123')
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  // Test 19: Scan progress callback reports discovered count
+  it('scan progress callback reports discovered count', () => {
+    createTlcProject(tempDir, 'project-one');
+    createTlcProject(tempDir, 'project-two');
+
+    const progressCounts = [];
+    const onProgress = (count) => progressCounts.push(count);
+
+    const results = scanner.scan([tempDir], { onProgress });
+
+    expect(results).toHaveLength(2);
+    // Progress callback should have been called at least once
+    expect(progressCounts.length).toBeGreaterThanOrEqual(1);
+    // The last reported count should match total found
+    expect(progressCounts[progressCounts.length - 1]).toBe(2);
+  });
+});