Metadata-Version: 2.4
Name: ppbuild
Version: 1.0.1
Summary: A declarative, language-agnostic build system and utility manager
Home-page: https://github.com/JoshCap20/pp
Author: Josh Caponigro
Project-URL: Bug Tracker, https://github.com/JoshCap20/pp/issues
Project-URL: Documentation, https://github.com/JoshCap20/pp/blob/main/TEMPLATE.md
Project-URL: Source Code, https://github.com/JoshCap20/pp
Keywords: build-system,developer-tools,automation,cli,yaml,cross-platform
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Systems Administration
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: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=5.1
Requires-Dist: python-dotenv>=0.19.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# pp
[![Tests](https://github.com/JoshCap20/pp/actions/workflows/test.yml/badge.svg)](https://github.com/JoshCap20/pp/actions/workflows/test.yml)
[![CI/CD](https://github.com/JoshCap20/pp/actions/workflows/publish.yml/badge.svg)](https://github.com/JoshCap20/pp/actions/workflows/publish.yml)

A declarative, language-agnostic build system and utility manager.

`pp` provides a unified interface for building, testing, and running applications across different programming languages and environments. By defining configurations in a declarative `pp.yaml` file, you eliminate the need to remember language-specific toolchains and command variations. The system works equally well for managing complex build processes, running simple utility scripts, and orchestrating development workflows.

Whether you're working on a Python web application, a Rust CLI tool, or a Node.js frontend, `pp` abstracts away the underlying toolchain complexity while providing powerful parameterization and environment management capabilities.

## Install

### Quick Install

```bash
pip install ppbuild
```

### macOS Users (externally-managed-environment error)

If you get an "externally-managed-environment" error on macOS, use one of these methods:

**Option 1: Using pipx (Recommended)**
```bash
# Install pipx if you don't have it
brew install pipx

# Install pp using pipx
pipx install ppbuild
```

**Option 2: Using virtual environment**
```bash
# Create and activate virtual environment
python3 -m venv ~/.pp-env
source ~/.pp-env/bin/activate

# Install pp
pip install ppbuild

# Add to your shell profile (.zshrc, .bash_profile, etc.)
echo 'alias pp="~/.pp-env/bin/pp"' >> ~/.zshrc
source ~/.zshrc
```

### Verify Installation

```bash
pp --help
```

### Development Installation

1. Clone the repository
```bash
git clone https://github.com/JoshCap20/pp.git
cd pp
```

2. Install in development mode
```bash
pip install -e .
```

3. Install development dependencies
```bash
pip install pytest pytest-cov black isort flake8 mypy
```

4. Run tests
```bash
pytest
```

The setup.py file creates a console script entry point, so after installation you can run `pp` from anywhere in your terminal.

## Configuration

Create a `pp.yaml` configuration file that defines the commands for your applications. The beauty is that you can have:

- A global config at `~/.pp/pp.yaml` for system-wide tools
- Project-specific configs that override the global one
- Environment-specific settings via `.env` files

See [TEMPLATE.md](TEMPLATE.md) for examples of creating your definition file.

## Usage

```bash
pp <application name> <action> [command]
```

**Examples:**
```bash
pp myapp build       # Build your application
pp myapp test        # Run tests
pp myapp run dev     # Start development server
pp backend deploy    # Deploy backend services
```

**Advanced Examples with Parameters:**
```bash
pp ollama run --model deepseek-r1 --temperature 0.8    # Run AI model with specific settings
pp web_server run --port 3000 --debug                  # Start server on custom port with debug
pp database backup --output prod-backup.sql --compress # Create compressed database backup
pp docker scale --service web --replicas 3             # Scale web service to 3 instances
```

The configuration is overridden by the current directory, so you can drop a `pp.yaml` in any project and immediately have access to all your build, test, run, lint, docker, and deployment commands through the same simple interface.

## Features

- **Simple Commands**: Define basic commands that just work (`pp myapp build`)
- **Parameterized Commands**: Add typed parameters with validation, defaults, and help text
- **Environment Management**: Automatic virtual environment activation (for python only) and environment variable injection
- **Directory Context**: Commands run in the right directory with the right environment
- **Type Safety**: Parameters are validated (strings, integers, floats, booleans) with constraints
- **Flexible Configuration**: Global configs, project-specific overrides, and environment-specific settings

## How it Works

1. `pp` looks for a `pp.yaml` in your current directory, then falls back to `~/.pp/pp.yaml`
2. It loads your application definitions and creates CLI subcommands automatically
3. When you run a command, it executes the underlying tool (npm, cargo, docker, etc.) with the right arguments
4. Parameters are validated and interpolated into your commands with proper escaping
5. You get consistent logging and error handling across all your projects

This means you can finally stop context-switching between different build tools and just focus on building cool stuff.

## How I use it

I define global tools for common CLI operations in `~/.pp/pp.yaml` and then define project-specific tools in `pp.yaml` for each project. This way, I can have a single `pp` command that works for all my projects.

## Todo

- [ ] Download github repos and setup commands automatically
- [ ] Chain existing commands
- [ ] Easy MCP setup integration
- [ ] pp utility commands (--init, etc)
