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>

scripts/afterPack.cjs

@@ -0,0 +1,39 @@
+/**
+ * electron-builder afterPack hook
+ * Copies node_modules to the standalone directory in the packaged app
+ */
+
+const { cpSync, existsSync } = require("fs")
+const path = require("path")
+
+module.exports = async function (context) {
+    const appOutDir = context.appOutDir
+    const resourcesDir = path.join(
+        appOutDir,
+        context.packager.platform.name === "mac"
+            ? `${context.packager.appInfo.productFilename}.app/Contents/Resources`
+            : "resources"
+    )
+    const standaloneDir = path.join(resourcesDir, "standalone")
+    const sourceNodeModules = path.join(
+        context.packager.projectDir,
+        "electron-standalone",
+        "node_modules"
+    )
+    const targetNodeModules = path.join(standaloneDir, "node_modules")
+
+    console.log(`[afterPack] Copying node_modules to ${targetNodeModules}`)
+
+    if (existsSync(sourceNodeModules) && existsSync(standaloneDir)) {
+        cpSync(sourceNodeModules, targetNodeModules, { recursive: true })
+        console.log("[afterPack] node_modules copied successfully")
+    } else {
+        console.error("[afterPack] Source or target directory not found!")
+        console.error(`  Source: ${sourceNodeModules} exists: ${existsSync(sourceNodeModules)}`)
+        console.error(`  Target dir: ${standaloneDir} exists: ${existsSync(standaloneDir)}`)
+        throw new Error(
+            "[afterPack] Failed: Required directories not found. " +
+            "Ensure 'npm run electron:prepare' was run before building."
+        )
+    }
+}

scripts/electron-dev.mjs

