@astra-kit/rp 0.0.0-stage → 0.10.0

package/src/constants/create-version.js

@@ -0,0 +1,523 @@
+/**
+ * Git, npm, configuration and display values of the shared `astra-rp create-version` command.
+ *
+ * @module constants/create-version
+ */
+
+import { GITHUB_REGISTRY_PROVIDER, GITLAB_REGISTRY_PROVIDER, JSR_REGISTRY_PROVIDER, NPM_REGISTRY_PROVIDER, NPM_REGISTRY_TOKEN_VARIABLE } from "./registry.js";
+
+import { DEFAULT_CREATE_VERSION_COMMAND } from "./package-manager.js";
+import { COMMIT_SHORT_SHA_LENGTH } from "./changelog.js";
+
+/** 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 = "astra-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(["astra-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";
+
+/** Environment variable that holds the npm token; the temporary npm config references it as `${NPM_TOKEN}`. */
+export const NPM_TOKEN_VARIABLE = NPM_REGISTRY_TOKEN_VARIABLE;
+
+/**
+ * Path segments, relative to the user home directory (`os.homedir()`), of the environment file
+ * shared by every project: one `NPM_TOKEN` for all the repositories that release with astra-rp.
+ */
+export const SHARED_ENVIRONMENT_FILE_SEGMENTS = Object.freeze([".config", "astra-rp", LOCAL_ENVIRONMENT_FILE]);
+
+/** How the shared environment file is shown to the user, independent of the platform. */
+export const SHARED_ENVIRONMENT_FILE_LABEL = `~/${SHARED_ENVIRONMENT_FILE_SEGMENTS.join("/")}`;
+
+/** Where `NPM_TOKEN` was found, in lookup order: environment, repository `.env`, shared file. */
+export const NPM_TOKEN_SOURCE = Object.freeze({
+  environment: "environment",
+  repository: "repository",
+  shared: "shared",
+});
+
+/** How each {@link NPM_TOKEN_SOURCE} is named in the diagnosis and the error messages; never the token. */
+export const NPM_TOKEN_SOURCE_LABEL = Object.freeze({
+  [NPM_TOKEN_SOURCE.environment]: "variable de entorno",
+  [NPM_TOKEN_SOURCE.repository]: `${LOCAL_ENVIRONMENT_FILE} del repo`,
+  [NPM_TOKEN_SOURCE.shared]: SHARED_ENVIRONMENT_FILE_LABEL,
+});
+
+/**
+ * Result of checking the npm credentials before publishing:
+ * - `ok`: the token authenticates and its user owns the package (or it was never published); npm
+ *   cannot tell beforehand whether the token itself can write (read-only or granular tokens);
+ * - `missingToken`: no source defines `NPM_TOKEN`;
+ * - `invalidToken`: the registry rejects the token (`npm whoami` answers 401/403);
+ * - `notOwner`: the token authenticates as a user that is not an owner of the package;
+ * - `projectCredentials`: the project `.npmrc` defines credentials for the publish registry, which
+ *   npm prefers over the temporary config that binds `NPM_TOKEN`;
+ * - `unknown`: the check could not finish (network, a registry without `npm owner ls`, an
+ *   organization package whose access may come from a team); it warns but does not block.
+ */
+export const NPM_AUTH_STATUS = Object.freeze({
+  ok: "ok",
+  missingToken: "missing-token",
+  invalidToken: "invalid-token",
+  notOwner: "not-owner",
+  projectCredentials: "project-credentials",
+  unsupportedAuth: "unsupported-auth",
+  unknown: "unknown",
+});
+
+/** npm error codes of a rejected credential: `npm whoami` fails with them for an invalid or expired token. */
+export const NPM_REJECTED_CREDENTIAL_PATTERN = /\bE40[13]\b/u;
+
+/** Where `NPM_TOKEN` can be defined, in lookup order, as the credential messages explain it. */
+export const NPM_TOKEN_LOCATIONS = `la variable de entorno ${NPM_TOKEN_VARIABLE}, el ${LOCAL_ENVIRONMENT_FILE} del repo (ignorado por Git) o ${SHARED_ENVIRONMENT_FILE_LABEL} (un solo token para todos tus proyectos)`;
+
+/** Why npm answers 404 to a publication the token cannot make. */
+export const NPM_PUT_NOT_FOUND_NOTE = "Un 404 Not Found de npm en el PUT suele significar falta de permisos sobre el paquete (npm responde 404 en vez de 403).";
+
+/** Diagnosis note of an owner token: npm exposes no side-effect-free way to check its write permission. */
+export const NPM_WRITE_ACCESS_UNVERIFIED_NOTE = "permiso de escritura del token no verificable antes de publicar";
+
+/** Why a failed publication can still be the token when its user owns the package. */
+export const NPM_READ_ONLY_TOKEN_NOTE =
+  "El token puede ser read-only o granular sin permiso de escritura sobre el paquete (npm no permite verificarlo antes de publicar): revisalo en npm → Access Tokens.";
+
+/**
+ * Next action after fixing the npm credentials reported by the diagnosis.
+ *
+ * @param {string} createVersionCommand - How the project runs create-version (`pnpm create-version`, `bun run create-version`…).
+ * @returns {string} Spanish next action.
+ */
+export const buildNpmAuthRerunAction = (createVersionCommand) => `volvé a correr ${createVersionCommand}`;
+
+/**
+ * Next action after fixing the npm credentials once `npm publish` failed.
+ *
+ * @param {string} createVersionCommand - How the project runs create-version.
+ * @returns {string} Spanish next action.
+ */
+export const buildNpmPublishRetryAction = (createVersionCommand) => `corré ${createVersionCommand} para reintentar solo la publicación`;
+
+/** {@link buildNpmAuthRerunAction} of a pnpm project. */
+export const NPM_AUTH_RERUN_ACTION = buildNpmAuthRerunAction(DEFAULT_CREATE_VERSION_COMMAND);
+
+/** {@link buildNpmPublishRetryAction} of a pnpm project. */
+export const NPM_PUBLISH_RETRY_ACTION = buildNpmPublishRetryAction(DEFAULT_CREATE_VERSION_COMMAND);
+
+/**
+ * Option that keeps the plain text output of `npm whoami` and `npm owner ls` even when the project
+ * config or the environment enables npm's global JSON output (`json=true`, `npm_config_json=true`).
+ */
+export const NPM_PLAIN_OUTPUT_OPTION = "--json=false";
+
+/** Arguments of the npm command that prints the user a token authenticates as. */
+export const NPM_WHOAMI_ARGUMENTS = Object.freeze(["whoami", NPM_PLAIN_OUTPUT_OPTION]);
+
+/** Arguments of the npm command that lists the owners of a package, followed by the package name. */
+export const NPM_OWNER_LIST_ARGUMENTS = Object.freeze(["owner", "ls", NPM_PLAIN_OUTPUT_OPTION]);
+
+/** Project npm config, read from the repository root; npm prefers it over the temporary `--userconfig`. */
+export const PROJECT_NPM_CONFIG_FILE = ".npmrc";
+
+/**
+ * npm config fields that select the HTTP credential of a registry, either bound to it
+ * (`//host/path/:_authToken`) or unbound (`_authToken`); any of them in the project `.npmrc` or in an
+ * inherited `npm_config_*` variable overrides `NPM_TOKEN`. TLS client options such as `keyfile` or
+ * `certfile` are not listed: they do not replace the token.
+ */
+export const NPM_CREDENTIAL_CONFIG_FIELDS = Object.freeze(["_authToken", "_auth", "_password", "username"]);
+
+/** Prefix of the environment variables npm reads as config, in any casing (`npm_config_`, `NPM_CONFIG_`). */
+export const NPM_CONFIG_ENVIRONMENT_PREFIX = "npm_config_";
+
+/** Prefix of an npm config key bound to a registry: `//host[:port]/path/:field`. */
+export const NPM_REGISTRY_BOUND_KEY_PREFIX = "//";
+
+/** One line of `npm owner ls`: `<user> <<email>>`; the `user` group keeps the npm user name. */
+export const NPM_OWNER_LINE_PATTERN = /^(?<user>[^\s<]+)(?:\s+<[^>]*>)?$/u;
+
+/** 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",
+  verifyChangelog: "verify-changelog",
+  runChecks: "run-checks",
+  bumpVersion: "bump-version",
+  prepareRelease: "prepare-release",
+  pushRelease: "push-release",
+  pushReleaseTag: "push-release-tag",
+  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_REGISTRY_PROVIDER,
+  github: GITHUB_REGISTRY_PROVIDER,
+  gitlab: GITLAB_REGISTRY_PROVIDER,
+  jsr: JSR_REGISTRY_PROVIDER,
+});
+
+/** `package.json` script run as the release checks when the configuration does not set `checks`. */
+export const DEFAULT_CHECKS_SCRIPT = "ci";
+
+/** Command line of the default release checks in a pnpm project (other package managers run `<pm> run ci`). */
+export const DEFAULT_CHECKS_COMMAND = `pnpm run ${DEFAULT_CHECKS_SCRIPT}`;
+
+/** Built-in publisher selected with `publish: "npm"`. */
+export const NPM_PUBLISHER = NPM_REGISTRY_PROVIDER;
+
+/** 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";
+
+/** npm dist-tag every stable release is published under. */
+export const NPM_DIST_TAG = "latest";
+
+
+/** Command-line flags of `astra-rp create-version`. */
+export const CREATE_VERSION_FLAG = Object.freeze({
+  bump: "bump",
+  patch: "patch",
+  minor: "minor",
+  major: "major",
+  setVersion: "set-version",
+  dryRun: "dry-run",
+  skipUnpublished: "skip-unpublished",
+  ignoreLocalChanges: "ignore-local-changes",
+  acceptSuggested: "accept-suggested",
+  local: "local",
+  ci: "ci",
+  setupCi: "setup-ci",
+  ciRelease: "ci-release",
+  retryCi: "retry-ci",
+  help: "help",
+  /** Short flag of `--help`; public alias of the `h` entry of `CREATE_VERSION_SHORT_FLAG`. */
+  helpShort: "h",
+  endOfOptions: "--",
+});
+
+/**
+ * Short name of each release type: `--bump`/`-b` accepts it as a value (`-b m`) and it is also the
+ * short flag of the `--patch`, `--minor` and `--major` shortcuts. Case-sensitive: `m` is minor and
+ * `M` major.
+ */
+export const RELEASE_TYPE_SHORT_NAME = Object.freeze({
+  patch: "p",
+  minor: "m",
+  major: "M",
+});
+
+/**
+ * Long flag of each short flag of `astra-rp create-version`. Short flags are whole tokens (`-sv` has
+ * two letters), so they are never grouped: `-lm` is rejected instead of read as `-l -m`. A value may
+ * follow as the next token or after `=` (`-b m`, `-b=m`, `-sv 1.3.0`, `-sv=1.3.0`).
+ */
+export const CREATE_VERSION_SHORT_FLAG = Object.freeze({
+  b: CREATE_VERSION_FLAG.bump,
+  sv: CREATE_VERSION_FLAG.setVersion,
+  [RELEASE_TYPE_SHORT_NAME.patch]: CREATE_VERSION_FLAG.patch,
+  [RELEASE_TYPE_SHORT_NAME.minor]: CREATE_VERSION_FLAG.minor,
+  [RELEASE_TYPE_SHORT_NAME.major]: CREATE_VERSION_FLAG.major,
+  l: CREATE_VERSION_FLAG.local,
+  [CREATE_VERSION_FLAG.helpShort]: CREATE_VERSION_FLAG.help,
+});
+
+/** Single-dash token of a short flag, with an optional `=value`: `-l`, `-sv=1.3.0`; not `--local`. */
+export const SHORT_FLAG_TOKEN_PATTERN = /^-(?<name>[^-=][^=]*)(?:=(?<value>.*))?$/su;
+
+/** Message of the `git stash` entry holding the changes `--ignore-local-changes` sets aside. */
+export const LOCAL_CHANGES_STASH_MESSAGE = "astra-rp create-version: cambios locales apartados durante el release";
+
+/** 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 = `"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;
+
+/** Separator between the original and the new path of a renamed or copied `git status --porcelain` entry. */
+export const PORCELAIN_RENAME_SEPARATOR = " -> ";
+
+/**
+ * Extensions of the files `--ignore-local-changes` refuses to set aside: the configuration is
+ * loaded before the changes are set aside, and it (or a hook) may import code or data from them,
+ * so the release would run with content that is not the committed one.
+ */
+export const UNSETTABLE_ASIDE_EXTENSIONS = Object.freeze([".js", ".mjs", ".cjs", ".ts", ".json"]);
+
+/** 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: the same as in changelog entries. */
+export const SHORT_SHA_LENGTH = COMMIT_SHORT_SHA_LENGTH;
+
+/** 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 = "astra-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 = "astra-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.
+ *
+ * @param {string} createVersionCommand - How the project runs create-version.
+ * @returns {string} Spanish message.
+ */
+export const buildMainSyncedRestartMessage = (createVersionCommand) =>
+  `${MAIN_BRANCH} se actualizó desde origin: volvé a correr ${createVersionCommand} para diagnosticar con el código y la configuración nuevos.`;
+
+/** {@link buildMainSyncedRestartMessage} of a pnpm project. */
+export const MAIN_SYNCED_RESTART_MESSAGE = buildMainSyncedRestartMessage(DEFAULT_CREATE_VERSION_COMMAND);
+
+/** Exit code of a release stopped by a failed step, invalid arguments or configuration. */
+export const FAILURE_EXIT_CODE = 1;
+
+/** What each release type means when a project does not describe it. */
+export 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.",
+});
+
+/**
+ * Default descriptions while `preMajorShift` applies to a `0.x` version: each release type carries
+ * the changes of the level above (a patch ships features, a minor breaking changes) and a major
+ * leaves `0.x`.
+ */
+export const PRE_MAJOR_SHIFTED_RELEASE_TYPE_DESCRIPTIONS = Object.freeze({
+  patch: "Arreglos o funcionalidades nuevas compatibles; lo existente sigue funcionando igual.",
+  minor: "Cambio incompatible: quien lo usa tiene que adaptarse.",
+  major: "Sale de 0.x: primera versión estable 1.0.0.",
+});

