aeo-ready 1.0.0

package/src/history/index.js

@@ -0,0 +1,47 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+
+const DIR_NAME = ".agent-web";
+const HISTORY_FILE = "history.json";
+
+export async function saveResult(result, baseDir) {
+  const dir = join(baseDir, DIR_NAME);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  const historyPath = join(dir, HISTORY_FILE);
+  const history = loadHistory(historyPath);
+
+  history.scans.push({
+    id: generateId(),
+    timestamp: result.timestamp,
+    score: result.score,
+    grade: result.grade,
+    siteType: result.siteType,
+    target: result.target,
+    agentReadiness: result.agentReadiness.score,
+    aiVisibility: result.aiVisibility.score,
+    benchmark: result.benchmark?.score ?? null,
+  });
+
+  writeFileSync(historyPath, JSON.stringify(history, null, 2));
+}
+
+export function loadHistory(historyPath) {
+  if (existsSync(historyPath)) {
+    try {
+      return JSON.parse(readFileSync(historyPath, "utf8"));
+    } catch {
+      /* corrupted — start fresh */
+    }
+  }
+  return { scans: [] };
+}
+
+export function getHistory(baseDir) {
+  const historyPath = join(baseDir, DIR_NAME, HISTORY_FILE);
+  return loadHistory(historyPath);
+}
+
+function generateId() {
+  return Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
+}

package/src/index.js

@@ -0,0 +1,2 @@
+export { scan } from "./scan.js";
+export { getHistory } from "./history/index.js";

package/src/scan.js

