readiness-audit 2.3.0 → 2.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +8 -0
- package/README.md +7 -5
- package/bin/readiness-audit.mjs +14 -4
- package/package.json +1 -1
- package/src/audit.mjs +13 -9
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,13 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 2.4.0 (2026-11-02)
|
|
4
|
+
|
|
5
|
+
From a review by the agents that run the scorecard daily for two projects. No scoring changes, and no new warnings or failures.
|
|
6
|
+
|
|
7
|
+
- **`--concurrency <n>` sets how many requests the audit sends to a site at once,** for a site that slows under parallel requests. Without it, nothing changes: 6 at a time for the discovery files, 4 for sitemaps and pages. The limit now also covers the sampled skill files and the MCP alias probes, which went out together before. At achurch.ai, a sweep of ten requests at a time slowed the site for minutes (2026-10-12); its own checks now send at most two. The library takes it as `audit(domain, { concurrency })`.
|
|
8
|
+
- **README:** documents `--concurrency` in the options and in "Safe to run", and says that a warning on a required check lowers the required score without changing the exit code (a site can show "required 14 of 15" with no FAIL line, because W6 warns). Two links to the research pointed at a placeholder; they now open [Who requests agent discovery files?](docs/research/who-reads-discovery-files.md).
|
|
9
|
+
- **Plans:** the status lines of the sample-by-template, proving-the-score and dependency-updates plans say 2.0.0 is published, and keep what's still open.
|
|
10
|
+
|
|
3
11
|
## 2.3.0 (2026-10-24)
|
|
4
12
|
|
|
5
13
|
From the sister project's agent, after it reviewed this one. No scoring changes.
|
package/README.md
CHANGED
|
@@ -42,7 +42,7 @@ The agent reads the page when it runs. To have it follow the text you reviewed,
|
|
|
42
42
|
|
|
43
43
|
What agents and crawlers actually ask a site for, from production logs:
|
|
44
44
|
|
|
45
|
-
- **The AI crawlers read robots.txt and the sitemap, not llms.txt.** In a week across 56 domains on Cloudflare, bots in Cloudflare's AI categories requested robots.txt 3,644 times and the sitemap 2,232 times, and llms.txt 49 times. llms.txt still matters to other readers: directories, tools, scripts and search bots requested it on every site ([research](
|
|
45
|
+
- **The AI crawlers read robots.txt and the sitemap, not llms.txt.** In a week across 56 domains on Cloudflare, bots in Cloudflare's AI categories requested robots.txt 3,644 times and the sitemap 2,232 times, and llms.txt 49 times. llms.txt still matters to other readers: directories, tools, scripts and search bots requested it on every site ([research](docs/research/who-reads-discovery-files.md)).
|
|
46
46
|
- **Directories crawl the well-known files; working agents call the API.** At animalhouse.ai, 4 of the 28 addresses that read llms.txt called the API ([§2](STANDARD.md#2-what-the-traffic-says)). Across the 16 sites with an API, 13% of llms.txt readers also got a successful API answer that week.
|
|
47
47
|
- **Bots ask for markdown.** 12,601 requests asked for markdown at ordinary page URLs that week, 92% of them from one search engine's crawler (Exa's).
|
|
48
48
|
- **A hosted MCP endpoint gets found within hours.** Seven MCP directory crawlers connected to animalhouse.ai's in its first two hours, and 14 browser visits reached it in the same two hours ([§2](STANDARD.md#2-what-the-traffic-says)).
|
|
@@ -51,7 +51,7 @@ What agents and crawlers actually ask a site for, from production logs:
|
|
|
51
51
|
## This repo holds
|
|
52
52
|
|
|
53
53
|
- **[STANDARD.md](STANDARD.md):** what to build, item by item, each with an ID, a level and the reason it's at that level. It covers discovery files, search (SEO, and the AI answer engines that GEO and AEO are about), the API, MCP servers, skills, engagement, measurement and tests.
|
|
54
|
-
- **[Who requests agent discovery files?](
|
|
54
|
+
- **[Who requests agent discovery files?](docs/research/who-reads-discovery-files.md):** the week across 56 domains, with charts, its queries and its classifier.
|
|
55
55
|
- **`readiness-audit`:** the scorecard. It checks a live site against everything the standard can verify from outside, about 30 checks in one pass, and lists what it can't see for you to review.
|
|
56
56
|
|
|
57
57
|
## Why this one
|
|
@@ -76,7 +76,7 @@ What agents and crawlers actually ask a site for, from production logs:
|
|
|
76
76
|
## Score a site
|
|
77
77
|
|
|
78
78
|
```
|
|
79
|
-
readiness-audit <domain> [--mcp /path] [--no-mcp] [--json] [--compare previous] [--base url]
|
|
79
|
+
readiness-audit <domain> [--mcp /path] [--no-mcp] [--json] [--compare previous] [--base url] [--concurrency n]
|
|
80
80
|
readiness-audit --matrix <domain> <domain> ... [--recorded results.json]
|
|
81
81
|
readiness-audit --logs <access-log> [--json]
|
|
82
82
|
```
|
|
@@ -88,17 +88,19 @@ readiness-audit --logs <access-log> [--json]
|
|
|
88
88
|
| `--json` | print the results as JSON |
|
|
89
89
|
| `--compare file` | list what changed since a previous run: a status page from `--matrix` or a saved `--json` report |
|
|
90
90
|
| `--base url` | score a local or preview build as the domain before you deploy (`--base http://localhost:3000`); DNS and host redirects are skipped |
|
|
91
|
+
| `--concurrency n` | send at most n requests to the site at once (default 6 for the discovery files, 4 for sitemaps and pages). Lower it for a site that slows under parallel requests; the checks are the same |
|
|
91
92
|
| `--matrix` | score several sites and print a markdown status page |
|
|
92
93
|
| `--recorded file` | with `--matrix`, add your recorded T5 and T6 results (format: [examples/recorded.json](examples/recorded.json)) |
|
|
93
94
|
| `--logs file` | count requests for the discovery files in an exported access log (combined log format, or JSON lines from Cloudflare, Vercel or Railway), by client family. It prints counts, never addresses |
|
|
94
95
|
|
|
95
|
-
It prints a pass, warning or failure for each check, with the reason, and exits with code 1 when a required check fails, so it can gate a deploy. The API checks run when `/openapi.json` or `/api` answers, or when the site declares an API (a `service-desc` link, an API catalog, an API link in llms.txt). A declared API that doesn't answer fails them. A site with neither skips them, the way a site with no hosted MCP endpoint skips the MCP checks.
|
|
96
|
+
It prints a pass, warning or failure for each check, with the reason, and exits with code 1 when a required check fails, so it can gate a deploy. A warning on a required check, such as W6's heading jumps, lowers the required score ("required 14 of 15") without changing the exit code; only a failure does. The API checks run when `/openapi.json` or `/api` answers, or when the site declares an API (a `service-desc` link, an API catalog, an API link in llms.txt). A declared API that doesn't answer fails them. A site with neither skips them, the way a site with no hosted MCP endpoint skips the MCP checks.
|
|
96
97
|
|
|
97
98
|
To check fixes before they ship, score a local build: `npx readiness-audit@2 example.com --base http://localhost:3000`. The site's own URLs (from its sitemap, llms.txt, skills and catalog) are requested from the base and reported under the domain. From a clone, run `node bin/readiness-audit.mjs example.com`.
|
|
98
99
|
|
|
99
100
|
### Safe to run
|
|
100
101
|
|
|
101
|
-
- **It only reads:** GET requests, plus a few POSTs that create nothing (an MCP `initialize`, `server/discover` and `tools/list`, and an empty POST to `/`),
|
|
102
|
+
- **It only reads:** GET requests, plus a few POSTs that create nothing (an MCP `initialize`, `server/discover` and `tools/list`, and an empty POST to `/`), at most six at a time. With `--matrix`, each site gets its own six.
|
|
103
|
+
- **It can go slower.** A site that slows under parallel requests can be audited with `--concurrency 2`, or `--concurrency 1` for one request at a time. The same checks run, and take longer.
|
|
102
104
|
- **It stays on public addresses.** It won't follow a link the site supplies (in its sitemap, share images, skills, catalog or DNS record) to a private or local address, at any redirect. `--base` may be local, because you chose it.
|
|
103
105
|
- **A hostile site can't reach a decoder bug.** It asks for gzip and decodes it itself; a body in an encoding it didn't ask for, such as Brotli, is reported rather than read, and every body is capped at 16 MB.
|
|
104
106
|
- **Run it only against sites you run,** or with the owner's permission. [SECURITY.md](SECURITY.md) has the details and how to report a problem.
|
package/bin/readiness-audit.mjs
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
// readiness-audit: score a live site against the Agent and Search Readiness Standard.
|
|
3
3
|
//
|
|
4
|
-
// readiness-audit <domain> [--mcp /path] [--no-mcp] [--json] [--compare previous] [--base url]
|
|
4
|
+
// readiness-audit <domain> [--mcp /path] [--no-mcp] [--json] [--compare previous] [--base url] [--concurrency n]
|
|
5
5
|
// readiness-audit --matrix <domain> <domain> ... [--recorded results.json] (a markdown status page)
|
|
6
6
|
// readiness-audit --logs <access-log> [--json] (who requests the discovery files)
|
|
7
7
|
//
|
|
@@ -31,9 +31,15 @@ const recordedPath = valueOf('--recorded');
|
|
|
31
31
|
const comparePath = valueOf('--compare');
|
|
32
32
|
const base = valueOf('--base');
|
|
33
33
|
const logsPath = valueOf('--logs');
|
|
34
|
-
const
|
|
34
|
+
const concurrencyOpt = valueOf('--concurrency');
|
|
35
|
+
const domains = args.filter((a, i) => !a.startsWith('-') && !['--mcp', '--recorded', '--compare', '--base', '--logs', '--concurrency'].includes(args[i - 1]))
|
|
35
36
|
.map((d) => d.replace(/^https?:\/\//, '').replace(/\/.*$/, ''));
|
|
36
|
-
const opts = { mcpPath: flag('--no-mcp') ? null : (mcpOpt ?? '/mcp'), base: base ?? null };
|
|
37
|
+
const opts = { mcpPath: flag('--no-mcp') ? null : (mcpOpt ?? '/mcp'), base: base ?? null, concurrency: null };
|
|
38
|
+
if (flag('--concurrency')) {
|
|
39
|
+
const n = Number(concurrencyOpt);
|
|
40
|
+
if (!Number.isInteger(n) || n < 1) { console.error(`--concurrency needs a whole number of 1 or more, like --concurrency 2 (got ${concurrencyOpt})`); process.exit(2); }
|
|
41
|
+
opts.concurrency = n;
|
|
42
|
+
}
|
|
37
43
|
if (base) {
|
|
38
44
|
let u;
|
|
39
45
|
try { u = new URL(base); } catch { u = null; }
|
|
@@ -54,7 +60,7 @@ if (!domains.length || flag('--help') || flag('-h')) {
|
|
|
54
60
|
console.error(`readiness-audit ${VERSION}
|
|
55
61
|
|
|
56
62
|
Usage:
|
|
57
|
-
readiness-audit <domain> [--mcp /path] [--no-mcp] [--json] [--compare previous] [--base url]
|
|
63
|
+
readiness-audit <domain> [--mcp /path] [--no-mcp] [--json] [--compare previous] [--base url] [--concurrency n]
|
|
58
64
|
readiness-audit --matrix <domain> <domain> ... [--recorded results.json]
|
|
59
65
|
readiness-audit --logs <access-log> [--json]
|
|
60
66
|
|
|
@@ -69,6 +75,10 @@ Options:
|
|
|
69
75
|
--base url score a local or preview build as the domain, before you
|
|
70
76
|
deploy (http://localhost:3000); DNS and host redirects are
|
|
71
77
|
skipped
|
|
78
|
+
--concurrency n
|
|
79
|
+
at most n requests to the site at once (default 6 for
|
|
80
|
+
the discovery files, 4 for sitemaps and pages); lower it
|
|
81
|
+
for a site that slows under parallel requests
|
|
72
82
|
--logs f count requests for the discovery files in an exported access
|
|
73
83
|
log (combined log format or JSON lines), by client family;
|
|
74
84
|
prints counts, never addresses
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "readiness-audit",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.4.0",
|
|
4
4
|
"description": "Score any site's readiness for AI agents and search (GEO, AEO, AI SEO): llms.txt, robots.txt AI crawler rules, structured data, link previews, OpenAPI, MCP, agent skills and A2A. Read-only CLI, no account.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
package/src/audit.mjs
CHANGED
|
@@ -11,7 +11,7 @@ import { isIP } from 'node:net';
|
|
|
11
11
|
import { request } from './http.mjs';
|
|
12
12
|
import { SKILL_NAME, sampleSkillEntries, skillNameProblem, cdnCacheNote, repeatsSummary, hasVariantDescription, spread, samplePages, sharedCardText, API_LINK, MCP_LINK, linkRels, apiPresence, DISCOVERY_FILES, AI_BOTS, missingSections, richResultPages, list, norm, pathDepth, decodeText, headings, headingSkips, sitemapEntries, llmsLinks, baseMapper, formatRecorded } from './helpers.mjs';
|
|
13
13
|
|
|
14
|
-
export const VERSION = '2.
|
|
14
|
+
export const VERSION = '2.4.0';
|
|
15
15
|
export const REPO = 'https://github.com/geeks-accelerator/agent-and-search-readiness';
|
|
16
16
|
const UA = `readiness-audit/${VERSION} (+${REPO})`;
|
|
17
17
|
const AID_PROTOCOLS = ['mcp', 'a2a', 'openapi', 'grpc', 'graphql', 'websocket', 'local', 'zeroconf', 'ucp'];
|
|
@@ -105,8 +105,12 @@ export function makeGuard(domain) {
|
|
|
105
105
|
return { siteHosts, isSafe };
|
|
106
106
|
}
|
|
107
107
|
|
|
108
|
-
export async function audit(domain, { mcpPath = '/mcp', base = null } = {}) {
|
|
108
|
+
export async function audit(domain, { mcpPath = '/mcp', base = null, concurrency = null } = {}) {
|
|
109
109
|
const BASE = `https://${domain}`;
|
|
110
|
+
// Requests in flight to the site at once. By default, 6 for the discovery files and 4 for
|
|
111
|
+
// sitemaps and pages; `concurrency` sets one limit for all of them, for a site that slows
|
|
112
|
+
// under parallel requests.
|
|
113
|
+
const limit = (byDefault) => concurrency ?? byDefault;
|
|
110
114
|
const rand = Math.random().toString(36).slice(2, 10);
|
|
111
115
|
|
|
112
116
|
const { siteHosts, isSafe } = makeGuard(domain);
|
|
@@ -178,7 +182,7 @@ export async function audit(domain, { mcpPath = '/mcp', base = null } = {}) {
|
|
|
178
182
|
() => get('/', { method: 'POST', redirect: 'manual' }),
|
|
179
183
|
() => get(D.legacyCard),
|
|
180
184
|
() => get(D.wkCard),
|
|
181
|
-
], 6, (job) => job());
|
|
185
|
+
], limit(6), (job) => job());
|
|
182
186
|
const catalogEntries = [...(json(ard)?.entries ?? []), ...(json(aiCatalog)?.entries ?? [])];
|
|
183
187
|
const rels = linkRels(home.headers.get('link'));
|
|
184
188
|
const api = apiPresence({ openapiSpec: json(openapi), apiIndexJson: ok(apiIndex) && isJson(apiIndex), rels, catalogJson: ok(apiCatalog) ? json(apiCatalog) : null, llmsText: ok(llms) ? llms.text : '' });
|
|
@@ -231,7 +235,7 @@ export async function audit(domain, { mcpPath = '/mcp', base = null } = {}) {
|
|
|
231
235
|
// ---- The sitemap, read once for D2 and the W checks: an index is expanded to its pages ----
|
|
232
236
|
const sitemapIndex = /<sitemapindex/.test(sitemap.text);
|
|
233
237
|
const sitemapLists = sitemapIndex
|
|
234
|
-
? await mapLimit(sitemapEntries(sitemap.text).slice(0, 10), 4, async (e) => sitemapEntries((await get(e.loc)).text))
|
|
238
|
+
? await mapLimit(sitemapEntries(sitemap.text).slice(0, 10), limit(4), async (e) => sitemapEntries((await get(e.loc)).text))
|
|
235
239
|
: [sitemapEntries(sitemap.text)];
|
|
236
240
|
const seenLocs = new Set();
|
|
237
241
|
const entries = sitemapLists.flat().filter((e) => {
|
|
@@ -258,7 +262,7 @@ export async function audit(domain, { mcpPath = '/mcp', base = null } = {}) {
|
|
|
258
262
|
// Agents follow the links in llms.txt, so a sample of the site's own links must answer 200.
|
|
259
263
|
const links = ok(llms) ? llmsLinks(llms.text, `${BASE}/llms.txt`, siteHosts) : [];
|
|
260
264
|
const sample = spread(links, 10);
|
|
261
|
-
const answers = await mapLimit(sample, 4, async (u) => ({ u, r: await get(u) }));
|
|
265
|
+
const answers = await mapLimit(sample, limit(4), async (u) => ({ u, r: await get(u) }));
|
|
262
266
|
llmsAnswers = answers;
|
|
263
267
|
// Missing pages, server errors and no answer are broken. A 401, 403 or 405 is an endpoint that
|
|
264
268
|
// exists but wants a key or another method, which is fine to list.
|
|
@@ -481,14 +485,14 @@ export async function audit(domain, { mcpPath = '/mcp', base = null } = {}) {
|
|
|
481
485
|
} else {
|
|
482
486
|
// Entry URLs may be relative, and resolve against the index (RFC 3986).
|
|
483
487
|
const indexUrl = `${BASE}/.well-known/agent-skills/index.json`;
|
|
484
|
-
const files = await
|
|
488
|
+
const files = await mapLimit(sample, limit(5), async (e) => {
|
|
485
489
|
const url = new URL(e.url, indexUrl).href;
|
|
486
490
|
const r = await get(url);
|
|
487
491
|
const fm = r.text.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1] ?? '';
|
|
488
492
|
const field = (k) => fm.match(new RegExp(`^${k}:\\s*(?:"([^"]*)"|'([^']*)'|(.*))$`, 'm'))?.slice(1).find((v) => v !== undefined)?.trim() ?? '';
|
|
489
493
|
const label = typeof e.name === 'string' && e.name ? e.name : url;
|
|
490
494
|
return { url, status: r.status, text: r.text, name: field('name'), description: field('description'), entryName: e.name, label, lines: r.text.split('\n').length };
|
|
491
|
-
})
|
|
495
|
+
});
|
|
492
496
|
const unreachable = files.filter((f) => f.status !== 200).map((f) => `${f.label} (${f.status})`);
|
|
493
497
|
const read = files.filter((f) => f.status === 200);
|
|
494
498
|
const badName = read.map((f) => [f, skillNameProblem(f)]).filter(([, why]) => why).map(([f, why]) => `${f.label} (${why})`);
|
|
@@ -553,7 +557,7 @@ export async function audit(domain, { mcpPath = '/mcp', base = null } = {}) {
|
|
|
553
557
|
variants.push(['(none)', await get(mcpPath, { method: 'POST', headers: { 'content-type': 'application/json', accept: null }, body: INIT })]);
|
|
554
558
|
const discover = await modern('server/discover', 2);
|
|
555
559
|
const browser = await get(mcpPath, { headers: { accept: 'text/html' }, redirect: 'manual' });
|
|
556
|
-
const aliases = await
|
|
560
|
+
const aliases = await mapLimit(['/sse', '/api/mcp'], limit(2), (p) => get(p, { method: 'POST', redirect: 'manual', headers: { 'content-type': 'application/json' }, body: INIT }));
|
|
557
561
|
const problems = [];
|
|
558
562
|
const refused = variants.filter(([, r]) => r.status !== 200).map(([a, r]) => `${a} → ${r.status}`);
|
|
559
563
|
if (refused.length) problems.push(`2025-era initialize refused for Accept ${refused.join(', ')}`);
|
|
@@ -651,7 +655,7 @@ export async function audit(domain, { mcpPath = '/mcp', base = null } = {}) {
|
|
|
651
655
|
ldBroken: ld.filter((x) => x === null).length, types,
|
|
652
656
|
};
|
|
653
657
|
};
|
|
654
|
-
const pages = await mapLimit(pick, 4, async (u) => parsePage(u, await get(u, { headers: { accept: 'text/html' } })));
|
|
658
|
+
const pages = await mapLimit(pick, limit(4), async (u) => parsePage(u, await get(u, { headers: { accept: 'text/html' } })));
|
|
655
659
|
// A body the audit refused (an encoding it doesn't decode) is reported once, in W3, not as missing tags everywhere.
|
|
656
660
|
const ok200 = pages.filter((p) => p.status === 200 && p.html && !p.error);
|
|
657
661
|
if (ok200.length) { const sizes = ok200.map((p) => p.bytes).sort((a, b) => a - b); htmlKb = Math.round(sizes[Math.floor(sizes.length / 2)] / 1024); }
|