# Publishing mothership-bot to PyPI

This guide explains how to publish the mothership-bot package to PyPI.

## ✅ Pre-Publishing Checklist

- [x] Package metadata complete in pyproject.toml
- [x] README.md included
- [x] LICENSE file included
- [x] Package builds successfully (`uv build`)
- [x] Package installs and imports work
- [x] Version number set (currently 1.0.0)

## PyPI Account Setup

### 1. Create PyPI Accounts

You'll need accounts on both:
- **TestPyPI** (for testing): https://test.pypi.org/account/register/
- **PyPI** (production): https://pypi.org/account/register/

### 2. Create API Tokens

For each account:

1. Go to Account Settings → API tokens
2. Click "Add API token"
3. For TestPyPI: Name it "mothership-bot-test"
4. For PyPI: Name it "mothership-bot"
5. Set scope to "Entire account" or specific to "mothership-bot" project
6. Copy the token (starts with `pypi-`)

### 3. Configure UV with API Tokens

```bash
# For TestPyPI
export UV_PUBLISH_TOKEN="pypi-your-test-token-here"

# For PyPI
export UV_PUBLISH_TOKEN="pypi-your-production-token-here"
```

Or use keyring (recommended for security):
```bash
pip install keyring
keyring set https://test.pypi.org/legacy/ __token__
# Enter your TestPyPI token when prompted

keyring set https://upload.pypi.org/legacy/ __token__
# Enter your PyPI token when prompted
```

## Publishing Process

### Step 1: Test on TestPyPI (Recommended)

```bash
cd /home/user/mothership/packages/python

# Clean previous builds
rm -rf dist/

# Build fresh package
uv build

# Publish to TestPyPI
uv publish --publish-url https://test.pypi.org/legacy/
```

### Step 2: Verify TestPyPI Installation

```bash
# Create test environment
python -m venv test-env
source test-env/bin/activate

# Install from TestPyPI
pip install --index-url https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple/ \
  mothership-bot

# Test imports
python -c "from mothership import BotFactory, create_logger; print('✅ Works!')"

# Cleanup
deactivate
rm -rf test-env
```

### Step 3: Publish to PyPI (Production)

Once TestPyPI installation works:

```bash
cd /home/user/mothership/packages/python

# Publish to PyPI
uv publish

# Or explicitly specify PyPI URL
uv publish --publish-url https://upload.pypi.org/legacy/
```

### Step 4: Verify PyPI Installation

```bash
# Create test environment
python -m venv verify-env
source verify-env/bin/activate

# Install from PyPI
pip install mothership-bot

# Test it
python -c "from mothership import BotFactory, create_logger; print('✅ Published!')"

# Cleanup
deactivate
rm -rf verify-env
```

## Alternative: Using twine

If you prefer using twine:

```bash
# Install twine
pip install twine

# Check package
twine check dist/*

# Upload to TestPyPI
twine upload --repository testpypi dist/*

# Upload to PyPI
twine upload dist/*
```

## Version Management

When publishing updates:

1. Update version in `pyproject.toml`:
   ```toml
   version = "1.0.1"  # or 1.1.0, 2.0.0, etc.
   ```

2. Rebuild and republish:
   ```bash
   rm -rf dist/
   uv build
   uv publish
   ```

## Quick Command Reference

```bash
# Build package
uv build

# Publish to TestPyPI
export UV_PUBLISH_TOKEN="pypi-test-token"
uv publish --publish-url https://test.pypi.org/legacy/

# Publish to PyPI
export UV_PUBLISH_TOKEN="pypi-prod-token"
uv publish

# Check package without uploading
twine check dist/*

# View package on PyPI
# https://pypi.org/project/mothership-bot/
```

## Troubleshooting

### Error: "403 Forbidden"
- Check your API token is correct
- Ensure token has correct scope
- Verify you're authorized for the package name

### Error: "400 Bad Request - File already exists"
- You cannot re-upload the same version
- Increment version number in pyproject.toml
- Rebuild the package

### Error: Package name already taken
- Choose a different name in pyproject.toml
- Check https://pypi.org/search/ for availability

## Post-Publishing

After successful publish:

1. ✅ Verify package page: https://pypi.org/project/mothership-bot/
2. ✅ Test installation: `pip install mothership-bot`
3. ✅ Update documentation with install instructions
4. ✅ Create GitHub release matching version
5. ✅ Announce on social media/channels

## Security Best Practices

- ✅ Use API tokens (not passwords)
- ✅ Use project-scoped tokens when possible
- ✅ Store tokens in keyring or environment variables
- ✅ Never commit tokens to git
- ✅ Rotate tokens periodically
- ✅ Revoke tokens when no longer needed