@@ -0,0 +1,358 @@
+import chalk from "chalk";
+import { fetchUrl, resolveUrl } from "./utils/fetch.js";
+import { detectSiteType } from "./utils/detect-type.js";
+import { runDiscoveryChecks } from "./checks/agent-readiness/discovery.js";
+import { runContentStructureChecks } from "./checks/agent-readiness/content-structure.js";
+import { runCapabilityChecks } from "./checks/agent-readiness/capability.js";
+import { runActionableChecks } from "./checks/agent-readiness/actionable.js";
+import { runStructuredDataChecks } from "./checks/ai-visibility/structured-data.js";
+import { runCitationReadinessChecks } from "./checks/ai-visibility/citation-readiness.js";
+import { runAuthorityChecks } from "./checks/ai-visibility/authority.js";
+import { runFreshnessChecks } from "./checks/ai-visibility/freshness.js";
+import { runBenchmark } from "./benchmark/agentic-seo.js";
+import { saveResult } from "./history/index.js";
+import { generateDashboard } from "./dashboard/generate.js";
+import { readdirSync, readFileSync, existsSync } from "fs";
+import { join } from "path";
+import { exec } from "child_process";
+
+export async function scan(opts) {
+  const { url, dir, json, benchmark } = opts;
+  const mode = url ? "url" : "repo";
+
+  if (!json) {
+    console.log(
+      chalk.bold("\n  aeo-ready") + chalk.dim(" — AI readiness audit\n"),
+    );
+  }
+
+  const context = await gatherContext(mode, url, dir);
+
+  if (!json) {
+    console.log(chalk.dim(`  Mode: ${mode} | Type: ${context.siteType}\n`));
+  }
+
+  const agentReadiness = await runAgentReadinessChecks(context);
+  const aiVisibility = await runAiVisibilityChecks(context);
+
+  const score = agentReadiness.score + aiVisibility.score;
+  const grade = scoreToGrade(score);
+
+  let benchmarkResult = null;
+  if (benchmark) {
+    benchmarkResult = await runBenchmark(mode === "url" ? url : dir);
+  }
+
+  const result = {
+    score,
+    grade,
+    siteType: context.siteType,
+    mode,
+    target: url || dir,
+    timestamp: new Date().toISOString(),
+    agentReadiness,
+    aiVisibility,
+    benchmark: benchmarkResult,
+  };
+
+  if (!json) {
+    printReport(result);
+  }
+
+  const baseDir = dir || process.cwd();
+  await saveResult(result, baseDir);
+
+  if (!json) {
+    const dashPath = await generateDashboard(result, baseDir);
+    console.log(chalk.dim(`  Dashboard: ${dashPath}\n`));
+    openInBrowser(dashPath);
+  }
+
+  return result;
+}
+
+async function gatherContext(mode, url, dir) {
+  const context = { mode, url, dir, pages: {}, files: [], html: "" };
+
+  if (mode === "url") {
+    const homepage = await fetchUrl(url);
+    context.html = homepage.text;
+    context.pages.home = homepage;
+
+    const fetches = [
+      fetchUrl(resolveUrl(url, "/llms.txt")),
+      fetchUrl(resolveUrl(url, "/robots.txt")),
+      fetchUrl(resolveUrl(url, "/sitemap.xml")),
+      fetchUrl(resolveUrl(url, "/.well-known/agent.json")),
+      fetchUrl(resolveUrl(url, "/openapi.json")),
+    ];
+
+    const [llms, robots, sitemap, agentJson, openapi] =
+      await Promise.all(fetches);
+    context.pages.llmsTxt = llms;
+    context.pages.robotsTxt = robots;
+    context.pages.sitemap = sitemap;
+    context.pages.agentJson = agentJson;
+    context.pages.openapi = openapi;
+  } else {
+    const fileList = listFiles(dir);
+    context.files = fileList;
+    context.fileContents = {};
+    for (const f of fileList) {
+      try {
+        context.fileContents[f] = readFileSync(join(dir, f), "utf8");
+      } catch {
+        /* skip binary/unreadable */
+      }
+    }
+    const indexHtml = [
+      "index.html",
+      "public/index.html",
+      "dist/index.html",
+    ].find((p) => existsSync(join(dir, p)));
+    if (indexHtml) {
+      context.html = readFileSync(join(dir, indexHtml), "utf8");
+    }
+  }
+
+  context.siteType = detectSiteType({
+    html: context.html,
+    files: context.files,
+    url,
+  });
+
+  return context;
+}
+
+function listFiles(dir) {
+  const skip = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    ".next",
+    ".venv",
+    "__pycache__",
+    "target",
+    ".aeo-ready",
+  ]);
+  const results = [];
+
+  function walk(current, prefix) {
+    let entries;
+    try {
+      entries = readdirSync(join(dir, current), { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (skip.has(entry.name)) continue;
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walk(join(current, entry.name), rel);
+      } else {
+        results.push(rel);
+      }
+    }
+  }
+
+  walk("", "");
+  return results;
+}
+
+async function runAgentReadinessChecks(context) {
+  const discovery = await runDiscoveryChecks(context);
+  const contentStructure = await runContentStructureChecks(context);
+  const capability = await runCapabilityChecks(context);
+  const actionable = await runActionableChecks(context);
+
+  const score =
+    discovery.score +
+    contentStructure.score +
+    capability.score +
+    actionable.score;
+
+  return {
+    score,
+    maxScore: 50,
+    categories: { discovery, contentStructure, capability, actionable },
+  };
+}
+
+async function runAiVisibilityChecks(context) {
+  const structuredData = await runStructuredDataChecks(context);
+  const citationReadiness = await runCitationReadinessChecks(context);
+  const authority = await runAuthorityChecks(context);
+  const freshness = await runFreshnessChecks(context);
+
+  const score =
+    structuredData.score +
+    citationReadiness.score +
+    authority.score +
+    freshness.score;
+
+  return {
+    score,
+    maxScore: 50,
+    categories: { structuredData, citationReadiness, authority, freshness },
+  };
+}
+
+function scoreToGrade(score) {
+  if (score >= 80) return "A";
+  if (score >= 65) return "B";
+  if (score >= 50) return "C";
+  if (score >= 35) return "D";
+  return "F";
+}
+
+function printReport(result) {
+  const { score, grade, agentReadiness, aiVisibility, benchmark } = result;
+
+  const gradeColor =
+    grade === "A"
+      ? chalk.green
+      : grade === "B"
+        ? chalk.cyan
+        : grade === "C"
+          ? chalk.yellow
+          : chalk.red;
+
+  console.log(
+    `  ${bar(score, 100, 40)}  ${gradeColor.bold(grade)} ${score}/100\n`,
+  );
+
+  console.log(
+    chalk.dim(
+      "  Agent Readiness — can AI agents find, read, and use your site?",
+    ),
+  );
+  console.log(
+    chalk.dim(
+      "  AI Visibility — how accurately do AI search engines describe you?",
+    ),
+  );
+
+  if (agentReadiness.score < 25) {
+    console.log(
+      chalk.dim(
+        "\n  Agent Readiness is low — AI engines can't cite what they can't read.",
+      ),
+    );
+    console.log(chalk.dim("  Fix the agent side first. Visibility follows."));
+  }
+  console.log("");
+
+  printScorecard("Agent Readiness", agentReadiness);
+  printScorecard("AI Visibility", aiVisibility);
+
+  const allChecks = [
+    ...Object.values(agentReadiness.categories),
+    ...Object.values(aiVisibility.categories),
+  ].flatMap((c) => c.checks);
+  const passed = allChecks.filter((c) => c.passed).length;
+  const failed = allChecks.filter((c) => !c.passed && c.points === 0).length;
+  const partial = allChecks.length - passed - failed;
+
+  console.log(
+    chalk.dim(
+      `  ${chalk.green(passed + " passed")} · ${partial ? chalk.yellow(partial + " partial") + " · " : ""}${chalk.red(failed + " failed")} · ${allChecks.length} checks total\n`,
+    ),
+  );
+
+  if (benchmark && benchmark.available) {
+    printBenchmark(benchmark);
+  }
+}
+
+function printScorecard(name, scorecard) {
+  const pct = Math.round((scorecard.score / scorecard.maxScore) * 100);
+  console.log(
+    chalk.bold(`  ${name}`) +
+      chalk.dim(` ${scorecard.score}/${scorecard.maxScore} (${pct}%)`),
+  );
+
+  for (const [catName, cat] of Object.entries(scorecard.categories)) {
+    const label = formatCategoryName(catName);
+    const catPct = Math.round((cat.score / cat.maxScore) * 100);
+    const icon =
+      catPct >= 80
+        ? chalk.green("✓")
+        : catPct >= 40
+          ? chalk.yellow("◑")
+          : chalk.red("✗");
+    console.log(
+      `  ${icon} ${label.padEnd(28)} ${bar(cat.score, cat.maxScore, 20)} ${chalk.dim(`${cat.score}/${cat.maxScore} (${catPct}%)`)}`,
+    );
+
+    for (const check of cat.checks) {
+      if (check.passed) {
+        console.log(
+          chalk.green(`      +`) +
+            chalk.dim(` ${check.name} [${check.points}]`),
+        );
+      } else {
+        console.log(
+          chalk.red(`      -`) +
+            ` ${check.name} ` +
+            chalk.dim(`[${check.points || 0}/${check.maxPoints}]`),
+        );
+        if (check.fix) {
+          console.log(chalk.dim(`        ${check.fix}`));
+        }
+      }
+    }
+  }
+  console.log("");
+}
+
+function printBenchmark(benchmark) {
+  console.log(
+    chalk.dim("  ─── Second opinion: agentic-seo ───────────────────\n"),
+  );
+  console.log(
+    `  ${bar(benchmark.score, benchmark.maxScore, 20)} ${chalk.dim(`${benchmark.score}/${benchmark.maxScore}`)}${benchmark.grade ? chalk.dim(` (${benchmark.grade})`) : ""}\n`,
+  );
+
+  if (benchmark.categories) {
+    for (const [, cat] of Object.entries(benchmark.categories)) {
+      const pct =
+        cat.percentage ?? Math.round((cat.score / cat.maxScore) * 100);
+      const icon =
+        pct >= 80
+          ? chalk.green("✓")
+          : pct >= 40
+            ? chalk.yellow("◑")
+            : chalk.red("✗");
+      console.log(
+        `  ${icon} ${cat.name.padEnd(24)} ${bar(cat.score, cat.maxScore, 16)} ${chalk.dim(`${cat.score}/${cat.maxScore} (${pct}%)`)}`,
+      );
+    }
+    console.log("");
+  }
+}
+
+function bar(value, max, width) {
+  const filled = max > 0 ? Math.round((value / max) * width) : 0;
+  const empty = width - filled;
+  const pct = max > 0 ? Math.round((value / max) * 100) : 0;
+  const color = pct >= 80 ? chalk.green : pct >= 50 ? chalk.yellow : chalk.red;
+  return color("█".repeat(filled)) + chalk.dim("░".repeat(empty));
+}
+
+function formatCategoryName(camelCase) {
+  return camelCase
+    .replace(/([A-Z])/g, " $1")
+    .replace(/^./, (c) => c.toUpperCase())
+    .trim();
+}
+
+function openInBrowser(filePath) {
+  const cmd =
+    process.platform === "darwin"
+      ? "open"
+      : process.platform === "win32"
+        ? "start"
+        : "xdg-open";
+  exec(`${cmd} "${filePath}"`, () => {});
+}

