@vizzly-testing/cli 0.38.1 → 0.39.0

package/dist/commands/project.js

@@ -1,9 +1,11 @@
 import { createApiClient as defaultCreateApiClient } from '../api/client.js';
 import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
 import { getApiUrl as defaultGetApiUrl } from '../utils/environment-config.js';
+import { preflightChanges } from '../utils/file-changes.js';
 import { getAccessToken as defaultGetAccessToken } from '../utils/global-config.js';
 import * as defaultOutput from '../utils/output.js';
-import { saveProjectLink as defaultSaveProjectLink } from '../utils/project-link-store.js';
+import { planProjectBinding as defaultPlanProjectBinding, writeProjectBinding as defaultWriteProjectBinding } from '../utils/project-binding.js';
+import { getProjectLink as defaultGetProjectLink, saveProjectLink as defaultSaveProjectLink } from '../utils/project-link-store.js';
 export function parseProjectSelector(selector, options = {}) {
   let organizationSlug = options.org || null;
   let projectSlug = options.project || null;
@@ -42,7 +44,10 @@ export async function projectLinkCommand(selector, options = {}, globalOptions =
     getApiUrl = defaultGetApiUrl,
     loadConfig = defaultLoadConfig,
     output = defaultOutput,
+    getProjectLink = defaultGetProjectLink,
+    planProjectBinding = defaultPlanProjectBinding,
     saveProjectLink = defaultSaveProjectLink,
+    writeProjectBinding = defaultWriteProjectBinding,
     exit = code => process.exit(code)
   } = deps;
   output.configure({
@@ -55,66 +60,145 @@ export async function projectLinkCommand(selector, options = {}, globalOptions =
     projectSlug
   } = parseProjectSelector(selector, options);
   try {
-    let config = await loadConfig(globalOptions.config, globalOptions);
-    let userToken = config.userToken || globalOptions.token || (await getAccessToken());
-    if (!userToken) {
+    let config;
+    let configError;
+    try {
+      config = await loadConfig(globalOptions.config, globalOptions);
+    } catch (error) {
+      configError = error;
+    }
+    let apiUrl = config?.apiUrl || getApiUrl();
+    let project = {
+      organizationSlug,
+      projectSlug
+    };
+    let binding = await planProjectBinding({
+      configPath: globalOptions.config || config?._configPath,
+      project,
+      apiUrl,
+      currentProject: config?.project,
+      currentApiUrl: config?._configApiUrl
+    });
+    if (binding.status === 'manual') {
+      let result = {
+        linked: false,
+        organizationSlug,
+        projectSlug,
+        binding: {
+          status: 'manual',
+          configPath: binding.configPath,
+          instructions: binding.instructions
+        }
+      };
+      if (globalOptions.json) output.data(result);else {
+        output.error('Project configuration needs an explicit edit');
+        output.hint(binding.instructions);
+      }
+      output.cleanup();
+      exit(2);
+      return result;
+    }
+    if (configError) throw configError;
+    if (binding.after !== null) {
+      await preflightChanges([{
+        path: binding.configPath,
+        before: binding.before,
+        after: binding.after
+      }]);
+    }
+    let linkedProject = !options.name && !options.expiresAt ? await getProjectLink({
+      apiUrl,
+      ...project
+    }) : null;
+    let reused = Boolean(linkedProject);
+    let userToken = linkedProject ? null : config.userToken || globalOptions.token || (await getAccessToken());
+    if (!linkedProject && !userToken) {
       output.error('Login required before linking a project');
       output.hint('Run "vizzly login" first, then try project link again');
       output.cleanup();
       exit(1);
-      return;
+      return {
+        linked: false,
+        reason: 'auth_required'
+      };
     }
-    output.startSpinner(`Linking ${organizationSlug}/${projectSlug}...`);
-    let apiUrl = config.apiUrl || getApiUrl();
-    let client = createApiClient({
-      baseUrl: apiUrl,
-      token: userToken,
-      command: 'project-link'
-    });
-    let response = await client.request(`/api/cli/${projectSlug}/link-token`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'X-Organization': organizationSlug
-      },
-      body: JSON.stringify({
-        name: options.name,
-        expiresAt: options.expiresAt
-      })
-    });
-    let linkedProject = await saveProjectLink({
-      apiUrl,
-      organizationSlug: response.organization?.slug || organizationSlug,
-      organizationName: response.organization?.name,
-      projectSlug: response.project?.slug || projectSlug,
-      projectName: response.project?.name,
-      token: response.token.token,
-      tokenId: response.token.id,
-      tokenPrefix: response.token.token_prefix,
-      expiresAt: response.token.expires_at,
-      createdAt: response.token.created_at
-    });
+    if (!linkedProject) {
+      output.startSpinner(`Linking ${organizationSlug}/${projectSlug}...`);
+      let client = createApiClient({
+        baseUrl: apiUrl,
+        token: userToken,
+        command: 'project-link'
+      });
+      let response = await client.request(`/api/cli/${projectSlug}/link-token`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Organization': organizationSlug
+        },
+        body: JSON.stringify({
+          name: options.name,
+          expiresAt: options.expiresAt
+        })
+      });
+      linkedProject = await saveProjectLink({
+        apiUrl,
+        organizationSlug: response.organization?.slug || organizationSlug,
+        organizationName: response.organization?.name,
+        projectSlug: response.project?.slug || projectSlug,
+        projectName: response.project?.name,
+        token: response.token.token,
+        tokenId: response.token.id,
+        tokenPrefix: response.token.token_prefix,
+        expiresAt: response.token.expires_at,
+        createdAt: response.token.created_at
+      });
+    }
+    if (linkedProject.organizationSlug !== organizationSlug || linkedProject.projectSlug !== projectSlug) {
+      binding = await planProjectBinding({
+        configPath: binding.configPath,
+        project: {
+          organizationSlug: linkedProject.organizationSlug,
+          projectSlug: linkedProject.projectSlug
+        },
+        apiUrl,
+        currentProject: config?.project,
+        currentApiUrl: config?._configApiUrl
+      });
+      if (binding.status === 'manual') throw new Error(binding.instructions);
+    }
+    await writeProjectBinding(binding);
     output.stopSpinner();
+    let result = {
+      linked: true,
+      organizationSlug: linkedProject.organizationSlug,
+      projectSlug: linkedProject.projectSlug,
+      tokenPrefix: linkedProject.tokenPrefix,
+      storage: linkedProject.storage,
+      reused,
+      binding: {
+        status: 'bound',
+        configPath: binding.configPath
+      }
+    };
     if (globalOptions.json) {
-      output.data({
-        linked: true,
-        organizationSlug: linkedProject.organizationSlug,
-        projectSlug: linkedProject.projectSlug,
-        tokenPrefix: linkedProject.tokenPrefix,
-        storage: linkedProject.storage
-      });
+      output.data(result);
       output.cleanup();
-      return;
+      return result;
     }
     output.complete(`Linked ${linkedProject.organizationSlug}/${linkedProject.projectSlug}`);
-    output.hint(`Active project: ${linkedProject.organizationSlug}/${linkedProject.projectSlug}`);
+    output.hint(`Repository project: ${linkedProject.organizationSlug}/${linkedProject.projectSlug}`);
     output.hint(`Cloud uploads and project-scoped context will use ${linkedProject.tokenPrefix}...`);
     output.hint(`Credential storage: ${linkedProject.storage}`);
     output.cleanup();
+    return result;
   } catch (error) {
     output.stopSpinner();
     output.error('Failed to link project', error);
     output.cleanup();
     exit(1);
+    return {
+      linked: false,
+      reason: 'link_failed'
+    };
   }
 }

