geo-ai-search-optimization 2.0.0 → 2.2.0

package/src/cli-site-ops-commands.js

@@ -31,6 +31,29 @@ import { createRewritePack, renderRewritePackMarkdown, writeRewritePackOutput }
 import { renderScanMarkdown, scanProject, writeScanOutput } from "./scan.js";
 import { createSchemaTemplate } from "./schema.js";
 import { analyzeWebsiteUrl, renderWebsiteOnboardingMarkdown, writeWebsiteOnboardingOutput } from "./url-onboarding.js";
+import { analyzeCrawlers, renderCrawlersMarkdown, writeCrawlersOutput } from "./crawlers.js";
+import { analyzeCitability, renderCitabilityMarkdown, writeCitabilityOutput } from "./citability.js";
+import { validateLlmsTxt, renderValidateLlmsMarkdown, writeValidateLlmsOutput } from "./validate-llms.js";
+import { validateSchema, renderValidateSchemaMarkdown, writeValidateSchemaOutput } from "./validate-schema.js";
+import { analyzeEeat, renderEeatMarkdown, writeEeatOutput } from "./eeat.js";
+import { analyzePlatformReadiness, renderPlatformReadyMarkdown, writePlatformReadyOutput } from "./platform-ready.js";
+import { analyzeReadability, renderReadabilityMarkdown, writeReadabilityOutput } from "./readability.js";
+import { analyzeHeadingStructure, renderHeadingStructureMarkdown, writeHeadingStructureOutput } from "./heading-structure.js";
+import { analyzeInternalLinks, renderInternalLinksMarkdown, writeInternalLinksOutput } from "./internal-links.js";
+import { analyzeSocialMeta, renderSocialMetaMarkdown, writeSocialMetaOutput } from "./social-meta.js";
+import { initConfig } from "./config.js";
+import { writePdfReport } from "./pdf-report.js";
+import { fullPageAudit, renderFullPageAuditMarkdown, writeFullPageAuditOutput } from "./full-page-audit.js";
+import { fullAudit, renderFullAuditMarkdown, writeFullAuditOutput } from "./full-audit.js";
+import { analyzeSitemap, renderSitemapMarkdown, writeSitemapOutput } from "./sitemap.js";
+import { analyzeSecurity, renderSecurityMarkdown, writeSecurityOutput } from "./security.js";
+import { analyzeFreshness, renderFreshnessMarkdown, writeFreshnessOutput } from "./freshness.js";
+import { analyzeTopics, renderTopicsMarkdown, writeTopicsOutput } from "./topics.js";
+import { batchFullPageAudit, renderBatchFullPageAuditMarkdown, writeBatchFullPageAuditOutput } from "./batch-full-page-audit.js";
+import { generateAutoFix, renderAutoFixMarkdown, writeAutoFixOutput } from "./auto-fix.js";
+import { savePageSnapshot, buildPageTrend, renderPageTrendMarkdown, writePageTrendOutput } from "./page-snapshot.js";
+import { diagnose, renderDiagnoseMarkdown, writeDiagnoseOutput } from "./diagnose.js";
+import { comparePages, renderCompareMarkdown, writeCompareOutput } from "./compare.js";
 
 export const SITE_OPS_HELP_LINES = [
   "  geo-ai-search-optimization doctor [--json]",
@@ -53,7 +76,30 @@ export const SITE_OPS_HELP_LINES = [
   "  geo-ai-search-optimization watch <project-path> [--debounce <ms>]",
   "  geo-ai-search-optimization init-hook [--min-score <n>] [target-dir]",
   "  geo-ai-search-optimization citation-check <site-url> --queries <q1,q2,...> [--queries-file <file>] [--engine <perplexity|google|all>] [--json] [--out <file>]",
-  "  geo-ai-search-optimization citation-monitor <site-url> --queries-file <file> [--save] [--json] [--out <file>]"
+  "  geo-ai-search-optimization citation-monitor <site-url> --queries-file <file> [--save] [--json] [--out <file>]",
+  "  geo-ai-search-optimization crawlers <url-or-file> [--strategy <open|selective|block-all>] [--json] [--out <file>]",
+  "  geo-ai-search-optimization citability <url-or-file> [--json] [--out <file>]",
+  "  geo-ai-search-optimization validate-llms <url-or-file> [--json] [--out <file>]",
+  "  geo-ai-search-optimization validate-schema <url-or-file> [--json] [--out <file>]",
+  "  geo-ai-search-optimization eeat <url-or-file> [--json] [--out <file>]",
+  "  geo-ai-search-optimization platform-ready <url-or-file> [--json] [--out <file>]",
+  "  geo-ai-search-optimization readability <url-or-file> [--json] [--out <file>]",
+  "  geo-ai-search-optimization heading-structure <url-or-file> [--json] [--out <file>]",
+  "  geo-ai-search-optimization internal-links <url-or-file> [--base-url <url>] [--json] [--out <file>]",
+  "  geo-ai-search-optimization social-meta <url-or-file> [--json] [--out <file>]",
+  "  geo-ai-search-optimization init-config [target-dir] [--site-name <name>] [--site-url <url>] [--overwrite] [--json]",
+  "  geo-ai-search-optimization pdf-report <audit.json> [--out <file>] [--title <title>]",
+  "  geo-ai-search-optimization full-page-audit <url-or-file> [--base-url <url>] [--save] [--data-dir <dir>] [--json] [--out <file>]",
+  "  geo-ai-search-optimization full-audit <project-path> [--sample-urls <url1,url2,...>] [--max-file-size <bytes>] [--save] [--data-dir <dir>] [--json] [--out <file>]",
+  "  geo-ai-search-optimization sitemap <url-or-file> [--json] [--out <file>]",
+  "  geo-ai-search-optimization security <url-or-file> [--json] [--out <file>]",
+  "  geo-ai-search-optimization freshness <url-or-file> [--json] [--out <file>]",
+  "  geo-ai-search-optimization topics <url-or-file> [--json] [--out <file>]",
+  "  geo-ai-search-optimization batch-full-page-audit <url1> [url2...] [--urls-file <file>] [--concurrency <n>] [--json] [--out <file>]",
+  "  geo-ai-search-optimization auto-fix <url-or-file> [--json] [--out <file>]",
+  "  geo-ai-search-optimization page-trend <url-or-file> [--data-dir <dir>] [--last <n>] [--json] [--out <file>]",
+  "  geo-ai-search-optimization diagnose <url-or-dir-or-file> [--json] [--out <file>]",
+  "  geo-ai-search-optimization compare <url-or-file-A> <url-or-file-B> [--json] [--out <file>]"
 ];
 
 const passthroughWriteOutput = async (outputPath) => outputPath;
@@ -441,6 +487,326 @@ const handleInitHook = createStructuredOutputCommandHandler({
   getOutputJson: (args) => hasFlag(args, "--json")
 });
 
+const handleCrawlers = createStructuredOutputCommandHandler({
+  commandLabel: "AI crawler analysis",
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) throw new Error("crawlers requires a URL or robots.txt file path");
+    return analyzeCrawlers(input, { strategy: getFlagValue(args, "--strategy") || "open" });
+  },
+  renderMarkdown: renderCrawlersMarkdown,
+  writeOutput: writeCrawlersOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleCitability = createStructuredOutputCommandHandler({
+  commandLabel: "citability analysis",
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) throw new Error("citability requires a URL or file path");
+    return analyzeCitability(input);
+  },
+  renderMarkdown: renderCitabilityMarkdown,
+  writeOutput: writeCitabilityOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleValidateLlms = createStructuredOutputCommandHandler({
+  commandLabel: "llms.txt validation",
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) throw new Error("validate-llms requires a URL or llms.txt file path");
+    return validateLlmsTxt(input);
+  },
+  renderMarkdown: renderValidateLlmsMarkdown,
+  writeOutput: writeValidateLlmsOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleValidateSchema = createStructuredOutputCommandHandler({
+  commandLabel: "schema validation",
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) throw new Error("validate-schema requires a URL or file path");
+    return validateSchema(input);
+  },
+  renderMarkdown: renderValidateSchemaMarkdown,
+  writeOutput: writeValidateSchemaOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleEeat = createStructuredOutputCommandHandler({
+  commandLabel: "E-E-A-T analysis",
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) throw new Error("eeat requires a URL or file path");
+    return analyzeEeat(input);
+  },
+  renderMarkdown: renderEeatMarkdown,
+  writeOutput: writeEeatOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handlePlatformReady = createStructuredOutputCommandHandler({
+  commandLabel: "platform readiness",
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) throw new Error("platform-ready requires a URL or file path");
+    return analyzePlatformReadiness(input);
+  },
+  renderMarkdown: renderPlatformReadyMarkdown,
+  writeOutput: writePlatformReadyOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleReadability = createStructuredOutputCommandHandler({
+  commandLabel: "readability analysis",
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) throw new Error("readability requires a URL or file path");
+    return analyzeReadability(input);
+  },
+  renderMarkdown: renderReadabilityMarkdown,
+  writeOutput: writeReadabilityOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleHeadingStructure = createStructuredOutputCommandHandler({
+  commandLabel: "heading structure",
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) throw new Error("heading-structure requires a URL or file path");
+    return analyzeHeadingStructure(input);
+  },
+  renderMarkdown: renderHeadingStructureMarkdown,
+  writeOutput: writeHeadingStructureOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleInternalLinks = createStructuredOutputCommandHandler({
+  commandLabel: "internal links",
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) throw new Error("internal-links requires a URL or file path");
+    return analyzeInternalLinks(input, { baseUrl: getFlagValue(args, "--base-url") });
+  },
+  renderMarkdown: renderInternalLinksMarkdown,
+  writeOutput: writeInternalLinksOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleSocialMeta = createStructuredOutputCommandHandler({
+  commandLabel: "social meta",
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) throw new Error("social-meta requires a URL or file path");
+    return analyzeSocialMeta(input);
+  },
+  renderMarkdown: renderSocialMetaMarkdown,
+  writeOutput: writeSocialMetaOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleInitConfig = createActionCommandHandler({
+  execute: async (args) =>
+    initConfig({
+      targetDir: args.find((value) => !value.startsWith("-")) || ".",
+      siteName: getFlagValue(args, "--site-name"),
+      siteUrl: getFlagValue(args, "--site-url"),
+      overwrite: hasFlag(args, "--overwrite")
+    }),
+  getOutputJson: (args) => hasFlag(args, "--json"),
+  renderText: (result) => `Created config at ${result.outputPath}\n`
+});
+
+const handlePdfReport = createActionCommandHandler({
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) throw new Error("pdf-report requires an audit JSON file path");
+    return writePdfReport(input, getFlagValue(args, "--out"), {
+      title: getFlagValue(args, "--title")
+    });
+  },
+  getOutputJson: (args) => hasFlag(args, "--json"),
+  renderText: (result) => `Generated PDF-ready HTML report at ${result.outputPath}\n`
+});
+
+const handleSitemap = createStructuredOutputCommandHandler({
+  commandLabel: "sitemap analysis",
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) throw new Error("sitemap requires a URL or sitemap file path");
+    return analyzeSitemap(input);
+  },
+  renderMarkdown: renderSitemapMarkdown,
+  writeOutput: writeSitemapOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleSecurity = createStructuredOutputCommandHandler({
+  commandLabel: "security analysis",
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) throw new Error("security requires a URL or file path");
+    return analyzeSecurity(input);
+  },
+  renderMarkdown: renderSecurityMarkdown,
+  writeOutput: writeSecurityOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleFreshness = createStructuredOutputCommandHandler({
+  commandLabel: "freshness analysis",
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) throw new Error("freshness requires a URL or file path");
+    return analyzeFreshness(input);
+  },
+  renderMarkdown: renderFreshnessMarkdown,
+  writeOutput: writeFreshnessOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleTopics = createStructuredOutputCommandHandler({
+  commandLabel: "topic analysis",
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) throw new Error("topics requires a URL or file path");
+    return analyzeTopics(input);
+  },
+  renderMarkdown: renderTopicsMarkdown,
+  writeOutput: writeTopicsOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleBatchFullPageAudit = createStructuredOutputCommandHandler({
+  commandLabel: "batch full page audit",
+  execute: async (args) => {
+    const nonFlags = args.filter((value) => !value.startsWith("-"));
+    const urlsFile = getFlagValue(args, "--urls-file");
+    let urls = [...nonFlags];
+
+    if (urlsFile) {
+      const { readFile } = await import("node:fs/promises");
+      const fileContent = await readFile(urlsFile, "utf8");
+      const fileUrls = fileContent.split("\n").map((line) => line.trim()).filter(Boolean);
+      urls = [...urls, ...fileUrls];
+    }
+
+    if (urls.length === 0) throw new Error("batch-full-page-audit requires at least one URL");
+
+    const concurrencyValue = getFlagValue(args, "--concurrency");
+    return batchFullPageAudit(urls, {
+      concurrency: concurrencyValue ? parsePositiveInteger(concurrencyValue, "--concurrency") : 2
+    });
+  },
+  renderMarkdown: renderBatchFullPageAuditMarkdown,
+  writeOutput: writeBatchFullPageAuditOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleDiagnose = createStructuredOutputCommandHandler({
+  commandLabel: "diagnose",
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) throw new Error("diagnose requires a URL, file path, or directory");
+    return diagnose(input);
+  },
+  renderMarkdown: renderDiagnoseMarkdown,
+  writeOutput: writeDiagnoseOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleCompare = createStructuredOutputCommandHandler({
+  commandLabel: "compare",
+  execute: async (args) => {
+    const nonFlags = args.filter((value) => !value.startsWith("-"));
+    if (nonFlags.length < 2) throw new Error("compare requires two URLs or file paths: <A> <B>");
+    return comparePages(nonFlags[0], nonFlags[1]);
+  },
+  renderMarkdown: renderCompareMarkdown,
+  writeOutput: writeCompareOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleAutoFix = createStructuredOutputCommandHandler({
+  commandLabel: "auto-fix",
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) throw new Error("auto-fix requires a URL or file path");
+    return generateAutoFix(input);
+  },
+  renderMarkdown: renderAutoFixMarkdown,
+  writeOutput: writeAutoFixOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handlePageTrend = createStructuredOutputCommandHandler({
+  commandLabel: "page trend",
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) throw new Error("page-trend requires a URL or file path (same input used for full-page-audit)");
+    const lastValue = getFlagValue(args, "--last");
+    return buildPageTrend(input, {
+      dataDir: getFlagValue(args, "--data-dir") || undefined,
+      last: lastValue ? parsePositiveInteger(lastValue, "--last") : 0
+    });
+  },
+  renderMarkdown: renderPageTrendMarkdown,
+  writeOutput: writePageTrendOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleFullPageAudit = createStructuredOutputCommandHandler({
+  commandLabel: "full page audit",
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) throw new Error("full-page-audit requires a URL or file path");
+    const result = await fullPageAudit(input, { baseUrl: getFlagValue(args, "--base-url") });
+
+    if (hasFlag(args, "--save")) {
+      const saved = await savePageSnapshot(result, {
+        dataDir: getFlagValue(args, "--data-dir") || undefined
+      });
+      process.stderr.write(`快照已保存：${saved.path}\n`);
+    }
+
+    return result;
+  },
+  renderMarkdown: renderFullPageAuditMarkdown,
+  writeOutput: writeFullPageAuditOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleFullAudit = createStructuredOutputCommandHandler({
+  commandLabel: "full audit",
+  execute: async (args) => {
+    const projectPath = args.find((value) => !value.startsWith("-"));
+    if (!projectPath) throw new Error("full-audit requires a project path");
+
+    const sampleUrlsRaw = getFlagValue(args, "--sample-urls");
+    const sampleUrls = sampleUrlsRaw ? sampleUrlsRaw.split(",").map((u) => u.trim()).filter(Boolean) : [];
+
+    const result = await fullAudit(projectPath, {
+      sampleUrls,
+      maxFileSize: getFlagValue(args, "--max-file-size")
+        ? parsePositiveInteger(getFlagValue(args, "--max-file-size"), "--max-file-size")
+        : undefined
+    });
+
+    if (hasFlag(args, "--save")) {
+      const dataDir = getFlagValue(args, "--data-dir") || undefined;
+      const saved = await saveSnapshot(result, { dataDir });
+      process.stderr.write(`快照已保存：${saved.path}\n`);
+    }
+
+    return result;
+  },
+  renderMarkdown: renderFullAuditMarkdown,
+  writeOutput: writeFullAuditOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
 export const SITE_OPS_COMMAND_HANDLERS = {
   doctor: handleDoctor,
   "quick-start": handleQuickStart,
@@ -462,5 +828,28 @@ export const SITE_OPS_COMMAND_HANDLERS = {
   watch: handleWatch,
   "init-hook": handleInitHook,
   "citation-check": handleCitationCheck,
-  "citation-monitor": handleCitationMonitor
+  "citation-monitor": handleCitationMonitor,
+  crawlers: handleCrawlers,
+  citability: handleCitability,
+  "validate-llms": handleValidateLlms,
+  "validate-schema": handleValidateSchema,
+  eeat: handleEeat,
+  "platform-ready": handlePlatformReady,
+  readability: handleReadability,
+  "heading-structure": handleHeadingStructure,
+  "internal-links": handleInternalLinks,
+  "social-meta": handleSocialMeta,
+  "init-config": handleInitConfig,
+  "pdf-report": handlePdfReport,
+  "full-page-audit": handleFullPageAudit,
+  "full-audit": handleFullAudit,
+  sitemap: handleSitemap,
+  security: handleSecurity,
+  freshness: handleFreshness,
+  topics: handleTopics,
+  "batch-full-page-audit": handleBatchFullPageAudit,
+  "auto-fix": handleAutoFix,
+  "page-trend": handlePageTrend,
+  diagnose: handleDiagnose,
+  compare: handleCompare
 };

package/src/compare.js

@@ -0,0 +1,175 @@
+import { writeScanOutput } from "./scan.js";
+import { fullPageAudit } from "./full-page-audit.js";
+
+/**
+ * Compare two pages across all 12 dimensions.
+ * Produces a side-by-side analysis with delta scoring.
+ */
+
+export async function comparePages(inputA, inputB, options = {}) {
+  const [resultA, resultB] = await Promise.all([
+    fullPageAudit(inputA, options),
+    fullPageAudit(inputB, options)
+  ]);
+
+  const dimensions = {};
+  const allDimKeys = new Set([
+    ...Object.keys(resultA.dimensions),
+    ...Object.keys(resultB.dimensions)
+  ]);
+
+  let aWins = 0;
+  let bWins = 0;
+  let ties = 0;
+
+  for (const key of allDimKeys) {
+    const scoreA = resultA.dimensions[key]?.score ?? 0;
+    const scoreB = resultB.dimensions[key]?.score ?? 0;
+    const delta = scoreA - scoreB;
+    const winner = delta > 0 ? "A" : delta < 0 ? "B" : "tie";
+
+    if (winner === "A") aWins++;
+    else if (winner === "B") bWins++;
+    else ties++;
+
+    dimensions[key] = {
+      scoreA,
+      scoreB,
+      delta,
+      winner,
+      labelA: resultA.dimensions[key]?.label ?? "",
+      labelB: resultB.dimensions[key]?.label ?? ""
+    };
+  }
+
+  const compositeA = resultA.compositeScore;
+  const compositeB = resultB.compositeScore;
+  const compositeDelta = compositeA - compositeB;
+
+  // Identify where each page is stronger
+  const aStrengths = Object.entries(dimensions)
+    .filter(([, d]) => d.delta > 10)
+    .sort((a, b) => b[1].delta - a[1].delta)
+    .map(([key, d]) => ({ dimension: key, delta: d.delta }));
+
+  const bStrengths = Object.entries(dimensions)
+    .filter(([, d]) => d.delta < -10)
+    .sort((a, b) => a[1].delta - b[1].delta)
+    .map(([key, d]) => ({ dimension: key, delta: Math.abs(d.delta) }));
+
+  // Platform comparison
+  const platformComparison = [];
+  if (resultA.platformSummary && resultB.platformSummary) {
+    for (let i = 0; i < resultA.platformSummary.length; i++) {
+      const pA = resultA.platformSummary[i];
+      const pB = resultB.platformSummary[i];
+      if (pA && pB) {
+        platformComparison.push({
+          platform: pA.platform,
+          scoreA: pA.score,
+          scoreB: pB.score,
+          delta: pA.score - pB.score,
+          readinessA: pA.readiness,
+          readinessB: pB.readiness
+        });
+      }
+    }
+  }
+
+  const overallWinner = compositeDelta > 5 ? "A" : compositeDelta < -5 ? "B" : "tie";
+
+  return {
+    kind: "geo-compare",
+    inputA,
+    inputB,
+    compositeA,
+    compositeB,
+    compositeDelta,
+    overallWinner,
+    dimensionWins: { A: aWins, B: bWins, ties },
+    dimensions,
+    aStrengths,
+    bStrengths,
+    platformComparison,
+    summary: overallWinner === "tie"
+      ? `Near parity. A: ${compositeA}/100, B: ${compositeB}/100 (Δ${compositeDelta >= 0 ? "+" : ""}${compositeDelta}).`
+      : `${overallWinner === "A" ? "Page A" : "Page B"} leads. A: ${compositeA}/100, B: ${compositeB}/100 (Δ${compositeDelta >= 0 ? "+" : ""}${compositeDelta}). Dimension wins: A=${aWins}, B=${bWins}, Ties=${ties}.`
+  };
+}
+
+export function renderCompareMarkdown(report) {
+  const lines = [
+    "# GEO Page Comparison",
+    "",
+    `- **Page A**: \`${report.inputA}\``,
+    `- **Page B**: \`${report.inputB}\``,
+    `- Summary: ${report.summary}`,
+    "",
+    "## Composite Scores",
+    "",
+    `| | Page A | Page B | Delta |`,
+    `|--|--------|--------|-------|`,
+    `| **Composite** | **${report.compositeA}** | **${report.compositeB}** | ${report.compositeDelta >= 0 ? "+" : ""}${report.compositeDelta} |`,
+    ""
+  ];
+
+  const dimLabels = {
+    base: "Base", citability: "Citability", eeat: "E-E-A-T", readability: "Readability",
+    headingStructure: "Headings", internalLinks: "Links", socialMeta: "Social",
+    platformReady: "Platforms", schema: "Schema", freshness: "Freshness",
+    security: "Security", topics: "Topics"
+  };
+
+  lines.push(
+    "## Dimension Comparison",
+    "",
+    "| Dimension | Page A | Page B | Δ | Winner |",
+    "|-----------|--------|--------|---|--------|"
+  );
+
+  const sorted = Object.entries(report.dimensions)
+    .sort((a, b) => Math.abs(b[1].delta) - Math.abs(a[1].delta));
+
+  for (const [key, d] of sorted) {
+    const winIcon = d.winner === "A" ? "◀️ A" : d.winner === "B" ? "B ▶️" : "—";
+    lines.push(`| ${dimLabels[key] || key} | ${d.scoreA} | ${d.scoreB} | ${d.delta >= 0 ? "+" : ""}${d.delta} | ${winIcon} |`);
+  }
+  lines.push("");
+
+  if (report.aStrengths.length > 0) {
+    lines.push("## Page A Strengths", "");
+    for (const s of report.aStrengths) {
+      lines.push(`- **${dimLabels[s.dimension] || s.dimension}**: +${s.delta} points ahead`);
+    }
+    lines.push("");
+  }
+
+  if (report.bStrengths.length > 0) {
+    lines.push("## Page B Strengths", "");
+    for (const s of report.bStrengths) {
+      lines.push(`- **${dimLabels[s.dimension] || s.dimension}**: +${s.delta} points ahead`);
+    }
+    lines.push("");
+  }
+
+  if (report.platformComparison.length > 0) {
+    lines.push(
+      "## Platform Readiness Comparison",
+      "",
+      "| Platform | A Score | B Score | Δ | A Status | B Status |",
+      "|----------|---------|---------|---|----------|----------|"
+    );
+    for (const p of report.platformComparison) {
+      lines.push(`| ${p.platform} | ${p.scoreA} | ${p.scoreB} | ${p.delta >= 0 ? "+" : ""}${p.delta} | ${p.readinessA} | ${p.readinessB} |`);
+    }
+    lines.push("");
+  }
+
+  lines.push(`## Verdict`, "", `**Dimension wins**: A=${report.dimensionWins.A}, B=${report.dimensionWins.B}, Ties=${report.dimensionWins.ties}`, "");
+
+  return lines.join("\n");
+}
+
+export async function writeCompareOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}