03-typescript-safety

03-TypeScript-Safety

Type System Configuration

The project uses strict TypeScript configuration in tsconfig.json with ESNext modules and strict type checking.

Central Type Definitions

All types are centrally defined in types/index.ts and must be imported from there.

CRITICAL TYPE SAFETY RULES - MUST FOLLOW

✅ ALWAYS DO:

1. Import from central types: import { AgentClient, AgentStatus } from '../types/index.js'
2. Use strict type annotations: Define return types for all public methods
3. Validate enum usage: Always use enum values, never string literals
4. Type guard functions: Implement type guards for runtime type checking
5. Generic constraints: Use proper generic constraints for extensibility

❌ NEVER DO:

1. Use any type: Avoid any - use unknown or proper types instead
2. Skip type annotations: Never omit return types on public methods
3. String literal enums: Use enum values like AgentStatus.CONNECTED, not 'connected'
4. Bypass type checking: Never use as any or @ts-ignore without justification
5. Ignore nullable types: Always handle undefined/null cases explicitly

Enum Usage Standards

✅ CORRECT Enum Usage:

// Import from central types
import { AgentClientType, AgentStatus } from '../types/index.js';

// Use enum values
client.status = AgentStatus.CONNECTED;
if (client.type === AgentClientType.CLAUDE_CODE) { ... }

// Type-safe enum iteration
Object.values(AgentClientType).forEach(type => { ... });

❌ INCORRECT Enum Usage:

// Bad - string literals
client.status = 'connected';
if (client.type === 'claude-code') { ... }

// Bad - hardcoded values
const types = ['claude-code', 'gemini-cli'];

Interface Implementation Standards

Required Interface Patterns:

// Tool definitions must implement ToolDefinition
export interface ToolDefinition {
  name: string;
  description: string;
  inputSchema: {
    type: string;
    properties: Record<string, any>;
    required?: string[];
  };
  clientTypes?: AgentClientType[];
  handler: (args: any, client: AgentClient) => Promise<any>;
}

// Resource definitions must implement ResourceDefinition  
export interface ResourceDefinition {
  uri: string;
  name: string;
  description: string;
  mimeType: string;
  clientTypes?: AgentClientType[];
  handler: (client: AgentClient) => Promise<any>;
}