# {{ cookiecutter.project_name }}

{{ cookiecutter.project_description }}

## Features

✨ **Professional-Grade Foundation**: Built with kens-pythontools, providing 99% coverage for CLI use cases

🛡️ **Robust Error Handling**: Comprehensive error management with user-friendly messages and proper exit codes

🔒 **Security-First**: Input sanitization, path validation, secure configuration management

⚡ **Performance Monitoring**: Built-in timing, memory monitoring, and progress tracking

🧪 **Testing Ready**: Complete testing utilities and mock data generation

{% if cookiecutter.use_plugins == "yes" -%}
🔌 **Plugin Architecture**: Extensible plugin system for adding custom functionality
{% endif -%}

{% if cookiecutter.use_async == "yes" -%}
🚀 **Async Support**: Full async/await support with retry logic and progress tracking
{% endif -%}

{% if cookiecutter.use_rich == "yes" -%}
🎨 **Beautiful Output**: Rich terminal output with colors, tables, and progress bars
{% endif -%}

## Installation

### From Source

```bash
git clone <repository-url>
cd {{ cookiecutter.project_slug }}

# Option 1: Use the setup script (recommended)
./setup.sh          # On Linux/macOS
python setup.py      # Cross-platform alternative

# Option 2: Manual installation
{% if cookiecutter.package_manager == "uv" -%}
uv sync
{% elif cookiecutter.package_manager == "poetry" -%}
poetry install
{% elif cookiecutter.package_manager == "pipenv" -%}
pipenv install
{% else -%}
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .
{% endif -%}
```

### Using pip

```bash
pip install {{ cookiecutter.project_slug }}
```

## Quick Start

```bash
# Basic usage
{{ cookiecutter.project_slug }} hello --name "World"

# Show version
{{ cookiecutter.project_slug }} version

{% if cookiecutter.use_plugins == "yes" -%}
# List loaded plugins
{{ cookiecutter.project_slug }} plugins
{% endif -%}

# Get help
{{ cookiecutter.project_slug }} --help
```

## Core Utilities

This project includes a comprehensive set of core utilities:

### Error Handling
```python
from {{ cookiecutter.project_slug }}.core import handle_errors, CLIError

@handle_errors()
def my_command():
    if something_wrong:
        raise CLIError("User-friendly message",
                      user_message="What the user should see")
```

### Input Validation & Security
```python
from {{ cookiecutter.project_slug }}.core import sanitize_input, validate_config

# Sanitize user input
clean_input = sanitize_input(user_input, max_length=100)

# Validate configuration
config = validate_config(config_data, MyConfigClass)
```

### Performance Monitoring
```python
from {{ cookiecutter.project_slug }}.core import Timer, PerformanceProfiler

# Simple timing
timer = Timer("operation")
with timer.measure():
    # Your code here
    pass

# Advanced profiling
profiler = PerformanceProfiler()
with profiler.profile("complex_operation"):
    # Your code here
    pass
```

{% if cookiecutter.use_async == "yes" -%}
### Async Operations
```python
from {{ cookiecutter.project_slug }}.core import run_async, gather_with_progress

@run_async
async def my_async_command():
    tasks = [async_operation(i) for i in range(10)]
    results = await gather_with_progress(*tasks, desc="Processing")
    return results
```
{% endif -%}

### Testing
```python
from {{ cookiecutter.project_slug }}.core import CLITestContext, MockDataGenerator

def test_my_feature():
    with CLITestContext() as ctx:
        # Create test files
        test_file = ctx.create_file("test.txt", "content")

        # Generate mock data
        csv_data = MockDataGenerator.csv_data(rows=10)

        # Test your CLI commands
        # ...
```

{% if cookiecutter.use_plugins == "yes" -%}
### Plugin Development
```python
from {{ cookiecutter.project_slug }}.core import CommandPlugin, plugin_command

class MyPlugin(CommandPlugin):
    name = "my_plugin"
    version = "1.0.0"
    description = "My custom plugin"

    def initialize(self) -> bool:
        return True

    def cleanup(self):
        pass

    def register_commands(self, app):
        app.command()(self.my_command)

    @plugin_command("my-cmd", help="My custom command")
    def my_command(self):
        print("Hello from plugin!")
```
{% endif -%}

## Development

### Setup Development Environment

```bash
{% if cookiecutter.package_manager == "poetry" -%}
# Install with development dependencies
poetry install --with dev

# Activate virtual environment
poetry shell
{% elif cookiecutter.package_manager == "pipenv" -%}
# Install with development dependencies
pipenv install --dev

# Activate virtual environment
pipenv shell
{% else -%}
# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"
{% endif -%}
```

{% if cookiecutter.use_testing == "yes" -%}
### Running Tests

```bash
{% if cookiecutter.package_manager == "poetry" -%}
poetry run pytest
{% elif cookiecutter.package_manager == "pipenv" -%}
pipenv run pytest
{% else -%}
pytest
{% endif -%}

# With coverage
{% if cookiecutter.package_manager == "poetry" -%}
poetry run pytest --cov={{ cookiecutter.project_slug }}
{% elif cookiecutter.package_manager == "pipenv" -%}
pipenv run pytest --cov={{ cookiecutter.project_slug }}
{% else -%}
pytest --cov={{ cookiecutter.project_slug }}
{% endif -%}
```
{% endif -%}

{% if cookiecutter.use_linting == "yes" -%}
### Code Quality

