electrobun 0.13.0-beta.0 → 0.13.0-beta.12

package/dist/api/bun/core/Updater.ts

@@ -5,6 +5,7 @@ import { execSync } from "child_process";
 import tar from "tar";
 import { ZstdInit } from "@oneidentity/zstd-js/wasm";
 import { OS as currentOS, ARCH as currentArch } from '../../shared/platform';
+import { getPlatformFolder, getTarballFileName } from '../../shared/naming';
 import { native } from '../proc/native';
 
 // setTimeout(async () => {
@@ -142,7 +143,7 @@ const Updater = {
 
     const channelBucketUrl = await Updater.channelBucketUrl();
     const cacheBuster = Math.random().toString(36).substring(7);
-    const platformFolder = `${localInfo.channel}-${currentOS}-${currentArch}`;
+    const platformFolder = getPlatformFolder(localInfo.channel, currentOS, currentArch);
     const updateInfoUrl = join(localInfo.bucketUrl, platformFolder, `update.json?${cacheBuster}`);
 
     try {
@@ -210,7 +211,7 @@ const Updater = {
         }
 
         // check if there's a patch file for it
-        const platformFolder = `${localInfo.channel}-${currentOS}-${currentArch}`;
+        const platformFolder = getPlatformFolder(localInfo.channel, currentOS, currentArch);
         const patchResponse = await fetch(
           join(localInfo.bucketUrl, platformFolder, `${currentHash}.patch`)
         );
@@ -329,17 +330,8 @@ const Updater = {
       // then just download it and unpack it
       if (currentHash !== latestHash) {
         const cacheBuster = Math.random().toString(36).substring(7);
-        const platformFolder = `${localInfo.channel}-${currentOS}-${currentArch}`;
-        // Platform-specific tarball naming
-        let tarballName: string;
-        if (currentOS === 'macos') {
-          tarballName = `${appFileName}.app.tar.zst`;
-        } else if (currentOS === 'win') {
-          tarballName = `${appFileName}.tar.zst`;
-        } else {
-          tarballName = `${appFileName}.tar.zst`;
-        }
-        
+        const platformFolder = getPlatformFolder(localInfo.channel, currentOS, currentArch);
+        const tarballName = getTarballFileName(appFileName, currentOS);
         const urlToLatestTarball = join(
           localInfo.bucketUrl,
           platformFolder,
@@ -694,7 +686,7 @@ start "" launcher.exe
 
   channelBucketUrl: async () => {
     await Updater.getLocallocalInfo();
-    const platformFolder = `${localInfo.channel}-${currentOS}-${currentArch}`;
+    const platformFolder = getPlatformFolder(localInfo.channel, currentOS, currentArch);
     return join(localInfo.bucketUrl, platformFolder);
   },
 

package/dist/api/shared/naming.test.ts

@@ -0,0 +1,285 @@
+import { describe, expect, it } from 'bun:test';
+import {
+  sanitizeAppName,
+  getAppFileName,
+  getBundleFileName,
+  getPlatformFolder,
+  getTarballFileName,
+  getWindowsSetupFileName,
+  getLinuxSetupFileName,
+  getLinuxAppImageBaseName,
+  getLinuxAppImageFileName,
+  sanitizeVolumeNameForHdiutil,
+  getDmgVolumeName,
+  getUpdateInfoUrl,
+  getPatchFileUrl,
+  getTarballUrl,
+} from './naming';
+
+describe('sanitizeAppName', () => {
+  it('removes spaces from app name', () => {
+    expect(sanitizeAppName('My App')).toBe('MyApp');
+    expect(sanitizeAppName('My  Multi  Spaced  App')).toBe('MyMultiSpacedApp');
+  });
+
+  it('preserves names without spaces', () => {
+    expect(sanitizeAppName('MyApp')).toBe('MyApp');
+  });
+
+  it('handles empty string', () => {
+    expect(sanitizeAppName('')).toBe('');
+  });
+});
+
+describe('getAppFileName', () => {
+  it('returns sanitized name without suffix for stable builds', () => {
+    expect(getAppFileName('My App', 'stable')).toBe('MyApp');
+  });
+
+  it('appends channel suffix for canary builds', () => {
+    expect(getAppFileName('My App', 'canary')).toBe('MyApp-canary');
+  });
+
+  it('appends channel suffix for dev builds', () => {
+    expect(getAppFileName('My App', 'dev')).toBe('MyApp-dev');
+  });
+
+  it('handles custom channels', () => {
+    expect(getAppFileName('My App', 'beta')).toBe('MyApp-beta');
+    expect(getAppFileName('My App', 'nightly')).toBe('MyApp-nightly');
+  });
+});
+
+describe('getBundleFileName', () => {
+  describe('macOS', () => {
+    it('adds .app extension for stable builds', () => {
+      expect(getBundleFileName('My App', 'stable', 'macos')).toBe('MyApp.app');
+    });
+
+    it('adds .app extension for canary builds', () => {
+      expect(getBundleFileName('My App', 'canary', 'macos')).toBe('MyApp-canary.app');
+    });
+  });
+
+  describe('Windows', () => {
+    it('returns plain name for stable builds', () => {
+      expect(getBundleFileName('My App', 'stable', 'win')).toBe('MyApp');
+    });
+
+    it('returns plain name with suffix for canary builds', () => {
+      expect(getBundleFileName('My App', 'canary', 'win')).toBe('MyApp-canary');
+    });
+  });
+
+  describe('Linux', () => {
+    it('returns plain name for stable builds', () => {
+      expect(getBundleFileName('My App', 'stable', 'linux')).toBe('MyApp');
+    });
+
+    it('returns plain name with suffix for canary builds', () => {
+      expect(getBundleFileName('My App', 'canary', 'linux')).toBe('MyApp-canary');
+    });
+  });
+});
+
+describe('getPlatformFolder', () => {
+  it('constructs correct folder format for all platform combinations', () => {
+    expect(getPlatformFolder('stable', 'macos', 'arm64')).toBe('stable-macos-arm64');
+    expect(getPlatformFolder('stable', 'macos', 'x64')).toBe('stable-macos-x64');
+    expect(getPlatformFolder('canary', 'win', 'x64')).toBe('canary-win-x64');
+    expect(getPlatformFolder('dev', 'linux', 'arm64')).toBe('dev-linux-arm64');
+    expect(getPlatformFolder('dev', 'linux', 'x64')).toBe('dev-linux-x64');
+  });
+});
+
+describe('getTarballFileName', () => {
+  describe('macOS', () => {
+    it('uses .app.tar.zst extension', () => {
+      expect(getTarballFileName('MyApp', 'macos')).toBe('MyApp.app.tar.zst');
+    });
+
+    it('preserves channel suffix in filename', () => {
+      expect(getTarballFileName('MyApp-canary', 'macos')).toBe('MyApp-canary.app.tar.zst');
+    });
+  });
+
+  describe('Windows', () => {
+    it('uses .tar.zst extension', () => {
+      expect(getTarballFileName('MyApp', 'win')).toBe('MyApp.tar.zst');
+    });
+
+    it('preserves channel suffix in filename', () => {
+      expect(getTarballFileName('MyApp-canary', 'win')).toBe('MyApp-canary.tar.zst');
+    });
+  });
+
+  describe('Linux', () => {
+    it('uses .tar.zst extension', () => {
+      expect(getTarballFileName('MyApp', 'linux')).toBe('MyApp.tar.zst');
+    });
+
+    it('preserves channel suffix in filename', () => {
+      expect(getTarballFileName('MyApp-canary', 'linux')).toBe('MyApp-canary.tar.zst');
+    });
+  });
+});
+
+describe('getWindowsSetupFileName', () => {
+  it('returns AppName-Setup.exe for stable builds', () => {
+    expect(getWindowsSetupFileName('MyApp', 'stable')).toBe('MyApp-Setup.exe');
+  });
+
+  it('includes channel suffix for canary builds', () => {
+    expect(getWindowsSetupFileName('MyApp', 'canary')).toBe('MyApp-Setup-canary.exe');
+  });
+
+  it('includes channel suffix for dev builds', () => {
+    expect(getWindowsSetupFileName('MyApp', 'dev')).toBe('MyApp-Setup-dev.exe');
+  });
+});
+
+describe('getLinuxSetupFileName', () => {
+  it('returns AppName-Setup.run for stable builds', () => {
+    expect(getLinuxSetupFileName('MyApp', 'stable')).toBe('MyApp-Setup.run');
+  });
+
+  it('includes channel suffix for canary builds', () => {
+    expect(getLinuxSetupFileName('MyApp', 'canary')).toBe('MyApp-Setup-canary.run');
+  });
+
+  it('includes channel suffix for dev builds', () => {
+    expect(getLinuxSetupFileName('MyApp', 'dev')).toBe('MyApp-Setup-dev.run');
+  });
+});
+
+describe('getLinuxAppImageBaseName', () => {
+  it('returns AppName-Setup for stable builds', () => {
+    expect(getLinuxAppImageBaseName('MyApp', 'stable')).toBe('MyApp-Setup');
+  });
+
+  it('includes channel suffix for canary builds', () => {
+    expect(getLinuxAppImageBaseName('MyApp', 'canary')).toBe('MyApp-Setup-canary');
+  });
+});
+
+describe('getLinuxAppImageFileName', () => {
+  it('returns full filename with .AppImage extension for stable', () => {
+    expect(getLinuxAppImageFileName('MyApp', 'stable')).toBe('MyApp-Setup.AppImage');
+  });
+
+  it('returns full filename with .AppImage extension for canary', () => {
+    expect(getLinuxAppImageFileName('MyApp', 'canary')).toBe('MyApp-Setup-canary.AppImage');
+  });
+});
+
+describe('sanitizeVolumeNameForHdiutil', () => {
+  it('removes special characters', () => {
+    expect(sanitizeVolumeNameForHdiutil('My-App_v1.0')).toBe('MyAppv10');
+  });
+
+  it('removes parentheses and other punctuation', () => {
+    expect(sanitizeVolumeNameForHdiutil('My App (Beta)')).toBe('My App Beta');
+  });
+
+  it('preserves spaces and alphanumerics', () => {
+    expect(sanitizeVolumeNameForHdiutil('My App 2024')).toBe('My App 2024');
+  });
+
+  it('trims leading and trailing whitespace', () => {
+    expect(sanitizeVolumeNameForHdiutil('  My App  ')).toBe('My App');
+  });
+
+  it('handles names with only special characters', () => {
+    expect(sanitizeVolumeNameForHdiutil('---')).toBe('');
+  });
+});
+
+describe('getDmgVolumeName', () => {
+  it('adds -stable suffix for stable builds (to avoid CI volume conflicts)', () => {
+    expect(getDmgVolumeName('MyApp', 'stable')).toBe('MyApp-stable');
+  });
+
+  it('returns sanitized name for canary builds (already has suffix)', () => {
+    expect(getDmgVolumeName('MyApp-canary', 'canary')).toBe('MyAppcanary');
+  });
+
+  it('sanitizes special characters', () => {
+    expect(getDmgVolumeName('My-App', 'stable')).toBe('MyApp-stable');
+  });
+});
+
+describe('URL construction functions', () => {
+  const bucketUrl = 'https://storage.example.com/releases';
+  const platformFolder = 'canary-macos-arm64';
+
+  describe('getUpdateInfoUrl', () => {
+    it('constructs correct URL', () => {
+      expect(getUpdateInfoUrl(bucketUrl, platformFolder))
+        .toBe('https://storage.example.com/releases/canary-macos-arm64/update.json');
+    });
+
+    it('handles bucket URLs with trailing content', () => {
+      expect(getUpdateInfoUrl('https://example.com/bucket', 'stable-win-x64'))
+        .toBe('https://example.com/bucket/stable-win-x64/update.json');
+    });
+  });
+
+  describe('getPatchFileUrl', () => {
+    it('constructs correct URL with hash', () => {
+      expect(getPatchFileUrl(bucketUrl, platformFolder, 'abc123def456'))
+        .toBe('https://storage.example.com/releases/canary-macos-arm64/abc123def456.patch');
+    });
+  });
+
+  describe('getTarballUrl', () => {
+    it('constructs correct URL for macOS tarball', () => {
+      expect(getTarballUrl(bucketUrl, platformFolder, 'MyApp.app.tar.zst'))
+        .toBe('https://storage.example.com/releases/canary-macos-arm64/MyApp.app.tar.zst');
+    });
+
+    it('constructs correct URL for Windows tarball', () => {
+      expect(getTarballUrl(bucketUrl, 'stable-win-x64', 'MyApp.tar.zst'))
+        .toBe('https://storage.example.com/releases/stable-win-x64/MyApp.tar.zst');
+    });
+  });
+});
+
+// Integration tests that verify CLI and Updater would produce matching values
+describe('CLI and Updater consistency', () => {
+  it('produces matching platform folders', () => {
+    // CLI uses: `${buildEnvironment}-${currentTarget.os}-${currentTarget.arch}`
+    // Updater uses: `${localInfo.channel}-${currentOS}-${currentArch}`
+    // Both should use getPlatformFolder()
+    const cliResult = getPlatformFolder('canary', 'macos', 'arm64');
+    const updaterResult = getPlatformFolder('canary', 'macos', 'arm64');
+    expect(cliResult).toBe(updaterResult);
+    expect(cliResult).toBe('canary-macos-arm64');
+  });
+
+  it('produces matching tarball names for macOS', () => {
+    const appFileName = getAppFileName('My App', 'canary');
+    const tarballName = getTarballFileName(appFileName, 'macos');
+    expect(tarballName).toBe('MyApp-canary.app.tar.zst');
+  });
+
+  it('produces matching tarball names for Windows', () => {
+    const appFileName = getAppFileName('My App', 'stable');
+    const tarballName = getTarballFileName(appFileName, 'win');
+    expect(tarballName).toBe('MyApp.tar.zst');
+  });
+
+  it('produces matching tarball names for Linux', () => {
+    const appFileName = getAppFileName('My App', 'dev');
+    const tarballName = getTarballFileName(appFileName, 'linux');
+    expect(tarballName).toBe('MyApp-dev.tar.zst');
+  });
+
+  it('stable builds have no channel suffix in artifact names', () => {
+    // This is the regression test for the -stable bug
+    expect(getAppFileName('MyApp', 'stable')).toBe('MyApp');
+    expect(getAppFileName('MyApp', 'stable')).not.toContain('-stable');
+    expect(getTarballFileName(getAppFileName('MyApp', 'stable'), 'macos')).toBe('MyApp.app.tar.zst');
+    expect(getWindowsSetupFileName('MyApp', 'stable')).toBe('MyApp-Setup.exe');
+    expect(getLinuxSetupFileName('MyApp', 'stable')).toBe('MyApp-Setup.run');
+  });
+});

package/dist/api/shared/naming.ts

@@ -0,0 +1,131 @@
+import type { SupportedOS, SupportedArch } from './platform';
+
+/**
+ * Build environment/channel types.
+ * "stable" is special - it produces artifacts without a channel suffix.
+ */
+export type BuildEnvironment = 'stable' | 'canary' | 'dev' | (string & {});
+
+/**
+ * Sanitizes an app name by removing spaces.
+ * Used as the base for all artifact naming.
+ */
+export function sanitizeAppName(appName: string): string {
+  return appName.replace(/ /g, '');
+}
+
+/**
+ * Generates the app file name based on build environment.
+ * Format: "AppName" (stable) or "AppName-channel" (non-stable)
+ *
+ * @example
+ * getAppFileName("My App", "stable") // "MyApp"
+ * getAppFileName("My App", "canary") // "MyApp-canary"
+ */
+export function getAppFileName(appName: string, buildEnvironment: BuildEnvironment): string {
+  const sanitized = sanitizeAppName(appName);
+  return buildEnvironment === 'stable' ? sanitized : `${sanitized}-${buildEnvironment}`;
+}
+
+/**
+ * Generates the bundle file name (with platform-specific extension).
+ * macOS: "AppName.app" or "AppName-channel.app"
+ * Others: "AppName" or "AppName-channel"
+ */
+export function getBundleFileName(appName: string, buildEnvironment: BuildEnvironment, os: SupportedOS): string {
+  const appFileName = getAppFileName(appName, buildEnvironment);
+  return os === 'macos' ? `${appFileName}.app` : appFileName;
+}
+
+/**
+ * Generates the platform folder name for artifacts.
+ * Format: "channel-os-arch" (e.g., "stable-macos-arm64", "canary-win-x64")
+ */
+export function getPlatformFolder(buildEnvironment: BuildEnvironment, os: SupportedOS, arch: SupportedArch): string {
+  return `${buildEnvironment}-${os}-${arch}`;
+}
+
+/**
+ * Generates the tarball file name for update distribution.
+ * macOS: "AppFileName.app.tar.zst"
+ * Others: "AppFileName.tar.zst"
+ */
+export function getTarballFileName(appFileName: string, os: SupportedOS): string {
+  return os === 'macos' ? `${appFileName}.app.tar.zst` : `${appFileName}.tar.zst`;
+}
+
+/**
+ * Generates the Windows installer setup file name.
+ * Format: "AppName-Setup.exe" (stable) or "AppName-Setup-channel.exe" (non-stable)
+ */
+export function getWindowsSetupFileName(appName: string, buildEnvironment: BuildEnvironment): string {
+  return buildEnvironment === 'stable'
+    ? `${appName}-Setup.exe`
+    : `${appName}-Setup-${buildEnvironment}.exe`;
+}
+
+/**
+ * Generates the Linux self-extracting binary file name.
+ * Format: "AppName-Setup.run" (stable) or "AppName-Setup-channel.run" (non-stable)
+ */
+export function getLinuxSetupFileName(appName: string, buildEnvironment: BuildEnvironment): string {
+  return buildEnvironment === 'stable'
+    ? `${appName}-Setup.run`
+    : `${appName}-Setup-${buildEnvironment}.run`;
+}
+
+/**
+ * Generates the Linux AppImage wrapper name (without extension).
+ * Format: "AppName-Setup" (stable) or "AppName-Setup-channel" (non-stable)
+ */
+export function getLinuxAppImageBaseName(appName: string, buildEnvironment: BuildEnvironment): string {
+  return buildEnvironment === 'stable'
+    ? `${appName}-Setup`
+    : `${appName}-Setup-${buildEnvironment}`;
+}
+
+/**
+ * Generates the full Linux AppImage file name.
+ */
+export function getLinuxAppImageFileName(appName: string, buildEnvironment: BuildEnvironment): string {
+  return `${getLinuxAppImageBaseName(appName, buildEnvironment)}.AppImage`;
+}
+
+/**
+ * Sanitizes a volume name for hdiutil (macOS DMG creation).
+ * Removes all non-alphanumeric characters except spaces.
+ */
+export function sanitizeVolumeNameForHdiutil(name: string): string {
+  return name.replace(/[^a-zA-Z0-9 ]/g, '').trim();
+}
+
+/**
+ * Generates the DMG volume name for macOS during creation.
+ * Uses sanitized name with "-stable" suffix for stable builds to avoid
+ * CI volume mounting conflicts. The DMG is renamed after creation.
+ */
+export function getDmgVolumeName(appFileName: string, buildEnvironment: BuildEnvironment): string {
+  const baseName = sanitizeVolumeNameForHdiutil(appFileName);
+  return buildEnvironment === 'stable' ? `${baseName}-stable` : baseName;
+}
+
+/**
+ * Constructs the full URL for the update.json file.
+ */
+export function getUpdateInfoUrl(bucketUrl: string, platformFolder: string): string {
+  return `${bucketUrl}/${platformFolder}/update.json`;
+}
+
+/**
+ * Constructs the full URL for a patch file.
+ */
+export function getPatchFileUrl(bucketUrl: string, platformFolder: string, hash: string): string {
+  return `${bucketUrl}/${platformFolder}/${hash}.patch`;
+}
+
+/**
+ * Constructs the full URL for a tarball.
+ */
+export function getTarballUrl(bucketUrl: string, platformFolder: string, tarballFileName: string): string {
+  return `${bucketUrl}/${platformFolder}/${tarballFileName}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "electrobun",
-  "version": "0.13.0-beta.0",
+  "version": "0.13.0-beta.12",
   "description": "Build ultra fast, tiny, and cross-platform desktop apps with Typescript.",
   "license": "MIT",
   "author": "Blackboard Technologies Inc.",
@@ -35,6 +35,7 @@
     "dev:clean": "cd ../kitchen && rm -rf node_modules && rm -rf vendors/cef && cd ../package && bun dev",
     "dev:rerun": "cd ../kitchen && bun start",
     "dev:canary": "bun install && bun build:release && bun build:cli && cd ../kitchen && bun install && bun build:canary",
+    "dev:stable": "bun install && bun build:release && bun build:cli && cd ../kitchen && bun install && bun build:stable",
     "run:template": "bun install && bun build:dev && bun build:cli && cd ../templates/interactive-playground && bun install && bun build:dev && bun start",
     "dev:docs": "cd ../documentation && bun start",
     "build:docs:release": "cd ../documentation && bun run build",
@@ -46,7 +47,8 @@
     "push:major": "bun scripts/push-version.js major",
     "push:stable": "bun scripts/push-version.js stable",
     "build:push:artifacts": "bun scripts/build-and-upload-artifacts.js",
-    "test": "bun install && bun build:dev && bun build:cli && cd ../tests && bun install && bun build:dev && bun start"
+    "test": "bun install && bun build:dev && bun build:cli && cd ../tests && bun install && bun build:dev && bun start",
+    "test:unit": "bun test src/shared"
   },
   "devDependencies": {
     "@types/archiver": "^6.0.3",

package/src/cli/index.ts

@@ -22,6 +22,17 @@ import tar from "tar";
 import archiver from "archiver";
 import { ZstdInit } from "@oneidentity/zstd-js/wasm";
 import { OS, ARCH } from '../shared/platform';
+import {
+  getAppFileName,
+  getBundleFileName,
+  getPlatformFolder,
+  getTarballFileName,
+  getWindowsSetupFileName,
+  getLinuxSetupFileName,
+  getLinuxAppImageBaseName,
+  sanitizeVolumeNameForHdiutil,
+  getDmgVolumeName,
+} from '../shared/naming';
 import { getTemplate, getTemplateNames } from './templates/embedded';
 // import { loadBsdiff, loadBspatch } from 'bsdiff-wasm';
 // MacOS named pipes hang at around 4KB
@@ -1014,6 +1025,12 @@ if (commandArg === "init") {
     console.log("   bun start");
     console.log("");
     console.log("🎉 Happy building with Electrobun!");
+    console.log("");
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+    console.log("NOTE FOR AI ASSISTANTS: Electrobun is NOT Electron.");
+    console.log("Different architecture, different APIs. Do not use Electron patterns.");
+    console.log("Docs: https://blackboard.sh/electrobun/llms.txt");
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
   })();
 } else if (commandArg === "build") {
   // Get config
@@ -1030,10 +1047,10 @@ if (commandArg === "init") {
   const targetOS = currentTarget.os;
   const targetARCH = currentTarget.arch;
   const targetBinExt = targetOS === 'win' ? '.exe' : '';
-  const appFileName = `${config.app.name.replace(/ /g, "")}-${buildEnvironment}`;
-  const buildSubFolder = `${buildEnvironment}-${currentTarget.os}-${currentTarget.arch}`;
+  const appFileName = getAppFileName(config.app.name, buildEnvironment);
+  const buildSubFolder = getPlatformFolder(buildEnvironment, currentTarget.os, currentTarget.arch);
   const buildFolder = join(projectRoot, config.build.buildFolder, buildSubFolder);
-  const bundleFileName = targetOS === 'macos' ? `${appFileName}.app` : appFileName;
+  const bundleFileName = getBundleFileName(config.app.name, buildEnvironment, targetOS);
   const artifactFolder = join(projectRoot, config.build.artifactFolder, buildSubFolder);
   
   // Ensure core binaries are available for the target platform before starting build
@@ -1041,11 +1058,6 @@ if (commandArg === "init") {
   
   // Get platform-specific paths for the current target
   const targetPaths = getPlatformPaths(currentTarget.os, currentTarget.arch);
-  
-  // Helper functions
-  const sanitizeVolumeNameForHdiutil = (name: string) => {
-    return name.replace(/[^a-zA-Z0-9 ]/g, '').trim();
-  };
 
   // Helper to run lifecycle hook scripts
   const runHook = (hookName: keyof typeof config.scripts, extraEnv: Record<string, string> = {}) => {
@@ -1087,11 +1099,28 @@ if (commandArg === "init") {
 
   const buildIcons = (appBundleFolderResourcesPath: string) => {
     // Platform-specific icon handling
-    if (targetOS === 'macos' && config.build.mac?.icon) {
-      const iconPath = join(projectRoot, config.build.mac.icon);
-      if (existsSync(iconPath)) {
-        const targetIconPath = join(appBundleFolderResourcesPath, "AppIcon.icns");
-        cpSync(iconPath, targetIconPath, { dereference: true });
+    if (targetOS === 'macos' && config.build.mac?.icons) {
+      // macOS uses .iconset folders that get converted to .icns using iconutil
+      // This only works when building on macOS since iconutil is a macOS-only tool
+      const iconSourceFolder = join(projectRoot, config.build.mac.icons);
+      const iconDestPath = join(appBundleFolderResourcesPath, "AppIcon.icns");
+      if (existsSync(iconSourceFolder)) {
+        if (OS === 'macos') {
+          // Use iconutil to convert .iconset folder to .icns
+          Bun.spawnSync(
+            ["iconutil", "-c", "icns", "-o", iconDestPath, iconSourceFolder],
+            {
+              cwd: appBundleFolderResourcesPath,
+              stdio: ["ignore", "inherit", "inherit"],
+              env: {
+                ...process.env,
+                ELECTROBUN_BUILD_ENV: buildEnvironment,
+              },
+            }
+          );
+        } else {
+          console.log(`WARNING: Cannot build macOS icons on ${OS} - iconutil is only available on macOS`);
+        }
       }
     } else if (targetOS === 'linux' && config.build.linux?.icon) {
       const iconSourcePath = join(projectRoot, config.build.linux.icon);
@@ -1965,7 +1994,8 @@ if (commandArg === "init") {
   if (shouldCodesign) {
     codesignAppBundle(
       appBundleFolderPath,
-      join(buildFolder, "entitlements.plist")
+      join(buildFolder, "entitlements.plist"),
+      config
     );
   } else {
     console.log("skipping codesign");
@@ -1975,11 +2005,11 @@ if (commandArg === "init") {
   // NOTE: Codesigning fails in dev mode (when using a single-file-executable bun cli as the launcher)
   // see https://github.com/oven-sh/bun/issues/7208
   if (shouldNotarize) {
-    notarizeAndStaple(appBundleFolderPath);
+    notarizeAndStaple(appBundleFolderPath, config);
   } else {
     console.log("skipping notarization");
   }
-  
+
   const artifactsToUpload = [];
 
   console.log(`DEBUG: Checking for Linux AppImage creation - targetOS: ${targetOS}, buildEnvironment: ${buildEnvironment}`);
@@ -2203,7 +2233,8 @@ if (commandArg === "init") {
     if (shouldCodesign) {
       codesignAppBundle(
         selfExtractingBundle.appBundleFolderPath,
-        join(buildFolder, "entitlements.plist")
+        join(buildFolder, "entitlements.plist"),
+        config
       );
     } else {
       console.log("skipping codesign");
@@ -2211,7 +2242,7 @@ if (commandArg === "init") {
 
     // Note: we need to notarize the original app bundle, the self-extracting app bundle, and the dmg
     if (shouldNotarize) {
-      notarizeAndStaple(selfExtractingBundle.appBundleFolderPath);
+      notarizeAndStaple(selfExtractingBundle.appBundleFolderPath, config);
     } else {
       console.log("skipping notarization");
     }
@@ -2229,11 +2260,7 @@ if (commandArg === "init") {
         buildEnvironment === "stable"
           ? join(buildFolder, `${appFileName}-stable.dmg`)
           : finalDmgPath;
-      const baseVolumeName = sanitizeVolumeNameForHdiutil(appFileName);
-      const dmgVolumeName =
-        buildEnvironment === "stable"
-          ? `${baseVolumeName}-stable`
-          : baseVolumeName;
+      const dmgVolumeName = getDmgVolumeName(appFileName, buildEnvironment);
 
       // Create a staging directory for DMG contents (app + Applications shortcut)
       const dmgStagingDir = join(buildFolder, '.dmg-staging');
@@ -2266,13 +2293,13 @@ if (commandArg === "init") {
       artifactsToUpload.push(finalDmgPath);
 
       if (shouldCodesign) {
-        codesignAppBundle(finalDmgPath);
+        codesignAppBundle(finalDmgPath, undefined, config);
       } else {
         console.log("skipping codesign");
       }
 
       if (shouldNotarize) {
-        notarizeAndStaple(finalDmgPath);
+        notarizeAndStaple(finalDmgPath, config);
       } else {
         console.log("skipping notarization");
       }
@@ -2702,11 +2729,7 @@ async function createWindowsSelfExtractingExe(
 ): Promise<string> {
   console.log("Creating Windows installer with separate archive...");
 
-  // Format: MyApp-Setup.exe (stable) or MyApp-Setup-canary.exe (non-stable)
-  const setupFileName = buildEnvironment === "stable"
-    ? `${config.app.name}-Setup.exe`
-    : `${config.app.name}-Setup-${buildEnvironment}.exe`;
-
+  const setupFileName = getWindowsSetupFileName(config.app.name, buildEnvironment);
   const outputExePath = join(buildFolder, setupFileName);
 
   // Copy the extractor exe
@@ -2793,14 +2816,12 @@ async function createLinuxSelfExtractingBinary(
   compressedTarPath: string,
   appFileName: string,
   targetPaths: any,
-  buildEnvironment: string
+  buildEnvironment: string,
+  config: Awaited<ReturnType<typeof getConfig>>
 ): Promise<string> {
   console.log("Creating self-extracting Linux binary...");
-  
-  // Format: MyApp-Setup.run (stable) or MyApp-Setup-canary.run (non-stable)
-  const setupFileName = buildEnvironment === "stable" 
-    ? `${config.app.name}-Setup.run`
-    : `${config.app.name}-Setup-${buildEnvironment}.run`;
+
+  const setupFileName = getLinuxSetupFileName(config.app.name, buildEnvironment);
   
   const outputPath = join(buildFolder, setupFileName);
   
@@ -2967,10 +2988,7 @@ async function createLinuxSelfExtractingAppImage(
   console.log('Creating Linux AppImage wrapper...');
 
   // Create wrapper AppImage filename
-  const wrapperName = buildEnvironment === 'stable' 
-    ? `${config.app.name}-Setup`
-    : `${config.app.name}-Setup-${buildEnvironment}`;
-  
+  const wrapperName = getLinuxAppImageBaseName(config.app.name, buildEnvironment);
   const wrapperAppImagePath = join(buildFolder, `${wrapperName}.AppImage`);
   const wrapperAppDirPath = join(buildFolder, `${wrapperName}.AppDir`);
 
@@ -3111,7 +3129,8 @@ Categories=Utility;
 
 function codesignAppBundle(
   appBundleOrDmgPath: string,
-  entitlementsFilePath?: string
+  entitlementsFilePath: string | undefined,
+  config: Awaited<ReturnType<typeof getConfig>>
 ) {
   console.log("code signing...");
   if (OS !== 'macos' || !config.build.mac.codesign) {
@@ -3310,7 +3329,7 @@ function codesignAppBundle(
   );
 }
 
-function notarizeAndStaple(appOrDmgPath: string) {
+function notarizeAndStaple(appOrDmgPath: string, config: Awaited<ReturnType<typeof getConfig>>) {
   if (OS !== 'macos' || !config.build.mac.notarize) {
     return;
   }