cartethyia 2.3.1 → 2.3.3

package/scripts/cli/cli-launcher.cjs

@@ -21,17 +21,34 @@ const startupSignalPath = trayMode
   ? path.join(os.tmpdir(), `cartethyia-tray-${process.pid}-${randomUUID()}.json`)
   : null;
 let spawnError;
-const child = spawn("bun", ["run", cliPath, ...process.argv.slice(2)], {
-  cwd: packageRoot,
-  detached: trayMode,
-  stdio: trayMode ? "ignore" : "inherit",
-  windowsHide: trayMode,
-  env: {
-    ...process.env,
-    CARTETHYIA_CONFIG_DIR: configDir,
-    ...(trayMode ? { CARTETHYIA_TRAY_STARTUP_SIGNAL: startupSignalPath } : {}),
-  },
-});
+// On Windows, `cmd /c start "" /b` gives bun its own console group so the
+// launching terminal can close without signalling the gateway. Elsewhere
+// `detached: true` is enough. Either way the child is unref'd below so the
+// launcher can exit without taking the gateway down with it.
+const useWindowsDetach = process.platform === "win32" && trayMode;
+const child = useWindowsDetach
+  ? spawn("cmd", ["/c", "start", "", "/b", "bun", "run", cliPath, ...process.argv.slice(2)], {
+      cwd: packageRoot,
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+      env: {
+        ...process.env,
+        CARTETHYIA_CONFIG_DIR: configDir,
+        CARTETHYIA_TRAY_STARTUP_SIGNAL: startupSignalPath,
+      },
+    })
+  : spawn("bun", ["run", cliPath, ...process.argv.slice(2)], {
+      cwd: packageRoot,
+      detached: trayMode,
+      stdio: trayMode ? "ignore" : "inherit",
+      windowsHide: trayMode,
+      env: {
+        ...process.env,
+        CARTETHYIA_CONFIG_DIR: configDir,
+        ...(trayMode ? { CARTETHYIA_TRAY_STARTUP_SIGNAL: startupSignalPath } : {}),
+      },
+    });
 
 child.once("error", (error) => {
   spawnError = error;
@@ -61,6 +78,10 @@ if (trayMode) {
       return;
     }
     console.log(`Cartethyia is ready at ${url}`);
+    // The gateway child is already detached and unref'd; this Node process is
+    // the only thing still holding the launching terminal open. Exit once the
+    // URL has been shown so the shell prompt comes back.
+    setTimeout(() => process.exit(0), 1_500);
   };
   const poll = () => {
     if (settled) return;

package/scripts/cli/cli.ts

@@ -6,6 +6,7 @@ import { join } from "node:path";
 import SysTray from "systray2";
 import { isNewerRelease } from "../../src/console/updates/version-compare";
 import { PACKAGE_ROOT, resolvePackagePath, resolveUserConfigDir } from "../../src/config/package-paths";
+import { resolvePort } from "../../src/config/runtime";
 import { MINIMUM_BUN_VERSION, bunVersionAtLeast } from "../shared/env";
 
 process.env.CARTETHYIA_CONFIG_DIR ??= resolveUserConfigDir();
@@ -13,13 +14,18 @@ process.env.CARTETHYIA_CONFIG_DIR ??= resolveUserConfigDir();
 const HELP = `Cartethyia ${MINIMUM_BUN_VERSION}+ (Bun is required)
 
 Usage:
-  carte
+  carte                  start, then show an arrow-key menu (no GUI needed)
+  carte --tray           start with a system-tray icon instead
   cartethyia setup [--non-interactive]
   cartethyia start
-  cartethyia tray
+  cartethyia menu
+  cartethyia stop           stop a gateway left running in the background
   cartethyia update
 
-The short carte command starts Cartethyia in the system tray.
+carte starts the gateway and opens a menu driven by the arrow keys and Enter:
+open the console, open settings, hide to the background, check for updates, or
+exit. It needs no desktop environment, so it works over SSH and headless.
+carte --tray uses a system-tray icon instead, which needs a graphical session.
 Setup explains Lite (embedded SQLite) and Full (external PostgreSQL), then saves
 configuration under the current user's Cartethyia config directory.
 `;
@@ -42,6 +48,54 @@ async function loadUserConfig(): Promise<void> {
   }
 }
 
+/**
+ * Runtime state for a gateway left running by "Hide to background".
+ *
+ * Kept out of `.env` on purpose: the drain token authorises a shutdown, so it
+ * belongs in a machine-written file the operator never hand-edits and never
+ * commits. It is written when the menu detaches and removed when the gateway
+ * is drained, so a stale file never outlives the process it refers to.
+ */
+const RUNTIME_STATE_FILE = "runtime.json";
+
+function writePersistedDrainToken(token: string): void {
+  const configDir = process.env.CARTETHYIA_CONFIG_DIR;
+  if (!configDir) return;
+  try {
+    writeFileSync(join(configDir, RUNTIME_STATE_FILE), JSON.stringify({ drainToken: token }), {
+      encoding: "utf8",
+      mode: 0o600,
+    });
+  } catch {
+    // A read-only config directory costs only the `stop` command, not startup.
+  }
+}
+
+function readPersistedDrainToken(): string | null {
+  const configDir = process.env.CARTETHYIA_CONFIG_DIR;
+  if (!configDir) return null;
+  const statePath = join(configDir, RUNTIME_STATE_FILE);
+  if (!existsSync(statePath)) return null;
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(statePath, "utf8"));
+    if (isRecord(parsed) && typeof parsed["drainToken"] === "string") return parsed["drainToken"];
+  } catch {
+    // A corrupt or stale state file reads as "no background gateway".
+  }
+  return null;
+}
+
+function clearPersistedDrainToken(): void {
+  const configDir = process.env.CARTETHYIA_CONFIG_DIR;
+  if (!configDir) return;
+  try {
+    unlinkSync(join(configDir, RUNTIME_STATE_FILE));
+  } catch {
+    // Best effort: the drain request already succeeded.
+  }
+}
+
+
 type TrayStartupSignal =
   | { readonly status: "ready"; readonly url: string }
   | { readonly status: "failed"; readonly message: string };
