@emaxe/tuigram 1.0.0

package/.env.example

@@ -0,0 +1,29 @@
+# ── Telegram API Credentials ──────────────────────────────────────────────────
+# Получить на https://my.telegram.org -> API development tools.
+# Проще всего заполнить командой: tuigram init
+TELEGRAM_API_ID=
+TELEGRAM_API_HASH=
+
+# ── Data & Storage Directories ────────────────────────────────────────────────
+# По умолчанию файлы лежат в пользовательских директориях ОС и НЕ внутри пакета:
+#   настройки (этот файл):  ~/.config/tuigram/.env
+#                           %APPDATA%\tuigram\.env                  (Windows)
+#   сессия и загрузки:      ~/.local/share/tuigram/
+#                           %LOCALAPPDATA%\tuigram\                 (Windows)
+# Переопределить можно переменными ниже (раскомментируйте при необходимости).
+# TUIGRAM_CONFIG_DIR=
+# TUIGRAM_DATA_DIR=
+
+# Устаревшая переменная: относительный путь разрешается от корня пакета.
+# Оставлена для совместимости со старыми установками из клона репозитория.
+# DATA_DIR=./data
+
+# ── TUI UI Preferences ────────────────────────────────────────────────────────
+# Тема интерфейса: default (тёмная), nord, light (светлая)
+TUI_THEME=default
+
+# Автоскролл к последнему сообщению при открытии чата (true/false)
+AUTO_SCROLL=true
+
+# Показывать уведомления о наборе текста (true/false)
+SHOW_TYPING=true

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maksim Klisin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,364 @@
+# 🚀 TuiGram
+
+[![npm](https://img.shields.io/npm/v/@emaxe/tuigram)](https://www.npmjs.com/package/@emaxe/tuigram)
+[![node](https://img.shields.io/node/v/@emaxe/tuigram)](https://nodejs.org)
+[![license](https://img.shields.io/npm/l/@emaxe/tuigram)](./LICENSE)
+
+Полнофункциональный терминальный клиент Telegram (TUI + CLI) на Node.js на базе протокола MTProto (`teleproto`).
+
+Позволяет полноценно общаться в Telegram прямо из терминала: просматривать список чатов с разделением по категориям, читать переписку с сохранением форматирования (жирный, курсив, ссылки, подсветка кода), отправлять сообщения, ответы (Reply), редактировать, удалять, ставить реакции и отправлять файлы.
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────────────────┐
+│ 🚀 TuiGram │ Maksim (@maksim) │ ● В сети                                                    │
+│ 👥 Tech Chat [1420 уч.]                          ✍️ Alex печатает...                        │
+├──────────────────────────────┬──────────────────────────────────────────────────────────────┤
+│ [1:Все] [2:ЛС] [3:Группы]... │ ─────── Сегодня ───────                                      │
+│ [/] Поиск чатов...           │                                                              │
+│ 📌 👤 Pavel Durov · Let me…  │ Alex [13:40]                                                 │
+│ 👥 Tech Chat · Nice work! [3]│   Have you checked the latest release?                       │
+│ 🤖 BotFather · Done!   12:10 │ Вы [13:42] ✓✓                                                │
+│ 📢 News Channel · Дайд… [12] │   ┌─ Ответ на сообщение #1042                                │
+│                              │   Yes, testing it right now!                                 │
+│                              │   👍 4  🔥 2                                                 │
+│                              ├──────────────────────────────────────────────────────────────┤
+│                              │ ↩️ Ответ на [Alex]: "Have you checked..." [Esc: Отмена]      │
+│                              │ Пишу ответ прямо здесь█                                       │
+│                              │                                                              │
+├──────────────────────────────┴──────────────────────────────────────────────────────────────┤
+│ [Tab] Панель │ [Enter] Отправить │ [1-6] Вкладки │ [F1] Помощь │ [Ctrl+A] Действия │ [Ctrl+Q]│
+└─────────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## ⚡ Особенности и возможности
+
+- **Полноценный интерактивный TUI**:
+  - Двухпанельный адаптивный интерфейс (список чатов слева + история и поле ввода справа);
+  - Поддержка управления клавиатурой и мышью (клики, прокрутка колесом);
+  - Категории чатов: Все, Личные (ЛС), Группы, Каналы, Боты, Непрочитанные;
+  - Мгновенный поиск и фильтрация чатов по названию и `@username` (`/`);
+  - Отображение статуса набора текста («Собеседник печатает...») в реальном времени;
+  - Цветовое форматирование Telegram Entities (Bold, Italic, Monospace Code, URLs, Mentions, Spoilers);
+  - Индикаторы медиа-вложений (фото, видео, документы, голосовые, стикеры, опросы);
+  - Реакции на сообщения (👍, 🔥, ❤️);
+  - Бесконечная пагинация истории сообщений вверх (`PageUp` / `Ctrl+U`);
+  - Контекстные режимы быстрого ответа (Reply `Ctrl+R`) и редактирования (Edit `Ctrl+E`);
+  - Модальные окна: Справка (`F1` / `?`), Сведения о чате (`Ctrl+P`), Меню действий (`Ctrl+A`), Отправка файла (`Ctrl+O`).
+- **Автономный CLI-режим**:
+  - Быстрая отправка сообщений и файлов из командной строки;
+  - Просмотр списка диалогов и истории в терминале;
+  - Потоковый стриминг живых обновлений.
+- **Умная конфигурация**:
+  - Ключи и сессия хранятся в пользовательских директориях ОС — пакет остаётся read-only и переживает обновления;
+  - Безопасное хранение сессии и ключей (`chmod 0600`).
+
+---
+
+## 📦 Установка
+
+### Вариант 1: глобальная установка из npm (рекомендуется)
+
+```bash
+npm install -g @emaxe/tuigram
+```
+
+После этого команда `tuigram` доступна в любом каталоге.
+
+### Вариант 2: разовый запуск без установки
+
+```bash
+npx @emaxe/tuigram
+```
+
+### Вариант 3: из исходников (для разработки)
+
+```bash
+git clone https://github.com/emaxe/tuigram.git
+cd tuigram
+npm install
+npm start
+```
+
+---
+
+## ⚙️ Первый запуск
+
+### 1. Ключи Telegram API
+
+Получите `api_id` и `api_hash` на [https://my.telegram.org](https://my.telegram.org) (раздел *API development tools*), затем:
+
+```bash
+tuigram init
+```
+
+Команда спросит оба ключа и сохранит их с правами `0600`. Для скриптов и CI есть неинтерактивный вариант:
+
+```bash
+tuigram init --api-id 1234567 --api-hash 0123456789abcdef0123456789abcdef
+```
+
+Альтернатива — переменные окружения `TELEGRAM_API_ID` и `TELEGRAM_API_HASH`: они имеют приоритет над файлом настроек.
+
+### 2. Авторизация и запуск
+
+```bash
+tuigram
+```
+
+При первом запуске TuiGram предложит ввести номер телефона, код подтверждения из Telegram и пароль 2FA (если включён). После этого сессия сохранится, и последующие запуски будут происходить мгновенно.
+
+Отдельно авторизоваться можно командой `tuigram login`.
+
+> **В неинтерактивной среде** (CI, пайп, `< /dev/null`) вход по телефону невозможен:
+> `tuigram login` сразу завершится с понятной ошибкой вместо зависания. Если сессия
+> уже есть — команда просто сообщит, под кем вы авторизованы, и вернёт код `0`.
+> Для автоматизации положите готовый `session.txt` в директорию данных
+> (путь подскажет `tuigram paths`).
+
+---
+
+## 📂 Где хранятся файлы
+
+Ничего не пишется внутрь самого пакета — это важно при глобальной установке, где каталог `node_modules` обычно недоступен на запись и стирается при обновлении.
+
+| Что | macOS / Linux | Windows |
+|---|---|---|
+| Настройки (`.env`) | `~/.config/tuigram/.env` | `%APPDATA%\tuigram\.env` |
+| Сессия | `~/.local/share/tuigram/session.txt` | `%LOCALAPPDATA%\tuigram\session.txt` |
+| Загрузки из чатов | `~/.local/share/tuigram/downloads/` | `%LOCALAPPDATA%\tuigram\downloads\` |
+
+Посмотреть актуальные пути и состояние конфигурации:
+
+```bash
+tuigram paths
+```
+
+Переопределить расположение можно переменными `TUIGRAM_CONFIG_DIR` и `TUIGRAM_DATA_DIR` (учитываются также `XDG_CONFIG_HOME` / `XDG_DATA_HOME`).
+
+**Приоритет настроек** (сверху вниз, первое найденное выигрывает):
+1. переменные окружения процесса;
+2. `.env` в корне проекта — только при запуске из клона репозитория;
+3. `~/.config/tuigram/.env` — основной файл установленного CLI.
+
+Сессия из старых установок (`<проект>/data/session.txt`) переносится в новое расположение автоматически при первом запуске — повторно логиниться не нужно.
+
+---
+
+## 🛠 Разработка
+
+При запуске из клона репозитория работает интерактивное меню-диспетчер:
+
+```bash
+./run.sh      # или npm run menu
+```
+
+Оно даёт удобный выбор режима (TUI, логин, диалоги, отправка, тесты, очистка).
+
+Тесты и проверка содержимого будущего npm-пакета:
+
+```bash
+npm test                        # юнит-тесты
+node scripts/check-package.js   # проверка, что в пакет не утекают .env и сессия
+```
+
+---
+
+## ⌨️ Горячие клавиши
+
+| Сочетание клавиш | Область | Действие |
+|---|---|---|
+| `Tab` / `Shift+Tab` | Глобально | Фокус по кругу: Список диалогов → Лента сообщений → Поле ввода |
+| `↑` / `↓` | Список диалогов | Выбор чата |
+| `Enter` | Список диалогов | Открыть выбранный чат и загрузить историю |
+| `1` .. `6` | Список диалогов | Переключение категорий: `1:Все`, `2:ЛС`, `3:Группы`, `4:Каналы`, `5:Боты`, `6:Непроч` |
+| `/` | Список диалогов | Поиск / фильтрация чатов |
+| `Enter` | Поле ввода | Отправить набранное сообщение |
+| `Ctrl+J` | Поле ввода | Перенос строки без отправки |
+| `Ctrl+R` | Чат / Ввод | Ответить (Reply) на последнее сообщение |
+| `Ctrl+E` | Чат / Ввод | Редактировать своё последнее сообщение |
+| `Ctrl+A` | Сообщения | Контекстное меню действий (Реакции, Удаление, Скачивание, Ответ) |
+| `Ctrl+O` | Глобально | Отправить файл / фото / документ |
+| `Ctrl+F` | Окно отправки | Обзор файлов (навигация по папкам) |
+| `Ctrl+D` | Окно отправки | Отправить без сжатия, документом |
+| `Ctrl+P` | Глобально | Информация о текущем чате (ID, участники, ссылки) |
+| `PageUp` / `Ctrl+U`| История | Прокрутка вверх / подгрузка старой истории |
+| `PageDown` / `Ctrl+D`| История | Прокрутка вниз |
+| `Esc` | Модальные окна | Закрыть модальное окно / отменить Reply/Edit |
+| `F1` или `?` | Глобально | Окно справки со всеми горячими клавишами |
+| `Ctrl+Q` / `Ctrl+C` | Глобально | Безопасный выход из клиента |
+
+---
+
+## 💬 Слэш-команды в поле ввода
+
+В поле ввода сообщения доступны быстрые команды (начинаются с `/`):
+
+- `/help` — открыть окно помощи;
+- `/info` — подробная информация о текущем чате;
+- `/sendfile` — открыть окно отправки файла;
+- `/sendfile <путь>` — отправить файл сразу;
+- `/sendfile <путь> -- <подпись>` — файл с подписью;
+- `/sendfile <путь> | <путь> -- <подпись>` — альбом из нескольких файлов;
+- `/clear` — очистить экранную ленту сообщений;
+- `/logout` — выйти из аккаунта Telegram.
+
+---
+
+## 📎 Отправка файлов и картинок
+
+Три способа: окно `Ctrl+O`, слэш-команда `/sendfile`, консольная команда `sendfile`.
+
+**Окно отправки (`Ctrl+O`)**
+
+- `Ctrl+F` — обзор файлов: навигация по папкам стрелками, `Enter` — войти в папку или выбрать файл, `Esc` — назад. Внизу показывается размер подсвеченного файла.
+- Путь можно и просто ввести: понимает `~/Desktop/foto.png`, пути в кавычках и с экранированными пробелами — то есть перетаскивание файла прямо в терминал работает.
+- Несколько файлов — через `|` в поле пути (или добавляйте их по одному через обзор). До 10 штук уходят одним альбомом.
+- `Ctrl+D` — отправить без сжатия, документом. Полезно, когда важно исходное качество картинки.
+- Строка под чекбоксом сразу показывает, что именно уйдёт: `✓ photo.png · 2.4 MB · уйдёт как фото`.
+- Если в этот момент активен режим ответа (`Ctrl+R`), файл уйдёт **ответом** на сообщение.
+
+**Что уходит фото, а что документом**
+
+`.png`, `.jpg`, `.jpeg` Telegram принимает как сжатое фото; видеоформаты (`.mp4`, `.mov`, `.mkv` и т.п.) — как видео; всё остальное, включая `.webp` и `.heic`, — документом. Флажок «Как файл, без сжатия» (`Ctrl+D`, в CLI — `--as-file`) заставляет отправить документом что угодно.
+
+**Прогресс и отмена**
+
+Во время загрузки в строке состояния идут проценты. `Esc` прерывает отправку.
+
+**Скачивание входящих**
+
+`Ctrl+A` на сообщении → «Скачать медиа-вложение». Файл сохранится в `data/downloads/`.
+
+---
+
+## 🎨 Темы оформления
+
+Тема задаётся в `.env`:
+
+```env
+TUI_THEME=default   # тёмная (по умолчанию)
+TUI_THEME=nord      # Nord
+TUI_THEME=light     # светлая
+```
+
+Все цвета заданы hex-значениями и сводятся к палитре xterm-256 (индексы ≥ 16).
+Именованные цвета (`blue`, `cyan`, `gray`) специально не используются: они
+занимают индексы 0–15, которые тема терминала перекрашивает по-своему — из-за
+этого синий фон мог рисоваться бирюзовым, а серый текст пропадать совсем.
+
+Контраст каждой пары «текст на фоне» проверяется автотестом по WCAG (порог 3:1)
+уже **после** конверсии в xterm-256, то есть ровно в том виде, в каком цвет
+увидит пользователь.
+
+---
+
+## 🛠️ Использование через консоль (CLI)
+
+TuiGram можно запускать в режиме консольных утилит (при запуске из клона
+репозитория подставьте `node bin/tuigram.js` вместо `tuigram`):
+
+```bash
+# Авторизация
+tuigram login
+
+# Список диалогов
+tuigram dialogs --limit 30
+
+# Просмотр истории чата (@username, ID или me для «Избранного»)
+tuigram history @durov --limit 20
+tuigram history me
+
+# Отправка текстового сообщения
+tuigram send me "Привет из терминала!"
+tuigram send @friend "Встречаемся в 18:00"
+
+# Отправка файла (несколько путей уходят одним альбомом)
+tuigram sendfile me ./screenshot.png
+tuigram sendfile me ~/a.png ~/b.png --caption "Две картинки"
+tuigram sendfile me ~/photo.png --as-file   # без сжатия, документом
+
+# Живой стрим обновлений в реальном времени
+tuigram listen
+```
+
+---
+
+## 📁 Структура проекта
+
+```
+TuiGram/
+├── bin/
+│   └── tuigram.js               # CLI исполняемый файл
+├── src/
+│   ├── index.js                 # Главная точка входа (TUI / CLI роутер)
+│   ├── config.js                # Пути пользовательских директорий и загрузчик .env
+│   ├── state.js                 # Реактивное централизованное хранилище состояния
+│   ├── telegram/
+│   │   ├── client.js            # Создание и управление MTProto клиентом
+│   │   ├── auth.js              # Интерактивный логин-визард и 2FA
+│   │   ├── dialogs.js           # Получение, фильтрация и поиск диалогов
+│   │   ├── messages.js          # Загрузка истории, отправка, правка, файлы, реакции
+│   │   ├── listener.js          # Живой фоновый слушатель событий MTProto
+│   │   ├── entities.js          # Парсинг пиров, типы чатов и кэш сущностей
+│   │   └── formatter.js         # Telegram Entities -> Blessed ANSI форматирование
+│   ├── ui/
+│   │   ├── screen.js            # Управление Blessed Screen
+│   │   ├── theme.js             # Темы оформления (Default Dark, Nord, Light)
+│   │   ├── app.js               # Главный координатор интерфейса
+│   │   └── components/
+│   │       ├── header.js        # Верхняя шапка и статус подключения
+│   │       ├── chatList.js      # Список диалогов со скроллом, табами и поиском
+│   │       ├── chatView.js      # Лента сообщений с автоскроллом и форматированием
+│   │       ├── inputBox.js      # Поле ввода с плашкой Reply/Edit и историей
+│   │       ├── statusBar.js     # Нижняя строка подсказок и тостов
+│   │       └── modals/
+│   │           ├── helpModal.js     # Окно справки
+│   │           ├── chatInfoModal.js # Окно информации о чате
+│   │           ├── actionModal.js   # Меню действий с сообщением
+│   │           ├── fileModal.js     # Диалог отправки файла
+│   │           └── confirmModal.js  # Диалог подтверждения
+│   ├── cli/
+│   │   ├── cliCommands.js       # Автономные CLI команды
+│   │   ├── init.js              # tuigram init / paths — настройка и диагностика
+│   │   └── formatters.js        # Консольные форматтеры таблиц и логов
+│   └── utils/
+│       ├── storage.js           # Файловые операции и сохранение сессий
+│       └── time.js              # Форматирование времени и дат
+├── scripts/
+│   └── check-package.js         # Предпубликационная проверка npm-пакета
+├── test/
+│   └── unit.test.js             # Юнит-тесты
+├── .env.example                 # Пример конфигурации
+├── run.sh                       # Меню-диспетчер для разработки
+├── LICENSE
+├── package.json
+└── README.md
+```
+
+> В опубликованный npm-пакет попадают только `bin/`, `src/`, `README.md`, `LICENSE`
+> и `.env.example` — см. поле `files` в `package.json`.
+
+---
+
+## 🔒 Безопасность
+
+**Где лежит авторизация.** Единственный файл — `session.txt` в директории данных
+(`~/.local/share/tuigram/` или `%LOCALAPPDATA%\tuigram\`; путь можно сменить через
+`TUIGRAM_DATA_DIR`, посмотреть — командой `tuigram paths`). Внутри строка
+`StringSession` от MTProto: версия формата, номер дата-центра, его адрес и порт,
+и 256-байтный `authKey`, закодированные в base64. Пароля и кода подтверждения там нет.
+
+- Файл сессии и файл настроек сохраняются с правами `0600` — чтение и запись только владельцу.
+- Ни сессия, ни ключи не лежат внутри пакета: `npm update` их не затрагивает.
+- `data/` и `.env` в `.gitignore` и исключены из npm-пакета полем `files`;
+  проверка `node scripts/check-package.js` падает, если секрет всё же попал в сборку.
+- **`authKey` хранится в открытом виде**: base64 — это кодирование, а не шифрование.
+  Кто прочитает файл, тот получит полный доступ к аккаунту без телефона, кода и 2FA.
+  Не кладите его в общие папки и незашифрованные бэкапы. Если файл утёк —
+  завершите сеанс в официальном клиенте («Настройки → Устройства»), это отзовёт ключ
+  на сервере, и строка станет бесполезной.
+- `/logout` в TUI отзывает ключ на сервере и удаляет файл сессии.
+- Никакие данные не передаются сторонним серверам — прямое соединение с официальными
+  серверами Telegram MTProto.

package/bin/tuigram.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../src/index.js";

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@emaxe/tuigram",
+  "version": "1.0.0",
+  "description": "Полнофункциональный TUI & CLI клиент Telegram на Node.js на базе MTProto (teleproto)",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "bin": {
+    "tuigram": "bin/tuigram.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE",
+    ".env.example"
+  ],
+  "keywords": [
+    "telegram",
+    "tui",
+    "cli",
+    "terminal",
+    "mtproto",
+    "teleproto",
+    "chat",
+    "messenger",
+    "blessed",
+    "terminal-client"
+  ],
+  "author": "Maksim Klisin <emaxe.work@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/emaxe/tuigram.git"
+  },
+  "homepage": "https://github.com/emaxe/tuigram#readme",
+  "bugs": {
+    "url": "https://github.com/emaxe/tuigram/issues"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "menu": "./run.sh",
+    "tui": "node src/index.js tui",
+    "init": "node src/index.js init",
+    "login": "node src/index.js login",
+    "dialogs": "node src/index.js dialogs",
+    "history": "node src/index.js history",
+    "send": "node src/index.js send",
+    "listen": "node src/index.js listen",
+    "test": "node test/unit.test.js",
+    "prepublishOnly": "node test/unit.test.js && node scripts/check-package.js"
+  },
+  "dependencies": {
+    "big-integer": "^1.6.52",
+    "colorette": "^2.0.20",
+    "dotenv": "^16.4.7",
+    "input": "^1.0.1",
+    "neo-blessed": "^0.2.0",
+    "teleproto": "^1.229.0"
+  }
+}

package/src/cli/cliCommands.js

@@ -0,0 +1,164 @@
+import { connectClient, withClient } from "../telegram/client.js";
+import { loginInteractive } from "../telegram/auth.js";
+import { fetchDialogs } from "../telegram/dialogs.js";
+import { fetchHistory, sendMessage, sendFiles } from "../telegram/messages.js";
+import { inspectLocalFile } from "../utils/storage.js";
+import { formatFileSize } from "../utils/time.js";
+import { startTelegramListener } from "../telegram/listener.js";
+import { formatDialogRow, formatHistoryMessage, formatStreamEvent } from "./formatters.js";
+import { green, bold, red, yellow } from "colorette";
+
+/**
+ * Авторизация в аккаунте через CLI.
+ */
+export async function cmdLogin() {
+    console.log(bold("\n🔑 Интерактивная авторизация в Telegram:\n"));
+    await loginInteractive();
+}
+
+/**
+ * Вывод списка диалогов в консоль.
+ * @param {object} flags
+ */
+export async function cmdDialogs(flags) {
+    await withClient(async (client) => {
+        const limit = flags.limit ? parseInt(flags.limit, 10) : 50;
+        const archived = flags.archived === true ? true : undefined;
+
+        console.log(bold(`\n📂 Загрузка диалогов (макс. ${limit})...\n`));
+        const dialogs = await fetchDialogs(client, { limit, archived });
+
+        for (const d of dialogs) {
+            console.log(formatDialogRow(d));
+        }
+
+        console.log(gray(`\nВсего получено: ${dialogs.length} диалогов\n`));
+    });
+}
+
+/**
+ * Вывод истории сообщений чата.
+ * @param {string} peer
+ * @param {object} flags
+ */
+export async function cmdHistory(peer, flags) {
+    if (!peer) {
+        throw new Error("Укажите идентификатор чата: tuigram history <@username | -100... | me>");
+    }
+
+    await withClient(async (client) => {
+        const limit = flags.limit ? parseInt(flags.limit, 10) : 30;
+        console.log(bold(`\n💬 Загрузка истории для ${peer} (макс. ${limit} сообщений)...\n`));
+
+        const result = await fetchHistory(client, peer, { limit });
+        const messages = [...result.messages].reverse();
+
+        for (const m of messages) {
+            console.log(formatHistoryMessage(m));
+        }
+
+        console.log(gray(`\nВсего отображено: ${messages.length} сообщений\n`));
+    });
+}
+
+/**
+ * Отправка текстового сообщения из CLI.
+ * @param {string} peer
+ * @param {string} text
+ * @param {object} flags
+ */
+export async function cmdSend(peer, text, flags) {
+    if (!peer || !text) {
+        throw new Error("Использование: tuigram send <@username|me|id> <текст сообщения>");
+    }
+
+    await withClient(async (client) => {
+        const replyTo = flags.reply ? parseInt(flags.reply, 10) : undefined;
+        console.log(yellow(`Отправка сообщения в ${peer}...`));
+        const sent = await sendMessage(client, peer, text, { replyTo });
+        console.log(green(`✓ Сообщение успешно отправлено! (ID: ${sent.id})`));
+    });
+}
+
+/**
+ * Отправка файла из CLI.
+ * @param {string} peer
+ * @param {string} filePath
+ * @param {object} flags
+ */
+export async function cmdSendFile(peer, filePaths, flags) {
+    const rawPaths = (Array.isArray(filePaths) ? filePaths : [filePaths]).filter(Boolean);
+    if (!peer || rawPaths.length === 0) {
+        throw new Error(
+            "Использование: tuigram sendfile <@username|me|id> <путь> [ещё_путь ...] [--caption \"текст\"] [--as-file]"
+        );
+    }
+
+    // Валидируем до подключения: понятная ошибка вместо сетевой
+    const files = [];
+    for (const raw of rawPaths) {
+        const info = inspectLocalFile(raw);
+        if (!info.ok) throw new Error(info.error);
+        files.push(info);
+    }
+
+    const totalSize = files.reduce((sum, f) => sum + f.size, 0);
+    const label = files.length === 1 ? files[0].name : `${files.length} файлов`;
+
+    await withClient(async (client) => {
+        const caption = flags.caption || "";
+        const forceDocument = Boolean(flags["as-file"] || flags.document);
+
+        console.log(yellow(`Отправка ${label} (${formatFileSize(totalSize)}) в ${peer}...`));
+
+        let lastPercent = -1;
+        const progressCallback = (progress) => {
+            const percent = Math.min(99, Math.round((progress || 0) * 100));
+            if (percent === lastPercent) return;
+            lastPercent = percent;
+            process.stdout.write(`\rЗагрузка: ${percent}%   `);
+        };
+
+        const sent = await sendFiles(client, peer, files.map((f) => f.filePath), {
+            caption,
+            forceDocument,
+            progressCallback,
+        });
+
+        process.stdout.write("\r                    \r");
+        const ids = sent.map((m) => m.id).join(", ");
+        console.log(green(`✓ Успешно отправлено! (ID: ${ids})`));
+    });
+}
+
+/**
+ * Режим непрерывного прослушивания живых событий в консоли.
+ */
+export async function cmdListen() {
+    const client = await connectClient();
+    const me = await client.getMe();
+
+    console.log(green(bold(`\n🟢 Подключено как: ${me.firstName || ""} ${me.lastName || ""} (@${me.username || me.id})`)));
+    console.log(yellow("Слушаю обновления в реальном времени... Нажмите Ctrl+C для выхода.\n"));
+
+    const listener = startTelegramListener(client);
+
+    listener.on("new_message", (data) => console.log(formatStreamEvent("new_message", data)));
+    listener.on("edited_message", (data) => console.log(formatStreamEvent("edited_message", data)));
+    listener.on("deleted_messages", (data) => console.log(formatStreamEvent("deleted_messages", data)));
+    listener.on("typing", (data) => console.log(formatStreamEvent("typing", data)));
+
+    const shutdown = async () => {
+        console.log(yellow("\nОстановка слушателя..."));
+        listener.stop();
+        await client.disconnect().catch(() => {});
+        process.exit(0);
+    };
+
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+
+function gray(text) {
+    return `\x1b[90m${text}\x1b[0m`;
+}