@aexol/spectral 0.9.43 → 0.9.44

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

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

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

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

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

@@ -0,0 +1,193 @@
+import { auditTechnical } from "../analyzers/technical.js";
+import { analyzeContentQuality } from "../analyzers/content.js";
+import { fetchPage } from "../utils/fetcher.js";
+import { parsePage, extractText } from "../utils/parser.js";
+import { analyzeKeywords } from "../analyzers/keywords.js";
+import { analyzeReadability } from "../analyzers/readability.js";
+import { errorResult, textResult, truncate } from "./helpers.js";
+export function registerBatchTools(ext, config) {
+    // === seo_audit_batch ===
+    const batchTool = {
+        name: "seo_audit_batch",
+        label: "SEO Batch Audit",
+        description: "Run SEO audits on multiple URLs, typically from a sitemap. " +
+            "Audits each URL for technical SEO, content quality, and schema markup. " +
+            "Returns a comparison table with scores for each page. " +
+            "Use this after seo_crawl to audit all discovered subpages at once.",
+        promptSnippet: "`seo_audit_batch { urls[] }` — audit multiple URLs and compare scores",
+        parameters: {
+            type: "object",
+            properties: {
+                urls: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "List of URLs to audit.",
+                },
+                maxPages: {
+                    type: "number",
+                    description: "Max URLs to audit (limits batch size). Default: 20.",
+                },
+            },
+            required: ["urls"],
+        },
+        async execute(_toolCallId, params) {
+            const { urls, maxPages } = params;
+            try {
+                const toAudit = urls.slice(0, maxPages ?? 20);
+                const results = [];
+                for (const url of toAudit) {
+                    try {
+                        const fetchResult = await fetchPage(url, config);
+                        const pageData = parsePage(fetchResult.content, fetchResult.finalUrl);
+                        const technical = await auditTechnical(url, config, pageData, fetchResult);
+                        const text = extractText(fetchResult.content);
+                        const content = analyzeContentQuality(text, fetchResult.finalUrl);
+                        results.push({
+                            url: fetchResult.finalUrl,
+                            status: fetchResult.statusCode,
+                            technicalScore: technical.score,
+                            contentScore: content.overallQuality,
+                            title: pageData.title ?? "(no title)",
+                            wordCount: pageData.wordCount,
+                        });
+                    }
+                    catch (err) {
+                        results.push({
+                            url,
+                            status: 0,
+                            technicalScore: 0,
+                            contentScore: 0,
+                            title: "(error)",
+                            wordCount: 0,
+                            error: err instanceof Error ? err.message : String(err),
+                        });
+                    }
+                }
+                const avgTech = Math.round(results.filter((r) => !r.error).reduce((s, r) => s + r.technicalScore, 0) /
+                    Math.max(1, results.filter((r) => !r.error).length));
+                const avgContent = Math.round(results.filter((r) => !r.error).reduce((s, r) => s + r.contentScore, 0) /
+                    Math.max(1, results.filter((r) => !r.error).length));
+                const lines = [
+                    `✓ Batch Audit: ${results.length} pages`,
+                    ``,
+                    `Average Technical Score: ${avgTech}/100`,
+                    `Average Content Score: ${avgContent}/100`,
+                    ``,
+                    `| # | URL | Status | Tech | Content | Title |`,
+                    `|---|-----|--------|------|---------|-------|`,
+                ];
+                results.forEach((r, i) => {
+                    lines.push(`| ${i + 1} | ${truncate(r.url, 60)} | ${r.status || "ERR"} | ${r.technicalScore} | ${r.contentScore} | ${truncate(r.title, 40)} |`);
+                });
+                return textResult(lines.join("\n"), { results, avgTech, avgContent });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    // === seo_competitor_gap ===
+    const gapTool = {
+        name: "seo_competitor_gap",
+        label: "SEO Competitor Gap Analysis",
+        description: "Compare your page against a competitor's page. Analyzes differences in: " +
+            "keyword usage (which keywords do they use that you don't?), content length, " +
+            "readability, heading structure, schema markup, and technical signals. " +
+            "Helps identify content gaps and optimization opportunities.",
+        promptSnippet: "`seo_competitor_gap { yourUrl, competitorUrl }` — compare pages for content/SEO gaps",
+        parameters: {
+            type: "object",
+            properties: {
+                yourUrl: { type: "string", description: "Your page URL." },
+                competitorUrl: { type: "string", description: "Competitor page URL to compare against." },
+            },
+            required: ["yourUrl", "competitorUrl"],
+        },
+        async execute(_toolCallId, params) {
+            const { yourUrl, competitorUrl } = params;
+            try {
+                const [yourFetch, compFetch] = await Promise.all([
+                    fetchPage(yourUrl, config),
+                    fetchPage(competitorUrl, config),
+                ]);
+                const yourData = parsePage(yourFetch.content, yourFetch.finalUrl);
+                const compData = parsePage(compFetch.content, compFetch.finalUrl);
+                const yourText = extractText(yourFetch.content);
+                const compText = extractText(compFetch.content);
+                const yourKw = analyzeKeywords(yourText, yourData.url);
+                const compKw = analyzeKeywords(compText, compData.url);
+                const yourReadability = analyzeReadability(yourText, yourData.url);
+                const compReadability = analyzeReadability(compText, compData.url);
+                // Find keywords competitor uses that you don't
+                const yourKeywordSet = new Set(yourKw.keywords.map((k) => k.keyword));
+                const compKeywordSet = new Set(compKw.keywords.map((k) => k.keyword));
+                const competitorOnlyKeywords = compKw.keywords
+                    .filter((k) => !yourKeywordSet.has(k.keyword))
+                    .slice(0, 10);
+                const sharedKeywords = compKw.keywords
+                    .filter((k) => yourKeywordSet.has(k.keyword))
+                    .slice(0, 10);
+                const yourSchemaTypes = new Set(yourData.schemaBlocks.map((s) => s.type));
+                const compSchemaTypes = new Set(compData.schemaBlocks.map((s) => s.type));
+                const compOnlySchemas = [...compSchemaTypes].filter((t) => !yourSchemaTypes.has(t));
+                const lines = [
+                    `✓ Competitor Gap Analysis`,
+                    ``,
+                    `Your page:       ${yourData.url}`,
+                    `Competitor:      ${compData.url}`,
+                    ``,
+                    `## Content Comparison`,
+                    ``,
+                    `| Metric | Yours | Competitor |`,
+                    `|--------|-------|------------|`,
+                    `| Word count | ${yourData.wordCount} | ${compData.wordCount} |`,
+                    `| Headings | H1:${yourData.h1Count} H2:${yourData.h2Count} H3:${yourData.h3Count} | H1:${compData.h1Count} H2:${compData.h2Count} H3:${compData.h3Count} |`,
+                    `| Internal links | ${yourData.internalLinkCount} | ${compData.internalLinkCount} |`,
+                    `| Images | ${yourData.images.length} | ${compData.images.length} |`,
+                    `| Schema types | ${yourData.schemaBlocks.length} | ${compData.schemaBlocks.length} |`,
+                    `| Readability (grade) | ${yourReadability.gradeAverage} | ${compReadability.gradeAverage} |`,
+                    `| Readability (ease) | ${yourReadability.fleschReadingEase} | ${compReadability.fleschReadingEase} |`,
+                    ``,
+                ];
+                if (competitorOnlyKeywords.length > 0) {
+                    lines.push(`## Keywords Competitor Uses That You Don't`, ``, ...competitorOnlyKeywords.map((k) => `  • "${k.keyword}" — ${k.count}x, density ${k.density}%, TF-IDF ${k.tfidf}`), ``);
+                }
+                if (sharedKeywords.length > 0) {
+                    lines.push(`## Shared Keywords`, ``, ...sharedKeywords.map((k) => `  • "${k.keyword}" — you: ${yourKw.keywords.find((yk) => yk.keyword === k.keyword)?.count ?? 0}x, competitor: ${k.count}x`), ``);
+                }
+                if (compOnlySchemas.length > 0) {
+                    lines.push(`## Schema Types Competitor Has That You Don't`, ``, ...compOnlySchemas.map((t) => `  • ${t}`), ``);
+                }
+                // Content gap recommendations
+                lines.push(`## Recommendations`);
+                if (compData.wordCount > yourData.wordCount * 1.5) {
+                    lines.push(`  • Content gap: Competitor has ${compData.wordCount - yourData.wordCount} more words. Consider expanding your content.`);
+                }
+                if (compData.h2Count > yourData.h2Count) {
+                    lines.push(`  • Structure gap: Competitor uses more H2 subheadings (${compData.h2Count} vs ${yourData.h2Count}). Break your content into more sections.`);
+                }
+                if (compData.schemaBlocks.length > yourData.schemaBlocks.length) {
+                    lines.push(`  • Schema gap: Competitor has ${compData.schemaBlocks.length - yourData.schemaBlocks.length} more schema types. Consider adding: ${compOnlySchemas.join(", ")}`);
+                }
+                if (competitorOnlyKeywords.length > 0) {
+                    lines.push(`  • Keyword gap: Competitor ranks for ${competitorOnlyKeywords.length} keywords you don't cover. Consider addressing: ${competitorOnlyKeywords.map((k) => `"${k.keyword}"`).join(", ")}`);
+                }
+                if (lines[lines.length - 1] === `## Recommendations`) {
+                    lines.push(`  • No significant gaps detected. Your content appears competitive.`);
+                }
+                return textResult(lines.join("\n"), {
+                    yourUrl: yourData.url,
+                    competitorUrl: compData.url,
+                    competitorOnlyKeywords,
+                    sharedKeywords,
+                    compOnlySchemas,
+                });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    ext.registerTool(batchTool);
+    ext.registerTool(gapTool);
+}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"crawl.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/tools/crawl.ts"],"names":[],"mappings":"AAAA,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,CA4F7E"}

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

@@ -0,0 +1,166 @@
+import { crawlSite } from "../analyzers/crawler.js";
+import { errorResult, textResult, truncate } from "./helpers.js";
+export function registerCrawlTools(ext, config) {
+    const crawlTool = {
+        name: "seo_crawl",
+        label: "SEO Site Crawler",
+        description: "Crawl an entire website starting from a URL, following internal links up to a configurable depth and page limit. " +
+            "Discovers all subpages, builds an internal link graph, detects broken links (4xx/5xx), " +
+            "finds duplicate content (same title/description/H1 across pages), and identifies orphan pages. " +
+            "Respects robots.txt and rate-limits requests. Returns per-page details and a site-wide summary. " +
+            "Use this before seo_audit to discover all pages, then run seo_audit on key subpages.",
+        promptSnippet: "`seo_crawl { url, maxPages?, maxDepth?, concurrency? }` — crawl a site and discover all subpages, broken links, and duplicate content",
+        promptGuidelines: [
+            "Use seo_crawl to discover all pages on a site before running targeted audits on key subpages.",
+            "The crawler respects robots.txt and rate-limits requests automatically.",
+            "Start with maxPages=50 for a quick scan, increase to 200-500 for a full site audit.",
+        ],
+        parameters: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "The starting URL to crawl." },
+                maxPages: { type: "number", description: "Maximum pages to crawl. Default: 200." },
+                maxDepth: { type: "number", description: "Maximum crawl depth from start URL. Default: 5." },
+                concurrency: { type: "number", description: "Concurrent fetches. Default: 3." },
+            },
+            required: ["url"],
+        },
+        async execute(_toolCallId, params) {
+            const { url, maxPages, maxDepth, concurrency } = params;
+            try {
+                const crawlConfig = {};
+                if (maxPages !== undefined)
+                    crawlConfig.maxPages = maxPages;
+                if (maxDepth !== undefined)
+                    crawlConfig.maxDepth = maxDepth;
+                if (concurrency !== undefined)
+                    crawlConfig.concurrency = concurrency;
+                const result = await crawlSite(url, config, crawlConfig);
+                const summary = formatCrawlSummary(result);
+                return textResult(summary, {
+                    pagesCrawled: result.pagesCrawled,
+                    brokenLinks: result.brokenLinks.length,
+                    duplicateGroups: result.duplicateGroups.length,
+                    orphanPages: result.orphanPages.length,
+                    urls: result.pages.map((p) => p.url),
+                });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    const crawlReportTool = {
+        name: "seo_crawl_report",
+        label: "SEO Crawl Report",
+        description: "Generate a detailed report from a crawl result. " +
+            "Shows broken links with source pages, duplicate content groups (title/description/H1), " +
+            "orphan pages, link graph statistics, and per-page status codes. " +
+            "Use this after seo_crawl to get actionable insights about site structure problems.",
+        promptSnippet: "`seo_crawl_report { crawlResult }` — generate detailed crawl analysis report",
+        parameters: {
+            type: "object",
+            properties: {
+                crawlResult: {
+                    type: "object",
+                    description: "The CrawlResult object from seo_crawl.",
+                },
+            },
+            required: ["crawlResult"],
+        },
+        async execute(_toolCallId, params) {
+            const { crawlResult } = params;
+            try {
+                const report = generateCrawlReport(crawlResult);
+                return textResult(report, {
+                    pagesCrawled: crawlResult.pagesCrawled,
+                    brokenLinks: crawlResult.brokenLinks.length,
+                    duplicateGroups: crawlResult.duplicateGroups.length,
+                });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    ext.registerTool(crawlTool);
+    ext.registerTool(crawlReportTool);
+}
+function formatCrawlSummary(result) {
+    const lines = [
+        `✓ Crawl Complete: ${result.baseUrl}`,
+        ``,
+        `Pages crawled: ${result.pagesCrawled}`,
+        `Total pages discovered: ${result.totalPagesFound}`,
+        `Max depth reached: ${result.maxDepthReached}`,
+        `Broken links: ${result.brokenLinks.length}`,
+        `Duplicate content groups: ${result.duplicateGroups.length}`,
+        `Orphan pages: ${result.orphanPages.length}`,
+        `Errors: ${result.errors.length}`,
+        ``,
+        `Crawled URLs (${result.pages.length}):`,
+    ];
+    for (const page of result.pages) {
+        const statusIcon = page.statusCode >= 400 ? "❌" : page.statusCode >= 300 ? "↪" : "✓";
+        const title = page.pageData?.title ?? "(no title)";
+        lines.push(`  ${statusIcon} [${page.statusCode}] depth=${page.depth} ${truncate(page.url, 100)} — ${truncate(title, 60)}`);
+    }
+    if (result.brokenLinks.length > 0) {
+        lines.push(``, `Broken Links (${result.brokenLinks.length}):`);
+        for (const bl of result.brokenLinks) {
+            lines.push(`  ❌ ${bl.targetUrl} → ${bl.statusCode} (from ${bl.sourcePage})`);
+        }
+    }
+    if (result.duplicateGroups.length > 0) {
+        lines.push(``, `Duplicate Content (${result.duplicateGroups.length} groups):`);
+        for (const dg of result.duplicateGroups) {
+            lines.push(`  [${dg.type}] "${truncate(dg.value, 80)}" — ${dg.pageUrls.length} pages`);
+            for (const url of dg.pageUrls.slice(0, 5)) {
+                lines.push(`    • ${url}`);
+            }
+            if (dg.pageUrls.length > 5)
+                lines.push(`    ... and ${dg.pageUrls.length - 5} more`);
+        }
+    }
+    if (result.errors.length > 0) {
+        lines.push(``, `Errors (${result.errors.length}):`);
+        for (const err of result.errors.slice(0, 10)) {
+            lines.push(`  ⚠ ${err}`);
+        }
+    }
+    return lines.join("\n");
+}
+function generateCrawlReport(result) {
+    const lines = [
+        `# SEO Crawl Report`,
+        ``,
+        `**Base URL:** ${result.baseUrl}`,
+        `**Pages crawled:** ${result.pagesCrawled}`,
+        `**Max depth:** ${result.maxDepthReached}`,
+        `**Errors:** ${result.errors.length}`,
+        ``,
+        `## Page Status Summary`,
+        ``,
+        `| URL | Status | Depth | Title |`,
+        `|-----|--------|-------|-------|`,
+        ...result.pages.map((p) => `| ${p.url} | ${p.statusCode} | ${p.depth} | ${truncate(p.pageData?.title ?? "", 50)} |`),
+        ``,
+    ];
+    if (result.brokenLinks.length > 0) {
+        lines.push(`## Broken Links (${result.brokenLinks.length})`, ``, `| Source | Target | Status |`, `|--------|--------|--------|`, ...result.brokenLinks.map((bl) => `| ${bl.sourcePage} | ${bl.targetUrl} | ${bl.statusCode} |`), ``);
+    }
+    if (result.duplicateGroups.length > 0) {
+        lines.push(`## Duplicate Content (${result.duplicateGroups.length} groups)`, ``);
+        for (const dg of result.duplicateGroups) {
+            lines.push(`### ${dg.type.toUpperCase()}: "${truncate(dg.value, 100)}"`, ``, `**${dg.pageUrls.length} pages** share this ${dg.type}:`, ...dg.pageUrls.map((u) => `- ${u}`), ``);
+        }
+    }
+    if (result.linkGraph.length > 0) {
+        const avgInlinks = result.linkGraph.reduce((s, n) => s + n.internalInlinks, 0) / result.linkGraph.length;
+        lines.push(`## Link Graph`, ``, `**Average internal inlinks per page:** ${avgInlinks.toFixed(1)}`, ``, `### Top Pages by Internal Inlinks`, ``, `| URL | Inlinks | Outlinks | Depth |`, `|-----|---------|----------|-------|`, ...result.linkGraph
+            .sort((a, b) => b.internalInlinks - a.internalInlinks)
+            .slice(0, 20)
+            .map((n) => `| ${n.url} | ${n.internalInlinks} | ${n.internalOutlinks} | ${n.depth} |`), ``);
+    }
+    return lines.join("\n");
+}

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

@@ -6,5 +6,6 @@
  */
 import type { ExtensionAPI } from "../../../sdk/coding-agent/index.js";
 import type { SeoConfig } from "../config.js";
+export type AuditCategory = "technical" | "content" | "schema" | "images" | "preload" | "agentUx";
 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

@@ -1 +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"}
+{"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;AAa9C,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAIlG,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CA+DjF"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"keywords.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/tools/keywords.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAQ9C,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAqP/E"}

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

@@ -0,0 +1,234 @@
+import { fetchPage } from "../utils/fetcher.js";
+import { parsePage, extractText } from "../utils/parser.js";
+import { analyzeKeywords, analyzeKeywordDensity } from "../analyzers/keywords.js";
+import { analyzeReadability, interpretReadability } from "../analyzers/readability.js";
+import { optimizeContent } from "../analyzers/content-optimize.js";
+import { errorResult, textResult } from "./helpers.js";
+export function registerKeywordTools(ext, config) {
+    // === seo_keywords ===
+    const keywordsTool = {
+        name: "seo_keywords",
+        label: "SEO Keyword Analysis",
+        description: "Extract keywords from page content using TF-IDF analysis. " +
+            "Returns top keywords with density scores, n-gram phrases (bigrams and trigrams), " +
+            "and search intent classification (informational, commercial, transactional). " +
+            "Detects keyword stuffing when keyword density exceeds 3%. " +
+            "All analysis is offline — no external API keys required.",
+        promptSnippet: "`seo_keywords { url? | text? }` — extract keywords, n-grams, and search intent from content",
+        parameters: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "URL to fetch and analyze. If provided, text is extracted from the page." },
+                text: { type: "string", description: "Raw text to analyze. Used if 'url' is not provided." },
+            },
+        },
+        async execute(_toolCallId, params) {
+            const { url, text } = params;
+            try {
+                let content = text;
+                let resolvedUrl = url ?? "";
+                if (url) {
+                    const result = await fetchPage(url, config);
+                    content = extractText(result.content);
+                    resolvedUrl = result.finalUrl;
+                }
+                if (!content) {
+                    return errorResult("Either 'url' or 'text' must be provided.");
+                }
+                const analysis = analyzeKeywords(content, resolvedUrl);
+                const lines = [
+                    `✓ Keyword Analysis: ${resolvedUrl || "(text)"}`,
+                    ``,
+                    `Total words: ${analysis.totalWords}`,
+                    `Search intent: ${analysis.searchIntent} (confidence: ${(analysis.intentConfidence * 100).toFixed(0)}%)`,
+                    ``,
+                    `Top Keywords (by TF-IDF):`,
+                ];
+                for (const kw of analysis.keywords.slice(0, 15)) {
+                    lines.push(`  "${kw.keyword}" — ${kw.count}x, density ${kw.density}%, TF-IDF ${kw.tfidf}` +
+                        (kw.variants.length > 0 ? `, variants: ${kw.variants.join(", ")}` : ""));
+                }
+                if (analysis.topNgrams.length > 0) {
+                    lines.push(``, `Top Phrases (n-grams):`);
+                    for (const ng of analysis.topNgrams.slice(0, 10)) {
+                        lines.push(`  "${ng.ngram}" — ${ng.count}x`);
+                    }
+                }
+                if (analysis.keywordStuffingFlags.length > 0) {
+                    lines.push(``, `⚠ Keyword Stuffing Warnings:`);
+                    for (const flag of analysis.keywordStuffingFlags) {
+                        lines.push(`  ${flag}`);
+                    }
+                }
+                return textResult(lines.join("\n"), { analysis });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    // === seo_keyword_density ===
+    const densityTool = {
+        name: "seo_keyword_density",
+        label: "SEO Keyword Density Check",
+        description: "Check the density of specific target keywords on a page. " +
+            "Provides count, density percentage, and a verdict for each keyword " +
+            "(too low, optimal, acceptable, or too high/possible stuffing). " +
+            "Use this to verify your target keywords are present at appropriate levels.",
+        promptSnippet: "`seo_keyword_density { url? | text?, keywords[] }` — check density of target keywords",
+        parameters: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "URL to fetch and analyze." },
+                text: { type: "string", description: "Raw text to analyze. Used if 'url' is not provided." },
+                keywords: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Target keywords to check density for.",
+                },
+            },
+            required: ["keywords"],
+        },
+        async execute(_toolCallId, params) {
+            const { url, text, keywords } = params;
+            try {
+                let content = text;
+                let resolvedUrl = url ?? "";
+                if (url) {
+                    const result = await fetchPage(url, config);
+                    content = extractText(result.content);
+                    resolvedUrl = result.finalUrl;
+                }
+                if (!content)
+                    return errorResult("Either 'url' or 'text' must be provided.");
+                if (!keywords || keywords.length === 0)
+                    return errorResult("At least one keyword is required.");
+                const results = analyzeKeywordDensity(content, keywords);
+                const lines = [
+                    `✓ Keyword Density: ${resolvedUrl || "(text)"}`,
+                    ``,
+                ];
+                for (const r of results) {
+                    lines.push(`  "${r.keyword}": ${r.count}x, ${r.density}% — ${r.verdict}`);
+                }
+                return textResult(lines.join("\n"), { results });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    // === seo_readability ===
+    const readabilityTool = {
+        name: "seo_readability",
+        label: "SEO Readability Analysis",
+        description: "Analyze text readability using multiple formulas: Flesch-Kincaid Grade Level, " +
+            "Flesch Reading Ease, SMOG Index, Automated Readability Index (ARI), and Coleman-Liau Index. " +
+            "Returns grade-level averages and SEO-specific readability advice. " +
+            "Helps ensure content targets the right audience level.",
+        promptSnippet: "`seo_readability { url? | text? }` — analyze content readability",
+        parameters: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "URL to fetch and analyze." },
+                text: { type: "string", description: "Raw text to analyze. Used if 'url' is not provided." },
+            },
+        },
+        async execute(_toolCallId, params) {
+            const { url, text } = params;
+            try {
+                let content = text;
+                let resolvedUrl = url ?? "";
+                if (url) {
+                    const result = await fetchPage(url, config);
+                    content = extractText(result.content);
+                    resolvedUrl = result.finalUrl;
+                }
+                if (!content)
+                    return errorResult("Either 'url' or 'text' must be provided.");
+                const result = analyzeReadability(content, resolvedUrl);
+                const interpretation = interpretReadability(result);
+                const lines = [
+                    `✓ Readability Analysis: ${resolvedUrl || "(text)"}`,
+                    ``,
+                    `Words: ${content.split(/\s+/).filter(Boolean).length}`,
+                    `Sentences: ${result.sentenceCount}`,
+                    `Syllables: ${result.syllableCount}`,
+                    `Complex words (3+ syllables): ${result.complexWordCount}`,
+                    ``,
+                    `Readability Scores:`,
+                    `  Flesch Reading Ease: ${result.fleschReadingEase}`,
+                    `  Flesch-Kincaid Grade: ${result.fleschKincaid}`,
+                    `  SMOG Index: ${result.smog}`,
+                    `  ARI (Automated Readability): ${result.ari}`,
+                    `  Coleman-Liau: ${result.colemanLiau}`,
+                    `  Average Grade Level: ${result.gradeAverage}`,
+                    ``,
+                    `Interpretation: ${interpretation}`,
+                ];
+                return textResult(lines.join("\n"), { result });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    // === seo_content_optimize ===
+    const optimizeTool = {
+        name: "seo_content_optimize",
+        label: "SEO Content Optimization",
+        description: "Analyze on-page content optimization opportunities. Checks title length (ideal 50-60 chars), " +
+            "meta description length (ideal 150-160 chars), heading hierarchy (H1→H2→H3 structure), " +
+            "content length (minimum 300 words), duplicate title/description, and suspicious headings. " +
+            "Returns a score for each category with specific, actionable recommendations.",
+        promptSnippet: "`seo_content_optimize { url }` — content optimization audit with actionable fixes",
+        parameters: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "The URL to analyze." },
+            },
+            required: ["url"],
+        },
+        async execute(_toolCallId, params) {
+            const { url } = params;
+            try {
+                const fetchResult = await fetchPage(url, config);
+                const pageData = parsePage(fetchResult.content, fetchResult.finalUrl);
+                const result = optimizeContent(pageData);
+                const lines = [
+                    `✓ Content Optimization: ${result.url}`,
+                    ``,
+                    `Overall Score: ${result.overallScore}/100`,
+                    ``,
+                    `Category Scores:`,
+                    `  Title: ${result.titleScore}/100`,
+                    `  Meta Description: ${result.descriptionScore}/100`,
+                    `  Heading Structure: ${result.headingStructureScore}/100`,
+                    `  Content Length: ${result.contentLengthScore}/100`,
+                    ``,
+                ];
+                if (result.issues.length > 0) {
+                    const sorted = result.issues.sort((a, b) => {
+                        const rank = { critical: 0, high: 1, medium: 2, low: 3 };
+                        return (rank[a.severity] ?? 4) - (rank[b.severity] ?? 4);
+                    });
+                    lines.push(`Issues (${result.issues.length}):`);
+                    for (const issue of sorted) {
+                        lines.push(`  [${issue.severity.toUpperCase()}] ${issue.category}: ${issue.issue}`, `    → ${issue.recommendation}`);
+                    }
+                }
+                else {
+                    lines.push(`No issues found — content is well-optimized!`);
+                }
+                return textResult(lines.join("\n"), { result });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    ext.registerTool(keywordsTool);
+    ext.registerTool(densityTool);
+    ext.registerTool(readabilityTool);
+    ext.registerTool(optimizeTool);
+}

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

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

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

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