tlc-claude-code 2.4.2 → 2.4.4

package/server/lib/orchestration/prompt-builder.test.js

@@ -0,0 +1,200 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { createRequire } from 'module';
+import { describe, it, expect, afterEach } from 'vitest';
+
+const require = createRequire(import.meta.url);
+
+const { packagePrompt } = require('../prompt-packager.js');
+const { buildTaskPrompt, buildContextPrompt, buildFullPrompt } = require('./prompt-builder.js');
+
+const tempDirs = [];
+
+function makeTempProject() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'tlc-prompt-builder-'));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  while (tempDirs.length > 0) {
+    fs.rmSync(tempDirs.pop(), { recursive: true, force: true });
+  }
+});
+
+describe('prompt-builder', () => {
+  describe('buildTaskPrompt', () => {
+    it('matches the existing dispatcher prompt format and includes TDD instructions', () => {
+      const result = buildTaskPrompt({
+        goal: 'Implement login',
+        files: ['src/login.js', 'src/login.test.js'],
+        criteria: ['Supports valid credentials', 'Rejects bad passwords'],
+        testCases: ['logs in a valid user', 'rejects an invalid user'],
+      });
+
+      expect(result).toBe([
+        'Goal: Implement login',
+        '',
+        'Files to work with:',
+        '  - src/login.js',
+        '  - src/login.test.js',
+        '',
+        'Acceptance criteria:',
+        '  - Supports valid credentials',
+        '  - Rejects bad passwords',
+        '',
+        'Test cases:',
+        '  - logs in a valid user',
+        '  - rejects an invalid user',
+        '',
+        'Methodology: Write tests first (red → green → refactor). You MUST write the test before implementing any code. Test-first is required.',
+      ].join('\n'));
+    });
+
+    it('supports empty file, criteria, and test case lists', () => {
+      const result = buildTaskPrompt({ goal: 'Implement logout' });
+
+      expect(result).toContain('Goal: Implement logout');
+      expect(result).toContain('Files to work with:\n');
+      expect(result).toContain('Acceptance criteria:\n');
+      expect(result).toContain('Test cases:\n');
+      expect(result).toContain('Write tests first');
+    });
+  });
+
+  describe('buildContextPrompt', () => {
+    it('delegates to packagePrompt with the provided options', () => {
+      const input = {
+        agentPrompt: 'Do the task',
+        projectDoc: '# Project',
+        planDoc: '# Plan',
+        codingStandards: '# Standards',
+        files: [
+          { path: 'b.js', content: 'b' },
+          { path: 'a.js', content: 'a' },
+        ],
+        tokenBudget: 500,
+      };
+
+      expect(buildContextPrompt(input)).toBe(packagePrompt(input));
+    });
+  });
+
+  describe('buildFullPrompt', () => {
+    it('reads project docs and relevant files, then packages the full prompt', () => {
+      const projectDir = makeTempProject();
+      fs.mkdirSync(path.join(projectDir, '.planning', 'phases'), { recursive: true });
+      fs.writeFileSync(path.join(projectDir, 'PROJECT.md'), '# Project\nShip it');
+      fs.writeFileSync(path.join(projectDir, 'CODING-STANDARDS.md'), '# Standards\nWrite tests');
+      fs.writeFileSync(path.join(projectDir, '.planning', 'phases', '1-PLAN.md'), '# Phase 1\nDo it');
+      fs.mkdirSync(path.join(projectDir, 'src'), { recursive: true });
+      fs.writeFileSync(path.join(projectDir, 'src', 'feature.js'), 'module.exports = { feature: true };');
+      fs.writeFileSync(path.join(projectDir, 'src', 'feature.test.js'), 'test("feature", () => {});');
+
+      const result = buildFullPrompt({
+        task: {
+          goal: 'Build feature',
+          files: ['src/feature.js', 'src/feature.test.js'],
+          criteria: ['Feature works'],
+          testCases: ['Feature passes'],
+        },
+        projectDir,
+        phase: 1,
+      });
+
+      expect(result).toContain('--- Task ---');
+      expect(result).toContain('Goal: Build feature');
+      expect(result).toContain('--- PROJECT.md ---');
+      expect(result).toContain('# Project\nShip it');
+      expect(result).toContain('--- Current Phase Plan ---');
+      expect(result).toContain('# Phase 1\nDo it');
+      expect(result).toContain('--- Coding Standards ---');
+      expect(result).toContain('# Standards\nWrite tests');
+      expect(result).toContain('--- src/feature.js ---');
+      expect(result).toContain('module.exports = { feature: true };');
+      expect(result).toContain('--- src/feature.test.js ---');
+    });
+
+    it('resolves padded or prefixed phase plan filenames', () => {
+      const projectDir = makeTempProject();
+      fs.mkdirSync(path.join(projectDir, '.planning', 'phases'), { recursive: true });
+      fs.writeFileSync(path.join(projectDir, 'PROJECT.md'), '# Project');
+      fs.writeFileSync(path.join(projectDir, 'CODING-STANDARDS.md'), '# Standards');
+      fs.writeFileSync(path.join(projectDir, '.planning', 'phases', '02-api-PLAN.md'), '# Phase 2');
+
+      const result = buildFullPrompt({
+        task: { goal: 'Build API' },
+        projectDir,
+        phase: 2,
+      });
+
+      expect(result).toContain('--- Current Phase Plan ---');
+      expect(result).toContain('# Phase 2');
+    });
+
+    it('skips missing docs and missing task files instead of throwing', () => {
+      const projectDir = makeTempProject();
+
+      const result = buildFullPrompt({
+        task: {
+          goal: 'Build minimal task',
+          files: ['missing.js'],
+        },
+        projectDir,
+        phase: 3,
+      });
+
+      expect(result).toContain('--- Task ---');
+      expect(result).toContain('Goal: Build minimal task');
+      expect(result).not.toContain('--- PROJECT.md ---');
+      expect(result).not.toContain('--- Current Phase Plan ---');
+      expect(result).not.toContain('--- Coding Standards ---');
+      expect(result).not.toContain('--- Relevant Files ---');
+    });
+
+    it('supports injected fs implementations', () => {
+      const fakeFs = {
+        existsSync(targetPath) {
+          return [
+            '/project/PROJECT.md',
+            '/project/CODING-STANDARDS.md',
+            '/project/.planning/phases',
+            '/project/.planning/phases/4-build-PLAN.md',
+            '/project/src/app.js',
+          ].includes(targetPath);
+        },
+        readdirSync(targetPath) {
+          if (targetPath === '/project/.planning/phases') {
+            return ['4-build-PLAN.md'];
+          }
+          return [];
+        },
+        readFileSync(targetPath) {
+          const contents = {
+            '/project/PROJECT.md': '# Project',
+            '/project/CODING-STANDARDS.md': '# Standards',
+            '/project/.planning/phases/4-build-PLAN.md': '# Phase 4',
+            '/project/src/app.js': 'console.log("app");',
+          };
+          return contents[targetPath];
+        },
+      };
+
+      const result = buildFullPrompt({
+        task: {
+          goal: 'Build app',
+          files: ['src/app.js'],
+        },
+        projectDir: '/project',
+        phase: 4,
+        fs: fakeFs,
+      });
+
+      expect(result).toContain('# Project');
+      expect(result).toContain('# Standards');
+      expect(result).toContain('# Phase 4');
+      expect(result).toContain('--- src/app.js ---');
+    });
+  });
+});

