434 lines
16 KiB
Plaintext
434 lines
16 KiB
Plaintext
---
|
|
description: Guidelines for implementing CLI commands using Commander.js
|
|
globs: scripts/modules/commands.js
|
|
alwaysApply: false
|
|
---
|
|
|
|
# Command-Line Interface Implementation Guidelines
|
|
|
|
## Command Structure Standards
|
|
|
|
- **Basic Command Template**:
|
|
```javascript
|
|
// ✅ DO: Follow this structure for all commands
|
|
programInstance
|
|
.command('command-name')
|
|
.description('Clear, concise description of what the command does')
|
|
.option('-s, --short-option <value>', 'Option description', 'default value')
|
|
.option('--long-option <value>', 'Option description')
|
|
.action(async (options) => {
|
|
// Command implementation
|
|
});
|
|
```
|
|
|
|
- **Command Handler Organization**:
|
|
- ✅ DO: Keep action handlers concise and focused
|
|
- ✅ DO: Extract core functionality to appropriate modules
|
|
- ✅ DO: Include validation for required parameters
|
|
- ❌ DON'T: Implement business logic in command handlers
|
|
|
|
## Option Naming Conventions
|
|
|
|
- **Command Names**:
|
|
- ✅ DO: Use kebab-case for command names (`analyze-complexity`)
|
|
- ❌ DON'T: Use camelCase for command names (`analyzeComplexity`)
|
|
- ✅ DO: Use descriptive, action-oriented names
|
|
|
|
- **Option Names**:
|
|
- ✅ DO: Use kebab-case for long-form option names (`--output-format`)
|
|
- ✅ DO: Provide single-letter shortcuts when appropriate (`-f, --file`)
|
|
- ✅ DO: Use consistent option names across similar commands
|
|
- ❌ DON'T: Use different names for the same concept (`--file` in one command, `--path` in another)
|
|
|
|
```javascript
|
|
// ✅ DO: Use consistent option naming
|
|
.option('-f, --file <path>', 'Path to the tasks file', 'tasks/tasks.json')
|
|
.option('-o, --output <dir>', 'Output directory', 'tasks')
|
|
|
|
// ❌ DON'T: Use inconsistent naming
|
|
.option('-f, --file <path>', 'Path to the tasks file')
|
|
.option('-p, --path <dir>', 'Output directory') // Should be --output
|
|
```
|
|
|
|
> **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']`.
|
|
|
|
- **Boolean Flag Conventions**:
|
|
- ✅ DO: Use positive flags with `--skip-` prefix for disabling behavior
|
|
- ❌ DON'T: Use negated boolean flags with `--no-` prefix
|
|
- ✅ DO: Use consistent flag handling across all commands
|
|
|
|
```javascript
|
|
// ✅ DO: Use positive flag with skip- prefix
|
|
.option('--skip-generate', 'Skip generating task files')
|
|
|
|
// ❌ DON'T: Use --no- prefix
|
|
.option('--no-generate', 'Skip generating task files')
|
|
```
|
|
|
|
> **Important**: When handling boolean flags in the code, make your intent clear:
|
|
```javascript
|
|
// ✅ DO: Use clear variable naming that matches the flag's intent
|
|
const generateFiles = !options.skipGenerate;
|
|
|
|
// ❌ DON'T: Use confusing double negatives
|
|
const dontSkipGenerate = !options.skipGenerate;
|
|
```
|
|
|
|
## Input Validation
|
|
|
|
- **Required Parameters**:
|
|
- ✅ DO: Check that required parameters are provided
|
|
- ✅ DO: Provide clear error messages when parameters are missing
|
|
- ✅ DO: Use early returns with process.exit(1) for validation failures
|
|
|
|
```javascript
|
|
// ✅ DO: Validate required parameters early
|
|
if (!prompt) {
|
|
console.error(chalk.red('Error: --prompt parameter is required. Please provide a task description.'));
|
|
process.exit(1);
|
|
}
|
|
```
|
|
|
|
- **Parameter Type Conversion**:
|
|
- ✅ DO: Convert string inputs to appropriate types (numbers, booleans)
|
|
- ✅ DO: Handle conversion errors gracefully
|
|
|
|
```javascript
|
|
// ✅ DO: Parse numeric parameters properly
|
|
const fromId = parseInt(options.from, 10);
|
|
if (isNaN(fromId)) {
|
|
console.error(chalk.red('Error: --from must be a valid number'));
|
|
process.exit(1);
|
|
}
|
|
```
|
|
|
|
- **Enhanced Input Validation**:
|
|
- ✅ DO: Validate file existence for critical file operations
|
|
- ✅ DO: Provide context-specific validation for identifiers
|
|
- ✅ DO: Check required API keys for features that depend on them
|
|
|
|
```javascript
|
|
// ✅ DO: Validate file existence
|
|
if (!fs.existsSync(tasksPath)) {
|
|
console.error(chalk.red(`Error: Tasks file not found at path: ${tasksPath}`));
|
|
if (tasksPath === 'tasks/tasks.json') {
|
|
console.log(chalk.yellow('Hint: Run task-master init or task-master parse-prd to create tasks.json first'));
|
|
} else {
|
|
console.log(chalk.yellow(`Hint: Check if the file path is correct: ${tasksPath}`));
|
|
}
|
|
process.exit(1);
|
|
}
|
|
|
|
// ✅ DO: Validate task ID
|
|
const taskId = parseInt(options.id, 10);
|
|
if (isNaN(taskId) || taskId <= 0) {
|
|
console.error(chalk.red(`Error: Invalid task ID: ${options.id}. Task ID must be a positive integer.`));
|
|
console.log(chalk.yellow('Usage example: task-master update-task --id=23 --prompt="Update with new information"'));
|
|
process.exit(1);
|
|
}
|
|
|
|
// ✅ DO: Check for required API keys
|
|
if (useResearch && !process.env.PERPLEXITY_API_KEY) {
|
|
console.log(chalk.yellow('Warning: PERPLEXITY_API_KEY environment variable is missing. Research-backed updates will not be available.'));
|
|
console.log(chalk.yellow('Falling back to Claude AI for task update.'));
|
|
}
|
|
```
|
|
|
|
## User Feedback
|
|
|
|
- **Operation Status**:
|
|
- ✅ DO: Provide clear feedback about the operation being performed
|
|
- ✅ DO: Display success or error messages after completion
|
|
- ✅ DO: Use colored output to distinguish between different message types
|
|
|
|
```javascript
|
|
// ✅ DO: Show operation status
|
|
console.log(chalk.blue(`Parsing PRD file: ${file}`));
|
|
console.log(chalk.blue(`Generating ${numTasks} tasks...`));
|
|
|
|
try {
|
|
await parsePRD(file, outputPath, numTasks);
|
|
console.log(chalk.green('Successfully generated tasks from PRD'));
|
|
} catch (error) {
|
|
console.error(chalk.red(`Error: ${error.message}`));
|
|
process.exit(1);
|
|
}
|
|
```
|
|
|
|
- **Success Messages with Next Steps**:
|
|
- ✅ DO: Use boxen for important success messages with clear formatting
|
|
- ✅ DO: Provide suggested next steps after command completion
|
|
- ✅ DO: Include ready-to-use commands for follow-up actions
|
|
|
|
```javascript
|
|
// ✅ DO: Display success with next steps
|
|
console.log(boxen(
|
|
chalk.white.bold(`Subtask ${parentId}.${subtask.id} Added Successfully`) + '\n\n' +
|
|
chalk.white(`Title: ${subtask.title}`) + '\n' +
|
|
chalk.white(`Status: ${getStatusWithColor(subtask.status)}`) + '\n' +
|
|
(dependencies.length > 0 ? chalk.white(`Dependencies: ${dependencies.join(', ')}`) + '\n' : '') +
|
|
'\n' +
|
|
chalk.white.bold('Next Steps:') + '\n' +
|
|
chalk.cyan(`1. Run ${chalk.yellow(`task-master show ${parentId}`)} to see the parent task with all subtasks`) + '\n' +
|
|
chalk.cyan(`2. Run ${chalk.yellow(`task-master set-status --id=${parentId}.${subtask.id} --status=in-progress`)} to start working on it`),
|
|
{ padding: 1, borderColor: 'green', borderStyle: 'round', margin: { top: 1 } }
|
|
));
|
|
```
|
|
|
|
## Command Registration
|
|
|
|
- **Command Grouping**:
|
|
- ✅ DO: Group related commands together in the code
|
|
- ✅ DO: Add related commands in a logical order
|
|
- ✅ DO: Use comments to delineate command groups
|
|
|
|
- **Command Export**:
|
|
- ✅ DO: Export the registerCommands function
|
|
- ✅ DO: Keep the CLI setup code clean and maintainable
|
|
|
|
```javascript
|
|
// ✅ DO: Follow this export pattern
|
|
export {
|
|
registerCommands,
|
|
setupCLI,
|
|
runCLI,
|
|
checkForUpdate, // Include version checking functions
|
|
compareVersions,
|
|
displayUpgradeNotification
|
|
};
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
- **Exception Management**:
|
|
- ✅ DO: Wrap async operations in try/catch blocks
|
|
- ✅ DO: Display user-friendly error messages
|
|
- ✅ DO: Include detailed error information in debug mode
|
|
|
|
```javascript
|
|
// ✅ DO: Handle errors properly
|
|
try {
|
|
// Command implementation
|
|
} catch (error) {
|
|
console.error(chalk.red(`Error: ${error.message}`));
|
|
|
|
if (CONFIG.debug) {
|
|
console.error(error);
|
|
}
|
|
|
|
process.exit(1);
|
|
}
|
|
```
|
|
|
|
- **Unknown Options Handling**:
|
|
- ✅ DO: Provide clear error messages for unknown options
|
|
- ✅ DO: Show available options when an unknown option is used
|
|
- ✅ DO: Include command-specific help displays for common errors
|
|
- ❌ DON'T: Allow unknown options with `.allowUnknownOption()`
|
|
|
|
```javascript
|
|
// ✅ DO: Register global error handlers for unknown options
|
|
programInstance.on('option:unknown', function(unknownOption) {
|
|
const commandName = this._name || 'unknown';
|
|
console.error(chalk.red(`Error: Unknown option '${unknownOption}'`));
|
|
console.error(chalk.yellow(`Run 'task-master ${commandName} --help' to see available options`));
|
|
process.exit(1);
|
|
});
|
|
|
|
// ✅ DO: Add command-specific help displays
|
|
function showCommandHelp() {
|
|
console.log(boxen(
|
|
chalk.white.bold('Command Help') + '\n\n' +
|
|
chalk.cyan('Usage:') + '\n' +
|
|
` task-master command --option1=<value> [options]\n\n` +
|
|
chalk.cyan('Options:') + '\n' +
|
|
' --option1 <value> Description of option1 (required)\n' +
|
|
' --option2 <value> Description of option2\n\n' +
|
|
chalk.cyan('Examples:') + '\n' +
|
|
' task-master command --option1=value --option2=value',
|
|
{ padding: 1, borderColor: 'blue', borderStyle: 'round' }
|
|
));
|
|
}
|
|
```
|
|
|
|
- **Global Error Handling**:
|
|
- ✅ DO: Set up global error handlers for uncaught exceptions
|
|
- ✅ DO: Detect and format Commander-specific errors
|
|
- ✅ DO: Provide suitable guidance for fixing common errors
|
|
|
|
```javascript
|
|
// ✅ DO: Set up global error handlers with helpful messages
|
|
process.on('uncaughtException', (err) => {
|
|
// Handle Commander-specific errors
|
|
if (err.code === 'commander.unknownOption') {
|
|
const option = err.message.match(/'([^']+)'/)?.[1];
|
|
console.error(chalk.red(`Error: Unknown option '${option}'`));
|
|
console.error(chalk.yellow(`Run 'task-master <command> --help' to see available options`));
|
|
process.exit(1);
|
|
}
|
|
|
|
// Handle other error types...
|
|
console.error(chalk.red(`Error: ${err.message}`));
|
|
process.exit(1);
|
|
});
|
|
```
|
|
|
|
- **Contextual Error Handling**:
|
|
- ✅ DO: Provide specific error handling for common issues
|
|
- ✅ DO: Include troubleshooting hints for each error type
|
|
- ✅ DO: Use consistent error formatting across all commands
|
|
|
|
```javascript
|
|
// ✅ DO: Provide specific error handling with guidance
|
|
try {
|
|
// Implementation
|
|
} catch (error) {
|
|
console.error(chalk.red(`Error: ${error.message}`));
|
|
|
|
// Provide more helpful error messages for common issues
|
|
if (error.message.includes('task') && error.message.includes('not found')) {
|
|
console.log(chalk.yellow('\nTo fix this issue:'));
|
|
console.log(' 1. Run task-master list to see all available task IDs');
|
|
console.log(' 2. Use a valid task ID with the --id parameter');
|
|
} else if (error.message.includes('API key')) {
|
|
console.log(chalk.yellow('\nThis error is related to API keys. Check your environment variables.'));
|
|
}
|
|
|
|
if (CONFIG.debug) {
|
|
console.error(error);
|
|
}
|
|
|
|
process.exit(1);
|
|
}
|
|
```
|
|
|
|
## Integration with Other Modules
|
|
|
|
- **Import Organization**:
|
|
- ✅ DO: Group imports by module/functionality
|
|
- ✅ DO: Import only what's needed, not entire modules
|
|
- ❌ DON'T: Create circular dependencies
|
|
|
|
```javascript
|
|
// ✅ DO: Organize imports by module
|
|
import { program } from 'commander';
|
|
import path from 'path';
|
|
import chalk from 'chalk';
|
|
import https from 'https';
|
|
|
|
import { CONFIG, log, readJSON } from './utils.js';
|
|
import { displayBanner, displayHelp } from './ui.js';
|
|
import { parsePRD, listTasks } from './task-manager.js';
|
|
import { addDependency } from './dependency-manager.js';
|
|
```
|
|
|
|
## Subtask Management Commands
|
|
|
|
- **Add Subtask Command Structure**:
|
|
```javascript
|
|
// ✅ DO: Follow this structure for adding subtasks
|
|
programInstance
|
|
.command('add-subtask')
|
|
.description('Add a new subtask to a parent task or convert an existing task to a subtask')
|
|
.option('-f, --file <path>', 'Path to the tasks file', 'tasks/tasks.json')
|
|
.option('-p, --parent <id>', 'ID of the parent task (required)')
|
|
.option('-i, --task-id <id>', 'Existing task ID to convert to subtask')
|
|
.option('-t, --title <title>', 'Title for the new subtask (when not converting)')
|
|
.option('-d, --description <description>', 'Description for the new subtask (when not converting)')
|
|
.option('--details <details>', 'Implementation details for the new subtask (when not converting)')
|
|
.option('--dependencies <ids>', 'Comma-separated list of subtask IDs this subtask depends on')
|
|
.option('--status <status>', 'Initial status for the subtask', 'pending')
|
|
.option('--skip-generate', 'Skip regenerating task files')
|
|
.action(async (options) => {
|
|
// Validate required parameters
|
|
if (!options.parent) {
|
|
console.error(chalk.red('Error: --parent parameter is required'));
|
|
showAddSubtaskHelp(); // Show contextual help
|
|
process.exit(1);
|
|
}
|
|
|
|
// Implementation with detailed error handling
|
|
});
|
|
```
|
|
|
|
- **Remove Subtask Command Structure**:
|
|
```javascript
|
|
// ✅ DO: Follow this structure for removing subtasks
|
|
programInstance
|
|
.command('remove-subtask')
|
|
.description('Remove a subtask from its parent task, optionally converting it to a standalone task')
|
|
.option('-f, --file <path>', 'Path to the tasks file', 'tasks/tasks.json')
|
|
.option('-i, --id <id>', 'ID of the subtask to remove in format "parentId.subtaskId" (required)')
|
|
.option('-c, --convert', 'Convert the subtask to a standalone task')
|
|
.option('--skip-generate', 'Skip regenerating task files')
|
|
.action(async (options) => {
|
|
// Implementation with detailed error handling
|
|
})
|
|
.on('error', function(err) {
|
|
console.error(chalk.red(`Error: ${err.message}`));
|
|
showRemoveSubtaskHelp(); // Show contextual help
|
|
process.exit(1);
|
|
});
|
|
```
|
|
|
|
## Version Checking and Updates
|
|
|
|
- **Automatic Version Checking**:
|
|
- ✅ DO: Implement version checking to notify users of available updates
|
|
- ✅ DO: Use non-blocking version checks that don't delay command execution
|
|
- ✅ DO: Display update notifications after command completion
|
|
|
|
```javascript
|
|
// ✅ DO: Implement version checking function
|
|
async function checkForUpdate() {
|
|
// Implementation details...
|
|
return { currentVersion, latestVersion, needsUpdate };
|
|
}
|
|
|
|
// ✅ DO: Implement semantic version comparison
|
|
function compareVersions(v1, v2) {
|
|
const v1Parts = v1.split('.').map(p => parseInt(p, 10));
|
|
const v2Parts = v2.split('.').map(p => parseInt(p, 10));
|
|
|
|
// Implementation details...
|
|
return result; // -1, 0, or 1
|
|
}
|
|
|
|
// ✅ DO: Display attractive update notifications
|
|
function displayUpgradeNotification(currentVersion, latestVersion) {
|
|
const message = boxen(
|
|
`${chalk.blue.bold('Update Available!')} ${chalk.dim(currentVersion)} → ${chalk.green(latestVersion)}\n\n` +
|
|
`Run ${chalk.cyan('npm i task-master-ai@latest -g')} to update to the latest version with new features and bug fixes.`,
|
|
{
|
|
padding: 1,
|
|
margin: { top: 1, bottom: 1 },
|
|
borderColor: 'yellow',
|
|
borderStyle: 'round'
|
|
}
|
|
);
|
|
|
|
console.log(message);
|
|
}
|
|
|
|
// ✅ DO: Integrate version checking in CLI run function
|
|
async function runCLI(argv = process.argv) {
|
|
try {
|
|
// Start the update check in the background - don't await yet
|
|
const updateCheckPromise = checkForUpdate();
|
|
|
|
// Setup and parse
|
|
const programInstance = setupCLI();
|
|
await programInstance.parseAsync(argv);
|
|
|
|
// After command execution, check if an update is available
|
|
const updateInfo = await updateCheckPromise;
|
|
if (updateInfo.needsUpdate) {
|
|
displayUpgradeNotification(updateInfo.currentVersion, updateInfo.latestVersion);
|
|
}
|
|
} catch (error) {
|
|
// Error handling...
|
|
}
|
|
}
|
|
```
|
|
|
|
Refer to [`commands.js`](mdc:scripts/modules/commands.js) for implementation examples and [`new_features.mdc`](mdc:.cursor/rules/new_features.mdc) for integration guidelines. |