From c96aca5f1dfbe1771aa0024bedd103f6e3373e76 Mon Sep 17 00:00:00 2001 From: William Valentin Date: Thu, 26 Feb 2026 21:00:28 -0800 Subject: [PATCH] chore(companion): enforce reference-app generator sync in CI --- .../companion-reference-apps-check.yml | 26 +++++++++++++++++++ README.md | 2 ++ docs/api/PROTOCOL.md | 2 ++ docs/architecture/AGENT_DIAGRAM.md | 2 ++ .../GATEWAY_SESSIONS_AND_QUEUE.md | 2 ++ docs/operations/COMPANION_RELEASE_BUNDLE.md | 1 + ...-personal-assistant-productization-plan.md | 2 +- docs/plans/state.json | 26 ++++++++++++++++++- package.json | 3 ++- 9 files changed, 63 insertions(+), 3 deletions(-) create mode 100644 .github/workflows/companion-reference-apps-check.yml diff --git a/.github/workflows/companion-reference-apps-check.yml b/.github/workflows/companion-reference-apps-check.yml new file mode 100644 index 0000000..17c05d2 --- /dev/null +++ b/.github/workflows/companion-reference-apps-check.yml @@ -0,0 +1,26 @@ +name: companion-reference-apps-check + +on: + pull_request: + workflow_dispatch: + +jobs: + check: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '22' + + - name: Enable Corepack + run: corepack enable + + - name: Install dependencies + run: pnpm install --frozen-lockfile + + - name: Verify generated companion reference apps are in sync + run: pnpm companion:reference-apps:check diff --git a/README.md b/README.md index 138a920..ec770fa 100644 --- a/README.md +++ b/README.md @@ -1753,7 +1753,9 @@ Minimal companion CLI: - `flynn companion --verify-release-bundle ./dist/companion-macos --verify-signing-key ./keys/release-public.pem --verify-signing-key-id team-k1 --require-signature` verifies checksums and signature metadata before install. - `pnpm companion:bundle -- --output ./dist/companion-macos --platform macos --signing-key ./keys/release-private.pem --signing-key-id team-k1` builds and verifies a release bundle in one step. - `pnpm companion:reference-apps -- --output ./apps/companion` regenerates macOS/iOS/Android reference app starter shells plus `apps/companion/macos-app` runnable scaffold using a reproducible default `generatedAt` timestamp (override with `--generated-at `). +- `pnpm companion:reference-apps:check` regenerates `apps/companion` and fails if tracked reference-app artifacts drift from generator output. - GitHub Actions workflow `.github/workflows/companion-release-bundle.yml` runs build-and-verify bundle automation and uploads release artifacts on manual dispatch. +- GitHub Actions workflow `.github/workflows/companion-reference-apps-check.yml` enforces reference-app generator sync on pull requests. `run-companion.sh` verifies bundle checksums (`CHECKSUMS.sha256`) before launching `flynn companion`. - `flynn companion --once --platform ios --app-version 1.2.3 --device-name "iPhone" --status-text ready --battery-pct 84 --power-source battery` sends richer initial node status metadata. diff --git a/docs/api/PROTOCOL.md b/docs/api/PROTOCOL.md index 0239342..2b0387d 100644 --- a/docs/api/PROTOCOL.md +++ b/docs/api/PROTOCOL.md @@ -1869,4 +1869,6 @@ For more implementation details, see: - Companion shell template helper: `src/companion/shellTemplate.ts` (writes platform-native starter template files for `macos`, `ios`, and `android` shell scaffolding, including iOS/Android runtime skeletons for `node.register` + status/location/push + `agent.send`) - Companion macOS menu-bar app scaffold helper: `src/companion/macosMenuBarApp.ts` (writes runnable Swift Package menu-bar app starter surface) - Companion reference app exporter: `src/companion/referenceApps.ts` + `scripts/export-companion-reference-apps.ts` (regenerates in-repo platform starter app directories, including `apps/companion/macos-app`) +- Companion reference app sync-check script: `package.json#companion:reference-apps:check` (regenerates and fails on `apps/companion` drift) - CI artifact workflow: `.github/workflows/companion-release-bundle.yml` (manual dispatch bundle build/verify/upload pipeline) +- CI reference-app sync workflow: `.github/workflows/companion-reference-apps-check.yml` (PR-time generator drift guard) diff --git a/docs/architecture/AGENT_DIAGRAM.md b/docs/architecture/AGENT_DIAGRAM.md index 586da9b..1f1bcbb 100644 --- a/docs/architecture/AGENT_DIAGRAM.md +++ b/docs/architecture/AGENT_DIAGRAM.md @@ -162,7 +162,9 @@ Gateway streaming UX signals: - `flynn companion --export-shell-template ` can emit platform starter shell templates (macOS/iOS/Android native scaffold files + bootstrap JSON), including iOS/Android runtime skeletons for registration, heartbeat/status, location/push updates, and handoff. - `pnpm companion:bundle -- --output ...` runs a build-and-verify release pipeline for repeatable companion artifact generation. - `pnpm companion:reference-apps -- --output apps/companion` regenerates in-repo macOS/iOS/Android reference app starter surfaces plus a runnable `macos-app` Swift Package menu-bar scaffold. +- `pnpm companion:reference-apps:check` verifies committed `apps/companion` artifacts match generator output. - `.github/workflows/companion-release-bundle.yml` provides CI artifact generation for companion release bundles using the same build-and-verify pipeline. +- `.github/workflows/companion-reference-apps-check.yml` enforces reference-app generator sync in CI. - `flynn companion` can bootstrap status/location/push metadata on connect (`node.status.set` + optional `node.location.set`/`node.push_token.set`) so thin companion shells can register operational context in one launch. - Canvas artifacts are persisted by the gateway so session UI surfaces can recover after daemon restarts. - TTS synthesis uses an ordered provider chain with health cooldown tracking; if all providers fail, replies degrade to text-only without dropping the response. diff --git a/docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md b/docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md index 16b5fd5..f9b221e 100644 --- a/docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md +++ b/docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md @@ -28,7 +28,9 @@ If you only want the protocol surface, see `docs/api/PROTOCOL.md`. - Companion packaging automation is available via `pnpm companion:bundle -- --output ...`, which builds and verifies the release bundle in one pass. - Companion platform starter scaffolds can be generated via `flynn companion --export-shell-template ` for macOS/iOS/Android reference app bootstrapping, including iOS/Android runtime skeletons that issue `node.register`, `node.status.set`, `node.location.set`, `node.push_token.set`, and `agent.send`. - Companion reference app directories can be regenerated via `pnpm companion:reference-apps -- --output apps/companion` for repo-shipped starter surfaces, including a runnable `macos-app` Swift Package menu-bar scaffold. +- Companion reference-app sync can be enforced with `pnpm companion:reference-apps:check` (regenerate + diff fail on drift). - CI workflow `.github/workflows/companion-release-bundle.yml` mirrors this pipeline for manual artifact generation/upload. +- CI workflow `.github/workflows/companion-reference-apps-check.yml` enforces reference-app generator sync on pull requests. - Companion CLI supports one-shot shell bootstrap metadata for live sessions (`--app-version`/`--status-text`, `--latitude`/`--longitude`, `--push-token`) so desktop/mobile wrappers can initialize node status/location/push in a single launch flow. - Canvas artifacts are persisted per session under the gateway data directory for UI recovery across restarts. - TTS output is best-effort with ordered provider fallback + per-provider cooldown tracking; synthesis failures still fall back to text-only responses. diff --git a/docs/operations/COMPANION_RELEASE_BUNDLE.md b/docs/operations/COMPANION_RELEASE_BUNDLE.md index 93e62da..ede41f3 100644 --- a/docs/operations/COMPANION_RELEASE_BUNDLE.md +++ b/docs/operations/COMPANION_RELEASE_BUNDLE.md @@ -61,6 +61,7 @@ By default it uses a reproducible `generatedAt` timestamp (`2026-02-27T00:00:00. CI automation: - `.github/workflows/companion-release-bundle.yml` provides a manual-dispatch workflow that generates an ephemeral signing key, builds/verifies a bundle with `pnpm companion:bundle`, and uploads artifacts. +- `.github/workflows/companion-reference-apps-check.yml` runs `pnpm companion:reference-apps:check` on pull requests to ensure `apps/companion` stays in sync with generators. ## Generate Platform Starter Shell Template diff --git a/docs/plans/2026-02-26-personal-assistant-productization-plan.md b/docs/plans/2026-02-26-personal-assistant-productization-plan.md index 5afa925..79c67d3 100644 --- a/docs/plans/2026-02-26-personal-assistant-productization-plan.md +++ b/docs/plans/2026-02-26-personal-assistant-productization-plan.md @@ -51,7 +51,7 @@ Within 8-10 weeks, ship a stable "Personal Assistant Mode" that supports: 2. Ship a minimal mobile companion shell (iOS + Android) for registration, status, push token, and message handoff. 3. Add signed release artifacts and installation docs. -Status update (2026-02-27): companion bootstrap-manifest export is now available via `flynn companion --export-bootstrap ` as a packaging contract for desktop/mobile shells, `flynn companion --export-release-bundle ` now emits bundle artifacts (bootstrap JSON + launcher + README + `CHECKSUMS.sha256` + `RELEASE_MANIFEST.json`, optional `CHECKSUMS.sha256.sig` with `--signing-key`), `flynn companion --verify-release-bundle ` now validates checksum/signature artifacts before install, `pnpm companion:bundle -- --output ...` now provides one-pass build-and-verify automation, `.github/workflows/companion-release-bundle.yml` provides CI artifact build/verify/upload, `flynn companion --export-shell-template ` now emits macOS/iOS/Android starter shell templates including iOS/Android runtime skeletons for register/status/location/push/handoff flows, `pnpm companion:reference-apps` now regenerates in-repo macOS/iOS/Android reference app starter directories plus `apps/companion/macos-app` runnable menu-bar scaffold with a reproducible default `generatedAt` timestamp, and `flynn companion` supports one-shot status/location/push bootstrap flags (`--app-version`, `--latitude/--longitude`, `--push-token`) so thin shells can initialize companion metadata in a single run. +Status update (2026-02-27): companion bootstrap-manifest export is now available via `flynn companion --export-bootstrap ` as a packaging contract for desktop/mobile shells, `flynn companion --export-release-bundle ` now emits bundle artifacts (bootstrap JSON + launcher + README + `CHECKSUMS.sha256` + `RELEASE_MANIFEST.json`, optional `CHECKSUMS.sha256.sig` with `--signing-key`), `flynn companion --verify-release-bundle ` now validates checksum/signature artifacts before install, `pnpm companion:bundle -- --output ...` now provides one-pass build-and-verify automation, `.github/workflows/companion-release-bundle.yml` provides CI artifact build/verify/upload, `flynn companion --export-shell-template ` now emits macOS/iOS/Android starter shell templates including iOS/Android runtime skeletons for register/status/location/push/handoff flows, `pnpm companion:reference-apps` now regenerates in-repo macOS/iOS/Android reference app starter directories plus `apps/companion/macos-app` runnable menu-bar scaffold with a reproducible default `generatedAt` timestamp, `pnpm companion:reference-apps:check` + `.github/workflows/companion-reference-apps-check.yml` now enforce generator/output sync in CI, and `flynn companion` supports one-shot status/location/push bootstrap flags (`--app-version`, `--latitude/--longitude`, `--push-token`) so thin shells can initialize companion metadata in a single run. ### Implementation Anchors diff --git a/docs/plans/state.json b/docs/plans/state.json index bfa9233..cb5690e 100644 --- a/docs/plans/state.json +++ b/docs/plans/state.json @@ -7193,6 +7193,30 @@ ], "test_status": "workflow/docs update; runtime validation remains covered by companion bundle/verify test suites" }, + "personal-assistant-productization-phase1-companion-reference-app-sync-check": { + "status": "completed", + "date": "2026-02-27", + "updated": "2026-02-27", + "summary": "Added reproducibility + CI drift guard for companion reference app surfaces. `pnpm companion:reference-apps` now uses a deterministic default `generatedAt` timestamp (override via `--generated-at`), `pnpm companion:reference-apps:check` validates generated output matches committed `apps/companion`, and `.github/workflows/companion-reference-apps-check.yml` enforces this check on pull requests.", + "files_modified": [ + "scripts/export-companion-reference-apps.ts", + "src/companion/referenceApps.test.ts", + "package.json", + ".github/workflows/companion-reference-apps-check.yml", + "apps/companion/macos/companion.bootstrap.json", + "apps/companion/ios/companion.bootstrap.json", + "apps/companion/android/companion.bootstrap.json", + "apps/companion/macos-app/Sources/FlynnCompanionMenuBar/Resources/companion.bootstrap.json", + "README.md", + "docs/api/PROTOCOL.md", + "docs/architecture/AGENT_DIAGRAM.md", + "docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md", + "docs/operations/COMPANION_RELEASE_BUNDLE.md", + "docs/plans/2026-02-26-personal-assistant-productization-plan.md", + "docs/plans/state.json" + ], + "test_status": "pnpm test:run src/companion/referenceApps.test.ts src/companion/shellTemplate.test.ts src/companion/macosMenuBarApp.test.ts + pnpm typecheck passing; `pnpm companion:reference-apps:check` passes locally" + }, "personal-assistant-productization-roadmap-complete-2026-02-27": { "status": "completed", "date": "2026-02-27", @@ -7221,7 +7245,7 @@ "tier2_completion": "4/4 (100%) — inbound webhooks, vector memory search, Dockerfile, heartbeat monitor", "tier3_completion": "5/5 (100%) — lane queue, credential redaction, web UI token dashboard, xAI (Grok) provider, Voyage AI embeddings", "tier4_completion": "4/4 (100%) — gateway lock, shell completion, Tailscale Serve/Funnel, DM pairing codes", - "feature_gap_scorecard": "rebaselined 2026-02-26 and finalized 2026-02-27 — channel breadth, setup wizard, browser workflow reliability primitives (wait/assert/extract/retries/checkpoints/guardrails/budgets), companion reconnect/runtime-handoff foundations, companion packaging/distribution primitives (bootstrap export + release-bundle artifacts + checksum manifests + release manifest artifact + optional signatures + verification mode + checksum-gated launcher + one-pass build/verify automation + CI workflow), repo-shipped macOS/iOS/Android reference app starter surfaces plus runnable macOS menu-bar Swift Package scaffold (`apps/companion/macos-app`) and iOS/Android runtime shell skeletons (`IOSCompanionRuntime.swift`, `AndroidCompanionRuntime.kt`), one-shot status/location/push shell bootstrap controls, voice reliability hardening (talk controls + TTS fallback/health + interruption-safe cancel semantics), and onboarding first-success funnel improvements are implemented.", + "feature_gap_scorecard": "rebaselined 2026-02-26 and finalized 2026-02-27 — channel breadth, setup wizard, browser workflow reliability primitives (wait/assert/extract/retries/checkpoints/guardrails/budgets), companion reconnect/runtime-handoff foundations, companion packaging/distribution primitives (bootstrap export + release-bundle artifacts + checksum manifests + release manifest artifact + optional signatures + verification mode + checksum-gated launcher + one-pass build/verify automation + CI workflow), repo-shipped macOS/iOS/Android reference app starter surfaces plus runnable macOS menu-bar Swift Package scaffold (`apps/companion/macos-app`) and iOS/Android runtime shell skeletons (`IOSCompanionRuntime.swift`, `AndroidCompanionRuntime.kt`) with CI-enforced generator sync (`pnpm companion:reference-apps:check` + workflow), one-shot status/location/push shell bootstrap controls, voice reliability hardening (talk controls + TTS fallback/health + interruption-safe cancel semantics), and onboarding first-success funnel improvements are implemented.", "operator_dx_milestone": "Phase 3 (Live Ops Dashboard): 2/2 plans complete — milestone done", "dashboard_observability": "completed — service health graphs + core service log viewer added to web UI via observability RPCs and bounded backend sampling", "gmail_auth_cli": "flynn gmail-auth command implemented with OAuth2 flow, doctor check, config routed to Telegram", diff --git a/package.json b/package.json index 1d070c9..18c0310 100644 --- a/package.json +++ b/package.json @@ -24,7 +24,8 @@ "audit:phase0-baseline": "node --import tsx/esm scripts/summarize-phase0-baseline.ts", "audit:backend-canary:probes": "node --import tsx/esm scripts/run-pi-canary-guard-probes.ts", "companion:bundle": "node --import tsx/esm scripts/build-companion-release-bundle.ts", - "companion:reference-apps": "node --import tsx/esm scripts/export-companion-reference-apps.ts" + "companion:reference-apps": "node --import tsx/esm scripts/export-companion-reference-apps.ts", + "companion:reference-apps:check": "pnpm companion:reference-apps -- --output ./apps/companion --url ws://127.0.0.1:18800 && git diff --exit-code -- apps/companion" }, "keywords": [ "ai",