🐛 Make finalize command resilient to missing builds

The finalize command now handles 404 errors gracefully instead of
failing CI. When no build exists for a parallel ID (e.g., tests were
skipped or no screenshots uploaded), it warns and exits 0.

Added global --strict flag for users who want hard failures on any
error. This flag is available on all commands.

Closes VIZ-108

Author: Robdel12

src/cli.js

@@ -236,6 +236,7 @@ program
   .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 });
 
 // Load plugins before defining commands

src/commands/finalize.js

@@ -96,13 +96,42 @@ export async function finalizeCommand(
   } catch (error) {
     output.stopSpinner();
 
-    // Don't fail CI for Vizzly infrastructure issues (5xx errors)
     let status = error.context?.status;
+
+    // Don't fail CI for Vizzly infrastructure issues (5xx errors)
     if (status >= 500) {
       output.warn('Vizzly API unavailable - finalize skipped.');
       return { success: true, result: { skipped: true } };
     }
 
+    // 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:');
+        output.info('  • No screenshots were uploaded with this parallel-id');
+        output.info('  • Tests were skipped or failed before capturing screenshots');
+        output.info('  • The parallel-id does not match what was used during test runs');
+        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:');
+        output.info('  • No screenshots were uploaded with this parallel-id');
+        output.info('  • Tests were skipped or failed before capturing screenshots');
+        output.info('  • The parallel-id does not match what was used during test runs');
+        output.info('Use --strict flag to fail CI when no build is found.');
+      }
+      return { success: true, result: { skipped: true, reason: 'no-build-found' } };
+    }
+
     output.error('Failed to finalize parallel build', error);
     exit(1);
     return { success: false, error };

tests/commands/finalize.test.js

@@ -339,5 +339,117 @@ describe('commands/finalize', () => {
         )
       );
     });
+
+    it('does not fail CI when no build found (404) in non-strict mode', async () => {
+      let output = createMockOutput();
+      let exitCode = null;
+
+      let apiError = new Error('API request failed: 404 - Not Found');
+      apiError.context = { status: 404 };
+
+      let result = await finalizeCommand(
+        'parallel-123',
+        {},
+        {},
+        {
+          loadConfig: async () => ({
+            apiKey: 'test-token',
+            apiUrl: 'https://api.test',
+          }),
+          createApiClient: () => ({ request: async () => ({}) }),
+          finalizeParallelBuild: async () => {
+            throw apiError;
+          },
+          output,
+          exit: code => {
+            exitCode = code;
+          },
+        }
+      );
+
+      assert.strictEqual(result.success, true);
+      assert.strictEqual(result.result.skipped, true);
+      assert.strictEqual(result.result.reason, 'no-build-found');
+      assert.strictEqual(exitCode, null);
+      assert.ok(
+        output.calls.some(
+          c => c.method === 'warn' && c.args[0].includes('No build found')
+        )
+      );
+    });
+
+    it('fails CI when no build found (404) in strict mode', async () => {
+      let output = createMockOutput();
+      let exitCode = null;
+
+      let apiError = new Error('API request failed: 404 - Not Found');
+      apiError.context = { status: 404 };
+
+      let result = await finalizeCommand(
+        'parallel-123',
+        {},
+        { strict: true },
+        {
+          loadConfig: async () => ({
+            apiKey: 'test-token',
+            apiUrl: 'https://api.test',
+          }),
+          createApiClient: () => ({ request: async () => ({}) }),
+          finalizeParallelBuild: async () => {
+            throw apiError;
+          },
+          output,
+          exit: code => {
+            exitCode = code;
+          },
+        }
+      );
+
+      assert.strictEqual(result.success, false);
+      assert.strictEqual(result.reason, 'no-build-found');
+      assert.strictEqual(exitCode, 1);
+      assert.ok(
+        output.calls.some(
+          c => c.method === 'error' && c.args[0].includes('No build found')
+        )
+      );
+    });
+
+    it('shows verbose hints when no build found in non-strict mode', async () => {
+      let output = createMockOutput();
+
+      let apiError = new Error('API request failed: 404 - Not Found');
+      apiError.context = { status: 404 };
+
+      await finalizeCommand(
+        'parallel-123',
+        {},
+        { verbose: true },
+        {
+          loadConfig: async () => ({
+            apiKey: 'test-token',
+            apiUrl: 'https://api.test',
+          }),
+          createApiClient: () => ({ request: async () => ({}) }),
+          finalizeParallelBuild: async () => {
+            throw apiError;
+          },
+          output,
+          exit: () => {},
+        }
+      );
+
+      // Should show helpful hints in verbose mode
+      assert.ok(
+        output.calls.some(
+          c => c.method === 'info' && c.args[0].includes('Possible reasons')
+        )
+      );
+      assert.ok(
+        output.calls.some(
+          c => c.method === 'info' && c.args[0].includes('--strict')
+        )
+      );
+    });
   });
 });