@mikitasazan/notify 1.8.0 → 1.9.0

package/README.md

@@ -95,17 +95,18 @@ notify report --project playhub --json < payload.json   # весь объект
 
 Полные сигнатуры — `src/events.ts`.
 
-**Ключ задачи.** Первая строка каждой карточки — два тега: `#тип #ключ`.
+**Ключ задачи.** Первая строка каждой карточки — три тега: `#тип #ключ
+#итог`.
 По ним дневной разборщик сверяет «это 🔴 уже закрыто более поздней карточкой
 той же задачи?» без сравнения человеческих формулировок. Явный `--key`
 побеждает; без него ключ выводится из заголовка и меняется вместе с ним —
 регулярный отправитель передаёт `--key` явно. В stdout CLI ключ не попадает.
 
-**Единственная дверь для свободного HTML** — `sendReport()` (`report --json` у
-аналитик): плотную строку дневного отчёта не разложить в `label=value` не
-испортив. Стандартизирован транспорт, формат тела — нет, и только здесь.
-Строку тегов `#report #ключ` пакет ставит и здесь: тег — фильтр владельца, к
-формату тела он отношения не имеет. Без явного ключа берётся `daily`.
+**Свободного HTML в пакете нет.** Дверь `sendReport()` удалена 25.08.2026:
+она отдавала произвольную разметку и ставила карточке два тега вместо трёх —
+единственный вид, который нельзя было отфильтровать по итогу. Последний её
+отправитель перешёл на типизированный `report` ещё 25.08; тип события задаёт
+каждый знак карточки, других путей нет.
 
 **Неизвестный проект** не роняет вызвавший крон (код возврата 0), но больше и
 не исчезает молча: в mac-config Ops уходит красная карточка «notify: событие

package/dist/cli.js

@@ -1,24 +1,25 @@
 #!/usr/bin/env node
 /**
- * `notify <type> [--flag value]...` — тонкий диспетчер. Ноль зависимостей:
- * разбор аргументов написан руками (не yargs/commander), потому что здесь
- * нужно ровно два вида флагов (одиночный и повторяемый `key=value`).
+ * `notify <type> [--flag value]...` — a thin dispatcher. Zero dependencies:
+ * argument parsing is written by hand (not yargs/commander), because it
+ * needs exactly two kinds of flags (a single one and a repeatable
+ * `key=value`).
  *
- * Код возврата ВСЕГДА 0 — уведомление не имеет права уронить вызвавший его
- * деплой или задачу. Все ошибки — только в stderr. Исключения намеренно нет
- * (см. docs/rollout.md «чего не делаем»): сценария, где деплой должен упасть
- * из-за неотправленного сообщения, не существует.
+ * The exit code is ALWAYS 0 — a notification has no right to bring down the
+ * deploy or task that called it. All errors go to stderr only. There is
+ * deliberately no exception (see docs/rollout.md "what we don't do"): there
+ * is no scenario where a deploy should fail because a message did not send.
  *
  *   notify deploy   --project playhub --status ok --commit "msg" [--commit-url "..."] --url "..."
- *   notify job      --project playhub --job "Импорт игр" --status ok --stat "добавлено=5"
- *   notify report   --project playhub --title "Сводка за день" --line "Игр=1284"
+ *   notify job      --project playhub --job "Game import" --status ok --stat "added=5"
+ *   notify report   --project playhub --title "Daily summary" --line "Games=1284"
  *   notify ci       --project arvent  --status fail --branch master --actor saz_sam
  *   notify pr       --project arvent  --action opened --number 142 --title "..."
- *   notify incident --project arvent  --title "Redis недоступен" --detail "$ERR"
- *   notify file     --project arvent  --title "Полные диалоги" --path ./out.txt [--filename имя.txt]
- *   notify <type> [--key стабильный-ключ]   # ключ задачи в последней строке карточки
- *   notify <type> --json < payload.json   # весь объект события со stdin
- *   notify setup <chat_id форума> <ключ-проекта>   # создать вкладки, см. setup.ts
+ *   notify incident --project arvent  --title "Redis is unreachable" --detail "$ERR"
+ *   notify file     --project arvent  --title "Full dialogues" --path ./out.txt [--filename name.txt]
+ *   notify <type> [--key stable-key]   # the task's key on the card's last line
+ *   notify <type> --json < payload.json   # the whole event object on stdin
+ *   notify setup <forum chat_id> <project key>   # create the tabs, see setup.ts
  */
 import { readFileSync } from 'node:fs';
 import { KNOWN_FLAGS } from "./cli-flags.js";
@@ -52,7 +53,7 @@ if (command === 'setup') {
 }
 const flags = new Map();
 const parseErrors = [];
