@mikitasazan/notify 1.9.0 → 1.10.0

package/dist/cli-flags.d.ts

@@ -1,11 +1,11 @@
 /**
- * Каждое имя флага, которое CLI умеет читать. Существует ради одной вещи:
- * опечатка в имени флага раньше просто игнорировалась. `--noto=...` вместо
- * `--note=...` рисовал карточку без причины и выходил нулём — владелец получал
- * обрезанное сообщение, а вызывающая задача считала, что всё хорошо.
+ * Every flag name the CLI can read. It exists for one reason: a typo in a
+ * flag name used to be ignored. `--noto=...` instead of `--note=...` made a
+ * card with a missing field and exited with code zero — the owner got a
+ * cut-down message, and the task that called it thought everything was fine.
  *
- * Список закрытый и проверяется тестом: тест вытаскивает из этого же файла все
- * имена, которые читает `one`/`num`/`pairs`, и требует, чтобы каждое было
- * здесь. Разойтись молча он не может.
+ * The list is closed and a test checks it: the test pulls every name that
+ * `one`/`num`/`pairs` reads out of this same file, and requires each one to
+ * be here. The list and the code cannot drift apart without the test seeing it.
  */
 export declare const KNOWN_FLAGS: ReadonlySet<string>;

package/dist/cli-flags.js

