Registry pluginów#

plugins.json — indeks repozytorium#

Każde repozytorium publikuje plik plugins.json z listą dostępnych pluginów:

{
  "version": 1,
  "name": "vCLU Official Plugins",
  "namespace": "vclu",
  "description": "Official plugin repository",
  "author": "vclu",
  "url": "https://github.com/Domktorymysli/vclu-plugins",
  "plugins": [
    {
      "id": "weather",
      "name": "Weather Plugin",
      "version": "1.0.0",
      "description": "Weather data from OpenWeatherMap",
      "author": "vclu",
      "path": "plugins/weather",
      "tags": ["weather", "api"]
    },
    {
      "id": "telegram",
      "name": "Telegram Bot",
      "version": "2.1.0",
      "description": "Telegram bot integration",
      "author": "vclu",
      "path": "plugins/telegram",
      "tags": ["notifications"]
    }
  ]
}

Pole	Typ	Opis
`version`	int	Wersja formatu (obecnie 1)
`name`	string	Nazwa repozytorium
`namespace`	string	Namespace pluginów (np. `"vclu"`)
`url`	string	URL repozytorium
`plugins`	array	Lista pluginów

Plugin listing#

Pole	Typ	Opis
`id`	string	Short ID pluginu
`name`	string	Nazwa wyświetlana
`version`	string	Wersja
`description`	string	Opis
`path`	string	Ścieżka w repozytorium (np. `"plugins/weather"`)
`tags`	array	Tagi

Zarządzanie repozytoriami#

Domyślne repozytorium#

vCLU zawiera domyślne repozytorium:

{
  "name": "vCLU Official",
  "url": "https://github.com/Domktorymysli/vclu-plugins",
  "enabled": true,
  "default": true
}

Repozytorium default: true nie może być usunięte.

Dodawanie repozytorium#

POST /api/plugins/repositories
{
  "name": "My Plugins",
  "url": "https://github.com/user/vclu-plugins"
}

Lista repozytoriów#

GET /api/plugins/repositories

Usuwanie repozytorium#

DELETE /api/plugins/repositories/:name

Instalacja z repozytorium#

Przebieg#

GET /api/plugins/available — pobiera plugins.json ze wszystkich repozytoriów
Użytkownik wybiera plugin w UI
POST /api/plugins/install z {id, fullId, repository}
Loader pobiera pliki z repozytorium:
- Buduje URL: {repoURL}/plugins/{id}/plugin.json
- Pobiera plugin.json + pliki z files[]
- Zapisuje do plugins/{namespace}--{id}/
Dodaje wpis do .vclu.json

URL resolution#

Dla GitHub:

Repo URL: https://github.com/user/repo
→ Raw base: https://raw.githubusercontent.com/user/repo/main/
→ plugins.json: {rawBase}/plugins.json
→ Plugin files: {rawBase}/{path}/init.lua

Konfiguracja w .vclu.json#

Zainstalowane pluginy zapisane w sekcji plugins:

{
  "plugins": {
    "repositories": [
      {
        "name": "vCLU Official",
        "url": "https://github.com/Domktorymysli/vclu-plugins",
        "enabled": true,
        "default": true
      }
    ],
    "installed": [
      {
        "id": "@vclu/weather",
        "version": "1.0.0",
        "enabled": true,
        "repository": "vCLU Official",
        "installedAt": "2026-02-17T10:30:00Z",
        "config": {
          "apiKey": "your-key",
          "city": "Warsaw",
          "interval": 3600
        }
      }
    ]
  }
}

Pola installed[]#

Pole	Typ	Opis
`id`	string	Full ID (`@namespace/shortId`)
`version`	string	Zainstalowana wersja
`enabled`	bool	Czy plugin aktywny
`repository`	string	Nazwa repozytorium źródłowego
`installedAt`	string	Data instalacji (ISO 8601)
`config`	object	Konfiguracja użytkownika

Oficjalne pluginy#

ID	Full ID	Wersja	Opis
weather	`@vclu/weather`	1.0.0	OpenWeatherMap
time-sync	`@vclu/time-sync`	1.0.0	WorldTimeAPI sync
sun-position	`@vclu/sun-position`	1.0.0	Pozycja słońca/księżyca
telegram	`@vclu/telegram`	2.1.0	Bot Telegram
salda-recuperator	`@vclu/salda-recuperator`	1.0.0	Rekuperator Salda
supla-power-meter	`@vclu/supla-power-meter`	1.0.0	Licznik Supla
influx-metrics	`@vclu/influx-metrics`	1.1.0	Metryki InfluxDB
example	`@vclu/example`	2.1.0	Szablon pluginu