feat: Add full WSL2/WSLg compatibility for Electron desktop app

.gitignore

@@ -170,4 +170,5 @@ OPUS_ANALYSIS_AND_IDEAS.md
 # Auto Claude generated files
 .security-key
 /shared_docs
-Agents.md
+Agents.md
+logs/security/

CHANGELOG.md

@@ -1,3 +1,91 @@
+## Unreleased - WSL2/WSLg Compatibility
+
+### ✨ New Platform Support
+
+- **Full WSL2/WSLg compatibility** - Auto Claude Electron desktop app now runs natively on Windows 11 WSL2 with WSLg (Windows Subsystem for Linux Graphics)
+
+- Added comprehensive WSL2 setup guide and troubleshooting documentation ([guides/WSL2_SETUP.md](guides/WSL2_SETUP.md))
+
+### 🛠️ Technical Improvements
+
+**Lazy Initialization Pattern:**
+- Implemented lazy initialization for all Electron app access to handle delayed initialization on WSL2
+- Replaced direct `@electron-toolkit/utils` usage with safe platform detection
+- Added Proxy-based lazy initialization for singleton services (ProjectStore, ChangelogService, TitleGenerator)
+
+**Sentry Integration:**
+- Fixed Sentry initialization timing with safe version detection and package.json fallback
+- Sentry now initializes before app.whenReady() while remaining WSL2-compatible
+- Temporarily disabled Sentry environment propagation to subprocesses for WSL2 compatibility
+
+**electron-log:**
+- Disabled preload script to avoid WSL2 path resolution issues
+- Main logging functionality preserved and working correctly
+
+**electron-updater:**
+- Implemented lazy loading pattern with module-level variable
+- Added null checks to all autoUpdater access functions
+- Changed `getCurrentVersion()` to use `app.getVersion()` instead of autoUpdater for better reliability
+
+**Settings Management:**
+- Fixed settings path resolution by using `getSettingsPath()` function calls instead of module-level constants
+
+**Build Configuration:**
+- Ensured CJS format with `.js` extensions for main and preload bundles
+- Fixed preload script path from `.mjs` to `.js` to match build output
+- Externalized Sentry packages to avoid bundling issues
+
+**Backend Path Detection:**
+- Added safe `app.getAppPath()` access with try-catch for WSL2 compatibility
+- Multiple fallback paths for backend detection
+
+### 🐛 Bug Fixes
+
+- Fixed "app.getVersion() is not a function" errors on WSL2 startup
+- Fixed "autoUpdater is not defined" errors when accessing update functions
+- Fixed "settingsPath is not defined" error in setup wizard
+- Fixed preload script "index.mjs" not found error
+- Fixed Sentry initialization timing error: "SDK should be initialized before app ready event"
+- Fixed electron-log preload script path resolution failures
+- Fixed module-level constant initialization issues on WSL2
+- Fixed singleton service initialization timing on WSL2
+
+### 📚 Documentation
+
+- Added [WSL2_SETUP.md](guides/WSL2_SETUP.md) with:
+  - Prerequisites and installation steps
+  - Step-by-step WSLg verification guide
+  - Comprehensive troubleshooting section
+  - Technical explanations of all fixes
+  - Architecture patterns for WSL2 compatibility
+  - Testing checklist for WSL2 development
+
+### 🔧 Files Changed
+
+**Main Process:**
+- `apps/frontend/src/main/index.ts` - Lazy platform detection, safe app initialization
+- `apps/frontend/src/main/sentry.ts` - Safe version detection with fallbacks
+- `apps/frontend/src/main/app-logger.ts` - Disabled preload for WSL2
+- `apps/frontend/src/main/app-updater.ts` - Lazy loading with null checks
+- `apps/frontend/src/main/project-store.ts` - Proxy-based lazy initialization
+- `apps/frontend/src/main/changelog/changelog-service.ts` - Proxy-based lazy initialization, safe path detection
+- `apps/frontend/src/main/title-generator.ts` - Proxy-based lazy initialization, safe path detection
+- `apps/frontend/src/main/env-utils.ts` - Disabled Sentry subprocess env for WSL2
+
+**IPC Handlers:**
+- `apps/frontend/src/main/ipc-handlers/settings-handlers.ts` - Function-based path resolution
+- `apps/frontend/src/main/ipc-handlers/context/utils.ts` - WSL2-safe path handling
+- `apps/frontend/src/main/ipc-handlers/project-handlers.ts` - WSL2-safe initialization
+
+**Build Configuration:**
+- `apps/frontend/electron.vite.config.ts` - CJS format, external dependencies
+- `apps/frontend/package.json` - Updated for WSL2 compatibility
+
+**Other:**
+- `.gitignore` - Added logs/security/ exclusion
+
+---
+
 ## 2.7.4 - Terminal & Workflow Enhancements
 
 ### ✨ New Features

