@vizzly-testing/cli 0.25.0 → 0.26.0

package/dist/cli.js

@@ -11,7 +11,7 @@ import { projectListCommand, projectRemoveCommand, projectSelectCommand, project
 import { runCommand, validateRunOptions } from './commands/run.js';
 import { statusCommand, validateStatusOptions } from './commands/status.js';
 import { tddCommand, validateTddOptions } from './commands/tdd.js';
-import { runDaemonChild, tddStartCommand, tddStatusCommand, tddStopCommand } from './commands/tdd-daemon.js';
+import { runDaemonChild, tddListCommand, tddStartCommand, tddStatusCommand, tddStopCommand } from './commands/tdd-daemon.js';
 import { uploadCommand, validateUploadOptions } from './commands/upload.js';
 import { validateWhoamiOptions, whoamiCommand } from './commands/whoami.js';
 import { createPluginServices } from './plugin-api.js';
@@ -22,6 +22,7 @@ import { openBrowser } from './utils/browser.js';
 import { colors } from './utils/colors.js';
 import { loadConfig } from './utils/config-loader.js';
 import { getContext } from './utils/context.js';
+import { saveUserPath } from './utils/global-config.js';
 import * as output from './utils/output.js';
 import { getPackageVersion } from './utils/package-info.js';
 
@@ -188,7 +189,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
 });
 
@@ -300,6 +301,12 @@ tddCmd.command('status').description('Check TDD server status').action(async opt
   await tddStatusCommand(options, globalOptions);
 });
 
+// TDD List - List all running servers (for menubar app integration)
+tddCmd.command('list').description('List all running TDD servers').action(async options => {
+  const globalOptions = program.opts();
+  await tddListCommand(options, globalOptions);
+});
+
 // TDD Run - One-off test run with ephemeral server (generates static report)
 tddCmd.command('run <command>').description('Run tests once in TDD mode with local visual comparisons').option('--port <port>', 'Port for TDD server', '47392').option('--branch <branch>', 'Git branch override').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', parseFloat).option('--token <token>', 'API token override').option('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--baseline-build <id>', 'Use specific build as baseline').option('--baseline-comparison <id>', 'Use specific comparison as baseline').option('--set-baseline', 'Accept current screenshots as new baseline (overwrites existing)').option('--fail-on-diff', 'Fail tests when visual differences are detected').option('--no-open', 'Skip opening report in browser').action(async (command, options) => {
   const globalOptions = program.opts();
@@ -412,7 +419,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
@@ -521,4 +528,8 @@ program.command('project:remove').description('Remove project configuration for
   const globalOptions = program.opts();
   await projectRemoveCommand(options, globalOptions);
 });
+
+// Save user's PATH for menubar app (non-blocking, runs in background)
+// This auto-configures the menubar app so it can find npx/node
+saveUserPath().catch(() => {});
 program.parse();

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/commands/tdd-daemon.js

@@ -1,7 +1,8 @@
 import { spawn } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
+import { getServerRegistry } from '../tdd/server-registry.js';
 import * as output from '../utils/output.js';
 import { tddCommand } from './tdd.js';
 
@@ -16,32 +17,72 @@ export async function tddStartCommand(options = {}, globalOptions = {}) {
     verbose: globalOptions.verbose,
     color: !globalOptions.noColor
   });
+  let registry = getServerRegistry();
+  let colors = output.getColors();
 
