Плагины

Плагин помогает добавить в Mockarty готовые моки, подключения или другой полезный контент. Например, комплект моков даёт команде тестовое API платёжного провайдера без настройки каждого мока вручную. Плагины поставляются в .zip-файлах; некоторые также содержат код в песочнице или панели интерфейса. Администратор устанавливает плагин для всей установки, а владелец пространства может поставить разрешённый плагин без кода только для своей команды.

Установить плагин из файла можно и без доступа к интернету. Здесь описаны установка и использование. Если вы создаёте свой плагин, откройте Написание плагинов; настройки кластера и безопасности приведены в Эксплуатации плагинов.

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

Нужна учётная запись администратора.

Веб-интерфейс: Панель администратора → вкладка Плагины → Установить плагин… → выберите .zip-файл, либо Установить по ссылке… → вставьте ссылку на .zip (по желанию его sha256, чтобы зафиксировать точные байты). Плагин появится в списке выключенным; нажмите Включить, чтобы активировать его вклады.

CLI:

mockarty-cli plugin install ./acme-kit.zip                    # из локального файла
mockarty-cli plugin install https://example.com/acme-1.0.0.zip  # по ссылке
mockarty-cli plugin install https://example.com/acme-1.0.0.zip --sha256 <hex>  # зафиксировать байты
mockarty-cli plugin enable acme.demo-kit
mockarty-cli plugin list

REST:

curl -X POST http://localhost:5770/api/v1/plugins \
  -H "X-API-Key: $TOKEN" \
  -F bundle=@acme-kit.zip
# либо установить по ссылке (сервер сам скачает; "sha256" фиксирует байты):
curl -X POST http://localhost:5770/api/v1/plugins/install-url \
  -H "X-API-Key: $TOKEN" -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/acme-1.0.0.zip"}'
curl -X POST http://localhost:5770/api/v1/plugins/acme.demo-kit/enable \
  -H "X-API-Key: $TOKEN"

После включения комплекты моков плагина появляются в каталоге «Комплекты моков» (в интерфейсе, REST и встроенных ИИ-инструментах) и инстанцируются как любой встроенный комплект. Выключение плагина убирает его комплекты из каталога; уже созданные из них моки остаются и редактируются как обычно.

Установка в своё пространство

Когда администратор это включил (Admin → Plugins), владелец пространства может установить плагин без администратора — из Настройки → Расширения. Выберите маркетплейс, видимый вашему пространству, найдите плагин, нажмите Установить. Такой плагин:

• работает только внутри вашего пространства — другие команды его контент не видят;
• должен быть полностью no-code (mock-киты, контент-паки, wiki-макросы, типы связей, пресеты коннекторов). Бандлы с WASM-модулями, панелями интерфейса, типами событий или типами задач отклоняются с понятной ошибкой — их по-прежнему ставит администратор;
• вы можете удалить его в любой момент из того же таба (уже созданный из него контент останется), а администраторы всегда видят его и тоже могут удалить.

При смене пространства в настройках список маркетплейсов и каталог плагинов загружаются для выбранного пространства заново.

Если маркетплейс не настроен, вкладка сообщает об этом и предлагает редактору пространства кнопку Добавить маркетплейс…. Укажите название и ссылку на index.json маркетплейса. Системный администратор может из того же пустого состояния открыть Администрирование → Плагины и загрузить .zip-бандл для всего инстанса. Пункт Встроенный реестр появляется только тогда, когда администратор настроил его на этом инстансе; это не встроенный онлайн-каталог.

GET /api/v1/marketplace/sources?namespace=<namespace> возвращает настроенные sources и права вызывающего canManageNamespace и canManageGlobal. Пустой массив sources означает, что просматривать пока нечего. Источник пространства добавляется через POST /api/v1/marketplace/sources с полями name, url и namespace; сервер проверяет право записи в пространство и ссылку на реестр до сохранения.

Тот же поток доступен ИИ-агентам по MCP: marketplace_catalog (смотрите на nsInstall: true), plugin_ns_install, plugin_ns_uninstall.

Попросить администратора установить плагин

