cartethyia 2.5.10 → 2.6.0

package/scripts/cli/prompt.ts

@@ -2,108 +2,246 @@ 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.
+ * Rules are never selectable and are not included in the returned action index.
  */
 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.
- */
+/** Options for {@link chooseFromMenu}. Indices count actions, not rules. */
 export interface MenuOptions {
   readonly initialIndex?: number;
+  /** Short status retained below the menu after an action completes. */
+  readonly status?: { readonly tone: "success" | "error"; readonly text: string };
+}
+
+interface MouseEvent {
+  readonly button: number;
+  readonly column: number;
+  readonly row: number;
+  readonly release: boolean;
 }
 
+const CURSOR_HOME = "\u001b[H";
+const CLEAR_SCREEN = "\u001b[2J";
+const CLEAR_LINE = "\u001b[2K";
+const HIDE_CURSOR = "\u001b[?25l";
+const SHOW_CURSOR = "\u001b[?25h";
+const ENABLE_MOUSE = "\u001b[?1000h\u001b[?1006h";
+const DISABLE_MOUSE = "\u001b[?1006l\u001b[?1000l";
+const RESET = "\u001b[0m";
+const MOUSE_PATTERN = /\u001b\[<(\d+);(\d+);(\d+)([Mm])/g;
+
+function parseMouseEvents(sequence: string): MouseEvent[] {
+  return [...sequence.matchAll(MOUSE_PATTERN)].map((match) => ({
+    button: Number(match[1]),
+    column: Number(match[2]),
+    row: Number(match[3]),
+    release: match[4] === "m",
+  }));
+}
+
+function clamp(value: number, minimum: number, maximum: number): number {
+  return Math.max(minimum, Math.min(maximum, value));
+}
+
+function plainText(value: string, width: number): string {
+  return value.length <= width ? value : width <= 1 ? value.slice(0, width) : `${value.slice(0, width - 1)}…`;
+}
+
+/**
+ * An interactive terminal menu with keyboard and xterm SGR mouse support.
+ *
+ * A single click focuses on press and activates on release over the same row,
+ * matching ordinary desktop buttons. Terminals without mouse reporting retain
+ * the complete arrow-key/Enter interface. stdin is restored even on Ctrl-C or
+ * Esc so the caller can drain the gateway normally.
+ */
 export async function chooseFromMenu(
   header: string | readonly string[],
   rows: readonly MenuRow[],
   options: MenuOptions = {},
 ): Promise<number> {
-  if (!process.stdin.isTTY) return -1;
+  const input = process.stdin;
+  const output = process.stdout;
+  if (!input.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;
+  const actionRows = rows.flatMap((row, rowIndex) => row.kind === "action" ? [rowIndex] : []);
+  if (actionRows.length === 0) return -1;
+  let selected = clamp(options.initialIndex ?? 0, 0, actionRows.length - 1);
+  let pressedAction: number | null = null;
+  let settled = false;
+  let frameTop = 0;
+  let menuWidth = 0;
+  const color = output.isTTY === true && process.env.NO_COLOR === undefined && process.env.TERM !== "dumb";
+  const paint = (code: string, value: string): string => color ? `\u001b[${code}m${value}${RESET}` : value;
+  const muted = (value: string): string => paint("2;38;2;130;148;165", value);
+  const accent = (value: string): string => paint("38;2;145;200;240", value);
+  const selectedPaint = (value: string): string => paint("1;38;2;225;242;255;48;2;43;75;106", value);
+  const status = options.status === undefined ? undefined : {
+    ...options.status,
+    text: options.status.text.replace(/\s+/g, " ").trim(),
+  };
+
+  const render = (): void => {
+    const columns = Math.max(32, output.columns || 80);
+    const labelWidth = Math.max(...rows.flatMap((row) => row.kind === "action" ? [row.label.length] : [0]));
+    const contentWidth = Math.max(...rows.map((row) => row.kind === "rule"
+      ? 24
+      : labelWidth + (row.hint?.length ?? 0) + 7));
+    const innerWidth = Math.min(contentWidth, columns - 4);
+    menuWidth = innerWidth + 2;
+    const lines = [accent(`╭─ Actions ${"─".repeat(Math.max(0, innerWidth - 10))}╮`)];
+
+    rows.forEach((row, rowIndex) => {
+      if (row.kind === "rule") {
+        lines.push(muted(`│ ${"─".repeat(Math.max(0, innerWidth - 4))} │`));
+        return;
+      }
+      const hintWidth = Math.max(0, innerWidth - labelWidth - 7);
+      const hint = plainText(row.hint ?? "", hintWidth).padEnd(hintWidth);
+      const isSelected = actionRows[selected] === rowIndex;
+      const pointer = isSelected ? "❯" : " ";
+      const text = ` ${pointer} ${row.label.padEnd(labelWidth)}  ${hint} `;
+      const content = plainText(text, innerWidth).padEnd(innerWidth);
+      lines.push(isSelected ? `│${selectedPaint(content)}│` : `│${content}│`);
+    });
+    lines.push(accent(`╰${"─".repeat(innerWidth)}╯`));
+    if (status !== undefined) {
+      const prefix = status.tone === "success" ? "✓ " : "✗ ";
+      const text = plainText(`${prefix}${status.text}`, columns - 2);
+      lines.push(paint(status.tone === "success" ? "38;2;135;205;160" : "38;2;240;145;145", text));
     }
-    seenActions += 1;
-  }
+    lines.push(muted("  ↑ ↓ navigate · Enter select · Click to open · Esc cancel"));
+
+    const cursor = `\u001b[${frameTop};1H`;
+    output.write(`${cursor}${lines.map((line) => `${CLEAR_LINE}${line}`).join("\n")}`);
+  };
+
+  const actionAtScreenPosition = (column: number, screenRow: number): number | null => {
+    if (column < 1 || column > menuWidth) return null;
+    const rowIndex = screenRow - frameTop - 1;
+    if (rowIndex < 0 || rowIndex >= rows.length) return null;
+    const actionIndex = actionRows.indexOf(rowIndex);
+    return actionIndex < 0 ? null : actionIndex;
+  };
+
+  const headerLines = typeof header === "string" ? [header] : header;
+  output.write(`${CLEAR_SCREEN}${CURSOR_HOME}`);
+  for (const line of headerLines) output.write(`${line}\n`);
+  output.write("\n");
+  frameTop = headerLines.length + 2;
+  output.write(HIDE_CURSOR + ENABLE_MOUSE);
+  render();
+
+  const wasRaw = input.isRaw;
+  input.setEncoding("utf8");
+  if (input.isTTY) input.setRawMode(true);
+  input.resume();
 
+  const onKeypress = (_sequence: string, key: { readonly name: string | undefined }): void => {
+    if (key.name === "\u0003" || key.name === "escape") {
+      finish(-1);
+      return;
+    }
+    if (key.name === "up" || key.name === "k") move(-1);
+    else if (key.name === "down" || key.name === "j") move(1);
+    else if (key.name === "home") { selected = 0; render(); }
+    else if (key.name === "end") { selected = actionRows.length - 1; render(); }
+    else if (key.name === "return" || key.name === "enter" || key.name === "space") finish(selected);
+  };
+  const onMouseSequence = (sequence: string): void => {
+    for (const mouse of parseMouseEvents(sequence)) {
+      if ((mouse.button & 32) !== 0) continue;
+      if ((mouse.button & 64) !== 0) {
+        move((mouse.button & 1) === 0 ? -1 : 1);
+        continue;
+      }
+      if ((mouse.button & 3) !== 0) continue;
+      const actionIndex = actionAtScreenPosition(mouse.column, mouse.row);
+      if (mouse.release) {
+        if (pressedAction !== null && pressedAction === actionIndex) finish(actionIndex);
+        pressedAction = null;
+        continue;
+      }
+      pressedAction = actionIndex;
+      if (actionIndex !== null && actionIndex !== selected) {
+        selected = actionIndex;
+        render();
+      }
+    }
+  };
+  let resolveMenu: (actionIndex: number) => void = () => undefined;
+  const finish = (actionIndex: number): void => {
+    if (settled) return;
+    settled = true;
+    resolveMenu(actionIndex);
+  };
+  const move = (delta: number): void => {
+    selected = (selected + delta + actionRows.length) % actionRows.length;
+    pressedAction = null;
+    render();
+  };
+  // Keypress parsing also consumes mouse sequences, so mouse reporting owns
+  // the data stream while this menu is active. Keyboard escape sequences are
+  // decoded here as well instead of relying on two competing data listeners.
+  let pendingInput = "";
+  const onRawData = (chunk: Buffer | string): void => {
+    pendingInput += String(chunk);
+    const names: Record<string, string> = {
+      "\u001b[A": "up", "\u001b[B": "down", "\u001b[H": "home", "\u001b[F": "end",
+      "\u001bOA": "up", "\u001bOB": "down", "\u001bOH": "home", "\u001bOF": "end",
+    };
+    while (pendingInput.length > 0 && !settled) {
+      if (pendingInput.startsWith("\u001b[<")) {
+        const mouse = /^\u001b\[<\d+;\d+;\d+[Mm]/.exec(pendingInput);
+        if (mouse === null) {
+          if (pendingInput.length < 32) return;
+          pendingInput = pendingInput.slice(1);
+          continue;
+        }
+        onMouseSequence(mouse[0]);
+        pendingInput = pendingInput.slice(mouse[0].length);
+        continue;
+      }
+      if (pendingInput.startsWith("\u001b[") || pendingInput.startsWith("\u001bO")) {
+        const sequence = Object.keys(names).find((candidate) => pendingInput.startsWith(candidate));
+        if (sequence === undefined) {
+          if (pendingInput.length < 3) return;
+          pendingInput = pendingInput.slice(1);
+          continue;
+        }
+        onKeypress(sequence, { name: names[sequence] });
+        pendingInput = pendingInput.slice(sequence.length);
+        continue;
+      }
+      if (pendingInput.startsWith("\r\n")) pendingInput = pendingInput.slice(1);
+      const character = pendingInput[0]!;
+      const name = character === "\r" || character === "\n" ? "return" : character === "\u001b" ? "escape" : character;
+      onKeypress(character, { name });
+      pendingInput = pendingInput.slice(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,
+    input.on("data", onRawData);
+    return await new Promise<number>((resolve) => {
+      resolveMenu = resolve;
     });
-    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;
+  } finally {
+    input.removeListener("data", onRawData);
+    if (input.isTTY) input.setRawMode(wasRaw);
+    // Always release the resumed stdin. A listener-less but flowing TTY keeps
+    // the CLI alive after Hide to Tray or another terminal action completes.
+    // The next menu resumes it explicitly, so preserving a flowing state here
+    // provides no benefit and leaves the terminal looking stuck.
+    input.pause();
+    if (settled) output.write(`\n${DISABLE_MOUSE}${SHOW_CURSOR}${RESET}`);
+    else output.write(`${CLEAR_SCREEN}${CURSOR_HOME}${DISABLE_MOUSE}${SHOW_CURSOR}${RESET}`);
   }
 }
 
-/**
- * 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.
- */
+/** Asks the operator to type an exact word before a destructive action runs. */
 export async function confirmByTyping(word: string, message: string): Promise<boolean> {
   if (!process.stdin.isTTY) return false;
   try {

package/scripts/cli/services.ts

@@ -1,88 +1,88 @@
-/**
- * TCP reachability checks for the services setup and doctor ask about.
- *
- * These are extracted from the env helpers so the dotenv reader and the probe
- * stay independent: doctor can be imported without pulling in `.env` parsing.
- */
-
-export interface ProbeResult {
-  success: boolean;
-  error?: string;
-}
-
-/**
- * Opens a TCP connection to `host:port` and resolves once it connects, errors,
- * or the timeout elapses. The socket is always closed so a probe never leaves a
- * half-open connection behind.
- */
-export async function probeTcpService(
-  host: string,
-  port: number,
-  timeoutMs: number,
-): Promise<ProbeResult> {
-  const { promise, resolve } = Promise.withResolvers<ProbeResult>();
-
-  const timeoutHandle = setTimeout(() => {
-    resolve({ success: false, error: "timeout" });
-  }, timeoutMs);
-
-  Bun.connect({
-    hostname: host,
-    port: port,
-    socket: {
-      open: () => {
-        clearTimeout(timeoutHandle);
-        resolve({ success: true });
-      },
-      data: () => {},
-      error: (err) => {
-        clearTimeout(timeoutHandle);
-        resolve({ success: false, error: String(err) });
-      },
-    },
-  })
-    .then((socket) => {
-      socket.end();
-    })
-    .catch((err) => {
-      clearTimeout(timeoutHandle);
-      resolve({ success: false, error: String(err) });
-    });
-
-  return promise;
-}
-
-/**
- * Local PostgreSQL ports worth probing before asking for a URL. 5432 is the
- * server default (Laragon, Homebrew, systemd); 5433 is the usual second
- * instance when 5432 is already taken.
- */
-export const LOCAL_POSTGRES_CANDIDATES = [
-  { host: "127.0.0.1", port: 5432 },
-  { host: "127.0.0.1", port: 5433 },
-] as const;
-
-/** First local PostgreSQL that accepts a TCP connection, or null. */
-export async function detectLocalPostgres(
-  timeoutMs: number,
-): Promise<{ host: string; port: number } | null> {
-  for (const candidate of LOCAL_POSTGRES_CANDIDATES) {
-    const probe = await probeTcpService(candidate.host, candidate.port, timeoutMs);
-    if (probe.success) return candidate;
-  }
-  return null;
-}
-
-/**
- * Parses a service URL and requires an explicit host and port.
- * Returns null if the URL is invalid or incomplete.
- */
-export function parseServiceUrl(url: string): { host: string; port: number } | null {
-  try {
-    const urlObj = new URL(url);
-    if (!urlObj.hostname || !urlObj.port) return null;
-    return { host: urlObj.hostname, port: Number(urlObj.port) };
-  } catch {
-    return null;
-  }
-}
+/**
+ * TCP reachability checks for the services setup and doctor ask about.
+ *
+ * These are extracted from the env helpers so the dotenv reader and the probe
+ * stay independent: doctor can be imported without pulling in `.env` parsing.
+ */
+
+export interface ProbeResult {
+  success: boolean;
+  error?: string;
+}
+
+/**
+ * Opens a TCP connection to `host:port` and resolves once it connects, errors,
+ * or the timeout elapses. The socket is always closed so a probe never leaves a
+ * half-open connection behind.
+ */
+export async function probeTcpService(
+  host: string,
+  port: number,
+  timeoutMs: number,
+): Promise<ProbeResult> {
+  const { promise, resolve } = Promise.withResolvers<ProbeResult>();
+
+  const timeoutHandle = setTimeout(() => {
+    resolve({ success: false, error: "timeout" });
+  }, timeoutMs);
+
+  Bun.connect({
+    hostname: host,
+    port: port,
+    socket: {
+      open: () => {
+        clearTimeout(timeoutHandle);
+        resolve({ success: true });
+      },
+      data: () => {},
+      error: (err) => {
+        clearTimeout(timeoutHandle);
+        resolve({ success: false, error: String(err) });
+      },
+    },
+  })
+    .then((socket) => {
+      socket.end();
+    })
+    .catch((err) => {
+      clearTimeout(timeoutHandle);
+      resolve({ success: false, error: String(err) });
+    });
+
+  return promise;
+}
+
+/**
+ * Local PostgreSQL ports worth probing before asking for a URL. 5432 is the
+ * server default (Laragon, Homebrew, systemd); 5433 is the usual second
+ * instance when 5432 is already taken.
+ */
+export const LOCAL_POSTGRES_CANDIDATES = [
+  { host: "127.0.0.1", port: 5432 },
+  { host: "127.0.0.1", port: 5433 },
+] as const;
+
+/** First local PostgreSQL that accepts a TCP connection, or null. */
+export async function detectLocalPostgres(
+  timeoutMs: number,
+): Promise<{ host: string; port: number } | null> {
+  for (const candidate of LOCAL_POSTGRES_CANDIDATES) {
+    const probe = await probeTcpService(candidate.host, candidate.port, timeoutMs);
+    if (probe.success) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Parses a service URL and requires an explicit host and port.
+ * Returns null if the URL is invalid or incomplete.
+ */
+export function parseServiceUrl(url: string): { host: string; port: number } | null {
+  try {
+    const urlObj = new URL(url);
+    if (!urlObj.hostname || !urlObj.port) return null;
+    return { host: urlObj.hostname, port: Number(urlObj.port) };
+  } catch {
+    return null;
+  }
+}