@alucard_24/pi-codeindex 0.0.0-stage → 1.1.0

package/src/service-protocol.js

@@ -0,0 +1,122 @@
+// IPC locale autenticato. Nessun provider o modello viene importato qui.
+import fs from 'node:fs/promises';
+import net from 'node:net';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+
+export const PROTOCOL = 1;
+export const HOST = '127.0.0.1';
+export const MAX_FRAME = 8 * 1024 * 1024;
+export const MAX_TEXT_BYTES = 2 * 1024 * 1024;
+export const MAX_TEXTS = 128;
+
+export function serviceError(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+
+export function serviceAddress(config) {
+  const directory = path.resolve(config.serviceDir);
+  const identity = process.platform === 'win32' ? directory.toLowerCase() : directory;
+  const port = config.servicePort || 49152 + createHash('sha256').update(identity).digest().readUInt16BE(0) % 16384;
+  return { directory, host: HOST, port, file: path.join(directory, 'service.json') };
+}
+
+function checkPrivate(stat, target, directory = false) {
+  if (stat.isSymbolicLink() || (directory ? !stat.isDirectory() : !stat.isFile())) {
+    throw serviceError('UNSAFE_SERVICE_PATH', `percorso del servizio non sicuro: ${target}`);
+  }
+  if (process.platform !== 'win32' && (stat.uid !== process.getuid() || (stat.mode & 0o077))) {
+    throw serviceError('UNSAFE_SERVICE_PATH', `il servizio richiede proprietà utente e permessi privati (0700 directory, 0600 file): ${target}`);
+  }
+}
+
+export async function prepareServiceDirectory(address) {
+  await fs.mkdir(address.directory, { recursive: true, mode: 0o700 });
+  checkPrivate(await fs.lstat(address.directory), address.directory, true);
+}
+
+// Status è read-only: non crea directory/file e non avvia il servizio.
+export async function readServiceRecord(address) {
+  try {
+    checkPrivate(await fs.lstat(address.directory), address.directory, true);
+    const stat = await fs.lstat(address.file);
+    checkPrivate(stat, address.file);
+    if (stat.size > 4096) throw serviceError('BAD_SERVICE_RECORD', 'record del servizio troppo grande');
+    const record = JSON.parse(await fs.readFile(address.file, 'utf8'));
+    if (record.port !== address.port || !Number.isInteger(record.pid) || record.pid < 1 ||
+        typeof record.token !== 'string' || !/^[a-f0-9]{64}$/.test(record.token)) {
+      throw serviceError('BAD_SERVICE_RECORD', 'record del servizio locale non valido');
+    }
+    if (record.protocol !== PROTOCOL) throw serviceError('PROTOCOL_MISMATCH', 'servizio locale di versione incompatibile: arrestalo prima di riavviare pi');
+    return record;
+  } catch (e) {
+    if (e.code === 'ENOENT') return null;
+    throw e;
+  }
+}
+
+export async function writeServiceRecord(address, record) {
+  const tmp = `${address.file}.${randomUUID()}.tmp`;
+  try {
+    await fs.writeFile(tmp, JSON.stringify(record) + '\n', { flag: 'wx', mode: 0o600 });
+    await fs.rename(tmp, address.file);
+  } finally { await fs.rm(tmp, { force: true }); }
+}
+
+export function readFrame(socket, { timeoutMs = 30_000 } = {}) {
+  return new Promise((resolve, reject) => {
+    let size = 0;
+    const chunks = [];
+    const finish = (error, value) => {
+      clearTimeout(timer);
+      socket.off('data', data); socket.off('end', end); socket.off('close', end); socket.off('error', fail);
+      if (error) reject(error); else resolve(value);
+    };
+    const fail = (e) => finish(e);
+    const end = () => fail(serviceError('SERVICE_DISCONNECTED', 'servizio locale disconnesso; nessun fallback in-process'));
+    const data = (chunk) => {
+      size += chunk.length;
+      if (size > MAX_FRAME) return fail(serviceError('FRAME_TOO_LARGE', 'messaggio del servizio troppo grande'));
+      chunks.push(chunk);
+      const newline = chunk.indexOf(10);
+      if (newline < 0) return;
+      try {
+        const buffer = Buffer.concat(chunks);
+        const at = buffer.indexOf(10);
+        if (buffer.subarray(at + 1).toString().trim()) throw new Error('attesa una sola richiesta per connessione');
+        finish(null, JSON.parse(buffer.subarray(0, at).toString('utf8')));
+      } catch (e) { fail(serviceError('BAD_FRAME', `messaggio del servizio non valido: ${e.message}`)); }
+    };
+    const timer = setTimeout(() => fail(serviceError('SERVICE_TIMEOUT', 'timeout del servizio locale')), timeoutMs);
+    socket.on('data', data); socket.once('end', end); socket.once('close', end); socket.once('error', fail);
+  });
+}
+
+export function writeFrame(socket, value) {
+  const frame = JSON.stringify(value) + '\n';
+  if (Buffer.byteLength(frame) > MAX_FRAME) throw serviceError('FRAME_TOO_LARGE', 'messaggio del servizio troppo grande');
+  socket.write(frame);
+}
+
+export async function rpc(address, record, request, { timeoutMs = 15 * 60_000, connectTimeoutMs = 1000 } = {}) {
+  const socket = net.createConnection({ host: HOST, port: address.port });
+  socket.on('error', () => {});
+  try {
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { socket.destroy(); reject(serviceError('CONNECT_TIMEOUT', 'timeout connessione al servizio locale')); }, connectTimeoutMs);
+      socket.once('connect', () => { clearTimeout(timer); resolve(); });
+      socket.once('error', (e) => { clearTimeout(timer); reject(e); });
+    });
+    const response = readFrame(socket, { timeoutMs });
+    try { writeFrame(socket, { protocol: PROTOCOL, token: record.token, ...request }); }
+    catch (e) { socket.destroy(); await response.catch(() => {}); throw e; }
+    const message = await response;
+    if (!message || message.protocol !== PROTOCOL || typeof message.ok !== 'boolean') throw serviceError('BAD_FRAME', 'risposta del servizio non valida');
+    if (!message.ok) throw Object.assign(serviceError(message.code ?? 'SERVICE_ERROR', message.error ?? 'errore del servizio locale'), { info: message.info });
+    return message;
+  } finally { socket.destroy(); }
+}
+
+export function disconnected(error) {
+  return ['ECONNREFUSED', 'ECONNRESET', 'EPIPE', 'CONNECT_TIMEOUT', 'SERVICE_DISCONNECTED'].includes(error.code);
+}

