Agentdeck Deploy

AgentDeck Deploy

Canonical deploy procedure for AgentDeck. This file is the single source of truth — .claude/skills/agentdeck-deploy is a tracked directory symlink to this skill. Build, install, launch, and configure AgentDeck on connected targets; keep deployment scoped to what is actually connected and skip missing devices with a clear note (never fail the whole deploy because one device is absent).

Arguments / Target Names

Parse the argument string to determine target(s). Multiple targets can be combined (e.g. android ios).

The default all sequence above does not include ESP32 or the D200H Studio plugin. When reviewing release coverage, list those channels explicitly; when deploying, follow the requested target scope. ulanzi means TC001 firmware, whereas d200h / ulanzi-plugin means the Studio plugin. A firmware build or a plugin package does not update the installed runtime.

Device Registry

Android Devices

Apple Devices

iPhone XR is retired from routine test and deploy targets. Do not include it in all, ios, or iphone runs even if it appears in device discovery; target it only when the user explicitly requests that device.

ESP32 Boards

두 이름 층 (panel/form + 인치): friendly 는 ./scripts/flash.sh <friendly> 에 넘기는 canonical 친근명, pio env 는 pio run -e <pio env> / .pio/build/<pio env>/ 에 쓰는 실제 PlatformIO env. flash.sh 는 둘 다 받지만 pio run -e 는 pio env 만 받는다.

Execution Steps

Output discipline. Every step below runs from the repository root (cd "$(git rev-parse --show-toplevel)"). Send long build output to a log under diagnostics/logs/ (gitignored) and show only the tail or the errors, e.g. mkdir -p diagnostics/logs; <build> >diagnostics/logs/<target>.log 2>&1 || { tail -40 diagnostics/logs/<target>.log; exit 1; }, then grep -nE 'error|FAILED' diagnostics/logs/<target>.log | head -20 if the tail is not enough. Use each tool's quiet mode: xcodebuild -quiet, gradle -q, pio run -s.

Step 0: Pre-flight — Detect Connected Devices

Run before any deploy to know what's available:

cd "$(git rev-parse --show-toplevel)"

echo "=== ADB Devices ==="
adb devices -l 2>/dev/null | grep -w device | grep -v "List"

echo "=== Apple Devices ==="
xcrun devicectl list devices 2>/dev/null | grep -E "(iPhone|iPad)" || echo "none"

echo "=== Serial Ports (ESP32) ==="
ls /dev/cu.usb* 2>/dev/null || echo "none"

echo "=== Stream Deck ==="
pgrep -x "Stream Deck" >/dev/null && echo "running" || echo "not running"

echo "=== Daemon ==="
cat ~/.agentdeck/daemon.json 2>/dev/null || echo "not running"

For macOS targets (macos, apple, all, or any run that ends in screenshots/E2E driven through System Events), also run bash scripts/macos-preflight.sh --automation --accessibility --screen-recording --json (add --firewall apple/DerivedData/Build/Products/Debug/AgentDeck.app once that app is built). Exit 2 means a grant is denied: relay each fix path to the user and stop the E2E part instead of letting a consent sheet stall it; exit 3 means it could not confirm — say so, never assume granted.

Only deploy to devices that are actually connected. Skip missing devices with a warning, don't fail. If preflight access fails, follow AGENTS.md Agent working agreements for execution-policy failures; retry only the affected command after resolving access, and do not infer device absence from an unreadable probe.

Step 1: Build (always first, unless target is bridge-only or esp32-only)

mkdir -p diagnostics/logs
pnpm build >diagnostics/logs/pnpm-build.log 2>&1 || { tail -40 diagnostics/logs/pnpm-build.log; exit 1; }

For Android targets, also build APK:

bash scripts/build-android-release.sh >diagnostics/logs/android.log 2>&1 || { tail -40 diagnostics/logs/android.log; exit 1; }

This produces dist/agentdeck-v{VERSION}.apk.

For Apple targets (ios/macos), build via xcodebuild (see Step 3/4).

Step 2: Android Deploy

For EACH connected Android device in the target set:

SERIAL="<device_serial>"
APK="dist/agentdeck-v*.apk"  # use the actual versioned filename from Step 1

# 1. Stop running app
adb -s $SERIAL shell am force-stop dev.agentdeck

# 2. Install (attempt direct first, uninstall on signature conflict)
if ! adb -s $SERIAL install -r $APK 2>&1 | grep -q "Success"; then
  adb -s $SERIAL uninstall dev.agentdeck
  adb -s $SERIAL install $APK
