openbridge-debug

name	openbridge-debug
description	Debug and validate OpenBridge on a real macOS desktop through mini-machine plus full VNC computer-use. Use when local broker automation is not enough, when you need end-to-end GUI verification on macOS, or when local changes should be pushed to a branch and rebuilt from a fresh machine clone instead of transferred manually.

OpenBridge Debug via Mini-Machine

This skill replaces the old local OpenBridge automation MCP flow.

Use a remote macOS machine plus full computer-use instead:

• machine.sh creates/lists/gets/stops mini-machine sessions and requires a request description for each new machine.
• publish_branch_for_machine.sh snapshots local changes to a git branch so the remote Mac can build them directly; a local compile pass is optional, not required.
• rerun_setup_on_machine.sh reruns setup on an already-running machine so OpenBridge reopens with the updated branch after you push.
• setup_bridge_on_machine.sh clones OpenBridge on the remote Mac, builds OpenBridge, and opens the app.
• vnc is the actual computer-use tool for screenshots, clicks, typing, keys, and scroll.

Prerequisites

From the local machine:

gh auth status
python3 -m pip install --user --break-system-packages vnc-computer-use   # if `vnc` is missing

If your Python install is externally managed and you do not want --break-system-packages, install vnc-computer-use with a virtualenv or pipx instead.

You need repo + workflow scopes for gh.

For private repo clone inside the remote macOS machine, use one of these:

1. gh auth login on the machine.
2. Export CUEBOARD_GH_TOKEN on the machine before cloning.
3. Export CUEBOARD_REPO_URL to a clone URL the machine can access.

Default workflow

You do not need a successful local build before creating or using a machine. A remote machine build can be your first compile/validation pass; a local build is only an optional preflight when you want faster feedback before pushing.

1. If local changes are not pushed yet, publish them to a branch (local compile optional)

If you want a quick local preflight before pushing, run from the repo root:

cd web && yarn install --immutable && yarn build:embedded
cd ../macos && BUILD_CONFIGURATION=UnsignedDebug bash DevKit/Scripts/workspace_build_debug.sh

If you do not need the local preflight, skip straight to the publish step. In either case, push the branch snapshot so the remote Mac can do the compile/validation pass:

macos/DevKit/skill/publish_branch_for_machine.sh \
  --message "wip: describe the current OpenBridge fix" \
  --branch your-branch-name

That prints the matching machine-side setup command.

1b. When a machine is already running and you want the updated OpenBridge there quickly

After you push the latest branch snapshot, run:

macos/DevKit/skill/publish_branch_for_machine.sh \
  --branch your-branch-name \
  --message "wip: describe the latest OpenBridge change"

macos/DevKit/skill/rerun_setup_on_machine.sh \
  --run-id <run-id> \
  --branch your-branch-name

If the branch is already committed and clean locally, omit --message from the publish step.

This keeps the update flow atomic:

1. stages/commits local changes when needed
2. pushes the branch to origin
3. reruns setup on the still-running machine from a second explicit command
4. updates the existing checkout, rebuilds OpenBridge, kills the older OpenBridge process, and reopens the new one

Forward any extra machine setup flags after --, for example:

macos/DevKit/skill/rerun_setup_on_machine.sh \
  --run-id <run-id> \
  --branch your-branch-name \
  -- --skip-open

2. Create a macOS machine

Always create a fresh mini-machine for your own validation run. Do not take over or reuse a machine that someone else may already be using, even if it looks idle. If you need to continue your own in-flight debugging session, only reconnect to the machine that you created for that same task.

macos/DevKit/skill/machine.sh new "Validate OpenBridge on branch your-branch-name"

Save:

• run id
• VNC URL
• VNC user
• VNC password
• SSH command

Use macos/DevKit/skill/machine.sh list to see active run titles/request descriptions, and get <run-id> if you need the connection info later.

3. Connect with full computer use

vnc connect tunnel.eyhn.in::<vnc-port> --username <user> --password=<password>

Always drive the UI with the full screenshot loop:

vnc get_screenshot -o /tmp/bridge-machine.png
# inspect the screenshot
vnc left_click <x> <y>
vnc type "text"
vnc key enter
vnc scroll down:400 700 500
vnc get_screenshot -o /tmp/bridge-machine-after.png