@@ -125,6 +179,60 @@ function openUrl(url: string): Promise<void> {
   return child.exited.then(() => undefined);
 }
 
+/**
+ * A single-select menu driven by the arrow keys and Enter, built on stdin raw
+ * mode so no menu dependency is added. It only reads keys and returns an
+ * index; the caller keeps owning the gateway process.
+ *
+ * Returns -1 when stdin is not a TTY (piped, CI, or a non-interactive run) so
+ * callers can fall back without blocking on input that will never arrive.
+ */
+function chooseFromMenu(title: string, options: readonly string[]): Promise<number> {
+  const stdin = process.stdin;
+  if (!stdin.isTTY) return Promise.resolve(-1);
+  const { promise, resolve } = Promise.withResolvers<number>();
+  let index = 0;
+
+  const render = (): void => {
+    process.stdout.write(`\u001b[2J\u001b[H${title}\n\n`);
+    options.forEach((option, position) => {
+      const marker = position === index ? "\u2192" : " ";
+      process.stdout.write(`  ${marker} ${option}\n`);
+    });
+    process.stdout.write("\n\u2191\u2193 move \u00b7 Enter choose \u00b7 Esc/q exit\n");
+  };
+  const cleanup = (choice: number): void => {
+    stdin.setRawMode(false);
+    stdin.off("keypress", onKey);
+    stdin.pause();
+    process.stdout.write("\u001b[2J\u001b[H");
+    resolve(choice);
+  };
+  const onKey = (_chunk: unknown, key: { name?: string }): void => {
+    if (key.name === "up") {
+      index = (index - 1 + options.length) % options.length;
+      render();
+      return;
+    }
+    if (key.name === "down") {
+      index = (index + 1) % options.length;
+      render();
+      return;
+    }
+    if (key.name === "return") {
+      cleanup(index);
+      return;
+    }
+    if (key.name === "escape" || key.name === "q") cleanup(-1);
+  };
+
+  stdin.setRawMode(true);
+  stdin.resume();
+  render();
+  stdin.on("keypress", onKey);
+  return promise;
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === "object";
 }
@@ -289,8 +397,112 @@ async function stopTray(tray: SysTray, ready: boolean, exited: boolean): Promise
   if (!tray.killed) tray.process.kill();
 }
 
