tlc-claude-code 1.4.9 → 1.5.2

package/CLAUDE.md

@@ -112,3 +112,26 @@ When working with teammates:
 - The USER is the author. Claude is a tool, not an author.
 
 **ALWAYS ask before `git push`.** Never push to remote without explicit user approval.
+
+---
+
+<!-- TLC-STANDARDS -->
+
+## Code Quality (TLC)
+
+This project follows TLC (Test-Led Coding) code quality standards. See [CODING-STANDARDS.md](./CODING-STANDARDS.md) for detailed guidelines.
+
+### Quick Reference
+
+**Module Structure:** Code lives in `server/lib/` - each module is a self-contained `.js` file with corresponding `.test.js` test file.
+
+### Key Rules
+
+1. **Test-first development** - Tests are written BEFORE implementation
+2. **No hardcoded URLs or config** - Use environment variables
+3. **JSDoc required** - Document all exported functions
+4. **Paired test files** - Every `module.js` has a `module.test.js`
+
+### Standards Reference
+
+For complete standards including file naming, import rules, error handling patterns, and service design guidelines, see [CODING-STANDARDS.md](./CODING-STANDARDS.md).

package/CODING-STANDARDS.md

@@ -0,0 +1,408 @@
+# TLC Coding Standards
+
+This document defines the coding standards for projects using TLC (Test-Led Coding).
+
+## Module Structure
+
+Organize code by **entity**, not by type. Each entity gets its own folder with consistent substructure.
+
+### Correct Structure
+
+```
+src/
+  {entity}/
+    types/           # TypeScript interfaces and types
+    schemas/         # Validation schemas (Zod, Joi, etc.)
+    constants/       # Entity-specific constants
+    {entity}.service.js
+    {entity}.controller.js
+    {entity}.repository.js
+    {entity}.seed.js
+```
+
+### Examples
+
+```
+src/
+  user/
+    types/
+      user.types.ts
+      user-response.types.ts
+    schemas/
+      create-user.schema.ts
+      update-user.schema.ts
+    constants/
+      user.constants.ts
+    user.service.ts
+    user.controller.ts
+    user.repository.ts
+    user.seed.ts
+  order/
+    types/
+      order.types.ts
+    schemas/
+      create-order.schema.ts
+    constants/
+      order-status.constants.ts
+    order.service.ts
+    order.controller.ts
+```
+
+### Never Do This
+
+```
+src/
+  services/          # NO - flat service folder
+    user.service.ts
+    order.service.ts
+  interfaces/        # NO - flat interface folder
+    user.interface.ts
+    order.interface.ts
+  types/             # NO - flat types folder
+```
+
+## Type Definitions
+
+### Types in Separate Files
+
+All types must be in dedicated files under `types/` folder.
+
+```typescript
+// CORRECT: src/user/types/user.types.ts
+export interface User {
+  id: string;
+  email: string;
+  name: string;
+}
+
+export interface CreateUserInput {
+  email: string;
+  name: string;
+}
+```
+
+### Never Inline Types in Services
+
+```typescript
+// WRONG: Inline interface in service
+export class UserService {
+  async createUser(input: { email: string; name: string }): Promise<{ id: string; email: string }> {
+    // ...
+  }
+}
+
+// CORRECT: Import types from types folder
+import { CreateUserInput, User } from './types/user.types.js';
+
+export class UserService {
+  async createUser(input: CreateUserInput): Promise<User> {
+    // ...
+  }
+}
+```
+
+## Validation Schemas
+
+Place all validation schemas in the `schemas/` folder.
+
+```typescript
+// src/user/schemas/create-user.schema.ts
+import { z } from 'zod';
+
+export const createUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1).max(100),
+});
+
+export type CreateUserInput = z.infer<typeof createUserSchema>;
+```
+
+## Constants
+
+### No Magic Strings
+
+All repeated values must be defined as constants.
+
+```typescript
+// WRONG: Magic strings
+if (user.role === 'admin') { ... }
+if (status === 'pending') { ... }
+
+// CORRECT: Use constants
+import { UserRole } from './constants/user.constants.js';
+import { OrderStatus } from '../order/constants/order-status.constants.js';
+
+if (user.role === UserRole.ADMIN) { ... }
+if (status === OrderStatus.PENDING) { ... }
+```
+
+### Constants File Structure
+
+```typescript
+// src/user/constants/user.constants.ts
+export const UserRole = {
+  ADMIN: 'admin',
+  USER: 'user',
+  GUEST: 'guest',
+} as const;
+
+export type UserRole = typeof UserRole[keyof typeof UserRole];
+
+export const USER_DEFAULTS = {
+  MAX_LOGIN_ATTEMPTS: 5,
+  SESSION_TIMEOUT_MS: 3600000,
+} as const;
+```
+
+## Configuration
+
+### No Hardcoded Values
+
+Configuration values must come from environment variables.
+
+```typescript
+// WRONG: Hardcoded URL
+const API_URL = 'https://api.example.com';
+
+// CORRECT: From environment
+const API_URL = process.env.API_URL;
+
+// BETTER: Validated config module
+import { config } from './config.js';
+const apiUrl = config.apiUrl; // Validated at startup
+```
+
+### Config Module Pattern
+
+```typescript
+// src/config.ts
+import { z } from 'zod';
+
+const configSchema = z.object({
+  apiUrl: z.string().url(),
+  port: z.coerce.number().default(3000),
+  nodeEnv: z.enum(['development', 'production', 'test']),
+});
+
+export const config = configSchema.parse({
+  apiUrl: process.env.API_URL,
+  port: process.env.PORT,
+  nodeEnv: process.env.NODE_ENV,
+});
+```
+
+## Seed Files
+
+Each entity should have its own seed file for test and development data.
+
+```typescript
+// src/user/user.seed.ts
+import { User } from './types/user.types.js';
+
+export const userSeeds: User[] = [
+  { id: '1', email: 'admin@example.com', name: 'Admin User' },
+  { id: '2', email: 'user@example.com', name: 'Regular User' },
+];
+
+export async function seedUsers(repository: UserRepository): Promise<void> {
+  for (const user of userSeeds) {
+    await repository.create(user);
+  }
+}
+```
+
+## JSDoc Requirements
+
+All public members must have JSDoc documentation.
+
+### Functions
+
+```typescript
+/**
+ * Creates a new user in the system.
+ * @param input - The user creation input data
+ * @returns The created user with generated ID
+ * @throws {ValidationError} If input fails validation
+ * @throws {DuplicateError} If email already exists
+ */
+export async function createUser(input: CreateUserInput): Promise<User> {
+  // ...
+}
+```
+
+### Classes
+
+```typescript
+/**
+ * Service for managing user operations.
+ * Handles user CRUD operations and authentication.
+ */
+export class UserService {
+  /**
+   * Creates a new UserService instance.
+   * @param repository - The user repository for data access
+   * @param eventBus - Event bus for publishing user events
+   */
+  constructor(
+    private repository: UserRepository,
+    private eventBus: EventBus
+  ) {}
+}
+```
+
+### Interfaces
+
+```typescript
+/**
+ * Represents a user in the system.
+ */
+export interface User {
+  /** Unique identifier */
+  id: string;
+  /** User's email address (unique) */
+  email: string;
+  /** User's display name */
+  name: string;
+  /** Account creation timestamp */
+  createdAt: Date;
+}
+```
+
+## File Naming Conventions
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Service | `{entity}.service.ts` | `user.service.ts` |
+| Controller | `{entity}.controller.ts` | `user.controller.ts` |
+| Repository | `{entity}.repository.ts` | `user.repository.ts` |
+| Types | `{entity}.types.ts` | `user.types.ts` |
+| Schema | `{action}-{entity}.schema.ts` | `create-user.schema.ts` |
+| Constants | `{entity}.constants.ts` | `user.constants.ts` |
+| Seed | `{entity}.seed.ts` | `user.seed.ts` |
+| Tests | `{file}.test.ts` | `user.service.test.ts` |
+
+## Import Rules
+
+### Use Path Aliases
+
+```typescript
+// CORRECT: Path alias
+import { User } from '@/user/types/user.types.js';
+
+// AVOID: Deep relative paths
+import { User } from '../../../user/types/user.types.js';
+```
+
+### Import Order
+
+1. Node built-ins (`fs`, `path`, `crypto`)
+2. External packages (`express`, `zod`)
+3. Internal modules using path aliases
+4. Relative imports (same module only)
+
+```typescript
+import { readFile } from 'fs/promises';
+
+import express from 'express';
+import { z } from 'zod';
+
+import { logger } from '@/lib/logger.js';
+import { config } from '@/config.js';
+
+import { UserService } from './user.service.js';
+import { User } from './types/user.types.js';
+```
+
+## Service Design
+
+### Single Responsibility
+
+Each service handles one entity or domain concept.
+
+```typescript
+// CORRECT: Single responsibility
+class UserService { /* user operations only */ }
+class AuthService { /* authentication only */ }
+class EmailService { /* email sending only */ }
+
+// WRONG: Mixed responsibilities
+class UserService {
+  sendEmail() { /* NO */ }
+  authenticate() { /* NO */ }
+}
+```
+
+### Dependency Injection
+
+Services receive dependencies through constructor.
+
+```typescript
+export class UserService {
+  constructor(
+    private repository: UserRepository,
+    private emailService: EmailService,
+    private eventBus: EventBus
+  ) {}
+}
+```
+
+## Error Handling
+
+### Custom Error Classes
+
+```typescript
+// src/lib/errors/index.ts
+export class AppError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public statusCode: number = 500
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(entity: string, id: string) {
+    super(`${entity} not found: ${id}`, 'NOT_FOUND', 404);
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(message: string, public details?: unknown) {
+    super(message, 'VALIDATION_ERROR', 400);
+  }
+}
+```
+
+### Error Handling in Services
+
+```typescript
+async function getUser(id: string): Promise<User> {
+  const user = await repository.findById(id);
+  if (!user) {
+    throw new NotFoundError('User', id);
+  }
+  return user;
+}
+```
+
+### Error Handling in Controllers
+
+```typescript
+app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
+  if (err instanceof AppError) {
+    return res.status(err.statusCode).json({
+      error: err.code,
+      message: err.message,
+    });
+  }
+
+  logger.error('Unhandled error', { error: err });
+  return res.status(500).json({
+    error: 'INTERNAL_ERROR',
+    message: 'An unexpected error occurred',
+  });
+});
+```

