Developer CLI

@evoxapp/plugin-cli paketinin binary adı evox-plugindır.

Kurulum

Node.js 20+ gerekir. Kurulum yapmadan npx ile kullanabilirsiniz:

npx @evoxapp/plugin-cli init my-plugin

veya global kurulum:

npm install -g @evoxapp/plugin-cli
evox-plugin init my-plugin

Dil

CLI mesajları ve init şablonları (README, yorumlar, aksiyon adları, tuş başlıkları) İngilizce veya Türkçe üretilir. Dil şu sırayla seçilir: --lang en|tr > EVOX_PLUGIN_LANG > LC_ALL > LC_MESSAGES > LANG > sistem locale’i (Türkçe ise tr) > en. C ve POSIX locale’i dil seçimi sayılmaz. Geçersiz bir --lang değeri PLUGIN_CLI_LANG_INVALID döner; geçersiz bir EVOX_PLUGIN_LANG değeri yok sayılır. Hata kodları ve JSON çıktı alanlarının adları dile göre değişmez. Şablon değerleri seçilen dili izler: örneğin yazar adı --lang tr ile Yerel Geliştirici, --lang en ile Local Developer olur. Bu sayfadaki örnekler Türkçe şablonu gösterir.

Komutlar

# init: proje iskeleti (iki hedef)
evox-plugin init ./my-plugin --name "Plugin Adı"                      # sandbox-js (public T2 hedefi, varsayılan) — evox-plugin.json
evox-plugin init ./my-plugin --runtime trusted-node --name "Plugin"   # T1 yerel gelistirme — manifest.json + runtime.mjs

# build/run/sandbox-test yalnız sandbox-js (T2) projeleri içindir; evox-plugin.json gerektirir.
evox-plugin build ./my-plugin
evox-plugin run ./my-plugin
evox-plugin sandbox-test ./my-plugin

# validate/pack/publish-check iki hedefte de çalışır (T1 için aşağıdaki bölüme bakın).
evox-plugin validate ./my-plugin
evox-plugin pack ./my-plugin
evox-plugin publish-check ./my-plugin

--plugin-id <uuid> opsiyoneldir; verilmezse otomatik üretilir ve çıktıda gösterilir.

T1 (trusted-node) mı, T2 (sandbox-js) mi? İki init hedefinin akışı farklıdır:

T1 · --runtime trusted-node → manifest.json + runtime.mjs üretir. Doğrudan evoX Eklentiler → Geliştirici penceresinden yüklenir; yerel geliştirme için CLI komutu gerekmez. build/run/sandbox-test bu projede çalışmaz. validate, publish-check ve pack projeyi Market incelemesi için paketler (aşağıdaki T1 projesini Market incelemesine hazırlama bölümü). Adımlar: Hızlı başlangıç.
T2 · varsayılan (sandbox-js) → evox-plugin.json config’i üretir. validate → sandbox-test → build → pack → publish-check pipeline’ı bu projeler içindir (public upload açılınca yayın hedefi).

Komut	Hedef	Sonuç
`init`	—	Başlangıç projesi oluşturur (varsayılan `sandbox-js`/T2; `--runtime trusted-node` ile T1)
`validate`	T2, T1	T2’de manifest, path ve dependency inventory kontrolü; T1’de `manifest.json` kontrolü
`build`	T2	esbuild ile browser-compatible tek ESM bundle üretir
`run`	T2	Host-validation preview çalıştırır
`sandbox-test`	T2	Sandbox uyum kontrolü: kaynakta Node/DOM/doğrudan ağ erişimini tarar, browser bundle’ı doğrular, ihlalde non-zero çıkar
`pack`	T2, T1	`evox-archive-v1` policy ile `.evoxpack` oluşturur
`publish-check`	T2, T1	Local parity kontrolü yapar; paket yazmaz

T1 (trusted-node) projesi yerel geliştirmede bu komutları kullanmaz; kod değiştirdikçe Geliştirici penceresinden yeniden yükleyerek geliştirir.

run sandbox değildir. Gerçek T2 sınırı host-owned Electron sandboxında doğrulanır.

sandbox-test statik bir uyum kontrolüdür: sandbox-js kaynağınızı Node/DOM/doğrudan ağ (fetch/WebSocket/XHR) erişimine karşı tarar ve browser bundle’ını doğrular. Yayına göndermeden önce çalıştırın; herhangi bir ihlal fail-closed non-zero çıkış verir (CI/pre-submit için uygun). Gerçek T2 güvenlik sınırı host-owned Electron Chromium Worker’dır; sandbox-test onu tamamlar, yerine geçmez.

`evox-plugin.json` (sandbox-js/T2 config)

sandbox-js projesinin kök config dosyası. init üretir; pipeline komutları (validate/build/pack/publish-check) bunu okur. (T1 trusted-node projesinde bu dosya yoktur; T1 doğrudan manifest.json + runtime.mjs ile çalışır.)

