diff --git a/src/utils/__tests__/args.test.ts b/src/utils/__tests__/args.test.ts index 569b5c0ec..57c4661f6 100644 --- a/src/utils/__tests__/args.test.ts +++ b/src/utils/__tests__/args.test.ts @@ -972,6 +972,10 @@ test('usage includes agent workflows, config, environment, and examples footers' usageText, /help react-devtools\s+React Native performance, profiling, component tree, and renders/, ); + assert.match( + usageText, + /help physical-device\s+Connected phone\/tablet setup and iOS signing prerequisites/, + ); assert.match( usageText, /help react-native\s+React Native app automation hazards, overlays, Metro, and routing/, @@ -1122,6 +1126,16 @@ test('usageForCommand resolves remote help topic', () => { assert.match(help, /install-from-source --github-actions-artifact org\/repo:artifact/); }); +test('usageForCommand resolves physical-device help topic', () => { + const help = usageForCommand('physical-device'); + if (help === null) throw new Error('Expected physical-device help text'); + assert.match(help, /agent-device help physical-device/); + assert.match(help, /Start with Automatic Signing and only these env vars/); + assert.match(help, /AGENT_DEVICE_IOS_TEAM_ID=ABCDE12345/); + assert.match(help, /AGENT_DEVICE_IOS_BUNDLE_ID=com\.yourname\.agentdevice\.runner/); + assert.match(help, /profile name\/specifier, not a file path/); +}); + test('usageForCommand resolves macos help topic', () => { const help = usageForCommand('macos'); if (help === null) throw new Error('Expected macos help text'); diff --git a/src/utils/cli-help.ts b/src/utils/cli-help.ts index f80003232..b943ab797 100644 --- a/src/utils/cli-help.ts +++ b/src/utils/cli-help.ts @@ -20,6 +20,10 @@ const AGENT_WORKFLOWS = [ label: 'help react-devtools', description: 'React Native performance, profiling, component tree, and renders', }, + { + label: 'help physical-device', + description: 'Connected phone/tablet setup and iOS signing prerequisites', + }, { label: 'help remote', description: 'Remote/cloud config, tenants, leases, and local service tunnels', @@ -406,6 +410,36 @@ Slow-flow investigation: For 15-20s async work, use wait with the exact expected text or selector instead of repeated snapshots. Report React render offenders separately from network/backend waits and device frame/CPU/memory findings.`, }, + 'physical-device': { + summary: 'Connected phone/tablet setup and iOS signing prerequisites', + body: `agent-device help physical-device + +Use this when the target is connected hardware instead of a simulator/emulator. +For simulator/emulator workflows, use help workflow. + +Discovery: + agent-device devices --platform ios + agent-device devices --platform android + Use --device only when multiple devices are present. + +iOS physical-device prerequisites: + Xcode and xcrun devicectl must be available from the selected Xcode. + The device must be paired/trusted, connected, unlocked when needed, and have Developer Mode enabled. + The AgentDeviceRunner XCTest host must be signed before commands can run on a physical device. + Start with Automatic Signing and only these env vars: + AGENT_DEVICE_IOS_TEAM_ID=ABCDE12345 + AGENT_DEVICE_IOS_BUNDLE_ID=com.yourname.agentdevice.runner + Find team ids and Apple Development signing certificates with: + security find-identity -v -p codesigning + If Xcode cannot choose a profile, set AGENT_DEVICE_IOS_PROVISIONING_PROFILE to the profile name/specifier, not a file path. + AGENT_DEVICE_IOS_SIGNING_IDENTITY is optional; omit it unless xcodebuild asks for a specific identity. + The profile/team must allow AGENT_DEVICE_IOS_BUNDLE_ID and .uitests. + First-run XCTest setup/build can take longer than normal commands; keep the device connected and use --debug to inspect signing/build diagnostics if setup times out. + +Android physical-device prerequisites: + Enable USB debugging and confirm the device appears in agent-device devices --platform android. + Android does not need the iOS runner signing setup. For React Native/Expo Metro reachability, read help react-native.`, + }, remote: { summary: 'Remote config, tenant, lease, and remote host flow', body: `agent-device help remote @@ -436,6 +470,7 @@ Rules: For self-contained scripts, pass the same --remote-config to every operational command, including disconnect; a preceding connect is optional but not required. For remote artifact installs, use install-from-source or install-from-source --github-actions-artifact org/repo:artifact; do not download CI artifacts locally first. After connect, let the active remote connection supply runtime hints. + For connected phone/tablet setup and iOS signing prerequisites, read agent-device help physical-device. For remote Android and iOS bridge React DevTools, run agent-device react-devtools normally. The CLI opens the needed local service tunnel for the DevTools daemon and keeps it alive until agent-device react-devtools stop or disconnect. Use --debug when remote connection or transport errors need diagnostic ids and remote log hints.`, }, diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md index 7f81ed7d4..d07639ffb 100644 --- a/website/docs/docs/commands.md +++ b/website/docs/docs/commands.md @@ -811,17 +811,21 @@ agent-device session list --json - `session list` shows active daemon sessions and their tracked device/app context. - Use `--json` when you want to inspect or script against the raw session metadata. -## iOS device prerequisites +## iOS physical-device prerequisites + +For CLI-discoverable setup guidance, run `agent-device help physical-device`. - Xcode + `xcrun devicectl` available. -- Paired physical device with Developer Mode enabled. -- Use Automatic Signing in Xcode, or pass optional env overrides: +- Paired/trusted physical device, connected, unlocked when needed, with Developer Mode enabled. +- The `AgentDeviceRunner` XCTest host must be signed before commands can run on a physical device. +- Start with Automatic Signing and only these env vars: - `AGENT_DEVICE_IOS_TEAM_ID` - - `AGENT_DEVICE_IOS_SIGNING_IDENTITY` (optional) - - `AGENT_DEVICE_IOS_PROVISIONING_PROFILE` - `AGENT_DEVICE_IOS_BUNDLE_ID` (runner bundle-id base; tests use `.uitests`) -- Free Apple Developer (Personal Team) accounts can fail on unavailable generic bundle IDs; set `AGENT_DEVICE_IOS_BUNDLE_ID` to a unique reverse-DNS value. -- First-run XCTest setup/build can take longer than normal commands; keep the device connected and inspect daemon diagnostics if setup times out. +- Find team ids and Apple Development signing certificates with `security find-identity -v -p codesigning`. +- If Xcode cannot choose a profile, set `AGENT_DEVICE_IOS_PROVISIONING_PROFILE` to the profile name/specifier, not a file path. +- `AGENT_DEVICE_IOS_SIGNING_IDENTITY` is optional; omit it unless `xcodebuild` asks for a specific identity. +- The profile/team must allow `AGENT_DEVICE_IOS_BUNDLE_ID` and `.uitests`. +- First-run XCTest setup/build can take longer than normal commands; keep the device connected and use `--debug` to inspect signing/build diagnostics if setup times out. - If you override the iOS runner derived-data path and also force cleanup, keep `AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH` under the project `.tmp/` directory. Other cleanup override paths are rejected with a recovery hint. - For daemon startup troubleshooting: - follow stale metadata hints for `/daemon.json` and `/daemon.lock` (`state-dir` defaults to `~/.agent-device`)