# Deploy Hook — Agent Operating Guide

Remote deploy trigger for this host. Use the HTTPS base URL below.

## Auth (required for all /deploy and /sites calls)

1. Your client IP must be on the server allowlist.
2. Send the shared secret on every request:

   Authorization: Bearer <ask human / read server config>

   (or header X-Deploy-Token: <ask human / read server config>)

If you get HTTP 403, your IP is not allowlisted — ask a human to add it in config.
If you get HTTP 401, the token is wrong/missing.

## Base URL

https://hook.akali.ondrejsmetak.cz

## Endpoints

### GET /docs
This document (no auth).

### GET /health
Liveness check (no auth). Returns {"ok": true}.

### GET /sites
List deployable site keys (auth required).

### POST /deploy/{site}
Start a deploy for an allowlisted site.
- Path `{site}` must be one of the keys from GET /sites (e.g. szj).
- Body: empty (no JSON required). Do not send shell commands.
- Response 202 JSON:
  {
    "job_id": "...",
    "site": "szj",
    "status": "starting",
    "log_url": "/deploy/szj/jobs/<job_id>/log",
    "status_url": "/deploy/szj/jobs/<job_id>"
  }
- Only one deploy per site at a time. A second start while running returns HTTP 409.

### GET /deploy/{site}/jobs/{job_id}
JSON job status (auth required).

### GET /deploy/{site}/jobs/{job_id}/log
Server-Sent Events stream of the deploy log (auth required).
- Content-Type: text/event-stream
- Events:
  - `data: <log line>` for each line
  - final event: `event: done` then `data: {"exit_code": N, "status": "ok"|"failed"}`
- Keep the connection open until the `done` event.
- Exit code 0 = success.

## Recommended agent flow

1. GET /sites — confirm the site key exists.
2. POST /deploy/{site} — capture job_id and log_url.
3. GET the log_url with Accept: text/event-stream — follow until event: done.
4. If exit_code != 0, report the last log lines to the user.

## Example (curl)

curl -sS -H "Authorization: Bearer $TOKEN" \
  -X POST https://hook.akali.ondrejsmetak.cz/deploy/szj

curl -sS -N -H "Authorization: Bearer $TOKEN" \
  https://hook.akali.ondrejsmetak.cz/deploy/szj/jobs/JOB_ID/log

## Rules for agents

- Never invent site names or script paths. Only use GET /sites.
- Never ask the user to paste the token into chat logs if avoidable; use env/config.
- Do not retry a failed auth in a tight loop.
- Deploys run the fixed host scripts (update.sh); you cannot pass arbitrary commands.