tlc-claude-code 2.4.2 → 2.4.3

package/CLAUDE.md

@@ -4,11 +4,12 @@
 
 ## Rules (Enforced by hooks — violations are blocked)
 
-1. **Tests before code.** Always. Red → Green → Refactor. Use `/tlc:build`.
-2. **Plans go in files.** Use `/tlc:plan` → writes to `.planning/phases/`. Never plan in chat.
-3. **No direct implementation.** User says "build X" → run `/tlc:progress` then `/tlc:build`.
-4. **No Co-Authored-By in commits.** The user is the author. Claude is a tool.
-5. **Ask before `git push`.** Never push without explicit approval.
+1. **Never commit to main.** Always create `phase/{N}` branch. PR back to main when done.
+2. **Tests before code.** Always. Red → Green → Refactor. Use `/tlc:build`.
+3. **Plans go in files.** Use `/tlc:plan` → writes to `.planning/phases/`. Never plan in chat.
+4. **No direct implementation.** User says "build X" → run `/tlc:progress` then `/tlc:build`.
+5. **No Co-Authored-By in commits.** The user is the author. Claude is a tool.
+6. **Ask before `git push`.** Never push without explicit approval.
 
 ## Command Dispatch
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tlc-claude-code",
-  "version": "2.4.2",
+  "version": "2.4.3",
   "description": "TLC - Test Led Coding for Claude Code",
   "bin": {
     "tlc-claude-code": "./bin/install.js",
@@ -34,11 +34,14 @@
     "postinstall": "node bin/postinstall.js",
     "build": "cd dashboard && npm run build",
     "build:web": "cd dashboard-web && npm install && npm run build",
+    "preversion": "node scripts/version-sync.js && git diff --quiet || (echo 'Working tree not clean' && exit 1)",
+    "version": "node scripts/version-sync.js && git add .tlc.json",
     "prepublishOnly": "npm run build && npm run build:web",
     "docs": "node scripts/docs-update.js",
     "docs:check": "node scripts/docs-update.js --check",
     "docs:screenshots": "node scripts/generate-screenshots.js",
     "docs:capture": "node scripts/capture-screenshots.js",
+    "test:version-sync": "cd server && npx vitest run --dir .. scripts/version-sync.test.js",
     "test:e2e": "npx playwright test",
     "test:e2e:ui": "npx playwright test --ui"
   },

package/scripts/dev-link.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+cd "${REPO_ROOT}" || {
+  echo "Error: failed to change to repo root: ${REPO_ROOT}" >&2
+  exit 1
+}
+
+if ! npm link; then
+  echo "Error: npm link failed" >&2
+  exit 1
+fi
+
+LINK_PATH="$(command -v tlc-claude-code || true)"
+
+if [ -z "${LINK_PATH}" ]; then
+  echo "Error: tlc-claude-code was not found on PATH after npm link" >&2
+  exit 1
+fi
+
+echo "Local link created successfully."
+echo "Use it from another project with:"
+echo "  npm link tlc-claude-code"
+echo "Resolved binary:"
+echo "  ${LINK_PATH}"

