mirror of
https://github.com/ruvnet/RuView
synced 2026-07-20 17:03:24 +00:00
ruv
d0525359d4
ADR-125 Tier 2 "Shortcuts-as-glue" item. Three files under
`scripts/macos-shortcuts/`:
README.md one-time operator setup + architecture diagram
announce-via-homepod.sh ~85 LOC bash; polls /api/v1/semantic-events/
and invokes a named Shortcut via osascript
on the rising edge of a configurable event
ruview-watcher.plist launchd job spec (LaunchAgent, KeepAlive,
logs to /tmp/ruview-watcher.{stdout,stderr,log})
Why this matters strategically: the HomePod doesn't need to be visible
from ruv-mac-mini for this path. The Mac mini is iCloud-paired into the
operator's Home graph; Shortcuts.app reaches the HomePod via that graph,
not via local mDNS. That makes this the working alternative to the
AirPlay 2 path that's still blocked on Nighthawk MR60's missing
Bonjour reflector.
Smoke test on real C6 (real hardware, no mocks):
$ ~/announce-via-homepod.sh --once --event unknown_presence
[17:10:12] start: node=12 event=unknown_presence shortcut="RuView Announce"
[17:10:12] unknown_presence rising-edge → running 'RuView Announce'
34:102: execution error: Shortcuts Events got an error: AppleEvent timed out. (-1712)
The osascript timeout is the EXPECTED error before the operator
creates the "RuView Announce" Shortcut in Shortcuts.app — the
trigger logic is verified working. Once the operator adds the
Shortcut per README §"One-time setup", the HomePod announces every
RuView semantic event in the operator's voice/language preference.
Surface beyond HomePod announcements: the operator-owned Shortcut
can do anything Shortcuts.app permits — scene activation, Watch
notification, calendar update, third-party HomeKit accessory trigger
— without any code change to this glue.
Refs ADR-125 §1.4 "Tier 2 — Shortcuts-as-glue", §2.1.d.
Co-Authored-By: claude-flow <ruv@ruv.net>
97 lines
3.8 KiB
Markdown
97 lines
3.8 KiB
Markdown
# macOS Shortcuts ↔ RuView bridge (ADR-125 §1.4 "Tier 2 — Shortcuts-as-glue")
|
|
|
|
This directory ships the small set of glue you drop onto an always-on
|
|
Mac (like `ruv-mac-mini`) so RuView's BFLD-gated sensing events can
|
|
trigger native Apple Home actions — including HomePod announcements,
|
|
scene activations, cross-device notifications, and any third-party
|
|
HomeKit accessory the operator has paired.
|
|
|
|
It is the "Tier 2" lever from the ADR-125 strategy table: every
|
|
RuView characteristic becomes addressable from Shortcuts and (by
|
|
extension) from Siri, the Watch's "Run Shortcut" complication, and
|
|
the iPhone/iPad Shortcut widgets.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
real C6 (192.168.1.179, ruv.net)
|
|
→ UDP feature_state → c6-presence-watcher.py → BFLD PrivacyGate
|
|
→ /tmp/ruview-last-feature.json
|
|
→ ruview-sensing-server.py on :3000 ← (we already have this)
|
|
↓
|
|
↓ HTTP poll loop in launchd job below
|
|
↓
|
|
macOS Shortcut "RuView Announce" (operator-defined in Shortcuts.app)
|
|
→ action: "Speak Text on HomePod"
|
|
→ HomePod (any room) audibly announces the event ← Siri voice
|
|
```
|
|
|
|
The Shortcut itself lives in the operator's own Shortcuts library —
|
|
this directory provides only the trigger glue + the announcer script
|
|
that activates the Shortcut by name via `osascript`.
|
|
|
|
## One-time setup on the Mac
|
|
|
|
1. **Create the Shortcut** in `Shortcuts.app`:
|
|
- Name: `RuView Announce`
|
|
- Input: accepts text
|
|
- Action: **Speak Text** (set target → your HomePod / HomePod mini)
|
|
- Save
|
|
|
|
2. **Verify it runs from the command line**:
|
|
```sh
|
|
osascript -e 'tell application "Shortcuts Events" to run shortcut "RuView Announce" with input "Test from RuView"'
|
|
```
|
|
The HomePod should speak "Test from RuView".
|
|
|
|
3. **Install the launchd job**:
|
|
```sh
|
|
cp ruview-watcher.plist ~/Library/LaunchAgents/com.ruvnet.ruview.watcher.plist
|
|
launchctl load ~/Library/LaunchAgents/com.ruvnet.ruview.watcher.plist
|
|
```
|
|
`launchctl list | grep ruvnet` should show the job loaded.
|
|
|
|
4. **Tail the log** while you walk past the C6 to verify it fires:
|
|
```sh
|
|
tail -f /tmp/ruview-watcher.log
|
|
```
|
|
|
|
## Files
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `announce-via-homepod.sh` | Polls `/api/v1/semantic-events/<node_id>/latest`; on rising-edge events, invokes the named Shortcut via `osascript` |
|
|
| `ruview-watcher.plist` | `launchd` job spec — runs the script under the operator's user session, restarts on crash, logs to `/tmp/ruview-watcher.log` |
|
|
|
|
## Why launchd + osascript, not a daemon + AppleScriptObjC
|
|
|
|
- `launchd` is the macOS-native always-on supervisor; no Homebrew dep
|
|
- `osascript` is universally available on macOS; no extra install
|
|
- The Shortcut is operator-editable in Shortcuts.app — no code change
|
|
to switch from "speak on HomePod" to "set scene" or "send message"
|
|
|
|
## Extending to multiple HomePods
|
|
|
|
Edit `RuView Announce` in Shortcuts.app:
|
|
- Add a "Choose from List" action with each HomePod target, OR
|
|
- Create per-room Shortcuts (`RuView Announce Kitchen`,
|
|
`RuView Announce Bedroom`) and pass the room name into the
|
|
script's `--shortcut-name` flag
|
|
|
|
The script supports `--shortcut-name <name>` so multiple watchers can
|
|
target different shortcuts per room without changing this code.
|
|
|
|
## Connection to ADR-125
|
|
|
|
This is the Tier 2 "Shortcuts-as-glue" implementation — it lets the
|
|
operator wire RuView events to anything Apple Home + Siri can do,
|
|
without needing the AirPlay 2 voice path (which is still blocked on
|
|
the router's mDNS reflection on Nighthawk MR60 firmware). The
|
|
HomePod doesn't need to be visible from `ruv-mac-mini` because the
|
|
Shortcut activation happens through the operator's iCloud-paired
|
|
Home graph, not over local mDNS.
|
|
|
|
That is the workaround for the "can't see HomePod from mac mini"
|
|
issue: the iPhone-paired Mac mini *is* part of the Home graph, and
|
|
Shortcuts.app uses that graph (not Bonjour) to reach the HomePod.
|