docs: enterprise refactor plan with ralph specs

dist/server/notifications/NotificationService.js

@@ -0,0 +1,121 @@
+"use strict";
+/**
+ * NotificationService — orchestrates notifiers.
+ * Called after every anomaly:detected event.
+ * Persists notification attempts to the notifications table.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotificationService = void 0;
+const crypto = __importStar(require("crypto"));
+const SlackNotifier_1 = require("./SlackNotifier");
+const WebhookNotifier_1 = require("./WebhookNotifier");
+const SEVERITY_RANK = { low: 0, medium: 1, high: 2, critical: 3 };
+class NotificationService {
+    constructor(config) {
+        const slackUrl = config?.slackWebhookUrl ?? process.env['ABE_SLACK_WEBHOOK_URL'];
+        const webhookUrl = config?.webhookUrl ?? process.env['ABE_WEBHOOK_URL'];
+        const minSeverity = config?.minSeverity ?? process.env['ABE_NOTIFY_MIN_SEVERITY'] ?? 'high';
+        const frontendBase = config?.frontendBaseUrl ?? process.env['ABE_CORS_ORIGIN'] ?? 'http://localhost:5173';
+        if (slackUrl)
+            this.slack = new SlackNotifier_1.SlackNotifier(slackUrl, frontendBase);
+        if (webhookUrl)
+            this.webhook = new WebhookNotifier_1.WebhookNotifier(webhookUrl);
+        this.minSeverityRank = SEVERITY_RANK[minSeverity] ?? 2;
+        this.persister = config?.persister;
+    }
+    async notify(anomaly, sessionId, targetUrl) {
+        const anomalySeverityRank = SEVERITY_RANK[anomaly.severity] ?? 0;
+        if (anomalySeverityRank < this.minSeverityRank)
+            return;
+        const sends = [];
+        if (this.slack) {
+            sends.push(this.sendWithRetry('slack', anomaly, sessionId, targetUrl));
+        }
+        if (this.webhook) {
+            sends.push(this.sendWithRetry('webhook', anomaly, sessionId, targetUrl));
+        }
+        await Promise.allSettled(sends);
+    }
+    async sendWithRetry(channel, anomaly, sessionId, targetUrl) {
+        const record = {
+            id: crypto.randomUUID(),
+            anomalyId: anomaly.id,
+            channel,
+            status: 'pending',
+        };
+        try {
+            await this.doSend(channel, anomaly, sessionId, targetUrl);
+            record.status = 'success';
+            record.sentAt = Date.now();
+            this.persister?.(record);
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            // Retry once after 60s
+            setTimeout(async () => {
+                const retryRecord = {
+                    id: crypto.randomUUID(),
+                    anomalyId: anomaly.id,
+                    channel,
+                    status: 'pending',
+                };
+                try {
+                    await this.doSend(channel, anomaly, sessionId, targetUrl);
+                    retryRecord.status = 'success';
+                    retryRecord.sentAt = Date.now();
+                    this.persister?.(retryRecord);
+                }
+                catch (retryErr) {
+                    retryRecord.status = 'failed';
+                    retryRecord.error = retryErr instanceof Error ? retryErr.message : String(retryErr);
+                    this.persister?.(retryRecord);
+                }
+            }, 60000);
+            record.status = 'failed';
+            record.error = errMsg;
+            this.persister?.(record);
+        }
+    }
+    async doSend(channel, anomaly, sessionId, targetUrl) {
+        if (channel === 'slack' && this.slack) {
+            await this.slack.send(anomaly, sessionId, targetUrl);
+        }
+        else if (channel === 'webhook' && this.webhook) {
+            await this.webhook.send(anomaly);
+        }
+    }
+}
+exports.NotificationService = NotificationService;

dist/server/notifications/SlackNotifier.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * SlackNotifier — sends anomaly notifications to a Slack webhook.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SlackNotifier = void 0;
+const SEVERITY_EMOJI = {
+    low: ':blue_circle:',
+    medium: ':yellow_circle:',
+    high: ':red_circle:',
+    critical: ':rotating_light:',
+};
+class SlackNotifier {
+    constructor(webhookUrl, frontendBaseUrl = 'http://localhost:5173') {
+        this.webhookUrl = webhookUrl;
+        this.frontendBaseUrl = frontendBaseUrl;
+    }
+    async send(anomaly, sessionId, targetUrl) {
+        const emoji = SEVERITY_EMOJI[anomaly.severity] ?? ':warning:';
+        const payload = {
+            text: '🐛 ABE found a bug!',
+            blocks: [
+                {
+                    type: 'section',
+                    text: {
+                        type: 'mrkdwn',
+                        text: `*ABE Bug Report*\n` +
+                            `*Severity:* ${emoji} ${anomaly.severity.toUpperCase()}\n` +
+                            `*Type:* ${anomaly.type}\n` +
+                            `*Description:* ${anomaly.description}\n` +
+                            `*Session:* ${sessionId}\n` +
+                            `*Target:* ${targetUrl}`,
+                    },
+                },
+                {
+                    type: 'actions',
+                    elements: [
+                        {
+                            type: 'button',
+                            text: { type: 'plain_text', text: 'View Report' },
+                            url: `${this.frontendBaseUrl}/anomalies/${anomaly.id}`,
+                        },
+                    ],
+                },
+            ],
+        };
+        const res = await fetch(this.webhookUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(payload),
+        });
+        if (!res.ok) {
+            throw new Error(`Slack webhook returned ${res.status}: ${await res.text()}`);
+        }
+    }
+}
+exports.SlackNotifier = SlackNotifier;

dist/server/notifications/WebhookNotifier.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * WebhookNotifier — posts full anomaly JSON to a generic webhook URL.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookNotifier = void 0;
+class WebhookNotifier {
+    constructor(webhookUrl) {
+        this.webhookUrl = webhookUrl;
+    }
+    async send(anomaly) {
+        const res = await fetch(this.webhookUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-ABE-Event': 'anomaly.detected',
+            },
+            body: JSON.stringify(anomaly),
+        });
+        if (!res.ok) {
+            throw new Error(`Webhook returned ${res.status}: ${await res.text()}`);
+        }
+    }
+}
+exports.WebhookNotifier = WebhookNotifier;