# Рецепты

> Готовые примеры — прогресс деплоя, сборка Xcode, мониторинг сервера, таймер, очередь задач, подтверждение агента.

Каждый рецепт — какая интеграция нужна (поля и шаблон карточки, см.
[Типы полей](/docs/api/ru/fields.md)) и рабочий код. Токен везде читается из
`SPARKU_TOKEN_<АДРЕС>` — см. [CLI sparku](/docs/api/ru/cli.md#токен).

## 1. Прогресс деплоя в CI с вспышкой при ошибке

**Интеграция:** `deploy`, шаблон карточки «Прогресс». Поля: `progress`
(`progress`), `stage` (`state`: `running`/`done`/`failed`), `title` (`text`).

```bash
#!/bin/bash
# deploy.sh — запускается в CI
set -euo pipefail

sparku push deploy title="api · prod" stage=running progress=0

total_steps=5
for step in $(seq 1 $total_steps); do
  ./run-step.sh "$step" || {
    sparku push deploy stage=failed
    sparku notify deploy "Деплой упал на шаге $step" --state failed --color red
    exit 1
  }
  sparku push deploy progress="$(( step * 100 / total_steps ))%"
done

sparku push deploy stage=done progress=100%
sparku notify deploy "Деплой готов" --state done
```

## 2. Сборка Xcode / `swift build`

**Интеграция:** `build`, шаблон «Статус». Поля: `phase` (`state`:
`building`/`testing`/`passed`/`failed`), `title` (`text`).

```bash
#!/bin/bash
# build.sh
sparku push build title="SparkU" phase=building

if ! xcodebuild -scheme SparkU -destination 'platform=macOS' build 2>build.log; then
  sparku push build phase=failed
  sparku notify build "Сборка упала" --state failed --color red
  exit 1
fi

sparku push build phase=testing
if ! xcodebuild -scheme SparkU -destination 'platform=macOS' test 2>test.log; then
  sparku push build phase=failed
  sparku notify build "Тесты упали" --state failed --color red
  exit 1
fi

sparku push build phase=passed
sparku notify build "Сборка и тесты зелёные" --state passed
```

## 3. Мониторинг сервера на Python раз в N секунд

**Интеграция:** `server`, шаблон «Шкалы». Поля: `cpu` (`number`, 0–100, `%`),
`memory` (`number`, 0–100, `%`), `latency` (`number`, мс).

```python
#!/usr/bin/env python3
import http.client, json, os, socket, time

TOKEN = os.environ["SPARKU_TOKEN_SERVER"]

class SparkU(http.client.HTTPConnection):
    def __init__(self):
        super().__init__("sparku")
    def connect(self):
        self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
        self.sock.connect(os.path.expanduser("~/.sparku/run/api.sock"))

def push(fields):
    api = SparkU()
    api.request("POST", "/v1/integrations/server/fields", json.dumps(fields), {
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    })
    response = api.getresponse()
    response.read()

def read_metrics():
    # замените на реальный сбор метрик (psutil, /proc, ssh на прод и т. д.)
    import random
    return {"cpu": random.uniform(10, 90), "memory": random.uniform(30, 80), "latency": random.uniform(40, 300)}

while True:
    push(read_metrics())
    time.sleep(5)
```

Запуск в фоне: `nohup python3 monitor.py &` или через `launchd`/systemd — сокет
переживает перезапуск скрипта, следующий `push` просто восстановит значения.

## 4. Таймер / обратный отсчёт одним push

**Интеграция:** `timer`, шаблон «Таймер». Поле: `until` (`time`).

Таймер тикает внутри SparkU — повторять `push` раз в секунду не нужно, достаточно
одного вызова с моментом окончания:

```bash
# отсчёт 25 минут (Pomodoro)
sparku push timer until=+25m

# конкретный момент в ISO 8601
sparku push timer until=2026-09-28T15:00:00Z
```

Отменить отсчёт — `sparku end timer`.

## 5. Очередь задач (список)

**Интеграция:** `queue`, шаблон «Список». Поле: `tasks` (`list`).

```bash
#!/bin/bash
# queue.sh — обновляет список задач сборки

tasks_json() {
  cat <<'JSON'
[
  {"title": "Сборка iOS", "subtitle": "шаг 3 из 5", "value": "60%", "state": "running"},
  {"title": "Тесты API", "subtitle": "412 из 420", "value": "98%", "state": "done"},
  {"title": "Миграция БД", "subtitle": "staging", "state": "failed"},
  {"title": "Деплой лендинга", "subtitle": "в очереди"}
]
JSON
}

sparku push queue "tasks:=$(tasks_json)"
```

`tasks:=...` — двоеточие перед `=` в `sparku push` говорит CLI разобрать значение
как JSON, а не как строку (см. [CLI sparku](/docs/api/ru/cli.md)).

## 6. Агент спрашивает перед опасной командой

**Интеграция:** `agent`, диалоги включены в настройках, карточка не обязательна.

```bash
#!/bin/bash
# cleanup-branch.sh — вызывается ИИ-агентом (Claude Code, Codex и т. п.) из shell
set -euo pipefail

if sparku ask agent "Удалить ветку feature/old и закрыть PR #42?" \
     --accept Удалить --decline "Не трогать" --timeout 5m; then
  git push origin --delete feature/old
  gh pr close 42
else
  echo "отменено человеком" >&2
  exit 1
fi
```

Подробнее про коды выхода `ask` и раздел «Для ИИ-агентов» — [Вопросы человеку](/docs/api/ru/dialogs.md).

## 7. Обёртка `if sparku ask …` для любой команды

**Интеграция:** та же `agent`, что и в рецепте 6, — одна интеграция для всех
подтверждений в терминале.

```bash
#!/bin/bash
# confirm.sh — обёртка: спрашивает и выполняет любую команду
# использование: ./confirm.sh "Удалить node_modules?" rm -rf node_modules

question=$1; shift

if sparku ask agent "$question"; then
  "$@"
else
  echo "отменено" >&2
  exit 1
fi
```

```bash
./confirm.sh "Перезапустить прод-сервер?" ssh prod 'sudo systemctl restart api'
```