@noeva/etl-core 1.0.0-next.4 → 1.0.0
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.
- package/CHANGELOG.md +183 -0
- package/LICENSE +19 -0
- package/README.md +3 -2
- package/deploy/Dockerfile +1 -1
- package/dist/chunk-BVUOUBLW.js +1 -0
- package/dist/chunk-CRR3Q2C7.js +2 -0
- package/dist/chunk-J3PBMWSP.js +2 -0
- package/dist/{chunk-KMUNED7K.js → chunk-LJ7DVP5F.js} +1 -1
- package/dist/{chunk-ZBKP2UOF.js → chunk-P6B2KLNJ.js} +2 -2
- package/dist/chunk-PKBSETMV.js +2 -0
- package/dist/chunk-QPJC4GWR.js +1 -0
- package/dist/chunk-RCRMQPFH.js +5 -0
- package/dist/chunk-RS5SGDUU.js +1 -0
- package/dist/chunk-RWPHH4E2.js +1 -0
- package/dist/chunk-SRFFKE5W.js +6 -0
- package/dist/chunk-WVODQB6Z.js +1 -0
- package/dist/chunk-XZMCC6VQ.js +1 -0
- package/dist/chunk-ZCYGHS7P.js +2 -0
- package/dist/cli.js +2 -2
- package/dist/connector-kit.d.ts +4 -2
- package/dist/connector-kit.js +1 -1
- package/dist/connectors/file.js +1 -1
- package/dist/connectors/http.js +1 -1
- package/dist/connectors/imap.js +1 -1
- package/dist/connectors/jira.js +2 -2
- package/dist/connectors/mail.js +1 -1
- package/dist/connectors/noeva.js +1 -1
- package/dist/connectors/oauth.js +1 -1
- package/dist/connectors/postgres.js +1 -1
- package/dist/connectors/sendgrid.js +1 -1
- package/dist/connectors/smtp.js +1 -1
- package/dist/connectors/sqlserver.js +1 -1
- package/dist/connectors/zoho.d.ts +304 -0
- package/dist/connectors/zoho.js +2 -0
- package/dist/etl.config.js +2 -2
- package/dist/guida/404.html +3 -3
- package/dist/guida/GUIDA_SVILUPPO.html +8 -8
- package/dist/guida/TECHNICAL_OVERVIEW.html +8 -8
- package/dist/guida/assets/{GUIDA_SVILUPPO.md.D13C7Zwu.js → GUIDA_SVILUPPO.md.CrN52ZDN.js} +1 -1
- package/dist/guida/assets/{TECHNICAL_OVERVIEW.md.DQP0pWc8.js → TECHNICAL_OVERVIEW.md.DTIhkkg9.js} +1 -1
- package/dist/guida/assets/{app.CzIZwOrR.js → app.DlsuGVZn.js} +1 -1
- package/dist/guida/assets/chunks/@localSearchIndexroot.LnC621Vy.js +1 -0
- package/dist/guida/assets/chunks/{VPLocalSearchBox.Cv9o56BQ.js → VPLocalSearchBox.v4vBLemj.js} +2 -2
- package/dist/guida/assets/chunks/{theme.CsUxYN72.js → theme.D9XEK7o0.js} +2 -2
- package/dist/guida/assets/connectors_README.md.BqI2RLCu.js +1 -0
- package/dist/guida/assets/connectors_README.md.BqI2RLCu.lean.js +1 -0
- package/dist/guida/assets/connectors_oauth.md.BeotXAWb.js +7 -0
- package/dist/guida/assets/connectors_oauth.md.BeotXAWb.lean.js +1 -0
- package/dist/guida/assets/connectors_zoho.md.BfEzRNZk.js +17 -0
- package/dist/guida/assets/connectors_zoho.md.BfEzRNZk.lean.js +1 -0
- package/dist/guida/assets/{conventions_node-descriptor.md.D8Si7E2S.js → conventions_node-descriptor.md.MQaGlm8a.js} +1 -1
- package/dist/guida/assets/{guide_claude-code_index.md.CxVSru8e.js → guide_claude-code_index.md.DEnzf9b_.js} +1 -1
- package/dist/guida/assets/{nodes_source.md.V_vlNfOz.js → nodes_source.md.DP2i3GFv.js} +3 -3
- package/dist/guida/assets/{nodes_source.md.V_vlNfOz.lean.js → nodes_source.md.DP2i3GFv.lean.js} +1 -1
- package/dist/guida/assets/{runbooks_aggiornamento-pm2.md.f3LAxif4.js → runbooks_aggiornamento-pm2.md.DrFr4blI.js} +1 -1
- package/dist/guida/assets/{runbooks_deployment.md.CsIYRa_5.js → runbooks_deployment.md.CwG77qGO.js} +1 -1
- package/dist/guida/assets/{style.BNn_AkzN.css → style.DFlUbYCk.css} +1 -1
- package/dist/guida/connectors/README.html +6 -6
- package/dist/guida/connectors/file.html +6 -6
- package/dist/guida/connectors/http.html +6 -6
- package/dist/guida/connectors/imap.html +6 -6
- package/dist/guida/connectors/jira.html +6 -6
- package/dist/guida/connectors/noeva.html +6 -6
- package/dist/guida/connectors/oauth.html +8 -8
- package/dist/guida/connectors/postgres.html +6 -6
- package/dist/guida/connectors/process.html +6 -6
- package/dist/guida/connectors/sendgrid.html +6 -6
- package/dist/guida/connectors/smtp.html +6 -6
- package/dist/guida/connectors/sqlserver.html +6 -6
- package/dist/guida/connectors/zoho.html +43 -0
- package/dist/guida/conventions/node-columns.html +6 -6
- package/dist/guida/conventions/node-descriptor.html +8 -8
- package/dist/guida/conventions/run-report.html +6 -6
- package/dist/guida/conventions/run-trace.html +6 -6
- package/dist/guida/conventions/variabili-del-core.html +5 -5
- package/dist/guida/conventions/versioni-di-pipeline.html +6 -6
- package/dist/guida/guide/claude-code/index.html +7 -7
- package/dist/guida/guide/claude-code/prompt.html +7 -7
- package/dist/guida/guide/claude-code/strumenti.html +5 -5
- package/dist/guida/guide/grafo.html +6 -6
- package/dist/guida/guide/usare/app-desktop.html +5 -5
- package/dist/guida/guide/usare/esito-di-una-run.html +6 -6
- package/dist/guida/guide/usare/index.html +5 -5
- package/dist/guida/hashmap.json +1 -1
- package/dist/guida/index.html +6 -6
- package/dist/guida/nodes/README.html +6 -6
- package/dist/guida/nodes/action.html +6 -6
- package/dist/guida/nodes/ai.html +6 -6
- package/dist/guida/nodes/join.html +6 -6
- package/dist/guida/nodes/lookup.html +6 -6
- package/dist/guida/nodes/pipeline.html +6 -6
- package/dist/guida/nodes/route.html +6 -6
- package/dist/guida/nodes/sink.html +6 -6
- package/dist/guida/nodes/source.html +8 -8
- package/dist/guida/nodes/task.html +6 -6
- package/dist/guida/nodes/transform.html +6 -6
- package/dist/guida/nodes/try-catch.html +6 -6
- package/dist/guida/nodes/union.html +6 -6
- package/dist/guida/pagine.json +1 -0
- package/dist/guida/pipelines/README.html +6 -6
- package/dist/guida/pipelines/crm-leads-sync.html +6 -6
- package/dist/guida/pipelines/cross-workspace-csv-merge.html +6 -6
- package/dist/guida/pipelines/movimenti-per-conto.html +6 -6
- package/dist/guida/pipelines/orders-enriched-daily.html +6 -6
- package/dist/guida/pipelines/test-posta.html +6 -6
- package/dist/guida/runbooks/aggiornamento-pm2.html +7 -7
- package/dist/guida/runbooks/deploy-ecr.html +6 -6
- package/dist/guida/runbooks/deployment.html +8 -8
- package/dist/guida/runbooks/etl-worker.html +6 -6
- package/dist/guida/runbooks/graph-server.html +6 -6
- package/dist/guida/runbooks/mask-key.html +6 -6
- package/dist/guida/runbooks/oauth-google-posta.html +6 -6
- package/dist/guida/runbooks/rollback-di-pipeline.html +6 -6
- package/dist/guida/runbooks/scd2-rehash.html +6 -6
- package/dist/guida/runbooks/sql-task-truncate-swap.html +6 -6
- package/dist/guida/runbooks/stato-incrementale.html +6 -6
- package/dist/guida/sub-pipelines/README.html +6 -6
- package/dist/guida/sub-pipelines/riepilogo-ordini.html +6 -6
- package/dist/index.js +1 -1
- package/dist/pipelines.js +1 -1
- package/dist/testing.js +1 -1
- package/kit/boilerplate/.github/workflows/ci.yml +1 -1
- package/kit/boilerplate/.github/workflows/image.yml +1 -1
- package/kit/boilerplate/package.json +1 -1
- package/kit/skills/etl-graph/references/wiring.md +4 -3
- package/kit/skills/new-connector/SKILL.md +1 -1
- package/package.json +12 -6
- package/dist/chunk-BFW7HTF6.js +0 -2
- package/dist/chunk-BPRH262Y.js +0 -2
- package/dist/chunk-DPWGI266.js +0 -1
- package/dist/chunk-H75NY6Z4.js +0 -1
- package/dist/chunk-HMED2UDJ.js +0 -2
- package/dist/chunk-MOHJWOCB.js +0 -1
- package/dist/chunk-MXSKD3Z4.js +0 -2
- package/dist/chunk-PGJWGJEB.js +0 -5
- package/dist/chunk-R53642SH.js +0 -1
- package/dist/chunk-RU6CZIDB.js +0 -1
- package/dist/chunk-UN3BPCPA.js +0 -1
- package/dist/chunk-XFHTODDW.js +0 -6
- package/dist/guida/assets/chunks/@localSearchIndexroot.08YFQ5n8.js +0 -1
- package/dist/guida/assets/connectors_README.md.ChyXSf73.js +0 -1
- package/dist/guida/assets/connectors_README.md.ChyXSf73.lean.js +0 -1
- package/dist/guida/assets/connectors_oauth.md.DUHajB0u.js +0 -7
- package/dist/guida/assets/connectors_oauth.md.DUHajB0u.lean.js +0 -1
- /package/dist/guida/assets/{GUIDA_SVILUPPO.md.D13C7Zwu.lean.js → GUIDA_SVILUPPO.md.CrN52ZDN.lean.js} +0 -0
- /package/dist/guida/assets/{TECHNICAL_OVERVIEW.md.DQP0pWc8.lean.js → TECHNICAL_OVERVIEW.md.DTIhkkg9.lean.js} +0 -0
- /package/dist/guida/assets/{conventions_node-descriptor.md.D8Si7E2S.lean.js → conventions_node-descriptor.md.MQaGlm8a.lean.js} +0 -0
- /package/dist/guida/assets/{guide_claude-code_index.md.CxVSru8e.lean.js → guide_claude-code_index.md.DEnzf9b_.lean.js} +0 -0
- /package/dist/guida/assets/{runbooks_aggiornamento-pm2.md.f3LAxif4.lean.js → runbooks_aggiornamento-pm2.md.DrFr4blI.lean.js} +0 -0
- /package/dist/guida/assets/{runbooks_deployment.md.CsIYRa_5.lean.js → runbooks_deployment.md.CwG77qGO.lean.js} +0 -0
|
@@ -6,21 +6,21 @@
|
|
|
6
6
|
<title>Guida allo sviluppo · Noeva ETL</title>
|
|
7
7
|
<meta name="description" content="Documentazione di Noeva ETL: come usare la piattaforma e come creare pipeline con Claude Code.">
|
|
8
8
|
<meta name="generator" content="VitePress v1.6.4">
|
|
9
|
-
<link rel="preload stylesheet" href="/guida/core/assets/style.
|
|
9
|
+
<link rel="preload stylesheet" href="/guida/core/assets/style.DFlUbYCk.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.
|
|
12
|
+
<script type="module" src="/guida/core/assets/app.DlsuGVZn.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.
|
|
14
|
+
<link rel="modulepreload" href="/guida/core/assets/chunks/theme.D9XEK7o0.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.
|
|
16
|
+
<link rel="modulepreload" href="/guida/core/assets/GUIDA_SVILUPPO.md.CrN52ZDN.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>
|
|
20
20
|
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
|
|
21
21
|
</head>
|
|
22
22
|
<body>
|
|
23
|
-
<div id="app"><div class="Layout" data-v-f5dee57d><!--[--><!--]--><!--[--><span tabindex="-1" data-v-93360a68></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-93360a68>Skip to content</a><!--]--><!----><header class="VPNav" data-v-f5dee57d data-v-b9fcca01><div class="VPNavBar" data-v-b9fcca01 data-v-b140bbbf><div class="wrapper" data-v-b140bbbf><div class="container" data-v-b140bbbf><div class="title" data-v-b140bbbf><div class="VPNavBarTitle has-sidebar" data-v-b140bbbf data-v-fa0d91f3><a class="title" href="/guida/core/" data-v-fa0d91f3><!--[--><!--]--><!--[--><!--[--><!--[--><img class="VPImage dark logo" src="/guida/core/logo-light.png" alt="Noeva" data-v-05ca73a1><!--]--><!--[--><img class="VPImage light logo" src="/guida/core/logo-dark.png" alt="Noeva" data-v-05ca73a1><!--]--><!--]--><!--]--><!----><!--[--><!--[--><!--[--><!--[--><span class="etl-wordmark" aria-hidden="true">ETL</span><span class="etl-embedded-title">Documentazione</span><!--]--><!--]--><!--]--><!--]--></a></div></div><div class="content" data-v-b140bbbf><div class="content-body" data-v-b140bbbf><!--[--><!--]--><div class="VPNavBarSearch search" data-v-b140bbbf><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Cerca nella documentazione"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Cerca</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-b140bbbf data-v-bc0c15e0><span id="main-nav-aria-label" class="visually-hidden" data-v-bc0c15e0> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/guida/core/guide/usare/" tabindex="0" data-v-bc0c15e0 data-v-5860da0c><!--[--><span data-v-5860da0c>Usare</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/guida/core/guide/claude-code/" tabindex="0" data-v-bc0c15e0 data-v-5860da0c><!--[--><span data-v-5860da0c>Creare con Claude Code</span><!--]--></a><!--]--><!--[--><div class="VPFlyout VPNavBarMenuGroup" data-v-bc0c15e0 data-v-6f404e8a><button type="button" class="button" aria-haspopup="true" aria-expanded="false" data-v-6f404e8a><span class="text" data-v-6f404e8a><!----><span data-v-6f404e8a>Riferimento</span><span class="vpi-chevron-down text-icon" data-v-6f404e8a></span></span></button><div class="menu" data-v-6f404e8a><div class="VPMenu" data-v-6f404e8a data-v-1bb74cb7><div class="items" data-v-1bb74cb7><!--[--><!--[--><div class="VPMenuLink" data-v-1bb74cb7 data-v-8b15bc2d><a class="VPLink link" href="/guida/core/guide/grafo" data-v-8b15bc2d><!--[--><span data-v-8b15bc2d>Il grafo, nodo per nodo</span><!--]--></a></div><!--]--><!--[--><div class="VPMenuLink" data-v-1bb74cb7 data-v-8b15bc2d><a class="VPLink link" href="/guida/core/nodes/README" data-v-8b15bc2d><!--[--><span data-v-8b15bc2d>Tipi di nodo</span><!--]--></a></div><!--]--><!--[--><div class="VPMenuLink" data-v-1bb74cb7 data-v-8b15bc2d><a class="VPLink link" href="/guida/core/connectors/README" data-v-8b15bc2d><!--[--><span data-v-8b15bc2d>Connettori</span><!--]--></a></div><!--]--><!--[--><div class="VPMenuLink" data-v-1bb74cb7 data-v-8b15bc2d><a class="VPLink link" href="/guida/core/pipelines/README" data-v-8b15bc2d><!--[--><span data-v-8b15bc2d>Pipeline pronte</span><!--]--></a></div><!--]--><!--[--><div class="VPMenuLink" data-v-1bb74cb7 data-v-8b15bc2d><a class="VPLink link" href="/guida/core/conventions/run-report" data-v-8b15bc2d><!--[--><span data-v-8b15bc2d>Il report di run</span><!--]--></a></div><!--]--><!--[--><div class="VPMenuLink" data-v-1bb74cb7 data-v-8b15bc2d><a class="VPLink link" href="/guida/core/conventions/run-trace" data-v-8b15bc2d><!--[--><span data-v-8b15bc2d>La traccia di una run</span><!--]--></a></div><!--]--><!--[--><div class="VPMenuLink" data-v-1bb74cb7 data-v-8b15bc2d><a class="VPLink link" href="/guida/core/conventions/variabili-del-core" data-v-8b15bc2d><!--[--><span data-v-8b15bc2d>Variabili d'ambiente del core</span><!--]--></a></div><!--]--><!--[--><div class="VPMenuLink" data-v-1bb74cb7 data-v-8b15bc2d><a class="VPLink link" href="/guida/core/runbooks/graph-server" data-v-8b15bc2d><!--[--><span data-v-8b15bc2d>Operatività</span><!--]--></a></div><!--]--><!--]--></div><!--[--><!--]--></div></div></div><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-b140bbbf data-v-978134ec><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-978134ec data-v-139a0758 data-v-6ae48061><span class="check" data-v-6ae48061><span class="icon" data-v-6ae48061><!--[--><span class="vpi-sun sun" data-v-139a0758></span><span class="vpi-moon moon" data-v-139a0758></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-b140bbbf data-v-0ddd3b74 data-v-6f404e8a><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-6f404e8a><span class="vpi-more-horizontal icon" data-v-6f404e8a></span></button><div class="menu" data-v-6f404e8a><div class="VPMenu" data-v-6f404e8a data-v-1bb74cb7><!----><!--[--><!--[--><!----><div class="group" data-v-0ddd3b74><div class="item appearance" data-v-0ddd3b74><p class="label" data-v-0ddd3b74>Tema</p><div class="appearance-action" data-v-0ddd3b74><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-0ddd3b74 data-v-139a0758 data-v-6ae48061><span class="check" data-v-6ae48061><span class="icon" data-v-6ae48061><!--[--><span class="vpi-sun sun" data-v-139a0758></span><span class="vpi-moon moon" data-v-139a0758></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-b140bbbf data-v-d8d7505f><span class="container" data-v-d8d7505f><span class="top" data-v-d8d7505f></span><span class="middle" data-v-d8d7505f></span><span class="bottom" data-v-d8d7505f></span></span></button></div></div></div></div><div class="divider" data-v-b140bbbf><div class="divider-line" data-v-b140bbbf></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-f5dee57d data-v-cff79b2d><div class="container" data-v-cff79b2d><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-cff79b2d><span class="vpi-align-left menu-icon" data-v-cff79b2d></span><span class="menu-text" data-v-cff79b2d>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-cff79b2d data-v-64e5faff><button data-v-64e5faff>Torna su</button><!----></div></div></div><aside class="VPSidebar" data-v-f5dee57d data-v-24ac7daa><div class="curtain" data-v-24ac7daa></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-24ac7daa><span class="visually-hidden" id="sidebar-aria-label" data-v-24ac7daa> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-4be63f01><section class="VPSidebarItem level-0" data-v-4be63f01 data-v-0fae8093><div class="item" role="button" tabindex="0" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><h2 class="text" data-v-0fae8093>Usare Noeva ETL</h2><!----></div><div class="items" data-v-0fae8093><!--[--><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/guide/usare/" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>Come si usa</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/guide/usare/app-desktop" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>L'app desktop</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/guide/usare/esito-di-una-run" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>Leggere l'esito di una run</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/TECHNICAL_OVERVIEW" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>Panoramica di prodotto</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-4be63f01><section class="VPSidebarItem level-0 has-active" data-v-4be63f01 data-v-0fae8093><div class="item" role="button" tabindex="0" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><h2 class="text" data-v-0fae8093>Creare con Claude Code</h2><!----></div><div class="items" data-v-0fae8093><!--[--><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/guide/claude-code/" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>Dal bisogno al processo</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/guide/claude-code/prompt" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>Comporre il prompt</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/guide/claude-code/strumenti" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>Skill e subagent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/GUIDA_SVILUPPO" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>Guida allo sviluppo</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-4be63f01><section class="VPSidebarItem level-0" data-v-4be63f01 data-v-0fae8093><div class="item" role="button" tabindex="0" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><h2 class="text" data-v-0fae8093>Concetti</h2><!----></div><div class="items" data-v-0fae8093><!--[--><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/guide/grafo" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>Il grafo, nodo per nodo</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/conventions/run-report" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>Il report di run</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/conventions/run-trace" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>La traccia di una run</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/conventions/versioni-di-pipeline" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>Versioni di pipeline</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/conventions/node-descriptor" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>Descriptor dei nodi</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/conventions/node-columns" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>Colonne dei nodi</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/conventions/variabili-del-core" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>Variabili d'ambiente del core</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-4be63f01><section class="VPSidebarItem level-0 collapsible collapsed" data-v-4be63f01 data-v-0fae8093><div class="item" role="button" tabindex="0" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><h2 class="text" data-v-0fae8093>Tipi di nodo</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-0fae8093><span class="vpi-chevron-right caret-icon" data-v-0fae8093></span></div></div><div class="items" data-v-0fae8093><!--[--><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/nodes/README" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>Cheatsheet</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/nodes/action" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>action</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/nodes/ai" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>ai</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/nodes/join" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>join</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/nodes/lookup" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>lookup</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/nodes/pipeline" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>pipeline</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/nodes/route" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>route</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/nodes/sink" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>sink</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/nodes/source" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>source</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/nodes/task" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>task</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/nodes/transform" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>transform</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/nodes/try-catch" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>try-catch</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/nodes/union" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>union</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-4be63f01><section class="VPSidebarItem level-0 collapsible collapsed" data-v-4be63f01 data-v-0fae8093><div class="item" role="button" tabindex="0" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><h2 class="text" data-v-0fae8093>Connettori</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-0fae8093><span class="vpi-chevron-right caret-icon" data-v-0fae8093></span></div></div><div class="items" data-v-0fae8093><!--[--><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/connectors/README" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>Panoramica</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/connectors/file" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>File (storage × codec)</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/connectors/http" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>HTTP (API REST per i nodi lookup e action)</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/connectors/imap" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>IMAP (caselle di posta)</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/connectors/jira" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>Jira Cloud (issue da una JQL o per chiave, liste di una issue, creazione, aggiornamento, transizioni, upsert, commenti, worklog e link)</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/connectors/noeva" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>Noeva (file dei workspace)</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/connectors/oauth" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>OAuth2 per i connettori di posta</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/connectors/postgres" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>PostgreSQL</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/connectors/process" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>processo esterno</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/connectors/sendgrid" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>SendGrid (mail via API REST)</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/connectors/smtp" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>SMTP (notifiche email)</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/connectors/sqlserver" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>SQL Server</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-4be63f01><section class="VPSidebarItem level-0 collapsible collapsed" data-v-4be63f01 data-v-0fae8093><div class="item" role="button" tabindex="0" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><h2 class="text" data-v-0fae8093>Pipeline pronte</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-0fae8093><span class="vpi-chevron-right caret-icon" data-v-0fae8093></span></div></div><div class="items" data-v-0fae8093><!--[--><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/pipelines/README" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>Le schede di una pipeline</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/pipelines/test-posta" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>test-posta</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-4be63f01><section class="VPSidebarItem level-0 collapsible collapsed" data-v-4be63f01 data-v-0fae8093><div class="item" role="button" tabindex="0" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><h2 class="text" data-v-0fae8093>Esempi</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-0fae8093><span class="vpi-chevron-right caret-icon" data-v-0fae8093></span></div></div><div class="items" data-v-0fae8093><!--[--><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/sub-pipelines/README" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>Le schede di una sub-pipeline</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/pipelines/crm-leads-sync" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>crm-leads-sync</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/pipelines/cross-workspace-csv-merge" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>cross-workspace-csv-merge</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/pipelines/movimenti-per-conto" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>movimenti-per-conto</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/pipelines/orders-enriched-daily" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>orders-enriched-daily</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/sub-pipelines/riepilogo-ordini" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>riepilogo-ordini</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-4be63f01><section class="VPSidebarItem level-0 collapsible collapsed" data-v-4be63f01 data-v-0fae8093><div class="item" role="button" tabindex="0" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><h2 class="text" data-v-0fae8093>Operatività</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-0fae8093><span class="vpi-chevron-right caret-icon" data-v-0fae8093></span></div></div><div class="items" data-v-0fae8093><!--[--><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/runbooks/aggiornamento-pm2" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>aggiornare un deploy PM2 di un repo cliente</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/runbooks/deploy-ecr" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>un cliente su ECR + ECS</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/runbooks/deployment" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>distribuzione del runner ETL</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/runbooks/etl-worker" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>worker etl worker (polling su processes)</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/runbooks/graph-server" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>server grafi etl serve (HTTP)</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/runbooks/mask-key" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>chiavi di mask (creazione, rotazione, compromissione)</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/runbooks/oauth-google-posta" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>OAuth2 per una casella Google (IMAP + SMTP)</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/runbooks/rollback-di-pipeline" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>rollback di una pipeline</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/runbooks/scd2-rehash" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>rehash di una dimensione storicizzata</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/runbooks/sql-task-truncate-swap" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>task SQL, truncate e scambio di tabelle</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0fae8093><div class="item" data-v-0fae8093><div class="indicator" data-v-0fae8093></div><a class="VPLink link link" href="/guida/core/runbooks/stato-incrementale" data-v-0fae8093><!--[--><p class="text" data-v-0fae8093>stato di pipeline e watermark</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><!--]--><!--[--><!--]--></nav></aside><div class="VPContent has-sidebar" id="VPContent" data-v-f5dee57d data-v-b2578848><div class="VPDoc has-sidebar has-aside" data-v-b2578848 data-v-303c7d43><!--[--><!--]--><div class="container" data-v-303c7d43><div class="aside" data-v-303c7d43><div class="aside-curtain" data-v-303c7d43></div><div class="aside-container" data-v-303c7d43><div class="aside-content" data-v-303c7d43><div class="VPDocAside" data-v-303c7d43 data-v-50c80a94><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-50c80a94 data-v-ba0e722b><div class="content" data-v-ba0e722b><div class="outline-marker" data-v-ba0e722b></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-ba0e722b>In questa pagina</div><ul class="VPDocOutlineItem root" data-v-ba0e722b data-v-d9a98cc8><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-50c80a94></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-303c7d43><div class="content-container" data-v-303c7d43><!--[--><!--]--><main class="main" data-v-303c7d43><div style="position:relative;" class="vp-doc _guida_core_GUIDA_SVILUPPO" data-v-303c7d43><div><h1 id="guida-allo-sviluppo" tabindex="-1">Guida allo sviluppo <a class="header-anchor" href="#guida-allo-sviluppo" aria-label="Permalink to "Guida allo sviluppo""></a></h1><blockquote><p>Come si scrive una pipeline in un <strong>repo cliente</strong>: le cartelle, il catalogo, l'API pubblica del core, i comandi <code>etl</code> e il kit dell'agente. Per la visione di prodotto vedi la <a href="./TECHNICAL_OVERVIEW">panoramica</a>; per il percorso con Claude Code, <a href="./guide/claude-code/">dal bisogno al processo</a>.</p></blockquote><h2 id="_1-cos-e-in-breve" tabindex="-1">1. Cos'è in breve <a class="header-anchor" href="#_1-cos-e-in-breve" aria-label="Permalink to "1. Cos'è in breve""></a></h2><p>Noeva ETL è un motore ETL <strong>code-first</strong>: le pipeline di integrazione dati (estrazione → trasformazione → caricamento) sono scritte in TypeScript, testate con vitest e documentate — non job grafici stile Talend, ma software vero.</p><p>Il motore è il <strong>core</strong>, il pacchetto <code>@noeva/etl-core</code>: nodi, connettori, transform, la CLI <code>etl</code> e questa guida. Le pipeline di un cliente vivono nel suo <strong>repo cliente</strong>, <code>noeva-etl-<slug></code>, che dipende dal core e ne usa solo l'API pubblica. Un deploy esegue un repo cliente: le sue pipeline, con la versione del core che il repo dichiara.</p><p>Il servizio è <strong>stateless</strong>: non ha un proprio database, esegue una pipeline e restituisce un <code>GraphRunReport</code> (JSON). La CLI <code>etl</code> si avvia in tre modi:</p><ul><li><strong><code>etl serve</code></strong> — il modo di un deploy: nello stesso processo espone i grafi via HTTP, per l'app desktop, <strong>e</strong> avvia i worker. Vedi <a href="./runbooks/graph-server">il runbook di <code>etl serve</code></a>.</li><li><strong><code>etl worker</code></strong> — solo il <strong>daemon</strong>: resta in polling sulla tabella <code>processes</code> di Noeva, sempre attraverso noeva-server-api, ed esegue le pipeline dei job che Noeva crea (lanci dall'app, job pianificati). Mai insieme a un <code>etl serve</code> nello stesso ambiente, o i job vengono presi due volte. Vedi <a href="./runbooks/etl-worker">il runbook del worker</a>.</li><li><strong><code>etl run <pipeline></code></strong> — batch: una esecuzione, report su stdout, poi termina. Con <code>--trace</code> è una run tracciata, che salva anche la traccia dei record (<a href="./conventions/run-trace">La traccia di una run</a>).</li></ul><p>In tutti e tre i casi il nucleo che esegue la pipeline è lo stesso: cambia solo chi la fa partire e dove finisce il report.</p><h2 id="_2-il-repo-cliente" tabindex="-1">2. Il repo cliente <a class="header-anchor" href="#_2-il-repo-cliente" aria-label="Permalink to "2. Il repo cliente""></a></h2><p>Un repo cliente ha la stessa forma per ogni cliente:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>etl.config.ts # il catalogo: il cliente e le sue pipeline</span></span>
|
|
23
|
+
<div id="app"><div class="Layout" data-v-22f0e4eb><!--[--><!--]--><!--[--><span tabindex="-1" data-v-3426c47a></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-3426c47a>Skip to content</a><!--]--><!----><header class="VPNav" data-v-22f0e4eb data-v-c0562b42><div class="VPNavBar" data-v-c0562b42 data-v-09e46d68><div class="wrapper" data-v-09e46d68><div class="container" data-v-09e46d68><div class="title" data-v-09e46d68><div class="VPNavBarTitle has-sidebar" data-v-09e46d68 data-v-373bba86><a class="title" href="/guida/core/" data-v-373bba86><!--[--><!--]--><!--[--><!--[--><!--[--><img class="VPImage dark logo" src="/guida/core/logo-light.png" alt="Noeva" data-v-b8fe04e5><!--]--><!--[--><img class="VPImage light logo" src="/guida/core/logo-dark.png" alt="Noeva" data-v-b8fe04e5><!--]--><!--]--><!--]--><!----><!--[--><!--[--><!--[--><!--[--><span class="etl-wordmark" aria-hidden="true">ETL</span><span class="etl-embedded-title">Documentazione</span><!--]--><!--]--><!--]--><!--]--></a></div></div><div class="content" data-v-09e46d68><div class="content-body" data-v-09e46d68><!--[--><!--]--><div class="VPNavBarSearch search" data-v-09e46d68><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Cerca nella documentazione"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Cerca</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-09e46d68 data-v-39d75b74><span id="main-nav-aria-label" class="visually-hidden" data-v-39d75b74> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/guida/core/guide/usare/" tabindex="0" data-v-39d75b74 data-v-d4ae6030><!--[--><span data-v-d4ae6030>Usare</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/guida/core/guide/claude-code/" tabindex="0" data-v-39d75b74 data-v-d4ae6030><!--[--><span data-v-d4ae6030>Creare con Claude Code</span><!--]--></a><!--]--><!--[--><div class="VPFlyout VPNavBarMenuGroup" data-v-39d75b74 data-v-5d303cc7><button type="button" class="button" aria-haspopup="true" aria-expanded="false" data-v-5d303cc7><span class="text" data-v-5d303cc7><!----><span data-v-5d303cc7>Riferimento</span><span class="vpi-chevron-down text-icon" data-v-5d303cc7></span></span></button><div class="menu" data-v-5d303cc7><div class="VPMenu" data-v-5d303cc7 data-v-e79ccfeb><div class="items" data-v-e79ccfeb><!--[--><!--[--><div class="VPMenuLink" data-v-e79ccfeb data-v-b2643254><a class="VPLink link" href="/guida/core/guide/grafo" data-v-b2643254><!--[--><span data-v-b2643254>Il grafo, nodo per nodo</span><!--]--></a></div><!--]--><!--[--><div class="VPMenuLink" data-v-e79ccfeb data-v-b2643254><a class="VPLink link" href="/guida/core/nodes/README" data-v-b2643254><!--[--><span data-v-b2643254>Tipi di nodo</span><!--]--></a></div><!--]--><!--[--><div class="VPMenuLink" data-v-e79ccfeb data-v-b2643254><a class="VPLink link" href="/guida/core/connectors/README" data-v-b2643254><!--[--><span data-v-b2643254>Connettori</span><!--]--></a></div><!--]--><!--[--><div class="VPMenuLink" data-v-e79ccfeb data-v-b2643254><a class="VPLink link" href="/guida/core/pipelines/README" data-v-b2643254><!--[--><span data-v-b2643254>Pipeline pronte</span><!--]--></a></div><!--]--><!--[--><div class="VPMenuLink" data-v-e79ccfeb data-v-b2643254><a class="VPLink link" href="/guida/core/conventions/run-report" data-v-b2643254><!--[--><span data-v-b2643254>Il report di run</span><!--]--></a></div><!--]--><!--[--><div class="VPMenuLink" data-v-e79ccfeb data-v-b2643254><a class="VPLink link" href="/guida/core/conventions/run-trace" data-v-b2643254><!--[--><span data-v-b2643254>La traccia di una run</span><!--]--></a></div><!--]--><!--[--><div class="VPMenuLink" data-v-e79ccfeb data-v-b2643254><a class="VPLink link" href="/guida/core/conventions/variabili-del-core" data-v-b2643254><!--[--><span data-v-b2643254>Variabili d'ambiente del core</span><!--]--></a></div><!--]--><!--[--><div class="VPMenuLink" data-v-e79ccfeb data-v-b2643254><a class="VPLink link" href="/guida/core/runbooks/graph-server" data-v-b2643254><!--[--><span data-v-b2643254>Operatività</span><!--]--></a></div><!--]--><!--]--></div><!--[--><!--]--></div></div></div><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-09e46d68 data-v-41033a42><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-41033a42 data-v-16571e93 data-v-3d2b146f><span class="check" data-v-3d2b146f><span class="icon" data-v-3d2b146f><!--[--><span class="vpi-sun sun" data-v-16571e93></span><span class="vpi-moon moon" data-v-16571e93></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-09e46d68 data-v-6ab99828 data-v-5d303cc7><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-5d303cc7><span class="vpi-more-horizontal icon" data-v-5d303cc7></span></button><div class="menu" data-v-5d303cc7><div class="VPMenu" data-v-5d303cc7 data-v-e79ccfeb><!----><!--[--><!--[--><!----><div class="group" data-v-6ab99828><div class="item appearance" data-v-6ab99828><p class="label" data-v-6ab99828>Tema</p><div class="appearance-action" data-v-6ab99828><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-6ab99828 data-v-16571e93 data-v-3d2b146f><span class="check" data-v-3d2b146f><span class="icon" data-v-3d2b146f><!--[--><span class="vpi-sun sun" data-v-16571e93></span><span class="vpi-moon moon" data-v-16571e93></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-09e46d68 data-v-91920283><span class="container" data-v-91920283><span class="top" data-v-91920283></span><span class="middle" data-v-91920283></span><span class="bottom" data-v-91920283></span></span></button></div></div></div></div><div class="divider" data-v-09e46d68><div class="divider-line" data-v-09e46d68></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-22f0e4eb data-v-caa5a72f><div class="container" data-v-caa5a72f><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-caa5a72f><span class="vpi-align-left menu-icon" data-v-caa5a72f></span><span class="menu-text" data-v-caa5a72f>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-caa5a72f data-v-731b3d50><button data-v-731b3d50>Torna su</button><!----></div></div></div><aside class="VPSidebar" data-v-22f0e4eb data-v-ac566ed2><div class="curtain" data-v-ac566ed2></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-ac566ed2><span class="visually-hidden" id="sidebar-aria-label" data-v-ac566ed2> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-f8570edd><section class="VPSidebarItem level-0" data-v-f8570edd data-v-8de60be2><div class="item" role="button" tabindex="0" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><h2 class="text" data-v-8de60be2>Usare Noeva ETL</h2><!----></div><div class="items" data-v-8de60be2><!--[--><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/guide/usare/" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>Come si usa</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/guide/usare/app-desktop" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>L'app desktop</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/guide/usare/esito-di-una-run" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>Leggere l'esito di una run</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/TECHNICAL_OVERVIEW" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>Panoramica di prodotto</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f8570edd><section class="VPSidebarItem level-0 has-active" data-v-f8570edd data-v-8de60be2><div class="item" role="button" tabindex="0" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><h2 class="text" data-v-8de60be2>Creare con Claude Code</h2><!----></div><div class="items" data-v-8de60be2><!--[--><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/guide/claude-code/" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>Dal bisogno al processo</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/guide/claude-code/prompt" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>Comporre il prompt</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/guide/claude-code/strumenti" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>Skill e subagent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/GUIDA_SVILUPPO" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>Guida allo sviluppo</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f8570edd><section class="VPSidebarItem level-0" data-v-f8570edd data-v-8de60be2><div class="item" role="button" tabindex="0" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><h2 class="text" data-v-8de60be2>Concetti</h2><!----></div><div class="items" data-v-8de60be2><!--[--><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/guide/grafo" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>Il grafo, nodo per nodo</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/conventions/run-report" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>Il report di run</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/conventions/run-trace" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>La traccia di una run</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/conventions/versioni-di-pipeline" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>Versioni di pipeline</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/conventions/node-descriptor" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>Descriptor dei nodi</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/conventions/node-columns" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>Colonne dei nodi</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/conventions/variabili-del-core" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>Variabili d'ambiente del core</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f8570edd><section class="VPSidebarItem level-0 collapsible collapsed" data-v-f8570edd data-v-8de60be2><div class="item" role="button" tabindex="0" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><h2 class="text" data-v-8de60be2>Tipi di nodo</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-8de60be2><span class="vpi-chevron-right caret-icon" data-v-8de60be2></span></div></div><div class="items" data-v-8de60be2><!--[--><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/nodes/README" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>Cheatsheet</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/nodes/action" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>action</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/nodes/ai" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>ai</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/nodes/join" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>join</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/nodes/lookup" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>lookup</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/nodes/pipeline" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>pipeline</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/nodes/route" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>route</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/nodes/sink" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>sink</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/nodes/source" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>source</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/nodes/task" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>task</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/nodes/transform" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>transform</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/nodes/try-catch" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>try-catch</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/nodes/union" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>union</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f8570edd><section class="VPSidebarItem level-0 collapsible collapsed" data-v-f8570edd data-v-8de60be2><div class="item" role="button" tabindex="0" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><h2 class="text" data-v-8de60be2>Connettori</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-8de60be2><span class="vpi-chevron-right caret-icon" data-v-8de60be2></span></div></div><div class="items" data-v-8de60be2><!--[--><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/connectors/README" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>Panoramica</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/connectors/file" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>File (storage × codec)</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/connectors/http" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>HTTP (API REST per i nodi lookup e action)</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/connectors/imap" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>IMAP (caselle di posta)</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/connectors/jira" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>Jira Cloud (issue da una JQL o per chiave, liste di una issue, creazione, aggiornamento, transizioni, upsert, commenti, worklog e link)</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/connectors/noeva" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>Noeva (file dei workspace)</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/connectors/oauth" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>OAuth2 per i connettori</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/connectors/postgres" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>PostgreSQL</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/connectors/process" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>processo esterno</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/connectors/sendgrid" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>SendGrid (mail via API REST)</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/connectors/smtp" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>SMTP (notifiche email)</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/connectors/sqlserver" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>SQL Server</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/connectors/zoho" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>Zoho CRM (record di un modulo, con i campi dichiarati)</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f8570edd><section class="VPSidebarItem level-0 collapsible collapsed" data-v-f8570edd data-v-8de60be2><div class="item" role="button" tabindex="0" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><h2 class="text" data-v-8de60be2>Pipeline pronte</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-8de60be2><span class="vpi-chevron-right caret-icon" data-v-8de60be2></span></div></div><div class="items" data-v-8de60be2><!--[--><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/pipelines/README" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>Le schede di una pipeline</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/pipelines/test-posta" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>test-posta</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f8570edd><section class="VPSidebarItem level-0 collapsible collapsed" data-v-f8570edd data-v-8de60be2><div class="item" role="button" tabindex="0" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><h2 class="text" data-v-8de60be2>Esempi</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-8de60be2><span class="vpi-chevron-right caret-icon" data-v-8de60be2></span></div></div><div class="items" data-v-8de60be2><!--[--><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/sub-pipelines/README" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>Le schede di una sub-pipeline</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/pipelines/crm-leads-sync" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>crm-leads-sync</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/pipelines/cross-workspace-csv-merge" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>cross-workspace-csv-merge</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/pipelines/movimenti-per-conto" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>movimenti-per-conto</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/pipelines/orders-enriched-daily" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>orders-enriched-daily</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/sub-pipelines/riepilogo-ordini" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>riepilogo-ordini</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f8570edd><section class="VPSidebarItem level-0 collapsible collapsed" data-v-f8570edd data-v-8de60be2><div class="item" role="button" tabindex="0" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><h2 class="text" data-v-8de60be2>Operatività</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-8de60be2><span class="vpi-chevron-right caret-icon" data-v-8de60be2></span></div></div><div class="items" data-v-8de60be2><!--[--><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/runbooks/aggiornamento-pm2" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>aggiornare un deploy PM2 di un repo cliente</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/runbooks/deploy-ecr" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>un cliente su ECR + ECS</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/runbooks/deployment" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>distribuzione del runner ETL</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/runbooks/etl-worker" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>worker etl worker (polling su processes)</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/runbooks/graph-server" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>server grafi etl serve (HTTP)</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/runbooks/mask-key" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>chiavi di mask (creazione, rotazione, compromissione)</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/runbooks/oauth-google-posta" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>OAuth2 per una casella Google (IMAP + SMTP)</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/runbooks/rollback-di-pipeline" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>rollback di una pipeline</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/runbooks/scd2-rehash" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>rehash di una dimensione storicizzata</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/runbooks/sql-task-truncate-swap" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>task SQL, truncate e scambio di tabelle</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8de60be2><div class="item" data-v-8de60be2><div class="indicator" data-v-8de60be2></div><a class="VPLink link link" href="/guida/core/runbooks/stato-incrementale" data-v-8de60be2><!--[--><p class="text" data-v-8de60be2>stato di pipeline e watermark</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><!--]--><!--[--><!--]--></nav></aside><div class="VPContent has-sidebar" id="VPContent" data-v-22f0e4eb data-v-0c4b08a9><div class="VPDoc has-sidebar has-aside" data-v-0c4b08a9 data-v-4f20312f><!--[--><!--]--><div class="container" data-v-4f20312f><div class="aside" data-v-4f20312f><div class="aside-curtain" data-v-4f20312f></div><div class="aside-container" data-v-4f20312f><div class="aside-content" data-v-4f20312f><div class="VPDocAside" data-v-4f20312f data-v-2db35001><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-2db35001 data-v-2f8395af><div class="content" data-v-2f8395af><div class="outline-marker" data-v-2f8395af></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-2f8395af>In questa pagina</div><ul class="VPDocOutlineItem root" data-v-2f8395af data-v-9c3b479d><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-2db35001></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-4f20312f><div class="content-container" data-v-4f20312f><!--[--><!--]--><main class="main" data-v-4f20312f><div style="position:relative;" class="vp-doc _guida_core_GUIDA_SVILUPPO" data-v-4f20312f><div><h1 id="guida-allo-sviluppo" tabindex="-1">Guida allo sviluppo <a class="header-anchor" href="#guida-allo-sviluppo" aria-label="Permalink to "Guida allo sviluppo""></a></h1><blockquote><p>Come si scrive una pipeline in un <strong>repo cliente</strong>: le cartelle, il catalogo, l'API pubblica del core, i comandi <code>etl</code> e il kit dell'agente. Per la visione di prodotto vedi la <a href="./TECHNICAL_OVERVIEW">panoramica</a>; per il percorso con Claude Code, <a href="./guide/claude-code/">dal bisogno al processo</a>.</p></blockquote><h2 id="_1-cos-e-in-breve" tabindex="-1">1. Cos'è in breve <a class="header-anchor" href="#_1-cos-e-in-breve" aria-label="Permalink to "1. Cos'è in breve""></a></h2><p>Noeva ETL è un motore ETL <strong>code-first</strong>: le pipeline di integrazione dati (estrazione → trasformazione → caricamento) sono scritte in TypeScript, testate con vitest e documentate — non job grafici stile Talend, ma software vero.</p><p>Il motore è il <strong>core</strong>, il pacchetto <code>@noeva/etl-core</code>: nodi, connettori, transform, la CLI <code>etl</code> e questa guida. Le pipeline di un cliente vivono nel suo <strong>repo cliente</strong>, <code>noeva-etl-<slug></code>, che dipende dal core e ne usa solo l'API pubblica. Un deploy esegue un repo cliente: le sue pipeline, con la versione del core che il repo dichiara.</p><p>Il servizio è <strong>stateless</strong>: non ha un proprio database, esegue una pipeline e restituisce un <code>GraphRunReport</code> (JSON). La CLI <code>etl</code> si avvia in tre modi:</p><ul><li><strong><code>etl serve</code></strong> — il modo di un deploy: nello stesso processo espone i grafi via HTTP, per l'app desktop, <strong>e</strong> avvia i worker. Vedi <a href="./runbooks/graph-server">il runbook di <code>etl serve</code></a>.</li><li><strong><code>etl worker</code></strong> — solo il <strong>daemon</strong>: resta in polling sulla tabella <code>processes</code> di Noeva, sempre attraverso noeva-server-api, ed esegue le pipeline dei job che Noeva crea (lanci dall'app, job pianificati). Mai insieme a un <code>etl serve</code> nello stesso ambiente, o i job vengono presi due volte. Vedi <a href="./runbooks/etl-worker">il runbook del worker</a>.</li><li><strong><code>etl run <pipeline></code></strong> — batch: una esecuzione, report su stdout, poi termina. Con <code>--trace</code> è una run tracciata, che salva anche la traccia dei record (<a href="./conventions/run-trace">La traccia di una run</a>).</li></ul><p>In tutti e tre i casi il nucleo che esegue la pipeline è lo stesso: cambia solo chi la fa partire e dove finisce il report.</p><h2 id="_2-il-repo-cliente" tabindex="-1">2. Il repo cliente <a class="header-anchor" href="#_2-il-repo-cliente" aria-label="Permalink to "2. Il repo cliente""></a></h2><p>Un repo cliente ha la stessa forma per ogni cliente:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>etl.config.ts # il catalogo: il cliente e le sue pipeline</span></span>
|
|
24
24
|
<span class="line"><span>src/</span></span>
|
|
25
25
|
<span class="line"><span> pipelines/<nome>/ # una cartella per pipeline: schema, grafo, changelog, snapshot del piano, run, test</span></span>
|
|
26
26
|
<span class="line"><span> sub-pipelines/<nome>/ # i pezzi di grafo riusati da più pipeline</span></span>
|
|
@@ -54,7 +54,7 @@
|
|
|
54
54
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">transform</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"raw-contract"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"to-fact"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">mapTransform</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"to-fact"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, toFact))</span></span>
|
|
55
55
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">transform</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"to-fact"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"fact-contract"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">validate</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"fact-contract"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, factSchema))</span></span>
|
|
56
56
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">sink</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"fact-contract"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, sink)</span></span>
|
|
57
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">build</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span></code></pre></div><p>Gli undici tipi di nodo. A questi si aggiunge il nodo <a href="./nodes/pipeline"><code>pipeline</code></a>, <code>.pipeline(from, id, sub, { params?, deps?, fromPort?, deadLetter?, purpose? })</code>, che istanzia una sub-pipeline e alla costruzione diventa i suoi nodi:</p><table tabindex="0"><thead><tr><th>Nodo</th><th>Metodo</th><th>Cosa fa</th></tr></thead><tbody><tr><td><code>source</code></td><td><code>.source(id, source)</code></td><td>punto d'ingresso di uno stream</td></tr><tr><td><code>transform</code></td><td><code>.transform(from, id, t, opts)</code></td><td>trasformazione pura; accetta <code>deadLetter</code></td></tr><tr><td><code>lookup</code></td><td><code>.lookup(from, id, config, opts)</code></td><td>lettura <strong>in sola lettura</strong> in mezzo al grafo, a batch, da un DB o un'API REST; accetta <code>deadLetter</code> e <code>recordReport</code></td></tr><tr><td><code>ai</code></td><td><code>.ai(from, id, config, opts)</code></td><td>domanda a un <strong>modello</strong> per ogni record, con la risposta che arricchisce il record (es. <code>noevaAiExtract</code>); si esegue come un <code>lookup</code>; accetta <code>deadLetter</code> e <code>recordReport</code></td></tr><tr><td><code>action</code></td><td><code>.action(from, id, action, opts)</code></td><td><strong>scrittura per record</strong> in mezzo al grafo, con un record in uscita su cui il grafo prosegue; accetta <code>deadLetter</code> e <code>recordReport</code></td></tr><tr><td><code>route</code></td><td><code>.route(from, id, { routes }, opts)</code></td><td><strong>smistamento esclusivo</strong>: ogni record esce sulla porta della prima condizione vera, o su <code>default</code>; ogni porta va collegata; accetta <code>deadLetter</code></td></tr><tr><td><code>join</code></td><td><code>.join(id, { build, probe, … })</code></td><td>fan-in <strong>a chiave</strong>: join inner/left, lato <code>build</code> in memoria e <code>probe</code> in streaming; accetta <code>deadLetter</code></td></tr><tr><td><code>union</code></td><td><code>.union(id, { from, order })</code></td><td>fan-in di N flussi con la stessa forma, record invariati: <code>interleave</code> (default) nell'ordine di arrivo, <code>concat</code> nell'ordine di <code>from</code></td></tr><tr><td><code>try-catch</code></td><td><code>.tryCatch(from, id, opts)</code></td><td>apre uno scope di gestione errori sui nodi a valle, con una porta <code>catch</code></td></tr><tr><td><code>sink</code></td><td><code>.sink(from, sink)</code></td><td>scrittura verso l'esterno; l'id del nodo è <code>sink.name</code></td></tr><tr><td><code>task</code></td><td><code>.task(id, task, opts)</code></td><td>operazione <strong>senza record</strong> (truncate, scambio di tabelle), avviata dagli edge di controllo <code>after</code></td></tr></tbody></table><p>Il cheatsheet dei nodi, con una scheda di dettaglio per ciascuno (opzioni, errori, esempi), è in <a href="./nodes/README">Tipi di nodo</a>.</p><p>Il <strong>fan-out</strong> invece è libero: basta agganciare più nodi allo stesso <code>from</code>, e il runner duplica lo stream. La forma del grafo è validata <strong>a runtime</strong> su <code>.build()</code>: cicli, id sconosciuti o più di un ingresso su un nodo diverso da <code>join</code> e <code>union</code> esplodono come <code>GraphValidationError</code> alla costruzione. Esempio di riferimento completo: <a href="./pipelines/orders-enriched-daily"><code>orders-enriched-daily</code></a>.</p><p>Oltre agli edge di dati ci sono gli <strong>edge di controllo</strong>: l'opzione <code>after</code> di <code>.task()</code> e <code>.source()</code> dice «parti solo dopo che questi nodi sono riusciti». Partono da un <code>task</code> o da un <code>sink</code> e arrivano a un <code>task</code> o a una <code>source</code>. Dettagli nella scheda <a href="./nodes/task"><code>task</code></a>.</p><p>Ogni nodo ha uno <strong>scopo</strong>, <code>purpose</code>, scritto per chi legge il grafo nell'app: che cosa fa il nodo e perché serve, in una-tre frasi di business. Lo verificano <code>etl catalog check</code> ed <code>etl docs build</code>.</p><p>Il <code>RunContext</code> che ogni nodo riceve porta env, parametri di lancio (<code>ctx.params</code>), logger, metriche, il segnale d'arresto e lo store dello stato di pipeline. Gli errori di dominio sono <code>EtlError</code> (<code>ValidationError</code>, <code>ExtractError</code>, <code>LoadError</code>, <code>ConfigError</code>, <code>GraphValidationError</code>, <code>JoinError</code>, <code>LookupError</code>, <code>ActionError</code>, <code>TaskError</code>, <code>AssertionError</code>, <code>GraphRunFailure</code>): un errore che non lo è conta come bug.</p><h2 id="_5-come-gira-una-pipeline" tabindex="-1">5. Come gira una pipeline <a class="header-anchor" href="#_5-come-gira-una-pipeline" aria-label="Permalink to "5. Come gira una pipeline""></a></h2><p>Il grafo è <strong>pull-based</strong>: la domanda parte dai sink e risale verso le source, quindi è il ritmo di scrittura a regolare quello di lettura (backpressure gratis). I record scorrono in streaming, mai tutti in memoria — tranne il lato <code>build</code> di un <code>join</code> e le transform che trattengono lo stream, come <code>sort</code>, che hanno un tetto obbligatorio.</p><p>Quando un record fallisce ci sono tre percorsi, dal più locale al più drastico:</p><ul><li><strong>Dead-letter per nodo</strong> — <code>{ deadLetter: sink }</code> su un <code>transform</code>, <code>lookup</code>, <code>ai</code>, <code>action</code>, <code>route</code> o <code>join</code>. Il record che solleva <code>EtlError</code> esce come envelope <code>DeadLetter</code> su quel sink e <strong>lo stream continua</strong>. Adatto alle trasformazioni <strong>stateless</strong> (map/mapColumns/flatMap/explode/unpivot/filter/validate, <code>parse</code>, <code>hashRow</code>, <code>surrogateKey</code>, <code>mask</code>). Sul <code>.pipeline()</code> della root la <code>deadLetter</code> si distribuisce a ogni nodo isolabile dell'istanza, istanze annidate comprese (<a href="./nodes/pipeline#deadletter-sull-istanza"><code>deadLetter</code> sull'istanza</a>).</li><li><strong>Nodo <code>try-catch</code></strong> — protegge tutti i nodi raggiungibili dalla sua porta <code>out</code>, sink compresi. Di default è <code>per-record</code>: ogni record che fallisce va sul ramo <code>catch</code>, che è fatto di nodi veri e può loggare, rimappare o instradare altrove. In <code>circuit-breaker</code> al primo errore la sub-stream si ferma.</li><li><strong>Fail-fast</strong> — il default, senza dead-letter né guard: l'errore aborta la run. È l'unica scelta sensata per le trasformazioni <strong>stateful</strong> (es. <code>groupBy</code>, <code>sort</code>, <code>serialize</code>): un'aggregazione spezzata per record darebbe un risultato falso. Vale per tutto il grafo: al primo errore fatale il runner annulla anche i rami indipendenti e aspetta che ogni sink e ogni task chiuda prima di riportare la run fallita. Un <code>task</code> che fallisce è sempre fatale.</li></ul><p>Un errore che <strong>non</strong> è un <code>EtlError</code> (un <code>TypeError</code>, un bug) aborta sempre la run, anche dentro un guard: un bug non va scaricato in un sink di scarto, va visto. Qualunque sia la scelta, nessun record sparisce in silenzio: ogni scarto è contato nel report.</p><p>Ogni <code>run()</code> produce un <code>GraphRunReport</code>:</p><ul><li><strong>stato</strong> — <code>success</code>, <code>partial</code> (arrivata in fondo con scarti o errori catturati) o <code>failed</code>;</li><li><strong>totali</strong> — <code>extracted</code> (somma delle source), <code>written</code> (somma dei sink: su un fan-out lo stesso record scritto due volte conta due), <code>rejected</code>, <code>rejectedReasons</code>;</li><li><strong>per nodo</strong> — <code>nodes[]</code> ed <code>edges[]</code> con la topologia reale e i contatori di ogni nodo, <code>caught</code> sui guard, tempi di attraversamento;</li><li><strong>stato di pipeline</strong> — <code>state</code>, una voce per source incrementale: da dove ha letto, cosa propone, se il watermark è stato committato;</li><li>metriche ed errore — <strong>mai segreti o payload</strong>.</li></ul><p>È il "prodotto" del servizio: chi invoca la pipeline decide se archiviarlo, alertare, ecc. Schema completo in <a href="./conventions/run-report">Il report di run</a>.</p><h2 id="_6-cosa-c-e-gia-pronto" tabindex="-1">6. Cosa c'è già pronto <a class="header-anchor" href="#_6-cosa-c-e-gia-pronto" aria-label="Permalink to "6. Cosa c'è già pronto""></a></h2><p><strong>Connettori</strong>, uno per subpath di <code>@noeva/etl-core/connectors/</code>:</p><ul><li><strong>PostgreSQL</strong> (<code>postgres</code>) — source con cursor streaming, sink con upsert <code>ON CONFLICT</code> o in modalità SCD2 (dimensioni storicizzate), task SQL <code>postgresSqlTask</code> (statement in una transazione, per il nodo <code>task</code>).</li><li><strong>SQL Server</strong> (<code>sqlserver</code>) — source streaming, sink con <code>MERGE</code> o in modalità SCD2, task SQL <code>mssqlSqlTask</code>.</li><li><strong>File</strong> (<code>file</code>) — architettura a due assi componibili: <ul><li><em>storage</em>: dove vivono i file (locale, <strong>S3</strong>, <strong>SFTP</strong>, <strong>FTP/FTPS</strong>);</li><li><em>codec</em>: come si (de)serializzano — <strong>CSV</strong> (anche grezzo, <code>csvRawCodec</code>), <strong>JSON/NDJSON</strong>, <strong>XML</strong>, <strong>XLSX</strong>, <strong>Parquet</strong>. Storage e codec si combinano liberamente (es. CSV su S3, Parquet su SFTP).</li></ul></li><li><strong>Noeva</strong> (<code>noeva</code>) — file dei workspace Noeva via noeva-server-api: lettura di un file o di una cartella intera, scrittura di uno o più file in <code>overwrite</code> o <code>new-version</code>, upload con elaborazione AI (<code>noevaUploadAction</code>), lookup su stato e testo estratto ed estrazione AI di campi strutturati (<code>noevaAiExtract</code>, nodo <code>ai</code>).</li><li><strong>IMAP</strong> (<code>imap</code>) — caselle di posta: <code>imapSource</code> legge i messaggi di una cartella (allegati ed EML grezzo), le action <code>imapFlagAction</code> e <code>imapSpostaAction</code> marcano e spostano, con la cartella come coda.</li><li><strong>SMTP</strong> (<code>smtp</code>) — notifiche email: <code>smtpAction</code> e <code>smtpSink</code> inviano una mail costruita da una funzione del record, con Message-ID deterministico contro i doppioni.</li><li><strong>SendGrid</strong> (<code>sendgrid</code>) — mail via API REST v3: <code>sendgridAction</code> e <code>sendgridSink</code>, con la stessa mail di SMTP (<code>MailInUscita</code>), sandbox per le prove, retry di <code>429</code> e <code>5xx</code>; <code>mailAction</code> e <code>mailSink</code> (<code>mail</code>) scelgono fra SMTP e SendGrid da configurazione.</li><li><strong>HTTP</strong> (<code>http</code>) — API REST per i nodi <code>lookup</code> e <code>action</code>: <code>httpLookup</code> legge in sola lettura, una richiesta per batch o una <code>GET</code> per chiave, <code>httpAction</code> scrive e prosegue con l'esito; la risposta è validata da uno schema Zod e le credenziali vengono dal registry <code>HTTP_INSTANCES</code>. Il loro trasporto, <code>richiestaHttp</code>, è condiviso con i connettori REST di dominio, come Jira.</li><li><strong>Jira Cloud</strong> (<code>jira</code>) — <code>jiraIssues</code> legge le issue di una JQL, pagina dopo pagina, con i siti nel registry <code>JIRA_INSTANCES</code>; i campi si dichiarano per id o per nome e diventano colonne normalizzate, con gli ADF convertiti in testo. <code>jiraIssueLookup</code> legge le stesse issue per chiave, e <code>jiraChangelogLookup</code>, <code>jiraCommentsLookup</code> e <code>jiraWorklogsLookup</code> danno a ogni issue la sua lista completa. <code>jiraCreateIssue</code>, <code>jiraUpdateIssue</code>, <code>jiraTransition</code>, <code>jiraUpsertIssue</code> (per ID esterno), <code>jiraAddComment</code> e <code>jiraAddWorklog</code> (con una chiave di deduplica obbligatoria) e <code>jiraLinkIssues</code> scrivono come nodi <code>action</code>, con l'esito come dato.</li><li><strong>Processo esterno</strong> (<code>process</code>) — <code>processoEsternoAction</code> lancia un programma per record, senza shell, in una cartella temporanea sempre cancellata: i file del record entrano, i file di <code>uscita/</code> e un riepilogo JSON validato con Zod escono. Ambiente da allowlist e timeout obbligatorio.</li><li><strong>OAuth2</strong> (<code>oauth</code>) — non un connettore ma l'<strong>identità</strong> che IMAP e SMTP usano dove la password non basta più (Gmail, Workspace, Microsoft 365): tiene il refresh token e ne scambia uno nuovo quando l'access token scade, con un registry proprio <code>OAUTH_INSTANCES</code>.</li></ul><p>Le schede, con configurazione e variabili d'ambiente di ognuno, sono in <a href="./connectors/README">Connettori</a>.</p><p><strong>Trasformazioni riusabili</strong>, dalla radice del pacchetto: <code>groupBy</code> (aggregazione stateful generica init/reduce/finalize), <code>dedup</code> (duplicati per chiave), <code>mapColumns</code> (select, rename, cast e colonne calcolate, con lineage di colonna) e <code>castValue</code> (i suoi cast stretti, usabili da soli), <code>explode</code> (un campo array → un record per elemento), <code>unpivot</code> e <code>pivot</code> (dal formato largo al lungo e ritorno, con colonne dichiarate), <code>sort</code> (ordinamento stabile su più chiavi), <code>chunk</code> (record in lotti di N per un sink o un'API con limite di payload), <code>parse</code> (byte di un file → righe, con un <code>FileCodec</code>) e <code>serialize</code> (record → un file per gruppo, stateful), <code>hashRow</code> e <code>surrogateKey</code> (hash di riga e chiave surrogata deterministici), <code>mask</code> (mascheramento e pseudonimizzazione delle colonne con dati personali), <code>profile</code> (profilo delle colonne nel report del nodo, a memoria costante), <code>assert</code> (controlli sul dataset a fine stream). Il catalogo completo è in <a href="./nodes/transform#transform-pronte">transform</a>.</p><p><strong>Pipeline d'esempio</strong>, con la loro scheda nella sezione «Esempi» di questa guida:</p><ul><li><a href="./pipelines/orders-enriched-daily"><code>orders-enriched-daily</code></a> — dataset demo in memoria, esempio di riferimento per una pipeline <strong>a grafo</strong>: due sorgenti, join a chiave, fan-out su due sink, dead-letter isolato su due nodi indipendenti, try/catch e un'istanza della sub-pipeline <a href="./sub-pipelines/riepilogo-ordini"><code>riepilogo-ordini</code></a>.</li><li><a href="./pipelines/movimenti-per-conto"><code>movimenti-per-conto</code></a> — dataset demo in memoria, esempio di riferimento per le transform di file e di ordinamento in mezzo al grafo: <code>parse</code>, <code>sort</code> e <code>serialize</code>, da estratti conto CSV a un CSV per conto.</li><li><a href="./pipelines/crm-leads-sync"><code>crm-leads-sync</code></a> — copia fra due istanze Postgres dello stesso registry, con un try/catch per record.</li><li><a href="./pipelines/cross-workspace-csv-merge"><code>cross-workspace-csv-merge</code></a> — merge di un CSV fra due workspace Noeva, con un <code>union</code> e la scrittura in <code>new-version</code> su entrambi.</li></ul><p><strong>Pipeline pronte</strong>, da dichiarare nel catalogo: <a href="./pipelines/test-posta"><code>test-posta</code></a>, la prova dei connettori IMAP e SMTP di un'installazione.</p><h2 id="_7-i-comandi" tabindex="-1">7. I comandi <a class="header-anchor" href="#_7-i-comandi" aria-label="Permalink to "7. I comandi""></a></h2><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> exec</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # in una cartella vuota: il boilerplate di un repo cliente</span></span>
|
|
57
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">build</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span></code></pre></div><p>Gli undici tipi di nodo. A questi si aggiunge il nodo <a href="./nodes/pipeline"><code>pipeline</code></a>, <code>.pipeline(from, id, sub, { params?, deps?, fromPort?, deadLetter?, purpose? })</code>, che istanzia una sub-pipeline e alla costruzione diventa i suoi nodi:</p><table tabindex="0"><thead><tr><th>Nodo</th><th>Metodo</th><th>Cosa fa</th></tr></thead><tbody><tr><td><code>source</code></td><td><code>.source(id, source)</code></td><td>punto d'ingresso di uno stream</td></tr><tr><td><code>transform</code></td><td><code>.transform(from, id, t, opts)</code></td><td>trasformazione pura; accetta <code>deadLetter</code></td></tr><tr><td><code>lookup</code></td><td><code>.lookup(from, id, config, opts)</code></td><td>lettura <strong>in sola lettura</strong> in mezzo al grafo, a batch, da un DB o un'API REST; accetta <code>deadLetter</code> e <code>recordReport</code></td></tr><tr><td><code>ai</code></td><td><code>.ai(from, id, config, opts)</code></td><td>domanda a un <strong>modello</strong> per ogni record, con la risposta che arricchisce il record (es. <code>noevaAiExtract</code>); si esegue come un <code>lookup</code>; accetta <code>deadLetter</code> e <code>recordReport</code></td></tr><tr><td><code>action</code></td><td><code>.action(from, id, action, opts)</code></td><td><strong>scrittura per record</strong> in mezzo al grafo, con un record in uscita su cui il grafo prosegue; accetta <code>deadLetter</code> e <code>recordReport</code></td></tr><tr><td><code>route</code></td><td><code>.route(from, id, { routes }, opts)</code></td><td><strong>smistamento esclusivo</strong>: ogni record esce sulla porta della prima condizione vera, o su <code>default</code>; ogni porta va collegata; accetta <code>deadLetter</code></td></tr><tr><td><code>join</code></td><td><code>.join(id, { build, probe, … })</code></td><td>fan-in <strong>a chiave</strong>: join inner/left, lato <code>build</code> in memoria e <code>probe</code> in streaming; accetta <code>deadLetter</code></td></tr><tr><td><code>union</code></td><td><code>.union(id, { from, order })</code></td><td>fan-in di N flussi con la stessa forma, record invariati: <code>interleave</code> (default) nell'ordine di arrivo, <code>concat</code> nell'ordine di <code>from</code></td></tr><tr><td><code>try-catch</code></td><td><code>.tryCatch(from, id, opts)</code></td><td>apre uno scope di gestione errori sui nodi a valle, con una porta <code>catch</code></td></tr><tr><td><code>sink</code></td><td><code>.sink(from, sink)</code></td><td>scrittura verso l'esterno; l'id del nodo è <code>sink.name</code></td></tr><tr><td><code>task</code></td><td><code>.task(id, task, opts)</code></td><td>operazione <strong>senza record</strong> (truncate, scambio di tabelle), avviata dagli edge di controllo <code>after</code></td></tr></tbody></table><p>Il cheatsheet dei nodi, con una scheda di dettaglio per ciascuno (opzioni, errori, esempi), è in <a href="./nodes/README">Tipi di nodo</a>.</p><p>Il <strong>fan-out</strong> invece è libero: basta agganciare più nodi allo stesso <code>from</code>, e il runner duplica lo stream. La forma del grafo è validata <strong>a runtime</strong> su <code>.build()</code>: cicli, id sconosciuti o più di un ingresso su un nodo diverso da <code>join</code> e <code>union</code> esplodono come <code>GraphValidationError</code> alla costruzione. Esempio di riferimento completo: <a href="./pipelines/orders-enriched-daily"><code>orders-enriched-daily</code></a>.</p><p>Oltre agli edge di dati ci sono gli <strong>edge di controllo</strong>: l'opzione <code>after</code> di <code>.task()</code> e <code>.source()</code> dice «parti solo dopo che questi nodi sono riusciti». Partono da un <code>task</code> o da un <code>sink</code> e arrivano a un <code>task</code> o a una <code>source</code>. Dettagli nella scheda <a href="./nodes/task"><code>task</code></a>.</p><p>Ogni nodo ha uno <strong>scopo</strong>, <code>purpose</code>, scritto per chi legge il grafo nell'app: che cosa fa il nodo e perché serve, in una-tre frasi di business. Lo verificano <code>etl catalog check</code> ed <code>etl docs build</code>.</p><p>Il <code>RunContext</code> che ogni nodo riceve porta env, parametri di lancio (<code>ctx.params</code>), logger, metriche, il segnale d'arresto e lo store dello stato di pipeline. Gli errori di dominio sono <code>EtlError</code> (<code>ValidationError</code>, <code>ExtractError</code>, <code>LoadError</code>, <code>ConfigError</code>, <code>GraphValidationError</code>, <code>JoinError</code>, <code>LookupError</code>, <code>ActionError</code>, <code>TaskError</code>, <code>AssertionError</code>, <code>GraphRunFailure</code>): un errore che non lo è conta come bug.</p><h2 id="_5-come-gira-una-pipeline" tabindex="-1">5. Come gira una pipeline <a class="header-anchor" href="#_5-come-gira-una-pipeline" aria-label="Permalink to "5. Come gira una pipeline""></a></h2><p>Il grafo è <strong>pull-based</strong>: la domanda parte dai sink e risale verso le source, quindi è il ritmo di scrittura a regolare quello di lettura (backpressure gratis). I record scorrono in streaming, mai tutti in memoria — tranne il lato <code>build</code> di un <code>join</code> e le transform che trattengono lo stream, come <code>sort</code>, che hanno un tetto obbligatorio.</p><p>Quando un record fallisce ci sono tre percorsi, dal più locale al più drastico:</p><ul><li><strong>Dead-letter per nodo</strong> — <code>{ deadLetter: sink }</code> su un <code>transform</code>, <code>lookup</code>, <code>ai</code>, <code>action</code>, <code>route</code> o <code>join</code>. Il record che solleva <code>EtlError</code> esce come envelope <code>DeadLetter</code> su quel sink e <strong>lo stream continua</strong>. Adatto alle trasformazioni <strong>stateless</strong> (map/mapColumns/flatMap/explode/unpivot/filter/validate, <code>parse</code>, <code>hashRow</code>, <code>surrogateKey</code>, <code>mask</code>). Sul <code>.pipeline()</code> della root la <code>deadLetter</code> si distribuisce a ogni nodo isolabile dell'istanza, istanze annidate comprese (<a href="./nodes/pipeline#deadletter-sull-istanza"><code>deadLetter</code> sull'istanza</a>).</li><li><strong>Nodo <code>try-catch</code></strong> — protegge tutti i nodi raggiungibili dalla sua porta <code>out</code>, sink compresi. Di default è <code>per-record</code>: ogni record che fallisce va sul ramo <code>catch</code>, che è fatto di nodi veri e può loggare, rimappare o instradare altrove. In <code>circuit-breaker</code> al primo errore la sub-stream si ferma.</li><li><strong>Fail-fast</strong> — il default, senza dead-letter né guard: l'errore aborta la run. È l'unica scelta sensata per le trasformazioni <strong>stateful</strong> (es. <code>groupBy</code>, <code>sort</code>, <code>serialize</code>): un'aggregazione spezzata per record darebbe un risultato falso. Vale per tutto il grafo: al primo errore fatale il runner annulla anche i rami indipendenti e aspetta che ogni sink e ogni task chiuda prima di riportare la run fallita. Un <code>task</code> che fallisce è sempre fatale.</li></ul><p>Un errore che <strong>non</strong> è un <code>EtlError</code> (un <code>TypeError</code>, un bug) aborta sempre la run, anche dentro un guard: un bug non va scaricato in un sink di scarto, va visto. Qualunque sia la scelta, nessun record sparisce in silenzio: ogni scarto è contato nel report.</p><p>Ogni <code>run()</code> produce un <code>GraphRunReport</code>:</p><ul><li><strong>stato</strong> — <code>success</code>, <code>partial</code> (arrivata in fondo con scarti o errori catturati) o <code>failed</code>;</li><li><strong>totali</strong> — <code>extracted</code> (somma delle source), <code>written</code> (somma dei sink: su un fan-out lo stesso record scritto due volte conta due), <code>rejected</code>, <code>rejectedReasons</code>;</li><li><strong>per nodo</strong> — <code>nodes[]</code> ed <code>edges[]</code> con la topologia reale e i contatori di ogni nodo, <code>caught</code> sui guard, tempi di attraversamento;</li><li><strong>stato di pipeline</strong> — <code>state</code>, una voce per source incrementale: da dove ha letto, cosa propone, se il watermark è stato committato;</li><li>metriche ed errore — <strong>mai segreti o payload</strong>.</li></ul><p>È il "prodotto" del servizio: chi invoca la pipeline decide se archiviarlo, alertare, ecc. Schema completo in <a href="./conventions/run-report">Il report di run</a>.</p><h2 id="_6-cosa-c-e-gia-pronto" tabindex="-1">6. Cosa c'è già pronto <a class="header-anchor" href="#_6-cosa-c-e-gia-pronto" aria-label="Permalink to "6. Cosa c'è già pronto""></a></h2><p><strong>Connettori</strong>, uno per subpath di <code>@noeva/etl-core/connectors/</code>:</p><ul><li><strong>PostgreSQL</strong> (<code>postgres</code>) — source con cursor streaming, sink con upsert <code>ON CONFLICT</code> o in modalità SCD2 (dimensioni storicizzate), task SQL <code>postgresSqlTask</code> (statement in una transazione, per il nodo <code>task</code>).</li><li><strong>SQL Server</strong> (<code>sqlserver</code>) — source streaming, sink con <code>MERGE</code> o in modalità SCD2, task SQL <code>mssqlSqlTask</code>.</li><li><strong>File</strong> (<code>file</code>) — architettura a due assi componibili: <ul><li><em>storage</em>: dove vivono i file (locale, <strong>S3</strong>, <strong>SFTP</strong>, <strong>FTP/FTPS</strong>);</li><li><em>codec</em>: come si (de)serializzano — <strong>CSV</strong> (anche grezzo, <code>csvRawCodec</code>), <strong>JSON/NDJSON</strong>, <strong>XML</strong>, <strong>XLSX</strong>, <strong>Parquet</strong>. Storage e codec si combinano liberamente (es. CSV su S3, Parquet su SFTP).</li></ul></li><li><strong>Noeva</strong> (<code>noeva</code>) — file dei workspace Noeva via noeva-server-api: lettura di un file o di una cartella intera, scrittura di uno o più file in <code>overwrite</code> o <code>new-version</code>, upload con elaborazione AI (<code>noevaUploadAction</code>), lookup su stato e testo estratto ed estrazione AI di campi strutturati (<code>noevaAiExtract</code>, nodo <code>ai</code>).</li><li><strong>IMAP</strong> (<code>imap</code>) — caselle di posta: <code>imapSource</code> legge i messaggi di una cartella (allegati ed EML grezzo), le action <code>imapFlagAction</code> e <code>imapSpostaAction</code> marcano e spostano, con la cartella come coda.</li><li><strong>SMTP</strong> (<code>smtp</code>) — notifiche email: <code>smtpAction</code> e <code>smtpSink</code> inviano una mail costruita da una funzione del record, con Message-ID deterministico contro i doppioni.</li><li><strong>SendGrid</strong> (<code>sendgrid</code>) — mail via API REST v3: <code>sendgridAction</code> e <code>sendgridSink</code>, con la stessa mail di SMTP (<code>MailInUscita</code>), sandbox per le prove, retry di <code>429</code> e <code>5xx</code>; <code>mailAction</code> e <code>mailSink</code> (<code>mail</code>) scelgono fra SMTP e SendGrid da configurazione.</li><li><strong>HTTP</strong> (<code>http</code>) — API REST per i nodi <code>lookup</code> e <code>action</code>: <code>httpLookup</code> legge in sola lettura, una richiesta per batch o una <code>GET</code> per chiave, <code>httpAction</code> scrive e prosegue con l'esito; la risposta è validata da uno schema Zod e le credenziali vengono dal registry <code>HTTP_INSTANCES</code>. Il loro trasporto, <code>richiestaHttp</code>, è condiviso con i connettori REST di dominio, come Jira.</li><li><strong>Jira Cloud</strong> (<code>jira</code>) — <code>jiraIssues</code> legge le issue di una JQL, pagina dopo pagina, con i siti nel registry <code>JIRA_INSTANCES</code>; i campi si dichiarano per id o per nome e diventano colonne normalizzate, con gli ADF convertiti in testo. <code>jiraIssueLookup</code> legge le stesse issue per chiave, e <code>jiraChangelogLookup</code>, <code>jiraCommentsLookup</code> e <code>jiraWorklogsLookup</code> danno a ogni issue la sua lista completa. <code>jiraCreateIssue</code>, <code>jiraUpdateIssue</code>, <code>jiraTransition</code>, <code>jiraUpsertIssue</code> (per ID esterno), <code>jiraAddComment</code> e <code>jiraAddWorklog</code> (con una chiave di deduplica obbligatoria) e <code>jiraLinkIssues</code> scrivono come nodi <code>action</code>, con l'esito come dato.</li><li><strong>Zoho CRM</strong> (<code>zoho</code>) — <code>zohoCrmRecords</code> legge i record di un modulo con i soli campi dichiarati, che sono anche la regola di privacy, in ordine di <code>id</code>: con la Records API fino a 100.000 record, con la Query API (COQL) a chiavi crescenti di <code>id</code> oltre. Le organizzazioni stanno nel registry <code>ZOHO_INSTANCES</code>, il token lo rinnova un'identità OAuth2 e il trasporto è quello condiviso di <code>http</code>.</li><li><strong>Processo esterno</strong> (<code>process</code>) — <code>processoEsternoAction</code> lancia un programma per record, senza shell, in una cartella temporanea sempre cancellata: i file del record entrano, i file di <code>uscita/</code> e un riepilogo JSON validato con Zod escono. Ambiente da allowlist e timeout obbligatorio.</li><li><strong>OAuth2</strong> (<code>oauth</code>) — non un connettore ma l'<strong>identità</strong> che IMAP e SMTP usano dove la password non basta più (Gmail, Workspace, Microsoft 365), e con cui Zoho CRM autentica le sue richieste: tiene il refresh token e ne scambia uno nuovo quando l'access token scade, con un registry proprio <code>OAUTH_INSTANCES</code>.</li></ul><p>Le schede, con configurazione e variabili d'ambiente di ognuno, sono in <a href="./connectors/README">Connettori</a>.</p><p><strong>Trasformazioni riusabili</strong>, dalla radice del pacchetto: <code>groupBy</code> (aggregazione stateful generica init/reduce/finalize), <code>dedup</code> (duplicati per chiave), <code>mapColumns</code> (select, rename, cast e colonne calcolate, con lineage di colonna) e <code>castValue</code> (i suoi cast stretti, usabili da soli), <code>explode</code> (un campo array → un record per elemento), <code>unpivot</code> e <code>pivot</code> (dal formato largo al lungo e ritorno, con colonne dichiarate), <code>sort</code> (ordinamento stabile su più chiavi), <code>chunk</code> (record in lotti di N per un sink o un'API con limite di payload), <code>parse</code> (byte di un file → righe, con un <code>FileCodec</code>) e <code>serialize</code> (record → un file per gruppo, stateful), <code>hashRow</code> e <code>surrogateKey</code> (hash di riga e chiave surrogata deterministici), <code>mask</code> (mascheramento e pseudonimizzazione delle colonne con dati personali), <code>profile</code> (profilo delle colonne nel report del nodo, a memoria costante), <code>assert</code> (controlli sul dataset a fine stream). Il catalogo completo è in <a href="./nodes/transform#transform-pronte">transform</a>.</p><p><strong>Pipeline d'esempio</strong>, con la loro scheda nella sezione «Esempi» di questa guida:</p><ul><li><a href="./pipelines/orders-enriched-daily"><code>orders-enriched-daily</code></a> — dataset demo in memoria, esempio di riferimento per una pipeline <strong>a grafo</strong>: due sorgenti, join a chiave, fan-out su due sink, dead-letter isolato su due nodi indipendenti, try/catch e un'istanza della sub-pipeline <a href="./sub-pipelines/riepilogo-ordini"><code>riepilogo-ordini</code></a>.</li><li><a href="./pipelines/movimenti-per-conto"><code>movimenti-per-conto</code></a> — dataset demo in memoria, esempio di riferimento per le transform di file e di ordinamento in mezzo al grafo: <code>parse</code>, <code>sort</code> e <code>serialize</code>, da estratti conto CSV a un CSV per conto.</li><li><a href="./pipelines/crm-leads-sync"><code>crm-leads-sync</code></a> — copia fra due istanze Postgres dello stesso registry, con un try/catch per record.</li><li><a href="./pipelines/cross-workspace-csv-merge"><code>cross-workspace-csv-merge</code></a> — merge di un CSV fra due workspace Noeva, con un <code>union</code> e la scrittura in <code>new-version</code> su entrambi.</li></ul><p><strong>Pipeline pronte</strong>, da dichiarare nel catalogo: <a href="./pipelines/test-posta"><code>test-posta</code></a>, la prova dei connettori IMAP e SMTP di un'installazione.</p><h2 id="_7-i-comandi" tabindex="-1">7. I comandi <a class="header-anchor" href="#_7-i-comandi" aria-label="Permalink to "7. I comandi""></a></h2><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> exec</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # in una cartella vuota: il boilerplate di un repo cliente</span></span>
|
|
58
58
|
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> exec</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ci</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # il gate completo del repo, lo stesso della CI</span></span>
|
|
59
59
|
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> exec</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> agent</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> sync</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # riscrive il kit dell'agente dal core installato (§10)</span></span>
|
|
60
60
|
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> exec</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> upgrade</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --check</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # versione installata e ultima, changelog e deriva dei file gestiti</span></span>
|
|
@@ -73,8 +73,8 @@
|
|
|
73
73
|
<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;"> build</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # il gate della documentazione, poi il sito del cliente</span></span>
|
|
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
|
-
<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'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>▶ <fase></code>, e la prima che fallisce ferma il gate: <code>etl ci: la fase «<fase>» è fallita</code>, con l'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'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'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'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'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'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'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'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 <chiave></code>. Con il core già all'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'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'ambiente sull'intero catalogo: su stdout una riga per variabile obbligatoria mancante, <code><VARIABILE>\t<provenienze></code>, dove la provenienza è <code>core</code>, <code>pipeline <nome></code> o <code>istanza <connettore> <id> (<pipeline che la usano>)</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'obbligatoria, <code>0</code> altrimenti, anche con sconosciute. Le variabili del core sono in <a href="./conventions/variabili-del-core">Variabili d'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'istanza (l'utente di un DB, l'identità OAuth2), e quelle variabili, se stanno nel <code>.env</code>, compaiono fra le sconosciute. Legge l'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'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><regola>\t<pipeline>: <dettaglio></code>; su stderr il riepilogo e gli avvisi del caricamento. Esce con <code>0</code> se il catalogo è conforme (anche vuoto, con l'avviso), <code>1</code> con almeno una violazione, <code>2</code> per un errore d'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'istanza, che genera il core</td></tr><tr><td><code>piano-senza-segreti</code></td><td>con l'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'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'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'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 <n></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><regola>\t<dove>: <dettaglio></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><PipelineDag name="…" /></code>, ogni sub-pipeline che una di loro istanzia una con <code><SubPipelineDag></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'indice del catalogo sono una riga col link qui. Un link <code>core:</code> diventa <code>/guida/core/<pagina></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'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 "8. Aggiungere le cose più comuni""></a></h2><h3 id="una-nuova-pipeline" tabindex="-1">Una nuova pipeline <a class="header-anchor" href="#una-nuova-pipeline" aria-label="Permalink to "Una nuova pipeline""></a></h3><p>Una cartella <code>src/pipelines/<nome>/</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'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'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'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 <nome></code> (<code>versions/v1.plan.json</code>) e si crea la scheda <code>docs/pipelines/<nome>.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 "Una nuova sub-pipeline""></a></h3><p>Un pezzo di grafo riusato da più pipeline, o più volte nella stessa, è una sub-pipeline: <code>src/sub-pipelines/<nome>/</code> con <code>schema.ts</code> (contratti d'ingresso e d'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'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/<nome>.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 "Un connettore del cliente""></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<T></code>, <code>Sink<T></code> o l'interfaccia di un <code>lookup</code> o di un'<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 "Una nuova trasformazione""></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 "9. Cosa NON fare (vincoli non negoziabili)""></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'è il nodo <code>lookup</code>, per una scrittura il nodo <code>action</code>, per un'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'ambiente, documentate in <code>.env.example</code>.</li><li><strong>Codice senza test o senza scheda aggiornata non è "finito"</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'agente <a class="header-anchor" href="#_10-il-kit-dell-agente" aria-label="Permalink to "10. Il kit dell'agente""></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'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'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'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\":\"
|
|
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'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>▶ <fase></code>, e la prima che fallisce ferma il gate: <code>etl ci: la fase «<fase>» è fallita</code>, con l'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'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'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'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'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'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'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'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 <chiave></code>. Con il core già all'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'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'ambiente sull'intero catalogo: su stdout una riga per variabile obbligatoria mancante, <code><VARIABILE>\t<provenienze></code>, dove la provenienza è <code>core</code>, <code>pipeline <nome></code> o <code>istanza <connettore> <id> (<pipeline che la usano>)</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'obbligatoria, <code>0</code> altrimenti, anche con sconosciute. Le variabili del core sono in <a href="./conventions/variabili-del-core">Variabili d'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'istanza (l'utente di un DB, l'identità OAuth2), e quelle variabili, se stanno nel <code>.env</code>, compaiono fra le sconosciute. Legge l'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'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><regola>\t<pipeline>: <dettaglio></code>; su stderr il riepilogo e gli avvisi del caricamento. Esce con <code>0</code> se il catalogo è conforme (anche vuoto, con l'avviso), <code>1</code> con almeno una violazione, <code>2</code> per un errore d'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'istanza, che genera il core</td></tr><tr><td><code>piano-senza-segreti</code></td><td>con l'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'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'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'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 <n></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><regola>\t<dove>: <dettaglio></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><PipelineDag name="…" /></code>, ogni sub-pipeline che una di loro istanzia una con <code><SubPipelineDag></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'indice del catalogo sono una riga col link qui. Un link <code>core:</code> diventa <code>/guida/core/<pagina></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'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 "8. Aggiungere le cose più comuni""></a></h2><h3 id="una-nuova-pipeline" tabindex="-1">Una nuova pipeline <a class="header-anchor" href="#una-nuova-pipeline" aria-label="Permalink to "Una nuova pipeline""></a></h3><p>Una cartella <code>src/pipelines/<nome>/</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'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'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'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 <nome></code> (<code>versions/v1.plan.json</code>) e si crea la scheda <code>docs/pipelines/<nome>.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 "Una nuova sub-pipeline""></a></h3><p>Un pezzo di grafo riusato da più pipeline, o più volte nella stessa, è una sub-pipeline: <code>src/sub-pipelines/<nome>/</code> con <code>schema.ts</code> (contratti d'ingresso e d'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'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/<nome>.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 "Un connettore del cliente""></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<T></code>, <code>Sink<T></code> o l'interfaccia di un <code>lookup</code> o di un'<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 "Una nuova trasformazione""></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 "9. Cosa NON fare (vincoli non negoziabili)""></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'è il nodo <code>lookup</code>, per una scrittura il nodo <code>action</code>, per un'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'ambiente, documentate in <code>.env.example</code>.</li><li><strong>Codice senza test o senza scheda aggiornata non è "finito"</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'agente <a class="header-anchor" href="#_10-il-kit-dell-agente" aria-label="Permalink to "10. Il kit dell'agente""></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'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'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'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-4f20312f data-v-0be8676d><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-0be8676d><span class="visually-hidden" id="doc-footer-aria-label" data-v-0be8676d>Pager</span><div class="pager" data-v-0be8676d><a class="VPLink link pager-link prev" href="/guida/core/guide/claude-code/strumenti" data-v-0be8676d><!--[--><span class="desc" data-v-0be8676d>Pagina precedente</span><span class="title" data-v-0be8676d>Skill e subagent</span><!--]--></a></div><div class="pager" data-v-0be8676d><a class="VPLink link pager-link next" href="/guida/core/guide/grafo" data-v-0be8676d><!--[--><span class="desc" data-v-0be8676d>Pagina successiva</span><span class="title" data-v-0be8676d>Il grafo, nodo per nodo</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><footer class="VPFooter has-sidebar" data-v-22f0e4eb data-v-331f077b><div class="container" data-v-331f077b><p class="message" data-v-331f077b>Noeva è un marchio registrato di 4D S.R.L.</p><p class="copyright" data-v-331f077b>© 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\":\"BeotXAWb\",\"connectors_postgres.md\":\"DPpHqXkc\",\"connectors_process.md\":\"lQLmWbGN\",\"connectors_readme.md\":\"BqI2RLCu\",\"connectors_sendgrid.md\":\"dJzIWepq\",\"connectors_smtp.md\":\"DXXvaNxD\",\"connectors_sqlserver.md\":\"D1sYNLEq\",\"connectors_zoho.md\":\"BfEzRNZk\",\"conventions_node-columns.md\":\"D9K1peUx\",\"conventions_node-descriptor.md\":\"MQaGlm8a\",\"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\":\"CrN52ZDN\",\"guide_claude-code_index.md\":\"DEnzf9b_\",\"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\":\"DP2i3GFv\",\"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\":\"DrFr4blI\",\"runbooks_deploy-ecr.md\":\"4jQypInn\",\"runbooks_deployment.md\":\"CwG77qGO\",\"runbooks_etl-worker.md\":\"Bu05cEgT\",\"runbooks_graph-server.md\":\"opGHnuzK\",\"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\":\"DTIhkkg9\"}");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\",\"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\":\"Zoho CRM (record di un modulo, con i campi dichiarati)\",\"link\":\"/connectors/zoho\"}]},{\"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\":\"un cliente su ECR + ECS\",\"link\":\"/runbooks/deploy-ecr\"},{\"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>
|