Nuovo sistema: index.json + fragment.json + compile.py (SHA-256 automatici)

SKALD.md

@@ -15,7 +15,13 @@ _Updated: 2026-07-22_
 Il branch **`main`** è il branch di **release**. Solo codice pronto per produzione finisce qui.
 Sviluppo e versioni alfa-staranno su branch separati in futuro.
 
-Per deployare l'ultima versione del marketplace sul server:
+Deploy rapido con MCP SSH:
+
+```bash
+mcp__ssh__exec alias=skald-home-server command="/home/dguiducci/marketplace_deploy.sh"
+```
+
+Oppure via SSH classico:
 
 ```bash
 ssh dguiducci@skald-home-server /home/dguiducci/marketplace_deploy.sh
@@ -28,6 +34,11 @@ Lo script sul server fa:
 La directory `/var/www/connectors.skaldagent.net/` è di proprietà di `dguiducci`,
 quindi non serve sudo per la copia.
 
+**Prima del deploy**, ricordarsi di rigenerare l'indice:
+```bash
+python3 scripts/compile.py
+```
+
 ## Cos'è
 
 Il **marketplace** è il catalogo dei connector testati per Skald. Ogni connector è un adattatore che permette a Skald di interfacciarsi con un servizio esterno (API, email, calendario, ricerca, messaggistica, ecc.).
@@ -56,18 +67,22 @@ Stato attuale (2026-07-21): tutti i 13 connector del marketplace hanno `title` n
 
 ```
 connectors/
-├── connectors.json          ← INDICE (radice di fiducia unica)
+├── index.json              ← lista ordinata degli id dei connector (input per compile.py)
+├── connectors.json         ← INDICE COMPILATO (generato da compile.py, non editare)
+├── compile.py              ← genera connectors.json
 ├── index.html               ← Catalogo UI (legge connectors.json via fetch)
 ├── oauth/
 │   └── show.html            ← OAuth callback receiver (client-side, no backend)
 ├── gmail/                   ← Un connector per cartella
+│   ├── fragment.json        ← Frammento dell'indice (id, name, type, ..., SENZA files[])
 │   ├── connector.json       ← Configurazione tecnica
 │   ├── gmail_mcp_server.py  ← Script MCP
 │   ├── gmail_oauth_setup.py ← Script setup OAuth
 │   ├── requirements.txt     ← Dipendenze Python
 │   ├── icon_sm.svg          ← Icona piccola (48×48)
-│   └── icon_lg.svg          ← Icona grande (es. preview)
+│   └── icon_lg.svg          ← Icona grande (es. 96×96)
 ├── email/
+│   ├── fragment.json
 │   ├── connector.json
 │   ├── email_mcp_server.py
 │   ├── verify.py
@@ -75,17 +90,21 @@ connectors/
 │   ├── icon_sm.svg
 │   └── icon_lg.svg
 ├── ssh/
+│   ├── fragment.json
 │   ├── connector.json
 │   ├── ssh_mcp_server.py
 │   ├── requirements.txt
 │   ├── icon_sm.svg
 │   └── icon_lg.svg
 └── tavily/
+    ├── fragment.json
     ├── connector.json
     ├── verify.py
     ├── icon_sm.png
     └── icon_lg.png
 ```
+    └── icon_lg.png
+```
 
 ## Schema — connectors.json (root)
 
@@ -436,28 +455,103 @@ il test scrivendo `verify`.
 
 ## Integrità file (sha256)
 
-- Gli hash sha256 sono **solo in `connectors.json`** (l'indice)
-- `connector.json` **non contiene hash di sé stesso** — è il file manifesto
-- L'indice è l'unica radice di fiducia; in futuro si può firmare digitalmente solo l'indice
-- Sui file locali, per calcolare/aggiornare gli hash:
-  ```bash
-  python3 -c "import hashlib; print(hashlib.sha256(open('file.py','rb').read()).hexdigest())"
-  ```
+- Gli SHA-256 sono generati **automaticamente** da `scripts/compile.py` a partire
+  dai file fisici presenti in ogni cartella — mai manuali, mai stale.
+- L'unico file firmato (in futuro) sarà `connectors.json` (l'indice).
+- `fragment.json` e `index.json` non hanno hash — sono solo input di compilazione.
+
+## Struttura directory
+
+```
+connectors/
+├── index.json              ← lista ordinata degli id dei connector (input per compile.py)
+├── connectors.json         ← INDICE COMPILATO (generato da compile.py, non editare)
+├── compile.py              ← genera connectors.json (lanciato da scripts/compile.py)
+├── index.html              ← Catalogo UI (legge connectors.json via fetch)
+├── oauth/
+│   └── show.html           ← OAuth callback receiver
+├── gmail/                   ← Un connector per cartella
+│   ├── fragment.json        ← Frammento dell'indice (id, name, type, ..., SENZA files[])
+│   ├── connector.json       ← Configurazione tecnica (mcp_config, auth.deliver, ...)
+│   ├── gmail_mcp_server.py  ← Script MCP
+│   ├── gmail_oauth_setup.py ← Script setup OAuth
+│   ├── requirements.txt     ← Dipendenze Python
+│   ├── icon_sm.svg          ← Icona piccola (48×48)
+│   └── icon_lg.svg          ← Icona grande (es. 96×96)
+├── email/
+│   ├── fragment.json
+│   ├── connector.json
+│   ├── email_mcp_server.py
+│   ├── verify.py
+│   ├── requirements.txt
+│   ├── icon_sm.svg
+│   └── icon_lg.svg
+└── ...
+```
 
 ## Workflow locale
 
