@mikitasazan/notify 1.3.0 → 1.4.1

package/dist/cli-flags.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Каждое имя флага, которое CLI умеет читать. Существует ради одной вещи:
+ * опечатка в имени флага раньше просто игнорировалась. `--noto=...` вместо
+ * `--note=...` рисовал карточку без причины и выходил нулём — владелец получал
+ * обрезанное сообщение, а вызывающая задача считала, что всё хорошо.
+ *
+ * Список закрытый и проверяется тестом: тест вытаскивает из этого же файла все
+ * имена, которые читает `one`/`num`/`pairs`, и требует, чтобы каждое было
+ * здесь. Разойтись молча он не может.
+ */
+export declare const KNOWN_FLAGS: ReadonlySet<string>;

package/dist/cli-flags.js

@@ -0,0 +1,19 @@
+/**
+ * Каждое имя флага, которое CLI умеет читать. Существует ради одной вещи:
+ * опечатка в имени флага раньше просто игнорировалась. `--noto=...` вместо
+ * `--note=...` рисовал карточку без причины и выходил нулём — владелец получал
+ * обрезанное сообщение, а вызывающая задача считала, что всё хорошо.
+ *
+ * Список закрытый и проверяется тестом: тест вытаскивает из этого же файла все
+ * имена, которые читает `one`/`num`/`pairs`, и требует, чтобы каждое было
+ * здесь. Разойтись молча он не может.
+ */
+export const KNOWN_FLAGS = new Set([
+    'action', 'actor', 'assignee', 'author', 'body', 'branch', 'commit',
+    'commit-body', 'commit-title', 'commit-url', 'detail', 'expected',
+    'filename', 'item', 'job', 'key', 'last-seen', 'line', 'logs', 'note',
+    'number', 'path', 'period', 'project', 'reviewer', 'stat', 'status',
+    'target', 'title', 'url', 'via', 'workflow-name', 'workflow-url',
+    // Флаги без значения. Живут здесь же, чтобы разбор и список не разошлись.
+    'json', 'recovered', 'dry-run'
+]);

package/dist/cli.js

@@ -21,16 +21,30 @@
  *   notify setup <chat_id форума> <ключ-проекта>   # создать вкладки, см. setup.ts
  */
 import { readFileSync } from 'node:fs';
+import { KNOWN_FLAGS } from "./cli-flags.js";
+import { render } from "./render.js";
 import { notify } from "./send.js";
 import { setupTopic } from "./setup.js";
 const log = (msg) => console.error(`[notify] ${msg}`);
