Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
"""Shared infrastructure for demo recording scripts."""
import json
import os
import platform
import re
import shlex
import shutil
import subprocess
import tempfile
import urllib.request
from dataclasses import dataclass
from datetime import datetime, timedelta, timezone
from pathlib import Path
from .themes import PALETTES, THEMES, format_theme_for_vhs
REAL_HOME = Path.home()
FIXTURES_DIR = Path(__file__).parent / "fixtures"
DEPS_DIR = Path(__file__).parent.parent / ".deps" # Downloaded dependencies
# External dependency URLs
_GCS_BUCKET = "https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases"
_ZELLIJ_PLUGIN_URL = "https://github.com/Cynary/zellij-tab-name/releases/download/v0.4.1/zellij-tab-name.wasm"
_VHS_FORK_REPO = "https://github.com/max-sixty/vhs.git"
_VHS_FORK_BRANCH = "keypress-overlay"
# The demo repo's origin claims a GitHub URL, and `url.<bare>.pushInsteadOf`
# sends every push to the local bare repo beside it. `git remote get-url origin`
# reports the URL below, which is what wt's CI detection parses for an
# owner/repo before it will call `gh` at all — a bare filesystem path doesn't
# parse, so a path remote leaves the CI column empty and the picker's `pr` and
# `comments` tabs permanently unavailable. Only push is rewritten: plain
# `get-url` applies `insteadOf` but not `pushInsteadOf`, so rewriting fetch too
# would hand wt the local path again. Nothing in the demos fetches from origin
# (only `wt switch pr:`/`mr:` do, and no tape uses them), and
# `worktrunk.default-branch` is seeded so default-branch detection never falls
# through to `git ls-remote` — so no demo command reaches the network.
DEMO_ORIGIN_URL = "https://github.com/acme/demo.git"
# What `Repository::project_identifier` derives from the URL above. Keys the
# approvals file, so it must track `DEMO_ORIGIN_URL`.
DEMO_PROJECT_ID = "github.com/acme/demo"
def _detect_platform() -> str:
"""Detect platform for Claude Code binary download."""
system = platform.system().lower()
machine = platform.machine().lower()
if system == "darwin":
os_name = "darwin"
elif system == "linux":
os_name = "linux"
else:
raise RuntimeError(f"Unsupported OS: {system}")
if machine in ("x86_64", "amd64"):
arch = "x64"
elif machine in ("arm64", "aarch64"):
arch = "arm64"
else:
raise RuntimeError(f"Unsupported architecture: {machine}")
# Check for musl on Linux x64
if os_name == "linux" and arch == "x64":
try:
result = subprocess.run(
["ldd", "--version"], capture_output=True, text=True, check=False
)
if "musl" in result.stderr.lower() or "musl" in result.stdout.lower():
return "linux-x64-musl"
except FileNotFoundError:
pass
return f"{os_name}-{arch}"
def _download_file(url: str, dest: Path) -> None:
"""Download a file from URL to destination (parallel-safe).
Uses PID-unique temp file to avoid races when multiple processes download
simultaneously. Only moves to dest if dest doesn't exist at move time.
"""
dest.parent.mkdir(parents=True, exist_ok=True)
print(f"Downloading {dest.name}...")
temp = dest.with_suffix(f".{os.getpid()}.tmp")
try:
urllib.request.urlretrieve(url, temp)
# Only move if dest doesn't exist (another process may have finished first)
if not dest.exists():
temp.rename(dest)
finally:
temp.unlink(missing_ok=True)
def _ensure_claude_binary() -> Path:
"""Ensure Claude Code binary is downloaded, return path."""
claude_binary = DEPS_DIR / "claude"
if claude_binary.exists():
return claude_binary
plat = _detect_platform()
print(f"Fetching Claude Code for {plat}...")
# Get stable version
with urllib.request.urlopen(f"{_GCS_BUCKET}/stable") as resp:
version = resp.read().decode().strip()
print(f"Claude Code version: {version}")
# Download binary
_download_file(f"{_GCS_BUCKET}/{version}/{plat}/claude", claude_binary)
claude_binary.chmod(0o755)
# Verify
result = subprocess.run(
[str(claude_binary), "--version"], capture_output=True, text=True, check=False
)
if result.returncode != 0:
raise RuntimeError(
f"Claude binary downloaded but --version failed: {result.stderr or result.stdout}"
)
print(f"✓ Claude Code {version} ready")
return claude_binary
def claude_auth_available() -> bool:
"""Return whether a Claude demo can authenticate without interactive login."""
if os.environ.get("ANTHROPIC_API_KEY") or os.environ.get(
"CLAUDE_CODE_OAUTH_TOKEN"
):
return True
if platform.system() != "Darwin":
return False
try:
with tempfile.TemporaryDirectory(prefix="wt-claude-auth-") as auth_dir:
auth_home = Path(auth_dir)
_forward_macos_keychains(auth_home)
result = subprocess.run(
[str(_ensure_claude_binary()), "auth", "status", "--json"],
env=_isolated_claude_env(auth_home),
capture_output=True,
text=True,
check=False,
timeout=10,
)
if result.returncode != 0:
return False
return bool(json.loads(result.stdout).get("loggedIn"))
except (
OSError,
RuntimeError,
subprocess.TimeoutExpired,
json.JSONDecodeError,
):
return False
def _forward_macos_keychains(home: Path) -> None:
"""Make the user's Keychain search list visible from an isolated HOME."""
if (
platform.system() != "Darwin"
or os.environ.get("ANTHROPIC_API_KEY")
or os.environ.get("CLAUDE_CODE_OAUTH_TOKEN")
):
return
real_home_env = {**os.environ, "HOME": str(REAL_HOME)}
result = subprocess.run(
["security", "list-keychains", "-d", "user"],
env=real_home_env,
capture_output=True,
text=True,
check=False,
)
if result.returncode != 0:
raise RuntimeError(
f"Failed to read the macOS Keychain search list: {result.stderr}"
)
# `security` has no structured output for the search list. Its output is a
# shell-like sequence of quoted paths, one per line.
keychains = [path for path in shlex.split(result.stdout) if Path(path).exists()]
if not keychains:
raise RuntimeError("The macOS user Keychain search list is empty")
(home / "Library" / "Preferences").mkdir(parents=True, exist_ok=True)
run(
["security", "list-keychains", "-d", "user", "-s", *keychains],
env=_isolated_claude_env(home),
)
def recorder_env() -> dict[str, str]:
"""The recorder's environment without the calling Claude Code session's state.
A build started from inside Claude Code inherits that session's ``CLAUDE*``
variables, and a demo's Claude Code reads them as its own: the inherited
child-session marker, for one, makes it warn that transcript saving is off.
Only ``CLAUDE_CODE_OAUTH_TOKEN``, the documented way to authenticate demos,
passes through.
"""
return {
name: value
for name, value in os.environ.items()
if not name.startswith("CLAUDE") or name == "CLAUDE_CODE_OAUTH_TOKEN"
}
def _isolated_claude_env(home: Path) -> dict[str, str]:
"""Build an environment whose Claude state stays under an isolated HOME."""
env = recorder_env()
env["HOME"] = str(home)
env["XDG_CONFIG_HOME"] = str(home / ".config")
return env
def _ensure_zellij_plugin() -> Path:
"""Ensure Zellij tab-name plugin is downloaded, return path."""
plugin_path = DEPS_DIR / "zellij-tab-name.wasm"
if plugin_path.exists():
return plugin_path
_download_file(_ZELLIJ_PLUGIN_URL, plugin_path)
print("✓ Zellij plugin ready")
return plugin_path
# A source marker for the newest fork commit the tapes depend on, as
# (file, substring). Name the latest one: the branch is linear, so a clone that
# has it has the ones before it too.
#
# `ensure_vhs_binary` reuses an existing clone and an existing binary without
# pulling, so a clone made before that commit keeps building a VHS the tapes
# have outgrown — one that drops the Alt modifier, turning a tape's `Alt+p`
# into a literal "p" typed at whatever has focus; one that times the keystroke
# overlay from the first keypress rather than from the video, which slides
# every key a fixed distance away from what it did; or one that records a
# modifier as a keystroke of its own, so `Alt+"8"` reads as a spent ⌥ followed
# by an unrelated 8. Each records a wrong GIF with no error from VHS, the
# build, or the recording, which is why this checks rather than trusting the
# clone.
_VHS_FORK_MARKER = ("keystroke.go", "heldModifiers")
def _require_current_vhs_fork(vhs_dir: Path) -> None:
"""Fail when the VHS clone predates the fork commit the tapes need."""
source_name, marker = _VHS_FORK_MARKER
source = vhs_dir / source_name
if source.exists() and marker in source.read_text():
return
raise RuntimeError(
f"The VHS fork clone at {vhs_dir} predates the {marker} fix, so a tape's "
f"keystroke overlay would not match what the screen does.\n"
f"Update and rebuild it:\n"
f" git -C {vhs_dir} pull && rm -f {vhs_dir / 'vhs'}"
)
def ensure_vhs_binary() -> Path:
"""Ensure VHS binary is cloned and built, return path.
Uses a custom VHS fork with keystroke overlay support.
Requires Go to be installed.
"""
vhs_dir = DEPS_DIR / "vhs"
vhs_binary = vhs_dir / "vhs"
if vhs_binary.exists():
_require_current_vhs_fork(vhs_dir)
return vhs_binary
# Check Go is available
if not shutil.which("go"):
raise RuntimeError(
"Go is required to build VHS. Install from https://go.dev/dl/"
)
# Clone if needed
if not vhs_dir.exists():
print("Cloning VHS fork...")
DEPS_DIR.mkdir(parents=True, exist_ok=True)
result = subprocess.run(
["git", "clone", "-b", _VHS_FORK_BRANCH, "--depth=1", _VHS_FORK_REPO, str(vhs_dir)],
capture_output=True,
text=True,
)
if result.returncode != 0:
raise RuntimeError(f"Failed to clone VHS fork: {result.stderr}")
# Build
print("Building VHS...")
result = subprocess.run(
["go", "build", "-o", "vhs", "."],
cwd=vhs_dir,
capture_output=True,
text=True,
)
if result.returncode != 0:
raise RuntimeError(f"Failed to build VHS: {result.stderr}")
# Verify
result = subprocess.run(
[str(vhs_binary), "--version"],
capture_output=True,
text=True,
check=False,
)
if result.returncode != 0:
raise RuntimeError(f"VHS built but --version failed: {result.stderr}")
_require_current_vhs_fork(vhs_dir)
print("✓ VHS ready")
return vhs_binary
# Shared content for demos
VALIDATION_RS = """//! Input validation utilities.
/// Validates that a number is positive.
pub fn is_positive(n: i32) -> bool {
n > 0
}
/// Validates that a string is not empty.
pub fn is_non_empty(s: &str) -> bool {
!s.trim().is_empty()
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_is_positive() {
assert!(is_positive(1));
assert!(!is_positive(0));
assert!(!is_positive(-1));
}
}
"""
@dataclass
class DemoEnv:
"""Isolated demo environment with its own repo and home directory."""
name: str
out_dir: Path
theme: str
repo_name: str = "worktrunk"
@property
def root(self) -> Path:
return self.out_dir / f".demo-{self.name}"
@property
def home(self) -> Path:
return self.root
@property
def work_base(self) -> Path:
return self.home / "w"
@property
def repo(self) -> Path:
return self.work_base / self.repo_name
@property
def bare_remote(self) -> Path:
return self.root / "remote.git"
@property
def starship_config(self) -> Path:
return self.out_dir / "starship.toml"
def run(cmd, cwd=None, env=None, check=True, capture=False):
"""Run a command."""
result = subprocess.run(
cmd, cwd=cwd, env=env, check=check, capture_output=capture, text=True
)
return result.stdout if capture else None
def git(args, cwd=None, env=None):
"""Run git command."""
run(["git"] + args, cwd=cwd, env=env)
def render_tape(template_path: Path, replacements: dict, repo_root: Path) -> str | None:
"""Render a VHS tape template with Source inlining and variable substitutions.
Args:
template_path: Path to the .tape template file
replacements: Dict of {{VAR}} -> value replacements
repo_root: Root of the repository (for resolving Source paths)
Returns:
Rendered tape content, or None if template doesn't exist
"""
if not template_path.exists():
print(f"Warning: {template_path} not found, skipping VHS recording")
return None
rendered = template_path.read_text()
# Inline Source directives (VHS doesn't support them, we handle it)
def inline_source(match):
source_path = repo_root / match.group(1).strip().strip('"')
return source_path.read_text()
rendered = re.sub(r"^Source\s+(.+)$", inline_source, rendered, flags=re.MULTILINE)
# Apply template variable replacements
for key, value in replacements.items():
rendered = rendered.replace(f"{{{{{key}}}}}", str(value))
return rendered
def record_vhs(
tape_path: Path, vhs_binary: str = "vhs", expected_output: Path = None
):
"""Record a demo GIF using VHS."""
env = recorder_env()
# GIF assets include ANSI styling independent of the recorder's shell.
env.pop("NO_COLOR", None)
env["CLICOLOR_FORCE"] = "1"
run([vhs_binary, str(tape_path)], check=True, env=env)
if expected_output and not expected_output.exists():
raise RuntimeError(
f"VHS exited 0 but {expected_output.name} was not created. "
"Check ffmpeg output above — likely missing libass support."
)
def build_wt(repo_root: Path):
"""Build the wt binary."""
print("Building wt binary...")
run(["cargo", "build", "--quiet"], cwd=repo_root)
# The demo's open PRs on the mocked forge, one row per branch.
#
# `delay` is how long that branch's `gh pr list` waits before answering. wt runs
# one call per branch concurrently, so staggering the delays is what the picker
# and `wt list --full` show as CI status streaming in: cells land one at a time
# behind the frame that already painted from local git. Keep the largest under
# the tape's post-command sleep — `wt list` can't finish until every call
# returns, even though it renders progressively.
#
# `checks` is `statusCheckRollup`; `review` is `reviewDecision` (None for a PR
# with no reviews). Comment ages are hours before the recording, so the pane's
# relative times read naturally. A branch absent here has no PR; DEMO_BRANCH_CI
# below covers branch CI without one.
DEMO_PRS = [
{
"number": 1,
"branch": "alpha",
"title": "Add utility functions module",
"body": "Adds `src/utils.rs` with path normalization and project-root "
"discovery, plus the string helpers the config loader needs.",
"author": "dbenson",
"checks": [("COMPLETED", "SUCCESS")],
"review": "APPROVED",
"delay": 0.3,
# Bodies are written for the picker's preview pane, which is about half
# the terminal — roughly 65 columns at `SIZE_DOCS_PICKER`. Short
# sentences and short code lines keep the wrap from shredding them, and
# the thread runs a little past one screen so ctrl-d has somewhere to go.
"comments": [
(
"dbenson",
28,
"Opening this for review. The path helpers are lifted out "
"of the config loader as-is — no behaviour change intended.",
),
(
"rmurthy",
26,
"`normalize_path` pops `..` without resolving "
"symlinks, so it can land somewhere the kernel "
"wouldn't. Worth saying so in the doc comment.",
),
(
"dbenson",
22,
"That's the documented difference from "
"`fs::canonicalize` — we never touch the "
"filesystem, so we can't know. Spelled it out:\n\n"
"```rust\n"
"/// Purely lexical: `..` pops the\n"
"/// previous component without\n"
"/// resolving symlinks.\n"
"```",
),
(
"rmurthy",
20,
"Reads well. One more: `find_project_root` walks "
"all the way to `/` when the path is outside any "
"project. That's a lot of `stat` for a miss.",
),
(
"dbenson",
18,
"Measured it: a miss from a nested path is about forty "
"`stat` calls here. Fine on a warm cache, less so on a "
"network mount.",
),
(
"rmurthy",
14,
"A network mount is exactly where I'd expect it to bite. "
"Worth a ceiling — the first directory we can't read is "
"as good a one as any.",
),
(
"dbenson",
6,
"Bounded it at the filesystem root, or the first "
"directory we can't read. There's a test that "
"runs it from `/tmp` now.",
),
(
"rmurthy",
4,
"Last thing and then I'm happy: `join_relative` "
"takes `&str` while everything around it takes "
"`impl AsRef<Path>`.",
),
(
"dbenson",
2,
"Fixed. Every helper in the module takes "
"`impl AsRef<Path>` now.",
),
(
"rmurthy",
1,
"Approving. Let's land this before the config "
"loader change, so that one can drop its own copy "
"of the helpers.",
),
],
},
{
"number": 2,
"branch": "beta",
"title": "Cache resolved config per project",
"body": "Keeps the parsed config behind a `OnceCell` so a command "
"that reads it twice doesn't parse twice.",
"author": "dbenson",
"checks": [("IN_PROGRESS", None)],
"review": "REVIEW_REQUIRED",
"delay": 0.8,
"comments": [
(
"rmurthy",
3,
"Does this need invalidation? A long-lived process would "
"hold a stale config across an edit.",
),
],
},
{
"number": 4,
"branch": "api",
"title": "Add the /health endpoint",
"body": "Returns build metadata and the database's round-trip time.",
"author": "dbenson",
"checks": [("COMPLETED", "FAILURE")],
"review": None,
"delay": 1.2,
"comments": [
(
"ci-bot",
1,
"`test (linux)` failed: `acme::tests::test_add_zeros` "
"panicked at `assert_eq!(add(0, 0), 0)`.",
),
],
},
{
"number": 5,
"branch": "auth",
"title": "Rotate session tokens on privilege change",
"body": "Issues a fresh token whenever a session's role changes, so a "
"downgraded session can't keep its old claims.",
"author": "rmurthy",
"checks": [("COMPLETED", "SUCCESS")],
"review": "CHANGES_REQUESTED",
"delay": 1.6,
"comments": [
(
"dbenson",
5,
"The rotation drops the old token immediately, which logs "
"out every other tab. Can we keep it valid for a grace "
"period?",
),
],
},
{
"number": 6,
"branch": "billing",
"title": "Format currency by locale",
"body": "Replaces the hand-rolled formatter with the locale-aware one.",
"author": "dbenson",
"checks": [("COMPLETED", "SUCCESS")],
"review": None,
"delay": 1.0,
"comments": [],
},
]
# Branches whose CI comes from the check-runs API rather than a PR — the bare
# `#` in the CI column. `main` has pushed commits and passing checks but no open
# PR. Branches listed in neither this nor DEMO_PRS show no CI at all, which is
# what `hooks` (no remote) demonstrates.
DEMO_BRANCH_CI = {
"main": [("completed", "success")],
"cache": [("completed", "success")],
"release": [("completed", "failure")],
"search": [("completed", "success")],
"retry": [("completed", "failure")],
}
def _iso_hours_ago(now: datetime, hours: int) -> str:
"""RFC 3339 timestamp `hours` before `now`, as the forge reports one.
`now` must be UTC-aware: the forge stamps comments in UTC, and the picker
renders them as an age against the clock. A naive local time with a `Z`
suffix would shift every age by the recorder's UTC offset.
"""
return (now - timedelta(hours=hours)).strftime("%Y-%m-%dT%H:%M:%SZ")
def _rev_parse(repo: Path, rev: str) -> str | None:
"""Resolve `rev` in `repo`, or None when it doesn't exist."""
result = subprocess.run(
["git", "-C", str(repo), "rev-parse", "--verify", "--quiet", rev],
capture_output=True,
text=True,
)
return result.stdout.strip() or None
def write_gh_mock_data(env: DemoEnv) -> None:
"""Write the mocked forge's responses for this demo environment.
Runs after the branches exist: the check-runs responses are keyed by commit
SHA, and a PR's `headRefOid` is its pushed tip, so a branch with unpushed
commits reports the stale-head marker a real PR would. `prepare_demo_repo`
calls it once the shared branches are in place; a setup that adds more
branches calls it again, which rewrites every file from the current state.
Each file's first line is the delay the mock waits before answering; see
DEMO_PRS and `fixtures/gh-mock.sh`.
"""
mock_dir = env.home / ".local" / "share" / "gh-mock"
for sub in ("head", "view", "sha"):
(mock_dir / sub).mkdir(parents=True, exist_ok=True)
def write(rel: str, delay: float, payload) -> None:
(mock_dir / rel).write_text(f"{delay}\n{json.dumps(payload)}\n")
now = datetime.now(timezone.utc)
for pr in DEMO_PRS:
branch = pr["branch"]
# The pushed tip when there is one, so unpushed local commits read as a
# stale PR head; a branch created during the recording has neither yet.
head = _rev_parse(env.repo, f"origin/{branch}") or _rev_parse(
env.repo, branch
)
comments = [
{
"author": {"login": author},
"body": body,
"createdAt": _iso_hours_ago(now, hours),
}
for author, hours, body in pr["comments"]
]
newest = min((hours for _, hours, _ in pr["comments"]), default=1)
entry = {
"number": pr["number"],
"title": pr["title"],
"body": pr["body"],
"author": {"login": pr["author"]},
"comments": comments,
"headRefOid": head,
"mergeStateStatus": "CLEAN",
"statusCheckRollup": [
{"status": status, "conclusion": conclusion}
for status, conclusion in pr["checks"]
],
"url": f"https://github.com/acme/demo/pull/{pr['number']}",
"headRepositoryOwner": {"login": "acme"},
"reviewDecision": pr["review"],
"isDraft": False,
"updatedAt": _iso_hours_ago(now, newest),
}
# `/` -> `_` matches `sanitize` in fixtures/gh-mock.sh.
write(f"head/{branch.replace('/', '_')}", pr["delay"], [entry])
# The comments tab's own fetch, for a row whose CI call hasn't primed
# the cache yet — which the delays above make the common case.
write(f"view/{pr['number']}", pr["delay"], {"comments": comments})
for branch, checks in DEMO_BRANCH_CI.items():
sha = _rev_parse(env.repo, branch)
if sha is None:
continue
write(
f"sha/{sha}",
0.5,
[{"status": status, "conclusion": conclusion} for status, conclusion in checks],
)
def commit_dated(repo: Path, message: str, offset: str, env_extra: dict = None):
"""Commit with a date offset like '7d' or '2H'."""
now = datetime.now()
if offset.endswith("d"):
delta = timedelta(days=int(offset[:-1]))
elif offset.endswith("H"):
delta = timedelta(hours=int(offset[:-1]))
else:
raise ValueError(f"Unknown offset format: {offset}")
date_str = (now - delta).strftime("%Y-%m-%dT%H:%M:%S")
env = os.environ.copy()
env["GIT_AUTHOR_DATE"] = date_str
env["GIT_COMMITTER_DATE"] = date_str
env["SKIP_DEMO_HOOK"] = "1"
if env_extra:
env.update(env_extra)
git(["-C", str(repo), "commit", "-qm", message], env=env)
def prepare_base_repo(env: DemoEnv, repo_root: Path):
"""Set up the base demo repository with Rust project.
Creates:
- Git repo with initial commit
- Rust project (Cargo.toml, lib.rs, Cargo.lock)
- Mock gh CLI for CI status
- bat wrapper for syntax highlighting
- User config directory
Demos should call this first, then add their own:
- Project hooks config (.config/wt.toml)
- Branches and worktrees
- Additional mock CLIs
- Approved commands in user config
"""
# Clean previous (exist_ok=True handles cases where rmtree silently fails,
# e.g., stale processes holding files open)
shutil.rmtree(env.root, ignore_errors=True)
env.root.mkdir(parents=True, exist_ok=True)
env.work_base.mkdir(parents=True, exist_ok=True)
env.repo.mkdir(parents=True, exist_ok=True)
# Init bare remote
run(["git", "init", "--bare", "-q", str(env.bare_remote)])
# Init main repo
git(["-C", str(env.repo), "init", "-q"])
git(["-C", str(env.repo), "config", "user.name", "Worktrunk Demo"])
git(["-C", str(env.repo), "config", "user.email", "[email protected]"])
git(["-C", str(env.repo), "config", "commit.gpgsign", "false"])
# Suppress wt hints in demo output (hints are stored in git config)
git(["-C", str(env.repo), "config", "worktrunk.hints.worktree-path", "true"])
# Initial commit
(env.repo / "README.md").write_text("# Acme App\n\nA demo application.\n")
git(["-C", str(env.repo), "add", "README.md"])
commit_dated(env.repo, "Initial commit", "7d")
git(["-C", str(env.repo), "branch", "-m", "main"])
# Claim a GitHub origin, push to the local bare repo (see DEMO_ORIGIN_URL).
git(["-C", str(env.repo), "remote", "add", "origin", DEMO_ORIGIN_URL])
git([
"-C",
str(env.repo),
"config",
f"url.{env.bare_remote}.pushInsteadOf",
DEMO_ORIGIN_URL,
])
# Seed the default branch so detection never reaches `git ls-remote`, whose
# fetch URL is the unreachable github.com one.
git(["-C", str(env.repo), "config", "worktrunk.default-branch", "main"])
git(["-C", str(env.repo), "push", "-u", "origin", "main", "-q"])
# Rust project
(env.repo / "Cargo.toml").write_text(
'[package]\nname = "acme"\nversion = "0.1.0"\nedition = "2021"\n\n[workspace]\n'
)
(env.repo / "src").mkdir()
shutil.copy(FIXTURES_DIR / "lib.rs", env.repo / "src" / "lib.rs")
(env.repo / ".gitignore").write_text("/target\n")
git(["-C", str(env.repo), "add", ".gitignore", "Cargo.toml", "src/"])
commit_dated(env.repo, "Add Rust project with tests", "6d")
# Build to create Cargo.lock
run(["cargo", "build", "--release", "-q"], cwd=env.repo, check=False)
git(["-C", str(env.repo), "add", "Cargo.lock"])
commit_dated(env.repo, "Add Cargo.lock", "6d")
git(["-C", str(env.repo), "push", "-q"])
# Mock CLI tools
bin_dir = env.home / ".local" / "bin"
bin_dir.mkdir(parents=True, exist_ok=True)
# bat wrapper for syntax highlighting (alias cat to bat for toml files)
bat_wrapper = bin_dir / "cat"
bat_wrapper.write_text("""#!/bin/bash
# Use bat for syntax highlighting if file is toml
if [[ "$1" == *.toml ]]; then
exec bat --style=plain --paging=never "$@"
else
exec /bin/cat "$@"
fi
""")
bat_wrapper.chmod(0o755)
# Build wt binary
build_wt(repo_root)
# Install fish completions (needed for tab completion in demos)
# Note: Demos using tab completion also need to source the completions
# in the tape's hidden section (VHS doesn't trigger fish's lazy loading)
wt_bin = repo_root / "target" / "debug" / "wt"
install_env = os.environ.copy()
install_env["HOME"] = str(env.home)
run([str(wt_bin), "config", "shell", "install", "fish", "--yes"], env=install_env)
# Fish syntax highlighting colors — use ANSI names so the VHS terminal
# theme controls the actual rendered RGB values (light vs dark).
# Two mechanisms: fish_variables for --shell/--snapshot mode (fish reads at
# startup), colors.fish for VHS recordings (VHS applies Env HOME after fish
# starts, so fish_variables from the demo home isn't read).
fish_config_dir = env.home / ".config" / "fish"
fish_config_dir.mkdir(parents=True, exist_ok=True)
color_vars = {
"fish_color_autosuggestion": "brblack",
"fish_color_command": "yellow", # amber — matches website .cmd color
"fish_color_comment": "brblack",
"fish_color_end": "normal",
"fish_color_error": "red",
"fish_color_escape": "cyan",
"fish_color_keyword": "yellow",
"fish_color_normal": "normal",
"fish_color_operator": "normal",
"fish_color_param": "normal",
"fish_color_quote": "green",
"fish_color_redirection": "normal",
}
# fish_variables file (for --shell and --snapshot modes)
lines = [
"# This file contains fish universal variable definitions.",
"# VERSION: 3.0",
]
lines.extend(f"SETUVAR {k}:{v}" for k, v in color_vars.items())
lines.extend([
"SETUVAR fish_color_cancel:\\x2d\\x2dreverse",
"SETUVAR fish_color_search_match:\\x2d\\x2dbackground\\x3d111",
"SETUVAR fish_color_selection:\\x2d\\x2dbackground\\x3dbrblack",
"SETUVAR fish_color_valid_path:\\x2d\\x2dunderline",
"SETUVAR fish_greeting:",
])
(fish_config_dir / "fish_variables").write_text("\n".join(lines) + "\n")
# colors.fish script (sourced in VHS tape hidden section)
color_lines = [f"set -g {k} {v}" for k, v in color_vars.items()]
(fish_config_dir / "colors.fish").write_text("\n".join(color_lines) + "\n")
# User config directory (demos add their own config.toml)
config_dir = env.home / ".config" / "worktrunk"
config_dir.mkdir(parents=True)
# Project config directory
(env.repo / ".config").mkdir(exist_ok=True)
def setup_claude_code_config(
env: DemoEnv,
worktree_paths: list[str],
allowed_tools: list[str] = None,
) -> None:
"""Set up Claude Code configuration to skip first-run dialogs.
Args:
env: Demo environment
worktree_paths: List of worktree paths to pre-approve for trust
allowed_tools: List of tools to pre-approve (default: none, Claude will ask)
"""
api_key_suffix = (
os.environ.get("ANTHROPIC_API_KEY", "")[-20:]
if os.environ.get("ANTHROPIC_API_KEY")
else ""
)
# Build projects config - pre-approve trust for all worktree paths
# Use resolved paths to handle macOS symlinks (/var -> /private/var)
projects_config = {}
for path in worktree_paths:
resolved_path = str(Path(path).resolve())
projects_config[resolved_path] = {
"allowedTools": [],
"hasTrustDialogAccepted": True,
}
claude_json = env.home / ".claude.json"
claude_json.write_text(
json.dumps(
{
"numStartups": 100,
"installMethod": "global",
"theme": env.theme,
"firstStartTime": "2025-01-01T00:00:00.000Z",
"hasCompletedOnboarding": True,
"hasCompletedClaudeInChromeOnboarding": True,
"claudeInChromeDefaultEnabled": False,
"sonnet45MigrationComplete": True,
"opus45MigrationComplete": True,
"thinkingMigrationComplete": True,
"hasShownOpus45Notice": {},
"hasShownOpus46Notice": {},
"opusProMigrationComplete": True,
"opus46FeedSeenCount": 100,
"unpinFable5LaunchEffort": True,
"sonnet1m45MigrationComplete": True,
"lastReleaseNotesSeen": "99.0.0",
"lastOnboardingVersion": "99.0.0",
"announcementImpressions": {
"fable-5-promo-2": 100,
"fable-5-promo-2-2": 100,
"fable-5-promo-2-3": 100,
"fable-5-promo-2-4-max": 100,
"opus-5-launch": 100,
},
"oauthAccount": {
"displayName": "wt",
"emailAddress": "[email protected]",
},
"customApiKeyResponses": {
"approved": [api_key_suffix] if api_key_suffix else [],
"rejected": [],
},
"officialMarketplaceAutoInstalled": True,
"effortCalloutDismissed": True,
"lspRecommendationDisabled": True,
"passesUpsellSeenCount": 100,
"passesLastSeenRemaining": 999,
"hasVisitedPasses": True,
"tipsHistory": {
"new-user-warmup": 100,
"terminal-setup": 100,
"theme-command": 100,
"fast-mode-2026-02-01": 100,
"adaptive-thinking-2026-01-28": 100,
"prompt-caching-scope-2026-01-05": 100,
"plan-mode-for-complex-tasks": 100,
"memory-command": 100,
"todo-list": 100,
"stickers-command": 100,
"status-line": 100,
"custom-commands": 100,
"custom-agents": 100,
"permissions": 100,
"git-worktrees": 100,
"guest-passes": 100,
},
"projects": projects_config,
},
indent=2,
)
)
# Copy claude binary (downloaded automatically if missing)
# Claude Code detects native install by checking if ~/.local/bin/claude exists
local_bin = env.home / ".local" / "bin"
local_bin.mkdir(parents=True, exist_ok=True)
claude_binary = _ensure_claude_binary()
shutil.copy(claude_binary, local_bin / "claude")
# Claude settings.json
claude_dir = env.home / ".claude"
claude_dir.mkdir(exist_ok=True)
settings = {
"permissions": {"allow": allowed_tools or [], "deny": [], "ask": []},
"model": "claude-opus-4-6",
# Accounts in the Remote Control rollout otherwise start it, which
# prints a live claude.ai session URL into the GIF.
"remoteControlAtStartup": False,
"statusLine": {
"type": "command",
"command": "wt list statusline --format=claude-code",
},
}
(claude_dir / "settings.json").write_text(json.dumps(settings, indent=2))
_forward_macos_keychains(env.home)
def setup_zellij_config(env: DemoEnv, default_cwd: str = None) -> None:
"""Set up Zellij configuration for demo recording.
Creates config with the site palette for the recording's theme, minimal
keybinds, and tab-rename plugin. Plugin is downloaded automatically if
missing.
Args:
env: Demo environment
default_cwd: Optional default working directory for new panes
"""
palette = PALETTES[env.theme]
zellij_config_dir = env.home / ".config" / "zellij"
zellij_config_dir.mkdir(parents=True, exist_ok=True)
zellij_plugins_dir = zellij_config_dir / "plugins"
zellij_plugins_dir.mkdir(exist_ok=True)
# Copy Zellij plugin (downloaded automatically if missing)
plugin_path = _ensure_zellij_plugin()
shutil.copy(plugin_path, zellij_plugins_dir / "zellij-tab-name.wasm")
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"
{default_cwd_line}
pane_frames false
show_startup_tips false
show_release_notes false
theme "worktrunk"
// Load the tab-name plugin
load_plugins {{
"file:{zellij_plugins_dir}/zellij-tab-name.wasm"
}}
themes {{
worktrunk {{
fg "{palette['--wt-ink']}"
bg "{palette['--wt-paper']}"
black "{palette['--wt-paper-soft']}"
red "{palette['--wt-terminal-red']}"
green "{palette['--wt-terminal-green']}"
yellow "{palette['--wt-terminal-yellow']}"
blue "{palette['--wt-terminal-blue']}"
magenta "{palette['--wt-terminal-magenta']}"
cyan "{palette['--wt-terminal-cyan']}"
white "{palette['--wt-ink-muted']}"
orange "{palette['--wt-copper']}"
}}
}}
keybinds clear-defaults=true {{
normal {{
bind "Ctrl Space" {{ SwitchToMode "tmux"; }}
}}
tmux {{
bind "o" {{ SwitchToMode "pane"; }}
bind "p" {{ SwitchToMode "pane"; }}
bind "t" {{ SwitchToMode "tab"; }}
bind "q" {{ Quit; }}
}}
tab {{
bind "n" {{ NewTab; SwitchToMode "Normal"; }}
bind "h" "Left" {{ GoToPreviousTab; SwitchToMode "Normal"; }}
bind "l" "Right" {{ GoToNextTab; SwitchToMode "Normal"; }}
bind "1" {{ GoToTab 1; SwitchToMode "Normal"; }}
bind "2" {{ GoToTab 2; SwitchToMode "Normal"; }}
bind "3" {{ GoToTab 3; SwitchToMode "Normal"; }}
bind "4" {{ GoToTab 4; SwitchToMode "Normal"; }}
}}
pane {{
bind "n" {{ NewPane; SwitchToMode "Normal"; }}
}}
shared_except "locked" {{
bind "Ctrl t" {{ NewTab; }}
bind "Ctrl n" {{ NewPane; }}
}}
shared_except "normal" {{
bind "Ctrl Space" "Ctrl c" {{ SwitchToMode "normal"; }}
bind "Esc" {{ SwitchToMode "normal"; }}
}}
}}
""")
def setup_fish_config(env: DemoEnv, wsl_create: bool = False) -> None:
"""Set up Fish shell configuration for demo recording.
Creates config with wsl abbreviation, starship, wt shell integration,
Zellij tab auto-rename, and completion pre-loading.
Note: Completion files are installed by prepare_base_repo(). This function
creates config.fish that sources them (needed because VHS doesn't trigger
fish's lazy completion loading reliably).
Args:
env: Demo environment
wsl_create: If True, wsl abbreviation includes --create flag
"""
fish_config_dir = env.home / ".config" / "fish"
fish_config_dir.mkdir(parents=True, exist_ok=True)
wsl_cmd = (
"wt switch --execute=claude --create"
if wsl_create
else "wt switch --execute=claude"
)
fish_config = fish_config_dir / "config.fish"
fish_config.write_text(f"""# Demo fish config
# wsl abbreviation: switch to worktree and launch Claude
abbr --add wsl '{wsl_cmd}'
# New Zellij tabs start new fish processes, so disable suggestions here rather
# than only in the tape's initial shell.
set -g fish_autosuggestion_enabled 0
starship init fish | source
# Pre-load wt completions (VHS doesn't trigger lazy loading reliably)
source ~/.config/fish/completions/wt.fish 2>/dev/null
# Disable cursor blinking for VHS recording
set fish_cursor_default block
# Send escape sequences to disable cursor blink
printf '\\e[?12l' # Disable cursor blink mode
printf '\\e[2 q' # Set steady block cursor (non-blinking)
# Auto-rename Zellij tabs based on git branch (for demo)
function __zellij_tab_rename --on-variable PWD
if set -q ZELLIJ
# Get git branch name, fallback to directory basename
set -l branch (git rev-parse --abbrev-ref HEAD 2>/dev/null)
if test -n "$branch"
zellij action rename-tab $branch
end
end
end
""")
def setup_mock_clis(env: DemoEnv) -> None:
"""Set up comprehensive mock CLIs for all demo scenarios.
Creates mocks for: npm, docker, flyctl, llm, cargo.
Each mock handles all cases - demos just use the branches they need.
"""
bin_dir = env.home / ".local" / "bin"
bin_dir.mkdir(parents=True, exist_ok=True)
# npm mock - handles install, build, dev (with optional port)
npm_mock = bin_dir / "npm"
npm_mock.write_text("""#!/bin/bash
if [[ "$1" == "install" ]]; then
echo "added 847 packages in 3.2s"
elif [[ "$1" == "run" && "$2" == "build" ]]; then
echo "vite v5.4.2 building for production..."
echo "✓ 142 modules transformed"
echo "dist/index.js 45.2 kB │ gzip: 14.8 kB"
elif [[ "$1" == "run" && "$2" == "dev" ]]; then
# Extract port from args if provided (e.g., npm run dev -- --port 3001)
port=3000
for arg in "$@"; do
if [[ "$prev" == "--port" ]]; then
port="$arg"
fi
prev="$arg"
done
echo ""
echo " VITE v5.4.2 ready in 342 ms"
echo ""
echo " ➜ Local: http://localhost:$port/"
echo " ➜ Network: http://192.168.1.42:$port/"
fi
""")
npm_mock.chmod(0o755)
# docker mock - handles compose up
docker_mock = bin_dir / "docker"
docker_mock.write_text("""#!/bin/bash
if [[ "$1" == "compose" && "$2" == "up" ]]; then
echo "[+] Running 1/1"
echo " ✔ Container postgres Started"
fi
""")
docker_mock.chmod(0o755)
# flyctl mock - handles scale
flyctl_mock = bin_dir / "flyctl"
flyctl_mock.write_text("""#!/bin/bash
if [[ "$1" == "scale" ]]; then
echo "Scaling app to 0 machines"
fi
""")
flyctl_mock.chmod(0o755)
# llm mock — the command every demo's `[commit.generation]` points at.
llm_mock = bin_dir / "llm"
shutil.copy(FIXTURES_DIR / "llm-mock.sh", llm_mock)
llm_mock.chmod(0o755)
# cargo mock - handles nextest run
cargo_mock = bin_dir / "cargo"
cargo_mock.write_text(r"""#!/bin/bash
if [[ "$1" == "nextest" && "$2" == "run" ]]; then
sleep 0.3
echo " Finished \`test\` profile [unoptimized + debuginfo] target(s) in 0.02s"
echo " Starting 2 tests across 1 binary"
echo " PASS [ 0.001s] acme::tests::test_add"
echo " PASS [ 0.001s] acme::tests::test_add_zeros"
echo "------------"
echo " Summary [ 0.002s] 2 tests run: 2 passed, 0 skipped"
fi
""")
cargo_mock.chmod(0o755)
def prepare_demo_repo(env: DemoEnv, repo_root: Path, hooks_config: str = None):
"""Set up a full demo repository with varied branches.
Creates a rich repo for great `wt list` output:
- Git repo with Rust project
- Mock CLIs (npm, docker, flyctl, llm, cargo, gh)
- bat wrapper for syntax highlighting
- Extra branches without worktrees (docs/readme, spike/search)
- alpha: large diff, unpushed commits, behind main
- beta: staged changes, behind main
- hooks: no remote, staged+unstaged changes
Args:
env: Demo environment
repo_root: Path to worktrunk repo for building wt
hooks_config: Optional project hooks (.config/wt.toml) content.
If None, uses default pre-merge hook.
After calling this, main is at the latest commit and worktrees exist for
alpha, beta, hooks. Demos can then add their own config.
"""
# Base setup: git repo, Rust project, bat wrapper, wt binary
prepare_base_repo(env, repo_root)
# Set up all mock CLIs - demos use what they need
setup_mock_clis(env)
# Project hooks
if hooks_config is None:
hooks_config = '[pre-merge]\ntest = "cargo nextest run"\n'
(env.repo / ".config" / "wt.toml").write_text(hooks_config)
(env.repo / "AGENTS.md").write_text("# Acme App\n\nRust project. Run `cargo test` for tests.\n")
git(["-C", str(env.repo), "add", ".config/wt.toml", "AGENTS.md"])
commit_dated(env.repo, "Add project hooks", "5d")
git(["-C", str(env.repo), "push", "-q"])
# Mock gh CLI. Its responses are written by `write_gh_mock_data` at the end
# of this function, once the branches it keys off exist.
bin_dir = env.home / ".local" / "bin"
gh_mock = bin_dir / "gh"
shutil.copy(FIXTURES_DIR / "gh-mock.sh", gh_mock)
gh_mock.chmod(0o755)
# Extra branches without worktrees (for --branches view)
git(["-C", str(env.repo), "branch", "docs/readme"])
git(["-C", str(env.repo), "branch", "spike/search"])
# Create beta first (from current main, so it will be behind after main commit)
_create_branch_beta(env)
# Commit to main so beta is behind
readme = env.repo / "README.md"
readme.write_text(
readme.read_text() + "\n## Development\n\nSee CONTRIBUTING.md for guidelines.\n"
)
(env.repo / "notes.md").write_text("# Notes\n")
git(["-C", str(env.repo), "add", "README.md", "notes.md"])
commit_dated(env.repo, "docs: add development section", "1d")
git(["-C", str(env.repo), "push", "-q"])
# Create alpha and hooks after the main commit (so they're only ahead, not diverged)
_create_branch_alpha(env)
_create_branch_hooks(env)
write_gh_mock_data(env)
def _create_branch_alpha(env: DemoEnv):
"""Create alpha branch with large diff and unpushed commits."""
branch = "alpha"
path = env.work_base / f"acme.{branch}"
git(["-C", str(env.repo), "checkout", "-q", "-b", branch, "main"])
# Initial README changes
(env.repo / "README.md").write_text("""# Acme App
A demo application for showcasing worktrunk features.
## Features
- Fast worktree switching
- Integrated merge workflow
- Pre-merge test hooks
- LLM commit messages
## Getting Started
Run `wt list` to see all worktrees.
""")
git(["-C", str(env.repo), "add", "README.md"])
commit_dated(env.repo, "docs: expand README", "3d")
# More commits
readme = env.repo / "README.md"
readme.write_text(readme.read_text() + "\n## Contributing\n\nPRs welcome!\n")
git(["-C", str(env.repo), "add", "README.md"])
commit_dated(env.repo, "docs: add contributing section", "3d")
readme.write_text(readme.read_text() + "\n## License\n\nMIT\n")
git(["-C", str(env.repo), "add", "README.md"])
commit_dated(env.repo, "docs: add license", "3d")
# Add utils module with substantial content
shutil.copy(FIXTURES_DIR / "alpha-utils.rs", env.repo / "src" / "utils.rs")
# Update lib.rs to include the module
lib_rs = env.repo / "src" / "lib.rs"
lib_content = lib_rs.read_text()
lib_rs.write_text("pub mod utils;\n\n" + lib_content)
git(["-C", str(env.repo), "add", "src/utils.rs", "src/lib.rs"])
commit_dated(env.repo, "feat: add utility functions module", "3d")
git(["-C", str(env.repo), "push", "-u", "origin", branch, "-q"])
git(["-C", str(env.repo), "checkout", "-q", "main"])
git(["-C", str(env.repo), "worktree", "add", "-q", str(path), branch])
# Unpushed commit
readme = path / "README.md"
readme.write_text(readme.read_text() + "## FAQ\n\n")
git(["-C", str(path), "add", "README.md"])
commit_dated(path, "docs: add FAQ section", "3d")
# Working tree changes - large diff using shared fixture
shutil.copy(FIXTURES_DIR / "alpha-readme.md", path / "README.md")
(path / "scratch.rs").write_text("// scratch\n")
def _create_branch_beta(env: DemoEnv):
"""Create beta branch with staged changes and remote tracking."""
branch = "beta"
path = env.work_base / f"acme.{branch}"
git(["-C", str(env.repo), "checkout", "-q", "-b", branch, "main"])
git(["-C", str(env.repo), "push", "-u", "origin", branch, "-q"])
git(["-C", str(env.repo), "checkout", "-q", "main"])
git(["-C", str(env.repo), "worktree", "add", "-q", str(path), branch])
# Staged new file
(path / "notes.txt").write_text("# TODO\n- Add caching\n")
git(["-C", str(path), "add", "notes.txt"])
def _create_branch_hooks(env: DemoEnv):
"""Create hooks branch with refactored lib.rs, no remote."""
branch = "hooks"
path = env.work_base / f"acme.{branch}"
git(["-C", str(env.repo), "checkout", "-q", "-b", branch, "main"])
shutil.copy(FIXTURES_DIR / "lib-hooks.rs", env.repo / "src" / "lib.rs")
git(["-C", str(env.repo), "add", "src/lib.rs"])
commit_dated(env.repo, "feat: add math operations, consolidate tests", "2H")
# No push - no upstream
git(["-C", str(env.repo), "checkout", "-q", "main"])
git(["-C", str(env.repo), "worktree", "add", "-q", str(path), branch])
# Staged then modified
lib_rs = path / "src" / "lib.rs"
lib_rs.write_text(lib_rs.read_text() + "// Division coming soon\n")
git(["-C", str(path), "add", "src/lib.rs"])
lib_rs.write_text(lib_rs.read_text() + "// TODO: add division\n")
# =============================================================================
# Demo recording infrastructure
# =============================================================================
def check_dependencies(commands: list[str]):
"""Check that required commands are available, exit if not."""
for cmd in commands:
if not shutil.which(cmd):
raise SystemExit(f"Missing dependency: {cmd}")
def _ffmpeg_draws_subtitles(ffmpeg: str) -> bool:
"""Whether this ffmpeg was built with libass, i.e. has the `ass` filter."""
result = subprocess.run([ffmpeg, "-filters"], capture_output=True, text=True)
return " ass " in result.stdout
def check_ffmpeg_libass():
"""Put an ffmpeg that can draw subtitles on PATH, for the keystroke overlay.
Homebrew ships two builds: `ffmpeg` is the one linked onto PATH and is
built without libass, while `ffmpeg-full` carries it and stays unlinked —
so installing ffmpeg at any point silently takes the overlay away again.
VHS shells out to plain `ffmpeg`, so when the linked build can't draw
subtitles this puts the full one in front of it for the rest of the build.
Worth doing rather than telling the user to fix their PATH: the failure
lands at the very end of a recording, as an ffmpeg filter-graph parse
error naming the subtitle file, minutes after the work that produced it.
"""
ffmpeg = shutil.which("ffmpeg")
if ffmpeg and _ffmpeg_draws_subtitles(ffmpeg):
return
# Ask brew only where there is one: `subprocess.run` on a missing program
# raises rather than returning non-zero, which would replace the message
# below with a traceback on any box without Homebrew.
if shutil.which("brew"):
full = subprocess.run(
["brew", "--prefix", "ffmpeg-full"], capture_output=True, text=True
)
candidate = (
Path(full.stdout.strip()) / "bin" / "ffmpeg" if full.returncode == 0 else None
)
if candidate and candidate.exists() and _ffmpeg_draws_subtitles(str(candidate)):
os.environ["PATH"] = f"{candidate.parent}{os.pathsep}{os.environ['PATH']}"
return
raise SystemExit(
"No ffmpeg with libass support (required for the keystroke overlay).\n"
"Install with: brew install ffmpeg-full"
)
def write_starship_config(path: Path, theme: str) -> None:
"""Write the starship fixture plus its ``site`` palette for ``theme``."""
palette = PALETTES[theme]
path.write_text(f"""{(FIXTURES_DIR / "starship.toml").read_text()}
[palettes.site]
craft = "{palette['--wt-craft']}"
muted = "{palette['--wt-ink-muted']}"
red = "{palette['--wt-terminal-red']}"
""")
def setup_demo_output(env: DemoEnv) -> None:
"""Set up demo output directory and write the starship config."""
env.out_dir.mkdir(parents=True, exist_ok=True)
write_starship_config(env.starship_config, env.theme)
def record_text(
demo_env: DemoEnv,
tape_path: Path,
output_txt: Path,
replacements: dict,
repo_root: Path,
vhs_binary: str = "vhs",
) -> None:
"""Record text output by rendering tape via VHS.
Uses VHS with .txt output to capture authentic shell session including
real prompts and command output.
Args:
demo_env: Demo environment
tape_path: Path to VHS tape file
output_txt: Path to write text output
replacements: Template variable replacements
repo_root: Root of the repository (for resolving Source paths)
vhs_binary: VHS binary to use
Raises:
subprocess.CalledProcessError: If VHS fails
RuntimeError: If VHS succeeds but output file not created
"""
# Render tape with variable substitution
rendered = render_tape(tape_path, replacements, repo_root)
if not rendered:
raise RuntimeError(f"Failed to render tape: {tape_path}")
# Modify for text output
temp_txt = (demo_env.out_dir / ".text-output.txt").resolve()
rendered = re.sub(
r'^Output\s+"[^"]+"', f'Output "{temp_txt}"', rendered, flags=re.MULTILINE
)
rendered = re.sub(r"^Set Width .*$", "Set Width 120", rendered, flags=re.MULTILINE)
rendered = re.sub(
r"^Set Height .*$", "Set Height 120", rendered, flags=re.MULTILINE
)
for setting in ["FontSize", "Theme", "Padding"]:
rendered = re.sub(rf"^Set {setting} .*$\n?", "", rendered, flags=re.MULTILINE)
# Write and run
tape_rendered = (demo_env.out_dir / ".text-rendered.tape").resolve()
tape_rendered.write_text(rendered)
try:
run(
[vhs_binary, str(tape_rendered)],
check=True,
env=_isolated_claude_env(demo_env.home),
)
finally:
tape_rendered.unlink(missing_ok=True)
if not temp_txt.exists():
raise RuntimeError(f"VHS succeeded but output file not created: {temp_txt}")
shutil.copy(temp_txt, output_txt)
temp_txt.unlink()
def extract_commands_from_tape(
tape_path: Path, repo_root: Path, command_prefixes: tuple[str, ...] = ("wt", "git")
) -> list[str]:
"""Extract shell commands from a VHS tape file.
Parses the tape looking for Type "command" followed by Enter patterns,
filtering to commands that start with specified prefixes (default: wt, git).
Only extracts commands executed after a Show directive (visible part of
demo). A command may be typed while hidden to make a complete command the
first frame, provided its Enter occurs after Show. Skips commands executed
in Hide blocks.
Args:
tape_path: Path to the .tape template file
repo_root: Root of the repository (for resolving Source paths)
command_prefixes: Tuple of command prefixes to extract (default: wt, git)
Returns:
List of commands in order they appear in the tape
"""
# Render tape with dummy replacements to inline Source directives
rendered = render_tape(tape_path, {}, repo_root)
if not rendered:
return []
commands = []
in_visible_section = False
pending_command = None
lines = rendered.split("\n")
for raw_line in lines:
line = raw_line.strip()
# Track visibility
if line == "Show":
in_visible_section = True
continue
elif line == "Hide":
in_visible_section = False
continue
if line.startswith("Type "):
match = re.match(r'Type\s+["\'](.+)["\']', line)
if match:
pending_command = match.group(1)
continue
if line == "Enter":
if (
in_visible_section
and pending_command
and any(
pending_command.startswith(prefix) for prefix in command_prefixes
)
):
commands.append(pending_command)
pending_command = None
continue
if line and not line.startswith(("#", "Sleep ")):
# Interactive editing or completion means the literal Type text is
# not the command that Enter will execute. Snapshot mode cannot
# replay those terminal interactions faithfully.
pending_command = None
return commands
def record_snapshot(
demo_env: "DemoEnv",
tape_path: Path,
output_snap: Path,
repo_root: Path,
) -> None:
"""Record command output snapshot for regression testing.
Extracts commands from the tape and runs them in a fish shell with full
shell integration (just like the GIF demos). The snapshot format is:
$ wt list
<output>
$ wt switch alpha
<output>
This captures semantic output (what commands produce) rather than visual
rendering (how it looks in a terminal). Small diffs are expected when
output formats change; the goal is catching unexpected regressions like
new hints or warnings creeping in.
Args:
demo_env: Demo environment with repo and home paths
tape_path: Path to the .tape template file
output_snap: Path to write snapshot output
repo_root: Root of the repository
Raises:
RuntimeError: If no commands found in tape
"""
commands = extract_commands_from_tape(tape_path, repo_root)
if not commands:
raise RuntimeError(f"No snapshotable commands found in {tape_path.name}")
# Build environment matching the GIF demos
env = _isolated_claude_env(demo_env.home)
env.update(
{
"PATH": f"{repo_root / 'target' / 'debug'}:{demo_env.home / '.local' / 'bin'}:{os.environ.get('PATH', '')}",
"TERM": "xterm-256color",
"LANG": "en_US.UTF-8",
"LC_ALL": "en_US.UTF-8",
"GIT_PAGER": "", # Plain text output, no delta formatting
# Pin what the snapshot's shape depends on. The commands run without
# a terminal, so `wt` falls back to `COLUMNS` for width and drops
# color; both would otherwise come from whatever shell invoked the
# build, and a snapshot that reflows with the recorder's window
# can't show that a hint crept in.
"COLUMNS": "80",
"CLICOLOR_FORCE": "1",
}
)
env.pop("NO_COLOR", None)
# Generate a fish script that:
# 1. Initializes shell integration (like shared-commands.tape)
# 2. Runs each command, printing "$ cmd" before and blank line after
script_lines = [
"# Initialize shell integration",
"wt config shell init fish | source",
"source ~/.config/fish/completions/wt.fish",
f"cd {demo_env.repo}",
"",
]
for i, cmd in enumerate(commands):
# Echo the command prompt, run command (merging stderr)
script_lines.append(f"echo '$ {cmd}'")
script_lines.append(f"{cmd} 2>&1")
# Blank line between commands (not after last)
if i < len(commands) - 1:
script_lines.append("echo ''")
script_content = "\n".join(script_lines)
script_path = demo_env.out_dir / ".snapshot-script.fish"
script_path.write_text(script_content)
# Run the script in fish
result = subprocess.run(
["fish", str(script_path)],
env=env,
capture_output=True,
text=True,
)
# Combine stdout and stderr
output = (result.stdout + result.stderr).rstrip()
# Normalize temp paths to stable placeholder
temp_path = str(demo_env.out_dir)
temp_path_real = str(demo_env.out_dir.resolve())
output = output.replace(temp_path_real, "<DEMO_DIR>")
output = output.replace(temp_path, "<DEMO_DIR>")
# Write snapshot
output_snap.parent.mkdir(parents=True, exist_ok=True)
output_snap.write_text(output + "\n")
@dataclass
class DemoSize:
"""Canvas and font size for demo recording."""
width: int
height: int
fontsize: int
# Predefined sizes for different contexts
SIZE_SOCIAL = DemoSize(width=1200, height=700, fontsize=26) # Big text for mobile
SIZE_DOCS = DemoSize(width=1600, height=900, fontsize=24) # More content for docs
SIZE_DOCS_MOBILE = DemoSize(width=576, height=432, fontsize=20)
# The picker demo trades text size for terminal size, on the same canvas as the
# rest: 139x34 rather than 102x25. It is the one demo whose subject is a table
# and a preview pane side by side, and the columns it loses first are the ones
# worth watching — at 102 columns the CI status and the branch summary fall off
# the right edge, and the preview pane is too short to page a diff through.
SIZE_DOCS_PICKER = DemoSize(width=1600, height=900, fontsize=18)
def build_tape_replacements(demo_env: DemoEnv, repo_root: Path) -> dict:
"""Build template variable replacements for tape rendering.
Used by both GIF recording and text recording to ensure consistency.
All paths are resolved to absolute paths for VHS compatibility.
Tapes use Source directives for shared content:
- Source shared-setup.tape: VHS Set directives (at top, before Output)
- Source shared-commands.tape: Env vars and shell setup (after Require)
"""
return {
"DEMO_REPO": demo_env.repo.resolve(),
"DEMO_HOME": demo_env.home.resolve(),
"REAL_HOME": REAL_HOME,
"STARSHIP_CONFIG": demo_env.starship_config.resolve(),
"TARGET_DEBUG": (repo_root / "target" / "debug").resolve(),
"ANTHROPIC_API_KEY": os.environ.get("ANTHROPIC_API_KEY", ""),
"CLAUDE_CODE_OAUTH_TOKEN": os.environ.get("CLAUDE_CODE_OAUTH_TOKEN", ""),
"GIT_PAGER": "", # Overridden by record_theme
}
def record_theme(
demo_env: "DemoEnv",
tape_template: Path,
output_gif: Path,
repo_root: Path,
vhs_binary: str = "vhs",
size: DemoSize = None,
):
"""Record one demo GIF in a prepared environment, in the environment's theme.
Args:
demo_env: Prepared demo environment for this theme
tape_template: Path to the .tape template file
output_gif: Output GIF path
repo_root: Path to worktrunk repo root (for target/debug)
vhs_binary: VHS binary to use (default "vhs", can be path to custom build)
size: Canvas and font size (default SIZE_DOCS)
"""
if size is None:
size = SIZE_DOCS
tape_rendered = demo_env.out_dir / ".rendered.tape"
delta_flags = "delta --paging=never"
if demo_env.theme == "light":
delta_flags += " --light"
replacements = {
**build_tape_replacements(demo_env, repo_root),
"OUTPUT_GIF": output_gif,
"THEME": format_theme_for_vhs(THEMES[demo_env.theme]),
"WIDTH": size.width,
"HEIGHT": size.height,
"FONTSIZE": size.fontsize,
"GIT_PAGER": delta_flags,
}
rendered = render_tape(tape_template, replacements, repo_root)
if not rendered:
return
tape_rendered.write_text(rendered)
print(f"\nRecording {demo_env.theme} GIF...")
record_vhs(tape_rendered, vhs_binary, expected_output=output_gif)
tape_rendered.unlink(missing_ok=True)
print(f"GIF saved to {output_gif}")