@emaxe/tuigram 1.0.0 → 1.0.1

package/README.ru.md

@@ -0,0 +1,656 @@
+# 🚀 TuiGram
+
+**Русский** · [English](./README.md)
+
+[![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)
+[![downloads](https://img.shields.io/npm/dm/@emaxe/tuigram)](https://www.npmjs.com/package/@emaxe/tuigram)
+[![platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)](#-установка)
+
+Полнофункциональный терминальный клиент Telegram (TUI + CLI) на Node.js на базе протокола MTProto (`teleproto`).
+
+Позволяет полноценно общаться в Telegram прямо из терминала: просматривать список чатов с разделением по категориям, читать переписку с сохранением форматирования (жирный, курсив, ссылки, подсветка кода), отправлять сообщения, ответы (Reply), редактировать, удалять, ставить реакции и отправлять файлы.
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────────────────┐
+│ 🚀 TuiGram │ Alex Rivers (@alex_rivers) │ ● В сети                                          │
+│ 👥 Tech Chat [1420 уч.]                        ✍️ Sam печатает...                           │
+├──────────────────────────────┬──────────────────────────────────────────────────────────────┤
+│ [1:Все] [2:ЛС] [3:Группы] …  │ ──────────────── Сегодня ────────────────                    │
+│ [/] Поиск чатов...           │                                                              │
+│ 📌 👤 Sam Lee · Let me know… │ Sam Lee [13:40]                                              │
+│ 👥 Tech Chat · Nice work! [3]│   Have you checked the latest release?                       │
+│ 🤖 Deploy Bot · Done!   12:10│                                                              │
+│ 📢 News Channel · Дайд… [12] │ Sam Lee [13:41]                                              │
+│ 👤 Mia Novak · 📷 Фото  9:41 │   📷 Фото · 1.8 MB                                           │
+│ 💾 Избранное · Ссылка     вчр│                                                              │
+│                              │ Вы [13:42] ✓✓                                                │
+│                              │   ┌─ Ответ на сообщение #1042                                │
+│                              │   Yes, testing it right now!                                 │
+│                              │   👍 4  🔥 2                                                 │
+│                              ├──────────────────────────────────────────────────────────────┤
+│                              │ ↩️ Ответ на [Sam Lee]: "Have you checked…"  [Esc]            │
+│                              │ Пишу ответ прямо здесь█                                      │
+├──────────────────────────────┴──────────────────────────────────────────────────────────────┤
+│ [Tab] Панель │ [Enter] Отправить │ [1-6] Вкладки │ [F1] Помощь │ [Ctrl+Q] Выход             │
+└─────────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 📑 Содержание
+
+- [Особенности и возможности](#-особенности-и-возможности)
+- [«Скриншоты»](#-скриншоты)
+- [Установка](#-установка)
+- [Первый запуск](#-первый-запуск)
+- [Где хранятся файлы](#-где-хранятся-файлы)
+- [Разработка](#-разработка)
+- [Горячие клавиши](#️-горячие-клавиши)
+- [Слэш-команды](#-слэш-команды-в-поле-ввода)
+- [Отправка файлов и картинок](#-отправка-файлов-и-картинок)
+- [Темы оформления](#-темы-оформления)
+- [Использование через консоль (CLI)](#️-использование-через-консоль-cli)
+- [Структура проекта](#-структура-проекта)
+- [Безопасность](#-безопасность)
+- [История изменений](#-история-изменений)
+- [Участие в разработке](#-участие-в-разработке)
+- [Лицензия](#-лицензия)
+
+---
+
+## ⚡ Особенности и возможности
+
+- **Полноценный интерактивный 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`).
+
+---
+
+## 🖼 «Скриншоты»
+
+TuiGram живёт в терминале, поэтому вместо картинок — точные текстовые снимки экранов.
+Подписи, подсказки и формат вывода взяты из кода интерфейса, а не придуманы:
+данные в примерах вымышленные.
+
+Главное окно показано в начале README. Ниже — остальные экраны клиента.
+
+### Поиск и фильтрация чатов
+
+Клавиша `/` включает мгновенный поиск по названию и `@username`, цифры `1`–`6`
+переключают категории.
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────────────────┐
+│ 🚀 TuiGram │ Alex Rivers (@alex_rivers) │ ● В сети                                          │
+├──────────────────────────────┬──────────────────────────────────────────────────────────────┤
+│ [1:Все] [2:ЛС] [3:Группы] …  │ ──────────────── Сегодня ────────────────                    │
+│ [/] tech█                    │                                                              │
+│ 👥 Tech Chat · Nice work! [3]│ Sam Lee [11:02]                                              │
+│ 📢 Tech Digest · Выпуск…     │   Let me know how it goes.                                   │
+│ 🤖 TechSupport Bot · Ок      │                                                              │
+│                              │ Вы [11:05] ✓✓                                                │
+│ 3 из 214 чатов               │   Will do 👍                                                 │
+│                              ├──────────────────────────────────────────────────────────────┤
+│                              │ Введите сообщение…█                                          │
+└──────────────────────────────┴──────────────────────────────────────────────────────────────┘
+```
+
+<details>
+<summary><b>Справка — <code>F1</code> / <code>?</code></b></summary>
+
+Полный список горячих клавиш и слэш-команд прямо в клиенте.
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│ 🚀 TuiGram — Горячие клавиши и управление                                │
+│                                                                          │
+│ Навигация и фокус:                                                       │
+│   [Tab] / [Shift+Tab]   Фокус: Чаты → Сообщения → Ввод                   │
+│   [↑] / [↓]             Перемещение по списку чатов                      │
+│   [Enter]               Открыть чат / Загрузить историю                  │
+│   [PageUp] / [Ctrl+U]   Прокрутка вверх / старая история                 │
+│                                                                          │
+│ Вкладки фильтрации диалогов:                                             │
+│   [1] Все чаты      [2] Личные (ЛС)      [3] Группы                      │
+│   [4] Каналы        [5] Боты             [6] Непрочитанные               │
+│   [/] Поиск чатов по названию/username                                   │
+│                                                                          │
+│ Работа с сообщениями:                                                    │
+│   [Enter]   Отправить      [Ctrl+R]  Ответить (Reply)                    │
+│   [Ctrl+J]  Перенос строки [Ctrl+E]  Редактировать сообщение             │
+│   [Ctrl+A]  Меню действий  [Ctrl+O]  Отправить файл / фото               │
+│   [Ctrl+P]  Инфо о чате    [Esc]     Закрыть окно / режим                │
+│                                                                          │
+│ Слэш-команды в поле ввода:                                               │
+│   /help  /info  /sendfile  /sendfile <путь>  /clear  /logout             │
+│                                                                          │
+│ Выход:                                                                   │
+│   [Ctrl+Q] или [Ctrl+C]   Безопасный выход из клиента                    │
+│                                                                          │
+│                         [ Закрыть ]                                      │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+</details>
+
+<details>
+<summary><b>Меню действий с сообщением — <code>Ctrl+A</code></b></summary>
+
+Ответ, редактирование, удаление, реакции и скачивание вложения.
+Пункты «Редактировать» и «Скачать» появляются только там, где они применимы.
+
+```
+┌──────────────────────────────────────────────────────┐
+│ ⚡ Действия с сообщением #1042                       │
+│ Sam Lee: Have you checked the latest release?        │
+├──────────────────────────────────────────────────────┤
+│ ↩️  Ответить (Reply)                                 │
+│ ✏️  Редактировать текст                              │
+│ 🗑️  Удалить сообщение                                │
+│ 👍  Поставить реакцию 👍                             │
+│ 🔥  Поставить реакцию 🔥                             │
+│ ❤️  Поставить реакцию ❤️                             │
+│ 📥  Скачать медиа-вложение                           │
+│ 📋  Скопировать текст в ввод                         │
+├──────────────────────────────────────────────────────┤
+│ [↑↓] Выбор   [Enter] Выполнить   [Esc] Отмена        │
+└──────────────────────────────────────────────────────┘
+```
+
+</details>
+
+<details>
+<summary><b>Отправка файла — <code>Ctrl+O</code></b></summary>
+
+Несколько путей через `|` уходят одним альбомом. Строка под чекбоксом сразу
+показывает, чем именно станет файл на стороне Telegram.
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ 📤 Отправка файла или документа                            │
+├────────────────────────────────────────────────────────────┤
+│ Путь к файлу (несколько — через |)         [Ctrl+F] Обзор  │
+│ ┌────────────────────────────────────────────────────────┐ │
+│ │ ~/Desktop/photo.png | ~/Desktop/chart.png█             │ │
+│ └────────────────────────────────────────────────────────┘ │
+│ Подпись (необязательно):                                   │
+│ ┌────────────────────────────────────────────────────────┐ │
+│ │ Две картинки с релиза                                  │ │
+│ └────────────────────────────────────────────────────────┘ │
+│ [ ] Как файл, без сжатия      [Ctrl+D]                     │
+│ ✓ photo.png · 2.4 MB · уйдёт как фото                      │
+├────────────────────────────────────────────────────────────┤
+│            [ Отправить ]        [ Отмена ]                 │
+│ [Tab] Поля  [Enter] Далее  [Ctrl+F] Обзор  [Esc] Выход     │
+└────────────────────────────────────────────────────────────┘
+```
+
+</details>
+
+<details>
+<summary><b>Обзор файлов — <code>Ctrl+F</code></b></summary>
+
+Навигация по папкам стрелками, размер подсвеченного файла — внизу.
+
+```
+┌──────────────────────────────────────────────────────────┐
+│ 📁 Выбор файла: /Users/alex/Desktop                      │
+├──────────────────────────────────────────────────────────┤
+│   ..                                             <папка> │
+│   screenshots/                                   <папка> │
+│ ▸ photo.png                                       2.4 MB │
+│   chart.png                                       812 KB │
+│   report.pdf                                      1.1 MB │
+│   archive.zip                                    18.7 MB │
+├──────────────────────────────────────────────────────────┤
+│ photo.png · 2.4 MB                                       │
+│ [↑↓] Навигация  [Enter] Выбрать  [Esc] Назад             │
+└──────────────────────────────────────────────────────────┘
+```
+
+</details>
+
+<details>
+<summary><b>Сведения о чате — <code>Ctrl+P</code></b></summary>
+
+ID, тип, username, число участников и описание.
+
+```
+┌──────────────────────────────────────────────────────┐
+│ ℹ Информация о чате                                  │
+├──────────────────────────────────────────────────────┤
+│ Название:        Tech Chat                           │
+│ Тип:             supergroup                          │
+│ ID:              -1001234567890                      │
+│ Username:        @techchat                           │
+│ Участников:      1420                                │
+│ Уведомления:     Включены                            │
+│                                                      │
+│ О чате / О себе:                                     │
+│   Чат про терминальные клиенты и MTProto.            │
+├──────────────────────────────────────────────────────┤
+│                    [ Закрыть ]                       │
+└──────────────────────────────────────────────────────┘
+```
+
+</details>
+
+### Консольный режим
+
+<details>
+<summary><b>Вывод CLI-команд</b></summary>
+
+**`tuigram dialogs --limit 8`**
+
+```
+📂 Загрузка диалогов (макс. 8)...
+
+📌 [user      ] Sam Lee                          id=100200301
+   [supergroup] Tech Chat                        id=-1001234567890 (+3)
+   [bot       ] Deploy Bot                       id=100200302
+   [channel   ] News Channel                     id=-1009876543210 (+12)
+   [saved     ] Избранное                        id=100200300
+   [user      ] Mia Novak                        id=100200303 (+1)
+   [group     ] Team Terminal                    id=-400112233
+   [user      ] Nina Ivanova                     id=100200304
+
+Всего получено: 8 диалогов
+```
+
+**`tuigram history @sam_lee --limit 5`**
+
+```
+💬 Загрузка истории для @sam_lee (макс. 5 сообщений)...
+
+[29.08.2026, 11:02:14] #1040 Sam Lee: Let me know how it goes.
+[29.08.2026, 11:05:41] #1041 Вы: Will do 👍
+[29.08.2026, 13:40:07] #1042 Sam Lee: Have you checked the latest release?
+[29.08.2026, 13:41:22] #1043 Sam Lee: 📷 Фото
+[29.08.2026, 13:42:55] #1044 Вы (в ответ на #1042): Yes, testing it right now! (изменено)
+
+Всего отображено: 5 сообщений
+```
+
+**`tuigram listen`**
+
+```
+🟢 Подключено как: Alex Rivers (@alex_rivers)
+Слушаю обновления в реальном времени... Нажмите Ctrl+C для выхода.
+
+[13:40:07] + НОВОЕ [-1001234567890] Sam Lee: Have you checked the latest release?
+[13:41:19] ✍️ ПЕЧАТАЕТ чат: -1001234567890
+[13:42:55] + НОВОЕ [-1001234567890] Вы: Yes, testing it right now!
+[13:43:30] ~ ИЗМЕНЕНО [-1001234567890] #1044: Yes, testing it right now! 🚀
+[13:44:02] - УДАЛЕНО [123456789] IDs: 1039, 1038
+```
+
+</details>
+
+---
+
+## 📦 Установка
+
+### Вариант 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` на сообщении → «Скачать медиа-вложение». Файл сохранится в подкаталоге
+`downloads/` директории данных (путь покажет `tuigram paths`).
+
+---
+
+## 🎨 Темы оформления
+
+Тема задаётся в `.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 @sam_lee --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                       # Меню-диспетчер для разработки
+├── AGENTS.md                    # Правила кодовой базы (источник правды для ИИ-агентов)
+├── CHANGELOG.md
+├── LICENSE
+├── package.json
+├── README.md
+└── README.ru.md
+```
+
+> В опубликованный npm-пакет попадают только `bin/`, `src/`, `README.md`, `README.ru.md`,
+> `CHANGELOG.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.
+
+
+---
+
+## 📜 История изменений
+
+Все заметные изменения фиксируются в [CHANGELOG.md](./CHANGELOG.md).
+Формат — [Keep a Changelog](https://keepachangelog.com/ru/1.1.0/),
+версионирование — [SemVer](https://semver.org/lang/ru/).
+
+---
+
+## 🤝 Участие в разработке
+
+Баг-репорты и pull request'ы приветствуются:
+[issues](https://github.com/emaxe/tuigram/issues).
+
+Перед отправкой изменений:
+
+```bash
+npm test                        # юнит-тесты должны быть зелёными
+node scripts/check-package.js   # в пакет не должны попасть .env и сессия
+```
+
+Правила кодовой базы для людей и ИИ-агентов собраны в [AGENTS.md](./AGENTS.md) —
+единый источник правды по архитектуре, стилю, тестам и безопасности.
+Если работаете с Claude Code, Cursor или Copilot, начните с него.
+
+Обе версии README (`README.md` и `README.ru.md`) должны обновляться вместе.
+
+---
+
+## 📄 Лицензия
+
+[MIT](./LICENSE) © Maksim Klisin
+
+TuiGram — неофициальный клиент. Проект не связан с Telegram Messenger Inc.
+и не аффилирован с ним.