@link-assistant/hive-mind 2.13.1 → 2.13.2

package/src/telegram-markdown-validator.lib.mjs

@@ -0,0 +1,192 @@
+/**
+ * Faithful port of TDLib's legacy-Markdown parser used by the Telegram Bot API
+ * (`parse_mode: 'Markdown'`), so the bot can tell *before* sending whether
+ * Telegram will reject a message with
+ * `Bad Request: can't parse entities: Can't find end of the entity starting at byte offset N`.
+ *
+ * Reference implementation: td/telegram/MessageEntity.cpp — `parse_markdown()`
+ * https://github.com/tdlib/td/blob/master/td/telegram/MessageEntity.cpp
+ *
+ * The two properties that matter for this repository (issue #2166):
+ *
+ *  1. Only `\_`, `\*`, `` \` `` and `\[` are recognised as escape sequences, and
+ *     **only at top level**. Inside an entity (for example the label of a
+ *     `[label](url)` link) every byte is copied verbatim, so `\_` there is shown
+ *     to the user as a literal backslash + underscore.
+ *  2. An unterminated `_`, `*`, `` ` `` or `[` makes the whole message fail with
+ *     HTTP 400 and a *byte* offset pointing at the opening character.
+ *
+ * @module telegram-markdown-validator.lib
+ * @see https://github.com/link-assistant/hive-mind/issues/2166
+ */
+
+const UNDERSCORE = 0x5f; // _
+const ASTERISK = 0x2a; // *
+const BACKTICK = 0x60; // `
+const OPEN_BRACKET = 0x5b; // [
+const CLOSE_BRACKET = 0x5d; // ]
+const BACKSLASH = 0x5c; // \
+const OPEN_PAREN = 0x28; // (
+const CLOSE_PAREN = 0x29; // )
+const LF = 0x0a;
+const CR = 0x0d;
+
+/** Parse modes this module knows how to validate. */
+export const VALIDATABLE_PARSE_MODES = Object.freeze(['Markdown']);
+
+function isUtf8CharacterFirstCodeUnit(byte) {
+  return (byte & 0xc0) !== 0x80;
+}
+
+function isSpaceByte(byte) {
+  return byte === 0x20 || byte === 0x09 || byte === LF || byte === 0x0b || byte === 0x0c || byte === CR;
+}
+
+/**
+ * Parse `text` exactly like TDLib's `parse_markdown()`.
+ *
+ * @param {string} text - Message text as it would be sent with `parse_mode: 'Markdown'`.
+ * @returns {{ok: true, text: string, entities: Array<{type: string, offset: number, length: number, url?: string}>}
+ *          |{ok: false, byteOffset: number, description: string}}
+ *   On success, the rendered plain text (escapes removed, markup consumed) plus
+ *   the entities Telegram would create. On failure, the byte offset of the
+ *   unterminated entity and the exact Bot API error description.
+ */
+export function parseTelegramLegacyMarkdown(text) {
+  const source = Buffer.from(String(text ?? ''), 'utf-8');
+  const size = source.length;
+  // TDLib relies on std::string's NUL terminator when it peeks past the end.
+  const at = index => (index >= 0 && index < size ? source[index] : 0);
+
+  const out = Buffer.alloc(size);
+  let resultSize = 0;
+  let utf16Offset = 0;
+  const entities = [];
+
+  for (let i = 0; i < size; i++) {
+    const c = source[i];
+    if (c === BACKSLASH && (at(i + 1) === UNDERSCORE || at(i + 1) === ASTERISK || at(i + 1) === BACKTICK || at(i + 1) === OPEN_BRACKET)) {
+      i++;
+      out[resultSize++] = source[i];
+      utf16Offset++;
+      continue;
+    }
+    if (c !== UNDERSCORE && c !== ASTERISK && c !== BACKTICK && c !== OPEN_BRACKET) {
+      if (isUtf8CharacterFirstCodeUnit(c)) utf16Offset += 1 + (c >= 0xf0 ? 1 : 0);
+      out[resultSize++] = source[i];
+      continue;
+    }
+
+    // We are at the beginning of an entity.
+    const beginPos = i;
+    let endCharacter = c;
+    let isPre = false;
+    if (c === OPEN_BRACKET) endCharacter = CLOSE_BRACKET;
+
+    i++;
+
+    let language = '';
+    if (c === BACKTICK && at(i) === BACKTICK && at(i + 1) === BACKTICK) {
+      i += 2;
+      isPre = true;
+      let languageEnd = i;
+      while (!isSpaceByte(at(languageEnd)) && at(languageEnd) !== BACKTICK) languageEnd++;
+      if (i !== languageEnd && languageEnd < size && at(languageEnd) !== BACKTICK) {
+        language = source.slice(i, languageEnd).toString('utf-8');
+        i = languageEnd;
+      }
+      // Skip one newline at the beginning of the text.
+      if (at(i) === LF || at(i) === CR) {
+        if ((at(i + 1) === LF || at(i + 1) === CR) && at(i) !== at(i + 1)) i += 2;
+        else i++;
+      }
+    }
+
+    const entityOffset = utf16Offset;
+    while (i < size && (source[i] !== endCharacter || (isPre && !(at(i + 1) === BACKTICK && at(i + 2) === BACKTICK)))) {
+      const cur = source[i];
+      if (isUtf8CharacterFirstCodeUnit(cur)) utf16Offset += 1 + (cur >= 0xf0 ? 1 : 0);
+      out[resultSize++] = source[i++];
+    }
+    if (i === size) {
+      return {
+        ok: false,
+        byteOffset: beginPos,
+        description: `Bad Request: can't parse entities: Can't find end of the entity starting at byte offset ${beginPos}`,
+      };
+    }
+
+    if (entityOffset !== utf16Offset) {
+      const entityLength = utf16Offset - entityOffset;
+      if (c === UNDERSCORE) entities.push({ type: 'italic', offset: entityOffset, length: entityLength });
+      else if (c === ASTERISK) entities.push({ type: 'bold', offset: entityOffset, length: entityLength });
+      else if (c === OPEN_BRACKET) {
+        let url;
+        if (at(i + 1) !== OPEN_PAREN) {
+          url = source.slice(beginPos + 1, i).toString('utf-8');
+        } else {
+          i += 2;
+          const urlStart = i;
+          while (i < size && source[i] !== CLOSE_PAREN) i++;
+          url = source.slice(urlStart, i).toString('utf-8');
+        }
+        if (url) entities.push({ type: 'text_link', offset: entityOffset, length: entityLength, url });
+      } else if (c === BACKTICK) {
+        if (isPre) entities.push({ type: 'pre', offset: entityOffset, length: entityLength, ...(language ? { language } : {}) });
+        else entities.push({ type: 'code', offset: entityOffset, length: entityLength });
+      }
+    }
+    if (isPre) i += 2;
+  }
+
+  return { ok: true, text: out.slice(0, resultSize).toString('utf-8'), entities };
+}
+
+/**
+ * Render a small window of `text` around a byte offset, for logs.
+ *
+ * @param {string} text
+ * @param {number} byteOffset
+ * @param {number} [radius=32]
+ * @returns {string}
+ */
+export function describeByteOffsetContext(text, byteOffset, radius = 32) {
+  const buffer = Buffer.from(String(text ?? ''), 'utf-8');
+  const start = Math.max(0, byteOffset - radius);
+  const end = Math.min(buffer.length, byteOffset + radius);
+  return JSON.stringify(buffer.slice(start, end).toString('utf-8'));
+}
+
+/**
+ * Check whether Telegram would accept `text` under `parseMode`.
+ *
+ * Parse modes other than legacy `Markdown` (and plain text) are reported as
+ * valid — this module deliberately only models the parser the bot uses.
+ *
+ * @param {string} text
+ * @param {string|undefined|null} parseMode
+ * @returns {{valid: boolean, description?: string, byteOffset?: number, context?: string}}
+ */
+export function validateTelegramText(text, parseMode) {
+  if (!parseMode || String(parseMode) !== 'Markdown') return { valid: true };
+  if (typeof text !== 'string' || text.length === 0) return { valid: true };
+  const parsed = parseTelegramLegacyMarkdown(text);
+  if (parsed.ok) return { valid: true };
+  return {
+    valid: false,
+    description: parsed.description,
+    byteOffset: parsed.byteOffset,
+    context: describeByteOffsetContext(text, parsed.byteOffset),
+  };
+}
+
+/**
+ * Convenience predicate used by tests and by pre-send checks.
+ *
+ * @param {string} text
+ * @param {string} [parseMode='Markdown']
+ * @returns {boolean}
+ */
+export function isValidTelegramMarkdown(text, parseMode = 'Markdown') {
+  return validateTelegramText(text, parseMode).valid;
+}