package/dist/commands/run.js

@@ -274,8 +274,8 @@ export async function runCommand(testCommand, options = {}, globalOptions = {},
       commitAuthorName: commitAuthor.name,
       commitAuthorEmail: commitAuthor.email,
       environment: config.build.environment,
-      threshold: config.comparison.threshold,
-      minClusterSize: config.comparison.minClusterSize,
+      threshold: config._comparisonOverrides?.threshold,
+      minClusterSize: config._comparisonOverrides?.minClusterSize,
       eager: config.eager || false,
       allowNoToken: config.allowNoToken || false,
       wait: config.wait || options.wait || false,

package/dist/commands/tdd.js

@@ -12,7 +12,10 @@ import { createAuthService as defaultCreateAuthService } from '../services/auth-
 import { createBuildObject as defaultCreateBuildObject } from '../services/build-manager.js';
 import { createConfigService as defaultCreateConfigService } from '../services/config-service.js';
 import { createProjectService as defaultCreateProjectService } from '../services/project-service.js';
+import { generateStaticReport as defaultGenerateStaticReport, getReportFileUrl } from '../services/static-report-generator.js';
+import { getServerRegistry } from '../tdd/server-registry.js';
 import { initializeDaemon as defaultInitializeDaemon, runTests as defaultRunTests } from '../test-runner/index.js';
+import { openBrowser as defaultOpenBrowser } from '../utils/browser.js';
 import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
 import { detectBranch as defaultDetectBranch, detectCommit as defaultDetectCommit, detectCommitAuthor as defaultDetectCommitAuthor, detectCommitMessage as defaultDetectCommitMessage, detectPullRequestNumber as defaultDetectPullRequestNumber, generateBuildNameWithGit as defaultGenerateBuildNameWithGit } from '../utils/git.js';
 import * as defaultOutput from '../utils/output.js';
@@ -63,7 +66,9 @@ export async function tddCommand(testCommand, options = {}, globalOptions = {},
     detectPullRequestNumber = defaultDetectPullRequestNumber,
     generateBuildNameWithGit = defaultGenerateBuildNameWithGit,
     spawn = defaultSpawn,
-    output = defaultOutput
+    output = defaultOutput,
+    generateStaticReport = defaultGenerateStaticReport,
+    openBrowser = defaultOpenBrowser
   } = deps;
   output.configure({
     json: globalOptions.json,
@@ -93,6 +98,9 @@ export async function tddCommand(testCommand, options = {}, globalOptions = {},
       ...options
     };
     let config = await loadConfig(globalOptions.config, allOptions);
+    if (options.autoPort) {
+      config.server.port = await getServerRegistry().findAvailablePort(config.server.port);
+    }
 
     // Dev mode works locally by default - only needs token for baseline download
     let needsToken = options.baselineBuild || options.baselineComparison || config.baselineBuildId || config.baselineComparisonId;
@@ -207,38 +215,57 @@ export async function tddCommand(testCommand, options = {}, globalOptions = {},
 
     // Normal dev mode - run tests
     output.debug('run', testCommand);
-    let runResult = await runTests({
-      runOptions,
-      config: configWithVerbose,
-      deps: {
-        serverManager,
-        buildManager,
-        spawn: (command, spawnOptions) => {
-          let proc = spawn(command, spawnOptions);
-          testProcess = proc;
-          return proc;
-        },
-        createApiClient,
-        createApiBuild,
-        getBuild,
-        finalizeApiBuild,
-        createError: (msg, code) => new VizzlyError(msg, code),
-        output,
-        onBuildCreated: data => {
-          output.debug('build', `created ${data.buildId?.substring(0, 8)}`);
-        },
-        onServerReady: data => {
-          output.debug('server', `ready on :${data.port}`);
-        },
-        onFinalizeFailed: data => {
-          output.warn(`Failed to finalize build: ${data.error}`);
+    let runError = null;
+    let runResult;
+    try {
+      runResult = await runTests({
+        runOptions,
+        config: configWithVerbose,
+        deps: {
+          serverManager,
+          buildManager,
+          spawn: (command, spawnOptions) => {
+            let proc = spawn(command, spawnOptions);
+            testProcess = proc;
+            return proc;
+          },
+          createApiClient,
+          createApiBuild,
+          getBuild,
+          finalizeApiBuild,
+          createError: (msg, code) => new VizzlyError(msg, code),
+          output,
+          onBuildCreated: data => {
+            output.debug('build', `created ${data.buildId?.substring(0, 8)}`);
+          },
+          onServerReady: data => {
+            output.debug('server', `ready on :${data.port}`);
+          },
+          onFinalizeFailed: data => {
+            output.warn(`Failed to finalize build: ${data.error}`);
+          }
         }
+      });
+    } catch (error) {
+      if (!error.runResult) throw error;
+      runResult = error.runResult;
+      runError = error;
+    }
+    let reportPath = null;
+    let reportError = null;
+    if (runResult.screenshotsCaptured > 0 || runResult.comparisons?.length > 0) {
+      let report = await generateStaticReport(process.cwd());
+      if (report.success) {
+        reportPath = report.reportPath;
+      } else {
+        reportError = report.error;
+        output.warn(`Failed to generate static report: ${report.error}`);
       }
-    });
+    }
 
     // Determine success based on comparison results
     // (Summary is printed by printResults() in tdd-service.js, called from getTddResults)
-    let hasFailures = runResult.failed || runResult.comparisons?.some(c => c.status === 'failed');
+    let hasFailures = runResult.failed || runResult.testsFailed > 0 || runResult.capture?.setup === 'disabled' || runResult.capture?.rejected > 0 || runResult.capture?.errors > 0 || Boolean(reportError) || runResult.comparisons?.some(c => ['failed', 'error'].includes(c.status));
     let exitCode = hasFailures ? 1 : 0;
 
     // JSON output mode
@@ -251,9 +278,9 @@ export async function tddCommand(testCommand, options = {}, globalOptions = {},
         diffPercentage: c.diffPercentage ?? c.diff_percentage ?? null,
         threshold: c.threshold ?? config.comparison.threshold,
         paths: {
-          baseline: c.baselinePath || c.baseline_path || null,
-          current: c.currentPath || c.current_path || null,
-          diff: c.diffPath || c.diff_path || null
+          baseline: c.baseline || c.baselinePath || c.baseline_path || null,
+          current: c.current || c.currentPath || c.current_path || null,
+          diff: c.diff || c.diffPath || c.diff_path || null
         },
         viewport: c.viewport || {
           width: c.viewportWidth || c.viewport_width,
@@ -267,29 +294,50 @@ export async function tddCommand(testCommand, options = {}, globalOptions = {},
         total: comparisons.length,
         passed: comparisons.filter(c => c.status === 'passed').length,
         failed: comparisons.filter(c => c.status === 'failed').length,
-        new: comparisons.filter(c => c.status === 'new').length
+        new: comparisons.filter(c => c.status === 'new').length,
+        errors: comparisons.filter(c => c.status === 'error').length
       };
       output.data({
         status: hasFailures ? 'failed' : 'completed',
         exitCode,
         comparisons,
         summary,
-        reportPath: runResult.reportPath || '.vizzly/report/index.html',
+        capture: runResult.capture,
+        reportPath,
+        reportError,
+        ...(runError ? {
+          error: {
+            message: runError.message
+          }
+        } : {}),
         contextCommand: buildLocalContextCommand({
           structured: true
         })
       });
       output.cleanup();
     }
-    if (!globalOptions.json && !options.daemon) {
+    if (!globalOptions.json) {
+      if (reportPath) output.hint(`Report: ${getReportFileUrl(reportPath)}`);
       output.blank?.();
       output.print(`  Context      ${buildLocalContextCommand()}`);
     }
+    if (reportPath && options.open !== false) {
+      try {
+        await openBrowser(getReportFileUrl(reportPath));
+      } catch (error) {
+        output.warn(`Could not open the report: ${error.message}`);
+      }
+    }
     return {
       result: {
+        ...runResult,
         success: !hasFailures,
         exitCode,
-        ...runResult
+        reportPath,
+        reportError,
+        ...(runError ? {
+          error: runError.message
+        } : {})
       },
       cleanup
     };
@@ -308,8 +356,10 @@ export async function tddCommand(testCommand, options = {}, globalOptions = {},
           total: 0,
           passed: 0,
           failed: 0,
-          new: 0
-        }
+          new: 0,
+          errors: 0
+        },
+        reportPath: null
       });
       output.cleanup();
     } else {
@@ -319,7 +369,8 @@ export async function tddCommand(testCommand, options = {}, globalOptions = {},
       result: {
         success: false,
         exitCode: 1,
-        error: error.message
+        error: error.message,
+        reportPath: null
       },
       cleanup
     };

package/dist/commands/upload.js

@@ -132,8 +132,8 @@ export async function uploadCommand(screenshotsPath, options = {}, globalOptions
       commitAuthorName: commitAuthor.name,
       commitAuthorEmail: commitAuthor.email,
       environment: config.build.environment,
-      threshold: config.comparison.threshold,
-      minClusterSize: config.comparison.minClusterSize,
+      threshold: config._comparisonOverrides?.threshold,
+      minClusterSize: config._comparisonOverrides?.minClusterSize,
       uploadAll: options.uploadAll || false,
       metadata: options.metadata ? JSON.parse(options.metadata) : {},
       pullRequestNumber,

package/dist/init/agents.js

@@ -0,0 +1,99 @@
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readOptionalFile } from '../utils/config-discovery.js';
+import { fileChange } from '../utils/file-changes.js';
+let sourcePath = fileURLToPath(new URL('../../skills/vizzly/', import.meta.url));
+let start = '<!-- vizzly-agent-guidance -->';
+let end = '<!-- /vizzly-agent-guidance -->';
+function guidanceContent() {
+  return `${start}
+## Visual testing with Vizzly
+
+For user-facing changes, use the repo-local Vizzly skill at
+\`.agents/skills/vizzly/SKILL.md\`.
+
+- Check existing screenshots and diffs before and after the change.
+- Use the repository's existing visual test command.
+- For cloud reviews, discover supported requests with
+  \`vizzly api schema --json\` and inspect baseline, current, and diff images
+  together.
+- For local results, use \`vizzly context ... --json\`.
+
+Don't approve or reject changes, or replace baselines, unless the task asks
+for it.
+${end}
+`;
+}
+function addGuidance(source) {
+  let content = source || '';
+  let starts = content.split(start).length - 1;
+  let ends = content.split(end).length - 1;
+  let begin = content.indexOf(start);
+  let finish = content.indexOf(end);
+  if (starts !== ends || starts > 1 || starts && finish < begin) {
+    throw new Error('Repair the incomplete or duplicate Vizzly guidance markers in AGENTS.md before running init.');
+  }
+  let block = guidanceContent();
+  if (starts) return content;
+  return content.trim() ? `${content.trimEnd()}\n\n${block}` : block;
+}
+async function skillFiles(directory, prefix = '') {
+  let files = [];
+  for (let entry of await readdir(directory, {
+    withFileTypes: true
+  })) {
+    let relative = path.join(prefix, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await skillFiles(path.join(directory, entry.name), relative)));
+    } else if (entry.isFile()) {
+      files.push(relative);
+    }
+  }
+  return files;
+}
+export async function planAgentSetup(cwd, {
+  skill,
+  guidance
+}) {
+  if (!skill && !guidance) return {
+    changes: []
+  };
+  let targetPath = path.join(cwd, '.agents', 'skills', 'vizzly');
+  let existing = await readOptionalFile(path.join(targetPath, 'SKILL.md'));
+  let changes = [];
+  if (!existing) {
+    for (let filename of await skillFiles(sourcePath)) {
+      changes.push(await fileChange(path.join(targetPath, filename), await readOptionalFile(path.join(sourcePath, filename))));
+    }
+  }
+  let agentSkill = {
+    status: existing ? 'exists' : 'installed',
+    sourcePath,
+    targetPath
+  };
+  let agentGuidance;
+  if (guidance) {
+    let agentsPath = path.join(cwd, 'AGENTS.md');
+    let before = await readOptionalFile(agentsPath);
+    let after = addGuidance(before);
+    changes.push(before === after ? null : {
+      path: agentsPath,
+      before,
+      after
+    });
+    let status = 'exists';
+    if (before !== after) {
+      status = before === null ? 'created' : 'updated';
+    }
+    agentGuidance = {
+      status,
+      agentsPath
+    };
+  }
+  return {
+    changes: changes.filter(Boolean),
+    agentSkill,
+    agentGuidance
+  };
+}

package/dist/init/core.js

@@ -0,0 +1,31 @@
+function createConfigContent(format) {
+  if (format === 'json' || format === 'yaml') return '{}\n';
+  if (!['javascript', 'typescript'].includes(format)) {
+    throw new Error(`Cannot generate ${format} config. Use a .js, .ts or .json file.`);
+  }
+  return `// Vizzly supplies defaults. Uncomment only settings you want to change.
+// Configuration: https://docs.vizzly.dev/integration/cli/
+export default {
+  // comparison: { threshold: 2, minClusterSize: 2 },
+  // upload: { screenshotsDir: './screenshots' },
+};
+`;
+}
+export function planConfig(config) {
+  let after;
+  if (config.format === 'package') {
+    let pkg = {
+      ...config.packageConfig,
+      vizzly: {}
+    };
+    let indent = config.source?.match(/\n([ \t]+)\S/)?.[1] || '  ';
+    after = `${JSON.stringify(pkg, null, indent)}\n`;
+  } else {
+    after = createConfigContent(config.format);
+  }
+  return {
+    path: config.configPath,
+    before: config.source,
+    after
+  };
+}

package/dist/init/prompts.js

@@ -0,0 +1,44 @@
+import { createInterface } from 'node:readline';
+export function createPrompts({
+  input = process.stdin,
+  output = process.stderr
+} = {}) {
+  let reader = createInterface({
+    input,
+    crlfDelay: Infinity,
+    terminal: false
+  });
+  let lines = reader[Symbol.asyncIterator]();
+  let cancelled = () => Object.assign(new Error('Setup cancelled.'), {
+    code: 'INIT_CANCELLED'
+  });
+  let interrupted = false;
+  let onInterrupt = () => {
+    interrupted = true;
+    reader.close();
+  };
+  process.on('SIGINT', onInterrupt);
+  async function ask(question, fallback = '') {
+    output.write(`${question}${fallback ? ` [${fallback}]` : ''}: `);
+    let line = await lines.next();
+    if (line.done || interrupted) throw cancelled();
+    return line.value.trim() || fallback;
+  }
+  async function confirm(question, defaultYes = false) {
+    while (true) {
+      let answer = (await ask(`${question} ${defaultYes ? '[Y/n]' : '[y/N]'}`)).toLowerCase();
+      if (!answer) return defaultYes;
+      if (['y', 'yes'].includes(answer)) return true;
+      if (['n', 'no'].includes(answer)) return false;
+      output.write('Enter yes or no.\n');
+    }
+  }
+  return {
+    ask,
+    confirm,
+    close() {
+      process.off('SIGINT', onInterrupt);
+      reader.close();
+    }
+  };
+}