Некоторые плагины устанавливает только администратор: они выполняют код внутри общего инстанса, поэтому ставятся один раз для всех. В Настройки → Расширения такой плагин помечен Только админ-установка, а рядом есть кнопка Попросить администратора.

1. Нажмите Попросить администратора.
2. Напишите, для чего вам нужен плагин. Поле обязательное — администратор решает по тому, что вы здесь напишете, поэтому пишите конкретно: какой сервис хотите тестировать и чем плагин поможет.
3. Нажмите Отправить заявку.

После этого заявки появляются в разделе Ваши заявки на той же вкладке — с состоянием и ответом администратора:

У пространства имён может быть одна ожидающая заявка на каждый плагин. Повторная заявка на тот же плагин отклоняется, пока на первую не ответили или пока вы её не отозвали.

Отправлять, видеть и отзывать заявки может только владелец пространства имён.

Администраторам. Откройте панель администратора → вкладка Плагины. В разделе Заявки от пространств имён собраны заявки, которые ждут ответа, — самые старые первыми: плагин, его версия, пространство, которое попросило, и причина, которую оно указало. Нажмите Одобрить или Отклонить и напишите ответ — владелец пространства его увидит. При отклонении причина обязательна.

Одобрение только фиксирует ваше решение. Оно ничего не устанавливает: установите бандл сами кнопками на той же вкладке (Установить плагин…, Установить по ссылке… или установка в один клик из раздела Доступны из реестра) и включите его.

REST. Владелец пространства отправляет заявку (reason обязателен, version и source — по желанию):

curl -X POST http://localhost:5770/api/v1/namespaces/team-a/plugin-install-requests \
  -H "X-API-Key: $TOKEN" -H 'Content-Type: application/json' \
  -d '{"plugin_id":"acme.ru-fakers","version":"1.0.0","reason":"Нужны российские ИНН и СНИЛС в платёжных моках"}'

В ответе — новая заявка с её id и "state": "pending". GET по тому же адресу возвращает заявки пространства, а POST .../plugin-install-requests/<id>/withdraw отзывает ожидающую.

Администратор читает очередь запросом GET /api/v1/plugin-install-requests?state=pending и отвечает на заявку ($REQUEST_ID — это id из очереди):

curl -X POST "http://localhost:5770/api/v1/plugin-install-requests/$REQUEST_ID/decide" \
  -H "X-API-Key: $TOKEN" -H 'Content-Type: application/json' \
  -d '{"state":"rejected","note":"Пока нет: код этого плагина ещё не проверила служба безопасности. Попросите снова после проверки."}'

state — это approved, rejected или installed. Для rejected поле note обязательно. На заявку отвечают один раз; installed принимается только для одобренной заявки и отмечает её выполненной после того, как вы установили бандл.

ИИ-агенты проходят тот же путь по MCP: plugin_install_request_create, plugin_install_request_list и plugin_install_request_withdraw — для владельца пространства; plugin_install_request_queue_list и plugin_install_request_decide — для администратора.

Готовые наборы

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

К каждому набору есть README, где написано, что он делает и чего не делает.
Прочитайте его до установки: набор готовит форму, но не переносит за вас данные.

Декларативные наборы ставятся как любой другой бандл. Нагрузочный обработчик —
справочник для автора и runtime, а не доказательство рабочего пути исполнения
заданий. Он поставляется исходниками со скриптом сборки, потому что программа
опознаётся по контрольной сумме именно собранных байтов; подробности в README.

Как написать плагин

Заготовка, правка, упаковка, установка:

mockarty-cli plugin create my-plugin
# отредактируйте my-plugin/plugin.json
cd my-plugin && zip -r my-plugin.zip plugin.json README.md
mockarty-cli plugin inspect my-plugin.zip   # офлайн-валидация
mockarty-cli plugin install my-plugin.zip

plugin.json описывает плагин и его вклады:

{
  "id": "acme.demo-kit",
  "name": "ACME demo kit",
  "version": "1.0.0",
  "description": "Моки партнёрского API ACME.",
  "author": {"name": "ACME", "url": "https://acme.example"},
  "contributes": {
    "mock_kits": [
      {
        "key": "acme_partner",
        "name": "ACME partner API",
        "mocks": [
          {"route": "/partner/ping", "method": "GET", "status_code": 200, "body": {"ok": true}}
        ]
      }
    ]
  }
}

