tlc-claude-code 2.2.1 → 2.4.0

package/server/lib/command-router.js

@@ -0,0 +1,171 @@
+/**
+ * Command Router
+ *
+ * Integration point for TLC command routing. Given a command name,
+ * resolves routing config, checks provider availability, packages
+ * prompts, and dispatches to the appropriate execution path.
+ *
+ * @module command-router
+ */
+
+const { buildProviderCommand } = require('./cli-dispatcher.js');
+
+/**
+ * Check whether a model is available in the router state.
+ * @param {string} model - Model name to check
+ * @param {Object} routerState - Parsed .tlc/.router-state.json
+ * @returns {boolean} True if the model's provider is available
+ */
+function isModelAvailable(model, routerState, providerConfig) {
+  if (model === 'claude') return true;
+  // Check router state (probed CLIs) first
+  const probed = routerState?.providers?.[model];
+  if (probed?.available === true) return true;
+  // Also accept user-defined provider aliases from model_providers config
+  if (providerConfig?.[model]?.type === 'cli') return true;
+  return false;
+}
+
+/**
+ * Route a single model to its result.
+ * @param {string} model - Model name
+ * @param {Object} opts - Routing options
+ * @param {string} opts.agentPrompt - Command instruction text
+ * @param {Object} opts.context - Project context
+ * @param {Object|undefined} opts.providerConfig - Provider config for CLI models
+ * @param {Object} opts.routerState - Router state from .router-state.json
+ * @param {Object} deps - Injected dependencies
+ * @returns {Promise<Object>} Result for this model
+ */
+async function routeModel(model, { agentPrompt, context, providerConfig, routerState }, deps) {
+  // Claude is always inline
+  if (model === 'claude') {
+    return { model: 'claude', type: 'inline' };
+  }
+
+  // Check availability — return skipped (not duplicate Claude) so parallel doesn't double-run
+  if (!isModelAvailable(model, routerState, providerConfig)) {
+    return {
+      type: 'skipped',
+      model,
+      warning: `${model} is unavailable`,
+    };
+  }
+
+  // Get provider command config
+  const provider = providerConfig?.[model];
+  if (!provider) {
+    return {
+      type: 'skipped',
+      model,
+      warning: `${model} has no provider config`,
+    };
+  }
+
+  const cmdSpec = buildProviderCommand(provider);
+  if (!cmdSpec) {
+    return {
+      type: 'skipped',
+      model,
+      warning: `${model} is not a CLI provider`,
+    };
+  }
+
+  // Package prompt with full context
+  const prompt = deps.packagePrompt({
+    agentPrompt,
+    projectDoc: context.projectDoc || null,
+    planDoc: context.planDoc || null,
+    codingStandards: context.codingStandards || null,
+    files: context.files || null,
+  });
+
+  // Dispatch to CLI
+  const dispatchResult = await deps.dispatch({
+    command: cmdSpec.command,
+    args: cmdSpec.args,
+    prompt,
+  });
+
+  return {
+    type: 'cli',
+    model,
+    output: dispatchResult.stdout,
+    stderr: dispatchResult.stderr,
+    exitCode: dispatchResult.exitCode,
+    duration: dispatchResult.duration,
+  };
+}
+
+/**
+ * Route a TLC command to the appropriate execution path.
+ * @param {Object} options
+ * @param {string} options.command - TLC command name (e.g., 'build', 'review')
+ * @param {string} options.agentPrompt - The command's instruction text
+ * @param {string|null} options.flagModel - --model flag override
+ * @param {Object} options.context - Project context for prompt packaging
+ * @param {string|null} options.context.projectDoc - PROJECT.md contents
+ * @param {string|null} options.context.planDoc - Current phase PLAN.md
+ * @param {string|null} options.context.codingStandards - CODING-STANDARDS.md
+ * @param {Array|null} options.context.files - [{path, content}]
+ * @param {Object} deps - Injected dependencies for testability
+ * @param {string} [options.projectDir] - Project directory for config loading
+ * @param {string} [options.homeDir] - Home directory for personal config
+ * @param {Object} deps - Injected dependencies for testability
+ * @param {Function} deps.resolveRouting - from task-router-config
+ * @param {Function} deps.packagePrompt - from prompt-packager
+ * @param {Function} deps.dispatch - from cli-dispatcher
+ * @param {Function} deps.readRouterState - reads .tlc/.router-state.json
+ * @returns {Promise<Object>} Result
+ */
+async function routeCommand({ command, agentPrompt, flagModel, context, projectDir, homeDir }, deps) {
+  // Resolve routing config — pass full context so personal + project configs are loaded
+  const routing = deps.resolveRouting({ command, flagModel, projectDir, homeDir });
+
+  // Read router state for provider availability
+  const routerState = deps.readRouterState();
+
+  const { models, strategy, providers: providerConfig } = routing;
+
+  // Single strategy — fall back to Claude if target is unavailable
+  if (strategy === 'single') {
+    const model = models[0];
+    const result = await routeModel(model, {
+      agentPrompt,
+      context,
+      providerConfig,
+      routerState,
+    }, deps);
+
+    // For single strategy, skipped means fall back to inline
+    if (result.type === 'skipped') {
+      return { type: 'inline', model: 'claude', warning: result.warning + ', falling back to inline (claude)' };
+    }
+
+    return result;
+  }
+
+  // Parallel strategy
+  if (strategy === 'parallel') {
+    const promises = models.map((model) =>
+      routeModel(model, {
+        agentPrompt,
+        context,
+        providerConfig,
+        routerState,
+      }, deps)
+    );
+
+    const results = await Promise.all(promises);
+
+    return {
+      type: 'parallel',
+      results,
+    };
+  }
+
+  // Unknown strategy — fall back to inline
+  return { type: 'inline', model: 'claude' };
+}
+
+module.exports = { routeCommand };

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/field-report.js

