npm package: @lemantorus/code-collector
Description: TUI utility to collect all code files into a single XML file - perfect for AI assistants, code review, and documentation
Author: lemantorus
Latest version: 1.2.2

# 📦 Code Collector

[![npm version](https://badge.fury.io/js/@lemantorus%2Fcode-collector.svg)](https://badge.fury.io/js/@lemantorus%2Fcode-collector)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)

> **Collect all your code into a single XML file** — perfect for AI assistants, code review, and documentation.

A powerful TUI (Terminal User Interface) utility that scans your project and aggregates all code files into one structured XML document with token counting, smart filtering, and built-in ignore presets.

## ✨ Features

- 🖥️ **Interactive TUI** — Navigate directories with keyboard, preview selections
- 🔢 **Token Counting** — GPT tokenizer integration for accurate token counts
- 🎯 **12+ Ignore Presets** — Node.js, Python, Rust, Go, Java, and more
- ⚡ **CI/CD Friendly** — Run without TUI in automated pipelines
- 📋 **Clipboard Integration** — Output path automatically copied
- 🔧 **Custom Rules** — Add your own ignore patterns for directories, files, or extensions

## 📦 Installation

```bash
# Install globally
npm install -g @lemantorus/code-collector

# Or use with npx (no installation required)
npx @lemantorus/code-collector --path ~/my-project
```

## 🚀 Quick Start

```bash
# Interactive mode (default)
code-collector

# Specify a directory
code-collector --path ~/projects/my-app

# CI mode (no TUI)
code-collector --no-tui

# Custom output file
code-collector --output my-code.xml
```

## 📋 CLI Options

| Option | Alias | Description | Default |
|--------|-------|-------------|---------|
| `--path` | `-p` | Starting directory | Current directory |
| `--output` | `-o` | Output filename | `all_code.txt` |
| `--no-tui` | | Run without TUI (CI mode) | `false` |
| `--open` | | Open output file after collection | `false` |
| `--help` | `-h` | Show help | |
| `--version` | `-v` | Show version | |

## ⌨️ TUI Keyboard Shortcuts

### File Browser

| Key | Action |
|-----|--------|
| `↑` / `↓` | Navigate directories |
| `Enter` | Enter directory |
| `Backspace` / `Esc` | Go to parent directory |
| `R` | Run collection |
| `I` | Open ignore settings |
| `P` | Quick presets menu |
| `/` | Search directories |
| `Q` | Quit |

### Ignore Settings

| Key | Action |
|-----|--------|
| `↑` / `↓` | Navigate presets |
| `Enter` | Toggle preset on/off |
| `E` | Edit preset rules |
| `A` | Add custom rule |
| `S` | Save and go back |
| `/` | Search presets |
| `Esc` | Cancel |

### Category Editor

| Key | Action |
|-----|--------|
| `D` | Show Directories |
| `F` | Show Files |
| `E` | Show Extensions |
| `↑` / `↓` | Navigate rules |
| `A` | Add new rule |
| `X` | Delete selected rule |
| `S` | Save changes |
| `Esc` | Cancel |

## 🎯 Built-in Ignore Presets

| Preset | Ignores |
|--------|---------|
| **Node.js** | `node_modules/`, `dist/`, `build/` |
| **Python** | `venv/`, `.venv/`, `__pycache__/`, `*.pyc` |
| **Rust** | `target/`, `Cargo.lock` |
| **Go** | `vendor/` |
| **Java/Kotlin** | `.gradle/`, `*.class` |
| **Databases** | `*.db`, `*.sqlite`, `*.sqlite3` |
| **Build Artifacts** | `dist/`, `build/`, `out/`, `target/` |
| **VCS** | `.git/`, `.svn/`, `.hg/` |
| **Secrets** | `.env`, `*.pem`, `*.key`, `credentials.*` |
| **Media** | `*.png`, `*.jpg`, `*.gif`, `*.zip`, `*.mp4` |
| **IDE** | `.idea/`, `.vscode/`, `*.iml` |
| **JavaScript** | `*.min.js`, `*.min.css` |

## 📄 Output Format

The output is a structured XML file:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<codebase project="/path/to/project" generated="2025-01-15T12:00:00Z">
  <meta>
    <totalFiles>42</totalFiles>
    <totalTokens>15234</totalTokens>
    <totalSize>125000</totalSize>
  </meta>
  
  <file path="src/index.ts" lang="typescript" tokens="150">
    <content><![CDATA[
// Your code here
export function hello() {
  return "Hello, World!";
}
]]></content>
  </file>
  
  <file path="src/utils.ts" lang="typescript" tokens="85">
    <content><![CDATA[
// Utility functions
export const formatDate = (d: Date) => d.toISOString();
]]></content>
  </file>
</codebase>
```

## 🔧 Adding Custom Rules

In the TUI:
1. Press `I` to open Ignore Settings
2. Press `A` to add a custom rule
3. Choose type: `[D]irectory`, `[F]ile`, or `[E]xtension`
4. Enter the pattern (supports glob patterns)

Examples:
- Directory: `my-build-folder`
- File: `*.generated.ts`
- Extension: `.min.js`

## 🤖 Use Cases

### For AI Assistants
Collect your entire codebase into a single file to provide context to ChatGPT, Claude, or other AI tools:
```bash
code-collector --no-tui --output context.txt
```

### For Code Review
Generate a comprehensive view of all changes:
```bash
code-collector --path ./my-feature
```

### For Documentation
Create code snapshots for tutorials or documentation.

### For CI/CD
Run in automated pipelines:
```yaml
- name: Collect code
  run: npx @lemantorus/code-collector --no-tui --output artifacts/codebase.xml
```

## 🛠️ Development

```bash
# Clone the repository
git clone https://github.com/lemantorus/code-collector.git
cd code-collector

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm run dev

# Type check
npx tsc --noEmit
```

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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) file for details.

## 🙏 Acknowledgments

- [Ink](https://github.com/vadimdemedes/ink) - React for interactive CLI apps
- [GPT Tokenizer](https://github.com/niklashigi/gpt-tokenizer) - Accurate GPT token counting
- [Commander.js](https://github.com/tj/commander.js) - CLI framework

---

Made with ❤️ by [lemantorus](https://github.com/lemantorus)