@evandu/super-pi 0.1.113 → 0.1.114

package/README.md

@@ -56,6 +56,22 @@ super-pi stop    # Stop the background server
 super-pi restart # Restart the server
 ```
 
+If the panel suddenly stops working and the browser only says "connecting", the server may have
+died. Its log says why:
+
+```bash
+super-pi logs          # The last 200 lines of the server log
+super-pi logs 50       # The last 50 lines
+super-pi logs --follow # Keep printing new lines (Ctrl+C to stop)
+super-pi logs --path   # Where the log file is
+super-pi logs --clear  # Empty the log file
+```
+
+The log lives in `<data directory>/logs/server.log` (`super-pi logs --path` prints the exact path;
+`SUPER_PI_DATA_DIR` moves the whole data directory). A separate `logs/heartbeat.txt` is touched
+every minute while the server lives, so `super-pi logs` can also tell you when the server was last
+alive - which is how a crash that left no message at all still gets a time on it.
+
 To start Super Pi automatically when the current user signs in, run:
 
 ```bash

package/bin/super-pi.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { execFile, spawn } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync, openSync, readSync, closeSync, truncateSync } from "node:fs";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
@@ -38,7 +38,7 @@ function ownVersion() {
 /** The line that names what is running, so two installations can be told apart at a glance. */
 function runningBanner(url) {
   const { version, location } = ownVersion();
-  return `Super Pi v${version} is running at ${url}\n  installed at ${location}`;
+  return `Super Pi v${version} is running at ${url}\n  installed at ${location}\n  log file: ${logFile()}`;
 }
 
 function options(args) {
@@ -63,7 +63,75 @@ async function running(port) {
 }
 async function stop(port) { try { const headers = process.env.SUPER_PI_ACCESS_TOKEN ? { authorization: `Bearer ${process.env.SUPER_PI_ACCESS_TOKEN}` } : {}; const response = await fetch(`http://127.0.0.1:${port}/api/shutdown`, { method: "POST", headers, signal: AbortSignal.timeout(3000) }); return response.ok || response.status === 202; } catch { return false; } }
 function openBrowser(url) { const command = platform === "darwin" ? "open" : platform === "win32" ? "cmd.exe" : "xdg-open"; const args = platform === "darwin" ? [url] : platform === "win32" ? ["/c", "start", "", url] : [url]; spawn(command, args, { detached: true, stdio: "ignore", windowsHide: true }).unref(); }
-function usage() { console.log("Usage: super-pi|super_pi <start|stop|restart|update|diagnose|autostart> [options]"); console.log("  autostart enable|disable|status  Configure startup at sign-in"); console.log("  diagnose                       Measure where a message spends its time"); console.log("  --port PORT  Server port (default: 3080)"); console.log("  --host HOST  Server host (default: 0.0.0.0)"); console.log("  --no-browser  Do not open a browser"); }
+function usage() { console.log("Usage: super-pi|super_pi <start|stop|restart|update|diagnose|logs|autostart> [options]"); console.log("  autostart enable|disable|status  Configure startup at sign-in"); console.log("  diagnose                       Measure where a message spends its time"); console.log("  logs [N] [--follow]            Show the server log (last N lines, default 200)"); console.log("  logs --path                    Print the log file's path"); console.log("  logs --clear                   Empty the log file"); console.log("  --port PORT  Server port (default: 3080)"); console.log("  --host HOST  Server host (default: 0.0.0.0)"); console.log("  --no-browser  Do not open a browser"); }
+
+/**
+ * WHERE THE SERVER KEEPS ITS LOG FILE.
+ *
+ * The same rule the server itself uses when it picks its data directory, mirrored here on purpose:
+ * the CLI has to find the file the server wrote, and the server may be a DIFFERENT installation of
+ * Super Pi than the CLI that is asking (the global install and the one the `/super_pi` extension
+ * loads are two separate installs by design). `SUPER_PI_DATA_DIR` overrides both, which is what a
+ * person with a custom data directory needs.
+ */
+function dataDir() {
+  if (process.env.SUPER_PI_DATA_DIR) return resolve(process.env.SUPER_PI_DATA_DIR);
+  const local = join(root, ".super-pi");
+  if (!root.match(/[\\/]node_modules[\\/]/i) && existsSync(local)) return local;
+  return join(home, ".super-pi");
+}
+function logFile() { return join(dataDir(), "logs", "server.log"); }
+function heartbeatFile() { return join(dataDir(), "logs", "heartbeat.txt"); }
+
+/** "How long ago was the server alive?" - the answer a silent death cannot give by itself. */
+function lastAlive() {
+  const file = heartbeatFile();
+  if (!existsSync(file)) return null;
+  try {
+    const at = statSync(file).mtimeMs;
+    const minutes = Math.max(0, Math.round((Date.now() - at) / 60000));
+    const when = new Date(at).toLocaleString();
+    return minutes < 1 ? `${when} (just now)` : `${when} (${minutes} minute${minutes === 1 ? "" : "s"} ago)`;
+  } catch { return null; }
+}
+
+
+/** The last `lines` lines of the log file, read from the end so a big file stays cheap to open. */
+function readLogTail(file, lines) {
+  if (!existsSync(file)) return [];
+  const size = statSync(file).size;
+  if (size === 0) return [];
+  const length = Math.min(size, 512 * 1024);
+  const buffer = Buffer.alloc(length);
+  const fd = openSync(file, "r");
+  try { readSync(fd, buffer, 0, length, size - length); } finally { closeSync(fd); }
+  const all = buffer.toString("utf8").split(/\r?\n/);
+  if (all.length > 0 && all[all.length - 1] === "") all.pop();
+  return all.slice(Math.max(0, all.length - lines));
+}
+
+/** Print whatever the log file gains from now on, until Ctrl+C. */
+function followLog(file) {
+  let offset = existsSync(file) ? statSync(file).size : 0;
+  const tick = () => {
+    try {
+      if (!existsSync(file)) return;
+      const size = statSync(file).size;
+      // A SMALLER FILE MEANS THE LOG WAS ROTATED (or cleared): start over from the top.
+      if (size < offset) offset = 0;
+      if (size <= offset) return;
+      const buffer = Buffer.alloc(size - offset);
+      const fd = openSync(file, "r");
+      try { readSync(fd, buffer, 0, buffer.length, offset); } finally { closeSync(fd); }
+      offset = size;
+      process.stdout.write(buffer.toString("utf8"));
+    } catch { /* the file is being rotated under us; the next tick picks it up */ }
+  };
+  tick();
+  const timer = setInterval(tick, 400);
+  process.on("SIGINT", () => { clearInterval(timer); process.exit(0); });
+}
+
 function paths() { if (platform === "win32") return { task: "Super Pi" }; if (platform === "darwin") return { file: join(home, "Library", "LaunchAgents", "com.evandu.super-pi.plist") }; return { file: join(process.env.XDG_CONFIG_HOME ?? join(home, ".config"), "systemd", "user", "super-pi.service") }; }
 async function system(command, args) { if (process.env.SUPER_PI_AUTOSTART_DRY_RUN === "1") { console.log(`[dry-run] ${command} ${args.join(" ")}`); return; } await execFileAsync(command, args, { windowsHide: true }); }
 async function enable(value) {
@@ -104,6 +172,30 @@ try {
     console.log(renderReport(result));
     process.exit(result.error ? 1 : 0);
   }
+  if (command === "logs" || command === "log") {
+    // HOW THE SERVER DIED, IN ONE COMMAND.
+    //
+    // The server runs detached with its console thrown away, so this file is the only record of it.
+    // It is written synchronously as the server speaks, so the last lines are always the crash.
+    const file = logFile();
+    const count = Number.parseInt(args.find((a) => /^\d+$/.test(a)) ?? "200", 10);
+    const follow = args.some((a) => a === "--follow" || a === "-f");
+    if (args.includes("--path")) { console.log(file); process.exit(0); }
+    if (args.includes("--clear")) { if (existsSync(file)) truncateSync(file, 0); console.log(`Cleared ${file}`); process.exit(0); }
+    if (!existsSync(file)) { console.log(`No log file yet at ${file}\nStart Super Pi with: super-pi start`); process.exit(0); }
+    console.log(`Log file: ${file}`);
+    const alive = lastAlive();
+    console.log(alive ? `Last alive: ${alive}` : "Last alive: unknown (no heartbeat file - the server may never have started)");
+    for (const line of readLogTail(file, Number.isInteger(count) && count > 0 ? count : 200)) console.log(line);
+    if (follow) {
+      // FOLLOWING MEANS THIS COMMAND DOES NOT END. The promise below never settles; `followLog` ends
+      // the process on Ctrl+C. Without it this branch would fall through to the "unknown command"
+      // check below and take the tail down with it.
+      followLog(file);
+      await new Promise(() => {});
+    }
+    process.exit(0);
+  }
   if (!["start", "stop", "restart", "update"].includes(command)) throw new Error(`Unknown command: ${command}`);
   if (command === "update") { const npm = platform === "win32" ? "npm.cmd" : "npm"; const args = prefix ? ["install", "--prefix", prefix, "@evandu/super-pi"] : ["install", "-g", "@evandu/super-pi"]; const child = spawn(npm, args, { stdio: "inherit", shell: platform === "win32", env: process.env }); const code = await new Promise((resolve) => child.on("close", resolve)); if (code !== 0) process.exit(code ?? 1); }
   const value = options(args);

package/dist/client/.super-pi-client-sources.json

@@ -28,5 +28,5 @@
     "src/client/types.ts": "fb2cf2889d695f102e0e7b02090ce0d96b351a4c6343e31fd8b88ac4b51a5781",
     "src/client/vite-env.d.ts": "65996936fbb042915f7b74a200fcdde7e410f32a669b1ab9597cfaa4b0faddb5"
   },
-  "recordedAt": "2026-10-23T03:40:19.344Z"
+  "recordedAt": "2026-10-23T03:47:58.951Z"
 }

package/dist/extension.js

@@ -116,7 +116,7 @@ export default function (pi) {
                     }
                 }
                 if (!ready) {
-                    ctx.ui.notify?.(`Warning: Super Pi server on port ${port} did not respond to health check in time`, "warning");
+                    ctx.ui.notify?.(`Warning: Super Pi server on port ${port} did not respond to health check in time. Run "super-pi logs" to see why.`, "warning");
                 }
             }
             openBrowser(url);

