@alucard_24/pi-codeindex 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alucard24
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,346 @@
-# Temporary Holding Version
+# pi-codeindex
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Indice semantico locale del codice per l'agente pi: embedding con
+**EmbeddingGemma 2** (ONNX, in-process) e ricerca ibrida (coseno + lessico)
+che restituisce `path:righe` + simbolo + anteprima. Nessun server, nessun
+database: due file in `~/.cache/pi-codeindex/<sha1(repo)>/`.
+
+## Requisiti
+
+- Node 22+ (testato su 26.5.1).
+- CPU sempre disponibile come profilo base nelle build native supportate.
+- GPU opzionale: CUDA su Linux x64, WebGPU dove incluso nel binding,
+  DirectML su Windows, CoreML su macOS. Non tutte le combinazioni modello,
+  driver e hardware sono verificate: vedi la matrice sotto.
+
+## Installazione
+
+### Da npm, solo su richiesta
+
+```bash
+pi -e npm:@alucard_24/pi-codeindex@1.0.0
+```
+
+Carica il pacchetto per questa invocazione, senza aggiungerlo alle impostazioni
+globali di pi. Dalla sessione puoi usare `/codeindex configure` e
+`/codeindex doctor`. I pesi vengono scaricati solo al primo utilizzo del modello;
+CUDA e Vulkan richiedono i setup opzionali descritti sotto.
+
+Il pacchetto npm include codice, setup, schema, README, licenza e query di
+esempio. Il repository GitHub resta privato; piano di lavoro, report completi,
+harness sperimentale e test non sono inclusi nel tarball npm.
+
+### Dal sorgente (sviluppo)
+
+```bash
+npm install
+npm run setup-gpu     # solo GPU NVIDIA: scarica il provider CUDA e lo configura
+```
+
+`setup-gpu.sh` è **solo Linux x64** e richiede CUDA 13 + `patchelf`.
+Va rieseguito se un aggiornamento/reinstallazione sostituisce il provider.
+DirectML, CoreML e WebGPU usano i provider inclusi nel binding nativo;
+non richiedono questo script CUDA.
+
+Il pacchetto espone anche il binario `pi-codeindex`: gli esempi
+`node src/cli.js ...` possono essere eseguiti come `pi-codeindex ...`
+quando il binario è sul PATH. `pi-codeindex setup-gpu` avvia il setup CUDA.
+Nessun postinstall scarica i pesi e nessuna configurazione globale di pi viene
+modificata dal pacchetto.
+
+## Embedding e backend
+
+Il modello **EmbeddingGemma 2** gira localmente, in-process. I soli pesi testo
+vengono scaricati al primo utilizzo (anche dall'indicizzazione automatica) e
+riutilizzati fra repository. Nessun server o API di embedding; dopo il primo
+download è possibile lavorare offline. Il codice da embeddare non viene
+inviato al server dei pesi. Un processo pi mantiene una propria pipeline.
+
+| `device` | Default `dtype: auto` | Stato |
+|---|---|---|
+| `cpu` | `q8` | inferenza reale verificata su Linux x64 |
+| `cuda` | `fp16` | inferenza reale verificata su NVIDIA/Linux x64; setup opzionale |
+| `webgpu` | `fp16` | inferenza reale verificata su questa macchina Linux; supporto hardware/driver variabile |
+| `dml` | `fp16` | DirectML/Windows: integrazione e policy testate, hardware non verificato |
+| `coreml` | `fp16` | CoreML/macOS: integrazione e policy testate, hardware non verificato |
+
+**Vulkan è selezionabile come backend nativo di WebGPU**, non come provider
+ONNX autonomo: usa `device: "webgpu"` + `webgpuBackend: "vulkan"` dopo il setup
+opzionale sotto. `device: "vulkan"` resta un errore esplicativo. Con
+`webgpuBackend: "auto"` decide Dawn: non si garantisce Vulkan e non lo si
+presenta come forzato. Stato e metadati distinguono `webgpu→vulkan/fp16` da
+`webgpu→auto/fp16`.
+Un provider presente nel binding non garantisce compatibilità, velocità,
+utilizzo della GPU dedicata o copertura totale del grafo: ORT può eseguire
+alcuni operatori su CPU. Gli smoke test non sostituiscono un benchmark di
+retrieval/performance per piattaforma. `q4` è disponibile ma il drift non è
+validato sull'eval.
+
+**Auto:** Linux prova CUDA → WebGPU → CPU; Windows DirectML → WebGPU → CPU;
+macOS CoreML → WebGPU → CPU. I provider assenti vengono saltati; una prova del
+modello reale deve riuscire prima che il profilo venga fissato. Tentativi e
+fallback sono visibili nei log e nello stato/avvisi dell'estensione.
+Un device forzato fallisce per default; `fallback: "cpu"` autorizza il ripiego.
+Il fallback avviene solo all'inizializzazione, mai durante l'embedding di un
+indice già iniziato. La prima riconciliazione di un processo inizializza il
+modello anche se l'indice era caldo; i vecchi tempi di re-index sotto indicati
+precedono questo cambiamento.
+
+### WebGPU con Vulkan forzato (opzionale, Linux x64)
+
+```bash
+npm run setup-vulkan
+CODEINDEX_OFFLINE=true node src/cli.js doctor --probe --device webgpu --webgpu-backend vulkan
+CODEINDEX_DEVICE=webgpu CODEINDEX_WEBGPU_BACKEND=vulkan pi -e ./src/extension.js
+```
+
+Il setup richiede **compilatore C++17, header Node/N-API, `tar`, `patchelf` e
+rete** per scaricare i piccoli sorgenti del binding. Non compila ORT/Dawn e
+non richiede CUDA o il Vulkan SDK: riusa il runtime precompilato con WebGPU;
+per eseguire serve il driver Vulkan. Header fuori dai percorsi standard:
+`npm run setup-vulkan -- --node-headers /percorso/include/node`.
+
+Il binding Node standard 1.30.0 non espone il selettore Dawn. Il setup
+compila un binding opzionale da un commit ORT fissato e con hash dei sorgenti
+verificati. Binding e copia del runtime (con SONAME distinto) restano in
+`~/.cache/pi-codeindex/native/`: **nessuna modifica a `node_modules`**, nessun
+provider standard sostituito. Il backend aggiunto ha nome unico e priorità
+negativa: viene usato solo da una sessione che lo richiede esplicitamente.
+Prima del caricamento si verificano gli hash; un controllo negativo obbligatorio
+rifiuta i binding che ignorano il selettore. Manca il setup, il runtime è
+cambiato o non esiste un adapter Vulkan? Errore, non WebGPU automatico nascosto.
+Il fallback CPU resta solo quello già autorizzato da `fallback: "cpu"`.
+
+Il setup è idempotente; dopo un cambio di runtime può essere necessario
+rieseguirlo. `pi-codeindex setup-vulkan` è equivalente. Riavvia pi dopo setup
+o cambi di profilo. Il backend WebGPU entra nell'identità dell'indice: cambiare
+`auto` ↔ `vulkan` richiede re-index. Con `device: "auto"` il selettore riguarda
+solo l'eventuale tentativo WebGPU: CUDA può ancora essere scelto prima.
+
+Windows richiederebbe anche una build ORT/Dawn con Vulkan abilitato: **non
+implementata/verificata** da questo setup. AMD e Intel richiedono prove sulle
+rispettive GPU. Nessuna promessa di vantaggio prestazionale rispetto a CUDA.
+Le prove con il modello completo richiedono VRAM libera; il processo `doctor`
+riporta l'errore e non termina applicazioni GPU altrui per liberarla.
+
+Test opzionali reali, dopo setup e download dei pesi fp16:
+`CODEINDEX_TEST_VULKAN=1 node --test test/vulkan-integration.test.js`.
+La suite normale non richiede GPU né compila addon. Verificati su questa
+macchina Linux x64 / RTX 5070 Ti: EmbeddingGemma fp16, indice incrementale,
+ricerca su fixture e coesistenza con i provider standard. Queste prove non
+sostituiscono un benchmark di qualità o prestazioni su altri hardware.
+
+## Configurazione
+
+Dentro pi:
+
+```text
+/codeindex configure                     menu interattivo + conferma salvataggio
+/codeindex config                        valori effettivi, provenienza e percorso
+/codeindex config set device webgpu
+/codeindex config set dtype fp16
+/codeindex config set webgpuBackend vulkan  solo WebGPU, setup-vulkan richiesto
+/codeindex config set fallback cpu
+/codeindex config unset device           ripristina la scelta automatica
+/codeindex doctor                        inventario, senza inferenza/download
+/codeindex doctor --probe --device webgpu prova reale isolata (può scaricare i pesi)
+```
+
+La configurazione è **della macchina**, non della sessione pi:
+`$XDG_CONFIG_HOME/pi-codeindex/config.json` oppure
+`~/.config/pi-codeindex/config.json` (`%APPDATA%/pi-codeindex/config.json`
+su Windows). `CODEINDEX_CONFIG=/percorso/config.json` sceglie un file diverso,
+anche per un singolo progetto; nessun file del repository viene letto
+implicitamente. Non vengono modificate le impostazioni di pi.
+Precedenza: **default < file < ambiente**. Il menu salva solo i campi cambiati,
+non gli override d'ambiente. JSON malformato/chiavi sconosciute producono errori,
+non default silenziosi. Schema per editor: [config.schema.json](config.schema.json).
+
+```json
+{
+  "device": "auto",
+  "dtype": "auto",
+  "fallback": "error",
+  "offline": false,
+  "cpuThreads": 0
+}
+```
+
+| Campo | Valori | Override ambiente |
+|---|---|---|
+| `device` | `auto`, `cpu`, `cuda`, `webgpu`, `dml`, `coreml` | `CODEINDEX_DEVICE` |
+| `dtype` | `auto`, `q8`, `q4`, `fp16` | `CODEINDEX_DTYPE` |
+| `webgpuBackend` | `auto` (default), `vulkan` forzato; riguarda solo WebGPU | `CODEINDEX_WEBGPU_BACKEND` |
+| `fallback` | `error` (default), `cpu`; riguarda device forzati | `CODEINDEX_FALLBACK` |
+| `offline` | booleano; niente download, errore se mancano pesi | `CODEINDEX_OFFLINE=true\|false\|1\|0` |
+| `cacheDir` | cache pesi, default `~/.cache/pi-codeindex/text-model` | `CODEINDEX_MODEL_CACHE` |
+| `cpuThreads` | 0 = default ORT, oppure 1–256; non limita la GPU | `CODEINDEX_CPU_THREADS` |
+
+**Riavvia pi con un nuovo processo** dopo una modifica: non si cambia pipeline
+nel mezzo di un run. Il menu non riavvia né reindicizza da solo. Device, dtype
+e backend WebGPU effettivi sono salvati nell'indice; se diversi, la ricerca rifiuta di mescolare
+i vettori e chiede un re-index. Gli indici precedenti senza `device` vengono
+ricostruiti alla prossima indicizzazione.
+
+Da shell, senza avviare pi:
+
+```bash
+node src/cli.js config show
+node src/cli.js config set device cpu
+node src/cli.js config set cpuThreads 4
+node src/cli.js doctor --probe --device cpu --json
+node src/cli.js doctor --probe --all       # prove sequenziali dei provider presenti
+node src/cli.js doctor --probe --device webgpu --webgpu-backend vulkan
+CODEINDEX_DEVICE=cuda CODEINDEX_DTYPE=fp16 pi -e ./src/extension.js
+```
+
+`doctor` senza `--probe` non carica/scarica il modello. Le prove reali girano
+in subprocessi isolati con timeout di 120 s per backend; `--all` può scaricare
+più varianti. Ogni provider forzato viene provato senza fallback, per non
+attribuire alla GPU un successo ottenuto in CPU. Usa `offline: true` per provarle solo dalla cache. Un crash nativo
+di una prova non abbatte pi; questo isolamento riguarda `doctor`, non la normale
+pipeline in-process. Smoke del menu e dei comandi via RPC, senza chiamate al
+modello: `CODEINDEX_TEST_RPC=1 node --test test/config-rpc.test.js` (richiede
+`pi` sul PATH; usa un file config temporaneo, non modifica quello utente).
+
+## Comandi
+
+```bash
+node src/cli.js index   [--root DIR] [--max-files 5000] [--max-bytes 200] [--force]
+node src/cli.js status  [--root DIR]
+node src/cli.js search  "query" [--k 8] [--path-prefix src/] [--stale] [--bundle] [--json]
+node src/cli.js eval    [--file eval/queries.jsonl] [--json]
+node src/cli.js embed-test
+```
+
+- `index` è incrementale: confronta l'hash di ogni file e riusa i vettori dei
+  chunk invariati. Salvataggio atomico; una cache di ripresa evita di
+  ricalcolare tutto se il run viene interrotto.
+- `search` legge il codice dal disco solo per i risultati finali e non esce
+  mai dal repo.
+- `eval` misura recall@3/@8 e latenza sulle query della fixture.
+
+## Uso dentro pi
+
+```bash
+# pacchetto npm: solo questa invocazione, nessuna configurazione globale
+pi -e npm:@alucard_24/pi-codeindex@1.0.0
+
+# in sviluppo, dalla directory del progetto
+pi -e ./src/extension.js
+```
+
+Cosa aggiunge:
+
+- **`search_code`** — ricerca semantica (`query`, `k` 1–30, `path_prefix`,
+  `context`) che restituisce `path:start-end`, simbolo e anteprima. Non
+  sostituisce `grep`.
+  - i risultati il cui file è cambiato dopo l'indicizzazione sono marcati
+    `STALE` (hash su disco, non fiducia nel watcher);
+  - `context: "bundle"` aggiunge import, importatori e fino a 5 chiamanti
+    **euristici** dei primi 3 risultati: un round-trip invece di una catena
+    `grep`+`read`.
+- **outline su `read`** — se leggi un file > 300 righe con ≥ 5 simboli indicizzati
+  e senza `offset`/`limit` mirati, ricevi un blocco `[outline from code index]`
+  con i simboli e i loro range (max 40, ~3,5% di caratteri in più).
+- **riga di stato** nel footer (`codeindex: 5.2k chunk`, `codeindex: 1.2k/4.8k`
+  durante l'indicizzazione).
+- **`/codeindex status|reindex [--force]|enable|disable|config|configure|doctor`**. `disable` spegne
+  tutto: tool, outline, riga di stato, riga nel system prompt, watcher e
+  indicizzazione in corso. Lo stato è persistito nel branch della sessione;
+  una sessione nuova riparte attiva.
+- **indicizzazione automatica** all'avvio della sessione, in background,
+  single-flight, interrompibile, con cap 5.000 file / 200 MB.
+- **sincronizzazione**: watcher ricorsivo con debounce 800 ms, invalidazione
+  diretta da `write`/`edit` e sweep `git status` dopo `bash`. Una riconciliazione
+  riusa i vettori dei file intatti (misurato: 1 chunk re-embedded su 3 dopo una
+  modifica, 920 ms fino all'indice aggiornato).
+
+Fuori da un repo git l'estensione si disattiva da sola; se il modello non è
+scaricabile o il reindex fallisce, `search_code` risponde con lo stato reale e
+la sessione continua.
+
+## Cosa indicizza
+
+JS/TS/TSX/JSX, Python, Go, Rust, C, C++, C#, PowerBuilder (.srw/.sru/…),
+Markdown. Chunk declaration-aware, con fusione dei chunk piccoli (Markdown fino
+a 80 righe; codice solo micro-chunk ≤6 righe). Esclusi: binari, file >1 MB,
+minified, lockfile, `.pbl`/`.pbt`/`.pbw`.
+
+## Numeri misurati (RTX 5070 Ti, fp16)
+
+| Repo | File | Chunk | Primo indice | Re-index |
+|---|---|---|---|---|
+| `pi.dev-ext` | 373 | 5.230 | 44 s | 169 ms |
+| `Strata` | 2.872 | 29.974 | ~2–5 min | 737 ms |
+
+Su CPU q8 (`pi.dev-ext`): 18m28s il primo indice, 143 ms il secondo.
+Ricerca a indice caldo: p50 32 ms. Recall@3 sulla fixture: 5/8.
+
+Dentro pi: cache in-process dell'indice (stat dei due file come chiave), quindi
+11,5 ms a caldo su `pi.dev-ext` e **40 ms su `Strata`** (30k chunk), contro ~1,2 s
+di caricamento modello alla prima query di un processo nuovo.
+Outline su un file da 3.713 righe: **+3,5% caratteri** sulla read.
+
+## Misura (giro completo)
+
+I file e i comandi di questa sezione si riferiscono al checkout di sviluppo:
+piano, report completi e harness non vengono distribuiti nel pacchetto npm.
+Il riepilogo e i limiti delle misure sono riportati qui senza estenderne lo scope.
+
+`RESULTS.md` riporta l'esperimento A (pi nudo) vs C (pi + indice) su 10 task per
+repo × 3 ripetizioni: mediana dei delta **−25,4% token su `Strata`** e **−9,7% su
+`pi.dev-ext`**, ma costo totale **−12,3%** e **−12,9%**: sotto la soglia del 15%
+del gate primario. Il verdetto è nel file: **gate non superato**, progetto fermo
+per la regola scritta in `PLAN.md`. Il braccio B (OpenLore) non è stato eseguito:
+nessun claim comparativo.
+
+La Fase 6 ha ripetuto la misura con un budget di **80 tool call** per sessione
+(`RESULTS-FASE6.md`): costo **−23,2%** su `Strata` e **−19,2%** su `pi.dev-ext`,
+ma successo **27/30 vs 28/30** su `Strata`. Tutti i fallimenti sono run tagliati
+dal cap; il criterio pre-registrato `C ≥ A` non è soddisfatto per una run, quindi
+quel gate resta non superato.
+
+La Fase 7 (`RESULTS-FASE7.md`, 80 coppie appaiate per repo, ipotesi più debole
+pre-registrata prima dei run) supera il gate che chiede **solo di non spendere
+più**: costo appaiato **−22,1%** su `Strata` (CI unilaterale [−29,3%, −14,1%]) e
+−21,5% su `pi.dev-ext`, successo **74/80 vs 74/80** e 79/80 vs 80/80. La soglia
+del **15%** resta non misurata: quello che è dimostrato è "in sessione con budget
+di 80 tool call il costo non aumenta e il successo non peggiora oltre 10pp".
+
+```bash
+node scripts/experiment.mjs --repo ~/AI-Projects/Strata --repeat 8 \
+  --max-tool-calls 80 --out /tmp/exp5-strata
+node scripts/analyze-experiment.mjs --runs /tmp/exp5-strata --runs /tmp/exp5-pidev
+```
+
+## Limiti noti
+
+- Il chunker è euristico (regex per famiglia): nessun parser AST, nessun
+  call graph. Gli errori di confine sono possibili e non etichettati.
+- I chiamanti del bundle sono euristici (scansione dell'identificatore, non un
+  call graph): su un campione di 61 casi la precisione misurata è 92%. Il livello
+  import è più stretto: solo specifiche che risolvono a un unico file, 29/30 edge
+  senza ambiguità su `Strata`.
+- I documenti di piano Markdown competono con il codice nella ricerca: il cap
+  di 2 risultati per file e il peso maggiore di path/simbolo mitigano, non
+  eliminano il problema.
+- Query in italiano su codice con identificatori inglesi funzionano meno bene
+  delle query in inglese.
+- Device e `dtype` fanno parte dell'identità dei vettori: cambiarli richiede
+  un re-index. Lo storage v2 lega manifest e vettori con SHA-256: anche un
+  salvataggio concorrente/incompleto non viene scambiato per un indice valido.
+  Gli indici vecchi senza digest richiedono ricostruzione. La directory è
+  unica per repo: processi con profili diversi possono sostituirla o renderla
+  temporaneamente indisponibile, mai riutilizzare vettori incompatibili.
+- DirectML e CoreML richiedono ancora smoke test su Windows/macOS; WebGPU è
+  verificato solo sulla macchina Linux disponibile, non su tutte le GPU.
+- I pesi sono ancora scaricati dalla revisione `main` del modello; il cache non
+  viene aggiornato automaticamente. Prima di un rilascio riproducibile occorre
+  fissare uno snapshot dei pesi e verificarne l'integrità.
+
+## Licenza
+
+Il codice di pi-codeindex è distribuito sotto licenza [MIT](LICENSE).
+Dipendenze, sorgenti upstream scaricati dal setup e pesi del modello mantengono
+le rispettive licenze; non sono inclusi nel tarball del pacchetto.

package/config.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "pi-codeindex — configurazione embedding locali",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "device": { "enum": ["auto", "cpu", "cuda", "webgpu", "dml", "coreml"], "default": "auto", "description": "Per Vulkan forzato usa webgpu con webgpuBackend: vulkan. auto prova i provider presenti per piattaforma, poi CPU." },
+    "dtype": { "enum": ["auto", "q8", "q4", "fp16"], "default": "auto", "description": "auto: q8 su CPU, fp16 sugli altri provider. Cambiarlo richiede reindex." },
+    "webgpuBackend": { "enum": ["auto", "vulkan"], "default": "auto", "description": "Backend Dawn quando il provider effettivo è webgpu. vulkan forza Vulkan e richiede setup-vulkan (inizialmente Linux x64). Non influenza CPU/CUDA/DirectML/CoreML." },
+    "fallback": { "enum": ["error", "cpu"], "default": "error", "description": "Fallback consentito per un device forzato; auto include sempre CPU." },
+    "offline": { "type": "boolean", "default": false },
+    "cacheDir": { "type": "string", "minLength": 1, "pattern": "\\S", "description": "Cache dei pesi. Supporta ~/; i percorsi relativi sono risolti dal cwd." },
+    "cpuThreads": { "type": "integer", "minimum": 0, "maximum": 256, "default": 0, "description": "0 usa il default di ONNX Runtime; non limita la GPU." }
+  }
+}

package/eval/queries.jsonl

@@ -0,0 +1,8 @@
+{"query":"dove viene stimato il numero di token BPE di un messaggio","expects":["bpe-token-estimator"],"why":"estimatore token BPE dedicato"}
+{"query":"come viene applicata una modifica ancorata a un file","expects":["anchored-edit"],"why":"motore delle modifiche ancorate"}
+{"query":"ricerca nella history canonica delle sessioni","expects":["history-service","history-source-reader","context-history-tool"],"why":"lettura e ricerca della history"}
+{"query":"coordinamento della compaction tra più sessioni","expects":["compaction-coordinator"],"why":"coordinatore della compaction"}
+{"query":"lock per evitare rebase concorrenti di una sessione","expects":["rebase-lock"],"why":"lock di rebase"}
+{"query":"quali artefatti vengono conservati e per quanto tempo","expects":["ARTIFACTS.md","artifacts"],"why":"documentazione sugli artefatti"}
+{"query":"marker di omissione per non riesportare dati già visti","expects":["egress"],"why":"gestione egress e marker di omissione"}
+{"query":"indicizzazione incrementale delle sessioni salvate","expects":["session-indexer"],"why":"indice incrementale delle sessioni"}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@alucard_24/pi-codeindex",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "Indice semantico locale del codice per pi (EmbeddingGemma 2, ONNX)",
+  "license": "MIT",
+  "author": "Alucard24",
+  "repository": { "type": "git", "url": "git+https://github.com/Alucard24/pi-codeindex.git" },
+  "homepage": "https://www.npmjs.com/package/@alucard_24/pi-codeindex",
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "main": "./src/extension.js",
+  "bin": { "pi-codeindex": "src/cli.js" },
+  "files": ["src", "scripts/setup-gpu.sh", "scripts/setup-vulkan.mjs", "scripts/vulkan-sources.json", "eval/queries.jsonl", "config.schema.json", "README.md", "LICENSE"],
+  "engines": { "node": ">=22" },
+  "scripts": {
+    "test": "node --test 'test/*.test.js'",
+    "embed-test": "node src/cli.js embed-test",
+    "setup-gpu": "bash scripts/setup-gpu.sh",
+    "setup-vulkan": "node scripts/setup-vulkan.mjs",
+    "doctor": "node src/cli.js doctor"
+  },
+  "keywords": ["pi-package", "embeddings", "code-search"],
+  "type": "module",
+  "pi": {
+    "extensions": [
+      "./src/extension.js"
+    ]
+  },
+  "dependencies": {
+    "@huggingface/transformers": "4.3.2",
+    "onnxruntime-node": "1.30.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  }
 }

package/scripts/setup-gpu.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Abilita il provider CUDA di onnxruntime-node (Linux x64, GPU NVIDIA).
+#
+# 1. scarica i binari del provider CUDA se mancano (script ufficiale ORT);
+# 2. trova le librerie CUDA 13 richieste dal provider 1.30 (libcublasLt.so.13,
+#    libcudart.so.13, libcurand.so.10, ...);
+# 3. scrive un RUNPATH nel .so del provider: così la GPU funziona senza
+#    esportare LD_LIBRARY_PATH (necessario perché l'estensione pi gira
+#    dentro un processo già avviato).
+#
+# Idempotente. Da rieseguire dopo `npm install` (node_modules viene ricreato).
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+if ! node -e 'process.exit(process.platform === "linux" && process.arch === "x64" ? 0 : 1)'; then
+  echo "[gpu] setup CUDA disponibile solo su Linux x64; usa doctor per i backend della tua piattaforma." >&2
+  exit 1
+fi
+# Funziona anche con dipendenze npm hoisted, non solo con node_modules locale.
+ORT="$(node --input-type=module - "$ROOT/package.json" <<'JS'
+import { createRequire } from 'node:module';
+import path from 'node:path';
+console.log(path.dirname(createRequire(process.argv[2]).resolve('onnxruntime-node/package.json')));
+JS
+)"
+PROVIDER="$(find "$ORT/bin" -path '*/linux/x64/libonnxruntime_providers_cuda.so' | head -1 || true)"
+BIN_DIR="$(dirname "${PROVIDER:-$ORT/bin/napi-v6/linux/x64/x}")"
+
+if [[ ! -f "$PROVIDER" ]]; then
+  echo "[gpu] provider CUDA assente: lo scarico (≈270 MB)…"
+  node "$ORT/script/install.js" --onnxruntime-node-install=cuda12
+  PROVIDER="$BIN_DIR/libonnxruntime_providers_cuda.so"
+fi
+
+find_cuda_lib() {
+  local d
+  for d in \
+    "${CUDA13_LIB:-}" \
+    "$HOME"/.local/cuda-13*/targets/*/lib \
+    /usr/local/cuda-13*/targets/*/lib \
+    /usr/local/cuda/lib64 \
+    "$HOME"/.local/venv-cu13/lib/python*/site-packages/nvidia/cu13/lib \
+    /opt/cuda/lib64; do
+    [[ -n "$d" && -e "$d/libcublasLt.so.13" ]] && { echo "$d"; return 0; }
+  done
+  return 1
+}
+
+CUDA_LIB="$(find_cuda_lib || true)"
+if [[ -z "$CUDA_LIB" ]]; then
+  echo "[gpu] ERRORE: non trovo libcublasLt.so.13 (serve il runtime CUDA 13)." >&2
+  echo "      Installa CUDA 13 o imposta CUDA13_LIB=/percorso/lib." >&2
+  exit 1
+fi
+
+command -v patchelf >/dev/null || { echo "[gpu] ERRORE: patchelf non installato." >&2; exit 1; }
+
+echo "[gpu] CUDA libs: $CUDA_LIB"
+patchelf --set-rpath "$CUDA_LIB" "$PROVIDER"
+if LD_LIBRARY_PATH= ldd "$PROVIDER" | grep -q "not found"; then
+  echo "[gpu] ERRORE: dipendenze non risolte:" >&2
+  LD_LIBRARY_PATH= ldd "$PROVIDER" | grep "not found" >&2
+  exit 1
+fi
+echo "[gpu] ok: provider CUDA pronto (nessun LD_LIBRARY_PATH richiesto)"

