William Valentin
138 lines
3.6 KiB
Markdown
138 lines
3.6 KiB
Markdown
# Companion Release Bundle Runbook
|
|
|
|
This runbook covers generating, verifying, and launching Flynn companion shell bundles.
|
|
|
|
## Generate Bundle
|
|
|
|
From a Flynn host:
|
|
|
|
```bash
|
|
flynn companion \
|
|
--platform macos \
|
|
--node-id companion-macbook \
|
|
--app-version 1.0.0 \
|
|
--export-release-bundle ./dist/companion-macos
|
|
```
|
|
|
|
Generated files:
|
|
|
|
- `companion.bootstrap.json`
|
|
- `run-companion.sh`
|
|
- `README.md`
|
|
- `CHECKSUMS.sha256`
|
|
- `RELEASE_MANIFEST.json`
|
|
|
|
Optional signed export:
|
|
|
|
```bash
|
|
flynn companion \
|
|
--platform macos \
|
|
--node-id companion-macbook \
|
|
--export-release-bundle ./dist/companion-macos \
|
|
--signing-key ./keys/release-private.pem \
|
|
--signing-key-id team-k1
|
|
```
|
|
|
|
Additional file:
|
|
|
|
- `CHECKSUMS.sha256.sig`
|
|
|
|
One-command automation:
|
|
|
|
```bash
|
|
pnpm companion:bundle -- \
|
|
--output ./dist/companion-macos \
|
|
--platform macos \
|
|
--signing-key ./keys/release-private.pem \
|
|
--signing-key-id team-k1
|
|
```
|
|
|
|
This script builds the bundle and immediately verifies checksums/signatures before returning success.
|
|
|
|
Reference app starters can be regenerated in-repo with:
|
|
|
|
```bash
|
|
pnpm companion:reference-apps -- --output ./apps/companion
|
|
```
|
|
|
|
This also regenerates `apps/companion/macos-app`, a runnable Swift Package menu-bar reference app scaffold.
|
|
By default it uses a reproducible `generatedAt` timestamp (`2026-02-27T00:00:00.000Z`); pass `--generated-at <iso>` if you need a different value.
|
|
|
|
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
|
|
|
|
For native app bootstrapping (without launcher/checksum artifacts), export a platform template:
|
|
|
|
```bash
|
|
flynn companion \
|
|
--platform ios \
|
|
--node-id companion-ios \
|
|
--export-shell-template ./dist/companion-ios-template
|
|
```
|
|
|
|
Generated files:
|
|
|
|
- `companion.bootstrap.json`
|
|
- `MenuBarCompanion.swift` (macOS)
|
|
- `CompanionBootstrap.swift` + `IOSCompanionRuntime.swift` (iOS)
|
|
- `CompanionBootstrap.kt` + `AndroidCompanionRuntime.kt` (Android)
|
|
- `README.md`
|
|
|
|
## Verify Bundle Integrity
|
|
|
|
On the target host (before launch), verify checksums:
|
|
|
|
```bash
|
|
cd ./dist/companion-macos
|
|
sha256sum --check CHECKSUMS.sha256
|
|
```
|
|
|
|
Expected result:
|
|
|
|
- all bundle files report `OK`
|
|
|
|
If signature is present, verify `CHECKSUMS.sha256.sig` with your org signing key policy before launch.
|
|
|
|
Automated CLI verification mode:
|
|
|
|
```bash
|
|
flynn companion \
|
|
--verify-release-bundle ./dist/companion-macos \
|
|
--verify-signing-key ./keys/release-public.pem \
|
|
--verify-signing-key-id team-k1 \
|
|
--require-signature
|
|
```
|
|
|
|
## Launch
|
|
|
|
```bash
|
|
./run-companion.sh
|
|
```
|
|
|
|
Launcher behavior:
|
|
|
|
- verifies `CHECKSUMS.sha256` before invoking `flynn companion`
|
|
- aborts launch on checksum mismatch or missing checksum tooling
|
|
|
|
Optional handoff smoke test:
|
|
|
|
```bash
|
|
./run-companion.sh --handoff "status check"
|
|
```
|
|
|
|
## Platform Notes
|
|
|
|
- `ios` and `macos` default push provider to `apns` when `--push-token` is set.
|
|
- `android` defaults push provider to `fcm` when `--push-token` is set.
|
|
- For `linux`, `windows`, or `unknown` platforms, specify `--push-provider` explicitly when using `--push-token`.
|
|
|
|
## Distribution Guidance
|
|
|
|
- Treat `companion.bootstrap.json` as sensitive if it includes gateway tokens or push tokens.
|
|
- Remove or rotate secrets before sharing bundles externally.
|
|
- For signed releases, sign the bundle directory or tarball with your standard org release-signing process after checksum verification.
|