package/server/lib/orchestration/standalone-compat.js

@@ -0,0 +1,39 @@
+const path = require('path');
+
+function guessProvider(binary) {
+  const basename = path.basename(String(binary || '')).toLowerCase();
+
+  if (['codex', 'claude', 'gemini', 'ollama'].includes(basename)) {
+    return basename;
+  }
+
+  return basename;
+}
+
+async function executeCli(prompt, endpoint, options = {}) {
+  const { dispatch } = require('./cli-dispatch');
+  const provider = guessProvider(endpoint && endpoint.binary);
+  const result = await dispatch({
+    ...options,
+    prompt,
+    provider,
+    // Preserve the original binary path so custom/absolute paths still work
+    binaryOverride: endpoint && endpoint.binary,
+    flags: Array.isArray(endpoint && endpoint.cli_flags) ? endpoint.cli_flags : [],
+  });
+
+  return {
+    response: result.stdout,
+    provider: endpoint && endpoint.name,
+    latency_ms: result.duration,
+  };
+}
+
+function buildTaskPrompt(task) {
+  return require('./prompt-builder').buildTaskPrompt(task);
+}
+
+module.exports = {
+  executeCli,
+  buildTaskPrompt,
+};

package/server/lib/orchestration/standalone-compat.test.js

@@ -0,0 +1,144 @@
+import path from 'path';
+import { describe, it, expect, vi, afterEach } from 'vitest';
+
+const cliDispatch = require('./cli-dispatch.js');
+const promptBuilder = require('./prompt-builder.js');
+const { executeCli, buildTaskPrompt } = require('./standalone-compat.js');
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('standalone-compat', () => {
+  describe('executeCli', () => {
+    it('delegates to cli-dispatch with provider guessed from codex binary', async () => {
+      const dispatchSpy = vi.spyOn(cliDispatch, 'dispatch').mockResolvedValue({
+        stdout: 'ok',
+        duration: 42,
+      });
+
+      await executeCli(
+        'Ship it',
+        {
+          binary: 'codex',
+          cli_flags: ['--model', 'gpt-5.4'],
+          name: 'Codex CLI',
+        },
+        {
+          timeout: 5000,
+          worktreePath: '/tmp/worktree',
+        }
+      );
+
+      expect(dispatchSpy).toHaveBeenCalledWith({
+        prompt: 'Ship it',
+        provider: 'codex',
+        binaryOverride: 'codex',
+        flags: ['--model', 'gpt-5.4'],
+        timeout: 5000,
+        worktreePath: '/tmp/worktree',
+      });
+    });
+
+    it('guesses provider from the binary basename for known CLIs', async () => {
+      const dispatchSpy = vi.spyOn(cliDispatch, 'dispatch').mockResolvedValue({
+        stdout: 'done',
+        duration: 12,
+      });
+
+      await executeCli('Review this', {
+        binary: path.join('/usr', 'local', 'bin', 'claude'),
+        cli_flags: ['--permission-mode', 'auto'],
+        name: 'Claude Desktop',
+      });
+
+      expect(dispatchSpy).toHaveBeenCalledWith({
+        prompt: 'Review this',
+        provider: 'claude',
+        binaryOverride: path.join('/usr', 'local', 'bin', 'claude'),
+        flags: ['--permission-mode', 'auto'],
+      });
+    });
+
+    it('passes through empty flags when cli_flags is not provided', async () => {
+      const dispatchSpy = vi.spyOn(cliDispatch, 'dispatch').mockResolvedValue({
+        stdout: 'done',
+        duration: 7,
+      });
+
+      await executeCli('Run', {
+        binary: 'gemini',
+        name: 'Gemini CLI',
+      });
+
+      expect(dispatchSpy).toHaveBeenCalledWith({
+        prompt: 'Run',
+        provider: 'gemini',
+        binaryOverride: 'gemini',
+        flags: [],
+      });
+    });
+
+    it('falls back to the binary basename for unknown providers and reshapes the result', async () => {
+      vi.spyOn(cliDispatch, 'dispatch').mockResolvedValue({
+        stdout: 'custom output',
+        duration: 88,
+      });
+
+      const result = await executeCli('Custom task', {
+        binary: '/opt/tools/custom-runner',
+        cli_flags: ['--fast'],
+        name: 'Standalone Custom',
+      });
+
+      expect(result).toEqual({
+        response: 'custom output',
+        provider: 'Standalone Custom',
+        latency_ms: 88,
+      });
+    });
+
+    it('lets explicit options like spawn pass through unchanged', async () => {
+      const spawn = vi.fn();
+      const dispatchSpy = vi.spyOn(cliDispatch, 'dispatch').mockResolvedValue({
+        stdout: 'ok',
+        duration: 3,
+      });
+
+      await executeCli(
+        'Test',
+        {
+          binary: 'ollama',
+          cli_flags: ['llama3.2'],
+          name: 'Ollama',
+        },
+        { spawn }
+      );
+
+      expect(dispatchSpy).toHaveBeenCalledWith({
+        prompt: 'Test',
+        provider: 'ollama',
+        binaryOverride: 'ollama',
+        flags: ['llama3.2'],
+        spawn,
+      });
+    });
+  });
+
+  describe('buildTaskPrompt', () => {
+    it('delegates directly to prompt-builder and returns its string', () => {
+      const task = {
+        goal: 'Implement feature',
+        files: ['src/feature.js'],
+        criteria: ['It works'],
+        testCases: ['passes tests'],
+      };
+      const buildSpy = vi.spyOn(promptBuilder, 'buildTaskPrompt').mockReturnValue('prompt text');
+
+      const result = buildTaskPrompt(task);
+
+      expect(buildSpy).toHaveBeenCalledWith(task);
+      expect(result).toBe('prompt text');
+    });
+  });
+});

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