Что важно знать:

• id — слаг в нижнем регистре (буквы, цифры, ., _, -) и он постоянный: установка бандла с тем же id обновляет плагин на месте.
• version — semver. Необязательный min_mockarty_version блокирует установку на слишком старый сервер.
• Ключи комплектов (key) не должны совпадать со встроенными комплектами и другими включёнными плагинами — при конфликте включение вернёт понятную ошибку.
• Неизвестные типы вкладов отклоняются при установке: опечатка никогда не превратится в тихое «ничего не произошло».

Кодовые расширения (WebAssembly)

Помимо готового контента, плагин может добавлять небольшие куски логики в виде
WebAssembly-модуля (.wasm). Модуль работает в строгой песочнице: он не имеет
доступа к файловой системе, сети и часам, а каждый вызов ограничен по времени и
памяти. Именно это нужно услышать офицеру ИБ банка или госсектора — кодовый
плагин не может сделать ничего, что хост явно не разрешил.

Первая точка расширения — кастомные faker-провайдеры. Модуль реализует
функцию, которая принимает {"name":"<faker>"} и возвращает
{"value":"<строка>"}, а манифест связывает её с именами фейкеров:

{
  "id": "acme.ru-fakers",
  "name": "Russian data fakers",
  "version": "1.0.0",
  "contributes": {
    "wasm": [
      {
        "point": "faker-provider",
        "module": "fakers.wasm",
        "fn": "faker",
        "exports": ["ru_inn", "ru_snils", "ru_ogrn"]
      }
    ]
  }
}

После включения плагина шаблон ответа мока использует новый фейкер как любой
встроенный:

{ "inn": "$.fake.ru_inn" }

Положите .wasm-файл рядом с plugin.json в бандл. Модуль должен экспортировать
memory, mk_alloc(size) и вашу функцию; подойдёт любой язык, компилируемый в
WebAssembly (Rust, Go/TinyGo, AssemblyScript, C).

Программы, которые приносит плагин

WebAssembly закрывает небольшие фрагменты логики. Некоторым задачам нужно
больше: нативная библиотека, свой стек протокола, сканер, расширение для
нагрузочного тестирования. Для них пакет плагина может принести собственную
программу — управляемый обработчик.

Текущий релиз содержит фундамент локального жизненного цикла: в Desktop и при
явном локальном/одноузловом размещении Mockarty выбирает сборку под хост,
сверяет контрольную сумму, запускает и проверяет здоровье процесса, ограничивает
циклы перезапуска и останавливает его при выключении, откате, отзыве или удалении.

Mockarty выдаёт программе отдельные учётные данные обработчика и настройки
подключения. Удаление, выключение и откат плагина отзывают эти учётные данные.
Управляемую программу можно запустить и наблюдать за ней, но отправка заданий
таким программам пока недоступна. Установка не делает объявленные типы
заданий исполнимыми; счётчики очереди и выполняемых заданий остаются нулевыми.

В кластере из нескольких узлов это, наоборот, запрещено — см. раздел
Где программе разрешено выполняться
ниже. Декларативных плагинов и WASM в песочнице это ограничение не касается.

Это самое серьёзное, что может запросить пакет, — поэтому оно и самое заметное:

• манифест обязан запросить разрешение runtime:managed-worker: пакет, который
  приносит программу молча, будет отклонён;
• в предпросмотре установки видны отметка управляемый обработчик, платформы,
  под которые есть сборки, и ограничения, с которыми обработчик будет работать;
• если сборки под вашу платформу нет или экземпляр настроен такие программы не
  запускать, предпросмотр скажет об этом до любой записи — у вас не появится
  установленное расширение, которое никогда не сможет стартовать.

Контракт пакета объявляет типы заданий и ресурсный конверт обработчика:

{
  "contributes": {
    "task_types": [
      { "type": "plugin-acme-scan", "name": "Проверка ACME", "description": "Запускает сканер ACME" }
    ],
    "workers": [
      {
        "key": "scanner",
        "name": "Сканер ACME",
        "task_types": ["plugin-acme-scan"],
        "limits": { "max_concurrent": 4, "memory_mb": 1024, "queue_depth": 50 },
        "health": { "path": "/healthz", "timeout_seconds": 30 },
        "artifacts": [
          { "os": "linux",  "arch": "amd64", "path": "bin/scanner-linux-amd64",  "sha256": "…" },
          { "os": "darwin", "arch": "arm64", "path": "bin/scanner-darwin-arm64", "sha256": "…" }
        ]
      }
    ]
  },
  "permissions": ["runtime:managed-worker"]
}

Обработчик может назвать только типы заданий, объявленные в том же пакете. Если
ограничения не указаны, Mockarty сохраняет осторожные значения, а не «без
ограничений». Ограничение параллелизма Mockarty передаёт программе. Отправка
заданий управляемым программам пока недоступна; глубина очереди сохраняется
для будущего использования. Предел памяти передаётся программе как бюджет — потолка на
уровне операционной системы он не ставит, так что это обязательство самой
программы, и предпросмотр перед установкой прямо об этом говорит.

Программа запускается в своей собственной папке — той, куда распакована её
сборка, — и получает только те настройки, которые ей даёт Mockarty, но не
окружение самого сервера. Ко всему за пределами этой папки обращайтесь по
абсолютным путям.

Что происходит, когда обработчик ведёт себя плохо

Сторонняя программа рано или поздно упадёт, и плагин, который не может
запуститься, не должен стоить вам сервера. Mockarty ограничивает цену:

• после неудачного запуска следующая попытка выполняется не сразу, и каждая
  следующая неудача увеличивает паузу — сломанный обработчик не крутится в
  цикле;
• после нескольких неудач подряд он помечается как остановлен после
  повторяющихся сбоев и больше не перезапускается до окончания паузы, а
  причина видна на карточке в разделе Администрирование → Плагины;
• обновление, обработчик которого так и не вышел в готовность, откатывается на
  ту версию, которая у вас работала.

В разделе Администрирование → Плагины рядом с плагином видно состояние каждого
обработчика (готов, запускается, перезапускается, остановлен).

Хранение

Программы, которые приносит пакет, хранятся по одному экземпляру на каждую
уникальную сборку: две версии с одинаковым двоичным файлом не займут место
дважды, а версия, на которую можно откатиться, сохраняет свою. После удаления
расширения его программы становятся высвобождаемыми — освободить место можно в
разделе Администрирование → Плагины.

Где программе разрешено выполняться

Mockarty решает это по тому, ЧЕМ является установка, а не по каждому пакету, и
решает осторожно: пакет объявляет программу, а оператор решает, запускает ли
эта машина программы вообще.

Кластерное поведение выбрано намеренно: узлы Mockarty заменяемы, поэтому
долгоживущая программа, запущенная внутри одного из них, жила бы и умирала
вместе со случайным узлом. Если вашему кластеру она всё-таки нужна — скажите
это явно настройкой ниже: Mockarty запустит ровно одну копию, на узле, который
сейчас ведущий, а не по копии на узел.

Оператору доступны три настройки:

• MOCKARTY_EXTENSION_WORKER_PLACEMENT — local запускает программы на этой
  машине, disabled не запускает никогда. Любое другое значение отклоняется и
  трактуется как disabled, поэтому опечатка не может расширить то, что
  выполняется. Расширения с программой отклоняются при установке с точной
  причиной, всё остальное продолжает работать.
• MOCKARTY_EXTENSION_WORKER_CACHE_DIR — где хранятся проверенные программы
  (по умолчанию — каталог extension-workers внутри вашего каталога данных).
  Каталог должен быть доступен Mockarty на запись и на исполнение.
• MOCKARTY_EXTENSION_ARTIFACT_QUOTA_MB — суммарный объём, который эти
  программы могут занимать (по умолчанию 4096). При превышении установка
  отклоняется с указанием занятого и запрошенного объёма.

Чью программу разрешено выполнять

Где выполняется программа и кто её написал — два разных вопроса. Бандл может
быть подписан издателем, чей ключ вы импортировали, а может не быть подписан
никем — и пока вы не скажете иначе, оба случая обрабатываются одинаково.

