tlc-claude-code 2.3.0 → 2.4.1

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

@@ -0,0 +1,336 @@
+import { describe, it, expect, vi } from 'vitest';
+import { routeCommand } from './command-router.js';
+
+/**
+ * Create default mock dependencies for routeCommand.
+ * @param {Object} overrides - Override individual deps
+ * @returns {Object} Deps object with all mocks
+ */
+function createMockDeps(overrides = {}) {
+  return {
+    resolveRouting: vi.fn(() => ({
+      models: ['claude'],
+      strategy: 'single',
+      source: 'shipped-defaults',
+    })),
+    packagePrompt: vi.fn(() => 'packaged-prompt-text'),
+    dispatch: vi.fn(async () => ({
+      stdout: 'cli output',
+      stderr: '',
+      exitCode: 0,
+      duration: 500,
+    })),
+    readRouterState: vi.fn(() => ({
+      providers: {
+        claude: { available: true, path: '/opt/homebrew/bin/claude' },
+        codex: { available: true, path: '/opt/homebrew/bin/codex' },
+        gemini: { available: false, path: '' },
+      },
+    })),
+    ...overrides,
+  };
+}
+
+describe('command-router', () => {
+  describe('routeCommand', () => {
+    it('routes to inline when model is claude', async () => {
+      const deps = createMockDeps();
+
+      const result = await routeCommand({
+        command: 'build',
+        agentPrompt: 'Build the feature',
+        flagModel: null,
+        context: { projectDoc: null, planDoc: null, codingStandards: null, files: null },
+      }, deps);
+
+      expect(result).toEqual({ type: 'inline', model: 'claude' });
+      expect(deps.resolveRouting).toHaveBeenCalledWith(expect.objectContaining({ command: 'build' }));
+    });
+
+    it('routes to CLI dispatch when model is codex', async () => {
+      const deps = createMockDeps({
+        resolveRouting: vi.fn(() => ({
+          models: ['codex'],
+          strategy: 'single',
+          source: 'personal-config',
+          providers: {
+            codex: { type: 'cli', command: 'codex', flags: ['--quiet'] },
+          },
+        })),
+      });
+
+      const result = await routeCommand({
+        command: 'review',
+        agentPrompt: 'Review the code',
+        flagModel: null,
+        context: { projectDoc: 'My Project', planDoc: null, codingStandards: null, files: null },
+      }, deps);
+
+      expect(result.type).toBe('cli');
+      expect(result.model).toBe('codex');
+      expect(result.output).toBe('cli output');
+      expect(result.exitCode).toBe(0);
+      expect(result.duration).toBe(500);
+      expect(deps.packagePrompt).toHaveBeenCalled();
+      expect(deps.dispatch).toHaveBeenCalled();
+    });
+
+    it('parallel strategy returns both inline and CLI results', async () => {
+      const deps = createMockDeps({
+        resolveRouting: vi.fn(() => ({
+          models: ['claude', 'codex'],
+          strategy: 'parallel',
+          source: 'project-override',
+          providers: {
+            codex: { type: 'cli', command: 'codex', flags: [] },
+          },
+        })),
+        dispatch: vi.fn(async () => ({
+          stdout: 'codex says hello',
+          stderr: '',
+          exitCode: 0,
+          duration: 800,
+        })),
+      });
+
+      const result = await routeCommand({
+        command: 'build',
+        agentPrompt: 'Build it',
+        flagModel: null,
+        context: { projectDoc: null, planDoc: null, codingStandards: null, files: null },
+      }, deps);
+
+      expect(result.type).toBe('parallel');
+      expect(result.results).toHaveLength(2);
+
+      const claudeResult = result.results.find(r => r.model === 'claude');
+      const codexResult = result.results.find(r => r.model === 'codex');
+      expect(claudeResult).toEqual({ model: 'claude', type: 'inline' });
+      expect(codexResult.type).toBe('cli');
+      expect(codexResult.model).toBe('codex');
+      expect(codexResult.output).toBe('codex says hello');
+    });
+
+    it('unavailable provider falls back to inline with warning', async () => {
+      const deps = createMockDeps({
+        resolveRouting: vi.fn(() => ({
+          models: ['gemini'],
+          strategy: 'single',
+          source: 'personal-config',
+          // No provider config — truly unknown model
+        })),
+        readRouterState: vi.fn(() => ({
+          providers: {
+            claude: { available: true },
+          },
+        })),
+      });
+
+      const result = await routeCommand({
+        command: 'review',
+        agentPrompt: 'Review this',
+        flagModel: null,
+        context: { projectDoc: null, planDoc: null, codingStandards: null, files: null },
+      }, deps);
+
+      expect(result.type).toBe('inline');
+      expect(result.model).toBe('claude');
+      expect(result.warning).toMatch(/gemini/i);
+    });
+
+    it('flag override routes to specified model', async () => {
+      const deps = createMockDeps({
+        resolveRouting: vi.fn(() => ({
+          models: ['codex'],
+          strategy: 'single',
+          source: 'flag-override',
+          providers: {
+            codex: { type: 'cli', command: 'codex', flags: ['--quiet'] },
+          },
+        })),
+      });
+
+      const result = await routeCommand({
+        command: 'build',
+        agentPrompt: 'Build it',
+        flagModel: 'codex',
+        context: { projectDoc: null, planDoc: null, codingStandards: null, files: null },
+      }, deps);
+
+      expect(result.type).toBe('cli');
+      expect(result.model).toBe('codex');
+      expect(deps.resolveRouting).toHaveBeenCalledWith(expect.objectContaining({
+        flagModel: 'codex',
+      }));
+    });
+
+    it('packages prompt with all context fields', async () => {
+      const context = {
+        projectDoc: 'Project doc content',
+        planDoc: 'Plan doc content',
+        codingStandards: 'Standards content',
+        files: [{ path: 'src/app.js', content: 'const x = 1;' }],
+      };
+
+      const deps = createMockDeps({
+        resolveRouting: vi.fn(() => ({
+          models: ['codex'],
+          strategy: 'single',
+          source: 'personal-config',
+          providers: {
+            codex: { type: 'cli', command: 'codex', flags: [] },
+          },
+        })),
+      });
+
+      await routeCommand({
+        command: 'build',
+        agentPrompt: 'Build the feature',
+        flagModel: null,
+        context,
+      }, deps);
+
+      expect(deps.packagePrompt).toHaveBeenCalledWith(expect.objectContaining({
+        agentPrompt: 'Build the feature',
+        projectDoc: 'Project doc content',
+        planDoc: 'Plan doc content',
+        codingStandards: 'Standards content',
+        files: [{ path: 'src/app.js', content: 'const x = 1;' }],
+      }));
+    });
+
+    it('CLI dispatch timeout handled gracefully', async () => {
+      const deps = createMockDeps({
+        resolveRouting: vi.fn(() => ({
+          models: ['codex'],
+          strategy: 'single',
+          source: 'personal-config',
+          providers: {
+            codex: { type: 'cli', command: 'codex', flags: [] },
+          },
+        })),
+        dispatch: vi.fn(async () => ({
+          stdout: '',
+          stderr: 'Process timed out',
+          exitCode: -1,
+          duration: 120000,
+        })),
+      });
+
+      const result = await routeCommand({
+        command: 'build',
+        agentPrompt: 'Build it',
+        flagModel: null,
+        context: { projectDoc: null, planDoc: null, codingStandards: null, files: null },
+      }, deps);
+
+      expect(result.type).toBe('cli');
+      expect(result.model).toBe('codex');
+      expect(result.exitCode).toBe(-1);
+      expect(result.output).toBe('');
+    });
+
+    it('non-zero exit code from CLI captured in result', async () => {
+      const deps = createMockDeps({
+        resolveRouting: vi.fn(() => ({
+          models: ['codex'],
+          strategy: 'single',
+          source: 'personal-config',
+          providers: {
+            codex: { type: 'cli', command: 'codex', flags: [] },
+          },
+        })),
+        dispatch: vi.fn(async () => ({
+          stdout: 'partial output',
+          stderr: 'error occurred',
+          exitCode: 1,
+          duration: 300,
+        })),
+      });
+
+      const result = await routeCommand({
+        command: 'build',
+        agentPrompt: 'Build it',
+        flagModel: null,
+        context: { projectDoc: null, planDoc: null, codingStandards: null, files: null },
+      }, deps);
+
+      expect(result.type).toBe('cli');
+      expect(result.exitCode).toBe(1);
+      expect(result.output).toBe('partial output');
+    });
+
+    it('unknown model falls back to inline', async () => {
+      const deps = createMockDeps({
+        resolveRouting: vi.fn(() => ({
+          models: ['unknown-model'],
+          strategy: 'single',
+          source: 'flag-override',
+        })),
+        readRouterState: vi.fn(() => ({
+          providers: {
+            claude: { available: true, path: '/opt/homebrew/bin/claude' },
+          },
+        })),
+      });
+
+      const result = await routeCommand({
+        command: 'build',
+        agentPrompt: 'Build it',
+        flagModel: 'unknown-model',
+        context: { projectDoc: null, planDoc: null, codingStandards: null, files: null },
+      }, deps);
+
+      expect(result.type).toBe('inline');
+      expect(result.model).toBe('claude');
+      expect(result.warning).toMatch(/unknown-model/i);
+    });
+
+    it('parallel with one unavailable provider still runs available ones', async () => {
+      const deps = createMockDeps({
+        resolveRouting: vi.fn(() => ({
+          models: ['claude', 'codex', 'gemini'],
+          strategy: 'parallel',
+          source: 'project-override',
+          providers: {
+            codex: { type: 'cli', command: 'codex', flags: [] },
+            // gemini has no provider config — truly unavailable
+          },
+        })),
+        readRouterState: vi.fn(() => ({
+          providers: {
+            claude: { available: true },
+            codex: { available: true },
+            // gemini not in router state either
+          },
+        })),
+        dispatch: vi.fn(async () => ({
+          stdout: 'codex output',
+          stderr: '',
+          exitCode: 0,
+          duration: 400,
+        })),
+      });
+
+      const result = await routeCommand({
+        command: 'build',
+        agentPrompt: 'Build it',
+        flagModel: null,
+        context: { projectDoc: null, planDoc: null, codingStandards: null, files: null },
+      }, deps);
+
+      expect(result.type).toBe('parallel');
+      expect(result.results).toHaveLength(3);
+
+      const [claudeResult, codexResult, geminiResult] = result.results;
+
+      expect(claudeResult).toEqual({ model: 'claude', type: 'inline' });
+      expect(codexResult.type).toBe('cli');
+      expect(codexResult.model).toBe('codex');
+      // Gemini is unavailable — skipped (not duplicate Claude)
+      expect(geminiResult.type).toBe('skipped');
+      expect(geminiResult.model).toBe('gemini');
+      expect(geminiResult.warning).toMatch(/gemini/i);
+    });
+  });
+});

