tlc-claude-code 2.0.1 → 2.2.0

package/server/lib/orchestration/agent-dispatcher.js

@@ -0,0 +1,114 @@
+/**
+ * Agent Dispatcher
+ * Routes tasks to Claude or Codex with correct CLI flags per provider.
+ */
+
+const SUPPORTED_PROVIDERS = new Set(['claude', 'codex']);
+
+/**
+ * Build a TDD-enforcing prompt from a task object.
+ * @param {object} task - Task with goal, files, criteria, testCases.
+ * @returns {string} Prompt string.
+ */
+export function buildPrompt(task) {
+  const { goal, files = [], criteria = [], testCases = [] } = task;
+
+  const fileList = files.map((f) => `  - ${f}`).join('\n');
+  const criteriaList = criteria.map((c) => `  - ${c}`).join('\n');
+  const testCaseList = testCases.map((t) => `  - ${t}`).join('\n');
+
+  return [
+    `Goal: ${goal}`,
+    '',
+    'Files to work with:',
+    fileList,
+    '',
+    'Acceptance criteria:',
+    criteriaList,
+    '',
+    'Test cases:',
+    testCaseList,
+    '',
+    'Methodology: Write tests first (red → green → refactor). You MUST write the test before implementing any code. Test-first is required.',
+  ].join('\n');
+}
+
+/**
+ * Returns sandbox CLI arguments for Codex based on the current platform.
+ * @param {object} task - Task object (reserved for future use).
+ * @param {string} platform - OS platform string (e.g. 'darwin', 'linux', 'win32').
+ * @returns {string} Sandbox flag string or empty string.
+ */
+export function buildSandboxArgs(_task, platform) {
+  if (platform === 'darwin' || platform === 'linux') {
+    return '--sandbox workspace-write';
+  }
+  return '';
+}
+
+/**
+ * Dispatch a task to the specified AI provider, returning the shell command string.
+ * @param {object} task - Task object.
+ * @param {string} worktreePath - Absolute path to the git worktree.
+ * @param {string} provider - Provider name: 'claude' or 'codex'.
+ * @returns {string} Shell command string.
+ * @throws {Error} If the provider is not supported or not available.
+ */
+export function dispatch(task, worktreePath, provider) {
+  if (!SUPPORTED_PROVIDERS.has(provider)) {
+    throw new Error(`Provider "${provider}" is not supported or unavailable`);
+  }
+
+  const prompt = buildPrompt(task);
+  // Escape shell-sensitive characters to prevent injection from task content
+  const safePrompt = prompt
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\$/g, '\\$')
+    .replace(/`/g, '\\`')
+    .replace(/!/g, '\\!');
+
+  if (provider === 'claude') {
+    return `claude --agent builder --worktree "${worktreePath}" -p "${safePrompt}" --permission-mode auto`;
+  }
+
+  if (provider === 'codex') {
+    const sandbox = buildSandboxArgs(task, process.platform);
+    const sandboxPart = sandbox ? ` ${sandbox}` : '';
+    return `codex exec --full-auto -C "${worktreePath}"${sandboxPart} "${safePrompt}"`;
+  }
+}
+
+/**
+ * Create a round-robin scheduler over a list of providers.
+ * @param {string[]} providers - Ordered list of provider names.
+ * @param {object} [routerState] - Optional router state with availability info.
+ * @returns {{ next: () => string }} Object with a `.next()` method.
+ */
+export function createRoundRobin(providers, routerState) {
+  // Filter to only available providers when routerState is given
+  const available = routerState
+    ? providers.filter((p) => {
+        const info = routerState.providers?.[p];
+        return info ? info.available : true;
+      })
+    : providers;
+
+  // If routerState was provided and filtered everything out, respect that — don't fall back
+  const pool = routerState ? available : providers;
+  if (pool.length === 0) {
+    // No providers available — return a robin that always throws
+    return {
+      next() { throw new Error('No available providers in router state'); },
+    };
+  }
+
+  let index = 0;
+  return {
+    next() {
+      const provider = pool[index % pool.length];
+      index += 1;
+      return provider;
+    },
+  };
+}

