beez-rp 0.1.1

package/types/terminal-ui.d.ts

@@ -0,0 +1,180 @@
+/**
+ * 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 { styleText } from "node:util";
+import { BOX_TONE, INTERRUPTED_EXIT_CODE } from "./constants/terminal-ui.js";
+export type TextFormat = Parameters<typeof styleText>[0];
+export type SelectOption = {
+    label: string;
+    hint?: string;
+    description?: string;
+    value: string;
+};
+/**
+ * Icons shared by status lines, colored once at import. They use Nerd Font
+ * glyphs, so the terminal needs a Nerd Font.
+ */
+export declare const ICON: {
+    success: string;
+    failure: string;
+    warning: string;
+    info: string;
+    pending: string;
+    arrow: string;
+    bullet: string;
+    star: string;
+    rocket: "";
+};
+/**
+ * Returns how long the command has waited for the user's answers.
+ *
+ * @returns {number} Milliseconds spent with a prompt open.
+ */
+export declare function getPromptWaitMs(): number;
+/**
+ * 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 declare function measureActiveMs(startedAt: number, promptWaitAtStart?: number): number;
+/**
+ * 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 declare function paint(format: TextFormat, text: string): string;
+/**
+ * Measures the visible width of a string, ignoring ANSI codes.
+ *
+ * @param {string} text - Possibly styled text.
+ * @returns {number} Visible column count.
+ */
+export declare function visibleWidth(text: string): number;
+/**
+ * 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 declare function wrapStyledLine(text: string, width: number): string[];
+/**
+ * Returns the box width for the current terminal.
+ *
+ * @returns {number} Outer width in columns.
+ */
+export declare function resolveBoxWidth(): number;
+/**
+ * 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 declare function renderBox({ title, lines, tone, width }: {
+    title?: string;
+    lines: string[];
+    tone?: TextFormat;
+    width?: number;
+}): string;
+/**
+ * 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 declare function renderRow(icon: string, label: string, value: string, labelWidth?: number): string;
+/**
+ * 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 declare function renderBanner({ projectName, publishedLabel }: {
+    projectName: string;
+    publishedLabel: string | null;
+}): string;
+/**
+ * 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 declare function renderStepHeader(stepNumber: number, stepCount: number, title: string): string;
+/**
+ * Writes a line to stdout.
+ *
+ * @param {string} [text] - Line content.
+ */
+export declare function print(text?: string): void;
+/**
+ * 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 declare function formatDuration(milliseconds: number): string;
+/**
+ * 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 declare function startSpinner(label: string): {
+    update: (label: string) => void;
+    succeed: (label?: string) => void;
+    fail: (label?: string) => void;
+};
+/**
+ * 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 declare function countTerminalRows(lines: string[], columns: number): number;
+/**
+ * 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 declare function resolveNumberKey(text: string | undefined, optionCount: number): number;
+/**
+ * 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 declare function select({ message, options, defaultIndex }: {
+    message: string;
+    options: SelectOption[];
+    defaultIndex?: number;
+}): Promise<string>;
+export { BOX_TONE, INTERRUPTED_EXIT_CODE };

package/types/testing.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Version bump fixtures for the test suites of every repository that uses
+ * `beez-rp`, so `create-version`, the Vercel build gate and any custom release
+ * command are checked against the same rule: from a stable version only the
+ * next patch, minor or major is allowed.
+ *
+ * @module testing
+ */
+/** Stable version every fixture bumps from. */
+export declare const CURRENT_STABLE_VERSION = "1.2.3";
+/** The only versions allowed after {@link CURRENT_STABLE_VERSION}: next patch, minor and major. */
+export declare const ALLOWED_NEXT_VERSIONS: readonly string[];
+/** Every rejected kind of bump from {@link CURRENT_STABLE_VERSION}, grouped by why it is rejected. */
+export declare const REJECTED_VERSION_BUMPS: Readonly<{
+    unchanged: readonly string[];
+    lower: readonly string[];
+    "skips patches": readonly string[];
+    "skips minors": readonly string[];
+    "skips majors": readonly string[];
+    "minor bump without resetting the patch": readonly string[];
+    "major bump without resetting minor and patch": readonly string[];
+    prerelease: readonly string[];
+    "build metadata": readonly string[];
+    "not a plain X.Y.Z": readonly string[];
+}>;
+/**
+ * All rejected bumps as `[reason, version]` pairs for table-driven tests.
+ *
+ * @type {ReadonlyArray<readonly [string, string]>}
+ */
+export declare const REJECTED_VERSION_BUMP_CASES: ReadonlyArray<readonly [string, string]>;

