M1: initial scaffold — pipeline, specs, source, Dockerfile

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-17 23:52:40 +12:00
commit 8584def154
22 changed files with 1413 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,99 @@
+# 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`