fi

# 3. Launch
adb -s $SERIAL shell am start -n dev.agentdeck/.MainActivity

# 4. adb reverse for daemon connection
adb -s $SERIAL reverse tcp:9120 tcp:9120

Device-specific post-install:

Pantone 6 (after ANY install, especially after uninstall→reinstall):

# Rotation fix — reinstall resets system rotation settings (NOTE: Pantone 6 only! Do NOT run on Crema S or ordinary tablets)
adb -s AA007422R24C1300039 shell settings put system accelerometer_rotation 0
adb -s AA007422R24C1300039 shell settings put system user_rotation 1  # 1=landscape

Crema S: No special steps needed. (Standard requestedOrientation is used; do not modify system-wide user_rotation.)

Lenovo Tab: No special steps needed.

Step 3: iOS Deploy

Build once, install on multiple devices:

cd "$(git rev-parse --show-toplevel)"

# Build (one build serves both devices); a fixed derived-data path, never a DerivedData hash
xcodebuild build -project apple/AgentDeck.xcodeproj -scheme AgentDeck_iOS \
  -destination 'platform=iOS,id=00008112-001608A02ED2601E' \
  -derivedDataPath apple/DerivedData \
  CODE_SIGN_STYLE=Automatic DEVELOPMENT_TEAM=QF36NDHYHD -quiet \
  >diagnostics/logs/xcodebuild-ios.log 2>&1 || { tail -40 diagnostics/logs/xcodebuild-ios.log; exit 1; }

APP=apple/DerivedData/Build/Products/Debug-iphoneos/AgentDeck.app

For EACH iOS device in the target set:

DEVICE_ID="<devicectl_id>"
xcrun devicectl device install app --device $DEVICE_ID $APP
xcrun devicectl device process launch --device $DEVICE_ID bound.serendipity.agent.deck

Important:

• Devices must be unlocked (passcode protected → install fails)
• After uninstall→reinstall, local network permission popup appears again
• Prefer existing XcodeBuildMCP tools when available; otherwise use these established xcodebuild commands

Step 4: macOS Deploy

cd "$(git rev-parse --show-toplevel)"
xcodebuild build -project apple/AgentDeck.xcodeproj -scheme AgentDeck_macOS \
  -destination 'platform=macOS' -derivedDataPath apple/DerivedData -quiet \
  >diagnostics/logs/xcodebuild-macos.log 2>&1 || { tail -40 diagnostics/logs/xcodebuild-macos.log; exit 1; }

# Kill existing → relaunch
killall AgentDeck 2>/dev/null; sleep 0.5
open -a "$PWD/apple/DerivedData/Build/Products/Debug/AgentDeck.app"

Do not add or alter App Store UI text that asks users to install or launch external tools (App Review 4.2.3 — see AGENTS.md "App Store build invariants").

Step 5: Bridge/Daemon Restart

Use the supervisor-routed lifecycle command (.claude/rules/daemon-lifecycle.md): daemon restart rebuilds stale packages on a checkout, restarts through the LaunchAgent/systemd/Scheduled Task that owns the daemon, and verifies the daemon that came up by pid and build — never background daemon start & with a fixed sleep.

agentdeck daemon restart
# Bounded health wait on the registry-resolved port (never a blind 9120 probe)
PORT=$(sed -n 's/.*"port"[[:space:]]*:[[:space:]]*\([0-9][0-9]*\).*/\1/p' ~/.agentdeck/daemon.json 2>/dev/null | head -n 1)
for _ in 1 2 3 4 5 6 7 8 9 10; do
  curl -fsS --max-time 2 "http://127.0.0.1:${PORT:-9120}/health" >/dev/null && break
  sleep 1
done
agentdeck daemon status

If the health wait never answers, report the daemon as unverified (not stopped) and show agentdeck daemon status.

Step 6: Plugin

A build is not a deployment: Marketplace installation can replace the source link, and an already-running process keeps its old JavaScript after a rebuild. On macOS, from the persistent main checkout, run pnpm plugin:deploy. It refuses linked worktrees and checkouts missing known origin/master changes, builds shared and plugin, preserves a replaced installation outside the host scan directory, links the source, restarts it, and requires a fresh runtime receipt matching the bundle path and SHA-256. pnpm plugin:check checks the current installation and running process without changing them. Never report success from pnpm build or a successful streamdeck link alone.

After a Marketplace/DRM validation session, restore the development installation with pnpm plugin:deploy and record pnpm plugin:check before finishing. A failed switch restores the prior installation; do not delete its backup.