Noctalia-плагин для zapret-zdy

Репозиторий-источник Noctalia для shell'а Noctalia: крючок GUI управления обходом DPI (zapret-zdy) — индикатор в баре, плитка в Control Center, панель управления и отдельное постоянное окно «Диагностика и трассировка».

Плагин не содержит логики обхода: он вызывает установленный CLI zapret-zdy из соседнего проекта agents-repos/zapret-discord-youtube и разбирает его машинный вывод (--json-progress). Статус опрашивается read-only без root; действия (start/stop/check/dpi/trace/update/…) эскалируются через pkexec или sudo -n.

Это самостоятельный репозиторий: раньше плагин лежал подкаталогом gui/noctalia-plugin/ внутри репозитория CLI, теперь ведётся здесь и подключается к Noctalia как обычный источник (в корне — catalog.toml и папка плагина zapret-zdy/).

Формат

Текущий формат Noctalia-плагина — это plugin.toml + Luau entryPoints, а не manifest.json + QML. Плагин лежит одной папкой, имя папки = часть id после /. Корень этого репозитория и есть каталог-источник:

<repo-root>/
├── README.md            # этот файл (инструкция по установке)
├── CONTRIBUTING.md      # правила оформления (коммиты, ветки, приёмка)
├── catalog.toml         # индекс плагинов для git-источника
├── tools/               # проверка правил оформления (общие для хуков и CI)
├── .githooks/           # commit-msg и pre-push
├── .forgejo/workflows/  # CI: валидация плагина и правила оформления
└── zapret-zdy/          # сам плагин, id = "zapret-zdy/zapret-zdy"
    ├── plugin.toml      # манифест: метаданные, настройки, entryPoints
    ├── service.luau     # фоновый сервис: опрос статуса + запуск команд
    ├── widget.luau      # индикатор в баре (глиф, спиннер, tooltip)
    ├── shortcut.luau    # плитка Control Center (вкл/выкл)
    ├── panel.luau       # панель управления
    ├── diag.luau        # постоянное окно: diagnose + трассировка
    ├── translations/en.json   # английский источник строк (+ ru.json и др.)
    ├── thumbnail.webp   # карточка плагина (960×540)
    └── README.md        # страница плагина (EN, формат стора)

Требования

• установленный zapret-zdy. Скрипт установки живёт в репозитории CLI: sudo ./linux/zapret-zdy.sh install создаёт /usr/local/bin/zapret-zdy. Нужна версия CLI с флагами --json-progress и --no-elevate, а также с командой check-updates; CLI ставится из репозитория zapret-discord-youtube. После обновления CLI переустановите/обновите его (... install или ... update), иначе плагин получит ответ старого формата;
• pkexec (polkit) для эскалации по умолчанию либо sudo с правилом NOPASSWD для CLI;
• Noctalia v5.0.0-beta.9 или новее: манифест заявляет plugin_api = 24 (direct-argv, постоянная панель, openSettings, асинхронное чтение файлов). Поддерживаемый шеллом диапазон — 3…kCurrentPluginApiVersion, см. src/scripting/plugin_api.h в репозитории Noctalia.

Установка (разработка)

Официальный способ — добавить этот каталог как локальный source и включить плагин:

noctalia msg plugins source add zdy-dev path "$PWD"
noctalia msg plugins enable zapret-zdy/zapret-zdy

Правки .luau подхватываются на лету; манифест — при перечитывании source.

Что где в интерфейсе

Элемент	Назначение
Виджет в баре	состояние, спиннер во время операций, метка «↑» при доступном обновлении; левый клик — панель, правый — вкл/выкл
Плитка Control Center	одна кнопка вкл/выкл
Панель panel	управление, стратегия, Game Filter, проверка своего домена, логи действий, отчёт последней операции
Окно diag	постоянная панель: диагностика настроек и трассировка очереди с пояснением результата

Окно diag открывается кнопкой «Диагностика» в основной панели или командой:

noctalia msg panel-toggle zapret-zdy/zapret-zdy:diag

Установка из git-источника

Чтобы ставить плагин как обычный Noctalia-source, добавьте этот репозиторий (через GUI: Settings → Plugins → Add source — либо CLI):

noctalia msg plugins source add zdy git https://fjo.e-not.me/agents-repos/noctalia-plugins
noctalia msg plugins enable zapret-zdy/zapret-zdy

После появления новых коммитов в main источник нужно обновить:

noctalia msg plugins update zdy

Замечания:

• catalog.toml обязателен именно для git-источников (Noctalia читает его через git show без полного клона); для path-источников он не нужен — там каталоги сканируются напрямую. При релизе новой версии обновляйте version в обоих файлах: catalog.toml и zapret-zdy/plugin.toml — иначе Noctalia не увидит обновление;
• git-операции Noctalia неинтерактивны: если источник приватный, он должен быть доступен через уже настроенный SSH-agent / credential helper / SSH-config, иначе клон/обновление молча не сработает;
• id zapret-zdy/zapret-zdy валиден (часть после / совпадает с именем папки); plugin_api = 24 входит в поддерживаемый диапазон.

