CLI locale

01Panoramica

@nucleo/cli è un pacchetto Node con un solo eseguibile, nucleo. Non è la WP-CLI: i comandi wp nucleo … sono descritti a parte.

La CLI non contiene logica del sito. Ogni comando che tocca il sito chiama le ability di Nucleo tramite l'Abilities API di WordPress (/wp-json/wp-abilities/v1/abilities/<nome>/run), con un utente e una Application Password.

I comandi pull e push tengono il sito in una cartella locale di file JSON. Altri comandi fanno lavoro locale che il server non può fare: screenshot e coverage CSS con Playwright, analisi dei token di un file HTML, scaffold e controllo dei plugin dei componenti.

nucleo mcp espone il server MCP del sito come processo STDIO, per i client MCP che non parlano HTTP.

Il codice della CLI non controlla l'edizione. L'edizione conta solo lato sito: un comando che chiama un'ability Pro fallisce con HTTP 404 se il sito non ha la licenza Pro attiva.

02Requisiti e installazione

Requisiti

Cosa fa: elenca cosa serve per eseguire la CLI.

Come si usa: verifica la versione con node --version.

Parametri: nessuno.

Permessi: sul sito serve un utente WordPress con una Application Password. Le capability necessarie dipendono dal comando: vedi ogni comando.

Edizione: Free

Limiti noti:

• Node 20 o superiore. Il pacchetto è un modulo ES.
• Nessuna dipendenza obbligatoria.
• Playwright è facoltativo. Serve solo a screenshot e critical, con il browser Chromium.
• Sul sito serve il plugin Nucleo attivo. Il plugin richiede WordPress 6.9 o successivo, la versione con l'Abilities API che la CLI usa.
• icons add scarica le icone da https://api.iconify.design: serve accesso a Internet.
• component check usa php, phpcs, phpstan e phpunit installati in locale.

Installazione

Cosa fa: rende disponibile il comando nucleo.

Come si usa: il pacchetto non è pubblicato su npm: al 30 ottobre 2026 npm view @nucleo/cli risponde 404. Ci sono tre strade.

Strada 1, pacchetto della release. Il build della release crea il file nucleo-cli-<versione>.tgz. Il file è allegato alla release GitHub del tag v<versione>, insieme allo zip Free e al tema. Installalo con npm:

npm i -g ./nucleo-cli-0.2.0.tgz

Il campo bin del pacchetto crea il comando nucleo. Il pacchetto contiene solo bin/, src/ e README.md.

Strada 2, dal repository. In cli/ esegui npm link: npm collega il comando nucleo all'eseguibile del repository.

Strada 3, senza installazione. Esegui node cli/bin/nucleo.js <comando> dalla radice del repository.

Parametri: nessuno.

Permessi: con -g npm scrive nella cartella globale dei pacchetti.

Edizione: Free. La release GitHub contiene la CLI insieme al plugin Free.

Limiti noti: nessuno rilevato.

Installazione di Playwright

Cosa fa: abilita screenshot e critical.

Come si usa: nella cartella del progetto del sito:

npm i -D playwright && npx playwright install chromium

La CLI cerca prima Playwright accanto a sé. Poi cerca node_modules/playwright nella cartella di lavoro e nella prima cartella superiore che contiene un package.json. Non sale oltre.

Parametri: nessuno.

Permessi: nessuno.

Edizione: Free

Limiti noti: i messaggi di errore sono tre. Ognuno indica il comando da eseguire:

• Playwright assente: Playwright is not installed. … In the project folder run: npm i -D playwright && npx playwright install chromium.
• Chromium assente: Playwright is installed but Chromium is missing. Run: npx playwright install chromium.
• Librerie di sistema assenti: Chromium cannot start: system libraries are missing. Run: sudo npx playwright install-deps chromium.

03Configurazione e meccanismi comuni

Collegamento al sito

Cosa fa: definisce sito, utente e password per i comandi che chiamano il sito.

