diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 287577d..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 @@ -42,7 +43,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 +78,49 @@ 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 + export REQUIRE_SIGNED=1 + 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..560e3f5 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_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 @@ -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 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/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/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/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 6a077f5..30d16c3 100644 --- a/README.md +++ b/README.md @@ -1,47 +1,160 @@ # 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, as a VST3 plugin for macOS 11 or newer, on Apple silicon and Intel. +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 + +- 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. + +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 installs for every user on the Mac: + + | 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` | + + 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 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 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 -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. +Delete these three items, and empty the Bin: -## Install +- `/Library/Audio/Plug-Ins/VST3/Drosera.vst3` +- `/Library/Audio/Plug-Ins/Components/Drosera.component` +- `/Applications/Drosera.app` -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. +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. -### If the plugin is blocked +## Quickstart -Releases are not yet notarized by Apple, so macOS blocks files downloaded with a browser. After moving the plugin, -run this once in Terminal: +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 -xattr -dr com.apple.quarantine ~/Library/Audio/Plug-Ins/VST3/Drosera.vst3 +cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release ``` -## Using it +```bash +cmake --build build +``` -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 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. -See the [manual](docs/MANUAL.md) for every control, MIDI, and the known limits. +## Contributing -## Status +Contributions are welcome, under the project's licence, AGPLv3. -Validated by automated tests and `pluginval` on macOS. Not yet compared with a hardware unit. +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: -## For developers + ```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 -- [Building and testing](docs/BUILDING.md) -- [Contributing](CONTRIBUTING.md) -- [Releasing](docs/RELEASING.md) -- [Changelog](CHANGELOG.md) +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. ## Credits @@ -49,7 +162,7 @@ Derived from the MIT-licensed firmware of [Audrey II](https://github.com/Synthux (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). 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/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/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 e773cd3..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,33 +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 zip from the draft, check it against `SHA256SUMS.txt`, install it by - following `INSTALL.txt`, and try it in a host. -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. + +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. + +### When it fails + +**This path has never run**, because the secrets do not exist yet. Expect to debug it the first time. + +- **`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. + +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). -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. +## Checklist on a clean Mac -**This path has never run**, because those secrets do not exist yet. Expect to debug it the first time. +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/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.
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.
 
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.
diff --git a/tools/package/build_pkg.sh b/tools/package/build_pkg.sh
new file mode 100755
index 0000000..05935c1
--- /dev/null
+++ b/tools/package/build_pkg.sh
@@ -0,0 +1,118 @@
+#!/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
+
+# 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"
+    "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
+
+# 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
+    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")" +product_signing=() +[ "$signing" = 1 ] && product_signing=(--sign "$DEVELOPER_ID_INSTALLER" --timestamp) +productbuild --quiet --distribution "$work/distribution.xml" --resources "$work/screens" \ + --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 new file mode 100755 index 0000000..69364d3 --- /dev/null +++ b/tools/package/check_pkg.sh @@ -0,0 +1,88 @@ +#!/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 + +# 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 + [ "${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" + 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 +echo "check_pkg: $package is fine" 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/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..ba2befe --- /dev/null +++ b/tools/package/resources/conclusion.html @@ -0,0 +1,17 @@ + + + +

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
  • +
+

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

+ 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..b681959 --- /dev/null +++ b/tools/package/test_package.sh @@ -0,0 +1,191 @@ +#!/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 + +# 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 + +# 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 + +# 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" +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 ]