snapdrift 0.8.2 → 0.10.0

package/lib/cli.mjs

@@ -1,6 +1,6 @@
 // @ts-check
 
-import { execSync } from 'node:child_process';
+import { spawnSync } from 'node:child_process';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
@@ -49,6 +49,11 @@ export const LOCAL_DIFF_SUBDIR = 'diff';
  *   --accept-cross-engine  Allow importing baselines from a different capture engine
  *   --from-snap-action <path>  Snap action workflow YAML path (init command)
  *
+ * Values may be given inline as `--flag=value` (so values beginning with a hyphen,
+ * e.g. `--routes=-mobile`, work) or after the `--` end-of-options marker. Unknown
+ * flags and missing option values are rejected with a non-zero error; invalid
+ * *values* for --to/--from remain silently ignored (validated downstream).
+ *
  * @param {string[]} argv - process.argv
  * @returns {CliOptions}
  */
@@ -71,41 +76,105 @@ export function parseArgs(argv) {
   /** @type {string | undefined} */
   let fromSnapAction;
 
-  for (let i = 1; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === '--open') {
-      open = true;
-    } else if (arg === '--config' && i + 1 < args.length) {
-      configPath = args[++i];
-    } else if (arg === '--routes' && i + 1 < args.length) {
-      routes.push(
-        ...args[++i]
-          .split(',')
-          .map((r) => r.trim())
-          .filter(Boolean)
-      );
-    } else if (arg === '--baseline-dir' && i + 1 < args.length) {
-      baselineDir = path.resolve(args[++i]);
-    } else if (arg === '--current-dir' && i + 1 < args.length) {
-      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];
-    }
-  }
+   // Flags that consume the following token as their value. Unknown flags and
+   // missing option values are rejected rather than silently ignored, so a typo
+   // cannot fall back to the default config/directories. Invalid *values* for
+   // --to/--from stay silently ignored to preserve the migrate-baselines contract
+   // (their validation happens downstream). Values that begin with a hyphen (e.g.
+   // a route id like `-mobile`) may be supplied inline as `--flag=value` or bare.
+   const VALUE_FLAGS = new Set([
+     '--config',
+     '--routes',
+     '--baseline-dir',
+     '--current-dir',
+     '--diff-dir',
+     '--to',
+     '--from',
+     '--from-snap-action'
+   ]);
+   const BOOLEAN_FLAGS = new Set(['--open', '--accept-cross-engine']);
+
+   /**
+    * Assign a parsed value (from an inline `--flag=value` or a following token)
+    * to the option named by `flag`.
+    *
+    * @param {string} flag
+    * @param {string} value
+    */
+   function assignFlag(flag, value) {
+     if (flag === '--routes') {
+       routes.push(...value.split(',').map((r) => r.trim()).filter(Boolean));
+     } else if (flag === '--config') {
+       configPath = value;
+     } else if (flag === '--baseline-dir') {
+       baselineDir = path.resolve(value);
+     } else if (flag === '--current-dir') {
+       currentDir = path.resolve(value);
+     } else if (flag === '--diff-dir') {
+       diffDir = path.resolve(value);
+     } else if (flag === '--to') {
+       if (value === 'snap' || value === 'local') to = value;
+     } else if (flag === '--from') {
+       if (value === 'snap') from = value;
+     } else if (flag === '--from-snap-action') {
+       fromSnapAction = value;
+     }
+   }
+
+   let endOfOptions = false;
+
+   for (let i = 1; i < args.length; i++) {
+     const raw = args[i];
+
+     if (raw === '--') {
+       endOfOptions = true;
+       continue;
+     }
+
+     // End-of-options: after `--`, tokens are values/positionals, never flags.
+     if (endOfOptions) {
+       if (VALUE_FLAGS.has(raw)) {
+         const value = args[i + 1];
+         if (value === undefined) {
+           throw new Error(`Missing value for flag ${raw}`);
+         }
+         assignFlag(raw, value);
+         i++; // consume the following token so it is not reprocessed as a flag
+       }
+       continue;
+     }
+
+     // Inline `--flag=value` form (also handles values that begin with a hyphen).
+     const eq = raw.indexOf('=');
+     if (raw.startsWith('--') && eq > 0) {
+       const flag = raw.slice(0, eq);
+       if (!VALUE_FLAGS.has(flag)) {
+         throw new Error(`Unknown flag: ${flag}`);
+       }
+       assignFlag(flag, raw.slice(eq + 1));
+       continue;
+     }
+
+     if (BOOLEAN_FLAGS.has(raw)) {
+       if (raw === '--open') {
+         open = true;
+       } else if (raw === '--accept-cross-engine') {
+         acceptCrossEngine = true;
+       }
+     } else if (VALUE_FLAGS.has(raw)) {
+       const value = args[i + 1];
+       // A hyphenated following token (e.g. a route id like `-mobile`) is a
+       // legitimate value; only a missing token, the `--` end-of-options marker,
+       // or a following *recognized flag* means the value is absent.
+       if (value === undefined || value === '--' || VALUE_FLAGS.has(value) || BOOLEAN_FLAGS.has(value)) {
+         throw new Error(`Missing value for flag ${raw}`);
+       }
+       assignFlag(raw, value);
+       i++; // consume the following token so it is not reprocessed as a flag
+     } else if (raw.startsWith('-')) {
+       throw new Error(`Unknown flag: ${raw}`);
+     }
+   }
 
   return { command, open, configPath, routes, baselineDir, currentDir, diffDir, to, from, acceptCrossEngine, fromSnapAction };
 }
