# Ticket 0002: `dispatch-workflow.sh`

**Vaihe:** 2/12
**Status:** done
**Feature branch:** `feature/0002-dispatch-workflow-sh`
**TDD required:** Yes
**Feature file required:** Yes

**Required context:**
- `docs/test-plan/tdd-guide.md`
- `tests/features/0002-dispatch-workflow.feature`
- Skills: `tdd`, `implementation`, `clean-code`, `bash-script`

---

## TDD — Red-Green-Refactor

### Red
Kirjoita `tests/dispatch-workflow.bats` mock-Gitea API:a vasten:
- Dispatch → API palauttaa 201
- Poll: API palauttaa `running` 3 kertaa, sitten `completed` + `success` → exit 0
- Poll: API palauttaa `completed` + `failure` → exit 1
- Timeout: ylittää `timeout_minutes` → exit 124
- Virheellinen target_repo → exit 1

```bash
bats tests/dispatch-workflow.bats
# FAIL
```

### Green
`scripts/dispatch-workflow.sh` — dispatch + poll-silmukka 10s välein.

```bash
bats tests/dispatch-workflow.bats
# PASS
```

### Refactor
Poista duplikaatio, tarkista edge caset. Testit vihreänä.

## DoD
- [ ] Cucumber: `@ticket-0002 and @mock` → kaikki skenaariot GREEN
- [ ] `tests/dispatch-workflow.bats` — kaikki testit läpi
- [ ] Dispatch, poll, ja timeout toimivat mock-API:a vasten
- [ ] Exit-koodit: 0 (success), 1 (failure), 124 (timeout)

---

## Toiminto

Dispatchaa workflow toisessa repossa ja pollaa sen valmistumista synkronisesti. Vastaa Jenkinsin `buildJob()`-semantiikkaa — kutsuja jää odottamaan kunnes dispatchattu workflow on valmis.

## Rajapinta

```bash
dispatch-workflow.sh <target_repo> <workflow_file> <ref> <inputs_json> [timeout_minutes]
```

| Parametri | Pakollinen | Kuvaus |
|-----------|------------|--------|
| `target_repo` | Kyllä | `owner/repo` |
| `workflow_file` | Kyllä | Workflow-tiedosto (esim. `test.yml`) |
| `ref` | Kyllä | Branch |
| `inputs_json` | Kyllä | JSON-objekti input-parametreina |
| `timeout_minutes` | Ei | Oletus: 360 |

## API-kutsut

1. **Dispatch:** `POST /api/v1/repos/{target_repo}/actions/workflows/{workflow_file}/dispatches`
2. **Etsi run:** `GET /api/v1/repos/{target_repo}/actions/runs?status=running`
3. **Poll:** `GET /api/v1/repos/{target_repo}/actions/runs/{run_id}` (10s välein)
4. **Lopetus:** `conclusion == "success"` → exit 0, muuten exit 1
5. **Timeout:** `> timeout_minutes` → exit 124

## Esimerkkikutsu

```bash
dispatch-workflow.sh "tests/integration" "test.yml" "main" \
  '{"version":"1.2.3","tags":"@smoke","root_commit":"abc123","root_repo":"services/temperature-store"}'
```

## Verifiointi

Mock-Gitea API, jossa:
- `POST dispatches` → palauttaa 201
- `GET runs` → palauttaa `status: running` 3 kertaa, sitten `status: completed, conclusion: success`

Skripti pollaa ja palauttaa exit 0.

## Viitteet

- `docs/shared-scripts.md` — Rajapinnan määrittely
- `docs/design-rationale.md` — Periaate 4: Deterministinen testigraafi
- `docs/architecture.md` — Tietovuo 4: Test flow -ketjutus