@rivi-software/agentic-seo-check 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RIVI Software
+
+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

@@ -1,3 +1,211 @@
-# Temporary Holding Version
+<p align="center">
+  <a href="https://rivi.software">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/rivi-software/agentic-seo-check/main/assets/rivi-agentic-seo-check-on-dark.svg">
+      <img src="https://raw.githubusercontent.com/rivi-software/agentic-seo-check/main/assets/rivi-agentic-seo-check.svg" alt="RIVI agentic-seo-check" width="545">
+    </picture>
+  </a>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  SEO analysis built for coding agents: a CLI and an MCP server that audit URLs,<br>
+  static build output or raw HTML, and return findings an agent can act on.<br>
+  Open source, from <a href="https://rivi.software">RIVI Software</a>.
+</p>
+
+<p align="center">
+  <a href="https://github.com/rivi-software/agentic-seo-check/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/rivi-software/agentic-seo-check/ci.yml?branch=main&label=CI" alt="CI status"></a>
+  <a href="https://www.npmjs.com/package/@rivi-software/agentic-seo-check"><img src="https://img.shields.io/npm/v/@rivi-software/agentic-seo-check?color=0b6b3a" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@rivi-software/agentic-seo-check"><img src="https://img.shields.io/npm/dm/@rivi-software/agentic-seo-check?color=0b6b3a" alt="Monthly npm downloads"></a>
+  <a href="https://github.com/rivi-software/agentic-seo-check/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-0b6b3a" alt="MIT License"></a>
+</p>
+
+<p align="center">
+  <a href="#install">Install</a>
+  ·
+  <a href="#cli">CLI</a>
+  ·
+  <a href="#mcp-server">MCP server</a>
+  ·
+  <a href="#agent-skill">Agent skill</a>
+  ·
+  <a href="https://github.com/rivi-software/agentic-seo-check/blob/main/CONTRIBUTING.md">Contributing</a>
+  ·
+  <a href="https://rivi.software">rivi.software</a>
+</p>
+
+<br>
+
+agentic-seo-check is one core with two interfaces:
+
+- **CLI** `agentic-seo-check` with JSON (default when piped) or Markdown output and CI-friendly exit codes.
+- **MCP server** exposing five tools for Claude Code, Cursor, Codex and any other MCP client.
+
+It audits **URLs** (production, staging, `localhost` dev servers), **static build output** (`dist/`, `out/`, `build/`) and **raw HTML**, and returns findings an agent can act on: a stable rule id, severity, what is wrong, the fix, a CSS selector for where it lives, and evidence with the current values.
+
+## What it checks
+
+| Area | Examples (123 rules in total, `agentic-seo-check rules` lists them) |
+| --- | --- |
+| On-page basics | title missing/long/short/placeholder ("React App"), meta description, H1 and heading outline, canonical (missing, conflicting, relative, pointing elsewhere), robots meta and `X-Robots-Tag`, `lang`, viewport, charset, doctype |
+| Social | Open Graph completeness, absolute `og:image`, `og:url` vs canonical, Twitter card |
+| Images and links | alt text, filename-style alt, missing dimensions (CLS), empty or generic anchor text, `href="#"`/`javascript:` anchors, http links on https pages, internal nofollow |
+| International | hreflang syntax, absolute URLs, self reference, x-default, return links (crawl) |
+| Structured data | JSON-LD parse errors, `@context`/`@type`, required and recommended properties for Article, Product, Offer, Organization, WebSite, BreadcrumbList, FAQPage, LocalBusiness, Event, Recipe, VideoObject, JobPosting, HowTo, Review, SoftwareApplication and more, ISO 8601 dates; microdata too |
+| Content | empty or thin content, "lorem ipsum", readability, keyword presence in title/H1/body/description/URL and density |
+| Response | 4xx/5xx, redirects and chains, slow HTML response, non-HTML content type, http instead of https |
+| Site-level (crawl or directory) | robots.txt (missing, blocking, disallowed pages), sitemap (missing, invalid, noindex/non-canonical/broken/redirecting URLs, pages not in sitemap, orphan pages), broken internal links with their sources, redirected links and chains, duplicate titles/descriptions/H1s/content, deep pages, soft 404, http→https and www redirects, hreflang return links |
+| Rendering (`--render`, Playwright) | title/description/canonical/H1/content/links/structured data that only exist after JavaScript runs; noindex injected or removed by JavaScript; console errors |
+| Performance (`--lighthouse`, Chrome) | LCP, CLS, TBT, FCP, Speed Index, TTFB with Core Web Vitals thresholds, Lighthouse opportunities with estimated savings, failed Lighthouse SEO and agentic-browsing audits |
+
+## Install
+
+Requires Node 22.19 or newer. Published on npm as [`@rivi-software/agentic-seo-check`](https://www.npmjs.com/package/@rivi-software/agentic-seo-check); the commands it installs are `agentic-seo-check` and `agentic-seo-check-mcp`.
+
+```bash
+npx @rivi-software/agentic-seo-check audit https://example.com   # no install
+npm install -g @rivi-software/agentic-seo-check                  # or pnpm add -D / npm i -D in a project
+agentic-seo-check --help
+```
+
+Optional, only for `--render` and `--lighthouse`: `playwright` and `lighthouse` (+ `chrome-launcher`) are optional peer dependencies, so install them next to the tool, plus Google Chrome or `npx playwright install chromium`. The renderer uses a Playwright-managed Chromium when present and falls back to the installed Google Chrome or Edge.
+
+From source: `pnpm install && pnpm build && node dist/cli.js --help`.
+
+## CLI
+
+```bash
+# one page (Markdown on a terminal, JSON when piped or with --format json)
+agentic-seo-check audit https://www.example.com/pricing
+
+# whole site
+agentic-seo-check crawl https://www.example.com --max-pages 100 --max-depth 4
+
+# local dev server, ignore the dev robots.txt, include JS rendering comparison
+agentic-seo-check audit http://localhost:3000 --crawl --ignore-robots --render
+
+# static export, with the production origin for canonical/sitemap comparison
+agentic-seo-check audit ./out --base-url https://www.example.com
+
+# raw HTML from stdin
+cat page.html | agentic-seo-check audit - --base-url https://www.example.com/page
+
+# keyword focus, Lighthouse, Markdown report to a file
+agentic-seo-check audit https://www.example.com/widgets --keyword "blue widgets" --lighthouse -o report.md
+
+# CI: exit 1 when errors exist, smaller output
+agentic-seo-check audit https://staging.example.com --crawl --fail-on error --compact --no-info
+
+# rule reference
+agentic-seo-check rules --category structured-data
+agentic-seo-check rules --rule canonical.multiple
+```
+
+Exit codes: `0` success, `1` findings at or above `--fail-on`, `2` usage or runtime error. Progress goes to stderr, the report to stdout.
+
+## MCP server
+
+Add to a project `.mcp.json` (Claude Code reads it automatically):
+
+```json
+{
+  "mcpServers": {
+    "agentic-seo-check": {
+      "command": "npx",
+      "args": ["-y", "@rivi-software/agentic-seo-check", "mcp"]
+    }
+  }
+}
+```
+
+Or `claude mcp add agentic-seo-check -- npx -y @rivi-software/agentic-seo-check mcp`. From a source checkout, use `node /absolute/path/to/agentic-seo-check/dist/mcp-bin.js` instead (this repo's own `.mcp.json` does that).
+
+| Tool | Purpose |
+| --- | --- |
+| `seo_audit_page` | Audit one URL or an HTML string. Options: `keyword`, `render`, `lighthouse`, `formFactor`, `includeInfo`, `disableRules`, `headers`, `format` (json/markdown), `detail` (compact/full). |
+| `seo_crawl_site` | Crawl and audit a site. Options: `maxPages`, `maxDepth`, `concurrency`, `delayMs`, `respectRobots`, `includeSubdomains`, `checkExternalLinks`, `includePatterns`, `excludePatterns`, `pageDetail`. |
+| `seo_audit_directory` | Audit built HTML files in a directory. Options: `dir`, `baseUrl`, `maxPages`, `pageDetail`. |
+| `seo_lighthouse` | Lighthouse performance + SEO + agentic-browsing for one URL. |
+| `seo_list_rules` | Rule reference, filter by `category` or `rule`. |
+
+All tools are read-only. Results are returned both as text (JSON or Markdown) and as `structuredContent`.
+
+## Agent skill
+
+`skills/seo-audit/SKILL.md` teaches an agent the audit → fix → re-audit loop, how to map rule ids to framework code (Next.js, Astro, Nuxt, SvelteKit, Remix, TanStack Start), and the caveats (preview-host noindex, localhost limits). Copy it to `.claude/skills/seo-audit/` in a project or `~/.claude/skills/` to make it available; this repo links it under `.claude/skills/`.
+
+## Output shape
+
+```jsonc
+{
+  "schemaVersion": 1,
+  "kind": "page",                    // or "site"
+  "url": "https://www.example.com/",
+  "score": 67,                       // 100 - 15/error - 5/warning - 1/info, floored at 0
+  "counts": { "error": 0, "warning": 6, "info": 3 },
+  "summary": { "title": "…", "metaDescription": null, "canonical": null, "indexable": true, "h1": [], "wordCount": 25, "...": "…" },
+  "findings": [
+    {
+      "rule": "meta-description.missing",
+      "severity": "warning",
+      "category": "meta",
+      "message": "Page has no meta description.",
+      "recommendation": "Add a unique meta description (about 70-160 characters) …",
+      "selector": "head > meta[name=\"description\"]",
+      "url": "https://www.example.com/",
+      "docs": "https://developers.google.com/search/docs/appearance/snippet"
+    }
+  ],
+  "response": { "status": 200, "finalUrl": "…", "redirectChain": [], "timeMs": 142, "headers": { "content-type": "text/html" } },
+  "performance": { "metrics": { "performanceScore": 99, "lcpMs": 848, "cls": 0, "...": "…" }, "opportunities": [] },   // with --lighthouse
+  "rendering": { "raw": { "wordCount": 25 }, "rendered": { "wordCount": 137 }, "...": "…" }                         // with --render
+}
+```
+
+Site audits add `crawl` stats, `robotsTxt`, `sitemaps`, `siteFindings`, `issues` (page findings rolled up per rule with example URLs) and `pages`.
+
+## Library
+
+```ts
+import { auditUrl, auditSite, auditDirectory, auditHtml, renderMarkdown } from '@rivi-software/agentic-seo-check';
+
+const page = await auditUrl('https://www.example.com/', { keyword: 'example', render: true });
+const site = await auditSite('https://www.example.com/', { maxPages: 100 });
+console.log(renderMarkdown(site));
+```
+
+## Scope of this first version
+
+- Crawls are breadth-first, same-site, HTML only, and obey robots.txt by default. `--render`/`--lighthouse` apply to the start page only during a crawl.
+- Scores are indicative. Thresholds (title 30-60 chars, description 70-160, thin content 300 words, slow response 2 s, deep page depth 3) are configurable through the library `thresholds` option.
+- Not included yet: gzip sitemaps, rendering every page in a crawl, field (CrUX) data, rank tracking, backlink data, AI-generated copy suggestions.
+
+## Contributing
+
+Bug reports, wrong findings, new rules and fixes are welcome from anyone. With Node 24 and pnpm 12:
+
+```bash
+pnpm install
+pnpm run verify
+```
+
+`verify` runs what CI runs: format, lint, typecheck, tests, build and a check of the packed package. `pnpm run dev audit https://example.com` runs the CLI from source. [CONTRIBUTING.md](https://github.com/rivi-software/agentic-seo-check/blob/main/CONTRIBUTING.md) covers proposing a change, what a pull request needs and how releases reach npm, and [AGENTS.md](https://github.com/rivi-software/agentic-seo-check/blob/main/AGENTS.md) is the brief for coding agents working on the tool itself. Everyone who takes part follows the [code of conduct](https://github.com/rivi-software/agentic-seo-check/blob/main/CODE_OF_CONDUCT.md). [SECURITY.md](https://github.com/rivi-software/agentic-seo-check/blob/main/SECURITY.md) says how to report a vulnerability privately.
+
+## License
+
+Licensed under the [MIT License](https://github.com/rivi-software/agentic-seo-check/blob/main/LICENSE). Copyright © 2026 RIVI Software.
+
+<br>
+
+<p align="center">
+  <a href="https://rivi.software">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/rivi-software/agentic-seo-check/main/assets/rivi-mark-on-dark.svg">
+      <img src="https://raw.githubusercontent.com/rivi-software/agentic-seo-check/main/assets/rivi-mark.svg" alt="RIVI Software" width="36" height="36">
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <sub>RIVI agentic-seo-check is made by <a href="https://rivi.software">RIVI Software</a>, which builds software for radio stations. Created in <a href="https://t3.codes">T3 Code</a>.</sub>
+</p>

package/dist/brand.d.ts

@@ -0,0 +1,11 @@
+/**
+ * RIVI Software's name, site and mark as the CLI, the MCP server and the Markdown report show
+ * them. The marks are copies of assets/rivi-mark.svg and assets/rivi-mark-on-dark.svg, inlined
+ * because npm ships dist/ without assets/.
+ */
+import type { Icon } from "@modelcontextprotocol/sdk/types.js";
+export declare const MAKER = "RIVI Software";
+export declare const MAKER_URL = "https://rivi.software";
+export declare const REPOSITORY_URL = "https://github.com/rivi-software/agentic-seo-check";
+/** The mark as MCP icons: the ink tile for light themes, the light tile for dark ones. */
+export declare const MCP_ICONS: Icon[];

package/dist/brand.js

@@ -0,0 +1,22 @@
+export const MAKER = "RIVI Software";
+export const MAKER_URL = "https://rivi.software";
+export const REPOSITORY_URL = "https://github.com/rivi-software/agentic-seo-check";
+const MARK_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 40 40" role="img" aria-label="RIVI Software"><rect width="40" height="40" rx="9" fill="#15171a"/><g fill="#f5f6f7"><rect x="8" y="16" width="3" height="8" rx="1.5"/><rect x="13.25" y="11" width="3" height="18" rx="1.5"/><rect x="18.5" y="7" width="3" height="26" rx="1.5" fill="#3be08a"/><rect x="23.75" y="12" width="3" height="16" rx="1.5"/><rect x="29" y="16" width="3" height="8" rx="1.5"/></g></svg>';
+const MARK_ON_DARK_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 40 40" role="img" aria-label="RIVI Software"><rect width="40" height="40" rx="9" fill="#f5f6f7"/><g fill="#15171a"><rect x="8" y="16" width="3" height="8" rx="1.5"/><rect x="13.25" y="11" width="3" height="18" rx="1.5"/><rect x="18.5" y="7" width="3" height="26" rx="1.5" fill="#0e9f55"/><rect x="23.75" y="12" width="3" height="16" rx="1.5"/><rect x="29" y="16" width="3" height="8" rx="1.5"/></g></svg>';
+const dataUri = (svg) => `data:image/svg+xml;base64,${Buffer.from(svg, "utf-8").toString("base64")}`;
+/** The mark as MCP icons: the ink tile for light themes, the light tile for dark ones. */
+export const MCP_ICONS = [
+    {
+        mimeType: "image/svg+xml",
+        sizes: ["any"],
+        src: dataUri(MARK_SVG),
+        theme: "light",
+    },
+    {
+        mimeType: "image/svg+xml",
+        sizes: ["any"],
+        src: dataUri(MARK_ON_DARK_SVG),
+        theme: "dark",
+    },
+];
+//# sourceMappingURL=brand.js.map

package/dist/brand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brand.js","sourceRoot":"","sources":["../src/brand.ts"],"names":[],"mappings":"AAOA,MAAM,CAAC,MAAM,KAAK,GAAG,eAAe,CAAC;AACrC,MAAM,CAAC,MAAM,SAAS,GAAG,uBAAuB,CAAC;AAEjD,MAAM,CAAC,MAAM,cAAc,GACzB,oDAAoD,CAAC;AAEvD,MAAM,QAAQ,GACZ,2cAA2c,CAAC;AAE9c,MAAM,gBAAgB,GACpB,2cAA2c,CAAC;AAE9c,MAAM,OAAO,GAAG,CAAC,GAAW,EAAE,EAAE,CAC9B,6BAA6B,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;AAE9E,0FAA0F;AAC1F,MAAM,CAAC,MAAM,SAAS,GAAW;IAC/B;QACE,QAAQ,EAAE,eAAe;QACzB,KAAK,EAAE,CAAC,KAAK,CAAC;QACd,GAAG,EAAE,OAAO,CAAC,QAAQ,CAAC;QACtB,KAAK,EAAE,OAAO;KACf;IACD;QACE,QAAQ,EAAE,eAAe;QACzB,KAAK,EAAE,CAAC,KAAK,CAAC;QACd,GAAG,EAAE,OAAO,CAAC,gBAAgB,CAAC;QAC9B,KAAK,EAAE,MAAM;KACd;CACF,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+import { promises as fs } from "node:fs";
+import { Command, InvalidArgumentError, Option } from "commander";
+import { MAKER, MAKER_URL, REPOSITORY_URL } from "./brand.js";
+import { auditTarget, compactAudit } from "./core/audit.js";
+import { renderMarkdown } from "./core/report/markdown.js";
+import { ALL_RULES } from "./core/rules/index.js";
+import { SEVERITY_RANK } from "./core/types.js";
+import { startMcpServer } from "./mcp.js";
+import { VERSION } from "./version.js";
+const program = new Command();
+program
+    .name("agentic-seo-check")
+    .description("SEO analysis for coding agents. Audits URLs, static build output or raw HTML and prints machine-readable findings.")
+    .version(VERSION)
+    .addHelpText("afterAll", `\nMade by ${MAKER} (${MAKER_URL}). Docs and issues: ${REPOSITORY_URL}`)
+    .showHelpAfterError();
+const intArg = (value) => {
+    // oxlint-disable-next-line unicorn/prefer-number-coercion -- parseInt reads the leading digits ("10.5" is 10), where Number would refuse what users have always passed
+    const n = Number.parseInt(value, 10);
+    if (!Number.isFinite(n) || n < 0) {
+        throw new InvalidArgumentError("Expected a non-negative integer.");
+    }
+    return n;
+};
+const addAuditOptions = (cmd, crawlDefault) => {
+    if (!crawlDefault) {
+        cmd.option("--crawl", "Crawl the whole site starting at the URL instead of auditing one page");
+    }
+    return cmd
+        .option("--max-pages <n>", "Maximum pages to crawl", intArg, 50)
+        .option("--max-depth <n>", "Maximum link depth from the start URL", intArg, 3)
+        .option("--concurrency <n>", "Parallel requests while crawling", intArg, 5)
+        .option("--delay <ms>", "Delay between requests per worker", intArg, 0)
+        .option("-k, --keyword <keyword>", "Target keyword for keyword.* checks")
+        .option("--render", "Render with headless Chromium (Playwright) and compare with the server HTML")
+        .option("--lighthouse", "Run Lighthouse for Core Web Vitals and Lighthouse SEO audits (slow)")
+        .addOption(new Option("--form-factor <type>", "Lighthouse device emulation")
+        .choices(["mobile", "desktop"])
+        .default("mobile"))
+        .option("--base-url <url>", "Origin used for directories, files and stdin HTML (default http://localhost/)")
+        .option("--ignore-robots", "Do not obey robots.txt while crawling")
+        .option("--include-subdomains", "Treat subdomains as internal when crawling")
+        .option("--check-external", "Probe external links for 4xx/5xx while crawling")
+        .option("--include <regex...>", "Only crawl URLs matching these patterns")
+        .option("--exclude <regex...>", "Skip URLs matching these patterns")
+        .addOption(new Option("-f, --format <format>", "Output format (default: json when piped, md on a terminal)").choices(["json", "md"]))
+        .option("-o, --out <file>", "Write the report to a file instead of stdout")
+        .addOption(new Option("--fail-on <severity>", "Exit with code 1 when findings at or above this severity exist")
+        .choices(["error", "warning", "info", "none"])
+        .default("none"))
+        .option("--no-info", "Omit info-level findings")
+        .option("--compact", "Trim evidence lists and bulky fields (smaller output for LLM consumption)")
+        .addOption(new Option("--page-detail <level>", "Per-page detail in site reports")
+        .choices(["full", "summary"])
+        .default("full"))
+        .option("--disable <rule...>", "Rule ids to skip")
+        .option("--timeout <ms>", "Per-request timeout", intArg, 15_000)
+        .option("--user-agent <ua>", "Custom User-Agent header")
+        .option("-H, --header <header...>", 'Extra request header "Name: value" (repeatable)')
+        .option("-q, --quiet", "Suppress progress output on stderr");
+};
+/** The report format: as asked, else by the output file's extension, else Markdown on a terminal. */
+const formatOf = (opts) => {
+    if (opts.format !== undefined) {
+        return opts.format;
+    }
+    if (opts.out) {
+        return opts.out.endsWith(".md") ? "md" : "json";
+    }
+    return process.stdout.isTTY ? "md" : "json";
+};
+const runAudit = async (target, opts, forceCrawl) => {
+    const headers = {};
+    for (const h of opts.header ?? []) {
+        const idx = h.indexOf(":");
+        if (idx === -1) {
+            throw new InvalidArgumentError(`Header "${h}" must be "Name: value".`);
+        }
+        headers[h.slice(0, idx).trim()] = h.slice(idx + 1).trim();
+    }
+    const showProgress = !opts.quiet && process.stderr.isTTY;
+    const onProgress = (e) => {
+        if (!showProgress) {
+            return;
+        }
+        const counter = e.crawled === undefined ? "" : ` [${e.crawled}/${e.discovered}]`;
+        process.stderr.write(`\u001B[2m${e.phase}${counter}: ${e.message}\u001B[0m\n`);
+    };
+    const options = {
+        crawl: forceCrawl || Boolean(opts.crawl),
+        maxPages: opts.maxPages,
+        maxDepth: opts.maxDepth,
+        concurrency: opts.concurrency,
+        delayMs: opts.delay,
+        keyword: opts.keyword,
+        render: opts.render,
+        lighthouse: opts.lighthouse,
+        formFactor: opts.formFactor,
+        baseUrl: opts.baseUrl,
+        respectRobots: !opts.ignoreRobots,
+        includeSubdomains: opts.includeSubdomains,
+        checkExternalLinks: opts.checkExternal,
+        includePatterns: opts.include,
+        excludePatterns: opts.exclude,
+        includeInfo: opts.info,
+        disableRules: opts.disable,
+        pageDetail: opts.pageDetail,
+        fetch: {
+            timeoutMs: opts.timeout,
+            userAgent: opts.userAgent,
+            headers: Object.keys(headers).length ? headers : undefined,
+        },
+        onProgress,
+    };
+    let audit = await auditTarget(target, options);
+    if (opts.compact) {
+        audit = compactAudit(audit);
+    }
+    const format = formatOf(opts);
+    const output = format === "md" ? renderMarkdown(audit) : JSON.stringify(audit, null, 2);
+    if (opts.out) {
+        await fs.writeFile(opts.out, `${output}\n`, "utf-8");
+        if (!opts.quiet) {
+            process.stderr.write(`Report written to ${opts.out}\n`);
+        }
+    }
+    else {
+        process.stdout.write(`${output}\n`);
+    }
+    if (opts.failOn !== "none") {
+        const threshold = SEVERITY_RANK[opts.failOn];
+        const { counts } = audit;
+        const hits = ["error", "warning", "info"]
+            .filter((s) => SEVERITY_RANK[s] >= threshold)
+            .reduce((n, s) => n + counts[s], 0);
+        if (hits > 0) {
+            if (!opts.quiet) {
+                process.stderr.write(`${hits} finding(s) at or above "${opts.failOn}" severity.\n`);
+            }
+            process.exitCode = 1;
+        }
+    }
+};
+addAuditOptions(program
+    .command("audit")
+    .argument("<target>", 'URL, directory of HTML files, .html file, or "-" for HTML on stdin')
+    .description("Audit a page, a site (--crawl), a build directory or raw HTML"), false).action(async (target, opts) => {
+    await runAudit(target, opts, false);
+});
+addAuditOptions(program
+    .command("crawl")
+    .argument("<url>", "Start URL")
+    .description('Crawl a site and audit every page (same as "audit --crawl")'), true).action(async (url, opts) => {
+    await runAudit(url, opts, true);
+});
+program
+    .command("rules")
+    .description("List the rules this tool can report")
+    .option("--category <category>", "Filter by category")
+    .option("--rule <id>", "Show one rule")
+    .addOption(new Option("-f, --format <format>", "Output format")
+    .choices(["json", "md"])
+    .default(process.stdout.isTTY ? "md" : "json"))
+    .action((opts) => {
+    const rules = ALL_RULES.filter((r) => (!opts.category || r.category === opts.category) &&
+        (!opts.rule || r.id === opts.rule));
+    if (opts.format === "json") {
+        process.stdout.write(`${JSON.stringify({ count: rules.length, rules }, null, 2)}\n`);
+        return;
+    }
+    const lines = [
+        "| Rule | Severity | Category | Checks |",
+        "| --- | --- | --- | --- |",
+    ];
+    for (const r of rules) {
+        lines.push(`| \`${r.id}\` | ${r.severity} | ${r.category} | ${r.description.replaceAll("|", "\\|")}${r.requires ? ` _(requires ${r.requires})_` : ""} |`);
+    }
+    process.stdout.write(`${lines.join("\n")}\n`);
+});
+program
+    .command("mcp")
+    .description("Start the MCP server on stdio (for Claude Code, Cursor, Codex, etc.)")
+    .action(async () => {
+    await startMcpServer();
+});
+try {
+    await program.parseAsync(process.argv);
+}
+catch (error) {
+    process.stderr.write(`agentic-seo-check: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(2);
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AAEzC,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAElE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE5D,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,mBAAmB,CAAC;KACzB,WAAW,CACV,oHAAoH,CACrH;KACA,OAAO,CAAC,OAAO,CAAC;KAChB,WAAW,CACV,UAAU,EACV,aAAa,KAAK,KAAK,SAAS,uBAAuB,cAAc,EAAE,CACxE;KACA,kBAAkB,EAAE,CAAC;AAExB,MAAM,MAAM,GAAG,CAAC,KAAa,EAAU,EAAE;IACvC,uKAAuK;IACvK,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAErC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,oBAAoB,CAAC,kCAAkC,CAAC,CAAC;IACrE,CAAC;IAED,OAAO,CAAC,CAAC;AACX,CAAC,CAAC;AAEF,MAAM,eAAe,GAAG,CAAC,GAAY,EAAE,YAAqB,EAAW,EAAE;IACvE,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,GAAG,CAAC,MAAM,CACR,SAAS,EACT,uEAAuE,CACxE,CAAC;IACJ,CAAC;IAED,OAAO,GAAG;SACP,MAAM,CAAC,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,EAAE,EAAE,CAAC;SAC/D,MAAM,CACL,iBAAiB,EACjB,uCAAuC,EACvC,MAAM,EACN,CAAC,CACF;SACA,MAAM,CAAC,mBAAmB,EAAE,kCAAkC,EAAE,MAAM,EAAE,CAAC,CAAC;SAC1E,MAAM,CAAC,cAAc,EAAE,mCAAmC,EAAE,MAAM,EAAE,CAAC,CAAC;SACtE,MAAM,CAAC,yBAAyB,EAAE,qCAAqC,CAAC;SACxE,MAAM,CACL,UAAU,EACV,6EAA6E,CAC9E;SACA,MAAM,CACL,cAAc,EACd,qEAAqE,CACtE;SACA,SAAS,CACR,IAAI,MAAM,CAAC,sBAAsB,EAAE,6BAA6B,CAAC;SAC9D,OAAO,CAAC,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;SAC9B,OAAO,CAAC,QAAQ,CAAC,CACrB;SACA,MAAM,CACL,kBAAkB,EAClB,+EAA+E,CAChF;SACA,MAAM,CAAC,iBAAiB,EAAE,uCAAuC,CAAC;SAClE,MAAM,CACL,sBAAsB,EACtB,4CAA4C,CAC7C;SACA,MAAM,CACL,kBAAkB,EAClB,iDAAiD,CAClD;SACA,MAAM,CAAC,sBAAsB,EAAE,yCAAyC,CAAC;SACzE,MAAM,CAAC,sBAAsB,EAAE,mCAAmC,CAAC;SACnE,SAAS,CACR,IAAI,MAAM,CACR,uBAAuB,EACvB,4DAA4D,CAC7D,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAC1B;SACA,MAAM,CAAC,kBAAkB,EAAE,8CAA8C,CAAC;SAC1E,SAAS,CACR,IAAI,MAAM,CACR,sBAAsB,EACtB,gEAAgE,CACjE;SACE,OAAO,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;SAC7C,OAAO,CAAC,MAAM,CAAC,CACnB;SACA,MAAM,CAAC,WAAW,EAAE,0BAA0B,CAAC;SAC/C,MAAM,CACL,WAAW,EACX,2EAA2E,CAC5E;SACA,SAAS,CACR,IAAI,MAAM,CAAC,uBAAuB,EAAE,iCAAiC,CAAC;SACnE,OAAO,CAAC,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;SAC5B,OAAO,CAAC,MAAM,CAAC,CACnB;SACA,MAAM,CAAC,qBAAqB,EAAE,kBAAkB,CAAC;SACjD,MAAM,CAAC,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,EAAE,MAAM,CAAC;SAC/D,MAAM,CAAC,mBAAmB,EAAE,0BAA0B,CAAC;SACvD,MAAM,CACL,0BAA0B,EAC1B,iDAAiD,CAClD;SACA,MAAM,CAAC,aAAa,EAAE,oCAAoC,CAAC,CAAC;AACjE,CAAC,CAAC;AA+BF,qGAAqG;AACrG,MAAM,QAAQ,GAAG,CAAC,IAAgB,EAAiB,EAAE;IACnD,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;QACb,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;IAClD,CAAC;IAED,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;AAC9C,CAAC,CAAC;AAEF,MAAM,QAAQ,GAAG,KAAK,EACpB,MAAc,EACd,IAAgB,EAChB,UAAmB,EACJ,EAAE;IACjB,MAAM,OAAO,GAA2B,EAAE,CAAC;IAE3C,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;QAClC,MAAM,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAE3B,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;YACf,MAAM,IAAI,oBAAoB,CAAC,WAAW,CAAC,0BAA0B,CAAC,CAAC;QACzE,CAAC;QAED,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5D,CAAC;IAED,MAAM,YAAY,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;IAEzD,MAAM,UAAU,GAAG,CAAC,CAAgB,EAAQ,EAAE;QAC5C,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,OAAO;QACT,CAAC;QAED,MAAM,OAAO,GACX,CAAC,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,UAAU,GAAG,CAAC;QAEnE,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,YAAY,CAAC,CAAC,KAAK,GAAG,OAAO,KAAK,CAAC,CAAC,OAAO,aAAa,CACzD,CAAC;IACJ,CAAC,CAAC;IAEF,MAAM,OAAO,GAAuC;QAClD,KAAK,EAAE,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;QACxC,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,OAAO,EAAE,IAAI,CAAC,KAAK;QACnB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,aAAa,EAAE,CAAC,IAAI,CAAC,YAAY;QACjC,iBAAiB,EAAE,IAAI,CAAC,iBAAiB;QACzC,kBAAkB,EAAE,IAAI,CAAC,aAAa;QACtC,eAAe,EAAE,IAAI,CAAC,OAAO;QAC7B,eAAe,EAAE,IAAI,CAAC,OAAO;QAC7B,WAAW,EAAE,IAAI,CAAC,IAAI;QACtB,YAAY,EAAE,IAAI,CAAC,OAAO;QAC1B,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,KAAK,EAAE;YACL,SAAS,EAAE,IAAI,CAAC,OAAO;YACvB,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;SAC3D;QACD,UAAU;KACX,CAAC;IAEF,IAAI,KAAK,GAAU,MAAM,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEtD,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC;IAED,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAE9B,MAAM,MAAM,GACV,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAE3E,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;QACb,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,IAAI,EAAE,OAAO,CAAC,CAAC;QAErD,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;YAChB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qBAAqB,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAC3B,MAAM,SAAS,GAAG,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC7C,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;QAEzB,MAAM,IAAI,GAAI,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,CAAW;aACjD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC;aAC5C,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAEtC,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;YACb,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;gBAChB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,GAAG,IAAI,4BAA4B,IAAI,CAAC,MAAM,eAAe,CAC9D,CAAC;YACJ,CAAC;YAED,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;AACH,CAAC,CAAC;AAEF,eAAe,CACb,OAAO;KACJ,OAAO,CAAC,OAAO,CAAC;KAChB,QAAQ,CACP,UAAU,EACV,oEAAoE,CACrE;KACA,WAAW,CACV,+DAA+D,CAChE,EACH,KAAK,CACN,CAAC,MAAM,CAAC,KAAK,EAAE,MAAc,EAAE,IAAgB,EAAE,EAAE;IAClD,MAAM,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;AACtC,CAAC,CAAC,CAAC;AAEH,eAAe,CACb,OAAO;KACJ,OAAO,CAAC,OAAO,CAAC;KAChB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;KAC9B,WAAW,CAAC,6DAA6D,CAAC,EAC7E,IAAI,CACL,CAAC,MAAM,CAAC,KAAK,EAAE,GAAW,EAAE,IAAgB,EAAE,EAAE;IAC/C,MAAM,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AAClC,CAAC,CAAC,CAAC;AAEH,OAAO;KACJ,OAAO,CAAC,OAAO,CAAC;KAChB,WAAW,CAAC,qCAAqC,CAAC;KAClD,MAAM,CAAC,uBAAuB,EAAE,oBAAoB,CAAC;KACrD,MAAM,CAAC,aAAa,EAAE,eAAe,CAAC;KACtC,SAAS,CACR,IAAI,MAAM,CAAC,uBAAuB,EAAE,eAAe,CAAC;KACjD,OAAO,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;KACvB,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CACjD;KACA,MAAM,CACL,CAAC,IAAiE,EAAE,EAAE;IACpE,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAC5B,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC,QAAQ,CAAC;QAChD,CAAC,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,IAAI,CAAC,CACrC,CAAC;IAEF,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAC/D,CAAC;QAEF,OAAO;IACT,CAAC;IAED,MAAM,KAAK,GAAG;QACZ,yCAAyC;QACzC,2BAA2B;KAC5B,CAAC;IAEF,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CACR,OAAO,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,QAAQ,MAAM,CAAC,CAAC,QAAQ,MAAM,CAAC,CAAC,WAAW,CAAC,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAC9I,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAChD,CAAC,CACF,CAAC;AAEJ,OAAO;KACJ,OAAO,CAAC,KAAK,CAAC;KACd,WAAW,CACV,sEAAsE,CACvE;KACA,MAAM,CAAC,KAAK,IAAI,EAAE;IACjB,MAAM,cAAc,EAAE,CAAC;AACzB,CAAC,CAAC,CAAC;AAEL,IAAI,CAAC;IACH,MAAM,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AACzC,CAAC;AAAC,OAAO,KAAK,EAAE,CAAC;IACf,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,sBAAsB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CACjF,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}

package/dist/core/audit.d.ts

@@ -0,0 +1,72 @@
+import type { ProgressEvent } from "./crawl.js";
+import type { FetchOptions } from "./fetch.js";
+import type { Audit, IssueRollup, PageAudit, PageSource, ResponseInfo, SiteAudit, Thresholds } from "./types.js";
+export type { ProgressEvent } from "./crawl.js";
+export interface AuditOptions {
+    /** Target keyword/phrase for the keyword.* rules. */
+    keyword?: string;
+    /** Render with headless Chromium (Playwright) and compare against the server HTML. */
+    render?: boolean;
+    /** Run Lighthouse (performance + SEO + agentic-browsing categories). */
+    lighthouse?: boolean;
+    formFactor?: "mobile" | "desktop";
+    /** Include info-level findings (default true). */
+    includeInfo?: boolean;
+    /** Rule ids to skip. */
+    disableRules?: string[];
+    thresholds?: Partial<Thresholds>;
+    fetch?: FetchOptions;
+    /** Base URL for inline HTML, files and directories (default http://localhost/). */
+    baseUrl?: string;
+    includeSubdomains?: boolean;
+    onProgress?: (event: ProgressEvent) => void;
+}
+export interface CrawlOptions extends AuditOptions {
+    maxPages?: number;
+    maxDepth?: number;
+    concurrency?: number;
+    delayMs?: number;
+    respectRobots?: boolean;
+    checkExternalLinks?: boolean;
+    maxLinkChecks?: number;
+    includePatterns?: string[];
+    excludePatterns?: string[];
+    /** How much per-page detail to keep in the site result. */
+    pageDetail?: "full" | "summary";
+}
+export interface HtmlAuditInput {
+    url?: string;
+    response?: ResponseInfo;
+    source?: PageSource;
+    target?: string;
+    depth?: number;
+}
+export declare const DEFAULT_CRAWL: {
+    readonly maxPages: 50;
+    readonly maxDepth: 3;
+    readonly concurrency: 5;
+    readonly delayMs: 0;
+    readonly maxLinkChecks: 200;
+};
+export declare const rollupIssues: (pages: PageAudit[]) => IssueRollup[];
+export declare const recomputeSite: (site: SiteAudit) => void;
+/** Audit an HTML string. `url` is used to resolve links and for display. */
+export declare const auditHtml: (html: string, input?: HtmlAuditInput, options?: AuditOptions) => Promise<PageAudit>;
+/** Fetch and audit one URL. Optionally render and/or run Lighthouse. */
+export declare const auditUrl: (url: string, options?: AuditOptions) => Promise<PageAudit>;
+/** Audit a single .html file from disk. */
+export declare const auditFile: (filePath: string, options?: AuditOptions) => Promise<PageAudit>;
+/** Crawl a site and audit every page plus site-level checks. */
+export declare const auditSite: (startUrl: string, options?: CrawlOptions) => Promise<SiteAudit>;
+/** Audit a directory of built HTML files (dist/, out/, build/). */
+export declare const auditDirectory: (dir: string, options?: CrawlOptions) => Promise<SiteAudit>;
+/**
+ * Auto-detect the target type: http(s) URL, directory, .html file, or "-" for stdin.
+ * `crawl` forces a site crawl for URLs.
+ */
+export declare const auditTarget: (target: string, options?: CrawlOptions & {
+    crawl?: boolean;
+    stdinHtml?: string;
+}) => Promise<Audit>;
+/** Drop bulky, low-value fields to save tokens when the result is consumed by an LLM. */
+export declare const compactAudit: <T extends Audit>(audit: T) => T;