@aexol/spectral 0.9.42 → 0.9.43

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

@@ -0,0 +1,104 @@
+import { captureBaseline, compareBaseline, getBaselineHistory } from "../analyzers/drift.js";
+import { errorResult, textResult } from "./helpers.js";
+export function registerDriftTools(ext, config) {
+    const baselineTool = {
+        name: "seo_drift_baseline",
+        label: "SEO Drift Baseline",
+        description: "Capture an SEO baseline snapshot of a page and store it in a local SQLite database. " +
+            "Records: title, meta description, canonical, robots, H1/H2/H3 headings, schema blocks, Open Graph tags, " +
+            "HTML hash, schema hash, and status code. Use seo_drift_compare later to detect changes. " +
+            "Database path: configured by SEO_DB_PATH (default: ~/.spectral/seo/drift.db).",
+        promptSnippet: "`seo_drift_baseline { url }` — capture an SEO baseline snapshot for drift monitoring",
+        parameters: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "The URL to capture a baseline for." },
+            },
+            required: ["url"],
+        },
+        async execute(_toolCallId, params) {
+            const { url } = params;
+            try {
+                const baseline = await captureBaseline(url, config);
+                const summary = `✓ Baseline captured: ${baseline.url}\n` +
+                    `Baseline ID: ${baseline.id}\n` +
+                    `Timestamp: ${baseline.timestamp}\n` +
+                    `Title: ${baseline.title ?? "(none)"}\n` +
+                    `Canonical: ${baseline.canonical ?? "(none)"}\n` +
+                    `H1: ${baseline.h1 ?? "(none)"}\n` +
+                    `Status Code: ${baseline.statusCode}\n` +
+                    `HTML Hash: ${baseline.htmlHash}\n` +
+                    `Schema Hash: ${baseline.schemaHash}`;
+                return textResult(summary, { baseline });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    const compareTool = {
+        name: "seo_drift_compare",
+        label: "SEO Drift Compare",
+        description: "Compare a page's current state against a previously captured baseline. " +
+            "Detects changes in: title, meta description, canonical, robots, H1/H2/H3 headings, schema blocks, " +
+            "status code, and HTML hash. Assigns a severity level (none/low/medium/high) based on which fields changed. " +
+            "If baselineId is omitted, compares against the latest baseline for the URL.",
+        promptSnippet: "`seo_drift_compare { url, baselineId? }` — compare current page vs baseline snapshot",
+        parameters: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "The URL to compare." },
+                baselineId: { type: "number", description: "Specific baseline ID to compare against. If omitted, uses the latest." },
+            },
+            required: ["url"],
+        },
+        async execute(_toolCallId, params) {
+            const { url, baselineId } = params;
+            try {
+                const result = await compareBaseline(url, config, baselineId);
+                const summary = `✓ Drift Comparison: ${result.url}\n` +
+                    `Baseline ID: ${result.baselineId} (${result.baselineTimestamp})\n` +
+                    `Compared At: ${result.comparedAt}\n` +
+                    `Severity: ${result.severity.toUpperCase()}\n` +
+                    `Changed Fields (${result.changedFields.length}): ${result.changedFields.join(", ") || "(none)"}`;
+                return textResult(summary, { result });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    const historyTool = {
+        name: "seo_drift_history",
+        label: "SEO Drift History",
+        description: "List baseline snapshots for a URL, ordered by most recent. " +
+            "Returns baseline IDs, timestamps, titles, and status codes.",
+        promptSnippet: "`seo_drift_history { url, limit? }` — list baseline snapshots for a URL",
+        parameters: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "The URL to get baseline history for." },
+                limit: { type: "number", description: "Maximum number of baselines to return. Default: 20." },
+            },
+            required: ["url"],
+        },
+        async execute(_toolCallId, params) {
+            const { url, limit } = params;
+            try {
+                const history = getBaselineHistory(url, config, limit ?? 20);
+                const summary = `✓ Drift History: ${url}\n` +
+                    `Baselines: ${history.length}\n\n` +
+                    history
+                        .map((b) => `  #${b.id} | ${b.timestamp} | ${b.statusCode} | ${b.title ?? "(no title)"}`)
+                        .join("\n");
+                return textResult(summary, { history });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    ext.registerTool(baselineTool);
+    ext.registerTool(compareTool);
+    ext.registerTool(historyTool);
+}

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

@@ -0,0 +1,7 @@
+/**
+ * seo_fetch and seo_render tool definitions.
+ */
+import type { ExtensionAPI } from "../../../sdk/coding-agent/index.js";
+import type { SeoConfig } from "../config.js";
+export declare function registerFetchTools(ext: ExtensionAPI, config: SeoConfig): void;
+//# sourceMappingURL=fetch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/tools/fetch.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAK9C,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CA0I7E"}

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

@@ -0,0 +1,123 @@
+import { fetchPage } from "../utils/fetcher.js";
+import { renderPage, isRendererAvailable } from "../utils/renderer.js";
+import { errorResult, textResult, truncate } from "./helpers.js";
+export function registerFetchTools(ext, config) {
+    const fetchTool = {
+        name: "seo_fetch",
+        label: "SEO Fetch Page",
+        description: "Fetch a web page's HTML content with full redirect-chain tracking, status code, and response headers. " +
+            "Uses SSRF protection to block private/internal IPs. Does NOT execute JavaScript — use seo_render for SPA pages.",
+        promptSnippet: "`seo_fetch { url, userAgent?, timeout? }` — fetch a page's HTML with redirect tracking",
+        promptGuidelines: [
+            "When the user asks about SEO, search optimization, page audits, schema markup, sitemaps, or technical SEO for any website or URL, use the seo_* tools (seo_fetch, seo_parse_page, seo_technical_audit, seo_content_quality, seo_schema_audit, seo_image_audit, seo_preload_audit, seo_agent_ux_audit, seo_audit, etc.). These are offline-first and require no API keys.",
+        ],
+        parameters: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "The URL to fetch. https:// is prepended if missing." },
+                userAgent: {
+                    type: "string",
+                    description: "User agent: 'default', 'googlebot', or a custom UA string. Default: 'default'.",
+                },
+                timeout: { type: "number", description: "Request timeout in milliseconds. Default: 30000." },
+                followRedirects: { type: "boolean", description: "Whether to follow HTTP redirects. Default: true." },
+            },
+            required: ["url"],
+        },
+        async execute(_toolCallId, params) {
+            const { url, userAgent, timeout, followRedirects } = params;
+            try {
+                const result = await fetchPage(url, config, {
+                    userAgent: userAgent ?? "default",
+                    timeout,
+                    followRedirects,
+                });
+                if (result.error) {
+                    return errorResult(`Fetch failed: ${result.error}`, { result });
+                }
+                const summary = `✓ Fetched: ${result.finalUrl}\n` +
+                    `Status: ${result.statusCode} ${result.statusText}\n` +
+                    `Redirects: ${result.redirectChain.length}\n` +
+                    `Content-Length: ${result.contentLengthBytes} bytes\n` +
+                    `Headers: ${Object.keys(result.headers).join(", ")}`;
+                return textResult(summary, {
+                    url: result.url,
+                    finalUrl: result.finalUrl,
+                    statusCode: result.statusCode,
+                    content: truncate(result.content, 50_000),
+                    headers: result.headers,
+                    redirectChain: result.redirectChain,
+                });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    const renderTool = {
+        name: "seo_render",
+        label: "SEO Render Page",
+        description: "Render a web page with Playwright (Chromium) to get the full DOM after JavaScript execution. " +
+            "Use this for SPA pages where critical content is injected via JS. " +
+            "Slower than seo_fetch but necessary for JavaScript-heavy sites. " +
+            "Optionally captures the accessibility tree (for agent UX audits) and console errors.",
+        promptSnippet: "`seo_render { url, viewport?, captureA11y? }` — render a page with Playwright (SPA-aware)",
+        parameters: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "The URL to render." },
+                viewport: {
+                    type: "string",
+                    enum: ["desktop", "mobile"],
+                    description: "Viewport size. Default: 'desktop'.",
+                },
+                captureA11y: {
+                    type: "boolean",
+                    description: "Whether to capture the accessibility tree. Default: false.",
+                },
+                captureConsole: {
+                    type: "boolean",
+                    description: "Whether to capture console errors. Default: true.",
+                },
+                timeout: { type: "number", description: "Render timeout in milliseconds. Default: 30000." },
+            },
+            required: ["url"],
+        },
+        async execute(_toolCallId, params) {
+            const { url, viewport, captureA11y, captureConsole, timeout } = params;
+            const available = await isRendererAvailable();
+            if (!available) {
+                return errorResult("Playwright Chromium is not available. Install it with: npx playwright install chromium");
+            }
+            try {
+                const result = await renderPage(url, config, {
+                    viewport,
+                    captureA11y,
+                    captureConsole,
+                    timeout,
+                });
+                const summary = `✓ Rendered: ${result.finalUrl}\n` +
+                    `Status: ${result.statusCode}\n` +
+                    `SPA: ${result.isSpa}\n` +
+                    `Render time: ${result.renderMs}ms\n` +
+                    `Console errors: ${result.consoleErrors.length}`;
+                return textResult(summary, {
+                    url: result.url,
+                    finalUrl: result.finalUrl,
+                    statusCode: result.statusCode,
+                    content: truncate(result.content, 50_000),
+                    rawContent: truncate(result.rawContent, 20_000),
+                    isSpa: result.isSpa,
+                    consoleErrors: result.consoleErrors,
+                    renderMs: result.renderMs,
+                    accessibilityTree: result.accessibilityTree,
+                });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    ext.registerTool(fetchTool);
+    ext.registerTool(renderTool);
+}

package/dist/extensions/seo/tools/full-audit.d.ts

@@ -0,0 +1,10 @@
+/**
+ * seo_audit tool — full audit orchestrator.
+ *
+ * Runs multiple sub-audits in a single call and aggregates results into a
+ * combined report with an overall score and prioritized issue list.
+ */
+import type { ExtensionAPI } from "../../../sdk/coding-agent/index.js";
+import type { SeoConfig } from "../config.js";
+export declare function registerFullAuditTools(ext: ExtensionAPI, config: SeoConfig): void;
+//# sourceMappingURL=full-audit.d.ts.map

package/dist/extensions/seo/tools/full-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"full-audit.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/tools/full-audit.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAiB9C,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CA+DjF"}

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

