beez-rp 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+Todos los cambios relevantes de beez-rp se documentan en este archivo.
+
+El formato sigue [Keep a Changelog](https://keepachangelog.com/es-ES/1.1.0/) y el proyecto usa [Semantic Versioning](https://semver.org/lang/es/).
+
+## [Unreleased]
+
+## [0.1.1] - 2026-09-26
+
+### Added
+
+- Plantilla `.env.example` para configurar el token de npm.
+
+## [0.1.0] - 2026-09-26
+
+### Added
+
+- Reglas de versión compartidas: solo versiones estables `X.Y.Z` y solo la siguiente patch, minor o major, sin saltear, repetir ni bajar versiones.
+- Comando `beez-rp ignore-build` para el `ignoreCommand` de Vercel, que buildea solo cuando la versión de `package.json` es la siguiente versión estable válida.
+- Módulos `changelog` y `changelog-ai` para liberar el bloque `[Unreleased]` de Keep a Changelog y completarlo con Codex.
+- Módulo `terminal-ui` con cajas, spinner y selector interactivo para comandos de release.
+- Fixtures `beez-rp/testing` con todas las variantes de versión rechazadas, para los tests de cada proyecto.
+

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guido Modarelli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# beez-rp
+
+Proceso de release compartido por los proyectos Beez (beez-ui, TuTribu, Control Mensual). No tiene dependencias de runtime: solo usa módulos `node:*`, así que `npx` lo descarga y ejecuta en segundos, incluso antes de instalar las dependencias del proyecto.
+
+## Regla de versiones
+
+- Solo existen versiones estables `X.Y.Z`: nunca `-alpha.X`, `-beta.X`, `-rc.X`, metadata `+build`, prefijos (`v1.2.3`) ni ceros a la izquierda.
+- Después de una versión solo se permite la siguiente patch, minor o major. De `1.2.3` valen `1.2.4`, `1.3.0` o `2.0.0`.
+- No se puede repetir, bajar ni saltear versiones (`1.0.0` → `3.0.0`, `1.2.3` → `1.4.0`), ni subir la minor o la major sin reiniciar las partes menores (`1.2.3` → `1.3.3`).
+
+## Módulos
+
+| Import | Contenido |
+| --- | --- |
+| `beez-rp/versions` | `isStableReleaseVersion`, `parseReleaseVersion`, `bumpReleaseVersion`, `listNextVersions`, `listAllowedVersionsAfter`, `resolveRequestedVersion` (`--bump` / `--set-version`), `toReleaseTag`, `isReleaseCommitSubject`, `suggestReleaseType`. |
+| `beez-rp/build-gate` | `decideBuild(previousVersion, currentVersion)` y `decideBuildForCheckout(repositoryRoot)` para el `ignoreCommand` de Vercel. |
+| `beez-rp/changelog` | Lectura y release del bloque `## [Unreleased]` de `CHANGELOG.md` (Keep a Changelog). |
+| `beez-rp/changelog-ai` | Prompt e invocación de Codex para completar `[Unreleased]` vacío. |
+| `beez-rp/terminal-ui` | Cajas, filas, banner, spinner y selector interactivo sin dependencias. |
+| `beez-rp/testing` | Fixtures de versiones permitidas y rechazadas para los tests de cada proyecto. |
+| `beez-rp/constants` | Todas las constantes, agrupadas por dominio. |
+
+## Gate de Vercel
+
+`beez-rp ignore-build` compara la versión de `package.json` del commit desplegado con la de `HEAD^`. Imprime el motivo y, como última línea, `BUILD` o `SKIP`, y sale con `0`. Si no puede decidir, sale con `2`.
+
+El `ignoreCommand` de Vercel corre antes de instalar dependencias. Por eso cada proyecto usa un wrapper que buildea solo cuando la última línea es `BUILD`: cualquier otra salida, incluido un fallo de `npx` o de red, saltea el build.
+
+```bash
+#!/bin/bash
+# scripts/ignore-build.sh — Vercel: exit 0 saltea el build, exit 1 buildea.
+set -u
+GATE_OUTPUT=$(npx --yes beez-rp@X.Y.Z ignore-build)
+GATE_EXIT_CODE=$?
+echo "$GATE_OUTPUT"
+if [ "$GATE_EXIT_CODE" -eq 0 ] && [ "$(printf '%s\n' "$GATE_OUTPUT" | tail -n 1)" = "BUILD" ]; then
+  exit 1
+fi
+exit 0
+```
+
+```json
+{ "ignoreCommand": "bash scripts/ignore-build.sh" }
+```
+
+## Tests en los proyectos
+
+```ts
+import { REJECTED_VERSION_BUMP_CASES, CURRENT_STABLE_VERSION } from "beez-rp/testing";
+import { resolveRequestedVersion } from "beez-rp/versions";
+
+it.each(REJECTED_VERSION_BUMP_CASES)("rechaza %s (%j)", (_reason, version) => {
+  expect(() => resolveRequestedVersion(CURRENT_STABLE_VERSION, { bump: null, setVersion: version })).toThrow();
+});
+```
+
+## Publicar beez-rp
+
+```bash
+pnpm create-version            # o pnpm cv
+pnpm cv --bump patch|minor|major
+pnpm cv --set-version X.Y.Z    # solo la siguiente patch, minor o major
+pnpm cv --dry-run              # diagnóstico y plan, sin cambiar nada
+```
+
+El comando sale solo desde `main`, limpio y al día con origin (solo `CHANGELOG.md` puede quedar sin commitear).
+
+1. Si `[Unreleased]` está vacío, lo completa Codex a partir de los commits sin publicar.
+2. Corre `pnpm check`.
+3. Pide la versión, pasa `[Unreleased]` a `## [X.Y.Z] - AAAA-MM-DD` y crea el commit `X.Y.Z` con el tag `vX.Y.Z`.
+4. Sube `main` y el tag con `git push --atomic`.
+5. Publica en npm. El `.npmrc` del repo referencia `${NPM_TOKEN}`, que se toma del entorno o de un `.env` ignorado por Git.
+
+Si algo falla después del commit, volver a correr el comando retoma solo el push o la publicación, sin generar otra versión.
+
+## Desarrollo
+
+```bash
+pnpm install
+pnpm check        # typecheck (JSDoc con checkJs) + tests
+pnpm build:types  # genera types/*.d.ts (también corre en prepack)
+```

package/bin/beez-rp.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * `beez-rp` command line.
+ *
+ * `beez-rp ignore-build` prints why the current checkout is built or skipped
+ * and, as its last line, the decision (`BUILD` or `SKIP`), exiting with `0`.
+ * It exits with `2` when it cannot decide. Vercel wrappers must build only
+ * when the last line is `BUILD`, so any failure (including `npx` itself)
+ * skips the build.
+ *
+ * @module beez-rp-cli
+ */
+
+import { decideBuildForCheckout } from "../src/build-gate.js";
+import { BUILD_DECISION, DECISION_EXIT_CODE, GATE_FAILURE_EXIT_CODE } from "../src/constants/build-gate.js";
+import { CLI_COMMAND } from "../src/constants/cli.js";
+
+/** Usage printed for unknown commands. */
+const USAGE = `Usage: beez-rp ${CLI_COMMAND.ignoreBuild}`;
+
+const [command] = process.argv.slice(2);
+
+if (command !== CLI_COMMAND.ignoreBuild) {
+  console.error(`beez-rp: unknown command "${command ?? ""}". ${USAGE}`);
+  process.exitCode = GATE_FAILURE_EXIT_CODE;
+} else {
+  try {
+    const decision = decideBuildForCheckout(process.cwd());
+    console.log(decision.reason);
+    console.log(decision.shouldBuild ? BUILD_DECISION.build : BUILD_DECISION.skip);
+    process.exitCode = DECISION_EXIT_CODE;
+  } catch (error) {
+    console.error("beez-rp ignore-build: could not decide; the build must be skipped.", error);
+    process.exitCode = GATE_FAILURE_EXIT_CODE;
+  }
+}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "beez-rp",
+  "version": "0.1.1",
+  "description": "Dependency-free release process shared by the Beez projects: stable version rules, Vercel build gate, Keep a Changelog and terminal UI.",
+  "license": "MIT",
+  "author": "Guido Modarelli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/guidomodarelli/beez-rp.git"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@12.6.0",
+  "bin": {
+    "beez-rp": "./bin/beez-rp.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./versions": {
+      "types": "./types/versions.d.ts",
+      "default": "./src/versions.js"
+    },
+    "./build-gate": {
+      "types": "./types/build-gate.d.ts",
+      "default": "./src/build-gate.js"
+    },
+    "./changelog": {
+      "types": "./types/changelog.d.ts",
+      "default": "./src/changelog.js"
+    },
+    "./changelog-ai": {
+      "types": "./types/changelog-ai.d.ts",
+      "default": "./src/changelog-ai.js"
+    },
+    "./terminal-ui": {
+      "types": "./types/terminal-ui.d.ts",
+      "default": "./src/terminal-ui.js"
+    },
+    "./testing": {
+      "types": "./types/testing.d.ts",
+      "default": "./src/testing.js"
+    },
+    "./constants": {
+      "types": "./types/constants/index.d.ts",
+      "default": "./src/constants/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "src",
+    "types",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "scripts": {
+    "build:types": "tsc -p tsconfig.types.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "check": "pnpm typecheck && pnpm test",
+    "create-version": "node scripts/release.js",
+    "cv": "node scripts/release.js",
+    "prepack": "pnpm build:types"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.4",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  }
+}

package/src/build-gate.js

@@ -0,0 +1,93 @@
+/**
+ * Decides whether Vercel builds a commit (`vercel.json` → `ignoreCommand`).
+ *
+ * Only a stable `X.Y.Z` version that is the next patch, minor or major of the
+ * previous commit's version ships, the same rule `create-version` applies. An
+ * unchanged, lower or skipped version (`1.0.0` → `3.0.0`) and any prerelease
+ * or build-metadata version skip the build. When the previous version cannot
+ * be read there is nothing to compare, so a stable version builds.
+ *
+ * @module build-gate
+ */
+
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+import { PACKAGE_MANIFEST_FILE, PREVIOUS_REVISION } from "./constants/build-gate.js";
+import { isStableReleaseVersion, listAllowedVersionsAfter } from "./versions.js";
+
+/**
+ * @typedef {{ shouldBuild: boolean, reason: string }} BuildDecision
+ */
+
+/**
+ * Decides whether a commit is built.
+ *
+ * @param {string | null} previousVersion - Version of the previous commit, or `null` when unreadable.
+ * @param {string | null} currentVersion - Version of the commit being deployed, or `null` when unreadable.
+ * @returns {BuildDecision} Decision and a log line.
+ */
+export function decideBuild(previousVersion, currentVersion) {
+  if (currentVersion === null) {
+    return { shouldBuild: false, reason: "Current package version could not be read. Skipping build." };
+  }
+
+  if (!isStableReleaseVersion(currentVersion)) {
+    return { shouldBuild: false, reason: `Version ${currentVersion} is not a stable X.Y.Z release. Skipping build.` };
+  }
+
+  const allowedVersions = previousVersion === null ? null : listAllowedVersionsAfter(previousVersion);
+
+  if (allowedVersions === null) {
+    return { shouldBuild: true, reason: `Previous package version could not be compared. Building stable ${currentVersion}.` };
+  }
+
+  if (currentVersion === previousVersion) {
+    return { shouldBuild: false, reason: "Version did not change. Skipping build." };
+  }
+
+  if (!allowedVersions.includes(currentVersion)) {
+    return {
+      shouldBuild: false,
+      reason: `Version ${previousVersion} -> ${currentVersion} is not the next patch, minor or major (${allowedVersions.join(", ")}). Skipping build.`,
+    };
+  }
+
+  return { shouldBuild: true, reason: `Version changed: ${previousVersion} -> ${currentVersion}. Building.` };
+}
+
+/**
+ * Reads the `version` field of a `package.json` text.
+ *
+ * @param {() => string} readManifest - Returns the manifest contents.
+ * @returns {string | null} Version, or `null` when unreadable.
+ */
+function readVersion(readManifest) {
+  try {
+    const version = JSON.parse(readManifest()).version;
+    return typeof version === "string" ? version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Reads the previous and the current `package.json` versions of a Git
+ * checkout and decides whether it is built.
+ *
+ * @param {string} repositoryRoot - Checkout whose `HEAD` is being deployed.
+ * @returns {BuildDecision} Decision and a log line.
+ */
+export function decideBuildForCheckout(repositoryRoot) {
+  const previousVersion = readVersion(() =>
+    execFileSync("git", ["show", `${PREVIOUS_REVISION}:${PACKAGE_MANIFEST_FILE}`], {
+      cwd: repositoryRoot,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    })
+  );
+  const currentVersion = readVersion(() => readFileSync(path.join(repositoryRoot, PACKAGE_MANIFEST_FILE), "utf8"));
+
+  return decideBuild(previousVersion, currentVersion);
+}

package/src/changelog-ai.js

@@ -0,0 +1,52 @@
+/**
+ * Asks Codex to fill the CHANGELOG `[Unreleased]` block when a release finds it empty.
+ *
+ * The prompt travels through stdin (`codex exec -`), so the shell command stays a
+ * fixed string on Windows, where `codex` is a `.cmd` shim that needs a shell.
+ *
+ * @module changelog-ai
+ */
+
+import { spawn } from "node:child_process";
+
+import { CHANGE_TYPES, UNRELEASED_HEADING } from "./constants/changelog.js";
+import { CODEX_COMMAND, CODEX_NOT_FOUND_EXIT_CODE, PROMPT_SHORT_SHA_LENGTH } from "./constants/changelog-ai.js";
+
+/**
+ * Builds the instructions for Codex from the commits that will ship.
+ *
+ * @param {{ sha: string, subject: string }[]} commits - Unreleased commits, newest first.
+ * @param {string} audience - Who reads the changelog, e.g. "quien consume el paquete".
+ * @returns {string} Prompt in Spanish.
+ */
+export function buildChangelogPrompt(commits, audience) {
+  const commitList = commits.map((commit) => `- ${commit.sha.slice(0, PROMPT_SHORT_SHA_LENGTH)} ${commit.subject}`).join("\n");
+  return [
+    `Completá el bloque \`${UNRELEASED_HEADING}\` de CHANGELOG.md siguiendo Keep a Changelog.`,
+    `- Agrupá las entradas bajo \`### ${CHANGE_TYPES.join("`, `### ")}\`, en ese orden y solo las secciones que apliquen.`,
+    `- Una línea \`- \` por cambio, en español, clara para ${audience}; nada de detalles internos de implementación.`,
+    `- Si \`${UNRELEASED_HEADING}\` no existe, crealo justo debajo del título del documento.`,
+    "- Modificá únicamente CHANGELOG.md: no toques las versiones ya publicadas, ni otros archivos, ni hagas commits.",
+    "- Usá `git show <sha>` si necesitás ver el detalle de un commit.",
+    "",
+    "Commits sin publicar (del más nuevo al más viejo):",
+    commitList,
+  ].join("\n");
+}
+
+/**
+ * Runs Codex non-interactively with the prompt on stdin, showing its progress.
+ *
+ * @param {string} root - Repository directory where Codex edits CHANGELOG.md.
+ * @param {string} prompt - Instructions from {@link buildChangelogPrompt}.
+ * @returns {Promise<number>} Codex exit code; {@link CODEX_NOT_FOUND_EXIT_CODE} when the CLI is not installed.
+ */
+export function runCodex(root, prompt) {
+  return new Promise((resolve) => {
+    // The command line is a constant; the prompt only travels through stdin.
+    const child = spawn(CODEX_COMMAND, { cwd: root, shell: true, stdio: ["pipe", "inherit", "inherit"] });
+    child.on("error", () => resolve(CODEX_NOT_FOUND_EXIT_CODE));
+    child.on("close", (status) => resolve(status ?? 1));
+    child.stdin.end(prompt);
+  });
+}

package/src/changelog.js

@@ -0,0 +1,109 @@
+/**
+ * Reads and releases CHANGELOG.md in the Keep a Changelog format.
+ *
+ * Every change adds its entries under `## [Unreleased]`, grouped by change
+ * type (`### Added`, `### Changed`, `### Deprecated`, `### Removed`,
+ * `### Fixed`, `### Security`). Releasing moves that block under
+ * `## [X.Y.Z] - YYYY-MM-DD` and leaves an empty `## [Unreleased]` on top.
+ * Headings of older releases without brackets (`## 0.6.0 - 2026-09-23`)
+ * remain valid.
+ *
+ * @module changelog
+ */
+
+import {
+  CHANGE_TYPES,
+  ENTRY_LINE_PATTERN,
+  LEADING_WHITESPACE_PATTERN,
+  LINE_BREAK_PATTERN,
+  RELEASE_HEADING_PATTERN,
+  SECTION_HEADING_PATTERN,
+  UNRELEASED_HEADING,
+  UNRELEASED_LINE_PATTERN,
+} from "./constants/changelog.js";
+
+/**
+ * @typedef {{ label: string, heading: string, start: number, bodyStart: number, end: number }} ChangelogBlock
+ * @typedef {{ exists: boolean, entryCount: number, unknownSections: string[], body: string }} UnreleasedState
+ */
+
+/**
+ * Splits the changelog into release blocks in document order.
+ *
+ * @param {string} changelog - CHANGELOG.md contents.
+ * @returns {ChangelogBlock[]} Blocks.
+ */
+function listBlocks(changelog) {
+  const headings = [...changelog.matchAll(RELEASE_HEADING_PATTERN)];
+  return headings.map((match, index) => {
+    const start = match.index ?? 0;
+    return {
+      label: match[1],
+      heading: match[0],
+      start,
+      bodyStart: start + match[0].length,
+      end: headings[index + 1]?.index ?? changelog.length,
+    };
+  });
+}
+
+/**
+ * Counts the change entries of a block body.
+ *
+ * @param {string} body - Block text below its heading.
+ * @returns {number} Number of `- ` lines.
+ */
+function countEntries(body) {
+  return body.split(LINE_BREAK_PATTERN).filter((line) => ENTRY_LINE_PATTERN.test(line)).length;
+}
+
+/**
+ * Describes the `## [Unreleased]` block.
+ *
+ * @param {string} changelog - CHANGELOG.md contents.
+ * @returns {UnreleasedState} Unreleased state.
+ */
+export function readUnreleased(changelog) {
+  const block = listBlocks(changelog).find((candidate) => UNRELEASED_LINE_PATTERN.test(candidate.heading));
+  if (!block) return { exists: false, entryCount: 0, unknownSections: [], body: "" };
+  const body = changelog.slice(block.bodyStart, block.end);
+  const unknownSections = [...body.matchAll(SECTION_HEADING_PATTERN)]
+    .map((match) => match[1])
+    .filter((name) => !CHANGE_TYPES.includes(name));
+  return { exists: true, entryCount: countEntries(body), unknownSections, body: body.trim() };
+}
+
+/**
+ * Returns the newest released block (the first one that is not `[Unreleased]`).
+ *
+ * @param {string} changelog - CHANGELOG.md contents.
+ * @returns {{ version: string, entryCount: number } | null} Latest release entry.
+ */
+export function readLatestRelease(changelog) {
+  const block = listBlocks(changelog).find((candidate) => !UNRELEASED_LINE_PATTERN.test(candidate.heading));
+  return block ? { version: block.label, entryCount: countEntries(changelog.slice(block.bodyStart, block.end)) } : null;
+}
+
+/**
+ * Moves the `[Unreleased]` changes under a new version heading and leaves an empty `[Unreleased]` block.
+ *
+ * @param {string} changelog - CHANGELOG.md contents.
+ * @param {string} version - Version being released.
+ * @param {string} releaseDate - Date in `YYYY-MM-DD` format.
+ * @returns {string} Released changelog.
+ * @throws {Error} When `[Unreleased]` is missing, empty or uses an unknown section.
+ */
+export function releaseUnreleased(changelog, version, releaseDate) {
+  const unreleased = readUnreleased(changelog);
+  if (!unreleased.exists) throw new Error(`create-version: CHANGELOG.md needs a "${UNRELEASED_HEADING}" block`);
+  if (unreleased.unknownSections.length > 0) {
+    throw new Error(
+      `create-version: CHANGELOG.md [Unreleased] uses unknown sections (${unreleased.unknownSections.join(", ")}); use ${CHANGE_TYPES.join(", ")}`
+    );
+  }
+  if (unreleased.entryCount === 0) throw new Error("create-version: CHANGELOG.md [Unreleased] has no changes to release");
+  const block = listBlocks(changelog).find((candidate) => UNRELEASED_LINE_PATTERN.test(candidate.heading));
+  if (!block) throw new Error(`create-version: CHANGELOG.md needs a "${UNRELEASED_HEADING}" block`);
+  const released = `${UNRELEASED_HEADING}\n\n## [${version}] - ${releaseDate}\n\n${unreleased.body}\n\n`;
+  return `${changelog.slice(0, block.start)}${released}${changelog.slice(block.end).replace(LEADING_WHITESPACE_PATTERN, "")}`;
+}

package/src/constants/build-gate.js

@@ -0,0 +1,24 @@
+/**
+ * Contract between the `beez-rp ignore-build` command and the Vercel
+ * `ignoreCommand` wrapper that reads its output.
+ *
+ * @module constants/build-gate
+ */
+
+/** Decision printed as the last output line of `beez-rp ignore-build`. */
+export const BUILD_DECISION = Object.freeze({
+  build: "BUILD",
+  skip: "SKIP",
+});
+
+/** Git revision whose `package.json` holds the previous version. */
+export const PREVIOUS_REVISION = "HEAD^";
+
+/** Manifest that holds the version. */
+export const PACKAGE_MANIFEST_FILE = "package.json";
+
+/** Exit code of `beez-rp ignore-build` when a decision was printed. */
+export const DECISION_EXIT_CODE = 0;
+
+/** Exit code of `beez-rp ignore-build` when it could not decide; wrappers must skip the build. */
+export const GATE_FAILURE_EXIT_CODE = 2;

package/src/constants/changelog-ai.js

@@ -0,0 +1,14 @@
+/**
+ * Codex invocation used to fill an empty `[Unreleased]` block.
+ *
+ * @module constants/changelog-ai
+ */
+
+/** Exit code shells use when a command does not exist. */
+export const CODEX_NOT_FOUND_EXIT_CODE = 127;
+
+/** Fixed Codex command: non-interactive, allowed to edit the workspace, no saved session, prompt on stdin. */
+export const CODEX_COMMAND = "codex exec --sandbox workspace-write --ephemeral --color never -";
+
+/** Length of the abbreviated commit ids listed in the prompt. */
+export const PROMPT_SHORT_SHA_LENGTH = 7;

package/src/constants/changelog.js

@@ -0,0 +1,32 @@
+/**
+ * Keep a Changelog contract used to read and release `CHANGELOG.md`.
+ *
+ * @module constants/changelog
+ */
+
+/** Changelog file released together with `package.json`. */
+export const CHANGELOG_FILE = "CHANGELOG.md";
+
+/** Heading of the block that collects changes not yet released. */
+export const UNRELEASED_HEADING = "## [Unreleased]";
+
+/** Change types allowed as `###` sections, in Keep a Changelog order. */
+export const CHANGE_TYPES = Object.freeze(["Added", "Changed", "Deprecated", "Removed", "Fixed", "Security"]);
+
+/** Any release-level heading: `## [Unreleased]`, `## [0.7.0] - 2026-09-26` or `## 0.6.0 - 2026-09-23`. */
+export const RELEASE_HEADING_PATTERN = /^## +\[?([^\]\s]+)\]?[^\n]*$/gmu;
+
+/** Unreleased heading, case-insensitive, as its own line. */
+export const UNRELEASED_LINE_PATTERN = /^## +\[Unreleased\][ \t]*$/imu;
+
+/** A change entry line. */
+export const ENTRY_LINE_PATTERN = /^\s*- +\S/mu;
+
+/** A change-type section heading inside a release block. */
+export const SECTION_HEADING_PATTERN = /^### +(.+?)\s*$/gmu;
+
+/** Leading whitespace left before the next block after moving `[Unreleased]`. */
+export const LEADING_WHITESPACE_PATTERN = /^\s+/u;
+
+/** Line break in a changelog written on any platform. */
+export const LINE_BREAK_PATTERN = /\r?\n/u;

package/src/constants/cli.js

@@ -0,0 +1,10 @@
+/**
+ * Commands understood by the `beez-rp` command line.
+ *
+ * @module constants/cli
+ */
+
+/** Command names accepted as the first `beez-rp` argument. */
+export const CLI_COMMAND = Object.freeze({
+  ignoreBuild: "ignore-build",
+});

package/src/constants/index.js

@@ -0,0 +1,12 @@
+/**
+ * Facade of every `beez-rp` constant, grouped by domain.
+ *
+ * @module constants
+ */
+
+export * from "./build-gate.js";
+export * from "./changelog.js";
+export * from "./changelog-ai.js";
+export * from "./cli.js";
+export * from "./terminal-ui.js";
+export * from "./versions.js";