@noeva/etl-core 1.0.0-next.1 → 1.0.0-next.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. package/dist/cli.js +103 -103
  2. package/dist/guida/404.html +2 -2
  3. package/dist/guida/GUIDA_SVILUPPO.html +5 -5
  4. package/dist/guida/TECHNICAL_OVERVIEW.html +3 -3
  5. package/dist/guida/assets/{GUIDA_SVILUPPO.md.Dj20s7gS.js → GUIDA_SVILUPPO.md.D13C7Zwu.js} +1 -1
  6. package/dist/guida/assets/{app.vAJRZtow.js → app.BMz6ZZYF.js} +1 -1
  7. package/dist/guida/assets/chunks/@localSearchIndexroot.B3bE99g8.js +1 -0
  8. package/dist/guida/assets/chunks/{VPLocalSearchBox.D3nX303F.js → VPLocalSearchBox.D8gO6gDY.js} +1 -1
  9. package/dist/guida/assets/chunks/{theme.Bq6mfDhZ.js → theme.DV62mViB.js} +2 -2
  10. package/dist/guida/connectors/README.html +3 -3
  11. package/dist/guida/connectors/file.html +3 -3
  12. package/dist/guida/connectors/http.html +3 -3
  13. package/dist/guida/connectors/imap.html +3 -3
  14. package/dist/guida/connectors/jira.html +3 -3
  15. package/dist/guida/connectors/noeva.html +3 -3
  16. package/dist/guida/connectors/oauth.html +3 -3
  17. package/dist/guida/connectors/postgres.html +3 -3
  18. package/dist/guida/connectors/process.html +3 -3
  19. package/dist/guida/connectors/sendgrid.html +3 -3
  20. package/dist/guida/connectors/smtp.html +3 -3
  21. package/dist/guida/connectors/sqlserver.html +3 -3
  22. package/dist/guida/conventions/node-columns.html +3 -3
  23. package/dist/guida/conventions/node-descriptor.html +3 -3
  24. package/dist/guida/conventions/run-report.html +3 -3
  25. package/dist/guida/conventions/run-trace.html +3 -3
  26. package/dist/guida/conventions/variabili-del-core.html +3 -3
  27. package/dist/guida/conventions/versioni-di-pipeline.html +3 -3
  28. package/dist/guida/guide/claude-code/index.html +3 -3
  29. package/dist/guida/guide/claude-code/prompt.html +3 -3
  30. package/dist/guida/guide/claude-code/strumenti.html +3 -3
  31. package/dist/guida/guide/grafo.html +3 -3
  32. package/dist/guida/guide/usare/app-desktop.html +3 -3
  33. package/dist/guida/guide/usare/esito-di-una-run.html +3 -3
  34. package/dist/guida/guide/usare/index.html +3 -3
  35. package/dist/guida/hashmap.json +1 -1
  36. package/dist/guida/index.html +3 -3
  37. package/dist/guida/nodes/README.html +3 -3
  38. package/dist/guida/nodes/action.html +3 -3
  39. package/dist/guida/nodes/ai.html +3 -3
  40. package/dist/guida/nodes/join.html +3 -3
  41. package/dist/guida/nodes/lookup.html +3 -3
  42. package/dist/guida/nodes/pipeline.html +3 -3
  43. package/dist/guida/nodes/route.html +3 -3
  44. package/dist/guida/nodes/sink.html +3 -3
  45. package/dist/guida/nodes/source.html +3 -3
  46. package/dist/guida/nodes/task.html +3 -3
  47. package/dist/guida/nodes/transform.html +3 -3
  48. package/dist/guida/nodes/try-catch.html +3 -3
  49. package/dist/guida/nodes/union.html +3 -3
  50. package/dist/guida/pipelines/README.html +3 -3
  51. package/dist/guida/pipelines/crm-leads-sync.html +3 -3
  52. package/dist/guida/pipelines/cross-workspace-csv-merge.html +3 -3
  53. package/dist/guida/pipelines/movimenti-per-conto.html +3 -3
  54. package/dist/guida/pipelines/orders-enriched-daily.html +3 -3
  55. package/dist/guida/pipelines/test-posta.html +3 -3
  56. package/dist/guida/runbooks/aggiornamento-pm2.html +3 -3
  57. package/dist/guida/runbooks/deployment.html +3 -3
  58. package/dist/guida/runbooks/etl-worker.html +3 -3
  59. package/dist/guida/runbooks/graph-server.html +3 -3
  60. package/dist/guida/runbooks/mask-key.html +3 -3
  61. package/dist/guida/runbooks/oauth-google-posta.html +3 -3
  62. package/dist/guida/runbooks/rollback-di-pipeline.html +3 -3
  63. package/dist/guida/runbooks/scd2-rehash.html +3 -3
  64. package/dist/guida/runbooks/sql-task-truncate-swap.html +3 -3
  65. package/dist/guida/runbooks/stato-incrementale.html +3 -3
  66. package/dist/guida/sub-pipelines/README.html +3 -3
  67. package/dist/guida/sub-pipelines/riepilogo-ordini.html +3 -3
  68. package/package.json +1 -1
  69. package/dist/guida/assets/chunks/@localSearchIndexroot.Bhyx8u0i.js +0 -1
  70. /package/dist/guida/assets/{GUIDA_SVILUPPO.md.Dj20s7gS.lean.js → GUIDA_SVILUPPO.md.D13C7Zwu.lean.js} +0 -0
@@ -9,7 +9,7 @@
9
9
  <link rel="preload stylesheet" href="/guida/core/assets/style.BNn_AkzN.css" as="style">
10
10
  <link rel="preload stylesheet" href="/guida/core/vp-icons.css" as="style">
11
11
 
12
- <script type="module" src="/guida/core/assets/app.vAJRZtow.js"></script>
12
+ <script type="module" src="/guida/core/assets/app.BMz6ZZYF.js"></script>
13
13
  <link rel="preload" href="/guida/core/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
14
14
  <link rel="icon" type="image/svg+xml" href="/guida/core/favicon.svg">
15
15
  <meta name="theme-color" content="#0a0e15">
@@ -18,7 +18,7 @@
18
18
  </head>
19
19
  <body>
20
20
  <div id="app"></div>
