Глава 15

Свои плагины

Manta можно расширять собственными плагинами — на любом языке программирования. В этой главе рассказывается, что умеет плагин, как его установить, обновить и найти и на что обратить внимание. Техническое руководство находится в документации для разработчиков.

Что умеют плагины¶

• Показывать значки рядом с именами файлов (как значки Git).
• Показывать метки в строке пути (как ветку или проект).
• Предлагать команды для палитры команд и контекстного меню — при желании с сочетанием клавиш.
• Показывать панели под панелью файлов, на правой боковой панели или в виде окна.
• Показывать элементы в строке состояния — со значком, небольшим индикатором и цветом предупреждения (как Загрузка системы).
• Показывать сообщения.

Плагин — это папка с файлом plugin.toml и программой (например, скриптом Python). Manta запускает программу и обменивается с ней сообщениями (строки JSON через stdin/stdout). Файл .mantaplugin — это просто такая папка, упакованная в ZIP-архив.

Установка плагина¶

1. Откройте Настройки (⌘,) → Плагины.
2. Нажмите Установить плагин… и выберите Из файла (.mantaplugin, .zip)… или Из папки… (той, где лежит plugin.toml). Быстрее: дважды щелкните файл .mantaplugin в Finder или перетащите его на страницу «Плагины». Плагины из каталога сообщества устанавливаются через Обзор.
3. Прежде чем что-либо устанавливать, Manta показывает сводку: название, версию, автора, описание, Что ему разрешено (например, «Читает ваши файлы», «Изменяет или удаляет файлы», «Использует сеть», «Запускает другие программы», «Выполняет команды в Терминале»), запускаемую Команду, Источник, ссылку на Исходный код, Лицензию и размер. Ниже — предупреждение, что Manta не проверяет плагины.
4. Нажмите Установить. После этого плагин появится в разделе Установленные — пока выключенным.

Включение¶

Нажмите Включить на карточке плагина. В первый раз Manta попросит подтверждения и еще раз покажет автора, версию, разрешения, команду и папку, в которой она запускается.

Если плагин загружен из интернета, macOS держит его файлы в карантине, и Gatekeeper заблокировал бы программы в нем. Окно подтверждения сообщает об этом: только когда вы включаете плагин, Manta снимает с его файлов метку карантина, чтобы его программы могли работать, — и никогда незаметно для вас.

Другие кнопки на карточке плагина: Обновить, Показать журнал, Показать папку, Удалить. Вверху: Открыть папку плагинов и Обновить (ищет добавленные, измененные или удаленные плагины).

Обновление и удаление¶

• Обновление: если в каталоге плагинов есть более новая версия, на карточке плагина появляется надпись «В каталоге плагинов доступна версия …» и кнопка Обновить. Или установите новую версию тем же способом — из файла или папки. Если у нее тот же идентификатор, что и у установленного плагина, сводка сообщает об обновлении и показывает в поле Установлено версию, которая будет заменена. После подтверждения Manta заменяет плагин; включен он или выключен, сохраняется.
• Удаление: нажмите Удалить на карточке плагина. Manta удаляет папку плагина; папка с его данными сохраняется.

Поиск плагинов¶

В разделе Настройки → Плагины нажмите Обзор (или выберите Каталог плагинов… в палитре команд). Manta покажет плагины из каталога сообщества: название и описание на вашем языке, автора, лицензию, нужную версию Manta, разрешения и ссылку на исходный код.

1. Нажмите Установить (или Обновить, если есть более новая версия установленного плагина).
2. Manta загружает плагин и сравнивает его контрольную сумму SHA-256 с указанной в каталоге. Если они не совпадают, ничего не устанавливается.
3. Появляется обычная сводка («SHA-256 совпадает с каталогом плагинов»); дальше — как описано выше.

Плагины, которым нужна более новая версия Manta или которые не работают на вашем Mac, показываются, но установить их нельзя. В интернете открывает каталог на manta-filemanager.com/plugins.

Безопасность¶

Внешние плагины работают в песочнице macOS: они могут делать только то, что им разрешено. Без разрешений плагин может только читать собственную папку и системные файлы и записывать в собственную папку данных.

Те же правила действуют для всего, о чем плагин просит Manta (прочитать файл, показать содержимое папки, переименовать файлы). На карточке плагина отображается В песочнице; во всплывающей подсказке перечислены разрешения. Встроенные плагины — часть Manta и работают без песочницы.

Если песочница на вашем Mac не работает, карточка показывает Без песочницы и причину, а сводка предупреждает, что соблюдение разрешений обеспечить нельзя. Тогда плагин работает с правами вашего пользователя.

Поэтому перед установкой Manta показывает сводку, новые плагины сначала выключены, а при первом включении Manta спрашивает подтверждение.

Если плагин не работает¶

• Карточка показывает Ошибка и причину, например если нет python3.
• Показать журнал показывает последние сообщения плагина.
• Если плагин аварийно завершается, Manta перезапускает его — не более трех раз в минуту. После этого он остается в состоянии ошибки, пока вы не нажмете Обновить.
• Если в папке плагинов есть две папки с одинаковым идентификатором плагина, вторая показывает Не загружается и сообщение. Удалите одну из них.

Где хранятся плагины¶

При удалении плагина удаляется его папка; папка с его данными сохраняется.

Как написать плагин самому¶

Быстрее всего начать с примера Hello Python (examples/plugins/hello-python в исходном коде, с построчными комментариями, только стандартная библиотека Python). Его также можно установить в разделе Настройки → Плагины → Доступные. Есть и шаблоны для Node.js, shell (bash + jq) и Rust (examples/plugins/); для Rust есть также крейт manta-plugin-protocol.

Руководство, справочник по протоколу и примеры: Writing Manta plugins (docs/plugins.md).

Плагины могут говорить на всех языках Manta: Manta сообщает им текущий язык, а plugin.toml может содержать переведенные название и описание ([localized.ru], [localized.de] и т. д.).

Разработка и тестирование¶

• Перезагрузить плагины (палитра команд) перезапускает все работающие внешние плагины и заново просматривает папку плагинов.
• Режим разработчика: запустите Manta из Терминала командой /Applications/Manta.app/Contents/MacOS/manta --plugin-dev ~/code/my-plugin (можно указать несколько раз или задать переменную окружения MANTA_PLUGIN_DEV=dir1:dir2). В этом сеансе плагин работает прямо из этой папки — как доверенный, включенный и с меткой Разработка. Установленная копия с тем же идентификатором на это время отходит в сторону; ничего не сохраняется.
• Тест без Manta: python3 scripts/plugin-test.py путь/к/плагину.
• Упаковка: python3 scripts/plugin-pack.py путь/к/плагину создает файл .mantaplugin и выводит его контрольную сумму SHA-256 для каталога.
• Песочница: укажите разрешения, которые нужны вашему плагину, — без них он не сможет это делать. Если что-то запрещено, это видно в журнале (refused …).
• Журнал: Показать журнал на карточке или файл ~/Library/Application Support/Manta/plugin-data/<id>/plugin.log.

Подробнее: Develop and debug (docs/plugins.md, на английском).

Публикация плагина¶

Разместите плагин в публичном репозитории с лицензией, одобренной OSI, приложите файл .mantaplugin к релизу и откройте pull request, который добавляет его в plugins/registry.json. После этого он появится в разделе Обзор. Подробности: Publishing a plugin (docs/plugins.md, на английском).