@@ -0,0 +1,191 @@
+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 { auditPreload } from "../analyzers/preload.js";
+import { auditAgentUx } from "../analyzers/agent-ux.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"];
+export function registerFullAuditTools(ext, config) {
+    const fullAuditTool = {
+        name: "seo_audit",
+        label: "SEO Full Audit",
+        description: "Run a comprehensive SEO audit in a single call. Combines: technical audit (crawlability, security, mobile, AI crawlers), " +
+            "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)",
+        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.",
+        ],
+        parameters: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "The URL to audit." },
+                include: {
+                    type: "array",
+                    items: {
+                        type: "string",
+                        enum: ["technical", "content", "schema", "images", "preload", "agentUx"],
+                    },
+                    description: "Sub-audits to include. If omitted, runs all sub-audits.",
+                },
+            },
+            required: ["url"],
+        },
+        async execute(_toolCallId, params) {
+            const { url, include } = params;
+            try {
+                const categories = include ?? ALL_CATEGORIES;
+                const result = await runFullAudit(url, config, categories);
+                const issueLines = result.allIssues
+                    .sort((a, b) => severityRank(a.severity) - severityRank(b.severity))
+                    .slice(0, 30)
+                    .map((i) => `  [${i.severity.toUpperCase()}] ${i.category}: ${i.title}`)
+                    .join("\n");
+                const summary = `✓ Full SEO Audit: ${result.url}\n` +
+                    `Audited At: ${result.auditedAt}\n` +
+                    `Overall Score: ${result.overallScore}/100\n\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` +
+                    `Top Issues (${result.allIssues.length} total):\n${issueLines || "  (none)"}`;
+                return textResult(summary, { result });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    ext.registerTool(fullAuditTool);
+}
+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;
+    if (categories.includes("technical")) {
+        technical = await auditTechnical(url, config, pageData, fetchResult);
+        allIssues.push(...technical.issues);
+        scores.push(technical.score);
+    }
+    // Content quality.
+    let content;
+    if (categories.includes("content")) {
+        const text = extractText(fetchResult.content);
+        content = analyzeContentQuality(text, fetchResult.finalUrl);
+        scores.push(content.overallQuality);
+    }
+    // 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({
+                category: "Schema",
+                severity: "medium",
+                title: rec,
+                description: rec,
+                recommendation: rec,
+            });
+        }
+    }
+    // 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.",
+            });
+        }
+    }
+    // Preload audit.
+    let preload;
+    if (categories.includes("preload")) {
+        preload = auditPreload(fetchResult);
+        scores.push(preload.score);
+        for (const rec of preload.recommendations) {
+            allIssues.push({
+                category: "Preload",
+                severity: "medium",
+                title: rec,
+                description: rec,
+                recommendation: rec,
+            });
+        }
+    }
+    // Agent UX audit (requires rendering).
+    let agentUx;
+    if (categories.includes("agentUx")) {
+        const available = await isRendererAvailable();
+        if (available) {
+            const renderResult = await renderPage(url, config, {
+                captureA11y: true,
+                captureConsole: false,
+            });
+            agentUx = auditAgentUx(renderResult);
+            scores.push(agentUx.agentUxScore);
+            for (const opp of agentUx.opportunities) {
+                allIssues.push({
+                    category: "Agent UX",
+                    severity: "medium",
+                    title: opp,
+                    description: opp,
+                    recommendation: opp,
+                });
+            }
+        }
+    }
+    const overallScore = scores.length > 0
+        ? Math.round(scores.reduce((a, b) => a + b, 0) / scores.length)
+        : 0;
+    const summary = `SEO audit for ${fetchResult.finalUrl} — Overall score: ${overallScore}/100, ${allIssues.length} issues found.`;
+    return {
+        url: fetchResult.finalUrl,
+        auditedAt: new Date().toISOString(),
+        overallScore,
+        technical,
+        content,
+        schema,
+        images,
+        preload,
+        agentUx,
+        allIssues,
+        summary,
+    };
+}
+function severityRank(s) {
+    switch (s) {
+        case "critical": return 0;
+        case "high": return 1;
+        case "medium": return 2;
+        case "low": return 3;
+        default: return 4;
+    }
+}

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

