beez-rp 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,41 @@ El formato sigue [Keep a Changelog](https://keepachangelog.com/es-ES/1.1.0/) y e
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-27
+
+### Added
+
+- `artifact` en `beez-rp.config.js`: con `publish: "npm"`, publica exactamente el tarball que dejó el paso `prepare` (por ejemplo `releases/{version}-{sha256}/{name}-{version}.tgz`) en vez de reempaquetar el working tree. Los proyectos lo empaquetan con `npm pack --ignore-scripts`.
+- Antes de publicar ese tarball exige que `prepare` no haya modificado archivos versionados, rechaza paquetes que dependen de reescrituras de pnpm al empaquetar (`workspace:`/`catalog:`/`jsr:` o campos del manifest en `publishConfig` que solo pnpm sube a la raíz, como `exports`, `main`, `bin` o `types`; cualquier otra clave de `publishConfig` se acepta como configuración de npm), verifica el SHA-256 de su ruta cuando el patrón usa `{sha256}` y compara su SHA-512 con el `integrity` de `npm pack --dry-run --json --ignore-scripts` del commit de release. Durante esa comparación el tarball queda fuera de la raíz del paquete, así que se verifica aunque el paquete no tenga `files` y su carpeta no esté ignorada.
+- `beez-rp guard-publish` (y `beez-rp/guard-publish`): guard de `prepublishOnly` que bloquea `pnpm publish`, yarn y bun con un mensaje que indica publicar con `pnpm create-version`; `create-version` quita `npm_config_user_agent` del entorno de `npm publish` para no bloquearse.
+
+### Changed
+
+- `publish: "npm"` usa una config de npm temporal que solo referencia `${NPM_TOKEN}`, asociada al registry donde se publica (`publishConfig["@scope:registry"]` de un paquete con scope, `publishConfig.registry` o, si no hay, el registry que resuelve la config de npm en el repo: `.npmrc` del proyecto, variables de entorno o config global): los proyectos ya no necesitan `.npmrc` y pnpm deja de advertir por credenciales en el repositorio. La confirmación 2FA de npm sigue siendo interactiva.
+- El diagnóstico y la comprobación posterior a publicar consultan las versiones con `npm view --registry` en ese mismo registry, así que un paquete publicado en un registry propio ya no se vuelve a preparar y publicar. Con `NPM_TOKEN` (entorno o `.env`) esa consulta se autentica con la misma config temporal, así que también funciona con paquetes privados.
+- El resumen final enlaza a npmjs.com solo cuando se publicó en `https://registry.npmjs.org/`; en otro registry muestra `Registro: <url>` con el paquete y la versión.
+
+### Removed
+
+- `.npmrc` del repositorio de beez-rp.
+
+### Fixed
+
+- Si `main` estaba atrás de `origin/main`, `create-version` lo actualiza y termina sin tocar la versión ni los tags (código de salida 0), pidiendo volver a correr `pnpm create-version`: así el diagnóstico, el plan, las migraciones y `beez-rp.config.(m)js` con sus módulos importados salen del código actualizado y no del `main` anterior.
+
+## [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

@@ -16,7 +16,9 @@ Proceso de release compartido por los proyectos Beez (beez-ui, TuTribu, Control
 | `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/guard-publish` | `decidePublishGuard(userAgent)` del `prepublishOnly` que bloquea publicaciones con pnpm, yarn o bun. |
 | `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 +56,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 +71,71 @@ 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. Si `main` está atrás de origin, lo actualiza en fast-forward y termina (código de salida 0) sin tocar la versión ni los tags: hay que volver a correr `pnpm create-version`, que en un proceso nuevo carga `beez-rp.config.(m)js`, sus módulos y el diagnóstico desde el código actualizado.
+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. Las versiones publicadas se consultan con `npm view --registry` en el mismo registry donde se publica (ver abajo), porque `npm view` no aplica el `publishConfig` del `package.json`.
+
+### 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
+  artifact: "releases/{version}-{sha256}/{name}-{version}.tgz", // con "npm": publica ese tarball verificado
+  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. No hace falta `.npmrc`: el comando escribe una config de npm temporal fuera del repo que asocia `${NPM_TOKEN}` al registry donde realmente se publica, resuelto como npm: `publishConfig["@scope:registry"]` si el paquete tiene ese scope, si no `publishConfig.registry` y, si el `package.json` no declara ninguno, lo que devuelve `npm config get @scope:registry` (paquete con scope) o `npm config get registry` en la raíz del repo, que incluye el `.npmrc` del proyecto, las variables `npm_config_*` y la config global (como la publicación, no lee `~/.npmrc`, que se reemplaza por la config temporal); tiene que ser una URL http(s) válida o no se publica. Con `NPM_TOKEN` disponible, el diagnóstico también consulta `npm view` con esa config temporal, así que funciona con paquetes privados; sin token consulta sin autenticar. El resumen final enlaza a npmjs.com solo si el registry es `https://registry.npmjs.org/`; si no, muestra `Registro: <url>` con el paquete y la versión. Solo guarda esa referencia: npm la expande, el token nunca queda en disco ni en la línea de comandos, y la config se borra al terminar. npm hereda la terminal, así que la confirmación 2FA (navegador o código) funciona igual.
+
+Sin `artifact`, `publish: "npm"` publica el working tree. Con `artifact` publica exactamente el tarball que dejó `prepare`. Los proyectos empaquetan siempre con npm: `prepare` construye (con pnpm o lo que use el proyecto) y después corre `npm pack --ignore-scripts`. `npm pack` es reproducible (el mismo commit da siempre los mismos bytes), así que la verificación es una comparación de hash. Después de `prepare` y antes de `npm publish`:
+
+- Working tree: `git status --porcelain --untracked-files=no` tiene que estar vacío. `prepare` puede generar archivos ignorados o no versionados (`dist/`, `releases/`), pero no modificar archivos versionados como `package.json`; así lo que lee npm es exactamente el commit de release.
+- Publicable con npm: si el `package.json` depende de algo que solo pnpm reescribe al empaquetar (especificadores `workspace:`, `catalog:` o `jsr:` en `dependencies`, `peerDependencies` u `optionalDependencies`, o campos del manifest dentro de `publishConfig` que pnpm sube a la raíz del `package.json` empaquetado), no se publica. Para npm, `publishConfig` es solo [configuración de npm](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#publishconfig), así que se acepta cualquier clave (`registry`, `access`, `tag`, `provenance`, `@scope:registry`, `otp`...) salvo las que pnpm aplica al manifest: `name`, `bin`, `engines`, `type`, `imports`, `main`, `module`, `typings`, `types`, `exports`, `browser`, `esnext`, `es2015`, `unpkg`, `umd:main`, `os`, `cpu`, `libc` y `typesVersions` (lista de `PUBLISH_CONFIG_WHITELIST` en pnpm). Declaralos en la raíz del `package.json`.
+- Ubicación: el patrón es relativo a la raíz, reemplaza `{version}` (obligatorio) y `{name}` (el nombre de archivo que usa `npm pack`: `@scope/pkg` pasa a `scope-pkg`), y dentro de un segmento acepta `*` y `{sha256}`. Si hay varios, toma el más reciente. La ruta solo puede tener letras, números, `.`, `-`, `_`, `@`, `+`, `~` y `/`.
+- `{sha256}`: el SHA-256 del archivo tiene que coincidir con el de su ruta. Puede repetirse en un segmento o en varios; todas las apariciones tienen que declarar el mismo digest.
+- Hash: beez-rp corre `npm pack --dry-run --json --ignore-scripts` en la raíz y compara su `integrity` (`sha512-<base64>`) con el SHA-512 del tarball. Durante ese dry run el tarball se mueve a un directorio temporal fuera del paquete y siempre vuelve a su ruta, aunque npm falle: sin una lista `files` ni una regla de `.npmignore`/`.gitignore` que excluya su carpeta, npm lo contaría como parte del paquete y la integrity nunca coincidiría. Después se publica desde su ruta original. Si difieren, el tarball no es lo que npm empaquetaría de este commit (por ejemplo, se armó con otra herramienta o antes de construir) y no se publica. Si npm falla o su salida no se puede leer, tampoco.
+
+Ejemplo de `prepare` que deja `releases/{version}-{sha256}/{name}-{version}.tgz`: `pnpm build`, `npm pack --ignore-scripts --pack-destination releases/<version>-tmp/` y renombrar la carpeta con el SHA-256 del tarball.
+
+Si no hay tarball o la verificación falla, no se publica nada y volver a correr el comando retoma preparación y publicación.
 
-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.
+## Bloquear publicaciones con pnpm
 
-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.
+`create-version` publica siempre con npm y verifica el tarball contra `npm pack --dry-run`, así que un `pnpm publish` manual saltearía esas garantías. Cada proyecto lo bloquea con:
+
+```json
+{ "scripts": { "prepublishOnly": "beez-rp guard-publish" } }
+```
+
+`beez-rp guard-publish` lee `npm_config_user_agent`: si empieza con `pnpm/`, `yarn/` o `bun/`, explica por stderr que se publica con `pnpm create-version` y sale con `1`; con `npm/`, sin la variable o con un valor desconocido sale con `0` sin imprimir nada. npm toma un `npm_config_user_agent` heredado como su config `user-agent`, por eso `create-version` lo quita del entorno de `npm publish`: así `pnpm create-version` no se bloquea a sí mismo.
+
+Es una protección contra errores, no un candado: `--ignore-scripts` la esquiva a propósito. Aun así, un tarball empaquetado con pnpm no pasa la verificación de hash de `create-version`.
+
+## Publicar beez-rp
+
+beez-rp se publica con su propio comando (`beez-rp.config.js`: `checks: ["pnpm check"]`, `publish: "npm"`). Su `prepublishOnly` es `node bin/beez-rp.js guard-publish`, porque no se instala a sí mismo:
+
+```bash
+pnpm cv
+```
 
 ## Desarrollo
 

package/bin/beez-rp.js

@@ -2,11 +2,16 @@
 /**
  * `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`.
+ * - `beez-rp guard-publish` is the `prepublishOnly` guard: it exits with `1`
+ *   and explains why when pnpm, yarn or bun publishes, and with `0` otherwise.
  *
  * @module beez-rp-cli
  */
@@ -14,16 +19,23 @@
 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";
+import { decidePublishGuardForEnvironment } from "../src/guard-publish.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] | beez-rp ${CLI_COMMAND.guardPublish}`;
 
-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.guardPublish) {
+  const decision = decidePublishGuardForEnvironment();
+  if (decision.message) {
+    console.error(decision.message);
+  }
+  process.exitCode = decision.exitCode;
+} else if (command === CLI_COMMAND.ignoreBuild) {
   try {
     const decision = decideBuildForCheckout(process.cwd());
     console.log(decision.reason);
@@ -33,4 +45,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.3.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,14 @@
       "types": "./types/testing.d.ts",
       "default": "./src/testing.js"
     },
+    "./guard-publish": {
+      "types": "./types/guard-publish.d.ts",
+      "default": "./src/guard-publish.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,9 +73,10 @@
     "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"
+    "create-version": "node bin/beez-rp.js create-version",
+    "cv": "node bin/beez-rp.js create-version",
+    "prepack": "pnpm build:types",
+    "prepublishOnly": "node bin/beez-rp.js guard-publish"
   },
   "devDependencies": {
     "@types/node": "^24.13.4",

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,6 @@
 /** Command names accepted as the first `beez-rp` argument. */
 export const CLI_COMMAND = Object.freeze({
   ignoreBuild: "ignore-build",
+  createVersion: "create-version",
+  guardPublish: "guard-publish",
 });

package/src/constants/create-version.js

@@ -0,0 +1,319 @@
+/**
+ * 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;
+
+/** Placeholders of the `artifact` pattern: the released version and the npm package name. */
+export const ARTIFACT_VERSION_PLACEHOLDER = "{version}";
+export const ARTIFACT_NAME_PLACEHOLDER = "{name}";
+
+/**
+ * Scope of a package name as `npm pack` and `pnpm pack` name the tarball: the
+ * leading `@` is dropped and the `/` becomes `-` (`@scope/pkg` → `scope-pkg`).
+ * The `scope` group keeps the scope without `@`.
+ */
+export const PACKAGE_SCOPE_PATTERN = /^@(?<scope>[^/]+)\//u;
+
+/** Replacement of {@link PACKAGE_SCOPE_PATTERN} that yields the tarball base name prefix. */
+export const PACKED_SCOPE_REPLACEMENT = "$<scope>-";
+
+/** Wildcard of an `artifact` pattern segment, such as the checksum in `releases/{version}-*`. */
+export const ARTIFACT_SEGMENT_WILDCARD = "*";
+
+/**
+ * Checksum placeholder: the SHA-256 of the archive, verified before publishing. It may repeat,
+ * in one segment or several, and every occurrence must declare the same digest.
+ */
+export const ARTIFACT_SHA256_PLACEHOLDER = "{sha256}";
+
+/** Lowercase hexadecimal SHA-256 digest matched by {@link ARTIFACT_SHA256_PLACEHOLDER}. */
+export const SHA256_HEX_PATTERN_SOURCE = "[0-9a-f]{64}";
+
+/**
+ * Characters allowed in an artifact path passed to `npm publish` through the Windows shell;
+ * `~` is allowed because npm package names (and so tarball names) may contain it.
+ */
+export const SAFE_ARTIFACT_PATH_PATTERN = /^[\w.@+~/-]+$/u;
+
+/**
+ * Prefix that makes npm read an artifact path as a local file: a bare
+ * `releases/x/pkg.tgz` operand is parsed as a package spec (a GitHub shorthand).
+ */
+export const LOCAL_PATH_PREFIX = "./";
+
+/**
+ * Arguments of the `npm pack` run that reports the integrity npm would pack from the release
+ * checkout: nothing is written and no lifecycle script runs, so it only reads what `prepare` left.
+ */
+export const NPM_PACK_DRY_RUN_ARGUMENTS = Object.freeze(["pack", "--dry-run", "--json", "--ignore-scripts"]);
+
+/**
+ * Prefix of the temporary directory, outside the package root, that holds the prepared archive
+ * while `npm pack --dry-run` runs, so npm never packs the archive into the package it describes.
+ */
+export const ARTIFACT_HOLDING_DIRECTORY_PREFIX = "beez-rp-artifact-";
+
+/** Node.js error code of a `rename` across file systems, retried as copy and delete. */
+export const CROSS_DEVICE_RENAME_ERROR_CODE = "EXDEV";
+
+/** Hash algorithm of the npm `integrity` string (`sha512-<base64>`). */
+export const NPM_INTEGRITY_ALGORITHM = "sha512";
+
+/** npm `integrity` string as `npm pack --json` reports it. */
+export const NPM_INTEGRITY_PATTERN = /^sha512-[A-Za-z0-9+/]+={0,2}$/u;
+
+/** Manifest field whose keys npm applies as configuration when it publishes. */
+export const PUBLISH_CONFIG_FIELD = "publishConfig";
+
+/**
+ * `publishConfig` keys pnpm hoists onto the packed manifest root. npm treats every
+ * `publishConfig` key as npm configuration and never rewrites manifest fields with it, so a
+ * package that declares any of these would be published differently by npm than by `pnpm pack`.
+ * Any other key (`registry`, `access`, `tag`, `provenance`, `@scope:registry`, `otp`...) is npm
+ * configuration and is accepted.
+ *
+ * Source: `PUBLISH_CONFIG_WHITELIST` in pnpm v12.6.0
+ * (`pnpm/crates/exportable-manifest/src/create.rs`; same list as
+ * `releasing/exportable-manifest/src/overridePublishConfig.ts` in pnpm 11).
+ *
+ * @see https://github.com/pnpm/pnpm/blob/v12.6.0/pnpm/crates/exportable-manifest/src/create.rs
+ * @see https://docs.npmjs.com/cli/v11/configuring-npm/package-json#publishconfig
+ */
+export const PNPM_HOISTED_PUBLISH_CONFIG_KEYS = Object.freeze([
+  "name",
+  "bin",
+  "engines",
+  "type",
+  "imports",
+  "main",
+  "module",
+  "typings",
+  "types",
+  "exports",
+  "browser",
+  "esnext",
+  "es2015",
+  "unpkg",
+  "umd:main",
+  "os",
+  "cpu",
+  "libc",
+  "typesVersions",
+]);
+
+/** Dependency maps npm publishes as they are written in `package.json`. */
+export const PUBLISHED_DEPENDENCY_FIELDS = Object.freeze(["dependencies", "peerDependencies", "optionalDependencies"]);
+
+/**
+ * Dependency specifiers only `pnpm pack` rewrites and npm publishes verbatim, which npm then
+ * cannot install (`EUNSUPPORTEDPROTOCOL`):
+ * - `catalog:` (dereferenced to the catalog entry);
+ * - `workspace:` (resolved to the linked package version), as the whole specifier or, in
+ *   `peerDependencies`, as a segment of a compound range (`^1.0.0 || workspace:>=1.0.0`);
+ * - `jsr:` (turned into an `npm:@jsr/<scope>__<name>` alias).
+ *
+ * Source: `convert_dependency_for_publish` (catalog → workspace → jsr replacers) in pnpm v12.6.0
+ * `pnpm/crates/exportable-manifest/src/create.rs`, and `replace_workspace_protocol_peer_dependency`
+ * in `pnpm/crates/exportable-manifest/src/replace.rs`. No other protocol is rewritten there.
+ *
+ * @see https://github.com/pnpm/pnpm/blob/v12.6.0/pnpm/crates/exportable-manifest/src/create.rs
+ * @see https://github.com/pnpm/pnpm/blob/v12.6.0/pnpm/crates/exportable-manifest/src/replace.rs
+ */
+export const PNPM_PACK_REWRITTEN_SPECIFIER_PATTERN = /^(?:workspace|catalog|jsr):|\|\|\s*workspace:/u;
+
+/** Public npm registry: npm's default, used when no config sets `@scope:registry` nor `registry`. */
+export const DEFAULT_NPM_REGISTRY_URL = "https://registry.npmjs.org/";
+
+/** Prefix of a package page on npmjs.com, linked in the summary of a release published to {@link DEFAULT_NPM_REGISTRY_URL}. */
+export const NPMJS_PACKAGE_PAGE_URL = "https://www.npmjs.com/package/";
+
+/** `publishConfig` key of the registry for every package, used when no scope-specific registry applies. */
+export const PUBLISH_CONFIG_REGISTRY_KEY = "registry";
+
+/** Suffix of the scope-specific `publishConfig` registry key, as in `@scope:registry`. */
+export const SCOPED_REGISTRY_KEY_SUFFIX = ":registry";
+
+/**
+ * Registry URL allowed on the `npm view` command line built for the Windows shell: only characters
+ * without shell meaning (no `%`, `&`, `|`, `^`, quotes or spaces), after URL normalization.
+ */
+export const SHELL_SAFE_REGISTRY_URL_PATTERN = /^https?:\/\/[\w.~:/@+-]+$/u;
+
+/** npm option that selects the registry `npm view` queries. */
+export const NPM_REGISTRY_OPTION = "--registry";
+
+/** npm option that replaces the user config (`~/.npmrc`) with the temporary one. */
+export const NPM_USER_CONFIG_OPTION = "--userconfig";
+
+/** npm subcommand that prints the effective value of a config key. */
+export const NPM_CONFIG_GET_ARGUMENTS = Object.freeze(["config", "get"]);
+
+/** What `npm config get` prints for a key no config source sets, such as an unused `@scope:registry`. */
+export const NPM_UNSET_CONFIG_VALUE = "undefined";
+
+/** Protocols a publish registry URL may use. */
+export const NPM_REGISTRY_PROTOCOLS = Object.freeze(["http:", "https:"]);
+
+/**
+ * Value of the registry credential in the temporary npm config: npm expands `${NPM_TOKEN}` from
+ * the environment, so the token never reaches the disk or a command line.
+ */
+export const NPM_AUTH_TOKEN_REFERENCE = `\${${NPM_TOKEN_VARIABLE}}`;
+
+/** Prefix of the temporary directory holding the publish-only npm user config. */
+export const NPM_AUTH_DIRECTORY_PREFIX = "beez-rp-npm-auth-";
+
+/** Characters that could break out of a quoted path on the Windows shell. */
+export const UNSAFE_QUOTED_PATH_PATTERN = /["%]/u;
+
+/** Placeholder replaced by the released version in `summary` lines. */
+export const SUMMARY_VERSION_PLACEHOLDER = "{version}";
+
+/**
+ * Shown when syncing `main` brought new commits: the run ends (exit code 0, it is not a failure)
+ * so the next one loads the updated configuration and diagnoses again.
+ */
+export const MAIN_SYNCED_RESTART_MESSAGE = `${MAIN_BRANCH} se actualizó desde origin: volvé a correr pnpm create-version para diagnosticar con el código y la configuración nuevos.`;
+
+/** Exit code of a release stopped by a failed step, invalid arguments or configuration. */
+export const FAILURE_EXIT_CODE = 1;

package/src/constants/guard-publish.js

@@ -0,0 +1,29 @@
+/**
+ * Contract of `beez-rp guard-publish`, the `prepublishOnly` guard that keeps
+ * Beez packages from being published by a package manager other than npm.
+ *
+ * @module constants/guard-publish
+ */
+
+/**
+ * Environment variable package managers set for lifecycle scripts, for
+ * example `pnpm/12.6.0 npm/? node/v24.21.0 win32 x64`. npm also reads it as its
+ * `user-agent` config, so an inherited value survives `npm publish`.
+ */
+export const PACKAGE_MANAGER_USER_AGENT_VARIABLE = "npm_config_user_agent";
+
+/** User agent prefix of npm, the only package manager allowed to publish. */
+export const ALLOWED_PUBLISH_USER_AGENT_PREFIX = "npm/";
+
+/** Package managers whose `publish` is blocked, keyed by their user agent prefix. */
+export const BLOCKED_PUBLISH_PACKAGE_MANAGERS = Object.freeze({
+  "pnpm/": "pnpm",
+  "yarn/": "yarn",
+  "bun/": "bun",
+});
+
+/** Exit codes of `beez-rp guard-publish`. */
+export const GUARD_PUBLISH_EXIT_CODE = Object.freeze({
+  allowed: 0,
+  blocked: 1,
+});

package/src/constants/index.js

@@ -8,5 +8,7 @@ export * from "./build-gate.js";
 export * from "./changelog.js";
 export * from "./changelog-ai.js";
 export * from "./cli.js";
+export * from "./guard-publish.js";
 export * from "./terminal-ui.js";
 export * from "./versions.js";
+export * from "./create-version.js";