auto-mobile: Instructions file for Codex

AutoMobile

Bun TypeScript MCP server providing Android & iOS device automation capabilities through its tools and resources. Kotlin & Swift supporting libraries and apps in android/ and ios/ respectively.

Key Rules

• TypeScript only (no JavaScript)
• Docs have two audiences, and neither is a changelog. docs/using/ is for end users only: what to call, parameters, results, errors and what to do — no source paths, class names, issue-number rationale, or AutoMobile's own CI/test harness. docs/design-docs/ holds technical internals: architecture, contracts, invariants, failure modes and why a choice was made. Keep both concise and current-state: do not add progress logs, status checklists, dated history, per-PR/issue narration, or pasted run output to either; that belongs in the PR description, commit message, or issue. Update a doc only when the behavior it describes changes, by editing the existing statement in place.
• Write GitHub issue and pull request references as clickable Markdown links only in AI-authored prose a human reads directly — issue and PR bodies, review comments, commit messages, and assistant chat responses — where a clickable link genuinely aids navigation for the reader. Do NOT require links in checked-in repository content: neither source code comments (bare #NNNN is the established convention — src/ references are bare, never linked) nor Markdown documentation files (under docs/ and elsewhere), where bare #NNNN is likewise fine. Forcing explicit links into committed files renders as noise in an editor and makes the touched file the only inconsistent one. Automated reviewers (e.g. Codex) must NOT flag bare #NNNN references that appear in source-code comments or Markdown files; treat those as compliant.
• After implementation changes, run relevant validation commands
• Before pushing shell/scripts changes, run scripts/prepush-shell.sh and bun run format (the formatter catches Fast Validation fan-out); if bun.lock and/or package.json changed in the diff, run bun scripts/release/pin-runtime-deps.ts --write and commit package.json, bun.lock, and scripts/release/runtime-graph.json; otherwise rebase onto current main and do not hand-edit pins to mask a stale base; never run two bats test/bats/ sweeps concurrently on one machine; when an Actions API job log is empty, read the fast-validation-logs workflow artifact's per-check .status/.log files under scratch/fast-validate-*/.
• Write terminal output to scratch/ when not visible
• Local validation scripts live under scripts/ and should almost always be written in bash with shellcheck validation
• Run scripts/prepush-android.sh from the repository root before pushing changes under android/; its scoped Detekt pass is a smoke check, not a substitute for the full-tree CI Detekt job.
• For Playground/JUnit-runner emulator CI red (on PRs both suites run in the one Run Android Emulator Tests job, scripts/android/run-emulator-suites.sh), inspect .github/actions/android-emulator boot diagnostics first: no runner-health means an infra/runner-health question, while booted tests that fail are a regression.
• Copy android/local.properties from a working checkout into each new Android worktree; it is gitignored and required for Gradle SDK resolution.
• Ktfmt normalizes runCatching{}.getOrNull() to runCatching {}.getOrNull() once; write the spaced form and do not mistake that first rewrite for a non-idempotent formatter.
• Before adding a helper, parser, or dependency, search src/, scripts/lib/, package.json, and the runtime standard library. Prefer the standard library, then an existing direct dependency, then an existing repository helper, then a small tested helper. Do not parse JSON, YAML, XML, or TypeScript with line regexes when a structured parser or typed module contract exists. For new packages, state which built-in and installed alternatives were checked. Preserve injected interfaces/FakeTimer seams where tests need deterministic control.
• Always use interfaces & fakes & FakeTimer to decouple implementations and keep tests extremely fast and non-flaky
• Unit tests should pass in 100ms or less. Do not assume that a failing test can be allowed to fail. CI enforces this per test from the JUnit reporter's time (which excludes beforeAll); a test over budget is re-run in isolation and only its MEDIAN is failed, so a genuine breach must be fixed in the test, never by raising BUN_TEST_MAX_MS.
• For Swift, prefer an existing standard-library or Foundation API before adding an extension, helper, or package. Use URLComponents plus URLQueryItem for query values and Codable for AutoMobile-owned stable schemas. Keep JSONSerialization only at documented dynamic/bridge boundaries. A convenience dependency requires a stated platform-API gap, deployment-target check, and tests using interfaces/fakes.
• For TypeScript changes, prefer the JavaScript/Node standard library, then an existing AutoMobile seam, before adding a local generic helper or direct dependency. Keep time, randomness, I/O, concurrency, and process access injectable when tests need control; justify any new direct dependency in docs/decisions/.
• For Kotlin changes, check the Kotlin stdlib, JDK/AndroidX, the module's existing dependencies, and dependency-compatible AutoMobile modules before adding a helper, wrapper, *Util file, or dependency. Prefer the narrowest existing solution; keep one-off helpers private and adjacent to their consumer. Extract shared code only for two or more real consumers, and state any intentional exception (semantics, performance, API level, compatibility, testability, or readability) in the PR summary.