-1. Lavora su file nella cartella `connectors/`
-2. Modifica `connectors.json`, `connector.json`, script, icone
-3. **Prima del deploy** aggiorna gli sha256 in `connectors.json`:
+1. **Aggiungere un nuovo connector**:
+   - Crea cartella `connectors/<id>/`
+   - Crea `fragment.json` (id, name, type, scope, icone, auth, tools, ...)
+   - Crea `connector.json` (config tecnica: mcp_config, launch_command, ...)
+   - Aggiungi script MCP, icone, verify.py, requirements.txt
+   - Aggiungi l'id a `connectors/index.json`
+   - Lancia `python3 scripts/compile.py`
+
+2. **Modificare un connector esistente**:
+   - Modifica i file nella cartella del connector
+   - **Non toccare** `connectors.json` — viene rigenerato
+   - Lancia `python3 scripts/compile.py`
+
+3. **Prima del deploy**:
    ```bash
-   python3 scripts/update_hashes.py
+   python3 scripts/compile.py           # rigenera connectors.json con SHA-256 fresh
+   python3 scripts/compile.py --verify  # (opzionale) verifica che sia aggiornato
    ```
-4. Fai l'upload sul server con rsync:
+
+4. **Deploy sul server**:
    ```bash
-   rsync -avz --delete connectors/ dguiducci@skald-server:/var/www/connectors.skaldagent.net/
+   ssh dguiducci@skald-home-server /home/dguiducci/marketplace_deploy.sh
    ```
+   oppure con MCP SSH:
+   ```bash
+   # via mcp__ssh__exec alias "skald-home-server"
+   /home/dguiducci/marketplace_deploy.sh
+   ```
+   (Il deploy script fa `git pull` + `cp -r connectors/* /var/www/connectors.skaldagent.net/`)
+
 5. Verifica su `https://connectors.skaldagent.net/`
 
+## Fragment.json
+
+Vedi [connector.manifest_guide.md](docs/connector.manifest_guide.md) per i dettagli.
+
+`fragment.json` contiene tutti i campi dell'entry di `connectors.json` **tranne** `files[]`.
+Questi sono i campi obbligatori:
+
+| Campo | Obbligatorio | Descrizione |
+|-------|-------------|-------------|
+| `id` | ✅ | Identificatore unico (match con folder name) |
+| `name` | ✅ | Nome visualizzato |
+| `type` | ✅ | `mcp_remote` o `mcp_local` |
+| `scope` | ✅ | `global` o `user` |
+| `icon_small` | ✅ | Path relativo dalla root del marketplace |
+| `icon_large` | ✅ | Path relativo dalla root del marketplace |
+| `user_description` | ✅ | Descrizione breve per la UI |
+| `requires` | ✅ | Array di enum requisiti |
+| `tags` | ✅ | Array di tag per filtraggio |
+| `folder` | ✅ | Nome della cartella del connector (match con `id`) |
+| `version` | ✅ | Intero per-connector, +1 a ogni modifica dei file |
+| `version_string` | ✅ | Semver (solo display) |
+| `version_release_date` | ✅ | Data ISO 8601 (solo display) |
+| `tools` | ✅ | Array di `{name, display_name}` per friendly names UI |
+| `auth` | opzionale | Configurazione autenticazione (se diversa da `"none"`) |
+
+Nota: l'array `files[]` (con SHA-256 e size) viene aggiunto **automaticamente**
+da `compile.py` scansionando i file presenti nella cartella — non va mai scritto
+a mano.
+
 ## Deploy su server remoto
 
 Il server remoto è:
@@ -468,19 +562,6 @@ Il server remoto è:
 - **Proprietario**: `caddy:caddy`
 - **Sudo**: richiesto per scrivere in `/var/www/`
 
-Comando di deploy (da eseguire con sudo o con rsync):
-
-```bash
-# Sync se il server permette rsync via SSH
-rsync -avz --delete ./connectors/ dguiducci@skald-server:/var/www/connectors.skaldagent.net/
-```
-
-Dopo il deploy, verificare i permessi:
-```bash
-sudo chown -R caddy:caddy /var/www/connectors.skaldagent.net/
-sudo find /var/www/connectors.skaldagent.net/ -type f -exec chmod 644 {} \;
-```
-
 ## Connector attuali
 
 | ID | Nome | Tipo | Scope | Auth | Verify |