167 lines
6.3 KiB
Markdown
167 lines
6.3 KiB
Markdown
# Plugin Packaging
|
||
|
||
Описание сборки и упаковки плагинов для дистрибуции.
|
||
|
||
## Source Plugin Layout
|
||
|
||
Исходная структура плагина в монорепо `verstak-official-plugins`:
|
||
|
||
```
|
||
plugin-name/
|
||
plugin.json — обязательный manifest
|
||
frontend/
|
||
package.json — опционально, npm проект (Svelte/Vite)
|
||
src/
|
||
index.js — source entry point для plain JS plugins
|
||
...
|
||
dist/ — ignored build output для npm frontend plugins
|
||
index.js
|
||
style.css
|
||
backend/ — опционально (Go sidecar)
|
||
go.mod
|
||
main.go
|
||
migrations/ — опционально
|
||
001_init.sql
|
||
assets/ — опционально
|
||
README.md
|
||
```
|
||
|
||
## Dist Plugin Package Layout
|
||
|
||
Результат сборки (`dist/<plugin-name>/`) — это минимальный пакет для установки:
|
||
|
||
```
|
||
dist/
|
||
plugin-name/
|
||
plugin.json — manifest для runtime package
|
||
frontend/
|
||
dist/ — только собранные файлы (копируется содержимое)
|
||
index.js
|
||
style.css
|
||
backend/
|
||
plugin-name — скомпилированный бинарник (копируется из backend/)
|
||
```
|
||
|
||
## Что попадает в dist
|
||
|
||
### plugin.json
|
||
|
||
Исходный `plugin.json` копируется в package. Если plain JS plugin в исходниках
|
||
указывает `frontend.entry` на `frontend/src/index.js`, `build.sh` переписывает
|
||
это поле в packaged manifest на `frontend/dist/index.js`.
|
||
|
||
Содержит:
|
||
|
||
| Поле | Назначение в dist |
|
||
|---|---|
|
||
| `id`, `name`, `version`, `apiVersion`, `schemaVersion` | Идентификация |
|
||
| `provides` | Capabilities плагина |
|
||
| `requires`, `optionalRequires` | Зависимости от capabilities |
|
||
| `permissions` | Запрашиваемые разрешения |
|
||
| `frontend.entry` | Путь к frontend entry (относительно корня плагина) |
|
||
| `contributes` | UI contributions |
|
||
|
||
### frontend/dist
|
||
|
||
Для plugins с `frontend/package.json` содержимое `frontend/dist/` копируется в
|
||
`dist/<plugin-name>/frontend/dist/`. Это результат `npm run build` —
|
||
скомпилированные JS/CSS без map-файлов и dev-зависимостей.
|
||
|
||
Для plain JS plugins без `frontend/package.json` `build.sh` всегда копирует
|
||
tracked `frontend/src/index.js` в `dist/<plugin-name>/frontend/dist/index.js`.
|
||
Ignored source-side `frontend/dist/` не используется для таких plugins, чтобы
|
||
локальные stale build artifacts не попадали в package.
|
||
|
||
### backend binary
|
||
|
||
Если в исходном плагине есть `backend/` с `go.mod` или `main.go`, собирается через:
|
||
|
||
```bash
|
||
cd backend && go build -o <plugin-name> .
|
||
```
|
||
|
||
Бинарник копируется в `dist/<plugin-name>/backend/<plugin-name>` с правами `+x`.
|
||
|
||
## Что НЕ попадает в dist
|
||
|
||
| Исключение | Причина |
|
||
|---|---|
|
||
| `node_modules/` | Dev dependency, не нужны в runtime |
|
||
| `.git/` | Git metadata |
|
||
| Go source files (`*.go`, `go.mod`, `go.sum`) | Исходный код backend, не нужен после компиляции |
|
||
| Frontend source (`src/`, `package.json`, `package-lock.json`) | Исходный код frontend, нужен только dist/ |
|
||
| Test files (`*_test.go`, `*.test.js`) | Тесты |
|
||
| Test cache (`testdata/`, `coverage/`) | Артефакты тестирования |
|
||
| IDE configs (`.vscode/`, `.idea/`) | Настройки разработчика |
|
||
|
||
## Сборка
|
||
|
||
### Полная сборка всех плагинов
|
||
|
||
```bash
|
||
cd ~/git/verstak2/verstak-official-plugins
|
||
./scripts/build.sh
|
||
```
|
||
|
||
`build.sh` для каждого плагина в `plugins/`:
|
||
|
||
1. Проверяет `plugin.json` (JSON validation).
|
||
2. Собирает frontend для plugins с `frontend/package.json`: `npm install && npm run build`.
|
||
3. Собирает backend: `go build -o <plugin-name> .`.
|
||
4. Упаковывает в `dist/<plugin-name>/` через `package_plugin()`. Plain JS
|
||
frontend берётся из `frontend/src/index.js`, packaged manifest получает
|
||
`frontend.entry = "frontend/dist/index.js"`.
|
||
|
||
### Сборка конкретного плагина
|
||
|
||
```bash
|
||
cd ~/git/verstak2/verstak-official-plugins
|
||
./scripts/build.sh
|
||
```
|
||
|
||
`build.sh` intentionally packages all official plugins because packaging includes
|
||
manifest rewriting for plain JS plugins. Do not hand-copy `plugin.json` for a
|
||
plain JS plugin without applying the same `frontend.entry` rewrite.
|
||
|
||
### Backend build details
|
||
|
||
```bash
|
||
cd backend
|
||
go mod download # загрузить зависимости
|
||
go build -o <plugin-name> . # скомпилировать бинарник
|
||
```
|
||
|
||
Имя бинарника совпадает с именем директории плагина (например, `platform-test`).
|
||
|
||
Бинарник должен быть самодостаточным: все зависимости статически линкуются (CGO_ENABLED=0 для кросс-платформенности при необходимости).
|
||
|
||
## Установка в dev-среде
|
||
|
||
```bash
|
||
cd ~/git/verstak2/verstak-desktop
|
||
./scripts/install-dev-plugins.sh
|
||
```
|
||
|
||
Скрипт:
|
||
|
||
1. Находит `verstak-official-plugins` как sibling-репозиторий (`../verstak-official-plugins`).
|
||
2. Если `dist/platform-test/` отсутствует — запускает `build.sh`.
|
||
3. Копирует `dist/platform-test/` в `./plugins/platform-test/` (atomic через temp dir).
|
||
4. Проверяет наличие `plugin.json`.
|
||
|
||
Директория `./plugins/` в `verstak-desktop` не коммитится (`.gitignore`).
|
||
|
||
## Установка пользователем
|
||
|
||
Пользовательские плагины размещаются в `~/.config/verstak/plugins/<plugin-name>/` с той же структурой, что и dist-пакет:
|
||
|
||
```
|
||
~/.config/verstak/plugins/
|
||
some-plugin/
|
||
plugin.json
|
||
frontend/dist/
|
||
backend/
|
||
```
|
||
|
||
Plugin discovery сканирует эту директорию автоматически.
|