beez-rp 0.2.0 → 0.3.0

package/src/create-version/run.js

@@ -27,6 +27,7 @@ import {
   FAILURE_EXIT_CODE,
   GITHUB_REPOSITORY_PATTERN,
   MAIN_BRANCH,
+  MAIN_SYNCED_RESTART_MESSAGE,
   MAX_LISTED_COMMITS,
   MAX_LISTED_ITEMS,
   MIGRATION_STATUS,
@@ -61,9 +62,17 @@ import {
   startSpinner,
 } from "../terminal-ui.js";
 import { listNextVersions, resolveRequestedVersion, suggestReleaseType, toReleaseTag } from "../versions.js";
+import {
+  expandArtifactPattern,
+  findPnpmPackRewrites,
+  findPreparedArtifact,
+  isSafeArtifactPath,
+  verifyPreparedArtifact,
+  withArtifactOutsidePackageRoot,
+} from "./artifact.js";
 import { loadCreateVersionConfig } from "./config.js";
 import { ReleaseStepError } from "./errors.js";
-import { lookupPublishedVersions, publishToNpm } from "./npm.js";
+import { buildNpmAuthConfigLine, describePublishedRelease, lookupPublishedVersions, publishToNpm, readNpmPackIntegrity, resolvePublishRegistry } from "./npm.js";
 import { RELEASE_USAGE, buildReleasePlan, parseReleaseArguments } from "./plan.js";
 import { createGitReader, listCommits, runCommandLine, runInherited } from "./process.js";
 import { collectReleaseState } from "./state.js";
@@ -83,12 +92,21 @@ import { collectReleaseState } from "./state.js";
  *   pushed: boolean,
  *   published: boolean,
  *   commitCount: number | null,
+ *   packageName: string,
+ *   registryUrl: string | null,
  * }} ReleaseContext
  */
 
 /** Raised when the user cancels on purpose; ends the run without an error box. */
 class ReleaseCancelledError extends Error {}
 
+/**
+ * Raised after syncing `main` brought new commits: the diagnosis, the plan and the configuration
+ * (with every module it imports) belong to the previous `main`, so the run ends without an error
+ * and asks to run the command again in a new process.
+ */
+class MainSyncedRestartError extends Error {}
+
 /** Answers of the pending-migrations prompt. */
 const MIGRATION_CHOICE = Object.freeze({ apply: "apply", skip: "skip", cancel: "cancel" });
 
@@ -304,6 +322,16 @@ function readWorkingUnreleased(repositoryRoot) {
   return existsSync(changelogPath) ? readUnreleased(readFileSync(changelogPath, "utf8")) : { exists: false, entryCount: 0, unknownSections: [], body: "" };
 }
 
