tlc-claude-code 1.8.4 → 2.0.1

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

@@ -0,0 +1,470 @@
+/**
+ * @file project-status.test.js
+ * @description Tests for the Project Status module (Phase 75, Task 1).
+ *
+ * Tests the factory function `createProjectStatus(deps)` which accepts injected
+ * dependencies (fs, execSync) and returns `{ getFullStatus(projectPath) }`.
+ *
+ * The module parses a project's `.planning/ROADMAP.md` to extract a full roadmap
+ * with milestones, phases (with goals, deliverables, status), reads per-phase
+ * PLAN.md for task counts, TESTS.md for test counts, VERIFIED.md for verification
+ * status, and extracts recent git commits and project info.
+ *
+ * All filesystem and git operations are injected as dependencies so tests can
+ * run entirely against mock data with no real filesystem access.
+ *
+ * TDD: RED phase — these tests are written BEFORE the implementation.
+ */
+import { describe, it, beforeEach, expect, vi } from 'vitest';
+import { createProjectStatus } from './project-status.js';
+
+// ---------------------------------------------------------------------------
+// Mock factories
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a mock `fs` dependency backed by an in-memory file map.
+ * Keys are absolute file paths, values are file contents (strings).
+ * @param {Record<string, string>} files - Map of path -> content
+ * @returns {{ existsSync: vi.fn, readFileSync: vi.fn, readdirSync: vi.fn }}
+ */
+function createMockFs(files = {}) {
+  return {
+    existsSync: vi.fn((p) => p in files),
+    readFileSync: vi.fn((p) => {
+      if (p in files) return files[p];
+      throw new Error(`ENOENT: no such file or directory, open '${p}'`);
+    }),
+    readdirSync: vi.fn((p) => {
+      // Return filenames that are direct children of the directory path
+      return Object.keys(files)
+        .filter((f) => f.startsWith(p + '/') && !f.slice(p.length + 1).includes('/'))
+        .map((f) => f.slice(p.length + 1));
+    }),
+  };
+}
+
+/**
+ * Creates a mock `execSync` that returns a configurable string for git log.
+ * @param {string} output - The stdout to return
+ * @returns {vi.fn}
+ */
+function createMockExecSync(output = '') {
+  return vi.fn(() => output);
+}
+
+// ---------------------------------------------------------------------------
+// Shared mock content
+// ---------------------------------------------------------------------------
+
+const MOCK_ROADMAP = `# TLC Roadmap - v1.0
+
+## Milestone: v1.0 - Team Collaboration Release
+
+### Phase 1: Core Infrastructure [x]
+
+**Goal:** Establish TLC as source of truth for planning.
+
+**Deliverables:**
+- [x] CLAUDE.md enforcement
+- [x] Multi-user task claiming
+
+---
+
+### Phase 2: Test Quality [x] ✓ COMPLETE
+
+**Goal:** Improve test quality metrics.
+
+**Deliverables:**
+- [x] Test quality scoring
+- [x] Auto-fix on failure
+
+---
+
+### Phase 3: Dev Server [>]
+
+**Goal:** Unified development environment.
+
+**Deliverables:**
+- [x] Auto-detect project type
+- [ ] Docker-compose generation
+
+---
+
+## Milestone: v2.0 - Standalone Release
+
+### Phase 4: LLM Router [ ]
+
+**Goal:** Multi-model support.
+
+**Deliverables:**
+- [ ] Model routing
+- [ ] Provider config
+`;
+
+const MOCK_PLAN = `# Phase 1: Core Infrastructure - Plan
+
+## Tasks
+
+### Task 1: CLAUDE.md [x]
+
+### Task 2: Multi-user [x]
+
+### Task 3: Bug tracking [ ]
+`;
+
+const MOCK_TESTS = `# Phase 1 Tests
+
+## Test Files
+
+| File | Tests | Status |
+|------|-------|--------|
+| lib/core.test.js | 10 | Passing |
+| lib/user.test.js | 5 | Passing |
+| **Total** | **15** | **All Passing** |
+`;
+
+const MOCK_PACKAGE_JSON = JSON.stringify({
+  name: 'test-project',
+  version: '2.1.0',
+  description: 'A test project for TLC',
+});
+
+const MOCK_PROJECT_MD = `# Test Project
+
+This is the project description paragraph that should be extracted.
+
+## Architecture
+
+Some architecture notes.
+`;
+
+const MOCK_GIT_LOG = `abc1234|feat: add roadmap parser|2026-02-09|Jurgen
+def5678|fix: correct milestone grouping|2026-02-08|Alice
+ghi9012|test: add project-status tests|2026-02-07|Bob`;
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('project-status', () => {
+  let mockFs;
+  let mockExecSync;
+  let projectStatus;
+
+  /**
+   * Builds a full file map for a project at the given path.
+   * Includes ROADMAP.md, a Phase 1 PLAN, TESTS, and VERIFIED file,
+   * plus package.json and PROJECT.md.
+   * @param {string} projectPath - Absolute path to the project root
+   * @returns {Record<string, string>} File map
+   */
+  function buildFullFileMap(projectPath) {
+    return {
+      [`${projectPath}/package.json`]: MOCK_PACKAGE_JSON,
+      [`${projectPath}/PROJECT.md`]: MOCK_PROJECT_MD,
+      [`${projectPath}/.planning/ROADMAP.md`]: MOCK_ROADMAP,
+      [`${projectPath}/.planning/phases`]: '', // directory marker
+      [`${projectPath}/.planning/phases/1-PLAN.md`]: MOCK_PLAN,
+      [`${projectPath}/.planning/phases/1-TESTS.md`]: MOCK_TESTS,
+      [`${projectPath}/.planning/phases/1-VERIFIED.md`]: '# Verified\nPhase 1 verified.',
+    };
+  }
+
+  beforeEach(() => {
+    const files = buildFullFileMap('/project');
+    mockFs = createMockFs(files);
+    mockExecSync = createMockExecSync(MOCK_GIT_LOG);
+    projectStatus = createProjectStatus({ fs: mockFs, execSync: mockExecSync });
+  });
+
+  it('parses full roadmap with milestones grouping phases', () => {
+    const result = projectStatus.getFullStatus('/project');
+
+    expect(result.milestones).toBeDefined();
+    expect(Array.isArray(result.milestones)).toBe(true);
+    expect(result.milestones).toHaveLength(2);
+
+    // First milestone has 3 phases
+    expect(result.milestones[0].name).toBe('v1.0 - Team Collaboration Release');
+    expect(result.milestones[0].phases).toHaveLength(3);
+
+    // Second milestone has 1 phase
+    expect(result.milestones[1].name).toBe('v2.0 - Standalone Release');
+    expect(result.milestones[1].phases).toHaveLength(1);
+
+    // Total phases
+    expect(result.totalPhases).toBe(4);
+  });
+
+  it('extracts phase goals from ROADMAP.md', () => {
+    const result = projectStatus.getFullStatus('/project');
+
+    const phase1 = result.milestones[0].phases[0];
+    expect(phase1.goal).toBe('Establish TLC as source of truth for planning.');
+
+    const phase2 = result.milestones[0].phases[1];
+    expect(phase2.goal).toBe('Improve test quality metrics.');
+
+    const phase3 = result.milestones[0].phases[2];
+    expect(phase3.goal).toBe('Unified development environment.');
+
+    const phase4 = result.milestones[1].phases[0];
+    expect(phase4.goal).toBe('Multi-model support.');
+  });
+
+  it('extracts phase deliverables as arrays', () => {
+    const result = projectStatus.getFullStatus('/project');
+
+    const phase1 = result.milestones[0].phases[0];
+    expect(phase1.deliverables).toHaveLength(2);
+    expect(phase1.deliverables[0]).toEqual({ text: 'CLAUDE.md enforcement', done: true });
+    expect(phase1.deliverables[1]).toEqual({ text: 'Multi-user task claiming', done: true });
+
+    const phase3 = result.milestones[0].phases[2];
+    expect(phase3.deliverables).toHaveLength(2);
+    expect(phase3.deliverables[0]).toEqual({ text: 'Auto-detect project type', done: true });
+    expect(phase3.deliverables[1]).toEqual({ text: 'Docker-compose generation', done: false });
+
+    const phase4 = result.milestones[1].phases[0];
+    expect(phase4.deliverables).toHaveLength(2);
+    expect(phase4.deliverables[0]).toEqual({ text: 'Model routing', done: false });
+    expect(phase4.deliverables[1]).toEqual({ text: 'Provider config', done: false });
+  });
+
+  it('counts tasks from PLAN.md files', () => {
+    const result = projectStatus.getFullStatus('/project');
+
+    // Phase 1 has a PLAN.md with 3 tasks, 2 completed
+    const phase1 = result.milestones[0].phases[0];
+    expect(phase1.taskCount).toBe(3);
+    expect(phase1.completedTaskCount).toBe(2);
+  });
+
+  it('parses test counts from TESTS.md', () => {
+    const result = projectStatus.getFullStatus('/project');
+
+    // Phase 1 has a TESTS.md with 2 test files, 15 total tests
+    const phase1 = result.milestones[0].phases[0];
+    expect(phase1.hasTests).toBe(true);
+    expect(phase1.testFileCount).toBe(2);
+    expect(phase1.testCount).toBe(15);
+
+    // Test summary should aggregate
+    expect(result.testSummary).toBeDefined();
+    expect(result.testSummary.totalFiles).toBe(2);
+    expect(result.testSummary.totalTests).toBe(15);
+  });
+
+  it('detects verified phases from VERIFIED.md', () => {
+    const result = projectStatus.getFullStatus('/project');
+
+    // Phase 1 has a VERIFIED.md
+    const phase1 = result.milestones[0].phases[0];
+    expect(phase1.verified).toBe(true);
+
+    // Phase 2 does NOT have a VERIFIED.md
+    const phase2 = result.milestones[0].phases[1];
+    expect(phase2.verified).toBe(false);
+  });
+
+  it('extracts recent commits via git log', () => {
+    const result = projectStatus.getFullStatus('/project');
+
+    expect(result.recentCommits).toBeDefined();
+    expect(Array.isArray(result.recentCommits)).toBe(true);
+    expect(result.recentCommits).toHaveLength(3);
+
+    expect(result.recentCommits[0]).toEqual({
+      hash: 'abc1234',
+      message: 'feat: add roadmap parser',
+      date: '2026-02-09',
+      author: 'Jurgen',
+    });
+    expect(result.recentCommits[1]).toEqual({
+      hash: 'def5678',
+      message: 'fix: correct milestone grouping',
+      date: '2026-02-08',
+      author: 'Alice',
+    });
+    expect(result.recentCommits[2]).toEqual({
+      hash: 'ghi9012',
+      message: 'test: add project-status tests',
+      date: '2026-02-07',
+      author: 'Bob',
+    });
+
+    // Verify execSync was called with a git log command
+    expect(mockExecSync).toHaveBeenCalled();
+    const gitCall = mockExecSync.mock.calls[0][0];
+    expect(gitCall).toContain('git log');
+  });
+
+  it('reads project info from package.json and PROJECT.md', () => {
+    const result = projectStatus.getFullStatus('/project');
+
+    expect(result.projectInfo).toBeDefined();
+    expect(result.projectInfo.name).toBe('test-project');
+    expect(result.projectInfo.version).toBe('2.1.0');
+    expect(result.projectInfo.description).toContain('project description paragraph');
+  });
+
+  it('graceful fallback for missing .planning directory', () => {
+    // Build a project with no .planning directory at all
+    const files = {
+      '/empty-project/package.json': JSON.stringify({ name: 'empty', version: '0.1.0' }),
+    };
+    const fs = createMockFs(files);
+    const exec = createMockExecSync('');
+    const status = createProjectStatus({ fs, execSync: exec });
+
+    const result = status.getFullStatus('/empty-project');
+
+    expect(result).toBeDefined();
+    expect(result.milestones).toEqual([]);
+    expect(result.totalPhases).toBe(0);
+    expect(result.completedPhases).toBe(0);
+    expect(result.testSummary).toEqual(expect.objectContaining({
+      totalFiles: 0,
+      totalTests: 0,
+    }));
+    expect(result.projectInfo.name).toBe('empty');
+  });
+
+  it('handles heading format with status suffixes', () => {
+    const result = projectStatus.getFullStatus('/project');
+
+    // Phase 1: [x] -> done
+    const phase1 = result.milestones[0].phases[0];
+    expect(phase1.number).toBe(1);
+    expect(phase1.name).toBe('Core Infrastructure');
+    expect(phase1.status).toBe('done');
+
+    // Phase 2: [x] ✓ COMPLETE -> done
+    const phase2 = result.milestones[0].phases[1];
+    expect(phase2.number).toBe(2);
+    expect(phase2.name).toBe('Test Quality');
+    expect(phase2.status).toBe('done');
+
+    // Phase 3: [>] -> in_progress
+    const phase3 = result.milestones[0].phases[2];
+    expect(phase3.number).toBe(3);
+    expect(phase3.name).toBe('Dev Server');
+    expect(phase3.status).toBe('in_progress');
+
+    // Phase 4: [ ] -> pending
+    const phase4 = result.milestones[1].phases[0];
+    expect(phase4.number).toBe(4);
+    expect(phase4.name).toBe('LLM Router');
+    expect(phase4.status).toBe('pending');
+  });
+
+  it('returns zero phases for empty roadmap', () => {
+    const files = {
+      '/minimal/package.json': JSON.stringify({ name: 'minimal', version: '1.0.0' }),
+      '/minimal/.planning/ROADMAP.md': '# Roadmap\n\nNothing planned yet.\n',
+      '/minimal/.planning/phases': '',
+    };
+    const fs = createMockFs(files);
+    const exec = createMockExecSync('');
+    const status = createProjectStatus({ fs, execSync: exec });
+
+    const result = status.getFullStatus('/minimal');
+
+    expect(result.totalPhases).toBe(0);
+    expect(result.completedPhases).toBe(0);
+    expect(result.milestones).toEqual([]);
+  });
+
+  it('falls back to deliverable counts when no PLAN.md exists', () => {
+    // Phases 2, 3, 4 have no PLAN.md but have deliverables in ROADMAP.md
+    const result = projectStatus.getFullStatus('/project');
+
+    // Phase 2: 2 deliverables, both [x] → taskCount=2, completedTaskCount=2
+    const phase2 = result.milestones[0].phases[1];
+    expect(phase2.taskCount).toBe(2);
+    expect(phase2.completedTaskCount).toBe(2);
+
+    // Phase 3: 2 deliverables, 1 [x] and 1 [ ] → taskCount=2, completedTaskCount=1
+    const phase3 = result.milestones[0].phases[2];
+    expect(phase3.taskCount).toBe(2);
+    expect(phase3.completedTaskCount).toBe(1);
+
+    // Phase 4: 2 deliverables, both [ ] → taskCount=2, completedTaskCount=0
+    const phase4 = result.milestones[1].phases[0];
+    expect(phase4.taskCount).toBe(2);
+    expect(phase4.completedTaskCount).toBe(0);
+  });
+
+  it('parses checklist items without Deliverables header', () => {
+    // Kasha-style ROADMAP: - [x] items directly under phase, no **Deliverables:** header
+    const roadmap = `# Roadmap
+
+## Milestone: v1.0
+
+### Phase 1: Foundation [x]
+- **Discussion:** assessment.md
+- **Plan:** plan.md
+- [x] 1.1 Update framework
+- [x] 1.2 Standardize Node.js
+- [x] 1.3 Standardize TypeScript
+
+### Phase 2: Backend [>]
+- [x] 2.1 Migration Batch 1
+- [x] 2.2 Migration Batch 2
+- [ ] 2.3 TypeORM standardization
+- [ ] 2.4 Gateway migration
+`;
+
+    const files = {
+      '/kasha/package.json': JSON.stringify({ name: 'kasha', version: '1.0.0' }),
+      '/kasha/.planning/ROADMAP.md': roadmap,
+    };
+    const fs = createMockFs(files);
+    const exec = createMockExecSync('');
+    const status = createProjectStatus({ fs, execSync: exec });
+
+    const result = status.getFullStatus('/kasha');
+
+    // Phase 1: 3 checklist items, all done
+    const phase1 = result.milestones[0].phases[0];
+    expect(phase1.deliverables).toHaveLength(3);
+    expect(phase1.taskCount).toBe(3);
+    expect(phase1.completedTaskCount).toBe(3);
+
+    // Phase 2: 4 checklist items, 2 done
+    const phase2 = result.milestones[0].phases[1];
+    expect(phase2.deliverables).toHaveLength(4);
+    expect(phase2.taskCount).toBe(4);
+    expect(phase2.completedTaskCount).toBe(2);
+  });
+
+  it('prefers PLAN.md task counts over deliverable counts', () => {
+    // Phase 1 has both a PLAN.md (3 tasks, 2 done) and deliverables (2 items, 2 done)
+    // PLAN.md should take precedence
+    const result = projectStatus.getFullStatus('/project');
+
+    const phase1 = result.milestones[0].phases[0];
+    expect(phase1.taskCount).toBe(3);
+    expect(phase1.completedTaskCount).toBe(2);
+  });
+
+  it('milestone boundary correctly separates phases', () => {
+    const result = projectStatus.getFullStatus('/project');
+
+    // v1.0 milestone should have phases 1, 2, 3
+    const v1Phases = result.milestones[0].phases;
+    expect(v1Phases.map((p) => p.number)).toEqual([1, 2, 3]);
+
+    // v2.0 milestone should have phase 4 only
+    const v2Phases = result.milestones[1].phases;
+    expect(v2Phases.map((p) => p.number)).toEqual([4]);
+
+    // Phases should not leak across milestone boundaries
+    const allPhaseNumbers = result.milestones.flatMap((m) => m.phases.map((p) => p.number));
+    expect(allPhaseNumbers).toEqual([1, 2, 3, 4]);
+
+    // completedPhases should count all [x] phases across milestones
+    expect(result.completedPhases).toBe(2);
+  });
+});

