rudder-worktree-preview-maintainer

Rudder Worktree Preview Maintainer

Run the current Rudder checkout as a temporary preview so the user can inspect the feature in a browser without leaving a foreground command running.

This skill is for the common post-implementation hand-off: the branch already contains the work, and the user wants a local URL to test. It is not a PR checkout workflow, it is not a broad process cleanup workflow, and it is not the canonical developer environment for Codex-managed worktrees.

Rudder's normal pnpm dev entrypoint is the canonical development path. In Codex-managed worktrees under ~/.codex/worktrees/<id>/<repo>, pnpm dev auto-derives an isolated RUDDER_HOME, instance id, server port, embedded PostgreSQL port, and worktree branding when no repo-local .rudder/ config exists. Use this preview skill only when the user wants a managed background preview handoff with health verification, logs, and a stop command.

Preview readiness is environment proof, not product proof. A healthy URL means the checkout can be opened; it does not prove that a feature, workflow, agent path, or UI regression is fixed. When this skill is used inside a lifecycle handoff or review gate, the owning workflow must still exercise the relevant route, command, agent run, or Desktop/browser interaction and report the observed terminal state.

Use This Skill When

• The user asks to run the current branch or current worktree locally.
• The user wants to manually test a recently implemented UI or workflow change.
• The assistant needs to hand off a stable preview URL after implementation without leaving pnpm dev in the foreground.
• The user asks for logs, a stop command, or a temporary preview that can be cleaned up independently.
• The task is to provide a preview URL, not to package Desktop or publish a release.

Do Not Use This Skill When

• The user asks to check out or preview a GitHub PR; use pr-local-preview-maintainer instead.
• The user asks only to stop or clean local dev processes; use stop-rudder-dev-maintainer instead.
• The user is asking why Codex worktrees interfere, how normal development should be isolated, or whether pnpm dev is using the current worktree. In that case inspect scripts/dev-local-env.mjs, doc/engineering/DEVELOPING.md, and the /api/health payload for the active dev runtime.
• The user simply wants to develop inside the current Codex worktree. Use pnpm dev, which should auto-isolate Codex-managed worktrees, instead of starting a separate /tmp/rudder-worktree-preview instance.
• The change needs packaged Desktop verification; follow the Desktop validation workflow in the repo docs.
• The user wants production-like pnpm prod behavior rather than a dev preview.

Default Workflow

1. Inspect the current worktree

Start from the repository root and record the current branch:

git status --short --branch
git branch --show-current

Do not switch branches, reset files, or stop unrelated runtimes. A dirty worktree is normal after implementation work.

2. Choose isolated runtime settings

The preview is intentionally temporary and may use a different instance than the canonical pnpm dev runtime for the same worktree. Tell the user this if they are comparing data between surfaces.

Prefer a branch-derived instance id, a non-default app port, and an isolated RUDDER_HOME under /tmp:

RUDDER_INSTANCE_ID=<branch-slug>
PORT=<free-port>
RUDDER_HOME=/tmp/rudder-worktree-preview/<branch-slug>/home

Use 3100 only when the user explicitly asks for the default dev runtime and the port is free. Otherwise choose a free port starting near 3310.

If the user wants the same data and instance as their normal Codex worktree development surface, do not use this launcher by default. Start or inspect pnpm dev instead and verify the /api/health response matches the expected worktree-derived instance id.

If embedded PostgreSQL works, use a free RUDDER_EMBEDDED_POSTGRES_PORT. If embedded PostgreSQL fails in the local environment, use a dedicated external database for this preview instead of reusing another Rudder instance's database.

3. Use the bundled launcher first

From the repo root:

bash .agents/skills/maintainer/rudder-worktree-preview-maintainer/scripts/start_current_branch_preview.sh

The launcher:

• derives an instance id from the current branch
• finds free app and embedded PostgreSQL ports
• starts @rudderhq/server with Vite dev middleware
• uses tmux when available, then launchctl on macOS
• waits for /api/health
• prints the URL, logs, and stop command

Useful options:

bash .agents/skills/maintainer/rudder-worktree-preview-maintainer/scripts/start_current_branch_preview.sh --replace
bash .agents/skills/maintainer/rudder-worktree-preview-maintainer/scripts/start_current_branch_preview.sh --port 3312
bash .agents/skills/maintainer/rudder-worktree-preview-maintainer/scripts/start_current_branch_preview.sh --database-url postgres://user:pass@127.0.0.1:5432/dbname
bash .agents/skills/maintainer/rudder-worktree-preview-maintainer/scripts/start_current_branch_preview.sh --stop

Use --replace only for the same branch-derived preview session. Do not kill ports or process groups that belong to another Rudder worktree.

4. Handle startup failures pragmatically

If readiness fails, inspect the managed logs before responding:

tmux capture-pane -pt rudder-preview-<instance-id> -S -180
tail -180 /tmp/rudder-worktree-preview/<instance-id>/*.log

Fix local startup issues that are clearly environmental, such as occupied ports or missing dependencies. If embedded PostgreSQL fails, create or use an isolated external database and rerun with --database-url; do not point the preview at the user's main dev data unless they explicitly ask for that.

5. Verify readiness

Before handing off, check:

curl -fsS http://127.0.0.1:<port>/api/health

The instanceId in the response should match the preview instance id. If it does not, the URL may belong to another runtime.

For visible UI work, also open the URL in a browser when practical. If browser automation is unavailable or hangs, say that clearly and still provide the health-checked URL.

If the user asked whether a feature works, do not stop at this readiness check. Run or hand back the concrete scenario proof needed for that feature, and label the preview URL as only the environment that made the proof possible.

6. Hand off the preview

Keep the response short and concrete:

当前分支已经跑起来了：
http://127.0.0.1:<port>

实例：<instance-id>
日志：<tmux attach or log path>
停止：<stop command>
Health check passed.

Mention when the preview uses a non-default port because 3100 is occupied. Mention when the database is isolated or temporary so the user knows what data they are looking at.

Cleanup Requests

For cleanup, stop only the managed preview for the current branch:

bash .agents/skills/maintainer/rudder-worktree-preview-maintainer/scripts/start_current_branch_preview.sh --stop

Verify the preview port is free afterward. Do not remove worktrees, delete databases, or stop other Rudder sessions unless the user explicitly asks.

Judgment Rules

• Isolation matters more than preserving the default port.
• Do not present this skill as the fix for Codex worktree isolation. That belongs in the default pnpm dev environment resolution.
• Be explicit when this preview uses a temporary /tmp instance that differs from the normal pnpm dev instance for the same checkout.
• A health-checked URL is the minimum hand-off; logs and a stop command make it usable.
• Do not present preview readiness as review or validation of the changed workflow unless a separate scenario was exercised and reported.
• Never stop unrelated Rudder sessions just because they occupy 3100.
• Do not leave a foreground command running when the user needs a preview after the assistant turn ends; use tmux or a user-level managed process.
• If the task shifts from previewing to fixing a startup bug, say that and keep source edits scoped.