clawdex-mobile 3.0.0 → 5.0.0

package/bin/clawdex.js

@@ -10,13 +10,14 @@ function printUsage() {
   console.log(`Usage: clawdex <command> [options]
 
 Commands:
-  init [--no-start] [--platform <mobile|ios|android>]
-      Run interactive onboarding and secure setup.
-      By default, this also starts bridge + Expo at the end.
-      Use --no-start to skip auto-launch.
+  init [--no-start]
+      Run interactive bridge onboarding and secure setup.
+      By default, this also starts the secure bridge in the foreground.
+      Use --no-start to configure only.
 
   stop
-      Stop bridge + Expo services for this project.
+      Stop bridge services for this project.
+      Also stops a local Expo dev process if one was started from this checkout.
 
   upgrade [--version <latest|x.y.z>] [--restart]
   update  [--version <latest|x.y.z>] [--restart]
@@ -146,7 +147,7 @@ function runUpgrade(args) {
 
   console.log(`Current clawdex-mobile version: ${previousVersion}`);
   if (!options.noStop) {
-    console.log("Stopping running bridge/Expo services before upgrade...");
+    console.log("Stopping running local services before upgrade...");
     const stopResult = runScript("stop-services.sh", [], { exitOnComplete: false });
     if (!stopResult.ok) {
       console.error("error: failed to stop services before upgrade.");

package/docs/setup-and-operations.md

@@ -6,11 +6,14 @@ This guide is the detailed companion to the top-level `README.md`.
 
 After `clawdex init`, expected sequence:
 
-1. Bridge health passes (`Bridge health check passed.`)
-2. Expo starts (`Starting Expo (mobile) in background...`)
-3. You may briefly see a spinner (`Waiting for Expo output - ...`)
-4. Expo output begins (`expo start --host lan`, QR block, `Metro waiting on exp://...`)
-5. Press Enter to detach onboarding while Expo + bridge keep running
+1. Secure config is written or reused
+2. The bridge starts in the foreground
+3. A pairing QR is printed for the mobile app
+4. Bridge logs stay attached until you stop the process
+
+Published npm releases bundle prebuilt bridge binaries for `darwin-arm64`, `darwin-x64`, `linux-x64`, and `win32-x64`. On those hosts, normal bridge startup does not require a Rust compile.
+
+`clawdex init` does not run a project-local `npm install` for the published CLI path. The only required npm install there is `npm install -g clawdex-mobile@latest`.
 
 ## Manual Secure Setup (No Wizard)
 
@@ -37,7 +40,13 @@ Creates/updates:
 npm run secure:bridge
 ```
 
-### 4) Start Expo
+### 4) Pair from the mobile app
+
+Open the installed mobile app on your phone, then scan the bridge QR. If needed, enter the bridge URL manually (for example `http://100.x.y.z:8787` or `http://192.168.x.y:8787`). The chosen bridge URL is stored on-device and can be changed later in Settings.
+
+## Local Mobile Development Only
+
+If you are developing the mobile app from this repo, start Expo separately:
 
 ```bash
 npm run mobile
@@ -45,15 +54,12 @@ npm run mobile
 
 `npm run mobile` uses `scripts/start-expo.sh`, which sets `REACT_NATIVE_PACKAGER_HOSTNAME` from your secure config so QR resolution is predictable.
 
-On first app launch, onboarding will ask for your bridge URL (for example `http://100.x.y.z:8787` or `http://192.168.x.y:8787`). This URL is stored on-device and can be changed later in Settings.
-
 ## Advanced Knobs
 
 Optional environment variables:
 
 - `CLAWDEX_SETUP_VERBOSE=true` — show full installer output
-- `BRIDGE_HEALTH_WAIT_SECS=300` — max wait for bridge `/health`
-- `EXPO_OUTPUT_WAIT_SECS=90` — spinner timeout before streaming Expo logs
+- `CLAWDEX_BRIDGE_FORCE_SOURCE_BUILD=true` — ignore a bundled bridge binary and build from local Rust sources instead
 - `EXPO_AUTO_REPAIR=true` — auto-repair React Native runtime on `npm run mobile`
 - `EXPO_CLEAR_CACHE=true` — force `expo start --clear` via `npm run mobile`
 
@@ -65,7 +71,8 @@ npm run teardown
 
 Can:
 
-- stop Expo + bridge
+- stop the bridge
+- also stop local Expo if you started it from this repo
 - remove generated artifacts (`.env.secure`, `.bridge.log`, `.expo.log`, pid files)
 - optionally reset `apps/mobile/.env` from `.env.example`
 - optionally run `tailscale down`
@@ -94,7 +101,7 @@ npm run teardown -- --yes
 
 | Variable | Purpose |
 |---|---|
-| `EXPO_PUBLIC_HOST_BRIDGE_TOKEN` | token sent by mobile client |
+| `EXPO_PUBLIC_HOST_BRIDGE_TOKEN` | token used by local mobile dev builds |
 | `EXPO_PUBLIC_ALLOW_QUERY_TOKEN_AUTH` | query-token behavior for WebSocket auth fallback |
 | `EXPO_PUBLIC_ALLOW_INSECURE_REMOTE_BRIDGE` | suppress insecure-HTTP warning |
 | `EXPO_PUBLIC_PRIVACY_POLICY_URL` | in-app Privacy link |

package/docs/troubleshooting.md

@@ -1,23 +1,17 @@
 # Troubleshooting
 
-## Onboarding looks stuck before Expo logs appear
+## Bridge startup seems slow
 
-- Expo startup can be slow on first launch.
-- You should see: `Waiting for Expo output ...`
-- Increase timeout if needed:
-
-```bash
-EXPO_OUTPUT_WAIT_SECS=180 clawdex init
-```
-
-- If Expo never emits logs:
-
-```bash
-tail -n 120 .expo.log
-```
+- `clawdex init` no longer starts Expo for the shipped app.
+- Published npm installs should use a bundled bridge binary on `darwin-arm64`, `darwin-x64`, `linux-x64`, and `win32-x64`.
+- `clawdex init` should not run a repo `npm install` on the published CLI path.
+- If startup is still compiling Rust, you are usually on a source checkout, an unsupported host, or a package without bundled bridge binaries.
+- The slow parts are usually npm dependency install/repair or the first Rust bridge build on source-based setups.
+- If you want to skip the interactive wizard after initial setup, use `npm run secure:bridge`.
 
 ## Expo starts but QR/network is wrong
 
+- This only applies when you are developing the mobile app locally from the repo.
 - Re-run `npm run secure:setup`
 - Confirm `.env.secure` has correct `BRIDGE_HOST`
 - Restart `npm run mobile`
@@ -38,13 +32,14 @@ npm run stop:services
 
 ## Bridge auth errors (`401`, invalid token)
 
-- Ensure `BRIDGE_AUTH_TOKEN` in `.env.secure` matches `EXPO_PUBLIC_HOST_BRIDGE_TOKEN` in `apps/mobile/.env`
-- Restart bridge + Expo after token changes
+- For the shipped mobile app, rescan the bridge QR or update the stored token in Settings.
+- For a local dev build, also ensure `BRIDGE_AUTH_TOKEN` in `.env.secure` matches `EXPO_PUBLIC_HOST_BRIDGE_TOKEN` in `apps/mobile/.env`.
+- Restart the bridge after token changes.
 
 ## Tailscale issues
 
 - Verify host and phone are on the same Tailscale network
-- Check host IP (`tailscale ip -4`) and mobile `.env` URL
+- Check host IP (`tailscale ip -4`) and the bridge URL saved in the mobile app
 
 ## `codex` not found
 
@@ -53,6 +48,8 @@ npm run stop:services
 
 ## Bridge build fails with `linker 'cc' not found`
 
+This only applies when the bridge is building from Rust source instead of using a bundled binary.
+
 Install C build tools:
 
 ```bash
@@ -106,7 +103,7 @@ npm run start -- --clear
 
 ## Plan mode errors (`RPC-32600` invalid `collaborationMode`)
 
-- Restart Expo and reload app bundle
+- Restart the app and reconnect to the bridge
 - Ensure bridge/mobile revisions match
 - Run API test if needed:
 
@@ -118,4 +115,4 @@ npm run -w apps/mobile test -- --runInBand src/api/__tests__/client.test.ts
 
 - Ensure revision supports `turn/interrupt`
 - If run already finished, stop button disappears by design
-- Pull latest, restart bridge, reload Expo bundle
+- Pull latest, restart bridge, then retry from the mobile app

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawdex-mobile",
-  "version": "3.0.0",
+  "version": "5.0.0",
   "homepage": "https://github.com/Mohit-Patil/clawdex-mobile#readme",
   "repository": {
     "type": "git",
@@ -21,11 +21,12 @@
     "ios": "./scripts/start-expo.sh ios",
     "android": "./scripts/start-expo.sh android",
     "bridge": "BRIDGE_WORKDIR=$(pwd) npm run -w @codex/rust-bridge dev",
+    "bridge:package:stage-current": "node ./scripts/bridge-binary.js stage-current",
     "setup:wizard": "./scripts/setup-wizard.sh",
     "stop:services": "./scripts/stop-services.sh",
     "secure:setup": "./scripts/setup-secure-dev.sh",
-    "secure:bridge": "./scripts/start-bridge-secure.sh",
-    "secure:bridge:dev": "BRIDGE_RUN_MODE=dev ./scripts/start-bridge-secure.sh",
+    "secure:bridge": "node ./scripts/start-bridge-secure.js",
+    "secure:bridge:dev": "node ./scripts/start-bridge-secure.js --dev",
     "bridge:ts": "BRIDGE_WORKDIR=$(pwd) npm run -w @codex/mac-bridge dev",
     "version:sync": "node scripts/sync-versions.js",
     "build": "npm run --workspaces build",

package/scripts/bridge-binary.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const SUPPORTED_RUNTIME_TARGETS = {
+  "darwin-arm64": {
+    platform: "darwin",
+    arch: "arm64",
+    rustTarget: "aarch64-apple-darwin",
+    binaryName: "codex-rust-bridge",
+  },
+  "darwin-x64": {
+    platform: "darwin",
+    arch: "x64",
+    rustTarget: "x86_64-apple-darwin",
+    binaryName: "codex-rust-bridge",
+  },
+  "linux-x64": {
+    platform: "linux",
+    arch: "x64",
+    rustTarget: "x86_64-unknown-linux-gnu",
+    binaryName: "codex-rust-bridge",
+  },
+  "win32-x64": {
+    platform: "win32",
+    arch: "x64",
+    rustTarget: "x86_64-pc-windows-msvc",
+    binaryName: "codex-rust-bridge.exe",
+  },
+};
+
+function repoRoot() {
+  return path.resolve(__dirname, "..");
+}
+
+function resolveRuntimeTarget(platform = os.platform(), arch = os.arch()) {
+  for (const [target, metadata] of Object.entries(SUPPORTED_RUNTIME_TARGETS)) {
+    if (metadata.platform === platform && metadata.arch === arch) {
+      return target;
+    }
+  }
+  return null;
+}
+
+function binaryNameForTarget(target) {
+  const metadata = SUPPORTED_RUNTIME_TARGETS[target];
+  if (!metadata) {
+    throw new Error(`Unsupported bridge target '${target}'.`);
+  }
+  return metadata.binaryName;
+}
+
+function packagedBinaryPath(rootDir = repoRoot(), target = resolveRuntimeTarget()) {
+  if (!target) {
+    return null;
+  }
+  return path.join(rootDir, "vendor", "bridge-binaries", target, binaryNameForTarget(target));
+}
+
+function builtBinaryPath(rootDir = repoRoot(), platform = os.platform()) {
+  const binaryName = platform === "win32" ? "codex-rust-bridge.exe" : "codex-rust-bridge";
+  return path.join(rootDir, "services", "rust-bridge", "target", "release", binaryName);
+}
+
+function ensureExecutable(filePath) {
+  if (process.platform !== "win32") {
+    fs.chmodSync(filePath, 0o755);
+  }
+}
+
+function stageBinary({ rootDir = repoRoot(), from, target = resolveRuntimeTarget() }) {
+  if (!from) {
+    throw new Error("--from is required.");
+  }
+  if (!target) {
+    throw new Error("No supported runtime target for this host. Pass --target explicitly.");
+  }
+
+  const destination = packagedBinaryPath(rootDir, target);
+  if (!destination) {
+    throw new Error(`Unable to compute packaged path for target '${target}'.`);
+  }
+
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.copyFileSync(from, destination);
+  ensureExecutable(destination);
+  return destination;
+}
+
+function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (!value.startsWith("--")) {
+      positional.push(value);
+      continue;
+    }
+
+    const key = value.slice(2);
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      flags[key] = true;
+      continue;
+    }
+    flags[key] = next;
+    index += 1;
+  }
+
+  return { positional, flags };
+}
+
+function main() {
+  const { positional, flags } = parseArgs(process.argv.slice(2));
+  const command = positional[0];
+  const rootDir = flags.root ? path.resolve(flags.root) : repoRoot();
+
+  switch (command) {
+    case "current-target": {
+      const target = resolveRuntimeTarget();
+      if (!target) {
+        process.exit(1);
+      }
+      console.log(target);
+      return;
+    }
+    case "has-current-packaged": {
+      const filePath = packagedBinaryPath(rootDir);
+      if (filePath && fs.existsSync(filePath)) {
+        console.log(filePath);
+        return;
+      }
+      process.exit(1);
+      return;
+    }
+    case "current-packaged-path": {
+      const target = flags.target || resolveRuntimeTarget();
+      const filePath = packagedBinaryPath(rootDir, target);
+      if (!filePath) {
+        process.exit(1);
+      }
+      console.log(filePath);
+      return;
+    }
+    case "current-built-path": {
+      console.log(builtBinaryPath(rootDir));
+      return;
+    }
+    case "stage-current": {
+      const destination = stageBinary({
+        rootDir,
+        from: builtBinaryPath(rootDir),
+        target: flags.target || resolveRuntimeTarget(),
+      });
+      console.log(destination);
+      return;
+    }
+    case "stage": {
+      const destination = stageBinary({
+        rootDir,
+        from: flags.from ? path.resolve(flags.from) : "",
+        target: flags.target || resolveRuntimeTarget(),
+      });
+      console.log(destination);
+      return;
+    }
+    default:
+      console.error("Usage:");
+      console.error("  node scripts/bridge-binary.js current-target");
+      console.error("  node scripts/bridge-binary.js has-current-packaged");
+      console.error("  node scripts/bridge-binary.js current-packaged-path [--target <target>]");
+      console.error("  node scripts/bridge-binary.js current-built-path");
+      console.error("  node scripts/bridge-binary.js stage-current [--target <target>]");
+      console.error("  node scripts/bridge-binary.js stage --from <binary> [--target <target>]");
+      process.exit(1);
+  }
+}
+
+module.exports = {
+  SUPPORTED_RUNTIME_TARGETS,
+  binaryNameForTarget,
+  builtBinaryPath,
+  ensureExecutable,
+  packagedBinaryPath,
+  resolveRuntimeTarget,
+  stageBinary,
+};
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}