@aexol/spectral 0.9.125 → 0.9.127

package/dist/extensions/seo/tools/helpers.js

@@ -1,15 +1,56 @@
-/** Create a text-only tool result. */
-export function textResult(text, details = {}) {
+/** Version of the SEO tool result schema. Increment on breaking changes. */
+export const SEO_RESULT_VERSION = 2;
+/** Create a text tool result. Accepts either legacy (text, details) or new (text, result, warnings). */
+export function textResult(text, detailsOrResult, warnings) {
+    // Detect legacy call: second arg is a plain object with string keys.
+    const isLegacy = detailsOrResult !== undefined
+        && typeof detailsOrResult === "object"
+        && detailsOrResult !== null
+        && !Array.isArray(detailsOrResult);
+    if (isLegacy) {
+        const details = detailsOrResult;
+        return {
+            content: [{ type: "text", text }],
+            details: {
+                ...details,
+                metadata: { ...(details.metadata ?? {}), version: SEO_RESULT_VERSION },
+            },
+        };
+    }
     return {
         content: [{ type: "text", text }],
-        details,
+        details: {
+            result: detailsOrResult,
+            warnings: warnings ?? [],
+            metadata: { version: SEO_RESULT_VERSION },
+        },
     };
 }
-/** Create an error tool result. */
-export function errorResult(message, details = {}) {
+/** Create an error tool result. Accepts either legacy (msg, details) or new (msg, result, warnings). */
+export function errorResult(message, detailsOrResult, warnings) {
+    const isLegacy = detailsOrResult !== undefined
+        && typeof detailsOrResult === "object"
+        && detailsOrResult !== null
+        && !Array.isArray(detailsOrResult);
+    if (isLegacy) {
+        const details = detailsOrResult;
+        return {
+            content: [{ type: "text", text: `❌ ${message}` }],
+            details: {
+                isError: true,
+                ...details,
+                metadata: { ...(details.metadata ?? {}), version: SEO_RESULT_VERSION },
+            },
+        };
+    }
     return {
         content: [{ type: "text", text: `❌ ${message}` }],
-        details: { isError: true, ...details },
+        details: {
+            isError: true,
+            result: detailsOrResult,
+            warnings: warnings ?? [],
+            metadata: { version: SEO_RESULT_VERSION },
+        },
     };
 }
 /** Format a JSON object as pretty-printed text for tool output. */
@@ -22,3 +63,13 @@ export function truncate(text, maxLen) {
         return text;
     return text.slice(0, maxLen) + "... (truncated)";
 }
+/** Validate and normalize a tool URL input, enforcing length limits. */
+export function validateToolUrl(raw, maxLen = 4096) {
+    const trimmed = raw.trim();
+    if (trimmed.length > maxLen) {
+        throw new Error(`URL exceeds maximum length of ${maxLen} characters.`);
+    }
+    if (!trimmed)
+        throw new Error("URL is required.");
+    return trimmed;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"performance.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/tools/performance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAW9C,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CA4NnF"}
+{"version":3,"file":"performance.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/tools/performance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAS9C,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CA8MnF"}

package/dist/extensions/seo/tools/performance.js

@@ -2,14 +2,13 @@ import { fetchPage } from "../utils/fetcher.js";
 import { calculatePerformanceFromFetch, analyzePageWeight, analyzeRenderBlocking, analyzeFonts, } from "../analyzers/performance.js";
 import { errorResult, textResult } from "./helpers.js";
 export function registerPerformanceTools(ext, config) {
-    // === seo_performance ===
     const perfTool = {
         name: "seo_performance",
         label: "SEO Performance Audit (Core Web Vitals)",
         description: "Estimate Core Web Vitals metrics from page structure analysis. " +
             "Reports LCP (Largest Contentful Paint), CLS (Cumulative Layout Shift), TBT (Total Blocking Time), FCP, and TTFB. " +
             "Each metric is rated: good, needs-improvement, or poor against Google's thresholds. " +
-            "Note: These are heuristic estimates based on page complexity. For accurate numbers use Lighthouse or PageSpeed Insights.",
+            "When a browser is available, real Web Vitals are measured via Playwright.",
         promptSnippet: "`seo_performance { url }` — estimate Core Web Vitals (LCP, CLS, TBT) with ratings",
         parameters: {
             type: "object",
@@ -22,7 +21,17 @@ export function registerPerformanceTools(ext, config) {
             const { url } = params;
             try {
                 const fetchResult = await fetchPage(url, config);
-                const perf = calculatePerformanceFromFetch(fetchResult, url);
+                let measuredPerformance = undefined;
+                try {
+                    const { isRendererAvailable, renderPage } = await import("../utils/renderer.js");
+                    if (await isRendererAvailable()) {
+                        const rendered = await renderPage(url, config, { capturePerformance: true });
+                        if (rendered.measuredPerformance)
+                            measuredPerformance = rendered.measuredPerformance;
+                    }
+                }
+                catch { /* renderer not available */ }
+                const perf = calculatePerformanceFromFetch(fetchResult, url, measuredPerformance);
                 const lines = [
                     `✓ Performance Estimate: ${perf.url}`,
                     ``,
@@ -34,8 +43,8 @@ export function registerPerformanceTools(ext, config) {
                     `  TBT: ${perf.tbt.value}ms — ${perf.tbt.rating.toUpperCase()}`,
                     ``,
                     `Other Metrics:`,
-                    `  FCP: ${perf.fcp}ms`,
-                    `  TTFB: ${perf.ttfb}ms`,
+                    `  FCP: ${perf.fcp.value}ms (${perf.fcp.rating})`,
+                    `  TTFB: ${perf.ttfb.value}ms (${perf.ttfb.rating})`,
                     ``,
                     `Google Thresholds:`,
                     `  LCP: good ≤ 2500ms, poor > 4000ms`,
@@ -49,7 +58,6 @@ export function registerPerformanceTools(ext, config) {
             }
         },
     };
-    // === seo_page_weight ===
     const weightTool = {
         name: "seo_page_weight",
         label: "SEO Page Weight Analysis",
@@ -84,11 +92,11 @@ export function registerPerformanceTools(ext, config) {
                 if (weight.topHeavyResources.length > 0) {
                     lines.push(``, `Heaviest resources:`);
                     for (const r of weight.topHeavyResources) {
-                        lines.push(`  ${r.type.toUpperCase()}: ${r.sizeKb} KB — ${r.url}`);
+                        lines.push(`  ${r.type.toUpperCase()}: ${r.url} (${r.sizeKb} KB)`);
                     }
                 }
-                if (weight.totalKb > 5000) {
-                    lines.push(``, `⚠ Page exceeds 5MB — may impact mobile performance.`);
+                if (weight.totalKb < 500) {
+                    lines.push(``, `✓ Page weight is excellent.`);
                 }
                 else if (weight.totalKb > 2000) {
                     lines.push(``, `⚡ Page weight is above average. Consider optimizing assets.`);
@@ -100,7 +108,6 @@ export function registerPerformanceTools(ext, config) {
             }
         },
     };
-    // === seo_render_blocking ===
     const blockingTool = {
         name: "seo_render_blocking",
         label: "SEO Render-Blocking Resource Audit",
@@ -151,7 +158,6 @@ export function registerPerformanceTools(ext, config) {
             }
         },
     };
-    // === seo_font_audit ===
     const fontTool = {
         name: "seo_font_audit",
         label: "SEO Font Optimization Audit",

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

@@ -1 +1 @@
-{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/tools/report.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAI9C,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CA+E9E"}
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/tools/report.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAqB9C,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAgH9E"}