Alan	Açıklama
`schemaVersion`	Config şema sürümü (`1`)
`sourceEntry`	Plugin kaynak giriş dosyası (ör. `src/plugin.ts`); `build` bunu tek ESM bundle’a derler
`package.name` / `package.description`	Paket meta bilgisi
`package.author.id` / `package.author.name`	Geliştirici kimliği (yerelde `local-developer` / `Yerel Geliştirici`)
`plugin`	Host manifest’i (kimlik, runtime `sandbox-js`, izinler, aksiyonlar) — alanlar için Manifest

dependencies.json ayrı tutulur ve validate/pack tarafından envanterlenir. publish-check moderation, production scanner, signing veya revocation yerine geçmez. Public executable upload hazır olmadığı sürece PLUGIN_UPLOAD_NOT_READY korunur.

T1 projesini Market incelemesine hazırlama

T1 (trusted-node) eklenti Market’e, minify edilmemiş tek bir ESM dosyası olarak girer; inceleme kodu bu dosyada okur. Önce:

manifest.json’a platforms alanını, eklentinin çalıştırdığı her program için declaredCommands ve dokunduğu her sistem yolu için declaredPaths beyanlarını ekleyin (bkz. Manifest).
Proje klasöründe npm install çalıştırın. @evoxapp/plugin-sdk projeye kurulu olmalı ve package-lock.json bulunmalıdır; bağımlılıkların integrity değeri buradan okunur.

evox-plugin validate ./my-plugin
evox-plugin publish-check ./my-plugin
evox-plugin pack ./my-plugin

publish-check manifest.json’daki runtime girişini bağımlılıklarıyla birlikte tek dosyaya derler, dosyayı beyanlarla karşılaştırır ve bulguları yazar. Paket üretmez.
pack aynı kontrollerden geçen projeyi .evoxpack yapar. Paket üç dosya taşır: plugin/manifest.json, package-lock.json’dan üretilen plugin/dependencies.json ve plugin/runtime/plugin.mjs.

Hata bulgusu varsa paket üretilmez:

Kod	Neden
`PLUGIN_CLI_TRUSTED_PLATFORMS_REQUIRED`	`platforms` alanı yok
`PLUGIN_CLI_NATIVE_MODULE_FORBIDDEN`	`.node` dosyası, `binding.gyp` ya da `process.dlopen`
`PLUGIN_CLI_INSTALL_SCRIPT_FORBIDDEN`	Bundle’a giren bir bağımlılığın `preinstall`/`install`/`postinstall` betiği var
`PLUGIN_CLI_DYNAMIC_CODE_FORBIDDEN`	`eval`, `new Function` ya da `vm` modülü
`PLUGIN_CLI_DYNAMIC_REQUIRE_FORBIDDEN`	Node yerleşik modülü dışında bir şeyi yükleyen `require`
`PLUGIN_CLI_DYNAMIC_IMPORT_FORBIDDEN`	Node yerleşik modülü dışında bir şeyi yükleyen `import()`
`PLUGIN_CLI_CHILD_PROCESS_UNDECLARED`	`child_process` kullanılıyor ama `declaredCommands` yok
`PLUGIN_CLI_COMMAND_UNDECLARED`	Bundle `declaredCommands` dışında bir program çalıştırıyor
`PLUGIN_CLI_LOCKFILE_REQUIRED`	Bağımlılık var ama `package-lock.json` yok
`PLUGIN_CLI_DEPENDENCY_INTEGRITY_MISSING`	`package-lock.json` bir bağımlılığın sha512 integrity değerini taşımıyor
`PLUGIN_CLI_ANALYSIS_LIMIT_EXCEEDED`	Bundle analiz sınırını aşıyor: 16 MB’tan büyük ya da çok fazla `child_process` takma adı, çağrısı veya sistem yolu taşıyor

Uyarılar paketi durdurmaz ama çıktıda warnings altında listelenir: komut adı çalışma anında kurulan çağrı (PLUGIN_CLI_COMMAND_UNRESOLVED), kabuk üzerinden çalıştırma (PLUGIN_CLI_SHELL_EXECUTION), bundle’da bulunmayan beyanlı komut (PLUGIN_CLI_COMMAND_UNUSED), declaredPaths dışındaki sistem yolu (PLUGIN_CLI_PATH_UNDECLARED), child_process.fork (PLUGIN_CLI_FORK_USED) ve worker_threads (PLUGIN_CLI_WORKER_THREADS_USED).

Bu kontroller yalnız yardımcıdır; güvenlik kanıtı değildir. Paketlenen eklenti yine sandbox değildir ve kullanıcının yetkileriyle çalışır. T1 Market yüklemesi henüz kapalıdır: publish-check publishable: false ve TRUSTED_PLUGIN_UPLOAD_NOT_READY döner.

Başlangıç

Temel kavramlar

Örnekler ve dağıtım

Kurulum

Dil

Komutlar

`evox-plugin.json` (sandbox-js/T2 config)

T1 projesini Market incelemesine hazırlama

​Kurulum

​Dil

​Komutlar

​evox-plugin.json (sandbox-js/T2 config)

​T1 projesini Market incelemesine hazırlama

Kurulum

Dil

Komutlar

`evox-plugin.json` (sandbox-js/T2 config)

T1 projesini Market incelemesine hazırlama