Skip to content

Universal SEO skill for Claude Code. 26 sub-skills + 19 sub-agents covering technical SEO, E-E-A-T, schema, GEO/AEO, agent readiness (Lighthouse Agentic Browsing, WebMCP, llms.txt), backlinks, local SEO, e-commerce, international SEO, Google APIs, and PDF/Excel reporting. 9 optional extensions for live SEO data.

fix(unlighthouse): pass documented CLI flags, parse the real ci-result shape

Agrici Daniel6210356cce71
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 13f91fc..c953e25 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,6 +15,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
follow. `seo-flow` already had this; the other 13 agents were missing it.
Fixes #291.
+### Fixed
+
+- `unlighthouse_run.py` no longer passes `--max-routes` as `--scanner
+ '{"maxRoutes": N}'`, a CLI flag unlighthouse-ci's parser never reads (the
+ crawl silently ran uncapped). Route count and a new per-page timeout are
+ now set via a generated `unlighthouse.config.mjs` passed with
+ `--config-file`, confirmed against unlighthouse's CLI source and docs.
+ `ci-result.json` is parsed as the array the default `jsonSimple` reporter
+ actually writes, with a tolerant fallback for the `jsonExpanded` object
+ shape, instead of assuming a dict. `extensions/unlighthouse/install.sh`
+ no longer aborts on a marketplace/plugin install: it now also checks
+ `${CLAUDE_PLUGIN_ROOT}` and the plugin cache before requiring the manual
+ `~/.claude/skills/seo` layout. Fixes #189.
+
## [2.2.6] - 2026-09-10
### Security
diff --git a/extensions/unlighthouse/install.sh b/extensions/unlighthouse/install.sh
index 71b3bce..908ec31 100755
--- a/extensions/unlighthouse/install.sh
+++ b/extensions/unlighthouse/install.sh
@@ -8,6 +8,7 @@ set -euo pipefail
main() {
SKILL_DIR="${HOME}/.claude/skills"
+ SEO_SKILL_DIR="${SKILL_DIR}/seo"
echo "════════════════════════════════════════"
echo "║ Claude SEO — Unlighthouse ║"
@@ -15,9 +16,24 @@ main() {
command -v python3 >/dev/null 2>&1 || { echo "✗ Python 3 required."; exit 1; }
command -v npx >/dev/null 2>&1 || { echo "✗ Node 18+ / npx required."; exit 1; }
- [ ! -d "${SKILL_DIR}/seo" ] && { echo "✗ claude-seo base not installed."; exit 1; }
+ # Support both traditional (curl|bash → ~/.claude/skills/seo) and marketplace
+ # (plugin install → ${CLAUDE_PLUGIN_ROOT}, or ~/.claude/plugins/cache/.../skills/seo)
+ # installations. A plugin install never populates ~/.claude/skills/seo, so that
+ # check alone would always abort; check the plugin locations too before failing.
SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" >/dev/null 2>&1 && pwd)"
+ if [ ! -d "${SEO_SKILL_DIR}" ] && [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -d "${CLAUDE_PLUGIN_ROOT}/skills/seo" ]; then
+ SEO_SKILL_DIR="${CLAUDE_PLUGIN_ROOT}/skills/seo"
+ fi
+ if [ ! -d "${SEO_SKILL_DIR}" ]; then
+ _PLUGIN_SEO_DIR="$(cd "${SOURCE_DIR}/../.." 2>/dev/null && pwd)/skills/seo"
+ [ -d "${_PLUGIN_SEO_DIR}" ] && SEO_SKILL_DIR="${_PLUGIN_SEO_DIR}"
+ fi
+ if [ ! -d "${SEO_SKILL_DIR}" ]; then
+ _GLOB_MATCH=$(ls -d "${HOME}/.claude/plugins/cache/"*/claude-seo/*/skills/seo 2>/dev/null | tail -n1 || true)
+ [ -n "${_GLOB_MATCH}" ] && [ -d "${_GLOB_MATCH}" ] && SEO_SKILL_DIR="${_GLOB_MATCH}"
+ fi
+ [ ! -d "${SEO_SKILL_DIR}" ] && { echo "✗ claude-seo base not installed."; exit 1; }
echo "→ Pre-warming unlighthouse..."
npx --yes [email protected] unlighthouse-ci --help >/dev/null 2>&1 || true
diff --git a/extensions/unlighthouse/skills/seo-unlighthouse/SKILL.md b/extensions/unlighthouse/skills/seo-unlighthouse/SKILL.md
index 52a3695..35d0ad2 100644
--- a/extensions/unlighthouse/skills/seo-unlighthouse/SKILL.md
+++ b/extensions/unlighthouse/skills/seo-unlighthouse/SKILL.md
@@ -33,12 +33,21 @@ url_safety pre-flight and subprocess timeout management.
## Output handling
-The wrapper reads `ci-result.json` from the Unlighthouse output dir and
-returns it parsed. Aggregate fields:
-
-- `score.performance` (median across audited routes)
-- `score.accessibility`, `score.bestPractices`, `score.seo`
-- Per-route breakdown is available in `<output_dir>/ci-result.json`
+The wrapper reads `ci-result.json` from the Unlighthouse output dir, normalizes
+it (the default `jsonSimple` reporter writes a flat JSON array of per-route
+results; a tolerant fallback also accepts the `jsonExpanded` object shape),
+and returns:
+
+- `route_count`: number of routes actually audited
+- `aggregate_scores`: median score per Lighthouse category across all audited
+ routes (`performance`, `accessibility`, `best-practices`, `seo`)
+- `routes`: the per-route breakdown (also on disk at `<output_dir>/ci-result.json`)
+
+Route cap and per-page timeout are set via a generated `unlighthouse.config.mjs`
+passed with `--config-file` (the only CLI-documented way to set `scanner.maxRoutes`;
+unlighthouse-ci has no `--max-routes` flag). Use `--page-timeout <seconds>` to
+change the per-page Lighthouse task timeout (default 60s); this is separate
+from the overall `--timeout` subprocess guard (default 600s).
## Cross-skill delegation
diff --git a/scripts/unlighthouse_run.py b/scripts/unlighthouse_run.py
index 7241a45..21c9e09 100644
--- a/scripts/unlighthouse_run.py
+++ b/scripts/unlighthouse_run.py
@@ -10,11 +10,31 @@ support without a paid Google Cloud bill.
This wrapper:
- Validates the target via url_safety before any subprocess starts.
- - Invokes ``npx --yes [email protected] …`` with sensible
- defaults (mobile form factor, 8 parallel workers, JSON output).
- - Captures the JSON summary the CLI writes and returns it parsed
- so claude-seo agents can ingest the result without re-running
- Lighthouse.
+ - Invokes ``npx --yes [email protected] …`` with sensible
+ defaults (mobile form factor, JSON reporter, generated config file).
+ - Captures the JSON result the CLI writes and returns it parsed,
+ normalized to a flat route list regardless of which reporter shape
+ produced it, so claude-seo agents can ingest the result without
+ re-running Lighthouse.
+
+Route cap and per-page timeout
+===============================
+The unlighthouse-ci CLI (a ``cac``-based parser, see
+``packages/cli/src/{createCli,ci,util}.ts`` upstream) has no
+``--max-routes`` flag and does not read an arbitrary ``--scanner``
+argument at all: unrecognised flags are silently dropped by
+``pickOptions()``. The only CLI-documented way to reach
+``scanner.maxRoutes`` is ``--config-file <path>``, a config module
+loaded via c12 (https://unlighthouse.dev/integrations/cli,
+https://unlighthouse.dev/api/config). This wrapper generates a small
+``unlighthouse.config.mjs`` and passes it with ``--config-file``.
+
+The same generated config sets ``puppeteerClusterOptions.timeout``
+(milliseconds), which unlighthouse forwards to ``Cluster.launch()``
+(puppeteer-cluster) as the per-page task timeout — a documented pass
+-through (https://unlighthouse.dev/api/config#puppeteerclusteroptions).
+This guards against a single hung page consuming the whole crawl's
+time budget, independent of the subprocess-level ``--timeout``.
Prerequisites
=============
@@ -34,10 +54,12 @@ import argparse
import json
import os
import shutil
+import statistics
import subprocess
import sys
import tempfile
from pathlib import Path
+from typing import Any
_SCRIPTS_DIR = os.path.dirname(os.path.abspath(__file__))
if _SCRIPTS_DIR not in sys.path:
@@ -46,6 +68,11 @@ from url_safety import URLSafetyError, validate_url_strict # noqa: E402
UNLIGHTHOUSE_PIN = "[email protected]"
+# Numeric metadata keys that are not per-category scores; excluded from
+# aggregate score averaging so a route's `score` (the Lighthouse overall
+# score) doesn't get double-counted alongside its category scores.
+_NON_CATEGORY_NUMERIC_KEYS = frozenset({"score"})
+
def _check_node() -> str | None:
"""Return None if Node is OK, else an error message."""
@@ -56,6 +83,105 @@ def _check_node() -> str | None:
return None
+def build_config(max_routes: int | None, page_timeout_ms: int) -> dict[str, Any]:
+ """Build the object written to the generated unlighthouse config file.
+
+ ``max_routes=None`` maps to ``scanner.maxRoutes: false`` (unlimited),
+ matching the documented type ``number | false``.
+ """
+ return {
+ "scanner": {"maxRoutes": max_routes if max_routes is not None else False},
+ "puppeteerClusterOptions": {"timeout": page_timeout_ms},
+ }
+
+
+def write_config_file(out_dir: Path, config: dict[str, Any]) -> Path:
+ """Write an ESM config module unlighthouse-ci loads via --config-file.
+
+ A ``.mjs`` module (rather than ``.ts``) avoids depending on the TS
+ loader unlighthouse's config resolver (c12) pulls in on demand.
+ """
+ config_path = out_dir / "unlighthouse.config.mjs"
+ config_path.write_text(f"export default {json.dumps(config)}\n", encoding="utf-8")
+ return config_path
+
+
+def build_cmd(target: str, *, device: str, out_dir: Path, config_path: Path) -> list[str]:
+ """Build the unlighthouse-ci argv. Every flag here is documented in
+ ``packages/cli/src/createCli.ts`` and ``packages/cli/src/ci.ts`` upstream.
+ """
+ return [
+ "npx", "--yes", "--package", UNLIGHTHOUSE_PIN, "unlighthouse-ci",
+ "--site", target,
+ "--device", device,
+ "--output-path", str(out_dir),
+ "--config-file", str(config_path),
+ # The real flag is `--build-static` (ci.ts); the CLI declares it
+ # with a required value placeholder, so pass it explicitly.
+ "--build-static", "true",
+ ]
+
+
+def _route_scores(route: dict[str, Any]) -> dict[str, float]:
+ """Extract per-category numeric scores from one route result.
+
+ Handles both reporter shapes:
+ - jsonSimple/json (the CLI default): flat numeric keys alongside
+ `path`, e.g. {"path": "/", "score": 0.9, "performance": 0.9, ...}.
+ - jsonExpanded: nested {"categories": {key: {"score": 0.9, ...}}}.
+ """
+ scores: dict[str, float] = {}
+ categories = route.get("categories")
+ if isinstance(categories, dict):
+ for key, cat in categories.items():
+ if isinstance(cat, dict) and isinstance(cat.get("score"), (int, float)):
+ scores[key] = float(cat["score"])
+ for key, value in route.items():
+ if key in _NON_CATEGORY_NUMERIC_KEYS or key in ("categories", "metrics", "path"):
+ continue
+ if isinstance(value, bool):
+ continue
+ if isinstance(value, (int, float)):
+ scores[key] = float(value)
+ return scores
+
+
+def normalize_ci_result(data: Any) -> dict[str, Any]:
+ """Normalize a parsed ``ci-result.json`` payload into a stable shape.
+
+ The default unlighthouse-ci reporter (``jsonSimple``, used whenever
+ ``--reporter`` isn't passed) writes the file as a flat JSON ARRAY of
+ per-route dicts, not an object. A ``jsonExpanded`` reporter instead
+ writes ``{"summary": ..., "routes": [...], "metadata": ...}``. Both
+ shapes are accepted; anything else degrades to an empty route list
+ rather than raising.
+ """
+ if isinstance(data, list):
+ routes = [r for r in data if isinstance(r, dict)]
+ elif isinstance(data, dict):
+ candidate = data.get("routes")
+ routes = [r for r in candidate if isinstance(r, dict)] if isinstance(candidate, list) else []
+ else:
+ routes = []
+
+ per_category: dict[str, list[float]] = {}
+ for route in routes:
+ for key, value in _route_scores(route).items():
+ per_category.setdefault(key, []).append(value)
+
+ aggregate_scores = {
+ key: round(statistics.median(values), 4)
+ for key, values in per_category.items()
+ if values
+ }
+
+ return {
+ "routes": routes,
+ "route_count": len(routes),
+ "aggregate_scores": aggregate_scores,
+ }
+
+
def run(
target: str,
*,
@@ -63,6 +189,7 @@ def run(
max_routes: int | None = 200,
output_dir: str | None = None,
timeout: int = 600,
+ page_timeout: int = 60,
) -> dict:
try:
target, _ = validate_url_strict(target)
@@ -77,16 +204,9 @@ def run(
prefix="claude-seo-unlighthouse-"))
out_dir.mkdir(parents=True, exist_ok=True)
- cmd = [
- "npx", "--yes", "--package", UNLIGHTHOUSE_PIN, "unlighthouse-ci",
- "--site", target,
- "--device", device,
- "--output-path", str(out_dir),
- # Reasonable defaults for a one-shot audit; callers can override.
- "--build-static-files",
- ]
- if max_routes is not None:
- cmd.extend(["--scanner", json.dumps({"maxRoutes": max_routes})])
+ config = build_config(max_routes, page_timeout * 1000)
+ config_path = write_config_file(out_dir, config)
+ cmd = build_cmd(target, device=device, out_dir=out_dir, config_path=config_path)
try:
proc = subprocess.run(
@@ -105,20 +225,25 @@ def run(
return {"ok": False, "error": f"npx invocation failed: {exc}"}
summary_path = out_dir / "ci-result.json"
- summary: dict = {}
+ normalized: dict[str, Any] = {"routes": [], "route_count": 0, "aggregate_scores": {}}
+ raw_summary: Any = None
if summary_path.is_file():
try:
- summary = json.loads(summary_path.read_text(encoding="utf-8"))
+ raw_summary = json.loads(summary_path.read_text(encoding="utf-8"))
except json.JSONDecodeError as exc:
return {"ok": False, "error": f"ci-result.json invalid JSON: {exc}",
"output_dir": str(out_dir)}
+ normalized = normalize_ci_result(raw_summary)
return {
"ok": proc.returncode == 0,
"exit_code": proc.returncode,
"target": target,
"output_dir": str(out_dir),
- "summary": summary,
+ "summary": raw_summary,
+ "routes": normalized["routes"],
+ "route_count": normalized["route_count"],
+ "aggregate_scores": normalized["aggregate_scores"],
"stdout_tail": proc.stdout[-2000:] if proc.stdout else "",
"stderr_tail": proc.stderr[-2000:] if proc.stderr else "",
}
@@ -141,7 +266,12 @@ def main() -> int:
)
parser.add_argument(
"--timeout", type=int, default=600,
- help="Subprocess timeout in seconds (default 600).",
+ help="Overall subprocess timeout in seconds (default 600).",
+ )
+ parser.add_argument(
+ "--page-timeout", type=int, default=60,
+ help="Per-page Lighthouse task timeout in seconds (default 60). Guards "
+ "against one hung page stalling the whole crawl.",
)
parser.add_argument("--json", action="store_true")
args = parser.parse_args()
@@ -152,6 +282,7 @@ def main() -> int:
max_routes=args.max_routes,
output_dir=args.output_dir,
timeout=args.timeout,
+ page_timeout=args.page_timeout,
)
if args.json:
@@ -164,11 +295,10 @@ def main() -> int:
print(f" Output dir: {result.get('output_dir')}")
if result.get("error"):
print(f" Error: {result['error']}")
- elif result.get("summary"):
- scores = result["summary"].get("scores") or result["summary"].get("score") or {}
- if scores:
- for k, v in scores.items():
- print(f" {k:14s} {v}")
+ else:
+ print(f" Routes: {result.get('route_count', 0)}")
+ for k, v in (result.get("aggregate_scores") or {}).items():
+ print(f" {k:14s} {v}")
return 0 if result["ok"] else 1
diff --git a/tests/test_unlighthouse_run.py b/tests/test_unlighthouse_run.py
new file mode 100644
index 0000000..1d823a9
--- /dev/null
+++ b/tests/test_unlighthouse_run.py
@@ -0,0 +1,168 @@
+"""Unlighthouse extension regressions (issue #189).
+
+Three confirmed bugs in scripts/unlighthouse_run.py and
+extensions/unlighthouse/install.sh:
+
+(a) ``--max-routes`` was forwarded as ``--scanner '{"maxRoutes": N}'``, a
+ made-up CLI flag unlighthouse-ci's cac-based parser never reads
+ (confirmed against packages/cli/src/{createCli,ci,util}.ts upstream).
+ The only documented way to reach ``scanner.maxRoutes`` is
+ ``--config-file <path>`` pointing at a config module. No per-page
+ timeout guard existed at all.
+(b) ``ci-result.json`` was parsed assuming a dict; the default
+ ``jsonSimple`` reporter (used whenever ``--reporter`` isn't passed)
+ writes a flat JSON array of per-route results instead.
+(c) install.sh required ``~/.claude/skills/seo`` to exist, which is never
+ true for a marketplace/plugin install, so the installer always
+ aborted in that path.
+
+These tests exercise the pure argument-builder and JSON-normalization
+functions directly with fixture data: no network, no unlighthouse install,
+no subprocess execution.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "scripts"))
+
+import unlighthouse_run as ul # noqa: E402
+
+# --------------------------------------------------------------------------
+# (a) config / argument builder
+# --------------------------------------------------------------------------
+
+
+def test_build_config_sets_scanner_max_routes_as_number():
+ config = ul.build_config(50, 60_000)
+ assert config["scanner"]["maxRoutes"] == 50
+ assert config["puppeteerClusterOptions"]["timeout"] == 60_000
+
+
+def test_build_config_none_max_routes_maps_to_false_unlimited():
+ config = ul.build_config(None, 30_000)
+ assert config["scanner"]["maxRoutes"] is False
+
+
+def test_write_config_file_emits_valid_esm_default_export(tmp_path):
+ config = ul.build_config(25, 45_000)
+ path = ul.write_config_file(tmp_path, config)
+ assert path.name == "unlighthouse.config.mjs"
+ text = path.read_text(encoding="utf-8")
+ assert text.startswith("export default ")
+ payload = json.loads(text.removeprefix("export default ").strip())
+ assert payload == config
+
+
+def test_build_cmd_never_uses_the_ignored_scanner_json_flag(tmp_path):
+ config_path = tmp_path / "unlighthouse.config.mjs"
+ cmd = ul.build_cmd(
+ "https://example.com", device="mobile", out_dir=tmp_path, config_path=config_path,
+ )
+ assert "--scanner" not in cmd
+ assert "--max-routes" not in cmd
+
+
+def test_build_cmd_passes_config_file_and_documented_flags(tmp_path):
+ config_path = tmp_path / "unlighthouse.config.mjs"
+ cmd = ul.build_cmd(
+ "https://example.com", device="desktop", out_dir=tmp_path, config_path=config_path,
+ )
+ assert cmd[0:2] == ["npx", "--yes"]
+ assert "--site" in cmd and "https://example.com" in cmd
+ assert "--device" in cmd and "desktop" in cmd
+ assert "--config-file" in cmd
+ assert str(config_path) in cmd
+ assert "--output-path" in cmd and str(tmp_path) in cmd
+ # The real CLI flag (packages/cli/src/ci.ts) is `--build-static`, not
+ # the nonexistent `--build-static-files` the old code passed.
+ assert "--build-static" in cmd
+ assert "--build-static-files" not in cmd
+
+
+# --------------------------------------------------------------------------
+# (b) ci-result.json shape handling
+# --------------------------------------------------------------------------
+
+JSON_SIMPLE_FIXTURE = [
+ {"path": "/", "score": 0.92, "performance": 0.9, "accessibility": 0.95,
+ "best-practices": 1.0, "seo": 0.88},
+ {"path": "/about", "score": 0.80, "performance": 0.7, "accessibility": 0.9,
+ "best-practices": 0.92, "seo": 0.85},
+]
+
+JSON_EXPANDED_FIXTURE = {
+ "summary": {"score": 0.86},
+ "routes": [
+ {
+ "path": "/",
+ "score": 0.92,
+ "categories": {
+ "performance": {"key": "performance", "score": 0.9},
+ "accessibility": {"key": "accessibility", "score": 0.95},
+ "best-practices": {"key": "best-practices", "score": 1.0},
+ "seo": {"key": "seo", "score": 0.88},
+ },
+ "metrics": {},
+ },
+ {
+ "path": "/about",
+ "score": 0.80,
+ "categories": {
+ "performance": {"key": "performance", "score": 0.7},
+ "accessibility": {"key": "accessibility", "score": 0.9},
+ "best-practices": {"key": "best-practices", "score": 0.92},
+ "seo": {"key": "seo", "score": 0.85},
+ },
+ "metrics": {},
+ },
+ ],
+ "metadata": {},
+}
+
+
+def test_normalize_handles_default_jsonsimple_array_shape():
+ normalized = ul.normalize_ci_result(JSON_SIMPLE_FIXTURE)
+ assert normalized["route_count"] == 2
+ assert normalized["routes"] == JSON_SIMPLE_FIXTURE
+ assert normalized["aggregate_scores"]["performance"] == 0.8
+ assert normalized["aggregate_scores"]["accessibility"] == pytest.approx(0.925)
+ assert normalized["aggregate_scores"]["seo"] == pytest.approx(0.865)
+
+
+def test_normalize_falls_back_to_object_shape_with_routes_key():
+ normalized = ul.normalize_ci_result(JSON_EXPANDED_FIXTURE)
+ assert normalized["route_count"] == 2
+ assert normalized["aggregate_scores"]["performance"] == 0.8
+ assert normalized["aggregate_scores"]["accessibility"] == pytest.approx(0.925)
+
+
+def test_normalize_tolerates_garbage_input():
+ assert ul.normalize_ci_result(None) == {
+ "routes": [], "route_count": 0, "aggregate_scores": {},
+ }
+ assert ul.normalize_ci_result({"unexpected": "shape"}) == {
+ "routes": [], "route_count": 0, "aggregate_scores": {},
+ }
+ assert ul.normalize_ci_result([1, 2, "not-a-dict"]) == {
+ "routes": [], "route_count": 0, "aggregate_scores": {},
+ }
+
+
+# --------------------------------------------------------------------------
+# (c) installer no longer hard-requires the manual skill directory
+# --------------------------------------------------------------------------
+
+
+def test_installer_detects_plugin_install_paths():
+ text = (ROOT / "extensions" / "unlighthouse" / "install.sh").read_text(encoding="utf-8")
+ assert "CLAUDE_PLUGIN_ROOT" in text
+ assert "plugins/cache" in text
+ # The old unconditional abort before any plugin-path check is gone.
+ assert '[ ! -d "${SKILL_DIR}/seo" ] && { echo "✗ claude-seo base not installed."; exit 1; }' not in text