tlc-claude-code 2.1.0 → 2.2.0

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

@@ -0,0 +1,101 @@
+/**
+ * Tmux Session Manager
+ * Manages tmux sessions with panes for agent visibility.
+ */
+
+/**
+ * Sanitizes a session name by stripping special characters and replacing spaces with hyphens.
+ * @param {string} name - Raw session name
+ * @returns {string} Sanitized session name
+ */
+function sanitizeName(name) {
+  return name
+    .replace(/\s+/g, '-')
+    .replace(/[^a-zA-Z0-9\-_]/g, '');
+}
+
+/**
+ * Checks whether tmux is available on the system.
+ * @param {{ exec: Function }} deps - Injected exec function
+ * @returns {boolean} True if tmux is found, false otherwise
+ */
+export function isAvailable({ exec }) {
+  try {
+    exec('which tmux');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Creates a new detached tmux session with the given name.
+ * @param {string} name - Session name (will be sanitized)
+ * @param {{ exec: Function }} deps - Injected exec function
+ */
+export function createSession(name, { exec }) {
+  const safe = sanitizeName(name);
+  exec(`tmux new-session -d -s ${safe}`);
+}
+
+/**
+ * Adds a pane to an existing tmux session and runs a command in it.
+ * @param {string} session - Session name
+ * @param {string} paneName - Logical pane name (unused by tmux directly)
+ * @param {string} command - Command to send to the pane
+ * @param {{ exec: Function, paneCount?: number, paneIndex?: number }} deps - Injected deps
+ */
+export function addPane(session, paneName, command, { exec, paneCount = 2, paneIndex = 1 }) {
+  // For 4-pane grid: alternate horizontal/vertical splits based on pane index
+  // For 2 panes: vertical split (side by side)
+  // Default: vertical split
+  let splitFlag;
+  if (paneCount === 4) {
+    // paneIndex 1,3 => horizontal split; paneIndex 2,4 => vertical split
+    splitFlag = paneIndex % 2 === 1 ? '-h' : '-v';
+  } else {
+    // 2 panes: vertical split (splits current pane side-by-side)
+    splitFlag = '-h';
+  }
+
+  exec(`tmux split-window ${splitFlag} -t ${session}`);
+  // Use single quotes to avoid shell re-tokenizing nested double quotes in the command
+  exec(`tmux send-keys -t ${session} '${command.replace(/'/g, "'\\''")}' Enter`);
+}
+
+/**
+ * Captures the current content of a pane and returns it as a string.
+ * @param {string} session - Session name
+ * @param {number} paneIndex - Zero-based pane index
+ * @param {{ exec: Function }} deps - Injected exec function
+ * @returns {string} Captured pane content
+ */
+export function capturePane(session, paneIndex, { exec }) {
+  // Use .N suffix to target pane N within the session's first window
+  return exec(`tmux capture-pane -t ${session}:.${paneIndex} -p`);
+}
+
+/**
+ * Kills a tmux session by name.
+ * @param {string} name - Session name
+ * @param {{ exec: Function }} deps - Injected exec function
+ */
+export function killSession(name, { exec }) {
+  const safe = sanitizeName(name);
+  exec(`tmux kill-session -t ${safe}`);
+}
+
+/**
+ * Builds a layout descriptor based on the number of agents.
+ * @param {number} agentCount - Number of agents/panes
+ * @returns {{ type: string }} Layout descriptor
+ */
+export function buildLayout(agentCount) {
+  if (agentCount === 2) {
+    return { type: 'vertical' };
+  }
+  if (agentCount <= 4) {
+    return { type: 'grid' };
+  }
+  return { type: 'tiled' };
+}

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');
+    });
+  });
+});