package/server/lib/prompt-packager.js

@@ -0,0 +1,98 @@
+/**
+ * Prompt Packager Module
+ * Serializes project context into a single prompt string for CLI dispatch to external LLMs.
+ */
+
+const DEFAULT_TOKEN_BUDGET = 100000;
+const TRUNCATION_MARKER = '...';
+
+/**
+ * Format a source file as a labeled block for inclusion in the prompt.
+ * @param {string} filePath - Relative path to the file
+ * @param {string} content - File contents
+ * @returns {string} Formatted block with path header
+ */
+function formatFileBlock(filePath, content) {
+  return `--- ${filePath} ---\n${content}`;
+}
+
+/**
+ * Truncate text to fit within a character budget.
+ * When truncation is needed, cuts at a character boundary and appends an ellipsis marker.
+ * @param {string} text - The text to truncate
+ * @param {number} budget - Maximum character count
+ * @returns {string} The text, truncated if necessary
+ */
+function truncateToBudget(text, budget) {
+  if (budget <= 0) return '';
+  if (text.length <= budget) return text;
+  const cutLen = budget - TRUNCATION_MARKER.length;
+  if (cutLen <= 0) return text.slice(0, budget);
+  return text.slice(0, cutLen) + TRUNCATION_MARKER;
+}
+
+/**
+ * Package project context and an agent prompt into a single string for external LLM dispatch.
+ * @param {object} opts
+ * @param {string} opts.agentPrompt - The command's instruction text (required)
+ * @param {string|null} [opts.projectDoc] - Contents of PROJECT.md
+ * @param {string|null} [opts.planDoc] - Contents of current phase PLAN.md
+ * @param {string|null} [opts.codingStandards] - Contents of CODING-STANDARDS.md
+ * @param {Array<{path: string, content: string}>|null} [opts.files] - Relevant source files
+ * @param {number} [opts.tokenBudget=100000] - Maximum characters in output
+ * @returns {string} Serialized prompt string
+ */
+function packagePrompt({
+  agentPrompt,
+  projectDoc = null,
+  planDoc = null,
+  codingStandards = null,
+  files = null,
+  tokenBudget = DEFAULT_TOKEN_BUDGET,
+}) {
+  if (tokenBudget <= 0) return '';
+
+  // Pre-truncate large individual file contents to a per-file budget.
+  // Each file gets at most half the total budget to leave room for other sections.
+  const perFileBudget = Math.floor(tokenBudget / 2);
+  const sortedFiles =
+    files && files.length > 0
+      ? [...files]
+          .sort((a, b) => a.path.localeCompare(b.path))
+          .map((f) => ({
+            path: f.path,
+            content: truncateToBudget(f.content, perFileBudget),
+          }))
+      : null;
+
+  // Task section goes FIRST so truncation of context never drops the instruction
+  const sections = [];
+
+  sections.push(`--- Task ---\n${agentPrompt}`);
+
+  sections.push('\nYou are working on the following project:');
+
+  if (projectDoc != null) {
+    sections.push(`\n--- PROJECT.md ---\n${projectDoc}`);
+  }
+
+  if (planDoc != null) {
+    sections.push(`\n--- Current Phase Plan ---\n${planDoc}`);
+  }
+
+  if (codingStandards != null) {
+    sections.push(`\n--- Coding Standards ---\n${codingStandards}`);
+  }
+
+  if (sortedFiles && sortedFiles.length > 0) {
+    const fileBlocks = sortedFiles
+      .map((f) => formatFileBlock(f.path, f.content))
+      .join('\n\n');
+    sections.push(`\n--- Relevant Files ---\n\n${fileBlocks}`);
+  }
+
+  const full = sections.join('\n');
+  return truncateToBudget(full, tokenBudget);
+}
+
+module.exports = { packagePrompt, truncateToBudget, formatFileBlock };

