@orbito/omm (0.4.0)
Installation
@orbito:registry=https://git.kozminski.net.pl/api/packages/orbito/npm/npm install @orbito/omm@0.4.0"@orbito/omm": "0.4.0"About this package
OMM — OrbitoModulesManager
CLI do pakowania i publikacji modułów Orbito na repozytorium modułów
(modules.orbito.pl) — odpowiednik npm publish dla modułów.
Tożsamość paczki (kod modułu i wersja) pochodzi wyłącznie z module.json
w katalogu modułu. Karta modułu musi już istnieć w repozytorium (tworzy się ją
w panelu developera) — pierwsza publikacja nie tworzy modułu automatycznie.
Instalacja
npm i -g @orbito/omm
Paczka jest na razie w prywatnym rejestrze npm (Gitea) — wymagany wpis
w ~/.npmrc (ten sam co dla @orbito/api-lib):
@orbito:registry=https://git.kozminski.net.pl/api/packages/orbito/npm/
//git.kozminski.net.pl/api/packages/orbito/npm/:_authToken=<token>
Wymagany Node.js >= 18.13. Do pracy nad samym CLI: npm install && npm link
w katalogu repo.
Publikacja nowej wersji CLI: podbij version w package.json i npm publish
(rejestr ustawiony w publishConfig).
Użycie
omm login # logowanie hasłem; generuje i zapisuje token publikacji
omm login --token omm_abc... # wariant CI: gotowy token
omm whoami # kto jest zalogowany
omm logout # unieważnia token i usuwa go z konfiguracji
omm pack --dry-run # pokaż, co wejdzie do paczki
omm pack # zbuduj ZIP lokalnie (bez wysyłania)
omm publish # spakuj + wgraj WERSJĘ ROBOCZĄ + poczekaj na build Dockera
omm publish --release # jak wyżej + opublikuj w rejestrze (draft → published)
omm publish --no-wait # wgraj draft i nie czekaj na build
omm publish --changelog "..." # z opisem zmian
omm dev # uruchom moduł lokalnie i podepnij do firmy w Orbito
omm dev unlink # odepnij instancję deweloperską
omm secrets list # sekrety modułu ze statusem (bez wartości)
omm secrets set ALLEGRO_CLIENT_ID # ustaw wartość (prompt bez echa)
omm secrets unset ALLEGRO_CLIENT_ID # usuń wartość
Domyślnie publish wysyła wersję roboczą (draft) — do testów. Publikacja
w rejestrze (widoczna dla firm) wymaga świadomego --release.
Wersję nowej publikacji podbija się edytując pole version w module.json
(musi być semver wyższy niż ostatnio opublikowana wersja).
Konfiguracja
~/.config/omm/config.json— zapisany token publikacji per rejestr (tworzone przezomm login).OMM_TOKEN— token publikacji z env (ma priorytet nad configiem; do CI).OMM_REGISTRY/--registry— adres API rejestru (domyślniehttps://modules.orbito.pl/api).OMM_SECRET_VALUE— wartość dlaomm secrets setbez promptu (CI).
Co trafia do paczki
Jeśli module.json ma pole files (tablica ścieżek) — tylko wskazane pliki
i katalogi (module.json dołączany zawsze). Bez files — cały katalog modułu
z wyłączeniami: node_modules/, .git/, .env*, .npmrc, *.zip,
make-zip.sh, pliki edytorów.
omm.config.js i .omm-dev.json (konfiguracja i stan trybu deweloperskiego —
sekret oraz id instancji) są wykluczone zawsze, także gdy zostaną wymienione
w polu files.
.npmrc jest wykluczony domyślnie (sekrety w paczce). Jeśli build Dockera
modułu wymaga prywatnych paczek npm, trzeba świadomie dodać --include-npmrc.
Tryb deweloperski (omm dev)
omm dev uruchamia moduł jako zwykły proces Node (node --watch index.js)
i podpina go do wybranej firmy w Orbito Core — bez publikacji w rejestrze
i bez builda obrazu Dockera. Moduł rejestruje się w core dokładnie tak jak
kontener produkcyjny, więc strony, metody i hooki działają normalnie,
a zmiana pliku restartuje tylko proces modułu.
Wymaga core z włączonym trybem dev (DEV_MODULES_ENABLED=true,
DEV_MODULES_SECRET=<sekret> w .env core — nigdy na produkcji).
omm dev # katalog bieżący, core http://localhost:3003
omm dev -C ../modules/core.orders # inny katalog modułu
omm dev --core http://core.dev:3003 --company 665f... --name sklep-1
omm dev --no-watch --debug # bez hot reloadu, z logami SDK (ORBITO_DEBUG=1)
omm dev unlink # wyłącza instancję z ostatniego linku
omm dev unlink --instance 665f... # albo wskazaną
Gdy companyId nie jest podany, CLI pobiera listę firm z core: przy jednej
firmie używa jej automatycznie, przy wielu wypisuje listę id i kończy pracę.
omm.config.js
Opcjonalny plik w katalogu modułu (CommonJS albo ESM — zależnie od typu paczki):
module.exports = {
coreUrl: 'http://localhost:3003', // adres Orbito Core
devSecret: 'ten-sam-co-DEV_MODULES_SECRET',
companyId: '665f1c2b3a4d5e6f70819293',
instanceName: 'sklep-1', // dla modułów niesingletonowych
entry: 'index.js', // plik startowy modułu
watch: true, // node --watch
debug: false // ORBITO_DEBUG=1
};
Priorytet ustawień: flaga CLI > zmienna środowiskowa (OMM_CORE_URL,
OMM_DEV_SECRET, OMM_COMPANY_ID, OMM_INSTANCE_NAME) > omm.config.js >
wartości domyślne. Sekretu nie da się podać flagą CLI — byłby widoczny
w liście procesów.
omm.config.js zawiera sekret, a .omm-dev.json (stan ostatniego linku)
id instancji — dopisz oba do .gitignore modułu. Do paczki publikowanej
przez omm pack/omm publish nie trafiają.
Jak to działa
POST /dev/modules/link— core tworzy (lub aktualizuje) instancję z flagądev: truei wydaje jednorazowy token rejestracji oraz adres RPC.- CLI uruchamia
node [--watch] <entry>zORBITO_HOST,ORBITO_PORT(puste przy unix sockecie),ORBITO_TOKEN,ORBITO_INSTANCE_ID,ORBITO_COMPANY_ID,ORBITO_MODULE_CODE,ORBITO_MODULE_VERSION,ORBITO_DEBUGoraz zmiennymi z.envmodułu (patrz niżej). - Nadzorca odpytuje
GET /dev/modules/pingco 3 s i porównujebootIdcore. ZmianabootId= core wstał od nowa (nowa ścieżka socketu RPC, nowe tokeny), czego sam moduł by nie zauważył — nadzorca ubija go, pobiera świeży token i uruchamia z nowym adresem RPC. Gdy core nie odpowiada (trwa restart), nadzorca po prostu czeka na kolejny ping. - Gdy proces modułu padnie sam (błąd w kodzie, odrzucona rejestracja),
nadzorca czeka 2 s, ponawia link ze świeżym tokenem (z backoffem do 10 s,
gdy core nie odpowiada) i startuje moduł ponownie.
Ctrl+Czatrzymuje moduł, ale nie odpina instancji — do tego służyomm dev unlink. - Podbicie
versionwmodule.jsoni ponownyomm devaktualizuje wersję instancji dev (core doręczaMODULE_ENABLEDjak przy aktualizacji).
Sekrety lokalnie (.env)
omm dev nie pobiera wartości sekretów z repozytorium (API ich nie zwraca).
Zamiast tego wczytuje plik .env z katalogu modułu i dokłada zmienne do
środowiska procesu modułu — moduł czyta je z process.env tak samo jak
na produkcji:
# .env w katalogu modułu
ALLEGRO_CLIENT_ID=abc123
ALLEGRO_CLIENT_SECRET="wartość ze spacjami"
Format: KEY=VALUE w każdej linii, linie puste i zaczynające się od #
są pomijane, cudzysłowy wokół wartości (pojedyncze lub podwójne) są zdejmowane,
bez interpolacji ${...} i bez wartości wielolinijkowych.
Pierwszeństwo: zmienne ORBITO_* ustawiane przez omm > zmienne środowiska,
w którym uruchomiono omm dev > .env. Przy starcie CLI wypisuje, ile zmiennych
wczytało (bez wartości). Zmiana .env wymaga ponownego uruchomienia omm dev
(node --watch restartuje moduł z tym samym środowiskiem).
.env* nie trafia do paczki (omm pack/omm publish) — dopisz .env
do .gitignore modułu.
Sekrety modułu (omm secrets)
Klucze aplikacji (np. client ID/secret marketplace'u) nie powinny leżeć w kodzie modułu. Wartości trzyma repozytorium modułów — zaszyfrowane, globalnie per kod modułu (nie per wersja ani per firma). Rdzeń pobiera je przy starcie kontenera modułu i przekazuje jako zmienne środowiskowe.
Moduł deklaruje sekrety w module.json (bez wartości):
{
"name": "core/allegro",
"version": "1.2.0",
"secrets": [
{ "name": "ALLEGRO_CLIENT_ID", "description": "Client ID aplikacji Allegro (produkcja)" },
{ "name": "ALLEGRO_CLIENT_SECRET" }
]
}
Nazwa: ^[A-Z][A-Z0-9_]*$, max 64 znaki, bez prefiksu ORBITO_ (zarezerwowany
dla rdzenia), bez duplikatów; description opcjonalny, max 200 znaków.
omm secrets list # kod modułu z ./module.json
omm secrets list --module core/allegro # albo wskazany
omm secrets set ALLEGRO_CLIENT_SECRET # wartość z promptu bez echa
OMM_SECRET_VALUE=... omm secrets set ALLEGRO_CLIENT_SECRET # CI, bez promptu
omm secrets unset ALLEGRO_CLIENT_SECRET
listpokazuje sumę sekretów zadeklarowanych w ostatniej wersji i zapisanych, ze statusemustawiony/brak wartości/niezadeklarowany— nigdy wartości.setdziała także dla nazwy jeszcze niezadeklarowanej (wartości można ustawić przed pierwszą publikacją). Pusta wartość to błąd.- Nowa wartość trafia do kontenerów przy ich najbliższym starcie — bez publikacji nowej wersji modułu.
- Publikacja nie jest blokowana przy brakujących wartościach —
omm publish --releasewypisze ostrzeżenie⚠dla każdego zadeklarowanego sekretu bez wartości.
Jak działa publikacja
POST /developer/publish— upload ZIP-a; serwer czytamodule.json, sprawdza właściciela karty modułu, semver i kolejkuje build obrazu Dockera. Draft o tej samej wersji jest nadpisywany (retry bez podbijania wersji); wersje opublikowane są niemutowalne.GET /developer/publish/:imageId— CLI odpytuje status builda.POST /developer/publish/:imageId/finalize— tylko przy--release: publikacja (draft → published); poprzednia opublikowana wersja przechodzi w deprecated. Ostrzeżenia serwera (warnings, np. brak wartości sekretu) CLI wypisuje jako⚠.
Autoryzacja: nagłówek Authorization: Bearer omm_... (token publikacji,
zarządzany w panelu developera lub przez omm login/omm logout).
Dependencies
Dependencies
| ID | Version |
|---|---|
| commander | ^12.1.0 |
| yazl | ^2.5.1 |