@@ -163,15 +232,30 @@ export function printSummary(summary) {
  * @returns {void}
  */
 function openFile(filePath) {
-  const cmd =
-    process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-  try {
-    execSync(`${cmd} "${filePath}"`);
-  } catch {
+  const { cmd, args } = buildOpenCommand(filePath);
+  const result = spawnSync(cmd, args);
+  if (result.error) {
     process.stderr.write(`Could not open file: ${filePath}\n`);
   }
 }
 
+/**
+ * Build the platform-correct invocation to open a file with the OS default
+ * viewer. The path is passed as a separate argument (never shell-interpolated)
+ * so metacharacters in a local path cannot execute commands. On Windows, `start`
+ * is a cmd.exe built-in rather than an executable, so spawnSync (which does not
+ * use a shell by default) returns ENOENT; open the registered handler through
+ * rundll32, a real executable, keeping the path as a separate argument.
+ *
+ * @param {string} filePath
+ * @returns {{ cmd: string, args: string[] }}
+ */
+export function buildOpenCommand(filePath, platform = process.platform) {
+  if (platform === 'darwin') return { cmd: 'open', args: [filePath] };
+  if (platform === 'linux') return { cmd: 'xdg-open', args: [filePath] };
+  return { cmd: 'rundll32', args: ['url.dll,FileProtocolHandler', filePath] };
+}
+
 /**
  * Run the `capture` command — capture screenshots to a local baseline directory.
  *
@@ -346,21 +430,24 @@ export async function runDiffCommand(opts) {
   const markdownPath = path.join(opts.diffDir, 'summary.md');
   const htmlPath = path.join(opts.diffDir, 'report.html');
 
+  const diffOptions = /** @type {import('../types/visual-diff-types').ProviderDiffOptions & { diffImagesDir: string }} */ ({
+    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,
+    diffImagesDir: path.join(opts.diffDir, 'diffs')
+  });
+
   const diffed = await diffWithPolicy({
     provider: captured.providerName === 'local' ? createProvider('local') : provider,
     providerName: captured.providerName,
     localScreenshots: captured.localScreenshots,
     captureOptions,
-    diffOptions: {
-      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
-    },
+    diffOptions,
     onSkip: () =>
       process.stdout.write('Visual regression skipped (Snap unavailable, warn-and-skip mode).\n'),
     onFallback: () => process.stdout.write('Falling back to local provider for the diff...\n'),
@@ -377,7 +464,8 @@ export async function runDiffCommand(opts) {
 
   const html = await generateHtmlReport(summary, {
     baselineRunDir: opts.baselineDir,
-    currentRunDir
+    currentRunDir,
+    diffRunDir: opts.diffDir
   });
 
   await Promise.all([

package/lib/init-from-action.mjs

@@ -87,19 +87,30 @@ function translateStepToConfig(step) {
     });
   }
 
-  // Snap provider config (if present in inputs)
-  /** @type {JsonObject | undefined} */
-  let snap;
-  const snapApiUrl = inputs['snap-api-url'] || inputs.snap_api_url;
-  const snapApiKeyEnv = inputs['snap-api-key-env'] || inputs.snap_api_key_env;
-  const snapProjectId = inputs['snap-project-id'] || inputs.snap_project_id;
-
-  if (snapApiKeyEnv || snapProjectId) {
-    snap = {};
-    if (snapApiUrl) snap.apiUrl = snapApiUrl;
-    if (snapApiKeyEnv) snap.apiKeyEnv = snapApiKeyEnv;
-    if (snapProjectId) snap.projectId = snapProjectId;
-  }
+   // Snap provider config (if present in inputs). A hosted Snap provider requires
+   // an API-key source; only enable provider: "snap" when one is present. When a
+   // project ID exists without an API-key source, keep a valid (local) config and
+   // emit a clear migration warning rather than emitting provider: "snap" with no
+   // API-key source, which later fails validation.
+   /** @type {JsonObject | undefined} */
+   let snap;
+   const snapApiUrl = inputs['snap-api-url'] || inputs.snap_api_url;
+   const snapApiKeyEnv = inputs['snap-api-key-env'] || inputs.snap_api_key_env;
+   const snapProjectId = inputs['snap-project-id'] || inputs.snap_project_id;
+
+   if (snapApiKeyEnv) {
+     snap = {};
+     if (snapApiUrl) snap.apiUrl = snapApiUrl;
+     snap.apiKeyEnv = snapApiKeyEnv;
+     if (snapProjectId) snap.projectId = snapProjectId;
+   } else if (snapProjectId) {
+     warnings.push({
+       field: 'snap.projectId',
+       originalValue: snapProjectId,
+       message: `Snap project ID "${snapProjectId}" is present but no API-key source (snap-api-key-env) was configured. SnapDrift keeps the local provider; add a Snap API key source to enable hosted baselines.`,
+       severity: 'warning'
+     });
+   }
 
   const config = {
     baselineArtifactName: 'snapdrift-baseline',

package/lib/outage-policy.mjs

@@ -41,6 +41,25 @@ export const MISSING_BASELINE_REASON = 'missing_main_baseline_artifact';
 /** @returns {void} */
 function noop() {}
 
+/**
+ * @param {unknown} outageError
+ * @param {'capture' | 'diff'} phase
+ * @param {string | undefined} lookupMessage
+ * @returns {Error}
+ */
+function createBaselineLookupFallbackError(outageError, phase, lookupMessage) {
+  const lookupDetail = typeof lookupMessage === 'string' && lookupMessage.trim().length > 0
+    ? ` ${lookupMessage.trim()}`
+    : '';
+  const outageDetail = outageError instanceof Error && outageError.message
+    ? ` Snap fallback reason: ${outageError.message}`
+    : '';
+  return new Error(
+    `Cannot fall back to a local ${phase} because the GitHub baseline lookup failed.${lookupDetail}${outageDetail}`,
+    { cause: outageError }
+  );
+}
+
 /**
  * Whether the current capture leaves real PNGs on the runner's filesystem.
  *
@@ -70,7 +89,9 @@ export function hasLocalScreenshots(providerName, config) {
  *   config?: VisualRegressionConfig,
  *   createLocalProvider?: () => VisualProvider,
  *   onSkip?: (error: SnapSkipError) => void,
- *   onFallback?: (error: SnapFallbackError) => void
+ *   onFallback?: (error: SnapFallbackError) => void,
+ *   baselineResolutionStatus?: string,
+ *   baselineResolutionMessage?: string
  * }} options
  * @returns {Promise<{
  *   outcome: 'captured' | 'skipped',
@@ -100,6 +121,9 @@ export async function captureWithPolicy(options) {
     }
     if (error instanceof SnapFallbackError) {
       onFallback(error);
+      if (options.baselineResolutionStatus === 'error') {
+        throw createBaselineLookupFallbackError(error, 'capture', options.baselineResolutionMessage);
+      }
       const result = await createLocalProvider().capture(options.captureOptions);
       // The rest of the pipeline must be told the *effective* provider, not the
       // configured one — otherwise it rebuilds SnapProvider around local output.
@@ -134,7 +158,9 @@ export async function captureWithPolicy(options) {
  *   onSkip?: (error: SnapSkipError) => void,
  *   onFallback?: (error: SnapFallbackError) => void,
  *   onRecapture?: () => void,
- *   onBaselineUnavailable?: () => void
+ *   onBaselineUnavailable?: () => void,
+ *   baselineResolutionStatus?: string,
+ *   baselineResolutionMessage?: string
  * }} options
  * @returns {Promise<{
  *   outcome: 'diffed' | 'skipped' | 'baseline-unavailable',
@@ -170,9 +196,16 @@ export async function diffWithPolicy(options) {
       : Boolean(options.diffOptions.baselineResultsPath);
     if (!baselineAvailable) {
       onBaselineUnavailable();
+      if (options.baselineResolutionStatus === 'error') {
+        throw createBaselineLookupFallbackError(error, 'diff', options.baselineResolutionMessage);
+      }
       return { outcome: 'baseline-unavailable', providerName: 'local' };
     }
 
+    if (options.baselineResolutionStatus === 'error') {
+      throw createBaselineLookupFallbackError(error, 'diff', options.baselineResolutionMessage);
+    }
+
     const localProvider = createLocalProvider();
     let diffOptions = options.diffOptions;
     /** @type {CaptureResult | undefined} */

package/lib/provider.mjs

@@ -1,8 +1,16 @@
 // @ts-check
 
-import { runBaselineCapture, generateDriftReport, stageArtifacts } from '@snapdrift/adapter-fs';
+import { loadSnapdriftConfig, runBaselineCapture, generateDriftReport, stageArtifacts } from '@snapdrift/adapter-fs';
 import { buildReportCommentBody } from '@snapdrift/adapter-report-md';
-import { SnapProvider, SnapApiError, SnapUnavailableError, SnapFallbackError, SnapSkipError, isLocalBaseUrl } from './snap-provider.mjs';
+import {
+  SnapProvider,
+  SnapApiError,
+  SnapUpgradeRequiredError,
+  SnapUnavailableError,
+  SnapFallbackError,
+  SnapSkipError,
+  isLocalBaseUrl
+} from './snap-provider.mjs';
 
 /** @typedef {import('../types/visual-diff-types').VisualProvider} VisualProvider */
 /** @typedef {import('../types/visual-diff-types').ProviderCaptureOptions} CaptureOptions */
@@ -35,7 +43,12 @@ export class LocalProvider {
    * @returns {Promise<DiffResult>}
    */
   async diff(options) {
-    return generateDriftReport(options);
+    const { config } = await loadSnapdriftConfig(options.configPath);
+    const comparisonPolicy = config.diff.comparisonPolicy ?? {
+      version: 1,
+      threshold: config.diff.threshold
+    };
+    return generateDriftReport({ ...options, comparisonPolicy });
   }
 
   /**
@@ -55,8 +68,7 @@ export class LocalProvider {
    */
   async fetchLatestBaseline(_options) {
     throw new Error(
-      'LocalProvider.fetchLatestBaseline is not yet implemented. ' +
-      'Use the pr-diff action for baseline resolution, or wait for a future release.'
+      'LocalProvider.fetchLatestBaseline is not yet implemented. ' + 'Use the pr-diff action for baseline resolution, or wait for a future release.'
     );
   }
 
@@ -64,7 +76,7 @@ export class LocalProvider {
    * Build a PR comment body from a diff summary.
    * LocalProvider omits the dashboard link (no dashboard exists).
    *
-   * @param {Record<string, unknown>} summary
+   * @param {import('@snapdrift/manifest').VisualReportSummary} summary
    * @param {import('../types/visual-diff-types').ProviderCommentMeta} [meta]
    * @returns {string}
    */
@@ -73,7 +85,7 @@ export class LocalProvider {
   }
 }
 
-/** @type {Record<string, (config?: VisualRegressionConfig) => VisualProvider>} */
+/** @type {{ local: (config?: VisualRegressionConfig) => LocalProvider, snap: (config: VisualRegressionConfig) => SnapProvider }} */
 const PROVIDER_FACTORIES = {
   local: () => new LocalProvider(),
   snap: (config) => {
@@ -84,6 +96,24 @@ const PROVIDER_FACTORIES = {
   }
 };
 
+/**
+ * @overload
+ * @param {'snap'} providerName
+ * @param {VisualRegressionConfig} config
+ * @returns {SnapProvider}
+ */
+/**
+ * @overload
+ * @param {'local'} providerName
+ * @param {VisualRegressionConfig} [config]
+ * @returns {LocalProvider}
+ */
+/**
+ * @overload
+ * @param {string} providerName
+ * @param {VisualRegressionConfig} [config]
+ * @returns {VisualProvider}
+ */
 /**
  * Create a VisualProvider instance by name.
  *
@@ -95,12 +125,9 @@ const PROVIDER_FACTORIES = {
 export function createProvider(providerName, config) {
   const factory = PROVIDER_FACTORIES[providerName];
   if (!factory) {
-    throw new Error(
-      `Unknown SnapDrift provider: "${providerName}". ` +
-      `Available providers: ${Object.keys(PROVIDER_FACTORIES).join(', ')}.`
-    );
+    throw new Error(`Unknown SnapDrift provider: "${providerName}". ` + `Available providers: ${Object.keys(PROVIDER_FACTORIES).join(', ')}.`);
   }
   return factory(config);
 }
 
-export { SnapProvider, SnapApiError, SnapUnavailableError, SnapFallbackError, SnapSkipError, isLocalBaseUrl };
+export { SnapProvider, SnapApiError, SnapUpgradeRequiredError, SnapUnavailableError, SnapFallbackError, SnapSkipError, isLocalBaseUrl };

package/lib/report.mjs

@@ -26,14 +26,15 @@ async function defaultImageReader(runDir, imagePath) {
  * @param {{
  *   baselineRunDir?: string,
  *   currentRunDir?: string,
+ *   diffRunDir?: string,
  *   imageReader?: (runDir: string, imagePath: string) => Promise<string | null>
  * }} [options]
  * @returns {Promise<string>}
  */
 export async function generateHtmlReport(summary, options = {}) {
   const enrichedOptions = { ...options };
-  if (!enrichedOptions.imageReader && (options.baselineRunDir || options.currentRunDir)) {
+  if (!enrichedOptions.imageReader && (options.baselineRunDir || options.currentRunDir || options.diffRunDir)) {
     enrichedOptions.imageReader = defaultImageReader;
   }
   return _generateHtmlReport(summary, enrichedOptions);
-}
+}

package/lib/resolve-baseline-artifact.mjs

@@ -0,0 +1,147 @@
+// @ts-check
+
+/**
+ * @typedef {{
+ *   found: boolean,
+ *   resolutionStatus: 'found' | 'missing',
+ *   artifactName: string,
+ *   headSha?: string,
+ *   runId?: string,
+ *   message: string
+ * }} BaselineResolution
+ */
+
+/**
+ * Resolve the most recent successful, non-expired SnapDrift baseline artifact.
+ *
+ * The GitHub API calls are kept here so the standalone resolver and the PR
+ * wrapper share the same response validation and pagination behavior.
+ *
+ * @param {{
+ *   github: {
+ *     paginate: Function,
+ *     rest: { actions: {
+ *       listWorkflowRuns: Function,
+ *       listWorkflowRunArtifacts: Function
+ *     }}
+ *   },
+ *   repository: string,
+ *   workflowId: string,
+ *   branch: string,
+ *   artifactName: string
+ * }} options
+ * @returns {Promise<BaselineResolution>}
+ */
+export async function resolveBaselineArtifact({
+  github,
+  repository,
+  workflowId,
+  branch,
+  artifactName
+}) {
+  const { owner, repo } = parseBaselineRepository(repository);
+  if (typeof artifactName !== 'string' || artifactName.trim().length === 0) {
+    throw new Error('Invalid baseline artifact name. Expected a non-empty name.');
+  }
+
+  // Search the complete successful-run history so an older, still-valid
+  // baseline remains discoverable; 100 keeps that intentional search to the
+  // fewest API pages GitHub allows.
+  const runs = await github.paginate(github.rest.actions.listWorkflowRuns, {
+    owner,
+    repo,
+    workflow_id: workflowId,
+    branch,
+    event: 'push',
+    per_page: 100
+  });
+
+  if (!Array.isArray(runs)) {
+    throw new Error('GitHub returned an invalid workflow run list.');
+  }
+
+  for (const run of runs) {
+    validateWorkflowRun(run);
+
+    // GitHub returns a null conclusion for queued and in-progress runs. They
+    // are valid records and must be ignored before inspecting terminal fields.
+    if (run.status !== 'completed') {
+      continue;
+    }
+    if (typeof run.conclusion !== 'string') {
+      throw new Error(`GitHub returned a malformed completed workflow run record for run ${run.id}.`);
+    }
+    if (run.conclusion !== 'success') {
+      continue;
+    }
+
+    const artifacts = await github.paginate(github.rest.actions.listWorkflowRunArtifacts, {
+      owner,
+      repo,
+      run_id: run.id,
+      per_page: 100
+    });
+    if (!Array.isArray(artifacts)) {
+      throw new Error(`GitHub returned a malformed artifact list for workflow run ${run.id}.`);
+    }
+
+    // Only the artifact SnapDrift depends on needs strict field validation.
+    // Other artifacts in the same run belong to the consumer workflow and may
+    // legitimately have a different shape.
+    const namedArtifacts = artifacts.filter((artifact) => (
+      artifact && typeof artifact === 'object' && artifact.name === artifactName
+    ));
+    for (const artifact of namedArtifacts) {
+      if (typeof artifact.expired !== 'boolean') {
+        throw new Error(`GitHub returned a malformed baseline artifact record for workflow run ${run.id}.`);
+      }
+    }
+
+    const match = namedArtifacts.find((artifact) => !artifact.expired);
+    if (match) {
+      return {
+        found: true,
+        resolutionStatus: 'found',
+        artifactName: match.name,
+        headSha: run.head_sha,
+        runId: String(run.id),
+        message: ''
+      };
+    }
+  }
+
+  return {
+    found: false,
+    resolutionStatus: 'missing',
+    artifactName,
+    message: `No non-expired SnapDrift baseline artifact named ${artifactName} was found.`
+  };
+}
+
+/**
+ * @param {string} repository
+ * @returns {{owner: string, repo: string}}
+ */
+export function parseBaselineRepository(repository) {
+  const value = String(repository || '').trim();
+  const parts = value.split('/');
+  if (parts.length !== 2 || parts.some((part) => part.trim().length === 0)) {
+    throw new Error(`Invalid baseline repository "${value}". Expected owner/name.`);
+  }
+  return { owner: parts[0].trim(), repo: parts[1].trim() };
+}
+
+/**
+ * @param {unknown} run
+ * @returns {asserts run is {id: number, status: string, head_sha: string, conclusion?: unknown}}
+ */
+function validateWorkflowRun(run) {
+  if (!run || typeof run !== 'object') {
+    throw new Error('GitHub returned a malformed workflow run record.');
+  }
+  const record = /** @type {Record<string, unknown>} */ (run);
+  if (typeof record.id !== 'number' || !Number.isInteger(record.id) || record.id <= 0 ||
+      typeof record.status !== 'string' || typeof record.head_sha !== 'string' || record.head_sha.length === 0) {
+    throw new Error('GitHub returned a malformed workflow run record.');
+  }
+}

package/lib/resolve-baseline-paths.mjs

@@ -0,0 +1,40 @@
+// @ts-check
+
+import path from 'node:path';
+
+/**
+ * @typedef {{
+ *   runDir: string,
+ *   resultsFile: string,
+ *   manifestFile: string,
+ *   screenshotsDir: string,
+ * }} BaselinePaths
+ */
+
+/**
+ * @typedef {{
+ *   workspace: string,
+ *   downloadPath?: string,
+ * }} ResolveBaselinePathsParams
+ */
+
+const DEFAULT_DOWNLOAD_PATH = 'snapdrift-baseline-download';
+
+/**
+ * Resolve the baseline download paths for the resolve-baseline composite action.
+ *
+ * `downloadPath` may be absolute (used directly) or relative to the Actions
+ * workspace (prefixed with `workspace`). Returns the run dir plus the results,
+ * manifest, and screenshots paths derived from it.
+ *
+ * @param {ResolveBaselinePathsParams} params
+ * @returns {BaselinePaths}
+ */
+export function resolveBaselinePaths({ workspace, downloadPath }) {
+  const rel = downloadPath || DEFAULT_DOWNLOAD_PATH;
+  const runDir = path.isAbsolute(rel) ? rel : path.join(workspace, rel);
+  const resultsFile = path.join(runDir, 'results.json');
+  const manifestFile = path.join(runDir, 'manifest.json');
+  const screenshotsDir = path.join(path.dirname(manifestFile), 'screenshots');
+  return { runDir, resultsFile, manifestFile, screenshotsDir };
+}