@goodandready/dsh-messenger-gateway 0.3.2 → 0.3.8

package/lib/artifacts.js

@@ -0,0 +1,118 @@
+export function extractMermaidDiagrams(text) {
+  if (!text || typeof text !== 'string') return []
+  const regex = /```mermaid\s*\n([\s\S]*?)```/gi
+  const diagrams = []
+  let match
+  while ((match = regex.exec(text)) !== null) {
+    diagrams.push({
+      fullMatch: match[0],
+      code: match[1].trim(),
+      index: match.index,
+    })
+  }
+  return diagrams
+}
+
+export function escapeSvgXml(str = '') {
+  return String(str)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;')
+}
+
+export function generateDiagramSvg(code, title = 'Mermaid Diagram') {
+  const lines = code.split('\n').slice(0, 30)
+  const lineSpans = lines.map((line, i) => {
+    const escaped = escapeSvgXml(line)
+    return `<tspan x="24" dy="${i === 0 ? '0' : '1.4em'}">${escaped}</tspan>`
+  }).join('')
+
+  const height = Math.max(160, Math.min(800, lines.length * 24 + 100))
+  const safeTitle = escapeSvgXml(title)
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 ${height}" width="800" height="${height}">
+  <defs>
+    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#1e1e2e"/>
+      <stop offset="100%" stop-color="#181825"/>
+    </linearGradient>
+  </defs>
+  <rect width="100%" height="100%" rx="12" fill="url(#bg)" stroke="#313244" stroke-width="2"/>
+  <circle cx="28" cy="28" r="6" fill="#f38ba8" />
+  <circle cx="48" cy="28" r="6" fill="#f9e2af" />
+  <circle cx="68" cy="28" r="6" fill="#a6e3a1" />
+  <text x="96" y="32" fill="#cdd6f4" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, monospace" font-size="14" font-weight="600">${safeTitle}</text>
+  <line x1="16" y1="48" x2="784" y2="48" stroke="#313244" stroke-width="1"/>
+  <text x="24" y="76" fill="#a6adc8" font-family="'JetBrains Mono', 'Fira Code', monospace" font-size="13" xml:space="preserve">
+    ${lineSpans}
+  </text>
+</svg>`
+}
+
+export function formatMarkdownTables(text) {
+  if (!text || typeof text !== 'string') return text
+  const tableRegex = /((?:^|\n)\|[^\n]+\|\n\|[\s\-:|]+\|\n(?:\|[^\n]+\|\n?)+)/g
+
+  return text.replace(tableRegex, (match) => {
+    const rawLines = match.trim().split('\n')
+    if (rawLines.length < 3) return match
+
+    const rows = rawLines.map((line) => {
+      const cells = line.split('|').slice(1, -1).map((c) => c.trim())
+      return cells
+    })
+
+    const colCount = Math.max(...rows.map((r) => r.length))
+    const colWidths = Array(colCount).fill(0)
+
+    rows.forEach((row, rowIdx) => {
+      if (rowIdx === 1) return
+      row.forEach((cell, colIdx) => {
+        colWidths[colIdx] = Math.max(colWidths[colIdx] || 0, cell.length)
+      })
+    })
+
+    const formattedRows = rows.map((row, rowIdx) => {
+      if (rowIdx === 1) {
+        return colWidths.map((w) => '-'.repeat(Math.max(w, 3))).join(' | ')
+      }
+      return row.map((cell, colIdx) => cell.padEnd(colWidths[colIdx] || 3)).join(' | ')
+    })
+
+    const alignedTable = formattedRows.join('\n')
+    return `\n\`\`\`\n${alignedTable}\n\`\`\`\n`
+  })
+}
+
+export function processDiagramsAndTables(rawText, options = {}) {
+  const { artifactPreviews = true } = options
+  let text = String(rawText || '')
+  const files = []
+
+  if (artifactPreviews) {
+    const diagrams = extractMermaidDiagrams(text)
+    if (diagrams.length > 0) {
+      let diagramIndex = 1
+      for (const diag of diagrams) {
+        const svgContent = generateDiagramSvg(diag.code, `Диаграмма ${diagramIndex}`)
+        const base64 = Buffer.from(svgContent, 'utf-8').toString('base64')
+        files.push({
+          name: `diagram-${diagramIndex}.svg`,
+          mime: 'image/svg+xml',
+          kind: 'photo',
+          dataBase64: base64,
+          bytes: Buffer.from(svgContent, 'utf-8'),
+        })
+
+        text = text.replace(diag.fullMatch, `\n📊 <b>[Диаграмма ${diagramIndex}: см. вложение]</b>\n`)
+        diagramIndex++
+      }
+    }
+    text = formatMarkdownTables(text)
+  }
+
+  return { text, files, diagramsCount: files.length }
+}

