Orbito Orders managment

@orbito/omm (0.4.0)

Published 2026-10-07 10:28:09 +02:00 by wiktor

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

OrbitoModulesManager — CLI do pakowania i publikacji modułów Orbito na modules.orbito.pl

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 przez omm login).
  • OMM_TOKEN — token publikacji z env (ma priorytet nad configiem; do CI).
  • OMM_REGISTRY / --registry — adres API rejestru (domyślnie https://modules.orbito.pl/api).
  • OMM_SECRET_VALUE — wartość dla omm secrets set bez 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

  1. POST /dev/modules/link — core tworzy (lub aktualizuje) instancję z flagą dev: true i wydaje jednorazowy token rejestracji oraz adres RPC.
  2. CLI uruchamia node [--watch] <entry> z ORBITO_HOST, ORBITO_PORT (puste przy unix sockecie), ORBITO_TOKEN, ORBITO_INSTANCE_ID, ORBITO_COMPANY_ID, ORBITO_MODULE_CODE, ORBITO_MODULE_VERSION, ORBITO_DEBUG oraz zmiennymi z .env modułu (patrz niżej).
  3. Nadzorca odpytuje GET /dev/modules/ping co 3 s i porównuje bootId core. Zmiana bootId = 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.
  4. 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+C zatrzymuje moduł, ale nie odpina instancji — do tego służy omm dev unlink.
  5. Podbicie version w module.json i ponowny omm dev aktualizuje wersję instancji dev (core doręcza MODULE_ENABLED jak 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
  • list pokazuje sumę sekretów zadeklarowanych w ostatniej wersji i zapisanych, ze statusem ustawiony / brak wartości / niezadeklarowany — nigdy wartości.
  • set dział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 --release wypisze ostrzeżenie ⚠ dla każdego zadeklarowanego sekretu bez wartości.

Jak działa publikacja

  1. POST /developer/publish — upload ZIP-a; serwer czyta module.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.
  2. GET /developer/publish/:imageId — CLI odpytuje status builda.
  3. 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
Details
npm
2026-10-07 10:28:09 +02:00
9
UNLICENSED
23 KiB
Assets (1)
omm-0.4.0.tgz 23 KiB
Versions (15) View all
2.2.0 2026-10-27
2.1.3 2026-10-27
2.1.2 2026-10-25
2.1.1 2026-10-25
2.1.0 2026-10-16