snapdrift 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.4.0 - 2026-05-26
+
+### Features
+
+- **VisualProvider interface** — new `VisualProvider` interface (`capture`, `diff`, `publishBaseline`, `fetchLatestBaseline`, `buildCommentBody`) with `LocalProvider` and `SnapProvider` implementations. Config `provider` field (`"local"` | `"snap"`) selects the backend; defaults to `"local"` for zero-config backward compatibility.
+- **SnapProvider** — calls Snap's `/v1/visual/*` API for capture, diff, and baseline management. Retries on 5xx with exponential backoff (3 attempts, 30 s cap). Honors `snap.onUnavailable` (`"fail"` | `"warn-and-skip"` | `"fallback-local"`). 4xx errors never retry or fall back.
+- **Snap config** — new `snap` config block (`apiUrl`, `apiKeyEnv`/`apiKey`, `projectId`, `onUnavailable`) in `snapdrift.json`. Exactly one of `apiKeyEnv` or `apiKey` is required when `provider: "snap"`.
+- **PR comment unification** — both providers now produce identical PR comment markdown via a shared `buildCommentBody(summary, meta?)` method. `SnapProvider` appends a "View in dashboard →" link when `dashboardUrl` is present; `LocalProvider` omits it. Comment steps route through the provider instead of calling `buildReportCommentBody` directly, with a defensive fallback to `LocalProvider` if config loading fails.
+- **`migrate-baselines` command** — one-shot CLI command (`snapdrift migrate-baselines --to snap` / `--to local`) to upload local baselines to Snap or export Snap baselines back to a local directory. Supports `--accept-cross-engine` for engine-mismatch scenarios.
+- **`init --from-snap-action` codemod** — translates a Snap `github-action` workflow YAML into `snapdrift.json` with `provider: "snap"`. Emits structured warnings for features with no direct equivalent (jpeg format, baseline tags, single-shot artifact upload).
+
+### Infrastructure
+
+- **`@snapdrift/manifest` v1.1.0** — added `ProviderCommentMeta`, `dashboardUrl` on `VisualDiffSummary`, `buildCommentBody` on `VisualProvider`, `SnapConfig` re-export.
+- **`@snapdrift/adapter-report-md` v1.1.0** — `buildReportCommentBody` now accepts `dashboardUrl` in meta; renders "View in dashboard →" link when present and valid.
+- **Action contract tests** — `snapdrift-actions-contract` test suite now asserts that comment and pr-diff steps include `createProvider` and `buildCommentBody` calls.
+- **Provider unification tests** — new `buildCommentBody — provider unification` test block verifying identical markdown output across providers, dashboard link inclusion/exclusion, and URL validation.
+
 ## 0.3.0 - 2026-05-26
 
 ### Infrastructure

package/actions/comment/action.yml

@@ -20,6 +20,10 @@ inputs:
     description: Artifact label to include in the comment.
     required: false
     default: ''
+  repo-config-path:
+    description: Path to the SnapDrift config file (needed for provider-aware comment rendering).
+    required: false
+    default: .github/snapdrift.json
   max-changed-rows:
     description: Maximum number of changed-route rows shown in the PR comment before truncation.
     required: false
@@ -42,6 +46,7 @@ runs:
         VISUAL_DIFF_RUN_URL: ${{ inputs.run-url }}
         VISUAL_DIFF_ARTIFACT_NAME: ${{ inputs.artifact-name }}
         INPUT_PR_NUMBER: ${{ inputs.pr-number }}
+        REPO_CONFIG_PATH: ${{ inputs.repo-config-path }}
         MAX_CHANGED_ROWS: ${{ inputs.max-changed-rows }}
         MAX_ERROR_ROWS: ${{ inputs.max-error-rows }}
       with:
@@ -63,15 +68,29 @@ runs:
             return;
           }
 
