Rebuild App (local development)

Kill the running dev build, rebuild it as the isolated termio-dev.app bundle, and relaunch — so every rebuild reflects the current Dock icon and, crucially, does not disturb an installed release build you use daily.

The dev channel

termio ships a TERMIO_CHANNEL=dev build that is a fully separate app from the release one, so both can run at the same time:

All of this falls out of the .dev bundle-id suffix via Sources/termio/Companion/AppChannel.swift (paths + port) and scripts/build-app.sh (id, name, SUFeedURL deletion, CLI rebind). Sparkle.framework itself is embedded on both channels — the binary links it either way — so a dev bundle still carries it; it just has nothing to check.

termio is a plain SwiftPM executable (Package.swift → executableTarget named termio); swift build alone produces a bare binary with no Dock icon. So this skill builds the real bundle via scripts/build-app.sh. For a dev build the script auto-picks a real codesigning identity from your own keychain (any "Apple Development" / "Developer ID Application" cert — a free Apple ID gives you one) so the dev app can post macOS notifications; usernoted rejects an ad-hoc signature outright, so an unsigned dev build can never banner. A contributor with no signing cert falls back to ad-hoc automatically — the build still succeeds, they just don't get notifications. Set SIGN_IDENTITY=… to force a specific one. The app runs unsandboxed with .exec PTYs — see CLAUDE.md. The icon is packaging/icon-static.svg, rasterized to packaging/AppIcon.png by scripts/render-icon.sh (needs headless Chrome). Note: dev and release currently share the same icon art and differ only by name ("termio dev") — a tinted dev icon is a possible follow-up.

Instructions

When invoked, execute these steps sequentially:

1. Kill only the running dev app + its tunnel. Both channels' inner binary is named termio (CFBundleExecutable), so pkill -x termio would kill the release app too. Match the dev bundle path instead. SIGKILL skips the app's willTerminate cleanup, so also reap the companion tunnel it spawned on the dev port (8788):

   pkill -9 -f "termio-dev.app/Contents/MacOS/termio" || true
   pkill -9 -f "cloudflared tunnel --url http://127.0.0.1:8788" || true
   pkill -9 -f "tunelo port 8788" || true

2. Build the dev bundle from the committed packaging/AppIcon.png — do not re-render the icon (see "Icons" below). Show the tail of the output; if the build fails, show the error and stop — do NOT relaunch:

   TERMIO_CHANNEL=dev ./scripts/build-app.sh 2>&1 | tail -12

3. Re-register the dev bundle with LaunchServices, then refresh the Dock cache. macOS resolves an app's icon by its bundle id (sh.termio.app.dev); lsregister -f forces our path to win and killall Dock drops the cached icon:

   LSREG="/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister"
   "$LSREG" -f "$PWD/termio-dev.app"
   touch ./termio-dev.app
   killall Dock 2>/dev/null || true

4. Relaunch via open (NOT nohup on the inner binary — that bypasses LaunchServices). open's --stdout / --stderr still capture logs:

   open ./termio-dev.app --stdout /tmp/termio-dev.log --stderr /tmp/termio-dev.log
   echo "launched ./termio-dev.app (logs: /tmp/termio-dev.log)"

5. Upgrade the running dev daemon. build-app.sh already rebuilt the daemon into Resources/termiod, but a running dev daemon keeps its old image: a dev app's launch-time reconcile deliberately refuses to stage (its bundle stamp is a placeholder, and that guard is what keeps a dev build from ever deploying itself over a release daemon). Without this step, a termiod-side change gets "verified" against the previous daemon. The deploy is idempotent — same version reports current and does nothing, so it costs nothing on Swift-only rebuilds — and an execve handoff keeps the pid and carries every live session. TERMIOD_SOCK must be unset first: a shell inside a termio session carries it pointed at the release daemon, and it overrides the channel.

   unset TERMIOD_SOCK
   ./termio-dev.app/Contents/Resources/termio-dev server deploy --json 2>&1 | tail -3

   A daemon that isn't running needs nothing: the first pane starts it from the new bundle.
6. Report the result: whether the build succeeded, the app relaunched, and the daemon version the deploy reported. If the window doesn't appear, check /tmp/termio-dev.log.

Verifying a termiod-side change

Sessions carried across the handoff keep the environment and shell their old daemon spawned them with — a change to session spawning (env, injection, PTY setup) is invisible in them by design. Open a new session to see it.

Icons

scripts/render-icon.sh rasterizes packaging/icon-static.svg into packaging/AppIcon.png (and the iOS asset) through headless Chrome — and its output is not reproducible: rendering the same SVG twice writes two different files, neither matching the committed one. Running it on every rebuild therefore dirtied the tree with two unreviewable binary diffs, cost a Chrome launch, and risked overwriting hand-touched artwork. So it is not part of this loop.

Re-render only when the SVG actually changed, and commit the PNGs as their own change:

./scripts/render-icon.sh && git add packaging/AppIcon.png \
  ios/Sources/Assets.xcassets/AppIcon.appiconset/AppIcon.png

Notes

• This builds release configuration (via build-app.sh) into the dev channel bundle, so it's a few seconds slower than a bare swift build. For quick code-only iteration without a bundle, run swift build and launch "$(swift build --show-bin-path)/termio" directly — but that has no Dock icon and, running unbundled, uses AppChannel.suffix == "" (i.e. the release state dir and port 8787), so it is not isolated. Use the bundle when you need isolation.
• A concurrent SwiftPM process holding the .build lock can make a build emit spurious errors mid-write; if that happens, just rerun.
• Do NOT modify Package.swift or sources during a rebuild.
• After rebuilding a UI change, pair this with the app-screenshot-debug skill to actually see the result.