projpack 1.0.0
Bundle project files into single text file for AI analysis
License: MIT
Requires Python: >=3.7
Keywords: project, bundling, ai, tools, development, utility

# ProjPack 📦

**Bundle entire projects into single text files for AI analysis**

ProjPack solves the problem of sharing complex projects with AI tools by intelligently bundling all relevant files into a single, well-structured text document. Perfect for code reviews, debugging sessions, documentation generation, or any scenario where you need to provide complete project context to an AI assistant.

## 🚀 Quick Start

```bash
# Install ProjPack
pip install projpack

# Bundle your project
projpack pack /path/to/your/project

# Preview what would be included
projpack scan /path/to/your/project -v
```

## ✨ Features

- **🎯 Smart File Filtering**: Automatically excludes binary files, build artifacts, and dependencies
- **📝 Gitignore-like Syntax**: Uses `.ppignore` files with familiar pattern matching
- **🌳 Structured Output**: Clear file organization with metadata and tree views
- **⚡ Configurable**: Customizable file size limits, ignore patterns, and output formats
- **🛡️ Safe by Default**: Includes comprehensive default ignore patterns
- **🌍 Unicode Support**: Handles international characters and various encodings
- **📊 Detailed Statistics**: Processing metrics and file categorization

## 📦 Installation

### From PyPI (Recommended)
```bash
pip install projpack
```

### From Source
```bash
git clone https://github.com/yourusername/projpack.git
cd projpack
pip install -e .
```

## 🏃‍♂️ Usage

### Basic Commands

#### Bundle a Project
```bash
# Bundle current directory
projpack pack .

# Bundle specific directory with custom output
projpack pack /path/to/project -o my_bundle.txt

# Verbose output with statistics
projpack pack . -v
```

#### Preview Project Analysis
```bash
# See what files would be included
projpack scan . -v

# List all files that would be processed
projpack scan . --list-files

# Check processing statistics
projpack scan . 
```

#### Initialize Ignore File
```bash
# Create default .ppignore in current directory
projpack init

# Create .ppignore in specific directory
projpack init /path/to/project
```

### Command Options

#### `projpack pack` Options
- `-o, --output`: Output file path (default: `<project_name>_bundle.txt`)
- `-i, --ignore-file`: Custom ignore file path
- `-s, --max-size`: Maximum file size in MB (default: 10)
- `-v, --verbose`: Enable detailed output
- `-f, --force`: Overwrite existing files without confirmation
- `--no-stats`: Exclude statistics from bundle header

#### `projpack scan` Options
- `-i, --ignore-file`: Custom ignore file path
- `-s, --max-size`: Maximum file size in MB (default: 10)
- `-v, --verbose`: Enable detailed output
- `-l, --list-files`: Show all files that would be processed

## 🚫 Ignore Patterns

ProjPack uses `.ppignore` files with gitignore-like syntax to exclude unwanted files.

### Default Patterns
ProjPack automatically ignores common files:
- **Python**: `__pycache__/`, `*.pyc`, `*.pyo`, `build/`, `dist/`, `*.egg-info/`
- **Node.js**: `node_modules/`, `.npm`, `bower_components/`
- **Version Control**: `.git/`, `.svn/`, `.hg/`, `.bzr/`
- **Virtual Environments**: `venv/`, `.venv`, `env/`, `ENV/`
- **OS Files**: `.DS_Store`, `Thumbs.db`, `*.swp`
- **Build Artifacts**: `build/`, `target/`, `bin/`, `obj/`

### Custom .ppignore Syntax

```bash
# Comments start with #
# This is a comment

# Ignore all .log files
*.log

# Ignore entire directories
temp/
cache/

# Use ** for recursive matching
**/node_modules/
**/*.tmp

# Negation with ! (include files that would otherwise be ignored)
!important.log
!src/**/*.min.js

# Absolute paths from project root
/specific-file.txt
/build/release/
```

### Pattern Examples

