chore(preview): add a Local Studio (dev:local) worktree preview config

[dawsontoth]

⊙ Problem

The worktree preview launcher (.claude/preview-worktree.sh) always ran pnpm run dev (Fabric mode), so preview_start could not serve a worktree in Local Studio mode (dev:local) against a local Harper instance — useful when central-manager is unavailable or when testing Local Studio itself. Closes #1638.

❓ Your call: is a second named launch config the right shape? I followed the issue's proposal (two configs, mode chosen by name) rather than its "nice-to-have" of reading the script from a gitignored file like .claude/preview-cwd. Two configs are discoverable in the preview picker and need no per-worktree setup; a gitignored file would allow per-worktree defaults but is invisible state. Easy to switch later — the script argument stays either way.

💡 Solution

.claude/preview-worktree.sh now takes an optional first argument naming the package.json script to run, defaulting to dev, and passes it quoted to pnpm run (the [preview] Serving … line now names the script too). The existing studio (worktree) config passes no argument, so it behaves exactly as before. In .claude/launch.json, a new studio local (worktree) config passes dev:local, and the script's usage header names it. Both bind port 5173, so only one can run at a time.

dev:local layers .github/deploy-public-env/.env.dev-local (VITE_LOCAL_STUDIO=true) over .env.local, so it only needs VITE_LOCAL_STUDIO_DEV_URL pointing at a running Harper instance (.env.local.example defaults it to http://localhost:9925).

Also fixed: the script's comments (header, inline) said it falls back to the main checkout when .claude/preview-cwd is absent. It actually falls back to $root ($CLAUDE_PROJECT_DIR, i.e. the checkout it was launched from, which is the worktree itself when a session runs in one). Comment-only.

✅ Verification

Route: live smoke of the launcher, without touching port 5173 (other sessions may hold it).

• Argument dispatch, with a stub npm first on PATH so nothing binds a port: no argument and an empty argument both ran pnpm run dev → npm run dev:fabric with VITE_LOCAL_STUDIO unset; dev:local ran the real dotenv -e .github/deploy-public-env/.env.dev-local -e .env.local -- npm run vite-host with VITE_LOCAL_STUDIO=true and VITE_LOCAL_STUDIO_DEV_URL=http://localhost:9925; an unknown name (nope) failed fast with pnpm's Missing script: nope, exit 1. Re-run on the final commit for the default and dev:local cases.
• Real server, with an npm shim that only appends --port 5199 --strictPort to vite-host: bash .claude/preview-worktree.sh dev:local started Vite 8.3.2 on 5199, / returned 200, and the served src/config/constants.ts carried "VITE_LOCAL_STUDIO": "true". Server stopped afterwards; 5199 confirmed free.
• jq parses .claude/launch.json (3 configurations); bash -n clean (shellcheck is not installed here).
• Gates: npx dprint check exit 0 (covers launch.json; .sh is outside dprint's scope), npx oxlint exit 0. The pre-commit hook ran the full vitest suite (395 files, 3,663 passed, 11 skipped), lint, format and commitlint. No TypeScript changed, so tsc -b is unaffected. One hook run hit a 30s timeout in the unrelated src/lib/monaco/editorApi.test.ts under machine load; it passed alone in 2.6s and the retried hook was green.
• Cross-model review: one full round, codex (graded) and gemini both ran; their only finding was the same comment nit on the new usage paragraph, which I trimmed to one line. The Cursor leg failed no-receipt (1Password SSH agent refused to sign its git fetch) and the Harper domain adjudicator failed auth (expired Claude OAuth session), so outside findings were not adjudicated — an environment gap, not an open finding.

🤖 Generated with Claude Code

_{🤖 Generated by Claude Code (Claude Opus 5.5); posted via @dawsontoth.}

Related PRs: none found
Complexity: easy

_{Review-Coverage: authored=claude; ran=gemini,codex; blocked=cursor-composer(no-receipt),domain(auth); declined=cursor-grok,cursor-kimi,cursor-muse; rounds=1; full=1 @ cb254e7}

_{Review-Attention: read ~3m (raised: degraded review) @ cb254e7}

[gemini-code-assist]

Code Review

This pull request introduces a new 'studio local (worktree)' launch configuration and updates the '.claude/preview-worktree.sh' script to accept a custom dev script argument (defaulting to 'dev'), enabling support for Local Studio mode via 'dev:local'. The feedback suggests enhancing the script's flexibility by forwarding any additional command-line arguments to the underlying 'pnpm run' command.

[gemini-code-assist]

To make the preview script more flexible, consider forwarding any additional arguments passed to the script (such as --force or other Vite flags) to the underlying pnpm run command. This can be achieved cleanly by appending "${@:2}" to the pnpm run command, which safely expands to all arguments starting from the second one (or nothing if none are provided).

Suggested change

	exec pnpm --config.verify-deps-before-run=false run "$dev_script"
	exec pnpm --config.verify-deps-before-run=false run "$dev_script" "${@:2}"

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	67.53%	10099 / 14953
🔵	Statements	67.69%	10777 / 15920
🔵	Functions	60.78%	2599 / 4276
🔵	Branches	62.53%	7685 / 12289

File Coverage

No changed files found.

Generated in workflow #2064 for commit cb254e7 by the Vitest Coverage Report Action