@@ -1,12 +1,12 @@
 /**
- * Каждое имя флага, которое CLI умеет читать. Существует ради одной вещи:
- * опечатка в имени флага раньше просто игнорировалась. `--noto=...` вместо
- * `--note=...` рисовал карточку без причины и выходил нулём — владелец получал
- * обрезанное сообщение, а вызывающая задача считала, что всё хорошо.
+ * Every flag name the CLI can read. It exists for one reason: a typo in a
+ * flag name used to be ignored. `--noto=...` instead of `--note=...` made a
+ * card with a missing field and exited with code zero — the owner got a
+ * cut-down message, and the task that called it thought everything was fine.
  *
- * Список закрытый и проверяется тестом: тест вытаскивает из этого же файла все
- * имена, которые читает `one`/`num`/`pairs`, и требует, чтобы каждое было
- * здесь. Разойтись молча он не может.
+ * The list is closed and a test checks it: the test pulls every name that
+ * `one`/`num`/`pairs` reads out of this same file, and requires each one to
+ * be here. The list and the code cannot drift apart without the test seeing it.
  */
 export const KNOWN_FLAGS = new Set([
     'action', 'actor', 'assignee', 'author', 'body', 'branch', 'commit',
@@ -16,6 +16,6 @@ export const KNOWN_FLAGS = new Set([
     'item-group', 'job', 'key', 'last-seen', 'line', 'logs', 'note',
     'aside', 'number', 'path', 'period', 'project', 'reviewer', 'stat', 'status',
     'target', 'title', 'url', 'via', 'workflow-name', 'workflow-url',
-    // Флаги без значения. Живут здесь же, чтобы разбор и список не разошлись.
+    // Flags with no value. They live here too, so parsing and the list do not drift apart.
     'json', 'recovered', 'dry-run'
 ]);

package/dist/lint.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The card checks itself, at the moment it is sent.
+ *
+ * Everything else that guards the template runs on examples: the tests on
+ * fixtures, the catalogue build on twenty-one hand-written cards. A live
+ * sender passes values none of them ever pass — an empty title, a status word
+ * from a `--json` payload, a number with a plus sign built by hand — and the
+ * card that reaches the owner is the one nobody looked at.
+ *
+ * So the finished HTML is read here, right before delivery, by the same rules
+ * the page states. A card that breaks them is STILL SENT: a notification is
+ * never worth losing, and a lint is not a reason to drop one. The breach is
+ * reported separately, as its own red card to mac-config, the way a lost
+ * project already is.
+ */
+/**
+ * Reads a finished card and returns what is wrong with it, in the owner's
+ * terms. An empty array means the card obeys the standard.
+ */
+export declare const lintCard: (html: string) => string[];

package/dist/lint.js

@@ -0,0 +1,90 @@
+/**
+ * The card checks itself, at the moment it is sent.
+ *
+ * Everything else that guards the template runs on examples: the tests on
+ * fixtures, the catalogue build on twenty-one hand-written cards. A live
+ * sender passes values none of them ever pass — an empty title, a status word
+ * from a `--json` payload, a number with a plus sign built by hand — and the
+ * card that reaches the owner is the one nobody looked at.
+ *
+ * So the finished HTML is read here, right before delivery, by the same rules
+ * the page states. A card that breaks them is STILL SENT: a notification is
+ * never worth losing, and a lint is not a reason to drop one. The breach is
+ * reported separately, as its own red card to mac-config, the way a lost
+ * project already is.
+ */
+/** The words that are never a name, in the slot where the name belongs. */
+const NOT_A_NAME = new Set([
+    'ok',
+    'fail',
+    'failed',
+    'error',
+    'success',
+    'disabled',
+    'silent',
+    'unknown',
+    'open',
+    'the run',
+    'run',
+    'done',
+    'undefined',
+    'null'
+]);
+/** The five words the third tag is allowed to be, and there is no sixth. */
+const OUTCOMES = new Set(['ok', 'fail', 'off', 'unknown', 'news']);
+/** Labels the template retired. Each one used to say what a neighbour said. */
+const RETIRED = ['Title', 'Number', 'State', 'Via', 'Check', 'Logs', 'Task', 'Id', 'Period'];
+/**
+ * Reads a finished card and returns what is wrong with it, in the owner's
+ * terms. An empty array means the card obeys the standard.
+ */
+export const lintCard = (html) => {
+    const rows = html.split('\n');
+    const found = [];
+    const tags = (rows[0] ?? '').trim().split(/\s+/);
+    if (tags.length !== 3 || !tags.every((t) => t.startsWith('#'))) {
+        found.push(`line 1 is "${rows[0] ?? ''}" — it must be exactly three tags`);
+    }
+    else if (!OUTCOMES.has(tags[2].slice(1))) {
+        found.push(`the outcome tag is "${tags[2]}" — the vocabulary is ok, fail, off, unknown, news`);
+    }
+    if (tags[1] === '#' || tags[1] === '#_') {
+        found.push('the instance tag is empty — it groups nothing and pairs with nothing');
+    }
+    const second = rows[1] ?? '';
+    if (!second) {
+        found.push('there is no line 2 — a card must say what it is about');
+    }
+    // The identifier: what stands after `Type:`, with or without a link on it.
+    const named = second.match(/<b>[^<]+:<\/b>\s*(?:<a href="[^"]*">)?([^<]*)/);
+    if (named && NOT_A_NAME.has(named[1].trim().toLowerCase())) {
+        found.push(`line 2 says "${named[1].trim()}" where the name of the thing belongs`);
+    }
+    for (const label of RETIRED) {
+        if (html.includes(`<b>${label}:</b>`)) {
+            found.push(`the row "${label}:" is back — that fact is already said somewhere else`);
+        }
+    }
+    // Every link must go somewhere a tap can reach, and must be named by what it
+    // opens. A local path is not a link at all — it is monospaced, to be copied.
+    for (const m of html.matchAll(/<a href="([^"]*)">([^<]*)<\/a>/g)) {
+        const [, href, text] = m;
+        if (!/^https?:\/\/\S+$/.test(href)) {
+            found.push(`the link "${text}" points at "${href}", which is not an address`);
+        }
+        if (NOT_A_NAME.has(text.trim().toLowerCase())) {
+            found.push(`a link named "${text}" — name the thing it opens, not the click`);
+        }
+    }
+    // A number is either compared or it is not. A sign in front of it looks like
+    // a comparison and is not one.
+    for (const m of html.matchAll(/<b>([^<]+):<\/b> ([^\n<]*)/g)) {
+        if (/(^|\s)[+\-]\d/.test(m[2])) {
+            found.push(`"${m[1]}: ${m[2]}" — a signed number is not a comparison`);
+        }
+    }
+    if (/all good/i.test(html)) {
+        found.push('"all good" is a status, not a recommendation');
+    }
+    return found;
+};

package/dist/render.js

@@ -280,7 +280,20 @@ const renderGroup = (g) => [
  * The title is cut to its first line: a multi-line commit subject must not
  * drag its own body into the field.
  */
-const titleField = (title) => field('Title', title);
+/**
+ * The commit is one row, the way a task and a pull request are one row: the
+ * hash carries the link, the subject stands next to it. It used to take two —
+ * `Commit: a1b2c3d` and `Title: feat: new landing` underneath — and `Title:`
+ * was the same row the issue card had already lost for the same reason: you
+ * could not read what the card was about without reading two lines.
+ */
+const commitRow = (hash, url, title) => {
+    const linked = fieldLink('Commit', url, hash);
+    if (linked === null || !title) {
+        return linked ?? field('Commit', title);
+    }
+    return `${linked} ${esc(firstLine(title))}`;
+};
 const bodyQuote = (body) => body ? note(body) : null;
 /**
  * Labelled rows, sorted into the groups the sender itself named.
@@ -437,7 +450,7 @@ const renderDeploy = (e) => {
         // repeat in words, and it is the same law a job and a report follow. The
         // `Via` row is gone: it used to carry this same name one floor below.
         typeLine(icon, 'Deploy', mechanism(e.workflowName, e.via, runUrl), runUrl),
-        ...twoBlocks([field('Target', e.target), field('Reason', e.note)], [fieldLink('Commit', e.commitUrl, e.commit), titleField(e.commitTitle), bodyQuote(e.commitBody)])
+        ...twoBlocks([field('Target', e.target), field('Reason', e.note)], [commitRow(e.commit, e.commitUrl, e.commitTitle), bodyQuote(e.commitBody)])
     ]);
 };
 const schedule = (expected, lastSeen, lastLabel) => {
@@ -519,7 +532,7 @@ const renderCi = (e) => {
     const runUrl = e.workflowUrl ?? e.url;
     return join([
         typeLine(icon, 'CI', mechanism(e.workflowName, undefined, runUrl), runUrl),
-        ...twoBlocks([field('Actor', e.actor), field('Reason', e.note)], [fieldLink('Commit', e.commitUrl, e.commit), titleField(e.commitTitle), bodyQuote(e.commitBody)])
+        ...twoBlocks([field('Actor', e.actor), field('Reason', e.note)], [commitRow(e.commit, e.commitUrl, e.commitTitle), bodyQuote(e.commitBody)])
     ]);
 };
 // A pull request and an issue are identified the way GitHub itself identifies

package/dist/send.js

@@ -1,24 +1,27 @@
 /**
- * Транспорт. Переносит проверенный на проде код из
- * game-publisher/scripts/lib/telegram.ts (fetch → curl-фолбэк через stdin,
- * `.trim()` токена) и добавляет то, чего там не было: несколько целей за
- * вызов, `message_thread_id`, повтор на HTTP 429 с уважением `retry_after`,
- * повтор на 5xx, отказ без повтора на прочих 4xx.
+ * Transport. Carries over the code proven in production from
+ * game-publisher/scripts/lib/telegram.ts (fetch, with a curl fallback
+ * through stdin, and `.trim()` on the token) and adds what that code did not
+ * have: several targets per call, `message_thread_id`, a retry on HTTP 429
+ * that respects `retry_after`, a retry on 5xx, and a refusal with no retry
+ * on any other 4xx.
  *
- * Токен — ТОЛЬКО из `process.env.OPS_BOT_TOKEN`, с `.trim()`: перевод
- * строки в токене (частая находка при копипасте) заставляет curl разобрать
- * конфиг как две директивы и утащить хвост токена в stderr прогона.
+ * The token comes ONLY from `process.env.OPS_BOT_TOKEN`, with `.trim()`: a
+ * newline in the token (a common find after copy-paste) makes curl read the
+ * config as two directives and leak the tail of the token into the run's
+ * stderr.
  *
- * Нет токена → 'skipped', не исключение: уведомление не имеет права уронить
- * деплой или регулярную задачу, которая его вызвала.
+ * No token means 'skipped', not an exception: a notification must never be
+ * allowed to bring down the deploy or the scheduled task that called it.
  */
 import { execFileSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { basename } from 'node:path';
 import { render } from "./render.js";
+import { lintCard } from "./lint.js";
 import { ROUTES, targets } from "./routes.js";
 const log = (msg) => {
-    // stderr, не stdout — stdout зарезервирован под возможный машинный вывод CLI.
+    // stderr, not stdout — stdout is reserved for possible machine output of the CLI.
     console.error(`[notify] ${msg}`);
 };
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
@@ -31,11 +34,12 @@ const buildBody = (target, text) => JSON.stringify({
     disable_notification: target.silent
 });
 /**
- * Запасной путь: curl — другой стек TLS/DNS, выручает там, где fetch/undici
- * не маршрутизирует. URL с токеном уходит файлом конфига через stdin, а не
- * аргументом: в argv его видно любому пользователю сервера через `ps aux`.
- * stderr — в 'pipe', а не наследуется: сообщение об ошибке curl может
- * содержать кусок URL с токеном, в лог прогона он попадать не должен.
+ * Fallback path: curl uses a different TLS/DNS stack, and helps in places
+ * where fetch/undici cannot route the request. The URL with the token goes
+ * out as a config file through stdin, not as an argument: in argv it would
+ * be visible to any user on the server through `ps aux`. stderr is set to
+ * 'pipe', not inherited: a curl error message can contain a piece of the URL
+ * with the token, and it must not end up in the run's log.
  */
 const sendViaCurl = (token, target, text) => {
     const config = [
@@ -55,10 +59,10 @@ const sendViaCurl = (token, target, text) => {
         return 'ok';
     }
     catch (err) {
-        // 28 — собственный таймаут curl (`max-time` выше). Как и таймаут fetch, он
-        // означает «ответа нет», а не «не доставлено»: повтор положил бы в чат
-        // вторую копию. Всё остальное (отказ соединения, 4xx с `fail`) повторить
-        // безопасно.
+        // 28 is curl's own timeout (the `max-time` set above). Like a fetch
+        // timeout, it means "no answer came back", not "not delivered": a retry
+        // would put a second copy in the chat. Everything else (connection
+        // refused, 4xx with `fail`) is safe to retry.
         return err.status === 28 ? 'fail' : 'retry';
     }
 };
@@ -81,34 +85,38 @@ const attempt = async (token, target, text) => {
         if (res.status >= 500) {
             return { outcome: 'retry', waitMs: 1000 };
         }
-        // 4xx кроме 429 — постоянная ошибка (не тот thread, бот не админ,
-        // неверный chat_id). Повтор её не исправит.
+        // A 4xx other than 429 is a permanent error (wrong thread, the bot is
+        // not an admin, wrong chat_id). A retry will not fix it.
         //
-        // Причину обязательно вытаскиваем: Telegram кладёт её в `description`
-        // («message thread not found», «can't parse entities»), и без неё понять,
-        // почему уведомления пропали, невозможно — а разбираться будет не
-        // разработчик, а владелец.
+        // We always pull out the reason: Telegram puts it in `description`
+        // ("message thread not found", "can't parse entities"), and without it
+        // there is no way to understand why notifications went missing — and the
+        // one working it out will not be a developer, it will be the owner.
         const detail = (await res.json().catch(() => null));
         log(`HTTP ${res.status}: ${detail?.description ?? 'no description'} — permanent error, not retried`);
         return { outcome: 'fail' };
     }
     catch (err) {
-        // Таймаут — НЕ то же самое, что «не доставлено»: запрос мог дойти, а ответ
-        // не успеть вернуться. Повтор (хоть curl-ом, хоть следующей попыткой) кладёт
-        // в чат второй экземпляр того же сообщения — дедупа у Bot API нет. Поэтому
-        // на таймауте останавливаемся и честно пишем 'failed': лишняя копия аварии
-        // хуже, чем пропущенная строка в логе, а сообщение, скорее всего, ушло.
+        // A timeout is NOT the same thing as "not delivered": the request may
+        // have gone through, and only the answer failed to come back in time. A
+        // retry (whether by curl or by the next attempt) puts a second copy of
+        // the same message in the chat — the Bot API has no deduplication. So on
+        // a timeout we stop and honestly write 'failed': an extra copy of an
+        // alarm is worse than a missing line in the log, and the message most
+        // likely went out anyway.
         if (err instanceof Error && err.name === 'TimeoutError') {
             log('answer timed out — not retried: the message may already be out');
             return { outcome: 'fail' };
         }
-        // Сюда попадают отказы соединения (DNS, TLS, сеть недоступна) — запрос
-        // почти наверняка не ушёл, и curl-фолбэк безопасен. НЕ абсолютно: обрыв
-        // (reset/truncation) ПОСЛЕ того, как Telegram принял POST, тоже кидает
-        // исключение — тогда повтор даст дубль. Это редкий случай; полное
-        // отсутствие дублей невозможно без idempotency-key у Bot API (его нет).
-        // Логика прежняя: дубль на редком reset — меньшее зло, чем потеря
-        // сообщения на частом сетевом сбое.
+        // This branch catches connection failures (DNS, TLS, network
+        // unreachable) — the request almost certainly did not go out, so the
+        // curl fallback is safe. NOT absolutely safe: a break (reset or
+        // truncation) AFTER Telegram already accepted the POST also throws an
+        // exception here — then a retry produces a duplicate. This is a rare
+        // case; a full guarantee against duplicates is not possible without an
+        // idempotency key on the Bot API (it does not have one). The logic
+        // stays the same: a duplicate on a rare reset is a smaller problem than
+        // a lost message on a common network failure.
         log('fetch did not go through, trying curl…');
         const curl = sendViaCurl(token, target, text);
         return curl === 'retry' ? { outcome: 'retry', waitMs: 1000 } : { outcome: curl };
@@ -140,10 +148,11 @@ const deliver = async (where, text) => {
         log('skipped: no OPS_BOT_TOKEN, the message was not sent');
         return 'skipped';
     }
-    // Токен interpolируется в URL и в curl-конфиг (`url = "...bot${token}..."`).
-    // Валидный токен Telegram — это `\d+:[\w-]+`; что-либо с кавычкой/переводом
-    // строки/`?` сломало бы разбор (инъекция директивы curl или query-хвост).
-    // Это требует покорёженного секрета, но проверка копеечная.
+    // The token is interpolated into the URL and into the curl config
+    // (`url = "...bot${token}..."`). A valid Telegram token matches
+    // `\d+:[\w-]+`; anything with a quote, a newline, or a `?` would break the
+    // parsing (a curl directive injection or a query tail). This needs a
+    // corrupted secret to happen, but the check is cheap.
     if (!/^\d+:[A-Za-z0-9_-]+$/.test(token)) {
         log('failed: OPS_BOT_TOKEN does not look like a Telegram token, send cancelled');
         return 'skipped';
@@ -152,19 +161,20 @@ const deliver = async (where, text) => {
         return 'skipped';
     }
     const results = [];
-    // Последовательно, не Promise.all: провал одной цели не должен гонять
-    // ретраи параллельно с остальными и колотить API по нескольким чатам разом.
+    // One after another, not Promise.all: a failure on one target must not run
+    // its retries in parallel with the rest and hammer the API on several chats at once.
     for (const target of where) {
         results.push(await sendOne(token, target, text));
     }
     return results.includes('sent') ? 'sent' : 'failed';
 };
 /**
- * Файл (sendDocument) — multipart, поэтому не через `buildBody`. Политика
- * повторов та же, что у сообщений: 429 с уважением retry_after, 5xx —
- * повтор, прочие 4xx и таймаут — нет (дубль файла хуже пропуска).
- * Отдельного curl-фолбэка нет: файл шлётся с этой же машины, а не из CI,
- * и другой TLS-стек здесь ни разу не понадобился.
+ * A file (sendDocument) is multipart, so it does not go through `buildBody`.
+ * The retry policy is the same as for messages: 429 respects retry_after,
+ * 5xx retries, any other 4xx or a timeout does not (a duplicate file is
+ * worse than a missing one). There is no separate curl fallback here: the
+ * file is sent from this same machine, not from CI, and a different TLS
+ * stack has never been needed here.
  */
 const sendFileOnce = async (token, target, e, caption) => {
     try {
@@ -176,8 +186,8 @@ const sendFileOnce = async (token, target, e, caption) => {
         form.append('caption', caption);
         form.append('parse_mode', 'HTML');
         form.append('disable_notification', String(target.silent));
-        // readFileSync + Blob, не openAsBlob: тот появился в Node 19.8, а пакет
-        // бегает и на сервере. Файлы здесь — текстовые отчёты, память не вопрос.
+        // readFileSync + Blob, not openAsBlob: that appeared in Node 19.8, and
+        // this package also runs on the server. The files here are text reports, so memory is not a concern.
         form.append('document', new Blob([readFileSync(e.path)]), e.filename ?? basename(e.path));
         const res = await fetch(`https://api.telegram.org/bot${token}/sendDocument`, {
             method: 'POST',
@@ -204,7 +214,7 @@ const sendFileOnce = async (token, target, e, caption) => {
             log('answer timed out — not retried: the file may already be out');
             return { outcome: 'fail' };
         }
-        // Файл не читается (нет на диске, нет прав) — постоянная ошибка.
+        // The file cannot be read (not on disk, no permission) — a permanent error.
         if (err instanceof Error && 'code' in err) {
             log(`failed to send the file: ${err.message}`);
             return { outcome: 'fail' };
@@ -225,7 +235,7 @@ const sendFile = async (e) => {
     }
     const caption = render(e);
     const results = [];
-    // Контракт тот же, что у deliver: провал одной цели не отменяет остальные.
+    // The same contract as deliver: a failure on one target does not cancel the rest.
     for (const target of where) {
         let waitMs = 0;
         let got = 'failed';
@@ -248,19 +258,22 @@ const sendFile = async (e) => {
     return results.includes('sent') ? 'sent' : 'failed';
 };
 /**
- * Отправляет событие во все его цели (тема проекта + при необходимости
- * `incidents` + чат команды). Цели идут последовательно; провал одной не
- * отменяет остальные. `'sent'`, если хотя бы одна цель получила сообщение.
+ * Sends the event to all of its targets (the project topic, plus
+ * `incidents` if needed, plus the team chat). Targets are handled one after
+ * another; a failure on one does not cancel the rest. Returns `'sent'` if at
+ * least one target got the message.
  *
- * Неизвестный проект по-прежнему НЕ роняет вызвавший крон (код возврата не
- * меняется) — но и не исчезает молча: в mac-config Ops уходит красная
- * карточка. Дважды этот класс провала жил незамеченным неделями: «vault» и
- * «mac-config» до 04.08, отчёты Alitools — до 18.08. Рекурсия невозможна:
- * карточка-ошибка адресована mac-config, который в ROUTES есть всегда.
+ * An unknown project still does NOT bring down the scheduled task that
+ * called it (the exit code does not change) — but it no longer disappears
+ * silently either: a red card goes out to mac-config Ops. This kind of
+ * failure lived unnoticed for weeks, twice: "vault" and "mac-config" until
+ * 04.08, and the Alitools reports until 18.08. Recursion is not possible
+ * here: the error card is addressed to mac-config, which is always present
+ * in ROUTES.
  */
 const reportLostProject = async (project, kind) => {
-    // Локальный лог называет и допустимые написания — это единственная
-    // диагностика, доступная на машине, где случилась опечатка.
+    // The local log also names the valid spellings — this is the only
+    // diagnostic available on the machine where the typo happened.
     log(`unknown project "${String(project)}" — known: ${Object.keys(ROUTES).join(', ')}`);
     const lost = {
         type: 'job',
@@ -272,9 +285,30 @@ const reportLostProject = async (project, kind) => {
     };
     await deliver(targets(lost), render(lost)).catch(() => undefined);
 };
+/**
+ * The card broke the standard. It still goes out — a notification is never
+ * worth losing over its own formatting — and the breach is raised as its own
+ * red card, the way a lost project is.
+ *
+ * `key` carries the type, so a renderer that starts producing broken deploy
+ * cards raises one running complaint rather than a new one every hour.
+ * Recursion is not possible: this card is not linted.
+ */
+const reportBrokenCard = async (e, faults) => {
+    log(`card does not match the standard: ${faults.join('; ')}`);
+    const broken = {
+        type: 'job',
+        project: 'mac-config',
+        job: 'notify: a card broke the standard',
+        status: 'fail',
+        note: `${String(e.type)} card for ${String(e.project)}: ${faults.join('; ')}`,
+        key: `notify-broken-${String(e.type)}`
+    };
+    await deliver(targets(broken), render(broken)).catch(() => undefined);
+};
 export const notify = async (e) => {
-    // Object.hasOwn, не `in`: `in` ходит по цепочке прототипов, и --project
-    // toString/constructor проходил бы гвард, терял событие И карточку о потере.
+    // Object.hasOwn, not `in`: `in` walks the prototype chain, and
+    // --project toString/constructor would pass the guard, losing the event AND the card about the loss.
     if (!Object.hasOwn(ROUTES, e.project)) {
         await reportLostProject(e.project, String(e.type));
         return 'skipped';
@@ -283,5 +317,13 @@ export const notify = async (e) => {
     if (e.path) {
         return sendFile(e);
     }
-    return deliver(targets(e), render(e));
+    const html = render(e);
+    // Send first, complain second: the delivery of the real card must not wait
+    // on, or be lost to, a check about how it looks.
+    const result = await deliver(targets(e), html);
+    const faults = lintCard(html);
+    if (faults.length > 0) {
+        await reportBrokenCard(e, faults);
+    }
+    return result;
 };

package/dist/setup.js

@@ -1,16 +1,16 @@
 /**
- * `notify setup "<Название проекта>"` — заводит вкладки «⚙️ Ops» и «💬 Dev»
- * в уже созданном форуме и печатает готовую строку для `ROUTES`.
+ * `notify setup "<Project name>"` creates the "⚙️ Ops" and "💬 Dev" tabs in a
+ * forum that already exists, and prints the ready line for `ROUTES`.
  *
- * Сам форум-супергруппу бот создать не может — Telegram разрешает это только
- * живому аккаунту. Поэтому порядок для нового проекта такой:
- *   1. создать группу в Telegram, включить в ней «Темы», добавить
- *      @mikita_ops_bot администратором с правом «Управление темами»;
- *   2. `notify setup <chat_id>` — заведёт обе вкладки и напечатает строку;
- *   3. вставить строку в `src/routes.ts`.
+ * The bot cannot create the forum supergroup itself — Telegram only allows a
+ * real account to do that. So the order for a new project is:
+ *   1. create a group in Telegram, turn on "Topics" in it, add
+ *      @mikita_ops_bot as an admin with the "Manage topics" right;
+ *   2. run `notify setup <chat_id>` — it creates both tabs and prints the line;
+ *   3. paste the line into `src/routes.ts`.
  *
- * Шаг 1 делается один раз на проект и занимает полминуты; шаги 2–3 —
- * механические.
+ * Step 1 happens once per project and takes half a minute. Steps 2 and 3 are
+ * mechanical.
  */
 const log = (msg) => console.error(`[notify] ${msg}`);
 const createTopic = async (token, chat, name, color) => {
@@ -29,7 +29,7 @@ const createTopic = async (token, chat, name, color) => {
         return body.result.message_thread_id;
     }
     catch (err) {
-        // Сеть/таймаут/нечитаемый ответ — не роняем CLI (его контракт: всегда exit 0).
+        // Network error, timeout, or an unreadable response — do not crash the CLI (its contract: always exit 0).
         log(`could not create "${name}": ${err instanceof Error ? err.message : String(err)}`);
         return null;
     }
@@ -42,8 +42,8 @@ export const setupTopic = async (chatId, projectKey) => {
     }
     const ops = await createTopic(token, chatId, '⚙️ Ops', 9367192);
     const dev = await createTopic(token, chatId, '💬 Dev', 7322096);
-    // Частичный успех: если создался только Ops — печатаем его, иначе повторный
-    // запуск создал бы ДРУГУЮ тему Ops, а старый id потерялся бы.
+    // Partial success: if only Ops was created, print it. Otherwise running the
+    // command again would create A DIFFERENT Ops topic, and the old id would be lost.
     if (ops === null) {
         log('Ops was not created — check: is the bot a group admin with "Manage topics", and are topics on?');
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikitasazan/notify",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Единая типизированная отправка Telegram-уведомлений (форум-темы, маршрутизация, ретраи) для всех проектов",
   "type": "module",
   "license": "MIT",