@vizzly-testing/cli 0.35.2 → 0.35.3-beta.1

package/dist/commands/status.js

@@ -3,18 +3,17 @@
  * Uses functional API operations directly
  */
 
-import { createApiClient as defaultCreateApiClient, getBuild as defaultGetBuild, getPreviewInfo as defaultGetPreviewInfo } from '../api/index.js';
+import { createApiClient as defaultCreateApiClient, getBuildStatus as defaultGetBuildStatus, getPreviewInfo as defaultGetPreviewInfo } from '../api/index.js';
 import { getAppBaseUrl } from '../utils/api-url.js';
 import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
-import { getApiUrl as defaultGetApiUrl } from '../utils/environment-config.js';
 import * as defaultOutput from '../utils/output.js';
+import { getVisualReviewState } from '../utils/visual-context-normalizers.js';
 function createStatusDeps(deps = {}) {
   return {
     loadConfig: deps.loadConfig || defaultLoadConfig,
     createApiClient: deps.createApiClient || defaultCreateApiClient,
-    getBuild: deps.getBuild || defaultGetBuild,
+    getBuildStatus: deps.getBuildStatus || defaultGetBuildStatus,
     getPreviewInfo: deps.getPreviewInfo || defaultGetPreviewInfo,
-    getApiUrl: deps.getApiUrl || defaultGetApiUrl,
     output: deps.output || defaultOutput,
     exit: deps.exit || (code => process.exit(code))
   };
@@ -32,7 +31,7 @@ function createStatusClient({
 }) {
   return createApiClient({
     baseUrl: config.apiUrl,
-    token: config.apiKey,
+    token: config.apiKey || config.userToken,
     command: 'status'
   });
 }
@@ -52,10 +51,108 @@ async function fetchOptionalPreviewInfo(getPreviewInfo, client, buildId) {
 export function normalizeBuildStatus(buildStatus) {
   return buildStatus.build || buildStatus;
 }
-export function createStatusData(build, previewInfo = null) {
+
+/**
+ * Read exact processing counts from canonical or legacy status responses.
+ *
+ * Legacy `pending_screenshots` is review state, not queue state, so it is
+ * deliberately excluded. Missing processing fields remain missing instead of
+ * becoming client-authored zeroes.
+ *
+ * @param {Object} status - Canonical status bundle or legacy build record.
+ * @returns {Object|undefined} API-provided processing facts when available.
+ */
+export function getProcessingStatus(status = {}) {
+  if (status.processing) {
+    return status.processing;
+  }
+  let build = normalizeBuildStatus(status);
+  let processing = {};
+  let fields = [['total', build.screenshot_count], ['completed', build.completed_jobs], ['failed', build.failed_jobs], ['active', build.processing_screenshots]];
+  for (let [name, value] of fields) {
+    if (value != null) {
+      processing[name] = value;
+    }
+  }
+  return Object.keys(processing).length > 0 ? processing : undefined;
+}
+
+/**
+ * Read comparison totals without deriving them from screenshot counts.
+ *
+ * @param {Object} status - Canonical status bundle or legacy build record.
+ * @returns {Object|undefined} API-provided comparison facts when available.
+ */
+export function getComparisonStatus(status = {}) {
+  if (status.comparisons) {
+    return status.comparisons;
+  }
+  let build = normalizeBuildStatus(status);
+  let comparisons = {};
+  let fields = [['total', build.total_comparisons], ['new', build.new_comparisons], ['changed', build.changed_comparisons], ['identical', build.identical_comparisons]];
+  for (let [name, value] of fields) {
+    if (value != null) {
+      comparisons[name] = value;
+    }
+  }
+  return Object.keys(comparisons).length > 0 ? comparisons : undefined;
+}
+
+/**
+ * Prefer canonical Cricket review state while retaining the legacy fallback.
+ *
+ * Processing status stays separate: a pending review never means a screenshot
+ * is still being processed.
+ *
+ * @param {Object} status - Canonical status bundle or legacy build record.
+ * @returns {string|null} API-provided review state when available.
+ */
+export function getBuildReviewState(status = {}) {
+  let build = normalizeBuildStatus(status);
+  return getVisualReviewState(build) || getVisualReviewState(status.visualReview?.build || status.visual_review) || null;
+}
+
+/**
+ * Give agents concrete paths from lifecycle status into visual evidence.
+ *
+ * @param {Object} build - Build record from the status response.
+ * @returns {{label: string, command: string}[]} Executable CLI commands.
+ */
+export function createStatusSuggestedCommands(build = {}) {
+  if (!build.id) {
+    return [];
+  }
+  return [{
+    label: 'Inspect build context',
+    command: `vizzly --json context build ${build.id} --agent --source cloud`
+  }, {
+    label: 'List comparisons',
+    command: `vizzly --json comparisons --build ${build.id}`
+  }];
+}
+
+/**
+ * Preserve the established JSON fields while exposing canonical status facts.
+ *
+ * Every lifecycle, processing, comparison, and review value comes directly
+ * from the API. Undefined values intentionally disappear during JSON encoding
+ * rather than being presented as false certainty.
+ *
+ * @param {Object} status - Canonical status bundle or legacy build record.
+ * @param {Object|null} previewInfo - Optional preview response.
+ * @returns {Object} Machine-readable status payload.
+ */
+export function createStatusData(status, previewInfo = null) {
+  let build = normalizeBuildStatus(status);
+  let processing = getProcessingStatus(status);
+  let comparisons = getComparisonStatus(status);
+  let visualReview = build.visual_review || status.visualReview?.build || status.visual_review;
   return {
+    resource: status.resource,
+    schemaVersion: status.schema_version,
     buildId: build.id,
     status: build.status,
+    conclusion: status.conclusion,
     name: build.name,
     createdAt: build.created_at,
     updatedAt: build.updated_at,
@@ -64,15 +161,24 @@ export function createStatusData(build, previewInfo = null) {
     branch: build.branch,
     commit: build.commit_sha,
     commitMessage: build.commit_message,
-    screenshotsTotal: build.screenshot_count || 0,
-    comparisonsTotal: build.total_comparisons || 0,
-    newComparisons: build.new_comparisons || 0,
-    changedComparisons: build.changed_comparisons || 0,
-    identicalComparisons: build.identical_comparisons || 0,
+    screenshotsTotal: processing?.total ?? build.screenshot_count,
+    processing,
+    comparisonsTotal: comparisons?.total ?? build.total_comparisons,
+    comparisons,
+    newComparisons: comparisons?.new ?? build.new_comparisons,
+    changedComparisons: comparisons?.changed ?? build.changed_comparisons,
+    identicalComparisons: comparisons?.identical ?? build.identical_comparisons,
+    reviewState: getBuildReviewState(status),
+    review: status.review,
+    reviewFlow: status.reviewFlow,
+    visualReview,
     approvalStatus: build.approval_status,
     executionTime: build.execution_time_ms,
     isBaseline: build.is_baseline,
     userAgent: build.user_agent,
+    scope: status.scope,
+    links: status.links,
+    suggestedCommands: createStatusSuggestedCommands(build),
     preview: previewInfo ? {
       url: previewInfo.preview_url,
       status: previewInfo.status,
@@ -95,11 +201,21 @@ export function createBuildInfo(build) {
   }
   return buildInfo;
 }
-export function createComparisonStats(build, colors) {
+
+/**
+ * Format API comparison outcomes without filling missing buckets with zeroes.
+ *
+ * @param {Object} status - Canonical status bundle or legacy build record.
+ * @param {Object} colors - Output color helpers.
+ * @returns {string} Human-readable comparison summary.
+ */
+export function createComparisonStats(status, colors) {
+  let build = normalizeBuildStatus(status);
+  let comparisons = getComparisonStatus(status) || {};
   let stats = [];
-  let newCount = build.new_comparisons || 0;
-  let changedCount = build.changed_comparisons || 0;
-  let identicalCount = build.identical_comparisons || 0;
+  let newCount = comparisons.new ?? build.new_comparisons;
+  let changedCount = comparisons.changed ?? build.changed_comparisons;
+  let identicalCount = comparisons.identical ?? build.identical_comparisons;
   if (newCount > 0) {
     stats.push(`${colors.brand.info(newCount)} new`);
   }
@@ -111,27 +227,47 @@ export function createComparisonStats(build, colors) {
   }
   return stats.join(colors.brand.textMuted(' · '));
 }
-export function createBuildUrl(baseUrl, build) {
-  if (!baseUrl || !build.project_id) {
+
+/**
+ * Build the best available legacy link when the API did not return one.
+ *
+ * Slug routes match the current app, while the project-ID route remains as a
+ * compatibility fallback for older build responses.
+ *
+ * @param {string} baseUrl - API or app base URL.
+ * @param {Object} build - Build record.
+ * @param {Object|null} scope - Canonical organization and project scope.
+ * @returns {string|null} Build URL when the response has enough identity.
+ */
+export function createBuildUrl(baseUrl, build, scope = null) {
+  if (!baseUrl) {
     return null;
   }
-  return `${getAppBaseUrl(baseUrl)}/projects/${build.project_id}/builds/${build.id}`;
-}
-export function shouldFailStatus(build) {
-  return build.status === 'failed' || build.failed_jobs > 0;
-}
-export function getProcessingProgress(build) {
-  if (build.status !== 'processing' && build.status !== 'pending') {
-    return null;
+  let organizationSlug = scope?.organization?.slug || build.organization_slug || build.org_slug;
+  let projectSlug = scope?.project?.slug || build.project_slug;
+  let appBaseUrl = getAppBaseUrl(baseUrl);
+  if (organizationSlug && projectSlug) {
+    return `${appBaseUrl}/${organizationSlug}/${projectSlug}/builds/${build.id}`;
   }
-  let completedJobs = build.completed_jobs || 0;
-  let failedJobs = build.failed_jobs || 0;
-  let processingScreenshots = build.processing_screenshots || 0;
-  let totalJobs = completedJobs + failedJobs + processingScreenshots;
-  if (totalJobs <= 0) {
-    return null;
+  if (build.project_id) {
+    return `${appBaseUrl}/projects/${build.project_id}/builds/${build.id}`;
   }
-  return (completedJobs + failedJobs) / totalJobs * 100;
+  return null;
+}
+
+/**
+ * Preserve status failure behavior while accepting the canonical conclusion.
+ *
+ * Review-required and rejected builds keep their existing successful command
+ * exit behavior. Only build or processing failures produce a failing status.
+ *
+ * @param {Object} status - Canonical status bundle or legacy build record.
+ * @returns {boolean} Whether human status should exit non-zero.
+ */
+export function shouldFailStatus(status) {
+  let build = normalizeBuildStatus(status);
+  let processing = getProcessingStatus(status);
+  return build.status === 'failed' || ['build_failed', 'processing_failed'].includes(status.conclusion) || (processing?.failed ?? 0) > 0;
 }
 function writeStatusTiming({
   build,
@@ -149,10 +285,46 @@ function writeStatusTiming({
     output.hint(`Took ${Math.round(build.execution_time_ms / 1000)}s`);
   }
 }
-function createVerboseInfo(build) {
+
+/**
+ * Render follow-up commands after the factual status summary.
+ *
+ * Status answers lifecycle questions; these commands are the explicit bridge
+ * to screenshot evidence without bloating the status response itself.
+ *
+ * @param {Object} build - Build record from the status response.
+ * @param {Object} output - Configured output boundary.
+ */
+function writeSuggestedCommands({
+  build,
+  output
+}) {
+  let commands = createStatusSuggestedCommands(build);
+  if (commands.length === 0) {
+    return;
+  }
+  let colors = output.getColors();
+  output.blank();
+  output.print('  Suggested commands');
+  for (let item of commands) {
+    output.print(`    ${colors.brand.textMuted(item.command)}`);
+  }
+}
+
+/**
+ * Add optional API facts without inventing placeholders for missing metadata.
+ *
+ * @param {Object} status - Canonical status bundle or legacy build record.
+ * @returns {Object} Available verbose fields.
+ */
+function createVerboseInfo(status) {
+  let build = normalizeBuildStatus(status);
   let verboseInfo = {};
-  if (build.approved_screenshots > 0 || build.rejected_screenshots > 0 || build.pending_screenshots > 0) {
-    verboseInfo.Approvals = `${build.approved_screenshots || 0} approved, ${build.rejected_screenshots || 0} rejected, ${build.pending_screenshots || 0} pending`;
+  if (status.review) {
+    let reviewParts = [['approved', status.review.approved], ['rejected', status.review.rejected], ['pending', status.review.pending]].filter(([, value]) => value != null).map(([label, value]) => `${value} ${label}`);
+    if (reviewParts.length > 0) {
+      verboseInfo.Review = reviewParts.join(', ');
+    }
   }
   if (build.avg_diff_percentage != null) {
     verboseInfo['Avg Diff'] = `${(build.avg_diff_percentage * 100).toFixed(2)}%`;
@@ -163,29 +335,72 @@ function createVerboseInfo(build) {
   if (build.is_baseline) {
     verboseInfo.Baseline = 'Yes';
   }
-  verboseInfo['User Agent'] = build.user_agent || 'Unknown';
+  if (build.user_agent) {
+    verboseInfo['User Agent'] = build.user_agent;
+  }
   verboseInfo['Build ID'] = build.id;
-  verboseInfo['Project ID'] = build.project_id;
+  if (status.scope?.project?.id || build.project_id) {
+    verboseInfo['Project ID'] = status.scope?.project?.id || build.project_id;
+  }
   return verboseInfo;
 }
+
+/**
+ * Format only the processing facts supplied by the API.
+ *
+ * @param {Object|undefined} processing - Canonical processing counts.
+ * @returns {string} Human-readable processing summary.
+ */
+function formatProcessingStatus(processing) {
+  if (!processing) {
+    return '';
+  }
+  let labels = {
+    total: 'total',
+    completed: 'completed',
+    failed: 'failed',
+    active: 'active',
+    pending: 'pending'
+  };
+  return Object.entries(labels).filter(([field]) => processing[field] != null).map(([field, label]) => `${processing[field]} ${label}`).join(' · ');
+}
+
+/**
+ * Present lifecycle, processing, comparisons, and review as separate facts.
+ *
+ * Keeping these lanes separate prevents review-pending counts from looking
+ * like unfinished processing and keeps the human view aligned with JSON.
+ *
+ * @param {Object} options - Human status presentation inputs.
+ */
 function writeHumanStatus({
   build,
   buildUrl,
   globalOptions,
   output,
-  previewInfo
+  previewInfo,
+  status
 }) {
   output.header('status', build.status);
   output.keyValue(createBuildInfo(build));
   output.blank();
   let colors = output.getColors();
-  let comparisonStats = createComparisonStats(build, colors);
-  output.labelValue('Screenshots', String(build.screenshot_count || 0));
+  let comparisonStats = createComparisonStats(status, colors);
+  let processing = getProcessingStatus(status);
+  let screenshotsTotal = processing?.total ?? build.screenshot_count;
+  let processingSummary = formatProcessingStatus(processing);
+  if (screenshotsTotal != null) {
+    output.labelValue('Screenshots', String(screenshotsTotal));
+  }
+  if (processingSummary) {
+    output.labelValue('Processing', processingSummary);
+  }
   if (comparisonStats) {
     output.labelValue('Comparisons', comparisonStats);
   }
-  if (build.approval_status) {
-    output.labelValue('Approval', build.approval_status);
+  let reviewState = getBuildReviewState(status);
+  if (reviewState) {
+    output.labelValue('Review', reviewState);
   }
   output.blank();
   writeStatusTiming({
@@ -207,17 +422,20 @@ function writeHumanStatus({
     output.blank();
     output.divider();
     output.blank();
-    output.keyValue(createVerboseInfo(build));
-  }
-  let progress = getProcessingProgress(build);
-  if (progress !== null) {
-    output.blank();
-    output.print(`  ${output.progressBar(progress, 100)} ${Math.round(progress)}%`);
+    output.keyValue(createVerboseInfo(status));
   }
+  writeSuggestedCommands({
+    build,
+    output
+  });
 }
 
 /**
- * Status command implementation
+ * Fetch and present the server-owned build status contract.
+ *
+ * Preview remains an optional adjacent resource, and established 5xx and
+ * build-failure exit semantics remain unchanged.
+ *
  * @param {string} buildId - Build ID to check status for
  * @param {Object} options - Command options
  * @param {Object} globalOptions - Global CLI options
@@ -227,9 +445,8 @@ export async function statusCommand(buildId, options = {}, globalOptions = {}, d
   let {
     loadConfig,
     createApiClient,
-    getBuild,
+    getBuildStatus,
     getPreviewInfo,
-    getApiUrl,
     output,
     exit
   } = createStatusDeps(deps);
@@ -243,8 +460,8 @@ export async function statusCommand(buildId, options = {}, globalOptions = {}, d
     let config = await loadConfig(globalOptions.config, allOptions);
 
     // Validate API token
-    if (!config.apiKey) {
-      output.error('API token required. Use --token or set VIZZLY_TOKEN environment variable');
+    if (!config.apiKey && !config.userToken) {
+      output.error('Authentication required. Use --token, set VIZZLY_TOKEN, or run "vizzly login"');
       output.cleanup();
       exit(1);
       return {
@@ -261,7 +478,7 @@ export async function statusCommand(buildId, options = {}, globalOptions = {}, d
       createApiClient,
       config
     });
-    let buildStatus = await getBuild(client, buildId);
+    let buildStatus = await getBuildStatus(client, buildId);
 
     // Also fetch preview info (if exists)
     let previewInfo = await fetchOptionalPreviewInfo(getPreviewInfo, client, buildId);
@@ -272,26 +489,26 @@ export async function statusCommand(buildId, options = {}, globalOptions = {}, d
 
     // Output in JSON mode
     if (globalOptions.json) {
-      output.data(createStatusData(build, previewInfo));
+      output.data(createStatusData(buildStatus, previewInfo));
       output.cleanup();
       return;
     }
 
     // Human-readable output
     // Show build URL if we can construct it
-    let baseUrl = config.baseUrl || getApiUrl();
-    let buildUrl = createBuildUrl(baseUrl, build);
+    let buildUrl = buildStatus.links?.web || createBuildUrl(config.apiUrl, build, buildStatus.scope);
     writeHumanStatus({
       build,
       buildUrl,
       globalOptions,
       output,
-      previewInfo
+      previewInfo,
+      status: buildStatus
     });
     output.cleanup();
 
     // Exit with appropriate code based on build status
-    if (shouldFailStatus(build)) {
+    if (shouldFailStatus(buildStatus)) {
       exit(1);
     }
   } catch (error) {

package/dist/commands/tdd.js

@@ -16,8 +16,22 @@ import { initializeDaemon as defaultInitializeDaemon, runTests as defaultRunTest
 import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
 import { detectBranch as defaultDetectBranch, detectCommit as defaultDetectCommit, detectCommitMessage as defaultDetectCommitMessage, detectPullRequestNumber as defaultDetectPullRequestNumber, generateBuildNameWithGit as defaultGenerateBuildNameWithGit } from '../utils/git.js';
 import * as defaultOutput from '../utils/output.js';
-function buildLocalContextCommand() {
-  return 'vizzly context build current --source local --agent';
+
+/**
+ * Build the follow-up command for local TDD evidence.
+ *
+ * JSON consumers need a self-contained command that returns structured
+ * evidence when executed. Human output keeps the existing readable summary.
+ *
+ * @param {Object} options - Command output options.
+ * @param {boolean} [options.structured=false] - Include machine-readable JSON.
+ * @returns {string} Executable local context command.
+ */
+function buildLocalContextCommand({
+  structured = false
+} = {}) {
+  let jsonFlag = structured ? ' --json' : '';
+  return `vizzly context build current --source local --agent${jsonFlag}`;
 }
 
 /**
@@ -257,7 +271,9 @@ export async function tddCommand(testCommand, options = {}, globalOptions = {},
         comparisons,
         summary,
         reportPath: runResult.reportPath || '.vizzly/report/index.html',
-        contextCommand: buildLocalContextCommand()
+        contextCommand: buildLocalContextCommand({
+          structured: true
+        })
       });
       output.cleanup();
     }

package/dist/commands/whoami.js

@@ -182,16 +182,4 @@ export async function whoamiCommand(options = {}, globalOptions = {}, deps = {})
       exit(1);
     }
   }
-}
-
-/**
- * Validate whoami options
- * @param {Object} options - Command options
- */
-export function validateWhoamiOptions() {
-  let errors = [];
-
-  // No specific validation needed for whoami command
-
-  return errors;
 }