@mikitasazan/notify 1.0.3 → 1.1.1

package/README.md

@@ -86,9 +86,24 @@ notify report --project playhub --json < payload.json   # весь объект
 | `issue` | событие задачи | `project`, `action`, `number`, `title` |
 | `incident` | приложение сломалось прямо сейчас | `project`, `title` |
 | `heartbeat_miss` | задача не отметилась вовремя | `project`, `job` |
+| `file` | файл-вложение с подписью-карточкой | `project`, `title`, `path` |
 
 Полные сигнатуры — `src/events.ts`.
 
+**Ключ задачи.** Последняя строка каждой карточки — `#проект/ключ` в `<code>`.
+По нему дневной разборщик сверяет «это 🔴 уже закрыто более поздней карточкой
+той же задачи?» без сравнения человеческих формулировок. Явный `--key`
+побеждает; без него ключ выводится из заголовка и меняется вместе с ним —
+регулярный отправитель передаёт `--key` явно. В stdout CLI ключ не попадает.
+
+**Единственная дверь для свободного HTML** — `sendReport()` (`report --json` у
+аналитик): плотную строку дневного отчёта не разложить в `label=value` не
+испортив. Стандартизирован транспорт, формат — нет, и только здесь.
+
+**Неизвестный проект** не роняет вызвавший крон (код возврата 0), но больше и
+не исчезает молча: в mac-config Ops уходит красная карточка «notify: событие
+потеряно». До 18.08.2026 опечатка в `--project` терялась без следа неделями.
+
 `--action` у `pr`: `opened`, `ready_for_review`, `review_requested`, `approved`,
 `changes_requested`, `merged`, `closed`. У `issue`: `opened`, `assigned`,
 `closed`. Принимаются и сырые имена GitHub (`reopened`,
@@ -113,7 +128,16 @@ CLI), однако общий workflow `.github/workflows/ops-notify.yml` их
    живому аккаунту, ботом это не сделать.
 2. `notify setup <chat_id> maphub` — заведёт вкладки «⚙️ Ops» и «💬 Dev» и
    напечатает готовую строку.
-3. Вставить строку в `src/routes.ts`.
+3. Вставить строку в `src/routes.ts` (и значение в тип `Project` в
+   `src/events.ts`), выпустить пакет.
+4. В репозиторий проекта — трёхстрочный `.github/workflows/notify.yml`,
+   вызывающий `mikitasazan/notify/.github/workflows/ops-notify.yml@v1`:
+   CI, деплой, PR и задачи начинают приходить сами.
+5. Закрепить в «⚙️ Ops» легенду значков (пример — в любом существующем
+   форуме) и, если задача проекта бежит с мака, — добавить её плист под
+   обёртку `run-scheduled.sh` (репозиторий mac-config).
+
+Весь путь — минут десять, единственный ручной шаг — п. 1.
 
 **Появились сотрудники на проекте** — просто добавь их в форум этого проекта.
 Ничего не мигрируется и не дублируется: они видят Ops и Dev своего проекта и

package/dist/cli.js

@@ -15,6 +15,8 @@
  *   notify ci       --project arvent  --status fail --branch master --actor saz_sam
  *   notify pr       --project arvent  --action opened --number 142 --title "..."
  *   notify incident --project arvent  --title "Redis недоступен" --detail "$ERR"
+ *   notify file     --project arvent  --title "Полные диалоги" --path ./out.txt [--filename имя.txt]
+ *   notify <type> [--key стабильный-ключ]   # ключ задачи в последней строке карточки
  *   notify <type> --json < payload.json   # весь объект события со stdin
  *   notify setup <chat_id форума> <ключ-проекта>   # создать вкладки, см. setup.ts
  */
@@ -161,7 +163,8 @@ else {
                 url: one('url'),
                 target: one('target'),
                 via: one('via'),
-                note: one('note')
+                note: one('note'),
+                key: one('key')
             };
             break;
         case 'job':
@@ -173,7 +176,8 @@ else {
                 stats: pairs('stat'),
                 items: items(),
                 note: one('note'),
-                url: one('url')
+                url: one('url'),
+                key: one('key')
             };
             break;
         case 'report':