Come si usa: tre fonti, in ordine di priorità: opzioni della riga di comando, variabili d'ambiente, file nucleo.config.json nella cartella corrente.

{
  "site": "https://esempio.it",
  "user": "marco",
  "password": "abcd efgh ijkl mnop qrst uvwx",
  "componentsPath": "../wordpress/wp-content/plugins"
}

Parametri:

Permessi: l'autenticazione è una Application Password di WordPress, non OAuth. La CLI non gestisce token OAuth. Senza token OAuth il sito non controlla gli scope: contano solo le capability dell'utente.

Edizione: Free

Limiti noti:

• Errori: Missing site: use --site URL or NUCLEO_SITE, Invalid site URL: …, Invalid site URL (http or https required): …, Missing user: use --user or NUCLEO_USER, Missing Application Password: use --password or NUCLEO_APP_PASSWORD, nucleo.config.json is not valid JSON: ….
• La CLI legge la configurazione solo quando il comando chiama il sito. tokens suggest, screenshot, component new e component check funzionano senza.

Chiamate alle ability

Cosa fa: invia le chiamate alle ability del sito.

Come si usa: le ability di lettura vanno in GET con la query input[chiave]=valore, con gli oggetti annidati tra parentesi quadre. Le ability di scrittura vanno in POST con il corpo {"input": {...}}. Ogni richiesta porta Authorization: Basic … e Accept: application/json.

Parametri: nessuno.

Permessi: quelli di ogni ability.

Edizione: Free

Limiti noti:

• HTTP 401 o 403: <ability>: accesso negato (HTTP <stato>). Controlla utente e Application Password.
• HTTP 404: <ability>: ability not found (HTTP 404). Is Nucleo active on this site?. Lo stesso messaggio compare quando l'ability è Pro e il sito non ha la licenza: le ability Pro non si registrano.
• Altri stati: <ability>: <message> con il messaggio del sito, oppure HTTP <stato>.
• Rete: Connection to <sito> failed: ….
• Limite di frequenza del sito: 60 scritture ogni 60 secondi per utente e gruppo di scope (filtro nucleo/rate_limit). La risposta è ok: false con error.code rate_limited. Solo le chiamate di content-list, terms-set e content-upsert fatte da pull e push riprovano: aspettano retryAfter secondi (10 se manca), fino a 5 volte. Le altre chiamate riportano l'errore.

Riga di comando, uscita e codici

Cosa fa: interpreta argomenti e opzioni con la stessa regola per tutti i comandi.

Come si usa: nucleo <comando> [argomenti] [--opzione valore | --opzione=valore | --flag].

Parametri: opzioni booleane, senza valore: --dry-run, --prune, --yes, --help, --version, --no-push, --use-tokens. Tutte le altre richiedono un valore. Le booleane accettano anche =true o =1 e =false o =0; un altro valore dà errore.

Permessi: nessuno.

Edizione: Free

Limiti noti:

• Un'opzione con valore seguita da niente o da un'altra --opzione dà Missing value for --<nome>. -- da solo dà Invalid option: --.
• Un'opzione che il comando non accetta dà Unknown option: --<nome>. Use "nucleo help"., prima di ogni chiamata al sito.
• Codice di uscita: 0 se il comando riesce, 1 per errori di uso, errori del sito o passi falliti. component deploy esce con 2 se copia il plugin ma non lo attiva. Gli errori vanno su stderr con il prefisso nucleo: .
• Un comando sconosciuto dà Unknown command: <nome>. Use "nucleo help".
• I messaggi sono in parte in italiano e in parte in inglese.

04Comandi generali

nucleo help

Cosa fa: stampa l'elenco dei comandi e delle opzioni di configurazione, in inglese. Elenca anche --urls e --no-push di critical.

Come si usa: nucleo help, nucleo --help oppure nucleo senza argomenti. --help vale con qualsiasi comando e stampa sempre lo stesso testo generale.

Parametri: nessuno.

Permessi: nessuno.

