feat(desktop): log server output and show a diagnostic page on startup failure

The shell previously discarded the sidecar server's stdout/stderr, so a
failed startup on a user machine (e.g. the Windows report in #174) left
nothing to debug. Now a packaged build writes everything the server
prints to server.log in the data dir, interleaved with launcher
lifecycle lines stamped with seconds since launch; the previous log is
kept as server.log.old.

When the server dies or never spawns, the launcher bails out
immediately instead of waiting the full 90 s, and the window opens on a
built-in diagnostic page that explains the failure, shows the log path
to attach to a bug report, and offers a retry. The launcher keeps
polling behind the page and loads the app the moment the server becomes
reachable, so slow first launches (antivirus scanning a fresh install)
self-heal.

Paths handed to the sidecar now go through dunce, stripping the
Windows \\?\ extended-length prefix Tauri's resource resolver can
produce, which not every Node library tolerates.

Refs #174

Author: ApocDev

app/src-tauri/Cargo.lock

@@ -21,6 +21,10 @@ tauri-build = { version = "2.6.3", features = [] }
 serde_json = "1.0"
 serde = { version = "1.0", features = ["derive"] }
 log = "0.4"
+# the diagnostic page is an inline data: URL
+base64 = "0.22"
+# strips Windows `\\?\` extended-length prefixes off paths passed to the sidecar
+dunce = "1"
 # `devtools` enables right-click → Inspect in release too — useful while the desktop
 # shell is young (e.g. to see updater/ACL errors from the webview console).
 tauri = { version = "2.11.3", features = ["devtools"] }

app/src-tauri/Cargo.toml

@@ -1,3 +1,3 @@
 fn main() {
-  tauri_build::build()
+    tauri_build::build()
 }

app/src-tauri/build.rs

@@ -4,14 +4,33 @@
 //            for it and open the window.
 //   - bundle: we start the server ourselves via the vendored `node` sidecar against
 //            the bundled `.output`, with the data/migrations/mod dirs passed in.
+//            Everything the server prints (plus launcher lifecycle lines) goes to
+//            `server.log` in the data dir, so a failed startup on a user's machine
+//            is debuggable from the one file the diagnostic page points at.
 use std::net::TcpStream;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
 use std::time::{Duration, Instant};
 
+use base64::engine::general_purpose::STANDARD as BASE64;
+use base64::Engine as _;
 use tauri::webview::PageLoadEvent;
 use tauri::{Manager, RunEvent, WebviewUrl, WebviewWindowBuilder};
 use tauri_plugin_opener::OpenerExt;
 use tauri_plugin_window_state::{StateFlags, WindowExt};
 
+#[cfg(not(debug_assertions))]
+use std::io::Write as _;
+#[cfg(not(debug_assertions))]
+use std::sync::Mutex;
+#[cfg(not(debug_assertions))]
+use tauri::path::BaseDirectory;
+#[cfg(not(debug_assertions))]
+use tauri_plugin_shell::{
+    process::{CommandChild, CommandEvent},
+    ShellExt,
+};
+
 // External `<a>` clicks (incl. target=_blank, which on_navigation alone misses)
 // become a same-frame navigation, which the on_navigation hook cancels and hands to
 // the system browser — so links like the GitHub button open in the user's browser
@@ -26,35 +45,98 @@ window.addEventListener('click', function (e) {
 }, true);
 "#;
 
-use std::sync::Mutex;
-#[cfg(not(debug_assertions))]
-use tauri::path::BaseDirectory;
-#[cfg(not(debug_assertions))]
-use tauri_plugin_shell::{process::CommandChild, ShellExt};
-
 const PORT: u16 = 34115;
 
 /// Holds the sidecar server process so it can be killed when the app exits.
 #[cfg(not(debug_assertions))]
 struct ServerChild(Mutex<Option<CommandChild>>);
 
-/// Block until something accepts connections on the port, or time out.
-fn wait_for_port(port: u16, timeout: Duration) -> bool {
-    let start = Instant::now();
-    while start.elapsed() < timeout {
-        if TcpStream::connect(("127.0.0.1", port)).is_ok() {
-            return true;
+/// `server.log` in the data dir: launcher lifecycle lines (stamped with seconds
+/// since launch) interleaved with the server's own stdout/stderr, verbatim. One log
+/// per launch — the previous one is kept as `server.log.old`. This file exists so
+/// user bug reports are debuggable without a terminal, so it must never take the app
+/// down with it: a failed create just disables logging.
+#[cfg(not(debug_assertions))]
+#[derive(Clone)]
+struct ServerLog {
+    file: Arc<Mutex<Option<std::fs::File>>>,
+    start: Instant,
+}
+
+#[cfg(not(debug_assertions))]
+impl ServerLog {
+    fn create(dir: &std::path::Path) -> (Self, std::path::PathBuf) {
+        let path = dir.join("server.log");
+        let _ = std::fs::rename(&path, dir.join("server.log.old"));
+        let log = Self {
+            file: Arc::new(Mutex::new(std::fs::File::create(&path).ok())),
+            start: Instant::now(),
+        };
+        (log, path)
+    }
+
+    /// One line of the server's own output, verbatim.
+    fn output(&self, line: &[u8]) {
+        if let Some(f) = self.file.lock().unwrap().as_mut() {
+            let _ = f.write_all(line);
+            let _ = f.write_all(b"\n");
         }
-        std::thread::sleep(Duration::from_millis(150));
     }
-    false
+
+    /// A launcher-side lifecycle line.
+    fn line(&self, msg: &str) {
+        let t = self.start.elapsed().as_secs_f32();
+        if let Some(f) = self.file.lock().unwrap().as_mut() {
+            let _ = writeln!(f, "[launcher +{t:.1}s] {msg}");
+        }
+    }
+}
+
+/// The page shown when the local server didn't come up in time: says what happened
+/// in user terms and points at the log file to attach to a bug report. The launcher
+/// keeps polling the port behind it and swaps in the app the moment the server is
+/// reachable (first launches can be slow — e.g. antivirus scanning the fresh
+/// install), so the page also self-heals.
+fn error_page_url(log_path: Option<&str>) -> String {
+    let escape = |s: &str| {
+        s.replace('&', "&amp;")
+            .replace('<', "&lt;")
+            .replace('>', "&gt;")
+    };
+    let diagnostics = match log_path {
+        Some(p) => format!(
+            "<p>If it keeps failing, this log file records what the server said — \
+             please attach it to a bug report:</p><p><code>{}</code></p>",
+            escape(p)
+        ),
+        None => "<p>Check the terminal running the dev server for errors.</p>".to_string(),
+    };
+    let html = format!(
+        r#"<!doctype html><html><head><meta charset="utf-8"><title>PyOps</title><style>
+:root{{color-scheme:dark}}
+body{{margin:0;display:flex;min-height:100vh;align-items:center;justify-content:center;background:#111418;color:#e6e6e6;font:15px/1.55 system-ui,sans-serif}}
+main{{max-width:36rem;padding:2rem}}
+h1{{font-size:1.15rem;margin:0 0 .75rem}}
+p{{margin:.5rem 0;color:#b6bcc4}}
+code{{user-select:all;background:#1c2127;padding:.15rem .4rem;font-size:.85em;word-break:break-all}}
+button{{margin-top:1rem;background:#2563eb;border:0;color:#fff;font:inherit;padding:.5rem 1rem;cursor:pointer}}
+</style></head><body><main>
+<h1>PyOps couldn't reach its local server</h1>
+<p>The app runs a local server in the background, and it hasn't come up yet. This
+window keeps checking and loads the app automatically the moment the server is
+reachable — on a first launch that can take a while.</p>
+<p>If nothing happens for a few minutes, close the app and start it again.</p>
+{diagnostics}
+<button onclick="window.location.replace('http://localhost:{PORT}')">Retry now</button>
+</main></body></html>"#
+    );
+    format!("data:text/html;base64,{}", BASE64.encode(html))
 }
 
-/// Open the main window (hidden) pointed at the local server, revealing it only once
-/// the first page has painted — so the user never sees a blank webview while the
-/// server boots / server-renders.
-fn open_main_window(app: &tauri::AppHandle) {
-    let url = format!("http://localhost:{PORT}");
+/// Open the app window (label "main") at `url`. Normally hidden until the first page
+/// has painted — so the user never sees a blank webview while the server
+/// server-renders — but the diagnostic page opens visible immediately.
+fn open_window(app: &tauri::AppHandle, url: String, visible: bool) {
     // First-run size, wide enough for the desktop nav even with fractional display
     // scaling (the inline bar collapses to a hamburger below 1400 CSS px, and a 1.25x
     // scale makes the CSS viewport ~physical/1.25; the Deck's ~1280 intentionally
@@ -66,7 +148,7 @@ fn open_main_window(app: &tauri::AppHandle) {
         .title(title)
         .inner_size(1800.0, 1100.0)
         .min_inner_size(900.0, 600.0)
-        .visible(false)
+        .visible(visible)
         .initialization_script(EXTERNAL_LINKS_SCRIPT)
         .on_navigation(move |url| {
             // Stay on the local server; send any other web link to the system browser.
@@ -136,42 +218,137 @@ pub fn run() {
                 )?;
             }
 
+            // Set when the server process dies (or never spawns) — lets the port
+            // wait below bail out immediately instead of sitting through the full
+            // timeout on a server that will never come up.
+            let server_exited = Arc::new(AtomicBool::new(false));
+            #[cfg(debug_assertions)]
+            let log_path: Option<String> = None;
+
             // Bundled build: start the server via the vendored node sidecar. The data
             // dir is the per-OS app-data dir; migrations + mod source are bundled
             // resources. (In dev the server is already up from beforeDevCommand.)
             #[cfg(not(debug_assertions))]
-            {
-                let server_entry =
-                    app.path().resolve("output/server/index.mjs", BaseDirectory::Resource)?;
-                let drizzle = app.path().resolve("drizzle", BaseDirectory::Resource)?;
-                let mod_dir = app.path().resolve("mod", BaseDirectory::Resource)?;
-                let data_dir = app.path().app_data_dir()?;
+            let (server_log, log_path) = {
+                // Tauri can resolve resources to `\\?\C:\…` extended-length paths on
+                // Windows; Node itself copes, but not every library does — pass the
+                // plain form to the sidecar.
+                let server_entry = dunce::simplified(
+                    &app.path()
+                        .resolve("output/server/index.mjs", BaseDirectory::Resource)?,
+                )
+                .to_path_buf();
+                let drizzle =
+                    dunce::simplified(&app.path().resolve("drizzle", BaseDirectory::Resource)?)
+                        .to_path_buf();
+                let mod_dir =
+                    dunce::simplified(&app.path().resolve("mod", BaseDirectory::Resource)?)
+                        .to_path_buf();
+                let data_dir = dunce::simplified(&app.path().app_data_dir()?).to_path_buf();
                 std::fs::create_dir_all(&data_dir).ok();
 
-                let (mut rx, child) = app
-                    .shell()
-                    .sidecar("node")?
-                    .arg(server_entry.to_string_lossy().to_string())
-                    .env("PORT", PORT.to_string())
-                    .env("HOST", "127.0.0.1")
-                    .env("PYOPS_DATA_DIR", data_dir.to_string_lossy().to_string())
-                    .env("PYOPS_MIGRATIONS_DIR", drizzle.to_string_lossy().to_string())
-                    .env("PYOPS_MOD_DIR", mod_dir.to_string_lossy().to_string())
-                    .spawn()?;
-                app.manage(ServerChild(Mutex::new(Some(child))));
-                // keep the pipe drained so the child never blocks on a full stdout
-                tauri::async_runtime::spawn(async move { while rx.recv().await.is_some() {} });
-            }
+                let (server_log, log_file) = ServerLog::create(&data_dir);
+                server_log.line(&format!(
+                    "PyOps v{} launching server",
+                    app.package_info().version
+                ));
+                server_log.line(&format!("entry: {}", server_entry.display()));
+                server_log.line(&format!("data dir: {}", data_dir.display()));
+
+                let spawned = app.shell().sidecar("node").and_then(|cmd| {
+                    cmd.arg(server_entry.to_string_lossy().to_string())
+                        .env("PORT", PORT.to_string())
+                        .env("HOST", "127.0.0.1")
+                        .env("PYOPS_DATA_DIR", data_dir.to_string_lossy().to_string())
+                        .env(
+                            "PYOPS_MIGRATIONS_DIR",
+                            drizzle.to_string_lossy().to_string(),
+                        )
+                        .env("PYOPS_MOD_DIR", mod_dir.to_string_lossy().to_string())
+                        .spawn()
+                });
+                match spawned {
+                    Ok((mut rx, child)) => {
+                        app.manage(ServerChild(Mutex::new(Some(child))));
+                        let log = server_log.clone();
+                        let exited = server_exited.clone();
+                        tauri::async_runtime::spawn(async move {
+                            while let Some(event) = rx.recv().await {
+                                match event {
+                                    CommandEvent::Stdout(line) | CommandEvent::Stderr(line) => {
+                                        log.output(&line)
+                                    }
+                                    CommandEvent::Error(e) => {
+                                        log.line(&format!("server process error: {e}"))
+                                    }
+                                    CommandEvent::Terminated(p) => {
+                                        log.line(&format!(
+                                            "server exited (code {:?}, signal {:?})",
+                                            p.code, p.signal
+                                        ));
+                                        exited.store(true, Ordering::Relaxed);
+                                    }
+                                    _ => {}
+                                }
+                            }
+                        });
+                    }
+                    Err(e) => {
+                        server_log.line(&format!("failed to spawn the server: {e}"));
+                        server_exited.store(true, Ordering::Relaxed);
+                    }
+                }
+                (server_log, Some(log_file.display().to_string()))
+            };
 
             // The web UI drives the update via the updater/process plugins on launch
             // (guarded by window.isTauri), so nothing to spawn here.
 
-            // Wait for the server off the main thread, then open the window on it.
+            // Wait for the server off the main thread: open the app window when the
+            // port answers, or the diagnostic page if the server died / timed out.
+            // The page isn't a dead end — we keep polling and load the app the
+            // moment the server shows up late (slow first launches are real, e.g.
+            // antivirus scanning the fresh install).
             let handle = app.handle().clone();
+            let exited = server_exited.clone();
             std::thread::spawn(move || {
-                wait_for_port(PORT, Duration::from_secs(90));
+                let deadline = Instant::now() + Duration::from_secs(90);
+                let ready = loop {
+                    if TcpStream::connect(("127.0.0.1", PORT)).is_ok() {
+                        break true;
+                    }
+                    if exited.load(Ordering::Relaxed) || Instant::now() >= deadline {
+                        break false;
+                    }
+                    std::thread::sleep(Duration::from_millis(150));
+                };
+                if ready {
+                    #[cfg(not(debug_assertions))]
+                    server_log.line("server ready, opening the app");
+                    let h = handle.clone();
+                    let _ = handle.run_on_main_thread(move || {
+                        open_window(&h, format!("http://localhost:{PORT}"), false)
+                    });
+                    return;
+                }
+                #[cfg(not(debug_assertions))]
+                server_log.line("server not reachable, showing the diagnostic page");
+                let url = error_page_url(log_path.as_deref());
                 let h = handle.clone();
-                let _ = handle.run_on_main_thread(move || open_main_window(&h));
+                let _ = handle.run_on_main_thread(move || open_window(&h, url, true));
+                loop {
+                    if TcpStream::connect(("127.0.0.1", PORT)).is_ok() {
+                        #[cfg(not(debug_assertions))]
+                        server_log.line("server came up late, loading the app");
+                        if let Some(w) = handle.get_webview_window("main") {
+                            let _ = w.eval(&format!(
+                                "window.location.replace('http://localhost:{PORT}')"
+                            ));
+                        }
+                        break;
+                    }
+                    std::thread::sleep(Duration::from_secs(1));
+                }
             });
 
             Ok(())

app/src-tauri/src/lib.rs

@@ -2,5 +2,5 @@
 #![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
 
 fn main() {
-  app_lib::run();
+    app_lib::run();
 }