@@ -184,7 +188,8 @@ else {
                 period: one('period'),
                 lines: pairs('line'),
                 items: items(),
-                url: one('url')
+                url: one('url'),
+                key: one('key')
             };
             break;
         case 'ci':
@@ -195,7 +200,8 @@ else {
                 branch: one('branch'),
                 commit: one('commit'),
                 actor: one('actor'),
-                url: one('url')
+                url: one('url'),
+                key: one('key')
             };
             break;
         case 'pr':
@@ -207,7 +213,8 @@ else {
                 title: one('title') ?? '(без заголовка)',
                 author: one('author'),
                 reviewer: one('reviewer'),
-                url: one('url')
+                url: one('url'),
+                key: one('key')
             };
             break;
         case 'issue':
@@ -219,7 +226,8 @@ else {
                 title: one('title') ?? '(без заголовка)',
                 author: one('author'),
                 assignee: one('assignee'),
-                url: one('url')
+                url: one('url'),
+                key: one('key')
             };
             break;
         case 'incident':
@@ -228,7 +236,8 @@ else {
                 project: project(),
                 title: one('title') ?? '(без заголовка)',
                 detail: one('detail'),
-                url: one('url')
+                url: one('url'),
+                key: one('key')
             };
             break;
         case 'heartbeat_miss':
@@ -237,9 +246,26 @@ else {
                 project: project(),
                 job: one('job') ?? '(без имени)',
                 lastSeen: one('last-seen'),
-                expected: one('expected')
+                expected: one('expected'),
+                key: one('key')
+            };
+            break;
+        case 'file': {
+            const path = one('path');
+            if (!path) {
+                parseErrors.push('--path: обязателен для file');
+            }
+            event = {
+                type: 'file',
+                project: project(),
+                title: one('title') ?? '(без заголовка)',
+                path: path ?? '',
+                filename: one('filename'),
+                note: one('note'),
+                key: one('key')
             };
             break;
+        }
         default:
             log(`неизвестный тип события: ${command ?? '(не указан)'}`);
     }

package/dist/events.d.ts

@@ -9,7 +9,19 @@
  *   - обязательные поля не добавляются никогда — только новый тип события.
  * Тогда старый вызывающий код и новый пакет совместимы в обе стороны.
  */
-export type Project = 'playhub' | 'one-q' | 'arvent' | 'game-publisher' | 'vault' | 'mac-config';
+export type Project = 'playhub' | 'one-q' | 'arvent' | 'game-publisher' | 'vault' | 'mac-config' | 'alitools';
+/**
+ * Стабильный машинный ключ задачи — последняя строка каждой карточки, вида
+ * `#проект/ключ`. По нему дневной разборщик сверяет «это 🔴 уже закрыто более
+ * поздней карточкой того же ключа?» без сравнения человеческих формулировок,
+ * которые меняются. Необязателен: без него ключ выводится из типа и заголовка
+ * (см. `render.ts`), но выведенный наследует хрупкость формулировки — наши
+ * регулярные отправители передают его явно. В stdout CLI ключ не попадает
+ * никогда: сторож на VPS разбирает stdout по словам `sent|failed|skipped`.
+ */
+type Keyed = {
+    key?: string;
+};
 /**
  * Позиция списка внутри сообщения: задача из дайджеста, упавшая проверка,
  * замечание. `url` необязателен — тогда рендерится просто строкой.
@@ -18,7 +30,7 @@ export type Item = {
     text: string;
     url?: string;
 };
-export type NotifyEvent = 
+export type NotifyEvent = Keyed & (
 /** Выкатка кода на сервер. */
 {
     type: 'deploy';
@@ -122,7 +134,26 @@ export type NotifyEvent =
     job: string;
     lastSeen?: string;
     expected?: string;
-};
+}
+/**
+ * Файл-вложение (sendDocument) с подписью-карточкой. Появился, когда
+ * eval-отчёт Arvent слал файл голым curl мимо пакета: без ретраев файл
+ * терялся в любую сетевую икоту, а chat_id и номер вкладки жили копией,
+ * которая устаревает молча. Маршрут — тот же `ROUTES`, транспорт — с теми
+ * же повторами. Подпись у Telegram ограничена 1024 символами — режется
+ * тем же безопасным клампом.
+ */
+ | {
+    type: 'file';
+    project: Project;
+    title: string;
+    /** Путь к локальному файлу. */
+    path: string;
+    /** Имя файла в чате; по умолчанию — имя из `path`. */
+    filename?: string;
+    note?: string;
+});
 export type EventType = NotifyEvent['type'];
 /** Красное = со звуком. Всё остальное — тихо. (Отдельной темы «инциденты» больше нет — авария видна в ленте проекта.) */
 export declare const severity: (e: NotifyEvent) => "info" | "error";
