stack/scripts/coordinator/README.md

# Coordinator Scripts

Utility scripts for setting up and managing the autonomous coordinator system in Mosaic Stack.

## Overview

The coordinator system automates issue assignment, tracking, and orchestration across AI agents. These scripts help with setup, configuration, and testing.

## Scripts

### Python Modules

#### issue_estimator.py

Formula-based context estimator for predicting token usage before issue assignment.

**Prerequisites:**

- Python 3.8+
- Virtual environment with dependencies (see Installation below)

**Usage:**

```bash
# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run examples
python issue_estimator.py

# Run tests
pytest test_issue_estimator.py -v

# Run with coverage
pytest test_issue_estimator.py --cov=issue_estimator --cov=models --cov-report=term-missing
```

**Python API:**

```python
from issue_estimator import estimate_issue

# Quick estimation
result = estimate_issue(
    files=2,
    complexity="medium",
    tests="medium",
    docs="light"
)

print(f"Total estimate: {result.total_estimate:,} tokens")
print(f"Recommended agent: {result.recommended_agent}")
```

**Documentation:** See [ESTIMATOR.md](ESTIMATOR.md) for complete API reference and examples.

### Bash Scripts

#### create-gitea-bot.sh

Creates the `mosaic` bot user in Gitea for coordinator automation.

**Prerequisites:**

- Gitea admin access
- Admin API token with sufficient permissions

**Usage:**

```bash
# Set admin token and run
export ADMIN_TOKEN="your-gitea-admin-token"
./scripts/coordinator/create-gitea-bot.sh

# Or specify variables
ADMIN_TOKEN="token" GITEA_URL="https://gitea.example.com" \
  ./scripts/coordinator/create-gitea-bot.sh
```

**What it does:**

1. Creates `mosaic` bot user account
2. Sets up email: `mosaic@mosaicstack.dev`
3. Adds bot to `mosaic/stack` repository as collaborator
4. Generates API token for coordinator use
5. Tests bot authentication
6. Displays credentials for secure storage

**Output:**
The script provides the API token and password that must be stored in your secrets vault or .env file.

### test-gitea-bot.sh

Tests bot functionality and verifies all necessary permissions.

**Prerequisites:**

- Bot user created (run `create-gitea-bot.sh` first)
- `GITEA_BOT_TOKEN` in environment or .env file

**Usage:**

```bash
# Run tests with token from .env
./scripts/coordinator/test-gitea-bot.sh

# Or specify token explicitly
export GITEA_BOT_TOKEN="your-bot-token"
./scripts/coordinator/test-gitea-bot.sh

# Test against specific issue
export TEST_ISSUE="156"
./scripts/coordinator/test-gitea-bot.sh
```

**Tests performed:**

1. Bot authentication
2. Repository access
3. Issue listing
4. Issue reading
5. Issue assignment
6. Comment posting
7. Label management
8. Repository permissions

**Output:**
Success/failure for each test with detailed error messages.

## Installation

### Python Environment

For the context estimator and Python-based coordinator components:

```bash
# Navigate to coordinator directory
cd scripts/coordinator

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Verify installation
pytest test_issue_estimator.py -v
```

### Bash Scripts

No installation needed for bash scripts. Just ensure they're executable:

```bash
chmod +x scripts/coordinator/*.sh
```

## Configuration

### Environment Variables

All scripts support these environment variables:

```bash
# Gitea connection
GITEA_URL                # Default: https://git.mosaicstack.dev
ADMIN_TOKEN              # Gitea admin token (required for create-gitea-bot.sh)

# Bot credentials
GITEA_BOT_TOKEN          # Bot API token (required for test-gitea-bot.sh)
GITEA_BOT_USERNAME       # Default: mosaic
GITEA_BOT_PASSWORD       # For reference only

# Repository
GITEA_REPO_OWNER         # Default: mosaic
GITEA_REPO_NAME          # Default: stack

# Testing
TEST_ISSUE               # Issue number for testing (default: 156)
```

### .env File

Create or update `.env` file in project root:

```bash
# Gitea Configuration
GITEA_URL=https://git.mosaicstack.dev
GITEA_BOT_USERNAME=mosaic
GITEA_BOT_TOKEN=your-bot-token-here
GITEA_BOT_PASSWORD=your-bot-password-here
GITEA_REPO_OWNER=mosaic
GITEA_REPO_NAME=stack
```

**Security:** Never commit .env to version control. Add `.env` to `.gitignore`.

## Workflow

### Initial Setup

