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

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

spec/pipeline.md

@@ -0,0 +1,93 @@
+# Pipeline Spec (WE-P)
+
+## Overview
+
+Orchestrates the full evaluation pipeline for a single URL. Accepts a URL, runs
+screenshot capture, Lighthouse audits, and DOM analysis in sequence, writes all
+outputs to a configured directory, and exits with a clear success or failure code.
+
+## Responsibilities
+
+- Parse and validate input (URL + output directory)
+- Execute pipeline stages in order: screenshot → lighthouse → DOM → report
+- Write all output files to the configured output directory
+- Exit 0 on success, exit 1 on any stage failure (with error to stderr)
+
+Delegates to: `screenshot.js`, `lighthouse.js`, `dom-analysis.js`, `report.js`
+
+## Dependencies
+
+None — this is the root spec. All other specs depend on this one for the I/O contract.
+
+## Data Model
+
+### Input
+
+```
+CLI: node src/index.js <url>
+ENV: TARGET_URL=<url>         (fallback if no CLI arg)
+ENV: OUTPUT_DIR=/output       (default: /output)
+```
+
+### Output directory layout
+
+```
+$OUTPUT_DIR/
+  report.md                  ← primary artifact
+  screenshots/
+    desktop.png
+    mobile.png
+  raw/
+    lighthouse-desktop.json
+    lighthouse-mobile.json
+    dom.json
+```
+
+## Requirements
+
+**WE-P-1:** The URL must be provided as the first CLI argument or via `TARGET_URL`.
+If neither is present, print usage to stderr and exit 1.
+
+**WE-P-2:** The URL must start with `http://` or `https://`. If it does not, print
+an error and exit 1.
+Why: Lighthouse and Playwright both require a valid HTTP URL. Silent failures with
+invalid URLs are confusing.
+
+**WE-P-3:** The output directory (default `/output`) and its subdirectories
+(`screenshots/`, `raw/`) must be created if they do not exist.
+Why: The Docker volume mount only creates the parent; subdirs must be explicit.
+
+**WE-P-4:** Pipeline stages run sequentially in this order:
+1. Screenshots + DOM extraction (single Playwright browser session)
+2. Lighthouse desktop audit
+3. Lighthouse mobile audit
+4. Report assembly
+Why: Lighthouse requires its own Chrome instance. Running screenshots and DOM
+extraction first in a single Playwright session is more efficient than two sessions.
+
+**WE-P-5:** Each pipeline stage logs a single progress line to stdout before starting
+(e.g., `"Capturing screenshots..."`).
+
+**WE-P-6:** If any stage throws, the error message is printed to stderr and the
+process exits 1. Partial output files are acceptable — the caller should check
+exit code, not file presence.
+
+**WE-P-7:** On success, print the path to `report.md` and exit 0.
+
+## Scenarios
+
+### Scenario: Happy path
+**Given:** Valid URL `https://example.com` and writable `/output`
+**When:** Pipeline completes all stages
+**Then:** Exit 0; `report.md`, `screenshots/desktop.png`, `screenshots/mobile.png`,
+`raw/lighthouse-desktop.json`, `raw/lighthouse-mobile.json`, `raw/dom.json` all exist
+
+### Scenario: Missing URL
+**Given:** No CLI arg and `TARGET_URL` not set
+**When:** `index.js` starts
+**Then:** Prints usage to stderr, exits 1
+
+### Scenario: Invalid URL scheme
+**Given:** URL `file:///etc/passwd`
+**When:** Validation runs
+**Then:** Prints error "URL must start with http:// or https://", exits 1