@astra-kit/rp 0.0.0-stage → 0.10.0

package/src/create-version/ci-config.js

@@ -0,0 +1,54 @@
+/**
+ * Validates repository-owned CI release settings.
+ * @module create-version/ci-config
+ */
+
+import { CI_ENVIRONMENT_NAME_PATTERN, CI_RESERVED_ENVIRONMENT_NAMES, CI_VERCEL_DEPLOYMENT, CI_WORKFLOW_DIRECTORY, CI_WORKFLOW_NAME_PATTERN } from "../constants/ci-release.js";
+
+/**
+ * @typedef {{ workflow: string, secrets?: string[], variables?: string[], deployment?: "vercel" | null }} CiReleaseConfig
+ * @typedef {{ workflow: string, secrets: string[], variables: string[], deployment: "vercel" | null }} ResolvedCiReleaseConfig
+ */
+
+/**
+ * Builds the root-relative path of a workflow file.
+ * @param {string} workflow - Validated workflow filename.
+ * @returns {string} Path under {@link CI_WORKFLOW_DIRECTORY}.
+ */
+export function ciWorkflowPath(workflow) {
+  return `${CI_WORKFLOW_DIRECTORY}/${workflow}`;
+}
+
+/**
+ * Resolves a workflow basename and explicit environment bindings.
+ * @param {unknown} raw - Repository-owned configuration, or null to disable CI releases.
+ * @returns {ResolvedCiReleaseConfig | null} Validated configuration.
+ * @throws {Error} When the workflow path or environment names are invalid.
+ */
+export function resolveCiReleaseConfig(raw) {
+  if (raw === undefined || raw === null) return null;
+  if (typeof raw !== "object" || Array.isArray(raw)) throw new Error("astra-rp create-version: ci debe ser un objeto con workflow.");
+  const config = /** @type {Record<string, unknown>} */ (raw);
+  const workflow = typeof config.workflow === "string" ? config.workflow.replace(`${CI_WORKFLOW_DIRECTORY}/`, "") : "";
+  if (!CI_WORKFLOW_NAME_PATTERN.test(workflow)) throw new Error("astra-rp create-version: ci.workflow debe ser un nombre de archivo .yml o .yaml dentro de .github/workflows.");
+  const secrets = resolveEnvironmentNames(config.secrets, "secrets");
+  const variables = resolveEnvironmentNames(config.variables, "variables");
+  if (secrets.some((name) => variables.includes(name))) throw new Error("astra-rp create-version: ci.secrets y ci.variables no pueden definir la misma variable.");
+  if (config.deployment !== undefined && config.deployment !== null && config.deployment !== CI_VERCEL_DEPLOYMENT) throw new Error("astra-rp create-version: ci.deployment debe ser vercel o null.");
+  return { workflow, secrets, variables, deployment: config.deployment === CI_VERCEL_DEPLOYMENT ? CI_VERCEL_DEPLOYMENT : null };
+}
+
+/**
+ * Validates names before they become YAML environment bindings.
+ * @param {unknown} value - Explicit secret or variable names.
+ * @param {string} field - Configuration field for the diagnostic.
+ * @returns {string[]} Unique environment names.
+ * @throws {Error} When a list contains an unsafe or repeated name.
+ */
+function resolveEnvironmentNames(value, field) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || Array.from(value).some((name) => typeof name !== "string" || !CI_ENVIRONMENT_NAME_PATTERN.test(name) || CI_RESERVED_ENVIRONMENT_NAMES.includes(name)) || new Set(value).size !== value.length) {
+    throw new Error(`astra-rp create-version: ci.${field} debe ser una lista de nombres de variables únicos (por ejemplo DATABASE_MIGRATION_URL).`);
+  }
+  return /** @type {string[]} */ (value);
+}

package/src/create-version/ci-publication-history.js

