Metadata-Version: 2.4
Name: puba
Version: 0.1.0
Summary: Safe Python package release CLI
Author: Griffin McManus
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: keyring>=23.0

# puba

**Safe Python Package Release CLI**

A minimal, dependency-free CLI to safely check, build, and publish Python packages without risking secrets.

---

## Features

- Ensure git working directory is clean before releasing  
- Scan for secrets in the repo before publishing  
- Run tests automatically (via `pytest` if installed)  
- Build the package (`python -m build`)  
- Safely upload to PyPI or TestPyPI  
- Store your PyPI token securely in **macOS Keychain**, **Windows Credential Manager**, or Linux keyring  
- Dry run mode for testing builds without uploading  
- `checks` command to validate the repo without publishing  
- No external dependencies required for CLI parsing  

---

## Usage

### 1️⃣ Store PyPI token securely

```bash
puba auth
```

- On macOS → stored in Keychain  
- On Windows → stored in Credential Manager  
- On Linux → stored in system keyring if available  
- Fallback → prompts you for input each time  

---

### 2️⃣ Install optional dev tools (for tests, builds, and publishing)

If you want to run tests, build packages, or publish safely, install optional dependencies:

```bash
# zsh users: quote the extras to avoid glob errors
pip install ".[dev]"
```

- Installs: `pytest`, `build`, `twine`  
- You can also install subsets:
  ```bash
  pip install ".[test]"   # only pytest
  pip install ".[build]"  # only build and twine
  ```

---

### 3️⃣ Run safety checks only

```bash
puba checks
```

Checks performed:

- Git working directory is clean  
- Secret scan (requires `gitleaks`)  
- Runs tests (`pytest`)  
- Builds the package  

> No upload occurs in this step.  

---

### 4️⃣ Publish package

```bash
puba publish
```

**Options:**

- `--test` → Upload to **TestPyPI** instead of PyPI  
- `--dry` → Run all checks and build without uploading  

**Examples:**

```bash
# Standard release
puba publish

# Upload to TestPyPI
puba publish --test

# Dry run (check + build only)
puba publish --dry
```

---

### 5️⃣ Help

```bash
puba help
```

Displays usage instructions and available commands.

---

## Example Workflow

```
          +----------------+
          | puba auth |
          +----------------+
                   |
                   v
          +------------------+
          | puba checks |
          +------------------+
                   |
                   v
          +-------------------+
          | puba publish |
          +-------------------+
```

1. Store token (one-time)  
2. Check repo before release  
3. Publish safely  

Optional: test PyPI or dry-run:  
```bash
puba publish --test
puba publish --dry
```

---

## Notes

- **Secrets are never committed** — always stored in system keyring or provided via environment variable `PYPI_TOKEN`.  
- Works on **macOS, Windows, and Linux**.  
- Can be integrated into **CI/CD pipelines** with environment variables:

```bash
export PYPI_TOKEN=pypi-xxxxxxxxxxxx
puba publish --dry
```

---

## Recommended Tools (Optional)

- `pytest` → for running tests automatically  
- `gitleaks` → for scanning secrets before publishing  
- `build` → Python build system (`pip install build`)  
- `twine` → for uploading packages (`pip install twine`)