package/types/versions.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Release version rules: only stable `X.Y.Z` versions exist, and after a
+ * version only its next patch, minor or major is allowed (from `1.2.3`:
+ * `1.2.4`, `1.3.0` or `2.0.0`). No version can be skipped, repeated or
+ * lowered, and prereleases or build metadata are never released.
+ *
+ * @module versions
+ */
+export type ReleaseType = "patch" | "minor" | "major";
+export type NextVersion = {
+    releaseType: ReleaseType;
+    version: string;
+};
+/**
+ * @typedef {"patch" | "minor" | "major"} ReleaseType
+ * @typedef {{ releaseType: ReleaseType, version: string }} NextVersion
+ */
+/**
+ * Returns whether a value is a stable `X.Y.Z` release version.
+ *
+ * @param {unknown} version - Candidate version.
+ * @returns {boolean} `true` only for plain `X.Y.Z` without prerelease, metadata, prefix or leading zeros.
+ */
+export declare function isStableReleaseVersion(version: unknown): boolean;
+/**
+ * Parses a stable `X.Y.Z` version.
+ *
+ * @param {string} version - Version such as `0.93.0`.
+ * @returns {[number, number, number]} Major, minor and patch numbers.
+ * @throws {Error} When the version is not a stable release version.
+ */
+export declare function parseReleaseVersion(version: string): [number, number, number];
+/**
+ * Returns the next version for a semver release type.
+ *
+ * @param {string} version - Current `X.Y.Z` version.
+ * @param {ReleaseType} releaseType - One of {@link RELEASE_TYPE}.
+ * @returns {string} Next `X.Y.Z` version.
+ * @throws {Error} When the version is not stable or the release type is unknown.
+ */
+export declare function bumpReleaseVersion(version: string, releaseType: ReleaseType): string;
+/**
+ * Lists the only versions allowed after the current one: the next patch,
+ * minor and major. Anything else would skip versions or go backwards.
+ *
+ * @param {string} currentVersion - Current `X.Y.Z` version.
+ * @returns {NextVersion[]} Allowed next versions, patch first.
+ */
+export declare function listNextVersions(currentVersion: string): NextVersion[];
+/**
+ * Lists the versions allowed after any previous semver version. A previous
+ * prerelease is also followed by its own stable release (`1.0.0-beta.1` →
+ * `1.0.0`).
+ *
+ * @param {string} previousVersion - Previous version, stable or prerelease.
+ * @returns {string[] | null} Allowed versions, or `null` when the previous version is not semver.
+ */
+export declare function listAllowedVersionsAfter(previousVersion: string): string[] | null;
+/**
+ * Resolves the version requested through `--bump` or `--set-version`.
+ *
+ * @param {string} currentVersion - Current `X.Y.Z` version.
+ * @param {{ bump: ReleaseType | null, setVersion: string | null }} request - Parsed CLI options.
+ * @returns {NextVersion | null} Requested version, or `null` to ask interactively.
+ * @throws {Error} With a Spanish message when the request is invalid.
+ */
+export declare function resolveRequestedVersion(currentVersion: string, { bump, setVersion }: {
+    bump: ReleaseType | null;
+    setVersion: string | null;
+}): NextVersion | null;
+/**
+ * Builds the Git tag name of a release version.
+ *
+ * @param {string} version - `X.Y.Z` version.
+ * @returns {string} Tag such as `v0.94.0`.
+ */
+export declare function toReleaseTag(version: string): string;
+/**
+ * Returns whether a commit subject is a release bump commit (`0.93.0`).
+ *
+ * @param {string} subject - Commit subject.
+ * @returns {boolean} `true` for version-only subjects.
+ */
+export declare function isReleaseCommitSubject(subject: string): boolean;
+/**
+ * Suggests the semver release type for the commits that will ship.
+ *
+ * Breaking changes suggest `major`; features (conventional `feat` or legacy
+ * imperative subjects such as "Add ...") suggest `minor`; a set made only of
+ * conventional maintenance commits (`fix`, `chore`, `docs`, ...) suggests
+ * `patch`. Unknown legacy subjects suggest `minor`.
+ *
+ * @param {{ subject: string, body?: string }[]} commits - Commits since the last release.
+ * @returns {{ releaseType: ReleaseType, reason: string }} Suggested type and a Spanish explanation.
+ */
+export declare function suggestReleaseType(commits: {
+    subject: string;
+    body?: string;
+}[]): {
+    releaseType: ReleaseType;
+    reason: string;
+};