@vizzly-testing/cli 0.38.0 → 0.39.0

package/dist/utils/file-changes.js

@@ -0,0 +1,105 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { access, lstat, mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { readOptionalFile } from './config-discovery.js';
+export async function fileChange(filename, after) {
+  let before = await readOptionalFile(filename);
+  return before === after ? null : {
+    path: filename,
+    before,
+    after
+  };
+}
+async function writableParent(filename) {
+  let parent = path.dirname(filename);
+  while (true) {
+    try {
+      await access(parent, constants.W_OK);
+      return;
+    } catch (error) {
+      if (error.code !== 'ENOENT' || path.dirname(parent) === parent) {
+        throw error;
+      }
+      parent = path.dirname(parent);
+    }
+  }
+}
+async function checkChange(change) {
+  // Reject redirects in parent folders too, including explicit config paths.
+  // Top-level OS aliases such as /tmp on macOS are safe to follow.
+  for (let parent = path.dirname(change.path); path.dirname(parent) !== parent; parent = path.dirname(parent)) {
+    try {
+      if (path.dirname(parent) !== path.parse(parent).root && (await lstat(parent)).isSymbolicLink()) {
+        throw new Error(`Setup will not write through a symlink: ${parent}`);
+      }
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
+  let info;
+  try {
+    info = await lstat(change.path);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  if (info?.isSymbolicLink()) {
+    throw new Error(`Setup will not replace a symlink: ${change.path}`);
+  }
+  let current = await readOptionalFile(change.path);
+  if (current !== change.before) {
+    throw new Error(`${change.path} changed during setup; run init again.`);
+  }
+  if (current !== null) {
+    if (!info.isFile()) {
+      throw new Error(`Setup needs a regular file: ${change.path}`);
+    }
+    await access(change.path, constants.W_OK);
+  }
+  await writableParent(change.path);
+}
+export async function preflightChanges(changes) {
+  for (let change of changes.filter(Boolean)) await checkChange(change);
+}
+export async function applyChanges(changes) {
+  let planned = changes.filter(Boolean);
+  await preflightChanges(planned);
+  let completed = [];
+  try {
+    for (let change of planned) {
+      await checkChange(change);
+      await mkdir(path.dirname(change.path), {
+        recursive: true
+      });
+      if (change.before === null) {
+        await writeFile(change.path, change.after, {
+          flag: 'wx'
+        });
+      } else {
+        let temporary = `${change.path}.${randomUUID()}.tmp`;
+        try {
+          let {
+            mode
+          } = await lstat(change.path);
+          await writeFile(temporary, change.after, {
+            flag: 'wx',
+            mode
+          });
+          await rename(temporary, change.path);
+        } finally {
+          await rm(temporary, {
+            force: true
+          });
+        }
+      }
+      completed.push({
+        path: change.path,
+        status: 'written'
+      });
+    }
+  } catch (error) {
+    error.completed = completed;
+    throw error;
+  }
+  return completed;
+}

package/dist/utils/login-poll-wait.js

@@ -0,0 +1,50 @@
+import { setTimeout as delay } from 'node:timers/promises';
+
+/** Wait for the next check, with optional terminal input and a live countdown. */
+export async function waitForLoginPoll({
+  milliseconds,
+  manualAllowed = true,
+  earliestCheckAt = 0,
+  stdin = process.stdin,
+  now = Date.now,
+  sleep = delay,
+  onTick
+}) {
+  if (!stdin.isTTY) {
+    onTick(milliseconds, false);
+    await sleep(milliseconds);
+    return;
+  }
+  let deadline = now() + milliseconds;
+  let requested = false;
+  let timer;
+  let wasFlowing = stdin.readableFlowing === true;
+  let onData = data => {
+    if (manualAllowed && /[\r\n]/.test(data.toString())) {
+      requested = true;
+      timer?.abort();
+    }
+  };
+  if (manualAllowed) {
+    stdin.on('data', onData);
+    stdin.resume();
+  }
+  try {
+    while (true) {
+      let remaining = Math.min(deadline, requested ? earliestCheckAt : deadline) - now();
+      if (remaining <= 0) return;
+      onTick(remaining, manualAllowed && !requested);
+      timer = new AbortController();
+      try {
+        await sleep(Math.min(remaining, 1000), undefined, {
+          signal: timer.signal
+        });
+      } catch (error) {
+        if (!timer.signal.aborted) throw error;
+      }
+    }
+  } finally {
+    stdin.removeListener('data', onData);
+    if (manualAllowed && !wasFlowing) stdin.pause();
+  }
+}

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.0",
+  "version": "0.39.0",
   "description": "Visual regression testing from your terminal",
   "keywords": [
     "llm-context",
@@ -87,24 +87,24 @@
     "fix": "pnpm run format && pnpm run lint:fix"
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": "^22.18.0 || >=24.0.0"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@vizzly-testing/bear-den": "0.1.4",
+    "@vizzly-testing/bear-den": "0.1.6",
     "@vizzly-testing/honeydiff": "^0.17.0",
-    "ansis": "^4.2.0",
+    "ansis": "^4.4.0",
     "commander": "^15.0.0",
-    "cosmiconfig": "^9.0.0",
-    "dotenv": "^17.2.1",
-    "form-data": "^4.0.0",
-    "glob": "^13.0.0",
-    "react": "^19.1.1",
-    "react-dom": "^19.1.1",
-    "zod": "^4.1.12"
+    "cosmiconfig": "^10.0.1",
+    "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.7"
   },
   "tsd": {
     "directory": "test-d",
@@ -117,29 +117,29 @@
     }
   },
   "devDependencies": {
-    "@babel/cli": "^8.0.1",
-    "@babel/core": "^8.0.1",
-    "@babel/preset-env": "^8.0.2",
+    "@babel/cli": "^8.0.6",
+    "@babel/core": "^8.0.6",
+    "@babel/preset-env": "^8.0.6",
     "@babel/preset-react": "^8.0.1",
     "@babel/preset-typescript": "^8.0.1",
-    "@biomejs/biome": "^2.5.10",
+    "@biomejs/biome": "^2.5.15",
     "@heroicons/react": "^2.2.0",
-    "@modelcontextprotocol/sdk": "^1.0.4",
-    "@playwright/test": "^1.55.1",
-    "@tailwindcss/postcss": "^4.1.13",
-    "@tanstack/react-query": "^5.90.11",
-    "@types/node": "^26.0.0",
-    "@vitejs/plugin-react": "^6.0.1",
-    "autoprefixer": "^10.4.21",
+    "@modelcontextprotocol/sdk": "^1.31.0",
+    "@playwright/test": "^1.63.0",
+    "@tailwindcss/postcss": "^4.3.3",
+    "@tanstack/react-query": "^5.104.0",
+    "@types/node": "^26.6.3",
+    "@vitejs/plugin-react": "^6.1.2",
+    "autoprefixer": "^10.6.1",
     "babel-plugin-react-compiler": "^1.0.0",
     "babel-plugin-transform-remove-console": "^6.9.4",
-    "postcss": "^8.5.6",
-    "rimraf": "^6.0.1",
-    "tailwindcss": "^4.1.13",
+    "postcss": "^8.5.29",
+    "rimraf": "^6.1.3",
+    "tailwindcss": "^4.3.3",
     "tsd": "^0.33.0",
     "tui-driver": "github:vizzly-testing/tui-driver",
     "typescript": "^7.0.2",
-    "vite": "^8.2.2",
-    "wouter": "^3.7.1"
+    "vite": "^8.3.1",
+    "wouter": "^3.11.1"
   }
 }

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.