@antodevs/groundtruth 0.2.4 → 0.2.6

package/README.md

@@ -41,12 +41,14 @@ Current-generation AI coding assistants (Claude Code, Antigravity, Cursor) suffe
 
 **GroundTruth** acts as a transparent middleware layer that resolves this by dynamically injecting real-time, stack-specific documentation directly into the agent's context window prior to inference.
 
-### The v0.2.0 Engine: Jina Reader & Source Registry
+### The v0.2 Engine: Global Cloud Intelligence
+
+GroundTruth v0.2 introduces a paradigm shift in context quality and scalability:
+- **Global Cloud Registry**: Bypasses search engines by querying a high-performance **Cloudflare Worker** registry. It covers the top ~200 frameworks with "Golden List" manual precision and over **10,000+ npm packages** via automated background indexing.
+- **Jina Reader API Integration**: Seamlessly parses dynamic, JavaScript-rendered SPAs (like Vercel AI SDK, Next.js, and Svelte docs) into clean, LLM-optimized Markdown.
+- **Automated "Gentle" Indexer**: A remote bot periodically synchronizes the latest documentation URLs from the npm ecosystem directly to the cloud registry, ensuring your context is never stale.
+- **Zero-Config Resilience**: Operates locally with a strictly enforced 1.5s cloud timeout. If the registry is unreachable, it silently falls back to local Readability extraction or search.
 
-GroundTruth v0.2.0 introduces a massive upgrade to content quality:
-- **Jina Reader API Integration**: Parses dynamic, JavaScript-rendered SPAs (like Vercel AI SDK, Next.js, and Svelte docs) into clean, LLM-optimized Markdown.
-- **Smart Source Registry**: Automatically bypasses search engines for the top 20+ frameworks (React, Svelte, Vue, Astro, etc.) and fetches their official documentation directly. 
-- **Readability Fallback**: Ensures reliable extraction even if the primary engine fails.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antodevs/groundtruth",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Lightweight Node.js proxy to intercept API requests from coding agents and inject fresh web context",
   "publishConfig": {
     "access": "public"
@@ -44,10 +44,9 @@
     "release:minor": "git add . && git commit -m \"chore: auto-commit before release\" || true && npm version minor && git push origin main --tags && npm publish"
   },
   "dependencies": {
-    "@mozilla/readability": "^0.5.0",
+    "@mozilla/readability": "^0.6.0",
     "chalk": "^5.3.0",
-    "cheerio": "^1.0.0",
-    "linkedom": "^0.18.12",
-    "node-fetch": "^3.3.2"
+    "cheerio": "^1.2.0",
+    "linkedom": "^0.18.12"
   }
 }

package/src/registry.js

@@ -2,7 +2,6 @@
  * @module registry
  * @description Interroga il Cloudflare Worker (Remote Registry) per risolvere URL docs ufficiali.
  */
-import fetch from 'node-fetch';
 
 const REGISTRY_API_URL = 'https://groundtruth-registry.antony-flex01.workers.dev/lookup';
 
