Add advanced monitoring and release infrastructure

2026-08-15 18:23:35 -04:00
parent a67bb5fdf3
commit 0da94715be
38 changed files with 4219 additions and 406 deletions
@@ -0,0 +1,57 @@
+# puter release checklist
+
+This checklist is the authoritative handoff for producing a public puter release. Run it from the repository root on a macOS runner.
+
+## Local quality gates
+
+- [x] `swift test --parallel` passes, including native full/lightweight sampler budgets, process sort semantics, memory pressure, storage, power parsing, helper input validation, security inspection, recording, alerts, and diagnostic serialization.
+- [x] `./scripts/build-app.sh` produces a Hardened Runtime app with the live Icon Composer asset, Sparkle framework, command-limited helper, launch-daemon property list, and SMC backend/license when available.
+- [x] `./scripts/build-dmg.sh` produces a drag-to-install DMG.
+- [x] `./scripts/validate-package.sh` validates signatures, nested code, runtime search paths, Sparkle linkage, bundle metadata, Icon Composer configuration, helper payload, SMC payload/license, DMG checksum, mounted app, and Applications shortcut.
+- [x] Packaged-app accessibility smoke tests cover sidebar hide/recovery, the descending/ascending/categorized sort cycle, process rows, and live Hardware values.
+- [x] Current sampler benchmark: full process telemetry 0.0529 seconds/iteration; lightweight system telemetry 0.0076 seconds/iteration.
+- [x] Current 20-second packaged Hardware-page benchmark: 0.83% average CPU, 9.7% one-second peak while hardware work completed.
+
+Benchmark numbers are evidence from the development Mac, not universal product guarantees. CI enforces the portable per-iteration budget rather than a machine-specific CPU percentage.
+
+## Required protected release inputs
+
+- [ ] `DEVELOPER_ID_P12_BASE64`: Developer ID Application certificate and private key in PKCS#12 form.
+- [ ] `DEVELOPER_ID_P12_PASSWORD`: PKCS#12 password.
+- [ ] `DEVELOPER_ID_IDENTITY`: exact `Developer ID Application: … (TEAMID)` identity.
+- [ ] `APPLE_NOTARY_KEY_BASE64`: App Store Connect API private key.
+- [ ] `APPLE_NOTARY_KEY_ID` and `APPLE_NOTARY_ISSUER_ID`.
+- [ ] `SPARKLE_FEED_URL`, `SPARKLE_PUBLIC_KEY`, `SPARKLE_PRIVATE_KEY`, and `SPARKLE_DOWNLOAD_PREFIX`.
+- [ ] `RELEASE_TOKEN`: token allowed to create a release and upload assets to this Gitea repository.
+- [ ] Stats-derived `smc` executable through `PUTER_SMC_SOURCE`, or Stats installed at `/Applications/Stats.app` on the runner.
+
+Never commit certificates, API keys, Sparkle private keys, or release tokens.
+
+## Signed release procedure
+
+1. Confirm the working tree and intended tag are clean and reviewed.
+2. Confirm `security find-identity -v -p codesigning` lists the Developer ID Application identity.
+3. Run the local gates above.
+4. Push a semantic version tag such as `v1.0.0`.
+5. The `Signed release` workflow must:
+   - import the certificate into an ephemeral keychain;
+   - build with Hardened Runtime, library validation, update feed, and EdDSA public key;
+   - validate the signed app and DMG before submission;
+   - submit to Apple, staple and validate both app and DMG;
+   - validate the notarized package again;
+   - generate the EdDSA-signed appcast;
+   - publish the notarized DMG, stapled app ZIP, appcast, and `SHA256SUMS`.
+6. Download the published assets on a separate Mac and run:
+
+   ```sh
+   hdiutil verify puter-macOS.dmg
+   spctl --assess --type open --context context:primary-signature -v puter-macOS.dmg
+   xcrun stapler validate puter-macOS.dmg
+   ```
+
+7. Install into `/Applications`, launch it, approve the helper only when testing fan control, and verify monitoring works without helper approval.
+8. Exercise Check for Updates against the published appcast from the previous release before announcing the new release.
+
+## Release acceptance
+
+A release is complete only when Apple notarization is accepted, stapler and Gatekeeper validation pass, the Gitea assets are downloadable with matching SHA-256 values, Sparkle verifies the appcast, and the installed app passes the packaged smoke tests. An ad-hoc or Apple Development build is not a public release.