beez-rp 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -6,6 +6,19 @@ El formato sigue [Keep a Changelog](https://keepachangelog.com/es-ES/1.1.0/) y e
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-26
+
+### Added
+
+- `beez-rp create-version` (y `beez-rp/create-version`): el comando de release compartido por todos los proyectos, configurable con `beez-rp.config.js` (checks, migraciones, preparación, publicación en npm o propia, textos y resumen).
+- Retoma en un mismo flujo el push de un commit de versión local y la publicación de una versión que npm todavía no tiene.
+- `buildChangelogPrompt` acepta el idioma de las entradas: español por defecto o inglés limitado a ASCII.
+
+### Changed
+
+- El último release es el último commit de `origin/main` que cambió la versión de `package.json`, así que también reconoce releases con otros asuntos o versiones subidas a mano.
+- beez-rp se publica con su propio `beez-rp create-version` en lugar de un script aparte.
+
 ## [0.1.1] - 2026-09-26
 
 ### Added

package/README.md

@@ -17,6 +17,7 @@ Proceso de release compartido por los proyectos Beez (beez-ui, TuTribu, Control
 | `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/create-version` | Comando compartido de release: `runCreateVersion`, el planificador puro `buildReleasePlan`, el lector de estado y los tipos de `beez-rp.config.js`. |
 | `beez-rp/testing` | Fixtures de versiones permitidas y rechazadas para los tests de cada proyecto. |
 | `beez-rp/constants` | Todas las constantes, agrupadas por dominio. |
 
@@ -54,7 +55,13 @@ it.each(REJECTED_VERSION_BUMP_CASES)("rechaza %s (%j)", (_reason, version) => {
 });
 ```
 
-## Publicar beez-rp
+## create-version
+
+Cada proyecto versiona con el mismo comando y describe sus diferencias en `beez-rp.config.js` (o `beez-rp.config.mjs`, que tiene prioridad y conviene en proyectos sin `"type": "module"`):
+
+```json
+{ "scripts": { "create-version": "beez-rp create-version", "cv": "beez-rp create-version" } }
+```
 
 ```bash
 pnpm create-version            # o pnpm cv
@@ -63,15 +70,46 @@ 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).
+El comando sale solo desde `main`, limpio y al día con origin (solo `CHANGELOG.md` puede quedar sin commitear). En una rama feature explica qué falta: pushear, abrir o mergear el PR (con `gh`).
+
+1. Actualiza `main` desde origin si está atrás.
+2. Aplica migraciones pendientes, si el proyecto tiene adaptador, después de pedir confirmación.
+3. Si `[Unreleased]` está vacío, lo completa Codex a partir de los commits sin publicar.
+4. Corre los `checks`.
+5. Pide la versión, pasa `[Unreleased]` a `## [X.Y.Z] - AAAA-MM-DD` y crea el commit `X.Y.Z` con el tag anotado `vX.Y.Z`.
+6. Corre `prepare`, sube `main` y el tag con `git push --atomic` y corre `publish`.
+
+El último release es el último commit de `origin/main` que cambió el `version` de `package.json`, así que sirve con commits `X.Y.Z`, con otros asuntos de release y con versiones subidas a mano. Si algo falla después del commit, volver a correr el comando retoma solo lo que falta: el push de un commit de versión local o, con `registry: "npm"`, la preparación y publicación de una versión que npm todavía no tiene.
+
+### beez-rp.config.js
+
+```js
+/** @type {import("beez-rp/create-version").CreateVersionConfig} */
+export default {
+  projectName: "TuTribu",                       // banner; por defecto el name de package.json
+  changelog: { audience: "quien usa TuTribu", language: "es" }, // "en": entradas en inglés ASCII
+  releaseTypeDescriptions: { patch: "…", minor: "…", major: "…" },
+  publishedLabel: "en producción",              // banner: vX.Y.Z en producción
+  registry: "npm",                              // retoma y banner según las versiones en npm
+  checks: ["pnpm check"],                       // antes de tocar la versión
+  migrations: { check, apply, targetHint },     // adaptador de base de datos
+  prepare: ["pnpm release:prepare"],            // comandos o función, sobre el commit de versión
+  publish: "npm",                               // npm publish con NPM_TOKEN, o una función
+  summary: ["Vercel buildea {version}."],       // líneas extra del resumen final
+};
+```
+
+Solo `changelog.audience` es obligatorio. Los hooks (`migrations.check`, `migrations.apply`, `prepare`, `publish`) reciben `{ repositoryRoot, version, git, run, print, fail }`: `git` lee Git, `run("pnpm x")` corre un comando visible y devuelve su exit code, y `fail(mensaje, qué hacer)` corta el paso con una explicación. El config no necesita importar `beez-rp`.
+
+`migrations.check` devuelve `{ status: "up-to-date" | "pending" | "unknown", pending, target, reason }`; después de `apply`, el comando vuelve a llamar a `check` y falla si siguen pendientes. `publish: "npm"` toma `NPM_TOKEN` del entorno o de un `.env` ignorado por Git, referenciado por el `.npmrc` del repo.
+
+## Publicar beez-rp
 
-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.
+beez-rp se publica con su propio comando (`beez-rp.config.js`: `checks: ["pnpm check"]`, `publish: "npm"`):
 
-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.
+```bash
+pnpm cv
+```
 
 ## Desarrollo
 

package/bin/beez-rp.js

@@ -2,11 +2,14 @@
 /**
  * `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.
+ * - `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.
+ * - `beez-rp create-version [--bump patch|minor|major | --set-version X.Y.Z] [--dry-run]`
+ *   diagnoses the repository in the current directory and ships its release
+ *   from `main`, following its `beez-rp.config.js`.
  *
  * @module beez-rp-cli
  */
@@ -14,16 +17,16 @@
 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";
+import { runCreateVersion } from "../src/create-version/run.js";
 
 /** Usage printed for unknown commands. */
-const USAGE = `Usage: beez-rp ${CLI_COMMAND.ignoreBuild}`;
+const USAGE = `Usage: beez-rp ${CLI_COMMAND.ignoreBuild} | beez-rp ${CLI_COMMAND.createVersion} [options]`;
 
-const [command] = process.argv.slice(2);
+const [command, ...commandArguments] = process.argv.slice(2);
 
-if (command !== CLI_COMMAND.ignoreBuild) {
-  console.error(`beez-rp: unknown command "${command ?? ""}". ${USAGE}`);
-  process.exitCode = GATE_FAILURE_EXIT_CODE;
-} else {
+if (command === CLI_COMMAND.createVersion) {
+  process.exitCode = await runCreateVersion({ repositoryRoot: process.cwd(), argv: commandArguments });
+} else if (command === CLI_COMMAND.ignoreBuild) {
   try {
     const decision = decideBuildForCheckout(process.cwd());
     console.log(decision.reason);
@@ -33,4 +36,7 @@ if (command !== CLI_COMMAND.ignoreBuild) {
     console.error("beez-rp ignore-build: could not decide; the build must be skipped.", error);
     process.exitCode = GATE_FAILURE_EXIT_CODE;
   }
+} else {
+  console.error(`beez-rp: unknown command "${command ?? ""}". ${USAGE}`);
+  process.exitCode = GATE_FAILURE_EXIT_CODE;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beez-rp",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "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",
@@ -46,6 +46,10 @@
       "types": "./types/testing.d.ts",
       "default": "./src/testing.js"
     },
+    "./create-version": {
+      "types": "./types/create-version/index.d.ts",
+      "default": "./src/create-version/index.js"
+    },
     "./constants": {
       "types": "./types/constants/index.d.ts",
       "default": "./src/constants/index.js"
@@ -65,8 +69,8 @@
     "typecheck": "tsc -p tsconfig.json",
     "test": "vitest run",
     "check": "pnpm typecheck && pnpm test",
-    "create-version": "node scripts/release.js",
-    "cv": "node scripts/release.js",
+    "create-version": "node bin/beez-rp.js create-version",
+    "cv": "node bin/beez-rp.js create-version",
     "prepack": "pnpm build:types"
   },
   "devDependencies": {

package/src/changelog-ai.js

@@ -11,16 +11,33 @@ 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";
+import { CHANGELOG_LANGUAGE } from "./constants/create-version.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.
+ * @param {"es" | "en"} [language] - Language of the entries: Spanish by default, or English limited to ASCII.
+ * @returns {string} Prompt written in the requested language.
  */
-export function buildChangelogPrompt(commits, audience) {
+export function buildChangelogPrompt(commits, audience, language = CHANGELOG_LANGUAGE.spanish) {
   const commitList = commits.map((commit) => `- ${commit.sha.slice(0, PROMPT_SHORT_SHA_LENGTH)} ${commit.subject}`).join("\n");
+
+  if (language === CHANGELOG_LANGUAGE.english) {
+    return [
+      `Fill the \`${UNRELEASED_HEADING}\` block of CHANGELOG.md following Keep a Changelog.`,
+      `- Group entries under \`### ${CHANGE_TYPES.join("`, `### ")}\`, in that order and only the sections that apply.`,
+      `- One \`- \` line per change, in English and ASCII only, clear for ${audience}; no internal implementation details.`,
+      `- If \`${UNRELEASED_HEADING}\` does not exist, create it right below the document title.`,
+      "- Modify only CHANGELOG.md: do not touch released versions or other files, and do not commit.",
+      "- Use `git show <sha>` when you need the details of a commit.",
+      "",
+      "Unreleased commits (newest first):",
+      commitList,
+    ].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.`,

package/src/constants/cli.js

@@ -7,4 +7,5 @@
 /** Command names accepted as the first `beez-rp` argument. */
 export const CLI_COMMAND = Object.freeze({
   ignoreBuild: "ignore-build",
+  createVersion: "create-version",
 });

package/src/constants/create-version.js

@@ -0,0 +1,150 @@
+/**
+ * Git, npm, configuration and display values of the shared `beez-rp create-version` command.
+ *
+ * @module constants/create-version
+ */
+
+/** Branch that receives releases. */
+export const MAIN_BRANCH = "main";
+
+/** Remote that receives releases. */
+export const RELEASE_REMOTE = "origin";
+
+/** Remote-tracking ref of the release branch. */
+export const REMOTE_MAIN_REF = `${RELEASE_REMOTE}/${MAIN_BRANCH}`;
+
+/** Configuration module read from the repository root. */
+export const CREATE_VERSION_CONFIG_FILE = "beez-rp.config.js";
+
+/**
+ * Configuration candidates in lookup order: `.mjs` is always ESM, so projects
+ * without `"type": "module"` load it without Node warnings.
+ */
+export const CREATE_VERSION_CONFIG_FILES = Object.freeze(["beez-rp.config.mjs", CREATE_VERSION_CONFIG_FILE]);
+
+/** Manifest whose `version` is released; shared with the build gate. */
+export { PACKAGE_MANIFEST_FILE } from "./build-gate.js";
+
+/** Pinned Node.js version compared with the running one when present; a full version or only its major. */
+export const PINNED_NODE_VERSION_FILE = ".nvmrc";
+
+/** Environment file that may hold `NPM_TOKEN` locally; ignored by Git. */
+export const LOCAL_ENVIRONMENT_FILE = ".env";
+
+/** Stable identifiers of every step the command knows how to run, in execution order. */
+export const RELEASE_STEP = Object.freeze({
+  syncMain: "sync-main",
+  applyMigrations: "apply-migrations",
+  generateChangelog: "generate-changelog",
+  runChecks: "run-checks",
+  bumpVersion: "bump-version",
+  prepareRelease: "prepare-release",
+  pushRelease: "push-release",
+  publishRelease: "publish-release",
+});
+
+/** What the command does with the current state. */
+export const RELEASE_MODE = Object.freeze({
+  newRelease: "new-release",
+  resume: "resume",
+  upToDate: "up-to-date",
+  blocked: "blocked",
+});
+
+/** Result of a project migrations adapter. */
+export const MIGRATION_STATUS = Object.freeze({
+  upToDate: "up-to-date",
+  pending: "pending",
+  unknown: "unknown",
+});
+
+/** Pull request states reported by `gh pr view --json state`. */
+export const PULL_REQUEST_STATE = Object.freeze({
+  open: "OPEN",
+  merged: "MERGED",
+  closed: "CLOSED",
+});
+
+/** Fields requested from `gh pr view`. */
+export const PULL_REQUEST_JSON_FIELDS = "number,url,title,state,isDraft,headRefOid";
+
+/** Message `gh pr view` prints when the branch has no pull request. */
+export const NO_PULL_REQUEST_MESSAGE_PATTERN = /no pull requests found/iu;
+
+/** Registries whose published versions drive resumes and the banner. */
+export const RELEASE_REGISTRY = Object.freeze({
+  npm: "npm",
+});
+
+/** Built-in publisher selected with `publish: "npm"`. */
+export const NPM_PUBLISHER = "npm";
+
+/** Result of asking npm which versions of the package exist. */
+export const NPM_LOOKUP_STATUS = Object.freeze({
+  ok: "ok",
+  failed: "failed",
+});
+
+/** Valid npm package name (optionally scoped), checked before it reaches a shell command line. */
+export const NPM_PACKAGE_NAME_PATTERN = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/u;
+
+/** npm error code of a package that was never published. */
+export const NPM_NOT_FOUND_CODE = "E404";
+
+/** Environment variable that holds the npm token; the repository `.npmrc` references it as `${NPM_TOKEN}`. */
+export const NPM_TOKEN_VARIABLE = "NPM_TOKEN";
+
+/** npm dist-tag every stable release is published under. */
+export const NPM_DIST_TAG = "latest";
+
+/** Languages the Codex changelog prompt can request. */
+export const CHANGELOG_LANGUAGE = Object.freeze({
+  spanish: "es",
+  english: "en",
+});
+
+/** Command-line flags of `beez-rp create-version`. */
+export const CREATE_VERSION_FLAG = Object.freeze({
+  bump: "bump",
+  setVersion: "set-version",
+  dryRun: "dry-run",
+  help: "help",
+  helpShort: "h",
+  endOfOptions: "--",
+});
+
+/** Optional `v` prefix accepted in hand-typed versions. */
+export const VERSION_PREFIX_PATTERN = /^v/u;
+
+/** `version` field of `package.json`, replaced in place to keep formatting. */
+export const PACKAGE_VERSION_FIELD_PATTERN = /("version"\s*:\s*")[^"]+(")/u;
+
+/** `git log -G` pattern of a changed top-level `version` field; the last such commit is the last release. */
+export const VERSION_FIELD_CHANGE_PATTERN = `^[[:space:]]*"version"[[:space:]]*:`;
+
+/** GitHub `owner/repo` inside an SSH or HTTPS remote URL. */
+export const GITHUB_REPOSITORY_PATTERN = /github\.com[:/]([^/]+\/[^/]+?)(?:\.git)?$/u;
+
+/** Separates fields inside one `git log --format` record. */
+export const FIELD_SEPARATOR = "\x1f";
+
+/** Separates records in `git log --format` output. */
+export const RECORD_SEPARATOR = "\x1e";
+
+/** Width of the `git status --porcelain` state columns before each path. */
+export const PORCELAIN_STATUS_WIDTH = 3;
+
+/** Maximum commits listed in a box. */
+export const MAX_LISTED_COMMITS = 12;
+
+/** Maximum uncommitted files, foreign commits or pending migrations listed before summarizing. */
+export const MAX_LISTED_ITEMS = 5;
+
+/** Length of the abbreviated commit ids shown to the user. */
+export const SHORT_SHA_LENGTH = 7;
+
+/** Placeholder replaced by the released version in `summary` lines. */
+export const SUMMARY_VERSION_PLACEHOLDER = "{version}";
+
+/** Exit code of a release stopped by a failed step, invalid arguments or configuration. */
+export const FAILURE_EXIT_CODE = 1;

package/src/constants/index.js

@@ -10,3 +10,4 @@ export * from "./changelog-ai.js";
 export * from "./cli.js";
 export * from "./terminal-ui.js";
 export * from "./versions.js";
+export * from "./create-version.js";

package/src/create-version/config.js

@@ -0,0 +1,225 @@
+/**
+ * Loads and validates `beez-rp.config.js`, the per-project part of
+ * `beez-rp create-version`: changelog audience and language, version
+ * descriptions, registry, checks, migrations, preparation and publication.
+ *
+ * The configuration never needs to import `beez-rp`: hooks receive every
+ * helper through their context, so a project can type it with
+ * `@type {import("beez-rp/create-version").CreateVersionConfig}` only.
+ *
+ * @module create-version/config
+ */
+
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import {
+  CHANGELOG_LANGUAGE,
+  CREATE_VERSION_CONFIG_FILE,
+  CREATE_VERSION_CONFIG_FILES,
+  NPM_PUBLISHER,
+  RELEASE_REGISTRY,
+} from "../constants/create-version.js";
+import { RELEASE_TYPE_ORDER } from "../constants/versions.js";
+
+/**
+ * @typedef {import("./process.js").GitReader} GitReader
+ * @typedef {"patch" | "minor" | "major"} ReleaseType
+ * @typedef {{ status: "up-to-date" | "pending" | "unknown", pending: string[], target: string | null, reason: string | null }} MigrationCheck
+ * @typedef {{
+ *   repositoryRoot: string,
+ *   version: string | null,
+ *   git: GitReader,
+ *   run: (commandLine: string) => Promise<number>,
+ *   print: (text?: string) => void,
+ *   fail: (message: string, hint: string) => never,
+ * }} HookContext
+ * @typedef {(context: HookContext) => Promise<void> | void} ReleaseHook
+ * @typedef {{
+ *   check: (context: HookContext) => Promise<MigrationCheck> | MigrationCheck,
+ *   apply: (context: HookContext) => Promise<void> | void,
+ *   targetHint?: string,
+ * }} MigrationsAdapter
+ * @typedef {{
+ *   projectName?: string,
+ *   changelog: { audience: string, language?: "es" | "en" },
+ *   releaseTypeDescriptions?: Partial<Record<ReleaseType, string>>,
+ *   registry?: "npm" | null,
+ *   publishedLabel?: string,
+ *   checks?: string[],
+ *   migrations?: MigrationsAdapter | null,
+ *   prepare?: string[] | ReleaseHook | null,
+ *   publish?: "npm" | ReleaseHook | null,
+ *   summary?: string[],
+ * }} CreateVersionConfig
+ *   `summary` lines replace `{version}` with the released version.
+ * @typedef {{
+ *   projectName: string | null,
+ *   changelog: { audience: string, language: "es" | "en" },
+ *   releaseTypeDescriptions: Record<ReleaseType, string>,
+ *   registry: "npm" | null,
+ *   publishedLabel: string,
+ *   checks: string[],
+ *   migrations: MigrationsAdapter | null,
+ *   prepare: string[] | ReleaseHook | null,
+ *   publish: "npm" | ReleaseHook | null,
+ *   summary: string[],
+ * }} ResolvedCreateVersionConfig
+ */
+
+/** What each release type means when a project does not describe it. */
+const DEFAULT_RELEASE_TYPE_DESCRIPTIONS = Object.freeze({
+  patch: "Solo arreglos o cambios internos; nada nuevo para quien lo usa.",
+  minor: "Funcionalidades nuevas compatibles; lo existente sigue funcionando igual.",
+  major: "Cambio incompatible: quien lo usa tiene que adaptarse.",
+});
+
+/** Banner suffix of the version on `origin/main` when a project does not name its environment. */
+const DEFAULT_PUBLISHED_LABEL = "publicada";
+
+/**
+ * Types a configuration in editors; returns it unchanged.
+ *
+ * @param {CreateVersionConfig} config - Project configuration.
+ * @returns {CreateVersionConfig} The same configuration.
+ */
+export function defineCreateVersionConfig(config) {
+  return config;
+}
+
+/**
+ * Builds a configuration error that names the file and the invalid field.
+ *
+ * @param {string} field - Offending field path.
+ * @param {string} expectation - What the field must be.
+ * @returns {Error} Error to throw.
+ */
+function invalidField(field, expectation) {
+  return new Error(`beez-rp create-version: ${CREATE_VERSION_CONFIG_FILE}: ${field} must be ${expectation}`);
+}
+
+/**
+ * Checks that a value is an array of non-empty strings.
+ *
+ * @param {unknown} value - Candidate.
+ * @returns {value is string[]} Whether it is a string list.
+ */
+function isStringList(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string" && item.trim().length > 0);
+}
+
+/**
+ * Validates a raw configuration and fills its defaults.
+ *
+ * @param {unknown} rawConfig - Default export of `beez-rp.config.js`.
+ * @returns {ResolvedCreateVersionConfig} Configuration ready for the command.
+ * @throws {Error} When a field has an unsupported type or value.
+ */
+export function resolveCreateVersionConfig(rawConfig) {
+  if (!rawConfig || typeof rawConfig !== "object" || Array.isArray(rawConfig)) {
+    throw invalidField("the default export", "an object");
+  }
+
+  const config = /** @type {Record<string, unknown>} */ (rawConfig);
+  const changelog = /** @type {Record<string, unknown> | undefined} */ (config.changelog);
+
+  if (!changelog || typeof changelog.audience !== "string" || changelog.audience.trim() === "") {
+    throw invalidField("changelog.audience", "a non-empty string describing who reads the changelog");
+  }
+
+  const language = changelog.language ?? CHANGELOG_LANGUAGE.spanish;
+  if (!(/** @type {readonly unknown[]} */ (Object.values(CHANGELOG_LANGUAGE))).includes(language)) {
+    throw invalidField("changelog.language", `one of ${Object.values(CHANGELOG_LANGUAGE).join(", ")}`);
+  }
+
+  if (config.projectName !== undefined && (typeof config.projectName !== "string" || config.projectName.trim() === "")) {
+    throw invalidField("projectName", "a non-empty string");
+  }
+
+  const descriptions = config.releaseTypeDescriptions ?? {};
+  if (typeof descriptions !== "object" || descriptions === null || Array.isArray(descriptions)) {
+    throw invalidField("releaseTypeDescriptions", "an object keyed by patch, minor and major");
+  }
+  for (const [releaseType, description] of Object.entries(descriptions)) {
+    if (!(/** @type {readonly string[]} */ (RELEASE_TYPE_ORDER)).includes(releaseType) || typeof description !== "string") {
+      throw invalidField(`releaseTypeDescriptions.${releaseType}`, "a string for patch, minor or major");
+    }
+  }
+
+  const publish = config.publish ?? null;
+  if (publish !== null && publish !== NPM_PUBLISHER && typeof publish !== "function") {
+    throw invalidField("publish", `"${NPM_PUBLISHER}", a function or null`);
+  }
+
+  const registry = config.registry ?? (publish === NPM_PUBLISHER ? RELEASE_REGISTRY.npm : null);
+  if (registry !== null && !(/** @type {readonly unknown[]} */ (Object.values(RELEASE_REGISTRY))).includes(registry)) {
+    throw invalidField("registry", `one of ${Object.values(RELEASE_REGISTRY).join(", ")} or null`);
+  }
+
+  const checks = config.checks ?? [];
+  if (!isStringList(checks)) {
+    throw invalidField("checks", "a list of command lines");
+  }
+
+  const prepare = config.prepare ?? null;
+  if (prepare !== null && typeof prepare !== "function" && !isStringList(prepare)) {
+    throw invalidField("prepare", "a list of command lines, a function or null");
+  }
+
+  const migrations = /** @type {MigrationsAdapter | null} */ (config.migrations ?? null);
+  if (migrations !== null && (typeof migrations.check !== "function" || typeof migrations.apply !== "function")) {
+    throw invalidField("migrations", "an object with check and apply functions, or null");
+  }
+  if (migrations?.targetHint !== undefined && typeof migrations.targetHint !== "string") {
+    throw invalidField("migrations.targetHint", "a string");
+  }
+
+  const summary = config.summary ?? [];
+  if (!isStringList(summary)) {
+    throw invalidField("summary", "a list of lines");
+  }
+
+  if (config.publishedLabel !== undefined && typeof config.publishedLabel !== "string") {
+    throw invalidField("publishedLabel", "a string");
+  }
+
+  return {
+    projectName: /** @type {string | undefined} */ (config.projectName) ?? null,
+    changelog: { audience: changelog.audience, language: /** @type {"es" | "en"} */ (language) },
+    releaseTypeDescriptions: { ...DEFAULT_RELEASE_TYPE_DESCRIPTIONS, .../** @type {Partial<Record<ReleaseType, string>>} */ (descriptions) },
+    registry: /** @type {"npm" | null} */ (registry),
+    publishedLabel: /** @type {string | undefined} */ (config.publishedLabel) ?? DEFAULT_PUBLISHED_LABEL,
+    checks,
+    migrations,
+    prepare: /** @type {string[] | ReleaseHook | null} */ (prepare),
+    publish: /** @type {"npm" | ReleaseHook | null} */ (publish),
+    summary,
+  };
+}
+
+/**
+ * Imports `beez-rp.config.mjs` or `beez-rp.config.js` from the repository root and validates it.
+ *
+ * @param {string} repositoryRoot - Repository root.
+ * @returns {Promise<ResolvedCreateVersionConfig>} Resolved configuration.
+ * @throws {Error} When the file is missing, fails to load or is invalid.
+ */
+export async function loadCreateVersionConfig(repositoryRoot) {
+  const configPath = CREATE_VERSION_CONFIG_FILES.map((fileName) => path.join(repositoryRoot, fileName)).find((candidate) => existsSync(candidate));
+
+  if (!configPath) {
+    throw new Error(
+      `beez-rp create-version: ${CREATE_VERSION_CONFIG_FILES.join(" or ")} not found in ${repositoryRoot}; create it with at least changelog.audience`
+    );
+  }
+
+  let module;
+  try {
+    module = await import(pathToFileURL(configPath).href);
+  } catch (error) {
+    throw new Error(`beez-rp create-version: could not load ${configPath}`, { cause: error });
+  }
+
+  return resolveCreateVersionConfig(module.default);
+}

package/src/create-version/errors.js

@@ -0,0 +1,19 @@
+/**
+ * Errors of `beez-rp create-version`.
+ *
+ * @module create-version/errors
+ */
+
+/** Failure of a release step or hook, with a Spanish explanation and the next action to take. */
+export class ReleaseStepError extends Error {
+  /**
+   * @param {string} message - What failed, in Spanish.
+   * @param {string} hint - What to do next, in Spanish.
+   * @param {{ cause?: unknown }} [options] - Original error, when wrapping one.
+   */
+  constructor(message, hint, options) {
+    super(message, options);
+    this.name = "ReleaseStepError";
+    this.hint = hint;
+  }
+}

package/src/create-version/index.js

@@ -0,0 +1,18 @@
+/**
+ * `beez-rp/create-version`: shared release command of the Beez projects.
+ *
+ * Projects run it as `beez-rp create-version` and describe their differences
+ * in `beez-rp.config.js` (changelog audience and language, checks, migrations,
+ * preparation, publication). The pure planner and the state reader are
+ * exported for project tests and custom tooling.
+ *
+ * @module create-version
+ */
+
+export { defineCreateVersionConfig, loadCreateVersionConfig, resolveCreateVersionConfig } from "./config.js";
+export { ReleaseStepError } from "./errors.js";
+export { lookupPublishedVersions, publishToNpm } from "./npm.js";
+export { DEFAULT_CAPABILITIES, RELEASE_USAGE, buildReleasePlan, describeFeatureBranchGaps, parseReleaseArguments } from "./plan.js";
+export { createGitReader, listCommits, parseCommitLog, readPackageVersionAt, runCaptured, runCommandLine, runInherited } from "./process.js";
+export { createHookContext, runCreateVersion } from "./run.js";
+export { collectReleaseState, findLastRelease, readChangelogState } from "./state.js";