@@ -0,0 +1,13 @@
+/**
+ * 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>>;
+/** 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;
+//# sourceMappingURL=helpers.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,24 @@
+/** Create a text-only tool result. */
+export function textResult(text, details = {}) {
+    return {
+        content: [{ type: "text", text }],
+        details,
+    };
+}
+/** Create an error tool result. */
+export function errorResult(message, details = {}) {
+    return {
+        content: [{ type: "text", text: `❌ ${message}` }],
+        details: { isError: true, ...details },
+    };
+}
+/** Format a JSON object as pretty-printed text for tool output. */
+export function jsonText(obj) {
+    return JSON.stringify(obj, null, 2);
+}
+/** Truncate text to a maximum length. */
+export function truncate(text, maxLen) {
+    if (text.length <= maxLen)
+        return text;
+    return text.slice(0, maxLen) + "... (truncated)";
+}

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

@@ -0,0 +1,7 @@
+/**
+ * seo_image_audit tool.
+ */
+import type { ExtensionAPI } from "../../../sdk/coding-agent/index.js";
+import type { SeoConfig } from "../config.js";
+export declare function registerImageTools(ext: ExtensionAPI, config: SeoConfig): void;
+//# sourceMappingURL=images.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"images.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/tools/images.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAK9C,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CA8C7E"}

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

