{"_id":"@bridgetoagent-com/llms-txt-validator","name":"@bridgetoagent-com/llms-txt-validator","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@bridgetoagent-com/llms-txt-validator","version":"0.1.0","description":"Validator for llms.txt — checks parser conformance against the llmstxt.org reference spec, link reachability, and missing sections.","keywords":["llms.txt","llms-txt","validator","linter","ai-agents","agentic-web","llmstxt"],"homepage":"https://www.bridgetoagent.com/tools/llms-txt-validator","bugs":{"url":"https://github.com/bridgetoagent/llms-txt-validator/issues"},"repository":{"type":"git","url":"git+https://github.com/bridgetoagent/llms-txt-validator.git"},"license":"MIT","author":{"name":"BridgeToAgent editorial","url":"https://www.bridgetoagent.com"},"type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"main":"./dist/index.js","types":"./dist/index.d.ts","bin":{"llms-txt-validator":"dist/cli.js"},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","lint":"tsc --noEmit","prepublishOnly":"npm run lint && npm run test && npm run build"},"publishConfig":{"access":"public"},"engines":{"node":">=18.0.0"},"devDependencies":{"@types/node":"^20.11.0","@vitest/coverage-v8":"^1.2.0","tsup":"^8.0.1","typescript":"^5.3.3","vitest":"^1.2.0"},"gitHead":"64ea45c20cedc4f15a637c4783548270c19b0ba4","_id":"@bridgetoagent-com/llms-txt-validator@0.1.0","_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-Rfz4Bo6ai9iGY/wMO5J18FgnVv0MYV98UGCmlObtGXZzDD7u6wU3+Ji7YX79GoWjDUdCxmcBxtv6+Zgbw4DiZQ==","shasum":"faa0fd3504cca832cc7db1694a8d0c8db5c605b4","tarball":"https://registry.npmjs.org/@bridgetoagent-com/llms-txt-validator/-/llms-txt-validator-0.1.0.tgz","fileCount":9,"unpackedSize":115390,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC3Cfvu9mLC7LCvYFoCw08E4iewjkkhJdlOweohOoO8zgIgXlRlfVglEC3weZkF29NSzBvDxW/3CqDbz3i+QI4Wk6E="}]},"_npmUser":{"name":"bridgetoagent","email":"info@shakaproductions.se"},"directories":{},"maintainers":[{"name":"bridgetoagent","email":"info@shakaproductions.se"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/llms-txt-validator_0.1.0_1779208918444_0.42324709774465585"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-19T16:41:58.321Z","0.1.0":"2026-05-19T16:41:58.588Z","modified":"2026-05-19T16:41:58.850Z"},"maintainers":[{"name":"bridgetoagent","email":"info@shakaproductions.se"}],"description":"Validator for llms.txt — checks parser conformance against the llmstxt.org reference spec, link reachability, and missing sections.","homepage":"https://www.bridgetoagent.com/tools/llms-txt-validator","keywords":["llms.txt","llms-txt","validator","linter","ai-agents","agentic-web","llmstxt"],"repository":{"type":"git","url":"git+https://github.com/bridgetoagent/llms-txt-validator.git"},"author":{"name":"BridgeToAgent editorial","url":"https://www.bridgetoagent.com"},"bugs":{"url":"https://github.com/bridgetoagent/llms-txt-validator/issues"},"license":"MIT","readme":"# llms-txt-validator\n\nValidator for [llms.txt](https://llmstxt.org) — checks parser conformance against the reference spec, link reachability, and missing or malformed sections.\n\nShips as:\n\n- A **hosted web tool** at [bridgetoagent.com/tools/llms-txt-validator](https://www.bridgetoagent.com/tools/llms-txt-validator) — paste, upload, or fetch by URL. No signup, no email gate.\n- A **CLI** for local files and CI pipelines.\n- A **JavaScript / TypeScript library** for embedding in your own validation flow.\n\nMIT licensed. No telemetry. No external dependencies beyond `fetch`.\n\n---\n\n## Install\n\n```bash\nnpm install --save-dev @bridgetoagent-com/llms-txt-validator\n# or\npnpm add -D @bridgetoagent-com/llms-txt-validator\n# or\nyarn add -D @bridgetoagent-com/llms-txt-validator\n```\n\nRequires Node 18 or newer (uses the native `fetch` API).\n\n---\n\n## Quick start\n\n### CLI\n\n```bash\n# Validate a local file\nnpx @bridgetoagent-com/llms-txt-validator ./llms.txt\n\n# Fetch and validate from a URL\nnpx @bridgetoagent-com/llms-txt-validator https://example.com/llms.txt\n\n# Also verify every link is reachable\nnpx @bridgetoagent-com/llms-txt-validator ./llms.txt --check-links\n\n# Machine-readable output for CI\nnpx @bridgetoagent-com/llms-txt-validator ./llms.txt --json\n```\n\nExit codes:\n\n| Code | Meaning |\n| ---- | ------- |\n| `0`  | Valid (status: `pass`) |\n| `1`  | Warnings only (status: `pass_with_warnings`) |\n| `2`  | Errors found (status: `fail`) |\n| `64` | Bad command-line usage |\n| `66` | Could not read input |\n\n### Library\n\n```ts\nimport { validate } from \"@bridgetoagent-com/llms-txt-validator\";\n\nconst source = await fs.readFile(\"./llms.txt\", \"utf8\");\nconst report = await validate(source);\n\nconsole.log(report.status);     // \"pass\" | \"pass_with_warnings\" | \"fail\"\nconsole.log(report.summary);    // { errors, warnings, infos, sections, links }\nconsole.log(report.issues);     // [{ severity, code, message, line, ... }, ...]\nconsole.log(report.parsed);     // parsed document tree\n```\n\nEnable reachability checking:\n\n```ts\nconst report = await validate(source, {\n  checkReachability: true,\n  concurrency: 8,       // default\n  timeoutMs: 5000,      // default\n  slowThresholdMs: 3000 // default\n});\n\nconsole.log(report.reachability); // { checked, failed, slow }\n```\n\nParser only (no validation, no I/O):\n\n```ts\nimport { parse } from \"@bridgetoagent-com/llms-txt-validator\";\n\nconst doc = parse(source);\n// doc.title, doc.description, doc.sections[].links, etc.\n```\n\n---\n\n## What gets checked\n\n### Structure (always on)\n\n- `# Title` is present and is the first non-blank content\n- No duplicate H1 headings\n- Optional `> blockquote` description captured immediately after the title\n- `## Section` headings used for resource groups (H2 level)\n- H3+ headings flagged (info — uncommon in llms.txt)\n- Empty sections flagged\n\n### Link bullets\n\n- `- [text](url)` or `- [text](url): description` syntax\n- Malformed Markdown links flagged\n- Empty link text or URL\n- Relative URLs (`/docs/foo`) — llms.txt is consumed by external agents, must be absolute\n- Fragment-only URLs (`#anchor`)\n- `mailto:` URLs flagged as unusual\n- `http://` URLs flagged (prefer `https://`)\n- Duplicate URLs (warning) and duplicate link text (info)\n\n### Reachability (opt-in)\n\nPass `--check-links` (CLI) or `{ checkReachability: true }` (library) to enable network checks:\n\n- Bounded-concurrency HEAD requests against every link\n- Falls back to GET when HEAD returns 405 or 501\n- `link-non-2xx` for 4xx/5xx responses\n- `link-unreachable` for network errors and timeouts\n- `link-slow` warning for links above the slow threshold (default 3s)\n\nUser-agent: `bridgetoagent-llms-txt-validator/0.1 (+https://github.com/bridgetoagent/llms-txt-validator)` — identifies itself so server logs aren't anonymous.\n\n---\n\n## Issue codes\n\nStable identifiers for every kind of finding — pin on these in CI or tooling.\n\n| Code | Severity | Meaning |\n| ---- | -------- | ------- |\n| `missing-title` | error | No `# Title` heading found |\n| `title-not-first` | error | Content appears before the title |\n| `title-not-h1` | error | First heading is not H1 |\n| `duplicate-title` | warning | Multiple H1 headings |\n| `section-wrong-level` | info | H3+ heading where H2 is conventional |\n| `empty-section` | warning | Section has no link bullets |\n| `malformed-link` | error | Bullet line is not a valid Markdown link |\n| `link-missing-url` | error | Link `[text]()` has no URL |\n| `link-empty-text` | warning | Link `[](url)` has no display text |\n| `link-relative-url` | warning | Root-relative URL — must be absolute |\n| `link-hash-only` | warning | Fragment-only URL — meaningless to external agents |\n| `link-mailto` | info | `mailto:` URL — unusual in llms.txt |\n| `link-non-https` | warning | `http://` — prefer `https://` |\n| `duplicate-url` | warning | Same URL appears more than once |\n| `duplicate-link-text` | info | Same link text appears more than once |\n| `link-unreachable` | error | Network error or timeout (reachability mode) |\n| `link-non-2xx` | error | HTTP 4xx or 5xx response (reachability mode) |\n| `link-slow` | warning | Response slower than threshold (reachability mode) |\n| `no-content-after-title` | warning | Title exists but nothing else |\n| `trailing-whitespace` | info | Line has trailing whitespace |\n| `tabs-instead-of-spaces` | info | Line contains tab characters |\n\n---\n\n## CI / pre-commit usage\n\n### GitHub Actions\n\n```yaml\n- name: Validate llms.txt\n  run: npx @bridgetoagent-com/llms-txt-validator ./public/llms.txt --check-links\n```\n\n### Husky / lint-staged\n\n```json\n{\n  \"lint-staged\": {\n    \"public/llms.txt\": \"@bridgetoagent-com/llms-txt-validator\"\n  }\n}\n```\n\n### Standalone script\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\nnpx @bridgetoagent-com/llms-txt-validator ./public/llms.txt --check-links --json > .llms-txt-report.json\n```\n\n---\n\n## How this compares to other tools\n\nThis validator focuses on **conformance to the [llmstxt.org reference spec](https://llmstxt.org)** plus **link health**.\n\nIt does **not**:\n\n- Generate `llms.txt` from a site's DOM (see [BridgeToAgent](https://www.bridgetoagent.com) for that)\n- Score how *good* the content of your `llms.txt` is for any particular agent\n- Crawl the URLs it references to validate the linked content\n\nGenerating a complete agent-readiness kit from your real site is a separate problem — that's what the BridgeToAgent kit at [bridgetoagent.com](https://www.bridgetoagent.com) does ($49, generates `agents.json` + `llms.txt` + `agent-instructions.md` together).\n\n---\n\n## Contributing\n\nBug reports, edge cases, and PRs welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md).\n\nGood first issues:\n\n- Real-world `llms.txt` files we miss-parse (open an issue with the source URL)\n- Additional issue codes for spec corner cases\n- Performance improvements on large files\n\n---\n\n## License\n\n[MIT](./LICENSE) — copyright 2026 BridgeToAgent editorial.\n\n---\n\n## See also\n\n- The [llmstxt.org](https://llmstxt.org) reference specification\n- BridgeToAgent's [agent-readiness blog coverage](https://www.bridgetoagent.com/blog)\n- [The Lighthouse Agentic Browsing audit suite](https://www.bridgetoagent.com/blog/lighthouse-every-audit-every-fix), which includes the `llms-txt-well-formed` audit this validator helps you pass\n","readmeFilename":"README.md","_rev":"1-1f73d843c1a43fd24145e935f5419656"}