@@ -0,0 +1,113 @@
+/**
+ * Reads the worker's own GitHub Actions history to prove that a custom publisher already finished,
+ * so neither a retry that only needs to deploy nor a duplicate dispatch queued behind the release's
+ * concurrency group runs a non-idempotent publication again.
+ * A registry publication is proven by the registry itself; a custom `publish` function leaves no
+ * such record, and the successful release step of an earlier run or attempt is the durable one.
+ * @module create-version/ci-publication-history
+ */
+
+import {
+  CI_ACTIONS_HISTORY_ENVIRONMENT, CI_ACTIONS_HISTORY_PAGE_SIZE, CI_ACTIONS_HISTORY_TIMEOUT_MS, CI_DEFAULT_GITHUB_API_URL,
+  CI_GITHUB_API_VERSION, CI_RELEASE_WORKER_STEP_NAME, CI_STEP_SUCCESS_CONCLUSION,
+} from "../constants/ci-release.js";
+import { CREATE_VERSION_FLAG } from "../constants/create-version.js";
+import { ReleaseStepError } from "./errors.js";
+import { formatCiReleaseRunTitle } from "./github-workflow.js";
+
+/**
+ * @typedef {{ id: number, display_title: string, run_attempt: number, html_url: string }} ActionsWorkflowRun
+ * @typedef {{ steps?: { name: string, conclusion: string | null }[] }} ActionsJob
+ * @typedef {{ url: string, attempt: number }} CompletedCiPublication
+ */
+
+/**
+ * Tells whether the worker must prove from its Actions history that the publication already
+ * finished: a custom publisher leaves no registry record, and both a retry after a failed deployment
+ * and two concurrent `--retry-ci` dispatches (queued, not cancelled, by the workflow's concurrency
+ * group) reach the worker again for the same release, with or without a deployment.
+ * @param {import("./config.js").ResolvedCreateVersionConfig} config - Project configuration.
+ * @returns {boolean} True when `publish` is a function.
+ */
+export function requiresCiPublicationHistory(config) {
+  return typeof config.publish === "function";
+}
+
+/**
+ * Builds the recovery hint shared by every history failure: nothing was published.
+ * @param {string} workflow - Configured workflow filename.
+ * @returns {string} Actionable hint.
+ */
+function describeHistoryRecovery(workflow) {
+  return `Dale al job de ${workflow} permissions "actions: read" y GITHUB_TOKEN: \${{ github.token }} (regeneralo con --${CREATE_VERSION_FLAG.setupCi} después de borrarlo en un commit propio) y reintentá con --${CREATE_VERSION_FLAG.retryCi}; el publisher personalizado no se ejecutó.`;
+}
+
+/**
+ * Requests one Actions REST resource of the worker's repository.
+ * @param {{ apiUrl: string, repository: string, token: string, workflow: string }} connection - Validated Actions access.
+ * @param {string} resourcePath - Path below `repos/{owner}/{repo}/actions/`, with its query.
+ * @returns {Promise<any>} Parsed JSON body.
+ * @throws {ReleaseStepError} When the request fails, times out or answers a non-success status.
+ */
+async function requestActionsResource(connection, resourcePath) {
+  const requestPath = `/repos/${connection.repository}/actions/${resourcePath}`;
+  let response;
+  try {
+    response = await fetch(`${connection.apiUrl}${requestPath}`, {
+      headers: { Accept: "application/vnd.github+json", Authorization: `Bearer ${connection.token}`, "X-GitHub-Api-Version": CI_GITHUB_API_VERSION },
+      signal: AbortSignal.timeout(CI_ACTIONS_HISTORY_TIMEOUT_MS),
+    });
+  } catch (error) {
+    throw new ReleaseStepError(`ci-publication-history:requestActionsResource failed: no se pudo consultar GET ${requestPath} para saber si el publisher personalizado ya terminó en otra ejecución.`, describeHistoryRecovery(connection.workflow), { cause: error });
+  }
+  if (!response.ok) {
+    throw new ReleaseStepError(`ci-publication-history:requestActionsResource failed: GET ${requestPath} respondió ${response.status} (x-github-request-id ${response.headers.get("x-github-request-id") ?? "ausente"}); no se puede saber si el publisher personalizado ya terminó en otra ejecución.`, describeHistoryRecovery(connection.workflow));
+  }
+  return response.json();
+}
+
+/**
+ * Tells whether a run attempt is the one executing this worker. GitHub lists the running attempt too;
+ * its release step has not succeeded yet, but it is skipped explicitly so only other attempts count.
+ * @param {ActionsWorkflowRun} run - Listed workflow run.
+ * @param {number} attempt - Attempt number of that run.
+ * @param {NodeJS.ProcessEnv} environment - Worker environment providing the current run id and attempt.
+ * @returns {boolean} True for the current run attempt.
+ */
+function isCurrentRunAttempt(run, attempt, environment) {
+  return String(run.id) === environment[CI_ACTIONS_HISTORY_ENVIRONMENT.runId] && String(attempt) === environment[CI_ACTIONS_HISTORY_ENVIRONMENT.runAttempt];
+}
+
+/**
+ * Finds another run or attempt of this exact release whose release step succeeded, which means its
+ * custom publisher already finished. Only successful release steps count: a duplicate dispatch queued
+ * behind the release's concurrency group starts after the first run ends, so it sees that success.
+ * The current run attempt (`GITHUB_RUN_ID`/`GITHUB_RUN_ATTEMPT`) never counts.
+ * Fails closed: when the history cannot be read, the worker stops before publishing.
+ * @param {string} workflow - Configured workflow filename that dispatches the release.
+ * @param {import("./github-workflow.js").CiReleaseIdentity} release - Verified release identity.
+ * @param {NodeJS.ProcessEnv} [environment] - Worker environment providing the Actions API, repository and token.
+ * @returns {Promise<CompletedCiPublication | null>} Another successful run attempt, or null when publication never finished.
+ * @throws {ReleaseStepError} When the Actions history is unavailable or unreadable.
+ */
+export async function findCompletedCiPublication(workflow, release, environment = process.env) {
+  const repository = environment[CI_ACTIONS_HISTORY_ENVIRONMENT.repository];
+  const token = environment[CI_ACTIONS_HISTORY_ENVIRONMENT.token];
+  if (!repository || !token) {
+    const missing = [CI_ACTIONS_HISTORY_ENVIRONMENT.repository, CI_ACTIONS_HISTORY_ENVIRONMENT.token].filter((name) => !environment[name]);
+    throw new ReleaseStepError(`ci-publication-history:findCompletedCiPublication failed: faltan ${missing.join(" y ")} para comprobar en Actions si el publisher personalizado de ${release.tag} ya terminó en otra ejecución.`, describeHistoryRecovery(workflow));
+  }
+  const connection = { apiUrl: (environment[CI_ACTIONS_HISTORY_ENVIRONMENT.apiUrl] || CI_DEFAULT_GITHUB_API_URL).replace(/\/+$/u, ""), repository, token, workflow };
+  const runTitle = formatCiReleaseRunTitle(release);
+  const listed = await requestActionsResource(connection, `workflows/${encodeURIComponent(workflow)}/runs?event=workflow_dispatch&head_sha=${release.sha}&per_page=${CI_ACTIONS_HISTORY_PAGE_SIZE}`);
+  const releaseRuns = /** @type {ActionsWorkflowRun[]} */ (listed.workflow_runs ?? []).filter((run) => run.display_title === runTitle);
+  for (const run of releaseRuns) {
+    for (let attempt = 1; attempt <= run.run_attempt; attempt += 1) {
+      if (isCurrentRunAttempt(run, attempt, environment)) continue;
+      const attemptJobs = await requestActionsResource(connection, `runs/${run.id}/attempts/${attempt}/jobs?per_page=${CI_ACTIONS_HISTORY_PAGE_SIZE}`);
+      const published = /** @type {ActionsJob[]} */ (attemptJobs.jobs ?? []).some((job) => (job.steps ?? []).some((step) => step.name === CI_RELEASE_WORKER_STEP_NAME && step.conclusion === CI_STEP_SUCCESS_CONCLUSION));
+      if (published) return { url: run.html_url, attempt };
+    }
+  }
+  return null;
+}

