cartethyia 2.3.4 → 2.4.0

package/scripts/cli/menu.ts

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

package/scripts/cli/runtime-state.ts

@@ -1,37 +1,31 @@
-import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 /**
- * Runtime state for a gateway left running by "Hide to background".
+ * The install's drain token, persisted in the config directory.
  *
- * 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.
+ * Why it persists instead of being generated per run: `cartethyia stop` runs in
+ * a different process, possibly minutes later, and the token is the only way it
+ * can authenticate to a gateway it did not start. A token regenerated on each
+ * start could never match the gateway that is actually running, which is why
+ * `stop` reported "no gateway found" or a 401 on a live gateway.
+ *
+ * It is kept out of `.env` on purpose: it authorises a shutdown, so it belongs
+ * in a machine-written file the operator never hand-edits and never commits.
+ * Mode 0600 where the platform honours it.
  */
 const RUNTIME_STATE_FILE = "runtime.json";
 
+interface RuntimeState {
+  readonly drainToken: string;
+}
+
 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 {
+function readState(): RuntimeState | null {
   const path = statePath();
   if (path === null || !existsSync(path)) return null;
   try {
@@ -40,23 +34,45 @@ export function readPersistedDrainToken(): string | null {
       parsed !== null &&
       typeof parsed === "object" &&
       "drainToken" in parsed &&
-      typeof parsed.drainToken === "string"
+      typeof parsed.drainToken === "string" &&
+      parsed.drainToken.length > 0
     ) {
-      return parsed.drainToken;
+      return { drainToken: parsed.drainToken };
     }
   } catch {
-    // A corrupt or stale state file reads as "no background gateway".
+    // A corrupt or stale state file reads as "no token".
   }
   return null;
 }
 
-/** Removes the token once the drain has been accepted. */
-export function clearPersistedDrainToken(): void {
+/**
+ * Returns the install's drain token, creating and persisting one on first use.
+ *
+ * Every start calls this, so a gateway started from the menu, from `tray`, or
+ * from `cartethyia start` all authenticate with the same token and `stop`
+ * always has the one that works.
+ */
+export function ensureDrainToken(): string {
+  const existing = readState();
+  if (existing !== null) return existing.drainToken;
+
+  const token = crypto.randomUUID().replace(/-/g, "") + crypto.randomUUID().replace(/-/g, "");
   const path = statePath();
-  if (path === null) return;
-  try {
-    unlinkSync(path);
-  } catch {
-    // Best effort: the drain request already succeeded.
+  if (path !== null) {
+    try {
+      writeFileSync(path, JSON.stringify({ drainToken: token }), {
+        encoding: "utf8",
+        mode: 0o600,
+      });
+    } catch {
+      // A read-only config directory still yields a usable in-process token;
+      // only `stop` from another process is lost.
+    }
   }
+  return token;
+}
+
+/** The persisted token, or null when this install has never started. */
+export function readPersistedDrainToken(): string | null {
+  return readState()?.drainToken ?? null;
 }