Packaging & Releases

Kangentic uses electron-builder to create platform-specific installers. Configuration lives in electron-builder.yml at the project root.

Platform Targets

Platform	Format	Installer Type
Windows	.exe	NSIS (Nullsoft Scriptable Install System)
macOS	.dmg	Disk image with drag-to-install
Linux	.deb, .rpm	Native package manager formats

Native Module Handling

Several native modules require special handling during packaging:

Module	Strategy
better-sqlite3	Rebuilt for the target Electron version via electron-builder rebuild
node-pty	Uses prebuilt binaries; falls back to rebuild if prebuilds unavailable
Bridge script	Selectively unpacked from ASAR to allow process spawning

ASAR Packaging

The app is packaged as an ASAR archive for faster loading and to prevent casual modification. Selective unpacking is configured for:

• Native .node modules that require filesystem access
• The bridge script used for process spawning

Security Fuses

Production builds set Electron security fuses to harden the application:

Fuse	Setting	Purpose
RunAsNode	Disabled	Prevents ELECTRON_RUN_AS_NODE environment variable
NodeOptions	Disabled	Prevents NODE_OPTIONS injection
Inspection	Disabled	Prevents --inspect debugging in production
Cookie Encryption	Enabled	Encrypts cookies at rest
ASAR Integrity	Enabled	Validates ASAR archive integrity on load

Code Signing

Windows

Windows builds are signed using Azure Trusted Signing. The CI pipeline authenticates with Azure credentials and signs the NSIS installer during the build step.

macOS

macOS builds use:

• Hardened runtime — required for notarization
• Apple notarization — the DMG is submitted to Apple’s notary service and stapled before release

Release Workflow

Releases follow a structured process:

1. Trigger: Run /release patch|minor|major in the repo — this bumps the version and pushes a git tag
2. CI Build: The tag push triggers GitHub Actions, which builds on all three platforms (ubuntu, windows, macos)
3. Draft Release: CI creates a draft GitHub Release with all platform artifacts attached
4. Manual Review: A maintainer reviews the draft release and the build artifacts
5. Publish: The maintainer publishes the release — this makes it visible to the auto-updater
6. npm Publish: The launcher package is published to npm so npx kangentic downloads the new version

Note

The auto-updater only sees published releases, not drafts. This gives maintainers a chance to verify builds before users receive the update.

Environment Protection

The release workflow uses GitHub environment protection rules:

• Required reviewers must approve the deployment
• The production environment is protected with branch restrictions

CI Build Matrix

Runner	Platform	Artifact
ubuntu-latest	Linux	.deb, .rpm
windows-latest	Windows	NSIS .exe
macos-latest	macOS	.dmg

Local Testing

# Build the app without creating an installer
npm run package

# Create distributable installers locally
npm run make

# Test the full publish pipeline (dry run)
npm run publish -- --dry-run

Tip

Use npm run package for quick local testing. It builds the app but skips installer creation, which is significantly faster.