@worca/ui 0.9.0-rc.1 → 0.9.0-rc.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@worca/ui",
-  "version": "0.9.0-rc.1",
+  "version": "0.9.0-rc.2",
   "description": "Pipeline monitoring UI for worca-cc",
   "license": "MIT",
   "author": "Sinisha Djukic",
@@ -23,9 +23,10 @@
   },
   "files": [
     "bin/worca-ui.js",
-    "server/*.js",
-    "!server/*.test.js",
-    "!server/test/",
+    "server/**/*.js",
+    "!server/**/*.test.js",
+    "!server/test/**",
+    "!server/**/test/**",
     "app/favicon-*.svg",
     "app/index.html",
     "app/main.bundle.js",

package/server/integrations/adapter.js

@@ -0,0 +1,91 @@
+/**
+ * @typedef {('text'|'bold'|'code'|'code_block'|'link')} MessageSegmentKind
+ *
+ * @typedef {{
+ *   kind: MessageSegmentKind,
+ *   value: string,
+ *   href?: string
+ * }} MessageSegment
+ *
+ * @typedef {{
+ *   title: string|null,
+ *   body: MessageSegment[],
+ *   severity: 'info'|'success'|'warning'|'error'
+ * }} NormalizedMessage
+ *
+ * @typedef {{
+ *   platform: string,
+ *   chatId: string,
+ *   userId: string,
+ *   text: string,
+ *   raw: object
+ * }} IncomingMessage
+ *
+ * @typedef {object} ChatAdapter
+ * @property {string} name
+ * @property {boolean} supportsInbound
+ * @property {() => Promise<void>} start
+ * @property {() => Promise<void>} stop
+ * @property {(chatId: string, msg: NormalizedMessage) => Promise<void>} send
+ * @property {(cb: (msg: IncomingMessage) => void) => void} onInbound
+ */
+
+export const MESSAGE_SEGMENT_KINDS = [
+  'text',
+  'bold',
+  'code',
+  'code_block',
+  'link',
+  'markdown',
+];
+
+export const SEVERITY_LEVELS = ['info', 'success', 'warning', 'error'];
+
+export const ADAPTER_INTERFACE_KEYS = [
+  'name',
+  'supportsInbound',
+  'start',
+  'stop',
+  'send',
+  'onInbound',
+];
+
+/** @param {unknown} seg @returns {seg is MessageSegment} */
+export function isValidSegment(seg) {
+  if (!seg || typeof seg !== 'object') return false;
+  return (
+    MESSAGE_SEGMENT_KINDS.includes(seg.kind) && typeof seg.value === 'string'
+  );
+}
+
+/** @param {unknown} msg @returns {msg is NormalizedMessage} */
+export function isValidMessage(msg) {
+  if (!msg || typeof msg !== 'object') return false;
+  if (msg.title !== null && typeof msg.title !== 'string') return false;
+  if (!Array.isArray(msg.body) || !msg.body.every(isValidSegment)) return false;
+  return SEVERITY_LEVELS.includes(msg.severity);
+}
+
+/** @param {unknown} inc @returns {inc is IncomingMessage} */
+export function isValidIncoming(inc) {
+  if (!inc || typeof inc !== 'object') return false;
+  return (
+    typeof inc.platform === 'string' &&
+    typeof inc.chatId === 'string' &&
+    typeof inc.userId === 'string' &&
+    typeof inc.text === 'string' &&
+    inc.raw !== undefined
+  );
+}
+
+/** @param {unknown} adapter @returns {adapter is ChatAdapter} */
+export function isValidAdapter(adapter) {
+  if (!adapter || typeof adapter !== 'object') return false;
+  return (
+    typeof adapter.name === 'string' &&
+    typeof adapter.supportsInbound === 'boolean' &&
+    typeof adapter.start === 'function' &&
+    typeof adapter.send === 'function' &&
+    typeof adapter.onInbound === 'function'
+  );
+}

package/server/integrations/adapters/discord.js

@@ -0,0 +1,109 @@
+/**
+ * Discord adapter — outbound only, REST POST /channels/{id}/messages (markdown).
+ * @module adapters/discord
+ */
+
+const DISCORD_API = 'https://discord.com/api/v10';
+const SEND_BACKOFF_DELAYS = [1000, 5000, 30000];
+
+// ---------------------------------------------------------------------------
+// Markdown renderer
+// ---------------------------------------------------------------------------
+
+/**
+ * Render a NormalizedMessage to Discord markdown.
+ * @param {import('../adapter.js').NormalizedMessage} msg
+ * @returns {string}
+ */
+export function renderToMarkdown(msg) {
+  const parts = [];
+  if (msg.title) {
+    parts.push(`**${msg.title}**\n`);
+  }
+  for (const seg of msg.body) {
+    switch (seg.kind) {
+      case 'markdown':
+        parts.push(seg.value);
+        break;
+      case 'bold':
+        parts.push(`**${seg.value}**`);
+        break;
+      case 'code':
+        parts.push(`\`${seg.value}\``);
+        break;
+      case 'code_block':
+        parts.push(`\`\`\`\n${seg.value}\n\`\`\``);
+        break;
+      case 'link':
+        parts.push(`[${seg.value}](${seg.href ?? ''})`);
+        break;
+      default: // 'text'
+        parts.push(seg.value);
+    }
+  }
+  return parts.join('');
+}
+
+// ---------------------------------------------------------------------------
+// Adapter factory
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {{
+ *   botToken: string,
+ *   channelId?: string,
+ *   fetchFn?: typeof fetch,
+ *   _sleep?: (ms: number) => Promise<void>
+ * }} options
+ * @returns {import('../adapter.js').ChatAdapter}
+ */
+export function createDiscordAdapter({
+  botToken,
+  channelId: _defaultChannelId,
+  fetchFn = globalThis.fetch,
+  _sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+}) {
+  const authHeader = botToken.startsWith('Bot ') ? botToken : `Bot ${botToken}`;
+
+  return {
+    name: 'discord',
+    supportsInbound: false,
+    persistent: false,
+
+    connectionState() {
+      return { state: 'n/a', error: null };
+    },
+
+    async start() {},
+    async stop() {},
+
+    async send(chatId, msg) {
+      const content = renderToMarkdown(msg);
+      const url = `${DISCORD_API}/channels/${chatId}/messages`;
+      const body = JSON.stringify({ content });
+      const headers = {
+        'Content-Type': 'application/json',
+        Authorization: authHeader,
+      };
+
+      for (let attempt = 0; attempt <= SEND_BACKOFF_DELAYS.length; attempt++) {
+        const res = await fetchFn(url, { method: 'POST', headers, body });
+        if (res.status !== 429) {
+          if (!res.ok)
+            console.warn(`[discord] send failed: HTTP ${res.status}`);
+          return;
+        }
+        if (attempt === SEND_BACKOFF_DELAYS.length) {
+          console.warn('[discord] send dropped after retries (429)');
+          return;
+        }
+        const data = await res.json().catch(() => ({}));
+        const ms =
+          (data.retry_after ?? 0) * 1000 || SEND_BACKOFF_DELAYS[attempt];
+        await _sleep(ms);
+      }
+    },
+
+    onInbound(_cb) {},
+  };
+}

package/server/integrations/adapters/slack.js

@@ -0,0 +1,106 @@
+/**
+ * Slack adapter — outbound only, POST to incoming webhook URL (mrkdwn).
+ * @module adapters/slack
+ */
+
+import { toSlackMrkdwn } from '../markdown.js';
+
+const SEND_BACKOFF_DELAYS = [1000, 5000, 30000];
+
+// ---------------------------------------------------------------------------
+// mrkdwn renderer
+// ---------------------------------------------------------------------------
+
+/**
+ * Render a NormalizedMessage to Slack mrkdwn.
+ * @param {import('../adapter.js').NormalizedMessage} msg
+ * @returns {string}
+ */
+export function renderToMrkdwn(msg) {
+  const parts = [];
+  if (msg.title) {
+    parts.push(`*${msg.title}*\n`);
+  }
+  for (const seg of msg.body) {
+    switch (seg.kind) {
+      case 'markdown':
+        parts.push(toSlackMrkdwn(seg.value));
+        break;
+      case 'bold':
+        parts.push(`*${seg.value}*`);
+        break;
+      case 'code':
+        parts.push(`\`${seg.value}\``);
+        break;
+      case 'code_block':
+        parts.push(`\`\`\`\n${seg.value}\n\`\`\``);
+        break;
+      case 'link':
+        parts.push(`<${seg.href ?? ''}|${seg.value}>`);
+        break;
+      default: // 'text'
+        parts.push(seg.value);
+    }
+  }
+  return parts.join('');
+}
+
+// ---------------------------------------------------------------------------
+// Adapter factory
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {{
+ *   webhookUrl?: string,
+ *   fetchFn?: typeof fetch,
+ *   _sleep?: (ms: number) => Promise<void>
+ * }} options
+ * @returns {import('../adapter.js').ChatAdapter}
+ */
+export function createSlackAdapter({
+  webhookUrl = process.env.SLACK_WEBHOOK_URL,
+  fetchFn = globalThis.fetch,
+  _sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+} = {}) {
+  return {
+    name: 'slack',
+    supportsInbound: false,
+    persistent: false,
+
+    connectionState() {
+      return { state: 'n/a', error: null };
+    },
+
+    async start() {},
+    async stop() {},
+
+    async send(_chatId, msg) {
+      const text = renderToMrkdwn(msg);
+      const body = JSON.stringify({ text });
+      const headers = { 'Content-Type': 'application/json' };
+
+      for (let attempt = 0; attempt <= SEND_BACKOFF_DELAYS.length; attempt++) {
+        const res = await fetchFn(webhookUrl, {
+          method: 'POST',
+          headers,
+          body,
+        });
+        if (res.status !== 429) {
+          if (!res.ok) console.warn(`[slack] send failed: HTTP ${res.status}`);
+          return;
+        }
+        if (attempt === SEND_BACKOFF_DELAYS.length) {
+          console.warn('[slack] send dropped after retries (429)');
+          return;
+        }
+        const retryAfter = res.headers?.get('retry-after');
+        const ms = retryAfter
+          ? Number(retryAfter) * 1000
+          : SEND_BACKOFF_DELAYS[attempt];
+        await _sleep(ms);
+      }
+    },
+
+    onInbound(_cb) {},
+  };
+}

package/server/integrations/adapters/telegram.js

@@ -0,0 +1,228 @@
+/**
+ * Telegram adapter — two-way, long-poll getUpdates + sendMessage (HTML parse_mode).
+ * @module adapters/telegram
+ */
+
+import { mkdir, open, readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { toTelegramHtml } from '../markdown.js';
+
+const TELEGRAM_API = 'https://api.telegram.org';
+const LONG_POLL_TIMEOUT_SEC = 30;
+const SEND_BACKOFF_DELAYS = [1000, 5000, 30000];
+
+// ---------------------------------------------------------------------------
+// HTML escaping + renderer
+// ---------------------------------------------------------------------------
+
+function escapeHtml(text) {
+  return String(text)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/**
+ * Render a NormalizedMessage to Telegram HTML.
+ * @param {import('../adapter.js').NormalizedMessage} msg
+ * @returns {string}
+ */
+export function renderToHtml(msg) {
+  const parts = [];
+  if (msg.title) {
+    parts.push(`<b>${escapeHtml(msg.title)}</b>\n`);
+  }
+  for (const seg of msg.body) {
+    switch (seg.kind) {
+      case 'markdown':
+        parts.push(toTelegramHtml(seg.value));
+        break;
+      case 'bold':
+        parts.push(`<b>${escapeHtml(seg.value)}</b>`);
+        break;
+      case 'code':
+        parts.push(`<code>${escapeHtml(seg.value)}</code>`);
+        break;
+      case 'code_block':
+        parts.push(`<pre>${escapeHtml(seg.value)}</pre>`);
+        break;
+      case 'link':
+        parts.push(
+          `<a href="${escapeHtml(seg.href ?? '')}">${escapeHtml(seg.value)}</a>`,
+        );
+        break;
+      default: // 'text'
+        parts.push(escapeHtml(seg.value));
+    }
+  }
+  return parts.join('');
+}
+
+// ---------------------------------------------------------------------------
+// Cursor persistence (fsynced)
+// ---------------------------------------------------------------------------
+
+async function readCursor(cursorPath) {
+  try {
+    const data = await readFile(cursorPath, 'utf8');
+    const n = parseInt(data.trim(), 10);
+    return Number.isFinite(n) ? n : 0;
+  } catch {
+    return 0;
+  }
+}
+
+async function writeCursor(cursorPath, offset) {
+  await mkdir(dirname(cursorPath), { recursive: true });
+  const fh = await open(cursorPath, 'w');
+  try {
+    await fh.write(String(offset));
+    await fh.datasync();
+  } finally {
+    await fh.close();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Adapter factory
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {{
+ *   token: string,
+ *   cursorPath: string,
+ *   fetchFn?: typeof fetch,
+ *   _sleep?: (ms: number) => Promise<void>
+ * }} options
+ * @returns {import('../adapter.js').ChatAdapter}
+ */
+export function createTelegramAdapter({
+  token,
+  cursorPath,
+  fetchFn = globalThis.fetch,
+  _sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+}) {
+  let inboundCb = null;
+  let running = false;
+  // Connection health tracking
+  let connState = 'connecting'; // 'connecting' | 'connected' | 'disconnected'
+  let connError = null;
+  let lastPollOk = null; // ISO timestamp of last successful poll
+
+  async function pollLoop() {
+    let cursor = await readCursor(cursorPath);
+    while (running) {
+      try {
+        const url =
+          `${TELEGRAM_API}/bot${token}/getUpdates` +
+          `?offset=${cursor}&timeout=${LONG_POLL_TIMEOUT_SEC}`;
+        const res = await fetchFn(url);
+        if (res.status === 429) {
+          const data = await res.json().catch(() => ({}));
+          const ms = (data.parameters?.retry_after ?? 1) * 1000;
+          await _sleep(ms);
+          continue;
+        }
+        if (!res.ok) {
+          connState = 'disconnected';
+          connError = `HTTP ${res.status}`;
+          if (running) await _sleep(5000);
+          continue;
+        }
+        connState = 'connected';
+        connError = null;
+        lastPollOk = new Date().toISOString();
+        const data = await res.json();
+        if (data.ok && data.result.length > 0) {
+          for (const update of data.result) {
+            cursor = update.update_id + 1;
+            if (inboundCb && update.message) {
+              const m = update.message;
+              inboundCb({
+                platform: 'telegram',
+                chatId: String(m.chat.id),
+                userId: String(m.from?.id ?? m.chat.id),
+                text: m.text ?? '',
+                raw: update,
+              });
+            }
+          }
+          await writeCursor(cursorPath, cursor);
+        }
+      } catch (err) {
+        connState = 'disconnected';
+        connError = err.message;
+        console.error('[telegram] poll error:', err.message);
+        if (running) await _sleep(1000);
+      }
+    }
+  }
+
+  return {
+    name: 'telegram',
+    supportsInbound: true,
+    persistent: true,
+
+    connectionState() {
+      // If the last successful poll is older than 2× the poll timeout,
+      // the connection is stale (e.g. network dropped, fetch is hanging).
+      let effectiveState = connState;
+      let effectiveError = connError;
+      if (connState === 'connected' && lastPollOk) {
+        const staleMs = (LONG_POLL_TIMEOUT_SEC * 2 + 10) * 1000; // ~70s
+        if (Date.now() - new Date(lastPollOk).getTime() > staleMs) {
+          effectiveState = 'disconnected';
+          effectiveError = 'Connection stale — no poll response';
+        }
+      }
+      return { state: effectiveState, error: effectiveError, lastPollOk };
+    },
+
+    async start() {
+      running = true;
+      connState = 'connecting';
+      connError = null;
+      pollLoop().catch((err) =>
+        console.error('[telegram] fatal poll error:', err.message),
+      );
+    },
+
+    async stop() {
+      running = false;
+    },
+
+    async send(chatId, msg) {
+      const text = renderToHtml(msg);
+      const url = `${TELEGRAM_API}/bot${token}/sendMessage`;
+      const body = JSON.stringify({
+        chat_id: chatId,
+        text,
+        parse_mode: 'HTML',
+      });
+      const headers = { 'Content-Type': 'application/json' };
+
+      for (let attempt = 0; attempt <= SEND_BACKOFF_DELAYS.length; attempt++) {
+        const res = await fetchFn(url, { method: 'POST', headers, body });
+        if (res.status !== 429) {
+          if (!res.ok)
+            console.warn(`[telegram] sendMessage failed: HTTP ${res.status}`);
+          return;
+        }
+        if (attempt === SEND_BACKOFF_DELAYS.length) {
+          console.warn('[telegram] sendMessage dropped after retries (429)');
+          return;
+        }
+        const data = await res.json().catch(() => ({}));
+        const ms =
+          (data.parameters?.retry_after ?? 0) * 1000 ||
+          SEND_BACKOFF_DELAYS[attempt];
+        await _sleep(ms);
+      }
+    },
+
+    onInbound(cb) {
+      inboundCb = cb;
+    },
+  };
+}