aeo-ready 1.1.0 → 1.3.0

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 "";
-}

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

@@ -1,64 +0,0 @@
-import { existsSync, readFileSync } from "fs";
-import { join } from "path";
-
-const AI_CRAWLERS = [
-  "GPTBot",
-  "OAI-SearchBot",
-  "ClaudeBot",
-  "Claude-User",
-  "Claude-SearchBot",
-  "Google-Extended",
-  "PerplexityBot",
-  "Meta-ExternalAgent",
-  "CCBot",
-];
-
-export function generateRobotsTxt(check, scanResult, dir) {
-  const filePath = join(dir, "robots.txt");
-  const exists = existsSync(filePath);
-
-  if (exists) {
-    return {
-      file: "robots.txt",
-      description: "Add missing AI crawler rules",
-      draft: false,
-      merge: mergeRobotsTxt,
-      content: generateCrawlerBlock(),
-    };
-  }
-
-  return {
-    file: "robots.txt",
-    description: "Allow all AI crawlers for maximum agent discoverability",
-    draft: false,
-    content: generateFullRobotsTxt(),
-  };
-}
-
-function mergeRobotsTxt(existing, newContent) {
-  const presentBots = AI_CRAWLERS.filter((bot) => existing.includes(bot));
-  const missingBots = AI_CRAWLERS.filter((bot) => !existing.includes(bot));
-
-  if (missingBots.length === 0) return existing;
-
-  const additions = missingBots
-    .map((bot) => `User-agent: ${bot}\nAllow: /\n`)
-    .join("\n");
-
-  return (
-    existing.trimEnd() + "\n\n# AI crawlers (added by agent-web)\n" + additions
-  );
-}
-
-function generateCrawlerBlock() {
-  return AI_CRAWLERS.map((bot) => `User-agent: ${bot}\nAllow: /\n`).join("\n");
-}
-
-function generateFullRobotsTxt() {
-  let content = "User-agent: *\nAllow: /\n\n";
-  content += "# AI crawlers — explicit allow for agent discoverability\n";
-  content += AI_CRAWLERS.map((bot) => `User-agent: ${bot}\nAllow: /\n`).join(
-    "\n",
-  );
-  return content;
-}

package/src/fix/index.js

