@mikitasazan/notify 1.8.1 → 1.10.0

package/README.md

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

package/dist/cli-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/events.js

@@ -68,7 +68,11 @@ export const iconFor = (e) => {
         case 'ci':
             return e.status === 'ok' ? ICON.ok : ICON.red;
         case 'job':
-            return JOB_ICON[e.status];
+            // `?? ICON.unknown`: an untyped `--json` payload can carry a status
+            // outside the map, and an undefined icon printed the literal word
+            // `undefined` at the head of line 2. Not knowing is itself a state the
+            // package already has a word and a sound for.
+            return JOB_ICON[e.status] ?? ICON.unknown;
         case 'session':
             return e.status === 'ok' ? ICON.ok : ICON.alarm;
         case 'incident':
@@ -76,9 +80,9 @@ export const iconFor = (e) => {
         case 'heartbeat_miss':
             return e.recovered ? ICON.ok : ICON.unknown;
         case 'pr':
-            return PR_ICON[e.action];
+            return PR_ICON[e.action] ?? ICON.unknown;
         case 'issue':
-            return ISSUE_ICON[e.action];
+            return ISSUE_ICON[e.action] ?? ICON.unknown;
         case 'report':
             return ICON.info;
     }

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export type { EventType, NotifyEvent, Project } from './events.ts';
 export { severity } from './events.ts';
-export { notify, sendReport } from './send.ts';
+export { notify } from './send.ts';
 export { render } from './render.ts';
 export { trend } from './trend.ts';
 export type { SendResult } from './send.ts';

package/dist/index.js

@@ -1,5 +1,5 @@
 export { severity } from "./events.js";
-export { notify, sendReport } from "./send.js";
+export { notify } from "./send.js";
 // `render` is exported so a sender can put on disk EXACTLY the card that was
 // sent rather than its own second version of the text. A hand-built copy had
 // already drifted from what went out.

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.d.ts

@@ -19,7 +19,7 @@
  * separates BLOCKS BY MEANING (header / body / actions), not mechanically
  * after every line.
  */
-import { type NotifyEvent } from './events.ts';
+import { ICON, type NotifyEvent } from './events.ts';
 /** Escapes EVERYTHING that comes from outside — only the template adds tags. */
 export declare const esc: (v: unknown) => string;
 /**
@@ -65,16 +65,20 @@ export declare const eventKey: (e: NotifyEvent) => string;
  * `#fail` under a 🚫 and said so. Nor is a task that has simply gone quiet —
  * nobody knows yet whether it broke, and `#unknown` is the honest word for it.
  */
-export declare const OUTCOME_TAG: Readonly<Record<string, string>>;
-export declare const outcomeTag: (e: NotifyEvent) => string;
+/** Every icon the package can print — the key space of the outcome table. */
+type Icon = (typeof ICON)[keyof typeof ICON];
+/** The five words the third tag is allowed to be, and there is no sixth. */
+type OutcomeTag = 'ok' | 'fail' | 'off' | 'unknown' | 'news';
 /**
- * The tag line for free-form HTML (`sendReport`). The tag is the owner's
- * FILTER, and it has nothing to do with the body's format: a daily report
- * stays free-form text, but stops being the one card with no tags. The key
- * used to hang off the tail as `<i><code>#key</code></i>` — that is the old
- * format, from before tags moved to the first line.
+ * The type is `Record` over EVERY icon, not over `string`. A new icon added to
+ * `ICON` without a word here now fails to compile. Under the old loose type it
+ * fell through a `?? 'news'` default instead: a card whose outcome nobody had
+ * decided was indistinguishable from a card that is genuinely just news, and
+ * nothing anywhere went red. `news` is therefore written out for each icon
+ * that means it, never left to a fallback.
  */
-export declare const reportTags: (key: string) => string;
+export declare const OUTCOME_TAG: Readonly<Record<Icon, OutcomeTag>>;
+export declare const outcomeTag: (e: NotifyEvent) => OutcomeTag;
 /**
  * Renders an event into finished HTML text, cut to Telegram's limit.
  * Tags are the FIRST line, added before the cut (not after, as before):
@@ -83,3 +87,4 @@ export declare const reportTags: (key: string) => string;
  * parser on exactly the longest, meaning the most important, messages.
  */
 export declare const render: (e: NotifyEvent) => string;
+export {};

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.
@@ -383,10 +396,20 @@ const typeLine = (icon, type, action, url, aside) => {
     // template prints the word "null". That is how line 2 of a card became
     // `ℹ️ null` — reachable through `--json` and through a direct call from JS,
     // where there are no types.
-    // `action || 'open'` in the linked case: an empty title must not swallow the
-    // link, which would be the one thing the card cannot afford to lose.
-    const line = url ? fieldLink(type, url, action || 'open') : field(type, action);
     const tail = aside ? ` (${esc(aside)})` : '';
+    const name = action?.trim();
+    // No name: the card must not invent one. It used to write the word `open`
+    // into the identifier slot, so a report with a link and no title arrived as
+    // `Report: open` — and a deploy with neither fell back to its own status
+    // word, `Deploy: fail`, saying the outcome a third time after the icon and
+    // the tag. Both are the same mistake: a slot that must hold a name holding
+    // something else instead. The type word itself takes the link, so nothing
+    // clickable is lost and nothing false is said.
+    if (!name) {
+        const bare = `<b>${esc(cap(type))}</b>`;
+        return `${icon} ${url ? `<a href="${esc(url)}">${bare}</a>` : bare}${tail}`;
+    }
+    const line = url ? fieldLink(type, url, name) : field(type, name);
     return line === null ? `${icon} <b>${esc(cap(type))}</b>${tail}` : `${icon} ${line}${tail}`;
 };
 // `workflowUrl ?? url`: half the senders send the run link under the name
@@ -405,7 +428,7 @@ const typeLine = (icon, type, action, url, aside) => {
  * GitHub Action always fills the workflow name, and the hand-run scripts send
  * no run link at all.
  */
-const mechanism = (workflowName, via, runUrl) => workflowName ?? via ?? (runUrl ? 'the run' : undefined);
+const mechanism = (workflowName, via, runUrl) => workflowName ?? via;
 // The name of what ran sits WITH the type line, not eight lines below it.
 // `Deploy: fail` and `by what means it ran` answer one question, and the owner
 // read the two rows as unrelated things. It used to be one fact split in two:
@@ -426,8 +449,8 @@ const renderDeploy = (e) => {
         // is already said by the icon and the third tag; there is nothing to
         // 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) ?? e.status, runUrl),
-        ...twoBlocks([field('Target', e.target), field('Reason', e.note)], [fieldLink('Commit', e.commitUrl, e.commit), titleField(e.commitTitle), bodyQuote(e.commitBody)])
+        typeLine(icon, 'Deploy', mechanism(e.workflowName, e.via, runUrl), runUrl),
+        ...twoBlocks([field('Target', e.target), field('Reason', e.note)], [commitRow(e.commit, e.commitUrl, e.commitTitle), bodyQuote(e.commitBody)])
     ]);
 };
 const schedule = (expected, lastSeen, lastLabel) => {
@@ -465,11 +488,11 @@ const renderJob = (e) => {
         ...(hasItems ? bullets(e.items, disabledList) : []),
         e.command || e.logs ? '' : null,
         fieldCode('Log', e.logs),
-        ...fieldRun(e.command, e.commandNote),
-        // Kept only when the caller actually names the workflow — a named row is a
-        // second, different destination; an unnamed one repeats the Task link.
-        e.workflowName && (e.workflowUrl ?? e.url) ? '' : null,
-        e.workflowName ? fieldAction('Workflow', e.workflowUrl ?? e.url, e.workflowName) : null
+        ...fieldRun(e.command, e.commandNote)
+        // No trailing `Workflow:` row. It pointed at `workflowUrl ?? url` — the
+        // exact address line 2 already carries — so it was one destination
+        // written twice, and it stood BELOW the `To do:` command, which is the
+        // last thing the card is supposed to say.
     ]);
 };
 const renderReport = (e) => {
@@ -508,8 +531,8 @@ const renderCi = (e) => {
     const icon = iconFor(e);
     const runUrl = e.workflowUrl ?? e.url;
     return join([
-        typeLine(icon, 'CI', mechanism(e.workflowName, undefined, runUrl) ?? e.status, runUrl),
-        ...twoBlocks([field('Actor', e.actor), field('Reason', e.note)], [fieldLink('Commit', e.commitUrl, e.commit), titleField(e.commitTitle), bodyQuote(e.commitBody)])
+        typeLine(icon, 'CI', mechanism(e.workflowName, undefined, runUrl), runUrl),
+        ...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
@@ -554,7 +577,7 @@ const renderIncident = (e) => join([
     typeLine(iconFor(e), 'Incident', e.title, e.url),
     e.detail && e.detail !== e.title ? note(e.detail) : null,
     e.logs ? '' : null,
-    fieldCode('Logs', e.logs)
+    fieldCode('Log', e.logs)
 ]);
 // A session in trouble. Same law as every other card: identifier first, then
 // the facts as fields, then his own words as a quote — never as a field, which
@@ -578,14 +601,16 @@ const renderSession = (e) => join([
 ]);
 const renderHeartbeatMiss = (e) => {
     const icon = iconFor(e);
-    const action = e.recovered ? 'ok' : 'miss';
     return join([
         // The task's name on the type line, exactly as a job card carries it. The
         // `Task:` row said the same thing a floor below. No sender in any
         // repository builds this event any more — the silence watchdog sends an
         // ordinary job with `--status silent` — but a machine still running the old
         // copy of that watchdog can, and the card it gets must obey the template.
-        typeLine(icon, 'Heartbeat', e.job, undefined, action),
+        // No bracket saying `ok` or `miss`: the icon says it, the third tag says
+        // it, and `miss` is not one of the five words the outcome is allowed to
+        // be. The bracket is for what finishes the NAME, never for a verdict.
+        typeLine(icon, 'Heartbeat', e.job),
         field('Reason', e.note),
         ...schedule(e.expected, e.lastSeen, e.recovered ? 'Last run' : 'Last seen')
     ]);
@@ -660,24 +685,19 @@ export const eventKey = (e) => {
                 return `i${e.number}`;
         }
     };
-    return e.key ? slug(e.key) : fallback();
+    // An empty instance tag (`#session # #fail`) is not a tag: it groups
+    // nothing and the parser cannot pair a red card with its green one. An
+    // untyped `--json` payload can leave every field it is derived from blank,
+    // so the project name is the last resort.
+    return (e.key ? slug(e.key) : fallback()) || slug(e.project) || 'event';
 };
 /**
- * The third tag is the OUTCOME, and it is always there. The owner: "I'm
- * missing a fail tag or something like it, so failures can be grouped and
- * ok can be grouped." One tap in Telegram collects every failure of a
- * project at once, no matter what type it arrived as — a deploy, a check,
- * a scheduled task, an incident.
- *
- * The value comes from the ICON, never from the status word. The icon is
- * already the single source of truth for the sound, and a second list of "what
- * counts as broken" would drift from the first — it already did once, when a
- * red card arrived silent.
- *
- * One icon meaning, one tag. A watchdog that SWITCHED SOMETHING OFF is not a
- * failure and must not be filed under the same word as one: the owner read
- * `#fail` under a 🚫 and said so. Nor is a task that has simply gone quiet —
- * nobody knows yet whether it broke, and `#unknown` is the honest word for it.
+ * The type is `Record` over EVERY icon, not over `string`. A new icon added to
+ * `ICON` without a word here now fails to compile. Under the old loose type it
+ * fell through a `?? 'news'` default instead: a card whose outcome nobody had
+ * decided was indistinguishable from a card that is genuinely just news, and
+ * nothing anywhere went red. `news` is therefore written out for each icon
+ * that means it, never left to a fallback.
  */
 export const OUTCOME_TAG = {
     [ICON.red]: 'fail',
@@ -686,20 +706,16 @@ export const OUTCOME_TAG = {
     [ICON.unknown]: 'unknown',
     [ICON.ok]: 'ok',
     [ICON.landed]: 'ok',
-    [ICON.approved]: 'ok'
+    [ICON.approved]: 'ok',
+    // Something happened; no verdict was passed on it.
+    [ICON.fresh]: 'news',
+    [ICON.taken]: 'news',
+    [ICON.discarded]: 'news',
+    [ICON.changes]: 'news',
+    [ICON.info]: 'news'
 };
-// Everything left over — a task was opened, a PR opened, edits asked for, a
-// digest — is news: something happened, no verdict was passed.
-export const outcomeTag = (e) => OUTCOME_TAG[iconFor(e)] ?? 'news';
+export const outcomeTag = (e) => OUTCOME_TAG[iconFor(e)];
 const tagsLine = (e) => `#${TYPE_TAG[e.type]} #${esc(eventKey(e))} #${outcomeTag(e)}`;
-/**
- * The tag line for free-form HTML (`sendReport`). The tag is the owner's
- * FILTER, and it has nothing to do with the body's format: a daily report
- * stays free-form text, but stops being the one card with no tags. The key
- * used to hang off the tail as `<i><code>#key</code></i>` — that is the old
- * format, from before tags moved to the first line.
- */
-export const reportTags = (key) => `#report #${esc(slug(key))}`;
 /**
  * Renders an event into finished HTML text, cut to Telegram's limit.
  * Tags are the FIRST line, added before the cut (not after, as before):

package/dist/send.d.ts

@@ -1,21 +1,3 @@
-import type { NotifyEvent, Project } from './events.ts';
+import type { NotifyEvent } from './events.ts';
 export type SendResult = 'sent' | 'skipped' | 'failed';
 export declare const notify: (e: NotifyEvent) => Promise<SendResult>;
-/**
- * Готовый HTML во вкладку «Ops» проекта — ТОЛЬКО для дневных отчётов.
- *
- * Зачем исключение из правила «свободного текста в API нет». Отчёт — это не
- * событие: в нём плотная строка вроде
- * `🎮 1284 игр (🍎 412 iOS +3 · 🤖 890 Android +5) | 📈 +240 запусков`,
- * и разложить её в `label=value` можно только испортив. Но транспорт у отчёта
- * ТОТ ЖЕ: ретраи, 429, таймауты, curl-фолбэк, номер вкладки. Пока его копировали
- * в каждый скрипт, один и тот же баг с дублями на таймауте пришлось чинить
- * дважды — в пакете и в game-publisher (27.07.2026).
- *
- * Граница: формат событий по-прежнему задаёт только пакет, «своё» уведомление
- * о деплое или упавшей задаче написать нельзя. Здесь стандартизирован транспорт,
- * а не формат — и в этом весь смысл.
- *
- * Всегда беззвучно: отчёт читают утром, а не по звонку.
- */
-export declare const sendReport: (project: Project, html: string, key?: string) => Promise<SendResult>;

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 { clampMessage, render, reportTags } from "./render.js";
+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 };
@@ -133,17 +141,18 @@ const sendOne = async (token, target, text) => {
     log('out of send attempts');
     return 'failed';
 };
-/** Общий хвост для `notify` и `sendReport`: токен, цели, последовательная отправка. */
+/** The shared tail of `notify()`: token, targets, delivery one after another. */
 const deliver = async (where, text) => {
     const token = process.env.OPS_BOT_TOKEN?.trim();
     if (!token) {
         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,36 +317,13 @@ export const notify = async (e) => {
     if (e.path) {
         return sendFile(e);
     }
-    return deliver(targets(e), render(e));
-};
-/**
- * Готовый HTML во вкладку «Ops» проекта — ТОЛЬКО для дневных отчётов.
- *
- * Зачем исключение из правила «свободного текста в API нет». Отчёт — это не
- * событие: в нём плотная строка вроде
- * `🎮 1284 игр (🍎 412 iOS +3 · 🤖 890 Android +5) | 📈 +240 запусков`,
- * и разложить её в `label=value` можно только испортив. Но транспорт у отчёта
- * ТОТ ЖЕ: ретраи, 429, таймауты, curl-фолбэк, номер вкладки. Пока его копировали
- * в каждый скрипт, один и тот же баг с дублями на таймауте пришлось чинить
- * дважды — в пакете и в game-publisher (27.07.2026).
- *
- * Граница: формат событий по-прежнему задаёт только пакет, «своё» уведомление
- * о деплое или упавшей задаче написать нельзя. Здесь стандартизирован транспорт,
- * а не формат — и в этом весь смысл.
- *
- * Всегда беззвучно: отчёт читают утром, а не по звонку.
- */
-export const sendReport = async (project, html, key) => {
-    if (!Object.hasOwn(ROUTES, project)) {
-        // Та же красная карточка, что у notify(): дверь свободного HTML — не
-        // лазейка для молчаливой потери (этот класс уже жил неделями дважды).
-        await reportLostProject(project, 'report');
-        return 'skipped';
+    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);
     }
-    const forum = ROUTES[project];
-    // Без проекта — как и render.ts: карточка уже лежит в форуме своего
-    // проекта, дублировать его в теге незачем. Строка тегов ПЕРВАЯ и до обрезки,
-    // как у любой другой карточки.
-    const tags = reportTags(key ?? 'daily');
-    return deliver([{ chat: forum.chat, thread: forum.ops, silent: true }], `${tags}\n${clampMessage(html, Math.max(64, 4000 - tags.length - 1))}`);
+    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.8.1",
+  "version": "1.10.0",
   "description": "Единая типизированная отправка Telegram-уведомлений (форум-темы, маршрутизация, ретраи) для всех проектов",
   "type": "module",
   "license": "MIT",