Рецепты

Каждый рецепт — какая интеграция нужна (поля и шаблон карточки, см. Типы полей) и рабочий код. Токен везде читается из SPARKU_TOKEN_<АДРЕС> — см. CLI sparku.

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

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

#!/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).

#!/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, мс).

#!/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 раз в секунду не нужно, достаточно одного вызова с моментом окончания:

# отсчёт 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).

#!/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).

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

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

#!/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 и раздел «Для ИИ-агентов» — Вопросы человеку.

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

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

#!/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

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