@noeva/analytics-core 0.1.0 → 0.3.1

package/modello/repository/gitignore

@@ -3,9 +3,10 @@
 .env.local
 .dev.vars
 
-# Il pacchetto e il catalogo compilato si rigenerano.
+# Il pacchetto, il catalogo compilato e le cartelle Windows (rilascio-windows.yml) si rigenerano.
 node_modules/
 target/
+dist/
 
 # Il motore wren-core-wasm (68 MB): in produzione arriva dal contenitore sotto /vendor/.
 apps/vendor/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noeva/analytics-core",
-  "version": "0.1.0",
+  "version": "0.3.1",
   "description": "Gli strumenti di un progetto NOEVA Analytics nel suo repository: moduli di pagina, snapshot, verifica dello standard e kit dell'agente (ADR 0005).",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "cli.js",
     "core.js",
+    "pubblica.js",
     "kit/",
     "modello/",
     "contenuto/",

package/pubblica.js

@@ -0,0 +1,211 @@
+// `analytics pubblica`: la apps/ del progetto sul contenitore, in R2 (ADR 0005, punto 3).
+//
+// Si pubblica il commit, non il disco: i file di apps/ tracciati in HEAD, meno
+// quelli che apps/.assetsignore esclude (lo snapshot, che ha la sua strada, il
+// motore, i file di lavoro). Cosi' quello che va online e' quello che `analytics
+// ci` ha verificato, in CI come sul Mac, e un file lasciato fuori da git non
+// parte per sbaglio.
+//
+// Il contenitore accetta una versione solo con un biglietto di tipo `pagine` per
+// quel progetto e quella versione, con il workspace che possiede il progetto:
+// firmato da chi ha il segreto del contenitore, o rilasciato dall'API NOEVA alla
+// chiave di un membro del workspace (chiediBiglietto, sotto).
+//
+// Il controllo dei percorsi e' lo stesso di lib/analytics/pagine-r2.js, che
+// rifiuterebbe comunque: qui si ferma prima di caricare mezza versione. Una
+// prova del monorepo li confronta.
+
+import { execFileSync } from 'node:child_process';
+import { createHmac } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ErroreConfig } from './core.js';
+
+const SEGMENTO = /^[A-Za-z0-9_@][A-Za-z0-9_.@-]{0,99}$/;
+const PROFONDITA = 8;
+const ESTENSIONI = new Set([
+  'html', 'js', 'mjs', 'css', 'json', 'md', 'txt', 'csv', 'svg', 'png', 'jpg', 'jpeg', 'webp', 'gif', 'ico',
+  'pdf', 'woff', 'woff2', 'parquet', 'wasm',
+]);
+const IN_PARALLELO = 6;
+const DURATA_BIGLIETTO_MS = 15 * 60 * 1000;
+const API_NOEVA = 'https://api.noeva.ai';
+
+/** Un percorso di file della apps/ che il contenitore accetta (pagine-r2.js). */
+export function percorsoAmmesso(file) {
+  if (typeof file !== 'string' || !file) return false;
+  const segmenti = file.split('/');
+  if (segmenti.length > PROFONDITA || !segmenti.every((s) => SEGMENTO.test(s))) return false;
+  const nome = segmenti.at(-1);
+  return ESTENSIONI.has(nome.slice(nome.lastIndexOf('.') + 1).toLowerCase());
+}
+
+// Le regole di un .gitignore semplice, come le legge assembla.py: `vendor/**`,
+// `dati/*.parquet`, `dati/chat/**`. Un `*` non attraversa le cartelle.
+export function regoleIgnorate(testo) {
+  return testo.split('\n').map((r) => r.trim()).filter((r) => r && !r.startsWith('#'));
+}
+
+const comeRegex = (glob) => new RegExp(`^${glob.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*\*/g, '\0').replace(/\*/g, '[^/]*').replace(/\?/g, '[^/]').replace(/\0/g, '.*')}$`);
+
+export function ignorato(rel, regole) {
+  return regole.some((r) => (r.endsWith('/**') ? rel.startsWith(r.slice(0, -2)) : comeRegex(r).test(rel)));
+}
+
+const git = (radice, args, opzioni = {}) => execFileSync('git', args, { cwd: radice, maxBuffer: 256 * 1024 * 1024, ...opzioni });
+
+/**
+ * I file da pubblicare: {file, byte, oggetto} per ogni file di apps/ in HEAD che
+ * .assetsignore (di HEAD) non esclude. `scartati` sono quelli con un percorso o
+ * un tipo che il contenitore rifiuterebbe.
+ */
+export function filePubblicabili(radice) {
+  let righe;
+  try {
+    righe = git(radice, ['ls-tree', '-r', '-l', '-z', 'HEAD', '--', 'apps/'], { encoding: 'utf8' }).split('\0').filter(Boolean);
+  } catch {
+    throw new ErroreConfig('git ls-tree HEAD non risponde: serve un repository git con almeno un commit');
+  }
+  let regole = [];
+  try {
+    regole = regoleIgnorate(git(radice, ['show', 'HEAD:apps/.assetsignore'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }));
+  } catch { /* nessun .assetsignore: si pubblica tutto, e analytics ci lo segnala */ }
+
+  const file = [];
+  const scartati = [];
+  for (const riga of righe) {
+    // <modo> <tipo> <oggetto> <byte>\t<percorso>
+    const [testa, percorso] = riga.split('\t');
+    const [, tipo, oggetto, byte] = testa.trim().split(/\s+/);
+    if (tipo !== 'blob') continue;
+    const rel = percorso.slice('apps/'.length);
+    const nome = rel.split('/').at(-1);
+    if (nome === '.assetsignore' || nome === '.DS_Store' || nome === '.gitkeep' || ignorato(rel, regole)) continue;
+    if (!percorsoAmmesso(rel)) { scartati.push(rel); continue; }
+    file.push({ file: rel, byte: Number(byte), oggetto });
+  }
+  return { file, scartati };
+}
+
+/** La versione: data e ora UTC del commit e il suo sha corto, unica e leggibile. */
+export function versioneDi(radice) {
+  const [sha, quando] = git(radice, ['log', '-1', '--format=%h%x09%cI'], { encoding: 'utf8' }).trim().split('\t');
+  const t = new Date(quando).toISOString().replace(/[-:]/g, '').replace('T', '-').slice(0, 15);
+  return `${t}-${sha}`;
+}
+
+/** Lo stesso formato di lib/cancello/sessione.js: base64url(JSON).base64url(HMAC-SHA256). */
+export function firmaBiglietto(payload, segreto) {
+  const corpo = Buffer.from(JSON.stringify(payload)).toString('base64url');
+  const mac = createHmac('sha256', segreto).update(corpo).digest('base64url');
+  return `${corpo}.${mac}`;
+}
+
+// Il valore della variabile o, se manca, quello del file nella home (permessi
+// 600, mai nel repository): come dal_file di lib/snapshot/pubblica.py.
+function dalFile(env, variabile, nome, casa) {
+  if (env[variabile]) return env[variabile].trim();
+  const f = join(casa, nome);
+  return existsSync(f) ? readFileSync(f, 'utf8').trim() || null : null;
+}
+
+/**
+ * Il biglietto per scrivere `tipo` (pagine) di questo progetto e versione. Due
+ * strade, come per i dati (lib/snapshot/pubblica.py): firmato qui col segreto del
+ * contenitore, sul Mac di chi lo amministra; o rilasciato dall'API NOEVA a chi ha
+ * la chiave di un membro del workspace, ed e' la strada della CI del repository.
+ */
+export async function chiediBiglietto({ progetto, versione, workspace, tipo, env, casa, fetchImpl }) {
+  const da = env.GITHUB_ACTIONS ? `ci ${env.GITHUB_REPOSITORY ?? ''}`.trim() : `analytics ${tipo}`;
+  const segreto = dalFile(env, 'SEGRETO_DATI', '.segreto-dati', casa);
+  if (segreto) {
+    return firmaBiglietto({ tipo, prog: progetto, ver: versione, ws: workspace, da, exp: Date.now() + DURATA_BIGLIETTO_MS }, segreto);
+  }
+  const chiave = dalFile(env, 'NOEVA_API_KEY', '.noeva-api-key', casa);
+  if (!chiave) {
+    throw new ErroreConfig('nessun biglietto: serve la chiave API NOEVA di un membro del workspace (NOEVA_API_KEY o ' +
+      '~/.noeva-api-key; in CI il secret del repository), o il segreto del contenitore (SEGRETO_DATI o ~/.segreto-dati)');
+  }
+  const api = (env.NOEVA_API || API_NOEVA).replace(/\/+$/, '');
+  const r = await fetchImpl(`${api}/api/analytics/biglietto-dati`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${chiave}`, 'x-noeva-workspace': workspace,
+      'Content-Type': 'application/json', 'User-Agent': 'noeva-analytics-core',
+    },
+    body: JSON.stringify({ progetto, versione, da, tipo }),
+  });
+  let corpo = {};
+  try { corpo = await r.json(); } catch { /* il messaggio d'errore sotto basta */ }
+  if (!r.ok || !corpo?.payload?.biglietto) {
+    throw new ErroreConfig(`l'API NOEVA non rilascia il biglietto (${r.status}): ${corpo?.message ?? corpo?.error ?? 'risposta inattesa'}`);
+  }
+  return corpo.payload.biglietto;
+}
+
+async function chiama(fetchImpl, metodo, url, biglietto, corpo, tipo) {
+  // Niente redirect: un contenitore senza la rotta manda al login con un 302, e
+  // seguirlo darebbe un 200 (la pagina di login) scambiato per una pubblicazione.
+  const r = await fetchImpl(url, {
+    method: metodo,
+    body: corpo,
+    redirect: 'manual',
+    headers: {
+      Authorization: `Bearer ${biglietto}`,
+      'User-Agent': 'noeva-analytics-core',
+      ...(corpo !== undefined ? { 'Content-Length': String(corpo.length), 'Content-Type': tipo } : {}),
+    },
+  });
+  const testo = await r.text();
+  let risposta;
+  try { risposta = JSON.parse(testo); } catch { risposta = { errore: testo.slice(0, 200) }; }
+  if (!r.ok || risposta.ok !== true) {
+    const dettaglio = risposta.mancanti ? ` (${risposta.mancanti.join(', ')})` : '';
+    const perche = r.status >= 300 && r.status < 400
+      ? `rimanda a ${r.headers.get('Location') ?? '?'}: il contenitore non ha questa rotta (va deployato?)`
+      : (risposta.errore ?? '');
+    throw new ErroreConfig(`${metodo} ${new URL(url).pathname}: ${r.status} ${perche}${dettaglio}`);
+  }
+  return risposta;
+}
+
+/**
+ * Pubblica la apps/ di HEAD: carica ogni file e sposta il puntatore. `prova`
+ * elenca e basta. Restituisce {versione, file, byte, scartati}.
+ */
+export async function pubblica(radice, config, {
+  url, workspace = config.workspace, env = process.env, fetchImpl = fetch, prova = false, stampa = () => {}, casa = homedir(),
+} = {}) {
+  const { file, scartati } = filePubblicabili(radice);
+  if (scartati.length) {
+    throw new ErroreConfig(`file che il contenitore non accetta (percorso o tipo): ${scartati.join(', ')}. ` +
+      'Si escludono in apps/.assetsignore o si rinominano.');
+  }
+  if (!file.some((f) => f.file === 'index.html')) throw new ErroreConfig('apps/index.html manca in HEAD');
+  const versione = versioneDi(radice);
+  const byte = file.reduce((s, f) => s + f.byte, 0);
+  const esito = { versione, file: file.length, byte, scartati };
+  if (prova) return esito;
+
+  if (!url) throw new ErroreConfig('serve --url: l\'indirizzo del contenitore (in prova http://localhost:8789)');
+  if (!workspace) throw new ErroreConfig('serve il workspace NOEVA che possiede il progetto: `workspace` in analytics.json, o --workspace');
+  const biglietto = await chiediBiglietto({
+    progetto: config.progetto, versione, workspace, tipo: 'pagine', env, casa, fetchImpl,
+  });
+
+  const base = `${url.replace(/\/+$/, '')}/_pagine/${config.progetto}/${versione}`;
+  stampa(`▸ ${config.progetto}: versione ${versione}, ${file.length} file, ${Math.round(byte / 1024)} kB -> ${url}`);
+  const coda = [...file];
+  const lavora = async () => {
+    for (let f = coda.shift(); f; f = coda.shift()) {
+      const corpo = git(radice, ['cat-file', 'blob', f.oggetto]);
+      const percorso = f.file.split('/').map(encodeURIComponent).join('/');
+      await chiama(fetchImpl, 'PUT', `${base}/${percorso}`, biglietto, corpo, 'application/octet-stream');
+    }
+  };
+  await Promise.all(Array.from({ length: IN_PARALLELO }, lavora));
+  const manifesto = Buffer.from(JSON.stringify({ file: file.map(({ file: f, byte: b }) => ({ file: f, byte: b })) }));
+  await chiama(fetchImpl, 'POST', `${base}/pubblica`, biglietto, manifesto, 'application/json');
+  return esito;
+}