flynn/docs/plans/2026-02-16-companion-platform-clients-foundation-checklist.md

Companion Platform Clients Foundation Checklist (2026-02-16)

Scope

• Build platform-focused companion wrappers on top of CompanionRuntimeClient so app runtimes can use stable, platform-specific methods without manual RPC payload shaping.
• Cover macOS, iOS, and Android runtime surfaces.

Implementation

• Added src/companion/platformClients.ts with:
  • MacOSCompanionClient
  • IOSCompanionClient
  • AndroidCompanionClient
• Standardized shared operations for each platform client:
  • connect() / disconnect()
  • register()
  • getCapabilities()
  • setStatus() (platform pinned per client)
  • setLocation() / getLocation()
  • getSystemCapabilities()
  • listNodes() (platform + role filtered)
• Platform push registration semantics:
  • macOS/iOS -> APNs (node.push_token.set provider apns)
  • Android -> FCM (node.push_token.set provider fcm)

Tests

• Added src/companion/platformClients.test.ts.
• Verified wrapper behavior with runtime mock coverage for:
  • platform-specific node.status.set payloads
  • APNs vs FCM push provider enforcement by wrapper
  • platform-filtered system.nodes queries

Docs Updated

• README.md companion section now references platformClients.ts wrappers.
• docs/api/PROTOCOL.md implementation references now include platform wrappers.