apps/backend/agents/tools_pkg/tools/qa.py

@@ -12,7 +12,6 @@
 from typing import Any
 
 from core.file_utils import write_json_atomic
-from spec.validate_pkg.auto_fix import auto_fix_plan
 
 try:
     from claude_agent_sdk import tool
@@ -159,6 +158,9 @@ async def update_qa_status(args: dict[str, Any]) -> dict[str, Any]:
 
         except json.JSONDecodeError as e:
             # Attempt to auto-fix the plan and retry
+            # Lazy import to avoid circular dependency
+            from spec.validate_pkg.auto_fix import auto_fix_plan
+
             if auto_fix_plan(spec_dir):
                 # Retry after fix
                 try:

apps/backend/agents/tools_pkg/tools/subtask.py

@@ -12,7 +12,6 @@
 from typing import Any
 
 from core.file_utils import write_json_atomic
-from spec.validate_pkg.auto_fix import auto_fix_plan
 
 try:
     from claude_agent_sdk import tool
@@ -142,6 +141,9 @@ async def update_subtask_status(args: dict[str, Any]) -> dict[str, Any]:
 
         except json.JSONDecodeError as e:
             # Attempt to auto-fix the plan and retry
+            # Lazy import to avoid circular dependency
+            from spec.validate_pkg.auto_fix import auto_fix_plan
+
             if auto_fix_plan(spec_dir):
                 # Retry after fix
                 try:

apps/frontend/electron.vite.config.ts

