@crewhaus/tool-notify 0.7.0

package/dist/lib/blocks.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Message structure, and the escaping that keeps a value from becoming it.
+ *
+ * A notification is almost always assembled from data the harness did not
+ * write: a branch name, an error string, a customer's subject line. If that
+ * data reaches a chat platform unescaped it stops being a value and becomes
+ * syntax — `<!channel>` on Slack pages everyone in the room, `@everyone` on
+ * Discord does the same, and a stray ``` turns the rest of the message into
+ * a code block. That is markup injection, and it is the reason this file
+ * exists separately from the tools: escaping is a pure function that can be
+ * tested exhaustively, and every path that puts text on a platform goes
+ * through it.
+ *
+ * The blocks are deliberately few. Five kinds cover a notification — a
+ * heading, a paragraph, a list of name/value fields, a rule, a link — and
+ * each renders to something every platform actually supports. A richer model
+ * would render well on one platform and badly on the others, which is worse
+ * than a plain one that renders the same everywhere.
+ */
+export type Platform = "slack" | "discord" | "teams" | "webhook";
+export type Block = {
+    readonly kind: "heading";
+    readonly text: string;
+} | {
+    readonly kind: "paragraph";
+    readonly text: string;
+} | {
+    readonly kind: "fields";
+    readonly fields: ReadonlyArray<{
+        readonly name: string;
+        readonly value: string;
+    }>;
+} | {
+    readonly kind: "divider";
+} | {
+    readonly kind: "link";
+    readonly url: string;
+    readonly text?: string;
+};
+/**
+ * Escape a VALUE for a platform, so it can only ever be read as text.
+ *
+ *  - **slack**: `&`, `<` and `>` are the only three characters Slack treats
+ *    as markup structure, and escaping them is exactly what Slack's own docs
+ *    prescribe. It kills `<!channel>`, `<!here>`, `<@U123>` and the
+ *    `<url|label>` link form in one move. Slack's `*bold*`/`_italic_` marks
+ *    are cosmetic — they cannot change who is notified or where a link goes
+ *    — so they are left alone rather than backslash-littering every message.
+ *  - **discord**: backslash-escape the characters that open markdown
+ *    constructs, so a value cannot close a code fence or start a spoiler.
+ *    Mentions are NOT handled here: Discord has no in-content escape for
+ *    them, and the correct fix is the `allowed_mentions` field on the
+ *    request, which `buildChatPayload` always sets to "parse nothing".
+ *  - **teams**: HTML-escape first, because Teams renders a card's text as
+ *    HTML, then backslash-escape the markdown marks it also honours.
+ *  - **webhook**: identity. A generic webhook receives JSON; JSON encoding
+ *    is the escaping, and mangling the value on the way would corrupt a
+ *    payload nobody asked to be rendered.
+ */
+export declare function escapeFor(platform: Platform, value: string): string;
+/**
+ * Is a URL safe to put behind a link?
+ *
+ * `javascript:`, `data:` and `vbscript:` in a chat message are a phishing
+ * payload aimed at whoever clicks. Only http and https get rendered as
+ * links; anything else is refused rather than silently downgraded, because a
+ * caller who asked for a link and got plain text would not notice.
+ */
+export declare function linkSchemeAllowed(url: string): boolean;
+/**
+ * Render a text body plus blocks into one string for a platform.
+ *
+ * Blocks with an unusable link are dropped and reported rather than
+ * rendered, so a `javascript:` URL never reaches a reader.
+ */
+export declare function renderBlocks(platform: Platform, text: string | undefined, blocks: readonly Block[]): {
+    readonly rendered: string;
+    readonly dropped: readonly string[];
+};
+/** Platform byte/character limits, so a message is cut here rather than there. */
+export declare const PLATFORM_TEXT_LIMIT: Readonly<Record<Platform, number>>;
+/**
+ * Cut `text` to a platform's limit, marking the cut. Counting is in UTF-16
+ * code units, which is what every one of these platforms documents its limit
+ * in, and the cut never splits a surrogate pair.
+ */
+export declare function clampToPlatform(platform: Platform, text: string): {
+    readonly text: string;
+    readonly truncated: boolean;
+};
+export type ChatPayload = {
+    readonly body: string;
+    readonly contentType: string;
+};
+/**
+ * The JSON body a platform's incoming-webhook or API endpoint expects.
+ *
+ * Slack and Discord both accept a thread reference, and both are told not to
+ * resolve mentions: Slack via `link_names: false` plus the escaping above,
+ * Discord via `allowed_mentions: { parse: [] }`, which is the only reliable
+ * way to stop `@everyone` in a message body from paging a server.
+ */
+export declare function buildChatPayload(input: {
+    readonly platform: Platform;
+    readonly text: string;
+    readonly threadId?: string | undefined;
+    readonly channel?: string | undefined;
+    readonly username?: string | undefined;
+}): ChatPayload;
+/** Platforms whose posted messages can be edited or deleted by id. */
+export declare const EDITABLE_PLATFORMS: ReadonlySet<Platform>;
+/** Platforms that carry a thread identifier on a post. */
+export declare const THREADED_PLATFORMS: ReadonlySet<Platform>;

package/dist/lib/blocks.js

@@ -0,0 +1,217 @@
+/**
+ * Message structure, and the escaping that keeps a value from becoming it.
+ *
+ * A notification is almost always assembled from data the harness did not
+ * write: a branch name, an error string, a customer's subject line. If that
+ * data reaches a chat platform unescaped it stops being a value and becomes
+ * syntax — `<!channel>` on Slack pages everyone in the room, `@everyone` on
+ * Discord does the same, and a stray ``` turns the rest of the message into
+ * a code block. That is markup injection, and it is the reason this file
+ * exists separately from the tools: escaping is a pure function that can be
+ * tested exhaustively, and every path that puts text on a platform goes
+ * through it.
+ *
+ * The blocks are deliberately few. Five kinds cover a notification — a
+ * heading, a paragraph, a list of name/value fields, a rule, a link — and
+ * each renders to something every platform actually supports. A richer model
+ * would render well on one platform and badly on the others, which is worse
+ * than a plain one that renders the same everywhere.
+ */
+/**
+ * Escape a VALUE for a platform, so it can only ever be read as text.
+ *
+ *  - **slack**: `&`, `<` and `>` are the only three characters Slack treats
+ *    as markup structure, and escaping them is exactly what Slack's own docs
+ *    prescribe. It kills `<!channel>`, `<!here>`, `<@U123>` and the
+ *    `<url|label>` link form in one move. Slack's `*bold*`/`_italic_` marks
+ *    are cosmetic — they cannot change who is notified or where a link goes
+ *    — so they are left alone rather than backslash-littering every message.
+ *  - **discord**: backslash-escape the characters that open markdown
+ *    constructs, so a value cannot close a code fence or start a spoiler.
+ *    Mentions are NOT handled here: Discord has no in-content escape for
+ *    them, and the correct fix is the `allowed_mentions` field on the
+ *    request, which `buildChatPayload` always sets to "parse nothing".
+ *  - **teams**: HTML-escape first, because Teams renders a card's text as
+ *    HTML, then backslash-escape the markdown marks it also honours.
+ *  - **webhook**: identity. A generic webhook receives JSON; JSON encoding
+ *    is the escaping, and mangling the value on the way would corrupt a
+ *    payload nobody asked to be rendered.
+ */
+export function escapeFor(platform, value) {
+    switch (platform) {
+        case "slack":
+            return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+        case "discord":
+            // Only the marks that introduce STRUCTURE: code fences, emphasis,
+            // spoilers, block quotes and links. `#`, `-` and `1.` make a heading or
+            // a list at the start of a line and cannot change what the message
+            // does, so they are left alone rather than littering every hyphen in
+            // every branch name with a backslash.
+            return value.replace(/([\\`*_~|>[\]()])/g, "\\$1");
+        case "teams":
+            return value
+                .replace(/&/g, "&amp;")
+                .replace(/</g, "&lt;")
+                .replace(/>/g, "&gt;")
+                .replace(/([\\`*_~\[\]])/g, "\\$1");
+        case "webhook":
+            return value;
+    }
+}
+/**
+ * Is a URL safe to put behind a link?
+ *
+ * `javascript:`, `data:` and `vbscript:` in a chat message are a phishing
+ * payload aimed at whoever clicks. Only http and https get rendered as
+ * links; anything else is refused rather than silently downgraded, because a
+ * caller who asked for a link and got plain text would not notice.
+ */
+export function linkSchemeAllowed(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === "http:" || parsed.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+/** Render one block for a platform. Values are escaped; structure is not. */
+function renderBlock(platform, block) {
+    switch (block.kind) {
+        case "heading": {
+            const text = escapeFor(platform, block.text);
+            if (platform === "slack")
+                return `*${text}*`;
+            if (platform === "webhook")
+                return block.text;
+            return `**${text}**`;
+        }
+        case "paragraph":
+            return escapeFor(platform, block.text);
+        case "fields": {
+            const lines = block.fields.map((f) => {
+                const name = escapeFor(platform, f.name);
+                const value = escapeFor(platform, f.value);
+                if (platform === "slack")
+                    return `*${name}:* ${value}`;
+                if (platform === "webhook")
+                    return `${f.name}: ${f.value}`;
+                return `**${name}:** ${value}`;
+            });
+            return lines.join("\n");
+        }
+        case "divider":
+            return platform === "slack" ? "───" : "---";
+        case "link": {
+            const label = block.text ?? block.url;
+            if (platform === "slack") {
+                // The URL goes inside Slack's own link syntax unescaped — escaping it
+                // would break the link — but the LABEL is escaped, because a label
+                // containing `|` or `>` would otherwise close the construct early and
+                // let the rest of the label become markup.
+                return `<${block.url}|${escapeFor("slack", label)}>`;
+            }
+            if (platform === "webhook")
+                return `${label}: ${block.url}`;
+            return `[${escapeFor(platform, label)}](${block.url})`;
+        }
+    }
+}
+/**
+ * Render a text body plus blocks into one string for a platform.
+ *
+ * Blocks with an unusable link are dropped and reported rather than
+ * rendered, so a `javascript:` URL never reaches a reader.
+ */
+export function renderBlocks(platform, text, blocks) {
+    const dropped = [];
+    const parts = [];
+    if (text !== undefined && text !== "")
+        parts.push(escapeFor(platform, text));
+    for (const block of blocks) {
+        if (block.kind === "link" && !linkSchemeAllowed(block.url)) {
+            dropped.push("a link block whose URL was not http(s)");
+            continue;
+        }
+        parts.push(renderBlock(platform, block));
+    }
+    return { rendered: parts.join("\n\n"), dropped };
+}
+/** Platform byte/character limits, so a message is cut here rather than there. */
+export const PLATFORM_TEXT_LIMIT = {
+    slack: 40_000,
+    discord: 2_000,
+    teams: 28_000,
+    webhook: 100_000,
+};
+/**
+ * Cut `text` to a platform's limit, marking the cut. Counting is in UTF-16
+ * code units, which is what every one of these platforms documents its limit
+ * in, and the cut never splits a surrogate pair.
+ */
+export function clampToPlatform(platform, text) {
+    const limit = PLATFORM_TEXT_LIMIT[platform];
+    if (text.length <= limit)
+        return { text, truncated: false };
+    const marker = "\n… (truncated)";
+    let cut = limit - marker.length;
+    const code = text.charCodeAt(cut - 1);
+    if (code >= 0xd800 && code <= 0xdbff)
+        cut -= 1; // do not split a surrogate pair
+    return { text: `${text.slice(0, cut)}${marker}`, truncated: true };
+}
+/**
+ * The JSON body a platform's incoming-webhook or API endpoint expects.
+ *
+ * Slack and Discord both accept a thread reference, and both are told not to
+ * resolve mentions: Slack via `link_names: false` plus the escaping above,
+ * Discord via `allowed_mentions: { parse: [] }`, which is the only reliable
+ * way to stop `@everyone` in a message body from paging a server.
+ */
+export function buildChatPayload(input) {
+    const { platform, text } = input;
+    if (platform === "slack") {
+        return {
+            body: JSON.stringify({
+                text,
+                link_names: false,
+                ...(input.channel !== undefined ? { channel: input.channel } : {}),
+                ...(input.threadId !== undefined ? { thread_ts: input.threadId } : {}),
+                ...(input.username !== undefined ? { username: input.username } : {}),
+            }),
+            contentType: "application/json",
+        };
+    }
+    if (platform === "discord") {
+        return {
+            body: JSON.stringify({
+                content: text,
+                allowed_mentions: { parse: [] },
+                ...(input.username !== undefined ? { username: input.username } : {}),
+            }),
+            contentType: "application/json",
+        };
+    }
+    if (platform === "teams") {
+        return {
+            body: JSON.stringify({
+                "@type": "MessageCard",
+                "@context": "https://schema.org/extensions",
+                text,
+            }),
+            contentType: "application/json",
+        };
+    }
+    return {
+        body: JSON.stringify({
+            text,
+            ...(input.channel !== undefined ? { channel: input.channel } : {}),
+            ...(input.threadId !== undefined ? { threadId: input.threadId } : {}),
+        }),
+        contentType: "application/json",
+    };
+}
+/** Platforms whose posted messages can be edited or deleted by id. */
+export const EDITABLE_PLATFORMS = new Set(["slack", "discord"]);
+/** Platforms that carry a thread identifier on a post. */
+export const THREADED_PLATFORMS = new Set(["slack", "discord"]);

package/dist/lib/digest.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Folding many events into one message.
+ *
+ * This is the function that stops a harness sending forty notifications when
+ * one would do. A watcher loop that fires per event will, on a bad morning,
+ * page a channel forty times with the same failure; a digest turns that into
+ * "38× connection refused (host-a, host-b), 2× timeout" and the reader
+ * learns more from it.
+ *
+ * Pure, and deliberately boring about order: groups are ranked by count and
+ * ties are broken by key, with a plain codepoint comparison rather than
+ * `localeCompare`, so the same events always fold to the same bytes.
+ */
+import type { Block } from "./blocks";
+export type DigestEvent = {
+    /** What makes two events "the same". Events sharing a key are counted. */
+    readonly key: string;
+    /** One line about this occurrence. The first one seen is the exemplar. */
+    readonly summary?: string;
+    /** Free-form labels; distinct values are listed under the group. */
+    readonly labels?: Readonly<Record<string, string>>;
+    /** Severity, used only for ordering when `sort` is "severity". */
+    readonly severity?: "info" | "warning" | "error" | "critical";
+};
+export type DigestGroup = {
+    readonly key: string;
+    readonly count: number;
+    readonly summary?: string;
+    readonly severity?: DigestEvent["severity"];
+    /** label name → the distinct values seen, sorted and capped. */
+    readonly labels: Readonly<Record<string, readonly string[]>>;
+};
+export type Digest = {
+    readonly total: number;
+    readonly distinct: number;
+    readonly groups: readonly DigestGroup[];
+    /** Groups that did not fit under `maxGroups`, and how many events they held. */
+    readonly omittedGroups: number;
+    readonly omittedEvents: number;
+};
+/**
+ * Fold events into groups.
+ *
+ * `maxGroups` caps what is rendered, not what is counted: the totals always
+ * describe every event handed in, and the omitted tail is reported as a
+ * number rather than dropped silently. A digest that quietly loses events is
+ * the failure mode that makes people distrust digests.
+ */
+export declare function buildDigest(events: readonly DigestEvent[], options?: {
+    readonly maxGroups?: number;
+    readonly sort?: "count" | "severity" | "key";
+}): Digest;
+/** One line per group: `12× build failed — host: a, b`. */
+export declare function digestToText(digest: Digest, title?: string): string;
+/** The same digest as blocks, for a platform that renders them. */
+export declare function digestToBlocks(digest: Digest, title?: string): Block[];

package/dist/lib/digest.js

@@ -0,0 +1,140 @@
+const SEVERITY_RANK = {
+    critical: 0,
+    error: 1,
+    warning: 2,
+    info: 3,
+};
+function byString(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** Cap on distinct values listed per label, so one group cannot flood the digest. */
+const MAX_LABEL_VALUES = 8;
+/**
+ * Fold events into groups.
+ *
+ * `maxGroups` caps what is rendered, not what is counted: the totals always
+ * describe every event handed in, and the omitted tail is reported as a
+ * number rather than dropped silently. A digest that quietly loses events is
+ * the failure mode that makes people distrust digests.
+ */
+export function buildDigest(events, options = {}) {
+    const maxGroups = Math.max(1, options.maxGroups ?? 10);
+    const sort = options.sort ?? "count";
+    const groups = new Map();
+    events.forEach((event, index) => {
+        let group = groups.get(event.key);
+        if (group === undefined) {
+            group = {
+                key: event.key,
+                count: 0,
+                labels: new Map(),
+                firstIndex: index,
+                ...(event.summary !== undefined ? { summary: event.summary } : {}),
+                ...(event.severity !== undefined ? { severity: event.severity } : {}),
+            };
+            groups.set(event.key, group);
+        }
+        group.count += 1;
+        // The most severe occurrence wins: a group that was warning-then-critical
+        // is a critical group, and rendering it as a warning would understate it.
+        if (event.severity !== undefined) {
+            const current = group.severity;
+            if (current === undefined ||
+                (SEVERITY_RANK[event.severity] ?? 9) < (SEVERITY_RANK[current] ?? 9)) {
+                group.severity = event.severity;
+            }
+        }
+        for (const [name, value] of Object.entries(event.labels ?? {})) {
+            let values = group.labels.get(name);
+            if (values === undefined) {
+                values = new Set();
+                group.labels.set(name, values);
+            }
+            values.add(value);
+        }
+    });
+    const ordered = [...groups.values()].sort((a, b) => {
+        if (sort === "key")
+            return byString(a.key, b.key);
+        if (sort === "severity") {
+            const sa = SEVERITY_RANK[a.severity ?? "info"] ?? 9;
+            const sb = SEVERITY_RANK[b.severity ?? "info"] ?? 9;
+            if (sa !== sb)
+                return sa - sb;
+        }
+        if (b.count !== a.count)
+            return b.count - a.count;
+        return byString(a.key, b.key);
+    });
+    const kept = ordered.slice(0, maxGroups);
+    const omitted = ordered.slice(maxGroups);
+    return {
+        total: events.length,
+        distinct: ordered.length,
+        omittedGroups: omitted.length,
+        omittedEvents: omitted.reduce((sum, g) => sum + g.count, 0),
+        groups: kept.map((group) => {
+            const labels = {};
+            for (const name of [...group.labels.keys()].sort(byString)) {
+                const values = [...(group.labels.get(name) ?? new Set())].sort(byString);
+                labels[name] = values.slice(0, MAX_LABEL_VALUES);
+            }
+            return {
+                key: group.key,
+                count: group.count,
+                labels,
+                ...(group.summary !== undefined ? { summary: group.summary } : {}),
+                ...(group.severity !== undefined ? { severity: group.severity } : {}),
+            };
+        }),
+    };
+}
+/** One line per group: `12× build failed — host: a, b`. */
+export function digestToText(digest, title) {
+    const lines = [];
+    if (title !== undefined && title !== "")
+        lines.push(title);
+    lines.push(`${digest.total} events in ${digest.distinct} groups`);
+    for (const group of digest.groups) {
+        const labelText = Object.entries(group.labels)
+            .map(([name, values]) => `${name}: ${values.join(", ")}`)
+            .join("; ");
+        const head = `${group.count}× ${group.summary ?? group.key}`;
+        const severity = group.severity !== undefined ? ` [${group.severity}]` : "";
+        lines.push(`${head}${severity}${labelText === "" ? "" : ` — ${labelText}`}`);
+    }
+    if (digest.omittedGroups > 0) {
+        lines.push(`…and ${digest.omittedGroups} more groups covering ${digest.omittedEvents} events, not shown`);
+    }
+    return lines.join("\n");
+}
+/** The same digest as blocks, for a platform that renders them. */
+export function digestToBlocks(digest, title) {
+    const blocks = [];
+    if (title !== undefined && title !== "")
+        blocks.push({ kind: "heading", text: title });
+    blocks.push({
+        kind: "paragraph",
+        text: `${digest.total} events in ${digest.distinct} groups`,
+    });
+    blocks.push({ kind: "divider" });
+    for (const group of digest.groups) {
+        const fields = [
+            { name: "count", value: String(group.count) },
+        ];
+        if (group.severity !== undefined)
+            fields.push({ name: "severity", value: group.severity });
+        for (const [name, values] of Object.entries(group.labels)) {
+            fields.push({ name, value: values.join(", ") });
+        }
+        blocks.push({ kind: "paragraph", text: group.summary ?? group.key });
+        blocks.push({ kind: "fields", fields });
+    }
+    if (digest.omittedGroups > 0) {
+        blocks.push({
+            kind: "paragraph",
+            text: `…and ${digest.omittedGroups} more groups covering ${digest.omittedEvents} events, not shown`,
+        });
+    }
+    return blocks;
+}