fileweaver/README.md

A CLI tool to weave files together based on regex patterns

# 📁 FileWeaver

<div align="center">

![Version](https://img.shields.io/npm/v/fileweaver)
![Downloads](https://img.shields.io/npm/dm/fileweaver)
![License](https://img.shields.io/npm/l/fileweaver)
![Node](https://img.shields.io/node/v/fileweaver)

A powerful CLI tool for weaving files together with advanced pattern matching capabilities, featuring visual progress and tree view of processed files. Optimized for sharing code with Large Language Models (LLMs).

[Installation](#installation) •
[Usage](#usage) •
[Examples](#examples) •
[Contributing](#contributing)

</div>

## ✨ Features

- 🔍 **Regex Pattern Matching**: Filter files using regular expressions
- 🚫 **Exclusion Patterns**: Ignore files that match specific patterns
- 📂 **Directory Support**: Process files from any directory
- 📑 **File Headers**: Option to include original filenames in the output
- 🎯 **Flexible Output**: Specify custom output location and filename
- 🌳 **Tree View**: Visual representation of processed files with optional inclusion in output
- 📊 **Progress Bar**: Real-time processing visualization
- 🎨 **Colored Output**: Enhanced readability with color-coded messages
- 📝 **Custom Prompts**: Add custom prompts to the output file
- 🗂️ **Directory Tree**: Include directory structure in the output file
- 📏 **Token Estimation**: Get approximate token counts for LLM context management
- 📊 **Size Limiting**: Control output size to fit LLM context windows
- 🧹 **Comment Removal**: Strip comments to reduce size and focus on core code
- 📄 **Markdown Format**: Generate output in Markdown with proper code formatting
- 📋 **Project Summary**: Auto-generate project overviews from README and package.json
- ⭐ **File Prioritization**: Ensure important files appear first in the output
- 🔍 **Language Detection**: Automatically identify and tag programming languages

## 🚀 Installation

```bash
npm install -g fileweaver
```

## 🔧 Usage

```bash
fileweaver [options]
```

### Options

| Option | Description | Default |
|--------|-------------|---------|
| `-r, --regex <pattern>` | Regex pattern to match files | - |
| `-ir, --ignoreregex <pattern>` | Regex pattern to ignore files | - |
| `-d, --directory <path>` | Directory path | Current directory |
| `-h, --headers` | Add file headers to content | false |
| `-o, --output <file>` | Output file name | output.txt |
| `-t, --tree` | Include directory tree in output file | false |
| `-p, --prompt <text>` | Add custom prompt to output file | - |
| `-m, --markdown` | Format output as markdown with code blocks | false |
| `-tok, --tokens` | Show token estimation for LLMs | false |
| `-nc, --no-comments` | Strip comments from code files | false |
| `-s, --summary` | Include auto-generated project summary | false |
| `-i, --important <files>` | Comma-separated file patterns to prioritize | - |
| `-m, --max-size <size>` | Maximum output size in KB | Infinity |
| `--version` | Show version number | - |
| `--help` | Show help | - |

## 📋 Examples

### Basic File Concatenation with Tree

```bash
fileweaver -d . -r "\.js$" -t true -o combined.js
```

This will include a tree view in the output file:
```
==================================================
Directory Tree:
==================================================
├── src
│   ├── index.js
│   └── utils
│       ├── helper.js
│       └── validator.js
└── index.js
```

### Add Custom Prompt

```bash
fileweaver -r "\.md$" -p "Process these markdown files for documentation" -o docs.md
```

Output will include:
```
==================================================
Prompt:
==================================================
Process these markdown files for documentation
```

### LLM-Optimized Format with Token Estimation

```bash
fileweaver -r "\.(js|jsx)$" -markdown -tokens -o for-llm.md
```

This will:
- Format all JavaScript files with Markdown code blocks
- Add language tags to each code block
- Include token count estimation for LLM context management

### Generate Project Summary with Key Files First

```bash
fileweaver -s -i "index.js,main.jsx,README.md" -markdown -o project-overview.md
```

This will:
- Generate a project summary from README and package.json
- Prioritize the specified important files
- Format everything as Markdown

### Size-Limited Export for LLM Context

```bash
fileweaver -r "src/" -max-size 100 -tokens -nc -o llm-input.txt
```

This will:
- Process all files in the src directory
- Limit output to 100KB to fit LLM context windows
- Remove comments to save space
- Show token estimation
- Save to llm-input.txt

### Combine Multiple LLM-Optimized Features

```bash
fileweaver -d ./src -r "\.(js|ts)$" -markdown -tokens -nc -s -i "index.js,App.tsx" -max-size 150 -o llm-ready.md
```

This will:
- Process all JS and TS files
- Format with Markdown
- Remove comments
- Include project summary
- Prioritize important files
- Limit size to 150KB
- Estimate tokens
- Save as llm-ready.md

## 🔍 Advanced Usage

### Complete LLM Project Analysis

Generate a comprehensive project overview optimized for code review by LLMs:

```bash
fileweaver -d ./project -s -markdown -tokens -i "index.js,package.json,src/App.js" -t true -p "Please review this React project codebase and suggest improvements" -o llm-review.md
```

This will:
- Process all files in the project
- Generate a project summary
- Format with Markdown code blocks
- Prioritize key files at the beginning
- Include directory tree
- Add token estimations
- Add the specified prompt for the LLM

### Code Exploration with Size Constraints

```bash
fileweaver -r "\.jsx?$" -ir "test|mock" -markdown -nc -max-size 50 -o explore.md
```

This will:
- Process all JavaScript files (excluding test and mock files)
- Format with Markdown
- Remove comments
- Limit output to 50KB
- Save to explore.md

## 🤝 Contributing

Contributions are welcome! Feel free to:

1. Fork the repository
2. Create your feature branch: `git checkout -b feature/amazing-feature`
3. Commit your changes: `git commit -m 'Add amazing feature'`
4. Push to the branch: `git push origin feature/amazing-feature`
5. Open a Pull Request

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE.md) file for details.

## 🛟 Support

For support and questions, please [open an issue](https://github.com/c2developers/fileweaver/issues) on GitHub.

---

<div align="center">
Made with ❤️ by C2Developers
</div>