mirror of
https://github.com/kuhyx/utils.git
synced 2026-11-10 20:27:15 +01:00
Krzysztof kuhy Rudnicki
a0fb279b1b
New agent_ready/ package (dist and live-url modes, 100% branch coverage) checks robots, sitemap, llms.txt, ai-catalog, 404, no-JS text, markdown mirrors and JSON-LD. repo_contract gains web-repo detection and installs the agent-ready pre-commit hook, CI workflow and check_agent_ready.sh shim; scripts/check_agent_ready.sh is the shared entry point. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NBScELfMUiieK9ManFbS3Y
94 lines
2.9 KiB
Markdown
94 lines
2.9 KiB
Markdown
# agent_ready
|
|
|
|
This tool checks kuhy's websites against [AgentReady](https://agentready.org)
|
|
v2.0. It runs every find and read item, and the act items when you pass `--act`.
|
|
It is Python 3 standard library only, with no dependencies.
|
|
`DOCS-spec-notes.md` maps each `AR-*` ID to the check that tests it.
|
|
|
|
## Usage
|
|
|
|
```sh
|
|
~/src/utils/agent_ready/check.sh dist <build-dir> [--act] [--min-text N] [--max-pages N]
|
|
~/src/utils/agent_ready/check.sh url <base-url> [--act] [--min-text N] [--max-pages N] [--timeout S] [--budget S]
|
|
```
|
|
|
|
The output is one line per check:
|
|
|
|
```text
|
|
PASS AR-FIND-03 sitemap lists 12 pages
|
|
FAIL AR-READ-02 soft 404, unknown paths must return 404: /agentready-probe-1a2b -> HTTP 200
|
|
SKIP AR-READ-11 pricing page: n/a for sites without paid plans
|
|
```
|
|
|
|
| exit | meaning |
|
|
|---|---|
|
|
| 0 | every check passed (SKIPs do not fail) |
|
|
| 1 | at least one FAIL, at any strength: MUST, SHOULD or MAY |
|
|
| 2 | usage error (bad arguments, missing directory, not an http(s) URL) |
|
|
| 3 | network undeterminable: the homepage was unreachable, or a fetch timed out or hit the 45 s budget, and nothing failed |
|
|
|
|
## Pre-commit and CI (dist mode)
|
|
|
|
Point the checker at the build output after the build step. Dist mode checks
|
|
that each file exists and is well-formed:
|
|
|
|
- robots.txt
|
|
- sitemap.xml
|
|
- llms.txt
|
|
- the AI Catalog
|
|
- 404.html
|
|
- the text in every sitemap page's HTML
|
|
- each page's markdown mirror
|
|
|
|
```yaml
|
|
# .github/workflows/*.yml, after the build
|
|
- run: ~/src/utils/agent_ready/check.sh dist dist/
|
|
```
|
|
|
|
```yaml
|
|
# .pre-commit-config.yaml (local hook; build first, e.g. in a wrapper script)
|
|
- id: agent-ready
|
|
name: AgentReady (build output)
|
|
entry: bash -c 'pnpm build >/dev/null && ~/src/utils/agent_ready/check.sh dist dist'
|
|
language: system
|
|
pass_filenames: false
|
|
```
|
|
|
|
Dist mode cannot check HTTP behaviour: content types, the `Link` header, real
|
|
404 status, or responses to agent user-agents. Those checks print as SKIP, or
|
|
the check falls back to "404.html exists".
|
|
|
|
## Post-deploy (url mode)
|
|
|
|
Run this once the deploy is live:
|
|
|
|
```sh
|
|
~/src/utils/agent_ready/check.sh url https://kuhy.duckdns.org
|
|
```
|
|
|
|
Url mode checks status codes **and** content types. A server that answers
|
|
every path with `200 text/html` (an SPA fallback) fails on robots.txt, the
|
|
sitemap, llms.txt, the catalog and the 404 probe. A status-only check would
|
|
pass it. Url mode also checks that:
|
|
|
|
- `/agentready-probe-<random>` ends on a 404, after following redirects.
|
|
- No sitemap page is byte-identical to the homepage shell.
|
|
- The homepage answers 200 to ClaudeBot, GPTBot and the other agent
|
|
user-agents.
|
|
|
|
## Tests
|
|
|
|
```sh
|
|
~/.claude/scripts/capped.sh python -m pytest ~/src/utils/agent_ready/tests -q
|
|
```
|
|
|
|
The test fixtures are generated in `tmp_path` by `tests/sitegen.py`, so there
|
|
are no static mirror `.md` files to trip the markdown-naming gate. The good
|
|
and bad build trees are served by loopback `http.server` instances in four
|
|
shapes:
|
|
|
|
- compliant
|
|
- SPA fallback
|
|
- JSON 404 on every path
|
|
- 403 to GPTBot
|