iia-arg/dsh-plugins--packages-dsh-vypusk-watch ↗★ 2

dsh-vypusk-watch

Сторож окна выпуска: сверяет каждый установленный пакет с git-меткой его версии и поднимает одну тревогу, если бой разошёлся с выпуском · Release window watchdog: compares every installed package with the git tag of its version and raises one alarm if production diverged from the release

包名
dsh-vypusk-watch
兼容性
待验证
版本
3.1.8
许可证
MIT
最近更新
2026年10月22日

安装

此插件尚未提供可验证的 bundle,或兼容性检查未通过。请先阅读仓库说明。 阅读完整 README ↗

dsh-vypusk-watch · сторож окна выпуска · release window watchdog

Версия · Version: 3.1.8

Сторож, который сверяет каждый установленный пакет с git-меткой его версии и громко говорит, если в бой попало не то, что выпускали.

A watchdog that compares every installed package with the git tag of its version and speaks up loudly if what reached production is not what was released.

Без непустого VYPUSK_REPO сторож отказывает кодом 3 до helper окна, канала тревог и файлов состояния: это ошибка вызова, а не тревога СЛЕПОТЫ. Правило действует и с --avto-montazh. При заданном дереве остальные ошибки настроек/чтения остаются слепотой с прежним кодом 2 и уведомлением.

Missing/empty VYPUSK_REPO is invocation error 3 before the window helper, alert channel or state files, including --avto-montazh. With an explicit tree, other missing settings or read failures keep their existing blindness2/alert contract.

Читатель кода 3 в бою: vypusk-okno-watch.service (SuccessExitStatus=0 1 2 ⇒ failed) → /etc/agent-registry/storozha-sutochnye.txt:53 (vypusk-okno-watch.service 1) → /usr/local/sbin/sadik-watch: каждые 10 минут проверяет is-failed и формирует владельцу FAILED, кроме подтверждённой отсрочки окном монтажа; эту запись перечня сохраняйте.

Production reader of exit 3: vypusk-okno-watch.service (SuccessExitStatus=0 1 2 ⇒ failed) → /etc/agent-registry/storozha-sutochnye.txt:53 (vypusk-okno-watch.service 1) → /usr/local/sbin/sadik-watch: checks is-failed every 10 minutes and reports FAILED to the owner, except for a confirmed deployment-window deferral; preserve this list entry.

Зачем нужно · Why it exists

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

A package is installed into the production directory from the working tree. If it is installed without a release tag, or files are edited in place, the version number stays the same — and nothing shows it: the number does not distinguish two different builds. Once a package reached production without a tag twice within three hours, and both times a human, not a tool, caught it.

Сторож закрывает этот класс: для каждого пакета дерева он находит установленные копии, читает их версию, находит метку своей версии и сверяет суммы файлов. Совпало — молчит. Разошлось — одна тревога, без повторов, пока картина не изменится.

The watchdog closes this class: for every package in the tree it finds the installed copies, reads their version, finds the tag of their own version and compares file checksums. Match — silence. Divergence — one alarm, with no repeats until the picture changes.

Место в системе · Place in the system

