@vizzly-testing/cli 0.38.1 → 0.39.1

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/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/dist/utils/update-check.js

@@ -0,0 +1,2 @@
+import { checkForUpdate } from './update-notifications.js';
+await checkForUpdate();

package/dist/utils/update-notifications.js

@@ -0,0 +1,175 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { agentGuidanceFlag, agentGuidancePath, bundledAgentSkill, planAgentSetup } from '../init/agents.js';
+import { createPrompts } from '../init/prompts.js';
+import { findCliUpdatePlan, runUpdateProcess } from './cli-update.js';
+import { readOptionalFile } from './config-discovery.js';
+import { applyChanges, fileChange, preflightChanges } from './file-changes.js';
+import { getGlobalConfigDir } from './global-config.js';
+import * as output from './output.js';
+import { getPackageName, getPackageVersion } from './package-info.js';
+let day = 24 * 60 * 60 * 1000;
+async function readState(filename) {
+  try {
+    let state = JSON.parse(await readOptionalFile(filename));
+    return state && typeof state === 'object' && !Array.isArray(state) ? state : {};
+  } catch {
+    return {};
+  }
+}
+async function stateChange(filename, state) {
+  return fileChange(filename, `${JSON.stringify(state, null, 2)}\n`);
+}
+
+// The registry's latest tag contains stable releases. Never suggest a downgrade
+// or a prerelease, even when an unexpected registry response is cached.
+export function isNewerStableVersion(candidate, current) {
+  let latest = /^(\d+)\.(\d+)\.(\d+)$/.exec(candidate);
+  let installed = /^(\d+)\.(\d+)\.(\d+)(-[\w.-]+)?(?:\+[\w.-]+)?$/.exec(current);
+  if (!latest || !installed) return false;
+  for (let index = 1; index <= 3; index++) {
+    let difference = Number(latest[index]) - Number(installed[index]);
+    if (difference) return difference > 0;
+  }
+  return Boolean(installed[4]);
+}
+export async function checkForUpdate() {
+  try {
+    let filename = path.join(getGlobalConfigDir(), 'updates.json');
+    let response = await fetch(`https://registry.npmjs.org/${encodeURIComponent(getPackageName())}/latest`, {
+      signal: AbortSignal.timeout(3000)
+    });
+    if (!response.ok) return;
+    let {
+      version
+    } = await response.json();
+    if (!/^\d+\.\d+\.\d+$/.test(version)) return;
+    // Keep notice history saved while the network request was in flight.
+    let state = await readState(filename);
+    await applyChanges([await stateChange(filename, {
+      ...state,
+      latestVersion: version
+    })]);
+  } catch {
+    // Update checks never affect the command being run.
+  }
+}
+async function offerUpdate(cwd, {
+  cliVersion,
+  guidanceFlag
+}) {
+  if (!process.stdin.isTTY) return;
+  let cliPlan = cliVersion ? await findCliUpdatePlan(cwd, cliVersion) : null;
+  if (!cliPlan && !guidanceFlag) return;
+  let updatedCli;
+  try {
+    let guidancePlan;
+    if (!cliPlan && guidanceFlag) {
+      guidancePlan = await planAgentSetup(cwd, {
+        skill: true,
+        guidance: guidanceFlag === '--agent-guidance'
+      });
+      await preflightChanges(guidancePlan.changes);
+    }
+    if (cliPlan) {
+      output.printErr(`  Apply: ${cliPlan.command} ${cliPlan.args.join(' ')} (in ${cliPlan.cwd})`);
+      // A CLI upgrade can bring new guidance even if the current bundle matches.
+      if (!guidanceFlag && (await readOptionalFile(path.join(cwd, '.agents', 'skills', 'vizzly', 'SKILL.md')))) {
+        guidanceFlag = await agentGuidanceFlag(cwd);
+      }
+    }
+    if (guidanceFlag) {
+      output.printErr(`  Refresh: vizzly init ${guidanceFlag} (replaces bundled skill files${guidanceFlag === '--agent-guidance' ? ' and the Vizzly AGENTS.md note' : ''})`);
+    }
+    if (!(await confirmUpdate())) return;
+    if (cliPlan) {
+      await runUpdateProcess(cliPlan.command, cliPlan.args, cliPlan.cwd);
+      updatedCli = cliPlan.cliPath;
+      if (guidanceFlag) {
+        await runUpdateProcess(process.execPath, [cliPlan.cliPath, 'init', guidanceFlag, '--no-update-notifier'], cwd);
+      }
+    } else {
+      await applyChanges(guidancePlan.changes);
+    }
+    output.printErr('  Vizzly update applied.');
+  } catch (error) {
+    if (error.code !== 'INIT_CANCELLED') output.printErr(`  Could not apply the Vizzly update: ${error.message}`);
+  }
+  return updatedCli;
+}
+async function confirmUpdate() {
+  let prompts = createPrompts();
+  try {
+    return await prompts.confirm('Apply available Vizzly updates now?');
+  } finally {
+    prompts.close();
+  }
+}
+async function planGuidanceNotice(cwd, cliVersion) {
+  let installed = await readOptionalFile(path.join(cwd, '.agents', 'skills', 'vizzly', 'SKILL.md'));
+  let guidance = await readState(agentGuidancePath(cwd));
+  if (!installed || isNewerStableVersion(guidance.cliVersion, cliVersion)) return null;
+  let {
+    version,
+    files
+  } = await bundledAgentSkill();
+  if (!guidance.version) {
+    let contents = await Promise.all(files.map(({
+      filename
+    }) => readOptionalFile(path.join(cwd, '.agents', 'skills', 'vizzly', filename))));
+    if (files.every(({
+      content
+    }, index) => content === contents[index])) guidance.version = version;
+  }
+  if (guidance.version === version || guidance.notifiedVersion === version) return null;
+  let flag = await agentGuidanceFlag(cwd);
+  return {
+    flag,
+    message: `Vizzly agent guidance has an update. Run vizzly init ${flag} to refresh it.`,
+    change: await stateChange(agentGuidancePath(cwd), {
+      ...guidance,
+      notifiedVersion: version
+    })
+  };
+}
+function startUpdateCheck() {
+  output.printErr('  Checking for Vizzly updates in the background…');
+  let child = spawn(process.execPath, [fileURLToPath(new URL('./update-check.js', import.meta.url))], {
+    detached: true,
+    stdio: 'ignore'
+  });
+  child.on('error', () => {});
+  child.unref();
+}
+export async function notifyUpdates(options = {}) {
+  if (options.updateNotifier === false || options.json || output.isJson() || !process.stderr.isTTY || !process.stdout.isTTY || process.env.CI || 'NO_UPDATE_NOTIFIER' in process.env || 'VIZZLY_NO_UPDATE_NOTIFIER' in process.env || !['info', 'debug'].includes(output.getLogLevel())) return;
+  try {
+    let cwd = process.cwd();
+    let filename = path.join(getGlobalConfigDir(), 'updates.json');
+    let state = await readState(filename);
+    let messages = [];
+    let available = {};
+    let cliVersion = getPackageVersion();
+    if (isNewerStableVersion(state.latestVersion, cliVersion) && state.notifiedCliVersion !== state.latestVersion) {
+      messages.push(`Vizzly ${state.latestVersion} is available (installed: ${cliVersion}). Update ${getPackageName()} with the package manager that installed it.`);
+      state.notifiedCliVersion = state.latestVersion;
+      available.cliVersion = state.latestVersion;
+    }
+    let guidanceNotice = await planGuidanceNotice(cwd, cliVersion);
+    if (guidanceNotice) {
+      messages.push(guidanceNotice.message);
+      available.guidanceFlag = guidanceNotice.flag;
+    }
+    let checkDue = !Number.isFinite(state.lastCheckedAt) || state.lastCheckedAt > Date.now() || Date.now() - state.lastCheckedAt >= day;
+    if (checkDue) state.lastCheckedAt = Date.now();
+    // If state cannot be saved, stay quiet instead of repeating a notice on
+    // every invocation. Setup's file preflight also protects against symlinks.
+    await applyChanges([guidanceNotice?.change, await stateChange(filename, state)]);
+    for (let message of messages) output.printErr(`  ${message}`);
+    if (checkDue) startUpdateCheck();
+    return await offerUpdate(cwd, available);
+  } catch {
+    // Missing, malformed, or unwritable metadata must not break CLI commands.
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.38.1",
+  "version": "0.39.1",
   "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.9",
     "form-data": "^4.0.6",
     "glob": "^13.0.6",
-    "react": "^19.3.0",
-    "react-dom": "^19.3.0",
-    "zod": "^4.6.5"
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "zod": "^4.6.7"
   },
   "tsd": {
     "directory": "test-d",
@@ -118,28 +118,28 @@
   },
   "devDependencies": {
     "@babel/cli": "^8.0.6",
-    "@babel/core": "^8.0.6",
-    "@babel/preset-env": "^8.0.6",
+    "@babel/core": "^8.0.7",
+    "@babel/preset-env": "^8.0.7",
     "@babel/preset-react": "^8.0.1",
-    "@babel/preset-typescript": "^8.0.1",
-    "@biomejs/biome": "^2.5.15",
+    "@babel/preset-typescript": "^8.0.7",
+    "@biomejs/biome": "^2.6.2",
     "@heroicons/react": "^2.2.0",
-    "@modelcontextprotocol/sdk": "^1.31.0",
-    "@playwright/test": "^1.63.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "@playwright/test": "^1.64.1",
     "@tailwindcss/postcss": "^4.3.3",
-    "@tanstack/react-query": "^5.104.0",
-    "@types/node": "^26.6.3",
+    "@tanstack/react-query": "^5.104.5",
+    "@types/node": "^26.6.5",
     "@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.29",
+    "postcss": "^8.5.31",
     "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.3.1",
-    "wouter": "^3.11.1"
+    "vite": "^8.3.5",
+    "wouter": "^3.13.0"
   }
 }

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.