@@ -16,6 +16,26 @@ export function sanitizeName(name) {
     .replace(/-{2,}/g, '-');
 }
 
+/**
+ * Build a short, stable task slug from a task name.
+ * Uses the first 4 words, lowercases, hyphenates, and limits to 30 chars.
+ * @param {string} taskName
+ * @returns {string}
+ */
+export function sanitizeTaskName(taskName) {
+  const words = String(taskName)
+    .trim()
+    .toLowerCase()
+    .split(/\s+/)
+    .filter(Boolean)
+    .slice(0, 4);
+
+  const truncated = words.join('-').slice(0, 30);
+  return sanitizeName(truncated)
+    .replace(/^-+|-+$/g, '')
+    .replace(/-{2,}/g, '-');
+}
+
 /**
  * Create a git worktree for the given name.
  * @param {string} name - Worktree name (will be sanitized)
@@ -47,6 +67,29 @@ export function createWorktree(name, { exec, maxConcurrent } = {}) {
   return { name: safe, branch, path };
 }
 
+/**
+ * Create a git worktree named for a phase/task combination.
+ * @param {number|string} phase
+ * @param {number|string} taskNumber
+ * @param {string} taskName
+ * @param {{ exec: Function, baseBranch?: string }} options
+ * @returns {{ name: string, branch: string, path: string }}
+ */
+export function createTaskWorktree(phase, taskNumber, taskName, { exec, baseBranch } = {}) {
+  const taskSlug = sanitizeTaskName(taskName);
+  const rawName = taskSlug
+    ? `phase-${phase}-task-${taskNumber}-${taskSlug}`
+    : `phase-${phase}-task-${taskNumber}`;
+  const name = sanitizeName(rawName);
+  const branch = `worktree-${name}`;
+  const path = `.claude/worktrees/${name}`;
+  const startPoint = baseBranch || exec('git branch --show-current').trim();
+
+  exec(`git worktree add -b ${branch} ${path} ${startPoint}`);
+
+  return { name, branch, path };
+}
+
 /**
  * List active worktrees under .claude/worktrees/.
  * @param {{ exec: Function }} options

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

@@ -1,6 +1,7 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import {
   createWorktree,
+  createTaskWorktree,
   listWorktrees,
   mergeWorktree,
   removeWorktree,
@@ -58,6 +59,55 @@ describe('worktree-manager', () => {
     });
   });
 
+  describe('createTaskWorktree', () => {
+    it('builds a phase/task-based worktree name', () => {
+      exec.mockImplementation((cmd) => {
+        if (cmd === 'git branch --show-current') return 'feature/current\n';
+        return '';
+      });
+
+      const result = createTaskWorktree(30, 5, 'Config Size', { exec });
+
+      expect(result).toEqual({
+        name: 'phase-30-task-5-config-size',
+        branch: 'worktree-phase-30-task-5-config-size',
+        path: '.claude/worktrees/phase-30-task-5-config-size',
+      });
+      expect(exec).toHaveBeenCalledWith(
+        'git worktree add -b worktree-phase-30-task-5-config-size .claude/worktrees/phase-30-task-5-config-size feature/current'
+      );
+    });
+
+    it('sanitizes task name to first four words and max 30 chars', () => {
+      exec.mockImplementation((cmd) => {
+        if (cmd === 'git branch --show-current') return 'main\n';
+        return '';
+      });
+
+      const result = createTaskWorktree(
+        12,
+        9,
+        'Configuration synchronization validation instrumentation extra trailing words',
+        { exec }
+      );
+
+      expect(result.name).toBe('phase-12-task-9-configuration-synchronization');
+      expect(result.branch).toBe('worktree-phase-12-task-9-configuration-synchronization');
+    });
+
+    it('uses a provided base branch instead of the current branch', () => {
+      exec.mockReturnValue('');
+
+      const result = createTaskWorktree(7, 2, 'Ship Metrics', { exec, baseBranch: 'release/7' });
+
+      expect(result.name).toBe('phase-7-task-2-ship-metrics');
+      expect(exec).toHaveBeenCalledTimes(1);
+      expect(exec).toHaveBeenCalledWith(
+        'git worktree add -b worktree-phase-7-task-2-ship-metrics .claude/worktrees/phase-7-task-2-ship-metrics release/7'
+      );
+    });
+  });
+
   describe('listWorktrees', () => {
     it('returns active worktrees with branch and path', () => {
       exec.mockReturnValue(

package/server/lib/router-config.js

@@ -20,6 +20,10 @@ export const defaultConfig = {
   devserver: { url: null, queue: { maxConcurrent: 3, timeout: 120000 } },
 };
 
+function isMissingConfigError(error) {
+  return error?.code === 'ENOENT' || error?.message?.includes('ENOENT');
+}
+
 export async function loadRouterConfig(options = {}) {
   try {
     let content;
@@ -38,7 +42,13 @@ export async function loadRouterConfig(options = {}) {
       capabilities: { ...defaultConfig.capabilities, ...routerConfig.capabilities },
       devserver: { ...defaultConfig.devserver, ...routerConfig.devserver },
     };
-  } catch {
+  } catch (error) {
+    if (!isMissingConfigError(error)) {
+      const message = error instanceof SyntaxError
+        ? 'Failed to parse .tlc.json router config; using defaults'
+        : `Failed to load .tlc.json router config; using defaults (${error?.message || 'unknown error'})`;
+      console.warn(`[TLC WARNING] ${message}`);
+    }
     return { ...defaultConfig };
   }
 }
@@ -75,8 +85,13 @@ export async function saveRouterConfig(config, options = {}) {
   try {
     const content = await readFile(configPath, 'utf-8');
     existing = JSON.parse(content);
-  } catch {
-    // New file
+  } catch (error) {
+    if (!isMissingConfigError(error)) {
+      const message = error instanceof SyntaxError
+        ? 'Failed to parse existing .tlc.json router config; overwriting router section'
+        : `Failed to load existing .tlc.json router config; overwriting router section (${error?.message || 'unknown error'})`;
+      console.warn(`[TLC WARNING] ${message}`);
+    }
   }
 
   existing.router = config;

package/server/lib/router-config.test.js

@@ -1,4 +1,7 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { mkdtemp, rm, writeFile } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
 import {
   loadRouterConfig,
   validateConfig,
@@ -9,6 +12,13 @@ import {
 } from './router-config.js';
 
 describe('Router Config', () => {
+  const originalCwd = process.cwd();
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    process.chdir(originalCwd);
+  });
+
   describe('loadRouterConfig', () => {
     it('reads from .tlc.json', async () => {
       const config = await loadRouterConfig({ _readFile: vi.fn().mockResolvedValue(JSON.stringify({
@@ -28,6 +38,32 @@ describe('Router Config', () => {
       const config = await loadRouterConfig({ _readFile: vi.fn().mockResolvedValue('{}') });
       expect(config.providers).toBeDefined();
     });
+
+    it('warns when router config JSON is invalid', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      const config = await loadRouterConfig({
+        _readFile: vi.fn().mockResolvedValue('{invalid json'),
+      });
+
+      expect(config).toEqual({ ...defaultConfig });
+      expect(warnSpy).toHaveBeenCalledWith(
+        '[TLC WARNING] Failed to parse .tlc.json router config; using defaults'
+      );
+    });
+
+    it('stays silent when router config file is missing', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const error = new Error('ENOENT');
+      error.code = 'ENOENT';
+
+      const config = await loadRouterConfig({
+        _readFile: vi.fn().mockRejectedValue(error),
+      });
+
+      expect(config).toEqual({ ...defaultConfig });
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
   });
 
   describe('validateConfig', () => {
@@ -79,5 +115,25 @@ describe('Router Config', () => {
       await saveRouterConfig({ providers: {} }, { _writeFile: writeFile });
       expect(writeFile).toHaveBeenCalled();
     });
+
+    it('warns when existing router config JSON is invalid', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const tempDir = await mkdtemp(join(tmpdir(), 'router-config-test-'));
+      await writeFile(join(tempDir, '.tlc.json'), '{invalid json');
+      process.chdir(tempDir);
+
+      await saveRouterConfig(
+        { providers: {} },
+        {
+          _writeFile: vi.fn().mockResolvedValue(undefined),
+        },
+      );
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        '[TLC WARNING] Failed to parse existing .tlc.json router config; overwriting router section'
+      );
+
+      await rm(tempDir, { recursive: true, force: true });
+    });
   });
 });

package/server/lib/routing/index.js

@@ -0,0 +1,34 @@
+const {
+  resolveRouting,
+  loadPersonalConfig,
+  loadProjectOverride,
+  SHIPPED_DEFAULTS,
+  ROUTABLE_COMMANDS,
+} = require('../task-router-config.js');
+const { dispatch, buildProviderCommand } = require('../cli-dispatcher.js');
+const { routeCommand } = require('../command-router.js');
+const {
+  showRouting,
+  showProviders,
+  savePersonalRouting,
+  formatRoutingTable,
+  formatProviderList,
+} = require('../routing-command.js');
+const { generatePreamble } = require('../routing-preamble.js');
+
+module.exports = {
+  resolveRouting,
+  loadPersonalConfig,
+  loadProjectOverride,
+  SHIPPED_DEFAULTS,
+  ROUTABLE_COMMANDS,
+  dispatch,
+  buildProviderCommand,
+  routeCommand,
+  showRouting,
+  showProviders,
+  savePersonalRouting,
+  formatRoutingTable,
+  formatProviderList,
+  generatePreamble,
+};