+export {};

package/dist/render.d.ts

@@ -27,5 +27,11 @@ export declare const esc: (v: unknown) => string;
  *    повторяем — сообщение исчезало совсем.
  */
 export declare const clampMessage: (text: string, limit?: number) => string;
-/** Рендерит событие в готовый HTML-текст, обрезанный под лимит Telegram. */
+export declare const eventKey: (e: NotifyEvent) => string;
+/**
+ * Рендерит событие в готовый HTML-текст, обрезанный под лимит Telegram.
+ * Ключ добавляется ПОСЛЕ обрезки, с зарезервированным местом: обрезанная
+ * карточка без ключа была бы невидима разборщику — ровно на самых длинных,
+ * то есть самых важных сообщениях.
+ */
 export declare const render: (e: NotifyEvent) => string;

package/dist/render.js

@@ -152,6 +152,8 @@ const renderHeartbeatMiss = (e) => join([
     kv('последний раз', e.lastSeen),
     kv('ожидалось', e.expected)
 ]);
+// Подпись файла — та же карточка, но лимит Telegram у caption свой: 1024.
+const renderFile = (e) => join([header('📄', e.title, e.project), kv('примечание', e.note)]);
 const RENDERERS = {
     deploy: renderDeploy,
     job: renderJob,
@@ -160,9 +162,47 @@ const RENDERERS = {
     pr: renderPr,
     issue: renderIssue,
     incident: renderIncident,
-    heartbeat_miss: renderHeartbeatMiss
+    heartbeat_miss: renderHeartbeatMiss,
+    file: renderFile
 };
-/** Рендерит событие в готовый HTML-текст, обрезанный под лимит Telegram. */
+/**
+ * Ключ задачи — последняя строка карточки: `#проект/ключ` в <code>. Явный
+ * `key` побеждает; выведенный строится из заголовка и наследует хрупкость
+ * формулировки — регулярные отправители передают явный. Ключ переживает
+ * MTProto-чтение (это простой текст, не разметка), по нему разборщик сверяет
+ * 🔴 с более поздней успешной карточкой той же задачи.
+ */
+const slug = (raw) => raw
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, '-')
+    .replace(/^-+|-+$/g, '');
+export const eventKey = (e) => {
+    const fallback = () => {
+        switch (e.type) {
+            case 'job':
+            case 'heartbeat_miss':
+                return slug(e.job);
+            case 'report':
+            case 'incident':
+            case 'file':
+                return slug(e.title);
+            case 'pr':
+                return `pr-${e.number}`;
+            case 'issue':
+                return `issue-${e.number}`;
+            default:
+                return e.type;
+        }
+    };
+    return `#${slug(e.project)}/${e.key ? slug(e.key) : fallback()}`;
+};
+const keyLine = (e) => `<code>${esc(eventKey(e))}</code>`;
+/**
+ * Рендерит событие в готовый HTML-текст, обрезанный под лимит Telegram.
+ * Ключ добавляется ПОСЛЕ обрезки, с зарезервированным местом: обрезанная
+ * карточка без ключа была бы невидима разборщику — ровно на самых длинных,
+ * то есть самых важных сообщениях.
+ */
 export const render = (e) => {
     const renderer = RENDERERS[e.type];
     // Прикрывает путь `--json` и вызовы из JS без типов: там `type` — обычная
@@ -171,5 +211,10 @@ export const render = (e) => {
     if (typeof renderer !== 'function') {
         throw new Error(`неизвестный тип события: ${String(e.type)}`);
     }
-    return clampMessage(renderer(e));
+    const tag = keyLine(e);
+    // clampMessage может выйти за переданный limit на хвост закрывающих тегов и
+    // многоточие — минус 40 оставляет ему этот запас. У сообщений свой запас уже
+    // есть (4000 против 4096 у Telegram), у caption лимит 1024 настоящий.
+    const budget = e.type === 'file' ? 1024 - tag.length - 40 : 4000 - tag.length - 1;
+    return `${clampMessage(renderer(e), budget)}\n${tag}`;
 };

package/dist/routes.js

@@ -12,7 +12,12 @@ export const ROUTES = {
     vault: { chat: '-1004459314999', ops: 3 },
     // Тоже инфраструктура, без `dev`: дневной дайджест задач и понедельничная
     // сводка спотыканий. До этой строки оба тихо умирали на «неизвестный проект».
-    'mac-config': { chat: '-1004442522004', ops: 2 }
+    'mac-config': { chat: '-1004442522004', ops: 2 },
+    // Корпоративный проект владельца: только его собственные отчёты «что дала
+    // выливка» (ali98x-sentry). Без `dev` — команда проекта живёт в чужих
+    // системах, людей здесь нет. До 18.08.2026 отчёты терялись на «неизвестный
+    // проект» неделями.
+    alitools: { chat: '-1003904331479', ops: 3 }
 };
 /**
  * Куда уходит событие. Всё — во вкладку «Ops» своего проекта; красное

package/dist/send.d.ts

@@ -4,6 +4,12 @@ export type SendResult = 'sent' | 'skipped' | 'failed';
  * Отправляет событие во все его цели (тема проекта + при необходимости
  * `incidents` + чат команды). Цели идут последовательно; провал одной не
  * отменяет остальные. `'sent'`, если хотя бы одна цель получила сообщение.
+ *
+ * Неизвестный проект по-прежнему НЕ роняет вызвавший крон (код возврата не
+ * меняется) — но и не исчезает молча: в mac-config Ops уходит красная
+ * карточка. Дважды этот класс провала жил незамеченным неделями: «vault» и
+ * «mac-config» до 04.08, отчёты Alitools — до 18.08. Рекурсия невозможна:
+ * карточка-ошибка адресована mac-config, который в ROUTES есть всегда.
  */
 export declare const notify: (e: NotifyEvent) => Promise<SendResult>;
 /**

package/dist/send.js

@@ -13,6 +13,8 @@
  * деплой или регулярную задачу, которая его вызвала.
  */
 import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
 import { clampMessage, render } from "./render.js";
 import { ROUTES, targets } from "./routes.js";
 const log = (msg) => {
@@ -157,12 +159,119 @@ const deliver = async (where, text) => {
     }
     return results.includes('sent') ? 'sent' : 'failed';
 };
+/**
+ * Файл (sendDocument) — multipart, поэтому не через `buildBody`. Политика
+ * повторов та же, что у сообщений: 429 с уважением retry_after, 5xx —
+ * повтор, прочие 4xx и таймаут — нет (дубль файла хуже пропуска).
+ * Отдельного curl-фолбэка нет: файл шлётся с этой же машины, а не из CI,
+ * и другой TLS-стек здесь ни разу не понадобился.
+ */
+const sendFileOnce = async (token, target, e, caption) => {
+    try {
+        const form = new FormData();
+        form.append('chat_id', target.chat);
+        if (target.thread) {
+            form.append('message_thread_id', String(target.thread));
+        }
+        form.append('caption', caption);
+        form.append('parse_mode', 'HTML');
+        form.append('disable_notification', String(target.silent));
+        // readFileSync + Blob, не openAsBlob: тот появился в Node 19.8, а пакет
+        // бегает и на сервере. Файлы здесь — текстовые отчёты, память не вопрос.
+        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',
+            body: form,
+            signal: AbortSignal.timeout(60_000)
+        });
+        if (res.ok) {
+            return { outcome: 'ok' };
+        }
+        if (res.status === 429) {
+            const body = (await res.json().catch(() => null));
+            const retryAfter = typeof body?.parameters?.retry_after === 'number' ? body.parameters.retry_after : 5;
+            return { outcome: 'retry', waitMs: Math.min(retryAfter, 60) * 1000 };
+        }
+        if (res.status >= 500) {
+            return { outcome: 'retry', waitMs: 1000 };
+        }
+        const detail = (await res.json().catch(() => null));
+        log(`HTTP ${res.status}: ${detail?.description ?? 'без описания'} — не повторяем, ошибка постоянная`);
+        return { outcome: 'fail' };
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === 'TimeoutError') {
+            log('таймаут ответа — не повторяем: файл мог уже уйти');
+            return { outcome: 'fail' };
+        }
+        // Файл не читается (нет на диске, нет прав) — постоянная ошибка.
+        if (err instanceof Error && 'code' in err) {
+            log(`файл не отправлен: ${err.message}`);
+            return { outcome: 'fail' };
+        }
+        log(`сеть не пустила файл: ${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 — файл не отправлен');
+        return 'skipped';
+    }
+    const where = targets(e);
+    if (where.length === 0) {
+        return 'skipped';
+    }
+    const caption = render(e);
+    for (const target of where) {
+        let waitMs = 0;
+        for (let i = 0; i < MAX_ATTEMPTS; i++) {
+            if (waitMs > 0) {
+                await sleep(waitMs);
+            }
+            const result = await sendFileOnce(token, target, e, caption);
+            if (result.outcome === 'ok') {
+                return 'sent';
+            }
+            if (result.outcome === 'fail') {
+                return 'failed';
+            }
+            waitMs = result.waitMs;
+        }
+    }
+    log('исчерпаны попытки отправки файла');
+    return 'failed';
+};
 /**
  * Отправляет событие во все его цели (тема проекта + при необходимости
  * `incidents` + чат команды). Цели идут последовательно; провал одной не
  * отменяет остальные. `'sent'`, если хотя бы одна цель получила сообщение.
+ *
+ * Неизвестный проект по-прежнему НЕ роняет вызвавший крон (код возврата не
+ * меняется) — но и не исчезает молча: в mac-config Ops уходит красная
+ * карточка. Дважды этот класс провала жил незамеченным неделями: «vault» и
+ * «mac-config» до 04.08, отчёты Alitools — до 18.08. Рекурсия невозможна:
+ * карточка-ошибка адресована mac-config, который в ROUTES есть всегда.
  */
-export const notify = async (e) => deliver(targets(e), render(e));
+export const notify = async (e) => {
+    if (!(e.project in ROUTES)) {
+        const lost = {
+            type: 'job',
+            project: 'mac-config',
+            job: 'notify: событие потеряно',
+            status: 'fail',
+            note: `проект «${String(e.project)}» не в ROUTES — событие «${String(e.type)}» никуда не доставлено`,
+            key: 'notify-unknown-project'
+        };
+        await deliver(targets(lost), render(lost)).catch(() => undefined);
+        return 'skipped';
+    }
+    if (e.type === 'file') {
+        return sendFile(e);
+    }
+    return deliver(targets(e), render(e));
+};
 /**
  * Готовый HTML во вкладку «Ops» проекта — ТОЛЬКО для дневных отчётов.
  *

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@mikitasazan/notify",
-  "version": "1.0.3",
+  "version": "1.1.1",
   "description": "Единая типизированная отправка Telegram-уведомлений (форум-темы, маршрутизация, ретраи) для всех проектов",
   "type": "module",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/mikitasazan/notify.git"
+    "url": "git+https://github.com/sazanwork/notify.git"
   },
   "bugs": {
-    "url": "https://github.com/mikitasazan/notify/issues"
+    "url": "https://github.com/sazanwork/notify/issues"
   },
-  "homepage": "https://github.com/mikitasazan/notify#readme",
+  "homepage": "https://github.com/sazanwork/notify#readme",
   "publishConfig": {
     "access": "public"
   },