package/src/constants/guard-publish.js

@@ -0,0 +1,29 @@
+/**
+ * Contract of `astra-rp guard-publish`, the `prepublishOnly` guard that keeps
+ * 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 `astra-rp guard-publish`. */
+export const GUARD_PUBLISH_EXIT_CODE = Object.freeze({
+  allowed: 0,
+  blocked: 1,
+});

package/src/constants/index.js

@@ -0,0 +1,18 @@
+/**
+ * Facade of every `astra-rp` constant, grouped by domain.
+ *
+ * @module constants
+ */
+
+export * from "./build-gate.js";
+export * from "./changelog.js";
+export * from "./cli.js";
+export * from "./guard-publish.js";
+export * from "./package-manager.js";
+export * from "./version-files.js";
+export * from "./monorepo.js";
+export * from "./terminal-ui.js";
+export * from "./versions.js";
+export * from "./create-version.js";
+export * from "./registry.js";
+export * from "./ci-release.js";

package/src/constants/monorepo.js

@@ -0,0 +1,57 @@
+/**
+ * Monorepo mode of `astra-rp create-version`: workspace discovery, per-package
+ * tags and the subject of the single release commit.
+ *
+ * @module constants/monorepo
+ */
+
+/** `packages` value that releases the workspaces the root `package.json` declares. */
+export const WORKSPACES_PACKAGES = "workspaces";
+
+/** Placeholders of `tagFormat`. `{version}` is required. */
+export const TAG_FORMAT_PLACEHOLDER = Object.freeze({
+  version: "{version}",
+  /** Last directory segment of the package (`packages/widget` → `widget`). */
+  component: "{component}",
+  /** npm name of the package (`@scope/widget`). */
+  name: "{name}",
+});
+
+/** Tag of each package in monorepo mode: `widget-v1.2.0` (the release-please component tag). */
+export const DEFAULT_MONOREPO_TAG_FORMAT = `${TAG_FORMAT_PLACEHOLDER.component}-v${TAG_FORMAT_PLACEHOLDER.version}`;
+
+/**
+ * Placeholder of `summary` replaced by the name of each released package in monorepo mode (next
+ * to `{version}`, its version): a line with either one is printed once per released package.
+ */
+export const SUMMARY_PACKAGE_PLACEHOLDER = "{name}";
+
+/** Prefix of the release commit subject: `release: @scope/a@1.2.0, @scope/b@0.3.1`. */
+export const MONOREPO_RELEASE_SUBJECT_PREFIX = "release: ";
+
+/** Separator of the released packages in the release commit subject. */
+export const MONOREPO_RELEASE_ENTRY_SEPARATOR = ", ";
+
+/** One `name@X.Y.Z` entry of the release commit subject; the name may be scoped. */
+export const MONOREPO_RELEASE_ENTRY_PATTERN = /^(?<name>(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*)@(?<version>(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*))$/u;
+
+/** Workspace pattern that matches every direct subdirectory: `packages/*`. */
+export const WORKSPACE_WILDCARD_SUFFIX = "/*";
+
+/** Prefix of a workspace pattern that excludes directories: `!packages/internal`. */
+export const WORKSPACE_EXCLUSION_PREFIX = "!";
+
+/** Manifest fields listing dependencies; any of them links workspace packages for change detection. */
+export const DEPENDENCY_FIELDS = Object.freeze(["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]);
+
+/** Answer of the per-package version prompt that leaves the package out of this release. */
+export const SKIP_PACKAGE_CHOICE = "skip";
+
+/** Steps of a monorepo release plan (the shared ones reuse `RELEASE_STEP`). */
+export const MONOREPO_RELEASE_STEP = Object.freeze({
+  chooseVersions: "choose-versions",
+  verifyChangelogs: "verify-changelogs",
+  bumpPackages: "bump-packages",
+  pushPackages: "push-packages",
+  publishPackages: "publish-packages",
+});