snapdrift 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -1,6 +1,14 @@
 # Changelog
 
-## Unreleased
+## 0.6.0 - 2026-07-17
+
+### Features
+
+- **`migrate-baselines --to local --from snap` is now functional** — `SnapProvider.exportBaselines` downloads the project's export archive from Snap's `GET /v1/visual/projects/:id/export` endpoint (requires an API key with the `visual:export` scope), parses the tar in pure JS, selects the most recent accepted baseline, and maps it back to the local baseline layout (`results.json`, `manifest.json`, `screenshots/<routeId>.png`). The imported engine name is passed through truthfully — baselines rendered by Snap's hosted worker report their own engine (falling back to `snap-hosted`) and require `--accept-cross-engine` to import, while baselines originally published by SnapDrift report `snapdrift-local` and import cleanly. Clear errors cover a missing `visual:export` scope (403), an unknown project (404), oversized exports (413), projects with no accepted baselines, and legacy baselines that predate manifest tracking. Previously this command failed with a "Snap export endpoint is not yet available" stub error.
+
+### Fixes
+
+- **Reject error pages during capture** — `runBaselineCapture` now checks the HTTP status of each route navigation and fails the route if it resolves to a 4xx/5xx. `page.goto` resolves even on a 404/500 (the error body still loads), so previously a broken route — wrong slug, misconfigured `baseUrl`, or an outage — would silently screenshot its error page and upload it as a valid baseline. The failure flows into the existing retry-then-fail path, so a genuinely broken capture now fails loudly instead of poisoning the baseline. Complements the 0% -drift heuristic guard from #93 with a direct status check. Redirects (3xx) still pass, since Playwright follows them and reports the final status; `null` responses (non-navigation schemes) are treated as fine.
 
 ## 0.5.1 - 2026-07-14
 

package/docs/contracts.md

@@ -272,12 +272,13 @@ snapdrift migrate-baselines --to snap [--config <path>] [--baseline-dir <dir>]
 snapdrift migrate-baselines --to local --from snap [--accept-cross-engine] [--config <path>] [--baseline-dir <dir>]
 ```
 
-- Downloads baselines from Snap's export endpoint.
-- Writes `results.json`, `manifest.json`, and `screenshots/*.png` to the local baseline directory.
+- Downloads the project's export archive from Snap's export endpoint (`GET /v1/visual/projects/:id/export`, a tar containing every accepted baseline's screenshots, capture profile, and source manifest). Requires an API key with the `visual:export` scope.
+- Imports the **most recent accepted baseline** (by `createdAt`) from the archive; older accepted baselines in the export are ignored.
+- Writes `results.json`, `manifest.json`, and `screenshots/*.png` to the local baseline directory. Screenshot filenames are derived from the baseline's route ids (`screenshots/<routeId>.png`), matching what a local capture would produce.
 - Writes `.migration-metadata.json` next to the baseline recording `source`, `migratedAt`, and the engine that produced the export.
-- Without `--accept-cross-engine`: hard-errors if the exported manifest's engine name is not `snapdrift-local`.
+- Without `--accept-cross-engine`: hard-errors if the exported baseline's engine name is not `snapdrift-local` (e.g. `snap-hosted` for baselines rendered by Snap's worker).
 - With `--accept-cross-engine`: overrides the engine name to `snapdrift-local` in the imported manifest (visual differences may occur when the captures came from a different engine).
-- Requires the Snap export endpoint to be available; if it is not yet wired up, the command fails with an actionable message instead of producing a partial baseline.
+- Fails with an actionable message — instead of producing a partial baseline — when the project has no accepted baselines, when the selected baseline predates manifest tracking (no source manifest recorded at publish time), when the key lacks the `visual:export` scope (403), or when the export exceeds Snap's size caps (413).
 
 ### init
 

package/docs/integration-guide.md

@@ -227,7 +227,7 @@ Conversely, downloading a Snap baseline back to a local directory (useful for re
 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.
+The reverse direction downloads the project's export archive from Snap (`GET /v1/visual/projects/:id/export`, which requires an API key with the `visual:export` scope) and imports the most recent accepted baseline into the local baseline directory. 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:
 

package/lib/snap-provider.mjs

@@ -9,7 +9,7 @@ import path from 'node:path';
 
 import { makeMarkdown, buildReportCommentBody } from '@snapdrift/adapter-report-md';
 import { loadSnapdriftConfig, runBaselineCapture } from '@snapdrift/adapter-fs';
-import { selectConfiguredRoutes, splitCommaList, determineDriftStatus, VIEWPORT_PRESETS } from '@snapdrift/manifest';
+import { selectConfiguredRoutes, splitCommaList, determineDriftStatus, VIEWPORT_PRESETS, viewportHash } from '@snapdrift/manifest';
 
 /** @typedef {import('../types/visual-diff-types').VisualProvider} VisualProvider */
 /** @typedef {import('../types/visual-diff-types').ProviderCaptureOptions} CaptureOptions */
