@mikitasazan/notify 1.2.1 → 1.4.0

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,6 +21,8 @@
  *   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}`);
@@ -39,11 +41,11 @@ if (command === 'setup') {
 const flags = new Map();
 const parseErrors = [];
 /** Флаги без значения. Всё остальное обязано его иметь. */
-const BOOLEAN_FLAGS = new Set(['json']);
+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: "${arg}"`);
         continue;
     }
     // Форма `--key=value` обязательна для значений, начинающихся с `--`
@@ -65,13 +67,18 @@ for (let i = 1; i < args.length; i++) {
     // ТЕРЯЛОСЬ ВСЁ сообщение, а `--status` без значения рисовал 🔴 на
     // успешном деплое. Теперь это явная ошибка разбора.
     if (next === undefined || next.startsWith('--')) {
-        parseErrors.push(`флаг --${key} без значения`);
+        parseErrors.push(`flag --${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 --${key}`);
+    }
+}
 // Число с явной ошибкой разбора, иначе рендер рисовал «PR #NaN».
 const num = (key) => {
     const raw = one(key);
@@ -114,7 +121,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 "${raw ?? ''}" (${Object.keys(PR_ALIASES).join(', ')})`);
         return 'opened';
     }
     return hit;
@@ -122,7 +129,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;
@@ -139,6 +146,15 @@ const status = () => {
     const raw = (one('status') ?? '').toLowerCase();
     return raw === 'ok' || raw === 'success' || raw === 'passed' || raw === '0' ? 'ok' : 'fail';
 };
+// `job` — единственный тип с третьим состоянием (`disabled`): задача не
+// провалилась сама, её выключил кто-то извне (GitHub Actions без минут).
+const jobStatus = () => {
+    const raw = (one('status') ?? '').toLowerCase();
+    if (raw === 'disabled') {
+        return 'disabled';
+    }
+    return raw === 'ok' || raw === 'success' || raw === 'passed' || raw === '0' ? 'ok' : 'fail';
+};
 let event;
 if (flags.has('json')) {
     try {
@@ -148,7 +164,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: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
 else {
@@ -160,6 +178,10 @@ else {
                 status: status(),
                 commit: one('commit'),
                 commitUrl: one('commit-url'),
+                commitTitle: one('commit-title'),
+                commitBody: one('commit-body'),
+                workflowUrl: one('workflow-url'),
+                workflowName: one('workflow-name'),
                 url: one('url'),
                 target: one('target'),
                 via: one('via'),
@@ -171,10 +193,12 @@ else {
                 type: 'job',
                 project: project(),
                 job: one('job') ?? '(без имени)',
-                status: status(),
+                status: jobStatus(),
                 stats: pairs('stat'),
                 items: items(),
                 note: one('note'),
+                workflowUrl: one('workflow-url'),
+                workflowName: one('workflow-name'),
                 url: one('url')
             };
             break;
@@ -196,7 +220,13 @@ else {
                 status: status(),
                 branch: one('branch'),
                 commit: one('commit'),
+                commitUrl: one('commit-url'),
+                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')
             };
             break;
@@ -207,6 +237,7 @@ else {
                 action: prAction(one('action')),
                 number: num('number'),
                 title: one('title') ?? '(без заголовка)',
+                body: one('body'),
                 author: one('author'),
                 reviewer: one('reviewer'),
                 url: one('url')
@@ -219,6 +250,7 @@ else {
                 action: issueAction(one('action')),
                 number: num('number'),
                 title: one('title') ?? '(без заголовка)',
+                body: one('body'),
                 author: one('author'),
                 assignee: one('assignee'),
                 url: one('url')
@@ -230,6 +262,7 @@ else {
                 project: project(),
                 title: one('title') ?? '(без заголовка)',
                 detail: one('detail'),
+                logs: one('logs'),
                 url: one('url')
             };
             break;
@@ -239,7 +272,9 @@ else {
                 project: project(),
                 job: one('job') ?? '(без имени)',
                 lastSeen: one('last-seen'),
-                expected: one('expected')
+                expected: one('expected'),
+                recovered: flags.has('recovered'),
+                note: one('note')
             };
             break;
         case 'file': {
@@ -258,7 +293,10 @@ else {
             break;
         }
         default:
-            log(`неизвестный тип события: ${command ?? '(не указан)'}`);
+            // В parseErrors, а не просто в лог: иначе неизвестный тип уходил в
+            // тишину — событие не собиралось, ошибок разбора не было, и CLI выходил
+            // нулём, ничего не отправив и ничего об этом не сказав.
+            parseErrors.push(`unknown event type: ${command ?? '(none given)'}`);
     }
 }
 // --key применим к любому типу — одна точка вместо строки в каждом case
@@ -273,7 +311,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) {
@@ -284,7 +341,9 @@ if (event) {
         log(await notify(event));
     }
     catch (err) {
-        log(`не отправлено: ${err instanceof Error ? err.message : String(err)}`);
+        // Слово `failed` — контракт, тот же, что у ошибки разбора выше. Без него
+        // исключение при отправке читалось сторожами как «ничего не случилось».
+        log(`failed: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
 process.exit(0);

package/dist/events.d.ts

@@ -29,9 +29,16 @@ type Keyed = {
  * Позиция списка внутри сообщения: задача из дайджеста, упавшая проверка,
  * замечание. `url` необязателен — тогда рендерится просто строкой.
  */
+/**
+ * `label` — необязательный жирный префикс перед `text` (`#243 (overdue)`,
+ * `#287`) для позиций внутри именованных групп отчёта. Без `label` позиция
+ * рендерится как обычная нумерованная/маркированная строка — так уже
+ * работают дайджест-задачи и список выключенных workflow.
+ */
 export type Item = {
     text: string;
     url?: string;
+    label?: string;
 };
 export type NotifyEvent = Keyed & (
 /** Выкатка кода на сервер. */
@@ -42,6 +49,13 @@ export type NotifyEvent = Keyed & (
     commit?: string;
     /** Ссылка на коммит — строка «коммит» становится кликабельной. */
     commitUrl?: string;
+    /** Заголовок коммита — рендерится рядом с телом в цитате. */
+    commitTitle?: string;
+    /** Тело коммита, если есть — та же цитата, что и заголовок. */
+    commitBody?: string;
+    workflowUrl?: string;
+    /** Название прогона для видимого текста ссылки (по умолчанию — просто "run"). */
+    workflowName?: string;
     url?: string;
     /**
      * Куда выкатили. Заполнять ТОЛЬКО когда окружений больше одного: у сайтов
@@ -64,11 +78,20 @@ export type NotifyEvent = Keyed & (
     type: 'job';
     project: Project;
     job: string;
-    status: 'ok' | 'fail';
+    /** `disabled` — задача выключена извне (например GitHub Actions кончил бесплатные минуты), не провалилась сама. */
+    status: 'ok' | 'fail' | 'disabled';
     stats?: Array<[label: string, value: string | number]>;
-    /** Детали: что именно упало, замечания прогона. */
+    /** Детали: что именно упало, замечания прогона; у `disabled` — список выключенных процессов (каждый со своей ссылкой). */
     items?: Item[];
     note?: string;
+    workflowUrl?: string;
+    /** Название прогона для видимого текста ссылки (по умолчанию — просто "run"). */
+    workflowName?: string;
+    /**
+     * Запасное имя для ссылки на прогон: половина отправителей шлёт её как
+     * `--url`. Рендер берёт `workflowUrl ?? url`, так что оба имени работают.
+     * В новых вызовах предпочитай `workflowUrl` — оно говорит, куда ведёт.
+     */
     url?: string;
 }
 /** Сводка с цифрами: дневной отчёт, дайджест аналитики. */
@@ -77,13 +100,24 @@ export type NotifyEvent = Keyed & (
     project: Project;
     title: string;
     period?: string;
-    lines: Array<[label: string, value: string | number]>;
+    /** Пусто/не передано, когда используются `groups` — два вида отчёта не смешиваются в одном событии. */
+    lines?: Array<[label: string, value: string | number]>;
     /**
      * Список позиций со ссылками — для дайджестов задач, где ценность в
      * самих названиях, а не в цифре. Рендерятся отдельным блоком после
      * `lines`.
      */
     items?: Item[];
+    /**
+     * Именованные группы (доска задач: Ready/In Progress/Not on the
+     * board; аналитика: Metrics/Links) — каждая со своим заголовком и
+     * списком позиций. Заменяет `lines`/`items`, когда задан: разные
+     * отчёты используют либо плоский вид, либо группы, не оба разом.
+     */
+    groups?: Array<{
+        name: string;
+        items: Item[];
+    }>;
     url?: string;
 }
 /** Итог CI на основной ветке. */
@@ -93,7 +127,22 @@ export type NotifyEvent = Keyed & (
     status: 'ok' | 'fail';
     branch?: string;
     commit?: string;
+    /** Ссылка на коммит — хэш становится кликабельным. */
+    commitUrl?: string;
+    /** Заголовок коммита (subject) — отдельное поле `Title:`, не цитата. */
+    commitTitle?: string;
+    /** Тело коммита (после subject) — та же цитата, что и заголовок. */
+    commitBody?: string;
     actor?: string;
+    /**
+     * 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`, который у CI не используется. */
+    workflowUrl?: string;
+    /** Название прогона для видимого текста ссылки (по умолчанию — просто "run"). */
+    workflowName?: string;
     url?: string;
 }
 /**
@@ -107,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;
@@ -118,6 +169,8 @@ export type NotifyEvent = Keyed & (
     action: 'opened' | 'assigned' | 'closed';
     number: number;
     title: string;
+    /** Тело задачи — цитата под полем `Title:`, отдельно от заголовка. */
+    body?: string;
     author?: string;
     assignee?: string;
     url?: string;
@@ -128,6 +181,8 @@ export type NotifyEvent = Keyed & (
     project: Project;
     title: string;
     detail?: string;
+    /** Локальный путь к логам (не URL — рендерится моноширинным, для копирования, не для клика). */
+    logs?: string;
     url?: string;
 }
 /** Задача не отметилась вовремя — сторож молчания (heartbeat). */
@@ -137,6 +192,10 @@ export type NotifyEvent = Keyed & (
     job: string;
     lastSeen?: string;
     expected?: string;
+    /** Задача снова отчиталась — тот же тип, зелёная карточка вместо красной, ключ (для сверки) не меняется. */
+    recovered?: boolean;
+    /** Готовое предложение-причина; без него собирается из lastSeen/expected. */
+    note?: string;
 }
 /**
  * Файл-вложение (sendDocument) с подписью-карточкой. Появился, когда

package/dist/events.js

@@ -11,10 +11,17 @@
  */
 /** Красное = со звуком. Всё остальное — тихо. (Отдельной темы «инциденты» больше нет — авария видна в ленте проекта.) */
 export const severity = (e) => {
-    if (e.type === 'incident' || e.type === 'heartbeat_miss') {
+    if (e.type === 'heartbeat_miss') {
+        return e.recovered ? 'info' : 'error';
+    }
+    if (e.type === 'incident') {
         return 'error';
     }
-    if ('status' in e && e.status === 'fail') {
+    // `disabled` рисуется красным (`ICON.red` в render.ts) ровно как `fail` —
+    // задача не работает, что бы ни было тому причиной. Молчаливая отправка
+    // красной карточки без звука хуже отсутствия карточки: авария выглядит
+    // аварией, но не будит (тот же довод, что уже был у `fail`).
+    if ('status' in e && (e.status === 'fail' || e.status === 'disabled')) {
         return 'error';
     }
     return 'info';

package/dist/render.d.ts

@@ -1,14 +1,23 @@
 /**
- * Один рендерер на тип события, все по одному каркасу:
+ * Один рендерер на тип события, все по одному каркасу — утверждён
+ * владельцем 20.08.2026 после ~15 живых раундов в тестовом форуме:
  *
- *   эмодзи Заголовок · проект
- *   ключ: значение
- *   ключ: значение
- *   <a href="…">Ссылка</a>
+ *   #тип #экземпляр
+ *   значок <b>Тип:</b> действие
  *
- * Проект указывается ВСЕГДА, даже в теме самого проекта — в теме
- * `🔴 incidents` сообщения четырёх проектов лежат вперемешку, и формат
- * должен быть один и тот же независимо от того, куда сообщение попало.
+ *   <b>Ярлык:</b> значение
+ *   <blockquote>цитата чужого текста — тело коммита, тело задачи</blockquote>
+ *
+ *   <i><u>Группа</u></i>
+ *   <b>#N (overdue):</b> <a>заголовок</a>
+ *
+ *   <b>Ярлык:</b> значение   ← действия/направления
+ *
+ * Три уровня начертания, никогда не смешиваются: поле — жирный ярлык с
+ * большой буквы + обычное значение; группа — курсив+подчёркивание, без
+ * жирности и без двоеточия; строка 2 (тип) — тот же закон поля. Пустая
+ * строка разделяет БЛОКИ ПО СМЫСЛУ (шапка / суть / действия), не механически
+ * после каждой строки.
  */
 import type { NotifyEvent } from './events.ts';
 /** Экранируется ВСЁ, что пришло снаружи — теги ставит только шаблон. */
@@ -27,11 +36,20 @@ export declare const esc: (v: unknown) => string;
  *    повторяем — сообщение исчезало совсем.
  */
 export declare const clampMessage: (text: string, limit?: number) => string;
+/**
+ * Экземпляр-тег: что именно это конкретное событие (ветка, окружение,
+ * задача, номер) — по нему разборщик сверяет 🔴 с более поздней зелёной
+ * карточкой ТОГО ЖЕ экземпляра. Явный `key` побеждает всегда; без него —
+ * выводится из самых стабильных полей типа (ветка/окружение важнее заголовка,
+ * потому что заголовок у регулярной задачи не меняется, а у отчёта как раз
+ * заголовок и есть единственное стабильное поле).
+ */
 export declare const eventKey: (e: NotifyEvent) => string;
 /**
  * Рендерит событие в готовый HTML-текст, обрезанный под лимит Telegram.
- * Ключ добавляется ПОСЛЕ обрезки, с зарезервированным местом: обрезанная
- * карточка без ключа была бы невидима разборщику — ровно на самых длинных,
- * то есть самых важных сообщениях.
+ * Теги — ПЕРВАЯ строка, добавляются до обрезки (не после, как раньше): они
+ * несут и человеческий фильтр, и машинный ключ разборщика — обрезанная
+ * карточка без них была бы не только некликабельной, но и невидимой
+ * разборщику ровно на самых длинных, то есть самых важных сообщениях.
  */
 export declare const render: (e: NotifyEvent) => string;

package/dist/render.js

@@ -1,3 +1,5 @@
+/** Первая буква — заглавная, остальное как есть (ga4/GitHub остаются собой). */
+const cap = (s) => (s.length > 0 ? s.charAt(0).toUpperCase() + s.slice(1) : s);
 /** Экранируется ВСЁ, что пришло снаружи — теги ставит только шаблон. */
 export const esc = (v) => String(v ?? '')
     .replace(/&/g, '&')
@@ -39,7 +41,12 @@ export const clampMessage = (text, limit = 4000) => {
     // blockquote — с приходом цитаты для примечаний/деталей длинный detail режется
     // прямо посередине неё, и без этого тега Telegram отвечал бы 400 на незакрытую
     // цитату (regex `<blockquote[ >]` ловит и вариант с атрибутом `expandable`).
-    const tail = ['b', 'a', 'i', 'code', 'blockquote']
+    // `u` в списке с 2026-08-25: заголовок группы рисуется как `<i><u>…</u></i>`,
+    // и обрезанный посередине длинный заголовок оставлял `<u>` незакрытым.
+    // Telegram отвечает на такое 400 — то есть карточка пропадала целиком, а
+    // отправитель с `|| true` этого не замечал. Нашёл Codex; воспроизводится
+    // отчётом с именем группы в 5000 знаков.
+    const tail = ['b', 'a', 'i', 'u', 'code', 'blockquote']
         .filter((t) => {
         const opened = (body.match(new RegExp(`<${t}[ >]`, 'g')) ?? []).length;
         const closed = (body.match(new RegExp(`</${t}>`, 'g')) ?? []).length;
@@ -49,12 +56,6 @@ export const clampMessage = (text, limit = 4000) => {
         .join('');
     return `${body}${tail}\n…`;
 };
-const header = (icon, title, project) => `${icon} <b>${esc(title)}</b> · ${esc(project)}`;
-// Тире, не жирное значение: сплошной жирный текст в первой версии карточки
-// читался как крик (жалоба владельца 18.08). Иконка-лид уже держит внимание
-// на заголовке, факты идут построчно и без выделения — глаз сам находит
-// цифру рядом с меткой.
-//
 // Только первая строка: однострочное поле по контракту (коммит, ветка,
 // автор, статистика), а не место для абзаца. Живой случай (18.08): CI-карточка
 // понесла ПОЛНОЕ тело коммита с историей под-коммитов через `--commit` и вместо
@@ -67,7 +68,51 @@ const firstLine = (value) => {
     }
     return `${value.split('\n')[0]}…`;
 };
-const kv = (label, value) => value === undefined || value === '' ? null : `${esc(label)} — ${esc(firstLine(value))}`;
+/**
+ * Поле: `<b>Ярлык:</b> значение` — жирный ярлык с большой буквы, значение
+ * обычным. `null` отбрасывается наравне с `undefined`/`''` — источники поля
+ * это JSON со stdin (`--json`) и объекты с сервера, где отсутствующее
+ * значение сериализуется как `null`, а не как пропущенный ключ.
+ */
+const field = (label, value) => value === undefined || value === null || value === '' ? null : `<b>${esc(cap(label))}:</b> ${esc(firstLine(value))}`;
+/**
+ * Поле-идентификатор (`commit:`/`pr:`/`issue:`): значение — ссылка, если
+ * она есть, иначе обычный текст того же поля — идентификатор не должен
+ * пропадать целиком только потому, что вызывающий не передал url.
+ */
+const fieldLink = (label, url, text) => {
+    if (text === undefined || text === null || text === '') {
+        return null;
+    }
+    // `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» без
+ * ссылки бессмысленнее, чем не показывать строку вовсе.
+ */
+// Текст ссылки — имя того, куда она ведёт (имя 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;
+/** Заголовок группы: курсив + подчёркивание, без жирности, без двоеточия. */
+const group = (name) => `<i><u>${esc(cap(name))}</u></i>`;
+/** Позиция внутри группы: `<b>label:</b> <a>text</a>` — либо простая маркированная/нумерованная строка без label. */
+const groupItem = (it, index, numbered) => {
+    const linked = it.url ? `<a href="${esc(it.url)}">${esc(it.text)}</a>` : esc(it.text);
+    if (it.label) {
+        return `<b>${esc(it.label)}:</b> ${linked}`;
+    }
+    return numbered ? `${index + 1}. ${linked}` : `• ${linked}`;
+};
 // Длинное пояснение (примечание, детали инцидента) — цитатой: у Telegram это
 // полоска слева и лёгкий отступ, читается как «подробности», а не как часть
 // заголовка. Длиннее ~400 знаков — цитата сворачивается сама (`expandable`,
@@ -80,109 +125,209 @@ const note = (text) => {
     const body = esc(text);
     return body.length > EXPAND_AT ? `<blockquote expandable>${body}</blockquote>` : `<blockquote>${body}</blockquote>`;
 };
-const link = (url, label) => url ? `<a href="${esc(url)}">${esc(label)}</a>` : null;
 const join = (parts) => parts.filter((p) => p !== null).join('\n');
-/** Список позиций — общий для `job` и `report`, чтобы они не разъехались. */
-const bullets = (items) => (items ?? []).map((it) => (it.url ? `• <a href="${esc(it.url)}">${esc(it.text)}</a>` : `• ${esc(it.text)}`));
+/** Плоский список позиций (без ярлыков) — job/report без групп. */
+const bullets = (items, numbered) => (items ?? []).map((it, i) => groupItem(it, i, numbered));
+/** Именованная группа целиком: заголовок + позиции, разделены строкой пустоты внутри вызова через join. */
+const renderGroup = (g) => [
+    group(g.name),
+    ...g.items.map((it, i) => groupItem(it, i, false))
+];
+/**
+ * ОДНО правило на все карточки, где есть и заголовок, и тело: заголовок —
+ * обычное поле `Title:`, тело — цитата, и в цитате больше ничего нет.
+ *
+ * Раньше заголовок клался В ЦИТАТУ вместе с телом, разделённые пустой
+ * строкой. Владелец нашёл, чем это плохо: заголовок — главное в карточке, то,
+ * ЧТО это, а лежал он серым текстом того же веса, что и описание, и отличить
+ * одно от другого можно было только по пустой строке. У PR без тела карточка
+ * вырождалась в одинокую серую цитату из одной строки.
+ *
+ * Заголовок режется до первой строки: многострочный subject коммита не должен
+ * затягивать в поле собственное тело.
+ */
+const titleField = (title) => field('Title', title);
+const bodyQuote = (body) => body ? note(body) : null;
+// Значок = статус сообщения, не тип события. Ровно четыре на весь пакет —
+// закреплённая легенда в форумах обещает это владельцу как факт, не как
+// приближение. 🔴 сломалось, 🚨 инцидент, ✅ прошло, ℹ️ к сведению.
+const ICON = { red: '🔴', alarm: '🚨', ok: '✅', info: 'ℹ️' };
+/** Строка 2: значок вне жирного, `<b>Тип:</b> действие` — то же поле, не особый случай. */
+// `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' ? '✅' : '🔴';
-    const title = e.status === 'ok' ? 'Деплой завершён' : 'Деплой упал';
-    // Коммит со ссылкой — кликабельная строка вместо голого текста; жалоба
-    // владельца на некликабельные дайджесты распространяется и сюда.
-    const commitLine = e.commit
-        ? e.commitUrl
-            ? `коммит: <a href="${esc(e.commitUrl)}"><b>${esc(firstLine(e.commit))}</b></a>`
-            : kv('коммит', e.commit)
-        : null;
+    const icon = e.status === 'ok' ? ICON.ok : ICON.red;
     return join([
-        header(icon, title, e.project),
-        commitLine,
-        kv('откуда', e.via),
-        kv('куда', e.target),
-        note(e.note),
-        link(e.url, 'Открыть логи')
+        typeLine(icon, 'Deploy', e.status),
+        '',
+        fieldLink('Commit', e.commitUrl, e.commit),
+        titleField(e.commitTitle),
+        bodyQuote(e.commitBody),
+        field('Via', e.via),
+        field('Target', e.target),
+        field('Reason', e.note),
+        e.workflowUrl ?? e.url ? '' : null,
+        fieldAction('Workflow', e.workflowUrl ?? e.url, e.workflowName)
     ]);
 };
 const renderJob = (e) => {
-    const icon = e.status === 'ok' ? '✅' : '🔴';
-    const items = bullets(e.items);
+    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([
-        header(icon, e.job, e.project),
-        ...(e.stats ?? []).map(([label, value]) => kv(label, value)),
-        items.length > 0 ? '' : null,
-        ...items,
-        note(e.note),
-        link(e.url, 'Подробнее')
+        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,
+        // 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) => {
-    const items = bullets(e.items);
+    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,
+            e.url ? '' : null,
+            fieldAction('Details', e.url, undefined)
+        ]);
+    }
+    const items = bullets(e.items, false);
     return join([
-        header('📊', e.title, e.project),
-        e.period ? esc(e.period) : null,
-        e.period ? '' : null,
-        ...e.lines.map(([label, value]) => kv(label, value)),
+        typeLine(ICON.info, 'Report', e.period ? `${e.title} · ${e.period}` : e.title),
+        '',
+        ...(e.lines ?? []).map(([label, value]) => field(label, value)),
         items.length > 0 ? '' : null,
         ...items,
-        link(e.url, 'Открыть отчёт')
+        // Обе аналитики шлют сюда ссылку на снимок дня в docs/. Рендер её не читал,
+        // и дневной отчёт приходил без единственного способа посмотреть подробности.
+        e.url ? '' : null,
+        fieldAction('Details', e.url, undefined)
     ]);
 };
 const renderCi = (e) => {
-    const icon = e.status === 'ok' ? '✅' : '🔴';
-    const title = e.status === 'ok' ? 'CI зелёный' : 'CI упал';
+    const icon = e.status === 'ok' ? ICON.ok : ICON.red;
     return join([
-        header(icon, title, e.project),
-        kv('ветка', e.branch),
-        kv('коммит', e.commit),
-        kv('автор', e.actor),
-        link(e.url, 'Открыть логи')
+        typeLine(icon, 'CI', e.status),
+        '',
+        fieldLink('Commit', e.commitUrl, e.commit),
+        titleField(e.commitTitle),
+        bodyQuote(e.commitBody),
+        field('Actor', e.actor),
+        field('Reason', e.note),
+        e.workflowUrl ?? e.url ? '' : null,
+        fieldAction('Workflow', e.workflowUrl ?? e.url, e.workflowName)
     ]);
 };
-// Значок у каждого вида свой: в ленте Ops событие узнаётся по нему до чтения
-// текста. Дублировать значок между видами нельзя — легенда закреплена в теме
-// и обещает однозначность.
-const PR_TITLES = {
-    opened: { icon: '🔀', verb: 'открыт' },
-    ready_for_review: { icon: '📤', verb: 'готов к ревью' },
-    review_requested: { icon: '👁', verb: 'ждёт ревью' },
-    approved: { icon: '👍', verb: 'ревью пройдено' },
-    changes_requested: { icon: '📝', verb: 'запрошены правки' },
-    merged: { icon: '✅', verb: 'смёржен' },
-    closed: { icon: '⛔', verb: 'закрыт без слияния' }
-};
-const ISSUE_TITLES = {
-    opened: { icon: '🆕', verb: 'заведена' },
-    assigned: { icon: '🙋', verb: 'взята в работу' },
-    closed: { icon: '☑️', verb: 'закрыта' }
+// PR/Issue: значок теперь по статусу (четыре на пакет), не по действию —
+// `merged`/`approved` = успех, `changes_requested` = требует внимания,
+// остальное = к сведению. Слово действия само по себе уже говорит, что
+// произошло (`opened`, `ready_for_review` и т.д.), значок дублировать не должен.
+const PR_ICON = {
+    opened: ICON.info,
+    ready_for_review: ICON.info,
+    review_requested: ICON.info,
+    approved: ICON.ok,
+    changes_requested: ICON.red,
+    merged: ICON.ok,
+    closed: ICON.info
 };
-const renderPr = (e) => {
-    const { icon, verb } = PR_TITLES[e.action];
-    return join([
-        header(icon, `PR #${e.number} ${verb}`, e.project),
-        esc(e.title),
-        kv('автор', e.author),
-        kv('ревьюер', e.reviewer),
-        link(e.url, 'Открыть PR')
-    ]);
+const ISSUE_ICON = {
+    opened: ICON.info,
+    assigned: ICON.info,
+    closed: ICON.ok
 };
-const renderIssue = (e) => {
-    const { icon, verb } = ISSUE_TITLES[e.action];
+const renderPr = (e) => join([
+    typeLine(PR_ICON[e.action], 'PR', e.action),
+    '',
+    // Идентификатор первым, заголовок под ним: так вещь читается «#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('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'),
+    '',
+    // `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';
     return join([
-        header(icon, `Задача #${e.number} ${verb}`, e.project),
-        esc(e.title),
-        kv('автор', e.author),
-        kv('исполнитель', e.assignee),
-        link(e.url, 'Открыть задачу')
+        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)
     ]);
 };
-const renderIncident = (e) => join([header('🚨', 'Инцидент', e.project), esc(e.title), note(e.detail), link(e.url, 'Подробнее')]);
-const renderHeartbeatMiss = (e) => join([
-    header('🔴', `Не отметилась: ${e.job}`, e.project),
-    kv('последний раз', e.lastSeen),
-    kv('ожидалось', e.expected)
-]);
 // Подпись файла — та же карточка, но лимит Telegram у caption свой: 1024.
-const renderFile = (e) => join([header('📄', e.title, e.project), note(e.note)]);
+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,
@@ -194,28 +339,47 @@ const RENDERERS = {
     heartbeat_miss: renderHeartbeatMiss,
     file: renderFile
 };
-/**
- * Ключ задачи — последняя строка карточки: `#ключ` курсивом в <code>. Без
- * названия проекта: `targets()` никогда не шлёт карточку в чужой форум,
- * проект и так на виду в заголовке («· mac-config»), а дублирующий префикс
- * только растягивал тег на лишнюю строку в узком экране телефона (жалоба
- * владельца 18.08). Явный `key` побеждает; выведенный строится из заголовка
- * и наследует хрупкость формулировки — регулярные отправители передают явный.
- * Ключ переживает MTProto-чтение (простой текст, не разметка), по нему
- * разборщик сверяет 🔴 с более поздней успешной карточкой той же задачи —
- * внутри чата одного проекта, где ключ и так уникален.
- */
+// Тег наверху карточки И машинный ключ разборщика — ОДНО И ТО ЖЕ значение
+// (решение владельца 20.08.2026): раньше это были два разных представления
+// одного факта (снизу — дефисный `#ci-arvent`, сверху — теги вручную), и это
+// читалось как дублирование. Разделитель — подчёркивание, не дефис: дефис
+// разрывает Telegram-хэштег на середине слова (`#mac-config` линкуется
+// только как `#mac`), а тег ДОЛЖЕН быть кликабельным — это и есть фильтр
+// «показать всю историю этого экземпляра», которым владелец пользуется вживую.
 const slug = (raw) => raw
     .toLowerCase()
-    .replace(/[^\p{L}\p{N}]+/gu, '-')
-    .replace(/^-+|-+$/g, '')
-    // Ключ — идентификатор, не пересказ: без среза тег из длинного заголовка
-    // съедал бюджет caption до отрицательного, и slice с минусом возвращал
-    // почти весь текст — Telegram отвечал постоянным 400, файл терялся.
+    .replace(/[^\p{L}\p{N}]+/gu, '_')
+    .replace(/^_+|_+$/g, '')
     .slice(0, 60);
+// Тип-тег наверху — не буквальный `e.type`: `heartbeat_miss` читался бы как
+// `#heartbeat_miss`, а видимый тип у владельца всегда просто `#heartbeat`
+// (зелёная и красная карточки одного вида — один и тот же тип-тег).
+const TYPE_TAG = {
+    deploy: 'deploy',
+    job: 'job',
+    report: 'report',
+    ci: 'ci',
+    pr: 'pr',
+    issue: 'issue',
+    incident: 'incident',
+    heartbeat_miss: 'heartbeat',
+    file: 'file'
+};
+/**
+ * Экземпляр-тег: что именно это конкретное событие (ветка, окружение,
+ * задача, номер) — по нему разборщик сверяет 🔴 с более поздней зелёной
+ * карточкой ТОГО ЖЕ экземпляра. Явный `key` побеждает всегда; без него —
+ * выводится из самых стабильных полей типа (ветка/окружение важнее заголовка,
+ * потому что заголовок у регулярной задачи не меняется, а у отчёта как раз
+ * заголовок и есть единственное стабильное поле).
+ */
 export const eventKey = (e) => {
     const fallback = () => {
         switch (e.type) {
+            case 'ci':
+                return slug(e.branch || e.project);
+            case 'deploy':
+                return slug(e.target || e.project);
             case 'job':
             case 'heartbeat_miss':
                 return slug(e.job);
@@ -224,21 +388,20 @@ export const eventKey = (e) => {
             case 'file':
                 return slug(e.title);
             case 'pr':
-                return `pr-${e.number}`;
+                return `p${e.number}`;
             case 'issue':
-                return `issue-${e.number}`;
-            default:
-                return e.type;
+                return `i${e.number}`;
         }
     };
     return e.key ? slug(e.key) : fallback();
 };
-const keyLine = (e) => `<i><code>#${esc(eventKey(e))}</code></i>`;
+const tagsLine = (e) => `#${TYPE_TAG[e.type]} #${esc(eventKey(e))}`;
 /**
  * Рендерит событие в готовый HTML-текст, обрезанный под лимит Telegram.
- * Ключ добавляется ПОСЛЕ обрезки, с зарезервированным местом: обрезанная
- * карточка без ключа была бы невидима разборщику — ровно на самых длинных,
- * то есть самых важных сообщениях.
+ * Теги — ПЕРВАЯ строка, добавляются до обрезки (не после, как раньше): они
+ * несут и человеческий фильтр, и машинный ключ разборщика — обрезанная
+ * карточка без них была бы не только некликабельной, но и невидимой
+ * разборщику ровно на самых длинных, то есть самых важных сообщениях.
  */
 export const render = (e) => {
     const renderer = RENDERERS[e.type];
@@ -248,10 +411,10 @@ export const render = (e) => {
     if (typeof renderer !== 'function') {
         throw new Error(`неизвестный тип события: ${String(e.type)}`);
     }
-    const tag = keyLine(e);
+    const tags = tagsLine(e);
     // clampMessage может выйти за переданный limit на хвост закрывающих тегов и
     // многоточие — минус 40 оставляет ему этот запас. У сообщений свой запас уже
     // есть (4000 против 4096 у Telegram), у caption лимит 1024 настоящий.
-    const budget = Math.max(64, e.type === 'file' ? 1024 - tag.length - 40 : 4000 - tag.length - 1);
-    return `${clampMessage(renderer(e), budget)}\n${tag}`;
+    const budget = Math.max(64, e.type === 'file' ? 1024 - tags.length - 40 : 4000 - tags.length - 1);
+    return `${tags}\n${clampMessage(renderer(e), budget)}`;
 };

package/package.json

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