18 added, 8 removed. Audit A to A.
---
name: run-wenlan-app
description: Build, launch, screenshot, and drive the wenlan-app Tauri desktop app in dev mode on macOS. Use when asked to run or start the app, verify a UI change in the real running app (not just tests), or take a screenshot of it.
---
# Run wenlan-app (dev)
Tauri 2 desktop app (Rust `app/` + React/Vite frontend on :1420). Drive it
with `.claude/skills/run-wenlan-app/driver.sh` — all paths below are relative
- to the unit root (repo or worktree root). macOS host only; the daemon the app
- talks to is the user's live `wenlan-server` on `:7878` — **never kill it,
- never run `pnpm clean:dev`** (that would restart it).
+ to the unit root (repo or worktree root). macOS host only.
+ A debug build refuses to start without a complete isolated runtime identity
+ (`validate_debug_runtime_isolation` in `app/src/lib.rs`), so `launch` takes the
+ worktree-scoped config from `scripts/dev-runtime.sh` and starts its **own**
+ daemon on the worktree port. The user's live `wenlan-server` on `:7878` is
+ never the daemon under test and **must never be killed**; `stop` only ends the
+ daemon this worktree recorded.
+
## Prerequisites
- `pnpm install` done in the unit root (worktrees start without `node_modules`).
- Sibling backend checkout at `../wenlan` of the **main** checkout, or
`WENLAN_BACKEND_DIR` set. The driver defaults both this and
`CARGO_TARGET_DIR` to the main checkout (warm ~14G cargo cache) via
`git rev-parse --git-common-dir`, so worktrees work out of the box.
- Terminal needs macOS Screen Recording permission (for `shot`).
## Run (agent path)
```bash
.claude/skills/run-wenlan-app/driver.sh build # sidecars + cargo build (decoupled from tauri dev)
- .claude/skills/run-wenlan-app/driver.sh launch # vite up + launch target/debug/wenlan-app directly → "APP UP"
+ .claude/skills/run-wenlan-app/driver.sh launch # isolated daemon + vite up + launch target/debug/wenlan-app directly → "APP UP"
.claude/skills/run-wenlan-app/driver.sh shot /tmp/shot.png # window PNG, works while occluded
- .claude/skills/run-wenlan-app/driver.sh stop # kills only the dev app + vite, never :7878
+ .claude/skills/run-wenlan-app/driver.sh stop # kills only the dev app, vite, and this worktree's daemon; never :7878
```
Logs land in `$TMPDIR/wenlan-app.log` and `$TMPDIR/wenlan-vite.log`.
**Look at the screenshot** after `shot` — a blank frame means the frontend
did not load.
### Driving UI state
Synthetic events (`CGEvent.postToPid`) are **not handled** by Tauri's
WKWebView, and global coordinate clicks are forbidden here (other live agent
sessions share this desktop; a stray click once hit the updater's Install
button and it consumed `target/debug/wenlan-app`). Instead, drive UI state
through **vite HMR**: make a temporary `import.meta.env.DEV`-guarded edit
(e.g. force a section expanded, early-return a toast), wait ~3s, `shot`,
revert the edit. Mark such edits `// TEMP (do not commit)`.
## Run (human path)
- `pnpm dev:all` — full chain including daemon restart. Useless for agents
- (restarts the user's daemon) and `pnpm tauri dev` alone dies on cold caches
- (see Gotchas). Ctrl-C to stop.
+ `pnpm dev:all` — the supported entry point: an isolated worktree daemon plus
+ `pnpm tauri dev` with a dev bundle identifier and the worktree UI port. Agents
+ use `driver.sh` instead because `tauri dev` dies on cold caches (see Gotchas).
+ Ctrl-C to stop.
## Test
`pnpm test` (Vitest), `cd app && cargo test`.
## Gotchas
- **`launch` must run unsandboxed.** The app inherits the shell's seatbelt
sandbox, which denies the mach lookup for the ViewBridge XPC service behind
`NSOpenPanel`. The app starts fine and then hard-crashes on the *first*
file/folder picker — `+[NSOpenPanel openPanel]` returns NULL and objc2
panics — hours after launch, looking exactly like a product bug. It is not:
the same call returns a panel normally outside the sandbox. `launch` now
refuses when it detects a sandboxed shell (canary: `pbpaste`).
- `tauri dev` compiles sidecars inside `beforeDevCommand`, then waits only
180s for vite — on a cold cache it dies with
`Error Could not connect to `http://localhost:1420/` after 180s`.
The driver decouples: sidecars → vite → `cargo build` → direct launch.
- `app/Cargo.toml` has `default = []` (no `custom-protocol`), so a plain
debug `cargo build` produces the dev binary that loads `devUrl` :1420.
+ That URL is baked in at build time and no runtime env var overrides it, so
+ `driver.sh vite` pins vite to :1420 even though the isolated runtime config
+ also carries a worktree-scoped `WENLAN_DEV_UI_PORT` (which `pnpm dev:all`
+ does use, since the tauri CLI can rewrite `devUrl` via `--config`).
- `scripts/resolve-backend-dir.sh` fallbacks don't reach worktrees under
`.claude/worktrees/<name>` (3 levels deep) — the driver exports
`WENLAN_BACKEND_DIR` explicitly.
- The dev updater toast covers the lower-left sidebar and its Install button
is live. Never click it. Suppress during verification with a TEMP
`if (import.meta.env.DEV) return null;` at the top of
`src/components/UpdaterDialog.tsx`.
- The app owns a secondary ~500×500 window; `wincap.swift` sorts by area to
capture the main one.
- Full-screen `screencapture` shows whatever is frontmost — on a desktop with
a live user this races window focus. `shot` uses ScreenCaptureKit's
desktop-independent window capture instead.
## Troubleshooting
- `initializing rolling file appender failed ... PermissionDenied` in the app
log → the binary was spawned through a sandboxed pnpm/tauri chain; launch
`target/debug/wenlan-app` directly (what `driver.sh launch` does).
- `could not create image from window` / `could not create image from rect`
from `screencapture -l`/`-R` → use `driver.sh shot`.
- `Assertion failed: (did_initialize), function CGS_REQUIRE_INIT` from a
Swift capture script → touch `NSApplication.shared` before creating an
`SCContentFilter` (already done in `wincap.swift`).
- `failed to restart app: No such file or directory` after an updater
Install → the updater consumed the dev binary; rebuild with
`driver.sh build`.
- `vitest: command not found` in a fresh worktree → `pnpm install`.