package/dist/server/index.js

@@ -28,12 +28,25 @@ import { ExecService } from "./exec-service.js";
 import { createHttpServer, getLanIps, isLocalOrPrivateAddress, parseServerArgs } from "./http-server.js";
 import { WsBroadcaster, WsServer } from "./ws-server.js";
 import { initRunningVersion } from "./version.js";
+import { installServerLogging } from "./logging.js";
 import { ToolRegistry } from "./tool-registry.js";
 import { ToolRunner } from "./tool-runner.js";
 import { ToolLlmService } from "./tool-llm.js";
 // ------------------------------------------------------------- Environment & paths
 const rootDir = resolve(import.meta.dirname, "../..");
 initRunningVersion(rootDir);
+// ------------------------------------------------------------- The log file
+//
+// THE SERVER IS STARTED DETACHED WITH ITS OUTPUT THROWN AWAY, so anything printed to the console
+// is gone. A crash used to take the process down with no word at all, and the browser just sat there
+// saying "connecting". The log file is installed BEFORE anything else can fail, so the first line in
+// it is always "the server started" and the last line is always "the server stopped".
+const defaultDataDir = !rootDir.includes("node_modules") && existsSync(join(rootDir, ".super-pi"))
+    ? join(rootDir, ".super-pi")
+    : join(homedir(), ".super-pi");
+const dataDir = resolve(process.env.SUPER_PI_DATA_DIR ?? defaultDataDir);
+const logging = installServerLogging(dataDir);
+logging.write("info", `server starting: pid ${process.pid}, node ${process.versions.node}, data dir ${dataDir}`);
 // THE SECURITY PATCH, APPLIED WHERE IT CANNOT BREAK AN INSTALL.
 //
 // Pi's package pins a vulnerable `brace-expansion` in its own shrinkwrapped tree, and npm will not let
