From 160a6407c00c1cdd8d6c2b7e582b9fbe37487cef Mon Sep 17 00:00:00 2001 From: Stefano Veloccia Date: Tue, 3 Nov 2026 19:08:56 +0100 Subject: [PATCH 01/10] Design a signed macOS installer for the VST3, AU and Standalone Co-Authored-By: Claude Opus 5.5 --- .../2026-11-03-macos-installer-design.md | 188 ++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 docs/superpowers/specs/2026-11-03-macos-installer-design.md diff --git a/docs/superpowers/specs/2026-11-03-macos-installer-design.md b/docs/superpowers/specs/2026-11-03-macos-installer-design.md new file mode 100644 index 0000000..108ca47 --- /dev/null +++ b/docs/superpowers/specs/2026-11-03-macos-installer-design.md @@ -0,0 +1,188 @@ +# macOS installer design + +This design replaces the release zip with an installer package. It reverses two non-goals of +`2026-11-01-repository-and-release-design.md`: installers, and AU and Standalone releases. + +## Goal + +Release Drosera as one file, `Drosera-X.Y.Z-macos.pkg`, which installs the VST3, the AU and the Standalone app. The +package is built and checked in CI. When Apple credentials are available it is signed with Developer ID and notarized, +and it opens with no Gatekeeper warning. + +Success means: + +- A user installs all three formats by opening one file. They never use Terminal, `xattr` included. +- With the credentials, the package opens with no warning. `spctl` reports it as `accepted` from a notarized + Developer ID. +- Without them, macOS blocks the package once. The user clicks **Open Anyway** in System Settings, and nothing else + is blocked afterwards: the hosts load the plugins and the Standalone app opens. +- Every CI run builds and checks the package, so packaging cannot break unnoticed between releases. +- Renders stay byte-identical to `tools/hardware-comparison/reference/SHA256SUMS`, because nothing here touches the + DSP. + +## Non-goals + +A `.dmg`, an uninstaller, localised installer screens, per-user installation, Windows, automatic updates, and a +documented way to sign on a developer's own Mac. The script can sign anywhere the variables are set, but CI is the +only signing path this design documents and tests. + +## Findings that shape the design + +**Signing needs a paid account.** Developer ID certificates and notarization require the Apple Developer Program. +Software notarized while the membership is active keeps working after it lapses, so the owner can pay for the years +with a release. Until then, the package is unsigned. + +**An unsigned package costs the user one approval.** Since macOS 15, Control-click → Open no longer overrides +Gatekeeper; the route is System Settings → Privacy & Security → Open Anyway. A probe on macOS 27.2 on 2026-11-03 +checked what happens next. It used an unsigned `.pkg` holding an app and a `.vst3` bundle, both signed ad hoc, given +the quarantine attribute Safari writes, and opened from Finder: + +- Installer did not pass the quarantine attribute to the installed files. They carried only `com.apple.provenance`. +- The installed app launched through LaunchServices without Gatekeeper. +- The `.vst3` binary loaded into another process. + +The probe did not use Drosera's own bundles or a real DAW. The manual checklist below covers that. + +**Homebrew offers no way round it.** Homebrew 5 deprecated `--no-quarantine`, and from 2026-09-01 it disables casks +that fail Gatekeeper. + +## Package layout + +`pkgbuild` builds one component package per format. `productbuild` combines them with `distribution.xml` into the +product package. + +| Choice | Identifier | Installs | +|---|---|---| +| VST3 | `com.codeskine.drosera.vst3` | `/Library/Audio/Plug-Ins/VST3/Drosera.vst3` | +| Audio Unit | `com.codeskine.drosera.au` | `/Library/Audio/Plug-Ins/Components/Drosera.component` | +| Standalone | `com.codeskine.drosera.app` | `/Applications/Drosera.app` | + +- Each component's version is the version in `project()` in `CMakeLists.txt`. +- The three choices are shown under Customize and are all selected by default. +- Installation is for all users, on the system volume, as an administrator (`enable_localSystem` only). +- A component plist sets `BundleIsRelocatable` to false on every bundle. Otherwise Installer updates a copy found + elsewhere, for example `~/Downloads/Drosera.app`, instead of writing to the paths above. +- `distribution.xml` requires macOS 11 or newer, matching `CMAKE_OSX_DEPLOYMENT_TARGET`. It declares + `hostArchitectures="arm64,x86_64"`, so Installer on Apple silicon does not ask for Rosetta. +- The AU component has a `postinstall` script. Its only command is `killall -9 AudioComponentRegistrar`, so hosts see + a new version without a restart. It exits 0 whether or not that process was running. + +### Screens + +The screens are in English, like the rest of the project. Their text is the same in both modes. Instructions about +Gatekeeper cannot go here, because a user reads them only after the package has opened. + +1. **Welcome:** what Drosera is, the three formats and where each goes, and that Customize leaves formats out. +2. **Read Me:** the copyright notice and the AGPLv3 notice, with the address of the source. Then the full text of + `LICENSE`, `LICENSE-AudreyII`, `THIRD_PARTY_LICENSES.md`, `third_party/DaisySP/LICENSE`, + `assets/fonts/OFL-Inter.txt` and `assets/fonts/OFL-Cormorant.txt`. `build_pkg.sh` generates this page from those + files, so it cannot drift from them. It replaces the licence files the zip carried, and adds the font licences, + which the zip lacked. +3. **Conclusion:** rescan plugins in the host, and where to find the Standalone app. Then how to uninstall: delete the + three paths in the table. And a note for users of 0.1.x, who copied the VST3 to + `~/Library/Audio/Plug-Ins/VST3/` by hand: delete that copy, or the host finds two. + +No screen has the Agree / Disagree licence dialog. The AGPL does not need to be accepted to use the program, and an +agreement to accept would misrepresent it. + +The installer never touches a user's home folder, the old 0.1.x copy included. + +## Signing and notarization + +`build_pkg.sh` builds an unsigned package by default. It signs when `DEVELOPER_ID_APPLICATION`, +`DEVELOPER_ID_INSTALLER` and the notarization variables are all set. Each `DEVELOPER_ID_*` variable holds the full +name of a certificate, such as `Developer ID Application: Name (TEAMID)`. If only some of the variables are set, the +script stops with an error. Once signing has started, any failure stops the script. In CI it never falls back to an +unsigned package once the secrets exist. + +**Unsigned mode.** The bundles keep the ad hoc signatures CMake gives them. `productbuild` runs without `--sign`. + +**Signed mode.** + +1. Sign each bundle on its own with + `codesign --force --options runtime --timestamp --sign "$DEVELOPER_ID_APPLICATION"`, never with `--deep`. + Notarization requires the hardened runtime on every executable, plug-ins included. +2. Sign the Standalone app with `tools/package/resources/Drosera.entitlements` as well. Its only entitlement is + `com.apple.security.device.audio-input`. The VST3 and the AU take no entitlements, because they run with the + host's. +3. Run `productbuild --sign "$DEVELOPER_ID_INSTALLER"`. The component packages inside are not signed. +4. Run `xcrun notarytool submit --wait`. If Apple rejects the package, print `xcrun notarytool log` for the + submission, then fail. +5. Run `xcrun stapler staple` on the package, so Gatekeeper accepts it offline. + +**Microphone.** Under the hardened runtime, macOS gives a signed app audio input only if it declares why. +`CMakeLists.txt` adds `MICROPHONE_PERMISSION_ENABLED TRUE` and +`MICROPHONE_PERMISSION_TEXT "Drosera uses audio input to feed external sound into its feedback loop."` to +`juce_add_plugin`. This changes only the bundles' `Info.plist`. The post-build ad hoc signing stays as it is. + +**Credentials in CI.** The repository secret names stay as `RELEASING.md` lists them: `APPLE_CERTIFICATE`, +`APPLE_CERTIFICATE_PASSWORD`, `APPLE_ID`, `APPLE_TEAM_ID`, `APPLE_APP_PASSWORD`. `APPLE_CERTIFICATE` becomes one +base64 `.p12` holding both identities, Developer ID Application and Developer ID Installer. CI imports it into a +temporary keychain, as the current notarization step does. It reads the two certificate names from that keychain and +passes them to the script. + +## Files + +| Path | Holds | +|---|---| +| `tools/package/build_pkg.sh` | `build_pkg.sh `: stages the three bundles, generates the Read Me, builds the component and product packages, and signs and notarizes in signed mode | +| `tools/package/check_pkg.sh` | `check_pkg.sh `: checks a package without installing it (below) | +| `tools/package/resources/distribution.xml` | The product definition; the script fills in the version | +| `tools/package/resources/components.plist` | `BundleIsRelocatable` false for every bundle | +| `tools/package/resources/welcome.html`, `conclusion.html` | The fixed screens | +| `tools/package/resources/readme-header.html` | The top of the Read Me, before the licence texts | +| `tools/package/resources/Drosera.entitlements` | The Standalone app's entitlement | +| `tools/package/resources/scripts/au/postinstall` | The AU cache refresh | + +## Checks + +`check_pkg.sh` expands the package with `pkgutil --expand-full` into a temporary folder and fails unless: + +- it holds exactly the three component packages, with the identifiers and install paths in the table; +- every bundle has `BundleIsRelocatable` false; +- `distribution.xml` requires macOS 11 and lists both architectures; +- every bundle passes `codesign --verify --strict`; +- the VST3 from the package loads and renders in `plugin_host_test` against `tests/fixtures/state-baseline.bin`. What + a user installs is what must work, as the zip check had it. + +If the package is signed, it also requires `pkgutil --check-signature` to name a Developer ID Installer certificate, +`spctl --assess --type install` to report `source=Notarized Developer ID`, and `xcrun stapler validate` to succeed. + +## CI and release + +**`ci.yml`** + +- A new step builds the package unsigned and runs `check_pkg.sh` on every push. Without a version input, it uses the + version in `project()`. +- For a build with a version, the step runs in signed mode when the secrets exist. +- It replaces the steps "Sign with Developer ID and notarize" and "Package". +- `auval` and `pluginval` on the AU, already in CI, stay as they are. +- "Upload the package" uploads `Drosera-X.Y.Z-macos.pkg` as the `drosera-macos` artefact. + +**`release.yml`** publishes `Drosera-X.Y.Z-macos.pkg` and its checksum in `SHA256SUMS.txt`. Its publish job runs on +Linux, where `pkgutil` does not exist, so it decides as `ci.yml` does, from whether the `APPLE_ID` secret is set. When +it is not, it adds a short paragraph to the notes on opening the package with Open Anyway. `release_check.py` is +unchanged. + +## Documents + +- `docs/INSTALL.txt` is deleted. Its content moves to the installer screens. +- `README.md`, under Install: download the `.pkg` from Releases and open it. While releases are unsigned, a subsection + gives the Open Anyway steps, with no Terminal command. Also how to uninstall, and the note for 0.1.x users. +- `docs/RELEASING.md`: + - how to request both Developer ID certificates and export them as one `.p12`; + - that the signed path has never run until the secrets exist; + - this checklist, before the first signed release and before the first unsigned one: install on a Mac that has + never had Drosera; find Drosera as an AU in Logic and as a VST3 in another host; open the Standalone app and + confirm it asks for microphone access; uninstall by following the Conclusion screen. +- `2026-11-01-repository-and-release-design.md` gets a note at the top that this design replaces its zip and its + non-goals on installers and on AU and Standalone releases. +- `CLAUDE.md`: the `build_pkg.sh` and `check_pkg.sh` commands, and `tools/package/` in the code map. +- `CHANGELOG.md`, under Unreleased: the installer, the AU and Standalone formats, and the note for 0.1.x users. + +## Risks + +- **The signed path cannot run until the secrets exist.** CI exercises everything else on every push. The first + signed release may need debugging, and `RELEASING.md` says so. +- **Gatekeeper may tighten.** The probe holds for macOS 27.2. If a later macOS removes Open Anyway, unsigned releases + stop being installable without Terminal, and paying for the account becomes the only route. From 9a3de6bf9fdb28018f49d198fd4fda4e56501f95 Mon Sep 17 00:00:00 2001 From: Stefano Veloccia Date: Tue, 3 Nov 2026 19:13:34 +0100 Subject: [PATCH 02/10] Plan the macOS installer Co-Authored-By: Claude Opus 5.5 --- .../plans/2026-11-03-macos-installer.md | 289 ++++++++++++++++++ 1 file changed, 289 insertions(+) create mode 100644 docs/superpowers/plans/2026-11-03-macos-installer.md diff --git a/docs/superpowers/plans/2026-11-03-macos-installer.md b/docs/superpowers/plans/2026-11-03-macos-installer.md new file mode 100644 index 0000000..cfa01ad --- /dev/null +++ b/docs/superpowers/plans/2026-11-03-macos-installer.md @@ -0,0 +1,289 @@ +# macOS Installer Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Replace the release zip with `Drosera-X.Y.Z-macos.pkg`, which installs the VST3, the AU and the Standalone app. The package is built and checked on every CI run, and signed and notarized when the Apple secrets exist. + +**Architecture:** Two bash scripts in `tools/package/`. `build_pkg.sh` stages the bundles, runs `pkgbuild` once per format and `productbuild` with a `distribution.xml`, and signs when its variables are set. `check_pkg.sh` expands a package without installing it and checks it. A third script, `test_package.sh`, proves `check_pkg.sh` passes a good package and rejects broken ones. CI calls the scripts in place of the zip steps. + +**Tech Stack:** bash, `pkgbuild`, `productbuild`, `pkgutil`, `codesign`, `notarytool`, `stapler`, CMake/JUCE 8, GitHub Actions. + +**Spec:** `docs/superpowers/specs/2026-11-03-macos-installer-design.md` + +## Global Constraints + +- Output name: `Drosera--macos.pkg`. `` is the CI version input, or the version in `project()` in `CMakeLists.txt` when there is none. It may carry an rc suffix such as `0.1.1-rc1`. +- Identifiers and paths, exactly: `com.codeskine.drosera.vst3` → `/Library/Audio/Plug-Ins/VST3/Drosera.vst3`; `com.codeskine.drosera.au` → `/Library/Audio/Plug-Ins/Components/Drosera.component`; `com.codeskine.drosera.app` → `/Applications/Drosera.app`. +- Every bundle has `BundleIsRelocatable` false. Decided here, beyond the spec: it also has `BundleIsVersionChecked` false, so installing a package always writes its own version, even over a newer one. +- `distribution.xml`: `minSpecVersion="2"`, `hostArchitectures="arm64,x86_64"`, `enable_localSystem="true"` only, ``, three visible choices, all selected by default, and no `` element. +- The screens are in English, with the same text in both modes. Nothing mentions Gatekeeper or Open Anyway. +- Signing variables: `DEVELOPER_ID_APPLICATION`, `DEVELOPER_ID_INSTALLER`, `APPLE_ID`, `APPLE_TEAM_ID`, `APPLE_APP_PASSWORD`. None set → unsigned. All set → signed. Any other combination → exit 1 before building anything. +- Never `codesign --deep`. Only the Standalone app takes entitlements: `com.apple.security.device.audio-input`. +- Microphone text, verbatim: `Drosera uses audio input to feed external sound into its feedback loop.` +- Nothing touches `src/dsp/`. `tools/hardware-comparison/check_reference.sh build/render_cli` must still pass with no new checksums. +- The scripts start with `set -euo pipefail`, take paths that may contain spaces, and clean up their temporary folders with a `trap`. +- Commit messages follow the repo's style (an imperative sentence, no prefix) and end with `Co-Authored-By: Claude Opus 5.5 `. + +## Review Focus + +1. **A missing bundle.** If the AU or the Standalone app did not build, `build_pkg.sh` must fail and name the missing bundle, not ship a package with two formats. Test in Task 1. +2. **Paths and versions outside the happy path.** An artefacts folder or output path containing a space, and an rc version such as `0.1.1-rc1`, must both build and pass `check_pkg.sh`. Test in Task 1. +3. **Licence text with HTML characters.** The AGPL contains ``. The Read Me must show it escaped as `<https://www.gnu.org/licenses/>`, not swallow it as a tag. Test in Task 1. +4. **A broken seal on a bundle.** `check_pkg.sh` must reject a package whose bundle fails `codesign --verify --strict`. This happened before: JUCE writes `moduleinfo.json` after signing. Test in Task 1. +5. **Half-configured signing.** In CI, a partial set of signing variables must fail the build, never produce an unsigned package. Test in Task 3. + +--- + +### Task 1: Unsigned package, its checks, and their test + +**Files:** +- Create: `tools/package/build_pkg.sh`, `tools/package/check_pkg.sh`, `tools/package/test_package.sh` (all executable) +- Create: `tools/package/resources/distribution.xml`, `components.plist`, `welcome.html`, `conclusion.html`, `readme-header.html`, `scripts/au/postinstall` (executable) +- Modify: `CLAUDE.md` (Commands and Code map) + +**Interfaces:** +- Produces: `tools/package/build_pkg.sh `. `` holds `VST3/Drosera.vst3`, `AU/Drosera.component` and `Standalone/Drosera.app`, like `build/Drosera_artefacts/Release`. Exit 0 and the package at ``, or exit 1 with a message on stderr. +- Produces: `tools/package/check_pkg.sh `. It reads `PLUGIN_HOST_TEST`, default `build/plugin_host_test_artefacts/Release/plugin_host_test`, and `STATE_FIXTURE`, default `tests/fixtures/state-baseline.bin`. Exit 0, or exit 1 with one line per failed check on stderr. +- Produces: `tools/package/test_package.sh `, which prints `PASS ` / `FAIL ` for each case and exits 1 on any failure. +- Produces, for Task 3: a function `sign_and_notarize` in `build_pkg.sh`, called between staging and `productbuild` when signing is on, and a `signed_checks` block in `check_pkg.sh`. Task 1 leaves both as the unsigned branch only. + +- [ ] **Step 1: Write `test_package.sh`, the failing test** + +It builds packages into a temporary folder from `$1` and runs `check_pkg.sh` on each. Cases and assertions: +- `good`: `build_pkg.sh "$1" 0.0.0-test /Drosera.pkg`, then `check_pkg.sh` exits 0. +- `spaces_and_rc`: copy `$1` to `/arte facts/` and output to `/out dir/Drosera-0.1.1-rc1-macos.pkg`; both scripts exit 0. +- `readme_escapes_html`: the expanded package's `Resources/readme.html` contains `<https://www.gnu.org/licenses/>` and not ``. +- `missing_au`: copy `$1` without `AU/`; `build_pkg.sh` exits non-zero and its stderr contains `Drosera.component`. +- `relocatable_rejected`: build the same three component packages with plain `pkgbuild --root` (no `--component-plist`, so the bundles default to relocatable) and the repo's `distribution.xml`. `check_pkg.sh` exits non-zero and stderr contains `relocatable`. +- `broken_seal_rejected`: copy `$1`, append a byte to `VST3/Drosera.vst3/Contents/Resources/moduleinfo.json` (create it if absent), build. `check_pkg.sh` exits non-zero and stderr contains `codesign`. +- `two_components_rejected`: a product built from only the VST3 and AU component packages; `check_pkg.sh` exits non-zero. + +- [ ] **Step 2: Run it and see it fail** + +Run: `cmake --build build --target Drosera_VST3 Drosera_AU Drosera_Standalone plugin_host_test && tools/package/test_package.sh build/Drosera_artefacts/Release` +Expected: FAIL on every case, because `build_pkg.sh` does not exist. + +- [ ] **Step 3: Write the resources** + +- `distribution.xml`: as the Global Constraints say. Choices `vst3`, `au`, `app`, titled `VST3`, `Audio Unit`, `Standalone`. ``, ``, ``, title `Drosera`. The placeholder `@VERSION@` goes in the three `pkg-ref` versions. +- `components.plist`: the array `pkgbuild --analyze` produces for one bundle, with `BundleIsRelocatable` false, `BundleIsVersionChecked` false, `BundleOverwriteAction` `upgrade`. `RootRelativeBundlePath` stays `@BUNDLE@`, and the script fills it in per format. +- `welcome.html`: what Drosera is (one line from the README), the three formats with their paths, and that Customize leaves formats out. +- `readme-header.html`: `Copyright 2026 codeskine.`, the AGPLv3 notice, and the source address `https://github.com/codeskine/Drosera/releases`, as `docs/INSTALL.txt` words it today. +- `conclusion.html`: rescan plugins in the host, and the Standalone app is in Applications. To uninstall, delete the three paths. Users of 0.1.x: delete `~/Library/Audio/Plug-Ins/VST3/Drosera.vst3`, or the host finds two copies. +- `scripts/au/postinstall`: `#!/bin/sh`, `killall -9 AudioComponentRegistrar 2>/dev/null`, `exit 0`. + +- [ ] **Step 4: Implement `build_pkg.sh`** + +1. Check the three bundles exist and name any missing one. +2. Stage each with `ditto` into its own root. +3. Generate `readme.html`: `readme-header.html`, then for each licence file in the spec's order, an `

