Metadata-Version: 2.4
Name: rkn-checker-tui
Version: 1.0.1
Summary: Дружелюбный TUI поверх rkn-block-checker: меню, пресеты, история, понятные описания вердиктов.
Author: howdeploy
License: MIT
Project-URL: Homepage, https://github.com/howdeploy/rkn-checker-tui
Project-URL: Repository, https://github.com/howdeploy/rkn-checker-tui
Project-URL: Issues, https://github.com/howdeploy/rkn-checker-tui/issues
Project-URL: Upstream, https://github.com/MayersScott/rkn-block-checker
Keywords: rkn,tspu,censorship,tui,textual,diagnostics
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Russian
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet
Classifier: Topic :: System :: Networking :: Monitoring
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rkn-block-checker>=0.5.0
Requires-Dist: textual<9,>=8.2
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: textual-dev>=1.7; extra == "dev"
Dynamic: license-file

![Python](https://img.shields.io/badge/Python-3776AB?logo=python&logoColor=white)
![Textual](https://img.shields.io/badge/Textual-5A56E0?logo=python&logoColor=white)
![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux&logoColor=black)
![macOS](https://img.shields.io/badge/macOS-000000?logo=apple&logoColor=white)
![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)

# rkn-checker-tui

Дружелюбный TUI поверх [rkn-block-checker](https://github.com/MayersScott/rkn-block-checker): меню вместо флагов, пресеты вместо параметров, понятные вердикты на русском и история снапшотов с диффом.

## Что это

Обёртка над `rkn-block-checker` — пробником, который послойно диагностирует блокировку: DNS → TCP → TLS → HTTP. Под капотом тот же движок, что и в оригинале. TUI меняет только то, как с этим работает человек.

Не нужно помнить флаги, держать в голове чем `TLS_BLOCK` отличается от `TCP_RESET` и руками складывать списки сайтов в JSON. Запустил — увидел статус сети, выбрал режим, получил таблицу с понятным описанием каждой строки. Хочешь сравнить «как было вчера» и «как сейчас» — есть снапшоты и diff.

## Возможности

- **Стартовая диагностика сети** — VPN / фильтрация / норма с IP и ISP в шапке
- **Три пресета сканирования** — Быстрая / Стандартная / Тщательная
- **Четыре режима** — whitelist + blacklist, только whitelist, только blacklist, ad-hoc URL
- **Понятные вердикты на русском** — что произошло физически и почему это блокировка
- **Свои списки сайтов** — кастомные whitelist / blacklist в формате `name=url`
- **Снапшоты и diff** — сохранить результат, сравнить с прошлым, увидеть регрессии и восстановления
- **История ad-hoc URL** — последние проверки запоминаются
- **Конфиг переживает перезапуск** — `~/.config/rkn-tui/config.json`, атомарная запись

## Требования

- **Python 3.10+**
- **Linux** или **macOS** (Windows не тестировался, теоретически работает через WSL/Terminal)
- Терминал с поддержкой Unicode и 256 цветов
- Сеть наружу (без неё движок ничего не покажет)

## Установка

**Через pipx (рекомендуется):**
```bash
pipx install rkn-checker-tui
```

**Через uv:**
```bash
uv tool install rkn-checker-tui
```

**Из репозитория (для разработки):**
```bash
git clone https://github.com/howdeploy/rkn-checker-tui
cd rkn-checker-tui
pipx install --editable .
```

## Запуск

```bash
rkn-tui
```

При старте проиграет диагностика сети (~3–5 секунд) и откроется главное меню.

### Главное меню

| Пункт | Что делает |
|-------|------------|
| Проверка подключения | Whitelist + blacklist одним сканом (быстрый ответ «всё ли вообще работает») |
| Только blacklist | Сайты, которые обычно режет ТСПУ |
| Только whitelist | Контрольная группа — должны открываться |
| Ad-hoc URL | Проверить конкретный сайт или несколько разом |
| История | Снапшоты прошлых сканов, открыть и сравнить |
| Настройки | Дефолтный пресет, кастомные списки |
| Помощь | Что значат вердикты |
| Выход | `q` тоже работает |

### Хоткеи

- `↑` / `↓` — навигация по меню и таблицам
- `Enter` — открыть пункт
- `←` / `→` — фильтр в таблице результатов (Все / OK / Заблокировано)
- `s` — сохранить снапшот текущего скана
- `Esc` — назад
- `Ctrl+S` — сохранить настройки
- `Ctrl+P` — командная палитра
- `q` — выход

## Пресеты

Пресет управляет тем, **как** сканируется (параллелизм, таймауты, представление клиента), а режим — **что** сканируется (какой набор URL).

| Пресет | Workers | Timeout | Identify UA | Когда брать |
|--------|---------|---------|-------------|-------------|
| **Быстрая** | 20 | 3.0 с | нет | Частый ре-чек «как сейчас сеть». Громко, быстро, без анонимности на стороне пробника. |
| **Стандартная** | 10 | 5.0 с | нет | Дефолт автора оригинала. Подходит для разовой диагностики и сохранения снапшота. |
| **Тщательная** | 5 | 10.0 с | да | Длинные таймауты + self-identify в User-Agent. Для отчёта и нестабильной сети, где быстрый скан выдаёт ложные таймауты. |

Дефолтный пресет выставляется в **Настройках** и применяется ко всем сканам из меню (кроме пункта «Быстрая проверка», который всегда использует Быструю — там это самый частый сценарий).

## Кастомные списки сайтов

Кроме встроенных whitelist/blacklist из `rkn-block-checker` можно подсунуть свои — на свой регион, своего провайдера, на конкретные ресурсы, которые тебе важно мониторить.

### Через интерфейс

Главное меню → **Настройки** → редакторы whitelist / blacklist.

Формат — по одной строке `name=url`. Пустые строки и `#`-комментарии игнорируются:

```text
# Мои белые контрольные
google=https://google.com
wikipedia=https://wikipedia.org

# Мои чёрные на проверку
example-blocked=https://example-blocked.org
```

Правила:

- Имя — любая непустая строка без `=`
- URL — обязательно `http://` или `https://`, иначе строка отклоняется
- Дубликаты имён внутри одного списка запрещены — TUI покажет ошибку и не сохранит
- **Пустой редактор** = «использовать встроенный список». Чтобы вернуть встроенный — просто очисти поле и сохрани

Сохранение — `Ctrl+S` или кнопка «Сохранить». Кнопка «Сбросить» возвращает оба списка к встроенным.

### Через файл конфигурации

Тот же эффект, но руками. Конфиг лежит в `~/.config/rkn-tui/config.json` (или `$XDG_CONFIG_HOME/rkn-tui/config.json`):

```json
{
  "default_preset": "default",
  "custom_white": {
    "google": "https://google.com",
    "wikipedia": "https://wikipedia.org"
  },
  "custom_black": {
    "example-blocked": "https://example-blocked.org"
  },
  "recent_adhoc": []
}
```

`null` в `custom_white` / `custom_black` означает «использовать встроенный список».

При сломанном JSON TUI стартанёт с дефолтами и не упадёт — сломанный конфиг просто игнорируется.

## Добавить свой пресет

Три встроенных пресета закрывают типовые сценарии, но если нужен ещё один — это правка одного файла.

Открой `rkn_tui/presets.py` и добавь новый `Preset` рядом с существующими:

```python
PARANOID = Preset(
    name="paranoid",
    label="Параноидальная",
    description="Один воркер, 30 секунд таймаут — для совсем гнилого канала.",
    workers=1,
    timeout=30.0,
    identify=True,
    no_self_info=False,
)

ALL: list[Preset] = [QUICK, DEFAULT, THOROUGH, PARANOID]
```

Параметры:

- `name` — внутреннее имя (snake_case, ASCII). Это значение пишется в конфиг.
- `label` — что будет видно в радио-кнопке настроек.
- `description` — короткое объяснение, когда брать этот пресет.
- `workers` — параллелизм проб (1 = строго последовательно).
- `timeout` — таймаут одной пробы в секундах.
- `identify` — посылать ли `User-Agent: rkn-block-checker` (полезно для прозрачности и обхода эвристик «подозрительный клиент»).
- `no_self_info` — пропустить ли запрос `get_self_info` при сканировании.

Чтобы новый пресет принимался конфигом, дополни `VALID_PRESETS` в `rkn_tui/storage.py`:

```python
VALID_PRESETS = {"quick", "default", "thorough", "paranoid"}
```

И добавь его в `PRESETS_ORDER` в `rkn_tui/screens/settings.py`, чтобы он появился в радио-группе:

```python
PRESETS_ORDER = ("quick", "default", "thorough", "paranoid")
```

После установки в editable-режиме (`pipx install --editable .`) новый пресет подхватится со следующим запуском `rkn-tui`.

## Вердикты — короткая шпаргалка

| Вердикт | Что произошло |
|---------|---------------|
| **OK** | Сайт открылся без помех |
| **Подмена DNS** | Резолвер отдал не те IP, что DoH |
| **Сброс TCP** | На пути middlebox шлёт RST |
| **DPI по SNI** | TLS-рукопожатие обрывается — классический ТСПУ |
| **Заглушка** | HTTP 451 или маркеры провайдерских заглушек |
| **Таймаут** | Пакеты молча отбрасываются (низкая уверенность) |
| **Не отвечает** | Сайт лежит — это не про РКН |

Полное описание с разбором «почему так уверены» — внутри TUI: открой строку результата клавишей `Enter`.

## Снапшоты и история

После любого скана `s` или кнопка «Сохранить снапшот» откроет ввод метки. Снапшот пишется в `~/.config/rkn-tui/snapshots/{YYYYMMDDTHHMMSS}-{slug}.json` со всеми вердиктами и контекстом сети на момент скана.

В разделе **История**:

- **Открыть** — просмотреть снапшот как обычный результат (read-only, без повторного сохранения)
- **Сравнить** — выбрать второй снапшот; покажется diff с разделением на «Только в старом», «Изменилось», «Только в новом»
- **Удалить** — с подтверждением

Diff подсвечивает регрессии (было OK → стало заблокировано) и восстановления (наоборот).

## Структура проекта

```
rkn_tui/
├── app.py              # точка входа, загрузка конфига
├── presets.py          # QUICK / DEFAULT / THOROUGH
├── engine.py           # обёртка над rkn_checker.core
├── vpn_check.py        # стартовая диагностика сети
├── verdicts.py         # описания вердиктов на русском
├── storage.py          # конфиг ~/.config/rkn-tui/config.json
├── snapshots.py        # снапшоты и diff
├── styles.tcss         # Catppuccin Mocha
└── screens/            # экраны Textual: splash, menu, scan, results, history, diff, settings, adhoc
```

## Кредит

Probe-движок — [rkn-block-checker](https://github.com/MayersScott/rkn-block-checker) (MIT) автора Dmitry Vinogradov. TUI и обёртка — отдельный проект, не аффилирован с автором оригинала.

## Лицензия

MIT.
