@xingjisoft/neutrino 0.3.0 → 0.4.1

package/dist/bin.js

@@ -3,7 +3,10 @@ import process from "node:process";
 import { App } from "./app.js";
 import { loadConfig } from "./config.js";
 import { installCrashGuard } from "./terminal/restore.js";
-import { startWebServer } from "./web/server.js";
+import { webUrls } from "./web/server.js";
+import { runningBackground, startBackgroundService, stopBackgroundService, } from "./background.js";
+import { runWebService } from "./web/service.js";
+import { openInBrowser } from "./browser.js";
 const DEFAULT_WEB_PORT = 8765;
 /** Binding here makes the UI reachable from every interface. */
 const WILDCARD_HOST = "0.0.0.0";
@@ -35,6 +38,11 @@ Usage:
   neutrino                     Start the terminal UI (with the web UI).
   neutrino --lan               Start both, reachable from other devices.
   neutrino web [--port <port>] Start only the web UI (serves saved history).
+  neutrino background start    Run the web UI in the background; conversations
+                               started there survive the terminal/CLI exiting.
+  neutrino background stop     Stop the background service.
+  neutrino background status   Show whether it is running and where.
+  neutrino background open     Open its console in the default browser.
 
 Options:
   -p, --port <port>   Web UI port. Default: ${DEFAULT_WEB_PORT}
@@ -43,18 +51,32 @@ Options:
                       devices on your LAN or VPN.
       --no-web        Do not start the web UI with the terminal UI.
       --no-auth       Serve without password login.
+      --no-tray       Do not show the Windows notification-area icon of the
+                      background service.
       --web-port <n>  Deprecated alias for --port while the TUI runs.
   -h, --help          Show this help.
 
 Environment:
   NEUTRINO_WEB_PORT   Same as --port in either mode.
   NEUTRINO_WEB_HOST   Same as --host.
+  NEUTRINO_NO_TRAY    Set to 1 to keep the background service out of the
+                      Windows notification area.
 
 The web UI starts by default alongside the terminal UI on loopback. Turn it
 off for one run with --no-web, or permanently in Settings → Web console. It can
 read every saved conversation and drive an agent with shell access, so it binds
