feat(electron): add desktop application support with electron (#344)

* feat(electron): add desktop application support with electron

- implement complete Electron main process architecture with window management,
  app menu, IPC handlers, and settings window
- integrate Next.js server for production builds with embedded standalone server
- add configuration management with persistent storage and env file support
- create preload scripts with secure context bridge for renderer communication
- set up electron-builder configuration for multi-platform packaging (macOS,
  Windows, Linux)
- add GitHub Actions workflow for automated release builds
- include development scripts for hot-reload during Electron development

* feat(electron): enhance security and stability

- encrypt API keys using Electron safeStorage API before persisting to disk
- add error handling and rollback for preset switching failures
- extract inline styles to external CSS file and remove unsafe-inline from CSP
- implement dynamic port allocation with automatic fallback for production builds

* fix(electron): add maintainer field for Linux .deb package

- add maintainer email to linux configuration in electron-builder.yml
- required for building .deb packages

* fix(electron): use shx for cross-platform file copying

- replace Unix-only cp -r with npx shx cp -r
- add shx as devDependency for Windows compatibility

* fix(electron): fix runtime icon path for all platforms

- use icon.png directly instead of platform-specific formats
- electron-builder handles icon conversion during packaging
- macOS uses embedded icon from app bundle, no explicit path needed
- add icon.png to extraResources for Windows/Linux runtime access

* fix(electron): add security warning for plaintext API key storage

- warn user when safeStorage is unavailable (Linux without keyring)
- fail secure: throw error if encryption fails instead of storing plaintext
- prevent duplicate warnings with hasWarnedAboutPlaintext flag

* fix(electron): add remaining review fixes

- Add Windows ARM64 architecture support
- Add IPC input validation with config key whitelist
- Add server.js existence check before starting Next.js server
- Make afterPack throw error on missing directories
- Add workflow permissions for release job

---------

Co-authored-by: dayuan.jiang <jdy.toh@gmail.com>

electron/main/port-manager.ts

@@ -0,0 +1,129 @@
+import net from "node:net"
+import { app } from "electron"
+
+/**
+ * Port configuration
+ */
+const PORT_CONFIG = {
+    // Development mode uses fixed port for hot reload compatibility
+    development: 6002,
+    // Production mode port range (will find first available)
+    production: {
+        min: 10000,
+        max: 65535,
+    },
+    // Maximum attempts to find an available port
+    maxAttempts: 100,
+}
+
+/**
+ * Currently allocated port (cached after first allocation)
+ */
+let allocatedPort: number | null = null
+
+/**
+ * Check if a specific port is available
+ */
+export function isPortAvailable(port: number): Promise<boolean> {
+    return new Promise((resolve) => {
+        const server = net.createServer()
+        server.once("error", () => resolve(false))
+        server.once("listening", () => {
+            server.close()
+            resolve(true)
+        })
+        server.listen(port, "127.0.0.1")
+    })
+}
+
+/**
+ * Generate a random port within the production range
+ */
+function getRandomPort(): number {
+    const { min, max } = PORT_CONFIG.production
+    return Math.floor(Math.random() * (max - min + 1)) + min
+}
+
+/**
+ * Find an available port
+ * - In development: uses fixed port (6002)
+ * - In production: finds a random available port
+ * - If a port was previously allocated, verifies it's still available
+ *
+ * @param reuseExisting If true, try to reuse the previously allocated port
+ * @returns Promise<number> The available port
+ * @throws Error if no available port found after max attempts
+ */
+export async function findAvailablePort(reuseExisting = true): Promise<number> {
+    const isDev = !app.isPackaged
+
+    // Try to reuse cached port if requested and available
+    if (reuseExisting && allocatedPort !== null) {
+        const available = await isPortAvailable(allocatedPort)
+        if (available) {
+            return allocatedPort
+        }
+        console.warn(
+            `Previously allocated port ${allocatedPort} is no longer available`,
+        )
+        allocatedPort = null
+    }
+
+    if (isDev) {
+        // Development mode: use fixed port
+        const port = PORT_CONFIG.development
+        const available = await isPortAvailable(port)
+        if (available) {
+            allocatedPort = port
+            return port
+        }
+        console.warn(
+            `Development port ${port} is in use, finding alternative...`,
+        )
+    }
+
+    // Production mode or dev port unavailable: find random available port
+    for (let attempt = 0; attempt < PORT_CONFIG.maxAttempts; attempt++) {
+        const port = isDev
+            ? PORT_CONFIG.development + attempt + 1
+            : getRandomPort()
+
+        const available = await isPortAvailable(port)
+        if (available) {
+            allocatedPort = port
+            console.log(`Allocated port: ${port}`)
+            return port
+        }
+    }
+
+    throw new Error(
+        `Failed to find available port after ${PORT_CONFIG.maxAttempts} attempts`,
+    )
+}
+
+/**
+ * Get the currently allocated port
+ * Returns null if no port has been allocated yet
+ */
+export function getAllocatedPort(): number | null {
+    return allocatedPort
+}
+
+/**
+ * Reset the allocated port (useful for testing or restart scenarios)
+ */
+export function resetAllocatedPort(): void {
+    allocatedPort = null
+}
+
+/**
+ * Get the server URL with the allocated port
+ */
+export function getServerUrl(): string {
+    if (allocatedPort === null) {
+        throw new Error(
+            "No port allocated yet. Call findAvailablePort() first.",
+        )
+    }
+    return `http://localhost:${allocatedPort}`
+}