tlc-claude-code 2.0.1 → 2.2.0

package/server/lib/orchestration/tmux-manager.test.js

@@ -0,0 +1,109 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+  createSession,
+  addPane,
+  capturePane,
+  killSession,
+  isAvailable,
+  buildLayout,
+} from './tmux-manager.js';
+
+describe('tmux-manager', () => {
+  let exec;
+
+  beforeEach(() => {
+    exec = vi.fn(() => '');
+  });
+
+  describe('isAvailable', () => {
+    it('returns true when tmux is installed', () => {
+      exec.mockReturnValue('/usr/bin/tmux');
+      expect(isAvailable({ exec })).toBe(true);
+    });
+
+    it('returns false when tmux is missing', () => {
+      exec.mockImplementation(() => { throw new Error('not found'); });
+      expect(isAvailable({ exec })).toBe(false);
+    });
+  });
+
+  describe('createSession', () => {
+    it('generates correct tmux new-session command', () => {
+      exec.mockReturnValue('');
+      createSession('tlc-build-42', { exec });
+      const cmd = exec.mock.calls[0][0];
+      expect(cmd).toContain('tmux new-session');
+      expect(cmd).toContain('tlc-build-42');
+    });
+
+    it('sanitizes session names', () => {
+      exec.mockReturnValue('');
+      createSession('bad session/name!', { exec });
+      const cmd = exec.mock.calls[0][0];
+      expect(cmd).not.toContain('/');
+      expect(cmd).not.toContain('!');
+    });
+  });
+
+  describe('addPane', () => {
+    it('splits correctly for 2 panes (vertical)', () => {
+      exec.mockReturnValue('');
+      addPane('sess', 'agent-1', 'echo hello', { exec, paneCount: 2 });
+      const cmd = exec.mock.calls[0][0];
+      expect(cmd).toContain('split-window');
+    });
+
+    it('splits correctly for 4 panes (2x2 grid)', () => {
+      exec.mockReturnValue('');
+      addPane('sess', 'agent-3', 'echo test', { exec, paneCount: 4, paneIndex: 3 });
+      const cmd = exec.mock.calls[0][0];
+      expect(cmd).toContain('split-window');
+    });
+
+    it('runs command in the new pane', () => {
+      exec.mockReturnValue('');
+      addPane('sess', 'agent-1', 'codex exec "do stuff"', { exec, paneCount: 2 });
+      const cmds = exec.mock.calls.map(c => c[0]);
+      expect(cmds.some(c => c.includes('codex exec'))).toBe(true);
+    });
+  });
+
+  describe('capturePane', () => {
+    it('returns pane content via tmux capture-pane', () => {
+      exec.mockReturnValue('Line 1\nLine 2\nLine 3');
+      const content = capturePane('sess', 0, { exec });
+      expect(content).toContain('Line 1');
+      expect(content).toContain('Line 3');
+      const cmd = exec.mock.calls[0][0];
+      expect(cmd).toContain('capture-pane');
+      expect(cmd).toContain(':.'); // pane target uses .N syntax
+    });
+  });
+
+  describe('killSession', () => {
+    it('runs tmux kill-session', () => {
+      exec.mockReturnValue('');
+      killSession('tlc-build-42', { exec });
+      const cmd = exec.mock.calls[0][0];
+      expect(cmd).toContain('kill-session');
+      expect(cmd).toContain('tlc-build-42');
+    });
+  });
+
+  describe('buildLayout', () => {
+    it('returns vertical for 2 agents', () => {
+      const layout = buildLayout(2);
+      expect(layout.type).toBe('vertical');
+    });
+
+    it('returns grid for 4 agents', () => {
+      const layout = buildLayout(4);
+      expect(layout.type).toBe('grid');
+    });
+
+    it('returns tiled for >4 agents', () => {
+      const layout = buildLayout(6);
+      expect(layout.type).toBe('tiled');
+    });
+  });
+});

