tlc-claude-code 1.8.1 → 1.8.3

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

@@ -34,17 +34,24 @@ const { auditProject, generateReport } = require('./lib/standards/audit-checker'
 
 Run `auditProject(projectPath)` which executes:
 
-| Check | What It Finds |
-|-------|---------------|
-| Standards Files | Missing CLAUDE.md or CODING-STANDARDS.md |
-| Flat Folders | Files in src/services/, src/interfaces/, src/controllers/ |
-| Inline Interfaces | `interface X {` inside *.service.ts files |
-| Hardcoded URLs | http:// or https:// URLs in code |
-| Hardcoded Ports | `const port = 3000` patterns |
-| Magic Strings | `=== 'active'` comparisons without constants |
-| Flat Seeds | Seed files in src/seeds/ instead of src/{entity}/seeds/ |
-| Missing JSDoc | Exported functions without `/**` comments |
-| Deep Imports | `../../../` style imports (3+ levels) |
+| Check | What It Finds | Severity |
+|-------|---------------|----------|
+| Standards Files | Missing CLAUDE.md or CODING-STANDARDS.md | error |
+| Flat Folders | Files in src/services/, src/interfaces/, src/controllers/ | error |
+| Inline Interfaces | `interface X {` inside *.service.ts or *.controller.ts files | error |
+| Inline Constants | `const X =` hardcoded values inside service/controller files | warning |
+| Hardcoded URLs | http:// or https:// URLs in code | error |
+| Hardcoded Ports | `const port = 3000` patterns | error |
+| Magic Strings | `=== 'active'` comparisons without constants | warning |
+| Flat Seeds | Seed files in src/seeds/ instead of src/{entity}/seeds/ | warning |
+| Missing JSDoc | Exported functions without `/**` comments | warning |
+| Deep Imports | `../../../` style imports (3+ levels) | warning |
+| **Oversized Files** | Files exceeding 1000 lines (warn at 500) | error/warning |
+| **Overcrowded Folders** | Folders with >15 files directly inside (warn at 8) | error/warning |
+| **`any` Type Usage** | `any` type annotations in TypeScript files | error |
+| **Missing Return Types** | Exported functions without explicit return type | warning |
+| **Missing Parameter Types** | Function parameters without type annotations | error |
+| **Weak tsconfig** | `strict: true` not enabled in tsconfig.json | warning |
 
 ### Step 3: Generate Report
 
@@ -80,15 +87,27 @@ Status: {PASSED | FAILED}
 TLC Audit Results
 ═══════════════════════════════════════════════════════════════
 
-Status: ✗ FAILED (12 issues found)
-
-Standards Files:    ✓ PASSED
-Flat Folders:       ✗ 3 issues
-Inline Interfaces:  ✗ 2 issues
-Hardcoded URLs:     ✗ 4 issues
-Magic Strings:      ✗ 2 issues
-JSDoc Coverage:     ✗ 1 issue
-Import Style:       ✓ PASSED
+Status: FAILED (18 issues found)
+
+  STRUCTURE
+  Standards Files:      PASSED
+  Flat Folders:         3 issues
+  Overcrowded Folders:  2 issues (controllers/ has 22 files)
+  Oversized Files:      1 issue  (csp.controller.ts: 2,041 lines)
+
+  TYPES & INTERFACES
+  Inline Interfaces:    2 issues
+  Inline Constants:     3 issues
+  any Type Usage:       5 issues
+  Missing Return Types: 4 issues
+  Missing Param Types:  2 issues
+  Weak tsconfig:        PASSED
+
+  CODE QUALITY
+  Hardcoded URLs:       4 issues
+  Magic Strings:        2 issues
+  JSDoc Coverage:       8 issues (42% of exports undocumented)
+  Import Style:         PASSED
 
 Report saved to: .planning/AUDIT-REPORT.md
 

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

@@ -692,6 +692,11 @@ git diff --name-status main...HEAD
 1. **Test Coverage** - Every implementation file has a test file
 2. **TDD Compliance** - Commits show test-first pattern (score ≥ 50%)
 3. **Security Scan** - No hardcoded secrets, eval(), innerHTML, etc.
+4. **File Size** - No file exceeds 1000 lines (warning at 500+)
+5. **Folder Size** - No folder exceeds 15 files (warning at 8+)
+6. **Strict Typing** - No `any` types in new/changed files
+7. **Return Types** - All exported functions have explicit return types
+8. **Module Structure** - Files grouped by domain entity, not by type
 
 **Review output:**
 
@@ -702,6 +707,10 @@ git diff --name-status main...HEAD
 Test Coverage: ✅ 5/5 files covered
 TDD Score: 75% ✅
 Security: ✅ No issues
+File Sizes: ✅ All under 1000 lines
+Folder Sizes: ✅ All under 15 files
+Strict Typing: ✅ No `any` found
+Return Types: ✅ All exports typed
 
 Verdict: ✅ APPROVED
 ───────────────────────────────
@@ -721,6 +730,18 @@ TDD Score: 25% ❌ (target: 50%)
 Security: ❌ 1 high severity issue
 └── Hardcoded password in src/config.js
 
+File Sizes: ⚠️ 1 file over limit
+└── src/api/users.controller.ts (1,247 lines) → split by feature
+
+Strict Typing: ❌ 3 `any` types found
+├── src/api/users.controller.ts:45 → define interface
+├── src/api/users.controller.ts:89 → use `unknown`
+└── src/services/email.ts:12 → define `EmailOptions` interface
+
+Return Types: ⚠️ 2 exported functions missing return types
+├── src/utils/helpers.ts:getConfig() → add `: AppConfig`
+└── src/utils/helpers.ts:parseInput() → add `: ParsedInput`
+
 Verdict: ❌ CHANGES REQUESTED
 
 ⚠️ Phase cannot complete until issues are fixed.
@@ -730,7 +751,10 @@ Verdict: ❌ CHANGES REQUESTED
 **Actions on failure:**
 1. Add missing test files
 2. Fix security issues
-3. Re-run `/tlc:build {phase}` to retry
+3. Split oversized files (>1000 lines) into focused sub-modules
+4. Replace `any` types with proper interfaces or `unknown`
+5. Add explicit return types to all exported functions
+6. Re-run `/tlc:build {phase}` to retry
 
 **CRITICAL: Phase is NOT complete until review passes.**
 

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

@@ -12,6 +12,10 @@ Automatically fix all coding standards violations. No prompts - just fixes every
    - Extracts inline interfaces to types/ files
    - Replaces magic strings with constants
    - Adds missing JSDoc comments
+   - **Splits oversized files** (>1000 lines) into focused sub-modules
+   - **Organizes overcrowded folders** (>15 files) into domain subfolders
+   - **Replaces `any` types** with proper interfaces or `unknown`
+   - **Adds missing return types** to exported functions
 4. Commits after each module/entity
 5. Reports results when done
 
@@ -101,6 +105,72 @@ export function getUser(id: string): User { }
 export function getUser(id: string): User { }
 ```
 
+#### Oversized Files (>1000 lines)
+```
+// Before: csp.controller.ts (2,041 lines)
+// Analyze the file's responsibilities and split by feature:
+
+// After:
+modules/csp/
+  controllers/
+    policy.controller.ts      # Policy CRUD routes
+    report.controller.ts      # Violation report routes
+    directive.controller.ts   # Directive management routes
+  csp.routes.ts               # Thin route registration
+  csp.service.ts              # Shared business logic
+```
+
+**Split strategy:**
+1. Count exported functions/methods and group by feature
+2. Create a controller/service per feature group
+3. Keep a thin "facade" file that re-exports or registers all routes
+4. Move shared helpers to a utils file within the module
+
+#### Overcrowded Folders (>15 files)
+```
+// Before: controllers/ with 22 files
+// Group by domain:
+
+// After:
+modules/
+  auth/       # auth.controller.ts, auth.service.ts
+  user/       # user.controller.ts, user.service.ts
+  billing/    # payment.controller.ts, invoice.controller.ts
+  catalog/    # product.controller.ts, category.controller.ts
+```
+
+#### `any` Type Replacement
+```typescript
+// Before
+function processData(data: any): any {
+  return data.items;
+}
+
+// After
+interface ProcessInput {
+  items: unknown[];
+}
+
+function processData(data: ProcessInput): unknown[] {
+  return data.items;
+}
+```
+
+**Strategy:** Read how the variable is used, infer the shape, create an interface.
+
+#### Missing Return Types
+```typescript
+// Before
+export function calculateTotal(items: CartItem[]) {
+  return items.reduce((sum, item) => sum + item.price, 0);
+}
+
+// After
+export function calculateTotal(items: CartItem[]): number {
+  return items.reduce((sum, item) => sum + item.price, 0);
+}
+```
+
 ### Step 4: Commit After Each Module
 
 After fixing all issues in an entity/module:

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

@@ -0,0 +1,138 @@
+# /tlc:dashboard - TLC Dashboard Container
+
+Manage the TLC dashboard as a standalone Docker container in any project.
+
+## Instructions for Claude
+
+### Step 1: Parse Arguments
+
+The user may pass a subcommand:
+
+```
+/tlc:dashboard              → start (default)
+/tlc:dashboard stop         → stop
+/tlc:dashboard rebuild      → rebuild with latest TLC
+/tlc:dashboard logs         → tail logs
+/tlc:dashboard status       → show container status
+```
+
+### Step 2: Ensure docker-compose.tlc.yml Exists
+
+Check if `docker-compose.tlc.yml` exists in the project root.
+
+**If it does NOT exist:**
+
+1. Find the TLC package directory:
+   ```bash
+   TLC_DIR=$(node -e "try { console.log(require.resolve('tlc-claude-code/package.json').replace('/package.json','')) } catch(e) { console.log('') }")
+   ```
+   If empty, try global:
+   ```bash
+   TLC_DIR=$(npm root -g)/tlc-claude-code
+   ```
+
+2. Copy the template:
+   ```bash
+   cp "$TLC_DIR/templates/docker-compose.tlc.yml" ./docker-compose.tlc.yml
+   ```
+
+3. If template not found, generate it inline (see Template section below).
+
+4. Tell the user:
+   ```
+   Created docker-compose.tlc.yml in your project root.
+   This file is YOURS — customize it freely. TLC will never overwrite it.
+   ```
+
+**If it already exists:** Use it as-is. Never modify the user's file.
+
+### Step 3: Execute Subcommand
+
+**start (default):**
+```bash
+docker compose -f docker-compose.tlc.yml up -d
+```
+
+Then show:
+```
+TLC Dashboard running at http://localhost:3147
+
+  Stop:    /tlc:dashboard stop
+  Logs:    /tlc:dashboard logs
+  Rebuild: /tlc:dashboard rebuild
+```
+
+**stop:**
+```bash
+docker compose -f docker-compose.tlc.yml down
+```
+
+**rebuild:**
+```bash
+docker compose -f docker-compose.tlc.yml build --no-cache
+docker compose -f docker-compose.tlc.yml up -d
+```
+
+**logs:**
+```bash
+docker compose -f docker-compose.tlc.yml logs -f --tail 50 dashboard
+```
+
+**status:**
+```bash
+docker compose -f docker-compose.tlc.yml ps
+```
+
+### Step 4: Verify
+
+After `start` or `rebuild`, check the dashboard is serving the React SPA:
+
+```bash
+# Wait a few seconds for startup
+sleep 5
+curl -s http://localhost:3147 | head -5
+```
+
+If it contains `<div id="root">` → React SPA is running.
+If it contains the old static HTML → warn the user that TLC needs updating.
+
+---
+
+## Template
+
+The `docker-compose.tlc.yml` template contains only the dashboard service:
+
+```yaml
+# TLC Dashboard
+# This file is yours — customize freely. TLC will never overwrite it.
+# Docs: https://github.com/jurgencalleja/TLC/wiki/devserver
+
+services:
+  dashboard:
+    image: node:20-alpine
+    container_name: tlc-dashboard
+    working_dir: /project
+    command: >
+      sh -c "
+        npm install -g tlc-claude-code@latest &&
+        TLC_DIR=$$(npm root -g)/tlc-claude-code &&
+        cd /project && node $$TLC_DIR/server/index.js
+      "
+    environment:
+      - TLC_PORT=3147
+      - TLC_AUTH=false
+    ports:
+      - "${DASHBOARD_PORT:-3147}:3147"
+    volumes:
+      - .:/project
+    restart: on-failure
+```
+
+---
+
+## Important Notes
+
+- The compose file belongs to the USER. Never overwrite or modify it.
+- If the user has customized ports, environment, or volumes — respect that.
+- The dashboard serves the React SPA from `dashboard-web/dist/` (included in npm package since v1.8.1).
+- This is independent from `/tlc:start` which manages the full dev environment (app, db, storage).

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

@@ -17,6 +17,12 @@ Research and create implementation plans with clear tasks.
 - **Error boundaries**: Where can failures occur? How are they handled?
 - **Data flow**: How does data enter, transform, and exit the system?
 
+### Code Quality Gates
+- **File size limit**: No file should exceed 1000 lines. Plan splits for large modules.
+- **Folder limit**: No folder should exceed 15 files. Plan domain subfolders.
+- **Strict typing**: Plan interfaces upfront — no `any` types, explicit return types.
+- **Module structure**: Group by domain entity (NestJS-style), not by file type.
+
 ### Task Breakdown
 - **Vertical slices**: Each task delivers testable, visible progress
 - **Risk-first**: Tackle unknowns and integrations early
@@ -61,6 +67,13 @@ Each task should be:
 - **Small** - completable in one focused session
 - **Testable** - has clear pass/fail criteria
 - **Independent** - minimal dependencies on other tasks
+- **Standards-compliant** - won't produce files >1000 lines or folders >15 files
+
+**Before finalizing tasks, check:**
+1. Will any planned file exceed 1000 lines? → Split into sub-modules
+2. Will any folder exceed 15 files? → Plan domain subfolders
+3. Are all interfaces defined? → Add `interfaces/` directory per module
+4. Are types explicit? → Plan typed interfaces, not `any`
 
 #### Task Status Markers (Multi-User)
 
@@ -82,12 +95,15 @@ Use `/tlc:claim` to claim a task, `/tlc:release` to release one.
 **Goal:** Define database schema for users table
 
 **Files:**
-- src/db/schema/users.ts
+- src/modules/user/interfaces/user.interface.ts
+- src/modules/user/user.repository.ts
 
 **Acceptance Criteria:**
 - [ ] Schema has id, email, passwordHash, createdAt
 - [ ] Email is unique
 - [ ] Timestamps auto-populate
+- [ ] All types explicit (no `any`)
+- [ ] Exported functions have return types
 
 **Test Cases:**
 - Schema validates correct user data

package/.claude/commands/tlc/review-pr.md

@@ -42,6 +42,7 @@ Same checks as `/tlc:review`:
 - Test coverage for changed files
 - TDD compliance (commit order)
 - Security scan
+- **Coding standards** (file size, folder size, strict typing, return types, module structure)
 
 ### Step 4: Generate PR Comment
 
@@ -53,12 +54,17 @@ Same checks as `/tlc:review`:
 | Test Coverage | ✅ All files covered |
 | TDD Score | ✅ 75% |
 | Security | ✅ No issues |
+| File Sizes | ✅ All under 1000 lines |
+| Folder Sizes | ✅ All under 15 files |
+| Strict Typing | ✅ No `any` types |
+| Return Types | ✅ All exports typed |
 
 ### Summary
 
 - 8 files changed (5 impl, 3 tests)
 - 4 commits analyzed
 - No security vulnerabilities detected
+- All coding standards met
 
 ### Verdict: ✅ APPROVED
 
@@ -134,6 +140,12 @@ TDD Score: 0% ❌
 Security: ⚠️ 1 medium severity issue
 └── console.log with sensitive data
 
+Coding Standards: ❌ 4 issues
+├── src/auth/login.js (1,247 lines) → split by feature
+├── src/auth/login.js:45 → `any` type found
+├── src/auth/login.js:89 → `any` type found
+└── src/config.js:getConfig() → missing return type
+
 Posting review...
 
 ─────────────────────────────────
@@ -145,6 +157,9 @@ See: https://github.com/org/repo/pull/43#review-123457
 Required actions:
 1. Add/update tests for modified files
 2. Remove console.log with sensitive data
+3. Split oversized file (>1000 lines)
+4. Replace `any` types with proper interfaces
+5. Add return types to exported functions
 ─────────────────────────────────
 ```
 

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

@@ -112,6 +112,65 @@ Scan diff for common security issues:
 
 **Fail if:** Any HIGH severity issues found.
 
+### Step 5b: Coding Standards Check
+
+Scan all changed/added files for coding standards violations:
+
+#### File Size Check
+```bash
+# For each changed implementation file
+wc -l <file>
+# >1000 lines = ERROR, 500-1000 = WARNING
+```
+
+#### Folder Size Check
+```bash
+# For each folder containing changed files
+ls <folder> | wc -l
+# >15 files = ERROR, 8-15 = WARNING
+```
+
+#### Strict Typing Check
+```bash
+# Scan changed .ts/.tsx files for `any` type
+grep -n ': any' <file>
+grep -n 'as any' <file>
+grep -n '<any>' <file>
+# Any match = ERROR
+```
+
+#### Return Type Check
+```bash
+# Scan changed .ts/.tsx files for exported functions missing return types
+# Pattern: export function name(params) {   (no : ReturnType before {)
+grep -n 'export function.*)[[:space:]]*{' <file>
+grep -n 'export const.*=.*=>.*{' <file>
+# Missing return type on exported function = WARNING
+```
+
+#### Module Structure Check
+```
+# Flag flat folder anti-patterns in changed files:
+# - src/services/ with >5 unrelated services → should be modules/{entity}/
+# - src/controllers/ with >5 controllers → should be modules/{entity}/
+# - src/interfaces/ at project root → should be per-module interfaces/
+```
+
+**Standards results in report:**
+```
+Coding Standards:
+  File Sizes: ✅ All under 1000 lines
+  Folder Sizes: ✅ All under 15 files
+  Strict Typing: ❌ 3 `any` types found
+  ├── src/api/users.controller.ts:45
+  ├── src/api/users.controller.ts:89
+  └── src/services/email.ts:12
+  Return Types: ⚠️ 2 missing on exports
+  Module Structure: ✅ Domain-grouped
+```
+
+**Fail if:** Any `any` types in new code, or files >1000 lines.
+
 ### Step 6: Invoke External Providers (Codex, Gemini)
 
 **CRITICAL: This step runs automatically when providers are configured.**
@@ -220,6 +279,9 @@ Invoking Codex (GPT-5.2) for review...
 - ✅ All changed files have tests
 - ✅ TDD score: 75%
 - ✅ No security issues detected
+- ✅ All files under 1000 lines
+- ✅ No `any` types
+- ✅ All exports have return types
 
 ## Statistics