@@ -0,0 +1,92 @@
+/**
+ * Field Report Module — Agent Self-Rating
+ *
+ * After build/review, the agent rates its experience and files structured
+ * reports when quality falls below threshold (rating < 8).
+ */
+
+/** Rating threshold — reports are filed when rating is below this value */
+const REPORT_THRESHOLD = 8;
+
+/**
+ * Determine whether a field report should be filed based on the rating.
+ * @param {number} rating - Self-assessed quality rating (0–10)
+ * @returns {boolean} true if rating < 8, false otherwise
+ */
+function shouldFileReport(rating) {
+  if (typeof rating !== 'number') {
+    throw new TypeError('rating must be a number');
+  }
+  return rating < REPORT_THRESHOLD;
+}
+
+/**
+ * Create a formatted field report from the given parameters.
+ * @param {object} params
+ * @param {string} params.skill - The TLC skill that was executed (e.g. 'tlc:build')
+ * @param {number} params.rating - Self-assessed quality rating (0–10)
+ * @param {string} params.issue - Description of the issue encountered
+ * @param {string} params.suggestion - Suggested improvement
+ * @param {() => Date} [params.now] - Optional clock function for deterministic dates
+ * @returns {string} Formatted markdown report
+ */
+function createFieldReport({ skill, rating, issue, suggestion, now }) {
+  if (!skill) {
+    throw new Error('skill is required');
+  }
+  if (typeof rating !== 'number') {
+    throw new TypeError('rating must be a number');
+  }
+  if (!issue) {
+    throw new Error('issue is required');
+  }
+  if (!suggestion) {
+    throw new Error('suggestion is required');
+  }
+
+  const date = (now ? now() : new Date()).toISOString();
+  const critical = rating === 0 ? ' CRITICAL' : '';
+  const heading = `## ${date} ${skill} ${rating}/10${critical} — ${issue}`;
+  const body = `**Suggestion:** ${suggestion}`;
+
+  return `${heading}\n\n${body}\n`;
+}
+
+/**
+ * Format a report string as a single markdown section.
+ * Ensures the entry ends with exactly one trailing newline.
+ * @param {string} report - Raw report content from createFieldReport
+ * @returns {string} Formatted markdown section with trailing newline
+ */
+function formatReportEntry(report) {
+  if (typeof report !== 'string') {
+    throw new TypeError('report must be a string');
+  }
+  return report.trimEnd() + '\n';
+}
+
+/**
+ * Append a new report to existing file content.
+ * If existing content is empty, creates a new document with a header.
+ * @param {string} existingContent - Current file content (may be empty)
+ * @param {string} newReport - New report to append
+ * @returns {string} Combined content
+ */
+function appendReport(existingContent, newReport) {
+  if (typeof existingContent !== 'string') {
+    throw new TypeError('existingContent must be a string');
+  }
+  if (typeof newReport !== 'string') {
+    throw new TypeError('newReport must be a string');
+  }
+
+  const entry = formatReportEntry(newReport);
+
+  if (!existingContent) {
+    return `# Field Reports\n\n${entry}`;
+  }
+
+  return `${existingContent}\n\n---\n\n${entry}`;
+}
+
+module.exports = { shouldFileReport, createFieldReport, formatReportEntry, appendReport };