omm — CLI do publikacji

omm (Orbito Modules Manager) to oficjalne narzędzie do pakowania i publikowania modułów w repozytorium modułów Orbito (modules.orbito.pl) — odpowiednik npm publish dla modułów. Pozwala też przetestować wersję roboczą modułu we własnej firmie w Orbito bez otwierania panelu.

Co robi za Ciebie:

• pakuje moduł zgodnie z regułami repozytorium (bez node_modules, bez sekretów w .env/.npmrc),
• waliduje module.json lokalnie, zanim cokolwiek wyśle,
• wysyła paczkę i kolejkuje build obrazu Dockera,
• śledzi status builda i pokazuje błąd, jeśli obraz się nie zbuduje,
• publikuje wersję w rejestrze jednym poleceniem (--release),
• testuje moduł w Twojej firmie: instaluje go, aktualizuje, pokazuje logi i problemy, wywołuje jego metody.

Instalacja

npm config set @orbito:registry https://git.kozminski.net.pl/api/packages/orbito/npm/   # raz na komputer
npm i -g @orbito/omm

Wymagany Node.js >= 18.13. Paczki @orbito/* (@orbito/omm, @orbito/api-lib) nie są na npmjs.org — leżą w firmowym rejestrze npm Orbito. Rejestr pozwala pobierać paczki anonimowo, więc token nie jest potrzebny, ale npm musi wiedzieć, skąd brać scope @orbito. Pierwsza komenda dopisuje do ~/.npmrc linię:

@orbito:registry=https://git.kozminski.net.pl/api/packages/orbito/npm/

Bez niej npm i -g @orbito/omm i npm install w module kończą się błędem 404. Sam omm da się zainstalować bez zapisywania konfiguracji, podając rejestr flagą (działa też w PowerShell na Windows):

npm i -g @orbito/omm --@orbito:registry=https://git.kozminski.net.pl/api/packages/orbito/npm/

Linię w ~/.npmrc zapisuje wtedy omm skill install — albo dopisz ją pierwszą komendą z bloku wyżej.

Jeśli npm i -g kończy się błędem EACCES (permission denied, np. na /usr/local/lib/node_modules), globalny katalog npm należy do roota — typowe dla Node.js z instalatora .pkg na macOS albo z pakietu systemowego na Linuksie. Są dwa wyjścia: uruchom z sudo tylko instalację (sudo npm i -g @orbito/omm --@orbito:registry=https://git.kozminski.net.pl/api/packages/orbito/npm/), a omm skill install już bez sudo, żeby skill trafił do Twojego katalogu domowego; albo przenieś globalny katalog npm do katalogu użytkownika według instrukcji npm (Node z nvm lub z Homebrew nie ma tego problemu).

Logowanie

Logujesz się kontem Orbito — tym samym co w panelu my.orbi.do. Repozytorium modułów nie ma własnych haseł. Model kont i namespace'ów opisuje Konto i namespace'y.

omm login                                  # e-mail i hasło: sesja Orbito Core + token publikacji w repozytorium
omm login --core http://localhost:3003 --registry http://localhost:3005   # inne serwery
omm login --token <jwt>                    # zamiast hasła: gotowy JWT rdzenia (loguje do obu)
omm login --token omm_abc...               # tylko repozytorium: gotowy token publikacji (CI)
omm whoami                                 # konto w repozytorium i Twoje namespace'y z rolą
omm whoami --core                          # konto w Orbito Core i firma robocza
omm logout                                 # unieważnia token publikacji, usuwa go i sesję rdzenia

Jedno omm login robi dwie rzeczy:

1. loguje do Orbito Core i zapisuje sesję (JWT ważny 48 h, odświeżany automatycznie),
2. tym samym JWT tworzy w repozytorium długożyciowy token publikacji omm-<nazwa komputera>.

Oba trafiają do ~/.config/omm/config.json dopiero wtedy, gdy oba kroki się udadzą; hasło nie jest nigdzie zapisywane. Firma robocza (omm company use) zostaje przy ponownym logowaniu na to samo konto.

• --core <url> i --registry <url> wybierają tylko adresy serwerów (domyślnie ostatnio używane, potem https://my.orbi.do/api i https://modules.orbito.pl/api). Samo --core bez adresu (składnia omm 1.x) oznacza domyślny rdzeń.
• --token omm_... loguje tylko do repozytorium. Komendy rdzenia potrzebują wtedy omm login albo OMM_CORE_TOKEN.
• omm logout unieważnia token publikacji w repozytorium i usuwa z konfiguracji token i sesję rdzenia. JWT rdzenia nie da się unieważnić — po prostu wygasa.

Tokenami publikacji zarządzasz też w panelu developera (Tokeny publikacji).

Namespace'y (omm namespace)

Moduł należy do namespace'u, nie do osoby: jego kod to <namespace>/<slug>, np. acme/hello. Każdy członek namespace'u może wszystko przy jego modułach; członkami zarządza tylko właściciel. Szczegóły: Konto i namespace'y.

omm namespace list                          # Twoje namespace'y z rolą (owner / member)
omm namespace create acme                   # a-z, 0-9, -, 3–30 znaków, unikalna nazwa
omm namespace members acme                  # właściciel, członkowie i oczekujące zaproszenia
omm namespace invite acme anna@acme.pl      # tylko właściciel
omm namespace remove acme anna@acme.pl      # tylko właściciel: usuwa członka albo anuluje zaproszenie

• invite od razu dodaje osobę, która logowała się już do repozytorium; w przeciwnym razie zapisuje zaproszenie, realizowane przy jej pierwszym logowaniu. Repozytorium nie wysyła maili.
• Właściciela nie można usunąć; namespace'u nie da się usunąć ani przekazać.
• Każda komenda przyjmuje -r, --registry <url>. Z --json list wypisuje listę, a pozostałe komendy szczegóły namespace'u: { id, name, role, owner, members: [{ id, email, name, addedAt }], invitations: [{ email, createdAt }], createdAt }.

Nowy moduł (omm init)

omm init "Hello"                                   # zakłada kartę modułu w Twoim namespace + szkielet w ./hello
omm init "Hello" --namespace acme                  # wybór namespace'u (potrzebny, gdy masz kilka)
omm init "Hello" --description "Wita ludzi" --dir moj-hello
omm init "Hello" --code acme/hello                 # karta już istnieje: tylko szkielet, bez wywołania repozytorium

<name> to wyświetlana nazwa karty modułu. Bez --code komenda zakłada kartę w namespace w repozytorium (wymaga omm login), a repozytorium nadaje modułowi kod <namespace>/<slug nazwy>. Namespace to --namespace, a bez tej flagi Twój jedyny namespace. Przy kilku namespace'ach omm init pyta w terminalu, a w skryptach i z --json kończy się błędem — podaj wtedy --namespace. Bez żadnego namespace'u komenda podpowiada omm namespace create <name>. Z --code karta musi już istnieć — omm nie łączy się wtedy z repozytorium.

Moduł powstaje z wbudowanego szablonu: module.json, package.json, index.js, pages/hello.yaml i .gitignore — jedna metoda, jedna strona OVE, kod modułu wpisany we wszystkie pliki. omm init nie uruchamia npm install; zrób to sam w nowym katalogu.

Pakowanie

omm pack --dry-run             # tylko wypisz listę plików, nic nie zapisuj
omm pack                       # zbuduj ZIP lokalnie (bez wysyłania)
omm pack -o /tmp/modul.zip     # własna ścieżka wynikowa
omm pack --include-npmrc       # dołącz .npmrc (uwaga: sekrety!; zbędne dla @orbito/*)

Bez -o archiwum zapisywane jest jako <namespace>-<nazwa>-<wersja>.zip.

Publikacja

omm publish                    # spakuj + wgraj DRAFT + poczekaj na build Dockera
omm publish --release          # jak wyżej + publikacja w rejestrze (draft → published)
omm publish --no-wait          # wgraj draft i nie czekaj na build
omm publish --changelog "..."  # z opisem zmian (release notes)
omm publish --dry-run          # spakuj i wypisz zawartość, nic nie wysyłaj

Domyślnie publish wysyła wersję roboczą (draft) — do testów na własnej firmie. Draft widzą tylko członkowie namespace'u modułu i firmy z dostępem do modułu (Moduły robocze i dostęp firm). Udostępnienie wszystkim firmom wymaga świadomego --release.

Jak to działa

1. CLI czyta i waliduje module.json, buduje ZIP.
2. Upload paczki — serwer sprawdza, czy token należy do członka namespace'u modułu, sprawdza semver i kolejkuje build obrazu Dockera. Draft o tej samej wersji jest nadpisywany; wersje opublikowane są niemutowalne.
3. CLI odpytuje status builda (co 3 s) i wypisuje wynik.
4. Przy --release — publikacja wersji; poprzednia opublikowana wersja przechodzi w deprecated. Dla każdego zadeklarowanego w module.json sekretu bez ustawionej wartości CLI wypisuje ostrzeżenie ⚠ — publikacja nie jest blokowana, ale moduł nie dostanie tej zmiennej, dopóki nie ustawisz jej przez omm secrets set.

Testowanie na własnej firmie

Zanim udostępnisz moduł firmom, przetestuj go jako wersję roboczą (draft) zainstalowaną w Twojej własnej firmie w Orbito. Moduł działa wtedy w kontenerze dokładnie tak jak po publikacji, a omm pozwala go zainstalować, zaktualizować, czytać jego logi i problemy oraz wywoływać jego metody — bez otwierania panelu.

Logowanie do Orbito Core

Sesję rdzenia zapisuje to samo omm login co token publikacji (patrz Logowanie). Domyślny adres rdzenia to ostatnio używany, a za pierwszym razem https://my.orbi.do/api; inny wskażesz przez omm login --core <url>. Sesja jest odświeżana automatycznie przed komendą rdzenia, gdy zostaje jej mniej niż 24 h; wygasła sesja kończy komendę błędem z prośbą o ponowne omm login.

Firma robocza

omm company list          # Twoje firmy z identyfikatorami (* = firma robocza)
omm company use <id>      # ustawia firmę roboczą (id albo numer z listy)
omm company use           # wybór interaktywny

Komendy z kolejnej sekcji działają na firmie roboczej. Jako członek namespace'u modułu zainstalujesz jego wersję roboczą w każdej firmie, do której należysz. Pierwsza instalacja albo aktualizacja draftu nadaje firmie trwały dostęp do modułu: moduł działa w niej dalej po restarcie kontenera i widzą go pozostali użytkownicy firmy. Inną firmę dopiszesz ręcznie w panelu developera — Moduły robocze i dostęp firm.

Gdy rdzeń nie znajduje wersji (HTTP 404), omm install i omm update dodają podpowiedź (hint w --json): sprawdź przez omm whoami, czy jesteś zalogowany jako członek namespace'u modułu.

Pętla testowa

omm publish                                  # draft + build obrazu Dockera
omm install                                  # instaluje wersję z module.json (z zależnościami)
omm instances                                # instancje modułu w firmie
omm logs                                     # dzisiejsze logi modułu
omm logs --container                         # stdout/stderr kontenera
omm problems --status waiting                # problemy zgłoszone przez moduł
omm call getOrders --params '{"limit": 5}'   # wywołanie metody modułu
# … poprawka w kodzie …
omm publish                                  # nadpisuje draft tej samej wersji
omm update                                   # ta sama wersja: przeładowanie z nowym obrazem
# … i tak do skutku, na koniec:
omm publish --release

Podczas pracy nad draftem nie musisz podbijać wersji: omm publish nadpisuje draft, a omm update tej samej wersji przeładowuje instancję. Wersję podbijasz dopiero przed publikacją (--release).

Wspólne flagi komend rdzenia:

Wyjście dla skryptów i agentów AI (--json)

Flaga --json (w dowolnym miejscu linii komend, działa dla każdej komendy omm) wypisuje na stdout wyłącznie wynik jako JSON, bez komunikatów o postępie. Błąd trafia na stderr jako {"error": "...", "status": 404} (status to kod HTTP albo null, plus code/details/validation, gdy zwróci je serwer, oraz hint z podpowiedzią omm, co zrobić dalej), a kod wyjścia to 1. Na wejście ze stdin czekają tylko komendy interaktywne: omm login bez --token, omm company use bez argumentu, omm init bez --namespace na koncie z kilkoma namespace'ami (tylko w terminalu) i omm secrets set bez OMM_SECRET_VALUE — oraz omm automation create/update -f -, które czytają graf ze stdin.

omm instances --json
omm call ping --json

Automatyzacje firmy (omm automation)

Automatyzacje firmy roboczej bez edytora w panelu: przegląd, graf zapisany jako plik JSON, włączanie i diagnoza biegów. Przydaje się do testu wyzwalaczy i akcji własnego modułu (draft zainstalowany w firmie) oraz agentom AI, które składają automatyzacje dla użytkownika. Opis dla agentów z formatem grafu, kodami błędów i statusami: Company automations.

omm automation elements --kind action --query etykieta   # wyzwalacze i akcje dostępne w firmie
omm automation element set_var         # pełna definicja elementu jako JSON
omm automation create -f graf.json     # nowa automatyzacja, zawsze WYŁĄCZONA
omm automation get <id>                # graf i walidacja
omm automation enable <id>             # włączenie to osobny krok
omm automation runs --automation <id> --status errored
omm automation run <runId>             # kroki biegu

Plik grafu (create wymaga całości, update dowolnego podzbioru pól):

{
    "name": "Etykieta dla nowych zamówień",
    "desc": "Opis opcjonalny",
    "triggers": [{ "type": "<typ wyzwalacza>", "params": {} }],
    "actions": {
        "a1": {
            "type": "<moduleCode>:<kod akcji>",
            "params": { "__instanceId": "<id instancji>" },
            "branches": { "next": null }
        }
    },
    "startActionId": "a1"
}

• Szkic → włączenie. create zawsze zapisuje automatyzację wyłączoną, a update nigdy nie zmienia isEnabled; plik z polem isEnabled jest odrzucany. Włącza się ją jawnie omm automation enable <id> — rdzeń sprawdza wtedy dostępność elementów i parametry akcji.
• Elementy modułów wymagają params.__instanceId — id instancji, która je wykonuje (omm instances -m <moduleCode>). branches mapuje wyjścia akcji (next albo np. true/false warunku) na id następnej akcji lub null.
• create i update wysyłają graf do ścisłej walidacji: rdzeń sprawdza cały graf (elementy, parametry, gałęzie, cykle, klucze zdarzeń, zmienne szablonów) i odrzuca błędny kodem 422 bez zapisu. Błędy są wypisywane po jednym w linii jako ścieżka: komunikat (KOD), a z --json trafiają do pola validation błędu na stderr:

{"error":"Automation graph is invalid","status":422,"validation":{"errors":[{"path":"actions.wait.params.value","code":"INVALID_TYPE","message":"expected a number"}]}}

• Wynik omm automation get <id> --json po usunięciu isEnabled można edytować i odesłać przez omm automation update <id> -f — pola tylko do odczytu (_id, validation, generatedName …) omm pomija.

Sekrety modułu (omm secrets)

Klucze aplikacji modułu (np. client ID/secret marketplace'u) trzyma repozytorium modułów — zaszyfrowane, globalnie per kod modułu (nie per wersja ani per firma). Moduł deklaruje je w polu secrets w module.json, a wartości ustawiasz komendami omm secrets:

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           # usuwa wartość

• set działa także dla nazwy jeszcze niezadeklarowanej w module.json — wartości możesz ustawić przed pierwszą publikacją wersji, która ich używa.
• Nowa wartość trafia do kontenerów modułu przy ich najbliższym starcie — bez publikacji nowej wersji modułu.
• Wartości nie da się odczytać z powrotem ani przez omm, ani przez panel developera.

Repozytorium kodu modułu (omm repo)

Karta modułu w repozytorium modułów może przechowywać link do repozytorium git z kodem modułu — żeby wszyscy członkowie namespace'u wiedzieli, gdzie jest aktualny kod. Link widzą tylko członkowie namespace'u modułu: w panelu developera (szczegóły modułu, pole „Repozytorium kodu" w edycji modułu) i w omm. Nie trafia do module.json, paczki ZIP ani na stronę sklepu.

omm repo                                          # pokazuje link; kod modułu z ./module.json
omm repo --module core/allegro                    # albo wskazany
omm repo set                                      # bierze git remote get-url origin z bieżącego katalogu
omm repo set git@git.example.com:acme/hello.git   # albo podany adres
omm repo unset                                    # usuwa link

• Dozwolone formaty: https://… / http://…, ssh://… oraz git@host:org/repo.git; maksymalnie 500 znaków.
• Adres nie może zawierać hasła ani tokenu — taki zostanie odrzucony.
• Z --json każda z komend zwraca { moduleCode, repositoryUrl }.

Business solutions (omm solution)

Zestawy modułów z szablonami automatyzacji, instalowane w firmie jednym kliknięciem. Publikuje je tylko namespace core (Orbito); inne konta dostają 403. Format katalogu zestawu (solution.yaml, README.md, okładka, pliki automatyzacji) i reguły walidacji: Business solutions.

Skill dla agentów AI (omm skill install)

omm skill install                    # skill dla agentów, których katalog istnieje (~/.claude, ~/.codex, ~/.config/opencode)
omm skill install --project          # do .claude/, .codex/ i .opencode/ w bieżącym katalogu
omm skill install --agent codex      # tylko wskazany agent (claude, codex, opencode); flaga powtarzalna

Pobiera skill orbito-modules (SKILL.md z https://orbito.pl/docs/skill/SKILL.md) i zapisuje go w skills/orbito-modules/SKILL.md katalogu każdego wybranego agenta: Claude Code, Codex, OpenCode. Gdy żaden katalog agenta nie istnieje, instaluje skill dla Claude Code. Przy okazji zapisuje w konfiguracji npm linię scope @orbito (patrz Instalacja). Działa na Windows, macOS i Linux. Ponowne uruchomienie aktualizuje skill — to polecenie podaje też powiadomienie o nieaktualnym skillu (dla kopii w projekcie: omm skill install --project).

Na Linux i macOS to samo robi jedna linia: curl -fsSL https://orbito.pl/docs/skill/install.sh | sh (z sh -s -- --project dla projektu). Skrypt jest cienką nakładką: ustawia scope @orbito w npm, instaluje @orbito/omm i uruchamia omm skill install z tymi samymi opcjami. Gdy globalny katalog npm nie jest zapisywalny, nie uruchamia sudo, tylko wypisuje oba wyjścia opisane w Instalacji.

Powiadomienia o aktualizacjach i omm doctor

Raz na dobę omm sprawdza w tle, czy jest nowsza wersja omm, SDK @orbito/api-lib (porównuje z zależnością w package.json modułu z bieżącego katalogu) i skilla dla agentów AI. Sprawdzenie nie opóźnia komendy, a błędy sieci są pomijane. Gdy coś jest nieaktualne, po wyniku komendy na stderr pojawia się powiadomienie z poleceniem aktualizacji i linkiem do listy zmian: w trybie tekstowym linie zaczynające się od !, z --json jedna linia {"notices": [...]} — stdout zostaje czystym wynikiem komendy.

Niezależnie od sieci (także offline i przy OMM_NO_UPDATE_CHECK=1) każda komenda korzystająca z rdzenia wypisuje powiadomienie core, gdy adres rdzenia to dawny https://v2.orbito.pl/api: ten host tylko przekierowuje na https://my.orbi.do/api i gubi przy tym sesję, więc trzeba zalogować się ponownie przez omm login --core https://my.orbi.do/api (omm doctor zgłasza to jako warn w kontroli core-login).

omm doctor                     # wymusza sprawdzenie i wypisuje tabelę kontroli
omm doctor --json              # to samo jako JSON: { "checks": [{ name, status: ok|warn|fail, message, fix }], "notices": [...] }
OMM_NO_UPDATE_CHECK=1 omm ...  # wyłącza sprawdzanie aktualizacji

omm doctor sprawdza Node.js, wersję omm, linię scope @orbito w konfiguracji npm, logowanie do repozytorium (ostrzeżenie, gdy konto nie należy do żadnego namespace'u) i do Orbito Core, firmę roboczą, moduł w bieżącym katalogu (manifest, SDK względem najnowszego) i zainstalowany skill. Kończy się kodem 1 tylko wtedy, gdy któraś kontrola ma status fail.

Konfiguracja

Publikacja z CI

W pipeline nie loguj się hasłem — omm login nie jest potrzebne. Komendy repozytorium (omm publish, omm secrets, omm repo) biorą token publikacji ze zmiennej środowiskowej:

export OMM_TOKEN=omm_...
export OMM_NO_UPDATE_CHECK=1
omm publish --release --changelog "$CI_COMMIT_MESSAGE"

Token najlepiej wygenerować w panelu developera, osobno dla każdego pipeline'u — wtedy unieważnisz go niezależnie od innych (Tokeny publikacji). Można też użyć tokenu, który omm login zapisał lokalnie w ~/.config/omm/config.json (registries["<rejestr>"].token), ale omm logout na tym komputerze go unieważni. Token należy do Twojego konta i działa we wszystkich Twoich namespace'ach.

Komendy rdzenia (omm install, omm logs, omm call, omm automation …) potrzebują w CI OMM_CORE_TOKEN=<JWT rdzenia> (ważny 48 h, nieodświeżany) i OMM_COMPANY=<id firmy>.