package/server/lib/orchestration/agent-dispatcher.test.js

@@ -0,0 +1,110 @@
+import { describe, it, expect, vi } from 'vitest';
+import {
+  dispatch,
+  buildPrompt,
+  buildSandboxArgs,
+  createRoundRobin,
+} from './agent-dispatcher.js';
+
+const SAMPLE_TASK = {
+  title: 'Create user schema',
+  goal: 'Define database schema for users table',
+  files: ['src/modules/user/user.repository.js', 'src/modules/user/user.repository.test.js'],
+  criteria: ['Schema has id, email, passwordHash', 'Email is unique'],
+  testCases: ['Schema validates correct user data', 'Schema rejects duplicate emails'],
+};
+
+const ROUTER_STATE = {
+  providers: {
+    claude: { available: true, path: '/usr/bin/claude' },
+    codex: { available: true, path: '/usr/bin/codex' },
+    gemini: { available: false, path: '' },
+  },
+};
+
+describe('agent-dispatcher', () => {
+  describe('dispatch', () => {
+    it('builds correct Claude command with worktree', () => {
+      const cmd = dispatch(SAMPLE_TASK, '/path/to/worktree', 'claude');
+      expect(cmd).toContain('claude');
+      expect(cmd).toContain('--agent builder');
+      expect(cmd).toContain('/path/to/worktree');
+      expect(cmd).toContain('--permission-mode');
+    });
+
+    it('builds correct Codex command with sandbox', () => {
+      const cmd = dispatch(SAMPLE_TASK, '/path/to/worktree', 'codex');
+      expect(cmd).toContain('codex exec');
+      expect(cmd).toContain('--full-auto');
+      expect(cmd).toContain('-C "/path/to/worktree"');
+      expect(cmd).toContain('--sandbox');
+    });
+
+    it('skips unavailable provider', () => {
+      expect(() => dispatch(SAMPLE_TASK, '/path', 'gemini'))
+        .toThrow(/unavailable|not supported/i);
+    });
+  });
+
+  describe('buildPrompt', () => {
+    it('includes acceptance criteria from task', () => {
+      const prompt = buildPrompt(SAMPLE_TASK);
+      expect(prompt).toContain('Schema has id, email, passwordHash');
+      expect(prompt).toContain('Email is unique');
+    });
+
+    it('includes test cases from task', () => {
+      const prompt = buildPrompt(SAMPLE_TASK);
+      expect(prompt).toContain('Schema validates correct user data');
+    });
+
+    it('includes file list', () => {
+      const prompt = buildPrompt(SAMPLE_TASK);
+      expect(prompt).toContain('user.repository.js');
+    });
+
+    it('enforces test-first', () => {
+      const prompt = buildPrompt(SAMPLE_TASK);
+      expect(prompt.toLowerCase()).toMatch(/test.*first|red.*green|write.*test.*before/);
+    });
+  });
+
+  describe('buildSandboxArgs', () => {
+    it('uses workspace-write on macOS', () => {
+      const args = buildSandboxArgs(SAMPLE_TASK, 'darwin');
+      expect(args).toContain('--sandbox workspace-write');
+    });
+
+    it('uses workspace-write on Linux', () => {
+      const args = buildSandboxArgs(SAMPLE_TASK, 'linux');
+      expect(args).toContain('--sandbox workspace-write');
+    });
+
+    it('returns empty string for unsupported platform', () => {
+      const args = buildSandboxArgs(SAMPLE_TASK, 'win32');
+      expect(args).toBe('');
+    });
+  });
+
+  describe('createRoundRobin', () => {
+    it('alternates between providers', () => {
+      const rr = createRoundRobin(['claude', 'codex']);
+      expect(rr.next()).toBe('claude');
+      expect(rr.next()).toBe('codex');
+      expect(rr.next()).toBe('claude');
+    });
+
+    it('skips unavailable providers', () => {
+      const rr = createRoundRobin(['claude', 'codex'], ROUTER_STATE);
+      // Both available, should alternate
+      expect(rr.next()).toBe('claude');
+      expect(rr.next()).toBe('codex');
+    });
+
+    it('handles single provider', () => {
+      const rr = createRoundRobin(['claude']);
+      expect(rr.next()).toBe('claude');
+      expect(rr.next()).toBe('claude');
+    });
+  });
+});

