feat(cli): add ax command to dump the accessibility tree

[R44VC0RP]

ran into this while having an agent drive a sim headless — an "open in app?" system dialog was silently eating every deep link we sent, and the only way to detect it was screenshotting and pixel-probing where the button should be. meanwhile the server already captures the full ax tree for the web ui overlay, it just wasn't reachable from the cli.

so this wires it up:

serve-sim ax [-d udid]

one-shot json dump of the current accessibility snapshot (roles, labels, values, enabled, frames) — same normalized shape the web ui consumes, fetched from the existing per-device /ax endpoint. errors out loud when no server is running or ax is still warming up.

serve-sim ax | jq '.elements[] | select(.role == "button") | .label'

added tests mirroring accessibility-endpoint.test.ts, lint + typecheck pass. the plumbing was already all there, this just exposes it.

Summary by CodeRabbit

• New Features

  • Added the serve-sim ax [-d udid] command to export a simulator’s accessibility tree as JSON.
  • Accessibility snapshots include screen dimensions and normalized element details such as labels, roles, values, states, and frames.
  • Added clear error reporting when the simulator server is unavailable or returns an error.

• Documentation

  • Updated CLI documentation with usage details for the new accessibility-tree command.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: b874e293-8f6d-4041-9399-eb2151eaf210

📥 Commits

Reviewing files that changed from the base of the PR and between 14ad57f and 05a2bbe.

📒 Files selected for processing (5)

• packages/serve-sim/README.md
• packages/serve-sim/src/__tests__/ax-cli.test.ts
• packages/serve-sim/src/ax-cli.ts
• packages/serve-sim/src/ax.ts
• packages/serve-sim/src/index.ts

---

📝 Walkthrough

Walkthrough

Changes

Accessibility snapshot CLI

Layer / File(s)	Summary
Snapshot retrieval and normalization packages/serve-sim/src/ax.ts, packages/serve-sim/src/ax-cli.ts, packages/serve-sim/src/__tests__/ax-cli.test.ts	Exports AX types and normalization, derives the /ax endpoint, fetches snapshots, handles HTTP errors, and tests normalization and retrieval.
CLI command wiring and output packages/serve-sim/src/index.ts, packages/serve-sim/README.md	Adds serve-sim ax [-d udid], resolves simulator state, prints the snapshot as JSON, handles failures, and documents the command.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant serve-sim ax
  participant ServerState
  participant fetchAxSnapshot
  participant AXEndpoint
  participant normalizeAxTree
  User->>serve-sim ax: run command
  serve-sim ax->>ServerState: resolve device state
  ServerState-->>serve-sim ax: return streamUrl
  serve-sim ax->>fetchAxSnapshot: request snapshot
  fetchAxSnapshot->>AXEndpoint: request derived /ax URL
  AXEndpoint-->>fetchAxSnapshot: return raw AX JSON
  fetchAxSnapshot->>normalizeAxTree: normalize RawAxeNode[]
  normalizeAxTree-->>fetchAxSnapshot: return AxSnapshot
  fetchAxSnapshot-->>serve-sim ax: return snapshot
  serve-sim ax-->>User: print JSON

Loading

Suggested reviewers: evanbacon

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding a CLI ax command to dump the accessibility tree.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}