geo-ai-search-optimization 2.0.0 → 2.2.1

package/action.yml

@@ -0,0 +1,130 @@
+name: "GEO AI Search Optimization"
+description: "Run GEO audit in CI/CD. Check your site's AI search readiness score and fail on regression."
+author: "geo-ai-search-optimization"
+
+inputs:
+  project-path:
+    description: "Path to the project to audit"
+    required: true
+    default: "."
+  min-score:
+    description: "Minimum GEO score to pass (0-100)"
+    required: false
+    default: "40"
+  baseline:
+    description: "Path to baseline audit JSON for regression detection"
+    required: false
+  fail-on-regression:
+    description: "Fail if score drops compared to baseline"
+    required: false
+    default: "false"
+  output-format:
+    description: "Output format: json or markdown"
+    required: false
+    default: "markdown"
+  save-snapshot:
+    description: "Save audit snapshot for trend tracking"
+    required: false
+    default: "false"
+
+outputs:
+  score:
+    description: "GEO audit score (0-100)"
+    value: ${{ steps.audit.outputs.score }}
+  score-label:
+    description: "Human-readable score label"
+    value: ${{ steps.audit.outputs.score-label }}
+  passed:
+    description: "Whether the audit passed (true/false)"
+    value: ${{ steps.audit.outputs.passed }}
+  report-path:
+    description: "Path to the generated report file"
+    value: ${{ steps.audit.outputs.report-path }}
+
+runs:
+  using: "composite"
+  steps:
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: "18"
+
+    - name: Install geo-ai-search-optimization
+      shell: bash
+      run: npm install -g geo-ai-search-optimization
+
+    - name: Run GEO Audit
+      id: audit
+      shell: bash
+      run: |
+        PROJ_PATH="${{ inputs.project-path }}"
+        BASELINE="${{ inputs.baseline }}"
+        MIN_SCORE="${{ inputs.min-score }}"
+
+        ARGS=("$PROJ_PATH" "--json")
+
+        if [ -n "$BASELINE" ]; then
+          ARGS+=("--baseline" "$BASELINE")
+        fi
+
+        if [ "${{ inputs.fail-on-regression }}" = "true" ]; then
+          ARGS+=("--fail-on-regression")
+        fi
+
+        ARGS+=("--min-score" "$MIN_SCORE")
+
+        RESULT=$(geo-ai-search-optimization ci "${ARGS[@]}" 2>geo-audit-stderr.log) || true
+        echo "$RESULT" > geo-audit-result.json
+
+        SCORE=$(echo "$RESULT" | node -e "
+          const data = JSON.parse(require('fs').readFileSync('/dev/stdin', 'utf8'));
+          console.log(data.audit?.score ?? data.score ?? 0);
+        " 2>/dev/null || echo "0")
+
+        LABEL=$(echo "$RESULT" | node -e "
+          const data = JSON.parse(require('fs').readFileSync('/dev/stdin', 'utf8'));
+          console.log(data.audit?.scoreLabel ?? data.scoreLabel ?? 'unknown');
+        " 2>/dev/null || echo "unknown")
+
+        PASSED=$(echo "$RESULT" | node -e "
+          const data = JSON.parse(require('fs').readFileSync('/dev/stdin', 'utf8'));
+          console.log(data.passed ?? (data.exitCode === 0));
+        " 2>/dev/null || echo "false")
+
+        echo "score=$SCORE" >> $GITHUB_OUTPUT
+        echo "score-label=$LABEL" >> $GITHUB_OUTPUT
+        echo "passed=$PASSED" >> $GITHUB_OUTPUT
+        echo "report-path=geo-audit-result.json" >> $GITHUB_OUTPUT
+
+    - name: Save Snapshot
+      if: inputs.save-snapshot == 'true'
+      shell: bash
+      run: |
+        geo-ai-search-optimization audit "${{ inputs.project-path }}" --save --json > /dev/null 2>&1 || true
+
+    - name: Generate Markdown Report
+      if: inputs.output-format == 'markdown'
+      shell: bash
+      run: |
+        geo-ai-search-optimization audit "${{ inputs.project-path }}" --out geo-audit-report.md || true
+
+    - name: Post Summary
+      if: always()
+      shell: bash
+      run: |
+        echo "### GEO Audit Results" >> $GITHUB_STEP_SUMMARY
+        echo "" >> $GITHUB_STEP_SUMMARY
+        echo "- **Score:** ${{ steps.audit.outputs.score }}/100 (${{ steps.audit.outputs.score-label }})" >> $GITHUB_STEP_SUMMARY
+        echo "- **Passed:** ${{ steps.audit.outputs.passed }}" >> $GITHUB_STEP_SUMMARY
+        echo "- **Min Score:** ${{ inputs.min-score }}" >> $GITHUB_STEP_SUMMARY
+
+    - name: Check Result
+      if: steps.audit.outputs.passed == 'false'
+      shell: bash
+      run: |
+        echo "::error::GEO audit failed. Score: ${{ steps.audit.outputs.score }}/100 (minimum: ${{ inputs.min-score }})"
+        exit 1
+
+branding:
+  icon: "search"
+  color: "blue"

package/package.json

@@ -1,19 +1,24 @@
 {
   "name": "geo-ai-search-optimization",
-  "version": "2.0.0",
+  "version": "2.2.1",
   "description": "Install and run a Generative Engine Optimization (GEO)-first, SEO-supported Codex skill for website optimization.",
   "type": "module",
   "bin": {
     "geo-ai-search-optimization": "bin/geo-ai-search-optimization.js"
   },
   "exports": {
-    ".": "./src/index.js"
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
   },
+  "types": "./src/index.d.ts",
   "files": [
     "bin",
     "src",
     "resources",
     "examples",
+    "action.yml",
     "README.md",
     "LICENSE"
   ],
@@ -34,7 +39,14 @@
     "codex-skill",
     "chatgpt",
     "perplexity",
-    "gemini"
+    "gemini",
+    "llms-txt",
+    "schema-validation",
+    "eeat",
+    "citability",
+    "ai-crawler",
+    "aeo",
+    "ai-optimization"
   ],
   "license": "MIT"
 }

package/src/auto-fix.js

@@ -0,0 +1,349 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeScanOutput } from "./scan.js";
+import { auditPage } from "./page-audit.js";
+
+/**
+ * Auto-fix generator: produces ready-to-use code snippets
+ * based on page audit findings.
+ */
+
+function generateMetaTags(metadata, signals) {
+  const tags = [];
+
+  if (!metadata.title) {
+    tags.push({ tag: "title", html: "<title>Your Page Title — Concise, Descriptive</title>", priority: "P0" });
+  }
+
+  if (!metadata.metaDescription) {
+    tags.push({
+      tag: "meta-description",
+      html: '<meta name="description" content="A clear, 150-160 character description of what this page covers and who it helps.">',
+      priority: "P0"
+    });
+  }
+
+  if (!metadata.canonical) {
+    tags.push({
+      tag: "canonical",
+      html: '<link rel="canonical" href="https://yoursite.com/this-page">',
+      priority: "P0"
+    });
+  }
+
+  // Viewport
+  tags.push({
+    tag: "viewport",
+    html: '<meta name="viewport" content="width=device-width, initial-scale=1">',
+    priority: "P1",
+    condition: "Add if missing"
+  });
+
+  // Charset
+  tags.push({
+    tag: "charset",
+    html: '<meta charset="UTF-8">',
+    priority: "P2",
+    condition: "Add if missing"
+  });
+
+  return tags;
+}
+
+function generateOgTags(metadata) {
+  const title = metadata.title || "Your Page Title";
+  const description = metadata.metaDescription || "A concise description of your page.";
+  const url = metadata.canonical || "https://yoursite.com/this-page";
+
+  return [
+    { tag: "og:title", html: `<meta property="og:title" content="${title}">` },
+    { tag: "og:description", html: `<meta property="og:description" content="${description}">` },
+    { tag: "og:url", html: `<meta property="og:url" content="${url}">` },
+    { tag: "og:type", html: '<meta property="og:type" content="article">' },
+    { tag: "og:image", html: '<meta property="og:image" content="https://yoursite.com/images/page-image.png">' },
+    { tag: "og:image:width", html: '<meta property="og:image:width" content="1200">' },
+    { tag: "og:image:height", html: '<meta property="og:image:height" content="630">' },
+    { tag: "og:image:alt", html: `<meta property="og:image:alt" content="${title}">` },
+    { tag: "twitter:card", html: '<meta name="twitter:card" content="summary_large_image">' },
+    { tag: "twitter:title", html: `<meta name="twitter:title" content="${title}">` },
+    { tag: "twitter:description", html: `<meta name="twitter:description" content="${description}">` }
+  ];
+}
+
+function generateJsonLd(metadata, headings, signals) {
+  const title = metadata.title || "Page Title";
+  const description = metadata.metaDescription || "Page description.";
+  const url = metadata.canonical || "https://yoursite.com/page";
+
+  const schemas = [];
+
+  // Article schema (default for content pages)
+  schemas.push({
+    type: "Article",
+    json: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "Article",
+      headline: title,
+      description,
+      author: { "@type": "Person", name: "Author Name" },
+      publisher: { "@type": "Organization", name: "Your Organization", url: "https://yoursite.com" },
+      datePublished: new Date().toISOString().slice(0, 10),
+      dateModified: new Date().toISOString().slice(0, 10),
+      mainEntityOfPage: url,
+      image: "https://yoursite.com/images/article-image.png"
+    }, null, 2)
+  });
+
+  // FAQ schema from question headings
+  const questionHeadings = (headings || []).filter((h) =>
+    h.text.includes("?") || h.text.includes("？") ||
+    /^(what|how|why|when|where|who|which|can|do|does|is|are|should)\b/i.test(h.text)
+  );
+
+  if (questionHeadings.length >= 2) {
+    schemas.push({
+      type: "FAQPage",
+      json: JSON.stringify({
+        "@context": "https://schema.org",
+        "@type": "FAQPage",
+        mainEntity: questionHeadings.slice(0, 5).map((h) => ({
+          "@type": "Question",
+          name: h.text,
+          acceptedAnswer: {
+            "@type": "Answer",
+            text: `[Replace with the answer visible on the page for: ${h.text}]`
+          }
+        }))
+      }, null, 2)
+    });
+  }
+
+  // Breadcrumb
+  schemas.push({
+    type: "BreadcrumbList",
+    json: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "BreadcrumbList",
+      itemListElement: [
+        { "@type": "ListItem", position: 1, name: "Home", item: "https://yoursite.com/" },
+        { "@type": "ListItem", position: 2, name: "Section", item: "https://yoursite.com/section/" },
+        { "@type": "ListItem", position: 3, name: title, item: url }
+      ]
+    }, null, 2)
+  });
+
+  return schemas;
+}
+
+function generateRobotsTxtAiSection() {
+  return {
+    label: "robots.txt AI Crawler Section",
+    content: [
+      "# AI Crawler Rules — REVIEW BEFORE ENABLING",
+      "# WARNING: Uncomment only the crawlers you want to explicitly allow.",
+      "# These rules override any existing User-agent: * Disallow: / rules.",
+      "# Make sure this does not expose private/admin paths unintentionally.",
+      "",
+      "# User-agent: GPTBot",
+      "# Allow: /",
+      "",
+      "# User-agent: ChatGPT-User",
+      "# Allow: /",
+      "",
+      "# User-agent: Google-Extended",
+      "# Allow: /",
+      "",
+      "# User-agent: PerplexityBot",
+      "# Allow: /",
+      "",
+      "# User-agent: ClaudeBot",
+      "# Allow: /",
+      "",
+      "# User-agent: anthropic-ai",
+      "# Allow: /",
+      "",
+      "# User-agent: Applebot-Extended",
+      "# Allow: /",
+      ""
+    ].join("\n")
+  };
+}
+
+function generateLlmsTxt(metadata) {
+  const title = metadata.title || "Your Site Name";
+  const url = metadata.canonical || "https://yoursite.com";
+  const host = (() => { try { return new URL(url).origin; } catch { return "https://yoursite.com"; } })();
+
+  return {
+    label: "llms.txt",
+    content: [
+      `# ${title}`,
+      "",
+      "> One-sentence description of what this site does and who it serves.",
+      "",
+      `Canonical: ${host}`,
+      "",
+      "## About",
+      "",
+      "- Describe what this site does in 1-2 sentences.",
+      "- Describe the primary audience.",
+      "- Mention what makes the content uniquely trustworthy.",
+      "",
+      "## Priority URLs",
+      "",
+      `- ${host}/`,
+      `- ${host}/pricing`,
+      `- ${host}/docs`,
+      `- ${host}/blog`,
+      "",
+      "## Recommended Sources",
+      "",
+      "- Link to pages with first-party research, methodology, or clear product facts.",
+      "",
+      "## AI Assistant Guidance",
+      "",
+      "- Use the latest canonical URLs when citing this site.",
+      "- Prefer pages with explicit dates, authors, or methodology notes.",
+      "",
+      "## Update Policy",
+      "",
+      "- Content is reviewed and updated [weekly/monthly/quarterly].",
+      ""
+    ].join("\n")
+  };
+}
+
+function generateHeadingFix(headings) {
+  if (!headings || headings.length === 0) {
+    return {
+      label: "Suggested Heading Structure",
+      content: [
+        "<!-- Suggested answer-first heading structure -->",
+        "<h1>Page Topic — What This Is</h1>",
+        "<p>[2-4 sentences: direct answer, who it's for, key limitation]</p>",
+        "",
+        "<h2>What is [Topic]?</h2>",
+        "<p>[Definition and context]</p>",
+        "",
+        "<h2>How does [Topic] work?</h2>",
+        "<p>[Process or methodology]</p>",
+        "",
+        "<h2>Who should use [Topic]?</h2>",
+        "<p>[Target audience and use cases]</p>",
+        "",
+        "<h2>[Topic] vs Alternatives</h2>",
+        "<p>[Comparison with alternatives]</p>",
+        "",
+        "<h2>Frequently Asked Questions</h2>",
+        "<h3>Question 1?</h3>",
+        "<p>[Answer]</p>",
+        "<h3>Question 2?</h3>",
+        "<p>[Answer]</p>"
+      ].join("\n")
+    };
+  }
+
+  return null;
+}
+
+function buildFixSummary(fixes) {
+  const metaCount = fixes.metaTags.length;
+  const ogCount = fixes.ogTags.length;
+  const schemaCount = fixes.jsonLdSchemas.length;
+  const hasRobots = fixes.robotsTxt !== null;
+  const hasLlms = fixes.llmsTxt !== null;
+  const hasHeading = fixes.headingFix !== null;
+
+  const parts = [];
+  if (metaCount > 0) parts.push(`${metaCount} meta tags`);
+  if (ogCount > 0) parts.push(`${ogCount} OG/Twitter tags`);
+  if (schemaCount > 0) parts.push(`${schemaCount} JSON-LD schema(s)`);
+  if (hasRobots) parts.push("robots.txt AI section");
+  if (hasLlms) parts.push("llms.txt template");
+  if (hasHeading) parts.push("heading structure");
+
+  return `Generated ${parts.join(", ")}.`;
+}
+
+export async function generateAutoFix(input, options = {}) {
+  const audit = await auditPage(input, options);
+
+  const metaTags = generateMetaTags(audit.metadata, audit.signals);
+  // Always generate OG/Twitter tags as templates — user applies what's missing
+  const ogTags = generateOgTags(audit.metadata);
+  const jsonLdSchemas = audit.signals.json_ld.count === 0
+    ? generateJsonLd(audit.metadata, audit.headings, audit.signals)
+    : [];
+  const robotsTxt = generateRobotsTxtAiSection();
+  const llmsTxt = generateLlmsTxt(audit.metadata);
+  const headingFix = audit.headingStats.questionHeadingCount === 0
+    ? generateHeadingFix(audit.headings)
+    : null;
+
+  return {
+    kind: "geo-auto-fix",
+    input,
+    source: audit.reference,
+    auditScore: audit.score.score,
+    metaTags,
+    ogTags,
+    jsonLdSchemas,
+    robotsTxt,
+    llmsTxt,
+    headingFix,
+    summary: buildFixSummary({ metaTags, ogTags, jsonLdSchemas, robotsTxt, llmsTxt, headingFix })
+  };
+}
+
+export function renderAutoFixMarkdown(report) {
+  const lines = [
+    "# GEO Auto-Fix: Generated Code",
+    "",
+    `- Source: \`${report.source}\``,
+    `- Audit Score: \`${report.auditScore}/100\``,
+    `- Summary: ${report.summary}`,
+    ""
+  ];
+
+  if (report.metaTags.length > 0) {
+    lines.push("## Meta Tags", "", "Add these to your `<head>`:", "", "```html");
+    for (const tag of report.metaTags) {
+      lines.push(`<!-- ${tag.priority}: ${tag.tag}${tag.condition ? ` (${tag.condition})` : ""} -->`);
+      lines.push(tag.html);
+    }
+    lines.push("```", "");
+  }
+
+  if (report.ogTags.length > 0) {
+    lines.push("## Open Graph & Twitter Tags", "", "```html");
+    for (const tag of report.ogTags) {
+      lines.push(tag.html);
+    }
+    lines.push("```", "");
+  }
+
+  if (report.jsonLdSchemas.length > 0) {
+    lines.push("## JSON-LD Structured Data", "");
+    for (const schema of report.jsonLdSchemas) {
+      lines.push(`### ${schema.type}`, "", "```html", `<script type="application/ld+json">`, schema.json, "</script>", "```", "");
+    }
+  }
+
+  if (report.robotsTxt) {
+    lines.push("## robots.txt AI Section", "", "Append to your `robots.txt`:", "", "```", report.robotsTxt.content, "```", "");
+  }
+
+  if (report.llmsTxt) {
+    lines.push("## llms.txt Template", "", "Save as `llms.txt` in your site root:", "", "```", report.llmsTxt.content, "```", "");
+  }
+
+  if (report.headingFix) {
+    lines.push("## Suggested Heading Structure", "", "```html", report.headingFix.content, "```", "");
+  }
+
+  return lines.join("\n");
+}
+
+export async function writeAutoFixOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}

