Cursor rule

1---
2description: Guidelines for integrating new features into the Task Master CLI
3globs: scripts/modules/*.js
4alwaysApply: false
5---
6 
7# Task Master Feature Integration Guidelines
8 
9## Feature Placement Decision Process
10 
11- **Identify Feature Type**:
12  - **Data Manipulation**: Features that create, read, update, or delete tasks belong in [`task-manager.js`](mdc:scripts/modules/task-manager.js)
13  - **Dependency Management**: Features that handle task relationships belong in [`dependency-manager.js`](mdc:scripts/modules/dependency-manager.js)
14  - **User Interface**: Features that display information to users belong in [`ui.js`](mdc:scripts/modules/ui.js)
15  - **AI Integration**: Features that use AI models belong in [`ai-services.js`](mdc:scripts/modules/ai-services.js)
16  - **Cross-Cutting**: Features that don't fit one category may need components in multiple modules
17 
18- **Command-Line Interface**:
19  - All new user-facing commands should be added to [`commands.js`](mdc:scripts/modules/commands.js)
20  - Use consistent patterns for option naming and help text
21  - Follow the Commander.js model for subcommand structure
22 
23## Implementation Pattern
24 
25The standard pattern for adding a feature follows this workflow:
26 
271. **Core Logic**: Implement the business logic in the appropriate module
282. **UI Components**: Add any display functions to [`ui.js`](mdc:scripts/modules/ui.js)
293. **Command Integration**: Add the CLI command to [`commands.js`](mdc:scripts/modules/commands.js)
304. **Testing**: Write tests for all components of the feature (following [`tests.mdc`](mdc:.cursor/rules/tests.mdc))
315. **Configuration**: Update any configuration in [`utils.js`](mdc:scripts/modules/utils.js) if needed
326. **Documentation**: Update help text and documentation in [dev_workflow.mdc](mdc:scripts/modules/dev_workflow.mdc)
33 
34```javascript
35// 1. CORE LOGIC: Add function to appropriate module (example in task-manager.js)
36/**
37 * Archives completed tasks to archive.json
38 * @param {string} tasksPath - Path to the tasks.json file
39 * @param {string} archivePath - Path to the archive.json file
40 * @returns {number} Number of tasks archived
41 */
42async function archiveTasks(tasksPath, archivePath = 'tasks/archive.json') {
43  // Implementation...
44  return archivedCount;
45}
46 
47// Export from the module
48export {
49  // ... existing exports ...
50  archiveTasks,
51};
52```
53 
54```javascript
55// 2. UI COMPONENTS: Add display function to ui.js
56/**
57 * Display archive operation results
58 * @param {string} archivePath - Path to the archive file
59 * @param {number} count - Number of tasks archived
60 */
61function displayArchiveResults(archivePath, count) {
62  console.log(boxen(
63    chalk.green(`Successfully archived ${count} tasks to ${archivePath}`),
64    { padding: 1, borderColor: 'green', borderStyle: 'round' }
65  ));
66}
67 
68// Export from the module
69export {
70  // ... existing exports ...
71  displayArchiveResults,
72};
73```
74 
75```javascript
76// 3. COMMAND INTEGRATION: Add to commands.js
77import { archiveTasks } from './task-manager.js';
78import { displayArchiveResults } from './ui.js';
79 
80// In registerCommands function
81programInstance
82  .command('archive')
83  .description('Archive completed tasks to separate file')
84  .option('-f, --file <file>', 'Path to the tasks file', 'tasks/tasks.json')
85  .option('-o, --output <file>', 'Archive output file', 'tasks/archive.json')
86  .action(async (options) => {
87    const tasksPath = options.file;
88    const archivePath = options.output;
89 
90    console.log(chalk.blue(`Archiving completed tasks from ${tasksPath} to ${archivePath}...`));
91 
92    const archivedCount = await archiveTasks(tasksPath, archivePath);
93    displayArchiveResults(archivePath, archivedCount);
94  });
95```
96 
97## Cross-Module Features
98 
99For features requiring components in multiple modules:
100 
101- ✅ **DO**: Create a clear unidirectional flow of dependencies
102```javascript
103  // In task-manager.js
104  function analyzeTasksDifficulty(tasks) {
105    // Implementation...
106    return difficultyScores;
107  }
108 
109  // In ui.js - depends on task-manager.js
110  import { analyzeTasksDifficulty } from './task-manager.js';
111 
112  function displayDifficultyReport(tasks) {
113    const scores = analyzeTasksDifficulty(tasks);
114    // Render the scores...
115  }
116```
117 
118- ❌ **DON'T**: Create circular dependencies between modules
119```javascript
120  // In task-manager.js - depends on ui.js
121  import { displayDifficultyReport } from './ui.js';
122 
123  function analyzeTasks() {
124    // Implementation...
125    displayDifficultyReport(tasks); // WRONG! Don't call UI functions from task-manager
126  }
127 
128  // In ui.js - depends on task-manager.js
129  import { analyzeTasks } from './task-manager.js';
130```
131 
132## Command-Line Interface Standards
133 
134- **Naming Conventions**:
135  - Use kebab-case for command names (`analyze-complexity`, not `analyzeComplexity`)
136  - Use kebab-case for option names (`--output-format`, not `--outputFormat`)
137  - Use the same option names across commands when they represent the same concept
138 
139- **Command Structure**:
140```javascript
141  programInstance
142    .command('command-name')
143    .description('Clear, concise description of what the command does')
144    .option('-s, --short-option <value>', 'Option description', 'default value')
145    .option('--long-option <value>', 'Option description')
146    .action(async (options) => {
147      // Command implementation
148    });
149```
150 
151## Utility Function Guidelines
152 
153When adding utilities to [`utils.js`](mdc:scripts/modules/utils.js):
154 
155- Only add functions that could be used by multiple modules
156- Keep utilities single-purpose and purely functional
157- Document parameters and return values
158 
159```javascript
160/**
161 * Formats a duration in milliseconds to a human-readable string
162 * @param {number} ms - Duration in milliseconds
163 * @returns {string} Formatted duration string (e.g., "2h 30m 15s")
164 */
165function formatDuration(ms) {
166  // Implementation...
167  return formatted;
168}
169```
170 
171## Writing Testable Code
172 
173When implementing new features, follow these guidelines to ensure your code is testable:
174 
175- **Dependency Injection**
176  - Design functions to accept dependencies as parameters
177  - Avoid hard-coded dependencies that are difficult to mock
178```javascript
179  // ✅ DO: Accept dependencies as parameters
180  function processTask(task, fileSystem, logger) {
181    fileSystem.writeFile('task.json', JSON.stringify(task));
182    logger.info('Task processed');
183  }
184 
185  // ❌ DON'T: Use hard-coded dependencies
186  function processTask(task) {
187    fs.writeFile('task.json', JSON.stringify(task));
188    console.log('Task processed');
189  }
190```
191 
192- **Separate Logic from Side Effects**
193  - Keep pure logic separate from I/O operations or UI rendering
194  - This allows testing the logic without mocking complex dependencies
195```javascript
196  // ✅ DO: Separate logic from side effects
197  function calculateTaskPriority(task, dependencies) {
198    // Pure logic that returns a value
199    return computedPriority;
200  }
201 
202  function displayTaskPriority(task, dependencies) {
203    const priority = calculateTaskPriority(task, dependencies);
204    console.log(`Task priority: ${priority}`);
205  }
206```
207 
208- **Callback Functions and Testing**
209  - When using callbacks (like in Commander.js commands), define them separately
210  - This allows testing the callback logic independently
211```javascript
212  // ✅ DO: Define callbacks separately for testing
213  function getVersionString() {
214    // Logic to determine version
215    return version;
216  }
217 
218  // In setupCLI
219  programInstance.version(getVersionString);
220 
221  // In tests
222  test('getVersionString returns correct version', () => {
223    expect(getVersionString()).toBe('1.5.0');
224  });
225```
226 
227- **UI Output Testing**
228  - For UI components, focus on testing conditional logic rather than exact output
229  - Use string pattern matching (like `expect(result).toContain('text')`)
230  - Pay attention to emojis and formatting which can make exact string matching difficult
231```javascript
232  // ✅ DO: Test the essence of the output, not exact formatting
233  test('statusFormatter shows done status correctly', () => {
234    const result = formatStatus('done');
235    expect(result).toContain('done');
236    expect(result).toContain('✅');
237  });
238```
239 
240## Testing Requirements
241 
242Every new feature **must** include comprehensive tests following the guidelines in [`tests.mdc`](mdc:.cursor/rules/tests.mdc). Testing should include:
243 
2441. **Unit Tests**: Test individual functions and components in isolation
245```javascript
246   // Example unit test for a new utility function
247   describe('newFeatureUtil', () => {
248     test('should perform expected operation with valid input', () => {
249       expect(newFeatureUtil('valid input')).toBe('expected result');
250     });
251 
252     test('should handle edge cases appropriately', () => {
253       expect(newFeatureUtil('')).toBeNull();
254     });
255   });
256```
257 
2582. **Integration Tests**: Verify the feature works correctly with other components
259```javascript
260   // Example integration test for a new command
261   describe('newCommand integration', () => {
262     test('should call the correct service functions with parsed arguments', () => {
263       const mockService = jest.fn().mockResolvedValue('success');
264       // Set up test with mocked dependencies
265       // Call the command handler
266       // Verify service was called with expected arguments
267     });
268   });
269```
270 
2713. **Edge Cases**: Test boundary conditions and error handling
272   - Invalid inputs
273   - Missing dependencies
274   - File system errors
275   - API failures
276 
2774. **Test Coverage**: Aim for at least 80% coverage for all new code
278 
2795. **Jest Mocking Best Practices**
280   - Follow the mock-first-then-import pattern as described in [`tests.mdc`](mdc:.cursor/rules/tests.mdc)
281   - Use jest.spyOn() to create spy functions for testing
282   - Clear mocks between tests to prevent interference
283   - See the Jest Module Mocking Best Practices section in [`tests.mdc`](mdc:.cursor/rules/tests.mdc) for details
284 
285When submitting a new feature, always run the full test suite to ensure nothing was broken:
286 
287```bash
288npm test
289```
290 
291## Documentation Requirements
292 
293For each new feature:
294 
2951. Add help text to the command definition
2962. Update [`dev_workflow.mdc`](mdc:scripts/modules/dev_workflow.mdc) with command reference
2973. Add examples to the appropriate sections in [`MODULE_PLAN.md`](mdc:scripts/modules/MODULE_PLAN.md)
298 
299Follow the existing command reference format:
300```markdown
301- **Command Reference: your-command**
302  - CLI Syntax: `task-manager your-command [options]`
303  - Description: Brief explanation of what the command does
304  - Parameters:
305    - `--option1=<value>`: Description of option1 (default: 'default')
306    - `--option2=<value>`: Description of option2 (required)
307  - Example: `task-manager your-command --option1=value --option2=value2`
308  - Notes: Additional details, limitations, or special considerations
309```
310 
311For more information on module structure, see [`MODULE_PLAN.md`](mdc:scripts/modules/MODULE_PLAN.md) and follow [`self_improve.mdc`](mdc:scripts/modules/self_improve.mdc) for best practices on updating documentation.
312