112 lines
6.4 KiB
Plaintext
112 lines
6.4 KiB
Plaintext
# Task ID: 98
|
|
# Title: Implement Standalone 'research' CLI Command for AI-Powered Queries
|
|
# Status: in-progress
|
|
# Dependencies: 2, 4, 16
|
|
# Priority: medium
|
|
# Description: Develop a new 'task-master research' (alias 'tm research') CLI command for fast, context-aware AI research queries using the ai-services-unified.js infrastructure.
|
|
# Details:
|
|
- Add a new CLI command 'research' to commands.js, following established CLI patterns and conventions.
|
|
- Command should accept a research query as the main parameter, with optional flags for task IDs (--tasks), file paths (--files), custom context (--context), output detail level (--detail), and result saving (--save).
|
|
- Integrate with ai-services-unified.js, invoking its research mode to process the query and context, leveraging project file tree and task context as needed.
|
|
- Implement logic to gather and inject relevant context from specified tasks, files, or custom input, and generate a project file tree snapshot if required.
|
|
- Ensure output is formatted for terminal readability, including citations and references where available.
|
|
- Support saving research results to a specified file if --save is provided.
|
|
- Provide both brief and comprehensive output modes, controlled by a flag.
|
|
- Ensure the command is non-interactive (one-shot execution) and complements the existing 'explore' command.
|
|
- Update help documentation and usage examples for the new command.
|
|
|
|
# Test Strategy:
|
|
- Write unit and integration tests to verify correct parsing of command-line arguments and flags.
|
|
- Test that the command invokes ai-services-unified.js in research mode with the correct parameters and context.
|
|
- Validate that context from tasks, files, and custom input is correctly gathered and passed to the research engine.
|
|
- Confirm that output is properly formatted, includes citations, and is displayed in the terminal as expected.
|
|
- Test saving results to files and handling of file system errors.
|
|
- Ensure the command works in both brief and comprehensive modes.
|
|
- Verify that the command does not enter interactive mode and exits cleanly after execution.
|
|
- Check help output and usage documentation for accuracy and completeness.
|
|
|
|
# Subtasks:
|
|
## 1. Command Registration [in-progress]
|
|
### Dependencies: None
|
|
### Description: Register the 'research' command with the CLI framework, ensuring it appears in the list of available commands and supports standard CLI conventions.
|
|
### Details:
|
|
Integrate the new command into the CLI's command registry. Ensure it is discoverable via the CLI's help system and follows established naming and grouping conventions.
|
|
|
|
## 2. Parameter and Flag Handling [pending]
|
|
### Dependencies: 94.1
|
|
### Description: Define and implement parsing for all arguments, flags, and options accepted by the 'research' command, including validation and default values.
|
|
### Details:
|
|
Use a command-line parsing framework to handle parameters. Ensure support for optional and required arguments, order-independence, and clear error messages for invalid input.
|
|
|
|
## 3. Context Gathering [pending]
|
|
### Dependencies: 94.2
|
|
### Description: Implement logic to gather necessary context for the research operation, such as reading from files, stdin, or other sources as specified by the user.
|
|
### Details:
|
|
Support reading input from files or stdin using '-' as a convention. Validate and preprocess the gathered context to ensure it is suitable for AI processing.
|
|
<info added on 2025-05-25T05:24:58.107Z>
|
|
Create a comprehensive, reusable context gathering utility `utils/contextGatherer.js` that can be shared between the research command and explore REPL functionality.
|
|
|
|
**Core Features:**
|
|
|
|
**Task/Subtask Context Extraction:**
|
|
- Parse task IDs and subtask IDs (formats: "15", "15.2", "16,17.1")
|
|
- Extract task titles, descriptions, details, and dependencies from the task system
|
|
- Include parent task context automatically for subtasks
|
|
- Format task data optimally for AI consumption
|
|
|
|
**File Path Context Processing:**
|
|
- Handle single or comma-separated file paths
|
|
- Implement safe file reading with comprehensive error handling
|
|
- Support multiple file types (JavaScript, markdown, text, JSON, etc.)
|
|
- Include file metadata (path, size, type, last modified)
|
|
|
|
**Project File Tree Generation:**
|
|
- Create structured project overview with configurable depth
|
|
- Filter out irrelevant directories (.git, node_modules, .env files)
|
|
- Include file counts and directory statistics
|
|
- Support custom filtering patterns
|
|
|
|
**Custom Context Integration:**
|
|
- Accept and merge custom context strings
|
|
- Maintain clear context hierarchy and organization
|
|
- Preserve context source attribution
|
|
|
|
**Unified API Design:**
|
|
```javascript
|
|
const contextGatherer = new ContextGatherer(projectRoot);
|
|
const context = await contextGatherer.gather({
|
|
tasks: ["15", "16.2"],
|
|
files: ["src/main.js", "README.md"],
|
|
customContext: "Additional context...",
|
|
includeProjectTree: true,
|
|
format: "research" // or "chat", "system-prompt"
|
|
});
|
|
```
|
|
|
|
**Output Formatting:**
|
|
- Support multiple output formats (research, chat, system-prompt)
|
|
- Ensure consistent context structure across different use cases
|
|
- Optimize for AI model consumption and token efficiency
|
|
|
|
This utility will eliminate code duplication between task 51 (explore REPL) and task 94 (research command) while providing a robust, extensible foundation for context gathering operations.
|
|
</info added on 2025-05-25T05:24:58.107Z>
|
|
|
|
## 4. AI Service Integration [pending]
|
|
### Dependencies: 94.3
|
|
### Description: Integrate with the AI service to process the gathered context and parameters, handling API calls, authentication, and error management.
|
|
### Details:
|
|
Establish a robust interface to the AI backend, manage API keys or tokens securely, and handle network or service errors gracefully.
|
|
|
|
## 5. Output Formatting [pending]
|
|
### Dependencies: 94.4
|
|
### Description: Format the AI-generated output according to user-specified modes (e.g., plain text, JSON), and support writing to stdout or files.
|
|
### Details:
|
|
Implement flexible output formatting, ensuring compatibility with piping and redirection. Provide clear, user-friendly output and support for machine-readable formats.
|
|
|
|
## 6. Documentation and Help [pending]
|
|
### Dependencies: 94.1, 94.2, 94.3, 94.4, 94.5
|
|
### Description: Document the 'research' command, including usage examples, parameter descriptions, and integration with the CLI's --help system.
|
|
### Details:
|
|
Update CLI documentation and ensure the --help flag provides comprehensive guidance on using the command, its options, and expected outputs.
|
|
|