website-evaluator/CLAUDE.md

CLAUDE.md — website-evaluator

Overview

A Docker-based website audit pipeline. Given a URL it runs screenshots (Playwright), Lighthouse audits (desktop + mobile), and DOM analysis, then assembles a structured Markdown report optimised for consumption by Claude.

Repository Structure

website-evaluator/
├── ABOUT.md               # One-line description for context-load menu
├── CLAUDE.md              # This file
├── MEMORY.md              # Index of memory topic files
├── FUTURE.md              # Ideas not on the active roadmap
├── README.md              # Human-readable overview and quick start
├── SPEC.md                # Index of spec files
├── spec/                  # Per-subsystem specs (WE-P, WE-S, WE-L, WE-D, WE-R)
├── src/
│   ├── index.js           # Entrypoint — arg parsing and pipeline orchestration
│   ├── screenshot.js      # Playwright screenshot capture (desktop + mobile)
│   ├── lighthouse.js      # Lighthouse audit runner (desktop + mobile presets)
│   ├── dom-analysis.js    # DOM metadata extraction via Playwright
│   └── report.js          # Markdown report assembly
├── Dockerfile             # Node 20 + Playwright base image
├── .dockerignore
├── package.json
└── scripts/
    └── verify-m1.sh       # Smoke test: run against example.com, check outputs

Tech Stack

• Runtime: Node.js 20, ES modules (type: "module")
• Screenshots + DOM: Playwright (Chromium)
• Audits: Lighthouse 12 + chrome-launcher (uses Playwright's bundled Chromium)
• Base image: mcr.microsoft.com/playwright/node:20-noble

Running Locally (Docker)

# Build
docker build -t website-evaluator .

# Run — output lands in ./output/
mkdir -p output
docker run --rm -v "$(pwd)/output:/output" website-evaluator https://example.com

# Output
output/
  report.md                # Primary artifact — feed this to Claude
  screenshots/
    desktop.png
    mobile.png
  raw/
    lighthouse-desktop.json
    lighthouse-mobile.json
    dom.json

Environment Variables

Variable	Default	Purpose
OUTPUT_DIR	/output	Where to write all output files

URL is passed as a CLI argument. TARGET_URL env var is also accepted as fallback.

Spec Prefixes

Spec file	Prefix	Domain
pipeline.md	WE-P	Orchestration + I/O contract
screenshot.md	WE-S	Screenshot capture
lighthouse.md	WE-L	Lighthouse audit
dom-analysis.md	WE-D	DOM metadata extraction
report.md	WE-R	Report structure + tone

Conventions

• ES modules throughout (import/export, .js extensions in imports)
• Async/await — no callbacks
• Each module exports one primary function; no side effects at import time
• Errors propagate to index.js which handles process exit
• console.log for progress, console.error for failures

Milestones

#	Scope	Status
M1	Core pipeline: screenshot + Lighthouse + DOM → report.md	In progress
M2	--analyze flag: calls Claude API, appends AI recommendations	Future
M3	Comparison mode: before/after and competitor diffs	Future

Gitea

• Org: skynet
• Remote: git@gitea.oreillyit.nz-ai-enablement:skynet/website-evaluator.git