Files

Den 3c88e16ae5 fix(funnel): repair activation-path bugs found in end-to-end audit (#114 )

Systematic trace of the activation funnel (store listing -> docs setup
guide -> in-app onboarding -> connect flow) after #113 showed a docs
404 bug had slipped through. Fixes found in this pass:

- README.md and CONTRIBUTING.md still told developers to run
  `npm install -g opencode` (missing -ai), the exact 404 #113 fixed
  everywhere else. Same package-name fix applied here.
- src/lib/diagnostics.ts: the health probe reported ok:true for any
  resolved fetch, including 401/403/404/500 responses. A wrong
  password or broken server therefore classified as "Health endpoint
  responded - connection actually works now.", contradicting the
  error shown right next to it. Health now requires a real 2xx;
  root-reachability probe explicitly opts out (requireOk: false) to
  keep its existing reachability-only semantics (already encoded in
  diagnostics-classify.test.ts).
- docs-site/vs-termux: architecture explainer described
  /session/{id}/events and /session/{id}/chat, neither of which
  exists; the app actually uses /global/event and
  /session/{id}/prompt_async (src/lib/sdk.ts).
- docs-site/features: opencode repo link pointed at
  github.com/opencode-ai/opencode instead of github.com/sst/opencode,
  the org used everywhere else in the docs.
- Stale "v0.4.3" version strings (README x3, docs-site/download x2)
  bumped to v0.4.7, the actual latest shipped release confirmed live
  on GitHub Releases and the F-Droid repo index. Fixed the associated
  Android min-OS contradiction (7.0 vs 8.0+) to 7.0, matching the live
  F-Droid manifest's minSdkVersion 24.
- Dropped stale "GPT-4" model naming on 3 docs-site pages, consistent
  with the model-agnostic policy already applied to the Play listing
  in #83.

See PR body for the found-not-fixed list (Play Console listing drift,
GitHub Sponsors not enabled, a Cloud-vs-waitlist messaging conflict)
that need a product/human decision rather than a code fix.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

2026-07-17 21:47:13 -07:00

5.2 KiB

Raw Blame History

Contributing to OpenCode Mobile

Thank you for your interest in contributing. This document covers how to set up the dev environment, run the app, connect to a local opencode server for testing, code style, and the contribution process.

Dev environment setup
Running on an emulator or device
Connecting to a local opencode server
Code style and linting
Filing a bug
Proposing a feature
Submitting a pull request
Developer Certificate of Origin
Code of Conduct

Dev environment setup

Prerequisites

Node.js 18 or 20 (check with node --version)
npm 9+ or bun (bun is faster — install via npm install -g bun)
Expo CLI: npm install -g expo-cli (optional — npx expo works too)
For Android: Android Studio + an AVD or a physical device with USB debugging
For iOS: macOS + Xcode 15+

Clone and install

git clone https://github.com/dzianisv/opencode-mobile.git
cd opencode-mobile
npm install       # or: bun install

Environment variables

Copy the example env file and fill in optional values (Sentry DSN is only needed for crash testing):

cp .env.example .env   # if the example doesn't exist yet, skip this

Running on an emulator or device

Android

# Start an Android emulator from Android Studio first, then:
npx expo start --android

# Or run the dev build directly:
npm run android

iOS (macOS only)

npx expo start --ios

# Or:
npm run ios

Expo Go (fastest for quick experiments)

npx expo start
# Scan the QR code with Expo Go on your phone

Note: Some native modules (biometric auth, secure store) require a development build and will not work in Expo Go. Use npx expo run:android / npx expo run:ios for a full dev build.

Connecting to a local opencode server

You need a running opencode server to test the app end-to-end.

# Install opencode
npm install -g opencode-ai

# Start it in server mode on all interfaces
OPENCODE_SERVER_PASSWORD=devpassword opencode serve --hostname 0.0.0.0 --port 4096

In the app, add a connection:

Emulator on same machine: http://10.0.2.2:4096 (Android AVD) or http://localhost:4096 (iOS Simulator)
Physical device on same LAN: http://<your-machine-LAN-IP>:4096
Tunnel for remote testing: run npx cloudflared tunnel --url http://localhost:4096 and use the provided HTTPS URL

Code style and linting

The project uses ESLint and TypeScript strict mode. Run before committing:

npm run lint          # ESLint
npm run typecheck     # TypeScript type check (tsc --noEmit)

There is no auto-formatter enforced by CI yet (Prettier is configured but optional). Keeping existing style consistent is more important than personal preference.

Key conventions:

Components: functional, with typed props via TypeScript interface
State: Zustand stores in src/stores/
API calls: through the SDK client in src/lib/
Screens: file-based routing via Expo Router under app/

Filing a bug

Use the Bug Report template.

Please include:

App version (visible in Settings screen)
opencode server version (opencode --version)
OS and version (e.g. Android 14, iOS 17.4)
Steps to reproduce
What you expected vs. what happened
Crash logs or screenshots if available

Security vulnerabilities: do NOT file public issues. See SECURITY.md.

Proposing a feature

Use the Feature Request template or start a GitHub Discussion if you want to explore the idea before opening a formal issue.

Submitting a pull request

Fork the repo and create a branch off main: git checkout -b feat/my-feature
Make your changes. Keep commits focused — one logical change per commit.
Ensure npm run lint and npm run typecheck pass.
If you changed UI, include a screenshot in the PR description.
Open the PR against dzianisv/opencode-mobile main. Fill in the PR template.
A maintainer will review within a few business days.

PRs that add new npm dependencies will receive extra scrutiny — keep the bundle lean.

Developer Certificate of Origin

This project does not require a formal Contributor License Agreement (CLA). By submitting a pull request you confirm that:

You wrote the contribution yourself, or have the right to submit it under the MIT License.
You grant VIBE TECHNOLOGIES, LLC and the project's users a perpetual, worldwide, royalty-free license under the MIT License terms.

That's it — no paperwork.

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. Please treat everyone with respect. Report issues to support@agentlabs.cc.

5.2 KiB Raw Blame History