-to loopback unless you ask for --host/--lan. Log in with the permanent password
-(default: 114514). Change it in Settings. --no-auth disables password login.
+to loopback unless you ask for --host/--lan. The same LAN access can be switched
+on, and off, in the browser's Settings → Web access; the choice is saved for the
+next launch, while --host/--lan win for the current one. Log in with the
+permanent password (default: 114514). Change it in Settings. --no-auth disables
+password login.
+
+Background residency is off by default. Turn it on in Settings → Background
+(shared by the regular and Pro workspaces). Switching it takes effect immediately,
+including for browser tasks already running. The background service keeps
+running when this terminal closes, so tasks started
+from the browser are not interrupted. Stop it with 'neutrino background stop',
+the tray icon, or Settings → Web console in the terminal.
 `);
 }
 /** Read the value that follows a flag, so `--host` alone is an error. */
@@ -65,13 +87,28 @@ function requireValue(argv, index, flag) {
     }
     return value;
 }
+const BACKGROUND_ACTIONS = new Set(["run", "start", "stop", "status", "open"]);
 function parseArgs(argv) {
-    const options = { mode: "tui", port: null, lan: false, noWeb: false, noAuth: false };
+    const options = {
+        mode: "tui", backgroundAction: null, port: null, lan: false, noWeb: false, noAuth: false, noTray: false,
+    };
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         if (arg === "web") {
             options.mode = "web";
         }
+        else if (arg === "background") {
+            options.mode = "background";
+            options.backgroundAction = "status";
+            const next = argv[i + 1];
+            if (next && !next.startsWith("-")) {
+                if (!BACKGROUND_ACTIONS.has(next)) {
+                    throw new Error(`unknown background action "${next}"`);
+                }
+                options.backgroundAction = next;
+                i += 1;
+            }
+        }
         else if (arg === "--port" || arg === "-p") {
             options.port = parsePort(argv[++i]);
         }
@@ -99,6 +136,25 @@ function parseArgs(argv) {
         else if (arg === "--no-auth") {
             options.noAuth = true;
         }
+        else if (arg === "--no-tray") {
+            options.noTray = true;
+        }
+        else if (arg === "--start") {
+            options.mode = "background";
+            options.backgroundAction = "start";
+        }
+        else if (arg === "--stop") {
+            options.mode = "background";
+            options.backgroundAction = "stop";
+        }
+        else if (arg === "--status") {
+            options.mode = "background";
+            options.backgroundAction = "status";
+        }
+        else if (arg === "--open") {
+            options.mode = "background";
+            options.backgroundAction = "open";
+        }
         else if (arg === "--help" || arg === "-h") {
             printHelp();
             process.exit(0);
@@ -113,31 +169,64 @@ function parseArgs(argv) {
     if (options.noWeb && options.mode === "web") {
         throw new Error("--no-web cannot be used with the 'web' command");
     }
+    if (options.noWeb && options.mode === "background") {
+        throw new Error("--no-web cannot be used with the 'background' command");
+    }
     if (options.noWeb && (options.port !== null || options.host !== undefined || options.lan)) {
         throw new Error("use either --no-web or web UI options, not both");
     }
     return options;
 }
-/** Print every address a client can open, plus what it takes to open one. */
-function reportAccess(handle) {
-    process.stdout.write(`Neutrino web UI listening on ${handle.host}:${handle.port}\n`);
-    const multiple = handle.urls.length > 1;
+/** Print where an already-running detached console can be opened. */
+function reportBackgroundAccess(status, started) {
+    process.stdout.write(`Neutrino ${status.resident ? "background " : ""}Web console ${started ? "started" : "already running"} `
+        + `(pid ${status.pid}) on ${status.host}:${status.port}\n`);
+    const { urls } = webUrls(status.host, status.port);
+    const multiple = urls.length > 1;
     process.stdout.write(multiple ? "Open the address that matches your device:\n" : "Open:\n");
-    for (const url of handle.urls)
+    for (const url of urls)
         process.stdout.write(`  ${url}\n`);
-    const wildcard = handle.host === "0.0.0.0" || handle.host === "::";
-    if (wildcard && !handle.urls.some((url) => !url.includes("//127.0.0.1:"))) {
-        // Bound to every interface, yet nothing outside this machine is reachable:
-        // usually Wi-Fi is off, the VPN is down, or the only adapters left are
-        // virtual ones we deliberately hide.
+    if ((status.host === "0.0.0.0" || status.host === "::")
+        && !urls.some((url) => !url.includes("//127.0.0.1:"))) {
         process.stdout.write("note: no reachable network address found, so only this machine can connect.\n");
     }
-    if (handle.authRequired) {
-        process.stdout.write("Sign in with your permanent Web password (default: 114514). Change it in Settings.\n");
+    if (status.auth_required) {
+        process.stdout.write("Sign in with your permanent Web password (default: 114514).\n");
     }
     else {
         process.stdout.write("Password login is disabled.\n");
     }
+    if (status.resident) {
+        process.stdout.write("It keeps running after this terminal exits. Stop it with 'neutrino background stop'"
+            + (process.platform === "win32" ? " or the tray icon" : "") + ".\n");
+    }
+}
+/**
+ * The detached service itself (`neutrino background run`).
+ *
+ * It owns the Web console and every browser conversation for as long as the
+ * machine's user session keeps it alive. The token written into the status
+ * file is the only way another local process can ask it to stop.
+ */
+async function runBackgroundService(host, auth) {
+    await runWebService({ port: options.port ?? portFromEnv ?? DEFAULT_WEB_PORT, host, auth, tray: !options.noTray });
+}
+function printBackgroundStatus() {
+    const status = runningBackground();
+    if (!status) {
+        process.stdout.write("No background service is running.\n");
+        process.stdout.write("Start one with 'neutrino background start'.\n");
+        return;
+    }
+    process.stdout.write(`Neutrino background service: running (pid ${status.pid})\n`);
+    process.stdout.write(`Residency: ${status.resident ? "on" : "off (follows the terminal)"}\n`);
+    process.stdout.write(`Started: ${status.started_at}\n`);
+    process.stdout.write(`Address: ${status.url}\n`);
+    const { urls } = webUrls(status.host, status.port);
+    for (const url of urls) {
+        if (url.replace(/\/$/, "") !== status.url)
+            process.stdout.write(`Also: ${url}\n`);
+    }
 }
 let options;
 try {
@@ -149,29 +238,82 @@ catch (err) {
     process.exit(2);
 }
 // Installed before either mode starts: a crash must leave a usable terminal
-// (TUI) and a log line (both), never a shell flooded with mouse reports.
-installCrashGuard();
+// (TUI) and a log line (both), never a shell flooded with mouse reports. A
+// detached service keeps its own SIGHUP handler so closing the terminal cannot
+// take it down.
+installCrashGuard({ surviveHangup: options.mode === "background" });
 const host = options.lan ? WILDCARD_HOST : options.host || process.env.NEUTRINO_WEB_HOST || undefined;
 const auth = !options.noAuth;
 const portFromEnv = envPort();
 if (options.mode === "web") {
-    // Headless: serve the saved history (and any live sessions in this process,
-    // which for a standalone server is none).
-    const port = options.port ?? portFromEnv ?? DEFAULT_WEB_PORT;
-    try {
-        const handle = await startWebServer({ port, host, auth });
-        reportAccess(handle);
-        process.stdout.write("Serving saved conversations. Press Ctrl+C to stop.\n");
-        const shutdown = () => {
-            handle.close().finally(() => process.exit(0));
-        };
-        process.on("SIGINT", shutdown);
-        process.on("SIGTERM", shutdown);
-    }
-    catch (err) {
-        process.stderr.write(`neutrino: failed to start web server: ${err instanceof Error ? err.message : String(err)}\n`);
+    const result = await startBackgroundService({
+        port: options.port ?? portFromEnv ?? DEFAULT_WEB_PORT, host, auth,
+        tray: !options.noTray, resident: loadConfig().background === true, ownerPid: process.pid,
+        strictPort: options.port !== null,
+    });
+    if (!result.ok) {
+        process.stderr.write(`neutrino: failed to start web server: ${result.error}\n`);
         process.exit(1);
     }
+    reportBackgroundAccess(result.status, result.started);
+    process.stdout.write("Serving saved conversations. Press Ctrl+C to close this terminal.\n");
+    // The owner monitor in the service also handles an abrupt terminal close.
+    const keepAlive = setInterval(() => { }, 60_000);
+    const shutdown = () => { clearInterval(keepAlive); process.exit(0); };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+else if (options.mode === "background") {
+    const action = options.backgroundAction ?? "status";
+    if (action === "run") {
+        // The detached child. It does not own a terminal, so its stdio is ignored
+        // by the parent and every diagnostic goes to background.log.
+        await runBackgroundService(host, auth);
+    }
+    else if (action === "start") {
+        const result = await startBackgroundService({
+            port: options.port ?? portFromEnv ?? DEFAULT_WEB_PORT,
+            host,
+            auth,
+            tray: !options.noTray,
+        });
+        if (!result.ok) {
+            process.stderr.write(`neutrino: ${result.error}\n`);
+            process.exit(1);
+        }
+        reportBackgroundAccess(result.status, result.started);
+        process.exitCode = 0;
+    }
+    else if (action === "stop") {
+        const result = await stopBackgroundService();
+        if (!result.ok) {
+            process.stderr.write(`neutrino: ${result.error}\n`);
+            process.exit(1);
+        }
+        process.stdout.write(result.stopped ? "Background service stopped.\n" : "No background service is running.\n");
+        process.exitCode = 0;
+    }
+    else if (action === "open") {
+        const started = await startBackgroundService({
+            port: options.port ?? portFromEnv ?? DEFAULT_WEB_PORT,
+            host,
+            auth,
+            tray: !options.noTray,
+        });
+        if (!started.ok) {
+            process.stderr.write(`neutrino: ${started.error}\n`);
+            process.exit(1);
+        }
+        if (started.started)
+            reportBackgroundAccess(started.status, true);
+        openInBrowser(started.status.url);
+        process.stdout.write(`Opening ${started.status.url}\n`);
+        process.exitCode = 0;
+    }
+    else {
+        printBackgroundStatus();
+        process.exitCode = 0;
+    }
 }
 else {
     if (!process.stdout.isTTY || !process.stdin.isTTY) {
@@ -181,22 +323,20 @@ else {
     }
     const app = new App();
     const webPort = options.port ?? portFromEnv ?? DEFAULT_WEB_PORT;
-    // Remember where the UI should live even when it is off right now, so the
-    // Settings toggle can mount it without restarting the terminal.
-    app.configureWeb(webPort, host, auth);
-    // Explicit web settings win over the saved preference; otherwise the web UI
-    // is part of a normal launch unless the user turned it off in Settings.
+    const saved = loadConfig();
+    app.configureWeb(webPort, host, auth, true, !options.noTray);
     const requested = options.port !== null || options.host !== undefined || options.lan
         || options.noAuth || portFromEnv !== null || Boolean(process.env.NEUTRINO_WEB_HOST);
-    const enabledByDefault = loadConfig().web_console !== false;
-    if (!options.noWeb && (requested || enabledByDefault)) {
+    if (!options.noWeb && (requested || saved.web_console !== false)) {
         try {
-            const handle = await app.enableWeb(webPort, host, auth);
-            reportAccess(handle);
+            const previous = runningBackground();
+            const status = await app.enableWeb(webPort, host, auth);
+            if (options.port !== null && options.port !== 0 && status.port !== webPort) {
+                process.stderr.write(`note: the Web console is already running on port ${status.port}; --port was not applied.\n`);
+            }
+            reportBackgroundAccess(status, previous?.pid !== status.pid);
         }
         catch (err) {
-            // A console that cannot bind (usually a second instance on 8765) must
-            // never take the terminal down with it.
             const detail = err instanceof Error ? err.message : String(err);
             process.stderr.write(`neutrino: web UI not started: ${detail}\n`);
             process.stderr.write("The terminal UI will keep running. Pass --port <port> to use another port, or --no-web to skip the web UI.\n");

package/dist/browser.js

@@ -0,0 +1,57 @@
+import { spawn } from "node:child_process";
+import process from "node:process";
+/**
+ * Where the browser console's Pro workspace lives, given the console's base
+ * URL.
+ *
+ * The base comes straight from the running server, but it is normalised here
+ * anyway: a trailing slash must not produce `//pro`, and a URL that already
+ * points at `/pro` must not become `/pro/pro`. A missing/blank base yields the
+ * path alone instead of throwing, so a half-configured console can still be
+ * reported instead of crashing the click that asked for it.
+ */
+export function proModeUrl(baseUrl) {
+    const base = String(baseUrl ?? "").trim().replace(/\/+$/, "");
+    if (/\/pro$/i.test(base))
+        return base;
+    return `${base}/pro`;
+}
+/**
+ * Open `url` in the user's default browser. Fire-and-forget: the child is
+ * detached, its stdio is ignored and it is unref'd so the terminal is never
+ * held open (or blocked) by the browser. Every failure is swallowed — opening
+ * a browser is best-effort and must never take the TUI down.
+ */
+export function openInBrowser(url) {
+    try {
+        let command;
+        let args;
+        if (process.platform === "win32") {
+            // `start` is a cmd built-in. The empty "" is the (required) window title,
+            // so a quoted URL is never mistaken for one.
+            command = "cmd";
+            args = ["/c", "start", "", url];
+        }
+        else if (process.platform === "darwin") {
+            command = "open";
+            args = [url];
+        }
+        else {
+            command = "xdg-open";
+            args = [url];
+        }
+        const child = spawn(command, args, {
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+        });
+        // A missing opener (xdg-open is not installed everywhere) is reported
+        // asynchronously; without a listener that 'error' event would crash the
+        // whole process.
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        // Best-effort only.
+    }
+}