@astra-kit/rp 0.0.0-stage → 0.10.0

package/src/create-version/npm-auth.js

@@ -0,0 +1,142 @@
+/**
+ * Pure explanations of the npm credential check of `astra-rp create-version`:
+ * the blocker the planner shows before anything is touched, and the error of a
+ * failed `npm publish`, whose output cannot be parsed because npm inherits the
+ * terminal (2FA). They name where `NPM_TOKEN` came from, never the token.
+ *
+ * @module create-version/npm-auth
+ */
+
+import {
+  NPM_AUTH_STATUS,
+  NPM_NOT_FOUND_CODE,
+  NPM_PUT_NOT_FOUND_NOTE,
+  NPM_READ_ONLY_TOKEN_NOTE,
+  NPM_TOKEN_LOCATIONS,
+  NPM_TOKEN_SOURCE_LABEL,
+  NPM_TOKEN_VARIABLE,
+  PROJECT_NPM_CONFIG_FILE,
+  buildNpmAuthRerunAction,
+  buildNpmPublishRetryAction,
+} from "../constants/create-version.js";
+import { DEFAULT_PROJECT_COMMANDS } from "../package-manager.js";
+
+/**
+ * @typedef {import("./npm.js").NpmAuthCheck} NpmAuthCheck
+ * @typedef {import("../package-manager.js").ProjectCommands} ProjectCommands
+ * @typedef {{ title: string, details: string[] }} NpmAuthProblem
+ */
+
+/**
+ * Names the source of the token for messages.
+ *
+ * @param {NpmAuthCheck} npmAuth - Check result.
+ * @returns {string} Source label, or a generic name when it is unknown.
+ */
+export function describeNpmTokenSource(npmAuth) {
+  return npmAuth.source ? NPM_TOKEN_SOURCE_LABEL[/** @type {keyof typeof NPM_TOKEN_SOURCE_LABEL} */ (npmAuth.source)] ?? npmAuth.source : NPM_TOKEN_VARIABLE;
+}
+
+/**
+ * Describes the owners npm reported, for the not-owner messages.
+ *
+ * @param {NpmAuthCheck} npmAuth - Check result.
+ * @returns {string} Comma-separated owners, or a placeholder when npm listed none.
+ */
+function describeOwners(npmAuth) {
+  return npmAuth.owners.length > 0 ? npmAuth.owners.join(", ") : "ninguno visible";
+}
+
+/**
+ * Builds the title and the fix of a credential problem.
+ *
+ * @param {NpmAuthCheck} npmAuth - Check result.
+ * @param {string} nextAction - What to run once fixed.
+ * @returns {{ title: string, reason: string | null, fix: string } | null} Problem, or `null` when the check does not block.
+ */
+function describeCredentialProblem(npmAuth, nextAction) {
+  const sourceLabel = describeNpmTokenSource(npmAuth);
+  const tokenVariable = npmAuth.tokenVariable ?? NPM_TOKEN_VARIABLE;
+
+  switch (npmAuth.status) {
+    case NPM_AUTH_STATUS.missingToken:
+      return { title: `Falta ${tokenVariable} para publicar ${npmAuth.packageName}`, reason: null, fix: `Definilo en ${tokenVariable === NPM_TOKEN_VARIABLE ? NPM_TOKEN_LOCATIONS : `la variable de entorno ${tokenVariable}, el .env del repo o ~/.config/astra-rp/.env`} y ${nextAction}.` };
+    case NPM_AUTH_STATUS.unsupportedAuth:
+      return { title: npmAuth.reason ?? "La autenticación configurada no está disponible", reason: null, fix: `Corregí publication.authentication o el entorno del CI y ${nextAction}.` };
+    case NPM_AUTH_STATUS.invalidToken:
+      return {
+        title: `El ${tokenVariable} (${sourceLabel}) es inválido o venció`,
+        reason: `${npmAuth.reason ?? "npm whoami rechazó el token"} (registry ${npmAuth.registryUrl}).`,
+        fix: `Generá uno nuevo con permiso de publicación (npm → Access Tokens), reemplazalo (${sourceLabel}) y ${nextAction}.`,
+      };
+    case NPM_AUTH_STATUS.notOwner:
+      return {
+        title: `El token autentica como ${npmAuth.user}, que no puede publicar ${npmAuth.packageName} (dueños: ${describeOwners(npmAuth)})`,
+        reason: `${npmAuth.reason ? `${npmAuth.reason} ` : ""}Origen del token: ${sourceLabel}.`,
+        fix: `Usá el token de un dueño o pedí que te agreguen (npm owner add ${npmAuth.user} ${npmAuth.packageName}) y ${nextAction}.`,
+      };
+    case NPM_AUTH_STATUS.projectCredentials:
+      return {
+        title: `El ${PROJECT_NPM_CONFIG_FILE} del proyecto define credenciales para ${npmAuth.registryUrl} que tienen prioridad sobre ${tokenVariable}`,
+        reason: `${npmAuth.reason ?? `${PROJECT_NPM_CONFIG_FILE} del proyecto con credenciales`}.`,
+        fix: `Sacalas: astra-rp usa ${tokenVariable} con una config temporal. Después ${nextAction}.`,
+      };
+    default:
+      return null;
+  }
+}
+
+/**
+ * Explains an npm credential check that must stop the release before anything is touched.
+ *
+ * @param {NpmAuthCheck} npmAuth - Result of `checkNpmPublishAccess`.
+ * @param {ProjectCommands} [commands] - Project commands quoted by the fix (pnpm when omitted).
+ * @returns {NpmAuthProblem | null} Blocker, or `null` when the check passed or could not decide (`unknown`).
+ */
+export function describeNpmAuthProblem(npmAuth, commands = DEFAULT_PROJECT_COMMANDS) {
+  const problem = describeCredentialProblem(npmAuth, buildNpmAuthRerunAction(commands.createVersion));
+  return problem ? { title: problem.title, details: [...(problem.reason ? [problem.reason] : []), problem.fix] } : null;
+}
+
+/**
+ * Warns about a first publication that cannot be told apart from a hidden package: `npm view` and
+ * `npm owner ls` answered E404, which is what a registry answers both for a new package and for a
+ * private package the token has no access to.
+ *
+ * @param {NpmAuthCheck} npmAuth - Result of `checkNpmPublishAccess`, confirmed against `npm view`.
+ * @returns {string | null} Warning, or `null` when the check is not a first publication.
+ */
+export function describeNpmFirstPublicationWarning(npmAuth) {
+  if (npmAuth.status !== NPM_AUTH_STATUS.ok || !npmAuth.firstPublication) {
+    return null;
+  }
+
+  return `El registry ${npmAuth.registryUrl} no muestra ${npmAuth.packageName} (npm view y npm owner ls responden ${NPM_NOT_FOUND_CODE}): se toma como primera publicación. Si ya existe como paquete privado, el token (${describeNpmTokenSource(npmAuth)}) no tiene acceso y npm publish va a fallar después de crear y pushear el commit y el tag.`;
+}
+
+/**
+ * Explains a failed `npm publish` from the credential check re-run after it: an invalid token, a
+ * user without permission on the package or, when the user can publish, the generic failure, which
+ * still names a read-only or granular token without write permission as a possible cause.
+ *
+ * @param {NpmAuthCheck} npmAuth - Result of `checkNpmPublishAccess` after the failure.
+ * @param {{ exitCode: number, version: string }} publication - npm exit code and version being published.
+ * @param {ProjectCommands} [commands] - Project commands quoted by the hint (pnpm when omitted).
+ * @returns {{ message: string, hint: string }} Spanish message and next action for `ReleaseStepError`.
+ */
+export function describeNpmPublishFailure(npmAuth, { exitCode, version }, commands = DEFAULT_PROJECT_COMMANDS) {
+  const failed = `npm publish terminó con código ${exitCode}`;
+  const retryAction = buildNpmPublishRetryAction(commands.createVersion);
+  const problem = describeCredentialProblem(npmAuth, retryAction);
+
+  if (problem) {
+    const notFoundNote = npmAuth.status === NPM_AUTH_STATUS.notOwner ? `${NPM_PUT_NOT_FOUND_NOTE} ` : "";
+    return { message: `${failed}: ${problem.title}.`, hint: `${notFoundNote}${problem.fix}` };
+  }
+
+  const credentials =
+    npmAuth.status === NPM_AUTH_STATUS.ok
+      ? `Las credenciales (${describeNpmTokenSource(npmAuth)}) autentican como ${npmAuth.user}${npmAuth.firstPublication ? "" : `, dueño de ${npmAuth.packageName}`}. ${NPM_READ_ONLY_TOKEN_NOTE}`
+      : `No se pudieron verificar las credenciales (${npmAuth.reason ?? "motivo desconocido"}).`;
+  return { message: `${failed}.`, hint: `Comprobá en npm si ${version} llegó; si no, ${retryAction}. ${credentials} ${NPM_PUT_NOT_FOUND_NOTE}` };
+}