openclaw-voice 1.0.5 → 1.0.6

package/README.md

@@ -41,26 +41,106 @@ Prerequisites:
 - Node.js 18+
 - Xcode + iOS runtime
 - CocoaPods
+- Android Studio + Android SDK (for Android runs)
 - A running OpenClaw Gateway endpoint (`wss://...`)
 
 Quick setup:
 
 ```bash
-bash scripts/bootstrap.sh
+npm run setup
 ```
 
-What it does:
+Optional environment check:
 
-- Installs dependencies with `npm install`
-- Generates iOS native project (if missing)
-- Installs CocoaPods
-- Launches the app on a physical device (`npm run ios -- --device`)
+```bash
+npm run doctor:ios
+```
+
+Debug run path (development, Metro required):
+
+```bash
+# Terminal A
+npm run dev:metro
+
+# Terminal B
+npm run ios:dev:device:install
+```
+
+If `Connecting to: iPhone` keeps spinning forever, stop that terminal (`Ctrl+C`) and launch directly:
+
+```bash
+EXPO_DEV_SERVER_URL=<metro-url> npm run ios:dev:device:open
+```
+
+Release run path (device testing, Metro not required):
+
+```bash
+npm run ios:release:device
+```
+
+`scripts/bootstrap.sh` runs `npm run setup` and prints these run paths.
+
+Android run path:
+
+```bash
+npm run doctor:android
+npm run android:emulator:setup   # one-time
+npm run android:emulator:start   # start emulator
+npm run android
+```
+
+If `doctor:android` reports SDK errors, set `ANDROID_HOME` (or `ANDROID_SDK_ROOT`) and ensure `adb` is available.
+If AVD creation fails with `Valid system image paths are: null`, install `cmdline-tools;latest` inside your SDK and rerun `npm run android:emulator:setup`.
+
+### Android: Verified Device/Emulator Steps
+
+Verified on macOS with Expo SDK 54 and Android API 35.
 
-Manual setup:
+1. Set SDK environment variables:
 
 ```bash
-npm install
-npm run ios
+export ANDROID_HOME="$HOME/Library/Android/sdk"
+export ANDROID_SDK_ROOT="$ANDROID_HOME"
+export PATH="$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$ANDROID_HOME/cmdline-tools/latest/bin:$PATH"
+```
+
+2. Validate toolchain:
+
+```bash
+npm run doctor:android
+```
+
+3. Emulator path:
+
+```bash
+npm run android:emulator:setup
+npm run android:emulator:start
+npm run android
+```
+
+4. Physical device path (USB debugging enabled):
+
+```bash
+adb devices
+npm run android
+```
+
+Expected result:
+- `adb devices` shows at least one `device`
+- Expo installs and launches the app without SDK-path errors
+
+### What Is Metro?
+
+`Metro` is the JavaScript bundler/dev server used by React Native/Expo in development.
+In Debug builds, the app loads JS from Metro (usually `:8081`) with fast refresh.
+
+- Debug build (`npm run ios`, `npm run ios:dev`) -> Metro required
+- Release build (`--configuration Release`) -> Metro not required (bundle is embedded)
+
+If Debug app does not attach to Metro, pass URL explicitly:
+
+```bash
+EXPO_DEV_SERVER_URL=http://192.168.0.10:8081 npm run ios:dev:device:open
 ```
 
 ## Use It As npm Package
