@alucard_24/pi-codeindex 0.0.0-stage → 1.1.0

package/src/cli.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+// CLI: embedding, indice, configurazione persistente e diagnostica.
+// Uso: node src/cli.js <comando> [opzioni]
+
+import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { embed, embedQuery, embedDocs, cosine, MODEL_ID, getEmbeddingProfile, modelDir, getServiceStatus, serviceCommand, embeddingStatus } from './embed.js';
+import { configCommand } from './config.js';
+import { formatProfile } from './backend.js';
+import { doctor, formatDoctor, parseDoctorArgs } from './doctor.js';
+import { indexRepo, statusOf } from './indexer.js';
+import { loadSearcher, search } from './search.js';
+import { formatBundle, formatHits } from './present.js';
+import { buildBundle, buildGraph } from './graph.js';
+import { runEval } from './eval.js';
+import { indexDir } from './store.js';
+import { fmtBytes, fmtDuration } from './util.js';
+
+function arg(name, def = null) {
+  const i = process.argv.indexOf(`--${name}`);
+  if (i === -1) return def;
+  const v = process.argv[i + 1];
+  return v && !v.startsWith('--') ? v : true;
+}
+
+function rssMb() {
+  return Math.round(process.memoryUsage().rss / 1024 / 1024);
+}
+
+async function embedTest() {
+  const SAME = 'export function parseArgs(argv) { return argv.slice(2); }';
+  const OTHER =
+    'async function waitForIdle(timeoutMs) { await new Promise((r) => setTimeout(r, timeoutMs)); }';
+
+  const t0 = performance.now();
+  const [sameA, sameB, other] = await embed([SAME, SAME, OTHER]);
+  const tCold = Math.round(performance.now() - t0);
+
+  const profile = await getEmbeddingProfile();
+  console.log('runtime      :', MODEL_ID, formatProfile(profile));
+  console.log('cache        :', await modelDir());
+  console.log('dims         :', sameA.length, '(atteso 768)');
+  console.log('cos(same)    :', cosine(sameA, sameB).toFixed(6), '(atteso ~1.0)');
+  console.log('cos(diverse) :', cosine(sameA, other).toFixed(6), '(atteso < 0.95)');
+  console.log('latency cold :', tCold, 'ms per 3 testi');
+  console.log('rss client   :', rssMb(), 'MiB');
+  const service = await getServiceStatus();
+  console.log('servizio     :', service.pid, '· RSS', Math.round(service.rssBytes / 1024 / 1024), 'MiB');
+
+  const batch = Array.from({ length: 16 }, (_, i) => `${SAME} // variante ${i}`);
+  const t1 = performance.now();
+  await embed(batch);
+  const warm = Math.round(performance.now() - t1);
+  console.log('latency warm :', warm, `ms per 16 testi (${(warm / 16).toFixed(1)} ms/testo)`);
+
+  const q = await embedQuery('dove vengono parsati gli argomenti da riga di comando');
+  const docs = await embedDocs([
+    { path: 'src/cli/args.ts', text: SAME },
+    { path: 'src/async/idle.ts', text: OTHER },
+  ]);
+  console.log('query->args  :', cosine(q[0], docs[0]).toFixed(4));
+  console.log('query->idle  :', cosine(q[0], docs[1]).toFixed(4));
+  console.log('rss client finale:', rssMb(), 'MiB');
+
+  const dump = arg('dump');
+  if (dump && dump !== true) {
+    fs.writeFileSync(dump, JSON.stringify({ ...profile, vectors: { same: sameA, other } }));
+    console.log('dump         :', dump);
+  }
+}
+
+async function cmdIndex() {
+  const root = arg('root') ?? process.cwd();
+  const maxFiles = Number(arg('max-files', 5000));
+  const maxBytes = Math.round(Number(arg('max-bytes', 200)) * 1024 * 1024);
+  const batchSize = Number(arg('batch', 16));
+  const force = Boolean(arg('force', false));
+
+  const r = await indexRepo({ root, maxFiles, maxBytes, batchSize, force });
+  const out = {
+    repo: r.repo,
+    profile: { model: r.index.model, dims: r.index.dims, device: r.index.device, dtype: r.index.dtype, webgpuBackend: r.index.webgpuBackend },
+    files: r.index.stats.files,
+    chunks: r.total,
+    embedded: r.embedded,
+    reused: r.reused,
+    unchangedFiles: r.unchanged,
+    bytes: r.index.stats.bytes,
+    durationMs: Math.round(r.duration),
+    skip: r.index.skipped,
+  };
+  if (arg('json')) {
+    console.log(JSON.stringify(out));
+  } else {
+    console.log(`repo         : ${r.repo}`);
+    console.log(`runtime      : ${formatProfile(r.index)} · servizio condiviso`);
+    console.log(`file         : ${out.files} (${fmtBytes(out.bytes)}) · invariati ${out.unchangedFiles}`);
+    console.log(`chunk        : ${out.chunks} · riusati ${out.reused} · embeddati ${out.embedded}`);
+    console.log(`esclusi      : estensione ${out.skip.ext}, dimensione ${out.skip.big}, binari ${out.skip.binary}, minified ${out.skip.minified}, cap ${out.skip.cap}`);
+    console.log(`durata       : ${fmtDuration(out.durationMs)}`);
+  }
+}
+
+async function cmdStatus() {
+  const root = arg('root') ?? process.cwd();
+  const { repo, index, hasVectors } = await statusOf(root);
+  if (!index) {
+    console.log(`nessun indice per ${repo}`);
+    return;
+  }
+  const info = {
+    repo,
+    files: index.stats?.files,
+    chunks: index.chunks.length,
+    dims: index.dims,
+    model: `${index.model} (${index.dtype})`,
+    device: index.device ?? 'legacy (reindex richiesto)',
+    ...(index.device === 'webgpu' ? { webgpuBackend: index.webgpuBackend ?? 'auto' } : {}),
+    chunkerVersion: index.chunkerVersion,
+    head: index.head,
+    updatedAt: index.updatedAt,
+    vectors: hasVectors,
+  };
+  if (arg('json')) {
+    console.log(JSON.stringify(info));
+    return;
+  }
+  for (const [k, v] of Object.entries(info)) console.log(`${k.padEnd(14)}: ${v}`);
+  console.log(`${'cache'.padEnd(14)}: ${indexDir(repo)}`);
+}
+
+async function cmdSearch() {
+  const query = process.argv[3];
+  if (!query) throw new Error('uso: search "query" [--k 8] [--path-prefix src/] [--json]');
+  const res = await search(query, {
+    root: arg('root') ?? process.cwd(),
+    k: Number(arg('k', 8)),
+    pathPrefix: arg('path-prefix'),
+    checkStale: Boolean(arg('stale', false)),
+  });
+  if (arg('bundle')) {
+    const { index } = await loadSearcher(res.repo);
+    const graph = await buildGraph(res.repo, index);
+    await buildBundle(res.repo, index, res.results, graph);
+    console.log(formatBundle(query, res));
+    return;
+  }
+  if (arg('json')) console.log(JSON.stringify({ ...res, repo: undefined }));
+  else console.log(formatHits(query, res));
+}
+
+async function cmdEval() {
+  const file = arg('file') ?? fileURLToPath(new URL('../eval/queries.jsonl', import.meta.url));
+  const r = await runEval({
+    root: arg('root') ?? process.cwd(),
+    file,
+    k: Number(arg('k', 8)),
+  });
+  console.log('');
+  console.log(`recall@3: ${(r.recall3 * 100).toFixed(0)}%  recall@8: ${(r.recall8 * 100).toFixed(0)}%  (${r.queries} query)`);
+  console.log(`latenza: p50 ${r.latencyP50} ms · p95 ${r.latencyP95} ms · cold ${r.coldMs} ms`);
+  if (arg('json')) console.log(JSON.stringify(r));
+  const ok = r.recall3 >= 0.625 && r.latencyP50 < 300;
+  if (!ok) process.exitCode = 2;
+}
+
+const cmd = process.argv[2];
+try {
+  if (cmd === 'config') console.log(await configCommand(process.argv.slice(3)));
+  else if (cmd === 'service') console.log(await serviceCommand(process.argv.slice(3)));
+  else if (cmd === 'setup-vulkan') {
+    const { setupVulkan } = await import('../scripts/setup-vulkan.mjs');
+    await setupVulkan(process.argv.slice(3));
+  }
+  else if (cmd === 'setup-gpu') {
+    if (process.platform !== 'linux' || process.arch !== 'x64') throw new Error('setup-gpu CUDA disponibile solo su Linux x64; usa doctor per i backend nativi della tua piattaforma');
+    const result = spawnSync('bash', [fileURLToPath(new URL('../scripts/setup-gpu.sh', import.meta.url))], { stdio: 'inherit' });
+    if (result.error) throw result.error;
+    process.exitCode = result.status ?? 1;
+  }
+  else if (cmd === 'doctor') {
+    const options = parseDoctorArgs(process.argv.slice(3));
+    const report = await doctor(options);
+    console.log(options.json ? JSON.stringify(report) : formatDoctor(report));
+    if (!report.ok) process.exitCode = 1;
+  }
+  else if (cmd === 'embed-test') await embedTest();
+  else if (cmd === 'index') await cmdIndex();
+  else if (cmd === 'status') await cmdStatus();
+  else if (cmd === 'search') await cmdSearch();
+  else if (cmd === 'eval') await cmdEval();
+  else {
+    console.error('comandi: embed-test | index | status | search | eval | setup-gpu | setup-vulkan | service [status [--json]|stop] | config [show|path|set CHIAVE VALORE|unset CHIAVE] | doctor [--probe] [--all] [--device DEVICE] [--dtype DTYPE] [--webgpu-backend auto|vulkan] [--json]');
+    process.exit(1);
+  }
+  const runtime = embeddingStatus();
+  const warnings = [...runtime.warnings, ...runtime.attempts.filter((a) => !a.ok).map((a) => `${a.device}: ${a.error}`)];
+  if (runtime.profile && warnings.length) console.error(`codeindex: selezionato ${formatProfile(runtime.profile)}; ${warnings.join('; ')}`);
+} catch (e) {
+  console.error(`errore: ${e.message}`);
+  if (process.env.CODEINDEX_DEBUG) console.error(e.stack);
+  process.exit(1);
+}