@@ -0,0 +1,275 @@
+#!/usr/bin/env node
+
+/**
+ * Development script for running Electron with Next.js
+ * 1. Reads preset configuration (if exists)
+ * 2. Starts Next.js dev server with preset env vars
+ * 3. Waits for it to be ready
+ * 4. Compiles Electron TypeScript
+ * 5. Launches Electron
+ * 6. Watches for preset changes and restarts Next.js
+ */
+
+import { spawn } from "node:child_process"
+import { fileURLToPath } from "node:url"
+import { existsSync, readFileSync, watch } from "node:fs"
+import path from "node:path"
+import os from "node:os"
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const rootDir = path.join(__dirname, "..")
+
+const NEXT_PORT = 6002
+const NEXT_URL = `http://localhost:${NEXT_PORT}`
+
+/**
+ * Get the user data path (same as Electron's app.getPath("userData"))
+ */
+function getUserDataPath() {
+    const appName = "next-ai-draw-io"
+    switch (process.platform) {
+        case "darwin":
+            return path.join(os.homedir(), "Library", "Application Support", appName)
+        case "win32":
+            return path.join(process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming"), appName)
+        default:
+            return path.join(os.homedir(), ".config", appName)
+    }
+}
+
+/**
+ * Load preset configuration from config file
+ */
+function loadPresetConfig() {
+    const configPath = path.join(getUserDataPath(), "config-presets.json")
+
+    if (!existsSync(configPath)) {
+        console.log("📋 No preset configuration found, using .env.local")
+        return null
+    }
+
+    try {
+        const content = readFileSync(configPath, "utf-8")
+        const data = JSON.parse(content)
+
+        if (!data.currentPresetId) {
+            console.log("📋 No active preset, using .env.local")
+            return null
+        }
+
+        const preset = data.presets.find(p => p.id === data.currentPresetId)
+        if (!preset) {
+            console.log("📋 Active preset not found, using .env.local")
+            return null
+        }
+
+        console.log(`📋 Using preset: "${preset.name}"`)
+        return preset.config
+    } catch (error) {
+        console.error("Failed to load preset config:", error.message)
+        return null
+    }
+}
+
+/**
+ * Wait for the Next.js server to be ready
+ */
+async function waitForServer(url, timeout = 120000) {
+    const start = Date.now()
+    console.log(`Waiting for server at ${url}...`)
+
+    while (Date.now() - start < timeout) {
+        try {
+            const response = await fetch(url)
+            if (response.ok || response.status < 500) {
+                console.log("Server is ready!")
+                return true
+            }
+        } catch {
+            // Server not ready yet
+        }
+        await new Promise((r) => setTimeout(r, 500))
+        process.stdout.write(".")
+    }
+
+    throw new Error(`Timeout waiting for server at ${url}`)
+}
+
+/**
+ * Run a command and wait for it to complete
+ */
+function runCommand(command, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn(command, args, {
+            cwd: rootDir,
+            stdio: "inherit",
+            shell: true,
+            ...options,
+        })
+
+        proc.on("close", (code) => {
+            if (code === 0) {
+                resolve()
+            } else {
+                reject(new Error(`Command failed with code ${code}`))
+            }
+        })
+
+        proc.on("error", reject)
+    })
+}
+
+/**
+ * Start Next.js dev server with preset environment
+ */
+function startNextServer(presetEnv) {
+    const env = { ...process.env }
+
+    // Apply preset environment variables
+    if (presetEnv) {
+        for (const [key, value] of Object.entries(presetEnv)) {
+            if (value !== undefined && value !== "") {
+                env[key] = value
+            }
+        }
+    }
+
+    const nextProcess = spawn("npm", ["run", "dev"], {
+        cwd: rootDir,
+        stdio: "inherit",
+        shell: true,
+        env,
+    })
+
+    nextProcess.on("error", (err) => {
+        console.error("Failed to start Next.js:", err)
+    })
+
+    return nextProcess
+}
+
+/**
+ * Main entry point
+ */
+async function main() {
+    console.log("🚀 Starting Electron development environment...\n")
+
+    // Load preset configuration
+    const presetEnv = loadPresetConfig()
+
+    // Start Next.js dev server with preset env
+    console.log("1. Starting Next.js development server...")
+    let nextProcess = startNextServer(presetEnv)
+
+    // Wait for Next.js to be ready
+    try {
+        await waitForServer(NEXT_URL)
+        console.log("")
+    } catch (err) {
+        console.error("\n❌ Next.js server failed to start:", err.message)
+        nextProcess.kill()
+        process.exit(1)
+    }
+
+    // Compile Electron TypeScript
+    console.log("\n2. Compiling Electron code...")
+    try {
+        await runCommand("npm", ["run", "electron:compile"])
+    } catch (err) {
+        console.error("❌ Electron compilation failed:", err.message)
+        nextProcess.kill()
+        process.exit(1)
+    }
+
+    // Start Electron
+    console.log("\n3. Starting Electron...")
+    const electronProcess = spawn("npm", ["run", "electron:start"], {
+        cwd: rootDir,
+        stdio: "inherit",
+        shell: true,
+        env: {
+            ...process.env,
+            NODE_ENV: "development",
+            ELECTRON_DEV_URL: NEXT_URL,
+        },
+    })
+
+    // Watch for preset config changes
+    const configPath = path.join(getUserDataPath(), "config-presets.json")
+    let configWatcher = null
+    let restartPending = false
+
+    function setupConfigWatcher() {
+        if (!existsSync(path.dirname(configPath))) {
+            // Directory doesn't exist yet, check again later
+            setTimeout(setupConfigWatcher, 5000)
+            return
+        }
+
+        try {
+            configWatcher = watch(configPath, { persistent: false }, async (eventType) => {
+                if (eventType === "change" && !restartPending) {
+                    restartPending = true
+                    console.log("\n🔄 Preset configuration changed, restarting Next.js server...")
+
+                    // Kill current Next.js process
+                    nextProcess.kill()
+
+                    // Wait a bit for process to die
+                    await new Promise(r => setTimeout(r, 1000))
+
+                    // Reload preset and restart
+                    const newPresetEnv = loadPresetConfig()
+                    nextProcess = startNextServer(newPresetEnv)
+
+                    try {
+                        await waitForServer(NEXT_URL)
+                        console.log("✅ Next.js server restarted with new configuration\n")
+                    } catch (err) {
+                        console.error("❌ Failed to restart Next.js:", err.message)
+                    }
+
+                    restartPending = false
+                }
+            })
+            console.log("👀 Watching for preset configuration changes...")
+        } catch (err) {
+            // File might not exist yet, that's ok
+            setTimeout(setupConfigWatcher, 5000)
+        }
+    }
+
+    // Start watching after a delay (config file might not exist yet)
+    setTimeout(setupConfigWatcher, 2000)
+
+    electronProcess.on("close", (code) => {
+        console.log(`\nElectron exited with code ${code}`)
+        if (configWatcher) configWatcher.close()
+        nextProcess.kill()
+        process.exit(code || 0)
+    })
+
+    electronProcess.on("error", (err) => {
+        console.error("Electron error:", err)
+        if (configWatcher) configWatcher.close()
+        nextProcess.kill()
+        process.exit(1)
+    })
+
+    // Handle termination signals
+    const cleanup = () => {
+        console.log("\n🛑 Shutting down...")
+        if (configWatcher) configWatcher.close()
+        electronProcess.kill()
+        nextProcess.kill()
+        process.exit(0)
+    }
+
+    process.on("SIGINT", cleanup)
+    process.on("SIGTERM", cleanup)
+}
+
+main().catch((err) => {
+    console.error("Fatal error:", err)
+    process.exit(1)
+})

scripts/prepare-electron-build.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+/**
+ * Prepare standalone directory for Electron packaging
+ * Copies the Next.js standalone output to a temp directory
+ * that electron-builder can properly include
+ */
+
+import { cpSync, rmSync, existsSync, mkdirSync } from "node:fs"
+import { join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url))
+const rootDir = join(__dirname, "..")
+
+const standaloneDir = join(rootDir, ".next", "standalone")
+const staticDir = join(rootDir, ".next", "static")
+const targetDir = join(rootDir, "electron-standalone")
+
+console.log("Preparing Electron build...")
+
+// Clean target directory
+if (existsSync(targetDir)) {
+    console.log("Cleaning previous build...")
+    rmSync(targetDir, { recursive: true })
+}
+
+// Create target directory
+mkdirSync(targetDir, { recursive: true })
+
+// Copy standalone (includes node_modules)
+console.log("Copying standalone directory...")
+cpSync(standaloneDir, targetDir, { recursive: true })
+
+// Copy static files
+console.log("Copying static files...")
+const targetStaticDir = join(targetDir, ".next", "static")
+mkdirSync(targetStaticDir, { recursive: true })
+cpSync(staticDir, targetStaticDir, { recursive: true })
+
+console.log("Done! Files prepared in electron-standalone/")