@vizzly-testing/cli 0.25.1 → 0.26.1

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';
 
@@ -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();
@@ -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/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`)}`);
 }

package/dist/tdd/server-registry.js

@@ -0,0 +1,252 @@
+import { execSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * Manages a global registry of running TDD servers at ~/.vizzly/servers.json
+ * Enables the menubar app to discover and manage multiple concurrent servers.
+ */
+export class ServerRegistry {
+  constructor() {
+    this.vizzlyHome = process.env.VIZZLY_HOME || join(homedir(), '.vizzly');
+    this.registryPath = join(this.vizzlyHome, 'servers.json');
+  }
+
+  /**
+   * Ensure the registry directory exists
+   */
+  ensureDirectory() {
+    if (!existsSync(this.vizzlyHome)) {
+      mkdirSync(this.vizzlyHome, {
+        recursive: true
+      });
+    }
+  }
+
+  /**
+   * Read the current registry, returning empty if it doesn't exist
+   */
+  read() {
+    try {
+      if (existsSync(this.registryPath)) {
+        let data = JSON.parse(readFileSync(this.registryPath, 'utf8'));
+        return {
+          version: data.version || 1,
+          servers: data.servers || []
+        };
+      }
+    } catch (_err) {
+      // Corrupted file, start fresh
+      console.warn('Warning: Could not read server registry, starting fresh');
+    }
+    return {
+      version: 1,
+      servers: []
+    };
+  }
+
+  /**
+   * Write the registry to disk
+   */
+  write(registry) {
+    this.ensureDirectory();
+    writeFileSync(this.registryPath, JSON.stringify(registry, null, 2));
+  }
+
+  /**
+   * Register a new server in the registry
+   */
+  register(serverInfo) {
+    // Validate required fields
+    if (!serverInfo.pid || !serverInfo.port || !serverInfo.directory) {
+      throw new Error('Missing required fields: pid, port, directory');
+    }
+    let port = Number(serverInfo.port);
+    let pid = Number(serverInfo.pid);
+    if (Number.isNaN(port) || Number.isNaN(pid)) {
+      throw new Error('Invalid port or pid - must be numbers');
+    }
+    let registry = this.read();
+
+    // Remove any existing entry for this port or directory (shouldn't happen, but be safe)
+    registry.servers = registry.servers.filter(s => s.port !== port && s.directory !== serverInfo.directory);
+
+    // Add the new server
+    registry.servers.push({
+      id: serverInfo.id || randomBytes(8).toString('hex'),
+      port,
+      pid,
+      directory: serverInfo.directory,
+      startedAt: serverInfo.startedAt || new Date().toISOString(),
+      configPath: serverInfo.configPath || null,
+      name: serverInfo.name || null,
+      logFile: serverInfo.logFile || null
+    });
+    this.write(registry);
+    this.notifyMenubar();
+    return registry;
+  }
+
+  /**
+   * Unregister a server by port and/or directory
+   * When both are provided, matches servers with BOTH criteria (AND logic)
+   * When only one is provided, matches servers with that criteria
+   */
+  unregister({
+    port,
+    directory
+  }) {
+    let registry = this.read();
+    let initialCount = registry.servers.length;
+    if (port && directory) {
+      // Both specified - match servers with both port AND directory
+      registry.servers = registry.servers.filter(s => !(s.port === port && s.directory === directory));
+    } else if (port) {
+      registry.servers = registry.servers.filter(s => s.port !== port);
+    } else if (directory) {
+      registry.servers = registry.servers.filter(s => s.directory !== directory);
+    }
+    if (registry.servers.length !== initialCount) {
+      this.write(registry);
+      this.notifyMenubar();
+    }
+    return registry;
+  }
+
+  /**
+   * Find a server by port or directory
+   */
+  find({
+    port,
+    directory
+  }) {
+    let registry = this.read();
+    if (port) {
+      return registry.servers.find(s => s.port === port);
+    }
+    if (directory) {
+      return registry.servers.find(s => s.directory === directory);
+    }
+    return null;
+  }
+
+  /**
+   * Get all registered servers
+   */
+  list() {
+    return this.read().servers;
+  }
+
+  /**
+   * Remove servers whose PIDs no longer exist (stale entries)
+   */
+  cleanupStale() {
+    let registry = this.read();
+    let initialCount = registry.servers.length;
+    registry.servers = registry.servers.filter(server => {
+      try {
+        // Signal 0 doesn't kill, just checks if process exists
+        process.kill(server.pid, 0);
+        return true;
+      } catch (err) {
+        // ESRCH = process doesn't exist, EPERM = exists but no permission (still valid)
+        return err.code === 'EPERM';
+      }
+    });
+    if (registry.servers.length !== initialCount) {
+      this.write(registry);
+      this.notifyMenubar();
+      return initialCount - registry.servers.length;
+    }
+    return 0;
+  }
+
+  /**
+   * Notify the menubar app that the registry changed
+   *
+   * Uses macOS notifyutil for instant Darwin notification delivery.
+   * The menubar app listens for this in addition to file watching.
+   */
+  notifyMenubar() {
+    if (process.platform !== 'darwin') return;
+    try {
+      execSync('notifyutil -p dev.vizzly.serverChanged', {
+        stdio: 'ignore',
+        timeout: 500
+      });
+    } catch {
+      // Non-fatal - menubar will still see changes via file watching
+    }
+  }
+
+  /**
+   * Get all ports currently in use by registered servers
+   * @returns {Set<number>} Set of ports in use
+   */
+  getUsedPorts() {
+    let registry = this.read();
+    return new Set(registry.servers.map(s => s.port));
+  }
+
+  /**
+   * Find an available port starting from the default
+   * @param {number} startPort - Port to start searching from (default: 47392)
+   * @param {number} maxAttempts - Maximum ports to try (default: 100)
+   * @returns {Promise<number>} Available port
+   */
+  async findAvailablePort(startPort = 47392, maxAttempts = 100) {
+    // Clean up stale entries first
+    this.cleanupStale();
+    let usedPorts = this.getUsedPorts();
+    for (let i = 0; i < maxAttempts; i++) {
+      let port = startPort + i;
+
+      // Skip if registered in our registry
+      if (usedPorts.has(port)) continue;
+
+      // Check if port is actually free (not used by other apps)
+      let isFree = await isPortFree(port);
+      if (isFree) {
+        return port;
+      }
+    }
+
+    // Fallback to default if nothing found (will fail later with clear error)
+    return startPort;
+  }
+}
+
+/**
+ * Check if a port is free (not in use by any process)
+ * @param {number} port - Port to check
+ * @returns {Promise<boolean>} True if port is free
+ */
+async function isPortFree(port) {
+  return new Promise(resolve => {
+    let server = createServer();
+    server.once('error', err => {
+      if (err.code === 'EADDRINUSE') {
+        resolve(false);
+      } else {
+        // Other errors - assume port is free
+        resolve(true);
+      }
+    });
+    server.once('listening', () => {
+      server.close(() => resolve(true));
+    });
+    server.listen(port, '127.0.0.1');
+  });
+}
+
+// Singleton instance
+let registryInstance = null;
+export function getServerRegistry() {
+  if (!registryInstance) {
+    registryInstance = new ServerRegistry();
+  }
+  return registryInstance;
+}

package/dist/utils/global-config.js

@@ -100,6 +100,32 @@ export async function clearGlobalConfig() {
   await saveGlobalConfig({});
 }
 
+/**
+ * Save user's PATH for menubar app to use
+ * This auto-configures the menubar app so it can find npx/node
+ * @returns {Promise<void>}
+ */
+export async function saveUserPath() {
+  let config = await loadGlobalConfig();
+  let userPath = process.env.PATH;
+
+  // Only update if PATH has changed
+  if (config.userPath === userPath) {
+    return;
+  }
+  config.userPath = userPath;
+  await saveGlobalConfig(config);
+}
+
+/**
+ * Get stored user PATH for external tools (like menubar app)
+ * @returns {Promise<string|null>} PATH string or null if not configured
+ */
+export async function getUserPath() {
+  let config = await loadGlobalConfig();
+  return config.userPath || null;
+}
+
 /**
  * Get authentication tokens from global config
  * @returns {Promise<Object|null>} Token object with accessToken, refreshToken, expiresAt, user, or null if not found

package/dist/utils/output.js

@@ -185,6 +185,10 @@ export function getColors() {
  */
 export function success(message, data = {}) {
   stopSpinner();
+  writeLog('info', message, {
+    status: 'success',
+    ...data
+  });
   if (config.silent) return;
   if (config.json) {
     console.log(JSON.stringify({
@@ -221,6 +225,7 @@ export function result(message) {
  * Show an info message
  */
 export function info(message, data = {}) {
+  writeLog('info', message, data);
   if (!shouldLog('info')) return;
   if (config.json) {
     console.log(JSON.stringify({
@@ -238,6 +243,7 @@ export function info(message, data = {}) {
  */
 export function warn(message, data = {}) {
   stopSpinner();
+  writeLog('warn', message, data);
   if (!shouldLog('warn')) return;
   if (config.json) {
     console.error(JSON.stringify({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.25.1",
+  "version": "0.26.1",
   "description": "Visual review platform for UI developers and designers",
   "keywords": [
     "visual-testing",
@@ -86,7 +86,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@vizzly-testing/honeydiff": "^0.9.0",
+    "@vizzly-testing/honeydiff": "^0.10.0",
     "ansis": "^4.2.0",
     "commander": "^14.0.0",
     "cosmiconfig": "^9.0.0",