switchroom 0.19.7 → 0.19.9

package/telegram-plugin/render/render.ts

@@ -1,6 +1,7 @@
-// IR -> Telegram rich-markdown renderer for the Telegram HTML render engine
-// (name kept for continuity with render/ir.ts + render/parse.ts; the actual
-// wire format is GFM markdown, NOT HTML — see the note below).
+// IR -> Telegram rich-markdown renderer. (The render/ir.ts + render/parse.ts
+// files were originally named for an "HTML render engine"; that name is
+// historical — the actual wire format is GFM markdown, NOT HTML. See the note
+// below and the refreshed header in render/ir.ts.)
 //
 // Increment 2 of the render pipeline: takes the typed IR produced by
 // `parse.ts` (per `ir.ts`) and emits a string suitable for the `markdown`
@@ -67,6 +68,11 @@ function renderInline(node: Inline, ctx: InlineCtx = {}): string {
     case "italic":
       return `*${renderInlineChildren(node.children, ctx)}*`;
     case "underline":
+      // The wire renders `__…__` as BOLD, not underline — Telegram's
+      // rich-message markdown has no underline token (live-verified; see
+      // reference/telegram-formatting-guide.md). We preserve the author's `__`
+      // bytes faithfully rather than rewriting them to `**`; the IR keeps
+      // underline as a distinct node, but it is NOT a distinct wire style.
       return `__${renderInlineChildren(node.children, ctx)}__`;
     case "strike":
       return `~~${renderInlineChildren(node.children, ctx)}~~`;
@@ -284,6 +290,9 @@ export const SUPPORTED_INLINE = [
   "plain",
   "bold",
   "italic",
+  // "underline" parses `__…__` into a distinct node and round-trips it, but the
+  // wire renders it as BOLD (no underline token on this path). Kept for faithful
+  // `__` byte round-trip, NOT because it is a distinct rendered style.
   "underline",
   "strike",
   "spoiler",

package/telegram-plugin/rich-send.ts

@@ -67,16 +67,22 @@ export function guardAccidentalFormatting(markdown: string): string {
 /**
  * Wrap raw GFM markdown into the rich-message input object.
  *
- * This is the ONE adapter every `{ markdown }` wire send funnels through
- * (`sendRichMessage` / `editMessageText({ markdown })`) — the reply-tool final
- * answer, draft-stream previews, cards, approvals, banners. It is therefore the
- * single deterministic seam for the #3252 accidental-formatting guards (F1):
- * applying `guardAccidentalFormatting` here guards EVERY markdown-parsed
- * outbound exactly once, without touching `plain`-mode degradations (which
- * bypass this wrapper and go straight to `sendMessage`, where no markdown
- * parsing happens). The composed guard is a strict no-op for any body without
- * an accidental-formatting signal and is idempotent, so callers that already
- * ran it (or the streaming path that renders then re-wraps) stay byte-identical.
+ * This is a CONVENIENCE adapter — NOT the universal seam. It applies
+ * `guardAccidentalFormatting` for the many callers that build a body through
+ * it (the reply-tool final answer, draft-stream previews, cards), but it is
+ * NOT the one place every `{ markdown }` wire send funnels through: several
+ * sites build a raw `{ markdown }` and call `sendRichMessage` /
+ * `editMessageText` directly, bypassing this wrapper (see the correctness
+ * audit's F1 list — banners, switchroomReply html, approval/folder-picker
+ * edits). The REAL universal seam for the #3252 accidental-formatting guards
+ * is the grammy API transformer `installRichMarkdownGuard`
+ * (`shared/bot-runtime.ts`), installed on the production Bot in gateway boot,
+ * which guards EVERY sendRichMessage/editMessageText payload regardless of the
+ * call site. This wrapper is kept belt-and-braces: the composed guard is a
+ * strict no-op for any body without an accidental-formatting signal and is
+ * idempotent, so a body guarded here and re-guarded by the transformer stays
+ * byte-identical. `plain`-mode degradations bypass both (they go straight to
+ * `sendMessage`, where no markdown parsing happens).
  */
 export function richMessage(markdown: string): InputRichMessageMarkdown {
   return { markdown: guardAccidentalFormatting(markdown) }

package/telegram-plugin/shared/bot-runtime.ts

@@ -32,6 +32,7 @@ import { createRetryApiCall } from '../retry-api-call.js'
 import { makeFloodWaitRecorder, makeFloodWaitProbe } from '../flood-circuit-breaker.js'
 import { RICH_MESSAGE_MAX_CHARS } from '../format.js'
 import { shouldEmitTgPost } from './gw-trace-gate.js'
+import { guardAccidentalFormatting } from '../rich-send.js'
 
 // ─── tg-post tag plumbing ─────────────────────────────────────────────────
 
@@ -147,6 +148,62 @@ export function installTgPostLogger(bot: Bot): void {
   })
 }
 
+/**
+ * Universal accidental-formatting guard, installed as a grammy API transformer
+ * on the single production Bot (#3252/#3463 follow-up). This is the REAL
+ * universal seam — not `richMessage()`. `richMessage()` only guards bodies its
+ * callers remember to wrap; the correctness audit found ~6 sites that build a
+ * raw `{ markdown }` and call `sendRichMessage` / `editMessageText` directly,
+ * bypassing it (`shared/bot-runtime.ts` switchroomReply html path,
+ * `slot-banner-driver.ts` OAuth banners, and edits in `folder-picker-handler`,
+ * `approval-callback`, `inline-keyboard-callbacks`). A transformer at the
+ * grammy `bot.api.config.use` layer sees every rich send regardless of the
+ * call site, `ctx.*` sugar, `lockedBot`, or `bot.api.raw`, so it closes the
+ * whole bypass class deterministically.
+ *
+ * Payload shape (verified against grammy 1.44.0 `out/core/api.js`, the pinned
+ * lockfile version):
+ *   - `sendRichMessage(chat_id, rich_message, ...)` → raw payload
+ *     `{ chat_id, rich_message: { markdown }, ... }`
+ *   - `editMessageText(chat_id, message_id, arg, ...)` → raw payload
+ *     `{ ..., rich_message: { markdown } }` when `arg` is an object, or
+ *     `{ ..., text }` when `arg` is a plain string.
+ * The markdown therefore lives at `payload.rich_message.markdown`, NOT
+ * `payload.markdown` (gating on the latter matches nothing — a silent no-op).
+ * Gating on `rich_message?.markdown` also structurally skips every literal /
+ * plain-string edit (they carry `text`, not `rich_message`), so those pass
+ * through byte-identical. `sendRichMessageDraft` is not wired in the repo
+ * (draft streaming uses sendMessage+editMessageText); extend the method gate
+ * here if a future draft adopter starts using it.
+ *
+ * The composed `guardAccidentalFormatting` is idempotent, so double-guarding a
+ * `richMessage()`-wrapped body that also passes through here is byte-identical
+ * (the internal guard in `richMessage()` is kept belt-and-braces).
+ *
+ * We clone `rich_message` before mutating: callers can share the object by
+ * reference (e.g. `richMessage()` output reused across a retry), and a
+ * transformer must not mutate the caller's input.
+ */
+export function installRichMarkdownGuard(bot: Bot): void {
+  bot.api.config.use(async (prev, method, payload, signal) => {
+    if (
+      (method === 'sendRichMessage' || method === 'editMessageText') &&
+      payload != null
+    ) {
+      const p = payload as Record<string, unknown>
+      const rich = p.rich_message as { markdown?: unknown } | undefined
+      if (rich != null && typeof rich.markdown === 'string') {
+        const guarded = guardAccidentalFormatting(rich.markdown)
+        if (guarded !== rich.markdown) {
+          // Clone rather than mutate the caller's shared object.
+          p.rich_message = { ...rich, markdown: guarded }
+        }
+      }
+    }
+    return prev(method, payload, signal)
+  })
+}
+
 // ─── robustApiCall factory ────────────────────────────────────────────────
 
 /**

package/telegram-plugin/tests/format-guard-pins.test.ts

@@ -0,0 +1,93 @@
+/**
+ * Pin tests for the accidental-formatting guard (#3252/#3463).
+ *
+ * Two internal-hardening assertions, no user-visible change:
+ *
+ *  1. Documents the `#{1,6}` cap in ACCIDENTAL_HEADING as intentional: a run of
+ *     7+ `#` glued to non-space is left UNescaped (CommonMark caps heading
+ *     promotion at 6 `#`, and the guard mirrors that). Correctness-audit F2
+ *     flagged this as asserted-but-untested.
+ *
+ *  2. A wiring assertion that PR1's `installRichMarkdownGuard` transformer is
+ *     actually installed on the production Bot in `initGatewayBot()`, so the
+ *     universal seam can't be silently dropped in a later refactor. Grammy's
+ *     installed transformers are anonymous fns (nothing to grip at runtime), so
+ *     this is a source-level AST assertion on the boot path — the same approach
+ *     `gateway-bot-construction-deferral.test.ts` uses.
+ */
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+import ts from 'typescript'
+import { guardAccidentalFormatting } from '../rich-send.js'
+import { guardAccidentalHeading } from '../render/line-start-guard.js'
+
+describe('accidental-heading guard: #{1,6} cap is intentional (F2)', () => {
+  it('escapes a 6-# run glued to non-space (upper bound of the cap)', () => {
+    expect(guardAccidentalHeading('######x')).toBe('\\######x')
+    expect(guardAccidentalFormatting('######x')).toBe('\\######x')
+  })
+
+  it('leaves a 7-# run glued to non-space UNescaped (past the CommonMark cap)', () => {
+    expect(guardAccidentalHeading('#######x')).toBe('#######x')
+    expect(guardAccidentalFormatting('#######x')).toBe('#######x')
+  })
+
+  it('leaves an 8+-# run glued to non-space UNescaped', () => {
+    expect(guardAccidentalHeading('##########x')).toBe('##########x')
+    expect(guardAccidentalFormatting('##########x')).toBe('##########x')
+  })
+})
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const GATEWAY_PATH = resolve(__dirname, '..', 'gateway', 'gateway.ts')
+const GATEWAY_SRC = readFileSync(GATEWAY_PATH, 'utf8')
+const sourceFile = ts.createSourceFile(
+  GATEWAY_PATH,
+  GATEWAY_SRC,
+  ts.ScriptTarget.Latest,
+  true,
+  ts.ScriptKind.TS,
+)
+
+function findFunction(name: string): ts.FunctionDeclaration | undefined {
+  for (const s of sourceFile.statements) {
+    if (ts.isFunctionDeclaration(s) && s.name?.text === name) return s
+  }
+  return undefined
+}
+
+function countCallsTo(root: ts.Node, name: string): number {
+  let count = 0
+  const visit = (node: ts.Node): void => {
+    if (
+      ts.isCallExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      node.expression.text === name
+    ) {
+      count++
+      // Installed on the constructed bot instance.
+      expect(node.arguments[0]?.getText(sourceFile)).toBe('bot')
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(root)
+  return count
+}
+
+describe('boot wiring: installRichMarkdownGuard is installed on the production Bot', () => {
+  it('imports installRichMarkdownGuard from ../shared/bot-runtime.js', () => {
+    // The import must exist for the boot call to resolve; a refactor that drops
+    // the import would break the seam.
+    expect(GATEWAY_SRC).toMatch(
+      /import\s*\{[^}]*\binstallRichMarkdownGuard\b[^}]*\}\s*from\s*'\.\.\/shared\/bot-runtime\.js'/,
+    )
+  })
+
+  it('calls installRichMarkdownGuard(bot) exactly once inside initGatewayBot()', () => {
+    const fn = findFunction('initGatewayBot')
+    expect(fn?.body).toBeDefined()
+    expect(countCallsTo(fn!.body!, 'installRichMarkdownGuard')).toBe(1)
+  })
+})

package/telegram-plugin/tests/render/underline-wire-outcome.test.ts

@@ -0,0 +1,32 @@
+/**
+ * Truth-pass pin (#3252 formatting-truth follow-up): the REAL wire outcome for
+ * a `__…__` run.
+ *
+ * The parser folds `__x__` into a distinct `underline` IR node and the renderer
+ * round-trips it back to `__x__` (asserted in parse.test.ts / render.test.ts).
+ * But Telegram's rich-message markdown has NO underline token: the wire renders
+ * `__x__` identically to `**x__` — i.e. as BOLD (live-verified 2026-07, see
+ * reference/telegram-formatting-guide.md).
+ *
+ * Decision (documented in the fmt-audit BUILD-LOG): we keep the underline node
+ * and faithfully preserve the author's `__` bytes rather than rewriting them to
+ * `**` — full removal would invert several green tests and change wire bytes for
+ * zero wire-visible benefit (both render as bold). This test pins the honest
+ * contract: `__x__` emits `__x__`, which the wire treats as bold, NOT a distinct
+ * underline style.
+ */
+import { describe, it, expect } from "vitest";
+import { parse } from "../../render/parse.js";
+import { render } from "../../render/render.js";
+
+describe("underline: real wire outcome for `__…__`", () => {
+  it("round-trips `__x__` to `__x__` on the wire (which Telegram renders as BOLD)", () => {
+    // The emitted bytes preserve the author's `__` delimiters verbatim.
+    expect(render(parse("__x__"))).toBe("__x__");
+  });
+
+  it("does NOT rewrite `__x__` to `**x**` (author bytes preserved, not normalised to bold syntax)", () => {
+    expect(render(parse("__underlined__"))).not.toContain("**");
+    expect(render(parse("__underlined__"))).toBe("__underlined__");
+  });
+});

package/telegram-plugin/tests/rich-markdown-guard-transformer.test.ts

@@ -0,0 +1,121 @@
+/**
+ * Wire-level outcome tests for the universal accidental-formatting guard
+ * (`installRichMarkdownGuard`, #3252/#3463 follow-up).
+ *
+ * These MUST go through a REAL grammy `Bot` with a stubbed transport. The
+ * existing unit/golden harnesses (`tests/bot-api.harness.ts` etc.) mock the
+ * `api` object ABOVE the grammy transformer layer, so `api.config.use`
+ * transformers never run there — a test written through them is a FALSE guard
+ * (it stays green with the transformer absent or mis-gated). By stubbing
+ * `client.fetch` we capture the exact serialized wire body AFTER the
+ * transformer has mutated the raw payload, which is the only place the guard's
+ * effect is observable.
+ *
+ * Red-team F-R1: the markdown lives at `payload.rich_message.markdown`, NOT
+ * `payload.markdown`. A guard gating on the latter matches nothing and every
+ * one of these assertions would still fail — so these tests pin the correct
+ * field shape too.
+ */
+import { describe, it, expect } from 'vitest'
+import { Bot } from 'grammy'
+import { installTgPostLogger, installRichMarkdownGuard } from '../shared/bot-runtime.js'
+
+interface CapturedCall {
+  method: string
+  body: Record<string, unknown>
+}
+
+/**
+ * Build a real grammy Bot whose transport is stubbed: every API call is
+ * captured (method + parsed JSON body) and answered with a minimal ok
+ * response. `botInfo` is supplied so `bot.init()` never hits the network.
+ */
+function makeCapturingBot(): { bot: Bot; calls: CapturedCall[] } {
+  const calls: CapturedCall[] = []
+  const fakeFetch = (async (url: unknown, init?: { body?: unknown }) => {
+    const method = String(url).split('/').pop() ?? ''
+    let body: Record<string, unknown> = {}
+    if (typeof init?.body === 'string') {
+      body = JSON.parse(init.body) as Record<string, unknown>
+    }
+    calls.push({ method, body })
+    // Minimal Telegram ok envelope. `result` shape doesn't matter for these
+    // send/edit calls — grammy only reads `ok`/`result`.
+    return {
+      ok: true,
+      status: 200,
+      json: async () => ({ ok: true, result: { message_id: 1, date: 0, chat: { id: 1, type: 'private' } } }),
+    } as unknown as Response
+  }) as unknown as typeof fetch
+
+  const bot = new Bot('123456:TEST_TOKEN', {
+    botInfo: {
+      id: 123456,
+      is_bot: true,
+      first_name: 'Test',
+      username: 'test_bot',
+      can_join_groups: false,
+      can_read_all_group_messages: false,
+      supports_inline_queries: false,
+      can_connect_to_business: false,
+      has_main_web_app: false,
+    },
+    client: { fetch: fakeFetch },
+  })
+  // Install exactly the production transformer stack ordering: logger first,
+  // then guard (guard composes outermost — grammy runs last-installed first).
+  installTgPostLogger(bot)
+  installRichMarkdownGuard(bot)
+  return { bot, calls }
+}
+
+function lastRichMarkdown(calls: CapturedCall[]): unknown {
+  const c = calls[calls.length - 1]
+  return (c.body.rich_message as { markdown?: unknown } | undefined)?.markdown
+}
+
+describe('installRichMarkdownGuard — universal wire seam', () => {
+  it('(a) escapes a raw { markdown } sendRichMessage on the wire', async () => {
+    const { bot, calls } = makeCapturingBot()
+    await bot.api.sendRichMessage(1, { markdown: '#3460 done' })
+    expect(calls[calls.length - 1].method).toBe('sendRichMessage')
+    expect(lastRichMarkdown(calls)).toBe('\\#3460 done')
+  })
+
+  it('(b) escapes an editMessageText object-arg { markdown } on the wire', async () => {
+    const { bot, calls } = makeCapturingBot()
+    await bot.api.editMessageText(1, 42, { markdown: '#3460 done' })
+    expect(calls[calls.length - 1].method).toBe('editMessageText')
+    expect(lastRichMarkdown(calls)).toBe('\\#3460 done')
+  })
+
+  it('(c) leaves a literalText / string-arg edit UNTOUCHED (carries text, not rich_message)', async () => {
+    const { bot, calls } = makeCapturingBot()
+    await bot.api.editMessageText(1, 42, '#3460 done')
+    const c = calls[calls.length - 1]
+    expect(c.method).toBe('editMessageText')
+    expect(c.body.text).toBe('#3460 done')
+    expect(c.body.rich_message).toBeUndefined()
+  })
+
+  it('(d) leaves a genuine heading byte-identical', async () => {
+    const { bot, calls } = makeCapturingBot()
+    await bot.api.sendRichMessage(1, { markdown: '# Title\n## Sub' })
+    expect(lastRichMarkdown(calls)).toBe('# Title\n## Sub')
+  })
+
+  it('(e) is idempotent on an already-guarded (richMessage-wrapped) body', async () => {
+    const { bot, calls } = makeCapturingBot()
+    // Simulate a body that already went through richMessage()'s internal guard.
+    await bot.api.sendRichMessage(1, { markdown: '\\#3460 done' })
+    expect(lastRichMarkdown(calls)).toBe('\\#3460 done')
+  })
+
+  it('does not mutate the caller\'s shared input object', async () => {
+    const { bot } = makeCapturingBot()
+    const input = { markdown: '#3460 done' }
+    await bot.api.sendRichMessage(1, input)
+    // Caller's object is unchanged; only the cloned wire payload is escaped.
+    expect(input.markdown).toBe('#3460 done')
+  })
+})