zoryn flow¶

zoryn flow выполняет сценарий (flow) — заданную вами последовательность шагов, которая сводит рутинное обновление пакета к одной команде. Сценарий умеет обновить и собрать пакет, прогнать ваши проверки по ssh или внутри devenv, отправить результат в gyle, а если шаг упал — запустить восстановительный сценарий (вплоть до ИИ-агента, читающего лог сборки) и повторить шаг.

Ни один шаг ничего не спрашивает у пользователя: сценарий рассчитан на запуск из cron, из CI или в терминале, за которым никто не следит.

Использование¶

zoryn flow [NAME] [--continue] [--restart] [--abort] [--dry-run] [-C DIR] [-d] [-v]
zoryn flow run [NAME] [--continue] [--restart] [--abort] [--dry-run] [-C DIR] [-d] [-v]
zoryn flow list [-C DIR]
zoryn flow show NAME [-C DIR]

zoryn flow NAME и zoryn flow run NAME — одно и то же: короткая форма переписывается в run ещё до разбора аргументов. Явная форма zoryn flow run <имя> нужна только для сценария, названного буквально run, list, show или help.

Команду запускают внутри gear-репозитория; zoryn сначала переходит в корень репозитория, поэтому слои конфигурации, .gear/version-up, {pkg} и файл состояния относятся к одному и тому же пакету, из какого бы подкаталога вы ни стартовали.

zoryn flow run¶

Выполняет сценарий. Без NAME сценарий выбирается по ключу [flow] name из .gear/version-up, а если его нет — по default из таблицы [flows] машинной конфигурации; с --continue и без NAME имя берётся из сохранённого состояния.

Опции¶

• NAME — какой сценарий выполнить. Без него имя берётся из [flow] name в .gear/version-up, иначе из [flows] default.
• --continue — продолжить прерванный сценарий с упавшего шага.
• --restart — отбросить сохранённое состояние и выполнить сценарий с первого шага.
• --abort — отбросить сохранённое состояние прерванного сценария.
• --dry-run — напечатать разобранные шаги и выйти, ничего не выполняя.
• -C DIR — перейти в каталог DIR перед выполнением.
• -d, --debug — отладочный вывод (в том числе трассировка порождаемых процессов).
• -v, --verbose — показывать вывод сборки на экране для шагов build, как это делает zoryn build -v (первая сборка внутри шага up всегда пишется только в лог-файл).

--continue, --restart и --abort взаимно исключают друг друга, а --continue несовместим с --dry-run.

zoryn flow                  # выполнить выбранный сценарий
zoryn flow update           # выполнить сценарий с именем 'update'
zoryn flow update --dry-run # только напечатать разобранные шаги
zoryn flow --continue       # продолжить после исправления упавшего шага
zoryn flow --abort          # отбросить сохранённое состояние

zoryn flow list¶

Печатает сценарии, видимые из текущего пакета: имя на строке, под ним — файл конфигурации, в котором сценарий определён. Если одно имя описано в двух слоях, показывается только победившее определение.

$ zoryn flow list
update
  /home/user/.config/zoryn/projects.d/curl.toml
fix-build
  /home/user/.zoryn

zoryn flow show¶

Печатает шаги сценария NAME в том же нумерованном виде, что и --dry-run, а под каждым шагом — его if, on-failure и max-retries, если тот отличается от значения по умолчанию. Значения, которые появятся только после следующих шагов, ещё неизвестны, поэтому строка с {new_version} или {task} печатается как есть.

$ zoryn flow show update
Flow update
  1. up
     on-failure: fix-build
     max-retries: 3
  2. devenv: make smoke
  3. ssh stand1: run-checks {pkg} {new_version}
  4. submit -B sisyphus --run

Где описываются сценарии¶

Сценарии читаются только из машинной конфигурации, из двух слоёв:

1. ~/.config/zoryn/projects.d/<проект>.toml — для конкретного пакета, приоритетнее;
2. ~/.zoryn — общая настройка.

Репозиторий пакета описывать шаги не может. В шагах лежат shell-команды и ssh-хосты, поэтому склонированный репозиторий не должен иметь возможности их подсунуть — максимум, что ему позволено, это выбрать сценарий по имени:

# .gear/version-up
[flow]
name = "kernel-update"

Если выбранного имени нет в вашей собственной конфигурации, запуск завершится ошибкой unknown flow '<имя>', и ничего из репозитория выполнено не будет.

Формат конфигурации¶

Каждый сценарий — это таблица [flows.<имя>] с массивом steps из inline-таблиц. В самой таблице [flows] хранится только ключ default — сценарий, который берётся, когда его никто не выбрал явно.

[flows]
default = "update"

[flows.update]
steps = [
  { run = "up", on-failure = "fix-build", max-retries = 3 },
  { run = "devenv", cmd = "make smoke" },
  { run = "ssh", host = "stand1", cmd = "run-checks {pkg} {new_version}" },
  { run = "submit", branch = "sisyphus", task-run = true },
]

[flows.fix-build]
steps = [ { run = "agent" } ]

[flows.batch-update]
steps = [
  { run = "batch", config = "qt6.toml" },
  { run = "bash", cmd = "notify-send 'batch {pkg} done'" },
]

# отправка в несколько репозиториев: один submit создаёт задание на каждую ветку, а {tasks} адресует их все
[flows.kernel]
steps = [
  { run = "submit", branch = "sisyphus,p11", task-run = false },
  { run = "zoryn", args = ["task", "add", "{tasks}", "rebuild", "--dependent-on", "kernel-image-for-vm"] },
  { run = "zoryn", args = ["task", "approve", "{tasks}", "all", "-m", "sign"] },
  { run = "zoryn", args = ["task", "run", "{tasks}", "--commit"] },
]

Типы шагов¶

Неизвестное значение run, пропущенный обязательный ключ, steps не в виде массива inline-таблиц или отсутствие самого массива steps — ошибка конфигурации; в сообщении указывается имя сценария, а где это применимо — и номер шага.

Общие ключи шага¶

Условие if выполняется тем же шеллом, что и шаг bash, поэтому в нём работают и шаблоны команд вида {git}, и переменные сценария: if = "test -f .gear/{pkg}.spec".

Опции шага¶

Шаги up, build, submit, task-* и agent принимают типизированные ключи-опции, которые ложатся на флаги соответствующей команды. Каждая опция необязательна; если её не задать, шаг ведёт себя ровно как голая команда без этого флага — включая чтение вашей конфигурации. Например, шаг up/build без ключа parallel соберёт пакет параллельно, если задано [builders] parallel = "on", как и zoryn up; шаг submit без commit/task-run публикует и запускает задание согласно вашей конфигурации [submit].

up и build (фаза сборки; no-build — только для up):

submit:

Одновременно заданные commit и test-only конфликтуют и роняют шаг — ровно так же, как zoryn submit отвергает такую пару.

task-add:

task-approve:

task-run:

agent:

Опции как флаги (неявно по имени)¶

Каждый ключ-опция шагов выбранного сценария доступен и как флаг командной строки у zoryn flow <ИМЯ> — так можно переопределить конфигурационное значение шага на один запуск, не правя сценарий:

• булев ключ k → --k (ставит true) или --no-k (ставит false);
• ключ со значением k → --k ЗНАЧЕНИЕ или --k=ЗНАЧЕНИЕ;
• у branch работает и привычная для zoryn короткая форма -B (-B sisyphus,p11).

Значение из CLI переопределяет конфигурационное значение для того шага (шагов), где ключ объявлен; если ключ не задан ни в CLI, ни в конфиге, действует «умолчание команды». --dry-run печатает каждый шаг с его итоговыми опциями, так что видно, что именно выполнится.