Установка (вручную)

Скопируйте папку плагина в локальный каталог плагинов Noctalia:

mkdir -p ~/.local/share/noctalia/plugins
cp -r zapret-zdy ~/.local/share/noctalia/plugins/

Noctalia увидит её как локальный source; включите плагин:

noctalia msg plugins enable zapret-zdy/zapret-zdy

Использование

• глиф в баре: shield-check — обход включён, shield-off — выключен; во время операции рядом с глифом идёт спиннер, при доступном обновлении — метка «↑». В tooltip — стратегия, режим ipset, Game Filter и статус обновлений;

• ЛКМ по виджету открывает панель, ПКМ — вкл/выкл;

• панель: состояние, включить/выключить/перезапустить, проверка обхода, выбор стратегии, автоподбор лучшей (с прогрессом по стратегиям), Game Filter (TCP/UDP), поле проверки своего домена, кнопки «Диагностика» и «Логи», кнопка обновления при доступном обновлении, подробный отчёт последней операции;

• окно diag (постоянное) — диагностика настроек и трассировка очереди;

• панель можно открыть командой:

  noctalia msg panel-toggle zapret-zdy/zapret-zdy:panel
  

Проверка обновлений

Настройка update_check (по умолчанию off) включает фоновую проверку: сервис раз в update_check_hours часов вызывает zapret-zdy check-updates — это read-only сравнение версий движка и детектора с GitHub и ревизий стратегий с удалёнными репозиториями. Ничего не устанавливается: при обнаруженном обновлении в панели появляется кнопка, запускающая zapret-zdy update (с обычным подтверждением прав).

Недоступный источник честно помечается как «проверить не удалось», а не как «актуально»; при полном отсутствии сети команда возвращает код 1.

Эскалация прав

Действия требуют root. По умолчанию плагин вызывает

pkexec /usr/local/bin/zapret-zdy --json-progress --no-elevate <команда>

Действия выполняются потоком (noctalia.runStream), а не вызовом с ограничением по времени: окно polkit остаётся, пока пользователь вводит пароль, а долгие операции (подбор стратегии, трассировка, обновление) отдают прогресс в реальном времени. Именно поэтому в манифесте заявлен plugin_api = 24: runAsync в Noctalia обрывает процесс через 5 секунд (и не дольше 60), чего окну polkit не хватает.

pkexec показывает системный запрос пароля через polkit-agent (в сессии должен быть запущен агент). Альтернативы в настройках плагина:

• escalation = sudo — sudo -n (нужно правило NOPASSWD; без tty и без правила команда сразу упадёт);
• escalation = none — если shell/пользователь уже root.

Read-only опрос (status, list, check-updates) идёт с флагом --no-elevate от текущего пользователя и root не требует.

Замечания

• Если в панели вместо списка стратегий показано «недоступен без прав root», значит $BASE/strategies/strategies.tsv не читается текущим пользователем (старая установка под sudo с umask 0077). Повторный install/update выставляет права 0644 на метаданные стратегий — после него список появится.
• Статус (status --json) читается без root всегда: конфиг /etc/zapret-zdy/config доступен на чтение.
• Панель и виджет не поднимают права сами: все действия идут через сервис.

Разработка

Проверка плагина

Основная проверка манифеста — линтер самой оболочки Noctalia. Он разбирает plugin.toml тем же кодом, что и рантайм, поэтому то, что не проходит здесь, не загрузится и у пользователя:

noctalia plugins lint .            # напрямую
bash tools/check-plugin-lint.sh    # то же, но понятно скажет, если noctalia нет

Он же стоит в CI (джоба lint) и в хуке pre-push. Если noctalia нет в PATH, скрипт пропускает проверку и говорит об этом; в CI флаг --require такое пропускание запрещает.

Официальный валидатор из official-plugins — вспомогательный: он проверяет лишь часть полей манифеста и, например, инвариант «persistent = true требует dismiss_on_outside_click = false» не знает. Скачать закреплённую ревизию, как это делает CI:

REV=f36c62aae9bb5d7aa463730139aa19c569a355f3
VALIDATOR=/tmp/validator/.github/workflows/validate-plugins.py
mkdir -p "$(dirname "$VALIDATOR")"
curl -fsSL -o "$VALIDATOR" \
  "https://raw.githubusercontent.com/noctalia-dev/official-plugins/$REV/.github/workflows/validate-plugins.py"
python3 "$VALIDATOR" --root .

Путь не косметика: валидатор считает корень как parents[2] от своего пути ещё при импорте и в плоском /tmp падает с IndexError — до разбора аргументов. Поэтому кладём его на ту же глубину, что и в официальном репозитории.

Синтаксис .luau (совместим с Lua 5.4, без Luau-only конструкций):

for f in zapret-zdy/*.luau; do luac5.4 -p "$f"; done

Хуки и правила оформления

Локальные хуки включаются один раз на машину:

bash tools/install-git-hooks.sh

Они проверяют сообщение коммита и имя ветки, а также запрещают прямой push в main. Те же правила гоняет CI (джоба conventions). Человеческое описание — CONTRIBUTING.md.