Rules:

• Take a screenshot before clicking.
• Click the center of the target, not the edge.
• Re-screenshot after every important action.
• Use keyboard shortcuts when they are simpler than pixel hunting.

4. Clone/build/open OpenBridge on the machine

Over SSH:

ssh -i <key> -o StrictHostKeyChecking=no -p <ssh-port> [e-mail]

For a fresh machine with no repo checkout yet, run the setup script from your local machine and stream it over SSH:

ssh -i <key> -o StrictHostKeyChecking=no -p <ssh-port> <user>@tunnel.eyhn.in \
  'bash -s -- --branch your-branch-name --repo-dir ~/openbridge' \
  < macos/DevKit/skill/setup_bridge_on_machine.sh

That keeps the heavy transfer on the machine side: the script itself is tiny, but the repository clone and build happen on the remote Mac.

For the first clone against the private OpenBridge repo, the easiest path is to inject your local GitHub token into the remote command:

ssh -i <key> -o StrictHostKeyChecking=no -p <ssh-port> <user>@tunnel.eyhn.in \
  "CUEBOARD_GH_TOKEN='$(gh auth token)' bash -s -- --branch your-branch-name --repo-dir ~/openbridge" \
  < macos/DevKit/skill/setup_bridge_on_machine.sh

setup_bridge_on_machine.sh will also bootstrap a portable Node.js toolchain on the machine when node/corepack are missing, pin the same SwiftFormat version used in CI, mark onboarding as complete, seed the user TCC database through a pinned copy of jacobsalmela/tccutil plus the required AppleEvents rows for OpenBridge / Terminal / osascript, and open the local OpenBridge build.

If the repo is already present on the machine, you can instead SSH in and run:

bash ~/openbridge/macos/DevKit/skill/setup_bridge_on_machine.sh \
  --branch your-branch-name \
  --repo-dir ~/openbridge

If the repo is private and the machine is not authenticated yet, first do one of:

gh auth login
# or
export CUEBOARD_GH_TOKEN=...

For day-to-day iteration, prefer publish_branch_for_machine.sh followed by rerun_setup_on_machine.sh instead of typing the SSH command manually; that keeps “push code” and “rerun machine setup” as two explicit steps while still making the warm-machine rebuild short.

5. Validate the bug or the new feature in OpenBridge

After the script opens OpenBridge.app, switch back to VNC and test the real UI.

Common loop:

1. vnc get_screenshot
2. inspect the current window
3. click/type/key/scroll
4. vnc get_screenshot again
5. repeat until the bug is reproduced or the feature is verified

By default the setup script marks onboarding as complete for the private repo workflow, so a fresh UnsignedDebug machine should open directly into the local app. Override BRIDGE_COMPLETE_ONBOARDING when you need a different bootstrap state.

6. Stop the machine when done

vnc disconnect
macos/DevKit/skill/machine.sh stop <run-id>

Fast paths

Reconnect to a machine you created yourself

Only use this when you are resuming your own existing debugging session. Do not use list/get to adopt a machine created by someone else; start a new machine instead for any new validation run.

macos/DevKit/skill/machine.sh list
macos/DevKit/skill/machine.sh get <run-id>

Dry-run the helper scripts before using them for real

macos/DevKit/skill/publish_branch_for_machine.sh --branch test-branch --message "test" --dry-run
macos/DevKit/skill/rerun_setup_on_machine.sh --run-id 123456789 --branch test-branch --dry-run
macos/DevKit/skill/setup_bridge_on_machine.sh --branch test-branch --repo-dir ~/openbridge --dry-run

Troubleshooting

• machine.sh new fails immediately: provide a request description, then re-check gh auth status and token scopes.
• vnc is missing: python3 -m pip install --user vnc-computer-use.
• machine clone fails: authenticate gh on the machine or export CUEBOARD_GH_TOKEN.
• OpenBridge builds but does not open the right app: rerun setup_bridge_on_machine.sh; it kills older OpenBridge.app processes before opening the fresh build.
• VNC password starts with -: use --password=<password>.