package/src/create-version/ci-release-identity-step.js

@@ -0,0 +1,58 @@
+/**
+ * Renders the dependency-free workflow step that authenticates a dispatched release before any
+ * project-controlled code (package installation, lifecycle scripts, hooks) runs with the job's
+ * publication secrets and OIDC permission.
+ * @module create-version/ci-release-identity-step
+ */
+
+import { CI_COMMIT_SHA_PATTERN, CI_RELEASE_ENVIRONMENT, CI_RELEASE_IDENTITY_STEP_NAME, CI_RELEASE_TAG_ENVIRONMENT, CI_RELEASE_VERSION_SHELL_PATTERN } from "../constants/ci-release.js";
+import { MAIN_BRANCH, RELEASE_REMOTE } from "../constants/create-version.js";
+import { RELEASE_TAG_PREFIX } from "../constants/versions.js";
+
+/** Indentation of a `run: |` body inside a generated job step. */
+const STEP_SCRIPT_INDENT = "          ";
+
+/**
+ * Builds the Bash script that mirrors the identity rules of `readCiReleaseIdentity` using only Git:
+ * the tag must be the stable tag of the dispatched version, resolve exactly to the dispatched commit
+ * (which must also be the checked-out HEAD), and that commit must already be in `origin/main`.
+ * Raw inputs are never echoed before their format is validated, so they cannot inject workflow commands.
+ * @returns {string[]} Script lines without indentation.
+ */
+function buildIdentityScript() {
+  const tag = `$${CI_RELEASE_TAG_ENVIRONMENT}`;
+  const version = `$${CI_RELEASE_ENVIRONMENT.version}`;
+  const sha = `$${CI_RELEASE_ENVIRONMENT.sha}`;
+  const mainRef = `refs/remotes/${RELEASE_REMOTE}/${MAIN_BRANCH}`;
+  return [
+    "set -euo pipefail",
+    'fail() { echo "::error title=Release no autorizado::$1"; exit 1; }',
+    `version_pattern='${CI_RELEASE_VERSION_SHELL_PATTERN}'`,
+    `sha_pattern='${CI_COMMIT_SHA_PATTERN.source}'`,
+    `[[ "${version}" =~ $version_pattern ]] || fail "El input version no es una versión estable X.Y.Z; no se instaló nada."`,
+    `[[ "${tag}" == "${RELEASE_TAG_PREFIX}${version}" ]] || fail "El input tag no es el tag de release ${RELEASE_TAG_PREFIX}${version}; no se instaló nada."`,
+    `[[ "${sha}" =~ $sha_pattern ]] || fail "El input sha no es un commit completo; no se instaló nada."`,
+    `git fetch --no-tags --quiet ${RELEASE_REMOTE} "+refs/heads/${MAIN_BRANCH}:${mainRef}" || fail "No se pudo traer ${RELEASE_REMOTE}/${MAIN_BRANCH} para verificar ${tag}."`,
+    `tag_sha="$(git rev-parse --verify --quiet "refs/tags/${tag}^{commit}")" || fail "${tag} no existe como tag en ${RELEASE_REMOTE}."`,
+    `[[ "$tag_sha" == "${sha}" ]] || fail "${tag} apunta a $tag_sha, no al commit ${sha} enviado."`,
+    `[[ "$(git rev-parse HEAD)" == "${sha}" ]] || fail "El checkout no está en el commit ${sha} de ${tag}."`,
+    `git merge-base --is-ancestor "${sha}" "${mainRef}" || fail "El commit ${sha} de ${tag} no está en ${RELEASE_REMOTE}/${MAIN_BRANCH}."`,
+  ];
+}
+
+/**
+ * Renders the identity step placed right after checkout and before any toolchain or dependency setup.
+ * Inputs reach the script only through step environment variables, never through `${{ }}` interpolation.
+ * @returns {string} Workflow YAML for one step, indented for the release job.
+ */
+export function renderCiReleaseIdentityStep() {
+  return [
+    `      - name: ${CI_RELEASE_IDENTITY_STEP_NAME}`,
+    "        env:",
+    `          ${CI_RELEASE_ENVIRONMENT.version}: \${{ inputs.version }}`,
+    `          ${CI_RELEASE_ENVIRONMENT.sha}: \${{ inputs.sha }}`,
+    `          ${CI_RELEASE_TAG_ENVIRONMENT}: \${{ inputs.tag }}`,
+    "        run: |",
+    ...buildIdentityScript().map((line) => `${STEP_SCRIPT_INDENT}${line}`),
+  ].join("\n");
+}