ax-audit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucio Duran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# ax-audit
+
+Audit websites for **AI Agent Experience (AX)** readiness. Lighthouse for AI Agents.
+
+```
+npx ax-audit https://example.com
+```
+
+## What it checks
+
+| Check | Description | Weight |
+|---|---|---|
+| **LLMs.txt** | `/llms.txt` presence and [spec](https://llmstxt.org) compliance | 15% |
+| **Robots.txt** | AI crawler configuration (GPTBot, ClaudeBot, etc.) | 15% |
+| **Structured Data** | JSON-LD on homepage (schema.org, @graph, entity types) | 15% |
+| **HTTP Headers** | Security headers + AI discovery Link headers + CORS | 15% |
+| **Agent Card** | `/.well-known/agent.json` [A2A protocol](https://a2a-protocol.org) | 10% |
+| **Security.txt** | `/.well-known/security.txt` [RFC 9116](https://www.rfc-editor.org/rfc/rfc9116) | 10% |
+| **Meta Tags** | AI meta tags (`ai:*`), `rel="alternate"`, `rel="me"` | 10% |
+| **OpenAPI** | `/.well-known/openapi.json` presence and validity | 10% |
+
+## Install
+
+```bash
+npm install -g ax-audit
+```
+
+Or run directly:
+
+```bash
+npx ax-audit https://your-site.com
+```
+
+## Usage
+
+```bash
+# Terminal output (default)
+ax-audit https://example.com
+
+# JSON output (for CI pipelines)
+ax-audit https://example.com --json
+
+# Run specific checks only
+ax-audit https://example.com --checks llms-txt,robots-txt,agent-json
+
+# Custom timeout (default: 10s)
+ax-audit https://example.com --timeout 15000
+```
+
+## Programmatic API
+
+```javascript
+import { audit } from 'ax-audit';
+
+const report = await audit({ url: 'https://example.com' });
+console.log(report.overallScore); // 0-100
+console.log(report.grade.label);  // 'Excellent' | 'Good' | 'Fair' | 'Poor'
+```
+
+## Scoring
+
+Each check returns a score from 0 to 100. The overall score is a weighted average.
+
+| Grade | Score | Exit Code |
+|---|---|---|
+| Excellent | 90-100 | 0 |
+| Good | 70-89 | 0 |
+| Fair | 50-69 | 1 |
+| Poor | 0-49 | 1 |
+
+Exit codes make it easy to gate CI/CD deployments on AX readiness.
+
+## CI Integration
+
+### GitHub Actions
+
+```yaml
+- name: AX Audit
+  run: npx ax-audit https://your-site.com --json > ax-report.json
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+
+## License
+
+MIT

package/bin/ax-audit.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+import { cli } from '../lib/cli.js';
+cli(process.argv);

package/lib/checks/agent-json.js

@@ -0,0 +1,77 @@
+import { AGENT_JSON_REQUIRED_FIELDS } from '../constants.js';
+
+export const meta = {
+  id: 'agent-json',
+  name: 'Agent Card (A2A)',
+  description: 'Checks /.well-known/agent.json A2A protocol compliance',
+  weight: 10,
+};
+
+export default async function check(ctx) {
+  const start = performance.now();
+  const findings = [];
+  let score = 100;
+
+  const res = await ctx.fetch(`${ctx.url}/.well-known/agent.json`);
+
+  if (!res.ok) {
+    findings.push({ status: 'fail', message: '/.well-known/agent.json not found', detail: `HTTP ${res.status || 'network error'}` });
+    return result(0, findings, start);
+  }
+
+  findings.push({ status: 'pass', message: '/.well-known/agent.json exists' });
+
+  // Valid JSON
+  let data;
+  try {
+    data = JSON.parse(res.body);
+  } catch {
+    findings.push({ status: 'fail', message: 'Invalid JSON' });
+    return result(10, findings, start);
+  }
+  findings.push({ status: 'pass', message: 'Valid JSON' });
+
+  // Required fields
+  for (const field of AGENT_JSON_REQUIRED_FIELDS) {
+    if (data[field] !== undefined && data[field] !== null) {
+      findings.push({ status: 'pass', message: `Required field "${field}" present` });
+    } else {
+      findings.push({ status: 'fail', message: `Required field "${field}" missing` });
+      score -= 15;
+    }
+  }
+
+  // Skills array
+  if (Array.isArray(data.skills) && data.skills.length > 0) {
+    findings.push({ status: 'pass', message: `${data.skills.length} skill(s) defined` });
+  } else if (Array.isArray(data.skills)) {
+    findings.push({ status: 'warn', message: 'Skills array is empty' });
+    score -= 10;
+  }
+
+  // Protocol version
+  if (data.protocolVersion) {
+    findings.push({ status: 'pass', message: `Protocol version: ${data.protocolVersion}` });
+  } else {
+    findings.push({ status: 'warn', message: 'No protocolVersion field' });
+    score -= 5;
+  }
+
+  // Optional valuable fields
+  const optionalFields = ['capabilities', 'authentication', 'documentationUrl'];
+  const presentOptional = optionalFields.filter(f => data[f] !== undefined);
+  if (presentOptional.length === optionalFields.length) {
+    findings.push({ status: 'pass', message: 'All optional fields present (capabilities, authentication, documentationUrl)' });
+  } else if (presentOptional.length > 0) {
+    findings.push({ status: 'pass', message: `${presentOptional.length}/${optionalFields.length} optional fields present` });
+  } else {
+    findings.push({ status: 'warn', message: 'No optional fields (capabilities, authentication, documentationUrl)' });
+    score -= 5;
+  }
+
+  return result(Math.max(0, score), findings, start);
+}
+
+function result(score, findings, start) {
+  return { id: meta.id, name: meta.name, description: meta.description, score, findings, duration: Math.round(performance.now() - start) };
+}

package/lib/checks/http-headers.js

@@ -0,0 +1,87 @@
+import { SECURITY_HEADERS } from '../constants.js';
+
+export const meta = {
+  id: 'http-headers',
+  name: 'HTTP Headers',
+  description: 'Checks security headers, AI discovery Link headers, and CORS',
+  weight: 15,
+};
+
+export default async function check(ctx) {
+  const start = performance.now();
+  const findings = [];
+  let score = 100;
+
+  const headers = ctx.headers;
+  if (!headers || Object.keys(headers).length === 0) {
+    findings.push({ status: 'fail', message: 'Could not fetch homepage headers' });
+    return result(0, findings, start);
+  }
+
+  // Security headers
+  let securityCount = 0;
+  for (const header of SECURITY_HEADERS) {
+    if (headers[header.name]) {
+      securityCount++;
+    } else if (header.critical) {
+      findings.push({ status: 'fail', message: `Missing critical header: ${header.label}` });
+      score -= 10;
+    }
+  }
+
+  if (securityCount === SECURITY_HEADERS.length) {
+    findings.push({ status: 'pass', message: `All ${SECURITY_HEADERS.length} security headers present` });
+  } else if (securityCount >= 4) {
+    findings.push({ status: 'pass', message: `${securityCount}/${SECURITY_HEADERS.length} security headers present` });
+  } else {
+    findings.push({ status: 'warn', message: `Only ${securityCount}/${SECURITY_HEADERS.length} security headers present` });
+    score -= 5;
+  }
+
+  // Link header for AI discovery
+  const linkHeader = headers['link'] || '';
+  const hasLlmsLink = /llms\.txt/i.test(linkHeader);
+  const hasAgentLink = /agent\.json/i.test(linkHeader);
+
+  if (hasLlmsLink && hasAgentLink) {
+    findings.push({ status: 'pass', message: 'Link header references both llms.txt and agent.json' });
+  } else if (hasLlmsLink) {
+    findings.push({ status: 'pass', message: 'Link header references llms.txt' });
+    findings.push({ status: 'warn', message: 'Link header does not reference agent.json' });
+    score -= 5;
+  } else if (hasAgentLink) {
+    findings.push({ status: 'pass', message: 'Link header references agent.json' });
+    findings.push({ status: 'warn', message: 'Link header does not reference llms.txt' });
+    score -= 5;
+  } else if (linkHeader) {
+    findings.push({ status: 'warn', message: 'Link header present but does not reference AI discovery files' });
+    score -= 15;
+  } else {
+    findings.push({ status: 'warn', message: 'No Link header for AI discovery (llms.txt, agent.json)' });
+    score -= 15;
+  }
+
+  // CORS on .well-known
+  const wellKnownRes = await ctx.fetch(`${ctx.url}/.well-known/agent.json`);
+  if (wellKnownRes.ok) {
+    const cors = wellKnownRes.headers['access-control-allow-origin'];
+    if (cors === '*' || cors) {
+      findings.push({ status: 'pass', message: 'CORS enabled on .well-known resources' });
+    } else {
+      findings.push({ status: 'warn', message: 'No CORS headers on .well-known resources' });
+      score -= 10;
+    }
+  }
+
+  // X-Robots-Tag on AI files
+  const llmsRes = await ctx.fetch(`${ctx.url}/llms.txt`);
+  if (llmsRes.ok && llmsRes.headers['x-robots-tag']?.includes('noindex')) {
+    findings.push({ status: 'pass', message: 'X-Robots-Tag: noindex on /llms.txt (prevents search indexing of raw text)' });
+  }
+
+  return result(Math.max(0, score), findings, start);
+}
+
+function result(score, findings, start) {
+  return { id: meta.id, name: meta.name, description: meta.description, score, findings, duration: Math.round(performance.now() - start) };
+}

package/lib/checks/index.js

@@ -0,0 +1,19 @@
+import llmsTxt, { meta as llmsTxtMeta } from './llms-txt.js';
+import robotsTxt, { meta as robotsTxtMeta } from './robots-txt.js';
+import agentJson, { meta as agentJsonMeta } from './agent-json.js';
+import securityTxt, { meta as securityTxtMeta } from './security-txt.js';
+import structuredData, { meta as structuredDataMeta } from './structured-data.js';
+import metaTags, { meta as metaTagsMeta } from './meta-tags.js';
+import openapi, { meta as openapiMeta } from './openapi.js';
+import httpHeaders, { meta as httpHeadersMeta } from './http-headers.js';
+
+export const checks = [
+  { run: llmsTxt, meta: llmsTxtMeta },
+  { run: robotsTxt, meta: robotsTxtMeta },
+  { run: agentJson, meta: agentJsonMeta },
+  { run: securityTxt, meta: securityTxtMeta },
+  { run: structuredData, meta: structuredDataMeta },
+  { run: metaTags, meta: metaTagsMeta },
+  { run: openapi, meta: openapiMeta },
+  { run: httpHeaders, meta: httpHeadersMeta },
+];

package/lib/checks/llms-txt.js

@@ -0,0 +1,80 @@
+export const meta = {
+  id: 'llms-txt',
+  name: 'LLMs.txt',
+  description: 'Checks /llms.txt presence and spec compliance',
+  weight: 15,
+};
+
+export default async function check(ctx) {
+  const start = performance.now();
+  const findings = [];
+  let score = 100;
+
+  const res = await ctx.fetch(`${ctx.url}/llms.txt`);
+
+  if (!res.ok) {
+    findings.push({ status: 'fail', message: '/llms.txt not found', detail: `HTTP ${res.status || 'network error'}` });
+    return result(0, findings, start);
+  }
+
+  findings.push({ status: 'pass', message: '/llms.txt exists' });
+  const text = res.body;
+
+  // H1 heading (first non-empty line should start with "# ")
+  const lines = text.split('\n').map(l => l.trim()).filter(Boolean);
+  if (!lines[0]?.startsWith('# ')) {
+    findings.push({ status: 'warn', message: 'Missing H1 heading (first line should start with "# ")' });
+    score -= 15;
+  } else {
+    findings.push({ status: 'pass', message: `H1 heading: "${lines[0].slice(2)}"` });
+  }
+
+  // Blockquote description ("> ")
+  const hasBlockquote = lines.some(l => l.startsWith('> '));
+  if (!hasBlockquote) {
+    findings.push({ status: 'warn', message: 'No blockquote description found ("> ...")' });
+    score -= 10;
+  } else {
+    findings.push({ status: 'pass', message: 'Blockquote description present' });
+  }
+
+  // Section headings ("## ")
+  const sections = lines.filter(l => l.startsWith('## '));
+  if (sections.length === 0) {
+    findings.push({ status: 'warn', message: 'No section headings found (## ...)' });
+    score -= 10;
+  } else {
+    findings.push({ status: 'pass', message: `${sections.length} section heading(s) found` });
+  }
+
+  // Markdown links [text](url)
+  const linkPattern = /\[([^\]]+)\]\((https?:\/\/[^)]+)\)/g;
+  const links = [...text.matchAll(linkPattern)];
+  if (links.length === 0) {
+    findings.push({ status: 'warn', message: 'No Markdown links found' });
+    score -= 10;
+  } else {
+    findings.push({ status: 'pass', message: `${links.length} link(s) found` });
+  }
+
+  // Content substance
+  if (text.length < 100) {
+    findings.push({ status: 'warn', message: 'Content appears minimal (< 100 characters)' });
+    score -= 10;
+  }
+
+  // Bonus: /llms-full.txt
+  const fullRes = await ctx.fetch(`${ctx.url}/llms-full.txt`);
+  if (fullRes.ok) {
+    findings.push({ status: 'pass', message: '/llms-full.txt also available (bonus)' });
+    score = Math.min(100, score + 10);
+  } else {
+    findings.push({ status: 'warn', message: '/llms-full.txt not found (optional but recommended)' });
+  }
+
+  return result(Math.max(0, score), findings, start);
+}
+
+function result(score, findings, start) {
+  return { id: meta.id, name: meta.name, description: meta.description, score, findings, duration: Math.round(performance.now() - start) };
+}

package/lib/checks/meta-tags.js

@@ -0,0 +1,87 @@
+export const meta = {
+  id: 'meta-tags',
+  name: 'Meta Tags',
+  description: 'Checks AI meta tags, rel="alternate", and rel="me" links',
+  weight: 10,
+};
+
+const AI_META_NAMES = ['ai:summary', 'ai:content_type', 'ai:author', 'ai:api', 'ai:agent_card'];
+
+export default async function check(ctx) {
+  const start = performance.now();
+  const findings = [];
+  let score = 100;
+
+  const html = ctx.html;
+  if (!html) {
+    findings.push({ status: 'fail', message: 'Could not fetch homepage HTML' });
+    return result(0, findings, start);
+  }
+
+  // AI meta tags (ai:*)
+  const foundAiMeta = AI_META_NAMES.filter(name => {
+    const pattern = new RegExp(`<meta\\s+[^>]*name=["']${escapeRegex(name)}["'][^>]*>`, 'i');
+    return pattern.test(html);
+  });
+
+  if (foundAiMeta.length >= 3) {
+    findings.push({ status: 'pass', message: `${foundAiMeta.length}/${AI_META_NAMES.length} AI meta tags found`, detail: foundAiMeta.join(', ') });
+  } else if (foundAiMeta.length > 0) {
+    findings.push({ status: 'warn', message: `${foundAiMeta.length}/${AI_META_NAMES.length} AI meta tags found`, detail: foundAiMeta.join(', ') });
+    score -= 15;
+  } else {
+    findings.push({ status: 'warn', message: 'No AI meta tags (ai:*) found' });
+    score -= 25;
+  }
+
+  // rel="alternate" to llms.txt
+  const hasLlmsAlternate = /rel=["']alternate["'][^>]*llms\.txt/i.test(html) ||
+    /llms\.txt[^>]*rel=["']alternate["']/i.test(html);
+  if (hasLlmsAlternate) {
+    findings.push({ status: 'pass', message: 'rel="alternate" link to llms.txt present' });
+  } else {
+    findings.push({ status: 'warn', message: 'No rel="alternate" link to llms.txt in HTML' });
+    score -= 15;
+  }
+
+  // rel="alternate" to agent.json
+  const hasAgentAlternate = /rel=["']alternate["'][^>]*agent\.json/i.test(html) ||
+    /agent\.json[^>]*rel=["']alternate["']/i.test(html);
+  if (hasAgentAlternate) {
+    findings.push({ status: 'pass', message: 'rel="alternate" link to agent.json present' });
+  } else {
+    findings.push({ status: 'warn', message: 'No rel="alternate" link to agent.json in HTML' });
+    score -= 10;
+  }
+
+  // rel="me" identity links
+  const relMePattern = /rel=["']me["']/gi;
+  const relMeCount = (html.match(relMePattern) || []).length;
+  if (relMeCount >= 3) {
+    findings.push({ status: 'pass', message: `${relMeCount} rel="me" identity link(s) found` });
+  } else if (relMeCount > 0) {
+    findings.push({ status: 'pass', message: `${relMeCount} rel="me" identity link(s) found` });
+  } else {
+    findings.push({ status: 'warn', message: 'No rel="me" identity links found' });
+    score -= 10;
+  }
+
+  // OpenGraph basics
+  const hasOg = /<meta\s+[^>]*property=["']og:/i.test(html);
+  if (hasOg) {
+    findings.push({ status: 'pass', message: 'OpenGraph meta tags present' });
+  } else {
+    findings.push({ status: 'warn', message: 'No OpenGraph meta tags found' });
+    score -= 10;
+  }
+
+  return result(Math.max(0, score), findings, start);
+}
+
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function result(score, findings, start) {
+  return { id: meta.id, name: meta.name, description: meta.description, score, findings, duration: Math.round(performance.now() - start) };
+}

package/lib/checks/openapi.js

@@ -0,0 +1,79 @@
+export const meta = {
+  id: 'openapi',
+  name: 'OpenAPI Spec',
+  description: 'Checks /.well-known/openapi.json presence and validity',
+  weight: 10,
+};
+
+export default async function check(ctx) {
+  const start = performance.now();
+  const findings = [];
+  let score = 100;
+
+  const res = await ctx.fetch(`${ctx.url}/.well-known/openapi.json`);
+
+  if (!res.ok) {
+    findings.push({ status: 'fail', message: '/.well-known/openapi.json not found', detail: `HTTP ${res.status || 'network error'}` });
+    return result(0, findings, start);
+  }
+
+  findings.push({ status: 'pass', message: '/.well-known/openapi.json exists' });
+
+  // Valid JSON
+  let data;
+  try {
+    data = JSON.parse(res.body);
+  } catch {
+    findings.push({ status: 'fail', message: 'Invalid JSON' });
+    return result(10, findings, start);
+  }
+  findings.push({ status: 'pass', message: 'Valid JSON' });
+
+  // OpenAPI version field
+  if (data.openapi) {
+    findings.push({ status: 'pass', message: `OpenAPI version: ${data.openapi}` });
+  } else if (data.swagger) {
+    findings.push({ status: 'warn', message: `Swagger version: ${data.swagger} (consider upgrading to OpenAPI 3.x)` });
+    score -= 10;
+  } else {
+    findings.push({ status: 'fail', message: 'No openapi or swagger version field' });
+    score -= 20;
+  }
+
+  // Info object
+  if (data.info && data.info.title) {
+    findings.push({ status: 'pass', message: `API title: "${data.info.title}"` });
+  } else {
+    findings.push({ status: 'warn', message: 'Missing info.title' });
+    score -= 10;
+  }
+
+  if (data.info?.description) {
+    findings.push({ status: 'pass', message: 'API description present' });
+  } else {
+    findings.push({ status: 'warn', message: 'Missing info.description' });
+    score -= 5;
+  }
+
+  // Paths
+  if (data.paths && Object.keys(data.paths).length > 0) {
+    findings.push({ status: 'pass', message: `${Object.keys(data.paths).length} path(s) documented` });
+  } else {
+    findings.push({ status: 'warn', message: 'No paths documented' });
+    score -= 15;
+  }
+
+  // Servers
+  if (Array.isArray(data.servers) && data.servers.length > 0) {
+    findings.push({ status: 'pass', message: `${data.servers.length} server(s) defined` });
+  } else {
+    findings.push({ status: 'warn', message: 'No servers defined' });
+    score -= 5;
+  }
+
+  return result(Math.max(0, score), findings, start);
+}
+
+function result(score, findings, start) {
+  return { id: meta.id, name: meta.name, description: meta.description, score, findings, duration: Math.round(performance.now() - start) };
+}

package/lib/checks/robots-txt.js

@@ -0,0 +1,91 @@
+import { ALL_AI_CRAWLERS, CORE_AI_CRAWLERS } from '../constants.js';
+
+export const meta = {
+  id: 'robots-txt',
+  name: 'Robots.txt',
+  description: 'Checks AI crawler configuration in robots.txt',
+  weight: 15,
+};
+
+export default async function check(ctx) {
+  const start = performance.now();
+  const findings = [];
+  let score = 100;
+
+  const res = await ctx.fetch(`${ctx.url}/robots.txt`);
+
+  if (!res.ok) {
+    findings.push({ status: 'fail', message: '/robots.txt not found' });
+    return result(0, findings, start);
+  }
+
+  findings.push({ status: 'pass', message: '/robots.txt exists' });
+  const text = res.body;
+  const configuredBots = parseUserAgents(text);
+
+  // Core AI crawlers
+  const coreConfigured = CORE_AI_CRAWLERS.filter(bot =>
+    configuredBots.some(b => b.name.toLowerCase() === bot.toLowerCase())
+  );
+  const coreMissing = CORE_AI_CRAWLERS.filter(bot =>
+    !configuredBots.some(b => b.name.toLowerCase() === bot.toLowerCase())
+  );
+
+  if (coreConfigured.length === CORE_AI_CRAWLERS.length) {
+    findings.push({ status: 'pass', message: `All ${CORE_AI_CRAWLERS.length} core AI crawlers explicitly configured` });
+  } else if (coreConfigured.length > 0) {
+    findings.push({ status: 'warn', message: `${coreConfigured.length}/${CORE_AI_CRAWLERS.length} core AI crawlers configured`, detail: `Missing: ${coreMissing.join(', ')}` });
+    score -= Math.round((coreMissing.length / CORE_AI_CRAWLERS.length) * 30);
+  } else {
+    findings.push({ status: 'fail', message: 'No core AI crawlers explicitly configured', detail: `Expected: ${CORE_AI_CRAWLERS.join(', ')}` });
+    score -= 40;
+  }
+
+  // Blocked AI crawlers
+  const blockedBots = configuredBots.filter(b =>
+    ALL_AI_CRAWLERS.some(ai => ai.toLowerCase() === b.name.toLowerCase()) && b.disallowed
+  );
+  if (blockedBots.length > 0) {
+    findings.push({ status: 'warn', message: `${blockedBots.length} AI crawler(s) explicitly blocked`, detail: blockedBots.map(b => b.name).join(', ') });
+    score -= blockedBots.length * 3;
+  }
+
+  // Sitemap directive
+  if (/^Sitemap:/mi.test(text)) {
+    findings.push({ status: 'pass', message: 'Sitemap directive present' });
+  } else {
+    findings.push({ status: 'warn', message: 'No Sitemap directive found' });
+    score -= 5;
+  }
+
+  // Total AI crawler coverage
+  const totalConfigured = ALL_AI_CRAWLERS.filter(bot =>
+    configuredBots.some(b => b.name.toLowerCase() === bot.toLowerCase())
+  );
+  findings.push({
+    status: totalConfigured.length >= 10 ? 'pass' : 'warn',
+    message: `${totalConfigured.length}/${ALL_AI_CRAWLERS.length} known AI crawlers have explicit rules`,
+  });
+
+  return result(Math.max(0, Math.min(100, score)), findings, start);
+}
+
+function parseUserAgents(text) {
+  const blocks = [];
+  let current = null;
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    const uaMatch = trimmed.match(/^User-agent:\s*(.+)/i);
+    if (uaMatch) {
+      current = { name: uaMatch[1].trim(), disallowed: false };
+      blocks.push(current);
+    } else if (current && /^Disallow:\s*\/\s*$/i.test(trimmed)) {
+      current.disallowed = true;
+    }
+  }
+  return blocks;
+}
+
+function result(score, findings, start) {
+  return { id: meta.id, name: meta.name, description: meta.description, score, findings, duration: Math.round(performance.now() - start) };
+}

package/lib/checks/security-txt.js

@@ -0,0 +1,67 @@
+import { SECURITY_TXT_REQUIRED_FIELDS } from '../constants.js';
+
+export const meta = {
+  id: 'security-txt',
+  name: 'Security.txt',
+  description: 'Checks /.well-known/security.txt RFC 9116 compliance',
+  weight: 10,
+};
+
+export default async function check(ctx) {
+  const start = performance.now();
+  const findings = [];
+  let score = 100;
+
+  const res = await ctx.fetch(`${ctx.url}/.well-known/security.txt`);
+
+  if (!res.ok) {
+    findings.push({ status: 'fail', message: '/.well-known/security.txt not found', detail: `HTTP ${res.status || 'network error'}` });
+    return result(0, findings, start);
+  }
+
+  findings.push({ status: 'pass', message: '/.well-known/security.txt exists' });
+  const text = res.body;
+
+  // Required fields
+  for (const field of SECURITY_TXT_REQUIRED_FIELDS) {
+    const regex = new RegExp(`^${field}:`, 'mi');
+    if (regex.test(text)) {
+      findings.push({ status: 'pass', message: `Required field "${field}" present` });
+    } else {
+      findings.push({ status: 'fail', message: `Required field "${field}" missing (RFC 9116)` });
+      score -= 25;
+    }
+  }
+
+  // Expires not in the past
+  const expiresMatch = text.match(/^Expires:\s*(.+)/mi);
+  if (expiresMatch) {
+    const expiresDate = new Date(expiresMatch[1].trim());
+    if (!isNaN(expiresDate.getTime())) {
+      if (expiresDate > new Date()) {
+        findings.push({ status: 'pass', message: `Expires date is in the future (${expiresDate.toISOString().split('T')[0]})` });
+      } else {
+        findings.push({ status: 'fail', message: 'Expires date is in the past — security.txt is expired' });
+        score -= 20;
+      }
+    }
+  }
+
+  // Optional fields
+  const optionalFields = ['Canonical', 'Preferred-Languages', 'Policy', 'Encryption', 'Hiring'];
+  const present = optionalFields.filter(f => new RegExp(`^${f}:`, 'mi').test(text));
+  if (present.length >= 3) {
+    findings.push({ status: 'pass', message: `${present.length}/${optionalFields.length} optional fields present` });
+  } else if (present.length > 0) {
+    findings.push({ status: 'pass', message: `${present.length}/${optionalFields.length} optional fields present` });
+  } else {
+    findings.push({ status: 'warn', message: 'No optional fields (Canonical, Preferred-Languages, Policy, etc.)' });
+    score -= 5;
+  }
+
+  return result(Math.max(0, score), findings, start);
+}
+
+function result(score, findings, start) {
+  return { id: meta.id, name: meta.name, description: meta.description, score, findings, duration: Math.round(performance.now() - start) };
+}

package/lib/checks/structured-data.js

@@ -0,0 +1,126 @@
+export const meta = {
+  id: 'structured-data',
+  name: 'Structured Data',
+  description: 'Checks JSON-LD structured data on homepage',
+  weight: 15,
+};
+
+export default async function check(ctx) {
+  const start = performance.now();
+  const findings = [];
+  let score = 100;
+
+  const html = ctx.html;
+  if (!html) {
+    findings.push({ status: 'fail', message: 'Could not fetch homepage HTML' });
+    return result(0, findings, start);
+  }
+
+  // Extract JSON-LD blocks
+  const jsonLdPattern = /<script\s+type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi;
+  const blocks = [...html.matchAll(jsonLdPattern)];
+
+  if (blocks.length === 0) {
+    findings.push({ status: 'fail', message: 'No JSON-LD structured data found' });
+    return result(0, findings, start);
+  }
+
+  findings.push({ status: 'pass', message: `${blocks.length} JSON-LD block(s) found` });
+
+  // Parse all blocks (unescape HTML entities first — common in SSR frameworks)
+  const parsed = [];
+  for (const block of blocks) {
+    const raw = unescapeHtml(block[1]);
+    try {
+      parsed.push(JSON.parse(raw));
+    } catch {
+      findings.push({ status: 'warn', message: 'Invalid JSON in a JSON-LD block' });
+      score -= 10;
+    }
+  }
+
+  if (parsed.length === 0) {
+    findings.push({ status: 'fail', message: 'All JSON-LD blocks have invalid JSON' });
+    return result(10, findings, start);
+  }
+
+  // Check for @context schema.org
+  const hasContext = parsed.some(d => {
+    const ctx = d['@context'];
+    return ctx && (ctx === 'https://schema.org' || ctx === 'https://schema.org/' || ctx === 'http://schema.org');
+  });
+  if (hasContext) {
+    findings.push({ status: 'pass', message: '@context references schema.org' });
+  } else {
+    findings.push({ status: 'warn', message: 'No @context referencing schema.org' });
+    score -= 15;
+  }
+
+  // Check for @graph (multi-entity pattern)
+  const hasGraph = parsed.some(d => Array.isArray(d['@graph']));
+  if (hasGraph) {
+    findings.push({ status: 'pass', message: '@graph array present (multi-entity structured data)' });
+  } else {
+    findings.push({ status: 'warn', message: 'No @graph array (single-entity only)' });
+    score -= 5;
+  }
+
+  // Collect all types
+  const allTypes = new Set();
+  for (const d of parsed) {
+    collectTypes(d, allTypes);
+  }
+
+  // Key types for AI agents
+  const importantTypes = ['Person', 'Organization', 'WebSite', 'WebPage', 'ProfilePage'];
+  const foundTypes = importantTypes.filter(t => allTypes.has(t));
+
+  if (foundTypes.length >= 2) {
+    findings.push({ status: 'pass', message: `Key types found: ${foundTypes.join(', ')}` });
+  } else if (foundTypes.length === 1) {
+    findings.push({ status: 'warn', message: `Only 1 key type found: ${foundTypes[0]}`, detail: `Consider adding: ${importantTypes.filter(t => !allTypes.has(t)).join(', ')}` });
+    score -= 10;
+  } else {
+    findings.push({ status: 'warn', message: 'No key entity types (Person, Organization, WebSite, etc.)' });
+    score -= 15;
+  }
+
+  // BreadcrumbList
+  if (allTypes.has('BreadcrumbList')) {
+    findings.push({ status: 'pass', message: 'BreadcrumbList present' });
+  } else {
+    findings.push({ status: 'warn', message: 'No BreadcrumbList found' });
+    score -= 5;
+  }
+
+  return result(Math.max(0, score), findings, start);
+}
+
+function unescapeHtml(str) {
+  return str
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&#x27;/g, "'")
+    .replace(/&#x2F;/g, '/');
+}
+
+function collectTypes(obj, types) {
+  if (!obj || typeof obj !== 'object') return;
+  if (obj['@type']) {
+    const t = Array.isArray(obj['@type']) ? obj['@type'] : [obj['@type']];
+    t.forEach(type => types.add(type));
+  }
+  if (Array.isArray(obj['@graph'])) {
+    obj['@graph'].forEach(item => collectTypes(item, types));
+  }
+  if (Array.isArray(obj)) {
+    obj.forEach(item => collectTypes(item, types));
+  }
+}
+
+function result(score, findings, start) {
+  return { id: meta.id, name: meta.name, description: meta.description, score, findings, duration: Math.round(performance.now() - start) };
+}

package/lib/cli.js

@@ -0,0 +1,50 @@
+import { Command } from 'commander';
+import { audit } from './orchestrator.js';
+import { report } from './reporter/index.js';
+import { VERSION } from './constants.js';
+
+export function cli(argv) {
+  const program = new Command();
+
+  program
+    .name('ax-audit')
+    .description('Audit websites for AI Agent Experience (AX) readiness. Lighthouse for AI Agents.')
+    .version(VERSION, '-v, --version')
+    .argument('<url>', 'URL to audit (e.g., https://example.com)')
+    .option('--json', 'Output results as JSON')
+    .option('--output <format>', 'Output format: terminal, json', 'terminal')
+    .option('--checks <list>', 'Comma-separated list of checks to run')
+    .option('--timeout <ms>', 'Per-request timeout in milliseconds', '10000')
+    .action(async (url, options) => {
+      // Validate URL
+      try {
+        new URL(url);
+      } catch {
+        console.error(`Error: Invalid URL "${url}". Provide a full URL like https://example.com`);
+        process.exit(1);
+      }
+
+      const format = options.json ? 'json' : options.output;
+      const checks = options.checks
+        ? options.checks.split(',').map(s => s.trim())
+        : undefined;
+
+      try {
+        const result = await audit({
+          url,
+          checks,
+          timeout: parseInt(options.timeout, 10),
+        });
+
+        report(result, format);
+
+        // Exit code: 0 for Good+, 1 for Fair/Poor
+        process.exit(result.overallScore >= 70 ? 0 : 1);
+      } catch (err) {
+        console.error(`Fatal: ${err.message}`);
+        process.exit(2);
+      }
+    });
+
+  program.parse(argv);
+}

package/lib/constants.js

@@ -0,0 +1,78 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
+
+export const VERSION = pkg.version;
+export const USER_AGENT = `ax-audit/${pkg.version} (https://github.com/lucioduran/ax-audit)`;
+
+// AI crawlers categorized by function
+export const AI_CRAWLERS = {
+  training: [
+    'GPTBot', 'ClaudeBot', 'Claude-Web', 'Anthropic-AI',
+    'Google-Extended', 'CCBot', 'Bytespider',
+    'Meta-ExternalAgent', 'Meta-ExternalFetcher',
+    'Cohere-AI', 'cohere-training-data-crawler',
+    'Applebot-Extended', 'Amazonbot', 'AI2Bot', 'AI2Bot-Dolma',
+    'DeepSeek-AI', 'PanguBot', 'Diffbot',
+  ],
+  search: [
+    'OAI-SearchBot', 'ChatGPT-User', 'Claude-SearchBot', 'Claude-User',
+    'PerplexityBot', 'Perplexity-User', 'DuckAssistBot', 'YouBot',
+    'Petalbot', 'Google-CloudVertexBot', 'Gemini',
+  ],
+  fetching: [
+    'FirecrawlAgent', 'Facebookbot',
+  ],
+};
+
+export const ALL_AI_CRAWLERS = [
+  ...AI_CRAWLERS.training,
+  ...AI_CRAWLERS.search,
+  ...AI_CRAWLERS.fetching,
+];
+
+// The most important AI crawlers to explicitly configure
+export const CORE_AI_CRAWLERS = [
+  'GPTBot', 'ClaudeBot', 'ChatGPT-User', 'Claude-SearchBot',
+  'Google-Extended', 'PerplexityBot',
+];
+
+// Scoring weights (must sum to 100)
+export const CHECK_WEIGHTS = {
+  'llms-txt': 15,
+  'robots-txt': 15,
+  'structured-data': 15,
+  'http-headers': 15,
+  'agent-json': 10,
+  'security-txt': 10,
+  'meta-tags': 10,
+  'openapi': 10,
+};
+
+// Grade thresholds
+export const GRADES = [
+  { min: 90, label: 'Excellent', color: 'green' },
+  { min: 70, label: 'Good', color: 'yellow' },
+  { min: 50, label: 'Fair', color: 'orange' },
+  { min: 0, label: 'Poor', color: 'red' },
+];
+
+// A2A Agent Card required fields
+export const AGENT_JSON_REQUIRED_FIELDS = ['name', 'description', 'url', 'skills'];
+
+// RFC 9116 required fields
+export const SECURITY_TXT_REQUIRED_FIELDS = ['Contact', 'Expires'];
+
+// Security headers to check
+export const SECURITY_HEADERS = [
+  { name: 'strict-transport-security', label: 'Strict-Transport-Security', critical: true },
+  { name: 'x-content-type-options', label: 'X-Content-Type-Options', critical: true },
+  { name: 'x-frame-options', label: 'X-Frame-Options', critical: false },
+  { name: 'x-xss-protection', label: 'X-XSS-Protection', critical: false },
+  { name: 'referrer-policy', label: 'Referrer-Policy', critical: false },
+  { name: 'permissions-policy', label: 'Permissions-Policy', critical: false },
+  { name: 'content-security-policy', label: 'Content-Security-Policy', critical: false },
+];

package/lib/fetcher.js

@@ -0,0 +1,64 @@
+import { USER_AGENT } from './constants.js';
+
+/**
+ * Creates a fetch wrapper with in-memory caching, timeout, and custom user-agent.
+ * @param {{ timeout?: number }} options
+ */
+export function createFetcher({ timeout = 10000 } = {}) {
+  const cache = new Map();
+
+  /**
+   * Fetch a URL with caching and timeout.
+   * Returns a normalized response object (never throws).
+   */
+  async function fetchUrl(url) {
+    if (cache.has(url)) return cache.get(url);
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+
+    try {
+      const response = await fetch(url, {
+        signal: controller.signal,
+        headers: {
+          'User-Agent': USER_AGENT,
+          'Accept': 'text/html, application/json, text/plain, */*',
+        },
+        redirect: 'follow',
+      });
+
+      const body = await response.text();
+
+      const headers = {};
+      response.headers.forEach((value, key) => {
+        headers[key.toLowerCase()] = value;
+      });
+
+      const result = {
+        status: response.status,
+        headers,
+        body,
+        ok: response.ok,
+        url: response.url,
+      };
+
+      cache.set(url, result);
+      return result;
+    } catch (err) {
+      const result = {
+        status: 0,
+        headers: {},
+        body: '',
+        ok: false,
+        url,
+        error: err.name === 'AbortError' ? 'Request timed out' : err.message,
+      };
+      cache.set(url, result);
+      return result;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  return { fetch: fetchUrl, fetchPage: fetchUrl };
+}

package/lib/orchestrator.js

@@ -0,0 +1,57 @@
+import { createFetcher } from './fetcher.js';
+import { checks as allChecks } from './checks/index.js';
+import { calculateOverallScore, getGrade } from './scorer.js';
+
+/**
+ * Run a full AX audit on a URL.
+ * @param {{ url: string, checks?: string[], timeout?: number }} options
+ */
+export async function audit(options) {
+  const startTime = performance.now();
+  const fetcher = createFetcher({ timeout: options.timeout || 10000 });
+
+  // Pre-fetch homepage (shared across checks that need HTML/headers)
+  const homepage = await fetcher.fetchPage(options.url);
+
+  const ctx = {
+    url: options.url.replace(/\/$/, ''),
+    fetch: fetcher.fetch,
+    html: homepage.body,
+    headers: homepage.headers,
+  };
+
+  // Filter checks if --checks flag was used
+  const checksToRun = options.checks
+    ? allChecks.filter(c => options.checks.includes(c.meta.id))
+    : allChecks;
+
+  // Run all checks in parallel (Promise.allSettled for resilience)
+  const settled = await Promise.allSettled(
+    checksToRun.map(c => c.run(ctx))
+  );
+
+  // Collect results, handle crashed checks gracefully
+  const results = settled.map((s, i) => {
+    if (s.status === 'fulfilled') return s.value;
+    return {
+      id: checksToRun[i].meta.id,
+      name: checksToRun[i].meta.name,
+      description: checksToRun[i].meta.description,
+      score: 0,
+      findings: [{ status: 'fail', message: `Check crashed: ${s.reason?.message || 'Unknown error'}` }],
+      duration: 0,
+    };
+  });
+
+  const overallScore = calculateOverallScore(results, checksToRun.map(c => c.meta));
+  const grade = getGrade(overallScore);
+
+  return {
+    url: options.url,
+    timestamp: new Date().toISOString(),
+    overallScore,
+    grade,
+    results,
+    duration: Math.round(performance.now() - startTime),
+  };
+}

package/lib/reporter/index.js

@@ -0,0 +1,14 @@
+import { reportTerminal } from './terminal.js';
+import { reportJson } from './json.js';
+
+export function report(auditReport, format) {
+  switch (format) {
+    case 'json':
+      reportJson(auditReport);
+      break;
+    case 'terminal':
+    default:
+      reportTerminal(auditReport);
+      break;
+  }
+}

package/lib/reporter/json.js

@@ -0,0 +1,3 @@
+export function reportJson(report) {
+  console.log(JSON.stringify(report, null, 2));
+}

package/lib/reporter/terminal.js

@@ -0,0 +1,49 @@
+import chalk from 'chalk';
+import { GRADES } from '../constants.js';
+
+const STATUS_ICONS = {
+  pass: chalk.green('  PASS '),
+  warn: chalk.yellow('  WARN '),
+  fail: chalk.red('  FAIL '),
+};
+
+function gradeColor(grade) {
+  if (grade.label === 'Excellent') return chalk.green;
+  if (grade.label === 'Good') return chalk.yellow;
+  if (grade.label === 'Fair') return chalk.hex('#FFA500');
+  return chalk.red;
+}
+
+export function reportTerminal(report) {
+  const grade = GRADES.find(g => report.overallScore >= g.min) || GRADES[GRADES.length - 1];
+  const colorFn = gradeColor(grade);
+
+  console.log();
+  console.log(chalk.bold('  AX Audit Report'));
+  console.log(chalk.dim(`  ${report.url}`));
+  console.log(chalk.dim(`  ${report.timestamp}  (${report.duration}ms)`));
+  console.log();
+
+  // Score bar
+  const barWidth = 40;
+  const filled = Math.round((report.overallScore / 100) * barWidth);
+  const empty = barWidth - filled;
+  console.log(`  ${colorFn('\u2588'.repeat(filled))}${chalk.gray('\u2591'.repeat(empty))}  ${colorFn.bold(report.overallScore + '/100')}  ${colorFn(grade.label)}`);
+  console.log();
+
+  // Individual checks
+  for (const check of report.results) {
+    console.log(chalk.bold(`  ${check.name}`) + chalk.dim(` (${check.score}/100)`));
+
+    for (const finding of check.findings) {
+      console.log(`${STATUS_ICONS[finding.status]} ${finding.message}`);
+      if (finding.detail) {
+        console.log(chalk.dim(`         ${finding.detail}`));
+      }
+    }
+    console.log();
+  }
+
+  console.log(chalk.dim('  Powered by ax-audit \u2014 Lighthouse for AI Agents'));
+  console.log();
+}

package/lib/scorer.js

@@ -0,0 +1,34 @@
+import { CHECK_WEIGHTS, GRADES } from './constants.js';
+
+/**
+ * Calculate the weighted overall score from individual check results.
+ * Re-normalizes if only a subset of checks was run.
+ */
+export function calculateOverallScore(results, metas) {
+  const weightMap = {};
+  let totalWeight = 0;
+
+  for (const m of metas) {
+    weightMap[m.id] = m.weight ?? CHECK_WEIGHTS[m.id] ?? 10;
+    totalWeight += weightMap[m.id];
+  }
+
+  let weightedSum = 0;
+  for (const r of results) {
+    const weight = weightMap[r.id] || 0;
+    weightedSum += (r.score / 100) * weight;
+  }
+
+  const overall = Math.round((weightedSum / totalWeight) * 100);
+  return Math.max(0, Math.min(100, overall));
+}
+
+/**
+ * Map a numeric score to a grade.
+ */
+export function getGrade(score) {
+  for (const grade of GRADES) {
+    if (score >= grade.min) return grade;
+  }
+  return GRADES[GRADES.length - 1];
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "ax-audit",
+  "version": "1.0.0",
+  "description": "Audit websites for AI Agent Experience (AX) readiness. Lighthouse for AI Agents.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Lucio Duran <email@lucioduran.com> (https://lucioduran.com)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lucioduran/ax-audit.git"
+  },
+  "homepage": "https://github.com/lucioduran/ax-audit#readme",
+  "bugs": {
+    "url": "https://github.com/lucioduran/ax-audit/issues"
+  },
+  "keywords": [
+    "ax",
+    "ai",
+    "agent-experience",
+    "audit",
+    "lighthouse",
+    "llms-txt",
+    "a2a",
+    "seo",
+    "cli",
+    "devtools"
+  ],
+  "bin": {
+    "ax-audit": "./bin/ax-audit.js"
+  },
+  "exports": {
+    ".": "./lib/orchestrator.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "start": "node bin/ax-audit.js",
+    "test": "node --test test/**/*.test.js",
+    "prepublishOnly": "npm test"
+  },
+  "dependencies": {
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0"
+  }
+}