package/server/lib/projects-registry.js

@@ -0,0 +1,237 @@
+/**
+ * Projects Registry - Track repos in a workspace
+ *
+ * Provides a registry for managing multiple projects within a workspace.
+ * Supports adding, removing, listing, and auto-detecting projects.
+ *
+ * @module projects-registry
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const PROJECTS_FILE = 'projects.json';
+
+/** Directories to ignore when scanning for repos */
+const IGNORE_DIRS = ['node_modules', '.git', '.svn', '.hg', 'dist', 'build', 'coverage'];
+
+/**
+ * Validate a git URL (SSH or HTTPS format)
+ * @param {string} url - The URL to validate
+ * @throws {Error} If the URL is not a valid git URL
+ */
+function validateGitUrl(url) {
+  // SSH format: git@host:user/repo.git
+  const sshPattern = /^git@[\w.-]+:[\w./-]+$/;
+  // HTTPS format: https://host/user/repo.git or https://host/user/repo
+  const httpsPattern = /^https:\/\/[\w.-]+\/[\w./-]+$/;
+
+  if (!sshPattern.test(url) && !httpsPattern.test(url)) {
+    throw new Error(`Invalid git URL: "${url}". Must be SSH (git@host:user/repo.git) or HTTPS (https://host/user/repo.git)`);
+  }
+}
+
+/**
+ * Ensure a path is relative (strip leading /)
+ * @param {string} localPath - The path to normalize
+ * @returns {string} Relative path
+ */
+function ensureRelativePath(localPath) {
+  return localPath.replace(/^\/+/, '');
+}
+
+/**
+ * Try to extract git remote URL from a repo directory
+ * Uses execSync first, falls back to parsing .git/config
+ * @param {string} repoAbsPath - Absolute path to the repo
+ * @returns {string} Git remote URL or empty string
+ */
+function extractGitRemoteUrl(repoAbsPath) {
+  // Try execSync first
+  try {
+    const url = execSync('git remote get-url origin', {
+      cwd: repoAbsPath,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    if (url) return url;
+  } catch {
+    // execSync failed, try parsing .git/config
+  }
+
+  // Fallback: parse .git/config
+  try {
+    const configPath = path.join(repoAbsPath, '.git', 'config');
+    const content = fs.readFileSync(configPath, 'utf-8');
+    const match = content.match(/\[remote "origin"\][^[]*url\s*=\s*(.+)/);
+    if (match) {
+      return match[1].trim();
+    }
+  } catch {
+    // Can't read git config
+  }
+
+  return '';
+}
+
+/**
+ * Check if a directory has TLC configured
+ * @param {string} dirAbsPath - Absolute path to directory
+ * @returns {boolean}
+ */
+function hasTlcConfig(dirAbsPath) {
+  try {
+    return fs.statSync(path.join(dirAbsPath, '.tlc.json')).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Create a projects registry instance
+ * @returns {Object} Registry with load, save, addProject, removeProject, listProjects, detectFromFilesystem methods
+ */
+function createProjectsRegistry() {
+  /**
+   * Load projects.json from a workspace root
+   * @param {string} workspaceRoot - Absolute path to workspace
+   * @returns {Promise<{version: number, projects: Array}>} Registry data
+   */
+  async function load(workspaceRoot) {
+    const filePath = path.join(workspaceRoot, PROJECTS_FILE);
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      return JSON.parse(content);
+    } catch {
+      return { version: 1, projects: [] };
+    }
+  }
+
+  /**
+   * Save registry data to projects.json atomically (write to temp, then rename)
+   * @param {string} workspaceRoot - Absolute path to workspace
+   * @param {Object} registryData - Registry data with version and projects
+   * @returns {Promise<void>}
+   */
+  async function save(workspaceRoot, registryData) {
+    if (!registryData || typeof registryData.version !== 'number') {
+      throw new Error('Registry data must have a "version" field');
+    }
+
+    const filePath = path.join(workspaceRoot, PROJECTS_FILE);
+    const tempPath = filePath + '.tmp.' + Date.now();
+
+    const content = JSON.stringify(registryData, null, 2) + '\n';
+    fs.writeFileSync(tempPath, content, 'utf-8');
+    fs.renameSync(tempPath, filePath);
+  }
+
+  /**
+   * Add a project to the registry
+   * @param {string} workspaceRoot - Absolute path to workspace
+   * @param {Object} project - Project details
+   * @param {string} project.name - Project name
+   * @param {string} project.gitUrl - Git remote URL (SSH or HTTPS)
+   * @param {string} project.localPath - Relative path within workspace
+   * @param {string} project.branch - Default branch name
+   * @returns {Promise<void>}
+   */
+  async function addProject(workspaceRoot, { name, gitUrl, localPath, branch }) {
+    validateGitUrl(gitUrl);
+
+    const registryData = await load(workspaceRoot);
+    const existing = registryData.projects.find(p => p.name === name);
+    if (existing) {
+      throw new Error(`Project "${name}" already exists in registry`);
+    }
+
+    registryData.projects.push({
+      name,
+      gitUrl,
+      localPath: ensureRelativePath(localPath),
+      defaultBranch: branch || 'main',
+      hasTlc: false,
+      description: '',
+    });
+
+    await save(workspaceRoot, registryData);
+  }
+
+  /**
+   * Remove a project from the registry by name
+   * @param {string} workspaceRoot - Absolute path to workspace
+   * @param {string} name - Project name to remove
+   * @returns {Promise<void>}
+   */
+  async function removeProject(workspaceRoot, name) {
+    const registryData = await load(workspaceRoot);
+    registryData.projects = registryData.projects.filter(p => p.name !== name);
+    await save(workspaceRoot, registryData);
+  }
+
+  /**
+   * List all projects in the registry
+   * @param {string} workspaceRoot - Absolute path to workspace
+   * @returns {Promise<Array>} Array of project entries
+   */
+  async function listProjects(workspaceRoot) {
+    const registryData = await load(workspaceRoot);
+    return registryData.projects;
+  }
+
+  /**
+   * Detect projects from filesystem by scanning for directories with .git/
+   * @param {string} workspaceRoot - Absolute path to workspace
+   * @returns {Promise<Array>} Array of detected project entries
+   */
+  async function detectFromFilesystem(workspaceRoot) {
+    const detected = [];
+
+    try {
+      const entries = fs.readdirSync(workspaceRoot, { withFileTypes: true });
+
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        if (IGNORE_DIRS.includes(entry.name)) continue;
+
+        const dirAbsPath = path.join(workspaceRoot, entry.name);
+        const gitDir = path.join(dirAbsPath, '.git');
+
+        // Only include directories that have a .git/ subdirectory
+        try {
+          const stat = fs.statSync(gitDir);
+          if (!stat.isDirectory()) continue;
+        } catch {
+          continue;
+        }
+
+        const gitUrl = extractGitRemoteUrl(dirAbsPath);
+
+        detected.push({
+          name: entry.name,
+          gitUrl,
+          localPath: entry.name,
+          defaultBranch: 'main',
+          hasTlc: hasTlcConfig(dirAbsPath),
+          description: '',
+        });
+      }
+    } catch {
+      // Ignore scan errors
+    }
+
+    return detected;
+  }
+
+  return {
+    load,
+    save,
+    addProject,
+    removeProject,
+    listProjects,
+    detectFromFilesystem,
+  };
+}
+
+module.exports = { createProjectsRegistry };