MOCKARTY_EXTENSION_NATIVE_TRUST отвечает именно за программы. На расширения,
которые добавляют только данные (наборы моков, типы связей, наборы контента), он
не влияет — они не запускают собственных программ, поэтому ужесточение этой
настройки их не отнимает.

Любое другое значение отклоняется и трактуется как signed-only, поэтому
опечатка не может расширить то, что выполняется. signed-only останавливает и
ту программу, которая была установлена до ужесточения настройки — проверка
выполняется каждый раз, когда Mockarty решает, что должно быть запущено, а не
только при установке. Судит она о том, кто подписал пакет на момент
установки: вывод ключа издателя из доверия прекращает новые установки от него
и не останавливает то, что вы уже запускаете. Чтобы остановить уже запущенный
пакет, используйте бюллетень безопасности.

Чтобы начать доверять издателю, импортируйте его trust-бандл:

mockarty-cli plugin trust import acme-publisher.json
mockarty-cli plugin trust list

После этого предпросмотр установки называет издателя вместо предупреждения о
неподтверждённом происхождении пакета.

Панели интерфейса

Плагин может добавить в Mockarty собственный экран. Объявите пункт сайдбара,
открывающий панель; панель — это HTML-страница из бандла, показываемая в
sandboxed-фрейме: она отрисовывает свою разметку, но не может дотянуться до
страницы хоста или вашей сессии.

{
  "id": "acme.dashboard",
  "name": "ACME dashboard",
  "version": "1.0.0",
  "contributes": {
    "ui": [
      {
        "point": "sidebar",
        "id": "acme-dash",
        "title": "ACME Dashboard",
        "icon": "chart-bar",
        "panel": "dashboard.html"
      }
    ]
  }
}

icon — id иконки Heroicon (без префикса hi-); panel — HTML-файл внутри
бандла. Положите HTML и всё, что ему нужно (CSS, JS, картинки), как ассеты
бандла. После включения плагина пункт появляется в сайдбаре у каждого
пользователя; клик открывает панель.

Разрешения (permissions)

Возможности, выходящие за пределы содержимого самого бандла, декларируются в
списке permissions манифеста — администратор просматривает их перед
установкой. Правила строгие:

• неизвестный ключ разрешения отклоняется при установке — возможность, которую
  этот Mockarty не понимает, нельзя молча «одобрить»;
• вклад, которому нужно разрешение, устанавливается только когда манифест его
  декларирует.

Сейчас применяемое разрешение:

Пример — внешне размещённая панель:

{
  "id": "acme.board",
  "name": "ACME board",
  "version": "1.0.0",
  "permissions": ["ui:external-panel"],
  "contributes": {
    "ui": [
      { "point": "sidebar", "id": "board", "title": "Board", "panel_url": "https://plugins.acme.com/board" }
    ]
  }
}

Без разрешения установка отклоняется с сообщением, где сказано, что именно
добавить. Панелям из бандла разрешение не нужно — проверенный бандл и есть
согласие.

Ключи с префиксом connect: (например, connect:read) приходят из
импортированных дескрипторов Atlassian Connect. Это информационное
происхождение — они показывают, что запрашивало исходное приложение, и ничего
не дают в Mockarty.

Происхождение пакета

Манифест может описывать, как собран бандл и что в него вошло:

{
  "provenance": {
    "source_url": "https://github.com/acme/mockarty-plugins",
    "source_revision": "9f2c1ab",
    "built_at": "2026-08-24T10:00:00Z",
    "builder": "GitHub Actions",
    "build_command": "mockarty-cli plugin pack ./acme-kit"
  },
  "sbom": [
    { "name": "leftpad", "version": "1.2.3", "license": "MIT" }
  ]
}

Оба блока показываются везде, где пакет просматривают, и оба — слова автора.
Mockarty проверяет, что поля пригодны (ссылка открывается, дата разбирается, у
компонента есть версия), но не подтверждает сами утверждения. Рядом стоит то,
что действительно проверено: подпись и издатель, которому она принадлежит.
Вместе они отвечают на вопрос «кто это говорит и точно ли это он».

Издатели и ключи подписи

Mockarty проверяет подписанный бандл по доверенным ключам издателей и
запоминает, каким именно ключом подписан каждый установленный плагин — в
списке плагинов видно имя издателя, а не просто «подписано».

