Narzędzia i diagnostyka

CLI @lomi-dev/plugin-cli udostępnia cztery komendy: check, build, package i doctor. Uruchamiaj je w katalogu projektu pluginu, obok package.json. Wersja opisana tutaj to 0.1.0-alpha.2, korzystająca z SDK 1.1.0-alpha.1.

Polecenia

Skrypt szablonu	Bezpośrednie wywołanie	Wynik
pnpm check	pnpm exec lomi-plugin check	TypeScript, manifest, wejściowe zasoby; bez analizy bundle
pnpm build	pnpm exec lomi-plugin build	Kontrole wejścia, build, walidacja kompletnego package/
pnpm package	pnpm exec lomi-plugin package	Build i zweryfikowane artefakty ZIP, SHA-256, JSON
pnpm run doctor	pnpm exec lomi-plugin doctor	Raport środowiska i dostępnych metadanych aplikacji

Dozwolone flagi to --json, --help / -h, --version / -v oraz --app <path> tylko dla doctor. CLI nie ma argumentu katalogu projektu, flagi --watch, dev ani publish. Najpierw przejdź do projektu przez cd.

Konfiguracja buildu

Plik lomi-plugin.config.mjs jest opcjonalny. To moduł Node z eksportem domyślnym:

import { defineConfig } from '@lomi-dev/plugin-cli';

export default defineConfig({
  entry: 'src/index.tsx',
  manifest: 'plugin.json',
  assets: ['view.css', 'LICENSE'],
});

Pole	Domyślnie	Znaczenie
entry	src/index.tsx	Źródło TypeScript/TSX lub JavaScript do zbudowania; używane, gdy manifest ma entry
manifest	plugin.json	Manifest wejściowy; do wyniku trafia jako plugin.json
assets	[]	Lista unikalnych, istniejących plików lub katalogów, kopiowanych z zachowaniem ścieżek

Nie ma globów ani innych pól konfiguracji. CLI zapisuje wynik do package/. defineConfig() pomaga z typami; właściwą walidację wykonują polecenia CLI. Plik konfiguracyjny wykonuje się w Node, więc nie jest samym plikiem danych.

Wszystkie pliki z stylesheets muszą znaleźć się na liście assets, bezpośrednio albo w kopiowanym katalogu. Do motywu dodaj cały katalog z theme.jsonc i zasobami. CLI wymaga motywów v2 w JSONC, nawet jeśli sam importer Lomi obsługuje również starszy format.

Nie kopiuj src, tests, node_modules, .git, .github, .env, plików .ts, .tsx ani ręcznie dodawanych .map. Zasoby nie mogą kolidować z generowanym plugin.json ani dist/. Mapy źródeł utworzone przez build są dozwolone.

Źródło a wynik

entry konfiguracji wskazuje źródło, a entry manifestu wskazuje wynik. Przykładowo:

lomi-plugin.config.mjs → entry: src/main.tsx
plugin.json           → entry: dist/plugin.mjs
package/              → dist/plugin.mjs

Aktualny build helper dobiera nazwę i rozszerzenie pliku wynikowego z manifestu. Nie wskazuj w nim .tsx. Własne biblioteki muszą działać w przeglądarce; zależności npm zostają dołączone do buildu, a React i SDK korzystają z instancji Lomi.

Lokalne archiwa przed publikacją npm

Ta ścieżka używa lokalnych źródeł, więc nie wymaga opublikowanych paczek Lomi. W jednym katalogu umieść plugin-sdk, plugin-tools i create-lomi-plugin z odpowiadającymi sobie wersjami. Zacznij w ich katalogu nadrzędnym:

mkdir plugin-archives
pnpm --dir plugin-sdk install --frozen-lockfile
pnpm --dir plugin-sdk build
pnpm --dir plugin-sdk pack --pack-destination ../plugin-archives
pnpm --dir plugin-tools/packages/cli pack --pack-destination ../../../plugin-archives
node create-lomi-plugin/index.mjs my-plugin --id example.workspace-info --name "Workspace info" --template panel
cd my-plugin
pnpm add -D --save-exact --ignore-scripts @lomi-dev/plugin-sdk@file:../plugin-archives/lomi-dev-plugin-sdk-1.1.0-alpha.1.tgz @lomi-dev/plugin-cli@file:../plugin-archives/lomi-dev-plugin-cli-0.1.0-alpha.2.tgz
pnpm check
pnpm run doctor
pnpm package

pnpm add instaluje zależności projektu i zastępuje przypięcia SDK/CLI odwołaniami file: do archiwów. Zachowaj te archiwa oraz lockfile, jeśli chcesz odtworzyć środowisko. Pozostałe zależności wymagają dostępu do rejestru lub wcześniejszej pamięci podręcznej. Gotowy package/ nie potrzebuje już źródeł ani node_modules.