package/bin/install.js

@@ -65,6 +65,8 @@ const COMMANDS = [
   // Multi-Tool & Deployment
   'export.md',
   'deploy.md',
+  // Multi-Model
+  'llm.md',
   // Help
   'help.md'
 ];

package/dashboard/dist/components/QualityGatePane.d.ts

@@ -0,0 +1,38 @@
+interface ThresholdConfig {
+    default: number;
+    dimensions?: Record<string, number>;
+}
+interface QualityGateConfig {
+    preset: string;
+    thresholds: ThresholdConfig;
+}
+interface EvaluationResult {
+    file: string;
+    pass: boolean;
+    composite: number;
+    scores?: Record<string, number>;
+    failed?: string[];
+}
+interface TrendData {
+    direction: 'improving' | 'declining' | 'stable';
+    slope: number;
+}
+interface HistoryRecord {
+    composite: number;
+    timestamp?: Date;
+}
+interface QualityGatePaneProps {
+    config?: QualityGateConfig;
+    evaluations?: EvaluationResult[];
+    currentEvaluation?: EvaluationResult;
+    history?: HistoryRecord[];
+    trend?: TrendData;
+    presets?: string[];
+    loading?: boolean;
+    error?: string;
+    onConfigure?: () => void;
+    onChangePreset?: (preset: string) => void;
+    onRetry?: () => void;
+}
+export declare function QualityGatePane({ config, evaluations, currentEvaluation, history, trend, presets, loading, error, onConfigure, onChangePreset, onRetry, }: QualityGatePaneProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dashboard/dist/components/QualityGatePane.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+export function QualityGatePane({ config, evaluations = [], currentEvaluation, history = [], trend, presets = ['fast', 'balanced', 'thorough', 'critical'], loading, error, onConfigure, onChangePreset, onRetry, }) {
+    if (loading) {
+        return (_jsxs(Box, { padding: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: "Quality Gate" }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "gray", children: "Loading..." }) })] }));
+    }
+    if (error) {
+        return (_jsxs(Box, { padding: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: "Quality Gate" }), _jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: "red", children: ["Error: ", error] }) })] }));
+    }
+    const getScoreColor = (score, threshold = 70) => {
+        if (score >= threshold)
+            return 'green';
+        if (score >= threshold - 15)
+            return 'yellow';
+        return 'red';
+    };
+    const getTrendArrow = (direction) => {
+        switch (direction) {
+            case 'improving':
+                return '↑';
+            case 'declining':
+                return '↓';
+            default:
+                return '→';
+        }
+    };
+    return (_jsxs(Box, { padding: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: "Quality Gate" }), config && (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { dimColor: true, children: "Preset: " }), _jsx(Text, { color: "cyan", children: config.preset })] }), _jsxs(Box, { children: [_jsx(Text, { dimColor: true, children: "Threshold: " }), _jsxs(Text, { children: [config.thresholds.default, "%"] })] })] })), config?.thresholds?.dimensions && (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, dimColor: true, children: "Dimension Thresholds:" }), Object.entries(config.thresholds.dimensions).map(([dim, threshold]) => (_jsxs(Box, { children: [_jsxs(Text, { children: ["  ", dim, ": "] }), _jsxs(Text, { color: "gray", children: [threshold, "%"] })] }, dim)))] })), currentEvaluation && (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, dimColor: true, children: "Current Evaluation:" }), _jsxs(Box, { children: [_jsxs(Text, { children: ["  ", currentEvaluation.file, ": "] }), _jsxs(Text, { color: currentEvaluation.pass ? 'green' : 'red', children: [currentEvaluation.composite, "% ", currentEvaluation.pass ? '✓' : '✗'] })] }), currentEvaluation.scores && (_jsx(Box, { flexDirection: "column", marginLeft: 2, children: Object.entries(currentEvaluation.scores).map(([dim, score]) => {
+                            const isFailing = currentEvaluation.failed?.includes(dim);
+                            return (_jsx(Box, { children: _jsxs(Text, { color: isFailing ? 'red' : 'gray', children: [dim, ": ", score, "%"] }) }, dim));
+                        }) })), !currentEvaluation.pass && onRetry && (_jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "yellow", children: "[Retry] \u21BB" }) }))] })), evaluations.length > 0 && (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, dimColor: true, children: "Recent Evaluations:" }), evaluations.slice(0, 5).map((evalResult, idx) => (_jsxs(Box, { children: [_jsx(Text, { color: evalResult.pass ? 'green' : 'red', children: evalResult.pass ? '✓' : '✗' }), _jsxs(Text, { children: [" ", evalResult.file.split('/').pop(), ": "] }), _jsxs(Text, { color: getScoreColor(evalResult.composite, config?.thresholds?.default || 70), children: [evalResult.composite, "%"] })] }, idx)))] })), trend && (_jsxs(Box, { marginTop: 1, children: [_jsx(Text, { dimColor: true, children: "Trend: " }), _jsxs(Text, { color: trend.direction === 'improving' ? 'green' : trend.direction === 'declining' ? 'red' : 'gray', children: [getTrendArrow(trend.direction), " ", trend.direction] })] })), _jsx(Box, { marginTop: 1, children: onConfigure && (_jsx(Text, { color: "blue", children: "[Configure]" })) })] }));
+}

