Come va online un sito

Un sito attraversa quattro fasi. Solo l’ultima modifica ciò che vedono i visitatori.

Bozza e revisioni

La bozza è lo stato attuale dei file del sito. Ogni modifica crea una revisione: un ID di commit Git di 40 caratteri, con un riepilogo di una frase e autore (l’editor, l’assistente, un agente tramite MCP, la CLI o l’API). Nulla viene cancellato: la cronologia elenca tutte le revisioni e puoi confrontarne due o ripristinarne una precedente come nuova voce.

Una modifica corrisponde a una revisione, indipendentemente da cosa coinvolge. Una chiamata che modifica tre file crea una sola voce, mentre una modifica distribuita su più chiamate usa un changeset che esegui il commit una volta sola. Un changeset rimane aperto per 10 minuti.

Due autori contemporaneamente

Quando modifichi un file, invia l’hash che hai letto (expected_hash). Se qualcuno ha modificato quel file nel frattempo, l’intera modifica viene rifiutata con 409 conflict, non viene scritto nulla e l’errore REST o CLI include la revisione corrente:

{
  "error": {
    "type": "conflict_error",
    "code": "conflict",
    "message": "...",
    "details": {
      "reason": "revision_conflict",
      "current_revision": "9f2c...",
      "paths": [
        { "path": "src/content/site/business.json", "expected": "a1b2...", "found": "c3d4..." }
      ]
    }
  }
}

Rileggi i file indicati in paths, applica la tua modifica e riprova. Tramite MCP, l’errore comunica che il sito è cambiato da quando è stata preparata la modifica, senza details; dovrai quindi rileggere i file. Gli endpoint dei contenuti leggono da soli l’hash corrente, quindi si verifica un conflitto solo se qualcuno scrive nello stesso istante.

Build

Una build compila la bozza o una revisione specificata in un sito statico. Viene eseguita in un container isolato, senza rete né credenziali, e si interrompe dopo 5 minuti. Una build passa per gli stati queued, building e collecting fino a ready, oppure termina come failed o cancelled. Se avvii una build di una revisione per cui esiste già una build pronta, questa viene restituita anziché crearne un’altra.

Se una build non va a buon fine, error ne indica il motivo e il log della build mostra l’output del compilatore. Correggi i file e avvia un’altra build.

Anteprime

Un’anteprima è un link privato a una build, valido per 7 giorni per impostazione predefinita e per un massimo di 30. Chiunque abbia il link può vedere quella build, senza account. Il link non concede altri accessi, non viene mai indicizzato e può essere revocato. Mostra l’aspetto che avrebbe il sito, quindi condividilo prima di pubblicare.

Un’anteprima non è un sito pubblicato. Ogni pagina mostra una piccola barra “Anteprima” (nascosta mentre modifichi nell’app) e viene eseguita in modalità sandbox con origine null. Gli script non possono impostare cookie, usare l’archiviazione del browser o avviare un Worker. Le API di terze parti che rifiutano quell’origine li bloccano: perciò un modulo, un banner dei cookie o uno strumento lato client che ne ha bisogno funzionerà solo dopo la pubblicazione del sito. Un avviso della build indica quali di questi elementi usa il sito.

Pubblicazione

La pubblicazione rende una build visibile ai visitatori su tutti gli indirizzi del sito, nel giro di circa un minuto. È l’unica fase che modifica il sito pubblico.

1. Verifica. review_publish mostra quale build andrà online, se corrisponde alla bozza più recente, cosa ne impedisce la pubblicazione e un expected_generation.
2. Pubblica quella build usando l’expected_generation che hai letto.

La generazione è un contatore che aumenta a ogni pubblicazione, ripristino e rimozione della pubblicazione. Inviarla di nuovo significa pubblicare esattamente lo stato verificato. Se nel frattempo qualcun altro ha pubblicato, la chiamata viene rifiutata con 409 conflict e dovrai ripetere la verifica.

Non è possibile pubblicare una build finché è presente un blocco:

Ripristino e rimozione della pubblicazione

Un ripristino rimette online la build di una pubblicazione precedente, senza ricompilarla. La bozza non cambia, quindi può essere più recente di quella che vedono i visitatori. Un sito conserva le ultime 50 pubblicazioni per consentirne il ripristino.

Rimuovere la pubblicazione mette il sito offline: all’indirizzo i visitatori vedranno che non è disponibile alcun sito, finché non pubblicherai di nuovo. Non viene eliminato nulla.

Per pubblicare, ripristinare o rimuovere la pubblicazione serve l’ambito sites:publish; le operazioni sono disponibili solo per gli amministratori di uno spazio di lavoro. Un agente senza questo ambito può preparare tutto e chiedere al proprietario di pubblicare.

Esportazione e importazione

L’intero progetto viene esportato come archivio tar, compilabile ovunque con npm ci && npm run build. L’importazione di un archivio sostituisce la bozza con i suoi file in un’unica revisione. node_modules, dist, .git e i file segreti vengono esclusi. L’importazione non esegue né la build né la pubblicazione.