@@ -85,7 +165,7 @@ setStorage({
 const client = new GatewayClient('wss://your-openclaw-gateway.example.com', {
   token: 'your-token',
   clientId: 'openclaw-ios',
-  displayName: 'OpenClawVoice',
+  displayName: 'OpenClaw Pocket',
   role: 'operator',
   scopes: ['operator.read', 'operator.write'],
   caps: ['talk'],
@@ -156,13 +236,13 @@ cp .env.example .env
 - `EXPO_PUBLIC_DEFAULT_THEME` (`light` or `dark`)
 - `EXPO_PUBLIC_DEFAULT_SESSION_KEY` (default: `main`)
 - `EXPO_PUBLIC_GATEWAY_CLIENT_ID` (default: `openclaw-ios`)
-- `EXPO_PUBLIC_GATEWAY_DISPLAY_NAME` (default: `OpenClawVoice`)
+- `EXPO_PUBLIC_GATEWAY_DISPLAY_NAME` (default: `OpenClaw Pocket`)
 - `EXPO_PUBLIC_DEBUG_MODE` (`true` to show dev warnings and runtime debug panel, default: `false`)
 
 ## Connection Defaults
 
 - `clientId: openclaw-ios`
-- `displayName: OpenClawVoice`
+- `displayName: OpenClaw Pocket`
 - `role: operator`
 - `scopes: operator.read, operator.write`
 - `caps: talk`
@@ -171,8 +251,20 @@ Device identity is generated locally and reused when persistent storage is avail
 
 ## Scripts
 
+- `npm run setup` - Install deps, prepare native iOS project, install Pods
+- `npm run doctor:ios` - Validate iOS development environment and connectivity
+- `npm run doctor:android` - Validate Android SDK/adb/device environment
+- `npm run android:emulator:setup` - Install Android SDK pieces and create default emulator (`Pixel_8_API_35`)
+- `npm run android:emulator:start` - Start default Android emulator
+- `npm run dev:metro` - Start Metro for dev-client (tunnel mode)
 - `npm run start` - Start Expo dev server
-- `npm run ios` - Build and run iOS app
+- `npm run ios` - Alias for `npm run ios:dev`
+- `npm run ios:dev` - Build and run iOS Debug app (Metro required)
+- `npm run ios:dev:device` - Build and run iOS Debug app on device (Metro required)
+- `npm run ios:dev:device:install` - Install iOS Debug app on device (no bundler startup)
+- `npm run ios:dev:device:open` - Launch installed iOS app on connected device (uses `EXPO_DEV_SERVER_URL` when set)
+- `npm run ios:release` - Build and run iOS Release app (Metro not required)
+- `npm run ios:release:device` - Build and run iOS Release app on device (Metro not required)
 - `npm run android` - Build and run Android app
 - `npm run web` - Run web target
 - `npm run typecheck` - Run TypeScript checks
@@ -214,7 +306,13 @@ If this project helps your workflow, you can support maintenance on GitHub Spons
 
 ## Troubleshooting
 
-See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md).
+For `No script URL provided` / `Could not connect to development server`:
+
+- Start Metro explicitly (`npx expo start --dev-client --host tunnel --clear`)
+- Reinstall Debug app with `--no-bundler` from another terminal
+- Or use Release build (`npx expo run:ios --device --configuration Release`)
+
+See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for more.
 
 ## Contributing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-voice",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "main": "./dist/package.js",
   "types": "./dist/package.d.ts",
   "exports": {
@@ -18,9 +18,21 @@
     "access": "public"
   },
   "scripts": {
+    "setup": "bash scripts/setup.sh",
+    "doctor:ios": "node scripts/doctor-ios.mjs",
+    "doctor:android": "node scripts/doctor-android.mjs",
+    "android:emulator:setup": "bash scripts/setup-android-emulator.sh",
+    "android:emulator:start": "bash scripts/start-android-emulator.sh",
+    "dev:metro": "expo start --dev-client --host tunnel --clear",
     "start": "expo start",
     "android": "expo run:android",
-    "ios": "expo run:ios",
+    "ios": "npm run ios:dev --",
+    "ios:dev": "expo run:ios --configuration Debug",
+    "ios:dev:device": "npm run ios:dev -- --device",
+    "ios:dev:device:install": "npm run ios:dev -- --device --no-bundler",
+    "ios:dev:device:open": "bash scripts/launch-ios-device.sh",
+    "ios:release": "expo run:ios --configuration Release",
+    "ios:release:device": "npm run ios:release -- --device",
     "web": "expo start --web",
     "typecheck": "tsc --noEmit",
     "lint": "node scripts/lint.mjs",