cartethyia 2.4.5 → 2.4.6

package/scripts/cli/{cli-launcher.cjs → bin/cartethyia.cjs}

@@ -1,134 +1,167 @@
-#!/usr/bin/env node
-"use strict";
-
-const fs = require("node:fs");
-const { randomUUID } = require("node:crypto");
-const os = require("node:os");
-const path = require("node:path");
-const { spawn } = require("node:child_process");
-
-const packageRoot = path.resolve(__dirname, "..", "..");
-const cliPath = path.join(packageRoot, "scripts", "cli", "cli.ts");
-const configDir = process.env.CARTETHYIA_CONFIG_DIR || (
-  process.platform === "win32"
-    ? path.join(process.env.APPDATA || os.homedir(), "Cartethyia")
-    : process.platform === "darwin"
-      ? path.join(os.homedir(), "Library", "Application Support", "Cartethyia")
-      : path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "Cartethyia")
-);
-const trayMode = process.argv[2] === "tray";
-const startupSignalPath = trayMode
-  ? path.join(os.tmpdir(), `cartethyia-tray-${process.pid}-${randomUUID()}.json`)
-  : null;
-let spawnError;
-// 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;
-  if (error.code === "ENOENT") {
-    console.error("Cartethyia requires Bun 1.4.0 or newer. Install Bun from https://bun.sh, then run this command again.");
-  } else {
-    console.error(`Could not start Cartethyia's Bun runtime: ${error.message}`);
-  }
-  process.exitCode = 1;
-});
-
-if (trayMode) {
-  child.unref();
-  console.log("Loading Cartethyia…");
-  let settled = false;
-  const deadline = Date.now() + 60_000;
-  const finish = (error, url) => {
-    if (settled) return;
-    settled = true;
-    try {
-      fs.unlinkSync(startupSignalPath);
-    } catch {}
-    if (error) {
-      // `error.message` can be an empty string when the failure came from a
-      // signal rather than a thrown message, which printed as a bare
-      // "Cartethyia failed to start:" with no cause. Fall back to the code and
-      // name what usually causes it.
-      const detail =
-        error.message && error.message.trim() !== ""
-          ? error.message
-          : `the process exited without a message (code ${child.exitCode ?? "unknown"})`;
-      console.error(`Cartethyia failed to start: ${detail}`);
-      console.error(
-        "If another Cartethyia is already running on this port, stop it with `cartethyia stop` first.",
-      );
-      process.exitCode = 1;
-      if (child.exitCode === null) child.kill();
-      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;
-    if (fs.existsSync(startupSignalPath)) {
-      try {
-        const signal = JSON.parse(fs.readFileSync(startupSignalPath, "utf8"));
-        if (signal.status === "ready" && typeof signal.url === "string") {
-          finish(null, signal.url);
-          return;
-        }
-        if (signal.status === "failed" && typeof signal.message === "string") {
-          finish(new Error(signal.message));
-          return;
-        }
-      } catch {}
-    }
-    if (spawnError) {
-      finish(spawnError);
-      return;
-    }
-    if (Date.now() >= deadline) {
-      finish(new Error("startup did not complete within 60 seconds"));
-      return;
-    }
-    setTimeout(poll, 150);
-  };
-  child.once("exit", (code, signal) => {
-    if (!settled) setTimeout(() => finish(new Error(`the tray process exited before readiness (code ${code ?? signal ?? "unknown"})`)), 250);
-  });
-  poll();
-} else {
-  child.once("exit", (code, signal) => {
-    if (signal) {
-      process.kill(process.pid, signal);
-      return;
-    }
-    process.exitCode = code ?? 1;
-  });
-}
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const { randomUUID } = require("node:crypto");
+const os = require("node:os");
+const path = require("node:path");
+const { spawn } = require("node:child_process");
+
+const packageRoot = path.resolve(__dirname, "..", "..", "..");
+const cliPath = path.join(packageRoot, "scripts", "cli", "main.ts");
+const configDir = process.env.CARTETHYIA_CONFIG_DIR || (
+  process.platform === "win32"
+    ? path.join(process.env.APPDATA || os.homedir(), "Cartethyia")
+    : process.platform === "darwin"
+      ? path.join(os.homedir(), "Library", "Application Support", "Cartethyia")
+      : path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "Cartethyia")
+);
+const trayMode = process.argv[2] === "tray";
+// The launcher itself runs under Node, so `process.execPath` is node.exe — not
+// the Bun the child needs. Resolve bun from PATH instead; WScript.Shell does
+// not inherit this process's environment, so the child needs an absolute path.
+function resolveBunPath() {
+  if (process.env.CARTETHYIA_BUN) return process.env.CARTETHYIA_BUN;
+  const name = process.platform === "win32" ? "bun.exe" : "bun";
+  for (const dir of (process.env.PATH || "").split(path.delimiter)) {
+    if (!dir) continue;
+    const candidate = path.join(dir, name);
+    try {
+      if (fs.statSync(candidate).isFile()) return candidate;
+    } catch {}
+  }
+  return name;
+}
+
+const startupSignalPath = trayMode
+  ? path.join(os.tmpdir(), `cartethyia-tray-${process.pid}-${randomUUID()}.json`)
+  : null;
+let spawnError;
+// On Windows the tray must start with no console at all, and neither
+// `detached: true` nor `windowsHide: true` achieves that: a console-subsystem
+// child of a window-less parent still allocates a console, and inside Windows
+// Terminal the tab is already on screen before a flag can take effect
+// (measured). `wscript.exe` is GUI-subsystem, so it never allocates one, and a
+// child launched from it with window style 0 inherits that. Elsewhere
+// `detached: true` is enough.
+const useWindowsDetach = process.platform === "win32" && trayMode;
+const hiddenLauncher = path.join(packageRoot, "scripts", "cli", "tray", "hidden-window.vbs");
+const child = useWindowsDetach
+  ? spawn(
+      "wscript.exe",
+      // Absolute path, not "bun": the VBS runs through WScript.Shell, which
+      // does not inherit this process's PATH additions and resolves a bare
+      // name against the system PATH only.
+      ["//nologo", hiddenLauncher, resolveBunPath(), "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(resolveBunPath(), ["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;
+  if (error.code === "ENOENT") {
+    console.error("Cartethyia requires Bun 1.4.0 or newer. Install Bun from https://bun.sh, then run this command again.");
+  } else {
+    console.error(`Could not start Cartethyia's Bun runtime: ${error.message}`);
+  }
+  process.exitCode = 1;
+});
+
+if (trayMode) {
+  child.unref();
+  console.log("Loading Cartethyia…");
+  let settled = false;
+  const deadline = Date.now() + 60_000;
+  const finish = (error, url) => {
+    if (settled) return;
+    settled = true;
+    try {
+      fs.unlinkSync(startupSignalPath);
+    } catch {}
+    if (error) {
+      // `error.message` can be an empty string when the failure came from a
+      // signal rather than a thrown message, which printed as a bare
+      // "Cartethyia failed to start:" with no cause. Fall back to the code and
+      // name what usually causes it.
+      const detail =
+        error.message && error.message.trim() !== ""
+          ? error.message
+          : `the process exited without a message (code ${child.exitCode ?? "unknown"})`;
+      console.error(`Cartethyia failed to start: ${detail}`);
+      console.error(
+        "If another Cartethyia is already running on this port, stop the terminal that started it first.",
+      );
+      process.exitCode = 1;
+      if (child.exitCode === null) child.kill();
+      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;
+    if (fs.existsSync(startupSignalPath)) {
+      try {
+        const signal = JSON.parse(fs.readFileSync(startupSignalPath, "utf8"));
+        if (signal.status === "ready" && typeof signal.url === "string") {
+          finish(null, signal.url);
+          return;
+        }
+        if (signal.status === "failed" && typeof signal.message === "string") {
+          finish(new Error(signal.message));
+          return;
+        }
+      } catch {}
+    }
+    if (spawnError) {
+      finish(spawnError);
+      return;
+    }
+    if (Date.now() >= deadline) {
+      finish(new Error("startup did not complete within 60 seconds"));
+      return;
+    }
+    setTimeout(poll, 150);
+  };
+  // On Windows the spawned process is `wscript.exe`, which hands off to the
+  // tray and exits immediately — a successful handoff, not a failed start. Only
+  // a direct spawn's exit says anything about the tray, so the deadline covers
+  // the handoff case and this guard covers the direct one.
+  if (!useWindowsDetach) {
+    child.once("exit", (code, signal) => {
+      if (!settled) setTimeout(() => finish(new Error(`the tray process exited before readiness (code ${code ?? signal ?? "unknown"})`)), 250);
+    });
+  }
+  poll();
+} else {
+  child.once("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exitCode = code ?? 1;
+  });
+}