package/src/config-ui.js

@@ -0,0 +1,37 @@
+// Solo dialoghi standard pi: utilizzabili anche tramite RPC. Nessun salvataggio
+// prima della conferma; gli override d'ambiente non vengono copiati nel file.
+import { DEVICES, DTYPES, WEBGPU_BACKENDS, ENV_KEYS, formatConfig, loadConfig, parseSetting, updateConfig } from './config.js';
+
+export async function configure(ctx, options = {}) {
+  if (!ctx.hasUI) throw new Error('configurazione interattiva non disponibile; usa /codeindex config set CHIAVE VALORE');
+  const loaded = await loadConfig(options);
+  const draft = { ...loaded.config };
+  const patch = {};
+  const keys = Object.keys(ENV_KEYS);
+  while (true) {
+    const entries = [...keys.map((key) => `${key}: ${draft[key]}`), 'Salva', 'Annulla'];
+    const selected = await ctx.ui.select('Embedding locali — configurazione (riavvio richiesto)', entries);
+    if (!selected || selected === 'Annulla') return null;
+    if (selected === 'Salva') {
+      if (!Object.keys(patch).length) return null;
+      if (!(await ctx.ui.confirm('Salvare la configurazione?', `${loaded.file}\n${JSON.stringify(patch, null, 2)}\nRiavvia pi dopo il salvataggio. Per cambiare un servizio già attivo usa /codeindex service stop quando inattivo. Cambiare device/dtype/backend WebGPU richiede un re-index.`))) return null;
+      const file = await updateConfig(patch, options);
+      const overrides = Object.keys(patch).filter((key) => loaded.sources[key] === ENV_KEYS[key]);
+      return `salvato: ${file}\nRiavvia pi (nuovo processo) per applicare; per cambiare un servizio già attivo usa /codeindex service stop quando inattivo.` +
+        (overrides.length ? `\nAttenzione: override d'ambiente attivi per ${overrides.join(', ')}.` : '') +
+        `\n${formatConfig(await loadConfig(options))}`;
+    }
+    const key = keys[entries.indexOf(selected)];
+    if (!key) continue;
+    const choices = key === 'device' ? DEVICES : key === 'dtype' ? DTYPES
+      : key === 'webgpuBackend' ? WEBGPU_BACKENDS : key === 'fallback' ? ['error', 'cpu'] : key === 'offline' ? ['false', 'true'] : null;
+    const hint = key === 'webgpuBackend' ? ' — solo WebGPU; vulkan richiede setup-vulkan'
+      : key === 'serviceIdleMs' ? ' — millisecondi; 300000 = 5 minuti'
+      : key === 'serviceDir' || key === 'servicePort' ? ' — lascia uguale fra sessioni per condividere un solo modello' : '';
+    const text = choices ? await ctx.ui.select(`${key}${hint} (attuale: ${draft[key]})`, choices)
+      : await ctx.ui.input(`${key}${hint} (attuale: ${draft[key]})`, String(draft[key]));
+    if (text === undefined) continue;
+    try { draft[key] = patch[key] = parseSetting(key, text); }
+    catch (e) { ctx.ui.notify(e.message, 'error'); }
+  }
+}

