@bedolla/enriweb 0.1.6 → 0.1.7

package/dist/tools/WebFetchNpmProjection.js

@@ -0,0 +1,480 @@
+/**
+ * npm package-page projection for the web_fetch tool.
+ *
+ * @remarks
+ * npm package pages answer with a marketing shell; this projection queries
+ * the official registry metadata and fetches the README from the resolved
+ * repository (GitHub raw with branch preference and a bounded worker pool),
+ * stitching a structured Spanish result with early-exit on the first hit.
+ * Extracted from {@link WebFetchTool} as a pure collaborator.
+ *
+ * Size note (~590 lines, alert zone by design): the npm path owns metadata
+ * fetch, version pinning, the README pool and the stitched composition as
+ * one cohesive pipeline; the shared registry transport already lives in
+ * WebSearchRegistryHttpReader. Splitting is tracked debt; any future edit
+ * must extract the touched unit instead of growing this file.
+ *
+ * @module tools/WebFetchNpmProjection
+ */
+import { sliceUtf8Safe } from "../shared/Utf8SafeTextSlicer.js";
+/**
+ * Maximum concurrent README sub-fetches.
+ *
+ * @remarks
+ * Bounds the npm fan-out while keeping the worst case near one timeout for
+ * fast 404s; candidates dispatch in preference order.
+ */
+const README_FETCH_CONCURRENCY = 3;
+/**
+ * Bounds one npm sub-fetch to the short subfetch timeout.
+ *
+ * @param signal - Optional caller abort signal.
+ * @returns Combined signal, or undefined when the caller passed none.
+ */
+function subfetchSignal(signal) {
+    if (signal === undefined) {
+        return AbortSignal.timeout(README_SUBFETCH_TIMEOUT_MS);
+    }
+    if (signal.aborted) {
+        return signal;
+    }
+    return AbortSignal.any([signal, AbortSignal.timeout(README_SUBFETCH_TIMEOUT_MS)]);
+}
+/**
+ * Per-subfetch timeout (ms) for npm registry/metadata/README reads.
+ *
+ * @remarks
+ * Raw files answer in milliseconds; a hung candidate must not consume the
+ * whole tool budget. Combined with the pool, the npm path stays near one
+ * tool timeout even when every candidate hangs.
+ */
+const README_SUBFETCH_TIMEOUT_MS = 20_000;
+/**
+ * npm package-page projection collaborator.
+ */
+export class WebFetchNpmProjection {
+    /**
+     * Readme file candidates commonly used in GitHub repositories.
+     */
+    static README_FILENAMES = [
+        "README.md",
+        "readme.md",
+        "README.MD",
+        "README.rst",
+        "README.txt"
+    ];
+    /**
+     * Default branches to try when resolving GitHub raw README URLs.
+     */
+    static README_BRANCHES = ["main", "master"];
+    /**
+     * Attempts to provide a higher-quality fetch for npm package pages.
+     *
+     * @param params - Tool parameters
+     * @param client - EnriProxy client
+     * @param maxChars - Maximum content length to return
+     * @param projection - Effective projection traveling to README sub-fetches
+     * @param signal - Optional caller abort signal
+     * @returns Tool result if the URL is an npm package page, otherwise null
+     */
+    async tryExecuteNpmPackageFetch(params, client, maxChars, projection, signal) {
+        const requestedUrl = new URL(params.url);
+        const packageRef = this.tryParseNpmPackagePageRef(requestedUrl);
+        if (!packageRef) {
+            return null;
+        }
+        // A pinned `/v/<version>` page resolves its own registry manifest; only
+        // the unversioned page asks for `/latest` (small payload, parity with
+        // EnriProxy's registry tier).
+        const metadataUrl = packageRef.version !== undefined
+            ? `https://registry.npmjs.org/${encodeURIComponent(packageRef.name)}/${encodeURIComponent(packageRef.version)}`
+            : `https://registry.npmjs.org/${encodeURIComponent(packageRef.name)}/latest`;
+        // A signal that never fires stands in for the caller when it passed
+        // none, so subfetch timeouts are labeled as timeouts (not cancellations).
+        const callerSignal = signal ?? new AbortController().signal;
+        let metadataResponse;
+        try {
+            metadataResponse = await client.webFetch({
+                url: metadataUrl,
+                maxChars: Math.min(maxChars, 20000)
+            }, subfetchSignal(signal), { callerSignal, subfetchTimeoutMs: README_SUBFETCH_TIMEOUT_MS });
+        }
+        catch (error) {
+            // Transport failures on the metadata leg (proxy 5xx, subfetch timeout)
+            // degrade to the generic fetch path instead of failing the whole call;
+            // only a genuine caller abort propagates.
+            if (signal?.aborted) {
+                throw error;
+            }
+            return null;
+        }
+        if (metadataResponse.status < 200 || metadataResponse.status >= 300) {
+            return null;
+        }
+        const metadata = this.tryParseJsonObject(metadataResponse.content);
+        if (!metadata) {
+            return null;
+        }
+        const name = this.tryGetString(metadata["name"]) ?? packageRef.name;
+        const version = this.tryGetString(metadata["version"]);
+        const description = this.tryGetString(metadata["description"]);
+        const license = this.tryGetString(metadata["license"]);
+        const repositoryUrl = this.tryGetRepositoryUrl(metadata["repository"]);
+        const homepageUrl = this.tryGetString(metadata["homepage"]);
+        let gitHubRepoUrl = null;
+        if (repositoryUrl) {
+            gitHubRepoUrl = this.tryNormalizeGitHubRepoUrl(repositoryUrl);
+        }
+        let readmeText = null;
+        let readmeTruncated = false;
+        let readmeCursor;
+        let readmeTotalChars;
+        if (gitHubRepoUrl) {
+            const readmeResult = await this.tryFetchGitHubReadme(client, gitHubRepoUrl, maxChars, projection, signal);
+            if (readmeResult) {
+                readmeText = readmeResult.content;
+                readmeTruncated = readmeResult.truncated;
+                readmeCursor = readmeResult.cursor;
+                readmeTotalChars = readmeResult.totalChars;
+            }
+        }
+        const lines = [];
+        lines.push(`# ${name}`);
+        lines.push("");
+        lines.push(`URL solicitada: ${params.url}`);
+        lines.push("");
+        if (description) {
+            lines.push(`Descripción: ${description}`);
+        }
+        const versionLabel = version ?? packageRef.version ?? null;
+        if (versionLabel) {
+            // A pinned `/v/<version>` page labels the requested version; only the
+            // unversioned page reports the rolling "latest".
+            lines.push(packageRef.version !== undefined
+                ? `Versión solicitada: ${versionLabel}`
+                : `Última versión: ${versionLabel}`);
+        }
+        if (license) {
+            lines.push(`Licencia: ${license}`);
+        }
+        if (homepageUrl) {
+            lines.push(`Página principal: ${homepageUrl}`);
+        }
+        if (gitHubRepoUrl) {
+            lines.push(`Repositorio: ${gitHubRepoUrl}`);
+        }
+        else if (repositoryUrl) {
+            lines.push(`Repositorio: ${repositoryUrl}`);
+        }
+        if (readmeText) {
+            lines.push("");
+            lines.push("## README");
+            lines.push("");
+            lines.push(readmeText);
+        }
+        const combined = lines.join("\n").trim() + "\n";
+        const shouldTrim = combined.length > maxChars;
+        const content = shouldTrim ? sliceUtf8Safe(combined, 0, maxChars) : combined;
+        return {
+            content,
+            status: 200,
+            content_type: "text/markdown",
+            truncated: shouldTrim || readmeTruncated || metadataResponse.truncated,
+            url: params.url,
+            // The winning README sub-fetch may have emitted a continuation cursor
+            // for its raw capture: propagate it (plus the capture total) so the
+            // model can paginate without re-downloading.
+            ...(readmeCursor
+                ? { cursor: readmeCursor, total_chars: readmeTotalChars, has_more: true }
+                : { total_chars: combined.length, has_more: shouldTrim }),
+            applied_max_chars: maxChars
+        };
+    }
+    /**
+     * Attempts to parse package coordinates from an npmjs.com package page URL.
+     *
+     * @remarks
+     * Versioned pages (`/package/<name>/v/<version>`, including scoped
+     * packages) pin the registry manifest to the requested version; every
+     * other form resolves through `/latest`.
+     *
+     * @param url - Parsed URL
+     * @returns Package name plus optional pinned version, or null when the URL
+     *   is not an npm package page
+     */
+    tryParseNpmPackagePageRef(url) {
+        const hostname = url.hostname.toLowerCase();
+        if (hostname !== "www.npmjs.com" && hostname !== "npmjs.com") {
+            return null;
+        }
+        // Path segments may arrive percent-encoded (e.g. `%40scope%2Fname` when
+        // copied from the registry); decode before parsing so scoped packages
+        // resolve to `@scope/name` like their canonical page form.
+        const segments = url.pathname
+            .split("/")
+            .filter(Boolean)
+            .map((segment) => {
+            try {
+                return decodeURIComponent(segment);
+            }
+            catch {
+                return segment;
+            }
+        });
+        if (segments.length < 2) {
+            return null;
+        }
+        if (segments[0] !== "package") {
+            return null;
+        }
+        // Reads the pinned version from the segments starting at `from`.
+        const readPinnedVersion = (from) => {
+            const marker = segments[from];
+            const value = segments[from + 1];
+            return marker === "v" && value !== undefined && value.length > 0 ? value : undefined;
+        };
+        const first = segments[1];
+        if (!first) {
+            return null;
+        }
+        // A single percent-encoded segment (`%40scope%2Fname`) decodes to a name
+        // that already contains the slash; split it back into scope + name.
+        if (first.startsWith("@") && first.includes("/")) {
+            const [scope, name] = first.split("/");
+            if (!scope || !name) {
+                return null;
+            }
+            return { name: `${scope}/${name}`, version: readPinnedVersion(2) };
+        }
+        if (first.startsWith("@")) {
+            const second = segments[2];
+            if (!second) {
+                return null;
+            }
+            return { name: `${first}/${second}`, version: readPinnedVersion(3) };
+        }
+        return { name: first, version: readPinnedVersion(2) };
+    }
+    /**
+     * Tries to parse a JSON object from a string.
+     *
+     * @param input - JSON string
+     * @returns Parsed object or null
+     */
+    tryParseJsonObject(input) {
+        try {
+            const parsed = JSON.parse(input);
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                return null;
+            }
+            return parsed;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Extracts a string from an unknown value if possible.
+     *
+     * @param value - Unknown input
+     * @returns Trimmed string or null
+     */
+    tryGetString(value) {
+        if (typeof value !== "string") {
+            return null;
+        }
+        const trimmed = value.trim();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+    /**
+     * Extracts a repository URL from npm metadata.
+     *
+     * @param repository - Repository field value
+     * @returns Normalized URL string or null
+     */
+    tryGetRepositoryUrl(repository) {
+        if (typeof repository === "string") {
+            return this.normalizeRepositoryUrl(repository);
+        }
+        if (typeof repository === "object" && repository !== null && !Array.isArray(repository)) {
+            const record = repository;
+            const rawUrl = this.tryGetString(record["url"]);
+            if (!rawUrl) {
+                return null;
+            }
+            return this.normalizeRepositoryUrl(rawUrl);
+        }
+        return null;
+    }
+    /**
+     * Normalizes common git repository URL schemes into an https URL.
+     *
+     * @param rawUrl - Raw repository URL from metadata
+     * @returns Normalized URL string or null
+     */
+    normalizeRepositoryUrl(rawUrl) {
+        let urlText = rawUrl.trim();
+        if (urlText.startsWith("github:")) {
+            urlText = `https://github.com/${urlText.slice("github:".length)}`;
+        }
+        const scpMatch = urlText.match(/^git@([^:]+):(.+)$/u);
+        if (scpMatch) {
+            urlText = `https://${scpMatch[1]}/${scpMatch[2]}`;
+        }
+        if (urlText.startsWith("git+")) {
+            urlText = urlText.slice("git+".length);
+        }
+        if (urlText.startsWith("git://")) {
+            urlText = `https://${urlText.slice("git://".length)}`;
+        }
+        if (urlText.endsWith(".git")) {
+            urlText = urlText.slice(0, -".git".length);
+        }
+        try {
+            const parsed = new URL(urlText);
+            if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+                return null;
+            }
+            return parsed.toString();
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Normalizes a GitHub repository URL to the canonical https form.
+     *
+     * @param repositoryUrl - Repository URL
+     * @returns Canonical GitHub repo URL (https://github.com/{owner}/{repo}) or null
+     */
+    tryNormalizeGitHubRepoUrl(repositoryUrl) {
+        try {
+            const parsed = new URL(repositoryUrl);
+            if (parsed.hostname.toLowerCase() !== "github.com") {
+                return null;
+            }
+            const segments = parsed.pathname.split("/").filter(Boolean);
+            if (segments.length < 2) {
+                return null;
+            }
+            const owner = segments[0];
+            const repoRaw = segments[1];
+            if (!owner || !repoRaw) {
+                return null;
+            }
+            const repo = repoRaw.replace(/\.git$/iu, "");
+            return `https://github.com/${owner}/${repo}`;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Attempts to fetch a GitHub repository README via raw.githubusercontent.com.
+     *
+     * @remarks
+     * Candidates dispatch in preference order through a bounded worker pool;
+     * the first completed hit wins and aborts the stragglers, so the common
+     * case costs one fast fetch instead of the slowest of ten. Projection
+     * fields travel to the README sub-fetches; the registry metadata fetch
+     * stays raw because its JSON is parsed.
+     *
+     * @param client - EnriProxy client
+     * @param githubRepoUrl - Canonical GitHub repo URL
+     * @param maxChars - Maximum content length
+     * @param projection - Effective projection for the README page
+     * @param signal - Optional caller abort signal
+     * @returns README content with pagination fields, or null
+     */
+    async tryFetchGitHubReadme(client, githubRepoUrl, maxChars, projection, signal) {
+        const parsed = new URL(githubRepoUrl);
+        const segments = parsed.pathname.split("/").filter(Boolean);
+        if (segments.length < 2) {
+            return null;
+        }
+        const owner = segments[0];
+        const repo = segments[1];
+        if (!owner || !repo) {
+            return null;
+        }
+        const candidates = [];
+        for (const branch of WebFetchNpmProjection.README_BRANCHES) {
+            for (const filename of WebFetchNpmProjection.README_FILENAMES) {
+                candidates.push(`https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${filename}`);
+            }
+        }
+        const controller = new AbortController();
+        const onCallerAbort = () => controller.abort();
+        if (signal !== undefined) {
+            if (signal.aborted) {
+                controller.abort();
+            }
+            else {
+                signal.addEventListener("abort", onCallerAbort, { once: true });
+            }
+        }
+        try {
+            let nextIndex = 0;
+            let hit = null;
+            const worker = async () => {
+                while (hit === null) {
+                    const candidateIndex = nextIndex;
+                    nextIndex += 1;
+                    if (candidateIndex >= candidates.length) {
+                        return;
+                    }
+                    if (controller.signal.aborted) {
+                        return;
+                    }
+                    const candidateUrl = candidates[candidateIndex] ?? "";
+                    let response;
+                    try {
+                        response = await client.webFetch({
+                            url: candidateUrl,
+                            maxChars,
+                            format: projection.format,
+                            content: projection.content,
+                            includeLinks: projection.includeLinks,
+                            includeMetadata: projection.includeMetadata,
+                            ...(projection.anchor !== undefined ? { anchor: projection.anchor } : {}),
+                            ...(projection.prompt !== undefined ? { prompt: projection.prompt } : {})
+                        }, subfetchSignal(controller.signal), { callerSignal: controller.signal, subfetchTimeoutMs: README_SUBFETCH_TIMEOUT_MS });
+                    }
+                    catch (error) {
+                        // One candidate failing (404/timeout) must not orphan the rest,
+                        // but a CALLER cancellation is not a candidate failure: it
+                        // propagates so the npm projection surfaces an aborted call
+                        // instead of composing a normal result for a cancelled request
+                        // (same contract as the metadata leg above).
+                        if (signal?.aborted === true) {
+                            throw error;
+                        }
+                        continue;
+                    }
+                    if (hit !== null) {
+                        return;
+                    }
+                    if (response.status >= 200 && response.status < 300 && response.content.trim().length > 0) {
+                        hit = {
+                            content: response.content,
+                            truncated: response.truncated,
+                            cursor: response.cursor,
+                            totalChars: response.total_chars
+                        };
+                        controller.abort();
+                    }
+                }
+            };
+            const workers = [];
+            for (let i = 0; i < Math.min(README_FETCH_CONCURRENCY, candidates.length); i += 1) {
+                workers.push(worker());
+            }
+            await Promise.all(workers);
+            return hit;
+        }
+        finally {
+            signal?.removeEventListener("abort", onCallerAbort);
+        }
+    }
+}
+//# sourceMappingURL=WebFetchNpmProjection.js.map

package/dist/tools/WebFetchNpmProjection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebFetchNpmProjection.js","sourceRoot":"","sources":["../../src/tools/WebFetchNpmProjection.ts"],"names":[],"mappings":"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"}

package/dist/tools/WebFetchParamsParser.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Argument parsing for the web_fetch MCP tool.
+ *
+ * @remarks
+ * Lenient for malformed optional values (they degrade to documented
+ * defaults, matching the EnriCode client parser: unusable or out-of-domain
+ * budgets fall back to the documented default instead of failing the call,
+ * per the shared AR-4 client policy) but strict for structural mistakes
+ * (broken ranges, unknown action without cursor), which fail fast in
+ * Spanish. Snake_case field names
+ * are canonical; camelCase aliases (maxChars, offsetChars, limitChars,
+ * includeLinks, includeMetadata) are accepted as fallbacks for parity with
+ * the EnriCode tool surface. Extracted from {@link WebFetchTool} as a pure
+ * function module.
+ *
+ * @module tools/WebFetchParamsParser
+ */
+import { type WebFetchToolParams } from "./WebFetchTool.js";
+/**
+ * Validates raw MCP tool arguments.
+ *
+ * @param raw - Raw tool arguments
+ * @returns Validated parameters
+ */
+export declare function parseWebFetchParams(raw: unknown): WebFetchToolParams;
+//# sourceMappingURL=WebFetchParamsParser.d.ts.map

package/dist/tools/WebFetchParamsParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebFetchParamsParser.d.ts","sourceRoot":"","sources":["../../src/tools/WebFetchParamsParser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,EAAqC,KAAK,kBAAkB,EAA0B,MAAM,mBAAmB,CAAC;AAEvH;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,kBAAkB,CAsGpE"}