tlc-claude-code 1.8.1 → 1.8.3

package/.claude/commands/tlc/tlc.md

@@ -16,10 +16,185 @@ See `/tlc:build` for the complete engineering standards checklist.
 
 ## What This Does
 
-Launches the TLC dashboard - a visual interface showing project state, phases, tests, and next actions.
+Detects project state, checks for TLC version upgrades, and launches the dashboard. If a newer TLC version is installed than the project has configured, it automatically upgrades config and commands before proceeding.
 
 ## Process
 
+### Step 0: Check TLC Version (Upgrade Detection)
+
+**Run this BEFORE anything else.** Compare installed TLC version against the project's `.tlc.json` version.
+
+```bash
+# Get installed TLC version
+installedVersion=$(node -e "
+  try {
+    const p = require('tlc-claude-code/package.json');
+    console.log(p.version);
+  } catch(e) {
+    // Try global
+    const { execSync } = require('child_process');
+    try {
+      const v = execSync('npm list -g tlc-claude-code --json 2>/dev/null', { encoding: 'utf-8' });
+      console.log(JSON.parse(v).dependencies['tlc-claude-code'].version);
+    } catch(e2) { console.log('unknown'); }
+  }
+" 2>/dev/null)
+
+# Get project TLC version from .tlc.json
+projectVersion=$(node -e "
+  try {
+    const c = require('./.tlc.json');
+    console.log(c.tlcVersion || '0.0.0');
+  } catch(e) { console.log('0.0.0'); }
+" 2>/dev/null)
+```
+
+**If `installedVersion` > `projectVersion`:**
+
+Show upgrade notice and apply automatically:
+
+```
+─────────────────────────────────────────────────────
+ TLC UPGRADE DETECTED
+─────────────────────────────────────────────────────
+
+Installed: v{installedVersion}
+Project:   v{projectVersion}
+
+New in this version:
+  {list new features — see Version Features Map below}
+
+Applying upgrade...
+```
+
+Then execute the upgrade steps:
+
+#### Step 0.1: Merge New Config Sections into .tlc.json
+
+Read the project's `.tlc.json`. For each new config section introduced since `projectVersion`, **add it ONLY if it doesn't already exist**. Never overwrite existing user settings.
+
+```javascript
+// Pseudo-code for config merge
+const config = JSON.parse(fs.readFileSync('.tlc.json'));
+
+// Add new sections only if missing
+if (!config.router) {
+  config.router = {
+    providers: {},
+    capabilities: {}
+  };
+  console.log('  + Added: router (LLM provider routing)');
+}
+
+if (!config.dashboard) {
+  config.dashboard = {
+    port: 3147,
+    auth: false
+  };
+  console.log('  + Added: dashboard config');
+}
+
+if (!config.docs) {
+  config.docs = {
+    autoSync: false,
+    screenshots: []
+  };
+  console.log('  + Added: docs automation config');
+}
+
+// Update version stamp
+config.tlcVersion = installedVersion;
+
+fs.writeFileSync('.tlc.json', JSON.stringify(config, null, 2));
+```
+
+#### Step 0.2: Update CLAUDE.md Command Dispatch
+
+Read the project's `CLAUDE.md`. Check if the command dispatch table exists. If new commands were added since `projectVersion`, append them to the table.
+
+**How to detect:** Read `.claude/commands/tlc/*.md` directory listing from the installed TLC package. Compare against the dispatch table entries in the project's `CLAUDE.md`. Add any missing rows.
+
+**Never remove or reorder existing entries.** Only append new ones.
+
+#### Step 0.3: Sync Command Files
+
+The `.claude/commands/tlc/` directory should already be up-to-date if the user ran `tlc` (the CLI installer). But verify:
+
+```bash
+# Check if commands are current
+installedCommandCount=$(ls node_modules/tlc-claude-code/.claude/commands/tlc/*.md 2>/dev/null | wc -l)
+projectCommandCount=$(ls .claude/commands/tlc/*.md 2>/dev/null | wc -l)
+
+if [ "$installedCommandCount" -gt "$projectCommandCount" ]; then
+  echo "  + Syncing new commands to .claude/commands/tlc/"
+  cp node_modules/tlc-claude-code/.claude/commands/tlc/*.md .claude/commands/tlc/
+fi
+```
+
+#### Step 0.4: Detect New LLM Providers
+
+If the `router` section was just added (or is empty), scan for available CLI tools:
+
+```bash
+which claude  >/dev/null 2>&1 && echo "claude detected"
+which codex   >/dev/null 2>&1 && echo "codex detected"
+which gemini  >/dev/null 2>&1 && echo "gemini detected"
+```
+
+If providers are detected but `router.providers` is empty, offer to configure:
+
+```
+LLM providers detected: claude, codex
+
+Configure multi-model routing? (Y/n)
+```
+
+If yes, populate `router.providers` with detected CLIs and default capability mappings.
+
+If no, skip — user can run `/tlc:llm config` later.
+
+#### Step 0.5: Report and Continue
+
+```
+─────────────────────────────────────────────────────
+ UPGRADE COMPLETE
+─────────────────────────────────────────────────────
+
+Updated .tlc.json:
+  + router (LLM provider routing)
+  + dashboard config
+  + docs automation config
+  ~ tlcVersion: 0.0.0 → 1.8.2
+
+Synced:
+  + 3 new commands added
+  + CLAUDE.md dispatch table updated
+
+Configure LLM routing now? → /tlc:llm config
+Configure dashboard?       → /tlc:dashboard
+
+Continuing to dashboard...
+─────────────────────────────────────────────────────
+```
+
+Then continue to Step 1 (launch dashboard) as normal.
+
+**If versions match:** Skip this step silently. No output.
+
+#### Version Features Map
+
+This map tells the upgrade which config sections to add based on version ranges. Update this when new features ship.
+
+| Since Version | Config Section | Default Value | Description |
+|---|---|---|---|
+| 1.5.0 | `router` | `{ providers: {}, capabilities: {} }` | LLM multi-model routing |
+| 1.5.0 | `enterprise` | `{ enabled: false }` | Enterprise features toggle |
+| 1.7.0 | `docs` | `{ autoSync: false, screenshots: [] }` | Documentation automation |
+| 1.8.0 | `dashboard` | `{ port: 3147, auth: false }` | Dashboard configuration |
+| 1.8.2 | `dashboard.compose` | `"docker-compose.tlc.yml"` | Standalone dashboard compose file |
+
+---
+
 ### Step 1: Launch Dashboard
 
 Run the TLC dashboard:

package/CLAUDE.md

@@ -96,6 +96,7 @@ Every TLC command is defined in `.claude/commands/tlc/*.md`. When you invoke a c
 | "issues", "import issues" | `/tlc:issues` | Manual issue tracking |
 | "checklist", "full check" | `/tlc:checklist` | Ad-hoc project review |
 | "quick task", "small fix" | `/tlc:quick` | Coding without tests |
+| "dashboard", "start dashboard", "dashboard container" | `/tlc:dashboard` | Running docker-compose manually |
 
 ### Before ANY work — run `/tlc`
 

package/CODING-STANDARDS.md

@@ -588,6 +588,141 @@ Refs: #456
 
 ---
 
+## 18. File Size Limits
+
+Large files are a code smell. They indicate a class or module is doing too much.
+
+| Threshold | Action |
+|---|---|
+| **< 300 lines** | Ideal. No action needed. |
+| **300-500 lines** | Acceptable. Review if it can be split. |
+| **500-1000 lines** | Warning. Should be split into focused sub-modules. |
+| **> 1000 lines** | Violation. MUST be split before merging. |
+
+### How to Split
+
+**Controllers with many routes:**
+```
+# Bad: csp.controller.ts (2,000+ lines)
+# Good: Split by resource/feature:
+modules/csp/
+  controllers/
+    policy.controller.ts      # CRUD for policies
+    report.controller.ts      # CSP violation reports
+    directive.controller.ts   # Directive management
+  csp.routes.ts               # Route registration (thin)
+```
+
+**Services with many methods:**
+```
+# Bad: user.service.ts (1,500 lines)
+# Good: Split by responsibility:
+modules/user/
+  services/
+    user-auth.service.ts      # Login, register, password reset
+    user-profile.service.ts   # Profile CRUD, avatar, preferences
+    user-admin.service.ts     # Admin operations, ban, role changes
+  user.service.ts             # Thin facade re-exporting sub-services
+```
+
+---
+
+## 19. Folder Overcrowding
+
+Too many files in one folder makes navigation difficult. Organize into subfolders by domain.
+
+| Threshold | Action |
+|---|---|
+| **< 8 files** | Fine as-is. |
+| **8-15 files** | Consider grouping into subfolders. |
+| **> 15 files** | MUST be organized into subfolders. |
+
+```
+# Bad: 25 files dumped in controllers/
+controllers/
+  auth.controller.ts
+  user.controller.ts
+  payment.controller.ts
+  invoice.controller.ts
+  product.controller.ts
+  ... (20 more)
+
+# Good: Organized by domain
+modules/
+  auth/auth.controller.ts
+  user/user.controller.ts
+  billing/
+    payment.controller.ts
+    invoice.controller.ts
+  catalog/
+    product.controller.ts
+```
+
+---
+
+## 20. Strict Typing
+
+TypeScript without strict types is just JavaScript with extra steps.
+
+### Rules
+
+1. **No `any` type** - Use `unknown` and narrow, or define a proper interface.
+2. **No implicit `any`** - Enable `noImplicitAny` in tsconfig.
+3. **All functions must have explicit return types** - Not just exported functions.
+4. **All parameters must be typed** - No untyped function parameters.
+5. **Prefer `interface` over `type`** for object shapes - Easier to extend.
+6. **Use `strict: true`** in tsconfig.json.
+
+```typescript
+// Bad: Missing types, implicit any
+function processData(data) {
+  const result = data.items.map(item => item.value);
+  return result;
+}
+
+// Good: Explicit types everywhere
+interface DataPayload {
+  items: Array<{ value: number }>;
+}
+
+function processData(data: DataPayload): number[] {
+  return data.items.map((item) => item.value);
+}
+```
+
+```typescript
+// Bad: any type
+function handleResponse(response: any): any {
+  return response.data;
+}
+
+// Good: Proper types
+interface ApiResponse<T> {
+  data: T;
+  status: number;
+}
+
+function handleResponse<T>(response: ApiResponse<T>): T {
+  return response.data;
+}
+```
+
+### tsconfig.json Requirements
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true
+  }
+}
+```
+
+---
+
 ## AI Instructions
 
 When generating code:
@@ -605,6 +740,10 @@ When generating code:
 11. **Always** add JSDoc to public members
 12. **Always** create index.ts with barrel exports
 13. **Always** verify build passes after changes
+14. **Never** let files exceed 1000 lines - split into sub-modules
+15. **Never** let folders exceed 15 files - organize into subfolders
+16. **Never** use `any` type - use `unknown` or proper interfaces
+17. **Always** add explicit return types to functions
 
 ### Cleanup Tasks
 

package/docker-compose.dev.yml

@@ -94,7 +94,8 @@ services:
       retries: 5
     restart: on-failure
 
-  # TLC Dashboard
+  # TLC Dashboard (Express API + React SPA on port 3147)
+  # Since v1.8.1, the server serves the React dashboard from dashboard-web/dist/
   dashboard:
     image: node:20-alpine
     container_name: tlc-${COMPOSE_PROJECT_NAME:-dev}-dashboard
@@ -105,7 +106,7 @@ services:
         npm install -g tlc-claude-code@latest &&
         TLC_DIR=/usr/local/lib/node_modules/tlc-claude-code &&
         echo 'TLC installed at:' $$TLC_DIR &&
-        ls -la $$TLC_DIR/server/ &&
+        ls $$TLC_DIR/dashboard-web/dist/index.html && echo '[TLC] React SPA ready' || echo '[TLC] WARNING: dashboard-web/dist not found' &&
         cd /project && node $$TLC_DIR/server/index.js --proxy-only --skip-db
       "
     environment:
@@ -121,26 +122,6 @@ services:
       - app
     restart: on-failure
 
-  # TLC Dashboard Web (built from dashboard-web, serves static files via nginx)
-  dashboard-web:
-    build:
-      context: ./dashboard-web
-      dockerfile: Dockerfile
-    container_name: tlc-${COMPOSE_PROJECT_NAME:-dev}-dashboard-web
-    ports:
-      - "${DASHBOARD_WEB_PORT:-3002}:80"
-    environment:
-      - API_URL=http://dashboard:3147
-    depends_on:
-      - dashboard
-    restart: on-failure
-    healthcheck:
-      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:80/health"]
-      interval: 30s
-      timeout: 3s
-      start_period: 5s
-      retries: 3
-
   # Playwright E2E Tests (optional - starts on demand)
   playwright:
     image: mcr.microsoft.com/playwright:v1.40.0-jammy

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tlc-claude-code",
-  "version": "1.8.1",
+  "version": "1.8.3",
   "description": "TLC - Test Led Coding for Claude Code",
   "bin": {
     "tlc": "./bin/tlc.js",

package/server/lib/output-schemas.test.js

@@ -1,4 +1,6 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, writeFileSync, rmSync } from 'fs';
+import { join } from 'path';
 import {
   loadSchema,
   validateOutput,
@@ -9,8 +11,20 @@ import {
   schemaToPromptInstructions,
 } from './output-schemas.js';
 
+const schemasDir = join(process.cwd(), '.tlc', 'schemas');
+const testSchema = { type: 'object', required: ['summary'], properties: { summary: { type: 'string' } } };
+
 describe('Output Schemas', () => {
   describe('loadSchema', () => {
+    beforeEach(() => {
+      mkdirSync(schemasDir, { recursive: true });
+      writeFileSync(join(schemasDir, 'review-result.json'), JSON.stringify(testSchema));
+    });
+
+    afterEach(() => {
+      rmSync(join(schemasDir, 'review-result.json'), { force: true });
+    });
+
     it('reads from file', async () => {
       const schema = await loadSchema('review-result');
       expect(schema).toBeDefined();