+/**
+ * The default `carte` experience: start the gateway, then offer an arrow-key
+ * menu. This needs no desktop environment, so it works over SSH, on a headless
+ * box, and on Windows where the tray icon lands in the hidden-icons overflow
+ * and is never seen. `carte --tray` opts into the icon instead.
+ */
+async function startMenu(): Promise<void> {
+  const port = resolvePort();
+  const drainToken = randomBytes(32).toString("hex");
+  const dashboardUrl = `http://127.0.0.1:${port}/console`;
+  const settingsUrl = `${dashboardUrl}/settings`;
+  const currentVersion = await readInstalledVersion();
+
+  const gateway = await startGateway(port, drainToken);
+  let stopping = false;
+  const shutDown = async (): Promise<void> => {
+    if (stopping) return;
+    stopping = true;
+    await stopGateway(gateway, port, drainToken);
+  };
+  process.once("SIGINT", () => void shutDown());
+  process.once("SIGTERM", () => void shutDown());
+
+  const latest = await readLatestPublishedVersion();
+  const updateLabel =
+    latest !== null && isNewerRelease(currentVersion, latest)
+      ? `Update to ${latest}`
+      : "Check for updates";
+
+  const options = [
+    `Open Console \u00b7 ${dashboardUrl}`,
+    "Settings \u00b7 backup & restore, reset password",
+    "Hide to background and keep running",
+    updateLabel,
+    "Exit",
+  ] as const;
+
+  console.log(`Cartethyia ${currentVersion} is running at ${dashboardUrl}`);
+  for (;;) {
+    const choice = await chooseFromMenu(
+      `Cartethyia ${currentVersion} \u2014 running at ${dashboardUrl}`,
+      options,
+    );
+    if (choice === -1 || choice === 4) break;
+    if (choice === 0) {
+      await openUrl(dashboardUrl);
+      continue;
+    }
+    if (choice === 1) {
+      await openUrl(settingsUrl);
+      continue;
+    }
+    if (choice === 2) {
+      // The gateway is a detached child, so returning here leaves it running
+      // while this process lets go of the terminal. Persist the drain token
+      // now, because `cartethyia stop` runs in a later shell and has no other
+      // way to reach this process.
+      writePersistedDrainToken(drainToken);
+      console.log(`Cartethyia keeps running at ${dashboardUrl}.`);
+      console.log("Stop it later with: cartethyia stop");
+      return;
+    }
+    if (choice === 3) {
+      const code = await npmUpdate();
+      console.log(code === 0 ? "Update finished." : "Update failed.");
+    }
+  }
+  clearPersistedDrainToken();
+  await shutDown();
+}
+
+/**
+ * Stops a gateway left running by "Hide to background". That process is not a
+ * child of this one, so it cannot be signalled directly — the only handle is
+ * the loopback drain endpoint, which needs the drain token the start wrote.
+ */
+async function stopRunningGateway(): Promise<number> {
+  const port = resolvePort();
+  const token = readPersistedDrainToken();
+  if (token === null) {
+    console.error(
+      "No background Cartethyia gateway was found for this install. Start one with `carte`, or stop a foreground run with Ctrl-C.",
+    );
+    return 1;
+  }
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/admin/drain`, {
+      method: "POST",
+      headers: { "x-drain-token": token },
+      signal: AbortSignal.timeout(3_000),
+    });
+    if (response.status !== 202) {
+      console.error(`The gateway refused the drain request (HTTP ${response.status}).`);
+      return 1;
+    }
+  } catch {
+    console.error("No gateway is listening on the configured port. It may already be stopped.");
+    return 1;
+  }
+  clearPersistedDrainToken();
+  console.log("Cartethyia is draining and will stop once in-flight requests finish.");
+  return 0;
+}
+
+
 async function startTray(): Promise<void> {
-  const { resolvePort } = await import("../../src/config/runtime");
   const port = resolvePort();
   const drainToken = randomBytes(32).toString("hex");
   const currentVersion = await readInstalledVersion();
@@ -535,7 +747,7 @@ async function startTray(): Promise<void> {
 async function main(): Promise<void> {
   assertBunVersion();
   const [command] = process.argv.slice(2);
-  if (command === "setup" || command === "start" || command === "tray") {
+  if (command === "setup" || command === "start" || command === "tray" || command === "menu" || command === "stop") {
     await loadUserConfig();
   }
 
@@ -548,9 +760,15 @@ async function main(): Promise<void> {
     case "start":
       await import("../../src/main");
       return;
+    case "menu":
+      await startMenu();
+      return;
     case "tray":
       await startTray();
       return;
+    case "stop":
+      process.exitCode = await stopRunningGateway();
+      return;
     case "update": {
       const code = await npmUpdate();
       if (code !== 0) process.exitCode = code;