Import, export e sincronizzazione

01Panoramica

Nucleo salva il documento JSON di ogni pagina nei metadati del post e la configurazione del sito in opzioni WordPress. I dati precalcolati per il frontend ("artefatti") stanno in file PHP sotto wp-content/uploads/nucleo/store/, oppure in opzioni se la cartella non è scrivibile. L'export trasforma il sito in una mappa "percorso relativo → testo JSON": site.json, pages/, posts/, layouts/, sections/, menus/, media/manifest.json, rules/assets.json, content/ e terms/ per i tipi e le tassonomie modellati. L'import legge la stessa mappa e crea o aggiorna ogni documento per tipo di post e slug, e ogni elemento e termine per slug. site.json contiene un'impronta (base) di ogni documento al momento dell'export: l'import la usa per rilevare le modifiche fatte sul sito nel frattempo. Tre superfici usano lo stesso motore: le ability nucleo/site-export e nucleo/site-import, i comandi WP-CLI wp nucleo export|import|sync e la pagina Strumenti. La CLI locale nucleo pull e nucleo push chiama le ability via REST e aggiunge il caricamento delle immagini (media/).

02Archiviazione

Documento e storico nei metadati del post

Cosa fa: salva il documento sorgente, il numero di revisione, l'indice runtime e lo storico delle ultime versioni nei metadati del post.

Come si usa: interno. Lo usa la pipeline di salvataggio per ogni scrittura di documento.

Parametri:

L'HTML compilato va in post_content. Il CSS compilato dei blocchi va in uploads/nucleo/css/.

Permessi: dipendono dall'ability o dal comando che salva.

Edizione: Free

Limiti noti: lo storico conserva 20 versioni. Il ripristino restituisce il documento di una revisione ma non lo salva: decide il chiamante (vedi nucleo/doc-rollback nelle ability di scrittura).

Opzioni del sito

Cosa fa: conserva la configurazione di Nucleo nella tabella delle opzioni.

Come si usa: interno. Le ability di design e di amministrazione scrivono queste opzioni.

Parametri: opzioni rilevanti per import ed export.

Le impostazioni WordPress esportate in site.json (blogname, blogdescription, show_on_front, page_on_front, page_for_posts, date_format, time_format, lingua) restano nelle opzioni native.

Permessi: dipendono dall'ability o dal comando che scrive.

Edizione: Free

Limiti noti: nessuno rilevato.

Store degli artefatti

Cosa fa: salva array PHP precalcolati che il frontend legge a ogni richiesta: token, mappa dei layout, layout compilati, regole asset, modello dei contenuti e CSS critico.

Come si usa: interno. Lo store usa la cartella wp-content/uploads/nucleo/store. Il driver attivo compare in nucleo/status e nella scheda "System status" della pagina Strumenti.

Parametri: due driver.

Nucleo sceglie php-file se la cartella esiste o si può creare ed è scrivibile. Altrimenti sceglie option. Chiavi usate: tokens, layouts, layout-<id>, asset-rules, content-model, critical e lo stato dell'ottimizzatore CSS.

Permessi: nessuno: lo store non è esposto.

Edizione: Free

Limiti noti: le chiavi devono rispettare /^[a-z0-9][a-z0-9_-]{0,63}$/. I valori accettano solo scalari, null e array annidati: oggetti, risorse, NAN e INF danno un errore. Un file illeggibile vale come artefatto assente.

Generazione dello store e ricostruzione

Cosa fa: separa i file degli artefatti di ogni database. Dopo un reset o un import del database, la generazione nell'opzione manca. Nucleo allora non legge i file vecchi e ricostruisce gli artefatti dal database.

Come si usa: automatico. All'avvio dell'area di amministrazione (admin_init) Nucleo crea la generazione se manca e ricostruisce lo store se mancano tokens o layouts. Anche la prima scrittura senza generazione la crea. L'ability nucleo/cache-rebuild ricostruisce lo store senza ricompilare i documenti.