package/server/lib/orchestration/worktree-manager.js

@@ -0,0 +1,132 @@
+/**
+ * Worktree Manager
+ * Creates and manages git worktrees for parallel agent work.
+ */
+
+/**
+ * Sanitize a worktree name: spaces become hyphens, all other non-alphanumeric
+ * non-hyphen characters are stripped, then multiple hyphens are collapsed.
+ * @param {string} name
+ * @returns {string}
+ */
+export function sanitizeName(name) {
+  return name
+    .replace(/ /g, '-')
+    .replace(/[^a-zA-Z0-9-]/g, '')
+    .replace(/-{2,}/g, '-');
+}
+
+/**
+ * Create a git worktree for the given name.
+ * @param {string} name - Worktree name (will be sanitized)
+ * @param {{ exec: Function, maxConcurrent?: number }} options
+ * @returns {{ name: string, branch: string, path: string }}
+ */
+export function createWorktree(name, { exec, maxConcurrent } = {}) {
+  const safe = sanitizeName(name);
+  const limit = maxConcurrent != null ? maxConcurrent : 4;
+
+  // Only check the concurrent limit when explicitly requested (maxConcurrent passed)
+  if (maxConcurrent != null) {
+    const listOutput = exec('git worktree list');
+    // Exclude the primary checkout (first line) — only count auxiliary worktrees
+    const currentCount = listOutput
+      .split('\n')
+      .filter((line) => line.trim() !== '').length - 1;
+
+    if (currentCount >= limit) {
+      throw new Error(`Max concurrent worktrees (${limit}) reached`);
+    }
+  }
+
+  const branch = `worktree-${safe}`;
+  const path = `.claude/worktrees/${safe}`;
+
+  exec(`git worktree add -b ${branch} ${path}`);
+
+  return { name: safe, branch, path };
+}
+
+/**
+ * List active worktrees under .claude/worktrees/.
+ * @param {{ exec: Function }} options
+ * @returns {Array<{ name: string, branch: string, path: string }>}
+ */
+export function listWorktrees({ exec } = {}) {
+  const output = exec('git worktree list');
+  return output
+    .split('\n')
+    .filter((line) => line.includes('.claude/worktrees/'))
+    .map((line) => {
+      // Format: /repo/.claude/worktrees/task-1  abc1234 [worktree-task-1]
+      const parts = line.trim().split(/\s+/);
+      const worktreePath = parts[0];
+      const branchMatch = line.match(/\[([^\]]+)\]/);
+      const branch = branchMatch ? branchMatch[1] : '';
+      const namePart = worktreePath.split('.claude/worktrees/')[1];
+      return { name: namePart, branch, path: worktreePath };
+    });
+}
+
+/**
+ * Merge a worktree branch into targetBranch, then remove the worktree.
+ * On conflict, returns { merged: false, conflict: true } without removing.
+ * @param {string} name - Worktree name (already sanitized)
+ * @param {string} targetBranch
+ * @param {{ exec: Function }} options
+ * @returns {{ merged: boolean, conflict?: boolean }}
+ */
+export function mergeWorktree(name, targetBranch, { exec } = {}) {
+  const safe = sanitizeName(name);
+  const branch = `worktree-${safe}`;
+  const path = `.claude/worktrees/${safe}`;
+
+  try {
+    exec(`git checkout ${targetBranch}`);
+    exec(`git merge ${branch}`);
+  } catch (_err) {
+    return { merged: false, conflict: true };
+  }
+
+  exec(`git worktree remove ${path}`);
+  exec(`git branch -D ${branch}`);
+
+  return { merged: true };
+}
+
+/**
+ * Forcefully remove a worktree directory and its tracking branch.
+ * @param {string} name - Worktree name (already sanitized)
+ * @param {{ exec: Function }} options
+ */
+export function removeWorktree(name, { exec } = {}) {
+  const safe = sanitizeName(name);
+  const branch = `worktree-${safe}`;
+  const path = `.claude/worktrees/${safe}`;
+
+  exec(`git worktree remove --force ${path}`);
+  exec(`git branch -D ${branch}`);
+}
+
+/**
+ * Remove worktrees whose last commit is older than maxAge milliseconds.
+ * @param {{ exec: Function, maxAge?: number }} options
+ * @returns {string[]} Names of removed worktrees
+ */
+export function cleanupStale({ exec, maxAge = 2 * 3600_000 } = {}) {
+  const worktrees = listWorktrees({ exec });
+  const removed = [];
+  const now = Date.now();
+
+  for (const wt of worktrees) {
+    const lastCommitStr = exec(`git log -1 --format=%cI ${wt.branch}`).trim();
+    const lastCommitTime = new Date(lastCommitStr).getTime();
+
+    if (now - lastCommitTime > maxAge) {
+      removeWorktree(wt.name, { exec });
+      removed.push(wt.name);
+    }
+  }
+
+  return removed;
+}