package/scripts/cli/command/admin.ts

@@ -0,0 +1,65 @@
+/**
+ * The two admin actions the menu and the tray both offer.
+ *
+ * Both go through the running gateway rather than the database file: the
+ * gateway holds the connection and the schema is dialect-dependent, so reading
+ * or writing the tables from this process would need a second implementation
+ * of both.
+ */
+
+/**
+ * Asks the gateway to write a gzipped config backup into the download
+ * directory. Returns the written path and counts, or null when it failed.
+ */
+export async function exportBackup(
+  port: number,
+  token: string,
+): Promise<{ path: string; bytes: number; counts: Record<string, number> } | null> {
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/admin/export-backup`, {
+      method: "POST",
+      headers: { "content-type": "application/json", "x-drain-token": token },
+      body: JSON.stringify({}),
+      signal: AbortSignal.timeout(60_000),
+    });
+    if (!response.ok) {
+      const detail = await response.text().catch(() => "");
+      console.error(`The gateway refused the backup (HTTP ${response.status}). ${detail}`.trim());
+      return null;
+    }
+    return (await response.json()) as {
+      path: string;
+      bytes: number;
+      counts: Record<string, number>;
+    };
+  } catch {
+    console.error("Could not reach the gateway. Is it still running?");
+    return null;
+  }
+}
+
+/**
+ * Posts the console-account reset to the running gateway.
+ *
+ * Returns 0 on success and 1 on any failure so the caller can print one line
+ * either way.
+ */
+export async function resetConsoleAccount(port: number, token: string): Promise<number> {
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/admin/reset-console-account`, {
+      method: "POST",
+      headers: { "content-type": "application/json", "x-drain-token": token },
+      body: JSON.stringify({ confirm: "RESET" }),
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) {
+      const detail = await response.text().catch(() => "");
+      console.error(`The gateway refused the reset (HTTP ${response.status}). ${detail}`.trim());
+      return 1;
+    }
+    return 0;
+  } catch {
+    console.error("Could not reach the gateway. Is it still running?");
+    return 1;
+  }
+}