-          const modulePath = path.resolve(process.env.ACTION_ROOT, 'lib/pr-comment.mjs');
-          const { buildReportCommentBody, PR_COMMENT_MARKERS } = await import(pathToFileURL(modulePath));
+          const providerModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/provider.mjs');
+          const configModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/snapdrift-config.mjs');
+          const prCommentModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/pr-comment.mjs');
+          const { createProvider } = await import(pathToFileURL(providerModulePath));
+          const { loadSnapdriftConfig } = await import(pathToFileURL(configModulePath));
+          const { PR_COMMENT_MARKERS } = await import(pathToFileURL(prCommentModulePath));
+
+          // Provider-loading block duplicated in actions/pr-diff/action.yml — keep in sync.
+          let provider;
+          try {
+            const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
+            provider = createProvider(config.provider || 'local', config);
+          } catch (err) {
+            core.warning(`Could not load SnapDrift config; falling back to LocalProvider. ${err.message}`);
+            provider = createProvider('local');
+          }
 
           const summary = JSON.parse(fs.readFileSync(summaryPath, 'utf8'));
           const runUrl = process.env.VISUAL_DIFF_RUN_URL || `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}`;
 
           const maxChangedRows = Number(process.env.MAX_CHANGED_ROWS) || 20;
           const maxErrorRows = Number(process.env.MAX_ERROR_ROWS) || 10;
