@vizzly-testing/cli 0.24.1 → 0.25.1

package/dist/cli.js

@@ -188,7 +188,7 @@ const formatHelp = (cmd, helper) => {
   lines.push('');
   return lines.join('\n');
 };
-program.name('vizzly').description('Vizzly CLI for visual regression testing').version(getPackageVersion()).option('-c, --config <path>', 'Config file path').option('--token <token>', 'Vizzly API token').option('-v, --verbose', 'Verbose output (shorthand for --log-level debug)').option('--log-level <level>', 'Log level: debug, info, warn, error (default: info, or VIZZLY_LOG_LEVEL env var)').option('--json', 'Machine-readable output').option('--color', 'Force colored output (even in non-TTY)').option('--no-color', 'Disable colored output').configureHelp({
+program.name('vizzly').description('Vizzly CLI for visual regression testing').version(getPackageVersion()).option('-c, --config <path>', 'Config file path').option('--token <token>', 'Vizzly API token').option('-v, --verbose', 'Verbose output (shorthand for --log-level debug)').option('--log-level <level>', 'Log level: debug, info, warn, error (default: info, or VIZZLY_LOG_LEVEL env var)').option('--json', 'Machine-readable output').option('--color', 'Force colored output (even in non-TTY)').option('--no-color', 'Disable colored output').option('--strict', 'Fail on any error (default: be resilient, warn on non-critical issues)').configureHelp({
   formatHelp
 });
 
@@ -412,7 +412,7 @@ program.command('finalize').description('Finalize a parallel build after all sha
   }
   await finalizeCommand(parallelId, options, globalOptions);
 });