package/src/track/index.js

@@ -0,0 +1,167 @@
+import chalk from "chalk";
+
+const PROVIDERS = {
+  claude: {
+    name: "Claude",
+    url: "https://api.anthropic.com/v1/messages",
+    envKey: "ANTHROPIC_API_KEY",
+    model: "claude-sonnet-4-6",
+    call: callClaude,
+  },
+  openai: {
+    name: "ChatGPT",
+    url: "https://api.openai.com/v1/chat/completions",
+    envKey: "OPENAI_API_KEY",
+    model: "gpt-4o-mini",
+    call: callOpenAI,
+  },
+  google: {
+    name: "Gemini",
+    envKey: "GOOGLE_API_KEY",
+    model: "gemini-2.0-flash",
+    call: callGoogle,
+  },
+};
+
+const DEFAULT_PROMPTS = [
+  { template: "What is {company}?", category: "brand" },
+  { template: "What does {company} do?", category: "brand" },
+  { template: "Best {category} tools?", category: "discovery" },
+];
+
+export async function track(scanResult, config) {
+  const company = config.company || inferCompany(scanResult);
+  const category = config.category || "";
+  const prompts = config.prompts || DEFAULT_PROMPTS;
+
+  const available = getAvailableProviders();
+  if (available.length === 0) {
+    return null;
+  }
+
+  const rendered = prompts.map((p) => ({
+    ...p,
+    text: p.template
+      .replace("{company}", company)
+      .replace("{category}", category),
+  }));
+
+  const results = [];
+
+  for (const prompt of rendered) {
+    for (const provider of available) {
+      try {
+        const response = await provider.call(prompt.text, provider.model);
+        results.push({
+          provider: provider.name,
+          prompt: prompt.text,
+          category: prompt.category,
+          response: response.slice(0, 500),
+          mentions: response.toLowerCase().includes(company.toLowerCase()),
+        });
+      } catch {
+        results.push({
+          provider: provider.name,
+          prompt: prompt.text,
+          category: prompt.category,
+          response: "(failed)",
+          mentions: false,
+        });
+      }
+    }
+  }
+
+  return results;
+}
+
+export function printTrackResults(results, company) {
+  if (!results || results.length === 0) return;
+
+  console.log(chalk.bold("\n  AI Visibility — what models say about you\n"));
+
+  const grouped = {};
+  for (const r of results) {
+    if (!grouped[r.prompt]) grouped[r.prompt] = [];
+    grouped[r.prompt].push(r);
+  }
+
+  for (const [prompt, responses] of Object.entries(grouped)) {
+    console.log(chalk.dim(`  > "${prompt}"\n`));
+    for (const r of responses) {
+      const icon = r.mentions ? chalk.green("cited") : chalk.red("not cited");
+      console.log(`    ${chalk.bold(r.provider)} [${icon}]`);
+      const lines = r.response.split("\n").slice(0, 3);
+      for (const line of lines) {
+        console.log(chalk.dim(`    ${line.slice(0, 80)}`));
+      }
+      console.log("");
+    }
+  }
+
+  const total = results.length;
+  const cited = results.filter((r) => r.mentions).length;
+  const rate = Math.round((cited / total) * 100);
+  console.log(chalk.bold(`  Citation rate: ${cited}/${total} (${rate}%)\n`));
+}
+
+export function getAvailableProviders() {
+  return Object.values(PROVIDERS).filter((p) => process.env[p.envKey]);
+}
+
+function inferCompany(scanResult) {
+  const target = scanResult.target || "";
+  try {
+    return new URL(target).hostname.replace("www.", "").split(".")[0];
+  } catch {
+    return target.split("/").pop() || "unknown";
+  }
+}
+
+async function callClaude(prompt, model) {
+  const res = await fetch("https://api.anthropic.com/v1/messages", {
+    method: "POST",
+    headers: {
+      "x-api-key": process.env.ANTHROPIC_API_KEY,
+      "anthropic-version": "2023-06-01",
+      "content-type": "application/json",
+    },
+    body: JSON.stringify({
+      model,
+      max_tokens: 300,
+      messages: [{ role: "user", content: prompt }],
+    }),
+  });
+  const data = await res.json();
+  return data.content?.[0]?.text || "";
+}
+
+async function callOpenAI(prompt, model) {
+  const res = await fetch("https://api.openai.com/v1/chat/completions", {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
+      "content-type": "application/json",
+    },
+    body: JSON.stringify({
+      model,
+      messages: [{ role: "user", content: prompt }],
+      max_tokens: 300,
+    }),
+  });
+  const data = await res.json();
+  return data.choices?.[0]?.message?.content || "";
+}
+
+async function callGoogle(prompt, model) {
+  const key = process.env.GOOGLE_API_KEY;
+  const res = await fetch(
+    `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${key}`,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ contents: [{ parts: [{ text: prompt }] }] }),
+    },
+  );
+  const data = await res.json();
+  return data.candidates?.[0]?.content?.parts?.[0]?.text || "";
+}