package/scripts/setup-vulkan.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+// Setup esplicito, nessun postinstall. Compila solo il binding Node, non ORT/Dawn.
+// Sorgenti MIT upstream fissati; copia ORT privata con SONAME distinto, senza
+// toccare node_modules o il contesto WebGPU di altre estensioni.
+import fs from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { ORT_VERSION, ORT_SOURCE, VULKAN_REVISION, fileHash, ortLibrary, vulkanCacheDir,
+  vulkanStatus, verifyVulkanArtifacts } from '../src/vulkan.js';
+
+const require = createRequire(import.meta.url);
+const ADDON_URL = 'https://registry.npmjs.org/node-addon-api/-/node-addon-api-6.1.0.tgz';
+const ADDON_INTEGRITY = '+eawOlIgy680F0kBzPUNFhMZGtJ1YmqM6l4+Crf4IkImjYrO/mqPwRMh352g23uIaQKFItcQ64I7KMaJxHgAVA==';
+
+export function patchBindingSource(source) {
+  const anchor = 'if (name == "preferredLayout" ||';
+  if (source.split(anchor).length !== 2) throw new Error('patch Vulkan: sorgente upstream inatteso');
+  return source.replace(anchor, 'if (name == "dawnBackendType" ||\n              name == "preferredLayout" ||');
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, { stdio: 'inherit', timeout: 180_000, ...options });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`${command} terminato con ${result.signal ?? result.status}`);
+}
+async function download(url) {
+  const response = await fetch(url, { signal: AbortSignal.timeout(60_000) });
+  if (!response.ok) throw new Error(`download ${response.status}: ${url}`);
+  return Buffer.from(await response.arrayBuffer());
+}
+
+export async function setupVulkan(args = []) {
+  let headers, force = false;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--force') force = true;
+    else if (args[i] === '--node-headers' && args[i + 1] && !args[i + 1].startsWith('--')) headers = path.resolve(args[++i]);
+    else throw new Error('uso: setup-vulkan [--force] [--node-headers DIR]');
+  }
+  if (process.platform !== 'linux' || process.arch !== 'x64') throw new Error('setup-vulkan inizialmente disponibile solo su Linux x64; Windows/macOS non verificati');
+  if (require('onnxruntime-node/package.json').version !== ORT_VERSION) throw new Error(`setup-vulkan richiede onnxruntime-node ${ORT_VERSION}`);
+  if (!force) {
+    const status = vulkanStatus();
+    if (status.available) {
+      try { await verifyVulkanArtifacts(status); console.log(`Vulkan: binding già pronto in ${status.dir}`); return; }
+      catch (e) { console.log(e.message); }
+    }
+  }
+  const compiler = process.env.CXX || 'c++';
+  run(compiler, ['--version'], { stdio: 'ignore' });
+  run('patchelf', ['--version'], { stdio: 'ignore' });
+  run('tar', ['--version'], { stdio: 'ignore' });
+  headers ??= [path.resolve(path.dirname(process.execPath), '../include/node'), '/usr/include/node']
+    .find((dir) => existsSync(path.join(dir, 'node_api.h')));
+  if (!headers || !existsSync(path.join(headers, 'node_api.h'))) throw new Error('header Node mancanti: installa gli header di sviluppo o usa --node-headers DIR');
+
+  const dir = vulkanCacheDir();
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+  const work = await fs.mkdtemp(path.join(dir, '.build-'));
+  try {
+    const sourceManifest = JSON.parse(await fs.readFile(new URL('./vulkan-sources.json', import.meta.url), 'utf8'));
+    if (sourceManifest.revision !== ORT_SOURCE) throw new Error('revision sorgenti Vulkan incoerente');
+    console.log(`Vulkan: sorgenti ORT ${ORT_VERSION} @ ${ORT_SOURCE.slice(0, 12)} (hash Git verificati)`);
+    const sourceDir = path.join(work, 'source');
+    const entries = Object.entries(sourceManifest.files);
+    // Download limitato: solo binding e header pubblici, niente clone del repository.
+    for (let i = 0; i < entries.length; i += 4) await Promise.all(entries.slice(i, i + 4).map(async ([file, expected]) => {
+      const bytes = await download(`https://raw.githubusercontent.com/microsoft/onnxruntime/${ORT_SOURCE}/${file}`);
+      const actual = createHash('sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
+      if (actual !== expected) throw new Error(`hash sorgente inatteso: ${file}`);
+      const dest = path.join(sourceDir, file);
+      await fs.mkdir(path.dirname(dest), { recursive: true });
+      await fs.writeFile(dest, bytes);
+    }));
+    const helper = path.join(sourceDir, 'js/node/src/session_options_helper.cc');
+    await fs.writeFile(helper, patchBindingSource(await fs.readFile(helper, 'utf8')));
+    const tarball = await download(ADDON_URL);
+    if (createHash('sha512').update(tarball).digest('base64') !== ADDON_INTEGRITY) throw new Error('integrità node-addon-api non valida');
+    const archive = path.join(work, 'addon-api.tgz');
+    await fs.writeFile(archive, tarball);
+    const addonDir = path.join(work, 'addon-api');
+    await fs.mkdir(addonDir);
+    run('tar', ['-xzf', archive, '--strip-components=1', '-C', addonDir]);
+
+    const out = path.join(work, 'artifact');
+    await fs.mkdir(out);
+    const sourceLibraryHash = await fileHash(ortLibrary());
+    const library = `libpi-codeindex-ort-vulkan-${sourceLibraryHash.slice(0, 16)}.so.1`;
+    const libraryFile = path.join(out, library);
+    await fs.copyFile(ortLibrary(), libraryFile);
+    run('patchelf', ['--set-soname', library, libraryFile]);
+    const nodeDir = path.join(sourceDir, 'js/node/src');
+    const cpp = (await fs.readdir(nodeDir)).filter((f) => f.endsWith('.cc')).sort().map((f) => path.join(nodeDir, f));
+    console.log('Vulkan: compilazione binding isolato (C++/N-API 6), runtime precompilato riutilizzato');
+    const bindingFile = path.join(out, 'onnxruntime_binding.node');
+    run(compiler, ['-shared', '-fPIC', '-fvisibility=hidden', '-fvisibility-inlines-hidden', '-std=c++17', '-O2',
+      '-DNAPI_VERSION=6', '-DUSE_WEBGPU', '-DNAPI_CPP_EXCEPTIONS', '-DORT_API_MANUAL_INIT',
+      `-I${headers}`, `-I${addonDir}`, `-I${path.join(sourceDir, 'include/onnxruntime')}`,
+      `-I${path.join(sourceDir, 'include/onnxruntime/core/session')}`, ...cpp,
+      `-L${out}`, `-l:${library}`, '-Wl,-rpath,$ORIGIN', '-o', bindingFile]);
+    await fs.copyFile(path.join(sourceDir, 'LICENSE'), path.join(out, 'LICENSE-onnxruntime'));
+    await fs.copyFile(path.join(addonDir, 'LICENSE.md'), path.join(out, 'LICENSE-node-addon-api'));
+    // Il controllo negativo non richiede GPU o pesi. Nuovo processo, nessun
+    // addon tenuto aperto durante la pubblicazione degli artefatti.
+    const moduleUrl = new URL('../src/vulkan.js', import.meta.url).href;
+    run(process.execPath, ['--input-type=module', '-e', `
+      import { createRequire } from 'node:module';
+      import { assertVulkanSelector } from ${JSON.stringify(moduleUrl)};
+      process.env.ORT_DISABLE_TELEMETRY = '1';
+      const req = createRequire(${JSON.stringify(import.meta.url)});
+      const ort = req('onnxruntime-node');
+      const binding = req(${JSON.stringify(bindingFile)});
+      binding.initOrtOnce(2, ort.Tensor, true);
+      assertVulkanSelector(binding);
+      console.log('Vulkan: controllo negativo del selettore superato');
+    `]);
+    const bindingHash = await fileHash(bindingFile);
+    const libraryHash = await fileHash(libraryFile);
+    // Directory nuova ad ogni build: non riusare/sovrascrivere artefatti
+    // corrotti o ancora mappati da un altro processo. Il manifest si pubblica ultimo.
+    const artifact = createHash('sha256').update(bindingHash + libraryHash + randomUUID()).digest('hex');
+    const target = path.join(dir, artifact);
+    await fs.rename(out, target);
+    const manifest = { runtimeVersion: ORT_VERSION, sourceRevision: ORT_SOURCE, revision: VULKAN_REVISION,
+      platform: process.platform, arch: process.arch, artifact, library, sourceLibraryHash, bindingHash, libraryHash };
+    const tmp = path.join(dir, `manifest.${randomUUID()}.tmp`);
+    try {
+      await fs.writeFile(tmp, JSON.stringify(manifest, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+      await fs.rename(tmp, path.join(dir, 'manifest.json'));
+    } finally { await fs.rm(tmp, { force: true }); }
+    console.log(`Vulkan: installato in ${target}\nNessun file in node_modules modificato. Riavvia pi se già aperto. Ora esegui doctor --probe --device webgpu --webgpu-backend vulkan.`);
+  } finally { await fs.rm(work, { recursive: true, force: true }); }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  setupVulkan(process.argv.slice(2)).catch((e) => { console.error(`setup-vulkan: ${e.message}`); process.exitCode = 1; });
+}