100 lines
3.4 KiB
Markdown
100 lines
3.4 KiB
Markdown
# 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)
|
|
|
|
```bash
|
|
# 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`
|