electron-mac-release 0.0.0-stage → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Youngho Andrew Chaa
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,55 @@
1
- # Temporary Holding Version
1
+ # electron-mac-release
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Packages an Electron app for macOS, signs and notarises it, and publishes it to GitHub Releases with a Squirrel.Mac JSON update manifest (`update-darwin-<arch>.json`).
4
+
5
+ ## Install
6
+
7
+ ```sh
8
+ npm install -D electron-mac-release
9
+ ```
10
+
11
+ ## Configure
12
+
13
+ Add a `macRelease` block to the app's `package.json`. The app name comes from `productName` (or `name`) and the version from `version`.
14
+
15
+ ```json
16
+ "scripts": {
17
+ "package": "npm run build && electron-mac-release package",
18
+ "release": "electron-mac-release release"
19
+ },
20
+ "macRelease": {
21
+ "include": ["dist"],
22
+ "preRelease": ["npm test", "npm run build"],
23
+ "keychainProfile": "app-signing-profile",
24
+ "packager": {
25
+ "appBundleId": "dev.example.app",
26
+ "appCategoryType": "public.app-category.productivity",
27
+ "icon": "dist/assets/app.icns",
28
+ "asar": false,
29
+ "extendInfo": { "LSUIElement": true }
30
+ }
31
+ }
32
+ ```
33
+
34
+ | Key | Default | Meaning |
35
+ | --- | --- | --- |
36
+ | `packager` | required | Passed straight to `@electron/packager`. `appBundleId` is required. |
37
+ | `include` | everything | Top-level entries to ship. `package.json` is always kept. |
38
+ | `preRelease` | `[]` | Shell commands run before packaging a release. Put your build here. |
39
+ | `keychainProfile` | `app-signing-profile` | `notarytool` keychain profile used for notarisation. |
40
+ | `arch` | `arm64` | Architecture to build. Releases must run on a Mac of that architecture. |
41
+ | `out` | `out` | Output directory. Release artefacts go to `<out>/make`. |
42
+
43
+ ## Commands
44
+
45
+ - `electron-mac-release package` packages an unsigned app. Add `--sign` to sign and notarise it.
46
+ - `electron-mac-release release "Release notes"` checks that the tree is clean and the version is unreleased, runs `preRelease`, packages, signs, notarises and verifies the app, zips it with `ditto`, writes the update manifest, tags the commit, uploads both files to a draft release and publishes it as the latest. Without notes it prompts for them.
47
+
48
+ The GitHub repository is read from `gh repo view`. The app should read its updates from `https://github.com/<owner>/<repo>/releases/latest/download/update-darwin-<arch>.json`.
49
+
50
+ ## Environment
51
+
52
+ - `APPLE_KEYCHAIN_PROFILE` overrides `keychainProfile`.
53
+ - `APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD` (or `APPLE_ID_PASSWORD`) and `APPLE_TEAM_ID` notarise with an Apple ID instead of a keychain profile.
54
+ - `APPLE_SIGN_IDENTITY` picks a signing identity.
55
+ - `ELECTRON_MAC_RELEASE_ZIP_DIR` points at a directory holding the Electron ZIP, for offline packaging.
package/bin/cli.mjs ADDED
@@ -0,0 +1,24 @@
1
+ #!/usr/bin/env node
2
+ import { loadConfig } from '../lib/config.mjs';
3
+ import { packageApp } from '../lib/package.mjs';
4
+ import { release } from '../lib/release.mjs';
5
+
6
+ const usage = `Usage:
7
+ electron-mac-release package [--sign] Package the app (signed and notarised with --sign)
8
+ electron-mac-release release ["notes"] Sign, notarise and publish a GitHub release`;
9
+
10
+ const [command, ...args] = process.argv.slice(2);
11
+ try {
12
+ const config = loadConfig();
13
+ if (command === 'package') {
14
+ console.log(await packageApp(config, { sign: args.includes('--sign') }));
15
+ } else if (command === 'release') {
16
+ await release(config, args.join(' '));
17
+ } else {
18
+ console.error(usage);
19
+ process.exit(command ? 1 : 0);
20
+ }
21
+ } catch (error) {
22
+ console.error(error.message);
23
+ process.exit(1);
24
+ }
package/lib/config.mjs ADDED
@@ -0,0 +1,39 @@
1
+ // Reads the project's package.json and its "macRelease" block.
2
+ import { readFileSync } from 'node:fs';
3
+ import { join } from 'node:path';
4
+
5
+ export function loadConfig(cwd = process.cwd()) {
6
+ const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
7
+ const mac = pkg.macRelease ?? {};
8
+ if (!mac.packager?.appBundleId)
9
+ throw new Error('package.json needs "macRelease": { "packager": { "appBundleId": ... } }.');
10
+ if (mac.include !== undefined && !Array.isArray(mac.include))
11
+ throw new Error('"macRelease.include" must be an array of top-level paths.');
12
+ if (mac.preRelease !== undefined && !Array.isArray(mac.preRelease))
13
+ throw new Error('"macRelease.preRelease" must be an array of shell commands.');
14
+ return {
15
+ cwd,
16
+ name: pkg.productName || pkg.name,
17
+ version: pkg.version,
18
+ arch: mac.arch || 'arm64',
19
+ out: mac.out || 'out',
20
+ include: mac.include,
21
+ preRelease: mac.preRelease ?? [],
22
+ keychainProfile: mac.keychainProfile,
23
+ packager: mac.packager,
24
+ };
25
+ }
26
+
27
+ // Builds an @electron/packager "ignore" function that keeps only the listed top-level entries
28
+ // (plus package.json). Packager passes paths such as "/dist/main/index.js".
29
+ export function keepOnly(include) {
30
+ const keep = new Set(['package.json', ...include.map((p) => p.replace(/^\/+|\/+$/g, ''))]);
31
+ return (path) => path !== '' && !keep.has(path.slice(1).split('/')[0]);
32
+ }
33
+
34
+ export function artefactNames({ name, version, arch }) {
35
+ return {
36
+ zip: `${name}-darwin-${arch}-${version}.zip`,
37
+ manifest: `update-darwin-${arch}.json`,
38
+ };
39
+ }
@@ -0,0 +1,32 @@
1
+ // Builds the Squirrel.Mac JSON manifest that the app reads from the latest GitHub release.
2
+ const stableSemver = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
3
+
4
+ export function assertStableVersion(version) {
5
+ if (!stableSemver.test(version ?? ''))
6
+ throw new Error(`Updates require a stable semver version, got "${version}".`);
7
+ }
8
+
9
+ export function buildManifest({
10
+ name,
11
+ version,
12
+ repository,
13
+ zipName,
14
+ notes = '',
15
+ date = new Date(),
16
+ }) {
17
+ assertStableVersion(version);
18
+ return {
19
+ currentRelease: version,
20
+ releases: [
21
+ {
22
+ version,
23
+ updateTo: {
24
+ url: `https://github.com/${repository}/releases/download/v${version}/${zipName}`,
25
+ name: `${name} ${version}`,
26
+ notes,
27
+ pub_date: date.toISOString(),
28
+ },
29
+ },
30
+ ],
31
+ };
32
+ }
@@ -0,0 +1,63 @@
1
+ // Packages the app with @electron/packager; signs and notarises it when asked.
2
+ import { packager } from '@electron/packager';
3
+ import { closeSync, openSync, readSync, statSync } from 'node:fs';
4
+ import { join } from 'node:path';
5
+ import { keepOnly } from './config.mjs';
6
+
7
+ // Thin and universal Mach-O headers, in either byte order.
8
+ const machOMagic = new Set([
9
+ 0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe, 0xcafebabe, 0xbebafeca,
10
+ ]);
11
+ export function isMachO(file) {
12
+ const fd = openSync(file, 'r');
13
+ try {
14
+ const header = Buffer.alloc(4);
15
+ return readSync(fd, header, 0, 4, 0) === 4 && machOMagic.has(header.readUInt32BE(0));
16
+ } finally {
17
+ closeSync(fd);
18
+ }
19
+ }
20
+
21
+ export function signingOptions(config, env = process.env) {
22
+ const password = env.APPLE_APP_SPECIFIC_PASSWORD || env.APPLE_ID_PASSWORD;
23
+ if (env.APPLE_ID && (!password || !env.APPLE_TEAM_ID))
24
+ throw new Error('APPLE_ID requires APPLE_APP_SPECIFIC_PASSWORD and APPLE_TEAM_ID.');
25
+ return {
26
+ osxSign: {
27
+ ...(env.APPLE_SIGN_IDENTITY ? { identity: env.APPLE_SIGN_IDENTITY } : {}),
28
+ // Sign only executable code. Resources (.pak, .dat, .png, ...) are sealed by their
29
+ // bundle's signature and should not carry signatures of their own.
30
+ ignore: (file) => statSync(file).isFile() && !isMachO(file),
31
+ },
32
+ osxNotarize: env.APPLE_ID
33
+ ? { appleId: env.APPLE_ID, appleIdPassword: password, teamId: env.APPLE_TEAM_ID }
34
+ : {
35
+ keychainProfile:
36
+ env.APPLE_KEYCHAIN_PROFILE || config.keychainProfile || 'app-signing-profile',
37
+ },
38
+ };
39
+ }
40
+
41
+ export function packagerOptions(config, { sign = false, env = process.env } = {}) {
42
+ return {
43
+ dir: config.cwd,
44
+ name: config.name,
45
+ platform: 'darwin',
46
+ arch: config.arch,
47
+ out: join(config.cwd, config.out),
48
+ overwrite: true,
49
+ ...(env.ELECTRON_MAC_RELEASE_ZIP_DIR
50
+ ? { electronZipDir: env.ELECTRON_MAC_RELEASE_ZIP_DIR }
51
+ : {}),
52
+ ...(config.include ? { ignore: keepOnly(config.include) } : {}),
53
+ ...config.packager,
54
+ ...(sign ? signingOptions(config, env) : {}),
55
+ };
56
+ }
57
+
58
+ // Returns the path of the packaged .app bundle.
59
+ export async function packageApp(config, { sign = false } = {}) {
60
+ if (process.platform !== 'darwin') throw new Error('Packaging must run on macOS.');
61
+ const [dir] = await packager(packagerOptions(config, { sign }));
62
+ return join(dir, `${config.name}.app`);
63
+ }
@@ -0,0 +1,112 @@
1
+ // Builds a signed, notarised app locally, uploads it to a draft, then publishes the version on GitHub.
2
+ import { execFileSync, execSync } from 'node:child_process';
3
+ import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
4
+ import { join } from 'node:path';
5
+ import { createInterface } from 'node:readline/promises';
6
+ import { artefactNames } from './config.mjs';
7
+ import { assertStableVersion, buildManifest } from './manifest.mjs';
8
+ import { packageApp } from './package.mjs';
9
+
10
+ function run(cmd, args, cwd) {
11
+ execFileSync(cmd, args, { cwd, stdio: 'inherit' });
12
+ }
13
+ function read(cmd, args, cwd) {
14
+ return execFileSync(cmd, args, {
15
+ cwd,
16
+ encoding: 'utf8',
17
+ stdio: ['ignore', 'pipe', 'pipe'],
18
+ }).trim();
19
+ }
20
+ function tryRead(cmd, args, cwd) {
21
+ try {
22
+ return read(cmd, args, cwd);
23
+ } catch {
24
+ return null;
25
+ }
26
+ }
27
+
28
+ async function askNotes() {
29
+ if (!process.stdin.isTTY) throw new Error('Usage: electron-mac-release release "Release notes"');
30
+ const rl = createInterface({ input: process.stdin, output: process.stdout });
31
+ try {
32
+ return (await rl.question('Release statement: ')).trim();
33
+ } finally {
34
+ rl.close();
35
+ }
36
+ }
37
+
38
+ export async function release(config, notesArg) {
39
+ const { cwd, version, arch } = config;
40
+ if (process.platform !== 'darwin' || process.arch !== arch)
41
+ throw new Error(`Releases must be built on macOS ${arch}.`);
42
+ assertStableVersion(version);
43
+ run('gh', ['auth', 'status'], cwd);
44
+ if (read('git', ['status', '--porcelain'], cwd))
45
+ throw new Error('Commit or stash changes before releasing.');
46
+
47
+ const tag = `v${version}`;
48
+ const isDraft = tryRead(
49
+ 'gh',
50
+ ['release', 'view', tag, '--json', 'isDraft', '-q', '.isDraft'],
51
+ cwd,
52
+ );
53
+ if (isDraft === 'false')
54
+ throw new Error(`Release ${tag} is already public; bump package.json's version first.`);
55
+ const tagCommit = tryRead(
56
+ 'git',
57
+ ['rev-parse', '-q', '--verify', `refs/tags/${tag}^{commit}`],
58
+ cwd,
59
+ );
60
+ if (tagCommit && tagCommit !== read('git', ['rev-parse', 'HEAD'], cwd))
61
+ throw new Error(`Tag ${tag} points to another commit; bump the version first.`);
62
+
63
+ const notes = (notesArg ?? '').trim() || (await askNotes());
64
+ if (!notes) throw new Error('Release notes must not be empty.');
65
+
66
+ const repository = read(
67
+ 'gh',
68
+ ['repo', 'view', '--json', 'nameWithOwner', '-q', '.nameWithOwner'],
69
+ cwd,
70
+ );
71
+
72
+ for (const command of config.preRelease) execSync(command, { cwd, stdio: 'inherit' });
73
+
74
+ const names = artefactNames(config);
75
+ const makeDir = join(cwd, config.out, 'make');
76
+ const zipPath = join(makeDir, names.zip);
77
+ const manifestPath = join(makeDir, names.manifest);
78
+ // Remove old artefacts so they cannot satisfy this release.
79
+ rmSync(zipPath, { force: true });
80
+ rmSync(manifestPath, { force: true });
81
+ mkdirSync(makeDir, { recursive: true });
82
+
83
+ const appPath = await packageApp(config, { sign: true });
84
+
85
+ // The packager signs, notarises and staples the app; check all three.
86
+ run('codesign', ['--verify', '--deep', '--strict', appPath], cwd);
87
+ run('xcrun', ['stapler', 'validate', appPath], cwd);
88
+ run('spctl', ['--assess', '--type', 'execute', appPath], cwd);
89
+
90
+ // ditto keeps the bundle's symlinks and metadata, which Squirrel.Mac needs.
91
+ run('ditto', ['-c', '-k', '--sequesterRsrc', '--keepParent', appPath, zipPath], cwd);
92
+ const manifest = buildManifest({
93
+ name: config.name,
94
+ version,
95
+ repository,
96
+ zipName: names.zip,
97
+ notes,
98
+ });
99
+ writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
100
+
101
+ if (!tagCommit) run('git', ['tag', '-a', tag, '-m', notes], cwd);
102
+ run('git', ['push', 'origin', `refs/tags/${tag}`], cwd);
103
+ if (isDraft !== 'true')
104
+ run(
105
+ 'gh',
106
+ ['release', 'create', tag, '--draft', '--verify-tag', '--title', tag, '--notes', notes],
107
+ cwd,
108
+ );
109
+ run('gh', ['release', 'upload', tag, zipPath, manifestPath, '--clobber'], cwd);
110
+ run('gh', ['release', 'edit', tag, '--draft=false', '--latest', '--notes', notes], cwd);
111
+ console.log(`Released ${tag}`);
112
+ }
package/package.json CHANGED
@@ -1,6 +1,23 @@
1
1
  {
2
2
  "name": "electron-mac-release",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.0.1",
4
+ "description": "Package, sign, notarise and publish an Electron app for macOS to GitHub Releases, with a Squirrel.Mac update manifest.",
5
+ "type": "module",
6
+ "bin": {
7
+ "electron-mac-release": "bin/cli.mjs"
8
+ },
9
+ "files": [
10
+ "bin",
11
+ "lib"
12
+ ],
13
+ "scripts": {
14
+ "test": "node --test test/"
15
+ },
16
+ "engines": {
17
+ "node": ">=22"
18
+ },
19
+ "dependencies": {
20
+ "@electron/packager": "^20.3.0"
21
+ },
22
+ "license": "MIT"
23
+ }