+/**
+ * Anything taken from the caller and echoed into a message goes through this.
+ *
+ * `sent`, `failed` and `skipped` are a CONTRACT: `notify-fail.sh` greps
+ * `^\[notify\] sent$`, the server-side silence watchdog matches `*sent*`, and
+ * `action.yml` warns on `*failed*|*skipped*`. An input value carrying one of
+ * those words puts it on stderr — `notify sent --project=x` printed
+ * `unknown event type: sent`, and the watchdog read a card that was never
+ * delivered as delivered, then stopped repeating the alarm. Found by Codex,
+ * 25.08.2026.
+ */
+const safe = (v) => String(v ?? '').replace(/\b(sent|failed|skipped)\b/gi, (w) => `${w[0]}·${w.slice(1)}`);
 const args = process.argv.slice(2);
 const command = args[0];
 if (command === 'setup') {
     const [, chatId, projectKey] = args;
     if (!chatId || !projectKey) {
-        log('использование: notify setup <chat_id форума> <ключ-проекта>');
-        log('  сначала создай группу, включи в ней «Темы» и добавь бота админом');
+        log('usage: notify setup <forum chat_id> <project key>');
+        log('  create the group first, turn Topics on in it, add the bot as admin');
         process.exit(0);
     }
     await setupTopic(chatId, projectKey);
@@ -39,11 +53,11 @@ if (command === 'setup') {
 const flags = new Map();
 const parseErrors = [];
 /** Флаги без значения. Всё остальное обязано его иметь. */
-const BOOLEAN_FLAGS = new Set(['json', 'recovered']);
+const BOOLEAN_FLAGS = new Set(['json', 'recovered', 'dry-run']);
 for (let i = 1; i < args.length; i++) {
     const arg = args[i];
     if (!arg.startsWith('--')) {
-        parseErrors.push(`лишний аргумент без флага: «${arg}»`);
+        parseErrors.push(`stray argument with no flag: "${safe(arg)}"`);
         continue;
     }
     // Форма `--key=value` обязательна для значений, начинающихся с `--`
@@ -65,19 +79,24 @@ for (let i = 1; i < args.length; i++) {
     // ТЕРЯЛОСЬ ВСЁ сообщение, а `--status` без значения рисовал 🔴 на
     // успешном деплое. Теперь это явная ошибка разбора.
     if (next === undefined || next.startsWith('--')) {
-        parseErrors.push(`флаг --${key} без значения`);
+        parseErrors.push(`flag --${safe(key)} with no value`);
         continue;
     }
     i++;
     flags.set(key, [...(flags.get(key) ?? []), next]);
 }
 const one = (key) => flags.get(key)?.[0];
+for (const key of flags.keys()) {
+    if (!KNOWN_FLAGS.has(key)) {
+        parseErrors.push(`unknown flag --${safe(key)}`);
+    }
+}
 // Число с явной ошибкой разбора, иначе рендер рисовал «PR #NaN».
 const num = (key) => {
     const raw = one(key);
     const n = Number(raw);
     if (raw === undefined || Number.isNaN(n)) {
-        parseErrors.push(`--${key}: ожидается число, получено «${raw ?? ''}»`);
+        parseErrors.push(`--${safe(key)}: expected a number, got "${safe(raw)}"`);
         return 0;
     }
     return n;
@@ -114,7 +133,7 @@ const ISSUE_ALIASES = {
 const prAction = (raw) => {
     const hit = PR_ALIASES[(raw ?? '').toLowerCase()];
     if (!hit) {
-        parseErrors.push(`--action: неизвестное действие PR «${raw ?? ''}» (${Object.keys(PR_ALIASES).join(', ')})`);
+        parseErrors.push(`--action: unknown PR action "${safe(raw)}" (${Object.keys(PR_ALIASES).join(', ')})`);
         return 'opened';
     }
     return hit;
@@ -122,7 +141,7 @@ const prAction = (raw) => {
 const issueAction = (raw) => {
     const hit = ISSUE_ALIASES[(raw ?? '').toLowerCase()];
     if (!hit) {
-        parseErrors.push(`--action: неизвестное действие задачи «${raw ?? ''}» (${Object.keys(ISSUE_ALIASES).join(', ')})`);
+        parseErrors.push(`--action: unknown issue action "${raw ?? ''}" (${Object.keys(ISSUE_ALIASES).join(', ')})`);
         return 'opened';
     }
     return hit;
@@ -157,7 +176,9 @@ if (flags.has('json')) {
         event = { ...payload, type: command };
     }
     catch (err) {
-        log(`не удалось разобрать --json со stdin: ${err instanceof Error ? err.message : String(err)}`);
+        // Тоже в parseErrors: обе аналитики зовут CLI через `|| true`, и молчащий
+        // разбор JSON означал бы зелёный крон без дневного отчёта.
+        parseErrors.push(`--json from stdin did not parse: ${safe(err instanceof Error ? err.message : err)}`);
     }
 }
 else {
@@ -183,7 +204,7 @@ else {
             event = {
                 type: 'job',
                 project: project(),
-                job: one('job') ?? '(без имени)',
+                job: one('job') ?? '(no name)',
                 status: jobStatus(),
                 stats: pairs('stat'),
                 items: items(),
@@ -197,7 +218,7 @@ else {
             event = {
                 type: 'report',
                 project: project(),
-                title: one('title') ?? '(без заголовка)',
+                title: one('title') ?? '(no title)',
                 period: one('period'),
                 lines: pairs('line'),
                 items: items(),
@@ -215,6 +236,7 @@ else {
                 commitTitle: one('commit-title'),
                 commitBody: one('commit-body'),
                 actor: one('actor'),
+                note: one('note'),
                 workflowUrl: one('workflow-url'),
                 workflowName: one('workflow-name'),
                 url: one('url')
@@ -226,7 +248,8 @@ else {
                 project: project(),
                 action: prAction(one('action')),
                 number: num('number'),
-                title: one('title') ?? '(без заголовка)',
+                title: one('title') ?? '(no title)',
+                body: one('body'),
                 author: one('author'),
                 reviewer: one('reviewer'),
                 url: one('url')
@@ -238,7 +261,7 @@ else {
                 project: project(),
                 action: issueAction(one('action')),
                 number: num('number'),
-                title: one('title') ?? '(без заголовка)',
+                title: one('title') ?? '(no title)',
                 body: one('body'),
                 author: one('author'),
                 assignee: one('assignee'),
@@ -249,7 +272,7 @@ else {
             event = {
                 type: 'incident',
                 project: project(),
-                title: one('title') ?? '(без заголовка)',
+                title: one('title') ?? '(no title)',
                 detail: one('detail'),
                 logs: one('logs'),
                 url: one('url')
@@ -259,7 +282,7 @@ else {
             event = {
                 type: 'heartbeat_miss',
                 project: project(),
-                job: one('job') ?? '(без имени)',
+                job: one('job') ?? '(no name)',
                 lastSeen: one('last-seen'),
                 expected: one('expected'),
                 recovered: flags.has('recovered'),
@@ -269,12 +292,12 @@ else {
         case 'file': {
             const path = one('path');
             if (!path) {
-                parseErrors.push('--path: обязателен для file');
+                parseErrors.push('--path: required for a file event');
             }
             event = {
                 type: 'file',
                 project: project(),
-                title: one('title') ?? '(без заголовка)',
+                title: one('title') ?? '(no title)',
                 path: path ?? '',
                 filename: one('filename'),
                 note: one('note')
@@ -282,7 +305,10 @@ else {
             break;
         }
         default:
-            log(`неизвестный тип события: ${command ?? '(не указан)'}`);
+            // В parseErrors, а не просто в лог: иначе неизвестный тип уходил в
+            // тишину — событие не собиралось, ошибок разбора не было, и CLI выходил
+            // нулём, ничего не отправив и ничего об этом не сказав.
+            parseErrors.push(`unknown event type: ${safe(command ?? '(none given)')}`);
     }
 }
 // --key применим к любому типу — одна точка вместо строки в каждом case
@@ -297,7 +323,26 @@ if (parseErrors.length > 0) {
     for (const err of parseErrors) {
         log(err);
     }
-    log('событие не отправлено — исправь команду');
+    // The word `failed` is a CONTRACT, not prose. Two readers match on it: the
+    // GitHub Action turns it into a yellow annotation, and the VPS watchdog reads
+    // the combined stream for `sent|failed|skipped`. Before this, a parse error
+    // printed neither word — the run stayed green, the watchdog stayed quiet, and
+    // the card simply never existed.
+    // It must NOT contain the substring `sent`: heartbeat-check.sh matches `*sent*`
+    // and would read a failure as a success.
+    log('failed: bad command, nothing delivered');
+    process.exit(0);
+}
+if (event && flags.has('dry-run')) {
+    // The rendered card on STDOUT, nothing sent and no token needed. This is how
+    // a change to the format is shown to the owner before it reaches a forum, and
+    // how ~25 edited call sites are checked one by one — the package always exits
+    // 0, so a typo in a flag is otherwise silent.
+    //
+    // stdout, not stderr: every other line this CLI prints goes to stderr, and
+    // watchdogs read that stream for the words `sent|failed|skipped`. A card
+    // printed there would be read as a verdict.
+    process.stdout.write(`${render(event)}\n`);
     process.exit(0);
 }
 if (event) {
@@ -308,7 +353,9 @@ if (event) {
         log(await notify(event));
     }
     catch (err) {
-        log(`не отправлено: ${err instanceof Error ? err.message : String(err)}`);
+        // Слово `failed` — контракт, тот же, что у ошибки разбора выше. Без него
+        // исключение при отправке читалось сторожами как «ничего не случилось».
+        log(`failed: ${safe(err instanceof Error ? err.message : err)}`);
     }
 }
 process.exit(0);

package/dist/events.d.ts

@@ -49,12 +49,12 @@ export type NotifyEvent = Keyed & (
     commit?: string;
     /** Ссылка на коммит — строка «коммит» становится кликабельной. */
     commitUrl?: string;
-    /** Заголовок коммита — рендерится рядом с телом в цитате. */
+    /** Заголовок коммита — рендерится полем `Title:`, тело идёт цитатой ниже. */
     commitTitle?: string;
     /** Тело коммита, если есть — та же цитата, что и заголовок. */
     commitBody?: string;
     workflowUrl?: string;
-    /** Название прогона для видимого текста ссылки (по умолчанию — просто "run"). */
+    /** Название прогона для видимого текста ссылки (по умолчанию — `open`). */
     workflowName?: string;
     url?: string;
     /**
@@ -85,8 +85,13 @@ export type NotifyEvent = Keyed & (
     items?: Item[];
     note?: string;
     workflowUrl?: string;
-    /** Название прогона для видимого текста ссылки (по умолчанию — просто "run"). */
+    /** Название прогона для видимого текста ссылки (по умолчанию — `open`). */
     workflowName?: string;
+    /**
+     * Запасное имя для ссылки на прогон: половина отправителей шлёт её как
+     * `--url`. Рендер берёт `workflowUrl ?? url`, так что оба имени работают.
+     * В новых вызовах предпочитай `workflowUrl` — оно говорит, куда ведёт.
+     */
     url?: string;
 }
 /** Сводка с цифрами: дневной отчёт, дайджест аналитики. */
@@ -124,14 +129,19 @@ export type NotifyEvent = Keyed & (
     commit?: string;
     /** Ссылка на коммит — хэш становится кликабельным. */
     commitUrl?: string;
-    /** Заголовок коммита (subject) — рендерится в цитате вместе с телом. */
+    /** Заголовок коммита (subject) — отдельное поле `Title:`, не цитата. */
     commitTitle?: string;
     /** Тело коммита (после subject) — та же цитата, что и заголовок. */
     commitBody?: string;
     actor?: string;
-    /** Ссылка на прогон (workflow run) — отдельно от `url`, который у CI не используется. */
+    /**
+     * Why this run happened, when there is no commit to point at: a nightly
+     * schedule, a manual press. Renders as `Reason:`, same as on deploy.
+     */
+    note?: string;
+    /** Ссылка на прогон (workflow run) — отдельно от `url` — запасной для `workflowUrl`. */
     workflowUrl?: string;
-    /** Название прогона для видимого текста ссылки (по умолчанию — просто "run"). */
+    /** Название прогона для видимого текста ссылки (по умолчанию — `open`). */
     workflowName?: string;
     url?: string;
 }
@@ -146,6 +156,8 @@ export type NotifyEvent = Keyed & (
     action: 'opened' | 'ready_for_review' | 'review_requested' | 'approved' | 'changes_requested' | 'merged' | 'closed';
     number: number;
     title: string;
+    /** PR description — quoted on its own; the title is the `Title:` field above it. */
+    body?: string;
     author?: string;
     reviewer?: string;
     url?: string;
@@ -157,7 +169,7 @@ export type NotifyEvent = Keyed & (
     action: 'opened' | 'assigned' | 'closed';
     number: number;
     title: string;
-    /** Тело задачи — рендерится в цитате вместе с заголовком. */
+    /** Тело задачи — цитата под полем `Title:`, отдельно от заголовка. */
     body?: string;
     author?: string;
     assignee?: string;

package/dist/render.js

@@ -41,12 +41,32 @@ export const clampMessage = (text, limit = 4000) => {
     // blockquote — с приходом цитаты для примечаний/деталей длинный detail режется
     // прямо посередине неё, и без этого тега Telegram отвечал бы 400 на незакрытую
     // цитату (regex `<blockquote[ >]` ловит и вариант с атрибутом `expandable`).
-    const tail = ['b', 'a', 'i', 'code', 'blockquote']
-        .filter((t) => {
-        const opened = (body.match(new RegExp(`<${t}[ >]`, 'g')) ?? []).length;
-        const closed = (body.match(new RegExp(`</${t}>`, 'g')) ?? []).length;
-        return opened > closed;
-    })
+    // `u` в списке с 2026-08-25: заголовок группы рисуется как `<i><u>…</u></i>`,
+    // и обрезанный посередине длинный заголовок оставлял `<u>` незакрытым.
+    // Telegram отвечает на такое 400 — то есть карточка пропадала целиком, а
+    // отправитель с `|| true` этого не замечал. Нашёл Codex; воспроизводится
+    // отчётом с именем группы в 5000 знаков.
+    //
+    // Порядок закрытия — обратный порядку ОТКРЫТИЯ, а не фиксированный список.
+    // Фиксированный список закрывал `<i><u>` как `</i></u>`: тегов поровну,
+    // счётчик сходится, вложенность нарушена, и Telegram отвечает тем же 400.
+    // Второй заход того же бага (25.08.2026), поэтому теперь порядок берётся из
+    // самого текста: последний открытый закрывается первым.
+    const open = [];
+    const tagRe = /<(\/?)(b|a|i|u|code|blockquote)[ >]/g;
+    for (let m = tagRe.exec(body); m !== null; m = tagRe.exec(body)) {
+        if (m[1] === '/') {
+            const at = open.lastIndexOf(m[2]);
+            if (at !== -1) {
+                open.splice(at, 1);
+            }
+        }
+        else {
+            open.push(m[2]);
+        }
+    }
+    const tail = open
+        .reverse()
         .map((t) => `</${t}>`)
         .join('');
     return `${body}${tail}\n…`;
@@ -79,14 +99,23 @@ const fieldLink = (label, url, text) => {
     if (text === undefined || text === null || text === '') {
         return null;
     }
-    return url ? `<b>${esc(cap(label))}:</b> <a href="${esc(url)}">${esc(text)}</a>` : field(label, text);
+    // `firstLine` here for the same reason `field` has it: the linked case used to
+    // skip it, so a multi-line value (arvent's two-line `commit`) became two-line
+    // LINK TEXT instead of one identifier.
+    return url
+        ? `<b>${esc(cap(label))}:</b> <a href="${esc(url)}">${esc(firstLine(text))}</a>`
+        : field(label, text);
 };
 /**
  * Поле-действие (`workflow:`): в отличие от `fieldLink`, без URL это НЕ
  * поле — прогону просто некуда вести, показывать голое слово «run» без
  * ссылки бессмысленнее, чем не показывать строку вовсе.
  */
-const fieldAction = (label, url, text) => url ? `<b>${esc(cap(label))}:</b> <a href="${esc(url)}">${esc(text ?? 'run')}</a>` : null;
+// Текст ссылки — имя того, куда она ведёт (имя workflow, имя прогона). Запасное
+// слово было «run»: существительное, которое ничего не называет — владелец читал
+// «Workflow: run» и не понимал, что это. «open» — глагол, он хотя бы честно
+// говорит, что это ссылка, а не название.
+const fieldAction = (label, url, text) => url ? `<b>${esc(cap(label))}:</b> <a href="${esc(url)}">${esc(text ?? 'open')}</a>` : null;
 /** Моноширинное поле — путь/команда для копирования, не ссылка. */
 const fieldCode = (label, value) => value ? `<b>${esc(cap(label))}:</b> <code>${esc(value)}</code>` : null;
 /** Заголовок группы: курсив + подчёркивание, без жирности, без двоеточия. */
@@ -120,56 +149,90 @@ const renderGroup = (g) => [
     ...g.items.map((it, i) => groupItem(it, i, false))
 ];
 /**
- * Цитата коммита/задачи: заголовок первой строкой (multiline title режется
- * до первой строки — subject не должен тащить в цитату собственное тело
- * под-коммита), тело — через пустую строку, если есть.
+ * ОДНО правило на все карточки, где есть и заголовок, и тело: заголовок —
+ * обычное поле `Title:`, тело — цитата, и в цитате больше ничего нет.
+ *
+ * Раньше заголовок клался В ЦИТАТУ вместе с телом, разделённые пустой
+ * строкой. Владелец нашёл, чем это плохо: заголовок — главное в карточке, то,
+ * ЧТО это, а лежал он серым текстом того же веса, что и описание, и отличить
+ * одно от другого можно было только по пустой строке. У PR без тела карточка
+ * вырождалась в одинокую серую цитату из одной строки.
+ *
+ * Заголовок режется до первой строки: многострочный subject коммита не должен
+ * затягивать в поле собственное тело.
  */
-const commitQuote = (title, body) => {
-    if (!title && !body) {
-        return null;
-    }
-    const text = [title ? firstLine(title) : undefined, body].filter(Boolean).join('\n\n');
-    return note(text);
-};
+const titleField = (title) => field('Title', title);
+const bodyQuote = (body) => body ? note(body) : null;
 // Значок = статус сообщения, не тип события. Ровно четыре на весь пакет —
 // закреплённая легенда в форумах обещает это владельцу как факт, не как
 // приближение. 🔴 сломалось, 🚨 инцидент, ✅ прошло, ℹ️ к сведению.
 const ICON = { red: '🔴', alarm: '🚨', ok: '✅', info: 'ℹ️' };
 /** Строка 2: значок вне жирного, `<b>Тип:</b> действие` — то же поле, не особый случай. */
-const typeLine = (icon, type, action) => `${icon} ${field(type, action)}`;
+// `action` объявлен строкой, но приходит и из `--json`, и из прямых вызовов на
+// JS, где типов нет. Пустое или отсутствующее значение давало строку `ℹ️ null`
+// прямо во второй строке карточки. Пустая строка честнее: поле просто исчезает.
+const typeLine = (icon, type, action) => {
+    // `field` возвращает null на пустом значении, а интерполяция null в шаблон
+    // печатает слово «null». Так вторая строка карточки становилась `ℹ️ null` —
+    // достижимо через `--json` и прямой вызов на JS, где типов нет.
+    const line = field(type, action);
+    return line === null ? `${icon} <b>${esc(cap(type))}</b>` : `${icon} ${line}`;
+};
+// `workflowUrl ?? url`: половина отправителей шлёт ссылку на прогон под именем
+// `--url` — это имя было в пакете раньше и осталось в вызовах. Рендер читал
+// только `workflowUrl`, поэтому красная карточка приходила БЕЗ ЕДИНОЙ ССЫЛКИ
+// на логи. Отвергать `--url` было бы честнее по имени и хуже по делу: намерение
+// однозначно, а карточка без ссылки бесполезна ровно тогда, когда нужна.
 const renderDeploy = (e) => {
     const icon = e.status === 'ok' ? ICON.ok : ICON.red;
     return join([
         typeLine(icon, 'Deploy', e.status),
         '',
         fieldLink('Commit', e.commitUrl, e.commit),
-        commitQuote(e.commitTitle, e.commitBody),
+        titleField(e.commitTitle),
+        bodyQuote(e.commitBody),
         field('Via', e.via),
         field('Target', e.target),
         field('Reason', e.note),
-        e.workflowUrl ? '' : null,
-        fieldAction('Workflow', e.workflowUrl, e.workflowName)
+        e.workflowUrl ?? e.url ? '' : null,
+        fieldAction('Workflow', e.workflowUrl ?? e.url, e.workflowName)
     ]);
 };
 const renderJob = (e) => {
     const icon = e.status === 'fail' || e.status === 'disabled' ? ICON.red : ICON.ok;
     const hasItems = (e.items ?? []).length > 0;
+    const disabledList = hasItems && e.status === 'disabled';
     return join([
         typeLine(icon, 'Job', e.status),
         '',
+        // The name is NOT the type line: line 2 is `Job: fail` by the format's own
+        // rule, so the name is its own field. Called `Task:` and not `Job:` because
+        // repeating the label of the line right above it reads as a mistake.
+        // Until now the name was dropped entirely — every caller passed it and the
+        // owner only ever saw it as the small grey instance tag.
+        field('Task', e.job),
         field('Reason', e.note),
         ...(e.stats ?? []).map(([label, value]) => field(label, value)),
         hasItems ? '' : null,
-        hasItems ? group('Disabled workflows') : null,
-        ...(hasItems && e.status === 'disabled' ? bullets(e.items, true) : hasItems ? bullets(e.items, false) : []),
-        e.workflowUrl ? '' : null,
-        fieldAction('Workflow', e.workflowUrl, e.workflowName)
+        // Heading ONLY for `disabled`. It used to print for any job carrying a
+        // list, so playhub's daily card of newly published games was headed
+        // "Disabled workflows".
+        disabledList ? group('Disabled workflows') : null,
+        ...(hasItems ? bullets(e.items, disabledList) : []),
+        e.workflowUrl ?? e.url ? '' : null,
+        fieldAction('Workflow', e.workflowUrl ?? e.url, e.workflowName)
     ]);
 };
 const renderReport = (e) => {
     if (e.groups && e.groups.length > 0) {
         const body = e.groups.flatMap((g, i) => (i === 0 ? renderGroup(g) : ['', ...renderGroup(g)]));
-        return join([typeLine(ICON.info, 'Report', e.period ? `${e.title} · ${e.period}` : e.title), '', ...body]);
+        return join([
+            typeLine(ICON.info, 'Report', e.period ? `${e.title} · ${e.period}` : e.title),
+            '',
+            ...body,
+            e.url ? '' : null,
+            fieldAction('Details', e.url, undefined)
+        ]);
     }
     const items = bullets(e.items, false);
     return join([
@@ -177,7 +240,11 @@ const renderReport = (e) => {
         '',
         ...(e.lines ?? []).map(([label, value]) => field(label, value)),
         items.length > 0 ? '' : null,
-        ...items
+        ...items,
+        // Обе аналитики шлют сюда ссылку на снимок дня в docs/. Рендер её не читал,
+        // и дневной отчёт приходил без единственного способа посмотреть подробности.
+        e.url ? '' : null,
+        fieldAction('Details', e.url, undefined)
     ]);
 };
 const renderCi = (e) => {
@@ -186,10 +253,12 @@ const renderCi = (e) => {
         typeLine(icon, 'CI', e.status),
         '',
         fieldLink('Commit', e.commitUrl, e.commit),
-        commitQuote(e.commitTitle, e.commitBody),
+        titleField(e.commitTitle),
+        bodyQuote(e.commitBody),
         field('Actor', e.actor),
-        e.workflowUrl ? '' : null,
-        fieldAction('Workflow', e.workflowUrl, e.workflowName)
+        field('Reason', e.note),
+        e.workflowUrl ?? e.url ? '' : null,
+        fieldAction('Workflow', e.workflowUrl ?? e.url, e.workflowName)
     ]);
 };
 // PR/Issue: значок теперь по статусу (четыре на пакет), не по действию —
@@ -213,39 +282,67 @@ const ISSUE_ICON = {
 const renderPr = (e) => join([
     typeLine(PR_ICON[e.action], 'PR', e.action),
     '',
-    fieldLink('Pr', e.url, `#${e.number}`),
-    note(e.title),
-    '',
+    // Идентификатор первым, заголовок под ним: так вещь читается «#118, вот
+    // такая», а не «вот такая, кстати #118» — и так её пишет сам GitHub.
+    fieldLink('Number', e.url, `#${e.number}`),
+    titleField(e.title),
+    bodyQuote(e.body),
+    // Без пустой строки перед автором: у задачи её нет, и одно и то же поле
+    // не должно стоять по-разному в двух соседних карточках. Пустая строка в
+    // этом формате означает «дальше указатель, куда пойти» — автор не он.
     field('Author', e.author),
     field('Reviewer', e.reviewer)
 ]);
 const renderIssue = (e) => join([
     typeLine(ISSUE_ICON[e.action], 'Issue', e.action),
     '',
-    fieldLink('Issue', e.url, `#${e.number}`),
-    commitQuote(e.title, e.body),
+    fieldLink('Number', e.url, `#${e.number}`),
+    titleField(e.title),
+    bodyQuote(e.body),
     field('Author', e.author),
     field('Assignee', e.assignee)
 ]);
 const renderIncident = (e) => join([
     typeLine(ICON.alarm, 'Incident', 'open'),
     '',
-    field('Reason', e.detail ?? e.title),
+    // `detail` is a diagnosis of several lines (vault greps three of them plus a
+    // log path). It used to go through `field`, which keeps only the first line,
+    // so every alarm this package ever sent arrived gutted. Same shape as a
+    // commit now: short label, full text quoted under it.
+    // Ярлык `Title`, а не `Reason`: у аварии заголовок — такой же заголовок,
+    // как у коммита и задачи, и называться в одной карточке он должен так же.
+    titleField(e.title),
+    e.detail && e.detail !== e.title ? note(e.detail) : null,
     e.logs || e.url ? '' : null,
     fieldCode('Logs', e.logs),
     fieldAction('Workflow', e.url, undefined)
 ]);
+// Раньше всё это склеивалось в одну строку `Reason:` через тире: «имя — no
+// reports — expected X, last seen Y». Каждая другая карточка кладёт факт на
+// свою строку с ярлыком, и владелец справедливо спросил, зачем тут отдельный
+// формат. Отдельного формата больше нет.
 const renderHeartbeatMiss = (e) => {
     const icon = e.recovered ? ICON.ok : ICON.red;
     const action = e.recovered ? 'ok' : 'miss';
-    const reason = e.note ??
-        (e.recovered
-            ? `${e.job} is reporting again${e.lastSeen ? ` — last run ${e.lastSeen}` : ''}`
-            : `${e.job} — no reports${e.expected ? ` — expected ${e.expected}` : ''}${e.lastSeen ? `, last seen ${e.lastSeen}` : ''}`);
-    return join([typeLine(icon, 'Heartbeat', action), '', field('Reason', reason)]);
+    return join([
+        typeLine(icon, 'Heartbeat', action),
+        '',
+        field('Task', e.job),
+        field('Reason', e.note),
+        field('Expected', e.expected),
+        field(e.recovered ? 'Last run' : 'Last seen', e.lastSeen)
+    ]);
 };
 // Подпись файла — та же карточка, но лимит Telegram у caption свой: 1024.
-const renderFile = (e) => join([typeLine(ICON.info, 'File', 'new'), '', field('Reason', e.note ?? e.title)]);
+const renderFile = (e) => join([
+    typeLine(ICON.info, 'File', 'new'),
+    '',
+    // Раньше здесь стояло `field('Title', e.note ?? e.title)`: подпись файла
+    // приходила под ярлыком заголовка, а сам заголовок из карточки исчезал.
+    // Один ярлык — один смысл: Title это title, Reason это note.
+    field('Title', e.title),
+    field('Reason', e.note)
+]);
 const RENDERERS = {
     deploy: renderDeploy,
     job: renderJob,
@@ -327,7 +424,7 @@ export const render = (e) => {
     // строка, и неизвестное значение роняло процесс через `renderer is not a
     // function`. Падать из-за уведомления нельзя.
     if (typeof renderer !== 'function') {
-        throw new Error(`неизвестный тип события: ${String(e.type)}`);
+        throw new Error(`unknown event type: ${String(e.type)}`);
     }
     const tags = tagsLine(e);
     // clampMessage может выйти за переданный limit на хвост закрывающих тегов и

package/dist/send.js

@@ -89,7 +89,7 @@ const attempt = async (token, target, text) => {
         // почему уведомления пропали, невозможно — а разбираться будет не
         // разработчик, а владелец.
         const detail = (await res.json().catch(() => null));
-        log(`HTTP ${res.status}: ${detail?.description ?? 'без описания'} — не повторяем, ошибка постоянная`);
+        log(`HTTP ${res.status}: ${detail?.description ?? 'no description'} — permanent error, not retried`);
         return { outcome: 'fail' };
     }
     catch (err) {
@@ -99,7 +99,7 @@ const attempt = async (token, target, text) => {
         // на таймауте останавливаемся и честно пишем 'failed': лишняя копия аварии
         // хуже, чем пропущенная строка в логе, а сообщение, скорее всего, ушло.
         if (err instanceof Error && err.name === 'TimeoutError') {
-            log('таймаут ответа — не повторяем: сообщение могло уже уйти');
+            log('answer timed out — not retried: the message may already be out');
             return { outcome: 'fail' };
         }
         // Сюда попадают отказы соединения (DNS, TLS, сеть недоступна) — запрос
@@ -109,7 +109,7 @@ const attempt = async (token, target, text) => {
         // отсутствие дублей невозможно без idempotency-key у Bot API (его нет).
         // Логика прежняя: дубль на редком reset — меньшее зло, чем потеря
         // сообщения на частом сетевом сбое.
-        log('fetch не прошёл, пробуем curl…');
+        log('fetch did not go through, trying curl…');
         const curl = sendViaCurl(token, target, text);
         return curl === 'retry' ? { outcome: 'retry', waitMs: 1000 } : { outcome: curl };
     }
@@ -130,14 +130,14 @@ const sendOne = async (token, target, text) => {
         }
         waitMs = result.waitMs;
     }
-    log('исчерпаны попытки отправки');
+    log('out of send attempts');
     return 'failed';
 };
 /** Общий хвост для `notify` и `sendReport`: токен, цели, последовательная отправка. */
 const deliver = async (where, text) => {
     const token = process.env.OPS_BOT_TOKEN?.trim();
     if (!token) {
-        log('нет OPS_BOT_TOKEN — сообщение не отправлено');
+        log('skipped: no OPS_BOT_TOKEN, the message was not sent');
         return 'skipped';
     }
     // Токен interpolируется в URL и в curl-конфиг (`url = "...bot${token}..."`).
@@ -145,7 +145,7 @@ const deliver = async (where, text) => {
     // строки/`?` сломало бы разбор (инъекция директивы curl или query-хвост).
     // Это требует покорёженного секрета, но проверка копеечная.
     if (!/^\d+:[A-Za-z0-9_-]+$/.test(token)) {
-        log('OPS_BOT_TOKEN не похож на токен Telegram — отправка отменена');
+        log('failed: OPS_BOT_TOKEN does not look like a Telegram token, send cancelled');
         return 'skipped';
     }
     if (where.length === 0) {
@@ -196,27 +196,27 @@ const sendFileOnce = async (token, target, e, caption) => {
             return { outcome: 'retry', waitMs: 1000 };
         }
         const detail = (await res.json().catch(() => null));
-        log(`HTTP ${res.status}: ${detail?.description ?? 'без описания'} — не повторяем, ошибка постоянная`);
+        log(`HTTP ${res.status}: ${detail?.description ?? 'no description'} — permanent error, not retried`);
         return { outcome: 'fail' };
     }
     catch (err) {
         if (err instanceof Error && err.name === 'TimeoutError') {
-            log('таймаут ответа — не повторяем: файл мог уже уйти');
+            log('answer timed out — not retried: the file may already be out');
             return { outcome: 'fail' };
         }
         // Файл не читается (нет на диске, нет прав) — постоянная ошибка.
         if (err instanceof Error && 'code' in err) {
-            log(`файл не отправлен: ${err.message}`);
+            log(`failed to send the file: ${err.message}`);
             return { outcome: 'fail' };
         }
-        log(`сеть не пустила файл: ${err instanceof Error ? err.message : String(err)}`);
+        log(`the network refused the file: ${err instanceof Error ? err.message : String(err)}`);
         return { outcome: 'retry', waitMs: 1000 };
     }
 };
 const sendFile = async (e) => {
     const token = process.env.OPS_BOT_TOKEN?.trim();
     if (!token || !/^\d+:[A-Za-z0-9_-]+$/.test(token)) {
-        log('нет валидного OPS_BOT_TOKEN — файл не отправлен');
+        log('skipped: no valid OPS_BOT_TOKEN, the file was not sent');
         return 'skipped';
     }
     const where = targets(e);
@@ -261,13 +261,13 @@ const sendFile = async (e) => {
 const reportLostProject = async (project, kind) => {
     // Локальный лог называет и допустимые написания — это единственная
     // диагностика, доступная на машине, где случилась опечатка.
-    log(`неизвестный проект «${String(project)}» — известны: ${Object.keys(ROUTES).join(', ')}`);
+    log(`unknown project "${String(project)}" — known: ${Object.keys(ROUTES).join(', ')}`);
     const lost = {
         type: 'job',
         project: 'mac-config',
-        job: 'notify: событие потеряно',
+        job: 'notify: an event was lost',
         status: 'fail',
-        note: `проект «${String(project)}» не в ROUTES — событие «${kind}» никуда не доставлено`,
+        note: `project "${String(project)}" is not in ROUTES — event "${kind}" went nowhere`,
         key: 'notify-unknown-project'
     };
     await deliver(targets(lost), render(lost)).catch(() => undefined);

package/package.json

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