Metadata-Version: 2.3
Name: contextcraft
Version: 1.0.1
Summary: A CLI toolkit to generate comprehensive project context for LLMs.
License: MIT
Keywords: llm,cli,context,toolkit,documentation
Author: Shourya Maheshwari shorz2905@gmail.com
Requires-Python: >=3.9,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Utilities
Requires-Dist: pathspec (>=0.12.1,<0.13.0)
Requires-Dist: pyperclip (>=1.9.0,<2.0.0)
Requires-Dist: rich (>=13.0.0,<14.0.0)
Requires-Dist: toml (>=0.10.2,<0.11.0)
Requires-Dist: tomli (>=2.0.0,<3.0.0) ; python_version < "3.11"
Requires-Dist: typer (>=0.9.0,<0.10.0)
Project-URL: Documentation, https://shorzinator.github.io/ContextCraft/
Project-URL: Homepage, https://github.com/Shorzinator/ContextCraft
Project-URL: Repository, https://github.com/Shorzinator/ContextCraft
Description-Content-Type: text/markdown

<div align="center">

# ContextCraft</center>
</div>

<div align="center">

[![CI](https://github.com/Shorzinator/ContextCraft/workflows/ContextCraft%20CI/badge.svg)](https://github.com/Shorzinator/ContextCraft/actions)
[![Coverage](https://img.shields.io/badge/coverage-77%25-yellow)](https://github.com/Shorzinator/ContextCraft)
[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Code style: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

</div>

<div align="center">

**A powerful CLI toolkit to generate comprehensive project context for Large Language Models (LLMs).</center>**
</div>

ContextCraft transforms your codebase into well-structured, LLM-friendly documentation by intelligently aggregating directory trees, code files, dependencies, and Git context into clean, consumable formats. It's like a translator between your repo and the digital mind you just hired to read it.

Transform your entire codebase into AI-ready context with one command.
No more copy-paste nightmares. No more explaining your project structure.
Just instant, comprehensive context that LLMs actually understand.

## ✨ Features

### 🌳 **Smart Directory Trees**
- Beautiful, hierarchical project structure visualization
- Rich console output with emojis and colors
- Intelligent filtering with `.llmignore` support
- Clean file output for documentation

### 📄 **Code Flattening**
- Concatenate multiple files into organized documents
- Clear file markers and intelligent content handling
- Support for include/exclude patterns
- Binary file detection and graceful handling

### 📦 **Dependency Analysis**
- Multi-language dependency extraction (Python, Node.js)
- Support for Poetry, pip, npm, and yarn
- Clean Markdown output with language grouping
- Extensible architecture for additional languages

### 🔄 **Git Context**
- Current branch and status information
- Recent commit history with configurable depth
- Diff analysis for understanding changes
- Graceful handling of non-Git repositories

### 📋 **Context Bundling**
- Aggregate multiple tools into comprehensive bundles
- Configurable section inclusion/exclusion
- Well-structured Markdown with navigation
- Perfect for LLM consumption

### 📋 **Clipboard Integration**
- Copy output directly to clipboard with `--to-clipboard` or `-c`
- Available for all commands (tree, flatten, deps, git-info, bundle)
- Smart behavior: only works when no output file specified
- Cross-platform support with graceful error handling

### 🎯 **Intelligent Filtering**
- `.llmignore` files with `.gitignore`-style syntax
- Configurable global patterns via `pyproject.toml`
- Smart precedence hierarchy
- Tool-specific fallback exclusions

---

## 🚀 Quick Start

### Installation

```bash
# Install from PyPI (coming soon)
pip install contextcraft

# Or install from source
git clone https://github.com/Shorzinator/ContextCraft.git
cd ContextCraft
poetry install
```

### Basic Usage

```bash
# Generate a directory tree
contextcraft tree

# Save tree to file
contextcraft tree -o project_structure.txt

# Copy tree to clipboard
contextcraft tree --to-clipboard

# Flatten code files
contextcraft flatten src/ -o flattened_code.md

# Copy flattened code to clipboard
contextcraft flatten src/ -c

# Analyze dependencies
contextcraft deps

# Get Git context
contextcraft git-info

# Create a comprehensive bundle
contextcraft bundle -o project_context.md

# Copy bundle to clipboard
contextcraft bundle --to-clipboard
```

### Configuration

Create a `.llmignore` file to exclude files and directories:

```gitignore
# .llmignore
*.log
__pycache__/
node_modules/
.env
build/
dist/
```

Configure defaults in `pyproject.toml`:

```toml
[tool.contextcraft]
default_output_filename_tree = "project_tree.txt"
default_output_filename_flatten = "flattened_code.md"
default_output_filename_deps = "dependencies.md"
default_output_filename_git_info = "git_context.md"
default_output_filename_bundle = "project_bundle.md"

global_exclude_patterns = [
    "*.tmp",
    "temp/",
    ".cache/"
]
```

## 📖 Documentation

**🌐 [Live Documentation Website](https://shorzinator.github.io/ContextCraft/)**

Comprehensive documentation including:

- **[Getting Started](https://shorzinator.github.io/ContextCraft/getting-started/installation/)** - Installation and basic usage
- **[CLI Commands](https://shorzinator.github.io/ContextCraft/user-guide/cli-commands/)** - Complete command reference
- **[Configuration](https://shorzinator.github.io/ContextCraft/getting-started/configuration/)** - Advanced configuration options
- **[API Reference](https://shorzinator.github.io/ContextCraft/reference/)** - Detailed API documentation
- **[Examples](https://shorzinator.github.io/ContextCraft/examples/)** - Real-world usage examples
- **[Tutorials](https://shorzinator.github.io/ContextCraft/tutorials/)** - Step-by-step guides

## 🛠️ Development

### Prerequisites

- Python 3.9+
- Poetry
- Git

### Setup

```bash
# Clone the repository
git clone https://github.com/Shorzinator/ContextCraft.git
cd ContextCraft

# Install dependencies
poetry install --with dev

# Install pre-commit hooks
poetry run pre-commit install

# Run tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=src/contextcraft --cov-report=html
```

### Code Quality

We maintain high code quality standards. Some say it's obsessive. We say it's... necessary:

- **Linting**: Ruff for fast Python linting (not a dog, but still keeps your repo clean)
- **Formatting**: Ruff formatter for consistent code style
- **Security**: Bandit for security vulnerability scanning
- **Testing**: Pytest with 77%+ coverage (because 100% would be... suspicious)
- **Commits**: Conventional Commits for clear history and less git shame

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:

- Reporting bugs and requesting features
- Development setup and workflow
- Code standards and testing
- Pull request process

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. (TL;DR: Use it, don’t sue us.)

## 🙏 Acknowledgments

- Built with [Typer](https://typer.tiangolo.com/) for the CLI framework
- Styled with [Rich](https://rich.readthedocs.io/) for beautiful terminal output
- Powered by [Poetry](https://python-poetry.org/) for dependency management
- Quality assured with [Ruff](https://github.com/astral-sh/ruff) and [Pytest](https://pytest.org/)

## 📊 Project Status

ContextCraft is actively developed and maintained. Current status:

- ✅ **Core Tools**: All primary tools implemented and tested
- ✅ **CLI Interface**: Complete command-line interface
- ✅ **Documentation**: Comprehensive docs with examples
- ✅ **Testing**: 175+ tests with 77% coverage
- ✅ **CI/CD**: Automated testing and quality checks
- 🚀 **V1.0**: Feature-complete and production-ready

---

<div align="center">

**[📖 Documentation](https://shorzinator.github.io/ContextCraft/) • [🐛 Issues](https://github.com/Shorzinator/ContextCraft/issues) • [💬 Discussions](https://shorzinator.github.io/ContextCraft/community/)**

Made with ❤️ for the developer community

</div>