@@ -0,0 +1,46 @@
+import { auditImages } from "../analyzers/images.js";
+import { fetchPage } from "../utils/fetcher.js";
+import { errorResult, textResult } from "./helpers.js";
+export function registerImageTools(ext, config) {
+    const imageTool = {
+        name: "seo_image_audit",
+        label: "SEO Image Audit",
+        description: "Audit all images on a page for SEO issues: missing alt text, missing width/height dimensions, " +
+            "lazy-loading method (native, data-src, data-lazy, none), modern format usage (WebP, AVIF, JXL), " +
+            "and oversized images (>2000px). Returns per-image details and aggregate counts.",
+        promptSnippet: "`seo_image_audit { url }` — audit images for alt, dimensions, lazy loading, modern formats",
+        parameters: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "The URL to audit for image SEO." },
+            },
+            required: ["url"],
+        },
+        async execute(_toolCallId, params) {
+            const { url } = params;
+            try {
+                const result = await fetchPage(url, config);
+                if (result.error) {
+                    return errorResult(`Fetch failed: ${result.error}`);
+                }
+                const audit = auditImages(result.content, result.finalUrl);
+                const summary = `✓ Image Audit: ${result.finalUrl}\n` +
+                    `Total Images: ${audit.totalImages}\n` +
+                    `Missing Alt: ${audit.missingAlt} ${audit.missingAlt > 0 ? "⚠️" : "✓"}\n` +
+                    `Missing Dimensions: ${audit.missingDimensions} ${audit.missingDimensions > 0 ? "⚠️" : "✓"}\n\n` +
+                    `Lazy Loading:\n` +
+                    `  Native (loading="lazy"): ${audit.lazyLoading.native}\n` +
+                    `  data-src: ${audit.lazyLoading.dataSrc}\n` +
+                    `  data-lazy: ${audit.lazyLoading.dataLazy}\n` +
+                    `  None: ${audit.lazyLoading.none}\n\n` +
+                    `Modern Formats: ${audit.modernFormats} (WebP/AVIF/JXL)\n` +
+                    `Oversized (>2000px): ${audit.oversized.length}`;
+                return textResult(summary, { audit });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    ext.registerTool(imageTool);
+}

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

@@ -0,0 +1,7 @@
+/**
+ * seo_parasite_risk tool — parasite-SEO risk scanner.
+ */
+import type { ExtensionAPI } from "../../../sdk/coding-agent/index.js";
+import type { SeoConfig } from "../config.js";
+export declare function registerParasiteTools(ext: ExtensionAPI, config: SeoConfig): void;
+//# sourceMappingURL=parasite.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"parasite.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/tools/parasite.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAI9C,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CA0DhF"}

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

@@ -0,0 +1,53 @@
+import { scanParasiteRisk } from "../analyzers/parasite.js";
+import { errorResult, textResult } from "./helpers.js";
+export function registerParasiteTools(ext, config) {
+    const parasiteTool = {
+        name: "seo_parasite_risk",
+        label: "SEO Parasite Risk",
+        description: "Scan a list of URLs from one host for parasite-SEO risk. Fetches each URL and classifies content " +
+            "by subfolder, flagging section-level risk via: third-party byline patterns (Partner Content, Sponsored, " +
+            "Brand Studio), commercial-intent patterns (Buy Now, Promo Code, Coupon), and affiliate link markers " +
+            "(tag=, aff_id=, ref_=). Returns per-subfolder risk classification (high/medium/low). " +
+            "Per Google's 2024-11-19 policy, section-level manual actions target this pattern.",
+        promptSnippet: "`seo_parasite_risk { urls }` — scan URLs for parasite-SEO risk per subfolder",
+        parameters: {
+            type: "object",
+            properties: {
+                urls: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "List of URLs from one host to scan. Typically obtained from sitemap sampling.",
+                },
+            },
+            required: ["urls"],
+        },
+        async execute(_toolCallId, params) {
+            const { urls } = params;
+            try {
+                if (!urls || urls.length === 0) {
+                    return errorResult("At least one URL is required.");
+                }
+                const result = await scanParasiteRisk(urls, config);
+                const sectionLines = result.sections
+                    .sort((a, b) => {
+                    const rank = { high: 0, medium: 1, low: 2 };
+                    return rank[a.risk] - rank[b.risk];
+                })
+                    .map((s) => `  [${s.risk.toUpperCase()}] ${s.section} (${s.pageCount} pages) — ` +
+                    `3rd-party: ${s.thirdPartyHitsPerPage}/page, commerce: ${s.commerceHitsPerPage}/page, ` +
+                    `affiliate: ${s.affiliateLinkHitsPerPage}/page` +
+                    (s.flags.length > 0 ? ` [${s.flags.join(", ")}]` : ""))
+                    .join("\n");
+                const summary = `✓ Parasite Risk Scan: ${result.host}\n` +
+                    `Total Pages: ${result.totalPages}\n` +
+                    `Sections Scanned: ${result.sections.length}\n\n` +
+                    `Section Risk:\n${sectionLines}`;
+                return textResult(summary, { result });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    ext.registerTool(parasiteTool);
+}

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

@@ -0,0 +1,7 @@
+/**
+ * seo_parse_page tool — extract on-page SEO data from HTML.
+ */
+import type { ExtensionAPI } from "../../../sdk/coding-agent/index.js";
+import type { SeoConfig } from "../config.js";
+export declare function registerParseTools(ext: ExtensionAPI, config: SeoConfig): void;
+//# sourceMappingURL=parse.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/tools/parse.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAK9C,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CA0E7E"}