snapdrift 0.8.1 → 0.9.0

package/lib/cli.mjs

@@ -1,13 +1,13 @@
 // @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';
 
 import { loadSnapdriftConfig } from '@snapdrift/adapter-fs';
 import { shouldFailDriftCheck } from '@snapdrift/manifest';
 import { createProvider } from './provider.mjs';
-import { SnapFallbackError, SnapSkipError } from './snap-provider.mjs';
+import { captureWithPolicy, diffWithPolicy, publishBaselineWithPolicy } from './outage-policy.mjs';
 import { generateHtmlReport } from './report.mjs';
 
 /** @typedef {import('../types/visual-diff-types').VisualDiffSummary} DriftSummary */
@@ -39,7 +39,8 @@ export const LOCAL_DIFF_SUBDIR = 'diff';
  * Supported flags:
  *   --open              Open the HTML report after diff
  *   --config <path>     Path to snapdrift.json (default: .github/snapdrift.json)
- *   --routes <ids>      Comma-separated route IDs to run
+ *   --routes <ids>      Comma-separated route IDs (diff/capture/local baseline;
+ *                       hosted baselines require the complete configured set)
  *   --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)
@@ -48,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}
  */
@@ -70,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 };
 }
@@ -162,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.
  *
@@ -180,36 +265,33 @@ function openFile(filePath) {
 export async function runCaptureCommand(opts) {
   process.stdout.write(`Capturing baseline to ${opts.baselineDir} ...\n`);
   const { config } = await loadSnapdriftConfig(opts.configPath);
-  const provider = createProvider(config.provider ?? 'local', config);
-  try {
-    const { selectedRouteIds } = await provider.capture({
+  const providerName = config.provider ?? 'local';
+  const provider = createProvider(providerName, config);
+
+  // onUnavailable: warn-and-skip — the user asked not to fail the build when
+  // Snap is down. `diff` and `baseline` both honour this; `capture` used to
+  // let SnapSkipError reach bin/snapdrift.mjs, which exits 1. See #108.
+  const captured = await captureWithPolicy({
+    provider,
+    providerName,
+    config,
+    captureOptions: {
       configPath: opts.configPath,
       routeIds: opts.routes.length > 0 ? opts.routes : undefined,
       outDir: opts.baselineDir,
-      purpose: 'baseline'
-    });
-    process.stdout.write(`Captured ${selectedRouteIds.length} route(s) to ${opts.baselineDir}\n`);
-  } catch (error) {
-    // onUnavailable: warn-and-skip — the user asked not to fail the build when
-    // Snap is down. `diff` and `baseline` both honour this; `capture` used to
-    // let SnapSkipError reach bin/snapdrift.mjs, which exits 1. See #108.
-    if (error instanceof SnapSkipError) {
-      process.stdout.write('Capture skipped (Snap unavailable, warn-and-skip mode).\n');
-      return;
-    }
-    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;
+      purpose: 'capture'
+    },
+    onSkip: () => process.stdout.write('Capture skipped (Snap unavailable, warn-and-skip mode).\n'),
+    onFallback: () => process.stdout.write('Falling back to local provider for capture...\n')
+  });
+
+  if (captured.outcome === 'skipped') {
+    return;
   }
+
+  process.stdout.write(
+    `Captured ${captured.result.selectedRouteIds.length} route(s) to ${opts.baselineDir}\n`
+  );
 }
 
 /**
@@ -240,79 +322,65 @@ export async function runBaselineCommand(opts) {
       : `Capturing baseline to ${opts.baselineDir} ...\n`
   );
 
-  /** Capture locally so `fallback-local` still leaves the user with a baseline. */
-  async function captureLocalFallback() {
-    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
-    });
+  /** @type {import('../types/visual-diff-types').ProviderCaptureOptions} */
+  const captureOptions = {
+    configPath: opts.configPath,
+    routeIds: opts.routes.length > 0 ? opts.routes : undefined,
+    outDir: opts.baselineDir,
+    purpose: 'baseline'
+  };
+
+  const onFallback = () => process.stdout.write('Falling back to local provider for capture...\n');
+
+  // Snap can go down during *either* phase — the capture submission or the
+  // publish that follows it — and the user's `onUnavailable` choice must hold
+  // for both, otherwise `warn-and-skip` still exits 1 and `fallback-local`
+  // still leaves them with no baseline.
+  const captured = await captureWithPolicy({
+    provider,
+    providerName,
+    config,
+    captureOptions,
+    onSkip: () => process.stdout.write('Baseline skipped (Snap unavailable, warn-and-skip mode).\n'),
+    onFallback
+  });
+
+  if (captured.outcome === 'skipped') {
+    return;
+  }
+
+  if (captured.providerName !== 'snap') {
+    const suffix = providerName === 'snap' ? ' (local fallback — nothing published to Snap)' : '';
     process.stdout.write(
-      `Captured ${selectedRouteIds.length} route(s) to ${opts.baselineDir} (local fallback — nothing published to Snap)\n`
+      `Captured ${captured.result.selectedRouteIds.length} route(s) to ${opts.baselineDir}${suffix}\n`
     );
+    return;
   }
 
-  /**
-   * Apply the configured `onUnavailable` behaviour. Snap can go down during
-   * *either* phase — the capture submission or the publish that follows it — and
-   * the user's choice must hold for both, otherwise `warn-and-skip` still exits 1
-   * and `fallback-local` still leaves them with no baseline.
-   *
-   * @param {unknown} error
-   * @param {string} skipMessage
-   * @returns {Promise<boolean>} true when the error was absorbed
-   */
-  async function handleUnavailable(error, skipMessage) {
-    if (error instanceof SnapSkipError) {
-      process.stdout.write(skipMessage);
-      return true;
-    }
-    if (error instanceof SnapFallbackError) {
-      await captureLocalFallback();
-      return true;
-    }
-    return false;
-  }
+  process.stdout.write(
+    `Captured ${captured.result.selectedRouteIds.length} route(s); waiting for Snap to finish rendering ...\n`
+  );
 
-  /** @type {{ resultsPath?: string, selectedRouteIds: string[] }} */
-  let captured;
-  try {
-    captured = await provider.capture({
-      configPath: opts.configPath,
-      routeIds: opts.routes.length > 0 ? opts.routes : undefined,
-      outDir: opts.baselineDir,
-      purpose: 'baseline'
-    });
-  } catch (error) {
-    if (await handleUnavailable(error, 'Baseline skipped (Snap unavailable, warn-and-skip mode).\n')) {
-      return;
-    }
-    throw error;
-  }
+  const published = await publishBaselineWithPolicy({
+    provider,
+    publishOptions: { resultsPath: captured.result.resultsPath },
+    captureOptions,
+    onSkip: () =>
+      process.stdout.write('Baseline publish skipped (Snap unavailable, warn-and-skip mode).\n'),
+    onFallback
+  });
 
-  if (providerName !== 'snap') {
-    process.stdout.write(`Captured ${captured.selectedRouteIds.length} route(s) to ${opts.baselineDir}\n`);
+  if (published.outcome === 'skipped') {
     return;
   }
 
-  process.stdout.write(
-    `Captured ${captured.selectedRouteIds.length} route(s); waiting for Snap to finish rendering ...\n`
-  );
-  try {
-    await provider.publishBaseline({ resultsPath: captured.resultsPath });
-  } catch (error) {
-    if (
-      await handleUnavailable(
-        error,
-        'Baseline publish skipped (Snap unavailable, warn-and-skip mode).\n'
-      )
-    ) {
-      return;
-    }
-    throw error;
+  if (published.outcome === 'fell-back') {
+    process.stdout.write(
+      `Captured ${published.recapture?.selectedRouteIds.length ?? 0} route(s) to ${opts.baselineDir} (local fallback — nothing published to Snap)\n`
+    );
+    return;
   }
+
   process.stdout.write('Snap baseline published successfully.\n');
 }
 
@@ -326,31 +394,32 @@ export async function runBaselineCommand(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 providerName = config.provider ?? 'local';
+  const provider = createProvider(providerName, config);
 
-  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;
-    }
+  /** @type {import('../types/visual-diff-types').ProviderCaptureOptions} */
+  const captureOptions = {
+    configPath: opts.configPath,
+    routeIds: opts.routes.length > 0 ? opts.routes : undefined,
+    outDir: opts.currentDir
+  };
+
+  const captured = await captureWithPolicy({
+    provider,
+    providerName,
+    config,
+    captureOptions,
+    onSkip: () =>
+      process.stdout.write('Visual regression skipped (Snap unavailable, warn-and-skip mode).\n'),
+    onFallback: () => process.stdout.write('Falling back to local provider for capture...\n')
+  });
+
+  if (captured.outcome === 'skipped') {
+    return;
   }
 
+  const currentCapture = captured.result;
+
   process.stdout.write('Comparing against baseline ...\n');
 
   const baselineResultsPath = path.join(opts.baselineDir, path.basename(config.resultsFile));
@@ -361,10 +430,12 @@ export async function runDiffCommand(opts) {
   const markdownPath = path.join(opts.diffDir, 'summary.md');
   const htmlPath = path.join(opts.diffDir, 'report.html');
 
-  const diffProvider = usedLocalFallback ? createProvider('local') : provider;
-  let diffResult;
-  try {
-    diffResult = await diffProvider.diff({
+  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,
@@ -373,20 +444,24 @@ export async function runDiffCommand(opts) {
       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;
+    },
+    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'),
+    onRecapture: () =>
+      process.stdout.write('Recapturing locally so the local diff has screenshots to compare...\n')
+  });
+
+  if (diffed.outcome !== 'diffed') {
+    return;
   }
 
-  const { summary, markdown } = diffResult;
+  const { summary, markdown } = diffed.result;
+  const currentRunDir = diffed.recapture?.screenshotsRoot ?? currentCapture.screenshotsRoot;
 
   const html = await generateHtmlReport(summary, {
     baselineRunDir: opts.baselineDir,
-    currentRunDir: currentCapture.screenshotsRoot
+    currentRunDir
   });
 
   await Promise.all([
@@ -485,4 +560,4 @@ export async function main(argv) {
     );
     process.exitCode = 1;
   }
-}
+}

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',