```bash
# 1. Create bot user (requires admin token)
export ADMIN_TOKEN="your-admin-gitea-token"
./scripts/coordinator/create-gitea-bot.sh

# Output will show:
# - Bot username (mosaic)
# - Bot password (save securely)
# - API token (save securely)
# - Instructions for next steps

# 2. Store credentials securely
# - Add GITEA_BOT_TOKEN to .env (don't commit)
# - Add GITEA_BOT_TOKEN to your secrets vault
# - Add GITEA_BOT_PASSWORD to your secrets vault

# 3. Update .env.example (no secrets)
# - Add template entries with placeholder values

# 4. Test bot functionality
./scripts/coordinator/test-gitea-bot.sh
```

### Daily Use

```bash
# Run tests to verify bot is working
./scripts/coordinator/test-gitea-bot.sh

# If tests fail:
# - Check GITEA_BOT_TOKEN is valid
# - Check token hasn't expired
# - Verify bot user still exists in Gitea
# - If needed, regenerate token (see docs)
```

### Token Rotation

When rotating the bot API token:

```bash
# 1. Generate new token in Gitea UI
#    Settings → Applications → Create new token

# 2. Update .env
export GITEA_BOT_TOKEN="new-token"

# 3. Test new token
./scripts/coordinator/test-gitea-bot.sh

# 4. Update secrets vault
# 5. Delete old token in Gitea UI
```

## Troubleshooting

### "ADMIN_TOKEN environment variable not set"

The `create-gitea-bot.sh` script requires a Gitea admin token.

**Solution:**

1. Log in to Gitea as admin
2. Go to Settings → Access Tokens
3. Create new token with `api` scope
4. Export and run: `ADMIN_TOKEN="token" ./scripts/coordinator/create-gitea-bot.sh`

### "Cannot connect to Gitea"

Script can't reach the Gitea instance.

**Solution:**

```bash
# Verify GITEA_URL is correct
echo $GITEA_URL

# Check connectivity
curl -s https://git.mosaicstack.dev/api/v1/version | jq .

# If still failing, check:
# - Network connectivity to Gitea server
# - Firewall rules
# - VPN/proxy configuration
```

### "Authentication failed"

Bot API token is invalid or expired.

**Solution:**

1. Check token in .env is correct (no extra spaces)
2. Verify token hasn't expired (90 day default)
3. Regenerate token if needed:
   - Log in as `mosaic` user
   - Settings → Applications → Delete old token
   - Create new token
   - Update .env and secrets vault

### "Bot user already exists"

The bot user was already created.

**Solution:**

- Continue setup with existing user
- Verify credentials are correct
- Run tests to confirm functionality

### "Permission denied" on operations

Bot doesn't have required permissions.

**Solution:**

1. Verify bot is added as repository collaborator
2. Check permission level (should be "push" or "admin")
3. Re-add if needed via API:

```bash
curl -X PUT \
  -H "Authorization: token $ADMIN_TOKEN" \
  "https://git.mosaicstack.dev/api/v1/repos/mosaic/stack/collaborators/mosaic" \
  -d '{"permission":"push"}'
```

## Documentation

For complete documentation on the coordinator bot:

- [Gitea Coordinator Setup Guide](../../docs/1-getting-started/3-configuration/4-gitea-coordinator.md)
- [Issue #156 - Create coordinator bot user](https://git.mosaicstack.dev/mosaic/stack/issues/156)
- [Coordinator Architecture](../../docs/3-architecture/non-ai-coordinator-comprehensive.md)

## Files

| File                      | Purpose                              |
| ------------------------- | ------------------------------------ |
| `issue_estimator.py`      | Context estimator implementation     |
| `models.py`               | Data models and enums for estimator  |
| `test_issue_estimator.py` | Test suite (35 tests, 100% coverage) |
| `ESTIMATOR.md`            | Complete estimator documentation     |
| `requirements.txt`        | Python dependencies                  |
| `.coveragerc`             | Coverage configuration               |
| `create-gitea-bot.sh`     | Bot user creation script             |
| `test-gitea-bot.sh`       | Bot functionality tests              |
| `README.md`               | This file                            |

## Related Issues

- #154 - Implement context estimator ✅ **COMPLETED**
- #156 - Create coordinator bot user in Gitea ✅ **COMPLETED**
- #157 - Configure coordinator webhook in Gitea
- #158 - Implement coordinator task assignment engine
- #140 - Coordinator integration architecture

## Support

For issues or questions:

1. Check the troubleshooting section above
2. Review the full documentation
3. Open an issue in the repository