package/src/service-worker.js

@@ -0,0 +1,3 @@
+// Worker autonomo: non deve mai importare il client embed.js.
+import { runServiceWorker } from './service.js';
+await runServiceWorker();

package/src/service.js

@@ -0,0 +1,172 @@
+// Un listener esclusivo per directory/utente, un modello, una coda seriale.
+import net from 'node:net';
+import fs from 'node:fs/promises';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { PROTOCOL, HOST, prepareServiceDirectory, readServiceRecord, writeServiceRecord, readFrame, writeFrame, serviceAddress, serviceError } from './service-protocol.js';
+import { validateServiceConfig, assertServiceCompatible, validateTexts } from './service-policy.js';
+
+export async function startEmbeddingService({ directory, port, maxQueue = 16, createRuntime = async (config) => {
+  const { createLocalEmbedder } = await import('./local-embed.js');
+  return createLocalEmbedder(config);
+} }) {
+  const address = serviceAddress({ serviceDir: directory, servicePort: port });
+  await prepareServiceDirectory(address);
+  const token = randomBytes(32).toString('hex');
+  const record = { protocol: PROTOCOL, pid: process.pid, port: address.port, token };
+  const sockets = new Set();
+  const startedAt = Date.now();
+  let lastUsedAt = startedAt;
+  let idleMs = 300_000;
+  let timer, runtime = null, activeConfig = null;
+  let pending = 0, initializing = false, stopping = false, shutdownStarted = false, tail = Promise.resolve();
+  let resolveStopped;
+  const stopped = new Promise((resolve) => { resolveStopped = resolve; });
+
+  function info() {
+    return { running: !stopping, stopping, shared: true, pid: process.pid, protocol: PROTOCOL, port: address.port,
+      pending, initializing, startedAt, lastUsedAt, idleMs, rssBytes: process.memoryUsage().rss,
+      ...(runtime?.info() ?? { profile: null, attempts: [], error: null }) };
+  }
+  function reply(socket, value) {
+    if (socket.destroyed) return;
+    try { writeFrame(socket, { protocol: PROTOCOL, ...value }); socket.end(); }
+    catch { socket.destroy(); }
+  }
+  function armIdle() {
+    clearTimeout(timer);
+    if (!stopping && pending === 0) timer = setTimeout(() => { void stop(); }, Math.max(1, idleMs - (Date.now() - lastUsedAt)));
+  }
+  async function stop() {
+    if (shutdownStarted) return stopped;
+    shutdownStarted = true;
+    stopping = true;
+    clearTimeout(timer);
+    // L'inferenza attiva termina; quelle in coda ricevono un errore esplicito.
+    await tail;
+    for (const socket of sockets) socket.destroy();
+    if (runtime) {
+      let timeout;
+      try { await Promise.race([runtime.dispose(), new Promise((resolve) => { timeout = setTimeout(resolve, 3000); })]); }
+      catch { /* l'uscita del processo libera comunque le risorse native */ }
+      finally { clearTimeout(timeout); }
+    }
+    try {
+      const current = await readServiceRecord(address);
+      if (current?.token === token) await fs.rm(address.file, { force: true });
+    } catch { /* non cancellare record sostituiti/non sicuri */ }
+    // Chiudi anche connessioni arrivate durante dispose, prima di rilasciare
+    // la porta: nessun client incompleto deve trattenere il worker nativo.
+    for (const socket of sockets) socket.destroy();
+    await new Promise((resolve) => server.close(resolve));
+    resolveStopped();
+  }
+  async function modelFor(config, expectedProfile) {
+    if (!runtime) {
+      activeConfig = config;
+      idleMs = config.serviceIdleMs;
+      initializing = true;
+      try {
+        runtime = await createRuntime(config);
+        await runtime.getProfile();
+      } catch (e) {
+        // Dopo un'inizializzazione fallita si esce: nessuna risorsa nativa
+        // residua viene riusata per avviare un altro profilo.
+        e.initializationFailed = true;
+        throw e;
+      } finally { initializing = false; }
+    }
+    const profile = await runtime.getProfile();
+    assertServiceCompatible(config, activeConfig, profile, expectedProfile);
+    return { runtime, profile };
+  }
+
+  const server = net.createServer((socket) => {
+    socket.on('error', () => {});
+    sockets.add(socket);
+    socket.once('close', () => sockets.delete(socket));
+    if (sockets.size > maxQueue + 16) { socket.destroy(); return; }
+    void (async () => {
+      let authenticated = false;
+      try {
+        const request = await readFrame(socket, { timeoutMs: 3000 });
+        if (typeof request?.token !== 'string' || !/^[a-f0-9]{64}$/.test(request.token) ||
+            !timingSafeEqual(Buffer.from(request.token), Buffer.from(token))) throw serviceError('UNAUTHORIZED', 'autenticazione del servizio locale fallita');
+        authenticated = true;
+        if (request.protocol !== PROTOCOL) throw serviceError('PROTOCOL_MISMATCH', 'protocollo del servizio incompatibile; arresta il servizio e riavvia pi');
+        if (request.op === 'status') { reply(socket, { ok: true, result: info() }); return; }
+        if (request.op === 'stop') {
+          if (stopping) { reply(socket, { ok: true, result: { stopping: true, pid: process.pid } }); return; }
+          if (pending) throw serviceError('SERVICE_BUSY', `servizio occupato (${pending} richieste): stop rifiutato per non interrompere altre sessioni`);
+          reply(socket, { ok: true, result: { stopping: true, pid: process.pid } });
+          // Blocca subito nuove operazioni, poi lascia uscire la risposta.
+          stopping = true;
+          setImmediate(() => { void stop(); });
+          return;
+        }
+        if (stopping) throw serviceError('SERVICE_STOPPING', 'servizio locale in arresto; riprova tra poco');
+        if (!['profile', 'embed'].includes(request.op)) throw serviceError('BAD_OPERATION', 'operazione del servizio sconosciuta');
+        const config = validateServiceConfig(request.config);
+        const requestedAddress = serviceAddress(config);
+        if (requestedAddress.directory !== address.directory || requestedAddress.port !== address.port) throw serviceError('BAD_CONFIG', 'endpoint client diverso da quello del servizio');
+        if (request.op === 'embed') validateTexts(request.texts, request.normalize);
+        if (pending >= maxQueue) throw serviceError('QUEUE_FULL', `coda del servizio piena (massimo ${maxQueue}); riprova senza avviare altri modelli`);
+        pending++;
+        clearTimeout(timer);
+        const task = tail.then(async () => {
+          try {
+            if (socket.destroyed) return;
+            if (stopping) throw serviceError('SERVICE_STOPPING', 'servizio locale in arresto');
+            const { runtime: model, profile } = await modelFor(config, request.expectedProfile);
+            const result = request.op === 'embed' ? await model.embed(request.texts, { normalize: request.normalize }) : profile;
+            reply(socket, { ok: true, result, info: info() });
+          } catch (e) {
+            reply(socket, { ok: false, code: e.code ?? 'INFERENCE_FAILED', error: String(e.message ?? e).slice(0, 4000), info: info() });
+            if (e.initializationFailed) {
+              stopping = true;
+              setImmediate(() => { void stop(); });
+            }
+          } finally {
+            pending--;
+            lastUsedAt = Date.now();
+            armIdle();
+          }
+        });
+        // La coda non viene avvelenata da richieste fallite/disconnesse.
+        tail = task.catch(() => {});
+      } catch (e) {
+        reply(socket, { ok: false, code: e.code ?? 'BAD_REQUEST', error: String(e.message ?? e).slice(0, 4000), ...(authenticated ? { info: info() } : {}) });
+      }
+    })();
+  });
+  server.on('error', () => {});
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen({ host: HOST, port: address.port, exclusive: true }, () => { server.off('error', reject); resolve(); });
+  });
+  try { await writeServiceRecord(address, record); }
+  catch (e) { server.close(); throw e; }
+  armIdle();
+  return { info, stop, stopped };
+}
+
+// Entry point condiviso dal worker reale e da fixture senza modello.
+export async function runServiceWorker(options = {}) {
+  let service;
+  try {
+    const directory = process.argv[2];
+    const port = Number(process.argv[3]);
+    if (!directory || !Number.isInteger(port) || port < 1024 || port > 65535) throw new Error('argomenti interni del servizio non validi');
+    service = await startEmbeddingService({ ...options, directory, port });
+    process.once('SIGTERM', () => { void service.stop(); });
+    process.once('SIGINT', () => { void service.stop(); });
+    if (process.connected) process.send({ ready: true, pid: process.pid }, () => { if (process.connected) process.disconnect(); });
+    await service.stopped;
+    // Necessario anche se ORT/Dawn trattiene handle dopo dispose: l'OS libera
+    // l'intero processo. Non si scarica/ricarica un modello nello stesso worker.
+    process.exit(0);
+  } catch (e) {
+    const exit = () => process.exit(e.code === 'EADDRINUSE' ? 0 : 1);
+    if (process.connected) process.send({ ready: false, code: e.code, error: e.message }, exit);
+    else exit();
+  }
+}

