cartethyia 2.5.3 → 2.5.6

package/scripts/cli/{command/setup.ts → setup.ts}

@@ -3,8 +3,7 @@ import { stdin as input, stdout as output } from "node:process";
 import { existsSync, mkdirSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
-import { createServer } from "node:net";
-import { MINIMUM_BUN_VERSION, bunVersionAtLeast } from "../support/bun";
+import { readRequiredBunVersion, bunVersionAtLeast } from "./version";
 import {
   ENV_PATH,
   PROJECT_ROOT,
@@ -12,11 +11,12 @@ import {
   hasPlaceholderSecrets,
   mandatoryEnvBody,
   readEnvFile,
-} from "../support/env";
-import { getLocalPlatform, getOsHints } from "../support/platform";
-import { detectLocalPostgres, parseServiceUrl, probeTcpService } from "../support/services";
-import type { ProbeResult } from "../support/services";
-import { resolveDataDir, resolveDbMode } from "../../../src/persistence/db-mode";
+} from "./env";
+import { getLocalPlatform, getOsHints } from "./platform";
+import { detectLocalPostgres, parseServiceUrl, probeTcpService } from "./services";
+import type { ProbeResult } from "./services";
+import { blockedPortMessage, probeListenPort } from "./port";
+import { resolveDataDir, resolveDbMode } from "../../src/persistence/db-mode";
 
 async function ask(question: string, defaultValue = ""): Promise<string> {
   const rl = createInterface({ input, output });
@@ -145,11 +145,12 @@ function setupCommand(): string {
  * Refuses to continue on a Bun older than the repository declares. Printed as
  * one sentence: a stack trace here tells a first-time installer nothing.
  */
-function assertBunVersion(): void {
+async function assertLocalBunVersion(): Promise<void> {
   const actual = Bun.version;
-  if (bunVersionAtLeast(actual, MINIMUM_BUN_VERSION)) return;
+  const minimum = await readRequiredBunVersion();
+  if (bunVersionAtLeast(actual, minimum)) return;
   throw new Error(
-    `Bun ${MINIMUM_BUN_VERSION} or newer is required (this is ${actual}). Install it from https://bun.sh and run this again.`,
+    `Bun ${minimum} or newer is required (this is ${actual}). Install it from https://bun.sh and run this again.`,
   );
 }
 
@@ -179,25 +180,8 @@ async function chooseDbMode(envExisted: boolean): Promise<void> {
 /** Port the example ships with. A VPS NAT often does not forward it. */
 const DEFAULT_PORT = "12800";
 
-/** Ports this installer suggests when 12800 is taken. */
 const PORT_SUGGESTIONS: readonly string[] = ["8080", "3000", "8081"];
 
-/**
- * True when nothing is listening on the port yet.
- *
- * Binding is the test, not connecting: only a real bind proves the port is
- * free, and the socket is closed immediately so the probe never holds it.
- */
-function isPortFree(host: string, port: number): Promise<boolean> {
-  return new Promise((resolve) => {
-    const server = createServer();
-    server.once("error", () => resolve(false));
-    server.listen(port, host, () => {
-      server.close(() => resolve(true));
-    });
-  });
-}
-
 /**
  * Asks which port the gateway should listen on. Enter keeps 12800. The
  * candidates are probed before the prompt so the operator is told what is
@@ -205,14 +189,21 @@ function isPortFree(host: string, port: number): Promise<boolean> {
  * production build; the dashboard dev server stays on 5173 and proxies to it.
  */
 async function choosePort(envExisted: boolean): Promise<void> {
-  const alreadyChosen = envExisted && Boolean(process.env.PORT?.trim());
-  if (alreadyChosen || nonInteractive()) return;
+  if (nonInteractive()) return;
+  const currentPort = process.env.PORT?.trim() || DEFAULT_PORT;
+  if (envExisted) {
+    const answer = await ask(`Keep the current port ${currentPort}? yes / no`, "yes");
+    if (answer.toLowerCase() === "yes" || answer.toLowerCase() === "y") return;
+    if (answer.toLowerCase() !== "no" && answer.toLowerCase() !== "n") {
+      throw new Error(`Port choice must be yes or no (got "${answer}")`);
+    }
+  }
 
-  const candidates = [DEFAULT_PORT, ...PORT_SUGGESTIONS];
+  const candidates = [...new Set([currentPort, DEFAULT_PORT, ...PORT_SUGGESTIONS])];
   const states = await Promise.all(
     candidates.map(async (port) => ({
       port,
-      free: await isPortFree("127.0.0.1", Number(port)),
+      free: port === currentPort || (await probeListenPort(Number(port))).status === "free",
     })),
   );
   const free = states.filter((s) => s.free).map((s) => s.port);
@@ -230,10 +221,16 @@ async function choosePort(envExisted: boolean): Promise<void> {
   if (taken.length > 0) console.log(`In use:    ${taken.join(", ")}`);
   console.log("Pick 8080 (or any open port) when a VPS does not forward 12800.");
 
-  const answer = await ask("Port", DEFAULT_PORT);
+  const answer = await ask("Port", currentPort);
   if (!/^[1-9][0-9]{0,4}$/.test(answer) || Number(answer) > 65535) {
     throw new Error(`Port must be a number from 1 to 65535 (got "${answer}")`);
   }
+  if (answer !== currentPort) {
+    const selected = await probeListenPort(Number(answer));
+    if (selected.status === "blocked") {
+      throw new Error(`${blockedPortMessage(Number(answer))} Port selection was not saved.`);
+    }
+  }
   if (!defaultFree && answer === DEFAULT_PORT) {
     console.log(`⚠ ${DEFAULT_PORT} is in use — starting will fail unless whatever holds it is stopped first.`);
   }
@@ -302,7 +299,7 @@ async function ensureFullDatabase(timeoutMs: number): Promise<void> {
 
 export async function setup(): Promise<void> {
   console.log("🚀 Setting up Cartethyia...\n");
-  assertBunVersion();
+  await assertLocalBunVersion();
 
   // Step 1: Setup the user config file for npm installs, repo .env for dev.
   const envPath = ENV_PATH;
@@ -323,6 +320,8 @@ export async function setup(): Promise<void> {
   // Step 2: Load the file, then choose the mode. A fresh file carries the
   // example default, which is not a choice the operator made, so it is asked.
   const fileEnv = await readEnvFile(envPath);
+  // See main.ts: Bun's automatic PORT default must not mask a saved choice.
+  if (process.env.PORT === "12800") delete process.env.PORT;
   for (const [key, value] of Object.entries(fileEnv)) {
     if (!process.env[key]) process.env[key] = value;
   }
@@ -376,6 +375,8 @@ export async function setup(): Promise<void> {
     console.log("🗂️  Lite mode: embedded SQLite, no PostgreSQL to install");
     const dataDir = resolveDataDir();
     mkdirSync(dataDir, { recursive: true });
+    mkdirSync(process.env.CARTETHYIA_TELEMETRY_PAYLOAD_DIR?.trim() || resolve(dataDir, "telemetry-payloads"), { recursive: true });
+    mkdirSync(process.env.CARTETHYIA_INSTALL_ID_DIR?.trim() || resolve(dataDir, ".cartethyia"), { recursive: true });
     console.log(`✓ Data directory ready at ${dataDir}\n`);
   } else {
     console.log("🐘 Checking PostgreSQL...");
@@ -429,7 +430,7 @@ export async function setup(): Promise<void> {
     console.log("    Production. Builds the dashboard, AOT manifest, and binary first.");
     console.log("");
     console.log("  bun run dev");
-    console.log("    Development. No build; hot reload, dashboard on 5173, API on");
+    console.log("    Development. No build; hot reload, dashboard on 5173 (or 1931 if busy), API on");
     console.log(`    ${port}. Use this while changing source.`);
   }
   console.log("");

package/scripts/cli/{command/start.ts → start.ts}

@@ -1,6 +1,7 @@
-import { resolvePort } from "../../../src/config/runtime";
-import { ensureDrainToken } from "../gateway/drain-token";
-import { clearInstanceLock, pidAlive, readInstanceLock, writeInstanceLock } from "../gateway/instance-lock";
+import { resolvePort } from "../../src/config/runtime";
+import { ensureDrainToken } from "./instance";
+import { clearInstanceLock, pidAlive, readInstanceLock, writeInstanceLock } from "./instance";
+import { blockedPortMessage, listenPortErrorMessage, probeListenPort } from "./port";
 
 /**
  * Runs the gateway in the foreground, in this process.
@@ -18,10 +19,14 @@ export async function startForeground(): Promise<void> {
   const token = ensureDrainToken();
   process.env.CARTETHYIA_DRAIN_TOKEN ??= token;
   const port = resolvePort();
+  const probe = await probeListenPort(port);
+  if (probe.status === "blocked" && probe.code !== "EADDRINUSE") {
+    throw new Error(listenPortErrorMessage(port, probe));
+  }
   const blocker = await inspectPortHolder(port, token);
   if (blocker !== null) throw new Error(blocker);
   writeInstanceLock(port, process.pid, token);
-  await import("../../../src/main");
+  await import("../../src/main");
 }
 
 /**
@@ -50,7 +55,7 @@ async function inspectPortHolder(port: number, token: string): Promise<string |
     signal: AbortSignal.timeout(3_000),
   }).catch(() => null);
   if (response === null) {
-    return `Port ${port} is busy and nothing there answers a drain request. Stop whatever holds it, or set a different PORT.`;
+    return blockedPortMessage(port);
   }
   if (response.status === 401) {
     return `Another Cartethyia gateway is already running on port ${port} under a different install. Stop it from its own terminal or tray — this install will not stop a gateway it does not own.`;

package/scripts/cli/{support/startup-signal.ts → startup-signal.ts}

@@ -1,23 +1,23 @@
-import { writeFileSync } from "node:fs";
-
-/**
- * Reports tray readiness to the launcher that is waiting on a signal file.
- *
- * The tray is spawned detached with no stdio, so the launcher cannot read its
- * output; a one-shot file is the only channel that survives the parent exiting.
- * `flag: "wx"` makes the write fail rather than overwrite, which keeps a late
- * report from replacing the failure the launcher already acted on.
- */
-export type TrayStartupSignal =
-  | { readonly status: "ready"; readonly url: string }
-  | { readonly status: "failed"; readonly message: string };
-
-export function reportTrayStartup(signal: TrayStartupSignal): void {
-  const signalPath = process.env.CARTETHYIA_TRAY_STARTUP_SIGNAL;
-  if (!signalPath) return;
-  try {
-    writeFileSync(signalPath, JSON.stringify(signal), { encoding: "utf8", flag: "wx" });
-  } catch {
-    // The launcher may have timed out and removed the one-shot signal file.
-  }
-}
+import { writeFileSync } from "node:fs";
+
+/**
+ * Reports tray readiness to the launcher that is waiting on a signal file.
+ *
+ * The tray is spawned detached with no stdio, so the launcher cannot read its
+ * output; a one-shot file is the only channel that survives the parent exiting.
+ * `flag: "wx"` makes the write fail rather than overwrite, which keeps a late
+ * report from replacing the failure the launcher already acted on.
+ */
+export type TrayStartupSignal =
+  | { readonly status: "ready"; readonly url: string }
+  | { readonly status: "failed"; readonly message: string };
+
+export function reportTrayStartup(signal: TrayStartupSignal): void {
+  const signalPath = process.env.CARTETHYIA_TRAY_STARTUP_SIGNAL;
+  if (!signalPath) return;
+  try {
+    writeFileSync(signalPath, JSON.stringify(signal), { encoding: "utf8", flag: "wx" });
+  } catch {
+    // The launcher may have timed out and removed the one-shot signal file.
+  }
+}

package/scripts/cli/tray/index.ts

@@ -1,8 +1,15 @@
 import { spawn, type ChildProcess } from "node:child_process";
 import { createInterface } from "node:readline";
-import SysTray from "systray2";
+import SysTray, { type MenuItem } from "systray2";
 import { resolvePackagePath } from "../../../src/config/package-paths";
 
+/**
+ * A row as systray2 holds it. The helper numbers the rows itself and reports
+ * that number back on a click and on an update, but it is absent from the
+ * package's typings.
+ */
+type IdentifiedItem = MenuItem & { readonly __id?: number };
+
 /**
  * One tray row. `action` rows report their id on click; separators are drawn
  * but never fire.
@@ -162,33 +169,69 @@ class WindowsTray implements Tray {
 /**
  * macOS and Linux tray: `systray2` runs its own helper, and neither platform
  * attaches a console window to it, so the bundled tray is used as-is.
+ *
+ * Clicks arrive only through `onClick`; a menu built without a listener shows
+ * every row and reports none of them, which is why the callbacks are wired
+ * here rather than left to the default.
  */
 class UnixTray implements Tray {
   readonly #tray: SysTray;
+  readonly #onSelect: (id: string) => void;
+  readonly #onExit: () => void;
+  /** Row objects kept by reference: a click hands back the object, not the id. */
+  readonly #items = new Map<string, IdentifiedItem>();
+  #closed = false;
 
   constructor(options: TrayOptions) {
+    this.#onSelect = options.onSelect;
+    this.#onExit = options.onExit;
+    const items = options.items.map((item) => {
+      if (item.kind === "separator") return SysTray.separator;
+      const menuItem: IdentifiedItem = {
+        title: item.title,
+        tooltip: item.title,
+        enabled: item.enabled ?? true,
+      };
+      this.#items.set(item.id, menuItem);
+      return menuItem;
+    });
     this.#tray = new SysTray({
       menu: {
         icon: options.iconPath,
         title: "Cartethyia",
         tooltip: options.tooltip,
-        items: options.items.map((item) =>
-          item.kind === "separator"
-            ? SysTray.separator
-            : { title: item.title, tooltip: item.title, enabled: item.enabled ?? true },
-        ),
+        items,
       },
       copyDir: true,
     });
   }
 
-  ready(): Promise<void> {
-    return this.#tray.ready().then(() => undefined);
+  async ready(): Promise<void> {
+    await this.#tray.ready();
+    // Registered after `ready()`: the helper process does not exist before
+    // that, and `onExit` attaches to it directly.
+    this.#tray.onExit(() => {
+      if (!this.#closed) this.#onExit();
+    });
+    await this.#tray.onClick((action) => {
+      for (const [id, item] of this.#items) {
+        // Identity first: `onClick` merges the clicked row into the object this
+        // class built, so a match needs no assumptions about the numbering.
+        if (item === action.item || item.__id === action.__id) {
+          this.#onSelect(id);
+          return;
+        }
+      }
+    });
   }
 
   update(id: string, title: string, enabled = true): void {
-    void id;
-    void this.#tray.sendAction({ type: "update-item", item: { title, tooltip: title, enabled } });
+    const item = this.#items.get(id);
+    // An update sent before the helper reports ready carries no row number, and
+    // systray2 then rewrites the first row instead of this one.
+    if (item?.__id === undefined) return;
+    const next: IdentifiedItem = { title, tooltip: title, enabled, __id: item.__id };
+    void this.#tray.sendAction({ type: "update-item", item: next });
   }
 
   setTooltip(text: string): void {
@@ -198,9 +241,16 @@ class UnixTray implements Tray {
   }
 
   async close(): Promise<void> {
-    if (this.#tray.killed) return;
+    if (this.#closed) return;
+    this.#closed = true;
+    const helper = this.#tray.process;
+    // `kill()` settles on the helper's `exit` event, so a helper that already
+    // exited would leave it pending forever and hang the shutdown after it.
+    if (helper.exitCode !== null || helper.signalCode !== null) return;
     try {
-      this.#tray.kill();
+      // `false`: systray2 otherwise calls `process.exit(0)` when the helper
+      // exits, which discards the exit code this close was given.
+      await this.#tray.kill(false);
     } catch {
       // The helper may already be gone.
     }