package/scripts/test-package.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+TMP_DIR=""
+TARBALL_PATH=""
+NPM_CACHE_DIR=""
+
+cleanup() {
+  if [ -n "${TMP_DIR}" ] && [ -d "${TMP_DIR}" ]; then
+    rm -rf "${TMP_DIR}"
+  fi
+
+  if [ -n "${TARBALL_PATH}" ] && [ -f "${TARBALL_PATH}" ]; then
+    rm -f "${TARBALL_PATH}"
+  fi
+}
+
+fail() {
+  echo "Error: $1" >&2
+  exit 1
+}
+
+trap cleanup EXIT
+
+TMP_DIR="$(mktemp -d 2>/dev/null || mktemp -d -t tlc-test-package)" || fail "failed to create temporary directory"
+NPM_CACHE_DIR="${TMP_DIR}/npm-cache"
+mkdir -p "${NPM_CACHE_DIR}" || fail "failed to create npm cache directory"
+
+cd "${REPO_ROOT}" || fail "failed to change to repo root: ${REPO_ROOT}"
+
+PACK_OUTPUT="$(npm_config_cache="${NPM_CACHE_DIR}" npm pack --json 2>&1)" || fail "npm pack failed: ${PACK_OUTPUT}"
+TARBALL_NAME="$(printf '%s\n' "${PACK_OUTPUT}" | node -e "let input=''; process.stdin.on('data', (chunk) => input += chunk); process.stdin.on('end', () => { const start = input.indexOf('['); if (start === -1) { process.exit(1); } const data = JSON.parse(input.slice(start)); if (!Array.isArray(data) || !data[0] || !data[0].filename) { process.exit(1); } process.stdout.write(data[0].filename); });")" || fail "failed to parse npm pack output"
+
+[ -n "${TARBALL_NAME}" ] || fail "npm pack did not return a tarball name"
+
+TARBALL_PATH="${REPO_ROOT}/${TARBALL_NAME}"
+[ -f "${TARBALL_PATH}" ] || fail "tarball was not created: ${TARBALL_PATH}"
+
+cd "${TMP_DIR}" || fail "failed to change to temp directory: ${TMP_DIR}"
+
+npm_config_cache="${NPM_CACHE_DIR}" npm install "${TARBALL_PATH}" >/dev/null 2>&1 || fail "npm install failed for ${TARBALL_NAME}"
+
+PACKAGE_FILE="${TMP_DIR}/node_modules/tlc-claude-code/server/lib/routing-preamble.js"
+[ -f "${PACKAGE_FILE}" ] || fail "installed package is missing server/lib/routing-preamble.js"
+
+OUTPUT="$(node -e "const {generatePreamble} = require('tlc-claude-code/server/lib/routing-preamble'); const p = generatePreamble('build'); console.log(p.substring(0,20))" 2>&1)" || fail "routing preamble validation failed: ${OUTPUT}"
+
+[ -n "${OUTPUT}" ] || fail "routing preamble validation produced no output"
+
+echo "Package test passed."
+exit 0

package/scripts/version-sync.js

@@ -0,0 +1,42 @@
+const fs = require('fs');
+const path = require('path');
+
+function syncVersion(rootDir = path.resolve(__dirname, '..')) {
+  const packageJsonPath = path.join(rootDir, 'package.json');
+  const tlcConfigPath = path.join(rootDir, '.tlc.json');
+
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+
+  if (typeof packageJson.version !== 'string' || packageJson.version.trim() === '') {
+    throw new Error('package.json is missing a valid version field');
+  }
+
+  let tlcConfig = {};
+
+  if (fs.existsSync(tlcConfigPath)) {
+    tlcConfig = JSON.parse(fs.readFileSync(tlcConfigPath, 'utf8'));
+  }
+
+  tlcConfig.version = packageJson.version;
+  tlcConfig.tlcVersion = packageJson.version;
+
+  fs.writeFileSync(tlcConfigPath, `${JSON.stringify(tlcConfig, null, 2)}\n`);
+}
+
+function main() {
+  try {
+    syncVersion();
+    process.exit(0);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  syncVersion,
+};

package/scripts/version-sync.test.js

@@ -0,0 +1,100 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import versionSyncModule from './version-sync.js';
+
+const { syncVersion } = versionSyncModule;
+
+const tempDirs = [];
+
+function createTempProject(packageVersion, tlcConfig) {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'version-sync-'));
+  tempDirs.push(tempDir);
+
+  fs.writeFileSync(
+    path.join(tempDir, 'package.json'),
+    `${JSON.stringify({ version: packageVersion }, null, 2)}\n`
+  );
+
+  if (tlcConfig !== undefined) {
+    fs.writeFileSync(
+      path.join(tempDir, '.tlc.json'),
+      `${JSON.stringify(tlcConfig, null, 2)}\n`
+    );
+  }
+
+  return tempDir;
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+afterEach(() => {
+  while (tempDirs.length > 0) {
+    fs.rmSync(tempDirs.pop(), { recursive: true, force: true });
+  }
+});
+
+describe('syncVersion', () => {
+  it('reads version from package.json correctly', () => {
+    const tempDir = createTempProject('1.2.3', { existing: true });
+
+    syncVersion(tempDir);
+
+    const tlcConfig = readJson(path.join(tempDir, '.tlc.json'));
+    expect(tlcConfig.version).toBe('1.2.3');
+  });
+
+  it('writes to .tlc.json version field', () => {
+    const tempDir = createTempProject('2.3.4', {});
+
+    syncVersion(tempDir);
+
+    const tlcConfig = readJson(path.join(tempDir, '.tlc.json'));
+    expect(tlcConfig.version).toBe('2.3.4');
+  });
+
+  it('writes to .tlc.json tlcVersion field', () => {
+    const tempDir = createTempProject('3.4.5', {});
+
+    syncVersion(tempDir);
+
+    const tlcConfig = readJson(path.join(tempDir, '.tlc.json'));
+    expect(tlcConfig.tlcVersion).toBe('3.4.5');
+  });
+
+  it('handles missing .tlc.json gracefully', () => {
+    const tempDir = createTempProject('4.5.6');
+
+    expect(() => syncVersion(tempDir)).not.toThrow();
+
+    const tlcConfig = readJson(path.join(tempDir, '.tlc.json'));
+    expect(tlcConfig).toEqual({
+      version: '4.5.6',
+      tlcVersion: '4.5.6',
+    });
+  });
+
+  it('does not overwrite other .tlc.json fields', () => {
+    const tempDir = createTempProject('5.6.7', {
+      project: 'TLC',
+      nested: { keep: true },
+      version: 'old',
+      tlcVersion: 'old',
+    });
+
+    syncVersion(tempDir);
+
+    const tlcConfig = readJson(path.join(tempDir, '.tlc.json'));
+    expect(tlcConfig).toEqual({
+      project: 'TLC',
+      nested: { keep: true },
+      version: '5.6.7',
+      tlcVersion: '5.6.7',
+    });
+  });
+});