package/server/lib/orchestration/worktree-manager.test.js

@@ -0,0 +1,129 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+  createWorktree,
+  listWorktrees,
+  mergeWorktree,
+  removeWorktree,
+  cleanupStale,
+  sanitizeName,
+} from './worktree-manager.js';
+
+describe('worktree-manager', () => {
+  let exec;
+
+  beforeEach(() => {
+    exec = vi.fn(() => '');
+  });
+
+  describe('sanitizeName', () => {
+    it('passes through alphanumeric and hyphens', () => {
+      expect(sanitizeName('phase-42-task-1')).toBe('phase-42-task-1');
+    });
+
+    it('strips special characters', () => {
+      expect(sanitizeName('my task/name@v2!')).toBe('my-tasknamev2');
+    });
+
+    it('collapses multiple hyphens', () => {
+      expect(sanitizeName('a--b---c')).toBe('a-b-c');
+    });
+  });
+
+  describe('createWorktree', () => {
+    it('creates directory and branch', () => {
+      exec.mockReturnValue('');
+      const result = createWorktree('phase-42-task-1', { exec });
+      expect(result.name).toBe('phase-42-task-1');
+      expect(result.branch).toBe('worktree-phase-42-task-1');
+      expect(result.path).toContain('.claude/worktrees/phase-42-task-1');
+      expect(exec).toHaveBeenCalled();
+      const cmd = exec.mock.calls[0][0];
+      expect(cmd).toContain('git worktree add');
+    });
+
+    it('rejects when at max concurrent limit', () => {
+      // 5 lines = 1 primary + 4 auxiliary worktrees → at limit of 4
+      exec.mockReturnValue('/repo  abc [main]\nworktree-a\nworktree-b\nworktree-c\nworktree-d\n');
+      expect(() => createWorktree('task-5', { exec, maxConcurrent: 4 }))
+        .toThrow(/max/i);
+    });
+
+    it('sanitizes names', () => {
+      exec.mockReturnValue('');
+      const result = createWorktree('bad name/here!', { exec });
+      expect(result.name).toBe('bad-namehere');
+    });
+  });
+
+  describe('listWorktrees', () => {
+    it('returns active worktrees with branch and path', () => {
+      exec.mockReturnValue(
+        '/repo/.claude/worktrees/task-1  abc1234 [worktree-task-1]\n' +
+        '/repo/.claude/worktrees/task-2  def5678 [worktree-task-2]\n'
+      );
+      const list = listWorktrees({ exec });
+      expect(list).toHaveLength(2);
+      expect(list[0].name).toBe('task-1');
+      expect(list[0].branch).toBe('worktree-task-1');
+      expect(list[0].path).toContain('task-1');
+    });
+
+    it('returns empty array when no worktrees', () => {
+      exec.mockReturnValue('/repo  abc1234 [main]\n');
+      const list = listWorktrees({ exec });
+      expect(list).toHaveLength(0);
+    });
+  });
+
+  describe('mergeWorktree', () => {
+    it('merges branch and cleans up', () => {
+      exec.mockReturnValue('');
+      const result = mergeWorktree('task-1', 'main', { exec });
+      expect(result.merged).toBe(true);
+      const cmds = exec.mock.calls.map(c => c[0]);
+      expect(cmds.some(c => c.includes('git merge'))).toBe(true);
+      expect(cmds.some(c => c.includes('git worktree remove'))).toBe(true);
+    });
+
+    it('reports conflict without destroying worktree', () => {
+      exec.mockImplementation((cmd) => {
+        if (cmd.includes('git merge')) throw new Error('CONFLICT');
+        return '';
+      });
+      const result = mergeWorktree('task-1', 'main', { exec });
+      expect(result.merged).toBe(false);
+      expect(result.conflict).toBe(true);
+      // Should NOT have called worktree remove
+      const cmds = exec.mock.calls.map(c => c[0]);
+      expect(cmds.some(c => c.includes('git worktree remove'))).toBe(false);
+    });
+  });
+
+  describe('removeWorktree', () => {
+    it('removes both directory and branch', () => {
+      exec.mockReturnValue('');
+      removeWorktree('task-1', { exec });
+      const cmds = exec.mock.calls.map(c => c[0]);
+      expect(cmds.some(c => c.includes('git worktree remove'))).toBe(true);
+      expect(cmds.some(c => c.includes('git branch -D'))).toBe(true);
+    });
+  });
+
+  describe('cleanupStale', () => {
+    it('removes only worktrees past timeout', () => {
+      const oldDate = new Date(Date.now() - 3 * 3600_000).toISOString(); // 3h ago
+      const freshDate = new Date(Date.now() - 30 * 60_000).toISOString(); // 30min ago
+      exec.mockImplementation((cmd) => {
+        if (cmd.includes('worktree list')) {
+          return '/repo/.claude/worktrees/old-task  abc [worktree-old-task]\n/repo/.claude/worktrees/new-task  def [worktree-new-task]\n';
+        }
+        if (cmd.includes('log') && cmd.includes('old-task')) return oldDate;
+        if (cmd.includes('log') && cmd.includes('new-task')) return freshDate;
+        return '';
+      });
+      const removed = cleanupStale({ exec, maxAge: 2 * 3600_000 });
+      expect(removed).toContain('old-task');
+      expect(removed).not.toContain('new-task');
+    });
+  });
+});