Edizione: Free

Limiti noti: nessuno rilevato.

nucleo --version

Cosa fa: stampa la versione del pacchetto (0.2.0 a questo commit).

Come si usa: nucleo --version.

Parametri: nessuno.

Permessi: nessuno.

Edizione: Free

Limiti noti: nessuno rilevato.

nucleo guide

Cosa fa: legge la guida a fasi dal sito e la stampa come testo. Senza fase, il sito sceglie la prima fase non completata.

Come si usa: nucleo guide [fase] [--design PERCORSO]. Chiama nucleo/guide in GET. Le fasi sono descritte nella guida a fasi.

Parametri:

Permessi: edit_posts. Scope OAuth dell'ability: nucleo:read.

Edizione: Free

Limiti noti: output su righe fisse: Phase N: <titolo>, State: tokens … · sections … · layouts … · menus … · post types … · documents …. Seguono, se presenti, Checks: (conteggi per tipo), Distinct: (elenco), Coverage: N of M documents read, poi le sezioni Basics: (in ogni chiamata, tranne la fase 0), To do:, Rules: (con tools:), Exit: e Next:. Le sezioni vuote non compaiono. Una risposta ok: false diventa un errore con il messaggio del sito.

05Sincronizzazione del sito

nucleo pull

Cosa fa: scarica il sito in una cartella locale. Prima scrive i file di nucleo/site-export. Poi scarica gli elementi dei tipi di contenuto in content/<tipo>/<slug>.json e i termini in terms/<tassonomia>.json. Ogni elemento e ogni termine riceve la chiave base: l'impronta della versione del sito, usata dal push per riconoscere le modifiche fatte sul sito dopo il pull.

Come si usa: nucleo pull [cartella] [--prune]. Chiamate, in ordine:

1. nucleo/site-export, che scrive i file di esportazione.
2. nucleo/content-list con perPage: 1 per l'elenco dei tipi. Poi, per ogni tipo, con type, full: true, perPage: 50 e page, fino all'ultima pagina.
3. nucleo/terms-get senza input per l'elenco delle tassonomie. Poi con taxonomy per ognuna.

Parametri:

Permessi: manage_options per site-export (scope nucleo:admin). edit_posts sul tipo per content-list (scope nucleo:read). edit_posts, più assign_terms della tassonomia, per terms-get (scope nucleo:read).

Edizione: Free

Limiti noti:

• Scarica solo i tipi con modeled: true nella risposta di content-list e quelli con una cartella content/<tipo>/ locale. Vale lo stesso per le tassonomie con terms/<tassonomia>.json locale.
• Gli elementi con managedBy non si scrivono. Gli elementi saltati dal server diventano avvisi e il loro file locale non si cancella.
• Un content-list o un terms-get assente (HTTP 404) non è un errore: la parte relativa si salta.
• Senza --prune, un termine locale assente sul sito resta in coda al file. Un file locale assente sul sito si elenca come local only: …. Un documento di pages/, posts/, layouts/, sections/ o menus/ assente dall'export si elenca come no longer on the site: …: un push successivo lo ricreerebbe.
• Un percorso assoluto, con .., ., segmenti vuoti o \ nella risposta del sito dà errore prima di scrivere.
• Prima di sovrascrivere o cancellare, copia ogni file locale con contenuto diverso in <cartella>/.nucleo-backup/<data-ora>/<percorso>. La data-ora è quella ISO con - al posto di : e ..
• Output: Wrote N files in <cartella>, poi local backup: …, removed: … e local only: … su stdout. Gli avvisi warning: … vanno su stderr, anche per le voci di menu saltate da site-export.

nucleo pull --only

Cosa fa: scarica solo alcuni file di nucleo/site-export e aggiorna in site.json solo la loro base. Serve a risolvere un conflitto tenendo la versione del sito.

Come si usa: nucleo pull [cartella] --only pages/home.json,menus/principale.json. Chiama solo nucleo/site-export.

Parametri:

