@mikitasazan/notify 1.11.0 → 1.12.0

package/dist/send.js

@@ -15,9 +15,10 @@
  * allowed to bring down the deploy or the scheduled task that called it.
  */
 import { execFileSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
-import { basename } from 'node:path';
-import { render } from "./render.js";
+import { appendFileSync, mkdirSync, readFileSync, renameSync, rmdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { eventKey, outcomeTag, render } from "./render.js";
 import { lintCard } from "./lint.js";
 import { ROUTES, targets } from "./routes.js";
 const log = (msg) => {
@@ -257,6 +258,99 @@ const sendFile = async (e) => {
     }
     return results.includes('sent') ? 'sent' : 'failed';
 };
+/**
+ * Repeat suppression (v2.1). A failure that is still the same failure does
+ * not resend every run: the first card goes out, repeats inside the window
+ * are swallowed, and past the window ONE card a day goes out carrying
+ * `Still red: day N`. A green outcome clears the record — without that, a
+ * new failure would inherit the old one's day counter and the recovery
+ * itself would never be told.
+ *
+ * The key is project + type + instance — DELIBERATELY no free text: both
+ * external reviews independently showed that normalizing prose (stripping
+ * digits, hexes, paths) merges different failures — "connect to host A" and
+ * "connect to host B" become one key and the second failure goes silent. A
+ * job that covers several targets owes each target its own `--key`.
+ *
+ * Every failure of the mechanism itself fails OPEN: a broken state file, a
+ * held lock, an unwritable directory all mean "send". A duplicate card is a
+ * small cost; a swallowed alarm is not.
+ */
+const WINDOW_MS = 20 * 3600_000;
+const DAY_MS = 24 * 3600_000;
+const statePath = () => process.env.NOTIFY_STATE?.trim() || join(homedir(), '.claude', '.runs', 'notify-sent.json');
+/** Exported for tests only — the time is injectable so day counting is provable. */
+export const dedupe = (e, now = Date.now()) => {
+    const file = statePath();
+    const lock = `${file}.lock`;
+    try {
+        mkdirSync(dirname(file), { recursive: true });
+        // The lock is a directory: mkdir is atomic on every filesystem this runs
+        // on. A held lock means another sender is mid-write — fail open.
+        mkdirSync(lock);
+    }
+    catch {
+        return { action: 'send' };
+    }
+    try {
+        let state = {};
+        try {
+            state = JSON.parse(readFileSync(file, 'utf-8'));
+        }
+        catch {
+            state = {}; // missing or broken JSON — start clean, never swallow
+        }
+        const key = `${String(e.project)}:${String(e.type)}:${eventKey(e)}`;
+        const rec = state[key];
+        const write = () => {
+            const tmp = `${file}.tmp`;
+            writeFileSync(tmp, JSON.stringify(state));
+            renameSync(tmp, file);
+        };
+        if (outcomeTag(e) !== 'fail') {
+            if (rec) {
+                delete state[key];
+                write();
+            }
+            return { action: 'send' };
+        }
+        if (!rec) {
+            state[key] = { first: new Date(now).toISOString(), last: new Date(now).toISOString(), count: 0 };
+            write();
+            return { action: 'send' };
+        }
+        const last = Date.parse(rec.last);
+        const first = Date.parse(rec.first);
+        if (Number.isNaN(last) || Number.isNaN(first)) {
+            delete state[key];
+            write();
+            return { action: 'send' };
+        }
+        if (now - last < WINDOW_MS) {
+            rec.count += 1;
+            write();
+            log(`suppressed: same failure "${key}" already reported ${rec.count} time(s) in the window`);
+            return { action: 'suppress' };
+        }
+        rec.last = new Date(now).toISOString();
+        write();
+        // Day 1 is the day the first card went out; the counter only appears
+        // from day 2 on — "Still red: day 1" would restate the card itself.
+        const day = Math.floor((now - first) / DAY_MS) + 1;
+        return { action: 'send', ...(day >= 2 ? { stillRed: day } : {}) };
+    }
+    catch {
+        return { action: 'send' };
+    }
+    finally {
+        try {
+            rmdirSync(lock);
+        }
+        catch {
+            // the lock directory is gone or never ours — nothing to release
+        }
+    }
+};
 /**
  * Sends the event to all of its targets (the project topic, plus
  * `incidents` if needed, plus the team chat). Targets are handled one after
@@ -281,6 +375,7 @@ const reportLostProject = async (project, kind) => {
         job: 'notify: an event was lost',
         status: 'fail',
         note: `project "${String(project)}" is not in ROUTES — event "${kind}" went nowhere`,
+        check: 'npx --yes @mikitasazan/notify routes --json',
         key: 'notify-unknown-project'
     };
     await deliver(targets(lost), render(lost)).catch(() => undefined);
@@ -290,21 +385,70 @@ const reportLostProject = async (project, kind) => {
  * worth losing over its own formatting — and the breach is raised as its own
  * red card, the way a lost project is.
  *
+ * The watchdog card names the offender: the first two content lines of the
+ * card it complains about, quoted verbatim under `Offender:` so the owner
+ * can find it in the feed. Its `Check:` is a real command (the mockups'
+ * `lint-text < card.txt` pointed at a file the owner does not have — a fake
+ * pointer is worse than none), and the offender's full text goes to the
+ * failure log the session start already reads.
+ *
  * `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.
+ * cards raises one running complaint rather than a new one every hour — and
+ * the card passes through the same `dedupe` as any failure, so it cannot
+ * loop daily on one unfixed offender.
+ *
+ * The watchdog lints ITSELF (v2.1 — the v1 card failed its own lint and
+ * nothing noticed). If its own card is at fault it still goes out, and the
+ * breach lands in the failure log: silence is the one thing it may not do.
  */
-const reportBrokenCard = async (e, faults) => {
-    log(`card does not match the standard: ${faults.join('; ')}`);
-    const broken = {
+const failuresLog = () => process.env.NOTIFY_FAILLOG?.trim() || join(homedir(), '.claude', '.runs', 'notify-fail.failures.log');
+const journal = (line) => {
+    try {
+        const file = failuresLog();
+        mkdirSync(dirname(file), { recursive: true });
+        appendFileSync(file, `${new Date().toISOString()} ${line}\n`);
+    }
+    catch {
+        // the journal is best-effort: a card must never be lost to bookkeeping
+    }
+};
+/** Exported for tests: the watchdog's own card must provably pass the lint. */
+export const brokenCardEvent = (e, faults, offenderHtml) => {
+    const offender = offenderHtml
+        .split('\n')
+        .slice(1) // the tag line names nothing a human reads
+        .map((r) => r.replace(/<[^>]+>/g, '').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&').trim())
+        .filter((r) => r !== '')
+        .slice(0, 2)
+        .join('\n');
+    return {
         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('; ')}`,
+        detail: offender || undefined,
+        detailLabel: 'Offender',
+        check: 'config jobs --log notify-broken',
         key: `notify-broken-${String(e.type)}`
     };
-    await deliver(targets(broken), render(broken)).catch(() => undefined);
+};
+const reportBrokenCard = async (e, faults, offenderHtml) => {
+    log(`card does not match the standard: ${faults.join('; ')}`);
+    const broken = brokenCardEvent(e, faults, offenderHtml);
+    const dup = dedupe(broken);
+    if (dup.action === 'suppress') {
+        return;
+    }
+    if (dup.stillRed) {
+        broken.stillRed = dup.stillRed;
+    }
+    const html = render(broken);
+    const ownFaults = lintCard(html);
+    if (ownFaults.length > 0) {
+        journal(`notify-watchdog: own card failed lint: ${ownFaults.join('; ')}`);
+    }
+    await deliver(targets(broken), html).catch(() => undefined);
 };
 export const notify = async (e) => {
     // Object.hasOwn, not `in`: `in` walks the prototype chain, and
@@ -313,6 +457,17 @@ export const notify = async (e) => {
         await reportLostProject(e.project, String(e.type));
         return 'skipped';
     }
+    // The same unresolved failure does not resend: the window swallows it, one
+    // card a day carries `Still red: day N`. Suppression reports 'sent' to the
+    // caller — the words sent/failed/skipped are a watchdog contract about the
+    // delivery PIPELINE, and a deliberate swallow is the pipeline working.
+    const dup = dedupe(e);
+    if (dup.action === 'suppress') {
+        return 'sent';
+    }
+    if (dup.stillRed) {
+        e.stillRed = dup.stillRed;
+    }
     // A card with a file becomes the caption of that file — one card, not two.
     if (e.path) {
         return sendFile(e);
@@ -323,7 +478,7 @@ export const notify = async (e) => {
     const result = await deliver(targets(e), html);
     const faults = lintCard(html);
     if (faults.length > 0) {
-        await reportBrokenCard(e, faults);
+        await reportBrokenCard(e, faults, html);
     }
     return result;
 };

package/dist/trend.d.ts

@@ -10,15 +10,18 @@
  * So the shape is not a sender's business any more. It lives here, one
  * implementation, and every report calls it:
  *
- *   trend(210, 207)        → '210 / 207 ▲3'
- *   trend(202, 207)        → '202 / 207 ▼5'
+ *   trend(210, 207)        → '207 / 210 ▲3'
+ *   trend(202, 207)        → '207 / 202 ▼5'
  *   trend(0, 0)            → '0 / 0 ='
  *   trend(37)              → '37'          nothing to compare to, so no mark
- *   trend(4.4, 3.6, '%')   → '4.4% / 3.6% ▲0.8'
+ *   trend(4.4, 3.6, '%')   → '3.6% / 4.4% ▲0.8'
  *
- * Both numbers are printed, now first and before first. The owner read
- * `51 ▲5` and asked what the 5 was — the new value or the old one. Neither: it
- * was the distance between two numbers, one of which the card never showed.
+ * Both numbers are printed, old first, new second — left is what it was,
+ * right is what it became. The owner read `51 ▲5` first and asked what the 5
+ * was — the new value or the old one. Neither: it was the distance between
+ * two numbers, one of which the card never showed. Once both were on the
+ * card the owner asked for THIS order specifically, so a reader can read the
+ * row left to right as a sentence: was, became, and by how much.
  *
  * The rule the owner asked for, in one line: where there is data to compare
  * against, the arrow is printed; where there is none, nothing is printed —

package/dist/trend.js

@@ -10,15 +10,18 @@
  * So the shape is not a sender's business any more. It lives here, one
  * implementation, and every report calls it:
  *
- *   trend(210, 207)        → '210 / 207 ▲3'
- *   trend(202, 207)        → '202 / 207 ▼5'
+ *   trend(210, 207)        → '207 / 210 ▲3'
+ *   trend(202, 207)        → '207 / 202 ▼5'
  *   trend(0, 0)            → '0 / 0 ='
  *   trend(37)              → '37'          nothing to compare to, so no mark
- *   trend(4.4, 3.6, '%')   → '4.4% / 3.6% ▲0.8'
+ *   trend(4.4, 3.6, '%')   → '3.6% / 4.4% ▲0.8'
  *
- * Both numbers are printed, now first and before first. The owner read
- * `51 ▲5` and asked what the 5 was — the new value or the old one. Neither: it
- * was the distance between two numbers, one of which the card never showed.
+ * Both numbers are printed, old first, new second — left is what it was,
+ * right is what it became. The owner read `51 ▲5` first and asked what the 5
+ * was — the new value or the old one. Neither: it was the distance between
+ * two numbers, one of which the card never showed. Once both were on the
+ * card the owner asked for THIS order specifically, so a reader can read the
+ * row left to right as a sentence: was, became, and by how much.
  *
  * The rule the owner asked for, in one line: where there is data to compare
  * against, the arrow is printed; where there is none, nothing is printed —
@@ -26,19 +29,23 @@
  */
 /** Integers stay integers; anything else keeps one decimal. */
 const fmt = (n) => (Number.isInteger(n) ? String(n) : n.toFixed(1));
-/**
- * Two values that round to the same first decimal are equal: `4.42%` against
- * `4.44%` is not movement, it is noise, and `▲0.0` reads as a lie.
- */
-const same = (a, b) => Math.abs(a - b) < 0.05;
 export const trend = (now, was, unit = '') => {
     const head = `${fmt(now)}${unit}`;
     if (was === undefined || !Number.isFinite(was)) {
         return head;
     }
-    const pair = `${head} / ${fmt(was)}${unit}`;
-    if (same(now, was)) {
+    const pair = `${fmt(was)}${unit} / ${head}`;
+    // Equality is judged on the printed digits, not the raw numbers: `4.44` and
+    // `4.46` round to different labels (`4.4%` / `4.5%`), and printing `=` next
+    // to two different numbers reads as a lie no threshold on the raw values
+    // can prevent.
+    if (fmt(now) === fmt(was)) {
         return `${pair} =`;
     }
-    return now > was ? `${pair} ▲${fmt(now - was)}` : `${pair} ▼${fmt(was - now)}`;
+    // The diff is computed from the two PRINTED numbers, not the raw ones: a
+    // diff of the raw values can round to `0.0` even when the printed pair
+    // reads `4.4% / 4.5%` — the arrow would show movement of nothing next to
+    // two numbers that are visibly different.
+    const diff = Number(fmt(now)) - Number(fmt(was));
+    return diff > 0 ? `${pair} ▲${fmt(Math.abs(diff))}` : `${pair} ▼${fmt(Math.abs(diff))}`;
 };

package/package.json

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