package/src/store.js

@@ -0,0 +1,142 @@
+// Storage a due file: index.json (metadati + chunk senza testo) e vectors.bin.
+// Niente database, niente dipendenze. Salvataggio atomico (tmp + rename).
+
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { sha1 } from './util.js';
+
+export const STORE_VERSION = 2;
+
+export function cacheRoot() {
+  return path.join(os.homedir(), '.cache', 'pi-codeindex');
+}
+
+export function indexDir(repoRoot) {
+  return path.join(cacheRoot(), sha1(path.resolve(repoRoot)));
+}
+
+export function indexPaths(dir) {
+  return {
+    dir,
+    json: path.join(dir, 'index.json'),
+    bin: path.join(dir, 'vectors.bin'),
+    cache: path.join(dir, 'embed-cache.json'), // ripresa dopo interruzione
+  };
+}
+
+export async function loadIndex(repoRoot) {
+  const { json, bin } = indexPaths(indexDir(repoRoot));
+  try {
+    const raw = await fs.readFile(json, 'utf8');
+    const index = JSON.parse(raw);
+    let vectors = null;
+    try {
+      const buf = await fs.readFile(bin);
+      const expected = index.chunks.length * index.dims;
+      vectors = unpackVectors(buf, index.dims, index.chunks.length);
+      // Due rename non sono una transazione: il digest lega il manifest ai
+      // vettori anche durante scritture concorrenti con profili differenti.
+      if (vectors.length !== expected || !index.vectorsHash ||
+          createHash('sha256').update(buf).digest('hex') !== index.vectorsHash) vectors = null;
+    } catch {
+      vectors = null; // indice senza vettori: si ricostruisce
+    }
+    return { index, vectors };
+  } catch {
+    return { index: null, vectors: null };
+  }
+}
+
+export async function saveIndex(repoRoot, index, vectors) {
+  const paths = indexPaths(indexDir(repoRoot));
+  await fs.mkdir(paths.dir, { recursive: true });
+  const token = randomUUID();
+  const binTmp = `${paths.bin}.${token}.tmp`;
+  const jsonTmp = `${paths.json}.${token}.tmp`;
+  const packed = packVectors(vectors, index.dims);
+  const vectorsHash = createHash('sha256').update(packed).digest('hex');
+  try {
+    await fs.writeFile(binTmp, packed);
+    await fs.writeFile(jsonTmp, JSON.stringify({ ...index, vectorsHash }));
+    await fs.rename(binTmp, paths.bin);
+    await fs.rename(jsonTmp, paths.json);
+  } finally {
+    await Promise.all([fs.rm(binTmp, { force: true }), fs.rm(jsonTmp, { force: true })]);
+  }
+  return paths;
+}
+
+/** righe (Float32Array[] | Float32Array) -> Buffer contiguo little-endian. */
+export function packVectors(vectors, dims) {
+  const rows = vectors instanceof Float32Array ? vectors.length / dims : vectors.length;
+  const out = new Float32Array(rows * dims);
+  if (vectors instanceof Float32Array) {
+    out.set(vectors);
+  } else {
+    for (let i = 0; i < rows; i++) out.set(vectors[i], i * dims);
+  }
+  return Buffer.from(out.buffer, out.byteOffset, out.byteLength);
+}
+
+export function unpackVectors(buf, dims, expectedRows) {
+  if (!buf || buf.length === 0) return new Float32Array(0);
+  const bytes = expectedRows ? Math.min(buf.length, expectedRows * dims * 4) : buf.length;
+  if (buf.byteOffset % 4 === 0) {
+    return new Float32Array(buf.buffer, buf.byteOffset, bytes / 4);
+  }
+  const copy = new Uint8Array(bytes);
+  copy.set(buf.subarray(0, bytes));
+  return new Float32Array(copy.buffer, 0, bytes / 4);
+}
+
+/** Cache di ripresa: identità chunk -> vettore. Sopravvive a un run interrotto. */
+export async function loadEmbedCache(repoRoot) {
+  const { cache } = indexPaths(indexDir(repoRoot));
+  try {
+    const obj = JSON.parse(await fs.readFile(cache, 'utf8'));
+    const out = new Map();
+    for (const [hash, b64] of Object.entries(obj)) {
+      const buf = Buffer.from(b64, 'base64');
+      if (buf.length === 768 * 4) out.set(hash, new Float32Array(buf.buffer, buf.byteOffset, 768));
+    }
+    return out;
+  } catch {
+    return new Map();
+  }
+}
+
+export async function saveEmbedCache(repoRoot, map) {
+  if (map.size === 0) return;
+  const { dir, cache } = indexPaths(indexDir(repoRoot));
+  await fs.mkdir(dir, { recursive: true });
+  const obj = {};
+  for (const [hash, vec] of map) obj[hash] = Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength).toString('base64');
+  const tmp = `${cache}.tmp`;
+  await fs.writeFile(tmp, JSON.stringify(obj));
+  await fs.rename(tmp, cache);
+}
+
+export async function clearEmbedCache(repoRoot) {
+  const { cache } = indexPaths(indexDir(repoRoot));
+  await fs.rm(cache, { force: true });
+}
+
+export async function removeIndex(repoRoot) {
+  const { dir } = indexPaths(indexDir(repoRoot));
+  await fs.rm(dir, { recursive: true, force: true });
+}
+
+export async function indexSize(repoRoot) {
+  const paths = indexPaths(indexDir(repoRoot));
+  let total = 0;
+  for (const p of [paths.json, paths.bin]) {
+    try {
+      total += (await fs.stat(p)).size;
+    } catch {
+      /* file assente */
+    }
+  }
+  return total;
+}