```bash
# Ignore all files with specific extensions
*.log
*.tmp
*.cache

# Ignore directories anywhere in the project
__pycache__/
node_modules/
.vscode/

# Ignore files in specific locations
/build/
/dist/
src/generated/

# Complex patterns
**/*.test.js          # All .test.js files in any subdirectory
src/**/*.min.*        # All minified files in src/ and subdirectories
!src/important.min.js # Exception: keep this specific minified file

# Environment and config files
.env
.env.local
config/secrets/
*.key
*.pem

# Temporary and cache files
*.swp
*.swo
*~
.cache/
tmp/
```

## 📄 Output Format

ProjPack creates well-structured bundles with:

```text
================================================================================
PROJECT BUNDLE GENERATED BY PROJPACK
================================================================================

Project Root: /path/to/your/project
Generated: 2024-01-20 15:30:45
Total Files: 25

STATISTICS:
  Files processed: 15
  Total size: 45.2 KB
  Files ignored: 8
  Binary files skipped: 2
  Large files skipped: 0
  Directories scanned: 8
  Processing time: 0.15s

FILE STRUCTURE:
├── src/
│   ├── main.py
│   ├── utils/
│   │   ├── helpers.py
│   │   └── constants.py
│   └── tests/
│       └── test_main.py
├── README.md
├── requirements.txt
└── setup.py

================================================================================
FILE CONTENTS
================================================================================

FILE: src/main.py
------------------------------------------------------------
Size: 2.1 KB
Encoding: utf-8
------------------------------------------------------------

#!/usr/bin/env python3
"""Main application module."""

def main():
    print("Hello, World!")

if __name__ == "__main__":
    main()


FILE: README.md
------------------------------------------------------------
Size: 1.5 KB
Encoding: utf-8
------------------------------------------------------------

# My Project

This is a sample project...

================================================================================
END OF PROJECT BUNDLE
================================================================================
```

## 🔧 Advanced Usage

### Custom File Size Limits
```bash
# Allow larger files (50MB limit)
projpack pack . -s 50

# Strict limit for smaller bundles (1MB limit)
projpack pack . -s 1
```

### Custom Ignore Files
```bash
# Use custom ignore file
projpack pack . -i my-custom.ignore

# Use ignore file from different location
projpack pack . -i /path/to/custom/.ppignore
```

### Integration with Scripts
```python
from projpack import ProjectPacker

# Programmatic usage
packer = ProjectPacker(
    project_root="/path/to/project",
    max_file_size=5 * 1024 * 1024,  # 5MB
    include_stats=True
)

# Scan project
files, stats = packer.scan_project(verbose=True)

# Create bundle
bundle_content = packer.pack_project(
    output_file="my_bundle.txt",
    verbose=True
)

# Get summary
summary = packer.get_project_summary()
print(f"Processed {summary['processed_files']} files")
```

## 🎯 Use Cases

### AI-Assisted Development
- **Code Reviews**: Share entire codebase context with AI
- **Debugging**: Provide complete project context for error analysis
- **Documentation**: Generate comprehensive project documentation
- **Refactoring**: Analyze project structure for improvement suggestions

### Project Analysis
- **Dependency Analysis**: Understand project structure and dependencies
- **Code Quality**: Review entire codebase for patterns and issues
- **Knowledge Transfer**: Share project understanding with team members
- **Backup**: Create text-based project snapshots

### Educational
- **Code Sharing**: Share projects in forums or educational platforms
- **Portfolio**: Create readable project summaries
- **Learning**: Analyze open-source project structures

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Setup
```bash
git clone https://github.com/yourusername/projpack.git
cd projpack
pip install -e ".[dev]"
```

### Running Tests
```bash
# Run basic tests
python tests/test_basic.py

# Run with pytest (if available)
pytest tests/

# Test CLI commands
projpack scan tests/fixtures/sample_project
```

## 📋 Requirements

- Python 3.7+
- `chardet` (for encoding detection)

## 📜 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🐛 Bug Reports & Feature Requests

Please use the [GitHub Issues](https://github.com/yourusername/projpack/issues) page to report bugs or request features.

## 📞 Support

- 📖 Documentation: [GitHub README](https://github.com/MFael1/projpack#readme)
- 🐛 Issues: [GitHub Issues](https://github.com/MFael1/projpack/issues)
- 💬 Discussions: [GitHub Discussions](https://github.com/MFael1/projpack/discussions)

---

**Made with ❤️ for the AI-assisted development community**