Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

fix(demos): add OCR validation for TUI demos, fix permission dialog (#897)

Maximilian Roosc153164ba7f1
diff --git a/docs/demos/CLAUDE.md b/docs/demos/CLAUDE.md
index 606903bbc..aec4f49dc 100644
--- a/docs/demos/CLAUDE.md
+++ b/docs/demos/CLAUDE.md
@@ -66,9 +66,27 @@ Snapshots capture command output (not terminal rendering) and are committed to `
- Output format changes you didn't intend
- New lines or missing output
+**TUI demo validation:**
+
+TUI demos (Zellij, Claude UI) can't use text snapshots because VHS only captures the outer terminal, not content inside terminal multiplexers. Instead, they use OCR-based validation:
+
+1. After recording, specific frames are extracted from the GIF using ffmpeg
+2. Tesseract OCR extracts text from those frames
+3. The text is validated for expected/forbidden patterns
+4. Validation runs automatically when building TUI demos with defined checkpoints
+
+Checkpoints are defined in `docs/demos/shared/validation.py`. To add validation to a TUI demo:
+1. Identify key frame numbers by examining the GIF (30fps, so frame 90 = 3 seconds)
+2. Define checkpoint patterns in `validation.py` with frame numbers, expected patterns, and forbidden patterns
+
+Currently `wt-zellij-omnibus` has checkpoints; other TUI demos are skipped until checkpoints are added.
+
+**Prerequisites for TUI validation:** `ffmpeg` and `tesseract` must be installed.
+
**Limitations:**
- Tab completion sequences are not replayed; only `Type "command"` + `Enter` patterns are extracted
-- TUI demos (wt-select, wt-switch, wt-statusline, wt-zellij-omnibus) are skipped since they require interactive input
+- TUI demos without defined checkpoints are skipped
+- OCR accuracy depends on font rendering quality
## Prerequisites
diff --git a/docs/demos/build b/docs/demos/build
index 9fbc7e26c..0417e0f52 100755
--- a/docs/demos/build
+++ b/docs/demos/build
@@ -47,6 +47,10 @@ from shared import ( # noqa: E402
build_tape_replacements,
ensure_vhs_binary,
)
+from shared.validation import ( # noqa: E402
+ TUI_CHECKPOINTS,
+ validate_tui_demo_verbose,
+)
REPO_ROOT = SCRIPT_DIR.parent.parent
OUT_DIR = SCRIPT_DIR.parent / "static" / "assets"
@@ -385,7 +389,23 @@ def record_demo(
vhs_binary=vhs_binary,
size=demo_size,
)
- print(f"✓ {output_name}: GIFs saved: {', '.join(themes)}")
+
+ # Validate TUI demos with OCR after recording
+ if output_name in TUI_CHECKPOINTS:
+ # Use the light theme GIF for validation
+ gif_path = output_gifs.get("light", list(output_gifs.values())[0])
+ success, output = validate_tui_demo_verbose(output_name, gif_path)
+ if success:
+ print(f"✓ {output_name}: GIFs saved + validation passed")
+ else:
+ print(f"✓ {output_name}: GIFs saved")
+ print(f"✗ {output_name}: Validation failed")
+ for line in output.split("\n"):
+ if line.startswith(" "):
+ print(line)
+ raise RuntimeError(f"TUI validation failed for {output_name}")
+ else:
+ print(f"✓ {output_name}: GIFs saved: {', '.join(themes)}")
# =============================================================================
@@ -498,13 +518,13 @@ Examples:
print(f"Available for {args.target}: {', '.join(all_names)}")
return
- # Filter out TUI demos in snapshot mode
+ # In snapshot mode, skip TUI demos (they validate via checkpoints during GIF recording)
if args.snapshot:
original_count = len(demos)
demos = [(t, n, s) for t, n, s in demos if n not in TUI_DEMOS]
skipped = original_count - len(demos)
if skipped:
- print(f"Skipping {skipped} TUI demo(s) (not snapshotable)")
+ print(f"Skipping {skipped} TUI demo(s) (validate during GIF recording instead)")
if not demos:
print("No snapshotable demos found")
return
diff --git a/docs/demos/shared/lib.py b/docs/demos/shared/lib.py
index ce867685d..41476e86d 100644
--- a/docs/demos/shared/lib.py
+++ b/docs/demos/shared/lib.py
@@ -504,6 +504,22 @@ def setup_zellij_config(env: DemoEnv, default_cwd: str = None) -> None:
default_cwd_line = f'default_cwd "{default_cwd}"' if default_cwd else ""
+ # Pre-populate Zellij permissions cache to avoid permission dialog
+ # On macOS, cache is at $HOME/Library/Caches/org.Zellij-Contributors.Zellij/
+ # On Linux, it would be at $HOME/.cache/zellij/
+ plugin_dest = zellij_plugins_dir / "zellij-tab-name.wasm"
+ if platform.system() == "Darwin":
+ zellij_cache_dir = env.home / "Library" / "Caches" / "org.Zellij-Contributors.Zellij"
+ else:
+ zellij_cache_dir = env.home / ".cache" / "zellij"
+ zellij_cache_dir.mkdir(parents=True, exist_ok=True)
+ permissions_file = zellij_cache_dir / "permissions.kdl"
+ permissions_file.write_text(f'''"{plugin_dest}" {{
+ ReadApplicationState
+ ChangeApplicationState
+}}
+''')
+
zellij_config = zellij_config_dir / "config.kdl"
zellij_config.write_text(f"""// Demo Zellij config
default_shell "fish"
@@ -513,6 +529,11 @@ show_startup_tips false
show_release_notes false
theme "warm-gold"
+// Load the tab-name plugin
+load_plugins {{
+ "file:{zellij_plugins_dir}/zellij-tab-name.wasm"
+}}
+
// Warm gold theme to match the demo aesthetic
themes {{
warm-gold {{
@@ -530,10 +551,6 @@ themes {{
}}
}}
-load_plugins {{
- "file:{zellij_plugins_dir}/zellij-tab-name.wasm"
-}}
-
keybinds clear-defaults=true {{
normal {{
bind "Ctrl Space" {{ SwitchToMode "tmux"; }}
diff --git a/docs/demos/shared/validation.py b/docs/demos/shared/validation.py
new file mode 100644
index 000000000..394a4e857
--- /dev/null
+++ b/docs/demos/shared/validation.py
@@ -0,0 +1,204 @@
+"""OCR-based validation for TUI demos.
+
+TUI demos (Zellij, interactive UIs) can't be validated via text output because
+VHS only captures the outer terminal, not content rendered inside terminal
+multiplexers. Instead, we extract key frames from the GIF and use OCR to verify
+expected content appears.
+
+Usage:
+ from shared.validation import validate_tui_demo, TUI_CHECKPOINTS
+
+ # Validate after building
+ errors = validate_tui_demo("wt-zellij-omnibus", gif_path)
+ if errors:
+ print("Validation failed:", errors)
+"""
+
+from __future__ import annotations
+
+import subprocess
+import tempfile
+from pathlib import Path
+
+# Checkpoint definitions per TUI demo
+# Format: {demo_name: [(frame_number, expected_patterns, forbidden_patterns), ...]}
+#
+# Frame numbers are calibrated from actual GIF content at 30fps.
+# Expected patterns must ALL be present (case-insensitive).
+# Forbidden patterns must ALL be absent (case-insensitive).
+
+TUI_CHECKPOINTS: dict[str, list[tuple[int, list[str], list[str]]]] = {
+ # Frame numbers calibrated with permissions cache fix (no permission dialog).
+ # At 30fps: frame 100 = ~3.3s, frame 500 = ~16.7s, frame 2000 = ~66.7s
+ "wt-zellij-omnibus": [
+ # Frame 100: After wt list - should see branch table, no permission dialog
+ (100, ["Branch", "Status", "main", "hooks"], ["Allow?", "permission"]),
+ # Frame 500: Claude UI visible - shows Opus model indicator and worktree
+ (500, ["Opus", "acme"], ["command not found", "Unknown command"]),
+ # Frame 2000: Near end - wt list --full showing all worktrees
+ (2000, ["Branch", "main", "feature", "billing"], ["CONFLICT", "error:", "failed"]),
+ ],
+}
+
+
+def check_dependencies() -> list[str]:
+ """Check that required tools are available. Returns list of missing tools."""
+ missing = []
+ for cmd in ["ffmpeg", "tesseract"]:
+ result = subprocess.run(
+ ["which", cmd], capture_output=True, text=True
+ )
+ if result.returncode != 0:
+ missing.append(cmd)
+ return missing
+
+
+def extract_frame(gif_path: Path, frame_number: int, output_path: Path) -> bool:
+ """Extract a single frame from a GIF. Returns True on success."""
+ result = subprocess.run(
+ [
+ "ffmpeg",
+ "-loglevel", "error",
+ "-i", str(gif_path),
+ "-vf", f"select=eq(n\\,{frame_number})",
+ "-vframes", "1",
+ "-update", "1",
+ str(output_path),
+ ],
+ capture_output=True,
+ )
+ return result.returncode == 0 and output_path.exists()
+
+
+def ocr_image(image_path: Path) -> str:
+ """Run OCR on an image and return the extracted text."""
+ with tempfile.NamedTemporaryFile(suffix=".txt", delete=False) as f:
+ output_base = f.name[:-4] # Remove .txt suffix for tesseract
+
+ result = subprocess.run(
+ ["tesseract", str(image_path), output_base, "-l", "eng"],
+ capture_output=True,
+ )
+
+ output_path = Path(f"{output_base}.txt")
+ if result.returncode == 0 and output_path.exists():
+ text = output_path.read_text()
+ output_path.unlink()
+ return text
+ return ""
+
+
+def validate_checkpoint(
+ gif_path: Path,
+ frame_number: int,
+ expected: list[str],
+ forbidden: list[str],
+ work_dir: Path,
+) -> list[str]:
+ """Validate a single checkpoint. Returns list of error messages."""
+ errors = []
+
+ # Extract frame
+ frame_path = work_dir / f"frame_{frame_number}.png"
+ if not extract_frame(gif_path, frame_number, frame_path):
+ return [f"Failed to extract frame {frame_number}"]
+
+ # OCR the frame
+ text = ocr_image(frame_path)
+ if not text:
+ return [f"OCR failed for frame {frame_number}"]
+
+ text_lower = text.lower()
+
+ # Check expected patterns
+ for pattern in expected:
+ if pattern.lower() not in text_lower:
+ errors.append(f"Expected pattern not found: '{pattern}'")
+
+ # Check forbidden patterns
+ for pattern in forbidden:
+ if pattern.lower() in text_lower:
+ errors.append(f"Forbidden pattern found: '{pattern}'")
+
+ return errors
+
+
+def validate_tui_demo(demo_name: str, gif_path: Path) -> list[str]:
+ """Validate a TUI demo GIF against its checkpoints.
+
+ Args:
+ demo_name: Name of the demo (e.g., "wt-zellij-omnibus")
+ gif_path: Path to the GIF file to validate
+
+ Returns:
+ List of error messages. Empty list means validation passed.
+ """
+ if demo_name not in TUI_CHECKPOINTS:
+ return [f"No checkpoints defined for demo: {demo_name}"]
+
+ if not gif_path.exists():
+ return [f"GIF not found: {gif_path}"]
+
+ # Check dependencies
+ missing = check_dependencies()
+ if missing:
+ return [f"Missing required tools: {', '.join(missing)}"]
+
+ checkpoints = TUI_CHECKPOINTS[demo_name]
+ all_errors = []
+
+ with tempfile.TemporaryDirectory(prefix="wt-validate-") as work_dir:
+ work_path = Path(work_dir)
+
+ for frame_number, expected, forbidden in checkpoints:
+ errors = validate_checkpoint(
+ gif_path, frame_number, expected, forbidden, work_path
+ )
+ if errors:
+ all_errors.append(f"Frame {frame_number}: {'; '.join(errors)}")
+
+ return all_errors
+
+
+def validate_tui_demo_verbose(demo_name: str, gif_path: Path) -> tuple[bool, str]:
+ """Validate a TUI demo with verbose output.
+
+ Returns:
+ (success, output_message)
+ """
+ lines = [f"Validating {demo_name}: {gif_path}"]
+
+ if demo_name not in TUI_CHECKPOINTS:
+ return False, f"No checkpoints defined for demo: {demo_name}"
+
+ if not gif_path.exists():
+ return False, f"GIF not found: {gif_path}"
+
+ missing = check_dependencies()
+ if missing:
+ return False, f"Missing required tools: {', '.join(missing)}"
+
+ checkpoints = TUI_CHECKPOINTS[demo_name]
+ all_passed = True
+
+ with tempfile.TemporaryDirectory(prefix="wt-validate-") as work_dir:
+ work_path = Path(work_dir)
+
+ for frame_number, expected, forbidden in checkpoints:
+ errors = validate_checkpoint(
+ gif_path, frame_number, expected, forbidden, work_path
+ )
+ if errors:
+ lines.append(f" ✗ Frame {frame_number}")
+ for error in errors:
+ lines.append(f" - {error}")
+ all_passed = False
+ else:
+ lines.append(f" ✓ Frame {frame_number}")
+
+ if all_passed:
+ lines.append("✓ All checkpoints passed")
+ else:
+ lines.append("✗ Some checkpoints failed")
+
+ return all_passed, "\n".join(lines)
diff --git a/docs/demos/snapshots/wt-commit.snap b/docs/demos/snapshots/wt-commit.snap
index de6c46f2c..57163a6be 100644
--- a/docs/demos/snapshots/wt-commit.snap
+++ b/docs/demos/snapshots/wt-commit.snap
@@ -12,12 +12,12 @@ $ wt step commit
Add validation module with is_positive and is_non_empty helpers
for validating user input. Includes comprehensive test coverage.
-✓ Committed changes @ 200f6f2
+✓ Committed changes @ 08d6aa2

$ git log -1
-commit 200f6f2d9731f93626892c1a410f942217189339
+commit 08d6aa281ae15980b1dc485df79834735f9afaeb
Author: Worktrunk Demo <[email protected]>
-Date: Mon Jan 26 13:27:07 2026 -0800
+Date: Tue Jan 27 19:36:26 2026 -0800
feat(validation): add input validation utilities
diff --git a/docs/demos/snapshots/wt-core.snap b/docs/demos/snapshots/wt-core.snap
index bf5006924..0c4dda4af 100644
--- a/docs/demos/snapshots/wt-core.snap
+++ b/docs/demos/snapshots/wt-core.snap
@@ -1,10 +1,10 @@
$ wt list
Branch Status HEAD± main↕ Remote⇅ Commit Age Message
-@ main ^| | 9b344c49 1d docs: add developm…
-+ hooks +! ↑ +2 ↑1 0967fab5 2h feat: add math ope…
-+ billing _| | 9b344c49 1d docs: add developm…
-+ alpha !? ↑⇡ +105 -14 ↑5 ⇡1 f31634d7 3d docs: add FAQ sect…
-+ beta + ↓| +2 ↓1 | b10e3edd 5d Add project hooks
+@ main ^| | 8dbd1794 1d docs: add developm…
++ hooks +! ↑ +2 ↑1 27ef5da7 2h feat: add math ope…
++ billing _| | 8dbd1794 1d docs: add developm…
++ alpha !? ↑⇡ +105 -14 ↑5 ⇡1 c53676dd 3d docs: add FAQ sect…
++ beta + ↓| +2 ↓1 | 6ed05ea1 5d Add project hooks
○ Showing 5 worktrees, 3 with changes, 2 ahead, 1 column hidden

@@ -17,12 +17,12 @@ $ wt switch --create api

$ wt list --full
Branch Status HEAD± main↕ main…± Remote⇅ CI Commit Age
-@ api _ 9b344c49 1d
-^ main ^| | 9b344c49 1d
-+ hooks +! ↑ +2 ↑1 +12 -7 0967fab5 2h
-+ billing _| | 9b344c49 1d
-+ alpha !? ↑⇡ +105 -14 ↑5 +264 -3 ⇡1 f31634d7 3d
-+ beta + ↓| +2 ↓1 | b10e3edd 5d
+@ api _ 8dbd1794 1d
+^ main ^| | 8dbd1794 1d
++ hooks +! ↑ +2 ↑1 +12 -7 27ef5da7 2h
++ billing _| | 8dbd1794 1d
++ alpha !? ↑⇡ +105 -14 ↑5 +264 -3 ⇡1 c53676dd 3d
++ beta + ↓| +2 ↓1 | 6ed05ea1 5d
○ Showing 6 worktrees, 3 with changes, 2 ahead, 2 columns hidden

diff --git a/docs/demos/snapshots/wt-list.snap b/docs/demos/snapshots/wt-list.snap
index e35834b30..4a787f4e0 100644
--- a/docs/demos/snapshots/wt-list.snap
+++ b/docs/demos/snapshots/wt-list.snap
@@ -1,32 +1,32 @@
$ wt list
Branch Status HEAD± main↕ Remote⇅ Commit Age Message
-@ main ^| | 9b344c49 1d docs: add developm…
-+ hooks +! ↑ +2 ↑1 0967fab5 2h feat: add math ope…
-+ billing _| | 9b344c49 1d docs: add developm…
-+ alpha !? ↑⇡ +105 -14 ↑5 ⇡1 f31634d7 3d docs: add FAQ sect…
-+ beta + ↓| +2 ↓1 | b10e3edd 5d Add project hooks
+@ main ^| | 8dbd1794 1d docs: add developm…
++ hooks +! ↑ +2 ↑1 27ef5da7 2h feat: add math ope…
++ billing _| | 8dbd1794 1d docs: add developm…
++ alpha !? ↑⇡ +105 -14 ↑5 ⇡1 c53676dd 3d docs: add FAQ sect…
++ beta + ↓| +2 ↓1 | 6ed05ea1 5d Add project hooks
○ Showing 5 worktrees, 3 with changes, 2 ahead, 1 column hidden

$ wt list --full
Branch Status HEAD± main↕ main…± Remote⇅ CI Commit Age
-@ main ^| | 9b344c49 1d
-+ hooks +! ↑ +2 ↑1 +12 -7 0967fab5 2h
-+ billing _| | 9b344c49 1d
-+ alpha !? ↑⇡ +105 -14 ↑5 +264 -3 ⇡1 f31634d7 3d
-+ beta + ↓| +2 ↓1 | b10e3edd 5d
+@ main ^| | 8dbd1794 1d
++ hooks +! ↑ +2 ↑1 +12 -7 27ef5da7 2h
++ billing _| | 8dbd1794 1d
++ alpha !? ↑⇡ +105 -14 ↑5 +264 -3 ⇡1 c53676dd 3d
++ beta + ↓| +2 ↓1 | 6ed05ea1 5d
○ Showing 5 worktrees, 3 with changes, 2 ahead, 2 columns hidden

$ wt list --branches
Branch Status HEAD± main↕ Remote⇅ Commit Age Message
-@ main ^| | 9b344c49 1d docs: add dev…
-+ hooks +! ↑ +2 ↑1 0967fab5 2h feat: add mat…
-+ billing _| | 9b344c49 1d docs: add dev…
-+ alpha !? ↑⇡ +105 -14 ↑5 ⇡1 f31634d7 3d docs: add FAQ…
-+ beta + ↓| +2 ↓1 | b10e3edd 5d Add project h…
- docs/readme /⊂ ↓1 b10e3edd 5d Add project h…
- spike/search /⊂ ↓1 b10e3edd 5d Add project h…
+@ main ^| | 8dbd1794 1d docs: add dev…
++ hooks +! ↑ +2 ↑1 27ef5da7 2h feat: add mat…
++ billing _| | 8dbd1794 1d docs: add dev…
++ alpha !? ↑⇡ +105 -14 ↑5 ⇡1 c53676dd 3d docs: add FAQ…
++ beta + ↓| +2 ↓1 | 6ed05ea1 5d Add project h…
+ docs/readme /⊂ ↓1 6ed05ea1 5d Add project h…
+ spike/search /⊂ ↓1 6ed05ea1 5d Add project h…
○ Showing 5 worktrees, 2 remote branches, 3 with changes, 2 ahead, 1 column hidden

diff --git a/docs/demos/snapshots/wt-merge.snap b/docs/demos/snapshots/wt-merge.snap
index 9a075fb83..5dc455135 100644
--- a/docs/demos/snapshots/wt-merge.snap
+++ b/docs/demos/snapshots/wt-merge.snap
@@ -1,9 +1,9 @@
$ wt list
Branch Status HEAD± main↕ Remote⇅ Commit Age Message
-@ main ^| | 9a898ce6 1d docs: add developme…
-+ hooks +! ↑ +25 ↑1 e5bf91b7 2h feat: add math oper…
-+ alpha !? ↑⇡ +105 -14 ↑5 ⇡1 99a8f5d5 3d docs: add FAQ secti…
-+ beta + ↓| +2 ↓1 | 77adea27 5d Add project hooks
+@ main ^| | 98c9958a 1d docs: add developme…
++ hooks +! ↑ +25 ↑1 a5a2f9d5 2h feat: add math oper…
++ alpha !? ↑⇡ +105 -14 ↑5 ⇡1 f9dceea8 3d docs: add FAQ secti…
++ beta + ↓| +2 ↓1 | b0853702 5d Add project hooks
○ Showing 4 worktrees, 3 with changes, 2 ahead, 1 column hidden

@@ -25,13 +25,13 @@ $ wt merge

$ wt list --branches --full
Branch Status HEAD± main↕ main…± Remote⇅ CI Commit Age
-@ main ^| | 9a898ce6 1d
-+ hooks +! ↑ +25 ↑1 +12 -7 e5bf91b7 2h
-+ notes _ 9a898ce6 1d
-+ alpha !? ↑⇡ +105 -14 ↑5 +264 -3 ⇡1 99a8f5d5 3d
-+ beta + ↓| +2 ↓1 | 77adea27 5d
- docs/readme /⊂ ↓1 77adea27 5d
- spike/search /⊂ ↓1 77adea27 5d
+@ main ^| | 98c9958a 1d
++ hooks +! ↑ +25 ↑1 +12 -7 a5a2f9d5 2h
++ notes _ 98c9958a 1d
++ alpha !? ↑⇡ +105 -14 ↑5 +264 -3 ⇡1 f9dceea8 3d
++ beta + ↓| +2 ↓1 | b0853702 5d
+ docs/readme /⊂ ↓1 b0853702 5d
+ spike/search /⊂ ↓1 b0853702 5d
○ Showing 5 worktrees, 2 remote branches, 3 with changes, 2 ahead, 2 columns hidden

diff --git a/docs/demos/tapes/wt-zellij-omnibus.tape b/docs/demos/tapes/wt-zellij-omnibus.tape
index 036e54956..2aa5092b2 100644
--- a/docs/demos/tapes/wt-zellij-omnibus.tape
+++ b/docs/demos/tapes/wt-zellij-omnibus.tape
@@ -42,14 +42,17 @@ Sleep 5s
# Start Zellij before showing
Type "zellij"
Enter
-Sleep 4s
+Sleep 3s
# Dismiss plugin permission dialog (zellij-tab-name asks for permissions on first run)
+# The permission is cached per-plugin-path, but on macOS Zellij uses native cache APIs
+# that ignore $HOME, so we can't pre-populate the cache in the demo's temp directory.
+# If no dialog appears (cache hit), "y" goes to shell, so we follow with Enter + clear.
Type "y"
-Sleep 1s
-# Clear any leftover characters from the permission dialog (before recording starts)
+Enter
+Sleep 500ms
Type "clear"
Enter
-Sleep 1s
+Sleep 500ms
Show
Sleep 500ms