Cursor rule

1---
2description: Guidelines for implementing CLI commands using Commander.js
3globs: scripts/modules/commands.js
4alwaysApply: false
5---
6 
7# Command-Line Interface Implementation Guidelines
8 
9## Command Structure Standards
10 
11- **Basic Command Template**:
12```javascript
13  // ✅ DO: Follow this structure for all commands
14  programInstance
15    .command('command-name')
16    .description('Clear, concise description of what the command does')
17    .option('-s, --short-option <value>', 'Option description', 'default value')
18    .option('--long-option <value>', 'Option description')
19    .action(async (options) => {
20      // Command implementation
21    });
22```
23 
24- **Command Handler Organization**:
25  - ✅ DO: Keep action handlers concise and focused
26  - ✅ DO: Extract core functionality to appropriate modules
27  - ✅ DO: Include validation for required parameters
28  - ❌ DON'T: Implement business logic in command handlers
29 
30## Option Naming Conventions
31 
32- **Command Names**:
33  - ✅ DO: Use kebab-case for command names (`analyze-complexity`)
34  - ❌ DON'T: Use camelCase for command names (`analyzeComplexity`)
35  - ✅ DO: Use descriptive, action-oriented names
36 
37- **Option Names**:
38  - ✅ DO: Use kebab-case for long-form option names (`--output-format`)
39  - ✅ DO: Provide single-letter shortcuts when appropriate (`-f, --file`)
40  - ✅ DO: Use consistent option names across similar commands
41  - ❌ DON'T: Use different names for the same concept (`--file` in one command, `--path` in another)
42 
43```javascript
44  // ✅ DO: Use consistent option naming
45  .option('-f, --file <path>', 'Path to the tasks file', 'tasks/tasks.json')
46  .option('-o, --output <dir>', 'Output directory', 'tasks')
47  
48  // ❌ DON'T: Use inconsistent naming
49  .option('-f, --file <path>', 'Path to the tasks file')
50  .option('-p, --path <dir>', 'Output directory') // Should be --output
51```
52 
53  > **Note**: Although options are defined with kebab-case (`--num-tasks`), Commander.js stores them internally as camelCase properties. Access them in code as `options.numTasks`, not `options['num-tasks']`.
54 
55## Input Validation
56 
57- **Required Parameters**:
58  - ✅ DO: Check that required parameters are provided
59  - ✅ DO: Provide clear error messages when parameters are missing
60  - ✅ DO: Use early returns with process.exit(1) for validation failures
61 
62```javascript
63  // ✅ DO: Validate required parameters early
64  if (!prompt) {
65    console.error(chalk.red('Error: --prompt parameter is required. Please provide a task description.'));
66    process.exit(1);
67  }
68```
69 
70- **Parameter Type Conversion**:
71  - ✅ DO: Convert string inputs to appropriate types (numbers, booleans)
72  - ✅ DO: Handle conversion errors gracefully
73 
74```javascript
75  // ✅ DO: Parse numeric parameters properly
76  const fromId = parseInt(options.from, 10);
77  if (isNaN(fromId)) {
78    console.error(chalk.red('Error: --from must be a valid number'));
79    process.exit(1);
80  }
81```
82 
83## User Feedback
84 
85- **Operation Status**:
86  - ✅ DO: Provide clear feedback about the operation being performed
87  - ✅ DO: Display success or error messages after completion
88  - ✅ DO: Use colored output to distinguish between different message types
89 
90```javascript
91  // ✅ DO: Show operation status
92  console.log(chalk.blue(`Parsing PRD file: ${file}`));
93  console.log(chalk.blue(`Generating ${numTasks} tasks...`));
94  
95  try {
96    await parsePRD(file, outputPath, numTasks);
97    console.log(chalk.green('Successfully generated tasks from PRD'));
98  } catch (error) {
99    console.error(chalk.red(`Error: ${error.message}`));
100    process.exit(1);
101  }
102```
103 
104## Command Registration
105 
106- **Command Grouping**:
107  - ✅ DO: Group related commands together in the code
108  - ✅ DO: Add related commands in a logical order
109  - ✅ DO: Use comments to delineate command groups
110 
111- **Command Export**:
112  - ✅ DO: Export the registerCommands function
113  - ✅ DO: Keep the CLI setup code clean and maintainable
114 
115```javascript
116  // ✅ DO: Follow this export pattern
117  export {
118    registerCommands,
119    setupCLI,
120    runCLI
121  };
122```
123 
124## Error Handling
125 
126- **Exception Management**:
127  - ✅ DO: Wrap async operations in try/catch blocks
128  - ✅ DO: Display user-friendly error messages
129  - ✅ DO: Include detailed error information in debug mode
130 
131```javascript
132  // ✅ DO: Handle errors properly
133  try {
134    // Command implementation
135  } catch (error) {
136    console.error(chalk.red(`Error: ${error.message}`));
137    
138    if (CONFIG.debug) {
139      console.error(error);
140    }
141    
142    process.exit(1);
143  }
144```
145 
146## Integration with Other Modules
147 
148- **Import Organization**:
149  - ✅ DO: Group imports by module/functionality
150  - ✅ DO: Import only what's needed, not entire modules
151  - ❌ DON'T: Create circular dependencies
152 
153```javascript
154  // ✅ DO: Organize imports by module
155  import { program } from 'commander';
156  import path from 'path';
157  import chalk from 'chalk';
158  
159  import { CONFIG, log, readJSON } from './utils.js';
160  import { displayBanner, displayHelp } from './ui.js';
161  import { parsePRD, listTasks } from './task-manager.js';
162  import { addDependency } from './dependency-manager.js';
163```
164 
165## Subtask Management Commands
166 
167- **Add Subtask Command Structure**:
168```javascript
169  // ✅ DO: Follow this structure for adding subtasks
170  programInstance
171    .command('add-subtask')
172    .description('Add a new subtask to a parent task or convert an existing task to a subtask')
173    .option('-f, --file <path>', 'Path to the tasks file', 'tasks/tasks.json')
174    .option('-p, --parent <id>', 'ID of the parent task (required)')
175    .option('-e, --existing <id>', 'ID of an existing task to convert to a subtask')
176    .option('-t, --title <title>', 'Title for the new subtask (when not converting)')
177    .option('-d, --description <description>', 'Description for the new subtask (when not converting)')
178    .option('--details <details>', 'Implementation details for the new subtask (when not converting)')
179    .option('--dependencies <ids>', 'Comma-separated list of subtask IDs this subtask depends on')
180    .option('--status <status>', 'Initial status for the subtask', 'pending')
181    .action(async (options) => {
182      // Validate required parameters
183      if (!options.parent) {
184        console.error(chalk.red('Error: --parent parameter is required'));
185        process.exit(1);
186      }
187      
188      // Validate that either existing task ID or title is provided
189      if (!options.existing && !options.title) {
190        console.error(chalk.red('Error: Either --existing or --title must be provided'));
191        process.exit(1);
192      }
193      
194      try {
195        // Implementation
196      } catch (error) {
197        // Error handling
198      }
199    });
200```
201 
202- **Remove Subtask Command Structure**:
203```javascript
204  // ✅ DO: Follow this structure for removing subtasks
205  programInstance
206    .command('remove-subtask')
207    .description('Remove a subtask from its parent task, optionally converting it to a standalone task')
208    .option('-f, --file <path>', 'Path to the tasks file', 'tasks/tasks.json')
209    .option('-i, --id <id>', 'ID of the subtask to remove in format "parentId.subtaskId" (required)')
210    .option('-c, --convert', 'Convert the subtask to a standalone task')
211    .action(async (options) => {
212      // Validate required parameters
213      if (!options.id) {
214        console.error(chalk.red('Error: --id parameter is required'));
215        process.exit(1);
216      }
217      
218      // Validate subtask ID format
219      if (!options.id.includes('.')) {
220        console.error(chalk.red('Error: Subtask ID must be in format "parentId.subtaskId"'));
221        process.exit(1);
222      }
223      
224      try {
225        // Implementation
226      } catch (error) {
227        // Error handling
228      }
229    });
230```
231 
232Refer to [`commands.js`](mdc:scripts/modules/commands.js) for implementation examples and [`new_features.mdc`](mdc:.cursor/rules/new_features.mdc) for integration guidelines.