Parametri: la generazione è un identificativo di 10 caratteri esadecimali (5 byte casuali) in nucleo_store_generation. Il formato accettato è /^[a-z0-9]{1,16}$/.

• Sul sito principale, alla creazione della generazione, Nucleo sposta nella nuova cartella i file della cartella base se il database ha dati Nucleo (documenti, layout o modello dei contenuti). Senza dati li cancella.
• Poi cancella le altre generazioni dello stesso blog.
• La ricostruzione ripubblica token, regole asset, layout e modello dei contenuti. Con l'opzione di ricompilazione accoda anche la ricompilazione di tutti i documenti.

Permessi: il controllo in admin_init gira per ogni utente che apre la bacheca. nucleo/cache-rebuild richiede manage_options e lo scope nucleo:admin.

Edizione: Free

Limiti noti: la ricostruzione usa un lock di 300 secondi: una seconda richiesta restituisce false. Un errore del filesystem in admin_init si ignora e la richiesta successiva riprova. Il frontend non ricostruisce mai lo store.

Registro di audit

Cosa fa: registra ogni scrittura delle ability con utente, client OAuth, ability, post, esito e riepilogo. nucleo/site-import scrive una riga per chiamata con riepilogo import o dry-run.

Come si usa: interno. Si legge con nucleo/audit-list.

Parametri: tabella {prefix}nucleo_audit con colonne id, time, user_id, client_id, ability, post_id, ok, summary.

Permessi: dipendono dall'ability che legge.

Edizione: Free

Limiti noti: conserva le ultime 10.000 righe. La pulizia avviene ogni 100 inserimenti. ability è troncato a 64 caratteri, summary a 255. La lettura restituisce al massimo 1.000 righe.

03Pacchetto di export

Struttura dei file

Cosa fa: definisce i file prodotti dall'export. Ogni valore è testo JSON con rientri, barre e Unicode non escapati.

Come si usa: lo producono nucleo/site-export, wp nucleo export, la pagina Strumenti (zip) e nucleo pull.

Parametri:

Si esportano solo i post dei quattro tipi che hanno un documento Nucleo, con stato any, in ordine di ID. Lo slug del file è post_name. Una bozza senza slug usa lo slug generato dal titolo, oppure post-<ID>.

Permessi: vedi nucleo/site-export.

Edizione: Free

Limiti noti: due post con lo stesso percorso (stesso tipo e stesso slug) producono un solo file: vince quello con ID più alto. Una pagina figlia usa solo il proprio slug nel nome del file: due pagine figlie omonime con genitori diversi collidono. Le pagine in un'altra lingua con lo stesso slug collidono allo stesso modo. Con un sito multilingua l'esito non è verificato: il percorso non distingue la lingua. Gli elementi con managedBy non si esportano in content/: stanno in pages/ o posts/.

site.json

Cosa fa: porta configurazione globale e impronte per il controllo dei conflitti.

Come si usa: si modifica in locale e si reinvia con l'import. Dopo un push riuscito la CLI aggiorna le chiavi base, tokensBase e siteBase.

Parametri:

homepage e postsPage sono lo slug (o il percorso, per una pagina figlia) della pagina. homepage vale null se la home mostra gli ultimi articoli.

Permessi: vedi nucleo/site-import.

Edizione: Free

Limiti noti: breakpoints è solo informativo: l'import non lo applica.

File di documento

Cosa fa: contiene il documento Nucleo (vedi lo schema del documento e dei blocchi) più il blocco wp con i dati WordPress.

Come si usa: {"schema": 1, "kind": ..., "meta": {...}, "root": {...}, "wp": {...}}.

Parametri: chiavi del blocco wp.

Riferimenti simbolici: l'export sostituisce gli ID con nomi leggibili e l'import li riconverte.

Permessi: vedi nucleo/site-import.

Edizione: Free. lang e translations richiedono il pacchetto Pro con un plugin multilingua. Nucleo controlla la presenza del componente multilingua, non la licenza.