```bash
# Formatting
{% if cookiecutter.package_manager == "poetry" -%}
poetry run black {{ cookiecutter.project_slug }}
poetry run isort {{ cookiecutter.project_slug }}
{% elif cookiecutter.package_manager == "pipenv" -%}
pipenv run black {{ cookiecutter.project_slug }}
pipenv run isort {{ cookiecutter.project_slug }}
{% else -%}
black {{ cookiecutter.project_slug }}
isort {{ cookiecutter.project_slug }}
{% endif -%}

# Linting
{% if cookiecutter.package_manager == "poetry" -%}
poetry run flake8 {{ cookiecutter.project_slug }}
poetry run mypy {{ cookiecutter.project_slug }}
{% elif cookiecutter.package_manager == "pipenv" -%}
pipenv run flake8 {{ cookiecutter.project_slug }}
pipenv run mypy {{ cookiecutter.project_slug }}
{% else -%}
flake8 {{ cookiecutter.project_slug }}
mypy {{ cookiecutter.project_slug }}
{% endif -%}
```
{% endif -%}

## Examples

Check out the `examples/` directory for comprehensive usage examples:

- `example_usage.py` - Common CLI patterns and utilities
{% if cookiecutter.use_plugins == "yes" -%}
- `plugin_examples.py` - Plugin development examples
{% endif -%}

## Architecture

This CLI tool is built on the **kens-pythontools** foundation, which provides:

### Core Modules

- **`core/async_utils.py`** - Async patterns, retry logic, progress tracking
- **`core/error_handler.py`** - Professional error handling with proper exit codes
- **`core/performance.py`** - Performance monitoring, timing, memory tracking
- **`core/security.py`** - Input sanitization, path validation, credential management
- **`core/validators.py`** - Data validation with Pydantic, input validation
- **`core/testing.py`** - CLI testing utilities, mock data generation
{% if cookiecutter.use_plugins == "yes" -%}
- **`core/plugins.py`** - Plugin architecture and management
{% endif -%}

### Design Principles

1. **99% Coverage**: Provides foundational patterns for any CLI use case
2. **Security First**: All inputs are validated and sanitized
3. **Performance Aware**: Built-in monitoring and optimization
4. **Error Resilient**: Comprehensive error handling and recovery
5. **Testing Ready**: Utilities for easy testing and mocking
6. **Extensible**: Plugin architecture for custom functionality

## Configuration

{% if cookiecutter.use_config_files == "yes" -%}
### Configuration Files

The application supports configuration files in {{ cookiecutter.config_format }} format:

```{{ cookiecutter.config_format }}
{% if cookiecutter.config_format == "toml" -%}
[app]
debug = false
log_level = "INFO"

[database]
host = "localhost"
port = 5432
{% elif cookiecutter.config_format == "yaml" -%}
app:
  debug: false
  log_level: INFO

database:
  host: localhost
  port: 5432
{% elif cookiecutter.config_format == "json" -%}
{
  "app": {
    "debug": false,
    "log_level": "INFO"
  },
  "database": {
    "host": "localhost",
    "port": 5432
  }
}
{% endif -%}
```
{% endif -%}

### Environment Variables

Configuration can be provided via environment variables:

```bash
export {{ cookiecutter.project_slug|upper }}_DEBUG=true
export {{ cookiecutter.project_slug|upper }}_LOG_LEVEL=DEBUG
export {{ cookiecutter.project_slug|upper }}_API_KEY=your_api_key
```

{% if cookiecutter.use_plugins == "yes" -%}
### Plugin Configuration

Plugins are automatically discovered from:
- `./plugins/` - Project-specific plugins
- `~/.{{ cookiecutter.project_slug }}/plugins/` - User-specific plugins

Create a plugin by implementing the plugin interface:

```python
from {{ cookiecutter.project_slug }}.core.plugins import CommandPlugin

class MyPlugin(CommandPlugin):
    # Plugin implementation
    pass
```
{% endif -%}

{% if cookiecutter.use_logging == "yes" -%}
## Logging

The application uses structured logging with automatic log rotation:

- **Console**: INFO level and above
- **File**: DEBUG level and above (`{{ cookiecutter.project_slug }}.log`)
- **Rotation**: 10MB files, 7 day retention

Configure logging level:
```bash
{{ cookiecutter.project_slug }} --log-level DEBUG command
```
{% endif -%}

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for your changes
{% if cookiecutter.use_linting == "yes" -%}
5. Ensure code quality (`black`, `isort`, `flake8`, `mypy`)
{% endif -%}
{% if cookiecutter.use_testing == "yes" -%}
6. Run tests (`pytest`)
{% endif -%}
7. Commit your changes (`git commit -m 'Add amazing feature'`)
8. Push to the branch (`git push origin feature/amazing-feature`)
9. Open a Pull Request

{% if cookiecutter.use_pre_commit == "yes" -%}
### Pre-commit Hooks

This project uses pre-commit hooks to ensure code quality:

```bash
pre-commit install
```
{% endif -%}

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Acknowledgments

- Built with [kens-pythontools](https://github.com/example/kens-pythontools) - The optimal foundation for Python CLI tools
{% if cookiecutter.cli_framework == "typer" -%}
- [Typer](https://typer.tiangolo.com/) - Modern Python CLI framework
{% elif cookiecutter.cli_framework == "click" -%}
- [Click](https://click.palletsprojects.com/) - Python CLI framework
{% endif -%}
{% if cookiecutter.use_rich == "yes" -%}
- [Rich](https://rich.readthedocs.io/) - Beautiful terminal output
{% endif -%}
{% if cookiecutter.use_logging == "yes" -%}
- [Loguru](https://loguru.readthedocs.io/) - Simplified logging
{% endif -%}

## Support

- 📚 [Documentation](docs/)
- 🐛 [Issue Tracker](../../issues)
- 💬 [Discussions](../../discussions)

---

**{{ cookiecutter.project_name }}** - Built for professional CLI development with kens-pythontools foundation.