-  // Check if server already running
-  if (await isServerRunning(options.port || 47392)) {
-    const port = options.port || 47392;
-    let colors = output.getColors();
-    output.header('tdd', 'local');
-    output.print(`  ${output.statusDot('success')} Already running`);
-    output.blank();
-    output.printBox(colors.brand.info(colors.underline(`http://localhost:${port}`)), {
-      title: 'Dashboard',
-      style: 'branded'
-    });
-    if (options.open) {
-      openDashboard(port);
+  // Check if THIS directory already has a server running
+  let existingServer = registry.find({
+    directory: process.cwd()
+  });
+  if (existingServer) {
+    // Verify it's actually running
+    if (await isServerRunning(existingServer.port)) {
+      output.header('tdd', 'local');
+      output.print(`  ${output.statusDot('success')} Already running`);
+      output.blank();
+      output.printBox(colors.brand.info(colors.underline(`http://localhost:${existingServer.port}`)), {
+        title: 'Dashboard',
+        style: 'branded'
+      });
+      if (options.open) {
+        openDashboard(existingServer.port);
+      }
+      return;
+    } else {
+      // Stale entry - clean it up (registry and local files)
+      registry.unregister({
+        directory: process.cwd()
+      });
+      let vizzlyDir = join(process.cwd(), '.vizzly');
+      let pidFile = join(vizzlyDir, 'server.pid');
+      let serverFile = join(vizzlyDir, 'server.json');
+      if (existsSync(pidFile)) unlinkSync(pidFile);
+      if (existsSync(serverFile)) unlinkSync(serverFile);
     }
-    return;
+  }
+
+  // Determine port: user-specified or auto-allocate
+  let port;
+  let autoAllocated = false;
+  if (options.port) {
+    // User specified a port - use it (will fail if busy)
+    port = options.port;
+
+    // Check if user-specified port is in use
+    if (await isServerRunning(port)) {
+      output.header('tdd', 'local');
+      output.print(`  ${output.statusDot('error')} Port ${port} is already in use`);
+      output.blank();
+      output.hint('Try a different port: vizzly tdd start --port 47393');
+      output.hint('Or let Vizzly auto-allocate: vizzly tdd start');
+      return;
+    }
+  } else {
+    // Auto-allocate an available port
+    // Note: There's a small race window between finding a port and binding.
+    // The registry acts as a soft reservation, and findAvailablePort does
+    // an actual TCP bind test to minimize this window.
+    port = await registry.findAvailablePort();
+    autoAllocated = port !== 47392;
   }
   try {
     // Ensure .vizzly directory exists
-    const vizzlyDir = join(process.cwd(), '.vizzly');
+    let vizzlyDir = join(process.cwd(), '.vizzly');
     if (!existsSync(vizzlyDir)) {
       mkdirSync(vizzlyDir, {
         recursive: true
       });
     }
-    const port = options.port || 47392;
 
     // Show header first so debug messages appear below it
     output.header('tdd', 'local');
@@ -119,7 +160,28 @@ export async function tddStartCommand(options = {}, globalOptions = {}) {
       process.exit(1);
     }
 
-    // Write server info to global location for SDK discovery (iOS/Swift can read this)
+    // Register server in global registry (for menubar app)
+    try {
+      let registry = getServerRegistry();
+
+      // Clean up any stale servers first
+      registry.cleanupStale();
+
+      // Register this server with log file path for menubar to read
+      let serverLogFile = join(process.cwd(), '.vizzly', 'server.log');
+      registry.register({
+        pid: child.pid,
+        port: port,
+        directory: process.cwd(),
+        name: basename(process.cwd()),
+        startedAt: new Date().toISOString(),
+        logFile: serverLogFile
+      });
+    } catch {
+      // Non-fatal
+    }
+
+    // Also write legacy server.json for SDK discovery (backwards compatibility)
     try {
       const globalVizzlyDir = join(homedir(), '.vizzly');
       if (!existsSync(globalVizzlyDir)) {
@@ -138,8 +200,11 @@ export async function tddStartCommand(options = {}, globalOptions = {}) {
       // Non-fatal, SDK can still use health check
     }
 
-    // Get colors for styled output
-    let colors = output.getColors();
+    // Show auto-allocated port message if applicable
+    if (autoAllocated) {
+      output.print(`  ${output.statusDot('info')} Auto-assigned port ${colors.brand.textTertiary(`:${port}`)}`);
+      output.blank();
+    }
 
     // Show dashboard URL in a branded box
     let dashboardUrl = `http://localhost:${port}`;
@@ -177,6 +242,17 @@ export async function tddStartCommand(options = {}, globalOptions = {}) {
 export async function runDaemonChild(options = {}, globalOptions = {}) {
   const vizzlyDir = join(process.cwd(), '.vizzly');
   const port = options.port || 47392;
+
+  // Set up log file for menubar app to read
+  const logFile = join(vizzlyDir, 'server.log');
+
+  // Configure output to write JSON logs to file (before tddCommand configures it)
+  output.configure({
+    logFile,
+    json: globalOptions.json,
+    verbose: globalOptions.verbose,
+    color: !globalOptions.noColor
+  });
   try {
     // Use existing tddCommand but with daemon mode
     const {
@@ -200,7 +276,8 @@ export async function runDaemonChild(options = {}, globalOptions = {}) {
       pid: process.pid,
       port: port,
       startTime: Date.now(),
-      failOnDiff: options.failOnDiff || false
+      failOnDiff: options.failOnDiff || false,
+      logFile: logFile
     };
     writeFileSync(join(vizzlyDir, 'server.json'), JSON.stringify(serverInfo, null, 2));
 
@@ -212,7 +289,18 @@ export async function runDaemonChild(options = {}, globalOptions = {}) {
         const serverFile = join(vizzlyDir, 'server.json');
         if (existsSync(serverFile)) unlinkSync(serverFile);
 
-        // Clean up global server file
+        // Unregister from global registry (for menubar app)
+        try {
+          let registry = getServerRegistry();
+          registry.unregister({
+            port: port,
+            directory: process.cwd()
+          });
+        } catch {
+          // Non-fatal
+        }
+
+        // Clean up legacy global server file
         try {
           const globalServerFile = join(homedir(), '.vizzly', 'server.json');
           if (existsSync(globalServerFile)) unlinkSync(globalServerFile);
@@ -329,12 +417,35 @@ export async function tddStopCommand(options = {}, globalOptions = {}) {
     // Clean up files
     if (existsSync(pidFile)) unlinkSync(pidFile);
     if (existsSync(serverFile)) unlinkSync(serverFile);
+
+    // Unregister from global registry (for menubar app)
+    try {
+      let registry = getServerRegistry();
+      registry.unregister({
+        port: port,
+        directory: process.cwd()
+      });
+    } catch {
+      // Non-fatal
+    }
+    output.print(`  ${output.statusDot('success')} Server stopped`);
   } catch (error) {
     if (error.code === 'ESRCH') {
       // Process not found - clean up stale files
       output.warn('TDD server was not running (cleaning up stale files)');
       if (existsSync(pidFile)) unlinkSync(pidFile);
       if (existsSync(serverFile)) unlinkSync(serverFile);
+
+      // Still unregister from registry
+      try {
+        let registry = getServerRegistry();
+        registry.unregister({
+          port: port,
+          directory: process.cwd()
+        });
+      } catch {
+        // Non-fatal
+      }
     } else {
       output.error('Error stopping TDD server', error);
     }
@@ -475,4 +586,66 @@ function openDashboard(port = 47392) {
     detached: true,
     stdio: 'ignore'
   }).unref();
+}
+
+/**
+ * List all running TDD servers from the global registry
+ * @param {Object} options - Command options
+ * @param {Object} globalOptions - Global CLI options
+ */
+export async function tddListCommand(_options, globalOptions = {}) {
+  output.configure({
+    json: globalOptions.json,
+    verbose: globalOptions.verbose,
+    color: !globalOptions.noColor
+  });
+  let registry = getServerRegistry();
+
+  // Clean up stale servers first
+  let cleaned = registry.cleanupStale();
+  if (cleaned > 0 && globalOptions.verbose) {
+    output.debug('tdd', `Cleaned up ${cleaned} stale server(s)`);
+  }
+  let servers = registry.list();
+
+  // JSON output
+  if (globalOptions.json) {
+    console.log(JSON.stringify({
+      servers
+    }, null, 2));
+    return;
+  }
+
+  // No servers
+  if (servers.length === 0) {
+    output.info('No TDD servers running');
+    output.hint('Start one with: vizzly tdd start');
+    return;
+  }
+
+  // Table output
+  let colors = output.getColors();
+  output.header('tdd', 'servers');
+  output.blank();
+  for (let server of servers) {
+    let uptimeStr = '';
+    if (server.startedAt) {
+      let startTime = new Date(server.startedAt).getTime();
+      let uptime = Math.floor((Date.now() - startTime) / 1000);
+      let hours = Math.floor(uptime / 3600);
+      let minutes = Math.floor(uptime % 3600 / 60);
+      if (hours > 0) uptimeStr += `${hours}h `;
+      if (minutes > 0 || hours > 0) uptimeStr += `${minutes}m`;else uptimeStr = '<1m';
+    }
+    let name = server.name || basename(server.directory);
+    let portStr = colors.brand.textTertiary(`:${server.port}`);
+    let uptimeLabel = uptimeStr ? colors.brand.textMuted(` · ${uptimeStr}`) : '';
+    output.print(`  ${output.statusDot('success')} ${name}${portStr}${uptimeLabel}`);
+    output.print(`    ${colors.brand.textMuted(server.directory)}`);
+    if (globalOptions.verbose) {
+      output.print(`    ${colors.brand.textMuted(`PID: ${server.pid}`)}`);
+    }
+    output.blank();
+  }
+  output.print(`  ${colors.brand.textTertiary(`${servers.length} server(s) running`)}`);
 }