-/** Флаги без значения. Всё остальное обязано его иметь. */
+/** Flags with no value. Everything else must have one. */
 const BOOLEAN_FLAGS = new Set(['json', 'recovered', 'dry-run']);
 for (let i = 1; i < args.length; i++) {
     const arg = args[i];
@@ -60,8 +61,8 @@ for (let i = 1; i < args.length; i++) {
         parseErrors.push(`stray argument with no flag: "${safe(arg)}"`);
         continue;
     }
-    // Форма `--key=value` обязательна для значений, начинающихся с `--`
-    // (текст ошибки, кусок диффа): иначе они были бы съедены как флаги.
+    // The `--key=value` form is required for values that start with `--`
+    // (an error message, a diff chunk): otherwise they would get eaten as flags.
     const eq = arg.indexOf('=');
     if (eq !== -1) {
         const key = arg.slice(2, eq);
@@ -74,10 +75,10 @@ for (let i = 1; i < args.length; i++) {
         continue;
     }
     const next = args[i + 1];
-    // Раньше флаг без значения молча становился строкой 'true'. Отсюда
-    // `--url` в конце команды давал `href="true"`, Telegram отвечал 400 и
-    // ТЕРЯЛОСЬ ВСЁ сообщение, а `--status` без значения рисовал 🔴 на
-    // успешном деплое. Теперь это явная ошибка разбора.
+    // A flag with no value used to silently become the string 'true'. That is
+    // how `--url` at the end of a command produced `href="true"`, Telegram
+    // answered 400 and THE WHOLE MESSAGE WAS LOST, and `--status` with no value
+    // painted 🔴 on a successful deploy. Now it is an explicit parse error.
     if (next === undefined || next.startsWith('--')) {
         parseErrors.push(`flag --${safe(key)} with no value`);
         continue;
@@ -91,7 +92,7 @@ for (const key of flags.keys()) {
         parseErrors.push(`unknown flag --${safe(key)}`);
     }
 }
-// Число с явной ошибкой разбора, иначе рендер рисовал «PR #NaN».
+// A number with an explicit parse error, otherwise the render drew "PR #NaN".
 const num = (key) => {
     const raw = one(key);
     const n = Number(raw);
@@ -102,12 +103,13 @@ const num = (key) => {
     return n;
 };
 /**
- * `--item "текст"` или `--item "текст|https://ссылка"`.
+ * `--item "text"` or `--item "text|https://link"`.
  *
- * Имя группы у позиции нельзя передать так же, как у `--stat`: черта здесь
- * уже занята ссылкой. Поэтому `--item-group "Red checks"` — одно имя на все
- * позиции этого вызова. Списки у отправителей однородные (красные проверки,
- * выключенные процессы), а разнородный список — это `--json`.
+ * An item's group name cannot be passed the same way `--stat` does it: the
+ * bar here is already taken by the link. So `--item-group "Red checks"` is
+ * one name for all the items in this call. Senders' lists are homogeneous
+ * (red checks, disabled processes), and a mixed list is what `--json` is
+ * for.
  */
 const items = () => {
     const name = flags.get('item-group')?.[0];
@@ -118,13 +120,13 @@ const items = () => {
     });
 };
 /**
- * `--stat "label=value"`, и с 25.08.2026 — `--stat "Group | label=value"`:
- * имя группы, вертикальная черта, ярлык. Черта выбрана потому, что её нет ни
- * в одном живом ярлыке, а двоеточие есть («Eval: bot answer quality») и
- * равенство занято значением. Пробелы вокруг черты необязательны.
+ * `--stat "label=value"`, and since 25.08.2026 — `--stat "Group | label=value"`:
+ * group name, vertical bar, label. The bar was chosen because it appears in
+ * no live label, while a colon does ("Eval: bot answer quality") and equals
+ * is taken by the value. Spaces around the bar are optional.
  *
- * Без черты всё как было — так шлют больше двадцати отправителей, и ни один
- * из них менять не нужно.
+ * Without the bar everything works as before — over twenty senders send it
+ * that way, and not one of them needs to change.
  */
 const pairs = (key) => (flags.get(key) ?? []).map((s) => {
     const idx = s.indexOf('=');
@@ -154,9 +156,10 @@ const ISSUE_ALIASES = {
     assigned: 'assigned',
     closed: 'closed'
 };
-// Ошибка кладётся в parseErrors — тот же путь, что у остального разбора: ниже
-// он печатает все ошибки разом и выходит ДО отправки. Значение-заглушка нужно
-// только чтобы удовлетворить тип, до сети оно не доживёт.
+// The error goes into parseErrors — the same path the rest of parsing takes:
+// below, it prints all the errors together and exits BEFORE sending. The
+// placeholder value only needs to satisfy the type; it never lives to reach
+// the network.
 const prAction = (raw) => {
     const hit = PR_ALIASES[(raw ?? '').toLowerCase()];
     if (!hit) {
@@ -174,19 +177,21 @@ const issueAction = (raw) => {
     return hit;
 };
 /**
- * Всё, что не признано успехом, считается провалом.
+ * Anything not recognized as a success counts as a failure.
  *
- * Тут важна не строгость, а согласованность: раньше `--status success`
- * (естественная опечатка при ручном вызове) рисовал 🔴 «упал», но `severity()`
- * видел «не fail» и слал сообщение БЕЗ звука. Красная плашка без звука —
- * худший исход: авария выглядит аварией, но не будит.
+ * What matters here is not strictness but consistency: `--status success`
+ * used to (a natural typo on a manual call) paint 🔴 "failed," but
+ * `severity()` saw "not fail" and sent the message WITH NO SOUND. A red
+ * card with no sound is the worst outcome: it looks like an incident but
+ * does not wake anyone up.
  */
 const status = () => {
     const raw = (one('status') ?? '').toLowerCase();
     return raw === 'ok' || raw === 'success' || raw === 'passed' || raw === '0' ? 'ok' : 'fail';
 };
-// `job` — единственный тип с третьим состоянием (`disabled`): задача не
-// провалилась сама, её выключил кто-то извне (GitHub Actions без минут).
+// `job` is the only type with a third state (`disabled`): the task did not
+// fail on its own, someone switched it off from outside (GitHub Actions out
+// of minutes).
 const jobStatus = () => {
     const raw = (one('status') ?? '').toLowerCase();
     if (raw === 'disabled') {
@@ -201,13 +206,14 @@ let event;
 if (flags.has('json')) {
     try {
         const payload = JSON.parse(readFileSync(0, 'utf-8'));
-        // type — за командой, не за payload: иначе --pr <объект с type:deploy>
-        // отправил бы событие другого типа.
+        // type comes from the command, not from the payload: otherwise --pr
+        // <object with type:deploy> would send an event of a different type.
         event = { ...payload, type: command };
     }
     catch (err) {
-        // Тоже в parseErrors: обе аналитики зовут CLI через `|| true`, и молчащий
-        // разбор JSON означал бы зелёный крон без дневного отчёта.
+        // Also into parseErrors: both analytics jobs call the CLI through
+        // `|| true`, and a silent JSON parse failure would mean a green cron run
+        // with no daily report.
         parseErrors.push(`--json from stdin did not parse: ${safe(err instanceof Error ? err.message : err)}`);
     }
 }
@@ -356,15 +362,15 @@ else {
             };
             break;
         default:
-            // В parseErrors, а не просто в лог: иначе неизвестный тип уходил в
-            // тишину — событие не собиралось, ошибок разбора не было, и CLI выходил
-            // нулём, ничего не отправив и ничего об этом не сказав.
+            // Into parseErrors, not just into the log: otherwise an unknown type
+            // went quiet — no event was built, there were no parse errors, and
+            // the CLI exited zero, sending nothing and saying nothing about it.
             parseErrors.push(`unknown event type: ${safe(command ?? '(none given)')}`);
     }
 }
-// --key применим к любому типу — одна точка вместо строки в каждом case
-// (девять копий уже потеряли бы десятую). `??`: путь --json может нести
-// key в самом объекте, отсутствие флага не должно его затирать.
+// --key applies to any type — one spot instead of a line in every case
+// (nine copies would already have lost the tenth). `??`: the --json path
+// may carry key in the object itself, a missing flag must not overwrite it.
 if (event) {
     event.key = one('key') ?? event.key;
     // --path is applicable to any type too, for the same reason --key is.
@@ -374,8 +380,9 @@ if (event) {
 if (event?.filename && !event.path) {
     parseErrors.push('--filename: given without --path, so there is no file to name');
 }
-// Ошибки разбора — до отправки: лучше внятно сказать, что не так с командой,
-// чем прислать сообщение с «true» вместо ссылки или 🔴 на успешном деплое.
+// Parse errors — before sending: better to say clearly what is wrong with
+// the command than to send a message with "true" instead of a link, or a
+// 🔴 on a successful deploy.
 if (parseErrors.length > 0) {
     for (const err of parseErrors) {
         log(err);
@@ -403,15 +410,17 @@ if (event && flags.has('dry-run')) {
     process.exit(0);
 }
 if (event) {
-    // Ловим ВСЁ: уведомление не имеет права уронить деплой или крон, который
-    // его вызвал. В bash с `set -e` (или в `trap ... ERR`) ненулевой код здесь
-    // завалил бы саму задачу — ровно то, чего пакет обязан не делать.
+    // Catches EVERYTHING: a notification has no right to bring down the
+    // deploy or cron job that called it. In bash with `set -e` (or in
+    // `trap ... ERR`) a non-zero code here would fail the task itself — the
+    // exact thing this package must never do.
     try {
         log(await notify(event));
     }
     catch (err) {
-        // Слово `failed` — контракт, тот же, что у ошибки разбора выше. Без него
-        // исключение при отправке читалось сторожами как «ничего не случилось».
+        // The word `failed` is a contract, the same one the parse error above
+        // uses. Without it, an exception while sending read to watchdogs as
+        // "nothing happened."
         log(`failed: ${safe(err instanceof Error ? err.message : err)}`);
     }
 }