Limiti noti: un ID senza nome resta numerico. Succede per post di tipi personalizzati nelle condizioni e per oggetti cancellati. Un URL media fuori dal manifest (per esempio una dimensione ridotta -300x200) resta assoluto. All'import un simbolo non risolto dà "Unresolved symbol: …".

menus/<slug>.json

Cosa fa: esporta un menu WordPress con le sue voci. Il nome del file è lo slug del menu.

Come si usa: {"name": "...", "items": [{"label", uno tra page | post | ref | url, "children"?}]}. ref accetta <post-type>:<slug>, term:<tassonomia>/<slug>, archive:<post-type> o home.

Parametri: vedi la descrizione completa del formato in nucleo/menu-set.

Permessi: vedi nucleo/site-import.

Edizione: Free

Limiti noti: l'export salta le voci con bersaglio non pubblicato, cancellato o non pubblico. L'ability le riporta in skipped con menu, label e reason.

Media nell'export

Cosa fa: media/manifest.json elenca gli allegati con stato inherit che hanno un file su disco: file (nome del file originale, non la copia -scaled), url, alt e sha1 del file.

Come si usa: l'export non include i file binari. All'import ogni media:<file> diventa l'URL di un allegato del sito di destinazione, in quest'ordine:

1. allegato con lo stesso nome file e lo stesso sha1;
2. allegato del sito a cui punta url della voce, se il file ha lo stesso sha1;
3. download dall'url della voce con media_sideload_image.

Un nome assente dal manifest usa l'allegato in libreria con lo stesso nome file, qualunque sia lo sha1. Nel dry-run l'URL viene dal manifest, senza download.

Parametri: nessuno.

Permessi: vedi nucleo/site-import.

Edizione: Free

Limiti noti: il download richiede che l'URL del sito di origine sia raggiungibile dal sito di destinazione e superi la validazione degli URL di WordPress. Errori: "Media not found in the manifest or in the library: …", "Invalid media URL: …", "Media not downloaded (…): …". Il manifest contiene tutta la libreria, non solo gli allegati usati.

04Export e import

nucleo/site-export

Cosa fa: restituisce il sito come mappa di file JSON, compresi gli elementi di content/ e i termini di terms/ dei tipi e delle tassonomie modellati.

Come si usa: ability di lettura, GET su /wp-json/wp-abilities/v1/abilities/nucleo/site-export/run, oppure tool MCP. Input vuoto. Output {files: {percorso: testo}, skipped: [{menu, label, reason}]}.

Parametri: nessuno.

Permessi: manage_options; scope OAuth nucleo:admin.

Edizione: Free

Limiti noti: nessuna paginazione: la risposta contiene tutti i documenti, gli elementi e il manifest completo. L'export non è un backup completo del sito: non contiene il modello dei contenuti, le impostazioni di Nucleo, le impostazioni per pagina (_nucleo_page), i campi dei documenti e i documenti su tipi di contenuto generici. Per un backup si usa uno strumento di WordPress. Annotazioni: readonly, idempotent.

nucleo/site-import

Cosa fa: importa i file prodotti da nucleo/site-export. Crea o aggiorna token, termini, elementi, sezioni, pagine, post, layout, regole, media, menu e impostazioni del sito.

Come si usa: ability di scrittura, POST su /wp-json/wp-abilities/v1/abilities/nucleo/site-import/run, oppure tool MCP. Esempio: {"files": {"pages/home.json": "{...}"}, "dryRun": true}.

Parametri:

Output: created, updated, unchanged (interi), errors ([{file, message, code, guide?}]), warnings ([{file, message}]), ids (simbolo → ID), base, tokensBase, siteBase. Codici d'errore: error, conflict, duplicate, not_json, invalid_document, quality_blocking, unsupported_status, legacy_base. Un codice di un altro servizio diventa error e resta in testa al messaggio (per esempio menu_target_missing: …).

Permessi: manage_options; scope OAuth nucleo:admin. Il limite di frequenza delle scritture vale anche qui.

Edizione: Free

