feat(local-dev): deploy from a sibling git worktree via up --worktree/--branch

[Yicong-Huang]

What changes were proposed in this PR?

bin/local-dev.sh can now build and run the stack from a sibling git worktree while the orchestration tooling itself always runs from the canonical checkout.

The key split is SELF_ROOT (where local-dev.sh, tui.py, and the docker overlay live — the tooling) vs SOURCE_ROOT (the application tree that gets built/run, which REPO_ROOT now points at).

• up / auto accept --worktree=PATH or --branch=NAME (resolved to the worktree that has the branch checked out). A plain up returns to this checkout.
• The selection persists to $STATE_DIR/deploy-source, so status / down / logs / single-service rebuild / auto all act on the active deployment. up re-marks the deploy target (branch / sha / worktree) at startup, and status --json gains "worktree" and "source" fields.
• Build stamps are namespaced per source tree (sha1 of the absolute path), so switching worktrees can't let a stamp from tree A suppress the required first build of tree B.
• Infra docker compose / .env / overlay stay pinned to the canonical checkout (orchestration), while the app schema/DDL still comes from the deployed source.
• The interactive TUI mirrors the CLI: u / a accept the same selectors, and the banner + SRC-dirty column re-point to the active tree live (the shell exports TEXERA_DEPLOY_SOURCE; the TUI re-reads the persisted pointer after a switch).
• Invalid --branch / --worktree fail fast with a clear, actionable message before anything is built or started.

Any related issues, documentation, discussions?

Closes #6030. The --help text and the in-TUI help (h) document the new selectors.

How was this PR tested?

Extended both existing local-dev test suites (all green):

• bin/local-dev/tests/test_local_dev_sh.sh — 25 checks (6 new): --help documents the selectors; status --json carries worktree/source; a stale pointer is dropped and falls back to self; a valid pointer to a throwaway worktree (created and cleaned up in-test) is honored and reports its branch; invalid --branch and --worktree fail fast with rc=1.
• bin/local-dev/tests/test_local_dev_tui.py — 43 checks (5 new): _stamp_dir_for matches the shell's sha1(path)[:12] namespacing; _resolve_deploy_source returns self when the pointer is missing/stale/points at a non-checkout, and the worktree when valid.

Run:

bash bin/local-dev/tests/test_local_dev_sh.sh
python3 -m pytest bin/local-dev/tests/test_local_dev_tui.py -q

Also verified manually that status --json against a persisted worktree pointer reports that worktree's branch/sha/source, and that bash -n / py_compile pass.

Was this PR authored or co-authored using generative AI tooling?

Generated-by: Claude Opus 4.8 (Claude Code)

[github-actions]

Automated Reviewer Suggestions

Based on the git blame history of the changed files, we recommend the following reviewers:

• No candidates found from git blame history.

[Copilot]

Copilot wasn't able to review any files in this pull request.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Copilot wasn't able to review any files in this pull request.

[Yicong-Huang]

@mengw15 could you please help on review? thanks

[Copilot]

Copilot wasn't able to review any files in this pull request.

[mengw15]

LGTM, left one forward-looking note

[mengw15]

The intentional split (SOURCE_ROOT for app, SELF_ROOT for infra) is the right call for the common case — 95% of PRs only touch app code and this is a huge quality-of-life win. But it silently deposits a real footgun for the other 5%:

• PR adds a new docker service (Redis, ClickHouse, etc.) in its compose file → deployed stack silently misses it (self's compose wins)
• PR adds a required env var → app starts, hits NPE at runtime (self's .env has no such var)
• PR adds a new backend service to the SERVICES=(...) array in main.sh → self's main.sh never launches it
• PR is itself a tooling change (like this PR) → self's tooling doesn't have the change under test

Worth surfacing this boundary to the user. Two lightweight options:

1. Add a note in --help (and the TUI ? help): "--worktree / --branch assumes the target only differs in app code — if it modifies bin/local-dev/**, bin/single-node/**, docker-compose*, or .env, checkout that branch and run its own local-dev.sh instead."
2. At startup of up --worktree=..., diff -q $SELF_ROOT/bin/local-dev/ $SOURCE_ROOT/bin/local-dev/ (same for bin/single-node/) and print a one-line warn if there's drift. Non-fatal, just informational.

Not blocking — the design is sound and the failure modes are recoverable. Just want future users to have a chance to notice the boundary before they burn 30 minutes debugging.