@vizzly-testing/cli 0.36.0 → 0.38.0

package/dist/test-runner/core.js

@@ -64,6 +64,8 @@ export function buildApiBuildPayload(options, comparisonConfig = null) {
     environment: options.environment || 'test',
     commit_sha: options.commit,
     commit_message: options.message,
+    commit_author_name: options.commitAuthorName,
+    commit_author_email: options.commitAuthorEmail,
     github_pull_request_number: options.pullRequestNumber,
     parallel_id: options.parallelId
   };

package/dist/types/index.d.ts

@@ -165,6 +165,8 @@ export interface UploadOptions {
   branch?: string;
   commit?: string;
   message?: string;
+  commitAuthorName?: string;
+  commitAuthorEmail?: string;
   environment?: string;
   threshold?: number;
   minClusterSize?: number;
@@ -517,6 +519,8 @@ export interface BuildOptions {
   commit_sha?: string;
   message?: string;
   commit_message?: string;
+  commitAuthorName?: string;
+  commitAuthorEmail?: string;
   environment?: string;
   threshold?: number;
   eager?: boolean;

package/dist/uploader/core.js

@@ -154,6 +154,8 @@ export function buildBuildInfo(options, defaultBranch = 'main') {
     branch: options.branch || defaultBranch || 'main',
     commit_sha: options.commit,
     commit_message: options.message,
+    commit_author_name: options.commitAuthorName,
+    commit_author_email: options.commitAuthorEmail,
     environment: options.environment || 'production',
     threshold: options.threshold,
     github_pull_request_number: options.pullRequestNumber,

package/dist/utils/ci-env.js

@@ -156,13 +156,23 @@ export function getCommit() {
 }
 
 /**
- * Get the commit message from CI environment variables
+ * Get the commit message from CI environment variables.
+ *
+ * For GitHub Actions pull_request events, the checkout is a synthetic merge
+ * commit whose message is "Merge <sha> into <sha>", so the PR title from the
+ * event payload is used instead.
+ *
  * @returns {string|null} Commit message or null if not available
  */
 export function getCommitMessage() {
-  return process.env.VIZZLY_COMMIT_MESSAGE ||
-  // Vizzly override
-  process.env.CI_COMMIT_MESSAGE ||
+  if (process.env.VIZZLY_COMMIT_MESSAGE) {
+    return process.env.VIZZLY_COMMIT_MESSAGE;
+  }
+  if (process.env.GITHUB_ACTIONS) {
+    let title = getGitHubEvent().pull_request?.title;
+    if (title) return title;
+  }
+  return process.env.CI_COMMIT_MESSAGE ||
   // GitLab CI
   process.env.TRAVIS_COMMIT_MESSAGE ||
   // Travis CI
@@ -176,6 +186,35 @@ export function getCommitMessage() {
   // Generic
   null;
 }
+
+/**
+ * Parse a "Name <email>" author string (GitLab's CI_COMMIT_AUTHOR format)
+ * @param {string|undefined} value - Author string
+ * @returns {{ name: string|null, email: string|null }}
+ */
+function parseAuthorString(value) {
+  let match = value?.match(/^(.*?)\s*<([^>]*)>\s*$/);
+  if (!match) return {
+    name: value?.trim() || null,
+    email: null
+  };
+  return {
+    name: match[1] || null,
+    email: match[2] || null
+  };
+}
+
+/**
+ * Get the commit author from CI environment variables
+ * @returns {{ name: string|null, email: string|null }} Author name and email
+ */
+export function getCommitAuthor() {
+  let gitlab = parseAuthorString(process.env.CI_COMMIT_AUTHOR);
+  return {
+    name: process.env.VIZZLY_COMMIT_AUTHOR_NAME || gitlab.name || null,
+    email: process.env.VIZZLY_COMMIT_AUTHOR_EMAIL || gitlab.email || null
+  };
+}
 function parsePullRequestNumber(value) {
   if (!/^\d+$/.test(value)) {
     return null;

package/dist/utils/git.js

@@ -1,6 +1,6 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { getBranch as getCIBranch, getCommit as getCICommit, getCommitMessage as getCICommitMessage, getPullRequestNumber } from './ci-env.js';
+import { getBranch as getCIBranch, getCommit as getCICommit, getCommitAuthor as getCICommitAuthor, getCommitMessage as getCICommitMessage, getPullRequestNumber } from './ci-env.js';
 let execFileAsync = promisify(execFile);
 async function runGit(args, cwd = process.cwd()) {
   let {
@@ -124,8 +124,48 @@ export async function detectCommitMessage(override = null, cwd = process.cwd())
   let ciCommitMessage = getCICommitMessage();
   if (ciCommitMessage) return ciCommitMessage;
 
-  // Fallback to regular git log
-  return await getCommitMessage(cwd);
+  // Fallback to git, reading the same commit reported as commit_sha
+  return await readCommit('%B', cwd);
+}
+
+/**
+ * Read a formatted field from the detected build commit.
+ *
+ * Uses detectCommit() so CI checkouts (e.g. GitHub's synthetic PR merge
+ * commit) describe the PR head rather than HEAD. Falls back to HEAD when that
+ * commit is not in local history (shallow clones).
+ *
+ * @param {string} format - git log --format string
+ * @param {string} cwd - Working directory
+ * @returns {Promise<string|null>} Formatted output or null
+ */
+async function readCommit(format, cwd = process.cwd()) {
+  let sha = await detectCommit(null, cwd);
+  let refs = /^[0-9a-f]{4,64}$/i.test(sha || '') ? [sha, 'HEAD'] : ['HEAD'];
+  for (let ref of refs) {
+    try {
+      return await runGit(['log', '-1', `--format=${format}`, ref], cwd);
+    } catch {
+      // Commit not available locally, try the next ref
+    }
+  }
+  return null;
+}
+
+/**
+ * Detect commit author with environment variable support, falling back to git
+ * @param {string} cwd - Working directory
+ * @returns {Promise<{ name: string|null, email: string|null }>}
+ */
+export async function detectCommitAuthor(cwd = process.cwd()) {
+  let author = getCICommitAuthor();
+  if (author.name && author.email) return author;
+  let stdout = await readCommit('%an%x00%ae', cwd);
+  let [gitName, gitEmail] = stdout ? stdout.split('\0') : [];
+  return {
+    name: author.name || gitName || null,
+    email: author.email || gitEmail || null
+  };
 }
 
 /**
@@ -206,9 +246,9 @@ export async function detectCommit(override = null, cwd = process.cwd()) {
  */
 export async function generateBuildNameWithGit(override = null, cwd = process.cwd()) {
   if (override) return override;
-  let branch = await getCurrentBranch(cwd);
-  let shortSha = await getCurrentCommitSha(cwd);
-  if (branch && shortSha) {
+  let branch = await detectBranch(null, cwd);
+  let shortSha = await detectCommit(null, cwd);
+  if (branch && branch !== 'unknown' && shortSha) {
     let shortCommit = shortSha.substring(0, 7);
     return `${branch}-${shortCommit}`;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "description": "Visual regression testing from your terminal",
   "keywords": [
     "llm-context",
@@ -72,17 +72,18 @@
     "dev:reporter": "cd src/reporter && vite --config vite.dev.config.js",
     "test:types": "tsd",
     "prepublishOnly": "pnpm run build",
-    "test": "node --experimental-test-coverage --test --test-concurrency=1 --test-reporter=spec $(find tests -name '*.test.js')",
+    "test": "node --experimental-test-coverage --test --test-concurrency=1 --test-reporter=spec $(find tests clients/swift/tests-js -name '*.test.js')",
     "test:watch": "node --test --test-reporter=spec --watch $(find tests -name '*.test.js')",
     "test:reporter": "playwright test --config=tests/reporter/playwright.config.js",
     "test:reporter:visual": "node bin/vizzly.js tdd run \"pnpm run test:reporter\" --no-open",
     "test:swift:e2e": "pnpm run build && node clients/swift/scripts/run-e2e.js",
+    "test:swift:previews:e2e": "node clients/swift/scripts/run-preview-e2e.js",
     "test:tui": "node --test --test-reporter=spec tests/tui/*.test.js",
     "test:tui:docker": "./tests/tui/run-tui-tests.sh",
-    "lint": "biome check src tests clients/storybook/src clients/storybook/tests clients/static-site/src clients/static-site/tests clients/vitest/src clients/vitest/tests clients/ember/src clients/ember/tests clients/ember/bin",
-    "lint:fix": "biome check --write --unsafe src tests clients/storybook/src clients/storybook/tests clients/static-site/src clients/static-site/tests clients/vitest/src clients/vitest/tests clients/ember/src clients/ember/tests clients/ember/bin",
-    "format": "biome format --write src tests clients/storybook/src clients/storybook/tests clients/static-site/src clients/static-site/tests clients/vitest/src clients/vitest/tests clients/ember/src clients/ember/tests clients/ember/bin",
-    "format:check": "biome format src tests clients/storybook/src clients/storybook/tests clients/static-site/src clients/static-site/tests clients/vitest/src clients/vitest/tests clients/ember/src clients/ember/tests clients/ember/bin",
+    "lint": "biome check src tests clients/storybook/src clients/storybook/tests clients/static-site/src clients/static-site/tests clients/vitest/src clients/vitest/tests clients/ember/src clients/ember/tests clients/ember/bin clients/swift/src clients/swift/tests-js clients/swift/scripts",
+    "lint:fix": "biome check --write --unsafe src tests clients/storybook/src clients/storybook/tests clients/static-site/src clients/static-site/tests clients/vitest/src clients/vitest/tests clients/ember/src clients/ember/tests clients/ember/bin clients/swift/src clients/swift/tests-js clients/swift/scripts",
+    "format": "biome format --write src tests clients/storybook/src clients/storybook/tests clients/static-site/src clients/static-site/tests clients/vitest/src clients/vitest/tests clients/ember/src clients/ember/tests clients/ember/bin clients/swift/src clients/swift/tests-js clients/swift/scripts",
+    "format:check": "biome format src tests clients/storybook/src clients/storybook/tests clients/static-site/src clients/static-site/tests clients/vitest/src clients/vitest/tests clients/ember/src clients/ember/tests clients/ember/bin clients/swift/src clients/swift/tests-js clients/swift/scripts",
     "fix": "pnpm run format && pnpm run lint:fix"
   },
   "engines": {
@@ -94,7 +95,7 @@
   },
   "dependencies": {
     "@vizzly-testing/bear-den": "0.1.4",
-    "@vizzly-testing/honeydiff": "^0.16.0",
+    "@vizzly-testing/honeydiff": "^0.17.0",
     "ansis": "^4.2.0",
     "commander": "^15.0.0",
     "cosmiconfig": "^9.0.0",

package/skills/vizzly/SKILL.md

@@ -20,21 +20,29 @@ test workflow in charge of how the UI is exercised.
 
 ## Inspect And Verify
 
+For cloud API queries, selectable fields, or an authorized review decision,
+start with `vizzly api schema --json` and follow
+[schema discovery](references/cli-context.md#query-the-cloud-api).
+Discover request details as needed instead of loading the entire OpenAPI document.
+Use `vizzly context ... --json` for local evidence and human-readable `context`
+output for guided inspection.
+
 1. Choose the supplied cloud build or comparison when one is named. Otherwise,
    use current local evidence or find the relevant cloud build.
-2. Request bounded JSON:
+2. For cloud data, discover the relevant API operations. For locally saved data,
+   request JSON context:
 
    ```bash
-   vizzly context build current --source local --agent --json
-   vizzly context build <build-id> --source cloud --agent --json
+   vizzly api schema --json
+   vizzly context build current --source local --json
    ```
 
 3. Confirm the build, source, branch, timestamps, baseline, review state, and
-   pagination before drawing conclusions. If `has_more` is true, run the
-   returned next-page command before concluding. Missing fields remain unknown.
-4. Follow `suggested_commands` to inspect a comparison. View its baseline,
-   current, and diff images together. If an image cannot be opened, label the
-   result metadata-only; do not call it visual verification.
+   pagination before drawing conclusions. Follow the schema's page instructions
+   for cloud data. Missing fields remain unknown.
+4. For cloud data, discover the comparison and image operations from the schema.
+   View the baseline, current, and diff images together. If an image cannot be
+   opened, label the result metadata-only; do not call it visual verification.
 5. Read image dimensions, viewport, browser, diff regions, fingerprint, and
    relevant history alongside the images. A prior approval is supporting
    evidence, not permission to approve the current comparison.
@@ -57,7 +65,7 @@ test workflow in charge of how the UI is exercised.
 ## Load A Reference When Needed
 
 - [CLI context](references/cli-context.md): local and cloud evidence, build
-  discovery, drill-downs, images, and TDD lifecycle.
+  discovery, schema queries, review decisions, images, and TDD lifecycle.
 - [SDK capture](references/sdks.md): add or change screenshot capture code.
 - [Dynamic content](references/dynamic-content.md): investigate unstable
   content and screenshot-specific tolerances.

package/skills/vizzly/references/cli-context.md

@@ -4,6 +4,41 @@ Use the repository's established CLI invocation and existing authentication.
 If cloud authentication is unavailable, report the blocker. Do not start an
 interactive login unless setup is in scope.
 
+## Query The Cloud API
+
+Discover the live review API instead of guessing endpoints or adding command flags:
+
+```bash
+vizzly api schema --json
+vizzly api schema <operation-id> --json
+vizzly api schema <operation-id> -q view=fields --json
+vizzly api schema <operation-id> -q view=response --json
+```
+
+The index lists available operations. The default operation view describes the
+method, path, parameters, authentication, and example arguments. Request field
+choices or response types only when needed. API JSON payloads are under
+`data.response`.
+
+Call the discovered path using `vizzly api <path>`, `-X` for its method, `-H`
+for headers, and `-q` for query parameters. Send the discovered API version
+header on data requests. Use `fields` to select just the evidence needed.
+Follow the response's pagination values explicitly; the CLI fetches one page
+per request. Keep cursors opaque and preserve the query they belong to.
+
+For a review, discover projects/builds, then inspect the build's screenshots,
+comparisons, and image endpoints. Download images with `--output <new-file>`
+and view baseline, current, and diff together. Use file output for large analysis
+responses too. Existing files are not overwritten. Export the full schema only
+when needed: `vizzly api schema --full --output <new-file> --json`.
+
+Review decisions require an authorized task, user credentials, and the documented
+organization header. Discover the decision operation's body before sending it
+with `-d @<file>` or `-d @-` for stdin. Generate a fresh `commandId` for each
+intended decision, then read back the review state. Generic writes are not
+automatically replayed; after an uncertain result, inspect state before retrying.
+Treat schema examples as argument arrays, not shell scripts.
+
 ## Choose The Evidence
 
 Use an ID supplied by the task. If no cloud build is supplied, list recent
@@ -12,17 +47,18 @@ builds and select the one matching the branch, commit, or pull request:
 ```bash
 vizzly builds --branch <branch> --limit 5 --json
 vizzly status <build-id> --json
-vizzly context build <build-id> --source cloud --agent --json
+vizzly api schema sdk.getBuildContext --json
 ```
 
-Use status for lifecycle facts and build context for visual evidence. Do not
-assume the first returned comparison is the most important; preserve API order
-and inspect the records relevant to the task.
+Use status for lifecycle facts, then follow the discovered build-context
+operation for visual evidence. Do not assume the first returned comparison is
+the most important; preserve API order and inspect the records relevant to the
+task.
 
 For saved local evidence:
 
 ```bash
-vizzly context build current --source local --agent --json
+vizzly context build current --source local --json
 vizzly context screenshot "<screenshot-name>" --source local --json
 vizzly context review-queue --source local --json
 ```
@@ -50,20 +86,45 @@ vizzly tdd stop --json
 `tdd run` and `tdd start` are alternatives. Stop only a daemon started for the
 current task.
 
+## Review A Local TDD Run
+
+After `tdd run` exits, inspect captures directly from `.vizzly`. These
+commands don't need a running TDD daemon or cloud credentials:
+
+```bash
+vizzly tdd screenshots list --page 1 --page-size 20
+vizzly tdd screenshots latest
+vizzly tdd screenshots show <comparison-id>
+```
+
+`latest` prints the current screenshot path for the most recent capture. Use
+`list` to find a comparison ID when you need a specific screenshot or browser
+variant. During UI iteration, inspect the current image first; request
+`--image diff` or `--image all` when comparison diagnostics help answer the
+question. Open the printed image paths with the available image viewer.
+
+`accept` replaces one local baseline and updates that report entry. Use it only
+when the task explicitly authorizes accepting a baseline; don't accept a change
+just to make a diff disappear:
+
+```bash
+vizzly tdd screenshots accept <comparison-id>
+```
+
 When a cloud build is in scope:
 
 ```bash
 vizzly run "<existing visual test command>" --wait --json
-vizzly context build <build-id> --source cloud --agent --json
+vizzly api schema --json
 ```
 
 ## Inspect A Comparison
 
-Follow the build response's `suggested_commands`. The direct form is:
+Discover comparison and image operations from the schema:
 
 ```bash
-vizzly context comparison <comparison-id> --source <local-or-cloud> --agent --json
-vizzly context comparison <comparison-id> --source <local-or-cloud> --agent --include diffs --json
+vizzly api schema getComparisonContext --json
+vizzly api schema sdk.getComparisonImage --json
 ```
 
 Open all three images together. Prefer `original_url` and fall back to `url`:
@@ -86,12 +147,10 @@ vizzly context similar <fingerprint-hash> --source cloud --json
 vizzly context review-queue --source <local-or-cloud> --json
 ```
 
-Use `--include diffs` only when compact diagnostics are insufficient. Request
-comments only when human review context matters.
+Use the documented response and pagination fields to request only the evidence
+needed. Request comments only when human review context matters.
 
 ## Continue Without Guessing
 
-Run returned `suggested_commands` rather than reconstructing IDs, sources, or
-pagination. When more evidence exists, the next-page command carries the API's
-opaque `--cursor`; do not edit or interpret it. Keep follow-up commands pinned
-to the source that produced the evidence.
+Use IDs and pagination values from API responses. Keep cursors opaque and
+preserve the query they belong to when requesting the next page.

package/skills/vizzly/references/setup-ci.md

@@ -36,8 +36,8 @@ vizzly finalize "<shared-ci-run-id>" --json
 - `vizzly doctor`: local configuration
 - `vizzly tdd status --json`: a local daemon started by the task
 - `vizzly status <build-id> --json`: cloud lifecycle
-- `vizzly context build <build-id> --source cloud --agent --json`: visual
-  evidence
+- `vizzly api schema --json`: discover supported cloud review operations and
+  their request and response schemas.
 
 If screenshots are absent, verify the existing integration, the test path that
 should capture them, and the active session. If authentication is absent,