@@ -18,7 +17,11 @@ export async function lookupRegistryUrl(depName) {
     if (!depName) return null;
 
     // Normalizzazione preventiva
-    const name = depName.split(' ')[0].toLowerCase().trim();
+    let name = depName.split(' ')[0].toLowerCase().trim();
+
+    // Alias mapping per framework comuni con scope npm
+    if (name === '@sveltejs/kit') name = 'sveltekit';
+
 
     // Check hit in memoria (ritorna subito)
     if (lookupCache.has(name)) {

package/src/sanitize.js

@@ -19,17 +19,56 @@ const DANGEROUS_PATTERNS = [
     /HUMAN:\s/gi,
 ];
 
+const NOISE_PATTERNS = [
+    /Skip to content/gi,
+    /Navigation Menu/gi,
+    /Toggle navigation/gi,
+    /Appearance settings/gi,
+    /AI CODE CREATION/gi,
+    /GitHub Copilot Write better code with AI/gi,
+    /Sign in/gi,
+    /Sign up/gi,
+    /Notifications/gi,
+    /Fork\s+\d+/gi,
+    /Star\s+[\d.]+[kK]?/gi,
+    /Code/gi,
+    /Issues/gi,
+    /Pull requests/gi,
+    /Actions/gi,
+    /Projects/gi,
+    /Security/gi,
+    /Insights/gi,
+    /Why GitHub/gi,
+    /Solutions/gi,
+    /Resources/gi,
+    /Open Source/gi,
+    /Enterprises/gi,
+    /Startups/gi,
+];
+
 /**
- * @description Filtra pattern pericolosi di prompt injection dal testo web scrappato.
+ * @description Filtra pattern pericolosi e rumore di navigazione dal testo web scrappato.
  * @param   {string} text - Testo raw proveniente da web scraping
  * @param   {number} maxLen - Lunghezza massima output (default 8000)
  * @returns {string} Testo sanitizzato
  */
 export function sanitizeWebContent(text, maxLen = 8000) {
     if (!text || typeof text !== 'string') return '';
+
     let cleaned = text;
+
+    // 1. Rimuoviamo il rumore di navigazione
+    for (const pattern of NOISE_PATTERNS) {
+        cleaned = cleaned.replace(pattern, '');
+    }
+
+    // 2. Rimuoviamo pattern pericolosi
     for (const p of DANGEROUS_PATTERNS) {
         cleaned = cleaned.replace(p, '[FILTERED]');
     }
+
+    // 3. Normalizzazione spazi bianchi per risparmiare token
+    cleaned = cleaned.replace(/\s+/g, ' ').trim();
+
     return cleaned.slice(0, maxLen);
 }

package/src/search.js

@@ -2,7 +2,6 @@
  * @module search
  * @description Logica di scraping web: Jina Reader → fallback Readability, registry bypass, DDG search.
  */
-import fetch from 'node-fetch';
 import * as cheerio from 'cheerio';
 import { Readability } from '@mozilla/readability';
 import { DOMParser } from 'linkedom';
@@ -59,8 +58,7 @@ export async function fetchPageContent(url, userAgent, opts = {}) {
     try {
         const pageRes = await fetch(url, {
             signal: AbortSignal.timeout(5000),
-            headers: { 'User-Agent': userAgent },
-            agent: url.startsWith('https:') ? httpsAgent : httpAgent
+            headers: { 'User-Agent': userAgent }
         });
         if (pageRes.ok) {
             const document = new DOMParser().parseFromString(await pageRes.text(), 'text/html');
@@ -142,7 +140,7 @@ async function doSearch(query, resultsLimit = 3) {
     const userAgent = getRandomUA();
     const searchRes = await fetch(
         `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`,
-        { signal: AbortSignal.timeout(5000), headers: { 'User-Agent': userAgent }, agent: httpsAgent }
+        { signal: AbortSignal.timeout(5000), headers: { 'User-Agent': userAgent } }
     );
     if (!searchRes.ok) throw new Error(`DDG ${searchRes.status}`);
 

package/src/state.js

@@ -13,26 +13,39 @@ const STATE_FILE = path.join(STATE_DIR, 'watcher-state.json');
 
 /**
  * @description Carica gli hash validati e memorizzati dallo schedule storage locale.
- * @returns {Promise<Map>} Restituisce le hash map entries persistite del cron logic stream precedente.
+ * @param {string} currentVersion - Versione attuale dell'applicazione per validare la cache.
+ * @returns {Promise<Map>} Restituisce le hash map entries persistite o una mappa vuota se la versione differisce.
  */
-export async function loadBatchState() {
+export async function loadBatchState(currentVersion) {
     try {
         if (!existsSync(STATE_FILE)) return new Map();
         const data = await readFile(STATE_FILE, 'utf8');
-        const parsed = JSON.parse(data);
-        return new Map(Object.entries(parsed));
+        const state = JSON.parse(data);
+
+        // Invalida la cache se la versione è differente (forza refresh dopo update)
+        if (state.version !== currentVersion) {
+            return new Map();
+        }
+
+        return new Map(Object.entries(state.hashes || {}));
     } catch {
         return new Map();
     }
 }
 
 /**
- * @description Sincronizza hash batches per fault tolerance cross process
- * @param {Map} map - Oggetto dei blocchi hashati validi in mem persist state map
+ * @description Sincronizza hash batches e versione per fault tolerance cross process.
+ * @param {Map} map - Oggetto dei blocchi hashati validi.
+ * @param {string} version - Versione attuale dell'applicazione.
  * @returns {Promise<void>} 
  */
-export async function saveBatchState(map) {
+export async function saveBatchState(map, version) {
     await mkdir(STATE_DIR, { recursive: true });
-    const obj = Object.fromEntries(map);
-    await atomicWrite(STATE_FILE, JSON.stringify(obj, null, 2), { backup: false });
+    const state = {
+        version: version,
+        updatedAt: new Date().toISOString(),
+        hashes: Object.fromEntries(map)
+    };
+    await atomicWrite(STATE_FILE, JSON.stringify(state, null, 2), { backup: false });
 }
+

package/src/watcher.js

@@ -52,7 +52,7 @@ export function startWatcher({ intervalMinutes, usePackageJson, batchSize }) {
 
     async function updateSkill() {
         if (previousBatchHashes.size === 0) {
-            previousBatchHashes = await loadBatchState();
+            previousBatchHashes = await loadBatchState(version);
         }
         const deps = await readPackageDeps();
         if (!deps || deps.length === 0) {
@@ -193,7 +193,7 @@ export function startWatcher({ intervalMinutes, usePackageJson, batchSize }) {
         await removeStaleBlocks(globalPath, activeBlockIds);
         await removeStaleBlocks(workspacePath, activeBlockIds);
 
-        await saveBatchState(previousBatchHashes);
+        await saveBatchState(previousBatchHashes, version);
 
         log(LOG_REFRESH, chalk.gray, `cycle done → ${activeBlockIds.size} blocks active, ${updatedCount} updated, ${skippedCount} skipped, ${failedCount} errors`);
     }
@@ -201,7 +201,7 @@ export function startWatcher({ intervalMinutes, usePackageJson, batchSize }) {
     let cycleCount = 0;
 
     process.on('SIGINT', async () => {
-        await saveBatchState(previousBatchHashes);
+        await saveBatchState(previousBatchHashes, version);
         process.exit(0);
     });