meodp 0.0.9 → 0.1.0

package/README.md

@@ -1,46 +1,228 @@
 # MEODP (Mystic Eyes of Death Perception)
 
-Written by Typescript, based on [Playwright](https://playwright.dev/).
+[![npm version](https://img.shields.io/npm/v/meodp)](https://www.npmjs.com/package/meodp)
 
-## Usage
+[English](https://yunyoujun.github.io/meodp/) | [简体中文](https://yunyoujun.github.io/meodp/zh/)
 
-You can use it like a lib or a cli.
+Check website and friend-link availability from Node.js or the command line. Built on [linkinator](https://github.com/JustinBeckwith/linkinator), with interactive HTML, JSON, and Markdown reports and optional history across runs.
 
-Or like an application:
+Requires **Node.js 22.19+**. The `meodp/check` entry, `meodp check`, and `meodp sitemap` commands do not require Playwright or a browser installation.
+
+Guides: [English](https://yunyoujun.github.io/meodp/guide/quick-start.html) · [简体中文](https://yunyoujun.github.io/meodp/zh/guide/quick-start.html). The repository's VitePress site includes API/CLI references and workspace development instructions in both languages.
+
+## Install
+
+```bash
+pnpm add meodp
+```
+
+## Library
 
 ```ts
-// Create a config file: `meodp.config.ts` in your project root.
-import { defineConfig } from 'meodp'
+import { checkLinks, formatReport, readReport, saveReport, writeReports } from 'meodp/check'
+
+const historyFile = '.cache/link-check/local.json'
+const report = await checkLinks([
+  { name: '云游君', url: 'https://www.yunyoujun.cn/' },
+  'https://example.com/',
+], {
+  observer: 'my-local-network',
+  previousReport: await readReport(historyFile),
+  concurrency: 5,
+  timeoutMs: 10000,
+  retries: 1,
+})
+
+console.log(formatReport(report))
+await writeReports(report, 'reports/links')
+await saveReport(report, historyFile)
+```
 
-export default defineConfig({
+`checkLinks()` returns a report without writing files. URL strings and objects with `url` and optional `name` are accepted; duplicate normalized URLs are checked once, in input order. Other fields such as friend email addresses are not copied into reports. Invalid input rejects before any requests are made.
 
+| Option           | Default          | Meaning                                                   |
+| ---------------- | ---------------- | --------------------------------------------------------- |
+| `concurrency`    | `5`              | Simultaneous site checks, from 1 to 100                   |
+| `timeoutMs`      | `10000`          | Per-request timeout in milliseconds, from 1 to 300000     |
+| `retries`        | `1`              | Additional attempts for transport/5xx errors, from 0 to 5 |
+| `maxRedirects`   | `5`              | Maximum followed redirects per attempt, from 0 to 20      |
+| `observer`       | Machine hostname | Identifies the network used for these observations        |
+| `previousReport` | None             | Previous report from the same observer                    |
+| `onResult`       | None             | Optional callback when each site's observation is ready   |
+
+Each observation includes its HTTP status, final URL, redirect chain, duration, attempt count, failure reason, last success, consecutive failed runs, and recovery/change flags. `formatReport(report, 'html')` returns a self-contained interactive HTML report; `'json'` returns JSON; the default is Markdown. `writeReports()` writes `report.html`, `report.json`, and `report.md` and returns `{ html, json, markdown }`.
+
+## Sitemap page checks
+
+Check all pages listed in an XML sitemap, reusing the same HTTP observations, history, and reports:
+
+```ts
+import { checkSitemap, readSitemapUrls, writeReports } from 'meodp/check'
+
+const report = await checkSitemap('https://example.com/sitemap.xml', {
+  concurrency: 5,
+  timeoutMs: 10000,
+  maxUrls: 10000,
 })
+await writeReports(report, 'reports/pages')
+
+// Start from a site: read Sitemap directives in robots.txt, then /sitemap.xml if none exist.
+const siteReport = await checkSitemap('https://example.com/', { discover: true })
+
+// Inspect or select the page list before making any page requests.
+const urls = await readSitemapUrls('https://example.com/sitemap.xml')
 ```
 
-## Ref
+```bash
+pnpm exec meodp sitemap https://example.com/sitemap.xml --output reports/pages
+pnpm exec meodp sitemap https://example.com/ --discover --output reports/pages \
+  --history .cache/sitemap/local.json --observer my-local-network
+pnpm exec meodp sitemap --help
+```
+
+Supports XML URL sets, nested sitemap indexes, namespaces, CDATA, XML entities, gzip files, redirects, and multiple `Sitemap:` directives in `robots.txt`. Relative entries resolve against the final sitemap URL. Pages and indexes are deduplicated; fragment identifiers are removed and query strings are preserved. Cyclic indexes terminate. Sitemaps may list pages on other HTTP(S) origins; those explicit entries are included.
+
+All `checkLinks()` options also apply. `readSitemapUrls()` only requests discovery documents; `checkSitemap()` then checks the complete list with the existing linkinator adapter. Sitemap documents are read sequentially; `concurrency` controls page checks. HTTP timeouts, retries, and redirect limits apply to both phases. Only transport/5xx discovery failures are retried. Robots discovery falls back for 404/410 or a successful file with no sitemap declarations; other errors are surfaced.
+
+| Additional option                         | Default    | Meaning                                                                     |
+| ----------------------------------------- | ---------- | --------------------------------------------------------------------------- |
+| `discover` / `--discover`                 | `false`    | Treat the input as a site URL; otherwise it is an explicit sitemap URL      |
+| `maxUrls` / `--max-urls`                  | `10000`    | Maximum unique pages, configurable up to 50000                              |
+| `maxSitemaps` / `--max-sitemaps`          | `100`      | Maximum sitemap documents, configurable up to 10000                         |
+| `maxSitemapBytes` / `--max-sitemap-bytes` | `10485760` | Per-document downloaded/decompressed byte limit, configurable up to 100 MiB |
+
+Discovery is complete before any page checks begin. A missing or unreadable nested sitemap, invalid XML/URL, empty page list, or exceeded limit rejects the run. The CLI exits with `2` and preserves existing reports/history, even with `--fail-on none`; it never saves a silently truncated page list. Page findings use the same `0`/`1` exit policies as `meodp check`.
+
+This mode measures HTTP availability of sitemap-listed pages. It does not follow their article links, check embedded assets, execute JavaScript, or apply robots `Disallow` rules. XML parsing and validation use [fast-xml-parser](https://github.com/NaturalIntelligence/fast-xml-parser); MEODP handles bounded discovery and delegates page checks to linkinator. Linkinator also offers a [native sitemap scan](https://github.com/JustinBeckwith/linkinator#command-usage), but its public API combines discovery with page/link scanning. Keeping discovery separate preserves MEODP's URL-only probes and existing redirect/history semantics.
+
+## CLI
+
+Use explicit subcommands to distinguish a fresh network check from rendering saved data:
 
-- [lychee](https://lychee.cli.rs/)
+| Command        | Input                            | Behavior                                                       |
+| -------------- | -------------------------------- | -------------------------------------------------------------- |
+| `meodp check`  | URL array in JSON/YAML           | Request sites and write fresh HTML, Markdown, and JSON reports |
+| `meodp report` | Saved `report.json`, or no input | Export a static report viewer; no site-check requests          |
+| `meodp scan`   | Legacy config directory          | Run the experimental Playwright scanner                        |
 
-## Logs
+`meodp`, `meodp --help`, and `meodp help` display the command overview. Use `meodp check -h` or `meodp help report` for details; `meodp --version` / `-v` prints the version. Unknown commands exit with code `2` instead of starting a scan. Help and version do not require Playwright.
+
+Create `links.yml` (JSON arrays also work):
+
+```yaml
+- name: 云游君
+  url: https://www.yunyoujun.cn/
+- name: Example
+  url: https://example.com/
+```
 
 ```bash
-logs/meodp
+pnpm exec meodp check links.yml --output reports/links
+
+# Persist observations from one network across separate runs.
+pnpm exec meodp check links.yml --output reports/links \
+  --history .cache/link-check/local.json --observer my-local-network
+
+# Generate a maintenance report without failing because a friend is unavailable.
+pnpm exec meodp check links.yml --fail-on none
+
+pnpm exec meodp check --help
 ```
 
-## FAQ
+`meodp check` inputs are local `.json`, `.yml`, or `.yaml` files. A friends-style array containing additional fields is supported directly. Only its `url` and `name` are used. Download remote list data explicitly before checking it; use `meodp sitemap` for remote sitemap inputs.
+
+Exit codes:
+
+- `0`: the selected policy passed.
+- `1`: observations matched the policy. Default `--fail-on unavailable` fails on unavailable sites; `--fail-on review` also includes restricted access and redirects.
+- `2`: invalid input/options, incompatible or corrupt history, or an execution/report-writing error. `--fail-on none` does not suppress these errors.
 
-### 与 lychee 的区别
+### Project scripts
 
-lychee 是一个使用 Rust 编写的快速检测链接的命令行。
-它的命令行应该能满足你使用命令行的大部分需求。
+Keep the package CLI general and name project scripts after their specific subject:
 
-但我希望能够通过脚本/配置自由地定制检测流程、日志，并记录相关内容，执行对应的函数。
-因此我们需要一个类似 SDK 的库，来实现类似的功能。
-同时基于 Typescript 可以获得更好的开发灵活性，而使用 Playwright 则可以模拟浏览器以检测页面中的资源加载。
+```json
+{
+  "scripts": {
+    "check:links": "meodp check public/links.yml --output reports/links --fail-on none",
+    "report:links": "meodp report reports/links/report.json --output reports/site"
+  }
+}
+```
+
+Use `pnpm run check:links` and `pnpm run report:links`; keep `lint`, `typecheck`, and `test` for code validation. `report:links` should render existing observations rather than implicitly invoke `check:links`. This makes exporting a report reproducible without another network scan. In CI, select the failure policy explicitly; friends uses `check:links:ci` with its own observer and history file.
+
+Documentation and CI use explicit `pnpm run <script>` for project scripts and `pnpm exec meodp <command>` for the package CLI. [pnpm documents](https://pnpm.io/cli/run) script-name shorthand only when it does not conflict with a built-in command; options after the script name are passed to the script.
+
+## Interactive report and static site
+
+Open `report.html` directly in a browser. It embeds the data, script, and styles in one file and works offline. The viewer supports status filters, name/URL search, sorting, pagination, expandable HTTP/error/redirect/history details, local JSON import (including drag-and-drop), JSON URL loading, and downloading the loaded report. Mobile layouts keep technical fields inside expandable details.
+
+Export an existing report as a static site, **without checking the sites again**:
+
+```bash
+pnpm exec meodp report reports/links/report.json --output reports/site
+
+# A reusable viewer with no bundled data; users can load their own JSON.
+pnpm exec meodp report --output reports/viewer
+
+# Read data from another location (cross-origin sources must allow CORS).
+pnpm exec meodp report --output reports/viewer --data-url https://example.com/report.json
+```
+
+Upload the contents of `reports/site/` to any static host, including a subdirectory. No Node.js server, database, browser automation, or CDN assets are needed at runtime. The output contains:
+
+- `index.html`: the interactive viewer with an embedded snapshot.
+- `report.json`: the data loaded on each hosted page visit, with cache bypassed. Replace it after a new scan to update the hosted view.
+
+Opening `index.html` through `file://` uses the embedded snapshot; choose a JSON file to load newer data offline. A hosted data-load failure displays an error and retains the embedded/current report. `--data-url` overrides the hosted source. The page reads reports; scanning still runs in Node.js or CI. Displayed timestamps always come from the observations, not the page load time.
+
+```ts
+import { parseReport, writeReportSite } from 'meodp/check'
+
+const report = parseReport(JSON.parse(jsonText))
+await writeReportSite(report, 'reports/site')
+await writeReportSite(undefined, 'reports/viewer', { dataUrl: './data/report.json' })
+```
+
+The viewer accepts MEODP `schemaVersion: 1` reports, validates observations and summary counts, and renders names/errors as text. Local files stay in the browser. Browser imports are limited to 10 MiB and 50,000 sites; HTTP data loads time out after 15 seconds. No remote scanning occurs in the viewer. Publish only the report data you intend to share: reports include observer names, site URLs, times, and error details.
+
+## Interpreting results
+
+| Status        | Meaning                                                                               |
+| ------------- | ------------------------------------------------------------------------------------- |
+| `reachable`   | The requested URL, possibly after redirects, returned HTTP 2xx                        |
+| `restricted`  | HTTP 401, 403, 429, 451, or 999; access needs review                                  |
+| `unavailable` | Other HTTP errors, transport/DNS/TLS failures, timeouts, or invalid/looping redirects |
+
+`checkLinks()` requests only the supplied URLs and their redirect destinations. `checkSitemap()` first reads discovery documents, then uses those same probes for the listed pages. The checker uses GET for the pages and does not request discovered article links, images, scripts, or stylesheets. Redirects are recorded separately from availability; a redirect to a working site is still reachable.
+
+Results describe **this observer at this time**. HTTP 2xx does not verify content, detect expired-domain parking, execute JavaScript, or prove that a blog is still owned by the same person. Restricted results require manual or browser verification. Sites using JavaScript redirects or returning a challenge page with HTTP 200 need separate verification.
+
+`consecutiveFailures` counts separate completed runs, not retries within one run or days of continuous downtime. A reachable or restricted observation breaks that failure streak. Previous success is retained. History must use the same observer; use distinct files for different machines or CI networks. Missing history starts a new record; corrupt history is an error. Use one writer per history file.
+
+MEODP reports observations; it does not remove friends, change their addresses, or send notifications.
+
+## Existing browser scanner
+
+The original Playwright-based scanner remains available through the root library entry and `meodp scan [root]` with `meodp.config.ts`. Install `playwright` and its browsers separately to use it. Its experimental resource scanning and legacy report format are separate from `meodp/check`; its CLI does not implement the new failure policies. The old `meodp export` command is retained for that legacy report format; use `meodp report` for a new `schemaVersion: 1` JSON report.
+
+**CLI migration for 0.1:** change a bare `meodp` scan to `meodp scan`, and `meodp ./project` to `meodp scan ./project`. The bare command now displays help. Existing `meodp check` / `meodp report` invocations and library APIs are unchanged.
+
+The former development-only `meodp-ts` executable is no longer shipped. Run `pnpm --filter meodp exec tsx bin/index.ts` from the workspace root when developing.
+
+## Development
+
+```bash
+pnpm install
+pnpm test
+pnpm typecheck
+pnpm build
+pnpm pack
+```
 
-如果可能，它未来也许可以支持插件或预置配置。
+The viewer source lives in `packages/meodp/src/check/viewer/` in the repository. Build, test, and typecheck commands bundle its browser TypeScript and CSS into an ignored generated module; published HTML needs no runtime dependencies.
 
-## TODO
+Tests use local HTTP servers for redirects, restricted access, transient failures, timeouts, history, report output, CLI exit policies, and sitemap discovery (indexes, gzip, namespaces, cycles, limits, and partial failures). They do not scan external sites. Library type checking and declaration generation use the package's `tsconfig.json`, independently of the experimental client template.
 
-- [ ] 文件下载
-- [ ] HTML 报告
+See [competitive analysis](https://github.com/YunYouJun/meodp/blob/main/docs/competitive-analysis.md) for the project scope and alternatives.

package/bin/index.mjs

@@ -1,6 +1,14 @@
 #!/usr/bin/env node
 'use strict'
 
-import { run } from '../dist/cli/index.mjs'
+import process from 'node:process'
+import { runCli } from '../dist/cli/main.mjs'
 
-run()
+async function main() {
+  process.exitCode = await runCli()
+}
+
+main().catch((error) => {
+  console.error(error)
+  process.exitCode = 2
+})

package/dist/check/cli.cjs

@@ -0,0 +1,166 @@
+'use strict';
+
+const promises = require('node:fs/promises');
+const path = require('node:path');
+const process = require('node:process');
+const node_util = require('node:util');
+const jsYaml = require('js-yaml');
+const check_index = require('../shared/meodp.a0bcc3e7.cjs');
+require('node:timers/promises');
+require('linkinator');
+require('node:os');
+require('node:crypto');
+require('node:buffer');
+require('node:zlib');
+require('fast-xml-parser');
+
+function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e.default : e; }
+
+const process__default = /*#__PURE__*/_interopDefaultCompat(process);
+
+const help = `Usage: meodp check <links.json|links.yml> [options]
+
+Check only the listed HTTP(S) URLs, with no browser or recursive resource scan.
+Input: an array of URL strings or objects with url and optional name.
+This makes network requests. To render saved data instead, use meodp report.
+
+  --output <directory>  Write report.json, report.md, report.html (default: reports/meodp)
+  --history <file>      Read previous observations and save the completed report
+  --observer <name>     Identify this network/environment (default: hostname)
+  --concurrency <n>     Concurrent sites (default: 5)
+  --timeout <ms>        Timeout per HTTP request (default: 10000)
+  --retries <n>         Retries for transport/5xx failures (default: 1)
+  --max-redirects <n>   Follow at most n redirects (default: 5)
+  --fail-on <policy>    unavailable (default), review, or none
+  -h, --help           Show this help
+
+Exit codes: 0 = policy passed; 1 = findings match --fail-on; 2 = input/execution error.
+Restricted results and redirects require review; they do not prove a dead site.
+`;
+async function runCheckCli(args = process__default.argv.slice(3)) {
+  return runScanCli("links", args);
+}
+async function runSitemapCli(args = process__default.argv.slice(3)) {
+  return runScanCli("sitemap", args);
+}
+async function runScanCli(mode, args) {
+  try {
+    const { values, positionals } = node_util.parseArgs({
+      args,
+      allowPositionals: true,
+      options: {
+        "output": { type: "string", default: "reports/meodp" },
+        "history": { type: "string" },
+        "observer": { type: "string" },
+        "concurrency": { type: "string" },
+        "timeout": { type: "string" },
+        "retries": { type: "string" },
+        "max-redirects": { type: "string" },
+        "fail-on": { type: "string", default: "unavailable" },
+        "help": { type: "boolean", short: "h" },
+        ...mode === "sitemap" ? {
+          "discover": { type: "boolean" },
+          "max-urls": { type: "string" },
+          "max-sitemaps": { type: "string" },
+          "max-sitemap-bytes": { type: "string" }
+        } : {}
+      }
+    });
+    if (values.help) {
+      console.log(mode === "links" ? help : `Usage: meodp sitemap <sitemap-url> [options]
+
+Read an XML sitemap or nested index, then check each listed page via HTTP.
+  --discover            Treat the URL as a site: read robots.txt or /sitemap.xml
+  --max-urls <n>         Reject discovery above n unique pages (default: 10000)
+  --max-sitemaps <n>     Limit sitemap documents (default: 100)
+  --max-sitemap-bytes <n> Limit each downloaded/decompressed document (default: 10485760)
+
+${help.slice(help.indexOf("  --output"))}`);
+      return 0;
+    }
+    if (positionals.length !== 1)
+      throw new Error(`Provide exactly one ${mode === "links" ? "JSON or YAML input file" : "HTTP(S) URL"}. Use --help for examples.`);
+    if (!["none", "unavailable", "review"].includes(values["fail-on"]))
+      throw new Error("--fail-on must be none, unavailable, or review");
+    const numeric = (value) => typeof value === "string" ? Number(value) : void 0;
+    const options = {
+      observer: values.observer,
+      previousReport: values.history ? await check_index.readReport(values.history) : void 0,
+      concurrency: numeric(values.concurrency),
+      timeoutMs: numeric(values.timeout),
+      retries: numeric(values.retries),
+      maxRedirects: numeric(values["max-redirects"]),
+      onResult(result) {
+        console.log(`[${result.status}] ${result.httpStatus ?? result.reason} ${result.url}`);
+      }
+    };
+    const input = positionals[0];
+    const report = mode === "sitemap" ? await check_index.checkSitemap(input, {
+      ...options,
+      discover: values.discover === true,
+      maxUrls: numeric(values["max-urls"]),
+      maxSitemaps: numeric(values["max-sitemaps"]),
+      maxSitemapBytes: numeric(values["max-sitemap-bytes"])
+    }) : await check_index.checkLinks(await readTargets(input), options);
+    const paths = await check_index.writeReports(report, values.output);
+    if (values.history)
+      await check_index.saveReport(report, values.history);
+    console.log(`${report.summary.total} URLs: ${report.summary.reachable} reachable, ${report.summary.restricted} restricted, ${report.summary.unavailable} unavailable`);
+    console.log(`Interactive report: ${path.resolve(paths.html)}`);
+    console.log(`Reports: ${path.resolve(paths.markdown)} and ${path.resolve(paths.json)}`);
+    if (values["fail-on"] === "none")
+      return 0;
+    const findings = report.summary.unavailable > 0 || values["fail-on"] === "review" && (report.summary.restricted > 0 || report.summary.redirected > 0);
+    return findings ? 1 : 0;
+  } catch (error) {
+    console.error(`meodp ${mode === "links" ? "check" : "sitemap"}: ${error instanceof Error ? error.message : String(error)}`);
+    return 2;
+  }
+}
+async function readTargets(input) {
+  const extension = path.extname(input).toLowerCase();
+  if (![".json", ".yml", ".yaml"].includes(extension))
+    throw new Error("Input file must use .json, .yml, or .yaml");
+  const source = await promises.readFile(input, "utf8");
+  return check_index.normalizeTargets(extension === ".json" ? JSON.parse(source) : jsYaml.load(source));
+}
+async function runReportCli(args = process__default.argv.slice(3)) {
+  try {
+    const { values, positionals } = node_util.parseArgs({
+      args,
+      allowPositionals: true,
+      options: {
+        "output": { type: "string", default: "reports/site" },
+        "data-url": { type: "string" },
+        "help": { type: "boolean", short: "h" }
+      }
+    });
+    if (values.help) {
+      console.log(`Usage: meodp report [report.json] [--output reports/site] [--data-url ./report.json]
+
+Export a static interactive viewer without making any site-check requests.
+With an input report, write index.html and report.json. The hosted viewer loads
+report.json on each visit; opening index.html as a local file uses its embedded snapshot.
+Without input, export an empty viewer supporting file upload and JSON URL loading.
+--data-url overrides the data source loaded by the hosted viewer (cross-origin needs CORS).
+-h, --help shows this help. To collect fresh observations, use meodp check.
+Exit codes: 0 = exported; 2 = invalid input or execution error.`);
+      return 0;
+    }
+    if (positionals.length > 1)
+      throw new Error("Provide at most one report.json file. Use --help for examples.");
+    const report = positionals[0] ? await check_index.readReport(positionals[0]) : void 0;
+    if (positionals[0] && !report)
+      throw new Error(`Report not found: ${positionals[0]}`);
+    const paths = await check_index.writeReportSite(report, values.output, values["data-url"] ? { dataUrl: values["data-url"] } : {});
+    console.log(`Static report site: ${path.resolve(paths.index)}`);
+    return 0;
+  } catch (error) {
+    console.error(`meodp report: ${error instanceof Error ? error.message : String(error)}`);
+    return 2;
+  }
+}
+
+exports.runCheckCli = runCheckCli;
+exports.runReportCli = runReportCli;
+exports.runSitemapCli = runSitemapCli;

package/dist/check/cli.d.cts

@@ -0,0 +1,5 @@
+declare function runCheckCli(args?: string[]): Promise<number>;
+declare function runSitemapCli(args?: string[]): Promise<number>;
+declare function runReportCli(args?: string[]): Promise<number>;
+
+export { runCheckCli, runReportCli, runSitemapCli };

package/dist/check/cli.d.mts

@@ -0,0 +1,5 @@
+declare function runCheckCli(args?: string[]): Promise<number>;
+declare function runSitemapCli(args?: string[]): Promise<number>;
+declare function runReportCli(args?: string[]): Promise<number>;
+
+export { runCheckCli, runReportCli, runSitemapCli };

package/dist/check/cli.d.ts

@@ -0,0 +1,5 @@
+declare function runCheckCli(args?: string[]): Promise<number>;
+declare function runSitemapCli(args?: string[]): Promise<number>;
+declare function runReportCli(args?: string[]): Promise<number>;
+
+export { runCheckCli, runReportCli, runSitemapCli };

package/dist/check/cli.mjs

@@ -0,0 +1,158 @@
+import { readFile } from 'node:fs/promises';
+import { resolve, extname } from 'node:path';
+import process from 'node:process';
+import { parseArgs } from 'node:util';
+import { load } from 'js-yaml';
+import { r as readReport, c as checkSitemap, a as checkLinks, w as writeReports, s as saveReport, n as normalizeTargets, b as writeReportSite } from '../shared/meodp.d0916bc5.mjs';
+import 'node:timers/promises';
+import 'linkinator';
+import 'node:os';
+import 'node:crypto';
+import 'node:buffer';
+import 'node:zlib';
+import 'fast-xml-parser';
+
+const help = `Usage: meodp check <links.json|links.yml> [options]
+
+Check only the listed HTTP(S) URLs, with no browser or recursive resource scan.
+Input: an array of URL strings or objects with url and optional name.
+This makes network requests. To render saved data instead, use meodp report.
+
+  --output <directory>  Write report.json, report.md, report.html (default: reports/meodp)
+  --history <file>      Read previous observations and save the completed report
+  --observer <name>     Identify this network/environment (default: hostname)
+  --concurrency <n>     Concurrent sites (default: 5)
+  --timeout <ms>        Timeout per HTTP request (default: 10000)
+  --retries <n>         Retries for transport/5xx failures (default: 1)
+  --max-redirects <n>   Follow at most n redirects (default: 5)
+  --fail-on <policy>    unavailable (default), review, or none
+  -h, --help           Show this help
+
+Exit codes: 0 = policy passed; 1 = findings match --fail-on; 2 = input/execution error.
+Restricted results and redirects require review; they do not prove a dead site.
+`;
+async function runCheckCli(args = process.argv.slice(3)) {
+  return runScanCli("links", args);
+}
+async function runSitemapCli(args = process.argv.slice(3)) {
+  return runScanCli("sitemap", args);
+}
+async function runScanCli(mode, args) {
+  try {
+    const { values, positionals } = parseArgs({
+      args,
+      allowPositionals: true,
+      options: {
+        "output": { type: "string", default: "reports/meodp" },
+        "history": { type: "string" },
+        "observer": { type: "string" },
+        "concurrency": { type: "string" },
+        "timeout": { type: "string" },
+        "retries": { type: "string" },
+        "max-redirects": { type: "string" },
+        "fail-on": { type: "string", default: "unavailable" },
+        "help": { type: "boolean", short: "h" },
+        ...mode === "sitemap" ? {
+          "discover": { type: "boolean" },
+          "max-urls": { type: "string" },
+          "max-sitemaps": { type: "string" },
+          "max-sitemap-bytes": { type: "string" }
+        } : {}
+      }
+    });
+    if (values.help) {
+      console.log(mode === "links" ? help : `Usage: meodp sitemap <sitemap-url> [options]
+
+Read an XML sitemap or nested index, then check each listed page via HTTP.
+  --discover            Treat the URL as a site: read robots.txt or /sitemap.xml
+  --max-urls <n>         Reject discovery above n unique pages (default: 10000)
+  --max-sitemaps <n>     Limit sitemap documents (default: 100)
+  --max-sitemap-bytes <n> Limit each downloaded/decompressed document (default: 10485760)
+
+${help.slice(help.indexOf("  --output"))}`);
+      return 0;
+    }
+    if (positionals.length !== 1)
+      throw new Error(`Provide exactly one ${mode === "links" ? "JSON or YAML input file" : "HTTP(S) URL"}. Use --help for examples.`);
+    if (!["none", "unavailable", "review"].includes(values["fail-on"]))
+      throw new Error("--fail-on must be none, unavailable, or review");
+    const numeric = (value) => typeof value === "string" ? Number(value) : void 0;
+    const options = {
+      observer: values.observer,
+      previousReport: values.history ? await readReport(values.history) : void 0,
+      concurrency: numeric(values.concurrency),
+      timeoutMs: numeric(values.timeout),
+      retries: numeric(values.retries),
+      maxRedirects: numeric(values["max-redirects"]),
+      onResult(result) {
+        console.log(`[${result.status}] ${result.httpStatus ?? result.reason} ${result.url}`);
+      }
+    };
+    const input = positionals[0];
+    const report = mode === "sitemap" ? await checkSitemap(input, {
+      ...options,
+      discover: values.discover === true,
+      maxUrls: numeric(values["max-urls"]),
+      maxSitemaps: numeric(values["max-sitemaps"]),
+      maxSitemapBytes: numeric(values["max-sitemap-bytes"])
+    }) : await checkLinks(await readTargets(input), options);
+    const paths = await writeReports(report, values.output);
+    if (values.history)
+      await saveReport(report, values.history);
+    console.log(`${report.summary.total} URLs: ${report.summary.reachable} reachable, ${report.summary.restricted} restricted, ${report.summary.unavailable} unavailable`);
+    console.log(`Interactive report: ${resolve(paths.html)}`);
+    console.log(`Reports: ${resolve(paths.markdown)} and ${resolve(paths.json)}`);
+    if (values["fail-on"] === "none")
+      return 0;
+    const findings = report.summary.unavailable > 0 || values["fail-on"] === "review" && (report.summary.restricted > 0 || report.summary.redirected > 0);
+    return findings ? 1 : 0;
+  } catch (error) {
+    console.error(`meodp ${mode === "links" ? "check" : "sitemap"}: ${error instanceof Error ? error.message : String(error)}`);
+    return 2;
+  }
+}
+async function readTargets(input) {
+  const extension = extname(input).toLowerCase();
+  if (![".json", ".yml", ".yaml"].includes(extension))
+    throw new Error("Input file must use .json, .yml, or .yaml");
+  const source = await readFile(input, "utf8");
+  return normalizeTargets(extension === ".json" ? JSON.parse(source) : load(source));
+}
+async function runReportCli(args = process.argv.slice(3)) {
+  try {
+    const { values, positionals } = parseArgs({
+      args,
+      allowPositionals: true,
+      options: {
+        "output": { type: "string", default: "reports/site" },
+        "data-url": { type: "string" },
+        "help": { type: "boolean", short: "h" }
+      }
+    });
+    if (values.help) {
+      console.log(`Usage: meodp report [report.json] [--output reports/site] [--data-url ./report.json]
+
+Export a static interactive viewer without making any site-check requests.
+With an input report, write index.html and report.json. The hosted viewer loads
+report.json on each visit; opening index.html as a local file uses its embedded snapshot.
+Without input, export an empty viewer supporting file upload and JSON URL loading.
+--data-url overrides the data source loaded by the hosted viewer (cross-origin needs CORS).
+-h, --help shows this help. To collect fresh observations, use meodp check.
+Exit codes: 0 = exported; 2 = invalid input or execution error.`);
+      return 0;
+    }
+    if (positionals.length > 1)
+      throw new Error("Provide at most one report.json file. Use --help for examples.");
+    const report = positionals[0] ? await readReport(positionals[0]) : void 0;
+    if (positionals[0] && !report)
+      throw new Error(`Report not found: ${positionals[0]}`);
+    const paths = await writeReportSite(report, values.output, values["data-url"] ? { dataUrl: values["data-url"] } : {});
+    console.log(`Static report site: ${resolve(paths.index)}`);
+    return 0;
+  } catch (error) {
+    console.error(`meodp report: ${error instanceof Error ? error.message : String(error)}`);
+    return 2;
+  }
+}
+
+export { runCheckCli, runReportCli, runSitemapCli };

package/dist/check/index.cjs

@@ -0,0 +1,25 @@
+'use strict';
+
+const check_index = require('../shared/meodp.a0bcc3e7.cjs');
+require('node:timers/promises');
+require('linkinator');
+require('node:os');
+require('node:crypto');
+require('node:fs/promises');
+require('node:path');
+require('node:buffer');
+require('node:util');
+require('node:zlib');
+require('fast-xml-parser');
+
+
+
+exports.checkLinks = check_index.checkLinks;
+exports.checkSitemap = check_index.checkSitemap;
+exports.formatReport = check_index.formatReport;
+exports.parseReport = check_index.parseReport;
+exports.readReport = check_index.readReport;
+exports.readSitemapUrls = check_index.readSitemapUrls;
+exports.saveReport = check_index.saveReport;
+exports.writeReportSite = check_index.writeReportSite;
+exports.writeReports = check_index.writeReports;