@bedolla/enriweb 0.1.5 → 0.1.7

package/dist/tools/WebSearchRegistryVerifier.js

@@ -1,15 +1,38 @@
+import { WebSearchRegistryHttpReader } from "./WebSearchRegistryHttpReader.js";
+import { sliceUtf8Safe } from "../shared/Utf8SafeTextSlicer.js";
 /**
  * Enriches web search results with registry version verification.
  */
 export class WebSearchRegistryVerifier {
+    /**
+     * Capped JSON HTTP reader owning the registry transport concerns.
+     */
+    httpReader;
     /**
      * NuGet V3 service index endpoint.
      */
     static NUGET_SERVICE_INDEX_URL = "https://api.nuget.org/v3/index.json";
+    /**
+     * Maximum bytes read from one npm packument (full-version manifest).
+     *
+     * @remarks
+     * Popular packages legitimately exceed the shared 5 MB registry cap
+     * (thousands of versions with full metadata); parity with the EnriCode
+     * client plane's 16 MiB download budget for the same endpoint.
+     */
+    static NPM_PACKUMENT_MAX_BYTES = 16_777_216;
     /**
      * Default concurrency for registry verification.
      */
     static DEFAULT_CONCURRENCY = 3;
+    /**
+     * Time one cached error entity stays fresh before a retry.
+     */
+    static ERROR_CACHE_TTL_MS = 60 * 1000;
+    /**
+     * Maximum cached verification entries (LRU eviction beyond this count).
+     */
+    static MAX_CACHE_ENTRIES = 200;
     /**
      * Dependencies.
      */
@@ -18,6 +41,16 @@ export class WebSearchRegistryVerifier {
      * In-memory TTL cache.
      */
     cache;
+    /**
+     * In-flight verification promises keyed by cache key.
+     *
+     * @remarks
+     * Single-flight coalescing: concurrent MCP requests verifying the same
+     * entity join one registry fetch instead of racing duplicates. Entries
+     * are removed when the verification settles (success, error or caller
+     * abort), so the map never outlives its requests.
+     */
+    inFlight = new Map();
     /**
      * Cached NuGet service index resolution.
      */
@@ -28,6 +61,10 @@ export class WebSearchRegistryVerifier {
      * @param deps - Dependencies
      */
     constructor(deps) {
+        this.httpReader = new WebSearchRegistryHttpReader({
+            fetchImpl: deps.fetchImpl,
+            timeoutMs: deps.timeoutMs
+        });
         this.deps = deps;
         this.cache = new Map();
         this.nugetServiceIndexCache = null;
@@ -36,17 +73,38 @@ export class WebSearchRegistryVerifier {
      * Attempts to verify canonical versions for registry entities found in search results.
      *
      * @param results - Search results
+     * @param signal - Optional caller abort signal (stops queueing new verifications)
      * @returns Verified entities (best-effort)
      */
-    async verifyFromSearchResults(results) {
-        const candidates = this.collectCandidates(results);
+    async verifyFromSearchResults(results, signal) {
+        if (signal?.aborted) {
+            return [];
+        }
+        // A non-array `results` payload (proxy shape drift) carries no
+        // candidates; it must degrade to unverified instead of throwing
+        // "results is not iterable" into the tool result.
+        const entries = Array.isArray(results) ? results : [];
+        const candidates = this.collectCandidates(entries);
         if (candidates.length === 0) {
             return [];
         }
         const tasks = candidates.map((candidate) => async () => {
-            return await this.verifyCandidate(candidate.kind, candidate.name);
+            if (signal?.aborted) {
+                throw new Error("Verificación cancelada por el cliente.");
+            }
+            return await this.verifyCandidate(candidate.kind, candidate.name, signal);
         });
-        return await this.runWithConcurrencyLimit(tasks, WebSearchRegistryVerifier.DEFAULT_CONCURRENCY);
+        try {
+            return await this.runWithConcurrencyLimit(tasks, WebSearchRegistryVerifier.DEFAULT_CONCURRENCY);
+        }
+        catch (error) {
+            // Cancellation must degrade to unverified results, never fail the search
+            // whose results already succeeded.
+            if (signal?.aborted) {
+                return [];
+            }
+            throw error;
+        }
     }
     /**
      * Collects registry candidates from search result URLs.
@@ -58,9 +116,12 @@ export class WebSearchRegistryVerifier {
         const unique = new Set();
         const candidates = [];
         for (const entry of results) {
-            if (!entry.url || candidates.length >= this.deps.maxEntitiesPerCall) {
+            if (candidates.length >= this.deps.maxEntitiesPerCall) {
                 break;
             }
+            if (!entry.url) {
+                continue;
+            }
             let parsedUrl;
             try {
                 parsedUrl = new URL(entry.url);
@@ -116,44 +177,146 @@ export class WebSearchRegistryVerifier {
         }
         return candidates;
     }
+    /**
+     * Maximum `releases` pages followed per GitHub verification.
+     */
+    static GITHUB_RELEASES_MAX_PAGES = 3;
     /**
      * Verifies a single candidate, using cache when available.
      *
      * @param kind - Registry kind
      * @param name - Candidate name
+     * @param signal - Optional caller abort signal forwarded to registry fetches
      * @returns Verification result
      */
-    async verifyCandidate(kind, name) {
+    async verifyCandidate(kind, name, signal) {
         const cacheKey = `${kind}:${name.toLowerCase()}`;
         const nowMs = Date.now();
         const cached = this.cache.get(cacheKey);
         if (cached && cached.expiresAtMs > nowMs) {
+            // LRU semantics: `Map.set` on an existing key updates the value
+            // WITHOUT moving the insertion-order record (ECMAScript spec), so a
+            // true recency refresh requires delete-then-set; otherwise eviction
+            // below stays FIFO and evicts hot entries inserted early.
+            this.cache.delete(cacheKey);
+            this.cache.set(cacheKey, cached);
             return cached.value;
         }
-        let value;
-        try {
-            if (kind === "npm") {
-                value = await this.verifyNpm(name);
+        // Single-flight: concurrent MCP requests verifying the same entity
+        // join the in-flight promise instead of racing duplicate registry
+        // fetches (GitHub unauthenticated quota is 60 req/h per IP).
+        const inFlight = this.inFlight.get(cacheKey);
+        if (inFlight !== undefined) {
+            return await inFlight;
+        }
+        const verification = (async () => {
+            let value;
+            try {
+                if (kind === "npm") {
+                    value = await this.verifyNpm(name, signal);
+                }
+                else if (kind === "pypi") {
+                    value = await this.verifyPyPi(name, signal);
+                }
+                else if (kind === "crates") {
+                    value = await this.verifyCrates(name, signal);
+                }
+                else if (kind === "nuget") {
+                    value = await this.verifyNuGet(name, signal);
+                }
+                else {
+                    value = await this.verifyGitHub(name, signal);
+                }
             }
-            else if (kind === "pypi") {
-                value = await this.verifyPyPi(name);
+            catch (error) {
+                // Map transport noise to stable Spanish before caching so error
+                // entities never carry raw undici English strings downstream.
+                value = {
+                    kind,
+                    name,
+                    status: "error",
+                    error: WebSearchRegistryVerifier.describeFetchError(error)
+                };
+                // Caller cancellations are not transient registry failures: caching
+                // them would poison the next search with "Operación cancelada…" rows,
+                // so the entity is returned uncached and re-verified on the next call.
+                if (WebSearchRegistryVerifier.isCallerCancellation(error, signal)) {
+                    return value;
+                }
             }
-            else if (kind === "crates") {
-                value = await this.verifyCrates(name);
+            const ttlMs = value.status === "error" ? WebSearchRegistryVerifier.ERROR_CACHE_TTL_MS : this.deps.cacheTtlMs;
+            this.cache.delete(cacheKey);
+            this.cache.set(cacheKey, { value, expiresAtMs: nowMs + ttlMs });
+            while (this.cache.size > WebSearchRegistryVerifier.MAX_CACHE_ENTRIES) {
+                const oldestKey = this.cache.keys().next().value;
+                if (oldestKey === undefined) {
+                    break;
+                }
+                this.cache.delete(oldestKey);
             }
-            else if (kind === "nuget") {
-                value = await this.verifyNuGet(name);
+            return value;
+        })();
+        this.inFlight.set(cacheKey, verification);
+        try {
+            return await verification;
+        }
+        finally {
+            this.inFlight.delete(cacheKey);
+        }
+    }
+    /**
+     * Reports whether one failure is a caller cancellation.
+     *
+     * @remarks
+     * Internal subfetch timeouts are reclassified as `TimeoutError` upstream
+     * and stay cacheable like any transient error; only genuine caller aborts
+     * (or errors shaped like one, e.g. a Spanish "cancelada" message) skip
+     * the error cache.
+     *
+     * @param error - Failure from a registry fetch.
+     * @param signal - Caller abort signal threaded into the verification.
+     * @returns True for caller cancellations.
+     */
+    static isCallerCancellation(error, signal) {
+        if (signal?.aborted) {
+            return true;
+        }
+        if (error instanceof Error) {
+            if (error.name === "TimeoutError" || /timeout|timed out|ETIMEDOUT/iu.test(error.message)) {
+                return false;
             }
-            else {
-                value = await this.verifyGitHub(name);
+            if (error.name === "AbortError" || /abort|cancelad/iu.test(error.message)) {
+                return true;
             }
         }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            value = { kind, name, status: "error", error: message };
+        return false;
+    }
+    /**
+     * Maps transport failures to stable Spanish text.
+     *
+     * @param error - Failure from a registry fetch.
+     * @returns Spanish description for the cached error entity.
+     */
+    static describeFetchError(error) {
+        if (error instanceof Error) {
+            const name = error.name;
+            const message = error.message;
+            if (name === "TimeoutError" || /timeout|timed out|ETIMEDOUT/iu.test(message)) {
+                return "Tiempo de espera agotado al consultar el registro; se reintentará en la próxima búsqueda.";
+            }
+            if (name === "AbortError" || /abort|cancelad/iu.test(message)) {
+                return "Operación cancelada antes de completar la verificación del registro.";
+            }
+            // Unknown failures (undici transport errors are English by nature,
+            // e.g. "fetch failed", "ENOTFOUND", "ECONNRESET") never reach the
+            // model raw: they are wrapped in a bounded Spanish note so
+            // `verified[].error` stays model-facing Spanish with a short
+            // technical tail.
+            const bounded = sliceUtf8Safe(message.replace(/\s+/gu, " ").trim(), 0, 120);
+            return `Fallo de red al consultar el registro (${bounded.length > 0 ? bounded : "sin detalle"}).`;
         }
-        this.cache.set(cacheKey, { value, expiresAtMs: nowMs + this.deps.cacheTtlMs });
-        return value;
+        const boundedRaw = sliceUtf8Safe(String(error).replace(/\s+/gu, " ").trim(), 0, 120);
+        return `Fallo de red al consultar el registro (${boundedRaw.length > 0 ? boundedRaw : "sin detalle"}).`;
     }
     /**
      * Runs tasks with a fixed concurrency limit.
@@ -188,15 +351,23 @@ export class WebSearchRegistryVerifier {
      * Verifies npm package versions via the npm registry.
      *
      * @param packageName - npm package name (may be scoped)
+     * @param signal - Optional caller abort signal
      * @returns Verified registry entity
      */
-    async verifyNpm(packageName) {
+    async verifyNpm(packageName, signal) {
         const encoded = encodeURIComponent(packageName);
         const sourceUrl = `https://registry.npmjs.org/${encoded}`;
-        const bodyRaw = await this.fetchJson(sourceUrl, { accept: "application/json" });
-        const body = this.tryGetRecord(bodyRaw);
+        // Popular packuments (full metadata for thousands of versions) exceed the
+        // default 5 MB cap; parity with the EnriCode client plane, which reads
+        // the same packument endpoint with a 16 MiB budget.
+        const bodyRaw = await this.httpReader.fetchJson(sourceUrl, {
+            accept: "application/json",
+            signal,
+            maxBytes: WebSearchRegistryVerifier.NPM_PACKUMENT_MAX_BYTES
+        });
+        const body = this.tryGetRecord(bodyRaw.value);
         if (!body) {
-            throw new Error(`Unexpected npm registry response for ${sourceUrl}`);
+            throw new Error(`Respuesta npm inesperada para ${sourceUrl}`);
         }
         const distTags = this.tryGetRecord(body["dist-tags"]);
         const versionsRecord = this.tryGetRecord(body["versions"]);
@@ -233,15 +404,16 @@ export class WebSearchRegistryVerifier {
      * Verifies PyPI project versions via the PyPI JSON API.
      *
      * @param projectName - PyPI project name
+     * @param signal - Optional caller abort signal
      * @returns Verified registry entity
      */
-    async verifyPyPi(projectName) {
+    async verifyPyPi(projectName, signal) {
         const encoded = encodeURIComponent(projectName);
         const sourceUrl = `https://pypi.org/pypi/${encoded}/json`;
-        const bodyRaw = await this.fetchJson(sourceUrl, { accept: "application/json" });
-        const body = this.tryGetRecord(bodyRaw);
+        const bodyRaw = await this.httpReader.fetchJson(sourceUrl, { accept: "application/json", signal });
+        const body = this.tryGetRecord(bodyRaw.value);
         if (!body) {
-            throw new Error(`Unexpected PyPI response for ${sourceUrl}`);
+            throw new Error(`Respuesta PyPI inesperada para ${sourceUrl}`);
         }
         const releases = this.tryGetRecord(body["releases"]);
         const candidates = [];
@@ -272,15 +444,16 @@ export class WebSearchRegistryVerifier {
      * Verifies crates.io package versions via the crates.io API.
      *
      * @param crateName - Crate name
+     * @param signal - Optional caller abort signal
      * @returns Verified registry entity
      */
-    async verifyCrates(crateName) {
+    async verifyCrates(crateName, signal) {
         const encoded = encodeURIComponent(crateName);
         const sourceUrl = `https://crates.io/api/v1/crates/${encoded}`;
-        const bodyRaw = await this.fetchJson(sourceUrl, { accept: "application/json" });
-        const body = this.tryGetRecord(bodyRaw);
+        const bodyRaw = await this.httpReader.fetchJson(sourceUrl, { accept: "application/json", signal });
+        const body = this.tryGetRecord(bodyRaw.value);
         if (!body) {
-            throw new Error(`Unexpected crates.io response for ${sourceUrl}`);
+            throw new Error(`Respuesta crates.io inesperada para ${sourceUrl}`);
         }
         const versions = Array.isArray(body["versions"]) ? body["versions"] : [];
         const stableCandidates = [];
@@ -335,24 +508,25 @@ export class WebSearchRegistryVerifier {
      * Verifies NuGet package versions via NuGet V3 endpoints.
      *
      * @param packageId - NuGet package ID
+     * @param signal - Optional caller abort signal
      * @returns Verified registry entity
      */
-    async verifyNuGet(packageId) {
+    async verifyNuGet(packageId, signal) {
         const lowerId = packageId.toLowerCase();
-        const serviceIndex = await this.getNuGetServiceIndex();
+        const serviceIndex = await this.getNuGetServiceIndex(signal);
         if (!serviceIndex.packageBaseAddressUrl) {
             return {
                 kind: "nuget",
                 name: packageId,
                 status: "error",
-                error: "NuGet service index did not provide PackageBaseAddress."
+                error: "El índice de NuGet no proporcionó PackageBaseAddress."
             };
         }
         const versionsUrl = `${serviceIndex.packageBaseAddressUrl}${lowerId}/index.json`;
-        const versionsBodyRaw = await this.fetchJson(versionsUrl, { accept: "application/json" });
-        const versionsBody = this.tryGetRecord(versionsBodyRaw);
+        const versionsBodyRaw = await this.httpReader.fetchJson(versionsUrl, { accept: "application/json", signal });
+        const versionsBody = this.tryGetRecord(versionsBodyRaw.value);
         if (!versionsBody) {
-            throw new Error(`Unexpected NuGet response for ${versionsUrl}`);
+            throw new Error(`Respuesta NuGet inesperada para ${versionsUrl}`);
         }
         const versions = Array.isArray(versionsBody["versions"]) ? versionsBody["versions"] : [];
         const versionStrings = versions
@@ -361,10 +535,10 @@ export class WebSearchRegistryVerifier {
         const bestStable = this.pickBestSemVer(versionStrings, { prerelease: false });
         const bestPre = this.pickBestSemVer(versionStrings, { prerelease: true });
         const stablePublishedAt = bestStable && serviceIndex.registrationsBaseUrl
-            ? await this.tryFetchNuGetLeafPublishedAt(serviceIndex.registrationsBaseUrl, lowerId, bestStable)
+            ? await this.tryFetchNuGetLeafPublishedAt(serviceIndex.registrationsBaseUrl, lowerId, bestStable, signal)
             : null;
         const prePublishedAt = bestPre && serviceIndex.registrationsBaseUrl
-            ? await this.tryFetchNuGetLeafPublishedAt(serviceIndex.registrationsBaseUrl, lowerId, bestPre)
+            ? await this.tryFetchNuGetLeafPublishedAt(serviceIndex.registrationsBaseUrl, lowerId, bestPre, signal)
             : null;
         return {
             kind: "nuget",
@@ -381,92 +555,117 @@ export class WebSearchRegistryVerifier {
     /**
      * Verifies GitHub repository releases via GitHub REST API.
      *
+     * @remarks
+     * `latest_stable` comes from `/releases/latest` (GitHub's own newest
+     * non-prerelease, non-draft pick, immune to first-page truncation);
+     * prerelease candidates page through `/releases?per_page=100` following
+     * the `Link` header (up to {@link GITHUB_RELEASES_MAX_PAGES} pages, i.e.
+     * 300 newest releases — beyond that the first pages are what we keep).
+     *
      * @param repoSlug - Repository slug in the form "owner/repo"
+     * @param signal - Optional caller abort signal
      * @returns Verified registry entity
      */
-    async verifyGitHub(repoSlug) {
-        const parts = repoSlug.split("/");
+    async verifyGitHub(repoSlug, signal) {
+        const cleanSlug = repoSlug.trim().replace(/\.git$/iu, "");
+        const parts = cleanSlug.split("/");
         const owner = parts[0];
         const repo = parts[1];
         if (!owner || !repo) {
-            return { kind: "github", name: repoSlug, status: "error", error: "Invalid repo slug." };
+            return { kind: "github", name: repoSlug, status: "error", error: "Repositorio inválido." };
         }
-        const sourceUrl = `https://api.github.com/repos/${owner}/${repo}/releases?per_page=100`;
-        const releasesRaw = await this.fetchJson(sourceUrl, {
-            accept: "application/vnd.github+json",
-            githubToken: this.deps.githubToken
-        });
-        const releases = Array.isArray(releasesRaw) ? releasesRaw : [];
-        const stableCandidates = [];
-        const preCandidates = [];
-        for (const item of releases) {
-            const record = this.tryGetRecord(item);
-            if (!record) {
-                continue;
-            }
-            if (record["draft"] === true) {
-                continue;
-            }
-            const tagNameRaw = this.tryGetNonEmptyString(record["tag_name"]);
-            if (!tagNameRaw) {
-                continue;
+        const latestUrl = `https://api.github.com/repos/${owner}/${repo}/releases/latest`;
+        const listUrl = `https://api.github.com/repos/${owner}/${repo}/releases?per_page=100`;
+        let latestStable = null;
+        try {
+            const latestPage = await this.httpReader.fetchJson(latestUrl, {
+                accept: "application/vnd.github+json",
+                githubToken: this.deps.githubToken,
+                signal
+            });
+            const latest = this.tryParseGitHubReleaseCandidate(latestPage.value);
+            if (latest !== null && !latest.prerelease) {
+                latestStable = { version: latest.version, publishedAt: latest.publishedAt };
             }
-            const tagName = tagNameRaw.startsWith("v") ? tagNameRaw.slice(1) : tagNameRaw;
-            const publishedAt = this.tryGetNonEmptyString(record["published_at"]);
-            const isPrerelease = record["prerelease"] === true;
-            const candidate = { version: tagName, publishedAt: publishedAt ?? null, prerelease: isPrerelease };
-            if (isPrerelease) {
-                preCandidates.push(candidate);
+        }
+        catch (error) {
+            // /releases/latest 404s when the repo has no published stable release
+            // at all; any other failure fails the entity honestly.
+            const message = error instanceof Error ? error.message : String(error);
+            if (!/HTTP 404/u.test(message)) {
+                throw error;
             }
-            else {
-                stableCandidates.push(candidate);
+        }
+        const stableListFallbacks = [];
+        const preCandidates = [];
+        let nextUrl = listUrl;
+        let fetchedPages = 0;
+        while (nextUrl !== null && fetchedPages < WebSearchRegistryVerifier.GITHUB_RELEASES_MAX_PAGES) {
+            const page = await this.httpReader.fetchJson(nextUrl, {
+                accept: "application/vnd.github+json",
+                githubToken: this.deps.githubToken,
+                signal
+            });
+            fetchedPages += 1;
+            const releases = Array.isArray(page.value) ? page.value : [];
+            for (const item of releases) {
+                const candidate = this.tryParseGitHubReleaseCandidate(item);
+                if (candidate === null) {
+                    continue;
+                }
+                if (candidate.prerelease) {
+                    preCandidates.push(candidate);
+                }
+                else {
+                    stableListFallbacks.push(candidate);
+                }
             }
+            nextUrl = page.nextUrl;
         }
-        const bestStable = this.pickBestVersionCandidate(stableCandidates, { prerelease: false });
+        const bestStable = latestStable ?? this.pickBestVersionCandidate(stableListFallbacks, { prerelease: false });
         const bestPre = this.pickBestVersionCandidate(preCandidates, { prerelease: true });
         return {
             kind: "github",
             name: repoSlug,
             latest_stable: bestStable
-                ? { version: bestStable.version, published_at: bestStable.publishedAt ?? undefined, source_url: sourceUrl }
+                ? {
+                    version: bestStable.version,
+                    published_at: bestStable.publishedAt ?? undefined,
+                    // Provenance honesty: attribute the fallback pick to the list
+                    // endpoint it actually came from, not to /releases/latest.
+                    source_url: latestStable !== null ? latestUrl : listUrl
+                }
                 : undefined,
             latest_prerelease: bestPre
-                ? { version: bestPre.version, published_at: bestPre.publishedAt ?? undefined, source_url: sourceUrl }
+                ? { version: bestPre.version, published_at: bestPre.publishedAt ?? undefined, source_url: listUrl }
                 : undefined,
             status: "ok"
         };
     }
     /**
-     * Performs an HTTP GET expecting a JSON response.
+     * Parses one GitHub release entry into a version candidate.
      *
-     * @param url - Target URL
-     * @param options - Request options
-     * @returns Parsed JSON object/array
+     * @param raw - Release entry from the GitHub API
+     * @returns Candidate, or null for drafts/entries without a tag
      */
-    async fetchJson(url, options) {
-        const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), this.deps.timeoutMs);
-        const headers = {
-            Accept: options.accept,
-            "User-Agent": "enriweb"
-        };
-        if (options.githubToken && options.githubToken.trim()) {
-            headers["Authorization"] = `Bearer ${options.githubToken.trim()}`;
+    tryParseGitHubReleaseCandidate(raw) {
+        const record = this.tryGetRecord(raw);
+        if (!record) {
+            return null;
         }
-        try {
-            const response = await this.deps.fetchImpl(url, {
-                method: "GET",
-                headers,
-                signal: controller.signal
-            });
-            if (!response.ok) {
-                throw new Error(`HTTP ${response.status} for ${url}`);
-            }
-            return await response.json();
+        if (record["draft"] === true) {
+            return null;
         }
-        finally {
-            clearTimeout(timeout);
+        const tagNameRaw = this.tryGetNonEmptyString(record["tag_name"]);
+        if (!tagNameRaw) {
+            return null;
         }
+        const tagName = tagNameRaw.startsWith("v") ? tagNameRaw.slice(1) : tagNameRaw;
+        return {
+            version: tagName,
+            publishedAt: this.tryGetNonEmptyString(record["published_at"]),
+            prerelease: record["prerelease"] === true
+        };
     }
     /**
      * Attempts to parse the npm package name from an npmjs.com URL.
@@ -479,7 +678,17 @@ export class WebSearchRegistryVerifier {
         if (hostname !== "www.npmjs.com" && hostname !== "npmjs.com") {
             return null;
         }
-        const segments = url.pathname.split("/").filter(Boolean);
+        const segments = url.pathname
+            .split("/")
+            .filter(Boolean)
+            .map((segment) => {
+            try {
+                return decodeURIComponent(segment);
+            }
+            catch {
+                return segment;
+            }
+        });
         if (segments.length < 2 || segments[0] !== "package") {
             return null;
         }
@@ -487,6 +696,13 @@ export class WebSearchRegistryVerifier {
         if (!first) {
             return null;
         }
+        if (first.startsWith("@") && first.includes("/")) {
+            const [scope, name] = first.split("/");
+            if (!scope || !name) {
+                return null;
+            }
+            return `${scope}/${name}`;
+        }
         if (first.startsWith("@")) {
             const second = segments[2];
             if (!second) {
@@ -566,10 +782,11 @@ export class WebSearchRegistryVerifier {
             return null;
         }
         const owner = segments[0];
-        const repo = segments[1];
-        if (!owner || !repo) {
+        const repoRaw = segments[1];
+        if (!owner || !repoRaw) {
             return null;
         }
+        const repo = repoRaw.replace(/\.git$/iu, "");
         return `${owner}/${repo}`;
     }
     /**
@@ -609,6 +826,10 @@ export class WebSearchRegistryVerifier {
     /**
      * Best-effort prerelease detection for PyPI version strings.
      *
+     * @remarks
+     * Covers PEP 440 separators and attached suffixes (`1.0b1`, `2.0beta1`)
+     * where the marker follows digits without a delimiter.
+     *
      * @param version - Version string
      * @returns True when prerelease-like
      */
@@ -620,6 +841,9 @@ export class WebSearchRegistryVerifier {
         if (/(?:^|[._-])(?:a|b|rc|dev|alpha|beta|pre|preview)\d*/.test(lower)) {
             return true;
         }
+        if (/\d(?:a|b|rc|dev|alpha|beta|pre|preview)\d*/.test(lower)) {
+            return true;
+        }
         return false;
     }
     /**
@@ -672,41 +896,86 @@ export class WebSearchRegistryVerifier {
         }
         let bestByTime = filtered[0];
         for (const item of filtered.slice(1)) {
-            if (item.publishedAt && bestByTime.publishedAt) {
-                if (item.publishedAt > bestByTime.publishedAt) {
-                    bestByTime = item;
-                }
-            }
-            else if (item.publishedAt && !bestByTime.publishedAt) {
+            const itemTime = this.tryParseTimeMs(item.publishedAt);
+            const bestTime = bestByTime !== undefined ? this.tryParseTimeMs(bestByTime.publishedAt) : null;
+            if (itemTime !== null && (bestTime === null || itemTime > bestTime)) {
                 bestByTime = item;
             }
         }
         return bestByTime;
     }
+    /**
+     * Parses one ISO timestamp to epoch milliseconds.
+     *
+     * @param value - Timestamp string, if present.
+     * @returns Epoch milliseconds, or null when missing or unparsable.
+     */
+    tryParseTimeMs(value) {
+        if (value === null || !value.trim()) {
+            return null;
+        }
+        const parsed = Date.parse(value);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
     /**
      * Parses SemVer strings (best-effort).
      *
+     * @remarks
+     * Accepts two to four numeric components (`1.2` → `1.2.0`, `1.2.3.4`
+     * keeps the fourth as a build tiebreak) so partial registry versions
+     * still rank instead of dropping out.
+     *
      * @param raw - Version string
      * @returns Parsed semver or null
      */
     tryParseSemVer(raw) {
         const trimmed = raw.trim();
         const normalized = trimmed.startsWith("v") ? trimmed.slice(1) : trimmed;
-        const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(normalized);
+        const match = /^(\d+)\.(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(normalized);
         if (!match) {
-            return null;
+            return this.tryParseAttachedPrerelease(normalized);
         }
         const major = Number.parseInt(match[1] ?? "", 10);
         const minor = Number.parseInt(match[2] ?? "", 10);
-        const patch = Number.parseInt(match[3] ?? "", 10);
-        if (!Number.isFinite(major) || !Number.isFinite(minor) || !Number.isFinite(patch)) {
+        const patch = match[3] === undefined ? 0 : Number.parseInt(match[3], 10);
+        const build = match[4] === undefined ? 0 : Number.parseInt(match[4], 10);
+        if (!Number.isFinite(major) || !Number.isFinite(minor) || !Number.isFinite(patch) || !Number.isFinite(build)) {
             return null;
         }
-        const prereleaseRaw = match[4];
+        const prereleaseRaw = match[5];
         const prerelease = prereleaseRaw
             ? prereleaseRaw.split(".").filter((p) => p.length > 0)
             : [];
-        return { raw: normalized, major, minor, patch, prerelease };
+        return { raw: normalized, major, minor, patch, build, prerelease };
+    }
+    /**
+     * Parses versions with attached prerelease suffixes (`2024.1b1`, `2.0rc2`).
+     *
+     * @param normalized - Version string without a leading "v".
+     * @returns Parsed semver or null.
+     */
+    tryParseAttachedPrerelease(normalized) {
+        const match = /^(\d+)\.(\d+)(?:\.(\d+))?(?:\.(\d+))?(a|b|rc|alpha|beta|pre|preview|dev)(\d*)$/i.exec(normalized);
+        if (!match) {
+            return null;
+        }
+        const major = Number.parseInt(match[1] ?? "", 10);
+        const minor = Number.parseInt(match[2] ?? "", 10);
+        const patch = match[3] === undefined ? 0 : Number.parseInt(match[3], 10);
+        const build = match[4] === undefined ? 0 : Number.parseInt(match[4], 10);
+        if (!Number.isFinite(major) || !Number.isFinite(minor) || !Number.isFinite(patch) || !Number.isFinite(build)) {
+            return null;
+        }
+        const marker = (match[5] ?? "").toLowerCase();
+        const number = match[6] ?? "";
+        return {
+            raw: normalized,
+            major,
+            minor,
+            patch,
+            build,
+            prerelease: [number ? `${marker}.${number}` : marker]
+        };
     }
     /**
      * Compares two SemVer values.
@@ -725,6 +994,9 @@ export class WebSearchRegistryVerifier {
         if (a.patch !== b.patch) {
             return a.patch - b.patch;
         }
+        if (a.build !== b.build) {
+            return a.build - b.build;
+        }
         const aPre = a.prerelease;
         const bPre = b.prerelease;
         if (aPre.length === 0 && bPre.length === 0) {
@@ -790,6 +1062,7 @@ export class WebSearchRegistryVerifier {
             return null;
         }
         let best = null;
+        let bestMs = -1;
         for (const item of releaseFiles) {
             const record = this.tryGetRecord(item);
             if (!record) {
@@ -799,8 +1072,13 @@ export class WebSearchRegistryVerifier {
             if (!uploadTime) {
                 continue;
             }
-            if (!best || uploadTime > best) {
+            const uploadMs = this.tryParseTimeMs(uploadTime);
+            if (uploadMs === null) {
+                continue;
+            }
+            if (best === null || uploadMs > bestMs) {
                 best = uploadTime;
+                bestMs = uploadMs;
             }
         }
         return best;
@@ -808,19 +1086,21 @@ export class WebSearchRegistryVerifier {
     /**
      * Resolves NuGet V3 endpoints from the service index, with caching.
      *
+     * @param signal - Optional caller abort signal
      * @returns Service index cache
      */
-    async getNuGetServiceIndex() {
+    async getNuGetServiceIndex(signal) {
         const nowMs = Date.now();
         if (this.nugetServiceIndexCache && this.nugetServiceIndexCache.expiresAtMs > nowMs) {
             return this.nugetServiceIndexCache;
         }
-        const bodyRaw = await this.fetchJson(WebSearchRegistryVerifier.NUGET_SERVICE_INDEX_URL, {
-            accept: "application/json"
+        const bodyRaw = await this.httpReader.fetchJson(WebSearchRegistryVerifier.NUGET_SERVICE_INDEX_URL, {
+            accept: "application/json",
+            signal
         });
-        const body = this.tryGetRecord(bodyRaw);
+        const body = this.tryGetRecord(bodyRaw.value);
         if (!body) {
-            throw new Error("Unexpected NuGet service index response.");
+            throw new Error("Respuesta inesperada del índice de NuGet.");
         }
         const resources = Array.isArray(body["resources"]) ? body["resources"] : [];
         let packageBase = null;
@@ -866,13 +1146,14 @@ export class WebSearchRegistryVerifier {
      * @param registrationsBaseUrl - Registrations base URL
      * @param lowerId - Lowercase package ID
      * @param version - Version string
+     * @param signal - Optional caller abort signal
      * @returns Published ISO 8601 timestamp or null
      */
-    async tryFetchNuGetLeafPublishedAt(registrationsBaseUrl, lowerId, version) {
+    async tryFetchNuGetLeafPublishedAt(registrationsBaseUrl, lowerId, version, signal) {
         const leafUrl = `${registrationsBaseUrl}${lowerId}/${encodeURIComponent(version)}.json`;
         try {
-            const bodyRaw = await this.fetchJson(leafUrl, { accept: "application/json" });
-            const body = this.tryGetRecord(bodyRaw);
+            const bodyRaw = await this.httpReader.fetchJson(leafUrl, { accept: "application/json", signal });
+            const body = this.tryGetRecord(bodyRaw.value);
             if (!body) {
                 return null;
             }