🐛 Fix CLI regressions across JSON, help, and TDD (#296)

## Why

The CLI had several rough edges at the boundaries users rely on most:
command errors could show misleading help, JSON mode could mix
machine-readable output with human text, TDD lifecycle commands were not
careful enough around explicit ports, and some commands hid local
validation failures behind auth or optional API state.

That makes the CLI feel unreliable in automation and confusing in local
workflows. This PR tightens those paths so exposed commands fail
clearly, preserve their output contracts, and avoid touching unrelated
local processes or config state.

It also removes the old global TDD `server.json` compatibility path.
Local TDD discovery is now project-local or explicit, which matches the
current daemon registry model and avoids carrying forward a second
server-discovery contract.

## What Changed

- Fixed command routing and help behavior so unknown root and nested
commands fail with the right recovery hints.
- Cleaned up root/TDD help output, including full nested command paths,
documented lifecycle `--port` flags, and hidden internal daemon-only
flags.
- Preserved JSON-mode contracts for validation errors, commander errors,
TDD commands, noisy child processes, `run --json --wait`, `upload --wait
--json`, review actions, and `status --json`.
- Made TDD daemon `start`, `status`, `stop`, and `list` safer around
explicit ports, isolated `VIZZLY_HOME`, stale files, registry entries,
and wrong-port no-ops.
- Removed the legacy global TDD `server.json` write/cleanup path so
daemon state is no longer mirrored into the user home directory.
- Validated preview/upload local paths before requiring auth so local
mistakes are reported immediately.
- Made `status` tolerate builds without preview metadata by returning
`preview: null` instead of failing.
- Updated in-repo docs, Swift SDK docs, Vizzly skill references, and the
JSON output reference so the documented workflows match the CLI
behavior.
- Added CLI-boundary regression tests that run the real command
entrypoint against local workspaces and local HTTP API servers.

## Impact

This should make the CLI more predictable for both local use and
automation. JSON stdout stays parseable, help/error output points users
to the right command, TDD lifecycle commands avoid unrelated processes,
local validation errors are surfaced before network/auth concerns, and
SDK server discovery no longer depends on a stale global file.

Author: Robdel12

AGENTS.md

@@ -37,8 +37,9 @@ Keep subjects concise; include issue/PR refs when relevant (example: `(#217)`).
 PRs should include:
 - Why the change is needed.
 - A clear summary of all meaningful diff areas.
-- A test plan with exact commands run.
+- A concise confidence/verification summary without listing commands run.
 - Screenshots or terminal output for UI/reporting changes when helpful.
+- Do not mention private or sibling repo work in public repo PRs.
 
 ## Security & Configuration Tips
 Use Node.js `>=22`. Keep secrets (for example `VIZZLY_TOKEN`) out of git.  

README.md

@@ -40,17 +40,31 @@ Use `vizzly init --agent-skill` to install only the local skill, or
 
 ### Start Local TDD
 
-Start the TDD server, run your tests, and open the dashboard at
-`http://localhost:47392`.
+Start the TDD server, run your tests, and open the dashboard at the URL the
+command prints. Add `--open` when you want Vizzly to open the dashboard for
+you. If the default port is busy, Vizzly picks the next available port; use the
+printed `--port` value with `vizzly tdd status` or `vizzly tdd stop`.
 
 ```bash
-vizzly tdd start
+vizzly tdd start --open
 pnpm test -- --watch
 ```
 
 The dashboard shows screenshots, baselines, and diffs as they arrive. Accept or
 reject changes right from the UI.
 
+For a one-off local check, wrap the test command with `tdd run`:
+
+```bash
+vizzly tdd run "pnpm test" --no-open
+vizzly context build current --source local --agent
+```
+
+That run writes review data under `.vizzly/` and prints a context command you
+can use for follow-up inspection. If screenshots were captured, Vizzly also
+generates `.vizzly/report/index.html`; omit `--no-open` when you want that
+report opened automatically.
+
 ### Run With Cloud Review
 
 Use cloud builds when you want shared baselines, team review, and CI status:
@@ -206,10 +220,18 @@ export default {
 | Command | What it does |
 | --- | --- |
 | `vizzly tdd start` | Start the local TDD server and dashboard. |
-| `vizzly tdd run "cmd"` | Run tests once and generate a static visual report. |
+| `vizzly tdd status` | Check the local TDD server for this project. |
+| `vizzly tdd list` | List running local TDD servers. |
+| `vizzly tdd stop` | Stop the local TDD server for this project. |
+| `vizzly tdd run "cmd"` | Run tests once and write local review data under `.vizzly/`. |
 | `vizzly run "cmd"` | Run tests with cloud build and review integration. |
 | `vizzly context ...` | Fetch visual context for builds, comparisons, screenshots, and review queues. |
 | `vizzly upload <dir>` | Upload an existing folder of screenshots. |
+| `vizzly preview <dir>` | Upload static build output for in-context review. |
+| `vizzly approve <comparison-id>` | Approve a visual comparison. |
+| `vizzly reject <comparison-id>` | Reject a visual comparison with a reason. |
+| `vizzly comment <build-id>` | Add a build comment. |
+| `vizzly config [key]` | Inspect resolved configuration values. |
 | `vizzly login` | Authenticate through the browser. |
 | `vizzly doctor` | Validate your local setup. |
 

clients/ember/README.md

@@ -5,12 +5,15 @@ Visual testing SDK for Ember.js projects using Testem. Capture screenshots from
 ## Installation
 
 ```bash
-pnpm install -D @vizzly-testing/ember
+pnpm install -D @vizzly-testing/cli @vizzly-testing/ember
 
-# Install a Playwright browser
+# Install the Playwright browser you plan to test with
 pnpm exec playwright install chromium
 ```
 
+Chromium, Firefox, and WebKit are supported. Install additional browsers with
+`pnpm exec playwright install firefox` or `pnpm exec playwright install webkit`.
+
 ## Setup
 
 ### 1. Configure Testem
@@ -31,7 +34,9 @@ module.exports = configure({
 });
 ```
 
-The `configure()` function replaces standard browser launchers (Chrome, Firefox, Safari) with Playwright-powered launchers that can capture screenshots. Browsers run in **headless mode by default**.
+The `configure()` function maps standard Testem launchers (Chrome, Firefox,
+Safari) to Playwright-powered Chromium, Firefox, and WebKit launchers that can
+capture screenshots. Browsers run in **headless mode by default**.
 
 > **Note for Ember + Vite projects**: The `cwd: 'dist'` option is required because Vite builds test files into the `dist/` directory. Without this, Testem won't find your test assets.
 

clients/ember/package.json

@@ -51,7 +51,7 @@
     "test:all": "node --test --test-reporter=spec 'tests/**/*.test.js'",
     "test:watch": "node --test --test-reporter=spec --watch 'tests/**/*.test.js'",
     "test:ember": "cd test-app && pnpm install --frozen-lockfile && pnpm run build --mode development && pnpm exec testem ci --file testem.cjs",
-    "test:ember:tdd": "../../bin/vizzly.js tdd run 'pnpm run test:ember'",
+    "test:ember:tdd": "../../bin/vizzly.js tdd run 'pnpm run test:ember' --no-open",
     "test:ember:cloud": "../../bin/vizzly.js run 'pnpm run test:ember'",
     "lint": "biome lint src tests bin",
     "lint:fix": "biome lint --write src tests bin",

clients/static-site/README.md

@@ -5,7 +5,7 @@ Seamlessly integrate your static sites (Gatsby, Astro, Jekyll, Next.js static ex
 ## Installation
 
 ```bash
-pnpm install @vizzly-testing/static-site
+pnpm install -D @vizzly-testing/cli @vizzly-testing/static-site
 ```
 
 The plugin is automatically discovered by the Vizzly CLI via the `@vizzly-testing/*` scope.
@@ -29,6 +29,9 @@ vizzly static-site ./dist \
 
 # With concurrency control
 vizzly static-site ./dist --concurrency 5
+
+# With comma-separated browser args
+vizzly static-site ./dist --browser-args "--no-sandbox,--disable-dev-shm-usage"
 ```
 
 ### Programmatic Usage
@@ -151,7 +154,7 @@ Configuration is merged in this order (later overrides earlier):
 - `--browser <type>` - Browser engine to use: `chromium`, `firefox`, or `webkit`
 - `--include <pattern>` - Include page pattern (glob)
 - `--exclude <pattern>` - Exclude page pattern (glob)
-- `--browser-args <args>` - Additional Playwright browser arguments
+- `--browser-args <args>` - Comma-separated Playwright browser arguments
 - `--headless` - Run browser in headless mode (default: true)
 - `--no-headless` - Run browser with a visible window
 - `--full-page` - Capture full page screenshots (default: true)

clients/storybook/README.md

@@ -7,7 +7,7 @@ changes with position-based comments and review rules.
 ## Installation
 
 ```bash
-pnpm install @vizzly-testing/storybook
+pnpm install -D @vizzly-testing/cli @vizzly-testing/storybook
 ```
 
 The plugin is automatically discovered by the Vizzly CLI via the `@vizzly-testing/*` scope.
@@ -43,6 +43,9 @@ vizzly storybook ./storybook-static \
 
 # With concurrency control
 vizzly storybook ./storybook-static --concurrency 5
+
+# With comma-separated browser args
+vizzly storybook ./storybook-static --browser-args "--no-sandbox,--disable-dev-shm-usage"
 ```
 
 ### Programmatic Usage
@@ -166,7 +169,7 @@ Configuration is merged in this order (later overrides earlier):
 - `--include <pattern>` - Include story pattern (glob)
 - `--exclude <pattern>` - Exclude story pattern (glob)
 - `--config <path>` - Path to custom config file
-- `--browser-args <args>` - Additional Playwright browser arguments
+- `--browser-args <args>` - Comma-separated Playwright browser arguments
 - `--headless` - Run browser in headless mode (default: true)
 - `--no-headless` - Run browser with a visible window
 - `--full-page` - Capture full page screenshots (default: true)

clients/swift/INTEGRATION.md

@@ -51,28 +51,43 @@ cd /path/to/MyiOSApp
 Create a `vizzly.config.js` file (optional but recommended):
 
 ```javascript
-export default {
-  // Delta E comparison threshold. Omitted screenshots use server config.
-  threshold: 0,
-
-  // TDD server port
-  port: 47392,
-
-  // Baseline directory
-  baselineDir: '.vizzly/baselines'
-}
+import { defineConfig } from '@vizzly-testing/cli/config';
+
+export default defineConfig({
+  server: {
+    port: 47392,
+  },
+  comparison: {
+    // Delta E comparison threshold. Omitted screenshots use server config.
+    threshold: 0,
+  },
+});
 ```
 
 ### 4. Start TDD Server
 
 ```bash
-vizzly tdd start
+vizzly tdd start --open
 ```
 
-This starts a local server at `http://localhost:47392` that will:
+This starts a local server that will:
 - Receive screenshots from your tests
 - Compare them against baselines
-- Serve a dashboard at `http://localhost:47392/dashboard`
+- Serve a dashboard at the URL printed by the command
+
+Vizzly uses port `47392` by default. If that port is busy, it auto-assigns
+another free port and prints that URL instead.
+
+For a one-off run, wrap your test command:
+
+```bash
+vizzly tdd run \
+  "xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15'" \
+  --no-open
+```
+
+That writes local review data under `.vizzly/` and creates a static report at
+`.vizzly/report/index.html` when screenshots are captured.
 
 ### 5. Write UI Tests with Vizzly
 
@@ -443,9 +458,11 @@ vizzly tdd start
 **Solution**:
 
 1. Ensure TDD server is running: `vizzly tdd start`
-2. Check `~/.vizzly/server.json` exists in your home directory
-3. Verify the server is reachable: `curl http://localhost:47392/health`
-4. Or explicitly set: `export VIZZLY_SERVER_URL=http://localhost:47392`
+2. Check `.vizzly/server.json` exists in your project checkout
+3. Verify the printed server URL is reachable, for example:
+   `curl http://localhost:47392/health`
+4. Or explicitly set the printed URL:
+   `export VIZZLY_SERVER_URL=http://localhost:47392`
 
 ## Best Practices
 

clients/swift/QUICKSTART.md

@@ -20,9 +20,12 @@ pnpm install -g @vizzly-testing/cli
 In your iOS project directory:
 
 ```bash
-vizzly tdd start
+vizzly tdd start --open
 ```
 
+Vizzly uses port `47392` by default. If that port is busy, it prints the
+dashboard URL with the auto-assigned port.
+
 ## 4. Write a Visual Test
 
 ```swift
@@ -58,14 +61,25 @@ xcodebuild test \
 
 ## 6. Review Results
 
-Open dashboard: **http://localhost:47392/dashboard**
+Open the dashboard URL printed by `vizzly tdd start`.
 
 - ✅ Green = Screenshots match baselines
 - ⚠️ Yellow = Visual differences detected
 - 🆕 Blue = New screenshots (first run)
 
 Click any screenshot to see side-by-side comparison and approve/reject changes.
 
+For a one-off local check, wrap the test command instead:
+
+```bash
+vizzly tdd run \
+  "xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15'" \
+  --no-open
+```
+
+That writes review data under `.vizzly/` and creates `.vizzly/report/index.html`
+when screenshots are captured.
+
 ## Next Steps
 
 - **More Examples**: See [Example/ExampleUITests.swift](Example/ExampleUITests.swift)

clients/swift/README.md

@@ -52,10 +52,12 @@ for native app integration.
 
 ```bash
 cd /path/to/your/ios/project
-vizzly tdd start
+vizzly tdd start --open
 ```
 
-This starts a local server at `http://localhost:47392` that receives screenshots and performs visual comparisons.
+This starts a local server that receives screenshots and performs visual
+comparisons. Vizzly uses `http://localhost:47392` by default; if that port is
+busy, use the URL printed by the command.
 
 ### 2. Add Vizzly to Your UI Tests
 
@@ -86,7 +88,20 @@ xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 1
 
 ### 4. View Results
 
-Open the dashboard at **http://localhost:47392/dashboard** to see visual comparisons, accept/reject changes, and review differences.
+Open the dashboard URL printed by `vizzly tdd start` to see visual comparisons,
+accept/reject changes, and review differences.
+
+For a one-off local run, wrap your `xcodebuild` command:
+
+```bash
+vizzly tdd run \
+  "xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15'" \
+  --no-open
+```
+
+That writes local review data under `.vizzly/`. If screenshots were captured,
+Vizzly also creates `.vizzly/report/index.html`; omit `--no-open` when you want
+the report opened automatically.
 
 ## Usage Examples
 
@@ -288,10 +303,11 @@ The SDK automatically discovers a running Vizzly TDD server using this priority
 
 1. **VIZZLY_SERVER_URL environment variable** - Explicitly set server URL
 2. **Project server file** - `.vizzly/server.json` in the current directory
-3. **Global server file** - `~/.vizzly/server.json` written by CLI
-4. **Default port health check** - Tests `http://localhost:47392/health`
+3. **Default port health check** - Tests `http://localhost:47392/health`
 
-When you run `vizzly tdd start`, the CLI automatically writes server info to `~/.vizzly/server.json` in your home directory, enabling zero-config discovery from iOS tests.
+When you run `vizzly tdd start`, the CLI writes server info to
+`.vizzly/server.json` in your project. Run UI tests from the project checkout,
+or set `VIZZLY_SERVER_URL` explicitly when your test process starts elsewhere.
 
 ### Environment Variables
 
@@ -464,9 +480,11 @@ override func setUpWithError() throws {
 ### Server Not Found
 
 1. Ensure TDD server is running: `vizzly tdd start`
-2. Check `~/.vizzly/server.json` exists in your home directory
-3. Verify the server is reachable: `curl http://localhost:47392/health`
-4. Or explicitly set: `export VIZZLY_SERVER_URL=http://localhost:47392`
+2. Check `.vizzly/server.json` exists in your project checkout
+3. Verify the printed server URL is reachable, for example:
+   `curl http://localhost:47392/health`
+4. Or explicitly set the printed URL:
+   `export VIZZLY_SERVER_URL=http://localhost:47392`
 
 ### Visual Differences Not Showing
 

clients/vitest/package.json

@@ -41,7 +41,7 @@
     "test": "pnpm run test:unit",
     "test:unit": "vitest run --config vitest.config.js",
     "test:e2e": "vitest run --config vitest.e2e.config.js",
-    "test:e2e:tdd": "../../bin/vizzly.js tdd run 'pnpm run test:e2e'",
+    "test:e2e:tdd": "../../bin/vizzly.js tdd run 'pnpm run test:e2e' --no-open",
     "test:e2e:cloud": "../../bin/vizzly.js run 'pnpm run test:e2e'",
     "lint": "biome lint src tests",
     "lint:fix": "biome lint --write src tests",