Если ключ объявлен только одним шагом, достаточно голого --k. Если его объявляют несколько шагов (например, skip-check есть и у up, и у submit), голая форма неоднозначна и отклоняется; уточните её как --<шаг>.<ключ>, где <шаг> — это name шага, если он задан, иначе его тип (up, submit, …). Уточнённая форма принимается всегда.

Неизвестный флаг выводит список опций, которые сценарий принимает; неоднозначный — перечисляет конкретные квалифицированные формы. Дополнение по TAB в bash предлагает флаги выбранного сценария и подставляет имена веток после -B/--branch.

zoryn flow release --commit           # переопределить commit у шага submit
zoryn flow release --no-commit        # на этот запуск сделать тестовую отправку
zoryn flow update --submit.skip-check # уточнить ключ, общий для двух шагов
zoryn flow update --builder arm-01    # направить up/build на конкретный билдер

Подстановки¶

Токены {pkg}, {old_version}, {new_version}, {tasks} и {task} подставляются в значения cmd, host, элементы args, prompt и if:

Предпочитайте {tasks}: он годится и для одного репозитория (просто 123), и для нескольких, а zoryn task run/add/approve принимают список через запятую. {task} используйте только когда осознанно нужен один первый номер.

Токен, значение которого ещё не выдал ни один предыдущий шаг, роняет шаг с сообщением flow variable '<имя>' is not available yet (produced by a later step) — это ошибка в конфигурации, а не случайность времени выполнения.

Все остальные токены {...} остаются нетронутыми и доходят до обычных шаблонов команд: {git}, {ssh} и прочие продолжают работать внутри cmd.

Подставленное значение попадает в /bin/sh, а часть значений приходит из репозитория пакета ({old_version} — это сырое поле Version:). Чтобы враждебный репозиторий не протащил через них синтаксис шелла, значение подставляется только если состоит исключительно из безопасного набора A-Za-z0-9.+~_,- (его хватает для любого настоящего имени пакета, версии, номера задания и списка {tasks} через запятую); всё прочее роняет шаг сообщением flow variable '<имя>' has an unsafe value …, не доходя до шелла.

Остальные ключи (branch, config, profile, cli, name) берутся буквально — подстановка в них не выполняется.

Ветвление, повторы и восстановление¶

Упавший шаг не обязан обрывать сценарий. Если у шага есть on-failure и остались попытки:

1. восстановительный сценарий ищется в тех же слоях конфигурации и выполняется целиком;
2. упавший шаг повторяется;
3. max-retries задаёт число таких попыток (по умолчанию 1 — одно восстановление и один повтор).

Восстановительный сценарий — обычный сценарий, у его шагов тоже может быть on-failure. Глубина вложенности ограничена пятью, поэтому сценарий, восстанавливающий сам себя и всегда падающий, всё равно завершится ошибкой, а не зациклится. Прогресс восстановительного сценария живёт только в памяти и в файл состояния не попадает.

Если восстановительный сценарий упал сам или его имя не определено, исходный шаг падает с объединённым сообщением (build failed; recovery flow 'fix-build' also failed: …).

Шаг up и отложенная сборка¶

Шаг up поднимает и коммитит версию до сборки. Как только коммит сделан, наивный повтор увидел бы, что пакет актуален, и остановил бы сценарий как «делать нечего», так и не собрав закоммиченное дерево и не дойдя до submit. zoryn закрывает это с обеих сторон. Поднятая версия и маркер отложенной сборки записываются в файл состояния до начала сборки, поэтому даже жёсткое прерывание во время сборки (Ctrl-C, kill, OOM, перезагрузка) оставляет состояние, с которого можно продолжить. А если сборка просто упала, тот же маркер сохраняется вместе с вычисленными версиями. В любом случае повтор — в том же процессе после восстановительного сценария или в отдельном zoryn flow --continue, пусть и в новом процессе — пересобирает уже поднятую версию, публикует {old_version} и {new_version} так же, как это сделал бы успешный up, и сценарий идёт дальше по шагам.