@@ -1,177 +0,0 @@
-import chalk from "chalk";
-import { writeFileSync, existsSync, readFileSync, mkdirSync } from "fs";
-import { join, dirname } from "path";
-import { generateRobotsTxt } from "./generators/robots-txt.js";
-import { generateAgentsJson } from "./generators/agents-json.js";
-import { generateLlmsTxt } from "./generators/llms-txt.js";
-import { generateAgentsMd } from "./generators/agents-md.js";
-import { generateDashboard } from "../dashboard/generate.js";
-
-export async function fix(beforeResult, dir, rescanFn) {
-  const failedChecks = getAllFailedChecks(beforeResult);
-  const applied = [];
-  const manual = [];
-
-  for (const check of failedChecks) {
-    const result = await generateFix(check, beforeResult, dir);
-    if (result) {
-      if (result.draft) {
-        manual.push(result);
-      } else {
-        writeFix(result, dir);
-        applied.push(result);
-      }
-    } else {
-      manual.push({ description: check.fix, name: check.name });
-    }
-  }
-
-  const afterResult = rescanFn ? await rescanFn() : null;
-
-  printSummary(beforeResult, afterResult, applied, manual);
-
-  if (afterResult && dir) {
-    const dashPath = await generateDashboard(afterResult, dir, {
-      beforeResult,
-    });
-    console.log(chalk.dim(`  Dashboard: ${dashPath}\n`));
-  }
-
-  return { applied, manual, afterResult };
-}
-
-function printSummary(before, after, applied, manual) {
-  const beforeScore = before.score;
-  const afterScore = after ? after.score : null;
-
-  console.log(chalk.bold("\n  aeo-ready --fix\n"));
-
-  if (afterScore !== null) {
-    const delta = afterScore - beforeScore;
-    const deltaStr =
-      delta > 0
-        ? chalk.green(` (+${delta})`)
-        : delta < 0
-          ? chalk.red(` (${delta})`)
-          : "";
-    const beforeGrade = gradeColor(before.grade)(`${beforeScore}`);
-    const afterGrade = gradeColor(after.grade)(`${afterScore}`);
-    console.log(
-      `  ${beforeGrade}${chalk.dim("/100")} ${chalk.dim("->")} ${afterGrade}${chalk.dim("/100")}${deltaStr}\n`,
-    );
-
-    const bA = before.agentReadiness.score;
-    const bV = before.aiVisibility.score;
-    const aA = after.agentReadiness.score;
-    const aV = after.aiVisibility.score;
-    const dA = aA - bA;
-    const dV = aV - bV;
-    const fmtDelta = (d) =>
-      d > 0 ? chalk.green(`+${d}`) : d < 0 ? chalk.red(`${d}`) : chalk.dim("—");
-
-    console.log(
-      chalk.dim("  Agent Readiness  ") +
-        `${bA} -> ${aA} ${fmtDelta(dA)}` +
-        chalk.dim("  can agents find, read, and use your site?"),
-    );
-    console.log(
-      chalk.dim("  AI Visibility    ") +
-        `${bV} -> ${aV} ${fmtDelta(dV)}` +
-        chalk.dim("  how accurately do AI engines describe you?"),
-    );
-
-    if (bA < 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."));
-    }
-  } else {
-    console.log(
-      `  ${chalk.dim("Score:")} ${beforeScore}/100 (${before.grade})\n`,
-    );
-  }
-
-  if (applied.length > 0) {
-    console.log(chalk.bold("\n  We fixed:"));
-    for (const fix of applied) {
-      console.log(
-        chalk.green(`    + ${fix.file}`) + chalk.dim(` — ${fix.description}`),
-      );
-    }
-  }
-
-  const humanTasks = manual.filter((m) => m.description);
-  if (humanTasks.length > 0) {
-    console.log(chalk.bold("\n  You still need to:"));
-    for (const task of humanTasks.slice(0, 6)) {
-      console.log(chalk.dim(`    - ${task.description}`));
-    }
-    if (humanTasks.length > 6) {
-      console.log(chalk.dim(`    ... and ${humanTasks.length - 6} more`));
-    }
-  }
-
-  console.log("");
-}
-
-function writeFix(fix, dir) {
-  const filePath = join(dir, fix.file);
-  const fileDir = dirname(filePath);
-  if (!existsSync(fileDir)) mkdirSync(fileDir, { recursive: true });
-
-  if (existsSync(filePath) && fix.merge) {
-    const existing = readFileSync(filePath, "utf8");
-    const merged = fix.merge(existing, fix.content);
-    writeFileSync(filePath, merged);
-  } else {
-    writeFileSync(filePath, fix.content);
-  }
-}
-
-async function generateFix(check, scanResult, dir) {
-  switch (check.name) {
-    case "robots.txt AI crawlers":
-      return generateRobotsTxt(check, scanResult, dir);
-    case "agents.json manifest":
-      return generateAgentsJson(check, scanResult, dir);
-    case "AGENTS.md / CLAUDE.md":
-      return generateAgentsMd(check, scanResult, dir);
-    case "llms.txt":
-      return generateLlmsTxt(check, scanResult, dir);
-    default:
-      return null;
-  }
-}
-
-function getAllFailedChecks(scanResult) {
-  const checks = [];
-  for (const scorecard of [
-    scanResult.agentReadiness,
-    scanResult.aiVisibility,
-  ]) {
-    for (const cat of Object.values(scorecard.categories)) {
-      for (const check of cat.checks) {
-        if (!check.passed) {
-          checks.push(check);
-        }
-      }
-    }
-  }
-  return checks;
-}
-
-function gradeColor(grade) {
-  switch (grade) {
-    case "A":
-      return chalk.green;
-    case "B":
-      return chalk.cyan;
-    case "C":
-      return chalk.yellow;
-    default:
-      return chalk.red;
-  }
-}

package/src/track/index.js

@@ -1,167 +0,0 @@
-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

@@ -1,99 +0,0 @@
-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"];

package/src/utils/tokens.js

@@ -1,18 +0,0 @@
-export function estimateTokens(text) {
-  if (!text) return 0;
-  return Math.ceil(text.length / 4);
-}
-
-export const TOKEN_BUDGETS = {
-  quickstart: 15000,
-  apiRef: 25000,
-  guide: 20000,
-  llmsTxt: 5000,
-};
-
-export function checkTokenBudget(text, type) {
-  const tokens = estimateTokens(text);
-  const budget = TOKEN_BUDGETS[type];
-  if (!budget) return { tokens, withinBudget: true, budget: null };
-  return { tokens, withinBudget: tokens <= budget, budget };
-}