Bug fixes: stable sentinel, quoted .env parser, Python version gate, ffmpeg check, dedupe first-run

Author: TechyCSR

main.js

@@ -1,5 +1,6 @@
 require("dotenv").config();
 
+const path = require("path");
 const { app, BrowserWindow, globalShortcut, session, ipcMain } = require("electron");
 
 // ── Linux GPU process crash workaround ──
@@ -58,7 +59,10 @@ class ApplicationController {
     // a settings-window prompt on first launch so users don't have to
     // dig through docs to figure out they need a Gemini API key.
     this.firstRunManager = new FirstRunManager({
-      logger: logger
+      logger: logger,
+      // Sentinel lives in userData so it survives cwd changes
+      // (the app may be launched from any directory).
+      sentinelPath: path.join(app.getPath("userData"), ".opencluely-firstrun-completed"),
     });
     // Lazily-initialised in getWhisperInstaller() so tests can mock
     // the constructor without polluting main-process startup.
@@ -166,10 +170,21 @@ class ApplicationController {
       // Small delay to ensure desktop/space detection is accurate
       await new Promise((resolve) => setTimeout(resolve, 200));
 
-      // During first-run onboarding, defer showing the main overlay
-      // window until the wizard finishes (it needs API keys to function).
-      const status = this.firstRunManager.getStatus();
+      // First-run onboarding: ensure .env exists and read status once
+      // so we can decide whether to defer showing the main overlay.
+      let status;
+      try {
+        this.firstRunManager.ensureEnv();
+        status = this.firstRunManager.getStatus();
+        this.isFirstRun = status.needsOnboarding;
+        logger.info("First-run status", status);
+      } catch (e) {
+        logger.warn("First-run check failed", { error: e.message });
+        status = { needsOnboarding: false };
+        this.isFirstRun = false;
+      }
       const isFirstRun = status.needsOnboarding;
+
       await windowManager.initializeWindows({ showMainWindow: !isFirstRun });
       this.setupGlobalShortcuts();
 
@@ -179,36 +194,26 @@ class ApplicationController {
       this.starting = false;
       this.isReady = true;
 
-      // First-run onboarding: ensure .env exists and launch the
-      // multi-step onboarding wizard if the user hasn't completed it.
-      // Non-blocking — failure here just logs.
-      try {
-        this.firstRunManager.ensureEnv();
-        const status = this.firstRunManager.getStatus();
-        this.isFirstRun = status.needsOnboarding;
-        logger.info("First-run status", status);
-        if (this.isFirstRun) {
-          // Defer slightly so all windows finish loading before we pop
-          // the wizard on top of them.
-          setTimeout(() => {
-            try {
-              windowManager.showOnboarding();
-              windowManager.broadcastToAllWindows("first-run", status);
-              logger.info("First-run onboarding: wizard opened");
-            } catch (e) {
-              logger.warn("Could not open first-run onboarding window", {
-                error: e.message
-              });
-              // Fallback to legacy settings prompt
-              try { this.showSettings(); } catch (_) { /* ignore */ }
-            }
-          }, 800);
-        } else {
-          // Already configured — mark completed so we never nag again.
-          this.firstRunManager.markCompleted();
-        }
-      } catch (e) {
-        logger.warn("First-run check failed", { error: e.message });
+      // Launch the onboarding wizard if this is the first run.
+      if (this.isFirstRun) {
+        // Defer slightly so all windows finish loading before we pop
+        // the wizard on top of them.
+        setTimeout(() => {
+          try {
+            windowManager.showOnboarding();
+            windowManager.broadcastToAllWindows("first-run", status);
+            logger.info("First-run onboarding: wizard opened");
+          } catch (e) {
+            logger.warn("Could not open first-run onboarding window", {
+              error: e.message
+            });
+            // Fallback to legacy settings prompt
+            try { this.showSettings(); } catch (_) { /* ignore */ }
+          }
+        }, 800);
+      } else {
+        // Already configured — mark completed so we never nag again.
+        this.firstRunManager.markCompleted();
       }
 
       logger.info("Application initialized successfully", {

src/core/first-run.js

@@ -94,13 +94,29 @@ class FirstRunManager {
     try {
       const content = fs.readFileSync(this.envPath, 'utf8');
       const result = {};
-      for (const line of content.split(/\r?\n/)) {
-        const trimmed = line.trim();
-        if (!trimmed || trimmed.startsWith('#')) continue;
-        const eq = trimmed.indexOf('=');
+      for (const rawLine of content.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#')) continue;
+        const eq = line.indexOf('=');
         if (eq === -1) continue;
-        const key = trimmed.slice(0, eq).trim();
-        const value = trimmed.slice(eq + 1).trim();
+        const key = line.slice(0, eq).trim();
+        let value = line.slice(eq + 1).trim();
+
+        // If the value is quoted, find the matching closing quote and
+        // take everything between. Anything after the closing quote is
+        // treated as trailing whitespace/comment.
+        if (value.startsWith('"') || value.startsWith("'")) {
+          const quote = value[0];
+          const closeIdx = value.indexOf(quote, 1);
+          if (closeIdx !== -1) {
+            value = value.slice(1, closeIdx);
+          }
+        } else {
+          // Unquoted: strip trailing inline comment (a " #" sequence).
+          const hashIdx = value.indexOf(' #');
+          if (hashIdx !== -1) value = value.slice(0, hashIdx).trim();
+        }
+
         result[key] = value;
       }
       return result;

src/core/whisper-installer.js

@@ -230,6 +230,22 @@ class WhisperInstaller {
     }
     log(`✓ Found Python: ${python}`);
 
+    // openai-whisper requires Python 3.9+ (3.10+ recommended for best
+    // performance). Catch version mismatch BEFORE attempting pip
+    // install — the pip error is cryptic and confusing.
+    const version = await this._getPythonVersion(python);
+    if (!version) {
+      log('! Could not determine Python version');
+      return { ok: false, command: null, message: 'Could not determine Python version', logs: '' };
+    }
+    log(`→ Python version: ${version}`);
+    if (!this._isPythonVersionOk(version)) {
+      const msg = `Python ${version} is too old. openai-whisper requires Python 3.9 or newer. Please upgrade Python and retry.`;
+      log(`! ${msg}`);
+      return { ok: false, command: null, message: msg, logs: msg };
+    }
+    log('✓ Python version OK');
+
     const vp = this.venvPaths;
     const venvExists = fs.existsSync(vp.python);
 
@@ -286,6 +302,21 @@ class WhisperInstaller {
       return { ok: false, command: null, message: msg, logs: msg };
     }
 
+    // Check for ffmpeg — whisper needs it for any non-WAV audio.
+    // We log a warning but don't fail; user can install it later.
+    const ffmpeg = await this._probeFfmpeg();
+    if (ffmpeg.found) {
+      log(`✓ ffmpeg detected (${ffmpeg.path})`);
+    } else {
+      const ffmpegMsg = this.platform === 'win32'
+        ? 'ffmpeg not found — install with `winget install ffmpeg` or download from gyan.dev. Required for non-WAV audio.'
+        : this.platform === 'darwin'
+          ? 'ffmpeg not found — install with `brew install ffmpeg`. Required for non-WAV audio.'
+          : 'ffmpeg not found — install with `sudo apt install ffmpeg` (Debian/Ubuntu). Required for non-WAV audio.';
+      log(`! ${ffmpegMsg}`);
+      log('  (Whisper will work for WAV files; install ffmpeg later for other formats)');
+    }
+
     const commandStr = `${vp.python} -m whisper`;
     log(`✓ Whisper CLI ready: ${commandStr} (v${verify.version || '?'})`);
 
@@ -294,9 +325,29 @@ class WhisperInstaller {
       command: commandStr,
       message: `Installed Whisper v${verify.version || '?'} into ${this.venvPath}`,
       logs: pipResult.stdout,
+      ffmpegDetected: ffmpeg.found,
     };
   }
 
+  /**
+   * Probe for ffmpeg on PATH. Returns { found, path }.
+   */
+  async _probeFfmpeg() {
+    try {
+      const { spawnSync } = require('child_process');
+      const r = spawnSync(
+        this.platform === 'win32' ? 'where' : 'which',
+        ['ffmpeg'],
+        { windowsHide: true },
+      );
+      if (r.status === 0) {
+        const path = (r.stdout || '').toString().split(/\r?\n/)[0].trim();
+        return { found: true, path };
+      }
+    } catch (_) { /* ignore */ }
+    return { found: false, path: null };
+  }
+
   /**
    * Short platform-tailored hints to show the user in the wizard.
    */
@@ -427,6 +478,33 @@ class WhisperInstaller {
     }
     return null;
   }
+
+  /**
+   * Resolve Python's `--version` string into a `major.minor` tuple
+   * (e.g. '3.11'). Returns null if it can't be determined.
+   */
+  async _getPythonVersion(pythonCmd) {
+    const r = await this.runExec(pythonCmd, ['-c', 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")'], {
+      timeout: 10000,
+    });
+    if (!r.ok) return null;
+    const m = (r.stdout || '').trim().match(/^(\d+)\.(\d+)/);
+    return m ? `${m[1]}.${m[2]}` : null;
+  }
+
+  /**
+   * openai-whisper requires Python 3.9+. We warn below 3.10 and refuse
+   * below 3.9. Returns false if the version is too old.
+   */
+  _isPythonVersionOk(version) {
+    const m = (version || '').match(/^(\d+)\.(\d+)/);
+    if (!m) return false;
+    const major = parseInt(m[1], 10);
+    const minor = parseInt(m[2], 10);
+    if (major > 3) return true;
+    if (major === 3 && minor >= 9) return true;
+    return false;
+  }
 }
 
 module.exports = WhisperInstaller;