Доверенные ключи приходят файлом, так же как бюллетени:

mockarty-cli plugin trust import acme-trust.json            # без подписи
mockarty-cli plugin trust import acme-trust.json acme.sig   # подписан уже доверенным ключом
mockarty-cli plugin trust list
mockarty-cli plugin trust retire <key-id>

Формат набора:

{
  "kind": "mockarty/plugin-trust",
  "version": 1,
  "publishers": [
    { "name": "ACME", "keys": [ { "publicKey": "<base64 ed25519 public key>" } ] }
  ]
}

Что важно знать:

• идентификатор ключа выводится из самого ключа, поэтому набор не может
  выдать чужой ключ за ключ известного издателя;
• отзыв ключа действует вперёд: новые установки с его подписью перестают
  считаться доверенными, а уже установленные плагины продолжают работать. Чтобы
  остановить то, что уже работает, импортируйте отзыв версии (ниже);
• набор, подписанный ключом, которому вы уже доверяете, принимается — так
  издатель меняет ключи без ручной передачи нового;
• ключи из MOCKARTY_PLUGINS_TRUSTED_KEYS продолжают работать и видны в списке
  под именем издателя environment.

Бюллетени безопасности и отзыв версий

Mockarty может хранить список заведомо небезопасных версий плагинов. Список —
это JSON-файл, который вы импортируете; изолированный контур использует ровно
тот же путь, что и подключённый, — «только онлайн» здесь нет:

mockarty-cli plugin advisories import advisories.json           # без подписи
mockarty-cli plugin advisories import advisories.json advisories.json.sig
mockarty-cli plugin advisories list

Каждая запись называет плагин, затронутые версии, важность и суть проблемы:

{
  "kind": "mockarty/plugin-advisories",
  "version": 1,
  "advisories": [
    { "id": "ACME-2026-001", "pluginId": "acme.kit", "severity": "high",
      "summary": "Что не так и что с этим делать.", "revoked": true,
      "affected": { "versions": ["1.0.0", "1.0.1"] } }
  ]
}

Запись обязана указать затронутые версии — перечислите их в versions,
задайте границы minVersion/maxVersion или напишите
"affected": {"allVersions": true}, если затронут весь плагин. Файл, который не
называет ничего, отклоняется при импорте: обрезанный или недоделанный фид не
сможет молча заблокировать все выпуски плагина — включая исправленный, который
вы как раз собирались поставить.
Два вида:

• отзыв ("revoked": true) — подходящие версии больше нельзя установить
  или включить, а уже включённая показывается как нездоровая с текстом
  бюллетеня, и вы решаете, что с ней делать;
• бюллетень (по умолчанию) — только информирует, работу никогда не
  блокирует.

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

Обновление и откат

Установка бандла с тем же id обновляет плагин на месте, сохраняя состояние
включения и настройки. Вместе с этим работают две защиты:

• Защита от понижения версии. Бандл с версией старее установленной
  отклоняется — случайно перезалитый старый файл не подменит более новый
  плагин. Повторите установку с «разрешить понижение» (интерфейс),
  --allow-downgrade (CLI) или "allow_downgrade": true (API), если это
  было намеренно.
• Откат. Каждое обновление сохраняет заменённый бандл. В разделе
  Администрирование → Плагины у такого плагина появляется кнопка Откатить,
  а из терминала то же делает mockarty-cli plugin rollback <plugin-id>.
  Сохранённый бандл проверяется как при обычной установке, поэтому откат,
  который сломал бы другой зависящий плагин, отклоняется с объяснением.

После отката в слоте оказывается версия, с которой вы откатились, — вернуться
вперёд можно одним нажатием. Удаление плагина очищает слот.

Каталоги показывают доступно обновление только когда опубликованная версия
действительно новее по семантическому версионированию: сама по себе несовпадающая
строка версии обновлением не считается.

Зависимости и совместимость

Плагин может требовать другие плагины и ограничивать поддерживаемые версии
Mockarty:

{
  "id": "acme.reports",
  "name": "ACME reports",
  "version": "1.0.0",
  "min_mockarty_version": "2.0.0",
  "max_mockarty_version": "3.0.0",
  "dependencies": [
    { "id": "acme.base-kit", "min_version": "1.2.0" }
  ]
}

