cartethyia 2.5.8 → 2.5.10

package/scripts/cli/prompt.ts

@@ -1,107 +1,137 @@
-import Enquirer from "enquirer";
-
-/**
- * One row in a menu: an action the caller can run, or a rule between groups.
- *
- * Rules are rendered by `enquirer`'s own separator role and are never
- * selectable, so the caller's action list stays a plain array indexed by the
- * rows the operator can actually pick.
- */
-export type MenuRow =
-  | { readonly kind: "action"; readonly label: string; readonly hint?: string }
-  | { readonly kind: "rule" };
-
-/**
- * A single-select menu driven by the arrow keys and Enter.
- *
- * Built on `enquirer` rather than a hand-rolled raw-mode listener: a raw
- * `process.stdin.on("keypress")` handler never fires unless something first
- * calls `readline.emitKeypressEvents`, and the menu rendered as inert text for
- * exactly that reason. `enquirer` owns the keypress plumbing, including Ctrl-C.
- *
- * `header` is printed once here and never handed to `enquirer`: enquirer
- * redraws its whole frame on every keypress, so a header inside the prompt
- * repeated once per keystroke and stacked the wordmark down the terminal.
- *
- * Returns -1 when stdin is not a TTY (piped, CI, or a non-interactive run) or
- * when the operator cancels, so the caller can drain and exit either way.
- */
-export async function chooseFromMenu(
-  header: string | readonly string[],
-  rows: readonly MenuRow[],
-): Promise<number> {
-  if (!process.stdin.isTTY) return -1;
-
-  const headerLines = typeof header === "string" ? [header] : header;
-  process.stdout.write("\u001b[2J\u001b[H");
-  for (const line of headerLines) process.stdout.write(`${line}\n`);
-  process.stdout.write("\n");
-
-  // Enquirer indexes the rows it renders, rules included, so the action index
-  // has to be recovered from the label rather than from the position.
-  const labels = rows.flatMap((row) => (row.kind === "action" ? [row.label] : []));
-
-
-  try {
-    const answer = await Enquirer.prompt<{ choice: string }>({
-      type: "select",
-      name: "choice",
-      message: "Select an action",
-      choices: rows.map((row) =>
-        row.kind === "rule"
-          ? { name: "rule", message: "", role: "separator" }
-          : {
-              name: row.label,
-              message: row.label,
-              ...(row.hint === undefined ? {} : { hint: row.hint }),
-            },
-      ),
-      initial: 0,
-    });
-    return labels.indexOf(answer.choice);
-  } catch {
-    // Enquirer rejects on Esc and on its own Ctrl-C handling. Return -1 so the
-    // caller drains the gateway rather than leaving a detached process behind.
-    process.stdout.write("\u001b[2J\u001b[H");
-    return -1;
-  }
-}
-
-/**
- * Asks the operator to type an exact word before a destructive action runs.
- *
- * Enter alone must not be enough: the reset deletes every console credential,
- * so the operator types the word rather than confirming a highlight. Returns
- * false on cancel, on a mismatch, or when stdin is not a TTY.
- */
-export async function confirmByTyping(word: string, message: string): Promise<boolean> {
-  if (!process.stdin.isTTY) return false;
-  try {
-    const answer = await Enquirer.prompt<{ confirmation: string }>({
-      type: "input",
-      name: "confirmation",
-      message: `${message} (type ${word})`,
-      validate: (value: string) =>
-        value.trim() === word ? true : `type ${word} exactly to confirm, or Ctrl-C to cancel`,
-    });
-    return answer.confirmation.trim() === word;
-  } catch {
-    return false;
-  }
-}
-
-/** A yes/no gate for the step before the typed confirmation. */
-export async function confirmStep(message: string): Promise<boolean> {
-  if (!process.stdin.isTTY) return false;
-  try {
-    const answer = await Enquirer.prompt<{ proceed: boolean }>({
-      type: "confirm",
-      name: "proceed",
-      message,
-      initial: false,
-    });
-    return answer.proceed;
-  } catch {
-    return false;
-  }
-}
+import Enquirer from "enquirer";
+
+/**
+ * One row in a menu: an action the caller can run, or a rule between groups.
+ *
+ * Rules are rendered by `enquirer`'s own separator role and are never
+ * selectable, so the caller's action list stays a plain array indexed by the
+ * rows the operator can actually pick.
+ */
+export type MenuRow =
+  | { readonly kind: "action"; readonly label: string; readonly hint?: string }
+  | { readonly kind: "rule" };
+
+/**
+ * A single-select menu driven by the arrow keys and Enter.
+ *
+ * Built on `enquirer` rather than a hand-rolled raw-mode listener: a raw
+ * `process.stdin.on("keypress")` handler never fires unless something first
+ * calls `readline.emitKeypressEvents`, and the menu rendered as inert text for
+ * exactly that reason. `enquirer` owns the keypress plumbing, including Ctrl-C.
+ *
+ * `header` is printed once here and never handed to `enquirer`: enquirer
+ * redraws its whole frame on every keypress, so a header inside the prompt
+ * repeated once per keystroke and stacked the wordmark down the terminal.
+ *
+ * Returns -1 when stdin is not a TTY (piped, CI, or a non-interactive run) or
+ * when the operator cancels, so the caller can drain and exit either way.
+ */
+/**
+ * Options for `chooseFromMenu`. `initialIndex` is an **action** index, not a
+ * row index — the caller numbers from the actions it exposes, which is also
+ * what the function returns. Rules (separators) are not indexed.
+ */
+export interface MenuOptions {
+  readonly initialIndex?: number;
+}
+
+export async function chooseFromMenu(
+  header: string | readonly string[],
+  rows: readonly MenuRow[],
+  options: MenuOptions = {},
+): Promise<number> {
+  if (!process.stdin.isTTY) return -1;
+
+  const headerLines = typeof header === "string" ? [header] : header;
+  process.stdout.write("\u001b[2J\u001b[H");
+  for (const line of headerLines) process.stdout.write(`${line}\n`);
+  process.stdout.write("\n");
+
+  // Enquirer indexes the rows it renders, rules included, so the action index
+  // has to be recovered from the label rather than from the position.
+  const labels = rows.flatMap((row) => (row.kind === "action" ? [row.label] : []));
+  // Translate the action-index the caller passed into the row-index enquirer
+  // wants (which counts rules). An out-of-range or unspecified initial index
+  // falls back to the first action.
+  const clampedActionIndex = (() => {
+    if (options.initialIndex === undefined) return 0;
+    if (options.initialIndex < 0) return 0;
+    if (options.initialIndex >= labels.length) return labels.length - 1;
+    return options.initialIndex;
+  })();
+  let seenActions = 0;
+  let rowInitial = 0;
+  for (let i = 0; i < rows.length; i += 1) {
+    const row = rows[i];
+    if (row === undefined || row.kind !== "action") continue;
+    if (seenActions === clampedActionIndex) {
+      rowInitial = i;
+      break;
+    }
+    seenActions += 1;
+  }
+
+
+  try {
+    const answer = await Enquirer.prompt<{ choice: string }>({
+      type: "select",
+      name: "choice",
+      message: "Select an action",
+      choices: rows.map((row) =>
+        row.kind === "rule"
+          ? { name: "rule", message: "", role: "separator" }
+          : {
+              name: row.label,
+              message: row.label,
+              ...(row.hint === undefined ? {} : { hint: row.hint }),
+            },
+      ),
+      initial: rowInitial,
+    });
+    return labels.indexOf(answer.choice);
+  } catch {
+    // Enquirer rejects on Esc and on its own Ctrl-C handling. Return -1 so the
+    // caller drains the gateway rather than leaving a detached process behind.
+    process.stdout.write("\u001b[2J\u001b[H");
+    return -1;
+  }
+}
+
+/**
+ * Asks the operator to type an exact word before a destructive action runs.
+ *
+ * Enter alone must not be enough: the reset deletes every console credential,
+ * so the operator types the word rather than confirming a highlight. Returns
+ * false on cancel, on a mismatch, or when stdin is not a TTY.
+ */
+export async function confirmByTyping(word: string, message: string): Promise<boolean> {
+  if (!process.stdin.isTTY) return false;
+  try {
+    const answer = await Enquirer.prompt<{ confirmation: string }>({
+      type: "input",
+      name: "confirmation",
+      message: `${message} (type ${word})`,
+      validate: (value: string) =>
+        value.trim() === word ? true : `type ${word} exactly to confirm, or Ctrl-C to cancel`,
+    });
+    return answer.confirmation.trim() === word;
+  } catch {
+    return false;
+  }
+}
+
+/** A yes/no gate for the step before the typed confirmation. */
+export async function confirmStep(message: string): Promise<boolean> {
+  if (!process.stdin.isTTY) return false;
+  try {
+    const answer = await Enquirer.prompt<{ proceed: boolean }>({
+      type: "confirm",
+      name: "proceed",
+      message,
+      initial: false,
+    });
+    return answer.proceed;
+  } catch {
+    return false;
+  }
+}

