Split native input backend resolver and concrete backends into focused modules

[shaun0927]

Tracked by #713.

Background

src/tools/native-input-backend.ts combines multiple concrete backends, routing policy, process-wide caches, Flutter resolver logic, and test reset hooks. This makes headless input behavior harder to change safely.

Objective

Separate native input backend implementations and routing policy into focused modules with explicit dependencies.

Scope

• Create shared backend interfaces.
• Move each concrete backend to its own module.
• Move resolver/caching logic into an injectable resolver class.
• Keep existing exported helper API during migration.

Target files and paths

• src/tools/native-input-backend.ts
• new src/input/backend.ts
• new src/input/simctl-backend.ts
• new src/input/applescript-backend.ts
• new src/input/webkit-backend.ts
• new src/input/flutter-resolver.ts
• new src/input/backend-resolver.ts
• tests/unit/native-input-backend.test.ts

Implementation steps

1. Define InputBackend and backend kind types.
2. Move Simctl backend without changing behavior.
3. Move AppleScript backend and keep opt-in guard.
4. Move WebKit backend and shared DOM input scripts if available.
5. Move resolver state from module globals into an instance.
6. Keep compatibility exports and migrate callers gradually.

Acceptance criteria

• Existing native input tests pass.
• Backend fallback order is unchanged.
• Resolver state can be reset through an explicit test hook or new instance.
• File responsibility boundaries are visible from module names.

Verification

• npm run lint -- --quiet
• npm test -- --runInBand tests/unit/native-input-backend.test.ts
• Manual smoke for at least one WebKit input and one native-app input path.

Dependencies / recommended order

Run after process-spawn optimization or as preparation for it. Split by backend if review size grows.

Risks and cautions

• Do not promote experimental backends.
• Do not change fallback semantics while moving files.
• Avoid changing public tool behavior in refactor PRs.

Non-goals

• Do not solve SimulatorKit research issues.
• Do not remove AppleScript fallback.
• Do not redesign app interaction tool schemas.

Ambiguity reducers

• “Concrete backend” means a class that sends input through one mechanism.
• “Resolver” means policy that chooses a backend for a requested operation and context.
• Module globals should be replaced only where an equivalent instance-owned state is available.

Validity review

Proceed as a P2 maintainability item. It is valid because native input is a strategic product surface.

Implementation detail refinements

• Keep compatibility exports until all callers migrate.
• Use one PR per backend extraction if necessary.
• Document fallback order in tests rather than relying on comments only.

Verification checklist reinforcement

• Fallback order test passes.
• Each backend module compiles independently through TypeScript imports.
• Resolver state reset is deterministic in tests.
• No tool schema changes occur.

[shaun0927]

Verification-definition update (2026-05-12)

This issue is a multi-PR refactor. After the currently open PR #731 merges, treat it as a substantial resolver/backend slice, not automatically as full issue closure.

Completed / pending slice ledger

• Slice A — backend/resolver split: merge PR refactor(input): split backends and resolver into focused modules (#707 a) #731 once checks are green.
  • Evidence from PR: new src/input/* backend/resolver modules, resolver instance state, reset semantics, fallback-order coverage.
  • PR-local validation reported: tests/unit/native-input-backend.test.ts 80/80 passed and tests/unit/input-backend-resolver.test.ts 14/14 passed.
• Remaining validation: confirm whether DOM input script centralization in Centralize DOM input script builders for WebKit and native input paths #709 changes imports or shared script ownership after refactor(input): split backends and resolver into focused modules (#707 a) #731 lands.

Post-merge verification required before closing #707

• npm run lint -- --quiet
• npm test -- --runInBand tests/unit/native-input-backend.test.ts tests/unit/input-backend-resolver.test.ts
• TypeScript/build check for touched modules, preferably npm run build:cli.
• Manual smoke for at least one WebKit input path and one native-app input path.
• Confirm backend fallback order is unchanged.
• Confirm resolver state reset/new instance behavior is deterministic in tests.
• Confirm no public MCP tool schema changed.

Stale-state guard

If #709 lands before or after #731, re-check imports and ownership so this issue does not close with duplicated DOM script builders or stale backend paths.

[shaun0927]

검증 완료(2026-05-16 KST): 최신 origin/develop / OpenSafari v0.6.0 기준으로 해당 이슈의 실행 가능한 체크리스트를 확인했습니다.

Evidence:

• PR-linked implementation is merged into develop.
• npm test -- --runTestsByPath ... targeted suites: 10 suites / 103 tests passed for HTTP auth, high-risk HTTP gating, auth persistence, audit logging, network interception, zombie cleanup, and device_boot WebKit retry.
• Broader targeted suites: 23 suites / 557 tests passed for lazy tool registration, proxy readiness, WebKit performance/refactors, socket discovery cache, simulator lifecycle/refactors, native input backends, DOM input scripts, coordinate-space, and AX diagnostics.
• npm run lint -- --quiet ... passed for the changed/validated paths.
• npm run build passed for v0.6.0.
• Real OpenSafari HTTP smoke: serve --http bound to 127.0.0.1; /health returned 200; unauthenticated /mcp returned 401; authenticated initialize succeeded; disallowed CORS origin returned 403.
• Real OpenSafari device smoke for Recover device_boot when WebKit client registration fails #756: device_boot on iPhone 16 iOS 26.4 returned a booted device and proxy; subsequent diagnose retained the simulator in device even while WebKit was unavailable.

체크리스트 중 외부 앱/장기 수동 검증 성격이 아닌 항목은 모두 체크 가능하다고 판단하여 완료로 닫습니다.