Impacchettare e pubblicare

Una volta che il tuo plugin sandbox funziona, puoi pubblicarlo sul marketplace EmDash in modo che altri siti possano installarlo con un clic dalla dashboard amministrativa. Il flusso di pubblicazione è solo per sandbox: i plugin nativi vengono distribuiti tramite npm e non sono impacchettati in tarball del marketplace.

Prerequisiti

Prima di pubblicare, assicurati che il tuo plugin:

• Abbia un package.json con sia un’esportazione "." (il descrittore) che un’esportazione "./sandbox" (l’ingresso runtime).
• Usi format: "standard" sul descrittore.
• Abbia un id unico e una version semver valida.
• Dichiari accuratamente le sue capabilities e allowedHosts sul descrittore.

Formato del pacchetto

I plugin pubblicati sono distribuiti come tarball .tar.gz contenenti:

manifest.json viene generato automaticamente. Contiene l’id del plugin, versione, capabilities, host consentiti, nomi degli hook, nomi delle route e configurazione admin — ma nessun codice eseguibile.

Costruire un pacchetto

cd packages/plugins/my-plugin
emdash plugin bundle

Questo farà:

Risoluzione dei punti di ingresso

Il comando bundle trova il tuo codice attraverso le esportazioni di package.json:

{
	"exports": {
		".": { "import": "./dist/index.mjs" },
		"./sandbox": { "import": "./dist/sandbox-entry.mjs" },
		"./admin": { "import": "./dist/admin.mjs" }
	}
}

Se "./sandbox" manca, il comando cerca src/sandbox-entry.ts come fallback. Il bundler mappa automaticamente i percorsi dist verso la sorgente — se la tua esportazione "." punta a ./dist/index.mjs, troverà e costruirà src/index.ts.

Opzioni

emdash plugin bundle [--dir <path>] [--outDir <path>]

Validazione

Il comando bundle controlla:

• Limite di dimensione — il pacchetto totale deve essere sotto 5 MB.
• Nessun built-in di Node.js in backend.js — il codice sandbox non può importare fs, path, child_process, ecc. Sostituiscili con Web API o sposta la logica in un plugin nativo.
• Whitelist delle capabilities — le capabilities dichiarate devono essere nell’insieme noto (gli errori di battitura falliscono).
• Nomi di capability deprecati attivano avvisi qui e un fallimento duro al momento della pubblicazione.
• network:request senza allowedHosts attiva un avviso (considera network:request:unrestricted se gli host sono configurati dall’operatore a runtime, o elenca gli host esplicitamente).
• Dimensioni dell’icona — icon.png dovrebbe essere 256×256 (avvisa se errato; lo include comunque).
• Limiti degli screenshot — max 5 screenshot, max 1920×1080.

Pubblicazione

emdash plugin publish

Questo trova il .tar.gz più recente in dist/ e lo carica. Per essere esplicito sul tarball o per costruire prima di pubblicare:

# Percorso tarball esplicito
emdash plugin publish --tarball dist/my-plugin-1.0.0.tar.gz

# Costruisci prima, poi pubblica
emdash plugin publish --build

Autenticazione

La prima volta che pubblichi, la CLI ti autentica tramite GitHub:

Il token dura 30 giorni. Dopo la scadenza, ti verrà chiesto di riautenticarti alla prossima pubblicazione.

Puoi gestire l’autenticazione separatamente:

emdash plugin login    # accedi senza pubblicare
emdash plugin logout   # cancella il token memorizzato

Registrazione iniziale

Se il tuo id del plugin non è ancora noto al marketplace, emdash plugin publish lo registra automaticamente prima di caricare la prima versione.

Requisiti di versione

Ogni versione pubblicata deve avere una semver più alta dell’ultima. Non puoi sovrascrivere o ripubblicare una versione esistente — aumenta la versione sia in package.json che nel descrittore prima di pubblicare nuovamente.

Audit di sicurezza

Ogni versione pubblicata passa attraverso un audit di sicurezza automatizzato. L’audit scansiona backend.js e admin.js per:

• Pattern di esfiltrazione dati
• Raccolta di credenziali tramite impostazioni
• Codice offuscato
• Abuso di risorse (crypto mining, ecc.)
• Attività di rete sospetta

L’audit produce un verdetto di pass, warn o fail, visualizzato sulla lista del marketplace del plugin. A seconda del livello di applicazione del marketplace, un verdetto di fail può bloccare completamente la pubblicazione.

Opzioni

emdash plugin publish [--tarball <path>] [--build] [--dir <path>] [--registry <url>]

Flusso completo

Ciclo di pubblicazione tipico:

# 1. Fai le tue modifiche
# 2. Aumenta la versione in src/index.ts e package.json
# 3. Impacchetta e pubblica
emdash plugin publish --build

Se vuoi ispezionare il pacchetto prima:

emdash plugin bundle
tar tzf dist/my-plugin-1.1.0.tar.gz
emdash plugin publish