21
- <script>window.__VP_HASH_MAP__=JSON.parse("{\"connectors_file.md\":\"B1NJe0VJ\",\"connectors_http.md\":\"B8utPijY\",\"connectors_imap.md\":\"CMMpZVXn\",\"connectors_jira.md\":\"0DJvrRXH\",\"connectors_noeva.md\":\"DkxCC8Ey\",\"connectors_oauth.md\":\"DUHajB0u\",\"connectors_postgres.md\":\"DPpHqXkc\",\"connectors_process.md\":\"lQLmWbGN\",\"connectors_readme.md\":\"ChyXSf73\",\"connectors_sendgrid.md\":\"dJzIWepq\",\"connectors_smtp.md\":\"DXXvaNxD\",\"connectors_sqlserver.md\":\"D1sYNLEq\",\"conventions_node-columns.md\":\"D9K1peUx\",\"conventions_node-descriptor.md\":\"D8Si7E2S\",\"conventions_run-report.md\":\"D_pG07VG\",\"conventions_run-trace.md\":\"nKS_RgLC\",\"conventions_variabili-del-core.md\":\"BU6BD6w_\",\"conventions_versioni-di-pipeline.md\":\"cy5nsizS\",\"guida_sviluppo.md\":\"Dj20s7gS\",\"guide_claude-code_index.md\":\"CxVSru8e\",\"guide_claude-code_prompt.md\":\"C7uETA9W\",\"guide_claude-code_strumenti.md\":\"BWhQnAlY\",\"guide_grafo.md\":\"Dy8_YMeh\",\"guide_usare_app-desktop.md\":\"CcDu8cJL\",\"guide_usare_esito-di-una-run.md\":\"DkvAOPBE\",\"guide_usare_index.md\":\"BJqi3P7J\",\"index.md\":\"kMhsF-sv\",\"nodes_action.md\":\"DOsTbV-i\",\"nodes_ai.md\":\"CVtP9gEJ\",\"nodes_join.md\":\"DSYbIDG6\",\"nodes_lookup.md\":\"BI8tgBIq\",\"nodes_pipeline.md\":\"DIMlyprm\",\"nodes_readme.md\":\"CHGy_go6\",\"nodes_route.md\":\"Bt9qH6OA\",\"nodes_sink.md\":\"yAf_z4wO\",\"nodes_source.md\":\"V_vlNfOz\",\"nodes_task.md\":\"Dk6VB7as\",\"nodes_transform.md\":\"Bv5fg2Xx\",\"nodes_try-catch.md\":\"DCYydDPm\",\"nodes_union.md\":\"CznVzHTK\",\"pipelines_crm-leads-sync.md\":\"BlZUnxYn\",\"pipelines_cross-workspace-csv-merge.md\":\"CsRE6GNe\",\"pipelines_movimenti-per-conto.md\":\"DRGfO1_5\",\"pipelines_orders-enriched-daily.md\":\"jESRtvBo\",\"pipelines_readme.md\":\"Ee6LS-SU\",\"pipelines_test-posta.md\":\"Cxo_DGBs\",\"runbooks_aggiornamento-pm2.md\":\"f3LAxif4\",\"runbooks_deployment.md\":\"DvIOOsoG\",\"runbooks_etl-worker.md\":\"Bu05cEgT\",\"runbooks_graph-server.md\":\"BOXZqdXC\",\"runbooks_mask-key.md\":\"nZkhAjBf\",\"runbooks_oauth-google-posta.md\":\"Bs7QTkmU\",\"runbooks_rollback-di-pipeline.md\":\"6US0Wsdc\",\"runbooks_scd2-rehash.md\":\"DtmuXA67\",\"runbooks_sql-task-truncate-swap.md\":\"C8viT-fp\",\"runbooks_stato-incrementale.md\":\"hGZ8FlbZ\",\"sub-pipelines_readme.md\":\"CF8gmNPU\",\"sub-pipelines_riepilogo-ordini.md\":\"qCBZJ4nh\",\"technical_overview.md\":\"DQP0pWc8\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"it-IT\",\"dir\":\"ltr\",\"title\":\"Noeva ETL\",\"titleTemplate\":\":title · Noeva ETL\",\"description\":\"Documentazione di Noeva ETL: come usare la piattaforma e come creare pipeline con Claude Code.\",\"base\":\"/guida/core/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":{\"light\":\"/logo-dark.png\",\"dark\":\"/logo-light.png\",\"alt\":\"Noeva\"},\"siteTitle\":false,\"footer\":{\"message\":\"Noeva è un marchio registrato di 4D S.R.L.\",\"copyright\":\"© 2026 4D S.R.L. · Gruppo4D\"},\"outline\":{\"level\":[2,3],\"label\":\"In questa pagina\"},\"docFooter\":{\"prev\":\"Pagina precedente\",\"next\":\"Pagina successiva\"},\"darkModeSwitchLabel\":\"Tema\",\"lightModeSwitchTitle\":\"Passa al tema chiaro\",\"darkModeSwitchTitle\":\"Passa al tema scuro\",\"sidebarMenuLabel\":\"Menu\",\"returnToTopLabel\":\"Torna su\",\"langMenuLabel\":\"Lingua\",\"notFound\":{\"title\":\"PAGINA NON TROVATA\",\"quote\":\"Il documento che cercavi non c'è più, o non è mai stato pubblicato qui.\",\"linkLabel\":\"Torna alla home\",\"linkText\":\"Torna alla home\"},\"search\":{\"provider\":\"local\",\"options\":{\"translations\":{\"button\":{\"buttonText\":\"Cerca\",\"buttonAriaLabel\":\"Cerca nella documentazione\"},\"modal\":{\"displayDetails\":\"Mostra i dettagli\",\"resetButtonTitle\":\"Azzera la ricerca\",\"backButtonTitle\":\"Chiudi la ricerca\",\"noResultsText\":\"Nessun risultato per\",\"footer\":{\"selectText\":\"per aprire\",\"selectKeyAriaLabel\":\"invio\",\"navigateText\":\"per spostarti\",\"navigateUpKeyAriaLabel\":\"freccia su\",\"navigateDownKeyAriaLabel\":\"freccia giù\",\"closeText\":\"per chiudere\",\"closeKeyAriaLabel\":\"esc\"}}}}},\"nav\":[{\"text\":\"Usare\",\"link\":\"/guide/usare/\",\"activeMatch\":\"^/guide/usare/\"},{\"text\":\"Creare con Claude Code\",\"link\":\"/guide/claude-code/\",\"activeMatch\":\"^/guide/claude-code/\"},{\"text\":\"Riferimento\",\"items\":[{\"text\":\"Il grafo, nodo per nodo\",\"link\":\"/guide/grafo\"},{\"text\":\"Tipi di nodo\",\"link\":\"/nodes/README\"},{\"text\":\"Connettori\",\"link\":\"/connectors/README\"},{\"text\":\"Pipeline pronte\",\"link\":\"/pipelines/README\"},{\"text\":\"Il report di run\",\"link\":\"/conventions/run-report\"},{\"text\":\"La traccia di una run\",\"link\":\"/conventions/run-trace\"},{\"text\":\"Variabili d'ambiente del core\",\"link\":\"/conventions/variabili-del-core\"},{\"text\":\"Operatività\",\"link\":\"/runbooks/graph-server\"}]}],\"sidebar\":[{\"text\":\"Usare Noeva ETL\",\"items\":[{\"text\":\"Come si usa\",\"link\":\"/guide/usare/\"},{\"text\":\"L'app desktop\",\"link\":\"/guide/usare/app-desktop\"},{\"text\":\"Leggere l'esito di una run\",\"link\":\"/guide/usare/esito-di-una-run\"},{\"text\":\"Panoramica di prodotto\",\"link\":\"/TECHNICAL_OVERVIEW\"}]},{\"text\":\"Creare con Claude Code\",\"items\":[{\"text\":\"Dal bisogno al processo\",\"link\":\"/guide/claude-code/\"},{\"text\":\"Comporre il prompt\",\"link\":\"/guide/claude-code/prompt\"},{\"text\":\"Skill e subagent\",\"link\":\"/guide/claude-code/strumenti\"},{\"text\":\"Guida allo sviluppo\",\"link\":\"/GUIDA_SVILUPPO\"}]},{\"text\":\"Concetti\",\"items\":[{\"text\":\"Il grafo, nodo per nodo\",\"link\":\"/guide/grafo\"},{\"text\":\"Il report di run\",\"link\":\"/conventions/run-report\"},{\"text\":\"La traccia di una run\",\"link\":\"/conventions/run-trace\"},{\"text\":\"Versioni di pipeline\",\"link\":\"/conventions/versioni-di-pipeline\"},{\"text\":\"Descriptor dei nodi\",\"link\":\"/conventions/node-descriptor\"},{\"text\":\"Colonne dei nodi\",\"link\":\"/conventions/node-columns\"},{\"text\":\"Variabili d'ambiente del core\",\"link\":\"/conventions/variabili-del-core\"}]},{\"text\":\"Tipi di nodo\",\"collapsed\":true,\"items\":[{\"text\":\"Cheatsheet\",\"link\":\"/nodes/README\"},{\"text\":\"action\",\"link\":\"/nodes/action\"},{\"text\":\"ai\",\"link\":\"/nodes/ai\"},{\"text\":\"join\",\"link\":\"/nodes/join\"},{\"text\":\"lookup\",\"link\":\"/nodes/lookup\"},{\"text\":\"pipeline\",\"link\":\"/nodes/pipeline\"},{\"text\":\"route\",\"link\":\"/nodes/route\"},{\"text\":\"sink\",\"link\":\"/nodes/sink\"},{\"text\":\"source\",\"link\":\"/nodes/source\"},{\"text\":\"task\",\"link\":\"/nodes/task\"},{\"text\":\"transform\",\"link\":\"/nodes/transform\"},{\"text\":\"try-catch\",\"link\":\"/nodes/try-catch\"},{\"text\":\"union\",\"link\":\"/nodes/union\"}]},{\"text\":\"Connettori\",\"collapsed\":true,\"items\":[{\"text\":\"Panoramica\",\"link\":\"/connectors/README\"},{\"text\":\"File (storage × codec)\",\"link\":\"/connectors/file\"},{\"text\":\"HTTP (API REST per i nodi lookup e action)\",\"link\":\"/connectors/http\"},{\"text\":\"IMAP (caselle di posta)\",\"link\":\"/connectors/imap\"},{\"text\":\"Jira Cloud (issue da una JQL o per chiave, liste di una issue, creazione, aggiornamento, transizioni, upsert, commenti, worklog e link)\",\"link\":\"/connectors/jira\"},{\"text\":\"Noeva (file dei workspace)\",\"link\":\"/connectors/noeva\"},{\"text\":\"OAuth2 per i connettori di posta\",\"link\":\"/connectors/oauth\"},{\"text\":\"PostgreSQL\",\"link\":\"/connectors/postgres\"},{\"text\":\"processo esterno\",\"link\":\"/connectors/process\"},{\"text\":\"SendGrid (mail via API REST)\",\"link\":\"/connectors/sendgrid\"},{\"text\":\"SMTP (notifiche email)\",\"link\":\"/connectors/smtp\"},{\"text\":\"SQL Server\",\"link\":\"/connectors/sqlserver\"}]},{\"text\":\"Pipeline pronte\",\"collapsed\":true,\"items\":[{\"text\":\"Le schede di una pipeline\",\"link\":\"/pipelines/README\"},{\"text\":\"test-posta\",\"link\":\"/pipelines/test-posta\"}]},{\"text\":\"Esempi\",\"collapsed\":true,\"items\":[{\"text\":\"Le schede di una sub-pipeline\",\"link\":\"/sub-pipelines/README\"},{\"text\":\"crm-leads-sync\",\"link\":\"/pipelines/crm-leads-sync\"},{\"text\":\"cross-workspace-csv-merge\",\"link\":\"/pipelines/cross-workspace-csv-merge\"},{\"text\":\"movimenti-per-conto\",\"link\":\"/pipelines/movimenti-per-conto\"},{\"text\":\"orders-enriched-daily\",\"link\":\"/pipelines/orders-enriched-daily\"},{\"text\":\"riepilogo-ordini\",\"link\":\"/sub-pipelines/riepilogo-ordini\"}]},{\"text\":\"Operatività\",\"collapsed\":true,\"items\":[{\"text\":\"aggiornare un deploy PM2 di un repo cliente\",\"link\":\"/runbooks/aggiornamento-pm2\"},{\"text\":\"distribuzione del runner ETL\",\"link\":\"/runbooks/deployment\"},{\"text\":\"worker etl worker (polling su processes)\",\"link\":\"/runbooks/etl-worker\"},{\"text\":\"server grafi etl serve (HTTP)\",\"link\":\"/runbooks/graph-server\"},{\"text\":\"chiavi di mask (creazione, rotazione, compromissione)\",\"link\":\"/runbooks/mask-key\"},{\"text\":\"OAuth2 per una casella Google (IMAP + SMTP)\",\"link\":\"/runbooks/oauth-google-posta\"},{\"text\":\"rollback di una pipeline\",\"link\":\"/runbooks/rollback-di-pipeline\"},{\"text\":\"rehash di una dimensione storicizzata\",\"link\":\"/runbooks/scd2-rehash\"},{\"text\":\"task SQL, truncate e scambio di tabelle\",\"link\":\"/runbooks/sql-task-truncate-swap\"},{\"text\":\"stato di pipeline e watermark\",\"link\":\"/runbooks/stato-incrementale\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
21
+ <script>window.__VP_HASH_MAP__=JSON.parse("{\"connectors_file.md\":\"B1NJe0VJ\",\"connectors_http.md\":\"B8utPijY\",\"connectors_imap.md\":\"CMMpZVXn\",\"connectors_jira.md\":\"0DJvrRXH\",\"connectors_noeva.md\":\"DkxCC8Ey\",\"connectors_oauth.md\":\"DUHajB0u\",\"connectors_postgres.md\":\"DPpHqXkc\",\"connectors_process.md\":\"lQLmWbGN\",\"connectors_readme.md\":\"ChyXSf73\",\"connectors_sendgrid.md\":\"dJzIWepq\",\"connectors_smtp.md\":\"DXXvaNxD\",\"connectors_sqlserver.md\":\"D1sYNLEq\",\"conventions_node-columns.md\":\"D9K1peUx\",\"conventions_node-descriptor.md\":\"D8Si7E2S\",\"conventions_run-report.md\":\"D_pG07VG\",\"conventions_run-trace.md\":\"nKS_RgLC\",\"conventions_variabili-del-core.md\":\"BU6BD6w_\",\"conventions_versioni-di-pipeline.md\":\"cy5nsizS\",\"guida_sviluppo.md\":\"D13C7Zwu\",\"guide_claude-code_index.md\":\"CxVSru8e\",\"guide_claude-code_prompt.md\":\"C7uETA9W\",\"guide_claude-code_strumenti.md\":\"BWhQnAlY\",\"guide_grafo.md\":\"Dy8_YMeh\",\"guide_usare_app-desktop.md\":\"CcDu8cJL\",\"guide_usare_esito-di-una-run.md\":\"DkvAOPBE\",\"guide_usare_index.md\":\"BJqi3P7J\",\"index.md\":\"kMhsF-sv\",\"nodes_action.md\":\"DOsTbV-i\",\"nodes_ai.md\":\"CVtP9gEJ\",\"nodes_join.md\":\"DSYbIDG6\",\"nodes_lookup.md\":\"BI8tgBIq\",\"nodes_pipeline.md\":\"DIMlyprm\",\"nodes_readme.md\":\"CHGy_go6\",\"nodes_route.md\":\"Bt9qH6OA\",\"nodes_sink.md\":\"yAf_z4wO\",\"nodes_source.md\":\"V_vlNfOz\",\"nodes_task.md\":\"Dk6VB7as\",\"nodes_transform.md\":\"Bv5fg2Xx\",\"nodes_try-catch.md\":\"DCYydDPm\",\"nodes_union.md\":\"CznVzHTK\",\"pipelines_crm-leads-sync.md\":\"BlZUnxYn\",\"pipelines_cross-workspace-csv-merge.md\":\"CsRE6GNe\",\"pipelines_movimenti-per-conto.md\":\"DRGfO1_5\",\"pipelines_orders-enriched-daily.md\":\"jESRtvBo\",\"pipelines_readme.md\":\"Ee6LS-SU\",\"pipelines_test-posta.md\":\"Cxo_DGBs\",\"runbooks_aggiornamento-pm2.md\":\"f3LAxif4\",\"runbooks_deployment.md\":\"DvIOOsoG\",\"runbooks_etl-worker.md\":\"Bu05cEgT\",\"runbooks_graph-server.md\":\"BOXZqdXC\",\"runbooks_mask-key.md\":\"nZkhAjBf\",\"runbooks_oauth-google-posta.md\":\"Bs7QTkmU\",\"runbooks_rollback-di-pipeline.md\":\"6US0Wsdc\",\"runbooks_scd2-rehash.md\":\"DtmuXA67\",\"runbooks_sql-task-truncate-swap.md\":\"C8viT-fp\",\"runbooks_stato-incrementale.md\":\"hGZ8FlbZ\",\"sub-pipelines_readme.md\":\"CF8gmNPU\",\"sub-pipelines_riepilogo-ordini.md\":\"qCBZJ4nh\",\"technical_overview.md\":\"DQP0pWc8\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"it-IT\",\"dir\":\"ltr\",\"title\":\"Noeva ETL\",\"titleTemplate\":\":title · Noeva ETL\",\"description\":\"Documentazione di Noeva ETL: come usare la piattaforma e come creare pipeline con Claude Code.\",\"base\":\"/guida/core/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":{\"light\":\"/logo-dark.png\",\"dark\":\"/logo-light.png\",\"alt\":\"Noeva\"},\"siteTitle\":false,\"footer\":{\"message\":\"Noeva è un marchio registrato di 4D S.R.L.\",\"copyright\":\"© 2026 4D S.R.L. · Gruppo4D\"},\"outline\":{\"level\":[2,3],\"label\":\"In questa pagina\"},\"docFooter\":{\"prev\":\"Pagina precedente\",\"next\":\"Pagina successiva\"},\"darkModeSwitchLabel\":\"Tema\",\"lightModeSwitchTitle\":\"Passa al tema chiaro\",\"darkModeSwitchTitle\":\"Passa al tema scuro\",\"sidebarMenuLabel\":\"Menu\",\"returnToTopLabel\":\"Torna su\",\"langMenuLabel\":\"Lingua\",\"notFound\":{\"title\":\"PAGINA NON TROVATA\",\"quote\":\"Il documento che cercavi non c'è più, o non è mai stato pubblicato qui.\",\"linkLabel\":\"Torna alla home\",\"linkText\":\"Torna alla home\"},\"search\":{\"provider\":\"local\",\"options\":{\"translations\":{\"button\":{\"buttonText\":\"Cerca\",\"buttonAriaLabel\":\"Cerca nella documentazione\"},\"modal\":{\"displayDetails\":\"Mostra i dettagli\",\"resetButtonTitle\":\"Azzera la ricerca\",\"backButtonTitle\":\"Chiudi la ricerca\",\"noResultsText\":\"Nessun risultato per\",\"footer\":{\"selectText\":\"per aprire\",\"selectKeyAriaLabel\":\"invio\",\"navigateText\":\"per spostarti\",\"navigateUpKeyAriaLabel\":\"freccia su\",\"navigateDownKeyAriaLabel\":\"freccia giù\",\"closeText\":\"per chiudere\",\"closeKeyAriaLabel\":\"esc\"}}}}},\"nav\":[{\"text\":\"Usare\",\"link\":\"/guide/usare/\",\"activeMatch\":\"^/guide/usare/\"},{\"text\":\"Creare con Claude Code\",\"link\":\"/guide/claude-code/\",\"activeMatch\":\"^/guide/claude-code/\"},{\"text\":\"Riferimento\",\"items\":[{\"text\":\"Il grafo, nodo per nodo\",\"link\":\"/guide/grafo\"},{\"text\":\"Tipi di nodo\",\"link\":\"/nodes/README\"},{\"text\":\"Connettori\",\"link\":\"/connectors/README\"},{\"text\":\"Pipeline pronte\",\"link\":\"/pipelines/README\"},{\"text\":\"Il report di run\",\"link\":\"/conventions/run-report\"},{\"text\":\"La traccia di una run\",\"link\":\"/conventions/run-trace\"},{\"text\":\"Variabili d'ambiente del core\",\"link\":\"/conventions/variabili-del-core\"},{\"text\":\"Operatività\",\"link\":\"/runbooks/graph-server\"}]}],\"sidebar\":[{\"text\":\"Usare Noeva ETL\",\"items\":[{\"text\":\"Come si usa\",\"link\":\"/guide/usare/\"},{\"text\":\"L'app desktop\",\"link\":\"/guide/usare/app-desktop\"},{\"text\":\"Leggere l'esito di una run\",\"link\":\"/guide/usare/esito-di-una-run\"},{\"text\":\"Panoramica di prodotto\",\"link\":\"/TECHNICAL_OVERVIEW\"}]},{\"text\":\"Creare con Claude Code\",\"items\":[{\"text\":\"Dal bisogno al processo\",\"link\":\"/guide/claude-code/\"},{\"text\":\"Comporre il prompt\",\"link\":\"/guide/claude-code/prompt\"},{\"text\":\"Skill e subagent\",\"link\":\"/guide/claude-code/strumenti\"},{\"text\":\"Guida allo sviluppo\",\"link\":\"/GUIDA_SVILUPPO\"}]},{\"text\":\"Concetti\",\"items\":[{\"text\":\"Il grafo, nodo per nodo\",\"link\":\"/guide/grafo\"},{\"text\":\"Il report di run\",\"link\":\"/conventions/run-report\"},{\"text\":\"La traccia di una run\",\"link\":\"/conventions/run-trace\"},{\"text\":\"Versioni di pipeline\",\"link\":\"/conventions/versioni-di-pipeline\"},{\"text\":\"Descriptor dei nodi\",\"link\":\"/conventions/node-descriptor\"},{\"text\":\"Colonne dei nodi\",\"link\":\"/conventions/node-columns\"},{\"text\":\"Variabili d'ambiente del core\",\"link\":\"/conventions/variabili-del-core\"}]},{\"text\":\"Tipi di nodo\",\"collapsed\":true,\"items\":[{\"text\":\"Cheatsheet\",\"link\":\"/nodes/README\"},{\"text\":\"action\",\"link\":\"/nodes/action\"},{\"text\":\"ai\",\"link\":\"/nodes/ai\"},{\"text\":\"join\",\"link\":\"/nodes/join\"},{\"text\":\"lookup\",\"link\":\"/nodes/lookup\"},{\"text\":\"pipeline\",\"link\":\"/nodes/pipeline\"},{\"text\":\"route\",\"link\":\"/nodes/route\"},{\"text\":\"sink\",\"link\":\"/nodes/sink\"},{\"text\":\"source\",\"link\":\"/nodes/source\"},{\"text\":\"task\",\"link\":\"/nodes/task\"},{\"text\":\"transform\",\"link\":\"/nodes/transform\"},{\"text\":\"try-catch\",\"link\":\"/nodes/try-catch\"},{\"text\":\"union\",\"link\":\"/nodes/union\"}]},{\"text\":\"Connettori\",\"collapsed\":true,\"items\":[{\"text\":\"Panoramica\",\"link\":\"/connectors/README\"},{\"text\":\"File (storage × codec)\",\"link\":\"/connectors/file\"},{\"text\":\"HTTP (API REST per i nodi lookup e action)\",\"link\":\"/connectors/http\"},{\"text\":\"IMAP (caselle di posta)\",\"link\":\"/connectors/imap\"},{\"text\":\"Jira Cloud (issue da una JQL o per chiave, liste di una issue, creazione, aggiornamento, transizioni, upsert, commenti, worklog e link)\",\"link\":\"/connectors/jira\"},{\"text\":\"Noeva (file dei workspace)\",\"link\":\"/connectors/noeva\"},{\"text\":\"OAuth2 per i connettori di posta\",\"link\":\"/connectors/oauth\"},{\"text\":\"PostgreSQL\",\"link\":\"/connectors/postgres\"},{\"text\":\"processo esterno\",\"link\":\"/connectors/process\"},{\"text\":\"SendGrid (mail via API REST)\",\"link\":\"/connectors/sendgrid\"},{\"text\":\"SMTP (notifiche email)\",\"link\":\"/connectors/smtp\"},{\"text\":\"SQL Server\",\"link\":\"/connectors/sqlserver\"}]},{\"text\":\"Pipeline pronte\",\"collapsed\":true,\"items\":[{\"text\":\"Le schede di una pipeline\",\"link\":\"/pipelines/README\"},{\"text\":\"test-posta\",\"link\":\"/pipelines/test-posta\"}]},{\"text\":\"Esempi\",\"collapsed\":true,\"items\":[{\"text\":\"Le schede di una sub-pipeline\",\"link\":\"/sub-pipelines/README\"},{\"text\":\"crm-leads-sync\",\"link\":\"/pipelines/crm-leads-sync\"},{\"text\":\"cross-workspace-csv-merge\",\"link\":\"/pipelines/cross-workspace-csv-merge\"},{\"text\":\"movimenti-per-conto\",\"link\":\"/pipelines/movimenti-per-conto\"},{\"text\":\"orders-enriched-daily\",\"link\":\"/pipelines/orders-enriched-daily\"},{\"text\":\"riepilogo-ordini\",\"link\":\"/sub-pipelines/riepilogo-ordini\"}]},{\"text\":\"Operatività\",\"collapsed\":true,\"items\":[{\"text\":\"aggiornare un deploy PM2 di un repo cliente\",\"link\":\"/runbooks/aggiornamento-pm2\"},{\"text\":\"distribuzione del runner ETL\",\"link\":\"/runbooks/deployment\"},{\"text\":\"worker etl worker (polling su processes)\",\"link\":\"/runbooks/etl-worker\"},{\"text\":\"server grafi etl serve (HTTP)\",\"link\":\"/runbooks/graph-server\"},{\"text\":\"chiavi di mask (creazione, rotazione, compromissione)\",\"link\":\"/runbooks/mask-key\"},{\"text\":\"OAuth2 per una casella Google (IMAP + SMTP)\",\"link\":\"/runbooks/oauth-google-posta\"},{\"text\":\"rollback di una pipeline\",\"link\":\"/runbooks/rollback-di-pipeline\"},{\"text\":\"rehash di una dimensione storicizzata\",\"link\":\"/runbooks/scd2-rehash\"},{\"text\":\"task SQL, truncate e scambio di tabelle\",\"link\":\"/runbooks/sql-task-truncate-swap\"},{\"text\":\"stato di pipeline e watermark\",\"link\":\"/runbooks/stato-incrementale\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
22
22
 
23
23
  </body>
24
24
  </html>
@@ -9,11 +9,11 @@
9
9
  <link rel="preload stylesheet" href="/guida/core/assets/style.BNn_AkzN.css" as="style">
10
10
  <link rel="preload stylesheet" href="/guida/core/vp-icons.css" as="style">
11
11
 
12
- <script type="module" src="/guida/core/assets/app.vAJRZtow.js"></script>
12
+ <script type="module" src="/guida/core/assets/app.BMz6ZZYF.js"></script>
13
13
  <link rel="preload" href="/guida/core/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
14
- <link rel="modulepreload" href="/guida/core/assets/chunks/theme.Bq6mfDhZ.js">
14
+ <link rel="modulepreload" href="/guida/core/assets/chunks/theme.DV62mViB.js">
15
15
  <link rel="modulepreload" href="/guida/core/assets/chunks/framework.qdetmeNX.js">
16
- <link rel="modulepreload" href="/guida/core/assets/GUIDA_SVILUPPO.md.Dj20s7gS.lean.js">
16
+ <link rel="modulepreload" href="/guida/core/assets/GUIDA_SVILUPPO.md.D13C7Zwu.lean.js">
17
17
  <link rel="icon" type="image/svg+xml" href="/guida/core/favicon.svg">
18
18
  <meta name="theme-color" content="#0a0e15">
19
19
  <script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
@@ -35,7 +35,7 @@
35
35
  <span class="line"><span>AGENTS.md # le istruzioni per l&#39;agente, con il blocco del kit</span></span>
36
36
  <span class="line"><span>.github/workflows/ci.yml # la CI: il setup, poi `etl ci`</span></span>
37
37
  <span class="line"><span>.github/workflows/image.yml # l&#39;immagine del deploy, a mano o su tag</span></span>
38
- <span class="line"><span>ecosystem.config.cjs # una riga: il deploy sotto PM2</span></span></code></pre></div><p><strong>Crearlo.</strong> <code>etl init &lt;slug&gt;</code> scrive nella cartella corrente il boilerplate del pacchetto, poi lancia <code>git init</code> con un primo commit e crea i branch <code>dev</code>, <code>staging</code> e <code>main</code>, con <code>HEAD</code> su <code>dev</code>. La cartella dev&#39;essere vuota: altrimenti il comando si ferma con exit <code>2</code> senza scrivere niente, e lo stesso vale per uno slug che non è fatto di minuscole, cifre e trattini. Senza un&#39;identità di git si ferma prima di scrivere, con exit <code>1</code>. Non crea il repo su GitHub né il secret del PAT, che restano a mano. Il boilerplate è magro, perché ciò che deve evolvere arriva per dipendenza:</p><table tabindex="0"><thead><tr><th>File</th><th>Cosa contiene</th></tr></thead><tbody><tr><td><code>package.json</code></td><td><code>noeva-etl-&lt;slug&gt;</code>, ESM, il core alla versione che genera il repo, il <code>packageManager</code> del core, gli alias <code>pipeline:*</code> e la toolchain nelle <code>devDependencies</code></td></tr><tr><td><code>etl.config.ts</code></td><td><code>client</code> e il catalogo vuoto</td></tr><tr><td><code>.env.example</code></td><td>le sole variabili obbligatorie del core (<code>NOEVA_API_BASE_URL</code>, <code>NOEVA_API_KEY</code>, <code>NOEVA_WORKSPACE_ID</code>)</td></tr><tr><td><code>.npmrc</code></td><td>il registry di <code>@my-ginkgo</code> su GitHub Packages, senza token</td></tr><tr><td><code>tsconfig.json</code>, <code>eslint.config.js</code>, <code>vitest.config.ts</code></td><td>una riga sul preset</td></tr><tr><td><code>.gitignore</code></td><td><code>.env</code>, <code>.runs/</code>, <code>.state/</code>, <code>logs/</code> di PM2, il sito costruito, la sua cache e i file temporanei di VitePress, <code>docs/catalogo.md</code></td></tr><tr><td><code>.prettierignore</code></td><td>il lockfile e gli snapshot del piano, che <code>etl versions snapshot</code> scrive con la sua formattazione</td></tr><tr><td><code>src/pipelines/</code>, <code>docs/pipelines/</code></td><td>vuote: le cartelle delle pipeline e le loro schede</td></tr><tr><td><code>AGENTS.md</code>, <code>CLAUDE.md</code></td><td>le istruzioni per l&#39;agente, con il blocco gestito dal core; <code>CLAUDE.md</code> è solo <code>@AGENTS.md</code></td></tr><tr><td><code>.claude/</code></td><td>file gestiti: il kit dell&#39;agente in <code>skills/</code>, <code>agents/</code> e <code>hooks/</code> <code>noeva-etl-*</code>, e la voce dell&#39;hook in <code>settings.json</code> (§10)</td></tr><tr><td><code>.github/workflows/ci.yml</code></td><td>file gestito: checkout con <code>fetch-depth: 0</code>, pnpm e node, install col PAT nel secret <code>NOEVA_ETL_PACKAGES_TOKEN</code>, poi <code>pnpm exec etl ci</code></td></tr><tr><td><code>.github/workflows/image.yml</code></td><td>file gestito: l&#39;immagine col Dockerfile del pacchetto, su <code>ghcr.io/&lt;owner&gt;/noeva-etl-&lt;slug&gt;</code> con tag = SHA, a mano o su tag; il PAT come BuildKit secret</td></tr><tr><td><code>ecosystem.config.cjs</code></td><td>file gestito: una riga su <code>ecosystem()</code> di <code>@noeva/etl-core/pm2</code>, che avvia <code>etl serve</code> sotto PM2</td></tr></tbody></table><p><strong>La toolchain</strong> sta nelle <code>devDependencies</code> del repo: <code>vitest</code>, <code>eslint</code>, <code>typescript</code>, <code>prettier</code> e <code>@types/node</code>, con i range che <code>etl init</code> legge dal <code>package.json</code> del core installato. Con pnpm le dipendenze del core non si vedono dal repo, e senza <code>vitest</code> e <code>@types/node</code> installati lì <code>tsc --noEmit</code> non trova i tipi dei test; con gli stessi range pnpm tiene una sola copia per il core e per il repo. Li riallinea <code>etl upgrade</code> a ogni bump, coi range del core nuovo.</p><p><strong>La CI.</strong> <code>ci.yml</code> non usa workflow riusabili dell&#39;org, così regge al transfer del repo, e gira sulle PR verso <code>dev</code> e <code>main</code> e sui push su <code>main</code>. Il secret <code>NOEVA_ETL_PACKAGES_TOKEN</code> del repo cliente è un <strong>PAT classic <code>read:packages</code></strong> dell&#39;utente invitato, che serve solo a installare il core. Nel repo del core lo stesso nome indica un PAT <code>write:packages</code>, che pubblica il pacchetto: non è lo stesso token.</p><p><strong>I file gestiti.</strong> Il blocco di <code>AGENTS.md</code>, fra <code>&lt;!-- noeva-etl:inizio … --&gt;</code> e <code>&lt;!-- noeva-etl:fine --&gt;</code>, lo scrive <code>etl agent sync</code>; il resto del file è del repo. Dice all&#39;agente di lanciare <code>etl upgrade --check</code> prima di ogni nuovo sviluppo, di leggere il changelog del core prima di ogni bump, e porta le regole su doc nello stesso commit, <code>--realign</code> e i tre rollback. I file gestiti che <code>etl init</code> scrive sono i due YAML (<code>ci.yml</code> e <code>image.yml</code>), <code>ecosystem.config.cjs</code>, il kit dell&#39;agente in <code>.claude/{skills,agents,hooks}/noeva-etl-*</code> con la voce dell&#39;hook in <code>.claude/settings.json</code> (§10), e il blocco di <code>AGENTS.md</code>; tutto il resto è del repo. Un file gestito che il repo vuole tenersi si dichiara in <code>etl.config.ts</code> con <code>unmanaged: [&quot;.github/workflows/ci.yml&quot;]</code> (per il kit, la cartella di una skill, il file di un subagent, <code>AGENTS.md</code> per il blocco o <code>.claude/settings.json</code> per la voce dell&#39;hook), e da lì l&#39;aggiornamento è del repo. <code>image.yml</code> costruisce l&#39;immagine del deploy col Dockerfile del pacchetto (<a href="./runbooks/deployment#immagine-del-repo-cliente">Deploy § Immagine del repo cliente</a>), e <code>ecosystem.config.cjs</code> è la riga che avvia <code>etl serve</code> sotto PM2 (<a href="./runbooks/aggiornamento-pm2">Aggiornare un deploy PM2</a>).</p><p><strong>Il catalogo.</strong> <code>etl.config.ts</code> esporta <code>defineEtlConfig({ client, pipelines })</code>: <code>client</code> è lo slug del cliente, <code>pipelines</code> le pipeline importate come valori. Ogni comando che lavora sulle pipeline (<code>list</code>, <code>plan</code>, <code>run</code>, <code>state</code>, <code>versions</code>, <code>env</code>, <code>catalog</code>, <code>docs</code>, <code>ci</code>, <code>serve</code>, <code>worker</code>) legge questo file: la CLI lo cerca risalendo dalla cartella corrente, e <code>--config &lt;file&gt;</code> lo indica a mano. Il TypeScript gira dai sorgenti con <code>tsx</code>, quindi il <code>package.json</code> del repo dichiara <code>&quot;type&quot;: &quot;module&quot;</code>. Un config assente o che non si importa, un export di forma sbagliata, una voce che non è una <code>RunnablePipeline</code>, un nome ripetuto (anche fra pipeline e sub-pipeline) o un <code>client</code> che non è uno slug fermano il comando con exit <code>2</code> e un errore che nomina la causa; un catalogo vuoto è permesso, con un avviso. Grafi, dispatch del worker e annuncio del catalogo a noeva-server vedono le stesse pipeline: non c&#39;è un registro a parte.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// etl.config.ts</span></span>
38
+ <span class="line"><span>ecosystem.config.cjs # una riga: il deploy sotto PM2</span></span></code></pre></div><p><strong>Crearlo.</strong> <code>etl init &lt;slug&gt;</code> scrive nella cartella corrente il boilerplate del pacchetto, poi lancia <code>git init</code> con un primo commit e crea i branch <code>dev</code>, <code>staging</code> e <code>main</code>, con <code>HEAD</code> su <code>dev</code>. La cartella dev&#39;essere vuota: altrimenti il comando si ferma con exit <code>2</code> senza scrivere niente, e lo stesso vale per uno slug che non è fatto di minuscole, cifre e trattini. Senza un&#39;identità di git si ferma prima di scrivere, con exit <code>1</code>. Non crea il repo su GitHub né il secret del PAT, che restano a mano. Il boilerplate è magro, perché ciò che deve evolvere arriva per dipendenza:</p><table tabindex="0"><thead><tr><th>File</th><th>Cosa contiene</th></tr></thead><tbody><tr><td><code>package.json</code></td><td><code>noeva-etl-&lt;slug&gt;</code>, ESM, il core alla versione che genera il repo, il pnpm del core (fissato nel codice di <code>etl init</code>), gli alias <code>pipeline:*</code> e la toolchain nelle <code>devDependencies</code></td></tr><tr><td><code>etl.config.ts</code></td><td><code>client</code> e il catalogo vuoto</td></tr><tr><td><code>.env.example</code></td><td>le sole variabili obbligatorie del core (<code>NOEVA_API_BASE_URL</code>, <code>NOEVA_API_KEY</code>, <code>NOEVA_WORKSPACE_ID</code>)</td></tr><tr><td><code>.npmrc</code></td><td>il registry di <code>@my-ginkgo</code> su GitHub Packages, senza token</td></tr><tr><td><code>tsconfig.json</code>, <code>eslint.config.js</code>, <code>vitest.config.ts</code></td><td>una riga sul preset</td></tr><tr><td><code>.gitignore</code></td><td><code>.env</code>, <code>.runs/</code>, <code>.state/</code>, <code>logs/</code> di PM2, il sito costruito, la sua cache e i file temporanei di VitePress, <code>docs/catalogo.md</code></td></tr><tr><td><code>.prettierignore</code></td><td>il lockfile e gli snapshot del piano, che <code>etl versions snapshot</code> scrive con la sua formattazione</td></tr><tr><td><code>src/pipelines/</code>, <code>docs/pipelines/</code></td><td>vuote: le cartelle delle pipeline e le loro schede</td></tr><tr><td><code>AGENTS.md</code>, <code>CLAUDE.md</code></td><td>le istruzioni per l&#39;agente, con il blocco gestito dal core; <code>CLAUDE.md</code> è solo <code>@AGENTS.md</code></td></tr><tr><td><code>.claude/</code></td><td>file gestiti: il kit dell&#39;agente in <code>skills/</code>, <code>agents/</code> e <code>hooks/</code> <code>noeva-etl-*</code>, e la voce dell&#39;hook in <code>settings.json</code> (§10)</td></tr><tr><td><code>.github/workflows/ci.yml</code></td><td>file gestito: checkout con <code>fetch-depth: 0</code>, pnpm e node, install col PAT nel secret <code>NOEVA_ETL_PACKAGES_TOKEN</code>, poi <code>pnpm exec etl ci</code></td></tr><tr><td><code>.github/workflows/image.yml</code></td><td>file gestito: l&#39;immagine col Dockerfile del pacchetto, su <code>ghcr.io/&lt;owner&gt;/noeva-etl-&lt;slug&gt;</code> con tag = SHA, a mano o su tag; il PAT come BuildKit secret</td></tr><tr><td><code>ecosystem.config.cjs</code></td><td>file gestito: una riga su <code>ecosystem()</code> di <code>@noeva/etl-core/pm2</code>, che avvia <code>etl serve</code> sotto PM2</td></tr></tbody></table><p><strong>La toolchain</strong> sta nelle <code>devDependencies</code> del repo: <code>vitest</code>, <code>eslint</code>, <code>typescript</code>, <code>prettier</code> e <code>@types/node</code>, con i range che <code>etl init</code> legge dal <code>package.json</code> del core installato. Con pnpm le dipendenze del core non si vedono dal repo, e senza <code>vitest</code> e <code>@types/node</code> installati lì <code>tsc --noEmit</code> non trova i tipi dei test; con gli stessi range pnpm tiene una sola copia per il core e per il repo. Li riallinea <code>etl upgrade</code> a ogni bump, coi range del core nuovo.</p><p><strong>La CI.</strong> <code>ci.yml</code> non usa workflow riusabili dell&#39;org, così regge al transfer del repo, e gira sulle PR verso <code>dev</code> e <code>main</code> e sui push su <code>main</code>. Il secret <code>NOEVA_ETL_PACKAGES_TOKEN</code> del repo cliente è un <strong>PAT classic <code>read:packages</code></strong> dell&#39;utente invitato, che serve solo a installare il core. Nel repo del core lo stesso nome indica un PAT <code>write:packages</code>, che pubblica il pacchetto: non è lo stesso token.</p><p><strong>I file gestiti.</strong> Il blocco di <code>AGENTS.md</code>, fra <code>&lt;!-- noeva-etl:inizio … --&gt;</code> e <code>&lt;!-- noeva-etl:fine --&gt;</code>, lo scrive <code>etl agent sync</code>; il resto del file è del repo. Dice all&#39;agente di lanciare <code>etl upgrade --check</code> prima di ogni nuovo sviluppo, di leggere il changelog del core prima di ogni bump, e porta le regole su doc nello stesso commit, <code>--realign</code> e i tre rollback. I file gestiti che <code>etl init</code> scrive sono i due YAML (<code>ci.yml</code> e <code>image.yml</code>), <code>ecosystem.config.cjs</code>, il kit dell&#39;agente in <code>.claude/{skills,agents,hooks}/noeva-etl-*</code> con la voce dell&#39;hook in <code>.claude/settings.json</code> (§10), e il blocco di <code>AGENTS.md</code>; tutto il resto è del repo. Un file gestito che il repo vuole tenersi si dichiara in <code>etl.config.ts</code> con <code>unmanaged: [&quot;.github/workflows/ci.yml&quot;]</code> (per il kit, la cartella di una skill, il file di un subagent, <code>AGENTS.md</code> per il blocco o <code>.claude/settings.json</code> per la voce dell&#39;hook), e da lì l&#39;aggiornamento è del repo. <code>image.yml</code> costruisce l&#39;immagine del deploy col Dockerfile del pacchetto (<a href="./runbooks/deployment#immagine-del-repo-cliente">Deploy § Immagine del repo cliente</a>), e <code>ecosystem.config.cjs</code> è la riga che avvia <code>etl serve</code> sotto PM2 (<a href="./runbooks/aggiornamento-pm2">Aggiornare un deploy PM2</a>).</p><p><strong>Il catalogo.</strong> <code>etl.config.ts</code> esporta <code>defineEtlConfig({ client, pipelines })</code>: <code>client</code> è lo slug del cliente, <code>pipelines</code> le pipeline importate come valori. Ogni comando che lavora sulle pipeline (<code>list</code>, <code>plan</code>, <code>run</code>, <code>state</code>, <code>versions</code>, <code>env</code>, <code>catalog</code>, <code>docs</code>, <code>ci</code>, <code>serve</code>, <code>worker</code>) legge questo file: la CLI lo cerca risalendo dalla cartella corrente, e <code>--config &lt;file&gt;</code> lo indica a mano. Il TypeScript gira dai sorgenti con <code>tsx</code>, quindi il <code>package.json</code> del repo dichiara <code>&quot;type&quot;: &quot;module&quot;</code>. Un config assente o che non si importa, un export di forma sbagliata, una voce che non è una <code>RunnablePipeline</code>, un nome ripetuto (anche fra pipeline e sub-pipeline) o un <code>client</code> che non è uno slug fermano il comando con exit <code>2</code> e un errore che nomina la causa; un catalogo vuoto è permesso, con un avviso. Grafi, dispatch del worker e annuncio del catalogo a noeva-server vedono le stesse pipeline: non c&#39;è un registro a parte.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// etl.config.ts</span></span>
39
39
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineEtlConfig } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@noeva/etl-core&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
40
40
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { testPosta } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@noeva/etl-core/pipelines&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
41
41
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { fattureDaily } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;./src/pipelines/fatture-daily/run.js&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
@@ -74,7 +74,7 @@
74
74
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> docs</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # lo stesso sito in sviluppo</span></span>
75
75
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> serve</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # grafi via HTTP + worker</span></span>
76
76
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> worker</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # solo il daemon su processes</span></span></code></pre></div><p><strong><code>etl ci</code></strong> è il gate del repo, lo stesso in locale e nella CI. Esegue, in quest&#39;ordine, <code>tsc --noEmit</code>, ESLint (<code>lint</code>), Prettier in <code>--check</code> (<code>format</code>), vitest con <code>--passWithNoTests</code> (<code>test</code>), <code>etl versions check</code>, <code>etl catalog check</code> ed <code>etl docs build</code>. Su stderr ogni fase si annuncia con <code>▶ &lt;fase&gt;</code>, e la prima che fallisce ferma il gate: <code>etl ci: la fase «&lt;fase&gt;» è fallita</code>, con l&#39;exit code della fase. Gli strumenti sono quelli installati nel repo, o in mancanza quelli fra le dipendenze del core; i comandi <code>etl</code> girano in processo sul catalogo già caricato. Un catalogo vuoto passa, con l&#39;avviso del caricamento, e un repo appena creato senza test pure; senza <code>origin/dev</code>, prima del primo push, il gate delle versioni dà l&#39;avviso «nessuna base» e controlla solo gli snapshot (vedi <a href="./conventions/versioni-di-pipeline">Versioni di pipeline</a>). Quali fasi girano arriva con il bump del core, mentre <code>ci.yml</code> resta fermo. Prima delle fasi <code>etl ci</code> guarda l&#39;ultima versione del core sul registry: un core non aggiornato è un avviso (<code>Avviso: il core installato è …</code>) e mai un errore, così un commit vecchio non diventa rosso perché è uscita una release; anche un registry che non risponde è solo un avviso.</p><p><strong><code>etl upgrade --check</code></strong> è in sola lettura, e il blocco di <code>AGENTS.md</code> lo chiede prima di ogni nuovo sviluppo. Su stdout dà la versione del core installata e l&#39;ultima sul registry, le sezioni del <code>CHANGELOG.md</code> del core fra le due, lette dal tarball della versione nuova senza installarla, con le major (<code>[MAJOR]</code>) e le voci «Cambia il piano» (<code>[CAMBIA IL PIANO]</code>) in evidenza in testa, e la deriva dei file gestiti: <code>modificato</code> (diverso dal template del core installato), <code>mancante</code> o <code>in più</code> (un file sotto <code>noeva-etl-*</code> che il kit non porta), con <code>saltato</code> per quelli in <code>unmanaged</code>. Per <code>AGENTS.md</code> e <code>.claude/settings.json</code> conta solo la parte gestita, il blocco e la voce dell&#39;hook. Chi ha installato una versione rilasciata segue il dist-tag <code>latest</code>; chi ha una prerelease <code>next</code> segue la più recente fra <code>latest</code> e <code>next</code>. Il registry è npmjs, o quello di <code>npm_config_registry</code>. Esce con <code>0</code>, o con <code>1</code> se il registry non risponde.</p><p><strong><code>etl upgrade</code></strong> fa il bump. Si ferma con exit <code>1</code> su un file gestito <code>modificato</code> o <code>in più</code>, che l&#39;aggiornamento sovrascriverebbe, e lo nomina; procede con <code>--force</code>, e le modifiche si perdono. Un file in <code>unmanaged</code> non lo ferma e non si riscrive. Poi stampa il changelog, porta <code>@noeva/etl-core</code> all&#39;ultima nel <code>package.json</code>, col prefisso che il range aveva (<code>^</code>, <code>~</code> o un pin esatto), e la toolchain delle <code>devDependencies</code> ai range del core nuovo, lancia <code>pnpm install</code> e infine la CLI del core appena installato (<code>pnpm exec etl upgrade --sync --force</code>), che risincronizza i file gestiti col suo template: i due YAML, <code>ecosystem.config.cjs</code> e il kit come <code>etl agent sync</code>. Se il changelog dice «Cambia il piano» suggerisce <code>pnpm exec etl versions snapshot --realign --ticket &lt;chiave&gt;</code>. Con il core già all&#39;ultima versione risincronizza soltanto i file gestiti; <code>etl upgrade --sync</code> fa lo stesso senza andare sul registry, per esempio dopo un bump fatto a mano con pnpm, e si ferma come l&#39;upgrade su un file toccato a mano, salvo <code>--force</code>. Package.json, lockfile e file gestiti si committano insieme, in una PR del bump. Un core dichiarato con <code>file:</code>, <code>link:</code> o <code>workspace:</code> si aggiorna a mano.</p><p><strong><code>etl env check</code></strong> verifica l&#39;ambiente sull&#39;intero catalogo: su stdout una riga per variabile obbligatoria mancante, <code>&lt;VARIABILE&gt;\t&lt;provenienze&gt;</code>, dove la provenienza è <code>core</code>, <code>pipeline &lt;nome&gt;</code> o <code>istanza &lt;connettore&gt; &lt;id&gt; (&lt;pipeline che la usano&gt;)</code>; su stderr un avviso per ogni chiave del <code>.env</code> che nessuno dichiara (solo il nome, mai il valore) e il riepilogo. Esce con <code>1</code> se manca un&#39;obbligatoria, <code>0</code> altrimenti, anche con sconosciute. Le variabili del core sono in <a href="./conventions/variabili-del-core">Variabili d&#39;ambiente del core</a>; quelle di una pipeline le dà il suo <code>environment(env)</code>, scritto con <code>ambienteDellaPipeline</code> di <code>./connector-kit</code> dagli stessi manifest della run (vedi <a href="./pipelines/test-posta"><code>test-posta</code></a>). Senza, il check ricade sul piano, che non mostra tutte le variabili di un&#39;istanza (l&#39;utente di un DB, l&#39;identità OAuth2), e quelle variabili, se stanno nel <code>.env</code>, compaiono fra le sconosciute. Legge l&#39;ambiente del processo, con il <code>.env</code> alla radice del repo che la CLI carica da sola prima di ogni comando (le variabili già nel processo vincono). Resta fuori dalla CI: serve l&#39;ambiente vero.</p><p><strong><code>etl catalog check</code></strong> è la conformità del catalogo: gli stessi controlli in ogni repo, che arrivano aggiornati con il bump del core. Su stdout una riga per violazione, <code>&lt;regola&gt;\t&lt;pipeline&gt;: &lt;dettaglio&gt;</code>; su stderr il riepilogo e gli avvisi del caricamento. Esce con <code>0</code> se il catalogo è conforme (anche vuoto, con l&#39;avviso), <code>1</code> con almeno una violazione, <code>2</code> per un errore d&#39;uso o di configurazione. Le regole:</p><table tabindex="0"><thead><tr><th>Regola</th><th>Cosa verifica</th></tr></thead><tbody><tr><td><code>changelog</code></td><td>numeri da 1 senza buchi, date <code>AAAA-MM-GG</code> in ordine, ticket, voci non vuote</td></tr><tr><td><code>piano-senza-credenziali</code></td><td><code>getSpec()</code> senza <code>.env</code> non lancia, il piano ha il nome della pipeline, almeno una source e un sink, si serializza in JSON e i nodi stanno nella proiezione</td></tr><tr><td><code>scopo-dei-nodi</code></td><td>ogni nodo e ogni istanza ha uno scopo; esenti il collettore dei dead-letter e i nodi di confine di un&#39;istanza, che genera il core</td></tr><tr><td><code>piano-senza-segreti</code></td><td>con l&#39;ambiente di <code>.env.example</code> e un valore riconoscibile al posto di ogni segreto il piano si disegna dalla configurazione risolta e non contiene segreti; poi lo stesso con le credenziali alternative</td></tr><tr><td><code>cartella-orfana</code></td><td>ogni <code>run.ts</code> sotto <code>src/pipelines/</code> esporta una pipeline del catalogo: una pipeline tolta da <code>etl.config.ts</code> non resta senza controlli</td></tr></tbody></table><p>L&#39;ambiente di prova di <code>piano-senza-segreti</code> è il <code>.env.example</code> alla radice del config, più le variabili segrete che le pipeline dichiarano con <code>environment(env)</code>. È segreta una variabile il cui nome contiene <code>PASSWORD</code>, <code>SECRET</code>, <code>TOKEN</code>, <code>API_KEY</code>, <code>ACCESS_KEY</code> o <code>PRIVATE_KEY</code>. Le credenziali commentate (<code># IMAP_ACCESS_TOKEN=</code>) sono alternative: il secondo passaggio le attiva e toglie quella attiva con lo stesso prefisso (<code>IMAP_PASSWORD</code>). Per questo <code>.env.example</code> deve essere completo: una pipeline che con quelle variabili si disegna dall&#39;esempio (un valore con la parola «esempio» nel piano) è una violazione, perché il controllo sui segreti guarderebbe solo i segnaposto.</p><p><strong><code>etl versions</code></strong> tiene le versioni di pipeline: ogni cambio di piano è una versione nuova, con la sua voce nel changelog e lo snapshot del piano. Il gate, il rollback di una pipeline sola e il riallineamento al core sono in <a href="./conventions/versioni-di-pipeline">Versioni di pipeline</a> e nel <a href="./runbooks/rollback-di-pipeline">runbook del rollback</a>.</p><p><strong><code>etl docs build</code></strong> costruisce la documentazione del cliente, con configurazione, tema e componenti dei grafi dal pacchetto: in un repo cliente <code>docs/</code> è solo markdown. Il sito va in <code>docs/.vitepress/dist</code> (<code>--outDir</code> per un&#39;altra cartella), col nome del cliente nel titolo, e comprende tutto <code>docs/</code>, ADR compresi, più una pagina indice del catalogo, <code>docs/catalogo.md</code>, che il build genera e che non si versiona. <strong><code>etl docs dev</code></strong> serve lo stesso sito in sviluppo (<code>--port &lt;n&gt;</code>). Il sito costruito lo serve <code>etl serve</code> su <code>/guida/</code>, accanto alla guida del core su <code>/guida/core/</code> (<a href="./runbooks/graph-server">runbook del server</a>). Prima di costruire il comando controlla la documentazione, e con un problema si ferma: una riga per problema su stdout, <code>&lt;regola&gt;\t&lt;dove&gt;: &lt;dettaglio&gt;</code>, ed exit <code>1</code>.</p><table tabindex="0"><thead><tr><th>Regola</th><th>Cosa verifica</th></tr></thead><tbody><tr><td><code>scheda-mancante</code></td><td>ogni pipeline del catalogo ha una pagina con <code>&lt;PipelineDag name=&quot;…&quot; /&gt;</code>, ogni sub-pipeline che una di loro istanzia una con <code>&lt;SubPipelineDag&gt;</code></td></tr><tr><td><code>scopo-mancante</code></td><td>ogni nodo e ogni istanza ha uno scopo, come <code>scopo-dei-nodi</code> di <code>etl catalog check</code></td></tr><tr><td><code>link-rotto</code></td><td>ogni link porta a una pagina pubblicata o a un file di <code>docs/</code>; un link fuori da <code>docs/</code> è rotto, perché non si pubblica</td></tr><tr><td><code>core-non-risolto</code></td><td>un link <code>core:nodes/lookup.md</code> porta a una pagina della guida del core installata</td></tr><tr><td><code>catalogo-del-repo</code></td><td><code>docs/catalogo.md</code> è quella generata: una scritta a mano non si sovrascrive</td></tr></tbody></table><p>Le pipeline pronte sono esenti: la loro scheda sta in questa guida, e nell&#39;indice del catalogo sono una riga col link qui. Un link <code>core:</code> diventa <code>/guida/core/&lt;pagina&gt;</code>, la guida del core servita dallo stesso deploy; si valida contro le pagine della guida nel pacchetto installato, quindi se un bump rinomina una pagina il build del cliente fallisce. Il piano si disegna senza l&#39;ambiente del processo, come lo snapshot.</p><h2 id="_8-aggiungere-le-cose-piu-comuni" tabindex="-1">8. Aggiungere le cose più comuni <a class="header-anchor" href="#_8-aggiungere-le-cose-piu-comuni" aria-label="Permalink to &quot;8. Aggiungere le cose più comuni&quot;">​</a></h2><h3 id="una-nuova-pipeline" tabindex="-1">Una nuova pipeline <a class="header-anchor" href="#una-nuova-pipeline" aria-label="Permalink to &quot;Una nuova pipeline&quot;">​</a></h3><p>Una cartella <code>src/pipelines/&lt;nome&gt;/</code> con: <code>schema.ts</code> (contratti Zod input/output), <code>pipeline.ts</code> (il grafo con <code>graph()...build()</code>, sorgenti e sink <strong>iniettati</strong>, non scritti dentro), <code>changelog.ts</code> (le versioni di pipeline, una nuova parte dalla v1), <code>run.ts</code> (il collegamento dei connettori concreti e la lettura dell&#39;ambiente), <code>pipeline.test.ts</code> (end-to-end con <code>arraySource</code>/<code>arraySink</code>: record validi caricati, invalidi al dead-letter, metriche corrette). Se legge variabili d&#39;ambiente, il suo <code>run.ts</code> dichiara anche <code>environment(env)</code> con <code>ambienteDellaPipeline</code>, dagli stessi manifest e istanze della run, così <code>etl env check</code> le vede tutte. Le sue variabili obbligatorie vanno in <code>.env.example</code>, che è anche l&#39;ambiente di prova di <code>etl catalog check</code>. Poi si aggiunge al catalogo in <code>etl.config.ts</code>, se ne scrive lo snapshot del piano con <code>pnpm etl versions snapshot &lt;nome&gt;</code> (<code>versions/v1.plan.json</code>) e si crea la scheda <code>docs/pipelines/&lt;nome&gt;.md</code> (vedi <a href="./pipelines/README">Le schede di una pipeline</a>).</p><h3 id="una-nuova-sub-pipeline" tabindex="-1">Una nuova sub-pipeline <a class="header-anchor" href="#una-nuova-sub-pipeline" aria-label="Permalink to &quot;Una nuova sub-pipeline&quot;">​</a></h3><p>Un pezzo di grafo riusato da più pipeline, o più volte nella stessa, è una sub-pipeline: <code>src/sub-pipelines/&lt;nome&gt;/</code> con <code>schema.ts</code> (contratti d&#39;ingresso e d&#39;uscita, e lo <code>z.object</code> dei parametri se ne ha), <code>sub-pipeline.ts</code> (<code>subPipeline({ … })</code>, con <code>params</code> per i dati che ogni istanza fissa e <code>deps</code> per i connettori che riceve dalla root) e <code>sub-pipeline.test.ts</code> (con <code>runSubPipeline</code>, <code>recordIds</code> acceso e spento). Un parametro compare in chiaro nel piano: le credenziali arrivano solo dentro una dipendenza. Lo scopo dei nodi del corpo si scrive nella definizione, quello dell&#39;istanza al punto di chiamata (<a href="./nodes/pipeline#scopo">Scopo</a>). Non si dichiara nel catalogo: arriva insieme alla prima root che la istanzia con <code>.pipeline()</code>. Scheda in <code>docs/sub-pipelines/&lt;nome&gt;.md</code> (vedi <a href="./sub-pipelines/README">Le schede di una sub-pipeline</a>).</p><h3 id="un-connettore-del-cliente" tabindex="-1">Un connettore del cliente <a class="header-anchor" href="#un-connettore-del-cliente" aria-label="Permalink to &quot;Un connettore del cliente&quot;">​</a></h3><p>Un sistema che conosce solo il cliente (il suo gestionale, la sua API) è un connettore del repo cliente, in <code>src/connectors/</code>: implementa <code>Source&lt;T&gt;</code>, <code>Sink&lt;T&gt;</code> o l&#39;interfaccia di un <code>lookup</code> o di un&#39;<code>action</code>, con gli strumenti di <code>@noeva/etl-core/connector-kit</code>, e ha la sua scheda in <code>docs/connectors/</code>. Un connettore che serve a più clienti va nel core.</p><h3 id="una-nuova-trasformazione" tabindex="-1">Una nuova trasformazione <a class="header-anchor" href="#una-nuova-trasformazione" aria-label="Permalink to &quot;Una nuova trasformazione&quot;">​</a></h3><p>Funzione pura, senza side-effect verso sistemi esterni (quelli stanno solo nei nodi che li dichiarano), così è testabile in isolamento. Prima di scriverne una, guarda le <a href="./nodes/transform#transform-pronte">transform pronte</a>. Se è stateful (come <code>groupBy</code>), va usata in fail-fast: niente dead-letter sul suo nodo (vedi §5).</p><h2 id="_9-cosa-non-fare-vincoli-non-negoziabili" tabindex="-1">9. Cosa NON fare (vincoli non negoziabili) <a class="header-anchor" href="#_9-cosa-non-fare-vincoli-non-negoziabili" aria-label="Permalink to &quot;9. Cosa NON fare (vincoli non negoziabili)&quot;">​</a></h2><ul><li><strong>Niente import dai percorsi interni del core</strong> — solo il pacchetto e i suoi subpath (§3).</li><li><strong>Niente <code>any</code></strong> — dati esterni entrano come <code>unknown</code>, si restringono con Zod.</li><li><strong>Niente IO dentro una <code>Transform</code></strong> — per una lettura c&#39;è il nodo <code>lookup</code>, per una scrittura il nodo <code>action</code>, per un&#39;operazione senza record il nodo <code>task</code>.</li><li><strong>Niente scarti silenziosi</strong> — ogni record invalido ha un percorso esplicito: dead-letter o fail-fast, mai un semplice skip.</li><li><strong>Sink non idempotenti</strong> — un retry/riesecuzione non deve mai duplicare dati (upsert su chiave naturale, MERGE, o write-then-swap, vedi <a href="./runbooks/sql-task-truncate-swap">il runbook</a>).</li><li><strong>Niente segreti</strong> nel codice, nei log o nel report — solo variabili d&#39;ambiente, documentate in <code>.env.example</code>.</li><li><strong>Codice senza test o senza scheda aggiornata non è &quot;finito&quot;</strong> — codice e documentazione cambiano nello stesso commit, e <code>etl docs build</code> lo verifica.</li></ul><h2 id="_10-il-kit-dell-agente" tabindex="-1">10. Il kit dell&#39;agente <a class="header-anchor" href="#_10-il-kit-dell-agente" aria-label="Permalink to &quot;10. Il kit dell&#39;agente&quot;">​</a></h2><p>Il repo cliente porta il kit con cui Claude Code, o un altro agente, lavora secondo le regole del core: la skill <code>etl-graph</code> (come si costruisce, si cabla e si configura un grafo sull&#39;API pubblica), le skill di scaffolding e di review (<code>/new-pipeline</code>, <code>/new-connector</code>, <code>/new-transform</code>, <code>/etl-review</code>, <code>/doc-sync</code>) e i subagent che materializzano e rivedono una pipeline, più l&#39;hook che blocca commit e push su <code>dev</code>, <code>staging</code> e <code>main</code>. I file del kit sono del core e arrivano con la sua versione: <code>etl init</code> li scrive alla nascita del repo, e <code>pnpm exec etl agent sync</code> li riscrive dal core installato in <code>.claude/skills/noeva-etl-*</code>, <code>.claude/agents/noeva-etl-*</code> e <code>.claude/hooks/noeva-etl-*</code>, insieme alla voce dell&#39;hook in <code>.claude/settings.json</code> e al blocco gestito di <code>AGENTS.md</code>. Toglie anche le voci <code>noeva-etl-*</code> che il kit non ha più, e salta quelle in <code>unmanaged</code>. I file si committano: li vedono anche gli agenti che non sono Claude, e un bump del core mostra il diff del kit. Il resto di <code>.claude/</code> e di <code>AGENTS.md</code> è del cliente. Il kit rimanda a questa guida invece di ricopiarla. Il catalogo completo è in <a href="./guide/claude-code/strumenti">Skill e subagent</a>.</p></div></div></main><footer class="VPDocFooter" data-v-303c7d43 data-v-64d0b887><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-64d0b887><span class="visually-hidden" id="doc-footer-aria-label" data-v-64d0b887>Pager</span><div class="pager" data-v-64d0b887><a class="VPLink link pager-link prev" href="/guida/core/guide/claude-code/strumenti" data-v-64d0b887><!--[--><span class="desc" data-v-64d0b887>Pagina precedente</span><span class="title" data-v-64d0b887>Skill e subagent</span><!--]--></a></div><div class="pager" data-v-64d0b887><a class="VPLink link pager-link next" href="/guida/core/guide/grafo" data-v-64d0b887><!--[--><span class="desc" data-v-64d0b887>Pagina successiva</span><span class="title" data-v-64d0b887>Il grafo, nodo per nodo</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><footer class="VPFooter has-sidebar" data-v-f5dee57d data-v-e10de3dd><div class="container" data-v-e10de3dd><p class="message" data-v-e10de3dd>Noeva è un marchio registrato di 4D S.R.L.</p><p class="copyright" data-v-e10de3dd>© 2026 4D S.R.L. · Gruppo4D</p></div></footer><!--[--><span hidden></span><!--]--></div></div>
77
- <script>window.__VP_HASH_MAP__=JSON.parse("{\"connectors_file.md\":\"B1NJe0VJ\",\"connectors_http.md\":\"B8utPijY\",\"connectors_imap.md\":\"CMMpZVXn\",\"connectors_jira.md\":\"0DJvrRXH\",\"connectors_noeva.md\":\"DkxCC8Ey\",\"connectors_oauth.md\":\"DUHajB0u\",\"connectors_postgres.md\":\"DPpHqXkc\",\"connectors_process.md\":\"lQLmWbGN\",\"connectors_readme.md\":\"ChyXSf73\",\"connectors_sendgrid.md\":\"dJzIWepq\",\"connectors_smtp.md\":\"DXXvaNxD\",\"connectors_sqlserver.md\":\"D1sYNLEq\",\"conventions_node-columns.md\":\"D9K1peUx\",\"conventions_node-descriptor.md\":\"D8Si7E2S\",\"conventions_run-report.md\":\"D_pG07VG\",\"conventions_run-trace.md\":\"nKS_RgLC\",\"conventions_variabili-del-core.md\":\"BU6BD6w_\",\"conventions_versioni-di-pipeline.md\":\"cy5nsizS\",\"guida_sviluppo.md\":\"Dj20s7gS\",\"guide_claude-code_index.md\":\"CxVSru8e\",\"guide_claude-code_prompt.md\":\"C7uETA9W\",\"guide_claude-code_strumenti.md\":\"BWhQnAlY\",\"guide_grafo.md\":\"Dy8_YMeh\",\"guide_usare_app-desktop.md\":\"CcDu8cJL\",\"guide_usare_esito-di-una-run.md\":\"DkvAOPBE\",\"guide_usare_index.md\":\"BJqi3P7J\",\"index.md\":\"kMhsF-sv\",\"nodes_action.md\":\"DOsTbV-i\",\"nodes_ai.md\":\"CVtP9gEJ\",\"nodes_join.md\":\"DSYbIDG6\",\"nodes_lookup.md\":\"BI8tgBIq\",\"nodes_pipeline.md\":\"DIMlyprm\",\"nodes_readme.md\":\"CHGy_go6\",\"nodes_route.md\":\"Bt9qH6OA\",\"nodes_sink.md\":\"yAf_z4wO\",\"nodes_source.md\":\"V_vlNfOz\",\"nodes_task.md\":\"Dk6VB7as\",\"nodes_transform.md\":\"Bv5fg2Xx\",\"nodes_try-catch.md\":\"DCYydDPm\",\"nodes_union.md\":\"CznVzHTK\",\"pipelines_crm-leads-sync.md\":\"BlZUnxYn\",\"pipelines_cross-workspace-csv-merge.md\":\"CsRE6GNe\",\"pipelines_movimenti-per-conto.md\":\"DRGfO1_5\",\"pipelines_orders-enriched-daily.md\":\"jESRtvBo\",\"pipelines_readme.md\":\"Ee6LS-SU\",\"pipelines_test-posta.md\":\"Cxo_DGBs\",\"runbooks_aggiornamento-pm2.md\":\"f3LAxif4\",\"runbooks_deployment.md\":\"DvIOOsoG\",\"runbooks_etl-worker.md\":\"Bu05cEgT\",\"runbooks_graph-server.md\":\"BOXZqdXC\",\"runbooks_mask-key.md\":\"nZkhAjBf\",\"runbooks_oauth-google-posta.md\":\"Bs7QTkmU\",\"runbooks_rollback-di-pipeline.md\":\"6US0Wsdc\",\"runbooks_scd2-rehash.md\":\"DtmuXA67\",\"runbooks_sql-task-truncate-swap.md\":\"C8viT-fp\",\"runbooks_stato-incrementale.md\":\"hGZ8FlbZ\",\"sub-pipelines_readme.md\":\"CF8gmNPU\",\"sub-pipelines_riepilogo-ordini.md\":\"qCBZJ4nh\",\"technical_overview.md\":\"DQP0pWc8\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"it-IT\",\"dir\":\"ltr\",\"title\":\"Noeva ETL\",\"titleTemplate\":\":title · Noeva ETL\",\"description\":\"Documentazione di Noeva ETL: come usare la piattaforma e come creare pipeline con Claude Code.\",\"base\":\"/guida/core/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":{\"light\":\"/logo-dark.png\",\"dark\":\"/logo-light.png\",\"alt\":\"Noeva\"},\"siteTitle\":false,\"footer\":{\"message\":\"Noeva è un marchio registrato di 4D S.R.L.\",\"copyright\":\"© 2026 4D S.R.L. · Gruppo4D\"},\"outline\":{\"level\":[2,3],\"label\":\"In questa pagina\"},\"docFooter\":{\"prev\":\"Pagina precedente\",\"next\":\"Pagina successiva\"},\"darkModeSwitchLabel\":\"Tema\",\"lightModeSwitchTitle\":\"Passa al tema chiaro\",\"darkModeSwitchTitle\":\"Passa al tema scuro\",\"sidebarMenuLabel\":\"Menu\",\"returnToTopLabel\":\"Torna su\",\"langMenuLabel\":\"Lingua\",\"notFound\":{\"title\":\"PAGINA NON TROVATA\",\"quote\":\"Il documento che cercavi non c'è più, o non è mai stato pubblicato qui.\",\"linkLabel\":\"Torna alla home\",\"linkText\":\"Torna alla home\"},\"search\":{\"provider\":\"local\",\"options\":{\"translations\":{\"button\":{\"buttonText\":\"Cerca\",\"buttonAriaLabel\":\"Cerca nella documentazione\"},\"modal\":{\"displayDetails\":\"Mostra i dettagli\",\"resetButtonTitle\":\"Azzera la ricerca\",\"backButtonTitle\":\"Chiudi la ricerca\",\"noResultsText\":\"Nessun risultato per\",\"footer\":{\"selectText\":\"per aprire\",\"selectKeyAriaLabel\":\"invio\",\"navigateText\":\"per spostarti\",\"navigateUpKeyAriaLabel\":\"freccia su\",\"navigateDownKeyAriaLabel\":\"freccia giù\",\"closeText\":\"per chiudere\",\"closeKeyAriaLabel\":\"esc\"}}}}},\"nav\":[{\"text\":\"Usare\",\"link\":\"/guide/usare/\",\"activeMatch\":\"^/guide/usare/\"},{\"text\":\"Creare con Claude Code\",\"link\":\"/guide/claude-code/\",\"activeMatch\":\"^/guide/claude-code/\"},{\"text\":\"Riferimento\",\"items\":[{\"text\":\"Il grafo, nodo per nodo\",\"link\":\"/guide/grafo\"},{\"text\":\"Tipi di nodo\",\"link\":\"/nodes/README\"},{\"text\":\"Connettori\",\"link\":\"/connectors/README\"},{\"text\":\"Pipeline pronte\",\"link\":\"/pipelines/README\"},{\"text\":\"Il report di run\",\"link\":\"/conventions/run-report\"},{\"text\":\"La traccia di una run\",\"link\":\"/conventions/run-trace\"},{\"text\":\"Variabili d'ambiente del core\",\"link\":\"/conventions/variabili-del-core\"},{\"text\":\"Operatività\",\"link\":\"/runbooks/graph-server\"}]}],\"sidebar\":[{\"text\":\"Usare Noeva ETL\",\"items\":[{\"text\":\"Come si usa\",\"link\":\"/guide/usare/\"},{\"text\":\"L'app desktop\",\"link\":\"/guide/usare/app-desktop\"},{\"text\":\"Leggere l'esito di una run\",\"link\":\"/guide/usare/esito-di-una-run\"},{\"text\":\"Panoramica di prodotto\",\"link\":\"/TECHNICAL_OVERVIEW\"}]},{\"text\":\"Creare con Claude Code\",\"items\":[{\"text\":\"Dal bisogno al processo\",\"link\":\"/guide/claude-code/\"},{\"text\":\"Comporre il prompt\",\"link\":\"/guide/claude-code/prompt\"},{\"text\":\"Skill e subagent\",\"link\":\"/guide/claude-code/strumenti\"},{\"text\":\"Guida allo sviluppo\",\"link\":\"/GUIDA_SVILUPPO\"}]},{\"text\":\"Concetti\",\"items\":[{\"text\":\"Il grafo, nodo per nodo\",\"link\":\"/guide/grafo\"},{\"text\":\"Il report di run\",\"link\":\"/conventions/run-report\"},{\"text\":\"La traccia di una run\",\"link\":\"/conventions/run-trace\"},{\"text\":\"Versioni di pipeline\",\"link\":\"/conventions/versioni-di-pipeline\"},{\"text\":\"Descriptor dei nodi\",\"link\":\"/conventions/node-descriptor\"},{\"text\":\"Colonne dei nodi\",\"link\":\"/conventions/node-columns\"},{\"text\":\"Variabili d'ambiente del core\",\"link\":\"/conventions/variabili-del-core\"}]},{\"text\":\"Tipi di nodo\",\"collapsed\":true,\"items\":[{\"text\":\"Cheatsheet\",\"link\":\"/nodes/README\"},{\"text\":\"action\",\"link\":\"/nodes/action\"},{\"text\":\"ai\",\"link\":\"/nodes/ai\"},{\"text\":\"join\",\"link\":\"/nodes/join\"},{\"text\":\"lookup\",\"link\":\"/nodes/lookup\"},{\"text\":\"pipeline\",\"link\":\"/nodes/pipeline\"},{\"text\":\"route\",\"link\":\"/nodes/route\"},{\"text\":\"sink\",\"link\":\"/nodes/sink\"},{\"text\":\"source\",\"link\":\"/nodes/source\"},{\"text\":\"task\",\"link\":\"/nodes/task\"},{\"text\":\"transform\",\"link\":\"/nodes/transform\"},{\"text\":\"try-catch\",\"link\":\"/nodes/try-catch\"},{\"text\":\"union\",\"link\":\"/nodes/union\"}]},{\"text\":\"Connettori\",\"collapsed\":true,\"items\":[{\"text\":\"Panoramica\",\"link\":\"/connectors/README\"},{\"text\":\"File (storage × codec)\",\"link\":\"/connectors/file\"},{\"text\":\"HTTP (API REST per i nodi lookup e action)\",\"link\":\"/connectors/http\"},{\"text\":\"IMAP (caselle di posta)\",\"link\":\"/connectors/imap\"},{\"text\":\"Jira Cloud (issue da una JQL o per chiave, liste di una issue, creazione, aggiornamento, transizioni, upsert, commenti, worklog e link)\",\"link\":\"/connectors/jira\"},{\"text\":\"Noeva (file dei workspace)\",\"link\":\"/connectors/noeva\"},{\"text\":\"OAuth2 per i connettori di posta\",\"link\":\"/connectors/oauth\"},{\"text\":\"PostgreSQL\",\"link\":\"/connectors/postgres\"},{\"text\":\"processo esterno\",\"link\":\"/connectors/process\"},{\"text\":\"SendGrid (mail via API REST)\",\"link\":\"/connectors/sendgrid\"},{\"text\":\"SMTP (notifiche email)\",\"link\":\"/connectors/smtp\"},{\"text\":\"SQL Server\",\"link\":\"/connectors/sqlserver\"}]},{\"text\":\"Pipeline pronte\",\"collapsed\":true,\"items\":[{\"text\":\"Le schede di una pipeline\",\"link\":\"/pipelines/README\"},{\"text\":\"test-posta\",\"link\":\"/pipelines/test-posta\"}]},{\"text\":\"Esempi\",\"collapsed\":true,\"items\":[{\"text\":\"Le schede di una sub-pipeline\",\"link\":\"/sub-pipelines/README\"},{\"text\":\"crm-leads-sync\",\"link\":\"/pipelines/crm-leads-sync\"},{\"text\":\"cross-workspace-csv-merge\",\"link\":\"/pipelines/cross-workspace-csv-merge\"},{\"text\":\"movimenti-per-conto\",\"link\":\"/pipelines/movimenti-per-conto\"},{\"text\":\"orders-enriched-daily\",\"link\":\"/pipelines/orders-enriched-daily\"},{\"text\":\"riepilogo-ordini\",\"link\":\"/sub-pipelines/riepilogo-ordini\"}]},{\"text\":\"Operatività\",\"collapsed\":true,\"items\":[{\"text\":\"aggiornare un deploy PM2 di un repo cliente\",\"link\":\"/runbooks/aggiornamento-pm2\"},{\"text\":\"distribuzione del runner ETL\",\"link\":\"/runbooks/deployment\"},{\"text\":\"worker etl worker (polling su processes)\",\"link\":\"/runbooks/etl-worker\"},{\"text\":\"server grafi etl serve (HTTP)\",\"link\":\"/runbooks/graph-server\"},{\"text\":\"chiavi di mask (creazione, rotazione, compromissione)\",\"link\":\"/runbooks/mask-key\"},{\"text\":\"OAuth2 per una casella Google (IMAP + SMTP)\",\"link\":\"/runbooks/oauth-google-posta\"},{\"text\":\"rollback di una pipeline\",\"link\":\"/runbooks/rollback-di-pipeline\"},{\"text\":\"rehash di una dimensione storicizzata\",\"link\":\"/runbooks/scd2-rehash\"},{\"text\":\"task SQL, truncate e scambio di tabelle\",\"link\":\"/runbooks/sql-task-truncate-swap\"},{\"text\":\"stato di pipeline e watermark\",\"link\":\"/runbooks/stato-incrementale\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
77
+ <script>window.__VP_HASH_MAP__=JSON.parse("{\"connectors_file.md\":\"B1NJe0VJ\",\"connectors_http.md\":\"B8utPijY\",\"connectors_imap.md\":\"CMMpZVXn\",\"connectors_jira.md\":\"0DJvrRXH\",\"connectors_noeva.md\":\"DkxCC8Ey\",\"connectors_oauth.md\":\"DUHajB0u\",\"connectors_postgres.md\":\"DPpHqXkc\",\"connectors_process.md\":\"lQLmWbGN\",\"connectors_readme.md\":\"ChyXSf73\",\"connectors_sendgrid.md\":\"dJzIWepq\",\"connectors_smtp.md\":\"DXXvaNxD\",\"connectors_sqlserver.md\":\"D1sYNLEq\",\"conventions_node-columns.md\":\"D9K1peUx\",\"conventions_node-descriptor.md\":\"D8Si7E2S\",\"conventions_run-report.md\":\"D_pG07VG\",\"conventions_run-trace.md\":\"nKS_RgLC\",\"conventions_variabili-del-core.md\":\"BU6BD6w_\",\"conventions_versioni-di-pipeline.md\":\"cy5nsizS\",\"guida_sviluppo.md\":\"D13C7Zwu\",\"guide_claude-code_index.md\":\"CxVSru8e\",\"guide_claude-code_prompt.md\":\"C7uETA9W\",\"guide_claude-code_strumenti.md\":\"BWhQnAlY\",\"guide_grafo.md\":\"Dy8_YMeh\",\"guide_usare_app-desktop.md\":\"CcDu8cJL\",\"guide_usare_esito-di-una-run.md\":\"DkvAOPBE\",\"guide_usare_index.md\":\"BJqi3P7J\",\"index.md\":\"kMhsF-sv\",\"nodes_action.md\":\"DOsTbV-i\",\"nodes_ai.md\":\"CVtP9gEJ\",\"nodes_join.md\":\"DSYbIDG6\",\"nodes_lookup.md\":\"BI8tgBIq\",\"nodes_pipeline.md\":\"DIMlyprm\",\"nodes_readme.md\":\"CHGy_go6\",\"nodes_route.md\":\"Bt9qH6OA\",\"nodes_sink.md\":\"yAf_z4wO\",\"nodes_source.md\":\"V_vlNfOz\",\"nodes_task.md\":\"Dk6VB7as\",\"nodes_transform.md\":\"Bv5fg2Xx\",\"nodes_try-catch.md\":\"DCYydDPm\",\"nodes_union.md\":\"CznVzHTK\",\"pipelines_crm-leads-sync.md\":\"BlZUnxYn\",\"pipelines_cross-workspace-csv-merge.md\":\"CsRE6GNe\",\"pipelines_movimenti-per-conto.md\":\"DRGfO1_5\",\"pipelines_orders-enriched-daily.md\":\"jESRtvBo\",\"pipelines_readme.md\":\"Ee6LS-SU\",\"pipelines_test-posta.md\":\"Cxo_DGBs\",\"runbooks_aggiornamento-pm2.md\":\"f3LAxif4\",\"runbooks_deployment.md\":\"DvIOOsoG\",\"runbooks_etl-worker.md\":\"Bu05cEgT\",\"runbooks_graph-server.md\":\"BOXZqdXC\",\"runbooks_mask-key.md\":\"nZkhAjBf\",\"runbooks_oauth-google-posta.md\":\"Bs7QTkmU\",\"runbooks_rollback-di-pipeline.md\":\"6US0Wsdc\",\"runbooks_scd2-rehash.md\":\"DtmuXA67\",\"runbooks_sql-task-truncate-swap.md\":\"C8viT-fp\",\"runbooks_stato-incrementale.md\":\"hGZ8FlbZ\",\"sub-pipelines_readme.md\":\"CF8gmNPU\",\"sub-pipelines_riepilogo-ordini.md\":\"qCBZJ4nh\",\"technical_overview.md\":\"DQP0pWc8\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"it-IT\",\"dir\":\"ltr\",\"title\":\"Noeva ETL\",\"titleTemplate\":\":title · Noeva ETL\",\"description\":\"Documentazione di Noeva ETL: come usare la piattaforma e come creare pipeline con Claude Code.\",\"base\":\"/guida/core/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":{\"light\":\"/logo-dark.png\",\"dark\":\"/logo-light.png\",\"alt\":\"Noeva\"},\"siteTitle\":false,\"footer\":{\"message\":\"Noeva è un marchio registrato di 4D S.R.L.\",\"copyright\":\"© 2026 4D S.R.L. · Gruppo4D\"},\"outline\":{\"level\":[2,3],\"label\":\"In questa pagina\"},\"docFooter\":{\"prev\":\"Pagina precedente\",\"next\":\"Pagina successiva\"},\"darkModeSwitchLabel\":\"Tema\",\"lightModeSwitchTitle\":\"Passa al tema chiaro\",\"darkModeSwitchTitle\":\"Passa al tema scuro\",\"sidebarMenuLabel\":\"Menu\",\"returnToTopLabel\":\"Torna su\",\"langMenuLabel\":\"Lingua\",\"notFound\":{\"title\":\"PAGINA NON TROVATA\",\"quote\":\"Il documento che cercavi non c'è più, o non è mai stato pubblicato qui.\",\"linkLabel\":\"Torna alla home\",\"linkText\":\"Torna alla home\"},\"search\":{\"provider\":\"local\",\"options\":{\"translations\":{\"button\":{\"buttonText\":\"Cerca\",\"buttonAriaLabel\":\"Cerca nella documentazione\"},\"modal\":{\"displayDetails\":\"Mostra i dettagli\",\"resetButtonTitle\":\"Azzera la ricerca\",\"backButtonTitle\":\"Chiudi la ricerca\",\"noResultsText\":\"Nessun risultato per\",\"footer\":{\"selectText\":\"per aprire\",\"selectKeyAriaLabel\":\"invio\",\"navigateText\":\"per spostarti\",\"navigateUpKeyAriaLabel\":\"freccia su\",\"navigateDownKeyAriaLabel\":\"freccia giù\",\"closeText\":\"per chiudere\",\"closeKeyAriaLabel\":\"esc\"}}}}},\"nav\":[{\"text\":\"Usare\",\"link\":\"/guide/usare/\",\"activeMatch\":\"^/guide/usare/\"},{\"text\":\"Creare con Claude Code\",\"link\":\"/guide/claude-code/\",\"activeMatch\":\"^/guide/claude-code/\"},{\"text\":\"Riferimento\",\"items\":[{\"text\":\"Il grafo, nodo per nodo\",\"link\":\"/guide/grafo\"},{\"text\":\"Tipi di nodo\",\"link\":\"/nodes/README\"},{\"text\":\"Connettori\",\"link\":\"/connectors/README\"},{\"text\":\"Pipeline pronte\",\"link\":\"/pipelines/README\"},{\"text\":\"Il report di run\",\"link\":\"/conventions/run-report\"},{\"text\":\"La traccia di una run\",\"link\":\"/conventions/run-trace\"},{\"text\":\"Variabili d'ambiente del core\",\"link\":\"/conventions/variabili-del-core\"},{\"text\":\"Operatività\",\"link\":\"/runbooks/graph-server\"}]}],\"sidebar\":[{\"text\":\"Usare Noeva ETL\",\"items\":[{\"text\":\"Come si usa\",\"link\":\"/guide/usare/\"},{\"text\":\"L'app desktop\",\"link\":\"/guide/usare/app-desktop\"},{\"text\":\"Leggere l'esito di una run\",\"link\":\"/guide/usare/esito-di-una-run\"},{\"text\":\"Panoramica di prodotto\",\"link\":\"/TECHNICAL_OVERVIEW\"}]},{\"text\":\"Creare con Claude Code\",\"items\":[{\"text\":\"Dal bisogno al processo\",\"link\":\"/guide/claude-code/\"},{\"text\":\"Comporre il prompt\",\"link\":\"/guide/claude-code/prompt\"},{\"text\":\"Skill e subagent\",\"link\":\"/guide/claude-code/strumenti\"},{\"text\":\"Guida allo sviluppo\",\"link\":\"/GUIDA_SVILUPPO\"}]},{\"text\":\"Concetti\",\"items\":[{\"text\":\"Il grafo, nodo per nodo\",\"link\":\"/guide/grafo\"},{\"text\":\"Il report di run\",\"link\":\"/conventions/run-report\"},{\"text\":\"La traccia di una run\",\"link\":\"/conventions/run-trace\"},{\"text\":\"Versioni di pipeline\",\"link\":\"/conventions/versioni-di-pipeline\"},{\"text\":\"Descriptor dei nodi\",\"link\":\"/conventions/node-descriptor\"},{\"text\":\"Colonne dei nodi\",\"link\":\"/conventions/node-columns\"},{\"text\":\"Variabili d'ambiente del core\",\"link\":\"/conventions/variabili-del-core\"}]},{\"text\":\"Tipi di nodo\",\"collapsed\":true,\"items\":[{\"text\":\"Cheatsheet\",\"link\":\"/nodes/README\"},{\"text\":\"action\",\"link\":\"/nodes/action\"},{\"text\":\"ai\",\"link\":\"/nodes/ai\"},{\"text\":\"join\",\"link\":\"/nodes/join\"},{\"text\":\"lookup\",\"link\":\"/nodes/lookup\"},{\"text\":\"pipeline\",\"link\":\"/nodes/pipeline\"},{\"text\":\"route\",\"link\":\"/nodes/route\"},{\"text\":\"sink\",\"link\":\"/nodes/sink\"},{\"text\":\"source\",\"link\":\"/nodes/source\"},{\"text\":\"task\",\"link\":\"/nodes/task\"},{\"text\":\"transform\",\"link\":\"/nodes/transform\"},{\"text\":\"try-catch\",\"link\":\"/nodes/try-catch\"},{\"text\":\"union\",\"link\":\"/nodes/union\"}]},{\"text\":\"Connettori\",\"collapsed\":true,\"items\":[{\"text\":\"Panoramica\",\"link\":\"/connectors/README\"},{\"text\":\"File (storage × codec)\",\"link\":\"/connectors/file\"},{\"text\":\"HTTP (API REST per i nodi lookup e action)\",\"link\":\"/connectors/http\"},{\"text\":\"IMAP (caselle di posta)\",\"link\":\"/connectors/imap\"},{\"text\":\"Jira Cloud (issue da una JQL o per chiave, liste di una issue, creazione, aggiornamento, transizioni, upsert, commenti, worklog e link)\",\"link\":\"/connectors/jira\"},{\"text\":\"Noeva (file dei workspace)\",\"link\":\"/connectors/noeva\"},{\"text\":\"OAuth2 per i connettori di posta\",\"link\":\"/connectors/oauth\"},{\"text\":\"PostgreSQL\",\"link\":\"/connectors/postgres\"},{\"text\":\"processo esterno\",\"link\":\"/connectors/process\"},{\"text\":\"SendGrid (mail via API REST)\",\"link\":\"/connectors/sendgrid\"},{\"text\":\"SMTP (notifiche email)\",\"link\":\"/connectors/smtp\"},{\"text\":\"SQL Server\",\"link\":\"/connectors/sqlserver\"}]},{\"text\":\"Pipeline pronte\",\"collapsed\":true,\"items\":[{\"text\":\"Le schede di una pipeline\",\"link\":\"/pipelines/README\"},{\"text\":\"test-posta\",\"link\":\"/pipelines/test-posta\"}]},{\"text\":\"Esempi\",\"collapsed\":true,\"items\":[{\"text\":\"Le schede di una sub-pipeline\",\"link\":\"/sub-pipelines/README\"},{\"text\":\"crm-leads-sync\",\"link\":\"/pipelines/crm-leads-sync\"},{\"text\":\"cross-workspace-csv-merge\",\"link\":\"/pipelines/cross-workspace-csv-merge\"},{\"text\":\"movimenti-per-conto\",\"link\":\"/pipelines/movimenti-per-conto\"},{\"text\":\"orders-enriched-daily\",\"link\":\"/pipelines/orders-enriched-daily\"},{\"text\":\"riepilogo-ordini\",\"link\":\"/sub-pipelines/riepilogo-ordini\"}]},{\"text\":\"Operatività\",\"collapsed\":true,\"items\":[{\"text\":\"aggiornare un deploy PM2 di un repo cliente\",\"link\":\"/runbooks/aggiornamento-pm2\"},{\"text\":\"distribuzione del runner ETL\",\"link\":\"/runbooks/deployment\"},{\"text\":\"worker etl worker (polling su processes)\",\"link\":\"/runbooks/etl-worker\"},{\"text\":\"server grafi etl serve (HTTP)\",\"link\":\"/runbooks/graph-server\"},{\"text\":\"chiavi di mask (creazione, rotazione, compromissione)\",\"link\":\"/runbooks/mask-key\"},{\"text\":\"OAuth2 per una casella Google (IMAP + SMTP)\",\"link\":\"/runbooks/oauth-google-posta\"},{\"text\":\"rollback di una pipeline\",\"link\":\"/runbooks/rollback-di-pipeline\"},{\"text\":\"rehash di una dimensione storicizzata\",\"link\":\"/runbooks/scd2-rehash\"},{\"text\":\"task SQL, truncate e scambio di tabelle\",\"link\":\"/runbooks/sql-task-truncate-swap\"},{\"text\":\"stato di pipeline e watermark\",\"link\":\"/runbooks/stato-incrementale\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
78
78
 
79
79
  </body>
80
80
  </html>
@@ -9,9 +9,9 @@
9
9
  <link rel="preload stylesheet" href="/guida/core/assets/style.BNn_AkzN.css" as="style">
10
10
  <link rel="preload stylesheet" href="/guida/core/vp-icons.css" as="style">
11
11
 
12
- <script type="module" src="/guida/core/assets/app.vAJRZtow.js"></script>
12
+ <script type="module" src="/guida/core/assets/app.BMz6ZZYF.js"></script>
13
13
  <link rel="preload" href="/guida/core/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
14
- <link rel="modulepreload" href="/guida/core/assets/chunks/theme.Bq6mfDhZ.js">
14
+ <link rel="modulepreload" href="/guida/core/assets/chunks/theme.DV62mViB.js">
15
15
  <link rel="modulepreload" href="/guida/core/assets/chunks/framework.qdetmeNX.js">
16
16
  <link rel="modulepreload" href="/guida/core/assets/TECHNICAL_OVERVIEW.md.DQP0pWc8.lean.js">
17
17
  <link rel="icon" type="image/svg+xml" href="/guida/core/favicon.svg">
@@ -40,7 +40,7 @@
40
40
  <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># solo daemon: polling continuo su processes (worker_type da env; uno o più</span></span>
41
41
  <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># workspace — NOEVA_WORKSPACE_IDS per il multi-workspace)</span></span>
42
42
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> worker</span></span></code></pre></div><ul><li><strong>Configurazione solo da variabili d&#39;ambiente</strong> (<code>PG*</code>, <code>MSSQL_*</code>, <code>ETL_ENV</code>, …); <strong>nessun segreto</strong> nel codice o nell&#39;immagine.</li><li><strong>Tre modalità di invocazione</strong>: <strong>batch</strong> (<code>etl run</code>, un container = una esecuzione, poi termina — vedi <a href="./runbooks/deployment">il deploy</a>); <strong>daemon</strong> (<code>etl worker</code>, resta in polling su <code>processes</code> finché non riceve <code>SIGTERM</code>/<code>SIGINT</code> — vedi <a href="./runbooks/etl-worker">il worker</a>); <strong>server + daemon</strong> (<code>etl serve</code>, il <code>CMD</code> di default dell&#39;immagine: un solo container per tutta la piattaforma — vedi <a href="./runbooks/graph-server"><code>etl serve</code></a>).</li><li><strong>App desktop</strong> <code>noeva-etl-ui</code>: si distribuisce come applicazione Tauri, uguale per tutti i deploy.</li><li><strong>Modello di deploy</strong>: il deploy esegue un repo cliente, come immagine container o sotto PM2 dai sorgenti. Vedi <a href="./runbooks/deployment">il deploy</a>.</li></ul><h2 id="_6-il-report-di-run-e-il-prodotto" tabindex="-1">6. Il report di run è il &quot;prodotto&quot; <a class="header-anchor" href="#_6-il-report-di-run-e-il-prodotto" aria-label="Permalink to &quot;6. Il report di run è il &quot;prodotto&quot;&quot;">​</a></h2><p>Il nucleo di esecuzione <strong>non persiste nulla</strong>: esegue e <strong>restituisce un risultato completo</strong>. È il chiamante a conservarlo: la CLI tiene le ultime run in locale (<code>etl runs list</code>), il worker lo scrive nel job Noeva, ed <code>etl serve</code> conserva nello stesso storico locale le run tracciate che lancia lui.</p><ul><li><strong><code>stdout</code></strong> = report in JSON (un oggetto, parsabile con <code>jq</code>); <strong><code>stderr</code></strong> = log.</li><li><strong>exit code</strong>: <code>0</code> se <code>success</code>/<code>partial</code>, <code>≠0</code> se <code>failed</code>.</li><li><strong>Anche in errore</strong> emette un report (<code>status: failed</code>) con dettagli e conteggi parziali.</li><li>Contiene: stato, tempi, versione, topologia reale del grafo (nodi e archi, con i conteggi e i tempi di ogni nodo), parametri, volumi (<code>extracted</code>/<code>written</code>/<code>rejected</code>), <strong>categorie di scarto</strong>, metriche, errore — <strong>senza segreti né payload/PII</strong>.</li></ul><p>Chi invoca decide cosa farne (archiviarlo, mandarlo in alert, ignorarlo). Vedi <a href="./conventions/run-report">run-report.md</a>.</p><h2 id="_7-come-si-espande" tabindex="-1">7. Come si espande <a class="header-anchor" href="#_7-come-si-espande" aria-label="Permalink to &quot;7. Come si espande&quot;">​</a></h2><p>Crescita <strong>per composizione</strong>, senza toccare il core. Comandi di scaffold coerenti generano struttura + test + doc:</p><ul><li><strong>Nuova pipeline</strong> → <code>/new-pipeline &lt;nome&gt;</code> (schema, definizione, changelog, snapshot del piano, run, test, scheda doc).</li><li><strong>Nuovo connettore</strong> → <code>/new-connector &lt;nome&gt; [source|sink]</code> (verso un nuovo sistema: API, file/CSV, altri DB, code…).</li><li><strong>Nuova trasformazione</strong> → <code>/new-transform &lt;nome&gt;</code> (logica riusabile, pura e testabile).</li></ul><p>Aggiungere un sistema = scrivere un <code>Source</code>/<code>Sink</code> che rispetta l&#39;interfaccia; tutte le pipeline esistenti possono usarlo subito (DI). La logica di dominio vive nelle trasformazioni, riusabili tra pipeline.</p><h2 id="_8-perche-ci-si-puo-fidare-governance" tabindex="-1">8. Perché ci si può fidare (governance) <a class="header-anchor" href="#_8-perche-ci-si-puo-fidare-governance" aria-label="Permalink to &quot;8. Perché ci si può fidare (governance)&quot;">​</a></h2><ul><li><strong>Test obbligatori</strong> con soglie di coverage come <strong>gate di CI</strong> (GitHub Actions).</li><li><strong>Documentazione nello stesso commit</strong> del codice (schede pipeline, runbook, decisioni), e <code>etl docs build</code> che non costruisce il sito con una scheda o uno scopo mancante o un link rotto.</li><li><strong>Decisioni tracciate</strong>: il core e ogni repo cliente registrano le loro scelte strutturali.</li><li><strong>Assistenti di qualità</strong> versionati nel kit dell&#39;agente: review ETL, audit dei contratti, sync della doc, autore dei test. Vedi <a href="./guide/claude-code/strumenti">Skill e subagent</a>.</li></ul><h2 id="_9-direzione-del-prodotto-chiara-e-semplice" tabindex="-1">9. Direzione del prodotto (chiara e semplice) <a class="header-anchor" href="#_9-direzione-del-prodotto-chiara-e-semplice" aria-label="Permalink to &quot;9. Direzione del prodotto (chiara e semplice)&quot;">​</a></h2><blockquote><p><strong>Un motore ETL piccolo, code-first e agnostico, che esegue pipeline affidabili e restituisce un risultato completo — e cresce per connettori e pipeline, non per complessità.</strong></p></blockquote><p>Principi guida (stabili):</p><ol><li><strong>Semplice e stateless</strong> — il servizio è una funzione <code>pipeline + config → report</code>.</li><li><strong>Agnostico</strong> — nessun DB interno, nessun cloud obbligato, nessun push integrato.</li><li><strong>Code-first</strong> — niente builder grafici; le pipeline restano codice testato e documentato.</li><li><strong>Portabile</strong> — un&#39;immagine, eseguibile ovunque, configurata da env.</li><li><strong>Espandibile per composizione</strong> — nuovi connettori/trasformazioni/pipeline, core stabile.</li></ol><h3 id="cosa-non-e-non-obiettivi-per-scelta" tabindex="-1">Cosa NON è (non-obiettivi, per scelta) <a class="header-anchor" href="#cosa-non-e-non-obiettivi-per-scelta" aria-label="Permalink to &quot;Cosa NON è (non-obiettivi, per scelta)&quot;">​</a></h3><ul><li>❌ Non è un <strong>pipeline builder</strong> grafico: l&#39;app desktop <code>noeva-etl-ui</code> mostra i DAG e le run, ma le pipeline si scrivono in codice.</li><li>❌ Non è uno <strong>strumento di visualizzazione BI</strong> (per i grafici si collega Metabase/Grafana/Power BI alle tabelle prodotte).</li><li>❌ Non possiede un <strong>database di stato</strong> (storico/audit = archiviazione dei report, a cura del chiamante). Lo stato di pipeline delle source incrementali, cioè i loro watermark, vive in uno store che il chiamante inietta: <code>noeva-server-api</code> per il worker, un file locale per la CLI.</li></ul><h3 id="evoluzioni-possibili-senza-tradire-i-principi" tabindex="-1">Evoluzioni possibili (senza tradire i principi) <a class="header-anchor" href="#evoluzioni-possibili-senza-tradire-i-principi" aria-label="Permalink to &quot;Evoluzioni possibili (senza tradire i principi)&quot;">​</a></h3><ul><li><strong>Scheduling</strong> esterno (cron / ECS Scheduled Task) — l&#39;idempotenza rende sicure retry e sovrapposizioni.</li><li><strong>Nuovi connettori</strong> (data warehouse, code di messaggi) e nuovi resolver per il nodo <code>lookup</code> (oggi PostgreSQL, SQL Server, Noeva, API REST con <code>httpLookup</code> e Jira Cloud con <code>jiraIssueLookup</code> e i lookup delle liste Jira; un nuovo DBMS riusa <code>connectors/shared/sql-lookup.ts</code>).</li><li><strong>Orchestrazione</strong> per dipendenze/backfill complessi (es. Temporal TS), solo se e quando servirà.</li><li><strong>Persistenza opzionale dei report</strong> come <em>adapter</em> lato chiamante, mai dentro il servizio.</li></ul><hr><p><em>Riferimenti: <a href="./GUIDA_SVILUPPO">guida allo sviluppo</a> · <a href="./connectors/README">connettori</a> · <a href="./conventions/run-report">report di run</a> · <a href="./runbooks/deployment">deployment</a> · <a href="./runbooks/etl-worker">etl worker</a> · <a href="./runbooks/graph-server">etl serve</a>.</em></p></div></div></main><footer class="VPDocFooter" data-v-303c7d43 data-v-64d0b887><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-64d0b887><span class="visually-hidden" id="doc-footer-aria-label" data-v-64d0b887>Pager</span><div class="pager" data-v-64d0b887><a class="VPLink link pager-link prev" href="/guida/core/guide/usare/esito-di-una-run" data-v-64d0b887><!--[--><span class="desc" data-v-64d0b887>Pagina precedente</span><span class="title" data-v-64d0b887>Leggere l'esito di una run</span><!--]--></a></div><div class="pager" data-v-64d0b887><a class="VPLink link pager-link next" href="/guida/core/guide/claude-code/" data-v-64d0b887><!--[--><span class="desc" data-v-64d0b887>Pagina successiva</span><span class="title" data-v-64d0b887>Dal bisogno al processo</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><footer class="VPFooter has-sidebar" data-v-f5dee57d data-v-e10de3dd><div class="container" data-v-e10de3dd><p class="message" data-v-e10de3dd>Noeva è un marchio registrato di 4D S.R.L.</p><p class="copyright" data-v-e10de3dd>© 2026 4D S.R.L. · Gruppo4D</p></div></footer><!--[--><span hidden></span><!--]--></div></div>
43
- <script>window.__VP_HASH_MAP__=JSON.parse("{\"connectors_file.md\":\"B1NJe0VJ\",\"connectors_http.md\":\"B8utPijY\",\"connectors_imap.md\":\"CMMpZVXn\",\"connectors_jira.md\":\"0DJvrRXH\",\"connectors_noeva.md\":\"DkxCC8Ey\",\"connectors_oauth.md\":\"DUHajB0u\",\"connectors_postgres.md\":\"DPpHqXkc\",\"connectors_process.md\":\"lQLmWbGN\",\"connectors_readme.md\":\"ChyXSf73\",\"connectors_sendgrid.md\":\"dJzIWepq\",\"connectors_smtp.md\":\"DXXvaNxD\",\"connectors_sqlserver.md\":\"D1sYNLEq\",\"conventions_node-columns.md\":\"D9K1peUx\",\"conventions_node-descriptor.md\":\"D8Si7E2S\",\"conventions_run-report.md\":\"D_pG07VG\",\"conventions_run-trace.md\":\"nKS_RgLC\",\"conventions_variabili-del-core.md\":\"BU6BD6w_\",\"conventions_versioni-di-pipeline.md\":\"cy5nsizS\",\"guida_sviluppo.md\":\"Dj20s7gS\",\"guide_claude-code_index.md\":\"CxVSru8e\",\"guide_claude-code_prompt.md\":\"C7uETA9W\",\"guide_claude-code_strumenti.md\":\"BWhQnAlY\",\"guide_grafo.md\":\"Dy8_YMeh\",\"guide_usare_app-desktop.md\":\"CcDu8cJL\",\"guide_usare_esito-di-una-run.md\":\"DkvAOPBE\",\"guide_usare_index.md\":\"BJqi3P7J\",\"index.md\":\"kMhsF-sv\",\"nodes_action.md\":\"DOsTbV-i\",\"nodes_ai.md\":\"CVtP9gEJ\",\"nodes_join.md\":\"DSYbIDG6\",\"nodes_lookup.md\":\"BI8tgBIq\",\"nodes_pipeline.md\":\"DIMlyprm\",\"nodes_readme.md\":\"CHGy_go6\",\"nodes_route.md\":\"Bt9qH6OA\",\"nodes_sink.md\":\"yAf_z4wO\",\"nodes_source.md\":\"V_vlNfOz\",\"nodes_task.md\":\"Dk6VB7as\",\"nodes_transform.md\":\"Bv5fg2Xx\",\"nodes_try-catch.md\":\"DCYydDPm\",\"nodes_union.md\":\"CznVzHTK\",\"pipelines_crm-leads-sync.md\":\"BlZUnxYn\",\"pipelines_cross-workspace-csv-merge.md\":\"CsRE6GNe\",\"pipelines_movimenti-per-conto.md\":\"DRGfO1_5\",\"pipelines_orders-enriched-daily.md\":\"jESRtvBo\",\"pipelines_readme.md\":\"Ee6LS-SU\",\"pipelines_test-posta.md\":\"Cxo_DGBs\",\"runbooks_aggiornamento-pm2.md\":\"f3LAxif4\",\"runbooks_deployment.md\":\"DvIOOsoG\",\"runbooks_etl-worker.md\":\"Bu05cEgT\",\"runbooks_graph-server.md\":\"BOXZqdXC\",\"runbooks_mask-key.md\":\"nZkhAjBf\",\"runbooks_oauth-google-posta.md\":\"Bs7QTkmU\",\"runbooks_rollback-di-pipeline.md\":\"6US0Wsdc\",\"runbooks_scd2-rehash.md\":\"DtmuXA67\",\"runbooks_sql-task-truncate-swap.md\":\"C8viT-fp\",\"runbooks_stato-incrementale.md\":\"hGZ8FlbZ\",\"sub-pipelines_readme.md\":\"CF8gmNPU\",\"sub-pipelines_riepilogo-ordini.md\":\"qCBZJ4nh\",\"technical_overview.md\":\"DQP0pWc8\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"it-IT\",\"dir\":\"ltr\",\"title\":\"Noeva ETL\",\"titleTemplate\":\":title · Noeva ETL\",\"description\":\"Documentazione di Noeva ETL: come usare la piattaforma e come creare pipeline con Claude Code.\",\"base\":\"/guida/core/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":{\"light\":\"/logo-dark.png\",\"dark\":\"/logo-light.png\",\"alt\":\"Noeva\"},\"siteTitle\":false,\"footer\":{\"message\":\"Noeva è un marchio registrato di 4D S.R.L.\",\"copyright\":\"© 2026 4D S.R.L. · Gruppo4D\"},\"outline\":{\"level\":[2,3],\"label\":\"In questa pagina\"},\"docFooter\":{\"prev\":\"Pagina precedente\",\"next\":\"Pagina successiva\"},\"darkModeSwitchLabel\":\"Tema\",\"lightModeSwitchTitle\":\"Passa al tema chiaro\",\"darkModeSwitchTitle\":\"Passa al tema scuro\",\"sidebarMenuLabel\":\"Menu\",\"returnToTopLabel\":\"Torna su\",\"langMenuLabel\":\"Lingua\",\"notFound\":{\"title\":\"PAGINA NON TROVATA\",\"quote\":\"Il documento che cercavi non c'è più, o non è mai stato pubblicato qui.\",\"linkLabel\":\"Torna alla home\",\"linkText\":\"Torna alla home\"},\"search\":{\"provider\":\"local\",\"options\":{\"translations\":{\"button\":{\"buttonText\":\"Cerca\",\"buttonAriaLabel\":\"Cerca nella documentazione\"},\"modal\":{\"displayDetails\":\"Mostra i dettagli\",\"resetButtonTitle\":\"Azzera la ricerca\",\"backButtonTitle\":\"Chiudi la ricerca\",\"noResultsText\":\"Nessun risultato per\",\"footer\":{\"selectText\":\"per aprire\",\"selectKeyAriaLabel\":\"invio\",\"navigateText\":\"per spostarti\",\"navigateUpKeyAriaLabel\":\"freccia su\",\"navigateDownKeyAriaLabel\":\"freccia giù\",\"closeText\":\"per chiudere\",\"closeKeyAriaLabel\":\"esc\"}}}}},\"nav\":[{\"text\":\"Usare\",\"link\":\"/guide/usare/\",\"activeMatch\":\"^/guide/usare/\"},{\"text\":\"Creare con Claude Code\",\"link\":\"/guide/claude-code/\",\"activeMatch\":\"^/guide/claude-code/\"},{\"text\":\"Riferimento\",\"items\":[{\"text\":\"Il grafo, nodo per nodo\",\"link\":\"/guide/grafo\"},{\"text\":\"Tipi di nodo\",\"link\":\"/nodes/README\"},{\"text\":\"Connettori\",\"link\":\"/connectors/README\"},{\"text\":\"Pipeline pronte\",\"link\":\"/pipelines/README\"},{\"text\":\"Il report di run\",\"link\":\"/conventions/run-report\"},{\"text\":\"La traccia di una run\",\"link\":\"/conventions/run-trace\"},{\"text\":\"Variabili d'ambiente del core\",\"link\":\"/conventions/variabili-del-core\"},{\"text\":\"Operatività\",\"link\":\"/runbooks/graph-server\"}]}],\"sidebar\":[{\"text\":\"Usare Noeva ETL\",\"items\":[{\"text\":\"Come si usa\",\"link\":\"/guide/usare/\"},{\"text\":\"L'app desktop\",\"link\":\"/guide/usare/app-desktop\"},{\"text\":\"Leggere l'esito di una run\",\"link\":\"/guide/usare/esito-di-una-run\"},{\"text\":\"Panoramica di prodotto\",\"link\":\"/TECHNICAL_OVERVIEW\"}]},{\"text\":\"Creare con Claude Code\",\"items\":[{\"text\":\"Dal bisogno al processo\",\"link\":\"/guide/claude-code/\"},{\"text\":\"Comporre il prompt\",\"link\":\"/guide/claude-code/prompt\"},{\"text\":\"Skill e subagent\",\"link\":\"/guide/claude-code/strumenti\"},{\"text\":\"Guida allo sviluppo\",\"link\":\"/GUIDA_SVILUPPO\"}]},{\"text\":\"Concetti\",\"items\":[{\"text\":\"Il grafo, nodo per nodo\",\"link\":\"/guide/grafo\"},{\"text\":\"Il report di run\",\"link\":\"/conventions/run-report\"},{\"text\":\"La traccia di una run\",\"link\":\"/conventions/run-trace\"},{\"text\":\"Versioni di pipeline\",\"link\":\"/conventions/versioni-di-pipeline\"},{\"text\":\"Descriptor dei nodi\",\"link\":\"/conventions/node-descriptor\"},{\"text\":\"Colonne dei nodi\",\"link\":\"/conventions/node-columns\"},{\"text\":\"Variabili d'ambiente del core\",\"link\":\"/conventions/variabili-del-core\"}]},{\"text\":\"Tipi di nodo\",\"collapsed\":true,\"items\":[{\"text\":\"Cheatsheet\",\"link\":\"/nodes/README\"},{\"text\":\"action\",\"link\":\"/nodes/action\"},{\"text\":\"ai\",\"link\":\"/nodes/ai\"},{\"text\":\"join\",\"link\":\"/nodes/join\"},{\"text\":\"lookup\",\"link\":\"/nodes/lookup\"},{\"text\":\"pipeline\",\"link\":\"/nodes/pipeline\"},{\"text\":\"route\",\"link\":\"/nodes/route\"},{\"text\":\"sink\",\"link\":\"/nodes/sink\"},{\"text\":\"source\",\"link\":\"/nodes/source\"},{\"text\":\"task\",\"link\":\"/nodes/task\"},{\"text\":\"transform\",\"link\":\"/nodes/transform\"},{\"text\":\"try-catch\",\"link\":\"/nodes/try-catch\"},{\"text\":\"union\",\"link\":\"/nodes/union\"}]},{\"text\":\"Connettori\",\"collapsed\":true,\"items\":[{\"text\":\"Panoramica\",\"link\":\"/connectors/README\"},{\"text\":\"File (storage × codec)\",\"link\":\"/connectors/file\"},{\"text\":\"HTTP (API REST per i nodi lookup e action)\",\"link\":\"/connectors/http\"},{\"text\":\"IMAP (caselle di posta)\",\"link\":\"/connectors/imap\"},{\"text\":\"Jira Cloud (issue da una JQL o per chiave, liste di una issue, creazione, aggiornamento, transizioni, upsert, commenti, worklog e link)\",\"link\":\"/connectors/jira\"},{\"text\":\"Noeva (file dei workspace)\",\"link\":\"/connectors/noeva\"},{\"text\":\"OAuth2 per i connettori di posta\",\"link\":\"/connectors/oauth\"},{\"text\":\"PostgreSQL\",\"link\":\"/connectors/postgres\"},{\"text\":\"processo esterno\",\"link\":\"/connectors/process\"},{\"text\":\"SendGrid (mail via API REST)\",\"link\":\"/connectors/sendgrid\"},{\"text\":\"SMTP (notifiche email)\",\"link\":\"/connectors/smtp\"},{\"text\":\"SQL Server\",\"link\":\"/connectors/sqlserver\"}]},{\"text\":\"Pipeline pronte\",\"collapsed\":true,\"items\":[{\"text\":\"Le schede di una pipeline\",\"link\":\"/pipelines/README\"},{\"text\":\"test-posta\",\"link\":\"/pipelines/test-posta\"}]},{\"text\":\"Esempi\",\"collapsed\":true,\"items\":[{\"text\":\"Le schede di una sub-pipeline\",\"link\":\"/sub-pipelines/README\"},{\"text\":\"crm-leads-sync\",\"link\":\"/pipelines/crm-leads-sync\"},{\"text\":\"cross-workspace-csv-merge\",\"link\":\"/pipelines/cross-workspace-csv-merge\"},{\"text\":\"movimenti-per-conto\",\"link\":\"/pipelines/movimenti-per-conto\"},{\"text\":\"orders-enriched-daily\",\"link\":\"/pipelines/orders-enriched-daily\"},{\"text\":\"riepilogo-ordini\",\"link\":\"/sub-pipelines/riepilogo-ordini\"}]},{\"text\":\"Operatività\",\"collapsed\":true,\"items\":[{\"text\":\"aggiornare un deploy PM2 di un repo cliente\",\"link\":\"/runbooks/aggiornamento-pm2\"},{\"text\":\"distribuzione del runner ETL\",\"link\":\"/runbooks/deployment\"},{\"text\":\"worker etl worker (polling su processes)\",\"link\":\"/runbooks/etl-worker\"},{\"text\":\"server grafi etl serve (HTTP)\",\"link\":\"/runbooks/graph-server\"},{\"text\":\"chiavi di mask (creazione, rotazione, compromissione)\",\"link\":\"/runbooks/mask-key\"},{\"text\":\"OAuth2 per una casella Google (IMAP + SMTP)\",\"link\":\"/runbooks/oauth-google-posta\"},{\"text\":\"rollback di una pipeline\",\"link\":\"/runbooks/rollback-di-pipeline\"},{\"text\":\"rehash di una dimensione storicizzata\",\"link\":\"/runbooks/scd2-rehash\"},{\"text\":\"task SQL, truncate e scambio di tabelle\",\"link\":\"/runbooks/sql-task-truncate-swap\"},{\"text\":\"stato di pipeline e watermark\",\"link\":\"/runbooks/stato-incrementale\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
43
+ <script>window.__VP_HASH_MAP__=JSON.parse("{\"connectors_file.md\":\"B1NJe0VJ\",\"connectors_http.md\":\"B8utPijY\",\"connectors_imap.md\":\"CMMpZVXn\",\"connectors_jira.md\":\"0DJvrRXH\",\"connectors_noeva.md\":\"DkxCC8Ey\",\"connectors_oauth.md\":\"DUHajB0u\",\"connectors_postgres.md\":\"DPpHqXkc\",\"connectors_process.md\":\"lQLmWbGN\",\"connectors_readme.md\":\"ChyXSf73\",\"connectors_sendgrid.md\":\"dJzIWepq\",\"connectors_smtp.md\":\"DXXvaNxD\",\"connectors_sqlserver.md\":\"D1sYNLEq\",\"conventions_node-columns.md\":\"D9K1peUx\",\"conventions_node-descriptor.md\":\"D8Si7E2S\",\"conventions_run-report.md\":\"D_pG07VG\",\"conventions_run-trace.md\":\"nKS_RgLC\",\"conventions_variabili-del-core.md\":\"BU6BD6w_\",\"conventions_versioni-di-pipeline.md\":\"cy5nsizS\",\"guida_sviluppo.md\":\"D13C7Zwu\",\"guide_claude-code_index.md\":\"CxVSru8e\",\"guide_claude-code_prompt.md\":\"C7uETA9W\",\"guide_claude-code_strumenti.md\":\"BWhQnAlY\",\"guide_grafo.md\":\"Dy8_YMeh\",\"guide_usare_app-desktop.md\":\"CcDu8cJL\",\"guide_usare_esito-di-una-run.md\":\"DkvAOPBE\",\"guide_usare_index.md\":\"BJqi3P7J\",\"index.md\":\"kMhsF-sv\",\"nodes_action.md\":\"DOsTbV-i\",\"nodes_ai.md\":\"CVtP9gEJ\",\"nodes_join.md\":\"DSYbIDG6\",\"nodes_lookup.md\":\"BI8tgBIq\",\"nodes_pipeline.md\":\"DIMlyprm\",\"nodes_readme.md\":\"CHGy_go6\",\"nodes_route.md\":\"Bt9qH6OA\",\"nodes_sink.md\":\"yAf_z4wO\",\"nodes_source.md\":\"V_vlNfOz\",\"nodes_task.md\":\"Dk6VB7as\",\"nodes_transform.md\":\"Bv5fg2Xx\",\"nodes_try-catch.md\":\"DCYydDPm\",\"nodes_union.md\":\"CznVzHTK\",\"pipelines_crm-leads-sync.md\":\"BlZUnxYn\",\"pipelines_cross-workspace-csv-merge.md\":\"CsRE6GNe\",\"pipelines_movimenti-per-conto.md\":\"DRGfO1_5\",\"pipelines_orders-enriched-daily.md\":\"jESRtvBo\",\"pipelines_readme.md\":\"Ee6LS-SU\",\"pipelines_test-posta.md\":\"Cxo_DGBs\",\"runbooks_aggiornamento-pm2.md\":\"f3LAxif4\",\"runbooks_deployment.md\":\"DvIOOsoG\",\"runbooks_etl-worker.md\":\"Bu05cEgT\",\"runbooks_graph-server.md\":\"BOXZqdXC\",\"runbooks_mask-key.md\":\"nZkhAjBf\",\"runbooks_oauth-google-posta.md\":\"Bs7QTkmU\",\"runbooks_rollback-di-pipeline.md\":\"6US0Wsdc\",\"runbooks_scd2-rehash.md\":\"DtmuXA67\",\"runbooks_sql-task-truncate-swap.md\":\"C8viT-fp\",\"runbooks_stato-incrementale.md\":\"hGZ8FlbZ\",\"sub-pipelines_readme.md\":\"CF8gmNPU\",\"sub-pipelines_riepilogo-ordini.md\":\"qCBZJ4nh\",\"technical_overview.md\":\"DQP0pWc8\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"it-IT\",\"dir\":\"ltr\",\"title\":\"Noeva ETL\",\"titleTemplate\":\":title · Noeva ETL\",\"description\":\"Documentazione di Noeva ETL: come usare la piattaforma e come creare pipeline con Claude Code.\",\"base\":\"/guida/core/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":{\"light\":\"/logo-dark.png\",\"dark\":\"/logo-light.png\",\"alt\":\"Noeva\"},\"siteTitle\":false,\"footer\":{\"message\":\"Noeva è un marchio registrato di 4D S.R.L.\",\"copyright\":\"© 2026 4D S.R.L. · Gruppo4D\"},\"outline\":{\"level\":[2,3],\"label\":\"In questa pagina\"},\"docFooter\":{\"prev\":\"Pagina precedente\",\"next\":\"Pagina successiva\"},\"darkModeSwitchLabel\":\"Tema\",\"lightModeSwitchTitle\":\"Passa al tema chiaro\",\"darkModeSwitchTitle\":\"Passa al tema scuro\",\"sidebarMenuLabel\":\"Menu\",\"returnToTopLabel\":\"Torna su\",\"langMenuLabel\":\"Lingua\",\"notFound\":{\"title\":\"PAGINA NON TROVATA\",\"quote\":\"Il documento che cercavi non c'è più, o non è mai stato pubblicato qui.\",\"linkLabel\":\"Torna alla home\",\"linkText\":\"Torna alla home\"},\"search\":{\"provider\":\"local\",\"options\":{\"translations\":{\"button\":{\"buttonText\":\"Cerca\",\"buttonAriaLabel\":\"Cerca nella documentazione\"},\"modal\":{\"displayDetails\":\"Mostra i dettagli\",\"resetButtonTitle\":\"Azzera la ricerca\",\"backButtonTitle\":\"Chiudi la ricerca\",\"noResultsText\":\"Nessun risultato per\",\"footer\":{\"selectText\":\"per aprire\",\"selectKeyAriaLabel\":\"invio\",\"navigateText\":\"per spostarti\",\"navigateUpKeyAriaLabel\":\"freccia su\",\"navigateDownKeyAriaLabel\":\"freccia giù\",\"closeText\":\"per chiudere\",\"closeKeyAriaLabel\":\"esc\"}}}}},\"nav\":[{\"text\":\"Usare\",\"link\":\"/guide/usare/\",\"activeMatch\":\"^/guide/usare/\"},{\"text\":\"Creare con Claude Code\",\"link\":\"/guide/claude-code/\",\"activeMatch\":\"^/guide/claude-code/\"},{\"text\":\"Riferimento\",\"items\":[{\"text\":\"Il grafo, nodo per nodo\",\"link\":\"/guide/grafo\"},{\"text\":\"Tipi di nodo\",\"link\":\"/nodes/README\"},{\"text\":\"Connettori\",\"link\":\"/connectors/README\"},{\"text\":\"Pipeline pronte\",\"link\":\"/pipelines/README\"},{\"text\":\"Il report di run\",\"link\":\"/conventions/run-report\"},{\"text\":\"La traccia di una run\",\"link\":\"/conventions/run-trace\"},{\"text\":\"Variabili d'ambiente del core\",\"link\":\"/conventions/variabili-del-core\"},{\"text\":\"Operatività\",\"link\":\"/runbooks/graph-server\"}]}],\"sidebar\":[{\"text\":\"Usare Noeva ETL\",\"items\":[{\"text\":\"Come si usa\",\"link\":\"/guide/usare/\"},{\"text\":\"L'app desktop\",\"link\":\"/guide/usare/app-desktop\"},{\"text\":\"Leggere l'esito di una run\",\"link\":\"/guide/usare/esito-di-una-run\"},{\"text\":\"Panoramica di prodotto\",\"link\":\"/TECHNICAL_OVERVIEW\"}]},{\"text\":\"Creare con Claude Code\",\"items\":[{\"text\":\"Dal bisogno al processo\",\"link\":\"/guide/claude-code/\"},{\"text\":\"Comporre il prompt\",\"link\":\"/guide/claude-code/prompt\"},{\"text\":\"Skill e subagent\",\"link\":\"/guide/claude-code/strumenti\"},{\"text\":\"Guida allo sviluppo\",\"link\":\"/GUIDA_SVILUPPO\"}]},{\"text\":\"Concetti\",\"items\":[{\"text\":\"Il grafo, nodo per nodo\",\"link\":\"/guide/grafo\"},{\"text\":\"Il report di run\",\"link\":\"/conventions/run-report\"},{\"text\":\"La traccia di una run\",\"link\":\"/conventions/run-trace\"},{\"text\":\"Versioni di pipeline\",\"link\":\"/conventions/versioni-di-pipeline\"},{\"text\":\"Descriptor dei nodi\",\"link\":\"/conventions/node-descriptor\"},{\"text\":\"Colonne dei nodi\",\"link\":\"/conventions/node-columns\"},{\"text\":\"Variabili d'ambiente del core\",\"link\":\"/conventions/variabili-del-core\"}]},{\"text\":\"Tipi di nodo\",\"collapsed\":true,\"items\":[{\"text\":\"Cheatsheet\",\"link\":\"/nodes/README\"},{\"text\":\"action\",\"link\":\"/nodes/action\"},{\"text\":\"ai\",\"link\":\"/nodes/ai\"},{\"text\":\"join\",\"link\":\"/nodes/join\"},{\"text\":\"lookup\",\"link\":\"/nodes/lookup\"},{\"text\":\"pipeline\",\"link\":\"/nodes/pipeline\"},{\"text\":\"route\",\"link\":\"/nodes/route\"},{\"text\":\"sink\",\"link\":\"/nodes/sink\"},{\"text\":\"source\",\"link\":\"/nodes/source\"},{\"text\":\"task\",\"link\":\"/nodes/task\"},{\"text\":\"transform\",\"link\":\"/nodes/transform\"},{\"text\":\"try-catch\",\"link\":\"/nodes/try-catch\"},{\"text\":\"union\",\"link\":\"/nodes/union\"}]},{\"text\":\"Connettori\",\"collapsed\":true,\"items\":[{\"text\":\"Panoramica\",\"link\":\"/connectors/README\"},{\"text\":\"File (storage × codec)\",\"link\":\"/connectors/file\"},{\"text\":\"HTTP (API REST per i nodi lookup e action)\",\"link\":\"/connectors/http\"},{\"text\":\"IMAP (caselle di posta)\",\"link\":\"/connectors/imap\"},{\"text\":\"Jira Cloud (issue da una JQL o per chiave, liste di una issue, creazione, aggiornamento, transizioni, upsert, commenti, worklog e link)\",\"link\":\"/connectors/jira\"},{\"text\":\"Noeva (file dei workspace)\",\"link\":\"/connectors/noeva\"},{\"text\":\"OAuth2 per i connettori di posta\",\"link\":\"/connectors/oauth\"},{\"text\":\"PostgreSQL\",\"link\":\"/connectors/postgres\"},{\"text\":\"processo esterno\",\"link\":\"/connectors/process\"},{\"text\":\"SendGrid (mail via API REST)\",\"link\":\"/connectors/sendgrid\"},{\"text\":\"SMTP (notifiche email)\",\"link\":\"/connectors/smtp\"},{\"text\":\"SQL Server\",\"link\":\"/connectors/sqlserver\"}]},{\"text\":\"Pipeline pronte\",\"collapsed\":true,\"items\":[{\"text\":\"Le schede di una pipeline\",\"link\":\"/pipelines/README\"},{\"text\":\"test-posta\",\"link\":\"/pipelines/test-posta\"}]},{\"text\":\"Esempi\",\"collapsed\":true,\"items\":[{\"text\":\"Le schede di una sub-pipeline\",\"link\":\"/sub-pipelines/README\"},{\"text\":\"crm-leads-sync\",\"link\":\"/pipelines/crm-leads-sync\"},{\"text\":\"cross-workspace-csv-merge\",\"link\":\"/pipelines/cross-workspace-csv-merge\"},{\"text\":\"movimenti-per-conto\",\"link\":\"/pipelines/movimenti-per-conto\"},{\"text\":\"orders-enriched-daily\",\"link\":\"/pipelines/orders-enriched-daily\"},{\"text\":\"riepilogo-ordini\",\"link\":\"/sub-pipelines/riepilogo-ordini\"}]},{\"text\":\"Operatività\",\"collapsed\":true,\"items\":[{\"text\":\"aggiornare un deploy PM2 di un repo cliente\",\"link\":\"/runbooks/aggiornamento-pm2\"},{\"text\":\"distribuzione del runner ETL\",\"link\":\"/runbooks/deployment\"},{\"text\":\"worker etl worker (polling su processes)\",\"link\":\"/runbooks/etl-worker\"},{\"text\":\"server grafi etl serve (HTTP)\",\"link\":\"/runbooks/graph-server\"},{\"text\":\"chiavi di mask (creazione, rotazione, compromissione)\",\"link\":\"/runbooks/mask-key\"},{\"text\":\"OAuth2 per una casella Google (IMAP + SMTP)\",\"link\":\"/runbooks/oauth-google-posta\"},{\"text\":\"rollback di una pipeline\",\"link\":\"/runbooks/rollback-di-pipeline\"},{\"text\":\"rehash di una dimensione storicizzata\",\"link\":\"/runbooks/scd2-rehash\"},{\"text\":\"task SQL, truncate e scambio di tabelle\",\"link\":\"/runbooks/sql-task-truncate-swap\"},{\"text\":\"stato di pipeline e watermark\",\"link\":\"/runbooks/stato-incrementale\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
44
44
 
45
45
  </body>
46
46
  </html>
@@ -13,7 +13,7 @@ import{_ as o,o as i,c as a,a5 as s}from"./chunks/framework.qdetmeNX.js";const g
13
13
  <span class="line"><span>AGENTS.md # le istruzioni per l&#39;agente, con il blocco del kit</span></span>
14
14
  <span class="line"><span>.github/workflows/ci.yml # la CI: il setup, poi \`etl ci\`</span></span>
15
15
  <span class="line"><span>.github/workflows/image.yml # l&#39;immagine del deploy, a mano o su tag</span></span>
16
- <span class="line"><span>ecosystem.config.cjs # una riga: il deploy sotto PM2</span></span></code></pre></div><p><strong>Crearlo.</strong> <code>etl init &lt;slug&gt;</code> scrive nella cartella corrente il boilerplate del pacchetto, poi lancia <code>git init</code> con un primo commit e crea i branch <code>dev</code>, <code>staging</code> e <code>main</code>, con <code>HEAD</code> su <code>dev</code>. La cartella dev&#39;essere vuota: altrimenti il comando si ferma con exit <code>2</code> senza scrivere niente, e lo stesso vale per uno slug che non è fatto di minuscole, cifre e trattini. Senza un&#39;identità di git si ferma prima di scrivere, con exit <code>1</code>. Non crea il repo su GitHub né il secret del PAT, che restano a mano. Il boilerplate è magro, perché ciò che deve evolvere arriva per dipendenza:</p><table tabindex="0"><thead><tr><th>File</th><th>Cosa contiene</th></tr></thead><tbody><tr><td><code>package.json</code></td><td><code>noeva-etl-&lt;slug&gt;</code>, ESM, il core alla versione che genera il repo, il <code>packageManager</code> del core, gli alias <code>pipeline:*</code> e la toolchain nelle <code>devDependencies</code></td></tr><tr><td><code>etl.config.ts</code></td><td><code>client</code> e il catalogo vuoto</td></tr><tr><td><code>.env.example</code></td><td>le sole variabili obbligatorie del core (<code>NOEVA_API_BASE_URL</code>, <code>NOEVA_API_KEY</code>, <code>NOEVA_WORKSPACE_ID</code>)</td></tr><tr><td><code>.npmrc</code></td><td>il registry di <code>@my-ginkgo</code> su GitHub Packages, senza token</td></tr><tr><td><code>tsconfig.json</code>, <code>eslint.config.js</code>, <code>vitest.config.ts</code></td><td>una riga sul preset</td></tr><tr><td><code>.gitignore</code></td><td><code>.env</code>, <code>.runs/</code>, <code>.state/</code>, <code>logs/</code> di PM2, il sito costruito, la sua cache e i file temporanei di VitePress, <code>docs/catalogo.md</code></td></tr><tr><td><code>.prettierignore</code></td><td>il lockfile e gli snapshot del piano, che <code>etl versions snapshot</code> scrive con la sua formattazione</td></tr><tr><td><code>src/pipelines/</code>, <code>docs/pipelines/</code></td><td>vuote: le cartelle delle pipeline e le loro schede</td></tr><tr><td><code>AGENTS.md</code>, <code>CLAUDE.md</code></td><td>le istruzioni per l&#39;agente, con il blocco gestito dal core; <code>CLAUDE.md</code> è solo <code>@AGENTS.md</code></td></tr><tr><td><code>.claude/</code></td><td>file gestiti: il kit dell&#39;agente in <code>skills/</code>, <code>agents/</code> e <code>hooks/</code> <code>noeva-etl-*</code>, e la voce dell&#39;hook in <code>settings.json</code> (§10)</td></tr><tr><td><code>.github/workflows/ci.yml</code></td><td>file gestito: checkout con <code>fetch-depth: 0</code>, pnpm e node, install col PAT nel secret <code>NOEVA_ETL_PACKAGES_TOKEN</code>, poi <code>pnpm exec etl ci</code></td></tr><tr><td><code>.github/workflows/image.yml</code></td><td>file gestito: l&#39;immagine col Dockerfile del pacchetto, su <code>ghcr.io/&lt;owner&gt;/noeva-etl-&lt;slug&gt;</code> con tag = SHA, a mano o su tag; il PAT come BuildKit secret</td></tr><tr><td><code>ecosystem.config.cjs</code></td><td>file gestito: una riga su <code>ecosystem()</code> di <code>@noeva/etl-core/pm2</code>, che avvia <code>etl serve</code> sotto PM2</td></tr></tbody></table><p><strong>La toolchain</strong> sta nelle <code>devDependencies</code> del repo: <code>vitest</code>, <code>eslint</code>, <code>typescript</code>, <code>prettier</code> e <code>@types/node</code>, con i range che <code>etl init</code> legge dal <code>package.json</code> del core installato. Con pnpm le dipendenze del core non si vedono dal repo, e senza <code>vitest</code> e <code>@types/node</code> installati lì <code>tsc --noEmit</code> non trova i tipi dei test; con gli stessi range pnpm tiene una sola copia per il core e per il repo. Li riallinea <code>etl upgrade</code> a ogni bump, coi range del core nuovo.</p><p><strong>La CI.</strong> <code>ci.yml</code> non usa workflow riusabili dell&#39;org, così regge al transfer del repo, e gira sulle PR verso <code>dev</code> e <code>main</code> e sui push su <code>main</code>. Il secret <code>NOEVA_ETL_PACKAGES_TOKEN</code> del repo cliente è un <strong>PAT classic <code>read:packages</code></strong> dell&#39;utente invitato, che serve solo a installare il core. Nel repo del core lo stesso nome indica un PAT <code>write:packages</code>, che pubblica il pacchetto: non è lo stesso token.</p><p><strong>I file gestiti.</strong> Il blocco di <code>AGENTS.md</code>, fra <code>&lt;!-- noeva-etl:inizio … --&gt;</code> e <code>&lt;!-- noeva-etl:fine --&gt;</code>, lo scrive <code>etl agent sync</code>; il resto del file è del repo. Dice all&#39;agente di lanciare <code>etl upgrade --check</code> prima di ogni nuovo sviluppo, di leggere il changelog del core prima di ogni bump, e porta le regole su doc nello stesso commit, <code>--realign</code> e i tre rollback. I file gestiti che <code>etl init</code> scrive sono i due YAML (<code>ci.yml</code> e <code>image.yml</code>), <code>ecosystem.config.cjs</code>, il kit dell&#39;agente in <code>.claude/{skills,agents,hooks}/noeva-etl-*</code> con la voce dell&#39;hook in <code>.claude/settings.json</code> (§10), e il blocco di <code>AGENTS.md</code>; tutto il resto è del repo. Un file gestito che il repo vuole tenersi si dichiara in <code>etl.config.ts</code> con <code>unmanaged: [&quot;.github/workflows/ci.yml&quot;]</code> (per il kit, la cartella di una skill, il file di un subagent, <code>AGENTS.md</code> per il blocco o <code>.claude/settings.json</code> per la voce dell&#39;hook), e da lì l&#39;aggiornamento è del repo. <code>image.yml</code> costruisce l&#39;immagine del deploy col Dockerfile del pacchetto (<a href="./runbooks/deployment#immagine-del-repo-cliente">Deploy § Immagine del repo cliente</a>), e <code>ecosystem.config.cjs</code> è la riga che avvia <code>etl serve</code> sotto PM2 (<a href="./runbooks/aggiornamento-pm2">Aggiornare un deploy PM2</a>).</p><p><strong>Il catalogo.</strong> <code>etl.config.ts</code> esporta <code>defineEtlConfig({ client, pipelines })</code>: <code>client</code> è lo slug del cliente, <code>pipelines</code> le pipeline importate come valori. Ogni comando che lavora sulle pipeline (<code>list</code>, <code>plan</code>, <code>run</code>, <code>state</code>, <code>versions</code>, <code>env</code>, <code>catalog</code>, <code>docs</code>, <code>ci</code>, <code>serve</code>, <code>worker</code>) legge questo file: la CLI lo cerca risalendo dalla cartella corrente, e <code>--config &lt;file&gt;</code> lo indica a mano. Il TypeScript gira dai sorgenti con <code>tsx</code>, quindi il <code>package.json</code> del repo dichiara <code>&quot;type&quot;: &quot;module&quot;</code>. Un config assente o che non si importa, un export di forma sbagliata, una voce che non è una <code>RunnablePipeline</code>, un nome ripetuto (anche fra pipeline e sub-pipeline) o un <code>client</code> che non è uno slug fermano il comando con exit <code>2</code> e un errore che nomina la causa; un catalogo vuoto è permesso, con un avviso. Grafi, dispatch del worker e annuncio del catalogo a noeva-server vedono le stesse pipeline: non c&#39;è un registro a parte.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// etl.config.ts</span></span>
16
+ <span class="line"><span>ecosystem.config.cjs # una riga: il deploy sotto PM2</span></span></code></pre></div><p><strong>Crearlo.</strong> <code>etl init &lt;slug&gt;</code> scrive nella cartella corrente il boilerplate del pacchetto, poi lancia <code>git init</code> con un primo commit e crea i branch <code>dev</code>, <code>staging</code> e <code>main</code>, con <code>HEAD</code> su <code>dev</code>. La cartella dev&#39;essere vuota: altrimenti il comando si ferma con exit <code>2</code> senza scrivere niente, e lo stesso vale per uno slug che non è fatto di minuscole, cifre e trattini. Senza un&#39;identità di git si ferma prima di scrivere, con exit <code>1</code>. Non crea il repo su GitHub né il secret del PAT, che restano a mano. Il boilerplate è magro, perché ciò che deve evolvere arriva per dipendenza:</p><table tabindex="0"><thead><tr><th>File</th><th>Cosa contiene</th></tr></thead><tbody><tr><td><code>package.json</code></td><td><code>noeva-etl-&lt;slug&gt;</code>, ESM, il core alla versione che genera il repo, il pnpm del core (fissato nel codice di <code>etl init</code>), gli alias <code>pipeline:*</code> e la toolchain nelle <code>devDependencies</code></td></tr><tr><td><code>etl.config.ts</code></td><td><code>client</code> e il catalogo vuoto</td></tr><tr><td><code>.env.example</code></td><td>le sole variabili obbligatorie del core (<code>NOEVA_API_BASE_URL</code>, <code>NOEVA_API_KEY</code>, <code>NOEVA_WORKSPACE_ID</code>)</td></tr><tr><td><code>.npmrc</code></td><td>il registry di <code>@my-ginkgo</code> su GitHub Packages, senza token</td></tr><tr><td><code>tsconfig.json</code>, <code>eslint.config.js</code>, <code>vitest.config.ts</code></td><td>una riga sul preset</td></tr><tr><td><code>.gitignore</code></td><td><code>.env</code>, <code>.runs/</code>, <code>.state/</code>, <code>logs/</code> di PM2, il sito costruito, la sua cache e i file temporanei di VitePress, <code>docs/catalogo.md</code></td></tr><tr><td><code>.prettierignore</code></td><td>il lockfile e gli snapshot del piano, che <code>etl versions snapshot</code> scrive con la sua formattazione</td></tr><tr><td><code>src/pipelines/</code>, <code>docs/pipelines/</code></td><td>vuote: le cartelle delle pipeline e le loro schede</td></tr><tr><td><code>AGENTS.md</code>, <code>CLAUDE.md</code></td><td>le istruzioni per l&#39;agente, con il blocco gestito dal core; <code>CLAUDE.md</code> è solo <code>@AGENTS.md</code></td></tr><tr><td><code>.claude/</code></td><td>file gestiti: il kit dell&#39;agente in <code>skills/</code>, <code>agents/</code> e <code>hooks/</code> <code>noeva-etl-*</code>, e la voce dell&#39;hook in <code>settings.json</code> (§10)</td></tr><tr><td><code>.github/workflows/ci.yml</code></td><td>file gestito: checkout con <code>fetch-depth: 0</code>, pnpm e node, install col PAT nel secret <code>NOEVA_ETL_PACKAGES_TOKEN</code>, poi <code>pnpm exec etl ci</code></td></tr><tr><td><code>.github/workflows/image.yml</code></td><td>file gestito: l&#39;immagine col Dockerfile del pacchetto, su <code>ghcr.io/&lt;owner&gt;/noeva-etl-&lt;slug&gt;</code> con tag = SHA, a mano o su tag; il PAT come BuildKit secret</td></tr><tr><td><code>ecosystem.config.cjs</code></td><td>file gestito: una riga su <code>ecosystem()</code> di <code>@noeva/etl-core/pm2</code>, che avvia <code>etl serve</code> sotto PM2</td></tr></tbody></table><p><strong>La toolchain</strong> sta nelle <code>devDependencies</code> del repo: <code>vitest</code>, <code>eslint</code>, <code>typescript</code>, <code>prettier</code> e <code>@types/node</code>, con i range che <code>etl init</code> legge dal <code>package.json</code> del core installato. Con pnpm le dipendenze del core non si vedono dal repo, e senza <code>vitest</code> e <code>@types/node</code> installati lì <code>tsc --noEmit</code> non trova i tipi dei test; con gli stessi range pnpm tiene una sola copia per il core e per il repo. Li riallinea <code>etl upgrade</code> a ogni bump, coi range del core nuovo.</p><p><strong>La CI.</strong> <code>ci.yml</code> non usa workflow riusabili dell&#39;org, così regge al transfer del repo, e gira sulle PR verso <code>dev</code> e <code>main</code> e sui push su <code>main</code>. Il secret <code>NOEVA_ETL_PACKAGES_TOKEN</code> del repo cliente è un <strong>PAT classic <code>read:packages</code></strong> dell&#39;utente invitato, che serve solo a installare il core. Nel repo del core lo stesso nome indica un PAT <code>write:packages</code>, che pubblica il pacchetto: non è lo stesso token.</p><p><strong>I file gestiti.</strong> Il blocco di <code>AGENTS.md</code>, fra <code>&lt;!-- noeva-etl:inizio … --&gt;</code> e <code>&lt;!-- noeva-etl:fine --&gt;</code>, lo scrive <code>etl agent sync</code>; il resto del file è del repo. Dice all&#39;agente di lanciare <code>etl upgrade --check</code> prima di ogni nuovo sviluppo, di leggere il changelog del core prima di ogni bump, e porta le regole su doc nello stesso commit, <code>--realign</code> e i tre rollback. I file gestiti che <code>etl init</code> scrive sono i due YAML (<code>ci.yml</code> e <code>image.yml</code>), <code>ecosystem.config.cjs</code>, il kit dell&#39;agente in <code>.claude/{skills,agents,hooks}/noeva-etl-*</code> con la voce dell&#39;hook in <code>.claude/settings.json</code> (§10), e il blocco di <code>AGENTS.md</code>; tutto il resto è del repo. Un file gestito che il repo vuole tenersi si dichiara in <code>etl.config.ts</code> con <code>unmanaged: [&quot;.github/workflows/ci.yml&quot;]</code> (per il kit, la cartella di una skill, il file di un subagent, <code>AGENTS.md</code> per il blocco o <code>.claude/settings.json</code> per la voce dell&#39;hook), e da lì l&#39;aggiornamento è del repo. <code>image.yml</code> costruisce l&#39;immagine del deploy col Dockerfile del pacchetto (<a href="./runbooks/deployment#immagine-del-repo-cliente">Deploy § Immagine del repo cliente</a>), e <code>ecosystem.config.cjs</code> è la riga che avvia <code>etl serve</code> sotto PM2 (<a href="./runbooks/aggiornamento-pm2">Aggiornare un deploy PM2</a>).</p><p><strong>Il catalogo.</strong> <code>etl.config.ts</code> esporta <code>defineEtlConfig({ client, pipelines })</code>: <code>client</code> è lo slug del cliente, <code>pipelines</code> le pipeline importate come valori. Ogni comando che lavora sulle pipeline (<code>list</code>, <code>plan</code>, <code>run</code>, <code>state</code>, <code>versions</code>, <code>env</code>, <code>catalog</code>, <code>docs</code>, <code>ci</code>, <code>serve</code>, <code>worker</code>) legge questo file: la CLI lo cerca risalendo dalla cartella corrente, e <code>--config &lt;file&gt;</code> lo indica a mano. Il TypeScript gira dai sorgenti con <code>tsx</code>, quindi il <code>package.json</code> del repo dichiara <code>&quot;type&quot;: &quot;module&quot;</code>. Un config assente o che non si importa, un export di forma sbagliata, una voce che non è una <code>RunnablePipeline</code>, un nome ripetuto (anche fra pipeline e sub-pipeline) o un <code>client</code> che non è uno slug fermano il comando con exit <code>2</code> e un errore che nomina la causa; un catalogo vuoto è permesso, con un avviso. Grafi, dispatch del worker e annuncio del catalogo a noeva-server vedono le stesse pipeline: non c&#39;è un registro a parte.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// etl.config.ts</span></span>
17
17
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineEtlConfig } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@noeva/etl-core&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
18
18
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { testPosta } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@noeva/etl-core/pipelines&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
19
19
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { fattureDaily } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;./src/pipelines/fatture-daily/run.js&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
@@ -1 +1 @@
1
- import{t as p}from"./chunks/theme.Bq6mfDhZ.js";import{R as s,a8 as i,a9 as u,aa as c,ab as l,ac as f,ad as d,ae as m,af as h,ag as g,ah as A,d as v,u as y,v as C,s as P,ai as b,aj as w,ak as R,a7 as E}from"./chunks/framework.qdetmeNX.js";function r(e){if(e.extends){const a=r(e.extends);return{...a,...e,async enhanceApp(t){a.enhanceApp&&await a.enhanceApp(t),e.enhanceApp&&await e.enhanceApp(t)}}}return e}const n=r(p),S=v({name:"VitePressApp",setup(){const{site:e,lang:a,dir:t}=y();return C(()=>{P(()=>{document.documentElement.lang=a.value,document.documentElement.dir=t.value})}),e.value.router.prefetchLinks&&b(),w(),R(),n.setup&&n.setup(),()=>E(n.Layout)}});async function T(){globalThis.__VITEPRESS__=!0;const e=D(),a=j();a.provide(u,e);const t=c(e.route);return a.provide(l,t),a.component("Content",f),a.component("ClientOnly",d),Object.defineProperties(a.config.globalProperties,{$frontmatter:{get(){return t.frontmatter.value}},$params:{get(){return t.page.value.params}}}),n.enhanceApp&&await n.enhanceApp({app:a,router:e,siteData:m}),{app:a,router:e,data:t}}function j(){return A(S)}function D(){let e=s;return h(a=>{let t=g(a),o=null;return t&&(e&&(t=t.replace(/\.js$/,".lean.js")),o=import(t)),s&&(e=!1),o},n.NotFound)}s&&T().then(({app:e,router:a,data:t})=>{a.go().then(()=>{i(a.route,t.site),e.mount("#app")})});export{T as createApp};
1
+ import{t as p}from"./chunks/theme.DV62mViB.js";import{R as s,a8 as i,a9 as u,aa as c,ab as l,ac as f,ad as d,ae as m,af as h,ag as g,ah as A,d as v,u as y,v as C,s as P,ai as b,aj as w,ak as R,a7 as E}from"./chunks/framework.qdetmeNX.js";function r(e){if(e.extends){const a=r(e.extends);return{...a,...e,async enhanceApp(t){a.enhanceApp&&await a.enhanceApp(t),e.enhanceApp&&await e.enhanceApp(t)}}}return e}const n=r(p),S=v({name:"VitePressApp",setup(){const{site:e,lang:a,dir:t}=y();return C(()=>{P(()=>{document.documentElement.lang=a.value,document.documentElement.dir=t.value})}),e.value.router.prefetchLinks&&b(),w(),R(),n.setup&&n.setup(),()=>E(n.Layout)}});async function T(){globalThis.__VITEPRESS__=!0;const e=D(),a=j();a.provide(u,e);const t=c(e.route);return a.provide(l,t),a.component("Content",f),a.component("ClientOnly",d),Object.defineProperties(a.config.globalProperties,{$frontmatter:{get(){return t.frontmatter.value}},$params:{get(){return t.page.value.params}}}),n.enhanceApp&&await n.enhanceApp({app:a,router:e,siteData:m}),{app:a,router:e,data:t}}function j(){return A(S)}function D(){let e=s;return h(a=>{let t=g(a),o=null;return t&&(e&&(t=t.replace(/\.js$/,".lean.js")),o=import(t)),s&&(e=!1),o},n.NotFound)}s&&T().then(({app:e,router:a,data:t})=>{a.go().then(()=>{i(a.route,t.site),e.mount("#app")})});export{T as createApp};