package/lib/ask.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto'
 import { normalizeThreadId } from './topics.js'
 
 export const TELEGRAM_CALLBACK_DATA_MAX = 64
+export const DEFAULT_PAGE_SIZE = 6
 
 export function makeAskToken() {
   return randomUUID().replace(/-/g, '').slice(0, 12)
@@ -24,6 +25,21 @@ export function parseCallbackData(data) {
   return { token: raw.slice(0, idx), buttonId: raw.slice(idx + 1) }
 }
 
+export function parseAskCallback(data) {
+  const raw = String(data || '')
+  const parts = raw.split(':')
+  if (parts.length < 2) return { token: undefined, kind: 'unknown', id: raw }
+  const token = parts[0]
+  const rest = parts.slice(1).join(':')
+
+  if (rest === 'done') return { token, kind: 'done', id: 'done' }
+  if (rest === 'cancel') return { token, kind: 'cancel', id: 'cancel' }
+  if (rest.startsWith('t:')) return { token, kind: 'toggle', id: rest.slice(2) }
+  if (rest.startsWith('p:')) return { token, kind: 'page', page: Number(rest.slice(2)) || 0 }
+
+  return { token, kind: 'select', id: rest }
+}
+
 export function buildInlineKeyboard(token, buttons) {
   const callbackKeys = []
   const rows = (buttons || []).map((row) => row.map((btn) => {
@@ -37,6 +53,79 @@ export function buildInlineKeyboard(token, buttons) {
   }
 }
 
+export function normalizeAskOptions(options = []) {
+  if (Array.isArray(options)) {
+    const flat = options.flat ? options.flat() : [].concat(...options)
+    return flat.map((opt, i) => {
+      if (typeof opt === 'string') return { id: String(i + 1), text: opt, selected: false }
+      const id = String(opt?.id ?? opt?.buttonId ?? i + 1).trim()
+      const text = String(opt?.text ?? opt?.label ?? id).trim()
+      return { id, text, selected: Boolean(opt?.selected) }
+    })
+  }
+  return []
+}
+
+export function buildMultiSelectKeyboard(token, options = [], selectedIds = new Set(), page = 0, pageSize = DEFAULT_PAGE_SIZE, opts = {}) {
+  const normalized = normalizeAskOptions(options)
+  const total = normalized.length
+  const limit = Math.max(1, pageSize)
+  const maxPages = Math.ceil(total / limit) || 1
+  const curPage = Math.max(0, Math.min(page, maxPages - 1))
+  const start = curPage * limit
+  const end = Math.min(start + limit, total)
+  const slice = normalized.slice(start, end)
+
+  const callbackKeys = []
+  const rows = []
+
+  for (const opt of slice) {
+    const isChecked = selectedIds.has(opt.id)
+    const icon = isChecked ? '☑️' : '⬜️'
+    const text = `${icon} ${opt.text}`
+    const callback_data = buildCallbackData(token, `t:${opt.id}`)
+    callbackKeys.push(callback_data)
+    rows.push([{ text, callback_data }])
+  }
+
+  // Pagination row if more than one page
+  if (maxPages > 1) {
+    const navRow = []
+    if (curPage > 0) {
+      const prevData = buildCallbackData(token, `p:${curPage - 1}`)
+      callbackKeys.push(prevData)
+      navRow.push({ text: '⬅️ Назад', callback_data: prevData })
+    }
+    const indicatorData = buildCallbackData(token, `p:${curPage}`)
+    callbackKeys.push(indicatorData)
+    navRow.push({ text: `${curPage + 1}/${maxPages}`, callback_data: indicatorData })
+    if (curPage < maxPages - 1) {
+      const nextData = buildCallbackData(token, `p:${curPage + 1}`)
+      callbackKeys.push(nextData)
+      navRow.push({ text: 'Вперед ➡️', callback_data: nextData })
+    }
+    rows.push(navRow)
+  }
+
+  // Action buttons (Done / Cancel)
+  const doneText = opts.doneText || '✅ Готово'
+  const cancelText = opts.cancelText || '❌ Отмена'
+  const doneData = buildCallbackData(token, 'done')
+  const cancelData = buildCallbackData(token, 'cancel')
+  callbackKeys.push(doneData, cancelData)
+  rows.push([
+    { text: doneText, callback_data: doneData },
+    { text: cancelText, callback_data: cancelData },
+  ])
+
+  return {
+    replyMarkup: { inline_keyboard: rows },
+    callbackKeys,
+    page: curPage,
+    maxPages,
+  }
+}
+
 export function indexCallbacks(callbackIndex, keys, token) {
   for (const key of keys || []) callbackIndex.set(key, token)
 }

package/lib/client.js

@@ -117,6 +117,8 @@ const css =
       notifyBridge: 'Notify → Telegram home',
       notifyBridgeHint: 'task_done/error from web sessions (not msgw-*)',
       notifyHome: 'Notify home name',
+      quickActions: 'Quick actions keyboard (/new, /stop, /voice, /status)',
+      artifactPreviews: 'Render diagram and table previews',
     }
     const ru = {
       title: 'Messenger gateway',
@@ -188,6 +190,8 @@ const css =
       notifyBridge: 'Notify → Telegram home',
       notifyBridgeHint: 'task_done/error из web-сессий (не msgw-*)',
       notifyHome: 'Имя home для notify',
+      quickActions: 'Быстрая клавиатура (/new, /stop, /voice, /status)',
+      artifactPreviews: 'Превью артефактов (диаграммы и таблицы)',
     }
 
     function useActiveLocale(ctx) {
@@ -419,6 +423,14 @@ const css =
             t('statusIndicator'),
           ),
           React.createElement('div', { className: 'msgw-hint' }, t('statusIndicatorHint')),
+          React.createElement('label', { className: 'msgw-check' },
+            React.createElement('input', { type: 'checkbox', checked: cfg.telegram?.quickActions !== false, onChange: (e) => setCfg({ ...cfg, telegram: { ...cfg.telegram, quickActions: e.target.checked } }) }),
+            t('quickActions'),
+          ),
+          React.createElement('label', { className: 'msgw-check' },
+            React.createElement('input', { type: 'checkbox', checked: cfg.telegram?.artifactPreviews !== false, onChange: (e) => setCfg({ ...cfg, telegram: { ...cfg.telegram, artifactPreviews: e.target.checked } }) }),
+            t('artifactPreviews'),
+          ),
           React.createElement(Field, { label: t('voiceMode') },
             React.createElement('select', { className: 'msgw-select', value: cfg.telegram?.voiceMode || 'mirror', onChange: (e) => setCfg({ ...cfg, telegram: { ...cfg.telegram, voiceMode: e.target.value } }) },
               React.createElement('option', { value: 'mirror' }, t('voiceModeMirror')),

package/lib/commands.js

@@ -9,6 +9,18 @@ export const DEFAULT_TELEGRAM_COMMANDS = [
   { command: 'home', description: 'Список home-каналов' },
   { command: 'model', description: 'Показать или сменить модель' },
   { command: 'status', description: 'Статус шлюза' },
+  { command: 'setalert', description: 'Назначить этот чат каналом алертов' },
+  { command: 'alert', description: 'Статус канала алертов: /alert [test]' },
+  { command: 'keyboard', description: 'Клавиатура быстрых действий: /keyboard on|off' },
+  { command: 'role', description: 'Роль и персона агента: /role [name]' },
+  { command: 'skills', description: 'Список активных инструментов и навыков' },
+  { command: 'tools', description: 'Список активных инструментов' },
+  { command: 'fork', description: 'Форк текущей сессии в новую ветку' },
+  { command: 'export', description: 'Экспорт истории диалога в Markdown' },
+  { command: 'rewind', description: 'Откат сообщений: /rewind [N]' },
+  { command: 'files', description: 'Файловый менеджер рабочей папки: /files [dir]' },
+  { command: 'get', description: 'Скачать файл в Telegram: /get <path>' },
+  { command: 'remind', description: 'Напоминание: /remind <время> <текст>' },
   { command: 'voice', description: 'Голосовые ответы: /voice on|off|status' },
   { command: 'tts', description: 'Озвучка в этом чате: /tts on|off|status' },
   { command: 'mute', description: 'Не присылать уведомления в этот чат' },

package/lib/config.js

@@ -40,17 +40,36 @@ export const PluginConfig = z.object({
     webhookPath: z.string().default('/dsh-messenger-gateway/telegram/webhook'),
     voiceMode: z.union([z.const('mirror'), z.const('always'), z.const('off')]).default('mirror')
       .description('mirror: TTS when inbound was voice; always/off override (per-user /voice wins)'),
+    quickActions: z.boolean().default(true).description('Show persistent quick actions keyboard in Telegram (/new, /stop, /voice, /status)'),
+    artifactPreviews: z.boolean().default(true).description('Render diagrams and formatted tables as previews'),
     notifyBridge: z.object({
       enabled: z.boolean().default(false),
       events: z.array(z.string()).default(['task_done', 'error']),
       home: z.string().default('default'),
       excludeSessionPrefixes: z.array(z.string()).default(['msgw-']),
     }).default({ enabled: false }),
+    alerts: z.object({
+      enabled: z.boolean().default(false),
+      chatId: z.union([z.number(), z.string()]).default(''),
+      threadId: z.number().default(0),
+      home: z.string().default(''),
+      events: z.array(z.string()).default(['error', 'pairing']),
+    }).default({ enabled: false }),
   }),
   discord: z.object({
     enabled: z.boolean().default(false),
     botToken: z.string().role('secret').default(''),
-  }),
+    webhookUrl: z.string().default(''),
+  }).default({ enabled: false }),
+  slack: z.object({
+    enabled: z.boolean().default(false),
+    botToken: z.string().role('secret').default(''),
+    webhookUrl: z.string().default(''),
+  }).default({ enabled: false }),
+  webhooks: z.object({
+    enabled: z.boolean().default(true),
+    secret: z.string().role('secret').default(''),
+  }).default({ enabled: true }),
   media: z.object({
     cacheDir: z.string().default(''),
     maxDocBytes: z.number().default(20 * 1024 * 1024),

package/lib/documents.js

@@ -1,12 +1,22 @@
+import { readFile } from 'node:fs/promises'
+import { extname } from 'node:path'
+import { inflateRawSync } from 'node:zlib'
+
 /** Format a cached inbound document/video path for the agent (fs tools). */
-export function formatInboundDocument(att) {
+export function formatInboundDocument(att, parsed = null) {
   const kind = att?.kind || 'document'
   const labels = { video: 'Видео', sticker: 'Стикер', animation: 'GIF', document: 'Документ' }
   const label = labels[kind] || 'Файл'
   const name = att?.name ? ` ${att.name}` : ''
   const mime = att?.mime ? ` (${att.mime})` : ''
   const emoji = att?.emoji ? ` emoji=${att.emoji}` : ''
-  return `[${label}${name}${mime}${emoji}]\nПуть: ${att.path}`
+  let base = `[${label}${name}${mime}${emoji}]\nПуть: ${att.path}`
+
+  if (parsed?.text) {
+    const truncNote = parsed.truncated ? ' (содержимое усечено)' : ''
+    base += `\n\n[Распознанный текст из файла${truncNote}]:\n\`\`\`\n${parsed.text}\n\`\`\``
+  }
+  return base
 }
 
 export function documentOnlyHint(attachments, userText) {
@@ -23,8 +33,140 @@ export function documentOnlyHint(attachments, userText) {
 }
 
 export const TEXT_INJECT_EXTS = new Set([
-  '.md', '.txt', '.csv', '.log', '.json', '.xml', '.yaml', '.yml', '.toml', '.ini', '.cfg',
+  '.md', '.txt', '.csv', '.tsv', '.log', '.json', '.xml', '.yaml', '.yml', '.toml', '.ini', '.cfg',
   '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.py', '.sh', '.bash', '.zsh', '.ps1',
   '.go', '.rs', '.java', '.kt', '.c', '.h', '.cpp', '.hpp', '.cs', '.rb', '.php',
   '.html', '.css', '.scss', '.sql', '.r', '.swift', '.vue', '.svelte',
 ])
+
+export function extractPdfText(buffer) {
+  const content = buffer.toString('binary')
+  const textBlocks = []
+  // Matches text inside BT ... ET blocks
+  const btRegex = /BT[\s\S]*?ET/g
+  let btMatch
+  while ((btMatch = btRegex.exec(content)) !== null) {
+    const block = btMatch[0]
+    // Matches (text) Tj
+    const tjRegex = /\((.*?)\)\s*Tj/g
+    let tjMatch
+    while ((tjMatch = tjRegex.exec(block)) !== null) {
+      textBlocks.push(tjMatch[1])
+    }
+    // Matches [(t1) 10 (t2)] TJ
+    const arrayRegex = /\[(.*?)\]\s*TJ/g
+    let arrMatch
+    while ((arrMatch = arrayRegex.exec(block)) !== null) {
+      const inner = arrMatch[1]
+      const strRegex = /\((.*?)\)/g
+      let strMatch
+      while ((strMatch = strRegex.exec(inner)) !== null) {
+        textBlocks.push(strMatch[1])
+      }
+    }
+  }
+
+  // Also check plain text streams if no BT/ET blocks were matched
+  if (!textBlocks.length) {
+    const streamRegex = /stream[\r\n]+([\s\S]*?)[\r\n]+endstream/g
+    let sMatch
+    while ((sMatch = streamRegex.exec(content)) !== null) {
+      const stream = sMatch[1]
+      const strRegex = /\(([\w\s.,;:!?-]{4,})\)/g
+      let strMatch
+      while ((strMatch = strRegex.exec(stream)) !== null) {
+        textBlocks.push(strMatch[1])
+      }
+    }
+  }
+
+  return textBlocks.join(' ').replace(/\\([()\\])/g, '$1').trim()
+}
+
+export function extractDocxText(buffer) {
+  // Locate word/document.xml inside ZIP local file headers
+  let pos = 0
+  const needle = Buffer.from('word/document.xml', 'utf8')
+  while (pos < buffer.length - 30) {
+    // Local file header signature: 0x04034b50
+    if (buffer[pos] === 0x50 && buffer[pos + 1] === 0x4b && buffer[pos + 2] === 0x03 && buffer[pos + 3] === 0x04) {
+      const compMethod = buffer.readUInt16LE(pos + 8)
+      const compSize = buffer.readUInt32LE(pos + 18)
+      const nameLen = buffer.readUInt16LE(pos + 26)
+      const extraLen = buffer.readUInt16LE(pos + 28)
+      const nameStart = pos + 30
+      const nameBuf = buffer.slice(nameStart, nameStart + nameLen)
+
+      if (nameBuf.equals(needle)) {
+        const dataStart = nameStart + nameLen + extraLen
+        const compData = buffer.slice(dataStart, dataStart + compSize)
+        let xmlStr = ''
+        try {
+          if (compMethod === 8) {
+            xmlStr = inflateRawSync(compData).toString('utf8')
+          } else {
+            xmlStr = compData.toString('utf8')
+          }
+        } catch {
+          return ''
+        }
+        // Extract all text inside <w:t>...</w:t> tags
+        const textParts = []
+        const tRegex = /<w:t[^>]*>([\s\S]*?)<\/w:t>/g
+        let tMatch
+        while ((tMatch = tRegex.exec(xmlStr)) !== null) {
+          textParts.push(tMatch[1])
+        }
+        return textParts.join(' ').trim()
+      }
+      pos = nameStart + nameLen + extraLen + compSize
+    } else {
+      pos++
+    }
+  }
+  return ''
+}
+
+export async function parseDocument(filePath, opts = {}) {
+  const { maxBytes = 64 * 1024 } = opts
+  const ext = extname(filePath).toLowerCase()
+
+  try {
+    const rawBuffer = await readFile(filePath)
+    let text = ''
+    let parsedType = 'text'
+
+    if (ext === '.pdf') {
+      parsedType = 'pdf'
+      text = extractPdfText(rawBuffer)
+    } else if (ext === '.docx') {
+      parsedType = 'docx'
+      text = extractDocxText(rawBuffer)
+    } else if (TEXT_INJECT_EXTS.has(ext)) {
+      parsedType = ext.slice(1)
+      text = rawBuffer.toString('utf8')
+    } else {
+      return { parsed: false, type: 'unsupported' }
+    }
+
+    text = text.trim()
+    if (!text) return { parsed: false, type: parsedType }
+
+    const originalLength = text.length
+    let truncated = false
+    if (text.length > maxBytes) {
+      text = text.slice(0, maxBytes)
+      truncated = true
+    }
+
+    return {
+      parsed: true,
+      type: parsedType,
+      text,
+      truncated,
+      originalLength,
+    }
+  } catch (err) {
+    return { parsed: false, error: err.message }
+  }
+}

package/lib/file-manager.js

@@ -0,0 +1,162 @@
+import { readdir, stat, readFile } from 'node:fs/promises'
+import { resolve, normalize, relative, join, extname } from 'node:path'
+
+export function formatFileSize(bytes) {
+  if (!Number.isFinite(bytes) || bytes <= 0) return '0 B'
+  const units = ['B', 'KB', 'MB', 'GB']
+  const i = Math.min(units.length - 1, Math.floor(Math.log(bytes) / Math.log(1024)))
+  const val = (bytes / Math.pow(1024, i)).toFixed(i === 0 ? 0 : 1)
+  return `${val} ${units[i]}`
+}
+
+export function resolveSafePath(baseCwd, userPath = '.') {
+  const base = resolve(normalize(baseCwd || process.cwd()))
+  const cleanUser = String(userPath || '').trim() || '.'
+  const target = resolve(base, cleanUser)
+
+  const rel = relative(base, target)
+  if (rel.startsWith('..') || (rel && resolve(base, rel) !== target)) {
+    const err = new Error('Access denied: path traversal out of workspace')
+    err.code = 'ERR_PATH_TRAVERSAL'
+    throw err
+  }
+  return { base, target, relativePath: rel || '.' }
+}
+
+export async function listFiles(baseCwd, subPath = '.', opts = {}) {
+  const { maxEntries = 50, showHidden = false } = opts
+  const { base, target, relativePath } = resolveSafePath(baseCwd, subPath)
+
+  let st
+  try {
+    st = await stat(target)
+  } catch (err) {
+    return { ok: false, error: `Каталог не найден: ${err.message}` }
+  }
+
+  if (!st.isDirectory()) {
+    return {
+      ok: true,
+      isDirectory: false,
+      currentPath: relativePath,
+      entries: [{ name: relativePath, size: st.size, isDirectory: false }],
+      formattedText: `📄 <b>${relativePath}</b> (${formatFileSize(st.size)})\nДля скачивания: <code>/get ${relativePath}</code>`,
+    }
+  }
+
+  const rawEntries = await readdir(target, { withFileTypes: true })
+  const entries = []
+
+  for (const entry of rawEntries) {
+    if (!showHidden && (entry.name.startsWith('.') || entry.name === 'node_modules')) {
+      continue
+    }
+    const full = join(target, entry.name)
+    try {
+      const entryStat = await stat(full)
+      entries.push({
+        name: entry.name,
+        isDirectory: entry.isDirectory(),
+        size: entryStat.size,
+        mtime: entryStat.mtimeMs,
+      })
+    } catch {
+      entries.push({
+        name: entry.name,
+        isDirectory: entry.isDirectory(),
+        size: 0,
+        mtime: 0,
+      })
+    }
+  }
+
+  // Sort: directories first, then alphabetical
+  entries.sort((a, b) => {
+    if (a.isDirectory !== b.isDirectory) return a.isDirectory ? -1 : 1
+    return a.name.localeCompare(b.name)
+  })
+
+  const total = entries.length
+  const sliced = entries.slice(0, maxEntries)
+
+  const lines = [
+    `📂 <b>Файлы: <code>${relativePath === '.' ? '/' : `/${relativePath}`}</code></b> (${total} элементов):`,
+    '',
+  ]
+
+  if (relativePath !== '.') {
+    lines.push('📁 <code>..</code> (на уровень выше: <code>/files ..</code>)')
+  }
+
+  for (const e of sliced) {
+    if (e.isDirectory) {
+      lines.push(`📁 <code>${e.name}/</code>`)
+    } else {
+      lines.push(`📄 <code>${e.name}</code> (${formatFileSize(e.size)})`)
+    }
+  }
+
+  if (total > maxEntries) {
+    lines.push(`\n<i>... и ещё ${total - maxEntries} файлов</i>`)
+  }
+
+  lines.push('\nСкачать файл: <code>/get <файл></code>\nПереход по папкам: <code>/files <папка></code>')
+
+  return {
+    ok: true,
+    isDirectory: true,
+    currentPath: relativePath,
+    total,
+    entries: sliced,
+    formattedText: lines.join('\n'),
+  }
+}
+
+export async function getFileForDownload(baseCwd, relativePath, maxBytes = 50 * 1024 * 1024) {
+  const { target, relativePath: safeRel } = resolveSafePath(baseCwd, relativePath)
+  let st
+  try {
+    st = await stat(target)
+  } catch (err) {
+    return { ok: false, error: `Файл не найден: ${safeRel}` }
+  }
+
+  if (st.isDirectory()) {
+    return { ok: false, error: `«${safeRel}» является каталогом, а не файлом. Список: /files ${safeRel}` }
+  }
+
+  if (st.size > maxBytes) {
+    return {
+      ok: false,
+      error: `Файл слишком большой (${formatFileSize(st.size)} > ${formatFileSize(maxBytes)}).`,
+    }
+  }
+
+  const bytes = await readFile(target)
+  const ext = extname(safeRel).toLowerCase()
+
+  const mimeMap = {
+    '.md': 'text/markdown',
+    '.txt': 'text/plain',
+    '.json': 'application/json',
+    '.pdf': 'application/pdf',
+    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    '.csv': 'text/csv',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.svg': 'image/svg+xml',
+    '.html': 'text/html',
+  }
+
+  const mime = mimeMap[ext] || 'application/octet-stream'
+
+  return {
+    ok: true,
+    name: safeRel.split(/[\\/]/).pop(),
+    relativePath: safeRel,
+    bytes,
+    size: st.size,
+    mime,
+  }
+}