Refactoring

Refactoring

Safe, systematic refactoring procedures for the @dotcontext/cli codebase.

When to Use

• Extracting logic into a new service or utility
• Consolidating duplicate code across services or generators
• Restructuring MCP gateway handlers
• Improving type safety or removing any usage
• Simplifying complex functions (high cyclomatic complexity)
• Migrating between patterns (e.g., callback to async/await)

Pre-Refactoring Checklist

Before starting any refactoring:

• All tests pass: npm test
• Build succeeds: npm run build
• Create a branch or ensure changes can be reverted
• Identify all callers of the code being refactored (use grep or IDE references)

Common Refactoring Scenarios

Extracting a New Service

The project follows a directory-per-service pattern. To extract logic into a new service:

1. Create src/services/<name>/ directory
2. Create the service class:

// src/services/cache/cacheService.ts
export interface CacheServiceOptions {
  repoPath: string;
  cacheDir?: string;
}

export class CacheService {
  private readonly repoPath: string;
  private readonly cacheDir: string;

  constructor(options: CacheServiceOptions) {
    this.repoPath = options.repoPath;
    this.cacheDir = options.cacheDir || '.context/.cache';
  }

  async get(key: string): Promise<string | null> { /* ... */ }
  async set(key: string, value: string): Promise<void> { /* ... */ }
}

1. Create src/services/<name>/index.ts barrel:

export { CacheService, CacheServiceOptions } from './cacheService';

1. Update callers to import from the new service
2. Write tests in src/services/<name>/cacheService.test.ts

Splitting a Large Gateway Handler

Gateway handlers in src/services/mcp/gateway/ can grow large. To split:

1. Identify action groups that share logic
2. Extract helper functions within the same file first
3. If helpers grow, extract into a separate utility or service
4. Keep the main handler function as a thin dispatcher: