snapdrift 0.2.0

package/docs/integration-guide.md

@@ -0,0 +1,222 @@
+# Integration Guide
+
+This guide covers integrating SnapDrift into a consumer repository from a public GitHub release.
+
+Examples use the public release tag for readability. If your organization requires immutable pins, resolve the tag to a commit SHA and pin that instead.
+
+## Prerequisites
+
+- SnapDrift provisions Node 22 internally.
+- The consumer app can use any stack as long as it can be started and reached at `baseUrl`.
+- The runner must be Ubuntu-compatible because Playwright Chromium is installed with system dependencies.
+- The runner must have outbound network access to fetch Playwright Chromium.
+
+Your repository still owns:
+
+- Checkout
+- Dependency installation
+- App build
+- App startup and readiness
+- App shutdown
+
+SnapDrift owns route selection, capture, comparison, skipped-report generation, artifact staging, artifact upload, PR reporting, and drift enforcement.
+
+## Step 1: Add `.github/snapdrift.json`
+
+```json
+{
+  "baselineArtifactName": "my-app-snapdrift-baseline",
+  "workingDirectory": ".",
+  "baseUrl": "http://127.0.0.1:8080",
+  "resultsFile": "qa-artifacts/snapdrift/baseline/current/results.json",
+  "manifestFile": "qa-artifacts/snapdrift/baseline/current/manifest.json",
+  "screenshotsRoot": "qa-artifacts/snapdrift/baseline/current",
+  "routes": [
+    { "id": "home-desktop", "path": "/", "viewport": "desktop" },
+    { "id": "home-mobile", "path": "/", "viewport": "mobile" }
+  ],
+  "diff": {
+    "threshold": 0.01,
+    "mode": "report-only"
+  }
+}
+```
+
+## Step 2: Publish a baseline on `main`
+
+```yaml
+- name: SnapDrift Baseline
+  uses: ranacseruet/snapdrift/actions/baseline@v0.1.0
+  with:
+    repo-config-path: .github/snapdrift.json
+    artifact-retention-days: '30'
+```
+
+If you want only part of the route set, pass `route-ids`.
+
+## Step 3: Run the pull request report
+
+The PR workflow needs permission to download baselines and upsert the report comment:
+
+```yaml
+permissions:
+  contents: read
+  actions: read
+  issues: write
+  pull-requests: write
+```
+
+Then add SnapDrift after the app is running:
+
+```yaml
+- name: SnapDrift Report
+  uses: ranacseruet/snapdrift/actions/pr-diff@v0.1.0
+  with:
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+    repo-config-path: .github/snapdrift.json
+```
+
+## Example workflow (Node app)
+
+```yaml
+name: SnapDrift Pull Request
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+  actions: read
+  issues: write
+  pull-requests: write
+
+jobs:
+  snapdrift:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+
+      - name: Start app
+        run: |
+          npm start &
+          for i in $(seq 1 45); do
+            curl -sf http://127.0.0.1:8080 && break || sleep 1
+          done
+
+      - name: SnapDrift Report
+        uses: ranacseruet/snapdrift/actions/pr-diff@v0.1.0
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          repo-config-path: .github/snapdrift.json
+```
+
+## Example workflow (Python app)
+
+```yaml
+name: SnapDrift Pull Request
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+  actions: read
+  issues: write
+  pull-requests: write
+
+jobs:
+  snapdrift:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install -r requirements.txt
+
+      - name: Start app
+        run: |
+          gunicorn myapp:app --bind 127.0.0.1:8080 &
+          for i in $(seq 1 45); do
+            curl -sf http://127.0.0.1:8080 && break || sleep 1
+          done
+
+      - name: SnapDrift Report
+        uses: ranacseruet/snapdrift/actions/pr-diff@v0.1.0
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          repo-config-path: .github/snapdrift.json
+```
+
+## What the wrapper does
+
+- Resolves route scope unless `route-ids` is passed explicitly
+- Downloads the latest successful `main` baseline
+- Captures current frames
+- Writes a skipped report when scope is irrelevant or the baseline is missing
+- Stages and uploads the drift artifact
+- Publishes the workflow summary
+- Upserts the PR report
+- Enforces `diff.mode` after publication completes
+
+## Useful overrides
+
+| Input | Purpose |
+|-------|---------|
+| `pr-number` | Explicit PR number override |
+| `route-ids` | Bypass scope detection and capture named routes |
+| `force-run` | Run the full route set |
+| `baseline-repository` | Read baselines from another repo |
+| `baseline-workflow-id` | Override the baseline workflow id |
+| `baseline-branch` | Override the baseline branch |
+| `comment-on-pr` | Set to `false` to suppress the PR report |
+
+## Low-level actions
+
+For custom orchestration:
+
+- `actions/capture`
+- `actions/compare`
+- `actions/scope`
+- `actions/enforce`
+- `actions/comment`
+- `actions/resolve-baseline`
+- `actions/stage`
+
+## Local development
+
+The `snapdrift` CLI lets you run captures and diffs locally against a running app. Use it to validate UI changes on your machine before pushing — the same capture and comparison engine is used in both contexts.
+
+```bash
+# Establish a baseline before making UI changes
+snapdrift capture
+
+# After making changes, compare and open the HTML report
+snapdrift diff --open
+```
+
+The CLI reads the same `.github/snapdrift.json` config used by the Actions workflow. Local outputs land in `.snapdrift/` by default and can be overridden with `--baseline-dir`, `--current-dir`, and `--diff-dir`.
+
+See the [Local CLI guide](local-cli.md) for full command reference, flags, directory layout, and examples.
+
+## Troubleshooting
+
+**"No non-expired SnapDrift baseline artifact was found"**  
+The baseline workflow has not completed successfully on `main`, or the artifact expired.
+
+**403 when posting the PR report**  
+Grant `issues: write` and `pull-requests: write` to the job.
+
+**Screenshots have different dimensions**  
+SnapDrift reports this as a dimension shift and skips pixel comparison for that route. Refresh the baseline after the change lands.
+
+**A route appears in `errors[]`**  
+Capture failed before comparison. Confirm the app is fully ready and reachable before SnapDrift runs.

