feat(companion): add generated macos ios android reference app surfaces

2026-02-26 19:37:28 -08:00
parent 3839c04a7d
commit be8b1f29a4
22 changed files with 419 additions and 5 deletions
@@ -0,0 +1,9 @@
+# Companion Reference Apps
+
+This directory contains generated companion starter shells for:
+
+- macOS menu-bar style wrapper
+- iOS shell
+- Android shell
+
+These are reference starters, not production binaries. Use them as a baseline for app packaging and distribution workflows.
@@ -0,0 +1,32 @@
+package flynn.companion
+
+// Reference Android bootstrap model for integrating with Flynn gateway runtime.
+// Wire FCM token refresh to node.push_token.set and app lifecycle to heartbeat publishing.
+
+data class CompanionBootstrap(
+  val schemaVersion: Int,
+  val generatedAt: String,
+  val gateway: Gateway,
+  val node: Node,
+  val runtime: Runtime
+)
+
+data class Gateway(
+  val url: String,
+  val token: String?
+)
+
+data class Node(
+  val nodeId: String,
+  val role: String,
+  val platform: String,
+  val capabilities: List<String>
+)
+
+data class Runtime(
+  val heartbeatSeconds: Int,
+  val handoffTimeoutMs: Int,
+  val autoReconnect: Boolean
+)
+
+// Generated for node: android-reference-shell (android)
@@ -0,0 +1,11 @@
+# Flynn Companion android Shell Template
+
+This directory contains a generated starter template for a android companion shell.
+
+Files:
+- `companion.bootstrap.json`: resolved Flynn companion bootstrap contract
+- `CompanionBootstrap.kt`: platform-native starter model/wrapper snippet
+
+Notes:
+- These templates are intentionally minimal and should be integrated into your app project.
+- Runtime transport should use Flynn gateway JSON-RPC node methods (`node.register`, `node.status.set`, `node.location.set`, `node.push_token.set`).
@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-02-27T03:35:54.245Z",
+  "gateway": {
+    "url": "ws://127.0.0.1:18800"
+  },
+  "node": {
+    "nodeId": "android-reference-shell",
+    "role": "companion",
+    "platform": "android",
+    "capabilities": [
+      "ui.canvas",
+      "node.status.write",
+      "node.location.write",
+      "node.push.register"
+    ]
+  },
+  "runtime": {
+    "heartbeatSeconds": 30,
+    "handoffTimeoutMs": 120000,
+    "autoReconnect": true
+  }
+}
@@ -0,0 +1,32 @@
+import Foundation
+
+// Reference iOS bootstrap model for integrating with Flynn gateway runtime.
+// Wire APNs token refresh to node.push_token.set and app lifecycle to heartbeat publishing.
+
+struct CompanionBootstrap: Codable {
+  let schemaVersion: Int
+  let generatedAt: String
+  let gateway: Gateway
+  let node: Node
+  let runtime: Runtime
+}
+
+struct Gateway: Codable {
+  let url: String
+  let token: String?
+}
+
+struct Node: Codable {
+  let nodeId: String
+  let role: String
+  let platform: String
+  let capabilities: [String]
+}
+
+struct Runtime: Codable {
+  let heartbeatSeconds: Int
+  let handoffTimeoutMs: Int
+  let autoReconnect: Bool
+}
+
+// Generated for node: ios-reference-shell (ios)
@@ -0,0 +1,11 @@
+# Flynn Companion ios Shell Template
+
+This directory contains a generated starter template for a ios companion shell.
+
+Files:
+- `companion.bootstrap.json`: resolved Flynn companion bootstrap contract
+- `CompanionBootstrap.swift`: platform-native starter model/wrapper snippet
+
+Notes:
+- These templates are intentionally minimal and should be integrated into your app project.
+- Runtime transport should use Flynn gateway JSON-RPC node methods (`node.register`, `node.status.set`, `node.location.set`, `node.push_token.set`).
@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-02-27T03:35:54.245Z",
+  "gateway": {
+    "url": "ws://127.0.0.1:18800"
+  },
+  "node": {
+    "nodeId": "ios-reference-shell",
+    "role": "companion",
+    "platform": "ios",
+    "capabilities": [
+      "ui.canvas",
+      "node.status.write",
+      "node.location.write",
+      "node.push.register"
+    ]
+  },
+  "runtime": {
+    "heartbeatSeconds": 30,
+    "handoffTimeoutMs": 120000,
+    "autoReconnect": true
+  }
+}
@@ -0,0 +1,38 @@
+import Foundation
+
+struct CompanionBootstrap: Codable {
+  let schemaVersion: Int
+  let generatedAt: String
+  let gateway: Gateway
+  let node: Node
+  let runtime: Runtime
+}
+
+struct Gateway: Codable {
+  let url: String
+  let token: String?
+}
+
+struct Node: Codable {
+  let nodeId: String
+  let role: String
+  let platform: String
+  let capabilities: [String]
+}
+
+struct Runtime: Codable {
+  let heartbeatSeconds: Int
+  let handoffTimeoutMs: Int
+  let autoReconnect: Bool
+}
+
+// Reference entrypoint for a menu-bar app wrapper.
+// Production apps should prefer in-process runtime integration over shelling out.
+func launchFlynnCompanion() throws {
+  let task = Process()
+  task.executableURL = URL(fileURLWithPath: "/bin/bash")
+  task.arguments = ["./run-companion.sh"]
+  try task.run()
+}
+
+// Generated for node: macos-reference-shell (macos)
@@ -0,0 +1,11 @@
+# Flynn Companion macos Shell Template
+
+This directory contains a generated starter template for a macos companion shell.
+
+Files:
+- `companion.bootstrap.json`: resolved Flynn companion bootstrap contract
+- `MenuBarCompanion.swift`: platform-native starter model/wrapper snippet
+
+Notes:
+- These templates are intentionally minimal and should be integrated into your app project.
+- Runtime transport should use Flynn gateway JSON-RPC node methods (`node.register`, `node.status.set`, `node.location.set`, `node.push_token.set`).
@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-02-27T03:35:54.245Z",
+  "gateway": {
+    "url": "ws://127.0.0.1:18800"
+  },
+  "node": {
+    "nodeId": "macos-reference-shell",
+    "role": "companion",
+    "platform": "macos",
+    "capabilities": [
+      "ui.canvas",
+      "node.status.write",
+      "node.location.write",
+      "node.push.register"
+    ]
+  },
+  "runtime": {
+    "heartbeatSeconds": 30,
+    "handoffTimeoutMs": 120000,
+    "autoReconnect": true
+  }
+}