Manifest e metadata plugin

XIQUIL separa il manifest sorgente del developer dal manifest runtime distribuito agli utenti.

Il pacchetto caricato sull’Hub contiene il codice del plugin e, preferibilmente, un plugin.source.json tecnico. Il plugin.json finale viene generato dall’Hub al momento dell’approvazione, inserito nel pacchetto e firmato.

Fonte dei dati

Campo	Fonte autorevole	Note
`name`	Hub	Lo slug del plugin non cambia dopo la creazione. Il manifest tecnico può dichiararlo solo come controllo di coerenza.
`version`	Hub	Deve usare formato strict `x.x.x`, senza prefisso `v`. Il canale (`beta`/`stable`) è separato dalla versione.
`display_name`	Hub	Modificabile nel flusso metadata dell’Hub.
`description`	Hub	Usata nel catalogo e nel manifest firmato.
`required_tier`	Hub	Determina installabilità in base alla licenza.
`min_core_version`	Hub	Obbligatoria per invio in review; formato `x.x.x`.
`max_core_version`	Hub	Opzionale; formato `x.x.x`.
`depends_on`	`plugin.source.json`	Dipendenze tecniche da altri plugin.
`provides_routes` / `provides_models` / `provides_frontend`	`plugin.source.json`	Capacità runtime del plugin.
`icon`, `nav_category`, `nav_path`	`plugin.source.json`	Dati tecnici per integrazione UI.
`permissions`, `settings_schema`, `system_packages`	`plugin.source.json`	Contratti tecnici richiesti dal Core.

Esempio plugin.source.json

{
  "name": "xq_demo_widget",
  "author": "Acme",
  "depends_on": [],
  "provides_routes": true,
  "provides_models": false,
  "provides_frontend": true,
  "icon": "ExtensionIcon",
  "nav_category": "sistema",
  "nav_path": "/plugins/xq_demo_widget",
  "permissions": ["impostazioni"],
  "settings_schema": [],
  "system_packages": []
}

Non mettere in plugin.source.json campi di marketplace come display_name, description, required_tier, version, min_core_version o max_core_version: se presenti in un vecchio plugin.json, l’Hub li tratta come legacy e non come fonte autorevole.

Firma e review

Quando l’amministratore approva una versione:

l’Hub valida che la release version sia x.x.x e maggiore delle versioni approvate precedenti;
legge i campi tecnici dal pacchetto caricato;
genera il plugin.json effettivo unendo form Hub e manifest tecnico;
sostituisce eventuali manifest legacy nel tarball;
calcola MANIFEST.sha256;
firma il pacchetto e aggiunge MANIFEST.sha256.keyid.

Nel backoffice la review mostra anche il confronto con la versione approvata precedente, quando disponibile: campi cambiati, valore precedente e valore nuovo.

Durante la review, metadata e campi versione della release sottomessa restano bloccati per il developer. L’amministratore può correggere i campi consentiti prima dell’approvazione; il plugin.json firmato viene sempre generato dai valori effettivi approvati sull’Hub.

Le versioni non più attive possono essere archiviate. Una versione archived non entra in review e non viene distribuita; può essere ripristinata come bozza se deve essere ripresa.

Firma Marketplace

I pacchetti Marketplace approvati contengono sempre:

File	A cosa serve
`plugin.json`	Manifest runtime generato dall’Hub.
`MANIFEST.sha256`	Hash dei file distribuiti.
`MANIFEST.sha256.sig`	Firma RSA-PSS del manifest hash.
`MANIFEST.sha256.keyid`	Identificatore della chiave Marketplace usata per firmare.

Il Core verifica il pacchetto prima dell’installazione. La licenza attiva contiene le chiavi pubbliche Marketplace fidate: questo permette all’Hub di ruotare chiave di firma senza invalidare subito i pacchetti già pubblicati.

Se l’installazione arriva dal tab Sviluppatore in developer mode, XIQUIL può accettare pacchetti locali non firmati. I pacchetti scaricati dal Marketplace ufficiale devono invece superare sempre la verifica firma.

Pacchetti locali

Il Core installato dagli utenti legge sempre il plugin.json firmato. Durante sviluppo locale puoi ancora usare un plugin.json completo per testare installazioni manuali, ma il pacchetto destinato all’Hub dovrebbe contenere plugin.source.json e lasciare all’Hub la generazione del manifest runtime.

Nel repository ufficiale xiquil-plugins, package.sh esclude il plugin.json legacy dal tarball quando trova plugin.source.json.