snapdrift 0.4.0 → 0.5.0

package/docs/integration-guide.md

@@ -46,13 +46,13 @@ SnapDrift owns route selection, capture, comparison, skipped-report generation,
 
 ```yaml
 - name: SnapDrift Baseline
-  uses: ranacseruet/snapdrift/actions/baseline@v0.2.1
+  uses: ranacseruet/snapdrift/actions/baseline@v0.4.0
   with:
     repo-config-path: .github/snapdrift.json
     artifact-retention-days: '30'
 ```
 
-If you want only part of the route set, pass `route-ids`.
+If you want only part of the route set, pass `route-ids`. If you don't want to upload the artifact (for example when using the Snap provider, which uploads via its own API), set `upload-artifact: 'false'`.
 
 ## Step 3: Run the pull request report
 
@@ -70,7 +70,7 @@ Then add SnapDrift after the app is running:
 
 ```yaml
 - name: SnapDrift Report
-  uses: ranacseruet/snapdrift/actions/pr-diff@v0.2.1
+  uses: ranacseruet/snapdrift/actions/pr-diff@v0.4.0
   with:
     github-token: ${{ secrets.GITHUB_TOKEN }}
     repo-config-path: .github/snapdrift.json
@@ -111,7 +111,7 @@ jobs:
           done
 
       - name: SnapDrift Report
-        uses: ranacseruet/snapdrift/actions/pr-diff@v0.2.1
+        uses: ranacseruet/snapdrift/actions/pr-diff@v0.4.0
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           repo-config-path: .github/snapdrift.json
@@ -150,7 +150,7 @@ jobs:
           done
 
       - name: SnapDrift Report
-        uses: ranacseruet/snapdrift/actions/pr-diff@v0.2.1
+        uses: ranacseruet/snapdrift/actions/pr-diff@v0.4.0
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           repo-config-path: .github/snapdrift.json
@@ -169,33 +169,89 @@ jobs:
 
 ## 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 |
-| `max-changed-rows` | Max changed-route rows shown before truncation (default: `20`) |
-| `max-error-rows` | Max error rows shown before truncation (default: `10`) |
+| Input | Default | Purpose |
+|-------|---------|---------|
+| `repo-config-path` | `.github/snapdrift.json` | Override the config file path |
+| `pr-number` | inferred from event | Explicit PR number override |
+| `route-ids` | scope-derived | Bypass scope detection and capture named routes (comma-separated) |
+| `force-run` | `false` | Run the full route set instead of using changed-file scope |
+| `force-run-reason` | `forced` | Reason string emitted to scope outputs when `force-run: true` |
+| `baseline-repository` | current repo | Read baselines from another repo (`owner/name`) |
+| `baseline-workflow-id` | `ci.yml` | Override the baseline workflow id or filename |
+| `baseline-branch` | `main` | Override the branch the baseline was published from |
+| `artifact-retention-days` | `30` | Retention period for the uploaded diff artifact |
+| `comment-on-pr` | `true` | Set to `false` to suppress the PR report upsert |
+| `max-changed-rows` | `20` | Max changed-route rows shown in the PR comment before truncation |
+| `max-error-rows` | `10` | Max error rows shown in the PR comment before truncation |
+
+The `pr-diff` action also exposes outputs you can use in subsequent steps: `should-run`, `scope-reason`, `selected-route-ids`, `baseline-found`, `status`, `summary-path`, `markdown-path`, `artifact-name`, `bundle-dir`. See the wrapper action's `outputs:` block for the canonical list.
+
+## Hosted Snap provider
+
+By default SnapDrift writes baselines and reports to the runner filesystem (`provider: "local"`). For a hosted backend with a shared baseline store and a run-detail dashboard, configure `provider: "snap"` in `snapdrift.json`:
+
+```json
+{
+  "provider": "snap",
+  "snap": {
+    "apiKeyEnv": "SNAP_API_KEY",
+    "projectId": "auto",
+    "onUnavailable": "fail"
+  }
+}
+```
+
+- `apiKeyEnv` — name of an environment variable holding the Snap API key. Mutually exclusive with `apiKey`. Exactly one of `apiKeyEnv` or `apiKey` is required.
+- `apiKey` — inline API key with `${VAR}` interpolation (e.g. `"${SNAP_API_KEY}"`). Mutually exclusive with `apiKeyEnv`.
+- `projectId` — Snap project id, or `"auto"` to derive it from `GITHUB_REPOSITORY` (default).
+- `onUnavailable` — behavior when the Snap API cannot be reached:
+  - `"fail"` (default) — fail the action with a non-retryable error.
+  - `"warn-and-skip"` — log a warning, write a skipped summary, and exit 0.
+  - `"fallback-local"` — log a warning and run the rest of the pipeline with `LocalProvider`.
+
+The Snap API client retries 5xx and network errors with exponential backoff (3 attempts, 1 s → 2 s → 4 s, capped at 30 s). 4xx errors never retry and never fall back.
+
+When `provider: "snap"` and `baseUrl` points to a local address (localhost, `127.0.0.0/8`, `::1`, or `0.0.0.0`), SnapDrift uses a **local-capture hybrid**: Playwright runs on the runner to render the page, then SnapDrift uploads the resulting screenshots to Snap. This makes it possible to point SnapDrift at a server that only the runner can reach (a typical case) without exposing the server to Snap's render worker.
+
+With the Snap provider, the PR comment includes a **"View in dashboard →"** link that points to `${apiUrl}/dashboard/visual/${projectId}/runs/${runId}`. The local provider omits the link.
+
+Migrating an existing local repo to the Snap provider is a one-shot CLI command:
+
+```bash
+snapdrift migrate-baselines --to snap
+```
+
+Conversely, downloading a Snap baseline back to a local directory (useful for reproducible local debugging) is:
+
+```bash
+snapdrift migrate-baselines --to local --from snap
+```
+
+The reverse direction requires the Snap export endpoint to be available; if it isn't, the command fails with an actionable error. See the [Contracts reference](contracts.md#migration-commands) for the full flag set, the engine-compatibility check, and the metadata file written for idempotency.
+
+If you're adopting SnapDrift as a replacement for the upstream `snap/github-action`, the `init` codemod translates the workflow YAML and emits a `MIGRATION_NOTES.md` with everything that couldn't be auto-translated:
+
+```bash
+snapdrift init --from-snap-action .github/workflows/snap.yml
+```
 
 ## Low-level actions
 
-For custom orchestration:
+The `pr-diff` wrapper composes the following low-level steps. They're still available for custom orchestration but most consumers don't need to reach for them:
 
-- `actions/capture`
-- `actions/compare`
-- `actions/scope`
-- `actions/enforce`
-- `actions/comment`
-- `actions/resolve-baseline`
-- `actions/stage`
+- `actions/capture` — capture routes and emit `results.json` + `manifest.json`
+- `actions/compare` — diff current capture against a baseline
+- `actions/scope` — decide whether to run and which routes to select from changed files
+- `actions/resolve-baseline` — find and download the latest successful baseline artifact
+- `actions/stage` — assemble the baseline or diff bundle for upload
+- `actions/enforce` — evaluate the summary against `diff.mode` and fail when required
+- `actions/comment` — upsert a PR comment from a summary (provider-aware)
+
+The two wrapper actions that orchestrate the full pipeline are `actions/baseline` (publish) and `actions/pr-diff` (drift detection). They are the primary integration points.
 
 ## 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.
+The `snapdrift` CLI lets you run captures, diffs, migrations, and config initialization 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
@@ -203,6 +259,12 @@ snapdrift capture
 
 # After making changes, compare and open the HTML report
 snapdrift diff --open
+
+# Migrate an established local baseline to the hosted Snap backend
+snapdrift migrate-baselines --to snap
+
+# Translate a snap/github-action workflow into snapdrift.json
+snapdrift init --from-snap-action .github/workflows/snap.yml
 ```
 
 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`.
@@ -226,13 +288,19 @@ If you don't want to republish the baseline on every push, the template includes
 ## Troubleshooting
 
 **"No non-expired SnapDrift baseline artifact was found"**  
-The baseline workflow has not completed successfully on `main`, or the artifact expired.
+The baseline workflow has not completed successfully on `main`, or the artifact expired. With the Snap provider, the equivalent situation is a 404 from `/v1/visual/projects/:id/baselines/latest`; `SnapProvider` swallows that 404 and proceeds without a baseline — `onUnavailable` is **not** consulted for this case (a 404 is the legitimate "no baseline yet" signal, not a Snap outage). If you want the PR pipeline to tolerate the first-run case, set `diff.mode: "report-only"`; `onUnavailable: "warn-and-skip"` will not help here.
 
 **403 when posting the PR report**  
 Grant `issues: write` and `pull-requests: write` to the job.
 
+**Snap API request keeps failing with 4xx**  
+The Snap client never retries 4xx and never falls back, even when `onUnavailable` is set. Inspect the response body — the most common cause is a project-id mismatch between `GITHUB_REPOSITORY` (auto-derived) and the project's id on Snap.
+
 **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.
+
+**Playwright install runs even though `provider: "snap"`**  
+That's expected for the Snap local-capture hybrid. Playwright runs locally to render the page, then the resulting screenshot is uploaded to Snap. The hybrid kicks in only when `baseUrl` points to a local address; for remote `baseUrl` Snap's render worker captures directly.

package/docs/local-cli.md

@@ -80,6 +80,75 @@ snapdrift diff --baseline-dir snapshots/baseline --diff-dir snapshots/diff
 
 ---
 
+### `snapdrift migrate-baselines`
+
+Move baselines between the local filesystem and the hosted Snap backend. Requires a config with `provider: "snap"` (or a `snap` block) for the direction being targeted.
+
+**Upload local baselines to Snap:**
+
+```bash
+snapdrift migrate-baselines --to snap
+```
+
+Reads `results.json`, `manifest.json`, and `screenshots/*.png` from the local baseline directory, then POSTs them to Snap as the initial accepted baseline for the current commit. Idempotent: if a baseline already exists for the same commit SHA the upload is skipped.
+
+**Download Snap baselines to a local directory:**
+
+```bash
+snapdrift migrate-baselines --to local --from snap
+```
+
+Snap must expose its export endpoint for this direction to succeed. If it doesn't, the command fails with an actionable error. By default the engine name on the exported manifest must be `snapdrift-local`; pass `--accept-cross-engine` to override the engine name in the imported manifest (visual differences may occur).
+
+**Options**
+
+| Flag | Default | Description |
+|:-----|:--------|:------------|
+| `--to <snap\|local>` | — | Migration target (required) |
+| `--from <snap>` | — | Migration source (required when `--to local`) |
+| `--accept-cross-engine` | off | Override the engine-name check when importing from Snap |
+| `--config <path>` | `.github/snapdrift.json` | Path to the config file |
+| `--baseline-dir <path>` | `.snapdrift/baseline` | Local baseline directory to read from or write to |
+
+**Side effects**
+
+A `.migration-metadata.json` file is written next to the local baseline after a successful download — it records the source engine, the migration timestamp, and a stable id used for idempotency on re-runs.
+
+---
+
+### `snapdrift init`
+
+Translate an existing `snap/github-action` workflow into `snapdrift.json` with `provider: "snap"`. Use this when migrating an existing consumer repo from the upstream Snap action to SnapDrift.
+
+```
+snapdrift init --from-snap-action <workflow-yaml-path>
+```
+
+Reads the workflow YAML, locates the step that uses the Snap action, and translates its inputs:
+
+| Snap action input | snapdrift config |
+|:------------------|:-----------------|
+| `threshold` / `diff-threshold` | `diff.threshold` |
+| `fail-on-changes` | `diff.mode` (`"fail-on-changes"`) |
+| `fail-on-incomplete` | `diff.mode` (`"fail-on-incomplete"`) |
+| (none of the above) | `diff.mode` (`"report-only"`) |
+| `snap-api-key-env` | `snap.apiKeyEnv` |
+| `snap-api-url` | `snap.apiUrl` |
+| `snap-project-id` | `snap.projectId` |
+| `format` | (warning — PNG-only, format dropped) |
+| `baseline_tag` | (warning — commit-based only) |
+| `routes` / page list | (warning — fill in `routes[]` manually) |
+| `baseUrl` | placeholder `http://localhost:3000` (warning — update to your real app) |
+
+The codemod writes two files:
+
+- `.github/snapdrift.json` — the translated config
+- `.github/MIGRATION_NOTES.md` — every warning and deferred decision, grouped by severity
+
+The command is **idempotent against `snapdrift.json`**: if the file already exists, the command refuses to overwrite and tells you to remove it manually.
+
+---
+
 ## Typical local workflow
 
 ```bash
@@ -131,8 +200,8 @@ Add `.snapdrift/` to your `.gitignore` to keep local run output out of version c
 
 | 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)) |
+| `0` | Clean — no drift above threshold, `diff.mode` is `report-only`, the diff was intentionally skipped (e.g. `SnapSkipError` from `onUnavailable: "warn-and-skip"`), or the command was a `capture` / `migrate-baselines` / `init` that completed |
+| `1` | Drift enforced — `diff.mode` caused the run to fail, a required command argument was missing, or the `--to local` engine-name check failed (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.
 
@@ -140,7 +209,9 @@ Enforcement follows the same `diff.mode` rules as the GitHub Actions workflow. S
 
 ## Console output
 
-`snapdrift diff` prints a summary to stdout:
+`snapdrift diff` prints a summary to stdout.
+
+**Clean run:**
 
 ```
 Capturing current screenshots to .snapdrift/current ...
@@ -151,7 +222,7 @@ Comparing against baseline ...
    Matched:  2
 ```
 
-When drift is detected:
+**Drift detected** (one or more routes changed):
 
 ```
 🟡  SnapDrift — Drift detected
@@ -165,6 +236,36 @@ When drift is detected:
 Report: .snapdrift/diff/report.html
 ```
 
+**Incomplete run** (errors, missing captures, or dimension shifts):
+
+```
+❌  SnapDrift — incomplete
+   Routes:   4
+   Matched:   2
+   Changed:   0
+   Missing:   1
+   Errors:    1
+   Dim diff:  1
+
+Report: .snapdrift/diff/report.html
+```
+
+The `Missing`, `Errors`, and `Dim diff` lines only print when their count is greater than zero. `summary.status` is the unstyled value from the run (`clean`, `changes-detected`, `incomplete`, or `skipped`).
+
+The `report.html` path is printed whenever the status is anything other than `clean`; pass `--open` to also launch it in your default browser.
+
+---
+
+## Environment variables
+
+| Variable | Applies to | Description |
+|:---------|:-----------|:------------|
+| `SNAPDRIFT_CAPTURE_CONCURRENCY` | `capture`, `diff` | Max concurrent route captures per viewport context (positive integer, default `5`). Set to `1` to restore serial behavior for apps with shared session or auth state. |
+| `SNAPDRIFT_CONFIG_PATH` | `capture`, `diff`, `migrate-baselines` | Override the config file path. Equivalent to `--config`. |
+| `SNAPDRIFT_ROUTE_IDS` | `capture`, `diff` | Comma-separated route ids to scope to. Equivalent to `--routes`. |
+
+`SNAPDRIFT_CAPTURE_CONCURRENCY` is the same env var consumed by the GitHub Actions wrapper; tweak it the same way for both environments.
+
 ---
 
 ## Tips
@@ -172,3 +273,5 @@ Report: .snapdrift/diff/report.html
 - **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.
+- **Self-contained HTML report**: `report.html` embeds baseline, current, and diff images as base64. Open it from any machine — no server required, and no relative-path resolution surprises. (The HTML report is a local-CLI feature; the GitHub Actions wrapper ships only `summary.json` + `summary.md` in its artifact bundle.)
+- **Provider-aware behavior**: with `provider: "snap"`, the `capture` and `diff` commands will hit the Snap API. The `--open` flag still opens the locally generated `report.html`; the Snap dashboard link lives in the PR comment, not the local output.

package/docs/workflow-templates/refresh-baseline-on-merge.yml

@@ -70,7 +70,7 @@ jobs:
       # ────────────────────────────────────────────────────────────────────────
 
       - name: Publish SnapDrift baseline
-        uses: ranacseruet/snapdrift/actions/baseline@v0.2.1
+        uses: ranacseruet/snapdrift/actions/baseline@v0.4.0
         with:
           repo-config-path: .github/snapdrift.json
           artifact-retention-days: '30'

package/lib/cli.mjs

@@ -185,7 +185,8 @@ export async function runCaptureCommand(opts) {
     const { selectedRouteIds } = await provider.capture({
       configPath: opts.configPath,
       routeIds: opts.routes.length > 0 ? opts.routes : undefined,
-      outDir: opts.baselineDir
+      outDir: opts.baselineDir,
+      purpose: 'baseline'
     });
     process.stdout.write(`Captured ${selectedRouteIds.length} route(s) to ${opts.baselineDir}\n`);
   } catch (error) {

package/lib/provider.mjs

@@ -2,7 +2,7 @@
 
 import { runBaselineCapture, generateDriftReport, stageArtifacts } from '@snapdrift/adapter-fs';
 import { buildReportCommentBody } from '@snapdrift/adapter-report-md';
-import { SnapProvider, SnapApiError, SnapUnavailableError, SnapFallbackError, SnapSkipError } from './snap-provider.mjs';
+import { SnapProvider, SnapApiError, SnapUnavailableError, SnapFallbackError, SnapSkipError, isLocalBaseUrl } from './snap-provider.mjs';
 
 /** @typedef {import('../types/visual-diff-types').VisualProvider} VisualProvider */
 /** @typedef {import('../types/visual-diff-types').ProviderCaptureOptions} CaptureOptions */
@@ -103,4 +103,4 @@ export function createProvider(providerName, config) {
   return factory(config);
 }
 
-export { SnapProvider, SnapApiError, SnapUnavailableError, SnapFallbackError, SnapSkipError };
+export { SnapProvider, SnapApiError, SnapUnavailableError, SnapFallbackError, SnapSkipError, isLocalBaseUrl };