# Woodpecker CI Tool Suite

Interact with Woodpecker CI pipelines (list builds, check status, trigger builds).

## Prerequisites

- `jq` and `curl` installed
- Woodpecker credentials in `~/.config/mosaic/credentials.json`

## Setup

A Woodpecker API token is required. To configure:

1. Go to Woodpecker CI → User Settings → API
2. Generate a personal token
3. Add to `credentials.json`:

```json
{
  "woodpecker": {
    "url": "https://ci.mosaicstack.dev",
    "token": "YOUR_TOKEN_HERE"
  }
}
```

## Scripts

| Script                     | Purpose                                                        |
| -------------------------- | -------------------------------------------------------------- |
| `pipeline-list.sh`         | List recent pipelines for a repo                               |
| `pipeline-status.sh`       | Get status of a specific or latest pipeline                    |
| `pipeline-trigger.sh`      | Trigger a new pipeline build                                   |
| `ci-wait.sh`               | Block until pipeline(s) reach terminal state                   |
| `verify-terminal-green.py` | Verify every JSON/API child step under the bounded CI contract |

## Common Options

- `-r owner/repo` — Repository (auto-detected from git remote if omitted)
- `-f json` — JSON output (default: table)
- `-h` — Show help

## API Reference

- Base URL: `https://ci.mosaicstack.dev`
- API prefix: `/api/`
- Auth: Bearer token in `Authorization` header

## Examples

```bash
# List recent builds
~/.config/mosaic/tools/woodpecker/pipeline-list.sh

# Check latest build status
~/.config/mosaic/tools/woodpecker/pipeline-status.sh

# Trigger a build on a specific branch
~/.config/mosaic/tools/woodpecker/pipeline-trigger.sh -b feature/my-branch

# Block until one or more pipelines finish (event-driven CI wait)
~/.config/mosaic/tools/woodpecker/ci-wait.sh -r usc/uconnect -n 3917 -n 3918

# Verify the full JSON child-step record; do not use the text summary for this gate
PR_HEAD=<full-40-hex-provider-head>
~/.config/mosaic/tools/woodpecker/pipeline-status.sh -r mosaicstack/stack -n 2188 -f json \
  | ~/.config/mosaic/tools/woodpecker/verify-terminal-green.py --expect-commit "$PR_HEAD" -
```
