Feat. Add. pkg installer distribution#49
Conversation
![amazon-q-developer[bot]](https://avatars.githubusercontent.com/in/1220912?s=60&v=4){kind=small}
There was a problem hiding this comment.
This PR adds comprehensive specification documentation for a new .pkg installer distribution channel. The documentation includes requirements, design, and implementation tasks that are well-structured and thorough.
After reviewing all files, the specifications appear sound with proper security considerations (secrets are already excluded via .gitignore), comprehensive error handling, and clear implementation guidance. The design appropriately reuses existing Makefile infrastructure and follows established patterns from the brew-release target.
The documentation is ready for implementation.
You can now have the agent implement changes and create commits directly on your pull request's source branch. Simply comment with /q followed by your request in natural language to ask the agent to make changes.
| ├── secrets/ | ||
| │ └── notarization.json # Now includes "installer_identity" field |
There was a problem hiding this comment.
🛑 Security Vulnerability: The design references secrets/notarization.json in the file layout (lines 115-116) without explicitly documenting that this file must be excluded from version control. The file contains sensitive credentials (Apple ID, team ID, signing identities) that could be exposed if committed.
Add explicit documentation that secrets/notarization.json must be added to .gitignore and specify validation in the build pipeline to fail if this file is tracked by git. This prevents accidental credential exposure.
| ### `secrets/notarization.json` (extended) | ||
|
|
||
| ```json | ||
| { | ||
| "apple_id": "[email]", | ||
| "team_id": "[team_id]", | ||
| "signing_identity": "Developer ID Application: [name] ([team_id])", | ||
| "installer_identity": "Developer ID Installer: [name] ([team_id])" | ||
| } | ||
| ``` |
There was a problem hiding this comment.
🛑 Security Vulnerability: The JSON schema includes sensitive credentials (Apple ID, signing identities) without documenting that this file must never be committed to version control. The design document should explicitly state that secrets/notarization.json must be listed in .gitignore.
Add a security note to this section specifying that this file contains sensitive credentials and must be excluded from version control.
| <choice id="wispr" visible="false"> | ||
| <pkg-ref id="com.stormacq.mac.wispr"/> | ||
| </choice> | ||
| <pkg-ref id="com.stormacq.mac.wispr" version="0" onConclusion="none">wispr-component.pkg</pkg-ref> |
There was a problem hiding this comment.
🛑 Logic Error: The pkg-ref version is hardcoded to 0 which conflicts with the requirement to set version via pkgbuild --version $(VERSION) (design.md line 166). This creates version inconsistency where the component package has the correct version but the distribution XML references version 0.
The pkg-ref version attribute should be set to match $(VERSION) dynamically during the build, or the design should clarify that version 0 is intentional and explain how version validation will work during installation.
There was a problem hiding this comment.
Pull request overview
Adds a requirements-first specification package for introducing a signed/notarized .pkg installer distribution workflow to the existing Wispr Makefile-based release pipeline.
Changes:
- Added a requirements document defining the
.pkginstaller build/sign/notarize/release acceptance criteria. - Added a design document detailing Makefile integration, data model changes, and the intended build flow.
- Added an implementation task plan and Kiro spec configuration for tracking the work.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 7 comments.
| File | Description |
|---|---|
.kiro/specs/pkg-installer/requirements.md |
Defines user stories and acceptance criteria for a .pkg installer distribution channel. |
.kiro/specs/pkg-installer/design.md |
Documents proposed architecture, Makefile targets/variables, and build/notarization flow. |
.kiro/specs/pkg-installer/tasks.md |
Breaks the work into actionable implementation steps and checkpoints. |
.kiro/specs/pkg-installer/.config.kiro |
Adds Kiro workflow metadata for the new spec. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| # Implementation Plan: pkg-installer | ||
|
|
||
| ## Overview | ||
|
|
||
| Extend the existing Makefile build pipeline with `pkg` and `pkg-release` targets that produce a signed, notarized `.pkg` installer with custom UI. All installer resources (`pkg/distribution.xml`, `pkg/resources/`) are created as static files. The `secrets/notarization.json` schema is extended with an `installer_identity` field. Property-based tests use Python/Hypothesis. |
| - _Requirements: 7.2, 7.3_ | ||
|
|
||
| - [ ] 3.4 Add `pkgbuild` step to create the component package | ||
| - `pkgbuild --root <app parent> --install-location /Applications --identifier $(BUNDLE_ID) --version $(VERSION) $(COMPONENT_PKG)` |
| - [ ] 3. Extend Makefile with `pkg` target | ||
| - [ ] 3.1 Add new Makefile variables for the pkg pipeline | ||
| - `INSTALLER_IDENTITY` read from `$(NOTARIZATION_JSON)` via `jq -r .installer_identity` | ||
| - `COMPONENT_PKG`, `PRODUCT_PKG`, `SIGNED_PKG`, `FINAL_PKG` derived paths in `$(EXPORT_DIR)` | ||
| - `PKG_RESOURCES` pointing to `$(CURDIR)/pkg/resources` | ||
| - `DISTRIBUTION_XML` pointing to `$(CURDIR)/pkg/distribution.xml` | ||
| - Reuse all existing variables (`BUNDLE_ID`, `SIGNING_IDENTITY`, `APP_PATH`, `EXPORT_DIR`, `ARCHIVE_PATH`, `API_KEY_PATH`, `API_KEY_ID`, `API_ISSUER`, `NOTARIZATION_JSON`) | ||
| - _Requirements: 5.6, 7.1, 7.2_ |
| - [ ] 8. Property-based tests (Python/Hypothesis) | ||
| - [ ]* 8.1 Write property test for installer identity extraction round trip | ||
| - **Property 1: Installer identity extraction round trip** | ||
| - Generate random valid JSON with a non-empty `installer_identity` string, write to temp file, extract via `jq -r .installer_identity`, assert output matches original |
|
|
||
| ## Error Handling | ||
|
|
||
| All error handling follows the existing Makefile pattern: print a descriptive message to stderr and `exit 1`. No partial artifacts are left behind on failure. |
|
|
||
| | Step | Tool | Key Arguments | | ||
| |------|------|---------------| | ||
| | Component pkg | `pkgbuild` | `--root` (app path parent), `--component-plist` (not needed, single app), `--install-location /Applications`, `--identifier $(BUNDLE_ID)`, `--version $(VERSION)` | |
|
|
||
| - [ ] 3.3 Add `installer_identity` validation step | ||
| - Read `INSTALLER_IDENTITY` from `$(NOTARIZATION_JSON)` and verify it is non-empty | ||
| - Print `Error: installer_identity not found in <path>` and `exit 1` if missing |
The
.pkginstalls to/Applicationswith a custom installer UI (branded background, welcome, readme, license). Two newMakefiletargets:make pkgfor local builds andmake pkg-release VERSION=x.y.zto upload to GitHub Releases. Reuses the existing notarize pipeline end-to-end, no duplicated build logic. Spec covers requirements, design, and implementation tasks in.kiro/specs/pkg-installer/.Recreated from #16 after accidental branch deletion.