package/docs/local-cli.md

@@ -0,0 +1,174 @@
+# Local CLI
+
+The `snapdrift` CLI lets you run visual captures and diffs locally against a running app — no GitHub Actions required. Use it during development to validate UI changes before pushing.
+
+## Prerequisites
+
+- Node >= 22
+- A running app reachable at the `baseUrl` in your config
+- A `.github/snapdrift.json` config file (or pass `--config` to point to another path)
+
+## Installation
+
+The CLI ships with the `snapdrift` package. Install it globally or use `npx`:
+
+```bash
+# global
+npm install -g snapdrift
+
+# or without installing
+npx snapdrift <command>
+```
+
+## Commands
+
+### `snapdrift capture`
+
+Captures full-page screenshots of all configured routes and saves them as a local baseline.
+
+```
+snapdrift capture [options]
+```
+
+Run this once to establish the baseline before making UI changes.
+
+**Options**
+
+| Flag | Default | Description |
+|:-----|:--------|:------------|
+| `--config <path>` | `.github/snapdrift.json` | Path to the config file |
+| `--routes <ids>` | all routes | Comma-separated route IDs to capture |
+| `--baseline-dir <path>` | `.snapdrift/baseline` | Directory to write baseline screenshots and metadata |
+
+**Example**
+
+```bash
+snapdrift capture
+snapdrift capture --routes home-desktop,home-mobile
+snapdrift capture --baseline-dir snapshots/baseline
+```
+
+---
+
+### `snapdrift diff`
+
+Captures current screenshots, compares them against the local baseline, and writes a JSON summary, a markdown report, and a self-contained HTML report.
+
+```
+snapdrift diff [options]
+```
+
+**Options**
+
+| Flag | Default | Description |
+|:-----|:--------|:------------|
+| `--config <path>` | `.github/snapdrift.json` | Path to the config file |
+| `--routes <ids>` | all routes | Comma-separated route IDs to compare |
+| `--baseline-dir <path>` | `.snapdrift/baseline` | Directory containing the baseline |
+| `--current-dir <path>` | `.snapdrift/current` | Directory to write current screenshots |
+| `--diff-dir <path>` | `.snapdrift/diff` | Directory to write the diff report |
+| `--open` | off | Open the HTML report automatically after the diff |
+
+**Example**
+
+```bash
+snapdrift diff
+snapdrift diff --open
+snapdrift diff --routes home-desktop --open
+snapdrift diff --baseline-dir snapshots/baseline --diff-dir snapshots/diff
+```
+
+---
+
+## Typical local workflow
+
+```bash
+# 1. Start your app
+npm start
+
+# 2. Capture a baseline (once, before making changes)
+snapdrift capture
+
+# 3. Make your UI changes
+
+# 4. Run a diff to see what changed
+snapdrift diff --open
+```
+
+The `--open` flag opens the HTML report in your default browser when the diff is complete.
+
+---
+
+## Local directory layout
+
+After running `capture` and `diff` with default paths:
+
+```
+.snapdrift/
+  baseline/
+    results.json          # capture metadata (status, dimensions, timing)
+    manifest.json         # screenshot manifest (ids, paths, dimensions)
+    screenshots/
+      home-desktop.png
+      home-mobile.png
+  current/
+    results.json
+    manifest.json
+    screenshots/
+      home-desktop.png
+      home-mobile.png
+  diff/
+    summary.json          # structured drift summary
+    summary.md            # human-readable markdown report
+    report.html           # self-contained HTML report with side-by-side images
+```
+
+Add `.snapdrift/` to your `.gitignore` to keep local run output out of version control.
+
+---
+
+## Exit codes
+
+| Code | Meaning |
+|:-----|:--------|
+| `0` | Clean — no drift above threshold, or `diff.mode` is `report-only` |
+| `1` | Drift enforced — `diff.mode` caused the run to fail (see [Drift modes](../README.md#drift-modes)) |
+
+Enforcement follows the same `diff.mode` rules as the GitHub Actions workflow. Set `"mode": "report-only"` during local development to always get a report without a failing exit code.
+
+---
+
+## Console output
+
+`snapdrift diff` prints a summary to stdout:
+
+```
+Capturing current screenshots to .snapdrift/current ...
+Comparing against baseline ...
+
+✅  SnapDrift — Clean
+   Routes:   2
+   Matched:  2
+```
+
+When drift is detected:
+
+```
+🟡  SnapDrift — Drift detected
+   Routes:   3
+   Matched:  2
+   Changed:  1
+
+   Changed routes:
+     • home-desktop (2.47% diff)
+
+Report: .snapdrift/diff/report.html
+```
+
+---
+
+## Tips
+
+- **Partial runs**: use `--routes` to capture or compare only the routes you are actively changing.
+- **Multiple baselines**: use `--baseline-dir` to maintain separate baselines per branch or feature.
+- **CI parity**: the CLI uses the same capture and comparison engine as the GitHub Actions workflow, so results are comparable.