5.6 KiB

Raw Blame History

Plugin Packaging

Описание сборки и упаковки плагинов для дистрибуции.

Source Plugin Layout

Исходная структура плагина в монорепо verstak-official-plugins:

plugin-name/
  plugin.json           — обязательный manifest
  frontend/
    package.json        — npm проект (Svelte)
    src/
      index.js          — entry point
      ...
    dist/               — сборка frontend (npm run build)
      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           — копируется из корня исходного плагина
    frontend/
      dist/               — только собранные файлы (копируется содержимое)
        index.js
        style.css
    backend/
      plugin-name         — скомпилированный бинарник (копируется из backend/)

Что попадает в dist

plugin.json

Копируется как из корня исходного плагина. Содержит:

Поле	Назначение в dist
`id`, `name`, `version`, `apiVersion`, `schemaVersion`	Идентификация
`provides`	Capabilities плагина
`requires`, `optionalRequires`	Зависимости от capabilities
`permissions`	Запрашиваемые разрешения
`frontend.entry`	Путь к frontend entry (относительно корня плагина)
`contributes`	UI contributions

frontend/dist

Содержимое frontend/dist/ копируется в dist/<plugin-name>/frontend/dist/. Это результат npm run build — скомпилированные JS/CSS без map-файлов и dev-зависимостей.

backend binary

Если в исходном плагине есть backend/ с go.mod или main.go, собирается через:

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/`)	Настройки разработчика

Сборка

Полная сборка всех плагинов

cd ~/git/verstak2/verstak-official-plugins
./scripts/build.sh

build.sh для каждого плагина в plugins/:

Проверяет plugin.json (JSON validation).
Собирает frontend: npm install && npm run build.
Собирает backend: go build -o <plugin-name> ..
Упаковывает в dist/<plugin-name>/ через package_plugin().

Сборка конкретного плагина

cd ~/git/verstak2/verstak-official-plugins/plugins/platform-test
# Frontend
cd frontend && npm install && npm run build
# Backend (если есть)
cd ../backend && go build -o platform-test .
# Package
mkdir -p ../../dist/platform-test
cp plugin.json ../../dist/platform-test/
cp -r frontend/dist/. ../../dist/platform-test/frontend/dist/
cp backend/platform-test ../../dist/platform-test/backend/

Backend build details

cd backend
go mod download  # загрузить зависимости
go build -o <plugin-name> .  # скомпилировать бинарник

Имя бинарника совпадает с именем директории плагина (например, platform-test).

Бинарник должен быть самодостаточным: все зависимости статически линкуются (CGO_ENABLED=0 для кросс-платформенности при необходимости).

Установка в dev-среде

cd ~/git/verstak2/verstak-desktop
./scripts/install-dev-plugins.sh

Скрипт:

Находит verstak-official-plugins как sibling-репозиторий (../verstak-official-plugins).
Если dist/platform-test/ отсутствует — запускает build.sh.
Копирует dist/platform-test/ в ./plugins/platform-test/ (atomic через temp dir).
Проверяет наличие plugin.json.

Директория ./plugins/ в verstak-desktop не коммитится (.gitignore).

Установка пользователем

Пользовательские плагины размещаются в ~/.config/verstak/plugins/<plugin-name>/ с той же структурой, что и dist-пакет:

~/.config/verstak/plugins/
  some-plugin/
    plugin.json
    frontend/dist/
    backend/

Plugin discovery сканирует эту директорию автоматически.

5.6 KiB Raw Blame History Unescape Escape