# Quick Guide: Publishing to TestPyPI

This is a quick reference for publishing TealFlowMCP to TestPyPI for testing.

## Prerequisites

1. **TestPyPI Account**: https://test.pypi.org/account/register/
2. **API Token**: https://test.pypi.org/manage/account/token/
   - Create with scope: "Entire account"
   - Save the token securely (starts with `pypi-`)

## Step-by-Step Publishing

### 1. Clean Previous Builds

```bash
rm -rf dist/ build/ *.egg-info/
```

### 2. Build the Package

```bash
uv build
```

**Expected output:**
```
dist/
├── tealflow_mcp-0.1.0-py3-none-any.whl
└── tealflow_mcp-0.1.0.tar.gz
```

### 3. Verify Package Contents

```bash
# Check that wheel was created
ls -lh dist/

# Verify wheel contents include knowledge_base
uv run python -m zipfile -l dist/tealflow_mcp-0.1.0-py3-none-any.whl | grep knowledge_base

# Run twine check
uv run twine check dist/*
```

**Expected**: `PASSED` for all checks

### 4. Upload to TestPyPI

```bash
uv run twine upload --repository testpypi dist/*
```

**You will be prompted:**
```
Enter your username: __token__
Enter your password: [paste your TestPyPI token here]
```

**Important:**
- Username is literally `__token__` (with double underscores)
- Password is your full API token (starts with `pypi-`)
- The token will not be visible when you paste it (this is normal)

### 5. Verify Upload

Visit: https://test.pypi.org/project/tealflow-mcp/

Check that:
- Version number is correct
- Description displays properly
- README renders correctly
- All metadata is accurate

### 6. Test Installation

```bash
# Create a clean virtual environment
python -m venv test_env
source test_env/bin/activate  # On Windows: test_env\Scripts\activate

# Install from TestPyPI (dependencies from real PyPI)
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ tealflow-mcp

# Test the installation
tealflow-mcp --version
python -c "import tealflow_mcp; print(tealflow_mcp.__version__)"

# Cleanup
deactivate
rm -rf test_env
```

## Common Issues

### Issue: "Invalid credentials"
- **Solution**: Make sure username is `__token__` (not your username)
- Check that you're using the TestPyPI token (not PyPI token)

### Issue: "File already exists"
- **Solution**: TestPyPI doesn't allow re-uploading the same version
- Increment version in `pyproject.toml` and `tealflow_mcp/__init__.py`
- Rebuild and upload again

### Issue: "Package not found" when installing
- **Solution**: Make sure to use both `--index-url` and `--extra-index-url`
- Wait a few minutes after upload for TestPyPI to index the package

### Issue: Dependencies not installing
- **Solution**: Use `--extra-index-url https://pypi.org/simple/` to fetch dependencies from real PyPI

## Security Notes

✅ **SECURE**: Entering token manually when prompted
❌ **NOT SECURE**: Storing token in `.pypirc` file

This guide uses the secure manual entry method - your token is never written to disk.

## After Testing

Once you've verified the package works correctly on TestPyPI, you can publish to production PyPI following the same process but using:
- Production PyPI token from https://pypi.org/manage/account/token/
- Command: `twine upload dist/*` (no `--repository` flag needed)

## Quick Commands Summary

```bash
# 1. Clean and build
rm -rf dist/ build/ *.egg-info/ && uv build

# 2. Verify
uv run twine check dist/*

# 3. Upload (will prompt for credentials)
uv run twine upload --repository testpypi dist/*

# 4. Test install
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ tealflow-mcp
```