+/**
+ * Reads the working tree `package.json`, which syncing `main` may have changed after the diagnosis.
+ *
+ * @param {string} repositoryRoot - Repository root.
+ * @returns {import("./artifact.js").PackageManifest} Current manifest.
+ */
+function readWorkingManifest(repositoryRoot) {
+  return JSON.parse(readFileSync(path.join(repositoryRoot, PACKAGE_MANIFEST_FILE), "utf8"));
+}
+
 /**
  * Returns the version being released: the one just bumped or the pending one.
  *
@@ -321,12 +349,33 @@ function requireReleaseVersion(context) {
 }
 
 /**
- * Fast-forwards local `main` to `origin/main`.
+ * Steps a configuration adds to the release plan.
+ *
+ * @param {ResolvedCreateVersionConfig} config - Resolved configuration.
+ * @returns {import("./plan.js").ReleaseCapabilities} Capabilities for `buildReleasePlan`.
+ */
+function describeReleaseCapabilities(config) {
+  return {
+    checks: config.checks.length > 0,
+    prepare: config.prepare !== null,
+    publish: config.publish !== null,
+    publishTitle: config.publish === NPM_PUBLISHER ? "Publicar en npm" : "Publicar el release",
+  };
+}
+
+/**
+ * Fast-forwards local `main` to `origin/main`. When that brings new commits the release stops
+ * before touching the version: the diagnosis, the plan and `beez-rp.config.(m)js` (imported with
+ * its modules at startup) come from the previous `main`, so the command must run again in a new
+ * process to diagnose with the new code and configuration.
  *
  * @param {ReleaseContext} context - Release context.
  * @returns {Promise<void>}
+ * @throws {ReleaseStepError} When the fast-forward fails.
+ * @throws {MainSyncedRestartError} When `main` moved and the command has to run again.
  */
 async function syncMainStep(context) {
+  const headBeforeSync = await context.reader.git(["rev-parse", "HEAD"]);
   await runGitStep(
     context,
     ["merge", "--ff-only", "--quiet", REMOTE_MAIN_REF],
@@ -334,6 +383,10 @@ async function syncMainStep(context) {
     `Revisá git status y git log ${REMOTE_MAIN_REF}..${MAIN_BRANCH}.`
   );
   print(`${ICON.success} ${MAIN_BRANCH} quedó igual a ${REMOTE_MAIN_REF}.`);
+
+  if ((await context.reader.git(["rev-parse", "HEAD"])) !== headBeforeSync) {
+    throw new MainSyncedRestartError();
+  }
 }
 
 /**
@@ -547,6 +600,128 @@ async function pushReleaseStep(context) {
   context.pushed = true;
 }
 
+/**
+ * Lists the tracked files that differ from `HEAD`. `prepare` may create untracked or ignored
+ * output (`dist/`, `releases/`), but a modified tracked file (such as `package.json`) means
+ * `npm pack --dry-run` would no longer read the release commit.
+ *
+ * @param {ReleaseContext} context - Release context.
+ * @returns {Promise<string[]>} `git status --porcelain` lines of modified tracked files.
+ * @throws {ReleaseStepError} When Git cannot report the working tree state.
+ */
+async function listTrackedChanges(context) {
+  const output = await context.reader.tryGit(["status", "--porcelain", "--untracked-files=no"]);
+
+  if (output === null) {
+    throw new ReleaseStepError("No se pudo leer el estado del working tree antes de publicar.", "No se publicó nada. Revisá git status y volvé a correr pnpm create-version.");
+  }
+
+  return output.split("\n").filter((line) => line.trim() !== "");
+}
+
+/**
+ * Finds and verifies the archive prepared for the release when the project configured `artifact`.
+ * The working tree must still be the release commit (no tracked file modified by `prepare`), the
+ * manifest must not rely on rewrites only `pnpm pack` applies, and the archive must have the same
+ * SHA-512 integrity `npm pack --dry-run --ignore-scripts` reports for that commit: `npm pack` is
+ * reproducible, so equal hashes mean the archive is byte for byte what npm packs.
+ *
+ * @param {ReleaseContext} context - Release context.
+ * @param {string} version - Version being published.
+ * @param {Record<string, unknown>} workingManifest - Working tree `package.json`, after `prepare`.
+ * @returns {Promise<string | null>} Verified archive path relative to the root, or `null` to publish the working tree.
+ */
+async function resolvePublishedArtifact(context, version, workingManifest) {
+  const { artifact } = context.config;
+
+  if (!artifact) {
+    return null;
+  }
+
+  const trackedChanges = await listTrackedChanges(context);
+
+  if (trackedChanges.length > 0) {
+    throw new ReleaseStepError(
+      `El paso de preparación modificó archivos versionados: ${trackedChanges.slice(0, MAX_LISTED_ITEMS).join("; ")}.`,
+      "No se publicó nada. prepare puede generar archivos ignorados (dist/, releases/) pero no cambiar archivos versionados como package.json: revertí esos cambios y volvé a correr pnpm create-version."
+    );
+  }
+
+  const pnpmRewrites = findPnpmPackRewrites(workingManifest);
+
+  if (pnpmRewrites.length > 0) {
+    throw new ReleaseStepError(
+      `Este paquete depende de reescrituras de pnpm al empaquetar y beez-rp publica con npm: ${pnpmRewrites.slice(0, MAX_LISTED_ITEMS).join("; ")}.`,
+      "No se publicó nada. Reemplazá los especificadores workspace:/catalog:/jsr: por rangos de versión y sacá de publishConfig los campos del manifest que solo pnpm aplica al empaquetar (exports, main, bin, types...): declaralos en la raíz de package.json."
+    );
+  }
+
+  const release = { version, packageName: String(workingManifest.name) };
+  const prepared = findPreparedArtifact(context.repositoryRoot, artifact, release);
+
+  if (!prepared) {
+    throw new ReleaseStepError(
+      `No hay un artefacto preparado de ${version} que coincida con ${expandArtifactPattern(artifact, release)}.`,
+      "Revisá la salida del paso de preparación y volvé a correr pnpm create-version: retoma la preparación y la publicación."
+    );
+  }
+
+  if (!isSafeArtifactPath(prepared.path)) {
+    throw new ReleaseStepError(`La ruta del artefacto ${prepared.path} tiene caracteres no permitidos.`, "Usá rutas con letras, números, ., -, _, @, +, ~ y /.");
+  }
+
+  // Without a `files` allowlist or an ignore rule, npm would pack the archive into the package it
+  // describes; it is moved out of the root during the dry run and published later from its path.
+  const npmPack = await withArtifactOutsidePackageRoot(context.repositoryRoot, prepared.path, () => readNpmPackIntegrity(context.repositoryRoot));
+
+  if (!npmPack.pack) {
+    throw new ReleaseStepError(
+      `No se pudo verificar ${prepared.path}: ${npmPack.problem}.`,
+      "No se publicó nada. Corré npm pack --dry-run --json --ignore-scripts en la raíz para ver el error y volvé a correr pnpm create-version."
+    );
+  }
+
+  if (npmPack.pack.version !== version) {
+    throw new ReleaseStepError(
+      `npm pack --dry-run describe ${npmPack.pack.name}@${npmPack.pack.version} y se está publicando ${version}.`,
+      "No se publicó nada. Revisá que HEAD sea el commit de release y volvé a correr pnpm create-version."
+    );
+  }
+
+  const problems = verifyPreparedArtifact(context.repositoryRoot, prepared, npmPack.pack.integrity);
+
+  if (problems.length > 0) {
+    throw new ReleaseStepError(
+      `El artefacto ${prepared.path} no se puede publicar: ${problems.join("; ")}.`,
+      "No se publicó nada. Hacé que prepare empaquete con npm pack --ignore-scripts después de construir, borrá ese tarball y volvé a correr pnpm create-version."
+    );
+  }
+
+  print(`${ICON.success} ${prepared.path} verificado${prepared.expectedSha256 ? " (SHA-256 de la ruta e integrity de npm pack)" : " (integrity de npm pack)"}.`);
+  return prepared.path;
+}
+
+/**
+ * Resolves the registry the release is published to: `publishConfig["@scope:registry"]` for a
+ * scoped package, else `publishConfig.registry`, else the registry npm's config resolves in the
+ * repository (project `.npmrc`, environment, global config).
+ *
+ * @param {Record<string, unknown>} manifest - Working tree `package.json`.
+ * @param {string} repositoryRoot - Repository root.
+ * @returns {Promise<string>} Registry URL, already checked to be a plain http(s) URL.
+ * @throws {ReleaseStepError} When the registry is not a valid http(s) URL or npm cannot report it.
+ */
+async function resolveReleaseRegistry(manifest, repositoryRoot) {
+  try {
+    return await resolvePublishRegistry(manifest, repositoryRoot);
+  } catch (error) {
+    throw new ReleaseStepError(
+      `No se puede publicar: ${error instanceof Error ? error.message : String(error)}.`,
+      "No se publicó nada. Corregí el registry (publishConfig.registry o publishConfig[\"@scope:registry\"] en package.json, o registry/@scope:registry en .npmrc) con una URL http(s) sin credenciales y volvé a correr pnpm create-version."
+    );
+  }
+}
+
 /**
  * Publishes the release with npm or the project hook.
  *
@@ -558,7 +733,18 @@ async function publishReleaseStep(context) {
   const { publish } = context.config;
 
   if (publish === NPM_PUBLISHER) {
-    const result = await publishToNpm(context.repositoryRoot);
+    // Syncing main may have renamed the package after the diagnosis: publish under the current name.
+    const manifest = readWorkingManifest(context.repositoryRoot);
+    const packageName = String(manifest.name);
+    context.packageName = packageName;
+    const registryUrl = await resolveReleaseRegistry(manifest, context.repositoryRoot);
+    context.registryUrl = registryUrl;
+    const authConfigLine = buildNpmAuthConfigLine(registryUrl);
+    const artifactPath = await resolvePublishedArtifact(context, version, manifest);
+    if (artifactPath) {
+      print(paint("gray", `Publicando ${artifactPath}; npm puede pedir la confirmación 2FA en el navegador o un código.`));
+    }
+    const result = await publishToNpm(context.repositoryRoot, { authConfigLine, artifactPath });
 
     if (result.missingToken) {
       throw new ReleaseStepError(
@@ -574,7 +760,8 @@ async function publishReleaseStep(context) {
       );
     }
 
-    const npm = await lookupPublishedVersions(context.state.packageName, context.repositoryRoot);
+    // npm view ignores publishConfig, so the registry the release went to is queried explicitly.
+    const npm = await lookupPublishedVersions(packageName, context.repositoryRoot, registryUrl);
     if (!npm.publishedVersions.includes(version)) {
       print(`${ICON.warning} ${paint("yellow", `npm todavía no muestra ${version}; puede tardar unos segundos en propagarse.`)}`);
     }
@@ -623,8 +810,8 @@ function renderReleaseSummary(context, remoteUrl, startedAt) {
     lines.push(`${ICON.success} ${paint("bold", "Git")}       ${MAIN_BRANCH} + ${tag} en ${RELEASE_REMOTE}`);
   }
 
-  if (context.published && context.config.registry === RELEASE_REGISTRY.npm) {
-    lines.push(`${ICON.success} ${paint("bold", "npm")}       https://www.npmjs.com/package/${context.state.packageName}/v/${version}`);
+  if (context.published && context.registryUrl) {
+    lines.push(`${ICON.success} ${paint("bold", "npm")}       ${describePublishedRelease({ registryUrl: context.registryUrl, packageName: context.packageName, version })}`);
   }
 
   const githubRepository = GITHUB_REPOSITORY_PATTERN.exec(remoteUrl)?.[1];
@@ -701,12 +888,7 @@ export async function runCreateVersion({ repositoryRoot, argv }) {
   print(renderBanner({ projectName: config.projectName ?? state.packageName, publishedLabel }));
   print(renderDiagnosis(state, repositoryRoot));
 
-  const plan = buildReleasePlan(state, {
-    checks: config.checks.length > 0,
-    prepare: config.prepare !== null,
-    publish: config.publish !== null,
-    publishTitle: config.publish === NPM_PUBLISHER ? "Publicar en npm" : "Publicar el release",
-  });
+  const plan = buildReleasePlan(state, describeReleaseCapabilities(config));
 
   if (plan.mode === RELEASE_MODE.upToDate) {
     const since = state.lastRelease?.version ? toReleaseTag(state.lastRelease.version) : "el inicio";
@@ -742,7 +924,7 @@ export async function runCreateVersion({ repositoryRoot, argv }) {
   }
 
   /** @type {ReleaseContext} */
-  const context = { repositoryRoot, config, state, options, reader, version: plan.pendingVersion, pushed: false, published: false, commitCount: null };
+  const context = { repositoryRoot, config, state, options, reader, version: plan.pendingVersion, pushed: false, published: false, commitCount: null, packageName: state.packageName, registryUrl: null };
 
   for (const [index, planStep] of plan.steps.entries()) {
     print(renderStepHeader(index + 1, plan.steps.length, planStep.title));
@@ -754,6 +936,18 @@ export async function runCreateVersion({ repositoryRoot, argv }) {
         return 0;
       }
 
+      // Not a failure: the run ends on purpose so the next one diagnoses the updated main.
+      if (error instanceof MainSyncedRestartError) {
+        print(
+          renderBox({
+            title: `${MAIN_BRANCH} actualizado`,
+            lines: [`${ICON.info} ${MAIN_SYNCED_RESTART_MESSAGE}`, "", paint("gray", "No se tocó la versión ni los tags.")],
+            tone: BOX_TONE.info,
+          })
+        );
+        return 0;
+      }
+
       const lines = [`${ICON.failure} ${error instanceof Error ? error.message : String(error)}`];
       if (error instanceof ReleaseStepError) {
         lines.push("", `${paint("bold", "Qué hacer:")} ${error.hint}`);

package/src/create-version/state.js

@@ -18,6 +18,7 @@ import { CHANGELOG_FILE } from "../constants/changelog.js";
 import {
   MAIN_BRANCH,
   MIGRATION_STATUS,
+  NPM_LOOKUP_STATUS,
   NO_PULL_REQUEST_MESSAGE_PATTERN,
   PACKAGE_MANIFEST_FILE,
   PULL_REQUEST_JSON_FIELDS,
@@ -25,7 +26,7 @@ import {
   REMOTE_MAIN_REF,
   VERSION_FIELD_CHANGE_PATTERN,
 } from "../constants/create-version.js";
-import { lookupPublishedVersions } from "./npm.js";
+import { lookupPublishedVersions, resolvePublishRegistry } from "./npm.js";
 import { createGitReader, listCommits, readPackageVersionAt, runCaptured } from "./process.js";
 
 /**
@@ -132,6 +133,28 @@ async function readMigrations(checkMigrations) {
   }
 }
 
+/**
+ * Lists the published versions on the registry the working-tree manifest publishes to, so the
+ * diagnosis sees the same versions `npm publish` would conflict with.
+ *
+ * @param {typeof lookupPublishedVersions} lookupNpm - npm lookup adapter.
+ * @param {Record<string, unknown>} manifest - Working-tree `package.json`.
+ * @param {string} repositoryRoot - Repository root.
+ * @returns {Promise<import("./npm.js").NpmLookup>} Published versions, or a failed lookup when the registry is invalid
+ *   or npm cannot report it.
+ */
+async function lookupNpmOnPublishRegistry(lookupNpm, manifest, repositoryRoot) {
+  /** @type {string} */
+  let registryUrl;
+  try {
+    registryUrl = await resolvePublishRegistry(manifest, repositoryRoot);
+  } catch (error) {
+    return { status: NPM_LOOKUP_STATUS.failed, publishedVersions: [], reason: error instanceof Error ? error.message : String(error) };
+  }
+
+  return lookupNpm(String(manifest.name), repositoryRoot, registryUrl);
+}
+
 /**
  * Gathers the complete release snapshot.
  *
@@ -188,7 +211,7 @@ export async function collectReleaseState({
 
   if (trackNpm) {
     onProgress("Consultando npm");
-    npm = await lookupNpm(manifest.name, repositoryRoot);
+    npm = await lookupNpmOnPublishRegistry(lookupNpm, manifest, repositoryRoot);
   }
 
   if (checkMigrations) {

package/src/guard-publish.js

@@ -0,0 +1,74 @@
+/**
+ * `prepublishOnly` guard of the Beez packages: they are published with npm by
+ * `pnpm create-version`, which verifies the tarball against
+ * `npm pack --dry-run`, so a `pnpm publish` (or yarn/bun) is blocked.
+ *
+ * The guard only blocks package managers it recognizes. Without a user agent,
+ * or with an unknown one, the publisher cannot be determined and it allows the
+ * publication. It can be bypassed on purpose with `--ignore-scripts`.
+ *
+ * @module guard-publish
+ */
+
+import {
+  ALLOWED_PUBLISH_USER_AGENT_PREFIX,
+  BLOCKED_PUBLISH_PACKAGE_MANAGERS,
+  GUARD_PUBLISH_EXIT_CODE,
+  PACKAGE_MANAGER_USER_AGENT_VARIABLE,
+} from "./constants/guard-publish.js";
+
+/**
+ * @typedef {{ allowed: boolean, packageManager: string | null, message: string | null, exitCode: number }} PublishGuardDecision
+ */
+
+/**
+ * Finds the blocked package manager that runs the publication.
+ *
+ * @param {string | undefined} userAgent - Value of `npm_config_user_agent`.
+ * @returns {string | null} Blocked package manager name, or `null` for npm, unknown or missing user agents.
+ */
+export function findBlockedPublishPackageManager(userAgent) {
+  if (!userAgent || userAgent.startsWith(ALLOWED_PUBLISH_USER_AGENT_PREFIX)) {
+    return null;
+  }
+
+  const blockedEntry = Object.entries(BLOCKED_PUBLISH_PACKAGE_MANAGERS).find(([userAgentPrefix]) => userAgent.startsWith(userAgentPrefix));
+  return blockedEntry ? blockedEntry[1] : null;
+}
+
+/**
+ * Builds the explanation printed when a publication is blocked.
+ *
+ * @param {string} packageManager - Blocked package manager name.
+ * @returns {string} Message in Spanish with what to run instead.
+ */
+export function buildBlockedPublishMessage(packageManager) {
+  return (
+    `beez-rp guard-publish: no publiques con ${packageManager}. Los paquetes Beez se publican con \`pnpm create-version\`, ` +
+    "que publica con npm y verifica el tarball contra `npm pack --dry-run`."
+  );
+}
+
+/**
+ * Decides whether the publication may continue.
+ *
+ * @param {string | undefined} userAgent - Value of `npm_config_user_agent`.
+ * @returns {PublishGuardDecision} Decision, message to print on stderr and exit code.
+ */
+export function decidePublishGuard(userAgent) {
+  const packageManager = findBlockedPublishPackageManager(userAgent);
+
+  return packageManager === null
+    ? { allowed: true, packageManager: null, message: null, exitCode: GUARD_PUBLISH_EXIT_CODE.allowed }
+    : { allowed: false, packageManager, message: buildBlockedPublishMessage(packageManager), exitCode: GUARD_PUBLISH_EXIT_CODE.blocked };
+}
+
+/**
+ * Decides with the user agent of an environment (the current process by default).
+ *
+ * @param {NodeJS.ProcessEnv} [environment] - Environment of the lifecycle script.
+ * @returns {PublishGuardDecision} Decision for its `npm_config_user_agent`.
+ */
+export function decidePublishGuardForEnvironment(environment = process.env) {
+  return decidePublishGuard(environment[PACKAGE_MANAGER_USER_AGENT_VARIABLE]);
+}

package/src/index.js

@@ -4,6 +4,7 @@
  * - `beez-rp/versions`: stable `X.Y.Z` rules; only the next patch, minor or major is allowed.
  * - `beez-rp/build-gate`: Vercel `ignoreCommand` decision built on those rules.
  * - `beez-rp/changelog` and `beez-rp/changelog-ai`: Keep a Changelog release and Codex fill-in.
+ * - `beez-rp/guard-publish`: `prepublishOnly` guard that blocks pnpm, yarn and bun publications.
  * - `beez-rp/terminal-ui`: boxes, spinners and prompts for release commands.
  * - `beez-rp/testing`: shared version bump fixtures for consumer test suites.
  * - `beez-rp/constants`: every constant above, grouped by domain.
@@ -14,6 +15,7 @@
 export * from "./build-gate.js";
 export * from "./changelog.js";
 export * from "./changelog-ai.js";
+export * from "./guard-publish.js";
 export * from "./versions.js";
 export {
   ICON,

package/types/constants/cli.d.ts

@@ -7,4 +7,5 @@
 export declare const CLI_COMMAND: Readonly<{
     ignoreBuild: "ignore-build";
     createVersion: "create-version";
+    guardPublish: "guard-publish";
 }>;

package/types/constants/create-version.d.ts

@@ -109,7 +109,125 @@ export declare const MAX_LISTED_COMMITS = 12;
 export declare const MAX_LISTED_ITEMS = 5;
 /** Length of the abbreviated commit ids shown to the user. */
 export declare const SHORT_SHA_LENGTH = 7;
+/** Placeholders of the `artifact` pattern: the released version and the npm package name. */
+export declare const ARTIFACT_VERSION_PLACEHOLDER = "{version}";
+export declare 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 declare const PACKAGE_SCOPE_PATTERN: RegExp;
+/** Replacement of {@link PACKAGE_SCOPE_PATTERN} that yields the tarball base name prefix. */
+export declare const PACKED_SCOPE_REPLACEMENT = "$<scope>-";
+/** Wildcard of an `artifact` pattern segment, such as the checksum in `releases/{version}-*`. */
+export declare 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 declare const ARTIFACT_SHA256_PLACEHOLDER = "{sha256}";
+/** Lowercase hexadecimal SHA-256 digest matched by {@link ARTIFACT_SHA256_PLACEHOLDER}. */
+export declare 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 declare const SAFE_ARTIFACT_PATH_PATTERN: RegExp;
+/**
+ * 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 declare 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 declare const NPM_PACK_DRY_RUN_ARGUMENTS: readonly string[];
+/**
+ * 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 declare const ARTIFACT_HOLDING_DIRECTORY_PREFIX = "beez-rp-artifact-";
+/** Node.js error code of a `rename` across file systems, retried as copy and delete. */
+export declare const CROSS_DEVICE_RENAME_ERROR_CODE = "EXDEV";
+/** Hash algorithm of the npm `integrity` string (`sha512-<base64>`). */
+export declare const NPM_INTEGRITY_ALGORITHM = "sha512";
+/** npm `integrity` string as `npm pack --json` reports it. */
+export declare const NPM_INTEGRITY_PATTERN: RegExp;
+/** Manifest field whose keys npm applies as configuration when it publishes. */
+export declare 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 declare const PNPM_HOISTED_PUBLISH_CONFIG_KEYS: readonly string[];
+/** Dependency maps npm publishes as they are written in `package.json`. */
+export declare const PUBLISHED_DEPENDENCY_FIELDS: readonly string[];
+/**
+ * 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 declare const PNPM_PACK_REWRITTEN_SPECIFIER_PATTERN: RegExp;
+/** Public npm registry: npm's default, used when no config sets `@scope:registry` nor `registry`. */
+export declare 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 declare 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 declare const PUBLISH_CONFIG_REGISTRY_KEY = "registry";
+/** Suffix of the scope-specific `publishConfig` registry key, as in `@scope:registry`. */
+export declare 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 declare const SHELL_SAFE_REGISTRY_URL_PATTERN: RegExp;
+/** npm option that selects the registry `npm view` queries. */
+export declare const NPM_REGISTRY_OPTION = "--registry";
+/** npm option that replaces the user config (`~/.npmrc`) with the temporary one. */
+export declare const NPM_USER_CONFIG_OPTION = "--userconfig";
+/** npm subcommand that prints the effective value of a config key. */
+export declare const NPM_CONFIG_GET_ARGUMENTS: readonly string[];
+/** What `npm config get` prints for a key no config source sets, such as an unused `@scope:registry`. */
+export declare const NPM_UNSET_CONFIG_VALUE = "undefined";
+/** Protocols a publish registry URL may use. */
+export declare const NPM_REGISTRY_PROTOCOLS: readonly string[];
+/**
+ * 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 declare const NPM_AUTH_TOKEN_REFERENCE = "${NPM_TOKEN}";
+/** Prefix of the temporary directory holding the publish-only npm user config. */
+export declare const NPM_AUTH_DIRECTORY_PREFIX = "beez-rp-npm-auth-";
+/** Characters that could break out of a quoted path on the Windows shell. */
+export declare const UNSAFE_QUOTED_PATH_PATTERN: RegExp;
 /** Placeholder replaced by the released version in `summary` lines. */
 export declare 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 declare const MAIN_SYNCED_RESTART_MESSAGE = "main se actualiz\u00F3 desde origin: volv\u00E9 a correr pnpm create-version para diagnosticar con el c\u00F3digo y la configuraci\u00F3n nuevos.";
 /** Exit code of a release stopped by a failed step, invalid arguments or configuration. */
 export declare const FAILURE_EXIT_CODE = 1;

package/types/constants/guard-publish.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 declare const PACKAGE_MANAGER_USER_AGENT_VARIABLE = "npm_config_user_agent";
+/** User agent prefix of npm, the only package manager allowed to publish. */
+export declare const ALLOWED_PUBLISH_USER_AGENT_PREFIX = "npm/";
+/** Package managers whose `publish` is blocked, keyed by their user agent prefix. */
+export declare const BLOCKED_PUBLISH_PACKAGE_MANAGERS: Readonly<{
+    "pnpm/": "pnpm";
+    "yarn/": "yarn";
+    "bun/": "bun";
+}>;
+/** Exit codes of `beez-rp guard-publish`. */
+export declare const GUARD_PUBLISH_EXIT_CODE: Readonly<{
+    allowed: 0;
+    blocked: 1;
+}>;

package/types/constants/index.d.ts

@@ -7,6 +7,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";