From f3452876daeeccc2d302b42fb989cc50368775e1 Mon Sep 17 00:00:00 2001 From: "kirill.moos" Date: Tue, 30 Jun 2026 11:40:51 +0300 Subject: [PATCH] docs: add LICENSE and rewrite README for public release --- LICENSE | 21 ++++++ README.md | 207 +++++++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 196 insertions(+), 32 deletions(-) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..a3a63c3 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Wilix + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 14570b1..5e2726d 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,186 @@ -# Template Plugin +# Loop Plugin Starter Template -Шаблон плагина для LOOP. +Стартовый шаблон для разработки плагинов под Loop. + +Шаблон включает серверную часть на Go и клиентскую часть на React/TypeScript, настроенный билд через Makefile, пример REST API и базовую структуру Redux store. + +## Требования + +| Инструмент | Версия | +|-----------|--------| +| Go | 1.21+ | +| Node.js | 22+ | +| Yarn | 4.x | + +## Быстрый старт + +### 1. Клонировать шаблон + +```bash +git clone my-plugin +cd my-plugin +``` + +### 2. Переименовать плагин + +Откройте `plugin.json` и замените значения: + +```json +{ + "id": "ru.loop.plugin.my-plugin", + "name": "My Plugin", + "description": "Описание вашего плагина", + "version": "0.1.0" +} +``` + +### 3. Обновить Go-модуль + +В `go.mod` замените имя модуля: + +``` +module git.example.com/your-org/my-plugin +``` + +Затем обновите все импорты в `server/`: + +```bash +find server/ -type f -name "*.go" | xargs sed -i 's|git.wilix.dev/loop/loop-plugin-starter-template|git.example.com/your-org/my-plugin|g' +``` + +### 4. Установить зависимости и собрать + +```bash +# Go-зависимости устанавливаются автоматически при сборке + +# Webapp-зависимости +cd webapp && yarn install && cd .. + +# Полная сборка (server + webapp + bundle) +make dist +``` + +Собранный плагин будет в `dist/-.tar.gz`. ## Структура проекта -- `server/` - серверная часть плагина (Go) -- `webapp/` - клиентская часть плагина (React/TypeScript) -- `plugin.json` - манифест плагина -- `plugin.go` - точка входа плагина - -## Установка и сборка - -```bash -cd server -go mod download - -cd ../webapp -yarn install - -cd .. - -make build +``` +├── plugin.json # Манифест плагина (ID, имя, версия) +├── Makefile # Команды сборки +├── .env.example # Пример переменных окружения +│ +├── server/ +│ ├── main.go # Точка входа серверной части +│ └── plugin/ +│ ├── plugin.go # Основная логика плагина (OnActivate/OnDeactivate) +│ ├── api.go # HTTP маршруты и обработчики +│ ├── configuration.go # Конфигурация плагина +│ ├── store.go # Работа с key-value хранилищем +│ └── telemetry.go # Телеметрия +│ +└── webapp/ + └── src/ + ├── index.tsx # Точка входа клиентской части + ├── registerApp.tsx # Регистрация компонентов в Loop + ├── components/ + │ └── RootComponent.tsx # Корневой React-компонент + ├── store/ + │ ├── actions.ts # Redux actions + │ └── reducers.ts # Redux reducers + └── utils/ + ├── api.ts # Запросы к серверной части плагина + └── usePlugin.ts # Хук для доступа к API плагина ``` -## Разработка +## Что нужно изменить -Для разработки используйте команды из Makefile: +### Серверная часть -- `make server` - сборка серверной части -- `make webapp` - сборка клиентской части -- `make dist` - полная сборка плагина -- `make check-style` - проверка стиля кода -- `make test` - запуск тестов +**`server/plugin/plugin.go`** — основная логика: +- `OnActivate` — вызывается при включении плагина +- `OnDeactivate` — вызывается при выключении -## Настройка +**`server/plugin/api.go`** — REST API: +- Добавляйте маршруты в `InitApi()` +- Пример маршрута `/example` уже включён -Измените следующие файлы для настройки плагина: +**`server/plugin/configuration.go`** — настройки плагина: +- Добавьте поля в структуру `Configuration` +- Они будут доступны в панели администратора Loop -- `plugin.json` - ID, имя и описание плагина -- `server/plugin/plugin.go` - основная логика сервера -- `webapp/src/index.tsx` - точка входа клиентской части -- `webapp/src/components/RootComponent.tsx` - корневой компонент React +### Клиентская часть + +**`webapp/src/registerApp.tsx`** — регистрация в Loop: +- Регистрация Redux reducer +- Регистрация React-компонентов через `registry` + +**`webapp/src/components/RootComponent.tsx`** — основной компонент: +- Точка входа для отображения вашего UI + +**`webapp/i18n/`** — переводы: +- `en.json` — английские строки +- `ru.json` — русские строки + +## Makefile: команды сборки + +```bash +make dist # Полная сборка (server + webapp + tar.gz) +make server # Только серверная часть +make webapp # Только клиентская часть +make check-style # Линтинг (golangci-lint + eslint) +make test # Запуск тестов +make clean # Очистить артефакты сборки +make deploy # Сборка и деплой на сервер (требует .env) +make watch # Сборка + hot reload webapp +``` + +Полный список команд: `make help` + +## Переменные окружения + +Скопируйте `.env.example` в `.env` и заполните: + +```bash +cp .env.example .env +``` + +| Переменная | Описание | +|-----------|----------| +| `MM_SERVICESETTINGS_SITEURL` | URL вашего Loop-сервера (для деплоя) | +| `MM_ADMIN_TOKEN` | Токен администратора (для деплоя через `make deploy`) | +| `MM_SERVICESETTINGS_ENABLEDEVELOPER` | `true` — билд только под текущую ОС (ускоряет разработку) | +| `MM_DEBUG` | `true` — билд без оптимизаций (для отладчика dlv) | + +## Деплой + +### Ручной деплой + +1. Соберите плагин: `make dist` +2. Загрузите `dist/-.tar.gz` в Loop: + **Администрирование → Управление плагинами → Загрузить плагин** + +### Деплой через `make deploy` + +Требует заполненного `.env` с `MM_SERVICESETTINGS_SITEURL` и `MM_ADMIN_TOKEN`: + +```bash +make deploy +``` + +### CI/CD + +В директории `.gitea/workflows/` есть пример workflow для Gitea Actions. +Адаптируйте его под вашу CI/CD систему. + +## Отладка + +Для удалённой отладки серверной части с помощью [Delve](https://github.com/go-delve/delve): + +```bash +MM_DEBUG=true make deploy # Билд без оптимизаций +make attach-headless # Attach dlv на порт 2346 +``` + +## Лицензия + +[MIT](LICENSE)