auto-mobile: Instructions file for Claude Code

AutoMobile

Node TypeScript MCP server providing Android Debug Bridge (ADB) capabilities through MCP tool calls for device automation.

Key Rules

• TypeScript only (no JavaScript) for application code. The one exception is lint tooling: oxlint-plugins/auto-mobile.mjs (oxlint's plugin API is JS-first), as eslint.config.mjs was before it. Every rule in it is covered by the fast unit tests under test/lint/.
• 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-*/.
• Use scripts/prepush.sh to select and run the relevant per-lane pre-push gates.
• Changes to package.json or bun.lock select runtime-pins, node, and integration lanes; runtime-graph input changes also require scripts/prepush-integration.sh.
• 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
• iOS tests never run on Linux or Windows. Do not hand-guard iOS test files: test/macos-only-tests.txt classifies them (an iOS path token such as ios, simctl, devicectl or simulator makes a test macOS-only; portable rules keep cross-platform logic running everywhere) and scripts/test-ts.sh skips them off macOS. A new test that imports only iOS source needs a rule there; test/lint/macOsOnlyTestClassification.integration.test.ts enforces it. See docs/design-docs/ci/macos-only-tests.md.
• 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. The isolated re-runs run serially after all shards, each bracketed by a calibration probe (runner-calibration.ts measure); a run whose probe reads above BUN_TEST_TIMING_CONTENTION_SLOWDOWN (1.5x) AND whose sample is over budget is retried up to BUN_TEST_TIMING_CONTENTION_RETRIES (2) times, only while the remaining recheck budget still covers one attempt for every run left to verify, and the least-contended attempt is kept (an under-budget sample is conclusive and never retried). Samples are never scaled, so a slow test still fails on a contended runner; the summary reports the probe slowdown beside each verdict and flags any shard with BUN_TEST_TIMING_CONTENDED_SHARD_MIN (10) over-budget first samples as "Runner contended".
• One canonical primitive per concern: UUIDs come from IdGenerator, randomness from Random (pick/next), backoff from Backoff. Inject these (interface + fake) rather than spawning a new randomUUID()/Math.random() path.
• Prefer narrow interfaces that expose exactly what consumers need (YAGNI); grow the interface when the second consumer arrives, not ahead of need.
• Unit tests must never resolve the real file-backed getDatabase(). Under bun test, NODE_ENV=test arms a guard that throws when a test resolves the default ~/.auto-mobile DB (issue #3067). Inject an in-memory DB via createTestDatabase(), or use a helper: test/helpers/navigationTestHarness.ts (in-memory NavigationGraphManager singleton + telemetry spy), test/db/inMemorySingletonDatabase.ts (:memory: singleton for identity checks), or test/helpers/tempFileDatabase.ts (temp-dir file DB for real getInstance/getInstanceForSession semantics). Resolve getDatabase() lazily (a getter), never in a field initializer, so construction alone can't trip the guard. The test preload (test/setup/testPreload.ts) is for suite-wide telemetry neutralization, not DB guard arming.