aeo-ready 1.0.0 → 1.2.0

package/src/checks/ai-visibility/structured-data.js

@@ -1,180 +0,0 @@
-export async function runStructuredDataChecks(context) {
-  const checks = [
-    checkSchemaOrg(context),
-    checkFaqMarkup(context),
-    checkRichSchemas(context),
-    checkOpenGraph(context),
-  ];
-
-  const score = checks.reduce((sum, c) => sum + (c.passed ? c.points : 0), 0);
-  return { score, maxScore: 12, checks };
-}
-
-function checkSchemaOrg(context) {
-  const allContent = getAllContent(context);
-  const html = context.html || "";
-
-  const jsonLdBlocks = extractJsonLd(html);
-  if (jsonLdBlocks.length === 0 && !allContent.includes("schema.org")) {
-    return fail(
-      "Schema.org markup",
-      4,
-      "No schema.org structured data found. Add JSON-LD with appropriate type (SoftwareApplication, Person, Article, Organization).",
-    );
-  }
-
-  let points = 2;
-  const types = jsonLdBlocks.map((b) => b["@type"]).filter(Boolean);
-  const hasCorrectType = hasAppropriateType(types, context.siteType);
-  if (hasCorrectType) points += 1;
-  const hasRequiredFields = jsonLdBlocks.some((b) => hasMinimumFields(b));
-  if (hasRequiredFields) points += 1;
-
-  if (points === 4) return pass("Schema.org markup", 4);
-  const issues = [];
-  if (!hasCorrectType) issues.push("type doesn't match site category");
-  if (!hasRequiredFields) issues.push("missing required fields");
-  return partial(
-    "Schema.org markup",
-    points,
-    4,
-    `Schema.org present but: ${issues.join(", ")}.`,
-  );
-}
-
-function checkFaqMarkup(context) {
-  const html = context.html || "";
-  const allContent = getAllContent(context);
-
-  const hasFaqSchema =
-    allContent.includes("FAQPage") || allContent.includes("Question");
-  const hasFaqContent = /faq|frequently asked|common questions/i.test(
-    allContent,
-  );
-
-  if (hasFaqSchema) return pass("FAQ markup", 3);
-  if (hasFaqContent) {
-    return partial(
-      "FAQ markup",
-      1,
-      3,
-      "FAQ content exists but not marked up with FAQPage schema. Add JSON-LD FAQPage.",
-    );
-  }
-  return fail(
-    "FAQ markup",
-    3,
-    "No FAQ markup. Add FAQPage schema for common questions — these surface directly in AI answers.",
-  );
-}
-
-function checkRichSchemas(context) {
-  const allContent = getAllContent(context);
-
-  const schemas = [];
-  if (allContent.includes("BreadcrumbList")) schemas.push("Breadcrumb");
-  if (allContent.includes("HowTo")) schemas.push("HowTo");
-  if (
-    allContent.includes("Product") ||
-    allContent.includes("SoftwareApplication")
-  )
-    schemas.push("Product");
-  if (allContent.includes("VideoObject")) schemas.push("Video");
-  if (allContent.includes("Review") || allContent.includes("AggregateRating"))
-    schemas.push("Review");
-
-  if (schemas.length >= 2)
-    return pass("Rich schemas (Breadcrumb/HowTo/Product)", 3);
-  if (schemas.length === 1)
-    return partial(
-      "Rich schemas (Breadcrumb/HowTo/Product)",
-      2,
-      3,
-      `Only ${schemas[0]} schema found. Add more rich schemas for better AI comprehension.`,
-    );
-  return fail(
-    "Rich schemas (Breadcrumb/HowTo/Product)",
-    3,
-    "No rich schemas (BreadcrumbList, HowTo, Product). These help AI understand page context and relationships.",
-  );
-}
-
-function checkOpenGraph(context) {
-  const html = context.html || "";
-
-  const hasOgTitle = /og:title/i.test(html);
-  const hasOgDesc = /og:description/i.test(html);
-  const hasMetaDesc = /name=["']description["']/i.test(html);
-
-  let points = 0;
-  if (hasOgTitle) points += 1;
-  if (hasOgDesc || hasMetaDesc) points += 1;
-
-  if (points === 2) return pass("Open Graph + meta description", 2);
-  if (points === 1)
-    return partial(
-      "Open Graph + meta description",
-      1,
-      2,
-      "Partial OG/meta tags. Need both og:title and description.",
-    );
-  return fail(
-    "Open Graph + meta description",
-    2,
-    "No Open Graph or meta description tags. AI systems use these for page summaries.",
-  );
-}
-
-function extractJsonLd(html) {
-  const blocks = [];
-  const regex =
-    /<script[^>]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi;
-  let match;
-  while ((match = regex.exec(html)) !== null) {
-    try {
-      const parsed = JSON.parse(match[1]);
-      if (Array.isArray(parsed)) blocks.push(...parsed);
-      else blocks.push(parsed);
-    } catch {
-      /* skip invalid */
-    }
-  }
-  return blocks;
-}
-
-function hasAppropriateType(types, siteType) {
-  const typeMap = {
-    saas: ["SoftwareApplication", "WebApplication", "Product", "Organization"],
-    api: ["SoftwareApplication", "WebAPI", "TechArticle"],
-    content: ["Article", "BlogPosting", "WebSite", "Organization"],
-    personal: ["Person", "ProfilePage", "WebSite"],
-  };
-  const expected = typeMap[siteType] || [];
-  return types.some((t) => expected.includes(t));
-}
-
-function hasMinimumFields(block) {
-  const required = ["name", "@type"];
-  return required.every((f) => block[f]);
-}
-
-function getAllContent(context) {
-  if (context.mode === "url") {
-    return Object.values(context.pages || {})
-      .map((p) => p?.text || "")
-      .join("\n");
-  }
-  return Object.values(context.fileContents || {}).join("\n");
-}
-
-function pass(name, points) {
-  return { name, passed: true, points, maxPoints: points };
-}
-
-function partial(name, points, maxPoints, fix) {
-  return { name, passed: false, points, maxPoints, fix };
-}
-
-function fail(name, maxPoints, fix) {
-  return { name, passed: false, points: 0, maxPoints, fix };
-}

package/src/dashboard/sections/agent-readiness.js

@@ -1,71 +0,0 @@
-export function renderAgentReadiness(result) {
-  return renderScorecard(
-    "Agent Readiness",
-    result.agentReadiness,
-    "agent-readiness",
-  );
-}
-
-function renderScorecard(title, scorecard, id) {
-  const pct = Math.round((scorecard.score / scorecard.maxScore) * 100);
-  const gradeClass =
-    pct >= 80
-      ? "grade-a"
-      : pct >= 60
-        ? "grade-b"
-        : pct >= 40
-          ? "grade-c"
-          : "grade-d";
-
-  let html = `<div class="scorecard" id="${id}">
-  <div class="scorecard-header">
-    <h3>${title}</h3>
-    <span class="pct ${gradeClass}">${scorecard.score}/${scorecard.maxScore} (${pct}%)</span>
-  </div>`;
-
-  for (const [catName, cat] of Object.entries(scorecard.categories)) {
-    const label = formatName(catName);
-    const catPct = Math.round((cat.score / cat.maxScore) * 100);
-    const barColor =
-      catPct >= 80 ? "#3fb950" : catPct >= 50 ? "#d29922" : "#f85149";
-
-    html += `\n  <div class="category">
-    <div class="cat-header">
-      <span class="cat-name">${label}</span>
-      <span class="cat-score">${cat.score}/${cat.maxScore}</span>
-      <div class="cat-bar"><div class="cat-bar-fill" style="width:${catPct}%;background:${barColor}"></div></div>
-    </div>`;
-
-    for (const check of cat.checks) {
-      if (check.passed) {
-        html += `\n    <div class="check pass">+ ${check.name} [${check.points}]</div>`;
-      } else {
-        html += `\n    <div class="check fail">- ${check.name} [${check.points || 0}/${check.maxPoints}]`;
-        if (check.fix) {
-          html += `<span class="fix">${escapeHtml(check.fix)}</span>`;
-        }
-        html += `</div>`;
-      }
-    }
-
-    html += `\n  </div>`;
-  }
-
-  html += `\n</div>`;
-  return html;
-}
-
-function formatName(camelCase) {
-  return camelCase
-    .replace(/([A-Z])/g, " $1")
-    .replace(/^./, (c) => c.toUpperCase())
-    .trim();
-}
-
-function escapeHtml(str) {
-  return str
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;");
-}

package/src/dashboard/sections/ai-visibility.js

@@ -1,67 +0,0 @@
-export function renderAiVisibility(result) {
-  return renderScorecard("AI Visibility", result.aiVisibility, "ai-visibility");
-}
-
-function renderScorecard(title, scorecard, id) {
-  const pct = Math.round((scorecard.score / scorecard.maxScore) * 100);
-  const gradeClass =
-    pct >= 80
-      ? "grade-a"
-      : pct >= 60
-        ? "grade-b"
-        : pct >= 40
-          ? "grade-c"
-          : "grade-d";
-
-  let html = `<div class="scorecard" id="${id}">
-  <div class="scorecard-header">
-    <h3>${title}</h3>
-    <span class="pct ${gradeClass}">${scorecard.score}/${scorecard.maxScore} (${pct}%)</span>
-  </div>`;
-
-  for (const [catName, cat] of Object.entries(scorecard.categories)) {
-    const label = formatName(catName);
-    const catPct = Math.round((cat.score / cat.maxScore) * 100);
-    const barColor =
-      catPct >= 80 ? "#3fb950" : catPct >= 50 ? "#d29922" : "#f85149";
-
-    html += `\n  <div class="category">
-    <div class="cat-header">
-      <span class="cat-name">${label}</span>
-      <span class="cat-score">${cat.score}/${cat.maxScore}</span>
-      <div class="cat-bar"><div class="cat-bar-fill" style="width:${catPct}%;background:${barColor}"></div></div>
-    </div>`;
-
-    for (const check of cat.checks) {
-      if (check.passed) {
-        html += `\n    <div class="check pass">+ ${check.name} [${check.points}]</div>`;
-      } else {
-        html += `\n    <div class="check fail">- ${check.name} [${check.points || 0}/${check.maxPoints}]`;
-        if (check.fix) {
-          html += `<span class="fix">${escapeHtml(check.fix)}</span>`;
-        }
-        html += `</div>`;
-      }
-    }
-
-    html += `\n  </div>`;
-  }
-
-  html += `\n</div>`;
-  return html;
-}
-
-function formatName(camelCase) {
-  return camelCase
-    .replace(/([A-Z])/g, " $1")
-    .replace(/^./, (c) => c.toUpperCase())
-    .trim();
-}
-
-function escapeHtml(str) {
-  return str
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;");
-}

package/src/dashboard/sections/recommendations.js

@@ -1,49 +0,0 @@
-export function renderRecommendations(result) {
-  const failed = [];
-
-  for (const scorecard of [result.agentReadiness, result.aiVisibility]) {
-    for (const [catName, cat] of Object.entries(scorecard.categories)) {
-      for (const check of cat.checks) {
-        if (!check.passed && check.fix) {
-          const impact = check.maxPoints - (check.points || 0);
-          failed.push({ ...check, category: catName, impact });
-        }
-      }
-    }
-  }
-
-  failed.sort((a, b) => b.impact - a.impact);
-  const top = failed.slice(0, 8);
-
-  if (top.length === 0) {
-    return `<h2 id="recommendations">Recommendations</h2>\n<p style="color:#3fb950;font-size:13px;">All checks passing. Nice.</p>`;
-  }
-
-  let html = `<h2 id="recommendations">Top Recommendations</h2>\n<p style="color:#8b949e;font-size:12px;margin-bottom:12px;">Sorted by point impact — fix these first.</p>`;
-
-  for (const rec of top) {
-    const category = formatName(rec.category);
-    html += `\n<div class="rec">
-  <div class="rec-title">${escapeHtml(rec.name)}</div>
-  <div class="rec-fix">${escapeHtml(rec.fix)}</div>
-  <div class="rec-impact">+${rec.impact} points · ${category}</div>
-</div>`;
-  }
-
-  return html;
-}
-
-function formatName(camelCase) {
-  return camelCase
-    .replace(/([A-Z])/g, " $1")
-    .replace(/^./, (c) => c.toUpperCase())
-    .trim();
-}
-
-function escapeHtml(str) {
-  return str
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;");
-}

package/src/fix/generators/agents-json.js

@@ -1,73 +0,0 @@
-import { existsSync, readFileSync } from "fs";
-import { join } from "path";
-
-export function generateAgentsJson(check, scanResult, dir) {
-  const { siteType, target } = scanResult;
-
-  const hostname = extractHostname(target);
-  const name = inferName(dir, hostname);
-
-  const manifest = {
-    schema_version: "1.0",
-    name,
-    description: "",
-    url: target || "",
-    site_type: siteType,
-    interfaces: {
-      human: "/",
-      llm: "/llms.txt",
-      structured: "/.well-known/agent.json",
-    },
-    capabilities: getCapabilities(siteType),
-    contact: {},
-  };
-
-  if (siteType === "saas" || siteType === "api") {
-    manifest.api_base = "";
-    manifest.openapi = "/openapi.json";
-    manifest.protocols = ["rest"];
-  }
-
-  return {
-    file: ".well-known/agent.json",
-    description: `Agent manifest for ${siteType} site — fill in description and contact`,
-    draft: true,
-    content: JSON.stringify(manifest, null, 2) + "\n",
-  };
-}
-
-function getCapabilities(siteType) {
-  switch (siteType) {
-    case "saas":
-      return ["pricing-lookup", "api-integration", "trial-signup"];
-    case "api":
-      return ["api-integration", "sdk-install", "docs-lookup"];
-    case "content":
-      return ["content-search", "topic-lookup", "citation"];
-    case "personal":
-      return ["contact", "expertise-lookup", "project-listing"];
-    default:
-      return [];
-  }
-}
-
-function extractHostname(target) {
-  if (!target) return null;
-  try {
-    return new URL(target).hostname.replace("www.", "");
-  } catch {
-    return null;
-  }
-}
-
-function inferName(dir, hostname) {
-  const pkgPath = join(dir, "package.json");
-  if (existsSync(pkgPath)) {
-    try {
-      const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
-      if (pkg.name) return pkg.name;
-    } catch {}
-  }
-  if (hostname) return hostname.split(".")[0];
-  return "";
-}

package/src/fix/generators/agents-md.js

@@ -1,85 +0,0 @@
-import { existsSync, readFileSync, readdirSync } from "fs";
-import { join } from "path";
-
-export function generateAgentsMd(check, scanResult, dir) {
-  const { siteType, target } = scanResult;
-  const name = inferName(dir);
-  const structure = inferStructure(dir);
-
-  const content = `# ${name || "[Project Name]"}
-
-> [One sentence: what this project does]
-
-## Project structure
-
-${structure || "```\n[Add key directories and their purpose]\n```"}
-
-## Key files
-
-- Entry point: [path]
-- Config: [path]
-- API routes: [path]
-
-## Development
-
-\`\`\`bash
-[install command]
-[run command]
-\`\`\`
-
-## Conventions
-
-- [Language/framework convention 1]
-- [Language/framework convention 2]
-
-## Constraints
-
-- [Rate limits, auth requirements, etc]
-- [External dependencies]
-`;
-
-  return {
-    file: "AGENTS.md",
-    description: "Draft AGENTS.md — REVIEW AND EDIT with real project details",
-    draft: true,
-    content,
-  };
-}
-
-function inferName(dir) {
-  const pkgPath = join(dir, "package.json");
-  if (existsSync(pkgPath)) {
-    try {
-      return JSON.parse(readFileSync(pkgPath, "utf8")).name || "";
-    } catch {}
-  }
-  const pomPath = join(dir, "pom.xml");
-  if (existsSync(pomPath)) {
-    const pom = readFileSync(pomPath, "utf8");
-    const match = pom.match(/<artifactId>([^<]+)<\/artifactId>/);
-    if (match) return match[1];
-  }
-  return "";
-}
-
-function inferStructure(dir) {
-  try {
-    const entries = readdirSync(dir, { withFileTypes: true });
-    const dirs = entries
-      .filter(
-        (e) =>
-          e.isDirectory() &&
-          !e.name.startsWith(".") &&
-          e.name !== "node_modules",
-      )
-      .map((e) => e.name)
-      .slice(0, 10);
-
-    if (dirs.length === 0) return null;
-
-    const lines = dirs.map((d) => `${d}/`);
-    return "```\n" + lines.join("\n") + "\n```";
-  } catch {
-    return null;
-  }
-}

package/src/fix/generators/llms-txt.js

@@ -1,166 +0,0 @@
-import { existsSync, readFileSync } from "fs";
-import { join } from "path";
-
-export function generateLlmsTxt(check, scanResult, dir) {
-  const { siteType, target } = scanResult;
-  const hostname = extractHostname(target);
-  const name = inferName(dir, hostname);
-
-  const content = generateByType(siteType, name, target);
-
-  return {
-    file: "llms.txt",
-    description: `Draft llms.txt for ${siteType} site — REVIEW AND EDIT before publishing`,
-    draft: true,
-    content,
-  };
-}
-
-function generateByType(siteType, name, target) {
-  const base = target || "https://example.com";
-
-  switch (siteType) {
-    case "saas":
-      return `# ${name || "[Company Name]"}
-
-> [One sentence: what problem you solve and for whom]
-
-## What it does
-- [Core capability 1]
-- [Core capability 2]
-- [Core capability 3]
-
-## Pricing
-- [Plan 1]: $X/mo — [what's included]
-- [Plan 2]: $X/mo — [what's included]
-- Details: ${base}/pricing
-
-## Integration
-- API docs: ${base}/docs
-- OpenAPI spec: ${base}/openapi.json
-- Auth: [API key / OAuth / etc]
-
-## Get started
-1. [Signup step]
-2. [First API call or setup]
-3. [See results]
-
-## Links
-- Documentation: ${base}/docs
-- Changelog: ${base}/changelog
-- Status: ${base}/status
-`;
-
-    case "api":
-      return `# ${name || "[Tool Name]"}
-
-> [One sentence: what this tool does]
-
-## Quick start
-\`\`\`bash
-[install command]
-\`\`\`
-
-## Key concepts
-- [Concept 1]: [one-line explanation]
-- [Concept 2]: [one-line explanation]
-
-## API reference
-- Base URL: ${base}/api/v1
-- Auth: [method]
-- OpenAPI: ${base}/openapi.json
-
-## SDKs
-- Node.js: \`npm install [package]\`
-- Python: \`pip install [package]\`
-
-## Links
-- Full docs: ${base}/docs
-- Examples: ${base}/examples
-- Changelog: ${base}/changelog
-`;
-
-    case "personal":
-      return `# ${name || "[Your Name]"}
-
-> [Role/title] — [what you're known for]
-
-## Expertise
-- [Area 1]
-- [Area 2]
-- [Area 3]
-
-## Notable work
-- [Project 1]: [one-line description] — [url]
-- [Project 2]: [one-line description] — [url]
-
-## Writing & speaking
-- [Topic you cover]
-- [Where to find your content]
-
-## Contact
-- Email: [email]
-- LinkedIn: [url]
-- Available for: [consulting / speaking / hiring / etc]
-`;
-
-    case "content":
-      return `# ${name || "[Publication Name]"}
-
-> [What topics you cover and your angle/expertise]
-
-## Topics
-- [Topic 1]: [what you cover, how many pieces]
-- [Topic 2]: [what you cover, how many pieces]
-
-## Best starting points
-- [Most important article]: ${base}/[path]
-- [Second article]: ${base}/[path]
-- [Third article]: ${base}/[path]
-
-## About
-- Author(s): [who writes]
-- Cadence: [how often you publish]
-- Angle: [what makes your coverage unique]
-
-## Links
-- All articles: ${base}/blog
-- RSS: ${base}/feed.xml
-- Newsletter: ${base}/subscribe
-`;
-
-    default:
-      return `# ${name || "[Site Name]"}
-
-> [One sentence: what this site is and who it's for]
-
-## What you'll find here
-- [Section 1]: [description]
-- [Section 2]: [description]
-
-## Links
-- Homepage: ${base}
-`;
-  }
-}
-
-function extractHostname(target) {
-  if (!target) return null;
-  try {
-    return new URL(target).hostname.replace("www.", "");
-  } catch {
-    return null;
-  }
-}
-
-function inferName(dir, hostname) {
-  const pkgPath = join(dir, "package.json");
-  if (existsSync(pkgPath)) {
-    try {
-      const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
-      if (pkg.name) return pkg.name;
-    } catch {}
-  }
-  if (hostname) return hostname.split(".")[0];
-  return "";
-}