@@ -20,31 +20,24 @@ const sentryDefines = {
 export default defineConfig({
   main: {
     define: sentryDefines,
-    plugins: [externalizeDepsPlugin({
-      // Bundle these packages into the main process (they won't be in node_modules in packaged app)
-      exclude: [
-        'uuid',
-        'chokidar',
-        'kuzu',
-        'electron-updater',
-        '@electron-toolkit/utils',
-        // Sentry and its transitive dependencies (opentelemetry -> debug -> ms)
-        '@sentry/electron',
-        '@sentry/core',
-        '@sentry/node',
-        '@sentry/utils',
-        '@opentelemetry/instrumentation',
-        'debug',
-        'ms'
-      ]
-    })],
+    plugins: [externalizeDepsPlugin()],
     build: {
       rollupOptions: {
         input: {
           index: resolve(__dirname, 'src/main/index.ts')
         },
-        // Only node-pty needs to be external (native module rebuilt by electron-builder)
-        external: ['@lydell/node-pty']
+        output: {
+          format: 'cjs',
+          entryFileNames: '[name].js'
+        },
+        // External modules that should not be bundled
+        external: [
+          '@lydell/node-pty', // Native module
+          '@sentry/electron',  // Sentry main (causes WSL2 issues when bundled)
+          '@sentry/core',
+          '@sentry/node',
+          '@electron-toolkit/utils' // Electron utilities (access app before ready)
+        ]
       }
     }
   },
@@ -54,6 +47,10 @@ export default defineConfig({
       rollupOptions: {
         input: {
           index: resolve(__dirname, 'src/preload/index.ts')
+        },
+        output: {
+          format: 'cjs',
+          entryFileNames: '[name].js'
         }
       }
     }

apps/frontend/package.json

@@ -18,10 +18,13 @@
     "node": ">=24.0.0",
     "npm": ">=10.0.0"
   },
+  "//": "NOTE: Use 'dev:wsl2' scripts for WSL2 environments. The --no-sandbox flag disables Chromium's sandbox security feature and should ONLY be used in WSL2. Regular 'dev' scripts are safe for macOS/Windows/Linux. Production builds never use --no-sandbox.",
   "scripts": {
     "postinstall": "node scripts/postinstall.cjs",
     "dev": "electron-vite dev",
     "dev:debug": "cross-env DEBUG=true electron-vite dev",
+    "dev:wsl2": "node scripts/check-wsl2.cjs && electron-vite dev -- --no-sandbox",
+    "dev:debug:wsl2": "node scripts/check-wsl2.cjs && cross-env DEBUG=true electron-vite dev -- --no-sandbox",
     "dev:mcp": "electron-vite dev -- --remote-debugging-port=9222",
     "build": "electron-vite build",
     "start": "electron .",

apps/frontend/scripts/check-wsl2.cjs

@@ -0,0 +1,78 @@
+/**
+ * WSL2 Detection Script
+ *
+ * Validates that the development environment is running in WSL2 before allowing
+ * --no-sandbox flag usage. This prevents accidental use of disabled Chromium
+ * sandbox outside of WSL2 environments where it's required.
+ *
+ * Usage: node scripts/check-wsl2.cjs
+ * Exit codes:
+ *   0 - Running in WSL2 (safe to use --no-sandbox)
+ *   1 - Not running in WSL2 (should not use --no-sandbox)
+ */
+
+const fs = require('fs');
+
+/**
+ * Check if running in WSL2 environment
+ * @returns {boolean} true if in WSL2, false otherwise
+ */
+function isWSL2() {
+  // Method 1: Check WSL_DISTRO_NAME environment variable
+  if (process.env.WSL_DISTRO_NAME) {
+    return true;
+  }
+
+  // Method 2: Check /proc/version for WSL2 signature (Linux only)
+  if (process.platform === 'linux') {
+    try {
+      const versionInfo = fs.readFileSync('/proc/version', 'utf8').toLowerCase();
+      // WSL2 typically contains 'microsoft' and 'wsl2' in kernel version
+      if (versionInfo.includes('microsoft') && versionInfo.includes('wsl2')) {
+        return true;
+      }
+      // Older WSL2 versions might only have 'microsoft'
+      if (versionInfo.includes('microsoft')) {
+        return true;
+      }
+    } catch {
+      // /proc/version doesn't exist or can't be read
+      return false;
+    }
+  }
+
+  // Method 3: Check for WSL interop (wsl.exe in PATH)
+  if (process.platform === 'linux') {
+    try {
+      const { execSync } = require('child_process');
+      execSync('which wsl.exe', { stdio: 'ignore' });
+      return true;
+    } catch {
+      // wsl.exe not found
+    }
+  }
+
+  return false;
+}
+
+// Main execution
+const isWsl2 = isWSL2();
+
+if (isWsl2) {
+  console.log('✓ WSL2 environment detected - --no-sandbox flag is safe to use');
+  process.exit(0);
+} else {
+  console.error('✗ Not running in WSL2!');
+  console.error('');
+  console.error('The dev:wsl2 script is designed for WSL2 environments only.');
+  console.error('It disables Chromium sandbox (--no-sandbox) which is a security risk outside WSL2.');
+  console.error('');
+  console.error('Please use one of these alternatives:');
+  console.error('  • npm run dev        - Development mode with Chromium sandbox enabled');
+  console.error('  • npm run dev:debug  - Debug mode with Chromium sandbox enabled');
+  console.error('');
+  console.error('If you are in WSL2 but seeing this error, check:');
+  console.error('  1. WSL_DISTRO_NAME environment variable is set');
+  console.error('  2. Running WSL2 (not WSL1): wsl.exe --list --verbose');
+  process.exit(1);
+}

apps/frontend/src/main/app-logger.ts

@@ -22,7 +22,7 @@ import os from 'os';
 
 // Configure electron-log (wrapped in try-catch for re-import scenarios in tests)
 try {
-  log.initialize();
+  log.initialize({ preload: false }); // Disable preload to avoid WSL2 path issues
 } catch {
   // Already initialized, ignore
 }
@@ -42,15 +42,19 @@ log.transports.console.format = '[{h}:{i}:{s}] [{level}] {text}';
 // Determine if this is a beta version
 function isBetaVersion(): boolean {
   try {
+    // WSL2 compatibility: app may not be ready yet at module load time
+    if (!app || typeof app.getVersion !== 'function') {
+      return false;
+    }
     const version = app.getVersion();
     return version.includes('-beta') || version.includes('-alpha') || version.includes('-rc');
   } catch (error) {
-    log.warn('Failed to detect beta version:', error);
+    // Silently fail if app is not ready yet - this is called at module load time
     return false;
   }
 }
 
-// Enhanced logging for beta versions
+// Enhanced logging for beta versions (lazy check - safe for WSL2)
 if (isBetaVersion()) {
   log.transports.file.level = 'debug';
   log.info('Beta version detected - enhanced logging enabled');