@trillboards/edge-sdk 0.2.4 → 0.2.6

package/deploy/macos/README.md

@@ -0,0 +1,161 @@
+# Trillboards Edge — macOS CCTV Connector (.pkg)
+
+A self-contained macOS installer for the Trillboards CCTV connector. The
+customer `.pkg` bundles Node, ffmpeg, the connector, and the pinned ~2.4 GB local
+VLM. It installs and verifies local AI before camera pairing opens. The connector
+never silently sends continuous camera load to cloud inference. No Node, ffmpeg,
+Docker, or terminal is required on the operator's Mac.
+
+What lands on disk (home-domain, **no sudo / no admin password**):
+
+```
+~/Library/Trillboards/edge/
+  bin/node                 pinned official Node v22 runtime (arm64/x64)
+  bin/ffmpeg               bundled ffmpeg (from ffmpeg-static)
+  bin/trillboards-edge     launcher (puts bin/ first on PATH, execs cli.js)
+  bin/trillboards-pair     first-run pairing helper (GUI + headless)
+  lib/edge-sdk/dist/cli.js the connector CLI
+  lib/node_modules/…       runtime deps (edge-core + edge-platform-rtsp +
+                           edge-sdk), WITHOUT the heavy local-inference stack
+  share/com.trillboards.edge.plist   LaunchAgent template
+  share/ensure-litertlm.sh           background local-AI retry supervisor
+  share/models/gemma-4-E2B-it.litertlm   required customer local VLM (removed after import)
+~/Applications/Trillboards CCTV Setup.app native customer setup window (opened automatically)
+~/Library/Application Support/Trillboards/trillboards.config.json   (after pair, 0600)
+~/Library/Logs/Trillboards/edge.{out,err}.log
+~/Library/LaunchAgents/com.trillboards.edge.plist                   (after pair)
+```
+
+The connector runs as a per-user **LaunchAgent** (`RunAtLoad` + `KeepAlive`),
+bootstrapped automatically on first successful pair. The device token is
+delivered **only by pairing** — it is never baked into the `.pkg`.
+
+> The customer build includes Gemma and completes its local health check before
+> pairing. Cloud inference requires explicit configuration. `--skip-model` is
+> available only for engineering checks and must not be published.
+
+---
+
+## Install (operator)
+
+1. Download `TrillboardsEdge-<version>-arm64.pkg`.
+2. Double-click it. The installer offers **Install for me only** (home-domain) —
+   no admin password. (Equivalent CLI: `installer -pkg <pkg> -target
+   CurrentUserHomeDirectory`.)
+3. The installer installs and verifies the connector and included local AI
+   model. Only then does **Trillboards CCTV Setup** open automatically. Select
+   **Start setup**. The app opens the signed-in Trillboards camera wizard,
+   finds recorders on the local network, and validates each channel before any
+   camera screens are created. Black, disconnected, and unreadable inputs are
+   ignored. After the working cameras are saved, the already-installed local AI
+   begins sensing and the connector starts at every login. Reopen **Trillboards
+   CCTV Setup** from
+   `~/Applications` to resume or repair setup.
+
+That's it. To check it's sensing: `tail -f ~/Library/Logs/Trillboards/edge.out.log`.
+
+### Adding RTSP credentials locally (optional, creds-stay-on-prem mode)
+
+If the portal delivered camera feeds **without** an `rtspUrl` (so credentials
+never leave the venue), edit
+`~/Library/Application Support/Trillboards/trillboards.config.json` and add the
+`rtspUrl` to each camera, then restart the agent:
+
+```bash
+launchctl kickstart -k "gui/$(id -u)/com.trillboards.edge"
+```
+
+---
+
+## Build (engineering)
+
+```bash
+cd trillboards-edge-sdk
+npm install                       # ensures ffmpeg-static is fetched
+cd packages/edge-sdk/deploy/macos
+./build-macos-pkg.sh              # → dist-installer/TrillboardsEdge-<ver>-arm64.pkg
+```
+
+Options:
+
+| flag | default | meaning |
+|------|---------|---------|
+| `--arch arm64\|x64` | host arch | target architecture |
+| `--node-version vX.Y.Z` | `v22.22.0` | pinned Node runtime to bundle |
+| `--bundle-model` | on | include the pinned ~2.4 GB Gemma model required by customer setup |
+| `--skip-model` | off | build a slim engineering artifact that must not be published to customers |
+| `--offline` | off | skip the official Node download; copy the host `node` |
+| `--sign-installer "Developer ID Installer: …"` | unset | `productsign` the pkg |
+
+The build is idempotent (it wipes its staging tree each run) and **smoke-tests
+the staged bundle** (`trillboards-edge version`) before packaging.
+
+### Local end-to-end test
+
+```bash
+bash packages/edge-sdk/deploy/macos/test-install-pair.sh
+```
+
+No sudo. It builds the pkg, installs it home-domain, starts a local stub
+pair+analyze server, pairs headlessly, runs `cloud-sense` against a **synthetic
+ffmpeg source** (a generated clip via `file:` — no RTSP server needed), asserts a
+**real JPEG frame** is produced by the bundled ffmpeg and POSTed with the paired
+`X-Device-Token`, verifies the LaunchAgent bootstraps and senses autonomously,
+then tears everything down. TAP output; non-zero exit on any failure.
+
+---
+
+## Signing & notarization (distribution follow-on)
+
+The local build is **unsigned** because this repo's signing keychain has only
+`Apple Development` / `Apple Distribution` identities — there is **no
+`Developer ID Installer`** cert (the one Gatekeeper requires for a `.pkg`
+distributed outside the App Store).
+
+To ship a Gatekeeper-clean installer, on a machine that has the
+`Developer ID Installer` cert:
+
+```bash
+# 1. Sign the installer
+./build-macos-pkg.sh --sign-installer "Developer ID Installer: Aethercorp Inc (78JQ7882U9)"
+#   (or: export MAC_INSTALLER_IDENTITY="Developer ID Installer: …" && ./build-macos-pkg.sh)
+
+# 2. Notarize + staple
+xcrun notarytool submit dist-installer/TrillboardsEdge-<ver>-arm64.pkg \
+  --keychain-profile <notary-profile> --wait
+xcrun stapler staple dist-installer/TrillboardsEdge-<ver>-arm64.pkg
+```
+
+The bundled `bin/node` and `bin/ffmpeg` are third-party Mach-O binaries; for full
+notarization they should additionally be **codesigned with a Developer ID
+Application cert + hardened runtime** before the pkg is built (notarytool checks
+nested executables). That cert is likewise not present here, so it's part of the
+same distribution follow-on. Until then, the unsigned pkg installs fine via the
+`installer` CLI and for internal/manual installs.
+
+---
+
+## Other platforms (same pair-then-local-first flow)
+
+macOS is the must-have one-click installer. The connector itself is
+cross-platform; the other OS installers live alongside this one and follow the
+**identical** flow — `pair` writes the config, then `auto-sense` waits for and
+runs the local model:
+
+- **Linux (systemd):** [`../systemd/`](../systemd/) — `install.sh` lays down the
+  SDK + a `trillboards-edge` systemd unit. Pair first, then point the unit at
+  `auto-sense`:
+  ```bash
+  trillboards-edge pair --code XXXX-XXXX --config /etc/trillboards/config.json
+  # edit the unit's ExecStart to: trillboards-edge auto-sense --config /etc/trillboards/config.json
+  sudo systemctl restart trillboards-edge
+  ```
+  ffmpeg is required on the host (the systemd install handles it via apt).
+- **Windows (Service):** [`../windows/install-service.ps1`](../windows/install-service.ps1)
+  — installs the SDK as a Windows service. Same flow: `trillboards-edge pair
+  --code XXXX-XXXX --config <path>` then run `auto-sense --config <path>`.
+- **Docker:** [`../docker/`](../docker/) — for headless/server NVR gateways.
+
+The pairing endpoint (`POST /v2/earner/cameras/pair`), the config shape, and the
+local-first sensing runtime are shared across all platforms — only the
+service-supervisor wrapper differs.