package/server/lib/port-guard.js

@@ -0,0 +1,44 @@
+/**
+ * Port guard - checks if a port is available before server startup.
+ *
+ * Detects port conflicts and reports which process holds the port.
+ * Designed for use with launchd ThrottleInterval to prevent restart spam.
+ *
+ * @module port-guard
+ */
+
+const net = require('net');
+
+/**
+ * Check if a port is available.
+ *
+ * @param {number} port - Port number to check
+ * @returns {Promise<{available: boolean, port: number, pid?: number, command?: string}>}
+ */
+async function checkPort(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+
+    server.once('error', (err) => {
+      if (err.code === 'EADDRINUSE') {
+        resolve({ available: false, port });
+      } else {
+        // Unexpected error — treat as unavailable
+        resolve({ available: false, port });
+      }
+    });
+
+    server.once('listening', () => {
+      // Port is free — close the test server
+      const addr = server.address();
+      const actualPort = addr ? addr.port : port;
+      server.close(() => {
+        resolve({ available: true, port: actualPort });
+      });
+    });
+
+    server.listen(port);
+  });
+}
+
+module.exports = { checkPort };

package/server/lib/port-guard.test.js

@@ -0,0 +1,65 @@
+/**
+ * Port guard tests - Phase 83 Task 2
+ */
+
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import net from 'net';
+
+import { checkPort } from './port-guard.js';
+
+describe('port-guard', () => {
+  let tempServer;
+
+  afterEach(() => {
+    if (tempServer) {
+      tempServer.close();
+      tempServer = null;
+    }
+  });
+
+  it('returns available:true when port is free', async () => {
+    // Use a high ephemeral port unlikely to be in use
+    const result = await checkPort(0);
+    expect(result.available).toBe(true);
+  });
+
+  it('returns available:false when port is occupied', async () => {
+    // Occupy a port first
+    tempServer = net.createServer();
+    await new Promise((resolve, reject) => {
+      tempServer.listen(0, resolve);
+      tempServer.on('error', reject);
+    });
+    const port = tempServer.address().port;
+
+    const result = await checkPort(port);
+    expect(result.available).toBe(false);
+  });
+
+  it('includes pid info when port is occupied (best effort)', async () => {
+    tempServer = net.createServer();
+    await new Promise((resolve, reject) => {
+      tempServer.listen(0, resolve);
+      tempServer.on('error', reject);
+    });
+    const port = tempServer.address().port;
+
+    const result = await checkPort(port);
+    expect(result.available).toBe(false);
+    // pid is best-effort (may not be available on all platforms)
+    expect(result).toHaveProperty('port', port);
+  });
+
+  it('handles EADDRINUSE gracefully', async () => {
+    tempServer = net.createServer();
+    await new Promise((resolve, reject) => {
+      tempServer.listen(0, resolve);
+      tempServer.on('error', reject);
+    });
+    const port = tempServer.address().port;
+
+    // Should not throw
+    const result = await checkPort(port);
+    expect(result.available).toBe(false);
+  });
+});

