cartethyia 2.5.9 → 2.6.0

package/scripts/cli/console-menu.ts

@@ -1,275 +1,308 @@
-import { existsSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { randomUUID } from "node:crypto";
-import { isNewerRelease } from "../../src/console/updates/version-compare";
-import { resolvePackagePath } from "../../src/config/package-paths";
-import { resolvePort } from "../../src/config/runtime";
-import { ensureDrainToken } from "./instance";
-import { attachGateway, stopAttachedGateway, type RunningGateway } from "./instance";
-import { startGateway } from "./gateway";
-import { stopGateway } from "./gateway";
-import { ENV_PATH, readEnvFile } from "./env";
-import { readInstalledVersion, readLatestPublishedVersion } from "./version";
-import { launchBackgroundWithStatus, openUrl } from "./background";
-import { chooseFromMenu, confirmByTyping, confirmStep } from "./prompt";
-import { renderWordmark } from "./wordmark";
-import { exportBackup, resetConsoleAccount } from "./admin";
-import { runDetachedUpdate } 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();
-
-  // Reattach without draining a healthy instance. A new child must either be
-  // ready or produce its actionable failure before the menu is shown; otherwise
-  // the UI offers gateway actions for a process that already exited.
-  const attached = await attachGateway(port, drainToken);
-  let startupError: unknown = null;
-  const ready: Promise<Bun.Subprocess | null> = attached
-    ? Promise.resolve(null)
-    : startGateway(port, drainToken).catch((error: unknown) => {
-      startupError = error;
-      return null;
-    });
-  let gateway: Bun.Subprocess | null = null;
-  const runningAttached: RunningGateway | null = attached;
-  void ready.then((child) => {
-    if (child === null) return;
-    gateway = child;
-    child.unref();
-  }).catch((error: unknown) => {
-    console.error(`The gateway did not start: ${error instanceof Error ? error.message : "unknown error"}`);
-  });
-
-  if (!attached) {
-    await ready;
-    if (startupError !== null) {
-      const detail = startupError instanceof Error ? startupError.message : "unknown startup error";
-      console.error(`The gateway did not start on port ${port}.\n${detail}`);
-      console.error("Fix the reported issue, then run `carte` again.");
-      process.exitCode = 1;
-      return;
-    }
-  }
-
-  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);
-    else if (runningAttached) await stopAttachedGateway(runningAttached, drainToken);
-  };
-  const detachAttached = (): void => {
-    if (runningAttached !== null) stopping = true;
-  };
-  // 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 || runningAttached !== null) return;
-    try {
-      gateway.kill();
-    } catch {
-      // Already gone; nothing to stop.
-    }
-  });
-  const interrupt = async (): Promise<void> => {
-    if (runningAttached !== null) {
-      detachAttached();
-      process.exit(0);
-    }
-    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();
-        runDetachedUpdate();
-        console.log("");
-        console.log(`Update available: ${currentVersion} \u2192 ${latestVersion}`);
-        console.log("Detached update started; this process will exit now.");
-        console.log("Re-run `carte` after it finishes.");
-        console.log("");
-        running = false;
-        process.exit(0);
-      },
-      async () => {
-        // Drain first, then start the tray.
-        //
-        // The tray's own startup probe refuses to boot when the port is busy,
-        // so starting it before this process has let go made it fail with
-        // "already running on port" every time — while the menu still printed
-        // that everything was running, because a detached child with no stdio
-        // cannot report anything back. Releasing the port first is the fix, and
-        // waiting on the child's signal is what stops the menu from claiming
-        // success for a child that died.
-        console.log("Stopping the gateway to free the port…");
-        running = false;
-        stopping = true;
-        handedOff = true;
-        await shutDown();
-        console.log("Starting the tray in the background…");
-        const signalPath = join(tmpdir(), `cartethyia-tray-menu-${process.pid}-${randomUUID()}.json`);
-        try {
-          const url = await launchBackgroundWithStatus(
-            ["run", resolvePackagePath("scripts", "cli", "main.ts"), "tray"],
-            { signalPath },
-          );
-          console.log(`Cartethyia is running in the background at ${url || dashboardUrl}.`);
-          console.log("The tray icon owns it; use Exit there to stop it.");
-        } catch (error) {
-          handedOff = false;
-          console.error(
-            `Could not hand off to the tray: ${error instanceof Error ? error.message : "unknown error"}`,
-          );
-          console.error("Cartethyia is stopped. Start it again from this menu.");
-        }
-      },
-      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;
-  if (runningAttached !== null) {
-    detachAttached();
-    return;
-  }
-  await shutDown();
-}
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { isNewerRelease } from "../../src/console/updates/version-compare";
+import { resolvePackagePath } from "../../src/config/package-paths";
+import { resolvePort } from "../../src/config/runtime";
+import { ensureDrainToken } from "./instance";
+import { attachGateway, stopAttachedGateway, type RunningGateway } from "./instance";
+import { startGateway } from "./gateway";
+import { stopGateway } from "./gateway";
+import { ENV_PATH, readEnvFile } from "./env";
+import { readInstalledVersion, readLatestPublishedVersion } from "./version";
+import { launchBackgroundWithStatus, openUrl } from "./background";
+import { chooseFromMenu, confirmByTyping, confirmStep, type MenuRow } from "./prompt";
+import { renderWordmark } from "./wordmark";
+import { exportBackup, resetConsoleAccount } from "./admin";
+import { runDetachedUpdate } from "./update";
+import { acquireController } from "./controller";
+import { restoreControllerAfterFailedHandoff } from "./controller";
+import { attachGateway as attachRunningGateway } from "./instance";
+
+
+/**
+ * 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> {
+  const controller = acquireController("menu");
+  const releaseController = (): void => controller.release();
+  process.once("exit", releaseController);
+  try {
+    await runMenu(controller.handoff);
+  } finally {
+    controller.release();
+    process.removeListener("exit", releaseController);
+  }
+}
+
+async function runMenu(handoff: { readonly token: string; readonly parentPid: number }): 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-import: `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();
+
+  // Reattach without draining a healthy instance. A new child must either be
+  // ready or produce its actionable failure before the menu is shown; otherwise
+  // the UI offers gateway actions for a process that already exited.
+  const attached = await attachGateway(port, drainToken);
+  let startupError: unknown = null;
+  const ready: Promise<Bun.Subprocess | null> = attached
+    ? Promise.resolve(null)
+    : startGateway(port, drainToken).catch((error: unknown) => {
+      startupError = error;
+      return null;
+    });
+  let gateway: Bun.Subprocess | null = null;
+  const runningAttached: RunningGateway | null = attached;
+  void ready.then((child) => {
+    if (child === null) return;
+    gateway = child;
+    child.unref();
+  }).catch((error: unknown) => {
+    console.error(`The gateway did not start: ${error instanceof Error ? error.message : "unknown error"}`);
+  });
+
+  if (!attached) {
+    await ready;
+    if (startupError !== null) {
+      const detail = startupError instanceof Error ? startupError.message : "unknown startup error";
+      console.error(`The gateway did not start on port ${port}.\n${detail}`);
+      console.error("Fix the reported issue, then run `carte` again.");
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  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);
+    else if (runningAttached) await stopAttachedGateway(runningAttached, drainToken);
+  };
+  const detachAttached = (): void => {
+    if (runningAttached !== null) stopping = true;
+  };
+  // 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 || runningAttached !== null) return;
+    try {
+      gateway.kill();
+    } catch {
+      // Already gone; nothing to stop.
+    }
+  });
+  const interrupt = async (): Promise<void> => {
+    if (runningAttached !== null) {
+      detachAttached();
+      process.exit(0);
+    }
+    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;
+  let backupStatus: { readonly tone: "success" | "error"; readonly text: string } | undefined;
+
+  while (running) {
+    const upToDate = latestVersion === null || !isNewerRelease(currentVersion, latestVersion);
+    // Header-line version checker. When something newer is published the line
+    // calls it out and the menu adds an `Update to X.Y.Z` row that the arrow
+    // keys land on by default — the operator still has to press Enter, so a
+    // reflex Enter cannot run an update by accident, but attention is on the
+    // action that matters.
+    const versionCheckerLine =
+      latestVersion === null
+        ? `${currentVersion} \u00b7 registry unavailable`
+        : upToDate
+          ? `${currentVersion} \u00b7 up to date`
+          : `${currentVersion} \u2192 ${latestVersion} available`;
+    const header = [
+      ...renderWordmark(),
+      `Console  ${dashboardUrl}`,
+      `Version  ${versionCheckerLine}`,
+      "",
+    ];
+
+    // 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 () => {
+        // Transfer the live gateway rather than draining it first. The tray
+        // adopts this instance through the ownership marker and reports ready
+        // before the menu returns to the shell.
+        running = false;
+        stopping = true;
+        handedOff = true;
+        console.log("Starting the tray in the background…");
+        const signalPath = join(tmpdir(), `cartethyia-tray-menu-${process.pid}-${randomUUID()}.json`);
+        try {
+          const url = await launchBackgroundWithStatus(
+            ["run", resolvePackagePath("scripts", "cli", "main.ts"), "tray"],
+            { signalPath, controllerHandoff: handoff },
+          );
+          console.log(`Cartethyia is running in the background at ${url || dashboardUrl}.`);
+          console.log("The tray icon owns it; use Exit there to stop it.");
+        } catch (error) {
+          restoreControllerAfterFailedHandoff(handoff);
+          handedOff = false;
+          console.error(
+            `Could not hand off to the tray: ${error instanceof Error ? error.message : "unknown error"}`,
+          );
+          console.error("Cartethyia is stopped. Start it again from this menu.");
+        }
+      },
+      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);
+        backupStatus = "error" in result
+          ? { tone: "error", text: `Backup failed: ${result.error}` }
+          : {
+              tone: "success",
+              text: `Backup saved at: ${result.path} (${(result.bytes / 1024).toFixed(1)} KiB)`,
+            };
+      },
+      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 () => {
+        running = false;
+      },
+    ];
+    // The Update action is only wired in when there is something newer to go
+    // to; otherwise the menu's up-to-date state is already told by the header
+    // line and an extra row would be noise.
+    const updateAction = async (): Promise<void> => {
+      if (upToDate || latestVersion === null) 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();
+      runDetachedUpdate();
+      console.log("");
+      console.log(`Update available: ${currentVersion} \u2192 ${latestVersion}`);
+      console.log("Detached update started; this process will exit now.");
+      console.log("Re-run `carte` after it finishes.");
+      console.log("");
+      running = false;
+      process.exit(0);
+    };
+    const extendedActions: readonly (() => Promise<void>)[] = upToDate
+      ? actions
+      : [...actions.slice(0, actions.length - 1), updateAction, actions[actions.length - 1] ?? (async () => undefined)];
+
+    const rows: MenuRow[] = [
+      { kind: "action", label: "Open Console", hint: "Open dashboard in browser" },
+      { kind: "action", label: "Hide to Tray", hint: "Keep the gateway running" },
+      { kind: "action", label: "Backup", hint: "Export config to Downloads" },
+      { kind: "action", label: "Reset", hint: "Delete console account" },
+    ];
+    if (!upToDate && latestVersion !== null) {
+      rows.push({ kind: "action", label: `Update to ${latestVersion}`, hint: "installs now and exits" });
+    }
+    rows.push({ kind: "rule" });
+    rows.push({ kind: "action", label: "Exit", hint: "Stop the gateway" });
+
+    // Focus the Update row by default when it exists, so the operator who
+    // launched `carte` *because* they saw the version checker gets a one-key
+    // path to the fix.
+    const updateIndex = upToDate || latestVersion === null ? -1 : 4;
+    const initialActionIndex = updateIndex >= 0 ? updateIndex : 0;
+    const choice = await chooseFromMenu(header, rows, { initialIndex: initialActionIndex, ...(backupStatus ? { status: backupStatus } : {}) });
+    if (choice === -1) break;
+    const action = extendedActions[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;
+  if (runningAttached !== null || (await attachRunningGateway(port, drainToken)) !== null) {
+    detachAttached();
+    return;
+  }
+  await shutDown();
+}