package/src/telegram-merge-command.lib.mjs

@@ -19,6 +19,7 @@
  */
 
 import { checkLabelPermissions, ensureReadyLabel } from './github-merge.lib.mjs';
+import { safeReply, safeEditMessageText } from './telegram-safe-reply.lib.mjs';
 import { extractMergeTargetUrlFromText, parseMergeTargetUrl } from './github-merge-targets.lib.mjs';
 import { createMergeQueueProcessor, MergeStatus, MERGE_QUEUE_CONFIG } from './telegram-merge-queue.lib.mjs';
 import { executeStartScreen } from './telegram-command-execution.lib.mjs';
@@ -331,12 +332,12 @@ export function registerMergeCommand(bot, options) {
     const targetResult = resolveMergeCommandTarget(positionals, ctx.message);
 
     if (!targetResult.target && !targetResult.error) {
-      return await ctx.reply(getMergeUsageMessage(), { parse_mode: 'MarkdownV2', reply_to_message_id: ctx.message.message_id });
+      return await safeReply(ctx, getMergeUsageMessage(), { parse_mode: 'MarkdownV2', reply_to_message_id: ctx.message.message_id });
     }
 
     if (!targetResult.target || !targetResult.target.valid) {
       const invalidPrefix = targetResult.fromReply ? 'Invalid merge target in replied message' : 'Invalid merge target';
-      return await ctx.reply(`${invalidPrefix}: ${escapeMarkdownV2(targetResult.error || targetResult.target?.error || 'Unknown target error')}\n\nPlease provide a valid GitHub repository, issue, or pull request URL\\.`, {
+      return await safeReply(ctx, `${invalidPrefix}: ${escapeMarkdownV2(targetResult.error || targetResult.target?.error || 'Unknown target error')}\n\nPlease provide a valid GitHub repository, issue, or pull request URL\\.`, {
         parse_mode: 'MarkdownV2',
         reply_to_message_id: ctx.message.message_id,
       });
@@ -352,7 +353,7 @@ export function registerMergeCommand(bot, options) {
     if (activeMergeOperations.has(repoKey)) {
       const existingOp = activeMergeOperations.get(repoKey);
       if (existingOp.processor.status === MergeStatus.RUNNING) {
-        return await ctx.reply(`A merge operation is already running for ${escapeMarkdownV2(owner)}/${escapeMarkdownV2(repo)}\\.\n\nPlease wait for it to complete or cancel it\\.`, {
+        return await safeReply(ctx, `A merge operation is already running for ${escapeMarkdownV2(owner)}/${escapeMarkdownV2(repo)}\\.\n\nPlease wait for it to complete or cancel it\\.`, {
           parse_mode: 'MarkdownV2',
           reply_to_message_id: ctx.message.message_id,
         });
@@ -360,7 +361,7 @@ export function registerMergeCommand(bot, options) {
     }
 
     // Send initial status message (reply to the /merge command)
-    const statusMessage = await ctx.reply(`Initializing merge queue for ${escapeMarkdownV2(owner)}/${escapeMarkdownV2(repo)}\\.\\.\\.\n\nThis may take a moment\\.`, {
+    const statusMessage = await safeReply(ctx, `Initializing merge queue for ${escapeMarkdownV2(owner)}/${escapeMarkdownV2(repo)}\\.\\.\\.\n\nThis may take a moment\\.`, {
       parse_mode: 'MarkdownV2',
       reply_to_message_id: ctx.message.message_id,
     });
@@ -369,14 +370,14 @@ export function registerMergeCommand(bot, options) {
       // Check permissions
       const permCheck = await checkLabelPermissions(owner, repo, VERBOSE);
       if (!permCheck.canManageLabels) {
-        await ctx.telegram.editMessageText(statusMessage.chat.id, statusMessage.message_id, undefined, `No permission to manage repository ${escapeMarkdownV2(owner)}/${escapeMarkdownV2(repo)}\\.\n\nPlease ensure you have write access to this repository\\.`, { parse_mode: 'MarkdownV2' });
+        await safeEditMessageText(ctx.telegram, statusMessage.chat.id, statusMessage.message_id, undefined, `No permission to manage repository ${escapeMarkdownV2(owner)}/${escapeMarkdownV2(repo)}\\.\n\nPlease ensure you have write access to this repository\\.`, { parse_mode: 'MarkdownV2' });
         return;
       }
 
       // Ensure ready label exists
       const labelResult = await ensureReadyLabel(owner, repo, VERBOSE);
       if (!labelResult.success) {
-        await ctx.telegram.editMessageText(statusMessage.chat.id, statusMessage.message_id, undefined, `Failed to setup 'ready' label: ${escapeMarkdownV2(labelResult.error)}`, {
+        await safeEditMessageText(ctx.telegram, statusMessage.chat.id, statusMessage.message_id, undefined, `Failed to setup 'ready' label: ${escapeMarkdownV2(labelResult.error)}`, {
           parse_mode: 'MarkdownV2',
         });
         return;
@@ -401,7 +402,7 @@ export function registerMergeCommand(bot, options) {
             // Without this check, progress updates from CI wait loops would re-add
             // the cancel button after the cancel handler had already removed it.
             const replyMarkup = processor.isCancelled ? undefined : { inline_keyboard: [[{ text: '🛑 Cancel', callback_data: `merge_cancel_${repoKey}` }]] };
-            await ctx.telegram.editMessageText(statusMessage.chat.id, statusMessage.message_id, undefined, message, {
+            await safeEditMessageText(ctx.telegram, statusMessage.chat.id, statusMessage.message_id, undefined, message, {
               parse_mode: 'MarkdownV2',
               ...(replyMarkup ? { reply_markup: replyMarkup } : {}),
             });
@@ -416,7 +417,7 @@ export function registerMergeCommand(bot, options) {
           try {
             const message = processor.formatFinalMessage();
             // Remove cancel button on completion
-            await ctx.telegram.editMessageText(statusMessage.chat.id, statusMessage.message_id, undefined, message, {
+            await safeEditMessageText(ctx.telegram, statusMessage.chat.id, statusMessage.message_id, undefined, message, {
               parse_mode: 'MarkdownV2',
             });
             VERBOSE && console.log(`[VERBOSE] /merge: Merge queue completed successfully for ${repoKey}`);
@@ -435,7 +436,7 @@ export function registerMergeCommand(bot, options) {
             const finalReport = processor.formatFinalMessage();
             // Issue #1269: Show error in the reply message with immediate feedback
             // Keep a button so users know the error was displayed and can dismiss
-            await ctx.telegram.editMessageText(statusMessage.chat.id, statusMessage.message_id, undefined, `❌ *Merge queue failed*\n\n⚠️ *Error:* ${escapeMarkdownV2(userMessage)}\n\n${finalReport}`, {
+            await safeEditMessageText(ctx.telegram, statusMessage.chat.id, statusMessage.message_id, undefined, `❌ *Merge queue failed*\n\n⚠️ *Error:* ${escapeMarkdownV2(userMessage)}\n\n${finalReport}`, {
               parse_mode: 'MarkdownV2',
               reply_markup: {
                 inline_keyboard: [[{ text: '❌ Failed - Click to dismiss', callback_data: `merge_dismiss_${repoKey}` }]],
@@ -454,7 +455,7 @@ export function registerMergeCommand(bot, options) {
 
       if (!initResult.success) {
         const userMessage = formatUserError(new Error(initResult.error), VERBOSE);
-        await ctx.telegram.editMessageText(statusMessage.chat.id, statusMessage.message_id, undefined, `Failed to initialize merge queue: ${escapeMarkdownV2(userMessage)}`, {
+        await safeEditMessageText(ctx.telegram, statusMessage.chat.id, statusMessage.message_id, undefined, `Failed to initialize merge queue: ${escapeMarkdownV2(userMessage)}`, {
           parse_mode: 'MarkdownV2',
         });
         return;
@@ -462,14 +463,14 @@ export function registerMergeCommand(bot, options) {
 
       if (initResult.message) {
         // No PRs to merge
-        await ctx.telegram.editMessageText(statusMessage.chat.id, statusMessage.message_id, undefined, `*Merge Queue \\- ${escapeMarkdownV2(owner)}/${escapeMarkdownV2(repo)}*${labelMsg}\n\n${escapeMarkdownV2(initResult.message)}\n\nTo use the merge queue:\n1\\. Add the \`ready\` label to repository PRs, or ensure the issue has a linked open PR\n2\\. Run \`/merge ${escapeMarkdownV2(targetUrl)}\` again`, { parse_mode: 'MarkdownV2' });
+        await safeEditMessageText(ctx.telegram, statusMessage.chat.id, statusMessage.message_id, undefined, `*Merge Queue \\- ${escapeMarkdownV2(owner)}/${escapeMarkdownV2(repo)}*${labelMsg}\n\n${escapeMarkdownV2(initResult.message)}\n\nTo use the merge queue:\n1\\. Add the \`ready\` label to repository PRs, or ensure the issue has a linked open PR\n2\\. Run \`/merge ${escapeMarkdownV2(targetUrl)}\` again`, { parse_mode: 'MarkdownV2' });
         return;
       }
 
       // Update message with PR list and cancel button, start processing
       const truncatedMsg = initResult.truncated ? `\n\n_Note: Only processing first ${MERGE_QUEUE_CONFIG.MAX_PRS_PER_SESSION} PRs_` : '';
 
-      await ctx.telegram.editMessageText(statusMessage.chat.id, statusMessage.message_id, undefined, `*Merge Queue \\- ${escapeMarkdownV2(owner)}/${escapeMarkdownV2(repo)}*${labelMsg}\n\n${getTargetFoundText(target, initResult.count)}${escapeMarkdownV2(truncatedMsg)}\n\nStarting merge process\\.\\.\\.`, {
+      await safeEditMessageText(ctx.telegram, statusMessage.chat.id, statusMessage.message_id, undefined, `*Merge Queue \\- ${escapeMarkdownV2(owner)}/${escapeMarkdownV2(repo)}*${labelMsg}\n\n${getTargetFoundText(target, initResult.count)}${escapeMarkdownV2(truncatedMsg)}\n\nStarting merge process\\.\\.\\.`, {
         parse_mode: 'MarkdownV2',
         reply_markup: {
           inline_keyboard: [[{ text: '🛑 Cancel', callback_data: `merge_cancel_${repoKey}` }]],
@@ -501,7 +502,7 @@ export function registerMergeCommand(bot, options) {
           // Show error in the reply message with immediate feedback
           try {
             const userMessage = formatUserError(error, VERBOSE);
-            await ctx.telegram.editMessageText(statusMessage.chat.id, statusMessage.message_id, undefined, `❌ *Merge queue failed unexpectedly*\n\n⚠️ *Error:* ${escapeMarkdownV2(userMessage)}\n\n_The queue processing has stopped\\. Please try again or check server logs\\._`, {
+            await safeEditMessageText(ctx.telegram, statusMessage.chat.id, statusMessage.message_id, undefined, `❌ *Merge queue failed unexpectedly*\n\n⚠️ *Error:* ${escapeMarkdownV2(userMessage)}\n\n_The queue processing has stopped\\. Please try again or check server logs\\._`, {
               parse_mode: 'MarkdownV2',
               reply_markup: {
                 inline_keyboard: [[{ text: '❌ Failed - Click to dismiss', callback_data: `merge_dismiss_${repoKey}` }]],
@@ -519,7 +520,7 @@ export function registerMergeCommand(bot, options) {
 
       try {
         const userMessage = formatUserError(error, VERBOSE);
-        await ctx.telegram.editMessageText(statusMessage.chat.id, statusMessage.message_id, undefined, `Error processing merge queue: ${escapeMarkdownV2(userMessage)}\n\nPlease check the repository URL and try again\\.`, { parse_mode: 'MarkdownV2' });
+        await safeEditMessageText(ctx.telegram, statusMessage.chat.id, statusMessage.message_id, undefined, `Error processing merge queue: ${escapeMarkdownV2(userMessage)}\n\nPlease check the repository URL and try again\\.`, { parse_mode: 'MarkdownV2' });
       } catch (editError) {
         VERBOSE && console.error('[VERBOSE] /merge: Failed to edit error message:', editError);
       }
@@ -547,9 +548,10 @@ export function registerMergeCommand(bot, options) {
     // the current PR finishes processing (which can take hours if waiting for CI).
     try {
       const cancellingMessage = operation.processor.formatProgressMessage();
-      await ctx.editMessageText(cancellingMessage, {
+      // No reply_markup = cancel button is removed immediately
+      await safeEditMessageText(ctx.telegram, ctx.chat?.id, ctx.callbackQuery?.message?.message_id, undefined, cancellingMessage, {
         parse_mode: 'MarkdownV2',
-        // No reply_markup = cancel button is removed immediately
+        verbose: VERBOSE,
       });
     } catch (err) {
       // If the full message edit fails, fall back to just removing the button

package/src/telegram-message-filters.lib.mjs

@@ -243,7 +243,7 @@ export function extractGitHubUrl(text, { parseGitHubUrl, cleanNonPrintableChars
 
     // Accept issue or PR URLs
     if (parsed.valid && (parsed.type === 'issue' || parsed.type === 'pull')) {
-      foundUrls.push(parsed.normalized);
+      foundUrls.push(parsed.canonical || parsed.normalized);
     }
   }