cartethyia 2.3.2 → 2.3.4

package/scripts/cli/cli.ts

@@ -8,6 +8,13 @@ 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";
+import { chooseFromMenu } from "./menu";
+import {
+  clearPersistedDrainToken,
+  readPersistedDrainToken,
+  writePersistedDrainToken,
+} from "./runtime-state";
+import { npmUpdate, readInstalledVersion, readLatestPublishedVersion } from "./version";
 
 process.env.CARTETHYIA_CONFIG_DIR ??= resolveUserConfigDir();
 
@@ -19,7 +26,7 @@ Usage:
   cartethyia setup [--non-interactive]
   cartethyia start
   cartethyia menu
-  cartethyia tray
+  cartethyia stop           stop a gateway left running in the background
   cartethyia update
 
 carte starts the gateway and opens a menu driven by the arrow keys and Enter:
@@ -48,6 +55,7 @@ async function loadUserConfig(): Promise<void> {
   }
 }
 
+
 type TrayStartupSignal =
   | { readonly status: "ready"; readonly url: string }
   | { readonly status: "failed"; readonly message: string };
@@ -93,29 +101,6 @@ async function waitForTrayStartupSignal(
   throw new Error("Cartethyia did not finish tray and gateway startup within 45 seconds");
 }
 
-function npmUpdate(): Promise<number> {
-  return new Promise((resolveExit) => {
-    const command = process.platform === "win32"
-      ? "cmd.exe"
-      : "npm";
-    const args = process.platform === "win32"
-      ? ["/d", "/s", "/c", "npm install --global cartethyia@latest"]
-      : ["install", "--global", "cartethyia@latest"];
-    let child;
-    try {
-      child = spawn(command, args, { cwd: tmpdir(), stdio: "inherit" });
-    } catch {
-      console.error("Could not start npm. Install Node.js with npm, then retry the update.");
-      resolveExit(1);
-      return;
-    }
-    child.once("error", () => {
-      console.error("Could not start npm. Install Node.js with npm, then retry the update.");
-      resolveExit(1);
-    });
-    child.once("exit", (code) => resolveExit(code ?? 1));
-  });
-}
 
 function openUrl(url: string): Promise<void> {
   const command = process.platform === "win32"
@@ -131,84 +116,6 @@ 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";
-}
-
-async function readInstalledVersion(): Promise<string> {
-  const metadata: unknown = await Bun.file(resolvePackagePath("package.json")).json();
-  if (!isRecord(metadata) || typeof metadata["version"] !== "string") {
-    throw new Error("Cartethyia package version is unavailable");
-  }
-  return metadata["version"];
-}
-
-async function readLatestPublishedVersion(): Promise<string | null> {
-  try {
-    const response = await fetch("https://registry.npmjs.org/cartethyia/latest", {
-      signal: AbortSignal.timeout(4_000),
-    });
-    if (!response.ok) return null;
-    const metadata: unknown = await response.json();
-    return isRecord(metadata) && typeof metadata["version"] === "string" ? metadata["version"] : null;
-  } catch {
-    return null;
-  }
-}
 
 function launchUpdatedTray(signalPath: string): ChildProcess {
   const env = { ...process.env, CARTETHYIA_TRAY_STARTUP_SIGNAL: signalPath };
@@ -227,7 +134,11 @@ async function startGateway(port: number, drainToken: string): Promise<ReturnTyp
     {
       cwd: PACKAGE_ROOT,
       env: { ...process.env, CARTETHYIA_DRAIN_TOKEN: drainToken },
-      stdin: "inherit",
+      // "ignore", not "inherit": the gateway does not read stdin, and in menu
+      // mode the menu is the only stdin consumer. With "inherit" the gateway
+      // held the fd and swallowed every keypress after the first, so the menu
+      // rendered but never received Enter.
+      stdin: "ignore",
       stdout: "inherit",
       stderr: "inherit",
     },
@@ -402,9 +313,13 @@ async function startMenu(): Promise<void> {
       continue;
     }
     if (choice === 2) {
-      // The gateway is already a detached child, so returning here leaves it
-      // running while this process lets go of the terminal.
-      console.log(`Cartethyia keeps running at ${dashboardUrl}. Stop it with: cartethyia stop`);
+      // 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) {
@@ -412,9 +327,44 @@ async function startMenu(): Promise<void> {
       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 port = resolvePort();
   const drainToken = randomBytes(32).toString("hex");
@@ -660,7 +610,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" || command === "menu") {
+  if (command === "setup" || command === "start" || command === "tray" || command === "menu" || command === "stop") {
     await loadUserConfig();
   }
 
@@ -679,6 +629,9 @@ async function main(): Promise<void> {
     case "tray":
       await startTray();
       return;
+    case "stop":
+      process.exitCode = await stopRunningGateway();
+      return;
     case "update": {
       const code = await npmUpdate();
       if (code !== 0) process.exitCode = code;

package/scripts/cli/menu.ts

@@ -0,0 +1,53 @@
+/**
+ * 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.
+ */
+export 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;
+}

package/scripts/cli/runtime-state.ts

@@ -0,0 +1,62 @@
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * 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 statePath(): string | null {
+  const configDir = process.env.CARTETHYIA_CONFIG_DIR;
+  return configDir ? join(configDir, RUNTIME_STATE_FILE) : null;
+}
+
+/** Persists the drain token so a later `cartethyia stop` can reach the gateway. */
+export function writePersistedDrainToken(token: string): void {
+  const path = statePath();
+  if (path === null) return;
+  try {
+    writeFileSync(path, JSON.stringify({ drainToken: token }), {
+      encoding: "utf8",
+      mode: 0o600,
+    });
+  } catch {
+    // A read-only config directory costs only the `stop` command, not startup.
+  }
+}
+
+/** Returns the token for a background gateway, or null when there is none. */
+export function readPersistedDrainToken(): string | null {
+  const path = statePath();
+  if (path === null || !existsSync(path)) return null;
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+    if (
+      parsed !== null &&
+      typeof parsed === "object" &&
+      "drainToken" in parsed &&
+      typeof parsed.drainToken === "string"
+    ) {
+      return parsed.drainToken;
+    }
+  } catch {
+    // A corrupt or stale state file reads as "no background gateway".
+  }
+  return null;
+}
+
+/** Removes the token once the drain has been accepted. */
+export function clearPersistedDrainToken(): void {
+  const path = statePath();
+  if (path === null) return;
+  try {
+    unlinkSync(path);
+  } catch {
+    // Best effort: the drain request already succeeded.
+  }
+}

package/scripts/cli/version.ts

@@ -0,0 +1,66 @@
+import { spawn } from "node:child_process";
+import { tmpdir } from "node:os";
+import { resolvePackagePath } from "../../src/config/package-paths";
+
+/** Reads the version from the installed package manifest. */
+export async function readInstalledVersion(): Promise<string> {
+  const metadata: unknown = await Bun.file(resolvePackagePath("package.json")).json();
+  if (
+    metadata === null ||
+    typeof metadata !== "object" ||
+    !("version" in metadata) ||
+    typeof metadata.version !== "string"
+  ) {
+    throw new Error("Cartethyia package version is unavailable");
+  }
+  return metadata.version;
+}
+
+/** Asks the npm registry for the newest published version, or null on failure. */
+export async function readLatestPublishedVersion(): Promise<string | null> {
+  try {
+    const response = await fetch("https://registry.npmjs.org/cartethyia/latest", {
+      signal: AbortSignal.timeout(4_000),
+    });
+    if (!response.ok) return null;
+    const metadata: unknown = await response.json();
+    if (
+      metadata !== null &&
+      typeof metadata === "object" &&
+      "version" in metadata &&
+      typeof metadata.version === "string"
+    ) {
+      return metadata.version;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Runs `npm install --global cartethyia@latest`. On Windows npm is a shell
+ * script, so it has to go through cmd.exe rather than being spawned directly.
+ */
+export function npmUpdate(): Promise<number> {
+  return new Promise((resolveExit) => {
+    const command = process.platform === "win32" ? "cmd.exe" : "npm";
+    const args =
+      process.platform === "win32"
+        ? ["/d", "/s", "/c", "npm install --global cartethyia@latest"]
+        : ["install", "--global", "cartethyia@latest"];
+    let child;
+    try {
+      child = spawn(command, args, { cwd: tmpdir(), stdio: "inherit" });
+    } catch {
+      console.error("Could not start npm. Install Node.js with npm, then retry the update.");
+      resolveExit(1);
+      return;
+    }
+    child.once("error", () => {
+      console.error("Could not start npm. Install Node.js with npm, then retry the update.");
+      resolveExit(1);
+    });
+    child.once("exit", (code) => resolveExit(code ?? 1));
+  });
+}