clawdex-mobile 1.0.0

package/.github/workflows/ci.yml

@@ -0,0 +1,77 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - "**"
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  js-workspaces:
+    name: JS - ${{ matrix.workspace }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        workspace:
+          - "@codex/mac-bridge"
+          - "clawdex-mobile"
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint -w "${{ matrix.workspace }}"
+
+      - name: Typecheck
+        run: npm run typecheck -w "${{ matrix.workspace }}"
+
+      - name: Test
+        run: npm run test -w "${{ matrix.workspace }}"
+
+  rust-bridge:
+    name: Rust Bridge
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt
+
+      - name: Cache Rust dependencies
+        uses: Swatinem/rust-cache@v2
+
+      - name: Rust fmt
+        working-directory: services/rust-bridge
+        run: cargo fmt --check
+
+      - name: Rust check
+        working-directory: services/rust-bridge
+        run: cargo check
+
+      - name: Rust test
+        working-directory: services/rust-bridge
+        run: cargo test

package/.github/workflows/npm-release.yml

@@ -0,0 +1,67 @@
+name: NPM Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+concurrency:
+  group: npm-release-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Publish package to npm
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+          cache: npm
+          cache-dependency-path: package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Verify package is publishable
+        run: |
+          node -e "const p=require('./package.json'); if (p.private) { throw new Error('package.json has private=true; cannot publish'); } if (!p.name || !p.version) { throw new Error('package.json must include name + version'); }"
+
+      - name: Verify tag version matches package version
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PACKAGE_VERSION="$(node -p "require('./package.json').version")"
+          if [ "${TAG_VERSION}" != "${PACKAGE_VERSION}" ]; then
+            echo "Tag version (${TAG_VERSION}) does not match package.json version (${PACKAGE_VERSION})."
+            exit 1
+          fi
+
+      - name: Show package contents
+        run: npm pack --dry-run
+
+      - name: Verify NPM token secret
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          if [ -z "${NODE_AUTH_TOKEN}" ]; then
+            echo "NPM_TOKEN secret is missing."
+            exit 1
+          fi
+
+      - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --access public

package/AGENTS.md

@@ -0,0 +1,120 @@
+# AGENTS
+
+## Project Purpose
+- Monorepo for controlling Codex from mobile:
+  - `apps/mobile`: Expo React Native client (Threads, Terminal, Git, Settings).
+  - `services/rust-bridge`: Rust WebSocket JSON-RPC bridge that wraps `codex app-server` plus terminal/git helpers.
+  - `services/mac-bridge`: legacy TypeScript bridge kept for reference.
+
+## Repo Layout
+- `apps/mobile`: UI and API client code.
+  - API layer: `src/api/*`
+  - Screens: `src/screens/*`
+- `services/rust-bridge`: primary backend bridge service.
+  - WS RPC server + app-server adapter: `src/main.rs`
+- `services/mac-bridge`: backend bridge service.
+  - HTTP/WS server: `src/server.ts`, `src/index.ts`
+  - Service adapters: `src/services/*`
+  - Shared protocol types: `src/types.ts`
+- Root `package.json`: npm workspaces + common scripts.
+
+## Setup
+1. Install deps:
+   - `npm install`
+2. Copy env examples:
+   - `cp apps/mobile/.env.example apps/mobile/.env`
+   - `cp services/rust-bridge/.env.example services/rust-bridge/.env`
+
+## Open Source License Requirements
+- Follow `docs/open-source-license-requirements.md` for licensing and third-party notice obligations.
+- For any release/distribution changes, ensure the guide remains satisfied before merge.
+
+### Starting the Bridge
+
+The bridge does **not** auto-load `.env` files. All environment variables must be passed inline.
+
+```bash
+BRIDGE_HOST=0.0.0.0 \
+BRIDGE_PORT=8787 \
+BRIDGE_ALLOW_INSECURE_NO_AUTH=true \
+CODEX_CLI_BIN=codex \
+BRIDGE_WORKDIR="$(pwd)" \
+npm run -w @codex/rust-bridge dev
+```
+
+- `BRIDGE_HOST=0.0.0.0` binds to all interfaces so the phone on the same LAN can reach it. Without this it defaults to `127.0.0.1` (localhost only).
+- `BRIDGE_ALLOW_INSECURE_NO_AUTH=true` disables auth for local development. Without it the bridge will throw `BRIDGE_AUTH_TOKEN is required`.
+- `CODEX_CLI_BIN=codex` tells the bridge which Codex binary to use. Make sure `codex` is in your PATH.
+- `BRIDGE_WORKDIR` sets the root directory for git/terminal operations.
+
+The shorthand `npm run bridge` only sets `BRIDGE_WORKDIR` — it will fail unless the other vars are already exported in your shell.
+
+### Starting Expo
+
+```bash
+npm run mobile
+```
+
+This runs `expo start` in the `apps/mobile` workspace. It loads `apps/mobile/.env` automatically.
+
+Make sure `EXPO_PUBLIC_HOST_BRIDGE_URL` in `apps/mobile/.env` points to your host machine's LAN IP and the bridge port:
+```
+EXPO_PUBLIC_HOST_BRIDGE_URL=http://<YOUR_LAN_IP>:8787
+```
+
+Find your LAN IP with `ifconfig en0 | grep inet` (macOS) or `ip addr` (Linux). The phone and the host machine must be on the same network.
+
+Optionally run on a specific platform:
+- `npm run ios`
+- `npm run android`
+
+## Core Commands
+- `npm run lint` (all workspaces)
+- `npm run typecheck` (all workspaces)
+- `npm run build` (all workspaces)
+- `npm run -w @codex/rust-bridge dev` (bridge run mode)
+- `npm run -w apps/mobile start` (Expo dev server)
+
+## Architecture Notes
+- Mobile app creates one `HostBridgeApiClient` and one `HostBridgeWsClient` in `App.tsx` and passes them to screen components.
+- Threads, Terminal, and Git screens keep local `useState` and call typed API helpers in `apps/mobile/src/api/client.ts`.
+- Bridge exposes:
+  - WebSocket JSON-RPC (`/rpc`) for thread, turn, approvals, terminal, and git operations.
+  - Optional HTTP `/health` endpoint.
+- App-server events (`turn/*`, `item/*`) are forwarded over WS; approval prompts are surfaced as `bridge/approval.*`.
+
+## Coding Conventions
+- Keep changes in `src/` only; do not manually edit build artifacts.
+- Preserve strong typing across bridge contracts (`services/rust-bridge/src/main.rs`, `apps/mobile/src/api/types.ts`).
+- Prefer small service-layer additions over bloating the main RPC router.
+- For mobile, keep API requests in `src/api/client.ts` and UI logic in screen files.
+
+## Security Guardrails
+- Treat bridge as trusted-network only until auth is added:
+  - `bridge/terminal/exec` executes shell commands.
+  - `bridge/git/*` can mutate repository state.
+- Never expose `services/rust-bridge` directly to the public internet in current form.
+- If adding new execution endpoints, enforce authentication/authorization first.
+
+## Known Risks
+- WebSocket broadcast path has limited resilience for slow/broken clients.
+- Thread/run cache updates can race under concurrent writes.
+- Mobile WS client currently lacks robust reconnect/backoff behavior.
+- npm audit still reports high vulnerabilities from Expo’s transitive toolchain (`minimatch` path) even on latest stable Expo.
+
+## Testing Expectations
+- Current safety net is lint + typecheck + manual smoke tests.
+- Minimum pre-merge checks:
+  - `npm run lint`
+  - `npm run typecheck`
+  - exercise bridge endpoints and WS flow
+  - open mobile app and verify Threads + Terminal + Git screens
+- Add tests for new API behavior when feasible (no test harness is currently configured).
+
+## Common Pitfalls
+- Bridge requires accessible `codex` CLI and `git` binaries in runtime PATH.
+- On real devices, use LAN host for bridge URL instead of localhost.
+- Endpoint changes must be mirrored in mobile `src/api/types.ts` + client methods.
+- Keep environment handling explicit; avoid relying on implicit cwd assumptions.
+- If Expo Go shows a Worklets JS/native mismatch, align Expo-compatible versions (`react-native-reanimated@4.1.1` with `react-native-worklets@0.5.1`) and reinstall cleanly.
+- If Expo shows `Failed to create a worklet`, ensure `apps/mobile/babel.config.js` includes `plugins: ['react-native-reanimated/plugin']` and restart with `expo start --clear`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohit Patil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.