package/src/batch-full-page-audit.js

@@ -0,0 +1,151 @@
+import { writeScanOutput } from "./scan.js";
+import { fullPageAudit } from "./full-page-audit.js";
+
+export async function batchFullPageAudit(urls, options = {}) {
+  if (!urls || urls.length === 0) {
+    throw new Error("batch-full-page-audit requires at least one URL or file path");
+  }
+
+  const concurrency = options.concurrency || 2;
+  const results = [];
+  const errors = [];
+
+  const chunks = [];
+  for (let i = 0; i < urls.length; i += concurrency) {
+    chunks.push(urls.slice(i, i + concurrency));
+  }
+
+  for (const chunk of chunks) {
+    const chunkResults = await Promise.all(
+      chunk.map(async (url) => {
+        try {
+          const result = await fullPageAudit(url, options);
+          return { ok: true, url, data: result };
+        } catch (err) {
+          return { ok: false, url, error: err.message };
+        }
+      })
+    );
+
+    for (const result of chunkResults) {
+      if (result.ok) {
+        results.push(result.data);
+      } else {
+        errors.push({ url: result.url, error: result.error });
+      }
+    }
+  }
+
+  // Compute aggregate stats
+  const scores = results.map((r) => r.compositeScore);
+  const avgScore = scores.length > 0 ? Math.round(scores.reduce((a, b) => a + b, 0) / scores.length) : 0;
+  const minScore = scores.length > 0 ? Math.min(...scores) : 0;
+  const maxScore = scores.length > 0 ? Math.max(...scores) : 0;
+
+  // Dimension averages
+  const dimensionKeys = ["base", "citability", "eeat", "readability", "headingStructure", "internalLinks", "socialMeta", "platformReady", "schema", "freshness", "security", "topics"];
+  const dimensionAverages = {};
+  for (const key of dimensionKeys) {
+    const dimScores = results.map((r) => r.dimensions[key]?.score || 0);
+    dimensionAverages[key] = dimScores.length > 0 ? Math.round(dimScores.reduce((a, b) => a + b, 0) / dimScores.length) : 0;
+  }
+
+  // Weakest pages
+  const weakest = [...results]
+    .sort((a, b) => a.compositeScore - b.compositeScore)
+    .slice(0, 5);
+
+  // Most common issues
+  const issueCounts = {};
+  for (const result of results) {
+    for (const issue of result.topIssues || []) {
+      const key = issue.issue;
+      issueCounts[key] = (issueCounts[key] || 0) + 1;
+    }
+  }
+  const commonIssues = Object.entries(issueCounts)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 10)
+    .map(([issue, count]) => ({ issue, count, percentage: Math.round((count / results.length) * 100) }));
+
+  return {
+    kind: "geo-batch-full-page-audit",
+    totalUrls: urls.length,
+    successful: results.length,
+    failed: errors.length,
+    avgScore,
+    minScore,
+    maxScore,
+    dimensionAverages,
+    results,
+    weakest,
+    commonIssues,
+    errors,
+    summary: `Batch audit: ${results.length}/${urls.length} pages. Average composite: ${avgScore}/100. Range: ${minScore}-${maxScore}.`
+  };
+}
+
+export function renderBatchFullPageAuditMarkdown(report) {
+  const lines = [
+    "# Batch Full Page Audit",
+    "",
+    `- Pages audited: \`${report.successful}/${report.totalUrls}\``,
+    `- Failures: \`${report.failed}\``,
+    `- **Average Composite Score: \`${report.avgScore}/100\`**`,
+    `- Range: \`${report.minScore}\` - \`${report.maxScore}\``,
+    `- Summary: ${report.summary}`,
+    "",
+    "## Dimension Averages",
+    "",
+    "| Dimension | Average Score |",
+    "|-----------|--------------|"
+  ];
+
+  const dimLabels = {
+    base: "Base Audit", citability: "Citability", eeat: "E-E-A-T",
+    readability: "Readability", headingStructure: "Heading Structure",
+    internalLinks: "Internal Links", socialMeta: "Social Meta",
+    platformReady: "Platform Readiness", schema: "Schema",
+    freshness: "Freshness", security: "Security", topics: "Topics"
+  };
+
+  for (const [key, avg] of Object.entries(report.dimensionAverages)) {
+    const icon = avg >= 70 ? "🟢" : avg >= 40 ? "🟡" : "🔴";
+    lines.push(`| ${icon} ${dimLabels[key] || key} | ${avg}/100 |`);
+  }
+
+  lines.push("", "## Page Results", "", "| Page | Composite | Label |", "|------|-----------|-------|");
+  for (const result of report.results) {
+    const short = result.input.length > 50 ? `...${result.input.slice(-47)}` : result.input;
+    const icon = result.compositeScore >= 70 ? "🟢" : result.compositeScore >= 40 ? "🟡" : "🔴";
+    lines.push(`| ${short} | ${icon} ${result.compositeScore}/100 | ${result.compositeLabel} |`);
+  }
+
+  if (report.weakest.length > 0) {
+    lines.push("", "## Weakest Pages", "");
+    for (const page of report.weakest) {
+      lines.push(`- **${page.compositeScore}/100** — \`${page.input}\``);
+    }
+  }
+
+  if (report.commonIssues.length > 0) {
+    lines.push("", "## Most Common Issues", "");
+    for (const issue of report.commonIssues) {
+      lines.push(`- (${issue.percentage}% of pages) ${issue.issue}`);
+    }
+  }
+
+  if (report.errors.length > 0) {
+    lines.push("", "## Errors", "");
+    for (const err of report.errors) {
+      lines.push(`- ❌ \`${err.url}\`: ${err.error}`);
+    }
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+export async function writeBatchFullPageAuditOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}