auto-mobile CLAUDE.md

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/.
• 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 — 625 references in src/, zero 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
• 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
• 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.
• 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.