Metadata-Version: 2.2
Name: patchcommander
Version: 1.2
Summary: AI-assisted coding automation tool for streamlined LLM code integration
Author: PatchCommander Team
Author-email: jacekjursza <jacek.jursza@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Jacek Jursza
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/jacekjursza/PatchCommander
Project-URL: Bug Tracker, https://github.com/jacekjursza/PatchCommander/issues
Keywords: ai,development,code-generation,llm,automation
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Intended Audience :: Developers
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=12.6.0
Requires-Dist: pyperclip>=1.8.2
Requires-Dist: tree-sitter>=0.20.0
Requires-Dist: tree-sitter-python>=0.20.0
Requires-Dist: tree-sitter-javascript>=0.20.0
Requires-Dist: diff-match-patch>=20200713
Requires-Dist: textual>=0.14.0
Dynamic: author
Dynamic: requires-python

# PatchCommander

PatchCommander is a powerful tool designed to streamline AI-assisted development workflows. It processes code changes generated by Large Language Models (LLMs) using a specific tag-based syntax, enabling developers to seamlessly apply AI-generated modifications across their codebase.



## Why PatchCommander?

Traditional copy-pasting of code suggested by LLMs is error-prone and time-consuming, especially when changes span multiple files or require careful integration into existing code. PatchCommander solves this by:

1. **Defining a structured tag syntax** that LLMs can be instructed to follow
2. **Automatically processing these tags** to make precise modifications to your codebase
3. **Providing safety features** like diff previews and syntax validation before changes are applied
4. **Handling complex code manipulations** like class merging and method updates intelligently

This creates a seamless workflow between AI code suggestions and practical implementation.

## Features

- **LLM-friendly tag syntax**: Simple XML-like tags that AI models can easily adopt
- **Multiple change types**: Support for file, class, function, method, and operation modifications
- **XPath targeting**: Target specific code elements using intuitive path syntax (e.g., `ClassName.method_name`)
- **Smart class merging**: Intelligently combines new class implementations with existing ones
- **Diff preview**: View changes before applying them, with side-by-side comparison option
- **Syntax validation**: Automatically checks for syntax errors and reverts changes if errors are found
- **Clipboard support**: Read input directly from clipboard when no file is specified
- **Multi-language support**: Works with Python and JavaScript/TypeScript files
- **API Access**: Use programmatically in your own tools and workflows

## Installation

### Option 1: Using pipx (recommended for command-line tools)

```bash
pipx install patchcommander
```

### Option 2: Using pip 

```bash
pip install patchcommander
```

### Option 3: Using uv

```bash
uv install patchcommander
```

### Option 4: From source

```bash
# Clone the repository
git clone https://github.com/jacekjursza/PatchCommander.git

# Navigate to the directory
cd PatchCommander

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .
```

## Quick Start

After installation, you can use PatchCommander with the shorter command:

```bash
# Run with input from clipboard (no arguments)
pcmd

# Run with input from a file
pcmd path/to/input_file.txt

# Show help
pcmd --help

# Display LLM instructions and syntax guide
pcmd --prompt

# Display only the tag syntax guide for LLMs
pcmd --syntax
```

## Tag Syntax for LLMs

When prompting your LLM, instruct it to format code changes using the following tags:

### FILE

Replace an entire file's content:

```
<FILE path="path/to/file.py">
# New file content goes here
</FILE>
```

### FILE with XPath

Update or add a specific element in a file using XPath:

```
<FILE path="path/to/file.py" xpath="ClassName">
class ClassName:
    # Updated class content
</FILE>

<FILE path="path/to/file.py" xpath="ClassName.method_name">
def method_name(self, args):
    # Updated method implementation
</FILE>

<FILE path="path/to/file.py" xpath="function_name">
def function_name(args):
    # Updated function implementation
</FILE>
```

### Line Range Targeting

Update specific line ranges in a file:

```
<FILE path="path/to/file.py" xpath="lines:10:20">
# This content will replace lines 10-20
</FILE>
```

### OPERATION

Perform file operations:

```
<OPERATION action="move_file" source="old/path.py" target="new/path.py" />

<OPERATION action="delete_file" source="path/to/file.py" />

<OPERATION action="delete_method" source="path/to/file.py" class="ClassName" method="method_name" />
```

## AI-Assisted Development Workflow

1. **Prompt the LLM**: Ask your LLM to implement a feature or fix a bug, instructing it to format changes using PatchCommander's tag syntax
2. **Copy the output**: Save the LLM's response with the tagged code changes to a file or clipboard
3. **Run PatchCommander**: Process the changes using `pcmd [filename]` or just `pcmd` for clipboard content
4. **Review the changes**: Examine the diffs for each proposed change (with side-by-side view if needed)
5. **Confirm or reject**: Choose which changes to apply
6. **Apply changes**: All confirmed changes are applied at once at the end of the process

## Example Prompt for LLMs

```
Please implement a user authentication system for my Flask application.
Format your response using PatchCommander tag syntax:
- Use <FILE> tags for new files or complete file replacements
- Use <FILE> tags with xpath attribute for targeting specific elements
- Use <OPERATION> tags for file operations

Example format:
<FILE path="app/auth.py">
[code here]
</FILE>

<FILE path="app/utils.py" xpath="validate_password">
def validate_password(password):
    [updated function code]
</FILE>

<FILE path="app/models.py" xpath="User.authenticate">
def authenticate(self, password):
    [method code here]
</FILE>
```

## Integration with Development Tools

PatchCommander can be integrated into your development workflow in several ways:

### Using the API

```python
from patchcommander.api import process_text, apply_changes

# Process changes from text
results = process_text("""
<FILE path="app.py" xpath="main">
def main():
    print("Hello, updated world!")
</FILE>
""")

# Apply the changes
apply_changes(results, auto_approve=True)
```

## Advanced Features

### Smart Class Merging

When updating a class, PatchCommander intelligently merges the new implementation with the existing one, preserving methods that aren't being changed while updating those that are.

### Syntax Validation

Before applying changes, PatchCommander validates the syntax of modified files to ensure they remain valid after changes are applied.

### Custom Configuration

Configure PatchCommander's behavior using the configuration UI:

```bash
pcmd --config
```

## License

[MIT License](LICENSE)

## Contributing

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

## Acknowledgements

- Tree-sitter for code parsing capabilities
- Textual for TUI components
- Rich for formatting and display