package/src/sync.js

@@ -0,0 +1,110 @@
+// Sincronizzazione: quali file meritano una riconciliazione.
+//
+// Non facciamo re-index per singolo path: `indexRepo` è già incrementale
+// (hash per file → riuso dei vettori) e su un repo da 2.872 file costa ~0,7 s.
+// Quindi la politica è: raccogli i path sporchi, attendi un debounce, riconcilia
+// tutto una volta. Meno codice, nessun indice parziale da mantenere coerente.
+
+import path from 'node:path';
+import { LANG_BY_EXT } from './chunker.js';
+
+/** Directory che il watcher non deve nemmeno guardare (oltre a quelle di git). */
+export const IGNORED_DIRS = new Set([
+  '.git', 'node_modules', '.venv', 'venv', '__pycache__', 'dist', 'build', 'out',
+  'target', 'vendor', '.next', '.nuxt', '.cache', '.openlore', '.pi', 'coverage',
+]);
+
+const extOf = (p) => {
+  const m = /\.[^./]+$/.exec(p);
+  return m ? m[0].toLowerCase() : '';
+};
+
+/**
+ * Path relativo -> normalizzato con '/', o null se fuori scope.
+ * Su rename, includeDirectories accetta anche directory/nomi senza estensione
+ * supportata: un evento sulla directory può rappresentare molti file rimossi.
+ */
+export function watchablePath(rel, root, { includeDirectories = false } = {}) {
+  if (!rel) return null;
+  let p = String(rel).replace(/\\/g, '/');
+  if (path.isAbsolute(p)) {
+    if (!root) return null;
+    const r = path.relative(root, p).replace(/\\/g, '/');
+    if (!r || r.startsWith('..') || path.isAbsolute(r)) return null;
+    p = r;
+  }
+  const segments = path.posix.normalize(p).split('/').filter(Boolean);
+  if (segments.length === 0 || segments[0] === '..') return null;
+  p = segments.join('/');
+  if (segments.some((s) => IGNORED_DIRS.has(s))) return null;
+  if (!includeDirectories && !(extOf(p) in LANG_BY_EXT)) return null;
+  return segments.join('/');
+}
+
+/** Filtra e deduplica una lista di path (watcher, hook dei tool, git status). */
+export function filterDirty(paths, root, options) {
+  const out = new Set();
+  for (const p of paths ?? []) {
+    const w = watchablePath(p, root, options);
+    if (w) out.add(w);
+  }
+  return out;
+}
+
+/**
+ * `git status --porcelain -z`: `XY path\0`, con `R`/`C` seguiti dal path
+ * originale come record successivo. Restituisce entrambi i lati del rename:
+ * un file rinominato va re-embedato (il path fa parte dell'identità).
+ */
+export function parsePorcelainStatus(z) {
+  const parts = String(z ?? '').split('\0');
+  const out = [];
+  for (let i = 0; i < parts.length; i++) {
+    const rec = parts[i];
+    if (!rec || rec.length < 4) continue;
+    const xy = rec.slice(0, 2);
+    out.push(rec.slice(3));
+    if (xy[0] === 'R' || xy[0] === 'C') {
+      const from = parts[++i];
+      if (from) out.push(from);
+    }
+  }
+  return out;
+}
+
+/**
+ * Coda con debounce: gli eventi ravvicinati diventano una sola riconciliazione.
+ * `onFlush` riceve il Set dei path accumulati. Restituisce {add, cancel, pending}.
+ */
+export function createDebouncedQueue(onFlush, {
+  delayMs = 800,
+  setTimeout: setTimer = setTimeout,
+  clearTimeout: clearTimer = clearTimeout,
+} = {}) {
+  let timer = null;
+  let dirty = new Set();
+
+  const flush = () => {
+    timer = null;
+    const batch = dirty;
+    dirty = new Set();
+    if (batch.size > 0) onFlush(batch);
+  };
+
+  return {
+    add(paths) {
+      for (const p of paths ?? []) dirty.add(p);
+      if (dirty.size === 0) return;
+      if (timer) clearTimer(timer);
+      timer = setTimer(flush, delayMs);
+    },
+    cancel() {
+      if (timer) clearTimer(timer);
+      timer = null;
+      dirty = new Set();
+    },
+    get pending() {
+      return dirty.size;
+    },
+  };
+}

