beez-rp 0.1.1

package/src/constants/terminal-ui.js

@@ -0,0 +1,93 @@
+/**
+ * Layout, ANSI and key contracts of the dependency-free terminal UI.
+ *
+ * @module constants/terminal-ui
+ */
+
+/** Widest box drawn, so lines stay readable on large terminals. */
+export const MAX_BOX_WIDTH = 84;
+
+/** Width assumed when stdout does not report its columns. */
+export const FALLBACK_TERMINAL_WIDTH = 80;
+
+/** Columns kept free at the right of the terminal when sizing a box. */
+export const TERMINAL_RIGHT_MARGIN = 2;
+
+/** Horizontal padding inside a box, per side. */
+export const BOX_PADDING = 1;
+
+/** Width of the label column of status rows. */
+export const ROW_LABEL_WIDTH = 16;
+
+/** Spinner animation frames. */
+export const SPINNER_FRAMES = Object.freeze(["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]);
+
+/** Delay between spinner frames. */
+export const SPINNER_INTERVAL_MS = 80;
+
+/** Exit code conventionally used after Ctrl+C. */
+export const INTERRUPTED_EXIT_CODE = 130;
+
+/** Splits styled text into ANSI escape sequences and single code points. */
+export const ANSI_TOKEN_PATTERN = /\x1b\[[0-9;]*m|[\s\S]/gu;
+
+/** First character of every ANSI escape sequence. */
+export const ANSI_ESCAPE = "\x1b";
+
+/** ANSI control sequences used by boxes, spinners and prompts. */
+export const ANSI_SEQUENCE = Object.freeze({
+  reset: "\x1b[0m",
+  hideCursor: "\x1b[?25l",
+  showCursor: "\x1b[?25h",
+  clearLine: "\r\x1b[2K",
+  clearBelow: "\x1b[0J",
+});
+
+/** Border color of each box tone. */
+export const BOX_TONE = Object.freeze({
+  neutral: "gray",
+  info: "cyan",
+  success: "green",
+  warning: "yellow",
+  danger: "red",
+  accent: "magenta",
+});
+
+/** Nerd Font glyphs (Font Awesome and Octicons sets) used as status icons. */
+export const ICON_GLYPH = Object.freeze({
+  success: "", // nf-fa-check
+  failure: "", // nf-fa-times
+  warning: "", // nf-fa-warning
+  info: "", // nf-fa-info_circle
+  pending: "", // nf-fa-circle_o
+  arrow: "", // nf-fa-chevron_right
+  bullet: "", // nf-oct-dot_fill
+  star: "", // nf-fa-star
+  rocket: "", // nf-fa-rocket
+});
+
+/** Label/value rows (`renderRow`): the value starts after a gap of two or more spaces. */
+export const VALUE_COLUMN_PATTERN = /^\s*\S(?:.*?\S)?\s{2,}(?=\S)/u;
+
+/** Leading marker (icon, arrow, bullet or `1.`, never a word) followed by a space, used as hanging indent. */
+export const HANGING_MARKER_PATTERN = /^(\s*)((?:[^\p{L}\p{N}\s]{1,2}|\d{1,2}\.)\s+)?/u;
+
+/** Options that can be picked with a single digit key (1-9). */
+export const MAX_NUMBERED_OPTIONS = 9;
+
+/** A single digit key that picks a numbered option. */
+export const NUMBER_KEY_PATTERN = /^[1-9]$/u;
+
+/** Seconds in a minute, used to format durations. */
+export const SECONDS_PER_MINUTE = 60;
+
+/** Milliseconds in a second, used to format durations. */
+export const MILLISECONDS_PER_SECOND = 1000;
+
+/** Key names (`readline` keypress events) handled by the select prompt. */
+export const PROMPT_KEY = Object.freeze({
+  interrupt: "c",
+  previous: Object.freeze(["up", "k"]),
+  next: Object.freeze(["down", "j", "tab"]),
+  confirm: Object.freeze(["return", "enter"]),
+});

package/src/constants/versions.js

@@ -0,0 +1,39 @@
+/**
+ * Release version rules shared by `create-version` and the Vercel build gate.
+ *
+ * @module constants/versions
+ */
+
+/** Semver release types, from the smallest to the largest change. */
+export const RELEASE_TYPE = Object.freeze({
+  patch: "patch",
+  minor: "minor",
+  major: "major",
+});
+
+/** Release types in the order they are offered: patch, minor, major. */
+export const RELEASE_TYPE_ORDER = Object.freeze([RELEASE_TYPE.patch, RELEASE_TYPE.minor, RELEASE_TYPE.major]);
+
+/** Stable `X.Y.Z` release version: no prerelease, build metadata, prefix or leading zeros. */
+export const RELEASE_VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+
+/** Any semver version, capturing its `X.Y.Z` core and optional prerelease. */
+export const SEMVER_PATTERN = /^((?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*))(-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+/** Prefix of the annotated Git tags that mark each release (`v0.93.0`). */
+export const RELEASE_TAG_PREFIX = "v";
+
+/** `git log --grep` pattern of release commit subjects (`0.93.0`). */
+export const RELEASE_COMMIT_SUBJECT_GREP = String.raw`^[0-9]+\.[0-9]+\.[0-9]+$`;
+
+/** Conventional commit header: `type(scope)!: subject`. */
+export const CONVENTIONAL_HEADER_PATTERN = /^(?<type>[a-z]+)(?:\([^)]*\))?(?<breaking>!)?:\s/i;
+
+/** Footer that marks a breaking change in a conventional commit body. */
+export const BREAKING_CHANGE_FOOTER_PATTERN = /^BREAKING[ -]CHANGE:/m;
+
+/** Conventional commit type that ships user-visible features. */
+export const FEATURE_COMMIT_TYPE = "feat";
+
+/** Imperative verbs used by legacy, non-conventional feature subjects. */
+export const LEGACY_FEATURE_SUBJECT_PATTERN = /^(add|implement|introduce|support|enable|create|allow)\b/i;

package/src/index.js

@@ -0,0 +1,37 @@
+/**
+ * `beez-rp`: dependency-free release process shared by the Beez projects.
+ *
+ * - `beez-rp/versions`: stable `X.Y.Z` rules; only the next patch, minor or major is allowed.
+ * - `beez-rp/build-gate`: Vercel `ignoreCommand` decision built on those rules.
+ * - `beez-rp/changelog` and `beez-rp/changelog-ai`: Keep a Changelog release and Codex fill-in.
+ * - `beez-rp/terminal-ui`: boxes, spinners and prompts for release commands.
+ * - `beez-rp/testing`: shared version bump fixtures for consumer test suites.
+ * - `beez-rp/constants`: every constant above, grouped by domain.
+ *
+ * @module beez-rp
+ */
+
+export * from "./build-gate.js";
+export * from "./changelog.js";
+export * from "./changelog-ai.js";
+export * from "./versions.js";
+export {
+  ICON,
+  countTerminalRows,
+  formatDuration,
+  getPromptWaitMs,
+  measureActiveMs,
+  paint,
+  print,
+  renderBanner,
+  renderBox,
+  renderRow,
+  renderStepHeader,
+  resolveBoxWidth,
+  resolveNumberKey,
+  select,
+  startSpinner,
+  visibleWidth,
+  wrapStyledLine,
+} from "./terminal-ui.js";
+export * from "./constants/index.js";

package/src/terminal-ui.js

@@ -0,0 +1,517 @@
+/**
+ * Dependency-free terminal UI for release commands: colors, banner, rounded
+ * boxes, step headers, spinners and the interactive select prompt.
+ *
+ * Colors go through `util.styleText`, which drops ANSI codes automatically
+ * when stdout is not a TTY or `NO_COLOR` is set. Interactive prompts fall
+ * back to their default answer when stdin is not a TTY, so a command never
+ * hangs in a pipe.
+ *
+ * @module terminal-ui
+ */
+
+import { emitKeypressEvents } from "node:readline";
+import { stripVTControlCharacters, styleText } from "node:util";
+
+import {
+  ANSI_ESCAPE,
+  ANSI_SEQUENCE,
+  ANSI_TOKEN_PATTERN,
+  BOX_PADDING,
+  BOX_TONE,
+  FALLBACK_TERMINAL_WIDTH,
+  HANGING_MARKER_PATTERN,
+  ICON_GLYPH,
+  INTERRUPTED_EXIT_CODE,
+  MAX_BOX_WIDTH,
+  MAX_NUMBERED_OPTIONS,
+  MILLISECONDS_PER_SECOND,
+  NUMBER_KEY_PATTERN,
+  PROMPT_KEY,
+  ROW_LABEL_WIDTH,
+  SECONDS_PER_MINUTE,
+  SPINNER_FRAMES,
+  SPINNER_INTERVAL_MS,
+  TERMINAL_RIGHT_MARGIN,
+  VALUE_COLUMN_PATTERN,
+} from "./constants/terminal-ui.js";
+
+/**
+ * @typedef {Parameters<typeof styleText>[0]} TextFormat
+ * @typedef {{ label: string, hint?: string, description?: string, value: string }} SelectOption
+ */
+
+/** Time spent waiting for answers, excluded from the reported total. */
+let promptWaitMs = 0;
+
+/**
+ * Icons shared by status lines, colored once at import. They use Nerd Font
+ * glyphs, so the terminal needs a Nerd Font.
+ */
+export const ICON = {
+  success: styleText("green", ICON_GLYPH.success),
+  failure: styleText("red", ICON_GLYPH.failure),
+  warning: styleText("yellow", ICON_GLYPH.warning),
+  info: styleText("cyan", ICON_GLYPH.info),
+  pending: styleText("gray", ICON_GLYPH.pending),
+  arrow: styleText("magenta", ICON_GLYPH.arrow),
+  bullet: styleText("gray", ICON_GLYPH.bullet),
+  star: styleText("yellow", ICON_GLYPH.star),
+  rocket: ICON_GLYPH.rocket,
+};
+
+/**
+ * Returns how long the command has waited for the user's answers.
+ *
+ * @returns {number} Milliseconds spent with a prompt open.
+ */
+export function getPromptWaitMs() {
+  return promptWaitMs;
+}
+
+/**
+ * Measures the elapsed time since a start, without the time spent waiting for answers.
+ *
+ * @param {number} startedAt - `Date.now()` when the measured work started.
+ * @param {number} [promptWaitAtStart] - {@link getPromptWaitMs} at that moment.
+ * @returns {number} Active milliseconds.
+ */
+export function measureActiveMs(startedAt, promptWaitAtStart = 0) {
+  return Date.now() - startedAt - (promptWaitMs - promptWaitAtStart);
+}
+
+/**
+ * Moves the cursor up a number of lines.
+ *
+ * @param {number} lineCount - Lines to move.
+ * @returns {string} ANSI sequence, empty when there is nothing to move.
+ */
+function cursorUp(lineCount) {
+  return lineCount > 0 ? `${ANSI_ESCAPE}[${lineCount}A` : "";
+}
+
+/**
+ * Applies one or more `util.styleText` formats.
+ *
+ * @param {TextFormat} format - Format names such as `"bold"` or `["cyan", "bold"]`.
+ * @param {string} text - Text to style.
+ * @returns {string} Styled text (plain when colors are disabled).
+ */
+export function paint(format, text) {
+  return styleText(format, text);
+}
+
+/**
+ * Measures the visible width of a string, ignoring ANSI codes.
+ *
+ * @param {string} text - Possibly styled text.
+ * @returns {number} Visible column count.
+ */
+export function visibleWidth(text) {
+  return [...stripVTControlCharacters(text)].length;
+}
+
+/**
+ * Splits styled text into words (with their ANSI codes) and the spaces between them.
+ *
+ * @param {string} text - Possibly styled text.
+ * @returns {{ text: string, width: number, isSpace: boolean }[]} Segments in order.
+ */
+function splitStyledSegments(text) {
+  /** @type {{ text: string, width: number, isSpace: boolean }[]} */
+  const segments = [];
+
+  for (const token of text.match(ANSI_TOKEN_PATTERN) ?? []) {
+    const isEscape = token.startsWith(ANSI_ESCAPE);
+    const isSpace = !isEscape && token === " ";
+    const last = segments.at(-1);
+
+    // An escape after a space starts the next word so it is never dropped with a line-start space.
+    if (last && ((isEscape && !last.isSpace) || (!isEscape && last.isSpace === isSpace))) {
+      last.text += token;
+      last.width += isEscape ? 0 : 1;
+    } else {
+      segments.push({ text: token, width: isEscape ? 0 : 1, isSpace });
+    }
+  }
+
+  return segments;
+}
+
+/**
+ * Returns the ANSI sequences seen so far, so a continuation line reopens the active styles.
+ *
+ * @param {string} text - Styled text already emitted.
+ * @returns {string} Concatenated escape sequences.
+ */
+function collectEscapes(text) {
+  return (text.match(ANSI_TOKEN_PATTERN) ?? []).filter((token) => token.startsWith(ANSI_ESCAPE)).join("");
+}
+
+/**
+ * Word-wraps a styled line to a visible width without ever cutting it off:
+ * words move to the next line, continuation lines align after a leading
+ * marker (icon, arrow, bullet or `1.`), styles are closed at each break and
+ * reopened on the next line, and a word longer than the width is split.
+ *
+ * @param {string} text - Possibly styled line.
+ * @param {number} width - Maximum visible width.
+ * @returns {string[]} Lines that each fit in `width` columns.
+ */
+export function wrapStyledLine(text, width) {
+  if (visibleWidth(text) <= width) {
+    return [text];
+  }
+
+  // Continuation lines align with the value column of a row, or after a leading marker.
+  const plainText = stripVTControlCharacters(text);
+  const indentPrefix = VALUE_COLUMN_PATTERN.exec(plainText)?.[0] ?? HANGING_MARKER_PATTERN.exec(plainText)?.[0] ?? "";
+  const indentWidth = [...indentPrefix].length;
+  const hangingIndent = indentWidth < width / 2 ? " ".repeat(indentWidth) : "";
+  /** @type {string[]} */
+  const lines = [];
+  let current = "";
+  let currentWidth = 0;
+  let emitted = "";
+
+  const closeLine = () => {
+    const hasStyles = current !== stripVTControlCharacters(current);
+    lines.push(`${current.trimEnd()}${hasStyles ? ANSI_SEQUENCE.reset : ""}`);
+  };
+
+  const breakLine = () => {
+    closeLine();
+    emitted += current;
+    current = `${hangingIndent}${collectEscapes(emitted)}`;
+    currentWidth = hangingIndent.length;
+  };
+
+  for (const segment of splitStyledSegments(text)) {
+    const isLineStart = currentWidth === hangingIndent.length && lines.length > 0;
+
+    if (segment.isSpace) {
+      if (!isLineStart) {
+        current += segment.text;
+        currentWidth += segment.width;
+      }
+      continue;
+    }
+
+    // Move the word to the next line only when it fits there; a longer word is split right here.
+    const fitsOnFreshLine = hangingIndent.length + segment.width <= width;
+    if (currentWidth + segment.width > width && currentWidth > hangingIndent.length && fitsOnFreshLine) {
+      breakLine();
+    }
+
+    // A single word wider than the line is split across lines instead of truncated.
+    for (const token of segment.text.match(ANSI_TOKEN_PATTERN) ?? []) {
+      const isEscape = token.startsWith(ANSI_ESCAPE);
+
+      if (!isEscape && currentWidth >= width) {
+        breakLine();
+      }
+
+      current += token;
+      currentWidth += isEscape ? 0 : 1;
+    }
+  }
+
+  if (stripVTControlCharacters(current).trim()) {
+    closeLine();
+  }
+
+  return lines;
+}
+
+/**
+ * Returns the box width for the current terminal.
+ *
+ * @returns {number} Outer width in columns.
+ */
+export function resolveBoxWidth() {
+  const columns = process.stdout.columns || FALLBACK_TERMINAL_WIDTH;
+  return Math.min(columns - TERMINAL_RIGHT_MARGIN, MAX_BOX_WIDTH);
+}
+
+/**
+ * Renders a rounded box with an optional title in its top border. Long lines
+ * are word-wrapped, never truncated; a title that does not fit in the border
+ * moves inside the box as its first lines.
+ *
+ * @param {{ title?: string, lines: string[], tone?: TextFormat, width?: number }} options - Box content.
+ * @returns {string} Multi-line box.
+ */
+export function renderBox({ title, lines, tone = BOX_TONE.neutral, width = resolveBoxWidth() }) {
+  /** @param {string} text */
+  const border = (text) => paint(tone, text);
+  const innerWidth = width - 2;
+  const contentWidth = innerWidth - BOX_PADDING * 2;
+  const titleText = title ? ` ${paint("bold", title)} ` : "";
+  const titleFits = visibleWidth(titleText) + 1 <= innerWidth;
+  const borderTitle = titleFits ? titleText : "";
+  const topFill = Math.max(innerWidth - visibleWidth(borderTitle) - 1, 0);
+  const top = `${border("╭─")}${borderTitle}${border(`${"─".repeat(topFill)}╮`)}`;
+  const padding = " ".repeat(BOX_PADDING);
+  const contentLines = titleFits || !title ? lines : [paint("bold", title), "", ...lines];
+  const body = contentLines
+    .flatMap((line) => wrapStyledLine(line, contentWidth))
+    .map((line) => {
+      const fill = " ".repeat(Math.max(contentWidth - visibleWidth(line), 0));
+      return `${border("│")}${padding}${line}${fill}${padding}${border("│")}`;
+    });
+  const bottom = border(`╰${"─".repeat(innerWidth)}╯`);
+
+  return [top, ...body, bottom].join("\n");
+}
+
+/**
+ * Renders a label/value row aligned for status panels.
+ *
+ * @param {string} icon - Leading icon.
+ * @param {string} label - Left column.
+ * @param {string} value - Right column.
+ * @param {number} [labelWidth] - Width of the label column.
+ * @returns {string} Row.
+ */
+export function renderRow(icon, label, value, labelWidth = ROW_LABEL_WIDTH) {
+  return `${icon} ${paint("bold", label.padEnd(labelWidth))}${value}`;
+}
+
+/**
+ * Renders the one-line header shown when a release command starts: an
+ * inverted `RELEASE` label, the project name, the published version aligned
+ * to the right and a rule underneath.
+ *
+ * @param {{ projectName: string, publishedLabel: string | null }} options - Header content.
+ * @returns {string} Header.
+ */
+export function renderBanner({ projectName, publishedLabel }) {
+  const width = resolveBoxWidth();
+  const left = `${paint(["inverse", "bold", "magenta"], " RELEASE ")}  ${paint("bold", projectName)}`;
+  const right = publishedLabel ? paint("gray", publishedLabel) : "";
+  const gap = " ".repeat(Math.max(width - visibleWidth(left) - visibleWidth(right), 2));
+
+  return ["", `${left}${gap}${right}`, paint("gray", "─".repeat(width)), ""].join("\n");
+}
+
+/**
+ * Renders the header that introduces each executed step.
+ *
+ * @param {number} stepNumber - 1-based index.
+ * @param {number} stepCount - Total steps.
+ * @param {string} title - Step title.
+ * @returns {string} Header line.
+ */
+export function renderStepHeader(stepNumber, stepCount, title) {
+  const label = paint(["bold", "magenta"], ` PASO ${stepNumber}/${stepCount} `);
+  const text = ` ${paint("bold", title)} `;
+  const fill = Math.max(resolveBoxWidth() - visibleWidth(label) - visibleWidth(text) - 2, 2);
+
+  return `\n${paint("magenta", "━━")}${label}${paint("gray", "━")}${text}${paint("gray", "━".repeat(fill))}`;
+}
+
+/**
+ * Writes a line to stdout.
+ *
+ * @param {string} [text] - Line content.
+ */
+export function print(text = "") {
+  process.stdout.write(`${text}\n`);
+}
+
+/**
+ * Formats a duration in a compact Spanish form.
+ *
+ * @param {number} milliseconds - Duration.
+ * @returns {string} Such as `3.2 s` or `4 min 05 s`.
+ */
+export function formatDuration(milliseconds) {
+  const totalSeconds = milliseconds / MILLISECONDS_PER_SECOND;
+
+  if (totalSeconds < SECONDS_PER_MINUTE) {
+    return `${totalSeconds.toFixed(1)} s`;
+  }
+
+  const minutes = Math.floor(totalSeconds / SECONDS_PER_MINUTE);
+  const seconds = Math.round(totalSeconds % SECONDS_PER_MINUTE);
+  return `${minutes} min ${String(seconds).padStart(2, "0")} s`;
+}
+
+/**
+ * Starts a spinner; on non-TTY outputs it prints the label once instead.
+ *
+ * @param {string} label - Initial label.
+ * @returns {{ update: (label: string) => void, succeed: (label?: string) => void, fail: (label?: string) => void }} Controls.
+ */
+export function startSpinner(label) {
+  const isInteractive = Boolean(process.stdout.isTTY);
+  const startedAt = Date.now();
+  let currentLabel = label;
+  let frameIndex = 0;
+  /** @type {ReturnType<typeof setInterval> | null} */
+  let timer = null;
+
+  const render = () => {
+    const frame = paint("magenta", SPINNER_FRAMES[frameIndex % SPINNER_FRAMES.length]);
+    process.stdout.write(`${ANSI_SEQUENCE.clearLine}${frame} ${currentLabel}`);
+    frameIndex += 1;
+  };
+
+  if (isInteractive) {
+    process.stdout.write(ANSI_SEQUENCE.hideCursor);
+    render();
+    timer = setInterval(render, SPINNER_INTERVAL_MS);
+  } else {
+    print(`${ICON.pending} ${label}`);
+  }
+
+  /**
+   * @param {string} icon - Final icon.
+   * @param {string} [finalLabel] - Final label; defaults to the current one.
+   */
+  const stop = (icon, finalLabel) => {
+    if (timer) {
+      clearInterval(timer);
+      process.stdout.write(`${ANSI_SEQUENCE.clearLine}${ANSI_SEQUENCE.showCursor}`);
+    }
+
+    print(`${icon} ${finalLabel ?? currentLabel} ${paint("gray", formatDuration(Date.now() - startedAt))}`);
+  };
+
+  return {
+    update(nextLabel) {
+      currentLabel = nextLabel;
+      if (!isInteractive) {
+        print(`${ICON.pending} ${nextLabel}`);
+      }
+    },
+    succeed: (finalLabel) => stop(ICON.success, finalLabel),
+    fail: (finalLabel) => stop(ICON.failure, finalLabel),
+  };
+}
+
+/**
+ * Restores the terminal and exits after Ctrl+C.
+ */
+function exitOnInterrupt() {
+  process.stdout.write(`${ANSI_SEQUENCE.showCursor}\n`);
+  print(`${ICON.warning} ${paint("yellow", "Release cancelado por el usuario. No se tocó nada más.")}`);
+  process.exit(INTERRUPTED_EXIT_CODE);
+}
+
+/**
+ * Counts the terminal rows that lines occupy, including the extra rows of
+ * lines wider than the terminal, so a prompt can erase exactly what it drew.
+ *
+ * @param {string[]} lines - Rendered lines, possibly styled.
+ * @param {number} columns - Terminal width in columns.
+ * @returns {number} Physical rows.
+ */
+export function countTerminalRows(lines, columns) {
+  const safeColumns = Math.max(columns, 1);
+  return lines.reduce((rows, line) => rows + Math.max(1, Math.ceil(visibleWidth(line) / safeColumns)), 0);
+}
+
+/**
+ * Maps a typed character to the option it selects.
+ *
+ * @param {string | undefined} text - Character typed by the user.
+ * @param {number} optionCount - Number of options in the prompt.
+ * @returns {number} Zero-based option index, or -1 when the key does not pick an option.
+ */
+export function resolveNumberKey(text, optionCount) {
+  if (!text || !NUMBER_KEY_PATTERN.test(text)) {
+    return -1;
+  }
+
+  const index = Number(text) - 1;
+  return index < Math.min(optionCount, MAX_NUMBERED_OPTIONS) ? index : -1;
+}
+
+/**
+ * Asks the user to choose one option: its number picks it right away, or the
+ * arrow keys move the selection and Enter confirms it.
+ *
+ * @param {{ message: string, options: SelectOption[], defaultIndex?: number }} prompt - Prompt; `description` renders on its own line below the option.
+ * @returns {Promise<string>} Selected value (the default one when stdin is not a TTY).
+ */
+export function select({ message, options, defaultIndex = 0 }) {
+  const input = process.stdin;
+  const question = `${paint(["bold", "cyan"], "?")} ${paint("bold", message)}`;
+
+  if (!input.isTTY) {
+    print(`${question} ${paint("gray", `→ ${options[defaultIndex].label} (sin terminal interactiva)`)}`);
+    return Promise.resolve(options[defaultIndex].value);
+  }
+
+  return new Promise((resolve) => {
+    const promptStartedAt = Date.now();
+    let selectedIndex = defaultIndex;
+    let renderedLineCount = 0;
+
+    const render = () => {
+      const lines = [
+        question,
+        ...options.flatMap((option, index) => {
+          const isSelected = index === selectedIndex;
+          const pointer = isSelected ? ICON.arrow : " ";
+          const numberLabel = index < MAX_NUMBERED_OPTIONS ? `${index + 1}.` : "  ";
+          const number = isSelected ? paint(["bold", "magentaBright"], numberLabel) : paint("gray", numberLabel);
+          const label = isSelected ? paint(["bold", "magentaBright"], option.label) : option.label;
+          const hint = option.hint ? `  ${paint("gray", option.hint)}` : "";
+          const optionLine = `  ${pointer} ${number} ${label}${hint}`;
+          return option.description ? [optionLine, `       ${paint("gray", option.description)}`] : [optionLine];
+        }),
+        paint("gray", `  1-${Math.min(options.length, MAX_NUMBERED_OPTIONS)} para elegir · ↑/↓ y Enter para moverte y confirmar`),
+      ];
+      process.stdout.write(`${cursorUp(renderedLineCount)}\r${ANSI_SEQUENCE.clearBelow}${lines.join("\n")}\n`);
+      // Long lines wrap in the terminal: count physical rows so the next redraw erases all of them.
+      renderedLineCount = countTerminalRows(lines, process.stdout.columns || FALLBACK_TERMINAL_WIDTH);
+    };
+
+    const finish = () => {
+      input.off("keypress", onKeypress);
+      input.setRawMode(false);
+      input.pause();
+      const chosen = options[selectedIndex];
+      process.stdout.write(`${cursorUp(renderedLineCount)}\r${ANSI_SEQUENCE.clearBelow}${ANSI_SEQUENCE.showCursor}`);
+      print(`${question} ${paint("magentaBright", chosen.label)}`);
+      promptWaitMs += Date.now() - promptStartedAt;
+      resolve(chosen.value);
+    };
+
+    /**
+     * @param {string | undefined} text - Typed character.
+     * @param {{ name?: string, ctrl?: boolean }} [key] - Parsed key.
+     */
+    const onKeypress = (text, key = {}) => {
+      const numberedIndex = resolveNumberKey(text, options.length);
+      const keyName = key.name ?? "";
+
+      if (key.ctrl && keyName === PROMPT_KEY.interrupt) {
+        input.setRawMode(false);
+        exitOnInterrupt();
+      } else if (numberedIndex !== -1) {
+        selectedIndex = numberedIndex;
+        finish();
+      } else if (PROMPT_KEY.previous.includes(keyName)) {
+        selectedIndex = (selectedIndex - 1 + options.length) % options.length;
+        render();
+      } else if (PROMPT_KEY.next.includes(keyName)) {
+        selectedIndex = (selectedIndex + 1) % options.length;
+        render();
+      } else if (PROMPT_KEY.confirm.includes(keyName)) {
+        finish();
+      }
+    };
+
+    emitKeypressEvents(input);
+    input.setRawMode(true);
+    input.resume();
+    input.on("keypress", onKeypress);
+    process.stdout.write(ANSI_SEQUENCE.hideCursor);
+    render();
+  });
+}
+
+export { BOX_TONE, INTERRUPTED_EXIT_CODE };