package/server/lib/prompt-packager.test.js

@@ -0,0 +1,185 @@
+import { describe, it, expect } from 'vitest';
+import {
+  packagePrompt,
+  truncateToBudget,
+  formatFileBlock,
+} from './prompt-packager.js';
+
+describe('prompt-packager', () => {
+  describe('formatFileBlock', () => {
+    it('produces correct header format', () => {
+      const result = formatFileBlock('src/auth/login.ts', 'const x = 1;');
+      expect(result).toBe('--- src/auth/login.ts ---\nconst x = 1;');
+    });
+
+    it('handles empty content', () => {
+      const result = formatFileBlock('empty.js', '');
+      expect(result).toBe('--- empty.js ---\n');
+    });
+  });
+
+  describe('truncateToBudget', () => {
+    it('returns text unchanged when within budget', () => {
+      const text = 'Hello world';
+      expect(truncateToBudget(text, 100)).toBe(text);
+    });
+
+    it('truncates at char boundary with ellipsis marker', () => {
+      const text = 'abcdefghij'; // 10 chars
+      const result = truncateToBudget(text, 8);
+      expect(result.length).toBeLessThanOrEqual(8);
+      expect(result).toContain('...');
+    });
+
+    it('returns empty string for budget of 0', () => {
+      expect(truncateToBudget('anything', 0)).toBe('');
+    });
+
+    it('handles text exactly at budget', () => {
+      const text = 'exact';
+      expect(truncateToBudget(text, 5)).toBe('exact');
+    });
+
+    it('handles empty text', () => {
+      expect(truncateToBudget('', 100)).toBe('');
+    });
+  });
+
+  describe('packagePrompt', () => {
+    const fullInput = {
+      agentPrompt: 'Implement the login feature',
+      projectDoc: '# My Project\nA cool project.',
+      planDoc: '## Phase 1\n- [ ] Task 1',
+      codingStandards: '## Standards\nUse JSDoc.',
+      files: [
+        { path: 'src/auth/login.ts', content: 'export function login() {}' },
+        { path: 'tests/auth/login.test.ts', content: 'test("login", () => {})' },
+      ],
+    };
+
+    it('packages all sections when everything provided', () => {
+      const result = packagePrompt(fullInput);
+      expect(result).toContain('You are working on the following project:');
+      expect(result).toContain('--- PROJECT.md ---');
+      expect(result).toContain('# My Project');
+      expect(result).toContain('--- Current Phase Plan ---');
+      expect(result).toContain('## Phase 1');
+      expect(result).toContain('--- Coding Standards ---');
+      expect(result).toContain('## Standards');
+      expect(result).toContain('--- Relevant Files ---');
+      expect(result).toContain('--- src/auth/login.ts ---');
+      expect(result).toContain('export function login() {}');
+      expect(result).toContain('--- tests/auth/login.test.ts ---');
+      expect(result).toContain('test("login", () => {})');
+      expect(result).toContain('--- Task ---');
+      expect(result).toContain('Implement the login feature');
+    });
+
+    it('omits PROJECT.md section when null', () => {
+      const result = packagePrompt({ ...fullInput, projectDoc: null });
+      expect(result).not.toContain('--- PROJECT.md ---');
+      expect(result).toContain('--- Current Phase Plan ---');
+      expect(result).toContain('--- Task ---');
+    });
+
+    it('omits plan section when null', () => {
+      const result = packagePrompt({ ...fullInput, planDoc: null });
+      expect(result).not.toContain('--- Current Phase Plan ---');
+      expect(result).toContain('--- PROJECT.md ---');
+      expect(result).toContain('--- Task ---');
+    });
+
+    it('omits coding standards when null', () => {
+      const result = packagePrompt({ ...fullInput, codingStandards: null });
+      expect(result).not.toContain('--- Coding Standards ---');
+      expect(result).toContain('--- PROJECT.md ---');
+      expect(result).toContain('--- Task ---');
+    });
+
+    it('omits files section when null', () => {
+      const result = packagePrompt({ ...fullInput, files: null });
+      expect(result).not.toContain('--- Relevant Files ---');
+      expect(result).toContain('--- PROJECT.md ---');
+      expect(result).toContain('--- Task ---');
+    });
+
+    it('omits files section when empty array', () => {
+      const result = packagePrompt({ ...fullInput, files: [] });
+      expect(result).not.toContain('--- Relevant Files ---');
+      expect(result).toContain('--- Task ---');
+    });
+
+    it('empty agentPrompt still produces valid output', () => {
+      const result = packagePrompt({ ...fullInput, agentPrompt: '' });
+      expect(result).toContain('--- Task ---');
+      expect(result).toContain('--- PROJECT.md ---');
+    });
+
+    it('files sorted by path for deterministic output', () => {
+      const result = packagePrompt({
+        agentPrompt: 'do it',
+        files: [
+          { path: 'z/last.js', content: 'last' },
+          { path: 'a/first.js', content: 'first' },
+          { path: 'm/middle.js', content: 'middle' },
+        ],
+      });
+      const aIdx = result.indexOf('--- a/first.js ---');
+      const mIdx = result.indexOf('--- m/middle.js ---');
+      const zIdx = result.indexOf('--- z/last.js ---');
+      expect(aIdx).toBeLessThan(mIdx);
+      expect(mIdx).toBeLessThan(zIdx);
+    });
+
+    it('truncates to budget when total exceeds limit', () => {
+      const result = packagePrompt({
+        ...fullInput,
+        tokenBudget: 50,
+      });
+      expect(result.length).toBeLessThanOrEqual(50);
+    });
+
+    it('budget of 0 returns empty string', () => {
+      const result = packagePrompt({ ...fullInput, tokenBudget: 0 });
+      expect(result).toBe('');
+    });
+
+    it('large individual files truncated before total budget check', () => {
+      const largeContent = 'x'.repeat(200000);
+      const result = packagePrompt({
+        agentPrompt: 'task',
+        files: [{ path: 'big.js', content: largeContent }],
+        tokenBudget: 1000,
+      });
+      expect(result.length).toBeLessThanOrEqual(1000);
+      // The file should be present but truncated
+      expect(result).toContain('--- big.js ---');
+    });
+
+    it('places task section before context so truncation never drops the instruction', () => {
+      const result = packagePrompt(fullInput);
+      const taskIdx = result.indexOf('--- Task ---');
+      const projectIdx = result.indexOf('--- PROJECT.md ---');
+      expect(taskIdx).toBeLessThan(projectIdx);
+    });
+
+    it('uses default tokenBudget of 100000 when not specified', () => {
+      const largeProject = 'x'.repeat(200000);
+      const result = packagePrompt({
+        agentPrompt: 'task',
+        projectDoc: largeProject,
+      });
+      expect(result.length).toBeLessThanOrEqual(100000);
+    });
+
+    it('handles minimal input with only agentPrompt', () => {
+      const result = packagePrompt({ agentPrompt: 'just do it' });
+      expect(result).toContain('--- Task ---');
+      expect(result).toContain('just do it');
+      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 ---');
+    });
+  });
+});