# validate compose-e2e — Runbook

Cross-repo e2e validation using wise-validator + sand-boxer.

## Prerequisites

**Workstation:**

- `sandboxer` on PATH (`cd ~/sand-boxer && make install`)
- `validate` on PATH (`cd ~/wise-validator && make install`)
- `ssh` available (BatchMode; respects `~/.ssh/config`)
- State Hub on `:8000` for result reporting (optional)

**Sandbox host (CoulombCore / sandboxer01):**

- SSH access
- `podman-compose` or `docker compose`
- Sufficient disk for images

## First run

```bash
export SANDBOXER_HOST=92.205.130.254   # or coulombcore alias
export SANDBOXER_COMPOSE_CMD=podman-compose

validate run ~/activity-core
```

Output: sandbox create → health wait → test → destroy. Exit 0 = pass, 1 = fail.

## Options

```bash
# Keep sandbox for debugging
validate run ~/activity-core --keep

# Attach State Hub workstream
validate run ~/activity-core --workstream-id <uuid>

# Skip State Hub reporting
validate run ~/activity-core --no-report

# Override host
validate run ~/activity-core --host 92.205.130.254
```

## Adding a repo contract

Create `<repo>/e2e/e2e.yml`:

```yaml
name: my-repo
compose_file: docker-compose.dev.yml
health_checks:
  - name: api
    url: http://localhost:8080
    timeout: 120
test_command: uv run python -m pytest e2e/tests/ -v
timeout: 300
cleanup: always
```

Run: `validate run ~/my-repo`

## Self-smoke (sand-boxer repo)

```bash
validate run ~/sand-boxer
```

Uses `e2e/docker-compose.smoke.yml` (nginx on `127.0.0.1:18080`).

## Troubleshooting

**`sandboxer not found`:** Install sand-boxer CLI.

**Health check timeout:** SSH to host and `curl` the URL from inside the sandbox dir.

**Stale sandboxes:** `sandboxer inspect stale` / `sandboxer reap-stale --apply`

## Migration from the-custodian

| Legacy | Replacement |
|--------|-------------|
| `make e2e REPO=` | Still works — delegates to `validate run` (SAND-WP-0004) |
| `python -m e2e_framework` | Deprecated wrapper → `validate run` |
| Embedded SSH provision | `sandboxer create` (sand-boxer) |

## activity-core scheduling

Instructions and cron jobs should invoke:

```bash
validate run /path/to/repo --host "${SANDBOXER_HOST}" --no-report
```

or, from a the-custodian checkout:

```bash
make e2e REPO=<slug>
```

Set `SANDBOXER_HOST` and `SANDBOXER_COMPOSE_CMD` in the instruction environment.