@@ -84,10 +97,6 @@ const envPort = Number.parseInt(process.env.SUPER_PI_PORT ?? "3080", 10);
 const port = cliArgs.port ?? (Number.isNaN(envPort) ? 3080 : envPort);
 const host = cliArgs.host ?? process.env.SUPER_PI_HOST ?? "0.0.0.0";
 const internalHost = (host === "0.0.0.0" || host === "::" || !host) ? "127.0.0.1" : host;
-const defaultDataDir = !rootDir.includes("node_modules") && existsSync(join(rootDir, ".super-pi"))
-    ? join(rootDir, ".super-pi")
-    : join(homedir(), ".super-pi");
-const dataDir = resolve(process.env.SUPER_PI_DATA_DIR ?? defaultDataDir);
 const agentPromptDir = join(dataDir, "agent-prompts");
 const clientDir = join(rootDir, "dist", "client");
 const accessToken = process.env.SUPER_PI_ACCESS_TOKEN;
@@ -326,6 +335,7 @@ const wsServer = new WsServer({
 httpServer.listen(port, host, () => {
     const displayHost = host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
     console.log(`Super Pi is running at http://${displayHost}:${port}`);
+    logging.write("info", `listening on ${host}:${port} (pid ${process.pid})`);
     if (host === "0.0.0.0" || host === "::") {
         const lanIps = getLanIps();
         for (const ip of lanIps) {

package/dist/server/logging.d.ts

@@ -0,0 +1,32 @@
+/**
+ * THE SERVER'S OWN LOG FILE.
+ *
+ * Super Pi is started DETACHED, with its standard streams thrown away (`stdio: "ignore"`), because
+ * the person who started it is usually gone by the time it matters - the panel runs in a browser tab
+ * and the server lives on behind it. The cost of that decision was that when the server DIED, it
+ * died silently: the browser sat there saying "connecting" and nobody could say why. A log file is
+ * the cheapest possible answer to "how did it die".
+ *
+ * Two properties matter more than volume here:
+ *
+ * - EVERY LINE IS WRITTEN SYNCHRONOUSLY. A buffered stream loses exactly the lines you want - the
+ *   ones written a millisecond before the crash - because the buffer is still in memory when the
+ *   process dies. `appendFileSync` costs a syscall per line, which is nothing at this volume, and
+ *   it costs the line that matters.
+ * - THE CRASH IS LOGGED BEFORE THE PROCESS LEAVES. `uncaughtException` and `unhandledRejection` are
+ *   the two ways a Node process dies without saying anything, and both are turned into a stack trace
+ *   in the log file.
+ */
+export declare const SERVER_LOG_NAME = "server.log";
+export interface ServerLogging {
+    /** Absolute path of the log file this server writes to. */
+    readonly logFile: string;
+    /** Absolute path of the liveness file; its timestamp says when the server was last alive. */
+    readonly heartbeatFile: string;
+    /** Append one line to the log file, independently of the console. */
+    write(level: string, message: string): void;
+}
+/**
+ * Install the file logger. Returns the handle so the caller can write lines the console never sees.
+ */
+export declare function installServerLogging(dataDir: string): ServerLogging;

package/dist/server/logging.js

@@ -0,0 +1,132 @@
+import { appendFileSync, existsSync, mkdirSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * THE SERVER'S OWN LOG FILE.
+ *
+ * Super Pi is started DETACHED, with its standard streams thrown away (`stdio: "ignore"`), because
+ * the person who started it is usually gone by the time it matters - the panel runs in a browser tab
+ * and the server lives on behind it. The cost of that decision was that when the server DIED, it
+ * died silently: the browser sat there saying "connecting" and nobody could say why. A log file is
+ * the cheapest possible answer to "how did it die".
+ *
+ * Two properties matter more than volume here:
+ *
+ * - EVERY LINE IS WRITTEN SYNCHRONOUSLY. A buffered stream loses exactly the lines you want - the
+ *   ones written a millisecond before the crash - because the buffer is still in memory when the
+ *   process dies. `appendFileSync` costs a syscall per line, which is nothing at this volume, and
+ *   it costs the line that matters.
+ * - THE CRASH IS LOGGED BEFORE THE PROCESS LEAVES. `uncaughtException` and `unhandledRejection` are
+ *   the two ways a Node process dies without saying anything, and both are turned into a stack trace
+ *   in the log file.
+ */
+export const SERVER_LOG_NAME = "server.log";
+/** Kept small enough to open by eye; the previous file is kept as `server.log.1`. */
+const MAX_LOG_BYTES = 8 * 1024 * 1024;
+function format(level, message) {
+    const time = new Date().toISOString();
+    // A multi-line message (a stack trace) stays one entry per line, each carrying the same stamp, so
+    // that a `tail` still shows where it started.
+    return message
+        .split("\n")
+        .map((line) => `[${time}] [${level}] ${line}`)
+        .join("\n");
+}
+function rotateIfLarge(logFile) {
+    try {
+        if (!existsSync(logFile))
+            return;
+        if (statSync(logFile).size < MAX_LOG_BYTES)
+            return;
+        const previous = `${logFile}.1`;
+        try {
+            renameSync(previous, `${previous}.old`);
+        }
+        catch { /* no previous file: fine */ }
+        renameSync(logFile, previous);
+    }
+    catch {
+        // Rotation is best-effort: a log file that cannot be rotated must not stop the server from
+        // starting, and must not stop it from logging.
+    }
+}
+/**
+ * Install the file logger. Returns the handle so the caller can write lines the console never sees.
+ */
+export function installServerLogging(dataDir) {
+    const logDir = join(dataDir, "logs");
+    try {
+        mkdirSync(logDir, { recursive: true });
+    }
+    catch { /* the write below will report the real problem */ }
+    const logFile = join(logDir, SERVER_LOG_NAME);
+    rotateIfLarge(logFile);
+    /**
+     * THE LIVENESS FILE.
+     *
+     * A log file says what the server said; it cannot say when the server STOPPED, because the lines
+     * it would have written to say that are exactly the ones a crash takes away. A native crash (the
+     * kind that comes from a terminal being killed) never runs a JavaScript handler at all, so the
+     * server cannot even write "I died". This file answers the other half of the question: it is
+     * touched every minute while the server lives, so its timestamp says "the server was alive until
+     * this moment" - which is how a silent death gets a time on it.
+     */
+    const heartbeatFile = join(logDir, "heartbeat.txt");
+    const touch = () => {
+        try {
+            writeFileSync(heartbeatFile, `${Date.now()}\n`, "utf8");
+        }
+        catch { /* best effort */ }
+    };
+    touch();
+    const heartbeat = setInterval(touch, 60_000);
+    // The heartbeat must not be the reason the process stays alive.
+    heartbeat.unref?.();
+    const write = (level, message) => {
+        try {
+            appendFileSync(logFile, `${format(level, message)}\n`, "utf8");
+        }
+        catch { /* never let logging crash the server */ }
+    };
+    // CONSOLE OUTPUT IS TEED INTO THE FILE, NOT REPLACED BY IT.
+    //
+    // Everything the server already prints (the banner, warnings from the services, the shutdown
+    // notice) is worth keeping, and the cheapest way to keep it is to keep printing it and copy it.
+    // A service that logs through `console.warn` gets into the file for free.
+    const levels = ["log", "info", "warn", "error", "debug"];
+    const originals = new Map();
+    for (const level of levels) {
+        const original = console[level];
+        originals.set(level, original);
+        console[level] = (...args) => {
+            original.apply(console, args);
+            write(level === "log" ? "info" : level, args.map((arg) => (typeof arg === "string" ? arg : safeStringify(arg))).join(" "));
+        };
+    }
+    /**
+     * THE TWO WAYS A NODE PROCESS DIES WITHOUT A WORD.
+     *
+     * `uncaughtException` is a throw nobody caught; `unhandledRejection` is a promise nobody awaited.
+     * Both used to take the server down silently. Both now write the stack and then end the process -
+     * for `uncaughtException` continuing is not safe, because the process state after an uncaught
+     * exception is undefined.
+     */
+    process.on("uncaughtException", (error) => {
+        write("fatal", `uncaughtException: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
+        process.exit(1);
+    });
+    process.on("unhandledRejection", (reason) => {
+        write("fatal", `unhandledRejection: ${reason instanceof Error ? (reason.stack ?? reason.message) : String(reason)}`);
+    });
+    process.on("exit", (code) => {
+        write("info", `server process exiting with code ${code}`);
+    });
+    return { logFile, heartbeatFile, write };
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evandu/super-pi",
-  "version": "0.1.113",
+  "version": "0.1.114",
   "description": "Web control plane and companion for Pi",
   "license": "MIT",
   "type": "module",
@@ -46,6 +46,7 @@
     "scripts/pi-model-switch.test.mjs",
     "scripts/pi-thinking-levels.test.mjs",
     "scripts/diagnose-cli.test.mjs",
+    "scripts/cli-logs.test.mjs",
     "scripts/lan-access.test.mjs",
     "scripts/terminal-pty.test.mjs",
     "scripts/persistence-repository.test.mjs",