Шаг up, не нашедший новой версии, — не ошибка: сценарий на нём успешно завершается (код возврата 0). Для ночного запуска из cron это штатный исход.

Починка ИИ-агентом¶

Шаг agent поднимает devenv с фичей, названной в [agent] cli (по умолчанию claude, также codex или opencode), и запускает этот CLI в неинтерактивном режиме — claude -p, codex exec, opencode run — с промптом, который называет самый свежий .gear/build.*.log и отсылает CLI к сценарию починки сборки из поставляемого Agent Skill zoryn (references/repair.md: прочитать лог, поправить пакет, проверить через gear-rpm внутри devenv, оставить изменения незакоммиченными для следующих шагов сценария). Devenv монтирует каталог поставляемого скилла только на чтение по его хостовому пути, поэтому указатель, установленный zoryn agent skill install, внутри него разрешается. Если лога сборки нет, шаг падает; неподдерживаемое значение cli тоже роняет шаг.

Обе половины настраиваются на самом шаге: ключ cli переопределяет машинное значение [agent] cli, а ключ prompt целиком заменяет встроенный промпт починки — { run = "agent", prompt = "прогони тесты {pkg} и почини упавшие, затем выйди" }. Промпт шага шаблонизируется как cmd и самодостаточен, поэтому наличия лога сборки не требует; позаботиться о том, чтобы CLI завершился после работы, должен сам промпт — как это делает и встроенный.

Вместе с on-failure и max-retries получается цикл «сборка сломалась — пусть агент попробует — собрать снова»:

[flows.update]
steps = [ { run = "up", on-failure = "fix-build", max-retries = 3 } ]

[flows.fix-build]
steps = [ { run = "agent" } ]

[agent]
cli = "claude"
flow_steps = true

Состояние и продолжение¶

Запущенный сценарий хранит своё положение в ~/.local/state/zoryn/flow-<проект>-state.json ($XDG_STATE_HOME учитывается). В состоянии лежат имя сценария, номер следующего шага, накопленные переменные и число использованных попыток текущего шага; оно записывается после каждого выполненного или пропущенного шага и удаляется, когда сценарий завершается — успешно или штатной остановкой.

• Упавший шаг оставляет состояние на месте и печатает, как продолжить. Исправьте причину — и zoryn flow --continue повторит именно этот шаг с уже накопленными переменными.
• Запустить сценарий, когда сохранено незавершённое состояние, нельзя: выберите --continue, --restart или --abort.
• --continue и --restart без NAME работают с тем сценарием, который назван в состоянии, даже если конфигурация сейчас выбрала бы другой. С NAME, не совпадающим с сохранённым сценарием, оба отклоняются.
• Файл состояния именуется по имени каталога пакета, поэтому две копии одного пакета (например, клоны sisyphus и p11, оба в каталоге foo) делили бы его. В состоянии записан путь его копии, и --continue/--restart из другой копии отклоняется, а не продолжает не то дерево.
• Для --abort достаточно самого факта существования файла, поэтому он спасает и состояние, повреждённое настолько, что его не удаётся прочитать; сообщение о повреждённом состоянии в любой команде называет --abort как выход.
• --dry-run печатает план раньше всего этого: незавершённый сценарий ему не мешает, а --restart его в этом режиме не стирает.

Сценарий с шагом up или build бесполезен без рабочего билдера, поэтому билдеры разрешаются, а их точки монтирования проверяются до первого шага — неверно настроенный билдер обрывает сценарий сразу, а не на середине.

Коды возврата¶

Связанное¶

• zoryn up — конвейер обновления, который выполняет шаг up
• zoryn submit — что делает шаг submit
• zoryn devenv — окружение для шагов devenv и agent
• Конфигурация — [flows], [agent] и .gear/version-up