package/scripts/cli/start.ts

@@ -26,6 +26,9 @@ export async function startForeground(): Promise<void> {
   const blocker = await inspectPortHolder(port, token);
   if (blocker !== null) throw new Error(blocker);
   writeInstanceLock(port, process.pid, token);
+  // dynamic-import: `src/main` boots the gateway as a side effect of module
+  // evaluation. Importing it statically would start the server before the
+  // port probe + instance-lock sequence above has a chance to refuse the run.
   await import("../../src/main");
 }
 

package/scripts/cli/tray.ts

@@ -1,208 +1,167 @@
-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 { startGateway } from "./gateway";
-import { stopGateway } from "./gateway";
-import { readInstalledVersion, readLatestPublishedVersion } from "./version";
-import { reportTrayStartup } from "./startup-signal";
-import { createTray } from "./tray/index";
-import { openUrl } from "./background";
-import { exportBackup, resetConsoleAccount } from "./admin";
-import { printUpdateInstructions } from "./update";
-
-/**
- * Runs the gateway with a tray icon. The tray is platform-specific (`tray/`):
- * on Windows it is a PowerShell NotifyIcon, because a Node tray library leaves
- * an empty console tab open for the tray's whole lifetime, and that window is
- * owned by Windows Terminal — not by this process, so it cannot be found and
- * hidden from inside.
- *
- * The gateway it starts is detached, which is what makes the health poll below
- * necessary — see {@link TRAY_HEALTH_POLL_MS}.
- */
-
-/**
- * How often the tray asks whether the gateway is still answering.
- *
- * 10 s: often enough that an operator who stops the gateway by hand sees the
- * icon go away, and far below the cost of a request. A detached gateway can no
- * longer be waited on, so this poll is the only signal left.
- */
-const TRAY_HEALTH_POLL_MS = 10_000;
-
-/**
- * Consecutive misses to forgive before a dead gateway closes the tray.
- *
- * One refusal is not a stopped gateway — a probe can lose a race with startup
- * or a slow request — and closing the icon on one would make startup feel
- * random.
- */
-const TRAY_HEALTH_MISSES_BEFORE_CLOSE = 3;
-
-export async function startTray(): Promise<void> {
-  const port = resolvePort();
-  const drainToken = ensureDrainToken();
-  const dashboardUrl = `http://127.0.0.1:${port}/console`;
-  const repositoryUrl = "https://github.com/risunCode/cartethyia";
-  const currentVersion = await readInstalledVersion();
-
-  let gateway: Bun.Subprocess | null = null;
-  let closing = false;
-  let busy = false;
-  let resetArmed = false;
-  let latestVersion: string | null = null;
-  let closePromise: Promise<void> | undefined;
-
-  const tray = createTray({
-    iconPath: resolvePackagePath(
-      "scripts",
-      "cli",
-      "tray",
-      "assets",
-      process.platform === "win32" ? "cartethyia.ico" : "cartethyia.png",
-    ),
-    tooltip: `Cartethyia ${currentVersion}`,
-    items: [
-      { kind: "action", id: "update", title: `Cartethyia ${currentVersion} \u00b7 checking\u2026`, enabled: true },
-      { kind: "separator" },
-      { kind: "action", id: "console", title: `Open Console \u00b7 ${dashboardUrl}` },
-      { kind: "action", id: "reset", title: "Reset console password" },
-      { kind: "action", id: "backup", title: "Backup" },
-      { kind: "separator" },
-      { kind: "action", id: "exit", title: "Exit" },
-    ],
-    onSelect: (id: string) => void handleSelect(id),
-    onExit: () => void close(1),
-  });
-
-  const close = (exitCode = 0): Promise<void> => {
-    if (closePromise) return closePromise;
-    closing = true;
-    closePromise = (async () => {
-      const current: Bun.Subprocess | null = gateway;
-      gateway = null;
-      if (current) await stopGateway(current, port, drainToken);
-      await tray.close();
-      process.exitCode = exitCode;
-    })();
-    return closePromise;
-  };
-
-  const refreshVersion = async (): Promise<void> => {
-    const fetched = await readLatestPublishedVersion();
-    if (closing) return;
-    latestVersion = fetched;
-    if (fetched === null) {
-      tray.update("update", `Cartethyia ${currentVersion} \u00b7 check for updates`, true);
-      return;
-    }
-    const newer = isNewerRelease(currentVersion, fetched);
-    tray.update(
-      "update",
-      newer
-        ? `Cartethyia ${currentVersion} \u00b7 update to ${fetched}`
-        : `Cartethyia ${currentVersion} \u00b7 up to date`,
-      // Always clickable: the row opens the repository, and only offers the
-      // update command when there is something newer.
-      true,
-    );
-  };
-
-  const runUpdate = async (): Promise<void> => {
-    if (busy) return;
-    busy = true;
-    const latest = await readLatestPublishedVersion();
-    await close();
-    printUpdateInstructions(currentVersion, latest);
-    // The tray has no terminal of its own, so these instructions are only
-    // visible when it was started from one. Hold that terminal open long
-    // enough to copy the command, then exit.
-    await new Promise<void>((resolve) => setTimeout(resolve, 180_000));
-    process.exit(0);
-  };
-
-  async function handleSelect(id: string): Promise<void> {
-    if (closing) return;
-    if (id === "exit") return void (await close());
-    if (id === "console") return void (await openUrl(dashboardUrl));
-    if (id === "backup") {
-      const result = await exportBackup(port, drainToken);
-      if (result !== null) {
-        console.log(
-          `Backup written to ${result.path} (${(result.bytes / 1024).toFixed(1)} KiB). Telemetry is not included.`,
-        );
-      }
-      return;
-    }
-    if (id === "reset") {
-      // A tray click cannot ask for the typed confirmation the menu uses, so
-      // the first click arms the action and the second one runs it.
-      if (!resetArmed) {
-        resetArmed = true;
-        tray.update("reset", "Reset console password \u00b7 click again to delete", true);
-        return;
-      }
-      resetArmed = false;
-      tray.update("reset", "Reset console password", true);
-      await resetConsoleAccount(port, drainToken);
-      return;
-    }
-    if (id === "update") {
-      // Nothing to install: the row is the way to the repository instead.
-      if (latestVersion === null || !isNewerRelease(currentVersion, latestVersion)) {
-        await openUrl(repositoryUrl);
-        return;
-      }
-      await runUpdate();
-    }
-  }
-
-  process.once("SIGINT", () => void close());
-  process.once("SIGTERM", () => void close());
-
-  try {
-    await tray.ready();
-    // Detached, unlike every other caller: the gateway must outlive this
-    // process. Attached, it dies with the tray — and the tray dies with the
-    // terminal that launched it, so closing that terminal took the gateway
-    // down too and "Hide to tray" left nothing serving. `stopGateway` drains
-    // over HTTP before it ever reaches for `kill()`, so detaching costs the
-    // exit path nothing: the tray can still stop the gateway on Exit.
-    gateway = await startGateway(port, drainToken, { detached: true });
-    // The launcher that spawned this tray is blocked on a signal file: it
-    // cannot read our stdio, because the tray is detached. Without this write
-    // it waits out its 60 s deadline and reports a failure for a tray that is
-    // running fine.
-    reportTrayStartup({ status: "ready", url: dashboardUrl });
-    console.log(`Cartethyia is running at ${dashboardUrl}`);
-    void refreshVersion();
-
-    let misses = 0;
-    // A detached child's `exited` never settles on Windows, so the old
-    // `await current.exited` would have parked here forever and the tray would
-    // never notice the gateway going away. Poll its health endpoint instead:
-    // that answers for a process we no longer own, which is the whole point of
-    // detaching it. The probe is the same one startup used, so a gateway that
-    // is up reads as up regardless of who spawned it.
-    while (!closing) {
-      await Bun.sleep(TRAY_HEALTH_POLL_MS);
-      if (closing || gateway === null) continue;
-      const alive = await fetch(`http://127.0.0.1:${port}/health`, {
-        signal: AbortSignal.timeout(2_000),
-      }).then((response) => response.ok).catch(() => false);
-      if (alive) {
-        misses = 0;
-        continue;
-      }
-      misses += 1;
-      if (misses < TRAY_HEALTH_MISSES_BEFORE_CLOSE) continue;
-      gateway = null;
-      console.error("Cartethyia stopped answering; the tray is closing.");
-      await close(1);
-    }
-  } catch (error) {
-    await close(1);
-    throw error;
-  }
-}
+import { resolvePackagePath } from "../../src/config/package-paths";
+import { resolvePort } from "../../src/config/runtime";
+import { ensureDrainToken } from "./instance";
+import { startGateway } from "./gateway";
+import { stopGateway } from "./gateway";
+import { readInstalledVersion } from "./version";
+import { reportTrayStartup } from "./startup-signal";
+import { createTray } from "./tray/index";
+import { openUrl } from "./background";
+import { exportBackup, resetConsoleAccount } from "./admin";
+
+/**
+ * Runs the gateway with a tray icon. The tray is platform-specific (`tray/`):
+ * on Windows it is a PowerShell NotifyIcon, because a Node tray library leaves
+ * an empty console tab open for the tray's whole lifetime, and that window is
+ * owned by Windows Terminal — not by this process, so it cannot be found and
+ * hidden from inside.
+ *
+ * The gateway it starts is detached, which is what makes the health poll below
+ * necessary — see {@link TRAY_HEALTH_POLL_MS}.
+ */
+
+/**
+ * How often the tray asks whether the gateway is still answering.
+ *
+ * 10 s: often enough that an operator who stops the gateway by hand sees the
+ * icon go away, and far below the cost of a request. A detached gateway can no
+ * longer be waited on, so this poll is the only signal left.
+ */
+const TRAY_HEALTH_POLL_MS = 10_000;
+
+/**
+ * Consecutive misses to forgive before a dead gateway closes the tray.
+ *
+ * One refusal is not a stopped gateway — a probe can lose a race with startup
+ * or a slow request — and closing the icon on one would make startup feel
+ * random.
+ */
+const TRAY_HEALTH_MISSES_BEFORE_CLOSE = 3;
+
+export async function startTray(): Promise<void> {
+  const port = resolvePort();
+  const drainToken = ensureDrainToken();
+  const dashboardUrl = `http://127.0.0.1:${port}/console`;
+  const releasesUrl = "https://github.com/risunCodex/Cartethyia/releases";
+  const currentVersion = await readInstalledVersion();
+
+  let gateway: Bun.Subprocess | null = null;
+  let closing = false;
+  let resetArmed = false;
+  let closePromise: Promise<void> | undefined;
+
+  const tray = createTray({
+    iconPath: resolvePackagePath(
+      "scripts",
+      "cli",
+      "tray",
+      "assets",
+      process.platform === "win32" ? "cartethyia.ico" : "cartethyia.png",
+    ),
+    tooltip: `Cartethyia ${currentVersion}`,
+    items: [
+      // Version row is informational; clicking it opens the releases page so
+      // the operator can decide for themselves. No background check: the tray
+      // used to poll the registry on open and the result was a cue the user
+      // did not ask for.
+      { kind: "action", id: "version", title: `Cartethyia ${currentVersion}`, enabled: true },
+      { kind: "separator" },
+      { kind: "action", id: "console", title: `Open Console \u00b7 ${dashboardUrl}` },
+      { kind: "action", id: "reset", title: "Reset console password" },
+      { kind: "action", id: "backup", title: "Backup" },
+      { kind: "separator" },
+      { kind: "action", id: "exit", title: "Exit" },
+    ],
+    onSelect: (id: string) => void handleSelect(id),
+    onExit: () => void close(1),
+  });
+
+  const close = (exitCode = 0): Promise<void> => {
+    if (closePromise) return closePromise;
+    closing = true;
+    closePromise = (async () => {
+      const current: Bun.Subprocess | null = gateway;
+      gateway = null;
+      if (current) await stopGateway(current, port, drainToken);
+      await tray.close();
+      process.exitCode = exitCode;
+    })();
+    return closePromise;
+  };
+
+  async function handleSelect(id: string): Promise<void> {
+    if (closing) return;
+    if (id === "exit") return void (await close());
+    if (id === "console") return void (await openUrl(dashboardUrl));
+    if (id === "version") return void (await openUrl(releasesUrl));
+    if (id === "backup") {
+      const result = await exportBackup(port, drainToken);
+      if (result !== null) {
+        console.log(
+          `Backup written to ${result.path} (${(result.bytes / 1024).toFixed(1)} KiB). Telemetry is not included.`,
+        );
+      }
+      return;
+    }
+    if (id === "reset") {
+      // A tray click cannot ask for the typed confirmation the menu uses, so
+      // the first click arms the action and the second one runs it.
+      if (!resetArmed) {
+        resetArmed = true;
+        tray.update("reset", "Reset console password \u00b7 click again to delete", true);
+        return;
+      }
+      resetArmed = false;
+      tray.update("reset", "Reset console password", true);
+      await resetConsoleAccount(port, drainToken);
+      return;
+    }
+  }
+
+  process.once("SIGINT", () => void close());
+  process.once("SIGTERM", () => void close());
+
+  try {
+    await tray.ready();
+    // Detached, unlike every other caller: the gateway must outlive this
+    // process. Attached, it dies with the tray — and the tray dies with the
+    // terminal that launched it, so closing that terminal took the gateway
+    // down too and "Hide to tray" left nothing serving. `stopGateway` drains
+    // over HTTP before it ever reaches for `kill()`, so detaching costs the
+    // exit path nothing: the tray can still stop the gateway on Exit.
+    gateway = await startGateway(port, drainToken, { detached: true });
+    // The launcher that spawned this tray is blocked on a signal file: it
+    // cannot read our stdio, because the tray is detached. Without this write
+    // it waits out its 60 s deadline and reports a failure for a tray that is
+    // running fine.
+    reportTrayStartup({ status: "ready", url: dashboardUrl });
+    console.log(`Cartethyia is running at ${dashboardUrl}`);
+
+    let misses = 0;
+    // A detached child's `exited` never settles on Windows, so the old
+    // `await current.exited` would have parked here forever and the tray would
+    // never notice the gateway going away. Poll its health endpoint instead:
+    // that answers for a process we no longer own, which is the whole point of
+    // detaching it. The probe is the same one startup used, so a gateway that
+    // is up reads as up regardless of who spawned it.
+    while (!closing) {
+      await Bun.sleep(TRAY_HEALTH_POLL_MS);
+      if (closing || gateway === null) continue;
+      const alive = await fetch(`http://127.0.0.1:${port}/health`, {
+        signal: AbortSignal.timeout(2_000),
+      }).then((response) => response.ok).catch(() => false);
+      if (alive) {
+        misses = 0;
+        continue;
+      }
+      misses += 1;
+      if (misses < TRAY_HEALTH_MISSES_BEFORE_CLOSE) continue;
+      gateway = null;
+      console.error("Cartethyia stopped answering; the tray is closing.");
+      await close(1);
+    }
+  } catch (error) {
+    await close(1);
+    throw error;
+  }
+}