package/server/lib/project-scanner.js

@@ -109,9 +109,11 @@ 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
+  // Read name, version, and workspaces from package.json if present
   let name = path.basename(projectDir);
   let version = null;
+  let isMonorepo = false;
+  let workspaces = [];
 
   const pkgPath = path.join(projectDir, 'package.json');
   if (fs.existsSync(pkgPath)) {
@@ -123,6 +125,34 @@ function readProjectMetadata(projectDir) {
       if (pkg.version) {
         version = pkg.version;
       }
+
+      // Detect monorepo workspaces (npm array or yarn object format)
+      let workspacePatterns = null;
+      if (Array.isArray(pkg.workspaces)) {
+        workspacePatterns = pkg.workspaces;
+      } else if (pkg.workspaces && Array.isArray(pkg.workspaces.packages)) {
+        workspacePatterns = pkg.workspaces.packages;
+      }
+
+      if (workspacePatterns) {
+        isMonorepo = true;
+        // Resolve glob patterns to actual directories
+        for (const pattern of workspacePatterns) {
+          try {
+            const globDir = path.join(projectDir, path.dirname(pattern));
+            if (fs.existsSync(globDir)) {
+              const entries = fs.readdirSync(globDir, { withFileTypes: true });
+              for (const entry of entries) {
+                if (entry.isDirectory()) {
+                  workspaces.push(path.join(path.dirname(pattern), entry.name));
+                }
+              }
+            }
+          } catch {
+            // Ignore glob resolution errors
+          }
+        }
+      }
     } catch {
       // Ignore malformed package.json
     }
@@ -147,6 +177,8 @@ function readProjectMetadata(projectDir) {
     phaseName: phaseInfo.phaseName,
     totalPhases: phaseInfo.totalPhases,
     completedPhases: phaseInfo.completedPhases,
+    isMonorepo,
+    workspaces,
   };
 }
 
@@ -235,9 +267,12 @@ class ProjectScanner {
       if (typeof onProgress === 'function') {
         onProgress(projectsByPath.size);
       }
+
+      // Stop recursion: a project's children are not separate projects
+      return;
     }
 
-    // Recurse into subdirectories
+    // Recurse into subdirectories (only for non-project directories)
     let entries;
     try {
       entries = fs.readdirSync(dir, { withFileTypes: true });