package/src/utils/detect-type.js

@@ -0,0 +1,99 @@
+export function detectSiteType(signals) {
+  const { html, files, url } = signals;
+  const text = (html || "").toLowerCase();
+  const fileList = (files || []).map((f) => f.toLowerCase());
+
+  const scores = {
+    saas: scoreSaas(text, fileList, url),
+    api: scoreApi(text, fileList, url),
+    content: scoreContent(text, fileList, url),
+    personal: scorePersonal(text, fileList, url),
+  };
+
+  const sorted = Object.entries(scores).sort((a, b) => b[1] - a[1]);
+  if (sorted[0][1] === 0) return "unknown";
+  return sorted[0][0];
+}
+
+function scoreSaas(text, files, url) {
+  let score = 0;
+  if (text.includes("/pricing") || text.includes("/plans")) score += 3;
+  if (text.includes("pricing") && !text.includes("/pricing")) score += 1;
+  if (text.includes("sign up") || text.includes("signup")) score += 2;
+  if (text.includes("free trial") || text.includes("start free")) score += 2;
+  if (text.includes("dashboard") && text.includes("login")) score += 2;
+  if (text.includes("per month") || text.includes("/mo")) score += 2;
+  if (files.some((f) => f.includes("pricing"))) score += 2;
+  return score;
+}
+
+function scoreApi(text, files, url) {
+  let score = 0;
+  const hostname = extractHostname(url);
+  if (
+    hostname &&
+    (hostname.startsWith("docs.") || hostname.startsWith("developer."))
+  )
+    score += 4;
+  if (text.includes("api reference") || text.includes("api docs")) score += 3;
+  if (text.includes("sdk") || text.includes("client library")) score += 2;
+  if (text.includes("openapi") || text.includes("swagger")) score += 3;
+  if (text.includes("endpoint") || text.includes("authentication")) score += 1;
+  if (text.includes("npm install") || text.includes("pip install")) score += 2;
+  if (files.some((f) => f.includes("openapi") || f.includes("swagger")))
+    score += 3;
+  if (files.some((f) => f.includes("sdk") || f.includes("client"))) score += 1;
+  return score;
+}
+
+function scoreContent(text, files, url) {
+  let score = 0;
+  if (text.includes("/blog") || text.includes("blog")) score += 2;
+  if ((text.match(/article/g) || []).length >= 3) score += 2;
+  if (text.includes("published") && text.includes("author")) score += 2;
+  if (text.includes("read more") || text.includes("continue reading"))
+    score += 2;
+  if (text.includes("subscribe") && text.includes("newsletter")) score += 1;
+  if (files.some((f) => f.includes("blog") || f.includes("posts"))) score += 3;
+  if (files.filter((f) => f.endsWith(".md")).length > 10) score += 1;
+  return score;
+}
+
+function scorePersonal(text, files, url) {
+  let score = 0;
+  const hostname = extractHostname(url);
+  if (hostname && isPersonalDomain(hostname)) score += 3;
+  if (text.includes("portfolio") || text.includes("my work")) score += 3;
+  if (
+    text.includes("about me") ||
+    text.includes("i am") ||
+    text.includes("i'm a")
+  )
+    score += 3;
+  if (text.includes("resume") || text.includes("cv")) score += 2;
+  if (text.includes("hire me") || text.includes("available for")) score += 2;
+  if (text.includes("linkedin.com/in/") || text.includes("github.com/"))
+    score += 1;
+  if (text.includes("@") && text.includes("contact")) score += 1;
+  return score;
+}
+
+function extractHostname(url) {
+  if (!url) return null;
+  try {
+    return new URL(url).hostname.replace("www.", "");
+  } catch {
+    return null;
+  }
+}
+
+function isPersonalDomain(hostname) {
+  const parts = hostname.split(".");
+  const name = parts[0];
+  const tld = parts.slice(1).join(".");
+  const personalTlds = ["com", "me", "io", "dev", "co", "net", "org"];
+  if (!personalTlds.includes(tld)) return false;
+  return /^[a-z]+[a-z]+$/.test(name) && name.length >= 6 && name.length <= 20;
+}
+
+export const SITE_TYPES = ["saas", "api", "content", "personal", "unknown"];