Permessi: manage_options (scope nucleo:admin).

Edizione: Free

Limiti noti:

• Rifiuta i percorsi in content/ e terms/: --only non accetta <file>: content/ e terms/ si scaricano con nucleo pull senza --only.
• Rifiuta un percorso assente dall'export: <file> non è tra i file di nucleo/site-export.
• Non scarica content/ e terms/ e ignora --prune.
• Un file locale diverso da quello del sito viene copiato prima in <cartella>/.nucleo-backup/<data-ora>/<percorso>. L'output lo segnala con local backup: <percorso>.
• Con site.json nell'elenco, il file scritto tiene la base del site.json locale.
• Le letture avvengono prima di ogni scrittura: un errore non lascia file a metà.

nucleo push

Cosa fa: invia la cartella locale al sito. Ordine: immagini di media/, termini di terms/, elementi di content/, poi tutti gli altri file .json con nucleo/site-import. Prima di caricare immagini o inviare dati esegue lo stesso push in dry-run: se il sito trova errori, il comando si ferma senza modificare nulla. Dopo ogni lotto di content/ o terms/ accettato scrive la base degli elementi e dei termini di quel lotto, anche se il push fallisce dopo; dopo un push riuscito aggiorna base, tokensBase e siteBase in site.json.

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

1. nucleo/media-upload per ogni immagine .jpg, .jpeg, .png, .webp, .gif e .avif di media/ (non ricorsivo). Aggiorna media/manifest.json con file, url, alt e sha1.
2. nucleo/terms-set per tassonomia, a lotti di 500 termini, genitori prima dei figli.
3. nucleo/content-upsert per tipo, a lotti di 25 elementi. I tipi citati da altri (<tipo>:<slug> in fields) vanno prima.
4. Con --prune: nucleo/content-list con perPage: 100 per ogni tipo con cartella locale. Con --yes: content-upsert con status: "trash".
5. nucleo/site-import con files (tutti i .json fuori da content/, terms/ e .nucleo-backup/), dryRun e, se presenti, pending, acknowledge e force.

Parametri:

Permessi: upload_files per media-upload (scope nucleo:write). manage_terms della tassonomia per terms-set (scope nucleo:write). edit_posts per content-upsert (scope nucleo:write). manage_options per site-import (scope nucleo:admin). edit_posts sul tipo per content-list.

Edizione: Free

Limiti noti:

• Output su stdout: media: <file> → <url> (id N), oppure (id N, already present) o (dry run). Poi created: N, updated: N, unchanged: N (documenti uguali a quelli del sito, se maggiore di 0), content unchanged: N (elementi di content/ e termini di terms/ uguali a quelli del sito, se maggiore di 0), trashed: N (se maggiore di 0) ed errors: N. Ogni errore va su stderr come - <file>: <messaggio> (<codice>).
• Codice di uscita 1 se c'è almeno un errore.
• Con errori quality_blocking stampa: Blocking issues: fix them, or ask the user to accept them and pass the file with --acknowledge FILE.
• Per ogni conflict stampa: Conflict: keep the site version with nucleo pull --only <file>, or overwrite it with nucleo push --force <file>. Per un file di content/ o terms/ il suggerimento è nucleo pull, senza --only, che li rifiuta.
• Un elemento o un termine cambiato sul sito dopo il pull (base diversa) dà conflict e non si scrive. Per tenere la versione del sito si esegue nucleo pull; per sovrascriverla, --force con il file.
• Un upload fallito ferma il push prima di site-import. Le voci già caricate restano nel manifest.
• Errori locali su content/ e terms/ fermano il push prima di ogni invio, con Contenuti non validi: <file>: <messaggio>. Codici: invalid_json, invalid_value, slug_mismatch (campo slug diverso dal nome del file), type_mismatch (campo type diverso dalla cartella) e duplicate (stesso slug in pages/ o posts/ per i tipi page e post).
• --prune non tocca gli elementi con protected: true, quelli con managedBy e i termini. Senza --yes stampa (add --yes to trash them).
• Un JSON non valido fuori da content/ e terms/, anche media/manifest.json, ferma il comando prima di ogni invio: Invalid JSON in <file>: ….
• Se site-import risponde ok: false, per esempio rate_limited dopo 5 nuovi tentativi, il comando esce con 1 e il messaggio del sito.
• Se il controllo preliminare in dry-run trova errori, stampa no changes to the site: il sito non viene toccato.
• Una cartella inesistente dà Folder not found: <cartella>.