package/src/config.js

@@ -0,0 +1,131 @@
+// Configurazione della macchina: mai lettura implicita di file nel repository.
+// Precedenza: default < file utente (o CODEINDEX_CONFIG) < ambiente.
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export const DEVICES = ['auto', 'cpu', 'cuda', 'webgpu', 'dml', 'coreml'];
+export const DTYPES = ['auto', 'q8', 'q4', 'fp16'];
+export const WEBGPU_BACKENDS = ['auto', 'vulkan'];
+export const ENV_KEYS = {
+  device: 'CODEINDEX_DEVICE', dtype: 'CODEINDEX_DTYPE', fallback: 'CODEINDEX_FALLBACK',
+  offline: 'CODEINDEX_OFFLINE', cacheDir: 'CODEINDEX_MODEL_CACHE', cpuThreads: 'CODEINDEX_CPU_THREADS',
+  webgpuBackend: 'CODEINDEX_WEBGPU_BACKEND',
+  serviceDir: 'CODEINDEX_SERVICE_DIR', servicePort: 'CODEINDEX_SERVICE_PORT', serviceIdleMs: 'CODEINDEX_SERVICE_IDLE_MS',
+};
+
+export function configPath(env = process.env, home = os.homedir()) {
+  if (env.CODEINDEX_CONFIG) return expandPath(env.CODEINDEX_CONFIG, home);
+  const base = env.XDG_CONFIG_HOME || (process.platform === 'win32' ? env.APPDATA : null) || path.join(home, '.config');
+  return path.resolve(base, 'pi-codeindex', 'config.json');
+}
+
+function expandPath(value, home = os.homedir()) {
+  return path.resolve(value === '~' ? home : value.startsWith('~/') ? path.join(home, value.slice(2)) : value);
+}
+
+export function defaults(home = os.homedir()) {
+  return { device: 'auto', dtype: 'auto', webgpuBackend: 'auto', fallback: 'error', offline: false,
+    cacheDir: path.join(home, '.cache', 'pi-codeindex', 'text-model'), cpuThreads: 0,
+    serviceDir: path.join(home, '.cache', 'pi-codeindex', 'service'), servicePort: 0, serviceIdleMs: 300_000 };
+}
+
+export function validateConfig(value, source = 'config') {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${source}: atteso un oggetto JSON`);
+  for (const [key, v] of Object.entries(value)) {
+    if (key === '$schema') {
+      if (typeof v !== 'string') throw new Error(`${source}: $schema deve essere una stringa`);
+      continue;
+    }
+    if (!Object.hasOwn(ENV_KEYS, key)) throw new Error(`${source}: chiave sconosciuta "${key}"`);
+    if (key === 'device' && v === 'vulkan') {
+      throw new Error(`${source}: Vulkan non è un provider ONNX autonomo. Usa device webgpu e webgpuBackend vulkan per forzarlo (setup-vulkan richiesto).`);
+    }
+    const choices = key === 'device' ? DEVICES : key === 'dtype' ? DTYPES
+      : key === 'webgpuBackend' ? WEBGPU_BACKENDS : key === 'fallback' ? ['error', 'cpu'] : null;
+    if (choices && !choices.includes(v)) throw new Error(`${source}: ${key} deve essere uno di: ${choices.join(', ')}`);
+    if (key === 'offline' && typeof v !== 'boolean') throw new Error(`${source}: offline deve essere booleano`);
+    if (['cacheDir', 'serviceDir'].includes(key) && (typeof v !== 'string' || !v.trim())) throw new Error(`${source}: ${key} deve essere un percorso non vuoto`);
+    if (key === 'cpuThreads' && (!Number.isInteger(v) || v < 0 || v > 256)) throw new Error(`${source}: cpuThreads deve essere un intero tra 0 e 256`);
+    if (key === 'servicePort' && (!Number.isInteger(v) || (v !== 0 && (v < 1024 || v > 65535)))) throw new Error(`${source}: servicePort deve essere 0 (automatico) oppure un intero tra 1024 e 65535`);
+    if (key === 'serviceIdleMs' && (!Number.isInteger(v) || v < 1000 || v > 86_400_000)) throw new Error(`${source}: serviceIdleMs deve essere un intero tra 1000 e 86400000`);
+  }
+  return value;
+}
+
+export function parseSetting(key, text) {
+  if (!Object.hasOwn(ENV_KEYS, key)) throw new Error(`chiave sconosciuta "${key}"`);
+  let value = text;
+  if (key === 'offline') {
+    if (!['true', 'false', '1', '0'].includes(text)) throw new Error('offline: usa true oppure false');
+    value = text === 'true' || text === '1';
+  } else if (['cpuThreads', 'servicePort', 'serviceIdleMs'].includes(key)) {
+    if (!/^\d+$/.test(text)) throw new Error(`${key}: atteso un intero`);
+    value = Number(text);
+  }
+  validateConfig({ [key]: value });
+  return value;
+}
+
+async function readConfig(file) {
+  try {
+    return validateConfig(JSON.parse(await fs.readFile(file, 'utf8')), file);
+  } catch (e) {
+    if (e.code === 'ENOENT') return {};
+    throw new Error(`configurazione non valida: ${e.message}`);
+  }
+}
+
+export async function loadConfig({ env = process.env, home = os.homedir() } = {}) {
+  const file = configPath(env, home);
+  const stored = await readConfig(file);
+  const config = { ...defaults(home), ...stored };
+  delete config.$schema;
+  const sources = Object.fromEntries(Object.keys(config).map((key) => [key, key in stored ? file : 'default']));
+  for (const [key, name] of Object.entries(ENV_KEYS)) {
+    if (env[name] === undefined) continue;
+    config[key] = parseSetting(key, env[name]);
+    sources[key] = name;
+  }
+  validateConfig(config, file);
+  config.cacheDir = expandPath(config.cacheDir, home);
+  config.serviceDir = expandPath(config.serviceDir, home);
+  return { config: Object.freeze(config), sources, file };
+}
+
+// Salva solo valori espliciti, mai gli override dell'ambiente. Temp unico per
+// non interferire con altre sessioni; rename atomico e permessi privati.
+export async function updateConfig(patch, { unset = [], env = process.env, home = os.homedir() } = {}) {
+  validateConfig(patch);
+  for (const key of unset) if (!Object.hasOwn(ENV_KEYS, key)) throw new Error(`chiave sconosciuta "${key}"`);
+  const file = configPath(env, home);
+  const stored = { ...await readConfig(file), ...patch };
+  for (const key of unset) delete stored[key];
+  validateConfig(stored, file);
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${randomUUID()}.tmp`;
+  try {
+    await fs.writeFile(tmp, `${JSON.stringify(stored, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+    await fs.rename(tmp, file);
+  } finally {
+    await fs.rm(tmp, { force: true });
+  }
+  return file;
+}
+
+export function formatConfig({ config, sources, file }) {
+  return [`file: ${file}`, ...Object.entries(config).map(([key, value]) =>
+    `${key.padEnd(12)}: ${value} (${sources[key]})`)].join('\n');
+}
+
+export async function configCommand(args, options = {}) {
+  const [action = 'show', key, ...rest] = args;
+  if (action === 'path' && args.length === 1) return configPath(options.env, options.home);
+  if (action === 'show' && args.length <= 1) return formatConfig(await loadConfig(options));
+  let file;
+  if (action === 'set' && key && rest.length) file = await updateConfig({ [key]: parseSetting(key, rest.join(' ')) }, options);
+  else if (action === 'unset' && key && !rest.length) file = await updateConfig({}, { ...options, unset: [key] });
+  else throw new Error('uso: config [show|path|set CHIAVE VALORE|unset CHIAVE]');
+  return `salvato: ${file}\nRiavvia pi (nuovo processo) per applicare. Per cambiare un profilo già attivo usa anche /codeindex service stop quando il servizio è inattivo. Gli override CODEINDEX_* hanno precedenza.\n${formatConfig(await loadConfig(options))}`;
+}

package/src/doctor.js

@@ -0,0 +1,101 @@
+// Diagnostica senza download per default. Le prove reali sono isolate in un
+// processo figlio con timeout: un crash nativo non abbatte la sessione pi.
+import { fork } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { loadConfig, parseSetting } from './config.js';
+import { nativeBackends, formatProfile } from './backend.js';
+import { vulkanStatus } from './vulkan.js';
+import { createEmbeddingClient } from './service-client.js';
+
+export function parseDoctorArgs(args) {
+  const options = { probe: false, all: false, json: false };
+  for (let i = 0; i < args.length; i++) {
+    const flag = args[i];
+    if (flag === '--probe') options.probe = true;
+    else if (flag === '--all') options.all = true;
+    else if (flag === '--json') options.json = true;
+    else if (flag === '--device' || flag === '--dtype' || flag === '--webgpu-backend') {
+      const value = args[++i];
+      if (!value || value.startsWith('--')) throw new Error(`manca il valore di ${flag}`);
+      const key = flag === '--webgpu-backend' ? 'webgpuBackend' : flag.slice(2);
+      options[key] = parseSetting(key, value);
+    } else throw new Error(`opzione doctor sconosciuta: ${flag}`);
+  }
+  if (options.all && !options.probe) throw new Error('--all richiede --probe');
+  if (options.all && options.device) throw new Error('scegli --all oppure --device, non entrambi');
+  if (options.webgpuBackend && !options.all) {
+    if (options.device && options.device !== 'webgpu') throw new Error('--webgpu-backend richiede --device webgpu oppure --all');
+    options.device = 'webgpu';
+  }
+  return options;
+}
+
+export function probeBackend({ device, dtype, webgpuBackend, timeoutMs = 120_000, env = process.env } = {}) {
+  return new Promise((resolve) => {
+    const childEnv = { ...env, CODEINDEX_FALLBACK: 'error' };
+    if (device) childEnv.CODEINDEX_DEVICE = device;
+    if (dtype) childEnv.CODEINDEX_DTYPE = dtype;
+    if (webgpuBackend) childEnv.CODEINDEX_WEBGPU_BACKEND = webgpuBackend;
+    const child = fork(fileURLToPath(new URL('./probe.js', import.meta.url)), [], { env: childEnv, silent: true, execArgv: [] });
+    let response = null, stderr = '', spawnError = null, timedOut = false;
+    const timer = setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, timeoutMs);
+    child.stderr.on('data', (s) => { stderr = (stderr + s).slice(-6000); });
+    child.stdout.on('data', () => {}); // drena eventuali messaggi del binding
+    child.on('message', (value) => { if (value && typeof value.ok === 'boolean') response = value; });
+    child.on('error', (e) => { spawnError = e.message; });
+    child.on('close', (code, signal) => {
+      clearTimeout(timer);
+      const ok = !timedOut && code === 0 && response?.ok === true;
+      resolve({ ...response, requested: device ?? 'auto', ok, code, signal,
+        ...(!ok ? { error: timedOut ? `timeout dopo ${timeoutMs} ms` : response?.error ?? spawnError ?? `processo terminato (${signal ?? code})`, stderr } : {}) });
+    });
+  });
+}
+
+export async function doctor({ probe = false, all = false, device, dtype, webgpuBackend, timeoutMs, env = process.env } = {}) {
+  if (device) parseSetting('device', device);
+  if (dtype) parseSetting('dtype', dtype);
+  if (webgpuBackend) {
+    parseSetting('webgpuBackend', webgpuBackend);
+    if (!all) {
+      if (device && device !== 'webgpu') throw new Error('--webgpu-backend richiede --device webgpu oppure --all');
+      device = 'webgpu';
+    }
+  }
+  const settings = await loadConfig({ env });
+  const native = nativeBackends();
+  const service = await createEmbeddingClient({ settings: () => settings, env }).status()
+    .catch((e) => ({ running: false, error: e.message }));
+  const report = { ok: !service.error, service, platform: process.platform, arch: process.arch, node: process.version,
+    runtime: native.version, settings,
+    requested: { device: device ?? settings.config.device, dtype: dtype ?? settings.config.dtype,
+      webgpuBackend: webgpuBackend ?? settings.config.webgpuBackend },
+    backends: native.backends, vulkan: vulkanStatus(), probes: [] };
+  if (probe) {
+    const devices = all ? native.backends.filter((b) => b.available).map((b) => b.device) : [device ?? settings.config.device];
+    for (const selected of devices) {
+      report.probes.push(await probeBackend({ device: selected, dtype, webgpuBackend, timeoutMs, env }));
+    }
+    report.ok = !service.error && report.probes.length > 0 && report.probes.every((p) => p.ok);
+  }
+  return report;
+}
+
+export function formatDoctor(report) {
+  const lines = [`${report.platform}/${report.arch} · Node ${report.node} · ONNX Runtime ${report.runtime}`,
+    `config: ${report.settings.file}`,
+    `richiesto: ${(report.requested ?? report.settings.config).device}/${(report.requested ?? report.settings.config).dtype} · fallback ${report.settings.config.fallback} · offline ${report.settings.config.offline}`,
+    ...report.backends.map((b) => `${b.device.padEnd(8)}: ${b.available ? 'presente' : 'assente'} — ${b.reason}`),
+    `backend WebGPU richiesto: ${(report.requested ?? report.settings.config).webgpuBackend} (solo quando il provider selezionato è WebGPU)`,
+    `Vulkan forzato: ${report.vulkan?.available ? 'presente' : 'assente'} — ${report.vulkan?.reason ?? 'non verificato'}`];
+  lines.push(`servizio condiviso: ${report.service?.error ?? (report.service?.running ? `PID ${report.service.pid} · ${report.service.pending} richieste · ${Math.round(report.service.rssBytes / 1024 / 1024)} MiB RSS` : report.service?.stopping ? 'in arresto' : 'fermo (nessun avvio da doctor)')}`);
+  if (!report.probes.length) lines.push('Nessuna inferenza eseguita. Usa doctor --probe (può scaricare i pesi), oppure --probe --all.');
+  for (const p of report.probes) {
+    lines.push(p.ok ? `PASS ${p.requested}: ${formatProfile(p.profile)} · ${p.profile.dims}d · ${p.elapsedMs} ms · cos(stesso) ${p.cosSame.toFixed(6)}`
+      : `FAIL ${p.requested}: ${p.error}`);
+    for (const a of p.attempts ?? []) if (!a.ok) lines.push(`  ${formatProfile(a)}: ${a.error}`);
+  }
+  if (report.probes.length) lines.push('Probe isolati: possono caricare una copia aggiuntiva del modello mentre il servizio condiviso è attivo.');
+  lines.push('Un provider presente non prova compatibilità/velocità del modello; ORT può eseguire alcuni operatori su CPU.');
+  return lines.join('\n');
+}

package/src/embed.js

@@ -0,0 +1,57 @@
+// Facciata dei client pi/CLI. L'unica pipeline vive nel servizio condiviso;
+// nessun errore di IPC attiva un fallback in-process.
+import { createEmbeddingClient } from './service-client.js';
+import { modelPath } from './model.js';
+import { MODEL_ID, DIMS, QUERY_PREFIX, docPrefix } from './backend.js';
+
+export { MODEL_ID, DIMS, QUERY_PREFIX, docPrefix };
+const client = createEmbeddingClient();
+
+export const getEmbeddingProfile = () => client.getProfile();
+export const embeddingStatus = () => client.info();
+export const getServiceStatus = () => client.status();
+export const stopEmbeddingService = () => client.stop();
+
+/** Testi -> Float32Array[] finiti, normalizzati L2 per default. */
+export async function embed(texts, options = {}) {
+  if (!Array.isArray(texts) || texts.length === 0) return [];
+  return client.embed(texts, options);
+}
+export function embedQuery(q) { return embed([QUERY_PREFIX + q]); }
+export function embedDocs(docs) {
+  return embed(docs.map((d) => typeof d === 'string' ? d : docPrefix(d.path, d.title) + d.text));
+}
+export function cosine(a, b) {
+  let dot = 0, na = 0, nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i]; na += a[i] * a[i]; nb += b[i] * b[i];
+  }
+  return dot / (Math.sqrt(na) * Math.sqrt(nb) || 1);
+}
+export async function modelDir() {
+  const profile = await client.getProfile();
+  return modelPath(client.info().config, profile.dtype);
+}
+
+export function formatServiceStatus(status) {
+  if (status.stopping) return `servizio condiviso: in arresto · PID ${status.pid} (rilascio delle risorse in corso)`;
+  if (!status.running) return `servizio condiviso: fermo (avvio automatico al prossimo embedding) · porta ${status.port}`;
+  const profile = status.profile;
+  return [`servizio condiviso: attivo · PID ${status.pid} · 127.0.0.1:${status.port}`,
+    `modello: ${profile ? `${profile.device}${profile.device === 'webgpu' ? `→${profile.webgpuBackend}` : ''}/${profile.dtype}` : status.initializing ? 'caricamento' : 'non caricato'}`,
+    `richieste attive/in coda: ${status.pending} · RSS servizio: ${Math.round(status.rssBytes / 1024 / 1024)} MiB`,
+    `uscita dopo inattività: ${status.idleMs} ms`].join('\n');
+}
+export async function serviceCommand(args, { service = client } = {}) {
+  const [action = 'status', ...rest] = args;
+  if (rest.some((arg) => arg !== '--json') || rest.length > 1 || (action !== 'status' && rest.length)) throw new Error('uso: service [status [--json]|stop]');
+  if (action === 'status') {
+    const status = await service.status();
+    return rest.includes('--json') ? JSON.stringify(status) : formatServiceStatus(status);
+  }
+  if (action === 'stop') {
+    const result = await service.stop();
+    return result.stopping ? `arresto del servizio condiviso richiesto (PID ${result.pid}); si riavvierà al prossimo embedding` : 'servizio condiviso già fermo';
+  }
+  throw new Error('uso: service [status [--json]|stop]');
+}

package/src/eval.js

@@ -0,0 +1,72 @@
+// Eval minima: query a risposta nota -> recall@k + latenza.
+// Fixture JSONL: {"query": "...", "expects": ["substring/path"], "why": "..."}
+
+import fs from 'node:fs/promises';
+import { search } from './search.js';
+import { repoRoot } from './util.js';
+
+const percentile = (arr, p) => {
+  if (arr.length === 0) return 0;
+  const s = [...arr].sort((a, b) => a - b);
+  return s[Math.min(s.length - 1, Math.floor((s.length - 1) * p))];
+};
+
+export async function loadQueries(file) {
+  const text = await fs.readFile(file, 'utf8');
+  return text
+    .split('\n')
+    .filter((l) => l.trim() && !l.trim().startsWith('//'))
+    .map((l, i) => {
+      try {
+        return JSON.parse(l);
+      } catch (e) {
+        throw new Error(`riga ${i + 1} di ${file}: JSON non valido (${e.message})`);
+      }
+    });
+}
+
+export async function runEval({ root, file, k = 8, quiet = false } = {}) {
+  const repo = root ?? repoRoot(process.cwd());
+  if (!repo) throw new Error('non è un repo git: passa --root');
+  const queries = await loadQueries(file);
+
+  const t0 = performance.now();
+  await search('warmup', { root: repo, k: 1 }); // carica modello e indice
+  const coldMs = Math.round(performance.now() - t0);
+
+  const rows = [];
+  const latencies = [];
+  for (const q of queries) {
+    const res = await search(q.query, { root: repo, k });
+    latencies.push(res.tookMs);
+    const top = res.results;
+    const matches = (n) =>
+      top.slice(0, n).some((r) => q.expects.some((e) => r.path.toLowerCase().includes(e.toLowerCase())));
+    rows.push({
+      query: q.query,
+      hit3: matches(3),
+      hit8: matches(8),
+      rank: top.findIndex((r) => q.expects.some((e) => r.path.toLowerCase().includes(e.toLowerCase()))) + 1,
+      top: top.slice(0, 3).map((r) => `${r.path}:${r.start}-${r.end}`),
+      tookMs: res.tookMs,
+      why: q.why,
+    });
+    if (!quiet) {
+      const mark = rows.at(-1).hit3 ? 'OK  ' : rows.at(-1).hit8 ? 'ok@8' : 'MISS';
+      console.log(`${mark} ${res.tookMs.toFixed(0).padStart(4)} ms · ${q.query}`);
+      console.log(`     attesi: ${q.expects.join(' | ')}`);
+      console.log(`     top:    ${rows.at(-1).top.join('  ·  ')}`);
+    }
+  }
+
+  return {
+    repo,
+    queries: rows.length,
+    recall3: rows.filter((r) => r.hit3).length / rows.length,
+    recall8: rows.filter((r) => r.hit8).length / rows.length,
+    coldMs,
+    latencyP50: Math.round(percentile(latencies, 0.5)),
+    latencyP95: Math.round(percentile(latencies, 0.95)),
+    rows,
+  };
+}