@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.
Files changed (150) hide show
  1. package/CHANGELOG.md +183 -0
  2. package/LICENSE +19 -0
  3. package/README.md +3 -2
  4. package/deploy/Dockerfile +1 -1
  5. package/dist/chunk-BVUOUBLW.js +1 -0
  6. package/dist/chunk-CRR3Q2C7.js +2 -0
  7. package/dist/chunk-J3PBMWSP.js +2 -0
  8. package/dist/{chunk-KMUNED7K.js → chunk-LJ7DVP5F.js} +1 -1
  9. package/dist/{chunk-ZBKP2UOF.js → chunk-P6B2KLNJ.js} +2 -2
  10. package/dist/chunk-PKBSETMV.js +2 -0
  11. package/dist/chunk-QPJC4GWR.js +1 -0
  12. package/dist/chunk-RCRMQPFH.js +5 -0
  13. package/dist/chunk-RS5SGDUU.js +1 -0
  14. package/dist/chunk-RWPHH4E2.js +1 -0
  15. package/dist/chunk-SRFFKE5W.js +6 -0
  16. package/dist/chunk-WVODQB6Z.js +1 -0
  17. package/dist/chunk-XZMCC6VQ.js +1 -0
  18. package/dist/chunk-ZCYGHS7P.js +2 -0
  19. package/dist/cli.js +2 -2
  20. package/dist/connector-kit.d.ts +4 -2
  21. package/dist/connector-kit.js +1 -1
  22. package/dist/connectors/file.js +1 -1
  23. package/dist/connectors/http.js +1 -1
  24. package/dist/connectors/imap.js +1 -1
  25. package/dist/connectors/jira.js +2 -2
  26. package/dist/connectors/mail.js +1 -1
  27. package/dist/connectors/noeva.js +1 -1
  28. package/dist/connectors/oauth.js +1 -1
  29. package/dist/connectors/postgres.js +1 -1
  30. package/dist/connectors/sendgrid.js +1 -1
  31. package/dist/connectors/smtp.js +1 -1
  32. package/dist/connectors/sqlserver.js +1 -1
  33. package/dist/connectors/zoho.d.ts +304 -0
  34. package/dist/connectors/zoho.js +2 -0
  35. package/dist/etl.config.js +2 -2
  36. package/dist/guida/404.html +3 -3
  37. package/dist/guida/GUIDA_SVILUPPO.html +8 -8
  38. package/dist/guida/TECHNICAL_OVERVIEW.html +8 -8
  39. package/dist/guida/assets/{GUIDA_SVILUPPO.md.D13C7Zwu.js → GUIDA_SVILUPPO.md.CrN52ZDN.js} +1 -1
  40. package/dist/guida/assets/{TECHNICAL_OVERVIEW.md.DQP0pWc8.js → TECHNICAL_OVERVIEW.md.DTIhkkg9.js} +1 -1
  41. package/dist/guida/assets/{app.CzIZwOrR.js → app.DlsuGVZn.js} +1 -1
  42. package/dist/guida/assets/chunks/@localSearchIndexroot.LnC621Vy.js +1 -0
  43. package/dist/guida/assets/chunks/{VPLocalSearchBox.Cv9o56BQ.js → VPLocalSearchBox.v4vBLemj.js} +2 -2
  44. package/dist/guida/assets/chunks/{theme.CsUxYN72.js → theme.D9XEK7o0.js} +2 -2
  45. package/dist/guida/assets/connectors_README.md.BqI2RLCu.js +1 -0
  46. package/dist/guida/assets/connectors_README.md.BqI2RLCu.lean.js +1 -0
  47. package/dist/guida/assets/connectors_oauth.md.BeotXAWb.js +7 -0
  48. package/dist/guida/assets/connectors_oauth.md.BeotXAWb.lean.js +1 -0
  49. package/dist/guida/assets/connectors_zoho.md.BfEzRNZk.js +17 -0
  50. package/dist/guida/assets/connectors_zoho.md.BfEzRNZk.lean.js +1 -0
  51. package/dist/guida/assets/{conventions_node-descriptor.md.D8Si7E2S.js → conventions_node-descriptor.md.MQaGlm8a.js} +1 -1
  52. package/dist/guida/assets/{guide_claude-code_index.md.CxVSru8e.js → guide_claude-code_index.md.DEnzf9b_.js} +1 -1
  53. package/dist/guida/assets/{nodes_source.md.V_vlNfOz.js → nodes_source.md.DP2i3GFv.js} +3 -3
  54. package/dist/guida/assets/{nodes_source.md.V_vlNfOz.lean.js → nodes_source.md.DP2i3GFv.lean.js} +1 -1
  55. package/dist/guida/assets/{runbooks_aggiornamento-pm2.md.f3LAxif4.js → runbooks_aggiornamento-pm2.md.DrFr4blI.js} +1 -1
  56. package/dist/guida/assets/{runbooks_deployment.md.CsIYRa_5.js → runbooks_deployment.md.CwG77qGO.js} +1 -1
  57. package/dist/guida/assets/{style.BNn_AkzN.css → style.DFlUbYCk.css} +1 -1
  58. package/dist/guida/connectors/README.html +6 -6
  59. package/dist/guida/connectors/file.html +6 -6
  60. package/dist/guida/connectors/http.html +6 -6
  61. package/dist/guida/connectors/imap.html +6 -6
  62. package/dist/guida/connectors/jira.html +6 -6
  63. package/dist/guida/connectors/noeva.html +6 -6
  64. package/dist/guida/connectors/oauth.html +8 -8
  65. package/dist/guida/connectors/postgres.html +6 -6
  66. package/dist/guida/connectors/process.html +6 -6
  67. package/dist/guida/connectors/sendgrid.html +6 -6
  68. package/dist/guida/connectors/smtp.html +6 -6
  69. package/dist/guida/connectors/sqlserver.html +6 -6
  70. package/dist/guida/connectors/zoho.html +43 -0
  71. package/dist/guida/conventions/node-columns.html +6 -6
  72. package/dist/guida/conventions/node-descriptor.html +8 -8
  73. package/dist/guida/conventions/run-report.html +6 -6
  74. package/dist/guida/conventions/run-trace.html +6 -6
  75. package/dist/guida/conventions/variabili-del-core.html +5 -5
  76. package/dist/guida/conventions/versioni-di-pipeline.html +6 -6
  77. package/dist/guida/guide/claude-code/index.html +7 -7
  78. package/dist/guida/guide/claude-code/prompt.html +7 -7
  79. package/dist/guida/guide/claude-code/strumenti.html +5 -5
  80. package/dist/guida/guide/grafo.html +6 -6
  81. package/dist/guida/guide/usare/app-desktop.html +5 -5
  82. package/dist/guida/guide/usare/esito-di-una-run.html +6 -6
  83. package/dist/guida/guide/usare/index.html +5 -5
  84. package/dist/guida/hashmap.json +1 -1
  85. package/dist/guida/index.html +6 -6
  86. package/dist/guida/nodes/README.html +6 -6
  87. package/dist/guida/nodes/action.html +6 -6
  88. package/dist/guida/nodes/ai.html +6 -6
  89. package/dist/guida/nodes/join.html +6 -6
  90. package/dist/guida/nodes/lookup.html +6 -6
  91. package/dist/guida/nodes/pipeline.html +6 -6
  92. package/dist/guida/nodes/route.html +6 -6
  93. package/dist/guida/nodes/sink.html +6 -6
  94. package/dist/guida/nodes/source.html +8 -8
  95. package/dist/guida/nodes/task.html +6 -6
  96. package/dist/guida/nodes/transform.html +6 -6
  97. package/dist/guida/nodes/try-catch.html +6 -6
  98. package/dist/guida/nodes/union.html +6 -6
  99. package/dist/guida/pagine.json +1 -0
  100. package/dist/guida/pipelines/README.html +6 -6
  101. package/dist/guida/pipelines/crm-leads-sync.html +6 -6
  102. package/dist/guida/pipelines/cross-workspace-csv-merge.html +6 -6
  103. package/dist/guida/pipelines/movimenti-per-conto.html +6 -6
  104. package/dist/guida/pipelines/orders-enriched-daily.html +6 -6
  105. package/dist/guida/pipelines/test-posta.html +6 -6
  106. package/dist/guida/runbooks/aggiornamento-pm2.html +7 -7
  107. package/dist/guida/runbooks/deploy-ecr.html +6 -6
  108. package/dist/guida/runbooks/deployment.html +8 -8
  109. package/dist/guida/runbooks/etl-worker.html +6 -6
  110. package/dist/guida/runbooks/graph-server.html +6 -6
  111. package/dist/guida/runbooks/mask-key.html +6 -6
  112. package/dist/guida/runbooks/oauth-google-posta.html +6 -6
  113. package/dist/guida/runbooks/rollback-di-pipeline.html +6 -6
  114. package/dist/guida/runbooks/scd2-rehash.html +6 -6
  115. package/dist/guida/runbooks/sql-task-truncate-swap.html +6 -6
  116. package/dist/guida/runbooks/stato-incrementale.html +6 -6
  117. package/dist/guida/sub-pipelines/README.html +6 -6
  118. package/dist/guida/sub-pipelines/riepilogo-ordini.html +6 -6
  119. package/dist/index.js +1 -1
  120. package/dist/pipelines.js +1 -1
  121. package/dist/testing.js +1 -1
  122. package/kit/boilerplate/.github/workflows/ci.yml +1 -1
  123. package/kit/boilerplate/.github/workflows/image.yml +1 -1
  124. package/kit/boilerplate/package.json +1 -1
  125. package/kit/skills/etl-graph/references/wiring.md +4 -3
  126. package/kit/skills/new-connector/SKILL.md +1 -1
  127. package/package.json +12 -6
  128. package/dist/chunk-BFW7HTF6.js +0 -2
  129. package/dist/chunk-BPRH262Y.js +0 -2
  130. package/dist/chunk-DPWGI266.js +0 -1
  131. package/dist/chunk-H75NY6Z4.js +0 -1
  132. package/dist/chunk-HMED2UDJ.js +0 -2
  133. package/dist/chunk-MOHJWOCB.js +0 -1
  134. package/dist/chunk-MXSKD3Z4.js +0 -2
  135. package/dist/chunk-PGJWGJEB.js +0 -5
  136. package/dist/chunk-R53642SH.js +0 -1
  137. package/dist/chunk-RU6CZIDB.js +0 -1
  138. package/dist/chunk-UN3BPCPA.js +0 -1
  139. package/dist/chunk-XFHTODDW.js +0 -6
  140. package/dist/guida/assets/chunks/@localSearchIndexroot.08YFQ5n8.js +0 -1
  141. package/dist/guida/assets/connectors_README.md.ChyXSf73.js +0 -1
  142. package/dist/guida/assets/connectors_README.md.ChyXSf73.lean.js +0 -1
  143. package/dist/guida/assets/connectors_oauth.md.DUHajB0u.js +0 -7
  144. package/dist/guida/assets/connectors_oauth.md.DUHajB0u.lean.js +0 -1
  145. /package/dist/guida/assets/{GUIDA_SVILUPPO.md.D13C7Zwu.lean.js → GUIDA_SVILUPPO.md.CrN52ZDN.lean.js} +0 -0
  146. /package/dist/guida/assets/{TECHNICAL_OVERVIEW.md.DQP0pWc8.lean.js → TECHNICAL_OVERVIEW.md.DTIhkkg9.lean.js} +0 -0
  147. /package/dist/guida/assets/{conventions_node-descriptor.md.D8Si7E2S.lean.js → conventions_node-descriptor.md.MQaGlm8a.lean.js} +0 -0
  148. /package/dist/guida/assets/{guide_claude-code_index.md.CxVSru8e.lean.js → guide_claude-code_index.md.DEnzf9b_.lean.js} +0 -0
  149. /package/dist/guida/assets/{runbooks_aggiornamento-pm2.md.f3LAxif4.lean.js → runbooks_aggiornamento-pm2.md.DrFr4blI.lean.js} +0 -0
  150. /package/dist/guida/assets/{runbooks_deployment.md.CsIYRa_5.lean.js → runbooks_deployment.md.CwG77qGO.lean.js} +0 -0
