contaigents/FILE_TOOL_ENHANCEMENT_PLAN.md

Modular AI Content Ecosystem with Audio Generation

# File Tool Enhancement Feature Plan

## Overview
Add search, line-based reading, and precise writing capabilities to existing file tools.

## New Tools

### 1. FileSearchTool
**Purpose**: Search within single file with context
**Parameters**: file_path, search_pattern, search_type, context_lines_before, context_lines_after, case_sensitive, max_results

### 2. FileReadLinesTool  
**Purpose**: Read specific line ranges with context
**Parameters**: file_path, start_line, end_line, include_line_numbers, context_lines_before, context_lines_after

### 3. FileWriteLineTool
**Purpose**: Insert/replace/delete specific lines
**Parameters**: file_path, operation, target_line, content, line_count

### 4. FileSearchMultipleTool
**Purpose**: Search across multiple files
**Parameters**: search_pattern, search_type, file_patterns, exclude_patterns, max_files, context_lines

## Implementation Tasks

### Task 1: Core Infrastructure (2-3 hours)
- [ ] Create `FileSearchService` class in `cli/src/services/fileSearchService.ts`
- [ ] Add line-based methods to existing `FileService`
- [ ] Create utility functions for line operations and context extraction
- [ ] Add file pattern matching utilities

### Task 2: FileSearchTool (1-2 hours)
- [ ] Create `cli/src/services/tools/FileSearchTool.ts`
- [ ] Implement single-file search with regex/text support
- [ ] Add context line extraction
- [ ] Add result formatting and limiting

### Task 3: FileReadLinesTool (1-2 hours)
- [ ] Create `cli/src/services/tools/FileReadLinesTool.ts`
- [ ] Implement line range reading with validation
- [ ] Add context line support
- [ ] Add line numbering options

### Task 4: FileWriteLineTool (2-3 hours)
- [ ] Create `cli/src/services/tools/FileWriteLineTool.ts`
- [ ] Implement insert/replace/delete operations
- [ ] Add operation preview functionality
- [ ] Add atomic operations with error handling

### Task 5: FileSearchMultipleTool (2-3 hours)
- [ ] Create `cli/src/services/tools/FileSearchMultipleTool.ts`
- [ ] Implement file pattern matching
- [ ] Add cross-file search with result aggregation
- [ ] Add performance optimizations

### Task 6: Integration (1 hour)
- [ ] Register new tools in `ToolManager.ts`
- [ ] Update tool documentation
- [ ] Add agent guidance for new tools

### Task 7: Testing (2 hours)
- [ ] Create unit tests for each new tool
- [ ] Create integration test scenarios
- [ ] Test with various file types and sizes

## File Structure
```
cli/src/services/
├── fileSearchService.ts          # New search service
├── fileService.ts                # Enhanced with line methods
└── tools/
    ├── FileSearchTool.ts         # New
    ├── FileReadLinesTool.ts      # New  
    ├── FileWriteLineTool.ts      # New
    └── FileSearchMultipleTool.ts # New
```

## Tool Call Examples

### Search in file
```xml
<tool_call name="file_search" id="1">
  <file_path>src/app.ts</file_path>
  <search_pattern>function.*async</search_pattern>
  <search_type>regex</search_type>
  <context_lines_after>3</context_lines_after>
</tool_call>
```

### Read specific lines
```xml
<tool_call name="read_file_lines" id="2">
  <file_path>src/config.ts</file_path>
  <start_line>10</start_line>
  <end_line>20</end_line>
  <context_lines_before>2</context_lines_before>
</tool_call>
```

### Insert line
```xml
<tool_call name="write_file_line" id="3">
  <file_path>src/utils.ts</file_path>
  <operation>insert</operation>
  <target_line>15</target_line>
  <content>console.log('Debug point');</content>
</tool_call>
```

### Search multiple files
```xml
<tool_call name="search_files" id="4">
  <search_pattern>import.*React</search_pattern>
  <search_type>regex</search_type>
  <file_patterns>["src/**/*.tsx", "src/**/*.ts"]</file_patterns>
  <exclude_patterns>["**/*.test.*"]</exclude_patterns>
</tool_call>
```

## Success Criteria
- [ ] All 4 new tools implemented and registered
- [ ] Tools work with existing XML parsing
- [ ] Performance acceptable for files up to 10k lines
- [ ] Error handling for edge cases
- [ ] Integration tests pass
- [ ] Agent can use tools effectively for code analysis/modification

## Estimated Total Time: 10-15 hours