-program.command('preview').description('Upload static files as a preview for a build').argument('[path]', 'Path to static files (dist/, build/, out/)').option('-b, --build <id>', 'Build ID to attach preview to').option('-p, --parallel-id <id>', 'Look up build by parallel ID').option('--base <path>', 'Override auto-detected base path').option('--open', 'Open preview URL in browser after upload').option('--dry-run', 'Show what would be uploaded without uploading').option('-x, --exclude <pattern>', 'Exclude files/dirs (repeatable, e.g. -x "*.log" -x "temp/")', (val, prev) => prev ? [...prev, val] : [val]).option('-i, --include <pattern>', 'Override default exclusions (repeatable, e.g. -i package.json -i tests/)', (val, prev) => prev ? [...prev, val] : [val]).action(async (path, options) => {
+program.command('preview').description('Upload static files as a preview for a build').argument('[path]', 'Path to static files (dist/, build/, out/)').option('-b, --build <id>', 'Build ID to attach preview to').option('-p, --parallel-id <id>', 'Look up build by parallel ID').option('--base <path>', 'Override auto-detected base path').option('--open', 'Open preview URL in browser after upload').option('--dry-run', 'Show what would be uploaded without uploading').option('--public-link', 'Acknowledge that preview URL grants access to anyone with the link (required for private projects)').option('-x, --exclude <pattern>', 'Exclude files/dirs (repeatable, e.g. -x "*.log" -x "temp/")', (val, prev) => prev ? [...prev, val] : [val]).option('-i, --include <pattern>', 'Override default exclusions (repeatable, e.g. -i package.json -i tests/)', (val, prev) => prev ? [...prev, val] : [val]).action(async (path, options) => {
   const globalOptions = program.opts();
 
   // Show helpful error if path is missing

package/dist/commands/finalize.js

@@ -7,6 +7,7 @@ import { createApiClient as defaultCreateApiClient, finalizeParallelBuild as def
 import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
 import * as defaultOutput from '../utils/output.js';
 import { writeSession as defaultWriteSession } from '../utils/session.js';
+let MISSING_BUILD_HINTS = ['  • No screenshots were uploaded with this parallel-id', '  • Tests were skipped or failed before capturing screenshots', '  • The parallel-id does not match what was used during test runs'];
 
 /**
  * Finalize command implementation
@@ -89,15 +90,54 @@ export async function finalizeCommand(parallelId, options = {}, globalOptions =
     };
   } catch (error) {
     output.stopSpinner();
+    let status = error.context?.status;
 
     // Don't fail CI for Vizzly infrastructure issues (5xx errors)
-    let status = error.context?.status;
+    // Note: --strict does NOT affect 5xx handling - infrastructure issues are out of user's control
     if (status >= 500) {
       output.warn('Vizzly API unavailable - finalize skipped.');
       return {
         success: true,
         result: {
-          skipped: true
+          skipped: true,
+          reason: 'api-unavailable'
+        }
+      };
+    }
+
+    // Handle missing builds gracefully (404 errors)
+    // This happens when: no screenshots were uploaded, tests were skipped, or parallel-id doesn't exist
+    if (status === 404) {
+      let isStrict = globalOptions.strict;
+      if (isStrict) {
+        output.error(`No build found for parallel ID: ${parallelId}`);
+        output.blank();
+        output.info('This can happen when:');
+        for (let hint of MISSING_BUILD_HINTS) {
+          output.info(hint);
+        }
+        exit(1);
+        return {
+          success: false,
+          reason: 'no-build-found',
+          error
+        };
+      }
+
+      // Non-strict mode: warn but don't fail CI
+      output.warn(`No build found for parallel ID: ${parallelId} - finalize skipped.`);
+      if (globalOptions.verbose) {
+        output.info('Possible reasons:');
+        for (let hint of MISSING_BUILD_HINTS) {
+          output.info(hint);
+        }
+        output.info('Use --strict flag to fail CI when no build is found.');
+      }
+      return {
+        success: true,
+        result: {
+          skipped: true,
+          reason: 'no-build-found'
         }
       };
     }

package/dist/commands/preview.js

@@ -12,7 +12,7 @@ import { readFile, realpath, stat, unlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { promisify } from 'node:util';
-import { createApiClient as defaultCreateApiClient, uploadPreviewZip as defaultUploadPreviewZip } from '../api/index.js';
+import { createApiClient as defaultCreateApiClient, getBuild as defaultGetBuild, uploadPreviewZip as defaultUploadPreviewZip } from '../api/index.js';
 import { openBrowser as defaultOpenBrowser } from '../utils/browser.js';
 import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
 import { detectBranch as defaultDetectBranch } from '../utils/git.js';
@@ -273,6 +273,7 @@ export async function previewCommand(path, options = {}, globalOptions = {}, dep
   let {
     loadConfig = defaultLoadConfig,
     createApiClient = defaultCreateApiClient,
+    getBuild = defaultGetBuild,
     uploadPreviewZip = defaultUploadPreviewZip,
     readSession = defaultReadSession,
     formatSessionAge = defaultFormatSessionAge,
@@ -377,6 +378,59 @@ export async function previewCommand(path, options = {}, globalOptions = {}, dep
       };
     }
 
+    // Create API client for non-dry-run operations (reused for visibility check and upload)
+    let client;
+    if (!options.dryRun) {
+      client = createApiClient({
+        baseUrl: config.apiUrl,
+        token: config.apiKey,
+        command: 'preview'
+      });
+
+      // Check project visibility for private projects
+      let buildResponse;
+      try {
+        buildResponse = await getBuild(client, buildId);
+      } catch (error) {
+        if (error.status === 404) {
+          output.error(`Build not found: ${buildId}`);
+        } else {
+          output.error('Failed to verify project visibility', error);
+        }
+        exit(1);
+        // Return is for testing (exit is mocked in tests)
+        return {
+          success: false,
+          reason: 'build-fetch-failed',
+          error
+        };
+      }
+
+      // Check if project is private and user hasn't acknowledged public link access
+      // Note: API returns { build, project } at top level, not nested
+      // Use === false to handle undefined/missing isPublic defensively
+      let project = buildResponse.project;
+      let isPrivate = project && project.isPublic === false;
+      if (isPrivate && !options.publicLink) {
+        output.error('This project is private.');
+        output.blank();
+        output.print('  Preview URLs grant access to anyone with the link (until expiration).');
+        output.blank();
+        output.print('  To proceed, acknowledge this by using:');
+        output.blank();
+        output.print('    vizzly preview ./dist --public-link');
+        output.blank();
+        output.print('  Or set your project to public in Vizzly settings.');
+        output.blank();
+        exit(1);
+        // Return is for testing (exit is mocked in tests)
+        return {
+          success: false,
+          reason: 'private-project-no-flag'
+        };
+      }
+    }
+
     // Check for zip command availability (skip for dry-run)
     if (!options.dryRun) {
       let zipInfo = getZipCommand();
@@ -532,13 +586,8 @@ export async function previewCommand(path, options = {}, globalOptions = {}, dep
     let compressionRatio = ((1 - zipBuffer.length / totalSize) * 100).toFixed(0);
     output.updateSpinner(`Compressed to ${formatBytes(zipBuffer.length)} (${compressionRatio}% smaller)`);
 
-    // Upload
+    // Upload (reuse client created earlier)
     output.updateSpinner('Uploading preview...');
-    let client = createApiClient({
-      baseUrl: config.apiUrl,
-      token: config.apiKey,
-      command: 'preview'
-    });
     let result = await uploadPreviewZip(client, buildId, zipBuffer);
     output.stopSpinner();
 

package/dist/plugin-api.js

@@ -9,10 +9,13 @@
  * exposed to plugins to prevent coupling to implementation details.
  */
 
+import { detectBranch, detectCommit, detectCommitMessage, detectPullRequestNumber, generateBuildNameWithGit } from './utils/git.js';
+
 /**
  * Creates a stable plugin services object from the internal services
  *
  * Only exposes:
+ * - git: Git information detection (branch, commit, PR number, etc.)
  * - testRunner: Build lifecycle management (createBuild, finalizeBuild, events)
  * - serverManager: Screenshot server control (start, stop)
  *
@@ -25,6 +28,29 @@ export function createPluginServices(services) {
     serverManager
   } = services;
   return Object.freeze({
+    // Git detection utilities - provides correct git info from CI environments
+    git: Object.freeze({
+      /**
+       * Detect git information for build creation
+       * Handles CI environment variables correctly (GitHub Actions, GitLab, etc.)
+       *
+       * @param {Object} [options] - Detection options
+       * @param {string} [options.buildPrefix] - Prefix for generated build name
+       * @returns {Promise<Object>} Git info: { branch, commit, message, prNumber, buildName }
+       */
+      async detect(options = {}) {
+        let [branch, commit, message] = await Promise.all([detectBranch(), detectCommit(), detectCommitMessage()]);
+        let prNumber = detectPullRequestNumber();
+        let buildName = await generateBuildNameWithGit(options.buildPrefix);
+        return {
+          branch,
+          commit,
+          message,
+          prNumber,
+          buildName
+        };
+      }
+    }),
     testRunner: Object.freeze({
       // EventEmitter methods for build lifecycle events
       once: testRunner.once.bind(testRunner),