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.mdindex 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.0follow. `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### Securitydiff --git a/extensions/unlighthouse/install.sh b/extensions/unlighthouse/install.shindex 71b3bce..908ec31 100755--- a/extensions/unlighthouse/install.sh+++ b/extensions/unlighthouse/install.sh@@ -8,6 +8,7 @@ set -euo pipefailmain() {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 || truediff --git a/extensions/unlighthouse/skills/seo-unlighthouse/SKILL.md b/extensions/unlighthouse/skills/seo-unlighthouse/SKILL.mdindex 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 delegationdiff --git a/scripts/unlighthouse_run.py b/scripts/unlighthouse_run.pyindex 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 argparseimport jsonimport osimport shutil+import statisticsimport subprocessimport sysimport tempfilefrom 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: E402UNLIGHTHOUSE_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 = Noneif 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 1diff --git a/tests/test_unlighthouse_run.py b/tests/test_unlighthouse_run.pynew file mode 100644index 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