@vizzly-testing/cli 0.32.0 → 0.34.0

package/dist/utils/colors.js

@@ -4,56 +4,47 @@
 import { Ansis } from 'ansis';
 
 // =============================================================================
-// Vizzly Observatory Design System Colors
-// Aligned with @vizzly-testing/observatory color tokens
+// Vizzly BearDen Design System Colors
+// Aligned with the reporter design system color tokens.
 // =============================================================================
 
 export let brand = {
-  // Primary brand color - Amber is Observatory's signature
-  amber: '#F59E0B',
+  // Primary brand color - restrained brass on graphite
+  amber: '#D69A35',
   // Primary brand, actions, highlights
-  amberLight: '#FBBF24',
+  amberLight: '#E0AD55',
   // Hover states, emphasis
 
   // Accent colors (semantic)
-  success: '#10B981',
+  success: '#7FD990',
   // Approved, passed, active (--accent-success)
-  warning: '#F59E0B',
+  warning: '#DCAD5F',
   // Pending, attention (--accent-warning)
-  danger: '#EF4444',
+  danger: '#D77782',
   // Rejected, failed, errors (--accent-danger)
-  info: '#3B82F6',
+  info: '#B7BDC6',
   // Processing, informational (--accent-info)
 
   // Surface colors (dark theme)
-  bg: '#0F172A',
+  bg: '#07080A',
   // Page background (--vz-bg)
-  surface: '#1A2332',
+  surface: '#101216',
   // Cards, panels (--vz-surface)
-  elevated: '#1E293B',
+  elevated: '#111318',
   // Dropdowns, modals (--vz-elevated)
-  border: '#374151',
+  border: '#30343B',
   // Primary borders (--vz-border)
-  borderSubtle: '#2D3748',
+  borderSubtle: '#252930',
   // Subtle dividers (--vz-border-subtle)
 
   // Text hierarchy
-  textPrimary: '#FFFFFF',
+  textPrimary: '#F4F6F8',
   // Headings, important (--text-primary)
-  textSecondary: '#9CA3AF',
+  textSecondary: '#C8CDD3',
   // Body text (--text-secondary)
-  textTertiary: '#6B7280',
+  textTertiary: '#A0A6AF',
   // Captions, metadata (--text-tertiary)
-  textMuted: '#4B5563',
-  // Disabled, placeholders (--text-muted)
-
-  // Legacy aliases (for backward compatibility)
-  green: '#10B981',
-  red: '#EF4444',
-  cyan: '#06B6D4',
-  // Still useful for links in terminals
-  slate: '#64748B',
-  dark: '#1E293B'
+  textMuted: '#7A828D' // Disabled, placeholders (--text-muted)
 };
 function supportsColorDefault() {
   // Respect NO_COLOR: https://no-color.org/
@@ -124,7 +115,7 @@ export function createColors(options = {}) {
       hex: () => noop,
       bgRgb: () => noop,
       bgHex: () => noop,
-      // Observatory brand colors (noop versions)
+      // BearDen brand colors (noop versions)
       brand: {
         // Primary
         amber: noop,
@@ -133,6 +124,7 @@ export function createColors(options = {}) {
         success: noop,
         warning: noop,
         danger: noop,
+        error: noop,
         info: noop,
         // Text hierarchy
         textPrimary: noop,
@@ -144,12 +136,7 @@ export function createColors(options = {}) {
         bgSuccess: noop,
         bgWarning: noop,
         bgDanger: noop,
-        bgInfo: noop,
-        // Legacy aliases
-        green: noop,
-        red: noop,
-        cyan: noop,
-        slate: noop
+        bgInfo: noop
       }
     };
   }
@@ -173,16 +160,16 @@ export function createColors(options = {}) {
     gray: colors.gray,
     black: colors.black,
     // Semantic aliases (basic)
-    success: colors.green,
-    error: colors.red,
-    warning: colors.yellow,
-    info: colors.blue,
+    success: colors.hex(brand.success),
+    error: colors.hex(brand.danger),
+    warning: colors.hex(brand.warning),
+    info: colors.hex(brand.info),
     // Extended colors for rich styling
     rgb: colors.rgb.bind(colors),
     hex: colors.hex.bind(colors),
     bgRgb: colors.bgRgb.bind(colors),
     bgHex: colors.bgHex.bind(colors),
-    // Observatory brand colors (Truecolor) - aligned with design system
+    // BearDen brand colors (Truecolor) - aligned with design system
     brand: {
       // Primary brand color
       amber: colors.hex(brand.amber),
@@ -191,6 +178,7 @@ export function createColors(options = {}) {
       success: colors.hex(brand.success),
       warning: colors.hex(brand.warning),
       danger: colors.hex(brand.danger),
+      error: colors.hex(brand.danger),
       info: colors.hex(brand.info),
       // Text hierarchy
       textPrimary: colors.hex(brand.textPrimary),
@@ -202,12 +190,7 @@ export function createColors(options = {}) {
       bgSuccess: colors.bgHex(brand.success),
       bgWarning: colors.bgHex(brand.warning),
       bgDanger: colors.bgHex(brand.danger),
-      bgInfo: colors.bgHex(brand.info),
-      // Legacy aliases (backward compatibility)
-      green: colors.hex(brand.green),
-      red: colors.hex(brand.red),
-      cyan: colors.hex(brand.cyan),
-      slate: colors.hex(brand.slate)
+      bgInfo: colors.bgHex(brand.info)
     }
   };
 }

package/dist/utils/global-config.js

@@ -121,7 +121,7 @@ export async function clearGlobalConfig() {
 
 /**
  * Save user's PATH for menubar app to use
- * This auto-configures the menubar app so it can find npx/node
+ * This auto-configures the menubar app so it can find package runners/node
  * @returns {Promise<void>}
  */
 export async function saveUserPath() {

package/dist/utils/output.js

@@ -235,7 +235,7 @@ export function isVerbose() {
 
 /**
  * Show command header with distinctive branding
- * Uses Observatory's signature amber color for "vizzly"
+ * Uses BearDen's signature amber color for "vizzly"
  * Only shows once per command execution
  * @param {string} command - Command name (e.g., 'tdd', 'run')
  * @param {string} [mode] - Optional mode (e.g., 'local', 'cloud')
@@ -245,7 +245,7 @@ export function header(command, mode = null) {
   headerShown = true;
   let parts = [];
 
-  // Brand "vizzly" with Observatory's signature amber
+  // Brand "vizzly" with BearDen's signature amber
   parts.push(colors.brand.amber(colors.bold('vizzly')));
 
   // Command in info blue (processing, active)
@@ -289,7 +289,7 @@ export function success(message, data = {}) {
     }));
   } else {
     console.error('');
-    console.error(colors.green('✓'), message);
+    console.error(colors.success('✓'), message);
   }
 }
 
@@ -308,7 +308,7 @@ export function result(message) {
     }));
   } else {
     console.error('');
-    console.error(colors.green('✓'), `${message} ${colors.dim(`· ${elapsed}`)}`);
+    console.error(colors.success('✓'), `${message} ${colors.dim(`· ${elapsed}`)}`);
   }
 }
 
@@ -325,7 +325,7 @@ export function info(message, data = {}) {
       ...data
     }));
   } else {
-    console.log(colors.cyan('ℹ'), message);
+    console.log(colors.info('ℹ'), message);
   }
 }
 
@@ -375,7 +375,7 @@ export function error(message, err = null, data = {}) {
     }
     console.error(JSON.stringify(errorData));
   } else {
-    console.error(colors.red('✖'), message);
+    console.error(colors.error('✖'), message);
 
     // Show error details
     if (err instanceof Error) {
@@ -456,7 +456,7 @@ export function getJsonFields() {
 
 /**
  * Start a spinner with message
- * Uses Observatory amber for the spinner animation
+ * Uses BearDen amber for the spinner animation
  */
 export function startSpinner(message) {
   if (config.json || config.silent || !process.stderr.isTTY) return;
@@ -578,12 +578,12 @@ function formatData(data) {
  */
 /**
  * Get a distinctive color for a component name
- * Uses Observatory design system colors for consistent styling
+ * Uses BearDen design system colors for consistent styling
  * @param {string} component - Component name
  * @returns {Function} Color function
  */
 function getComponentColor(component) {
-  // Map components to Observatory semantic colors
+  // Map components to BearDen semantic colors
   let componentColors = {
     // Server/infrastructure - success green (active, running)
     server: colors.brand.success,
@@ -698,7 +698,7 @@ function writeLog(level, message, data = {}) {
 /**
  * Generate a visual diff bar with color coding
  * Shows percentage as a filled/empty bar with color based on severity
- * Uses Observatory semantic colors (success → warning → danger)
+ * Uses BearDen semantic colors (success → warning → danger)
  * @param {number} percentage - Diff percentage (0-100)
  * @param {number} [width=10] - Bar width in characters
  * @returns {string} Colored diff bar string
@@ -716,7 +716,7 @@ export function diffBar(percentage, width = 10) {
   if (percentage > 0 && filled === 0) filled = 1;
   let empty = width - filled;
 
-  // Color based on severity using Observatory semantic colors
+  // Color based on severity using BearDen semantic colors
   let barColor;
   if (percentage < 1) {
     barColor = colors.brand.success; // Green - minimal change
@@ -733,7 +733,7 @@ export function diffBar(percentage, width = 10) {
 /**
  * Generate a gradient progress bar
  * Creates a visually appealing progress indicator with color gradient
- * Default gradient uses Observatory amber → amber-light (signature brand gradient)
+ * Default gradient uses BearDen amber → amber-light (signature brand gradient)
  * @param {number} current - Current progress value
  * @param {number} total - Total value
  * @param {number} [width=20] - Bar width in characters
@@ -745,7 +745,7 @@ export function diffBar(percentage, width = 10) {
 export function progressBar(current, total, width = 20, options = {}) {
   if (config.json || config.silent) return '';
 
-  // Default to Observatory's signature amber gradient
+  // Default to BearDen's signature amber gradient
   let {
     from = '#F59E0B',
     to = '#FBBF24'
@@ -791,7 +791,7 @@ function hexToRgb(hex) {
 
 /**
  * Create a colored badge/pill for status indicators
- * Uses Observatory semantic colors for consistent meaning
+ * Uses BearDen semantic colors for consistent meaning
  * @param {string} text - Badge text
  * @param {string} [type='info'] - Badge type: 'success', 'warning', 'error', 'info'
  * @returns {string} Formatted badge string
@@ -826,7 +826,7 @@ export function badge(text, type = 'info') {
 
 /**
  * Create a colored status dot
- * Uses Observatory semantic colors for consistent meaning
+ * Uses BearDen semantic colors for consistent meaning
  * @param {string} [status='info'] - Status type: 'success', 'warning', 'error', 'info'
  * @returns {string} Colored dot character
  */
@@ -1033,7 +1033,7 @@ export function box(content, options = {}) {
     innerWidth = Math.max(innerWidth, titleWidth);
   }
 
-  // Border styling - use Observatory amber for 'branded' style
+  // Border styling - use BearDen amber for 'branded' style
   let border = borderColor || (style === 'branded' ? colors.brand.amber : colors.dim);
   let titleColor = style === 'branded' ? colors.bold : s => s;
 

package/dist/utils/screenshot-options.js

@@ -6,6 +6,7 @@ export function createScreenshotProperties(options = {}) {
   let {
     buildId: _buildId,
     properties = {},
+    requestTimeout: _requestTimeout,
     threshold,
     minClusterSize,
     fullPage,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.32.0",
-  "description": "Visual review for agents and teams",
+  "version": "0.34.0",
+  "description": "Visual regression testing from your terminal",
   "keywords": [
     "llm-context",
     "visual-context",
@@ -23,6 +23,7 @@
   "license": "MIT",
   "author": "Stubborn Mule Software <support@vizzly.dev>",
   "type": "module",
+  "packageManager": "pnpm@11.3.0",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
@@ -53,13 +54,15 @@
   "files": [
     "bin",
     "dist",
+    "docs/assets",
+    "skills",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
     "cli": "source .envrc && node bin/vizzly.js",
     "start": "node src/index.js",
-    "build": "npm run clean && npm run compile && npm run build:reporter && npm run build:reporter-ssr && npm run copy-types",
+    "build": "pnpm run clean && pnpm run compile && pnpm run build:reporter && pnpm run build:reporter-ssr && pnpm run copy-types",
     "clean": "rimraf dist",
     "compile": "babel src --out-dir dist --ignore '**/*.test.js'",
     "copy-types": "mkdir -p dist/types && cp src/types/*.d.ts dist/types/",
@@ -67,12 +70,12 @@
     "build:reporter-ssr": "cd src/reporter && vite build --config vite.ssr.config.js",
     "dev:reporter": "cd src/reporter && vite --config vite.dev.config.js",
     "test:types": "tsd",
-    "prepublishOnly": "npm run build",
+    "prepublishOnly": "pnpm run build",
     "test": "node --experimental-test-coverage --test --test-concurrency=1 --test-reporter=spec $(find tests -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 run \"npm run test:reporter\"",
-    "test:swift:e2e": "npm run build && node clients/swift/scripts/run-e2e.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:tui": "node --test --test-reporter=spec tests/tui/*.test.js",
     "test:tui:docker": "./tests/tui/run-tui-tests.sh",
     "smoke:prod:pack": "node scripts/smoke-prod-pack.js",
@@ -80,7 +83,7 @@
     "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",
-    "fix": "npm run format && npm run lint:fix"
+    "fix": "pnpm run format && pnpm run lint:fix"
   },
   "engines": {
     "node": ">=22.0.0"
@@ -90,6 +93,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
+    "@vizzly-testing/bear-den": "0.1.2",
     "@vizzly-testing/honeydiff": "^0.10.3",
     "ansis": "^4.2.0",
     "commander": "^14.0.0",
@@ -125,7 +129,6 @@
     "@tanstack/react-query": "^5.90.11",
     "@types/node": "^25.0.2",
     "@vitejs/plugin-react": "^6.0.1",
-    "@vizzly-testing/observatory": "^0.3.3",
     "autoprefixer": "^10.4.21",
     "babel-plugin-react-compiler": "^1.0.0",
     "babel-plugin-transform-remove-console": "^6.9.4",

package/skills/vizzly/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: vizzly
+description: "Use when a repo has Vizzly configured and you need screenshot memory or visual history: before/after UI changes, visual regression review, screenshot history, approved baselines, diffs, dynamic regions, docs/manual images, public screenshots, or Vizzly builds. Teaches agents to use Vizzly CLI/context for local TDD, cloud builds, review state, comments, hotspots, previews, and SDK capture patterns."
+---
+
+# Vizzly
+
+Vizzly is the project's screenshot memory database. It stores approved baselines, current screenshots, diffs, review state, comments, hotspots, previews, and public screenshot URLs.
+
+Use Vizzly when you need to understand what the UI looked like before, what changed, what humans already reviewed, or which screenshots already exist. Browser automation is still useful for interacting with a live app; Vizzly is usually the faster first stop for visual history.
+
+## First Instinct
+
+Before changing UI, check whether Vizzly already has local screenshot context:
+
+```bash
+vizzly context build current --source local --agent
+```
+
+If a task names a screen, component, or screenshot, inspect that screenshot's history before changing thresholds or re-capturing blindly:
+
+```bash
+vizzly context screenshot "<screenshot-name>" --source local --json
+```
+
+When you make or verify UI changes, run the focused user workflow that owns the surface:
+
+```bash
+vizzly tdd run "<test command>" --no-open
+```
+
+Then inspect what changed:
+
+```bash
+vizzly context build current --source local --agent --json
+```
+
+For specific evidence, drill in:
+
+```bash
+vizzly context comparison <comparison-id> --json
+vizzly context screenshot "<screenshot-name>" --json
+vizzly context review-queue --json
+```
+
+If local context is unavailable and the project uses cloud builds, use the build id from CI or CLI output:
+
+```bash
+vizzly context build <build-id> --agent --json --include diffs,comments
+```
+
+## What Vizzly Knows
+
+- **Approved baselines**: expected UI.
+- **Current screenshots**: what the latest run rendered.
+- **Diffs**: where pixels/layout/content changed.
+- **Review state and comments**: human context attached to builds and screenshots.
+- **Hotspots and confirmed regions**: known dynamic areas.
+- **Preview links**: static or deployed UI context for a build.
+- **Public screenshots**: stable URLs for documentation and manuals.
+
+## Acting On Visual Context
+
+- Treat approved baselines as visual truth.
+- Treat diffs as evidence, not as approval instructions.
+- Do not approve or reject visual changes unless the user explicitly asks.
+- Prefer existing E2E or user journeys over narrow screenshot-only specs.
+- For dynamic content, inspect screenshot context before changing thresholds.
+- Prefer deterministic test data, per-screenshot `threshold`, per-screenshot `minClusterSize`, hotspots, or confirmed regions over global tolerance changes.
+- Report visual findings with screenshot names, build/comparison links when available, and the command you ran.
+
+## Capturing Screenshots
+
+Use the existing integration when one is present. For direct JavaScript capture:
+
+```javascript
+import { vizzlyScreenshot } from '@vizzly-testing/cli/client';
+
+let screenshot = await page.screenshot();
+await vizzlyScreenshot('checkout-form', screenshot, {
+  properties: {
+    browser: 'chromium',
+    viewport: 'desktop',
+    state: 'valid-card'
+  },
+  threshold: 2,
+  minClusterSize: 4
+});
+```
+
+Use `properties` to separate variants such as theme, locale, viewport, role, state, component, page, or docs/manual grouping.
+
+## When You Need More Detail
+
+- For SDK examples and capture patterns, read `references/sdks.md`.
+- For CLI/context commands and JSON output, read `references/cli-context.md`.
+- For dynamic content, thresholds, and hotspots, read `references/dynamic-content.md`.
+- For public screenshot URLs and docs/manual images, read `references/public-screenshots.md`.
+- For project setup and CI, read `references/setup-ci.md`.

package/skills/vizzly/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Vizzly"
+  short_description: "Use Vizzly visual context while changing UI."
+  default_prompt: "Use Vizzly to inspect visual context before and after UI changes."

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

@@ -0,0 +1,42 @@
+# CLI And Context
+
+Use these commands to gather Vizzly evidence before making UI assumptions.
+
+## Local TDD
+
+```bash
+vizzly tdd start
+vizzly tdd run "<test command>" --no-open
+vizzly context build current --source local --agent
+vizzly context build current --source local --agent --json
+```
+
+Local context reads `.vizzly` state and does not require cloud auth.
+
+## Cloud Builds
+
+```bash
+export VIZZLY_TOKEN="project-token"
+vizzly run "<test command>" --wait --json
+vizzly context build <build-id> --agent --json --include diffs,comments
+```
+
+`vizzly run --wait --json` returns a `contextCommand` when a cloud build is created. Prefer that command over constructing URLs by hand.
+
+## Drilldowns
+
+```bash
+vizzly context comparison <comparison-id> --json
+vizzly context screenshot "<screenshot-name>" --json
+vizzly context similar <fingerprint-hash> --json
+vizzly context review-queue --json
+```
+
+Use comparison context for one diff. Use screenshot context for history and recurring dynamic areas. Use review queue context when triaging unresolved visual work.
+
+## Good Agent Behavior
+
+- Use `--json` for automation and summaries.
+- Use `--agent` when building prompt context or asking another agent to continue.
+- Keep human-readable command output in final summaries only when it changes the user's next action.
+- Do not approve/reject unless explicitly asked.

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

@@ -0,0 +1,44 @@
+# Dynamic Content
+
+Dynamic content is common: dates, calendars, generated images, avatars, timers, randomized data, responsive text, and API-backed content.
+
+## Order Of Operations
+
+1. Make test data deterministic when the changing content is not what you are testing.
+2. Inspect screenshot context before changing code:
+
+```bash
+vizzly context screenshot "<screenshot-name>" --json
+```
+
+3. Use per-screenshot tolerances for local noise:
+
+```javascript
+await vizzlyScreenshot('plant-calendar', screenshot, {
+  properties: { surface: 'calendar' },
+  threshold: 4,
+  minClusterSize: 12
+});
+```
+
+4. Use hotspots or confirmed regions for recurring valid dynamic regions.
+
+## Avoid
+
+- Raising global project thresholds for one dynamic area.
+- Masking a whole page when a small region changes.
+- Treating every daily diff as product breakage.
+- Ignoring structural changes because a region is known to be dynamic.
+
+## How To Explain Findings
+
+Say whether the diff looks like:
+
+- expected dynamic content
+- deterministic fixture drift
+- real content disappearance
+- layout shift
+- screenshot timing/capture instability
+- baseline mismatch
+
+Then name the screenshot and include the relevant context command or link.

package/skills/vizzly/references/public-screenshots.md

@@ -0,0 +1,44 @@
+# Public Screenshots
+
+Public screenshots are Vizzly's path for stable image URLs in docs and manuals.
+
+Use this when a user asks for hotlinked UI screenshots, generated manual images, docs that stay current with UI, or CDN-like screenshot URLs.
+
+## Mental Model
+
+Do not use arbitrary build screenshot URLs as stable docs assets. Use Public Properties.
+
+The flow:
+
+1. Capture screenshots with stable metadata.
+2. Configure project Public Properties in Vizzly.
+3. Approve/publish the baseline build.
+4. Use the Public URLs tab to copy the stable URL.
+
+Example capture:
+
+```javascript
+await vizzlyScreenshot('watering-widget', screenshot, {
+  properties: {
+    manual: 'plant-care',
+    component: 'watering-widget',
+    viewport: 'desktop'
+  }
+});
+```
+
+Configure a Public Property like `manual=plant-care`. Vizzly publishes matching approved baseline screenshots and keeps stable URLs for each screenshot/property identity.
+
+## Good Uses
+
+- Product manuals
+- User docs
+- Component catalogs
+- In-app UI examples
+- Screenshots that should update when approved UI changes
+
+## Cautions
+
+- Public screenshots are public. Do not publish private user data, secrets, or internal-only UI.
+- A new unapproved build does not automatically become the public docs image.
+- Use stable names and properties so URLs do not churn.