feat: Migrate profile system from object literals to immutable ProfileBuilder architecture #287

New issue

Open

opened 2025-10-14 15:48:12 -06:00 by navan · 0 comments

navan commented

2025-10-14 15:48:12 -06:00

Owner

Originally created by @joedanz on 7/18/2025

🎯 Overview

This PR completes a comprehensive architectural migration of the Task Master profile system, transforming 13 AI coding assistant profiles from scattered object literals to a modern, type-safe, immutable ProfileBuilder pattern. This migration enhances maintainability, consistency, and developer experience while maintaining full backward compatibility.

🚀 Key Features

ProfileBuilder Architecture

✅ Type-safe Profile creation with fluent API pattern
✅ Immutable Profile instances for enhanced reliability
✅ Centralized ProfileRegistry for consistent profile management
✅ Automatic default file mapping generation when includeDefaultRules: true
✅ Lifecycle hooks support for complex profile operations (onAdd, onRemove, onPost)

Enhanced Profile Capabilities

✅ Automatic MCP configuration handling with computed properties
✅ Rule transformation system with comprehensive conversion support
✅ Subdirectory support for organized rule management (e.g., Cursor's taskmaster/ subdirectory)
✅ Legacy format compatibility for seamless migration

🛠 Technical Improvements

Before (Legacy)

// Scattered, inconsistent object literals
const cursorProfile = {
  profileName: 'cursor',
  displayName: 'Cursor',
  profileDir: '.cursor',
  rulesDir: 'rules',
  // ... inconsistent patterns
};

After (ProfileBuilder)

// Type-safe, fluent, consistent
const cursorProfile = ProfileBuilder.minimal('cursor')
  .display('Cursor')
  .profileDir('.cursor')
  .rulesDir('rules')
  .mcpConfig(true)
  .includeDefaultRules(false)
  .supportsSubdirectories(true)
  .conversion({
    profileTerms: [/* transformations */],
    fileExtensions: [{ from: /\.mdc/g, to: '.md' }],
    // ... comprehensive conversion config
  })
  .build();

🎯 Major Fixes & Enhancements

Enhanced Rule Transformation

Null-safe property access in rule transformer functions
Comprehensive file extension handling (.mdc → .md)
Profile-specific term replacements and path transformations
Global replacement patterns for consistent rule conversion

MCP Configuration Management

Automatic MCP config path computation based on profile directory
Boolean/object hybrid handling for mcpConfig property
Legacy compatibility for existing MCP configurations

🧪 Testing Excellence

Test Categories

Unit tests for ProfileBuilder, Profile, and ProfileRegistry
Integration tests for all 13 profiles
Rule transformation tests for conversion accuracy
MCP configuration validation tests
Subdirectory support tests
Immutability tests for Profile instances

🔧 Implementation Details

Core Classes

ProfileBuilder: Fluent API for type-safe profile construction
Profile: Immutable profile instances with computed properties
ProfileRegistry: Centralized profile management and retrieval
ProfileAdapter: Legacy compatibility layer

Key Files Modified

src/profile/ProfileBuilder.js - Core builder implementation
src/profile/Profile.js - Immutable profile class with lifecycle support
src/profiles/*.js - All 13 profiles migrated to new architecture
src/utils/rule-transformer.js - Enhanced with null-safe operations
tests/ - Comprehensive test suite updates for new architecture

🔄 Backward Compatibility

✅ Legacy profile format support via ProfileAdapter
✅ Existing API compatibility maintained throughout migration
✅ Gradual migration path allows incremental adoption
✅ No breaking changes for existing consumers

🏆 Quality Assurance

Comprehensive linting compliance
Type safety throughout the profile system
Immutability enforced for Profile instances
Error handling for edge cases and malformed configurations
Performance optimizations through computed properties

🎉 Impact

This migration establishes a robust, maintainable foundation for the Task Master profile system, enabling:

Easier profile creation and maintenance
Consistent behavior across all AI coding assistants
Type safety preventing runtime errors
Enhanced developer experience with fluent APIs
Future extensibility for new profile features

Summary by CodeRabbit

New Features
- Introduced an immutable profile system with a fluent builder pattern for defining profiles, including lifecycle hooks, conversion rules, and legacy compatibility.
- Added a centralized singleton registry for profile management, supporting profile registration, retrieval, filtering, and statistics.
- Implemented custom error classes for profile validation, registration, not found, and operation errors.
Refactor
- Migrated all existing profiles to use the new builder pattern, enabling declarative configuration, enhanced conversion logic, and structured lifecycle hook support.
- Updated rule transformation utilities to work directly with Profile instances and added defensive checks for undefined configuration arrays.
- Consolidated lifecycle hooks under a unified hooks object with standardized method names.
- Refactored VS Code profile to manage schema integration via lifecycle hooks instead of manual file transformations.
- Reorganized lifecycle hook naming and grouping, replacing previous separate hook properties with a single hooks object.
Bug Fixes
- Added null and type checks in transformation utilities to prevent runtime errors from missing or malformed profile conversion configurations.
Tests
- Added extensive unit tests for Profile, ProfileBuilder, and ProfileRegistry classes.
- Updated integration and unit tests for all profiles to reflect new profile construction, lifecycle hook structure, and directory layout changes.
- Improved test reliability and mocking in configuration and utility modules.
- Adjusted tests to accommodate new lifecycle hook access patterns and directory structures for Task Master files.
Documentation
- Added comprehensive JSDoc type definitions describing profile configuration, conversion rules, lifecycle hooks, and operation results.

*Originally created by @joedanz on 7/18/2025* ## 🎯 **Overview** This PR completes a comprehensive architectural migration of the Task Master profile system, transforming 13 AI coding assistant profiles from scattered object literals to a modern, type-safe, immutable ProfileBuilder pattern. This migration enhances maintainability, consistency, and developer experience while maintaining full backward compatibility. ## 🚀 **Key Features** ### **ProfileBuilder Architecture** - ✅ **Type-safe Profile creation** with fluent API pattern - ✅ **Immutable Profile instances** for enhanced reliability - ✅ **Centralized ProfileRegistry** for consistent profile management - ✅ **Automatic default file mapping generation** when `includeDefaultRules: true` - ✅ **Lifecycle hooks support** for complex profile operations (onAdd, onRemove, onPost) ### **Enhanced Profile Capabilities** - ✅ **Automatic MCP configuration handling** with computed properties - ✅ **Rule transformation system** with comprehensive conversion support - ✅ **Subdirectory support** for organized rule management (e.g., Cursor's `taskmaster/` subdirectory) - ✅ **Legacy format compatibility** for seamless migration ## 🛠 **Technical Improvements** ### **Before (Legacy)** ```javascript // Scattered, inconsistent object literals const cursorProfile = { profileName: 'cursor', displayName: 'Cursor', profileDir: '.cursor', rulesDir: 'rules', // ... inconsistent patterns }; ``` ### **After (ProfileBuilder)** ```javascript // Type-safe, fluent, consistent const cursorProfile = ProfileBuilder.minimal('cursor') .display('Cursor') .profileDir('.cursor') .rulesDir('rules') .mcpConfig(true) .includeDefaultRules(false) .supportsSubdirectories(true) .conversion({ profileTerms: [/* transformations */], fileExtensions: [{ from: /\.mdc/g, to: '.md' }], // ... comprehensive conversion config }) .build(); ``` ## 🎯 **Major Fixes & Enhancements** ### **Enhanced Rule Transformation** - **Null-safe property access** in rule transformer functions - **Comprehensive file extension handling** (`.mdc` → `.md`) - **Profile-specific term replacements** and path transformations - **Global replacement patterns** for consistent rule conversion ### **MCP Configuration Management** - **Automatic MCP config path computation** based on profile directory - **Boolean/object hybrid handling** for `mcpConfig` property - **Legacy compatibility** for existing MCP configurations ## 🧪 **Testing Excellence** ### **Test Categories** - **Unit tests** for ProfileBuilder, Profile, and ProfileRegistry - **Integration tests** for all 13 profiles - **Rule transformation tests** for conversion accuracy - **MCP configuration validation** tests - **Subdirectory support** tests - **Immutability** tests for Profile instances ## 🔧 **Implementation Details** ### **Core Classes** - **`ProfileBuilder`**: Fluent API for type-safe profile construction - **`Profile`**: Immutable profile instances with computed properties - **`ProfileRegistry`**: Centralized profile management and retrieval - **`ProfileAdapter`**: Legacy compatibility layer ### **Key Files Modified** - `src/profile/ProfileBuilder.js` - Core builder implementation - `src/profile/Profile.js` - Immutable profile class with lifecycle support - `src/profiles/*.js` - All 13 profiles migrated to new architecture - `src/utils/rule-transformer.js` - Enhanced with null-safe operations - `tests/` - Comprehensive test suite updates for new architecture ## 🔄 **Backward Compatibility** - ✅ **Legacy profile format support** via ProfileAdapter - ✅ **Existing API compatibility** maintained throughout migration - ✅ **Gradual migration path** allows incremental adoption - ✅ **No breaking changes** for existing consumers ## 🏆 **Quality Assurance** - **Comprehensive linting** compliance - **Type safety** throughout the profile system - **Immutability** enforced for Profile instances - **Error handling** for edge cases and malformed configurations - **Performance optimizations** through computed properties ## 🎉 **Impact** This migration establishes a **robust, maintainable foundation** for the Task Master profile system, enabling: - **Easier profile creation** and maintenance - **Consistent behavior** across all AI coding assistants - **Type safety** preventing runtime errors - **Enhanced developer experience** with fluent APIs - **Future extensibility** for new profile features  ## Summary by CodeRabbit * **New Features** * Introduced an immutable profile system with a fluent builder pattern for defining profiles, including lifecycle hooks, conversion rules, and legacy compatibility. * Added a centralized singleton registry for profile management, supporting profile registration, retrieval, filtering, and statistics. * Implemented custom error classes for profile validation, registration, not found, and operation errors. * **Refactor** * Migrated all existing profiles to use the new builder pattern, enabling declarative configuration, enhanced conversion logic, and structured lifecycle hook support. * Updated rule transformation utilities to work directly with Profile instances and added defensive checks for undefined configuration arrays. * Consolidated lifecycle hooks under a unified `hooks` object with standardized method names. * Refactored VS Code profile to manage schema integration via lifecycle hooks instead of manual file transformations. * Reorganized lifecycle hook naming and grouping, replacing previous separate hook properties with a single `hooks` object. * **Bug Fixes** * Added null and type checks in transformation utilities to prevent runtime errors from missing or malformed profile conversion configurations. * **Tests** * Added extensive unit tests for Profile, ProfileBuilder, and ProfileRegistry classes. * Updated integration and unit tests for all profiles to reflect new profile construction, lifecycle hook structure, and directory layout changes. * Improved test reliability and mocking in configuration and utility modules. * Adjusted tests to accommodate new lifecycle hook access patterns and directory structures for Task Master files. * **Documentation** * Added comprehensive JSDoc type definitions describing profile configuration, conversion rules, lifecycle hooks, and operation results.