Aurobore

Тема

Plugin System (система плагинов) ​

Модель плагина, манифест, версионирование, разрешения. Архитектура без реализации. Решение — ADR-003. Подробный контракт API — plugins/plugin-api.md.

Плагин — единица расширения платформы, добавляющая нативную возможность и её типизированный JS-интерфейс. Плагины — первоклассная сущность: устанавливаются, обнаруживаются и регистрируются автоматически, без ручной правки нативных конфигов (в отличие от Cordova).

1. Что такое плагин ​

Плагин = манифест (контракт) + нативная реализация (C++/QML) + сгенерированная JS-обёртка

  • сгенерированные TS-типы + (опционально) ресурсы.
plugins/camera/
├── plugin.manifest         # КОНТРАКТ: методы, события, типы, разрешения, нативные зависимости
├── native/                 # нативная реализация (C++/QML), пишет автор плагина
├── generated/              # JS-обёртка + TS-типы (КОДОГЕНЕРАЦИЯ из манифеста, не редактируется)
├── package metadata        # для дистрибуции (npm)
└── docs / examples         # документация и примеры использования

Принцип SoT: манифест — единственный источник истины. Из него генерируются JS-обёртка, типы, регистрация и документация. Это исключает рассинхронизацию слоёв.

2. Сущности, входящие в плагин ​

СущностьНазначение
ИдентичностьИмя, npm-имя, semver-версия, отображаемое имя плагина (Camera → Aurobore.Camera).
Методы (commands)Вызываемые из JS операции: имя, схема аргументов, схема результата, async/стрим.
СобытияИмена и схемы данных событий, которые плагин эмитит в JS.
ТипыОбщие структуры данных, используемые в методах/событиях (для генерации TS-типов).
РазрешенияКакие системные разрешения требует плагин (камера, геолокация, интернет, …).
Области (scopes)Уточнение разрешений (например, FS — каталог данных приложения).
Нативные зависимостиПакеты/модули Аврора и их версии (для генерации .spec/CMake): напр. ru.auroraos.webview, Qt-модули.
СовместимостьДиапазон версий Runtime/протокола моста, минимальная версия ОС Аврора, поддерживаемые движки.
Платформенные нюансыРазличия поведения по версиям движка/ОС, если есть.

3. Манифест (концептуально) ​

Манифест декларативен и человеко-/машиночитаем (формат — JSON/подобный, фиксируется в ADR-006):

name: "camera"
display: "Camera"            // → Aurobore.Camera
version: "1.0.0"
engineCompat: { runtime: ">=1.0 <2.0", bridgeProtocol: 1 }
auroraCompat: { minOs: "5.1.3", engines: ["chromium", "gecko"] }
permissions: ["camera"]
nativeDeps: { rpm: ["…"], qt: ["…"] }
types:
  Photo: { uri: string, width: int, height: int, format: string }
methods:
  getPhoto:  { args: { quality?: int, allowEditing?: bool }, result: Photo }
  pickPhoto: { args: {}, result: Photo }
events:
  # (если есть) например, captureProgress: { percent: int }

4. Жизненный цикл плагина в системе ​

  1. Установка — автор/пользователь добавляет плагин (aurobore plugin add camera); CLI ставит npm-пакет и регистрирует его в проекте.
  2. Кодогенерация — из манифеста генерируются JS-обёртка и TS-типы.
  3. Сборка — Build System включает нативную часть и её зависимости в генерируемый проект Аврора.
  4. Старт Runtime — Plugin Loader обнаруживает плагин, проверяет совместимость, регистрирует в Plugin Manager и экспортирует API в JS.
  5. Исполнение — вызовы/события маршрутизируются Bridge ↔ Plugin Manager ↔ плагин.
  6. Выгрузка/обновление — при остановке приложения; обновление — через смену версии и пересборку.

5. Версионирование и совместимость ​

  • Каждый плагин — semver.
  • Манифест объявляет совместимость с версией Runtime и протокола моста, минимальной версией ОС и поддерживаемыми движками.
  • При несовпадении Runtime не регистрирует плагин и выдаёт понятную ошибку (а не падает).
  • Это позволяет Runtime, мосту и плагинам эволюционировать независимо (NFR-5).

6. Разрешения и безопасность ​

  • Требуемые разрешения объявляются в манифесте → агрегируются в конфиге → проецируются в артефакты Аврора (.desktop) при сборке.
  • Перед вызовом метода Bridge проверяет наличие разрешения и область.
  • Плагин не получает доступ за пределами объявленных областей.

7. Типы плагинов ​

  • Стандартные (core) — официальные плагины Aurobore (см. standard-plugins.md).
  • Сторонние (community) — публикуются в npm, ставятся как обычные зависимости, автоинтегрируются.
  • Локальные (app-specific) — плагины внутри конкретного проекта (не публикуемые).

8. Связи ​

  • ↔ Plugin Loader — обнаружение и регистрация.
  • ↔ Bridge — транспорт вызовов/событий.
  • ↔ TypeScript SDK — потребление сгенерированных обёрток/типов.
  • ↔ Build System — включение нативной части и зависимостей.
  • ↔ Native SDK — контракты для написания нативной части.