@aexol/spectral 0.9.126 → 0.9.128

package/dist/extensions/seo/tools/full-audit.js

@@ -1,14 +1,15 @@
 import { auditTechnical } from "../analyzers/technical.js";
 import { analyzeContentQuality } from "../analyzers/content.js";
 import { auditSchema } from "../analyzers/schema.js";
-import { auditImages } from "../analyzers/images.js";
+import { auditImages, checkImageUrls } from "../analyzers/images.js";
 import { auditPreload } from "../analyzers/preload.js";
 import { auditAgentUx } from "../analyzers/agent-ux.js";
+import { calculatePerformanceFromFetch, analyzePageWeight } from "../analyzers/performance.js";
 import { fetchPage } from "../utils/fetcher.js";
 import { renderPage, isRendererAvailable } from "../utils/renderer.js";
 import { parsePage, extractText } from "../utils/parser.js";
-import { errorResult, textResult } from "./helpers.js";
-const ALL_CATEGORIES = ["technical", "content", "schema", "images", "preload", "agentUx"];
+import { errorResult, textResult, validateToolUrl } from "./helpers.js";
+const ALL_CATEGORIES = ["technical", "content", "schema", "images", "preload", "agentUx", "performance"];
 export function registerFullAuditTools(ext, config) {
     const fullAuditTool = {
         name: "seo_audit",
@@ -17,8 +18,9 @@ export function registerFullAuditTools(ext, config) {
             "content quality (filler, AI patterns, density), schema audit (detection, validation), image audit (alt, dimensions, formats), " +
             "preload audit (speculation rules, bfcache), and agent UX audit (accessibility, semantic HTML). " +
             "Returns an overall score and all issues prioritized by severity. " +
-            "Use 'include' to run only specific sub-audits.",
-        promptSnippet: "`seo_audit { url, include? }` — full SEO audit (technical + content + schema + images + preload + agentUx)",
+            "Use 'include' to run only specific sub-audits. " +
+            "When 'performance' is included and a browser is available, real Web Vitals are measured via Playwright.",
+        promptSnippet: "`seo_audit { url, include? }` — full SEO audit (technical + content + schema + images + preload + agentUx + performance)",
         promptGuidelines: [
             "When the user asks about SEO, search optimization, page audits, schema markup, sitemaps, Core Web Vitals, or technical SEO for any website or URL, use the seo_* tools. Start with seo_audit for comprehensive analysis — it runs all sub-audits in one call. For specific concerns use the targeted tools (seo_technical_audit, seo_content_quality, seo_schema_audit, seo_image_audit, seo_preload_audit, seo_agent_ux_audit). These tools are offline-first and require no API keys.",
         ],
@@ -30,7 +32,7 @@ export function registerFullAuditTools(ext, config) {
                     type: "array",
                     items: {
                         type: "string",
-                        enum: ["technical", "content", "schema", "images", "preload", "agentUx"],
+                        enum: ["technical", "content", "schema", "images", "preload", "agentUx", "performance"],
                     },
                     description: "Sub-audits to include. If omitted, runs all sub-audits.",
                 },
@@ -38,8 +40,9 @@ export function registerFullAuditTools(ext, config) {
             required: ["url"],
         },
         async execute(_toolCallId, params) {
-            const { url, include } = params;
+            const { url: rawUrl, include } = params;
             try {
+                const url = validateToolUrl(rawUrl);
                 const categories = include ?? ALL_CATEGORIES;
                 const result = await runFullAudit(url, config, categories);
                 const issueLines = result.allIssues
@@ -49,14 +52,18 @@ export function registerFullAuditTools(ext, config) {
                     .join("\n");
                 const summary = `✓ Full SEO Audit: ${result.url}\n` +
                     `Audited At: ${result.auditedAt}\n` +
-                    `Overall Score: ${result.overallScore}/100\n\n` +
+                    `Overall Score: ${result.overallScore}/100\n` +
+                    `Coverage: ${result.coverage}% | Confidence: ${result.confidence}\n` +
+                    `Skipped: ${result.skippedCategories.join(", ") || "none"}\n` +
                     `Sub-audits run:\n` +
                     `  Technical: ${result.technical ? `${result.technical.score}/100` : "skipped"}\n` +
                     `  Content: ${result.content ? `${result.content.overallQuality}/100` : "skipped"}\n` +
                     `  Schema: ${result.schema ? `${result.schema.detectedSchemas.length} blocks` : "skipped"}\n` +
                     `  Images: ${result.images ? `${result.images.missingAlt} missing alt` : "skipped"}\n` +
                     `  Preload: ${result.preload ? `${result.preload.score}/100` : "skipped"}\n` +
-                    `  Agent UX: ${result.agentUx ? `${result.agentUx.agentUxScore}/100` : "skipped"}\n\n` +
+                    `  Agent UX: ${result.agentUx ? `${result.agentUx.agentUxScore}/100` : "skipped"}\n` +
+                    `  Performance: ${result.performance ? `${result.performance.score}/100 (${result.performance.source ?? "heuristic"})` : "skipped"}\n` +
+                    `Renderer: ${result.rendererAvailable ? "available" : "unavailable"}${result.renderComparison ? ` | Render diff: ${result.renderComparison.textDelta > 0 ? "+" : ""}${result.renderComparison.textDelta} words${result.renderComparison.isSpa ? " (SPA detected)" : ""}` : ""}\n\n` +
                     `Top Issues (${result.allIssues.length} total):\n${issueLines || "  (none)"}`;
                 return textResult(summary, { result });
             }
@@ -70,89 +77,316 @@ export function registerFullAuditTools(ext, config) {
 async function runFullAudit(url, config, categories) {
     // Fetch the page once and reuse for all sub-audits.
     const fetchResult = await fetchPage(url, config);
-    const pageData = parsePage(fetchResult.content, fetchResult.finalUrl);
     const allIssues = [];
-    let scores = [];
-    // Technical audit.
-    let technical;
+    const skippedCategories = ALL_CATEGORIES.filter((category) => !categories.includes(category));
+    // Handle fetch failures as structured audit issues instead of generic errors.
+    if (fetchResult.error || fetchResult.statusCode === 0 || fetchResult.statusCode >= 400) {
+        const severity = fetchResult.statusCode >= 500 || fetchResult.statusCode === 0 ? "critical" : "high";
+        const title = fetchResult.statusCode === 0
+            ? `Fetch failed: ${fetchResult.error ?? "unknown error"}`
+            : `HTTP ${fetchResult.statusCode} ${fetchResult.statusText}`;
+        allIssues.push({
+            category: "Fetching",
+            severity,
+            title,
+            description: fetchResult.error
+                ? `Unable to fetch ${url}: ${fetchResult.error}`
+                : `Server returned ${fetchResult.statusCode} ${fetchResult.statusText}.`,
+            recommendation: fetchResult.statusCode >= 500
+                ? "Investigate server-side errors; the page may be temporarily unavailable."
+                : fetchResult.statusCode === 404
+                    ? "The page was not found. Check the URL or restore the resource."
+                    : fetchResult.statusCode === 0
+                        ? "Verify DNS, network connectivity, and that the server is reachable."
+                        : "Review server configuration and access controls.",
+        });
+        const summary = `SEO audit for ${url} — fetch failed (${fetchResult.statusCode || "error"}), ${allIssues.length} issues found.`;
+        return {
+            url,
+            auditedAt: new Date().toISOString(),
+            overallScore: 0,
+            coverage: 0,
+            confidence: "low",
+            skippedCategories: ALL_CATEGORIES,
+            rendererAvailable: false,
+            version: 2,
+            warnings: ["Fetch failed, sub-audits were not run."],
+            allIssues,
+            summary,
+        };
+    }
+    const pageData = parsePage(fetchResult.content, fetchResult.finalUrl);
+    // Concurrent sub-audit execution. Each sub-audit runs independently; a
+    // failure in one does not crash the others (Promise.allSettled).
+    const scores = [];
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), config.timeout * 4);
+    const subAuditFns = [];
     if (categories.includes("technical")) {
-        technical = await auditTechnical(url, config, pageData, fetchResult);
-        allIssues.push(...technical.issues);
-        scores.push(technical.score);
+        subAuditFns.push(async () => {
+            const technical = await auditTechnical(url, config, pageData, fetchResult);
+            return {
+                key: "technical",
+                score: technical.score,
+                issues: technical.issues,
+                result: technical,
+            };
+        });
     }
-    // Content quality.
-    let content;
     if (categories.includes("content")) {
-        const text = extractText(fetchResult.content);
-        content = analyzeContentQuality(text, fetchResult.finalUrl);
-        scores.push(content.overallQuality);
+        subAuditFns.push(async () => {
+            const text = extractText(fetchResult.content);
+            const content = analyzeContentQuality(text, fetchResult.finalUrl, pageData);
+            return {
+                key: "content",
+                score: content.overallQuality,
+                issues: [],
+                result: content,
+            };
+        });
     }
-    // Schema audit.
-    let schema;
     if (categories.includes("schema")) {
-        schema = auditSchema(fetchResult.content, fetchResult.finalUrl);
-        // Convert schema recommendations to issues.
-        for (const rec of schema.recommendations) {
-            allIssues.push({
+        subAuditFns.push(async () => {
+            const schema = auditSchema(fetchResult.content, fetchResult.finalUrl);
+            const issues = schema.recommendations.map((rec) => ({
                 category: "Schema",
                 severity: "medium",
                 title: rec,
                 description: rec,
                 recommendation: rec,
-            });
-        }
+            }));
+            return {
+                key: "schema",
+                score: schema.score,
+                issues,
+                result: schema,
+            };
+        });
     }
-    // Image audit.
-    let images;
     if (categories.includes("images")) {
-        images = auditImages(fetchResult.content, fetchResult.finalUrl);
-        if (images.missingAlt > 0) {
-            allIssues.push({
-                category: "Images",
-                severity: "medium",
-                title: `${images.missingAlt} images missing alt text`,
-                description: `${images.missingAlt} of ${images.totalImages} images have no alt attribute.`,
-                recommendation: "Add descriptive alt text to all informative images.",
-            });
-        }
-        if (images.missingDimensions > 0) {
-            allIssues.push({
-                category: "Images",
-                severity: "low",
-                title: `${images.missingDimensions} images missing dimensions`,
-                description: `${images.missingDimensions} images lack width/height attributes, causing layout shift.`,
-                recommendation: "Add width and height attributes to prevent CLS.",
-            });
-        }
+        subAuditFns.push(async () => {
+            const images = auditImages(fetchResult.content, fetchResult.finalUrl, pageData);
+            const issues = [];
+            if (images.missingAlt > 0) {
+                issues.push({
+                    category: "Images",
+                    severity: "medium",
+                    title: `${images.missingAlt} images missing alt text`,
+                    description: `${images.missingAlt} of ${images.totalImages} images have no alt attribute.`,
+                    recommendation: "Add descriptive alt text to all informative images.",
+                });
+            }
+            if (images.missingDimensions > 0) {
+                issues.push({
+                    category: "Images",
+                    severity: "low",
+                    title: `${images.missingDimensions} images missing dimensions`,
+                    description: `${images.missingDimensions} images lack width/height attributes, causing layout shift.`,
+                    recommendation: "Add width and height attributes to prevent CLS.",
+                });
+            }
+            if (images.fetchpriorityIssues?.length) {
+                for (const fi of images.fetchpriorityIssues) {
+                    issues.push({
+                        category: "Images",
+                        severity: "medium",
+                        title: fi,
+                        description: fi,
+                        recommendation: "Set fetchpriority=\"high\" on the LCP image and avoid it on small images.",
+                    });
+                }
+            }
+            if (images.ratioIssues?.length) {
+                issues.push({
+                    category: "Images",
+                    severity: "low",
+                    title: `${images.ratioIssues.length} image(s) with extreme aspect ratios`,
+                    description: `Extreme aspect ratios detected: ${images.ratioIssues.join("; ")}`,
+                    recommendation: "Review images with extreme aspect ratios; they may appear distorted.",
+                });
+            }
+            if (images.responsiveCoverage !== undefined && images.responsiveCoverage < 50) {
+                issues.push({
+                    category: "Images",
+                    severity: "medium",
+                    title: `Low responsive image coverage (${images.responsiveCoverage}%)`,
+                    description: `Only ${images.responsiveImages ?? 0} of ${images.totalImages} images use srcset, sizes, or picture elements.`,
+                    recommendation: "Add srcset and sizes attributes for responsive delivery.",
+                });
+            }
+            if (images.svgMissingTitle && images.svgMissingTitle > 0) {
+                issues.push({
+                    category: "Images",
+                    severity: "medium",
+                    title: `${images.svgMissingTitle} SVG(s) missing accessible title`,
+                    description: `${images.svgMissingTitle} inline SVGs lack a <title>, role="img", or aria-label.`,
+                    recommendation: "Add <title>, <desc>, or role=\"img\" with aria-label to SVGs.",
+                });
+            }
+            // Check for broken image URLs
+            if (images.images.length > 0) {
+                const { brokenUrls } = await checkImageUrls(images.images, config);
+                for (const url of brokenUrls) {
+                    issues.push({
+                        category: "Images",
+                        severity: "high",
+                        title: `Broken image: ${url}`,
+                        description: `Image returned a non-2xx status code: ${url}`,
+                        recommendation: "Replace or remove the broken image.",
+                    });
+                }
+            }
+            return {
+                key: "images",
+                score: images.score,
+                issues,
+                result: images,
+            };
+        });
     }
-    // Preload audit.
-    let preload;
     if (categories.includes("preload")) {
-        preload = auditPreload(fetchResult);
-        scores.push(preload.score);
-        for (const rec of preload.recommendations) {
-            allIssues.push({
+        subAuditFns.push(async () => {
+            const preload = auditPreload(fetchResult);
+            const issues = preload.recommendations.map((rec) => ({
                 category: "Preload",
                 severity: "medium",
                 title: rec,
                 description: rec,
                 recommendation: rec,
-            });
-        }
+            }));
+            return {
+                key: "preload",
+                score: preload.score,
+                issues,
+                result: preload,
+            };
+        });
+    }
+    let performanceFn;
+    if (categories.includes("performance")) {
+        performanceFn = async () => {
+            const available = await isRendererAvailable();
+            if (!available) {
+                // Fall back to heuristic performance analysis.
+                const perf = calculatePerformanceFromFetch(fetchResult, fetchResult.finalUrl);
+                const weight = analyzePageWeight(fetchResult, fetchResult.finalUrl);
+                return {
+                    key: "performance",
+                    score: perf.score,
+                    issues: [],
+                    result: { performance: perf, pageWeight: weight },
+                };
+            }
+            try {
+                const [mobileRender, desktopRender] = await Promise.allSettled([
+                    renderPage(url, config, {
+                        viewport: "mobile",
+                        capturePerformance: true,
+                        captureA11y: false,
+                        captureConsole: false,
+                        blockResources: [],
+                        timeout: config.timeout * 2,
+                        signal: controller.signal,
+                    }),
+                    renderPage(url, config, {
+                        viewport: "desktop",
+                        capturePerformance: true,
+                        captureA11y: false,
+                        captureConsole: false,
+                        blockResources: [],
+                        timeout: config.timeout * 2,
+                        signal: controller.signal,
+                    }),
+                ]);
+                const mobileOk = mobileRender.status === "fulfilled";
+                const desktopOk = desktopRender.status === "fulfilled";
+                if (!mobileOk && !desktopOk) {
+                    // Both renders failed — fall back to heuristic.
+                    const perf = calculatePerformanceFromFetch(fetchResult, fetchResult.finalUrl);
+                    const weight = analyzePageWeight(fetchResult, fetchResult.finalUrl);
+                    return {
+                        key: "performance",
+                        score: perf.score,
+                        issues: [],
+                        result: { performance: perf, pageWeight: weight },
+                    };
+                }
+                const mobileMeasured = mobileOk ? mobileRender.value.measuredPerformance : undefined;
+                const desktopMeasured = desktopOk ? desktopRender.value.measuredPerformance : undefined;
+                // Mobile-first SEO standard: main result = mobile
+                const perf = calculatePerformanceFromFetch(fetchResult, fetchResult.finalUrl, mobileMeasured);
+                let desktopPerf;
+                if (desktopMeasured) {
+                    desktopPerf = calculatePerformanceFromFetch(fetchResult, fetchResult.finalUrl, desktopMeasured);
+                    perf.desktop = desktopPerf;
+                }
+                const weight = analyzePageWeight(fetchResult, fetchResult.finalUrl, mobileMeasured);
+                // Weighted score: 60% mobile, 40% desktop
+                const mobileScore = perf.score;
+                const desktopScore = desktopPerf ? desktopPerf.score : mobileScore;
+                const weightedScore = Math.round(mobileScore * 0.6 + desktopScore * 0.4);
+                perf.score = weightedScore;
+                return {
+                    key: "performance",
+                    score: weightedScore,
+                    issues: [],
+                    result: { performance: perf, pageWeight: weight },
+                };
+            }
+            catch {
+                // Fall back to heuristic on any render failure.
+                const perf = calculatePerformanceFromFetch(fetchResult, fetchResult.finalUrl);
+                const weight = analyzePageWeight(fetchResult, fetchResult.finalUrl);
+                return {
+                    key: "performance",
+                    score: perf.score,
+                    issues: [],
+                    result: { performance: perf, pageWeight: weight },
+                };
+            }
+        };
     }
-    // Agent UX audit (requires rendering).
-    let agentUx;
+    let agentUxFn;
     if (categories.includes("agentUx")) {
-        const available = await isRendererAvailable();
-        if (available) {
+        agentUxFn = async () => {
+            const available = await isRendererAvailable();
+            if (!available) {
+                return {
+                    key: "agentUx",
+                    issues: [
+                        {
+                            category: "Agent UX",
+                            severity: "low",
+                            title: "Renderer unavailable — Agent UX audit skipped",
+                            description: "Headless renderer is not available; agent UX audit could not run.",
+                            recommendation: "Install or enable a headless browser to run the agent UX audit.",
+                        },
+                    ],
+                    skipped: true,
+                    result: { rendererAvailable: false },
+                };
+            }
             const renderResult = await renderPage(url, config, {
                 captureA11y: true,
                 captureConsole: false,
+                signal: controller.signal,
             });
-            agentUx = auditAgentUx(renderResult);
-            scores.push(agentUx.agentUxScore);
+            const comparison = compareStaticRendered(fetchResult, renderResult);
+            const issues = [];
+            if (comparison.isSpa || comparison.contentGrew) {
+                issues.push({
+                    category: "Rendering",
+                    severity: comparison.isSpa ? "high" : "medium",
+                    title: comparison.isSpa
+                        ? "Page appears to be a JavaScript-rendered SPA"
+                        : "Rendered content differs significantly from static HTML",
+                    description: comparison.notes.join(" ") || "Rendered DOM is significantly larger than static HTML.",
+                    recommendation: "Ensure critical content is present in server-rendered HTML or use SSR/SSG for SEO-critical content.",
+                });
+            }
+            const agentUx = auditAgentUx(renderResult);
             for (const opp of agentUx.opportunities) {
-                allIssues.push({
+                issues.push({
                     category: "Agent UX",
                     severity: "medium",
                     title: opp,
@@ -160,22 +394,73 @@ async function runFullAudit(url, config, categories) {
                     recommendation: opp,
                 });
             }
+            return {
+                key: "agentUx",
+                score: agentUx.agentUxScore,
+                issues,
+                result: { agentUx, renderComparison: comparison, rendererAvailable: true },
+            };
+        };
+    }
+    const outcomes = await Promise.allSettled([...subAuditFns, ...(agentUxFn ? [agentUxFn] : []), ...(performanceFn ? [performanceFn] : [])].map((fn) => fn()));
+    clearTimeout(timeout);
+    const resultMap = new Map();
+    for (const outcome of outcomes) {
+        if (outcome.status === "fulfilled") {
+            const value = outcome.value;
+            resultMap.set(value.key, value);
+            allIssues.push(...value.issues);
+            if (typeof value.score === "number") {
+                scores.push(value.score);
+            }
+        }
+        else {
+            allIssues.push({
+                category: "Audit",
+                severity: "medium",
+                title: "Sub-audit failed",
+                description: `A sub-audit rejected: ${outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason)}`,
+                recommendation: "Review the failing sub-audit and re-run the full audit.",
+            });
         }
     }
+    const technical = resultMap.get("technical")?.result;
+    const content = resultMap.get("content")?.result;
+    const schema = resultMap.get("schema")?.result;
+    const images = resultMap.get("images")?.result;
+    const preload = resultMap.get("preload")?.result;
+    const agentUx = resultMap.get("agentUx")?.result;
+    const rendererAvailable = agentUx && "rendererAvailable" in agentUx ? agentUx.rendererAvailable : false;
+    const renderComparison = agentUx && "renderComparison" in agentUx ? agentUx.renderComparison : undefined;
+    const agentUxResult = agentUx && "agentUx" in agentUx ? agentUx.agentUx : undefined;
+    const performancePayload = resultMap.get("performance")?.result;
+    const performanceResult = performancePayload?.performance;
+    const pageWeightResult = performancePayload?.pageWeight;
     const overallScore = scores.length > 0
         ? Math.round(scores.reduce((a, b) => a + b, 0) / scores.length)
         : 0;
+    const coverage = Math.round((scores.length / ALL_CATEGORIES.length) * 100);
+    const confidence = coverage === 100 ? "high" : coverage >= 50 ? "medium" : "low";
     const summary = `SEO audit for ${fetchResult.finalUrl} — Overall score: ${overallScore}/100, ${allIssues.length} issues found.`;
     return {
         url: fetchResult.finalUrl,
         auditedAt: new Date().toISOString(),
         overallScore,
+        coverage,
+        confidence,
+        skippedCategories,
+        rendererAvailable,
+        renderComparison,
+        version: 2,
+        warnings: [],
         technical,
         content,
         schema,
         images,
         preload,
-        agentUx,
+        agentUx: agentUxResult,
+        performance: performanceResult,
+        pageWeight: pageWeightResult,
         allIssues,
         summary,
     };
@@ -189,3 +474,43 @@ function severityRank(s) {
         default: return 4;
     }
 }
+function compareStaticRendered(fetchResult, renderResult) {
+    const staticPage = parsePage(fetchResult.content, fetchResult.finalUrl);
+    const renderedPage = parsePage(renderResult.content, renderResult.finalUrl);
+    const staticText = extractText(fetchResult.content).split(/\s+/).filter(Boolean);
+    const renderedText = extractText(renderResult.content).split(/\s+/).filter(Boolean);
+    const textDelta = renderedText.length - staticText.length;
+    const headingDelta = renderedPage.headings.length - staticPage.headings.length;
+    const linkDelta = renderedPage.internalLinkCount + renderedPage.externalLinkCount -
+        (staticPage.internalLinkCount + staticPage.externalLinkCount);
+    const imageDelta = renderedPage.images.length - staticPage.images.length;
+    const schemaDelta = renderedPage.schemaBlocks.length - staticPage.schemaBlocks.length;
+    const notes = [];
+    if (renderResult.isSpa)
+        notes.push("Initial HTML is small relative to rendered DOM (SPA signature).");
+    if (textDelta > staticText.length * 0.25)
+        notes.push(`Rendered text grew by ${textDelta} words (${Math.round((textDelta / Math.max(1, staticText.length)) * 100)}%).`);
+    if (headingDelta > 0)
+        notes.push(`${headingDelta} new headings appeared after render.`);
+    if (linkDelta > 0)
+        notes.push(`${linkDelta} new links appeared after render.`);
+    if (imageDelta > 0)
+        notes.push(`${imageDelta} new images appeared after render.`);
+    if (schemaDelta > 0)
+        notes.push(`${schemaDelta} new JSON-LD blocks appeared after render.`);
+    if (renderResult.consoleErrors.length > 0)
+        notes.push(`${renderResult.consoleErrors.length} console errors during render.`);
+    return {
+        staticByteLength: Buffer.byteLength(fetchResult.content, "utf-8"),
+        renderedByteLength: Buffer.byteLength(renderResult.content, "utf-8"),
+        contentGrew: textDelta > staticText.length * 0.25 ||
+            (renderResult.rawContent.length > 0 && renderResult.content.length > renderResult.rawContent.length * 1.5),
+        isSpa: renderResult.isSpa,
+        textDelta,
+        headingDelta,
+        linkDelta,
+        imageDelta,
+        schemaDelta,
+        notes,
+    };
+}

package/dist/extensions/seo/tools/helpers.d.ts

@@ -2,12 +2,23 @@
  * Helper utilities for SEO tool implementations.
  */
 import type { AgentToolResult } from "../../../sdk/coding-agent/index.js";
-/** Create a text-only tool result. */
-export declare function textResult(text: string, details?: Record<string, unknown>): AgentToolResult<Record<string, unknown>>;
-/** Create an error tool result. */
-export declare function errorResult(message: string, details?: Record<string, unknown>): AgentToolResult<Record<string, unknown>>;
+/** Structured details for tool results. */
+export interface ToolDetails<T = unknown> {
+    isError?: boolean;
+    result?: T;
+    warnings?: string[];
+    metadata?: Record<string, unknown>;
+}
+/** Version of the SEO tool result schema. Increment on breaking changes. */
+export declare const SEO_RESULT_VERSION = 2;
+/** Create a text tool result. Accepts either legacy (text, details) or new (text, result, warnings). */
+export declare function textResult(text: string, detailsOrResult?: Record<string, unknown> | unknown, warnings?: string[]): AgentToolResult<ToolDetails>;
+/** Create an error tool result. Accepts either legacy (msg, details) or new (msg, result, warnings). */
+export declare function errorResult(message: string, detailsOrResult?: Record<string, unknown> | unknown, warnings?: string[]): AgentToolResult<ToolDetails>;
 /** Format a JSON object as pretty-printed text for tool output. */
 export declare function jsonText(obj: unknown): string;
 /** Truncate text to a maximum length. */
 export declare function truncate(text: string, maxLen: number): string;
+/** Validate and normalize a tool URL input, enforcing length limits. */
+export declare function validateToolUrl(raw: string, maxLen?: number): string;
 //# sourceMappingURL=helpers.d.ts.map

package/dist/extensions/seo/tools/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/tools/helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAE1E,sCAAsC;AACtC,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,eAAe,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAKxH;AAED,mCAAmC;AACnC,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,eAAe,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAK5H;AAED,mEAAmE;AACnE,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAE7C;AAED,yCAAyC;AACzC,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAG7D"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/tools/helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAE1E,2CAA2C;AAC3C,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO;IACtC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,CAAC,CAAC;IACX,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC,wGAAwG;AACxG,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,EACnD,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,eAAe,CAAC,WAAW,CAAC,CAwB9B;AAED,wGAAwG;AACxG,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,EACnD,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,eAAe,CAAC,WAAW,CAAC,CAyB9B;AAED,mEAAmE;AACnE,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAE7C;AAED,yCAAyC;AACzC,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAG7D;AAED,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,SAAO,GAAG,MAAM,CAOlE"}