-          const body = buildReportCommentBody(summary, {
+          const body = provider.buildCommentBody(summary, {
             artifactName: process.env.VISUAL_DIFF_ARTIFACT_NAME || '',
             runUrl,
             maxChangedRows,

package/actions/pr-diff/action.yml

@@ -498,6 +498,7 @@ runs:
         SUMMARY_PATH: ${{ steps.compare.outputs.summary_path || steps.skipped_baseline.outputs.summary_path || steps.skipped_scope.outputs.summary_path }}
         ARTIFACT_NAME: ${{ steps.context.outputs.artifact_name }}
         RUN_URL: ${{ steps.context.outputs.run_url }}
+        REPO_CONFIG_PATH: ${{ inputs.repo-config-path }}
         MAX_CHANGED_ROWS: ${{ inputs.max-changed-rows }}
         MAX_ERROR_ROWS: ${{ inputs.max-error-rows }}
       with:
@@ -531,13 +532,25 @@ runs:
             return;
           }
 
-          const modulePath = path.resolve(process.env.ACTION_ROOT, 'lib/pr-comment.mjs');
-          const { buildReportCommentBody } = await import(pathToFileURL(modulePath));
+          const providerModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/provider.mjs');
+          const configModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/snapdrift-config.mjs');
+          const { createProvider } = await import(pathToFileURL(providerModulePath));
+          const { loadSnapdriftConfig } = await import(pathToFileURL(configModulePath));
+
+          // Provider-loading block duplicated in actions/comment/action.yml — keep in sync.
+          let provider;
+          try {
+            const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
+            provider = createProvider(config.provider || 'local', config);
+          } catch (err) {
+            core.warning(`Could not load SnapDrift config; falling back to LocalProvider. ${err.message}`);
+            provider = createProvider('local');
+          }
 
           const summary = JSON.parse(fs.readFileSync(summaryPath, 'utf8'));
           const maxChangedRows = Number(process.env.MAX_CHANGED_ROWS) || 20;
           const maxErrorRows = Number(process.env.MAX_ERROR_ROWS) || 10;
-          const body = buildReportCommentBody(summary, {
+          const body = provider.buildCommentBody(summary, {
             artifactName: process.env.ARTIFACT_NAME || '',
             runUrl: process.env.RUN_URL || '',
             maxChangedRows,

package/docs/contracts.md

@@ -34,6 +34,12 @@ SnapDrift reads runtime behavior from `.github/snapdrift.json` by default.
 |:------|:-----|:------------|
 | `selection.sharedPrefixes` | `string[]` | Prefixes that force the full route set |
 | `selection.sharedExact` | `string[]` | Exact files that force the full route set |
+| `provider` | `string` | `"local"` (default) or `"snap"` for hosted backend |
+| `snap.apiUrl` | `string` | Snap API base URL (default: `https://snap.i2dev.com`) |
+| `snap.apiKeyEnv` | `string` | Env var name for API key (mutually exclusive with `snap.apiKey`) |
+| `snap.apiKey` | `string` | Inline API key with `${VAR}` interpolation (mutually exclusive with `snap.apiKeyEnv`) |
+| `snap.projectId` | `string` | Snap project ID or `"auto"` (default: `"auto"`, derives from `GITHUB_REPOSITORY`) |
+| `snap.onUnavailable` | `string` | Behavior when Snap is unreachable: `"fail"` (default), `"warn-and-skip"`, or `"fallback-local"` |
 
 ### Example
 
@@ -129,6 +135,12 @@ The pull request drift bundle contains:
 }
 ```
 
+### Optional summary fields
+
+| Field | Type | Description |
+|:------|:-----|:------------|
+| `dashboardUrl` | `string?` | Snap dashboard URL for the run (set by `SnapProvider`; omitted by `LocalProvider`) |
+
 ### Status values
 
 | Status | Meaning |
@@ -208,6 +220,47 @@ When using the `snapdrift` CLI, outputs are written to `.snapdrift/` by default:
 
 All three directories can be overridden with `--baseline-dir`, `--current-dir`, and `--diff-dir`. See the [Local CLI guide](local-cli.md) for details.
 
+## Migration commands
+
+### migrate-baselines
+
+Migrate baselines between local storage and Snap.
+
+**Upload local baselines to Snap:**
+
+```
+snapdrift migrate-baselines --to snap [--config <path>] [--baseline-dir <dir>]
+```
+
+- Reads local manifest + baseline images from the baseline directory.
+- Uploads as the initial accepted baseline on Snap via `POST /v1/visual/projects/:id/baselines`.
+- Idempotent: skips upload if a baseline already exists with the matching commit SHA.
+- Requires snapdrift.json with `provider: "snap"` (or snap config).
+
+**Download Snap baselines to local:**
+
+```
+snapdrift migrate-baselines --to local --from snap [--accept-cross-engine] [--config <path>] [--baseline-dir <dir>]
+```
+
+- Downloads baselines from Snap's export endpoint.
+- Writes to the local baseline directory.
+- Without `--accept-cross-engine`: hard-errors if the exported baselines were captured by a different engine.
+- With `--accept-cross-engine`: overrides the engine name to `snapdrift-local` in the imported manifest (visual differences may occur).
+
+### init
+
+**Translate a Snap action workflow to snapdrift.json:**
+
+```
+snapdrift init --from-snap-action <workflow-yaml-path>
+```
+
+- Reads an existing Snap `github-action/` workflow YAML.
+- Translates Snap action inputs into `.github/snapdrift.json`.
+- Emits `.github/MIGRATION_NOTES.md` listing warnings and deferred decisions.
+- Idempotent: refuses to overwrite an existing `snapdrift.json`.
+
 ## Primary entrypoints
 
 - `actions/baseline`
@@ -235,3 +288,72 @@ These are for custom orchestration only. Wrapper actions set them automatically.
 | `SNAPDRIFT_BASELINE_SOURCE_SHA` | `compare-results.mjs` | Baseline source SHA to embed in the report |
 | `SNAPDRIFT_ENFORCE_OUTCOME` | `compare-results.mjs` | Set to `0` to disable enforcement in direct CLI usage |
 | `SNAPDRIFT_CAPTURE_CONCURRENCY` | `capture-routes.mjs` | Max concurrent route captures per viewport context (positive integer, default `5`). Set to `1` to restore serial behaviour for apps with shared session/auth state. |
+
+## PR comment markdown shape
+
+The canonical PR comment is produced by `provider.buildCommentBody(summary, meta)` in `@snapdrift/adapter-report-md`. Both `LocalProvider` and `SnapProvider` emit byte-identical markdown for the same summary — the only provider-specific difference is the optional **"View in dashboard →"** link appended by `SnapProvider`.
+
+Snap's server-side notification posting should render the same template from the run summary JSON so that reviewers see a consistent format regardless of which provider produced the run.
+
+### Structure
+
+```
+<!-- snapdrift-report -->
+## {status-icon} SnapDrift Report — {status-label}
+
+| Signal | Count |
+|:-------|------:|
+| Drift signals | N |
+| Missing in baseline | N |
+| Missing in current capture | N |
+| Dimension shifts | N |
+
+> **Note:** {message}                           ← optional, when summary.message is set
+
+<details><summary>Error details</summary>       ← collapsible, only when errors exist
+| Route | Viewport | Error |
+|:------|:---------|:------|
+| route-id | viewport | error message |
+*...and N more* — [View full report →]({runUrl})  ← when errors exceed maxErrorRows
+</details>
+
+<details><summary>Drift signals</summary>       ← collapsible, only when changed routes exist
+| Route | Viewport | Mismatch |
+|:------|:---------|:---------|
+| route-id | viewport | X.XX% |
+*...and N more* — [View full report →]({runUrl})  ← when routes exceed maxChangedRows
+</details>
+
+<details open><summary>Dimension shifts — comparison skipped</summary>  ← auto-expanded, only when dimension shifts exist
+> SnapDrift detected a dimension shift …
+| Route | Viewport | Baseline | Current |
+|:------|:---------|:---------|:--------|
+| route-id | viewport | WxH | WxH |
+</details>
+
+<sub>SnapDrift · artifact `name` · baseline `name` · sha `abc1234` · [View run](url) · [View in dashboard →](url)</sub>
+                                                  ↑ LocalProvider omits "View in dashboard"
+
+<div align="right"><sub>Powered by <a href="…">SnapDrift</a></sub></div>
+```
+
+### Meta parameters
+
+| Field | Type | Description |
+|:------|:-----|:------------|
+| `artifactName` | `string?` | PR diff artifact label |
+| `runUrl` | `string?` | GitHub Actions run URL (adds `[View run]` link) |
+| `dashboardUrl` | `string?` | Snap dashboard URL (adds `[View in dashboard →]` link; SnapProvider only) |
+| `maxChangedRows` | `number` | Max drift-signal rows before truncation (default 20) |
+| `maxErrorRows` | `number` | Max error rows before truncation (default 10) |
+
+### Update-in-place semantics
+
+Comments are identified by the `<!-- snapdrift-report -->` HTML marker. On re-run, the action finds the most recent matching comment and updates it in place. Duplicate markers from earlier runs are deleted.
+
+### Provider contract
+
+The `VisualProvider` interface requires `buildCommentBody(summary, meta?)`:
+
+- **`LocalProvider`** — delegates to `buildReportCommentBody` without a `dashboardUrl`.
+- **`SnapProvider`** — constructs `dashboardUrl` from `{apiUrl}/projects/{projectId}/runs/{lastRunId}` and passes it through.

package/lib/cli.mjs

@@ -4,8 +4,10 @@ import { execSync } from 'node:child_process';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
-import { runBaselineCapture, generateDriftReport, loadSnapdriftConfig } from '@snapdrift/adapter-fs';
+import { loadSnapdriftConfig } from '@snapdrift/adapter-fs';
 import { shouldFailDriftCheck } from '@snapdrift/manifest';
+import { createProvider } from './provider.mjs';
+import { SnapFallbackError, SnapSkipError } from './snap-provider.mjs';
 import { generateHtmlReport } from './report.mjs';
 
 /** @typedef {import('../types/visual-diff-types').VisualDiffSummary} DriftSummary */
@@ -23,13 +25,17 @@ export const LOCAL_DIFF_SUBDIR = 'diff';
  *   routes: string[],
  *   baselineDir: string,
  *   currentDir: string,
- *   diffDir: string
+ *   diffDir: string,
+ *   to?: 'snap' | 'local',
+ *   from?: 'snap',
+ *   acceptCrossEngine?: boolean,
+ *   fromSnapAction?: string
  * }} CliOptions
  */
 
 /**
  * Parse CLI arguments from process.argv (or a provided argv array).
- * Supported commands: capture, diff
+ * Supported commands: capture, diff, migrate-baselines, init
  * Supported flags:
  *   --open              Open the HTML report after diff
  *   --config <path>     Path to snapdrift.json (default: .github/snapdrift.json)
@@ -37,6 +43,10 @@ export const LOCAL_DIFF_SUBDIR = 'diff';
  *   --baseline-dir <p>  Override local baseline directory (default: .snapdrift/baseline)
  *   --current-dir <p>   Override local current-capture directory (default: .snapdrift/current)
  *   --diff-dir <p>      Override local diff-output directory (default: .snapdrift/diff)
+ *   --to <snap|local>   Migration target (migrate-baselines command)
+ *   --from <snap>       Migration source (migrate-baselines --to local)
+ *   --accept-cross-engine  Allow importing baselines from a different capture engine
+ *   --from-snap-action <path>  Snap action workflow YAML path (init command)
  *
  * @param {string[]} argv - process.argv
  * @returns {CliOptions}
@@ -52,6 +62,13 @@ export function parseArgs(argv) {
   let baselineDir = path.resolve(LOCAL_SNAPDRIFT_DIR, LOCAL_BASELINE_SUBDIR);
   let currentDir = path.resolve(LOCAL_SNAPDRIFT_DIR, LOCAL_CURRENT_SUBDIR);
   let diffDir = path.resolve(LOCAL_SNAPDRIFT_DIR, LOCAL_DIFF_SUBDIR);
+  /** @type {'snap' | 'local' | undefined} */
+  let to;
+  /** @type {'snap' | undefined} */
+  let from;
+  let acceptCrossEngine = false;
+  /** @type {string | undefined} */
+  let fromSnapAction;
 
   for (let i = 1; i < args.length; i++) {
     const arg = args[i];
@@ -72,10 +89,24 @@ export function parseArgs(argv) {
       currentDir = path.resolve(args[++i]);
     } else if (arg === '--diff-dir' && i + 1 < args.length) {
       diffDir = path.resolve(args[++i]);
+    } else if (arg === '--to' && i + 1 < args.length) {
+      const toVal = args[++i];
+      if (toVal === 'snap' || toVal === 'local') {
+        to = toVal;
+      }
+    } else if (arg === '--from' && i + 1 < args.length) {
+      const fromVal = args[++i];
+      if (fromVal === 'snap') {
+        from = fromVal;
+      }
+    } else if (arg === '--accept-cross-engine') {
+      acceptCrossEngine = true;
+    } else if (arg === '--from-snap-action' && i + 1 < args.length) {
+      fromSnapAction = args[++i];
     }
   }
 
-  return { command, open, configPath, routes, baselineDir, currentDir, diffDir };
+  return { command, open, configPath, routes, baselineDir, currentDir, diffDir, to, from, acceptCrossEngine, fromSnapAction };
 }
 
 /**
@@ -148,12 +179,29 @@ function openFile(filePath) {
  */
 export async function runCaptureCommand(opts) {
   process.stdout.write(`Capturing baseline to ${opts.baselineDir} ...\n`);
-  const { selectedRouteIds } = await runBaselineCapture({
-    configPath: opts.configPath,
-    routeIds: opts.routes.length > 0 ? opts.routes : undefined,
-    outDir: opts.baselineDir
-  });
-  process.stdout.write(`Captured ${selectedRouteIds.length} route(s) to ${opts.baselineDir}\n`);
+  const { config } = await loadSnapdriftConfig(opts.configPath);
+  const provider = createProvider(config.provider ?? 'local', config);
+  try {
+    const { selectedRouteIds } = await provider.capture({
+      configPath: opts.configPath,
+      routeIds: opts.routes.length > 0 ? opts.routes : undefined,
+      outDir: opts.baselineDir
+    });
+    process.stdout.write(`Captured ${selectedRouteIds.length} route(s) to ${opts.baselineDir}\n`);
+  } catch (error) {
+    if (error instanceof SnapFallbackError) {
+      process.stdout.write('Falling back to local provider for capture...\n');
+      const localProvider = createProvider('local');
+      const { selectedRouteIds } = await localProvider.capture({
+        configPath: opts.configPath,
+        routeIds: opts.routes.length > 0 ? opts.routes : undefined,
+        outDir: opts.baselineDir
+      });
+      process.stdout.write(`Captured ${selectedRouteIds.length} route(s) to ${opts.baselineDir}\n`);
+      return;
+    }
+    throw error;
+  }
 }
 
 /**
@@ -166,12 +214,30 @@ export async function runCaptureCommand(opts) {
 export async function runDiffCommand(opts) {
   process.stdout.write(`Capturing current screenshots to ${opts.currentDir} ...\n`);
   const { config } = await loadSnapdriftConfig(opts.configPath);
+  const provider = createProvider(config.provider ?? 'local', config);
 
-  const currentCapture = await runBaselineCapture({
-    configPath: opts.configPath,
-    routeIds: opts.routes.length > 0 ? opts.routes : undefined,
-    outDir: opts.currentDir
-  });
+  let currentCapture;
+  let usedLocalFallback = false;
+  try {
+    currentCapture = await provider.capture({
+      configPath: opts.configPath,
+      routeIds: opts.routes.length > 0 ? opts.routes : undefined,
+      outDir: opts.currentDir
+    });
+  } catch (error) {
+    if (error instanceof SnapFallbackError) {
+      process.stdout.write('Falling back to local provider for capture...\n');
+      const localProvider = createProvider('local');
+      currentCapture = await localProvider.capture({
+        configPath: opts.configPath,
+        routeIds: opts.routes.length > 0 ? opts.routes : undefined,
+        outDir: opts.currentDir
+      });
+      usedLocalFallback = true;
+    } else {
+      throw error;
+    }
+  }
 
   process.stdout.write('Comparing against baseline ...\n');
 
@@ -183,16 +249,28 @@ export async function runDiffCommand(opts) {
   const markdownPath = path.join(opts.diffDir, 'summary.md');
   const htmlPath = path.join(opts.diffDir, 'report.html');
 
-  const { summary, markdown } = await generateDriftReport({
-    configPath: opts.configPath,
-    routeIds: opts.routes.length > 0 ? opts.routes : undefined,
-    baselineResultsPath,
-    baselineManifestPath,
-    currentResultsPath: currentCapture.resultsPath,
-    currentManifestPath: currentCapture.manifestPath,
-    baselineRunDir: opts.baselineDir,
-    currentRunDir: currentCapture.screenshotsRoot
-  });
+  const diffProvider = usedLocalFallback ? createProvider('local') : provider;
+  let diffResult;
+  try {
+    diffResult = await diffProvider.diff({
+      configPath: opts.configPath,
+      routeIds: opts.routes.length > 0 ? opts.routes : undefined,
+      baselineResultsPath,
+      baselineManifestPath,
+      currentResultsPath: currentCapture.resultsPath,
+      currentManifestPath: currentCapture.manifestPath,
+      baselineRunDir: opts.baselineDir,
+      currentRunDir: currentCapture.screenshotsRoot
+    });
+  } catch (error) {
+    if (error instanceof SnapSkipError) {
+      process.stdout.write('Visual regression skipped (Snap unavailable, warn-and-skip mode).\n');
+      return;
+    }
+    throw error;
+  }
+
+  const { summary, markdown } = diffResult;
 
   const html = await generateHtmlReport(summary, {
     baselineRunDir: opts.baselineDir,
@@ -218,6 +296,58 @@ export async function runDiffCommand(opts) {
   }
 }
 
+/**
+ * Run the `migrate-baselines` command — migrate baselines between local and Snap.
+ *
+ * @param {CliOptions} opts
+ * @returns {Promise<void>}
+ */
+export async function runMigrateBaselinesCommand(opts) {
+  if (!opts.to || (opts.to !== 'snap' && opts.to !== 'local')) {
+    process.stderr.write('Usage: snapdrift migrate-baselines --to <snap|local> [--from snap] [--accept-cross-engine] [--config <path>] [--baseline-dir <dir>]\n');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (opts.to === 'local' && opts.from !== 'snap') {
+    process.stderr.write('Error: --to local requires --from snap\n');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (opts.acceptCrossEngine && opts.to !== 'local') {
+    process.stderr.write('Error: --accept-cross-engine is only valid with --to local\n');
+    process.exitCode = 1;
+    return;
+  }
+
+  const { runMigrateToSnap, runMigrateToLocal } = await import('./migrate-baselines.mjs');
+  const { config } = await loadSnapdriftConfig(opts.configPath);
+
+  if (opts.to === 'snap') {
+    await runMigrateToSnap(config, opts);
+  } else {
+    await runMigrateToLocal(config, opts);
+  }
+}
+
+/**
+ * Run the `init` command — initialize snapdrift config from a Snap action workflow.
+ *
+ * @param {CliOptions} opts
+ * @returns {Promise<void>}
+ */
+export async function runInitCommand(opts) {
+  if (!opts.fromSnapAction) {
+    process.stderr.write('Usage: snapdrift init --from-snap-action <workflow-yaml-path>\n');
+    process.exitCode = 1;
+    return;
+  }
+
+  const { runInitFromAction } = await import('./init-from-action.mjs');
+  await runInitFromAction(opts.fromSnapAction);
+}
+
 /**
  * Main CLI entry point — parse args and dispatch to the appropriate command.
  *
@@ -231,9 +361,13 @@ export async function main(argv) {
     await runCaptureCommand(opts);
   } else if (opts.command === 'diff') {
     await runDiffCommand(opts);
+  } else if (opts.command === 'migrate-baselines') {
+    await runMigrateBaselinesCommand(opts);
+  } else if (opts.command === 'init') {
+    await runInitCommand(opts);
   } else {
     process.stderr.write(
-      `Unknown command: ${opts.command}\nUsage: snapdrift <capture|diff> [options]\n`
+      `Unknown command: ${opts.command}\nUsage: snapdrift <capture|diff|migrate-baselines|init> [options]\n`
     );
     process.exitCode = 1;
   }