Limiti noti: input non valido dà WP_Error invalid_input. Un errore su un file non ferma gli altri. tokensBase compare solo se i token del sito ora coincidono con quelli di site.json. siteBase compare solo dopo un import vero con blocco site. Il dry-run non restituisce diff né report qualità completo: solo conteggi, errori e avvisi. Annotazioni: non readonly, non destructive, idempotent.

Ordine e regole dell'import

Cosa fa: descrive come l'import elabora i file.

Come si usa: vale per ability, WP-CLI, pagina Strumenti e nucleo push.

Parametri: ordine di elaborazione.

1. Ogni percorso che non finisce in .json dà not_json. Un file .php riceve anche guide con la regola sul codice dei componenti.
2. site.json: lettura di base, site, siteBase; scrittura dei token.
3. media/manifest.json.
4. terms/*.json, poi content/<tipo>/*.json: upsert per slug, in lotti da 500 termini e da 25 elementi. Il genitore arriva prima dei figli.
5. menus/*.json: crea o rinomina i menu, senza voci.
6. sections/, ordinate per dipendenza: una sezione inserita in un'altra con nc/section-ref arriva prima.
7. pages/, ordinate per wp.parent: il genitore arriva prima dei figli.
8. posts/, poi layouts/.
9. Voci dei menu, quando pagine e post esistono.
10. rules/assets.json.
11. Lingue e collegamento delle traduzioni (solo import vero, solo con il pacchetto Pro).
12. Impostazioni del blocco site. La lingua si applica per ultima.

Le pagine arrivano prima dei layout: le condizioni dei layout citano le pagine.

Regole per i documenti:

• Ricerca per postType e slug con qualsiasi stato. Un post trovato si aggiorna, altrimenti si crea.
• Due file con stesso tipo, slug e lingua: il secondo dà duplicate.
• Documento, titolo, stato e genitore uguali al sito: nessun salvataggio, conteggio in unchanged.
• Una sezione non importata fa fallire le pagine che la usano, con il motivo.
• wp.parent su un tipo diverso da page, un genitore non trovato o un ciclo danno errore. Un figlio pubblicato con genitore non pubblicato dà un avviso.
• Il salvataggio passa dalla stessa pipeline di doc-create e doc-patch: schema, qualità bloccante, acknowledge.
• Un file in una cartella non elencata (per esempio other/) si ignora senza errore.

Regole per content/ e terms/:

• Il nome del file deve essere lo slug dell'elemento e la cartella deve essere il suo type; altrimenti l'elemento dà errore.
• Uno slug uguale a un documento di pages/ o posts/ dà duplicate: vince il documento.
• Nell'import non c'è controllo di conflitto: l'upsert sovrascrive gli elementi e i termini con lo stesso slug. Le impronte di site.json riguardano solo i documenti. Il controllo su ogni elemento e termine lo fa la CLI con la sua base (vedi nucleo push).

Permessi: quelli della superficie che chiama.

Edizione: Free

Limiti noti: le regole asset si sostituiscono per intero. L'import non cancella mai post, menu, termini, elementi o voci assenti dai file: solo wp nucleo sync --prune cestina i documenti Nucleo. La lingua del blocco site può richiedere il download del pacchetto: serve il permesso di installare lingue, oppure WP-CLI senza utente, e nessun DISALLOW_FILE_MODS. Senza pacchetto l'errore ha codice language_unavailable e le altre chiavi restano scritte.

Controllo dei conflitti

Cosa fa: confronta a tre vie il file locale, la base di site.json e lo stato del sito. Evita che un import cancelli modifiche fatte sul sito dopo l'export.

Come si usa: automatico quando site.json ha base, tokensBase o siteBase. Si scavalca con force. Non si applica a content/ e terms/ nell'import: per quei file la CLI confronta la base di ogni elemento e termine (vedi nucleo push).

Parametri: impronte.

• Documento: sha1 del documento normalizzato, del titolo e dello stato del post, con prefisso v2:. Per una pagina figlia l'impronta include il percorso del genitore. Uno spostamento, un titolo o uno stato cambiati sul sito valgono come modifica del documento. Una base senza prefisso v2: usa il confronto precedente, senza titolo e stato.
• Token: sha1 dei token effettivi, default compresi.
• Impostazioni: un'impronta per chiave del blocco site.

Un file senza voce in base non entra nel controllo: si importa. Una base scritta prima di Nucleo 0.3.5 (senza prefisso v2:) non contiene titolo e stato: se il file li cambierebbe rispetto al sito, l'import si ferma con legacy_base invece di riscriverli. Si risolve con nucleo pull --only <file> oppure nucleo push --force <file>. Per i token e le impostazioni vale la stessa tabella. Il conflitto dei token dà conflict su site.json. Il conflitto delle impostazioni elenca le chiavi coinvolte.

Permessi: quelli della superficie che chiama.

Edizione: Free

Limiti noti: force non riporta indietro una chiave di site cambiata solo sul sito: resta il valore del sito. La nuova base restituita conserva la base vecchia per le chiavi in conflitto o non scritte.

Dry-run

Cosa fa: esegue l'import senza scrivere e restituisce gli stessi errori per file.

Come si usa: dryRun: true nell'ability, wp nucleo import --dry-run, nucleo push --dry-run. La pagina Strumenti lo esegue sempre come anteprima.

Parametri: comportamento.

• I token nuovi di site.json valgono per la validazione tramite il filtro pre_option_nucleo_tokens, senza salvarli.
• Le sezioni dello stesso import valgono per le pagine che le inseriscono.
• Un documento che cita un simbolo creato nello stesso import si conta senza validarlo e riceve un avviso in warnings.
• I termini e gli elementi di content/ che questo import crea valgono come trovati per i documenti successivi, le voci dei menu e le impostazioni.
• I menu nuovi e le pagine nuove valgono come trovati per i documenti successivi, le voci dei menu e le impostazioni.
• Le voci di menu e le impostazioni del sito passano gli stessi controlli dell'import vero.

Permessi: quelli della superficie che chiama.

Edizione: Free

Limiti noti: un documento che cita un oggetto non ancora creato non riceve la validazione di schema e qualità. Lingue e traduzioni non si controllano.

wp nucleo export

Cosa fa: scrive i file dell'export in una cartella del server, compresi content/ e terms/.

Come si usa: wp nucleo export <dir> --user=<admin>. Sintassi nel capitolo sui comandi WP-CLI.

Parametri: <dir> obbligatorio: senza, il comando termina con "Specify the site folder.".

Permessi: serve un utente con manage_options: senza, il comando termina con un errore. Passare --user=<admin>.

Edizione: Free

Limiti noti: non riporta le voci di menu saltate. I file esistenti con lo stesso percorso si sovrascrivono. I file vecchi non più esportati restano. Percorsi assoluti, con .. o con backslash danno errore.

wp nucleo import

Cosa fa: legge ricorsivamente i file .json di una cartella e li importa.

Come si usa: wp nucleo import <dir> [--dry-run] [--force]. Sintassi nel capitolo sui comandi WP-CLI.

Parametri:

Permessi: serve un utente con manage_options (--user=<admin>): senza, il comando termina con un errore.

Edizione: Free

Limiti noti: stampa solo "Creati, aggiornati, invariati" e un avviso per errore. Non stampa gli avvisi. Non aggiorna la base di site.json. Non accetta acknowledge: un documento con segnalazioni bloccanti fallisce. Non accetta force per singolo file.

wp nucleo sync

Cosa fa: importa la cartella come wp nucleo import. Con --prune cestina i documenti Nucleo che non hanno più un file.

Come si usa: wp nucleo sync <dir> [--prune]. Sintassi nel capitolo sui comandi WP-CLI.

Parametri:

Permessi: serve un utente con manage_options (--user=<admin>): senza, il comando termina con un errore.

Edizione: Free

Limiti noti: niente --dry-run né --force. Il prune confronta i file della cartella, non l'esito dell'import: un file con errore protegge comunque il suo post.

Pagina Strumenti: export e import zip

Cosa fa: scarica l'export come zip e importa uno zip o file .json con anteprima.

Come si usa: bacheca, Nucleo AI → Strumenti (slug nucleo-tools).

• "Download zip" esegue nucleo/site-export e scarica nucleo-export-AAAA-MM-GG.zip, senza compressione.
• Il riquadro "Import the site" accetta un solo .zip oppure uno o più .json. Esegue subito nucleo/site-import con dryRun: true e mostra l'anteprima.
• "Import" esegue l'import vero. La casella "Overwrite changes made on the site" chiede conferma e invia force: true.

Parametri: nessuno.

Permessi: pagina con capability manage_options. Le ability richiedono manage_options.

Edizione: Free

Limiti noti:

• Lo zip deve avere voci non compresse (metodo 0) e non cifrate. Uno zip creato da un altro strumento con compressione dà errore.
• I file .json scelti singolarmente arrivano con il solo nome, senza cartella: home.json invece di pages/home.json. L'import li ignora, tranne site.json.
• Nessun campo per acknowledge né per force per singolo file.

05Sincronizzazione con la CLI locale

Cartella locale

Cosa fa: rappresenta il sito su disco. La cartella predefinita è nucleo-site nella directory corrente.

Come si usa: si crea con nucleo pull, si modifica, si invia con nucleo push. Sintassi e configurazione (--site, --user, --password, Application Password) nel capitolo sulla CLI locale.

Parametri: struttura.

nucleo-site/
├── site.json
├── pages/<slug>.json
├── posts/<slug>.json
├── layouts/<slug>.json
├── sections/<slug>.json
├── menus/<slug>.json
├── media/manifest.json
├── media/<immagine>          (solo push: caricata con nucleo/media-upload)
├── rules/assets.json
├── content/<tipo>/<slug>.json
├── terms/<tassonomia>.json
└── .nucleo-backup/           (copie di sicurezza di pull)

Permessi: vedi le singole funzioni.

Edizione: Free

Limiti noti: percorsi assoluti, con .., ., segmenti vuoti o backslash si rifiutano prima di scrivere.

nucleo pull

Cosa fa: scarica il sito nella cartella locale.

1. Chiama nucleo/site-export e scrive tutti i file restituiti.
2. Scarica gli elementi di contenuto in content/<tipo>/<slug>.json con nucleo/content-list (full: true, 50 per pagina).
3. Scarica i termini in terms/<tassonomia>.json con nucleo/terms-get.

Come si usa: nucleo pull [dir] [--prune] [--only FILE[,FILE]].

Parametri:

Cosa scarica in content/ e terms/:

• Un tipo si scarica se è nel modello dei contenuti (modeled: true) o se la cartella content/<tipo> esiste già.
• Una tassonomia si scarica se è nel modello o se terms/<tassonomia>.json esiste già.
• Gli elementi con managedBy (hanno un documento Nucleo) non si scrivono in content/: stanno in pages/ o posts/.
• Senza --prune, i file locali assenti dal sito restano e compaiono come "solo locale". I termini locali assenti dal sito restano in coda al file.

Permessi: nucleo/site-export richiede manage_options (scope nucleo:admin). nucleo/content-list richiede edit_posts o la capability edit_posts del tipo (scope nucleo:read). nucleo/terms-get richiede edit_posts e assign_terms della tassonomia (scope nucleo:read).

Edizione: Free

Limiti noti: un'ability content-list o terms-get assente (HTTP 404) si salta. Un elemento senza slug o saltato dal server dà un avviso su stderr. Le voci di menu saltate dall'export danno un avviso. Le chiamate a content-list e terms-get con rate_limited si ripetono fino a 5 volte dopo retryAfter secondi (10 se manca). La chiamata a site-export non si ripete.

nucleo pull --only

Cosa fa: riscrive solo i file indicati e la loro voce in base. Serve a risolvere un conflitto tenendo la versione del sito.

Come si usa: nucleo pull --only pages/home.json oppure --only site.json.

Parametri: elenco di percorsi presenti nella risposta di nucleo/site-export.

• Prima di sovrascrivere, ogni file locale con contenuto diverso va in <dir>/.nucleo-backup/<data-ora>/<percorso>.
• Senza site.json nell'elenco: in site.json locale cambiano solo le voci base dei file scelti. Le altre chiavi restano.
• Con site.json nell'elenco: si scrive il site.json del sito, con la base del site.json locale.

Permessi: manage_options; scope nucleo:admin.

Edizione: Free

Limiti noti: rifiuta content/ e terms/. Rifiuta un percorso assente dall'export. Non usa --prune. Le letture avvengono prima di ogni scrittura: un errore non lascia file a metà.

nucleo push

Cosa fa: invia la cartella locale al sito, in quest'ordine.

1. Carica le immagini di media/ con nucleo/media-upload e aggiorna media/manifest.json.
2. Invia terms/ con nucleo/terms-set (lotti da 500) e content/ con nucleo/content-upsert (lotti da 25).
3. Invia il resto della cartella a nucleo/site-import.
4. Dopo un push vero scrive in site.json la nuova base, tokensBase e siteBase, e la base di elementi e termini di ogni lotto accettato, anche se il push fallisce dopo.

Come si usa: nucleo push [dir] [--dry-run] [--prune] [--yes] [--use-tokens] [--acknowledge FILE] [--force FILE[,FILE]].

Parametri:

Cosa non va a site-import: content/, terms/, .nucleo-backup/ e il file dei consensi se sta nella cartella. Si leggono solo i file .json. Prima di ogni invio il comando legge e valida tutta la cartella: pagine e altri JSON, content/, terms/ e media/manifest.json. Un errore locale ferma il push senza modifiche sul sito.

Regole di content/:

• Lo slug del file deve coincidere con slug e la cartella con type, se presenti. Altrimenti errore slug_mismatch o type_mismatch.
• Uno slug presente anche in pages/ (tipo page) o posts/ (tipo post) dà duplicate: vince il documento.
• I genitori arrivano prima dei figli. Un tipo che cita <altro tipo>:<slug> in fields arriva dopo il tipo citato.
• Il prune non tocca gli elementi protected (pagine di sistema), quelli senza slug e quelli con managedBy.

Permessi: nucleo/site-import: manage_options, scope nucleo:admin. nucleo/media-upload: upload_files, scope nucleo:write. nucleo/content-upsert: edit_posts, scope nucleo:write. nucleo/terms-set: manage_terms della tassonomia, scope nucleo:write.

Edizione: Free

Limiti noti: il comando esce con codice 1 se c'è almeno un errore. Esce con 1 anche se site-import rifiuta la richiesta (ok: false), per esempio rate_limited dopo i tentativi. Un upload fallito ferma il push dopo aver salvato nel manifest le voci già caricate. Per ogni file in conflict stampa il suggerimento nucleo pull --only <file> o nucleo push --force <file>; per un file di content/ o terms/ il suggerimento è nucleo pull senza --only, che li rifiuta. I consensi su content/ e terms/ si ignorano con un avviso. Le immagini si cercano solo in media/, non nelle sottocartelle, con estensioni .jpg, .jpeg, .png, .webp, .gif, .avif.

Flusso consigliato per un conflitto

Cosa fa: riassume i messaggi che la CLI e l'import danno per un file in conflict.

Come si usa:

• Per tenere la versione del sito: nucleo pull --only <file>, poi riapplicare la modifica locale. La copia locale precedente sta in .nucleo-backup/. Per un file di content/ o terms/ pull --only non va bene: si usa nucleo pull, che riscrive i file con copie di sicurezza in .nucleo-backup/.
• Per sovrascrivere il sito: nucleo push --force <file> (ability: force: ["<file>"]).

Parametri: nessuno.

Permessi: come nucleo pull e nucleo push.

Edizione: Free

Limiti noti: nessuno rilevato.