` with its name and its text in a `
` escaped with `sed -e 's/&/\&/g' -e 's//\>/g'`.
+4. Run `pkgbuild --root  --component-plist  --identifier  --version  --install-location ` for each format. For the AU only, add `--scripts resources/scripts/au`.
+5. Run `productbuild --distribution  --resources  --package-path  `.
+
+Leave the signing branch as a comment naming `sign_and_notarize` for Task 3.
+
+- [ ] **Step 5: Implement `check_pkg.sh`**
+
+1. Expand with `pkgutil --expand-full` into a temporary folder.
+2. Require exactly three component folders. Each `PackageInfo` must have the identifier and `install-location` of its row, and none may have a `` element; else fail with `relocatable`.
+3. Require `Distribution` to contain `hostArchitectures="arm64,x86_64"` and `min="11.0"`.
+4. Run `codesign --verify --strict` on each bundle under `Payload`. A failure prints a line containing `codesign`.
+5. Run `"$PLUGIN_HOST_TEST"  "$STATE_FIXTURE"`.
+
+- [ ] **Step 6: Run the test and see it pass**
+
+Run: `tools/package/test_package.sh build/Drosera_artefacts/Release`
+Expected: `PASS` for all seven cases, exit 0.
+
+- [ ] **Step 7: Add the commands to `CLAUDE.md`**
+
+Under Commands, two blocks:
+- `tools/package/build_pkg.sh build/Drosera_artefacts/Release 0.0.0 build/Drosera.pkg && tools/package/check_pkg.sh build/Drosera.pkg`
+- `tools/package/test_package.sh build/Drosera_artefacts/Release`
+
+In the code map, a row for `tools/package/`: the installer package, its checks, and the installer's screens.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add tools/package CLAUDE.md
+git commit -m "Build an installer package for the VST3, AU and Standalone, and check it without installing"
+```
+
+### Task 2: Microphone permission for the Standalone app
+
+**Files:**
+- Modify: `CMakeLists.txt` (the `juce_add_plugin(Drosera …)` call)
+- Create: `tools/package/resources/Drosera.entitlements`
+- Modify: `tools/package/test_package.sh`
+
+**Interfaces:**
+- Produces: `tools/package/resources/Drosera.entitlements`, a plist whose only key is `com.apple.security.device.audio-input`, true. Task 3 signs the Standalone app with it.
+
+- [ ] **Step 1: Add the failing case `standalone_asks_for_microphone` to `test_package.sh`**
+
+In the `good` package's expanded Standalone app, `/usr/libexec/PlistBuddy -c "Print :NSMicrophoneUsageDescription" Info.plist` prints exactly `Drosera uses audio input to feed external sound into its feedback loop.`
+Also: `plutil -lint` passes on `Drosera.entitlements`, and its only key is `com.apple.security.device.audio-input`.
+
+- [ ] **Step 2: Run it and see it fail**
+
+Run: `tools/package/test_package.sh build/Drosera_artefacts/Release`
+Expected: `FAIL standalone_asks_for_microphone`.
+
+- [ ] **Step 3: Add `MICROPHONE_PERMISSION_ENABLED TRUE` and `MICROPHONE_PERMISSION_TEXT` with the constraint's text to `juce_add_plugin`, and write `Drosera.entitlements`**
+
+- [ ] **Step 4: Rebuild and run everything that could notice**
+
+Run: `cmake --build build && tools/package/test_package.sh build/Drosera_artefacts/Release && build/render_test && tools/hardware-comparison/check_reference.sh build/render_cli`
+Expected: all PASS. The reference check shows no changed checksum.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add CMakeLists.txt tools/package
+git commit -m "Ask for microphone access in the Standalone app, and add its entitlement for signing"
+```
+
+### Task 3: Signed mode
+
+**Files:**
+- Modify: `tools/package/build_pkg.sh`, `tools/package/check_pkg.sh`, `tools/package/test_package.sh`
+
+**Interfaces:**
+- Consumes: `Drosera.entitlements` from Task 2, and the signing variables in the Global Constraints.
+- Produces: in signed mode, `build_pkg.sh` writes a signed, notarized and stapled package to the same ``.
+
+- [ ] **Step 1: Add the failing cases**
+
+- `partial_signing_vars_rejected`: run `build_pkg.sh` once with only `DEVELOPER_ID_APPLICATION` set, and once with all of them but `APPLE_APP_PASSWORD`. Each must exit non-zero within a second, print `signing` on stderr, and leave no output file.
+- `unsigned_package_has_no_signature`: on the `good` package, `pkgutil --check-signature` reports `no signature`, and `check_pkg.sh` still exits 0. The signed checks apply only to a signed package.
+
+- [ ] **Step 2: Run them and see `partial_signing_vars_rejected` fail**
+
+Run: `tools/package/test_package.sh build/Drosera_artefacts/Release`
+Expected: `FAIL partial_signing_vars_rejected`.
+
+- [ ] **Step 3: Implement the check of the variables and `sign_and_notarize`**
+
+Check the variables first, before any build work. `sign_and_notarize` runs on the staged bundles before `pkgbuild`:
+- `codesign --force --options runtime --timestamp --sign "$DEVELOPER_ID_APPLICATION"` on the VST3 and the AU;
+- the same plus `--entitlements resources/Drosera.entitlements` on the app.
+
+After `productbuild`, which now takes `--sign "$DEVELOPER_ID_INSTALLER"`:
+- run `xcrun notarytool submit  --apple-id … --team-id … --password … --wait --output-format json`;
+- read `status` and `id` from the JSON. Unless the status is `Accepted`, print `xcrun notarytool log  …` and exit 1;
+- then run `xcrun stapler staple `.
+
+- [ ] **Step 4: Implement `signed_checks` in `check_pkg.sh`**
+
+When `pkgutil --check-signature` does not say `no signature`:
+- it must name `Developer ID Installer`;
+- `spctl --assess --type install -vv` must print `source=Notarized Developer ID`;
+- `xcrun stapler validate` must exit 0;
+- every bundle must pass `codesign --verify --strict` and show `runtime` in `codesign -dv` flags.
+
+- [ ] **Step 5: Run the test and see it pass**
+
+Run: `tools/package/test_package.sh build/Drosera_artefacts/Release`
+Expected: all PASS. The signed path itself runs only with real certificates, and Task 6 says so.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add tools/package
+git commit -m "Sign, notarize and staple the package when the Developer ID variables are set"
+```
+
+### Task 4: CI and release
+
+**Files:**
+- Modify: `.github/workflows/ci.yml`
+- Modify: `.github/workflows/release.yml`
+
+**Interfaces:**
+- Consumes: `build_pkg.sh`, `check_pkg.sh`, `test_package.sh`.
+- Produces: the `drosera-macos` artefact, holding `Drosera--macos.pkg`.
+
+- [ ] **Step 1: Edit `ci.yml`**
+
+1. Add `Drosera_Standalone` to the Build step's targets.
+2. After "Check reference renders", add a step "Test the package scripts" that runs `tools/package/test_package.sh build/Drosera_artefacts/Release`.
+3. Replace "Sign with Developer ID and notarize" and "Package" with one step, "Build and check the installer", which runs on every push:
+   - the version is `inputs.version`, or else `sed -nE 's/^project\(Drosera VERSION ([0-9.]+).*/\1/p' CMakeLists.txt`;
+   - when `inputs.version != ''` and `CAN_NOTARIZE == 'true'`, it imports the `.p12` into a temporary keychain, as the old step does, and exports `DEVELOPER_ID_APPLICATION` and `DEVELOPER_ID_INSTALLER`, read with `security find-identity -v -p basic "$keychain"`. Only this step sees the secrets;
+   - then it runs `build_pkg.sh` and `check_pkg.sh` on `Drosera-$version-macos.pkg`.
+4. "Upload the package" uploads `Drosera-${{ inputs.version }}-macos.pkg`.
+
+- [ ] **Step 2: Edit `release.yml`**
+
+1. The publish job uses the `.pkg` in place of the zip, both in `sha256sum` and in `gh release create`.
+2. Add a job-level env `SIGNED: ${{ secrets.APPLE_ID != '' }}`. When it is not `true`, append to `notes.md` a paragraph: the package is not notarized yet; open it, then go to System Settings → Privacy & Security and click Open Anyway.
+
+- [ ] **Step 3: Check the workflows**
+
+Run: `actionlint .github/workflows/ci.yml .github/workflows/release.yml`. If it is missing, install it with `brew install actionlint`.
+Expected: no errors.
+
+- [ ] **Step 4: Commit, push the branch, and watch CI**
+
+```bash
+git add .github/workflows
+git commit -m "Build and check the installer in CI, and release it in place of the zip"
+git push -u origin macos-installer
+```
+
+Expected: the CI run for the branch is green, with "Test the package scripts" and "Build and check the installer" passing.
+
+### Task 5: Documents
+
+**Files:**
+- Delete: `docs/INSTALL.txt`
+- Modify: `README.md` (Install), `docs/RELEASING.md`, `docs/superpowers/specs/2026-11-01-repository-and-release-design.md` (a note at the top), `CHANGELOG.md` (Unreleased)
+
+- [ ] **Step 1: Check that nothing still uses `INSTALL.txt`**
+
+Run: `git grep -n "INSTALL.txt"`
+Expected: matches only in `docs/RELEASING.md`, `README.md` and the 2026-11-01 spec. All three are changed below; the old spec keeps its own text under the new note.
+
+- [ ] **Step 2: Write the changes the spec's Documents section lists**
+
+- **README:** download the `.pkg` from Releases and open it. "If macOS blocks the installer": open it, then System Settings → Privacy & Security → Open Anyway; no Terminal. Then how to uninstall, and the note for 0.1.x users.
+- **`RELEASING.md`:**
+  - how to request both Developer ID certificates and export them as one `.p12`;
+  - that the signed path has never run;
+  - the manual checklist from the spec;
+  - step 5 of the release steps now downloads and installs the `.pkg`;
+  - remove the unblocking text.
+- **CHANGELOG:** under Added, the installer and the AU and Standalone formats. Under Changed, the 0.1.x note.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git rm docs/INSTALL.txt
+git add README.md docs/RELEASING.md docs/superpowers/specs/2026-11-01-repository-and-release-design.md CHANGELOG.md
+git commit -m "Document installing with the package, and how to sign and notarize it"
+```
+
+### Task 6: Install on this Mac (manual, with the owner)
+
+Run the spec's checklist on the unsigned package. Only the owner can click through Installer and a DAW.
+
+- [ ] **Step 1: Build the package from the branch, quarantine it as Safari would, and reveal it in Finder**
+
+```bash
+tools/package/build_pkg.sh build/Drosera_artefacts/Release 0.0.0 ~/Downloads/Drosera-0.0.0-macos.pkg
+xattr -w com.apple.quarantine "0083;$(printf '%x' $(date +%s));Safari;$(uuidgen)" ~/Downloads/Drosera-0.0.0-macos.pkg
+open -R ~/Downloads/Drosera-0.0.0-macos.pkg
+```
+
+- [ ] **Step 2: The owner installs it**
+
+They open it, use Open Anyway, and look at Customize and the three screens. Then they find Drosera as an AU in Logic and as a VST3 in another host, and open the Standalone app, which should ask for microphone access.
+
+- [ ] **Step 3: Check the result**
+
+None of the three installed bundles has `com.apple.quarantine` (`xattr -l`). `pkgutil --pkgs | grep com.codeskine.drosera` lists three receipts.
+
+- [ ] **Step 4: Report**
+
+Say what passed, what the owner saw, and that the signed path is untested until the secrets exist.

From c7082c812d4a3248b34d5163f6fd7dac858d1445 Mon Sep 17 00:00:00 2001
From: Stefano Veloccia 
Date: Tue, 3 Nov 2026 19:17:28 +0100
Subject: [PATCH 03/10] Build an installer package for the VST3, AU and
 Standalone, and check it without installing

Co-Authored-By: Claude Opus 5.5 
---
 CLAUDE.md                                     |   9 ++
 tools/package/build_pkg.sh                    |  82 +++++++++++
 tools/package/check_pkg.sh                    |  72 ++++++++++
 tools/package/resources/components.plist      |  18 +++
 tools/package/resources/conclusion.html       |  16 +++
 tools/package/resources/distribution.xml      |  29 ++++
 tools/package/resources/readme-header.html    |   7 +
 .../package/resources/scripts/au/postinstall  |   4 +
 tools/package/resources/welcome.html          |  14 ++
 tools/package/test_package.sh                 | 135 ++++++++++++++++++
 10 files changed, 386 insertions(+)
 create mode 100755 tools/package/build_pkg.sh
 create mode 100755 tools/package/check_pkg.sh
 create mode 100644 tools/package/resources/components.plist
 create mode 100644 tools/package/resources/conclusion.html
 create mode 100644 tools/package/resources/distribution.xml
 create mode 100644 tools/package/resources/readme-header.html
 create mode 100755 tools/package/resources/scripts/au/postinstall
 create mode 100644 tools/package/resources/welcome.html
 create mode 100755 tools/package/test_package.sh

diff --git a/CLAUDE.md b/CLAUDE.md
index d29d700..b3221bb 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -28,6 +28,14 @@ build/plugin_host_test_artefacts/Release/plugin_host_test build/Drosera_artefact
 tools/hardware-comparison/check_reference.sh build/render_cli
 ```
 