package/src/util.js

@@ -0,0 +1,108 @@
+// Utility pure: hash, git, enumerazione file, euristiche su testo/binari.
+
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export function sha1(input) {
+  return createHash('sha1').update(input).digest('hex');
+}
+
+export function short(s, n = 60) {
+  const one = String(s).replace(/\s+/g, ' ').trim();
+  return one.length > n ? `${one.slice(0, n - 1)}…` : one;
+}
+
+export function git(cwd, args) {
+  try {
+    return execFileSync('git', args, {
+      cwd,
+      encoding: 'utf8',
+      maxBuffer: 64 * 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+  } catch {
+    return null;
+  }
+}
+
+export function repoRoot(cwd) {
+  const out = git(cwd, ['rev-parse', '--show-toplevel']);
+  return out ? out.trim() : null;
+}
+
+export function headCommit(cwd) {
+  const out = git(cwd, ['rev-parse', 'HEAD']);
+  return out ? out.trim() : null;
+}
+
+/** Elenca i file tracciati + untracked non ignorati. Null se non è un repo git. */
+export function lsFiles(root) {
+  const out = git(root, ['ls-files', '-z', '--cached', '--others', '--exclude-standard']);
+  if (out === null) return null;
+  return out.split('\0').filter(Boolean);
+}
+
+const IGNORED_DIRS = new Set([
+  '.git', 'node_modules', 'dist', 'build', 'out', '__pycache__', '.venv', 'venv',
+  'target', 'vendor', '.next', '.nuxt', '.openlore', '.pi', 'coverage', '.cache',
+]);
+
+/** Fallback quando non è un repo git: walk con esclusioni minime. */
+export async function walkFiles(root, { maxDepth = 32 } = {}) {
+  const acc = [];
+  async function rec(dir, depth) {
+    if (depth > maxDepth) return;
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.name.startsWith('.') && e.isDirectory()) continue;
+      const p = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (IGNORED_DIRS.has(e.name)) continue;
+        await rec(p, depth + 1);
+      } else if (e.isFile()) {
+        acc.push(path.relative(root, p));
+      }
+    }
+  }
+  await rec(root, 0);
+  return acc;
+}
+
+/** Byte NUL nei primi 8 KB: binario. */
+export function isBinary(buf) {
+  const n = Math.min(buf.length, 8192);
+  for (let i = 0; i < n; i++) if (buf[i] === 0) return true;
+  return false;
+}
+
+/** Riga più lunga > 2000 char: probabile bundle/minified. */
+export function isMinified(text) {
+  if (text.length < 4096) return false;
+  let run = 0;
+  for (let i = 0; i < text.length; i++) {
+    if (text.charCodeAt(i) === 10) run = 0;
+    else if (++run > 2000) return true;
+  }
+  return false;
+}
+
+export function fmtDuration(ms) {
+  if (ms < 1000) return `${Math.round(ms)} ms`;
+  const s = ms / 1000;
+  if (s < 60) return `${s.toFixed(1)} s`;
+  return `${Math.floor(s / 60)}m${String(Math.round(s % 60)).padStart(2, '0')}s`;
+}
+
+export function fmtBytes(n) {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 ** 2) return `${(n / 1024).toFixed(0)} KB`;
+  if (n < 1024 ** 3) return `${(n / 1024 ** 2).toFixed(1)} MB`;
+  return `${(n / 1024 ** 3).toFixed(2)} GB`;
+}