flowchart LR
    T["Таймер systemd · systemd timer
(вне пакета · outside the package)"] --> W["vypusk-okno-watch.sh
(root)"]
    REPO[("Рабочее дерево с метками · working tree with tags
<имя>-v<версия>")] -- "git show / git tag" --> W
    LIVE[("Боевые каталоги · production dirs
корни по имени пакета · roots by package name")] -- "суммы файлов · file checksums" --> W
    INFO[("Чужие копии · foreign copies
только сведение · informational only")] --> W
    W -- "одна тревога на картину · one alarm per picture" --> A["agent-alert"]
    W --> S[("Файл состояния · state file
отпечаток последней тревоги · last alarm fingerprint")]

Пакет содержит исходник, пустой список исключений, документацию, стенды и образец systemd/vypusk-okno-watch.service: автоматически не устанавливает исполняемый файл, юнит или таймер. На машине авторов служба живёт по пути /usr/local/sbin/vypusk-okno-watch.sh, а src/vypusk-okno-watch.sh — её побайтный снимок.

The package contains source, an empty exception list, documentation, stands and a sample systemd/vypusk-okno-watch.service: it automatically installs no executable, unit or timer. On the authors' machine the service lives at /usr/local/sbin/vypusk-okno-watch.sh, and src/vypusk-okno-watch.sh is its byte-for-byte snapshot.

Установка · Installation

Требования: Linux, bash, python3 ≥ 3.9, PyYAML (python3-yaml), git, jq, штатные coreutils; npm — только как оболочка для npm test. Права чтения ко всем боевым каталогам (на машине авторов сторож работает от root).

Requirements: Linux, bash, python3 ≥ 3.9, PyYAML (python3-yaml), git, jq, standard coreutils; npm only as the npm test wrapper. Read access to all production directories (on the authors' machine the watchdog runs as root).

Установка — вручную: скопировать src/vypusk-okno-watch.sh в системный путь и пустой src/vypusk-okno-watch.exceptions.list рядом с ним (либо явно задать путь VYPUSK_ISKLYUCHENIYA), задать окружение (см. docs/SETTINGS.md) и завести свой таймер. Пример юнита и таймера — в docs/ARCHITECTURE.md.

Installation is manual: copy src/vypusk-okno-watch.sh to a system path and the empty src/vypusk-okno-watch.exceptions.list next to it (or set its path through VYPUSK_ISKLYUCHENIYA), set the environment (see docs/SETTINGS.md) and create your own timer. A sample unit and timer are in docs/ARCHITECTURE.md.

Для git ≥ 2.35.2 владелец дерева должен совпадать с пользователем юнита. Иначе администратор доверяет именно этому дереву: git config --system --add safe.directory /path/to/tree (не *). Ошибка dubious ownership ведёт в слепоту; первая строка stderr git печатается рядом с причиной.

For git ≥ 2.35.2 the tree owner must match the unit user. Otherwise an administrator trusts that specific tree with git config --system --add safe.directory /path/to/tree (never *). dubious ownership is blindness; its first stderr line is retained.

Зависимости от соседей · Neighbor dependencies

agent-alert поставляется пакетом dsh-trevogi: $1 — один довод с текстом тревоги, HTML-экранированным сторожем (&, ``). Код 0 — канал подтвердил доставку; прочтение человеком не проверено. Один вызов за прогон, предел 90 с + 5 с до SIGKILL; внутренние повторы — договор отправителя. plugins.yaml и поля derevo описаны в README пакета dsh-montazh; читаются только разделы plugins и services.

dsh-trevogi supplies agent-alert: $1 is one argument containing the alarm text, HTML-escaped by the watchdog (&, ``). Exit 0 confirms delivery at the channel, not human reading. One call per run, 90 seconds plus 5 seconds before SIGKILL; internal retries belong to the sender. The dsh-montazh README defines plugins.yaml and derevo; only the plugins and services sections are read.

Быстрый старт · Quick start

VYPUSK_TIHO=1 VYPUSK_REPO=/path/to/tree VYPUSK_KORNI=/path/to/plugins/node_modules \
  VYPUSK_AGENT_KORNI= VYPUSK_INFO_KORNI= VYPUSK_SOOTVETSTVIYA= VYPUSK_SSYLKI= VYPUSK_RASKLADKA= VYPUSK_REESTR= \
  VYPUSK_ISKLYUCHENIYA=src/vypusk-okno-watch.exceptions.list bash src/vypusk-okno-watch.sh; echo "код · exit $?"

VYPUSK_TIHO=1 — без канала тревог: прогон только печатает. Пустые значения выключают необязательные проверки; не задать их вовсе нельзя — это слепота. Работает — значит, код 0 и строки сошлось: … N из N файлов, метка …. Код 1 — расхождение (тревога), 2 — слепота (сверять нечем), 3 — ошибка вызова: единственный разрешённый довод — --avto-montazh, любой иной довод (--dry-run тоже) даёт отказ с кодом 3 до чтения дерева — ничего не сверено, тревог нет, состояние не тронуто; всё задаётся окружением.

VYPUSK_TIHO=1 means no alarm channel: the run only prints. Empty values disable the optional checks; leaving them unset is not allowed — that is blindness. It works when the exit code is 0 and lines read сошлось: … N из N файлов, метка … (matched: N of N files, tag …). Exit 1 is divergence (alarm), 2 is blindness (nothing to compare against), 3 is a call error: the watchdog accepts only --avto-montazh; any other argument (--dry-run included) is refused with exit 3 before the tree is read — nothing compared, no alarm, state untouched; everything is set through the environment.

Настройки · Settings

Переменная · VariableЗначит · Meaning
VYPUSK_REPOрабочее дерево с метками · working tree with tags
VYPUSK_KORNIкорни боевых каталогов через : · production roots, :-separated
VYPUSK_AGENT_KORNI, VYPUSK_AGENT_POISKкорни копий агентов: явный перечень или родители для поиска /*/plugins · agent copy roots: an explicit list or parents to search `
/*/plugins`
VYPUSK_INFO_KORNIполитика чужих копий: только сведение; корни также должны входить в поиск (VYPUSK_KORNI/VYPUSK_AGENT_*) · foreign-copy policy only; these roots must also be included in the search (VYPUSK_KORNI/VYPUSK_AGENT_*)
VYPUSK_SOOTVETSTVIYAпары ключ=путь1:путь2, по строке; ключ — каталог, имя или прежнее имя; повтор ключа — слепота · one key=path1:path2 pair per line; key is directory, package name or former name; duplicate keys are blindness
VYPUSK_SSYLKIсимволические ссылки монтажа, которые обязаны существовать · install symlinks that must exist
VYPUSK_RASKLADKAпакеты без package.json, сверяемые по раскладке bin, sbin, libexec, lib → /usr/local, systemd → /etc/systemd/system · manifest-less packages compared by the fixed install layout
VYPUSK_REESTRреестр (plugins.yaml) с записями derevo: пакет сверяется с меткой ref по парам local ↔ remote, с режимом и владельцем · registry with derevo entries: the package is compared with its ref tag by local ↔ remote pairs, mode and owner
VYPUSK_ISKLYUCHENIYAпрощённые пропуски записи CHANGELOG · forgiven missing CHANGELOG entries
VYPUSK_SOSTOYANIE, VYPUSK_NAPOMINATфайл состояния и интервал повтора тревоги (86400 с) · state file and alarm repeat interval (86400 s)
VYPUSK_ALERT, VYPUSK_TIHOотправитель тревог; 1 — не звать его · alarm sender; 1 — do not call it

Подробно, с умолчаниями и тем, что сломается при неверном значении, — docs/SETTINGS.md.

Details, with defaults and what breaks with a wrong value: docs/SETTINGS.md.

Как работает · How it works

Правило тревоги — «бой разошёлся с меткой своей версии». Версия совпадает, а суммы файлов разные — тревога: это главный класс, номер не различает редакции. Своей метки нет, хотя выпуски этого пакета известны, — тоже расхождение: смонтировано невыпущенное. Совсем нет меток или две «своих» — слепота. Есть более новый выпуск, а своя метка на месте, — только сведение (INFO). Всё совпало — молчание: сторож, который говорит всегда, перестают читать.

The alarm rule is "production diverged from the tag of its own version". Same version but different file checksums — alarm: this is the main class, the number does not distinguish builds. No own tag while releases of this package are known — also divergence: something unreleased was installed. No tags at all, or two "own" tags — blindness. A newer release exists while the own tag is in place — information only (INFO). Everything matches — silence: a watchdog that always talks stops being read.

Режим счёта. Суммы считаются по всем файлам вне node_modules, без *.bak*, *.tar, *.tgz; режим печатается в выводе, чтобы числа не расходились. Файл, который есть в метке, но не входит в состав публикации (files манифеста) и отсутствует в бою, расхождением не считается: установка его не кладёт. Обратная сторона — файл есть в бою, а в метке нет — расхождение всегда: его положили руками.

Counting mode. Checksums cover every file outside node_modules, excluding *.bak*, *.tar, *.tgz; the mode is printed in the output so numbers stay comparable. A file present in the tag but not in the published file list (files in the manifest) and absent from production is not a divergence: installation does not place it. The other side — a file present in production but not in the tag — is always a divergence: it was put there by hand.

Дополнительные проверки. У версии в бою должна быть непустая запись в CHANGELOG — и в бою, и в метке (прощения — списком исключений с причиной, кем и когда). Пакеты, чей бой живёт не в корнях по имени, сверяются по составу публикации через пары соответствий. Названные символические ссылки монтажа проверяются отдельно: пропавшая ссылка не видна сверке файлов.

Extra checks. The version in production must have a non-empty CHANGELOG entry — both in production and in the tag (forgiveness via an exception list with reason, who and when). Packages whose production copy lives outside the name-based roots are checked by their published file list via correspondence pairs. Named install symlinks are checked separately: a missing link is invisible to file comparison.

Когда замолкает. Одну и ту же картину расхождения сторож отправляет один раз; дальше пишет только в журнал, пока картина не изменится или не пройдёт VYPUSK_NAPOMINAT секунд (по умолчанию сутки). Отпечаток картины считается по суммам, а не по тексту тревоги: вторая правка того же файла меняет картину. Отметка ставится только после подтверждённой доставки — отказ канала не глушится как «уже отправлено».

When it goes quiet. The watchdog sends the same divergence picture once; after that it only writes to the journal until the picture changes or VYPUSK_NAPOMINAT seconds pass (one day by default). The picture fingerprint is computed from checksums, not from the alarm text: a second edit of the same file changes the picture. The mark is set only after confirmed delivery — a channel failure is not silenced as "already sent".

Сторожа и проверки · Guards and checks

Перечень из 15 входов (12 shell-обёрток и три прямых Python-стенда) приведён по именам в docs/GUARDS.md. npm test запускает только копии выпуска и договор своей метки; остальные запускаются отдельно. Проверка исходников без установленного сторожа:

The 15 entry points (12 shell wrappers and three direct Python stands) are listed by name in docs/GUARDS.md. npm test runs only release copies and the own-tag contract; run the others separately. To check source without an installed watchdog:

VYPUSK_TEST_WATCH=src/vypusk-okno-watch.sh VYPUSK_TEST_REFERENCE=src/vypusk-okno-watch.sh npm test

Подмена эталона проверяет кандидат, а не тождество боевому файлу. Настройки — 7 проб: отсутствие REPO, KORNI, SSYLKI, AGENT-корней, RASKLADKA, REESTR и явно пустые необязательные значения.

An overridden reference checks the candidate, not equality with production. Settings have 7 probes: missing REPO, KORNI, SSYLKI, AGENT roots, RASKLADKA, REESTR and explicit empty optional values.

Границы · Limits

  • Не отличает «смонтировали и пометили» от «не монтировали вовсе»: оба дают «метка = бой», то есть зелёное. Он ловит несоответствие боя выпуску, а не отсутствие работы.
  • Не ловит правку в памяти процесса: сверяет диск с диском. Живую версию показывает только журнал работающего процесса.
  • Не ловит пакеты вне дерева, подмену самой метки, верность кода (одинаково плохой код в обоих местах — зелёный), содержимое node_modules и файлы, исключённые режимом счёта.
  • Не ловит неверное значение переменной окружения (VYPUSK_TIHO=да — не «1», режим боевой) и опечатку в имени необязательной (VYPUSK_TIH0=1 — ноль вместо «O», переменная не прочитана вовсе; так же с VYPUSK_NAPOMINAT и др.). Опечатка в имени обязательной настройки ловится: VYPUSK_REPO — отказ3 без канала, остальные — слепота2 «не задана».
  • src/vypusk-okno-watch.sh — снимок установленного файла, и стенд сверяет их суммы: правка снимка без выпуска нового боевого файла