package/server/lib/orchestration/orchestrator.js

@@ -0,0 +1,130 @@
+/**
+ * Orchestrator Engine
+ * Coordinates parallel agent execution with dependency-aware scheduling.
+ */
+
+/**
+ * Parses markdown plan content and extracts tasks.
+ * @param {string} planContent - Markdown plan content
+ * @returns {Array<{number: number, title: string, goal: string, files: string[], criteria: string[], testCases: string[]}>}
+ */
+export function parsePlanTasks(planContent) {
+  const tasks = [];
+  // Split on task headings: ### Task N: Title  OR  ### Task N.M: Title
+  const sections = planContent.split(/^(?=### Task [\d.]+:)/m);
+
+  for (const section of sections) {
+    const headingMatch = section.match(/^### Task ([\d.]+):\s*(.+?)(?:\s*\[.*?\])?\s*$/m);
+    if (!headingMatch) continue;
+
+    // Use integer for plain numbers (1, 2, 3), keep full string for dotted (87.1, 87.2)
+    const rawId = headingMatch[1];
+    const number = rawId.includes('.') ? rawId : parseInt(rawId, 10);
+    const title = headingMatch[2].trim();
+
+    // Goal
+    const goalMatch = section.match(/\*\*Goal:\*\*\s*(.+)/);
+    const goal = goalMatch ? goalMatch[1].trim() : '';
+
+    // Files
+    const filesMatch = section.match(/\*\*Files:\*\*\s*([\s\S]*?)(?=\*\*|---|\n##|$)/);
+    const files = filesMatch
+      ? filesMatch[1].split('\n').map(l => l.replace(/^-\s*/, '').trim()).filter(Boolean)
+      : [];
+
+    // Acceptance Criteria
+    const criteriaMatch = section.match(/\*\*Acceptance Criteria:\*\*\s*([\s\S]*?)(?=\*\*|---|\n##|$)/);
+    const criteria = criteriaMatch
+      ? criteriaMatch[1].split('\n').map(l => l.replace(/^-\s*\[.\]\s*/, '').replace(/^-\s*/, '').trim()).filter(Boolean)
+      : [];
+
+    // Test Cases
+    const testCasesMatch = section.match(/\*\*Test Cases:\*\*\s*([\s\S]*?)(?=\*\*|---|\n##|$)/);
+    const testCases = testCasesMatch
+      ? testCasesMatch[1].split('\n').map(l => l.replace(/^-\s*/, '').trim()).filter(Boolean)
+      : [];
+
+    tasks.push({ number, title, goal, files, criteria, testCases });
+  }
+
+  return tasks;
+}
+
+/**
+ * Builds a dependency graph from tasks and plan content.
+ * @param {Array<{number: number}>} tasks
+ * @param {string} planContent
+ * @returns {Map<number, number[]>} key=taskNumber, value=array of taskNumbers it depends on
+ */
+export function buildDependencyGraph(tasks, planContent) {
+  const graph = new Map();
+
+  // Initialise all tasks with empty dependency lists
+  for (const task of tasks) {
+    graph.set(task.number, []);
+  }
+
+  // Parse ## Dependencies section
+  const depsMatch = planContent.match(/## Dependencies([\s\S]*?)(?=\n## |\n*$)/);
+  if (!depsMatch) return graph;
+
+  const depsSection = depsMatch[1];
+  // Match lines like "Task N depends on Task M"
+  const lineRe = /Task ([\d.]+) depends on Task ([\d.]+)/g;
+  let match;
+  while ((match = lineRe.exec(depsSection)) !== null) {
+    const rawDep = match[1];
+    const rawReq = match[2];
+    const dependent = rawDep.includes('.') ? rawDep : parseInt(rawDep, 10);
+    const dependency = rawReq.includes('.') ? rawReq : parseInt(rawReq, 10);
+    if (!graph.has(dependent)) graph.set(dependent, []);
+    graph.get(dependent).push(dependency);
+  }
+
+  return graph;
+}
+
+/**
+ * Returns tasks that have no unmet dependencies and are not already completed.
+ * @param {Array<{number: number}>} tasks
+ * @param {Map<number, number[]>} graph
+ * @param {Set<number>} completedSet
+ * @returns {Array<{number: number}>}
+ */
+export function getIndependentTasks(tasks, graph, completedSet) {
+  return tasks.filter(task => {
+    if (completedSet.has(task.number)) return false;
+    const deps = graph.get(task.number) || [];
+    return deps.every(dep => completedSet.has(dep));
+  });
+}
+
+/**
+ * Orchestrates agent execution for a phase.
+ * @param {number} phaseNumber
+ * @param {object} options
+ * @param {boolean} [options.dryRun]
+ * @param {string} [options.planContent]
+ * @param {number} [options.maxAgents]
+ * @returns {Promise<object>}
+ */
+export async function orchestrate(phaseNumber, options = {}) {
+  const { dryRun = false, planContent, maxAgents } = options;
+
+  if (dryRun) {
+    const tasks = parsePlanTasks(planContent);
+    const graph = buildDependencyGraph(tasks, planContent);
+    const independent = getIndependentTasks(tasks, graph, new Set());
+    const independentCount = independent.length;
+    return {
+      dryRun: true,
+      tasks,
+      independentCount,
+      maxAgents,
+      sequential: independentCount <= 1,
+    };
+  }
+
+  // Full orchestration (not needed for current tests)
+  throw new Error('Live orchestration not yet implemented');
+}

package/server/lib/orchestration/orchestrator.test.js

@@ -0,0 +1,192 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+  parsePlanTasks,
+  buildDependencyGraph,
+  getIndependentTasks,
+  orchestrate,
+} from './orchestrator.js';
+
+const SAMPLE_PLAN = `# Phase 42: Auth — Plan
+
+## Tasks
+
+### Task 1: Create user schema [ ]
+
+**Goal:** Define schema
+
+**Files:**
+- src/user.js
+
+**Acceptance Criteria:**
+- [ ] Schema works
+
+**Test Cases:**
+- Schema validates
+
+---
+
+### Task 2: Login endpoint [ ]
+
+**Goal:** POST /login
+
+**Files:**
+- src/login.js
+
+**Acceptance Criteria:**
+- [ ] Login works
+
+**Test Cases:**
+- Valid login returns token
+
+---
+
+### Task 3: Session middleware [ ]
+
+**Goal:** JWT session
+
+**Files:**
+- src/session.js
+
+**Acceptance Criteria:**
+- [ ] Session persists
+
+**Test Cases:**
+- Session validates token
+
+## Dependencies
+
+Task 2 depends on Task 1
+Task 3 depends on Task 2
+`;
+
+const PARALLEL_PLAN = `# Phase 43: Utils — Plan
+
+## Tasks
+
+### Task 1: String helpers [ ]
+
+**Goal:** String utilities
+
+**Files:**
+- src/strings.js
+
+**Acceptance Criteria:**
+- [ ] Helpers work
+
+**Test Cases:**
+- capitalize works
+
+---
+
+### Task 2: Date helpers [ ]
+
+**Goal:** Date utilities
+
+**Files:**
+- src/dates.js
+
+**Acceptance Criteria:**
+- [ ] Helpers work
+
+**Test Cases:**
+- formatDate works
+
+---
+
+### Task 3: Number helpers [ ]
+
+**Goal:** Number utilities
+
+**Files:**
+- src/numbers.js
+
+**Acceptance Criteria:**
+- [ ] Helpers work
+
+**Test Cases:**
+- clamp works
+`;
+
+describe('orchestrator', () => {
+  describe('parsePlanTasks', () => {
+    it('extracts tasks from plan content', () => {
+      const tasks = parsePlanTasks(SAMPLE_PLAN);
+      expect(tasks).toHaveLength(3);
+      expect(tasks[0].title).toContain('Create user schema');
+      expect(tasks[1].title).toContain('Login endpoint');
+    });
+  });
+
+  describe('buildDependencyGraph', () => {
+    it('identifies dependent tasks', () => {
+      const tasks = parsePlanTasks(SAMPLE_PLAN);
+      const graph = buildDependencyGraph(tasks, SAMPLE_PLAN);
+      expect(graph.get(2)).toContain(1); // Task 2 depends on Task 1
+      expect(graph.get(3)).toContain(2); // Task 3 depends on Task 2
+    });
+
+    it('returns empty deps for independent tasks', () => {
+      const tasks = parsePlanTasks(PARALLEL_PLAN);
+      const graph = buildDependencyGraph(tasks, PARALLEL_PLAN);
+      expect(graph.get(1)).toHaveLength(0);
+      expect(graph.get(2)).toHaveLength(0);
+      expect(graph.get(3)).toHaveLength(0);
+    });
+  });
+
+  describe('getIndependentTasks', () => {
+    it('returns all tasks when no dependencies', () => {
+      const tasks = parsePlanTasks(PARALLEL_PLAN);
+      const graph = buildDependencyGraph(tasks, PARALLEL_PLAN);
+      const independent = getIndependentTasks(tasks, graph, new Set());
+      expect(independent).toHaveLength(3);
+    });
+
+    it('returns only root tasks when dependencies exist', () => {
+      const tasks = parsePlanTasks(SAMPLE_PLAN);
+      const graph = buildDependencyGraph(tasks, SAMPLE_PLAN);
+      const independent = getIndependentTasks(tasks, graph, new Set());
+      expect(independent).toHaveLength(1);
+      expect(independent[0].title).toContain('Create user schema');
+    });
+
+    it('unblocks dependent tasks when prerequisite completed', () => {
+      const tasks = parsePlanTasks(SAMPLE_PLAN);
+      const graph = buildDependencyGraph(tasks, SAMPLE_PLAN);
+      const completed = new Set([1]); // Task 1 done
+      const independent = getIndependentTasks(tasks, graph, completed);
+      expect(independent).toHaveLength(1);
+      expect(independent[0].title).toContain('Login endpoint');
+    });
+  });
+
+  describe('orchestrate', () => {
+    it('generates build report on dry-run', async () => {
+      const result = await orchestrate(43, {
+        dryRun: true,
+        planContent: PARALLEL_PLAN,
+      });
+      expect(result.dryRun).toBe(true);
+      expect(result.tasks).toHaveLength(3);
+      expect(result.independentCount).toBe(3);
+    });
+
+    it('respects max concurrent limit in dry-run', async () => {
+      const result = await orchestrate(43, {
+        dryRun: true,
+        planContent: PARALLEL_PLAN,
+        maxAgents: 2,
+      });
+      expect(result.maxAgents).toBe(2);
+    });
+
+    it('identifies sequential plan correctly', async () => {
+      const result = await orchestrate(42, {
+        dryRun: true,
+        planContent: SAMPLE_PLAN,
+      });
+      expect(result.independentCount).toBe(1);
+      expect(result.sequential).toBe(true);
+    });
+  });
+});

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