+```bash
+tools/package/build_pkg.sh build/Drosera_artefacts/Release 0.0.0 build/Drosera.pkg && tools/package/check_pkg.sh build/Drosera.pkg
+```
+
+```bash
+tools/package/test_package.sh build/Drosera_artefacts/Release
+```
+
 ## Code map
 
 | Path | Holds |
@@ -43,6 +51,7 @@ tools/hardware-comparison/check_reference.sh build/render_cli
 | `assets/fonts/` | The interface's fonts, embedded as binary data, with their licences |
 | `third_party/` | Vendored DaisySP |
 | `tools/hardware-comparison/` | Comparison against a real unit, and the reference checksums |
+| `tools/package/` | The installer package: building it, checking it without installing, and its screens |
 | `docs/superpowers/` | Design specs and implementation plans |
 
 ## Rules
diff --git a/tools/package/build_pkg.sh b/tools/package/build_pkg.sh
new file mode 100755
index 0000000..5ae21b4
--- /dev/null
+++ b/tools/package/build_pkg.sh
@@ -0,0 +1,82 @@
+#!/bin/bash
+# Builds Drosera's installer package: one component package per format, combined under distribution.xml.
+# usage: build_pkg.sh   
+#    holds VST3/Drosera.vst3, AU/Drosera.component and Standalone/Drosera.app,
+#   like build/Drosera_artefacts/Release.
+set -euo pipefail
+
+if [ "$#" -ne 3 ]; then
+    echo "usage: build_pkg.sh   " >&2
+    exit 2
+fi
+
+here=$(cd "$(dirname "$0")" && pwd)
+repo=$(cd "$here/../.." && pwd)
+resources="$here/resources"
+artefacts=$1
+version=$2
+output=$3
+
+# format, bundle, identifier, install location
+formats=(
+    "VST3 Drosera.vst3 com.codeskine.drosera.vst3 /Library/Audio/Plug-Ins/VST3"
+    "AU Drosera.component com.codeskine.drosera.au /Library/Audio/Plug-Ins/Components"
+    "Standalone Drosera.app com.codeskine.drosera.app /Applications")
+
+missing=0
+for row in "${formats[@]}"; do
+    read -r format bundle _ _ <<< "$row"
+    if [ ! -d "$artefacts/$format/$bundle" ]; then
+        echo "build_pkg: missing $artefacts/$format/$bundle" >&2
+        missing=1
+    fi
+done
+[ "$missing" -eq 0 ] || exit 1
+
+work=$(mktemp -d)
+trap 'rm -rf "$work"' EXIT
+mkdir -p "$work/components" "$work/screens"
+
+for row in "${formats[@]}"; do
+    read -r format bundle _ _ <<< "$row"
+    mkdir -p "$work/root-$format"
+    ditto "$artefacts/$format/$bundle" "$work/root-$format/$bundle"
+done
+
+# Task 3 adds sign_and_notarize here, on the staged bundles.
+
+licences=(
+    LICENSE
+    LICENSE-AudreyII
+    THIRD_PARTY_LICENSES.md
+    third_party/DaisySP/LICENSE
+    assets/fonts/OFL-Inter.txt
+    assets/fonts/OFL-Cormorant.txt)
+{
+    cat "$resources/readme-header.html"
+    for licence in "${licences[@]}"; do
+        echo "

$licence

" + echo "
"
+        sed -e 's/&/\&/g' -e 's//\>/g' "$repo/$licence"
+        echo "
" + done + echo "" +} > "$work/screens/readme.html" +cp "$resources/welcome.html" "$resources/conclusion.html" "$work/screens/" + +for row in "${formats[@]}"; do + read -r format bundle identifier location <<< "$row" + sed "s/@BUNDLE@/$bundle/" "$resources/components.plist" > "$work/components-$format.plist" + scripts=() + [ "$format" = AU ] && scripts=(--scripts "$resources/scripts/au") + pkgbuild --quiet --root "$work/root-$format" --component-plist "$work/components-$format.plist" \ + --identifier "$identifier" --version "$version" --install-location "$location" ${scripts[@]+"${scripts[@]}"} \ + "$work/components/Drosera-$format.pkg" +done + +sed "s/@VERSION@/$version/g" "$resources/distribution.xml" > "$work/distribution.xml" +mkdir -p "$(dirname "$output")" +productbuild --quiet --distribution "$work/distribution.xml" --resources "$work/screens" \ + --package-path "$work/components" "$work/Drosera.pkg" +mv -f "$work/Drosera.pkg" "$output" +echo "build_pkg: wrote $output" diff --git a/tools/package/check_pkg.sh b/tools/package/check_pkg.sh new file mode 100755 index 0000000..02419b7 --- /dev/null +++ b/tools/package/check_pkg.sh @@ -0,0 +1,72 @@ +#!/bin/bash +# Checks Drosera's installer package without installing it. +# usage: check_pkg.sh +# PLUGIN_HOST_TEST (default build/plugin_host_test_artefacts/Release/plugin_host_test) and +# STATE_FIXTURE (default tests/fixtures/state-baseline.bin) load the packaged VST3. +set -euo pipefail + +if [ "$#" -ne 1 ]; then + echo "usage: check_pkg.sh " >&2 + exit 2 +fi + +repo=$(cd "$(dirname "$0")/../.." && pwd) +package=$1 +host_test=${PLUGIN_HOST_TEST:-$repo/build/plugin_host_test_artefacts/Release/plugin_host_test} +fixture=${STATE_FIXTURE:-$repo/tests/fixtures/state-baseline.bin} + +work=$(mktemp -d) +trap 'rm -rf "$work"' EXIT +expanded="$work/expanded" +pkgutil --expand-full "$package" "$expanded" > /dev/null + +failures=0 +fail() { echo "check_pkg: $1" >&2; failures=$((failures + 1)); } + +# identifier, install location, bundle +expected=( + "com.codeskine.drosera.vst3 /Library/Audio/Plug-Ins/VST3 Drosera.vst3" + "com.codeskine.drosera.au /Library/Audio/Plug-Ins/Components Drosera.component" + "com.codeskine.drosera.app /Applications Drosera.app") + +components=("$expanded"/*.pkg) +if [ "${#components[@]}" -ne 3 ] || [ ! -d "${components[0]}" ]; then + fail "expected 3 component packages, found ${#components[@]}" +fi + +for row in "${expected[@]}"; do + read -r identifier location bundle <<< "$row" + found="" + for component in "${components[@]}"; do + [ -f "$component/PackageInfo" ] || continue + if grep -q "identifier=\"$identifier\"" "$component/PackageInfo"; then found=$component; fi + done + if [ -z "$found" ]; then + fail "no component package $identifier" + continue + fi + grep -q "install-location=\"$location\"" "$found/PackageInfo" \ + || fail "$identifier does not install to $location" + grep -q "" "$found/PackageInfo" && fail "$identifier has a relocatable bundle" + if [ ! -d "$found/Payload/$bundle" ]; then + fail "$identifier does not hold $bundle" + continue + fi + codesign --verify --strict "$found/Payload/$bundle" 2> "$work/codesign.err" \ + || fail "codesign rejects $bundle: $(tr '\n' ' ' < "$work/codesign.err")" +done + +distribution="$expanded/Distribution" +grep -q 'hostArchitectures="arm64,x86_64"' "$distribution" || fail "Distribution does not list arm64 and x86_64" +grep -q 'min="11.0"' "$distribution" || fail "Distribution does not require macOS 11" + +vst3=$(find "$expanded" -path '*/Payload/Drosera.vst3' -maxdepth 3 | head -1) +if [ -n "$vst3" ]; then + "$host_test" "$vst3" "$fixture" > "$work/host.log" 2>&1 \ + || fail "plugin_host_test fails on the packaged VST3: $(tail -3 "$work/host.log" | tr '\n' ' ')" +fi + +if [ "$failures" -ne 0 ]; then + exit 1 +fi +echo "check_pkg: $package is fine" diff --git a/tools/package/resources/components.plist b/tools/package/resources/components.plist new file mode 100644 index 0000000..aba87be --- /dev/null +++ b/tools/package/resources/components.plist @@ -0,0 +1,18 @@ + + + + + + BundleHasStrictIdentifier + + BundleIsRelocatable + + BundleIsVersionChecked + + BundleOverwriteAction + upgrade + RootRelativeBundlePath + @BUNDLE@ + + + diff --git a/tools/package/resources/conclusion.html b/tools/package/resources/conclusion.html new file mode 100644 index 0000000..7a05076 --- /dev/null +++ b/tools/package/resources/conclusion.html @@ -0,0 +1,16 @@ + + + +

Drosera is installed

+

Rescan plugins in your host. Drosera loads as an instrument. The Standalone app is in Applications.

+

Upgrading from 0.1.x

+

Earlier versions were copied by hand to your home folder. Delete +~/Library/Audio/Plug-Ins/VST3/Drosera.vst3, or your host finds two copies of Drosera.

+

Uninstalling

+

Delete these three items:

+
    +
  • /Library/Audio/Plug-Ins/VST3/Drosera.vst3
  • +
  • /Library/Audio/Plug-Ins/Components/Drosera.component
  • +
  • /Applications/Drosera.app
  • +
+ diff --git a/tools/package/resources/distribution.xml b/tools/package/resources/distribution.xml new file mode 100644 index 0000000..9d1f686 --- /dev/null +++ b/tools/package/resources/distribution.xml @@ -0,0 +1,29 @@ + + + Drosera + + + + + + + + + + + + + + + + + + + + + + + Drosera-VST3.pkg + Drosera-AU.pkg + Drosera-Standalone.pkg + diff --git a/tools/package/resources/readme-header.html b/tools/package/resources/readme-header.html new file mode 100644 index 0000000..f0cee92 --- /dev/null +++ b/tools/package/resources/readme-header.html @@ -0,0 +1,7 @@ + + + +

Licence

+

Copyright 2026 codeskine. Drosera is free software under the GNU Affero General Public License, version 3. The +source for this version is attached to its release at https://github.com/codeskine/Drosera/releases

+

Third-party code and fonts keep their own terms. The full texts follow.

diff --git a/tools/package/resources/scripts/au/postinstall b/tools/package/resources/scripts/au/postinstall new file mode 100755 index 0000000..9da81e6 --- /dev/null +++ b/tools/package/resources/scripts/au/postinstall @@ -0,0 +1,4 @@ +#!/bin/sh +# Hosts cache the Audio Units they found: restart the registrar so they see this version without a restart. +killall -9 AudioComponentRegistrar 2>/dev/null +exit 0 diff --git a/tools/package/resources/welcome.html b/tools/package/resources/welcome.html new file mode 100644 index 0000000..6818b59 --- /dev/null +++ b/tools/package/resources/welcome.html @@ -0,0 +1,14 @@ + + + +

Drosera

+

A feedback drone synth. Drosera makes sound on its own: a noise floor feeds two string resonators inside a +saturating loop, and you steer what the loop settles on.

+

This installer puts Drosera on this Mac for all users, in three formats:

+
    +
  • VST3 in /Library/Audio/Plug-Ins/VST3
  • +
  • Audio Unit in /Library/Audio/Plug-Ins/Components
  • +
  • Standalone app in /Applications
  • +
+

To leave out a format, click Customize on the Installation Type step.

+ diff --git a/tools/package/test_package.sh b/tools/package/test_package.sh new file mode 100755 index 0000000..edbd5a5 --- /dev/null +++ b/tools/package/test_package.sh @@ -0,0 +1,135 @@ +#!/bin/bash +# Proves that check_pkg.sh passes a good package and rejects broken ones, and that build_pkg.sh refuses bad input. +# usage: test_package.sh (the folder holding VST3/, AU/ and Standalone/) +set -uo pipefail + +if [ "$#" -ne 1 ]; then + echo "usage: test_package.sh " >&2 + exit 2 +fi + +here=$(cd "$(dirname "$0")" && pwd) +artefacts=$(cd "$1" && pwd) +build="$here/build_pkg.sh" +check="$here/check_pkg.sh" +tmp=$(mktemp -d) +trap 'rm -rf "$tmp"' EXIT +failures=0 + +pass() { echo "PASS $1"; } +fail() { echo "FAIL $1: $2"; failures=$((failures + 1)); } + +# Builds the three component packages with pkgbuild and a component plist that makes each bundle relocatable, and a +# product from them, leaving out the formats named after the output path. +plain_product() { + local out=$1; shift + local work="$tmp/plain-$RANDOM" + mkdir -p "$work/components" "$work/resources" + local -a rows=( + "VST3 Drosera.vst3 com.codeskine.drosera.vst3 /Library/Audio/Plug-Ins/VST3" + "AU Drosera.component com.codeskine.drosera.au /Library/Audio/Plug-Ins/Components" + "Standalone Drosera.app com.codeskine.drosera.app /Applications") + local row format bundle id location skip + for row in "${rows[@]}"; do + read -r format bundle id location <<< "$row" + skip=0 + for left_out in "$@"; do [ "$left_out" = "$format" ] && skip=1; done + [ "$skip" = 1 ] && continue + mkdir -p "$work/root-$format" + ditto "$artefacts/$format/$bundle" "$work/root-$format/$bundle" + sed -e "s/@BUNDLE@/$bundle/" -e '/BundleIsRelocatable/{n;s/false/true/;}' \ + "$here/resources/components.plist" > "$work/components-$format.plist" + pkgbuild --quiet --root "$work/root-$format" --component-plist "$work/components-$format.plist" \ + --identifier "$id" --version 0.0.0 --install-location "$location" "$work/components/Drosera-$format.pkg" + done + cp "$here"/resources/*.html "$work/resources/" + echo "test" > "$work/resources/readme.html" + local distribution="$work/distribution.xml" + sed 's/@VERSION@/0.0.0/g' "$here/resources/distribution.xml" > "$distribution" + for left_out in "$@"; do + [ "$left_out" = "Standalone" ] \ + && sed -i '' -E -e '//d' -e '/drosera\.app|choice="app"/d' "$distribution" + done + productbuild --quiet --distribution "$distribution" --resources "$work/resources" \ + --package-path "$work/components" "$out" +} + +# good +good="$tmp/Drosera.pkg" +if "$build" "$artefacts" 0.0.0-test "$good" > "$tmp/good.log" 2>&1 && "$check" "$good" >> "$tmp/good.log" 2>&1; then + pass good +else + fail good "$(tail -5 "$tmp/good.log")" +fi + +# spaces_and_rc +mkdir -p "$tmp/arte facts" "$tmp/out dir" +ditto "$artefacts" "$tmp/arte facts" +spaced="$tmp/out dir/Drosera-0.1.1-rc1-macos.pkg" +if "$build" "$tmp/arte facts" 0.1.1-rc1 "$spaced" > "$tmp/spaced.log" 2>&1 \ + && "$check" "$spaced" >> "$tmp/spaced.log" 2>&1; then + pass spaces_and_rc +else + fail spaces_and_rc "$(tail -5 "$tmp/spaced.log")" +fi + +# readme_escapes_html +if [ -f "$good" ] && pkgutil --expand "$good" "$tmp/good-expanded" > /dev/null 2>&1 \ + && grep -q '<https://www.gnu.org/licenses/>' "$tmp/good-expanded/Resources/readme.html" \ + && ! grep -q '' "$tmp/good-expanded/Resources/readme.html"; then + pass readme_escapes_html +else + fail readme_escapes_html "the Read Me does not hold the escaped AGPL address" +fi + +# missing_au +mkdir -p "$tmp/no-au" +ditto "$artefacts/VST3" "$tmp/no-au/VST3" +ditto "$artefacts/Standalone" "$tmp/no-au/Standalone" +if "$build" "$tmp/no-au" 0.0.0 "$tmp/no-au.pkg" > /dev/null 2> "$tmp/no-au.err"; then + fail missing_au "build_pkg.sh succeeded without the AU" +elif ! grep -q 'Drosera.component' "$tmp/no-au.err"; then + fail missing_au "the error does not name Drosera.component: $(cat "$tmp/no-au.err")" +elif [ -e "$tmp/no-au.pkg" ]; then + fail missing_au "a package was written anyway" +else + pass missing_au +fi + +# relocatable_rejected +relocatable="$tmp/relocatable.pkg" +if ! plain_product "$relocatable" > "$tmp/relocatable.log" 2>&1; then + fail relocatable_rejected "could not build the test package: $(tail -3 "$tmp/relocatable.log")" +elif "$check" "$relocatable" > /dev/null 2> "$tmp/relocatable.err"; then + fail relocatable_rejected "check_pkg.sh accepted relocatable bundles" +elif ! grep -q 'relocatable' "$tmp/relocatable.err"; then + fail relocatable_rejected "the error does not say relocatable: $(cat "$tmp/relocatable.err")" +else + pass relocatable_rejected +fi + +# broken_seal_rejected +mkdir -p "$tmp/broken" +ditto "$artefacts" "$tmp/broken" +printf 'x' >> "$tmp/broken/VST3/Drosera.vst3/Contents/Resources/moduleinfo.json" +if ! "$build" "$tmp/broken" 0.0.0 "$tmp/broken.pkg" > "$tmp/broken.log" 2>&1; then + fail broken_seal_rejected "could not build the test package: $(tail -3 "$tmp/broken.log")" +elif "$check" "$tmp/broken.pkg" > /dev/null 2> "$tmp/broken.err"; then + fail broken_seal_rejected "check_pkg.sh accepted a broken seal" +elif ! grep -q 'codesign' "$tmp/broken.err"; then + fail broken_seal_rejected "the error does not mention codesign: $(cat "$tmp/broken.err")" +else + pass broken_seal_rejected +fi + +# two_components_rejected +two="$tmp/two.pkg" +if ! plain_product "$two" Standalone > "$tmp/two.log" 2>&1; then + fail two_components_rejected "could not build the test package: $(tail -3 "$tmp/two.log")" +elif "$check" "$two" > /dev/null 2>&1; then + fail two_components_rejected "check_pkg.sh accepted a package without the Standalone app" +else + pass two_components_rejected +fi + +[ "$failures" -eq 0 ] From bc05bdd15289d3747b86bf9e92c6613cf53c3358 Mon Sep 17 00:00:00 2001 From: Stefano Veloccia Date: Tue, 3 Nov 2026 19:26:44 +0100 Subject: [PATCH 04/10] Ask for microphone access in the Standalone app, and add its entitlement for signing Co-Authored-By: Claude Opus 5.5 --- CMakeLists.txt | 2 ++ tools/package/resources/Drosera.entitlements | 8 ++++++++ tools/package/test_package.sh | 17 +++++++++++++++++ 3 files changed, 27 insertions(+) create mode 100644 tools/package/resources/Drosera.entitlements diff --git a/CMakeLists.txt b/CMakeLists.txt index acdb742..91357ca 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -75,6 +75,8 @@ if(DROSERA_BUILD_PLUGIN) PRODUCT_NAME "Drosera" IS_SYNTH TRUE NEEDS_MIDI_INPUT TRUE + MICROPHONE_PERMISSION_ENABLED TRUE + MICROPHONE_PERMISSION_TEXT "Drosera uses audio input to feed external sound into its feedback loop." COPY_PLUGIN_AFTER_BUILD FALSE) target_sources(Drosera PRIVATE ${DROSERA_PLUGIN_SOURCES}) diff --git a/tools/package/resources/Drosera.entitlements b/tools/package/resources/Drosera.entitlements new file mode 100644 index 0000000..d459cb2 --- /dev/null +++ b/tools/package/resources/Drosera.entitlements @@ -0,0 +1,8 @@ + + + + + com.apple.security.device.audio-input + + + diff --git a/tools/package/test_package.sh b/tools/package/test_package.sh index edbd5a5..f856cdc 100755 --- a/tools/package/test_package.sh +++ b/tools/package/test_package.sh @@ -82,6 +82,23 @@ else fail readme_escapes_html "the Read Me does not hold the escaped AGPL address" fi +# standalone_asks_for_microphone +microphone_text="Drosera uses audio input to feed external sound into its feedback loop." +entitlements="$here/resources/Drosera.entitlements" +app_plist="$tmp/good-full/Drosera-Standalone.pkg/Payload/Drosera.app/Contents/Info.plist" +if [ -f "$good" ]; then pkgutil --expand-full "$good" "$tmp/good-full" > /dev/null 2>&1; fi +asked=$(/usr/libexec/PlistBuddy -c "Print :NSMicrophoneUsageDescription" "$app_plist" 2>/dev/null || true) +keys=$(plutil -convert json -o - "$entitlements" 2>/dev/null || true) +if [ "$asked" != "$microphone_text" ]; then + fail standalone_asks_for_microphone "NSMicrophoneUsageDescription is '$asked'" +elif ! plutil -lint "$entitlements" > /dev/null 2>&1; then + fail standalone_asks_for_microphone "Drosera.entitlements is missing or invalid" +elif [ "$keys" != '{"com.apple.security.device.audio-input":true}' ]; then + fail standalone_asks_for_microphone "Drosera.entitlements holds $keys" +else + pass standalone_asks_for_microphone +fi + # missing_au mkdir -p "$tmp/no-au" ditto "$artefacts/VST3" "$tmp/no-au/VST3" From 5d926c602efc8e9253efa0758feb3ff16c40513e Mon Sep 17 00:00:00 2001 From: Stefano Veloccia Date: Tue, 3 Nov 2026 19:29:25 +0100 Subject: [PATCH 05/10] Sign, notarize and staple the package when the Developer ID variables are set Co-Authored-By: Claude Opus 5.5 --- tools/package/build_pkg.sh | 40 +++++++++++++++++++++++++++++++++-- tools/package/check_pkg.sh | 13 ++++++++++++ tools/package/test_package.sh | 28 ++++++++++++++++++++++++ 3 files changed, 79 insertions(+), 2 deletions(-) diff --git a/tools/package/build_pkg.sh b/tools/package/build_pkg.sh index 5ae21b4..05935c1 100755 --- a/tools/package/build_pkg.sh +++ b/tools/package/build_pkg.sh @@ -17,6 +17,16 @@ artefacts=$1 version=$2 output=$3 +# Signing takes all five variables or none: a half-configured CI must fail, not ship an unsigned package. +signing_vars=(DEVELOPER_ID_APPLICATION DEVELOPER_ID_INSTALLER APPLE_ID APPLE_TEAM_ID APPLE_APP_PASSWORD) +set_count=0 +for var in "${signing_vars[@]}"; do [ -n "${!var:-}" ] && set_count=$((set_count + 1)); done +if [ "$set_count" -ne 0 ] && [ "$set_count" -ne "${#signing_vars[@]}" ]; then + echo "build_pkg: signing needs all of ${signing_vars[*]}; only $set_count are set" >&2 + exit 1 +fi +signing=$([ "$set_count" -ne 0 ] && echo 1 || echo 0) + # format, bundle, identifier, install location formats=( "VST3 Drosera.vst3 com.codeskine.drosera.vst3 /Library/Audio/Plug-Ins/VST3" @@ -43,7 +53,30 @@ for row in "${formats[@]}"; do ditto "$artefacts/$format/$bundle" "$work/root-$format/$bundle" done -# Task 3 adds sign_and_notarize here, on the staged bundles. +# Each bundle on its own, never --deep: notarization needs the hardened runtime on every executable. Only the app +# takes entitlements; the plug-ins run with their host's. +sign_bundles() { + local -a sign=(codesign --force --options runtime --timestamp --sign "$DEVELOPER_ID_APPLICATION") + "${sign[@]}" "$work/root-VST3/Drosera.vst3" + "${sign[@]}" "$work/root-AU/Drosera.component" + "${sign[@]}" --entitlements "$resources/Drosera.entitlements" "$work/root-Standalone/Drosera.app" +} + +notarize_and_staple() { + local package=$1 result id status + local -a credentials=(--apple-id "$APPLE_ID" --team-id "$APPLE_TEAM_ID" --password "$APPLE_APP_PASSWORD") + result=$(xcrun notarytool submit "$package" "${credentials[@]}" --wait --output-format json) || true + id=$(plutil -extract id raw -o - - <<< "$result" 2>/dev/null || true) + status=$(plutil -extract status raw -o - - <<< "$result" 2>/dev/null || true) + if [ "$status" != Accepted ]; then + echo "build_pkg: notarization ended with '${status:-no status}': $result" >&2 + [ -n "$id" ] && xcrun notarytool log "$id" "${credentials[@]}" >&2 + exit 1 + fi + xcrun stapler staple "$package" +} + +[ "$signing" = 1 ] && sign_bundles licences=( LICENSE @@ -76,7 +109,10 @@ done sed "s/@VERSION@/$version/g" "$resources/distribution.xml" > "$work/distribution.xml" mkdir -p "$(dirname "$output")" +product_signing=() +[ "$signing" = 1 ] && product_signing=(--sign "$DEVELOPER_ID_INSTALLER" --timestamp) productbuild --quiet --distribution "$work/distribution.xml" --resources "$work/screens" \ - --package-path "$work/components" "$work/Drosera.pkg" + --package-path "$work/components" ${product_signing[@]+"${product_signing[@]}"} "$work/Drosera.pkg" +[ "$signing" = 1 ] && notarize_and_staple "$work/Drosera.pkg" mv -f "$work/Drosera.pkg" "$output" echo "build_pkg: wrote $output" diff --git a/tools/package/check_pkg.sh b/tools/package/check_pkg.sh index 02419b7..9b68665 100755 --- a/tools/package/check_pkg.sh +++ b/tools/package/check_pkg.sh @@ -66,6 +66,19 @@ if [ -n "$vst3" ]; then || fail "plugin_host_test fails on the packaged VST3: $(tail -3 "$work/host.log" | tr '\n' ' ')" fi +# A signed package must be signed for installation, notarized and stapled, with every bundle on the hardened runtime. +signature=$(pkgutil --check-signature "$package" 2>&1 || true) +if [[ "$signature" != *"no signature"* ]]; then + [[ "$signature" == *"Developer ID Installer"* ]] || fail "the package is not signed with Developer ID Installer" + spctl --assess --type install -vv "$package" 2>&1 | grep -q 'source=Notarized Developer ID' \ + || fail "spctl does not accept the package as notarized" + xcrun stapler validate "$package" > /dev/null 2>&1 || fail "the package has no stapled ticket" + for bundle in "$expanded"/*.pkg/Payload/Drosera.*; do + codesign -dv "$bundle" 2>&1 | grep -q 'flags=.*runtime' \ + || fail "$(basename "$bundle") is not signed with the hardened runtime" + done +fi + if [ "$failures" -ne 0 ]; then exit 1 fi diff --git a/tools/package/test_package.sh b/tools/package/test_package.sh index f856cdc..0c06a74 100755 --- a/tools/package/test_package.sh +++ b/tools/package/test_package.sh @@ -99,6 +99,34 @@ else pass standalone_asks_for_microphone fi +# partial_signing_vars_rejected +partial_ok=1 +for vars in "DEVELOPER_ID_APPLICATION=x" \ + "DEVELOPER_ID_APPLICATION=x DEVELOPER_ID_INSTALLER=y APPLE_ID=a APPLE_TEAM_ID=t"; do + rm -f "$tmp/partial.pkg" + started=$SECONDS + # shellcheck disable=SC2086 # each word of $vars is one assignment + if env -u DEVELOPER_ID_APPLICATION -u DEVELOPER_ID_INSTALLER -u APPLE_ID -u APPLE_TEAM_ID -u APPLE_APP_PASSWORD \ + $vars "$build" "$artefacts" 0.0.0 "$tmp/partial.pkg" > /dev/null 2> "$tmp/partial.err"; then + fail partial_signing_vars_rejected "build_pkg.sh succeeded with only $vars"; partial_ok=0 + elif ! grep -q 'signing' "$tmp/partial.err"; then + fail partial_signing_vars_rejected "the error does not mention signing: $(cat "$tmp/partial.err")"; partial_ok=0 + elif [ -e "$tmp/partial.pkg" ]; then + fail partial_signing_vars_rejected "a package was written with only $vars"; partial_ok=0 + elif [ $((SECONDS - started)) -gt 1 ]; then + fail partial_signing_vars_rejected "the check came after build work"; partial_ok=0 + fi +done +[ "$partial_ok" = 1 ] && pass partial_signing_vars_rejected + +# unsigned_package_has_no_signature +signature=$( [ -f "$good" ] && pkgutil --check-signature "$good" 2>&1 || true) +if [[ "$signature" == *"no signature"* ]] && "$check" "$good" > /dev/null 2>&1; then + pass unsigned_package_has_no_signature +else + fail unsigned_package_has_no_signature "the unsigned package carries a signature, or check_pkg.sh rejects it" +fi + # missing_au mkdir -p "$tmp/no-au" ditto "$artefacts/VST3" "$tmp/no-au/VST3" From 9df6db05be939d7f6ae7e3def3c4a9b355b04ec4 Mon Sep 17 00:00:00 2001 From: Stefano Veloccia Date: Tue, 3 Nov 2026 19:31:02 +0100 Subject: [PATCH 06/10] Build and check the installer in CI, and release it in place of the zip Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 70 ++++++++++++++++------------------- .github/workflows/release.yml | 11 +++++- 2 files changed, 41 insertions(+), 40 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 287577d..9e56ddc 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -42,7 +42,7 @@ jobs: "-DCMAKE_OSX_ARCHITECTURES=arm64;x86_64" - name: Build - run: cmake --build build --target voice_allocator_test render_test render_cli ui_test plugin_host_test Drosera_VST3 Drosera_AU + run: cmake --build build --target voice_allocator_test render_test render_cli ui_test plugin_host_test Drosera_VST3 Drosera_AU Drosera_Standalone - name: Test the release check run: python3 tools/test_release_check.py @@ -77,54 +77,48 @@ jobs: - name: Check reference renders run: tools/hardware-comparison/check_reference.sh build/render_cli - - name: Sign with Developer ID and notarize - if: inputs.version != '' && env.CAN_NOTARIZE == 'true' + - name: Test the package scripts + run: tools/package/test_package.sh build/Drosera_artefacts/Release + + - name: Build and check the installer env: # only this step sees them, not brew, pluginval or the tests + VERSION: ${{ inputs.version }} APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }} APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }} APPLE_ID: ${{ secrets.APPLE_ID }} APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }} APPLE_APP_PASSWORD: ${{ secrets.APPLE_APP_PASSWORD }} run: | - keychain="$RUNNER_TEMP/signing.keychain-db" - password=$(uuidgen) - security create-keychain -p "$password" "$keychain" - security unlock-keychain -p "$password" "$keychain" - security list-keychains -d user -s "$keychain" - echo "$APPLE_CERTIFICATE" | base64 --decode > "$RUNNER_TEMP/certificate.p12" - security import "$RUNNER_TEMP/certificate.p12" -k "$keychain" -P "$APPLE_CERTIFICATE_PASSWORD" -T /usr/bin/codesign - security set-key-partition-list -S apple-tool:,apple: -s -k "$password" "$keychain" - codesign --force --deep --options runtime --timestamp --sign "Developer ID Application" "$VST3" - ditto -c -k --keepParent "$VST3" "$RUNNER_TEMP/notarize.zip" - xcrun notarytool submit "$RUNNER_TEMP/notarize.zip" --apple-id "$APPLE_ID" --team-id "$APPLE_TEAM_ID" --password "$APPLE_APP_PASSWORD" --wait - xcrun stapler staple "$VST3" - - - name: Package - if: inputs.version != '' - env: - VERSION: ${{ inputs.version }} - run: | - stage="$RUNNER_TEMP/stage" - mkdir -p "$stage/licenses" - ditto "$VST3" "$stage/Drosera.vst3" - cp LICENSE THIRD_PARTY_LICENSES.md docs/INSTALL.txt "$stage/" - cp LICENSE-AudreyII "$stage/licenses/" - cp third_party/DaisySP/LICENSE "$stage/licenses/DaisySP-LICENSE" - ditto -c -k --norsrc --noextattr "$stage" "Drosera-$VERSION-macos.zip" - - # What a user unpacks is what must work, not the build folder. - unpacked="$RUNNER_TEMP/unpacked" - ditto -x -k "Drosera-$VERSION-macos.zip" "$unpacked" - ls -la "$unpacked" - test -f "$unpacked/Drosera.vst3/Contents/MacOS/Drosera" - test -x "$unpacked/Drosera.vst3/Contents/MacOS/Drosera" - codesign --verify --deep --strict "$unpacked/Drosera.vst3" - build/plugin_host_test_artefacts/Release/plugin_host_test "$unpacked/Drosera.vst3" tests/fixtures/state-baseline.bin + version="$VERSION" + [ -n "$version" ] || version=$(sed -nE 's/^project\(Drosera VERSION ([0-9.]+).*/\1/p' CMakeLists.txt) + + # Sign only a versioned build, and only when the secrets exist. build_pkg.sh signs when all five + # variables are set, so the others are cleared for every other build. + if [ -n "$VERSION" ] && [ "$CAN_NOTARIZE" = true ]; then + keychain="$RUNNER_TEMP/signing.keychain-db" + password=$(uuidgen) + security create-keychain -p "$password" "$keychain" + security unlock-keychain -p "$password" "$keychain" + security list-keychains -d user -s "$keychain" + echo "$APPLE_CERTIFICATE" | base64 --decode > "$RUNNER_TEMP/certificate.p12" + security import "$RUNNER_TEMP/certificate.p12" -k "$keychain" -P "$APPLE_CERTIFICATE_PASSWORD" \ + -T /usr/bin/codesign -T /usr/bin/productbuild + security set-key-partition-list -S apple-tool:,apple: -s -k "$password" "$keychain" + identities=$(security find-identity -v -p basic "$keychain") + DEVELOPER_ID_APPLICATION=$(sed -nE 's/.*"(Developer ID Application: [^"]*)".*/\1/p' <<< "$identities" | head -1) + DEVELOPER_ID_INSTALLER=$(sed -nE 's/.*"(Developer ID Installer: [^"]*)".*/\1/p' <<< "$identities" | head -1) + export DEVELOPER_ID_APPLICATION DEVELOPER_ID_INSTALLER + else + unset APPLE_ID APPLE_TEAM_ID APPLE_APP_PASSWORD + fi + + tools/package/build_pkg.sh build/Drosera_artefacts/Release "$version" "Drosera-$version-macos.pkg" + tools/package/check_pkg.sh "Drosera-$version-macos.pkg" - name: Upload the package if: inputs.version != '' uses: actions/upload-artifact@v4 with: name: drosera-macos - path: Drosera-${{ inputs.version }}-macos.zip + path: Drosera-${{ inputs.version }}-macos.pkg if-no-files-found: error diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index dff3175..767b716 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -39,6 +39,7 @@ jobs: env: GH_TOKEN: ${{ github.token }} VERSION: ${{ needs.check.outputs.version }} + SIGNED: ${{ secrets.APPLE_ID != '' }} steps: - uses: actions/checkout@v4 - uses: actions/download-artifact@v4 @@ -47,8 +48,14 @@ jobs: - name: Create a draft release run: | python3 tools/release_check.py "$GITHUB_REF_NAME" > notes.md - sha256sum "Drosera-$VERSION-macos.zip" > SHA256SUMS.txt + if [ "$SIGNED" != true ]; then + printf '\n%s\n%s\n%s\n' \ + '**Opening the installer.** This release is not notarized by Apple yet, so macOS blocks the installer the' \ + 'first time. Open it, close the warning, then go to System Settings → Privacy & Security and click' \ + '**Open Anyway**. Nothing else needs unblocking.' >> notes.md + fi + sha256sum "Drosera-$VERSION-macos.pkg" > SHA256SUMS.txt prerelease="" case "$GITHUB_REF_NAME" in *-rc*) prerelease="--prerelease" ;; esac gh release create "$GITHUB_REF_NAME" --draft $prerelease --title "Drosera $VERSION" --notes-file notes.md \ - "Drosera-$VERSION-macos.zip" SHA256SUMS.txt + "Drosera-$VERSION-macos.pkg" SHA256SUMS.txt From 3c12152017f2683760772a24fa21f7aa7ce9528a Mon Sep 17 00:00:00 2001 From: Stefano Veloccia Date: Tue, 3 Nov 2026 19:31:44 +0100 Subject: [PATCH 07/10] Document installing with the package, and how to sign and notarize it Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 5 +++ README.md | 33 ++++++++++++++----- docs/INSTALL.txt | 25 -------------- docs/RELEASING.md | 33 +++++++++++++++---- ...026-11-01-repository-and-release-design.md | 3 ++ 5 files changed, 59 insertions(+), 40 deletions(-) delete mode 100644 docs/INSTALL.txt diff --git a/CHANGELOG.md b/CHANGELOG.md index f4becac..c46d695 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,9 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Ver ### Added +- An installer, `Drosera-X.Y.Z-macos.pkg`, in place of the zip. It installs the VST3, the Audio Unit and a + standalone app for all users, and each can be left out. +- The Audio Unit and the standalone app. The app asks for microphone access, to feed external sound into the loop. - Three-string polyphony: up to three notes at once as separate feedback loops, with Coupling between them. - POLY, LOCK, Coupling, Interval 2 and Interval 3. LOCK chooses between a tuned chord and the free drone. - Three presets: Open Fifths, Sympathetic and Chord Keys. @@ -15,6 +18,8 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Ver ### Changed +- The VST3 now installs to `/Library/Audio/Plug-Ins/VST3/`. If you copied 0.1.x to + `~/Library/Audio/Plug-Ins/VST3/`, delete that copy, or your host finds two. - A new window, on one page with no tabs: the plant in the centre with Frequency and Body beside it, one row of FILTER, REVERB, PONG and ECHO below, and a SETUP panel for Strings, Output and MIDI. Red marks the controls inside the feedback loop, amber those after it. diff --git a/README.md b/README.md index 6a077f5..5e1755f 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,8 @@ ![Drosera's window: a sundew whose tentacles show the sound's spectrum, Feedback at its heart, Frequency and Body beside it, and one row of filter, reverb and echo controls below](docs/images/drosera.png) -A feedback drone synth, as a VST3 plugin for macOS 11 or newer, on Apple silicon and Intel. +A feedback drone synth, as a VST3 and Audio Unit plugin and a standalone app for macOS 11 or newer, on Apple silicon +and Intel. Drosera makes sound on its own: a noise floor feeds two string resonators inside a saturating loop, and you steer what the loop settles on. Play it with its knobs, excite it with audio, or put it on a note with MIDI, up to three @@ -10,17 +11,31 @@ notes at once. It comes with 16 presets. ## Install -Download the zip from [Releases](https://github.com/codeskine/Drosera/releases), unpack it, and move `Drosera.vst3` to -`~/Library/Audio/Plug-Ins/VST3/`. Then rescan plugins in your host. Drosera loads as an instrument. +Download `Drosera-X.Y.Z-macos.pkg` from [Releases](https://github.com/codeskine/Drosera/releases) and open it. It +installs, for all users: -### If the plugin is blocked +- the VST3 in `/Library/Audio/Plug-Ins/VST3/` +- the Audio Unit in `/Library/Audio/Plug-Ins/Components/` +- the standalone app in `/Applications/` -Releases are not yet notarized by Apple, so macOS blocks files downloaded with a browser. After moving the plugin, -run this once in Terminal: +To leave out a format, click Customize in the installer. Then rescan plugins in your host. Drosera loads as an +instrument. -```bash -xattr -dr com.apple.quarantine ~/Library/Audio/Plug-Ins/VST3/Drosera.vst3 -``` +### If macOS blocks the installer + +Releases are not yet notarized by Apple, so macOS blocks the installer the first time. Close the warning, open +System Settings → Privacy & Security, scroll down and click **Open Anyway**, then confirm. Nothing else needs +unblocking: the installed plugins and app open normally. + +### Upgrading from 0.1.x + +Version 0.1.x was copied by hand to `~/Library/Audio/Plug-Ins/VST3/`. Delete `Drosera.vst3` there, or your host finds +two copies. + +### Uninstalling + +Delete `/Library/Audio/Plug-Ins/VST3/Drosera.vst3`, `/Library/Audio/Plug-Ins/Components/Drosera.component` and +`/Applications/Drosera.app`. ## Using it diff --git a/docs/INSTALL.txt b/docs/INSTALL.txt deleted file mode 100644 index d26b892..0000000 --- a/docs/INSTALL.txt +++ /dev/null @@ -1,25 +0,0 @@ -Drosera, a feedback drone synth - -INSTALL - -1. Move Drosera.vst3 to this folder in your home folder: - - Library/Audio/Plug-Ins/VST3/ - - Library is hidden in Finder. Use Go > Go to Folder and type ~/Library/Audio/Plug-Ins/VST3/ - -2. If your host reports the plugin as blocked or damaged, run this once in Terminal. Releases are not yet - notarized by Apple, so macOS blocks files downloaded with a browser. - - xattr -dr com.apple.quarantine ~/Library/Audio/Plug-Ins/VST3/Drosera.vst3 - -3. Rescan plugins in your host. Drosera loads as an instrument. - -Requires macOS 11 or newer. - -LICENSE - -Copyright 2026 codeskine. Drosera is free software under the GNU Affero General Public License, version 3: see LICENSE. The source for this -version is attached to its release at https://github.com/codeskine/Drosera/releases - -Third-party code keeps its own terms: see THIRD_PARTY_LICENSES.md and the licenses folder. diff --git a/docs/RELEASING.md b/docs/RELEASING.md index e773cd3..f6856fa 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -19,8 +19,8 @@ and publishes it. git tag vX.Y.Z && git push origin main vX.Y.Z ``` -5. Wait for the Release workflow. Download the zip from the draft, check it against `SHA256SUMS.txt`, install it by - following `INSTALL.txt`, and try it in a host. +5. Wait for the Release workflow. Download the `.pkg` from the draft, check it against `SHA256SUMS.txt`, install it, + and try it in a host. Before the first unsigned release and the first signed one, go through the checklist below. 6. Publish the draft. GitHub attaches the tagged source, which with JUCE pinned by CMake is the corresponding source AGPLv3 requires. @@ -35,13 +35,34 @@ gh release delete vX.Y.Z-rcN --cleanup-tag ## Notarization -Releases are signed ad hoc, and `INSTALL.txt` gives the unblocking command. To notarize, add these repository secrets: -`APPLE_CERTIFICATE` (a base64 `.p12`), `APPLE_CERTIFICATE_PASSWORD`, `APPLE_ID`, `APPLE_TEAM_ID`, `APPLE_APP_PASSWORD`. -The workflow then signs with Developer ID, notarizes and staples, with no other change. Then remove the unblocking -steps from `INSTALL.txt` and the README. +The release is `Drosera-X.Y.Z-macos.pkg`, built by `tools/package/build_pkg.sh` and checked by +`tools/package/check_pkg.sh`. Without the secrets below it is unsigned: macOS blocks it once, the release notes say how +to click Open Anyway, and nothing it installs is blocked afterwards. + +To sign and notarize, the owner needs a paid Apple Developer Program membership. Packages notarized while it is active +keep working after it lapses. + +1. In the developer account, under Certificates, create a **Developer ID Application** and a **Developer ID + Installer** certificate, and install both in the login keychain. +2. In Keychain Access, select both identities (certificate and private key), export them together as one `.p12` with a + password, and encode it: `base64 -i Drosera.p12 | pbcopy`. +3. Create an app-specific password for the Apple ID at account.apple.com. +4. Add these repository secrets: `APPLE_CERTIFICATE` (the base64 `.p12`), `APPLE_CERTIFICATE_PASSWORD`, `APPLE_ID`, + `APPLE_TEAM_ID`, `APPLE_APP_PASSWORD`. + +A versioned build then signs each bundle with the hardened runtime, signs the package, notarizes and staples it, and +`check_pkg.sh` requires all of that. If notarization fails, the log of Apple's verdict is in the job's output. Once a +signed release is out, remove the Open Anyway subsection from the README. **This path has never run**, because those secrets do not exist yet. Expect to debug it the first time. +### Checklist before the first unsigned release and the first signed one + +1. Install the package on a Mac that has never had Drosera, from a browser download. +2. Find Drosera as an Audio Unit in Logic and as a VST3 in another host, and play it. +3. Open the standalone app and confirm it asks for microphone access. +4. Uninstall by following the installer's last screen, and check the hosts no longer list Drosera. + ## What is not covered - The x86_64 part of the universal binary is built, but no CI job runs it. diff --git a/docs/superpowers/specs/2026-11-01-repository-and-release-design.md b/docs/superpowers/specs/2026-11-01-repository-and-release-design.md index 8168390..2592429 100644 --- a/docs/superpowers/specs/2026-11-01-repository-and-release-design.md +++ b/docs/superpowers/specs/2026-11-01-repository-and-release-design.md @@ -1,5 +1,8 @@ # Repository and release design +> The release zip and the non-goals on installers and on AU and Standalone releases are replaced by +> `2026-11-03-macos-installer-design.md`. + Sub-project 1 of 2. The new interface is specified in `2026-11-01-rugiada-interface-design.md` and is built on top of this work. From 9a3df2171b45d7503d92a4b7ad3c1fc1eaa5007c Mon Sep 17 00:00:00 2001 From: Stefano Veloccia Date: Tue, 3 Nov 2026 19:38:14 +0100 Subject: [PATCH 08/10] Sign whenever any signing secret exists, and refuse an unsigned package then Signing hung on APPLE_ID alone, so a release with the other secrets but no APPLE_ID came out unsigned with a green run. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 4 +++- .github/workflows/release.yml | 2 +- tools/package/check_pkg.sh | 5 ++++- tools/package/test_package.sh | 11 +++++++++++ 4 files changed, 19 insertions(+), 3 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9e56ddc..3ab996d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -22,7 +22,8 @@ jobs: env: PLUGINVAL_VERSION: v1.0.4 VST3: build/Drosera_artefacts/Release/VST3/Drosera.vst3 - CAN_NOTARIZE: ${{ secrets.APPLE_ID != '' }} + # Any signing secret means signing is wanted: build_pkg.sh then fails unless all are there. + CAN_NOTARIZE: ${{ secrets.APPLE_CERTIFICATE != '' || secrets.APPLE_CERTIFICATE_PASSWORD != '' || secrets.APPLE_ID != '' || secrets.APPLE_TEAM_ID != '' || secrets.APPLE_APP_PASSWORD != '' }} steps: - uses: actions/checkout@v4 @@ -108,6 +109,7 @@ jobs: DEVELOPER_ID_APPLICATION=$(sed -nE 's/.*"(Developer ID Application: [^"]*)".*/\1/p' <<< "$identities" | head -1) DEVELOPER_ID_INSTALLER=$(sed -nE 's/.*"(Developer ID Installer: [^"]*)".*/\1/p' <<< "$identities" | head -1) export DEVELOPER_ID_APPLICATION DEVELOPER_ID_INSTALLER + export REQUIRE_SIGNED=1 else unset APPLE_ID APPLE_TEAM_ID APPLE_APP_PASSWORD fi diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 767b716..560e3f5 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -39,7 +39,7 @@ jobs: env: GH_TOKEN: ${{ github.token }} VERSION: ${{ needs.check.outputs.version }} - SIGNED: ${{ secrets.APPLE_ID != '' }} + SIGNED: ${{ secrets.APPLE_CERTIFICATE != '' || secrets.APPLE_CERTIFICATE_PASSWORD != '' || secrets.APPLE_ID != '' || secrets.APPLE_TEAM_ID != '' || secrets.APPLE_APP_PASSWORD != '' }} steps: - uses: actions/checkout@v4 - uses: actions/download-artifact@v4 diff --git a/tools/package/check_pkg.sh b/tools/package/check_pkg.sh index 9b68665..69364d3 100755 --- a/tools/package/check_pkg.sh +++ b/tools/package/check_pkg.sh @@ -67,8 +67,11 @@ if [ -n "$vst3" ]; then fi # A signed package must be signed for installation, notarized and stapled, with every bundle on the hardened runtime. +# REQUIRE_SIGNED=1, set by CI whenever signing secrets exist, refuses an unsigned package. signature=$(pkgutil --check-signature "$package" 2>&1 || true) -if [[ "$signature" != *"no signature"* ]]; then +if [[ "$signature" == *"no signature"* ]]; then + [ "${REQUIRE_SIGNED:-0}" = 1 ] && fail "the package is not signed, and REQUIRE_SIGNED=1" +else [[ "$signature" == *"Developer ID Installer"* ]] || fail "the package is not signed with Developer ID Installer" spctl --assess --type install -vv "$package" 2>&1 | grep -q 'source=Notarized Developer ID' \ || fail "spctl does not accept the package as notarized" diff --git a/tools/package/test_package.sh b/tools/package/test_package.sh index 0c06a74..b681959 100755 --- a/tools/package/test_package.sh +++ b/tools/package/test_package.sh @@ -127,6 +127,17 @@ else fail unsigned_package_has_no_signature "the unsigned package carries a signature, or check_pkg.sh rejects it" fi +# require_signed_rejects_unsigned +if [ ! -f "$good" ]; then + fail require_signed_rejects_unsigned "no good package to check" +elif REQUIRE_SIGNED=1 "$check" "$good" > /dev/null 2> "$tmp/require.err"; then + fail require_signed_rejects_unsigned "check_pkg.sh accepted an unsigned package with REQUIRE_SIGNED=1" +elif ! grep -q 'not signed' "$tmp/require.err"; then + fail require_signed_rejects_unsigned "the error does not say not signed: $(cat "$tmp/require.err")" +else + pass require_signed_rejects_unsigned +fi + # missing_au mkdir -p "$tmp/no-au" ditto "$artefacts/VST3" "$tmp/no-au/VST3" From 7a1e3607580488c063e8d9f97022b79fd6049581 Mon Sep 17 00:00:00 2001 From: Stefano Veloccia Date: Tue, 3 Nov 2026 20:22:38 +0100 Subject: [PATCH 09/10] Rewrite the install, release and build documentation for the installer The README walks through Open Anyway step by step and says where the standalone app keeps its settings. The manual describes the standalone app. RELEASING.md explains what the workflow does, how to set up signing, and what to do when it fails. BUILDING.md documents the package scripts. Co-Authored-By: Claude Opus 5.5 --- CONTRIBUTING.md | 3 +- README.md | 59 ++++++++--- docs/BUILDING.md | 57 +++++++++- docs/MANUAL.md | 21 +++- docs/RELEASING.md | 135 ++++++++++++++++++------ tools/package/resources/conclusion.html | 1 + 6 files changed, 225 insertions(+), 51 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fbd11b9..c7b3c77 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,8 @@ Contributions are welcome, and are accepted under the project's license, AGPLv3. -See [docs/BUILDING.md](docs/BUILDING.md) for how to build and test. CI must pass. +See [docs/BUILDING.md](docs/BUILDING.md) for how to build and test. CI must pass. If you change `tools/package/` or +the workflows, also run `tools/package/test_package.sh build/Drosera_artefacts/Release`. ## Rules diff --git a/README.md b/README.md index 5e1755f..166f17d 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,8 @@ ![Drosera's window: a sundew whose tentacles show the sound's spectrum, Feedback at its heart, Frequency and Body beside it, and one row of filter, reverb and echo controls below](docs/images/drosera.png) -A feedback drone synth, as a VST3 and Audio Unit plugin and a standalone app for macOS 11 or newer, on Apple silicon -and Intel. +A feedback drone synth for macOS 11 or newer, on Apple silicon and Intel. It comes as a VST3 plugin, an Audio Unit and a +standalone app. Drosera makes sound on its own: a noise floor feeds two string resonators inside a saturating loop, and you steer what the loop settles on. Play it with its knobs, excite it with audio, or put it on a note with MIDI, up to three @@ -11,31 +11,50 @@ notes at once. It comes with 16 presets. ## Install -Download `Drosera-X.Y.Z-macos.pkg` from [Releases](https://github.com/codeskine/Drosera/releases) and open it. It -installs, for all users: +1. Download `Drosera-X.Y.Z-macos.pkg` from [Releases](https://github.com/codeskine/Drosera/releases). +2. Open it and follow the installer. It asks for an administrator password, because it installs for every user on + the Mac: -- the VST3 in `/Library/Audio/Plug-Ins/VST3/` -- the Audio Unit in `/Library/Audio/Plug-Ins/Components/` -- the standalone app in `/Applications/` + | Format | Installed to | + |---|---| + | VST3 | `/Library/Audio/Plug-Ins/VST3/Drosera.vst3` | + | Audio Unit | `/Library/Audio/Plug-Ins/Components/Drosera.component` | + | Standalone app | `/Applications/Drosera.app` | -To leave out a format, click Customize in the installer. Then rescan plugins in your host. Drosera loads as an -instrument. + All three are selected. To leave one out, click **Customize** at the Installation Type step. +3. Rescan plugins in your host. Drosera loads as an instrument. ### If macOS blocks the installer -Releases are not yet notarized by Apple, so macOS blocks the installer the first time. Close the warning, open -System Settings → Privacy & Security, scroll down and click **Open Anyway**, then confirm. Nothing else needs -unblocking: the installed plugins and app open normally. +Releases are not notarized by Apple yet, so the first time you open the installer macOS says it could not verify that +the installer is free of malware, and does not open it. Then: + +1. Click **Done** in that warning. Do not move the file to the Bin. +2. Open **System Settings → Privacy & Security** and scroll down to Security. A line says the installer was blocked. + Click **Open Anyway** and confirm with your password or Touch ID. +3. The installer opens. Install as above. + +You do this once per downloaded installer. The plugins and the app it installs open normally, with no Terminal +command. ### Upgrading from 0.1.x -Version 0.1.x was copied by hand to `~/Library/Audio/Plug-Ins/VST3/`. Delete `Drosera.vst3` there, or your host finds -two copies. +Version 0.1.x came as a zip, and its VST3 was copied by hand to `~/Library/Audio/Plug-Ins/VST3/`, in your home +folder. Delete `Drosera.vst3` there, or your host finds two copies of Drosera. `~/Library` is hidden in Finder: use +**Go → Go to Folder** and type the path. + +Later versions install over the earlier one. Open the new installer and nothing else is needed. ### Uninstalling -Delete `/Library/Audio/Plug-Ins/VST3/Drosera.vst3`, `/Library/Audio/Plug-Ins/Components/Drosera.component` and -`/Applications/Drosera.app`. +Delete these three items, and empty the Bin: + +- `/Library/Audio/Plug-Ins/VST3/Drosera.vst3` +- `/Library/Audio/Plug-Ins/Components/Drosera.component` +- `/Applications/Drosera.app` + +The standalone app also keeps its audio settings in `~/Library/Application Support/Drosera.settings`. Delete it too to +leave nothing behind. Projects saved in your host keep their own copy of Drosera's settings. ## Using it @@ -45,11 +64,17 @@ Body beside it. Below, one row holds the filters, the reverb and the echo, with inside the feedback loop and change what the drone sustains; amber ones come after it and colour what comes out. Strings, Output and MIDI open from the SETUP field. Drag the window's corner to scale it from 75 % to 150 %. +The standalone app plays Drosera without a host. Its **Options** button, top left, opens the audio and MIDI settings, +where you choose the output, an audio input and MIDI devices. The audio input starts muted, to avoid a loop from the +speakers to the microphone: untick **Mute audio input** there to use it. The first time the app opens, macOS asks +whether it may use the microphone. + See the [manual](docs/MANUAL.md) for every control, MIDI, and the known limits. ## Status -Validated by automated tests and `pluginval` on macOS. Not yet compared with a hardware unit. +Validated on macOS by automated tests, by `pluginval` on the VST3 and the Audio Unit, and by Apple's `auval` on the Audio +Unit. Not yet compared with a hardware unit. Releases are not yet signed and notarized by Apple. ## For developers diff --git a/docs/BUILDING.md b/docs/BUILDING.md index 1e3a80f..89a7266 100644 --- a/docs/BUILDING.md +++ b/docs/BUILDING.md @@ -19,7 +19,9 @@ cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release cmake --build build ``` -The plugins land in `build/Drosera_artefacts/Release/`. They are not copied to the system plugin folders. +The VST3, the Audio Unit and the standalone app land in `build/Drosera_artefacts/Release/`, in `VST3/`, `AU/` and +`Standalone/`. They are not copied to the system plugin folders. Each is signed ad hoc once complete, so macOS loads it on +this Mac. To build a universal macOS binary, add `-DCMAKE_OSX_ARCHITECTURES="arm64;x86_64"` when configuring. To build only the DSP and its tests, with no download, add `-DDROSERA_BUILD_PLUGIN=OFF`. @@ -64,6 +66,59 @@ tools/hardware-comparison/check_reference.sh build/render_cli On arm64 only. Renders 10 presets and compares them with `tools/hardware-comparison/reference/SHA256SUMS`, which proves the engine still renders exactly the same. +## Package + +The release is an installer package, built from the three bundles: + +```bash +tools/package/build_pkg.sh build/Drosera_artefacts/Release 0.0.0 build/Drosera.pkg +``` + +```bash +tools/package/check_pkg.sh build/Drosera.pkg +``` + +`build_pkg.sh ` makes one component package per format and combines them under +`tools/package/resources/distribution.xml`, with the installer's screens from the same folder. The Read Me screen is +generated from the licence files, so it always holds their current text. + +`check_pkg.sh` expands a package without installing it. It checks: + +- the three components, with their identifiers and install paths; +- that no bundle can be relocated; +- the minimum macOS version and the architectures the installer declares (the text, not the binaries); +- each bundle's code signature; +- that the packaged VST3 loads and renders in `plugin_host_test`, which must be built. + +If the package is signed, it also checks the Installer signature, the notarization, the stapled ticket and the +hardened runtime. With `REQUIRE_SIGNED=1` it refuses an unsigned package. + +```bash +tools/package/test_package.sh build/Drosera_artefacts/Release +``` + +Proves the two scripts: it builds good and deliberately broken packages, and checks that each is accepted or refused +as it should be. + +A package built from a plain local build holds only this Mac's architecture. Release packages come from CI, which builds +universal. + +After a change to the plugin's options in `CMakeLists.txt`, reconfigure and rebuild with `--clean-first`. CMake rewrites +the bundles' `Info.plist` when it configures, and an incremental build does not sign them again, so `check_pkg.sh` +then rejects their signatures. + +`build_pkg.sh` signs and notarizes when all five of these are set, and refuses to run with only some of them: + +| Variable | Holds | +|---|---| +| `DEVELOPER_ID_APPLICATION` | The full name of the Developer ID Application identity, such as `Developer ID Application: Name (TEAMID)` | +| `DEVELOPER_ID_INSTALLER` | The full name of the Developer ID Installer identity | +| `APPLE_ID` | The Apple ID used for notarization | +| `APPLE_TEAM_ID` | The team's ID | +| `APPLE_APP_PASSWORD` | An app-specific password for that Apple ID | + +See [RELEASING.md](RELEASING.md#signing-and-notarization) for getting them. + ## Other tools - `build/pitch_probe [body] [first] [last] [step]` prints the pitch measured for a range of MIDI notes. diff --git a/docs/MANUAL.md b/docs/MANUAL.md index ee4ed02..6609ec5 100644 --- a/docs/MANUAL.md +++ b/docs/MANUAL.md @@ -108,8 +108,8 @@ where Echo Feedback runs away. At 0 %, Width plays each repeat in the middle at The output has a limiter and a final hard clip at full scale, because the loop can get loud. -The audio input is optional, and excites the strings. It stays off until the host connects the plugin's input -bus. Some presets need it to make sound. +The audio input is optional, and excites the strings. In a host, it stays off until the host connects the plugin's +input bus. In the standalone app, it starts muted: see below. Some presets need it to make sound. ## SETUP: MIDI @@ -171,6 +171,23 @@ so one note sounds one string. **MIDI Gate per voice.** With MIDI Pitch on, each voice is open only while its own note is held. With MIDI Gate off, a released note keeps sounding until its voice is taken. With MIDI Pitch off, the gate opens all three voices together. +## The standalone app + +`/Applications/Drosera.app` plays Drosera without a host. The window is the same, with an **Options** button in its +title bar: + +- **Audio/MIDI Settings…** chooses the output device, the input device and its channels, the sample rate and buffer + size, and the MIDI inputs to listen to. +- **Save current state…** and **Load a saved state…** keep the settings of every control in a file of your own. +- **Reset to default state** returns every control to its default. + +The audio input starts muted, so that a microphone near the speakers does not feed the output back into Drosera. A +banner says so. To use the input, untick **Mute audio input**, next to Feedback Loop in the settings. The first time the +app opens, macOS asks whether it may use the microphone. If you refused, allow it again in System Settings → Privacy & +Security → Microphone. + +The app keeps its devices and the last state in `~/Library/Application Support/Drosera.settings`. + ## Presets 16 factory presets, also exposed to the host as programs. "Resonator" needs an audio input. "Keys" expects notes. diff --git a/docs/RELEASING.md b/docs/RELEASING.md index f6856fa..35ff3cc 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -1,7 +1,7 @@ # Releasing Drosera -Pushing a tag builds, tests and packages Drosera, then creates a **draft** GitHub Release. A person reviews the draft -and publishes it. +Pushing a tag builds and tests Drosera, builds the installer `Drosera-X.Y.Z-macos.pkg`, and creates a **draft** GitHub +Release with it. A person reviews the draft and publishes it. ## Steps @@ -19,54 +19,129 @@ and publishes it. git tag vX.Y.Z && git push origin main vX.Y.Z ``` -5. Wait for the Release workflow. Download the `.pkg` from the draft, check it against `SHA256SUMS.txt`, install it, - and try it in a host. Before the first unsigned release and the first signed one, go through the checklist below. -6. Publish the draft. GitHub attaches the tagged source, which with JUCE pinned by CMake is the corresponding source +5. Wait for the Release workflow. Download `Drosera-X.Y.Z-macos.pkg` and `SHA256SUMS.txt` from the draft with a + browser, and check them in the folder you downloaded them to: + + ```bash + shasum -a 256 -c SHA256SUMS.txt + ``` + +6. Install the package and play Drosera in a host. Before the first unsigned release and before the first signed one, + go through the [checklist](#checklist-on-a-clean-mac) instead. +7. Publish the draft. GitHub attaches the tagged source, which with JUCE pinned by CMake is the corresponding source AGPLv3 requires. +## What the workflow does + +`release.yml` checks the tag, then runs `ci.yml` with the version. On a macOS runner, `ci.yml`: + +1. Builds universal (arm64 and x86_64) and runs every test, `pluginval` on the VST3 and the AU, `auval`, and the + reference renders. +2. Runs `tools/package/test_package.sh`, which proves the package checks still catch broken packages. +3. Builds `Drosera-X.Y.Z-macos.pkg` with `tools/package/build_pkg.sh`, signed if the signing secrets exist, and checks + it with `tools/package/check_pkg.sh`. That check expands the package without installing it and loads the packaged + VST3. +4. Uploads the package as the `drosera-macos` artefact. + +`release.yml` then attaches the package and `SHA256SUMS.txt` to the draft. The draft's notes are the changelog section. +While releases are unsigned, they end with a paragraph on opening the installer with Open Anyway. + +Every push to any branch runs the same build, tests and package check, unsigned and without uploading anything. + ## Trying the pipeline -A tag `vX.Y.Z-rcN` runs the same pipeline without touching the changelog. Its notes come from `Unreleased`, and the draft -is marked as a pre-release. Delete it afterwards: +A tag `vX.Y.Z-rcN` runs the same pipeline without touching the changelog. Its notes come from `Unreleased`, the draft is +marked as a pre-release, and its package is `Drosera-X.Y.Z-rcN-macos.pkg`. Delete it afterwards: ```bash gh release delete vX.Y.Z-rcN --cleanup-tag ``` -## Notarization +## Signing and notarization + +Releases are unsigned for now. macOS blocks the installer once; the user clicks Open Anyway in System Settings, as the +README and the release notes explain, and nothing the installer puts on the Mac is blocked afterwards. This was checked +on macOS 27.2 on 2026-11-03. + +A signed and notarized installer opens with no warning. That needs a paid Apple Developer Program membership. +Software notarized while the membership is active keeps working after it lapses, so it only needs paying in the years +with a release. + +### Setting it up + +1. Join the Apple Developer Program. Only the account holder can create Developer ID certificates. +2. In the developer account, under Certificates, IDs & Profiles, create a **Developer ID Application** certificate + and a **Developer ID Installer** certificate, and install both in the login keychain of a Mac. +3. In Keychain Access, under My Certificates, select both certificates. Each must show its private key beneath it. + Choose File → Export Items and save them as one `.p12` file with a password. +4. Encode it for GitHub: + + ```bash + base64 -i Drosera.p12 | pbcopy + ``` + +5. At [account.apple.com](https://account.apple.com), under Sign-In and Security, create an app-specific password for + notarization. +6. In the repository's settings, under Secrets and variables → Actions, add these five secrets: + + | Secret | Value | + |---|---| + | `APPLE_CERTIFICATE` | The base64 text of the `.p12` | + | `APPLE_CERTIFICATE_PASSWORD` | The `.p12` file's password | + | `APPLE_ID` | The Apple ID's email address | + | `APPLE_TEAM_ID` | The Team ID, shown under Membership details in the developer account | + | `APPLE_APP_PASSWORD` | The app-specific password | + +7. Push a tag `vX.Y.Z-rc1`, follow the run to the end, and go through the [checklist](#checklist-on-a-clean-mac). +8. Once a signed release is published, remove "If macOS blocks the installer" from the README. + +### What a signed build does + +Only a build with a version signs, that is a tag push. It imports the `.p12` into a temporary keychain, reads the two +Developer ID identities from it, and passes them to `build_pkg.sh`, which: + +1. Signs each bundle with the hardened runtime and a secure timestamp. The standalone app also gets the entitlement for + audio input, in `tools/package/resources/Drosera.entitlements`. +2. Builds the package and signs it with the Developer ID Installer identity. +3. Sends it to Apple's notary service and waits for the verdict. +4. Staples the ticket to the package, so Gatekeeper accepts it offline. + +`check_pkg.sh` then requires the Developer ID Installer signature, Gatekeeper's acceptance of the package as notarized, +the stapled ticket, and the hardened runtime on each bundle. -The release is `Drosera-X.Y.Z-macos.pkg`, built by `tools/package/build_pkg.sh` and checked by -`tools/package/check_pkg.sh`. Without the secrets below it is unsigned: macOS blocks it once, the release notes say how -to click Open Anyway, and nothing it installs is blocked afterwards. +As soon as any of the five secrets exists, CI expects a signed package. If a secret is missing or a step fails, the +build fails. It never falls back to an unsigned package. -To sign and notarize, the owner needs a paid Apple Developer Program membership. Packages notarized while it is active -keep working after it lapses. +### When it fails -1. In the developer account, under Certificates, create a **Developer ID Application** and a **Developer ID - Installer** certificate, and install both in the login keychain. -2. In Keychain Access, select both identities (certificate and private key), export them together as one `.p12` with a - password, and encode it: `base64 -i Drosera.p12 | pbcopy`. -3. Create an app-specific password for the Apple ID at account.apple.com. -4. Add these repository secrets: `APPLE_CERTIFICATE` (the base64 `.p12`), `APPLE_CERTIFICATE_PASSWORD`, `APPLE_ID`, - `APPLE_TEAM_ID`, `APPLE_APP_PASSWORD`. +**This path has never run**, because the secrets do not exist yet. Expect to debug it the first time. -A versioned build then signs each bundle with the hardened runtime, signs the package, notarizes and staples it, and -`check_pkg.sh` requires all of that. If notarization fails, the log of Apple's verdict is in the job's output. Once a -signed release is out, remove the Open Anyway subsection from the README. +- **`signing needs all of …`:** a secret is missing, or the keychain did not yield both identities. A `.p12` exported + with only one certificate, or without the private keys, does this. +- **Notarization rejected:** the job prints Apple's log for the submission. It names each file and the reason, such as + a binary without the hardened runtime or without a timestamp. +- **`spctl does not accept the package as notarized`:** if Gatekeeper assessments are disabled on the runner, `spctl` + cannot report a notarized source even for a good package. `pkgutil --check-signature` reports notarization on its own + ("Notarization: trusted by the Apple notary service"), and `check_pkg.sh` can switch to it. -**This path has never run**, because those secrets do not exist yet. Expect to debug it the first time. +To sign on a Mac with the certificates installed, set the five variables `build_pkg.sh` reads, listed in the +[build guide](BUILDING.md#package). -### Checklist before the first unsigned release and the first signed one +## Checklist on a clean Mac -1. Install the package on a Mac that has never had Drosera, from a browser download. -2. Find Drosera as an Audio Unit in Logic and as a VST3 in another host, and play it. -3. Open the standalone app and confirm it asks for microphone access. -4. Uninstall by following the installer's last screen, and check the hosts no longer list Drosera. +1. On a Mac, or a user account, that has never had Drosera, download the package from the draft with a browser. +2. Open it. Unsigned, macOS must block it once and open it with Open Anyway. Signed, it must open with no warning. +3. Check that Customize lists VST3, Audio Unit and Standalone, all selected, and read the three screens. +4. Install. Find Drosera as an Audio Unit in Logic and as a VST3 in another host, and play it. +5. Open the standalone app. macOS must ask for microphone access. In Options → Audio/MIDI Settings, untick Mute audio + input and check that an input excites the strings. +6. Uninstall by following the installer's last screen, and check that the hosts no longer list Drosera. ## What is not covered - The x86_64 part of the universal binary is built, but no CI job runs it. -- CI proves the plugin loads and passes `pluginval`. Only a person can try it in a DAW and listen to it. +- CI proves the plugins load and pass `pluginval` and `auval`. Only a person can play them in a DAW and listen. +- The signed path has never run. ## Checks before the first release diff --git a/tools/package/resources/conclusion.html b/tools/package/resources/conclusion.html index 7a05076..ba2befe 100644 --- a/tools/package/resources/conclusion.html +++ b/tools/package/resources/conclusion.html @@ -13,4 +13,5 @@

Uninstalling

  • /Library/Audio/Plug-Ins/Components/Drosera.component
  • /Applications/Drosera.app
  • +

    The standalone app also keeps its settings in ~/Library/Application Support/Drosera.settings.

    From 1f57ae3502ef34637b5a3008be779897498c93ae Mon Sep 17 00:00:00 2001 From: Stefano Veloccia Date: Tue, 3 Nov 2026 20:24:30 +0100 Subject: [PATCH 10/10] Restructure the README: badges, requirements, quickstart, project structure, contributing Co-Authored-By: Claude Opus 5.5 --- README.md | 137 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 105 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 166f17d..30d16c3 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,27 @@ # Drosera +[![CI](https://github.com/codeskine/Drosera/actions/workflows/ci.yml/badge.svg)](https://github.com/codeskine/Drosera/actions/workflows/ci.yml) +[![License: AGPL v3](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE) + ![Drosera's window: a sundew whose tentacles show the sound's spectrum, Feedback at its heart, Frequency and Body beside it, and one row of filter, reverb and echo controls below](docs/images/drosera.png) -A feedback drone synth for macOS 11 or newer, on Apple silicon and Intel. It comes as a VST3 plugin, an Audio Unit and a -standalone app. +A feedback drone synth for macOS, as a VST3, an Audio Unit and a standalone app. A noise floor feeds two string +resonators inside a saturating loop, so it sounds on its own: you steer what the loop settles on with its knobs, with +audio, or with MIDI, up to three notes at once. + +## Requirements -Drosera makes sound on its own: a noise floor feeds two string resonators inside a saturating loop, and you steer -what the loop settles on. Play it with its knobs, excite it with audio, or put it on a note with MIDI, up to three -notes at once. It comes with 16 presets. +- macOS 11 or newer, on Apple silicon or Intel +- An administrator password, to install +- A host that loads VST3 or Audio Unit instruments, such as Logic Pro, Ableton Live or Reaper. The standalone app needs + none. -## Install +To build from source: the Xcode command line tools, CMake 3.22 or newer, and Ninja. See [Building](#building-from-source). + +## Installation 1. Download `Drosera-X.Y.Z-macos.pkg` from [Releases](https://github.com/codeskine/Drosera/releases). -2. Open it and follow the installer. It asks for an administrator password, because it installs for every user on - the Mac: +2. Open it and follow the installer. It installs for every user on the Mac: | Format | Installed to | |---|---| @@ -56,40 +64,105 @@ Delete these three items, and empty the Bin: The standalone app also keeps its audio settings in `~/Library/Application Support/Drosera.settings`. Delete it too to leave nothing behind. Projects saved in your host keep their own copy of Drosera's settings. -## Using it - -Everything is on one page. In the middle, a sundew shows the sound's real spectrum: each tentacle is a frequency band, -from the lowest at the top, clockwise, and it unfurls as its band sounds. Feedback sits at its heart, with Frequency and -Body beside it. Below, one row holds the filters, the reverb and the echo, with its PONG controls. Red controls are -inside the feedback loop and change what the drone sustains; amber ones come after it and colour what comes out. -Strings, Output and MIDI open from the SETUP field. Drag the window's corner to scale it from 75 % to 150 %. - -The standalone app plays Drosera without a host. Its **Options** button, top left, opens the audio and MIDI settings, -where you choose the output, an audio input and MIDI devices. The audio input starts muted, to avoid a loop from the -speakers to the microphone: untick **Mute audio input** there to use it. The first time the app opens, macOS asks -whether it may use the microphone. - -See the [manual](docs/MANUAL.md) for every control, MIDI, and the known limits. +## Quickstart + +Once installed, this takes about two minutes. **Turn your speakers or headphones down first:** Drosera starts sounding +as soon as it loads, and the drone can swell. + +### In the standalone app + +1. Open **Drosera** from Applications. macOS asks whether it may use the microphone: either answer works for this + quickstart. +2. Click **Options** at the top left, choose **Audio/MIDI Settings…**, and pick your speakers or headphones as the + output. Close the window. +3. On first launch the "Default" preset is loaded and already droning. Turn **Frequency**, left of the plant, slowly: the drone moves to another + pitch, and the plant's tentacles unfurl where the sound is. +4. Turn **Feedback**, in the plant's heart, down and back up. Low, the loop dies away; high, it sustains and + saturates. +5. Open the preset selector at the top left and choose **Cathedral Bloom**, then **Ember Pong**, whose echo bounces + between left and right. + +### In a host + +1. In Logic Pro, create a Software Instrument track and, in its instrument slot, choose **AU Instruments → codeskine → + Drosera**. In another host, load **Drosera** as a VST3 instrument on a new track. +2. Select or arm the track. Drosera drones with no notes played. +3. Follow steps 3 to 5 above. +4. To play it from a keyboard, choose the **Keys (play notes)** preset. It turns MIDI Pitch and MIDI Gate on, in + **SETUP** at the top right, so Drosera is silent until you hold a key, and then sounds that note. + +The [manual](docs/MANUAL.md) explains every control, MIDI, the standalone app, and the known limits. + +## Project structure + +```text +. +├── src/ +│ ├── dsp/ # The engine, with no JUCE: the Audrey II firmware's loop and the plugin-only features +│ │ # DroseraCore.h is its host-independent front end, fixed at 48 kHz +│ └── plugin/ # The JUCE plugin +│ ├── PluginProcessor.cpp # Parameters, MIDI, resampling to and from 48 kHz +│ ├── PluginEditor.* # The window: assembles the interface and runs its timer +│ ├── Presets.h # The 16 factory presets +│ └── ui/ # Theme, fonts, knobs, the plant, header, control row, setup panel +├── tests/ # render_test, voice_allocator_test, ui_test, plugin_host_test, and their fixtures +├── assets/fonts/ # The interface's fonts, embedded in the plugin, with their licences +├── third_party/DaisySP/ # Vendored DSP library; local changes are listed in its PATCHES.txt +├── tools/ +│ ├── package/ # Builds and checks the installer, and holds its screens +│ ├── hardware-comparison/ # Comparison with a real unit, and the reference render checksums +│ └── release_check.py # Checks a release tag against the version and the changelog +├── docs/ # Manual, build and release guides, images +│ └── superpowers/ # Design specs and implementation plans +├── review/ # Code review notes and sound design measurements +├── .github/workflows/ # CI on every push, and the release pipeline +└── CMakeLists.txt # The build; downloads JUCE 8.0.9 on first configure +``` + +## Building from source + +```bash +cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release +``` + +```bash +cmake --build build +``` + +The first configure downloads JUCE, so it takes a few minutes. The VST3, the Audio Unit and the standalone app land in +`build/Drosera_artefacts/Release/`. [docs/BUILDING.md](docs/BUILDING.md) covers the tests, the installer package and +the other tools. + +## Contributing + +Contributions are welcome, under the project's licence, AGPLv3. + +1. Fork [codeskine/Drosera](https://github.com/codeskine/Drosera) on GitHub and clone your fork. +2. Create a branch from `main` named for the change: + + ```bash + git switch -c my-change + ``` + +3. Make the change, and build and run the tests as [docs/BUILDING.md](docs/BUILDING.md) describes. +4. Add user-visible changes to the `Unreleased` section of [CHANGELOG.md](CHANGELOG.md). +5. Push the branch to your fork and open a pull request against `main`. CI must pass. + +Read [CONTRIBUTING.md](CONTRIBUTING.md) first. Its rules protect the audio thread, the reference renders and saved +projects. [docs/RELEASING.md](docs/RELEASING.md) describes how releases are made. ## Status Validated on macOS by automated tests, by `pluginval` on the VST3 and the Audio Unit, and by Apple's `auval` on the Audio Unit. Not yet compared with a hardware unit. Releases are not yet signed and notarized by Apple. -## For developers - -- [Building and testing](docs/BUILDING.md) -- [Contributing](CONTRIBUTING.md) -- [Releasing](docs/RELEASING.md) -- [Changelog](CHANGELOG.md) - ## Credits Derived from the MIT-licensed firmware of [Audrey II](https://github.com/Synthux-Academy/Audrey-II), by Nick Donaldson (Synthux Academy), for Daisy Seed. Drosera is an independent project, not affiliated with or endorsed by Synthux Academy, and uses none of their artwork. -## License +## Licence -Copyright 2026 codeskine. AGPLv3, see [LICENSE](LICENSE). Third-party code keeps its own terms: see -[THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md). +Copyright 2026 codeskine. Drosera is free software under the GNU Affero General Public License, version 3: see +[LICENSE](LICENSE). Third-party code and fonts keep their own terms: see [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md).