@vizzly-testing/cli 0.38.1 → 0.39.0

package/dist/utils/project-binding.js

@@ -0,0 +1,96 @@
+import path from 'node:path';
+import { VizzlyError } from '../errors/vizzly-error.js';
+import { discoverConfig } from './config-discovery.js';
+import { applyChanges } from './file-changes.js';
+function sameProject(left, right) {
+  return left?.organizationSlug === right.organizationSlug && left?.projectSlug === right.projectSlug;
+}
+function bindingValues(project, apiUrl) {
+  return {
+    ...(apiUrl !== 'https://app.vizzly.dev' ? {
+      apiUrl
+    } : {}),
+    project
+  };
+}
+function javascriptBinding(values) {
+  return `export default ${JSON.stringify(values, null, 2)};\n`;
+}
+export async function planProjectBinding({
+  cwd = process.cwd(),
+  configPath = null,
+  project,
+  apiUrl = 'https://app.vizzly.dev',
+  currentProject,
+  currentApiUrl
+}) {
+  let config = await discoverConfig({
+    cwd,
+    configPath
+  });
+  let filename = config.configPath || path.join(cwd, 'vizzly.config.js');
+  let values = bindingValues(project, apiUrl);
+  let plan = {
+    status: 'ready',
+    configPath: filename,
+    before: config.source,
+    after: null
+  };
+  if (config.exists && sameProject(currentProject, project) && currentApiUrl === apiUrl) {
+    return plan;
+  }
+  if (!config.exists) {
+    if (['javascript', 'typescript'].includes(config.format)) {
+      plan.after = javascriptBinding(values);
+    } else if (config.format === 'json') {
+      plan.after = `${JSON.stringify(values, null, 2)}\n`;
+    } else {
+      throw new VizzlyError(`Cannot create a project binding in ${filename}. Use a JavaScript, TypeScript, or JSON config.`, 'PROJECT_CONFIG_FORMAT');
+    }
+    return plan;
+  }
+  if (config.format === 'package' || config.format === 'json') {
+    let document = JSON.parse(config.source);
+    let existing = config.format === 'package' ? document.vizzly || {} : document;
+    let updated = {
+      ...existing,
+      ...values
+    };
+    if (apiUrl === 'https://app.vizzly.dev' && existing.apiUrl) {
+      updated.apiUrl = apiUrl;
+    }
+    let result = config.format === 'package' ? {
+      ...document,
+      vizzly: updated
+    } : updated;
+    let indent = config.source.match(/\n([ \t]+)\S/)?.[1] || '  ';
+    plan.after = `${JSON.stringify(result, null, indent)}\n`;
+    return plan;
+  }
+
+  // A freshly scaffolded config contains only comments. Add the binding without
+  // interpreting or rewriting executable configuration supplied by the user.
+  let comments = String.raw`(?:\s|\/\/[^\n]*(?:\n|$)|\/\*[\s\S]*?\*\/)*`;
+  let emptyModule = new RegExp(`^${comments}export\\s+default\\s*\\{${comments}\\}\\s*;?\\s*$`);
+  if (['javascript', 'typescript'].includes(config.format) && emptyModule.test(config.source)) {
+    let propertyText = JSON.stringify(values, null, 2).slice(1, -1);
+    let closingBrace = config.source.lastIndexOf('}');
+    plan.after = `${config.source.slice(0, closingBrace).trimEnd()}\n${propertyText}\n${config.source.slice(closingBrace)}`;
+    return plan;
+  }
+  return {
+    ...plan,
+    status: 'manual',
+    instructions: `Add these fields to ${filename}, then run project link again:\n${JSON.stringify(values, null, 2)}`
+  };
+}
+export async function writeProjectBinding(plan) {
+  if (plan.status !== 'ready' || plan.after === null) {
+    return;
+  }
+  await applyChanges([{
+    path: plan.configPath,
+    before: plan.before,
+    after: plan.after
+  }]);
+}

package/dist/utils/project-link-store.js

@@ -49,25 +49,31 @@ export async function saveProjectLink(link, deps = {}) {
     token: link.token
   };
 }