package/dashboard/dist/components/QualityGatePane.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dashboard/dist/components/QualityGatePane.test.js

@@ -0,0 +1,147 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { describe, it, expect, vi } from 'vitest';
+import { render } from 'ink-testing-library';
+import { QualityGatePane } from './QualityGatePane.js';
+describe('QualityGatePane', () => {
+    it('renders without error', () => {
+        const { lastFrame } = render(_jsx(QualityGatePane, {}));
+        expect(lastFrame()).toBeDefined();
+    });
+    it('renders current preset', () => {
+        const config = {
+            preset: 'balanced',
+            thresholds: { default: 70 },
+        };
+        const { lastFrame } = render(_jsx(QualityGatePane, { config: config }));
+        const output = lastFrame();
+        expect(output).toContain('balanced');
+    });
+    it('renders threshold bars', () => {
+        const config = {
+            preset: 'balanced',
+            thresholds: {
+                default: 70,
+                dimensions: {
+                    style: 80,
+                    correctness: 90,
+                },
+            },
+        };
+        const { lastFrame } = render(_jsx(QualityGatePane, { config: config }));
+        const output = lastFrame();
+        expect(output).toContain('70');
+        expect(output).toContain('80');
+        expect(output).toContain('90');
+    });
+    it('renders trend chart with history', () => {
+        const config = { preset: 'balanced', thresholds: { default: 70 } };
+        const history = [
+            { composite: 65, timestamp: new Date('2024-01-01') },
+            { composite: 70, timestamp: new Date('2024-01-02') },
+            { composite: 75, timestamp: new Date('2024-01-03') },
+        ];
+        const { lastFrame } = render(_jsx(QualityGatePane, { config: config, history: history }));
+        const output = lastFrame();
+        // Should show some trend visualization
+        expect(output).toBeDefined();
+    });
+    it('renders evaluations list with recent items', () => {
+        const config = { preset: 'balanced', thresholds: { default: 70 } };
+        const evaluations = [
+            { file: 'src/index.js', pass: true, composite: 85 },
+            { file: 'src/utils.js', pass: false, composite: 60 },
+        ];
+        const { lastFrame } = render(_jsx(QualityGatePane, { config: config, evaluations: evaluations }));
+        const output = lastFrame();
+        expect(output).toContain('index.js');
+        expect(output).toContain('utils.js');
+    });
+    it('renders configure button', () => {
+        const onConfigure = vi.fn();
+        const { lastFrame } = render(_jsx(QualityGatePane, { config: { preset: 'fast', thresholds: { default: 60 } }, onConfigure: onConfigure }));
+        const output = lastFrame();
+        expect(output).toBeDefined();
+    });
+    it('renders preset selector', () => {
+        const onChangePreset = vi.fn();
+        const { lastFrame } = render(_jsx(QualityGatePane, { config: { preset: 'balanced', thresholds: { default: 70 } }, presets: ['fast', 'balanced', 'thorough', 'critical'], onChangePreset: onChangePreset }));
+        const output = lastFrame();
+        // Should show preset options or current preset
+        expect(output).toContain('balanced');
+    });
+    it('renders retry button when evaluation fails', () => {
+        const onRetry = vi.fn();
+        const evaluation = { file: 'test.js', pass: false, composite: 50 };
+        const { lastFrame } = render(_jsx(QualityGatePane, { config: { preset: 'balanced', thresholds: { default: 70 } }, currentEvaluation: evaluation, onRetry: onRetry }));
+        const output = lastFrame();
+        expect(output).toBeDefined();
+    });
+    it('handles loading state', () => {
+        const { lastFrame } = render(_jsx(QualityGatePane, { config: { preset: 'balanced', thresholds: { default: 70 } }, loading: true }));
+        const output = lastFrame();
+        expect(output).toBeDefined();
+    });
+    it('handles error state', () => {
+        const { lastFrame } = render(_jsx(QualityGatePane, { config: { preset: 'balanced', thresholds: { default: 70 } }, error: "Failed to load quality data" }));
+        const output = lastFrame();
+        expect(output).toBeDefined();
+    });
+    it('handles empty history', () => {
+        const { lastFrame } = render(_jsx(QualityGatePane, { config: { preset: 'balanced', thresholds: { default: 70 } }, history: [] }));
+        const output = lastFrame();
+        expect(output).toBeDefined();
+        // Should show empty state or placeholder
+    });
+    it('shows pass/fail indicator for evaluations', () => {
+        const evaluations = [
+            { file: 'pass.js', pass: true, composite: 85 },
+            { file: 'fail.js', pass: false, composite: 55 },
+        ];
+        const { lastFrame } = render(_jsx(QualityGatePane, { config: { preset: 'balanced', thresholds: { default: 70 } }, evaluations: evaluations }));
+        const output = lastFrame();
+        expect(output).toBeDefined();
+    });
+    it('shows dimension breakdown', () => {
+        const evaluation = {
+            file: 'test.js',
+            pass: true,
+            composite: 82,
+            scores: {
+                style: 80,
+                completeness: 85,
+                correctness: 90,
+                documentation: 75,
+            },
+        };
+        const { lastFrame } = render(_jsx(QualityGatePane, { config: { preset: 'balanced', thresholds: { default: 70 } }, currentEvaluation: evaluation }));
+        const output = lastFrame();
+        expect(output).toBeDefined();
+    });
+    it('highlights failing dimensions', () => {
+        const evaluation = {
+            file: 'test.js',
+            pass: false,
+            composite: 65,
+            scores: {
+                style: 50,
+                correctness: 80,
+            },
+            failed: ['style'],
+        };
+        const { lastFrame } = render(_jsx(QualityGatePane, { config: { preset: 'balanced', thresholds: { default: 70 } }, currentEvaluation: evaluation }));
+        const output = lastFrame();
+        // Should highlight the failing dimension
+        expect(output).toBeDefined();
+    });
+    it('shows trend direction', () => {
+        const history = [
+            { composite: 60 },
+            { composite: 65 },
+            { composite: 70 },
+            { composite: 75 },
+        ];
+        const { lastFrame } = render(_jsx(QualityGatePane, { config: { preset: 'balanced', thresholds: { default: 70 } }, history: history, trend: { direction: 'improving', slope: 5 } }));
+        const output = lastFrame();
+        expect(output).toBeDefined();
+    });
+});

package/dashboard/dist/components/orchestration/AgentCard.d.ts

@@ -0,0 +1,26 @@
+type AgentStatus = 'running' | 'queued' | 'completed' | 'failed' | 'paused' | 'cancelled';
+interface AgentTokens {
+    input: number;
+    output: number;
+}
+interface QualityInfo {
+    score: number;
+    pass: boolean;
+}
+interface Agent {
+    id: string;
+    name?: string;
+    model: string;
+    status: AgentStatus;
+    startTime: Date;
+    tokens: AgentTokens;
+    cost: number;
+    quality?: QualityInfo;
+}
+interface AgentCardProps {
+    agent: Agent;
+    onClick?: () => void;
+    selected?: boolean;
+}
+export declare function AgentCard({ agent, onClick, selected }: AgentCardProps): import("react/jsx-runtime").JSX.Element;
+export {};