@@ -0,0 +1,7 @@
1
+ import{_ as t,o,c as i,a5 as a}from"./chunks/framework.qdetmeNX.js";const p=JSON.parse('{"title":"OAuth2 per i connettori","description":"","frontmatter":{},"headers":[],"relativePath":"connectors/oauth.md","filePath":"connectors/oauth.md"}'),n={name:"connectors/oauth.md"};function s(d,e,r,c,l,h){return o(),i("div",null,[...e[0]||(e[0]=[a(`<h1 id="oauth2-per-i-connettori" tabindex="-1">OAuth2 per i connettori <a class="header-anchor" href="#oauth2-per-i-connettori" aria-label="Permalink to &quot;OAuth2 per i connettori&quot;">​</a></h1><p>Non è un connettore: è <strong>l&#39;identità</strong> che IMAP e SMTP usano per autenticarsi dove la password non basta più — Gmail, Google Workspace, Microsoft 365. Lo usa anche il connettore <a href="./zoho">Zoho CRM</a>, che autentica ogni richiesta alla Records API con il token che questa identità rinnova. Procedura passo passo nel runbook <a href="./../runbooks/oauth-google-posta">oauth-google-posta.md</a>.</p><h2 id="perche-esiste" tabindex="-1">Perché esiste <a class="header-anchor" href="#perche-esiste" aria-label="Permalink to &quot;Perché esiste&quot;">​</a></h2><p>I connettori sapevano già parlare XOAUTH2, ma un access token vive un&#39;ora: incollarne uno in <code>IMAP_ACCESS_TOKEN</code> è una configurazione che funziona per un&#39;ora e poi torna rossa. Questo modulo tiene il <strong>refresh token</strong> e scambia un access token nuovo quando serve.</p><h2 id="un-identita-due-connettori" tabindex="-1">Un&#39;identità, due connettori <a class="header-anchor" href="#un-identita-due-connettori" aria-label="Permalink to &quot;Un&#39;identità, due connettori&quot;">​</a></h2><p>La stessa casella Google si legge e si scrive con lo stesso consenso, quindi l&#39;identità sta in un registry suo e IMAP e SMTP la referenziano per id. Duplicare <code>CLIENT_SECRET</code> e <code>REFRESH_TOKEN</code> nei due blocchi significherebbe, prima o poi, ruotarne uno solo.</p><h2 id="variabili" tabindex="-1">Variabili <a class="header-anchor" href="#variabili" aria-label="Permalink to &quot;Variabili&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Variabile</th><th>Default</th><th>Note</th></tr></thead><tbody><tr><td><code>OAUTH_CLIENT_ID</code></td><td>—</td><td>obbligatoria se il registry è usato</td></tr><tr><td><code>OAUTH_CLIENT_SECRET</code></td><td>—</td><td>obbligatoria</td></tr><tr><td><code>OAUTH_REFRESH_TOKEN</code></td><td>—</td><td>obbligatoria; ottenuto una volta sola, vedi runbook</td></tr><tr><td><code>OAUTH_TOKEN_ENDPOINT</code></td><td><code>https://oauth2.googleapis.com/token</code></td><td><strong>deve essere <code>https://</code></strong>; Microsoft 365 si configura qui</td></tr><tr><td><code>OAUTH_SCOPE</code></td><td>—</td><td>solo se il provider lo vuole al refresh; Google no</td></tr><tr><td><code>OAUTH_INSTANCES</code></td><td>—</td><td>più caselle: <code>ordini,notifiche</code> → <code>OAUTH_&lt;ID&gt;_*</code></td></tr></tbody></table><p>Chi le usa:</p><table tabindex="0"><thead><tr><th>Variabile</th><th>Default</th><th>Note</th></tr></thead><tbody><tr><td><code>IMAP_AUTH=oauth2</code></td><td>dedotto</td><td>e <code>IMAP_PASSWORD</code> va <strong>tolta</strong></td></tr><tr><td><code>IMAP_OAUTH_INSTANCE</code></td><td><code>default</code></td><td>quale identità rinnova il token di quella casella</td></tr><tr><td><code>SMTP_AUTH=oauth2</code></td><td>dedotto</td><td>e <code>SMTP_PASSWORD</code> va <strong>tolta</strong></td></tr><tr><td><code>SMTP_OAUTH_INSTANCE</code></td><td><code>default</code></td><td>di norma la stessa di IMAP</td></tr><tr><td><code>ZOHO_&lt;ID&gt;_OAUTH_INSTANCE</code></td><td><code>default</code></td><td>l&#39;identità di un&#39;organizzazione <a href="./zoho">Zoho CRM</a>, con il token endpoint di Zoho</td></tr></tbody></table><p>Zoho risponde <code>200</code> anche a un refresh rifiutato, con <code>{ &quot;error&quot;: … }</code> nel corpo: il fornitore lo tratta come un rifiuto, un <code>ConfigError</code> con il codice di Zoho (per esempio <code>invalid_code</code>).</p><p>Le variabili sono dichiarate in <code>MANIFEST_OAUTH</code>: un&#39;identità incompleta dà un <code>ConfigError</code> che elenca <strong>tutte</strong> le variabili mancanti.</p><h3 id="nel-piano" tabindex="-1">Nel piano <a class="header-anchor" href="#nel-piano" aria-label="Permalink to &quot;Nel piano&quot;">​</a></h3><p>Un&#39;identità OAuth2 non è un nodo. Nel piano compare nella riga <code>credenziale</code> delle caselle IMAP e dei server SMTP che la usano: <code>OAuth · identità default · impostata</code>, oppure <code>… · mancano OAUTH_CLIENT_SECRET, OAUTH_REFRESH_TOKEN</code> con origine <code>mancante</code> e la variabile che punta alla prima da impostare. Un&#39;identità che non è in <code>OAUTH_INSTANCES</code> la run non la trova, anche se le sue variabili ci sono: il piano lo dice con <code>· manca OAUTH_INSTANCES</code>. Il piano la risolve con <code>risolviIdentitaOauth(id, env)</code>, che non lancia e dei segreti restituisce solo lo stato.</p><p>Per <code>etl env check</code>, <code>identitaOauthDichiarate(caselle, env)</code> dà le sole identità che le caselle date usano davvero, cioè quelle su <code>&lt;PREFIX&gt;AUTH=oauth2</code> senza <code>&lt;PREFIX&gt;ACCESS_TOKEN</code>, da aggiungere alle istanze di <code>ambienteDellaPipeline</code>: una pipeline con caselle su password non chiede variabili <code>OAUTH_*</code>.</p><h2 id="il-registry-puo-essere-vuoto" tabindex="-1">Il registry può essere vuoto <a class="header-anchor" href="#il-registry-puo-essere-vuoto" aria-label="Permalink to &quot;Il registry può essere vuoto&quot;">​</a></h2><p>È l&#39;unico, ed è deliberato. Un <code>PG_HOST</code> mancante è una configurazione rotta; OAuth2 invece è una <strong>scelta</strong>, e la maggioranza delle installazioni continuerà con una password. Senza <code>OAUTH_INSTANCES</code> né <code>OAUTH_CLIENT_ID</code> il registry esce vuoto e i connettori non cambiano comportamento.</p><p>La tolleranza finisce lì. Un&#39;istanza <strong>dichiarata</strong> in <code>OAUTH_INSTANCES</code> e incompleta è un errore, e un <code>IMAP_OAUTH_INSTANCE</code> che nomina un id inesistente pure: ricadere in silenzio sul token statico significherebbe autenticarsi con una credenziale diversa da quella che si crede.</p><h2 id="come-si-usa-dal-codice" tabindex="-1">Come si usa dal codice <a class="header-anchor" href="#come-si-usa-dal-codice" aria-label="Permalink to &quot;Come si usa dal codice&quot;">​</a></h2><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> oauth</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> fornitoriOauth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">loadOauthRegistry</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(env));</span></span>
2
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> tokenImap</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> oauth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(imap.auth, imap.oauthInstance);</span></span>
3
+ <span class="line"></span>
4
+ <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">imapSource</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(imap, {</span></span>
5
+ <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // …</span></span>
6
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ...</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(tokenImap </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!==</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> undefined</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ?</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { client: { accessToken: tokenImap } } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {}),</span></span>
7
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><strong>Un risolutore per run, non per nodo.</strong> <code>fornitoriOauth</code> memoizza per id d&#39;istanza: i nodi che condividono l&#39;identità condividono la cache del token. Una pipeline di posta può toccare la stessa casella in tre punti — sorgente, sessione delle action IMAP, notifiche SMTP — e senza la memoizzazione la stessa run chiederebbe tre token invece di uno. Il guaio non è lo spreco: è che funzionerebbe, quindi nessuno se ne accorgerebbe fino al primo rate limit.</p><p>Il fornitore serializza anche le richieste: due nodi che chiedono il token insieme sulla cache fredda fanno una chiamata sola.</p><h2 id="come-tratta-le-credenziali" tabindex="-1">Come tratta le credenziali <a class="header-anchor" href="#come-tratta-le-credenziali" aria-label="Permalink to &quot;Come tratta le credenziali&quot;">​</a></h2><ul><li><strong>Niente redirect.</strong> La <code>fetch</code> verso il token endpoint usa <code>redirect: &quot;error&quot;</code>. Il default di <code>fetch</code> è seguirli, e su un <code>307</code> il body — client secret e refresh token — viene ripetuto verso l&#39;host nuovo, anche in <code>http://</code>. Il vincolo <code>https://</code> guarda solo il primo URL: da solo non basterebbe.</li><li><strong>Niente credenziali nei messaggi d&#39;errore.</strong> Il testo che arriva dal provider viene redatto (client secret e refresh token sostituiti) e troncato a 160 caratteri: più d&#39;un IdP rieccheggia il valore rifiutato, e la CLI stampa gli errori su stderr.</li><li><strong>Nessuna <code>cause</code></strong>, come in IMAP e SMTP: <code>console.error</code> segue la catena delle cause per intero.</li><li><strong>Timeout di 30 secondi</strong>, come gli altri connettori: un endpoint muto non blocca la run.</li><li>La cache del token vive <strong>in memoria, per la durata della run</strong>. Mai su disco.</li></ul><h2 id="errori" tabindex="-1">Errori <a class="header-anchor" href="#errori" aria-label="Permalink to &quot;Errori&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Messaggio</th><th>Che cosa vuol dire</th></tr></thead><tbody><tr><td><code>OAuth2: refresh token rifiutato (invalid_grant)</code></td><td>Non più valido. Su un progetto Internal la causa prima è il <strong>cambio password della casella</strong>: lo scope è un ambito Gmail. Le altre cause sono nel runbook</td></tr><tr><td><code>OAuth2: il provider ha rifiutato la richiesta (invalid_client…)</code></td><td>Client ID o secret sbagliati</td></tr><tr><td><code>OAuth2: il token endpoint non risponde</code></td><td>Rete, DNS, timeout, o un redirect rifiutato</td></tr><tr><td><code>OAuth2: risposta del provider senza access_token utilizzabile</code></td><td>Il provider ha risposto 200 con un corpo che non contiene un token</td></tr><tr><td><code>Identità OAuth2 &quot;…&quot; non configurata</code></td><td><code>IMAP_OAUTH_INSTANCE</code> o <code>SMTP_OAUTH_INSTANCE</code> nomina un id che non esiste</td></tr></tbody></table>`,26)])])}const g=t(n,[["render",s]]);export{p as __pageData,g as default};
@@ -0,0 +1 @@
1
+ import{_ as t,o,c as i,a5 as a}from"./chunks/framework.qdetmeNX.js";const p=JSON.parse('{"title":"OAuth2 per i connettori","description":"","frontmatter":{},"headers":[],"relativePath":"connectors/oauth.md","filePath":"connectors/oauth.md"}'),n={name:"connectors/oauth.md"};function s(d,e,r,c,l,h){return o(),i("div",null,[...e[0]||(e[0]=[a("",26)])])}const g=t(n,[["render",s]]);export{p as __pageData,g as default};
@@ -0,0 +1,17 @@
1
+ import{_ as o,o as i,c as t,a5 as d}from"./chunks/framework.qdetmeNX.js";const u=JSON.parse('{"title":"Connettore: Zoho CRM (record di un modulo, con i campi dichiarati)","description":"","frontmatter":{},"headers":[],"relativePath":"connectors/zoho.md","filePath":"connectors/zoho.md"}'),a={name:"connectors/zoho.md"};function n(s,e,c,r,l,h){return i(),t("div",null,[...e[0]||(e[0]=[d(`<h1 id="connettore-zoho-crm-record-di-un-modulo-con-i-campi-dichiarati" tabindex="-1">Connettore: Zoho CRM (record di un modulo, con i campi dichiarati) <a class="header-anchor" href="#connettore-zoho-crm-record-di-un-modulo-con-i-campi-dichiarati" aria-label="Permalink to &quot;Connettore: Zoho CRM (record di un modulo, con i campi dichiarati)&quot;">​</a></h1><p>Legge i record di un modulo di <strong>Zoho CRM</strong> dentro il grafo: <code>zohoCrmRecords</code> è un <code>Source</code> che restituisce tutti i record del modulo, con i soli campi che il nodo dichiara, convertiti in colonne tipizzate. Codice in <code>src/connectors/zoho/</code>, subpath <code>@noeva/etl-core/connectors/zoho</code>; decisioni in ADR-0106.</p><p>Legge con la <strong>Records API v8</strong>, oppure, per i moduli oltre i 100.000 record, con la <strong>Query API (COQL)</strong>. Come <a href="./jira">Jira</a> (ADR-0100) il connettore non ha un trasporto suo: parla con <a href="./http#trasporto-condiviso--richiestahttp"><code>richiestaHttp</code></a>, e ne eredita timeout, tetto sui byte, abort, validazione Zod e retry di 429 e 5xx. Il token lo rinnova un&#39;identità del modulo <a href="./oauth">OAuth2</a>, con il refresh token di Zoho.</p><table tabindex="0"><thead><tr><th>Funzione</th><th>Tipo</th><th>Cosa fa</th></tr></thead><tbody><tr><td><code>zohoCrmRecords</code></td><td><code>Source</code></td><td>I record di un modulo, con i campi dichiarati, in colonne</td></tr><tr><td><code>loadZohoRegistry</code></td><td>registry</td><td>Le organizzazioni configurate, per istanza (ADR-0030)</td></tr><tr><td><code>loadZohoConfig</code></td><td>config</td><td>Una sola organizzazione, da variabili con prefisso</td></tr><tr><td><code>loadZohoInstance</code></td><td>config</td><td>Una sola organizzazione del registry, senza le altre</td></tr><tr><td><code>istanzaZohoPerIlPiano</code></td><td>piano</td><td>L&#39;organizzazione per il piano, con la sua ricaduta</td></tr><tr><td><code>trasportoZoho</code></td><td>config</td><td>La config del trasporto <code>http</code> per una richiesta, col token</td></tr><tr><td><code>MANIFEST_ZOHO</code></td><td>config</td><td>Le variabili di un&#39;organizzazione, per il piano (ADR-0089)</td></tr><tr><td><code>valoreZoho</code>, <code>colonnaZoho</code></td><td>utilità</td><td>La conversione di un valore e il nome della sua colonna</td></tr><tr><td><code>schemaRecordZoho</code></td><td>contratto</td><td>Lo schema Zod <code>strict</code> di un record letto con quei campi</td></tr><tr><td><code>nomiColonneZoho</code></td><td>utilità</td><td>Le colonne di un record, <code>id</code> compreso: quelle di un sink</td></tr><tr><td><code>colonneZoho</code>, <code>tipoColonnaZoho</code></td><td>utilità</td><td>Le colonne con il campo da cui vengono, e il loro tipo</td></tr><tr><td><code>dettaglioCredenzialeZoho</code></td><td>descriptor</td><td>La riga <code>credenziale</code>, per un nodo Zoho</td></tr><tr><td><code>maxCampiDi</code>, <code>eCampoUtente</code></td><td>utilità</td><td>I campi ammessi da una lettura; se un campo è un utente</td></tr><tr><td><code>LetturaZoho</code>, <code>CampoZoho</code>, …</td><td>tipi</td><td>La lettura (<code>records</code> o <code>coql</code>), un campo, un record</td></tr><tr><td><code>MAX_*</code>, <code>DEFAULT_ZOHO_*</code>, <code>CAMPO_*</code>, <code>SUFFISSO_NOME</code></td><td>costanti</td><td>I tetti di Zoho, i default del connettore, i nomi fissi</td></tr></tbody></table><h2 id="configurazione" tabindex="-1">Configurazione <a class="header-anchor" href="#configurazione" aria-label="Permalink to &quot;Configurazione&quot;">​</a></h2><p><code>loadZohoRegistry(env?)</code> risolve le organizzazioni: con <code>ZOHO_INSTANCES=vendite</code> ognuna ha le sue <code>ZOHO_&lt;ID&gt;_*</code>, senza lista valgono le variabili base <code>ZOHO_*</code> come istanza <code>default</code>.</p><table tabindex="0"><thead><tr><th>Variabile</th><th>Default</th><th>Note</th></tr></thead><tbody><tr><td><code>ZOHO_INSTANCES</code></td><td>—</td><td>elenco delle organizzazioni; senza, l&#39;istanza <code>default</code> dalle variabili base</td></tr><tr><td><code>ZOHO_&lt;ID&gt;_BASE_URL</code></td><td>—</td><td>obbligatoria; la base delle API v8 del data center, <code>https://www.zohoapis.eu/crm/v8</code></td></tr><tr><td><code>ZOHO_&lt;ID&gt;_OAUTH_INSTANCE</code></td><td><code>default</code></td><td>l&#39;identità <code>OAUTH_&lt;ID&gt;_*</code> che rinnova il token</td></tr><tr><td><code>ZOHO_&lt;ID&gt;_TIMEOUT_MS</code></td><td><code>60000</code></td><td>tempo massimo di una richiesta, in millisecondi</td></tr></tbody></table><p>Qui non c&#39;è nessun segreto. Client id, client secret e refresh token stanno nell&#39;identità OAuth2, con il token endpoint del data center di Zoho:</p><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:#24292E;--shiki-dark:#E1E4E8;">OAUTH_INSTANCES</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">zoho_vendite</span></span>
2
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">OAUTH_ZOHO_VENDITE_TOKEN_ENDPOINT</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">https://accounts.zoho.eu/oauth/v2/token</span></span>
3
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">OAUTH_ZOHO_VENDITE_CLIENT_ID</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">client</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> id</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> della</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> Zoho</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> API</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> Consol</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span>
4
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">OAUTH_ZOHO_VENDITE_CLIENT_SECRET</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">nel</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> .env</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> del</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> worker,</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> mai</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> nel</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> repositor</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">y</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span>
5
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">OAUTH_ZOHO_VENDITE_REFRESH_TOKEN</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">nel</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> .env</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> del</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> worker,</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> mai</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> nel</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> repositor</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">y</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span></code></pre></div><p>Il refresh token vuole gli scope <code>ZohoCRM.modules.READ</code> (i record) e <code>ZohoCRM.settings.fields.READ</code> (il catalogo dei campi), più <code>ZohoCRM.coql.READ</code> se un nodo legge con COQL: tutti e tre di sola lettura. Il data center della base delle API e quello del token endpoint devono essere lo stesso: un token di <code>accounts.zoho.eu</code> vale solo su <code>zohoapis.eu</code>.</p><p><code>BASE_URL</code> vuole <code>https</code> e deve finire con <code>/crm/v8</code>; <code>http</code> è ammesso solo verso la macchina locale, per un server di test. Gli errori nominano le variabili, mai i valori.</p><h2 id="source-—-zohocrmrecords" tabindex="-1">Source — <code>zohoCrmRecords</code> <a class="header-anchor" href="#source-—-zohocrmrecords" aria-label="Permalink to &quot;Source — \`zohoCrmRecords\`&quot;">​</a></h2><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> token</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> fornitoreToken</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">loadOauthRegistry</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">get</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(config.oauthInstance));</span></span>
6
+ <span class="line"></span>
7
+ <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">zohoCrmRecords</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
8
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> config, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// loadZohoRegistry().get(&quot;vendite&quot;)</span></span>
9
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> token, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// un fornitore per run, condiviso fra i nodi</span></span>
10
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> instanceId: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;vendite&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
11
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> modulo: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Deals&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
12
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> campi: [</span></span>
13
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { nome: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Stage&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, tipo: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;picklist&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
14
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { nome: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Owner&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, tipo: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;ownerlookup&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
15
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { nome: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Modified_Time&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, tipo: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;datetime&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
16
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ],</span></span>
17
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Opzione</th><th>Default</th><th>Note</th></tr></thead><tbody><tr><td><code>config</code></td><td>—</td><td>l&#39;organizzazione</td></tr><tr><td><code>token</code></td><td>—</td><td><code>() =&gt; Promise&lt;string&gt;</code>, da <code>fornitoreToken</code></td></tr><tr><td><code>modulo</code></td><td>—</td><td>il nome API del modulo (<code>Deals</code>, <code>omniconnectforzohocrm__Chat_Messages</code>)</td></tr><tr><td><code>campi</code></td><td>—</td><td>i campi, con il <code>data_type</code> di Zoho: 48 oltre a <code>Modified_Time</code> con <code>records</code>; con <code>coql</code> 499, nome e cognome di ogni utente compresi, e al più 15 collegamenti a utenti</td></tr><tr><td><code>lettura</code></td><td><code>records</code></td><td><code>records</code> (Records API, fino a 100.000 record) o <code>coql</code> (Query API, senza tetto)</td></tr><tr><td><code>name</code>, <code>instanceId</code></td><td>—</td><td>nome del nodo e istanza mostrata nel DAG</td></tr><tr><td><code>perPagina</code></td><td><code>200</code></td><td><code>records</code>: record per pagina, fra 1 e 200</td></tr><tr><td><code>maxPerInterrogazione</code></td><td><code>100000</code></td><td><code>records</code>: il tetto di Zoho per interrogazione; più basso solo nei test</td></tr><tr><td><code>perQuery</code></td><td><code>2000</code></td><td><code>coql</code>: record per query, fra 1 e 2000</td></tr><tr><td><code>retry</code>, <code>fetchImpl</code></td><td>—</td><td>retry di ogni richiesta (default 5 tentativi, attese fino a 60 s); <code>fetch</code> finto nei test</td></tr></tbody></table><h3 id="i-campi-sono-la-regola-di-privacy" tabindex="-1">I campi sono la regola di privacy <a class="header-anchor" href="#i-campi-sono-la-regola-di-privacy" aria-label="Permalink to &quot;I campi sono la regola di privacy&quot;">​</a></h3><p>Il source chiede a Zoho <strong>solo</strong> i campi dichiarati, più <code>id</code> (e, con <code>records</code>, <code>Modified_Time</code>; con <code>coql</code> anche nome e cognome degli utenti, vedi sotto), ed emette solo le loro colonne: un campo che Zoho manda senza che lo si chieda non esce. Un campo nuovo in Zoho non entra finché qualcuno non lo dichiara. Per la stessa ragione lo schema di <code>schemaRecordZoho</code> è <code>strict</code>: un record con una colonna in più non passa il contratto.</p><p>A ogni run il source legge prima il catalogo dei campi del modulo (<code>GET /settings/fields</code>): un campo dichiarato che Zoho non conosce più è un <code>ConfigError</code> che lo nomina, <strong>prima</strong> della prima pagina. Un tipo cambiato si segnala nel log (<code>zoho-source.tipo-cambiato</code>).</p><h3 id="colonne-e-valori" tabindex="-1">Colonne e valori <a class="header-anchor" href="#colonne-e-valori" aria-label="Permalink to &quot;Colonne e valori&quot;">​</a></h3><p>Il nome della colonna è il nome API in minuscolo, con i caratteri non di parola in <code>_</code> (<code>Account_Name</code> → <code>account_name</code>). La conversione è quella dello script che leggeva il CRM del primo cliente prima di questo connettore:</p><table tabindex="0"><thead><tr><th>Tipo Zoho</th><th>Colonna</th></tr></thead><tbody><tr><td><code>lookup</code></td><td>il solo <code>id</code> del record collegato, mai il nome</td></tr><tr><td><code>userlookup</code>, <code>ownerlookup</code></td><td>l&#39;<code>id</code>, e il nome dell&#39;utente Zoho in <code>&lt;colonna&gt;_nome</code></td></tr><tr><td><code>multiselectpicklist</code> e liste</td><td>le voci unite da <code>&quot;; &quot;</code></td></tr><tr><td><code>datetime</code></td><td>l&#39;ora locale come la dà Zoho, senza fuso: <code>AAAA-MM-GGTHH:MM:SS</code></td></tr><tr><td><code>date</code></td><td><code>AAAA-MM-GG</code></td></tr><tr><td><code>boolean</code></td><td>booleano</td></tr><tr><td><code>integer</code></td><td>intero</td></tr><tr><td><code>double</code>, <code>currency</code>, <code>decimal</code>, <code>percent</code></td><td>numero</td></tr><tr><td>il resto (testo, picklist, formule)</td><td>testo</td></tr></tbody></table><p>Un valore vuoto è <code>null</code>. Un valore che non si converte nel tipo del suo campo è un <code>ExtractError</code> che nomina modulo, campo e <code>id</code> del record, mai il valore.</p><h3 id="le-due-letture" tabindex="-1">Le due letture <a class="header-anchor" href="#le-due-letture" aria-label="Permalink to &quot;Le due letture&quot;">​</a></h3><p>Entrambe leggono il modulo <strong>in ordine di <code>id</code></strong>, in sequenza: un blocco si chiede solo quando chi legge ha consumato il precedente, e in memoria restano gli <code>id</code> visti, non i record. Un modulo vuoto (Zoho risponde <code>204</code>) non dà record.</p><p>L&#39;ordine è per <code>id</code> perché un <code>id</code> non cambia mai. La prima versione ordinava per <code>Modified_Time</code>, e nella prima prova su un CRM reale perdeva fra lo 0,1% e il 13% dei record per modulo: un record modificato durante la lettura passa in fondo all&#39;ordinamento, compare due volte e fa scivolare il confine fra due pagine, così un altro record salta.</p><ul><li><strong><code>records</code></strong> (default): la Records API, <code>GET /{modulo}?sort_by=id&amp;sort_order=asc</code>, pagine da 200 con <code>page_token</code>. Non va oltre 100.000 record per interrogazione: arrivato al tetto, il source si ferma con un <code>ExtractError</code> che indica la lettura <code>coql</code>, invece di lasciare un modulo troncato. <code>more_records</code> senza <code>next_page_token</code>, o un token già visto, è un <code>ExtractError</code>.</li><li><strong><code>coql</code></strong>: la Query API, <code>POST /coql</code> con <code>select &#39;id&#39;, &#39;Campo&#39;, … from Modulo where id &gt; &#39;&lt;ultimo&gt;&#39; order by id asc limit 2000</code>. Ogni query riparte dall&#39;ultimo <code>id</code> del blocco prima, come raccomanda Zoho per andare oltre i 100.000 record: nessun tetto, e dieci volte meno chiamate della Records API. Fino a 499 campi per query, quindi un modulo largo non si divide in passate. I nomi dei campi e del modulo sono nomi API già validati, e l&#39;<code>id</code> che entra nella query è di sole cifre: un <code>id</code> che non lo è, o un blocco i cui <code>id</code> non crescono, è un <code>ExtractError</code>. COQL restituisce un utente come <code>{ id, name }</code>, ma in <code>name</code> mette il solo cognome (e per alcuni utenti niente), mentre la Records API dà nome e cognome. Per ogni collegamento a un utente la query chiede quindi anche <code>&#39;&lt;Campo&gt;.first_name&#39;</code> e <code>&#39;&lt;Campo&gt;.last_name&#39;</code>, con una join sul modulo degli utenti, e la colonna <code>_nome</code> è «Nome Cognome», come con la Records API (<code>full_name</code> COQL non lo accetta). Senza nome né cognome resta il <code>name</code> di COQL; se manca anche quello la colonna resta vuota e il log lo segnala (<code>zoho-source.nome-utente-assente</code>). Nome e cognome contano fra i 499 campi della query, e i collegamenti a utenti sono al più 15, le join che COQL ammette. COQL non ammette i campi multi-select lookup, upload di file e immagini, e al più cinque campi formula dinamici.</li></ul><h3 id="token-ed-errori" tabindex="-1">Token ed errori <a class="header-anchor" href="#token-ed-errori" aria-label="Permalink to &quot;Token ed errori&quot;">​</a></h3><p>Il token si chiede al fornitore a <strong>ogni</strong> richiesta, con l&#39;header <code>Authorization: Zoho-oauthtoken &lt;token&gt;</code>: una lettura che dura più della vita del token si rinnova da sé. Zoho risponde <code>200</code> anche a un refresh rifiutato, con <code>{ &quot;error&quot;: … }</code> nel corpo: il fornitore lo tratta come un rifiuto e lo dice con il codice di Zoho, come un <code>ConfigError</code>.</p><p>Gli errori di lettura sono <code>ExtractError</code> con metodo, percorso e status, più un suggerimento per <code>400</code>, <code>401</code>, <code>403</code> e <code>404</code>. Mai il token, mai il corpo della risposta.</p><h3 id="nel-dag" tabindex="-1">Nel DAG <a class="header-anchor" href="#nel-dag" aria-label="Permalink to &quot;Nel DAG&quot;">​</a></h3><p>Il descriptor ha <code>kind: &quot;zoho-source&quot;</code>, l&#39;istanza, poi <code>api</code> (la base delle API, con la sua variabile), <code>modulo</code>, <code>lettura</code>, <code>campi</code>, e in fondo la <code>credenziale</code>: quale identità OAuth2 rinnova il token e, nel piano, se le sue variabili ci sono tutte o quali mancano. Mai un segreto.</p><h2 id="test" tabindex="-1">Test <a class="header-anchor" href="#test" aria-label="Permalink to &quot;Test&quot;">​</a></h2><p><code>src/connectors/zoho/*.test.ts</code>: configurazione e registry, descriptor senza segreti, conversione e nomi di colonna, paginazione per <code>id</code> con <code>page_token</code> e il tetto che indica COQL, lettura COQL a chiavi crescenti di <code>id</code> (query, blocchi, <code>id</code> non crescenti o non numerici), campo sconosciuto prima della prima pagina, privacy (nessun campo non dichiarato esce), token chiesto a ogni richiesta, retry di un 429. Nessuna chiamata a Zoho vero: <code>fetchImpl</code> finto e dati sintetici.</p>`,32)])])}const k=o(a,[["render",n]]);export{u as __pageData,k as default};
@@ -0,0 +1 @@
1
+ import{_ as o,o as i,c as t,a5 as d}from"./chunks/framework.qdetmeNX.js";const u=JSON.parse('{"title":"Connettore: Zoho CRM (record di un modulo, con i campi dichiarati)","description":"","frontmatter":{},"headers":[],"relativePath":"connectors/zoho.md","filePath":"connectors/zoho.md"}'),a={name:"connectors/zoho.md"};function n(s,e,c,r,l,h){return i(),t("div",null,[...e[0]||(e[0]=[d("",32)])])}const k=o(a,[["render",n]]);export{u as __pageData,k as default};
@@ -16,7 +16,7 @@ import{_ as e,o as s,c as a,a5 as n}from"./chunks/framework.qdetmeNX.js";const k
16
16
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> kind</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// es. &quot;postgres&quot;, &quot;sqlserver&quot;, &quot;noeva-file&quot;, &quot;file&quot;, &quot;memory&quot;</span></span>
17
17
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> connection</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> ConnectorConnectionRef</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// assente senza registry</span></span>
18
18
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> details</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> ConnectorDetail</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[];</span></span>
19
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Un segreto non entra nel descriptor in nessuna forma, nemmeno mascherata: non c&#39;è un valore da svelare, e quindi nemmeno un flag <code>sensitive</code>. Di una credenziale si dice solo <strong>quale variante</strong> è in uso e se è impostata, in una riga <code>credenziale</code>: <code>password · impostata</code>, <code>access token · impostato</code>, <code>token · impostato</code> (HTTP), <code>chiave API · impostata</code> (Noeva), <code>OAuth · identità default · impostata</code>. Se non ne è impostata nessuna, la riga elenca le alternative ammesse ed è <code>mancante</code>; se mancano variabili della variante scelta, le nomina (<code>basic · mancano HTTP_USERNAME, HTTP_PASSWORD</code>) e la sua variabile è la prima da impostare, quella che il badge deve indicare. Con OAuth2 dice anche se l&#39;identità che rinnova il token è completa, o quali sue variabili mancano. Un utente di posta non si mostra mai, quindi se manca lo dice questa riga (<code>… · manca IMAP_USER</code>): senza, il nodo sembrerebbe sano. <strong>La riga <code>credenziale</code> non è mai il primo dettaglio</strong>: la card del nodo mostra il primo, e lì va il sistema a cui il nodo punta.</p><p>Anche un valore non segreto che sia un URL perde le credenziali scritte nella userinfo (<code>utente:password@</code>): lo fanno <code>dettaglioVariabile</code> per le righe dei nodi e <code>variabileDelPiano</code> per <code>PlanSpec.configuration</code> (<code>withoutCredentials</code>, <code>src/connectors/shared/credenziali-url.ts</code>). Un descriptor che compone un URL a mano passa da lì.</p><p><code>env</code> e <code>origine</code> dicono <strong>quale variabile</strong> del <code>.env</code> ha prodotto un dettaglio e <strong>da dove</strong> arriva il valore: <code>env</code> (impostata), <code>default</code> (presa dal codice), <code>mancante</code> (obbligatoria e assente), <code>non impostata</code> (facoltativa, senza default). Servono al pannello del nodo per indicare la riga del <code>.env</code> da correggere e il nodo che ha davvero un problema. Un dettaglio corrisponde a una variabile: <code>host</code> e <code>porta</code> sono righe separate. Restano assenti sui dettagli che non vengono da una variabile (query, tabella, cartella scritte nella pipeline). Oggi li popolano IMAP, SMTP, SendGrid, HTTP, Jira, Noeva, Postgres e SQL Server, che leggono la configurazione dal manifest (sotto); gli altri connettori arrivano un tipo alla volta. Le righe che vengono da variabili della pipeline (la cartella di <code>salva-eml</code> in <code>test-posta</code>) le annota la pipeline stessa, con <code>conVariabili</code>.</p><p>Il campo è <strong>opzionale</strong> su <code>Source</code>/<code>Sink</code> (<code>descriptor?</code>). <code>toPlanSpec</code> (<code>src/core/plan-spec.ts</code>) lo proietta su <code>PlanNode.descriptor</code>, da cui viaggia in <code>etl plan</code> → <code>plans.generated.json</code> → UI.</p><p><strong>Solo i nodi che parlano con l&#39;esterno: <code>source</code>, <code>sink</code>, <code>lookup</code>, <code>ai</code>, <code>action</code> e <code>task</code>.</strong> Il <code>lookup</code> (e allo stesso modo il nodo <code>ai</code>, per esempio <code>noevaAiExtract</code> con kind <code>noeva-ai-extract</code>) prende il descriptor dal suo <code>LookupResolver</code> (<code>mssqlLookup</code>: kind <code>sqlserver-lookup</code>; <code>postgresLookup</code>: kind <code>postgres-lookup</code>; entrambi con la query; <code>httpLookup</code>: kind <code>http-lookup</code>, con base, metodo ed endpoint col segnaposto <code>{chiave}</code>; <code>jiraIssueLookup</code> e i lookup delle liste Jira: kind <code>jira-lookup</code>, con sito, operazione e campi). L&#39;<code>action</code> dalla sua <code>Action</code>, dove è <strong>obbligatorio</strong>. Il <code>task</code> dal suo <code>Task</code> (<code>postgresSqlTask</code>: kind <code>postgres-task</code>; <code>mssqlSqlTask</code>: kind <code>sqlserver-task</code>). <code>transform</code>/<code>route</code>/<code>join</code>/<code>union</code>/<code>try-catch</code> non sono connettori e non ricevono un descriptor (<code>planNodeDescriptor</code> ritorna <code>undefined</code> per quei kind).</p><h2 id="le-tre-regole-vincolanti" tabindex="-1">Le tre regole vincolanti <a class="header-anchor" href="#le-tre-regole-vincolanti" aria-label="Permalink to &quot;Le tre regole vincolanti&quot;">​</a></h2><ol><li><strong>Whitelist esplicita, mai un dump.</strong> <code>details</code> elenca campi scelti a mano. Non serializzare l&#39;oggetto opzioni: conterrebbe <code>password</code>/<code>apiKey</code>/pool.</li><li><strong>Niente segreti.</strong> host/porta/database si leggono dalla config <strong>pubblica</strong> del pool, o dalla risoluzione dell&#39;istanza nel piano, mai da campi credenziale. Se un valore non è derivabile si <strong>omette</strong> il detail — non si inventa e non si mette <code>undefined</code>.</li><li><strong>Un test anti-segreto per connettore.</strong> Ogni connettore ha un <code>descriptor.test.ts</code> che verifica <code>kind</code>, i campi attesi e che nessun <code>value</code> contenga il segreto della fixture (vedi esempi in <code>src/connectors/*/</code>). Sopra c&#39;è <code>etl catalog check</code> (regola <code>piano-senza-segreti</code>), che prende l&#39;ambiente da <code>.env.example</code>, mette un valore riconoscibile al posto di ogni segreto e verifica che il piano di <strong>ogni</strong> pipeline del catalogo non lo contenga, anche con le credenziali alternative commentate. Vale in ogni repo: nel core lo lancia <code>pnpm run check</code>, e <code>.env.example</code> del core porta le variabili di tutte le pipeline del suo catalogo.</li></ol><h2 id="campi-esposti-oggi-per-connettore" tabindex="-1">Campi esposti oggi, per connettore <a class="header-anchor" href="#campi-esposti-oggi-per-connettore" aria-label="Permalink to &quot;Campi esposti oggi, per connettore&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Connettore</th><th><code>kind</code></th><th><code>details</code> (label) — solo non sensibili</th><th>Fonte</th></tr></thead><tbody><tr><td>Postgres</td><td><code>postgres</code></td><td>host, porta, database, query (source) / table (sink)</td><td><code>pool.options</code> + query/table</td></tr><tr><td>SQL Server</td><td><code>sqlserver</code></td><td>host, porta, database, query (source) / table (sink)</td><td><code>pool.config</code> (runtime) + query/table</td></tr><tr><td>HTTP lookup</td><td><code>http-lookup</code></td><td>base, richiesta, modalità, credenziale (la variante di <code>HTTP_AUTH</code>). Mai token, chiave, utente né nome dell&#39;header</td><td>config + opzioni del lookup</td></tr><tr><td>HTTP action</td><td><code>http-action</code></td><td>base, richiesta, su errore, scrittura, credenziale. Mai token, chiave, utente né nome dell&#39;header</td><td>config + opzioni dell&#39;action</td></tr><tr><td>Jira source</td><td><code>jira-source</code></td><td>sito, gateway (token con scope), jql, campi (come dichiarati, per id o per nome, <code>updated</code> compreso), raw (solo con <code>raw: true</code>), watermark (solo in incrementale: <code>updated (timestamp)</code> e la sovrapposizione), credenziale («token classico» o «token con scope» e lo stato). Mai token, email né header</td><td>config + opzioni di <code>jiraIssues</code></td></tr><tr><td>Jira lookup</td><td><code>jira-lookup</code></td><td>sito, gateway (token con scope), operazione (<code>issue per chiave</code>; per le liste <code>changelog per issue</code>, <code>commenti per issue</code>, <code>worklog per issue</code> con l&#39;endpoint), campi (come dichiarati, per id o per nome, <code>updated</code> compreso; per il changelog i <code>fieldIds</code>, se filtra), raw (solo con <code>raw: true</code>), credenziale («token classico» o «token con scope» e lo stato). Mai token, email, header né chiavi</td><td>config + opzioni di <code>jiraIssueLookup</code>, <code>jiraChangelogLookup</code>, <code>jiraCommentsLookup</code>, <code>jiraWorklogsLookup</code></td></tr><tr><td>Jira action</td><td><code>jira-action</code></td><td>sito, gateway (token con scope), operazione (con l&#39;endpoint, senza la chiave della issue), su errore, idempotenza, limite (chiamate al secondo, letture comprese), ID esterno e creazione (solo l&#39;upsert: il campo con la sua variabile, e la creazione mai ritentata), deduplica (solo commenti e worklog: la proprietà che porta la chiave e dove si cerca, mai la chiave), verso (solo i link: partenza → arrivo), testo ricco (i campi che accettano markdown), credenziale. Mai token, email, header né valori dei campi</td><td>config + opzioni dell&#39;action Jira</td></tr><tr><td>Noeva file</td><td><code>noeva-file</code></td><td>baseUrl, workspace, fileName/fileId/fuzzyQuery (source) / fileName, mode, folderId (sink)</td><td>getter pubblici del client + opzioni</td></tr><tr><td>File</td><td><code>file</code></td><td>storage, codec, path/prefix</td><td>nome storage/codec + opzioni</td></tr><tr><td>Noeva cartella</td><td><code>noeva-folder</code></td><td>baseUrl, workspace, folderId, includeSubfolders, skipIfMetadataKey, maxFiles, skipVersion (se attivo)</td><td>getter pubblici del client + opzioni</td></tr><tr><td>Noeva multi-file</td><td><code>noeva-files</code></td><td>baseUrl, workspace, mode, folderId</td><td>getter pubblici del client + opzioni</td></tr><tr><td>Noeva upload</td><td><code>noeva-upload</code></td><td>baseUrl, workspace, se già presente, elaborazione AI, folderId, categoria</td><td>getter pubblici del client + opzioni</td></tr><tr><td>Noeva elaborazione</td><td><code>noeva-elaborazione</code></td><td>baseUrl, workspace, pronto (la definizione usata)</td><td>getter pubblici del client</td></tr><tr><td>Noeva testo</td><td><code>noeva-contenuto</code></td><td>baseUrl, workspace</td><td>getter pubblici del client</td></tr><tr><td>Noeva estrazione AI</td><td><code>noeva-ai-extract</code></td><td>baseUrl, workspace, modello, campi, temperature, maxTokens (mai prompt né testi)</td><td>getter pubblici del client + schema</td></tr><tr><td>Cartella locale</td><td><code>local-folder</code></td><td>cartella (come configurata, non risolta), estensioni, età minima, maxFiles</td><td>opzioni di <code>localFolderSource</code></td></tr><tr><td>IMAP</td><td><code>imap</code></td><td>host, porta; cartella, filtro, maxMessages (sorgente); aggiunge/toglie (flag); destinazione (spostamento); credenziale. Mai utente né segreti</td><td>config + opzioni di sorgente e action</td></tr><tr><td>SMTP</td><td><code>smtp</code></td><td>host, porta, mittente (<code>SMTP_FROM</code>), credenziale. Mai utente, segreti né destinatari</td><td>config</td></tr><tr><td>SendGrid</td><td><code>sendgrid</code></td><td>mittente (<code>SENDGRID_FROM</code>), base, sandbox, credenziale (solo lo stato). Mai la chiave né i destinatari</td><td>config</td></tr><tr><td>Solo log</td><td><code>log</code></td><td>esito</td><td>sink che registrano e non scrivono</td></tr><tr><td>SQL Server lookup</td><td><code>sqlserver-lookup</code></td><td>host, porta, database, query (+ <code>connection</code> dal registry)</td><td><code>pool.config</code> (runtime) + query</td></tr><tr><td>Postgres lookup</td><td><code>postgres-lookup</code></td><td>host, porta, database, query (+ <code>connection</code> dal registry)</td><td><code>pool.options</code> + query</td></tr><tr><td>Postgres task</td><td><code>postgres-task</code></td><td>host, porta, database, statement o statement 1…N (letterali mascherati), params (soli nomi), destructive (+ <code>connection</code>)</td><td><code>pool.options</code> + opzioni del task</td></tr><tr><td>SQL Server task</td><td><code>sqlserver-task</code></td><td>host, porta, database, statement o statement 1…N (letterali mascherati), params (soli nomi), destructive (+ <code>connection</code>)</td><td><code>pool.config</code> (runtime) + opzioni</td></tr><tr><td>Array (mem.)</td><td><code>memory</code></td><td>— (nessuno)</td><td><code>arraySource</code>/<code>arraySink</code></td></tr><tr><td>Processo esterno</td><td><code>processo-esterno</code></td><td>eseguibile, argomenti fissi, versione, timeout, ambiente (solo i <strong>nomi</strong> delle variabili in allowlist, mai i valori)</td><td>opzioni dell&#39;action</td></tr></tbody></table><p>Tutte le righe Noeva della tabella cominciano con baseUrl e workspace, da <code>clientDetails</code>. Con un client costruito dal manifest, subito dopo ci sono la riga <code>configurazione</code> (solo nel client d&#39;esempio, per un valore non valido) e la riga <code>credenziale</code> con lo stato della chiave API (<code>NOEVA_API_KEY</code>). Un client scritto a mano non ha la credenziale.</p><p>La <code>query</code> è mostrata <strong>troncata a 120 caratteri</strong> (<code>queryDetail</code>): è un &quot;puntamento&quot;, non il payload. Nel piano, dove non c&#39;è un pool, host, porta e database vengono dalla risoluzione dell&#39;istanza (vedi sotto).</p><h2 id="aggiungere-un-descriptor-a-un-nuovo-connettore" tabindex="-1">Aggiungere un descriptor a un nuovo connettore <a class="header-anchor" href="#aggiungere-un-descriptor-a-un-nuovo-connettore" aria-label="Permalink to &quot;Aggiungere un descriptor a un nuovo connettore&quot;">​</a></h2><ol><li><p>Nel factory del <code>Source</code>/<code>Sink</code>, costruisci il descriptor con i <strong>soli</strong> campi non sensibili noti alla costruzione:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
19
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Un segreto non entra nel descriptor in nessuna forma, nemmeno mascherata: non c&#39;è un valore da svelare, e quindi nemmeno un flag <code>sensitive</code>. Di una credenziale si dice solo <strong>quale variante</strong> è in uso e se è impostata, in una riga <code>credenziale</code>: <code>password · impostata</code>, <code>access token · impostato</code>, <code>token · impostato</code> (HTTP), <code>chiave API · impostata</code> (Noeva), <code>OAuth · identità default · impostata</code>. Se non ne è impostata nessuna, la riga elenca le alternative ammesse ed è <code>mancante</code>; se mancano variabili della variante scelta, le nomina (<code>basic · mancano HTTP_USERNAME, HTTP_PASSWORD</code>) e la sua variabile è la prima da impostare, quella che il badge deve indicare. Con OAuth2 dice anche se l&#39;identità che rinnova il token è completa, o quali sue variabili mancano. Un utente di posta non si mostra mai, quindi se manca lo dice questa riga (<code>… · manca IMAP_USER</code>): senza, il nodo sembrerebbe sano. <strong>La riga <code>credenziale</code> non è mai il primo dettaglio</strong>: la card del nodo mostra il primo, e lì va il sistema a cui il nodo punta.</p><p>Anche un valore non segreto che sia un URL perde le credenziali scritte nella userinfo (<code>utente:password@</code>): lo fanno <code>dettaglioVariabile</code> per le righe dei nodi e <code>variabileDelPiano</code> per <code>PlanSpec.configuration</code> (<code>withoutCredentials</code>, <code>src/connectors/shared/credenziali-url.ts</code>). Un descriptor che compone un URL a mano passa da lì.</p><p><code>env</code> e <code>origine</code> dicono <strong>quale variabile</strong> del <code>.env</code> ha prodotto un dettaglio e <strong>da dove</strong> arriva il valore: <code>env</code> (impostata), <code>default</code> (presa dal codice), <code>mancante</code> (obbligatoria e assente), <code>non impostata</code> (facoltativa, senza default). Servono al pannello del nodo per indicare la riga del <code>.env</code> da correggere e il nodo che ha davvero un problema. Un dettaglio corrisponde a una variabile: <code>host</code> e <code>porta</code> sono righe separate. Restano assenti sui dettagli che non vengono da una variabile (query, tabella, cartella scritte nella pipeline). Oggi li popolano IMAP, SMTP, SendGrid, HTTP, Jira, Zoho, Noeva, Postgres e SQL Server, che leggono la configurazione dal manifest (sotto); gli altri connettori arrivano un tipo alla volta. Le righe che vengono da variabili della pipeline (la cartella di <code>salva-eml</code> in <code>test-posta</code>) le annota la pipeline stessa, con <code>conVariabili</code>.</p><p>Il campo è <strong>opzionale</strong> su <code>Source</code>/<code>Sink</code> (<code>descriptor?</code>). <code>toPlanSpec</code> (<code>src/core/plan-spec.ts</code>) lo proietta su <code>PlanNode.descriptor</code>, da cui viaggia in <code>etl plan</code> → <code>plans.generated.json</code> → UI.</p><p><strong>Solo i nodi che parlano con l&#39;esterno: <code>source</code>, <code>sink</code>, <code>lookup</code>, <code>ai</code>, <code>action</code> e <code>task</code>.</strong> Il <code>lookup</code> (e allo stesso modo il nodo <code>ai</code>, per esempio <code>noevaAiExtract</code> con kind <code>noeva-ai-extract</code>) prende il descriptor dal suo <code>LookupResolver</code> (<code>mssqlLookup</code>: kind <code>sqlserver-lookup</code>; <code>postgresLookup</code>: kind <code>postgres-lookup</code>; entrambi con la query; <code>httpLookup</code>: kind <code>http-lookup</code>, con base, metodo ed endpoint col segnaposto <code>{chiave}</code>; <code>jiraIssueLookup</code> e i lookup delle liste Jira: kind <code>jira-lookup</code>, con sito, operazione e campi). L&#39;<code>action</code> dalla sua <code>Action</code>, dove è <strong>obbligatorio</strong>. Il <code>task</code> dal suo <code>Task</code> (<code>postgresSqlTask</code>: kind <code>postgres-task</code>; <code>mssqlSqlTask</code>: kind <code>sqlserver-task</code>). <code>transform</code>/<code>route</code>/<code>join</code>/<code>union</code>/<code>try-catch</code> non sono connettori e non ricevono un descriptor (<code>planNodeDescriptor</code> ritorna <code>undefined</code> per quei kind).</p><h2 id="le-tre-regole-vincolanti" tabindex="-1">Le tre regole vincolanti <a class="header-anchor" href="#le-tre-regole-vincolanti" aria-label="Permalink to &quot;Le tre regole vincolanti&quot;">​</a></h2><ol><li><strong>Whitelist esplicita, mai un dump.</strong> <code>details</code> elenca campi scelti a mano. Non serializzare l&#39;oggetto opzioni: conterrebbe <code>password</code>/<code>apiKey</code>/pool.</li><li><strong>Niente segreti.</strong> host/porta/database si leggono dalla config <strong>pubblica</strong> del pool, o dalla risoluzione dell&#39;istanza nel piano, mai da campi credenziale. Se un valore non è derivabile si <strong>omette</strong> il detail — non si inventa e non si mette <code>undefined</code>.</li><li><strong>Un test anti-segreto per connettore.</strong> Ogni connettore ha un <code>descriptor.test.ts</code> che verifica <code>kind</code>, i campi attesi e che nessun <code>value</code> contenga il segreto della fixture (vedi esempi in <code>src/connectors/*/</code>). Sopra c&#39;è <code>etl catalog check</code> (regola <code>piano-senza-segreti</code>), che prende l&#39;ambiente da <code>.env.example</code>, mette un valore riconoscibile al posto di ogni segreto e verifica che il piano di <strong>ogni</strong> pipeline del catalogo non lo contenga, anche con le credenziali alternative commentate. Vale in ogni repo: nel core lo lancia <code>pnpm run check</code>, e <code>.env.example</code> del core porta le variabili di tutte le pipeline del suo catalogo.</li></ol><h2 id="campi-esposti-oggi-per-connettore" tabindex="-1">Campi esposti oggi, per connettore <a class="header-anchor" href="#campi-esposti-oggi-per-connettore" aria-label="Permalink to &quot;Campi esposti oggi, per connettore&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Connettore</th><th><code>kind</code></th><th><code>details</code> (label) — solo non sensibili</th><th>Fonte</th></tr></thead><tbody><tr><td>Postgres</td><td><code>postgres</code></td><td>host, porta, database, query (source) / table (sink)</td><td><code>pool.options</code> + query/table</td></tr><tr><td>SQL Server</td><td><code>sqlserver</code></td><td>host, porta, database, query (source) / table (sink)</td><td><code>pool.config</code> (runtime) + query/table</td></tr><tr><td>HTTP lookup</td><td><code>http-lookup</code></td><td>base, richiesta, modalità, credenziale (la variante di <code>HTTP_AUTH</code>). Mai token, chiave, utente né nome dell&#39;header</td><td>config + opzioni del lookup</td></tr><tr><td>HTTP action</td><td><code>http-action</code></td><td>base, richiesta, su errore, scrittura, credenziale. Mai token, chiave, utente né nome dell&#39;header</td><td>config + opzioni dell&#39;action</td></tr><tr><td>Jira source</td><td><code>jira-source</code></td><td>sito, gateway (token con scope), jql, campi (come dichiarati, per id o per nome, <code>updated</code> compreso), raw (solo con <code>raw: true</code>), watermark (solo in incrementale: <code>updated (timestamp)</code> e la sovrapposizione), credenziale («token classico» o «token con scope» e lo stato). Mai token, email né header</td><td>config + opzioni di <code>jiraIssues</code></td></tr><tr><td>Jira lookup</td><td><code>jira-lookup</code></td><td>sito, gateway (token con scope), operazione (<code>issue per chiave</code>; per le liste <code>changelog per issue</code>, <code>commenti per issue</code>, <code>worklog per issue</code> con l&#39;endpoint), campi (come dichiarati, per id o per nome, <code>updated</code> compreso; per il changelog i <code>fieldIds</code>, se filtra), raw (solo con <code>raw: true</code>), credenziale («token classico» o «token con scope» e lo stato). Mai token, email, header né chiavi</td><td>config + opzioni di <code>jiraIssueLookup</code>, <code>jiraChangelogLookup</code>, <code>jiraCommentsLookup</code>, <code>jiraWorklogsLookup</code></td></tr><tr><td>Jira action</td><td><code>jira-action</code></td><td>sito, gateway (token con scope), operazione (con l&#39;endpoint, senza la chiave della issue), su errore, idempotenza, limite (chiamate al secondo, letture comprese), ID esterno e creazione (solo l&#39;upsert: il campo con la sua variabile, e la creazione mai ritentata), deduplica (solo commenti e worklog: la proprietà che porta la chiave e dove si cerca, mai la chiave), verso (solo i link: partenza → arrivo), testo ricco (i campi che accettano markdown), credenziale. Mai token, email, header né valori dei campi</td><td>config + opzioni dell&#39;action Jira</td></tr><tr><td>Zoho source</td><td><code>zoho-source</code></td><td>api (la base delle API, con la sua variabile), modulo, lettura (Records API o COQL), campi (i nomi API dichiarati), credenziale (l&#39;identità OAuth2 che rinnova il token e, nel piano, se è completa). Mai token, client secret né refresh token</td><td>config + opzioni di <code>zohoCrmRecords</code></td></tr><tr><td>Noeva file</td><td><code>noeva-file</code></td><td>baseUrl, workspace, fileName/fileId/fuzzyQuery (source) / fileName, mode, folderId (sink)</td><td>getter pubblici del client + opzioni</td></tr><tr><td>File</td><td><code>file</code></td><td>storage, codec, path/prefix</td><td>nome storage/codec + opzioni</td></tr><tr><td>Noeva cartella</td><td><code>noeva-folder</code></td><td>baseUrl, workspace, folderId, includeSubfolders, skipIfMetadataKey, maxFiles, skipVersion (se attivo)</td><td>getter pubblici del client + opzioni</td></tr><tr><td>Noeva multi-file</td><td><code>noeva-files</code></td><td>baseUrl, workspace, mode, folderId</td><td>getter pubblici del client + opzioni</td></tr><tr><td>Noeva upload</td><td><code>noeva-upload</code></td><td>baseUrl, workspace, se già presente, elaborazione AI, folderId, categoria</td><td>getter pubblici del client + opzioni</td></tr><tr><td>Noeva elaborazione</td><td><code>noeva-elaborazione</code></td><td>baseUrl, workspace, pronto (la definizione usata)</td><td>getter pubblici del client</td></tr><tr><td>Noeva testo</td><td><code>noeva-contenuto</code></td><td>baseUrl, workspace</td><td>getter pubblici del client</td></tr><tr><td>Noeva estrazione AI</td><td><code>noeva-ai-extract</code></td><td>baseUrl, workspace, modello, campi, temperature, maxTokens (mai prompt né testi)</td><td>getter pubblici del client + schema</td></tr><tr><td>Cartella locale</td><td><code>local-folder</code></td><td>cartella (come configurata, non risolta), estensioni, età minima, maxFiles</td><td>opzioni di <code>localFolderSource</code></td></tr><tr><td>IMAP</td><td><code>imap</code></td><td>host, porta; cartella, filtro, maxMessages (sorgente); aggiunge/toglie (flag); destinazione (spostamento); credenziale. Mai utente né segreti</td><td>config + opzioni di sorgente e action</td></tr><tr><td>SMTP</td><td><code>smtp</code></td><td>host, porta, mittente (<code>SMTP_FROM</code>), credenziale. Mai utente, segreti né destinatari</td><td>config</td></tr><tr><td>SendGrid</td><td><code>sendgrid</code></td><td>mittente (<code>SENDGRID_FROM</code>), base, sandbox, credenziale (solo lo stato). Mai la chiave né i destinatari</td><td>config</td></tr><tr><td>Solo log</td><td><code>log</code></td><td>esito</td><td>sink che registrano e non scrivono</td></tr><tr><td>SQL Server lookup</td><td><code>sqlserver-lookup</code></td><td>host, porta, database, query (+ <code>connection</code> dal registry)</td><td><code>pool.config</code> (runtime) + query</td></tr><tr><td>Postgres lookup</td><td><code>postgres-lookup</code></td><td>host, porta, database, query (+ <code>connection</code> dal registry)</td><td><code>pool.options</code> + query</td></tr><tr><td>Postgres task</td><td><code>postgres-task</code></td><td>host, porta, database, statement o statement 1…N (letterali mascherati), params (soli nomi), destructive (+ <code>connection</code>)</td><td><code>pool.options</code> + opzioni del task</td></tr><tr><td>SQL Server task</td><td><code>sqlserver-task</code></td><td>host, porta, database, statement o statement 1…N (letterali mascherati), params (soli nomi), destructive (+ <code>connection</code>)</td><td><code>pool.config</code> (runtime) + opzioni</td></tr><tr><td>Array (mem.)</td><td><code>memory</code></td><td>— (nessuno)</td><td><code>arraySource</code>/<code>arraySink</code></td></tr><tr><td>Processo esterno</td><td><code>processo-esterno</code></td><td>eseguibile, argomenti fissi, versione, timeout, ambiente (solo i <strong>nomi</strong> delle variabili in allowlist, mai i valori)</td><td>opzioni dell&#39;action</td></tr></tbody></table><p>Tutte le righe Noeva della tabella cominciano con baseUrl e workspace, da <code>clientDetails</code>. Con un client costruito dal manifest, subito dopo ci sono la riga <code>configurazione</code> (solo nel client d&#39;esempio, per un valore non valido) e la riga <code>credenziale</code> con lo stato della chiave API (<code>NOEVA_API_KEY</code>). Un client scritto a mano non ha la credenziale.</p><p>La <code>query</code> è mostrata <strong>troncata a 120 caratteri</strong> (<code>queryDetail</code>): è un &quot;puntamento&quot;, non il payload. Nel piano, dove non c&#39;è un pool, host, porta e database vengono dalla risoluzione dell&#39;istanza (vedi sotto).</p><h2 id="aggiungere-un-descriptor-a-un-nuovo-connettore" tabindex="-1">Aggiungere un descriptor a un nuovo connettore <a class="header-anchor" href="#aggiungere-un-descriptor-a-un-nuovo-connettore" aria-label="Permalink to &quot;Aggiungere un descriptor a un nuovo connettore&quot;">​</a></h2><ol><li><p>Nel factory del <code>Source</code>/<code>Sink</code>, costruisci il descriptor con i <strong>soli</strong> campi non sensibili noti alla costruzione:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
20
20
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> name,</span></span>
21
21
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> descriptor: {</span></span>
22
22
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> kind: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;mio-sistema&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
@@ -1,4 +1,4 @@
1
- import{_ as i,o as a,c as o,a5 as s}from"./chunks/framework.qdetmeNX.js";const u=JSON.parse('{"title":"Dal bisogno al processo","description":"","frontmatter":{},"headers":[],"relativePath":"guide/claude-code/index.md","filePath":"guide/claude-code/index.md"}'),t={name:"guide/claude-code/index.md"};function l(n,e,r,c,d,p){return a(),o("div",null,[...e[0]||(e[0]=[s(`<h1 id="dal-bisogno-al-processo" tabindex="-1">Dal bisogno al processo <a class="header-anchor" href="#dal-bisogno-al-processo" aria-label="Permalink to &quot;Dal bisogno al processo&quot;">​</a></h1><p>Un processo nuovo non si disegna in un&#39;interfaccia: si scrive con Claude Code nel <strong>repo cliente</strong>, <code>noeva-etl-&lt;slug&gt;</code>, e arriva nell&#39;app passando da una Pull Request e da un deploy. Il repo cliente contiene già ciò che serve perché Claude lo faccia secondo le regole del core: il kit dell&#39;agente, con le skill che generano lo scheletro, una skill che insegna come si costruisce un grafo e i subagent che lo materializzano e lo rivedono. Sono tutti nel <a href="./strumenti">catalogo degli strumenti</a>. Le cartelle del repo, il catalogo e i comandi <code>etl</code> sono nella <a href="./../../GUIDA_SVILUPPO">guida allo sviluppo</a>.</p><p>La parte che nessun agente può inventare è il <strong>dominio</strong>: da dove leggere, cosa trasformare, dove scrivere, cosa fare degli errori. Se manca, l&#39;agente si ferma e la chiede invece di indovinarla.</p><h2 id="prima-di-iniziare" tabindex="-1">Prima di iniziare <a class="header-anchor" href="#prima-di-iniziare" aria-label="Permalink to &quot;Prima di iniziare&quot;">​</a></h2><p>Servono accesso al repo cliente e al pacchetto del core, Node ≥ 20, pnpm 9 e Claude Code. Ogni attività vive in un <strong>worktree</strong> suo, con un branch staccato da <code>dev</code>: così puoi portare avanti più processi in parallelo senza che si pestino i piedi.</p><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;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> fetch</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> origin</span></span>
1
+ import{_ as i,o as a,c as o,a5 as s}from"./chunks/framework.qdetmeNX.js";const u=JSON.parse('{"title":"Dal bisogno al processo","description":"","frontmatter":{},"headers":[],"relativePath":"guide/claude-code/index.md","filePath":"guide/claude-code/index.md"}'),t={name:"guide/claude-code/index.md"};function l(n,e,r,c,d,p){return a(),o("div",null,[...e[0]||(e[0]=[s(`<h1 id="dal-bisogno-al-processo" tabindex="-1">Dal bisogno al processo <a class="header-anchor" href="#dal-bisogno-al-processo" aria-label="Permalink to &quot;Dal bisogno al processo&quot;">​</a></h1><p>Un processo nuovo non si disegna in un&#39;interfaccia: si scrive con Claude Code nel <strong>repo cliente</strong>, <code>noeva-etl-&lt;slug&gt;</code>, e arriva nell&#39;app passando da una Pull Request e da un deploy. Il repo cliente contiene già ciò che serve perché Claude lo faccia secondo le regole del core: il kit dell&#39;agente, con le skill che generano lo scheletro, una skill che insegna come si costruisce un grafo e i subagent che lo materializzano e lo rivedono. Sono tutti nel <a href="./strumenti">catalogo degli strumenti</a>. Le cartelle del repo, il catalogo e i comandi <code>etl</code> sono nella <a href="./../../GUIDA_SVILUPPO">guida allo sviluppo</a>.</p><p>La parte che nessun agente può inventare è il <strong>dominio</strong>: da dove leggere, cosa trasformare, dove scrivere, cosa fare degli errori. Se manca, l&#39;agente si ferma e la chiede invece di indovinarla.</p><h2 id="prima-di-iniziare" tabindex="-1">Prima di iniziare <a class="header-anchor" href="#prima-di-iniziare" aria-label="Permalink to &quot;Prima di iniziare&quot;">​</a></h2><p>Servono accesso al repo cliente e al pacchetto del core, Node ≥ 26, pnpm 9 e Claude Code. Ogni attività vive in un <strong>worktree</strong> suo, con un branch staccato da <code>dev</code>: così puoi portare avanti più processi in parallelo senza che si pestino i piedi.</p><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;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> fetch</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> origin</span></span>
2
2
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> worktree</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> add</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --no-track</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -b</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> feat/fatture-clienti-daily</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .claude/worktrees/fatture-clienti-daily</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> origin/dev</span></span>
3
3
  <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .claude/worktrees/fatture-clienti-daily</span></span>
4
4
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> install</span></span>
@@ -1,10 +1,10 @@
1
- import{_ as t,C as n,o,c as r,j as i,a,E as l,a5 as d}from"./chunks/framework.qdetmeNX.js";const m=JSON.parse('{"title":"Nodo: source","description":"","frontmatter":{"pageClass":"etl-wide"},"headers":[],"relativePath":"nodes/source.md","filePath":"nodes/source.md"}'),p={name:"nodes/source.md"};function h(c,s,k,u,g,E){const e=n("NodeDemo");return o(),r("div",null,[s[0]||(s[0]=i("h1",{id:"nodo-source",tabindex:"-1"},[a("Nodo: source "),i("a",{class:"header-anchor",href:"#nodo-source","aria-label":'Permalink to "Nodo: source"'},"​")],-1)),s[1]||(s[1]=i("p",null,[a("Il punto d'ingresso di un flusso: estrae record da un sistema esterno e li emette "),i("strong",null,"in streaming"),a(", uno alla volta, senza mai caricarli tutti in memoria. Ogni grafo ne ha almeno uno.")],-1)),l(e,{kind:"source"}),s[2]||(s[2]=d(`<table tabindex="0"><thead><tr><th>Metodo</th><th><code>.source(id, source, { after?, purpose?, writeReport? })</code></th></tr></thead><tbody><tr><td>Ingressi</td><td>0</td></tr><tr><td>Uscite</td><td>≥1 (fan-out libero)</td></tr><tr><td>Dead-letter</td><td>no: un errore di estrazione ferma la run</td></tr><tr><td>Codice</td><td><code>Source&lt;T&gt;</code> in <code>src/core/connector.ts</code></td></tr></tbody></table><h2 id="quando-usarlo" tabindex="-1">Quando usarlo <a class="header-anchor" href="#quando-usarlo" aria-label="Permalink to &quot;Quando usarlo&quot;">​</a></h2><p>Per ogni sistema da cui il processo <strong>parte</strong>: una tabella, un file, una cartella, una casella di posta, un workspace Noeva. Se invece i dati esterni servono ad <strong>arricchire</strong> record che scorrono già nel grafo, e vanno letti solo per le chiavi presenti, è un <a href="./lookup"><code>lookup</code></a>.</p><h2 id="il-contratto" tabindex="-1">Il contratto <a class="header-anchor" href="#il-contratto" aria-label="Permalink to &quot;Il contratto&quot;">​</a></h2><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">interface</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">T</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt; {</span></span>
1
+ import{_ as t,C as n,o,c as r,j as i,a,E as l,a5 as d}from"./chunks/framework.qdetmeNX.js";const m=JSON.parse('{"title":"Nodo: source","description":"","frontmatter":{"pageClass":"etl-wide"},"headers":[],"relativePath":"nodes/source.md","filePath":"nodes/source.md"}'),h={name:"nodes/source.md"};function p(c,s,k,u,g,E){const e=n("NodeDemo");return o(),r("div",null,[s[0]||(s[0]=i("h1",{id:"nodo-source",tabindex:"-1"},[a("Nodo: source "),i("a",{class:"header-anchor",href:"#nodo-source","aria-label":'Permalink to "Nodo: source"'},"​")],-1)),s[1]||(s[1]=i("p",null,[a("Il punto d'ingresso di un flusso: estrae record da un sistema esterno e li emette "),i("strong",null,"in streaming"),a(", uno alla volta, senza mai caricarli tutti in memoria. Ogni grafo ne ha almeno uno.")],-1)),l(e,{kind:"source"}),s[2]||(s[2]=d(`<table tabindex="0"><thead><tr><th>Metodo</th><th><code>.source(id, source, { after?, purpose?, writeReport? })</code></th></tr></thead><tbody><tr><td>Ingressi</td><td>0</td></tr><tr><td>Uscite</td><td>≥1 (fan-out libero)</td></tr><tr><td>Dead-letter</td><td>no: un errore di estrazione ferma la run</td></tr><tr><td>Codice</td><td><code>Source&lt;T&gt;</code> in <code>src/core/connector.ts</code></td></tr></tbody></table><h2 id="quando-usarlo" tabindex="-1">Quando usarlo <a class="header-anchor" href="#quando-usarlo" aria-label="Permalink to &quot;Quando usarlo&quot;">​</a></h2><p>Per ogni sistema da cui il processo <strong>parte</strong>: una tabella, un file, una cartella, una casella di posta, un workspace Noeva. Se invece i dati esterni servono ad <strong>arricchire</strong> record che scorrono già nel grafo, e vanno letti solo per le chiavi presenti, è un <a href="./lookup"><code>lookup</code></a>.</p><h2 id="il-contratto" tabindex="-1">Il contratto <a class="header-anchor" href="#il-contratto" aria-label="Permalink to &quot;Il contratto&quot;">​</a></h2><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">interface</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">T</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt; {</span></span>
2
2
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> name</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
3
3
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> extract</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> RunContext</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">incremental</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> IncrementalExtract</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> AsyncIterable</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">T</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;;</span></span>
4
4
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> descriptor</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> ConnectorDescriptor</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// che cos&#39;è e dove punta, per il DAG</span></span>
5
5
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> columns</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> PlanColumn</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[]; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// campi emessi, se non c&#39;è uno schema Zod</span></span>
6
6
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> watermark</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> SourceWatermark</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// presente se la source è incrementale</span></span>
7
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>La source si <strong>inietta</strong> nella funzione che costruisce il grafo, non si istanzia dentro: così la pipeline si prova con <code>arraySource</code> e <code>getSpec()</code> mostra la topologia senza credenziali.</p><h2 id="source-pronte" tabindex="-1">Source pronte <a class="header-anchor" href="#source-pronte" aria-label="Permalink to &quot;Source pronte&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Funzione</th><th>Sistema</th><th>Scheda</th></tr></thead><tbody><tr><td><code>postgresSource</code></td><td>PostgreSQL (cursor)</td><td><a href="./../connectors/postgres">postgres</a></td></tr><tr><td><code>mssqlSource</code></td><td>SQL Server</td><td><a href="./../connectors/sqlserver">sqlserver</a></td></tr><tr><td><code>fileSource</code>, <code>localFolderSource</code></td><td>File (storage × codec)</td><td><a href="./../connectors/file">file</a></td></tr><tr><td><code>noevaFileSource</code>, <code>noevaFolderSource</code></td><td>Workspace Noeva</td><td><a href="./../connectors/noeva">noeva</a></td></tr><tr><td><code>imapSource</code></td><td>Casella di posta</td><td><a href="./../connectors/imap">imap</a></td></tr><tr><td><code>jiraIssues</code></td><td>Jira Cloud (issue di una JQL)</td><td><a href="./../connectors/jira">jira</a></td></tr><tr><td><code>arraySource(name, rows)</code></td><td>In memoria: test e configurazione</td><td>—</td></tr></tbody></table><h2 id="esempio" tabindex="-1">Esempio <a class="header-anchor" href="#esempio" aria-label="Permalink to &quot;Esempio&quot;">​</a></h2><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">graph</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;fatture-giornaliere&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
7
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>La source si <strong>inietta</strong> nella funzione che costruisce il grafo, non si istanzia dentro: così la pipeline si prova con <code>arraySource</code> e <code>getSpec()</code> mostra la topologia senza credenziali.</p><h2 id="source-pronte" tabindex="-1">Source pronte <a class="header-anchor" href="#source-pronte" aria-label="Permalink to &quot;Source pronte&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Funzione</th><th>Sistema</th><th>Scheda</th></tr></thead><tbody><tr><td><code>postgresSource</code></td><td>PostgreSQL (cursor)</td><td><a href="./../connectors/postgres">postgres</a></td></tr><tr><td><code>mssqlSource</code></td><td>SQL Server</td><td><a href="./../connectors/sqlserver">sqlserver</a></td></tr><tr><td><code>fileSource</code>, <code>localFolderSource</code></td><td>File (storage × codec)</td><td><a href="./../connectors/file">file</a></td></tr><tr><td><code>noevaFileSource</code>, <code>noevaFolderSource</code></td><td>Workspace Noeva</td><td><a href="./../connectors/noeva">noeva</a></td></tr><tr><td><code>imapSource</code></td><td>Casella di posta</td><td><a href="./../connectors/imap">imap</a></td></tr><tr><td><code>jiraIssues</code></td><td>Jira Cloud (issue di una JQL)</td><td><a href="./../connectors/jira">jira</a></td></tr><tr><td><code>zohoCrmRecords</code></td><td>Zoho CRM (record di un modulo)</td><td><a href="./../connectors/zoho">zoho</a></td></tr><tr><td><code>arraySource(name, rows)</code></td><td>In memoria: test e configurazione</td><td>—</td></tr></tbody></table><h2 id="esempio" tabindex="-1">Esempio <a class="header-anchor" href="#esempio" aria-label="Permalink to &quot;Esempio&quot;">​</a></h2><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">graph</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;fatture-giornaliere&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
8
8
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;fatture&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, sources.fatture) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Source&lt;unknown&gt;: il contratto lo fa il nodo dopo</span></span>
9
9
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;clienti&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, sources.clienti)</span></span>
10
10
  <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>
@@ -30,4 +30,4 @@ import{_ as t,C as n,o,c as r,j as i,a,E as l,a5 as d}from"./chunks/framework.qd
30
30
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> lookback: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">5</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> *</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 60_000</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// opzionale, in millisecondi: copre le transazioni lunghe</span></span>
31
31
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
32
32
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Esito della run</th><th>Il watermark avanza?</th></tr></thead><tbody><tr><td><code>success</code></td><td>sì</td></tr><tr><td><code>partial</code></td><td>no, salvo <code>graph(nome, { commitOn: &quot;partial&quot; })</code>, e solo se ogni scarto è una dead-letter per record</td></tr><tr><td><code>failed</code></td><td>mai</td></tr></tbody></table><p>Regole da tenere a mente:</p><ul><li><strong>Il confine è <code>&gt;=</code></strong>, non <code>&gt;</code>: due run consecutive senza dati nuovi rileggono le righe al confine. Per questo una source incrementale scrive <strong>solo verso sink idempotenti</strong>.</li><li><strong>Senza il segnaposto <code>:watermark</code> la costruzione fallisce</strong> (source SQL): una query incrementale non degrada in silenzio in un full scan.</li><li><strong>Il watermark è testo</strong>, nella precisione del database: i microsecondi di Postgres non si perdono passando da una <code>Date</code>.</li><li><strong>Lo store lo inietta chi lancia la run</strong> (<code>ctx.stateStore</code>): un file locale per <code>etl run</code>, <code>noeva-server-api</code> per il worker e per <code>etl run --workspace &lt;id&gt;</code>. Un grafo con source incrementali non parte senza. Nei test si usa <code>MemoryPipelineStateStore</code>.</li><li><strong>Backfill:</strong> <code>params.watermark.&lt;nodeId&gt;</code> sostituisce in lettura il valore salvato, e non fa arretrare lo stato. <strong>Reset:</strong> <code>etl state reset</code>, l&#39;unico modo di farlo arretrare.</li></ul><p>Oggi sono incrementali <code>postgresSource</code>, <code>mssqlSource</code> e <code>jiraIssues</code> con <code>incremental</code> (il filtro su <code>updated</code> lo scrive il connettore: vedi <a href="./../connectors/jira">jira</a>, «Modalità incrementale»). Operatività, diagnosi e procedure: <a href="./../runbooks/stato-incrementale">runbook</a>.</p><h2 id="partire-dopo-un-altro-nodo-after" tabindex="-1">Partire dopo un altro nodo: <code>after</code> <a class="header-anchor" href="#partire-dopo-un-altro-nodo-after" aria-label="Permalink to &quot;Partire dopo un altro nodo: \`after\`&quot;">​</a></h2><p>Con <code>after</code> la source ha un <strong>gate</strong>: <code>extract()</code> non viene chiamato finché i nodi elencati non sono <strong>riusciti</strong>. Sono <a href="./task"><code>task</code></a> o <code>sink</code>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;ordini&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, ordini, { after: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;svuota-staging&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] }) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// dopo un task: pre-task</span></span>
33
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;fatti&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, fatti, { after: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;carica-dimensioni&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] }) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// dopo un sink: dimensioni prima dei fatti</span></span></code></pre></div><ul><li>Più nodi in <code>after</code> valgono in AND.</li><li>Tutto ciò che sta a valle aspetta con lei: un lookup sui fatti legge le dimensioni già caricate, e un sink a valle non chiama <code>load</code> finché il gate non si apre.</li><li>Se un predecessore non è riuscito la source è <strong>saltata</strong>: <code>extract()</code> non viene mai chiamato, e i nodi a valle sono saltati con lei. Vedi <a href="./task#nodi-saltati"><code>task</code></a>.</li><li><code>build()</code> rifiuta un <code>after</code> che crea un ciclo (il sink alimentato dalla source stessa) o un deadlock su un <code>join</code> o un <code>union</code> a valle.</li></ul><h2 id="errori" tabindex="-1">Errori <a class="header-anchor" href="#errori" aria-label="Permalink to &quot;Errori&quot;">​</a></h2><p><code>extract</code> è un contratto <strong>opaco</strong>: non isola il singolo record. Un errore di estrazione (<code>ExtractError</code>) interrompe la run, anche sotto un <code>try-catch</code>, perché la source sta a monte di ogni scope. Il retry non si applica alle source: rileggere non è sempre senza effetti.</p><h2 id="nel-dag-e-nel-report" tabindex="-1">Nel DAG e nel report <a class="header-anchor" href="#nel-dag-e-nel-report" aria-label="Permalink to &quot;Nel DAG e nel report&quot;">​</a></h2><p>Il nodo mostra il <code>descriptor</code> (tipo di connettore, istanza, puntamenti; mai segreti) e le colonne dichiarate in <code>columns</code>. Nel report, <code>extracted</code> conta i record emessi. Una source saltata ha <code>skipped: { because }</code> e <code>startedAt: null</code>. Una source incrementale ha anche una voce in <a href="./../conventions/run-report#stato-di-pipeline-state"><code>state</code></a>: da dove ha letto, cosa propone, se ha committato.</p><h2 id="anti-pattern" tabindex="-1">Anti-pattern <a class="header-anchor" href="#anti-pattern" aria-label="Permalink to &quot;Anti-pattern&quot;">​</a></h2><ul><li><code>Array.fromAsync(source.extract(ctx))</code>, o qualunque cosa che legga tutto in memoria: si perde lo streaming e con lui la backpressure.</li><li>Istanziare il client o il pool dentro <code>build…Pipeline</code>: va iniettato.</li></ul>`,29))])}const F=t(p,[["render",h]]);export{m as __pageData,F as default};
33
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;fatti&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, fatti, { after: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;carica-dimensioni&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] }) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// dopo un sink: dimensioni prima dei fatti</span></span></code></pre></div><ul><li>Più nodi in <code>after</code> valgono in AND.</li><li>Tutto ciò che sta a valle aspetta con lei: un lookup sui fatti legge le dimensioni già caricate, e un sink a valle non chiama <code>load</code> finché il gate non si apre.</li><li>Se un predecessore non è riuscito la source è <strong>saltata</strong>: <code>extract()</code> non viene mai chiamato, e i nodi a valle sono saltati con lei. Vedi <a href="./task#nodi-saltati"><code>task</code></a>.</li><li><code>build()</code> rifiuta un <code>after</code> che crea un ciclo (il sink alimentato dalla source stessa) o un deadlock su un <code>join</code> o un <code>union</code> a valle.</li></ul><h2 id="errori" tabindex="-1">Errori <a class="header-anchor" href="#errori" aria-label="Permalink to &quot;Errori&quot;">​</a></h2><p><code>extract</code> è un contratto <strong>opaco</strong>: non isola il singolo record. Un errore di estrazione (<code>ExtractError</code>) interrompe la run, anche sotto un <code>try-catch</code>, perché la source sta a monte di ogni scope. Il retry non si applica alle source: rileggere non è sempre senza effetti.</p><h2 id="nel-dag-e-nel-report" tabindex="-1">Nel DAG e nel report <a class="header-anchor" href="#nel-dag-e-nel-report" aria-label="Permalink to &quot;Nel DAG e nel report&quot;">​</a></h2><p>Il nodo mostra il <code>descriptor</code> (tipo di connettore, istanza, puntamenti; mai segreti) e le colonne dichiarate in <code>columns</code>. Nel report, <code>extracted</code> conta i record emessi. Una source saltata ha <code>skipped: { because }</code> e <code>startedAt: null</code>. Una source incrementale ha anche una voce in <a href="./../conventions/run-report#stato-di-pipeline-state"><code>state</code></a>: da dove ha letto, cosa propone, se ha committato.</p><h2 id="anti-pattern" tabindex="-1">Anti-pattern <a class="header-anchor" href="#anti-pattern" aria-label="Permalink to &quot;Anti-pattern&quot;">​</a></h2><ul><li><code>Array.fromAsync(source.extract(ctx))</code>, o qualunque cosa che legga tutto in memoria: si perde lo streaming e con lui la backpressure.</li><li>Istanziare il client o il pool dentro <code>build…Pipeline</code>: va iniettato.</li></ul>`,29))])}const F=t(h,[["render",p]]);export{m as __pageData,F as default};
@@ -1 +1 @@
1
- import{_ as t,C as n,o,c as r,j as i,a,E as l,a5 as d}from"./chunks/framework.qdetmeNX.js";const m=JSON.parse('{"title":"Nodo: source","description":"","frontmatter":{"pageClass":"etl-wide"},"headers":[],"relativePath":"nodes/source.md","filePath":"nodes/source.md"}'),p={name:"nodes/source.md"};function h(c,s,k,u,g,E){const e=n("NodeDemo");return o(),r("div",null,[s[0]||(s[0]=i("h1",{id:"nodo-source",tabindex:"-1"},[a("Nodo: source "),i("a",{class:"header-anchor",href:"#nodo-source","aria-label":'Permalink to "Nodo: source"'},"​")],-1)),s[1]||(s[1]=i("p",null,[a("Il punto d'ingresso di un flusso: estrae record da un sistema esterno e li emette "),i("strong",null,"in streaming"),a(", uno alla volta, senza mai caricarli tutti in memoria. Ogni grafo ne ha almeno uno.")],-1)),l(e,{kind:"source"}),s[2]||(s[2]=d("",29))])}const F=t(p,[["render",h]]);export{m as __pageData,F as default};
1
+ import{_ as t,C as n,o,c as r,j as i,a,E as l,a5 as d}from"./chunks/framework.qdetmeNX.js";const m=JSON.parse('{"title":"Nodo: source","description":"","frontmatter":{"pageClass":"etl-wide"},"headers":[],"relativePath":"nodes/source.md","filePath":"nodes/source.md"}'),h={name:"nodes/source.md"};function p(c,s,k,u,g,E){const e=n("NodeDemo");return o(),r("div",null,[s[0]||(s[0]=i("h1",{id:"nodo-source",tabindex:"-1"},[a("Nodo: source "),i("a",{class:"header-anchor",href:"#nodo-source","aria-label":'Permalink to "Nodo: source"'},"​")],-1)),s[1]||(s[1]=i("p",null,[a("Il punto d'ingresso di un flusso: estrae record da un sistema esterno e li emette "),i("strong",null,"in streaming"),a(", uno alla volta, senza mai caricarli tutti in memoria. Ogni grafo ne ha almeno uno.")],-1)),l(e,{kind:"source"}),s[2]||(s[2]=d("",29))])}const F=t(h,[["render",p]]);export{m as __pageData,F as default};
@@ -1,4 +1,4 @@
1
- import{_ as i,o as a,c as s,a5 as o}from"./chunks/framework.qdetmeNX.js";const k=JSON.parse('{"title":"Runbook: aggiornare un deploy PM2 di un repo cliente","description":"","frontmatter":{},"headers":[],"relativePath":"runbooks/aggiornamento-pm2.md","filePath":"runbooks/aggiornamento-pm2.md"}'),n={name:"runbooks/aggiornamento-pm2.md"};function l(t,e,r,d,c,p){return a(),s("div",null,[...e[0]||(e[0]=[o(`<h1 id="runbook-aggiornare-un-deploy-pm2-di-un-repo-cliente" tabindex="-1">Runbook: aggiornare un deploy PM2 di un repo cliente <a class="header-anchor" href="#runbook-aggiornare-un-deploy-pm2-di-un-repo-cliente" aria-label="Permalink to &quot;Runbook: aggiornare un deploy PM2 di un repo cliente&quot;">​</a></h1><blockquote><p>Portare a un nuovo commit di <code>main</code> un deploy che gira sotto PM2 dai sorgenti del repo cliente: <code>ecosystem.config.cjs</code> di una riga, <code>etl serve</code> dalla radice del repo, nessuna build. È una delle due confezioni dell&#39;artefatto, il repo cliente a un commit; l&#39;altra, l&#39;immagine container, sta in <a href="./deployment#immagine-del-repo-cliente">Deploy</a>.</p></blockquote><h2 id="sintesi" tabindex="-1">Sintesi <a class="header-anchor" href="#sintesi" aria-label="Permalink to &quot;Sintesi&quot;">​</a></h2><ul><li><strong>Cosa fa:</strong> ferma l&#39;app PM2, porta il repo al nuovo commit di <code>main</code>, installa le dipendenze dal lockfile (che fissa anche la versione del core), ricostruisce la documentazione del cliente, verifica l&#39;ambiente con <code>etl env check</code>, riavvia e controlla che la prima run registri versione di pipeline, release, core e cliente.</li><li><strong>Owner:</strong> il team che mantiene il repo cliente.</li><li><strong>Quando:</strong> dopo il merge su <code>main</code> di ciò che il deploy deve ricevere, in una finestra senza run in corso (§ 1).</li><li><strong>Durata:</strong> pochi minuti di fermo. Nel frattempo i processi restano <code>pending</code> e il worker li rivendica al riavvio: un worker fermo non perde lavoro (<a href="./etl-worker">worker</a>).</li><li><strong>Criticità:</strong> media. Un riavvio a run in corso la interrompe, e la run <strong>non</strong> torna in coda da sola (<a href="./etl-worker#arresto-e-deploy">worker § Arresto e deploy</a>).</li></ul><p>L&#39;app PM2 è una sola, e la configurazione la porta il pacchetto del core: il repo ha <code>ecosystem.config.cjs</code>, un file gestito di una riga che chiama <code>ecosystem()</code> di <code>@noeva/etl-core/pm2</code>. La UI è l&#39;app desktop, che si collega a <code>etl serve</code>.</p><table tabindex="0"><thead><tr><th>App</th><th>Cosa gira</th><th>Porta</th><th>Log in <code>logs/</code></th></tr></thead><tbody><tr><td><code>noeva-etl</code></td><td><code>etl serve</code>: server dei grafi, worker e <code>/guida/</code></td><td><code>9010</code></td><td><code>noeva-etl-out.log</code>, <code>noeva-etl-error.log</code></td></tr></tbody></table><p>La configurazione arriva dal <code>.env</code> alla radice del repo, che la CLI carica da sola prima di ogni comando: <code>etl serve</code> sotto PM2 ed <code>etl env check</code> lanciato dal terminale vedono lo stesso ambiente. Sotto PM2 la porta di default è <code>9010</code> (<a href="./../conventions/variabili-del-core">Variabili d&#39;ambiente del core</a>). I comandi qui sotto valgono in PowerShell e in Git Bash; in Windows PowerShell 5 <code>curl</code> è un alias di <code>Invoke-WebRequest</code>, quindi si scrive <code>curl.exe</code>.</p><h2 id="_0-prima-installazione" tabindex="-1">0. Prima installazione <a class="header-anchor" href="#_0-prima-installazione" aria-label="Permalink to &quot;0. Prima installazione&quot;">​</a></h2><p>Una volta sola, sul server, con l&#39;utente di servizio che farà girare PM2:</p><ol><li><p><strong>Il repo e le dipendenze</strong>, con Node 20 o successivo e pnpm (la versione la dice <code>packageManager</code> nel <code>package.json</code>):</p><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;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> clone</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">url</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> del</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> repo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> client</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> &amp;&amp; </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">rep</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">o</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span>
1
+ import{_ as i,o as a,c as s,a5 as o}from"./chunks/framework.qdetmeNX.js";const k=JSON.parse('{"title":"Runbook: aggiornare un deploy PM2 di un repo cliente","description":"","frontmatter":{},"headers":[],"relativePath":"runbooks/aggiornamento-pm2.md","filePath":"runbooks/aggiornamento-pm2.md"}'),n={name:"runbooks/aggiornamento-pm2.md"};function l(t,e,r,d,c,p){return a(),s("div",null,[...e[0]||(e[0]=[o(`<h1 id="runbook-aggiornare-un-deploy-pm2-di-un-repo-cliente" tabindex="-1">Runbook: aggiornare un deploy PM2 di un repo cliente <a class="header-anchor" href="#runbook-aggiornare-un-deploy-pm2-di-un-repo-cliente" aria-label="Permalink to &quot;Runbook: aggiornare un deploy PM2 di un repo cliente&quot;">​</a></h1><blockquote><p>Portare a un nuovo commit di <code>main</code> un deploy che gira sotto PM2 dai sorgenti del repo cliente: <code>ecosystem.config.cjs</code> di una riga, <code>etl serve</code> dalla radice del repo, nessuna build. È una delle due confezioni dell&#39;artefatto, il repo cliente a un commit; l&#39;altra, l&#39;immagine container, sta in <a href="./deployment#immagine-del-repo-cliente">Deploy</a>.</p></blockquote><h2 id="sintesi" tabindex="-1">Sintesi <a class="header-anchor" href="#sintesi" aria-label="Permalink to &quot;Sintesi&quot;">​</a></h2><ul><li><strong>Cosa fa:</strong> ferma l&#39;app PM2, porta il repo al nuovo commit di <code>main</code>, installa le dipendenze dal lockfile (che fissa anche la versione del core), ricostruisce la documentazione del cliente, verifica l&#39;ambiente con <code>etl env check</code>, riavvia e controlla che la prima run registri versione di pipeline, release, core e cliente.</li><li><strong>Owner:</strong> il team che mantiene il repo cliente.</li><li><strong>Quando:</strong> dopo il merge su <code>main</code> di ciò che il deploy deve ricevere, in una finestra senza run in corso (§ 1).</li><li><strong>Durata:</strong> pochi minuti di fermo. Nel frattempo i processi restano <code>pending</code> e il worker li rivendica al riavvio: un worker fermo non perde lavoro (<a href="./etl-worker">worker</a>).</li><li><strong>Criticità:</strong> media. Un riavvio a run in corso la interrompe, e la run <strong>non</strong> torna in coda da sola (<a href="./etl-worker#arresto-e-deploy">worker § Arresto e deploy</a>).</li></ul><p>L&#39;app PM2 è una sola, e la configurazione la porta il pacchetto del core: il repo ha <code>ecosystem.config.cjs</code>, un file gestito di una riga che chiama <code>ecosystem()</code> di <code>@noeva/etl-core/pm2</code>. La UI è l&#39;app desktop, che si collega a <code>etl serve</code>.</p><table tabindex="0"><thead><tr><th>App</th><th>Cosa gira</th><th>Porta</th><th>Log in <code>logs/</code></th></tr></thead><tbody><tr><td><code>noeva-etl</code></td><td><code>etl serve</code>: server dei grafi, worker e <code>/guida/</code></td><td><code>9010</code></td><td><code>noeva-etl-out.log</code>, <code>noeva-etl-error.log</code></td></tr></tbody></table><p>La configurazione arriva dal <code>.env</code> alla radice del repo, che la CLI carica da sola prima di ogni comando: <code>etl serve</code> sotto PM2 ed <code>etl env check</code> lanciato dal terminale vedono lo stesso ambiente. Sotto PM2 la porta di default è <code>9010</code> (<a href="./../conventions/variabili-del-core">Variabili d&#39;ambiente del core</a>). I comandi qui sotto valgono in PowerShell e in Git Bash; in Windows PowerShell 5 <code>curl</code> è un alias di <code>Invoke-WebRequest</code>, quindi si scrive <code>curl.exe</code>.</p><h2 id="_0-prima-installazione" tabindex="-1">0. Prima installazione <a class="header-anchor" href="#_0-prima-installazione" aria-label="Permalink to &quot;0. Prima installazione&quot;">​</a></h2><p>Una volta sola, sul server, con l&#39;utente di servizio che farà girare PM2:</p><ol><li><p><strong>Il repo e le dipendenze</strong>, con Node 26 o successivo e pnpm (la versione la dice <code>packageManager</code> nel <code>package.json</code>):</p><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;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> clone</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">url</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> del</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> repo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> client</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> &amp;&amp; </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">rep</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">o</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span>
2
2
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> checkout</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> main</span></span>
3
3
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> install</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --frozen-lockfile</span></span></code></pre></div></li><li><p><strong>Il <code>.env</code></strong>, alla radice del repo, partendo dal <code>.env.example</code>: le istanze di connettore, la configurazione delle pipeline e le variabili obbligatorie del core (<a href="./../conventions/variabili-del-core">Variabili d&#39;ambiente del core</a>). Poi <code>pnpm exec etl env check</code> finché non dice <code>Nessuna variabile obbligatoria mancante.</code> (§ 4).</p></li><li><p><strong>La documentazione del cliente</strong>, che <code>etl serve</code> mostra su <code>/guida/</code>: <code>pnpm exec etl docs build</code>.</p></li><li><p><strong>L&#39;avvio</strong>: <code>pm2 start ecosystem.config.cjs</code>, le verifiche del § 5, poi <code>pm2 save</code> e l&#39;avvio al boot del sistema (<code>pm2 startup</code> su Linux, un servizio su Windows).</p></li></ol><h2 id="_1-scegliere-il-momento" tabindex="-1">1. Scegliere il momento <a class="header-anchor" href="#_1-scegliere-il-momento" aria-label="Permalink to &quot;1. Scegliere il momento&quot;">​</a></h2><p>L&#39;arresto del worker <strong>annulla</strong> la run in corso invece di aspettarla, e la chiude <code>failed</code> con <code>Run interrotta dall&#39;arresto del worker:</code> in <code>error_message</code>. Rilanciarla è una decisione di chi opera, perché può aver già prodotto effetti esterni (<a href="./etl-worker#arresto-e-deploy">worker § Arresto e deploy</a>).</p><p>Sotto PM2 l&#39;arresto è cooperativo anche su Windows, dove i segnali non esistono: <code>ecosystem()</code> dichiara <code>shutdown_with_message: true</code>, e PM2 manda al processo il messaggio <code>shutdown</code>, che la CLI ascolta. Se la run non si chiude entro <code>kill_timeout</code> (10 s), PM2 uccide il processo, e la riga resta <code>running</code> e si recupera a mano (<a href="./etl-worker#run-fallita-a-meta-pipeline-lanciata-poi-crash-del-processo-worker">worker § Run fallita a metà</a>).</p><ol><li><p><strong>Guarda la cadenza.</strong> Il job schedulato di ogni pipeline decide quando parte la prossima run: il momento giusto è subito dopo la fine di una run.</p></li><li><p><strong>Verifica che nessun processo sia <code>running</code></strong> per i workspace del deploy:</p><div class="language-sql vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sql</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">SELECT</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> id, </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">function</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">status</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, updated_at</span></span>
4
4
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">FROM</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> processes</span></span>
@@ -2,7 +2,7 @@ import{_ as e,o as s,c as a,a5 as n}from"./chunks/framework.qdetmeNX.js";const c
2
2
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pipelin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # esegue una pipeline</span></span>
3
3
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> serve</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # default dell&#39;immagine: grafi via HTTP + worker</span></span>
4
4
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> worker</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # solo i worker</span></span>
5
- <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deploy-ecr</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">client</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # l&#39;immagine di un cliente su ECR + ECS (sotto)</span></span></code></pre></div><p>Prima di ogni comando la CLI carica da sola il <code>.env</code> alla radice del repo, se c&#39;è, e le variabili già nel processo vincono: <code>etl run</code> da un terminale vede lo stesso ambiente di <code>etl serve</code> sotto PM2. Nell&#39;immagine il <code>.env</code> non c&#39;è (lo esclude il contesto della build), e l&#39;ambiente arriva da <code>docker run --env-file</code> o dall&#39;orchestratore.</p><h2 id="immagine-del-repo-cliente" tabindex="-1">Immagine del repo cliente <a class="header-anchor" href="#immagine-del-repo-cliente" aria-label="Permalink to &quot;Immagine del repo cliente&quot;">​</a></h2><p>Il Dockerfile non sta nel repo cliente: lo porta il pacchetto del core, <code>@noeva/etl-core/deploy/Dockerfile</code>, con il suo <code>Dockerfile.dockerignore</code> accanto, e arriva aggiornato con il bump. L&#39;immagine parte da <code>node:20-slim</code> e installa il repo con <code>pnpm install --prod --frozen-lockfile</code>: il core arriva dal lockfile come ogni altra dipendenza, e non c&#39;è un&#39;immagine base del core. Non c&#39;è build del codice, che gira dai sorgenti con <code>tsx</code>; si costruisce invece la documentazione del cliente (<code>etl docs build</code>), che <code>etl serve</code> mostra su <code>/guida/</code>, mentre la guida del core su <code>/guida/core/</code> è già costruita nel pacchetto installato. <code>ENTRYPOINT</code> è <code>etl</code> e <code>CMD</code> è <code>serve</code>, quindi <code>… run &lt;pipeline&gt;</code> lancia una run sola.</p><p><strong>La costruisce <code>image.yml</code></strong>, il file gestito che <code>etl init</code> scrive nel repo cliente, lanciato a mano (Actions → Immagine → Run workflow) o spingendo un tag <code>v*</code>, mai a ogni push:</p><ul><li>pubblica su <code>ghcr.io/&lt;owner&gt;/noeva-etl-&lt;slug&gt;</code>, il GHCR dell&#39;owner del repo, con <code>GITHUB_TOKEN</code>, che dopo un transfer segue il repo;</li><li><strong>il tag è lo SHA del commit</strong>, sempre, più un tag facoltativo: quello dato a mano o il tag git spinto. Niente <code>latest</code> né timestamp: il workflow rifiuta <code>latest</code>. Il deploy cita lo SHA, e il rollback del deploy è «torna allo SHA precedente»;</li><li>il core si installa da npmjs <strong>senza credenziali</strong> (ADR-0105): nessun segreto entra nella build;</li><li><code>ETL_RELEASE</code> arriva come build arg, <code>git:&lt;sha a 12 caratteri&gt;</code>, ed è la release che il report di ogni run registra, accanto a <code>core</code> e <code>client</code>.</li></ul><p><strong>In locale</strong>, dalla radice del repo cliente e dopo <code>pnpm install</code> (il Dockerfile sta in <code>node_modules</code>):</p><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;">docker</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
5
+ <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deploy-ecr</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">client</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # l&#39;immagine di un cliente su ECR + ECS (sotto)</span></span></code></pre></div><p>Prima di ogni comando la CLI carica da sola il <code>.env</code> alla radice del repo, se c&#39;è, e le variabili già nel processo vincono: <code>etl run</code> da un terminale vede lo stesso ambiente di <code>etl serve</code> sotto PM2. Nell&#39;immagine il <code>.env</code> non c&#39;è (lo esclude il contesto della build), e l&#39;ambiente arriva da <code>docker run --env-file</code> o dall&#39;orchestratore.</p><h2 id="immagine-del-repo-cliente" tabindex="-1">Immagine del repo cliente <a class="header-anchor" href="#immagine-del-repo-cliente" aria-label="Permalink to &quot;Immagine del repo cliente&quot;">​</a></h2><p>Il Dockerfile non sta nel repo cliente: lo porta il pacchetto del core, <code>@noeva/etl-core/deploy/Dockerfile</code>, con il suo <code>Dockerfile.dockerignore</code> accanto, e arriva aggiornato con il bump. L&#39;immagine parte da <code>node:26-slim</code> e installa il repo con <code>pnpm install --prod --frozen-lockfile</code>: il core arriva dal lockfile come ogni altra dipendenza, e non c&#39;è un&#39;immagine base del core. Non c&#39;è build del codice, che gira dai sorgenti con <code>tsx</code>; si costruisce invece la documentazione del cliente (<code>etl docs build</code>), che <code>etl serve</code> mostra su <code>/guida/</code>, mentre la guida del core su <code>/guida/core/</code> è già costruita nel pacchetto installato. <code>ENTRYPOINT</code> è <code>etl</code> e <code>CMD</code> è <code>serve</code>, quindi <code>… run &lt;pipeline&gt;</code> lancia una run sola.</p><p><strong>La costruisce <code>image.yml</code></strong>, il file gestito che <code>etl init</code> scrive nel repo cliente, lanciato a mano (Actions → Immagine → Run workflow) o spingendo un tag <code>v*</code>, mai a ogni push:</p><ul><li>pubblica su <code>ghcr.io/&lt;owner&gt;/noeva-etl-&lt;slug&gt;</code>, il GHCR dell&#39;owner del repo, con <code>GITHUB_TOKEN</code>, che dopo un transfer segue il repo;</li><li><strong>il tag è lo SHA del commit</strong>, sempre, più un tag facoltativo: quello dato a mano o il tag git spinto. Niente <code>latest</code> né timestamp: il workflow rifiuta <code>latest</code>. Il deploy cita lo SHA, e il rollback del deploy è «torna allo SHA precedente»;</li><li>il core si installa da npmjs <strong>senza credenziali</strong> (ADR-0105): nessun segreto entra nella build;</li><li><code>ETL_RELEASE</code> arriva come build arg, <code>git:&lt;sha a 12 caratteri&gt;</code>, ed è la release che il report di ogni run registra, accanto a <code>core</code> e <code>client</code>.</li></ul><p><strong>In locale</strong>, dalla radice del repo cliente e dopo <code>pnpm install</code> (il Dockerfile sta in <code>node_modules</code>):</p><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;">docker</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
6
6
  <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -f</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> node_modules/@noeva/etl-core/deploy/Dockerfile</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
7
7
  <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --build-arg</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ETL_RELEASE=git:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> rev-parse</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --short=12</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> HEAD</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\</span></span>
8
8
  <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -t</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> noeva-etl-</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</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;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> rev-parse</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> HEAD</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span></span>