-export async function getActiveProjectLink(options = {}, deps = {}) {
+export async function getProjectLink(options = {}, deps = {}) {
   let {
     loadConfig = loadGlobalConfig,
-    getSecret = defaultGetSecret
+    getSecret = defaultGetSecret,
+    now = Date.now
   } = deps;
+  if (!options.account && !(options.organizationSlug && options.projectSlug)) {
+    return null;
+  }
   let config = await loadConfig();
   let projectLink = getProjectLinkConfig(config);
-  let account = options.account || projectLink.active;
+  let account = options.account || buildProjectLinkAccount(options);
   let link = account ? projectLink.links?.[account] : null;
-  if (!link && options.apiUrl && options.organizationSlug && options.projectSlug) {
-    account = buildProjectLinkAccount(options);
-    link = projectLink.links?.[account] || null;
-  }
   if (!link) {
     return null;
   }
   if (options.apiUrl && link.apiUrl && link.apiUrl !== options.apiUrl) {
     return null;
   }
+  if (link.expiresAt) {
+    let expiresAt = Date.parse(link.expiresAt);
+    if (!Number.isFinite(expiresAt) || expiresAt <= now()) {
+      return null;
+    }
+  }
   let token = link.storage === 'keychain' ? await getSecret(account) : link.token;
   if (!token) {
     return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.38.1",
+  "version": "0.39.0",
   "description": "Visual regression testing from your terminal",
   "keywords": [
     "llm-context",
@@ -99,12 +99,12 @@
     "ansis": "^4.4.0",
     "commander": "^15.0.0",
     "cosmiconfig": "^10.0.1",
-    "dotenv": "^17.4.2",
+    "dotenv": "^18.0.3",
     "form-data": "^4.0.6",
     "glob": "^13.0.6",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
-    "zod": "^4.6.5"
+    "zod": "^4.6.7"
   },
   "tsd": {
     "directory": "test-d",

package/skills/vizzly/SKILL.md

@@ -41,8 +41,9 @@ output for guided inspection.
    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.
+   View the current image with the baseline and diff when they're available.
+   A new screenshot may have no baseline or diff. Say which images you inspected;
+   if you couldn't open any images, label the result metadata-only.
 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.
@@ -69,4 +70,4 @@ output for guided inspection.
 - [SDK capture](references/sdks.md): add or change screenshot capture code.
 - [Dynamic content](references/dynamic-content.md): investigate unstable
   content and screenshot-specific tolerances.
-- [Setup and CI](references/setup-ci.md): initialize Vizzly or change CI.
+- [CI](references/ci.md): run visual tests with committed config and CI secrets.

package/skills/vizzly/references/ci.md

@@ -0,0 +1,33 @@
+# CI
+
+CI uses the config committed to the repository. Set up Vizzly locally first.
+
+## Cloud CI
+
+Use a project token from the repo's existing secret store. Never print it or
+save it in the repo.
+
+```bash
+vizzly run "<existing visual test command>" --json
+```
+
+Add `--wait` when you want CI to wait for cloud comparisons and fail on visual
+differences. Changed comparisons then make the command exit with code `1`.
+
+For parallel CI, give every shard the same ID for that CI run. Run shards
+without `--wait`, then finalize once they all finish:
+
+```bash
+vizzly run "<shard test command>" --parallel-id "<shared-ci-run-id>" --json
+vizzly finalize "<shared-ci-run-id>" --json
+```
+
+## Troubleshoot
+
+- `vizzly doctor`: check local config.
+- `vizzly status <build-id> --json`: check cloud build status.
+- `vizzly api schema --json`: find cloud review requests and their inputs
+  and outputs.
+
+If screenshots are missing, check the integration and the test that should
+capture them. If auth is missing, check the `VIZZLY_TOKEN` CI secret.

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

@@ -1,12 +1,12 @@
-# CLI Context
+# CLI context
 
-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.
+Use the repo's usual CLI command and existing credentials. If cloud auth isn't
+available, report it. Only start an interactive login when setup is part of
+the task.
 
-## Query The Cloud API
+## Query the cloud API
 
-Discover the live review API instead of guessing endpoints or adding command flags:
+Check the live API schema for endpoints and options:
 
 ```bash
 vizzly api schema --json
@@ -15,34 +15,38 @@ 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`.
+The index lists available requests. Each operation shows the method, path,
+parameters, auth, and example arguments. Ask for field choices or response types
+as needed. API results 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.
+Call the returned path with `vizzly api <path>`. Use `-X` for the method, `-H`
+for headers, and `-q` for query parameters. Include the API version header from
+the schema on data requests. Use `fields` to ask for just the data you need.
 
-For a review, discover projects/builds, then inspect the build's screenshots,
+The CLI fetches one page per request. Use the response's page fields to get
+more results. Pass cursors back unchanged and keep the same query.
+
+To review a build, find the project and build, then check its 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`.
+and view the baseline, current, and diff together. File output also helps with
+large analysis results. Existing files won't be overwritten. Export the full
+schema only when needed:
+
+```bash
+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.
+Review decisions need the user's authorization, user credentials, and the
+organization header listed in the schema. Check the decision request's body
+before sending it with `-d @<file>` or `-d @-` for stdin. Make a fresh `commandId`
+for each intended decision, then read back the review state. Writes aren't
+retried automatically. If you're unsure whether one succeeded, check the state
+before trying again. Treat schema examples as argument arrays, not shell scripts.
 
-## Choose The Evidence
+## Choose the evidence
 
-Use an ID supplied by the task. If no cloud build is supplied, list recent
-builds and select the one matching the branch, commit, or pull request:
+Use the ID supplied by the task. If no cloud build is named, find recent builds
+and choose the one matching the branch, commit, or pull request:
 
 ```bash
 vizzly builds --branch <branch> --limit 5 --json
@@ -50,12 +54,11 @@ vizzly status <build-id> --json
 vizzly api schema sdk.getBuildContext --json
 ```
 
-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.
+Use status to check build progress, then follow the build-context API for
+screenshots and diffs. Keep the API's comparison order and inspect the records
+that matter to the task. The first comparison isn't necessarily the most useful.
 
-For saved local evidence:
+For saved local results:
 
 ```bash
 vizzly context build current --source local --json
@@ -63,18 +66,18 @@ vizzly context screenshot "<screenshot-name>" --source local --json
 vizzly context review-queue --source local --json
 ```
 
-Confirm the stored build, branch, timestamp, and baseline are current enough
+Check that the saved build, branch, timestamp, and baseline are recent enough
 for the task.
 
-## Generate Fresh Evidence
+## Generate fresh evidence
 
-For one run, let Vizzly own the local session:
+For one run, let Vizzly start and stop the local server:
 
 ```bash
 vizzly tdd run "<existing visual test command>" --no-open
 ```
 
-For repeated runs, start the detached daemon once:
+For repeated runs, start a background server once:
 
 ```bash
 vizzly tdd start --json
@@ -83,13 +86,12 @@ vizzly tdd status --json
 vizzly tdd stop --json
 ```
 
-`tdd run` and `tdd start` are alternatives. Stop only a daemon started for the
-current task.
+Choose `tdd run` or `tdd start`. Only stop a server started for this task.
 
-## Review A Local TDD Run
+## 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:
+After `tdd run` exits, read captures from `.vizzly/`. You don't need a running
+server or cloud credentials:
 
 ```bash
 vizzly tdd screenshots list --page 1 --page-size 20
@@ -97,49 +99,61 @@ 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.
+`latest` prints the newest current screenshot's path. Use `list` to find a
+specific comparison ID or browser variant. While changing UI, open the current
+image first. Add `--image diff` or `--image all` when you need to compare it.
+Open the printed paths with an 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:
+`accept` replaces one local baseline and updates the report entry. Use it only
+when the task explicitly authorizes accepting a baseline:
 
 ```bash
 vizzly tdd screenshots accept <comparison-id>
 ```
 
-When a cloud build is in scope:
+Don't accept a change just to make a diff disappear.
+
+When the task calls for a cloud build:
 
 ```bash
-vizzly run "<existing visual test command>" --wait --json
+vizzly run "<existing visual test command>" --json
 vizzly api schema --json
 ```
 
-## Inspect A Comparison
+To make visual differences fail CI, see the
+[CI guide](ci.md#cloud-ci).
+
+## Inspect a comparison
 
-Discover comparison and image operations from the schema:
+Find comparison and image requests in the schema:
 
 ```bash
 vizzly api schema getComparisonContext --json
 vizzly api schema sdk.getComparisonImage --json
 ```
 
-Open all three images together. Prefer `original_url` and fall back to `url`:
+Request `comparison.images` to check which current, baseline, and diff images
+are available. Download them through `sdk.getComparisonImage`, using the
+comparison ID and image kind. Include the version header from the schema and
+use `--output <new-file>` to save each image.
 
-- Current: `comparison.screenshot.original_url` or
-  `comparison.screenshot.url`
-- Baseline: `comparison.baseline.original_url` or `comparison.baseline.url`
-- Diff: `comparison.analysis.diff_image_url`
+View the available images together. A new capture may have no baseline, and an
+identical capture may have no diff. Report missing or inaccessible images;
+don't invent them. Request `comparison.review` to check the review decision.
 
-Then compare the visible change with diff regions, fingerprint, and the
-separate `similar_by_fingerprint` and `recent_by_name` history streams.
-Previous review decisions help explain recurring evidence but do not decide the
-current review.
+Changed regions and full analysis use separate requests. Discover them when
+the images alone don't answer the question:
 
-Useful supporting commands:
+```bash
+vizzly api schema sdk.getComparisonRegions --json
+vizzly api schema sdk.getComparisonAnalysis --json
+```
+
+Use `--output <new-file>` for full analysis. Compare those details with the
+images and earlier comparisons. Previous decisions can help explain a recurring
+change; they don't decide the current review.
+
+Other useful commands:
 
 ```bash
 vizzly context screenshot "<screenshot-name>" --source <local-or-cloud> --json
@@ -147,10 +161,6 @@ vizzly context similar <fingerprint-hash> --source cloud --json
 vizzly context review-queue --source <local-or-cloud> --json
 ```
 
-Use the documented response and pagination fields to request only the evidence
-needed. Request comments only when human review context matters.
-
-## Continue Without Guessing
-
-Use IDs and pagination values from API responses. Keep cursors opaque and
-preserve the query they belong to when requesting the next page.
+Use IDs and page values from the API response. Pass cursors back unchanged,
+keep the same query, and request only what you need. Fetch comments when they
+help explain a review.

package/skills/vizzly/references/dynamic-content.md

@@ -1,28 +1,27 @@
-# Dynamic Content
+# Dynamic content
 
 Dates, timers, random data, API content, generated images, and responsive text
-can cause a diff. They are possible explanations, not conclusions.
+can cause diffs. Check the images before deciding that's what happened.
 
-## Diagnose Before Tuning
+## Check before changing settings
 
-1. Inspect the actual images and screenshot history:
+1. Open the images and check screenshot history:
 
    ```bash
    vizzly context screenshot "<screenshot-name>" --source <local-or-cloud> --json
    ```
 
-2. Record the visible region, recurrence, render metadata, and whether the same
-   change appears across builds or variants.
-3. Prefer deterministic fixtures when they can remove irrelevant variation.
-4. Use diff regions only to locate changed pixels; they do not approve a
-   comparison or explain why it changed.
-5. Preserve `threshold` and `minClusterSize` unless repeated evidence
-   justifies a change.
+2. Note where the change appears, how often it happens, the capture details,
+   and whether it appears in other builds or variants.
+3. Use fixed test data when it can remove changes unrelated to the test.
+4. Use diff regions to find changed pixels. They don't tell you why the pixels
+   changed or whether to approve them.
+5. Keep `threshold` and `minClusterSize` unless repeated captures show they
+   need to change.
 
-Avoid broad masks, global threshold changes for one region, and claims based on
-metadata alone. A recurring change can still be a bug, especially when content
-movement affects nearby layout.
+Avoid broad masks or global threshold changes to hide a problem in one region.
+Metadata alone can't explain a visual change. A recurring change can still be
+a bug, especially if moving content changes nearby layout.
 
-Report the observed change first. Label fixture drift, layout shift, capture
-timing, or baseline mismatch as a possible cause until the evidence establishes
-it.
+Describe what you see first. Treat changing test data, layout shifts, capture
+timing, or a wrong baseline as possible causes until you can confirm them.

package/skills/vizzly/references/sdks.md

@@ -1,8 +1,8 @@
-# SDK Capture
+# SDK capture
 
-Use the repository's existing Vizzly integration and user journey. The
-JavaScript example applies only when no framework-specific capture path already
-owns the workflow.
+Use the repo's existing Vizzly integration and test flow. Use this JavaScript
+example only if the repo doesn't already capture screenshots through a
+framework integration.
 
 ## JavaScript
 
@@ -14,28 +14,28 @@ await vizzlyScreenshot('settings-profile-edit-mode', screenshot);
 ```
 
 `vizzlyScreenshot(name, image, options)` accepts PNG bytes or a file path.
-Options include `properties`, `threshold`, `minClusterSize`, and
-`fullPage`. Preserve existing tuning unless visual evidence justifies changing
-it.
+Options include `properties`, `threshold`, `minClusterSize`, and `fullPage`.
+Keep existing settings unless the images show why they need to change.
 
-## Keep Identity Stable
+## Keep names and baseline matching consistent
 
-Use a descriptive name. Identity always includes the name, viewport width, and
-browser. Configured `signatureProperties` add custom identity fields; other
-properties are metadata.
+Use descriptive names and keep them the same across runs. Baseline matching
+always uses the name, viewport width, and browser. To also match on custom
+properties, use `signatureProperties` in `vizzly.config.js` for local baselines.
+Cloud baselines use the project's signature settings. Other properties are
+metadata.
 
-Do not assume theme, locale, or state creates a separate baseline unless the
-configuration says so. Avoid generic names such as `screenshot1` and names
-with slashes.
+Theme, locale, or state won't create a separate baseline unless the matching
+settings include them. Avoid generic names like `screenshot1` and names with
+slashes.
 
-## Follow Existing Integrations
+## Follow the existing setup
 
-- Keep the Vizzly Vitest matcher when it is already configured:
+Keep the Vitest matcher if it's already configured:
 
-  ```javascript
-  await expect(page).toMatchScreenshot('hero-section.png');
-  ```
+```javascript
+await expect(page).toMatchScreenshot('hero-section.png');
+```
 
-- Prefer existing Storybook, static-site, Ember, or Swift capture flows over a
-  parallel test path.
-- Inspect the repository's integration setup before changing capture code.
+Check the repo's setup before changing capture code. Use its Storybook,
+static-site, Ember, or Swift integration if it has one.

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

@@ -1,44 +0,0 @@
-# Setup And CI
-
-Use this reference only when the task includes initialization, CI changes, or
-configuration troubleshooting. These workflows mutate files or external build
-state.
-
-## Initialize
-
-Initialize only with authorization:
-
-```bash
-vizzly init
-```
-
-Use [CLI context](cli-context.md) for local evidence and TDD lifecycle commands.
-
-## Cloud CI
-
-Use a project-scoped token from the repository's existing secret system. Never
-print it or write it into the repository.
-
-```bash
-vizzly run "<existing visual test command>" --wait --json
-```
-
-For parallel CI, give every shard the same workflow-specific parallel ID. Run
-shards without `--wait`, then finalize once after all shards finish:
-
-```bash
-vizzly run "<shard test command>" --parallel-id "<shared-ci-run-id>" --json
-vizzly finalize "<shared-ci-run-id>" --json
-```
-
-## Troubleshoot
-
-- `vizzly doctor`: local configuration
-- `vizzly tdd status --json`: a local daemon started by the task
-- `vizzly status <build-id> --json`: cloud lifecycle
-- `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,
-report it rather than logging in unless setup is in scope.