@@ -85,6 +85,146 @@ function getPackageVersion() {
   }
 }
 
+const TAR_BLOCK_SIZE = 512;
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+/**
+ * Strips characters that could cause path traversal or produce invalid
+ * filenames when a route id is used as a screenshot filename. Mirrors the
+ * sanitisation applied by `@snapdrift/adapter-fs` during local capture so
+ * imported baselines land on the same filenames a local capture would produce.
+ *
+ * @param {string} id
+ * @returns {string}
+ */
+function sanitizeRouteId(id) {
+  return id
+    .replace(/\.\./g, '_')
+    .replace(/[/\\]/g, '_')
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\x00-\x1f\x7f]/g, '');
+}
+
+/**
+ * Parse a plain ustar-style tar archive (512-byte headers, bodies padded to
+ * 512-byte blocks, terminated by zero blocks) into a map of entry name →
+ * entry bytes. This is the exact layout Snap's export endpoint produces;
+ * long-name extensions (GNU/pax) are not needed and not supported.
+ *
+ * @param {Buffer} archive
+ * @returns {Map<string, Buffer>}
+ */
+function parseTarEntries(archive) {
+  /** @type {Map<string, Buffer>} */
+  const entries = new Map();
+  let offset = 0;
+
+  while (offset + TAR_BLOCK_SIZE <= archive.length) {
+    const header = archive.subarray(offset, offset + TAR_BLOCK_SIZE);
+    if (header.every((byte) => byte === 0)) {
+      break; // end-of-archive marker
+    }
+
+    const nameField = header.subarray(0, 100);
+    const nameEnd = nameField.indexOf(0);
+    const name = nameField.toString('utf-8', 0, nameEnd === -1 ? 100 : nameEnd);
+    const size = parseInt(header.toString('ascii', 124, 136).replace(/\0/g, '').trim(), 8);
+
+    if (!name || !Number.isFinite(size) || size < 0) {
+      throw new Error(`Snap export archive is corrupt: invalid tar header at offset ${offset}.`);
+    }
+
+    const bodyStart = offset + TAR_BLOCK_SIZE;
+    if (bodyStart + size > archive.length) {
+      throw new Error(`Snap export archive is truncated: entry "${name}" extends past the end of the archive.`);
+    }
+
+    entries.set(name, archive.subarray(bodyStart, bodyStart + size));
+    offset = bodyStart + Math.ceil(size / TAR_BLOCK_SIZE) * TAR_BLOCK_SIZE;
+  }
+
+  return entries;
+}
+
+/**
+ * Read the pixel dimensions from a PNG's IHDR chunk. Returns null when the
+ * bytes are not a PNG (e.g. a JPEG export) or are too short.
+ *
+ * @param {Buffer} bytes
+ * @returns {{ width: number, height: number } | null}
+ */
+function readPngDimensions(bytes) {
+  if (bytes.length < 24 || !bytes.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE)) {
+    return null;
+  }
+  return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
+}
+
+/**
+ * @param {string | undefined} json
+ * @returns {any}
+ */
+function safeJsonParse(json) {
+  if (!json) return null;
+  try {
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Sort key for picking the newest baseline. Snap serialises createdAt as an
+ * ISO string, but tolerate epoch numbers and treat unparsable values as
+ * oldest so a legacy row never shadows a well-formed one.
+ *
+ * @param {{ createdAt?: unknown }} baseline
+ * @returns {number}
+ */
+function baselineTimestamp(baseline) {
+  const createdAt = baseline?.createdAt;
+  if (typeof createdAt === 'number') return createdAt;
+  const parsed = Date.parse(typeof createdAt === 'string' ? createdAt : '');
+  return Number.isNaN(parsed) ? -Infinity : parsed;
+}
+
+/**
+ * Derive the capture engine from a baseline's capture profile. A baseline
+ * published by SnapDrift records `{ engine: { name: "snapdrift-local" } }`;
+ * a baseline rendered by Snap's hosted worker records Snap's own engine.
+ * When nothing is recorded (legacy hosted baselines export `{}`), fall back
+ * to "snap-hosted" so the CLI's cross-engine flow engages truthfully.
+ *
+ * @param {any} captureProfile
+ * @returns {{ name: string, version: string }}
+ */
+function resolveExportEngine(captureProfile) {
+  const engine = captureProfile?.engine;
+  if (engine && typeof engine.name === 'string' && engine.name) {
+    return {
+      name: engine.name,
+      version: typeof engine.version === 'string' && engine.version ? engine.version : 'unknown'
+    };
+  }
+  return { name: 'snap-hosted', version: 'unknown' };
+}
+
+/**
+ * Extract a human-readable detail string from a Snap API error response.
+ *
+ * @param {{ text: () => Promise<string> }} response
+ * @returns {Promise<string>}
+ */
+async function readErrorDetail(response) {
+  const errorBody = await response.text().catch(() => '');
+  try {
+    const parsed = JSON.parse(errorBody);
+    return parsed.error || parsed.message || '';
+  } catch {
+    return '';
+  }
+}
+
 /**
  * SnapProvider — VisualProvider that delegates capture + diff to Snap's
  * hosted /v1/visual/* API.
@@ -512,21 +652,185 @@ export class SnapProvider {
    * Export baselines from Snap for local import.
    * Used by `snapdrift migrate-baselines --to local --from snap`.
    *
-   * @param {{ tag?: string }} _options
+   * Downloads the project's export archive from
+   * `GET /v1/visual/projects/:id/export` (a plain ustar tar containing a
+   * `manifest.json`, per-baseline screenshot images, and per-baseline
+   * capture profiles; requires an API key with the `visual:export` scope),
+   * selects the most recent accepted baseline, and maps it back to the
+   * local baseline layout (`results.json` + `manifest.json` +
+   * `screenshots/<routeId>.png`) that `LocalProvider` reads.
+   *
+   * @param {{ tag?: string }} [_options]
    * @returns {Promise<{
    *   results: object,
    *   manifest: object,
    *   screenshots: Array<{ filename: string, data: Buffer }>,
    *   engine: { name: string, version: string }
    * }>}
-   * @throws {Error} The Snap export endpoint is not yet available.
+   * @throws {Error} When the project has no accepted baselines, the selected
+   *   baseline predates manifest tracking, or the export request fails.
    */
   async exportBaselines(_options) {
-    throw new Error(
-      'The Snap export endpoint is not yet available. ' +
-      'This command will be functional once the Snap API adds GET /v1/visual/projects/:id/export. ' +
-      'See Snap repo issue #482 for tracking.'
+    const exportPath = `/v1/visual/projects/${this.#projectId}/export`;
+    let archive;
+    try {
+      archive = await this.#requestBinary('GET', exportPath);
+    } catch (error) {
+      if (error instanceof SnapApiError) {
+        if (error.status === 403) {
+          throw new Error(
+            `Snap refused the export (403): the API key does not have the "visual:export" scope. ` +
+            `Issue a key with visual:export access for project "${this.#projectId}" and retry.`,
+            { cause: error }
+          );
+        }
+        if (error.status === 404) {
+          throw new Error(
+            `Snap project "${this.#projectId}" was not found (404). ` +
+            `Check snap.projectId in snapdrift.json (or GITHUB_REPOSITORY when projectId is "auto").`,
+            { cause: error }
+          );
+        }
+        if (error.status === 413) {
+          throw new Error(
+            `Snap export for project "${this.#projectId}" is too large (413): ${error.message}. ` +
+            `The export endpoint caps the number of accepted baselines and total archive bytes.`,
+            { cause: error }
+          );
+        }
+      }
+      throw error;
+    }
+
+    const entries = parseTarEntries(archive);
+    const manifestBytes = entries.get('manifest.json');
+    if (!manifestBytes) {
+      throw new Error('Snap export archive is missing manifest.json.');
+    }
+    const exportManifest = JSON.parse(manifestBytes.toString('utf-8'));
+    const baselines = Array.isArray(exportManifest.baselines) ? exportManifest.baselines : [];
+    if (baselines.length === 0) {
+      throw new Error(
+        `Snap project "${this.#projectId}" has no accepted baselines to export. ` +
+        `Publish a baseline first (snapdrift baseline with provider: "snap").`
+      );
+    }
+
+    // Most recent accepted baseline wins; `>=` makes the later array entry win
+    // a createdAt tie (the server appends newer rows last).
+    let baseline = baselines[0];
+    for (const candidate of baselines.slice(1)) {
+      if (baselineTimestamp(candidate) >= baselineTimestamp(baseline)) {
+        baseline = candidate;
+      }
+    }
+
+    if (!baseline.sourceManifest) {
+      throw new Error(
+        `Snap baseline "${baseline.id}" predates manifest tracking (no source manifest was recorded ` +
+        `at publish time) and cannot be migrated. Publish a fresh baseline with a current SnapDrift ` +
+        `version, then re-run the migration.`
+      );
+    }
+    const routes = Array.isArray(baseline.sourceManifest.routes) ? baseline.sourceManifest.routes : null;
+    if (!routes) {
+      throw new Error(
+        `Snap baseline "${baseline.id}" has an unrecognised source manifest format ` +
+        `(expected a "routes" array) and cannot be migrated.`
+      );
+    }
+
+    const archivePathByKey = new Map(
+      (baseline.objects || []).map((object) => [object.sourceKey, object.archivePath])
     );
+
+    /** @type {Array<{ filename: string, data: Buffer }>} */
+    const screenshots = [];
+    /** @type {Array<object>} */
+    const manifestEntries = [];
+
+    for (const route of routes) {
+      const archivePath = route.objectKey ? archivePathByKey.get(route.objectKey) : undefined;
+      const bytes = archivePath ? entries.get(archivePath) : undefined;
+      if (!bytes) {
+        process.stderr.write(
+          `[SnapDrift] Warning: Snap export has no image for route "${route.routeId}" ` +
+          `in baseline ${baseline.id}. Skipping the route.\n`
+        );
+        continue;
+      }
+
+      const descriptor = safeJsonParse(route.viewportDescriptorJson) ?? {};
+      const hasDescriptorDims = typeof descriptor.width === 'number' && typeof descriptor.height === 'number';
+      // Map the viewport descriptor back to a preset name when it matches one
+      // exactly; otherwise keep custom dimensions. This round-trips with the
+      // descriptor expansion capture() applies on the way up.
+      const presetName = hasDescriptorDims ? viewportHash(descriptor) : null;
+      const dimensions = readPngDimensions(bytes)
+        ?? (hasDescriptorDims ? { width: descriptor.width, height: descriptor.height } : { width: 1, height: 1 });
+      const viewport = presetName && VIEWPORT_PRESETS[presetName]
+        ? presetName
+        : hasDescriptorDims
+          ? { width: descriptor.width, height: descriptor.height }
+          : { width: dimensions.width, height: dimensions.height };
+
+      const extension = path.extname(archivePath) || '.png';
+      const filename = `${sanitizeRouteId(route.routeId)}${extension}`;
+      screenshots.push({ filename, data: Buffer.from(bytes) });
+      manifestEntries.push({
+        id: route.routeId,
+        path: route.routePath ?? '',
+        viewport,
+        imagePath: `screenshots/${filename}`,
+        width: dimensions.width,
+        height: dimensions.height
+      });
+    }
+
+    if (screenshots.length === 0) {
+      throw new Error(
+        `Snap baseline "${baseline.id}" contained no exportable screenshots — ` +
+        `the export archive had no image bytes for any of its routes.`
+      );
+    }
+
+    const captureProfile = safeJsonParse(
+      entries.get(`${baseline.id}/capture_profile.json`)?.toString('utf-8')
+    ) ?? {};
+    const engine = resolveExportEngine(captureProfile);
+
+    const generatedAt = new Date().toISOString();
+    const manifest = {
+      schemaVersion: 1,
+      generatedAt,
+      baseUrl: typeof baseline.sourceManifest.baseUrl === 'string' ? baseline.sourceManifest.baseUrl : '',
+      screenshots: manifestEntries,
+      captureProfile: { ...captureProfile, engine }
+    };
+
+    const results = {
+      startedAt: typeof baseline.createdAt === 'string' ? baseline.createdAt : generatedAt,
+      suite: 'snap-export',
+      provider: 'snap',
+      projectId: this.#projectId,
+      baselineId: baseline.id,
+      refBranch: baseline.refBranch,
+      // readLocalBaselines() picks this up as the commit SHA if the baseline is
+      // ever migrated back to Snap, keeping the idempotency key stable.
+      headSha: baseline.refSha,
+      routes: manifestEntries.map((entry) => ({
+        id: entry.id,
+        path: entry.path,
+        viewport: entry.viewport,
+        status: 'passed',
+        durationMs: 0,
+        imagePath: entry.imagePath,
+        width: entry.width,
+        height: entry.height
+      }))
+    };
+
+    return { results, manifest, screenshots, engine };
   }
 
   // ---------------------------------------------------------------------------
@@ -811,6 +1115,67 @@ export class SnapProvider {
     return this.#handleUnavailable(new SnapUnavailableError('Max retries exceeded'));
   }
 
+  /**
+   * Make an HTTP request to the Snap API that returns a binary body (e.g. the
+   * export tar). Mirrors #request's retry and error semantics — 4xx never
+   * retries and throws SnapApiError, 5xx/network errors retry with backoff and
+   * consult onUnavailable when exhausted — but returns the raw bytes instead
+   * of parsed JSON.
+   *
+   * @param {string} method
+   * @param {string} path
+   * @returns {Promise<any>} Raw response bytes as a Buffer
+   */
+  async #requestBinary(method, path) {
+    for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+      try {
+        const response = await this.#fetchFn(`${this.#apiUrl}${path}`, {
+          method,
+          headers: { 'Authorization': `Bearer ${this.#apiKey}` }
+        });
+
+        if (response.ok) {
+          return Buffer.from(await response.arrayBuffer());
+        }
+
+        // 4xx — never retry
+        if (response.status >= 400 && response.status < 500) {
+          const detail = await readErrorDetail(response);
+          const errorMessage = detail ? `Snap API ${response.status}: ${detail}` : `Snap API ${response.status}`;
+          throw new SnapApiError(response.status, errorMessage, path);
+        }
+
+        // 5xx — retry with backoff (unless this is the last attempt)
+        if (attempt < MAX_RETRIES) {
+          const delay = Math.min(INITIAL_RETRY_DELAY_MS * (RETRY_MULTIPLIER ** (attempt - 1)), MAX_RETRY_TOTAL_MS);
+          await this.#sleepFn(delay);
+          continue;
+        }
+
+        // Exhausted retries
+        const detail = await readErrorDetail(response);
+        const errorMessage = detail ? `Snap API ${response.status}: ${detail}` : `Snap API ${response.status}`;
+        return this.#handleUnavailable(new SnapApiError(response.status, errorMessage, path));
+      } catch (error) {
+        if (error instanceof SnapApiError) {
+          throw error;
+        }
+
+        // Network error — retry
+        if (attempt < MAX_RETRIES) {
+          const delay = Math.min(INITIAL_RETRY_DELAY_MS * (RETRY_MULTIPLIER ** (attempt - 1)), MAX_RETRY_TOTAL_MS);
+          await this.#sleepFn(delay);
+          continue;
+        }
+
+        return this.#handleUnavailable(new SnapUnavailableError(error instanceof Error ? error.message : String(error)));
+      }
+    }
+
+    // Unreachable, but satisfies the type checker
+    return this.#handleUnavailable(new SnapUnavailableError('Max retries exceeded'));
+  }
+
   /**
    * Handle unavailable behavior based on onUnavailable config.
    * @param {Error} error

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snapdrift",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "private": false,
   "type": "module",
   "description": "SnapDrift captures, compares, and reports UI drift for Playwright-based app checks.",