To konfiguracja pracy lokalnej. Po opublikowaniu zgodnego zestawu przejdź na dokładne wersje npm i odśwież lockfile; nie wpisuj ścieżek do lokalnych repozytoriów w projekcie przeznaczonym dla innych autorów.

Doctor

pnpm exec lomi-plugin doctor --json --app /Applications/Lomi.app

Na Windows lub Linuksie przekaż rzeczywistą ścieżkę zainstalowanej aplikacji. Bez --app doctor próbuje znaleźć /Applications/Lomi.app tylko na macOS. Nie uruchamia ani nie naprawia aplikacji. Na macOS może odczytać wersję z Info.plist; na innych platformach wykrycie pliku nie oznacza potwierdzenia zgodności.

Sprawdza Node, SDK, TypeScript, wersje React/React DOM i to, czy projekt oraz SDK rozwiązują tę samą kopię React. Brak React w projekcie zawierającym tylko motyw jest ostrzeżeniem. Ostrzeżenia mogą wystąpić przy kodzie zakończenia 0; HOST_UNVERIFIED nie potwierdza działania pluginu w desktopie.

JSON i kody zakończenia

pnpm exec lomi-plugin check --json

Sukces ma postać { schemaVersion: 1, command, ok: true, result }. Błędy wykonania używają { schemaVersion: 1, command, ok: false, diagnostics }. Każda diagnoza zawiera code, message, file, hint. Wynik doctor przechowuje kontrole w result.checks, każdą ze statusem ok, warning lub error.

Kod procesu	Znaczenie
0	Polecenie zakończone poprawnie; przejrzyj również ostrzeżenia doctor
1	Błąd projektu, wykonania lub kontroli doctor
2	Niepoprawne argumenty CLI

Typowe komunikaty

Kod	Co zrobić
CLI_ARGUMENT	Sprawdź komendę i flagi przez --help
CLI_INTERRUPTED	Polecenie przerwano; sprawdź ostatni poprawny wynik przed ponowieniem
SDK_VERSION	Zainstaluj zgodną paczkę SDK 1.1.0-alpha.1, z npm lub lokalnego archiwum
PLUGIN_CONFIG	Usuń nieobsługiwane pola; sprawdź eksport domyślny i unikalność assets
PLUGIN_MANIFEST	Popraw JSON, pola, przestrzenie nazw i odwołania między deklaracjami
PLUGIN_ENTRY	Sprawdź istnienie źródła wskazanego w konfiguracji
PLUGIN_TYPES	Popraw błędy TypeScript w raporcie
PLUGIN_ASSET	Dołącz brakujący zasób, usuń dowiązanie lub plik niedozwolony w paczce
PLUGIN_THEME	Sprawdź theme.jsonc, version: 2, nazwę i wygląd
PLUGIN_BUILD	Sprawdź importy Node, prywatne ścieżki, niejawne importy dynamiczne i kompletność wyniku
PLUGIN_PACKAGE	Upewnij się, że artifacts/ jest zwykłym katalogiem
PLUGIN_RELEASE_EXISTS	Zwiększ wersję w plugin.json albo świadomie przenieś poprzednie artefakty
NODE_VERSION	Użyj Node 22.14+
DEPENDENCY_VERSION, DEPENDENCY_MISSING	Dopasuj lub doinstaluj wskazaną zależność
REACT_DUPLICATE	Ujednolić React i React DOM do 19.2.8, następnie ponów instalację
HOST_MISSING	Sprawdź --app; bez aplikacji nadal możesz budować
HOST_TOO_OLD, HOST_VERSION	Sprawdź aplikację względem bazowej wersji 0.4.0 i jej runtime
HOST_UNVERIFIED	Wykonaj ręczną kwalifikację desktopową w Lomi
CLI_FAILURE	Odczytaj message i file; ogólny kod może oznaczać np. błąd systemu plików

CI i przerwany build

Dołączony workflow wykonuje instalację z lockfile, check i package, a następnie zachowuje artifacts/. Lockfile musi być w repozytorium. Przy lokalnych paczkach file: zapewnij je w CI albo przejdź na opublikowane wersje. ZIP z udanego CI nadal wymaga kwalifikacji desktopowej.

Zwykły błąd buildu zachowuje ostatni poprawny pakiet i sprząta własne pliki tymczasowe. Po awarii procesu sprawdź, czy inny build nie działa. Dopiero wtedy obejrzyj package.lomi-lock i .lomi-build-*; katalog z końcówką -previous może zawierać poprzedni wynik. Nie usuwaj blokady aktywnego procesu ani jedynej kopii poprawnego pakietu.