Правила:

• зависимость должна быть уже установлена (и видима устанавливающему
  пространству) в требуемой версии — ошибка установки называет, что именно
  поставить сначала; ничего не скачивается автоматически;
• плагин, от которого зависят другие, отказывается удаляться, пока не удалены
  зависящие (выключить его можно всегда);
• хост новее max_mockarty_version отклоняет установку — публикуйте
  обновлённую сборку, вместо поломки в рантайме. Хосты старше версии, где
  появились эти поля, игнорируют их — сочетайте dependencies с
  соответствующим min_mockarty_version.

Секреты и подключения в настройках

Настройки плагина — это конфигурация, никогда не учётные данные. Если плагину
нужен секрет или существующая интеграция, объявите поле типизированной ссылкой
в settings_schema:

{
  "type": "object",
  "properties": {
    "api_token": { "type": "string", "format": "mockarty-secret-ref", "title": "API token" },
    "tracker":  { "type": "string", "format": "mockarty-connection-ref", "title": "Tracker connection" }
  }
}

Хранимое значение — указатель: secret://<хранилище>/<запись> (запись из
раздела Хранилища → Секреты) или connection://<id интеграции> (интеграция из
Настройки → Интеграции). Сырые учётные данные не подходят под форму и
отклоняются при сохранении — секрет не может осесть в настройках плагина.
Панели и API настроек видят только ссылку.

Подпись плагинов

По умолчанию подпись необязательна; для защищённых контуров её можно сделать обязательной.

mockarty-cli plugin keygen --out orgkey          # orgkey (приватный) + orgkey.pub
mockarty-cli plugin sign my-plugin.zip --key orgkey
mockarty-cli plugin inspect my-plugin.zip        # покажет статус подписи

На сервере:

• MOCKARTY_PLUGINS_TRUSTED_KEYS — публичные ключи (base64, через запятую), которым сервер доверяет — например, ключ вашей службы безопасности.
• MOCKARTY_PLUGINS_REQUIRE_SIGNATURE=true — отказывать в установке бандлам без подписи или с подписью недоверенным ключом.

Подпись покрывает содержимое бандла; результат проверки (unsigned / trusted / untrusted) сохраняется вместе с плагином и пишется в журнал аудита.

Реестр плагинов

Реестр — это опубликованный index.json со списком устанавливаемых плагинов (например, GitHub-репозиторий с бандлами в релизах). По умолчанию Mockarty не обращается ко внешнему реестру. Настройте его явно, если хотите видеть удалённые пакеты на вкладке «Плагины»; локальная установка бандла доступна без реестра.

Включить публичный или внутренний реестр:

export MOCKARTY_PLUGINS_REGISTRY_URL=https://raw.githubusercontent.com/your-org/mockarty-plugins/main/index.json

Отключить значение реестра, заданное окружением развёртывания:

export MOCKARTY_PLUGINS_REGISTRY_URL=off

С настроенным реестром:

• на вкладке «Плагины» появляется раздел «Доступны из реестра» с установкой в один клик;
• mockarty-cli plugin search [запрос] показывает опубликованное;
• mockarty-cli plugin install <plugin-id> ставит по имени;
• перед установкой загрузка сверяется с sha256 из индекса.

Чтобы опубликовать плагин, подготовьте запись для индекса и откройте pull request в репозиторий реестра:

mockarty-cli plugin publish my-plugin.zip \
  --download-url https://github.com/your-org/mockarty-plugins/releases/download/my-plugin-v1.0.0/my-plugin.zip

Сгенерированная запись содержит namespace_installable — может ли владелец
пространства имён установить бандл сам (чистый no-code контент) или его
устанавливает администратор (в бандле WASM-модули, UI-панели, типы событий или
типы задач). Каталоги показывают по нему правильное действие сразу, вместо
ошибки после нажатия «Установить».

Полное отключение плагинов

MOCKARTY_PLUGINS_ENABLED=false убирает механизм целиком: ни API-маршрутов плагинов, ни вкладки «Плагины», ни ИИ-инструментов для них. Используйте в средах, где сторонний контент запрещён.