nucleo push --use-tokens

Cosa fa: prima dell'invio, sostituisce nei documenti locali i valori di style uguali a un token con il riferimento $gruppo.chiave.

Come si usa: nucleo push [cartella] --use-tokens [--dry-run]. Chiama nucleo/tokens-get. I token di site.json hanno la precedenza su quelli del sito.

Parametri: nessuno oltre al flag. Con --dry-run conta le sostituzioni, non modifica i file e valida le versioni con i token sostituiti, come il push vero.

Permessi: edit_posts (scope nucleo:read), più i permessi di push.

Edizione: Free

Limiti noti:

• Vale per i file .json con un oggetto root, fuori da content/, terms/ e media/. Visita style di ogni nodo e dei figli, anche i valori per breakpoint.
• Gruppi e proprietà: color (color, background, accentColor, dotColor e altre chiavi delle parti interne), space (padding, margin, gap, controlsInset …), radius (borderRadius …), shadow (boxShadow), font (fontFamily, numberFont). Le chiavi di stato …Hover e …Current usano il gruppo della chiave base.
• Il confronto è esatto dopo la normalizzazione: minuscole, spazi, #abc → #aabbcc, px → rem (16 px = 1 rem). Un valore solo vicino a un token resta invariato. 0 e i riferimenti $… non si sostituiscono. Con più token uguali vince il primo.
• Output: tokens: <file> <n> per file e tokens: N replacements.

nucleo push --acknowledge

Cosa fa: invia a site-import i consensi di una persona sulle segnalazioni di qualità bloccanti (quality_blocking).

Come si usa: nucleo push nucleo-site --acknowledge consensi.json. Il file ha questa forma:

{
  "pages/home.json": [
    { "rule": "a11y.contrast.low", "node": "cta", "reason": "Consenso di Marco, 27/10" }
  ]
}

La CLI mostra ogni consenso (Acknowledgement: <file> <regola> @<nodo>, reason: …) e chiede Confirm? [y/N]. Accetta y, yes, s, si o sì. Invia solo i consensi confermati.

Parametri: --acknowledge, percorso del file relativo alla cartella corrente.

Permessi: quelli di push.

Edizione: Free

Limiti noti:

• Senza terminale interattivo (agente, CI, pipe) il comando si rifiuta: --acknowledge needs an interactive terminal: a person confirms each acknowledgement. ….
• Ogni voce richiede rule, node e reason come stringhe non vuote. Altrimenti: <file>: <percorso> deve essere { "percorso.json": [{ "rule", "node", "reason" }] } con reason non vuoto.
• File assente: Acknowledgement file not found: …. JSON non valido: Invalid JSON in ….
• Un consenso su un file non inviato a site-import, anche in content/ o terms/, dà l'avviso acknowledgement ignored: ….
• Il file dei consensi dentro la cartella del sito non viene inviato a site-import.

06Design e media

nucleo tokens suggest

Cosa fa: legge il CSS di un file HTML di design e propone i token per nucleo/tokens-set. Non scrive file e non chiama il sito.

Come si usa: nucleo tokens suggest design.html > tokens.json. Su stdout stampa solo {"tokens": …}. Su stderr stampa le prove: <gruppo>.<chiave>: <valore> (<occorrenze>) from <variabile> e no token: <tipo> <valore> (<occorrenze>).

Parametri:

Permessi: nessuno.

Edizione: Free

Limiti noti:

• Legge i blocchi <style> e gli attributi style. Toglie prima gli <script>. Ignora @font-face. Le definizioni fuori da @media, @supports e @container vincono.
• Un valore diventa token solo se compare almeno 3 volte.
• Con almeno 3 variabili CSS definite nel file, sostituisce var(--nome) con il valore e ignora le regole senza variabili le cui classi non compaiono nel markup.
• Gruppi prodotti: color (primary, secondary, accent, background, text, surface, border, muted, scelti per luminosità e saturazione), font (body, heading), space (chiavi 1–16 per vicinanza), text (xs–6xl), radius (sm, md, lg, full), shadow (sm, md, lg). Le durate finiscono sempre in no token.
• Non diventano token unset, inherit, initial, revert, revert-layer, none, normal, i valori con var( non risolti e i valori con ;{}<>\.

nucleo media upload

Cosa fa: carica uno o più file nella libreria media del sito.

Come si usa: nucleo media upload foto1.jpg foto2.png [--alt TESTO]. Chiama nucleo/media-upload per ogni file, con file (nome base), data (base64) e alt.

Parametri:

Permessi: upload_files (scope nucleo:write).

Edizione: Free

Limiti noti:

• Il sito accetta JPEG, PNG, WebP, GIF e AVIF.
• Output: <file> → <url> (id N), oppure (already present) per un file già nella libreria. Un file fallito va su stderr e non ferma gli altri. Codice 1 se almeno uno fallisce.
• Nessun nuovo tentativo dopo rate_limited.

nucleo icons import

Cosa fa: carica come icone del sito i file .svg di una cartella.

Come si usa: nucleo icons import ./icone [--prefix P]. Chiama nucleo/icons-set con { set: { nome: svg } }, a lotti di 50.

Parametri:

Permessi: manage_options (scope nucleo:admin).

Edizione: Free

Limiti noti:

• Nome dell'icona: prefisso più nome del file senza estensione, in minuscolo, con le sequenze fuori da a-z0-9 sostituite da -. Un nome che non inizia con una lettera si salta con un avviso.
• Senza file validi: nessun file SVG con nome valido in <cartella>, codice 1.
• Un lotto fallito non ferma gli altri. Output: site icons: N.

nucleo icons add

Cosa fa: scarica icone da Iconify e le carica come icone del sito.

Come si usa: nucleo icons add mdi:car lucide:truck oppure nucleo icons add mdi:car --as auto. Scarica https://api.iconify.design/<prefisso>/<nome>.svg, poi chiama nucleo/icons-set.

Parametri:

Permessi: manage_options (scope nucleo:admin).

Edizione: Free

Limiti noti: un'icona con HTTP diverso da 200, o con una risposta che non inizia con <svg, dà errore e non ferma le altre. Codice 1 se almeno una fallisce. Il nome inviato non passa dalla normalizzazione di icons import.

nucleo icons remove

Cosa fa: rimuove icone del sito.

Come si usa: nucleo icons remove auto camion. Chiama nucleo/icons-set con { remove: [...] }.

Parametri: <nome...>, uno o più nomi.

Permessi: manage_options (scope nucleo:admin).

Edizione: Free

Limiti noti: output site icons: N. Errore dell'ability su stderr e codice 1.

nucleo icons list

Cosa fa: stampa su una riga le icone del sito, su una seconda riga le icone integrate.

Come si usa: nucleo icons list. Chiama nucleo/icons-set con input vuoto, in POST.

Parametri: nessuno.

Permessi: manage_options (scope nucleo:admin).

Edizione: Free

Limiti noti: la chiamata è una scrittura per il sito e conta nel limite di 60 scritture al minuto. Un sottocomando non valido dà l'uso Usage: nucleo icons import <folder> [--prefix P] | add <prefix:name...> [--as NAME] | remove <name...> | list.

07Browser locale (Playwright)

nucleo screenshot

Cosa fa: scatta screenshot a pagina intera di un URL a più larghezze. Non chiama le ability del sito.

Come si usa: nucleo screenshot https://esempio.it/chi-siamo/ [--out cartella] [--widths 390,768,1440]. Richiede Playwright con Chromium.

Parametri:

Permessi: nessuno sul sito. La CLI non invia credenziali alla pagina.

Edizione: Free

Limiti noti:

• Viewport alto 900 px. Attende networkidle prima dello scatto.
• Nome del file: <host-percorso>-<larghezza>.png, con i caratteri fuori da a-z0-9 sostituiti da - (home se vuoto). Stampa un percorso per riga.
• Una pagina riservata agli utenti loggati mostra la versione pubblica: Playwright non riceve i cookie dell'utente.

nucleo critical

Cosa fa: per ogni template apre l'URL con Chromium a quattro viewport (390, 820, 1440 e 2560 px), raccoglie le regole CSS che colpiscono almeno un elemento visibile nella prima schermata e scrive il risultato unito in <cartella>/<template>.css. Senza --no-push invia il CSS come critical CSS del template.

Come si usa:

• nucleo critical --urls home=https://esempio.it/,page=https://esempio.it/chi-siamo/ [--out cartella] [--no-push]
• nucleo critical [--out cartella] [--no-push]: senza --urls legge la mappa urls (template → URL) di nucleo/assets-report.

Per ogni CSS chiama nucleo/critical-set con template e css.

Parametri:

Permessi: manage_options per assets-report (scope nucleo:read). edit_theme_options per critical-set (scope nucleo:design). La configurazione del sito è obbligatoria anche con --urls --no-push.

Edizione: con --urls Free. Senza --urls Pro, perché nucleo/assets-report richiede la licenza Pro. Senza licenza il comando scrive nucleo: nucleo/assets-report not found. Without --urls, critical needs Nucleo Pro with an active licence. ed esce con 1.

Limiti noti:

• Senza --urls usa la mappa urls del report. Le voci senza URL assoluto si riportano su stderr come no URL in the report for template "<nome>", skipped. Se non resta alcun URL: nucleo: no URL to analyse. Run the asset audit or pass --urls template=URL., con codice 1.
• Ogni template si misura a quattro viewport (390×844, 820×1180, 1440×900, 2560×1440). Le regole si uniscono senza doppioni, nell'ordine di prima comparsa.
• Il CSS contiene solo le regole che colpiscono almeno un elemento visibile nella prima schermata. I fogli di altra origine non si leggono e si saltano.
• La CLI limita il CSS a 50 KB: la fusione si ferma alla prima regola che supererebbe il limite, senza errore. Il sito rifiuta comunque un CSS oltre 50 KB (The critical CSS exceeds the 50 KB limit.): il file locale resta scritto e il comando si ferma al primo esito ok: false di critical-set, con il messaggio del sito.
• Nome del file: il template con i caratteri fuori da A-Za-z0-9._- sostituiti da -.

08MCP

nucleo mcp

Cosa fa: fa da proxy tra STDIO e il server MCP HTTP del sito (POST <sito>/wp-json/nucleo/v1/mcp). Serve ai client MCP che avviano un processo locale.

Come si usa: nucleo mcp con NUCLEO_SITE, NUCLEO_USER e NUCLEO_APP_PASSWORD nell'ambiente del client MCP. Ogni riga di stdin è un messaggio JSON-RPC. Ogni risposta esce su stdout su una riga.

Parametri: nessuno oltre alla configurazione del sito.

Permessi: utente loggato via Application Password. Ogni ability chiamata controlla la sua capability. Gli scope OAuth non si applicano.

Edizione: Free. Le ability Pro compaiono solo se il sito ha la licenza.

Limiti noti:

• Le richieste si elaborano in sequenza, una alla volta.
• Le notifiche, cioè i messaggi senza id, non producono output. Un errore su una notifica va su stderr.
• JSON non valido: risposta -32700 Parse error. Errore HTTP o risposta vuota: risposta -32000 con il messaggio.
• La CLI rimanda l'intestazione Mcp-Session-Id se il server la invia. Il server di Nucleo a questo commit non la invia.
• Il processo termina con codice 0 alla chiusura di stdin.

09Componenti

nucleo component new

Cosa fa: crea un componente (data source, azione o blocco) in un plugin locale dei componenti. Se il plugin manca, crea anche lo scheletro.

Come si usa: nucleo component new <data-source|action|block> <nome> [--dir CARTELLA] [--vendor PREFISSO]. Non chiama il sito.

Parametri:

Permessi: nessuno sul sito.

Edizione: Free

Limiti noti:

• Scheletro del plugin: <slug>.php con l'intestazione Nucleo Components: <vendor>, composer.json, phpunit.xml, phpstan.neon, phpcs.xml.dist e tests/bootstrap.php.
• File del componente: src/DataSources/<Classe>.php, src/Actions/<Classe>.php oppure blocks/<nome>/block.nucleo.json con src/Blocks/<Classe>Renderer.php. Sempre un test in tests/<Classe>Test.php. Il nome registrato è <vendor>/<nome>.
• Se un file previsto esiste già, non scrive nulla: File già esistente: … Nessun file scritto.
• Stampa i percorsi scritti, uno per riga.

nucleo component check

Cosa fa: esegue php -l sui file PHP del plugin, poi phpcs, phpstan e phpunit. Un passo fallito non ferma gli altri.

Come si usa: nucleo component check [--dir CARTELLA]. Non chiama il sito.

Parametri:

Permessi: nessuno sul sito.

Edizione: Free

Limiti noti:

• Ricerca degli strumenti: <plugin>/vendor/bin/<strumento>, poi NUCLEO_TOOLS/<strumento>, poi il nome nel PATH.
• Argomenti fissi: phpcs --standard=phpcs.xml.dist, phpstan analyse --no-progress --memory-limit=1G -c phpstan.neon, phpunit -c phpunit.xml.
• Output: <passo>: ok|fail|missing e l'output del passo se non è ok. Codice 1 se un passo non è ok.
• Plugin assente: Plugin not found in <dir>: <slug>.php is missing. Create it with "nucleo component new".

nucleo component deploy

Cosa fa: controlla il plugin, lo copia nella cartella dei plugin di un WordPress locale e lo attiva. La copia è locale: nessuna richiesta HTTP trasporta codice PHP.

Come si usa: nucleo component deploy [--dir CARTELLA] [--plugins PERCORSO]. Passi:

1. Chiama nucleo/site-describe e legge environment. Procede solo con local o development.
2. Esegue component check. Se un passo non è ok, non copia nulla.
3. Copia la cartella in una cartella temporanea accanto alla destinazione, senza file nascosti, vendor, node_modules, tests, phpunit.xml, phpstan.neon, phpcs.xml.dist e composer.lock. Alla fine sostituisce la destinazione. Se la copia fallisce, la versione precedente resta.
4. Chiama nucleo/component-activate con plugin: <slug>.

Parametri:

Permessi: edit_posts per site-describe (scope nucleo:read). activate_plugins per component-activate (scope nucleo:admin). Scrittura sul file system della cartella dei plugin.

Edizione: Free

Limiti noti:

• Con staging, production o ambiente assente stampa il passo umano ed esce con 1: il componente arriva con la migrazione del sito o con il deploy via git.
• Non sovrascrive una destinazione esistente senza la riga Nucleo Components: nei primi 8 KB del file principale. Rifiuta sorgente e destinazione coincidenti o una dentro l'altra, anche tramite link simbolici: non copia nulla ed esce con 1.
• Se il sito risponde not_found dopo la copia, componentsPath non è la cartella dei plugin del sito collegato: messaggio ed uscita con 1.
• Altri errori di attivazione: la copia resta, il comando stampa activate <slug> from Plugins (<errore>) ed esce con 2.
• Output in caso di successo: copied N files to <destinazione> e plugin active.