package/server/lib/model-router.js

@@ -13,6 +13,10 @@ const DEFAULT_CONFIG = {
   devserver: { url: null },
 };
 
+function isMissingConfigError(error) {
+  return error?.code === 'ENOENT' || error?.message?.includes('ENOENT');
+}
+
 export class ModelRouter {
   constructor(config = {}) {
     this.config = { ...DEFAULT_CONFIG, ...config };
@@ -88,8 +92,13 @@ export class ModelRouter {
         this.config = { ...DEFAULT_CONFIG, ...configData.router };
         this.devserverUrl = configData.router.devserver?.url || null;
       }
-    } catch {
-      // Use defaults
+    } 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}`);
+      }
     }
   }
 }

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

@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import {
   ModelRouter,
   resolveProvider,
@@ -22,6 +22,10 @@ describe('Model Router', () => {
     });
   });
 
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
   describe('resolveProvider', () => {
     it('returns local when CLI detected', async () => {
       router._detectCLI = vi.fn().mockResolvedValue({ found: true, path: '/usr/bin/claude' });
@@ -105,6 +109,28 @@ describe('Model Router', () => {
 
       expect(router.config).toBeDefined();
     });
+
+    it('warns when config JSON is invalid', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      router._readConfig = vi.fn().mockRejectedValue(new SyntaxError('Unexpected token }'));
+
+      await router.loadConfig();
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        '[TLC WARNING] Failed to parse .tlc.json router config; using defaults'
+      );
+    });
+
+    it('stays silent when config file is missing', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const error = new Error('ENOENT');
+      error.code = 'ENOENT';
+      router._readConfig = vi.fn().mockRejectedValue(error);
+
+      await router.loadConfig();
+
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
   });
 
   describe('handleUnavailable', () => {

package/server/lib/orchestration/codex-orchestrator.js

@@ -0,0 +1,185 @@
+/**
+ * Codex Orchestrator
+ *
+ * Dispatches tasks to Codex CLI and captures thread IDs for resume flows.
+ */
+
+function createCliNotFoundError() {
+  return {
+    code: 'CODEX_CLI_NOT_FOUND',
+    message: 'Codex CLI is not installed or not available on PATH',
+  };
+}
+
+function createTimeoutError(timeout) {
+  return {
+    code: 'PROCESS_TIMEOUT',
+    message: `Process timed out after ${timeout}ms`,
+  };
+}
+
+function runCodex({
+  args,
+  prompt = '',
+  timeout = 120000,
+  cwd,
+  spawn = require('child_process').spawn,
+  onStdoutLine,
+}) {
+  return new Promise((resolve) => {
+    const start = Date.now();
+    const spawnOpts = {};
+    if (cwd) spawnOpts.cwd = cwd;
+
+    let proc;
+    try {
+      proc = spawn('codex', args, spawnOpts);
+    } catch (err) {
+      const error = err && err.code === 'ENOENT'
+        ? createCliNotFoundError()
+        : {
+            code: 'SPAWN_FAILED',
+            message: err && err.message ? err.message : 'Failed to spawn Codex CLI',
+          };
+
+      resolve({
+        stdout: '',
+        stderr: err && err.message ? err.message : error.message,
+        exitCode: -1,
+        duration: Date.now() - start,
+        error,
+      });
+      return;
+    }
+
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    let stdoutBuffer = '';
+
+    const finish = (exitCode, error = null, stderrOverride) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({
+        stdout,
+        stderr: stderrOverride !== undefined ? stderrOverride : stderr,
+        exitCode,
+        duration: Date.now() - start,
+        error,
+      });
+    };
+
+    const timer = setTimeout(() => {
+      proc.kill();
+      const error = createTimeoutError(timeout);
+      const nextStderr = stderr ? `${stderr}\n${error.message}` : error.message;
+      finish(-1, error, nextStderr);
+    }, timeout);
+
+    proc.stdout.on('data', (data) => {
+      const chunk = data.toString();
+      stdout += chunk;
+
+      if (!onStdoutLine) {
+        return;
+      }
+
+      stdoutBuffer += chunk;
+
+      while (stdoutBuffer.includes('\n')) {
+        const newlineIndex = stdoutBuffer.indexOf('\n');
+        const line = stdoutBuffer.slice(0, newlineIndex);
+        stdoutBuffer = stdoutBuffer.slice(newlineIndex + 1);
+        onStdoutLine(line);
+      }
+    });
+
+    proc.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    proc.on('close', (code) => {
+      if (onStdoutLine && stdoutBuffer) {
+        onStdoutLine(stdoutBuffer);
+        stdoutBuffer = '';
+      }
+
+      finish(code, null);
+    });
+
+    proc.on('error', (err) => {
+      const error = err && err.code === 'ENOENT'
+        ? createCliNotFoundError()
+        : {
+            code: 'SPAWN_FAILED',
+            message: err && err.message ? err.message : 'Failed to spawn Codex CLI',
+          };
+
+      const nextStderr = stderr || (err && err.message) || error.message;
+      finish(-1, error, nextStderr);
+    });
+
+    proc.stdin.on('error', () => {});
+
+    if (prompt) {
+      proc.stdin.write(prompt);
+    }
+    proc.stdin.end();
+  });
+}
+
+async function dispatchToCodex({
+  worktreePath,
+  prompt,
+  timeout = 120000,
+  spawn = require('child_process').spawn,
+}) {
+  let threadId = null;
+
+  const result = await runCodex({
+    args: ['exec', '--json', '--full-auto', '-C', worktreePath],
+    prompt,
+    timeout,
+    spawn,
+    onStdoutLine(line) {
+      if (!line) return;
+
+      try {
+        const event = JSON.parse(line);
+        if (event.type === 'thread.started' && typeof event.thread_id === 'string') {
+          threadId = event.thread_id;
+        }
+      } catch (_) {
+        // Ignore non-JSON lines in mixed stdout streams.
+      }
+    },
+  });
+
+  return {
+    threadId,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    exitCode: result.exitCode,
+    duration: result.duration,
+    error: result.error,
+  };
+}
+
+function resumeSession({
+  threadId,
+  prompt,
+  timeout = 120000,
+  spawn = require('child_process').spawn,
+}) {
+  return runCodex({
+    args: ['exec', 'resume', threadId, prompt],
+    timeout,
+    spawn,
+  });
+}
+
+module.exports = {
+  dispatchToCodex,
+  resumeSession,
+};