package/scripts/cli/command/console-menu.ts

@@ -0,0 +1,227 @@
+import { existsSync } from "node:fs";
+import { isNewerRelease } from "../../../src/console/updates/version-compare";
+import { resolvePackagePath } from "../../../src/config/package-paths";
+import { resolvePort } from "../../../src/config/runtime";
+import { ensureDrainToken } from "../gateway/drain-token";
+import { startGateway } from "../gateway/spawn";
+import { stopGateway } from "../gateway/stop";
+import { ENV_PATH, readEnvFile } from "../support/env";
+import { readInstalledVersion, readLatestPublishedVersion } from "../support/version";
+import { launchBackground, openUrl } from "../ui/background";
+import { chooseFromMenu, confirmByTyping, confirmStep } from "../ui/prompt";
+import { renderWordmark } from "../ui/wordmark";
+import { exportBackup, resetConsoleAccount } from "./admin";
+import { updateCommand } from "./update";
+
+/**
+ * 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.
+ */
+export async function startMenu(): Promise<void> {
+  // A fresh install has no config file yet, and the gateway refuses to boot
+  // without CARTETHYIA_DB_MODE — which surfaced as a stack trace about a
+  // missing database mode rather than "you have not set this up". Run setup
+  // first, the way `carte` is expected to behave on a new install.
+  const configured = existsSync(ENV_PATH) && (await readEnvFile(ENV_PATH)).CARTETHYIA_DB_MODE;
+  if (!configured) {
+    console.log(
+      existsSync(ENV_PATH)
+        ? "Cartethyia is missing its database mode. Starting setup.\n"
+        : "Cartethyia is not set up yet. Starting setup.\n",
+    );
+    // Dynamic on purpose: `setup` pulls in the whole wizard and the database
+    // mode resolver, and it is only reachable on a first run. A static import
+    // would pay that cost on every `carte`, which is the one path that has to
+    // stay fast.
+    const { setup } = await import("./setup");
+    await setup();
+    const after = existsSync(ENV_PATH) ? (await readEnvFile(ENV_PATH)).CARTETHYIA_DB_MODE : undefined;
+    if (!after) {
+      console.error(
+        `Setup did not record CARTETHYIA_DB_MODE in ${ENV_PATH}; run \`cartethyia setup\` and try again.`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+    process.env.CARTETHYIA_DB_MODE = after;
+  }
+
+  const port = resolvePort();
+  const drainToken = ensureDrainToken();
+  const dashboardUrl = `http://127.0.0.1:${port}/console`;
+  const currentVersion = await readInstalledVersion();
+
+  // The gateway starts in the background: the menu is usable before it has
+  // finished booting, and awaiting it cost ~670 ms of blank terminal on every
+  // start. `ready` resolves when the health probe passes; actions that need a
+  // listening gateway await it, so nothing races.
+  const ready = startGateway(port, drainToken);
+  let gateway: Bun.Subprocess | null = null;
+  void ready.then((child) => {
+    gateway = child;
+    child.unref();
+  }).catch((error: unknown) => {
+    console.error(
+      `The gateway did not start: ${error instanceof Error ? error.message : "unknown error"}`,
+    );
+  });
+
+  let stopping = false;
+  let handedOff = false;
+  const shutDown = async (): Promise<void> => {
+    if (stopping) return;
+    stopping = true;
+    const child = gateway ?? (await ready.catch(() => null));
+    if (child) await stopGateway(child, port, drainToken);
+  };
+  // Ctrl-C has to stop the gateway, and the drain endpoint cannot be called
+  // from an exit path: it is async, and enquirer's own Ctrl-C handler calls
+  // process.exit(130) while a prompt is live. So the gateway is a child in this
+  // process group — a terminal's Ctrl-C signals the whole group, and the
+  // gateway drains through the SIGINT handler it already has in src/main.ts —
+  // and `process.on("exit")` is the synchronous backstop for every other way
+  // this process can end (a closed terminal, a crash, a signal Bun cannot
+  // deliver on Windows). That handler can only call synchronous APIs, which is
+  // why it signals the child rather than awaiting the drain endpoint.
+  // `handedOff` is set by "Hide to tray": the gateway is being given to a tray
+  // that will own it, so this process must not kill it on the way out.
+  process.on("exit", () => {
+    if (stopping || handedOff || gateway === null) return;
+    try {
+      gateway.kill();
+    } catch {
+      // Already gone; nothing to stop.
+    }
+  });
+  const interrupt = async (): Promise<void> => {
+    process.stdout.write("\u001b[2J\u001b[H");
+    console.log("Stopping Cartethyia…");
+    await shutDown();
+    process.exit(0);
+  };
+  process.on("SIGTERM", () => void interrupt());
+  process.on("SIGINT", () => void interrupt());
+
+  let latestVersion = await readLatestPublishedVersion();
+  let running = true;
+
+  const header = [...renderWordmark(), `Cartethyia ${currentVersion} \u00b7 ${dashboardUrl}`];
+
+  while (running) {
+    const upToDate = latestVersion === null || !isNewerRelease(currentVersion, latestVersion);
+    const updateLabel =
+      latestVersion === null
+        ? "Check for updates"
+        : upToDate
+          ? `Up to date (${currentVersion})`
+          : `Update to ${latestVersion}`;
+
+    // Anything that talks to the gateway waits for it to be listening; the menu
+    // itself does not.
+    const whenReady = async (): Promise<void> => {
+      await ready.catch(() => undefined);
+    };
+
+    const actions: readonly (() => Promise<void>)[] = [
+      async () => openUrl(dashboardUrl),
+      async () => {
+        // Deleting the console account is the only real password recovery:
+        // /change-password needs the current password, and first-boot setup
+        // only runs when no user exists. Removing the user puts the wizard
+        // back. Providers, keys, and routing are untouched.
+        console.log("");
+        console.log("This deletes every console account and its sessions.");
+        console.log("The next visit to /console asks you to create a new one.");
+        console.log("Providers, API keys, and routing are not touched.");
+        console.log("");
+        if (!(await confirmStep("Continue with the reset?"))) {
+          console.log("Cancelled.");
+          return;
+        }
+        if (!(await confirmByTyping("RESET", "Confirm deleting the console account"))) {
+          console.log("Cancelled.");
+          return;
+        }
+        await whenReady();
+        const status = await resetConsoleAccount(port, drainToken);
+        console.log(
+          status === 0
+            ? `Console account removed. Open ${dashboardUrl} to create a new one.`
+            : "Reset failed; see the gateway log.",
+        );
+      },
+      async () => {
+        // Export straight to the download directory. The console page asks for
+        // the operator password, which is exactly the thing a locked-out
+        // operator does not have; the CLI already runs as the OS user who owns
+        // the database, so the loopback token is the whole gate.
+        await whenReady();
+        const result = await exportBackup(port, drainToken);
+        if (result === null) return;
+        console.log(
+          `Backup written to ${result.path} (${(result.bytes / 1024).toFixed(1)} KiB, ${Object.keys(result.counts).length} tables).`,
+        );
+        console.log("Telemetry is not included: it is per-request history, not configuration.");
+      },
+      async () => {
+        if (upToDate) return;
+        // npm cannot replace this package's directory while this process is
+        // running out of it: on Windows the rename fails with EBUSY and npm
+        // exits 14. Even with the gateway stopped, the CLI itself is executing
+        // from that directory, so an in-process install can never succeed.
+        // Print the command and exit, the way 9router does.
+        await shutDown();
+        console.log("");
+        console.log(`Update available: ${currentVersion} \u2192 ${latestVersion}`);
+        console.log("");
+        console.log("Run this now that Cartethyia has stopped:");
+        console.log("");
+        console.log(`   ${updateCommand()}`);
+        console.log("");
+        running = false;
+        process.exitCode = 0;
+        return;
+      },
+      async () => {
+        // Start a detached `tray` process that owns the gateway from scratch,
+        // then drain this one so the new process can claim the port. This is
+        // the pattern 9router uses and it is simpler than handing a live
+        // gateway between processes: the tray is a normal first-class run, not
+        // an adopted orphan, so Exit and update behave the same whether the
+        // gateway was started here or from `carte --tray`.
+        console.log("Starting the tray in the background…");
+        launchBackground(["run", resolvePackagePath("scripts", "cli", "main.ts"), "tray"]);
+        running = false;
+        stopping = true;
+        handedOff = true;
+        await shutDown();
+        console.log(`Cartethyia is running in the background at ${dashboardUrl}.`);
+        console.log("The tray icon owns it; use Exit there to stop it.");
+      },
+      async () => {
+        running = false;
+      },
+    ];
+
+    const choice = await chooseFromMenu(header, [
+        { kind: "action", label: "Open Console", hint: `browser \u00b7 ${dashboardUrl}` },
+        { kind: "action", label: "Reset console password", hint: "deletes the account" },
+        { kind: "action", label: "Backup", hint: "export config to Downloads" },
+        { kind: "action", label: updateLabel, hint: upToDate ? "open the repository" : "installs now" },
+        { kind: "action", label: "Hide to tray", hint: "keep the gateway running" },
+        { kind: "rule" },
+        { kind: "action", label: "Exit", hint: "stop the gateway" },
+      ],
+    );
+    if (choice === -1) break;
+    const action = actions[choice];
+    if (action) await action();
+  }
+  // "Hide to tray" has already given the gateway to the tray. Draining here
+  // would stop the very process the tray just adopted, which is why the menu
+  // appeared to hand over a gateway that was not listening.
+  if (handedOff) return;
+  await shutDown();
+}